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 size and most recent update time from the OSD.
1819 * @param o object name
1820 * @param psize where to store object size
1821 * @param pmtime where to store modification time
1822 * @returns 0 on success, negative error code on failure
1824 CEPH_RADOS_API
int rados_stat(rados_ioctx_t io
, const char *o
, uint64_t *psize
,
1827 CEPH_RADOS_API
int rados_stat2(rados_ioctx_t io
, const char *o
, uint64_t *psize
,
1828 struct timespec
*pmtime
);
1831 * Execute an OSD class method on an object
1833 * The OSD has a plugin mechanism for performing complicated
1834 * operations on an object atomically. These plugins are called
1835 * classes. This function allows librados users to call the custom
1836 * methods. The input and output formats are defined by the class.
1837 * Classes in ceph.git can be found in src/cls subdirectories
1839 * @param io the context in which to call the method
1840 * @param oid the object to call the method on
1841 * @param cls the name of the class
1842 * @param method the name of the method
1843 * @param in_buf where to find input
1844 * @param in_len length of in_buf in bytes
1845 * @param buf where to store output
1846 * @param out_len length of buf in bytes
1847 * @returns the length of the output, or
1848 * -ERANGE if out_buf does not have enough space to store it (For methods that return data). For
1849 * methods that don't return data, the return value is
1852 CEPH_RADOS_API
int rados_exec(rados_ioctx_t io
, const char *oid
,
1853 const char *cls
, const char *method
,
1854 const char *in_buf
, size_t in_len
, char *buf
,
1858 /** @} Synchronous I/O */
1861 * @name Asynchronous I/O
1862 * Read and write to objects without blocking.
1868 * @typedef rados_callback_t
1869 * Callbacks for asynchrous operations take two parameters:
1870 * - cb the completion that has finished
1871 * - arg application defined data made available to the callback function
1873 typedef void (*rados_callback_t
)(rados_completion_t cb
, void *arg
);
1876 * Constructs a completion to use with asynchronous operations
1878 * The complete and safe callbacks correspond to operations being
1879 * acked and committed, respectively. The callbacks are called in
1880 * order of receipt, so the safe callback may be triggered before the
1881 * complete callback, and vice versa. This is affected by journalling
1884 * TODO: more complete documentation of this elsewhere (in the RADOS docs?)
1886 * @note Read operations only get a complete callback.
1887 * @note BUG: this should check for ENOMEM instead of throwing an exception
1889 * @param cb_arg application-defined data passed to the callback functions
1890 * @param cb_complete the function to be called when the operation is
1891 * in memory on all replicas
1892 * @param cb_safe the function to be called when the operation is on
1893 * stable storage on all replicas
1894 * @param pc where to store the completion
1897 CEPH_RADOS_API
int rados_aio_create_completion(void *cb_arg
,
1898 rados_callback_t cb_complete
,
1899 rados_callback_t cb_safe
,
1900 rados_completion_t
*pc
);
1903 * Constructs a completion to use with asynchronous operations
1905 * The complete callback corresponds to operation being acked.
1907 * @note BUG: this should check for ENOMEM instead of throwing an exception
1909 * @param cb_arg application-defined data passed to the callback functions
1910 * @param cb_complete the function to be called when the operation is committed
1912 * @param pc where to store the completion
1915 CEPH_RADOS_API
int rados_aio_create_completion2(void *cb_arg
,
1916 rados_callback_t cb_complete
,
1917 rados_completion_t
*pc
);
1920 * Block until an operation completes
1922 * This means it is in memory on all replicas.
1924 * @note BUG: this should be void
1926 * @param c operation to wait for
1929 CEPH_RADOS_API
int rados_aio_wait_for_complete(rados_completion_t c
);
1932 * Block until an operation is safe
1934 * This means it is on stable storage on all replicas.
1936 * @note BUG: this should be void
1938 * @param c operation to wait for
1941 CEPH_RADOS_API
int rados_aio_wait_for_safe(rados_completion_t c
)
1942 __attribute__((deprecated
));
1945 * Has an asynchronous operation completed?
1947 * @warning This does not imply that the complete callback has
1950 * @param c async operation to inspect
1951 * @returns whether c is complete
1953 CEPH_RADOS_API
int rados_aio_is_complete(rados_completion_t c
);
1956 * Is an asynchronous operation safe?
1958 * @warning This does not imply that the safe callback has
1961 * @param c async operation to inspect
1962 * @returns whether c is safe
1964 CEPH_RADOS_API
int rados_aio_is_safe(rados_completion_t c
);
1967 * Block until an operation completes and callback completes
1969 * This means it is in memory on all replicas and can be read.
1971 * @note BUG: this should be void
1973 * @param c operation to wait for
1976 CEPH_RADOS_API
int rados_aio_wait_for_complete_and_cb(rados_completion_t c
);
1979 * Block until an operation is safe and callback has completed
1981 * This means it is on stable storage on all replicas.
1983 * @note BUG: this should be void
1985 * @param c operation to wait for
1988 CEPH_RADOS_API
int rados_aio_wait_for_safe_and_cb(rados_completion_t c
)
1989 __attribute__((deprecated
));
1992 * Has an asynchronous operation and callback completed
1994 * @param c async operation to inspect
1995 * @returns whether c is complete
1997 CEPH_RADOS_API
int rados_aio_is_complete_and_cb(rados_completion_t c
);
2000 * Is an asynchronous operation safe and has the callback completed
2002 * @param c async operation to inspect
2003 * @returns whether c is safe
2005 CEPH_RADOS_API
int rados_aio_is_safe_and_cb(rados_completion_t c
);
2008 * Get the return value of an asychronous operation
2010 * The return value is set when the operation is complete or safe,
2011 * whichever comes first.
2013 * @pre The operation is safe or complete
2015 * @note BUG: complete callback may never be called when the safe
2016 * message is received before the complete message
2018 * @param c async operation to inspect
2019 * @returns return value of the operation
2021 CEPH_RADOS_API
int rados_aio_get_return_value(rados_completion_t c
);
2024 * Get the internal object version of the target of an asychronous operation
2026 * The return value is set when the operation is complete or safe,
2027 * whichever comes first.
2029 * @pre The operation is safe or complete
2031 * @note BUG: complete callback may never be called when the safe
2032 * message is received before the complete message
2034 * @param c async operation to inspect
2035 * @returns version number of the asychronous operation's target
2037 CEPH_RADOS_API
uint64_t rados_aio_get_version(rados_completion_t c
);
2040 * Release a completion
2042 * Call this when you no longer need the completion. It may not be
2043 * freed immediately if the operation is not acked and committed.
2045 * @param c completion to release
2047 CEPH_RADOS_API
void rados_aio_release(rados_completion_t c
);
2050 * Write data to an object asynchronously
2052 * Queues the write and returns. The return value of the completion
2053 * will be 0 on success, negative error code on failure.
2055 * @param io the context in which the write will occur
2056 * @param oid name of the object
2057 * @param completion what to do when the write is safe and complete
2058 * @param buf data to write
2059 * @param len length of the data, in bytes
2060 * @param off byte offset in the object to begin writing at
2061 * @returns 0 on success, -EROFS if the io context specifies a snap_seq
2062 * other than LIBRADOS_SNAP_HEAD
2064 CEPH_RADOS_API
int rados_aio_write(rados_ioctx_t io
, const char *oid
,
2065 rados_completion_t completion
,
2066 const char *buf
, size_t len
, uint64_t off
);
2069 * Asynchronously append data to an object
2071 * Queues the append and returns.
2073 * The return value of the completion will be 0 on success, negative
2074 * error code on failure.
2076 * @param io the context to operate in
2077 * @param oid the name of the object
2078 * @param completion what to do when the append is safe and complete
2079 * @param buf the data to append
2080 * @param len length of buf (in bytes)
2081 * @returns 0 on success, -EROFS if the io context specifies a snap_seq
2082 * other than LIBRADOS_SNAP_HEAD
2084 CEPH_RADOS_API
int rados_aio_append(rados_ioctx_t io
, const char *oid
,
2085 rados_completion_t completion
,
2086 const char *buf
, size_t len
);
2089 * Asynchronously write an entire object
2091 * The object is filled with the provided data. If the object exists,
2092 * it is atomically truncated and then written.
2093 * Queues the write_full and returns.
2095 * The return value of the completion will be 0 on success, negative
2096 * error code on failure.
2098 * @param io the io context in which the write will occur
2099 * @param oid name of the object
2100 * @param completion what to do when the write_full is safe and complete
2101 * @param buf data to write
2102 * @param len length of the data, in bytes
2103 * @returns 0 on success, -EROFS if the io context specifies a snap_seq
2104 * other than LIBRADOS_SNAP_HEAD
2106 CEPH_RADOS_API
int rados_aio_write_full(rados_ioctx_t io
, const char *oid
,
2107 rados_completion_t completion
,
2108 const char *buf
, size_t len
);
2111 * Asynchronously write the same buffer multiple times
2113 * Queues the writesame and returns.
2115 * The return value of the completion will be 0 on success, negative
2116 * error code on failure.
2118 * @param io the io context in which the write will occur
2119 * @param oid name of the object
2120 * @param completion what to do when the writesame is safe and complete
2121 * @param buf data to write
2122 * @param data_len length of the data, in bytes
2123 * @param write_len the total number of bytes to write
2124 * @param off byte offset in the object to begin writing at
2125 * @returns 0 on success, -EROFS if the io context specifies a snap_seq
2126 * other than LIBRADOS_SNAP_HEAD
2128 CEPH_RADOS_API
int rados_aio_writesame(rados_ioctx_t io
, const char *oid
,
2129 rados_completion_t completion
,
2130 const char *buf
, size_t data_len
,
2131 size_t write_len
, uint64_t off
);
2134 * Asynchronously remove an object
2136 * Queues the remove and returns.
2138 * The return value of the completion will be 0 on success, negative
2139 * error code on failure.
2141 * @param io the context to operate in
2142 * @param oid the name of the object
2143 * @param completion what to do when the remove is safe and complete
2144 * @returns 0 on success, -EROFS if the io context specifies a snap_seq
2145 * other than LIBRADOS_SNAP_HEAD
2147 CEPH_RADOS_API
int rados_aio_remove(rados_ioctx_t io
, const char *oid
,
2148 rados_completion_t completion
);
2151 * Asynchronously read data from an object
2153 * The io context determines the snapshot to read from, if any was set
2154 * by rados_ioctx_snap_set_read().
2156 * The return value of the completion will be number of bytes read on
2157 * success, negative error code on failure.
2159 * @note only the 'complete' callback of the completion will be called.
2161 * @param io the context in which to perform the read
2162 * @param oid the name of the object to read from
2163 * @param completion what to do when the read is complete
2164 * @param buf where to store the results
2165 * @param len the number of bytes to read
2166 * @param off the offset to start reading from in the object
2167 * @returns 0 on success, negative error code on failure
2169 CEPH_RADOS_API
int rados_aio_read(rados_ioctx_t io
, const char *oid
,
2170 rados_completion_t completion
,
2171 char *buf
, size_t len
, uint64_t off
);
2174 * Block until all pending writes in an io context are safe
2176 * This is not equivalent to calling rados_aio_wait_for_safe() on all
2177 * write completions, since this waits for the associated callbacks to
2180 * @note BUG: always returns 0, should be void or accept a timeout
2182 * @param io the context to flush
2183 * @returns 0 on success, negative error code on failure
2185 CEPH_RADOS_API
int rados_aio_flush(rados_ioctx_t io
);
2189 * Schedule a callback for when all currently pending
2190 * aio writes are safe. This is a non-blocking version of
2191 * rados_aio_flush().
2193 * @param io the context to flush
2194 * @param completion what to do when the writes are safe
2195 * @returns 0 on success, negative error code on failure
2197 CEPH_RADOS_API
int rados_aio_flush_async(rados_ioctx_t io
,
2198 rados_completion_t completion
);
2202 * Asynchronously get object stats (size/mtime)
2205 * @param o object name
2206 * @param completion what to do when the stat is complete
2207 * @param psize where to store object size
2208 * @param pmtime where to store modification time
2209 * @returns 0 on success, negative error code on failure
2211 CEPH_RADOS_API
int rados_aio_stat(rados_ioctx_t io
, const char *o
,
2212 rados_completion_t completion
,
2213 uint64_t *psize
, time_t *pmtime
);
2215 CEPH_RADOS_API
int rados_aio_stat2(rados_ioctx_t io
, const char *o
,
2216 rados_completion_t completion
,
2217 uint64_t *psize
, struct timespec
*pmtime
);
2220 * Asynchronously compare an on-disk object range with a buffer
2222 * @param io the context in which to perform the comparison
2223 * @param o the name of the object to compare with
2224 * @param completion what to do when the comparison is complete
2225 * @param cmp_buf buffer containing bytes to be compared with object contents
2226 * @param cmp_len length to compare and size of @c cmp_buf in bytes
2227 * @param off object byte offset at which to start the comparison
2228 * @returns 0 on success, negative error code on failure,
2229 * (-MAX_ERRNO - mismatch_off) on mismatch
2231 CEPH_RADOS_API
int rados_aio_cmpext(rados_ioctx_t io
, const char *o
,
2232 rados_completion_t completion
,
2233 const char *cmp_buf
,
2238 * Cancel async operation
2241 * @param completion completion handle
2242 * @returns 0 on success, negative error code on failure
2244 CEPH_RADOS_API
int rados_aio_cancel(rados_ioctx_t io
,
2245 rados_completion_t completion
);
2248 * Asynchronously execute an OSD class method on an object
2250 * The OSD has a plugin mechanism for performing complicated
2251 * operations on an object atomically. These plugins are called
2252 * classes. This function allows librados users to call the custom
2253 * methods. The input and output formats are defined by the class.
2254 * Classes in ceph.git can be found in src/cls subdirectories
2256 * @param io the context in which to call the method
2257 * @param o name of the object
2258 * @param completion what to do when the exec completes
2259 * @param cls the name of the class
2260 * @param method the name of the method
2261 * @param in_buf where to find input
2262 * @param in_len length of in_buf in bytes
2263 * @param buf where to store output
2264 * @param out_len length of buf in bytes
2265 * @returns 0 on success, negative error code on failure
2267 CEPH_RADOS_API
int rados_aio_exec(rados_ioctx_t io
, const char *o
,
2268 rados_completion_t completion
,
2269 const char *cls
, const char *method
,
2270 const char *in_buf
, size_t in_len
,
2271 char *buf
, size_t out_len
);
2273 /** @} Asynchronous I/O */
2276 * @name Asynchronous Xattrs
2277 * Extended attributes are stored as extended attributes on the files
2278 * representing an object on the OSDs. Thus, they have the same
2279 * limitations as the underlying filesystem. On ext4, this means that
2280 * the total data stored in xattrs cannot exceed 4KB.
2286 * Asynchronously get the value of an extended attribute on an object.
2288 * @param io the context in which the attribute is read
2289 * @param o name of the object
2290 * @param completion what to do when the getxattr completes
2291 * @param name which extended attribute to read
2292 * @param buf where to store the result
2293 * @param len size of buf in bytes
2294 * @returns length of xattr value on success, negative error code on failure
2296 CEPH_RADOS_API
int rados_aio_getxattr(rados_ioctx_t io
, const char *o
,
2297 rados_completion_t completion
,
2298 const char *name
, char *buf
, size_t len
);
2301 * Asynchronously set an extended attribute on an object.
2303 * @param io the context in which xattr is set
2304 * @param o name of the object
2305 * @param completion what to do when the setxattr completes
2306 * @param name which extended attribute to set
2307 * @param buf what to store in the xattr
2308 * @param len the number of bytes in buf
2309 * @returns 0 on success, negative error code on failure
2311 CEPH_RADOS_API
int rados_aio_setxattr(rados_ioctx_t io
, const char *o
,
2312 rados_completion_t completion
,
2313 const char *name
, const char *buf
,
2317 * Asynchronously delete an extended attribute from an object.
2319 * @param io the context in which to delete the xattr
2320 * @param o the name of the object
2321 * @param completion what to do when the rmxattr completes
2322 * @param name which xattr to delete
2323 * @returns 0 on success, negative error code on failure
2325 CEPH_RADOS_API
int rados_aio_rmxattr(rados_ioctx_t io
, const char *o
,
2326 rados_completion_t completion
,
2330 * Asynchronously start iterating over xattrs on an object.
2332 * @post iter is a valid iterator
2334 * @param io the context in which to list xattrs
2335 * @param oid name of the object
2336 * @param completion what to do when the getxattrs completes
2337 * @param iter where to store the iterator
2338 * @returns 0 on success, negative error code on failure
2340 CEPH_RADOS_API
int rados_aio_getxattrs(rados_ioctx_t io
, const char *oid
,
2341 rados_completion_t completion
,
2342 rados_xattrs_iter_t
*iter
);
2344 /** @} Asynchronous Xattrs */
2347 * @name Watch/Notify
2349 * Watch/notify is a protocol to help communicate among clients. It
2350 * can be used to sychronize client state. All that's needed is a
2351 * well-known object name (for example, rbd uses the header object of
2354 * Watchers register an interest in an object, and receive all
2355 * notifies on that object. A notify attempts to communicate with all
2356 * clients watching an object, and blocks on the notifier until each
2357 * client responds or a timeout is reached.
2359 * See rados_watch() and rados_notify() for more details.
2365 * @typedef rados_watchcb_t
2367 * Callback activated when a notify is received on a watched
2370 * @param opcode undefined
2371 * @param ver version of the watched object
2372 * @param arg application-specific data
2374 * @note BUG: opcode is an internal detail that shouldn't be exposed
2375 * @note BUG: ver is unused
2377 typedef void (*rados_watchcb_t
)(uint8_t opcode
, uint64_t ver
, void *arg
);
2380 * @typedef rados_watchcb2_t
2382 * Callback activated when a notify is received on a watched
2385 * @param arg opaque user-defined value provided to rados_watch2()
2386 * @param notify_id an id for this notify event
2387 * @param handle the watcher handle we are notifying
2388 * @param notifier_id the unique client id for the notifier
2389 * @param data payload from the notifier
2390 * @param data_len length of payload buffer
2392 typedef void (*rados_watchcb2_t
)(void *arg
,
2395 uint64_t notifier_id
,
2400 * @typedef rados_watcherrcb_t
2402 * Callback activated when we encounter an error with the watch session.
2403 * This can happen when the location of the objects moves within the
2404 * cluster and we fail to register our watch with the new object location,
2405 * or when our connection with the object OSD is otherwise interrupted and
2406 * we may have missed notify events.
2408 * @param pre opaque user-defined value provided to rados_watch2()
2409 * @param cookie the internal id assigned to the watch session
2410 * @param err error code
2412 typedef void (*rados_watcherrcb_t
)(void *pre
, uint64_t cookie
, int err
);
2415 * Register an interest in an object
2417 * A watch operation registers the client as being interested in
2418 * notifications on an object. OSDs keep track of watches on
2419 * persistent storage, so they are preserved across cluster changes by
2420 * the normal recovery process. If the client loses its connection to
2421 * the primary OSD for a watched object, the watch will be removed
2422 * after 30 seconds. Watches are automatically reestablished when a new
2423 * connection is made, or a placement group switches OSDs.
2425 * @note BUG: librados should provide a way for watchers to notice connection resets
2426 * @note BUG: the ver parameter does not work, and -ERANGE will never be returned
2427 * (See URL tracker.ceph.com/issues/2592)
2429 * @param io the pool the object is in
2430 * @param o the object to watch
2431 * @param ver expected version of the object
2432 * @param cookie where to store the internal id assigned to this watch
2433 * @param watchcb what to do when a notify is received on this object
2434 * @param arg application defined data to pass when watchcb is called
2435 * @returns 0 on success, negative error code on failure
2436 * @returns -ERANGE if the version of the object is greater than ver
2438 CEPH_RADOS_API
int rados_watch(rados_ioctx_t io
, const char *o
, uint64_t ver
,
2440 rados_watchcb_t watchcb
, void *arg
)
2441 __attribute__((deprecated
));
2445 * Register an interest in an object
2447 * A watch operation registers the client as being interested in
2448 * notifications on an object. OSDs keep track of watches on
2449 * persistent storage, so they are preserved across cluster changes by
2450 * the normal recovery process. If the client loses its connection to the
2451 * primary OSD for a watched object, the watch will be removed after
2452 * a timeout configured with osd_client_watch_timeout.
2453 * Watches are automatically reestablished when a new
2454 * connection is made, or a placement group switches OSDs.
2456 * @param io the pool the object is in
2457 * @param o the object to watch
2458 * @param cookie where to store the internal id assigned to this watch
2459 * @param watchcb what to do when a notify is received on this object
2460 * @param watcherrcb what to do when the watch session encounters an error
2461 * @param arg opaque value to pass to the callback
2462 * @returns 0 on success, negative error code on failure
2464 CEPH_RADOS_API
int rados_watch2(rados_ioctx_t io
, const char *o
, uint64_t *cookie
,
2465 rados_watchcb2_t watchcb
,
2466 rados_watcherrcb_t watcherrcb
,
2470 * Register an interest in an object
2472 * A watch operation registers the client as being interested in
2473 * notifications on an object. OSDs keep track of watches on
2474 * persistent storage, so they are preserved across cluster changes by
2475 * the normal recovery process. Watches are automatically reestablished when a new
2476 * connection is made, or a placement group switches OSDs.
2478 * @param io the pool the object is in
2479 * @param o the object to watch
2480 * @param cookie where to store the internal id assigned to this watch
2481 * @param watchcb what to do when a notify is received on this object
2482 * @param watcherrcb what to do when the watch session encounters an error
2483 * @param timeout how many seconds the connection will keep after disconnection
2484 * @param arg opaque value to pass to the callback
2485 * @returns 0 on success, negative error code on failure
2487 CEPH_RADOS_API
int rados_watch3(rados_ioctx_t io
, const char *o
, uint64_t *cookie
,
2488 rados_watchcb2_t watchcb
,
2489 rados_watcherrcb_t watcherrcb
,
2494 * Asynchronous register an interest in an object
2496 * A watch operation registers the client as being interested in
2497 * notifications on an object. OSDs keep track of watches on
2498 * persistent storage, so they are preserved across cluster changes by
2499 * the normal recovery process. If the client loses its connection to
2500 * the primary OSD for a watched object, the watch will be removed
2501 * after 30 seconds. Watches are automatically reestablished when a new
2502 * connection is made, or a placement group switches OSDs.
2504 * @param io the pool the object is in
2505 * @param o the object to watch
2506 * @param completion what to do when operation has been attempted
2507 * @param handle where to store the internal id assigned to this watch
2508 * @param watchcb what to do when a notify is received on this object
2509 * @param watcherrcb what to do when the watch session encounters an error
2510 * @param arg opaque value to pass to the callback
2511 * @returns 0 on success, negative error code on failure
2513 CEPH_RADOS_API
int rados_aio_watch(rados_ioctx_t io
, const char *o
,
2514 rados_completion_t completion
, uint64_t *handle
,
2515 rados_watchcb2_t watchcb
,
2516 rados_watcherrcb_t watcherrcb
,
2520 * Asynchronous register an interest in an object
2522 * A watch operation registers the client as being interested in
2523 * notifications on an object. OSDs keep track of watches on
2524 * persistent storage, so they are preserved across cluster changes by
2525 * the normal recovery process. If the client loses its connection to
2526 * the primary OSD for a watched object, the watch will be removed
2527 * after the number of seconds that configured in timeout parameter.
2528 * Watches are automatically reestablished when a new
2529 * connection is made, or a placement group switches OSDs.
2531 * @param io the pool the object is in
2532 * @param o the object to watch
2533 * @param completion what to do when operation has been attempted
2534 * @param handle where to store the internal id assigned to this watch
2535 * @param watchcb what to do when a notify is received on this object
2536 * @param watcherrcb what to do when the watch session encounters an error
2537 * @param timeout how many seconds the connection will keep after disconnection
2538 * @param arg opaque value to pass to the callback
2539 * @returns 0 on success, negative error code on failure
2541 CEPH_RADOS_API
int rados_aio_watch2(rados_ioctx_t io
, const char *o
,
2542 rados_completion_t completion
, uint64_t *handle
,
2543 rados_watchcb2_t watchcb
,
2544 rados_watcherrcb_t watcherrcb
,
2549 * Check on the status of a watch
2551 * Return the number of milliseconds since the watch was last confirmed.
2552 * Or, if there has been an error, return that.
2554 * If there is an error, the watch is no longer valid, and should be
2555 * destroyed with rados_unwatch2(). The the user is still interested
2556 * in the object, a new watch should be created with rados_watch2().
2558 * @param io the pool the object is in
2559 * @param cookie the watch handle
2560 * @returns ms since last confirmed on success, negative error code on failure
2562 CEPH_RADOS_API
int rados_watch_check(rados_ioctx_t io
, uint64_t cookie
);
2565 * Unregister an interest in an object
2567 * Once this completes, no more notifies will be sent to us for this
2568 * watch. This should be called to clean up unneeded watchers.
2570 * @param io the pool the object is in
2571 * @param o the name of the watched object (ignored)
2572 * @param cookie which watch to unregister
2573 * @returns 0 on success, negative error code on failure
2575 CEPH_RADOS_API
int rados_unwatch(rados_ioctx_t io
, const char *o
, uint64_t cookie
)
2576 __attribute__((deprecated
));
2579 * Unregister an interest in an object
2581 * Once this completes, no more notifies will be sent to us for this
2582 * watch. This should be called to clean up unneeded watchers.
2584 * @param io the pool the object is in
2585 * @param cookie which watch to unregister
2586 * @returns 0 on success, negative error code on failure
2588 CEPH_RADOS_API
int rados_unwatch2(rados_ioctx_t io
, uint64_t cookie
);
2591 * Asynchronous unregister an interest in an object
2593 * Once this completes, no more notifies will be sent to us for this
2594 * watch. This should be called to clean up unneeded watchers.
2596 * @param io the pool the object is in
2597 * @param completion what to do when operation has been attempted
2598 * @param cookie which watch to unregister
2599 * @returns 0 on success, negative error code on failure
2601 CEPH_RADOS_API
int rados_aio_unwatch(rados_ioctx_t io
, uint64_t cookie
,
2602 rados_completion_t completion
);
2605 * Sychronously notify watchers of an object
2607 * This blocks until all watchers of the object have received and
2608 * reacted to the notify, or a timeout is reached.
2610 * @note BUG: the timeout is not changeable via the C API
2611 * @note BUG: the bufferlist is inaccessible in a rados_watchcb_t
2613 * @param io the pool the object is in
2614 * @param o the name of the object
2615 * @param ver obsolete - just pass zero
2616 * @param buf data to send to watchers
2617 * @param buf_len length of buf in bytes
2618 * @returns 0 on success, negative error code on failure
2620 CEPH_RADOS_API
int rados_notify(rados_ioctx_t io
, const char *o
, uint64_t ver
,
2621 const char *buf
, int buf_len
)
2622 __attribute__((deprecated
));
2625 * Sychronously notify watchers of an object
2627 * This blocks until all watchers of the object have received and
2628 * reacted to the notify, or a timeout is reached.
2630 * The reply buffer is optional. If specified, the client will get
2631 * back an encoded buffer that includes the ids of the clients that
2632 * acknowledged the notify as well as their notify ack payloads (if
2633 * any). Clients that timed out are not included. Even clients that
2634 * do not include a notify ack payload are included in the list but
2635 * have a 0-length payload associated with them. The format:
2639 * le64 gid global id for the client (for client.1234 that's 1234)
2640 * le64 cookie cookie for the client
2641 * le32 buflen length of reply message buffer
2642 * u8 * buflen payload
2646 * le64 gid global id for the client
2647 * le64 cookie cookie for the client
2650 * Note: There may be multiple instances of the same gid if there are
2651 * multiple watchers registered via the same client.
2653 * Note: The buffer must be released with rados_buffer_free() when the
2654 * user is done with it.
2656 * Note: Since the result buffer includes clients that time out, it
2657 * will be set even when rados_notify() returns an error code (like
2660 * @param io the pool the object is in
2661 * @param completion what to do when operation has been attempted
2662 * @param o the name of the object
2663 * @param buf data to send to watchers
2664 * @param buf_len length of buf in bytes
2665 * @param timeout_ms notify timeout (in ms)
2666 * @param reply_buffer pointer to reply buffer pointer (free with rados_buffer_free)
2667 * @param reply_buffer_len pointer to size of reply buffer
2668 * @returns 0 on success, negative error code on failure
2670 CEPH_RADOS_API
int rados_aio_notify(rados_ioctx_t io
, const char *o
,
2671 rados_completion_t completion
,
2672 const char *buf
, int buf_len
,
2673 uint64_t timeout_ms
, char **reply_buffer
,
2674 size_t *reply_buffer_len
);
2675 CEPH_RADOS_API
int rados_notify2(rados_ioctx_t io
, const char *o
,
2676 const char *buf
, int buf_len
,
2677 uint64_t timeout_ms
,
2678 char **reply_buffer
, size_t *reply_buffer_len
);
2681 * Decode a notify response
2683 * Decode a notify response (from rados_aio_notify() call) into acks and
2686 * @param reply_buffer buffer from rados_aio_notify() call
2687 * @param reply_buffer_len reply_buffer length
2688 * @param acks pointer to struct notify_ack_t pointer
2689 * @param nr_acks pointer to ack count
2690 * @param timeouts pointer to notify_timeout_t pointer
2691 * @param nr_timeouts pointer to timeout count
2692 * @returns 0 on success
2694 CEPH_RADOS_API
int rados_decode_notify_response(char *reply_buffer
, size_t reply_buffer_len
,
2695 struct notify_ack_t
**acks
, size_t *nr_acks
,
2696 struct notify_timeout_t
**timeouts
, size_t *nr_timeouts
);
2699 * Free notify allocated buffer
2701 * Release memory allocated by rados_decode_notify_response() call
2703 * @param acks notify_ack_t struct (from rados_decode_notify_response())
2704 * @param nr_acks ack count
2705 * @param timeouts notify_timeout_t struct (from rados_decode_notify_response())
2707 CEPH_RADOS_API
void rados_free_notify_response(struct notify_ack_t
*acks
, size_t nr_acks
,
2708 struct notify_timeout_t
*timeouts
);
2711 * Acknolwedge receipt of a notify
2713 * @param io the pool the object is in
2714 * @param o the name of the object
2715 * @param notify_id the notify_id we got on the watchcb2_t callback
2716 * @param cookie the watcher handle
2717 * @param buf payload to return to notifier (optional)
2718 * @param buf_len payload length
2719 * @returns 0 on success
2721 CEPH_RADOS_API
int rados_notify_ack(rados_ioctx_t io
, const char *o
,
2722 uint64_t notify_id
, uint64_t cookie
,
2723 const char *buf
, int buf_len
);
2726 * Flush watch/notify callbacks
2728 * This call will block until all pending watch/notify callbacks have
2729 * been executed and the queue is empty. It should usually be called
2730 * after shutting down any watches before shutting down the ioctx or
2731 * librados to ensure that any callbacks do not misuse the ioctx (for
2732 * example by calling rados_notify_ack after the ioctx has been
2735 * @param cluster the cluster handle
2737 CEPH_RADOS_API
int rados_watch_flush(rados_t cluster
);
2739 * Flush watch/notify callbacks
2741 * This call will be nonblock, and the completion will be called
2742 * until all pending watch/notify callbacks have been executed and
2743 * the queue is empty. It should usually be called after shutting
2744 * down any watches before shutting down the ioctx or
2745 * librados to ensure that any callbacks do not misuse the ioctx (for
2746 * example by calling rados_notify_ack after the ioctx has been
2749 * @param cluster the cluster handle
2750 * @param completion what to do when operation has been attempted
2752 CEPH_RADOS_API
int rados_aio_watch_flush(rados_t cluster
, rados_completion_t completion
);
2754 /** @} Watch/Notify */
2757 * Pin an object in the cache tier
2759 * When an object is pinned in the cache tier, it stays in the cache
2760 * tier, and won't be flushed out.
2762 * @param io the pool the object is in
2763 * @param o the object id
2764 * @returns 0 on success, negative error code on failure
2766 CEPH_RADOS_API
int rados_cache_pin(rados_ioctx_t io
, const char *o
);
2769 * Unpin an object in the cache tier
2771 * After an object is unpinned in the cache tier, it can be flushed out
2773 * @param io the pool the object is in
2774 * @param o the object id
2775 * @returns 0 on success, negative error code on failure
2777 CEPH_RADOS_API
int rados_cache_unpin(rados_ioctx_t io
, const char *o
);
2786 * Set allocation hint for an object
2788 * This is an advisory operation, it will always succeed (as if it was
2789 * submitted with a LIBRADOS_OP_FLAG_FAILOK flag set) and is not
2790 * guaranteed to do anything on the backend.
2792 * @param io the pool the object is in
2793 * @param o the name of the object
2794 * @param expected_object_size expected size of the object, in bytes
2795 * @param expected_write_size expected size of writes to the object, in bytes
2796 * @returns 0 on success, negative error code on failure
2798 CEPH_RADOS_API
int rados_set_alloc_hint(rados_ioctx_t io
, const char *o
,
2799 uint64_t expected_object_size
,
2800 uint64_t expected_write_size
);
2803 * Set allocation hint for an object
2805 * This is an advisory operation, it will always succeed (as if it was
2806 * submitted with a LIBRADOS_OP_FLAG_FAILOK flag set) and is not
2807 * guaranteed to do anything on the backend.
2809 * @param io the pool the object is in
2810 * @param o the name of the object
2811 * @param expected_object_size expected size of the object, in bytes
2812 * @param expected_write_size expected size of writes to the object, in bytes
2813 * @param flags hints about future IO patterns
2814 * @returns 0 on success, negative error code on failure
2816 CEPH_RADOS_API
int rados_set_alloc_hint2(rados_ioctx_t io
, const char *o
,
2817 uint64_t expected_object_size
,
2818 uint64_t expected_write_size
,
2824 * @name Object Operations
2826 * A single rados operation can do multiple operations on one object
2827 * atomically. The whole operation will succeed or fail, and no partial
2828 * results will be visible.
2830 * Operations may be either reads, which can return data, or writes,
2831 * which cannot. The effects of writes are applied and visible all at
2832 * once, so an operation that sets an xattr and then checks its value
2833 * will not see the updated value.
2839 * Create a new rados_write_op_t write operation. This will store all actions
2840 * to be performed atomically. You must call rados_release_write_op when you are
2843 * @note the ownership of a write operartion is passed to the function
2844 * performing the operation, so the same instance of @c rados_write_op_t
2845 * cannot be used again after being performed.
2847 * @returns non-NULL on success, NULL on memory allocation error.
2849 CEPH_RADOS_API rados_write_op_t
rados_create_write_op(void);
2852 * Free a rados_write_op_t, must be called when you're done with it.
2853 * @param write_op operation to deallocate, created with rados_create_write_op
2855 CEPH_RADOS_API
void rados_release_write_op(rados_write_op_t write_op
);
2858 * Set flags for the last operation added to this write_op.
2859 * At least one op must have been added to the write_op.
2860 * @param write_op operation to add this action to
2861 * @param flags see librados.h constants beginning with LIBRADOS_OP_FLAG
2863 CEPH_RADOS_API
void rados_write_op_set_flags(rados_write_op_t write_op
,
2867 * Ensure that the object exists before writing
2868 * @param write_op operation to add this action to
2870 CEPH_RADOS_API
void rados_write_op_assert_exists(rados_write_op_t write_op
);
2873 * Ensure that the object exists and that its internal version
2874 * number is equal to "ver" before writing. "ver" should be a
2875 * version number previously obtained with rados_get_last_version().
2876 * - If the object's version is greater than the asserted version
2877 * then rados_write_op_operate will return -ERANGE instead of
2879 * - If the object's version is less than the asserted version
2880 * then rados_write_op_operate will return -EOVERFLOW instead
2881 * of executing the op.
2882 * @param write_op operation to add this action to
2883 * @param ver object version number
2885 CEPH_RADOS_API
void rados_write_op_assert_version(rados_write_op_t write_op
, uint64_t ver
);
2888 * Ensure that given object range (extent) satisfies comparison.
2890 * @param write_op operation to add this action to
2891 * @param cmp_buf buffer containing bytes to be compared with object contents
2892 * @param cmp_len length to compare and size of @c cmp_buf in bytes
2893 * @param off object byte offset at which to start the comparison
2894 * @param prval returned result of comparison, 0 on success, negative error code
2895 * on failure, (-MAX_ERRNO - mismatch_off) on mismatch
2897 CEPH_RADOS_API
void rados_write_op_cmpext(rados_write_op_t write_op
,
2898 const char *cmp_buf
,
2904 * Ensure that given xattr satisfies comparison.
2905 * If the comparison is not satisfied, the return code of the
2906 * operation will be -ECANCELED
2907 * @param write_op operation to add this action to
2908 * @param name name of the xattr to look up
2909 * @param comparison_operator currently undocumented, look for
2910 * LIBRADOS_CMPXATTR_OP_EQ in librados.h
2911 * @param value buffer to compare actual xattr value to
2912 * @param value_len length of buffer to compare actual xattr value to
2914 CEPH_RADOS_API
void rados_write_op_cmpxattr(rados_write_op_t write_op
,
2916 uint8_t comparison_operator
,
2921 * Ensure that the an omap value satisfies a comparison,
2922 * with the supplied value on the right hand side (i.e.
2923 * for OP_LT, the comparison is actual_value < value.
2925 * @param write_op operation to add this action to
2926 * @param key which omap value to compare
2927 * @param comparison_operator one of LIBRADOS_CMPXATTR_OP_EQ,
2928 LIBRADOS_CMPXATTR_OP_LT, or LIBRADOS_CMPXATTR_OP_GT
2929 * @param val value to compare with
2930 * @param val_len length of value in bytes
2931 * @param prval where to store the return value from this action
2933 CEPH_RADOS_API
void rados_write_op_omap_cmp(rados_write_op_t write_op
,
2935 uint8_t comparison_operator
,
2941 * Ensure that the an omap value satisfies a comparison,
2942 * with the supplied value on the right hand side (i.e.
2943 * for OP_LT, the comparison is actual_value < value.
2945 * @param write_op operation to add this action to
2946 * @param key which omap value to compare
2947 * @param comparison_operator one of LIBRADOS_CMPXATTR_OP_EQ,
2948 LIBRADOS_CMPXATTR_OP_LT, or LIBRADOS_CMPXATTR_OP_GT
2949 * @param val value to compare with
2950 * @param key_len length of key in bytes
2951 * @param val_len length of value in bytes
2952 * @param prval where to store the return value from this action
2954 CEPH_RADOS_API
void rados_write_op_omap_cmp2(rados_write_op_t write_op
,
2956 uint8_t comparison_operator
,
2964 * @param write_op operation to add this action to
2965 * @param name name of the xattr
2966 * @param value buffer to set xattr to
2967 * @param value_len length of buffer to set xattr to
2969 CEPH_RADOS_API
void rados_write_op_setxattr(rados_write_op_t write_op
,
2976 * @param write_op operation to add this action to
2977 * @param name name of the xattr to remove
2979 CEPH_RADOS_API
void rados_write_op_rmxattr(rados_write_op_t write_op
,
2984 * @param write_op operation to add this action to
2985 * @param exclusive set to either LIBRADOS_CREATE_EXCLUSIVE or
2986 LIBRADOS_CREATE_IDEMPOTENT
2987 * will error if the object already exists.
2988 * @param category category string (DEPRECATED, HAS NO EFFECT)
2990 CEPH_RADOS_API
void rados_write_op_create(rados_write_op_t write_op
,
2992 const char* category
);
2996 * @param write_op operation to add this action to
2997 * @param offset offset to write to
2998 * @param buffer bytes to write
2999 * @param len length of buffer
3001 CEPH_RADOS_API
void rados_write_op_write(rados_write_op_t write_op
,
3007 * Write whole object, atomically replacing it.
3008 * @param write_op operation to add this action to
3009 * @param buffer bytes to write
3010 * @param len length of buffer
3012 CEPH_RADOS_API
void rados_write_op_write_full(rados_write_op_t write_op
,
3017 * Write the same buffer multiple times
3018 * @param write_op operation to add this action to
3019 * @param buffer bytes to write
3020 * @param data_len length of buffer
3021 * @param write_len total number of bytes to write, as a multiple of @c data_len
3022 * @param offset offset to write to
3024 CEPH_RADOS_API
void rados_write_op_writesame(rados_write_op_t write_op
,
3031 * Append to end of object.
3032 * @param write_op operation to add this action to
3033 * @param buffer bytes to write
3034 * @param len length of buffer
3036 CEPH_RADOS_API
void rados_write_op_append(rados_write_op_t write_op
,
3041 * @param write_op operation to add this action to
3043 CEPH_RADOS_API
void rados_write_op_remove(rados_write_op_t write_op
);
3046 * Truncate an object
3047 * @param write_op operation to add this action to
3048 * @param offset Offset to truncate to
3050 CEPH_RADOS_API
void rados_write_op_truncate(rados_write_op_t write_op
,
3054 * Zero part of an object
3055 * @param write_op operation to add this action to
3056 * @param offset Offset to zero
3057 * @param len length to zero
3059 CEPH_RADOS_API
void rados_write_op_zero(rados_write_op_t write_op
,
3064 * Execute an OSD class method on an object
3065 * See rados_exec() for general description.
3067 * @param write_op operation to add this action to
3068 * @param cls the name of the class
3069 * @param method the name of the method
3070 * @param in_buf where to find input
3071 * @param in_len length of in_buf in bytes
3072 * @param prval where to store the return value from the method
3074 CEPH_RADOS_API
void rados_write_op_exec(rados_write_op_t write_op
,
3082 * Set key/value pairs on an object
3084 * @param write_op operation to add this action to
3085 * @param keys array of null-terminated char arrays representing keys to set
3086 * @param vals array of pointers to values to set
3087 * @param lens array of lengths corresponding to each value
3088 * @param num number of key/value pairs to set
3090 CEPH_RADOS_API
void rados_write_op_omap_set(rados_write_op_t write_op
,
3091 char const* const* keys
,
3092 char const* const* vals
,
3097 * Set key/value pairs on an object
3099 * @param write_op operation to add this action to
3100 * @param keys array of null-terminated char arrays representing keys to set
3101 * @param vals array of pointers to values to set
3102 * @param key_lens array of lengths corresponding to each key
3103 * @param val_lens array of lengths corresponding to each value
3104 * @param num number of key/value pairs to set
3106 CEPH_RADOS_API
void rados_write_op_omap_set2(rados_write_op_t write_op
,
3107 char const* const* keys
,
3108 char const* const* vals
,
3109 const size_t *key_lens
,
3110 const size_t *val_lens
,
3114 * Remove key/value pairs from an object
3116 * @param write_op operation to add this action to
3117 * @param keys array of null-terminated char arrays representing keys to remove
3118 * @param keys_len number of key/value pairs to remove
3120 CEPH_RADOS_API
void rados_write_op_omap_rm_keys(rados_write_op_t write_op
,
3121 char const* const* keys
,
3125 * Remove key/value pairs from an object
3127 * @param write_op operation to add this action to
3128 * @param keys array of char arrays representing keys to remove
3129 * @param key_lens array of size_t values representing length of each key
3130 * @param keys_len number of key/value pairs to remove
3132 CEPH_RADOS_API
void rados_write_op_omap_rm_keys2(rados_write_op_t write_op
,
3133 char const* const* keys
,
3134 const size_t* key_lens
,
3139 * Remove key/value pairs from an object whose keys are in the range
3140 * [key_begin, key_end)
3142 * @param write_op operation to add this action to
3143 * @param key_begin the lower bound of the key range to remove
3144 * @param key_begin_len length of key_begin
3145 * @param key_end the upper bound of the key range to remove
3146 * @param key_end_len length of key_end
3148 CEPH_RADOS_API
void rados_write_op_omap_rm_range2(rados_write_op_t write_op
,
3149 const char *key_begin
,
3150 size_t key_begin_len
,
3151 const char *key_end
,
3152 size_t key_end_len
);
3155 * Remove all key/value pairs from an object
3157 * @param write_op operation to add this action to
3159 CEPH_RADOS_API
void rados_write_op_omap_clear(rados_write_op_t write_op
);
3162 * Set allocation hint for an object
3164 * @param write_op operation to add this action to
3165 * @param expected_object_size expected size of the object, in bytes
3166 * @param expected_write_size expected size of writes to the object, in bytes
3168 CEPH_RADOS_API
void rados_write_op_set_alloc_hint(rados_write_op_t write_op
,
3169 uint64_t expected_object_size
,
3170 uint64_t expected_write_size
);
3173 * Set allocation hint for an object
3175 * @param write_op operation to add this action to
3176 * @param expected_object_size expected size of the object, in bytes
3177 * @param expected_write_size expected size of writes to the object, in bytes
3178 * @param flags hints about future IO patterns
3180 CEPH_RADOS_API
void rados_write_op_set_alloc_hint2(rados_write_op_t write_op
,
3181 uint64_t expected_object_size
,
3182 uint64_t expected_write_size
,
3186 * Perform a write operation synchronously
3187 * @param write_op operation to perform
3188 * @param io the ioctx that the object is in
3189 * @param oid the object id
3190 * @param mtime the time to set the mtime to, NULL for the current time
3191 * @param flags flags to apply to the entire operation (LIBRADOS_OPERATION_*)
3193 CEPH_RADOS_API
int rados_write_op_operate(rados_write_op_t write_op
,
3199 * Perform a write operation synchronously
3200 * @param write_op operation to perform
3201 * @param io the ioctx that the object is in
3202 * @param oid the object id
3203 * @param mtime the time to set the mtime to, NULL for the current time
3204 * @param flags flags to apply to the entire operation (LIBRADOS_OPERATION_*)
3207 CEPH_RADOS_API
int rados_write_op_operate2(rados_write_op_t write_op
,
3210 struct timespec
*mtime
,
3214 * Perform a write operation asynchronously
3215 * @param write_op operation to perform
3216 * @param io the ioctx that the object is in
3217 * @param completion what to do when operation has been attempted
3218 * @param oid the object id
3219 * @param mtime the time to set the mtime to, NULL for the current time
3220 * @param flags flags to apply to the entire operation (LIBRADOS_OPERATION_*)
3222 CEPH_RADOS_API
int rados_aio_write_op_operate(rados_write_op_t write_op
,
3224 rados_completion_t completion
,
3230 * Perform a write operation asynchronously
3231 * @param write_op operation to perform
3232 * @param io the ioctx that the object is in
3233 * @param completion what to do when operation has been attempted
3234 * @param oid the object id
3235 * @param mtime the time to set the mtime to, NULL for the current time
3236 * @param flags flags to apply to the entire operation (LIBRADOS_OPERATION_*)
3238 CEPH_RADOS_API
int rados_aio_write_op_operate2(rados_write_op_t write_op
,
3240 rados_completion_t completion
,
3242 struct timespec
*mtime
,
3246 * Create a new rados_read_op_t read operation. This will store all
3247 * actions to be performed atomically. You must call
3248 * rados_release_read_op when you are finished with it (after it
3249 * completes, or you decide not to send it in the first place).
3251 * @note the ownership of a read operartion is passed to the function
3252 * performing the operation, so the same instance of @c rados_read_op_t
3253 * cannot be used again after being performed.
3255 * @returns non-NULL on success, NULL on memory allocation error.
3257 CEPH_RADOS_API rados_read_op_t
rados_create_read_op(void);
3260 * Free a rados_read_op_t, must be called when you're done with it.
3261 * @param read_op operation to deallocate, created with rados_create_read_op
3263 CEPH_RADOS_API
void rados_release_read_op(rados_read_op_t read_op
);
3266 * Set flags for the last operation added to this read_op.
3267 * At least one op must have been added to the read_op.
3268 * @param read_op operation to add this action to
3269 * @param flags see librados.h constants beginning with LIBRADOS_OP_FLAG
3271 CEPH_RADOS_API
void rados_read_op_set_flags(rados_read_op_t read_op
, int flags
);
3274 * Ensure that the object exists before reading
3275 * @param read_op operation to add this action to
3277 CEPH_RADOS_API
void rados_read_op_assert_exists(rados_read_op_t read_op
);
3280 * Ensure that the object exists and that its internal version
3281 * number is equal to "ver" before reading. "ver" should be a
3282 * version number previously obtained with rados_get_last_version().
3283 * - If the object's version is greater than the asserted version
3284 * then rados_read_op_operate will return -ERANGE instead of
3286 * - If the object's version is less than the asserted version
3287 * then rados_read_op_operate will return -EOVERFLOW instead
3288 * of executing the op.
3289 * @param read_op operation to add this action to
3290 * @param ver object version number
3292 CEPH_RADOS_API
void rados_read_op_assert_version(rados_read_op_t read_op
, uint64_t ver
);
3295 * Ensure that given object range (extent) satisfies comparison.
3297 * @param read_op operation to add this action to
3298 * @param cmp_buf buffer containing bytes to be compared with object contents
3299 * @param cmp_len length to compare and size of @c cmp_buf in bytes
3300 * @param off object byte offset at which to start the comparison
3301 * @param prval returned result of comparison, 0 on success, negative error code
3302 * on failure, (-MAX_ERRNO - mismatch_off) on mismatch
3304 CEPH_RADOS_API
void rados_read_op_cmpext(rados_read_op_t read_op
,
3305 const char *cmp_buf
,
3311 * Ensure that the an xattr satisfies a comparison
3312 * If the comparison is not satisfied, the return code of the
3313 * operation will be -ECANCELED
3314 * @param read_op operation to add this action to
3315 * @param name name of the xattr to look up
3316 * @param comparison_operator currently undocumented, look for
3317 * LIBRADOS_CMPXATTR_OP_EQ in librados.h
3318 * @param value buffer to compare actual xattr value to
3319 * @param value_len length of buffer to compare actual xattr value to
3321 CEPH_RADOS_API
void rados_read_op_cmpxattr(rados_read_op_t read_op
,
3323 uint8_t comparison_operator
,
3328 * Start iterating over xattrs on an object.
3330 * @param read_op operation to add this action to
3331 * @param iter where to store the iterator
3332 * @param prval where to store the return value of this action
3334 CEPH_RADOS_API
void rados_read_op_getxattrs(rados_read_op_t read_op
,
3335 rados_xattrs_iter_t
*iter
,
3339 * Ensure that the an omap value satisfies a comparison,
3340 * with the supplied value on the right hand side (i.e.
3341 * for OP_LT, the comparison is actual_value < value.
3343 * @param read_op operation to add this action to
3344 * @param key which omap value to compare
3345 * @param comparison_operator one of LIBRADOS_CMPXATTR_OP_EQ,
3346 LIBRADOS_CMPXATTR_OP_LT, or LIBRADOS_CMPXATTR_OP_GT
3347 * @param val value to compare with
3348 * @param val_len length of value in bytes
3349 * @param prval where to store the return value from this action
3351 CEPH_RADOS_API
void rados_read_op_omap_cmp(rados_read_op_t read_op
,
3353 uint8_t comparison_operator
,
3359 * Ensure that the an omap value satisfies a comparison,
3360 * with the supplied value on the right hand side (i.e.
3361 * for OP_LT, the comparison is actual_value < value.
3363 * @param read_op operation to add this action to
3364 * @param key which omap value to compare
3365 * @param comparison_operator one of LIBRADOS_CMPXATTR_OP_EQ,
3366 LIBRADOS_CMPXATTR_OP_LT, or LIBRADOS_CMPXATTR_OP_GT
3367 * @param val value to compare with
3368 * @param key_len length of key in bytes
3369 * @param val_len length of value in bytes
3370 * @param prval where to store the return value from this action
3372 CEPH_RADOS_API
void rados_read_op_omap_cmp2(rados_read_op_t read_op
,
3374 uint8_t comparison_operator
,
3381 * Get object size and mtime
3382 * @param read_op operation to add this action to
3383 * @param psize where to store object size
3384 * @param pmtime where to store modification time
3385 * @param prval where to store the return value of this action
3387 CEPH_RADOS_API
void rados_read_op_stat(rados_read_op_t read_op
,
3392 CEPH_RADOS_API
void rados_read_op_stat2(rados_read_op_t read_op
,
3394 struct timespec
*pmtime
,
3397 * Read bytes from offset into buffer.
3399 * prlen will be filled with the number of bytes read if successful.
3400 * A short read can only occur if the read reaches the end of the
3403 * @param read_op operation to add this action to
3404 * @param offset offset to read from
3405 * @param len length of buffer
3406 * @param buffer where to put the data
3407 * @param bytes_read where to store the number of bytes read by this action
3408 * @param prval where to store the return value of this action
3410 CEPH_RADOS_API
void rados_read_op_read(rados_read_op_t read_op
,
3418 * Compute checksum from object data
3420 * @param read_op operation to add this action to
3421 * @param type the checksum algorithm to utilize
3422 * @param init_value the init value for the algorithm
3423 * @param init_value_len the length of the init value
3424 * @param offset the offset to start checksumming in the object
3425 * @param len the number of bytes to checksum
3426 * @param chunk_size optional length-aligned chunk size for checksums
3427 * @param pchecksum where to store the checksum result for this action
3428 * @param checksum_len the number of bytes available for the result
3429 * @param prval where to store the return value for this action
3431 CEPH_RADOS_API
void rados_read_op_checksum(rados_read_op_t read_op
,
3432 rados_checksum_type_t type
,
3433 const char *init_value
,
3434 size_t init_value_len
,
3435 uint64_t offset
, size_t len
,
3436 size_t chunk_size
, char *pchecksum
,
3437 size_t checksum_len
, int *prval
);
3440 * Execute an OSD class method on an object
3441 * See rados_exec() for general description.
3443 * The output buffer is allocated on the heap; the caller is
3444 * expected to release that memory with rados_buffer_free(). The
3445 * buffer and length pointers can all be NULL, in which case they are
3448 * @param read_op operation to add this action to
3449 * @param cls the name of the class
3450 * @param method the name of the method
3451 * @param in_buf where to find input
3452 * @param in_len length of in_buf in bytes
3453 * @param out_buf where to put librados-allocated output buffer
3454 * @param out_len length of out_buf in bytes
3455 * @param prval where to store the return value from the method
3457 CEPH_RADOS_API
void rados_read_op_exec(rados_read_op_t read_op
,
3467 * Execute an OSD class method on an object
3468 * See rados_exec() for general description.
3470 * If the output buffer is too small, prval will
3471 * be set to -ERANGE and used_len will be 0.
3473 * @param read_op operation to add this action to
3474 * @param cls the name of the class
3475 * @param method the name of the method
3476 * @param in_buf where to find input
3477 * @param in_len length of in_buf in bytes
3478 * @param out_buf user-provided buffer to read into
3479 * @param out_len length of out_buf in bytes
3480 * @param used_len where to store the number of bytes read into out_buf
3481 * @param prval where to store the return value from the method
3483 CEPH_RADOS_API
void rados_read_op_exec_user_buf(rados_read_op_t read_op
,
3494 * Start iterating over key/value pairs on an object.
3496 * They will be returned sorted by key.
3498 * @param read_op operation to add this action to
3499 * @param start_after list keys starting after start_after
3500 * @param filter_prefix list only keys beginning with filter_prefix
3501 * @param max_return list no more than max_return key/value pairs
3502 * @param iter where to store the iterator
3503 * @param prval where to store the return value from this action
3505 CEPH_RADOS_API
void rados_read_op_omap_get_vals(rados_read_op_t read_op
,
3506 const char *start_after
,
3507 const char *filter_prefix
,
3508 uint64_t max_return
,
3509 rados_omap_iter_t
*iter
,
3511 __attribute__((deprecated
)); /* use v2 below */
3514 * Start iterating over key/value pairs on an object.
3516 * They will be returned sorted by key.
3518 * @param read_op operation to add this action to
3519 * @param start_after list keys starting after start_after
3520 * @param filter_prefix list only keys beginning with filter_prefix
3521 * @param max_return list no more than max_return key/value pairs
3522 * @param iter where to store the iterator
3523 * @param pmore flag indicating whether there are more keys to fetch
3524 * @param prval where to store the return value from this action
3526 CEPH_RADOS_API
void rados_read_op_omap_get_vals2(rados_read_op_t read_op
,
3527 const char *start_after
,
3528 const char *filter_prefix
,
3529 uint64_t max_return
,
3530 rados_omap_iter_t
*iter
,
3531 unsigned char *pmore
,
3535 * Start iterating over keys on an object.
3537 * They will be returned sorted by key, and the iterator
3538 * will fill in NULL for all values if specified.
3540 * @param read_op operation to add this action to
3541 * @param start_after list keys starting after start_after
3542 * @param max_return list no more than max_return keys
3543 * @param iter where to store the iterator
3544 * @param prval where to store the return value from this action
3546 CEPH_RADOS_API
void rados_read_op_omap_get_keys(rados_read_op_t read_op
,
3547 const char *start_after
,
3548 uint64_t max_return
,
3549 rados_omap_iter_t
*iter
,
3551 __attribute__((deprecated
)); /* use v2 below */
3554 * Start iterating over keys on an object.
3556 * They will be returned sorted by key, and the iterator
3557 * will fill in NULL for all values if specified.
3559 * @param read_op operation to add this action to
3560 * @param start_after list keys starting after start_after
3561 * @param max_return list no more than max_return keys
3562 * @param iter where to store the iterator
3563 * @param pmore flag indicating whether there are more keys to fetch
3564 * @param prval where to store the return value from this action
3566 CEPH_RADOS_API
void rados_read_op_omap_get_keys2(rados_read_op_t read_op
,
3567 const char *start_after
,
3568 uint64_t max_return
,
3569 rados_omap_iter_t
*iter
,
3570 unsigned char *pmore
,
3574 * Start iterating over specific key/value pairs
3576 * They will be returned sorted by key.
3578 * @param read_op operation to add this action to
3579 * @param keys array of pointers to null-terminated keys to get
3580 * @param keys_len the number of strings in keys
3581 * @param iter where to store the iterator
3582 * @param prval where to store the return value from this action
3584 CEPH_RADOS_API
void rados_read_op_omap_get_vals_by_keys(rados_read_op_t read_op
,
3585 char const* const* keys
,
3587 rados_omap_iter_t
*iter
,
3591 * Start iterating over specific key/value pairs
3593 * They will be returned sorted by key.
3595 * @param read_op operation to add this action to
3596 * @param keys array of pointers to keys to get
3597 * @param num_keys the number of strings in keys
3598 * @param key_lens array of size_t's describing each key len (in bytes)
3599 * @param iter where to store the iterator
3600 * @param prval where to store the return value from this action
3602 CEPH_RADOS_API
void rados_read_op_omap_get_vals_by_keys2(rados_read_op_t read_op
,
3603 char const* const* keys
,
3605 const size_t* key_lens
,
3606 rados_omap_iter_t
*iter
,
3610 * Perform a read operation synchronously
3611 * @param read_op operation to perform
3612 * @param io the ioctx that the object is in
3613 * @param oid the object id
3614 * @param flags flags to apply to the entire operation (LIBRADOS_OPERATION_*)
3616 CEPH_RADOS_API
int rados_read_op_operate(rados_read_op_t read_op
,
3622 * Perform a read operation asynchronously
3623 * @param read_op operation to perform
3624 * @param io the ioctx that the object is in
3625 * @param completion what to do when operation has been attempted
3626 * @param oid the object id
3627 * @param flags flags to apply to the entire operation (LIBRADOS_OPERATION_*)
3629 CEPH_RADOS_API
int rados_aio_read_op_operate(rados_read_op_t read_op
,
3631 rados_completion_t completion
,
3635 /** @} Object Operations */
3638 * Take an exclusive lock on an object.
3640 * @param io the context to operate in
3641 * @param oid the name of the object
3642 * @param name the name of the lock
3643 * @param cookie user-defined identifier for this instance of the lock
3644 * @param desc user-defined lock description
3645 * @param duration the duration of the lock. Set to NULL for infinite duration.
3646 * @param flags lock flags
3647 * @returns 0 on success, negative error code on failure
3648 * @returns -EBUSY if the lock is already held by another (client, cookie) pair
3649 * @returns -EEXIST if the lock is already held by the same (client, cookie) pair
3651 CEPH_RADOS_API
int rados_lock_exclusive(rados_ioctx_t io
, const char * oid
,
3652 const char * name
, const char * cookie
,
3654 struct timeval
* duration
,
3658 * Take a shared lock on an object.
3660 * @param io the context to operate in
3661 * @param o the name of the object
3662 * @param name the name of the lock
3663 * @param cookie user-defined identifier for this instance of the lock
3664 * @param tag The tag of the lock
3665 * @param desc user-defined lock description
3666 * @param duration the duration of the lock. Set to NULL for infinite duration.
3667 * @param flags lock flags
3668 * @returns 0 on success, negative error code on failure
3669 * @returns -EBUSY if the lock is already held by another (client, cookie) pair
3670 * @returns -EEXIST if the lock is already held by the same (client, cookie) pair
3672 CEPH_RADOS_API
int rados_lock_shared(rados_ioctx_t io
, const char * o
,
3673 const char * name
, const char * cookie
,
3674 const char * tag
, const char * desc
,
3675 struct timeval
* duration
, uint8_t flags
);
3678 * Release a shared or exclusive lock on an object.
3680 * @param io the context to operate in
3681 * @param o the name of the object
3682 * @param name the name of the lock
3683 * @param cookie user-defined identifier for the instance of the lock
3684 * @returns 0 on success, negative error code on failure
3685 * @returns -ENOENT if the lock is not held by the specified (client, cookie) pair
3687 CEPH_RADOS_API
int rados_unlock(rados_ioctx_t io
, const char *o
,
3688 const char *name
, const char *cookie
);
3691 * Asynchronous release a shared or exclusive lock on an object.
3693 * @param io the context to operate in
3694 * @param o the name of the object
3695 * @param name the name of the lock
3696 * @param cookie user-defined identifier for the instance of the lock
3697 * @param completion what to do when operation has been attempted
3698 * @returns 0 on success, negative error code on failure
3700 CEPH_RADOS_API
int rados_aio_unlock(rados_ioctx_t io
, const char *o
,
3701 const char *name
, const char *cookie
,
3702 rados_completion_t completion
);
3705 * List clients that have locked the named object lock and information about
3708 * The number of bytes required in each buffer is put in the
3709 * corresponding size out parameter. If any of the provided buffers
3710 * are too short, -ERANGE is returned after these sizes are filled in.
3712 * @param io the context to operate in
3713 * @param o the name of the object
3714 * @param name the name of the lock
3715 * @param exclusive where to store whether the lock is exclusive (1) or shared (0)
3716 * @param tag where to store the tag associated with the object lock
3717 * @param tag_len number of bytes in tag buffer
3718 * @param clients buffer in which locker clients are stored, separated by '\0'
3719 * @param clients_len number of bytes in the clients buffer
3720 * @param cookies buffer in which locker cookies are stored, separated by '\0'
3721 * @param cookies_len number of bytes in the cookies buffer
3722 * @param addrs buffer in which locker addresses are stored, separated by '\0'
3723 * @param addrs_len number of bytes in the clients buffer
3724 * @returns number of lockers on success, negative error code on failure
3725 * @returns -ERANGE if any of the buffers are too short
3727 CEPH_RADOS_API ssize_t
rados_list_lockers(rados_ioctx_t io
, const char *o
,
3728 const char *name
, int *exclusive
,
3729 char *tag
, size_t *tag_len
,
3730 char *clients
, size_t *clients_len
,
3731 char *cookies
, size_t *cookies_len
,
3732 char *addrs
, size_t *addrs_len
);
3735 * Releases a shared or exclusive lock on an object, which was taken by the
3738 * @param io the context to operate in
3739 * @param o the name of the object
3740 * @param name the name of the lock
3741 * @param client the client currently holding the lock
3742 * @param cookie user-defined identifier for the instance of the lock
3743 * @returns 0 on success, negative error code on failure
3744 * @returns -ENOENT if the lock is not held by the specified (client, cookie) pair
3745 * @returns -EINVAL if the client cannot be parsed
3747 CEPH_RADOS_API
int rados_break_lock(rados_ioctx_t io
, const char *o
,
3748 const char *name
, const char *client
,
3749 const char *cookie
);
3752 * Blocklists the specified client from the OSDs
3754 * @param cluster cluster handle
3755 * @param client_address client address
3756 * @param expire_seconds number of seconds to blocklist (0 for default)
3757 * @returns 0 on success, negative error code on failure
3759 CEPH_RADOS_API
int rados_blocklist_add(rados_t cluster
,
3760 char *client_address
,
3761 uint32_t expire_seconds
);
3762 CEPH_RADOS_API
int rados_blacklist_add(rados_t cluster
,
3763 char *client_address
,
3764 uint32_t expire_seconds
)
3765 __attribute__((deprecated
));
3768 * Gets addresses of the RADOS session, suitable for blocklisting.
3770 * @param cluster cluster handle
3771 * @param addrs the output string.
3772 * @returns 0 on success, negative error code on failure
3774 CEPH_RADOS_API
int rados_getaddrs(rados_t cluster
, char** addrs
);
3776 CEPH_RADOS_API
void rados_set_osdmap_full_try(rados_ioctx_t io
)
3777 __attribute__((deprecated
));
3779 CEPH_RADOS_API
void rados_unset_osdmap_full_try(rados_ioctx_t io
)
3780 __attribute__((deprecated
));
3782 CEPH_RADOS_API
void rados_set_pool_full_try(rados_ioctx_t io
);
3784 CEPH_RADOS_API
void rados_unset_pool_full_try(rados_ioctx_t io
);
3787 * Enable an application on a pool
3789 * @param io pool ioctx
3790 * @param app_name application name
3791 * @param force 0 if only single application per pool
3792 * @returns 0 on success, negative error code on failure
3794 CEPH_RADOS_API
int rados_application_enable(rados_ioctx_t io
,
3795 const char *app_name
, int force
);
3798 * List all enabled applications
3800 * If the provided buffer is too short, the required length is filled in and
3801 * -ERANGE is returned. Otherwise, the buffers are filled with the application
3802 * names, with a '\0' after each.
3804 * @param io pool ioctx
3805 * @param values buffer in which to store application names
3806 * @param values_len number of bytes in values buffer
3807 * @returns 0 on success, negative error code on failure
3808 * @returns -ERANGE if either buffer is too short
3810 CEPH_RADOS_API
int rados_application_list(rados_ioctx_t io
, char *values
,
3811 size_t *values_len
);
3814 * Get application metadata value from pool
3816 * @param io pool ioctx
3817 * @param app_name application name
3818 * @param key metadata key
3819 * @param value result buffer
3820 * @param value_len maximum len of value
3821 * @returns 0 on success, negative error code on failure
3823 CEPH_RADOS_API
int rados_application_metadata_get(rados_ioctx_t io
,
3824 const char *app_name
,
3825 const char *key
, char *value
,
3829 * Set application metadata on a pool
3831 * @param io pool ioctx
3832 * @param app_name application name
3833 * @param key metadata key
3834 * @param value metadata key
3835 * @returns 0 on success, negative error code on failure
3837 CEPH_RADOS_API
int rados_application_metadata_set(rados_ioctx_t io
,
3838 const char *app_name
,
3843 * Remove application metadata from a pool
3845 * @param io pool ioctx
3846 * @param app_name application name
3847 * @param key metadata key
3848 * @returns 0 on success, negative error code on failure
3850 CEPH_RADOS_API
int rados_application_metadata_remove(rados_ioctx_t io
,
3851 const char *app_name
,
3855 * List all metadata key/value pairs associated with an application.
3857 * This iterates over all metadata, key_len and val_len are filled in
3858 * with the number of bytes put into the keys and values buffers.
3860 * If the provided buffers are too short, the required lengths are filled
3861 * in and -ERANGE is returned. Otherwise, the buffers are filled with
3862 * the keys and values of the metadata, with a '\0' after each.
3864 * @param io pool ioctx
3865 * @param app_name application name
3866 * @param keys buffer in which to store key names
3867 * @param key_len number of bytes in keys buffer
3868 * @param values buffer in which to store values
3869 * @param vals_len number of bytes in values buffer
3870 * @returns 0 on success, negative error code on failure
3871 * @returns -ERANGE if either buffer is too short
3873 CEPH_RADOS_API
int rados_application_metadata_list(rados_ioctx_t io
,
3874 const char *app_name
,
3875 char *keys
, size_t *key_len
,
3880 * @name Mon/OSD/PG Commands
3882 * These interfaces send commands relating to the monitor, OSD, or PGs.
3888 * Send monitor command.
3890 * @note Takes command string in carefully-formatted JSON; must match
3891 * defined commands, types, etc.
3893 * The result buffers are allocated on the heap; the caller is
3894 * expected to release that memory with rados_buffer_free(). The
3895 * buffer and length pointers can all be NULL, in which case they are
3898 * @param cluster cluster handle
3899 * @param cmd an array of char *'s representing the command
3900 * @param cmdlen count of valid entries in cmd
3901 * @param inbuf any bulk input data (crush map, etc.)
3902 * @param inbuflen input buffer length
3903 * @param outbuf double pointer to output buffer
3904 * @param outbuflen pointer to output buffer length
3905 * @param outs double pointer to status string
3906 * @param outslen pointer to status string length
3907 * @returns 0 on success, negative error code on failure
3909 CEPH_RADOS_API
int rados_mon_command(rados_t cluster
, const char **cmd
,
3910 size_t cmdlen
, const char *inbuf
,
3911 size_t inbuflen
, char **outbuf
,
3912 size_t *outbuflen
, char **outs
,
3916 * Send ceph-mgr command.
3918 * @note Takes command string in carefully-formatted JSON; must match
3919 * defined commands, types, etc.
3921 * The result buffers are allocated on the heap; the caller is
3922 * expected to release that memory with rados_buffer_free(). The
3923 * buffer and length pointers can all be NULL, in which case they are
3926 * @param cluster cluster handle
3927 * @param cmd an array of char *'s representing the command
3928 * @param cmdlen count of valid entries in cmd
3929 * @param inbuf any bulk input data (crush map, etc.)
3930 * @param inbuflen input buffer length
3931 * @param outbuf double pointer to output buffer
3932 * @param outbuflen pointer to output buffer length
3933 * @param outs double pointer to status string
3934 * @param outslen pointer to status string length
3935 * @returns 0 on success, negative error code on failure
3937 CEPH_RADOS_API
int rados_mgr_command(rados_t cluster
, const char **cmd
,
3938 size_t cmdlen
, const char *inbuf
,
3939 size_t inbuflen
, char **outbuf
,
3940 size_t *outbuflen
, char **outs
,
3944 * Send ceph-mgr tell command.
3946 * @note Takes command string in carefully-formatted JSON; must match
3947 * defined commands, types, etc.
3949 * The result buffers are allocated on the heap; the caller is
3950 * expected to release that memory with rados_buffer_free(). The
3951 * buffer and length pointers can all be NULL, in which case they are
3954 * @param cluster cluster handle
3955 * @param name mgr name to target
3956 * @param cmd an array of char *'s representing the command
3957 * @param cmdlen count of valid entries in cmd
3958 * @param inbuf any bulk input data (crush map, etc.)
3959 * @param inbuflen input buffer length
3960 * @param outbuf double pointer to output buffer
3961 * @param outbuflen pointer to output buffer length
3962 * @param outs double pointer to status string
3963 * @param outslen pointer to status string length
3964 * @returns 0 on success, negative error code on failure
3966 CEPH_RADOS_API
int rados_mgr_command_target(
3970 size_t cmdlen
, const char *inbuf
,
3971 size_t inbuflen
, char **outbuf
,
3972 size_t *outbuflen
, char **outs
,
3976 * Send monitor command to a specific monitor.
3978 * @note Takes command string in carefully-formatted JSON; must match
3979 * defined commands, types, etc.
3981 * The result buffers are allocated on the heap; the caller is
3982 * expected to release that memory with rados_buffer_free(). The
3983 * buffer and length pointers can all be NULL, in which case they are
3986 * @param cluster cluster handle
3987 * @param name target monitor's name
3988 * @param cmd an array of char *'s representing the command
3989 * @param cmdlen count of valid entries in cmd
3990 * @param inbuf any bulk input data (crush map, etc.)
3991 * @param inbuflen input buffer length
3992 * @param outbuf double pointer to output buffer
3993 * @param outbuflen pointer to output buffer length
3994 * @param outs double pointer to status string
3995 * @param outslen pointer to status string length
3996 * @returns 0 on success, negative error code on failure
3998 CEPH_RADOS_API
int rados_mon_command_target(rados_t cluster
, const char *name
,
3999 const char **cmd
, size_t cmdlen
,
4000 const char *inbuf
, size_t inbuflen
,
4001 char **outbuf
, size_t *outbuflen
,
4002 char **outs
, size_t *outslen
);
4005 * free a rados-allocated buffer
4007 * Release memory allocated by librados calls like rados_mon_command().
4009 * @param buf buffer pointer
4011 CEPH_RADOS_API
void rados_buffer_free(char *buf
);
4013 CEPH_RADOS_API
int rados_osd_command(rados_t cluster
, int osdid
,
4014 const char **cmd
, size_t cmdlen
,
4015 const char *inbuf
, size_t inbuflen
,
4016 char **outbuf
, size_t *outbuflen
,
4017 char **outs
, size_t *outslen
);
4019 CEPH_RADOS_API
int rados_pg_command(rados_t cluster
, const char *pgstr
,
4020 const char **cmd
, size_t cmdlen
,
4021 const char *inbuf
, size_t inbuflen
,
4022 char **outbuf
, size_t *outbuflen
,
4023 char **outs
, size_t *outslen
);
4026 * This is not a doxygen comment leadin, because doxygen breaks on
4027 * a typedef with function params and returns, and I can't figure out
4030 * Monitor cluster log
4032 * Monitor events logged to the cluster log. The callback get each
4033 * log entry both as a single formatted line and with each field in a
4036 * Calling with a cb argument of NULL will deregister any previously
4037 * registered callback.
4039 * @param cluster cluster handle
4040 * @param level minimum log level (debug, info, warn|warning, err|error)
4041 * @param cb callback to run for each log message. It MUST NOT block
4042 * nor call back into librados.
4043 * @param arg void argument to pass to cb
4045 * @returns 0 on success, negative code on error
4047 typedef void (*rados_log_callback_t
)(void *arg
,
4050 uint64_t sec
, uint64_t nsec
,
4051 uint64_t seq
, const char *level
,
4055 * This is not a doxygen comment leadin, because doxygen breaks on
4056 * a typedef with function params and returns, and I can't figure out
4059 * Monitor cluster log
4061 * Monitor events logged to the cluster log. The callback get each
4062 * log entry both as a single formatted line and with each field in a
4065 * Calling with a cb argument of NULL will deregister any previously
4066 * registered callback.
4068 * @param cluster cluster handle
4069 * @param level minimum log level (debug, info, warn|warning, err|error)
4070 * @param cb callback to run for each log message. It MUST NOT block
4071 * nor call back into librados.
4072 * @param arg void argument to pass to cb
4074 * @returns 0 on success, negative code on error
4076 typedef void (*rados_log_callback2_t
)(void *arg
,
4078 const char *channel
,
4081 uint64_t sec
, uint64_t nsec
,
4082 uint64_t seq
, const char *level
,
4085 CEPH_RADOS_API
int rados_monitor_log(rados_t cluster
, const char *level
,
4086 rados_log_callback_t cb
, void *arg
);
4087 CEPH_RADOS_API
int rados_monitor_log2(rados_t cluster
, const char *level
,
4088 rados_log_callback2_t cb
, void *arg
);
4092 * register daemon instance for a service
4094 * Register us as a daemon providing a particular service. We identify
4095 * the service (e.g., 'rgw') and our instance name (e.g., 'rgw.$hostname').
4096 * The metadata is a map of keys and values with arbitrary static metdata
4097 * for this instance. The encoding is a series of NULL-terminated strings,
4098 * alternating key names and values, terminating with an empty key name.
4099 * For example, "foo\0bar\0this\0that\0\0" is the dict {foo=bar,this=that}.
4101 * For the lifetime of the librados instance, regular beacons will be sent
4102 * to the cluster to maintain our registration in the service map.
4104 * @param cluster handle
4105 * @param service service name
4106 * @param daemon daemon instance name
4107 * @param metadata_dict static daemon metadata dict
4109 CEPH_RADOS_API
int rados_service_register(
4111 const char *service
,
4113 const char *metadata_dict
);
4116 * update daemon status
4118 * Update our mutable status information in the service map.
4120 * The status dict is encoded the same way the daemon metadata is encoded
4121 * for rados_service_register. For example, "foo\0bar\0this\0that\0\0" is
4122 * {foo=bar,this=that}.
4124 * @param cluster rados cluster handle
4125 * @param status_dict status dict
4127 CEPH_RADOS_API
int rados_service_update_status(
4129 const char *status_dict
);
4131 /** @} Mon/OSD/PG commands */
4134 * These methods are no longer supported and return -ENOTSUP where possible.
4136 CEPH_RADOS_API
int rados_objects_list_open(
4138 rados_list_ctx_t
*ctx
) __attribute__((deprecated
));
4139 CEPH_RADOS_API
uint32_t rados_objects_list_get_pg_hash_position(
4140 rados_list_ctx_t ctx
) __attribute__((deprecated
));
4141 CEPH_RADOS_API
uint32_t rados_objects_list_seek(
4142 rados_list_ctx_t ctx
,
4143 uint32_t pos
) __attribute__((deprecated
));
4144 CEPH_RADOS_API
int rados_objects_list_next(
4145 rados_list_ctx_t ctx
,
4147 const char **key
) __attribute__((deprecated
));
4148 CEPH_RADOS_API
void rados_objects_list_close(
4149 rados_list_ctx_t ctx
) __attribute__((deprecated
));