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 0x1
61 * Constants for rados_write_op_create().
63 #define LIBRADOS_CREATE_EXCLUSIVE 1
64 #define LIBRADOS_CREATE_IDEMPOTENT 0
67 * Flags that can be set on a per-op basis via
68 * rados_read_op_set_flags() and rados_write_op_set_flags().
71 // fail a create operation if the object already exists
72 LIBRADOS_OP_FLAG_EXCL
= 0x1,
73 // allow the transaction to succeed even if the flagged op fails
74 LIBRADOS_OP_FLAG_FAILOK
= 0x2,
75 // indicate read/write op random
76 LIBRADOS_OP_FLAG_FADVISE_RANDOM
= 0x4,
77 // indicate read/write op sequential
78 LIBRADOS_OP_FLAG_FADVISE_SEQUENTIAL
= 0x8,
79 // indicate read/write data will be accessed in the near future (by someone)
80 LIBRADOS_OP_FLAG_FADVISE_WILLNEED
= 0x10,
81 // indicate read/write data will not accessed in the near future (by anyone)
82 LIBRADOS_OP_FLAG_FADVISE_DONTNEED
= 0x20,
83 // indicate read/write data will not accessed again (by *this* client)
84 LIBRADOS_OP_FLAG_FADVISE_NOCACHE
= 0x40,
85 // optionally support FUA (force unit access) on write requests
86 LIBRADOS_OP_FLAG_FADVISE_FUA
= 0x80,
89 #define CEPH_RADOS_API
92 * @name xattr comparison operations
93 * Operators for comparing xattrs on objects, and aborting the
94 * rados_read_op or rados_write_op transaction if the comparison
100 LIBRADOS_CMPXATTR_OP_EQ
= 1,
101 LIBRADOS_CMPXATTR_OP_NE
= 2,
102 LIBRADOS_CMPXATTR_OP_GT
= 3,
103 LIBRADOS_CMPXATTR_OP_GTE
= 4,
104 LIBRADOS_CMPXATTR_OP_LT
= 5,
105 LIBRADOS_CMPXATTR_OP_LTE
= 6
110 * @name Operation Flags
111 * Flags for rados_read_op_operate(), rados_write_op_operate(),
112 * rados_aio_read_op_operate(), and rados_aio_write_op_operate().
113 * See librados.hpp for details.
117 LIBRADOS_OPERATION_NOFLAG
= 0,
118 LIBRADOS_OPERATION_BALANCE_READS
= 1,
119 LIBRADOS_OPERATION_LOCALIZE_READS
= 2,
120 LIBRADOS_OPERATION_ORDER_READS_WRITES
= 4,
121 LIBRADOS_OPERATION_IGNORE_CACHE
= 8,
122 LIBRADOS_OPERATION_SKIPRWLOCKS
= 16,
123 LIBRADOS_OPERATION_IGNORE_OVERLAY
= 32,
124 /* send requests to cluster despite the cluster or pool being marked
125 full; ops will either succeed (e.g., delete) or return EDQUOT or
127 LIBRADOS_OPERATION_FULL_TRY
= 64,
129 * Mainly for delete op
131 LIBRADOS_OPERATION_FULL_FORCE
= 128,
132 LIBRADOS_OPERATION_IGNORE_REDIRECT
= 256,
133 LIBRADOS_OPERATION_ORDERSNAP
= 512,
134 /* enable/allow >0 return values and payloads on write/update */
135 LIBRADOS_OPERATION_RETURNVEC
= 1024,
140 * @name Alloc hint flags
141 * Flags for rados_write_op_alloc_hint2() and rados_set_alloc_hint2()
142 * indicating future IO patterns.
146 LIBRADOS_ALLOC_HINT_FLAG_SEQUENTIAL_WRITE
= 1,
147 LIBRADOS_ALLOC_HINT_FLAG_RANDOM_WRITE
= 2,
148 LIBRADOS_ALLOC_HINT_FLAG_SEQUENTIAL_READ
= 4,
149 LIBRADOS_ALLOC_HINT_FLAG_RANDOM_READ
= 8,
150 LIBRADOS_ALLOC_HINT_FLAG_APPEND_ONLY
= 16,
151 LIBRADOS_ALLOC_HINT_FLAG_IMMUTABLE
= 32,
152 LIBRADOS_ALLOC_HINT_FLAG_SHORTLIVED
= 64,
153 LIBRADOS_ALLOC_HINT_FLAG_LONGLIVED
= 128,
154 LIBRADOS_ALLOC_HINT_FLAG_COMPRESSIBLE
= 256,
155 LIBRADOS_ALLOC_HINT_FLAG_INCOMPRESSIBLE
= 512,
160 LIBRADOS_CHECKSUM_TYPE_XXHASH32
= 0,
161 LIBRADOS_CHECKSUM_TYPE_XXHASH64
= 1,
162 LIBRADOS_CHECKSUM_TYPE_CRC32C
= 2
163 } rados_checksum_type_t
;
168 #define LIBRADOS_SNAP_HEAD ((uint64_t)(-2))
169 #define LIBRADOS_SNAP_DIR ((uint64_t)(-1))
174 * A handle for interacting with a RADOS cluster. It encapsulates all
175 * RADOS client configuration, including username, key for
176 * authentication, logging, and debugging. Talking different clusters
177 * -- or to the same cluster with different users -- requires
178 * different cluster handles.
180 #ifndef VOIDPTR_RADOS_T
181 #define VOIDPTR_RADOS_T
182 typedef void *rados_t
;
183 #endif //VOIDPTR_RADOS_T
186 * @typedef rados_config_t
188 * A handle for the ceph configuration context for the rados_t cluster
189 * instance. This can be used to share configuration context/state
190 * (e.g., logging configuration) between librados instance.
192 * @warning The config context does not have independent reference
193 * counting. As such, a rados_config_t handle retrieved from a given
194 * rados_t is only valid as long as that rados_t.
196 typedef void *rados_config_t
;
199 * @typedef rados_ioctx_t
201 * An io context encapsulates a few settings for all I/O operations
203 * - pool - set when the io context is created (see rados_ioctx_create())
204 * - snapshot context for writes (see
205 * rados_ioctx_selfmanaged_snap_set_write_ctx())
206 * - snapshot id to read from (see rados_ioctx_snap_set_read())
207 * - object locator for all single-object operations (see
208 * rados_ioctx_locator_set_key())
209 * - namespace for all single-object operations (see
210 * rados_ioctx_set_namespace()). Set to LIBRADOS_ALL_NSPACES
211 * before rados_nobjects_list_open() will list all objects in all
214 * @warning Changing any of these settings is not thread-safe -
215 * librados users must synchronize any of these changes on their own,
216 * or use separate io contexts for each thread
218 typedef void *rados_ioctx_t
;
221 * @typedef rados_list_ctx_t
223 * An iterator for listing the objects in a pool.
224 * Used with rados_nobjects_list_open(),
225 * rados_nobjects_list_next(), and
226 * rados_nobjects_list_close().
228 typedef void *rados_list_ctx_t
;
231 * @typedef rados_object_list_cursor
233 * The cursor used with rados_enumerate_objects
234 * and accompanying methods.
236 typedef void * rados_object_list_cursor
;
239 * @struct rados_object_list_item
241 * The item populated by rados_object_list in
248 /// name of the object
251 size_t nspace_length
;
252 /// the object namespace
255 size_t locator_length
;
258 } rados_object_list_item
;
261 * @typedef rados_snap_t
262 * The id of a snapshot.
264 typedef uint64_t rados_snap_t
;
267 * @typedef rados_xattrs_iter_t
268 * An iterator for listing extended attrbutes on an object.
269 * Used with rados_getxattrs(), rados_getxattrs_next(), and
270 * rados_getxattrs_end().
272 typedef void *rados_xattrs_iter_t
;
275 * @typedef rados_omap_iter_t
276 * An iterator for listing omap key/value pairs on an object.
277 * Used with rados_read_op_omap_get_keys(), rados_read_op_omap_get_vals(),
278 * rados_read_op_omap_get_vals_by_keys(), rados_omap_get_next(), and
279 * rados_omap_get_end().
281 typedef void *rados_omap_iter_t
;
284 * @struct rados_pool_stat_t
285 * Usage information for a pool.
287 struct rados_pool_stat_t
{
288 /// space used in bytes
292 /// number of objects in the pool
293 uint64_t num_objects
;
294 /// number of clones of objects
295 uint64_t num_object_clones
;
296 /// num_objects * num_replicas
297 uint64_t num_object_copies
;
298 /// number of objects missing on primary
299 uint64_t num_objects_missing_on_primary
;
300 /// number of objects found on no OSDs
301 uint64_t num_objects_unfound
;
302 /// number of objects replicated fewer times than they should be
303 /// (but found on at least one OSD)
304 uint64_t num_objects_degraded
;
305 /// number of objects read
307 /// objects read in KB
309 /// number of objects written
311 /// objects written in KB
313 /// bytes originally provided by user
314 uint64_t num_user_bytes
;
315 /// bytes passed compression
316 uint64_t compressed_bytes_orig
;
317 /// bytes resulted after compression
318 uint64_t compressed_bytes
;
319 /// bytes allocated at storage
320 uint64_t compressed_bytes_alloc
;
324 * @struct rados_cluster_stat_t
325 * Cluster-wide usage information
327 struct rados_cluster_stat_t
{
328 /// total device size
332 /// total available/free
334 /// number of objects
335 uint64_t num_objects
;
339 * @typedef rados_write_op_t
341 * An object write operation stores a number of operations which can be
342 * executed atomically. For usage, see:
343 * - Creation and deletion: rados_create_write_op() rados_release_write_op()
344 * - Extended attribute manipulation: rados_write_op_cmpxattr()
345 * rados_write_op_cmpxattr(), rados_write_op_setxattr(),
346 * rados_write_op_rmxattr()
347 * - Object map key/value pairs: rados_write_op_omap_set(),
348 * rados_write_op_omap_rm_keys(), rados_write_op_omap_clear(),
349 * rados_write_op_omap_cmp()
350 * - Object properties: rados_write_op_assert_exists(),
351 * rados_write_op_assert_version()
352 * - Creating objects: rados_write_op_create()
353 * - IO on objects: rados_write_op_append(), rados_write_op_write(), rados_write_op_zero
354 * rados_write_op_write_full(), rados_write_op_writesame(), rados_write_op_remove,
355 * rados_write_op_truncate(), rados_write_op_zero(), rados_write_op_cmpext()
356 * - Hints: rados_write_op_set_alloc_hint()
357 * - Performing the operation: rados_write_op_operate(), rados_aio_write_op_operate()
359 typedef void *rados_write_op_t
;
362 * @typedef rados_read_op_t
364 * An object read operation stores a number of operations which can be
365 * executed atomically. For usage, see:
366 * - Creation and deletion: rados_create_read_op() rados_release_read_op()
367 * - Extended attribute manipulation: rados_read_op_cmpxattr(),
368 * rados_read_op_getxattr(), rados_read_op_getxattrs()
369 * - Object map key/value pairs: rados_read_op_omap_get_vals(),
370 * rados_read_op_omap_get_keys(), rados_read_op_omap_get_vals_by_keys(),
371 * rados_read_op_omap_cmp()
372 * - Object properties: rados_read_op_stat(), rados_read_op_assert_exists(),
373 * rados_read_op_assert_version()
374 * - IO on objects: rados_read_op_read(), rados_read_op_checksum(),
375 * rados_read_op_cmpext()
376 * - Custom operations: rados_read_op_exec(), rados_read_op_exec_user_buf()
377 * - Request properties: rados_read_op_set_flags()
378 * - Performing the operation: rados_read_op_operate(),
379 * rados_aio_read_op_operate()
381 typedef void *rados_read_op_t
;
384 * @typedef rados_completion_t
385 * Represents the state of an asynchronous operation - it contains the
386 * return value once the operation completes, and can be used to block
387 * until the operation is complete or safe.
389 typedef void *rados_completion_t
;
392 * @struct blkin_trace_info
393 * blkin trace information for Zipkin tracing
395 struct blkin_trace_info
;
398 * Get the version of librados.
400 * The version number is major.minor.extra. Note that this is
401 * unrelated to the Ceph version number.
403 * TODO: define version semantics, i.e.:
404 * - incrementing major is for backwards-incompatible changes
405 * - incrementing minor is for backwards-compatible changes
406 * - incrementing extra is for bug fixes
408 * @param major where to store the major version number
409 * @param minor where to store the minor version number
410 * @param extra where to store the extra version number
412 CEPH_RADOS_API
void rados_version(int *major
, int *minor
, int *extra
);
415 * @name Setup and Teardown
416 * These are the first and last functions to that should be called
417 * when using librados.
423 * Create a handle for communicating with a RADOS cluster.
425 * Ceph environment variables are read when this is called, so if
426 * $CEPH_ARGS specifies everything you need to connect, no further
427 * configuration is necessary.
429 * @param cluster where to store the handle
430 * @param id the user to connect as (i.e. admin, not client.admin)
431 * @returns 0 on success, negative error code on failure
433 CEPH_RADOS_API
int rados_create(rados_t
*cluster
, const char * const id
);
436 * Extended version of rados_create.
438 * Like rados_create, but
439 * 1) don't assume 'client\.'+id; allow full specification of name
440 * 2) allow specification of cluster name
441 * 3) flags for future expansion
443 CEPH_RADOS_API
int rados_create2(rados_t
*pcluster
,
444 const char *const clustername
,
445 const char * const name
, uint64_t flags
);
448 * Initialize a cluster handle from an existing configuration.
450 * Share configuration state with another rados_t instance.
452 * @param cluster where to store the handle
453 * @param cct the existing configuration to use
454 * @returns 0 on success, negative error code on failure
456 CEPH_RADOS_API
int rados_create_with_context(rados_t
*cluster
,
460 * Ping the monitor with ID mon_id, storing the resulting reply in
461 * buf (if specified) with a maximum size of len.
463 * The result buffer is allocated on the heap; the caller is
464 * expected to release that memory with rados_buffer_free(). The
465 * buffer and length pointers can be NULL, in which case they are
468 * @param cluster cluster handle
469 * @param[in] mon_id ID of the monitor to ping
470 * @param[out] outstr double pointer with the resulting reply
471 * @param[out] outstrlen pointer with the size of the reply in outstr
473 CEPH_RADOS_API
int rados_ping_monitor(rados_t cluster
, const char *mon_id
,
474 char **outstr
, size_t *outstrlen
);
477 * Connect to the cluster.
479 * @note BUG: Before calling this, calling a function that communicates with the
480 * cluster will crash.
482 * @pre The cluster handle is configured with at least a monitor
483 * address. If cephx is enabled, a client name and secret must also be
486 * @post If this succeeds, any function in librados may be used
488 * @param cluster The cluster to connect to.
489 * @returns 0 on success, negative error code on failure
491 CEPH_RADOS_API
int rados_connect(rados_t cluster
);
494 * Disconnects from the cluster.
496 * For clean up, this is only necessary after rados_connect() has
499 * @warning This does not guarantee any asynchronous writes have
500 * completed. To do that, you must call rados_aio_flush() on all open
503 * @warning We implicitly call rados_watch_flush() on shutdown. If
504 * there are watches being used, this should be done explicitly before
505 * destroying the relevant IoCtx. We do it here as a safety measure.
507 * @post the cluster handle cannot be used again
509 * @param cluster the cluster to shutdown
511 CEPH_RADOS_API
void rados_shutdown(rados_t cluster
);
516 * @name Configuration
517 * These functions read and update Ceph configuration for a cluster
518 * handle. Any configuration changes must be done before connecting to
521 * Options that librados users might want to set include:
524 * - key, keyfile, or keyring when using cephx
525 * - log_file, log_to_stderr, err_to_stderr, and log_to_syslog
526 * - debug_rados, debug_objecter, debug_monc, debug_auth, or debug_ms
528 * See docs.ceph.com for information about available configuration options`
534 * Configure the cluster handle using a Ceph config file
536 * If path is NULL, the default locations are searched, and the first
537 * found is used. The locations are:
538 * - $CEPH_CONF (environment variable)
539 * - /etc/ceph/ceph.conf
541 * - ceph.conf (in the current working directory)
543 * @pre rados_connect() has not been called on the cluster handle
545 * @param cluster cluster handle to configure
546 * @param path path to a Ceph configuration file
547 * @returns 0 on success, negative error code on failure
549 CEPH_RADOS_API
int rados_conf_read_file(rados_t cluster
, const char *path
);
552 * Configure the cluster handle with command line arguments
554 * argv can contain any common Ceph command line option, including any
555 * configuration parameter prefixed by '--' and replacing spaces with
556 * dashes or underscores. For example, the following options are equivalent:
557 * - --mon-host 10.0.0.1:6789
558 * - --mon_host 10.0.0.1:6789
561 * @pre rados_connect() has not been called on the cluster handle
563 * @param cluster cluster handle to configure
564 * @param argc number of arguments in argv
565 * @param argv arguments to parse
566 * @returns 0 on success, negative error code on failure
568 CEPH_RADOS_API
int rados_conf_parse_argv(rados_t cluster
, int argc
,
573 * Configure the cluster handle with command line arguments, returning
574 * any remainders. Same rados_conf_parse_argv, except for extra
575 * remargv argument to hold returns unrecognized arguments.
577 * @pre rados_connect() has not been called on the cluster handle
579 * @param cluster cluster handle to configure
580 * @param argc number of arguments in argv
581 * @param argv arguments to parse
582 * @param remargv char* array for returned unrecognized arguments
583 * @returns 0 on success, negative error code on failure
585 CEPH_RADOS_API
int rados_conf_parse_argv_remainder(rados_t cluster
, int argc
,
587 const char **remargv
);
589 * Configure the cluster handle based on an environment variable
591 * The contents of the environment variable are parsed as if they were
592 * Ceph command line options. If var is NULL, the CEPH_ARGS
593 * environment variable is used.
595 * @pre rados_connect() has not been called on the cluster handle
597 * @note BUG: this is not threadsafe - it uses a static buffer
599 * @param cluster cluster handle to configure
600 * @param var name of the environment variable to read
601 * @returns 0 on success, negative error code on failure
603 CEPH_RADOS_API
int rados_conf_parse_env(rados_t cluster
, const char *var
);
606 * Set a configuration option
608 * @pre rados_connect() has not been called on the cluster handle
610 * @param cluster cluster handle to configure
611 * @param option option to set
612 * @param value value of the option
613 * @returns 0 on success, negative error code on failure
614 * @returns -ENOENT when the option is not a Ceph configuration option
616 CEPH_RADOS_API
int rados_conf_set(rados_t cluster
, const char *option
,
620 * Get the value of a configuration option
622 * @param cluster configuration to read
623 * @param option which option to read
624 * @param buf where to write the configuration value
625 * @param len the size of buf in bytes
626 * @returns 0 on success, negative error code on failure
627 * @returns -ENAMETOOLONG if the buffer is too short to contain the
630 CEPH_RADOS_API
int rados_conf_get(rados_t cluster
, const char *option
,
631 char *buf
, size_t len
);
636 * Read usage info about the cluster
638 * This tells you total space, space used, space available, and number
639 * of objects. These are not updated immediately when data is written,
640 * they are eventually consistent.
642 * @param cluster cluster to query
643 * @param result where to store the results
644 * @returns 0 on success, negative error code on failure
646 CEPH_RADOS_API
int rados_cluster_stat(rados_t cluster
,
647 struct rados_cluster_stat_t
*result
);
650 * Get the fsid of the cluster as a hexadecimal string.
652 * The fsid is a unique id of an entire Ceph cluster.
654 * @param cluster where to get the fsid
655 * @param buf where to write the fsid
656 * @param len the size of buf in bytes (should be 37)
657 * @returns 0 on success, negative error code on failure
658 * @returns -ERANGE if the buffer is too short to contain the
661 CEPH_RADOS_API
int rados_cluster_fsid(rados_t cluster
, char *buf
, size_t len
);
664 * Get/wait for the most recent osdmap
666 * @param cluster the cluster to shutdown
667 * @returns 0 on success, negative error code on failure
669 CEPH_RADOS_API
int rados_wait_for_latest_osdmap(rados_t cluster
);
674 * RADOS pools are separate namespaces for objects. Pools may have
675 * different crush rules associated with them, so they could have
676 * differing replication levels or placement strategies. RADOS
677 * permissions are also tied to pools - users can have different read,
678 * write, and execute permissions on a per-pool basis.
686 * Gets a list of pool names as NULL-terminated strings. The pool
687 * names will be placed in the supplied buffer one after another.
688 * After the last pool name, there will be two 0 bytes in a row.
690 * If len is too short to fit all the pool name entries we need, we will fill
693 * Buf may be null to determine the buffer size needed to list all pools.
695 * @param cluster cluster handle
696 * @param buf output buffer
697 * @param len output buffer length
698 * @returns length of the buffer we would need to list all pools
700 CEPH_RADOS_API
int rados_pool_list(rados_t cluster
, char *buf
, size_t len
);
703 * List inconsistent placement groups of the given pool
705 * Gets a list of inconsistent placement groups as NULL-terminated strings.
706 * The placement group names will be placed in the supplied buffer one after
707 * another. After the last name, there will be two 0 types in a row.
709 * If len is too short to fit all the placement group entries we need, we will
710 * fill as much as we can.
712 * @param cluster cluster handle
713 * @param pool pool ID
714 * @param buf output buffer
715 * @param len output buffer length
716 * @returns length of the buffer we would need to list all pools
718 CEPH_RADOS_API
int rados_inconsistent_pg_list(rados_t cluster
, int64_t pool
,
719 char *buf
, size_t len
);
722 * Get a configuration handle for a rados cluster handle
724 * This handle is valid only as long as the cluster handle is valid.
726 * @param cluster cluster handle
727 * @returns config handle for this cluster
729 CEPH_RADOS_API rados_config_t
rados_cct(rados_t cluster
);
732 * Get a global id for current instance
734 * This id is a unique representation of current connection to the cluster
736 * @param cluster cluster handle
737 * @returns instance global id
739 CEPH_RADOS_API
uint64_t rados_get_instance_id(rados_t cluster
);
742 * Gets the minimum compatible OSD version
744 * @param cluster cluster handle
745 * @param[out] require_osd_release minimum compatible OSD version
746 * based upon the current features
747 * @returns 0 on sucess, negative error code on failure
749 CEPH_RADOS_API
int rados_get_min_compatible_osd(rados_t cluster
,
750 int8_t* require_osd_release
);
753 * Gets the minimum compatible client version
755 * @param cluster cluster handle
756 * @param[out] min_compat_client minimum compatible client version
757 * based upon the current features
758 * @param[out] require_min_compat_client required minimum client version
759 * based upon explicit setting
760 * @returns 0 on success, negative error code on failure
762 CEPH_RADOS_API
int rados_get_min_compatible_client(rados_t cluster
,
763 int8_t* min_compat_client
,
764 int8_t* require_min_compat_client
);
767 * Create an io context
769 * The io context allows you to perform operations within a particular
770 * pool. For more details see rados_ioctx_t.
772 * @param cluster which cluster the pool is in
773 * @param pool_name name of the pool
774 * @param ioctx where to store the io context
775 * @returns 0 on success, negative error code on failure
777 CEPH_RADOS_API
int rados_ioctx_create(rados_t cluster
, const char *pool_name
,
778 rados_ioctx_t
*ioctx
);
779 CEPH_RADOS_API
int rados_ioctx_create2(rados_t cluster
, int64_t pool_id
,
780 rados_ioctx_t
*ioctx
);
783 * The opposite of rados_ioctx_create
785 * This just tells librados that you no longer need to use the io context.
786 * It may not be freed immediately if there are pending asynchronous
787 * requests on it, but you should not use an io context again after
788 * calling this function on it.
790 * @warning This does not guarantee any asynchronous
791 * writes have completed. You must call rados_aio_flush()
792 * on the io context before destroying it to do that.
794 * @warning If this ioctx is used by rados_watch, the caller needs to
795 * be sure that all registered watches are disconnected via
796 * rados_unwatch() and that rados_watch_flush() is called. This
797 * ensures that a racing watch callback does not make use of a
800 * @param io the io context to dispose of
802 CEPH_RADOS_API
void rados_ioctx_destroy(rados_ioctx_t io
);
805 * Get configuration handle for a pool handle
807 * @param io pool handle
808 * @returns rados_config_t for this cluster
810 CEPH_RADOS_API rados_config_t
rados_ioctx_cct(rados_ioctx_t io
);
813 * Get the cluster handle used by this rados_ioctx_t
814 * Note that this is a weak reference, and should not
815 * be destroyed via rados_shutdown().
817 * @param io the io context
818 * @returns the cluster handle for this io context
820 CEPH_RADOS_API rados_t
rados_ioctx_get_cluster(rados_ioctx_t io
);
823 * Get pool usage statistics
825 * Fills in a rados_pool_stat_t after querying the cluster.
827 * @param io determines which pool to query
828 * @param stats where to store the results
829 * @returns 0 on success, negative error code on failure
831 CEPH_RADOS_API
int rados_ioctx_pool_stat(rados_ioctx_t io
,
832 struct rados_pool_stat_t
*stats
);
835 * Get the id of a pool
837 * @param cluster which cluster the pool is in
838 * @param pool_name which pool to look up
839 * @returns id of the pool
840 * @returns -ENOENT if the pool is not found
842 CEPH_RADOS_API
int64_t rados_pool_lookup(rados_t cluster
,
843 const char *pool_name
);
846 * Get the name of a pool
848 * @param cluster which cluster the pool is in
849 * @param id the id of the pool
850 * @param buf where to store the pool name
851 * @param maxlen size of buffer where name will be stored
852 * @returns length of string stored, or -ERANGE if buffer too small
854 CEPH_RADOS_API
int rados_pool_reverse_lookup(rados_t cluster
, int64_t id
,
855 char *buf
, size_t maxlen
);
858 * Create a pool with default settings
860 * The default crush rule is rule 0.
862 * @param cluster the cluster in which the pool will be created
863 * @param pool_name the name of the new pool
864 * @returns 0 on success, negative error code on failure
866 CEPH_RADOS_API
int rados_pool_create(rados_t cluster
, const char *pool_name
);
869 * Create a pool owned by a specific auid.
871 * DEPRECATED: auid support has been removed, and this call will be removed in a future
874 * @param cluster the cluster in which the pool will be created
875 * @param pool_name the name of the new pool
876 * @param auid the id of the owner of the new pool
877 * @returns 0 on success, negative error code on failure
879 CEPH_RADOS_API
int rados_pool_create_with_auid(rados_t cluster
,
880 const char *pool_name
,
882 __attribute__((deprecated
));
885 * Create a pool with a specific CRUSH rule
887 * @param cluster the cluster in which the pool will be created
888 * @param pool_name the name of the new pool
889 * @param crush_rule_num which rule to use for placement in the new pool1
890 * @returns 0 on success, negative error code on failure
892 CEPH_RADOS_API
int rados_pool_create_with_crush_rule(rados_t cluster
,
893 const char *pool_name
,
894 uint8_t crush_rule_num
);
897 * Create a pool with a specific CRUSH rule and auid
899 * DEPRECATED: auid support has been removed and this call will be removed
900 * in a future release.
902 * This is a combination of rados_pool_create_with_crush_rule() and
903 * rados_pool_create_with_auid().
905 * @param cluster the cluster in which the pool will be created
906 * @param pool_name the name of the new pool
907 * @param crush_rule_num which rule to use for placement in the new pool2
908 * @param auid the id of the owner of the new pool
909 * @returns 0 on success, negative error code on failure
911 CEPH_RADOS_API
int rados_pool_create_with_all(rados_t cluster
,
912 const char *pool_name
,
914 uint8_t crush_rule_num
)
915 __attribute__((deprecated
));
918 * Returns the pool that is the base tier for this pool.
920 * The return value is the ID of the pool that should be used to read from/write to.
921 * If tiering is not set up for the pool, returns \c pool.
923 * @param cluster the cluster the pool is in
924 * @param pool ID of the pool to query
925 * @param[out] base_tier base tier, or \c pool if tiering is not configured
926 * @returns 0 on success, negative error code on failure
928 CEPH_RADOS_API
int rados_pool_get_base_tier(rados_t cluster
, int64_t pool
,
932 * Delete a pool and all data inside it
934 * The pool is removed from the cluster immediately,
935 * but the actual data is deleted in the background.
937 * @param cluster the cluster the pool is in
938 * @param pool_name which pool to delete
939 * @returns 0 on success, negative error code on failure
941 CEPH_RADOS_API
int rados_pool_delete(rados_t cluster
, const char *pool_name
);
944 * Attempt to change an io context's associated auid "owner"
946 * DEPRECATED: auid support has been removed and this call has no effect.
948 * Requires that you have write permission on both the current and new
951 * @param io reference to the pool to change.
952 * @param auid the auid you wish the io to have.
953 * @returns 0 on success, negative error code on failure
955 CEPH_RADOS_API
int rados_ioctx_pool_set_auid(rados_ioctx_t io
, uint64_t auid
)
956 __attribute__((deprecated
));
960 * Get the auid of a pool
962 * DEPRECATED: auid support has been removed and this call always reports
963 * CEPH_AUTH_UID_DEFAULT (-1).
965 * @param io pool to query
966 * @param auid where to store the auid
967 * @returns 0 on success, negative error code on failure
969 CEPH_RADOS_API
int rados_ioctx_pool_get_auid(rados_ioctx_t io
, uint64_t *auid
)
970 __attribute__((deprecated
));
972 /* deprecated, use rados_ioctx_pool_requires_alignment2 instead */
973 CEPH_RADOS_API
int rados_ioctx_pool_requires_alignment(rados_ioctx_t io
)
974 __attribute__((deprecated
));
977 * Test whether the specified pool requires alignment or not.
979 * @param io pool to query
980 * @param req 1 if alignment is supported, 0 if not.
981 * @returns 0 on success, negative error code on failure
983 CEPH_RADOS_API
int rados_ioctx_pool_requires_alignment2(rados_ioctx_t io
,
986 /* deprecated, use rados_ioctx_pool_required_alignment2 instead */
987 CEPH_RADOS_API
uint64_t rados_ioctx_pool_required_alignment(rados_ioctx_t io
)
988 __attribute__((deprecated
));
991 * Get the alignment flavor of a pool
993 * @param io pool to query
994 * @param alignment where to store the alignment flavor
995 * @returns 0 on success, negative error code on failure
997 CEPH_RADOS_API
int rados_ioctx_pool_required_alignment2(rados_ioctx_t io
,
998 uint64_t *alignment
);
1001 * Get the pool id of the io context
1003 * @param io the io context to query
1004 * @returns the id of the pool the io context uses
1006 CEPH_RADOS_API
int64_t rados_ioctx_get_id(rados_ioctx_t io
);
1009 * Get the pool name of the io context
1011 * @param io the io context to query
1012 * @param buf pointer to buffer where name will be stored
1013 * @param maxlen size of buffer where name will be stored
1014 * @returns length of string stored, or -ERANGE if buffer too small
1016 CEPH_RADOS_API
int rados_ioctx_get_pool_name(rados_ioctx_t io
, char *buf
,
1022 * @name Object Locators
1028 * Set the key for mapping objects to pgs within an io context.
1030 * The key is used instead of the object name to determine which
1031 * placement groups an object is put in. This affects all subsequent
1032 * operations of the io context - until a different locator key is
1033 * set, all objects in this io context will be placed in the same pg.
1035 * @param io the io context to change
1036 * @param key the key to use as the object locator, or NULL to discard
1037 * any previously set key
1039 CEPH_RADOS_API
void rados_ioctx_locator_set_key(rados_ioctx_t io
,
1043 * Set the namespace for objects within an io context
1045 * The namespace specification further refines a pool into different
1046 * domains. The mapping of objects to pgs is also based on this
1049 * @param io the io context to change
1050 * @param nspace the name to use as the namespace, or NULL use the
1053 CEPH_RADOS_API
void rados_ioctx_set_namespace(rados_ioctx_t io
,
1054 const char *nspace
);
1057 * Get the namespace for objects within the io context
1059 * @param io the io context to query
1060 * @param buf pointer to buffer where name will be stored
1061 * @param maxlen size of buffer where name will be stored
1062 * @returns length of string stored, or -ERANGE if buffer too small
1064 CEPH_RADOS_API
int rados_ioctx_get_namespace(rados_ioctx_t io
, char *buf
,
1070 * @name Listing Objects
1074 * Start listing objects in a pool
1076 * @param io the pool to list from
1077 * @param ctx the handle to store list context in
1078 * @returns 0 on success, negative error code on failure
1080 CEPH_RADOS_API
int rados_nobjects_list_open(rados_ioctx_t io
,
1081 rados_list_ctx_t
*ctx
);
1084 * Return hash position of iterator, rounded to the current PG
1086 * @param ctx iterator marking where you are in the listing
1087 * @returns current hash position, rounded to the current pg
1089 CEPH_RADOS_API
uint32_t rados_nobjects_list_get_pg_hash_position(rados_list_ctx_t ctx
);
1092 * Reposition object iterator to a different hash position
1094 * @param ctx iterator marking where you are in the listing
1095 * @param pos hash position to move to
1096 * @returns actual (rounded) position we moved to
1098 CEPH_RADOS_API
uint32_t rados_nobjects_list_seek(rados_list_ctx_t ctx
,
1102 * Reposition object iterator to a different position
1104 * @param ctx iterator marking where you are in the listing
1105 * @param cursor position to move to
1106 * @returns rounded position we moved to
1108 CEPH_RADOS_API
uint32_t rados_nobjects_list_seek_cursor(rados_list_ctx_t ctx
,
1109 rados_object_list_cursor cursor
);
1112 * Reposition object iterator to a different position
1114 * The returned handle must be released with rados_object_list_cursor_free().
1116 * @param ctx iterator marking where you are in the listing
1117 * @param cursor where to store cursor
1118 * @returns 0 on success, negative error code on failure
1120 CEPH_RADOS_API
int rados_nobjects_list_get_cursor(rados_list_ctx_t ctx
,
1121 rados_object_list_cursor
*cursor
);
1124 * Get the next object name and locator in the pool
1126 * *entry and *key are valid until next call to rados_nobjects_list_*
1128 * @param ctx iterator marking where you are in the listing
1129 * @param entry where to store the name of the entry
1130 * @param key where to store the object locator (set to NULL to ignore)
1131 * @param nspace where to store the object namespace (set to NULL to ignore)
1132 * @returns 0 on success, negative error code on failure
1133 * @returns -ENOENT when there are no more objects to list
1135 CEPH_RADOS_API
int rados_nobjects_list_next(rados_list_ctx_t ctx
,
1138 const char **nspace
);
1141 * Close the object listing handle.
1143 * This should be called when the handle is no longer needed.
1144 * The handle should not be used after it has been closed.
1146 * @param ctx the handle to close
1148 CEPH_RADOS_API
void rados_nobjects_list_close(rados_list_ctx_t ctx
);
1151 * Get cursor handle pointing to the *beginning* of a pool.
1153 * This is an opaque handle pointing to the start of a pool. It must
1154 * be released with rados_object_list_cursor_free().
1156 * @param io ioctx for the pool
1157 * @returns handle for the pool, NULL on error (pool does not exist)
1159 CEPH_RADOS_API rados_object_list_cursor
rados_object_list_begin(
1163 * Get cursor handle pointing to the *end* of a pool.
1165 * This is an opaque handle pointing to the start of a pool. It must
1166 * be released with rados_object_list_cursor_free().
1168 * @param io ioctx for the pool
1169 * @returns handle for the pool, NULL on error (pool does not exist)
1171 CEPH_RADOS_API rados_object_list_cursor
rados_object_list_end(rados_ioctx_t io
);
1174 * Check if a cursor has reached the end of a pool
1178 * @returns 1 if the cursor has reached the end of the pool, 0 otherwise
1180 CEPH_RADOS_API
int rados_object_list_is_end(rados_ioctx_t io
,
1181 rados_object_list_cursor cur
);
1186 * Release a cursor. The handle may not be used after this point.
1191 CEPH_RADOS_API
void rados_object_list_cursor_free(rados_ioctx_t io
,
1192 rados_object_list_cursor cur
);
1195 * Compare two cursor positions
1197 * Compare two cursors, and indicate whether the first cursor precedes,
1198 * matches, or follows the second.
1201 * @param lhs first cursor
1202 * @param rhs second cursor
1203 * @returns -1, 0, or 1 for lhs < rhs, lhs == rhs, or lhs > rhs
1205 CEPH_RADOS_API
int rados_object_list_cursor_cmp(rados_ioctx_t io
,
1206 rados_object_list_cursor lhs
, rados_object_list_cursor rhs
);
1209 * @return the number of items set in the results array
1211 CEPH_RADOS_API
int rados_object_list(rados_ioctx_t io
,
1212 const rados_object_list_cursor start
,
1213 const rados_object_list_cursor finish
,
1214 const size_t result_size
,
1215 const char *filter_buf
,
1216 const size_t filter_buf_len
,
1217 rados_object_list_item
*results
,
1218 rados_object_list_cursor
*next
);
1220 CEPH_RADOS_API
void rados_object_list_free(
1221 const size_t result_size
,
1222 rados_object_list_item
*results
);
1225 * Obtain cursors delineating a subset of a range. Use this
1226 * when you want to split up the work of iterating over the
1227 * global namespace. Expected use case is when you are iterating
1228 * in parallel, with `m` workers, and each worker taking an id `n`.
1231 * @param start start of the range to be sliced up (inclusive)
1232 * @param finish end of the range to be sliced up (exclusive)
1233 * @param n which of the m chunks you would like to get cursors for
1234 * @param m how many chunks to divide start-finish into
1235 * @param split_start cursor populated with start of the subrange (inclusive)
1236 * @param split_finish cursor populated with end of the subrange (exclusive)
1238 CEPH_RADOS_API
void rados_object_list_slice(rados_ioctx_t io
,
1239 const rados_object_list_cursor start
,
1240 const rados_object_list_cursor finish
,
1243 rados_object_list_cursor
*split_start
,
1244 rados_object_list_cursor
*split_finish
);
1247 /** @} Listing Objects */
1252 * RADOS snapshots are based upon sequence numbers that form a
1253 * snapshot context. They are pool-specific. The snapshot context
1254 * consists of the current snapshot sequence number for a pool, and an
1255 * array of sequence numbers at which snapshots were taken, in
1256 * descending order. Whenever a snapshot is created or deleted, the
1257 * snapshot sequence number for the pool is increased. To add a new
1258 * snapshot, the new snapshot sequence number must be increased and
1259 * added to the snapshot context.
1261 * There are two ways to manage these snapshot contexts:
1262 * -# within the RADOS cluster
1263 * These are called pool snapshots, and store the snapshot context
1264 * in the OSDMap. These represent a snapshot of all the objects in
1266 * -# within the RADOS clients
1267 * These are called self-managed snapshots, and push the
1268 * responsibility for keeping track of the snapshot context to the
1269 * clients. For every write, the client must send the snapshot
1270 * context. In librados, this is accomplished with
1271 * rados_selfmanaged_snap_set_write_ctx(). These are more
1272 * difficult to manage, but are restricted to specific objects
1273 * instead of applying to an entire pool.
1279 * Create a pool-wide snapshot
1281 * @param io the pool to snapshot
1282 * @param snapname the name of the snapshot
1283 * @returns 0 on success, negative error code on failure
1285 CEPH_RADOS_API
int rados_ioctx_snap_create(rados_ioctx_t io
,
1286 const char *snapname
);
1289 * Delete a pool snapshot
1291 * @param io the pool to delete the snapshot from
1292 * @param snapname which snapshot to delete
1293 * @returns 0 on success, negative error code on failure
1295 CEPH_RADOS_API
int rados_ioctx_snap_remove(rados_ioctx_t io
,
1296 const char *snapname
);
1299 * Rollback an object to a pool snapshot
1301 * The contents of the object will be the same as
1302 * when the snapshot was taken.
1304 * @param io the pool in which the object is stored
1305 * @param oid the name of the object to rollback
1306 * @param snapname which snapshot to rollback to
1307 * @returns 0 on success, negative error code on failure
1309 CEPH_RADOS_API
int rados_ioctx_snap_rollback(rados_ioctx_t io
, const char *oid
,
1310 const char *snapname
);
1313 * @warning Deprecated: Use rados_ioctx_snap_rollback() instead
1315 CEPH_RADOS_API
int rados_rollback(rados_ioctx_t io
, const char *oid
,
1316 const char *snapname
)
1317 __attribute__((deprecated
));
1320 * Set the snapshot from which reads are performed.
1322 * Subsequent reads will return data as it was at the time of that
1325 * @param io the io context to change
1326 * @param snap the id of the snapshot to set, or LIBRADOS_SNAP_HEAD for no
1327 * snapshot (i.e. normal operation)
1329 CEPH_RADOS_API
void rados_ioctx_snap_set_read(rados_ioctx_t io
,
1333 * Allocate an ID for a self-managed snapshot
1335 * Get a unique ID to put in the snaphot context to create a
1336 * snapshot. A clone of an object is not created until a write with
1337 * the new snapshot context is completed.
1339 * @param io the pool in which the snapshot will exist
1340 * @param snapid where to store the newly allocated snapshot ID
1341 * @returns 0 on success, negative error code on failure
1343 CEPH_RADOS_API
int rados_ioctx_selfmanaged_snap_create(rados_ioctx_t io
,
1344 rados_snap_t
*snapid
);
1346 rados_aio_ioctx_selfmanaged_snap_create(rados_ioctx_t io
,
1347 rados_snap_t
*snapid
,
1348 rados_completion_t completion
);
1351 * Remove a self-managed snapshot
1353 * This increases the snapshot sequence number, which will cause
1354 * snapshots to be removed lazily.
1356 * @param io the pool in which the snapshot will exist
1357 * @param snapid where to store the newly allocated snapshot ID
1358 * @returns 0 on success, negative error code on failure
1360 CEPH_RADOS_API
int rados_ioctx_selfmanaged_snap_remove(rados_ioctx_t io
,
1361 rados_snap_t snapid
);
1363 rados_aio_ioctx_selfmanaged_snap_remove(rados_ioctx_t io
,
1364 rados_snap_t snapid
,
1365 rados_completion_t completion
);
1368 * Rollback an object to a self-managed snapshot
1370 * The contents of the object will be the same as
1371 * when the snapshot was taken.
1373 * @param io the pool in which the object is stored
1374 * @param oid the name of the object to rollback
1375 * @param snapid which snapshot to rollback to
1376 * @returns 0 on success, negative error code on failure
1378 CEPH_RADOS_API
int rados_ioctx_selfmanaged_snap_rollback(rados_ioctx_t io
,
1380 rados_snap_t snapid
);
1383 * Set the snapshot context for use when writing to objects
1385 * This is stored in the io context, and applies to all future writes.
1387 * @param io the io context to change
1388 * @param seq the newest snapshot sequence number for the pool
1389 * @param snaps array of snapshots in sorted by descending id
1390 * @param num_snaps how many snaphosts are in the snaps array
1391 * @returns 0 on success, negative error code on failure
1392 * @returns -EINVAL if snaps are not in descending order
1394 CEPH_RADOS_API
int rados_ioctx_selfmanaged_snap_set_write_ctx(rados_ioctx_t io
,
1396 rados_snap_t
*snaps
,
1400 * List all the ids of pool snapshots
1402 * If the output array does not have enough space to fit all the
1403 * snapshots, -ERANGE is returned and the caller should retry with a
1406 * @param io the pool to read from
1407 * @param snaps where to store the results
1408 * @param maxlen the number of rados_snap_t that fit in the snaps array
1409 * @returns number of snapshots on success, negative error code on failure
1410 * @returns -ERANGE is returned if the snaps array is too short
1412 CEPH_RADOS_API
int rados_ioctx_snap_list(rados_ioctx_t io
, rados_snap_t
*snaps
,
1416 * Get the id of a pool snapshot
1418 * @param io the pool to read from
1419 * @param name the snapshot to find
1420 * @param id where to store the result
1421 * @returns 0 on success, negative error code on failure
1423 CEPH_RADOS_API
int rados_ioctx_snap_lookup(rados_ioctx_t io
, const char *name
,
1427 * Get the name of a pool snapshot
1429 * @param io the pool to read from
1430 * @param id the snapshot to find
1431 * @param name where to store the result
1432 * @param maxlen the size of the name array
1433 * @returns 0 on success, negative error code on failure
1434 * @returns -ERANGE if the name array is too small
1436 CEPH_RADOS_API
int rados_ioctx_snap_get_name(rados_ioctx_t io
, rados_snap_t id
,
1437 char *name
, int maxlen
);
1440 * Find when a pool snapshot occurred
1442 * @param io the pool the snapshot was taken in
1443 * @param id the snapshot to lookup
1444 * @param t where to store the result
1445 * @returns 0 on success, negative error code on failure
1447 CEPH_RADOS_API
int rados_ioctx_snap_get_stamp(rados_ioctx_t io
, rados_snap_t id
,
1453 * @name Synchronous I/O
1454 * Writes are replicated to a number of OSDs based on the
1455 * configuration of the pool they are in. These write functions block
1456 * until data is in memory on all replicas of the object they're
1457 * writing to - they are equivalent to doing the corresponding
1458 * asynchronous write, and the calling
1459 * rados_ioctx_wait_for_complete(). For greater data safety, use the
1460 * asynchronous functions and rados_aio_wait_for_safe().
1466 * Return the version of the last object read or written to.
1468 * This exposes the internal version number of the last object read or
1469 * written via this io context
1471 * @param io the io context to check
1472 * @returns last read or written object version
1474 CEPH_RADOS_API
uint64_t rados_get_last_version(rados_ioctx_t io
);
1477 * Write *len* bytes from *buf* into the *oid* object, starting at
1478 * offset *off*. The value of *len* must be <= UINT_MAX/2.
1480 * @note This will never return a positive value not equal to len.
1481 * @param io the io context in which the write will occur
1482 * @param oid name of the object
1483 * @param buf data to write
1484 * @param len length of the data, in bytes
1485 * @param off byte offset in the object to begin writing at
1486 * @returns 0 on success, negative error code on failure
1488 CEPH_RADOS_API
int rados_write(rados_ioctx_t io
, const char *oid
,
1489 const char *buf
, size_t len
, uint64_t off
);
1492 * Write *len* bytes from *buf* into the *oid* object. The value of
1493 * *len* must be <= UINT_MAX/2.
1495 * The object is filled with the provided data. If the object exists,
1496 * it is atomically truncated and then written.
1498 * @param io the io context in which the write will occur
1499 * @param oid name of the object
1500 * @param buf data to write
1501 * @param len length of the data, in bytes
1502 * @returns 0 on success, negative error code on failure
1504 CEPH_RADOS_API
int rados_write_full(rados_ioctx_t io
, const char *oid
,
1505 const char *buf
, size_t len
);
1508 * Write the same *data_len* bytes from *buf* multiple times into the
1509 * *oid* object. *write_len* bytes are written in total, which must be
1510 * a multiple of *data_len*. The value of *write_len* and *data_len*
1511 * must be <= UINT_MAX/2.
1513 * @param io the io context in which the write will occur
1514 * @param oid name of the object
1515 * @param buf data to write
1516 * @param data_len length of the data, in bytes
1517 * @param write_len the total number of bytes to write
1518 * @param off byte offset in the object to begin writing at
1519 * @returns 0 on success, negative error code on failure
1521 CEPH_RADOS_API
int rados_writesame(rados_ioctx_t io
, const char *oid
,
1522 const char *buf
, size_t data_len
,
1523 size_t write_len
, uint64_t off
);
1526 * Append *len* bytes from *buf* into the *oid* object. The value of
1527 * *len* must be <= UINT_MAX/2.
1529 * @param io the context to operate in
1530 * @param oid the name of the object
1531 * @param buf the data to append
1532 * @param len length of buf (in bytes)
1533 * @returns 0 on success, negative error code on failure
1535 CEPH_RADOS_API
int rados_append(rados_ioctx_t io
, const char *oid
,
1536 const char *buf
, size_t len
);
1539 * Read data from an object
1541 * The io context determines the snapshot to read from, if any was set
1542 * by rados_ioctx_snap_set_read().
1544 * @param io the context in which to perform the read
1545 * @param oid the name of the object to read from
1546 * @param buf where to store the results
1547 * @param len the number of bytes to read
1548 * @param off the offset to start reading from in the object
1549 * @returns number of bytes read on success, negative error code on
1552 CEPH_RADOS_API
int rados_read(rados_ioctx_t io
, const char *oid
, char *buf
,
1553 size_t len
, uint64_t off
);
1556 * Compute checksum from object data
1558 * The io context determines the snapshot to checksum, if any was set
1559 * by rados_ioctx_snap_set_read(). The length of the init_value and
1560 * resulting checksum are dependent upon the checksum type:
1566 * The checksum result is encoded the following manner:
1568 * le32 num_checksum_chunks
1570 * leXX checksum for chunk (where XX = appropriate size for the checksum type)
1571 * } * num_checksum_chunks
1573 * @param io the context in which to perform the checksum
1574 * @param oid the name of the object to checksum
1575 * @param type the checksum algorithm to utilize
1576 * @param init_value the init value for the algorithm
1577 * @param init_value_len the length of the init value
1578 * @param len the number of bytes to checksum
1579 * @param off the offset to start checksumming in the object
1580 * @param chunk_size optional length-aligned chunk size for checksums
1581 * @param pchecksum where to store the checksum result
1582 * @param checksum_len the number of bytes available for the result
1583 * @return negative error code on failure
1585 CEPH_RADOS_API
int rados_checksum(rados_ioctx_t io
, const char *oid
,
1586 rados_checksum_type_t type
,
1587 const char *init_value
, size_t init_value_len
,
1588 size_t len
, uint64_t off
, size_t chunk_size
,
1589 char *pchecksum
, size_t checksum_len
);
1594 * @note This does not delete any snapshots of the object.
1596 * @param io the pool to delete the object from
1597 * @param oid the name of the object to delete
1598 * @returns 0 on success, negative error code on failure
1600 CEPH_RADOS_API
int rados_remove(rados_ioctx_t io
, const char *oid
);
1605 * If this enlarges the object, the new area is logically filled with
1606 * zeroes. If this shrinks the object, the excess data is removed.
1608 * @param io the context in which to truncate
1609 * @param oid the name of the object
1610 * @param size the new size of the object in bytes
1611 * @returns 0 on success, negative error code on failure
1613 CEPH_RADOS_API
int rados_trunc(rados_ioctx_t io
, const char *oid
,
1617 * Compare an on-disk object range with a buffer
1619 * @param io the context in which to perform the comparison
1620 * @param o name of the object
1621 * @param cmp_buf buffer containing bytes to be compared with object contents
1622 * @param cmp_len length to compare and size of @c cmp_buf in bytes
1623 * @param off object byte offset at which to start the comparison
1624 * @returns 0 on success, negative error code on failure,
1625 * (-MAX_ERRNO - mismatch_off) on mismatch
1627 CEPH_RADOS_API
int rados_cmpext(rados_ioctx_t io
, const char *o
,
1628 const char *cmp_buf
, size_t cmp_len
,
1633 * Extended attributes are stored as extended attributes on the files
1634 * representing an object on the OSDs. Thus, they have the same
1635 * limitations as the underlying filesystem. On ext4, this means that
1636 * the total data stored in xattrs cannot exceed 4KB.
1642 * Get the value of an extended attribute on an object.
1644 * @param io the context in which the attribute is read
1645 * @param o name of the object
1646 * @param name which extended attribute to read
1647 * @param buf where to store the result
1648 * @param len size of buf in bytes
1649 * @returns length of xattr value on success, negative error code on failure
1651 CEPH_RADOS_API
int rados_getxattr(rados_ioctx_t io
, const char *o
,
1652 const char *name
, char *buf
, size_t len
);
1655 * Set an extended attribute on an object.
1657 * @param io the context in which xattr is set
1658 * @param o name of the object
1659 * @param name which extended attribute to set
1660 * @param buf what to store in the xattr
1661 * @param len the number of bytes in buf
1662 * @returns 0 on success, negative error code on failure
1664 CEPH_RADOS_API
int rados_setxattr(rados_ioctx_t io
, const char *o
,
1665 const char *name
, const char *buf
,
1669 * Delete an extended attribute from an object.
1671 * @param io the context in which to delete the xattr
1672 * @param o the name of the object
1673 * @param name which xattr to delete
1674 * @returns 0 on success, negative error code on failure
1676 CEPH_RADOS_API
int rados_rmxattr(rados_ioctx_t io
, const char *o
,
1680 * Start iterating over xattrs on an object.
1682 * @post iter is a valid iterator
1684 * @param io the context in which to list xattrs
1685 * @param oid name of the object
1686 * @param iter where to store the iterator
1687 * @returns 0 on success, negative error code on failure
1689 CEPH_RADOS_API
int rados_getxattrs(rados_ioctx_t io
, const char *oid
,
1690 rados_xattrs_iter_t
*iter
);
1693 * Get the next xattr on the object
1695 * @pre iter is a valid iterator
1697 * @post name is the NULL-terminated name of the next xattr, and val
1698 * contains the value of the xattr, which is of length len. If the end
1699 * of the list has been reached, name and val are NULL, and len is 0.
1701 * @param iter iterator to advance
1702 * @param name where to store the name of the next xattr
1703 * @param val where to store the value of the next xattr
1704 * @param len the number of bytes in val
1705 * @returns 0 on success, negative error code on failure
1707 CEPH_RADOS_API
int rados_getxattrs_next(rados_xattrs_iter_t iter
,
1708 const char **name
, const char **val
,
1712 * Close the xattr iterator.
1714 * iter should not be used after this is called.
1716 * @param iter the iterator to close
1718 CEPH_RADOS_API
void rados_getxattrs_end(rados_xattrs_iter_t iter
);
1723 * Get the next omap key/value pair on the object
1725 * @pre iter is a valid iterator
1727 * @post key and val are the next key/value pair. key is
1728 * null-terminated, and val has length len. If the end of the list has
1729 * been reached, key and val are NULL, and len is 0. key and val will
1730 * not be accessible after rados_omap_get_end() is called on iter, so
1731 * if they are needed after that they should be copied.
1733 * @param iter iterator to advance
1734 * @param key where to store the key of the next omap entry
1735 * @param val where to store the value of the next omap entry
1736 * @param len where to store the number of bytes in val
1737 * @returns 0 on success, negative error code on failure
1739 CEPH_RADOS_API
int rados_omap_get_next(rados_omap_iter_t iter
,
1745 * Get the next omap key/value pair on the object. Note that it's
1746 * perfectly safe to mix calls to rados_omap_get_next and
1747 * rados_omap_get_next2.
1749 * @pre iter is a valid iterator
1751 * @post key and val are the next key/value pair. key has length
1752 * keylen and val has length vallen. If the end of the list has
1753 * been reached, key and val are NULL, and keylen and vallen is 0.
1754 * key and val will not be accessible after rados_omap_get_end()
1755 * is called on iter, so if they are needed after that they
1758 * @param iter iterator to advance
1759 * @param key where to store the key of the next omap entry
1760 * @param val where to store the value of the next omap entry
1761 * @param key_len where to store the number of bytes in key
1762 * @param val_len where to store the number of bytes in val
1763 * @returns 0 on success, negative error code on failure
1765 CEPH_RADOS_API
int rados_omap_get_next2(rados_omap_iter_t iter
,
1772 * Return number of elements in the iterator
1774 * @param iter the iterator of which to return the size
1776 CEPH_RADOS_API
unsigned int rados_omap_iter_size(rados_omap_iter_t iter
);
1779 * Close the omap iterator.
1781 * iter should not be used after this is called.
1783 * @param iter the iterator to close
1785 CEPH_RADOS_API
void rados_omap_get_end(rados_omap_iter_t iter
);
1788 * Get object stats (size/mtime)
1790 * TODO: when are these set, and by whom? can they be out of date?
1793 * @param o object name
1794 * @param psize where to store object size
1795 * @param pmtime where to store modification time
1796 * @returns 0 on success, negative error code on failure
1798 CEPH_RADOS_API
int rados_stat(rados_ioctx_t io
, const char *o
, uint64_t *psize
,
1801 * Execute an OSD class method on an object
1803 * The OSD has a plugin mechanism for performing complicated
1804 * operations on an object atomically. These plugins are called
1805 * classes. This function allows librados users to call the custom
1806 * methods. The input and output formats are defined by the class.
1807 * Classes in ceph.git can be found in src/cls subdirectories
1809 * @param io the context in which to call the method
1810 * @param oid the object to call the method on
1811 * @param cls the name of the class
1812 * @param method the name of the method
1813 * @param in_buf where to find input
1814 * @param in_len length of in_buf in bytes
1815 * @param buf where to store output
1816 * @param out_len length of buf in bytes
1817 * @returns the length of the output, or
1818 * -ERANGE if out_buf does not have enough space to store it (For methods that return data). For
1819 * methods that don't return data, the return value is
1822 CEPH_RADOS_API
int rados_exec(rados_ioctx_t io
, const char *oid
,
1823 const char *cls
, const char *method
,
1824 const char *in_buf
, size_t in_len
, char *buf
,
1828 /** @} Synchronous I/O */
1831 * @name Asynchronous I/O
1832 * Read and write to objects without blocking.
1838 * @typedef rados_callback_t
1839 * Callbacks for asynchrous operations take two parameters:
1840 * - cb the completion that has finished
1841 * - arg application defined data made available to the callback function
1843 typedef void (*rados_callback_t
)(rados_completion_t cb
, void *arg
);
1846 * Constructs a completion to use with asynchronous operations
1848 * The complete and safe callbacks correspond to operations being
1849 * acked and committed, respectively. The callbacks are called in
1850 * order of receipt, so the safe callback may be triggered before the
1851 * complete callback, and vice versa. This is affected by journalling
1854 * TODO: more complete documentation of this elsewhere (in the RADOS docs?)
1856 * @note Read operations only get a complete callback.
1857 * @note BUG: this should check for ENOMEM instead of throwing an exception
1859 * @param cb_arg application-defined data passed to the callback functions
1860 * @param cb_complete the function to be called when the operation is
1861 * in memory on all replicas
1862 * @param cb_safe the function to be called when the operation is on
1863 * stable storage on all replicas
1864 * @param pc where to store the completion
1867 CEPH_RADOS_API
int rados_aio_create_completion(void *cb_arg
,
1868 rados_callback_t cb_complete
,
1869 rados_callback_t cb_safe
,
1870 rados_completion_t
*pc
);
1873 * Constructs a completion to use with asynchronous operations
1875 * The complete callback corresponds to operation being acked.
1877 * @note BUG: this should check for ENOMEM instead of throwing an exception
1879 * @param cb_arg application-defined data passed to the callback functions
1880 * @param cb_complete the function to be called when the operation is committed
1882 * @param pc where to store the completion
1885 CEPH_RADOS_API
int rados_aio_create_completion2(void *cb_arg
,
1886 rados_callback_t cb_complete
,
1887 rados_completion_t
*pc
);
1890 * Block until an operation completes
1892 * This means it is in memory on all replicas.
1894 * @note BUG: this should be void
1896 * @param c operation to wait for
1899 CEPH_RADOS_API
int rados_aio_wait_for_complete(rados_completion_t c
);
1902 * Block until an operation is safe
1904 * This means it is on stable storage on all replicas.
1906 * @note BUG: this should be void
1908 * @param c operation to wait for
1911 CEPH_RADOS_API
int rados_aio_wait_for_safe(rados_completion_t c
)
1912 __attribute__((deprecated
));
1915 * Has an asynchronous operation completed?
1917 * @warning This does not imply that the complete callback has
1920 * @param c async operation to inspect
1921 * @returns whether c is complete
1923 CEPH_RADOS_API
int rados_aio_is_complete(rados_completion_t c
);
1926 * Is an asynchronous operation safe?
1928 * @warning This does not imply that the safe callback has
1931 * @param c async operation to inspect
1932 * @returns whether c is safe
1934 CEPH_RADOS_API
int rados_aio_is_safe(rados_completion_t c
);
1937 * Block until an operation completes and callback completes
1939 * This means it is in memory on all replicas and can be read.
1941 * @note BUG: this should be void
1943 * @param c operation to wait for
1946 CEPH_RADOS_API
int rados_aio_wait_for_complete_and_cb(rados_completion_t c
);
1949 * Block until an operation is safe and callback has completed
1951 * This means it is on stable storage on all replicas.
1953 * @note BUG: this should be void
1955 * @param c operation to wait for
1958 CEPH_RADOS_API
int rados_aio_wait_for_safe_and_cb(rados_completion_t c
)
1959 __attribute__((deprecated
));
1962 * Has an asynchronous operation and callback completed
1964 * @param c async operation to inspect
1965 * @returns whether c is complete
1967 CEPH_RADOS_API
int rados_aio_is_complete_and_cb(rados_completion_t c
);
1970 * Is an asynchronous operation safe and has the callback completed
1972 * @param c async operation to inspect
1973 * @returns whether c is safe
1975 CEPH_RADOS_API
int rados_aio_is_safe_and_cb(rados_completion_t c
);
1978 * Get the return value of an asychronous operation
1980 * The return value is set when the operation is complete or safe,
1981 * whichever comes first.
1983 * @pre The operation is safe or complete
1985 * @note BUG: complete callback may never be called when the safe
1986 * message is received before the complete message
1988 * @param c async operation to inspect
1989 * @returns return value of the operation
1991 CEPH_RADOS_API
int rados_aio_get_return_value(rados_completion_t c
);
1994 * Get the internal object version of the target of an asychronous operation
1996 * The return value is set when the operation is complete or safe,
1997 * whichever comes first.
1999 * @pre The operation is safe or complete
2001 * @note BUG: complete callback may never be called when the safe
2002 * message is received before the complete message
2004 * @param c async operation to inspect
2005 * @returns version number of the asychronous operation's target
2007 CEPH_RADOS_API
uint64_t rados_aio_get_version(rados_completion_t c
);
2010 * Release a completion
2012 * Call this when you no longer need the completion. It may not be
2013 * freed immediately if the operation is not acked and committed.
2015 * @param c completion to release
2017 CEPH_RADOS_API
void rados_aio_release(rados_completion_t c
);
2020 * Write data to an object asynchronously
2022 * Queues the write and returns. The return value of the completion
2023 * will be 0 on success, negative error code on failure.
2025 * @param io the context in which the write will occur
2026 * @param oid name of the object
2027 * @param completion what to do when the write is safe and complete
2028 * @param buf data to write
2029 * @param len length of the data, in bytes
2030 * @param off byte offset in the object to begin writing at
2031 * @returns 0 on success, -EROFS if the io context specifies a snap_seq
2032 * other than LIBRADOS_SNAP_HEAD
2034 CEPH_RADOS_API
int rados_aio_write(rados_ioctx_t io
, const char *oid
,
2035 rados_completion_t completion
,
2036 const char *buf
, size_t len
, uint64_t off
);
2039 * Asynchronously append data to an object
2041 * Queues the append and returns.
2043 * The return value of the completion will be 0 on success, negative
2044 * error code on failure.
2046 * @param io the context to operate in
2047 * @param oid the name of the object
2048 * @param completion what to do when the append is safe and complete
2049 * @param buf the data to append
2050 * @param len length of buf (in bytes)
2051 * @returns 0 on success, -EROFS if the io context specifies a snap_seq
2052 * other than LIBRADOS_SNAP_HEAD
2054 CEPH_RADOS_API
int rados_aio_append(rados_ioctx_t io
, const char *oid
,
2055 rados_completion_t completion
,
2056 const char *buf
, size_t len
);
2059 * Asynchronously write an entire object
2061 * The object is filled with the provided data. If the object exists,
2062 * it is atomically truncated and then written.
2063 * Queues the write_full and returns.
2065 * The return value of the completion will be 0 on success, negative
2066 * error code on failure.
2068 * @param io the io context in which the write will occur
2069 * @param oid name of the object
2070 * @param completion what to do when the write_full is safe and complete
2071 * @param buf data to write
2072 * @param len length of the data, in bytes
2073 * @returns 0 on success, -EROFS if the io context specifies a snap_seq
2074 * other than LIBRADOS_SNAP_HEAD
2076 CEPH_RADOS_API
int rados_aio_write_full(rados_ioctx_t io
, const char *oid
,
2077 rados_completion_t completion
,
2078 const char *buf
, size_t len
);
2081 * Asynchronously write the same buffer multiple times
2083 * Queues the writesame and returns.
2085 * The return value of the completion will be 0 on success, negative
2086 * error code on failure.
2088 * @param io the io context in which the write will occur
2089 * @param oid name of the object
2090 * @param completion what to do when the writesame is safe and complete
2091 * @param buf data to write
2092 * @param data_len length of the data, in bytes
2093 * @param write_len the total number of bytes to write
2094 * @param off byte offset in the object to begin writing at
2095 * @returns 0 on success, -EROFS if the io context specifies a snap_seq
2096 * other than LIBRADOS_SNAP_HEAD
2098 CEPH_RADOS_API
int rados_aio_writesame(rados_ioctx_t io
, const char *oid
,
2099 rados_completion_t completion
,
2100 const char *buf
, size_t data_len
,
2101 size_t write_len
, uint64_t off
);
2104 * Asynchronously remove an object
2106 * Queues the remove and returns.
2108 * The return value of the completion will be 0 on success, negative
2109 * error code on failure.
2111 * @param io the context to operate in
2112 * @param oid the name of the object
2113 * @param completion what to do when the remove is safe and complete
2114 * @returns 0 on success, -EROFS if the io context specifies a snap_seq
2115 * other than LIBRADOS_SNAP_HEAD
2117 CEPH_RADOS_API
int rados_aio_remove(rados_ioctx_t io
, const char *oid
,
2118 rados_completion_t completion
);
2121 * Asynchronously read data from an object
2123 * The io context determines the snapshot to read from, if any was set
2124 * by rados_ioctx_snap_set_read().
2126 * The return value of the completion will be number of bytes read on
2127 * success, negative error code on failure.
2129 * @note only the 'complete' callback of the completion will be called.
2131 * @param io the context in which to perform the read
2132 * @param oid the name of the object to read from
2133 * @param completion what to do when the read is complete
2134 * @param buf where to store the results
2135 * @param len the number of bytes to read
2136 * @param off the offset to start reading from in the object
2137 * @returns 0 on success, negative error code on failure
2139 CEPH_RADOS_API
int rados_aio_read(rados_ioctx_t io
, const char *oid
,
2140 rados_completion_t completion
,
2141 char *buf
, size_t len
, uint64_t off
);
2144 * Block until all pending writes in an io context are safe
2146 * This is not equivalent to calling rados_aio_wait_for_safe() on all
2147 * write completions, since this waits for the associated callbacks to
2150 * @note BUG: always returns 0, should be void or accept a timeout
2152 * @param io the context to flush
2153 * @returns 0 on success, negative error code on failure
2155 CEPH_RADOS_API
int rados_aio_flush(rados_ioctx_t io
);
2159 * Schedule a callback for when all currently pending
2160 * aio writes are safe. This is a non-blocking version of
2161 * rados_aio_flush().
2163 * @param io the context to flush
2164 * @param completion what to do when the writes are safe
2165 * @returns 0 on success, negative error code on failure
2167 CEPH_RADOS_API
int rados_aio_flush_async(rados_ioctx_t io
,
2168 rados_completion_t completion
);
2172 * Asynchronously get object stats (size/mtime)
2175 * @param o object name
2176 * @param completion what to do when the stat is complete
2177 * @param psize where to store object size
2178 * @param pmtime where to store modification time
2179 * @returns 0 on success, negative error code on failure
2181 CEPH_RADOS_API
int rados_aio_stat(rados_ioctx_t io
, const char *o
,
2182 rados_completion_t completion
,
2183 uint64_t *psize
, time_t *pmtime
);
2186 * Asynchronously compare an on-disk object range with a buffer
2188 * @param io the context in which to perform the comparison
2189 * @param o the name of the object to compare with
2190 * @param completion what to do when the comparison is complete
2191 * @param cmp_buf buffer containing bytes to be compared with object contents
2192 * @param cmp_len length to compare and size of @c cmp_buf in bytes
2193 * @param off object byte offset at which to start the comparison
2194 * @returns 0 on success, negative error code on failure,
2195 * (-MAX_ERRNO - mismatch_off) on mismatch
2197 CEPH_RADOS_API
int rados_aio_cmpext(rados_ioctx_t io
, const char *o
,
2198 rados_completion_t completion
,
2199 const char *cmp_buf
,
2204 * Cancel async operation
2207 * @param completion completion handle
2208 * @returns 0 on success, negative error code on failure
2210 CEPH_RADOS_API
int rados_aio_cancel(rados_ioctx_t io
,
2211 rados_completion_t completion
);
2214 * Asynchronously execute an OSD class method on an object
2216 * The OSD has a plugin mechanism for performing complicated
2217 * operations on an object atomically. These plugins are called
2218 * classes. This function allows librados users to call the custom
2219 * methods. The input and output formats are defined by the class.
2220 * Classes in ceph.git can be found in src/cls subdirectories
2222 * @param io the context in which to call the method
2223 * @param o name of the object
2224 * @param completion what to do when the exec completes
2225 * @param cls the name of the class
2226 * @param method the name of the method
2227 * @param in_buf where to find input
2228 * @param in_len length of in_buf in bytes
2229 * @param buf where to store output
2230 * @param out_len length of buf in bytes
2231 * @returns 0 on success, negative error code on failure
2233 CEPH_RADOS_API
int rados_aio_exec(rados_ioctx_t io
, const char *o
,
2234 rados_completion_t completion
,
2235 const char *cls
, const char *method
,
2236 const char *in_buf
, size_t in_len
,
2237 char *buf
, size_t out_len
);
2239 /** @} Asynchronous I/O */
2242 * @name Asynchronous Xattrs
2243 * Extended attributes are stored as extended attributes on the files
2244 * representing an object on the OSDs. Thus, they have the same
2245 * limitations as the underlying filesystem. On ext4, this means that
2246 * the total data stored in xattrs cannot exceed 4KB.
2252 * Asynchronously get the value of an extended attribute on an object.
2254 * @param io the context in which the attribute is read
2255 * @param o name of the object
2256 * @param completion what to do when the getxattr completes
2257 * @param name which extended attribute to read
2258 * @param buf where to store the result
2259 * @param len size of buf in bytes
2260 * @returns length of xattr value on success, negative error code on failure
2262 CEPH_RADOS_API
int rados_aio_getxattr(rados_ioctx_t io
, const char *o
,
2263 rados_completion_t completion
,
2264 const char *name
, char *buf
, size_t len
);
2267 * Asynchronously set an extended attribute on an object.
2269 * @param io the context in which xattr is set
2270 * @param o name of the object
2271 * @param completion what to do when the setxattr completes
2272 * @param name which extended attribute to set
2273 * @param buf what to store in the xattr
2274 * @param len the number of bytes in buf
2275 * @returns 0 on success, negative error code on failure
2277 CEPH_RADOS_API
int rados_aio_setxattr(rados_ioctx_t io
, const char *o
,
2278 rados_completion_t completion
,
2279 const char *name
, const char *buf
,
2283 * Asynchronously delete an extended attribute from an object.
2285 * @param io the context in which to delete the xattr
2286 * @param o the name of the object
2287 * @param completion what to do when the rmxattr completes
2288 * @param name which xattr to delete
2289 * @returns 0 on success, negative error code on failure
2291 CEPH_RADOS_API
int rados_aio_rmxattr(rados_ioctx_t io
, const char *o
,
2292 rados_completion_t completion
,
2296 * Asynchronously start iterating over xattrs on an object.
2298 * @post iter is a valid iterator
2300 * @param io the context in which to list xattrs
2301 * @param oid name of the object
2302 * @param completion what to do when the getxattrs completes
2303 * @param iter where to store the iterator
2304 * @returns 0 on success, negative error code on failure
2306 CEPH_RADOS_API
int rados_aio_getxattrs(rados_ioctx_t io
, const char *oid
,
2307 rados_completion_t completion
,
2308 rados_xattrs_iter_t
*iter
);
2310 /** @} Asynchronous Xattrs */
2313 * @name Watch/Notify
2315 * Watch/notify is a protocol to help communicate among clients. It
2316 * can be used to sychronize client state. All that's needed is a
2317 * well-known object name (for example, rbd uses the header object of
2320 * Watchers register an interest in an object, and receive all
2321 * notifies on that object. A notify attempts to communicate with all
2322 * clients watching an object, and blocks on the notifier until each
2323 * client responds or a timeout is reached.
2325 * See rados_watch() and rados_notify() for more details.
2331 * @typedef rados_watchcb_t
2333 * Callback activated when a notify is received on a watched
2336 * @param opcode undefined
2337 * @param ver version of the watched object
2338 * @param arg application-specific data
2340 * @note BUG: opcode is an internal detail that shouldn't be exposed
2341 * @note BUG: ver is unused
2343 typedef void (*rados_watchcb_t
)(uint8_t opcode
, uint64_t ver
, void *arg
);
2346 * @typedef rados_watchcb2_t
2348 * Callback activated when a notify is received on a watched
2351 * @param arg opaque user-defined value provided to rados_watch2()
2352 * @param notify_id an id for this notify event
2353 * @param handle the watcher handle we are notifying
2354 * @param notifier_id the unique client id for the notifier
2355 * @param data payload from the notifier
2356 * @param datalen length of payload buffer
2358 typedef void (*rados_watchcb2_t
)(void *arg
,
2361 uint64_t notifier_id
,
2366 * @typedef rados_watcherrcb_t
2368 * Callback activated when we encounter an error with the watch session.
2369 * This can happen when the location of the objects moves within the
2370 * cluster and we fail to register our watch with the new object location,
2371 * or when our connection with the object OSD is otherwise interrupted and
2372 * we may have missed notify events.
2374 * @param pre opaque user-defined value provided to rados_watch2()
2375 * @param err error code
2377 typedef void (*rados_watcherrcb_t
)(void *pre
, uint64_t cookie
, int err
);
2380 * Register an interest in an object
2382 * A watch operation registers the client as being interested in
2383 * notifications on an object. OSDs keep track of watches on
2384 * persistent storage, so they are preserved across cluster changes by
2385 * the normal recovery process. If the client loses its connection to
2386 * the primary OSD for a watched object, the watch will be removed
2387 * after 30 seconds. Watches are automatically reestablished when a new
2388 * connection is made, or a placement group switches OSDs.
2390 * @note BUG: librados should provide a way for watchers to notice connection resets
2391 * @note BUG: the ver parameter does not work, and -ERANGE will never be returned
2392 * (See URL tracker.ceph.com/issues/2592)
2394 * @param io the pool the object is in
2395 * @param o the object to watch
2396 * @param ver expected version of the object
2397 * @param cookie where to store the internal id assigned to this watch
2398 * @param watchcb what to do when a notify is received on this object
2399 * @param arg application defined data to pass when watchcb is called
2400 * @returns 0 on success, negative error code on failure
2401 * @returns -ERANGE if the version of the object is greater than ver
2403 CEPH_RADOS_API
int rados_watch(rados_ioctx_t io
, const char *o
, uint64_t ver
,
2405 rados_watchcb_t watchcb
, void *arg
)
2406 __attribute__((deprecated
));
2410 * Register an interest in an object
2412 * A watch operation registers the client as being interested in
2413 * notifications on an object. OSDs keep track of watches on
2414 * persistent storage, so they are preserved across cluster changes by
2415 * the normal recovery process. If the client loses its connection to the
2416 * primary OSD for a watched object, the watch will be removed after
2417 * a timeout configured with osd_client_watch_timeout.
2418 * Watches are automatically reestablished when a new
2419 * connection is made, or a placement group switches OSDs.
2421 * @param io the pool the object is in
2422 * @param o the object to watch
2423 * @param cookie where to store the internal id assigned to this watch
2424 * @param watchcb what to do when a notify is received on this object
2425 * @param watcherrcb what to do when the watch session encounters an error
2426 * @param arg opaque value to pass to the callback
2427 * @returns 0 on success, negative error code on failure
2429 CEPH_RADOS_API
int rados_watch2(rados_ioctx_t io
, const char *o
, uint64_t *cookie
,
2430 rados_watchcb2_t watchcb
,
2431 rados_watcherrcb_t watcherrcb
,
2435 * Register an interest in an object
2437 * A watch operation registers the client as being interested in
2438 * notifications on an object. OSDs keep track of watches on
2439 * persistent storage, so they are preserved across cluster changes by
2440 * the normal recovery process. Watches are automatically reestablished when a new
2441 * connection is made, or a placement group switches OSDs.
2443 * @param io the pool the object is in
2444 * @param o the object to watch
2445 * @param cookie where to store the internal id assigned to this watch
2446 * @param watchcb what to do when a notify is received on this object
2447 * @param watcherrcb what to do when the watch session encounters an error
2448 * @param timeout how many seconds the connection will keep after disconnection
2449 * @param arg opaque value to pass to the callback
2450 * @returns 0 on success, negative error code on failure
2452 CEPH_RADOS_API
int rados_watch3(rados_ioctx_t io
, const char *o
, uint64_t *cookie
,
2453 rados_watchcb2_t watchcb
,
2454 rados_watcherrcb_t watcherrcb
,
2459 * Asynchronous register an interest in an object
2461 * A watch operation registers the client as being interested in
2462 * notifications on an object. OSDs keep track of watches on
2463 * persistent storage, so they are preserved across cluster changes by
2464 * the normal recovery process. If the client loses its connection to
2465 * the primary OSD for a watched object, the watch will be removed
2466 * after 30 seconds. Watches are automatically reestablished when a new
2467 * connection is made, or a placement group switches OSDs.
2469 * @param io the pool the object is in
2470 * @param o the object to watch
2471 * @param completion what to do when operation has been attempted
2472 * @param handle where to store the internal id assigned to this watch
2473 * @param watchcb what to do when a notify is received on this object
2474 * @param watcherrcb what to do when the watch session encounters an error
2475 * @param arg opaque value to pass to the callback
2476 * @returns 0 on success, negative error code on failure
2478 CEPH_RADOS_API
int rados_aio_watch(rados_ioctx_t io
, const char *o
,
2479 rados_completion_t completion
, uint64_t *handle
,
2480 rados_watchcb2_t watchcb
,
2481 rados_watcherrcb_t watcherrcb
,
2485 * Asynchronous register an interest in an object
2487 * A watch operation registers the client as being interested in
2488 * notifications on an object. OSDs keep track of watches on
2489 * persistent storage, so they are preserved across cluster changes by
2490 * the normal recovery process. If the client loses its connection to
2491 * the primary OSD for a watched object, the watch will be removed
2492 * after the number of seconds that configured in timeout parameter.
2493 * Watches are automatically reestablished when a new
2494 * connection is made, or a placement group switches OSDs.
2496 * @param io the pool the object is in
2497 * @param o the object to watch
2498 * @param completion what to do when operation has been attempted
2499 * @param handle where to store the internal id assigned to this watch
2500 * @param watchcb what to do when a notify is received on this object
2501 * @param watcherrcb what to do when the watch session encounters an error
2502 * @param timeout how many seconds the connection will keep after disconnection
2503 * @param arg opaque value to pass to the callback
2504 * @returns 0 on success, negative error code on failure
2506 CEPH_RADOS_API
int rados_aio_watch2(rados_ioctx_t io
, const char *o
,
2507 rados_completion_t completion
, uint64_t *handle
,
2508 rados_watchcb2_t watchcb
,
2509 rados_watcherrcb_t watcherrcb
,
2514 * Check on the status of a watch
2516 * Return the number of milliseconds since the watch was last confirmed.
2517 * Or, if there has been an error, return that.
2519 * If there is an error, the watch is no longer valid, and should be
2520 * destroyed with rados_unwatch2(). The the user is still interested
2521 * in the object, a new watch should be created with rados_watch2().
2523 * @param io the pool the object is in
2524 * @param cookie the watch handle
2525 * @returns ms since last confirmed on success, negative error code on failure
2527 CEPH_RADOS_API
int rados_watch_check(rados_ioctx_t io
, uint64_t cookie
);
2530 * Unregister an interest in an object
2532 * Once this completes, no more notifies will be sent to us for this
2533 * watch. This should be called to clean up unneeded watchers.
2535 * @param io the pool the object is in
2536 * @param o the name of the watched object (ignored)
2537 * @param cookie which watch to unregister
2538 * @returns 0 on success, negative error code on failure
2540 CEPH_RADOS_API
int rados_unwatch(rados_ioctx_t io
, const char *o
, uint64_t cookie
)
2541 __attribute__((deprecated
));
2544 * Unregister an interest in an object
2546 * Once this completes, no more notifies will be sent to us for this
2547 * watch. This should be called to clean up unneeded watchers.
2549 * @param io the pool the object is in
2550 * @param cookie which watch to unregister
2551 * @returns 0 on success, negative error code on failure
2553 CEPH_RADOS_API
int rados_unwatch2(rados_ioctx_t io
, uint64_t cookie
);
2556 * Asynchronous unregister an interest in an object
2558 * Once this completes, no more notifies will be sent to us for this
2559 * watch. This should be called to clean up unneeded watchers.
2561 * @param io the pool the object is in
2562 * @param completion what to do when operation has been attempted
2563 * @param cookie which watch to unregister
2564 * @returns 0 on success, negative error code on failure
2566 CEPH_RADOS_API
int rados_aio_unwatch(rados_ioctx_t io
, uint64_t cookie
,
2567 rados_completion_t completion
);
2570 * Sychronously notify watchers of an object
2572 * This blocks until all watchers of the object have received and
2573 * reacted to the notify, or a timeout is reached.
2575 * @note BUG: the timeout is not changeable via the C API
2576 * @note BUG: the bufferlist is inaccessible in a rados_watchcb_t
2578 * @param io the pool the object is in
2579 * @param o the name of the object
2580 * @param ver obsolete - just pass zero
2581 * @param buf data to send to watchers
2582 * @param buf_len length of buf in bytes
2583 * @returns 0 on success, negative error code on failure
2585 CEPH_RADOS_API
int rados_notify(rados_ioctx_t io
, const char *o
, uint64_t ver
,
2586 const char *buf
, int buf_len
)
2587 __attribute__((deprecated
));
2590 * Sychronously notify watchers of an object
2592 * This blocks until all watchers of the object have received and
2593 * reacted to the notify, or a timeout is reached.
2595 * The reply buffer is optional. If specified, the client will get
2596 * back an encoded buffer that includes the ids of the clients that
2597 * acknowledged the notify as well as their notify ack payloads (if
2598 * any). Clients that timed out are not included. Even clients that
2599 * do not include a notify ack payload are included in the list but
2600 * have a 0-length payload associated with them. The format:
2604 * le64 gid global id for the client (for client.1234 that's 1234)
2605 * le64 cookie cookie for the client
2606 * le32 buflen length of reply message buffer
2607 * u8 * buflen payload
2611 * le64 gid global id for the client
2612 * le64 cookie cookie for the client
2615 * Note: There may be multiple instances of the same gid if there are
2616 * multiple watchers registered via the same client.
2618 * Note: The buffer must be released with rados_buffer_free() when the
2619 * user is done with it.
2621 * Note: Since the result buffer includes clients that time out, it
2622 * will be set even when rados_notify() returns an error code (like
2625 * @param io the pool the object is in
2626 * @param completion what to do when operation has been attempted
2627 * @param o the name of the object
2628 * @param buf data to send to watchers
2629 * @param buf_len length of buf in bytes
2630 * @param timeout_ms notify timeout (in ms)
2631 * @param reply_buffer pointer to reply buffer pointer (free with rados_buffer_free)
2632 * @param reply_buffer_len pointer to size of reply buffer
2633 * @returns 0 on success, negative error code on failure
2635 CEPH_RADOS_API
int rados_aio_notify(rados_ioctx_t io
, const char *o
,
2636 rados_completion_t completion
,
2637 const char *buf
, int buf_len
,
2638 uint64_t timeout_ms
, char **reply_buffer
,
2639 size_t *reply_buffer_len
);
2640 CEPH_RADOS_API
int rados_notify2(rados_ioctx_t io
, const char *o
,
2641 const char *buf
, int buf_len
,
2642 uint64_t timeout_ms
,
2643 char **reply_buffer
, size_t *reply_buffer_len
);
2646 * Acknolwedge receipt of a notify
2648 * @param io the pool the object is in
2649 * @param o the name of the object
2650 * @param notify_id the notify_id we got on the watchcb2_t callback
2651 * @param cookie the watcher handle
2652 * @param buf payload to return to notifier (optional)
2653 * @param buf_len payload length
2654 * @returns 0 on success
2656 CEPH_RADOS_API
int rados_notify_ack(rados_ioctx_t io
, const char *o
,
2657 uint64_t notify_id
, uint64_t cookie
,
2658 const char *buf
, int buf_len
);
2661 * Flush watch/notify callbacks
2663 * This call will block until all pending watch/notify callbacks have
2664 * been executed and the queue is empty. It should usually be called
2665 * after shutting down any watches before shutting down the ioctx or
2666 * librados to ensure that any callbacks do not misuse the ioctx (for
2667 * example by calling rados_notify_ack after the ioctx has been
2670 * @param cluster the cluster handle
2672 CEPH_RADOS_API
int rados_watch_flush(rados_t cluster
);
2674 * Flush watch/notify callbacks
2676 * This call will be nonblock, and the completion will be called
2677 * until all pending watch/notify callbacks have been executed and
2678 * the queue is empty. It should usually be called after shutting
2679 * down any watches before shutting down the ioctx or
2680 * librados to ensure that any callbacks do not misuse the ioctx (for
2681 * example by calling rados_notify_ack after the ioctx has been
2684 * @param cluster the cluster handle
2685 * @param completion what to do when operation has been attempted
2687 CEPH_RADOS_API
int rados_aio_watch_flush(rados_t cluster
, rados_completion_t completion
);
2689 /** @} Watch/Notify */
2692 * Pin an object in the cache tier
2694 * When an object is pinned in the cache tier, it stays in the cache
2695 * tier, and won't be flushed out.
2697 * @param io the pool the object is in
2698 * @param o the object id
2699 * @returns 0 on success, negative error code on failure
2701 CEPH_RADOS_API
int rados_cache_pin(rados_ioctx_t io
, const char *o
);
2704 * Unpin an object in the cache tier
2706 * After an object is unpinned in the cache tier, it can be flushed out
2708 * @param io the pool the object is in
2709 * @param o the object id
2710 * @returns 0 on success, negative error code on failure
2712 CEPH_RADOS_API
int rados_cache_unpin(rados_ioctx_t io
, const char *o
);
2721 * Set allocation hint for an object
2723 * This is an advisory operation, it will always succeed (as if it was
2724 * submitted with a LIBRADOS_OP_FLAG_FAILOK flag set) and is not
2725 * guaranteed to do anything on the backend.
2727 * @param io the pool the object is in
2728 * @param o the name of the object
2729 * @param expected_object_size expected size of the object, in bytes
2730 * @param expected_write_size expected size of writes to the object, in bytes
2731 * @returns 0 on success, negative error code on failure
2733 CEPH_RADOS_API
int rados_set_alloc_hint(rados_ioctx_t io
, const char *o
,
2734 uint64_t expected_object_size
,
2735 uint64_t expected_write_size
);
2738 * Set allocation hint for an object
2740 * This is an advisory operation, it will always succeed (as if it was
2741 * submitted with a LIBRADOS_OP_FLAG_FAILOK flag set) and is not
2742 * guaranteed to do anything on the backend.
2744 * @param io the pool the object is in
2745 * @param o the name of the object
2746 * @param expected_object_size expected size of the object, in bytes
2747 * @param expected_write_size expected size of writes to the object, in bytes
2748 * @param flags hints about future IO patterns
2749 * @returns 0 on success, negative error code on failure
2751 CEPH_RADOS_API
int rados_set_alloc_hint2(rados_ioctx_t io
, const char *o
,
2752 uint64_t expected_object_size
,
2753 uint64_t expected_write_size
,
2759 * @name Object Operations
2761 * A single rados operation can do multiple operations on one object
2762 * atomically. The whole operation will succeed or fail, and no partial
2763 * results will be visible.
2765 * Operations may be either reads, which can return data, or writes,
2766 * which cannot. The effects of writes are applied and visible all at
2767 * once, so an operation that sets an xattr and then checks its value
2768 * will not see the updated value.
2774 * Create a new rados_write_op_t write operation. This will store all actions
2775 * to be performed atomically. You must call rados_release_write_op when you are
2778 * @returns non-NULL on success, NULL on memory allocation error.
2780 CEPH_RADOS_API rados_write_op_t
rados_create_write_op(void);
2783 * Free a rados_write_op_t, must be called when you're done with it.
2784 * @param write_op operation to deallocate, created with rados_create_write_op
2786 CEPH_RADOS_API
void rados_release_write_op(rados_write_op_t write_op
);
2789 * Set flags for the last operation added to this write_op.
2790 * At least one op must have been added to the write_op.
2791 * @param write_op operation to add this action to
2792 * @param flags see librados.h constants beginning with LIBRADOS_OP_FLAG
2794 CEPH_RADOS_API
void rados_write_op_set_flags(rados_write_op_t write_op
,
2798 * Ensure that the object exists before writing
2799 * @param write_op operation to add this action to
2801 CEPH_RADOS_API
void rados_write_op_assert_exists(rados_write_op_t write_op
);
2804 * Ensure that the object exists and that its internal version
2805 * number is equal to "ver" before writing. "ver" should be a
2806 * version number previously obtained with rados_get_last_version().
2807 * - If the object's version is greater than the asserted version
2808 * then rados_write_op_operate will return -ERANGE instead of
2810 * - If the object's version is less than the asserted version
2811 * then rados_write_op_operate will return -EOVERFLOW instead
2812 * of executing the op.
2813 * @param write_op operation to add this action to
2814 * @param ver object version number
2816 CEPH_RADOS_API
void rados_write_op_assert_version(rados_write_op_t write_op
, uint64_t ver
);
2819 * Ensure that given object range (extent) satisfies comparison.
2821 * @param write_op operation to add this action to
2822 * @param cmp_buf buffer containing bytes to be compared with object contents
2823 * @param cmp_len length to compare and size of @c cmp_buf in bytes
2824 * @param off object byte offset at which to start the comparison
2825 * @param prval returned result of comparison, 0 on success, negative error code
2826 * on failure, (-MAX_ERRNO - mismatch_off) on mismatch
2828 CEPH_RADOS_API
void rados_write_op_cmpext(rados_write_op_t write_op
,
2829 const char *cmp_buf
,
2835 * Ensure that given xattr satisfies comparison.
2836 * If the comparison is not satisfied, the return code of the
2837 * operation will be -ECANCELED
2838 * @param write_op operation to add this action to
2839 * @param name name of the xattr to look up
2840 * @param comparison_operator currently undocumented, look for
2841 * LIBRADOS_CMPXATTR_OP_EQ in librados.h
2842 * @param value buffer to compare actual xattr value to
2843 * @param value_len length of buffer to compare actual xattr value to
2845 CEPH_RADOS_API
void rados_write_op_cmpxattr(rados_write_op_t write_op
,
2847 uint8_t comparison_operator
,
2852 * Ensure that the an omap value satisfies a comparison,
2853 * with the supplied value on the right hand side (i.e.
2854 * for OP_LT, the comparison is actual_value < value.
2856 * @param write_op operation to add this action to
2857 * @param key which omap value to compare
2858 * @param comparison_operator one of LIBRADOS_CMPXATTR_OP_EQ,
2859 LIBRADOS_CMPXATTR_OP_LT, or LIBRADOS_CMPXATTR_OP_GT
2860 * @param val value to compare with
2861 * @param val_len length of value in bytes
2862 * @param prval where to store the return value from this action
2864 CEPH_RADOS_API
void rados_write_op_omap_cmp(rados_write_op_t write_op
,
2866 uint8_t comparison_operator
,
2872 * Ensure that the an omap value satisfies a comparison,
2873 * with the supplied value on the right hand side (i.e.
2874 * for OP_LT, the comparison is actual_value < value.
2876 * @param write_op operation to add this action to
2877 * @param key which omap value to compare
2878 * @param comparison_operator one of LIBRADOS_CMPXATTR_OP_EQ,
2879 LIBRADOS_CMPXATTR_OP_LT, or LIBRADOS_CMPXATTR_OP_GT
2880 * @param val value to compare with
2881 * @param key_len length of key in bytes
2882 * @param val_len length of value in bytes
2883 * @param prval where to store the return value from this action
2885 CEPH_RADOS_API
void rados_write_op_omap_cmp2(rados_write_op_t write_op
,
2887 uint8_t comparison_operator
,
2895 * @param write_op operation to add this action to
2896 * @param name name of the xattr
2897 * @param value buffer to set xattr to
2898 * @param value_len length of buffer to set xattr to
2900 CEPH_RADOS_API
void rados_write_op_setxattr(rados_write_op_t write_op
,
2907 * @param write_op operation to add this action to
2908 * @param name name of the xattr to remove
2910 CEPH_RADOS_API
void rados_write_op_rmxattr(rados_write_op_t write_op
,
2915 * @param write_op operation to add this action to
2916 * @param exclusive set to either LIBRADOS_CREATE_EXCLUSIVE or
2917 LIBRADOS_CREATE_IDEMPOTENT
2918 * will error if the object already exists.
2919 * @param category category string (DEPRECATED, HAS NO EFFECT)
2921 CEPH_RADOS_API
void rados_write_op_create(rados_write_op_t write_op
,
2923 const char* category
);
2927 * @param write_op operation to add this action to
2928 * @param offset offset to write to
2929 * @param buffer bytes to write
2930 * @param len length of buffer
2932 CEPH_RADOS_API
void rados_write_op_write(rados_write_op_t write_op
,
2938 * Write whole object, atomically replacing it.
2939 * @param write_op operation to add this action to
2940 * @param buffer bytes to write
2941 * @param len length of buffer
2943 CEPH_RADOS_API
void rados_write_op_write_full(rados_write_op_t write_op
,
2948 * Write the same buffer multiple times
2949 * @param write_op operation to add this action to
2950 * @param buffer bytes to write
2951 * @param data_len length of buffer
2952 * @param write_len total number of bytes to write, as a multiple of @c data_len
2953 * @param offset offset to write to
2955 CEPH_RADOS_API
void rados_write_op_writesame(rados_write_op_t write_op
,
2962 * Append to end of object.
2963 * @param write_op operation to add this action to
2964 * @param buffer bytes to write
2965 * @param len length of buffer
2967 CEPH_RADOS_API
void rados_write_op_append(rados_write_op_t write_op
,
2972 * @param write_op operation to add this action to
2974 CEPH_RADOS_API
void rados_write_op_remove(rados_write_op_t write_op
);
2977 * Truncate an object
2978 * @param write_op operation to add this action to
2979 * @param offset Offset to truncate to
2981 CEPH_RADOS_API
void rados_write_op_truncate(rados_write_op_t write_op
,
2985 * Zero part of an object
2986 * @param write_op operation to add this action to
2987 * @param offset Offset to zero
2988 * @param len length to zero
2990 CEPH_RADOS_API
void rados_write_op_zero(rados_write_op_t write_op
,
2995 * Execute an OSD class method on an object
2996 * See rados_exec() for general description.
2998 * @param write_op operation to add this action to
2999 * @param cls the name of the class
3000 * @param method the name of the method
3001 * @param in_buf where to find input
3002 * @param in_len length of in_buf in bytes
3003 * @param prval where to store the return value from the method
3005 CEPH_RADOS_API
void rados_write_op_exec(rados_write_op_t write_op
,
3013 * Set key/value pairs on an object
3015 * @param write_op operation to add this action to
3016 * @param keys array of null-terminated char arrays representing keys to set
3017 * @param vals array of pointers to values to set
3018 * @param lens array of lengths corresponding to each value
3019 * @param num number of key/value pairs to set
3021 CEPH_RADOS_API
void rados_write_op_omap_set(rados_write_op_t write_op
,
3022 char const* const* keys
,
3023 char const* const* vals
,
3028 * Set key/value pairs on an object
3030 * @param write_op operation to add this action to
3031 * @param keys array of null-terminated char arrays representing keys to set
3032 * @param vals array of pointers to values to set
3033 * @param key_lens array of lengths corresponding to each key
3034 * @param val_lens array of lengths corresponding to each value
3035 * @param num number of key/value pairs to set
3037 CEPH_RADOS_API
void rados_write_op_omap_set2(rados_write_op_t write_op
,
3038 char const* const* keys
,
3039 char const* const* vals
,
3040 const size_t *key_lens
,
3041 const size_t *val_lens
,
3045 * Remove key/value pairs from an object
3047 * @param write_op operation to add this action to
3048 * @param keys array of null-terminated char arrays representing keys to remove
3049 * @param keys_len number of key/value pairs to remove
3051 CEPH_RADOS_API
void rados_write_op_omap_rm_keys(rados_write_op_t write_op
,
3052 char const* const* keys
,
3056 * Remove key/value pairs from an object
3058 * @param write_op operation to add this action to
3059 * @param keys array of char arrays representing keys to remove
3060 * @param key_lens array of size_t values representing length of each key
3061 * @param keys_len number of key/value pairs to remove
3063 CEPH_RADOS_API
void rados_write_op_omap_rm_keys2(rados_write_op_t write_op
,
3064 char const* const* keys
,
3065 const size_t* key_lens
,
3070 * Remove key/value pairs from an object whose keys are in the range
3071 * [key_begin, key_end)
3073 * @param write_op operation to add this action to
3074 * @param key_begin the lower bound of the key range to remove
3075 * @param key_begin_len length of key_begin
3076 * @param key_end the upper bound of the key range to remove
3077 * @param key_end_len length of key_end
3079 CEPH_RADOS_API
void rados_write_op_omap_rm_range2(rados_write_op_t write_op
,
3080 const char *key_begin
,
3081 size_t key_begin_len
,
3082 const char *key_end
,
3083 size_t key_end_len
);
3086 * Remove all key/value pairs from an object
3088 * @param write_op operation to add this action to
3090 CEPH_RADOS_API
void rados_write_op_omap_clear(rados_write_op_t write_op
);
3093 * Set allocation hint for an object
3095 * @param write_op operation to add this action to
3096 * @param expected_object_size expected size of the object, in bytes
3097 * @param expected_write_size expected size of writes to the object, in bytes
3099 CEPH_RADOS_API
void rados_write_op_set_alloc_hint(rados_write_op_t write_op
,
3100 uint64_t expected_object_size
,
3101 uint64_t expected_write_size
);
3104 * Set allocation hint for an object
3106 * @param write_op operation to add this action to
3107 * @param expected_object_size expected size of the object, in bytes
3108 * @param expected_write_size expected size of writes to the object, in bytes
3109 * @param flags hints about future IO patterns
3111 CEPH_RADOS_API
void rados_write_op_set_alloc_hint2(rados_write_op_t write_op
,
3112 uint64_t expected_object_size
,
3113 uint64_t expected_write_size
,
3117 * Perform a write operation synchronously
3118 * @param write_op operation to perform
3119 * @param io the ioctx that the object is in
3120 * @param oid the object id
3121 * @param mtime the time to set the mtime to, NULL for the current time
3122 * @param flags flags to apply to the entire operation (LIBRADOS_OPERATION_*)
3124 CEPH_RADOS_API
int rados_write_op_operate(rados_write_op_t write_op
,
3130 * Perform a write operation synchronously
3131 * @param write_op operation to perform
3132 * @param io the ioctx that the object is in
3133 * @param oid the object id
3134 * @param mtime the time to set the mtime to, NULL for the current time
3135 * @param flags flags to apply to the entire operation (LIBRADOS_OPERATION_*)
3138 CEPH_RADOS_API
int rados_write_op_operate2(rados_write_op_t write_op
,
3141 struct timespec
*mtime
,
3145 * Perform a write operation asynchronously
3146 * @param write_op operation to perform
3147 * @param io the ioctx that the object is in
3148 * @param completion what to do when operation has been attempted
3149 * @param oid the object id
3150 * @param mtime the time to set the mtime to, NULL for the current time
3151 * @param flags flags to apply to the entire operation (LIBRADOS_OPERATION_*)
3153 CEPH_RADOS_API
int rados_aio_write_op_operate(rados_write_op_t write_op
,
3155 rados_completion_t completion
,
3161 * Create a new rados_read_op_t write operation. This will store all
3162 * actions to be performed atomically. You must call
3163 * rados_release_read_op when you are finished with it (after it
3164 * completes, or you decide not to send it in the first place).
3166 * @returns non-NULL on success, NULL on memory allocation error.
3168 CEPH_RADOS_API rados_read_op_t
rados_create_read_op(void);
3171 * Free a rados_read_op_t, must be called when you're done with it.
3172 * @param read_op operation to deallocate, created with rados_create_read_op
3174 CEPH_RADOS_API
void rados_release_read_op(rados_read_op_t read_op
);
3177 * Set flags for the last operation added to this read_op.
3178 * At least one op must have been added to the read_op.
3179 * @param read_op operation to add this action to
3180 * @param flags see librados.h constants beginning with LIBRADOS_OP_FLAG
3182 CEPH_RADOS_API
void rados_read_op_set_flags(rados_read_op_t read_op
, int flags
);
3185 * Ensure that the object exists before reading
3186 * @param read_op operation to add this action to
3188 CEPH_RADOS_API
void rados_read_op_assert_exists(rados_read_op_t read_op
);
3191 * Ensure that the object exists and that its internal version
3192 * number is equal to "ver" before reading. "ver" should be a
3193 * version number previously obtained with rados_get_last_version().
3194 * - If the object's version is greater than the asserted version
3195 * then rados_read_op_operate will return -ERANGE instead of
3197 * - If the object's version is less than the asserted version
3198 * then rados_read_op_operate will return -EOVERFLOW instead
3199 * of executing the op.
3200 * @param read_op operation to add this action to
3201 * @param ver object version number
3203 CEPH_RADOS_API
void rados_read_op_assert_version(rados_read_op_t read_op
, uint64_t ver
);
3206 * Ensure that given object range (extent) satisfies comparison.
3208 * @param read_op operation to add this action to
3209 * @param cmp_buf buffer containing bytes to be compared with object contents
3210 * @param cmp_len length to compare and size of @c cmp_buf in bytes
3211 * @param off object byte offset at which to start the comparison
3212 * @param prval returned result of comparison, 0 on success, negative error code
3213 * on failure, (-MAX_ERRNO - mismatch_off) on mismatch
3215 CEPH_RADOS_API
void rados_read_op_cmpext(rados_read_op_t read_op
,
3216 const char *cmp_buf
,
3222 * Ensure that the an xattr satisfies a comparison
3223 * If the comparison is not satisfied, the return code of the
3224 * operation will be -ECANCELED
3225 * @param read_op operation to add this action to
3226 * @param name name of the xattr to look up
3227 * @param comparison_operator currently undocumented, look for
3228 * LIBRADOS_CMPXATTR_OP_EQ in librados.h
3229 * @param value buffer to compare actual xattr value to
3230 * @param value_len length of buffer to compare actual xattr value to
3232 CEPH_RADOS_API
void rados_read_op_cmpxattr(rados_read_op_t read_op
,
3234 uint8_t comparison_operator
,
3239 * Start iterating over xattrs on an object.
3241 * @param read_op operation to add this action to
3242 * @param iter where to store the iterator
3243 * @param prval where to store the return value of this action
3245 CEPH_RADOS_API
void rados_read_op_getxattrs(rados_read_op_t read_op
,
3246 rados_xattrs_iter_t
*iter
,
3250 * Ensure that the an omap value satisfies a comparison,
3251 * with the supplied value on the right hand side (i.e.
3252 * for OP_LT, the comparison is actual_value < value.
3254 * @param read_op operation to add this action to
3255 * @param key which omap value to compare
3256 * @param comparison_operator one of LIBRADOS_CMPXATTR_OP_EQ,
3257 LIBRADOS_CMPXATTR_OP_LT, or LIBRADOS_CMPXATTR_OP_GT
3258 * @param val value to compare with
3259 * @param val_len length of value in bytes
3260 * @param prval where to store the return value from this action
3262 CEPH_RADOS_API
void rados_read_op_omap_cmp(rados_read_op_t read_op
,
3264 uint8_t comparison_operator
,
3270 * Ensure that the an omap value satisfies a comparison,
3271 * with the supplied value on the right hand side (i.e.
3272 * for OP_LT, the comparison is actual_value < value.
3274 * @param read_op operation to add this action to
3275 * @param key which omap value to compare
3276 * @param comparison_operator one of LIBRADOS_CMPXATTR_OP_EQ,
3277 LIBRADOS_CMPXATTR_OP_LT, or LIBRADOS_CMPXATTR_OP_GT
3278 * @param val value to compare with
3279 * @param key_len length of key in bytes
3280 * @param val_len length of value in bytes
3281 * @param prval where to store the return value from this action
3283 CEPH_RADOS_API
void rados_read_op_omap_cmp2(rados_read_op_t read_op
,
3285 uint8_t comparison_operator
,
3292 * Get object size and mtime
3293 * @param read_op operation to add this action to
3294 * @param psize where to store object size
3295 * @param pmtime where to store modification time
3296 * @param prval where to store the return value of this action
3298 CEPH_RADOS_API
void rados_read_op_stat(rados_read_op_t read_op
,
3304 * Read bytes from offset into buffer.
3306 * prlen will be filled with the number of bytes read if successful.
3307 * A short read can only occur if the read reaches the end of the
3310 * @param read_op operation to add this action to
3311 * @param offset offset to read from
3312 * @param len length of buffer
3313 * @param buffer where to put the data
3314 * @param bytes_read where to store the number of bytes read by this action
3315 * @param prval where to store the return value of this action
3317 CEPH_RADOS_API
void rados_read_op_read(rados_read_op_t read_op
,
3325 * Compute checksum from object data
3327 * @param read_op operation to add this action to
3328 * @param type the checksum algorithm to utilize
3329 * @param init_value the init value for the algorithm
3330 * @param init_value_len the length of the init value
3331 * @param offset the offset to start checksumming in the object
3332 * @param len the number of bytes to checksum
3333 * @param chunk_size optional length-aligned chunk size for checksums
3334 * @param pchecksum where to store the checksum result for this action
3335 * @param checksum_len the number of bytes available for the result
3336 * @param prval where to store the return value for this action
3338 CEPH_RADOS_API
void rados_read_op_checksum(rados_read_op_t read_op
,
3339 rados_checksum_type_t type
,
3340 const char *init_value
,
3341 size_t init_value_len
,
3342 uint64_t offset
, size_t len
,
3343 size_t chunk_size
, char *pchecksum
,
3344 size_t checksum_len
, int *prval
);
3347 * Execute an OSD class method on an object
3348 * See rados_exec() for general description.
3350 * The output buffer is allocated on the heap; the caller is
3351 * expected to release that memory with rados_buffer_free(). The
3352 * buffer and length pointers can all be NULL, in which case they are
3355 * @param read_op operation to add this action to
3356 * @param cls the name of the class
3357 * @param method the name of the method
3358 * @param in_buf where to find input
3359 * @param in_len length of in_buf in bytes
3360 * @param out_buf where to put librados-allocated output buffer
3361 * @param out_len length of out_buf in bytes
3362 * @param prval where to store the return value from the method
3364 CEPH_RADOS_API
void rados_read_op_exec(rados_read_op_t read_op
,
3374 * Execute an OSD class method on an object
3375 * See rados_exec() for general description.
3377 * If the output buffer is too small, prval will
3378 * be set to -ERANGE and used_len will be 0.
3380 * @param read_op operation to add this action to
3381 * @param cls the name of the class
3382 * @param method the name of the method
3383 * @param in_buf where to find input
3384 * @param in_len length of in_buf in bytes
3385 * @param out_buf user-provided buffer to read into
3386 * @param out_len length of out_buf in bytes
3387 * @param used_len where to store the number of bytes read into out_buf
3388 * @param prval where to store the return value from the method
3390 CEPH_RADOS_API
void rados_read_op_exec_user_buf(rados_read_op_t read_op
,
3401 * Start iterating over key/value pairs on an object.
3403 * They will be returned sorted by key.
3405 * @param read_op operation to add this action to
3406 * @param start_after list keys starting after start_after
3407 * @param filter_prefix list only keys beginning with filter_prefix
3408 * @param max_return list no more than max_return key/value pairs
3409 * @param iter where to store the iterator
3410 * @param prval where to store the return value from this action
3412 CEPH_RADOS_API
void rados_read_op_omap_get_vals(rados_read_op_t read_op
,
3413 const char *start_after
,
3414 const char *filter_prefix
,
3415 uint64_t max_return
,
3416 rados_omap_iter_t
*iter
,
3418 __attribute__((deprecated
)); /* use v2 below */
3421 * Start iterating over key/value pairs on an object.
3423 * They will be returned sorted by key.
3425 * @param read_op operation to add this action to
3426 * @param start_after list keys starting after start_after
3427 * @param filter_prefix list only keys beginning with filter_prefix
3428 * @param max_return list no more than max_return key/value pairs
3429 * @param iter where to store the iterator
3430 * @param pmore flag indicating whether there are more keys to fetch
3431 * @param prval where to store the return value from this action
3433 CEPH_RADOS_API
void rados_read_op_omap_get_vals2(rados_read_op_t read_op
,
3434 const char *start_after
,
3435 const char *filter_prefix
,
3436 uint64_t max_return
,
3437 rados_omap_iter_t
*iter
,
3438 unsigned char *pmore
,
3442 * Start iterating over keys on an object.
3444 * They will be returned sorted by key, and the iterator
3445 * will fill in NULL for all values if specified.
3447 * @param read_op operation to add this action to
3448 * @param start_after list keys starting after start_after
3449 * @param max_return list no more than max_return keys
3450 * @param iter where to store the iterator
3451 * @param prval where to store the return value from this action
3453 CEPH_RADOS_API
void rados_read_op_omap_get_keys(rados_read_op_t read_op
,
3454 const char *start_after
,
3455 uint64_t max_return
,
3456 rados_omap_iter_t
*iter
,
3458 __attribute__((deprecated
)); /* use v2 below */
3461 * Start iterating over keys on an object.
3463 * They will be returned sorted by key, and the iterator
3464 * will fill in NULL for all values if specified.
3466 * @param read_op operation to add this action to
3467 * @param start_after list keys starting after start_after
3468 * @param max_return list no more than max_return keys
3469 * @param iter where to store the iterator
3470 * @param pmore flag indicating whether there are more keys to fetch
3471 * @param prval where to store the return value from this action
3473 CEPH_RADOS_API
void rados_read_op_omap_get_keys2(rados_read_op_t read_op
,
3474 const char *start_after
,
3475 uint64_t max_return
,
3476 rados_omap_iter_t
*iter
,
3477 unsigned char *pmore
,
3481 * Start iterating over specific key/value pairs
3483 * They will be returned sorted by key.
3485 * @param read_op operation to add this action to
3486 * @param keys array of pointers to null-terminated keys to get
3487 * @param keys_len the number of strings in keys
3488 * @param iter where to store the iterator
3489 * @param prval where to store the return value from this action
3491 CEPH_RADOS_API
void rados_read_op_omap_get_vals_by_keys(rados_read_op_t read_op
,
3492 char const* const* keys
,
3494 rados_omap_iter_t
*iter
,
3498 * Start iterating over specific key/value pairs
3500 * They will be returned sorted by key.
3502 * @param read_op operation to add this action to
3503 * @param keys array of pointers to keys to get
3504 * @param num_keys the number of strings in keys
3505 * @param key_lens array of size_t's describing each key len (in bytes)
3506 * @param iter where to store the iterator
3507 * @param prval where to store the return value from this action
3509 CEPH_RADOS_API
void rados_read_op_omap_get_vals_by_keys2(rados_read_op_t read_op
,
3510 char const* const* keys
,
3512 const size_t* key_lens
,
3513 rados_omap_iter_t
*iter
,
3517 * Perform a read operation synchronously
3518 * @param read_op operation to perform
3519 * @param io the ioctx that the object is in
3520 * @param oid the object id
3521 * @param flags flags to apply to the entire operation (LIBRADOS_OPERATION_*)
3523 CEPH_RADOS_API
int rados_read_op_operate(rados_read_op_t read_op
,
3529 * Perform a read operation asynchronously
3530 * @param read_op operation to perform
3531 * @param io the ioctx that the object is in
3532 * @param completion what to do when operation has been attempted
3533 * @param oid the object id
3534 * @param flags flags to apply to the entire operation (LIBRADOS_OPERATION_*)
3536 CEPH_RADOS_API
int rados_aio_read_op_operate(rados_read_op_t read_op
,
3538 rados_completion_t completion
,
3542 /** @} Object Operations */
3545 * Take an exclusive lock on an object.
3547 * @param io the context to operate in
3548 * @param oid the name of the object
3549 * @param name the name of the lock
3550 * @param cookie user-defined identifier for this instance of the lock
3551 * @param desc user-defined lock description
3552 * @param duration the duration of the lock. Set to NULL for infinite duration.
3553 * @param flags lock flags
3554 * @returns 0 on success, negative error code on failure
3555 * @returns -EBUSY if the lock is already held by another (client, cookie) pair
3556 * @returns -EEXIST if the lock is already held by the same (client, cookie) pair
3558 CEPH_RADOS_API
int rados_lock_exclusive(rados_ioctx_t io
, const char * oid
,
3559 const char * name
, const char * cookie
,
3561 struct timeval
* duration
,
3565 * Take a shared lock on an object.
3567 * @param io the context to operate in
3568 * @param o the name of the object
3569 * @param name the name of the lock
3570 * @param cookie user-defined identifier for this instance of the lock
3571 * @param tag The tag of the lock
3572 * @param desc user-defined lock description
3573 * @param duration the duration of the lock. Set to NULL for infinite duration.
3574 * @param flags lock flags
3575 * @returns 0 on success, negative error code on failure
3576 * @returns -EBUSY if the lock is already held by another (client, cookie) pair
3577 * @returns -EEXIST if the lock is already held by the same (client, cookie) pair
3579 CEPH_RADOS_API
int rados_lock_shared(rados_ioctx_t io
, const char * o
,
3580 const char * name
, const char * cookie
,
3581 const char * tag
, const char * desc
,
3582 struct timeval
* duration
, uint8_t flags
);
3585 * Release a shared or exclusive lock on an object.
3587 * @param io the context to operate in
3588 * @param o the name of the object
3589 * @param name the name of the lock
3590 * @param cookie user-defined identifier for the instance of the lock
3591 * @returns 0 on success, negative error code on failure
3592 * @returns -ENOENT if the lock is not held by the specified (client, cookie) pair
3594 CEPH_RADOS_API
int rados_unlock(rados_ioctx_t io
, const char *o
,
3595 const char *name
, const char *cookie
);
3598 * Asynchronous release a shared or exclusive lock on an object.
3600 * @param io the context to operate in
3601 * @param o the name of the object
3602 * @param name the name of the lock
3603 * @param cookie user-defined identifier for the instance of the lock
3604 * @param completion what to do when operation has been attempted
3605 * @returns 0 on success, negative error code on failure
3607 CEPH_RADOS_API
int rados_aio_unlock(rados_ioctx_t io
, const char *o
,
3608 const char *name
, const char *cookie
,
3609 rados_completion_t completion
);
3612 * List clients that have locked the named object lock and information about
3615 * The number of bytes required in each buffer is put in the
3616 * corresponding size out parameter. If any of the provided buffers
3617 * are too short, -ERANGE is returned after these sizes are filled in.
3619 * @param io the context to operate in
3620 * @param o the name of the object
3621 * @param name the name of the lock
3622 * @param exclusive where to store whether the lock is exclusive (1) or shared (0)
3623 * @param tag where to store the tag associated with the object lock
3624 * @param tag_len number of bytes in tag buffer
3625 * @param clients buffer in which locker clients are stored, separated by '\0'
3626 * @param clients_len number of bytes in the clients buffer
3627 * @param cookies buffer in which locker cookies are stored, separated by '\0'
3628 * @param cookies_len number of bytes in the cookies buffer
3629 * @param addrs buffer in which locker addresses are stored, separated by '\0'
3630 * @param addrs_len number of bytes in the clients buffer
3631 * @returns number of lockers on success, negative error code on failure
3632 * @returns -ERANGE if any of the buffers are too short
3634 CEPH_RADOS_API ssize_t
rados_list_lockers(rados_ioctx_t io
, const char *o
,
3635 const char *name
, int *exclusive
,
3636 char *tag
, size_t *tag_len
,
3637 char *clients
, size_t *clients_len
,
3638 char *cookies
, size_t *cookies_len
,
3639 char *addrs
, size_t *addrs_len
);
3642 * Releases a shared or exclusive lock on an object, which was taken by the
3645 * @param io the context to operate in
3646 * @param o the name of the object
3647 * @param name the name of the lock
3648 * @param client the client currently holding the lock
3649 * @param cookie user-defined identifier for the instance of the lock
3650 * @returns 0 on success, negative error code on failure
3651 * @returns -ENOENT if the lock is not held by the specified (client, cookie) pair
3652 * @returns -EINVAL if the client cannot be parsed
3654 CEPH_RADOS_API
int rados_break_lock(rados_ioctx_t io
, const char *o
,
3655 const char *name
, const char *client
,
3656 const char *cookie
);
3659 * Blacklists the specified client from the OSDs
3661 * @param cluster cluster handle
3662 * @param client_address client address
3663 * @param expire_seconds number of seconds to blacklist (0 for default)
3664 * @returns 0 on success, negative error code on failure
3666 CEPH_RADOS_API
int rados_blacklist_add(rados_t cluster
,
3667 char *client_address
,
3668 uint32_t expire_seconds
);
3671 * Gets addresses of the RADOS session, suitable for blacklisting.
3673 * @param cluster cluster handle
3674 * @param addrs the output string.
3675 * @returns 0 on success, negative error code on failure
3677 CEPH_RADOS_API
int rados_getaddrs(rados_t cluster
, char** addrs
);
3679 CEPH_RADOS_API
void rados_set_osdmap_full_try(rados_ioctx_t io
)
3680 __attribute__((deprecated
));
3682 CEPH_RADOS_API
void rados_unset_osdmap_full_try(rados_ioctx_t io
)
3683 __attribute__((deprecated
));
3685 CEPH_RADOS_API
void rados_set_pool_full_try(rados_ioctx_t io
);
3687 CEPH_RADOS_API
void rados_unset_pool_full_try(rados_ioctx_t io
);
3690 * Enable an application on a pool
3692 * @param io pool ioctx
3693 * @param app_name application name
3694 * @param force 0 if only single application per pool
3695 * @returns 0 on success, negative error code on failure
3697 CEPH_RADOS_API
int rados_application_enable(rados_ioctx_t io
,
3698 const char *app_name
, int force
);
3701 * List all enabled applications
3703 * If the provided buffer is too short, the required length is filled in and
3704 * -ERANGE is returned. Otherwise, the buffers are filled with the application
3705 * names, with a '\0' after each.
3707 * @param io pool ioctx
3708 * @param values buffer in which to store application names
3709 * @param values_len number of bytes in values buffer
3710 * @returns 0 on success, negative error code on failure
3711 * @returns -ERANGE if either buffer is too short
3713 CEPH_RADOS_API
int rados_application_list(rados_ioctx_t io
, char *values
,
3714 size_t *values_len
);
3717 * Get application metadata value from pool
3719 * @param io pool ioctx
3720 * @param app_name application name
3721 * @param key metadata key
3722 * @param value result buffer
3723 * @param value_len maximum len of value
3724 * @returns 0 on success, negative error code on failure
3726 CEPH_RADOS_API
int rados_application_metadata_get(rados_ioctx_t io
,
3727 const char *app_name
,
3728 const char *key
, char *value
,
3732 * Set application metadata on a pool
3734 * @param io pool ioctx
3735 * @param app_name application name
3736 * @param key metadata key
3737 * @param value metadata key
3738 * @returns 0 on success, negative error code on failure
3740 CEPH_RADOS_API
int rados_application_metadata_set(rados_ioctx_t io
,
3741 const char *app_name
,
3746 * Remove application metadata from a pool
3748 * @param io pool ioctx
3749 * @param app_name application name
3750 * @param key metadata key
3751 * @returns 0 on success, negative error code on failure
3753 CEPH_RADOS_API
int rados_application_metadata_remove(rados_ioctx_t io
,
3754 const char *app_name
,
3758 * List all metadata key/value pairs associated with an application.
3760 * This iterates over all metadata, key_len and val_len are filled in
3761 * with the number of bytes put into the keys and values buffers.
3763 * If the provided buffers are too short, the required lengths are filled
3764 * in and -ERANGE is returned. Otherwise, the buffers are filled with
3765 * the keys and values of the metadata, with a '\0' after each.
3767 * @param io pool ioctx
3768 * @param app_name application name
3769 * @param keys buffer in which to store key names
3770 * @param key_len number of bytes in keys buffer
3771 * @param values buffer in which to store values
3772 * @param vals_len number of bytes in values buffer
3773 * @returns 0 on success, negative error code on failure
3774 * @returns -ERANGE if either buffer is too short
3776 CEPH_RADOS_API
int rados_application_metadata_list(rados_ioctx_t io
,
3777 const char *app_name
,
3778 char *keys
, size_t *key_len
,
3783 * @name Mon/OSD/PG Commands
3785 * These interfaces send commands relating to the monitor, OSD, or PGs.
3791 * Send monitor command.
3793 * @note Takes command string in carefully-formatted JSON; must match
3794 * defined commands, types, etc.
3796 * The result buffers are allocated on the heap; the caller is
3797 * expected to release that memory with rados_buffer_free(). The
3798 * buffer and length pointers can all be NULL, in which case they are
3801 * @param cluster cluster handle
3802 * @param cmd an array of char *'s representing the command
3803 * @param cmdlen count of valid entries in cmd
3804 * @param inbuf any bulk input data (crush map, etc.)
3805 * @param inbuflen input buffer length
3806 * @param outbuf double pointer to output buffer
3807 * @param outbuflen pointer to output buffer length
3808 * @param outs double pointer to status string
3809 * @param outslen pointer to status string length
3810 * @returns 0 on success, negative error code on failure
3812 CEPH_RADOS_API
int rados_mon_command(rados_t cluster
, const char **cmd
,
3813 size_t cmdlen
, const char *inbuf
,
3814 size_t inbuflen
, char **outbuf
,
3815 size_t *outbuflen
, char **outs
,
3819 * Send ceph-mgr command.
3821 * @note Takes command string in carefully-formatted JSON; must match
3822 * defined commands, types, etc.
3824 * The result buffers are allocated on the heap; the caller is
3825 * expected to release that memory with rados_buffer_free(). The
3826 * buffer and length pointers can all be NULL, in which case they are
3829 * @param cluster cluster handle
3830 * @param cmd an array of char *'s representing the command
3831 * @param cmdlen count of valid entries in cmd
3832 * @param inbuf any bulk input data (crush map, etc.)
3833 * @param inbuflen input buffer length
3834 * @param outbuf double pointer to output buffer
3835 * @param outbuflen pointer to output buffer length
3836 * @param outs double pointer to status string
3837 * @param outslen pointer to status string length
3838 * @returns 0 on success, negative error code on failure
3840 CEPH_RADOS_API
int rados_mgr_command(rados_t cluster
, const char **cmd
,
3841 size_t cmdlen
, const char *inbuf
,
3842 size_t inbuflen
, char **outbuf
,
3843 size_t *outbuflen
, char **outs
,
3847 * Send ceph-mgr tell command.
3849 * @note Takes command string in carefully-formatted JSON; must match
3850 * defined commands, types, etc.
3852 * The result buffers are allocated on the heap; the caller is
3853 * expected to release that memory with rados_buffer_free(). The
3854 * buffer and length pointers can all be NULL, in which case they are
3857 * @param cluster cluster handle
3858 * @param name mgr name to target
3859 * @param cmd an array of char *'s representing the command
3860 * @param cmdlen count of valid entries in cmd
3861 * @param inbuf any bulk input data (crush map, etc.)
3862 * @param inbuflen input buffer length
3863 * @param outbuf double pointer to output buffer
3864 * @param outbuflen pointer to output buffer length
3865 * @param outs double pointer to status string
3866 * @param outslen pointer to status string length
3867 * @returns 0 on success, negative error code on failure
3869 CEPH_RADOS_API
int rados_mgr_command_target(
3873 size_t cmdlen
, const char *inbuf
,
3874 size_t inbuflen
, char **outbuf
,
3875 size_t *outbuflen
, char **outs
,
3879 * Send monitor command to a specific monitor.
3881 * @note Takes command string in carefully-formatted JSON; must match
3882 * defined commands, types, etc.
3884 * The result buffers are allocated on the heap; the caller is
3885 * expected to release that memory with rados_buffer_free(). The
3886 * buffer and length pointers can all be NULL, in which case they are
3889 * @param cluster cluster handle
3890 * @param name target monitor's name
3891 * @param cmd an array of char *'s representing the command
3892 * @param cmdlen count of valid entries in cmd
3893 * @param inbuf any bulk input data (crush map, etc.)
3894 * @param inbuflen input buffer length
3895 * @param outbuf double pointer to output buffer
3896 * @param outbuflen pointer to output buffer length
3897 * @param outs double pointer to status string
3898 * @param outslen pointer to status string length
3899 * @returns 0 on success, negative error code on failure
3901 CEPH_RADOS_API
int rados_mon_command_target(rados_t cluster
, const char *name
,
3902 const char **cmd
, size_t cmdlen
,
3903 const char *inbuf
, size_t inbuflen
,
3904 char **outbuf
, size_t *outbuflen
,
3905 char **outs
, size_t *outslen
);
3908 * free a rados-allocated buffer
3910 * Release memory allocated by librados calls like rados_mon_command().
3912 * @param buf buffer pointer
3914 CEPH_RADOS_API
void rados_buffer_free(char *buf
);
3916 CEPH_RADOS_API
int rados_osd_command(rados_t cluster
, int osdid
,
3917 const char **cmd
, size_t cmdlen
,
3918 const char *inbuf
, size_t inbuflen
,
3919 char **outbuf
, size_t *outbuflen
,
3920 char **outs
, size_t *outslen
);
3922 CEPH_RADOS_API
int rados_pg_command(rados_t cluster
, const char *pgstr
,
3923 const char **cmd
, size_t cmdlen
,
3924 const char *inbuf
, size_t inbuflen
,
3925 char **outbuf
, size_t *outbuflen
,
3926 char **outs
, size_t *outslen
);
3928 CEPH_RADOS_API
int rados_mgr_command(rados_t cluster
,
3929 const char **cmd
, size_t cmdlen
,
3930 const char *inbuf
, size_t inbuflen
,
3931 char **outbuf
, size_t *outbuflen
,
3932 char **outs
, size_t *outslen
);
3935 * This is not a doxygen comment leadin, because doxygen breaks on
3936 * a typedef with function params and returns, and I can't figure out
3939 * Monitor cluster log
3941 * Monitor events logged to the cluster log. The callback get each
3942 * log entry both as a single formatted line and with each field in a
3945 * Calling with a cb argument of NULL will deregister any previously
3946 * registered callback.
3948 * @param cluster cluster handle
3949 * @param level minimum log level (debug, info, warn|warning, err|error)
3950 * @param cb callback to run for each log message. It MUST NOT block
3951 * nor call back into librados.
3952 * @param arg void argument to pass to cb
3954 * @returns 0 on success, negative code on error
3956 typedef void (*rados_log_callback_t
)(void *arg
,
3959 uint64_t sec
, uint64_t nsec
,
3960 uint64_t seq
, const char *level
,
3964 * This is not a doxygen comment leadin, because doxygen breaks on
3965 * a typedef with function params and returns, and I can't figure out
3968 * Monitor cluster log
3970 * Monitor events logged to the cluster log. The callback get each
3971 * log entry both as a single formatted line and with each field in a
3974 * Calling with a cb argument of NULL will deregister any previously
3975 * registered callback.
3977 * @param cluster cluster handle
3978 * @param level minimum log level (debug, info, warn|warning, err|error)
3979 * @param cb callback to run for each log message. It MUST NOT block
3980 * nor call back into librados.
3981 * @param arg void argument to pass to cb
3983 * @returns 0 on success, negative code on error
3985 typedef void (*rados_log_callback2_t
)(void *arg
,
3987 const char *channel
,
3990 uint64_t sec
, uint64_t nsec
,
3991 uint64_t seq
, const char *level
,
3994 CEPH_RADOS_API
int rados_monitor_log(rados_t cluster
, const char *level
,
3995 rados_log_callback_t cb
, void *arg
);
3996 CEPH_RADOS_API
int rados_monitor_log2(rados_t cluster
, const char *level
,
3997 rados_log_callback2_t cb
, void *arg
);
4001 * register daemon instance for a service
4003 * Register us as a daemon providing a particular service. We identify
4004 * the service (e.g., 'rgw') and our instance name (e.g., 'rgw.$hostname').
4005 * The metadata is a map of keys and values with arbitrary static metdata
4006 * for this instance. The encoding is a series of NULL-terminated strings,
4007 * alternating key names and values, terminating with an empty key name.
4008 * For example, "foo\0bar\0this\0that\0\0" is the dict {foo=bar,this=that}.
4010 * For the lifetime of the librados instance, regular beacons will be sent
4011 * to the cluster to maintain our registration in the service map.
4013 * @param cluster handle
4014 * @param service service name
4015 * @param daemon daemon instance name
4016 * @param metadata_dict static daemon metadata dict
4018 CEPH_RADOS_API
int rados_service_register(
4020 const char *service
,
4022 const char *metadata_dict
);
4025 * update daemon status
4027 * Update our mutable status information in the service map.
4029 * The status dict is encoded the same way the daemon metadata is encoded
4030 * for rados_service_register. For example, "foo\0bar\0this\0that\0\0" is
4031 * {foo=bar,this=that}.
4033 * @param cluster rados cluster handle
4034 * @param status_dict status dict
4036 CEPH_RADOS_API
int rados_service_update_status(
4038 const char *status_dict
);
4040 /** @} Mon/OSD/PG commands */
4043 * These methods are no longer supported and return -ENOTSUP where possible.
4045 CEPH_RADOS_API
int rados_objects_list_open(
4047 rados_list_ctx_t
*ctx
) __attribute__((deprecated
));
4048 CEPH_RADOS_API
uint32_t rados_objects_list_get_pg_hash_position(
4049 rados_list_ctx_t ctx
) __attribute__((deprecated
));
4050 CEPH_RADOS_API
uint32_t rados_objects_list_seek(
4051 rados_list_ctx_t ctx
,
4052 uint32_t pos
) __attribute__((deprecated
));
4053 CEPH_RADOS_API
int rados_objects_list_next(
4054 rados_list_ctx_t ctx
,
4056 const char **key
) __attribute__((deprecated
));
4057 CEPH_RADOS_API
void rados_objects_list_close(
4058 rados_list_ctx_t ctx
) __attribute__((deprecated
));