1 // -*- mode:C++; tab-width:8; c-basic-offset:2; indent-tabs-mode:t -*-
2 // vim: ts=8 sw=2 smarttab
4 * Ceph - scalable distributed file system
6 * Copyright (C) 2004-2012 Sage Weil <sage@newdream.net>
8 * This is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Lesser General Public
10 * License version 2.1, as published by the Free Software
11 * Foundation. See file COPYING.
15 #ifndef CEPH_LIBRADOS_H
16 #define CEPH_LIBRADOS_H
22 #include <netinet/in.h>
23 #if defined(__linux__)
24 #include <linux/types.h>
25 #elif defined(__FreeBSD__)
26 #include <sys/types.h>
30 #include "rados_types.h"
34 #ifndef CEPH_OSD_TMAP_SET
35 /* These are also defined in rados.h and objclass.h. Keep them in sync! */
36 #define CEPH_OSD_TMAP_HDR 'h'
37 #define CEPH_OSD_TMAP_SET 's'
38 #define CEPH_OSD_TMAP_CREATE 'c'
39 #define CEPH_OSD_TMAP_RM 'r'
42 #define LIBRADOS_VER_MAJOR 3
43 #define LIBRADOS_VER_MINOR 0
44 #define LIBRADOS_VER_EXTRA 0
46 #define LIBRADOS_VERSION(maj, min, extra) ((maj << 16) + (min << 8) + extra)
48 #define LIBRADOS_VERSION_CODE LIBRADOS_VERSION(LIBRADOS_VER_MAJOR, LIBRADOS_VER_MINOR, LIBRADOS_VER_EXTRA)
50 #define LIBRADOS_SUPPORTS_WATCH 1
51 #define LIBRADOS_SUPPORTS_SERVICES 1
52 #define LIBRADOS_SUPPORTS_APP_METADATA 1
55 * They are also defined in cls_lock_types.h. Keep them in sync!
57 #define LIBRADOS_LOCK_FLAG_RENEW 0x1
60 * Constants for rados_write_op_create().
62 #define LIBRADOS_CREATE_EXCLUSIVE 1
63 #define LIBRADOS_CREATE_IDEMPOTENT 0
66 * Flags that can be set on a per-op basis via
67 * rados_read_op_set_flags() and rados_write_op_set_flags().
70 // fail a create operation if the object already exists
71 LIBRADOS_OP_FLAG_EXCL
= 0x1,
72 // allow the transaction to succeed even if the flagged op fails
73 LIBRADOS_OP_FLAG_FAILOK
= 0x2,
74 // indicate read/write op random
75 LIBRADOS_OP_FLAG_FADVISE_RANDOM
= 0x4,
76 // indicate read/write op sequential
77 LIBRADOS_OP_FLAG_FADVISE_SEQUENTIAL
= 0x8,
78 // indicate read/write data will be accessed in the near future (by someone)
79 LIBRADOS_OP_FLAG_FADVISE_WILLNEED
= 0x10,
80 // indicate read/write data will not accessed in the near future (by anyone)
81 LIBRADOS_OP_FLAG_FADVISE_DONTNEED
= 0x20,
82 // indicate read/write data will not accessed again (by *this* client)
83 LIBRADOS_OP_FLAG_FADVISE_NOCACHE
= 0x40,
84 // optionally support FUA (force unit access) on write requests
85 LIBRADOS_OP_FLAG_FADVISE_FUA
= 0x80,
88 #define CEPH_RADOS_API
91 * @name xattr comparison operations
92 * Operators for comparing xattrs on objects, and aborting the
93 * rados_read_op or rados_write_op transaction if the comparison
99 LIBRADOS_CMPXATTR_OP_EQ
= 1,
100 LIBRADOS_CMPXATTR_OP_NE
= 2,
101 LIBRADOS_CMPXATTR_OP_GT
= 3,
102 LIBRADOS_CMPXATTR_OP_GTE
= 4,
103 LIBRADOS_CMPXATTR_OP_LT
= 5,
104 LIBRADOS_CMPXATTR_OP_LTE
= 6
109 * @name Operation Flags
110 * Flags for rados_read_op_operate(), rados_write_op_operate(),
111 * rados_aio_read_op_operate(), and rados_aio_write_op_operate().
112 * See librados.hpp for details.
116 LIBRADOS_OPERATION_NOFLAG
= 0,
117 LIBRADOS_OPERATION_BALANCE_READS
= 1,
118 LIBRADOS_OPERATION_LOCALIZE_READS
= 2,
119 LIBRADOS_OPERATION_ORDER_READS_WRITES
= 4,
120 LIBRADOS_OPERATION_IGNORE_CACHE
= 8,
121 LIBRADOS_OPERATION_SKIPRWLOCKS
= 16,
122 LIBRADOS_OPERATION_IGNORE_OVERLAY
= 32,
123 /* send requests to cluster despite the cluster or pool being marked
124 full; ops will either succeed (e.g., delete) or return EDQUOT or
126 LIBRADOS_OPERATION_FULL_TRY
= 64,
128 * Mainly for delete op
130 LIBRADOS_OPERATION_FULL_FORCE
= 128,
131 LIBRADOS_OPERATION_IGNORE_REDIRECT
= 256,
132 LIBRADOS_OPERATION_ORDERSNAP
= 512,
137 * @name Alloc hint flags
138 * Flags for rados_write_op_alloc_hint2() and rados_set_alloc_hint2()
139 * indicating future IO patterns.
143 LIBRADOS_ALLOC_HINT_FLAG_SEQUENTIAL_WRITE
= 1,
144 LIBRADOS_ALLOC_HINT_FLAG_RANDOM_WRITE
= 2,
145 LIBRADOS_ALLOC_HINT_FLAG_SEQUENTIAL_READ
= 4,
146 LIBRADOS_ALLOC_HINT_FLAG_RANDOM_READ
= 8,
147 LIBRADOS_ALLOC_HINT_FLAG_APPEND_ONLY
= 16,
148 LIBRADOS_ALLOC_HINT_FLAG_IMMUTABLE
= 32,
149 LIBRADOS_ALLOC_HINT_FLAG_SHORTLIVED
= 64,
150 LIBRADOS_ALLOC_HINT_FLAG_LONGLIVED
= 128,
151 LIBRADOS_ALLOC_HINT_FLAG_COMPRESSIBLE
= 256,
152 LIBRADOS_ALLOC_HINT_FLAG_INCOMPRESSIBLE
= 512,
157 LIBRADOS_CHECKSUM_TYPE_XXHASH32
= 0,
158 LIBRADOS_CHECKSUM_TYPE_XXHASH64
= 1,
159 LIBRADOS_CHECKSUM_TYPE_CRC32C
= 2
160 } rados_checksum_type_t
;
165 #define LIBRADOS_SNAP_HEAD ((uint64_t)(-2))
166 #define LIBRADOS_SNAP_DIR ((uint64_t)(-1))
171 * A handle for interacting with a RADOS cluster. It encapsulates all
172 * RADOS client configuration, including username, key for
173 * authentication, logging, and debugging. Talking different clusters
174 * -- or to the same cluster with different users -- requires
175 * different cluster handles.
177 #ifndef VOIDPTR_RADOS_T
178 #define VOIDPTR_RADOS_T
179 typedef void *rados_t
;
180 #endif //VOIDPTR_RADOS_T
183 * @typedef rados_config_t
185 * A handle for the ceph configuration context for the rados_t cluster
186 * instance. This can be used to share configuration context/state
187 * (e.g., logging configuration) between librados instance.
189 * @warning The config context does not have independent reference
190 * counting. As such, a rados_config_t handle retrieved from a given
191 * rados_t is only valid as long as that rados_t.
193 typedef void *rados_config_t
;
196 * @typedef rados_ioctx_t
198 * An io context encapsulates a few settings for all I/O operations
200 * - pool - set when the io context is created (see rados_ioctx_create())
201 * - snapshot context for writes (see
202 * rados_ioctx_selfmanaged_snap_set_write_ctx())
203 * - snapshot id to read from (see rados_ioctx_snap_set_read())
204 * - object locator for all single-object operations (see
205 * rados_ioctx_locator_set_key())
206 * - namespace for all single-object operations (see
207 * rados_ioctx_set_namespace()). Set to LIBRADOS_ALL_NSPACES
208 * before rados_nobjects_list_open() will list all objects in all
211 * @warning Changing any of these settings is not thread-safe -
212 * librados users must synchronize any of these changes on their own,
213 * or use separate io contexts for each thread
215 typedef void *rados_ioctx_t
;
218 * @typedef rados_list_ctx_t
220 * An iterator for listing the objects in a pool.
221 * Used with rados_nobjects_list_open(),
222 * rados_nobjects_list_next(), and
223 * rados_nobjects_list_close().
225 typedef void *rados_list_ctx_t
;
228 * @typedef rados_object_list_cursor
230 * The cursor used with rados_enumerate_objects
231 * and accompanying methods.
233 typedef void * rados_object_list_cursor
;
236 * @struct rados_object_list_item
238 * The item populated by rados_object_list in
241 typedef struct rados_object_list_item
{
245 /// name of the object
248 size_t nspace_length
;
249 /// the object namespace
252 size_t locator_length
;
255 } rados_object_list_item
;
258 * @typedef rados_snap_t
259 * The id of a snapshot.
261 typedef uint64_t rados_snap_t
;
264 * @typedef rados_xattrs_iter_t
265 * An iterator for listing extended attrbutes on an object.
266 * Used with rados_getxattrs(), rados_getxattrs_next(), and
267 * rados_getxattrs_end().
269 typedef void *rados_xattrs_iter_t
;
272 * @typedef rados_omap_iter_t
273 * An iterator for listing omap key/value pairs on an object.
274 * Used with rados_read_op_omap_get_keys(), rados_read_op_omap_get_vals(),
275 * rados_read_op_omap_get_vals_by_keys(), rados_omap_get_next(), and
276 * rados_omap_get_end().
278 typedef void *rados_omap_iter_t
;
281 * @struct rados_pool_stat_t
282 * Usage information for a pool.
284 struct rados_pool_stat_t
{
285 /// space used in bytes
289 /// number of objects in the pool
290 uint64_t num_objects
;
291 /// number of clones of objects
292 uint64_t num_object_clones
;
293 /// num_objects * num_replicas
294 uint64_t num_object_copies
;
295 /// number of objects missing on primary
296 uint64_t num_objects_missing_on_primary
;
297 /// number of objects found on no OSDs
298 uint64_t num_objects_unfound
;
299 /// number of objects replicated fewer times than they should be
300 /// (but found on at least one OSD)
301 uint64_t num_objects_degraded
;
302 /// number of objects read
304 /// objects read in KB
306 /// number of objects written
308 /// objects written in KB
310 /// bytes originally provided by user
311 uint64_t num_user_bytes
;
312 /// bytes passed compression
313 uint64_t compressed_bytes_orig
;
314 /// bytes resulted after compression
315 uint64_t compressed_bytes
;
316 /// bytes allocated at storage
317 uint64_t compressed_bytes_alloc
;
321 * @struct rados_cluster_stat_t
322 * Cluster-wide usage information
324 struct rados_cluster_stat_t
{
325 /// total device size
329 /// total available/free
331 /// number of objects
332 uint64_t num_objects
;
336 * @typedef rados_write_op_t
338 * An object write operation stores a number of operations which can be
339 * executed atomically. For usage, see:
340 * - Creation and deletion: rados_create_write_op() rados_release_write_op()
341 * - Extended attribute manipulation: rados_write_op_cmpxattr()
342 * rados_write_op_cmpxattr(), rados_write_op_setxattr(),
343 * rados_write_op_rmxattr()
344 * - Object map key/value pairs: rados_write_op_omap_set(),
345 * rados_write_op_omap_rm_keys(), rados_write_op_omap_clear(),
346 * rados_write_op_omap_cmp()
347 * - Object properties: rados_write_op_assert_exists(),
348 * rados_write_op_assert_version()
349 * - Creating objects: rados_write_op_create()
350 * - IO on objects: rados_write_op_append(), rados_write_op_write(), rados_write_op_zero
351 * rados_write_op_write_full(), rados_write_op_writesame(), rados_write_op_remove,
352 * rados_write_op_truncate(), rados_write_op_zero(), rados_write_op_cmpext()
353 * - Hints: rados_write_op_set_alloc_hint()
354 * - Performing the operation: rados_write_op_operate(), rados_aio_write_op_operate()
356 typedef void *rados_write_op_t
;
359 * @typedef rados_read_op_t
361 * An object read operation stores a number of operations which can be
362 * executed atomically. For usage, see:
363 * - Creation and deletion: rados_create_read_op() rados_release_read_op()
364 * - Extended attribute manipulation: rados_read_op_cmpxattr(),
365 * rados_read_op_getxattr(), rados_read_op_getxattrs()
366 * - Object map key/value pairs: rados_read_op_omap_get_vals(),
367 * rados_read_op_omap_get_keys(), rados_read_op_omap_get_vals_by_keys(),
368 * rados_read_op_omap_cmp()
369 * - Object properties: rados_read_op_stat(), rados_read_op_assert_exists(),
370 * rados_read_op_assert_version()
371 * - IO on objects: rados_read_op_read(), rados_read_op_checksum(),
372 * rados_read_op_cmpext()
373 * - Custom operations: rados_read_op_exec(), rados_read_op_exec_user_buf()
374 * - Request properties: rados_read_op_set_flags()
375 * - Performing the operation: rados_read_op_operate(),
376 * rados_aio_read_op_operate()
378 typedef void *rados_read_op_t
;
381 * @typedef rados_completion_t
382 * Represents the state of an asynchronous operation - it contains the
383 * return value once the operation completes, and can be used to block
384 * until the operation is complete or safe.
386 typedef void *rados_completion_t
;
389 * @struct blkin_trace_info
390 * blkin trace information for Zipkin tracing
392 struct blkin_trace_info
;
395 * Get the version of librados.
397 * The version number is major.minor.extra. Note that this is
398 * unrelated to the Ceph version number.
400 * TODO: define version semantics, i.e.:
401 * - incrementing major is for backwards-incompatible changes
402 * - incrementing minor is for backwards-compatible changes
403 * - incrementing extra is for bug fixes
405 * @param major where to store the major version number
406 * @param minor where to store the minor version number
407 * @param extra where to store the extra version number
409 CEPH_RADOS_API
void rados_version(int *major
, int *minor
, int *extra
);
412 * @name Setup and Teardown
413 * These are the first and last functions to that should be called
414 * when using librados.
420 * Create a handle for communicating with a RADOS cluster.
422 * Ceph environment variables are read when this is called, so if
423 * $CEPH_ARGS specifies everything you need to connect, no further
424 * configuration is necessary.
426 * @param cluster where to store the handle
427 * @param id the user to connect as (i.e. admin, not client.admin)
428 * @returns 0 on success, negative error code on failure
430 CEPH_RADOS_API
int rados_create(rados_t
*cluster
, const char * const id
);
433 * Extended version of rados_create.
435 * Like rados_create, but
436 * 1) don't assume 'client\.'+id; allow full specification of name
437 * 2) allow specification of cluster name
438 * 3) flags for future expansion
440 CEPH_RADOS_API
int rados_create2(rados_t
*pcluster
,
441 const char *const clustername
,
442 const char * const name
, uint64_t flags
);
445 * Initialize a cluster handle from an existing configuration.
447 * Share configuration state with another rados_t instance.
449 * @param cluster where to store the handle
450 * @param cct the existing configuration to use
451 * @returns 0 on success, negative error code on failure
453 CEPH_RADOS_API
int rados_create_with_context(rados_t
*cluster
,
457 * Ping the monitor with ID mon_id, storing the resulting reply in
458 * buf (if specified) with a maximum size of len.
460 * The result buffer is allocated on the heap; the caller is
461 * expected to release that memory with rados_buffer_free(). The
462 * buffer and length pointers can be NULL, in which case they are
465 * @param cluster cluster handle
466 * @param[in] mon_id ID of the monitor to ping
467 * @param[out] outstr double pointer with the resulting reply
468 * @param[out] outstrlen pointer with the size of the reply in outstr
470 CEPH_RADOS_API
int rados_ping_monitor(rados_t cluster
, const char *mon_id
,
471 char **outstr
, size_t *outstrlen
);
474 * Connect to the cluster.
476 * @note BUG: Before calling this, calling a function that communicates with the
477 * cluster will crash.
479 * @pre The cluster handle is configured with at least a monitor
480 * address. If cephx is enabled, a client name and secret must also be
483 * @post If this succeeds, any function in librados may be used
485 * @param cluster The cluster to connect to.
486 * @returns 0 on success, negative error code on failure
488 CEPH_RADOS_API
int rados_connect(rados_t cluster
);
491 * Disconnects from the cluster.
493 * For clean up, this is only necessary after rados_connect() has
496 * @warning This does not guarantee any asynchronous writes have
497 * completed. To do that, you must call rados_aio_flush() on all open
500 * @warning We implicitly call rados_watch_flush() on shutdown. If
501 * there are watches being used, this should be done explicitly before
502 * destroying the relevant IoCtx. We do it here as a safety measure.
504 * @post the cluster handle cannot be used again
506 * @param cluster the cluster to shutdown
508 CEPH_RADOS_API
void rados_shutdown(rados_t cluster
);
513 * @name Configuration
514 * These functions read and update Ceph configuration for a cluster
515 * handle. Any configuration changes must be done before connecting to
518 * Options that librados users might want to set include:
521 * - key, keyfile, or keyring when using cephx
522 * - log_file, log_to_stderr, err_to_stderr, and log_to_syslog
523 * - debug_rados, debug_objecter, debug_monc, debug_auth, or debug_ms
525 * See docs.ceph.com for information about available configuration options`
531 * Configure the cluster handle using a Ceph config file
533 * If path is NULL, the default locations are searched, and the first
534 * found is used. The locations are:
535 * - $CEPH_CONF (environment variable)
536 * - /etc/ceph/ceph.conf
538 * - ceph.conf (in the current working directory)
540 * @pre rados_connect() has not been called on the cluster handle
542 * @param cluster cluster handle to configure
543 * @param path path to a Ceph configuration file
544 * @returns 0 on success, negative error code on failure
546 CEPH_RADOS_API
int rados_conf_read_file(rados_t cluster
, const char *path
);
549 * Configure the cluster handle with command line arguments
551 * argv can contain any common Ceph command line option, including any
552 * configuration parameter prefixed by '--' and replacing spaces with
553 * dashes or underscores. For example, the following options are equivalent:
554 * - --mon-host 10.0.0.1:6789
555 * - --mon_host 10.0.0.1:6789
558 * @pre rados_connect() has not been called on the cluster handle
560 * @param cluster cluster handle to configure
561 * @param argc number of arguments in argv
562 * @param argv arguments to parse
563 * @returns 0 on success, negative error code on failure
565 CEPH_RADOS_API
int rados_conf_parse_argv(rados_t cluster
, int argc
,
570 * Configure the cluster handle with command line arguments, returning
571 * any remainders. Same rados_conf_parse_argv, except for extra
572 * remargv argument to hold returns unrecognized arguments.
574 * @pre rados_connect() has not been called on the cluster handle
576 * @param cluster cluster handle to configure
577 * @param argc number of arguments in argv
578 * @param argv arguments to parse
579 * @param remargv char* array for returned unrecognized arguments
580 * @returns 0 on success, negative error code on failure
582 CEPH_RADOS_API
int rados_conf_parse_argv_remainder(rados_t cluster
, int argc
,
584 const char **remargv
);
586 * Configure the cluster handle based on an environment variable
588 * The contents of the environment variable are parsed as if they were
589 * Ceph command line options. If var is NULL, the CEPH_ARGS
590 * environment variable is used.
592 * @pre rados_connect() has not been called on the cluster handle
594 * @note BUG: this is not threadsafe - it uses a static buffer
596 * @param cluster cluster handle to configure
597 * @param var name of the environment variable to read
598 * @returns 0 on success, negative error code on failure
600 CEPH_RADOS_API
int rados_conf_parse_env(rados_t cluster
, const char *var
);
603 * Set a configuration option
605 * @pre rados_connect() has not been called on the cluster handle
607 * @param cluster cluster handle to configure
608 * @param option option to set
609 * @param value value of the option
610 * @returns 0 on success, negative error code on failure
611 * @returns -ENOENT when the option is not a Ceph configuration option
613 CEPH_RADOS_API
int rados_conf_set(rados_t cluster
, const char *option
,
617 * Get the value of a configuration option
619 * @param cluster configuration to read
620 * @param option which option to read
621 * @param buf where to write the configuration value
622 * @param len the size of buf in bytes
623 * @returns 0 on success, negative error code on failure
624 * @returns -ENAMETOOLONG if the buffer is too short to contain the
627 CEPH_RADOS_API
int rados_conf_get(rados_t cluster
, const char *option
,
628 char *buf
, size_t len
);
633 * Read usage info about the cluster
635 * This tells you total space, space used, space available, and number
636 * of objects. These are not updated immediately when data is written,
637 * they are eventually consistent.
639 * @param cluster cluster to query
640 * @param result where to store the results
641 * @returns 0 on success, negative error code on failure
643 CEPH_RADOS_API
int rados_cluster_stat(rados_t cluster
,
644 struct rados_cluster_stat_t
*result
);
647 * Get the fsid of the cluster as a hexadecimal string.
649 * The fsid is a unique id of an entire Ceph cluster.
651 * @param cluster where to get the fsid
652 * @param buf where to write the fsid
653 * @param len the size of buf in bytes (should be 37)
654 * @returns 0 on success, negative error code on failure
655 * @returns -ERANGE if the buffer is too short to contain the
658 CEPH_RADOS_API
int rados_cluster_fsid(rados_t cluster
, char *buf
, size_t len
);
661 * Get/wait for the most recent osdmap
663 * @param cluster the cluster to shutdown
664 * @returns 0 on success, negative error code on failure
666 CEPH_RADOS_API
int rados_wait_for_latest_osdmap(rados_t cluster
);
671 * RADOS pools are separate namespaces for objects. Pools may have
672 * different crush rules associated with them, so they could have
673 * differing replication levels or placement strategies. RADOS
674 * permissions are also tied to pools - users can have different read,
675 * write, and execute permissions on a per-pool basis.
683 * Gets a list of pool names as NULL-terminated strings. The pool
684 * names will be placed in the supplied buffer one after another.
685 * After the last pool name, there will be two 0 bytes in a row.
687 * If len is too short to fit all the pool name entries we need, we will fill
690 * Buf may be null to determine the buffer size needed to list all pools.
692 * @param cluster cluster handle
693 * @param buf output buffer
694 * @param len output buffer length
695 * @returns length of the buffer we would need to list all pools
697 CEPH_RADOS_API
int rados_pool_list(rados_t cluster
, char *buf
, size_t len
);
700 * List inconsistent placement groups of the given pool
702 * Gets a list of inconsistent placement groups as NULL-terminated strings.
703 * The placement group names will be placed in the supplied buffer one after
704 * another. After the last name, there will be two 0 types in a row.
706 * If len is too short to fit all the placement group entries we need, we will
707 * fill as much as we can.
709 * @param cluster cluster handle
710 * @param pool pool ID
711 * @param buf output buffer
712 * @param len output buffer length
713 * @returns length of the buffer we would need to list all pools
715 CEPH_RADOS_API
int rados_inconsistent_pg_list(rados_t cluster
, int64_t pool
,
716 char *buf
, size_t len
);
719 * Get a configuration handle for a rados cluster handle
721 * This handle is valid only as long as the cluster handle is valid.
723 * @param cluster cluster handle
724 * @returns config handle for this cluster
726 CEPH_RADOS_API rados_config_t
rados_cct(rados_t cluster
);
729 * Get a global id for current instance
731 * This id is a unique representation of current connection to the cluster
733 * @param cluster cluster handle
734 * @returns instance global id
736 CEPH_RADOS_API
uint64_t rados_get_instance_id(rados_t cluster
);
739 * Gets the minimum compatible OSD version
741 * @param cluster cluster handle
742 * @param[out] require_osd_release minimum compatible OSD version
743 * based upon the current features
744 * @returns 0 on sucess, negative error code on failure
746 CEPH_RADOS_API
int rados_get_min_compatible_osd(rados_t cluster
,
747 int8_t* require_osd_release
);
750 * Gets the minimum compatible client version
752 * @param cluster cluster handle
753 * @param[out] min_compat_client minimum compatible client version
754 * based upon the current features
755 * @param[out] require_min_compat_client required minimum client version
756 * based upon explicit setting
757 * @returns 0 on success, negative error code on failure
759 CEPH_RADOS_API
int rados_get_min_compatible_client(rados_t cluster
,
760 int8_t* min_compat_client
,
761 int8_t* require_min_compat_client
);
764 * Create an io context
766 * The io context allows you to perform operations within a particular
767 * pool. For more details see rados_ioctx_t.
769 * @param cluster which cluster the pool is in
770 * @param pool_name name of the pool
771 * @param ioctx where to store the io context
772 * @returns 0 on success, negative error code on failure
774 CEPH_RADOS_API
int rados_ioctx_create(rados_t cluster
, const char *pool_name
,
775 rados_ioctx_t
*ioctx
);
776 CEPH_RADOS_API
int rados_ioctx_create2(rados_t cluster
, int64_t pool_id
,
777 rados_ioctx_t
*ioctx
);
780 * The opposite of rados_ioctx_create
782 * This just tells librados that you no longer need to use the io context.
783 * It may not be freed immediately if there are pending asynchronous
784 * requests on it, but you should not use an io context again after
785 * calling this function on it.
787 * @warning This does not guarantee any asynchronous
788 * writes have completed. You must call rados_aio_flush()
789 * on the io context before destroying it to do that.
791 * @warning If this ioctx is used by rados_watch, the caller needs to
792 * be sure that all registered watches are disconnected via
793 * rados_unwatch() and that rados_watch_flush() is called. This
794 * ensures that a racing watch callback does not make use of a
797 * @param io the io context to dispose of
799 CEPH_RADOS_API
void rados_ioctx_destroy(rados_ioctx_t io
);
802 * Get configuration handle for a pool handle
804 * @param io pool handle
805 * @returns rados_config_t for this cluster
807 CEPH_RADOS_API rados_config_t
rados_ioctx_cct(rados_ioctx_t io
);
810 * Get the cluster handle used by this rados_ioctx_t
811 * Note that this is a weak reference, and should not
812 * be destroyed via rados_shutdown().
814 * @param io the io context
815 * @returns the cluster handle for this io context
817 CEPH_RADOS_API rados_t
rados_ioctx_get_cluster(rados_ioctx_t io
);
820 * Get pool usage statistics
822 * Fills in a rados_pool_stat_t after querying the cluster.
824 * @param io determines which pool to query
825 * @param stats where to store the results
826 * @returns 0 on success, negative error code on failure
828 CEPH_RADOS_API
int rados_ioctx_pool_stat(rados_ioctx_t io
,
829 struct rados_pool_stat_t
*stats
);
832 * Get the id of a pool
834 * @param cluster which cluster the pool is in
835 * @param pool_name which pool to look up
836 * @returns id of the pool
837 * @returns -ENOENT if the pool is not found
839 CEPH_RADOS_API
int64_t rados_pool_lookup(rados_t cluster
,
840 const char *pool_name
);
843 * Get the name of a pool
845 * @param cluster which cluster the pool is in
846 * @param id the id of the pool
847 * @param buf where to store the pool name
848 * @param maxlen size of buffer where name will be stored
849 * @returns length of string stored, or -ERANGE if buffer too small
851 CEPH_RADOS_API
int rados_pool_reverse_lookup(rados_t cluster
, int64_t id
,
852 char *buf
, size_t maxlen
);
855 * Create a pool with default settings
857 * The default crush rule is rule 0.
859 * @param cluster the cluster in which the pool will be created
860 * @param pool_name the name of the new pool
861 * @returns 0 on success, negative error code on failure
863 CEPH_RADOS_API
int rados_pool_create(rados_t cluster
, const char *pool_name
);
866 * Create a pool owned by a specific auid.
868 * DEPRECATED: auid support has been removed, and this call will be removed in a future
871 * @param cluster the cluster in which the pool will be created
872 * @param pool_name the name of the new pool
873 * @param auid the id of the owner of the new pool
874 * @returns 0 on success, negative error code on failure
876 CEPH_RADOS_API
int rados_pool_create_with_auid(rados_t cluster
,
877 const char *pool_name
,
879 __attribute__((deprecated
));
882 * Create a pool with a specific CRUSH rule
884 * @param cluster the cluster in which the pool will be created
885 * @param pool_name the name of the new pool
886 * @param crush_rule_num which rule to use for placement in the new pool1
887 * @returns 0 on success, negative error code on failure
889 CEPH_RADOS_API
int rados_pool_create_with_crush_rule(rados_t cluster
,
890 const char *pool_name
,
891 uint8_t crush_rule_num
);
894 * Create a pool with a specific CRUSH rule and auid
896 * DEPRECATED: auid support has been removed and this call will be removed
897 * in a future release.
899 * This is a combination of rados_pool_create_with_crush_rule() and
900 * rados_pool_create_with_auid().
902 * @param cluster the cluster in which the pool will be created
903 * @param pool_name the name of the new pool
904 * @param crush_rule_num which rule to use for placement in the new pool2
905 * @param auid the id of the owner of the new pool
906 * @returns 0 on success, negative error code on failure
908 CEPH_RADOS_API
int rados_pool_create_with_all(rados_t cluster
,
909 const char *pool_name
,
911 uint8_t crush_rule_num
)
912 __attribute__((deprecated
));
915 * Returns the pool that is the base tier for this pool.
917 * The return value is the ID of the pool that should be used to read from/write to.
918 * If tiering is not set up for the pool, returns \c pool.
920 * @param cluster the cluster the pool is in
921 * @param pool ID of the pool to query
922 * @param[out] base_tier base tier, or \c pool if tiering is not configured
923 * @returns 0 on success, negative error code on failure
925 CEPH_RADOS_API
int rados_pool_get_base_tier(rados_t cluster
, int64_t pool
,
929 * Delete a pool and all data inside it
931 * The pool is removed from the cluster immediately,
932 * but the actual data is deleted in the background.
934 * @param cluster the cluster the pool is in
935 * @param pool_name which pool to delete
936 * @returns 0 on success, negative error code on failure
938 CEPH_RADOS_API
int rados_pool_delete(rados_t cluster
, const char *pool_name
);
941 * Attempt to change an io context's associated auid "owner"
943 * DEPRECATED: auid support has been removed and this call has no effect.
945 * Requires that you have write permission on both the current and new
948 * @param io reference to the pool to change.
949 * @param auid the auid you wish the io to have.
950 * @returns 0 on success, negative error code on failure
952 CEPH_RADOS_API
int rados_ioctx_pool_set_auid(rados_ioctx_t io
, uint64_t auid
)
953 __attribute__((deprecated
));
957 * Get the auid of a pool
959 * DEPRECATED: auid support has been removed and this call always reports
960 * CEPH_AUTH_UID_DEFAULT (-1).
962 * @param io pool to query
963 * @param auid where to store the auid
964 * @returns 0 on success, negative error code on failure
966 CEPH_RADOS_API
int rados_ioctx_pool_get_auid(rados_ioctx_t io
, uint64_t *auid
)
967 __attribute__((deprecated
));
969 /* deprecated, use rados_ioctx_pool_requires_alignment2 instead */
970 CEPH_RADOS_API
int rados_ioctx_pool_requires_alignment(rados_ioctx_t io
)
971 __attribute__((deprecated
));
974 * Test whether the specified pool requires alignment or not.
976 * @param io pool to query
977 * @param req 1 if alignment is supported, 0 if not.
978 * @returns 0 on success, negative error code on failure
980 CEPH_RADOS_API
int rados_ioctx_pool_requires_alignment2(rados_ioctx_t io
,
983 /* deprecated, use rados_ioctx_pool_required_alignment2 instead */
984 CEPH_RADOS_API
uint64_t rados_ioctx_pool_required_alignment(rados_ioctx_t io
)
985 __attribute__((deprecated
));
988 * Get the alignment flavor of a pool
990 * @param io pool to query
991 * @param alignment where to store the alignment flavor
992 * @returns 0 on success, negative error code on failure
994 CEPH_RADOS_API
int rados_ioctx_pool_required_alignment2(rados_ioctx_t io
,
995 uint64_t *alignment
);
998 * Get the pool id of the io context
1000 * @param io the io context to query
1001 * @returns the id of the pool the io context uses
1003 CEPH_RADOS_API
int64_t rados_ioctx_get_id(rados_ioctx_t io
);
1006 * Get the pool name of the io context
1008 * @param io the io context to query
1009 * @param buf pointer to buffer where name will be stored
1010 * @param maxlen size of buffer where name will be stored
1011 * @returns length of string stored, or -ERANGE if buffer too small
1013 CEPH_RADOS_API
int rados_ioctx_get_pool_name(rados_ioctx_t io
, char *buf
,
1019 * @name Object Locators
1025 * Set the key for mapping objects to pgs within an io context.
1027 * The key is used instead of the object name to determine which
1028 * placement groups an object is put in. This affects all subsequent
1029 * operations of the io context - until a different locator key is
1030 * set, all objects in this io context will be placed in the same pg.
1032 * @param io the io context to change
1033 * @param key the key to use as the object locator, or NULL to discard
1034 * any previously set key
1036 CEPH_RADOS_API
void rados_ioctx_locator_set_key(rados_ioctx_t io
,
1040 * Set the namespace for objects within an io context
1042 * The namespace specification further refines a pool into different
1043 * domains. The mapping of objects to pgs is also based on this
1046 * @param io the io context to change
1047 * @param nspace the name to use as the namespace, or NULL use the
1050 CEPH_RADOS_API
void rados_ioctx_set_namespace(rados_ioctx_t io
,
1051 const char *nspace
);
1054 * Get the namespace for objects within the io context
1056 * @param io the io context to query
1057 * @param buf pointer to buffer where name will be stored
1058 * @param maxlen size of buffer where name will be stored
1059 * @returns length of string stored, or -ERANGE if buffer too small
1061 CEPH_RADOS_API
int rados_ioctx_get_namespace(rados_ioctx_t io
, char *buf
,
1067 * @name Listing Objects
1071 * Start listing objects in a pool
1073 * @param io the pool to list from
1074 * @param ctx the handle to store list context in
1075 * @returns 0 on success, negative error code on failure
1077 CEPH_RADOS_API
int rados_nobjects_list_open(rados_ioctx_t io
,
1078 rados_list_ctx_t
*ctx
);
1081 * Return hash position of iterator, rounded to the current PG
1083 * @param ctx iterator marking where you are in the listing
1084 * @returns current hash position, rounded to the current pg
1086 CEPH_RADOS_API
uint32_t rados_nobjects_list_get_pg_hash_position(rados_list_ctx_t ctx
);
1089 * Reposition object iterator to a different hash position
1091 * @param ctx iterator marking where you are in the listing
1092 * @param pos hash position to move to
1093 * @returns actual (rounded) position we moved to
1095 CEPH_RADOS_API
uint32_t rados_nobjects_list_seek(rados_list_ctx_t ctx
,
1099 * Reposition object iterator to a different position
1101 * @param ctx iterator marking where you are in the listing
1102 * @param cursor position to move to
1103 * @returns rounded position we moved to
1105 CEPH_RADOS_API
uint32_t rados_nobjects_list_seek_cursor(rados_list_ctx_t ctx
,
1106 rados_object_list_cursor cursor
);
1109 * Reposition object iterator to a different position
1111 * The returned handle must be released with rados_object_list_cursor_free().
1113 * @param ctx iterator marking where you are in the listing
1114 * @param cursor where to store cursor
1115 * @returns 0 on success, negative error code on failure
1117 CEPH_RADOS_API
int rados_nobjects_list_get_cursor(rados_list_ctx_t ctx
,
1118 rados_object_list_cursor
*cursor
);
1121 * Get the next object name and locator in the pool
1123 * *entry and *key are valid until next call to rados_nobjects_list_*
1125 * @param ctx iterator marking where you are in the listing
1126 * @param entry where to store the name of the entry
1127 * @param key where to store the object locator (set to NULL to ignore)
1128 * @param nspace where to store the object namespace (set to NULL to ignore)
1129 * @returns 0 on success, negative error code on failure
1130 * @returns -ENOENT when there are no more objects to list
1132 CEPH_RADOS_API
int rados_nobjects_list_next(rados_list_ctx_t ctx
,
1135 const char **nspace
);
1138 * Close the object listing handle.
1140 * This should be called when the handle is no longer needed.
1141 * The handle should not be used after it has been closed.
1143 * @param ctx the handle to close
1145 CEPH_RADOS_API
void rados_nobjects_list_close(rados_list_ctx_t ctx
);
1148 * Get cursor handle pointing to the *beginning* of a pool.
1150 * This is an opaque handle pointing to the start of a pool. It must
1151 * be released with rados_object_list_cursor_free().
1153 * @param io ioctx for the pool
1154 * @returns handle for the pool, NULL on error (pool does not exist)
1156 CEPH_RADOS_API rados_object_list_cursor
rados_object_list_begin(
1160 * Get cursor handle pointing to the *end* of a pool.
1162 * This is an opaque handle pointing to the start of a pool. It must
1163 * be released with rados_object_list_cursor_free().
1165 * @param io ioctx for the pool
1166 * @returns handle for the pool, NULL on error (pool does not exist)
1168 CEPH_RADOS_API rados_object_list_cursor
rados_object_list_end(rados_ioctx_t io
);
1171 * Check if a cursor has reached the end of a pool
1175 * @returns 1 if the cursor has reached the end of the pool, 0 otherwise
1177 CEPH_RADOS_API
int rados_object_list_is_end(rados_ioctx_t io
,
1178 rados_object_list_cursor cur
);
1183 * Release a cursor. The handle may not be used after this point.
1188 CEPH_RADOS_API
void rados_object_list_cursor_free(rados_ioctx_t io
,
1189 rados_object_list_cursor cur
);
1192 * Compare two cursor positions
1194 * Compare two cursors, and indicate whether the first cursor precedes,
1195 * matches, or follows the second.
1198 * @param lhs first cursor
1199 * @param rhs second cursor
1200 * @returns -1, 0, or 1 for lhs < rhs, lhs == rhs, or lhs > rhs
1202 CEPH_RADOS_API
int rados_object_list_cursor_cmp(rados_ioctx_t io
,
1203 rados_object_list_cursor lhs
, rados_object_list_cursor rhs
);
1206 * @return the number of items set in the results array
1208 CEPH_RADOS_API
int rados_object_list(rados_ioctx_t io
,
1209 const rados_object_list_cursor start
,
1210 const rados_object_list_cursor finish
,
1211 const size_t result_size
,
1212 const char *filter_buf
,
1213 const size_t filter_buf_len
,
1214 rados_object_list_item
*results
,
1215 rados_object_list_cursor
*next
);
1217 CEPH_RADOS_API
void rados_object_list_free(
1218 const size_t result_size
,
1219 rados_object_list_item
*results
);
1222 * Obtain cursors delineating a subset of a range. Use this
1223 * when you want to split up the work of iterating over the
1224 * global namespace. Expected use case is when you are iterating
1225 * in parallel, with `m` workers, and each worker taking an id `n`.
1228 * @param start start of the range to be sliced up (inclusive)
1229 * @param finish end of the range to be sliced up (exclusive)
1230 * @param n which of the m chunks you would like to get cursors for
1231 * @param m how many chunks to divide start-finish into
1232 * @param split_start cursor populated with start of the subrange (inclusive)
1233 * @param split_finish cursor populated with end of the subrange (exclusive)
1235 CEPH_RADOS_API
void rados_object_list_slice(rados_ioctx_t io
,
1236 const rados_object_list_cursor start
,
1237 const rados_object_list_cursor finish
,
1240 rados_object_list_cursor
*split_start
,
1241 rados_object_list_cursor
*split_finish
);
1244 /** @} Listing Objects */
1249 * RADOS snapshots are based upon sequence numbers that form a
1250 * snapshot context. They are pool-specific. The snapshot context
1251 * consists of the current snapshot sequence number for a pool, and an
1252 * array of sequence numbers at which snapshots were taken, in
1253 * descending order. Whenever a snapshot is created or deleted, the
1254 * snapshot sequence number for the pool is increased. To add a new
1255 * snapshot, the new snapshot sequence number must be increased and
1256 * added to the snapshot context.
1258 * There are two ways to manage these snapshot contexts:
1259 * -# within the RADOS cluster
1260 * These are called pool snapshots, and store the snapshot context
1261 * in the OSDMap. These represent a snapshot of all the objects in
1263 * -# within the RADOS clients
1264 * These are called self-managed snapshots, and push the
1265 * responsibility for keeping track of the snapshot context to the
1266 * clients. For every write, the client must send the snapshot
1267 * context. In librados, this is accomplished with
1268 * rados_selfmanaged_snap_set_write_ctx(). These are more
1269 * difficult to manage, but are restricted to specific objects
1270 * instead of applying to an entire pool.
1276 * Create a pool-wide snapshot
1278 * @param io the pool to snapshot
1279 * @param snapname the name of the snapshot
1280 * @returns 0 on success, negative error code on failure
1282 CEPH_RADOS_API
int rados_ioctx_snap_create(rados_ioctx_t io
,
1283 const char *snapname
);
1286 * Delete a pool snapshot
1288 * @param io the pool to delete the snapshot from
1289 * @param snapname which snapshot to delete
1290 * @returns 0 on success, negative error code on failure
1292 CEPH_RADOS_API
int rados_ioctx_snap_remove(rados_ioctx_t io
,
1293 const char *snapname
);
1296 * Rollback an object to a pool snapshot
1298 * The contents of the object will be the same as
1299 * when the snapshot was taken.
1301 * @param io the pool in which the object is stored
1302 * @param oid the name of the object to rollback
1303 * @param snapname which snapshot to rollback to
1304 * @returns 0 on success, negative error code on failure
1306 CEPH_RADOS_API
int rados_ioctx_snap_rollback(rados_ioctx_t io
, const char *oid
,
1307 const char *snapname
);
1310 * @warning Deprecated: Use rados_ioctx_snap_rollback() instead
1312 CEPH_RADOS_API
int rados_rollback(rados_ioctx_t io
, const char *oid
,
1313 const char *snapname
)
1314 __attribute__((deprecated
));
1317 * Set the snapshot from which reads are performed.
1319 * Subsequent reads will return data as it was at the time of that
1322 * @param io the io context to change
1323 * @param snap the id of the snapshot to set, or LIBRADOS_SNAP_HEAD for no
1324 * snapshot (i.e. normal operation)
1326 CEPH_RADOS_API
void rados_ioctx_snap_set_read(rados_ioctx_t io
,
1330 * Allocate an ID for a self-managed snapshot
1332 * Get a unique ID to put in the snaphot context to create a
1333 * snapshot. A clone of an object is not created until a write with
1334 * the new snapshot context is completed.
1336 * @param io the pool in which the snapshot will exist
1337 * @param snapid where to store the newly allocated snapshot ID
1338 * @returns 0 on success, negative error code on failure
1340 CEPH_RADOS_API
int rados_ioctx_selfmanaged_snap_create(rados_ioctx_t io
,
1341 rados_snap_t
*snapid
);
1343 rados_aio_ioctx_selfmanaged_snap_create(rados_ioctx_t io
,
1344 rados_snap_t
*snapid
,
1345 rados_completion_t completion
);
1348 * Remove a self-managed snapshot
1350 * This increases the snapshot sequence number, which will cause
1351 * snapshots to be removed lazily.
1353 * @param io the pool in which the snapshot will exist
1354 * @param snapid where to store the newly allocated snapshot ID
1355 * @returns 0 on success, negative error code on failure
1357 CEPH_RADOS_API
int rados_ioctx_selfmanaged_snap_remove(rados_ioctx_t io
,
1358 rados_snap_t snapid
);
1360 rados_aio_ioctx_selfmanaged_snap_remove(rados_ioctx_t io
,
1361 rados_snap_t snapid
,
1362 rados_completion_t completion
);
1365 * Rollback an object to a self-managed snapshot
1367 * The contents of the object will be the same as
1368 * when the snapshot was taken.
1370 * @param io the pool in which the object is stored
1371 * @param oid the name of the object to rollback
1372 * @param snapid which snapshot to rollback to
1373 * @returns 0 on success, negative error code on failure
1375 CEPH_RADOS_API
int rados_ioctx_selfmanaged_snap_rollback(rados_ioctx_t io
,
1377 rados_snap_t snapid
);
1380 * Set the snapshot context for use when writing to objects
1382 * This is stored in the io context, and applies to all future writes.
1384 * @param io the io context to change
1385 * @param seq the newest snapshot sequence number for the pool
1386 * @param snaps array of snapshots in sorted by descending id
1387 * @param num_snaps how many snaphosts are in the snaps array
1388 * @returns 0 on success, negative error code on failure
1389 * @returns -EINVAL if snaps are not in descending order
1391 CEPH_RADOS_API
int rados_ioctx_selfmanaged_snap_set_write_ctx(rados_ioctx_t io
,
1393 rados_snap_t
*snaps
,
1397 * List all the ids of pool snapshots
1399 * If the output array does not have enough space to fit all the
1400 * snapshots, -ERANGE is returned and the caller should retry with a
1403 * @param io the pool to read from
1404 * @param snaps where to store the results
1405 * @param maxlen the number of rados_snap_t that fit in the snaps array
1406 * @returns number of snapshots on success, negative error code on failure
1407 * @returns -ERANGE is returned if the snaps array is too short
1409 CEPH_RADOS_API
int rados_ioctx_snap_list(rados_ioctx_t io
, rados_snap_t
*snaps
,
1413 * Get the id of a pool snapshot
1415 * @param io the pool to read from
1416 * @param name the snapshot to find
1417 * @param id where to store the result
1418 * @returns 0 on success, negative error code on failure
1420 CEPH_RADOS_API
int rados_ioctx_snap_lookup(rados_ioctx_t io
, const char *name
,
1424 * Get the name of a pool snapshot
1426 * @param io the pool to read from
1427 * @param id the snapshot to find
1428 * @param name where to store the result
1429 * @param maxlen the size of the name array
1430 * @returns 0 on success, negative error code on failure
1431 * @returns -ERANGE if the name array is too small
1433 CEPH_RADOS_API
int rados_ioctx_snap_get_name(rados_ioctx_t io
, rados_snap_t id
,
1434 char *name
, int maxlen
);
1437 * Find when a pool snapshot occurred
1439 * @param io the pool the snapshot was taken in
1440 * @param id the snapshot to lookup
1441 * @param t where to store the result
1442 * @returns 0 on success, negative error code on failure
1444 CEPH_RADOS_API
int rados_ioctx_snap_get_stamp(rados_ioctx_t io
, rados_snap_t id
,
1450 * @name Synchronous I/O
1451 * Writes are replicated to a number of OSDs based on the
1452 * configuration of the pool they are in. These write functions block
1453 * until data is in memory on all replicas of the object they're
1454 * writing to - they are equivalent to doing the corresponding
1455 * asynchronous write, and the calling
1456 * rados_ioctx_wait_for_complete(). For greater data safety, use the
1457 * asynchronous functions and rados_aio_wait_for_safe().
1463 * Return the version of the last object read or written to.
1465 * This exposes the internal version number of the last object read or
1466 * written via this io context
1468 * @param io the io context to check
1469 * @returns last read or written object version
1471 CEPH_RADOS_API
uint64_t rados_get_last_version(rados_ioctx_t io
);
1474 * Write *len* bytes from *buf* into the *oid* object, starting at
1475 * offset *off*. The value of *len* must be <= UINT_MAX/2.
1477 * @note This will never return a positive value not equal to len.
1478 * @param io the io context in which the write will occur
1479 * @param oid name of the object
1480 * @param buf data to write
1481 * @param len length of the data, in bytes
1482 * @param off byte offset in the object to begin writing at
1483 * @returns 0 on success, negative error code on failure
1485 CEPH_RADOS_API
int rados_write(rados_ioctx_t io
, const char *oid
,
1486 const char *buf
, size_t len
, uint64_t off
);
1489 * Write *len* bytes from *buf* into the *oid* object. The value of
1490 * *len* must be <= UINT_MAX/2.
1492 * The object is filled with the provided data. If the object exists,
1493 * it is atomically truncated and then written.
1495 * @param io the io context in which the write will occur
1496 * @param oid name of the object
1497 * @param buf data to write
1498 * @param len length of the data, in bytes
1499 * @returns 0 on success, negative error code on failure
1501 CEPH_RADOS_API
int rados_write_full(rados_ioctx_t io
, const char *oid
,
1502 const char *buf
, size_t len
);
1505 * Write the same *data_len* bytes from *buf* multiple times into the
1506 * *oid* object. *write_len* bytes are written in total, which must be
1507 * a multiple of *data_len*. The value of *write_len* and *data_len*
1508 * must be <= UINT_MAX/2.
1510 * @param io the io context in which the write will occur
1511 * @param oid name of the object
1512 * @param buf data to write
1513 * @param data_len length of the data, in bytes
1514 * @param write_len the total number of bytes to write
1515 * @param off byte offset in the object to begin writing at
1516 * @returns 0 on success, negative error code on failure
1518 CEPH_RADOS_API
int rados_writesame(rados_ioctx_t io
, const char *oid
,
1519 const char *buf
, size_t data_len
,
1520 size_t write_len
, uint64_t off
);
1523 * Append *len* bytes from *buf* into the *oid* object. The value of
1524 * *len* must be <= UINT_MAX/2.
1526 * @param io the context to operate in
1527 * @param oid the name of the object
1528 * @param buf the data to append
1529 * @param len length of buf (in bytes)
1530 * @returns 0 on success, negative error code on failure
1532 CEPH_RADOS_API
int rados_append(rados_ioctx_t io
, const char *oid
,
1533 const char *buf
, size_t len
);
1536 * Read data from an object
1538 * The io context determines the snapshot to read from, if any was set
1539 * by rados_ioctx_snap_set_read().
1541 * @param io the context in which to perform the read
1542 * @param oid the name of the object to read from
1543 * @param buf where to store the results
1544 * @param len the number of bytes to read
1545 * @param off the offset to start reading from in the object
1546 * @returns number of bytes read on success, negative error code on
1549 CEPH_RADOS_API
int rados_read(rados_ioctx_t io
, const char *oid
, char *buf
,
1550 size_t len
, uint64_t off
);
1553 * Compute checksum from object data
1555 * The io context determines the snapshot to checksum, if any was set
1556 * by rados_ioctx_snap_set_read(). The length of the init_value and
1557 * resulting checksum are dependent upon the checksum type:
1563 * The checksum result is encoded the following manner:
1565 * le32 num_checksum_chunks
1567 * leXX checksum for chunk (where XX = appropriate size for the checksum type)
1568 * } * num_checksum_chunks
1570 * @param io the context in which to perform the checksum
1571 * @param oid the name of the object to checksum
1572 * @param type the checksum algorithm to utilize
1573 * @param init_value the init value for the algorithm
1574 * @param init_value_len the length of the init value
1575 * @param len the number of bytes to checksum
1576 * @param off the offset to start checksumming in the object
1577 * @param chunk_size optional length-aligned chunk size for checksums
1578 * @param pchecksum where to store the checksum result
1579 * @param checksum_len the number of bytes available for the result
1580 * @return negative error code on failure
1582 CEPH_RADOS_API
int rados_checksum(rados_ioctx_t io
, const char *oid
,
1583 rados_checksum_type_t type
,
1584 const char *init_value
, size_t init_value_len
,
1585 size_t len
, uint64_t off
, size_t chunk_size
,
1586 char *pchecksum
, size_t checksum_len
);
1591 * @note This does not delete any snapshots of the object.
1593 * @param io the pool to delete the object from
1594 * @param oid the name of the object to delete
1595 * @returns 0 on success, negative error code on failure
1597 CEPH_RADOS_API
int rados_remove(rados_ioctx_t io
, const char *oid
);
1602 * If this enlarges the object, the new area is logically filled with
1603 * zeroes. If this shrinks the object, the excess data is removed.
1605 * @param io the context in which to truncate
1606 * @param oid the name of the object
1607 * @param size the new size of the object in bytes
1608 * @returns 0 on success, negative error code on failure
1610 CEPH_RADOS_API
int rados_trunc(rados_ioctx_t io
, const char *oid
,
1614 * Compare an on-disk object range with a buffer
1616 * @param io the context in which to perform the comparison
1617 * @param o name of the object
1618 * @param cmp_buf buffer containing bytes to be compared with object contents
1619 * @param cmp_len length to compare and size of @c cmp_buf in bytes
1620 * @param off object byte offset at which to start the comparison
1621 * @returns 0 on success, negative error code on failure,
1622 * (-MAX_ERRNO - mismatch_off) on mismatch
1624 CEPH_RADOS_API
int rados_cmpext(rados_ioctx_t io
, const char *o
,
1625 const char *cmp_buf
, size_t cmp_len
,
1630 * Extended attributes are stored as extended attributes on the files
1631 * representing an object on the OSDs. Thus, they have the same
1632 * limitations as the underlying filesystem. On ext4, this means that
1633 * the total data stored in xattrs cannot exceed 4KB.
1639 * Get the value of an extended attribute on an object.
1641 * @param io the context in which the attribute is read
1642 * @param o name of the object
1643 * @param name which extended attribute to read
1644 * @param buf where to store the result
1645 * @param len size of buf in bytes
1646 * @returns length of xattr value on success, negative error code on failure
1648 CEPH_RADOS_API
int rados_getxattr(rados_ioctx_t io
, const char *o
,
1649 const char *name
, char *buf
, size_t len
);
1652 * Set an extended attribute on an object.
1654 * @param io the context in which xattr is set
1655 * @param o name of the object
1656 * @param name which extended attribute to set
1657 * @param buf what to store in the xattr
1658 * @param len the number of bytes in buf
1659 * @returns 0 on success, negative error code on failure
1661 CEPH_RADOS_API
int rados_setxattr(rados_ioctx_t io
, const char *o
,
1662 const char *name
, const char *buf
,
1666 * Delete an extended attribute from an object.
1668 * @param io the context in which to delete the xattr
1669 * @param o the name of the object
1670 * @param name which xattr to delete
1671 * @returns 0 on success, negative error code on failure
1673 CEPH_RADOS_API
int rados_rmxattr(rados_ioctx_t io
, const char *o
,
1677 * Start iterating over xattrs on an object.
1679 * @post iter is a valid iterator
1681 * @param io the context in which to list xattrs
1682 * @param oid name of the object
1683 * @param iter where to store the iterator
1684 * @returns 0 on success, negative error code on failure
1686 CEPH_RADOS_API
int rados_getxattrs(rados_ioctx_t io
, const char *oid
,
1687 rados_xattrs_iter_t
*iter
);
1690 * Get the next xattr on the object
1692 * @pre iter is a valid iterator
1694 * @post name is the NULL-terminated name of the next xattr, and val
1695 * contains the value of the xattr, which is of length len. If the end
1696 * of the list has been reached, name and val are NULL, and len is 0.
1698 * @param iter iterator to advance
1699 * @param name where to store the name of the next xattr
1700 * @param val where to store the value of the next xattr
1701 * @param len the number of bytes in val
1702 * @returns 0 on success, negative error code on failure
1704 CEPH_RADOS_API
int rados_getxattrs_next(rados_xattrs_iter_t iter
,
1705 const char **name
, const char **val
,
1709 * Close the xattr iterator.
1711 * iter should not be used after this is called.
1713 * @param iter the iterator to close
1715 CEPH_RADOS_API
void rados_getxattrs_end(rados_xattrs_iter_t iter
);
1720 * Get the next omap key/value pair on the object
1722 * @pre iter is a valid iterator
1724 * @post key and val are the next key/value pair. key is
1725 * null-terminated, and val has length len. If the end of the list has
1726 * been reached, key and val are NULL, and len is 0. key and val will
1727 * not be accessible after rados_omap_get_end() is called on iter, so
1728 * if they are needed after that they should be copied.
1730 * @param iter iterator to advance
1731 * @param key where to store the key of the next omap entry
1732 * @param val where to store the value of the next omap entry
1733 * @param len where to store the number of bytes in val
1734 * @returns 0 on success, negative error code on failure
1736 CEPH_RADOS_API
int rados_omap_get_next(rados_omap_iter_t iter
,
1742 * Get the next omap key/value pair on the object. Note that it's
1743 * perfectly safe to mix calls to rados_omap_get_next and
1744 * rados_omap_get_next2.
1746 * @pre iter is a valid iterator
1748 * @post key and val are the next key/value pair. key has length
1749 * keylen and val has length vallen. If the end of the list has
1750 * been reached, key and val are NULL, and keylen and vallen is 0.
1751 * key and val will not be accessible after rados_omap_get_end()
1752 * is called on iter, so if they are needed after that they
1755 * @param iter iterator to advance
1756 * @param key where to store the key of the next omap entry
1757 * @param val where to store the value of the next omap entry
1758 * @param key_len where to store the number of bytes in key
1759 * @param val_len where to store the number of bytes in val
1760 * @returns 0 on success, negative error code on failure
1762 CEPH_RADOS_API
int rados_omap_get_next2(rados_omap_iter_t iter
,
1769 * Return number of elements in the iterator
1771 * @param iter the iterator of which to return the size
1773 CEPH_RADOS_API
unsigned int rados_omap_iter_size(rados_omap_iter_t iter
);
1776 * Close the omap iterator.
1778 * iter should not be used after this is called.
1780 * @param iter the iterator to close
1782 CEPH_RADOS_API
void rados_omap_get_end(rados_omap_iter_t iter
);
1785 * Get object stats (size/mtime)
1787 * TODO: when are these set, and by whom? can they be out of date?
1790 * @param o object name
1791 * @param psize where to store object size
1792 * @param pmtime where to store modification time
1793 * @returns 0 on success, negative error code on failure
1795 CEPH_RADOS_API
int rados_stat(rados_ioctx_t io
, const char *o
, uint64_t *psize
,
1798 * Execute an OSD class method on an object
1800 * The OSD has a plugin mechanism for performing complicated
1801 * operations on an object atomically. These plugins are called
1802 * classes. This function allows librados users to call the custom
1803 * methods. The input and output formats are defined by the class.
1804 * Classes in ceph.git can be found in src/cls subdirectories
1806 * @param io the context in which to call the method
1807 * @param oid the object to call the method on
1808 * @param cls the name of the class
1809 * @param method the name of the method
1810 * @param in_buf where to find input
1811 * @param in_len length of in_buf in bytes
1812 * @param buf where to store output
1813 * @param out_len length of buf in bytes
1814 * @returns the length of the output, or
1815 * -ERANGE if out_buf does not have enough space to store it (For methods that return data). For
1816 * methods that don't return data, the return value is
1819 CEPH_RADOS_API
int rados_exec(rados_ioctx_t io
, const char *oid
,
1820 const char *cls
, const char *method
,
1821 const char *in_buf
, size_t in_len
, char *buf
,
1825 /** @} Synchronous I/O */
1828 * @name Asynchronous I/O
1829 * Read and write to objects without blocking.
1835 * @typedef rados_callback_t
1836 * Callbacks for asynchrous operations take two parameters:
1837 * - cb the completion that has finished
1838 * - arg application defined data made available to the callback function
1840 typedef void (*rados_callback_t
)(rados_completion_t cb
, void *arg
);
1843 * Constructs a completion to use with asynchronous operations
1845 * The complete and safe callbacks correspond to operations being
1846 * acked and committed, respectively. The callbacks are called in
1847 * order of receipt, so the safe callback may be triggered before the
1848 * complete callback, and vice versa. This is affected by journalling
1851 * TODO: more complete documentation of this elsewhere (in the RADOS docs?)
1853 * @note Read operations only get a complete callback.
1854 * @note BUG: this should check for ENOMEM instead of throwing an exception
1856 * @param cb_arg application-defined data passed to the callback functions
1857 * @param cb_complete the function to be called when the operation is
1858 * in memory on all relpicas
1859 * @param cb_safe the function to be called when the operation is on
1860 * stable storage on all replicas
1861 * @param pc where to store the completion
1864 CEPH_RADOS_API
int rados_aio_create_completion(void *cb_arg
,
1865 rados_callback_t cb_complete
,
1866 rados_callback_t cb_safe
,
1867 rados_completion_t
*pc
);
1870 * Block until an operation completes
1872 * This means it is in memory on all replicas.
1874 * @note BUG: this should be void
1876 * @param c operation to wait for
1879 CEPH_RADOS_API
int rados_aio_wait_for_complete(rados_completion_t c
);
1882 * Block until an operation is safe
1884 * This means it is on stable storage on all replicas.
1886 * @note BUG: this should be void
1888 * @param c operation to wait for
1891 CEPH_RADOS_API
int rados_aio_wait_for_safe(rados_completion_t c
);
1894 * Has an asynchronous operation completed?
1896 * @warning This does not imply that the complete callback has
1899 * @param c async operation to inspect
1900 * @returns whether c is complete
1902 CEPH_RADOS_API
int rados_aio_is_complete(rados_completion_t c
);
1905 * Is an asynchronous operation safe?
1907 * @warning This does not imply that the safe callback has
1910 * @param c async operation to inspect
1911 * @returns whether c is safe
1913 CEPH_RADOS_API
int rados_aio_is_safe(rados_completion_t c
);
1916 * Block until an operation completes and callback completes
1918 * This means it is in memory on all replicas and can be read.
1920 * @note BUG: this should be void
1922 * @param c operation to wait for
1925 CEPH_RADOS_API
int rados_aio_wait_for_complete_and_cb(rados_completion_t c
);
1928 * Block until an operation is safe and callback has completed
1930 * This means it is on stable storage on all replicas.
1932 * @note BUG: this should be void
1934 * @param c operation to wait for
1937 CEPH_RADOS_API
int rados_aio_wait_for_safe_and_cb(rados_completion_t c
);
1940 * Has an asynchronous operation and callback completed
1942 * @param c async operation to inspect
1943 * @returns whether c is complete
1945 CEPH_RADOS_API
int rados_aio_is_complete_and_cb(rados_completion_t c
);
1948 * Is an asynchronous operation safe and has the callback completed
1950 * @param c async operation to inspect
1951 * @returns whether c is safe
1953 CEPH_RADOS_API
int rados_aio_is_safe_and_cb(rados_completion_t c
);
1956 * Get the return value of an asychronous operation
1958 * The return value is set when the operation is complete or safe,
1959 * whichever comes first.
1961 * @pre The operation is safe or complete
1963 * @note BUG: complete callback may never be called when the safe
1964 * message is received before the complete message
1966 * @param c async operation to inspect
1967 * @returns return value of the operation
1969 CEPH_RADOS_API
int rados_aio_get_return_value(rados_completion_t c
);
1972 * Get the internal object version of the target of an asychronous operation
1974 * The return value is set when the operation is complete or safe,
1975 * whichever comes first.
1977 * @pre The operation is safe or complete
1979 * @note BUG: complete callback may never be called when the safe
1980 * message is received before the complete message
1982 * @param c async operation to inspect
1983 * @returns version number of the asychronous operation's target
1985 CEPH_RADOS_API
uint64_t rados_aio_get_version(rados_completion_t c
);
1988 * Release a completion
1990 * Call this when you no longer need the completion. It may not be
1991 * freed immediately if the operation is not acked and committed.
1993 * @param c completion to release
1995 CEPH_RADOS_API
void rados_aio_release(rados_completion_t c
);
1998 * Write data to an object asynchronously
2000 * Queues the write and returns. The return value of the completion
2001 * will be 0 on success, negative error code on failure.
2003 * @param io the context in which the write will occur
2004 * @param oid name of the object
2005 * @param completion what to do when the write is safe and complete
2006 * @param buf data to write
2007 * @param len length of the data, in bytes
2008 * @param off byte offset in the object to begin writing at
2009 * @returns 0 on success, -EROFS if the io context specifies a snap_seq
2010 * other than LIBRADOS_SNAP_HEAD
2012 CEPH_RADOS_API
int rados_aio_write(rados_ioctx_t io
, const char *oid
,
2013 rados_completion_t completion
,
2014 const char *buf
, size_t len
, uint64_t off
);
2017 * Asynchronously append data to an object
2019 * Queues the append and returns.
2021 * The return value of the completion will be 0 on success, negative
2022 * error code on failure.
2024 * @param io the context to operate in
2025 * @param oid the name of the object
2026 * @param completion what to do when the append is safe and complete
2027 * @param buf the data to append
2028 * @param len length of buf (in bytes)
2029 * @returns 0 on success, -EROFS if the io context specifies a snap_seq
2030 * other than LIBRADOS_SNAP_HEAD
2032 CEPH_RADOS_API
int rados_aio_append(rados_ioctx_t io
, const char *oid
,
2033 rados_completion_t completion
,
2034 const char *buf
, size_t len
);
2037 * Asynchronously write an entire object
2039 * The object is filled with the provided data. If the object exists,
2040 * it is atomically truncated and then written.
2041 * Queues the write_full and returns.
2043 * The return value of the completion will be 0 on success, negative
2044 * error code on failure.
2046 * @param io the io context in which the write will occur
2047 * @param oid name of the object
2048 * @param completion what to do when the write_full is safe and complete
2049 * @param buf data to write
2050 * @param len length of the data, 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_write_full(rados_ioctx_t io
, const char *oid
,
2055 rados_completion_t completion
,
2056 const char *buf
, size_t len
);
2059 * Asynchronously write the same buffer multiple times
2061 * Queues the writesame and returns.
2063 * The return value of the completion will be 0 on success, negative
2064 * error code on failure.
2066 * @param io the io context in which the write will occur
2067 * @param oid name of the object
2068 * @param completion what to do when the writesame is safe and complete
2069 * @param buf data to write
2070 * @param data_len length of the data, in bytes
2071 * @param write_len the total number of bytes to write
2072 * @param off byte offset in the object to begin writing at
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_writesame(rados_ioctx_t io
, const char *oid
,
2077 rados_completion_t completion
,
2078 const char *buf
, size_t data_len
,
2079 size_t write_len
, uint64_t off
);
2082 * Asynchronously remove an object
2084 * Queues the remove and returns.
2086 * The return value of the completion will be 0 on success, negative
2087 * error code on failure.
2089 * @param io the context to operate in
2090 * @param oid the name of the object
2091 * @param completion what to do when the remove is safe and complete
2092 * @returns 0 on success, -EROFS if the io context specifies a snap_seq
2093 * other than LIBRADOS_SNAP_HEAD
2095 CEPH_RADOS_API
int rados_aio_remove(rados_ioctx_t io
, const char *oid
,
2096 rados_completion_t completion
);
2099 * Asynchronously read data from an object
2101 * The io context determines the snapshot to read from, if any was set
2102 * by rados_ioctx_snap_set_read().
2104 * The return value of the completion will be number of bytes read on
2105 * success, negative error code on failure.
2107 * @note only the 'complete' callback of the completion will be called.
2109 * @param io the context in which to perform the read
2110 * @param oid the name of the object to read from
2111 * @param completion what to do when the read is complete
2112 * @param buf where to store the results
2113 * @param len the number of bytes to read
2114 * @param off the offset to start reading from in the object
2115 * @returns 0 on success, negative error code on failure
2117 CEPH_RADOS_API
int rados_aio_read(rados_ioctx_t io
, const char *oid
,
2118 rados_completion_t completion
,
2119 char *buf
, size_t len
, uint64_t off
);
2122 * Block until all pending writes in an io context are safe
2124 * This is not equivalent to calling rados_aio_wait_for_safe() on all
2125 * write completions, since this waits for the associated callbacks to
2128 * @note BUG: always returns 0, should be void or accept a timeout
2130 * @param io the context to flush
2131 * @returns 0 on success, negative error code on failure
2133 CEPH_RADOS_API
int rados_aio_flush(rados_ioctx_t io
);
2137 * Schedule a callback for when all currently pending
2138 * aio writes are safe. This is a non-blocking version of
2139 * rados_aio_flush().
2141 * @param io the context to flush
2142 * @param completion what to do when the writes are safe
2143 * @returns 0 on success, negative error code on failure
2145 CEPH_RADOS_API
int rados_aio_flush_async(rados_ioctx_t io
,
2146 rados_completion_t completion
);
2150 * Asynchronously get object stats (size/mtime)
2153 * @param o object name
2154 * @param completion what to do when the stat is complete
2155 * @param psize where to store object size
2156 * @param pmtime where to store modification time
2157 * @returns 0 on success, negative error code on failure
2159 CEPH_RADOS_API
int rados_aio_stat(rados_ioctx_t io
, const char *o
,
2160 rados_completion_t completion
,
2161 uint64_t *psize
, time_t *pmtime
);
2164 * Asynchronously compare an on-disk object range with a buffer
2166 * @param io the context in which to perform the comparison
2167 * @param o the name of the object to compare with
2168 * @param completion what to do when the comparison is complete
2169 * @param cmp_buf buffer containing bytes to be compared with object contents
2170 * @param cmp_len length to compare and size of @c cmp_buf in bytes
2171 * @param off object byte offset at which to start the comparison
2172 * @returns 0 on success, negative error code on failure,
2173 * (-MAX_ERRNO - mismatch_off) on mismatch
2175 CEPH_RADOS_API
int rados_aio_cmpext(rados_ioctx_t io
, const char *o
,
2176 rados_completion_t completion
,
2177 const char *cmp_buf
,
2182 * Cancel async operation
2185 * @param completion completion handle
2186 * @returns 0 on success, negative error code on failure
2188 CEPH_RADOS_API
int rados_aio_cancel(rados_ioctx_t io
,
2189 rados_completion_t completion
);
2192 * Asynchronously execute an OSD class method on an object
2194 * The OSD has a plugin mechanism for performing complicated
2195 * operations on an object atomically. These plugins are called
2196 * classes. This function allows librados users to call the custom
2197 * methods. The input and output formats are defined by the class.
2198 * Classes in ceph.git can be found in src/cls subdirectories
2200 * @param io the context in which to call the method
2201 * @param o name of the object
2202 * @param completion what to do when the exec completes
2203 * @param cls the name of the class
2204 * @param method the name of the method
2205 * @param in_buf where to find input
2206 * @param in_len length of in_buf in bytes
2207 * @param buf where to store output
2208 * @param out_len length of buf in bytes
2209 * @returns 0 on success, negative error code on failure
2211 CEPH_RADOS_API
int rados_aio_exec(rados_ioctx_t io
, const char *o
,
2212 rados_completion_t completion
,
2213 const char *cls
, const char *method
,
2214 const char *in_buf
, size_t in_len
,
2215 char *buf
, size_t out_len
);
2217 /** @} Asynchronous I/O */
2220 * @name Asynchronous Xattrs
2221 * Extended attributes are stored as extended attributes on the files
2222 * representing an object on the OSDs. Thus, they have the same
2223 * limitations as the underlying filesystem. On ext4, this means that
2224 * the total data stored in xattrs cannot exceed 4KB.
2230 * Asynchronously get the value of an extended attribute on an object.
2232 * @param io the context in which the attribute is read
2233 * @param o name of the object
2234 * @param completion what to do when the getxattr completes
2235 * @param name which extended attribute to read
2236 * @param buf where to store the result
2237 * @param len size of buf in bytes
2238 * @returns length of xattr value on success, negative error code on failure
2240 CEPH_RADOS_API
int rados_aio_getxattr(rados_ioctx_t io
, const char *o
,
2241 rados_completion_t completion
,
2242 const char *name
, char *buf
, size_t len
);
2245 * Asynchronously set an extended attribute on an object.
2247 * @param io the context in which xattr is set
2248 * @param o name of the object
2249 * @param completion what to do when the setxattr completes
2250 * @param name which extended attribute to set
2251 * @param buf what to store in the xattr
2252 * @param len the number of bytes in buf
2253 * @returns 0 on success, negative error code on failure
2255 CEPH_RADOS_API
int rados_aio_setxattr(rados_ioctx_t io
, const char *o
,
2256 rados_completion_t completion
,
2257 const char *name
, const char *buf
,
2261 * Asynchronously delete an extended attribute from an object.
2263 * @param io the context in which to delete the xattr
2264 * @param o the name of the object
2265 * @param completion what to do when the rmxattr completes
2266 * @param name which xattr to delete
2267 * @returns 0 on success, negative error code on failure
2269 CEPH_RADOS_API
int rados_aio_rmxattr(rados_ioctx_t io
, const char *o
,
2270 rados_completion_t completion
,
2274 * Asynchronously start iterating over xattrs on an object.
2276 * @post iter is a valid iterator
2278 * @param io the context in which to list xattrs
2279 * @param oid name of the object
2280 * @param completion what to do when the getxattrs completes
2281 * @param iter where to store the iterator
2282 * @returns 0 on success, negative error code on failure
2284 CEPH_RADOS_API
int rados_aio_getxattrs(rados_ioctx_t io
, const char *oid
,
2285 rados_completion_t completion
,
2286 rados_xattrs_iter_t
*iter
);
2288 /** @} Asynchronous Xattrs */
2291 * @name Watch/Notify
2293 * Watch/notify is a protocol to help communicate among clients. It
2294 * can be used to sychronize client state. All that's needed is a
2295 * well-known object name (for example, rbd uses the header object of
2298 * Watchers register an interest in an object, and receive all
2299 * notifies on that object. A notify attempts to communicate with all
2300 * clients watching an object, and blocks on the notifier until each
2301 * client responds or a timeout is reached.
2303 * See rados_watch() and rados_notify() for more details.
2309 * @typedef rados_watchcb_t
2311 * Callback activated when a notify is received on a watched
2314 * @param opcode undefined
2315 * @param ver version of the watched object
2316 * @param arg application-specific data
2318 * @note BUG: opcode is an internal detail that shouldn't be exposed
2319 * @note BUG: ver is unused
2321 typedef void (*rados_watchcb_t
)(uint8_t opcode
, uint64_t ver
, void *arg
);
2324 * @typedef rados_watchcb2_t
2326 * Callback activated when a notify is received on a watched
2329 * @param arg opaque user-defined value provided to rados_watch2()
2330 * @param notify_id an id for this notify event
2331 * @param handle the watcher handle we are notifying
2332 * @param notifier_id the unique client id for the notifier
2333 * @param data payload from the notifier
2334 * @param datalen length of payload buffer
2336 typedef void (*rados_watchcb2_t
)(void *arg
,
2339 uint64_t notifier_id
,
2344 * @typedef rados_watcherrcb_t
2346 * Callback activated when we encounter an error with the watch session.
2347 * This can happen when the location of the objects moves within the
2348 * cluster and we fail to register our watch with the new object location,
2349 * or when our connection with the object OSD is otherwise interrupted and
2350 * we may have missed notify events.
2352 * @param pre opaque user-defined value provided to rados_watch2()
2353 * @param err error code
2355 typedef void (*rados_watcherrcb_t
)(void *pre
, uint64_t cookie
, int err
);
2358 * Register an interest in an object
2360 * A watch operation registers the client as being interested in
2361 * notifications on an object. OSDs keep track of watches on
2362 * persistent storage, so they are preserved across cluster changes by
2363 * the normal recovery process. If the client loses its connection to
2364 * the primary OSD for a watched object, the watch will be removed
2365 * after 30 seconds. Watches are automatically reestablished when a new
2366 * connection is made, or a placement group switches OSDs.
2368 * @note BUG: librados should provide a way for watchers to notice connection resets
2369 * @note BUG: the ver parameter does not work, and -ERANGE will never be returned
2370 * (See URL tracker.ceph.com/issues/2592)
2372 * @param io the pool the object is in
2373 * @param o the object to watch
2374 * @param ver expected version of the object
2375 * @param cookie where to store the internal id assigned to this watch
2376 * @param watchcb what to do when a notify is received on this object
2377 * @param arg application defined data to pass when watchcb is called
2378 * @returns 0 on success, negative error code on failure
2379 * @returns -ERANGE if the version of the object is greater than ver
2381 CEPH_RADOS_API
int rados_watch(rados_ioctx_t io
, const char *o
, uint64_t ver
,
2383 rados_watchcb_t watchcb
, void *arg
)
2384 __attribute__((deprecated
));
2388 * Register an interest in an object
2390 * A watch operation registers the client as being interested in
2391 * notifications on an object. OSDs keep track of watches on
2392 * persistent storage, so they are preserved across cluster changes by
2393 * the normal recovery process. If the client loses its connection to the
2394 * primary OSD for a watched object, the watch will be removed after
2395 * a timeout configured with osd_client_watch_timeout.
2396 * Watches are automatically reestablished when a new
2397 * connection is made, or a placement group switches OSDs.
2399 * @param io the pool the object is in
2400 * @param o the object to watch
2401 * @param cookie where to store the internal id assigned to this watch
2402 * @param watchcb what to do when a notify is received on this object
2403 * @param watcherrcb what to do when the watch session encounters an error
2404 * @param arg opaque value to pass to the callback
2405 * @returns 0 on success, negative error code on failure
2407 CEPH_RADOS_API
int rados_watch2(rados_ioctx_t io
, const char *o
, uint64_t *cookie
,
2408 rados_watchcb2_t watchcb
,
2409 rados_watcherrcb_t watcherrcb
,
2413 * Register an interest in an object
2415 * A watch operation registers the client as being interested in
2416 * notifications on an object. OSDs keep track of watches on
2417 * persistent storage, so they are preserved across cluster changes by
2418 * the normal recovery process. 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 timeout how many seconds the connection will keep after disconnection
2427 * @param arg opaque value to pass to the callback
2428 * @returns 0 on success, negative error code on failure
2430 CEPH_RADOS_API
int rados_watch3(rados_ioctx_t io
, const char *o
, uint64_t *cookie
,
2431 rados_watchcb2_t watchcb
,
2432 rados_watcherrcb_t watcherrcb
,
2437 * Asynchronous register an interest in an object
2439 * A watch operation registers the client as being interested in
2440 * notifications on an object. OSDs keep track of watches on
2441 * persistent storage, so they are preserved across cluster changes by
2442 * the normal recovery process. If the client loses its connection to
2443 * the primary OSD for a watched object, the watch will be removed
2444 * after 30 seconds. Watches are automatically reestablished when a new
2445 * connection is made, or a placement group switches OSDs.
2447 * @param io the pool the object is in
2448 * @param o the object to watch
2449 * @param completion what to do when operation has been attempted
2450 * @param handle where to store the internal id assigned to this watch
2451 * @param watchcb what to do when a notify is received on this object
2452 * @param watcherrcb what to do when the watch session encounters an error
2453 * @param arg opaque value to pass to the callback
2454 * @returns 0 on success, negative error code on failure
2456 CEPH_RADOS_API
int rados_aio_watch(rados_ioctx_t io
, const char *o
,
2457 rados_completion_t completion
, uint64_t *handle
,
2458 rados_watchcb2_t watchcb
,
2459 rados_watcherrcb_t watcherrcb
,
2463 * Asynchronous register an interest in an object
2465 * A watch operation registers the client as being interested in
2466 * notifications on an object. OSDs keep track of watches on
2467 * persistent storage, so they are preserved across cluster changes by
2468 * the normal recovery process. If the client loses its connection to
2469 * the primary OSD for a watched object, the watch will be removed
2470 * after the number of seconds that configured in timeout parameter.
2471 * Watches are automatically reestablished when a new
2472 * connection is made, or a placement group switches OSDs.
2474 * @param io the pool the object is in
2475 * @param o the object to watch
2476 * @param completion what to do when operation has been attempted
2477 * @param handle where to store the internal id assigned to this watch
2478 * @param watchcb what to do when a notify is received on this object
2479 * @param watcherrcb what to do when the watch session encounters an error
2480 * @param timeout how many seconds the connection will keep after disconnection
2481 * @param arg opaque value to pass to the callback
2482 * @returns 0 on success, negative error code on failure
2484 CEPH_RADOS_API
int rados_aio_watch2(rados_ioctx_t io
, const char *o
,
2485 rados_completion_t completion
, uint64_t *handle
,
2486 rados_watchcb2_t watchcb
,
2487 rados_watcherrcb_t watcherrcb
,
2492 * Check on the status of a watch
2494 * Return the number of milliseconds since the watch was last confirmed.
2495 * Or, if there has been an error, return that.
2497 * If there is an error, the watch is no longer valid, and should be
2498 * destroyed with rados_unwatch2(). The the user is still interested
2499 * in the object, a new watch should be created with rados_watch2().
2501 * @param io the pool the object is in
2502 * @param cookie the watch handle
2503 * @returns ms since last confirmed on success, negative error code on failure
2505 CEPH_RADOS_API
int rados_watch_check(rados_ioctx_t io
, uint64_t cookie
);
2508 * Unregister an interest in an object
2510 * Once this completes, no more notifies will be sent to us for this
2511 * watch. This should be called to clean up unneeded watchers.
2513 * @param io the pool the object is in
2514 * @param o the name of the watched object (ignored)
2515 * @param cookie which watch to unregister
2516 * @returns 0 on success, negative error code on failure
2518 CEPH_RADOS_API
int rados_unwatch(rados_ioctx_t io
, const char *o
, uint64_t cookie
)
2519 __attribute__((deprecated
));
2522 * Unregister an interest in an object
2524 * Once this completes, no more notifies will be sent to us for this
2525 * watch. This should be called to clean up unneeded watchers.
2527 * @param io the pool the object is in
2528 * @param cookie which watch to unregister
2529 * @returns 0 on success, negative error code on failure
2531 CEPH_RADOS_API
int rados_unwatch2(rados_ioctx_t io
, uint64_t cookie
);
2534 * Asynchronous unregister an interest in an object
2536 * Once this completes, no more notifies will be sent to us for this
2537 * watch. This should be called to clean up unneeded watchers.
2539 * @param io the pool the object is in
2540 * @param completion what to do when operation has been attempted
2541 * @param cookie which watch to unregister
2542 * @returns 0 on success, negative error code on failure
2544 CEPH_RADOS_API
int rados_aio_unwatch(rados_ioctx_t io
, uint64_t cookie
,
2545 rados_completion_t completion
);
2548 * Sychronously notify watchers of an object
2550 * This blocks until all watchers of the object have received and
2551 * reacted to the notify, or a timeout is reached.
2553 * @note BUG: the timeout is not changeable via the C API
2554 * @note BUG: the bufferlist is inaccessible in a rados_watchcb_t
2556 * @param io the pool the object is in
2557 * @param o the name of the object
2558 * @param ver obsolete - just pass zero
2559 * @param buf data to send to watchers
2560 * @param buf_len length of buf in bytes
2561 * @returns 0 on success, negative error code on failure
2563 CEPH_RADOS_API
int rados_notify(rados_ioctx_t io
, const char *o
, uint64_t ver
,
2564 const char *buf
, int buf_len
)
2565 __attribute__((deprecated
));
2568 * Sychronously notify watchers of an object
2570 * This blocks until all watchers of the object have received and
2571 * reacted to the notify, or a timeout is reached.
2573 * The reply buffer is optional. If specified, the client will get
2574 * back an encoded buffer that includes the ids of the clients that
2575 * acknowledged the notify as well as their notify ack payloads (if
2576 * any). Clients that timed out are not included. Even clients that
2577 * do not include a notify ack payload are included in the list but
2578 * have a 0-length payload associated with them. The format:
2582 * le64 gid global id for the client (for client.1234 that's 1234)
2583 * le64 cookie cookie for the client
2584 * le32 buflen length of reply message buffer
2585 * u8 * buflen payload
2589 * le64 gid global id for the client
2590 * le64 cookie cookie for the client
2593 * Note: There may be multiple instances of the same gid if there are
2594 * multiple watchers registered via the same client.
2596 * Note: The buffer must be released with rados_buffer_free() when the
2597 * user is done with it.
2599 * Note: Since the result buffer includes clients that time out, it
2600 * will be set even when rados_notify() returns an error code (like
2603 * @param io the pool the object is in
2604 * @param completion what to do when operation has been attempted
2605 * @param o the name of the object
2606 * @param buf data to send to watchers
2607 * @param buf_len length of buf in bytes
2608 * @param timeout_ms notify timeout (in ms)
2609 * @param reply_buffer pointer to reply buffer pointer (free with rados_buffer_free)
2610 * @param reply_buffer_len pointer to size of reply buffer
2611 * @returns 0 on success, negative error code on failure
2613 CEPH_RADOS_API
int rados_aio_notify(rados_ioctx_t io
, const char *o
,
2614 rados_completion_t completion
,
2615 const char *buf
, int buf_len
,
2616 uint64_t timeout_ms
, char **reply_buffer
,
2617 size_t *reply_buffer_len
);
2618 CEPH_RADOS_API
int rados_notify2(rados_ioctx_t io
, const char *o
,
2619 const char *buf
, int buf_len
,
2620 uint64_t timeout_ms
,
2621 char **reply_buffer
, size_t *reply_buffer_len
);
2624 * Acknolwedge receipt of a notify
2626 * @param io the pool the object is in
2627 * @param o the name of the object
2628 * @param notify_id the notify_id we got on the watchcb2_t callback
2629 * @param cookie the watcher handle
2630 * @param buf payload to return to notifier (optional)
2631 * @param buf_len payload length
2632 * @returns 0 on success
2634 CEPH_RADOS_API
int rados_notify_ack(rados_ioctx_t io
, const char *o
,
2635 uint64_t notify_id
, uint64_t cookie
,
2636 const char *buf
, int buf_len
);
2639 * Flush watch/notify callbacks
2641 * This call will block until all pending watch/notify callbacks have
2642 * been executed and the queue is empty. It should usually be called
2643 * after shutting down any watches before shutting down the ioctx or
2644 * librados to ensure that any callbacks do not misuse the ioctx (for
2645 * example by calling rados_notify_ack after the ioctx has been
2648 * @param cluster the cluster handle
2650 CEPH_RADOS_API
int rados_watch_flush(rados_t cluster
);
2652 * Flush watch/notify callbacks
2654 * This call will be nonblock, and the completion will be called
2655 * until all pending watch/notify callbacks have been executed and
2656 * the queue is empty. It should usually be called after shutting
2657 * down any watches before shutting down the ioctx or
2658 * librados to ensure that any callbacks do not misuse the ioctx (for
2659 * example by calling rados_notify_ack after the ioctx has been
2662 * @param cluster the cluster handle
2663 * @param completion what to do when operation has been attempted
2665 CEPH_RADOS_API
int rados_aio_watch_flush(rados_t cluster
, rados_completion_t completion
);
2667 /** @} Watch/Notify */
2670 * Pin an object in the cache tier
2672 * When an object is pinned in the cache tier, it stays in the cache
2673 * tier, and won't be flushed out.
2675 * @param io the pool the object is in
2676 * @param o the object id
2677 * @returns 0 on success, negative error code on failure
2679 CEPH_RADOS_API
int rados_cache_pin(rados_ioctx_t io
, const char *o
);
2682 * Unpin an object in the cache tier
2684 * After an object is unpinned in the cache tier, it can be flushed out
2686 * @param io the pool the object is in
2687 * @param o the object id
2688 * @returns 0 on success, negative error code on failure
2690 CEPH_RADOS_API
int rados_cache_unpin(rados_ioctx_t io
, const char *o
);
2699 * Set allocation hint for an object
2701 * This is an advisory operation, it will always succeed (as if it was
2702 * submitted with a LIBRADOS_OP_FLAG_FAILOK flag set) and is not
2703 * guaranteed to do anything on the backend.
2705 * @param io the pool the object is in
2706 * @param o the name of the object
2707 * @param expected_object_size expected size of the object, in bytes
2708 * @param expected_write_size expected size of writes to the object, in bytes
2709 * @returns 0 on success, negative error code on failure
2711 CEPH_RADOS_API
int rados_set_alloc_hint(rados_ioctx_t io
, const char *o
,
2712 uint64_t expected_object_size
,
2713 uint64_t expected_write_size
);
2716 * Set allocation hint for an object
2718 * This is an advisory operation, it will always succeed (as if it was
2719 * submitted with a LIBRADOS_OP_FLAG_FAILOK flag set) and is not
2720 * guaranteed to do anything on the backend.
2722 * @param io the pool the object is in
2723 * @param o the name of the object
2724 * @param expected_object_size expected size of the object, in bytes
2725 * @param expected_write_size expected size of writes to the object, in bytes
2726 * @param flags hints about future IO patterns
2727 * @returns 0 on success, negative error code on failure
2729 CEPH_RADOS_API
int rados_set_alloc_hint2(rados_ioctx_t io
, const char *o
,
2730 uint64_t expected_object_size
,
2731 uint64_t expected_write_size
,
2737 * @name Object Operations
2739 * A single rados operation can do multiple operations on one object
2740 * atomically. The whole operation will succeed or fail, and no partial
2741 * results will be visible.
2743 * Operations may be either reads, which can return data, or writes,
2744 * which cannot. The effects of writes are applied and visible all at
2745 * once, so an operation that sets an xattr and then checks its value
2746 * will not see the updated value.
2752 * Create a new rados_write_op_t write operation. This will store all actions
2753 * to be performed atomically. You must call rados_release_write_op when you are
2756 * @returns non-NULL on success, NULL on memory allocation error.
2758 CEPH_RADOS_API rados_write_op_t
rados_create_write_op(void);
2761 * Free a rados_write_op_t, must be called when you're done with it.
2762 * @param write_op operation to deallocate, created with rados_create_write_op
2764 CEPH_RADOS_API
void rados_release_write_op(rados_write_op_t write_op
);
2767 * Set flags for the last operation added to this write_op.
2768 * At least one op must have been added to the write_op.
2769 * @param write_op operation to add this action to
2770 * @param flags see librados.h constants beginning with LIBRADOS_OP_FLAG
2772 CEPH_RADOS_API
void rados_write_op_set_flags(rados_write_op_t write_op
,
2776 * Ensure that the object exists before writing
2777 * @param write_op operation to add this action to
2779 CEPH_RADOS_API
void rados_write_op_assert_exists(rados_write_op_t write_op
);
2782 * Ensure that the object exists and that its internal version
2783 * number is equal to "ver" before writing. "ver" should be a
2784 * version number previously obtained with rados_get_last_version().
2785 * - If the object's version is greater than the asserted version
2786 * then rados_write_op_operate will return -ERANGE instead of
2788 * - If the object's version is less than the asserted version
2789 * then rados_write_op_operate will return -EOVERFLOW instead
2790 * of executing the op.
2791 * @param write_op operation to add this action to
2792 * @param ver object version number
2794 CEPH_RADOS_API
void rados_write_op_assert_version(rados_write_op_t write_op
, uint64_t ver
);
2797 * Ensure that given object range (extent) satisfies comparison.
2799 * @param write_op operation to add this action to
2800 * @param cmp_buf buffer containing bytes to be compared with object contents
2801 * @param cmp_len length to compare and size of @c cmp_buf in bytes
2802 * @param off object byte offset at which to start the comparison
2803 * @param prval returned result of comparison, 0 on success, negative error code
2804 * on failure, (-MAX_ERRNO - mismatch_off) on mismatch
2806 CEPH_RADOS_API
void rados_write_op_cmpext(rados_write_op_t write_op
,
2807 const char *cmp_buf
,
2813 * Ensure that given xattr satisfies comparison.
2814 * If the comparison is not satisfied, the return code of the
2815 * operation will be -ECANCELED
2816 * @param write_op operation to add this action to
2817 * @param name name of the xattr to look up
2818 * @param comparison_operator currently undocumented, look for
2819 * LIBRADOS_CMPXATTR_OP_EQ in librados.h
2820 * @param value buffer to compare actual xattr value to
2821 * @param value_len length of buffer to compare actual xattr value to
2823 CEPH_RADOS_API
void rados_write_op_cmpxattr(rados_write_op_t write_op
,
2825 uint8_t comparison_operator
,
2830 * Ensure that the an omap value satisfies a comparison,
2831 * with the supplied value on the right hand side (i.e.
2832 * for OP_LT, the comparison is actual_value < value.
2834 * @param write_op operation to add this action to
2835 * @param key which omap value to compare
2836 * @param comparison_operator one of LIBRADOS_CMPXATTR_OP_EQ,
2837 LIBRADOS_CMPXATTR_OP_LT, or LIBRADOS_CMPXATTR_OP_GT
2838 * @param val value to compare with
2839 * @param val_len length of value in bytes
2840 * @param prval where to store the return value from this action
2842 CEPH_RADOS_API
void rados_write_op_omap_cmp(rados_write_op_t write_op
,
2844 uint8_t comparison_operator
,
2850 * Ensure that the an omap value satisfies a comparison,
2851 * with the supplied value on the right hand side (i.e.
2852 * for OP_LT, the comparison is actual_value < value.
2854 * @param write_op operation to add this action to
2855 * @param key which omap value to compare
2856 * @param comparison_operator one of LIBRADOS_CMPXATTR_OP_EQ,
2857 LIBRADOS_CMPXATTR_OP_LT, or LIBRADOS_CMPXATTR_OP_GT
2858 * @param val value to compare with
2859 * @param key_len length of key in bytes
2860 * @param val_len length of value in bytes
2861 * @param prval where to store the return value from this action
2863 CEPH_RADOS_API
void rados_write_op_omap_cmp2(rados_write_op_t write_op
,
2865 uint8_t comparison_operator
,
2873 * @param write_op operation to add this action to
2874 * @param name name of the xattr
2875 * @param value buffer to set xattr to
2876 * @param value_len length of buffer to set xattr to
2878 CEPH_RADOS_API
void rados_write_op_setxattr(rados_write_op_t write_op
,
2885 * @param write_op operation to add this action to
2886 * @param name name of the xattr to remove
2888 CEPH_RADOS_API
void rados_write_op_rmxattr(rados_write_op_t write_op
,
2893 * @param write_op operation to add this action to
2894 * @param exclusive set to either LIBRADOS_CREATE_EXCLUSIVE or
2895 LIBRADOS_CREATE_IDEMPOTENT
2896 * will error if the object already exists.
2897 * @param category category string (DEPRECATED, HAS NO EFFECT)
2899 CEPH_RADOS_API
void rados_write_op_create(rados_write_op_t write_op
,
2901 const char* category
);
2905 * @param write_op operation to add this action to
2906 * @param offset offset to write to
2907 * @param buffer bytes to write
2908 * @param len length of buffer
2910 CEPH_RADOS_API
void rados_write_op_write(rados_write_op_t write_op
,
2916 * Write whole object, atomically replacing it.
2917 * @param write_op operation to add this action to
2918 * @param buffer bytes to write
2919 * @param len length of buffer
2921 CEPH_RADOS_API
void rados_write_op_write_full(rados_write_op_t write_op
,
2926 * Write the same buffer multiple times
2927 * @param write_op operation to add this action to
2928 * @param buffer bytes to write
2929 * @param data_len length of buffer
2930 * @param write_len total number of bytes to write, as a multiple of @c data_len
2931 * @param offset offset to write to
2933 CEPH_RADOS_API
void rados_write_op_writesame(rados_write_op_t write_op
,
2940 * Append to end of object.
2941 * @param write_op operation to add this action to
2942 * @param buffer bytes to write
2943 * @param len length of buffer
2945 CEPH_RADOS_API
void rados_write_op_append(rados_write_op_t write_op
,
2950 * @param write_op operation to add this action to
2952 CEPH_RADOS_API
void rados_write_op_remove(rados_write_op_t write_op
);
2955 * Truncate an object
2956 * @param write_op operation to add this action to
2957 * @param offset Offset to truncate to
2959 CEPH_RADOS_API
void rados_write_op_truncate(rados_write_op_t write_op
,
2963 * Zero part of an object
2964 * @param write_op operation to add this action to
2965 * @param offset Offset to zero
2966 * @param len length to zero
2968 CEPH_RADOS_API
void rados_write_op_zero(rados_write_op_t write_op
,
2973 * Execute an OSD class method on an object
2974 * See rados_exec() for general description.
2976 * @param write_op operation to add this action to
2977 * @param cls the name of the class
2978 * @param method the name of the method
2979 * @param in_buf where to find input
2980 * @param in_len length of in_buf in bytes
2981 * @param prval where to store the return value from the method
2983 CEPH_RADOS_API
void rados_write_op_exec(rados_write_op_t write_op
,
2991 * Set key/value pairs on an object
2993 * @param write_op operation to add this action to
2994 * @param keys array of null-terminated char arrays representing keys to set
2995 * @param vals array of pointers to values to set
2996 * @param lens array of lengths corresponding to each value
2997 * @param num number of key/value pairs to set
2999 CEPH_RADOS_API
void rados_write_op_omap_set(rados_write_op_t write_op
,
3000 char const* const* keys
,
3001 char const* const* vals
,
3006 * Set key/value pairs on an object
3008 * @param write_op operation to add this action to
3009 * @param keys array of null-terminated char arrays representing keys to set
3010 * @param vals array of pointers to values to set
3011 * @param key_lens array of lengths corresponding to each key
3012 * @param val_lens array of lengths corresponding to each value
3013 * @param num number of key/value pairs to set
3015 CEPH_RADOS_API
void rados_write_op_omap_set2(rados_write_op_t write_op
,
3016 char const* const* keys
,
3017 char const* const* vals
,
3018 const size_t *key_lens
,
3019 const size_t *val_lens
,
3023 * Remove key/value pairs from an object
3025 * @param write_op operation to add this action to
3026 * @param keys array of null-terminated char arrays representing keys to remove
3027 * @param keys_len number of key/value pairs to remove
3029 CEPH_RADOS_API
void rados_write_op_omap_rm_keys(rados_write_op_t write_op
,
3030 char const* const* keys
,
3034 * Remove key/value pairs from an object
3036 * @param write_op operation to add this action to
3037 * @param keys array of char arrays representing keys to remove
3038 * @param key_lens array of size_t values representing length of each key
3039 * @param keys_len number of key/value pairs to remove
3041 CEPH_RADOS_API
void rados_write_op_omap_rm_keys2(rados_write_op_t write_op
,
3042 char const* const* keys
,
3043 const size_t* key_lens
,
3047 * Remove all key/value pairs from an object
3049 * @param write_op operation to add this action to
3051 CEPH_RADOS_API
void rados_write_op_omap_clear(rados_write_op_t write_op
);
3054 * Set allocation hint for an object
3056 * @param write_op operation to add this action to
3057 * @param expected_object_size expected size of the object, in bytes
3058 * @param expected_write_size expected size of writes to the object, in bytes
3060 CEPH_RADOS_API
void rados_write_op_set_alloc_hint(rados_write_op_t write_op
,
3061 uint64_t expected_object_size
,
3062 uint64_t expected_write_size
);
3065 * Set allocation hint for an object
3067 * @param write_op operation to add this action to
3068 * @param expected_object_size expected size of the object, in bytes
3069 * @param expected_write_size expected size of writes to the object, in bytes
3070 * @param flags hints about future IO patterns
3072 CEPH_RADOS_API
void rados_write_op_set_alloc_hint2(rados_write_op_t write_op
,
3073 uint64_t expected_object_size
,
3074 uint64_t expected_write_size
,
3078 * Perform a write operation synchronously
3079 * @param write_op operation to perform
3080 * @param io the ioctx that the object is in
3081 * @param oid the object id
3082 * @param mtime the time to set the mtime to, NULL for the current time
3083 * @param flags flags to apply to the entire operation (LIBRADOS_OPERATION_*)
3085 CEPH_RADOS_API
int rados_write_op_operate(rados_write_op_t write_op
,
3091 * Perform a write operation synchronously
3092 * @param write_op operation to perform
3093 * @param io the ioctx that the object is in
3094 * @param oid the object id
3095 * @param mtime the time to set the mtime to, NULL for the current time
3096 * @param flags flags to apply to the entire operation (LIBRADOS_OPERATION_*)
3099 CEPH_RADOS_API
int rados_write_op_operate2(rados_write_op_t write_op
,
3102 struct timespec
*mtime
,
3106 * Perform a write operation asynchronously
3107 * @param write_op operation to perform
3108 * @param io the ioctx that the object is in
3109 * @param completion what to do when operation has been attempted
3110 * @param oid the object id
3111 * @param mtime the time to set the mtime to, NULL for the current time
3112 * @param flags flags to apply to the entire operation (LIBRADOS_OPERATION_*)
3114 CEPH_RADOS_API
int rados_aio_write_op_operate(rados_write_op_t write_op
,
3116 rados_completion_t completion
,
3122 * Create a new rados_read_op_t write operation. This will store all
3123 * actions to be performed atomically. You must call
3124 * rados_release_read_op when you are finished with it (after it
3125 * completes, or you decide not to send it in the first place).
3127 * @returns non-NULL on success, NULL on memory allocation error.
3129 CEPH_RADOS_API rados_read_op_t
rados_create_read_op(void);
3132 * Free a rados_read_op_t, must be called when you're done with it.
3133 * @param read_op operation to deallocate, created with rados_create_read_op
3135 CEPH_RADOS_API
void rados_release_read_op(rados_read_op_t read_op
);
3138 * Set flags for the last operation added to this read_op.
3139 * At least one op must have been added to the read_op.
3140 * @param read_op operation to add this action to
3141 * @param flags see librados.h constants beginning with LIBRADOS_OP_FLAG
3143 CEPH_RADOS_API
void rados_read_op_set_flags(rados_read_op_t read_op
, int flags
);
3146 * Ensure that the object exists before reading
3147 * @param read_op operation to add this action to
3149 CEPH_RADOS_API
void rados_read_op_assert_exists(rados_read_op_t read_op
);
3152 * Ensure that the object exists and that its internal version
3153 * number is equal to "ver" before reading. "ver" should be a
3154 * version number previously obtained with rados_get_last_version().
3155 * - If the object's version is greater than the asserted version
3156 * then rados_read_op_operate will return -ERANGE instead of
3158 * - If the object's version is less than the asserted version
3159 * then rados_read_op_operate will return -EOVERFLOW instead
3160 * of executing the op.
3161 * @param read_op operation to add this action to
3162 * @param ver object version number
3164 CEPH_RADOS_API
void rados_read_op_assert_version(rados_read_op_t read_op
, uint64_t ver
);
3167 * Ensure that given object range (extent) satisfies comparison.
3169 * @param read_op operation to add this action to
3170 * @param cmp_buf buffer containing bytes to be compared with object contents
3171 * @param cmp_len length to compare and size of @c cmp_buf in bytes
3172 * @param off object byte offset at which to start the comparison
3173 * @param prval returned result of comparison, 0 on success, negative error code
3174 * on failure, (-MAX_ERRNO - mismatch_off) on mismatch
3176 CEPH_RADOS_API
void rados_read_op_cmpext(rados_read_op_t read_op
,
3177 const char *cmp_buf
,
3183 * Ensure that the an xattr satisfies a comparison
3184 * If the comparison is not satisfied, the return code of the
3185 * operation will be -ECANCELED
3186 * @param read_op operation to add this action to
3187 * @param name name of the xattr to look up
3188 * @param comparison_operator currently undocumented, look for
3189 * LIBRADOS_CMPXATTR_OP_EQ in librados.h
3190 * @param value buffer to compare actual xattr value to
3191 * @param value_len length of buffer to compare actual xattr value to
3193 CEPH_RADOS_API
void rados_read_op_cmpxattr(rados_read_op_t read_op
,
3195 uint8_t comparison_operator
,
3200 * Start iterating over xattrs on an object.
3202 * @param read_op operation to add this action to
3203 * @param iter where to store the iterator
3204 * @param prval where to store the return value of this action
3206 CEPH_RADOS_API
void rados_read_op_getxattrs(rados_read_op_t read_op
,
3207 rados_xattrs_iter_t
*iter
,
3211 * Ensure that the an omap value satisfies a comparison,
3212 * with the supplied value on the right hand side (i.e.
3213 * for OP_LT, the comparison is actual_value < value.
3215 * @param read_op operation to add this action to
3216 * @param key which omap value to compare
3217 * @param comparison_operator one of LIBRADOS_CMPXATTR_OP_EQ,
3218 LIBRADOS_CMPXATTR_OP_LT, or LIBRADOS_CMPXATTR_OP_GT
3219 * @param val value to compare with
3220 * @param val_len length of value in bytes
3221 * @param prval where to store the return value from this action
3223 CEPH_RADOS_API
void rados_read_op_omap_cmp(rados_read_op_t read_op
,
3225 uint8_t comparison_operator
,
3231 * Ensure that the an omap value satisfies a comparison,
3232 * with the supplied value on the right hand side (i.e.
3233 * for OP_LT, the comparison is actual_value < value.
3235 * @param read_op operation to add this action to
3236 * @param key which omap value to compare
3237 * @param comparison_operator one of LIBRADOS_CMPXATTR_OP_EQ,
3238 LIBRADOS_CMPXATTR_OP_LT, or LIBRADOS_CMPXATTR_OP_GT
3239 * @param val value to compare with
3240 * @param key_len length of key in bytes
3241 * @param val_len length of value in bytes
3242 * @param prval where to store the return value from this action
3244 CEPH_RADOS_API
void rados_read_op_omap_cmp2(rados_read_op_t read_op
,
3246 uint8_t comparison_operator
,
3253 * Get object size and mtime
3254 * @param read_op operation to add this action to
3255 * @param psize where to store object size
3256 * @param pmtime where to store modification time
3257 * @param prval where to store the return value of this action
3259 CEPH_RADOS_API
void rados_read_op_stat(rados_read_op_t read_op
,
3265 * Read bytes from offset into buffer.
3267 * prlen will be filled with the number of bytes read if successful.
3268 * A short read can only occur if the read reaches the end of the
3271 * @param read_op operation to add this action to
3272 * @param offset offset to read from
3273 * @param len length of buffer
3274 * @param buffer where to put the data
3275 * @param bytes_read where to store the number of bytes read by this action
3276 * @param prval where to store the return value of this action
3278 CEPH_RADOS_API
void rados_read_op_read(rados_read_op_t read_op
,
3286 * Compute checksum from object data
3288 * @param read_op operation to add this action to
3289 * @param type the checksum algorithm to utilize
3290 * @param init_value the init value for the algorithm
3291 * @param init_value_len the length of the init value
3292 * @param offset the offset to start checksumming in the object
3293 * @param len the number of bytes to checksum
3294 * @param chunk_size optional length-aligned chunk size for checksums
3295 * @param pchecksum where to store the checksum result for this action
3296 * @param checksum_len the number of bytes available for the result
3297 * @param prval where to store the return value for this action
3299 CEPH_RADOS_API
void rados_read_op_checksum(rados_read_op_t read_op
,
3300 rados_checksum_type_t type
,
3301 const char *init_value
,
3302 size_t init_value_len
,
3303 uint64_t offset
, size_t len
,
3304 size_t chunk_size
, char *pchecksum
,
3305 size_t checksum_len
, int *prval
);
3308 * Execute an OSD class method on an object
3309 * See rados_exec() for general description.
3311 * The output buffer is allocated on the heap; the caller is
3312 * expected to release that memory with rados_buffer_free(). The
3313 * buffer and length pointers can all be NULL, in which case they are
3316 * @param read_op operation to add this action to
3317 * @param cls the name of the class
3318 * @param method the name of the method
3319 * @param in_buf where to find input
3320 * @param in_len length of in_buf in bytes
3321 * @param out_buf where to put librados-allocated output buffer
3322 * @param out_len length of out_buf in bytes
3323 * @param prval where to store the return value from the method
3325 CEPH_RADOS_API
void rados_read_op_exec(rados_read_op_t read_op
,
3335 * Execute an OSD class method on an object
3336 * See rados_exec() for general description.
3338 * If the output buffer is too small, prval will
3339 * be set to -ERANGE and used_len will be 0.
3341 * @param read_op operation to add this action to
3342 * @param cls the name of the class
3343 * @param method the name of the method
3344 * @param in_buf where to find input
3345 * @param in_len length of in_buf in bytes
3346 * @param out_buf user-provided buffer to read into
3347 * @param out_len length of out_buf in bytes
3348 * @param used_len where to store the number of bytes read into out_buf
3349 * @param prval where to store the return value from the method
3351 CEPH_RADOS_API
void rados_read_op_exec_user_buf(rados_read_op_t read_op
,
3362 * Start iterating over key/value pairs on an object.
3364 * They will be returned sorted by key.
3366 * @param read_op operation to add this action to
3367 * @param start_after list keys starting after start_after
3368 * @param filter_prefix list only keys beginning with filter_prefix
3369 * @param max_return list no more than max_return key/value pairs
3370 * @param iter where to store the iterator
3371 * @param prval where to store the return value from this action
3373 CEPH_RADOS_API
void rados_read_op_omap_get_vals(rados_read_op_t read_op
,
3374 const char *start_after
,
3375 const char *filter_prefix
,
3376 uint64_t max_return
,
3377 rados_omap_iter_t
*iter
,
3379 __attribute__((deprecated
)); /* use v2 below */
3382 * Start iterating over key/value pairs on an object.
3384 * They will be returned sorted by key.
3386 * @param read_op operation to add this action to
3387 * @param start_after list keys starting after start_after
3388 * @param filter_prefix list only keys beginning with filter_prefix
3389 * @param max_return list no more than max_return key/value pairs
3390 * @param iter where to store the iterator
3391 * @param pmore flag indicating whether there are more keys to fetch
3392 * @param prval where to store the return value from this action
3394 CEPH_RADOS_API
void rados_read_op_omap_get_vals2(rados_read_op_t read_op
,
3395 const char *start_after
,
3396 const char *filter_prefix
,
3397 uint64_t max_return
,
3398 rados_omap_iter_t
*iter
,
3399 unsigned char *pmore
,
3403 * Start iterating over keys on an object.
3405 * They will be returned sorted by key, and the iterator
3406 * will fill in NULL for all values if specified.
3408 * @param read_op operation to add this action to
3409 * @param start_after list keys starting after start_after
3410 * @param max_return list no more than max_return keys
3411 * @param iter where to store the iterator
3412 * @param prval where to store the return value from this action
3414 CEPH_RADOS_API
void rados_read_op_omap_get_keys(rados_read_op_t read_op
,
3415 const char *start_after
,
3416 uint64_t max_return
,
3417 rados_omap_iter_t
*iter
,
3419 __attribute__((deprecated
)); /* use v2 below */
3422 * Start iterating over keys on an object.
3424 * They will be returned sorted by key, and the iterator
3425 * will fill in NULL for all values if specified.
3427 * @param read_op operation to add this action to
3428 * @param start_after list keys starting after start_after
3429 * @param max_return list no more than max_return keys
3430 * @param iter where to store the iterator
3431 * @param pmore flag indicating whether there are more keys to fetch
3432 * @param prval where to store the return value from this action
3434 CEPH_RADOS_API
void rados_read_op_omap_get_keys2(rados_read_op_t read_op
,
3435 const char *start_after
,
3436 uint64_t max_return
,
3437 rados_omap_iter_t
*iter
,
3438 unsigned char *pmore
,
3442 * Start iterating over specific key/value pairs
3444 * They will be returned sorted by key.
3446 * @param read_op operation to add this action to
3447 * @param keys array of pointers to null-terminated keys to get
3448 * @param keys_len the number of strings in keys
3449 * @param iter where to store the iterator
3450 * @param prval where to store the return value from this action
3452 CEPH_RADOS_API
void rados_read_op_omap_get_vals_by_keys(rados_read_op_t read_op
,
3453 char const* const* keys
,
3455 rados_omap_iter_t
*iter
,
3459 * Start iterating over specific key/value pairs
3461 * They will be returned sorted by key.
3463 * @param read_op operation to add this action to
3464 * @param keys array of pointers to keys to get
3465 * @param num_keys the number of strings in keys
3466 * @param key_lens array of size_t's describing each key len (in bytes)
3467 * @param iter where to store the iterator
3468 * @param prval where to store the return value from this action
3470 CEPH_RADOS_API
void rados_read_op_omap_get_vals_by_keys2(rados_read_op_t read_op
,
3471 char const* const* keys
,
3473 const size_t* key_lens
,
3474 rados_omap_iter_t
*iter
,
3478 * Perform a read operation synchronously
3479 * @param read_op operation to perform
3480 * @param io the ioctx that the object is in
3481 * @param oid the object id
3482 * @param flags flags to apply to the entire operation (LIBRADOS_OPERATION_*)
3484 CEPH_RADOS_API
int rados_read_op_operate(rados_read_op_t read_op
,
3490 * Perform a read operation asynchronously
3491 * @param read_op operation to perform
3492 * @param io the ioctx that the object is in
3493 * @param completion what to do when operation has been attempted
3494 * @param oid the object id
3495 * @param flags flags to apply to the entire operation (LIBRADOS_OPERATION_*)
3497 CEPH_RADOS_API
int rados_aio_read_op_operate(rados_read_op_t read_op
,
3499 rados_completion_t completion
,
3503 /** @} Object Operations */
3506 * Take an exclusive lock on an object.
3508 * @param io the context to operate in
3509 * @param oid the name of the object
3510 * @param name the name of the lock
3511 * @param cookie user-defined identifier for this instance of the lock
3512 * @param desc user-defined lock description
3513 * @param duration the duration of the lock. Set to NULL for infinite duration.
3514 * @param flags lock flags
3515 * @returns 0 on success, negative error code on failure
3516 * @returns -EBUSY if the lock is already held by another (client, cookie) pair
3517 * @returns -EEXIST if the lock is already held by the same (client, cookie) pair
3519 CEPH_RADOS_API
int rados_lock_exclusive(rados_ioctx_t io
, const char * oid
,
3520 const char * name
, const char * cookie
,
3522 struct timeval
* duration
,
3526 * Take a shared lock on an object.
3528 * @param io the context to operate in
3529 * @param o the name of the object
3530 * @param name the name of the lock
3531 * @param cookie user-defined identifier for this instance of the lock
3532 * @param tag The tag of the lock
3533 * @param desc user-defined lock description
3534 * @param duration the duration of the lock. Set to NULL for infinite duration.
3535 * @param flags lock flags
3536 * @returns 0 on success, negative error code on failure
3537 * @returns -EBUSY if the lock is already held by another (client, cookie) pair
3538 * @returns -EEXIST if the lock is already held by the same (client, cookie) pair
3540 CEPH_RADOS_API
int rados_lock_shared(rados_ioctx_t io
, const char * o
,
3541 const char * name
, const char * cookie
,
3542 const char * tag
, const char * desc
,
3543 struct timeval
* duration
, uint8_t flags
);
3546 * Release a shared or exclusive lock on an object.
3548 * @param io the context to operate in
3549 * @param o the name of the object
3550 * @param name the name of the lock
3551 * @param cookie user-defined identifier for the instance of the lock
3552 * @returns 0 on success, negative error code on failure
3553 * @returns -ENOENT if the lock is not held by the specified (client, cookie) pair
3555 CEPH_RADOS_API
int rados_unlock(rados_ioctx_t io
, const char *o
,
3556 const char *name
, const char *cookie
);
3559 * Asynchronous release a shared or exclusive lock on an object.
3561 * @param io the context to operate in
3562 * @param o the name of the object
3563 * @param name the name of the lock
3564 * @param cookie user-defined identifier for the instance of the lock
3565 * @param completion what to do when operation has been attempted
3566 * @returns 0 on success, negative error code on failure
3568 CEPH_RADOS_API
int rados_aio_unlock(rados_ioctx_t io
, const char *o
,
3569 const char *name
, const char *cookie
,
3570 rados_completion_t completion
);
3573 * List clients that have locked the named object lock and information about
3576 * The number of bytes required in each buffer is put in the
3577 * corresponding size out parameter. If any of the provided buffers
3578 * are too short, -ERANGE is returned after these sizes are filled in.
3580 * @param io the context to operate in
3581 * @param o the name of the object
3582 * @param name the name of the lock
3583 * @param exclusive where to store whether the lock is exclusive (1) or shared (0)
3584 * @param tag where to store the tag associated with the object lock
3585 * @param tag_len number of bytes in tag buffer
3586 * @param clients buffer in which locker clients are stored, separated by '\0'
3587 * @param clients_len number of bytes in the clients buffer
3588 * @param cookies buffer in which locker cookies are stored, separated by '\0'
3589 * @param cookies_len number of bytes in the cookies buffer
3590 * @param addrs buffer in which locker addresses are stored, separated by '\0'
3591 * @param addrs_len number of bytes in the clients buffer
3592 * @returns number of lockers on success, negative error code on failure
3593 * @returns -ERANGE if any of the buffers are too short
3595 CEPH_RADOS_API ssize_t
rados_list_lockers(rados_ioctx_t io
, const char *o
,
3596 const char *name
, int *exclusive
,
3597 char *tag
, size_t *tag_len
,
3598 char *clients
, size_t *clients_len
,
3599 char *cookies
, size_t *cookies_len
,
3600 char *addrs
, size_t *addrs_len
);
3603 * Releases a shared or exclusive lock on an object, which was taken by the
3606 * @param io the context to operate in
3607 * @param o the name of the object
3608 * @param name the name of the lock
3609 * @param client the client currently holding the lock
3610 * @param cookie user-defined identifier for the instance of the lock
3611 * @returns 0 on success, negative error code on failure
3612 * @returns -ENOENT if the lock is not held by the specified (client, cookie) pair
3613 * @returns -EINVAL if the client cannot be parsed
3615 CEPH_RADOS_API
int rados_break_lock(rados_ioctx_t io
, const char *o
,
3616 const char *name
, const char *client
,
3617 const char *cookie
);
3620 * Blacklists the specified client from the OSDs
3622 * @param cluster cluster handle
3623 * @param client_address client address
3624 * @param expire_seconds number of seconds to blacklist (0 for default)
3625 * @returns 0 on success, negative error code on failure
3627 CEPH_RADOS_API
int rados_blacklist_add(rados_t cluster
,
3628 char *client_address
,
3629 uint32_t expire_seconds
);
3631 CEPH_RADOS_API
void rados_set_osdmap_full_try(rados_ioctx_t io
);
3633 CEPH_RADOS_API
void rados_unset_osdmap_full_try(rados_ioctx_t io
);
3636 * Enable an application on a pool
3638 * @param io pool ioctx
3639 * @param app_name application name
3640 * @param force 0 if only single application per pool
3641 * @returns 0 on success, negative error code on failure
3643 CEPH_RADOS_API
int rados_application_enable(rados_ioctx_t io
,
3644 const char *app_name
, int force
);
3647 * List all enabled applications
3649 * If the provided buffer is too short, the required length is filled in and
3650 * -ERANGE is returned. Otherwise, the buffers are filled with the application
3651 * names, with a '\0' after each.
3653 * @param io pool ioctx
3654 * @param values buffer in which to store application names
3655 * @param values_len number of bytes in values buffer
3656 * @returns 0 on success, negative error code on failure
3657 * @returns -ERANGE if either buffer is too short
3659 CEPH_RADOS_API
int rados_application_list(rados_ioctx_t io
, char *values
,
3660 size_t *values_len
);
3663 * Get application metadata value from pool
3665 * @param io pool ioctx
3666 * @param app_name application name
3667 * @param key metadata key
3668 * @param value result buffer
3669 * @param value_len maximum len of value
3670 * @returns 0 on success, negative error code on failure
3672 CEPH_RADOS_API
int rados_application_metadata_get(rados_ioctx_t io
,
3673 const char *app_name
,
3674 const char *key
, char *value
,
3678 * Set application metadata on a pool
3680 * @param io pool ioctx
3681 * @param app_name application name
3682 * @param key metadata key
3683 * @param value metadata key
3684 * @returns 0 on success, negative error code on failure
3686 CEPH_RADOS_API
int rados_application_metadata_set(rados_ioctx_t io
,
3687 const char *app_name
,
3692 * Remove application metadata from a pool
3694 * @param io pool ioctx
3695 * @param app_name application name
3696 * @param key metadata key
3697 * @returns 0 on success, negative error code on failure
3699 CEPH_RADOS_API
int rados_application_metadata_remove(rados_ioctx_t io
,
3700 const char *app_name
,
3704 * List all metadata key/value pairs associated with an application.
3706 * This iterates over all metadata, key_len and val_len are filled in
3707 * with the number of bytes put into the keys and values buffers.
3709 * If the provided buffers are too short, the required lengths are filled
3710 * in and -ERANGE is returned. Otherwise, the buffers are filled with
3711 * the keys and values of the metadata, with a '\0' after each.
3713 * @param io pool ioctx
3714 * @param app_name application name
3715 * @param keys buffer in which to store key names
3716 * @param key_len number of bytes in keys buffer
3717 * @param values buffer in which to store values
3718 * @param vals_len number of bytes in values buffer
3719 * @returns 0 on success, negative error code on failure
3720 * @returns -ERANGE if either buffer is too short
3722 CEPH_RADOS_API
int rados_application_metadata_list(rados_ioctx_t io
,
3723 const char *app_name
,
3724 char *keys
, size_t *key_len
,
3729 * @name Mon/OSD/PG Commands
3731 * These interfaces send commands relating to the monitor, OSD, or PGs.
3737 * Send monitor command.
3739 * @note Takes command string in carefully-formatted JSON; must match
3740 * defined commands, types, etc.
3742 * The result buffers are allocated on the heap; the caller is
3743 * expected to release that memory with rados_buffer_free(). The
3744 * buffer and length pointers can all be NULL, in which case they are
3747 * @param cluster cluster handle
3748 * @param cmd an array of char *'s representing the command
3749 * @param cmdlen count of valid entries in cmd
3750 * @param inbuf any bulk input data (crush map, etc.)
3751 * @param inbuflen input buffer length
3752 * @param outbuf double pointer to output buffer
3753 * @param outbuflen pointer to output buffer length
3754 * @param outs double pointer to status string
3755 * @param outslen pointer to status string length
3756 * @returns 0 on success, negative error code on failure
3758 CEPH_RADOS_API
int rados_mon_command(rados_t cluster
, const char **cmd
,
3759 size_t cmdlen
, const char *inbuf
,
3760 size_t inbuflen
, char **outbuf
,
3761 size_t *outbuflen
, char **outs
,
3765 * Send ceph-mgr command.
3767 * @note Takes command string in carefully-formatted JSON; must match
3768 * defined commands, types, etc.
3770 * The result buffers are allocated on the heap; the caller is
3771 * expected to release that memory with rados_buffer_free(). The
3772 * buffer and length pointers can all be NULL, in which case they are
3775 * @param cluster cluster handle
3776 * @param cmd an array of char *'s representing the command
3777 * @param cmdlen count of valid entries in cmd
3778 * @param inbuf any bulk input data (crush map, etc.)
3779 * @param inbuflen input buffer length
3780 * @param outbuf double pointer to output buffer
3781 * @param outbuflen pointer to output buffer length
3782 * @param outs double pointer to status string
3783 * @param outslen pointer to status string length
3784 * @returns 0 on success, negative error code on failure
3786 CEPH_RADOS_API
int rados_mgr_command(rados_t cluster
, const char **cmd
,
3787 size_t cmdlen
, const char *inbuf
,
3788 size_t inbuflen
, char **outbuf
,
3789 size_t *outbuflen
, char **outs
,
3793 * Send monitor command to a specific monitor.
3795 * @note Takes command string in carefully-formatted JSON; must match
3796 * defined commands, types, etc.
3798 * The result buffers are allocated on the heap; the caller is
3799 * expected to release that memory with rados_buffer_free(). The
3800 * buffer and length pointers can all be NULL, in which case they are
3803 * @param cluster cluster handle
3804 * @param name target monitor's name
3805 * @param cmd an array of char *'s representing the command
3806 * @param cmdlen count of valid entries in cmd
3807 * @param inbuf any bulk input data (crush map, etc.)
3808 * @param inbuflen input buffer length
3809 * @param outbuf double pointer to output buffer
3810 * @param outbuflen pointer to output buffer length
3811 * @param outs double pointer to status string
3812 * @param outslen pointer to status string length
3813 * @returns 0 on success, negative error code on failure
3815 CEPH_RADOS_API
int rados_mon_command_target(rados_t cluster
, const char *name
,
3816 const char **cmd
, size_t cmdlen
,
3817 const char *inbuf
, size_t inbuflen
,
3818 char **outbuf
, size_t *outbuflen
,
3819 char **outs
, size_t *outslen
);
3822 * free a rados-allocated buffer
3824 * Release memory allocated by librados calls like rados_mon_command().
3826 * @param buf buffer pointer
3828 CEPH_RADOS_API
void rados_buffer_free(char *buf
);
3830 CEPH_RADOS_API
int rados_osd_command(rados_t cluster
, int osdid
,
3831 const char **cmd
, size_t cmdlen
,
3832 const char *inbuf
, size_t inbuflen
,
3833 char **outbuf
, size_t *outbuflen
,
3834 char **outs
, size_t *outslen
);
3836 CEPH_RADOS_API
int rados_pg_command(rados_t cluster
, const char *pgstr
,
3837 const char **cmd
, size_t cmdlen
,
3838 const char *inbuf
, size_t inbuflen
,
3839 char **outbuf
, size_t *outbuflen
,
3840 char **outs
, size_t *outslen
);
3842 CEPH_RADOS_API
int rados_mgr_command(rados_t cluster
,
3843 const char **cmd
, size_t cmdlen
,
3844 const char *inbuf
, size_t inbuflen
,
3845 char **outbuf
, size_t *outbuflen
,
3846 char **outs
, size_t *outslen
);
3849 * This is not a doxygen comment leadin, because doxygen breaks on
3850 * a typedef with function params and returns, and I can't figure out
3853 * Monitor cluster log
3855 * Monitor events logged to the cluster log. The callback get each
3856 * log entry both as a single formatted line and with each field in a
3859 * Calling with a cb argument of NULL will deregister any previously
3860 * registered callback.
3862 * @param cluster cluster handle
3863 * @param level minimum log level (debug, info, warn|warning, err|error)
3864 * @param cb callback to run for each log message. It MUST NOT block
3865 * nor call back into librados.
3866 * @param arg void argument to pass to cb
3868 * @returns 0 on success, negative code on error
3870 typedef void (*rados_log_callback_t
)(void *arg
,
3873 uint64_t sec
, uint64_t nsec
,
3874 uint64_t seq
, const char *level
,
3878 * This is not a doxygen comment leadin, because doxygen breaks on
3879 * a typedef with function params and returns, and I can't figure out
3882 * Monitor cluster log
3884 * Monitor events logged to the cluster log. The callback get each
3885 * log entry both as a single formatted line and with each field in a
3888 * Calling with a cb argument of NULL will deregister any previously
3889 * registered callback.
3891 * @param cluster cluster handle
3892 * @param level minimum log level (debug, info, warn|warning, err|error)
3893 * @param cb callback to run for each log message. It MUST NOT block
3894 * nor call back into librados.
3895 * @param arg void argument to pass to cb
3897 * @returns 0 on success, negative code on error
3899 typedef void (*rados_log_callback2_t
)(void *arg
,
3901 const char *channel
,
3904 uint64_t sec
, uint64_t nsec
,
3905 uint64_t seq
, const char *level
,
3908 CEPH_RADOS_API
int rados_monitor_log(rados_t cluster
, const char *level
,
3909 rados_log_callback_t cb
, void *arg
);
3910 CEPH_RADOS_API
int rados_monitor_log2(rados_t cluster
, const char *level
,
3911 rados_log_callback2_t cb
, void *arg
);
3915 * register daemon instance for a service
3917 * Register us as a daemon providing a particular service. We identify
3918 * the service (e.g., 'rgw') and our instance name (e.g., 'rgw.$hostname').
3919 * The metadata is a map of keys and values with arbitrary static metdata
3920 * for this instance. The encoding is a series of NULL-terminated strings,
3921 * alternating key names and values, terminating with an empty key name.
3922 * For example, "foo\0bar\0this\0that\0\0" is the dict {foo=bar,this=that}.
3924 * For the lifetime of the librados instance, regular beacons will be sent
3925 * to the cluster to maintain our registration in the service map.
3927 * @param cluster handle
3928 * @param service service name
3929 * @param daemon daemon instance name
3930 * @param metadata_dict static daemon metadata dict
3932 CEPH_RADOS_API
int rados_service_register(
3934 const char *service
,
3936 const char *metadata_dict
);
3939 * update daemon status
3941 * Update our mutable status information in the service map.
3943 * The status dict is encoded the same way the daemon metadata is encoded
3944 * for rados_service_register. For example, "foo\0bar\0this\0that\0\0" is
3945 * {foo=bar,this=that}.
3947 * @param cluster rados cluster handle
3948 * @param status_dict status dict
3950 CEPH_RADOS_API
int rados_service_update_status(
3952 const char *status_dict
);
3954 /** @} Mon/OSD/PG commands */
3957 * These methods are no longer supported and return -ENOTSUP where possible.
3959 CEPH_RADOS_API
int rados_objects_list_open(
3961 rados_list_ctx_t
*ctx
) __attribute__((deprecated
));
3962 CEPH_RADOS_API
uint32_t rados_objects_list_get_pg_hash_position(
3963 rados_list_ctx_t ctx
) __attribute__((deprecated
));
3964 CEPH_RADOS_API
uint32_t rados_objects_list_seek(
3965 rados_list_ctx_t ctx
,
3966 uint32_t pos
) __attribute__((deprecated
));
3967 CEPH_RADOS_API
int rados_objects_list_next(
3968 rados_list_ctx_t ctx
,
3970 const char **key
) __attribute__((deprecated
));
3971 CEPH_RADOS_API
void rados_objects_list_close(
3972 rados_list_ctx_t ctx
) __attribute__((deprecated
));