1 // -*- mode:C++; tab-width:8; c-basic-offset:2; indent-tabs-mode:t -*-
2 // vim: ts=8 sw=2 smarttab
4 * Ceph - scalable distributed file system
6 * Copyright (C) 2004-2012 Sage Weil <sage@newdream.net>
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.
15 #ifndef CEPH_LIBRADOS_H
16 #define CEPH_LIBRADOS_H
22 #include <netinet/in.h>
23 #if defined(__linux__)
24 #include <linux/types.h>
25 #elif defined(__FreeBSD__)
26 #include <sys/types.h>
30 #include "rados_types.h"
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'
42 #define LIBRADOS_VER_MAJOR 3
43 #define LIBRADOS_VER_MINOR 0
44 #define LIBRADOS_VER_EXTRA 0
46 #define LIBRADOS_VERSION(maj, min, extra) ((maj << 16) + (min << 8) + extra)
48 #define LIBRADOS_VERSION_CODE LIBRADOS_VERSION(LIBRADOS_VER_MAJOR, LIBRADOS_VER_MINOR, LIBRADOS_VER_EXTRA)
50 #define LIBRADOS_SUPPORTS_WATCH 1
51 #define LIBRADOS_SUPPORTS_SERVICES 1
52 #define LIBRADOS_SUPPORTS_APP_METADATA 1
55 * They are also defined in cls_lock_types.h. Keep them in sync!
57 #define LIBRADOS_LOCK_FLAG_RENEW 0x1
60 * Constants for rados_write_op_create().
62 #define LIBRADOS_CREATE_EXCLUSIVE 1
63 #define LIBRADOS_CREATE_IDEMPOTENT 0
66 * Flags that can be set on a per-op basis via
67 * rados_read_op_set_flags() and rados_write_op_set_flags().
70 // fail a create operation if the object already exists
71 LIBRADOS_OP_FLAG_EXCL
= 0x1,
72 // allow the transaction to succeed even if the flagged op fails
73 LIBRADOS_OP_FLAG_FAILOK
= 0x2,
74 // indicate read/write op random
75 LIBRADOS_OP_FLAG_FADVISE_RANDOM
= 0x4,
76 // indicate read/write op sequential
77 LIBRADOS_OP_FLAG_FADVISE_SEQUENTIAL
= 0x8,
78 // indicate read/write data will be accessed in the near future (by someone)
79 LIBRADOS_OP_FLAG_FADVISE_WILLNEED
= 0x10,
80 // indicate read/write data will not accessed in the near future (by anyone)
81 LIBRADOS_OP_FLAG_FADVISE_DONTNEED
= 0x20,
82 // indicate read/write data will not accessed again (by *this* client)
83 LIBRADOS_OP_FLAG_FADVISE_NOCACHE
= 0x40,
84 // optionally support FUA (force unit access) on write requests
85 LIBRADOS_OP_FLAG_FADVISE_FUA
= 0x80,
88 #define CEPH_RADOS_API
91 * @name xattr comparison operations
92 * Operators for comparing xattrs on objects, and aborting the
93 * rados_read_op or rados_write_op transaction if the comparison
99 LIBRADOS_CMPXATTR_OP_EQ
= 1,
100 LIBRADOS_CMPXATTR_OP_NE
= 2,
101 LIBRADOS_CMPXATTR_OP_GT
= 3,
102 LIBRADOS_CMPXATTR_OP_GTE
= 4,
103 LIBRADOS_CMPXATTR_OP_LT
= 5,
104 LIBRADOS_CMPXATTR_OP_LTE
= 6
109 * @name Operation Flags
110 * Flags for rados_read_op_operate(), rados_write_op_operate(),
111 * rados_aio_read_op_operate(), and rados_aio_write_op_operate().
112 * See librados.hpp for details.
116 LIBRADOS_OPERATION_NOFLAG
= 0,
117 LIBRADOS_OPERATION_BALANCE_READS
= 1,
118 LIBRADOS_OPERATION_LOCALIZE_READS
= 2,
119 LIBRADOS_OPERATION_ORDER_READS_WRITES
= 4,
120 LIBRADOS_OPERATION_IGNORE_CACHE
= 8,
121 LIBRADOS_OPERATION_SKIPRWLOCKS
= 16,
122 LIBRADOS_OPERATION_IGNORE_OVERLAY
= 32,
123 /* send requests to cluster despite the cluster or pool being marked
124 full; ops will either succeed (e.g., delete) or return EDQUOT or
126 LIBRADOS_OPERATION_FULL_TRY
= 64,
128 * Mainly for delete op
130 LIBRADOS_OPERATION_FULL_FORCE
= 128,
131 LIBRADOS_OPERATION_IGNORE_REDIRECT
= 256,
132 LIBRADOS_OPERATION_ORDERSNAP
= 512,
133 /* enable/allow >0 return values and payloads on write/update */
134 LIBRADOS_OPERATION_RETURNVEC
= 1024,
139 * @name Alloc hint flags
140 * Flags for rados_write_op_alloc_hint2() and rados_set_alloc_hint2()
141 * indicating future IO patterns.
145 LIBRADOS_ALLOC_HINT_FLAG_SEQUENTIAL_WRITE
= 1,
146 LIBRADOS_ALLOC_HINT_FLAG_RANDOM_WRITE
= 2,
147 LIBRADOS_ALLOC_HINT_FLAG_SEQUENTIAL_READ
= 4,
148 LIBRADOS_ALLOC_HINT_FLAG_RANDOM_READ
= 8,
149 LIBRADOS_ALLOC_HINT_FLAG_APPEND_ONLY
= 16,
150 LIBRADOS_ALLOC_HINT_FLAG_IMMUTABLE
= 32,
151 LIBRADOS_ALLOC_HINT_FLAG_SHORTLIVED
= 64,
152 LIBRADOS_ALLOC_HINT_FLAG_LONGLIVED
= 128,
153 LIBRADOS_ALLOC_HINT_FLAG_COMPRESSIBLE
= 256,
154 LIBRADOS_ALLOC_HINT_FLAG_INCOMPRESSIBLE
= 512,
159 LIBRADOS_CHECKSUM_TYPE_XXHASH32
= 0,
160 LIBRADOS_CHECKSUM_TYPE_XXHASH64
= 1,
161 LIBRADOS_CHECKSUM_TYPE_CRC32C
= 2
162 } rados_checksum_type_t
;
167 #define LIBRADOS_SNAP_HEAD ((uint64_t)(-2))
168 #define LIBRADOS_SNAP_DIR ((uint64_t)(-1))
173 * A handle for interacting with a RADOS cluster. It encapsulates all
174 * RADOS client configuration, including username, key for
175 * authentication, logging, and debugging. Talking different clusters
176 * -- or to the same cluster with different users -- requires
177 * different cluster handles.
179 #ifndef VOIDPTR_RADOS_T
180 #define VOIDPTR_RADOS_T
181 typedef void *rados_t
;
182 #endif //VOIDPTR_RADOS_T
185 * @typedef rados_config_t
187 * A handle for the ceph configuration context for the rados_t cluster
188 * instance. This can be used to share configuration context/state
189 * (e.g., logging configuration) between librados instance.
191 * @warning The config context does not have independent reference
192 * counting. As such, a rados_config_t handle retrieved from a given
193 * rados_t is only valid as long as that rados_t.
195 typedef void *rados_config_t
;
198 * @typedef rados_ioctx_t
200 * An io context encapsulates a few settings for all I/O operations
202 * - pool - set when the io context is created (see rados_ioctx_create())
203 * - snapshot context for writes (see
204 * rados_ioctx_selfmanaged_snap_set_write_ctx())
205 * - snapshot id to read from (see rados_ioctx_snap_set_read())
206 * - object locator for all single-object operations (see
207 * rados_ioctx_locator_set_key())
208 * - namespace for all single-object operations (see
209 * rados_ioctx_set_namespace()). Set to LIBRADOS_ALL_NSPACES
210 * before rados_nobjects_list_open() will list all objects in all
213 * @warning Changing any of these settings is not thread-safe -
214 * librados users must synchronize any of these changes on their own,
215 * or use separate io contexts for each thread
217 typedef void *rados_ioctx_t
;
220 * @typedef rados_list_ctx_t
222 * An iterator for listing the objects in a pool.
223 * Used with rados_nobjects_list_open(),
224 * rados_nobjects_list_next(), and
225 * rados_nobjects_list_close().
227 typedef void *rados_list_ctx_t
;
230 * @typedef rados_object_list_cursor
232 * The cursor used with rados_enumerate_objects
233 * and accompanying methods.
235 typedef void * rados_object_list_cursor
;
238 * @struct rados_object_list_item
240 * The item populated by rados_object_list in
243 typedef struct rados_object_list_item
{
247 /// name of the object
250 size_t nspace_length
;
251 /// the object namespace
254 size_t locator_length
;
257 } rados_object_list_item
;
260 * @typedef rados_snap_t
261 * The id of a snapshot.
263 typedef uint64_t rados_snap_t
;
266 * @typedef rados_xattrs_iter_t
267 * An iterator for listing extended attrbutes on an object.
268 * Used with rados_getxattrs(), rados_getxattrs_next(), and
269 * rados_getxattrs_end().
271 typedef void *rados_xattrs_iter_t
;
274 * @typedef rados_omap_iter_t
275 * An iterator for listing omap key/value pairs on an object.
276 * Used with rados_read_op_omap_get_keys(), rados_read_op_omap_get_vals(),
277 * rados_read_op_omap_get_vals_by_keys(), rados_omap_get_next(), and
278 * rados_omap_get_end().
280 typedef void *rados_omap_iter_t
;
283 * @struct rados_pool_stat_t
284 * Usage information for a pool.
286 struct rados_pool_stat_t
{
287 /// space used in bytes
291 /// number of objects in the pool
292 uint64_t num_objects
;
293 /// number of clones of objects
294 uint64_t num_object_clones
;
295 /// num_objects * num_replicas
296 uint64_t num_object_copies
;
297 /// number of objects missing on primary
298 uint64_t num_objects_missing_on_primary
;
299 /// number of objects found on no OSDs
300 uint64_t num_objects_unfound
;
301 /// number of objects replicated fewer times than they should be
302 /// (but found on at least one OSD)
303 uint64_t num_objects_degraded
;
304 /// number of objects read
306 /// objects read in KB
308 /// number of objects written
310 /// objects written in KB
312 /// bytes originally provided by user
313 uint64_t num_user_bytes
;
314 /// bytes passed compression
315 uint64_t compressed_bytes_orig
;
316 /// bytes resulted after compression
317 uint64_t compressed_bytes
;
318 /// bytes allocated at storage
319 uint64_t compressed_bytes_alloc
;
323 * @struct rados_cluster_stat_t
324 * Cluster-wide usage information
326 struct rados_cluster_stat_t
{
327 /// total device size
331 /// total available/free
333 /// number of objects
334 uint64_t num_objects
;
338 * @typedef rados_write_op_t
340 * An object write operation stores a number of operations which can be
341 * executed atomically. For usage, see:
342 * - Creation and deletion: rados_create_write_op() rados_release_write_op()
343 * - Extended attribute manipulation: rados_write_op_cmpxattr()
344 * rados_write_op_cmpxattr(), rados_write_op_setxattr(),
345 * rados_write_op_rmxattr()
346 * - Object map key/value pairs: rados_write_op_omap_set(),
347 * rados_write_op_omap_rm_keys(), rados_write_op_omap_clear(),
348 * rados_write_op_omap_cmp()
349 * - Object properties: rados_write_op_assert_exists(),
350 * rados_write_op_assert_version()
351 * - Creating objects: rados_write_op_create()
352 * - IO on objects: rados_write_op_append(), rados_write_op_write(), rados_write_op_zero
353 * rados_write_op_write_full(), rados_write_op_writesame(), rados_write_op_remove,
354 * rados_write_op_truncate(), rados_write_op_zero(), rados_write_op_cmpext()
355 * - Hints: rados_write_op_set_alloc_hint()
356 * - Performing the operation: rados_write_op_operate(), rados_aio_write_op_operate()
358 typedef void *rados_write_op_t
;
361 * @typedef rados_read_op_t
363 * An object read operation stores a number of operations which can be
364 * executed atomically. For usage, see:
365 * - Creation and deletion: rados_create_read_op() rados_release_read_op()
366 * - Extended attribute manipulation: rados_read_op_cmpxattr(),
367 * rados_read_op_getxattr(), rados_read_op_getxattrs()
368 * - Object map key/value pairs: rados_read_op_omap_get_vals(),
369 * rados_read_op_omap_get_keys(), rados_read_op_omap_get_vals_by_keys(),
370 * rados_read_op_omap_cmp()
371 * - Object properties: rados_read_op_stat(), rados_read_op_assert_exists(),
372 * rados_read_op_assert_version()
373 * - IO on objects: rados_read_op_read(), rados_read_op_checksum(),
374 * rados_read_op_cmpext()
375 * - Custom operations: rados_read_op_exec(), rados_read_op_exec_user_buf()
376 * - Request properties: rados_read_op_set_flags()
377 * - Performing the operation: rados_read_op_operate(),
378 * rados_aio_read_op_operate()
380 typedef void *rados_read_op_t
;
383 * @typedef rados_completion_t
384 * Represents the state of an asynchronous operation - it contains the
385 * return value once the operation completes, and can be used to block
386 * until the operation is complete or safe.
388 typedef void *rados_completion_t
;
391 * @struct blkin_trace_info
392 * blkin trace information for Zipkin tracing
394 struct blkin_trace_info
;
397 * Get the version of librados.
399 * The version number is major.minor.extra. Note that this is
400 * unrelated to the Ceph version number.
402 * TODO: define version semantics, i.e.:
403 * - incrementing major is for backwards-incompatible changes
404 * - incrementing minor is for backwards-compatible changes
405 * - incrementing extra is for bug fixes
407 * @param major where to store the major version number
408 * @param minor where to store the minor version number
409 * @param extra where to store the extra version number
411 CEPH_RADOS_API
void rados_version(int *major
, int *minor
, int *extra
);
414 * @name Setup and Teardown
415 * These are the first and last functions to that should be called
416 * when using librados.
422 * Create a handle for communicating with a RADOS cluster.
424 * Ceph environment variables are read when this is called, so if
425 * $CEPH_ARGS specifies everything you need to connect, no further
426 * configuration is necessary.
428 * @param cluster where to store the handle
429 * @param id the user to connect as (i.e. admin, not client.admin)
430 * @returns 0 on success, negative error code on failure
432 CEPH_RADOS_API
int rados_create(rados_t
*cluster
, const char * const id
);
435 * Extended version of rados_create.
437 * Like rados_create, but
438 * 1) don't assume 'client\.'+id; allow full specification of name
439 * 2) allow specification of cluster name
440 * 3) flags for future expansion
442 CEPH_RADOS_API
int rados_create2(rados_t
*pcluster
,
443 const char *const clustername
,
444 const char * const name
, uint64_t flags
);
447 * Initialize a cluster handle from an existing configuration.
449 * Share configuration state with another rados_t instance.
451 * @param cluster where to store the handle
452 * @param cct the existing configuration to use
453 * @returns 0 on success, negative error code on failure
455 CEPH_RADOS_API
int rados_create_with_context(rados_t
*cluster
,
459 * Ping the monitor with ID mon_id, storing the resulting reply in
460 * buf (if specified) with a maximum size of len.
462 * The result buffer is allocated on the heap; the caller is
463 * expected to release that memory with rados_buffer_free(). The
464 * buffer and length pointers can be NULL, in which case they are
467 * @param cluster cluster handle
468 * @param[in] mon_id ID of the monitor to ping
469 * @param[out] outstr double pointer with the resulting reply
470 * @param[out] outstrlen pointer with the size of the reply in outstr
472 CEPH_RADOS_API
int rados_ping_monitor(rados_t cluster
, const char *mon_id
,
473 char **outstr
, size_t *outstrlen
);
476 * Connect to the cluster.
478 * @note BUG: Before calling this, calling a function that communicates with the
479 * cluster will crash.
481 * @pre The cluster handle is configured with at least a monitor
482 * address. If cephx is enabled, a client name and secret must also be
485 * @post If this succeeds, any function in librados may be used
487 * @param cluster The cluster to connect to.
488 * @returns 0 on success, negative error code on failure
490 CEPH_RADOS_API
int rados_connect(rados_t cluster
);
493 * Disconnects from the cluster.
495 * For clean up, this is only necessary after rados_connect() has
498 * @warning This does not guarantee any asynchronous writes have
499 * completed. To do that, you must call rados_aio_flush() on all open
502 * @warning We implicitly call rados_watch_flush() on shutdown. If
503 * there are watches being used, this should be done explicitly before
504 * destroying the relevant IoCtx. We do it here as a safety measure.
506 * @post the cluster handle cannot be used again
508 * @param cluster the cluster to shutdown
510 CEPH_RADOS_API
void rados_shutdown(rados_t cluster
);
515 * @name Configuration
516 * These functions read and update Ceph configuration for a cluster
517 * handle. Any configuration changes must be done before connecting to
520 * Options that librados users might want to set include:
523 * - key, keyfile, or keyring when using cephx
524 * - log_file, log_to_stderr, err_to_stderr, and log_to_syslog
525 * - debug_rados, debug_objecter, debug_monc, debug_auth, or debug_ms
527 * See docs.ceph.com for information about available configuration options`
533 * Configure the cluster handle using a Ceph config file
535 * If path is NULL, the default locations are searched, and the first
536 * found is used. The locations are:
537 * - $CEPH_CONF (environment variable)
538 * - /etc/ceph/ceph.conf
540 * - ceph.conf (in the current working directory)
542 * @pre rados_connect() has not been called on the cluster handle
544 * @param cluster cluster handle to configure
545 * @param path path to a Ceph configuration file
546 * @returns 0 on success, negative error code on failure
548 CEPH_RADOS_API
int rados_conf_read_file(rados_t cluster
, const char *path
);
551 * Configure the cluster handle with command line arguments
553 * argv can contain any common Ceph command line option, including any
554 * configuration parameter prefixed by '--' and replacing spaces with
555 * dashes or underscores. For example, the following options are equivalent:
556 * - --mon-host 10.0.0.1:6789
557 * - --mon_host 10.0.0.1:6789
560 * @pre rados_connect() has not been called on the cluster handle
562 * @param cluster cluster handle to configure
563 * @param argc number of arguments in argv
564 * @param argv arguments to parse
565 * @returns 0 on success, negative error code on failure
567 CEPH_RADOS_API
int rados_conf_parse_argv(rados_t cluster
, int argc
,
572 * Configure the cluster handle with command line arguments, returning
573 * any remainders. Same rados_conf_parse_argv, except for extra
574 * remargv argument to hold returns unrecognized arguments.
576 * @pre rados_connect() has not been called on the cluster handle
578 * @param cluster cluster handle to configure
579 * @param argc number of arguments in argv
580 * @param argv arguments to parse
581 * @param remargv char* array for returned unrecognized arguments
582 * @returns 0 on success, negative error code on failure
584 CEPH_RADOS_API
int rados_conf_parse_argv_remainder(rados_t cluster
, int argc
,
586 const char **remargv
);
588 * Configure the cluster handle based on an environment variable
590 * The contents of the environment variable are parsed as if they were
591 * Ceph command line options. If var is NULL, the CEPH_ARGS
592 * environment variable is used.
594 * @pre rados_connect() has not been called on the cluster handle
596 * @note BUG: this is not threadsafe - it uses a static buffer
598 * @param cluster cluster handle to configure
599 * @param var name of the environment variable to read
600 * @returns 0 on success, negative error code on failure
602 CEPH_RADOS_API
int rados_conf_parse_env(rados_t cluster
, const char *var
);
605 * Set a configuration option
607 * @pre rados_connect() has not been called on the cluster handle
609 * @param cluster cluster handle to configure
610 * @param option option to set
611 * @param value value of the option
612 * @returns 0 on success, negative error code on failure
613 * @returns -ENOENT when the option is not a Ceph configuration option
615 CEPH_RADOS_API
int rados_conf_set(rados_t cluster
, const char *option
,
619 * Get the value of a configuration option
621 * @param cluster configuration to read
622 * @param option which option to read
623 * @param buf where to write the configuration value
624 * @param len the size of buf in bytes
625 * @returns 0 on success, negative error code on failure
626 * @returns -ENAMETOOLONG if the buffer is too short to contain the
629 CEPH_RADOS_API
int rados_conf_get(rados_t cluster
, const char *option
,
630 char *buf
, size_t len
);
635 * Read usage info about the cluster
637 * This tells you total space, space used, space available, and number
638 * of objects. These are not updated immediately when data is written,
639 * they are eventually consistent.
641 * @param cluster cluster to query
642 * @param result where to store the results
643 * @returns 0 on success, negative error code on failure
645 CEPH_RADOS_API
int rados_cluster_stat(rados_t cluster
,
646 struct rados_cluster_stat_t
*result
);
649 * Get the fsid of the cluster as a hexadecimal string.
651 * The fsid is a unique id of an entire Ceph cluster.
653 * @param cluster where to get the fsid
654 * @param buf where to write the fsid
655 * @param len the size of buf in bytes (should be 37)
656 * @returns 0 on success, negative error code on failure
657 * @returns -ERANGE if the buffer is too short to contain the
660 CEPH_RADOS_API
int rados_cluster_fsid(rados_t cluster
, char *buf
, size_t len
);
663 * Get/wait for the most recent osdmap
665 * @param cluster the cluster to shutdown
666 * @returns 0 on success, negative error code on failure
668 CEPH_RADOS_API
int rados_wait_for_latest_osdmap(rados_t cluster
);
673 * RADOS pools are separate namespaces for objects. Pools may have
674 * different crush rules associated with them, so they could have
675 * differing replication levels or placement strategies. RADOS
676 * permissions are also tied to pools - users can have different read,
677 * write, and execute permissions on a per-pool basis.
685 * Gets a list of pool names as NULL-terminated strings. The pool
686 * names will be placed in the supplied buffer one after another.
687 * After the last pool name, there will be two 0 bytes in a row.
689 * If len is too short to fit all the pool name entries we need, we will fill
692 * Buf may be null to determine the buffer size needed to list all pools.
694 * @param cluster cluster handle
695 * @param buf output buffer
696 * @param len output buffer length
697 * @returns length of the buffer we would need to list all pools
699 CEPH_RADOS_API
int rados_pool_list(rados_t cluster
, char *buf
, size_t len
);
702 * List inconsistent placement groups of the given pool
704 * Gets a list of inconsistent placement groups as NULL-terminated strings.
705 * The placement group names will be placed in the supplied buffer one after
706 * another. After the last name, there will be two 0 types in a row.
708 * If len is too short to fit all the placement group entries we need, we will
709 * fill as much as we can.
711 * @param cluster cluster handle
712 * @param pool pool ID
713 * @param buf output buffer
714 * @param len output buffer length
715 * @returns length of the buffer we would need to list all pools
717 CEPH_RADOS_API
int rados_inconsistent_pg_list(rados_t cluster
, int64_t pool
,
718 char *buf
, size_t len
);
721 * Get a configuration handle for a rados cluster handle
723 * This handle is valid only as long as the cluster handle is valid.
725 * @param cluster cluster handle
726 * @returns config handle for this cluster
728 CEPH_RADOS_API rados_config_t
rados_cct(rados_t cluster
);
731 * Get a global id for current instance
733 * This id is a unique representation of current connection to the cluster
735 * @param cluster cluster handle
736 * @returns instance global id
738 CEPH_RADOS_API
uint64_t rados_get_instance_id(rados_t cluster
);
741 * Gets the minimum compatible OSD version
743 * @param cluster cluster handle
744 * @param[out] require_osd_release minimum compatible OSD version
745 * based upon the current features
746 * @returns 0 on sucess, negative error code on failure
748 CEPH_RADOS_API
int rados_get_min_compatible_osd(rados_t cluster
,
749 int8_t* require_osd_release
);
752 * Gets the minimum compatible client version
754 * @param cluster cluster handle
755 * @param[out] min_compat_client minimum compatible client version
756 * based upon the current features
757 * @param[out] require_min_compat_client required minimum client version
758 * based upon explicit setting
759 * @returns 0 on success, negative error code on failure
761 CEPH_RADOS_API
int rados_get_min_compatible_client(rados_t cluster
,
762 int8_t* min_compat_client
,
763 int8_t* require_min_compat_client
);
766 * Create an io context
768 * The io context allows you to perform operations within a particular
769 * pool. For more details see rados_ioctx_t.
771 * @param cluster which cluster the pool is in
772 * @param pool_name name of the pool
773 * @param ioctx where to store the io context
774 * @returns 0 on success, negative error code on failure
776 CEPH_RADOS_API
int rados_ioctx_create(rados_t cluster
, const char *pool_name
,
777 rados_ioctx_t
*ioctx
);
778 CEPH_RADOS_API
int rados_ioctx_create2(rados_t cluster
, int64_t pool_id
,
779 rados_ioctx_t
*ioctx
);
782 * The opposite of rados_ioctx_create
784 * This just tells librados that you no longer need to use the io context.
785 * It may not be freed immediately if there are pending asynchronous
786 * requests on it, but you should not use an io context again after
787 * calling this function on it.
789 * @warning This does not guarantee any asynchronous
790 * writes have completed. You must call rados_aio_flush()
791 * on the io context before destroying it to do that.
793 * @warning If this ioctx is used by rados_watch, the caller needs to
794 * be sure that all registered watches are disconnected via
795 * rados_unwatch() and that rados_watch_flush() is called. This
796 * ensures that a racing watch callback does not make use of a
799 * @param io the io context to dispose of
801 CEPH_RADOS_API
void rados_ioctx_destroy(rados_ioctx_t io
);
804 * Get configuration handle for a pool handle
806 * @param io pool handle
807 * @returns rados_config_t for this cluster
809 CEPH_RADOS_API rados_config_t
rados_ioctx_cct(rados_ioctx_t io
);
812 * Get the cluster handle used by this rados_ioctx_t
813 * Note that this is a weak reference, and should not
814 * be destroyed via rados_shutdown().
816 * @param io the io context
817 * @returns the cluster handle for this io context
819 CEPH_RADOS_API rados_t
rados_ioctx_get_cluster(rados_ioctx_t io
);
822 * Get pool usage statistics
824 * Fills in a rados_pool_stat_t after querying the cluster.
826 * @param io determines which pool to query
827 * @param stats where to store the results
828 * @returns 0 on success, negative error code on failure
830 CEPH_RADOS_API
int rados_ioctx_pool_stat(rados_ioctx_t io
,
831 struct rados_pool_stat_t
*stats
);
834 * Get the id of a pool
836 * @param cluster which cluster the pool is in
837 * @param pool_name which pool to look up
838 * @returns id of the pool
839 * @returns -ENOENT if the pool is not found
841 CEPH_RADOS_API
int64_t rados_pool_lookup(rados_t cluster
,
842 const char *pool_name
);
845 * Get the name of a pool
847 * @param cluster which cluster the pool is in
848 * @param id the id of the pool
849 * @param buf where to store the pool name
850 * @param maxlen size of buffer where name will be stored
851 * @returns length of string stored, or -ERANGE if buffer too small
853 CEPH_RADOS_API
int rados_pool_reverse_lookup(rados_t cluster
, int64_t id
,
854 char *buf
, size_t maxlen
);
857 * Create a pool with default settings
859 * The default crush rule is rule 0.
861 * @param cluster the cluster in which the pool will be created
862 * @param pool_name the name of the new pool
863 * @returns 0 on success, negative error code on failure
865 CEPH_RADOS_API
int rados_pool_create(rados_t cluster
, const char *pool_name
);
868 * Create a pool owned by a specific auid.
870 * DEPRECATED: auid support has been removed, and this call will be removed in a future
873 * @param cluster the cluster in which the pool will be created
874 * @param pool_name the name of the new pool
875 * @param auid the id of the owner of the new pool
876 * @returns 0 on success, negative error code on failure
878 CEPH_RADOS_API
int rados_pool_create_with_auid(rados_t cluster
,
879 const char *pool_name
,
881 __attribute__((deprecated
));
884 * Create a pool with a specific CRUSH rule
886 * @param cluster the cluster in which the pool will be created
887 * @param pool_name the name of the new pool
888 * @param crush_rule_num which rule to use for placement in the new pool1
889 * @returns 0 on success, negative error code on failure
891 CEPH_RADOS_API
int rados_pool_create_with_crush_rule(rados_t cluster
,
892 const char *pool_name
,
893 uint8_t crush_rule_num
);
896 * Create a pool with a specific CRUSH rule and auid
898 * DEPRECATED: auid support has been removed and this call will be removed
899 * in a future release.
901 * This is a combination of rados_pool_create_with_crush_rule() and
902 * rados_pool_create_with_auid().
904 * @param cluster the cluster in which the pool will be created
905 * @param pool_name the name of the new pool
906 * @param crush_rule_num which rule to use for placement in the new pool2
907 * @param auid the id of the owner of the new pool
908 * @returns 0 on success, negative error code on failure
910 CEPH_RADOS_API
int rados_pool_create_with_all(rados_t cluster
,
911 const char *pool_name
,
913 uint8_t crush_rule_num
)
914 __attribute__((deprecated
));
917 * Returns the pool that is the base tier for this pool.
919 * The return value is the ID of the pool that should be used to read from/write to.
920 * If tiering is not set up for the pool, returns \c pool.
922 * @param cluster the cluster the pool is in
923 * @param pool ID of the pool to query
924 * @param[out] base_tier base tier, or \c pool if tiering is not configured
925 * @returns 0 on success, negative error code on failure
927 CEPH_RADOS_API
int rados_pool_get_base_tier(rados_t cluster
, int64_t pool
,
931 * Delete a pool and all data inside it
933 * The pool is removed from the cluster immediately,
934 * but the actual data is deleted in the background.
936 * @param cluster the cluster the pool is in
937 * @param pool_name which pool to delete
938 * @returns 0 on success, negative error code on failure
940 CEPH_RADOS_API
int rados_pool_delete(rados_t cluster
, const char *pool_name
);
943 * Attempt to change an io context's associated auid "owner"
945 * DEPRECATED: auid support has been removed and this call has no effect.
947 * Requires that you have write permission on both the current and new
950 * @param io reference to the pool to change.
951 * @param auid the auid you wish the io to have.
952 * @returns 0 on success, negative error code on failure
954 CEPH_RADOS_API
int rados_ioctx_pool_set_auid(rados_ioctx_t io
, uint64_t auid
)
955 __attribute__((deprecated
));
959 * Get the auid of a pool
961 * DEPRECATED: auid support has been removed and this call always reports
962 * CEPH_AUTH_UID_DEFAULT (-1).
964 * @param io pool to query
965 * @param auid where to store the auid
966 * @returns 0 on success, negative error code on failure
968 CEPH_RADOS_API
int rados_ioctx_pool_get_auid(rados_ioctx_t io
, uint64_t *auid
)
969 __attribute__((deprecated
));
971 /* deprecated, use rados_ioctx_pool_requires_alignment2 instead */
972 CEPH_RADOS_API
int rados_ioctx_pool_requires_alignment(rados_ioctx_t io
)
973 __attribute__((deprecated
));
976 * Test whether the specified pool requires alignment or not.
978 * @param io pool to query
979 * @param req 1 if alignment is supported, 0 if not.
980 * @returns 0 on success, negative error code on failure
982 CEPH_RADOS_API
int rados_ioctx_pool_requires_alignment2(rados_ioctx_t io
,
985 /* deprecated, use rados_ioctx_pool_required_alignment2 instead */
986 CEPH_RADOS_API
uint64_t rados_ioctx_pool_required_alignment(rados_ioctx_t io
)
987 __attribute__((deprecated
));
990 * Get the alignment flavor of a pool
992 * @param io pool to query
993 * @param alignment where to store the alignment flavor
994 * @returns 0 on success, negative error code on failure
996 CEPH_RADOS_API
int rados_ioctx_pool_required_alignment2(rados_ioctx_t io
,
997 uint64_t *alignment
);
1000 * Get the pool id of the io context
1002 * @param io the io context to query
1003 * @returns the id of the pool the io context uses
1005 CEPH_RADOS_API
int64_t rados_ioctx_get_id(rados_ioctx_t io
);
1008 * Get the pool name of the io context
1010 * @param io the io context to query
1011 * @param buf pointer to buffer where name will be stored
1012 * @param maxlen size of buffer where name will be stored
1013 * @returns length of string stored, or -ERANGE if buffer too small
1015 CEPH_RADOS_API
int rados_ioctx_get_pool_name(rados_ioctx_t io
, char *buf
,
1021 * @name Object Locators
1027 * Set the key for mapping objects to pgs within an io context.
1029 * The key is used instead of the object name to determine which
1030 * placement groups an object is put in. This affects all subsequent
1031 * operations of the io context - until a different locator key is
1032 * set, all objects in this io context will be placed in the same pg.
1034 * @param io the io context to change
1035 * @param key the key to use as the object locator, or NULL to discard
1036 * any previously set key
1038 CEPH_RADOS_API
void rados_ioctx_locator_set_key(rados_ioctx_t io
,
1042 * Set the namespace for objects within an io context
1044 * The namespace specification further refines a pool into different
1045 * domains. The mapping of objects to pgs is also based on this
1048 * @param io the io context to change
1049 * @param nspace the name to use as the namespace, or NULL use the
1052 CEPH_RADOS_API
void rados_ioctx_set_namespace(rados_ioctx_t io
,
1053 const char *nspace
);
1056 * Get the namespace for objects within the io context
1058 * @param io the io context to query
1059 * @param buf pointer to buffer where name will be stored
1060 * @param maxlen size of buffer where name will be stored
1061 * @returns length of string stored, or -ERANGE if buffer too small
1063 CEPH_RADOS_API
int rados_ioctx_get_namespace(rados_ioctx_t io
, char *buf
,
1069 * @name Listing Objects
1073 * Start listing objects in a pool
1075 * @param io the pool to list from
1076 * @param ctx the handle to store list context in
1077 * @returns 0 on success, negative error code on failure
1079 CEPH_RADOS_API
int rados_nobjects_list_open(rados_ioctx_t io
,
1080 rados_list_ctx_t
*ctx
);
1083 * Return hash position of iterator, rounded to the current PG
1085 * @param ctx iterator marking where you are in the listing
1086 * @returns current hash position, rounded to the current pg
1088 CEPH_RADOS_API
uint32_t rados_nobjects_list_get_pg_hash_position(rados_list_ctx_t ctx
);
1091 * Reposition object iterator to a different hash position
1093 * @param ctx iterator marking where you are in the listing
1094 * @param pos hash position to move to
1095 * @returns actual (rounded) position we moved to
1097 CEPH_RADOS_API
uint32_t rados_nobjects_list_seek(rados_list_ctx_t ctx
,
1101 * Reposition object iterator to a different position
1103 * @param ctx iterator marking where you are in the listing
1104 * @param cursor position to move to
1105 * @returns rounded position we moved to
1107 CEPH_RADOS_API
uint32_t rados_nobjects_list_seek_cursor(rados_list_ctx_t ctx
,
1108 rados_object_list_cursor cursor
);
1111 * Reposition object iterator to a different position
1113 * The returned handle must be released with rados_object_list_cursor_free().
1115 * @param ctx iterator marking where you are in the listing
1116 * @param cursor where to store cursor
1117 * @returns 0 on success, negative error code on failure
1119 CEPH_RADOS_API
int rados_nobjects_list_get_cursor(rados_list_ctx_t ctx
,
1120 rados_object_list_cursor
*cursor
);
1123 * Get the next object name and locator in the pool
1125 * *entry and *key are valid until next call to rados_nobjects_list_*
1127 * @param ctx iterator marking where you are in the listing
1128 * @param entry where to store the name of the entry
1129 * @param key where to store the object locator (set to NULL to ignore)
1130 * @param nspace where to store the object namespace (set to NULL to ignore)
1131 * @returns 0 on success, negative error code on failure
1132 * @returns -ENOENT when there are no more objects to list
1134 CEPH_RADOS_API
int rados_nobjects_list_next(rados_list_ctx_t ctx
,
1137 const char **nspace
);
1140 * Close the object listing handle.
1142 * This should be called when the handle is no longer needed.
1143 * The handle should not be used after it has been closed.
1145 * @param ctx the handle to close
1147 CEPH_RADOS_API
void rados_nobjects_list_close(rados_list_ctx_t ctx
);
1150 * Get cursor handle pointing to the *beginning* of a pool.
1152 * This is an opaque handle pointing to the start of a pool. It must
1153 * be released with rados_object_list_cursor_free().
1155 * @param io ioctx for the pool
1156 * @returns handle for the pool, NULL on error (pool does not exist)
1158 CEPH_RADOS_API rados_object_list_cursor
rados_object_list_begin(
1162 * Get cursor handle pointing to the *end* of a pool.
1164 * This is an opaque handle pointing to the start of a pool. It must
1165 * be released with rados_object_list_cursor_free().
1167 * @param io ioctx for the pool
1168 * @returns handle for the pool, NULL on error (pool does not exist)
1170 CEPH_RADOS_API rados_object_list_cursor
rados_object_list_end(rados_ioctx_t io
);
1173 * Check if a cursor has reached the end of a pool
1177 * @returns 1 if the cursor has reached the end of the pool, 0 otherwise
1179 CEPH_RADOS_API
int rados_object_list_is_end(rados_ioctx_t io
,
1180 rados_object_list_cursor cur
);
1185 * Release a cursor. The handle may not be used after this point.
1190 CEPH_RADOS_API
void rados_object_list_cursor_free(rados_ioctx_t io
,
1191 rados_object_list_cursor cur
);
1194 * Compare two cursor positions
1196 * Compare two cursors, and indicate whether the first cursor precedes,
1197 * matches, or follows the second.
1200 * @param lhs first cursor
1201 * @param rhs second cursor
1202 * @returns -1, 0, or 1 for lhs < rhs, lhs == rhs, or lhs > rhs
1204 CEPH_RADOS_API
int rados_object_list_cursor_cmp(rados_ioctx_t io
,
1205 rados_object_list_cursor lhs
, rados_object_list_cursor rhs
);
1208 * @return the number of items set in the results array
1210 CEPH_RADOS_API
int rados_object_list(rados_ioctx_t io
,
1211 const rados_object_list_cursor start
,
1212 const rados_object_list_cursor finish
,
1213 const size_t result_size
,
1214 const char *filter_buf
,
1215 const size_t filter_buf_len
,
1216 rados_object_list_item
*results
,
1217 rados_object_list_cursor
*next
);
1219 CEPH_RADOS_API
void rados_object_list_free(
1220 const size_t result_size
,
1221 rados_object_list_item
*results
);
1224 * Obtain cursors delineating a subset of a range. Use this
1225 * when you want to split up the work of iterating over the
1226 * global namespace. Expected use case is when you are iterating
1227 * in parallel, with `m` workers, and each worker taking an id `n`.
1230 * @param start start of the range to be sliced up (inclusive)
1231 * @param finish end of the range to be sliced up (exclusive)
1232 * @param n which of the m chunks you would like to get cursors for
1233 * @param m how many chunks to divide start-finish into
1234 * @param split_start cursor populated with start of the subrange (inclusive)
1235 * @param split_finish cursor populated with end of the subrange (exclusive)
1237 CEPH_RADOS_API
void rados_object_list_slice(rados_ioctx_t io
,
1238 const rados_object_list_cursor start
,
1239 const rados_object_list_cursor finish
,
1242 rados_object_list_cursor
*split_start
,
1243 rados_object_list_cursor
*split_finish
);
1246 /** @} Listing Objects */
1251 * RADOS snapshots are based upon sequence numbers that form a
1252 * snapshot context. They are pool-specific. The snapshot context
1253 * consists of the current snapshot sequence number for a pool, and an
1254 * array of sequence numbers at which snapshots were taken, in
1255 * descending order. Whenever a snapshot is created or deleted, the
1256 * snapshot sequence number for the pool is increased. To add a new
1257 * snapshot, the new snapshot sequence number must be increased and
1258 * added to the snapshot context.
1260 * There are two ways to manage these snapshot contexts:
1261 * -# within the RADOS cluster
1262 * These are called pool snapshots, and store the snapshot context
1263 * in the OSDMap. These represent a snapshot of all the objects in
1265 * -# within the RADOS clients
1266 * These are called self-managed snapshots, and push the
1267 * responsibility for keeping track of the snapshot context to the
1268 * clients. For every write, the client must send the snapshot
1269 * context. In librados, this is accomplished with
1270 * rados_selfmanaged_snap_set_write_ctx(). These are more
1271 * difficult to manage, but are restricted to specific objects
1272 * instead of applying to an entire pool.
1278 * Create a pool-wide snapshot
1280 * @param io the pool to snapshot
1281 * @param snapname the name of the snapshot
1282 * @returns 0 on success, negative error code on failure
1284 CEPH_RADOS_API
int rados_ioctx_snap_create(rados_ioctx_t io
,
1285 const char *snapname
);
1288 * Delete a pool snapshot
1290 * @param io the pool to delete the snapshot from
1291 * @param snapname which snapshot to delete
1292 * @returns 0 on success, negative error code on failure
1294 CEPH_RADOS_API
int rados_ioctx_snap_remove(rados_ioctx_t io
,
1295 const char *snapname
);
1298 * Rollback an object to a pool snapshot
1300 * The contents of the object will be the same as
1301 * when the snapshot was taken.
1303 * @param io the pool in which the object is stored
1304 * @param oid the name of the object to rollback
1305 * @param snapname which snapshot to rollback to
1306 * @returns 0 on success, negative error code on failure
1308 CEPH_RADOS_API
int rados_ioctx_snap_rollback(rados_ioctx_t io
, const char *oid
,
1309 const char *snapname
);
1312 * @warning Deprecated: Use rados_ioctx_snap_rollback() instead
1314 CEPH_RADOS_API
int rados_rollback(rados_ioctx_t io
, const char *oid
,
1315 const char *snapname
)
1316 __attribute__((deprecated
));
1319 * Set the snapshot from which reads are performed.
1321 * Subsequent reads will return data as it was at the time of that
1324 * @param io the io context to change
1325 * @param snap the id of the snapshot to set, or LIBRADOS_SNAP_HEAD for no
1326 * snapshot (i.e. normal operation)
1328 CEPH_RADOS_API
void rados_ioctx_snap_set_read(rados_ioctx_t io
,
1332 * Allocate an ID for a self-managed snapshot
1334 * Get a unique ID to put in the snaphot context to create a
1335 * snapshot. A clone of an object is not created until a write with
1336 * the new snapshot context is completed.
1338 * @param io the pool in which the snapshot will exist
1339 * @param snapid where to store the newly allocated snapshot ID
1340 * @returns 0 on success, negative error code on failure
1342 CEPH_RADOS_API
int rados_ioctx_selfmanaged_snap_create(rados_ioctx_t io
,
1343 rados_snap_t
*snapid
);
1345 rados_aio_ioctx_selfmanaged_snap_create(rados_ioctx_t io
,
1346 rados_snap_t
*snapid
,
1347 rados_completion_t completion
);
1350 * Remove a self-managed snapshot
1352 * This increases the snapshot sequence number, which will cause
1353 * snapshots to be removed lazily.
1355 * @param io the pool in which the snapshot will exist
1356 * @param snapid where to store the newly allocated snapshot ID
1357 * @returns 0 on success, negative error code on failure
1359 CEPH_RADOS_API
int rados_ioctx_selfmanaged_snap_remove(rados_ioctx_t io
,
1360 rados_snap_t snapid
);
1362 rados_aio_ioctx_selfmanaged_snap_remove(rados_ioctx_t io
,
1363 rados_snap_t snapid
,
1364 rados_completion_t completion
);
1367 * Rollback an object to a self-managed snapshot
1369 * The contents of the object will be the same as
1370 * when the snapshot was taken.
1372 * @param io the pool in which the object is stored
1373 * @param oid the name of the object to rollback
1374 * @param snapid which snapshot to rollback to
1375 * @returns 0 on success, negative error code on failure
1377 CEPH_RADOS_API
int rados_ioctx_selfmanaged_snap_rollback(rados_ioctx_t io
,
1379 rados_snap_t snapid
);
1382 * Set the snapshot context for use when writing to objects
1384 * This is stored in the io context, and applies to all future writes.
1386 * @param io the io context to change
1387 * @param seq the newest snapshot sequence number for the pool
1388 * @param snaps array of snapshots in sorted by descending id
1389 * @param num_snaps how many snaphosts are in the snaps array
1390 * @returns 0 on success, negative error code on failure
1391 * @returns -EINVAL if snaps are not in descending order
1393 CEPH_RADOS_API
int rados_ioctx_selfmanaged_snap_set_write_ctx(rados_ioctx_t io
,
1395 rados_snap_t
*snaps
,
1399 * List all the ids of pool snapshots
1401 * If the output array does not have enough space to fit all the
1402 * snapshots, -ERANGE is returned and the caller should retry with a
1405 * @param io the pool to read from
1406 * @param snaps where to store the results
1407 * @param maxlen the number of rados_snap_t that fit in the snaps array
1408 * @returns number of snapshots on success, negative error code on failure
1409 * @returns -ERANGE is returned if the snaps array is too short
1411 CEPH_RADOS_API
int rados_ioctx_snap_list(rados_ioctx_t io
, rados_snap_t
*snaps
,
1415 * Get the id of a pool snapshot
1417 * @param io the pool to read from
1418 * @param name the snapshot to find
1419 * @param id where to store the result
1420 * @returns 0 on success, negative error code on failure
1422 CEPH_RADOS_API
int rados_ioctx_snap_lookup(rados_ioctx_t io
, const char *name
,
1426 * Get the name of a pool snapshot
1428 * @param io the pool to read from
1429 * @param id the snapshot to find
1430 * @param name where to store the result
1431 * @param maxlen the size of the name array
1432 * @returns 0 on success, negative error code on failure
1433 * @returns -ERANGE if the name array is too small
1435 CEPH_RADOS_API
int rados_ioctx_snap_get_name(rados_ioctx_t io
, rados_snap_t id
,
1436 char *name
, int maxlen
);
1439 * Find when a pool snapshot occurred
1441 * @param io the pool the snapshot was taken in
1442 * @param id the snapshot to lookup
1443 * @param t where to store the result
1444 * @returns 0 on success, negative error code on failure
1446 CEPH_RADOS_API
int rados_ioctx_snap_get_stamp(rados_ioctx_t io
, rados_snap_t id
,
1452 * @name Synchronous I/O
1453 * Writes are replicated to a number of OSDs based on the
1454 * configuration of the pool they are in. These write functions block
1455 * until data is in memory on all replicas of the object they're
1456 * writing to - they are equivalent to doing the corresponding
1457 * asynchronous write, and the calling
1458 * rados_ioctx_wait_for_complete(). For greater data safety, use the
1459 * asynchronous functions and rados_aio_wait_for_safe().
1465 * Return the version of the last object read or written to.
1467 * This exposes the internal version number of the last object read or
1468 * written via this io context
1470 * @param io the io context to check
1471 * @returns last read or written object version
1473 CEPH_RADOS_API
uint64_t rados_get_last_version(rados_ioctx_t io
);
1476 * Write *len* bytes from *buf* into the *oid* object, starting at
1477 * offset *off*. The value of *len* must be <= UINT_MAX/2.
1479 * @note This will never return a positive value not equal to len.
1480 * @param io the io context in which the write will occur
1481 * @param oid name of the object
1482 * @param buf data to write
1483 * @param len length of the data, in bytes
1484 * @param off byte offset in the object to begin writing at
1485 * @returns 0 on success, negative error code on failure
1487 CEPH_RADOS_API
int rados_write(rados_ioctx_t io
, const char *oid
,
1488 const char *buf
, size_t len
, uint64_t off
);
1491 * Write *len* bytes from *buf* into the *oid* object. The value of
1492 * *len* must be <= UINT_MAX/2.
1494 * The object is filled with the provided data. If the object exists,
1495 * it is atomically truncated and then written.
1497 * @param io the io context in which the write will occur
1498 * @param oid name of the object
1499 * @param buf data to write
1500 * @param len length of the data, in bytes
1501 * @returns 0 on success, negative error code on failure
1503 CEPH_RADOS_API
int rados_write_full(rados_ioctx_t io
, const char *oid
,
1504 const char *buf
, size_t len
);
1507 * Write the same *data_len* bytes from *buf* multiple times into the
1508 * *oid* object. *write_len* bytes are written in total, which must be
1509 * a multiple of *data_len*. The value of *write_len* and *data_len*
1510 * must be <= UINT_MAX/2.
1512 * @param io the io context in which the write will occur
1513 * @param oid name of the object
1514 * @param buf data to write
1515 * @param data_len length of the data, in bytes
1516 * @param write_len the total number of bytes to write
1517 * @param off byte offset in the object to begin writing at
1518 * @returns 0 on success, negative error code on failure
1520 CEPH_RADOS_API
int rados_writesame(rados_ioctx_t io
, const char *oid
,
1521 const char *buf
, size_t data_len
,
1522 size_t write_len
, uint64_t off
);
1525 * Append *len* bytes from *buf* into the *oid* object. The value of
1526 * *len* must be <= UINT_MAX/2.
1528 * @param io the context to operate in
1529 * @param oid the name of the object
1530 * @param buf the data to append
1531 * @param len length of buf (in bytes)
1532 * @returns 0 on success, negative error code on failure
1534 CEPH_RADOS_API
int rados_append(rados_ioctx_t io
, const char *oid
,
1535 const char *buf
, size_t len
);
1538 * Read data from an object
1540 * The io context determines the snapshot to read from, if any was set
1541 * by rados_ioctx_snap_set_read().
1543 * @param io the context in which to perform the read
1544 * @param oid the name of the object to read from
1545 * @param buf where to store the results
1546 * @param len the number of bytes to read
1547 * @param off the offset to start reading from in the object
1548 * @returns number of bytes read on success, negative error code on
1551 CEPH_RADOS_API
int rados_read(rados_ioctx_t io
, const char *oid
, char *buf
,
1552 size_t len
, uint64_t off
);
1555 * Compute checksum from object data
1557 * The io context determines the snapshot to checksum, if any was set
1558 * by rados_ioctx_snap_set_read(). The length of the init_value and
1559 * resulting checksum are dependent upon the checksum type:
1565 * The checksum result is encoded the following manner:
1567 * le32 num_checksum_chunks
1569 * leXX checksum for chunk (where XX = appropriate size for the checksum type)
1570 * } * num_checksum_chunks
1572 * @param io the context in which to perform the checksum
1573 * @param oid the name of the object to checksum
1574 * @param type the checksum algorithm to utilize
1575 * @param init_value the init value for the algorithm
1576 * @param init_value_len the length of the init value
1577 * @param len the number of bytes to checksum
1578 * @param off the offset to start checksumming in the object
1579 * @param chunk_size optional length-aligned chunk size for checksums
1580 * @param pchecksum where to store the checksum result
1581 * @param checksum_len the number of bytes available for the result
1582 * @return negative error code on failure
1584 CEPH_RADOS_API
int rados_checksum(rados_ioctx_t io
, const char *oid
,
1585 rados_checksum_type_t type
,
1586 const char *init_value
, size_t init_value_len
,
1587 size_t len
, uint64_t off
, size_t chunk_size
,
1588 char *pchecksum
, size_t checksum_len
);
1593 * @note This does not delete any snapshots of the object.
1595 * @param io the pool to delete the object from
1596 * @param oid the name of the object to delete
1597 * @returns 0 on success, negative error code on failure
1599 CEPH_RADOS_API
int rados_remove(rados_ioctx_t io
, const char *oid
);
1604 * If this enlarges the object, the new area is logically filled with
1605 * zeroes. If this shrinks the object, the excess data is removed.
1607 * @param io the context in which to truncate
1608 * @param oid the name of the object
1609 * @param size the new size of the object in bytes
1610 * @returns 0 on success, negative error code on failure
1612 CEPH_RADOS_API
int rados_trunc(rados_ioctx_t io
, const char *oid
,
1616 * Compare an on-disk object range with a buffer
1618 * @param io the context in which to perform the comparison
1619 * @param o name of the object
1620 * @param cmp_buf buffer containing bytes to be compared with object contents
1621 * @param cmp_len length to compare and size of @c cmp_buf in bytes
1622 * @param off object byte offset at which to start the comparison
1623 * @returns 0 on success, negative error code on failure,
1624 * (-MAX_ERRNO - mismatch_off) on mismatch
1626 CEPH_RADOS_API
int rados_cmpext(rados_ioctx_t io
, const char *o
,
1627 const char *cmp_buf
, size_t cmp_len
,
1632 * Extended attributes are stored as extended attributes on the files
1633 * representing an object on the OSDs. Thus, they have the same
1634 * limitations as the underlying filesystem. On ext4, this means that
1635 * the total data stored in xattrs cannot exceed 4KB.
1641 * Get the value of an extended attribute on an object.
1643 * @param io the context in which the attribute is read
1644 * @param o name of the object
1645 * @param name which extended attribute to read
1646 * @param buf where to store the result
1647 * @param len size of buf in bytes
1648 * @returns length of xattr value on success, negative error code on failure
1650 CEPH_RADOS_API
int rados_getxattr(rados_ioctx_t io
, const char *o
,
1651 const char *name
, char *buf
, size_t len
);
1654 * Set an extended attribute on an object.
1656 * @param io the context in which xattr is set
1657 * @param o name of the object
1658 * @param name which extended attribute to set
1659 * @param buf what to store in the xattr
1660 * @param len the number of bytes in buf
1661 * @returns 0 on success, negative error code on failure
1663 CEPH_RADOS_API
int rados_setxattr(rados_ioctx_t io
, const char *o
,
1664 const char *name
, const char *buf
,
1668 * Delete an extended attribute from an object.
1670 * @param io the context in which to delete the xattr
1671 * @param o the name of the object
1672 * @param name which xattr to delete
1673 * @returns 0 on success, negative error code on failure
1675 CEPH_RADOS_API
int rados_rmxattr(rados_ioctx_t io
, const char *o
,
1679 * Start iterating over xattrs on an object.
1681 * @post iter is a valid iterator
1683 * @param io the context in which to list xattrs
1684 * @param oid name of the object
1685 * @param iter where to store the iterator
1686 * @returns 0 on success, negative error code on failure
1688 CEPH_RADOS_API
int rados_getxattrs(rados_ioctx_t io
, const char *oid
,
1689 rados_xattrs_iter_t
*iter
);
1692 * Get the next xattr on the object
1694 * @pre iter is a valid iterator
1696 * @post name is the NULL-terminated name of the next xattr, and val
1697 * contains the value of the xattr, which is of length len. If the end
1698 * of the list has been reached, name and val are NULL, and len is 0.
1700 * @param iter iterator to advance
1701 * @param name where to store the name of the next xattr
1702 * @param val where to store the value of the next xattr
1703 * @param len the number of bytes in val
1704 * @returns 0 on success, negative error code on failure
1706 CEPH_RADOS_API
int rados_getxattrs_next(rados_xattrs_iter_t iter
,
1707 const char **name
, const char **val
,
1711 * Close the xattr iterator.
1713 * iter should not be used after this is called.
1715 * @param iter the iterator to close
1717 CEPH_RADOS_API
void rados_getxattrs_end(rados_xattrs_iter_t iter
);
1722 * Get the next omap key/value pair on the object
1724 * @pre iter is a valid iterator
1726 * @post key and val are the next key/value pair. key is
1727 * null-terminated, and val has length len. If the end of the list has
1728 * been reached, key and val are NULL, and len is 0. key and val will
1729 * not be accessible after rados_omap_get_end() is called on iter, so
1730 * if they are needed after that they should be copied.
1732 * @param iter iterator to advance
1733 * @param key where to store the key of the next omap entry
1734 * @param val where to store the value of the next omap entry
1735 * @param len where to store the number of bytes in val
1736 * @returns 0 on success, negative error code on failure
1738 CEPH_RADOS_API
int rados_omap_get_next(rados_omap_iter_t iter
,
1744 * Get the next omap key/value pair on the object. Note that it's
1745 * perfectly safe to mix calls to rados_omap_get_next and
1746 * rados_omap_get_next2.
1748 * @pre iter is a valid iterator
1750 * @post key and val are the next key/value pair. key has length
1751 * keylen and val has length vallen. If the end of the list has
1752 * been reached, key and val are NULL, and keylen and vallen is 0.
1753 * key and val will not be accessible after rados_omap_get_end()
1754 * is called on iter, so if they are needed after that they
1757 * @param iter iterator to advance
1758 * @param key where to store the key of the next omap entry
1759 * @param val where to store the value of the next omap entry
1760 * @param key_len where to store the number of bytes in key
1761 * @param val_len where to store the number of bytes in val
1762 * @returns 0 on success, negative error code on failure
1764 CEPH_RADOS_API
int rados_omap_get_next2(rados_omap_iter_t iter
,
1771 * Return number of elements in the iterator
1773 * @param iter the iterator of which to return the size
1775 CEPH_RADOS_API
unsigned int rados_omap_iter_size(rados_omap_iter_t iter
);
1778 * Close the omap iterator.
1780 * iter should not be used after this is called.
1782 * @param iter the iterator to close
1784 CEPH_RADOS_API
void rados_omap_get_end(rados_omap_iter_t iter
);
1787 * Get object stats (size/mtime)
1789 * TODO: when are these set, and by whom? can they be out of date?
1792 * @param o object name
1793 * @param psize where to store object size
1794 * @param pmtime where to store modification time
1795 * @returns 0 on success, negative error code on failure
1797 CEPH_RADOS_API
int rados_stat(rados_ioctx_t io
, const char *o
, uint64_t *psize
,
1800 * Execute an OSD class method on an object
1802 * The OSD has a plugin mechanism for performing complicated
1803 * operations on an object atomically. These plugins are called
1804 * classes. This function allows librados users to call the custom
1805 * methods. The input and output formats are defined by the class.
1806 * Classes in ceph.git can be found in src/cls subdirectories
1808 * @param io the context in which to call the method
1809 * @param oid the object to call the method on
1810 * @param cls the name of the class
1811 * @param method the name of the method
1812 * @param in_buf where to find input
1813 * @param in_len length of in_buf in bytes
1814 * @param buf where to store output
1815 * @param out_len length of buf in bytes
1816 * @returns the length of the output, or
1817 * -ERANGE if out_buf does not have enough space to store it (For methods that return data). For
1818 * methods that don't return data, the return value is
1821 CEPH_RADOS_API
int rados_exec(rados_ioctx_t io
, const char *oid
,
1822 const char *cls
, const char *method
,
1823 const char *in_buf
, size_t in_len
, char *buf
,
1827 /** @} Synchronous I/O */
1830 * @name Asynchronous I/O
1831 * Read and write to objects without blocking.
1837 * @typedef rados_callback_t
1838 * Callbacks for asynchrous operations take two parameters:
1839 * - cb the completion that has finished
1840 * - arg application defined data made available to the callback function
1842 typedef void (*rados_callback_t
)(rados_completion_t cb
, void *arg
);
1845 * Constructs a completion to use with asynchronous operations
1847 * The complete and safe callbacks correspond to operations being
1848 * acked and committed, respectively. The callbacks are called in
1849 * order of receipt, so the safe callback may be triggered before the
1850 * complete callback, and vice versa. This is affected by journalling
1853 * TODO: more complete documentation of this elsewhere (in the RADOS docs?)
1855 * @note Read operations only get a complete callback.
1856 * @note BUG: this should check for ENOMEM instead of throwing an exception
1858 * @param cb_arg application-defined data passed to the callback functions
1859 * @param cb_complete the function to be called when the operation is
1860 * in memory on all replicas
1861 * @param cb_safe the function to be called when the operation is on
1862 * stable storage on all replicas
1863 * @param pc where to store the completion
1866 CEPH_RADOS_API
int rados_aio_create_completion(void *cb_arg
,
1867 rados_callback_t cb_complete
,
1868 rados_callback_t cb_safe
,
1869 rados_completion_t
*pc
);
1872 * Constructs a completion to use with asynchronous operations
1874 * The complete callback corresponds to operation being acked.
1876 * @note BUG: this should check for ENOMEM instead of throwing an exception
1878 * @param cb_arg application-defined data passed to the callback functions
1879 * @param cb_complete the function to be called when the operation is committed
1881 * @param pc where to store the completion
1884 CEPH_RADOS_API
int rados_aio_create_completion2(void *cb_arg
,
1885 rados_callback_t cb_complete
,
1886 rados_completion_t
*pc
);
1889 * Block until an operation completes
1891 * This means it is in memory on all replicas.
1893 * @note BUG: this should be void
1895 * @param c operation to wait for
1898 CEPH_RADOS_API
int rados_aio_wait_for_complete(rados_completion_t c
);
1901 * Block until an operation is safe
1903 * This means it is on stable storage on all replicas.
1905 * @note BUG: this should be void
1907 * @param c operation to wait for
1910 CEPH_RADOS_API
int rados_aio_wait_for_safe(rados_completion_t c
)
1911 __attribute__((deprecated
));
1914 * Has an asynchronous operation completed?
1916 * @warning This does not imply that the complete callback has
1919 * @param c async operation to inspect
1920 * @returns whether c is complete
1922 CEPH_RADOS_API
int rados_aio_is_complete(rados_completion_t c
);
1925 * Is an asynchronous operation safe?
1927 * @warning This does not imply that the safe callback has
1930 * @param c async operation to inspect
1931 * @returns whether c is safe
1933 CEPH_RADOS_API
int rados_aio_is_safe(rados_completion_t c
);
1936 * Block until an operation completes and callback completes
1938 * This means it is in memory on all replicas and can be read.
1940 * @note BUG: this should be void
1942 * @param c operation to wait for
1945 CEPH_RADOS_API
int rados_aio_wait_for_complete_and_cb(rados_completion_t c
);
1948 * Block until an operation is safe and callback has completed
1950 * This means it is on stable storage on all replicas.
1952 * @note BUG: this should be void
1954 * @param c operation to wait for
1957 CEPH_RADOS_API
int rados_aio_wait_for_safe_and_cb(rados_completion_t c
)
1958 __attribute__((deprecated
));
1961 * Has an asynchronous operation and callback completed
1963 * @param c async operation to inspect
1964 * @returns whether c is complete
1966 CEPH_RADOS_API
int rados_aio_is_complete_and_cb(rados_completion_t c
);
1969 * Is an asynchronous operation safe and has the callback completed
1971 * @param c async operation to inspect
1972 * @returns whether c is safe
1974 CEPH_RADOS_API
int rados_aio_is_safe_and_cb(rados_completion_t c
);
1977 * Get the return value of an asychronous operation
1979 * The return value is set when the operation is complete or safe,
1980 * whichever comes first.
1982 * @pre The operation is safe or complete
1984 * @note BUG: complete callback may never be called when the safe
1985 * message is received before the complete message
1987 * @param c async operation to inspect
1988 * @returns return value of the operation
1990 CEPH_RADOS_API
int rados_aio_get_return_value(rados_completion_t c
);
1993 * Get the internal object version of the target of an asychronous operation
1995 * The return value is set when the operation is complete or safe,
1996 * whichever comes first.
1998 * @pre The operation is safe or complete
2000 * @note BUG: complete callback may never be called when the safe
2001 * message is received before the complete message
2003 * @param c async operation to inspect
2004 * @returns version number of the asychronous operation's target
2006 CEPH_RADOS_API
uint64_t rados_aio_get_version(rados_completion_t c
);
2009 * Release a completion
2011 * Call this when you no longer need the completion. It may not be
2012 * freed immediately if the operation is not acked and committed.
2014 * @param c completion to release
2016 CEPH_RADOS_API
void rados_aio_release(rados_completion_t c
);
2019 * Write data to an object asynchronously
2021 * Queues the write and returns. The return value of the completion
2022 * will be 0 on success, negative error code on failure.
2024 * @param io the context in which the write will occur
2025 * @param oid name of the object
2026 * @param completion what to do when the write is safe and complete
2027 * @param buf data to write
2028 * @param len length of the data, in bytes
2029 * @param off byte offset in the object to begin writing at
2030 * @returns 0 on success, -EROFS if the io context specifies a snap_seq
2031 * other than LIBRADOS_SNAP_HEAD
2033 CEPH_RADOS_API
int rados_aio_write(rados_ioctx_t io
, const char *oid
,
2034 rados_completion_t completion
,
2035 const char *buf
, size_t len
, uint64_t off
);
2038 * Asynchronously append data to an object
2040 * Queues the append and returns.
2042 * The return value of the completion will be 0 on success, negative
2043 * error code on failure.
2045 * @param io the context to operate in
2046 * @param oid the name of the object
2047 * @param completion what to do when the append is safe and complete
2048 * @param buf the data to append
2049 * @param len length of buf (in bytes)
2050 * @returns 0 on success, -EROFS if the io context specifies a snap_seq
2051 * other than LIBRADOS_SNAP_HEAD
2053 CEPH_RADOS_API
int rados_aio_append(rados_ioctx_t io
, const char *oid
,
2054 rados_completion_t completion
,
2055 const char *buf
, size_t len
);
2058 * Asynchronously write an entire object
2060 * The object is filled with the provided data. If the object exists,
2061 * it is atomically truncated and then written.
2062 * Queues the write_full and returns.
2064 * The return value of the completion will be 0 on success, negative
2065 * error code on failure.
2067 * @param io the io context in which the write will occur
2068 * @param oid name of the object
2069 * @param completion what to do when the write_full is safe and complete
2070 * @param buf data to write
2071 * @param len length of the data, in bytes
2072 * @returns 0 on success, -EROFS if the io context specifies a snap_seq
2073 * other than LIBRADOS_SNAP_HEAD
2075 CEPH_RADOS_API
int rados_aio_write_full(rados_ioctx_t io
, const char *oid
,
2076 rados_completion_t completion
,
2077 const char *buf
, size_t len
);
2080 * Asynchronously write the same buffer multiple times
2082 * Queues the writesame and returns.
2084 * The return value of the completion will be 0 on success, negative
2085 * error code on failure.
2087 * @param io the io context in which the write will occur
2088 * @param oid name of the object
2089 * @param completion what to do when the writesame is safe and complete
2090 * @param buf data to write
2091 * @param data_len length of the data, in bytes
2092 * @param write_len the total number of bytes to write
2093 * @param off byte offset in the object to begin writing at
2094 * @returns 0 on success, -EROFS if the io context specifies a snap_seq
2095 * other than LIBRADOS_SNAP_HEAD
2097 CEPH_RADOS_API
int rados_aio_writesame(rados_ioctx_t io
, const char *oid
,
2098 rados_completion_t completion
,
2099 const char *buf
, size_t data_len
,
2100 size_t write_len
, uint64_t off
);
2103 * Asynchronously remove an object
2105 * Queues the remove and returns.
2107 * The return value of the completion will be 0 on success, negative
2108 * error code on failure.
2110 * @param io the context to operate in
2111 * @param oid the name of the object
2112 * @param completion what to do when the remove is safe and complete
2113 * @returns 0 on success, -EROFS if the io context specifies a snap_seq
2114 * other than LIBRADOS_SNAP_HEAD
2116 CEPH_RADOS_API
int rados_aio_remove(rados_ioctx_t io
, const char *oid
,
2117 rados_completion_t completion
);
2120 * Asynchronously read data from an object
2122 * The io context determines the snapshot to read from, if any was set
2123 * by rados_ioctx_snap_set_read().
2125 * The return value of the completion will be number of bytes read on
2126 * success, negative error code on failure.
2128 * @note only the 'complete' callback of the completion will be called.
2130 * @param io the context in which to perform the read
2131 * @param oid the name of the object to read from
2132 * @param completion what to do when the read is complete
2133 * @param buf where to store the results
2134 * @param len the number of bytes to read
2135 * @param off the offset to start reading from in the object
2136 * @returns 0 on success, negative error code on failure
2138 CEPH_RADOS_API
int rados_aio_read(rados_ioctx_t io
, const char *oid
,
2139 rados_completion_t completion
,
2140 char *buf
, size_t len
, uint64_t off
);
2143 * Block until all pending writes in an io context are safe
2145 * This is not equivalent to calling rados_aio_wait_for_safe() on all
2146 * write completions, since this waits for the associated callbacks to
2149 * @note BUG: always returns 0, should be void or accept a timeout
2151 * @param io the context to flush
2152 * @returns 0 on success, negative error code on failure
2154 CEPH_RADOS_API
int rados_aio_flush(rados_ioctx_t io
);
2158 * Schedule a callback for when all currently pending
2159 * aio writes are safe. This is a non-blocking version of
2160 * rados_aio_flush().
2162 * @param io the context to flush
2163 * @param completion what to do when the writes are safe
2164 * @returns 0 on success, negative error code on failure
2166 CEPH_RADOS_API
int rados_aio_flush_async(rados_ioctx_t io
,
2167 rados_completion_t completion
);
2171 * Asynchronously get object stats (size/mtime)
2174 * @param o object name
2175 * @param completion what to do when the stat is complete
2176 * @param psize where to store object size
2177 * @param pmtime where to store modification time
2178 * @returns 0 on success, negative error code on failure
2180 CEPH_RADOS_API
int rados_aio_stat(rados_ioctx_t io
, const char *o
,
2181 rados_completion_t completion
,
2182 uint64_t *psize
, time_t *pmtime
);
2185 * Asynchronously compare an on-disk object range with a buffer
2187 * @param io the context in which to perform the comparison
2188 * @param o the name of the object to compare with
2189 * @param completion what to do when the comparison is complete
2190 * @param cmp_buf buffer containing bytes to be compared with object contents
2191 * @param cmp_len length to compare and size of @c cmp_buf in bytes
2192 * @param off object byte offset at which to start the comparison
2193 * @returns 0 on success, negative error code on failure,
2194 * (-MAX_ERRNO - mismatch_off) on mismatch
2196 CEPH_RADOS_API
int rados_aio_cmpext(rados_ioctx_t io
, const char *o
,
2197 rados_completion_t completion
,
2198 const char *cmp_buf
,
2203 * Cancel async operation
2206 * @param completion completion handle
2207 * @returns 0 on success, negative error code on failure
2209 CEPH_RADOS_API
int rados_aio_cancel(rados_ioctx_t io
,
2210 rados_completion_t completion
);
2213 * Asynchronously execute an OSD class method on an object
2215 * The OSD has a plugin mechanism for performing complicated
2216 * operations on an object atomically. These plugins are called
2217 * classes. This function allows librados users to call the custom
2218 * methods. The input and output formats are defined by the class.
2219 * Classes in ceph.git can be found in src/cls subdirectories
2221 * @param io the context in which to call the method
2222 * @param o name of the object
2223 * @param completion what to do when the exec completes
2224 * @param cls the name of the class
2225 * @param method the name of the method
2226 * @param in_buf where to find input
2227 * @param in_len length of in_buf in bytes
2228 * @param buf where to store output
2229 * @param out_len length of buf in bytes
2230 * @returns 0 on success, negative error code on failure
2232 CEPH_RADOS_API
int rados_aio_exec(rados_ioctx_t io
, const char *o
,
2233 rados_completion_t completion
,
2234 const char *cls
, const char *method
,
2235 const char *in_buf
, size_t in_len
,
2236 char *buf
, size_t out_len
);
2238 /** @} Asynchronous I/O */
2241 * @name Asynchronous Xattrs
2242 * Extended attributes are stored as extended attributes on the files
2243 * representing an object on the OSDs. Thus, they have the same
2244 * limitations as the underlying filesystem. On ext4, this means that
2245 * the total data stored in xattrs cannot exceed 4KB.
2251 * Asynchronously get the value of an extended attribute on an object.
2253 * @param io the context in which the attribute is read
2254 * @param o name of the object
2255 * @param completion what to do when the getxattr completes
2256 * @param name which extended attribute to read
2257 * @param buf where to store the result
2258 * @param len size of buf in bytes
2259 * @returns length of xattr value on success, negative error code on failure
2261 CEPH_RADOS_API
int rados_aio_getxattr(rados_ioctx_t io
, const char *o
,
2262 rados_completion_t completion
,
2263 const char *name
, char *buf
, size_t len
);
2266 * Asynchronously set an extended attribute on an object.
2268 * @param io the context in which xattr is set
2269 * @param o name of the object
2270 * @param completion what to do when the setxattr completes
2271 * @param name which extended attribute to set
2272 * @param buf what to store in the xattr
2273 * @param len the number of bytes in buf
2274 * @returns 0 on success, negative error code on failure
2276 CEPH_RADOS_API
int rados_aio_setxattr(rados_ioctx_t io
, const char *o
,
2277 rados_completion_t completion
,
2278 const char *name
, const char *buf
,
2282 * Asynchronously delete an extended attribute from an object.
2284 * @param io the context in which to delete the xattr
2285 * @param o the name of the object
2286 * @param completion what to do when the rmxattr completes
2287 * @param name which xattr to delete
2288 * @returns 0 on success, negative error code on failure
2290 CEPH_RADOS_API
int rados_aio_rmxattr(rados_ioctx_t io
, const char *o
,
2291 rados_completion_t completion
,
2295 * Asynchronously start iterating over xattrs on an object.
2297 * @post iter is a valid iterator
2299 * @param io the context in which to list xattrs
2300 * @param oid name of the object
2301 * @param completion what to do when the getxattrs completes
2302 * @param iter where to store the iterator
2303 * @returns 0 on success, negative error code on failure
2305 CEPH_RADOS_API
int rados_aio_getxattrs(rados_ioctx_t io
, const char *oid
,
2306 rados_completion_t completion
,
2307 rados_xattrs_iter_t
*iter
);
2309 /** @} Asynchronous Xattrs */
2312 * @name Watch/Notify
2314 * Watch/notify is a protocol to help communicate among clients. It
2315 * can be used to sychronize client state. All that's needed is a
2316 * well-known object name (for example, rbd uses the header object of
2319 * Watchers register an interest in an object, and receive all
2320 * notifies on that object. A notify attempts to communicate with all
2321 * clients watching an object, and blocks on the notifier until each
2322 * client responds or a timeout is reached.
2324 * See rados_watch() and rados_notify() for more details.
2330 * @typedef rados_watchcb_t
2332 * Callback activated when a notify is received on a watched
2335 * @param opcode undefined
2336 * @param ver version of the watched object
2337 * @param arg application-specific data
2339 * @note BUG: opcode is an internal detail that shouldn't be exposed
2340 * @note BUG: ver is unused
2342 typedef void (*rados_watchcb_t
)(uint8_t opcode
, uint64_t ver
, void *arg
);
2345 * @typedef rados_watchcb2_t
2347 * Callback activated when a notify is received on a watched
2350 * @param arg opaque user-defined value provided to rados_watch2()
2351 * @param notify_id an id for this notify event
2352 * @param handle the watcher handle we are notifying
2353 * @param notifier_id the unique client id for the notifier
2354 * @param data payload from the notifier
2355 * @param datalen length of payload buffer
2357 typedef void (*rados_watchcb2_t
)(void *arg
,
2360 uint64_t notifier_id
,
2365 * @typedef rados_watcherrcb_t
2367 * Callback activated when we encounter an error with the watch session.
2368 * This can happen when the location of the objects moves within the
2369 * cluster and we fail to register our watch with the new object location,
2370 * or when our connection with the object OSD is otherwise interrupted and
2371 * we may have missed notify events.
2373 * @param pre opaque user-defined value provided to rados_watch2()
2374 * @param err error code
2376 typedef void (*rados_watcherrcb_t
)(void *pre
, uint64_t cookie
, int err
);
2379 * Register an interest in an object
2381 * A watch operation registers the client as being interested in
2382 * notifications on an object. OSDs keep track of watches on
2383 * persistent storage, so they are preserved across cluster changes by
2384 * the normal recovery process. If the client loses its connection to
2385 * the primary OSD for a watched object, the watch will be removed
2386 * after 30 seconds. Watches are automatically reestablished when a new
2387 * connection is made, or a placement group switches OSDs.
2389 * @note BUG: librados should provide a way for watchers to notice connection resets
2390 * @note BUG: the ver parameter does not work, and -ERANGE will never be returned
2391 * (See URL tracker.ceph.com/issues/2592)
2393 * @param io the pool the object is in
2394 * @param o the object to watch
2395 * @param ver expected version of the object
2396 * @param cookie where to store the internal id assigned to this watch
2397 * @param watchcb what to do when a notify is received on this object
2398 * @param arg application defined data to pass when watchcb is called
2399 * @returns 0 on success, negative error code on failure
2400 * @returns -ERANGE if the version of the object is greater than ver
2402 CEPH_RADOS_API
int rados_watch(rados_ioctx_t io
, const char *o
, uint64_t ver
,
2404 rados_watchcb_t watchcb
, void *arg
)
2405 __attribute__((deprecated
));
2409 * Register an interest in an object
2411 * A watch operation registers the client as being interested in
2412 * notifications on an object. OSDs keep track of watches on
2413 * persistent storage, so they are preserved across cluster changes by
2414 * the normal recovery process. If the client loses its connection to the
2415 * primary OSD for a watched object, the watch will be removed after
2416 * a timeout configured with osd_client_watch_timeout.
2417 * Watches are automatically reestablished when a new
2418 * connection is made, or a placement group switches OSDs.
2420 * @param io the pool the object is in
2421 * @param o the object to watch
2422 * @param cookie where to store the internal id assigned to this watch
2423 * @param watchcb what to do when a notify is received on this object
2424 * @param watcherrcb what to do when the watch session encounters an error
2425 * @param arg opaque value to pass to the callback
2426 * @returns 0 on success, negative error code on failure
2428 CEPH_RADOS_API
int rados_watch2(rados_ioctx_t io
, const char *o
, uint64_t *cookie
,
2429 rados_watchcb2_t watchcb
,
2430 rados_watcherrcb_t watcherrcb
,
2434 * Register an interest in an object
2436 * A watch operation registers the client as being interested in
2437 * notifications on an object. OSDs keep track of watches on
2438 * persistent storage, so they are preserved across cluster changes by
2439 * the normal recovery process. Watches are automatically reestablished when a new
2440 * connection is made, or a placement group switches OSDs.
2442 * @param io the pool the object is in
2443 * @param o the object to watch
2444 * @param cookie where to store the internal id assigned to this watch
2445 * @param watchcb what to do when a notify is received on this object
2446 * @param watcherrcb what to do when the watch session encounters an error
2447 * @param timeout how many seconds the connection will keep after disconnection
2448 * @param arg opaque value to pass to the callback
2449 * @returns 0 on success, negative error code on failure
2451 CEPH_RADOS_API
int rados_watch3(rados_ioctx_t io
, const char *o
, uint64_t *cookie
,
2452 rados_watchcb2_t watchcb
,
2453 rados_watcherrcb_t watcherrcb
,
2458 * Asynchronous register an interest in an object
2460 * A watch operation registers the client as being interested in
2461 * notifications on an object. OSDs keep track of watches on
2462 * persistent storage, so they are preserved across cluster changes by
2463 * the normal recovery process. If the client loses its connection to
2464 * the primary OSD for a watched object, the watch will be removed
2465 * after 30 seconds. Watches are automatically reestablished when a new
2466 * connection is made, or a placement group switches OSDs.
2468 * @param io the pool the object is in
2469 * @param o the object to watch
2470 * @param completion what to do when operation has been attempted
2471 * @param handle where to store the internal id assigned to this watch
2472 * @param watchcb what to do when a notify is received on this object
2473 * @param watcherrcb what to do when the watch session encounters an error
2474 * @param arg opaque value to pass to the callback
2475 * @returns 0 on success, negative error code on failure
2477 CEPH_RADOS_API
int rados_aio_watch(rados_ioctx_t io
, const char *o
,
2478 rados_completion_t completion
, uint64_t *handle
,
2479 rados_watchcb2_t watchcb
,
2480 rados_watcherrcb_t watcherrcb
,
2484 * Asynchronous register an interest in an object
2486 * A watch operation registers the client as being interested in
2487 * notifications on an object. OSDs keep track of watches on
2488 * persistent storage, so they are preserved across cluster changes by
2489 * the normal recovery process. If the client loses its connection to
2490 * the primary OSD for a watched object, the watch will be removed
2491 * after the number of seconds that configured in timeout parameter.
2492 * Watches are automatically reestablished when a new
2493 * connection is made, or a placement group switches OSDs.
2495 * @param io the pool the object is in
2496 * @param o the object to watch
2497 * @param completion what to do when operation has been attempted
2498 * @param handle where to store the internal id assigned to this watch
2499 * @param watchcb what to do when a notify is received on this object
2500 * @param watcherrcb what to do when the watch session encounters an error
2501 * @param timeout how many seconds the connection will keep after disconnection
2502 * @param arg opaque value to pass to the callback
2503 * @returns 0 on success, negative error code on failure
2505 CEPH_RADOS_API
int rados_aio_watch2(rados_ioctx_t io
, const char *o
,
2506 rados_completion_t completion
, uint64_t *handle
,
2507 rados_watchcb2_t watchcb
,
2508 rados_watcherrcb_t watcherrcb
,
2513 * Check on the status of a watch
2515 * Return the number of milliseconds since the watch was last confirmed.
2516 * Or, if there has been an error, return that.
2518 * If there is an error, the watch is no longer valid, and should be
2519 * destroyed with rados_unwatch2(). The the user is still interested
2520 * in the object, a new watch should be created with rados_watch2().
2522 * @param io the pool the object is in
2523 * @param cookie the watch handle
2524 * @returns ms since last confirmed on success, negative error code on failure
2526 CEPH_RADOS_API
int rados_watch_check(rados_ioctx_t io
, uint64_t cookie
);
2529 * Unregister an interest in an object
2531 * Once this completes, no more notifies will be sent to us for this
2532 * watch. This should be called to clean up unneeded watchers.
2534 * @param io the pool the object is in
2535 * @param o the name of the watched object (ignored)
2536 * @param cookie which watch to unregister
2537 * @returns 0 on success, negative error code on failure
2539 CEPH_RADOS_API
int rados_unwatch(rados_ioctx_t io
, const char *o
, uint64_t cookie
)
2540 __attribute__((deprecated
));
2543 * Unregister an interest in an object
2545 * Once this completes, no more notifies will be sent to us for this
2546 * watch. This should be called to clean up unneeded watchers.
2548 * @param io the pool the object is in
2549 * @param cookie which watch to unregister
2550 * @returns 0 on success, negative error code on failure
2552 CEPH_RADOS_API
int rados_unwatch2(rados_ioctx_t io
, uint64_t cookie
);
2555 * Asynchronous unregister an interest in an object
2557 * Once this completes, no more notifies will be sent to us for this
2558 * watch. This should be called to clean up unneeded watchers.
2560 * @param io the pool the object is in
2561 * @param completion what to do when operation has been attempted
2562 * @param cookie which watch to unregister
2563 * @returns 0 on success, negative error code on failure
2565 CEPH_RADOS_API
int rados_aio_unwatch(rados_ioctx_t io
, uint64_t cookie
,
2566 rados_completion_t completion
);
2569 * Sychronously notify watchers of an object
2571 * This blocks until all watchers of the object have received and
2572 * reacted to the notify, or a timeout is reached.
2574 * @note BUG: the timeout is not changeable via the C API
2575 * @note BUG: the bufferlist is inaccessible in a rados_watchcb_t
2577 * @param io the pool the object is in
2578 * @param o the name of the object
2579 * @param ver obsolete - just pass zero
2580 * @param buf data to send to watchers
2581 * @param buf_len length of buf in bytes
2582 * @returns 0 on success, negative error code on failure
2584 CEPH_RADOS_API
int rados_notify(rados_ioctx_t io
, const char *o
, uint64_t ver
,
2585 const char *buf
, int buf_len
)
2586 __attribute__((deprecated
));
2589 * Sychronously notify watchers of an object
2591 * This blocks until all watchers of the object have received and
2592 * reacted to the notify, or a timeout is reached.
2594 * The reply buffer is optional. If specified, the client will get
2595 * back an encoded buffer that includes the ids of the clients that
2596 * acknowledged the notify as well as their notify ack payloads (if
2597 * any). Clients that timed out are not included. Even clients that
2598 * do not include a notify ack payload are included in the list but
2599 * have a 0-length payload associated with them. The format:
2603 * le64 gid global id for the client (for client.1234 that's 1234)
2604 * le64 cookie cookie for the client
2605 * le32 buflen length of reply message buffer
2606 * u8 * buflen payload
2610 * le64 gid global id for the client
2611 * le64 cookie cookie for the client
2614 * Note: There may be multiple instances of the same gid if there are
2615 * multiple watchers registered via the same client.
2617 * Note: The buffer must be released with rados_buffer_free() when the
2618 * user is done with it.
2620 * Note: Since the result buffer includes clients that time out, it
2621 * will be set even when rados_notify() returns an error code (like
2624 * @param io the pool the object is in
2625 * @param completion what to do when operation has been attempted
2626 * @param o the name of the object
2627 * @param buf data to send to watchers
2628 * @param buf_len length of buf in bytes
2629 * @param timeout_ms notify timeout (in ms)
2630 * @param reply_buffer pointer to reply buffer pointer (free with rados_buffer_free)
2631 * @param reply_buffer_len pointer to size of reply buffer
2632 * @returns 0 on success, negative error code on failure
2634 CEPH_RADOS_API
int rados_aio_notify(rados_ioctx_t io
, const char *o
,
2635 rados_completion_t completion
,
2636 const char *buf
, int buf_len
,
2637 uint64_t timeout_ms
, char **reply_buffer
,
2638 size_t *reply_buffer_len
);
2639 CEPH_RADOS_API
int rados_notify2(rados_ioctx_t io
, const char *o
,
2640 const char *buf
, int buf_len
,
2641 uint64_t timeout_ms
,
2642 char **reply_buffer
, size_t *reply_buffer_len
);
2645 * Acknolwedge receipt of a notify
2647 * @param io the pool the object is in
2648 * @param o the name of the object
2649 * @param notify_id the notify_id we got on the watchcb2_t callback
2650 * @param cookie the watcher handle
2651 * @param buf payload to return to notifier (optional)
2652 * @param buf_len payload length
2653 * @returns 0 on success
2655 CEPH_RADOS_API
int rados_notify_ack(rados_ioctx_t io
, const char *o
,
2656 uint64_t notify_id
, uint64_t cookie
,
2657 const char *buf
, int buf_len
);
2660 * Flush watch/notify callbacks
2662 * This call will block until all pending watch/notify callbacks have
2663 * been executed and the queue is empty. It should usually be called
2664 * after shutting down any watches before shutting down the ioctx or
2665 * librados to ensure that any callbacks do not misuse the ioctx (for
2666 * example by calling rados_notify_ack after the ioctx has been
2669 * @param cluster the cluster handle
2671 CEPH_RADOS_API
int rados_watch_flush(rados_t cluster
);
2673 * Flush watch/notify callbacks
2675 * This call will be nonblock, and the completion will be called
2676 * until all pending watch/notify callbacks have been executed and
2677 * the queue is empty. It should usually be called after shutting
2678 * down any watches before shutting down the ioctx or
2679 * librados to ensure that any callbacks do not misuse the ioctx (for
2680 * example by calling rados_notify_ack after the ioctx has been
2683 * @param cluster the cluster handle
2684 * @param completion what to do when operation has been attempted
2686 CEPH_RADOS_API
int rados_aio_watch_flush(rados_t cluster
, rados_completion_t completion
);
2688 /** @} Watch/Notify */
2691 * Pin an object in the cache tier
2693 * When an object is pinned in the cache tier, it stays in the cache
2694 * tier, and won't be flushed out.
2696 * @param io the pool the object is in
2697 * @param o the object id
2698 * @returns 0 on success, negative error code on failure
2700 CEPH_RADOS_API
int rados_cache_pin(rados_ioctx_t io
, const char *o
);
2703 * Unpin an object in the cache tier
2705 * After an object is unpinned in the cache tier, it can be flushed out
2707 * @param io the pool the object is in
2708 * @param o the object id
2709 * @returns 0 on success, negative error code on failure
2711 CEPH_RADOS_API
int rados_cache_unpin(rados_ioctx_t io
, const char *o
);
2720 * Set allocation hint for an object
2722 * This is an advisory operation, it will always succeed (as if it was
2723 * submitted with a LIBRADOS_OP_FLAG_FAILOK flag set) and is not
2724 * guaranteed to do anything on the backend.
2726 * @param io the pool the object is in
2727 * @param o the name of the object
2728 * @param expected_object_size expected size of the object, in bytes
2729 * @param expected_write_size expected size of writes to the object, in bytes
2730 * @returns 0 on success, negative error code on failure
2732 CEPH_RADOS_API
int rados_set_alloc_hint(rados_ioctx_t io
, const char *o
,
2733 uint64_t expected_object_size
,
2734 uint64_t expected_write_size
);
2737 * Set allocation hint for an object
2739 * This is an advisory operation, it will always succeed (as if it was
2740 * submitted with a LIBRADOS_OP_FLAG_FAILOK flag set) and is not
2741 * guaranteed to do anything on the backend.
2743 * @param io the pool the object is in
2744 * @param o the name of the object
2745 * @param expected_object_size expected size of the object, in bytes
2746 * @param expected_write_size expected size of writes to the object, in bytes
2747 * @param flags hints about future IO patterns
2748 * @returns 0 on success, negative error code on failure
2750 CEPH_RADOS_API
int rados_set_alloc_hint2(rados_ioctx_t io
, const char *o
,
2751 uint64_t expected_object_size
,
2752 uint64_t expected_write_size
,
2758 * @name Object Operations
2760 * A single rados operation can do multiple operations on one object
2761 * atomically. The whole operation will succeed or fail, and no partial
2762 * results will be visible.
2764 * Operations may be either reads, which can return data, or writes,
2765 * which cannot. The effects of writes are applied and visible all at
2766 * once, so an operation that sets an xattr and then checks its value
2767 * will not see the updated value.
2773 * Create a new rados_write_op_t write operation. This will store all actions
2774 * to be performed atomically. You must call rados_release_write_op when you are
2777 * @returns non-NULL on success, NULL on memory allocation error.
2779 CEPH_RADOS_API rados_write_op_t
rados_create_write_op(void);
2782 * Free a rados_write_op_t, must be called when you're done with it.
2783 * @param write_op operation to deallocate, created with rados_create_write_op
2785 CEPH_RADOS_API
void rados_release_write_op(rados_write_op_t write_op
);
2788 * Set flags for the last operation added to this write_op.
2789 * At least one op must have been added to the write_op.
2790 * @param write_op operation to add this action to
2791 * @param flags see librados.h constants beginning with LIBRADOS_OP_FLAG
2793 CEPH_RADOS_API
void rados_write_op_set_flags(rados_write_op_t write_op
,
2797 * Ensure that the object exists before writing
2798 * @param write_op operation to add this action to
2800 CEPH_RADOS_API
void rados_write_op_assert_exists(rados_write_op_t write_op
);
2803 * Ensure that the object exists and that its internal version
2804 * number is equal to "ver" before writing. "ver" should be a
2805 * version number previously obtained with rados_get_last_version().
2806 * - If the object's version is greater than the asserted version
2807 * then rados_write_op_operate will return -ERANGE instead of
2809 * - If the object's version is less than the asserted version
2810 * then rados_write_op_operate will return -EOVERFLOW instead
2811 * of executing the op.
2812 * @param write_op operation to add this action to
2813 * @param ver object version number
2815 CEPH_RADOS_API
void rados_write_op_assert_version(rados_write_op_t write_op
, uint64_t ver
);
2818 * Ensure that given object range (extent) satisfies comparison.
2820 * @param write_op operation to add this action to
2821 * @param cmp_buf buffer containing bytes to be compared with object contents
2822 * @param cmp_len length to compare and size of @c cmp_buf in bytes
2823 * @param off object byte offset at which to start the comparison
2824 * @param prval returned result of comparison, 0 on success, negative error code
2825 * on failure, (-MAX_ERRNO - mismatch_off) on mismatch
2827 CEPH_RADOS_API
void rados_write_op_cmpext(rados_write_op_t write_op
,
2828 const char *cmp_buf
,
2834 * Ensure that given xattr satisfies comparison.
2835 * If the comparison is not satisfied, the return code of the
2836 * operation will be -ECANCELED
2837 * @param write_op operation to add this action to
2838 * @param name name of the xattr to look up
2839 * @param comparison_operator currently undocumented, look for
2840 * LIBRADOS_CMPXATTR_OP_EQ in librados.h
2841 * @param value buffer to compare actual xattr value to
2842 * @param value_len length of buffer to compare actual xattr value to
2844 CEPH_RADOS_API
void rados_write_op_cmpxattr(rados_write_op_t write_op
,
2846 uint8_t comparison_operator
,
2851 * Ensure that the an omap value satisfies a comparison,
2852 * with the supplied value on the right hand side (i.e.
2853 * for OP_LT, the comparison is actual_value < value.
2855 * @param write_op operation to add this action to
2856 * @param key which omap value to compare
2857 * @param comparison_operator one of LIBRADOS_CMPXATTR_OP_EQ,
2858 LIBRADOS_CMPXATTR_OP_LT, or LIBRADOS_CMPXATTR_OP_GT
2859 * @param val value to compare with
2860 * @param val_len length of value in bytes
2861 * @param prval where to store the return value from this action
2863 CEPH_RADOS_API
void rados_write_op_omap_cmp(rados_write_op_t write_op
,
2865 uint8_t comparison_operator
,
2871 * Ensure that the an omap value satisfies a comparison,
2872 * with the supplied value on the right hand side (i.e.
2873 * for OP_LT, the comparison is actual_value < value.
2875 * @param write_op operation to add this action to
2876 * @param key which omap value to compare
2877 * @param comparison_operator one of LIBRADOS_CMPXATTR_OP_EQ,
2878 LIBRADOS_CMPXATTR_OP_LT, or LIBRADOS_CMPXATTR_OP_GT
2879 * @param val value to compare with
2880 * @param key_len length of key in bytes
2881 * @param val_len length of value in bytes
2882 * @param prval where to store the return value from this action
2884 CEPH_RADOS_API
void rados_write_op_omap_cmp2(rados_write_op_t write_op
,
2886 uint8_t comparison_operator
,
2894 * @param write_op operation to add this action to
2895 * @param name name of the xattr
2896 * @param value buffer to set xattr to
2897 * @param value_len length of buffer to set xattr to
2899 CEPH_RADOS_API
void rados_write_op_setxattr(rados_write_op_t write_op
,
2906 * @param write_op operation to add this action to
2907 * @param name name of the xattr to remove
2909 CEPH_RADOS_API
void rados_write_op_rmxattr(rados_write_op_t write_op
,
2914 * @param write_op operation to add this action to
2915 * @param exclusive set to either LIBRADOS_CREATE_EXCLUSIVE or
2916 LIBRADOS_CREATE_IDEMPOTENT
2917 * will error if the object already exists.
2918 * @param category category string (DEPRECATED, HAS NO EFFECT)
2920 CEPH_RADOS_API
void rados_write_op_create(rados_write_op_t write_op
,
2922 const char* category
);
2926 * @param write_op operation to add this action to
2927 * @param offset offset to write to
2928 * @param buffer bytes to write
2929 * @param len length of buffer
2931 CEPH_RADOS_API
void rados_write_op_write(rados_write_op_t write_op
,
2937 * Write whole object, atomically replacing it.
2938 * @param write_op operation to add this action to
2939 * @param buffer bytes to write
2940 * @param len length of buffer
2942 CEPH_RADOS_API
void rados_write_op_write_full(rados_write_op_t write_op
,
2947 * Write the same buffer multiple times
2948 * @param write_op operation to add this action to
2949 * @param buffer bytes to write
2950 * @param data_len length of buffer
2951 * @param write_len total number of bytes to write, as a multiple of @c data_len
2952 * @param offset offset to write to
2954 CEPH_RADOS_API
void rados_write_op_writesame(rados_write_op_t write_op
,
2961 * Append to end of object.
2962 * @param write_op operation to add this action to
2963 * @param buffer bytes to write
2964 * @param len length of buffer
2966 CEPH_RADOS_API
void rados_write_op_append(rados_write_op_t write_op
,
2971 * @param write_op operation to add this action to
2973 CEPH_RADOS_API
void rados_write_op_remove(rados_write_op_t write_op
);
2976 * Truncate an object
2977 * @param write_op operation to add this action to
2978 * @param offset Offset to truncate to
2980 CEPH_RADOS_API
void rados_write_op_truncate(rados_write_op_t write_op
,
2984 * Zero part of an object
2985 * @param write_op operation to add this action to
2986 * @param offset Offset to zero
2987 * @param len length to zero
2989 CEPH_RADOS_API
void rados_write_op_zero(rados_write_op_t write_op
,
2994 * Execute an OSD class method on an object
2995 * See rados_exec() for general description.
2997 * @param write_op operation to add this action to
2998 * @param cls the name of the class
2999 * @param method the name of the method
3000 * @param in_buf where to find input
3001 * @param in_len length of in_buf in bytes
3002 * @param prval where to store the return value from the method
3004 CEPH_RADOS_API
void rados_write_op_exec(rados_write_op_t write_op
,
3012 * Set key/value pairs on an object
3014 * @param write_op operation to add this action to
3015 * @param keys array of null-terminated char arrays representing keys to set
3016 * @param vals array of pointers to values to set
3017 * @param lens array of lengths corresponding to each value
3018 * @param num number of key/value pairs to set
3020 CEPH_RADOS_API
void rados_write_op_omap_set(rados_write_op_t write_op
,
3021 char const* const* keys
,
3022 char const* const* vals
,
3027 * Set key/value pairs on an object
3029 * @param write_op operation to add this action to
3030 * @param keys array of null-terminated char arrays representing keys to set
3031 * @param vals array of pointers to values to set
3032 * @param key_lens array of lengths corresponding to each key
3033 * @param val_lens array of lengths corresponding to each value
3034 * @param num number of key/value pairs to set
3036 CEPH_RADOS_API
void rados_write_op_omap_set2(rados_write_op_t write_op
,
3037 char const* const* keys
,
3038 char const* const* vals
,
3039 const size_t *key_lens
,
3040 const size_t *val_lens
,
3044 * Remove key/value pairs from an object
3046 * @param write_op operation to add this action to
3047 * @param keys array of null-terminated char arrays representing keys to remove
3048 * @param keys_len number of key/value pairs to remove
3050 CEPH_RADOS_API
void rados_write_op_omap_rm_keys(rados_write_op_t write_op
,
3051 char const* const* keys
,
3055 * Remove key/value pairs from an object
3057 * @param write_op operation to add this action to
3058 * @param keys array of char arrays representing keys to remove
3059 * @param key_lens array of size_t values representing length of each key
3060 * @param keys_len number of key/value pairs to remove
3062 CEPH_RADOS_API
void rados_write_op_omap_rm_keys2(rados_write_op_t write_op
,
3063 char const* const* keys
,
3064 const size_t* key_lens
,
3069 * Remove key/value pairs from an object whose keys are in the range
3070 * [key_begin, key_end)
3072 * @param write_op operation to add this action to
3073 * @param key_begin the lower bound of the key range to remove
3074 * @param key_begin_len length of key_begin
3075 * @param key_end the upper bound of the key range to remove
3076 * @param key_end_len length of key_end
3078 CEPH_RADOS_API
void rados_write_op_omap_rm_range2(rados_write_op_t write_op
,
3079 const char *key_begin
,
3080 size_t key_begin_len
,
3081 const char *key_end
,
3082 size_t key_end_len
);
3085 * Remove all key/value pairs from an object
3087 * @param write_op operation to add this action to
3089 CEPH_RADOS_API
void rados_write_op_omap_clear(rados_write_op_t write_op
);
3092 * Set allocation hint for an object
3094 * @param write_op operation to add this action to
3095 * @param expected_object_size expected size of the object, in bytes
3096 * @param expected_write_size expected size of writes to the object, in bytes
3098 CEPH_RADOS_API
void rados_write_op_set_alloc_hint(rados_write_op_t write_op
,
3099 uint64_t expected_object_size
,
3100 uint64_t expected_write_size
);
3103 * Set allocation hint for an object
3105 * @param write_op operation to add this action to
3106 * @param expected_object_size expected size of the object, in bytes
3107 * @param expected_write_size expected size of writes to the object, in bytes
3108 * @param flags hints about future IO patterns
3110 CEPH_RADOS_API
void rados_write_op_set_alloc_hint2(rados_write_op_t write_op
,
3111 uint64_t expected_object_size
,
3112 uint64_t expected_write_size
,
3116 * Perform a write operation synchronously
3117 * @param write_op operation to perform
3118 * @param io the ioctx that the object is in
3119 * @param oid the object id
3120 * @param mtime the time to set the mtime to, NULL for the current time
3121 * @param flags flags to apply to the entire operation (LIBRADOS_OPERATION_*)
3123 CEPH_RADOS_API
int rados_write_op_operate(rados_write_op_t write_op
,
3129 * Perform a write operation synchronously
3130 * @param write_op operation to perform
3131 * @param io the ioctx that the object is in
3132 * @param oid the object id
3133 * @param mtime the time to set the mtime to, NULL for the current time
3134 * @param flags flags to apply to the entire operation (LIBRADOS_OPERATION_*)
3137 CEPH_RADOS_API
int rados_write_op_operate2(rados_write_op_t write_op
,
3140 struct timespec
*mtime
,
3144 * Perform a write operation asynchronously
3145 * @param write_op operation to perform
3146 * @param io the ioctx that the object is in
3147 * @param completion what to do when operation has been attempted
3148 * @param oid the object id
3149 * @param mtime the time to set the mtime to, NULL for the current time
3150 * @param flags flags to apply to the entire operation (LIBRADOS_OPERATION_*)
3152 CEPH_RADOS_API
int rados_aio_write_op_operate(rados_write_op_t write_op
,
3154 rados_completion_t completion
,
3160 * Create a new rados_read_op_t write operation. This will store all
3161 * actions to be performed atomically. You must call
3162 * rados_release_read_op when you are finished with it (after it
3163 * completes, or you decide not to send it in the first place).
3165 * @returns non-NULL on success, NULL on memory allocation error.
3167 CEPH_RADOS_API rados_read_op_t
rados_create_read_op(void);
3170 * Free a rados_read_op_t, must be called when you're done with it.
3171 * @param read_op operation to deallocate, created with rados_create_read_op
3173 CEPH_RADOS_API
void rados_release_read_op(rados_read_op_t read_op
);
3176 * Set flags for the last operation added to this read_op.
3177 * At least one op must have been added to the read_op.
3178 * @param read_op operation to add this action to
3179 * @param flags see librados.h constants beginning with LIBRADOS_OP_FLAG
3181 CEPH_RADOS_API
void rados_read_op_set_flags(rados_read_op_t read_op
, int flags
);
3184 * Ensure that the object exists before reading
3185 * @param read_op operation to add this action to
3187 CEPH_RADOS_API
void rados_read_op_assert_exists(rados_read_op_t read_op
);
3190 * Ensure that the object exists and that its internal version
3191 * number is equal to "ver" before reading. "ver" should be a
3192 * version number previously obtained with rados_get_last_version().
3193 * - If the object's version is greater than the asserted version
3194 * then rados_read_op_operate will return -ERANGE instead of
3196 * - If the object's version is less than the asserted version
3197 * then rados_read_op_operate will return -EOVERFLOW instead
3198 * of executing the op.
3199 * @param read_op operation to add this action to
3200 * @param ver object version number
3202 CEPH_RADOS_API
void rados_read_op_assert_version(rados_read_op_t read_op
, uint64_t ver
);
3205 * Ensure that given object range (extent) satisfies comparison.
3207 * @param read_op operation to add this action to
3208 * @param cmp_buf buffer containing bytes to be compared with object contents
3209 * @param cmp_len length to compare and size of @c cmp_buf in bytes
3210 * @param off object byte offset at which to start the comparison
3211 * @param prval returned result of comparison, 0 on success, negative error code
3212 * on failure, (-MAX_ERRNO - mismatch_off) on mismatch
3214 CEPH_RADOS_API
void rados_read_op_cmpext(rados_read_op_t read_op
,
3215 const char *cmp_buf
,
3221 * Ensure that the an xattr satisfies a comparison
3222 * If the comparison is not satisfied, the return code of the
3223 * operation will be -ECANCELED
3224 * @param read_op operation to add this action to
3225 * @param name name of the xattr to look up
3226 * @param comparison_operator currently undocumented, look for
3227 * LIBRADOS_CMPXATTR_OP_EQ in librados.h
3228 * @param value buffer to compare actual xattr value to
3229 * @param value_len length of buffer to compare actual xattr value to
3231 CEPH_RADOS_API
void rados_read_op_cmpxattr(rados_read_op_t read_op
,
3233 uint8_t comparison_operator
,
3238 * Start iterating over xattrs on an object.
3240 * @param read_op operation to add this action to
3241 * @param iter where to store the iterator
3242 * @param prval where to store the return value of this action
3244 CEPH_RADOS_API
void rados_read_op_getxattrs(rados_read_op_t read_op
,
3245 rados_xattrs_iter_t
*iter
,
3249 * Ensure that the an omap value satisfies a comparison,
3250 * with the supplied value on the right hand side (i.e.
3251 * for OP_LT, the comparison is actual_value < value.
3253 * @param read_op operation to add this action to
3254 * @param key which omap value to compare
3255 * @param comparison_operator one of LIBRADOS_CMPXATTR_OP_EQ,
3256 LIBRADOS_CMPXATTR_OP_LT, or LIBRADOS_CMPXATTR_OP_GT
3257 * @param val value to compare with
3258 * @param val_len length of value in bytes
3259 * @param prval where to store the return value from this action
3261 CEPH_RADOS_API
void rados_read_op_omap_cmp(rados_read_op_t read_op
,
3263 uint8_t comparison_operator
,
3269 * Ensure that the an omap value satisfies a comparison,
3270 * with the supplied value on the right hand side (i.e.
3271 * for OP_LT, the comparison is actual_value < value.
3273 * @param read_op operation to add this action to
3274 * @param key which omap value to compare
3275 * @param comparison_operator one of LIBRADOS_CMPXATTR_OP_EQ,
3276 LIBRADOS_CMPXATTR_OP_LT, or LIBRADOS_CMPXATTR_OP_GT
3277 * @param val value to compare with
3278 * @param key_len length of key in bytes
3279 * @param val_len length of value in bytes
3280 * @param prval where to store the return value from this action
3282 CEPH_RADOS_API
void rados_read_op_omap_cmp2(rados_read_op_t read_op
,
3284 uint8_t comparison_operator
,
3291 * Get object size and mtime
3292 * @param read_op operation to add this action to
3293 * @param psize where to store object size
3294 * @param pmtime where to store modification time
3295 * @param prval where to store the return value of this action
3297 CEPH_RADOS_API
void rados_read_op_stat(rados_read_op_t read_op
,
3303 * Read bytes from offset into buffer.
3305 * prlen will be filled with the number of bytes read if successful.
3306 * A short read can only occur if the read reaches the end of the
3309 * @param read_op operation to add this action to
3310 * @param offset offset to read from
3311 * @param len length of buffer
3312 * @param buffer where to put the data
3313 * @param bytes_read where to store the number of bytes read by this action
3314 * @param prval where to store the return value of this action
3316 CEPH_RADOS_API
void rados_read_op_read(rados_read_op_t read_op
,
3324 * Compute checksum from object data
3326 * @param read_op operation to add this action to
3327 * @param type the checksum algorithm to utilize
3328 * @param init_value the init value for the algorithm
3329 * @param init_value_len the length of the init value
3330 * @param offset the offset to start checksumming in the object
3331 * @param len the number of bytes to checksum
3332 * @param chunk_size optional length-aligned chunk size for checksums
3333 * @param pchecksum where to store the checksum result for this action
3334 * @param checksum_len the number of bytes available for the result
3335 * @param prval where to store the return value for this action
3337 CEPH_RADOS_API
void rados_read_op_checksum(rados_read_op_t read_op
,
3338 rados_checksum_type_t type
,
3339 const char *init_value
,
3340 size_t init_value_len
,
3341 uint64_t offset
, size_t len
,
3342 size_t chunk_size
, char *pchecksum
,
3343 size_t checksum_len
, int *prval
);
3346 * Execute an OSD class method on an object
3347 * See rados_exec() for general description.
3349 * The output buffer is allocated on the heap; the caller is
3350 * expected to release that memory with rados_buffer_free(). The
3351 * buffer and length pointers can all be NULL, in which case they are
3354 * @param read_op operation to add this action to
3355 * @param cls the name of the class
3356 * @param method the name of the method
3357 * @param in_buf where to find input
3358 * @param in_len length of in_buf in bytes
3359 * @param out_buf where to put librados-allocated output buffer
3360 * @param out_len length of out_buf in bytes
3361 * @param prval where to store the return value from the method
3363 CEPH_RADOS_API
void rados_read_op_exec(rados_read_op_t read_op
,
3373 * Execute an OSD class method on an object
3374 * See rados_exec() for general description.
3376 * If the output buffer is too small, prval will
3377 * be set to -ERANGE and used_len will be 0.
3379 * @param read_op operation to add this action to
3380 * @param cls the name of the class
3381 * @param method the name of the method
3382 * @param in_buf where to find input
3383 * @param in_len length of in_buf in bytes
3384 * @param out_buf user-provided buffer to read into
3385 * @param out_len length of out_buf in bytes
3386 * @param used_len where to store the number of bytes read into out_buf
3387 * @param prval where to store the return value from the method
3389 CEPH_RADOS_API
void rados_read_op_exec_user_buf(rados_read_op_t read_op
,
3400 * Start iterating over key/value pairs on an object.
3402 * They will be returned sorted by key.
3404 * @param read_op operation to add this action to
3405 * @param start_after list keys starting after start_after
3406 * @param filter_prefix list only keys beginning with filter_prefix
3407 * @param max_return list no more than max_return key/value pairs
3408 * @param iter where to store the iterator
3409 * @param prval where to store the return value from this action
3411 CEPH_RADOS_API
void rados_read_op_omap_get_vals(rados_read_op_t read_op
,
3412 const char *start_after
,
3413 const char *filter_prefix
,
3414 uint64_t max_return
,
3415 rados_omap_iter_t
*iter
,
3417 __attribute__((deprecated
)); /* use v2 below */
3420 * Start iterating over key/value pairs on an object.
3422 * They will be returned sorted by key.
3424 * @param read_op operation to add this action to
3425 * @param start_after list keys starting after start_after
3426 * @param filter_prefix list only keys beginning with filter_prefix
3427 * @param max_return list no more than max_return key/value pairs
3428 * @param iter where to store the iterator
3429 * @param pmore flag indicating whether there are more keys to fetch
3430 * @param prval where to store the return value from this action
3432 CEPH_RADOS_API
void rados_read_op_omap_get_vals2(rados_read_op_t read_op
,
3433 const char *start_after
,
3434 const char *filter_prefix
,
3435 uint64_t max_return
,
3436 rados_omap_iter_t
*iter
,
3437 unsigned char *pmore
,
3441 * Start iterating over keys on an object.
3443 * They will be returned sorted by key, and the iterator
3444 * will fill in NULL for all values if specified.
3446 * @param read_op operation to add this action to
3447 * @param start_after list keys starting after start_after
3448 * @param max_return list no more than max_return keys
3449 * @param iter where to store the iterator
3450 * @param prval where to store the return value from this action
3452 CEPH_RADOS_API
void rados_read_op_omap_get_keys(rados_read_op_t read_op
,
3453 const char *start_after
,
3454 uint64_t max_return
,
3455 rados_omap_iter_t
*iter
,
3457 __attribute__((deprecated
)); /* use v2 below */
3460 * Start iterating over keys on an object.
3462 * They will be returned sorted by key, and the iterator
3463 * will fill in NULL for all values if specified.
3465 * @param read_op operation to add this action to
3466 * @param start_after list keys starting after start_after
3467 * @param max_return list no more than max_return keys
3468 * @param iter where to store the iterator
3469 * @param pmore flag indicating whether there are more keys to fetch
3470 * @param prval where to store the return value from this action
3472 CEPH_RADOS_API
void rados_read_op_omap_get_keys2(rados_read_op_t read_op
,
3473 const char *start_after
,
3474 uint64_t max_return
,
3475 rados_omap_iter_t
*iter
,
3476 unsigned char *pmore
,
3480 * Start iterating over specific key/value pairs
3482 * They will be returned sorted by key.
3484 * @param read_op operation to add this action to
3485 * @param keys array of pointers to null-terminated keys to get
3486 * @param keys_len the number of strings in keys
3487 * @param iter where to store the iterator
3488 * @param prval where to store the return value from this action
3490 CEPH_RADOS_API
void rados_read_op_omap_get_vals_by_keys(rados_read_op_t read_op
,
3491 char const* const* keys
,
3493 rados_omap_iter_t
*iter
,
3497 * Start iterating over specific key/value pairs
3499 * They will be returned sorted by key.
3501 * @param read_op operation to add this action to
3502 * @param keys array of pointers to keys to get
3503 * @param num_keys the number of strings in keys
3504 * @param key_lens array of size_t's describing each key len (in bytes)
3505 * @param iter where to store the iterator
3506 * @param prval where to store the return value from this action
3508 CEPH_RADOS_API
void rados_read_op_omap_get_vals_by_keys2(rados_read_op_t read_op
,
3509 char const* const* keys
,
3511 const size_t* key_lens
,
3512 rados_omap_iter_t
*iter
,
3516 * Perform a read operation synchronously
3517 * @param read_op operation to perform
3518 * @param io the ioctx that the object is in
3519 * @param oid the object id
3520 * @param flags flags to apply to the entire operation (LIBRADOS_OPERATION_*)
3522 CEPH_RADOS_API
int rados_read_op_operate(rados_read_op_t read_op
,
3528 * Perform a read operation asynchronously
3529 * @param read_op operation to perform
3530 * @param io the ioctx that the object is in
3531 * @param completion what to do when operation has been attempted
3532 * @param oid the object id
3533 * @param flags flags to apply to the entire operation (LIBRADOS_OPERATION_*)
3535 CEPH_RADOS_API
int rados_aio_read_op_operate(rados_read_op_t read_op
,
3537 rados_completion_t completion
,
3541 /** @} Object Operations */
3544 * Take an exclusive lock on an object.
3546 * @param io the context to operate in
3547 * @param oid the name of the object
3548 * @param name the name of the lock
3549 * @param cookie user-defined identifier for this instance of the lock
3550 * @param desc user-defined lock description
3551 * @param duration the duration of the lock. Set to NULL for infinite duration.
3552 * @param flags lock flags
3553 * @returns 0 on success, negative error code on failure
3554 * @returns -EBUSY if the lock is already held by another (client, cookie) pair
3555 * @returns -EEXIST if the lock is already held by the same (client, cookie) pair
3557 CEPH_RADOS_API
int rados_lock_exclusive(rados_ioctx_t io
, const char * oid
,
3558 const char * name
, const char * cookie
,
3560 struct timeval
* duration
,
3564 * Take a shared lock on an object.
3566 * @param io the context to operate in
3567 * @param o the name of the object
3568 * @param name the name of the lock
3569 * @param cookie user-defined identifier for this instance of the lock
3570 * @param tag The tag of the lock
3571 * @param desc user-defined lock description
3572 * @param duration the duration of the lock. Set to NULL for infinite duration.
3573 * @param flags lock flags
3574 * @returns 0 on success, negative error code on failure
3575 * @returns -EBUSY if the lock is already held by another (client, cookie) pair
3576 * @returns -EEXIST if the lock is already held by the same (client, cookie) pair
3578 CEPH_RADOS_API
int rados_lock_shared(rados_ioctx_t io
, const char * o
,
3579 const char * name
, const char * cookie
,
3580 const char * tag
, const char * desc
,
3581 struct timeval
* duration
, uint8_t flags
);
3584 * Release a shared or exclusive lock on an object.
3586 * @param io the context to operate in
3587 * @param o the name of the object
3588 * @param name the name of the lock
3589 * @param cookie user-defined identifier for the instance of the lock
3590 * @returns 0 on success, negative error code on failure
3591 * @returns -ENOENT if the lock is not held by the specified (client, cookie) pair
3593 CEPH_RADOS_API
int rados_unlock(rados_ioctx_t io
, const char *o
,
3594 const char *name
, const char *cookie
);
3597 * Asynchronous release a shared or exclusive lock on an object.
3599 * @param io the context to operate in
3600 * @param o the name of the object
3601 * @param name the name of the lock
3602 * @param cookie user-defined identifier for the instance of the lock
3603 * @param completion what to do when operation has been attempted
3604 * @returns 0 on success, negative error code on failure
3606 CEPH_RADOS_API
int rados_aio_unlock(rados_ioctx_t io
, const char *o
,
3607 const char *name
, const char *cookie
,
3608 rados_completion_t completion
);
3611 * List clients that have locked the named object lock and information about
3614 * The number of bytes required in each buffer is put in the
3615 * corresponding size out parameter. If any of the provided buffers
3616 * are too short, -ERANGE is returned after these sizes are filled in.
3618 * @param io the context to operate in
3619 * @param o the name of the object
3620 * @param name the name of the lock
3621 * @param exclusive where to store whether the lock is exclusive (1) or shared (0)
3622 * @param tag where to store the tag associated with the object lock
3623 * @param tag_len number of bytes in tag buffer
3624 * @param clients buffer in which locker clients are stored, separated by '\0'
3625 * @param clients_len number of bytes in the clients buffer
3626 * @param cookies buffer in which locker cookies are stored, separated by '\0'
3627 * @param cookies_len number of bytes in the cookies buffer
3628 * @param addrs buffer in which locker addresses are stored, separated by '\0'
3629 * @param addrs_len number of bytes in the clients buffer
3630 * @returns number of lockers on success, negative error code on failure
3631 * @returns -ERANGE if any of the buffers are too short
3633 CEPH_RADOS_API ssize_t
rados_list_lockers(rados_ioctx_t io
, const char *o
,
3634 const char *name
, int *exclusive
,
3635 char *tag
, size_t *tag_len
,
3636 char *clients
, size_t *clients_len
,
3637 char *cookies
, size_t *cookies_len
,
3638 char *addrs
, size_t *addrs_len
);
3641 * Releases a shared or exclusive lock on an object, which was taken by the
3644 * @param io the context to operate in
3645 * @param o the name of the object
3646 * @param name the name of the lock
3647 * @param client the client currently holding the lock
3648 * @param cookie user-defined identifier for the instance of the lock
3649 * @returns 0 on success, negative error code on failure
3650 * @returns -ENOENT if the lock is not held by the specified (client, cookie) pair
3651 * @returns -EINVAL if the client cannot be parsed
3653 CEPH_RADOS_API
int rados_break_lock(rados_ioctx_t io
, const char *o
,
3654 const char *name
, const char *client
,
3655 const char *cookie
);
3658 * Blacklists the specified client from the OSDs
3660 * @param cluster cluster handle
3661 * @param client_address client address
3662 * @param expire_seconds number of seconds to blacklist (0 for default)
3663 * @returns 0 on success, negative error code on failure
3665 CEPH_RADOS_API
int rados_blacklist_add(rados_t cluster
,
3666 char *client_address
,
3667 uint32_t expire_seconds
);
3670 * Gets addresses of the RADOS session, suitable for blacklisting.
3672 * @param cluster cluster handle
3673 * @param addrs the output string.
3674 * @returns 0 on success, negative error code on failure
3676 CEPH_RADOS_API
int rados_getaddrs(rados_t cluster
, char** addrs
);
3678 CEPH_RADOS_API
void rados_set_osdmap_full_try(rados_ioctx_t io
)
3679 __attribute__((deprecated
));
3681 CEPH_RADOS_API
void rados_unset_osdmap_full_try(rados_ioctx_t io
)
3682 __attribute__((deprecated
));
3684 CEPH_RADOS_API
void rados_set_pool_full_try(rados_ioctx_t io
);
3686 CEPH_RADOS_API
void rados_unset_pool_full_try(rados_ioctx_t io
);
3689 * Enable an application on a pool
3691 * @param io pool ioctx
3692 * @param app_name application name
3693 * @param force 0 if only single application per pool
3694 * @returns 0 on success, negative error code on failure
3696 CEPH_RADOS_API
int rados_application_enable(rados_ioctx_t io
,
3697 const char *app_name
, int force
);
3700 * List all enabled applications
3702 * If the provided buffer is too short, the required length is filled in and
3703 * -ERANGE is returned. Otherwise, the buffers are filled with the application
3704 * names, with a '\0' after each.
3706 * @param io pool ioctx
3707 * @param values buffer in which to store application names
3708 * @param values_len number of bytes in values buffer
3709 * @returns 0 on success, negative error code on failure
3710 * @returns -ERANGE if either buffer is too short
3712 CEPH_RADOS_API
int rados_application_list(rados_ioctx_t io
, char *values
,
3713 size_t *values_len
);
3716 * Get application metadata value from pool
3718 * @param io pool ioctx
3719 * @param app_name application name
3720 * @param key metadata key
3721 * @param value result buffer
3722 * @param value_len maximum len of value
3723 * @returns 0 on success, negative error code on failure
3725 CEPH_RADOS_API
int rados_application_metadata_get(rados_ioctx_t io
,
3726 const char *app_name
,
3727 const char *key
, char *value
,
3731 * Set application metadata on a pool
3733 * @param io pool ioctx
3734 * @param app_name application name
3735 * @param key metadata key
3736 * @param value metadata key
3737 * @returns 0 on success, negative error code on failure
3739 CEPH_RADOS_API
int rados_application_metadata_set(rados_ioctx_t io
,
3740 const char *app_name
,
3745 * Remove application metadata from a pool
3747 * @param io pool ioctx
3748 * @param app_name application name
3749 * @param key metadata key
3750 * @returns 0 on success, negative error code on failure
3752 CEPH_RADOS_API
int rados_application_metadata_remove(rados_ioctx_t io
,
3753 const char *app_name
,
3757 * List all metadata key/value pairs associated with an application.
3759 * This iterates over all metadata, key_len and val_len are filled in
3760 * with the number of bytes put into the keys and values buffers.
3762 * If the provided buffers are too short, the required lengths are filled
3763 * in and -ERANGE is returned. Otherwise, the buffers are filled with
3764 * the keys and values of the metadata, with a '\0' after each.
3766 * @param io pool ioctx
3767 * @param app_name application name
3768 * @param keys buffer in which to store key names
3769 * @param key_len number of bytes in keys buffer
3770 * @param values buffer in which to store values
3771 * @param vals_len number of bytes in values buffer
3772 * @returns 0 on success, negative error code on failure
3773 * @returns -ERANGE if either buffer is too short
3775 CEPH_RADOS_API
int rados_application_metadata_list(rados_ioctx_t io
,
3776 const char *app_name
,
3777 char *keys
, size_t *key_len
,
3782 * @name Mon/OSD/PG Commands
3784 * These interfaces send commands relating to the monitor, OSD, or PGs.
3790 * Send monitor command.
3792 * @note Takes command string in carefully-formatted JSON; must match
3793 * defined commands, types, etc.
3795 * The result buffers are allocated on the heap; the caller is
3796 * expected to release that memory with rados_buffer_free(). The
3797 * buffer and length pointers can all be NULL, in which case they are
3800 * @param cluster cluster handle
3801 * @param cmd an array of char *'s representing the command
3802 * @param cmdlen count of valid entries in cmd
3803 * @param inbuf any bulk input data (crush map, etc.)
3804 * @param inbuflen input buffer length
3805 * @param outbuf double pointer to output buffer
3806 * @param outbuflen pointer to output buffer length
3807 * @param outs double pointer to status string
3808 * @param outslen pointer to status string length
3809 * @returns 0 on success, negative error code on failure
3811 CEPH_RADOS_API
int rados_mon_command(rados_t cluster
, const char **cmd
,
3812 size_t cmdlen
, const char *inbuf
,
3813 size_t inbuflen
, char **outbuf
,
3814 size_t *outbuflen
, char **outs
,
3818 * Send ceph-mgr command.
3820 * @note Takes command string in carefully-formatted JSON; must match
3821 * defined commands, types, etc.
3823 * The result buffers are allocated on the heap; the caller is
3824 * expected to release that memory with rados_buffer_free(). The
3825 * buffer and length pointers can all be NULL, in which case they are
3828 * @param cluster cluster handle
3829 * @param cmd an array of char *'s representing the command
3830 * @param cmdlen count of valid entries in cmd
3831 * @param inbuf any bulk input data (crush map, etc.)
3832 * @param inbuflen input buffer length
3833 * @param outbuf double pointer to output buffer
3834 * @param outbuflen pointer to output buffer length
3835 * @param outs double pointer to status string
3836 * @param outslen pointer to status string length
3837 * @returns 0 on success, negative error code on failure
3839 CEPH_RADOS_API
int rados_mgr_command(rados_t cluster
, const char **cmd
,
3840 size_t cmdlen
, const char *inbuf
,
3841 size_t inbuflen
, char **outbuf
,
3842 size_t *outbuflen
, char **outs
,
3846 * Send ceph-mgr tell command.
3848 * @note Takes command string in carefully-formatted JSON; must match
3849 * defined commands, types, etc.
3851 * The result buffers are allocated on the heap; the caller is
3852 * expected to release that memory with rados_buffer_free(). The
3853 * buffer and length pointers can all be NULL, in which case they are
3856 * @param cluster cluster handle
3857 * @param name mgr name to target
3858 * @param cmd an array of char *'s representing the command
3859 * @param cmdlen count of valid entries in cmd
3860 * @param inbuf any bulk input data (crush map, etc.)
3861 * @param inbuflen input buffer length
3862 * @param outbuf double pointer to output buffer
3863 * @param outbuflen pointer to output buffer length
3864 * @param outs double pointer to status string
3865 * @param outslen pointer to status string length
3866 * @returns 0 on success, negative error code on failure
3868 CEPH_RADOS_API
int rados_mgr_command_target(
3872 size_t cmdlen
, const char *inbuf
,
3873 size_t inbuflen
, char **outbuf
,
3874 size_t *outbuflen
, char **outs
,
3878 * Send monitor command to a specific monitor.
3880 * @note Takes command string in carefully-formatted JSON; must match
3881 * defined commands, types, etc.
3883 * The result buffers are allocated on the heap; the caller is
3884 * expected to release that memory with rados_buffer_free(). The
3885 * buffer and length pointers can all be NULL, in which case they are
3888 * @param cluster cluster handle
3889 * @param name target monitor's name
3890 * @param cmd an array of char *'s representing the command
3891 * @param cmdlen count of valid entries in cmd
3892 * @param inbuf any bulk input data (crush map, etc.)
3893 * @param inbuflen input buffer length
3894 * @param outbuf double pointer to output buffer
3895 * @param outbuflen pointer to output buffer length
3896 * @param outs double pointer to status string
3897 * @param outslen pointer to status string length
3898 * @returns 0 on success, negative error code on failure
3900 CEPH_RADOS_API
int rados_mon_command_target(rados_t cluster
, const char *name
,
3901 const char **cmd
, size_t cmdlen
,
3902 const char *inbuf
, size_t inbuflen
,
3903 char **outbuf
, size_t *outbuflen
,
3904 char **outs
, size_t *outslen
);
3907 * free a rados-allocated buffer
3909 * Release memory allocated by librados calls like rados_mon_command().
3911 * @param buf buffer pointer
3913 CEPH_RADOS_API
void rados_buffer_free(char *buf
);
3915 CEPH_RADOS_API
int rados_osd_command(rados_t cluster
, int osdid
,
3916 const char **cmd
, size_t cmdlen
,
3917 const char *inbuf
, size_t inbuflen
,
3918 char **outbuf
, size_t *outbuflen
,
3919 char **outs
, size_t *outslen
);
3921 CEPH_RADOS_API
int rados_pg_command(rados_t cluster
, const char *pgstr
,
3922 const char **cmd
, size_t cmdlen
,
3923 const char *inbuf
, size_t inbuflen
,
3924 char **outbuf
, size_t *outbuflen
,
3925 char **outs
, size_t *outslen
);
3927 CEPH_RADOS_API
int rados_mgr_command(rados_t cluster
,
3928 const char **cmd
, size_t cmdlen
,
3929 const char *inbuf
, size_t inbuflen
,
3930 char **outbuf
, size_t *outbuflen
,
3931 char **outs
, size_t *outslen
);
3934 * This is not a doxygen comment leadin, because doxygen breaks on
3935 * a typedef with function params and returns, and I can't figure out
3938 * Monitor cluster log
3940 * Monitor events logged to the cluster log. The callback get each
3941 * log entry both as a single formatted line and with each field in a
3944 * Calling with a cb argument of NULL will deregister any previously
3945 * registered callback.
3947 * @param cluster cluster handle
3948 * @param level minimum log level (debug, info, warn|warning, err|error)
3949 * @param cb callback to run for each log message. It MUST NOT block
3950 * nor call back into librados.
3951 * @param arg void argument to pass to cb
3953 * @returns 0 on success, negative code on error
3955 typedef void (*rados_log_callback_t
)(void *arg
,
3958 uint64_t sec
, uint64_t nsec
,
3959 uint64_t seq
, const char *level
,
3963 * This is not a doxygen comment leadin, because doxygen breaks on
3964 * a typedef with function params and returns, and I can't figure out
3967 * Monitor cluster log
3969 * Monitor events logged to the cluster log. The callback get each
3970 * log entry both as a single formatted line and with each field in a
3973 * Calling with a cb argument of NULL will deregister any previously
3974 * registered callback.
3976 * @param cluster cluster handle
3977 * @param level minimum log level (debug, info, warn|warning, err|error)
3978 * @param cb callback to run for each log message. It MUST NOT block
3979 * nor call back into librados.
3980 * @param arg void argument to pass to cb
3982 * @returns 0 on success, negative code on error
3984 typedef void (*rados_log_callback2_t
)(void *arg
,
3986 const char *channel
,
3989 uint64_t sec
, uint64_t nsec
,
3990 uint64_t seq
, const char *level
,
3993 CEPH_RADOS_API
int rados_monitor_log(rados_t cluster
, const char *level
,
3994 rados_log_callback_t cb
, void *arg
);
3995 CEPH_RADOS_API
int rados_monitor_log2(rados_t cluster
, const char *level
,
3996 rados_log_callback2_t cb
, void *arg
);
4000 * register daemon instance for a service
4002 * Register us as a daemon providing a particular service. We identify
4003 * the service (e.g., 'rgw') and our instance name (e.g., 'rgw.$hostname').
4004 * The metadata is a map of keys and values with arbitrary static metdata
4005 * for this instance. The encoding is a series of NULL-terminated strings,
4006 * alternating key names and values, terminating with an empty key name.
4007 * For example, "foo\0bar\0this\0that\0\0" is the dict {foo=bar,this=that}.
4009 * For the lifetime of the librados instance, regular beacons will be sent
4010 * to the cluster to maintain our registration in the service map.
4012 * @param cluster handle
4013 * @param service service name
4014 * @param daemon daemon instance name
4015 * @param metadata_dict static daemon metadata dict
4017 CEPH_RADOS_API
int rados_service_register(
4019 const char *service
,
4021 const char *metadata_dict
);
4024 * update daemon status
4026 * Update our mutable status information in the service map.
4028 * The status dict is encoded the same way the daemon metadata is encoded
4029 * for rados_service_register. For example, "foo\0bar\0this\0that\0\0" is
4030 * {foo=bar,this=that}.
4032 * @param cluster rados cluster handle
4033 * @param status_dict status dict
4035 CEPH_RADOS_API
int rados_service_update_status(
4037 const char *status_dict
);
4039 /** @} Mon/OSD/PG commands */
4042 * These methods are no longer supported and return -ENOTSUP where possible.
4044 CEPH_RADOS_API
int rados_objects_list_open(
4046 rados_list_ctx_t
*ctx
) __attribute__((deprecated
));
4047 CEPH_RADOS_API
uint32_t rados_objects_list_get_pg_hash_position(
4048 rados_list_ctx_t ctx
) __attribute__((deprecated
));
4049 CEPH_RADOS_API
uint32_t rados_objects_list_seek(
4050 rados_list_ctx_t ctx
,
4051 uint32_t pos
) __attribute__((deprecated
));
4052 CEPH_RADOS_API
int rados_objects_list_next(
4053 rados_list_ctx_t ctx
,
4055 const char **key
) __attribute__((deprecated
));
4056 CEPH_RADOS_API
void rados_objects_list_close(
4057 rados_list_ctx_t ctx
) __attribute__((deprecated
));