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) 2011 New Dream Network
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.
22 #include <netinet/in.h>
23 #if defined(__linux__)
24 #include <linux/types.h>
25 #elif defined(__FreeBSD__)
26 #include <sys/types.h>
31 #include "../rados/librados.h"
34 #define LIBRBD_VER_MAJOR 1
35 #define LIBRBD_VER_MINOR 12
36 #define LIBRBD_VER_EXTRA 0
38 #define LIBRBD_VERSION(maj, min, extra) ((maj << 16) + (min << 8) + extra)
40 #define LIBRBD_VERSION_CODE LIBRBD_VERSION(LIBRBD_VER_MAJOR, LIBRBD_VER_MINOR, LIBRBD_VER_EXTRA)
42 #define LIBRBD_SUPPORTS_AIO_FLUSH 1
43 #define LIBRBD_SUPPORTS_AIO_OPEN 1
44 #define LIBRBD_SUPPORTS_LOCKING 1
45 #define LIBRBD_SUPPORTS_INVALIDATE 1
46 #define LIBRBD_SUPPORTS_IOVEC 1
47 #define LIBRBD_SUPPORTS_WATCH 0
48 #define LIBRBD_SUPPORTS_WRITESAME 1
51 #define CEPH_RBD_API __attribute__ ((visibility ("default")))
56 #define RBD_FLAG_OBJECT_MAP_INVALID (1<<0)
57 #define RBD_FLAG_FAST_DIFF_INVALID (1<<1)
59 typedef void *rbd_snap_t
;
60 typedef void *rbd_image_t
;
61 typedef void *rbd_image_options_t
;
63 typedef void *rbd_completion_t
;
64 typedef void (*rbd_callback_t
)(rbd_completion_t cb
, void *arg
);
66 typedef int (*librbd_progress_fn_t
)(uint64_t offset
, uint64_t total
, void *ptr
);
68 typedef void (*rbd_update_callback_t
)(void *arg
);
76 #define RBD_MAX_IMAGE_NAME_SIZE 96
77 #define RBD_MAX_BLOCK_NAME_SIZE 24
79 #define RBD_SNAP_REMOVE_UNPROTECT 1 << 0
80 #define RBD_SNAP_REMOVE_FLATTEN 1 << 1
81 #define RBD_SNAP_REMOVE_FORCE (RBD_SNAP_REMOVE_UNPROTECT | RBD_SNAP_REMOVE_FLATTEN)
84 * These types used to in set_image_notification to indicate the type of event
89 EVENT_TYPE_EVENTFD
= 2
97 char block_name_prefix
[RBD_MAX_BLOCK_NAME_SIZE
]; /* deprecated */
98 int64_t parent_pool
; /* deprecated */
99 char parent_name
[RBD_MAX_IMAGE_NAME_SIZE
]; /* deprecated */
103 RBD_MIRROR_MODE_DISABLED
, /* mirroring is disabled */
104 RBD_MIRROR_MODE_IMAGE
, /* mirroring enabled on a per-image basis */
105 RBD_MIRROR_MODE_POOL
/* mirroring enabled on all journaled images */
115 RBD_MIRROR_IMAGE_DISABLING
= 0,
116 RBD_MIRROR_IMAGE_ENABLED
= 1,
117 RBD_MIRROR_IMAGE_DISABLED
= 2
118 } rbd_mirror_image_state_t
;
122 rbd_mirror_image_state_t state
;
124 } rbd_mirror_image_info_t
;
127 MIRROR_IMAGE_STATUS_STATE_UNKNOWN
= 0,
128 MIRROR_IMAGE_STATUS_STATE_ERROR
= 1,
129 MIRROR_IMAGE_STATUS_STATE_SYNCING
= 2,
130 MIRROR_IMAGE_STATUS_STATE_STARTING_REPLAY
= 3,
131 MIRROR_IMAGE_STATUS_STATE_REPLAYING
= 4,
132 MIRROR_IMAGE_STATUS_STATE_STOPPING_REPLAY
= 5,
133 MIRROR_IMAGE_STATUS_STATE_STOPPED
= 6,
134 } rbd_mirror_image_status_state_t
;
138 rbd_mirror_image_info_t info
;
139 rbd_mirror_image_status_state_t state
;
143 } rbd_mirror_image_status_t
;
146 GROUP_IMAGE_STATE_ATTACHED
,
147 GROUP_IMAGE_STATE_INCOMPLETE
148 } rbd_group_image_state_t
;
153 } rbd_group_image_spec_t
;
156 rbd_group_image_spec_t spec
;
157 rbd_group_image_state_t state
;
158 } rbd_group_image_status_t
;
166 RBD_LOCK_MODE_EXCLUSIVE
= 0,
167 RBD_LOCK_MODE_SHARED
= 1,
170 CEPH_RBD_API
void rbd_version(int *major
, int *minor
, int *extra
);
174 RBD_IMAGE_OPTION_FORMAT
= 0,
175 RBD_IMAGE_OPTION_FEATURES
= 1,
176 RBD_IMAGE_OPTION_ORDER
= 2,
177 RBD_IMAGE_OPTION_STRIPE_UNIT
= 3,
178 RBD_IMAGE_OPTION_STRIPE_COUNT
= 4,
179 RBD_IMAGE_OPTION_JOURNAL_ORDER
= 5,
180 RBD_IMAGE_OPTION_JOURNAL_SPLAY_WIDTH
= 6,
181 RBD_IMAGE_OPTION_JOURNAL_POOL
= 7,
182 RBD_IMAGE_OPTION_FEATURES_SET
= 8,
183 RBD_IMAGE_OPTION_FEATURES_CLEAR
= 9,
184 RBD_IMAGE_OPTION_DATA_POOL
= 10
188 RBD_TRASH_IMAGE_SOURCE_USER
= 0,
189 RBD_TRASH_IMAGE_SOURCE_MIRRORING
= 1
190 } rbd_trash_image_source_t
;
195 rbd_trash_image_source_t source
;
196 time_t deletion_time
;
197 time_t deferment_end_time
;
198 } rbd_trash_image_info_t
;
200 CEPH_RBD_API
void rbd_image_options_create(rbd_image_options_t
* opts
);
201 CEPH_RBD_API
void rbd_image_options_destroy(rbd_image_options_t opts
);
202 CEPH_RBD_API
int rbd_image_options_set_string(rbd_image_options_t opts
,
203 int optname
, const char* optval
);
204 CEPH_RBD_API
int rbd_image_options_set_uint64(rbd_image_options_t opts
,
205 int optname
, uint64_t optval
);
206 CEPH_RBD_API
int rbd_image_options_get_string(rbd_image_options_t opts
,
207 int optname
, char* optval
,
209 CEPH_RBD_API
int rbd_image_options_get_uint64(rbd_image_options_t opts
,
210 int optname
, uint64_t* optval
);
211 CEPH_RBD_API
int rbd_image_options_is_set(rbd_image_options_t opts
,
212 int optname
, bool* is_set
);
213 CEPH_RBD_API
int rbd_image_options_unset(rbd_image_options_t opts
, int optname
);
214 CEPH_RBD_API
void rbd_image_options_clear(rbd_image_options_t opts
);
215 CEPH_RBD_API
int rbd_image_options_is_empty(rbd_image_options_t opts
);
218 CEPH_RBD_API
int rbd_list(rados_ioctx_t io
, char *names
, size_t *size
);
219 CEPH_RBD_API
int rbd_create(rados_ioctx_t io
, const char *name
, uint64_t size
,
221 CEPH_RBD_API
int rbd_create2(rados_ioctx_t io
, const char *name
, uint64_t size
,
222 uint64_t features
, int *order
);
224 * create new rbd image
226 * The stripe_unit must be a factor of the object size (1 << order).
227 * The stripe_count can be one (no intra-object striping) or greater
228 * than one. The RBD_FEATURE_STRIPINGV2 must be specified if the
229 * stripe_unit != the object size and the stripe_count is != 1.
232 * @param name image name
233 * @param size image size in bytes
234 * @param features initial feature bits
235 * @param order object/block size, as a power of two (object size == 1 << order)
236 * @param stripe_unit stripe unit size, in bytes.
237 * @param stripe_count number of objects to stripe over before looping
238 * @return 0 on success, or negative error code
240 CEPH_RBD_API
int rbd_create3(rados_ioctx_t io
, const char *name
, uint64_t size
,
241 uint64_t features
, int *order
,
242 uint64_t stripe_unit
, uint64_t stripe_count
);
243 CEPH_RBD_API
int rbd_create4(rados_ioctx_t io
, const char *name
, uint64_t size
,
244 rbd_image_options_t opts
);
245 CEPH_RBD_API
int rbd_clone(rados_ioctx_t p_ioctx
, const char *p_name
,
246 const char *p_snapname
, rados_ioctx_t c_ioctx
,
247 const char *c_name
, uint64_t features
, int *c_order
);
248 CEPH_RBD_API
int rbd_clone2(rados_ioctx_t p_ioctx
, const char *p_name
,
249 const char *p_snapname
, rados_ioctx_t c_ioctx
,
250 const char *c_name
, uint64_t features
, int *c_order
,
251 uint64_t stripe_unit
, int stripe_count
);
252 CEPH_RBD_API
int rbd_clone3(rados_ioctx_t p_ioctx
, const char *p_name
,
253 const char *p_snapname
, rados_ioctx_t c_ioctx
,
254 const char *c_name
, rbd_image_options_t c_opts
);
255 CEPH_RBD_API
int rbd_remove(rados_ioctx_t io
, const char *name
);
256 CEPH_RBD_API
int rbd_remove_with_progress(rados_ioctx_t io
, const char *name
,
257 librbd_progress_fn_t cb
,
259 CEPH_RBD_API
int rbd_rename(rados_ioctx_t src_io_ctx
, const char *srcname
,
260 const char *destname
);
262 CEPH_RBD_API
int rbd_trash_move(rados_ioctx_t io
, const char *name
,
264 CEPH_RBD_API
int rbd_trash_get(rados_ioctx_t io
, const char *id
,
265 rbd_trash_image_info_t
*info
);
266 CEPH_RBD_API
void rbd_trash_get_cleanup(rbd_trash_image_info_t
*info
);
267 CEPH_RBD_API
int rbd_trash_list(rados_ioctx_t io
,
268 rbd_trash_image_info_t
*trash_entries
,
269 size_t *num_entries
);
270 CEPH_RBD_API
void rbd_trash_list_cleanup(rbd_trash_image_info_t
*trash_entries
,
272 CEPH_RBD_API
int rbd_trash_remove(rados_ioctx_t io
, const char *id
, bool force
);
273 CEPH_RBD_API
int rbd_trash_remove_with_progress(rados_ioctx_t io
, const char *id
,
274 bool force
, librbd_progress_fn_t cb
,
276 CEPH_RBD_API
int rbd_trash_restore(rados_ioctx_t io
, const char *id
,
280 CEPH_RBD_API
int rbd_mirror_mode_get(rados_ioctx_t io_ctx
,
281 rbd_mirror_mode_t
*mirror_mode
);
282 CEPH_RBD_API
int rbd_mirror_mode_set(rados_ioctx_t io_ctx
,
283 rbd_mirror_mode_t mirror_mode
);
284 CEPH_RBD_API
int rbd_mirror_peer_add(rados_ioctx_t io_ctx
,
285 char *uuid
, size_t uuid_max_length
,
286 const char *cluster_name
,
287 const char *client_name
);
288 CEPH_RBD_API
int rbd_mirror_peer_remove(rados_ioctx_t io_ctx
,
290 CEPH_RBD_API
int rbd_mirror_peer_list(rados_ioctx_t io_ctx
,
291 rbd_mirror_peer_t
*peers
, int *max_peers
);
292 CEPH_RBD_API
void rbd_mirror_peer_list_cleanup(rbd_mirror_peer_t
*peers
,
294 CEPH_RBD_API
int rbd_mirror_peer_set_client(rados_ioctx_t io_ctx
,
296 const char *client_name
);
297 CEPH_RBD_API
int rbd_mirror_peer_set_cluster(rados_ioctx_t io_ctx
,
299 const char *cluster_name
);
300 CEPH_RBD_API
int rbd_mirror_image_status_list(rados_ioctx_t io_ctx
,
301 const char *start_id
, size_t max
,
303 rbd_mirror_image_status_t
*images
,
305 CEPH_RBD_API
void rbd_mirror_image_status_list_cleanup(char **image_ids
,
306 rbd_mirror_image_status_t
*images
, size_t len
);
307 CEPH_RBD_API
int rbd_mirror_image_status_summary(rados_ioctx_t io_ctx
,
308 rbd_mirror_image_status_state_t
*states
, int *counts
, size_t *maxlen
);
310 CEPH_RBD_API
int rbd_open(rados_ioctx_t io
, const char *name
,
311 rbd_image_t
*image
, const char *snap_name
);
312 CEPH_RBD_API
int rbd_open_by_id(rados_ioctx_t io
, const char *id
,
313 rbd_image_t
*image
, const char *snap_name
);
315 CEPH_RBD_API
int rbd_aio_open(rados_ioctx_t io
, const char *name
,
316 rbd_image_t
*image
, const char *snap_name
,
318 CEPH_RBD_API
int rbd_aio_open_by_id(rados_ioctx_t io
, const char *id
,
319 rbd_image_t
*image
, const char *snap_name
,
323 * Open an image in read-only mode.
325 * This is intended for use by clients that cannot write to a block
326 * device due to cephx restrictions. There will be no watch
327 * established on the header object, since a watch is a write. This
328 * means the metadata reported about this image (parents, snapshots,
329 * size, etc.) may become stale. This should not be used for
330 * long-running operations, unless you can be sure that one of these
331 * properties changing is safe.
333 * Attempting to write to a read-only image will return -EROFS.
335 * @param io ioctx to determine the pool the image is in
336 * @param name image name
337 * @param image where to store newly opened image handle
338 * @param snap_name name of snapshot to open at, or NULL for no snapshot
339 * @returns 0 on success, negative error code on failure
341 CEPH_RBD_API
int rbd_open_read_only(rados_ioctx_t io
, const char *name
,
342 rbd_image_t
*image
, const char *snap_name
);
343 CEPH_RBD_API
int rbd_open_by_id_read_only(rados_ioctx_t io
, const char *id
,
344 rbd_image_t
*image
, const char *snap_name
);
345 CEPH_RBD_API
int rbd_aio_open_read_only(rados_ioctx_t io
, const char *name
,
346 rbd_image_t
*image
, const char *snap_name
,
348 CEPH_RBD_API
int rbd_aio_open_by_id_read_only(rados_ioctx_t io
, const char *id
,
349 rbd_image_t
*image
, const char *snap_name
,
351 CEPH_RBD_API
int rbd_close(rbd_image_t image
);
352 CEPH_RBD_API
int rbd_aio_close(rbd_image_t image
, rbd_completion_t c
);
353 CEPH_RBD_API
int rbd_resize(rbd_image_t image
, uint64_t size
);
354 CEPH_RBD_API
int rbd_resize2(rbd_image_t image
, uint64_t size
, bool allow_shrink
,
355 librbd_progress_fn_t cb
, void *cbdata
);
356 CEPH_RBD_API
int rbd_resize_with_progress(rbd_image_t image
, uint64_t size
,
357 librbd_progress_fn_t cb
, void *cbdata
);
358 CEPH_RBD_API
int rbd_stat(rbd_image_t image
, rbd_image_info_t
*info
,
360 CEPH_RBD_API
int rbd_get_old_format(rbd_image_t image
, uint8_t *old
);
361 CEPH_RBD_API
int rbd_get_size(rbd_image_t image
, uint64_t *size
);
362 CEPH_RBD_API
int rbd_get_features(rbd_image_t image
, uint64_t *features
);
363 CEPH_RBD_API
int rbd_update_features(rbd_image_t image
, uint64_t features
,
365 CEPH_RBD_API
int rbd_get_stripe_unit(rbd_image_t image
, uint64_t *stripe_unit
);
366 CEPH_RBD_API
int rbd_get_stripe_count(rbd_image_t image
,
367 uint64_t *stripe_count
);
369 CEPH_RBD_API
int rbd_get_create_timestamp(rbd_image_t image
,
370 struct timespec
*timestamp
);
372 CEPH_RBD_API
int rbd_get_overlap(rbd_image_t image
, uint64_t *overlap
);
373 CEPH_RBD_API
int rbd_get_id(rbd_image_t image
, char *id
, size_t id_len
);
374 CEPH_RBD_API
int rbd_get_block_name_prefix(rbd_image_t image
,
375 char *prefix
, size_t prefix_len
);
376 CEPH_RBD_API
int64_t rbd_get_data_pool_id(rbd_image_t image
);
377 CEPH_RBD_API
int rbd_get_parent_info(rbd_image_t image
,
378 char *parent_poolname
, size_t ppoolnamelen
,
379 char *parent_name
, size_t pnamelen
,
380 char *parent_snapname
,
381 size_t psnapnamelen
);
382 CEPH_RBD_API
int rbd_get_parent_info2(rbd_image_t image
,
383 char *parent_poolname
,
385 char *parent_name
, size_t pnamelen
,
386 char *parent_id
, size_t pidlen
,
387 char *parent_snapname
,
388 size_t psnapnamelen
);
389 CEPH_RBD_API
int rbd_get_flags(rbd_image_t image
, uint64_t *flags
);
390 CEPH_RBD_API
int rbd_set_image_notification(rbd_image_t image
, int fd
, int type
);
392 /* exclusive lock feature */
393 CEPH_RBD_API
int rbd_is_exclusive_lock_owner(rbd_image_t image
, int *is_owner
);
394 CEPH_RBD_API
int rbd_lock_acquire(rbd_image_t image
, rbd_lock_mode_t lock_mode
);
395 CEPH_RBD_API
int rbd_lock_release(rbd_image_t image
);
396 CEPH_RBD_API
int rbd_lock_get_owners(rbd_image_t image
,
397 rbd_lock_mode_t
*lock_mode
,
399 size_t *max_lock_owners
);
400 CEPH_RBD_API
void rbd_lock_get_owners_cleanup(char **lock_owners
,
401 size_t lock_owner_count
);
402 CEPH_RBD_API
int rbd_lock_break(rbd_image_t image
, rbd_lock_mode_t lock_mode
,
403 const char *lock_owner
);
405 /* object map feature */
406 CEPH_RBD_API
int rbd_rebuild_object_map(rbd_image_t image
,
407 librbd_progress_fn_t cb
, void *cbdata
);
409 CEPH_RBD_API
int rbd_copy(rbd_image_t image
, rados_ioctx_t dest_io_ctx
,
410 const char *destname
);
411 CEPH_RBD_API
int rbd_copy2(rbd_image_t src
, rbd_image_t dest
);
412 CEPH_RBD_API
int rbd_copy3(rbd_image_t src
, rados_ioctx_t dest_io_ctx
,
413 const char *destname
, rbd_image_options_t dest_opts
);
414 CEPH_RBD_API
int rbd_copy4(rbd_image_t src
, rados_ioctx_t dest_io_ctx
,
415 const char *destname
, rbd_image_options_t dest_opts
,
417 CEPH_RBD_API
int rbd_copy_with_progress(rbd_image_t image
, rados_ioctx_t dest_p
,
418 const char *destname
,
419 librbd_progress_fn_t cb
, void *cbdata
);
420 CEPH_RBD_API
int rbd_copy_with_progress2(rbd_image_t src
, rbd_image_t dest
,
421 librbd_progress_fn_t cb
, void *cbdata
);
422 CEPH_RBD_API
int rbd_copy_with_progress3(rbd_image_t image
,
423 rados_ioctx_t dest_p
,
424 const char *destname
,
425 rbd_image_options_t dest_opts
,
426 librbd_progress_fn_t cb
, void *cbdata
);
427 CEPH_RBD_API
int rbd_copy_with_progress4(rbd_image_t image
,
428 rados_ioctx_t dest_p
,
429 const char *destname
,
430 rbd_image_options_t dest_opts
,
431 librbd_progress_fn_t cb
, void *cbdata
,
435 CEPH_RBD_API
int rbd_snap_list(rbd_image_t image
, rbd_snap_info_t
*snaps
,
437 CEPH_RBD_API
void rbd_snap_list_end(rbd_snap_info_t
*snaps
);
438 CEPH_RBD_API
int rbd_snap_create(rbd_image_t image
, const char *snapname
);
439 CEPH_RBD_API
int rbd_snap_remove(rbd_image_t image
, const char *snapname
);
440 CEPH_RBD_API
int rbd_snap_remove2(rbd_image_t image
, const char *snap_name
, uint32_t flags
,
441 librbd_progress_fn_t cb
, void *cbdata
);
442 CEPH_RBD_API
int rbd_snap_rollback(rbd_image_t image
, const char *snapname
);
443 CEPH_RBD_API
int rbd_snap_rollback_with_progress(rbd_image_t image
,
444 const char *snapname
,
445 librbd_progress_fn_t cb
,
447 CEPH_RBD_API
int rbd_snap_rename(rbd_image_t image
, const char *snapname
,
448 const char* dstsnapsname
);
450 * Prevent a snapshot from being deleted until it is unprotected.
452 * @param snap_name which snapshot to protect
453 * @returns 0 on success, negative error code on failure
454 * @returns -EBUSY if snap is already protected
456 CEPH_RBD_API
int rbd_snap_protect(rbd_image_t image
, const char *snap_name
);
458 * Allow a snaphshot to be deleted.
460 * @param snap_name which snapshot to unprotect
461 * @returns 0 on success, negative error code on failure
462 * @returns -EINVAL if snap is not protected
464 CEPH_RBD_API
int rbd_snap_unprotect(rbd_image_t image
, const char *snap_name
);
466 * Determine whether a snapshot is protected.
468 * @param snap_name which snapshot query
469 * @param is_protected where to store the result (0 or 1)
470 * @returns 0 on success, negative error code on failure
472 CEPH_RBD_API
int rbd_snap_is_protected(rbd_image_t image
, const char *snap_name
,
475 * Get the current snapshot limit for an image. If no limit is set,
476 * UINT64_MAX is returned.
478 * @param limit pointer where the limit will be stored on success
479 * @returns 0 on success, negative error code on failure
481 CEPH_RBD_API
int rbd_snap_get_limit(rbd_image_t image
, uint64_t *limit
);
484 * Set a limit for the number of snapshots that may be taken of an image.
486 * @param limit the maximum number of snapshots allowed in the future.
487 * @returns 0 on success, negative error code on failure
489 CEPH_RBD_API
int rbd_snap_set_limit(rbd_image_t image
, uint64_t limit
);
492 * Get the timestamp of a snapshot for an image.
494 * @param snap_id the snap id of a snapshot of input image.
495 * @param timestamp the timestamp of input snapshot.
496 * @returns 0 on success, negative error code on failure
498 CEPH_RBD_API
int rbd_snap_get_timestamp(rbd_image_t image
, uint64_t snap_id
, struct timespec
*timestamp
);
500 CEPH_RBD_API
int rbd_snap_set(rbd_image_t image
, const char *snapname
);
502 CEPH_RBD_API
int rbd_flatten(rbd_image_t image
);
504 CEPH_RBD_API
int rbd_flatten_with_progress(rbd_image_t image
,
505 librbd_progress_fn_t cb
,
509 * List all images that are cloned from the image at the
510 * snapshot that is set via rbd_snap_set().
512 * This iterates over all pools, so it should be run by a user with
513 * read access to all of them. pools_len and images_len are filled in
514 * with the number of bytes put into the pools and images buffers.
516 * If the provided buffers are too short, the required lengths are
517 * still filled in, but the data is not and -ERANGE is returned.
518 * Otherwise, the buffers are filled with the pool and image names
519 * of the children, with a '\0' after each.
521 * @param image which image (and implicitly snapshot) to list clones of
522 * @param pools buffer in which to store pool names
523 * @param pools_len number of bytes in pools buffer
524 * @param images buffer in which to store image names
525 * @param images_len number of bytes in images buffer
526 * @returns number of children on success, negative error code on failure
527 * @returns -ERANGE if either buffer is too short
529 CEPH_RBD_API ssize_t
rbd_list_children(rbd_image_t image
, char *pools
,
530 size_t *pools_len
, char *images
,
534 * @defgroup librbd_h_locking Advisory Locking
536 * An rbd image may be locking exclusively, or shared, to facilitate
537 * e.g. live migration where the image may be open in two places at once.
538 * These locks are intended to guard against more than one client
539 * writing to an image without coordination. They don't need to
540 * be used for snapshots, since snapshots are read-only.
542 * Currently locks only guard against locks being acquired.
543 * They do not prevent anything else.
545 * A locker is identified by the internal rados client id of the
546 * holder and a user-defined cookie. This (client id, cookie) pair
547 * must be unique for each locker.
549 * A shared lock also has a user-defined tag associated with it. Each
550 * additional shared lock must specify the same tag or lock
551 * acquisition will fail. This can be used by e.g. groups of hosts
552 * using a clustered filesystem on top of an rbd image to make sure
553 * they're accessing the correct image.
558 * List clients that have locked the image and information about the lock.
560 * The number of bytes required in each buffer is put in the
561 * corresponding size out parameter. If any of the provided buffers
562 * are too short, -ERANGE is returned after these sizes are filled in.
564 * @param exclusive where to store whether the lock is exclusive (1) or shared (0)
565 * @param tag where to store the tag associated with the image
566 * @param tag_len number of bytes in tag buffer
567 * @param clients buffer in which locker clients are stored, separated by '\0'
568 * @param clients_len number of bytes in the clients buffer
569 * @param cookies buffer in which locker cookies are stored, separated by '\0'
570 * @param cookies_len number of bytes in the cookies buffer
571 * @param addrs buffer in which locker addresses are stored, separated by '\0'
572 * @param addrs_len number of bytes in the clients buffer
573 * @returns number of lockers on success, negative error code on failure
574 * @returns -ERANGE if any of the buffers are too short
576 CEPH_RBD_API ssize_t
rbd_list_lockers(rbd_image_t image
, int *exclusive
,
577 char *tag
, size_t *tag_len
,
578 char *clients
, size_t *clients_len
,
579 char *cookies
, size_t *cookies_len
,
580 char *addrs
, size_t *addrs_len
);
583 * Take an exclusive lock on the image.
585 * @param image the image to lock
586 * @param cookie user-defined identifier for this instance of the lock
587 * @returns 0 on success, negative error code on failure
588 * @returns -EBUSY if the lock is already held by another (client, cookie) pair
589 * @returns -EEXIST if the lock is already held by the same (client, cookie) pair
591 CEPH_RBD_API
int rbd_lock_exclusive(rbd_image_t image
, const char *cookie
);
594 * Take a shared lock on the image.
596 * Other clients may also take a shared lock, as lock as they use the
599 * @param image the image to lock
600 * @param cookie user-defined identifier for this instance of the lock
601 * @param tag user-defined identifier for this shared use of the lock
602 * @returns 0 on success, negative error code on failure
603 * @returns -EBUSY if the lock is already held by another (client, cookie) pair
604 * @returns -EEXIST if the lock is already held by the same (client, cookie) pair
606 CEPH_RBD_API
int rbd_lock_shared(rbd_image_t image
, const char *cookie
,
610 * Release a shared or exclusive lock on the image.
612 * @param image the image to unlock
613 * @param cookie user-defined identifier for the instance of the lock
614 * @returns 0 on success, negative error code on failure
615 * @returns -ENOENT if the lock is not held by the specified (client, cookie) pair
617 CEPH_RBD_API
int rbd_unlock(rbd_image_t image
, const char *cookie
);
620 * Release a shared or exclusive lock that was taken by the specified client.
622 * @param image the image to unlock
623 * @param client the entity holding the lock (as given by rbd_list_lockers())
624 * @param cookie user-defined identifier for the instance of the lock to break
625 * @returns 0 on success, negative error code on failure
626 * @returns -ENOENT if the lock is not held by the specified (client, cookie) pair
628 CEPH_RBD_API
int rbd_break_lock(rbd_image_t image
, const char *client
,
634 CEPH_RBD_API ssize_t
rbd_read(rbd_image_t image
, uint64_t ofs
, size_t len
,
637 * @param op_flags: see librados.h constants beginning with LIBRADOS_OP_FLAG
639 CEPH_RBD_API ssize_t
rbd_read2(rbd_image_t image
, uint64_t ofs
, size_t len
,
640 char *buf
, int op_flags
);
641 /* DEPRECATED; use rbd_read_iterate2 */
642 CEPH_RBD_API
int64_t rbd_read_iterate(rbd_image_t image
, uint64_t ofs
, size_t len
,
643 int (*cb
)(uint64_t, size_t, const char *, void *),
647 * iterate read over an image
649 * Reads each region of the image and calls the callback. If the
650 * buffer pointer passed to the callback is NULL, the given extent is
651 * defined to be zeros (a hole). Normally the granularity for the
652 * callback is the image stripe size.
654 * @param image image to read
655 * @param ofs offset to start from
656 * @param len bytes of source image to cover
657 * @param cb callback for each region
658 * @returns 0 success, error otherwise
660 CEPH_RBD_API
int rbd_read_iterate2(rbd_image_t image
, uint64_t ofs
, uint64_t len
,
661 int (*cb
)(uint64_t, size_t, const char *, void *),
664 * get difference between two versions of an image
666 * This will return the differences between two versions of an image
667 * via a callback, which gets the offset and length and a flag
668 * indicating whether the extent exists (1), or is known/defined to
669 * be zeros (a hole, 0). If the source snapshot name is NULL, we
670 * interpret that as the beginning of time and return all allocated
671 * regions of the image. The end version is whatever is currently
672 * selected for the image handle (either a snapshot or the writeable
675 * @param fromsnapname start snapshot name, or NULL
676 * @param ofs start offset
677 * @param len len in bytes of region to report on
678 * @param include_parent 1 if full history diff should include parent
679 * @param whole_object 1 if diff extents should cover whole object
680 * @param cb callback to call for each allocated region
681 * @param arg argument to pass to the callback
682 * @returns 0 on success, or negative error code on error
684 CEPH_RBD_API
int rbd_diff_iterate(rbd_image_t image
,
685 const char *fromsnapname
,
686 uint64_t ofs
, uint64_t len
,
687 int (*cb
)(uint64_t, size_t, int, void *),
689 CEPH_RBD_API
int rbd_diff_iterate2(rbd_image_t image
,
690 const char *fromsnapname
,
691 uint64_t ofs
, uint64_t len
,
692 uint8_t include_parent
, uint8_t whole_object
,
693 int (*cb
)(uint64_t, size_t, int, void *),
695 CEPH_RBD_API ssize_t
rbd_write(rbd_image_t image
, uint64_t ofs
, size_t len
,
698 * @param op_flags: see librados.h constants beginning with LIBRADOS_OP_FLAG
700 CEPH_RBD_API ssize_t
rbd_write2(rbd_image_t image
, uint64_t ofs
, size_t len
,
701 const char *buf
, int op_flags
);
702 CEPH_RBD_API
int rbd_discard(rbd_image_t image
, uint64_t ofs
, uint64_t len
);
703 CEPH_RBD_API ssize_t
rbd_writesame(rbd_image_t image
, uint64_t ofs
, size_t len
,
704 const char *buf
, size_t data_len
, int op_flags
);
705 CEPH_RBD_API ssize_t
rbd_compare_and_write(rbd_image_t image
, uint64_t ofs
,
706 size_t len
, const char *cmp_buf
,
707 const char *buf
, uint64_t *mismatch_off
,
710 CEPH_RBD_API
int rbd_aio_write(rbd_image_t image
, uint64_t off
, size_t len
,
711 const char *buf
, rbd_completion_t c
);
714 * @param op_flags: see librados.h constants beginning with LIBRADOS_OP_FLAG
716 CEPH_RBD_API
int rbd_aio_write2(rbd_image_t image
, uint64_t off
, size_t len
,
717 const char *buf
, rbd_completion_t c
,
719 CEPH_RBD_API
int rbd_aio_writev(rbd_image_t image
, const struct iovec
*iov
,
720 int iovcnt
, uint64_t off
, rbd_completion_t c
);
721 CEPH_RBD_API
int rbd_aio_read(rbd_image_t image
, uint64_t off
, size_t len
,
722 char *buf
, rbd_completion_t c
);
724 * @param op_flags: see librados.h constants beginning with LIBRADOS_OP_FLAG
726 CEPH_RBD_API
int rbd_aio_read2(rbd_image_t image
, uint64_t off
, size_t len
,
727 char *buf
, rbd_completion_t c
, int op_flags
);
728 CEPH_RBD_API
int rbd_aio_readv(rbd_image_t image
, const struct iovec
*iov
,
729 int iovcnt
, uint64_t off
, rbd_completion_t c
);
730 CEPH_RBD_API
int rbd_aio_discard(rbd_image_t image
, uint64_t off
, uint64_t len
,
732 CEPH_RBD_API
int rbd_aio_writesame(rbd_image_t image
, uint64_t off
, size_t len
,
733 const char *buf
, size_t data_len
,
734 rbd_completion_t c
, int op_flags
);
735 CEPH_RBD_API ssize_t
rbd_aio_compare_and_write(rbd_image_t image
,
736 uint64_t off
, size_t len
,
737 const char *cmp_buf
, const char *buf
,
738 rbd_completion_t c
, uint64_t *mismatch_off
,
741 CEPH_RBD_API
int rbd_aio_create_completion(void *cb_arg
,
742 rbd_callback_t complete_cb
,
743 rbd_completion_t
*c
);
744 CEPH_RBD_API
int rbd_aio_is_complete(rbd_completion_t c
);
745 CEPH_RBD_API
int rbd_aio_wait_for_complete(rbd_completion_t c
);
746 CEPH_RBD_API ssize_t
rbd_aio_get_return_value(rbd_completion_t c
);
747 CEPH_RBD_API
void *rbd_aio_get_arg(rbd_completion_t c
);
748 CEPH_RBD_API
void rbd_aio_release(rbd_completion_t c
);
749 CEPH_RBD_API
int rbd_flush(rbd_image_t image
);
751 * Start a flush if caching is enabled. Get a callback when
752 * the currently pending writes are on disk.
754 * @param image the image to flush writes to
755 * @param c what to call when flushing is complete
756 * @returns 0 on success, negative error code on failure
758 CEPH_RBD_API
int rbd_aio_flush(rbd_image_t image
, rbd_completion_t c
);
761 * Drop any cached data for an image
763 * @param image the image to invalidate cached data for
764 * @returns 0 on success, negative error code on failure
766 CEPH_RBD_API
int rbd_invalidate_cache(rbd_image_t image
);
768 CEPH_RBD_API
int rbd_poll_io_events(rbd_image_t image
, rbd_completion_t
*comps
, int numcomp
);
770 CEPH_RBD_API
int rbd_metadata_get(rbd_image_t image
, const char *key
, char *value
, size_t *val_len
);
771 CEPH_RBD_API
int rbd_metadata_set(rbd_image_t image
, const char *key
, const char *value
);
772 CEPH_RBD_API
int rbd_metadata_remove(rbd_image_t image
, const char *key
);
774 * List all metadatas associated with this image.
776 * This iterates over all metadatas, key_len and val_len are filled in
777 * with the number of bytes put into the keys and values buffers.
779 * If the provided buffers are too short, the required lengths are
780 * still filled in, but the data is not and -ERANGE is returned.
781 * Otherwise, the buffers are filled with the keys and values
782 * of the image, with a '\0' after each.
784 * @param image which image (and implicitly snapshot) to list clones of
785 * @param start_after which name to begin listing after
786 * (use the empty string to start at the beginning)
787 * @param max the maximum number of names to lis(if 0 means no limit)
788 * @param keys buffer in which to store pool names
789 * @param keys_len number of bytes in pools buffer
790 * @param values buffer in which to store image names
791 * @param vals_len number of bytes in images buffer
792 * @returns number of children on success, negative error code on failure
793 * @returns -ERANGE if either buffer is too short
795 CEPH_RBD_API
int rbd_metadata_list(rbd_image_t image
, const char *start
, uint64_t max
,
796 char *keys
, size_t *key_len
, char *values
, size_t *vals_len
);
798 // RBD image mirroring support functions
799 CEPH_RBD_API
int rbd_mirror_image_enable(rbd_image_t image
);
800 CEPH_RBD_API
int rbd_mirror_image_disable(rbd_image_t image
, bool force
);
801 CEPH_RBD_API
int rbd_mirror_image_promote(rbd_image_t image
, bool force
);
802 CEPH_RBD_API
int rbd_mirror_image_demote(rbd_image_t image
);
803 CEPH_RBD_API
int rbd_mirror_image_resync(rbd_image_t image
);
804 CEPH_RBD_API
int rbd_mirror_image_get_info(rbd_image_t image
,
805 rbd_mirror_image_info_t
*mirror_image_info
,
807 CEPH_RBD_API
int rbd_mirror_image_get_status(rbd_image_t image
,
808 rbd_mirror_image_status_t
*mirror_image_status
,
810 CEPH_RBD_API
int rbd_aio_mirror_image_promote(rbd_image_t image
, bool force
,
812 CEPH_RBD_API
int rbd_aio_mirror_image_demote(rbd_image_t image
,
814 CEPH_RBD_API
int rbd_aio_mirror_image_get_info(rbd_image_t image
,
815 rbd_mirror_image_info_t
*mirror_image_info
,
818 CEPH_RBD_API
int rbd_aio_mirror_image_get_status(rbd_image_t image
,
819 rbd_mirror_image_status_t
*mirror_image_status
,
823 // RBD consistency groups support functions
824 CEPH_RBD_API
int rbd_group_create(rados_ioctx_t p
, const char *name
);
825 CEPH_RBD_API
int rbd_group_remove(rados_ioctx_t p
, const char *name
);
826 CEPH_RBD_API
int rbd_group_list(rados_ioctx_t p
, char *names
, size_t *size
);
829 * Register an image metadata change watcher.
831 * @param image the image to watch
832 * @param handle where to store the internal id assigned to this watch
833 * @param watch_cb what to do when a notify is received on this image
834 * @param arg opaque value to pass to the callback
835 * @returns 0 on success, negative error code on failure
837 CEPH_RBD_API
int rbd_update_watch(rbd_image_t image
, uint64_t *handle
,
838 rbd_update_callback_t watch_cb
, void *arg
);
841 * Unregister an image watcher.
843 * @param image the image to unwatch
844 * @param handle which watch to unregister
845 * @returns 0 on success, negative error code on failure
847 CEPH_RBD_API
int rbd_update_unwatch(rbd_image_t image
, uint64_t handle
);
850 CEPH_RBD_API
int rbd_group_image_add(
851 rados_ioctx_t group_p
, const char *group_name
,
852 rados_ioctx_t image_p
, const char *image_name
);
853 CEPH_RBD_API
int rbd_group_image_remove(
854 rados_ioctx_t group_p
, const char *group_name
,
855 rados_ioctx_t image_p
, const char *image_name
);
856 CEPH_RBD_API
int rbd_group_image_remove_by_id(
857 rados_ioctx_t group_p
, const char *group_name
,
858 rados_ioctx_t image_p
, const char *image_id
);
859 CEPH_RBD_API
int rbd_group_image_list(
860 rados_ioctx_t group_p
, const char *group_name
,
861 rbd_group_image_status_t
*images
,
863 CEPH_RBD_API
int rbd_image_get_group(rados_ioctx_t image_p
,
864 const char *image_name
,
865 rbd_group_spec_t
*group_spec
);
866 CEPH_RBD_API
void rbd_group_spec_cleanup(rbd_group_spec_t
*group_spec
);
867 CEPH_RBD_API
void rbd_group_image_status_cleanup(
868 rbd_group_image_status_t
*image
870 CEPH_RBD_API
void rbd_group_image_status_list_cleanup(
871 rbd_group_image_status_t
*images
,