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_GETADDRS 1
53 #define LIBRADOS_SUPPORTS_APP_METADATA 1
56 * They are also defined in cls_lock_types.h. Keep them in sync!
58 #define LIBRADOS_LOCK_FLAG_RENEW (1u<<0)
59 #define LIBRADOS_LOCK_FLAG_MAY_RENEW LIBRADOS_LOCK_FLAG_RENEW
60 #define LIBRADOS_LOCK_FLAG_MUST_RENEW (1u<<1)
63 * Constants for rados_write_op_create().
65 #define LIBRADOS_CREATE_EXCLUSIVE 1
66 #define LIBRADOS_CREATE_IDEMPOTENT 0
69 * Flags that can be set on a per-op basis via
70 * rados_read_op_set_flags() and rados_write_op_set_flags().
73 // fail a create operation if the object already exists
74 LIBRADOS_OP_FLAG_EXCL
= 0x1,
75 // allow the transaction to succeed even if the flagged op fails
76 LIBRADOS_OP_FLAG_FAILOK
= 0x2,
77 // indicate read/write op random
78 LIBRADOS_OP_FLAG_FADVISE_RANDOM
= 0x4,
79 // indicate read/write op sequential
80 LIBRADOS_OP_FLAG_FADVISE_SEQUENTIAL
= 0x8,
81 // indicate read/write data will be accessed in the near future (by someone)
82 LIBRADOS_OP_FLAG_FADVISE_WILLNEED
= 0x10,
83 // indicate read/write data will not accessed in the near future (by anyone)
84 LIBRADOS_OP_FLAG_FADVISE_DONTNEED
= 0x20,
85 // indicate read/write data will not accessed again (by *this* client)
86 LIBRADOS_OP_FLAG_FADVISE_NOCACHE
= 0x40,
87 // optionally support FUA (force unit access) on write requests
88 LIBRADOS_OP_FLAG_FADVISE_FUA
= 0x80,
91 #define CEPH_RADOS_API
94 * @name xattr comparison operations
95 * Operators for comparing xattrs on objects, and aborting the
96 * rados_read_op or rados_write_op transaction if the comparison
102 LIBRADOS_CMPXATTR_OP_EQ
= 1,
103 LIBRADOS_CMPXATTR_OP_NE
= 2,
104 LIBRADOS_CMPXATTR_OP_GT
= 3,
105 LIBRADOS_CMPXATTR_OP_GTE
= 4,
106 LIBRADOS_CMPXATTR_OP_LT
= 5,
107 LIBRADOS_CMPXATTR_OP_LTE
= 6
112 * @name Operation Flags
113 * Flags for rados_read_op_operate(), rados_write_op_operate(),
114 * rados_aio_read_op_operate(), and rados_aio_write_op_operate().
115 * See librados.hpp for details.
119 LIBRADOS_OPERATION_NOFLAG
= 0,
120 LIBRADOS_OPERATION_BALANCE_READS
= 1,
121 LIBRADOS_OPERATION_LOCALIZE_READS
= 2,
122 LIBRADOS_OPERATION_ORDER_READS_WRITES
= 4,
123 LIBRADOS_OPERATION_IGNORE_CACHE
= 8,
124 LIBRADOS_OPERATION_SKIPRWLOCKS
= 16,
125 LIBRADOS_OPERATION_IGNORE_OVERLAY
= 32,
126 /* send requests to cluster despite the cluster or pool being marked
127 full; ops will either succeed (e.g., delete) or return EDQUOT or
129 LIBRADOS_OPERATION_FULL_TRY
= 64,
131 * Mainly for delete op
133 LIBRADOS_OPERATION_FULL_FORCE
= 128,
134 LIBRADOS_OPERATION_IGNORE_REDIRECT
= 256,
135 LIBRADOS_OPERATION_ORDERSNAP
= 512,
136 /* enable/allow >0 return values and payloads on write/update */
137 LIBRADOS_OPERATION_RETURNVEC
= 1024,
142 * @name Alloc hint flags
143 * Flags for rados_write_op_alloc_hint2() and rados_set_alloc_hint2()
144 * indicating future IO patterns.
148 LIBRADOS_ALLOC_HINT_FLAG_SEQUENTIAL_WRITE
= 1,
149 LIBRADOS_ALLOC_HINT_FLAG_RANDOM_WRITE
= 2,
150 LIBRADOS_ALLOC_HINT_FLAG_SEQUENTIAL_READ
= 4,
151 LIBRADOS_ALLOC_HINT_FLAG_RANDOM_READ
= 8,
152 LIBRADOS_ALLOC_HINT_FLAG_APPEND_ONLY
= 16,
153 LIBRADOS_ALLOC_HINT_FLAG_IMMUTABLE
= 32,
154 LIBRADOS_ALLOC_HINT_FLAG_SHORTLIVED
= 64,
155 LIBRADOS_ALLOC_HINT_FLAG_LONGLIVED
= 128,
156 LIBRADOS_ALLOC_HINT_FLAG_COMPRESSIBLE
= 256,
157 LIBRADOS_ALLOC_HINT_FLAG_INCOMPRESSIBLE
= 512,
162 LIBRADOS_CHECKSUM_TYPE_XXHASH32
= 0,
163 LIBRADOS_CHECKSUM_TYPE_XXHASH64
= 1,
164 LIBRADOS_CHECKSUM_TYPE_CRC32C
= 2
165 } rados_checksum_type_t
;
170 #define LIBRADOS_SNAP_HEAD UINT64_C(-2)
171 #define LIBRADOS_SNAP_DIR UINT64_C(-1)
176 * A handle for interacting with a RADOS cluster. It encapsulates all
177 * RADOS client configuration, including username, key for
178 * authentication, logging, and debugging. Talking to different clusters
179 * -- or to the same cluster with different users -- requires
180 * different cluster handles.
182 #ifndef VOIDPTR_RADOS_T
183 #define VOIDPTR_RADOS_T
184 typedef void *rados_t
;
185 #endif //VOIDPTR_RADOS_T
188 * @typedef rados_config_t
190 * A handle for the ceph configuration context for the rados_t cluster
191 * instance. This can be used to share configuration context/state
192 * (e.g., logging configuration) between librados instance.
194 * @warning The config context does not have independent reference
195 * counting. As such, a rados_config_t handle retrieved from a given
196 * rados_t is only valid as long as that rados_t.
198 typedef void *rados_config_t
;
201 * @typedef rados_ioctx_t
203 * An io context encapsulates a few settings for all I/O operations
205 * - pool - set when the io context is created (see rados_ioctx_create())
206 * - snapshot context for writes (see
207 * rados_ioctx_selfmanaged_snap_set_write_ctx())
208 * - snapshot id to read from (see rados_ioctx_snap_set_read())
209 * - object locator for all single-object operations (see
210 * rados_ioctx_locator_set_key())
211 * - namespace for all single-object operations (see
212 * rados_ioctx_set_namespace()). Set to LIBRADOS_ALL_NSPACES
213 * before rados_nobjects_list_open() will list all objects in all
216 * @warning Changing any of these settings is not thread-safe -
217 * librados users must synchronize any of these changes on their own,
218 * or use separate io contexts for each thread
220 typedef void *rados_ioctx_t
;
223 * @typedef rados_list_ctx_t
225 * An iterator for listing the objects in a pool.
226 * Used with rados_nobjects_list_open(),
227 * rados_nobjects_list_next(), rados_nobjects_list_next2(), and
228 * rados_nobjects_list_close().
230 typedef void *rados_list_ctx_t
;
233 * @typedef rados_object_list_cursor
235 * The cursor used with rados_enumerate_objects
236 * and accompanying methods.
238 typedef void * rados_object_list_cursor
;
241 * @struct rados_object_list_item
243 * The item populated by rados_object_list in
250 /// name of the object
253 size_t nspace_length
;
254 /// the object namespace
257 size_t locator_length
;
260 } rados_object_list_item
;
263 * @typedef rados_snap_t
264 * The id of a snapshot.
266 typedef uint64_t rados_snap_t
;
269 * @typedef rados_xattrs_iter_t
270 * An iterator for listing extended attrbutes on an object.
271 * Used with rados_getxattrs(), rados_getxattrs_next(), and
272 * rados_getxattrs_end().
274 typedef void *rados_xattrs_iter_t
;
277 * @typedef rados_omap_iter_t
278 * An iterator for listing omap key/value pairs on an object.
279 * Used with rados_read_op_omap_get_keys(), rados_read_op_omap_get_vals(),
280 * rados_read_op_omap_get_vals_by_keys(), rados_omap_get_next(), and
281 * rados_omap_get_end().
283 typedef void *rados_omap_iter_t
;
286 * @struct rados_pool_stat_t
287 * Usage information for a pool.
289 struct rados_pool_stat_t
{
290 /// space used in bytes
294 /// number of objects in the pool
295 uint64_t num_objects
;
296 /// number of clones of objects
297 uint64_t num_object_clones
;
298 /// num_objects * num_replicas
299 uint64_t num_object_copies
;
300 /// number of objects missing on primary
301 uint64_t num_objects_missing_on_primary
;
302 /// number of objects found on no OSDs
303 uint64_t num_objects_unfound
;
304 /// number of objects replicated fewer times than they should be
305 /// (but found on at least one OSD)
306 uint64_t num_objects_degraded
;
307 /// number of objects read
309 /// objects read in KB
311 /// number of objects written
313 /// objects written in KB
315 /// bytes originally provided by user
316 uint64_t num_user_bytes
;
317 /// bytes passed compression
318 uint64_t compressed_bytes_orig
;
319 /// bytes resulted after compression
320 uint64_t compressed_bytes
;
321 /// bytes allocated at storage
322 uint64_t compressed_bytes_alloc
;
326 * @struct rados_cluster_stat_t
327 * Cluster-wide usage information
329 struct rados_cluster_stat_t
{
330 /// total device size
334 /// total available/free
336 /// number of objects
337 uint64_t num_objects
;
341 * @typedef rados_write_op_t
343 * An object write operation stores a number of operations which can be
344 * executed atomically. For usage, see:
345 * - Creation and deletion: rados_create_write_op() rados_release_write_op()
346 * - Extended attribute manipulation: rados_write_op_cmpxattr()
347 * rados_write_op_cmpxattr(), rados_write_op_setxattr(),
348 * rados_write_op_rmxattr()
349 * - Object map key/value pairs: rados_write_op_omap_set(),
350 * rados_write_op_omap_rm_keys(), rados_write_op_omap_clear(),
351 * rados_write_op_omap_cmp()
352 * - Object properties: rados_write_op_assert_exists(),
353 * rados_write_op_assert_version()
354 * - Creating objects: rados_write_op_create()
355 * - IO on objects: rados_write_op_append(), rados_write_op_write(), rados_write_op_zero
356 * rados_write_op_write_full(), rados_write_op_writesame(), rados_write_op_remove,
357 * rados_write_op_truncate(), rados_write_op_zero(), rados_write_op_cmpext()
358 * - Hints: rados_write_op_set_alloc_hint()
359 * - Performing the operation: rados_write_op_operate(), rados_aio_write_op_operate()
361 typedef void *rados_write_op_t
;
364 * @typedef rados_read_op_t
366 * An object read operation stores a number of operations which can be
367 * executed atomically. For usage, see:
368 * - Creation and deletion: rados_create_read_op() rados_release_read_op()
369 * - Extended attribute manipulation: rados_read_op_cmpxattr(),
370 * rados_read_op_getxattr(), rados_read_op_getxattrs()
371 * - Object map key/value pairs: rados_read_op_omap_get_vals(),
372 * rados_read_op_omap_get_keys(), rados_read_op_omap_get_vals_by_keys(),
373 * rados_read_op_omap_cmp()
374 * - Object properties: rados_read_op_stat(), rados_read_op_assert_exists(),
375 * rados_read_op_assert_version()
376 * - IO on objects: rados_read_op_read(), rados_read_op_checksum(),
377 * rados_read_op_cmpext()
378 * - Custom operations: rados_read_op_exec(), rados_read_op_exec_user_buf()
379 * - Request properties: rados_read_op_set_flags()
380 * - Performing the operation: rados_read_op_operate(),
381 * rados_aio_read_op_operate()
383 typedef void *rados_read_op_t
;
386 * @typedef rados_completion_t
387 * Represents the state of an asynchronous operation - it contains the
388 * return value once the operation completes, and can be used to block
389 * until the operation is complete or safe.
391 typedef void *rados_completion_t
;
394 * @struct blkin_trace_info
395 * blkin trace information for Zipkin tracing
397 struct blkin_trace_info
;
400 * Get the version of librados.
402 * The version number is major.minor.extra. Note that this is
403 * unrelated to the Ceph version number.
405 * TODO: define version semantics, i.e.:
406 * - incrementing major is for backwards-incompatible changes
407 * - incrementing minor is for backwards-compatible changes
408 * - incrementing extra is for bug fixes
410 * @param major where to store the major version number
411 * @param minor where to store the minor version number
412 * @param extra where to store the extra version number
414 CEPH_RADOS_API
void rados_version(int *major
, int *minor
, int *extra
);
417 * @name Setup and Teardown
418 * These are the first and last functions to that should be called
419 * when using librados.
425 * Create a handle for communicating with a RADOS cluster.
427 * Ceph environment variables are read when this is called, so if
428 * $CEPH_ARGS specifies everything you need to connect, no further
429 * configuration is necessary.
431 * @param cluster where to store the handle
432 * @param id the user to connect as (i.e. admin, not client.admin)
433 * @returns 0 on success, negative error code on failure
435 CEPH_RADOS_API
int rados_create(rados_t
*cluster
, const char * const id
);
438 * Extended version of rados_create.
440 * Like rados_create, but
441 * 1) don't assume 'client\.'+id; allow full specification of name
442 * 2) allow specification of cluster name
443 * 3) flags for future expansion
445 CEPH_RADOS_API
int rados_create2(rados_t
*pcluster
,
446 const char *const clustername
,
447 const char * const name
, uint64_t flags
);
450 * Initialize a cluster handle from an existing configuration.
452 * Share configuration state with another rados_t instance.
454 * @param cluster where to store the handle
455 * @param cct the existing configuration to use
456 * @returns 0 on success, negative error code on failure
458 CEPH_RADOS_API
int rados_create_with_context(rados_t
*cluster
,
462 * Ping the monitor with ID mon_id, storing the resulting reply in
463 * buf (if specified) with a maximum size of len.
465 * The result buffer is allocated on the heap; the caller is
466 * expected to release that memory with rados_buffer_free(). The
467 * buffer and length pointers can be NULL, in which case they are
470 * @param cluster cluster handle
471 * @param mon_id [in] ID of the monitor to ping
472 * @param outstr [out] double pointer with the resulting reply
473 * @param outstrlen [out] pointer with the size of the reply in outstr
475 CEPH_RADOS_API
int rados_ping_monitor(rados_t cluster
, const char *mon_id
,
476 char **outstr
, size_t *outstrlen
);
479 * Connect to the cluster.
481 * @note BUG: Before calling this, calling a function that communicates with the
482 * cluster will crash.
484 * @pre The cluster handle is configured with at least a monitor
485 * address. If cephx is enabled, a client name and secret must also be
488 * @post If this succeeds, any function in librados may be used
490 * @param cluster The cluster to connect to.
491 * @returns 0 on success, negative error code on failure
493 CEPH_RADOS_API
int rados_connect(rados_t cluster
);
496 * Disconnects from the cluster.
498 * For clean up, this is only necessary after rados_connect() has
501 * @warning This does not guarantee any asynchronous writes have
502 * completed. To do that, you must call rados_aio_flush() on all open
505 * @warning We implicitly call rados_watch_flush() on shutdown. If
506 * there are watches being used, this should be done explicitly before
507 * destroying the relevant IoCtx. We do it here as a safety measure.
509 * @post the cluster handle cannot be used again
511 * @param cluster the cluster to shutdown
513 CEPH_RADOS_API
void rados_shutdown(rados_t cluster
);
518 * @name Configuration
519 * These functions read and update Ceph configuration for a cluster
520 * handle. Any configuration changes must be done before connecting to
523 * Options that librados users might want to set include:
526 * - key, keyfile, or keyring when using cephx
527 * - log_file, log_to_stderr, err_to_stderr, and log_to_syslog
528 * - debug_rados, debug_objecter, debug_monc, debug_auth, or debug_ms
530 * See docs.ceph.com for information about available configuration options`
536 * Configure the cluster handle using a Ceph config file
538 * If path is NULL, the default locations are searched, and the first
539 * found is used. The locations are:
540 * - $CEPH_CONF (environment variable)
541 * - /etc/ceph/ceph.conf
543 * - ceph.conf (in the current working directory)
545 * @pre rados_connect() has not been called on the cluster handle
547 * @param cluster cluster handle to configure
548 * @param path path to a Ceph configuration file
549 * @returns 0 on success, negative error code on failure
551 CEPH_RADOS_API
int rados_conf_read_file(rados_t cluster
, const char *path
);
554 * Configure the cluster handle with command line arguments
556 * argv can contain any common Ceph command line option, including any
557 * configuration parameter prefixed by '--' and replacing spaces with
558 * dashes or underscores. For example, the following options are equivalent:
559 * - --mon-host 10.0.0.1:6789
560 * - --mon_host 10.0.0.1:6789
563 * @pre rados_connect() has not been called on the cluster handle
565 * @param cluster cluster handle to configure
566 * @param argc number of arguments in argv
567 * @param argv arguments to parse
568 * @returns 0 on success, negative error code on failure
570 CEPH_RADOS_API
int rados_conf_parse_argv(rados_t cluster
, int argc
,
575 * Configure the cluster handle with command line arguments, returning
576 * any remainders. Same rados_conf_parse_argv, except for extra
577 * remargv argument to hold returns unrecognized arguments.
579 * @pre rados_connect() has not been called on the cluster handle
581 * @param cluster cluster handle to configure
582 * @param argc number of arguments in argv
583 * @param argv arguments to parse
584 * @param remargv char* array for returned unrecognized arguments
585 * @returns 0 on success, negative error code on failure
587 CEPH_RADOS_API
int rados_conf_parse_argv_remainder(rados_t cluster
, int argc
,
589 const char **remargv
);
591 * Configure the cluster handle based on an environment variable
593 * The contents of the environment variable are parsed as if they were
594 * Ceph command line options. If var is NULL, the CEPH_ARGS
595 * environment variable is used.
597 * @pre rados_connect() has not been called on the cluster handle
599 * @note BUG: this is not threadsafe - it uses a static buffer
601 * @param cluster cluster handle to configure
602 * @param var name of the environment variable to read
603 * @returns 0 on success, negative error code on failure
605 CEPH_RADOS_API
int rados_conf_parse_env(rados_t cluster
, const char *var
);
608 * Set a configuration option
610 * @pre rados_connect() has not been called on the cluster handle
612 * @param cluster cluster handle to configure
613 * @param option option to set
614 * @param value value of the option
615 * @returns 0 on success, negative error code on failure
616 * @returns -ENOENT when the option is not a Ceph configuration option
618 CEPH_RADOS_API
int rados_conf_set(rados_t cluster
, const char *option
,
622 * Get the value of a configuration option
624 * @param cluster configuration to read
625 * @param option which option to read
626 * @param buf where to write the configuration value
627 * @param len the size of buf in bytes
628 * @returns 0 on success, negative error code on failure
629 * @returns -ENAMETOOLONG if the buffer is too short to contain the
632 CEPH_RADOS_API
int rados_conf_get(rados_t cluster
, const char *option
,
633 char *buf
, size_t len
);
638 * Read usage info about the cluster
640 * This tells you total space, space used, space available, and number
641 * of objects. These are not updated immediately when data is written,
642 * they are eventually consistent.
644 * @param cluster cluster to query
645 * @param result where to store the results
646 * @returns 0 on success, negative error code on failure
648 CEPH_RADOS_API
int rados_cluster_stat(rados_t cluster
,
649 struct rados_cluster_stat_t
*result
);
652 * Get the fsid of the cluster as a hexadecimal string.
654 * The fsid is a unique id of an entire Ceph cluster.
656 * @param cluster where to get the fsid
657 * @param buf where to write the fsid
658 * @param len the size of buf in bytes (should be 37)
659 * @returns 0 on success, negative error code on failure
660 * @returns -ERANGE if the buffer is too short to contain the
663 CEPH_RADOS_API
int rados_cluster_fsid(rados_t cluster
, char *buf
, size_t len
);
666 * Get/wait for the most recent osdmap
668 * @param cluster the cluster to shutdown
669 * @returns 0 on success, negative error code on failure
671 CEPH_RADOS_API
int rados_wait_for_latest_osdmap(rados_t cluster
);
676 * RADOS pools are separate namespaces for objects. Pools may have
677 * different crush rules associated with them, so they could have
678 * differing replication levels or placement strategies. RADOS
679 * permissions are also tied to pools - users can have different read,
680 * write, and execute permissions on a per-pool basis.
688 * Gets a list of pool names as NULL-terminated strings. The pool
689 * names will be placed in the supplied buffer one after another.
690 * After the last pool name, there will be two 0 bytes in a row.
692 * If len is too short to fit all the pool name entries we need, we will fill
695 * Buf may be null to determine the buffer size needed to list all pools.
697 * @param cluster cluster handle
698 * @param buf output buffer
699 * @param len output buffer length
700 * @returns length of the buffer we would need to list all pools
702 CEPH_RADOS_API
int rados_pool_list(rados_t cluster
, char *buf
, size_t len
);
705 * List inconsistent placement groups of the given pool
707 * Gets a list of inconsistent placement groups as NULL-terminated strings.
708 * The placement group names will be placed in the supplied buffer one after
709 * another. After the last name, there will be two 0 types in a row.
711 * If len is too short to fit all the placement group entries we need, we will
712 * fill as much as we can.
714 * @param cluster cluster handle
715 * @param pool pool ID
716 * @param buf output buffer
717 * @param len output buffer length
718 * @returns length of the buffer we would need to list all pools
720 CEPH_RADOS_API
int rados_inconsistent_pg_list(rados_t cluster
, int64_t pool
,
721 char *buf
, size_t len
);
724 * Get a configuration handle for a rados cluster handle
726 * This handle is valid only as long as the cluster handle is valid.
728 * @param cluster cluster handle
729 * @returns config handle for this cluster
731 CEPH_RADOS_API rados_config_t
rados_cct(rados_t cluster
);
734 * Get a global id for current instance
736 * This id is a unique representation of current connection to the cluster
738 * @param cluster cluster handle
739 * @returns instance global id
741 CEPH_RADOS_API
uint64_t rados_get_instance_id(rados_t cluster
);
744 * Gets the minimum compatible OSD version
746 * @param cluster cluster handle
747 * @param require_osd_release [out] minimum compatible OSD version
748 * based upon the current features
749 * @returns 0 on sucess, negative error code on failure
751 CEPH_RADOS_API
int rados_get_min_compatible_osd(rados_t cluster
,
752 int8_t* require_osd_release
);
755 * Gets the minimum compatible client version
757 * @param cluster cluster handle
758 * @param min_compat_client [out] minimum compatible client version
759 * based upon the current features
760 * @param require_min_compat_client [out] required minimum client version
761 * based upon explicit setting
762 * @returns 0 on success, negative error code on failure
764 CEPH_RADOS_API
int rados_get_min_compatible_client(rados_t cluster
,
765 int8_t* min_compat_client
,
766 int8_t* require_min_compat_client
);
769 * Create an io context
771 * The io context allows you to perform operations within a particular
772 * pool. For more details see rados_ioctx_t.
774 * @param cluster which cluster the pool is in
775 * @param pool_name name of the pool
776 * @param ioctx where to store the io context
777 * @returns 0 on success, negative error code on failure
779 CEPH_RADOS_API
int rados_ioctx_create(rados_t cluster
, const char *pool_name
,
780 rados_ioctx_t
*ioctx
);
781 CEPH_RADOS_API
int rados_ioctx_create2(rados_t cluster
, int64_t pool_id
,
782 rados_ioctx_t
*ioctx
);
785 * The opposite of rados_ioctx_create
787 * This just tells librados that you no longer need to use the io context.
788 * It may not be freed immediately if there are pending asynchronous
789 * requests on it, but you should not use an io context again after
790 * calling this function on it.
792 * @warning This does not guarantee any asynchronous
793 * writes have completed. You must call rados_aio_flush()
794 * on the io context before destroying it to do that.
796 * @warning If this ioctx is used by rados_watch, the caller needs to
797 * be sure that all registered watches are disconnected via
798 * rados_unwatch() and that rados_watch_flush() is called. This
799 * ensures that a racing watch callback does not make use of a
802 * @param io the io context to dispose of
804 CEPH_RADOS_API
void rados_ioctx_destroy(rados_ioctx_t io
);
807 * Get configuration handle for a pool handle
809 * @param io pool handle
810 * @returns rados_config_t for this cluster
812 CEPH_RADOS_API rados_config_t
rados_ioctx_cct(rados_ioctx_t io
);
815 * Get the cluster handle used by this rados_ioctx_t
816 * Note that this is a weak reference, and should not
817 * be destroyed via rados_shutdown().
819 * @param io the io context
820 * @returns the cluster handle for this io context
822 CEPH_RADOS_API rados_t
rados_ioctx_get_cluster(rados_ioctx_t io
);
825 * Get pool usage statistics
827 * Fills in a rados_pool_stat_t after querying the cluster.
829 * @param io determines which pool to query
830 * @param stats where to store the results
831 * @returns 0 on success, negative error code on failure
833 CEPH_RADOS_API
int rados_ioctx_pool_stat(rados_ioctx_t io
,
834 struct rados_pool_stat_t
*stats
);
837 * Get the id of a pool
839 * @param cluster which cluster the pool is in
840 * @param pool_name which pool to look up
841 * @returns id of the pool
842 * @returns -ENOENT if the pool is not found
844 CEPH_RADOS_API
int64_t rados_pool_lookup(rados_t cluster
,
845 const char *pool_name
);
848 * Get the name of a pool
850 * @param cluster which cluster the pool is in
851 * @param id the id of the pool
852 * @param buf where to store the pool name
853 * @param maxlen size of buffer where name will be stored
854 * @returns length of string stored, or -ERANGE if buffer too small
856 CEPH_RADOS_API
int rados_pool_reverse_lookup(rados_t cluster
, int64_t id
,
857 char *buf
, size_t maxlen
);
860 * Create a pool with default settings
862 * The default crush rule is rule 0.
864 * @param cluster the cluster in which the pool will be created
865 * @param pool_name the name of the new pool
866 * @returns 0 on success, negative error code on failure
868 CEPH_RADOS_API
int rados_pool_create(rados_t cluster
, const char *pool_name
);
871 * Create a pool owned by a specific auid.
873 * DEPRECATED: auid support has been removed, and this call will be removed in a future
876 * @param cluster the cluster in which the pool will be created
877 * @param pool_name the name of the new pool
878 * @param auid the id of the owner of the new pool
879 * @returns 0 on success, negative error code on failure
881 CEPH_RADOS_API
int rados_pool_create_with_auid(rados_t cluster
,
882 const char *pool_name
,
884 __attribute__((deprecated
));
887 * Create a pool with a specific CRUSH rule
889 * @param cluster the cluster in which the pool will be created
890 * @param pool_name the name of the new pool
891 * @param crush_rule_num which rule to use for placement in the new pool1
892 * @returns 0 on success, negative error code on failure
894 CEPH_RADOS_API
int rados_pool_create_with_crush_rule(rados_t cluster
,
895 const char *pool_name
,
896 uint8_t crush_rule_num
);
899 * Create a pool with a specific CRUSH rule and auid
901 * DEPRECATED: auid support has been removed and this call will be removed
902 * in a future release.
904 * This is a combination of rados_pool_create_with_crush_rule() and
905 * rados_pool_create_with_auid().
907 * @param cluster the cluster in which the pool will be created
908 * @param pool_name the name of the new pool
909 * @param crush_rule_num which rule to use for placement in the new pool2
910 * @param auid the id of the owner of the new pool
911 * @returns 0 on success, negative error code on failure
913 CEPH_RADOS_API
int rados_pool_create_with_all(rados_t cluster
,
914 const char *pool_name
,
916 uint8_t crush_rule_num
)
917 __attribute__((deprecated
));
920 * Returns the pool that is the base tier for this pool.
922 * The return value is the ID of the pool that should be used to read from/write to.
923 * If tiering is not set up for the pool, returns \c pool.
925 * @param cluster the cluster the pool is in
926 * @param pool ID of the pool to query
927 * @param base_tier [out] base tier, or \c pool if tiering is not configured
928 * @returns 0 on success, negative error code on failure
930 CEPH_RADOS_API
int rados_pool_get_base_tier(rados_t cluster
, int64_t pool
,
934 * Delete a pool and all data inside it
936 * The pool is removed from the cluster immediately,
937 * but the actual data is deleted in the background.
939 * @param cluster the cluster the pool is in
940 * @param pool_name which pool to delete
941 * @returns 0 on success, negative error code on failure
943 CEPH_RADOS_API
int rados_pool_delete(rados_t cluster
, const char *pool_name
);
946 * Attempt to change an io context's associated auid "owner"
948 * DEPRECATED: auid support has been removed and this call has no effect.
950 * Requires that you have write permission on both the current and new
953 * @param io reference to the pool to change.
954 * @param auid the auid you wish the io to have.
955 * @returns 0 on success, negative error code on failure
957 CEPH_RADOS_API
int rados_ioctx_pool_set_auid(rados_ioctx_t io
, uint64_t auid
)
958 __attribute__((deprecated
));
962 * Get the auid of a pool
964 * DEPRECATED: auid support has been removed and this call always reports
965 * CEPH_AUTH_UID_DEFAULT (-1).
967 * @param io pool to query
968 * @param auid where to store the auid
969 * @returns 0 on success, negative error code on failure
971 CEPH_RADOS_API
int rados_ioctx_pool_get_auid(rados_ioctx_t io
, uint64_t *auid
)
972 __attribute__((deprecated
));
974 /* deprecated, use rados_ioctx_pool_requires_alignment2 instead */
975 CEPH_RADOS_API
int rados_ioctx_pool_requires_alignment(rados_ioctx_t io
)
976 __attribute__((deprecated
));
979 * Test whether the specified pool requires alignment or not.
981 * @param io pool to query
982 * @param req 1 if alignment is supported, 0 if not.
983 * @returns 0 on success, negative error code on failure
985 CEPH_RADOS_API
int rados_ioctx_pool_requires_alignment2(rados_ioctx_t io
,
988 /* deprecated, use rados_ioctx_pool_required_alignment2 instead */
989 CEPH_RADOS_API
uint64_t rados_ioctx_pool_required_alignment(rados_ioctx_t io
)
990 __attribute__((deprecated
));
993 * Get the alignment flavor of a pool
995 * @param io pool to query
996 * @param alignment where to store the alignment flavor
997 * @returns 0 on success, negative error code on failure
999 CEPH_RADOS_API
int rados_ioctx_pool_required_alignment2(rados_ioctx_t io
,
1000 uint64_t *alignment
);
1003 * Get the pool id of the io context
1005 * @param io the io context to query
1006 * @returns the id of the pool the io context uses
1008 CEPH_RADOS_API
int64_t rados_ioctx_get_id(rados_ioctx_t io
);
1011 * Get the pool name of the io context
1013 * @param io the io context to query
1014 * @param buf pointer to buffer where name will be stored
1015 * @param maxlen size of buffer where name will be stored
1016 * @returns length of string stored, or -ERANGE if buffer too small
1018 CEPH_RADOS_API
int rados_ioctx_get_pool_name(rados_ioctx_t io
, char *buf
,
1024 * @name Object Locators
1030 * Set the key for mapping objects to pgs within an io context.
1032 * The key is used instead of the object name to determine which
1033 * placement groups an object is put in. This affects all subsequent
1034 * operations of the io context - until a different locator key is
1035 * set, all objects in this io context will be placed in the same pg.
1037 * @param io the io context to change
1038 * @param key the key to use as the object locator, or NULL to discard
1039 * any previously set key
1041 CEPH_RADOS_API
void rados_ioctx_locator_set_key(rados_ioctx_t io
,
1045 * Set the namespace for objects within an io context
1047 * The namespace specification further refines a pool into different
1048 * domains. The mapping of objects to pgs is also based on this
1051 * @param io the io context to change
1052 * @param nspace the name to use as the namespace, or NULL use the
1055 CEPH_RADOS_API
void rados_ioctx_set_namespace(rados_ioctx_t io
,
1056 const char *nspace
);
1059 * Get the namespace for objects within the io context
1061 * @param io the io context to query
1062 * @param buf pointer to buffer where name will be stored
1063 * @param maxlen size of buffer where name will be stored
1064 * @returns length of string stored, or -ERANGE if buffer too small
1066 CEPH_RADOS_API
int rados_ioctx_get_namespace(rados_ioctx_t io
, char *buf
,
1072 * @name Listing Objects
1076 * Start listing objects in a pool
1078 * @param io the pool to list from
1079 * @param ctx the handle to store list context in
1080 * @returns 0 on success, negative error code on failure
1082 CEPH_RADOS_API
int rados_nobjects_list_open(rados_ioctx_t io
,
1083 rados_list_ctx_t
*ctx
);
1086 * Return hash position of iterator, rounded to the current PG
1088 * @param ctx iterator marking where you are in the listing
1089 * @returns current hash position, rounded to the current pg
1091 CEPH_RADOS_API
uint32_t rados_nobjects_list_get_pg_hash_position(rados_list_ctx_t ctx
);
1094 * Reposition object iterator to a different hash position
1096 * @param ctx iterator marking where you are in the listing
1097 * @param pos hash position to move to
1098 * @returns actual (rounded) position we moved to
1100 CEPH_RADOS_API
uint32_t rados_nobjects_list_seek(rados_list_ctx_t ctx
,
1104 * Reposition object iterator to a different position
1106 * @param ctx iterator marking where you are in the listing
1107 * @param cursor position to move to
1108 * @returns rounded position we moved to
1110 CEPH_RADOS_API
uint32_t rados_nobjects_list_seek_cursor(rados_list_ctx_t ctx
,
1111 rados_object_list_cursor cursor
);
1114 * Reposition object iterator to a different position
1116 * The returned handle must be released with rados_object_list_cursor_free().
1118 * @param ctx iterator marking where you are in the listing
1119 * @param cursor where to store cursor
1120 * @returns 0 on success, negative error code on failure
1122 CEPH_RADOS_API
int rados_nobjects_list_get_cursor(rados_list_ctx_t ctx
,
1123 rados_object_list_cursor
*cursor
);
1126 * Get the next object name and locator in the pool
1128 * *entry and *key are valid until next call to rados_nobjects_list_*
1130 * @param ctx iterator marking where you are in the listing
1131 * @param entry where to store the name of the entry
1132 * @param key where to store the object locator (set to NULL to ignore)
1133 * @param nspace where to store the object namespace (set to NULL to ignore)
1134 * @returns 0 on success, negative error code on failure
1135 * @returns -ENOENT when there are no more objects to list
1137 CEPH_RADOS_API
int rados_nobjects_list_next(rados_list_ctx_t ctx
,
1140 const char **nspace
);
1143 * Get the next object name, locator and their sizes in the pool
1145 * The sizes allow to list objects with \0 (the NUL character)
1146 * in .e.g *entry. Is is unusual see such object names but a bug
1147 * in a client has risen the need to handle them as well.
1148 * *entry and *key are valid until next call to rados_nobjects_list_*
1150 * @param ctx iterator marking where you are in the listing
1151 * @param entry where to store the name of the entry
1152 * @param key where to store the object locator (set to NULL to ignore)
1153 * @param nspace where to store the object namespace (set to NULL to ignore)
1154 * @param entry_size where to store the size of name of the entry
1155 * @param key_size where to store the size of object locator (set to NULL to ignore)
1156 * @param nspace_size where to store the size of object namespace (set to NULL to ignore)
1157 * @returns 0 on success, negative error code on failure
1158 * @returns -ENOENT when there are no more objects to list
1160 CEPH_RADOS_API
int rados_nobjects_list_next2(rados_list_ctx_t ctx
,
1163 const char **nspace
,
1166 size_t *nspace_size
);
1169 * Close the object listing handle.
1171 * This should be called when the handle is no longer needed.
1172 * The handle should not be used after it has been closed.
1174 * @param ctx the handle to close
1176 CEPH_RADOS_API
void rados_nobjects_list_close(rados_list_ctx_t ctx
);
1179 * Get cursor handle pointing to the *beginning* of a pool.
1181 * This is an opaque handle pointing to the start of a pool. It must
1182 * be released with rados_object_list_cursor_free().
1184 * @param io ioctx for the pool
1185 * @returns handle for the pool, NULL on error (pool does not exist)
1187 CEPH_RADOS_API rados_object_list_cursor
rados_object_list_begin(
1191 * Get cursor handle pointing to the *end* of a pool.
1193 * This is an opaque handle pointing to the start of a pool. It must
1194 * be released with rados_object_list_cursor_free().
1196 * @param io ioctx for the pool
1197 * @returns handle for the pool, NULL on error (pool does not exist)
1199 CEPH_RADOS_API rados_object_list_cursor
rados_object_list_end(rados_ioctx_t io
);
1202 * Check if a cursor has reached the end of a pool
1206 * @returns 1 if the cursor has reached the end of the pool, 0 otherwise
1208 CEPH_RADOS_API
int rados_object_list_is_end(rados_ioctx_t io
,
1209 rados_object_list_cursor cur
);
1214 * Release a cursor. The handle may not be used after this point.
1219 CEPH_RADOS_API
void rados_object_list_cursor_free(rados_ioctx_t io
,
1220 rados_object_list_cursor cur
);
1223 * Compare two cursor positions
1225 * Compare two cursors, and indicate whether the first cursor precedes,
1226 * matches, or follows the second.
1229 * @param lhs first cursor
1230 * @param rhs second cursor
1231 * @returns -1, 0, or 1 for lhs < rhs, lhs == rhs, or lhs > rhs
1233 CEPH_RADOS_API
int rados_object_list_cursor_cmp(rados_ioctx_t io
,
1234 rados_object_list_cursor lhs
, rados_object_list_cursor rhs
);
1237 * @return the number of items set in the results array
1239 CEPH_RADOS_API
int rados_object_list(rados_ioctx_t io
,
1240 const rados_object_list_cursor start
,
1241 const rados_object_list_cursor finish
,
1242 const size_t result_size
,
1243 const char *filter_buf
,
1244 const size_t filter_buf_len
,
1245 rados_object_list_item
*results
,
1246 rados_object_list_cursor
*next
);
1248 CEPH_RADOS_API
void rados_object_list_free(
1249 const size_t result_size
,
1250 rados_object_list_item
*results
);
1253 * Obtain cursors delineating a subset of a range. Use this
1254 * when you want to split up the work of iterating over the
1255 * global namespace. Expected use case is when you are iterating
1256 * in parallel, with `m` workers, and each worker taking an id `n`.
1259 * @param start start of the range to be sliced up (inclusive)
1260 * @param finish end of the range to be sliced up (exclusive)
1261 * @param n which of the m chunks you would like to get cursors for
1262 * @param m how many chunks to divide start-finish into
1263 * @param split_start cursor populated with start of the subrange (inclusive)
1264 * @param split_finish cursor populated with end of the subrange (exclusive)
1266 CEPH_RADOS_API
void rados_object_list_slice(rados_ioctx_t io
,
1267 const rados_object_list_cursor start
,
1268 const rados_object_list_cursor finish
,
1271 rados_object_list_cursor
*split_start
,
1272 rados_object_list_cursor
*split_finish
);
1275 /** @} Listing Objects */
1280 * RADOS snapshots are based upon sequence numbers that form a
1281 * snapshot context. They are pool-specific. The snapshot context
1282 * consists of the current snapshot sequence number for a pool, and an
1283 * array of sequence numbers at which snapshots were taken, in
1284 * descending order. Whenever a snapshot is created or deleted, the
1285 * snapshot sequence number for the pool is increased. To add a new
1286 * snapshot, the new snapshot sequence number must be increased and
1287 * added to the snapshot context.
1289 * There are two ways to manage these snapshot contexts:
1290 * -# within the RADOS cluster
1291 * These are called pool snapshots, and store the snapshot context
1292 * in the OSDMap. These represent a snapshot of all the objects in
1294 * -# within the RADOS clients
1295 * These are called self-managed snapshots, and push the
1296 * responsibility for keeping track of the snapshot context to the
1297 * clients. For every write, the client must send the snapshot
1298 * context. In librados, this is accomplished with
1299 * rados_selfmanaged_snap_set_write_ctx(). These are more
1300 * difficult to manage, but are restricted to specific objects
1301 * instead of applying to an entire pool.
1307 * Create a pool-wide snapshot
1309 * @param io the pool to snapshot
1310 * @param snapname the name of the snapshot
1311 * @returns 0 on success, negative error code on failure
1313 CEPH_RADOS_API
int rados_ioctx_snap_create(rados_ioctx_t io
,
1314 const char *snapname
);
1317 * Delete a pool snapshot
1319 * @param io the pool to delete the snapshot from
1320 * @param snapname which snapshot to delete
1321 * @returns 0 on success, negative error code on failure
1323 CEPH_RADOS_API
int rados_ioctx_snap_remove(rados_ioctx_t io
,
1324 const char *snapname
);
1327 * Rollback an object to a pool snapshot
1329 * The contents of the object will be the same as
1330 * when the snapshot was taken.
1332 * @param io the pool in which the object is stored
1333 * @param oid the name of the object to rollback
1334 * @param snapname which snapshot to rollback to
1335 * @returns 0 on success, negative error code on failure
1337 CEPH_RADOS_API
int rados_ioctx_snap_rollback(rados_ioctx_t io
, const char *oid
,
1338 const char *snapname
);
1341 * @warning Deprecated: Use rados_ioctx_snap_rollback() instead
1343 CEPH_RADOS_API
int rados_rollback(rados_ioctx_t io
, const char *oid
,
1344 const char *snapname
)
1345 __attribute__((deprecated
));
1348 * Set the snapshot from which reads are performed.
1350 * Subsequent reads will return data as it was at the time of that
1353 * @param io the io context to change
1354 * @param snap the id of the snapshot to set, or LIBRADOS_SNAP_HEAD for no
1355 * snapshot (i.e. normal operation)
1357 CEPH_RADOS_API
void rados_ioctx_snap_set_read(rados_ioctx_t io
,
1361 * Allocate an ID for a self-managed snapshot
1363 * Get a unique ID to put in the snaphot context to create a
1364 * snapshot. A clone of an object is not created until a write with
1365 * the new snapshot context is completed.
1367 * @param io the pool in which the snapshot will exist
1368 * @param snapid where to store the newly allocated snapshot ID
1369 * @returns 0 on success, negative error code on failure
1371 CEPH_RADOS_API
int rados_ioctx_selfmanaged_snap_create(rados_ioctx_t io
,
1372 rados_snap_t
*snapid
);
1374 rados_aio_ioctx_selfmanaged_snap_create(rados_ioctx_t io
,
1375 rados_snap_t
*snapid
,
1376 rados_completion_t completion
);
1379 * Remove a self-managed snapshot
1381 * This increases the snapshot sequence number, which will cause
1382 * snapshots to be removed lazily.
1384 * @param io the pool in which the snapshot will exist
1385 * @param snapid where to store the newly allocated snapshot ID
1386 * @returns 0 on success, negative error code on failure
1388 CEPH_RADOS_API
int rados_ioctx_selfmanaged_snap_remove(rados_ioctx_t io
,
1389 rados_snap_t snapid
);
1391 rados_aio_ioctx_selfmanaged_snap_remove(rados_ioctx_t io
,
1392 rados_snap_t snapid
,
1393 rados_completion_t completion
);
1396 * Rollback an object to a self-managed snapshot
1398 * The contents of the object will be the same as
1399 * when the snapshot was taken.
1401 * @param io the pool in which the object is stored
1402 * @param oid the name of the object to rollback
1403 * @param snapid which snapshot to rollback to
1404 * @returns 0 on success, negative error code on failure
1406 CEPH_RADOS_API
int rados_ioctx_selfmanaged_snap_rollback(rados_ioctx_t io
,
1408 rados_snap_t snapid
);
1411 * Set the snapshot context for use when writing to objects
1413 * This is stored in the io context, and applies to all future writes.
1415 * @param io the io context to change
1416 * @param seq the newest snapshot sequence number for the pool
1417 * @param snaps array of snapshots in sorted by descending id
1418 * @param num_snaps how many snaphosts are in the snaps array
1419 * @returns 0 on success, negative error code on failure
1420 * @returns -EINVAL if snaps are not in descending order
1422 CEPH_RADOS_API
int rados_ioctx_selfmanaged_snap_set_write_ctx(rados_ioctx_t io
,
1424 rados_snap_t
*snaps
,
1428 * List all the ids of pool snapshots
1430 * If the output array does not have enough space to fit all the
1431 * snapshots, -ERANGE is returned and the caller should retry with a
1434 * @param io the pool to read from
1435 * @param snaps where to store the results
1436 * @param maxlen the number of rados_snap_t that fit in the snaps array
1437 * @returns number of snapshots on success, negative error code on failure
1438 * @returns -ERANGE is returned if the snaps array is too short
1440 CEPH_RADOS_API
int rados_ioctx_snap_list(rados_ioctx_t io
, rados_snap_t
*snaps
,
1444 * Get the id of a pool snapshot
1446 * @param io the pool to read from
1447 * @param name the snapshot to find
1448 * @param id where to store the result
1449 * @returns 0 on success, negative error code on failure
1451 CEPH_RADOS_API
int rados_ioctx_snap_lookup(rados_ioctx_t io
, const char *name
,
1455 * Get the name of a pool snapshot
1457 * @param io the pool to read from
1458 * @param id the snapshot to find
1459 * @param name where to store the result
1460 * @param maxlen the size of the name array
1461 * @returns 0 on success, negative error code on failure
1462 * @returns -ERANGE if the name array is too small
1464 CEPH_RADOS_API
int rados_ioctx_snap_get_name(rados_ioctx_t io
, rados_snap_t id
,
1465 char *name
, int maxlen
);
1468 * Find when a pool snapshot occurred
1470 * @param io the pool the snapshot was taken in
1471 * @param id the snapshot to lookup
1472 * @param t where to store the result
1473 * @returns 0 on success, negative error code on failure
1475 CEPH_RADOS_API
int rados_ioctx_snap_get_stamp(rados_ioctx_t io
, rados_snap_t id
,
1481 * @name Synchronous I/O
1482 * Writes are replicated to a number of OSDs based on the
1483 * configuration of the pool they are in. These write functions block
1484 * until data is in memory on all replicas of the object they're
1485 * writing to - they are equivalent to doing the corresponding
1486 * asynchronous write, and the calling
1487 * rados_ioctx_wait_for_complete(). For greater data safety, use the
1488 * asynchronous functions and rados_aio_wait_for_safe().
1494 * Return the version of the last object read or written to.
1496 * This exposes the internal version number of the last object read or
1497 * written via this io context
1499 * @param io the io context to check
1500 * @returns last read or written object version
1502 CEPH_RADOS_API
uint64_t rados_get_last_version(rados_ioctx_t io
);
1505 * Write *len* bytes from *buf* into the *oid* object, starting at
1506 * offset *off*. The value of *len* must be <= UINT_MAX/2.
1508 * @note This will never return a positive value not equal to len.
1509 * @param io the io context in which the write will occur
1510 * @param oid name of the object
1511 * @param buf data to write
1512 * @param len length of the data, in bytes
1513 * @param off byte offset in the object to begin writing at
1514 * @returns 0 on success, negative error code on failure
1516 CEPH_RADOS_API
int rados_write(rados_ioctx_t io
, const char *oid
,
1517 const char *buf
, size_t len
, uint64_t off
);
1520 * Write *len* bytes from *buf* into the *oid* object. The value of
1521 * *len* must be <= UINT_MAX/2.
1523 * The object is filled with the provided data. If the object exists,
1524 * it is atomically truncated and then written.
1526 * @param io the io context in which the write will occur
1527 * @param oid name of the object
1528 * @param buf data to write
1529 * @param len length of the data, in bytes
1530 * @returns 0 on success, negative error code on failure
1532 CEPH_RADOS_API
int rados_write_full(rados_ioctx_t io
, const char *oid
,
1533 const char *buf
, size_t len
);
1536 * Write the same *data_len* bytes from *buf* multiple times into the
1537 * *oid* object. *write_len* bytes are written in total, which must be
1538 * a multiple of *data_len*. The value of *write_len* and *data_len*
1539 * must be <= UINT_MAX/2.
1541 * @param io the io context in which the write will occur
1542 * @param oid name of the object
1543 * @param buf data to write
1544 * @param data_len length of the data, in bytes
1545 * @param write_len the total number of bytes to write
1546 * @param off byte offset in the object to begin writing at
1547 * @returns 0 on success, negative error code on failure
1549 CEPH_RADOS_API
int rados_writesame(rados_ioctx_t io
, const char *oid
,
1550 const char *buf
, size_t data_len
,
1551 size_t write_len
, uint64_t off
);
1554 * Append *len* bytes from *buf* into the *oid* object. The value of
1555 * *len* must be <= UINT_MAX/2.
1557 * @param io the context to operate in
1558 * @param oid the name of the object
1559 * @param buf the data to append
1560 * @param len length of buf (in bytes)
1561 * @returns 0 on success, negative error code on failure
1563 CEPH_RADOS_API
int rados_append(rados_ioctx_t io
, const char *oid
,
1564 const char *buf
, size_t len
);
1567 * Read data from an object
1569 * The io context determines the snapshot to read from, if any was set
1570 * by rados_ioctx_snap_set_read().
1572 * @param io the context in which to perform the read
1573 * @param oid the name of the object to read from
1574 * @param buf where to store the results
1575 * @param len the number of bytes to read
1576 * @param off the offset to start reading from in the object
1577 * @returns number of bytes read on success, negative error code on
1580 CEPH_RADOS_API
int rados_read(rados_ioctx_t io
, const char *oid
, char *buf
,
1581 size_t len
, uint64_t off
);
1584 * Compute checksum from object data
1586 * The io context determines the snapshot to checksum, if any was set
1587 * by rados_ioctx_snap_set_read(). The length of the init_value and
1588 * resulting checksum are dependent upon the checksum type:
1594 * The checksum result is encoded the following manner:
1596 * le32 num_checksum_chunks
1598 * leXX checksum for chunk (where XX = appropriate size for the checksum type)
1599 * } * num_checksum_chunks
1601 * @param io the context in which to perform the checksum
1602 * @param oid the name of the object to checksum
1603 * @param type the checksum algorithm to utilize
1604 * @param init_value the init value for the algorithm
1605 * @param init_value_len the length of the init value
1606 * @param len the number of bytes to checksum
1607 * @param off the offset to start checksumming in the object
1608 * @param chunk_size optional length-aligned chunk size for checksums
1609 * @param pchecksum where to store the checksum result
1610 * @param checksum_len the number of bytes available for the result
1611 * @return negative error code on failure
1613 CEPH_RADOS_API
int rados_checksum(rados_ioctx_t io
, const char *oid
,
1614 rados_checksum_type_t type
,
1615 const char *init_value
, size_t init_value_len
,
1616 size_t len
, uint64_t off
, size_t chunk_size
,
1617 char *pchecksum
, size_t checksum_len
);
1622 * @note This does not delete any snapshots of the object.
1624 * @param io the pool to delete the object from
1625 * @param oid the name of the object to delete
1626 * @returns 0 on success, negative error code on failure
1628 CEPH_RADOS_API
int rados_remove(rados_ioctx_t io
, const char *oid
);
1633 * If this enlarges the object, the new area is logically filled with
1634 * zeroes. If this shrinks the object, the excess data is removed.
1636 * @param io the context in which to truncate
1637 * @param oid the name of the object
1638 * @param size the new size of the object in bytes
1639 * @returns 0 on success, negative error code on failure
1641 CEPH_RADOS_API
int rados_trunc(rados_ioctx_t io
, const char *oid
,
1645 * Compare an on-disk object range with a buffer
1647 * @param io the context in which to perform the comparison
1648 * @param o name of the object
1649 * @param cmp_buf buffer containing bytes to be compared with object contents
1650 * @param cmp_len length to compare and size of @c cmp_buf in bytes
1651 * @param off object byte offset at which to start the comparison
1652 * @returns 0 on success, negative error code on failure,
1653 * (-MAX_ERRNO - mismatch_off) on mismatch
1655 CEPH_RADOS_API
int rados_cmpext(rados_ioctx_t io
, const char *o
,
1656 const char *cmp_buf
, size_t cmp_len
,
1661 * Extended attributes are stored as extended attributes on the files
1662 * representing an object on the OSDs. Thus, they have the same
1663 * limitations as the underlying filesystem. On ext4, this means that
1664 * the total data stored in xattrs cannot exceed 4KB.
1670 * Get the value of an extended attribute on an object.
1672 * @param io the context in which the attribute is read
1673 * @param o name of the object
1674 * @param name which extended attribute to read
1675 * @param buf where to store the result
1676 * @param len size of buf in bytes
1677 * @returns length of xattr value on success, negative error code on failure
1679 CEPH_RADOS_API
int rados_getxattr(rados_ioctx_t io
, const char *o
,
1680 const char *name
, char *buf
, size_t len
);
1683 * Set an extended attribute on an object.
1685 * @param io the context in which xattr is set
1686 * @param o name of the object
1687 * @param name which extended attribute to set
1688 * @param buf what to store in the xattr
1689 * @param len the number of bytes in buf
1690 * @returns 0 on success, negative error code on failure
1692 CEPH_RADOS_API
int rados_setxattr(rados_ioctx_t io
, const char *o
,
1693 const char *name
, const char *buf
,
1697 * Delete an extended attribute from an object.
1699 * @param io the context in which to delete the xattr
1700 * @param o the name of the object
1701 * @param name which xattr to delete
1702 * @returns 0 on success, negative error code on failure
1704 CEPH_RADOS_API
int rados_rmxattr(rados_ioctx_t io
, const char *o
,
1708 * Start iterating over xattrs on an object.
1710 * @post iter is a valid iterator
1712 * @param io the context in which to list xattrs
1713 * @param oid name of the object
1714 * @param iter where to store the iterator
1715 * @returns 0 on success, negative error code on failure
1717 CEPH_RADOS_API
int rados_getxattrs(rados_ioctx_t io
, const char *oid
,
1718 rados_xattrs_iter_t
*iter
);
1721 * Get the next xattr on the object
1723 * @pre iter is a valid iterator
1725 * @post name is the NULL-terminated name of the next xattr, and val
1726 * contains the value of the xattr, which is of length len. If the end
1727 * of the list has been reached, name and val are NULL, and len is 0.
1729 * @param iter iterator to advance
1730 * @param name where to store the name of the next xattr
1731 * @param val where to store the value of the next xattr
1732 * @param len the number of bytes in val
1733 * @returns 0 on success, negative error code on failure
1735 CEPH_RADOS_API
int rados_getxattrs_next(rados_xattrs_iter_t iter
,
1736 const char **name
, const char **val
,
1740 * Close the xattr iterator.
1742 * iter should not be used after this is called.
1744 * @param iter the iterator to close
1746 CEPH_RADOS_API
void rados_getxattrs_end(rados_xattrs_iter_t iter
);
1751 * Get the next omap key/value pair on the object
1753 * @pre iter is a valid iterator
1755 * @post key and val are the next key/value pair. key is
1756 * null-terminated, and val has length len. If the end of the list has
1757 * been reached, key and val are NULL, and len is 0. key and val will
1758 * not be accessible after rados_omap_get_end() is called on iter, so
1759 * if they are needed after that they should be copied.
1761 * @param iter iterator to advance
1762 * @param key where to store the key of the next omap entry
1763 * @param val where to store the value of the next omap entry
1764 * @param len where to store the number of bytes in val
1765 * @returns 0 on success, negative error code on failure
1767 CEPH_RADOS_API
int rados_omap_get_next(rados_omap_iter_t iter
,
1773 * Get the next omap key/value pair on the object. Note that it's
1774 * perfectly safe to mix calls to rados_omap_get_next and
1775 * rados_omap_get_next2.
1777 * @pre iter is a valid iterator
1779 * @post key and val are the next key/value pair. key has length
1780 * keylen and val has length vallen. If the end of the list has
1781 * been reached, key and val are NULL, and keylen and vallen is 0.
1782 * key and val will not be accessible after rados_omap_get_end()
1783 * is called on iter, so if they are needed after that they
1786 * @param iter iterator to advance
1787 * @param key where to store the key of the next omap entry
1788 * @param val where to store the value of the next omap entry
1789 * @param key_len where to store the number of bytes in key
1790 * @param val_len where to store the number of bytes in val
1791 * @returns 0 on success, negative error code on failure
1793 CEPH_RADOS_API
int rados_omap_get_next2(rados_omap_iter_t iter
,
1800 * Return number of elements in the iterator
1802 * @param iter the iterator of which to return the size
1804 CEPH_RADOS_API
unsigned int rados_omap_iter_size(rados_omap_iter_t iter
);
1807 * Close the omap iterator.
1809 * iter should not be used after this is called.
1811 * @param iter the iterator to close
1813 CEPH_RADOS_API
void rados_omap_get_end(rados_omap_iter_t iter
);
1816 * Get object stats (size/mtime)
1818 * TODO: when are these set, and by whom? can they be out of date?
1821 * @param o object name
1822 * @param psize where to store object size
1823 * @param pmtime where to store modification time
1824 * @returns 0 on success, negative error code on failure
1826 CEPH_RADOS_API
int rados_stat(rados_ioctx_t io
, const char *o
, uint64_t *psize
,
1829 * Execute an OSD class method on an object
1831 * The OSD has a plugin mechanism for performing complicated
1832 * operations on an object atomically. These plugins are called
1833 * classes. This function allows librados users to call the custom
1834 * methods. The input and output formats are defined by the class.
1835 * Classes in ceph.git can be found in src/cls subdirectories
1837 * @param io the context in which to call the method
1838 * @param oid the object to call the method on
1839 * @param cls the name of the class
1840 * @param method the name of the method
1841 * @param in_buf where to find input
1842 * @param in_len length of in_buf in bytes
1843 * @param buf where to store output
1844 * @param out_len length of buf in bytes
1845 * @returns the length of the output, or
1846 * -ERANGE if out_buf does not have enough space to store it (For methods that return data). For
1847 * methods that don't return data, the return value is
1850 CEPH_RADOS_API
int rados_exec(rados_ioctx_t io
, const char *oid
,
1851 const char *cls
, const char *method
,
1852 const char *in_buf
, size_t in_len
, char *buf
,
1856 /** @} Synchronous I/O */
1859 * @name Asynchronous I/O
1860 * Read and write to objects without blocking.
1866 * @typedef rados_callback_t
1867 * Callbacks for asynchrous operations take two parameters:
1868 * - cb the completion that has finished
1869 * - arg application defined data made available to the callback function
1871 typedef void (*rados_callback_t
)(rados_completion_t cb
, void *arg
);
1874 * Constructs a completion to use with asynchronous operations
1876 * The complete and safe callbacks correspond to operations being
1877 * acked and committed, respectively. The callbacks are called in
1878 * order of receipt, so the safe callback may be triggered before the
1879 * complete callback, and vice versa. This is affected by journalling
1882 * TODO: more complete documentation of this elsewhere (in the RADOS docs?)
1884 * @note Read operations only get a complete callback.
1885 * @note BUG: this should check for ENOMEM instead of throwing an exception
1887 * @param cb_arg application-defined data passed to the callback functions
1888 * @param cb_complete the function to be called when the operation is
1889 * in memory on all replicas
1890 * @param cb_safe the function to be called when the operation is on
1891 * stable storage on all replicas
1892 * @param pc where to store the completion
1895 CEPH_RADOS_API
int rados_aio_create_completion(void *cb_arg
,
1896 rados_callback_t cb_complete
,
1897 rados_callback_t cb_safe
,
1898 rados_completion_t
*pc
);
1901 * Constructs a completion to use with asynchronous operations
1903 * The complete callback corresponds to operation being acked.
1905 * @note BUG: this should check for ENOMEM instead of throwing an exception
1907 * @param cb_arg application-defined data passed to the callback functions
1908 * @param cb_complete the function to be called when the operation is committed
1910 * @param pc where to store the completion
1913 CEPH_RADOS_API
int rados_aio_create_completion2(void *cb_arg
,
1914 rados_callback_t cb_complete
,
1915 rados_completion_t
*pc
);
1918 * Block until an operation completes
1920 * This means it is in memory on all replicas.
1922 * @note BUG: this should be void
1924 * @param c operation to wait for
1927 CEPH_RADOS_API
int rados_aio_wait_for_complete(rados_completion_t c
);
1930 * Block until an operation is safe
1932 * This means it is on stable storage on all replicas.
1934 * @note BUG: this should be void
1936 * @param c operation to wait for
1939 CEPH_RADOS_API
int rados_aio_wait_for_safe(rados_completion_t c
)
1940 __attribute__((deprecated
));
1943 * Has an asynchronous operation completed?
1945 * @warning This does not imply that the complete callback has
1948 * @param c async operation to inspect
1949 * @returns whether c is complete
1951 CEPH_RADOS_API
int rados_aio_is_complete(rados_completion_t c
);
1954 * Is an asynchronous operation safe?
1956 * @warning This does not imply that the safe callback has
1959 * @param c async operation to inspect
1960 * @returns whether c is safe
1962 CEPH_RADOS_API
int rados_aio_is_safe(rados_completion_t c
);
1965 * Block until an operation completes and callback completes
1967 * This means it is in memory on all replicas and can be read.
1969 * @note BUG: this should be void
1971 * @param c operation to wait for
1974 CEPH_RADOS_API
int rados_aio_wait_for_complete_and_cb(rados_completion_t c
);
1977 * Block until an operation is safe and callback has completed
1979 * This means it is on stable storage on all replicas.
1981 * @note BUG: this should be void
1983 * @param c operation to wait for
1986 CEPH_RADOS_API
int rados_aio_wait_for_safe_and_cb(rados_completion_t c
)
1987 __attribute__((deprecated
));
1990 * Has an asynchronous operation and callback completed
1992 * @param c async operation to inspect
1993 * @returns whether c is complete
1995 CEPH_RADOS_API
int rados_aio_is_complete_and_cb(rados_completion_t c
);
1998 * Is an asynchronous operation safe and has the callback completed
2000 * @param c async operation to inspect
2001 * @returns whether c is safe
2003 CEPH_RADOS_API
int rados_aio_is_safe_and_cb(rados_completion_t c
);
2006 * Get the return value of an asychronous operation
2008 * The return value is set when the operation is complete or safe,
2009 * whichever comes first.
2011 * @pre The operation is safe or complete
2013 * @note BUG: complete callback may never be called when the safe
2014 * message is received before the complete message
2016 * @param c async operation to inspect
2017 * @returns return value of the operation
2019 CEPH_RADOS_API
int rados_aio_get_return_value(rados_completion_t c
);
2022 * Get the internal object version of the target of an asychronous operation
2024 * The return value is set when the operation is complete or safe,
2025 * whichever comes first.
2027 * @pre The operation is safe or complete
2029 * @note BUG: complete callback may never be called when the safe
2030 * message is received before the complete message
2032 * @param c async operation to inspect
2033 * @returns version number of the asychronous operation's target
2035 CEPH_RADOS_API
uint64_t rados_aio_get_version(rados_completion_t c
);
2038 * Release a completion
2040 * Call this when you no longer need the completion. It may not be
2041 * freed immediately if the operation is not acked and committed.
2043 * @param c completion to release
2045 CEPH_RADOS_API
void rados_aio_release(rados_completion_t c
);
2048 * Write data to an object asynchronously
2050 * Queues the write and returns. The return value of the completion
2051 * will be 0 on success, negative error code on failure.
2053 * @param io the context in which the write will occur
2054 * @param oid name of the object
2055 * @param completion what to do when the write is safe and complete
2056 * @param buf data to write
2057 * @param len length of the data, in bytes
2058 * @param off byte offset in the object to begin writing at
2059 * @returns 0 on success, -EROFS if the io context specifies a snap_seq
2060 * other than LIBRADOS_SNAP_HEAD
2062 CEPH_RADOS_API
int rados_aio_write(rados_ioctx_t io
, const char *oid
,
2063 rados_completion_t completion
,
2064 const char *buf
, size_t len
, uint64_t off
);
2067 * Asynchronously append data to an object
2069 * Queues the append and returns.
2071 * The return value of the completion will be 0 on success, negative
2072 * error code on failure.
2074 * @param io the context to operate in
2075 * @param oid the name of the object
2076 * @param completion what to do when the append is safe and complete
2077 * @param buf the data to append
2078 * @param len length of buf (in bytes)
2079 * @returns 0 on success, -EROFS if the io context specifies a snap_seq
2080 * other than LIBRADOS_SNAP_HEAD
2082 CEPH_RADOS_API
int rados_aio_append(rados_ioctx_t io
, const char *oid
,
2083 rados_completion_t completion
,
2084 const char *buf
, size_t len
);
2087 * Asynchronously write an entire object
2089 * The object is filled with the provided data. If the object exists,
2090 * it is atomically truncated and then written.
2091 * Queues the write_full and returns.
2093 * The return value of the completion will be 0 on success, negative
2094 * error code on failure.
2096 * @param io the io context in which the write will occur
2097 * @param oid name of the object
2098 * @param completion what to do when the write_full is safe and complete
2099 * @param buf data to write
2100 * @param len length of the data, in bytes
2101 * @returns 0 on success, -EROFS if the io context specifies a snap_seq
2102 * other than LIBRADOS_SNAP_HEAD
2104 CEPH_RADOS_API
int rados_aio_write_full(rados_ioctx_t io
, const char *oid
,
2105 rados_completion_t completion
,
2106 const char *buf
, size_t len
);
2109 * Asynchronously write the same buffer multiple times
2111 * Queues the writesame and returns.
2113 * The return value of the completion will be 0 on success, negative
2114 * error code on failure.
2116 * @param io the io context in which the write will occur
2117 * @param oid name of the object
2118 * @param completion what to do when the writesame is safe and complete
2119 * @param buf data to write
2120 * @param data_len length of the data, in bytes
2121 * @param write_len the total number of bytes to write
2122 * @param off byte offset in the object to begin writing at
2123 * @returns 0 on success, -EROFS if the io context specifies a snap_seq
2124 * other than LIBRADOS_SNAP_HEAD
2126 CEPH_RADOS_API
int rados_aio_writesame(rados_ioctx_t io
, const char *oid
,
2127 rados_completion_t completion
,
2128 const char *buf
, size_t data_len
,
2129 size_t write_len
, uint64_t off
);
2132 * Asynchronously remove an object
2134 * Queues the remove and returns.
2136 * The return value of the completion will be 0 on success, negative
2137 * error code on failure.
2139 * @param io the context to operate in
2140 * @param oid the name of the object
2141 * @param completion what to do when the remove is safe and complete
2142 * @returns 0 on success, -EROFS if the io context specifies a snap_seq
2143 * other than LIBRADOS_SNAP_HEAD
2145 CEPH_RADOS_API
int rados_aio_remove(rados_ioctx_t io
, const char *oid
,
2146 rados_completion_t completion
);
2149 * Asynchronously read data from an object
2151 * The io context determines the snapshot to read from, if any was set
2152 * by rados_ioctx_snap_set_read().
2154 * The return value of the completion will be number of bytes read on
2155 * success, negative error code on failure.
2157 * @note only the 'complete' callback of the completion will be called.
2159 * @param io the context in which to perform the read
2160 * @param oid the name of the object to read from
2161 * @param completion what to do when the read is complete
2162 * @param buf where to store the results
2163 * @param len the number of bytes to read
2164 * @param off the offset to start reading from in the object
2165 * @returns 0 on success, negative error code on failure
2167 CEPH_RADOS_API
int rados_aio_read(rados_ioctx_t io
, const char *oid
,
2168 rados_completion_t completion
,
2169 char *buf
, size_t len
, uint64_t off
);
2172 * Block until all pending writes in an io context are safe
2174 * This is not equivalent to calling rados_aio_wait_for_safe() on all
2175 * write completions, since this waits for the associated callbacks to
2178 * @note BUG: always returns 0, should be void or accept a timeout
2180 * @param io the context to flush
2181 * @returns 0 on success, negative error code on failure
2183 CEPH_RADOS_API
int rados_aio_flush(rados_ioctx_t io
);
2187 * Schedule a callback for when all currently pending
2188 * aio writes are safe. This is a non-blocking version of
2189 * rados_aio_flush().
2191 * @param io the context to flush
2192 * @param completion what to do when the writes are safe
2193 * @returns 0 on success, negative error code on failure
2195 CEPH_RADOS_API
int rados_aio_flush_async(rados_ioctx_t io
,
2196 rados_completion_t completion
);
2200 * Asynchronously get object stats (size/mtime)
2203 * @param o object name
2204 * @param completion what to do when the stat is complete
2205 * @param psize where to store object size
2206 * @param pmtime where to store modification time
2207 * @returns 0 on success, negative error code on failure
2209 CEPH_RADOS_API
int rados_aio_stat(rados_ioctx_t io
, const char *o
,
2210 rados_completion_t completion
,
2211 uint64_t *psize
, time_t *pmtime
);
2214 * Asynchronously compare an on-disk object range with a buffer
2216 * @param io the context in which to perform the comparison
2217 * @param o the name of the object to compare with
2218 * @param completion what to do when the comparison is complete
2219 * @param cmp_buf buffer containing bytes to be compared with object contents
2220 * @param cmp_len length to compare and size of @c cmp_buf in bytes
2221 * @param off object byte offset at which to start the comparison
2222 * @returns 0 on success, negative error code on failure,
2223 * (-MAX_ERRNO - mismatch_off) on mismatch
2225 CEPH_RADOS_API
int rados_aio_cmpext(rados_ioctx_t io
, const char *o
,
2226 rados_completion_t completion
,
2227 const char *cmp_buf
,
2232 * Cancel async operation
2235 * @param completion completion handle
2236 * @returns 0 on success, negative error code on failure
2238 CEPH_RADOS_API
int rados_aio_cancel(rados_ioctx_t io
,
2239 rados_completion_t completion
);
2242 * Asynchronously execute an OSD class method on an object
2244 * The OSD has a plugin mechanism for performing complicated
2245 * operations on an object atomically. These plugins are called
2246 * classes. This function allows librados users to call the custom
2247 * methods. The input and output formats are defined by the class.
2248 * Classes in ceph.git can be found in src/cls subdirectories
2250 * @param io the context in which to call the method
2251 * @param o name of the object
2252 * @param completion what to do when the exec completes
2253 * @param cls the name of the class
2254 * @param method the name of the method
2255 * @param in_buf where to find input
2256 * @param in_len length of in_buf in bytes
2257 * @param buf where to store output
2258 * @param out_len length of buf in bytes
2259 * @returns 0 on success, negative error code on failure
2261 CEPH_RADOS_API
int rados_aio_exec(rados_ioctx_t io
, const char *o
,
2262 rados_completion_t completion
,
2263 const char *cls
, const char *method
,
2264 const char *in_buf
, size_t in_len
,
2265 char *buf
, size_t out_len
);
2267 /** @} Asynchronous I/O */
2270 * @name Asynchronous Xattrs
2271 * Extended attributes are stored as extended attributes on the files
2272 * representing an object on the OSDs. Thus, they have the same
2273 * limitations as the underlying filesystem. On ext4, this means that
2274 * the total data stored in xattrs cannot exceed 4KB.
2280 * Asynchronously get the value of an extended attribute on an object.
2282 * @param io the context in which the attribute is read
2283 * @param o name of the object
2284 * @param completion what to do when the getxattr completes
2285 * @param name which extended attribute to read
2286 * @param buf where to store the result
2287 * @param len size of buf in bytes
2288 * @returns length of xattr value on success, negative error code on failure
2290 CEPH_RADOS_API
int rados_aio_getxattr(rados_ioctx_t io
, const char *o
,
2291 rados_completion_t completion
,
2292 const char *name
, char *buf
, size_t len
);
2295 * Asynchronously set an extended attribute on an object.
2297 * @param io the context in which xattr is set
2298 * @param o name of the object
2299 * @param completion what to do when the setxattr completes
2300 * @param name which extended attribute to set
2301 * @param buf what to store in the xattr
2302 * @param len the number of bytes in buf
2303 * @returns 0 on success, negative error code on failure
2305 CEPH_RADOS_API
int rados_aio_setxattr(rados_ioctx_t io
, const char *o
,
2306 rados_completion_t completion
,
2307 const char *name
, const char *buf
,
2311 * Asynchronously delete an extended attribute from an object.
2313 * @param io the context in which to delete the xattr
2314 * @param o the name of the object
2315 * @param completion what to do when the rmxattr completes
2316 * @param name which xattr to delete
2317 * @returns 0 on success, negative error code on failure
2319 CEPH_RADOS_API
int rados_aio_rmxattr(rados_ioctx_t io
, const char *o
,
2320 rados_completion_t completion
,
2324 * Asynchronously start iterating over xattrs on an object.
2326 * @post iter is a valid iterator
2328 * @param io the context in which to list xattrs
2329 * @param oid name of the object
2330 * @param completion what to do when the getxattrs completes
2331 * @param iter where to store the iterator
2332 * @returns 0 on success, negative error code on failure
2334 CEPH_RADOS_API
int rados_aio_getxattrs(rados_ioctx_t io
, const char *oid
,
2335 rados_completion_t completion
,
2336 rados_xattrs_iter_t
*iter
);
2338 /** @} Asynchronous Xattrs */
2341 * @name Watch/Notify
2343 * Watch/notify is a protocol to help communicate among clients. It
2344 * can be used to sychronize client state. All that's needed is a
2345 * well-known object name (for example, rbd uses the header object of
2348 * Watchers register an interest in an object, and receive all
2349 * notifies on that object. A notify attempts to communicate with all
2350 * clients watching an object, and blocks on the notifier until each
2351 * client responds or a timeout is reached.
2353 * See rados_watch() and rados_notify() for more details.
2359 * @typedef rados_watchcb_t
2361 * Callback activated when a notify is received on a watched
2364 * @param opcode undefined
2365 * @param ver version of the watched object
2366 * @param arg application-specific data
2368 * @note BUG: opcode is an internal detail that shouldn't be exposed
2369 * @note BUG: ver is unused
2371 typedef void (*rados_watchcb_t
)(uint8_t opcode
, uint64_t ver
, void *arg
);
2374 * @typedef rados_watchcb2_t
2376 * Callback activated when a notify is received on a watched
2379 * @param arg opaque user-defined value provided to rados_watch2()
2380 * @param notify_id an id for this notify event
2381 * @param handle the watcher handle we are notifying
2382 * @param notifier_id the unique client id for the notifier
2383 * @param data payload from the notifier
2384 * @param data_len length of payload buffer
2386 typedef void (*rados_watchcb2_t
)(void *arg
,
2389 uint64_t notifier_id
,
2394 * @typedef rados_watcherrcb_t
2396 * Callback activated when we encounter an error with the watch session.
2397 * This can happen when the location of the objects moves within the
2398 * cluster and we fail to register our watch with the new object location,
2399 * or when our connection with the object OSD is otherwise interrupted and
2400 * we may have missed notify events.
2402 * @param pre opaque user-defined value provided to rados_watch2()
2403 * @param cookie the internal id assigned to the watch session
2404 * @param err error code
2406 typedef void (*rados_watcherrcb_t
)(void *pre
, uint64_t cookie
, int err
);
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
2415 * the primary OSD for a watched object, the watch will be removed
2416 * after 30 seconds. Watches are automatically reestablished when a new
2417 * connection is made, or a placement group switches OSDs.
2419 * @note BUG: librados should provide a way for watchers to notice connection resets
2420 * @note BUG: the ver parameter does not work, and -ERANGE will never be returned
2421 * (See URL tracker.ceph.com/issues/2592)
2423 * @param io the pool the object is in
2424 * @param o the object to watch
2425 * @param ver expected version of the object
2426 * @param cookie where to store the internal id assigned to this watch
2427 * @param watchcb what to do when a notify is received on this object
2428 * @param arg application defined data to pass when watchcb is called
2429 * @returns 0 on success, negative error code on failure
2430 * @returns -ERANGE if the version of the object is greater than ver
2432 CEPH_RADOS_API
int rados_watch(rados_ioctx_t io
, const char *o
, uint64_t ver
,
2434 rados_watchcb_t watchcb
, void *arg
)
2435 __attribute__((deprecated
));
2439 * Register an interest in an object
2441 * A watch operation registers the client as being interested in
2442 * notifications on an object. OSDs keep track of watches on
2443 * persistent storage, so they are preserved across cluster changes by
2444 * the normal recovery process. If the client loses its connection to the
2445 * primary OSD for a watched object, the watch will be removed after
2446 * a timeout configured with osd_client_watch_timeout.
2447 * Watches are automatically reestablished when a new
2448 * connection is made, or a placement group switches OSDs.
2450 * @param io the pool the object is in
2451 * @param o the object to watch
2452 * @param cookie where to store the internal id assigned to this watch
2453 * @param watchcb what to do when a notify is received on this object
2454 * @param watcherrcb what to do when the watch session encounters an error
2455 * @param arg opaque value to pass to the callback
2456 * @returns 0 on success, negative error code on failure
2458 CEPH_RADOS_API
int rados_watch2(rados_ioctx_t io
, const char *o
, uint64_t *cookie
,
2459 rados_watchcb2_t watchcb
,
2460 rados_watcherrcb_t watcherrcb
,
2464 * Register an interest in an object
2466 * A watch operation registers the client as being interested in
2467 * notifications on an object. OSDs keep track of watches on
2468 * persistent storage, so they are preserved across cluster changes by
2469 * the normal recovery process. Watches are automatically reestablished when a new
2470 * connection is made, or a placement group switches OSDs.
2472 * @param io the pool the object is in
2473 * @param o the object to watch
2474 * @param cookie where to store the internal id assigned to this watch
2475 * @param watchcb what to do when a notify is received on this object
2476 * @param watcherrcb what to do when the watch session encounters an error
2477 * @param timeout how many seconds the connection will keep after disconnection
2478 * @param arg opaque value to pass to the callback
2479 * @returns 0 on success, negative error code on failure
2481 CEPH_RADOS_API
int rados_watch3(rados_ioctx_t io
, const char *o
, uint64_t *cookie
,
2482 rados_watchcb2_t watchcb
,
2483 rados_watcherrcb_t watcherrcb
,
2488 * Asynchronous register an interest in an object
2490 * A watch operation registers the client as being interested in
2491 * notifications on an object. OSDs keep track of watches on
2492 * persistent storage, so they are preserved across cluster changes by
2493 * the normal recovery process. If the client loses its connection to
2494 * the primary OSD for a watched object, the watch will be removed
2495 * after 30 seconds. Watches are automatically reestablished when a new
2496 * connection is made, or a placement group switches OSDs.
2498 * @param io the pool the object is in
2499 * @param o the object to watch
2500 * @param completion what to do when operation has been attempted
2501 * @param handle where to store the internal id assigned to this watch
2502 * @param watchcb what to do when a notify is received on this object
2503 * @param watcherrcb what to do when the watch session encounters an error
2504 * @param arg opaque value to pass to the callback
2505 * @returns 0 on success, negative error code on failure
2507 CEPH_RADOS_API
int rados_aio_watch(rados_ioctx_t io
, const char *o
,
2508 rados_completion_t completion
, uint64_t *handle
,
2509 rados_watchcb2_t watchcb
,
2510 rados_watcherrcb_t watcherrcb
,
2514 * Asynchronous register an interest in an object
2516 * A watch operation registers the client as being interested in
2517 * notifications on an object. OSDs keep track of watches on
2518 * persistent storage, so they are preserved across cluster changes by
2519 * the normal recovery process. If the client loses its connection to
2520 * the primary OSD for a watched object, the watch will be removed
2521 * after the number of seconds that configured in timeout parameter.
2522 * Watches are automatically reestablished when a new
2523 * connection is made, or a placement group switches OSDs.
2525 * @param io the pool the object is in
2526 * @param o the object to watch
2527 * @param completion what to do when operation has been attempted
2528 * @param handle where to store the internal id assigned to this watch
2529 * @param watchcb what to do when a notify is received on this object
2530 * @param watcherrcb what to do when the watch session encounters an error
2531 * @param timeout how many seconds the connection will keep after disconnection
2532 * @param arg opaque value to pass to the callback
2533 * @returns 0 on success, negative error code on failure
2535 CEPH_RADOS_API
int rados_aio_watch2(rados_ioctx_t io
, const char *o
,
2536 rados_completion_t completion
, uint64_t *handle
,
2537 rados_watchcb2_t watchcb
,
2538 rados_watcherrcb_t watcherrcb
,
2543 * Check on the status of a watch
2545 * Return the number of milliseconds since the watch was last confirmed.
2546 * Or, if there has been an error, return that.
2548 * If there is an error, the watch is no longer valid, and should be
2549 * destroyed with rados_unwatch2(). The the user is still interested
2550 * in the object, a new watch should be created with rados_watch2().
2552 * @param io the pool the object is in
2553 * @param cookie the watch handle
2554 * @returns ms since last confirmed on success, negative error code on failure
2556 CEPH_RADOS_API
int rados_watch_check(rados_ioctx_t io
, uint64_t cookie
);
2559 * Unregister an interest in an object
2561 * Once this completes, no more notifies will be sent to us for this
2562 * watch. This should be called to clean up unneeded watchers.
2564 * @param io the pool the object is in
2565 * @param o the name of the watched object (ignored)
2566 * @param cookie which watch to unregister
2567 * @returns 0 on success, negative error code on failure
2569 CEPH_RADOS_API
int rados_unwatch(rados_ioctx_t io
, const char *o
, uint64_t cookie
)
2570 __attribute__((deprecated
));
2573 * Unregister an interest in an object
2575 * Once this completes, no more notifies will be sent to us for this
2576 * watch. This should be called to clean up unneeded watchers.
2578 * @param io the pool the object is in
2579 * @param cookie which watch to unregister
2580 * @returns 0 on success, negative error code on failure
2582 CEPH_RADOS_API
int rados_unwatch2(rados_ioctx_t io
, uint64_t cookie
);
2585 * Asynchronous unregister an interest in an object
2587 * Once this completes, no more notifies will be sent to us for this
2588 * watch. This should be called to clean up unneeded watchers.
2590 * @param io the pool the object is in
2591 * @param completion what to do when operation has been attempted
2592 * @param cookie which watch to unregister
2593 * @returns 0 on success, negative error code on failure
2595 CEPH_RADOS_API
int rados_aio_unwatch(rados_ioctx_t io
, uint64_t cookie
,
2596 rados_completion_t completion
);
2599 * Sychronously notify watchers of an object
2601 * This blocks until all watchers of the object have received and
2602 * reacted to the notify, or a timeout is reached.
2604 * @note BUG: the timeout is not changeable via the C API
2605 * @note BUG: the bufferlist is inaccessible in a rados_watchcb_t
2607 * @param io the pool the object is in
2608 * @param o the name of the object
2609 * @param ver obsolete - just pass zero
2610 * @param buf data to send to watchers
2611 * @param buf_len length of buf in bytes
2612 * @returns 0 on success, negative error code on failure
2614 CEPH_RADOS_API
int rados_notify(rados_ioctx_t io
, const char *o
, uint64_t ver
,
2615 const char *buf
, int buf_len
)
2616 __attribute__((deprecated
));
2619 * Sychronously notify watchers of an object
2621 * This blocks until all watchers of the object have received and
2622 * reacted to the notify, or a timeout is reached.
2624 * The reply buffer is optional. If specified, the client will get
2625 * back an encoded buffer that includes the ids of the clients that
2626 * acknowledged the notify as well as their notify ack payloads (if
2627 * any). Clients that timed out are not included. Even clients that
2628 * do not include a notify ack payload are included in the list but
2629 * have a 0-length payload associated with them. The format:
2633 * le64 gid global id for the client (for client.1234 that's 1234)
2634 * le64 cookie cookie for the client
2635 * le32 buflen length of reply message buffer
2636 * u8 * buflen payload
2640 * le64 gid global id for the client
2641 * le64 cookie cookie for the client
2644 * Note: There may be multiple instances of the same gid if there are
2645 * multiple watchers registered via the same client.
2647 * Note: The buffer must be released with rados_buffer_free() when the
2648 * user is done with it.
2650 * Note: Since the result buffer includes clients that time out, it
2651 * will be set even when rados_notify() returns an error code (like
2654 * @param io the pool the object is in
2655 * @param completion what to do when operation has been attempted
2656 * @param o the name of the object
2657 * @param buf data to send to watchers
2658 * @param buf_len length of buf in bytes
2659 * @param timeout_ms notify timeout (in ms)
2660 * @param reply_buffer pointer to reply buffer pointer (free with rados_buffer_free)
2661 * @param reply_buffer_len pointer to size of reply buffer
2662 * @returns 0 on success, negative error code on failure
2664 CEPH_RADOS_API
int rados_aio_notify(rados_ioctx_t io
, const char *o
,
2665 rados_completion_t completion
,
2666 const char *buf
, int buf_len
,
2667 uint64_t timeout_ms
, char **reply_buffer
,
2668 size_t *reply_buffer_len
);
2669 CEPH_RADOS_API
int rados_notify2(rados_ioctx_t io
, const char *o
,
2670 const char *buf
, int buf_len
,
2671 uint64_t timeout_ms
,
2672 char **reply_buffer
, size_t *reply_buffer_len
);
2675 * Decode a notify response
2677 * Decode a notify response (from rados_aio_notify() call) into acks and
2680 * @param reply_buffer buffer from rados_aio_notify() call
2681 * @param reply_buffer_len reply_buffer length
2682 * @param acks pointer to struct notify_ack_t pointer
2683 * @param nr_acks pointer to ack count
2684 * @param timeouts pointer to notify_timeout_t pointer
2685 * @param nr_timeouts pointer to timeout count
2686 * @returns 0 on success
2688 CEPH_RADOS_API
int rados_decode_notify_response(char *reply_buffer
, size_t reply_buffer_len
,
2689 struct notify_ack_t
**acks
, size_t *nr_acks
,
2690 struct notify_timeout_t
**timeouts
, size_t *nr_timeouts
);
2693 * Free notify allocated buffer
2695 * Release memory allocated by rados_decode_notify_response() call
2697 * @param acks notify_ack_t struct (from rados_decode_notify_response())
2698 * @param nr_acks ack count
2699 * @param timeouts notify_timeout_t struct (from rados_decode_notify_response())
2701 CEPH_RADOS_API
void rados_free_notify_response(struct notify_ack_t
*acks
, size_t nr_acks
,
2702 struct notify_timeout_t
*timeouts
);
2705 * Acknolwedge receipt of a notify
2707 * @param io the pool the object is in
2708 * @param o the name of the object
2709 * @param notify_id the notify_id we got on the watchcb2_t callback
2710 * @param cookie the watcher handle
2711 * @param buf payload to return to notifier (optional)
2712 * @param buf_len payload length
2713 * @returns 0 on success
2715 CEPH_RADOS_API
int rados_notify_ack(rados_ioctx_t io
, const char *o
,
2716 uint64_t notify_id
, uint64_t cookie
,
2717 const char *buf
, int buf_len
);
2720 * Flush watch/notify callbacks
2722 * This call will block until all pending watch/notify callbacks have
2723 * been executed and the queue is empty. It should usually be called
2724 * after shutting down any watches before shutting down the ioctx or
2725 * librados to ensure that any callbacks do not misuse the ioctx (for
2726 * example by calling rados_notify_ack after the ioctx has been
2729 * @param cluster the cluster handle
2731 CEPH_RADOS_API
int rados_watch_flush(rados_t cluster
);
2733 * Flush watch/notify callbacks
2735 * This call will be nonblock, and the completion will be called
2736 * until all pending watch/notify callbacks have been executed and
2737 * the queue is empty. It should usually be called after shutting
2738 * down any watches before shutting down the ioctx or
2739 * librados to ensure that any callbacks do not misuse the ioctx (for
2740 * example by calling rados_notify_ack after the ioctx has been
2743 * @param cluster the cluster handle
2744 * @param completion what to do when operation has been attempted
2746 CEPH_RADOS_API
int rados_aio_watch_flush(rados_t cluster
, rados_completion_t completion
);
2748 /** @} Watch/Notify */
2751 * Pin an object in the cache tier
2753 * When an object is pinned in the cache tier, it stays in the cache
2754 * tier, and won't be flushed out.
2756 * @param io the pool the object is in
2757 * @param o the object id
2758 * @returns 0 on success, negative error code on failure
2760 CEPH_RADOS_API
int rados_cache_pin(rados_ioctx_t io
, const char *o
);
2763 * Unpin an object in the cache tier
2765 * After an object is unpinned in the cache tier, it can be flushed out
2767 * @param io the pool the object is in
2768 * @param o the object id
2769 * @returns 0 on success, negative error code on failure
2771 CEPH_RADOS_API
int rados_cache_unpin(rados_ioctx_t io
, const char *o
);
2780 * Set allocation hint for an object
2782 * This is an advisory operation, it will always succeed (as if it was
2783 * submitted with a LIBRADOS_OP_FLAG_FAILOK flag set) and is not
2784 * guaranteed to do anything on the backend.
2786 * @param io the pool the object is in
2787 * @param o the name of the object
2788 * @param expected_object_size expected size of the object, in bytes
2789 * @param expected_write_size expected size of writes to the object, in bytes
2790 * @returns 0 on success, negative error code on failure
2792 CEPH_RADOS_API
int rados_set_alloc_hint(rados_ioctx_t io
, const char *o
,
2793 uint64_t expected_object_size
,
2794 uint64_t expected_write_size
);
2797 * Set allocation hint for an object
2799 * This is an advisory operation, it will always succeed (as if it was
2800 * submitted with a LIBRADOS_OP_FLAG_FAILOK flag set) and is not
2801 * guaranteed to do anything on the backend.
2803 * @param io the pool the object is in
2804 * @param o the name of the object
2805 * @param expected_object_size expected size of the object, in bytes
2806 * @param expected_write_size expected size of writes to the object, in bytes
2807 * @param flags hints about future IO patterns
2808 * @returns 0 on success, negative error code on failure
2810 CEPH_RADOS_API
int rados_set_alloc_hint2(rados_ioctx_t io
, const char *o
,
2811 uint64_t expected_object_size
,
2812 uint64_t expected_write_size
,
2818 * @name Object Operations
2820 * A single rados operation can do multiple operations on one object
2821 * atomically. The whole operation will succeed or fail, and no partial
2822 * results will be visible.
2824 * Operations may be either reads, which can return data, or writes,
2825 * which cannot. The effects of writes are applied and visible all at
2826 * once, so an operation that sets an xattr and then checks its value
2827 * will not see the updated value.
2833 * Create a new rados_write_op_t write operation. This will store all actions
2834 * to be performed atomically. You must call rados_release_write_op when you are
2837 * @note the ownership of a write operartion is passed to the function
2838 * performing the operation, so the same instance of @c rados_write_op_t
2839 * cannot be used again after being performed.
2841 * @returns non-NULL on success, NULL on memory allocation error.
2843 CEPH_RADOS_API rados_write_op_t
rados_create_write_op(void);
2846 * Free a rados_write_op_t, must be called when you're done with it.
2847 * @param write_op operation to deallocate, created with rados_create_write_op
2849 CEPH_RADOS_API
void rados_release_write_op(rados_write_op_t write_op
);
2852 * Set flags for the last operation added to this write_op.
2853 * At least one op must have been added to the write_op.
2854 * @param write_op operation to add this action to
2855 * @param flags see librados.h constants beginning with LIBRADOS_OP_FLAG
2857 CEPH_RADOS_API
void rados_write_op_set_flags(rados_write_op_t write_op
,
2861 * Ensure that the object exists before writing
2862 * @param write_op operation to add this action to
2864 CEPH_RADOS_API
void rados_write_op_assert_exists(rados_write_op_t write_op
);
2867 * Ensure that the object exists and that its internal version
2868 * number is equal to "ver" before writing. "ver" should be a
2869 * version number previously obtained with rados_get_last_version().
2870 * - If the object's version is greater than the asserted version
2871 * then rados_write_op_operate will return -ERANGE instead of
2873 * - If the object's version is less than the asserted version
2874 * then rados_write_op_operate will return -EOVERFLOW instead
2875 * of executing the op.
2876 * @param write_op operation to add this action to
2877 * @param ver object version number
2879 CEPH_RADOS_API
void rados_write_op_assert_version(rados_write_op_t write_op
, uint64_t ver
);
2882 * Ensure that given object range (extent) satisfies comparison.
2884 * @param write_op operation to add this action to
2885 * @param cmp_buf buffer containing bytes to be compared with object contents
2886 * @param cmp_len length to compare and size of @c cmp_buf in bytes
2887 * @param off object byte offset at which to start the comparison
2888 * @param prval returned result of comparison, 0 on success, negative error code
2889 * on failure, (-MAX_ERRNO - mismatch_off) on mismatch
2891 CEPH_RADOS_API
void rados_write_op_cmpext(rados_write_op_t write_op
,
2892 const char *cmp_buf
,
2898 * Ensure that given xattr satisfies comparison.
2899 * If the comparison is not satisfied, the return code of the
2900 * operation will be -ECANCELED
2901 * @param write_op operation to add this action to
2902 * @param name name of the xattr to look up
2903 * @param comparison_operator currently undocumented, look for
2904 * LIBRADOS_CMPXATTR_OP_EQ in librados.h
2905 * @param value buffer to compare actual xattr value to
2906 * @param value_len length of buffer to compare actual xattr value to
2908 CEPH_RADOS_API
void rados_write_op_cmpxattr(rados_write_op_t write_op
,
2910 uint8_t comparison_operator
,
2915 * Ensure that the an omap value satisfies a comparison,
2916 * with the supplied value on the right hand side (i.e.
2917 * for OP_LT, the comparison is actual_value < value.
2919 * @param write_op operation to add this action to
2920 * @param key which omap value to compare
2921 * @param comparison_operator one of LIBRADOS_CMPXATTR_OP_EQ,
2922 LIBRADOS_CMPXATTR_OP_LT, or LIBRADOS_CMPXATTR_OP_GT
2923 * @param val value to compare with
2924 * @param val_len length of value in bytes
2925 * @param prval where to store the return value from this action
2927 CEPH_RADOS_API
void rados_write_op_omap_cmp(rados_write_op_t write_op
,
2929 uint8_t comparison_operator
,
2935 * Ensure that the an omap value satisfies a comparison,
2936 * with the supplied value on the right hand side (i.e.
2937 * for OP_LT, the comparison is actual_value < value.
2939 * @param write_op operation to add this action to
2940 * @param key which omap value to compare
2941 * @param comparison_operator one of LIBRADOS_CMPXATTR_OP_EQ,
2942 LIBRADOS_CMPXATTR_OP_LT, or LIBRADOS_CMPXATTR_OP_GT
2943 * @param val value to compare with
2944 * @param key_len length of key in bytes
2945 * @param val_len length of value in bytes
2946 * @param prval where to store the return value from this action
2948 CEPH_RADOS_API
void rados_write_op_omap_cmp2(rados_write_op_t write_op
,
2950 uint8_t comparison_operator
,
2958 * @param write_op operation to add this action to
2959 * @param name name of the xattr
2960 * @param value buffer to set xattr to
2961 * @param value_len length of buffer to set xattr to
2963 CEPH_RADOS_API
void rados_write_op_setxattr(rados_write_op_t write_op
,
2970 * @param write_op operation to add this action to
2971 * @param name name of the xattr to remove
2973 CEPH_RADOS_API
void rados_write_op_rmxattr(rados_write_op_t write_op
,
2978 * @param write_op operation to add this action to
2979 * @param exclusive set to either LIBRADOS_CREATE_EXCLUSIVE or
2980 LIBRADOS_CREATE_IDEMPOTENT
2981 * will error if the object already exists.
2982 * @param category category string (DEPRECATED, HAS NO EFFECT)
2984 CEPH_RADOS_API
void rados_write_op_create(rados_write_op_t write_op
,
2986 const char* category
);
2990 * @param write_op operation to add this action to
2991 * @param offset offset to write to
2992 * @param buffer bytes to write
2993 * @param len length of buffer
2995 CEPH_RADOS_API
void rados_write_op_write(rados_write_op_t write_op
,
3001 * Write whole object, atomically replacing it.
3002 * @param write_op operation to add this action to
3003 * @param buffer bytes to write
3004 * @param len length of buffer
3006 CEPH_RADOS_API
void rados_write_op_write_full(rados_write_op_t write_op
,
3011 * Write the same buffer multiple times
3012 * @param write_op operation to add this action to
3013 * @param buffer bytes to write
3014 * @param data_len length of buffer
3015 * @param write_len total number of bytes to write, as a multiple of @c data_len
3016 * @param offset offset to write to
3018 CEPH_RADOS_API
void rados_write_op_writesame(rados_write_op_t write_op
,
3025 * Append to end of object.
3026 * @param write_op operation to add this action to
3027 * @param buffer bytes to write
3028 * @param len length of buffer
3030 CEPH_RADOS_API
void rados_write_op_append(rados_write_op_t write_op
,
3035 * @param write_op operation to add this action to
3037 CEPH_RADOS_API
void rados_write_op_remove(rados_write_op_t write_op
);
3040 * Truncate an object
3041 * @param write_op operation to add this action to
3042 * @param offset Offset to truncate to
3044 CEPH_RADOS_API
void rados_write_op_truncate(rados_write_op_t write_op
,
3048 * Zero part of an object
3049 * @param write_op operation to add this action to
3050 * @param offset Offset to zero
3051 * @param len length to zero
3053 CEPH_RADOS_API
void rados_write_op_zero(rados_write_op_t write_op
,
3058 * Execute an OSD class method on an object
3059 * See rados_exec() for general description.
3061 * @param write_op operation to add this action to
3062 * @param cls the name of the class
3063 * @param method the name of the method
3064 * @param in_buf where to find input
3065 * @param in_len length of in_buf in bytes
3066 * @param prval where to store the return value from the method
3068 CEPH_RADOS_API
void rados_write_op_exec(rados_write_op_t write_op
,
3076 * Set key/value pairs on an object
3078 * @param write_op operation to add this action to
3079 * @param keys array of null-terminated char arrays representing keys to set
3080 * @param vals array of pointers to values to set
3081 * @param lens array of lengths corresponding to each value
3082 * @param num number of key/value pairs to set
3084 CEPH_RADOS_API
void rados_write_op_omap_set(rados_write_op_t write_op
,
3085 char const* const* keys
,
3086 char const* const* vals
,
3091 * Set key/value pairs on an object
3093 * @param write_op operation to add this action to
3094 * @param keys array of null-terminated char arrays representing keys to set
3095 * @param vals array of pointers to values to set
3096 * @param key_lens array of lengths corresponding to each key
3097 * @param val_lens array of lengths corresponding to each value
3098 * @param num number of key/value pairs to set
3100 CEPH_RADOS_API
void rados_write_op_omap_set2(rados_write_op_t write_op
,
3101 char const* const* keys
,
3102 char const* const* vals
,
3103 const size_t *key_lens
,
3104 const size_t *val_lens
,
3108 * Remove key/value pairs from an object
3110 * @param write_op operation to add this action to
3111 * @param keys array of null-terminated char arrays representing keys to remove
3112 * @param keys_len number of key/value pairs to remove
3114 CEPH_RADOS_API
void rados_write_op_omap_rm_keys(rados_write_op_t write_op
,
3115 char const* const* keys
,
3119 * Remove key/value pairs from an object
3121 * @param write_op operation to add this action to
3122 * @param keys array of char arrays representing keys to remove
3123 * @param key_lens array of size_t values representing length of each key
3124 * @param keys_len number of key/value pairs to remove
3126 CEPH_RADOS_API
void rados_write_op_omap_rm_keys2(rados_write_op_t write_op
,
3127 char const* const* keys
,
3128 const size_t* key_lens
,
3133 * Remove key/value pairs from an object whose keys are in the range
3134 * [key_begin, key_end)
3136 * @param write_op operation to add this action to
3137 * @param key_begin the lower bound of the key range to remove
3138 * @param key_begin_len length of key_begin
3139 * @param key_end the upper bound of the key range to remove
3140 * @param key_end_len length of key_end
3142 CEPH_RADOS_API
void rados_write_op_omap_rm_range2(rados_write_op_t write_op
,
3143 const char *key_begin
,
3144 size_t key_begin_len
,
3145 const char *key_end
,
3146 size_t key_end_len
);
3149 * Remove all key/value pairs from an object
3151 * @param write_op operation to add this action to
3153 CEPH_RADOS_API
void rados_write_op_omap_clear(rados_write_op_t write_op
);
3156 * Set allocation hint for an object
3158 * @param write_op operation to add this action to
3159 * @param expected_object_size expected size of the object, in bytes
3160 * @param expected_write_size expected size of writes to the object, in bytes
3162 CEPH_RADOS_API
void rados_write_op_set_alloc_hint(rados_write_op_t write_op
,
3163 uint64_t expected_object_size
,
3164 uint64_t expected_write_size
);
3167 * Set allocation hint for an object
3169 * @param write_op operation to add this action to
3170 * @param expected_object_size expected size of the object, in bytes
3171 * @param expected_write_size expected size of writes to the object, in bytes
3172 * @param flags hints about future IO patterns
3174 CEPH_RADOS_API
void rados_write_op_set_alloc_hint2(rados_write_op_t write_op
,
3175 uint64_t expected_object_size
,
3176 uint64_t expected_write_size
,
3180 * Perform a write operation synchronously
3181 * @param write_op operation to perform
3182 * @param io the ioctx that the object is in
3183 * @param oid the object id
3184 * @param mtime the time to set the mtime to, NULL for the current time
3185 * @param flags flags to apply to the entire operation (LIBRADOS_OPERATION_*)
3187 CEPH_RADOS_API
int rados_write_op_operate(rados_write_op_t write_op
,
3193 * Perform a write operation synchronously
3194 * @param write_op operation to perform
3195 * @param io the ioctx that the object is in
3196 * @param oid the object id
3197 * @param mtime the time to set the mtime to, NULL for the current time
3198 * @param flags flags to apply to the entire operation (LIBRADOS_OPERATION_*)
3201 CEPH_RADOS_API
int rados_write_op_operate2(rados_write_op_t write_op
,
3204 struct timespec
*mtime
,
3208 * Perform a write operation asynchronously
3209 * @param write_op operation to perform
3210 * @param io the ioctx that the object is in
3211 * @param completion what to do when operation has been attempted
3212 * @param oid the object id
3213 * @param mtime the time to set the mtime to, NULL for the current time
3214 * @param flags flags to apply to the entire operation (LIBRADOS_OPERATION_*)
3216 CEPH_RADOS_API
int rados_aio_write_op_operate(rados_write_op_t write_op
,
3218 rados_completion_t completion
,
3224 * Create a new rados_read_op_t read operation. This will store all
3225 * actions to be performed atomically. You must call
3226 * rados_release_read_op when you are finished with it (after it
3227 * completes, or you decide not to send it in the first place).
3229 * @note the ownership of a read operartion is passed to the function
3230 * performing the operation, so the same instance of @c rados_read_op_t
3231 * cannot be used again after being performed.
3233 * @returns non-NULL on success, NULL on memory allocation error.
3235 CEPH_RADOS_API rados_read_op_t
rados_create_read_op(void);
3238 * Free a rados_read_op_t, must be called when you're done with it.
3239 * @param read_op operation to deallocate, created with rados_create_read_op
3241 CEPH_RADOS_API
void rados_release_read_op(rados_read_op_t read_op
);
3244 * Set flags for the last operation added to this read_op.
3245 * At least one op must have been added to the read_op.
3246 * @param read_op operation to add this action to
3247 * @param flags see librados.h constants beginning with LIBRADOS_OP_FLAG
3249 CEPH_RADOS_API
void rados_read_op_set_flags(rados_read_op_t read_op
, int flags
);
3252 * Ensure that the object exists before reading
3253 * @param read_op operation to add this action to
3255 CEPH_RADOS_API
void rados_read_op_assert_exists(rados_read_op_t read_op
);
3258 * Ensure that the object exists and that its internal version
3259 * number is equal to "ver" before reading. "ver" should be a
3260 * version number previously obtained with rados_get_last_version().
3261 * - If the object's version is greater than the asserted version
3262 * then rados_read_op_operate will return -ERANGE instead of
3264 * - If the object's version is less than the asserted version
3265 * then rados_read_op_operate will return -EOVERFLOW instead
3266 * of executing the op.
3267 * @param read_op operation to add this action to
3268 * @param ver object version number
3270 CEPH_RADOS_API
void rados_read_op_assert_version(rados_read_op_t read_op
, uint64_t ver
);
3273 * Ensure that given object range (extent) satisfies comparison.
3275 * @param read_op operation to add this action to
3276 * @param cmp_buf buffer containing bytes to be compared with object contents
3277 * @param cmp_len length to compare and size of @c cmp_buf in bytes
3278 * @param off object byte offset at which to start the comparison
3279 * @param prval returned result of comparison, 0 on success, negative error code
3280 * on failure, (-MAX_ERRNO - mismatch_off) on mismatch
3282 CEPH_RADOS_API
void rados_read_op_cmpext(rados_read_op_t read_op
,
3283 const char *cmp_buf
,
3289 * Ensure that the an xattr satisfies a comparison
3290 * If the comparison is not satisfied, the return code of the
3291 * operation will be -ECANCELED
3292 * @param read_op operation to add this action to
3293 * @param name name of the xattr to look up
3294 * @param comparison_operator currently undocumented, look for
3295 * LIBRADOS_CMPXATTR_OP_EQ in librados.h
3296 * @param value buffer to compare actual xattr value to
3297 * @param value_len length of buffer to compare actual xattr value to
3299 CEPH_RADOS_API
void rados_read_op_cmpxattr(rados_read_op_t read_op
,
3301 uint8_t comparison_operator
,
3306 * Start iterating over xattrs on an object.
3308 * @param read_op operation to add this action to
3309 * @param iter where to store the iterator
3310 * @param prval where to store the return value of this action
3312 CEPH_RADOS_API
void rados_read_op_getxattrs(rados_read_op_t read_op
,
3313 rados_xattrs_iter_t
*iter
,
3317 * Ensure that the an omap value satisfies a comparison,
3318 * with the supplied value on the right hand side (i.e.
3319 * for OP_LT, the comparison is actual_value < value.
3321 * @param read_op operation to add this action to
3322 * @param key which omap value to compare
3323 * @param comparison_operator one of LIBRADOS_CMPXATTR_OP_EQ,
3324 LIBRADOS_CMPXATTR_OP_LT, or LIBRADOS_CMPXATTR_OP_GT
3325 * @param val value to compare with
3326 * @param val_len length of value in bytes
3327 * @param prval where to store the return value from this action
3329 CEPH_RADOS_API
void rados_read_op_omap_cmp(rados_read_op_t read_op
,
3331 uint8_t comparison_operator
,
3337 * Ensure that the an omap value satisfies a comparison,
3338 * with the supplied value on the right hand side (i.e.
3339 * for OP_LT, the comparison is actual_value < value.
3341 * @param read_op operation to add this action to
3342 * @param key which omap value to compare
3343 * @param comparison_operator one of LIBRADOS_CMPXATTR_OP_EQ,
3344 LIBRADOS_CMPXATTR_OP_LT, or LIBRADOS_CMPXATTR_OP_GT
3345 * @param val value to compare with
3346 * @param key_len length of key in bytes
3347 * @param val_len length of value in bytes
3348 * @param prval where to store the return value from this action
3350 CEPH_RADOS_API
void rados_read_op_omap_cmp2(rados_read_op_t read_op
,
3352 uint8_t comparison_operator
,
3359 * Get object size and mtime
3360 * @param read_op operation to add this action to
3361 * @param psize where to store object size
3362 * @param pmtime where to store modification time
3363 * @param prval where to store the return value of this action
3365 CEPH_RADOS_API
void rados_read_op_stat(rados_read_op_t read_op
,
3371 * Read bytes from offset into buffer.
3373 * prlen will be filled with the number of bytes read if successful.
3374 * A short read can only occur if the read reaches the end of the
3377 * @param read_op operation to add this action to
3378 * @param offset offset to read from
3379 * @param len length of buffer
3380 * @param buffer where to put the data
3381 * @param bytes_read where to store the number of bytes read by this action
3382 * @param prval where to store the return value of this action
3384 CEPH_RADOS_API
void rados_read_op_read(rados_read_op_t read_op
,
3392 * Compute checksum from object data
3394 * @param read_op operation to add this action to
3395 * @param type the checksum algorithm to utilize
3396 * @param init_value the init value for the algorithm
3397 * @param init_value_len the length of the init value
3398 * @param offset the offset to start checksumming in the object
3399 * @param len the number of bytes to checksum
3400 * @param chunk_size optional length-aligned chunk size for checksums
3401 * @param pchecksum where to store the checksum result for this action
3402 * @param checksum_len the number of bytes available for the result
3403 * @param prval where to store the return value for this action
3405 CEPH_RADOS_API
void rados_read_op_checksum(rados_read_op_t read_op
,
3406 rados_checksum_type_t type
,
3407 const char *init_value
,
3408 size_t init_value_len
,
3409 uint64_t offset
, size_t len
,
3410 size_t chunk_size
, char *pchecksum
,
3411 size_t checksum_len
, int *prval
);
3414 * Execute an OSD class method on an object
3415 * See rados_exec() for general description.
3417 * The output buffer is allocated on the heap; the caller is
3418 * expected to release that memory with rados_buffer_free(). The
3419 * buffer and length pointers can all be NULL, in which case they are
3422 * @param read_op operation to add this action to
3423 * @param cls the name of the class
3424 * @param method the name of the method
3425 * @param in_buf where to find input
3426 * @param in_len length of in_buf in bytes
3427 * @param out_buf where to put librados-allocated output buffer
3428 * @param out_len length of out_buf in bytes
3429 * @param prval where to store the return value from the method
3431 CEPH_RADOS_API
void rados_read_op_exec(rados_read_op_t read_op
,
3441 * Execute an OSD class method on an object
3442 * See rados_exec() for general description.
3444 * If the output buffer is too small, prval will
3445 * be set to -ERANGE and used_len will be 0.
3447 * @param read_op operation to add this action to
3448 * @param cls the name of the class
3449 * @param method the name of the method
3450 * @param in_buf where to find input
3451 * @param in_len length of in_buf in bytes
3452 * @param out_buf user-provided buffer to read into
3453 * @param out_len length of out_buf in bytes
3454 * @param used_len where to store the number of bytes read into out_buf
3455 * @param prval where to store the return value from the method
3457 CEPH_RADOS_API
void rados_read_op_exec_user_buf(rados_read_op_t read_op
,
3468 * Start iterating over key/value pairs on an object.
3470 * They will be returned sorted by key.
3472 * @param read_op operation to add this action to
3473 * @param start_after list keys starting after start_after
3474 * @param filter_prefix list only keys beginning with filter_prefix
3475 * @param max_return list no more than max_return key/value pairs
3476 * @param iter where to store the iterator
3477 * @param prval where to store the return value from this action
3479 CEPH_RADOS_API
void rados_read_op_omap_get_vals(rados_read_op_t read_op
,
3480 const char *start_after
,
3481 const char *filter_prefix
,
3482 uint64_t max_return
,
3483 rados_omap_iter_t
*iter
,
3485 __attribute__((deprecated
)); /* use v2 below */
3488 * Start iterating over key/value pairs on an object.
3490 * They will be returned sorted by key.
3492 * @param read_op operation to add this action to
3493 * @param start_after list keys starting after start_after
3494 * @param filter_prefix list only keys beginning with filter_prefix
3495 * @param max_return list no more than max_return key/value pairs
3496 * @param iter where to store the iterator
3497 * @param pmore flag indicating whether there are more keys to fetch
3498 * @param prval where to store the return value from this action
3500 CEPH_RADOS_API
void rados_read_op_omap_get_vals2(rados_read_op_t read_op
,
3501 const char *start_after
,
3502 const char *filter_prefix
,
3503 uint64_t max_return
,
3504 rados_omap_iter_t
*iter
,
3505 unsigned char *pmore
,
3509 * Start iterating over keys on an object.
3511 * They will be returned sorted by key, and the iterator
3512 * will fill in NULL for all values if specified.
3514 * @param read_op operation to add this action to
3515 * @param start_after list keys starting after start_after
3516 * @param max_return list no more than max_return keys
3517 * @param iter where to store the iterator
3518 * @param prval where to store the return value from this action
3520 CEPH_RADOS_API
void rados_read_op_omap_get_keys(rados_read_op_t read_op
,
3521 const char *start_after
,
3522 uint64_t max_return
,
3523 rados_omap_iter_t
*iter
,
3525 __attribute__((deprecated
)); /* use v2 below */
3528 * Start iterating over keys on an object.
3530 * They will be returned sorted by key, and the iterator
3531 * will fill in NULL for all values if specified.
3533 * @param read_op operation to add this action to
3534 * @param start_after list keys starting after start_after
3535 * @param max_return list no more than max_return keys
3536 * @param iter where to store the iterator
3537 * @param pmore flag indicating whether there are more keys to fetch
3538 * @param prval where to store the return value from this action
3540 CEPH_RADOS_API
void rados_read_op_omap_get_keys2(rados_read_op_t read_op
,
3541 const char *start_after
,
3542 uint64_t max_return
,
3543 rados_omap_iter_t
*iter
,
3544 unsigned char *pmore
,
3548 * Start iterating over specific key/value pairs
3550 * They will be returned sorted by key.
3552 * @param read_op operation to add this action to
3553 * @param keys array of pointers to null-terminated keys to get
3554 * @param keys_len the number of strings in keys
3555 * @param iter where to store the iterator
3556 * @param prval where to store the return value from this action
3558 CEPH_RADOS_API
void rados_read_op_omap_get_vals_by_keys(rados_read_op_t read_op
,
3559 char const* const* keys
,
3561 rados_omap_iter_t
*iter
,
3565 * Start iterating over specific key/value pairs
3567 * They will be returned sorted by key.
3569 * @param read_op operation to add this action to
3570 * @param keys array of pointers to keys to get
3571 * @param num_keys the number of strings in keys
3572 * @param key_lens array of size_t's describing each key len (in bytes)
3573 * @param iter where to store the iterator
3574 * @param prval where to store the return value from this action
3576 CEPH_RADOS_API
void rados_read_op_omap_get_vals_by_keys2(rados_read_op_t read_op
,
3577 char const* const* keys
,
3579 const size_t* key_lens
,
3580 rados_omap_iter_t
*iter
,
3584 * Perform a read operation synchronously
3585 * @param read_op operation to perform
3586 * @param io the ioctx that the object is in
3587 * @param oid the object id
3588 * @param flags flags to apply to the entire operation (LIBRADOS_OPERATION_*)
3590 CEPH_RADOS_API
int rados_read_op_operate(rados_read_op_t read_op
,
3596 * Perform a read operation asynchronously
3597 * @param read_op operation to perform
3598 * @param io the ioctx that the object is in
3599 * @param completion what to do when operation has been attempted
3600 * @param oid the object id
3601 * @param flags flags to apply to the entire operation (LIBRADOS_OPERATION_*)
3603 CEPH_RADOS_API
int rados_aio_read_op_operate(rados_read_op_t read_op
,
3605 rados_completion_t completion
,
3609 /** @} Object Operations */
3612 * Take an exclusive lock on an object.
3614 * @param io the context to operate in
3615 * @param oid the name of the object
3616 * @param name the name of the lock
3617 * @param cookie user-defined identifier for this instance of the lock
3618 * @param desc user-defined lock description
3619 * @param duration the duration of the lock. Set to NULL for infinite duration.
3620 * @param flags lock flags
3621 * @returns 0 on success, negative error code on failure
3622 * @returns -EBUSY if the lock is already held by another (client, cookie) pair
3623 * @returns -EEXIST if the lock is already held by the same (client, cookie) pair
3625 CEPH_RADOS_API
int rados_lock_exclusive(rados_ioctx_t io
, const char * oid
,
3626 const char * name
, const char * cookie
,
3628 struct timeval
* duration
,
3632 * Take a shared lock on an object.
3634 * @param io the context to operate in
3635 * @param o the name of the object
3636 * @param name the name of the lock
3637 * @param cookie user-defined identifier for this instance of the lock
3638 * @param tag The tag of the lock
3639 * @param desc user-defined lock description
3640 * @param duration the duration of the lock. Set to NULL for infinite duration.
3641 * @param flags lock flags
3642 * @returns 0 on success, negative error code on failure
3643 * @returns -EBUSY if the lock is already held by another (client, cookie) pair
3644 * @returns -EEXIST if the lock is already held by the same (client, cookie) pair
3646 CEPH_RADOS_API
int rados_lock_shared(rados_ioctx_t io
, const char * o
,
3647 const char * name
, const char * cookie
,
3648 const char * tag
, const char * desc
,
3649 struct timeval
* duration
, uint8_t flags
);
3652 * Release a shared or exclusive lock on an object.
3654 * @param io the context to operate in
3655 * @param o the name of the object
3656 * @param name the name of the lock
3657 * @param cookie user-defined identifier for the instance of the lock
3658 * @returns 0 on success, negative error code on failure
3659 * @returns -ENOENT if the lock is not held by the specified (client, cookie) pair
3661 CEPH_RADOS_API
int rados_unlock(rados_ioctx_t io
, const char *o
,
3662 const char *name
, const char *cookie
);
3665 * Asynchronous release a shared or exclusive lock on an object.
3667 * @param io the context to operate in
3668 * @param o the name of the object
3669 * @param name the name of the lock
3670 * @param cookie user-defined identifier for the instance of the lock
3671 * @param completion what to do when operation has been attempted
3672 * @returns 0 on success, negative error code on failure
3674 CEPH_RADOS_API
int rados_aio_unlock(rados_ioctx_t io
, const char *o
,
3675 const char *name
, const char *cookie
,
3676 rados_completion_t completion
);
3679 * List clients that have locked the named object lock and information about
3682 * The number of bytes required in each buffer is put in the
3683 * corresponding size out parameter. If any of the provided buffers
3684 * are too short, -ERANGE is returned after these sizes are filled in.
3686 * @param io the context to operate in
3687 * @param o the name of the object
3688 * @param name the name of the lock
3689 * @param exclusive where to store whether the lock is exclusive (1) or shared (0)
3690 * @param tag where to store the tag associated with the object lock
3691 * @param tag_len number of bytes in tag buffer
3692 * @param clients buffer in which locker clients are stored, separated by '\0'
3693 * @param clients_len number of bytes in the clients buffer
3694 * @param cookies buffer in which locker cookies are stored, separated by '\0'
3695 * @param cookies_len number of bytes in the cookies buffer
3696 * @param addrs buffer in which locker addresses are stored, separated by '\0'
3697 * @param addrs_len number of bytes in the clients buffer
3698 * @returns number of lockers on success, negative error code on failure
3699 * @returns -ERANGE if any of the buffers are too short
3701 CEPH_RADOS_API ssize_t
rados_list_lockers(rados_ioctx_t io
, const char *o
,
3702 const char *name
, int *exclusive
,
3703 char *tag
, size_t *tag_len
,
3704 char *clients
, size_t *clients_len
,
3705 char *cookies
, size_t *cookies_len
,
3706 char *addrs
, size_t *addrs_len
);
3709 * Releases a shared or exclusive lock on an object, which was taken by the
3712 * @param io the context to operate in
3713 * @param o the name of the object
3714 * @param name the name of the lock
3715 * @param client the client currently holding the lock
3716 * @param cookie user-defined identifier for the instance of the lock
3717 * @returns 0 on success, negative error code on failure
3718 * @returns -ENOENT if the lock is not held by the specified (client, cookie) pair
3719 * @returns -EINVAL if the client cannot be parsed
3721 CEPH_RADOS_API
int rados_break_lock(rados_ioctx_t io
, const char *o
,
3722 const char *name
, const char *client
,
3723 const char *cookie
);
3726 * Blocklists the specified client from the OSDs
3728 * @param cluster cluster handle
3729 * @param client_address client address
3730 * @param expire_seconds number of seconds to blocklist (0 for default)
3731 * @returns 0 on success, negative error code on failure
3733 CEPH_RADOS_API
int rados_blocklist_add(rados_t cluster
,
3734 char *client_address
,
3735 uint32_t expire_seconds
);
3736 CEPH_RADOS_API
int rados_blacklist_add(rados_t cluster
,
3737 char *client_address
,
3738 uint32_t expire_seconds
)
3739 __attribute__((deprecated
));
3742 * Gets addresses of the RADOS session, suitable for blocklisting.
3744 * @param cluster cluster handle
3745 * @param addrs the output string.
3746 * @returns 0 on success, negative error code on failure
3748 CEPH_RADOS_API
int rados_getaddrs(rados_t cluster
, char** addrs
);
3750 CEPH_RADOS_API
void rados_set_osdmap_full_try(rados_ioctx_t io
)
3751 __attribute__((deprecated
));
3753 CEPH_RADOS_API
void rados_unset_osdmap_full_try(rados_ioctx_t io
)
3754 __attribute__((deprecated
));
3756 CEPH_RADOS_API
void rados_set_pool_full_try(rados_ioctx_t io
);
3758 CEPH_RADOS_API
void rados_unset_pool_full_try(rados_ioctx_t io
);
3761 * Enable an application on a pool
3763 * @param io pool ioctx
3764 * @param app_name application name
3765 * @param force 0 if only single application per pool
3766 * @returns 0 on success, negative error code on failure
3768 CEPH_RADOS_API
int rados_application_enable(rados_ioctx_t io
,
3769 const char *app_name
, int force
);
3772 * List all enabled applications
3774 * If the provided buffer is too short, the required length is filled in and
3775 * -ERANGE is returned. Otherwise, the buffers are filled with the application
3776 * names, with a '\0' after each.
3778 * @param io pool ioctx
3779 * @param values buffer in which to store application names
3780 * @param values_len number of bytes in values buffer
3781 * @returns 0 on success, negative error code on failure
3782 * @returns -ERANGE if either buffer is too short
3784 CEPH_RADOS_API
int rados_application_list(rados_ioctx_t io
, char *values
,
3785 size_t *values_len
);
3788 * Get application metadata value from pool
3790 * @param io pool ioctx
3791 * @param app_name application name
3792 * @param key metadata key
3793 * @param value result buffer
3794 * @param value_len maximum len of value
3795 * @returns 0 on success, negative error code on failure
3797 CEPH_RADOS_API
int rados_application_metadata_get(rados_ioctx_t io
,
3798 const char *app_name
,
3799 const char *key
, char *value
,
3803 * Set application metadata on a pool
3805 * @param io pool ioctx
3806 * @param app_name application name
3807 * @param key metadata key
3808 * @param value metadata key
3809 * @returns 0 on success, negative error code on failure
3811 CEPH_RADOS_API
int rados_application_metadata_set(rados_ioctx_t io
,
3812 const char *app_name
,
3817 * Remove application metadata from a pool
3819 * @param io pool ioctx
3820 * @param app_name application name
3821 * @param key metadata key
3822 * @returns 0 on success, negative error code on failure
3824 CEPH_RADOS_API
int rados_application_metadata_remove(rados_ioctx_t io
,
3825 const char *app_name
,
3829 * List all metadata key/value pairs associated with an application.
3831 * This iterates over all metadata, key_len and val_len are filled in
3832 * with the number of bytes put into the keys and values buffers.
3834 * If the provided buffers are too short, the required lengths are filled
3835 * in and -ERANGE is returned. Otherwise, the buffers are filled with
3836 * the keys and values of the metadata, with a '\0' after each.
3838 * @param io pool ioctx
3839 * @param app_name application name
3840 * @param keys buffer in which to store key names
3841 * @param key_len number of bytes in keys buffer
3842 * @param values buffer in which to store values
3843 * @param vals_len number of bytes in values buffer
3844 * @returns 0 on success, negative error code on failure
3845 * @returns -ERANGE if either buffer is too short
3847 CEPH_RADOS_API
int rados_application_metadata_list(rados_ioctx_t io
,
3848 const char *app_name
,
3849 char *keys
, size_t *key_len
,
3854 * @name Mon/OSD/PG Commands
3856 * These interfaces send commands relating to the monitor, OSD, or PGs.
3862 * Send monitor command.
3864 * @note Takes command string in carefully-formatted JSON; must match
3865 * defined commands, types, etc.
3867 * The result buffers are allocated on the heap; the caller is
3868 * expected to release that memory with rados_buffer_free(). The
3869 * buffer and length pointers can all be NULL, in which case they are
3872 * @param cluster cluster handle
3873 * @param cmd an array of char *'s representing the command
3874 * @param cmdlen count of valid entries in cmd
3875 * @param inbuf any bulk input data (crush map, etc.)
3876 * @param inbuflen input buffer length
3877 * @param outbuf double pointer to output buffer
3878 * @param outbuflen pointer to output buffer length
3879 * @param outs double pointer to status string
3880 * @param outslen pointer to status string length
3881 * @returns 0 on success, negative error code on failure
3883 CEPH_RADOS_API
int rados_mon_command(rados_t cluster
, const char **cmd
,
3884 size_t cmdlen
, const char *inbuf
,
3885 size_t inbuflen
, char **outbuf
,
3886 size_t *outbuflen
, char **outs
,
3890 * Send ceph-mgr command.
3892 * @note Takes command string in carefully-formatted JSON; must match
3893 * defined commands, types, etc.
3895 * The result buffers are allocated on the heap; the caller is
3896 * expected to release that memory with rados_buffer_free(). The
3897 * buffer and length pointers can all be NULL, in which case they are
3900 * @param cluster cluster handle
3901 * @param cmd an array of char *'s representing the command
3902 * @param cmdlen count of valid entries in cmd
3903 * @param inbuf any bulk input data (crush map, etc.)
3904 * @param inbuflen input buffer length
3905 * @param outbuf double pointer to output buffer
3906 * @param outbuflen pointer to output buffer length
3907 * @param outs double pointer to status string
3908 * @param outslen pointer to status string length
3909 * @returns 0 on success, negative error code on failure
3911 CEPH_RADOS_API
int rados_mgr_command(rados_t cluster
, const char **cmd
,
3912 size_t cmdlen
, const char *inbuf
,
3913 size_t inbuflen
, char **outbuf
,
3914 size_t *outbuflen
, char **outs
,
3918 * Send ceph-mgr tell command.
3920 * @note Takes command string in carefully-formatted JSON; must match
3921 * defined commands, types, etc.
3923 * The result buffers are allocated on the heap; the caller is
3924 * expected to release that memory with rados_buffer_free(). The
3925 * buffer and length pointers can all be NULL, in which case they are
3928 * @param cluster cluster handle
3929 * @param name mgr name to target
3930 * @param cmd an array of char *'s representing the command
3931 * @param cmdlen count of valid entries in cmd
3932 * @param inbuf any bulk input data (crush map, etc.)
3933 * @param inbuflen input buffer length
3934 * @param outbuf double pointer to output buffer
3935 * @param outbuflen pointer to output buffer length
3936 * @param outs double pointer to status string
3937 * @param outslen pointer to status string length
3938 * @returns 0 on success, negative error code on failure
3940 CEPH_RADOS_API
int rados_mgr_command_target(
3944 size_t cmdlen
, const char *inbuf
,
3945 size_t inbuflen
, char **outbuf
,
3946 size_t *outbuflen
, char **outs
,
3950 * Send monitor command to a specific monitor.
3952 * @note Takes command string in carefully-formatted JSON; must match
3953 * defined commands, types, etc.
3955 * The result buffers are allocated on the heap; the caller is
3956 * expected to release that memory with rados_buffer_free(). The
3957 * buffer and length pointers can all be NULL, in which case they are
3960 * @param cluster cluster handle
3961 * @param name target monitor's name
3962 * @param cmd an array of char *'s representing the command
3963 * @param cmdlen count of valid entries in cmd
3964 * @param inbuf any bulk input data (crush map, etc.)
3965 * @param inbuflen input buffer length
3966 * @param outbuf double pointer to output buffer
3967 * @param outbuflen pointer to output buffer length
3968 * @param outs double pointer to status string
3969 * @param outslen pointer to status string length
3970 * @returns 0 on success, negative error code on failure
3972 CEPH_RADOS_API
int rados_mon_command_target(rados_t cluster
, const char *name
,
3973 const char **cmd
, size_t cmdlen
,
3974 const char *inbuf
, size_t inbuflen
,
3975 char **outbuf
, size_t *outbuflen
,
3976 char **outs
, size_t *outslen
);
3979 * free a rados-allocated buffer
3981 * Release memory allocated by librados calls like rados_mon_command().
3983 * @param buf buffer pointer
3985 CEPH_RADOS_API
void rados_buffer_free(char *buf
);
3987 CEPH_RADOS_API
int rados_osd_command(rados_t cluster
, int osdid
,
3988 const char **cmd
, size_t cmdlen
,
3989 const char *inbuf
, size_t inbuflen
,
3990 char **outbuf
, size_t *outbuflen
,
3991 char **outs
, size_t *outslen
);
3993 CEPH_RADOS_API
int rados_pg_command(rados_t cluster
, const char *pgstr
,
3994 const char **cmd
, size_t cmdlen
,
3995 const char *inbuf
, size_t inbuflen
,
3996 char **outbuf
, size_t *outbuflen
,
3997 char **outs
, size_t *outslen
);
3999 CEPH_RADOS_API
int rados_mgr_command(rados_t cluster
,
4000 const char **cmd
, size_t cmdlen
,
4001 const char *inbuf
, size_t inbuflen
,
4002 char **outbuf
, size_t *outbuflen
,
4003 char **outs
, size_t *outslen
);
4006 * This is not a doxygen comment leadin, because doxygen breaks on
4007 * a typedef with function params and returns, and I can't figure out
4010 * Monitor cluster log
4012 * Monitor events logged to the cluster log. The callback get each
4013 * log entry both as a single formatted line and with each field in a
4016 * Calling with a cb argument of NULL will deregister any previously
4017 * registered callback.
4019 * @param cluster cluster handle
4020 * @param level minimum log level (debug, info, warn|warning, err|error)
4021 * @param cb callback to run for each log message. It MUST NOT block
4022 * nor call back into librados.
4023 * @param arg void argument to pass to cb
4025 * @returns 0 on success, negative code on error
4027 typedef void (*rados_log_callback_t
)(void *arg
,
4030 uint64_t sec
, uint64_t nsec
,
4031 uint64_t seq
, const char *level
,
4035 * This is not a doxygen comment leadin, because doxygen breaks on
4036 * a typedef with function params and returns, and I can't figure out
4039 * Monitor cluster log
4041 * Monitor events logged to the cluster log. The callback get each
4042 * log entry both as a single formatted line and with each field in a
4045 * Calling with a cb argument of NULL will deregister any previously
4046 * registered callback.
4048 * @param cluster cluster handle
4049 * @param level minimum log level (debug, info, warn|warning, err|error)
4050 * @param cb callback to run for each log message. It MUST NOT block
4051 * nor call back into librados.
4052 * @param arg void argument to pass to cb
4054 * @returns 0 on success, negative code on error
4056 typedef void (*rados_log_callback2_t
)(void *arg
,
4058 const char *channel
,
4061 uint64_t sec
, uint64_t nsec
,
4062 uint64_t seq
, const char *level
,
4065 CEPH_RADOS_API
int rados_monitor_log(rados_t cluster
, const char *level
,
4066 rados_log_callback_t cb
, void *arg
);
4067 CEPH_RADOS_API
int rados_monitor_log2(rados_t cluster
, const char *level
,
4068 rados_log_callback2_t cb
, void *arg
);
4072 * register daemon instance for a service
4074 * Register us as a daemon providing a particular service. We identify
4075 * the service (e.g., 'rgw') and our instance name (e.g., 'rgw.$hostname').
4076 * The metadata is a map of keys and values with arbitrary static metdata
4077 * for this instance. The encoding is a series of NULL-terminated strings,
4078 * alternating key names and values, terminating with an empty key name.
4079 * For example, "foo\0bar\0this\0that\0\0" is the dict {foo=bar,this=that}.
4081 * For the lifetime of the librados instance, regular beacons will be sent
4082 * to the cluster to maintain our registration in the service map.
4084 * @param cluster handle
4085 * @param service service name
4086 * @param daemon daemon instance name
4087 * @param metadata_dict static daemon metadata dict
4089 CEPH_RADOS_API
int rados_service_register(
4091 const char *service
,
4093 const char *metadata_dict
);
4096 * update daemon status
4098 * Update our mutable status information in the service map.
4100 * The status dict is encoded the same way the daemon metadata is encoded
4101 * for rados_service_register. For example, "foo\0bar\0this\0that\0\0" is
4102 * {foo=bar,this=that}.
4104 * @param cluster rados cluster handle
4105 * @param status_dict status dict
4107 CEPH_RADOS_API
int rados_service_update_status(
4109 const char *status_dict
);
4111 /** @} Mon/OSD/PG commands */
4114 * These methods are no longer supported and return -ENOTSUP where possible.
4116 CEPH_RADOS_API
int rados_objects_list_open(
4118 rados_list_ctx_t
*ctx
) __attribute__((deprecated
));
4119 CEPH_RADOS_API
uint32_t rados_objects_list_get_pg_hash_position(
4120 rados_list_ctx_t ctx
) __attribute__((deprecated
));
4121 CEPH_RADOS_API
uint32_t rados_objects_list_seek(
4122 rados_list_ctx_t ctx
,
4123 uint32_t pos
) __attribute__((deprecated
));
4124 CEPH_RADOS_API
int rados_objects_list_next(
4125 rados_list_ctx_t ctx
,
4127 const char **key
) __attribute__((deprecated
));
4128 CEPH_RADOS_API
void rados_objects_list_close(
4129 rados_list_ctx_t ctx
) __attribute__((deprecated
));