]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | // -*- mode:C++; tab-width:8; c-basic-offset:2; indent-tabs-mode:t -*- |
2 | // vim: ts=8 sw=2 smarttab | |
3 | /* | |
4 | * Ceph - scalable distributed file system | |
5 | * | |
6 | * Copyright (C) 2004-2012 Sage Weil <sage@newdream.net> | |
7 | * | |
8 | * This is free software; you can redistribute it and/or | |
9 | * modify it under the terms of the GNU Lesser General Public | |
10 | * License version 2.1, as published by the Free Software | |
11 | * Foundation. See file COPYING. | |
12 | * | |
13 | */ | |
14 | ||
15 | #ifndef CEPH_LIBRADOS_H | |
16 | #define CEPH_LIBRADOS_H | |
17 | ||
18 | #ifdef __cplusplus | |
19 | extern "C" { | |
20 | #endif | |
21 | ||
22 | #include <netinet/in.h> | |
23 | #if defined(__linux__) | |
24 | #include <linux/types.h> | |
25 | #elif defined(__FreeBSD__) | |
26 | #include <sys/types.h> | |
27 | #endif | |
28 | #include <unistd.h> | |
29 | #include <string.h> | |
30 | #include "rados_types.h" | |
31 | ||
32 | #include <sys/time.h> | |
33 | ||
34 | #ifndef CEPH_OSD_TMAP_SET | |
35 | /* These are also defined in rados.h and objclass.h. Keep them in sync! */ | |
36 | #define CEPH_OSD_TMAP_HDR 'h' | |
37 | #define CEPH_OSD_TMAP_SET 's' | |
38 | #define CEPH_OSD_TMAP_CREATE 'c' | |
39 | #define CEPH_OSD_TMAP_RM 'r' | |
40 | #endif | |
41 | ||
11fdf7f2 TL |
42 | #define LIBRADOS_VER_MAJOR 3 |
43 | #define LIBRADOS_VER_MINOR 0 | |
44 | #define LIBRADOS_VER_EXTRA 0 | |
7c673cae FG |
45 | |
46 | #define LIBRADOS_VERSION(maj, min, extra) ((maj << 16) + (min << 8) + extra) | |
47 | ||
48 | #define LIBRADOS_VERSION_CODE LIBRADOS_VERSION(LIBRADOS_VER_MAJOR, LIBRADOS_VER_MINOR, LIBRADOS_VER_EXTRA) | |
49 | ||
50 | #define LIBRADOS_SUPPORTS_WATCH 1 | |
c07f9fc5 | 51 | #define LIBRADOS_SUPPORTS_SERVICES 1 |
f6b5b4d7 | 52 | #define LIBRADOS_SUPPORTS_GETADDRS 1 |
11fdf7f2 | 53 | #define LIBRADOS_SUPPORTS_APP_METADATA 1 |
7c673cae FG |
54 | |
55 | /* RADOS lock flags | |
56 | * They are also defined in cls_lock_types.h. Keep them in sync! | |
57 | */ | |
f67539c2 TL |
58 | #define LIBRADOS_LOCK_FLAG_RENEW (1u<<0) |
59 | #define LIBRADOS_LOCK_FLAG_MAY_RENEW LIBRADOS_LOCK_FLAG_RENEW | |
60 | #define LIBRADOS_LOCK_FLAG_MUST_RENEW (1u<<1) | |
7c673cae FG |
61 | |
62 | /* | |
63 | * Constants for rados_write_op_create(). | |
64 | */ | |
65 | #define LIBRADOS_CREATE_EXCLUSIVE 1 | |
66 | #define LIBRADOS_CREATE_IDEMPOTENT 0 | |
67 | ||
68 | /* | |
69 | * Flags that can be set on a per-op basis via | |
70 | * rados_read_op_set_flags() and rados_write_op_set_flags(). | |
71 | */ | |
72 | enum { | |
73 | // fail a create operation if the object already exists | |
74 | LIBRADOS_OP_FLAG_EXCL = 0x1, | |
75 | // allow the transaction to succeed even if the flagged op fails | |
76 | LIBRADOS_OP_FLAG_FAILOK = 0x2, | |
77 | // indicate read/write op random | |
78 | LIBRADOS_OP_FLAG_FADVISE_RANDOM = 0x4, | |
79 | // indicate read/write op sequential | |
80 | LIBRADOS_OP_FLAG_FADVISE_SEQUENTIAL = 0x8, | |
81 | // indicate read/write data will be accessed in the near future (by someone) | |
82 | LIBRADOS_OP_FLAG_FADVISE_WILLNEED = 0x10, | |
83 | // indicate read/write data will not accessed in the near future (by anyone) | |
84 | LIBRADOS_OP_FLAG_FADVISE_DONTNEED = 0x20, | |
85 | // indicate read/write data will not accessed again (by *this* client) | |
86 | LIBRADOS_OP_FLAG_FADVISE_NOCACHE = 0x40, | |
11fdf7f2 TL |
87 | // optionally support FUA (force unit access) on write requests |
88 | LIBRADOS_OP_FLAG_FADVISE_FUA = 0x80, | |
7c673cae FG |
89 | }; |
90 | ||
11fdf7f2 | 91 | #define CEPH_RADOS_API |
7c673cae FG |
92 | |
93 | /** | |
94 | * @name xattr comparison operations | |
95 | * Operators for comparing xattrs on objects, and aborting the | |
96 | * rados_read_op or rados_write_op transaction if the comparison | |
97 | * fails. | |
98 | * | |
99 | * @{ | |
100 | */ | |
101 | enum { | |
102 | LIBRADOS_CMPXATTR_OP_EQ = 1, | |
103 | LIBRADOS_CMPXATTR_OP_NE = 2, | |
104 | LIBRADOS_CMPXATTR_OP_GT = 3, | |
105 | LIBRADOS_CMPXATTR_OP_GTE = 4, | |
106 | LIBRADOS_CMPXATTR_OP_LT = 5, | |
107 | LIBRADOS_CMPXATTR_OP_LTE = 6 | |
108 | }; | |
109 | /** @} */ | |
110 | ||
111 | /** | |
112 | * @name Operation Flags | |
11fdf7f2 | 113 | * Flags for rados_read_op_operate(), rados_write_op_operate(), |
7c673cae FG |
114 | * rados_aio_read_op_operate(), and rados_aio_write_op_operate(). |
115 | * See librados.hpp for details. | |
116 | * @{ | |
117 | */ | |
118 | enum { | |
119 | LIBRADOS_OPERATION_NOFLAG = 0, | |
120 | LIBRADOS_OPERATION_BALANCE_READS = 1, | |
121 | LIBRADOS_OPERATION_LOCALIZE_READS = 2, | |
122 | LIBRADOS_OPERATION_ORDER_READS_WRITES = 4, | |
123 | LIBRADOS_OPERATION_IGNORE_CACHE = 8, | |
124 | LIBRADOS_OPERATION_SKIPRWLOCKS = 16, | |
125 | LIBRADOS_OPERATION_IGNORE_OVERLAY = 32, | |
126 | /* send requests to cluster despite the cluster or pool being marked | |
127 | full; ops will either succeed (e.g., delete) or return EDQUOT or | |
128 | ENOSPC. */ | |
129 | LIBRADOS_OPERATION_FULL_TRY = 64, | |
130 | /* | |
131 | * Mainly for delete op | |
132 | */ | |
133 | LIBRADOS_OPERATION_FULL_FORCE = 128, | |
31f18b77 | 134 | LIBRADOS_OPERATION_IGNORE_REDIRECT = 256, |
11fdf7f2 | 135 | LIBRADOS_OPERATION_ORDERSNAP = 512, |
9f95a23c TL |
136 | /* enable/allow >0 return values and payloads on write/update */ |
137 | LIBRADOS_OPERATION_RETURNVEC = 1024, | |
7c673cae FG |
138 | }; |
139 | /** @} */ | |
140 | ||
141 | /** | |
142 | * @name Alloc hint flags | |
143 | * Flags for rados_write_op_alloc_hint2() and rados_set_alloc_hint2() | |
144 | * indicating future IO patterns. | |
145 | * @{ | |
146 | */ | |
147 | enum { | |
148 | LIBRADOS_ALLOC_HINT_FLAG_SEQUENTIAL_WRITE = 1, | |
149 | LIBRADOS_ALLOC_HINT_FLAG_RANDOM_WRITE = 2, | |
150 | LIBRADOS_ALLOC_HINT_FLAG_SEQUENTIAL_READ = 4, | |
151 | LIBRADOS_ALLOC_HINT_FLAG_RANDOM_READ = 8, | |
152 | LIBRADOS_ALLOC_HINT_FLAG_APPEND_ONLY = 16, | |
153 | LIBRADOS_ALLOC_HINT_FLAG_IMMUTABLE = 32, | |
154 | LIBRADOS_ALLOC_HINT_FLAG_SHORTLIVED = 64, | |
155 | LIBRADOS_ALLOC_HINT_FLAG_LONGLIVED = 128, | |
156 | LIBRADOS_ALLOC_HINT_FLAG_COMPRESSIBLE = 256, | |
157 | LIBRADOS_ALLOC_HINT_FLAG_INCOMPRESSIBLE = 512, | |
158 | }; | |
159 | /** @} */ | |
160 | ||
161 | typedef enum { | |
162 | LIBRADOS_CHECKSUM_TYPE_XXHASH32 = 0, | |
163 | LIBRADOS_CHECKSUM_TYPE_XXHASH64 = 1, | |
164 | LIBRADOS_CHECKSUM_TYPE_CRC32C = 2 | |
165 | } rados_checksum_type_t; | |
166 | ||
167 | /* | |
168 | * snap id contants | |
169 | */ | |
20effc67 TL |
170 | #define LIBRADOS_SNAP_HEAD UINT64_C(-2) |
171 | #define LIBRADOS_SNAP_DIR UINT64_C(-1) | |
7c673cae FG |
172 | |
173 | /** | |
174 | * @typedef rados_t | |
175 | * | |
176 | * A handle for interacting with a RADOS cluster. It encapsulates all | |
177 | * RADOS client configuration, including username, key for | |
f67539c2 | 178 | * authentication, logging, and debugging. Talking to different clusters |
7c673cae FG |
179 | * -- or to the same cluster with different users -- requires |
180 | * different cluster handles. | |
181 | */ | |
182 | #ifndef VOIDPTR_RADOS_T | |
183 | #define VOIDPTR_RADOS_T | |
184 | typedef void *rados_t; | |
185 | #endif //VOIDPTR_RADOS_T | |
186 | ||
187 | /** | |
188 | * @typedef rados_config_t | |
189 | * | |
190 | * A handle for the ceph configuration context for the rados_t cluster | |
191 | * instance. This can be used to share configuration context/state | |
192 | * (e.g., logging configuration) between librados instance. | |
193 | * | |
194 | * @warning The config context does not have independent reference | |
195 | * counting. As such, a rados_config_t handle retrieved from a given | |
196 | * rados_t is only valid as long as that rados_t. | |
197 | */ | |
198 | typedef void *rados_config_t; | |
199 | ||
200 | /** | |
201 | * @typedef rados_ioctx_t | |
202 | * | |
203 | * An io context encapsulates a few settings for all I/O operations | |
204 | * done on it: | |
205 | * - pool - set when the io context is created (see rados_ioctx_create()) | |
206 | * - snapshot context for writes (see | |
207 | * rados_ioctx_selfmanaged_snap_set_write_ctx()) | |
208 | * - snapshot id to read from (see rados_ioctx_snap_set_read()) | |
209 | * - object locator for all single-object operations (see | |
210 | * rados_ioctx_locator_set_key()) | |
211 | * - namespace for all single-object operations (see | |
212 | * rados_ioctx_set_namespace()). Set to LIBRADOS_ALL_NSPACES | |
213 | * before rados_nobjects_list_open() will list all objects in all | |
214 | * namespaces. | |
215 | * | |
216 | * @warning Changing any of these settings is not thread-safe - | |
217 | * librados users must synchronize any of these changes on their own, | |
218 | * or use separate io contexts for each thread | |
219 | */ | |
220 | typedef void *rados_ioctx_t; | |
221 | ||
222 | /** | |
223 | * @typedef rados_list_ctx_t | |
224 | * | |
225 | * An iterator for listing the objects in a pool. | |
226 | * Used with rados_nobjects_list_open(), | |
f67539c2 | 227 | * rados_nobjects_list_next(), rados_nobjects_list_next2(), and |
7c673cae FG |
228 | * rados_nobjects_list_close(). |
229 | */ | |
230 | typedef void *rados_list_ctx_t; | |
231 | ||
232 | /** | |
233 | * @typedef rados_object_list_cursor | |
234 | * | |
235 | * The cursor used with rados_enumerate_objects | |
236 | * and accompanying methods. | |
237 | */ | |
238 | typedef void * rados_object_list_cursor; | |
239 | ||
11fdf7f2 TL |
240 | /** |
241 | * @struct rados_object_list_item | |
242 | * | |
243 | * The item populated by rados_object_list in | |
244 | * the results array. | |
245 | */ | |
f67539c2 | 246 | typedef struct { |
11fdf7f2 TL |
247 | |
248 | /// oid length | |
7c673cae | 249 | size_t oid_length; |
11fdf7f2 | 250 | /// name of the object |
7c673cae | 251 | char *oid; |
11fdf7f2 | 252 | /// namespace length |
7c673cae | 253 | size_t nspace_length; |
11fdf7f2 | 254 | /// the object namespace |
7c673cae | 255 | char *nspace; |
11fdf7f2 | 256 | /// locator length |
7c673cae | 257 | size_t locator_length; |
11fdf7f2 | 258 | /// object locator |
7c673cae FG |
259 | char *locator; |
260 | } rados_object_list_item; | |
261 | ||
262 | /** | |
263 | * @typedef rados_snap_t | |
264 | * The id of a snapshot. | |
265 | */ | |
266 | typedef uint64_t rados_snap_t; | |
267 | ||
268 | /** | |
269 | * @typedef rados_xattrs_iter_t | |
270 | * An iterator for listing extended attrbutes on an object. | |
271 | * Used with rados_getxattrs(), rados_getxattrs_next(), and | |
272 | * rados_getxattrs_end(). | |
273 | */ | |
274 | typedef void *rados_xattrs_iter_t; | |
275 | ||
276 | /** | |
277 | * @typedef rados_omap_iter_t | |
278 | * An iterator for listing omap key/value pairs on an object. | |
279 | * Used with rados_read_op_omap_get_keys(), rados_read_op_omap_get_vals(), | |
280 | * rados_read_op_omap_get_vals_by_keys(), rados_omap_get_next(), and | |
281 | * rados_omap_get_end(). | |
282 | */ | |
283 | typedef void *rados_omap_iter_t; | |
284 | ||
285 | /** | |
286 | * @struct rados_pool_stat_t | |
287 | * Usage information for a pool. | |
288 | */ | |
289 | struct rados_pool_stat_t { | |
290 | /// space used in bytes | |
291 | uint64_t num_bytes; | |
292 | /// space used in KB | |
293 | uint64_t num_kb; | |
294 | /// number of objects in the pool | |
295 | uint64_t num_objects; | |
296 | /// number of clones of objects | |
297 | uint64_t num_object_clones; | |
298 | /// num_objects * num_replicas | |
299 | uint64_t num_object_copies; | |
11fdf7f2 | 300 | /// number of objects missing on primary |
7c673cae FG |
301 | uint64_t num_objects_missing_on_primary; |
302 | /// number of objects found on no OSDs | |
303 | uint64_t num_objects_unfound; | |
304 | /// number of objects replicated fewer times than they should be | |
305 | /// (but found on at least one OSD) | |
306 | uint64_t num_objects_degraded; | |
11fdf7f2 | 307 | /// number of objects read |
7c673cae | 308 | uint64_t num_rd; |
11fdf7f2 | 309 | /// objects read in KB |
7c673cae | 310 | uint64_t num_rd_kb; |
11fdf7f2 | 311 | /// number of objects written |
7c673cae | 312 | uint64_t num_wr; |
11fdf7f2 | 313 | /// objects written in KB |
7c673cae | 314 | uint64_t num_wr_kb; |
11fdf7f2 TL |
315 | /// bytes originally provided by user |
316 | uint64_t num_user_bytes; | |
317 | /// bytes passed compression | |
318 | uint64_t compressed_bytes_orig; | |
319 | /// bytes resulted after compression | |
320 | uint64_t compressed_bytes; | |
321 | /// bytes allocated at storage | |
322 | uint64_t compressed_bytes_alloc; | |
7c673cae FG |
323 | }; |
324 | ||
325 | /** | |
326 | * @struct rados_cluster_stat_t | |
327 | * Cluster-wide usage information | |
328 | */ | |
329 | struct rados_cluster_stat_t { | |
11fdf7f2 TL |
330 | /// total device size |
331 | uint64_t kb; | |
332 | /// total used | |
333 | uint64_t kb_used; | |
334 | /// total available/free | |
335 | uint64_t kb_avail; | |
336 | /// number of objects | |
7c673cae FG |
337 | uint64_t num_objects; |
338 | }; | |
339 | ||
340 | /** | |
341 | * @typedef rados_write_op_t | |
342 | * | |
343 | * An object write operation stores a number of operations which can be | |
344 | * executed atomically. For usage, see: | |
345 | * - Creation and deletion: rados_create_write_op() rados_release_write_op() | |
346 | * - Extended attribute manipulation: rados_write_op_cmpxattr() | |
347 | * rados_write_op_cmpxattr(), rados_write_op_setxattr(), | |
348 | * rados_write_op_rmxattr() | |
349 | * - Object map key/value pairs: rados_write_op_omap_set(), | |
350 | * rados_write_op_omap_rm_keys(), rados_write_op_omap_clear(), | |
351 | * rados_write_op_omap_cmp() | |
352 | * - Object properties: rados_write_op_assert_exists(), | |
353 | * rados_write_op_assert_version() | |
354 | * - Creating objects: rados_write_op_create() | |
355 | * - IO on objects: rados_write_op_append(), rados_write_op_write(), rados_write_op_zero | |
356 | * rados_write_op_write_full(), rados_write_op_writesame(), rados_write_op_remove, | |
357 | * rados_write_op_truncate(), rados_write_op_zero(), rados_write_op_cmpext() | |
358 | * - Hints: rados_write_op_set_alloc_hint() | |
359 | * - Performing the operation: rados_write_op_operate(), rados_aio_write_op_operate() | |
360 | */ | |
361 | typedef void *rados_write_op_t; | |
362 | ||
363 | /** | |
364 | * @typedef rados_read_op_t | |
365 | * | |
366 | * An object read operation stores a number of operations which can be | |
367 | * executed atomically. For usage, see: | |
368 | * - Creation and deletion: rados_create_read_op() rados_release_read_op() | |
369 | * - Extended attribute manipulation: rados_read_op_cmpxattr(), | |
370 | * rados_read_op_getxattr(), rados_read_op_getxattrs() | |
371 | * - Object map key/value pairs: rados_read_op_omap_get_vals(), | |
372 | * rados_read_op_omap_get_keys(), rados_read_op_omap_get_vals_by_keys(), | |
373 | * rados_read_op_omap_cmp() | |
374 | * - Object properties: rados_read_op_stat(), rados_read_op_assert_exists(), | |
375 | * rados_read_op_assert_version() | |
376 | * - IO on objects: rados_read_op_read(), rados_read_op_checksum(), | |
377 | * rados_read_op_cmpext() | |
378 | * - Custom operations: rados_read_op_exec(), rados_read_op_exec_user_buf() | |
379 | * - Request properties: rados_read_op_set_flags() | |
380 | * - Performing the operation: rados_read_op_operate(), | |
381 | * rados_aio_read_op_operate() | |
382 | */ | |
383 | typedef void *rados_read_op_t; | |
384 | ||
385 | /** | |
386 | * @typedef rados_completion_t | |
387 | * Represents the state of an asynchronous operation - it contains the | |
388 | * return value once the operation completes, and can be used to block | |
389 | * until the operation is complete or safe. | |
390 | */ | |
391 | typedef void *rados_completion_t; | |
392 | ||
393 | /** | |
394 | * @struct blkin_trace_info | |
395 | * blkin trace information for Zipkin tracing | |
396 | */ | |
397 | struct blkin_trace_info; | |
398 | ||
399 | /** | |
400 | * Get the version of librados. | |
401 | * | |
402 | * The version number is major.minor.extra. Note that this is | |
403 | * unrelated to the Ceph version number. | |
404 | * | |
405 | * TODO: define version semantics, i.e.: | |
406 | * - incrementing major is for backwards-incompatible changes | |
407 | * - incrementing minor is for backwards-compatible changes | |
408 | * - incrementing extra is for bug fixes | |
409 | * | |
410 | * @param major where to store the major version number | |
411 | * @param minor where to store the minor version number | |
412 | * @param extra where to store the extra version number | |
413 | */ | |
414 | CEPH_RADOS_API void rados_version(int *major, int *minor, int *extra); | |
415 | ||
416 | /** | |
417 | * @name Setup and Teardown | |
418 | * These are the first and last functions to that should be called | |
419 | * when using librados. | |
420 | * | |
421 | * @{ | |
422 | */ | |
423 | ||
424 | /** | |
425 | * Create a handle for communicating with a RADOS cluster. | |
426 | * | |
427 | * Ceph environment variables are read when this is called, so if | |
428 | * $CEPH_ARGS specifies everything you need to connect, no further | |
429 | * configuration is necessary. | |
430 | * | |
431 | * @param cluster where to store the handle | |
432 | * @param id the user to connect as (i.e. admin, not client.admin) | |
433 | * @returns 0 on success, negative error code on failure | |
434 | */ | |
435 | CEPH_RADOS_API int rados_create(rados_t *cluster, const char * const id); | |
436 | ||
437 | /** | |
438 | * Extended version of rados_create. | |
439 | * | |
440 | * Like rados_create, but | |
441 | * 1) don't assume 'client\.'+id; allow full specification of name | |
442 | * 2) allow specification of cluster name | |
443 | * 3) flags for future expansion | |
444 | */ | |
445 | CEPH_RADOS_API int rados_create2(rados_t *pcluster, | |
446 | const char *const clustername, | |
447 | const char * const name, uint64_t flags); | |
448 | ||
449 | /** | |
450 | * Initialize a cluster handle from an existing configuration. | |
451 | * | |
452 | * Share configuration state with another rados_t instance. | |
453 | * | |
454 | * @param cluster where to store the handle | |
455 | * @param cct the existing configuration to use | |
456 | * @returns 0 on success, negative error code on failure | |
457 | */ | |
458 | CEPH_RADOS_API int rados_create_with_context(rados_t *cluster, | |
459 | rados_config_t cct); | |
460 | ||
461 | /** | |
462 | * Ping the monitor with ID mon_id, storing the resulting reply in | |
463 | * buf (if specified) with a maximum size of len. | |
464 | * | |
465 | * The result buffer is allocated on the heap; the caller is | |
466 | * expected to release that memory with rados_buffer_free(). The | |
467 | * buffer and length pointers can be NULL, in which case they are | |
468 | * not filled in. | |
469 | * | |
f67539c2 TL |
470 | * @param cluster cluster handle |
471 | * @param mon_id [in] ID of the monitor to ping | |
472 | * @param outstr [out] double pointer with the resulting reply | |
473 | * @param outstrlen [out] pointer with the size of the reply in outstr | |
7c673cae FG |
474 | */ |
475 | CEPH_RADOS_API int rados_ping_monitor(rados_t cluster, const char *mon_id, | |
476 | char **outstr, size_t *outstrlen); | |
477 | ||
478 | /** | |
479 | * Connect to the cluster. | |
480 | * | |
481 | * @note BUG: Before calling this, calling a function that communicates with the | |
482 | * cluster will crash. | |
483 | * | |
484 | * @pre The cluster handle is configured with at least a monitor | |
485 | * address. If cephx is enabled, a client name and secret must also be | |
486 | * set. | |
487 | * | |
488 | * @post If this succeeds, any function in librados may be used | |
489 | * | |
490 | * @param cluster The cluster to connect to. | |
11fdf7f2 | 491 | * @returns 0 on success, negative error code on failure |
7c673cae FG |
492 | */ |
493 | CEPH_RADOS_API int rados_connect(rados_t cluster); | |
494 | ||
495 | /** | |
496 | * Disconnects from the cluster. | |
497 | * | |
498 | * For clean up, this is only necessary after rados_connect() has | |
499 | * succeeded. | |
500 | * | |
501 | * @warning This does not guarantee any asynchronous writes have | |
502 | * completed. To do that, you must call rados_aio_flush() on all open | |
503 | * io contexts. | |
504 | * | |
505 | * @warning We implicitly call rados_watch_flush() on shutdown. If | |
506 | * there are watches being used, this should be done explicitly before | |
507 | * destroying the relevant IoCtx. We do it here as a safety measure. | |
508 | * | |
509 | * @post the cluster handle cannot be used again | |
510 | * | |
511 | * @param cluster the cluster to shutdown | |
512 | */ | |
513 | CEPH_RADOS_API void rados_shutdown(rados_t cluster); | |
514 | ||
515 | /** @} init */ | |
516 | ||
517 | /** | |
518 | * @name Configuration | |
519 | * These functions read and update Ceph configuration for a cluster | |
520 | * handle. Any configuration changes must be done before connecting to | |
521 | * the cluster. | |
522 | * | |
523 | * Options that librados users might want to set include: | |
524 | * - mon_host | |
525 | * - auth_supported | |
526 | * - key, keyfile, or keyring when using cephx | |
527 | * - log_file, log_to_stderr, err_to_stderr, and log_to_syslog | |
528 | * - debug_rados, debug_objecter, debug_monc, debug_auth, or debug_ms | |
529 | * | |
c07f9fc5 | 530 | * See docs.ceph.com for information about available configuration options` |
7c673cae FG |
531 | * |
532 | * @{ | |
533 | */ | |
534 | ||
535 | /** | |
536 | * Configure the cluster handle using a Ceph config file | |
537 | * | |
538 | * If path is NULL, the default locations are searched, and the first | |
539 | * found is used. The locations are: | |
540 | * - $CEPH_CONF (environment variable) | |
541 | * - /etc/ceph/ceph.conf | |
542 | * - ~/.ceph/config | |
543 | * - ceph.conf (in the current working directory) | |
544 | * | |
545 | * @pre rados_connect() has not been called on the cluster handle | |
546 | * | |
547 | * @param cluster cluster handle to configure | |
548 | * @param path path to a Ceph configuration file | |
549 | * @returns 0 on success, negative error code on failure | |
550 | */ | |
551 | CEPH_RADOS_API int rados_conf_read_file(rados_t cluster, const char *path); | |
552 | ||
553 | /** | |
554 | * Configure the cluster handle with command line arguments | |
555 | * | |
556 | * argv can contain any common Ceph command line option, including any | |
557 | * configuration parameter prefixed by '--' and replacing spaces with | |
558 | * dashes or underscores. For example, the following options are equivalent: | |
559 | * - --mon-host 10.0.0.1:6789 | |
560 | * - --mon_host 10.0.0.1:6789 | |
561 | * - -m 10.0.0.1:6789 | |
562 | * | |
563 | * @pre rados_connect() has not been called on the cluster handle | |
564 | * | |
565 | * @param cluster cluster handle to configure | |
566 | * @param argc number of arguments in argv | |
567 | * @param argv arguments to parse | |
568 | * @returns 0 on success, negative error code on failure | |
569 | */ | |
570 | CEPH_RADOS_API int rados_conf_parse_argv(rados_t cluster, int argc, | |
571 | const char **argv); | |
572 | ||
573 | ||
574 | /** | |
575 | * Configure the cluster handle with command line arguments, returning | |
576 | * any remainders. Same rados_conf_parse_argv, except for extra | |
577 | * remargv argument to hold returns unrecognized arguments. | |
578 | * | |
579 | * @pre rados_connect() has not been called on the cluster handle | |
580 | * | |
581 | * @param cluster cluster handle to configure | |
582 | * @param argc number of arguments in argv | |
583 | * @param argv arguments to parse | |
584 | * @param remargv char* array for returned unrecognized arguments | |
585 | * @returns 0 on success, negative error code on failure | |
586 | */ | |
587 | CEPH_RADOS_API int rados_conf_parse_argv_remainder(rados_t cluster, int argc, | |
588 | const char **argv, | |
589 | const char **remargv); | |
590 | /** | |
591 | * Configure the cluster handle based on an environment variable | |
592 | * | |
593 | * The contents of the environment variable are parsed as if they were | |
594 | * Ceph command line options. If var is NULL, the CEPH_ARGS | |
595 | * environment variable is used. | |
596 | * | |
597 | * @pre rados_connect() has not been called on the cluster handle | |
598 | * | |
599 | * @note BUG: this is not threadsafe - it uses a static buffer | |
600 | * | |
601 | * @param cluster cluster handle to configure | |
602 | * @param var name of the environment variable to read | |
603 | * @returns 0 on success, negative error code on failure | |
604 | */ | |
605 | CEPH_RADOS_API int rados_conf_parse_env(rados_t cluster, const char *var); | |
606 | ||
607 | /** | |
608 | * Set a configuration option | |
609 | * | |
610 | * @pre rados_connect() has not been called on the cluster handle | |
611 | * | |
612 | * @param cluster cluster handle to configure | |
613 | * @param option option to set | |
614 | * @param value value of the option | |
615 | * @returns 0 on success, negative error code on failure | |
616 | * @returns -ENOENT when the option is not a Ceph configuration option | |
617 | */ | |
618 | CEPH_RADOS_API int rados_conf_set(rados_t cluster, const char *option, | |
619 | const char *value); | |
620 | ||
621 | /** | |
622 | * Get the value of a configuration option | |
623 | * | |
624 | * @param cluster configuration to read | |
625 | * @param option which option to read | |
626 | * @param buf where to write the configuration value | |
627 | * @param len the size of buf in bytes | |
628 | * @returns 0 on success, negative error code on failure | |
629 | * @returns -ENAMETOOLONG if the buffer is too short to contain the | |
630 | * requested value | |
631 | */ | |
632 | CEPH_RADOS_API int rados_conf_get(rados_t cluster, const char *option, | |
633 | char *buf, size_t len); | |
634 | ||
635 | /** @} config */ | |
636 | ||
637 | /** | |
638 | * Read usage info about the cluster | |
639 | * | |
640 | * This tells you total space, space used, space available, and number | |
641 | * of objects. These are not updated immediately when data is written, | |
642 | * they are eventually consistent. | |
643 | * | |
644 | * @param cluster cluster to query | |
645 | * @param result where to store the results | |
646 | * @returns 0 on success, negative error code on failure | |
647 | */ | |
648 | CEPH_RADOS_API int rados_cluster_stat(rados_t cluster, | |
649 | struct rados_cluster_stat_t *result); | |
650 | ||
651 | /** | |
652 | * Get the fsid of the cluster as a hexadecimal string. | |
653 | * | |
654 | * The fsid is a unique id of an entire Ceph cluster. | |
655 | * | |
656 | * @param cluster where to get the fsid | |
657 | * @param buf where to write the fsid | |
658 | * @param len the size of buf in bytes (should be 37) | |
659 | * @returns 0 on success, negative error code on failure | |
660 | * @returns -ERANGE if the buffer is too short to contain the | |
661 | * fsid | |
662 | */ | |
663 | CEPH_RADOS_API int rados_cluster_fsid(rados_t cluster, char *buf, size_t len); | |
664 | ||
665 | /** | |
666 | * Get/wait for the most recent osdmap | |
667 | * | |
668 | * @param cluster the cluster to shutdown | |
11fdf7f2 | 669 | * @returns 0 on success, negative error code on failure |
7c673cae FG |
670 | */ |
671 | CEPH_RADOS_API int rados_wait_for_latest_osdmap(rados_t cluster); | |
672 | ||
673 | /** | |
674 | * @name Pools | |
675 | * | |
676 | * RADOS pools are separate namespaces for objects. Pools may have | |
677 | * different crush rules associated with them, so they could have | |
678 | * differing replication levels or placement strategies. RADOS | |
679 | * permissions are also tied to pools - users can have different read, | |
680 | * write, and execute permissions on a per-pool basis. | |
681 | * | |
682 | * @{ | |
683 | */ | |
684 | ||
685 | /** | |
686 | * List pools | |
687 | * | |
688 | * Gets a list of pool names as NULL-terminated strings. The pool | |
689 | * names will be placed in the supplied buffer one after another. | |
690 | * After the last pool name, there will be two 0 bytes in a row. | |
691 | * | |
692 | * If len is too short to fit all the pool name entries we need, we will fill | |
693 | * as much as we can. | |
694 | * | |
695 | * Buf may be null to determine the buffer size needed to list all pools. | |
696 | * | |
697 | * @param cluster cluster handle | |
698 | * @param buf output buffer | |
699 | * @param len output buffer length | |
700 | * @returns length of the buffer we would need to list all pools | |
701 | */ | |
702 | CEPH_RADOS_API int rados_pool_list(rados_t cluster, char *buf, size_t len); | |
703 | ||
704 | /** | |
705 | * List inconsistent placement groups of the given pool | |
706 | * | |
707 | * Gets a list of inconsistent placement groups as NULL-terminated strings. | |
708 | * The placement group names will be placed in the supplied buffer one after | |
709 | * another. After the last name, there will be two 0 types in a row. | |
710 | * | |
711 | * If len is too short to fit all the placement group entries we need, we will | |
712 | * fill as much as we can. | |
713 | * | |
714 | * @param cluster cluster handle | |
715 | * @param pool pool ID | |
716 | * @param buf output buffer | |
717 | * @param len output buffer length | |
718 | * @returns length of the buffer we would need to list all pools | |
719 | */ | |
720 | CEPH_RADOS_API int rados_inconsistent_pg_list(rados_t cluster, int64_t pool, | |
721 | char *buf, size_t len); | |
722 | ||
723 | /** | |
724 | * Get a configuration handle for a rados cluster handle | |
725 | * | |
726 | * This handle is valid only as long as the cluster handle is valid. | |
727 | * | |
728 | * @param cluster cluster handle | |
729 | * @returns config handle for this cluster | |
730 | */ | |
731 | CEPH_RADOS_API rados_config_t rados_cct(rados_t cluster); | |
732 | ||
733 | /** | |
734 | * Get a global id for current instance | |
735 | * | |
736 | * This id is a unique representation of current connection to the cluster | |
737 | * | |
738 | * @param cluster cluster handle | |
739 | * @returns instance global id | |
740 | */ | |
741 | CEPH_RADOS_API uint64_t rados_get_instance_id(rados_t cluster); | |
742 | ||
11fdf7f2 TL |
743 | /** |
744 | * Gets the minimum compatible OSD version | |
745 | * | |
746 | * @param cluster cluster handle | |
f67539c2 | 747 | * @param require_osd_release [out] minimum compatible OSD version |
11fdf7f2 TL |
748 | * based upon the current features |
749 | * @returns 0 on sucess, negative error code on failure | |
750 | */ | |
751 | CEPH_RADOS_API int rados_get_min_compatible_osd(rados_t cluster, | |
752 | int8_t* require_osd_release); | |
753 | ||
754 | /** | |
755 | * Gets the minimum compatible client version | |
756 | * | |
757 | * @param cluster cluster handle | |
f67539c2 | 758 | * @param min_compat_client [out] minimum compatible client version |
11fdf7f2 | 759 | * based upon the current features |
f67539c2 | 760 | * @param require_min_compat_client [out] required minimum client version |
11fdf7f2 TL |
761 | * based upon explicit setting |
762 | * @returns 0 on success, negative error code on failure | |
763 | */ | |
764 | CEPH_RADOS_API int rados_get_min_compatible_client(rados_t cluster, | |
765 | int8_t* min_compat_client, | |
766 | int8_t* require_min_compat_client); | |
767 | ||
7c673cae FG |
768 | /** |
769 | * Create an io context | |
770 | * | |
771 | * The io context allows you to perform operations within a particular | |
772 | * pool. For more details see rados_ioctx_t. | |
773 | * | |
774 | * @param cluster which cluster the pool is in | |
775 | * @param pool_name name of the pool | |
776 | * @param ioctx where to store the io context | |
777 | * @returns 0 on success, negative error code on failure | |
778 | */ | |
779 | CEPH_RADOS_API int rados_ioctx_create(rados_t cluster, const char *pool_name, | |
780 | rados_ioctx_t *ioctx); | |
781 | CEPH_RADOS_API int rados_ioctx_create2(rados_t cluster, int64_t pool_id, | |
782 | rados_ioctx_t *ioctx); | |
783 | ||
784 | /** | |
785 | * The opposite of rados_ioctx_create | |
786 | * | |
787 | * This just tells librados that you no longer need to use the io context. | |
788 | * It may not be freed immediately if there are pending asynchronous | |
789 | * requests on it, but you should not use an io context again after | |
790 | * calling this function on it. | |
791 | * | |
792 | * @warning This does not guarantee any asynchronous | |
793 | * writes have completed. You must call rados_aio_flush() | |
794 | * on the io context before destroying it to do that. | |
795 | * | |
796 | * @warning If this ioctx is used by rados_watch, the caller needs to | |
797 | * be sure that all registered watches are disconnected via | |
798 | * rados_unwatch() and that rados_watch_flush() is called. This | |
799 | * ensures that a racing watch callback does not make use of a | |
800 | * destroyed ioctx. | |
801 | * | |
802 | * @param io the io context to dispose of | |
803 | */ | |
804 | CEPH_RADOS_API void rados_ioctx_destroy(rados_ioctx_t io); | |
805 | ||
806 | /** | |
31f18b77 | 807 | * Get configuration handle for a pool handle |
7c673cae FG |
808 | * |
809 | * @param io pool handle | |
810 | * @returns rados_config_t for this cluster | |
811 | */ | |
812 | CEPH_RADOS_API rados_config_t rados_ioctx_cct(rados_ioctx_t io); | |
813 | ||
814 | /** | |
815 | * Get the cluster handle used by this rados_ioctx_t | |
816 | * Note that this is a weak reference, and should not | |
817 | * be destroyed via rados_shutdown(). | |
818 | * | |
819 | * @param io the io context | |
820 | * @returns the cluster handle for this io context | |
821 | */ | |
822 | CEPH_RADOS_API rados_t rados_ioctx_get_cluster(rados_ioctx_t io); | |
823 | ||
824 | /** | |
825 | * Get pool usage statistics | |
826 | * | |
827 | * Fills in a rados_pool_stat_t after querying the cluster. | |
828 | * | |
829 | * @param io determines which pool to query | |
830 | * @param stats where to store the results | |
831 | * @returns 0 on success, negative error code on failure | |
832 | */ | |
833 | CEPH_RADOS_API int rados_ioctx_pool_stat(rados_ioctx_t io, | |
834 | struct rados_pool_stat_t *stats); | |
835 | ||
836 | /** | |
837 | * Get the id of a pool | |
838 | * | |
839 | * @param cluster which cluster the pool is in | |
840 | * @param pool_name which pool to look up | |
841 | * @returns id of the pool | |
842 | * @returns -ENOENT if the pool is not found | |
843 | */ | |
844 | CEPH_RADOS_API int64_t rados_pool_lookup(rados_t cluster, | |
845 | const char *pool_name); | |
846 | ||
847 | /** | |
848 | * Get the name of a pool | |
849 | * | |
850 | * @param cluster which cluster the pool is in | |
851 | * @param id the id of the pool | |
852 | * @param buf where to store the pool name | |
853 | * @param maxlen size of buffer where name will be stored | |
854 | * @returns length of string stored, or -ERANGE if buffer too small | |
855 | */ | |
856 | CEPH_RADOS_API int rados_pool_reverse_lookup(rados_t cluster, int64_t id, | |
857 | char *buf, size_t maxlen); | |
858 | ||
859 | /** | |
860 | * Create a pool with default settings | |
861 | * | |
7c673cae FG |
862 | * The default crush rule is rule 0. |
863 | * | |
864 | * @param cluster the cluster in which the pool will be created | |
865 | * @param pool_name the name of the new pool | |
866 | * @returns 0 on success, negative error code on failure | |
867 | */ | |
868 | CEPH_RADOS_API int rados_pool_create(rados_t cluster, const char *pool_name); | |
869 | ||
870 | /** | |
11fdf7f2 | 871 | * Create a pool owned by a specific auid. |
7c673cae | 872 | * |
11fdf7f2 TL |
873 | * DEPRECATED: auid support has been removed, and this call will be removed in a future |
874 | * release. | |
7c673cae FG |
875 | * |
876 | * @param cluster the cluster in which the pool will be created | |
877 | * @param pool_name the name of the new pool | |
878 | * @param auid the id of the owner of the new pool | |
879 | * @returns 0 on success, negative error code on failure | |
880 | */ | |
881 | CEPH_RADOS_API int rados_pool_create_with_auid(rados_t cluster, | |
882 | const char *pool_name, | |
11fdf7f2 TL |
883 | uint64_t auid) |
884 | __attribute__((deprecated)); | |
7c673cae FG |
885 | |
886 | /** | |
887 | * Create a pool with a specific CRUSH rule | |
888 | * | |
889 | * @param cluster the cluster in which the pool will be created | |
890 | * @param pool_name the name of the new pool | |
891 | * @param crush_rule_num which rule to use for placement in the new pool1 | |
892 | * @returns 0 on success, negative error code on failure | |
893 | */ | |
894 | CEPH_RADOS_API int rados_pool_create_with_crush_rule(rados_t cluster, | |
895 | const char *pool_name, | |
896 | uint8_t crush_rule_num); | |
897 | ||
898 | /** | |
899 | * Create a pool with a specific CRUSH rule and auid | |
900 | * | |
11fdf7f2 TL |
901 | * DEPRECATED: auid support has been removed and this call will be removed |
902 | * in a future release. | |
903 | * | |
7c673cae FG |
904 | * This is a combination of rados_pool_create_with_crush_rule() and |
905 | * rados_pool_create_with_auid(). | |
906 | * | |
907 | * @param cluster the cluster in which the pool will be created | |
908 | * @param pool_name the name of the new pool | |
909 | * @param crush_rule_num which rule to use for placement in the new pool2 | |
910 | * @param auid the id of the owner of the new pool | |
911 | * @returns 0 on success, negative error code on failure | |
912 | */ | |
913 | CEPH_RADOS_API int rados_pool_create_with_all(rados_t cluster, | |
914 | const char *pool_name, | |
915 | uint64_t auid, | |
11fdf7f2 TL |
916 | uint8_t crush_rule_num) |
917 | __attribute__((deprecated)); | |
7c673cae FG |
918 | |
919 | /** | |
920 | * Returns the pool that is the base tier for this pool. | |
921 | * | |
922 | * The return value is the ID of the pool that should be used to read from/write to. | |
923 | * If tiering is not set up for the pool, returns \c pool. | |
924 | * | |
925 | * @param cluster the cluster the pool is in | |
926 | * @param pool ID of the pool to query | |
f67539c2 | 927 | * @param base_tier [out] base tier, or \c pool if tiering is not configured |
7c673cae FG |
928 | * @returns 0 on success, negative error code on failure |
929 | */ | |
930 | CEPH_RADOS_API int rados_pool_get_base_tier(rados_t cluster, int64_t pool, | |
931 | int64_t* base_tier); | |
932 | ||
933 | /** | |
934 | * Delete a pool and all data inside it | |
935 | * | |
936 | * The pool is removed from the cluster immediately, | |
937 | * but the actual data is deleted in the background. | |
938 | * | |
939 | * @param cluster the cluster the pool is in | |
940 | * @param pool_name which pool to delete | |
941 | * @returns 0 on success, negative error code on failure | |
942 | */ | |
943 | CEPH_RADOS_API int rados_pool_delete(rados_t cluster, const char *pool_name); | |
944 | ||
945 | /** | |
946 | * Attempt to change an io context's associated auid "owner" | |
947 | * | |
11fdf7f2 TL |
948 | * DEPRECATED: auid support has been removed and this call has no effect. |
949 | * | |
7c673cae FG |
950 | * Requires that you have write permission on both the current and new |
951 | * auid. | |
952 | * | |
953 | * @param io reference to the pool to change. | |
954 | * @param auid the auid you wish the io to have. | |
955 | * @returns 0 on success, negative error code on failure | |
956 | */ | |
11fdf7f2 TL |
957 | CEPH_RADOS_API int rados_ioctx_pool_set_auid(rados_ioctx_t io, uint64_t auid) |
958 | __attribute__((deprecated)); | |
959 | ||
7c673cae FG |
960 | |
961 | /** | |
962 | * Get the auid of a pool | |
963 | * | |
11fdf7f2 TL |
964 | * DEPRECATED: auid support has been removed and this call always reports |
965 | * CEPH_AUTH_UID_DEFAULT (-1). | |
966 | ||
7c673cae FG |
967 | * @param io pool to query |
968 | * @param auid where to store the auid | |
969 | * @returns 0 on success, negative error code on failure | |
970 | */ | |
11fdf7f2 TL |
971 | CEPH_RADOS_API int rados_ioctx_pool_get_auid(rados_ioctx_t io, uint64_t *auid) |
972 | __attribute__((deprecated)); | |
7c673cae FG |
973 | |
974 | /* deprecated, use rados_ioctx_pool_requires_alignment2 instead */ | |
975 | CEPH_RADOS_API int rados_ioctx_pool_requires_alignment(rados_ioctx_t io) | |
976 | __attribute__((deprecated)); | |
977 | ||
978 | /** | |
979 | * Test whether the specified pool requires alignment or not. | |
980 | * | |
981 | * @param io pool to query | |
11fdf7f2 | 982 | * @param req 1 if alignment is supported, 0 if not. |
7c673cae FG |
983 | * @returns 0 on success, negative error code on failure |
984 | */ | |
985 | CEPH_RADOS_API int rados_ioctx_pool_requires_alignment2(rados_ioctx_t io, | |
11fdf7f2 | 986 | int *req); |
7c673cae FG |
987 | |
988 | /* deprecated, use rados_ioctx_pool_required_alignment2 instead */ | |
989 | CEPH_RADOS_API uint64_t rados_ioctx_pool_required_alignment(rados_ioctx_t io) | |
990 | __attribute__((deprecated)); | |
991 | ||
992 | /** | |
993 | * Get the alignment flavor of a pool | |
994 | * | |
995 | * @param io pool to query | |
996 | * @param alignment where to store the alignment flavor | |
997 | * @returns 0 on success, negative error code on failure | |
998 | */ | |
999 | CEPH_RADOS_API int rados_ioctx_pool_required_alignment2(rados_ioctx_t io, | |
1000 | uint64_t *alignment); | |
1001 | ||
1002 | /** | |
1003 | * Get the pool id of the io context | |
1004 | * | |
1005 | * @param io the io context to query | |
1006 | * @returns the id of the pool the io context uses | |
1007 | */ | |
1008 | CEPH_RADOS_API int64_t rados_ioctx_get_id(rados_ioctx_t io); | |
1009 | ||
1010 | /** | |
1011 | * Get the pool name of the io context | |
1012 | * | |
1013 | * @param io the io context to query | |
1014 | * @param buf pointer to buffer where name will be stored | |
1015 | * @param maxlen size of buffer where name will be stored | |
1016 | * @returns length of string stored, or -ERANGE if buffer too small | |
1017 | */ | |
1018 | CEPH_RADOS_API int rados_ioctx_get_pool_name(rados_ioctx_t io, char *buf, | |
1019 | unsigned maxlen); | |
1020 | ||
1021 | /** @} pools */ | |
1022 | ||
1023 | /** | |
1024 | * @name Object Locators | |
1025 | * | |
1026 | * @{ | |
1027 | */ | |
1028 | ||
1029 | /** | |
1030 | * Set the key for mapping objects to pgs within an io context. | |
1031 | * | |
1032 | * The key is used instead of the object name to determine which | |
1033 | * placement groups an object is put in. This affects all subsequent | |
1034 | * operations of the io context - until a different locator key is | |
1035 | * set, all objects in this io context will be placed in the same pg. | |
1036 | * | |
1037 | * @param io the io context to change | |
1038 | * @param key the key to use as the object locator, or NULL to discard | |
1039 | * any previously set key | |
1040 | */ | |
1041 | CEPH_RADOS_API void rados_ioctx_locator_set_key(rados_ioctx_t io, | |
1042 | const char *key); | |
1043 | ||
1044 | /** | |
1045 | * Set the namespace for objects within an io context | |
1046 | * | |
1047 | * The namespace specification further refines a pool into different | |
1048 | * domains. The mapping of objects to pgs is also based on this | |
1049 | * value. | |
1050 | * | |
1051 | * @param io the io context to change | |
1052 | * @param nspace the name to use as the namespace, or NULL use the | |
1053 | * default namespace | |
1054 | */ | |
1055 | CEPH_RADOS_API void rados_ioctx_set_namespace(rados_ioctx_t io, | |
1056 | const char *nspace); | |
11fdf7f2 TL |
1057 | |
1058 | /** | |
1059 | * Get the namespace for objects within the io context | |
1060 | * | |
1061 | * @param io the io context to query | |
1062 | * @param buf pointer to buffer where name will be stored | |
1063 | * @param maxlen size of buffer where name will be stored | |
1064 | * @returns length of string stored, or -ERANGE if buffer too small | |
1065 | */ | |
1066 | CEPH_RADOS_API int rados_ioctx_get_namespace(rados_ioctx_t io, char *buf, | |
1067 | unsigned maxlen); | |
1068 | ||
7c673cae FG |
1069 | /** @} obj_loc */ |
1070 | ||
1071 | /** | |
1072 | * @name Listing Objects | |
1073 | * @{ | |
1074 | */ | |
1075 | /** | |
1076 | * Start listing objects in a pool | |
1077 | * | |
1078 | * @param io the pool to list from | |
1079 | * @param ctx the handle to store list context in | |
1080 | * @returns 0 on success, negative error code on failure | |
1081 | */ | |
1082 | CEPH_RADOS_API int rados_nobjects_list_open(rados_ioctx_t io, | |
1083 | rados_list_ctx_t *ctx); | |
1084 | ||
1085 | /** | |
1086 | * Return hash position of iterator, rounded to the current PG | |
1087 | * | |
1088 | * @param ctx iterator marking where you are in the listing | |
1089 | * @returns current hash position, rounded to the current pg | |
1090 | */ | |
1091 | CEPH_RADOS_API uint32_t rados_nobjects_list_get_pg_hash_position(rados_list_ctx_t ctx); | |
1092 | ||
1093 | /** | |
1094 | * Reposition object iterator to a different hash position | |
1095 | * | |
1096 | * @param ctx iterator marking where you are in the listing | |
1097 | * @param pos hash position to move to | |
1098 | * @returns actual (rounded) position we moved to | |
1099 | */ | |
1100 | CEPH_RADOS_API uint32_t rados_nobjects_list_seek(rados_list_ctx_t ctx, | |
1101 | uint32_t pos); | |
1102 | ||
1103 | /** | |
1104 | * Reposition object iterator to a different position | |
1105 | * | |
1106 | * @param ctx iterator marking where you are in the listing | |
1107 | * @param cursor position to move to | |
1108 | * @returns rounded position we moved to | |
1109 | */ | |
1110 | CEPH_RADOS_API uint32_t rados_nobjects_list_seek_cursor(rados_list_ctx_t ctx, | |
1111 | rados_object_list_cursor cursor); | |
1112 | ||
1113 | /** | |
1114 | * Reposition object iterator to a different position | |
1115 | * | |
1116 | * The returned handle must be released with rados_object_list_cursor_free(). | |
1117 | * | |
1118 | * @param ctx iterator marking where you are in the listing | |
1119 | * @param cursor where to store cursor | |
1120 | * @returns 0 on success, negative error code on failure | |
1121 | */ | |
1122 | CEPH_RADOS_API int rados_nobjects_list_get_cursor(rados_list_ctx_t ctx, | |
1123 | rados_object_list_cursor *cursor); | |
1124 | ||
1125 | /** | |
1126 | * Get the next object name and locator in the pool | |
1127 | * | |
1128 | * *entry and *key are valid until next call to rados_nobjects_list_* | |
1129 | * | |
1130 | * @param ctx iterator marking where you are in the listing | |
1131 | * @param entry where to store the name of the entry | |
1132 | * @param key where to store the object locator (set to NULL to ignore) | |
1133 | * @param nspace where to store the object namespace (set to NULL to ignore) | |
1134 | * @returns 0 on success, negative error code on failure | |
1135 | * @returns -ENOENT when there are no more objects to list | |
1136 | */ | |
1137 | CEPH_RADOS_API int rados_nobjects_list_next(rados_list_ctx_t ctx, | |
1138 | const char **entry, | |
1139 | const char **key, | |
1140 | const char **nspace); | |
1141 | ||
f67539c2 TL |
1142 | /** |
1143 | * Get the next object name, locator and their sizes in the pool | |
1144 | * | |
1145 | * The sizes allow to list objects with \0 (the NUL character) | |
1146 | * in .e.g *entry. Is is unusual see such object names but a bug | |
1147 | * in a client has risen the need to handle them as well. | |
1148 | * *entry and *key are valid until next call to rados_nobjects_list_* | |
1149 | * | |
1150 | * @param ctx iterator marking where you are in the listing | |
1151 | * @param entry where to store the name of the entry | |
1152 | * @param key where to store the object locator (set to NULL to ignore) | |
1153 | * @param nspace where to store the object namespace (set to NULL to ignore) | |
1154 | * @param entry_size where to store the size of name of the entry | |
1155 | * @param key_size where to store the size of object locator (set to NULL to ignore) | |
1156 | * @param nspace_size where to store the size of object namespace (set to NULL to ignore) | |
1157 | * @returns 0 on success, negative error code on failure | |
1158 | * @returns -ENOENT when there are no more objects to list | |
1159 | */ | |
1160 | CEPH_RADOS_API int rados_nobjects_list_next2(rados_list_ctx_t ctx, | |
1161 | const char **entry, | |
1162 | const char **key, | |
1163 | const char **nspace, | |
1164 | size_t *entry_size, | |
1165 | size_t *key_size, | |
1166 | size_t *nspace_size); | |
1167 | ||
7c673cae FG |
1168 | /** |
1169 | * Close the object listing handle. | |
1170 | * | |
1171 | * This should be called when the handle is no longer needed. | |
1172 | * The handle should not be used after it has been closed. | |
1173 | * | |
1174 | * @param ctx the handle to close | |
1175 | */ | |
1176 | CEPH_RADOS_API void rados_nobjects_list_close(rados_list_ctx_t ctx); | |
1177 | ||
1178 | /** | |
1179 | * Get cursor handle pointing to the *beginning* of a pool. | |
1180 | * | |
1181 | * This is an opaque handle pointing to the start of a pool. It must | |
1182 | * be released with rados_object_list_cursor_free(). | |
1183 | * | |
1184 | * @param io ioctx for the pool | |
1185 | * @returns handle for the pool, NULL on error (pool does not exist) | |
1186 | */ | |
1187 | CEPH_RADOS_API rados_object_list_cursor rados_object_list_begin( | |
1188 | rados_ioctx_t io); | |
1189 | ||
1190 | /** | |
1191 | * Get cursor handle pointing to the *end* of a pool. | |
1192 | * | |
1193 | * This is an opaque handle pointing to the start of a pool. It must | |
1194 | * be released with rados_object_list_cursor_free(). | |
1195 | * | |
1196 | * @param io ioctx for the pool | |
1197 | * @returns handle for the pool, NULL on error (pool does not exist) | |
1198 | */ | |
1199 | CEPH_RADOS_API rados_object_list_cursor rados_object_list_end(rados_ioctx_t io); | |
1200 | ||
1201 | /** | |
1202 | * Check if a cursor has reached the end of a pool | |
1203 | * | |
1204 | * @param io ioctx | |
1205 | * @param cur cursor | |
1206 | * @returns 1 if the cursor has reached the end of the pool, 0 otherwise | |
1207 | */ | |
1208 | CEPH_RADOS_API int rados_object_list_is_end(rados_ioctx_t io, | |
1209 | rados_object_list_cursor cur); | |
1210 | ||
1211 | /** | |
1212 | * Release a cursor | |
1213 | * | |
1214 | * Release a cursor. The handle may not be used after this point. | |
1215 | * | |
1216 | * @param io ioctx | |
1217 | * @param cur cursor | |
1218 | */ | |
1219 | CEPH_RADOS_API void rados_object_list_cursor_free(rados_ioctx_t io, | |
1220 | rados_object_list_cursor cur); | |
1221 | ||
1222 | /** | |
1223 | * Compare two cursor positions | |
1224 | * | |
1225 | * Compare two cursors, and indicate whether the first cursor precedes, | |
1226 | * matches, or follows the second. | |
1227 | * | |
1228 | * @param io ioctx | |
1229 | * @param lhs first cursor | |
1230 | * @param rhs second cursor | |
1231 | * @returns -1, 0, or 1 for lhs < rhs, lhs == rhs, or lhs > rhs | |
1232 | */ | |
1233 | CEPH_RADOS_API int rados_object_list_cursor_cmp(rados_ioctx_t io, | |
1234 | rados_object_list_cursor lhs, rados_object_list_cursor rhs); | |
1235 | ||
1236 | /** | |
11fdf7f2 | 1237 | * @return the number of items set in the results array |
7c673cae FG |
1238 | */ |
1239 | CEPH_RADOS_API int rados_object_list(rados_ioctx_t io, | |
1240 | const rados_object_list_cursor start, | |
1241 | const rados_object_list_cursor finish, | |
1242 | const size_t result_size, | |
1243 | const char *filter_buf, | |
1244 | const size_t filter_buf_len, | |
1245 | rados_object_list_item *results, | |
1246 | rados_object_list_cursor *next); | |
1247 | ||
1248 | CEPH_RADOS_API void rados_object_list_free( | |
1249 | const size_t result_size, | |
1250 | rados_object_list_item *results); | |
1251 | ||
1252 | /** | |
1253 | * Obtain cursors delineating a subset of a range. Use this | |
1254 | * when you want to split up the work of iterating over the | |
1255 | * global namespace. Expected use case is when you are iterating | |
1256 | * in parallel, with `m` workers, and each worker taking an id `n`. | |
1257 | * | |
11fdf7f2 | 1258 | * @param io ioctx |
7c673cae FG |
1259 | * @param start start of the range to be sliced up (inclusive) |
1260 | * @param finish end of the range to be sliced up (exclusive) | |
7c673cae | 1261 | * @param n which of the m chunks you would like to get cursors for |
11fdf7f2 | 1262 | * @param m how many chunks to divide start-finish into |
7c673cae FG |
1263 | * @param split_start cursor populated with start of the subrange (inclusive) |
1264 | * @param split_finish cursor populated with end of the subrange (exclusive) | |
1265 | */ | |
1266 | CEPH_RADOS_API void rados_object_list_slice(rados_ioctx_t io, | |
1267 | const rados_object_list_cursor start, | |
1268 | const rados_object_list_cursor finish, | |
1269 | const size_t n, | |
1270 | const size_t m, | |
1271 | rados_object_list_cursor *split_start, | |
1272 | rados_object_list_cursor *split_finish); | |
1273 | ||
1274 | ||
1275 | /** @} Listing Objects */ | |
1276 | ||
1277 | /** | |
1278 | * @name Snapshots | |
1279 | * | |
1280 | * RADOS snapshots are based upon sequence numbers that form a | |
1281 | * snapshot context. They are pool-specific. The snapshot context | |
1282 | * consists of the current snapshot sequence number for a pool, and an | |
1283 | * array of sequence numbers at which snapshots were taken, in | |
1284 | * descending order. Whenever a snapshot is created or deleted, the | |
1285 | * snapshot sequence number for the pool is increased. To add a new | |
1286 | * snapshot, the new snapshot sequence number must be increased and | |
1287 | * added to the snapshot context. | |
1288 | * | |
1289 | * There are two ways to manage these snapshot contexts: | |
1290 | * -# within the RADOS cluster | |
1291 | * These are called pool snapshots, and store the snapshot context | |
1292 | * in the OSDMap. These represent a snapshot of all the objects in | |
1293 | * a pool. | |
1294 | * -# within the RADOS clients | |
1295 | * These are called self-managed snapshots, and push the | |
1296 | * responsibility for keeping track of the snapshot context to the | |
1297 | * clients. For every write, the client must send the snapshot | |
1298 | * context. In librados, this is accomplished with | |
1299 | * rados_selfmanaged_snap_set_write_ctx(). These are more | |
1300 | * difficult to manage, but are restricted to specific objects | |
1301 | * instead of applying to an entire pool. | |
1302 | * | |
1303 | * @{ | |
1304 | */ | |
1305 | ||
1306 | /** | |
1307 | * Create a pool-wide snapshot | |
1308 | * | |
1309 | * @param io the pool to snapshot | |
1310 | * @param snapname the name of the snapshot | |
1311 | * @returns 0 on success, negative error code on failure | |
1312 | */ | |
1313 | CEPH_RADOS_API int rados_ioctx_snap_create(rados_ioctx_t io, | |
1314 | const char *snapname); | |
1315 | ||
1316 | /** | |
1317 | * Delete a pool snapshot | |
1318 | * | |
1319 | * @param io the pool to delete the snapshot from | |
1320 | * @param snapname which snapshot to delete | |
1321 | * @returns 0 on success, negative error code on failure | |
1322 | */ | |
1323 | CEPH_RADOS_API int rados_ioctx_snap_remove(rados_ioctx_t io, | |
1324 | const char *snapname); | |
1325 | ||
1326 | /** | |
1327 | * Rollback an object to a pool snapshot | |
1328 | * | |
1329 | * The contents of the object will be the same as | |
1330 | * when the snapshot was taken. | |
1331 | * | |
1332 | * @param io the pool in which the object is stored | |
1333 | * @param oid the name of the object to rollback | |
1334 | * @param snapname which snapshot to rollback to | |
1335 | * @returns 0 on success, negative error code on failure | |
1336 | */ | |
1337 | CEPH_RADOS_API int rados_ioctx_snap_rollback(rados_ioctx_t io, const char *oid, | |
1338 | const char *snapname); | |
1339 | ||
1340 | /** | |
1341 | * @warning Deprecated: Use rados_ioctx_snap_rollback() instead | |
1342 | */ | |
1343 | CEPH_RADOS_API int rados_rollback(rados_ioctx_t io, const char *oid, | |
1344 | const char *snapname) | |
1345 | __attribute__((deprecated)); | |
1346 | ||
1347 | /** | |
1348 | * Set the snapshot from which reads are performed. | |
1349 | * | |
1350 | * Subsequent reads will return data as it was at the time of that | |
1351 | * snapshot. | |
1352 | * | |
1353 | * @param io the io context to change | |
1354 | * @param snap the id of the snapshot to set, or LIBRADOS_SNAP_HEAD for no | |
1355 | * snapshot (i.e. normal operation) | |
1356 | */ | |
1357 | CEPH_RADOS_API void rados_ioctx_snap_set_read(rados_ioctx_t io, | |
1358 | rados_snap_t snap); | |
1359 | ||
1360 | /** | |
1361 | * Allocate an ID for a self-managed snapshot | |
1362 | * | |
1363 | * Get a unique ID to put in the snaphot context to create a | |
1364 | * snapshot. A clone of an object is not created until a write with | |
1365 | * the new snapshot context is completed. | |
1366 | * | |
1367 | * @param io the pool in which the snapshot will exist | |
1368 | * @param snapid where to store the newly allocated snapshot ID | |
1369 | * @returns 0 on success, negative error code on failure | |
1370 | */ | |
1371 | CEPH_RADOS_API int rados_ioctx_selfmanaged_snap_create(rados_ioctx_t io, | |
1372 | rados_snap_t *snapid); | |
1373 | CEPH_RADOS_API void | |
1374 | rados_aio_ioctx_selfmanaged_snap_create(rados_ioctx_t io, | |
1375 | rados_snap_t *snapid, | |
1376 | rados_completion_t completion); | |
1377 | ||
1378 | /** | |
1379 | * Remove a self-managed snapshot | |
1380 | * | |
1381 | * This increases the snapshot sequence number, which will cause | |
1382 | * snapshots to be removed lazily. | |
1383 | * | |
1384 | * @param io the pool in which the snapshot will exist | |
1385 | * @param snapid where to store the newly allocated snapshot ID | |
1386 | * @returns 0 on success, negative error code on failure | |
1387 | */ | |
1388 | CEPH_RADOS_API int rados_ioctx_selfmanaged_snap_remove(rados_ioctx_t io, | |
1389 | rados_snap_t snapid); | |
1390 | CEPH_RADOS_API void | |
1391 | rados_aio_ioctx_selfmanaged_snap_remove(rados_ioctx_t io, | |
1392 | rados_snap_t snapid, | |
1393 | rados_completion_t completion); | |
1394 | ||
1395 | /** | |
1396 | * Rollback an object to a self-managed snapshot | |
1397 | * | |
1398 | * The contents of the object will be the same as | |
1399 | * when the snapshot was taken. | |
1400 | * | |
1401 | * @param io the pool in which the object is stored | |
1402 | * @param oid the name of the object to rollback | |
1403 | * @param snapid which snapshot to rollback to | |
1404 | * @returns 0 on success, negative error code on failure | |
1405 | */ | |
1406 | CEPH_RADOS_API int rados_ioctx_selfmanaged_snap_rollback(rados_ioctx_t io, | |
1407 | const char *oid, | |
1408 | rados_snap_t snapid); | |
1409 | ||
1410 | /** | |
1411 | * Set the snapshot context for use when writing to objects | |
1412 | * | |
1413 | * This is stored in the io context, and applies to all future writes. | |
1414 | * | |
1415 | * @param io the io context to change | |
1416 | * @param seq the newest snapshot sequence number for the pool | |
1417 | * @param snaps array of snapshots in sorted by descending id | |
1418 | * @param num_snaps how many snaphosts are in the snaps array | |
1419 | * @returns 0 on success, negative error code on failure | |
1420 | * @returns -EINVAL if snaps are not in descending order | |
1421 | */ | |
1422 | CEPH_RADOS_API int rados_ioctx_selfmanaged_snap_set_write_ctx(rados_ioctx_t io, | |
1423 | rados_snap_t seq, | |
1424 | rados_snap_t *snaps, | |
1425 | int num_snaps); | |
1426 | ||
1427 | /** | |
1428 | * List all the ids of pool snapshots | |
1429 | * | |
1430 | * If the output array does not have enough space to fit all the | |
1431 | * snapshots, -ERANGE is returned and the caller should retry with a | |
1432 | * larger array. | |
1433 | * | |
1434 | * @param io the pool to read from | |
1435 | * @param snaps where to store the results | |
1436 | * @param maxlen the number of rados_snap_t that fit in the snaps array | |
1437 | * @returns number of snapshots on success, negative error code on failure | |
1438 | * @returns -ERANGE is returned if the snaps array is too short | |
1439 | */ | |
1440 | CEPH_RADOS_API int rados_ioctx_snap_list(rados_ioctx_t io, rados_snap_t *snaps, | |
1441 | int maxlen); | |
1442 | ||
1443 | /** | |
1444 | * Get the id of a pool snapshot | |
1445 | * | |
1446 | * @param io the pool to read from | |
1447 | * @param name the snapshot to find | |
1448 | * @param id where to store the result | |
1449 | * @returns 0 on success, negative error code on failure | |
1450 | */ | |
1451 | CEPH_RADOS_API int rados_ioctx_snap_lookup(rados_ioctx_t io, const char *name, | |
1452 | rados_snap_t *id); | |
1453 | ||
1454 | /** | |
1455 | * Get the name of a pool snapshot | |
1456 | * | |
1457 | * @param io the pool to read from | |
1458 | * @param id the snapshot to find | |
1459 | * @param name where to store the result | |
1460 | * @param maxlen the size of the name array | |
1461 | * @returns 0 on success, negative error code on failure | |
1462 | * @returns -ERANGE if the name array is too small | |
1463 | */ | |
1464 | CEPH_RADOS_API int rados_ioctx_snap_get_name(rados_ioctx_t io, rados_snap_t id, | |
1465 | char *name, int maxlen); | |
1466 | ||
1467 | /** | |
1468 | * Find when a pool snapshot occurred | |
1469 | * | |
1470 | * @param io the pool the snapshot was taken in | |
1471 | * @param id the snapshot to lookup | |
1472 | * @param t where to store the result | |
1473 | * @returns 0 on success, negative error code on failure | |
1474 | */ | |
1475 | CEPH_RADOS_API int rados_ioctx_snap_get_stamp(rados_ioctx_t io, rados_snap_t id, | |
1476 | time_t *t); | |
1477 | ||
1478 | /** @} Snapshots */ | |
1479 | ||
1480 | /** | |
1481 | * @name Synchronous I/O | |
1482 | * Writes are replicated to a number of OSDs based on the | |
1483 | * configuration of the pool they are in. These write functions block | |
1484 | * until data is in memory on all replicas of the object they're | |
1485 | * writing to - they are equivalent to doing the corresponding | |
1486 | * asynchronous write, and the calling | |
1487 | * rados_ioctx_wait_for_complete(). For greater data safety, use the | |
1488 | * asynchronous functions and rados_aio_wait_for_safe(). | |
1489 | * | |
1490 | * @{ | |
1491 | */ | |
1492 | ||
1493 | /** | |
1494 | * Return the version of the last object read or written to. | |
1495 | * | |
1496 | * This exposes the internal version number of the last object read or | |
1497 | * written via this io context | |
1498 | * | |
1499 | * @param io the io context to check | |
1500 | * @returns last read or written object version | |
1501 | */ | |
1502 | CEPH_RADOS_API uint64_t rados_get_last_version(rados_ioctx_t io); | |
1503 | ||
1504 | /** | |
1505 | * Write *len* bytes from *buf* into the *oid* object, starting at | |
1506 | * offset *off*. The value of *len* must be <= UINT_MAX/2. | |
1507 | * | |
1508 | * @note This will never return a positive value not equal to len. | |
1509 | * @param io the io context in which the write will occur | |
1510 | * @param oid name of the object | |
1511 | * @param buf data to write | |
1512 | * @param len length of the data, in bytes | |
1513 | * @param off byte offset in the object to begin writing at | |
1514 | * @returns 0 on success, negative error code on failure | |
1515 | */ | |
1516 | CEPH_RADOS_API int rados_write(rados_ioctx_t io, const char *oid, | |
1517 | const char *buf, size_t len, uint64_t off); | |
1518 | ||
1519 | /** | |
1520 | * Write *len* bytes from *buf* into the *oid* object. The value of | |
1521 | * *len* must be <= UINT_MAX/2. | |
1522 | * | |
1523 | * The object is filled with the provided data. If the object exists, | |
1524 | * it is atomically truncated and then written. | |
1525 | * | |
1526 | * @param io the io context in which the write will occur | |
1527 | * @param oid name of the object | |
1528 | * @param buf data to write | |
1529 | * @param len length of the data, in bytes | |
1530 | * @returns 0 on success, negative error code on failure | |
1531 | */ | |
1532 | CEPH_RADOS_API int rados_write_full(rados_ioctx_t io, const char *oid, | |
1533 | const char *buf, size_t len); | |
1534 | ||
1535 | /** | |
1536 | * Write the same *data_len* bytes from *buf* multiple times into the | |
1537 | * *oid* object. *write_len* bytes are written in total, which must be | |
1538 | * a multiple of *data_len*. The value of *write_len* and *data_len* | |
1539 | * must be <= UINT_MAX/2. | |
1540 | * | |
1541 | * @param io the io context in which the write will occur | |
1542 | * @param oid name of the object | |
1543 | * @param buf data to write | |
1544 | * @param data_len length of the data, in bytes | |
1545 | * @param write_len the total number of bytes to write | |
1546 | * @param off byte offset in the object to begin writing at | |
1547 | * @returns 0 on success, negative error code on failure | |
1548 | */ | |
1549 | CEPH_RADOS_API int rados_writesame(rados_ioctx_t io, const char *oid, | |
1550 | const char *buf, size_t data_len, | |
1551 | size_t write_len, uint64_t off); | |
1552 | ||
1553 | /** | |
1554 | * Append *len* bytes from *buf* into the *oid* object. The value of | |
1555 | * *len* must be <= UINT_MAX/2. | |
1556 | * | |
1557 | * @param io the context to operate in | |
1558 | * @param oid the name of the object | |
1559 | * @param buf the data to append | |
1560 | * @param len length of buf (in bytes) | |
1561 | * @returns 0 on success, negative error code on failure | |
1562 | */ | |
1563 | CEPH_RADOS_API int rados_append(rados_ioctx_t io, const char *oid, | |
1564 | const char *buf, size_t len); | |
1565 | ||
1566 | /** | |
1567 | * Read data from an object | |
1568 | * | |
1569 | * The io context determines the snapshot to read from, if any was set | |
1570 | * by rados_ioctx_snap_set_read(). | |
1571 | * | |
1572 | * @param io the context in which to perform the read | |
1573 | * @param oid the name of the object to read from | |
1574 | * @param buf where to store the results | |
1575 | * @param len the number of bytes to read | |
1576 | * @param off the offset to start reading from in the object | |
1577 | * @returns number of bytes read on success, negative error code on | |
1578 | * failure | |
1579 | */ | |
1580 | CEPH_RADOS_API int rados_read(rados_ioctx_t io, const char *oid, char *buf, | |
1581 | size_t len, uint64_t off); | |
1582 | ||
1583 | /** | |
1584 | * Compute checksum from object data | |
1585 | * | |
1586 | * The io context determines the snapshot to checksum, if any was set | |
1587 | * by rados_ioctx_snap_set_read(). The length of the init_value and | |
1588 | * resulting checksum are dependent upon the checksum type: | |
1589 | * | |
1590 | * XXHASH64: le64 | |
1591 | * XXHASH32: le32 | |
1592 | * CRC32C: le32 | |
1593 | * | |
1594 | * The checksum result is encoded the following manner: | |
1595 | * | |
1596 | * le32 num_checksum_chunks | |
1597 | * { | |
1598 | * leXX checksum for chunk (where XX = appropriate size for the checksum type) | |
1599 | * } * num_checksum_chunks | |
1600 | * | |
1601 | * @param io the context in which to perform the checksum | |
1602 | * @param oid the name of the object to checksum | |
1603 | * @param type the checksum algorithm to utilize | |
1604 | * @param init_value the init value for the algorithm | |
1605 | * @param init_value_len the length of the init value | |
1606 | * @param len the number of bytes to checksum | |
11fdf7f2 | 1607 | * @param off the offset to start checksumming in the object |
7c673cae FG |
1608 | * @param chunk_size optional length-aligned chunk size for checksums |
1609 | * @param pchecksum where to store the checksum result | |
1610 | * @param checksum_len the number of bytes available for the result | |
1611 | * @return negative error code on failure | |
1612 | */ | |
1613 | CEPH_RADOS_API int rados_checksum(rados_ioctx_t io, const char *oid, | |
1614 | rados_checksum_type_t type, | |
1615 | const char *init_value, size_t init_value_len, | |
1616 | size_t len, uint64_t off, size_t chunk_size, | |
1617 | char *pchecksum, size_t checksum_len); | |
1618 | ||
1619 | /** | |
1620 | * Delete an object | |
1621 | * | |
1622 | * @note This does not delete any snapshots of the object. | |
1623 | * | |
1624 | * @param io the pool to delete the object from | |
1625 | * @param oid the name of the object to delete | |
1626 | * @returns 0 on success, negative error code on failure | |
1627 | */ | |
1628 | CEPH_RADOS_API int rados_remove(rados_ioctx_t io, const char *oid); | |
1629 | ||
1630 | /** | |
1631 | * Resize an object | |
1632 | * | |
1633 | * If this enlarges the object, the new area is logically filled with | |
1634 | * zeroes. If this shrinks the object, the excess data is removed. | |
1635 | * | |
1636 | * @param io the context in which to truncate | |
1637 | * @param oid the name of the object | |
1638 | * @param size the new size of the object in bytes | |
1639 | * @returns 0 on success, negative error code on failure | |
1640 | */ | |
1641 | CEPH_RADOS_API int rados_trunc(rados_ioctx_t io, const char *oid, | |
1642 | uint64_t size); | |
1643 | ||
1644 | /** | |
1645 | * Compare an on-disk object range with a buffer | |
1646 | * | |
1647 | * @param io the context in which to perform the comparison | |
1648 | * @param o name of the object | |
1649 | * @param cmp_buf buffer containing bytes to be compared with object contents | |
11fdf7f2 | 1650 | * @param cmp_len length to compare and size of @c cmp_buf in bytes |
7c673cae FG |
1651 | * @param off object byte offset at which to start the comparison |
1652 | * @returns 0 on success, negative error code on failure, | |
1653 | * (-MAX_ERRNO - mismatch_off) on mismatch | |
1654 | */ | |
1655 | CEPH_RADOS_API int rados_cmpext(rados_ioctx_t io, const char *o, | |
1656 | const char *cmp_buf, size_t cmp_len, | |
1657 | uint64_t off); | |
1658 | ||
1659 | /** | |
1660 | * @name Xattrs | |
1661 | * Extended attributes are stored as extended attributes on the files | |
1662 | * representing an object on the OSDs. Thus, they have the same | |
1663 | * limitations as the underlying filesystem. On ext4, this means that | |
1664 | * the total data stored in xattrs cannot exceed 4KB. | |
1665 | * | |
1666 | * @{ | |
1667 | */ | |
1668 | ||
1669 | /** | |
1670 | * Get the value of an extended attribute on an object. | |
1671 | * | |
1672 | * @param io the context in which the attribute is read | |
1673 | * @param o name of the object | |
1674 | * @param name which extended attribute to read | |
1675 | * @param buf where to store the result | |
1676 | * @param len size of buf in bytes | |
1677 | * @returns length of xattr value on success, negative error code on failure | |
1678 | */ | |
1679 | CEPH_RADOS_API int rados_getxattr(rados_ioctx_t io, const char *o, | |
1680 | const char *name, char *buf, size_t len); | |
1681 | ||
1682 | /** | |
1683 | * Set an extended attribute on an object. | |
1684 | * | |
1685 | * @param io the context in which xattr is set | |
1686 | * @param o name of the object | |
1687 | * @param name which extended attribute to set | |
1688 | * @param buf what to store in the xattr | |
1689 | * @param len the number of bytes in buf | |
1690 | * @returns 0 on success, negative error code on failure | |
1691 | */ | |
1692 | CEPH_RADOS_API int rados_setxattr(rados_ioctx_t io, const char *o, | |
1693 | const char *name, const char *buf, | |
1694 | size_t len); | |
1695 | ||
1696 | /** | |
1697 | * Delete an extended attribute from an object. | |
1698 | * | |
1699 | * @param io the context in which to delete the xattr | |
1700 | * @param o the name of the object | |
1701 | * @param name which xattr to delete | |
1702 | * @returns 0 on success, negative error code on failure | |
1703 | */ | |
1704 | CEPH_RADOS_API int rados_rmxattr(rados_ioctx_t io, const char *o, | |
1705 | const char *name); | |
1706 | ||
1707 | /** | |
1708 | * Start iterating over xattrs on an object. | |
1709 | * | |
1710 | * @post iter is a valid iterator | |
1711 | * | |
1712 | * @param io the context in which to list xattrs | |
1713 | * @param oid name of the object | |
1714 | * @param iter where to store the iterator | |
1715 | * @returns 0 on success, negative error code on failure | |
1716 | */ | |
1717 | CEPH_RADOS_API int rados_getxattrs(rados_ioctx_t io, const char *oid, | |
1718 | rados_xattrs_iter_t *iter); | |
1719 | ||
1720 | /** | |
1721 | * Get the next xattr on the object | |
1722 | * | |
1723 | * @pre iter is a valid iterator | |
1724 | * | |
1725 | * @post name is the NULL-terminated name of the next xattr, and val | |
1726 | * contains the value of the xattr, which is of length len. If the end | |
1727 | * of the list has been reached, name and val are NULL, and len is 0. | |
1728 | * | |
1729 | * @param iter iterator to advance | |
1730 | * @param name where to store the name of the next xattr | |
1731 | * @param val where to store the value of the next xattr | |
1732 | * @param len the number of bytes in val | |
1733 | * @returns 0 on success, negative error code on failure | |
1734 | */ | |
1735 | CEPH_RADOS_API int rados_getxattrs_next(rados_xattrs_iter_t iter, | |
1736 | const char **name, const char **val, | |
1737 | size_t *len); | |
1738 | ||
1739 | /** | |
1740 | * Close the xattr iterator. | |
1741 | * | |
1742 | * iter should not be used after this is called. | |
1743 | * | |
1744 | * @param iter the iterator to close | |
1745 | */ | |
1746 | CEPH_RADOS_API void rados_getxattrs_end(rados_xattrs_iter_t iter); | |
1747 | ||
1748 | /** @} Xattrs */ | |
1749 | ||
1750 | /** | |
1751 | * Get the next omap key/value pair on the object | |
1752 | * | |
1753 | * @pre iter is a valid iterator | |
1754 | * | |
1755 | * @post key and val are the next key/value pair. key is | |
1756 | * null-terminated, and val has length len. If the end of the list has | |
1757 | * been reached, key and val are NULL, and len is 0. key and val will | |
1758 | * not be accessible after rados_omap_get_end() is called on iter, so | |
1759 | * if they are needed after that they should be copied. | |
1760 | * | |
1761 | * @param iter iterator to advance | |
1762 | * @param key where to store the key of the next omap entry | |
1763 | * @param val where to store the value of the next omap entry | |
1764 | * @param len where to store the number of bytes in val | |
1765 | * @returns 0 on success, negative error code on failure | |
1766 | */ | |
1767 | CEPH_RADOS_API int rados_omap_get_next(rados_omap_iter_t iter, | |
11fdf7f2 TL |
1768 | char **key, |
1769 | char **val, | |
1770 | size_t *len); | |
7c673cae FG |
1771 | |
1772 | /** | |
11fdf7f2 TL |
1773 | * Get the next omap key/value pair on the object. Note that it's |
1774 | * perfectly safe to mix calls to rados_omap_get_next and | |
1775 | * rados_omap_get_next2. | |
7c673cae | 1776 | * |
11fdf7f2 | 1777 | * @pre iter is a valid iterator |
7c673cae | 1778 | * |
11fdf7f2 TL |
1779 | * @post key and val are the next key/value pair. key has length |
1780 | * keylen and val has length vallen. If the end of the list has | |
1781 | * been reached, key and val are NULL, and keylen and vallen is 0. | |
1782 | * key and val will not be accessible after rados_omap_get_end() | |
1783 | * is called on iter, so if they are needed after that they | |
1784 | * should be copied. | |
7c673cae | 1785 | * |
11fdf7f2 TL |
1786 | * @param iter iterator to advance |
1787 | * @param key where to store the key of the next omap entry | |
1788 | * @param val where to store the value of the next omap entry | |
1789 | * @param key_len where to store the number of bytes in key | |
1790 | * @param val_len where to store the number of bytes in val | |
7c673cae FG |
1791 | * @returns 0 on success, negative error code on failure |
1792 | */ | |
11fdf7f2 TL |
1793 | CEPH_RADOS_API int rados_omap_get_next2(rados_omap_iter_t iter, |
1794 | char **key, | |
1795 | char **val, | |
1796 | size_t *key_len, | |
1797 | size_t *val_len); | |
7c673cae FG |
1798 | |
1799 | /** | |
11fdf7f2 | 1800 | * Return number of elements in the iterator |
7c673cae | 1801 | * |
11fdf7f2 | 1802 | * @param iter the iterator of which to return the size |
7c673cae | 1803 | */ |
11fdf7f2 | 1804 | CEPH_RADOS_API unsigned int rados_omap_iter_size(rados_omap_iter_t iter); |
7c673cae FG |
1805 | |
1806 | /** | |
11fdf7f2 | 1807 | * Close the omap iterator. |
7c673cae | 1808 | * |
11fdf7f2 | 1809 | * iter should not be used after this is called. |
7c673cae | 1810 | * |
11fdf7f2 | 1811 | * @param iter the iterator to close |
7c673cae | 1812 | */ |
11fdf7f2 | 1813 | CEPH_RADOS_API void rados_omap_get_end(rados_omap_iter_t iter); |
7c673cae FG |
1814 | |
1815 | /** | |
1e59de90 | 1816 | * Get object size and most recent update time from the OSD. |
7c673cae FG |
1817 | * |
1818 | * @param io ioctx | |
1819 | * @param o object name | |
11fdf7f2 TL |
1820 | * @param psize where to store object size |
1821 | * @param pmtime where to store modification time | |
7c673cae | 1822 | * @returns 0 on success, negative error code on failure |
7c673cae | 1823 | */ |
11fdf7f2 TL |
1824 | CEPH_RADOS_API int rados_stat(rados_ioctx_t io, const char *o, uint64_t *psize, |
1825 | time_t *pmtime); | |
1e59de90 TL |
1826 | |
1827 | CEPH_RADOS_API int rados_stat2(rados_ioctx_t io, const char *o, uint64_t *psize, | |
1828 | struct timespec *pmtime); | |
1829 | ||
7c673cae FG |
1830 | /** |
1831 | * Execute an OSD class method on an object | |
1832 | * | |
1833 | * The OSD has a plugin mechanism for performing complicated | |
1834 | * operations on an object atomically. These plugins are called | |
1835 | * classes. This function allows librados users to call the custom | |
1836 | * methods. The input and output formats are defined by the class. | |
1837 | * Classes in ceph.git can be found in src/cls subdirectories | |
1838 | * | |
1839 | * @param io the context in which to call the method | |
1840 | * @param oid the object to call the method on | |
1841 | * @param cls the name of the class | |
1842 | * @param method the name of the method | |
1843 | * @param in_buf where to find input | |
1844 | * @param in_len length of in_buf in bytes | |
1845 | * @param buf where to store output | |
1846 | * @param out_len length of buf in bytes | |
1847 | * @returns the length of the output, or | |
1848 | * -ERANGE if out_buf does not have enough space to store it (For methods that return data). For | |
1849 | * methods that don't return data, the return value is | |
1850 | * method-specific. | |
1851 | */ | |
1852 | CEPH_RADOS_API int rados_exec(rados_ioctx_t io, const char *oid, | |
1853 | const char *cls, const char *method, | |
1854 | const char *in_buf, size_t in_len, char *buf, | |
1855 | size_t out_len); | |
1856 | ||
1857 | ||
1858 | /** @} Synchronous I/O */ | |
1859 | ||
1860 | /** | |
1861 | * @name Asynchronous I/O | |
1862 | * Read and write to objects without blocking. | |
1863 | * | |
1864 | * @{ | |
1865 | */ | |
1866 | ||
1867 | /** | |
1868 | * @typedef rados_callback_t | |
1869 | * Callbacks for asynchrous operations take two parameters: | |
1870 | * - cb the completion that has finished | |
1871 | * - arg application defined data made available to the callback function | |
1872 | */ | |
1873 | typedef void (*rados_callback_t)(rados_completion_t cb, void *arg); | |
1874 | ||
1875 | /** | |
1876 | * Constructs a completion to use with asynchronous operations | |
1877 | * | |
1878 | * The complete and safe callbacks correspond to operations being | |
1879 | * acked and committed, respectively. The callbacks are called in | |
1880 | * order of receipt, so the safe callback may be triggered before the | |
1881 | * complete callback, and vice versa. This is affected by journalling | |
1882 | * on the OSDs. | |
1883 | * | |
1884 | * TODO: more complete documentation of this elsewhere (in the RADOS docs?) | |
1885 | * | |
1886 | * @note Read operations only get a complete callback. | |
1887 | * @note BUG: this should check for ENOMEM instead of throwing an exception | |
1888 | * | |
1889 | * @param cb_arg application-defined data passed to the callback functions | |
1890 | * @param cb_complete the function to be called when the operation is | |
9f95a23c | 1891 | * in memory on all replicas |
7c673cae FG |
1892 | * @param cb_safe the function to be called when the operation is on |
1893 | * stable storage on all replicas | |
1894 | * @param pc where to store the completion | |
1895 | * @returns 0 | |
1896 | */ | |
1897 | CEPH_RADOS_API int rados_aio_create_completion(void *cb_arg, | |
1898 | rados_callback_t cb_complete, | |
1899 | rados_callback_t cb_safe, | |
1900 | rados_completion_t *pc); | |
1901 | ||
9f95a23c TL |
1902 | /** |
1903 | * Constructs a completion to use with asynchronous operations | |
1904 | * | |
1905 | * The complete callback corresponds to operation being acked. | |
1906 | * | |
1907 | * @note BUG: this should check for ENOMEM instead of throwing an exception | |
1908 | * | |
1909 | * @param cb_arg application-defined data passed to the callback functions | |
1910 | * @param cb_complete the function to be called when the operation is committed | |
1911 | * on all replicas | |
1912 | * @param pc where to store the completion | |
1913 | * @returns 0 | |
1914 | */ | |
1915 | CEPH_RADOS_API int rados_aio_create_completion2(void *cb_arg, | |
1916 | rados_callback_t cb_complete, | |
1917 | rados_completion_t *pc); | |
1918 | ||
7c673cae FG |
1919 | /** |
1920 | * Block until an operation completes | |
1921 | * | |
1922 | * This means it is in memory on all replicas. | |
1923 | * | |
1924 | * @note BUG: this should be void | |
1925 | * | |
1926 | * @param c operation to wait for | |
1927 | * @returns 0 | |
1928 | */ | |
1929 | CEPH_RADOS_API int rados_aio_wait_for_complete(rados_completion_t c); | |
1930 | ||
1931 | /** | |
1932 | * Block until an operation is safe | |
1933 | * | |
1934 | * This means it is on stable storage on all replicas. | |
1935 | * | |
1936 | * @note BUG: this should be void | |
1937 | * | |
1938 | * @param c operation to wait for | |
1939 | * @returns 0 | |
1940 | */ | |
9f95a23c TL |
1941 | CEPH_RADOS_API int rados_aio_wait_for_safe(rados_completion_t c) |
1942 | __attribute__((deprecated)); | |
7c673cae FG |
1943 | |
1944 | /** | |
1945 | * Has an asynchronous operation completed? | |
1946 | * | |
1947 | * @warning This does not imply that the complete callback has | |
1948 | * finished | |
1949 | * | |
1950 | * @param c async operation to inspect | |
1951 | * @returns whether c is complete | |
1952 | */ | |
1953 | CEPH_RADOS_API int rados_aio_is_complete(rados_completion_t c); | |
1954 | ||
1955 | /** | |
1956 | * Is an asynchronous operation safe? | |
1957 | * | |
1958 | * @warning This does not imply that the safe callback has | |
1959 | * finished | |
1960 | * | |
1961 | * @param c async operation to inspect | |
1962 | * @returns whether c is safe | |
1963 | */ | |
1964 | CEPH_RADOS_API int rados_aio_is_safe(rados_completion_t c); | |
1965 | ||
1966 | /** | |
1967 | * Block until an operation completes and callback completes | |
1968 | * | |
1969 | * This means it is in memory on all replicas and can be read. | |
1970 | * | |
1971 | * @note BUG: this should be void | |
1972 | * | |
1973 | * @param c operation to wait for | |
1974 | * @returns 0 | |
1975 | */ | |
1976 | CEPH_RADOS_API int rados_aio_wait_for_complete_and_cb(rados_completion_t c); | |
1977 | ||
1978 | /** | |
1979 | * Block until an operation is safe and callback has completed | |
1980 | * | |
1981 | * This means it is on stable storage on all replicas. | |
1982 | * | |
1983 | * @note BUG: this should be void | |
1984 | * | |
1985 | * @param c operation to wait for | |
1986 | * @returns 0 | |
1987 | */ | |
9f95a23c TL |
1988 | CEPH_RADOS_API int rados_aio_wait_for_safe_and_cb(rados_completion_t c) |
1989 | __attribute__((deprecated)); | |
7c673cae FG |
1990 | |
1991 | /** | |
1992 | * Has an asynchronous operation and callback completed | |
1993 | * | |
1994 | * @param c async operation to inspect | |
1995 | * @returns whether c is complete | |
1996 | */ | |
1997 | CEPH_RADOS_API int rados_aio_is_complete_and_cb(rados_completion_t c); | |
1998 | ||
1999 | /** | |
2000 | * Is an asynchronous operation safe and has the callback completed | |
2001 | * | |
2002 | * @param c async operation to inspect | |
2003 | * @returns whether c is safe | |
2004 | */ | |
2005 | CEPH_RADOS_API int rados_aio_is_safe_and_cb(rados_completion_t c); | |
2006 | ||
2007 | /** | |
2008 | * Get the return value of an asychronous operation | |
2009 | * | |
2010 | * The return value is set when the operation is complete or safe, | |
2011 | * whichever comes first. | |
2012 | * | |
2013 | * @pre The operation is safe or complete | |
2014 | * | |
2015 | * @note BUG: complete callback may never be called when the safe | |
2016 | * message is received before the complete message | |
2017 | * | |
2018 | * @param c async operation to inspect | |
2019 | * @returns return value of the operation | |
2020 | */ | |
2021 | CEPH_RADOS_API int rados_aio_get_return_value(rados_completion_t c); | |
2022 | ||
2023 | /** | |
2024 | * Get the internal object version of the target of an asychronous operation | |
2025 | * | |
2026 | * The return value is set when the operation is complete or safe, | |
2027 | * whichever comes first. | |
2028 | * | |
2029 | * @pre The operation is safe or complete | |
2030 | * | |
2031 | * @note BUG: complete callback may never be called when the safe | |
2032 | * message is received before the complete message | |
2033 | * | |
2034 | * @param c async operation to inspect | |
2035 | * @returns version number of the asychronous operation's target | |
2036 | */ | |
2037 | CEPH_RADOS_API uint64_t rados_aio_get_version(rados_completion_t c); | |
2038 | ||
2039 | /** | |
2040 | * Release a completion | |
2041 | * | |
2042 | * Call this when you no longer need the completion. It may not be | |
2043 | * freed immediately if the operation is not acked and committed. | |
2044 | * | |
2045 | * @param c completion to release | |
2046 | */ | |
2047 | CEPH_RADOS_API void rados_aio_release(rados_completion_t c); | |
2048 | ||
2049 | /** | |
2050 | * Write data to an object asynchronously | |
2051 | * | |
2052 | * Queues the write and returns. The return value of the completion | |
2053 | * will be 0 on success, negative error code on failure. | |
2054 | * | |
2055 | * @param io the context in which the write will occur | |
2056 | * @param oid name of the object | |
2057 | * @param completion what to do when the write is safe and complete | |
2058 | * @param buf data to write | |
2059 | * @param len length of the data, in bytes | |
2060 | * @param off byte offset in the object to begin writing at | |
2061 | * @returns 0 on success, -EROFS if the io context specifies a snap_seq | |
2062 | * other than LIBRADOS_SNAP_HEAD | |
2063 | */ | |
2064 | CEPH_RADOS_API int rados_aio_write(rados_ioctx_t io, const char *oid, | |
2065 | rados_completion_t completion, | |
2066 | const char *buf, size_t len, uint64_t off); | |
2067 | ||
2068 | /** | |
11fdf7f2 | 2069 | * Asynchronously append data to an object |
7c673cae FG |
2070 | * |
2071 | * Queues the append and returns. | |
2072 | * | |
2073 | * The return value of the completion will be 0 on success, negative | |
2074 | * error code on failure. | |
2075 | * | |
2076 | * @param io the context to operate in | |
2077 | * @param oid the name of the object | |
2078 | * @param completion what to do when the append is safe and complete | |
2079 | * @param buf the data to append | |
2080 | * @param len length of buf (in bytes) | |
2081 | * @returns 0 on success, -EROFS if the io context specifies a snap_seq | |
2082 | * other than LIBRADOS_SNAP_HEAD | |
2083 | */ | |
2084 | CEPH_RADOS_API int rados_aio_append(rados_ioctx_t io, const char *oid, | |
2085 | rados_completion_t completion, | |
2086 | const char *buf, size_t len); | |
2087 | ||
2088 | /** | |
11fdf7f2 | 2089 | * Asynchronously write an entire object |
7c673cae FG |
2090 | * |
2091 | * The object is filled with the provided data. If the object exists, | |
2092 | * it is atomically truncated and then written. | |
2093 | * Queues the write_full and returns. | |
2094 | * | |
2095 | * The return value of the completion will be 0 on success, negative | |
2096 | * error code on failure. | |
2097 | * | |
2098 | * @param io the io context in which the write will occur | |
2099 | * @param oid name of the object | |
2100 | * @param completion what to do when the write_full is safe and complete | |
2101 | * @param buf data to write | |
2102 | * @param len length of the data, in bytes | |
2103 | * @returns 0 on success, -EROFS if the io context specifies a snap_seq | |
2104 | * other than LIBRADOS_SNAP_HEAD | |
2105 | */ | |
2106 | CEPH_RADOS_API int rados_aio_write_full(rados_ioctx_t io, const char *oid, | |
2107 | rados_completion_t completion, | |
2108 | const char *buf, size_t len); | |
2109 | ||
2110 | /** | |
11fdf7f2 | 2111 | * Asynchronously write the same buffer multiple times |
7c673cae FG |
2112 | * |
2113 | * Queues the writesame and returns. | |
2114 | * | |
2115 | * The return value of the completion will be 0 on success, negative | |
2116 | * error code on failure. | |
2117 | * | |
2118 | * @param io the io context in which the write will occur | |
2119 | * @param oid name of the object | |
2120 | * @param completion what to do when the writesame is safe and complete | |
2121 | * @param buf data to write | |
2122 | * @param data_len length of the data, in bytes | |
2123 | * @param write_len the total number of bytes to write | |
2124 | * @param off byte offset in the object to begin writing at | |
2125 | * @returns 0 on success, -EROFS if the io context specifies a snap_seq | |
2126 | * other than LIBRADOS_SNAP_HEAD | |
2127 | */ | |
2128 | CEPH_RADOS_API int rados_aio_writesame(rados_ioctx_t io, const char *oid, | |
2129 | rados_completion_t completion, | |
2130 | const char *buf, size_t data_len, | |
2131 | size_t write_len, uint64_t off); | |
2132 | ||
2133 | /** | |
11fdf7f2 | 2134 | * Asynchronously remove an object |
7c673cae FG |
2135 | * |
2136 | * Queues the remove and returns. | |
2137 | * | |
2138 | * The return value of the completion will be 0 on success, negative | |
2139 | * error code on failure. | |
2140 | * | |
2141 | * @param io the context to operate in | |
2142 | * @param oid the name of the object | |
2143 | * @param completion what to do when the remove is safe and complete | |
2144 | * @returns 0 on success, -EROFS if the io context specifies a snap_seq | |
2145 | * other than LIBRADOS_SNAP_HEAD | |
2146 | */ | |
2147 | CEPH_RADOS_API int rados_aio_remove(rados_ioctx_t io, const char *oid, | |
2148 | rados_completion_t completion); | |
2149 | ||
2150 | /** | |
11fdf7f2 | 2151 | * Asynchronously read data from an object |
7c673cae FG |
2152 | * |
2153 | * The io context determines the snapshot to read from, if any was set | |
2154 | * by rados_ioctx_snap_set_read(). | |
2155 | * | |
2156 | * The return value of the completion will be number of bytes read on | |
2157 | * success, negative error code on failure. | |
2158 | * | |
2159 | * @note only the 'complete' callback of the completion will be called. | |
2160 | * | |
2161 | * @param io the context in which to perform the read | |
2162 | * @param oid the name of the object to read from | |
2163 | * @param completion what to do when the read is complete | |
2164 | * @param buf where to store the results | |
2165 | * @param len the number of bytes to read | |
2166 | * @param off the offset to start reading from in the object | |
2167 | * @returns 0 on success, negative error code on failure | |
2168 | */ | |
2169 | CEPH_RADOS_API int rados_aio_read(rados_ioctx_t io, const char *oid, | |
2170 | rados_completion_t completion, | |
2171 | char *buf, size_t len, uint64_t off); | |
2172 | ||
2173 | /** | |
2174 | * Block until all pending writes in an io context are safe | |
2175 | * | |
2176 | * This is not equivalent to calling rados_aio_wait_for_safe() on all | |
2177 | * write completions, since this waits for the associated callbacks to | |
2178 | * complete as well. | |
2179 | * | |
2180 | * @note BUG: always returns 0, should be void or accept a timeout | |
2181 | * | |
2182 | * @param io the context to flush | |
2183 | * @returns 0 on success, negative error code on failure | |
2184 | */ | |
2185 | CEPH_RADOS_API int rados_aio_flush(rados_ioctx_t io); | |
2186 | ||
2187 | ||
2188 | /** | |
2189 | * Schedule a callback for when all currently pending | |
2190 | * aio writes are safe. This is a non-blocking version of | |
2191 | * rados_aio_flush(). | |
2192 | * | |
2193 | * @param io the context to flush | |
2194 | * @param completion what to do when the writes are safe | |
2195 | * @returns 0 on success, negative error code on failure | |
2196 | */ | |
2197 | CEPH_RADOS_API int rados_aio_flush_async(rados_ioctx_t io, | |
2198 | rados_completion_t completion); | |
2199 | ||
2200 | ||
2201 | /** | |
2202 | * Asynchronously get object stats (size/mtime) | |
2203 | * | |
2204 | * @param io ioctx | |
2205 | * @param o object name | |
11fdf7f2 | 2206 | * @param completion what to do when the stat is complete |
7c673cae FG |
2207 | * @param psize where to store object size |
2208 | * @param pmtime where to store modification time | |
2209 | * @returns 0 on success, negative error code on failure | |
2210 | */ | |
2211 | CEPH_RADOS_API int rados_aio_stat(rados_ioctx_t io, const char *o, | |
2212 | rados_completion_t completion, | |
2213 | uint64_t *psize, time_t *pmtime); | |
2214 | ||
1e59de90 TL |
2215 | CEPH_RADOS_API int rados_aio_stat2(rados_ioctx_t io, const char *o, |
2216 | rados_completion_t completion, | |
2217 | uint64_t *psize, struct timespec *pmtime); | |
2218 | ||
7c673cae FG |
2219 | /** |
2220 | * Asynchronously compare an on-disk object range with a buffer | |
2221 | * | |
2222 | * @param io the context in which to perform the comparison | |
2223 | * @param o the name of the object to compare with | |
2224 | * @param completion what to do when the comparison is complete | |
2225 | * @param cmp_buf buffer containing bytes to be compared with object contents | |
11fdf7f2 | 2226 | * @param cmp_len length to compare and size of @c cmp_buf in bytes |
7c673cae FG |
2227 | * @param off object byte offset at which to start the comparison |
2228 | * @returns 0 on success, negative error code on failure, | |
2229 | * (-MAX_ERRNO - mismatch_off) on mismatch | |
2230 | */ | |
2231 | CEPH_RADOS_API int rados_aio_cmpext(rados_ioctx_t io, const char *o, | |
2232 | rados_completion_t completion, | |
2233 | const char *cmp_buf, | |
2234 | size_t cmp_len, | |
2235 | uint64_t off); | |
2236 | ||
2237 | /** | |
2238 | * Cancel async operation | |
2239 | * | |
2240 | * @param io ioctx | |
2241 | * @param completion completion handle | |
2242 | * @returns 0 on success, negative error code on failure | |
2243 | */ | |
2244 | CEPH_RADOS_API int rados_aio_cancel(rados_ioctx_t io, | |
2245 | rados_completion_t completion); | |
2246 | ||
2247 | /** | |
2248 | * Asynchronously execute an OSD class method on an object | |
2249 | * | |
2250 | * The OSD has a plugin mechanism for performing complicated | |
2251 | * operations on an object atomically. These plugins are called | |
2252 | * classes. This function allows librados users to call the custom | |
2253 | * methods. The input and output formats are defined by the class. | |
2254 | * Classes in ceph.git can be found in src/cls subdirectories | |
2255 | * | |
2256 | * @param io the context in which to call the method | |
11fdf7f2 TL |
2257 | * @param o name of the object |
2258 | * @param completion what to do when the exec completes | |
7c673cae FG |
2259 | * @param cls the name of the class |
2260 | * @param method the name of the method | |
2261 | * @param in_buf where to find input | |
2262 | * @param in_len length of in_buf in bytes | |
2263 | * @param buf where to store output | |
2264 | * @param out_len length of buf in bytes | |
2265 | * @returns 0 on success, negative error code on failure | |
2266 | */ | |
2267 | CEPH_RADOS_API int rados_aio_exec(rados_ioctx_t io, const char *o, | |
2268 | rados_completion_t completion, | |
2269 | const char *cls, const char *method, | |
2270 | const char *in_buf, size_t in_len, | |
2271 | char *buf, size_t out_len); | |
2272 | ||
2273 | /** @} Asynchronous I/O */ | |
2274 | ||
2275 | /** | |
2276 | * @name Asynchronous Xattrs | |
2277 | * Extended attributes are stored as extended attributes on the files | |
2278 | * representing an object on the OSDs. Thus, they have the same | |
2279 | * limitations as the underlying filesystem. On ext4, this means that | |
2280 | * the total data stored in xattrs cannot exceed 4KB. | |
2281 | * | |
2282 | * @{ | |
2283 | */ | |
2284 | ||
2285 | /** | |
2286 | * Asynchronously get the value of an extended attribute on an object. | |
2287 | * | |
2288 | * @param io the context in which the attribute is read | |
2289 | * @param o name of the object | |
2290 | * @param completion what to do when the getxattr completes | |
2291 | * @param name which extended attribute to read | |
2292 | * @param buf where to store the result | |
2293 | * @param len size of buf in bytes | |
2294 | * @returns length of xattr value on success, negative error code on failure | |
2295 | */ | |
2296 | CEPH_RADOS_API int rados_aio_getxattr(rados_ioctx_t io, const char *o, | |
2297 | rados_completion_t completion, | |
2298 | const char *name, char *buf, size_t len); | |
2299 | ||
2300 | /** | |
2301 | * Asynchronously set an extended attribute on an object. | |
2302 | * | |
2303 | * @param io the context in which xattr is set | |
2304 | * @param o name of the object | |
2305 | * @param completion what to do when the setxattr completes | |
2306 | * @param name which extended attribute to set | |
2307 | * @param buf what to store in the xattr | |
2308 | * @param len the number of bytes in buf | |
2309 | * @returns 0 on success, negative error code on failure | |
2310 | */ | |
2311 | CEPH_RADOS_API int rados_aio_setxattr(rados_ioctx_t io, const char *o, | |
2312 | rados_completion_t completion, | |
2313 | const char *name, const char *buf, | |
2314 | size_t len); | |
2315 | ||
2316 | /** | |
2317 | * Asynchronously delete an extended attribute from an object. | |
2318 | * | |
2319 | * @param io the context in which to delete the xattr | |
2320 | * @param o the name of the object | |
2321 | * @param completion what to do when the rmxattr completes | |
2322 | * @param name which xattr to delete | |
2323 | * @returns 0 on success, negative error code on failure | |
2324 | */ | |
2325 | CEPH_RADOS_API int rados_aio_rmxattr(rados_ioctx_t io, const char *o, | |
2326 | rados_completion_t completion, | |
2327 | const char *name); | |
2328 | ||
2329 | /** | |
2330 | * Asynchronously start iterating over xattrs on an object. | |
2331 | * | |
2332 | * @post iter is a valid iterator | |
2333 | * | |
2334 | * @param io the context in which to list xattrs | |
2335 | * @param oid name of the object | |
11fdf7f2 | 2336 | * @param completion what to do when the getxattrs completes |
7c673cae FG |
2337 | * @param iter where to store the iterator |
2338 | * @returns 0 on success, negative error code on failure | |
2339 | */ | |
2340 | CEPH_RADOS_API int rados_aio_getxattrs(rados_ioctx_t io, const char *oid, | |
2341 | rados_completion_t completion, | |
2342 | rados_xattrs_iter_t *iter); | |
2343 | ||
2344 | /** @} Asynchronous Xattrs */ | |
2345 | ||
2346 | /** | |
2347 | * @name Watch/Notify | |
2348 | * | |
2349 | * Watch/notify is a protocol to help communicate among clients. It | |
2350 | * can be used to sychronize client state. All that's needed is a | |
2351 | * well-known object name (for example, rbd uses the header object of | |
2352 | * an image). | |
2353 | * | |
2354 | * Watchers register an interest in an object, and receive all | |
2355 | * notifies on that object. A notify attempts to communicate with all | |
2356 | * clients watching an object, and blocks on the notifier until each | |
2357 | * client responds or a timeout is reached. | |
2358 | * | |
2359 | * See rados_watch() and rados_notify() for more details. | |
2360 | * | |
2361 | * @{ | |
2362 | */ | |
2363 | ||
2364 | /** | |
2365 | * @typedef rados_watchcb_t | |
2366 | * | |
2367 | * Callback activated when a notify is received on a watched | |
2368 | * object. | |
2369 | * | |
2370 | * @param opcode undefined | |
2371 | * @param ver version of the watched object | |
2372 | * @param arg application-specific data | |
2373 | * | |
2374 | * @note BUG: opcode is an internal detail that shouldn't be exposed | |
2375 | * @note BUG: ver is unused | |
2376 | */ | |
2377 | typedef void (*rados_watchcb_t)(uint8_t opcode, uint64_t ver, void *arg); | |
2378 | ||
2379 | /** | |
2380 | * @typedef rados_watchcb2_t | |
2381 | * | |
2382 | * Callback activated when a notify is received on a watched | |
2383 | * object. | |
2384 | * | |
2385 | * @param arg opaque user-defined value provided to rados_watch2() | |
2386 | * @param notify_id an id for this notify event | |
2387 | * @param handle the watcher handle we are notifying | |
2388 | * @param notifier_id the unique client id for the notifier | |
2389 | * @param data payload from the notifier | |
20effc67 | 2390 | * @param data_len length of payload buffer |
7c673cae FG |
2391 | */ |
2392 | typedef void (*rados_watchcb2_t)(void *arg, | |
2393 | uint64_t notify_id, | |
2394 | uint64_t handle, | |
2395 | uint64_t notifier_id, | |
2396 | void *data, | |
2397 | size_t data_len); | |
2398 | ||
2399 | /** | |
2400 | * @typedef rados_watcherrcb_t | |
2401 | * | |
2402 | * Callback activated when we encounter an error with the watch session. | |
2403 | * This can happen when the location of the objects moves within the | |
2404 | * cluster and we fail to register our watch with the new object location, | |
2405 | * or when our connection with the object OSD is otherwise interrupted and | |
2406 | * we may have missed notify events. | |
2407 | * | |
2408 | * @param pre opaque user-defined value provided to rados_watch2() | |
20effc67 | 2409 | * @param cookie the internal id assigned to the watch session |
7c673cae FG |
2410 | * @param err error code |
2411 | */ | |
2412 | typedef void (*rados_watcherrcb_t)(void *pre, uint64_t cookie, int err); | |
2413 | ||
2414 | /** | |
2415 | * Register an interest in an object | |
2416 | * | |
2417 | * A watch operation registers the client as being interested in | |
2418 | * notifications on an object. OSDs keep track of watches on | |
2419 | * persistent storage, so they are preserved across cluster changes by | |
2420 | * the normal recovery process. If the client loses its connection to | |
2421 | * the primary OSD for a watched object, the watch will be removed | |
2422 | * after 30 seconds. Watches are automatically reestablished when a new | |
2423 | * connection is made, or a placement group switches OSDs. | |
2424 | * | |
2425 | * @note BUG: librados should provide a way for watchers to notice connection resets | |
2426 | * @note BUG: the ver parameter does not work, and -ERANGE will never be returned | |
2427 | * (See URL tracker.ceph.com/issues/2592) | |
2428 | * | |
2429 | * @param io the pool the object is in | |
2430 | * @param o the object to watch | |
2431 | * @param ver expected version of the object | |
2432 | * @param cookie where to store the internal id assigned to this watch | |
2433 | * @param watchcb what to do when a notify is received on this object | |
2434 | * @param arg application defined data to pass when watchcb is called | |
2435 | * @returns 0 on success, negative error code on failure | |
2436 | * @returns -ERANGE if the version of the object is greater than ver | |
2437 | */ | |
2438 | CEPH_RADOS_API int rados_watch(rados_ioctx_t io, const char *o, uint64_t ver, | |
2439 | uint64_t *cookie, | |
2440 | rados_watchcb_t watchcb, void *arg) | |
2441 | __attribute__((deprecated)); | |
2442 | ||
2443 | ||
2444 | /** | |
2445 | * Register an interest in an object | |
2446 | * | |
2447 | * A watch operation registers the client as being interested in | |
2448 | * notifications on an object. OSDs keep track of watches on | |
2449 | * persistent storage, so they are preserved across cluster changes by | |
2450 | * the normal recovery process. If the client loses its connection to the | |
2451 | * primary OSD for a watched object, the watch will be removed after | |
2452 | * a timeout configured with osd_client_watch_timeout. | |
2453 | * Watches are automatically reestablished when a new | |
2454 | * connection is made, or a placement group switches OSDs. | |
2455 | * | |
2456 | * @param io the pool the object is in | |
2457 | * @param o the object to watch | |
2458 | * @param cookie where to store the internal id assigned to this watch | |
2459 | * @param watchcb what to do when a notify is received on this object | |
2460 | * @param watcherrcb what to do when the watch session encounters an error | |
2461 | * @param arg opaque value to pass to the callback | |
2462 | * @returns 0 on success, negative error code on failure | |
2463 | */ | |
2464 | CEPH_RADOS_API int rados_watch2(rados_ioctx_t io, const char *o, uint64_t *cookie, | |
2465 | rados_watchcb2_t watchcb, | |
2466 | rados_watcherrcb_t watcherrcb, | |
2467 | void *arg); | |
2468 | ||
2469 | /** | |
2470 | * Register an interest in an object | |
2471 | * | |
2472 | * A watch operation registers the client as being interested in | |
2473 | * notifications on an object. OSDs keep track of watches on | |
2474 | * persistent storage, so they are preserved across cluster changes by | |
2475 | * the normal recovery process. Watches are automatically reestablished when a new | |
2476 | * connection is made, or a placement group switches OSDs. | |
2477 | * | |
2478 | * @param io the pool the object is in | |
2479 | * @param o the object to watch | |
2480 | * @param cookie where to store the internal id assigned to this watch | |
2481 | * @param watchcb what to do when a notify is received on this object | |
2482 | * @param watcherrcb what to do when the watch session encounters an error | |
2483 | * @param timeout how many seconds the connection will keep after disconnection | |
2484 | * @param arg opaque value to pass to the callback | |
2485 | * @returns 0 on success, negative error code on failure | |
2486 | */ | |
2487 | CEPH_RADOS_API int rados_watch3(rados_ioctx_t io, const char *o, uint64_t *cookie, | |
2488 | rados_watchcb2_t watchcb, | |
2489 | rados_watcherrcb_t watcherrcb, | |
2490 | uint32_t timeout, | |
2491 | void *arg); | |
2492 | ||
2493 | /** | |
2494 | * Asynchronous register an interest in an object | |
2495 | * | |
2496 | * A watch operation registers the client as being interested in | |
2497 | * notifications on an object. OSDs keep track of watches on | |
2498 | * persistent storage, so they are preserved across cluster changes by | |
2499 | * the normal recovery process. If the client loses its connection to | |
2500 | * the primary OSD for a watched object, the watch will be removed | |
2501 | * after 30 seconds. Watches are automatically reestablished when a new | |
2502 | * connection is made, or a placement group switches OSDs. | |
2503 | * | |
2504 | * @param io the pool the object is in | |
2505 | * @param o the object to watch | |
2506 | * @param completion what to do when operation has been attempted | |
2507 | * @param handle where to store the internal id assigned to this watch | |
2508 | * @param watchcb what to do when a notify is received on this object | |
2509 | * @param watcherrcb what to do when the watch session encounters an error | |
2510 | * @param arg opaque value to pass to the callback | |
2511 | * @returns 0 on success, negative error code on failure | |
2512 | */ | |
2513 | CEPH_RADOS_API int rados_aio_watch(rados_ioctx_t io, const char *o, | |
2514 | rados_completion_t completion, uint64_t *handle, | |
2515 | rados_watchcb2_t watchcb, | |
2516 | rados_watcherrcb_t watcherrcb, | |
2517 | void *arg); | |
2518 | ||
2519 | /** | |
2520 | * Asynchronous register an interest in an object | |
2521 | * | |
2522 | * A watch operation registers the client as being interested in | |
2523 | * notifications on an object. OSDs keep track of watches on | |
2524 | * persistent storage, so they are preserved across cluster changes by | |
2525 | * the normal recovery process. If the client loses its connection to | |
2526 | * the primary OSD for a watched object, the watch will be removed | |
2527 | * after the number of seconds that configured in timeout parameter. | |
2528 | * Watches are automatically reestablished when a new | |
2529 | * connection is made, or a placement group switches OSDs. | |
2530 | * | |
2531 | * @param io the pool the object is in | |
2532 | * @param o the object to watch | |
2533 | * @param completion what to do when operation has been attempted | |
2534 | * @param handle where to store the internal id assigned to this watch | |
2535 | * @param watchcb what to do when a notify is received on this object | |
2536 | * @param watcherrcb what to do when the watch session encounters an error | |
2537 | * @param timeout how many seconds the connection will keep after disconnection | |
2538 | * @param arg opaque value to pass to the callback | |
2539 | * @returns 0 on success, negative error code on failure | |
2540 | */ | |
2541 | CEPH_RADOS_API int rados_aio_watch2(rados_ioctx_t io, const char *o, | |
2542 | rados_completion_t completion, uint64_t *handle, | |
2543 | rados_watchcb2_t watchcb, | |
2544 | rados_watcherrcb_t watcherrcb, | |
2545 | uint32_t timeout, | |
2546 | void *arg); | |
2547 | ||
2548 | /** | |
2549 | * Check on the status of a watch | |
2550 | * | |
2551 | * Return the number of milliseconds since the watch was last confirmed. | |
2552 | * Or, if there has been an error, return that. | |
2553 | * | |
2554 | * If there is an error, the watch is no longer valid, and should be | |
2555 | * destroyed with rados_unwatch2(). The the user is still interested | |
2556 | * in the object, a new watch should be created with rados_watch2(). | |
2557 | * | |
2558 | * @param io the pool the object is in | |
2559 | * @param cookie the watch handle | |
2560 | * @returns ms since last confirmed on success, negative error code on failure | |
2561 | */ | |
2562 | CEPH_RADOS_API int rados_watch_check(rados_ioctx_t io, uint64_t cookie); | |
2563 | ||
2564 | /** | |
2565 | * Unregister an interest in an object | |
2566 | * | |
2567 | * Once this completes, no more notifies will be sent to us for this | |
2568 | * watch. This should be called to clean up unneeded watchers. | |
2569 | * | |
2570 | * @param io the pool the object is in | |
2571 | * @param o the name of the watched object (ignored) | |
2572 | * @param cookie which watch to unregister | |
2573 | * @returns 0 on success, negative error code on failure | |
2574 | */ | |
2575 | CEPH_RADOS_API int rados_unwatch(rados_ioctx_t io, const char *o, uint64_t cookie) | |
2576 | __attribute__((deprecated)); | |
2577 | ||
2578 | /** | |
2579 | * Unregister an interest in an object | |
2580 | * | |
2581 | * Once this completes, no more notifies will be sent to us for this | |
2582 | * watch. This should be called to clean up unneeded watchers. | |
2583 | * | |
2584 | * @param io the pool the object is in | |
2585 | * @param cookie which watch to unregister | |
2586 | * @returns 0 on success, negative error code on failure | |
2587 | */ | |
2588 | CEPH_RADOS_API int rados_unwatch2(rados_ioctx_t io, uint64_t cookie); | |
2589 | ||
2590 | /** | |
2591 | * Asynchronous unregister an interest in an object | |
2592 | * | |
2593 | * Once this completes, no more notifies will be sent to us for this | |
2594 | * watch. This should be called to clean up unneeded watchers. | |
2595 | * | |
2596 | * @param io the pool the object is in | |
2597 | * @param completion what to do when operation has been attempted | |
2598 | * @param cookie which watch to unregister | |
2599 | * @returns 0 on success, negative error code on failure | |
2600 | */ | |
2601 | CEPH_RADOS_API int rados_aio_unwatch(rados_ioctx_t io, uint64_t cookie, | |
2602 | rados_completion_t completion); | |
2603 | ||
2604 | /** | |
2605 | * Sychronously notify watchers of an object | |
2606 | * | |
2607 | * This blocks until all watchers of the object have received and | |
2608 | * reacted to the notify, or a timeout is reached. | |
2609 | * | |
2610 | * @note BUG: the timeout is not changeable via the C API | |
2611 | * @note BUG: the bufferlist is inaccessible in a rados_watchcb_t | |
2612 | * | |
2613 | * @param io the pool the object is in | |
2614 | * @param o the name of the object | |
2615 | * @param ver obsolete - just pass zero | |
2616 | * @param buf data to send to watchers | |
2617 | * @param buf_len length of buf in bytes | |
2618 | * @returns 0 on success, negative error code on failure | |
2619 | */ | |
2620 | CEPH_RADOS_API int rados_notify(rados_ioctx_t io, const char *o, uint64_t ver, | |
2621 | const char *buf, int buf_len) | |
2622 | __attribute__((deprecated)); | |
2623 | ||
2624 | /** | |
2625 | * Sychronously notify watchers of an object | |
2626 | * | |
2627 | * This blocks until all watchers of the object have received and | |
2628 | * reacted to the notify, or a timeout is reached. | |
2629 | * | |
2630 | * The reply buffer is optional. If specified, the client will get | |
2631 | * back an encoded buffer that includes the ids of the clients that | |
2632 | * acknowledged the notify as well as their notify ack payloads (if | |
2633 | * any). Clients that timed out are not included. Even clients that | |
2634 | * do not include a notify ack payload are included in the list but | |
2635 | * have a 0-length payload associated with them. The format: | |
2636 | * | |
2637 | * le32 num_acks | |
2638 | * { | |
2639 | * le64 gid global id for the client (for client.1234 that's 1234) | |
2640 | * le64 cookie cookie for the client | |
2641 | * le32 buflen length of reply message buffer | |
2642 | * u8 * buflen payload | |
2643 | * } * num_acks | |
2644 | * le32 num_timeouts | |
2645 | * { | |
2646 | * le64 gid global id for the client | |
2647 | * le64 cookie cookie for the client | |
2648 | * } * num_timeouts | |
2649 | * | |
2650 | * Note: There may be multiple instances of the same gid if there are | |
2651 | * multiple watchers registered via the same client. | |
2652 | * | |
2653 | * Note: The buffer must be released with rados_buffer_free() when the | |
2654 | * user is done with it. | |
2655 | * | |
2656 | * Note: Since the result buffer includes clients that time out, it | |
2657 | * will be set even when rados_notify() returns an error code (like | |
2658 | * -ETIMEDOUT). | |
2659 | * | |
2660 | * @param io the pool the object is in | |
2661 | * @param completion what to do when operation has been attempted | |
2662 | * @param o the name of the object | |
2663 | * @param buf data to send to watchers | |
2664 | * @param buf_len length of buf in bytes | |
2665 | * @param timeout_ms notify timeout (in ms) | |
2666 | * @param reply_buffer pointer to reply buffer pointer (free with rados_buffer_free) | |
2667 | * @param reply_buffer_len pointer to size of reply buffer | |
2668 | * @returns 0 on success, negative error code on failure | |
2669 | */ | |
11fdf7f2 TL |
2670 | CEPH_RADOS_API int rados_aio_notify(rados_ioctx_t io, const char *o, |
2671 | rados_completion_t completion, | |
2672 | const char *buf, int buf_len, | |
2673 | uint64_t timeout_ms, char **reply_buffer, | |
2674 | size_t *reply_buffer_len); | |
7c673cae FG |
2675 | CEPH_RADOS_API int rados_notify2(rados_ioctx_t io, const char *o, |
2676 | const char *buf, int buf_len, | |
2677 | uint64_t timeout_ms, | |
2678 | char **reply_buffer, size_t *reply_buffer_len); | |
7c673cae | 2679 | |
f67539c2 TL |
2680 | /** |
2681 | * Decode a notify response | |
2682 | * | |
2683 | * Decode a notify response (from rados_aio_notify() call) into acks and | |
2684 | * timeout arrays. | |
2685 | * | |
2686 | * @param reply_buffer buffer from rados_aio_notify() call | |
2687 | * @param reply_buffer_len reply_buffer length | |
2688 | * @param acks pointer to struct notify_ack_t pointer | |
2689 | * @param nr_acks pointer to ack count | |
2690 | * @param timeouts pointer to notify_timeout_t pointer | |
2691 | * @param nr_timeouts pointer to timeout count | |
2692 | * @returns 0 on success | |
2693 | */ | |
2694 | CEPH_RADOS_API int rados_decode_notify_response(char *reply_buffer, size_t reply_buffer_len, | |
2695 | struct notify_ack_t **acks, size_t *nr_acks, | |
2696 | struct notify_timeout_t **timeouts, size_t *nr_timeouts); | |
2697 | ||
2698 | /** | |
2699 | * Free notify allocated buffer | |
2700 | * | |
2701 | * Release memory allocated by rados_decode_notify_response() call | |
2702 | * | |
2703 | * @param acks notify_ack_t struct (from rados_decode_notify_response()) | |
2704 | * @param nr_acks ack count | |
2705 | * @param timeouts notify_timeout_t struct (from rados_decode_notify_response()) | |
2706 | */ | |
2707 | CEPH_RADOS_API void rados_free_notify_response(struct notify_ack_t *acks, size_t nr_acks, | |
2708 | struct notify_timeout_t *timeouts); | |
2709 | ||
7c673cae FG |
2710 | /** |
2711 | * Acknolwedge receipt of a notify | |
2712 | * | |
2713 | * @param io the pool the object is in | |
2714 | * @param o the name of the object | |
2715 | * @param notify_id the notify_id we got on the watchcb2_t callback | |
2716 | * @param cookie the watcher handle | |
2717 | * @param buf payload to return to notifier (optional) | |
2718 | * @param buf_len payload length | |
2719 | * @returns 0 on success | |
2720 | */ | |
2721 | CEPH_RADOS_API int rados_notify_ack(rados_ioctx_t io, const char *o, | |
2722 | uint64_t notify_id, uint64_t cookie, | |
2723 | const char *buf, int buf_len); | |
2724 | ||
2725 | /** | |
2726 | * Flush watch/notify callbacks | |
2727 | * | |
2728 | * This call will block until all pending watch/notify callbacks have | |
2729 | * been executed and the queue is empty. It should usually be called | |
2730 | * after shutting down any watches before shutting down the ioctx or | |
2731 | * librados to ensure that any callbacks do not misuse the ioctx (for | |
2732 | * example by calling rados_notify_ack after the ioctx has been | |
2733 | * destroyed). | |
2734 | * | |
2735 | * @param cluster the cluster handle | |
2736 | */ | |
2737 | CEPH_RADOS_API int rados_watch_flush(rados_t cluster); | |
2738 | /** | |
2739 | * Flush watch/notify callbacks | |
2740 | * | |
2741 | * This call will be nonblock, and the completion will be called | |
2742 | * until all pending watch/notify callbacks have been executed and | |
2743 | * the queue is empty. It should usually be called after shutting | |
2744 | * down any watches before shutting down the ioctx or | |
2745 | * librados to ensure that any callbacks do not misuse the ioctx (for | |
2746 | * example by calling rados_notify_ack after the ioctx has been | |
2747 | * destroyed). | |
2748 | * | |
2749 | * @param cluster the cluster handle | |
2750 | * @param completion what to do when operation has been attempted | |
2751 | */ | |
2752 | CEPH_RADOS_API int rados_aio_watch_flush(rados_t cluster, rados_completion_t completion); | |
2753 | ||
2754 | /** @} Watch/Notify */ | |
2755 | ||
2756 | /** | |
2757 | * Pin an object in the cache tier | |
2758 | * | |
2759 | * When an object is pinned in the cache tier, it stays in the cache | |
2760 | * tier, and won't be flushed out. | |
2761 | * | |
2762 | * @param io the pool the object is in | |
2763 | * @param o the object id | |
2764 | * @returns 0 on success, negative error code on failure | |
2765 | */ | |
2766 | CEPH_RADOS_API int rados_cache_pin(rados_ioctx_t io, const char *o); | |
2767 | ||
2768 | /** | |
2769 | * Unpin an object in the cache tier | |
2770 | * | |
2771 | * After an object is unpinned in the cache tier, it can be flushed out | |
2772 | * | |
2773 | * @param io the pool the object is in | |
2774 | * @param o the object id | |
2775 | * @returns 0 on success, negative error code on failure | |
2776 | */ | |
2777 | CEPH_RADOS_API int rados_cache_unpin(rados_ioctx_t io, const char *o); | |
2778 | ||
2779 | /** | |
2780 | * @name Hints | |
2781 | * | |
2782 | * @{ | |
2783 | */ | |
2784 | ||
2785 | /** | |
2786 | * Set allocation hint for an object | |
2787 | * | |
2788 | * This is an advisory operation, it will always succeed (as if it was | |
2789 | * submitted with a LIBRADOS_OP_FLAG_FAILOK flag set) and is not | |
2790 | * guaranteed to do anything on the backend. | |
2791 | * | |
2792 | * @param io the pool the object is in | |
2793 | * @param o the name of the object | |
2794 | * @param expected_object_size expected size of the object, in bytes | |
2795 | * @param expected_write_size expected size of writes to the object, in bytes | |
2796 | * @returns 0 on success, negative error code on failure | |
2797 | */ | |
2798 | CEPH_RADOS_API int rados_set_alloc_hint(rados_ioctx_t io, const char *o, | |
2799 | uint64_t expected_object_size, | |
2800 | uint64_t expected_write_size); | |
2801 | ||
2802 | /** | |
2803 | * Set allocation hint for an object | |
2804 | * | |
2805 | * This is an advisory operation, it will always succeed (as if it was | |
2806 | * submitted with a LIBRADOS_OP_FLAG_FAILOK flag set) and is not | |
2807 | * guaranteed to do anything on the backend. | |
2808 | * | |
2809 | * @param io the pool the object is in | |
2810 | * @param o the name of the object | |
2811 | * @param expected_object_size expected size of the object, in bytes | |
2812 | * @param expected_write_size expected size of writes to the object, in bytes | |
2813 | * @param flags hints about future IO patterns | |
2814 | * @returns 0 on success, negative error code on failure | |
2815 | */ | |
2816 | CEPH_RADOS_API int rados_set_alloc_hint2(rados_ioctx_t io, const char *o, | |
2817 | uint64_t expected_object_size, | |
2818 | uint64_t expected_write_size, | |
2819 | uint32_t flags); | |
2820 | ||
2821 | /** @} Hints */ | |
2822 | ||
2823 | /** | |
2824 | * @name Object Operations | |
2825 | * | |
2826 | * A single rados operation can do multiple operations on one object | |
11fdf7f2 | 2827 | * atomically. The whole operation will succeed or fail, and no partial |
7c673cae FG |
2828 | * results will be visible. |
2829 | * | |
2830 | * Operations may be either reads, which can return data, or writes, | |
2831 | * which cannot. The effects of writes are applied and visible all at | |
2832 | * once, so an operation that sets an xattr and then checks its value | |
2833 | * will not see the updated value. | |
2834 | * | |
2835 | * @{ | |
2836 | */ | |
2837 | ||
2838 | /** | |
2839 | * Create a new rados_write_op_t write operation. This will store all actions | |
2840 | * to be performed atomically. You must call rados_release_write_op when you are | |
2841 | * finished with it. | |
2842 | * | |
f67539c2 TL |
2843 | * @note the ownership of a write operartion is passed to the function |
2844 | * performing the operation, so the same instance of @c rados_write_op_t | |
2845 | * cannot be used again after being performed. | |
2846 | * | |
7c673cae FG |
2847 | * @returns non-NULL on success, NULL on memory allocation error. |
2848 | */ | |
2849 | CEPH_RADOS_API rados_write_op_t rados_create_write_op(void); | |
2850 | ||
2851 | /** | |
2852 | * Free a rados_write_op_t, must be called when you're done with it. | |
2853 | * @param write_op operation to deallocate, created with rados_create_write_op | |
2854 | */ | |
2855 | CEPH_RADOS_API void rados_release_write_op(rados_write_op_t write_op); | |
2856 | ||
2857 | /** | |
2858 | * Set flags for the last operation added to this write_op. | |
2859 | * At least one op must have been added to the write_op. | |
11fdf7f2 | 2860 | * @param write_op operation to add this action to |
7c673cae FG |
2861 | * @param flags see librados.h constants beginning with LIBRADOS_OP_FLAG |
2862 | */ | |
2863 | CEPH_RADOS_API void rados_write_op_set_flags(rados_write_op_t write_op, | |
2864 | int flags); | |
2865 | ||
2866 | /** | |
2867 | * Ensure that the object exists before writing | |
2868 | * @param write_op operation to add this action to | |
2869 | */ | |
2870 | CEPH_RADOS_API void rados_write_op_assert_exists(rados_write_op_t write_op); | |
2871 | ||
2872 | /** | |
2873 | * Ensure that the object exists and that its internal version | |
2874 | * number is equal to "ver" before writing. "ver" should be a | |
2875 | * version number previously obtained with rados_get_last_version(). | |
2876 | * - If the object's version is greater than the asserted version | |
2877 | * then rados_write_op_operate will return -ERANGE instead of | |
2878 | * executing the op. | |
2879 | * - If the object's version is less than the asserted version | |
2880 | * then rados_write_op_operate will return -EOVERFLOW instead | |
2881 | * of executing the op. | |
2882 | * @param write_op operation to add this action to | |
2883 | * @param ver object version number | |
2884 | */ | |
2885 | CEPH_RADOS_API void rados_write_op_assert_version(rados_write_op_t write_op, uint64_t ver); | |
2886 | ||
2887 | /** | |
2888 | * Ensure that given object range (extent) satisfies comparison. | |
2889 | * | |
2890 | * @param write_op operation to add this action to | |
2891 | * @param cmp_buf buffer containing bytes to be compared with object contents | |
11fdf7f2 | 2892 | * @param cmp_len length to compare and size of @c cmp_buf in bytes |
7c673cae FG |
2893 | * @param off object byte offset at which to start the comparison |
2894 | * @param prval returned result of comparison, 0 on success, negative error code | |
2895 | * on failure, (-MAX_ERRNO - mismatch_off) on mismatch | |
2896 | */ | |
2897 | CEPH_RADOS_API void rados_write_op_cmpext(rados_write_op_t write_op, | |
2898 | const char *cmp_buf, | |
2899 | size_t cmp_len, | |
2900 | uint64_t off, | |
2901 | int *prval); | |
2902 | ||
2903 | /** | |
2904 | * Ensure that given xattr satisfies comparison. | |
2905 | * If the comparison is not satisfied, the return code of the | |
2906 | * operation will be -ECANCELED | |
2907 | * @param write_op operation to add this action to | |
2908 | * @param name name of the xattr to look up | |
2909 | * @param comparison_operator currently undocumented, look for | |
2910 | * LIBRADOS_CMPXATTR_OP_EQ in librados.h | |
2911 | * @param value buffer to compare actual xattr value to | |
2912 | * @param value_len length of buffer to compare actual xattr value to | |
2913 | */ | |
2914 | CEPH_RADOS_API void rados_write_op_cmpxattr(rados_write_op_t write_op, | |
2915 | const char *name, | |
2916 | uint8_t comparison_operator, | |
2917 | const char *value, | |
2918 | size_t value_len); | |
2919 | ||
2920 | /** | |
2921 | * Ensure that the an omap value satisfies a comparison, | |
2922 | * with the supplied value on the right hand side (i.e. | |
2923 | * for OP_LT, the comparison is actual_value < value. | |
2924 | * | |
2925 | * @param write_op operation to add this action to | |
2926 | * @param key which omap value to compare | |
2927 | * @param comparison_operator one of LIBRADOS_CMPXATTR_OP_EQ, | |
2928 | LIBRADOS_CMPXATTR_OP_LT, or LIBRADOS_CMPXATTR_OP_GT | |
2929 | * @param val value to compare with | |
2930 | * @param val_len length of value in bytes | |
2931 | * @param prval where to store the return value from this action | |
2932 | */ | |
2933 | CEPH_RADOS_API void rados_write_op_omap_cmp(rados_write_op_t write_op, | |
11fdf7f2 TL |
2934 | const char *key, |
2935 | uint8_t comparison_operator, | |
2936 | const char *val, | |
2937 | size_t val_len, | |
2938 | int *prval); | |
2939 | ||
2940 | /** | |
2941 | * Ensure that the an omap value satisfies a comparison, | |
2942 | * with the supplied value on the right hand side (i.e. | |
2943 | * for OP_LT, the comparison is actual_value < value. | |
2944 | * | |
2945 | * @param write_op operation to add this action to | |
2946 | * @param key which omap value to compare | |
2947 | * @param comparison_operator one of LIBRADOS_CMPXATTR_OP_EQ, | |
2948 | LIBRADOS_CMPXATTR_OP_LT, or LIBRADOS_CMPXATTR_OP_GT | |
2949 | * @param val value to compare with | |
2950 | * @param key_len length of key in bytes | |
2951 | * @param val_len length of value in bytes | |
2952 | * @param prval where to store the return value from this action | |
2953 | */ | |
2954 | CEPH_RADOS_API void rados_write_op_omap_cmp2(rados_write_op_t write_op, | |
2955 | const char *key, | |
2956 | uint8_t comparison_operator, | |
2957 | const char *val, | |
2958 | size_t key_len, | |
2959 | size_t val_len, | |
2960 | int *prval); | |
7c673cae FG |
2961 | |
2962 | /** | |
2963 | * Set an xattr | |
2964 | * @param write_op operation to add this action to | |
2965 | * @param name name of the xattr | |
2966 | * @param value buffer to set xattr to | |
2967 | * @param value_len length of buffer to set xattr to | |
2968 | */ | |
2969 | CEPH_RADOS_API void rados_write_op_setxattr(rados_write_op_t write_op, | |
2970 | const char *name, | |
2971 | const char *value, | |
2972 | size_t value_len); | |
2973 | ||
2974 | /** | |
2975 | * Remove an xattr | |
2976 | * @param write_op operation to add this action to | |
2977 | * @param name name of the xattr to remove | |
2978 | */ | |
2979 | CEPH_RADOS_API void rados_write_op_rmxattr(rados_write_op_t write_op, | |
2980 | const char *name); | |
2981 | ||
2982 | /** | |
2983 | * Create the object | |
2984 | * @param write_op operation to add this action to | |
2985 | * @param exclusive set to either LIBRADOS_CREATE_EXCLUSIVE or | |
2986 | LIBRADOS_CREATE_IDEMPOTENT | |
2987 | * will error if the object already exists. | |
2988 | * @param category category string (DEPRECATED, HAS NO EFFECT) | |
2989 | */ | |
2990 | CEPH_RADOS_API void rados_write_op_create(rados_write_op_t write_op, | |
2991 | int exclusive, | |
2992 | const char* category); | |
2993 | ||
2994 | /** | |
2995 | * Write to offset | |
2996 | * @param write_op operation to add this action to | |
2997 | * @param offset offset to write to | |
2998 | * @param buffer bytes to write | |
2999 | * @param len length of buffer | |
3000 | */ | |
3001 | CEPH_RADOS_API void rados_write_op_write(rados_write_op_t write_op, | |
3002 | const char *buffer, | |
3003 | size_t len, | |
3004 | uint64_t offset); | |
3005 | ||
3006 | /** | |
3007 | * Write whole object, atomically replacing it. | |
3008 | * @param write_op operation to add this action to | |
3009 | * @param buffer bytes to write | |
3010 | * @param len length of buffer | |
3011 | */ | |
3012 | CEPH_RADOS_API void rados_write_op_write_full(rados_write_op_t write_op, | |
3013 | const char *buffer, | |
3014 | size_t len); | |
3015 | ||
3016 | /** | |
3017 | * Write the same buffer multiple times | |
3018 | * @param write_op operation to add this action to | |
3019 | * @param buffer bytes to write | |
3020 | * @param data_len length of buffer | |
11fdf7f2 | 3021 | * @param write_len total number of bytes to write, as a multiple of @c data_len |
7c673cae FG |
3022 | * @param offset offset to write to |
3023 | */ | |
3024 | CEPH_RADOS_API void rados_write_op_writesame(rados_write_op_t write_op, | |
3025 | const char *buffer, | |
3026 | size_t data_len, | |
3027 | size_t write_len, | |
3028 | uint64_t offset); | |
3029 | ||
3030 | /** | |
3031 | * Append to end of object. | |
3032 | * @param write_op operation to add this action to | |
3033 | * @param buffer bytes to write | |
3034 | * @param len length of buffer | |
3035 | */ | |
3036 | CEPH_RADOS_API void rados_write_op_append(rados_write_op_t write_op, | |
3037 | const char *buffer, | |
3038 | size_t len); | |
3039 | /** | |
3040 | * Remove object | |
3041 | * @param write_op operation to add this action to | |
3042 | */ | |
3043 | CEPH_RADOS_API void rados_write_op_remove(rados_write_op_t write_op); | |
3044 | ||
3045 | /** | |
3046 | * Truncate an object | |
3047 | * @param write_op operation to add this action to | |
3048 | * @param offset Offset to truncate to | |
3049 | */ | |
3050 | CEPH_RADOS_API void rados_write_op_truncate(rados_write_op_t write_op, | |
3051 | uint64_t offset); | |
3052 | ||
3053 | /** | |
3054 | * Zero part of an object | |
3055 | * @param write_op operation to add this action to | |
3056 | * @param offset Offset to zero | |
3057 | * @param len length to zero | |
3058 | */ | |
3059 | CEPH_RADOS_API void rados_write_op_zero(rados_write_op_t write_op, | |
3060 | uint64_t offset, | |
3061 | uint64_t len); | |
3062 | ||
3063 | /** | |
3064 | * Execute an OSD class method on an object | |
3065 | * See rados_exec() for general description. | |
3066 | * | |
3067 | * @param write_op operation to add this action to | |
3068 | * @param cls the name of the class | |
3069 | * @param method the name of the method | |
3070 | * @param in_buf where to find input | |
3071 | * @param in_len length of in_buf in bytes | |
3072 | * @param prval where to store the return value from the method | |
3073 | */ | |
3074 | CEPH_RADOS_API void rados_write_op_exec(rados_write_op_t write_op, | |
3075 | const char *cls, | |
3076 | const char *method, | |
3077 | const char *in_buf, | |
3078 | size_t in_len, | |
3079 | int *prval); | |
3080 | ||
3081 | /** | |
3082 | * Set key/value pairs on an object | |
3083 | * | |
3084 | * @param write_op operation to add this action to | |
3085 | * @param keys array of null-terminated char arrays representing keys to set | |
3086 | * @param vals array of pointers to values to set | |
3087 | * @param lens array of lengths corresponding to each value | |
3088 | * @param num number of key/value pairs to set | |
3089 | */ | |
3090 | CEPH_RADOS_API void rados_write_op_omap_set(rados_write_op_t write_op, | |
11fdf7f2 TL |
3091 | char const* const* keys, |
3092 | char const* const* vals, | |
3093 | const size_t *lens, | |
3094 | size_t num); | |
3095 | ||
3096 | /** | |
3097 | * Set key/value pairs on an object | |
3098 | * | |
3099 | * @param write_op operation to add this action to | |
3100 | * @param keys array of null-terminated char arrays representing keys to set | |
3101 | * @param vals array of pointers to values to set | |
3102 | * @param key_lens array of lengths corresponding to each key | |
3103 | * @param val_lens array of lengths corresponding to each value | |
3104 | * @param num number of key/value pairs to set | |
3105 | */ | |
3106 | CEPH_RADOS_API void rados_write_op_omap_set2(rados_write_op_t write_op, | |
3107 | char const* const* keys, | |
3108 | char const* const* vals, | |
3109 | const size_t *key_lens, | |
3110 | const size_t *val_lens, | |
3111 | size_t num); | |
7c673cae FG |
3112 | |
3113 | /** | |
3114 | * Remove key/value pairs from an object | |
3115 | * | |
3116 | * @param write_op operation to add this action to | |
3117 | * @param keys array of null-terminated char arrays representing keys to remove | |
3118 | * @param keys_len number of key/value pairs to remove | |
3119 | */ | |
3120 | CEPH_RADOS_API void rados_write_op_omap_rm_keys(rados_write_op_t write_op, | |
11fdf7f2 TL |
3121 | char const* const* keys, |
3122 | size_t keys_len); | |
3123 | ||
3124 | /** | |
3125 | * Remove key/value pairs from an object | |
3126 | * | |
3127 | * @param write_op operation to add this action to | |
3128 | * @param keys array of char arrays representing keys to remove | |
3129 | * @param key_lens array of size_t values representing length of each key | |
3130 | * @param keys_len number of key/value pairs to remove | |
3131 | */ | |
3132 | CEPH_RADOS_API void rados_write_op_omap_rm_keys2(rados_write_op_t write_op, | |
3133 | char const* const* keys, | |
3134 | const size_t* key_lens, | |
3135 | size_t keys_len); | |
7c673cae | 3136 | |
9f95a23c TL |
3137 | |
3138 | /** | |
3139 | * Remove key/value pairs from an object whose keys are in the range | |
3140 | * [key_begin, key_end) | |
3141 | * | |
3142 | * @param write_op operation to add this action to | |
3143 | * @param key_begin the lower bound of the key range to remove | |
3144 | * @param key_begin_len length of key_begin | |
3145 | * @param key_end the upper bound of the key range to remove | |
3146 | * @param key_end_len length of key_end | |
3147 | */ | |
3148 | CEPH_RADOS_API void rados_write_op_omap_rm_range2(rados_write_op_t write_op, | |
3149 | const char *key_begin, | |
3150 | size_t key_begin_len, | |
3151 | const char *key_end, | |
3152 | size_t key_end_len); | |
3153 | ||
7c673cae FG |
3154 | /** |
3155 | * Remove all key/value pairs from an object | |
3156 | * | |
3157 | * @param write_op operation to add this action to | |
3158 | */ | |
3159 | CEPH_RADOS_API void rados_write_op_omap_clear(rados_write_op_t write_op); | |
3160 | ||
3161 | /** | |
3162 | * Set allocation hint for an object | |
3163 | * | |
3164 | * @param write_op operation to add this action to | |
3165 | * @param expected_object_size expected size of the object, in bytes | |
3166 | * @param expected_write_size expected size of writes to the object, in bytes | |
3167 | */ | |
3168 | CEPH_RADOS_API void rados_write_op_set_alloc_hint(rados_write_op_t write_op, | |
3169 | uint64_t expected_object_size, | |
3170 | uint64_t expected_write_size); | |
3171 | ||
3172 | /** | |
3173 | * Set allocation hint for an object | |
3174 | * | |
3175 | * @param write_op operation to add this action to | |
3176 | * @param expected_object_size expected size of the object, in bytes | |
3177 | * @param expected_write_size expected size of writes to the object, in bytes | |
3178 | * @param flags hints about future IO patterns | |
3179 | */ | |
3180 | CEPH_RADOS_API void rados_write_op_set_alloc_hint2(rados_write_op_t write_op, | |
3181 | uint64_t expected_object_size, | |
3182 | uint64_t expected_write_size, | |
3183 | uint32_t flags); | |
3184 | ||
3185 | /** | |
3186 | * Perform a write operation synchronously | |
3187 | * @param write_op operation to perform | |
3188 | * @param io the ioctx that the object is in | |
3189 | * @param oid the object id | |
3190 | * @param mtime the time to set the mtime to, NULL for the current time | |
3191 | * @param flags flags to apply to the entire operation (LIBRADOS_OPERATION_*) | |
3192 | */ | |
3193 | CEPH_RADOS_API int rados_write_op_operate(rados_write_op_t write_op, | |
3194 | rados_ioctx_t io, | |
3195 | const char *oid, | |
3196 | time_t *mtime, | |
3197 | int flags); | |
3198 | /** | |
3199 | * Perform a write operation synchronously | |
3200 | * @param write_op operation to perform | |
3201 | * @param io the ioctx that the object is in | |
3202 | * @param oid the object id | |
3203 | * @param mtime the time to set the mtime to, NULL for the current time | |
3204 | * @param flags flags to apply to the entire operation (LIBRADOS_OPERATION_*) | |
3205 | */ | |
3206 | ||
3207 | CEPH_RADOS_API int rados_write_op_operate2(rados_write_op_t write_op, | |
3208 | rados_ioctx_t io, | |
3209 | const char *oid, | |
3210 | struct timespec *mtime, | |
3211 | int flags); | |
3212 | ||
3213 | /** | |
3214 | * Perform a write operation asynchronously | |
3215 | * @param write_op operation to perform | |
3216 | * @param io the ioctx that the object is in | |
3217 | * @param completion what to do when operation has been attempted | |
3218 | * @param oid the object id | |
3219 | * @param mtime the time to set the mtime to, NULL for the current time | |
3220 | * @param flags flags to apply to the entire operation (LIBRADOS_OPERATION_*) | |
3221 | */ | |
3222 | CEPH_RADOS_API int rados_aio_write_op_operate(rados_write_op_t write_op, | |
3223 | rados_ioctx_t io, | |
3224 | rados_completion_t completion, | |
3225 | const char *oid, | |
3226 | time_t *mtime, | |
3227 | int flags); | |
3228 | ||
1e59de90 TL |
3229 | /** |
3230 | * Perform a write operation asynchronously | |
3231 | * @param write_op operation to perform | |
3232 | * @param io the ioctx that the object is in | |
3233 | * @param completion what to do when operation has been attempted | |
3234 | * @param oid the object id | |
3235 | * @param mtime the time to set the mtime to, NULL for the current time | |
3236 | * @param flags flags to apply to the entire operation (LIBRADOS_OPERATION_*) | |
3237 | */ | |
3238 | CEPH_RADOS_API int rados_aio_write_op_operate2(rados_write_op_t write_op, | |
3239 | rados_ioctx_t io, | |
3240 | rados_completion_t completion, | |
3241 | const char *oid, | |
3242 | struct timespec *mtime, | |
3243 | int flags); | |
3244 | ||
7c673cae | 3245 | /** |
f67539c2 | 3246 | * Create a new rados_read_op_t read operation. This will store all |
7c673cae FG |
3247 | * actions to be performed atomically. You must call |
3248 | * rados_release_read_op when you are finished with it (after it | |
3249 | * completes, or you decide not to send it in the first place). | |
3250 | * | |
f67539c2 TL |
3251 | * @note the ownership of a read operartion is passed to the function |
3252 | * performing the operation, so the same instance of @c rados_read_op_t | |
3253 | * cannot be used again after being performed. | |
3254 | * | |
7c673cae FG |
3255 | * @returns non-NULL on success, NULL on memory allocation error. |
3256 | */ | |
3257 | CEPH_RADOS_API rados_read_op_t rados_create_read_op(void); | |
3258 | ||
3259 | /** | |
3260 | * Free a rados_read_op_t, must be called when you're done with it. | |
3261 | * @param read_op operation to deallocate, created with rados_create_read_op | |
3262 | */ | |
3263 | CEPH_RADOS_API void rados_release_read_op(rados_read_op_t read_op); | |
3264 | ||
3265 | /** | |
3266 | * Set flags for the last operation added to this read_op. | |
3267 | * At least one op must have been added to the read_op. | |
11fdf7f2 | 3268 | * @param read_op operation to add this action to |
7c673cae FG |
3269 | * @param flags see librados.h constants beginning with LIBRADOS_OP_FLAG |
3270 | */ | |
3271 | CEPH_RADOS_API void rados_read_op_set_flags(rados_read_op_t read_op, int flags); | |
3272 | ||
3273 | /** | |
3274 | * Ensure that the object exists before reading | |
3275 | * @param read_op operation to add this action to | |
3276 | */ | |
3277 | CEPH_RADOS_API void rados_read_op_assert_exists(rados_read_op_t read_op); | |
3278 | ||
3279 | /** | |
3280 | * Ensure that the object exists and that its internal version | |
3281 | * number is equal to "ver" before reading. "ver" should be a | |
3282 | * version number previously obtained with rados_get_last_version(). | |
3283 | * - If the object's version is greater than the asserted version | |
3284 | * then rados_read_op_operate will return -ERANGE instead of | |
3285 | * executing the op. | |
3286 | * - If the object's version is less than the asserted version | |
3287 | * then rados_read_op_operate will return -EOVERFLOW instead | |
3288 | * of executing the op. | |
3289 | * @param read_op operation to add this action to | |
3290 | * @param ver object version number | |
3291 | */ | |
3292 | CEPH_RADOS_API void rados_read_op_assert_version(rados_read_op_t read_op, uint64_t ver); | |
3293 | ||
3294 | /** | |
3295 | * Ensure that given object range (extent) satisfies comparison. | |
3296 | * | |
3297 | * @param read_op operation to add this action to | |
3298 | * @param cmp_buf buffer containing bytes to be compared with object contents | |
11fdf7f2 | 3299 | * @param cmp_len length to compare and size of @c cmp_buf in bytes |
7c673cae FG |
3300 | * @param off object byte offset at which to start the comparison |
3301 | * @param prval returned result of comparison, 0 on success, negative error code | |
3302 | * on failure, (-MAX_ERRNO - mismatch_off) on mismatch | |
3303 | */ | |
3304 | CEPH_RADOS_API void rados_read_op_cmpext(rados_read_op_t read_op, | |
3305 | const char *cmp_buf, | |
3306 | size_t cmp_len, | |
3307 | uint64_t off, | |
3308 | int *prval); | |
3309 | ||
3310 | /** | |
3311 | * Ensure that the an xattr satisfies a comparison | |
3312 | * If the comparison is not satisfied, the return code of the | |
3313 | * operation will be -ECANCELED | |
3314 | * @param read_op operation to add this action to | |
3315 | * @param name name of the xattr to look up | |
3316 | * @param comparison_operator currently undocumented, look for | |
3317 | * LIBRADOS_CMPXATTR_OP_EQ in librados.h | |
3318 | * @param value buffer to compare actual xattr value to | |
3319 | * @param value_len length of buffer to compare actual xattr value to | |
3320 | */ | |
3321 | CEPH_RADOS_API void rados_read_op_cmpxattr(rados_read_op_t read_op, | |
3322 | const char *name, | |
3323 | uint8_t comparison_operator, | |
3324 | const char *value, | |
3325 | size_t value_len); | |
3326 | ||
3327 | /** | |
3328 | * Start iterating over xattrs on an object. | |
3329 | * | |
3330 | * @param read_op operation to add this action to | |
3331 | * @param iter where to store the iterator | |
3332 | * @param prval where to store the return value of this action | |
3333 | */ | |
3334 | CEPH_RADOS_API void rados_read_op_getxattrs(rados_read_op_t read_op, | |
3335 | rados_xattrs_iter_t *iter, | |
3336 | int *prval); | |
3337 | ||
3338 | /** | |
3339 | * Ensure that the an omap value satisfies a comparison, | |
3340 | * with the supplied value on the right hand side (i.e. | |
3341 | * for OP_LT, the comparison is actual_value < value. | |
3342 | * | |
3343 | * @param read_op operation to add this action to | |
3344 | * @param key which omap value to compare | |
3345 | * @param comparison_operator one of LIBRADOS_CMPXATTR_OP_EQ, | |
3346 | LIBRADOS_CMPXATTR_OP_LT, or LIBRADOS_CMPXATTR_OP_GT | |
3347 | * @param val value to compare with | |
3348 | * @param val_len length of value in bytes | |
3349 | * @param prval where to store the return value from this action | |
3350 | */ | |
3351 | CEPH_RADOS_API void rados_read_op_omap_cmp(rados_read_op_t read_op, | |
11fdf7f2 TL |
3352 | const char *key, |
3353 | uint8_t comparison_operator, | |
3354 | const char *val, | |
3355 | size_t val_len, | |
3356 | int *prval); | |
3357 | ||
3358 | /** | |
3359 | * Ensure that the an omap value satisfies a comparison, | |
3360 | * with the supplied value on the right hand side (i.e. | |
3361 | * for OP_LT, the comparison is actual_value < value. | |
3362 | * | |
3363 | * @param read_op operation to add this action to | |
3364 | * @param key which omap value to compare | |
3365 | * @param comparison_operator one of LIBRADOS_CMPXATTR_OP_EQ, | |
3366 | LIBRADOS_CMPXATTR_OP_LT, or LIBRADOS_CMPXATTR_OP_GT | |
3367 | * @param val value to compare with | |
3368 | * @param key_len length of key in bytes | |
3369 | * @param val_len length of value in bytes | |
3370 | * @param prval where to store the return value from this action | |
3371 | */ | |
3372 | CEPH_RADOS_API void rados_read_op_omap_cmp2(rados_read_op_t read_op, | |
3373 | const char *key, | |
3374 | uint8_t comparison_operator, | |
3375 | const char *val, | |
3376 | size_t key_len, | |
3377 | size_t val_len, | |
3378 | int *prval); | |
7c673cae FG |
3379 | |
3380 | /** | |
3381 | * Get object size and mtime | |
3382 | * @param read_op operation to add this action to | |
3383 | * @param psize where to store object size | |
3384 | * @param pmtime where to store modification time | |
3385 | * @param prval where to store the return value of this action | |
3386 | */ | |
3387 | CEPH_RADOS_API void rados_read_op_stat(rados_read_op_t read_op, | |
3388 | uint64_t *psize, | |
3389 | time_t *pmtime, | |
3390 | int *prval); | |
3391 | ||
1e59de90 TL |
3392 | CEPH_RADOS_API void rados_read_op_stat2(rados_read_op_t read_op, |
3393 | uint64_t *psize, | |
3394 | struct timespec *pmtime, | |
3395 | int *prval); | |
7c673cae FG |
3396 | /** |
3397 | * Read bytes from offset into buffer. | |
3398 | * | |
3399 | * prlen will be filled with the number of bytes read if successful. | |
3400 | * A short read can only occur if the read reaches the end of the | |
3401 | * object. | |
3402 | * | |
3403 | * @param read_op operation to add this action to | |
3404 | * @param offset offset to read from | |
3405 | * @param len length of buffer | |
3406 | * @param buffer where to put the data | |
3407 | * @param bytes_read where to store the number of bytes read by this action | |
3408 | * @param prval where to store the return value of this action | |
3409 | */ | |
3410 | CEPH_RADOS_API void rados_read_op_read(rados_read_op_t read_op, | |
3411 | uint64_t offset, | |
3412 | size_t len, | |
3413 | char *buffer, | |
3414 | size_t *bytes_read, | |
3415 | int *prval); | |
3416 | ||
3417 | /** | |
3418 | * Compute checksum from object data | |
3419 | * | |
3420 | * @param read_op operation to add this action to | |
7c673cae FG |
3421 | * @param type the checksum algorithm to utilize |
3422 | * @param init_value the init value for the algorithm | |
3423 | * @param init_value_len the length of the init value | |
11fdf7f2 | 3424 | * @param offset the offset to start checksumming in the object |
7c673cae | 3425 | * @param len the number of bytes to checksum |
7c673cae FG |
3426 | * @param chunk_size optional length-aligned chunk size for checksums |
3427 | * @param pchecksum where to store the checksum result for this action | |
3428 | * @param checksum_len the number of bytes available for the result | |
3429 | * @param prval where to store the return value for this action | |
3430 | */ | |
3431 | CEPH_RADOS_API void rados_read_op_checksum(rados_read_op_t read_op, | |
3432 | rados_checksum_type_t type, | |
3433 | const char *init_value, | |
3434 | size_t init_value_len, | |
3435 | uint64_t offset, size_t len, | |
3436 | size_t chunk_size, char *pchecksum, | |
3437 | size_t checksum_len, int *prval); | |
3438 | ||
3439 | /** | |
3440 | * Execute an OSD class method on an object | |
3441 | * See rados_exec() for general description. | |
3442 | * | |
3443 | * The output buffer is allocated on the heap; the caller is | |
3444 | * expected to release that memory with rados_buffer_free(). The | |
3445 | * buffer and length pointers can all be NULL, in which case they are | |
3446 | * not filled in. | |
3447 | * | |
3448 | * @param read_op operation to add this action to | |
3449 | * @param cls the name of the class | |
3450 | * @param method the name of the method | |
3451 | * @param in_buf where to find input | |
3452 | * @param in_len length of in_buf in bytes | |
3453 | * @param out_buf where to put librados-allocated output buffer | |
3454 | * @param out_len length of out_buf in bytes | |
3455 | * @param prval where to store the return value from the method | |
3456 | */ | |
3457 | CEPH_RADOS_API void rados_read_op_exec(rados_read_op_t read_op, | |
3458 | const char *cls, | |
3459 | const char *method, | |
3460 | const char *in_buf, | |
3461 | size_t in_len, | |
3462 | char **out_buf, | |
3463 | size_t *out_len, | |
3464 | int *prval); | |
3465 | ||
3466 | /** | |
3467 | * Execute an OSD class method on an object | |
3468 | * See rados_exec() for general description. | |
3469 | * | |
3470 | * If the output buffer is too small, prval will | |
3471 | * be set to -ERANGE and used_len will be 0. | |
3472 | * | |
3473 | * @param read_op operation to add this action to | |
3474 | * @param cls the name of the class | |
3475 | * @param method the name of the method | |
3476 | * @param in_buf where to find input | |
3477 | * @param in_len length of in_buf in bytes | |
3478 | * @param out_buf user-provided buffer to read into | |
3479 | * @param out_len length of out_buf in bytes | |
3480 | * @param used_len where to store the number of bytes read into out_buf | |
3481 | * @param prval where to store the return value from the method | |
3482 | */ | |
3483 | CEPH_RADOS_API void rados_read_op_exec_user_buf(rados_read_op_t read_op, | |
3484 | const char *cls, | |
3485 | const char *method, | |
3486 | const char *in_buf, | |
3487 | size_t in_len, | |
3488 | char *out_buf, | |
3489 | size_t out_len, | |
3490 | size_t *used_len, | |
3491 | int *prval); | |
3492 | ||
3493 | /** | |
3494 | * Start iterating over key/value pairs on an object. | |
3495 | * | |
3496 | * They will be returned sorted by key. | |
3497 | * | |
3498 | * @param read_op operation to add this action to | |
3499 | * @param start_after list keys starting after start_after | |
3500 | * @param filter_prefix list only keys beginning with filter_prefix | |
3501 | * @param max_return list no more than max_return key/value pairs | |
3502 | * @param iter where to store the iterator | |
3503 | * @param prval where to store the return value from this action | |
3504 | */ | |
3505 | CEPH_RADOS_API void rados_read_op_omap_get_vals(rados_read_op_t read_op, | |
3506 | const char *start_after, | |
3507 | const char *filter_prefix, | |
3508 | uint64_t max_return, | |
3509 | rados_omap_iter_t *iter, | |
3510 | int *prval) | |
3511 | __attribute__((deprecated)); /* use v2 below */ | |
3512 | ||
3513 | /** | |
3514 | * Start iterating over key/value pairs on an object. | |
3515 | * | |
3516 | * They will be returned sorted by key. | |
3517 | * | |
3518 | * @param read_op operation to add this action to | |
3519 | * @param start_after list keys starting after start_after | |
3520 | * @param filter_prefix list only keys beginning with filter_prefix | |
3521 | * @param max_return list no more than max_return key/value pairs | |
3522 | * @param iter where to store the iterator | |
3523 | * @param pmore flag indicating whether there are more keys to fetch | |
3524 | * @param prval where to store the return value from this action | |
3525 | */ | |
3526 | CEPH_RADOS_API void rados_read_op_omap_get_vals2(rados_read_op_t read_op, | |
3527 | const char *start_after, | |
3528 | const char *filter_prefix, | |
3529 | uint64_t max_return, | |
3530 | rados_omap_iter_t *iter, | |
3531 | unsigned char *pmore, | |
3532 | int *prval); | |
3533 | ||
3534 | /** | |
3535 | * Start iterating over keys on an object. | |
3536 | * | |
3537 | * They will be returned sorted by key, and the iterator | |
3538 | * will fill in NULL for all values if specified. | |
3539 | * | |
3540 | * @param read_op operation to add this action to | |
3541 | * @param start_after list keys starting after start_after | |
3542 | * @param max_return list no more than max_return keys | |
3543 | * @param iter where to store the iterator | |
3544 | * @param prval where to store the return value from this action | |
3545 | */ | |
3546 | CEPH_RADOS_API void rados_read_op_omap_get_keys(rados_read_op_t read_op, | |
3547 | const char *start_after, | |
3548 | uint64_t max_return, | |
3549 | rados_omap_iter_t *iter, | |
3550 | int *prval) | |
3551 | __attribute__((deprecated)); /* use v2 below */ | |
3552 | ||
3553 | /** | |
3554 | * Start iterating over keys on an object. | |
3555 | * | |
3556 | * They will be returned sorted by key, and the iterator | |
3557 | * will fill in NULL for all values if specified. | |
3558 | * | |
3559 | * @param read_op operation to add this action to | |
3560 | * @param start_after list keys starting after start_after | |
3561 | * @param max_return list no more than max_return keys | |
3562 | * @param iter where to store the iterator | |
3563 | * @param pmore flag indicating whether there are more keys to fetch | |
3564 | * @param prval where to store the return value from this action | |
3565 | */ | |
3566 | CEPH_RADOS_API void rados_read_op_omap_get_keys2(rados_read_op_t read_op, | |
3567 | const char *start_after, | |
3568 | uint64_t max_return, | |
3569 | rados_omap_iter_t *iter, | |
3570 | unsigned char *pmore, | |
3571 | int *prval); | |
3572 | ||
3573 | /** | |
3574 | * Start iterating over specific key/value pairs | |
3575 | * | |
3576 | * They will be returned sorted by key. | |
3577 | * | |
3578 | * @param read_op operation to add this action to | |
3579 | * @param keys array of pointers to null-terminated keys to get | |
3580 | * @param keys_len the number of strings in keys | |
3581 | * @param iter where to store the iterator | |
3582 | * @param prval where to store the return value from this action | |
3583 | */ | |
3584 | CEPH_RADOS_API void rados_read_op_omap_get_vals_by_keys(rados_read_op_t read_op, | |
11fdf7f2 TL |
3585 | char const* const* keys, |
3586 | size_t keys_len, | |
3587 | rados_omap_iter_t *iter, | |
3588 | int *prval); | |
3589 | ||
3590 | /** | |
3591 | * Start iterating over specific key/value pairs | |
3592 | * | |
3593 | * They will be returned sorted by key. | |
3594 | * | |
3595 | * @param read_op operation to add this action to | |
3596 | * @param keys array of pointers to keys to get | |
3597 | * @param num_keys the number of strings in keys | |
3598 | * @param key_lens array of size_t's describing each key len (in bytes) | |
3599 | * @param iter where to store the iterator | |
3600 | * @param prval where to store the return value from this action | |
3601 | */ | |
3602 | CEPH_RADOS_API void rados_read_op_omap_get_vals_by_keys2(rados_read_op_t read_op, | |
3603 | char const* const* keys, | |
3604 | size_t num_keys, | |
3605 | const size_t* key_lens, | |
3606 | rados_omap_iter_t *iter, | |
3607 | int *prval); | |
7c673cae FG |
3608 | |
3609 | /** | |
3610 | * Perform a read operation synchronously | |
3611 | * @param read_op operation to perform | |
3612 | * @param io the ioctx that the object is in | |
3613 | * @param oid the object id | |
3614 | * @param flags flags to apply to the entire operation (LIBRADOS_OPERATION_*) | |
3615 | */ | |
3616 | CEPH_RADOS_API int rados_read_op_operate(rados_read_op_t read_op, | |
3617 | rados_ioctx_t io, | |
3618 | const char *oid, | |
3619 | int flags); | |
3620 | ||
3621 | /** | |
3622 | * Perform a read operation asynchronously | |
3623 | * @param read_op operation to perform | |
3624 | * @param io the ioctx that the object is in | |
3625 | * @param completion what to do when operation has been attempted | |
3626 | * @param oid the object id | |
3627 | * @param flags flags to apply to the entire operation (LIBRADOS_OPERATION_*) | |
3628 | */ | |
3629 | CEPH_RADOS_API int rados_aio_read_op_operate(rados_read_op_t read_op, | |
3630 | rados_ioctx_t io, | |
3631 | rados_completion_t completion, | |
3632 | const char *oid, | |
3633 | int flags); | |
3634 | ||
3635 | /** @} Object Operations */ | |
3636 | ||
3637 | /** | |
3638 | * Take an exclusive lock on an object. | |
3639 | * | |
3640 | * @param io the context to operate in | |
3641 | * @param oid the name of the object | |
3642 | * @param name the name of the lock | |
3643 | * @param cookie user-defined identifier for this instance of the lock | |
3644 | * @param desc user-defined lock description | |
3645 | * @param duration the duration of the lock. Set to NULL for infinite duration. | |
3646 | * @param flags lock flags | |
3647 | * @returns 0 on success, negative error code on failure | |
3648 | * @returns -EBUSY if the lock is already held by another (client, cookie) pair | |
3649 | * @returns -EEXIST if the lock is already held by the same (client, cookie) pair | |
3650 | */ | |
3651 | CEPH_RADOS_API int rados_lock_exclusive(rados_ioctx_t io, const char * oid, | |
3652 | const char * name, const char * cookie, | |
3653 | const char * desc, | |
3654 | struct timeval * duration, | |
3655 | uint8_t flags); | |
3656 | ||
3657 | /** | |
3658 | * Take a shared lock on an object. | |
3659 | * | |
3660 | * @param io the context to operate in | |
3661 | * @param o the name of the object | |
3662 | * @param name the name of the lock | |
3663 | * @param cookie user-defined identifier for this instance of the lock | |
3664 | * @param tag The tag of the lock | |
3665 | * @param desc user-defined lock description | |
3666 | * @param duration the duration of the lock. Set to NULL for infinite duration. | |
3667 | * @param flags lock flags | |
3668 | * @returns 0 on success, negative error code on failure | |
3669 | * @returns -EBUSY if the lock is already held by another (client, cookie) pair | |
3670 | * @returns -EEXIST if the lock is already held by the same (client, cookie) pair | |
3671 | */ | |
3672 | CEPH_RADOS_API int rados_lock_shared(rados_ioctx_t io, const char * o, | |
3673 | const char * name, const char * cookie, | |
3674 | const char * tag, const char * desc, | |
3675 | struct timeval * duration, uint8_t flags); | |
3676 | ||
3677 | /** | |
3678 | * Release a shared or exclusive lock on an object. | |
3679 | * | |
3680 | * @param io the context to operate in | |
3681 | * @param o the name of the object | |
3682 | * @param name the name of the lock | |
3683 | * @param cookie user-defined identifier for the instance of the lock | |
3684 | * @returns 0 on success, negative error code on failure | |
3685 | * @returns -ENOENT if the lock is not held by the specified (client, cookie) pair | |
3686 | */ | |
3687 | CEPH_RADOS_API int rados_unlock(rados_ioctx_t io, const char *o, | |
3688 | const char *name, const char *cookie); | |
3689 | ||
3690 | /** | |
3691 | * Asynchronous release a shared or exclusive lock on an object. | |
3692 | * | |
3693 | * @param io the context to operate in | |
3694 | * @param o the name of the object | |
3695 | * @param name the name of the lock | |
3696 | * @param cookie user-defined identifier for the instance of the lock | |
3697 | * @param completion what to do when operation has been attempted | |
3698 | * @returns 0 on success, negative error code on failure | |
3699 | */ | |
3700 | CEPH_RADOS_API int rados_aio_unlock(rados_ioctx_t io, const char *o, | |
3701 | const char *name, const char *cookie, | |
3702 | rados_completion_t completion); | |
3703 | ||
3704 | /** | |
3705 | * List clients that have locked the named object lock and information about | |
3706 | * the lock. | |
3707 | * | |
3708 | * The number of bytes required in each buffer is put in the | |
3709 | * corresponding size out parameter. If any of the provided buffers | |
3710 | * are too short, -ERANGE is returned after these sizes are filled in. | |
3711 | * | |
3712 | * @param io the context to operate in | |
3713 | * @param o the name of the object | |
3714 | * @param name the name of the lock | |
3715 | * @param exclusive where to store whether the lock is exclusive (1) or shared (0) | |
3716 | * @param tag where to store the tag associated with the object lock | |
3717 | * @param tag_len number of bytes in tag buffer | |
3718 | * @param clients buffer in which locker clients are stored, separated by '\0' | |
3719 | * @param clients_len number of bytes in the clients buffer | |
3720 | * @param cookies buffer in which locker cookies are stored, separated by '\0' | |
3721 | * @param cookies_len number of bytes in the cookies buffer | |
3722 | * @param addrs buffer in which locker addresses are stored, separated by '\0' | |
3723 | * @param addrs_len number of bytes in the clients buffer | |
3724 | * @returns number of lockers on success, negative error code on failure | |
3725 | * @returns -ERANGE if any of the buffers are too short | |
3726 | */ | |
3727 | CEPH_RADOS_API ssize_t rados_list_lockers(rados_ioctx_t io, const char *o, | |
3728 | const char *name, int *exclusive, | |
3729 | char *tag, size_t *tag_len, | |
3730 | char *clients, size_t *clients_len, | |
3731 | char *cookies, size_t *cookies_len, | |
3732 | char *addrs, size_t *addrs_len); | |
3733 | ||
3734 | /** | |
3735 | * Releases a shared or exclusive lock on an object, which was taken by the | |
3736 | * specified client. | |
3737 | * | |
3738 | * @param io the context to operate in | |
3739 | * @param o the name of the object | |
3740 | * @param name the name of the lock | |
3741 | * @param client the client currently holding the lock | |
3742 | * @param cookie user-defined identifier for the instance of the lock | |
3743 | * @returns 0 on success, negative error code on failure | |
3744 | * @returns -ENOENT if the lock is not held by the specified (client, cookie) pair | |
3745 | * @returns -EINVAL if the client cannot be parsed | |
3746 | */ | |
3747 | CEPH_RADOS_API int rados_break_lock(rados_ioctx_t io, const char *o, | |
3748 | const char *name, const char *client, | |
3749 | const char *cookie); | |
3750 | ||
3751 | /** | |
f67539c2 | 3752 | * Blocklists the specified client from the OSDs |
7c673cae FG |
3753 | * |
3754 | * @param cluster cluster handle | |
3755 | * @param client_address client address | |
f67539c2 | 3756 | * @param expire_seconds number of seconds to blocklist (0 for default) |
7c673cae FG |
3757 | * @returns 0 on success, negative error code on failure |
3758 | */ | |
f67539c2 | 3759 | CEPH_RADOS_API int rados_blocklist_add(rados_t cluster, |
7c673cae FG |
3760 | char *client_address, |
3761 | uint32_t expire_seconds); | |
f67539c2 TL |
3762 | CEPH_RADOS_API int rados_blacklist_add(rados_t cluster, |
3763 | char *client_address, | |
3764 | uint32_t expire_seconds) | |
3765 | __attribute__((deprecated)); | |
7c673cae | 3766 | |
9f95a23c | 3767 | /** |
f67539c2 | 3768 | * Gets addresses of the RADOS session, suitable for blocklisting. |
9f95a23c TL |
3769 | * |
3770 | * @param cluster cluster handle | |
3771 | * @param addrs the output string. | |
3772 | * @returns 0 on success, negative error code on failure | |
3773 | */ | |
3774 | CEPH_RADOS_API int rados_getaddrs(rados_t cluster, char** addrs); | |
11fdf7f2 | 3775 | |
9f95a23c TL |
3776 | CEPH_RADOS_API void rados_set_osdmap_full_try(rados_ioctx_t io) |
3777 | __attribute__((deprecated)); | |
3778 | ||
3779 | CEPH_RADOS_API void rados_unset_osdmap_full_try(rados_ioctx_t io) | |
3780 | __attribute__((deprecated)); | |
3781 | ||
3782 | CEPH_RADOS_API void rados_set_pool_full_try(rados_ioctx_t io); | |
3783 | ||
3784 | CEPH_RADOS_API void rados_unset_pool_full_try(rados_ioctx_t io); | |
11fdf7f2 | 3785 | |
c07f9fc5 FG |
3786 | /** |
3787 | * Enable an application on a pool | |
3788 | * | |
11fdf7f2 | 3789 | * @param io pool ioctx |
c07f9fc5 FG |
3790 | * @param app_name application name |
3791 | * @param force 0 if only single application per pool | |
3792 | * @returns 0 on success, negative error code on failure | |
3793 | */ | |
3794 | CEPH_RADOS_API int rados_application_enable(rados_ioctx_t io, | |
3795 | const char *app_name, int force); | |
3796 | ||
3797 | /** | |
3798 | * List all enabled applications | |
3799 | * | |
3800 | * If the provided buffer is too short, the required length is filled in and | |
3801 | * -ERANGE is returned. Otherwise, the buffers are filled with the application | |
3802 | * names, with a '\0' after each. | |
3803 | * | |
11fdf7f2 | 3804 | * @param io pool ioctx |
c07f9fc5 | 3805 | * @param values buffer in which to store application names |
11fdf7f2 | 3806 | * @param values_len number of bytes in values buffer |
c07f9fc5 FG |
3807 | * @returns 0 on success, negative error code on failure |
3808 | * @returns -ERANGE if either buffer is too short | |
3809 | */ | |
3810 | CEPH_RADOS_API int rados_application_list(rados_ioctx_t io, char *values, | |
3811 | size_t *values_len); | |
3812 | ||
3813 | /** | |
3814 | * Get application metadata value from pool | |
3815 | * | |
11fdf7f2 | 3816 | * @param io pool ioctx |
c07f9fc5 FG |
3817 | * @param app_name application name |
3818 | * @param key metadata key | |
3819 | * @param value result buffer | |
3820 | * @param value_len maximum len of value | |
3821 | * @returns 0 on success, negative error code on failure | |
3822 | */ | |
3823 | CEPH_RADOS_API int rados_application_metadata_get(rados_ioctx_t io, | |
3824 | const char *app_name, | |
3825 | const char *key, char *value, | |
3826 | size_t *value_len); | |
3827 | ||
3828 | /** | |
3829 | * Set application metadata on a pool | |
3830 | * | |
11fdf7f2 | 3831 | * @param io pool ioctx |
c07f9fc5 FG |
3832 | * @param app_name application name |
3833 | * @param key metadata key | |
3834 | * @param value metadata key | |
3835 | * @returns 0 on success, negative error code on failure | |
3836 | */ | |
3837 | CEPH_RADOS_API int rados_application_metadata_set(rados_ioctx_t io, | |
3838 | const char *app_name, | |
3839 | const char *key, | |
3840 | const char *value); | |
3841 | ||
3842 | /** | |
3843 | * Remove application metadata from a pool | |
3844 | * | |
11fdf7f2 | 3845 | * @param io pool ioctx |
c07f9fc5 FG |
3846 | * @param app_name application name |
3847 | * @param key metadata key | |
3848 | * @returns 0 on success, negative error code on failure | |
3849 | */ | |
3850 | CEPH_RADOS_API int rados_application_metadata_remove(rados_ioctx_t io, | |
3851 | const char *app_name, | |
3852 | const char *key); | |
3853 | ||
3854 | /** | |
3855 | * List all metadata key/value pairs associated with an application. | |
3856 | * | |
3857 | * This iterates over all metadata, key_len and val_len are filled in | |
3858 | * with the number of bytes put into the keys and values buffers. | |
3859 | * | |
3860 | * If the provided buffers are too short, the required lengths are filled | |
3861 | * in and -ERANGE is returned. Otherwise, the buffers are filled with | |
3862 | * the keys and values of the metadata, with a '\0' after each. | |
3863 | * | |
11fdf7f2 | 3864 | * @param io pool ioctx |
c07f9fc5 FG |
3865 | * @param app_name application name |
3866 | * @param keys buffer in which to store key names | |
11fdf7f2 | 3867 | * @param key_len number of bytes in keys buffer |
c07f9fc5 FG |
3868 | * @param values buffer in which to store values |
3869 | * @param vals_len number of bytes in values buffer | |
11fdf7f2 | 3870 | * @returns 0 on success, negative error code on failure |
c07f9fc5 FG |
3871 | * @returns -ERANGE if either buffer is too short |
3872 | */ | |
3873 | CEPH_RADOS_API int rados_application_metadata_list(rados_ioctx_t io, | |
3874 | const char *app_name, | |
3875 | char *keys, size_t *key_len, | |
3876 | char *values, | |
3877 | size_t *vals_len); | |
3878 | ||
7c673cae FG |
3879 | /** |
3880 | * @name Mon/OSD/PG Commands | |
3881 | * | |
3882 | * These interfaces send commands relating to the monitor, OSD, or PGs. | |
3883 | * | |
3884 | * @{ | |
3885 | */ | |
3886 | ||
3887 | /** | |
3888 | * Send monitor command. | |
3889 | * | |
3890 | * @note Takes command string in carefully-formatted JSON; must match | |
3891 | * defined commands, types, etc. | |
3892 | * | |
3893 | * The result buffers are allocated on the heap; the caller is | |
3894 | * expected to release that memory with rados_buffer_free(). The | |
3895 | * buffer and length pointers can all be NULL, in which case they are | |
3896 | * not filled in. | |
3897 | * | |
3898 | * @param cluster cluster handle | |
3899 | * @param cmd an array of char *'s representing the command | |
3900 | * @param cmdlen count of valid entries in cmd | |
3901 | * @param inbuf any bulk input data (crush map, etc.) | |
11fdf7f2 | 3902 | * @param inbuflen input buffer length |
7c673cae FG |
3903 | * @param outbuf double pointer to output buffer |
3904 | * @param outbuflen pointer to output buffer length | |
3905 | * @param outs double pointer to status string | |
3906 | * @param outslen pointer to status string length | |
3907 | * @returns 0 on success, negative error code on failure | |
3908 | */ | |
3909 | CEPH_RADOS_API int rados_mon_command(rados_t cluster, const char **cmd, | |
3910 | size_t cmdlen, const char *inbuf, | |
3911 | size_t inbuflen, char **outbuf, | |
3912 | size_t *outbuflen, char **outs, | |
3913 | size_t *outslen); | |
3914 | ||
3915 | /** | |
3916 | * Send ceph-mgr command. | |
3917 | * | |
3918 | * @note Takes command string in carefully-formatted JSON; must match | |
3919 | * defined commands, types, etc. | |
3920 | * | |
3921 | * The result buffers are allocated on the heap; the caller is | |
3922 | * expected to release that memory with rados_buffer_free(). The | |
3923 | * buffer and length pointers can all be NULL, in which case they are | |
3924 | * not filled in. | |
3925 | * | |
3926 | * @param cluster cluster handle | |
3927 | * @param cmd an array of char *'s representing the command | |
3928 | * @param cmdlen count of valid entries in cmd | |
3929 | * @param inbuf any bulk input data (crush map, etc.) | |
11fdf7f2 | 3930 | * @param inbuflen input buffer length |
7c673cae FG |
3931 | * @param outbuf double pointer to output buffer |
3932 | * @param outbuflen pointer to output buffer length | |
3933 | * @param outs double pointer to status string | |
3934 | * @param outslen pointer to status string length | |
3935 | * @returns 0 on success, negative error code on failure | |
3936 | */ | |
3937 | CEPH_RADOS_API int rados_mgr_command(rados_t cluster, const char **cmd, | |
3938 | size_t cmdlen, const char *inbuf, | |
3939 | size_t inbuflen, char **outbuf, | |
3940 | size_t *outbuflen, char **outs, | |
3941 | size_t *outslen); | |
3942 | ||
9f95a23c TL |
3943 | /** |
3944 | * Send ceph-mgr tell command. | |
3945 | * | |
3946 | * @note Takes command string in carefully-formatted JSON; must match | |
3947 | * defined commands, types, etc. | |
3948 | * | |
3949 | * The result buffers are allocated on the heap; the caller is | |
3950 | * expected to release that memory with rados_buffer_free(). The | |
3951 | * buffer and length pointers can all be NULL, in which case they are | |
3952 | * not filled in. | |
3953 | * | |
3954 | * @param cluster cluster handle | |
3955 | * @param name mgr name to target | |
3956 | * @param cmd an array of char *'s representing the command | |
3957 | * @param cmdlen count of valid entries in cmd | |
3958 | * @param inbuf any bulk input data (crush map, etc.) | |
3959 | * @param inbuflen input buffer length | |
3960 | * @param outbuf double pointer to output buffer | |
3961 | * @param outbuflen pointer to output buffer length | |
3962 | * @param outs double pointer to status string | |
3963 | * @param outslen pointer to status string length | |
3964 | * @returns 0 on success, negative error code on failure | |
3965 | */ | |
3966 | CEPH_RADOS_API int rados_mgr_command_target( | |
3967 | rados_t cluster, | |
3968 | const char *name, | |
3969 | const char **cmd, | |
3970 | size_t cmdlen, const char *inbuf, | |
3971 | size_t inbuflen, char **outbuf, | |
3972 | size_t *outbuflen, char **outs, | |
3973 | size_t *outslen); | |
3974 | ||
7c673cae FG |
3975 | /** |
3976 | * Send monitor command to a specific monitor. | |
3977 | * | |
3978 | * @note Takes command string in carefully-formatted JSON; must match | |
3979 | * defined commands, types, etc. | |
3980 | * | |
3981 | * The result buffers are allocated on the heap; the caller is | |
3982 | * expected to release that memory with rados_buffer_free(). The | |
3983 | * buffer and length pointers can all be NULL, in which case they are | |
3984 | * not filled in. | |
3985 | * | |
3986 | * @param cluster cluster handle | |
3987 | * @param name target monitor's name | |
3988 | * @param cmd an array of char *'s representing the command | |
3989 | * @param cmdlen count of valid entries in cmd | |
3990 | * @param inbuf any bulk input data (crush map, etc.) | |
11fdf7f2 | 3991 | * @param inbuflen input buffer length |
7c673cae FG |
3992 | * @param outbuf double pointer to output buffer |
3993 | * @param outbuflen pointer to output buffer length | |
3994 | * @param outs double pointer to status string | |
3995 | * @param outslen pointer to status string length | |
3996 | * @returns 0 on success, negative error code on failure | |
3997 | */ | |
3998 | CEPH_RADOS_API int rados_mon_command_target(rados_t cluster, const char *name, | |
3999 | const char **cmd, size_t cmdlen, | |
4000 | const char *inbuf, size_t inbuflen, | |
4001 | char **outbuf, size_t *outbuflen, | |
4002 | char **outs, size_t *outslen); | |
4003 | ||
4004 | /** | |
4005 | * free a rados-allocated buffer | |
4006 | * | |
4007 | * Release memory allocated by librados calls like rados_mon_command(). | |
4008 | * | |
4009 | * @param buf buffer pointer | |
4010 | */ | |
4011 | CEPH_RADOS_API void rados_buffer_free(char *buf); | |
4012 | ||
4013 | CEPH_RADOS_API int rados_osd_command(rados_t cluster, int osdid, | |
4014 | const char **cmd, size_t cmdlen, | |
4015 | const char *inbuf, size_t inbuflen, | |
4016 | char **outbuf, size_t *outbuflen, | |
4017 | char **outs, size_t *outslen); | |
4018 | ||
4019 | CEPH_RADOS_API int rados_pg_command(rados_t cluster, const char *pgstr, | |
4020 | const char **cmd, size_t cmdlen, | |
4021 | const char *inbuf, size_t inbuflen, | |
4022 | char **outbuf, size_t *outbuflen, | |
4023 | char **outs, size_t *outslen); | |
4024 | ||
7c673cae FG |
4025 | /* |
4026 | * This is not a doxygen comment leadin, because doxygen breaks on | |
4027 | * a typedef with function params and returns, and I can't figure out | |
4028 | * how to fix it. | |
4029 | * | |
4030 | * Monitor cluster log | |
4031 | * | |
4032 | * Monitor events logged to the cluster log. The callback get each | |
4033 | * log entry both as a single formatted line and with each field in a | |
4034 | * separate arg. | |
4035 | * | |
4036 | * Calling with a cb argument of NULL will deregister any previously | |
4037 | * registered callback. | |
4038 | * | |
4039 | * @param cluster cluster handle | |
4040 | * @param level minimum log level (debug, info, warn|warning, err|error) | |
4041 | * @param cb callback to run for each log message. It MUST NOT block | |
4042 | * nor call back into librados. | |
4043 | * @param arg void argument to pass to cb | |
4044 | * | |
4045 | * @returns 0 on success, negative code on error | |
4046 | */ | |
4047 | typedef void (*rados_log_callback_t)(void *arg, | |
4048 | const char *line, | |
4049 | const char *who, | |
4050 | uint64_t sec, uint64_t nsec, | |
4051 | uint64_t seq, const char *level, | |
4052 | const char *msg); | |
4053 | ||
31f18b77 FG |
4054 | /* |
4055 | * This is not a doxygen comment leadin, because doxygen breaks on | |
4056 | * a typedef with function params and returns, and I can't figure out | |
4057 | * how to fix it. | |
4058 | * | |
4059 | * Monitor cluster log | |
4060 | * | |
4061 | * Monitor events logged to the cluster log. The callback get each | |
4062 | * log entry both as a single formatted line and with each field in a | |
4063 | * separate arg. | |
4064 | * | |
4065 | * Calling with a cb argument of NULL will deregister any previously | |
4066 | * registered callback. | |
4067 | * | |
4068 | * @param cluster cluster handle | |
4069 | * @param level minimum log level (debug, info, warn|warning, err|error) | |
4070 | * @param cb callback to run for each log message. It MUST NOT block | |
4071 | * nor call back into librados. | |
4072 | * @param arg void argument to pass to cb | |
4073 | * | |
4074 | * @returns 0 on success, negative code on error | |
4075 | */ | |
4076 | typedef void (*rados_log_callback2_t)(void *arg, | |
4077 | const char *line, | |
224ce89b | 4078 | const char *channel, |
31f18b77 FG |
4079 | const char *who, |
4080 | const char *name, | |
4081 | uint64_t sec, uint64_t nsec, | |
4082 | uint64_t seq, const char *level, | |
4083 | const char *msg); | |
4084 | ||
7c673cae FG |
4085 | CEPH_RADOS_API int rados_monitor_log(rados_t cluster, const char *level, |
4086 | rados_log_callback_t cb, void *arg); | |
31f18b77 FG |
4087 | CEPH_RADOS_API int rados_monitor_log2(rados_t cluster, const char *level, |
4088 | rados_log_callback2_t cb, void *arg); | |
7c673cae | 4089 | |
224ce89b WB |
4090 | |
4091 | /** | |
4092 | * register daemon instance for a service | |
4093 | * | |
4094 | * Register us as a daemon providing a particular service. We identify | |
4095 | * the service (e.g., 'rgw') and our instance name (e.g., 'rgw.$hostname'). | |
4096 | * The metadata is a map of keys and values with arbitrary static metdata | |
4097 | * for this instance. The encoding is a series of NULL-terminated strings, | |
4098 | * alternating key names and values, terminating with an empty key name. | |
4099 | * For example, "foo\0bar\0this\0that\0\0" is the dict {foo=bar,this=that}. | |
4100 | * | |
4101 | * For the lifetime of the librados instance, regular beacons will be sent | |
4102 | * to the cluster to maintain our registration in the service map. | |
4103 | * | |
4104 | * @param cluster handle | |
4105 | * @param service service name | |
11fdf7f2 | 4106 | * @param daemon daemon instance name |
224ce89b WB |
4107 | * @param metadata_dict static daemon metadata dict |
4108 | */ | |
4109 | CEPH_RADOS_API int rados_service_register( | |
4110 | rados_t cluster, | |
4111 | const char *service, | |
4112 | const char *daemon, | |
4113 | const char *metadata_dict); | |
4114 | ||
4115 | /** | |
4116 | * update daemon status | |
4117 | * | |
4118 | * Update our mutable status information in the service map. | |
4119 | * | |
4120 | * The status dict is encoded the same way the daemon metadata is encoded | |
4121 | * for rados_service_register. For example, "foo\0bar\0this\0that\0\0" is | |
4122 | * {foo=bar,this=that}. | |
4123 | * | |
4124 | * @param cluster rados cluster handle | |
4125 | * @param status_dict status dict | |
4126 | */ | |
4127 | CEPH_RADOS_API int rados_service_update_status( | |
4128 | rados_t cluster, | |
4129 | const char *status_dict); | |
4130 | ||
7c673cae FG |
4131 | /** @} Mon/OSD/PG commands */ |
4132 | ||
4133 | /* | |
4134 | * These methods are no longer supported and return -ENOTSUP where possible. | |
4135 | */ | |
4136 | CEPH_RADOS_API int rados_objects_list_open( | |
4137 | rados_ioctx_t io, | |
4138 | rados_list_ctx_t *ctx) __attribute__((deprecated)); | |
4139 | CEPH_RADOS_API uint32_t rados_objects_list_get_pg_hash_position( | |
4140 | rados_list_ctx_t ctx) __attribute__((deprecated)); | |
4141 | CEPH_RADOS_API uint32_t rados_objects_list_seek( | |
4142 | rados_list_ctx_t ctx, | |
4143 | uint32_t pos) __attribute__((deprecated)); | |
4144 | CEPH_RADOS_API int rados_objects_list_next( | |
4145 | rados_list_ctx_t ctx, | |
4146 | const char **entry, | |
4147 | const char **key) __attribute__((deprecated)); | |
4148 | CEPH_RADOS_API void rados_objects_list_close( | |
4149 | rados_list_ctx_t ctx) __attribute__((deprecated)); | |
4150 | ||
4151 | ||
4152 | #ifdef __cplusplus | |
4153 | } | |
4154 | #endif | |
4155 | ||
4156 | #endif |