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 18
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_COMPARE_AND_WRITE 1
45 #define LIBRBD_SUPPORTS_COMPARE_AND_WRITE_IOVEC 1
46 #define LIBRBD_SUPPORTS_LOCKING 1
47 #define LIBRBD_SUPPORTS_INVALIDATE 1
48 #define LIBRBD_SUPPORTS_IOVEC 1
49 #define LIBRBD_SUPPORTS_WATCH 0
50 #define LIBRBD_SUPPORTS_WRITESAME 1
51 #define LIBRBD_SUPPORTS_WRITE_ZEROES 1
52 #define LIBRBD_SUPPORTS_ENCRYPTION 1
53 #define LIBRBD_SUPPORTS_ENCRYPTION_LOAD2 1
56 #define CEPH_RBD_API __attribute__ ((visibility ("default")))
57 #define CEPH_RBD_DEPRECATED __attribute__((deprecated))
58 #pragma GCC diagnostic push
59 #pragma GCC diagnostic ignored "-Wdeprecated-declarations"
62 #define CEPH_RBD_DEPRECATED
65 #define RBD_FLAG_OBJECT_MAP_INVALID (1<<0)
66 #define RBD_FLAG_FAST_DIFF_INVALID (1<<1)
68 #define RBD_MIRROR_IMAGE_STATUS_LOCAL_MIRROR_UUID ""
70 typedef void *rbd_image_t
;
71 typedef void *rbd_image_options_t
;
72 typedef void *rbd_pool_stats_t
;
74 typedef void *rbd_completion_t
;
75 typedef void (*rbd_callback_t
)(rbd_completion_t cb
, void *arg
);
77 typedef int (*librbd_progress_fn_t
)(uint64_t offset
, uint64_t total
, void *ptr
);
79 typedef void (*rbd_update_callback_t
)(void *arg
);
82 RBD_SNAP_NAMESPACE_TYPE_USER
= 0,
83 RBD_SNAP_NAMESPACE_TYPE_GROUP
= 1,
84 RBD_SNAP_NAMESPACE_TYPE_TRASH
= 2,
85 RBD_SNAP_NAMESPACE_TYPE_MIRROR
= 3,
86 } rbd_snap_namespace_type_t
;
100 } rbd_linked_image_spec_t
;
104 rbd_snap_namespace_type_t namespace_type
;
115 const char *pool_name
;
116 const char *image_name
;
117 const char *image_id
;
121 #define RBD_MAX_IMAGE_NAME_SIZE 96
122 #define RBD_MAX_BLOCK_NAME_SIZE 24
124 #define RBD_SNAP_CREATE_SKIP_QUIESCE (1 << 0)
125 #define RBD_SNAP_CREATE_IGNORE_QUIESCE_ERROR (1 << 1)
127 #define RBD_SNAP_REMOVE_UNPROTECT (1 << 0)
128 #define RBD_SNAP_REMOVE_FLATTEN (1 << 1)
129 #define RBD_SNAP_REMOVE_FORCE (RBD_SNAP_REMOVE_UNPROTECT | RBD_SNAP_REMOVE_FLATTEN)
132 * These types used to in set_image_notification to indicate the type of event
137 EVENT_TYPE_EVENTFD
= 2
145 char block_name_prefix
[RBD_MAX_BLOCK_NAME_SIZE
]; /* deprecated */
146 int64_t parent_pool
; /* deprecated */
147 char parent_name
[RBD_MAX_IMAGE_NAME_SIZE
]; /* deprecated */
151 RBD_MIRROR_MODE_DISABLED
, /* mirroring is disabled */
152 RBD_MIRROR_MODE_IMAGE
, /* mirroring enabled on a per-image basis */
153 RBD_MIRROR_MODE_POOL
/* mirroring enabled on all journaled images */
157 RBD_MIRROR_PEER_DIRECTION_RX
= 0,
158 RBD_MIRROR_PEER_DIRECTION_TX
= 1,
159 RBD_MIRROR_PEER_DIRECTION_RX_TX
= 2
160 } rbd_mirror_peer_direction_t
;
166 } rbd_mirror_peer_t CEPH_RBD_DEPRECATED
;
170 rbd_mirror_peer_direction_t direction
;
175 } rbd_mirror_peer_site_t
;
177 #define RBD_MIRROR_PEER_ATTRIBUTE_NAME_MON_HOST "mon_host"
178 #define RBD_MIRROR_PEER_ATTRIBUTE_NAME_KEY "key"
181 RBD_MIRROR_IMAGE_MODE_JOURNAL
= 0,
182 RBD_MIRROR_IMAGE_MODE_SNAPSHOT
= 1,
183 } rbd_mirror_image_mode_t
;
186 RBD_MIRROR_IMAGE_DISABLING
= 0,
187 RBD_MIRROR_IMAGE_ENABLED
= 1,
188 RBD_MIRROR_IMAGE_DISABLED
= 2
189 } rbd_mirror_image_state_t
;
193 rbd_mirror_image_state_t state
;
195 } rbd_mirror_image_info_t
;
198 MIRROR_IMAGE_STATUS_STATE_UNKNOWN
= 0,
199 MIRROR_IMAGE_STATUS_STATE_ERROR
= 1,
200 MIRROR_IMAGE_STATUS_STATE_SYNCING
= 2,
201 MIRROR_IMAGE_STATUS_STATE_STARTING_REPLAY
= 3,
202 MIRROR_IMAGE_STATUS_STATE_REPLAYING
= 4,
203 MIRROR_IMAGE_STATUS_STATE_STOPPING_REPLAY
= 5,
204 MIRROR_IMAGE_STATUS_STATE_STOPPED
= 6,
205 } rbd_mirror_image_status_state_t
;
209 rbd_mirror_image_info_t info
;
210 rbd_mirror_image_status_state_t state
;
214 } rbd_mirror_image_status_t CEPH_RBD_DEPRECATED
;
218 rbd_mirror_image_status_state_t state
;
222 } rbd_mirror_image_site_status_t
;
226 rbd_mirror_image_info_t info
;
227 uint32_t site_statuses_count
;
228 rbd_mirror_image_site_status_t
*site_statuses
;
229 } rbd_mirror_image_global_status_t
;
232 RBD_GROUP_IMAGE_STATE_ATTACHED
,
233 RBD_GROUP_IMAGE_STATE_INCOMPLETE
234 } rbd_group_image_state_t
;
239 rbd_group_image_state_t state
;
240 } rbd_group_image_info_t
;
248 RBD_GROUP_SNAP_STATE_INCOMPLETE
,
249 RBD_GROUP_SNAP_STATE_COMPLETE
250 } rbd_group_snap_state_t
;
254 rbd_group_snap_state_t state
;
255 } rbd_group_snap_info_t
;
260 char *group_snap_name
;
261 } rbd_snap_group_namespace_t
;
264 RBD_SNAP_MIRROR_STATE_PRIMARY
,
265 RBD_SNAP_MIRROR_STATE_PRIMARY_DEMOTED
,
266 RBD_SNAP_MIRROR_STATE_NON_PRIMARY
,
267 RBD_SNAP_MIRROR_STATE_NON_PRIMARY_DEMOTED
268 } rbd_snap_mirror_state_t
;
271 rbd_snap_mirror_state_t state
;
272 size_t mirror_peer_uuids_count
;
273 char *mirror_peer_uuids
;
275 char *primary_mirror_uuid
;
276 uint64_t primary_snap_id
;
277 uint64_t last_copied_object_number
;
278 } rbd_snap_mirror_namespace_t
;
281 RBD_LOCK_MODE_EXCLUSIVE
= 0,
282 RBD_LOCK_MODE_SHARED
= 1,
285 CEPH_RBD_API
void rbd_version(int *major
, int *minor
, int *extra
);
289 RBD_IMAGE_OPTION_FORMAT
= 0,
290 RBD_IMAGE_OPTION_FEATURES
= 1,
291 RBD_IMAGE_OPTION_ORDER
= 2,
292 RBD_IMAGE_OPTION_STRIPE_UNIT
= 3,
293 RBD_IMAGE_OPTION_STRIPE_COUNT
= 4,
294 RBD_IMAGE_OPTION_JOURNAL_ORDER
= 5,
295 RBD_IMAGE_OPTION_JOURNAL_SPLAY_WIDTH
= 6,
296 RBD_IMAGE_OPTION_JOURNAL_POOL
= 7,
297 RBD_IMAGE_OPTION_FEATURES_SET
= 8,
298 RBD_IMAGE_OPTION_FEATURES_CLEAR
= 9,
299 RBD_IMAGE_OPTION_DATA_POOL
= 10,
300 RBD_IMAGE_OPTION_FLATTEN
= 11,
301 RBD_IMAGE_OPTION_CLONE_FORMAT
= 12,
302 RBD_IMAGE_OPTION_MIRROR_IMAGE_MODE
= 13,
306 RBD_TRASH_IMAGE_SOURCE_USER
= 0,
307 RBD_TRASH_IMAGE_SOURCE_MIRRORING
= 1,
308 RBD_TRASH_IMAGE_SOURCE_MIGRATION
= 2,
309 RBD_TRASH_IMAGE_SOURCE_REMOVING
= 3,
310 RBD_TRASH_IMAGE_SOURCE_USER_PARENT
= 4,
311 } rbd_trash_image_source_t
;
316 rbd_trash_image_source_t source
;
317 time_t deletion_time
;
318 time_t deferment_end_time
;
319 } rbd_trash_image_info_t
;
325 } rbd_image_watcher_t
;
328 RBD_IMAGE_MIGRATION_STATE_UNKNOWN
= -1,
329 RBD_IMAGE_MIGRATION_STATE_ERROR
= 0,
330 RBD_IMAGE_MIGRATION_STATE_PREPARING
= 1,
331 RBD_IMAGE_MIGRATION_STATE_PREPARED
= 2,
332 RBD_IMAGE_MIGRATION_STATE_EXECUTING
= 3,
333 RBD_IMAGE_MIGRATION_STATE_EXECUTED
= 4,
334 RBD_IMAGE_MIGRATION_STATE_ABORTING
= 5,
335 } rbd_image_migration_state_t
;
338 int64_t source_pool_id
;
339 char *source_pool_namespace
;
340 char *source_image_name
;
341 char *source_image_id
;
342 int64_t dest_pool_id
;
343 char *dest_pool_namespace
;
344 char *dest_image_name
;
346 rbd_image_migration_state_t state
;
347 char *state_description
;
348 } rbd_image_migration_status_t
;
351 RBD_CONFIG_SOURCE_CONFIG
= 0,
352 RBD_CONFIG_SOURCE_POOL
= 1,
353 RBD_CONFIG_SOURCE_IMAGE
= 2,
354 } rbd_config_source_t
;
359 rbd_config_source_t source
;
360 } rbd_config_option_t
;
363 RBD_POOL_STAT_OPTION_IMAGES
,
364 RBD_POOL_STAT_OPTION_IMAGE_PROVISIONED_BYTES
,
365 RBD_POOL_STAT_OPTION_IMAGE_MAX_PROVISIONED_BYTES
,
366 RBD_POOL_STAT_OPTION_IMAGE_SNAPSHOTS
,
367 RBD_POOL_STAT_OPTION_TRASH_IMAGES
,
368 RBD_POOL_STAT_OPTION_TRASH_PROVISIONED_BYTES
,
369 RBD_POOL_STAT_OPTION_TRASH_MAX_PROVISIONED_BYTES
,
370 RBD_POOL_STAT_OPTION_TRASH_SNAPSHOTS
371 } rbd_pool_stat_option_t
;
373 /* rbd_write_zeroes / rbd_aio_write_zeroes flags */
375 RBD_WRITE_ZEROES_FLAG_THICK_PROVISION
= (1U<<0), /* fully allocated zeroed extent */
379 RBD_ENCRYPTION_FORMAT_LUKS1
= 0,
380 RBD_ENCRYPTION_FORMAT_LUKS2
= 1,
381 RBD_ENCRYPTION_FORMAT_LUKS
= 2
382 } rbd_encryption_format_t
;
385 RBD_ENCRYPTION_ALGORITHM_AES128
= 0,
386 RBD_ENCRYPTION_ALGORITHM_AES256
= 1
387 } rbd_encryption_algorithm_t
;
389 typedef void *rbd_encryption_options_t
;
392 rbd_encryption_format_t format
;
393 rbd_encryption_options_t opts
;
395 } rbd_encryption_spec_t
;
398 rbd_encryption_algorithm_t alg
;
399 const char* passphrase
;
400 size_t passphrase_size
;
401 } rbd_encryption_luks1_format_options_t
;
404 rbd_encryption_algorithm_t alg
;
405 const char* passphrase
;
406 size_t passphrase_size
;
407 } rbd_encryption_luks2_format_options_t
;
410 const char* passphrase
;
411 size_t passphrase_size
;
412 } rbd_encryption_luks_format_options_t
;
414 CEPH_RBD_API
void rbd_image_options_create(rbd_image_options_t
* opts
);
415 CEPH_RBD_API
void rbd_image_options_destroy(rbd_image_options_t opts
);
416 CEPH_RBD_API
int rbd_image_options_set_string(rbd_image_options_t opts
,
417 int optname
, const char* optval
);
418 CEPH_RBD_API
int rbd_image_options_set_uint64(rbd_image_options_t opts
,
419 int optname
, uint64_t optval
);
420 CEPH_RBD_API
int rbd_image_options_get_string(rbd_image_options_t opts
,
421 int optname
, char* optval
,
423 CEPH_RBD_API
int rbd_image_options_get_uint64(rbd_image_options_t opts
,
424 int optname
, uint64_t* optval
);
425 CEPH_RBD_API
int rbd_image_options_is_set(rbd_image_options_t opts
,
426 int optname
, bool* is_set
);
427 CEPH_RBD_API
int rbd_image_options_unset(rbd_image_options_t opts
, int optname
);
428 CEPH_RBD_API
void rbd_image_options_clear(rbd_image_options_t opts
);
429 CEPH_RBD_API
int rbd_image_options_is_empty(rbd_image_options_t opts
);
432 CEPH_RBD_API
void rbd_image_spec_cleanup(rbd_image_spec_t
*image
);
433 CEPH_RBD_API
void rbd_image_spec_list_cleanup(rbd_image_spec_t
*images
,
435 CEPH_RBD_API
void rbd_linked_image_spec_cleanup(rbd_linked_image_spec_t
*image
);
436 CEPH_RBD_API
void rbd_linked_image_spec_list_cleanup(
437 rbd_linked_image_spec_t
*images
, size_t num_images
);
438 CEPH_RBD_API
void rbd_snap_spec_cleanup(rbd_snap_spec_t
*snap
);
441 CEPH_RBD_API
int rbd_list(rados_ioctx_t io
, char *names
, size_t *size
)
443 CEPH_RBD_API
int rbd_list2(rados_ioctx_t io
, rbd_image_spec_t
* images
,
446 CEPH_RBD_API
int rbd_create(rados_ioctx_t io
, const char *name
, uint64_t size
,
448 CEPH_RBD_API
int rbd_create2(rados_ioctx_t io
, const char *name
, uint64_t size
,
449 uint64_t features
, int *order
);
451 * create new rbd image
453 * The stripe_unit must be a factor of the object size (1 << order).
454 * The stripe_count can be one (no intra-object striping) or greater
455 * than one. The RBD_FEATURE_STRIPINGV2 must be specified if the
456 * stripe_unit != the object size and the stripe_count is != 1.
459 * @param name image name
460 * @param size image size in bytes
461 * @param features initial feature bits
462 * @param order object/block size, as a power of two (object size == 1 << order)
463 * @param stripe_unit stripe unit size, in bytes.
464 * @param stripe_count number of objects to stripe over before looping
465 * @return 0 on success, or negative error code
467 CEPH_RBD_API
int rbd_create3(rados_ioctx_t io
, const char *name
, uint64_t size
,
468 uint64_t features
, int *order
,
469 uint64_t stripe_unit
, uint64_t stripe_count
);
470 CEPH_RBD_API
int rbd_create4(rados_ioctx_t io
, const char *name
, uint64_t size
,
471 rbd_image_options_t opts
);
472 CEPH_RBD_API
int rbd_clone(rados_ioctx_t p_ioctx
, const char *p_name
,
473 const char *p_snapname
, rados_ioctx_t c_ioctx
,
474 const char *c_name
, uint64_t features
, int *c_order
);
475 CEPH_RBD_API
int rbd_clone2(rados_ioctx_t p_ioctx
, const char *p_name
,
476 const char *p_snapname
, rados_ioctx_t c_ioctx
,
477 const char *c_name
, uint64_t features
, int *c_order
,
478 uint64_t stripe_unit
, int stripe_count
);
479 CEPH_RBD_API
int rbd_clone3(rados_ioctx_t p_ioctx
, const char *p_name
,
480 const char *p_snapname
, rados_ioctx_t c_ioctx
,
481 const char *c_name
, rbd_image_options_t c_opts
);
482 CEPH_RBD_API
int rbd_remove(rados_ioctx_t io
, const char *name
);
483 CEPH_RBD_API
int rbd_remove_with_progress(rados_ioctx_t io
, const char *name
,
484 librbd_progress_fn_t cb
,
486 CEPH_RBD_API
int rbd_rename(rados_ioctx_t src_io_ctx
, const char *srcname
,
487 const char *destname
);
489 CEPH_RBD_API
int rbd_trash_move(rados_ioctx_t io
, const char *name
,
491 CEPH_RBD_API
int rbd_trash_get(rados_ioctx_t io
, const char *id
,
492 rbd_trash_image_info_t
*info
);
493 CEPH_RBD_API
void rbd_trash_get_cleanup(rbd_trash_image_info_t
*info
);
494 CEPH_RBD_API
int rbd_trash_list(rados_ioctx_t io
,
495 rbd_trash_image_info_t
*trash_entries
,
496 size_t *num_entries
);
497 CEPH_RBD_API
void rbd_trash_list_cleanup(rbd_trash_image_info_t
*trash_entries
,
499 CEPH_RBD_API
int rbd_trash_purge(rados_ioctx_t io
, time_t expire_ts
, float threshold
);
500 CEPH_RBD_API
int rbd_trash_purge_with_progress(rados_ioctx_t io
, time_t expire_ts
,
501 float threshold
, librbd_progress_fn_t cb
,
503 CEPH_RBD_API
int rbd_trash_remove(rados_ioctx_t io
, const char *id
, bool force
);
504 CEPH_RBD_API
int rbd_trash_remove_with_progress(rados_ioctx_t io
,
507 librbd_progress_fn_t cb
,
509 CEPH_RBD_API
int rbd_trash_restore(rados_ioctx_t io
, const char *id
,
513 CEPH_RBD_API
int rbd_migration_prepare(rados_ioctx_t ioctx
,
514 const char *image_name
,
515 rados_ioctx_t dest_ioctx
,
516 const char *dest_image_name
,
517 rbd_image_options_t opts
);
518 CEPH_RBD_API
int rbd_migration_prepare_import(
519 const char *source_spec
, rados_ioctx_t dest_ioctx
,
520 const char *dest_image_name
, rbd_image_options_t opts
);
521 CEPH_RBD_API
int rbd_migration_execute(rados_ioctx_t ioctx
,
522 const char *image_name
);
523 CEPH_RBD_API
int rbd_migration_execute_with_progress(rados_ioctx_t ioctx
,
524 const char *image_name
,
525 librbd_progress_fn_t cb
,
527 CEPH_RBD_API
int rbd_migration_abort(rados_ioctx_t ioctx
,
528 const char *image_name
);
529 CEPH_RBD_API
int rbd_migration_abort_with_progress(rados_ioctx_t ioctx
,
530 const char *image_name
,
531 librbd_progress_fn_t cb
,
533 CEPH_RBD_API
int rbd_migration_commit(rados_ioctx_t ioctx
,
534 const char *image_name
);
535 CEPH_RBD_API
int rbd_migration_commit_with_progress(rados_ioctx_t ioctx
,
536 const char *image_name
,
537 librbd_progress_fn_t cb
,
539 CEPH_RBD_API
int rbd_migration_status(rados_ioctx_t ioctx
,
540 const char *image_name
,
541 rbd_image_migration_status_t
*status
,
543 CEPH_RBD_API
void rbd_migration_status_cleanup(
544 rbd_image_migration_status_t
*status
);
547 CEPH_RBD_API
int rbd_mirror_site_name_get(rados_t cluster
,
548 char *name
, size_t *max_len
);
549 CEPH_RBD_API
int rbd_mirror_site_name_set(rados_t cluster
,
552 CEPH_RBD_API
int rbd_mirror_mode_get(rados_ioctx_t io_ctx
,
553 rbd_mirror_mode_t
*mirror_mode
);
554 CEPH_RBD_API
int rbd_mirror_mode_set(rados_ioctx_t io_ctx
,
555 rbd_mirror_mode_t mirror_mode
);
557 CEPH_RBD_API
int rbd_mirror_uuid_get(rados_ioctx_t io_ctx
,
558 char *uuid
, size_t *max_len
);
560 CEPH_RBD_API
int rbd_mirror_peer_bootstrap_create(
561 rados_ioctx_t io_ctx
, char *token
, size_t *max_len
);
562 CEPH_RBD_API
int rbd_mirror_peer_bootstrap_import(
563 rados_ioctx_t io_ctx
, rbd_mirror_peer_direction_t direction
,
566 CEPH_RBD_API
int rbd_mirror_peer_site_add(
567 rados_ioctx_t io_ctx
, char *uuid
, size_t uuid_max_length
,
568 rbd_mirror_peer_direction_t direction
, const char *site_name
,
569 const char *client_name
);
570 CEPH_RBD_API
int rbd_mirror_peer_site_set_name(
571 rados_ioctx_t io_ctx
, const char *uuid
, const char *site_name
);
572 CEPH_RBD_API
int rbd_mirror_peer_site_set_client_name(
573 rados_ioctx_t io_ctx
, const char *uuid
, const char *client_name
);
574 CEPH_RBD_API
int rbd_mirror_peer_site_set_direction(
575 rados_ioctx_t io_ctx
, const char *uuid
,
576 rbd_mirror_peer_direction_t direction
);
577 CEPH_RBD_API
int rbd_mirror_peer_site_remove(
578 rados_ioctx_t io_ctx
, const char *uuid
);
579 CEPH_RBD_API
int rbd_mirror_peer_site_list(
580 rados_ioctx_t io_ctx
, rbd_mirror_peer_site_t
*peers
, int *max_peers
);
581 CEPH_RBD_API
void rbd_mirror_peer_site_list_cleanup(
582 rbd_mirror_peer_site_t
*peers
, int max_peers
);
583 CEPH_RBD_API
int rbd_mirror_peer_site_get_attributes(
584 rados_ioctx_t p
, const char *uuid
, char *keys
, size_t *max_key_len
,
585 char *values
, size_t *max_value_len
, size_t *key_value_count
);
586 CEPH_RBD_API
int rbd_mirror_peer_site_set_attributes(
587 rados_ioctx_t p
, const char *uuid
, const char *keys
, const char *values
,
588 size_t key_value_count
);
590 CEPH_RBD_API
int rbd_mirror_image_global_status_list(
591 rados_ioctx_t io_ctx
, const char *start_id
, size_t max
, char **image_ids
,
592 rbd_mirror_image_global_status_t
*images
, size_t *len
);
593 CEPH_RBD_API
void rbd_mirror_image_global_status_list_cleanup(
594 char **image_ids
, rbd_mirror_image_global_status_t
*images
, size_t len
);
596 /* rbd_mirror_peer_ commands are deprecated to rbd_mirror_peer_site_
598 CEPH_RBD_API
int rbd_mirror_peer_add(
599 rados_ioctx_t io_ctx
, char *uuid
, size_t uuid_max_length
,
600 const char *cluster_name
, const char *client_name
)
602 CEPH_RBD_API
int rbd_mirror_peer_remove(
603 rados_ioctx_t io_ctx
, const char *uuid
)
605 CEPH_RBD_API
int rbd_mirror_peer_list(
606 rados_ioctx_t io_ctx
, rbd_mirror_peer_t
*peers
, int *max_peers
)
608 CEPH_RBD_API
void rbd_mirror_peer_list_cleanup(
609 rbd_mirror_peer_t
*peers
, int max_peers
)
611 CEPH_RBD_API
int rbd_mirror_peer_set_client(
612 rados_ioctx_t io_ctx
, const char *uuid
, const char *client_name
)
614 CEPH_RBD_API
int rbd_mirror_peer_set_cluster(
615 rados_ioctx_t io_ctx
, const char *uuid
, const char *cluster_name
)
617 CEPH_RBD_API
int rbd_mirror_peer_get_attributes(
618 rados_ioctx_t p
, const char *uuid
, char *keys
, size_t *max_key_len
,
619 char *values
, size_t *max_value_len
, size_t *key_value_count
)
621 CEPH_RBD_API
int rbd_mirror_peer_set_attributes(
622 rados_ioctx_t p
, const char *uuid
, const char *keys
, const char *values
,
623 size_t key_value_count
)
626 /* rbd_mirror_image_status_list_ commands are deprecard to
627 * rbd_mirror_image_global_status_list_ commands */
629 CEPH_RBD_API
int rbd_mirror_image_status_list(
630 rados_ioctx_t io_ctx
, const char *start_id
, size_t max
, char **image_ids
,
631 rbd_mirror_image_status_t
*images
, size_t *len
)
633 CEPH_RBD_API
void rbd_mirror_image_status_list_cleanup(
634 char **image_ids
, rbd_mirror_image_status_t
*images
, size_t len
)
637 CEPH_RBD_API
int rbd_mirror_image_status_summary(
638 rados_ioctx_t io_ctx
, rbd_mirror_image_status_state_t
*states
, int *counts
,
641 CEPH_RBD_API
int rbd_mirror_image_instance_id_list(rados_ioctx_t io_ctx
,
642 const char *start_id
,
643 size_t max
, char **image_ids
,
646 CEPH_RBD_API
void rbd_mirror_image_instance_id_list_cleanup(char **image_ids
,
649 CEPH_RBD_API
int rbd_mirror_image_info_list(
650 rados_ioctx_t io_ctx
, rbd_mirror_image_mode_t
*mode_filter
,
651 const char *start_id
, size_t max
, char **image_ids
,
652 rbd_mirror_image_mode_t
*mode_entries
,
653 rbd_mirror_image_info_t
*info_entries
, size_t *num_entries
);
654 CEPH_RBD_API
void rbd_mirror_image_info_list_cleanup(
655 char **image_ids
, rbd_mirror_image_info_t
*info_entries
,
659 CEPH_RBD_API
int rbd_pool_metadata_get(rados_ioctx_t io_ctx
, const char *key
,
660 char *value
, size_t *val_len
);
661 CEPH_RBD_API
int rbd_pool_metadata_set(rados_ioctx_t io_ctx
, const char *key
,
663 CEPH_RBD_API
int rbd_pool_metadata_remove(rados_ioctx_t io_ctx
,
665 CEPH_RBD_API
int rbd_pool_metadata_list(rados_ioctx_t io_ctx
, const char *start
,
666 uint64_t max
, char *keys
,
667 size_t *key_len
, char *values
,
670 CEPH_RBD_API
int rbd_config_pool_list(rados_ioctx_t io_ctx
,
671 rbd_config_option_t
*options
,
673 CEPH_RBD_API
void rbd_config_pool_list_cleanup(rbd_config_option_t
*options
,
676 CEPH_RBD_API
int rbd_open(rados_ioctx_t io
, const char *name
,
677 rbd_image_t
*image
, const char *snap_name
);
678 CEPH_RBD_API
int rbd_open_by_id(rados_ioctx_t io
, const char *id
,
679 rbd_image_t
*image
, const char *snap_name
);
681 CEPH_RBD_API
int rbd_aio_open(rados_ioctx_t io
, const char *name
,
682 rbd_image_t
*image
, const char *snap_name
,
684 CEPH_RBD_API
int rbd_aio_open_by_id(rados_ioctx_t io
, const char *id
,
685 rbd_image_t
*image
, const char *snap_name
,
689 * Open an image in read-only mode.
691 * This is intended for use by clients that cannot write to a block
692 * device due to cephx restrictions. There will be no watch
693 * established on the header object, since a watch is a write. This
694 * means the metadata reported about this image (parents, snapshots,
695 * size, etc.) may become stale. This should not be used for
696 * long-running operations, unless you can be sure that one of these
697 * properties changing is safe.
699 * Attempting to write to a read-only image will return -EROFS.
701 * @param io ioctx to determine the pool the image is in
702 * @param name image name
703 * @param image where to store newly opened image handle
704 * @param snap_name name of snapshot to open at, or NULL for no snapshot
705 * @returns 0 on success, negative error code on failure
707 CEPH_RBD_API
int rbd_open_read_only(rados_ioctx_t io
, const char *name
,
708 rbd_image_t
*image
, const char *snap_name
);
709 CEPH_RBD_API
int rbd_open_by_id_read_only(rados_ioctx_t io
, const char *id
,
710 rbd_image_t
*image
, const char *snap_name
);
711 CEPH_RBD_API
int rbd_aio_open_read_only(rados_ioctx_t io
, const char *name
,
712 rbd_image_t
*image
, const char *snap_name
,
714 CEPH_RBD_API
int rbd_aio_open_by_id_read_only(rados_ioctx_t io
, const char *id
,
715 rbd_image_t
*image
, const char *snap_name
,
717 CEPH_RBD_API
int rbd_features_to_string(uint64_t features
, char *str_features
,
719 CEPH_RBD_API
int rbd_features_from_string(const char *str_features
, uint64_t *features
);
720 CEPH_RBD_API
int rbd_close(rbd_image_t image
);
721 CEPH_RBD_API
int rbd_aio_close(rbd_image_t image
, rbd_completion_t c
);
722 CEPH_RBD_API
int rbd_resize(rbd_image_t image
, uint64_t size
);
723 CEPH_RBD_API
int rbd_resize2(rbd_image_t image
, uint64_t size
, bool allow_shrink
,
724 librbd_progress_fn_t cb
, void *cbdata
);
725 CEPH_RBD_API
int rbd_resize_with_progress(rbd_image_t image
, uint64_t size
,
726 librbd_progress_fn_t cb
, void *cbdata
);
727 CEPH_RBD_API
int rbd_stat(rbd_image_t image
, rbd_image_info_t
*info
,
729 CEPH_RBD_API
int rbd_get_old_format(rbd_image_t image
, uint8_t *old
);
730 CEPH_RBD_API
int rbd_get_size(rbd_image_t image
, uint64_t *size
);
731 CEPH_RBD_API
int rbd_get_features(rbd_image_t image
, uint64_t *features
);
732 CEPH_RBD_API
int rbd_update_features(rbd_image_t image
, uint64_t features
,
734 CEPH_RBD_API
int rbd_get_op_features(rbd_image_t image
, uint64_t *op_features
);
735 CEPH_RBD_API
int rbd_get_stripe_unit(rbd_image_t image
, uint64_t *stripe_unit
);
736 CEPH_RBD_API
int rbd_get_stripe_count(rbd_image_t image
,
737 uint64_t *stripe_count
);
739 CEPH_RBD_API
int rbd_get_create_timestamp(rbd_image_t image
,
740 struct timespec
*timestamp
);
741 CEPH_RBD_API
int rbd_get_access_timestamp(rbd_image_t image
,
742 struct timespec
*timestamp
);
743 CEPH_RBD_API
int rbd_get_modify_timestamp(rbd_image_t image
,
744 struct timespec
*timestamp
);
746 CEPH_RBD_API
int rbd_get_overlap(rbd_image_t image
, uint64_t *overlap
);
747 CEPH_RBD_API
int rbd_get_name(rbd_image_t image
, char *name
, size_t *name_len
);
748 CEPH_RBD_API
int rbd_get_id(rbd_image_t image
, char *id
, size_t id_len
);
749 CEPH_RBD_API
int rbd_get_block_name_prefix(rbd_image_t image
,
750 char *prefix
, size_t prefix_len
);
751 CEPH_RBD_API
int64_t rbd_get_data_pool_id(rbd_image_t image
);
753 CEPH_RBD_API
int rbd_get_parent_info(rbd_image_t image
,
754 char *parent_poolname
, size_t ppoolnamelen
,
755 char *parent_name
, size_t pnamelen
,
756 char *parent_snapname
,
759 CEPH_RBD_API
int rbd_get_parent_info2(rbd_image_t image
,
760 char *parent_poolname
,
762 char *parent_name
, size_t pnamelen
,
763 char *parent_id
, size_t pidlen
,
764 char *parent_snapname
,
767 CEPH_RBD_API
int rbd_get_parent(rbd_image_t image
,
768 rbd_linked_image_spec_t
*parent_image
,
769 rbd_snap_spec_t
*parent_snap
);
771 CEPH_RBD_API
int rbd_get_migration_source_spec(rbd_image_t image
,
775 CEPH_RBD_API
int rbd_get_flags(rbd_image_t image
, uint64_t *flags
);
776 CEPH_RBD_API
int rbd_get_group(rbd_image_t image
, rbd_group_info_t
*group_info
,
777 size_t group_info_size
);
778 CEPH_RBD_API
int rbd_set_image_notification(rbd_image_t image
, int fd
, int type
);
780 /* exclusive lock feature */
781 CEPH_RBD_API
int rbd_is_exclusive_lock_owner(rbd_image_t image
, int *is_owner
);
782 CEPH_RBD_API
int rbd_lock_acquire(rbd_image_t image
, rbd_lock_mode_t lock_mode
);
783 CEPH_RBD_API
int rbd_lock_release(rbd_image_t image
);
784 CEPH_RBD_API
int rbd_lock_get_owners(rbd_image_t image
,
785 rbd_lock_mode_t
*lock_mode
,
787 size_t *max_lock_owners
);
788 CEPH_RBD_API
void rbd_lock_get_owners_cleanup(char **lock_owners
,
789 size_t lock_owner_count
);
790 CEPH_RBD_API
int rbd_lock_break(rbd_image_t image
, rbd_lock_mode_t lock_mode
,
791 const char *lock_owner
);
793 /* object map feature */
794 CEPH_RBD_API
int rbd_rebuild_object_map(rbd_image_t image
,
795 librbd_progress_fn_t cb
, void *cbdata
);
797 CEPH_RBD_API
int rbd_copy(rbd_image_t image
, rados_ioctx_t dest_io_ctx
,
798 const char *destname
);
799 CEPH_RBD_API
int rbd_copy2(rbd_image_t src
, rbd_image_t dest
);
800 CEPH_RBD_API
int rbd_copy3(rbd_image_t src
, rados_ioctx_t dest_io_ctx
,
801 const char *destname
, rbd_image_options_t dest_opts
);
802 CEPH_RBD_API
int rbd_copy4(rbd_image_t src
, rados_ioctx_t dest_io_ctx
,
803 const char *destname
, rbd_image_options_t dest_opts
,
805 CEPH_RBD_API
int rbd_copy_with_progress(rbd_image_t image
, rados_ioctx_t dest_p
,
806 const char *destname
,
807 librbd_progress_fn_t cb
, void *cbdata
);
808 CEPH_RBD_API
int rbd_copy_with_progress2(rbd_image_t src
, rbd_image_t dest
,
809 librbd_progress_fn_t cb
, void *cbdata
);
810 CEPH_RBD_API
int rbd_copy_with_progress3(rbd_image_t image
,
811 rados_ioctx_t dest_p
,
812 const char *destname
,
813 rbd_image_options_t dest_opts
,
814 librbd_progress_fn_t cb
, void *cbdata
);
815 CEPH_RBD_API
int rbd_copy_with_progress4(rbd_image_t image
,
816 rados_ioctx_t dest_p
,
817 const char *destname
,
818 rbd_image_options_t dest_opts
,
819 librbd_progress_fn_t cb
, void *cbdata
,
823 CEPH_RBD_API
int rbd_deep_copy(rbd_image_t src
, rados_ioctx_t dest_io_ctx
,
824 const char *destname
,
825 rbd_image_options_t dest_opts
);
826 CEPH_RBD_API
int rbd_deep_copy_with_progress(rbd_image_t image
,
827 rados_ioctx_t dest_io_ctx
,
828 const char *destname
,
829 rbd_image_options_t dest_opts
,
830 librbd_progress_fn_t cb
,
836 * Format the image using the encryption spec specified by
837 * (format, opts, opts_size) tuple.
839 * For a flat (i.e. non-cloned) image, the new encryption is loaded
840 * implicitly, calling rbd_encryption_load() afterwards is not needed.
841 * If existing encryption is already loaded, it is automatically
842 * replaced with the new encryption.
844 * For a cloned image, the new encryption must be loaded explicitly.
845 * Existing encryption (if any) must not be loaded.
847 CEPH_RBD_API
int rbd_encryption_format(rbd_image_t image
,
848 rbd_encryption_format_t format
,
849 rbd_encryption_options_t opts
,
852 * Load the encryption spec specified by (format, opts, opts_size)
853 * tuple for the image and all ancestor images. If an ancestor image
854 * which does not match any encryption format known to librbd is
855 * encountered, it - along with remaining ancestor images - is
856 * interpreted as plaintext.
858 CEPH_RBD_API
int rbd_encryption_load(rbd_image_t image
,
859 rbd_encryption_format_t format
,
860 rbd_encryption_options_t opts
,
863 * Load encryption specs. The first spec in the passed array is
864 * applied to the image itself, the second spec is applied to its
865 * ancestor image, the third spec is applied to the ancestor of
866 * that ancestor image and so on.
868 * If not enough specs are passed, the last spec is reused exactly as
869 * in rbd_encryption_load(). If an ancestor image for which the last
870 * spec is being reused turns out to not match any encryption format
871 * known to librbd, it - along with remaining ancestor images - is
872 * interpreted as plaintext.
874 CEPH_RBD_API
int rbd_encryption_load2(rbd_image_t image
,
875 const rbd_encryption_spec_t
*specs
,
879 CEPH_RBD_API
int rbd_snap_list(rbd_image_t image
, rbd_snap_info_t
*snaps
,
881 CEPH_RBD_API
void rbd_snap_list_end(rbd_snap_info_t
*snaps
);
882 CEPH_RBD_API
int rbd_snap_exists(rbd_image_t image
, const char *snapname
, bool *exists
);
883 CEPH_RBD_API
int rbd_snap_create(rbd_image_t image
, const char *snapname
);
884 CEPH_RBD_API
int rbd_snap_create2(rbd_image_t image
, const char *snap_name
,
885 uint32_t flags
, librbd_progress_fn_t cb
,
887 CEPH_RBD_API
int rbd_snap_remove(rbd_image_t image
, const char *snapname
);
888 CEPH_RBD_API
int rbd_snap_remove2(rbd_image_t image
, const char *snap_name
,
889 uint32_t flags
, librbd_progress_fn_t cb
,
891 CEPH_RBD_API
int rbd_snap_remove_by_id(rbd_image_t image
, uint64_t snap_id
);
892 CEPH_RBD_API
int rbd_snap_rollback(rbd_image_t image
, const char *snapname
);
893 CEPH_RBD_API
int rbd_snap_rollback_with_progress(rbd_image_t image
,
894 const char *snapname
,
895 librbd_progress_fn_t cb
,
897 CEPH_RBD_API
int rbd_snap_rename(rbd_image_t image
, const char *snapname
,
898 const char* dstsnapsname
);
900 * Prevent a snapshot from being deleted until it is unprotected.
902 * @param snap_name which snapshot to protect
903 * @returns 0 on success, negative error code on failure
904 * @returns -EBUSY if snap is already protected
906 CEPH_RBD_API
int rbd_snap_protect(rbd_image_t image
, const char *snap_name
);
908 * Allow a snaphshot to be deleted.
910 * @param snap_name which snapshot to unprotect
911 * @returns 0 on success, negative error code on failure
912 * @returns -EINVAL if snap is not protected
914 CEPH_RBD_API
int rbd_snap_unprotect(rbd_image_t image
, const char *snap_name
);
916 * Determine whether a snapshot is protected.
918 * @param snap_name which snapshot query
919 * @param is_protected where to store the result (0 or 1)
920 * @returns 0 on success, negative error code on failure
922 CEPH_RBD_API
int rbd_snap_is_protected(rbd_image_t image
, const char *snap_name
,
925 * Get the current snapshot limit for an image. If no limit is set,
926 * UINT64_MAX is returned.
928 * @param limit pointer where the limit will be stored on success
929 * @returns 0 on success, negative error code on failure
931 CEPH_RBD_API
int rbd_snap_get_limit(rbd_image_t image
, uint64_t *limit
);
934 * Set a limit for the number of snapshots that may be taken of an image.
936 * @param limit the maximum number of snapshots allowed in the future.
937 * @returns 0 on success, negative error code on failure
939 CEPH_RBD_API
int rbd_snap_set_limit(rbd_image_t image
, uint64_t limit
);
942 * Get the timestamp of a snapshot for an image.
944 * @param snap_id the snap id of a snapshot of input image.
945 * @param timestamp the timestamp of input snapshot.
946 * @returns 0 on success, negative error code on failure
948 CEPH_RBD_API
int rbd_snap_get_timestamp(rbd_image_t image
, uint64_t snap_id
, struct timespec
*timestamp
);
950 CEPH_RBD_API
int rbd_snap_set(rbd_image_t image
, const char *snapname
);
951 CEPH_RBD_API
int rbd_snap_set_by_id(rbd_image_t image
, uint64_t snap_id
);
952 CEPH_RBD_API
int rbd_snap_get_name(rbd_image_t image
, uint64_t snap_id
, char *snapname
, size_t *name_len
);
953 CEPH_RBD_API
int rbd_snap_get_id(rbd_image_t image
, const char *snapname
, uint64_t *snap_id
);
955 CEPH_RBD_API
int rbd_snap_get_namespace_type(rbd_image_t image
,
957 rbd_snap_namespace_type_t
*namespace_type
);
958 CEPH_RBD_API
int rbd_snap_get_group_namespace(rbd_image_t image
,
960 rbd_snap_group_namespace_t
*group_snap
,
961 size_t group_snap_size
);
962 CEPH_RBD_API
int rbd_snap_group_namespace_cleanup(rbd_snap_group_namespace_t
*group_snap
,
963 size_t group_snap_size
);
964 CEPH_RBD_API
int rbd_snap_get_trash_namespace(rbd_image_t image
,
968 CEPH_RBD_API
int rbd_snap_get_mirror_namespace(
969 rbd_image_t image
, uint64_t snap_id
,
970 rbd_snap_mirror_namespace_t
*mirror_snap
, size_t mirror_snap_size
);
971 CEPH_RBD_API
int rbd_snap_mirror_namespace_cleanup(
972 rbd_snap_mirror_namespace_t
*mirror_snap
, size_t mirror_snap_size
);
974 CEPH_RBD_API
int rbd_flatten(rbd_image_t image
);
976 CEPH_RBD_API
int rbd_flatten_with_progress(rbd_image_t image
,
977 librbd_progress_fn_t cb
,
980 CEPH_RBD_API
int rbd_sparsify(rbd_image_t image
, size_t sparse_size
);
982 CEPH_RBD_API
int rbd_sparsify_with_progress(rbd_image_t image
,
984 librbd_progress_fn_t cb
,
988 * List all images that are cloned from the image at the
989 * snapshot that is set via rbd_snap_set().
991 * This iterates over all pools, so it should be run by a user with
992 * read access to all of them. pools_len and images_len are filled in
993 * with the number of bytes put into the pools and images buffers.
995 * If the provided buffers are too short, the required lengths are
996 * still filled in, but the data is not and -ERANGE is returned.
997 * Otherwise, the buffers are filled with the pool and image names
998 * of the children, with a '\0' after each.
1000 * @param image which image (and implicitly snapshot) to list clones of
1001 * @param pools buffer in which to store pool names
1002 * @param pools_len number of bytes in pools buffer
1003 * @param images buffer in which to store image names
1004 * @param images_len number of bytes in images buffer
1005 * @returns number of children on success, negative error code on failure
1006 * @returns -ERANGE if either buffer is too short
1008 CEPH_RBD_API ssize_t
rbd_list_children(rbd_image_t image
, char *pools
,
1009 size_t *pools_len
, char *images
,
1011 CEPH_RBD_DEPRECATED
;
1012 CEPH_RBD_API
int rbd_list_children2(rbd_image_t image
,
1013 rbd_child_info_t
*children
,
1015 CEPH_RBD_DEPRECATED
;
1016 CEPH_RBD_API
void rbd_list_child_cleanup(rbd_child_info_t
*child
)
1017 CEPH_RBD_DEPRECATED
;
1018 CEPH_RBD_API
void rbd_list_children_cleanup(rbd_child_info_t
*children
,
1019 size_t num_children
)
1020 CEPH_RBD_DEPRECATED
;
1022 CEPH_RBD_API
int rbd_list_children3(rbd_image_t image
,
1023 rbd_linked_image_spec_t
*images
,
1024 size_t *max_images
);
1026 CEPH_RBD_API
int rbd_list_descendants(rbd_image_t image
,
1027 rbd_linked_image_spec_t
*images
,
1028 size_t *max_images
);
1031 * @defgroup librbd_h_locking Advisory Locking
1033 * An rbd image may be locking exclusively, or shared, to facilitate
1034 * e.g. live migration where the image may be open in two places at once.
1035 * These locks are intended to guard against more than one client
1036 * writing to an image without coordination. They don't need to
1037 * be used for snapshots, since snapshots are read-only.
1039 * Currently locks only guard against locks being acquired.
1040 * They do not prevent anything else.
1042 * A locker is identified by the internal rados client id of the
1043 * holder and a user-defined cookie. This (client id, cookie) pair
1044 * must be unique for each locker.
1046 * A shared lock also has a user-defined tag associated with it. Each
1047 * additional shared lock must specify the same tag or lock
1048 * acquisition will fail. This can be used by e.g. groups of hosts
1049 * using a clustered filesystem on top of an rbd image to make sure
1050 * they're accessing the correct image.
1055 * List clients that have locked the image and information about the lock.
1057 * The number of bytes required in each buffer is put in the
1058 * corresponding size out parameter. If any of the provided buffers
1059 * are too short, -ERANGE is returned after these sizes are filled in.
1061 * @param exclusive where to store whether the lock is exclusive (1) or shared (0)
1062 * @param tag where to store the tag associated with the image
1063 * @param tag_len number of bytes in tag buffer
1064 * @param clients buffer in which locker clients are stored, separated by '\0'
1065 * @param clients_len number of bytes in the clients buffer
1066 * @param cookies buffer in which locker cookies are stored, separated by '\0'
1067 * @param cookies_len number of bytes in the cookies buffer
1068 * @param addrs buffer in which locker addresses are stored, separated by '\0'
1069 * @param addrs_len number of bytes in the clients buffer
1070 * @returns number of lockers on success, negative error code on failure
1071 * @returns -ERANGE if any of the buffers are too short
1073 CEPH_RBD_API ssize_t
rbd_list_lockers(rbd_image_t image
, int *exclusive
,
1074 char *tag
, size_t *tag_len
,
1075 char *clients
, size_t *clients_len
,
1076 char *cookies
, size_t *cookies_len
,
1077 char *addrs
, size_t *addrs_len
);
1080 * Take an exclusive lock on the image.
1082 * @param image the image to lock
1083 * @param cookie user-defined identifier for this instance of the lock
1084 * @returns 0 on success, negative error code on failure
1085 * @returns -EBUSY if the lock is already held by another (client, cookie) pair
1086 * @returns -EEXIST if the lock is already held by the same (client, cookie) pair
1088 CEPH_RBD_API
int rbd_lock_exclusive(rbd_image_t image
, const char *cookie
);
1091 * Take a shared lock on the image.
1093 * Other clients may also take a shared lock, as lock as they use the
1096 * @param image the image to lock
1097 * @param cookie user-defined identifier for this instance of the lock
1098 * @param tag user-defined identifier for this shared use of the lock
1099 * @returns 0 on success, negative error code on failure
1100 * @returns -EBUSY if the lock is already held by another (client, cookie) pair
1101 * @returns -EEXIST if the lock is already held by the same (client, cookie) pair
1103 CEPH_RBD_API
int rbd_lock_shared(rbd_image_t image
, const char *cookie
,
1107 * Release a shared or exclusive lock on the image.
1109 * @param image the image to unlock
1110 * @param cookie user-defined identifier for the instance of the lock
1111 * @returns 0 on success, negative error code on failure
1112 * @returns -ENOENT if the lock is not held by the specified (client, cookie) pair
1114 CEPH_RBD_API
int rbd_unlock(rbd_image_t image
, const char *cookie
);
1117 * Release a shared or exclusive lock that was taken by the specified client.
1119 * @param image the image to unlock
1120 * @param client the entity holding the lock (as given by rbd_list_lockers())
1121 * @param cookie user-defined identifier for the instance of the lock to break
1122 * @returns 0 on success, negative error code on failure
1123 * @returns -ENOENT if the lock is not held by the specified (client, cookie) pair
1125 CEPH_RBD_API
int rbd_break_lock(rbd_image_t image
, const char *client
,
1126 const char *cookie
);
1131 CEPH_RBD_API ssize_t
rbd_read(rbd_image_t image
, uint64_t ofs
, size_t len
,
1134 * @param op_flags: see librados.h constants beginning with LIBRADOS_OP_FLAG
1136 CEPH_RBD_API ssize_t
rbd_read2(rbd_image_t image
, uint64_t ofs
, size_t len
,
1137 char *buf
, int op_flags
);
1138 /* DEPRECATED; use rbd_read_iterate2 */
1139 CEPH_RBD_API
int64_t rbd_read_iterate(rbd_image_t image
, uint64_t ofs
, size_t len
,
1140 int (*cb
)(uint64_t, size_t, const char *, void *),
1144 * iterate read over an image
1146 * Reads each region of the image and calls the callback. If the
1147 * buffer pointer passed to the callback is NULL, the given extent is
1148 * defined to be zeros (a hole). Normally the granularity for the
1149 * callback is the image stripe size.
1151 * @param image image to read
1152 * @param ofs offset to start from
1153 * @param len bytes of source image to cover
1154 * @param cb callback for each region
1155 * @returns 0 success, error otherwise
1157 CEPH_RBD_API
int rbd_read_iterate2(rbd_image_t image
, uint64_t ofs
, uint64_t len
,
1158 int (*cb
)(uint64_t, size_t, const char *, void *),
1161 * get difference between two versions of an image
1163 * This will return the differences between two versions of an image
1164 * via a callback, which gets the offset and length and a flag
1165 * indicating whether the extent exists (1), or is known/defined to
1166 * be zeros (a hole, 0). If the source snapshot name is NULL, we
1167 * interpret that as the beginning of time and return all allocated
1168 * regions of the image. The end version is whatever is currently
1169 * selected for the image handle (either a snapshot or the writeable
1172 * @param fromsnapname start snapshot name, or NULL
1173 * @param ofs start offset
1174 * @param len len in bytes of region to report on
1175 * @param include_parent 1 if full history diff should include parent
1176 * @param whole_object 1 if diff extents should cover whole object
1177 * @param cb callback to call for each allocated region
1178 * @param arg argument to pass to the callback
1179 * @returns 0 on success, or negative error code on error
1181 CEPH_RBD_API
int rbd_diff_iterate(rbd_image_t image
,
1182 const char *fromsnapname
,
1183 uint64_t ofs
, uint64_t len
,
1184 int (*cb
)(uint64_t, size_t, int, void *),
1186 CEPH_RBD_API
int rbd_diff_iterate2(rbd_image_t image
,
1187 const char *fromsnapname
,
1188 uint64_t ofs
, uint64_t len
,
1189 uint8_t include_parent
, uint8_t whole_object
,
1190 int (*cb
)(uint64_t, size_t, int, void *),
1192 CEPH_RBD_API ssize_t
rbd_write(rbd_image_t image
, uint64_t ofs
, size_t len
,
1195 * @param op_flags: see librados.h constants beginning with LIBRADOS_OP_FLAG
1197 CEPH_RBD_API ssize_t
rbd_write2(rbd_image_t image
, uint64_t ofs
, size_t len
,
1198 const char *buf
, int op_flags
);
1199 CEPH_RBD_API
int rbd_discard(rbd_image_t image
, uint64_t ofs
, uint64_t len
);
1200 CEPH_RBD_API ssize_t
rbd_writesame(rbd_image_t image
, uint64_t ofs
, size_t len
,
1201 const char *buf
, size_t data_len
,
1203 CEPH_RBD_API ssize_t
rbd_write_zeroes(rbd_image_t image
, uint64_t ofs
,
1204 size_t len
, int zero_flags
,
1206 CEPH_RBD_API ssize_t
rbd_compare_and_write(rbd_image_t image
, uint64_t ofs
,
1207 size_t len
, const char *cmp_buf
,
1209 uint64_t *mismatch_off
,
1212 CEPH_RBD_API
int rbd_aio_write(rbd_image_t image
, uint64_t off
, size_t len
,
1213 const char *buf
, rbd_completion_t c
);
1216 * @param op_flags: see librados.h constants beginning with LIBRADOS_OP_FLAG
1218 CEPH_RBD_API
int rbd_aio_write2(rbd_image_t image
, uint64_t off
, size_t len
,
1219 const char *buf
, rbd_completion_t c
,
1221 CEPH_RBD_API
int rbd_aio_writev(rbd_image_t image
, const struct iovec
*iov
,
1222 int iovcnt
, uint64_t off
, rbd_completion_t c
);
1223 CEPH_RBD_API
int rbd_aio_read(rbd_image_t image
, uint64_t off
, size_t len
,
1224 char *buf
, rbd_completion_t c
);
1226 * @param op_flags: see librados.h constants beginning with LIBRADOS_OP_FLAG
1228 CEPH_RBD_API
int rbd_aio_read2(rbd_image_t image
, uint64_t off
, size_t len
,
1229 char *buf
, rbd_completion_t c
, int op_flags
);
1230 CEPH_RBD_API
int rbd_aio_readv(rbd_image_t image
, const struct iovec
*iov
,
1231 int iovcnt
, uint64_t off
, rbd_completion_t c
);
1232 CEPH_RBD_API
int rbd_aio_discard(rbd_image_t image
, uint64_t off
, uint64_t len
,
1233 rbd_completion_t c
);
1234 CEPH_RBD_API
int rbd_aio_writesame(rbd_image_t image
, uint64_t off
, size_t len
,
1235 const char *buf
, size_t data_len
,
1236 rbd_completion_t c
, int op_flags
);
1237 CEPH_RBD_API
int rbd_aio_write_zeroes(rbd_image_t image
, uint64_t off
,
1238 size_t len
, rbd_completion_t c
,
1239 int zero_flags
, int op_flags
);
1240 CEPH_RBD_API ssize_t
rbd_aio_compare_and_write(rbd_image_t image
,
1241 uint64_t off
, size_t len
,
1242 const char *cmp_buf
,
1245 uint64_t *mismatch_off
,
1247 CEPH_RBD_API ssize_t
rbd_aio_compare_and_writev(rbd_image_t image
,
1249 const struct iovec
*cmp_iov
,
1251 const struct iovec
*iov
,
1254 uint64_t *mismatch_off
,
1257 CEPH_RBD_API
int rbd_aio_create_completion(void *cb_arg
,
1258 rbd_callback_t complete_cb
,
1259 rbd_completion_t
*c
);
1260 CEPH_RBD_API
int rbd_aio_is_complete(rbd_completion_t c
);
1261 CEPH_RBD_API
int rbd_aio_wait_for_complete(rbd_completion_t c
);
1262 CEPH_RBD_API ssize_t
rbd_aio_get_return_value(rbd_completion_t c
);
1263 CEPH_RBD_API
void *rbd_aio_get_arg(rbd_completion_t c
);
1264 CEPH_RBD_API
void rbd_aio_release(rbd_completion_t c
);
1265 CEPH_RBD_API
int rbd_flush(rbd_image_t image
);
1267 * Start a flush if caching is enabled. Get a callback when
1268 * the currently pending writes are on disk.
1270 * @param image the image to flush writes to
1271 * @param c what to call when flushing is complete
1272 * @returns 0 on success, negative error code on failure
1274 CEPH_RBD_API
int rbd_aio_flush(rbd_image_t image
, rbd_completion_t c
);
1277 * Drop any cached data for an image
1279 * @param image the image to invalidate cached data for
1280 * @returns 0 on success, negative error code on failure
1282 CEPH_RBD_API
int rbd_invalidate_cache(rbd_image_t image
);
1284 CEPH_RBD_API
int rbd_poll_io_events(rbd_image_t image
, rbd_completion_t
*comps
, int numcomp
);
1286 CEPH_RBD_API
int rbd_metadata_get(rbd_image_t image
, const char *key
, char *value
, size_t *val_len
);
1287 CEPH_RBD_API
int rbd_metadata_set(rbd_image_t image
, const char *key
, const char *value
);
1288 CEPH_RBD_API
int rbd_metadata_remove(rbd_image_t image
, const char *key
);
1290 * List all metadatas associated with this image.
1292 * This iterates over all metadatas, key_len and val_len are filled in
1293 * with the number of bytes put into the keys and values buffers.
1295 * If the provided buffers are too short, the required lengths are
1296 * still filled in, but the data is not and -ERANGE is returned.
1297 * Otherwise, the buffers are filled with the keys and values
1298 * of the image, with a '\0' after each.
1300 * @param image which image (and implicitly snapshot) to list clones of
1301 * @param start_after which name to begin listing after
1302 * (use the empty string to start at the beginning)
1303 * @param max the maximum number of names to lis(if 0 means no limit)
1304 * @param keys buffer in which to store pool names
1305 * @param keys_len number of bytes in pools buffer
1306 * @param values buffer in which to store image names
1307 * @param vals_len number of bytes in images buffer
1308 * @returns number of children on success, negative error code on failure
1309 * @returns -ERANGE if either buffer is too short
1311 CEPH_RBD_API
int rbd_metadata_list(rbd_image_t image
, const char *start
, uint64_t max
,
1312 char *keys
, size_t *key_len
, char *values
, size_t *vals_len
);
1314 // RBD image mirroring support functions
1315 CEPH_RBD_API
int rbd_mirror_image_enable(rbd_image_t image
) CEPH_RBD_DEPRECATED
;
1316 CEPH_RBD_API
int rbd_mirror_image_enable2(rbd_image_t image
,
1317 rbd_mirror_image_mode_t mode
);
1318 CEPH_RBD_API
int rbd_mirror_image_disable(rbd_image_t image
, bool force
);
1319 CEPH_RBD_API
int rbd_mirror_image_promote(rbd_image_t image
, bool force
);
1320 CEPH_RBD_API
int rbd_mirror_image_demote(rbd_image_t image
);
1321 CEPH_RBD_API
int rbd_mirror_image_resync(rbd_image_t image
);
1322 CEPH_RBD_API
int rbd_mirror_image_create_snapshot(rbd_image_t image
,
1324 CEPH_RBD_API
int rbd_mirror_image_create_snapshot2(rbd_image_t image
,
1327 CEPH_RBD_API
int rbd_mirror_image_get_info(rbd_image_t image
,
1328 rbd_mirror_image_info_t
*mirror_image_info
,
1330 CEPH_RBD_API
void rbd_mirror_image_get_info_cleanup(
1331 rbd_mirror_image_info_t
*mirror_image_info
);
1332 CEPH_RBD_API
int rbd_mirror_image_get_mode(rbd_image_t image
,
1333 rbd_mirror_image_mode_t
*mode
);
1335 CEPH_RBD_API
int rbd_mirror_image_get_global_status(
1337 rbd_mirror_image_global_status_t
*mirror_image_global_status
,
1338 size_t status_size
);
1339 CEPH_RBD_API
void rbd_mirror_image_global_status_cleanup(
1340 rbd_mirror_image_global_status_t
*mirror_image_global_status
);
1342 CEPH_RBD_API
int rbd_mirror_image_get_status(
1343 rbd_image_t image
, rbd_mirror_image_status_t
*mirror_image_status
,
1345 CEPH_RBD_DEPRECATED
;
1347 CEPH_RBD_API
int rbd_mirror_image_get_instance_id(rbd_image_t image
,
1349 size_t *id_max_length
);
1350 CEPH_RBD_API
int rbd_aio_mirror_image_promote(rbd_image_t image
, bool force
,
1351 rbd_completion_t c
);
1352 CEPH_RBD_API
int rbd_aio_mirror_image_demote(rbd_image_t image
,
1353 rbd_completion_t c
);
1354 CEPH_RBD_API
int rbd_aio_mirror_image_get_info(rbd_image_t image
,
1355 rbd_mirror_image_info_t
*mirror_image_info
,
1357 rbd_completion_t c
);
1358 CEPH_RBD_API
int rbd_aio_mirror_image_get_mode(rbd_image_t image
,
1359 rbd_mirror_image_mode_t
*mode
,
1360 rbd_completion_t c
);
1362 CEPH_RBD_API
int rbd_aio_mirror_image_get_global_status(
1364 rbd_mirror_image_global_status_t
*mirror_global_image_status
,
1365 size_t status_size
, rbd_completion_t c
);
1366 CEPH_RBD_API
int rbd_aio_mirror_image_get_status(
1367 rbd_image_t image
, rbd_mirror_image_status_t
*mirror_image_status
,
1368 size_t status_size
, rbd_completion_t c
)
1369 CEPH_RBD_DEPRECATED
;
1371 CEPH_RBD_API
int rbd_aio_mirror_image_create_snapshot(rbd_image_t image
,
1374 rbd_completion_t c
);
1376 // RBD groups support functions
1377 CEPH_RBD_API
int rbd_group_create(rados_ioctx_t p
, const char *name
);
1378 CEPH_RBD_API
int rbd_group_remove(rados_ioctx_t p
, const char *name
);
1379 CEPH_RBD_API
int rbd_group_list(rados_ioctx_t p
, char *names
, size_t *size
);
1380 CEPH_RBD_API
int rbd_group_rename(rados_ioctx_t p
, const char *src_name
,
1381 const char *dest_name
);
1382 CEPH_RBD_API
int rbd_group_info_cleanup(rbd_group_info_t
*group_info
,
1383 size_t group_info_size
);
1386 * Register an image metadata change watcher.
1388 * @param image the image to watch
1389 * @param handle where to store the internal id assigned to this watch
1390 * @param watch_cb what to do when a notify is received on this image
1391 * @param arg opaque value to pass to the callback
1392 * @returns 0 on success, negative error code on failure
1394 CEPH_RBD_API
int rbd_update_watch(rbd_image_t image
, uint64_t *handle
,
1395 rbd_update_callback_t watch_cb
, void *arg
);
1398 * Unregister an image watcher.
1400 * @param image the image to unwatch
1401 * @param handle which watch to unregister
1402 * @returns 0 on success, negative error code on failure
1404 CEPH_RBD_API
int rbd_update_unwatch(rbd_image_t image
, uint64_t handle
);
1407 * List any watchers of an image.
1409 * Watchers will be allocated and stored in the passed watchers array. If there
1410 * are more watchers than max_watchers, -ERANGE will be returned and the number
1411 * of watchers will be stored in max_watchers.
1413 * The caller should call rbd_watchers_list_cleanup when finished with the list
1416 * @param image the image to list watchers for.
1417 * @param watchers an array to store watchers in.
1418 * @param max_watchers capacity of the watchers array.
1419 * @returns 0 on success, negative error code on failure.
1420 * @returns -ERANGE if there are too many watchers for the passed array.
1421 * @returns the number of watchers in max_watchers.
1423 CEPH_RBD_API
int rbd_watchers_list(rbd_image_t image
,
1424 rbd_image_watcher_t
*watchers
,
1425 size_t *max_watchers
);
1427 CEPH_RBD_API
void rbd_watchers_list_cleanup(rbd_image_watcher_t
*watchers
,
1428 size_t num_watchers
);
1430 CEPH_RBD_API
int rbd_config_image_list(rbd_image_t image
,
1431 rbd_config_option_t
*options
,
1433 CEPH_RBD_API
void rbd_config_image_list_cleanup(rbd_config_option_t
*options
,
1436 CEPH_RBD_API
int rbd_group_image_add(rados_ioctx_t group_p
,
1437 const char *group_name
,
1438 rados_ioctx_t image_p
,
1439 const char *image_name
);
1440 CEPH_RBD_API
int rbd_group_image_remove(rados_ioctx_t group_p
,
1441 const char *group_name
,
1442 rados_ioctx_t image_p
,
1443 const char *image_name
);
1444 CEPH_RBD_API
int rbd_group_image_remove_by_id(rados_ioctx_t group_p
,
1445 const char *group_name
,
1446 rados_ioctx_t image_p
,
1447 const char *image_id
);
1448 CEPH_RBD_API
int rbd_group_image_list(rados_ioctx_t group_p
,
1449 const char *group_name
,
1450 rbd_group_image_info_t
*images
,
1451 size_t group_image_info_size
,
1452 size_t *num_entries
);
1453 CEPH_RBD_API
int rbd_group_image_list_cleanup(rbd_group_image_info_t
*images
,
1454 size_t group_image_info_size
,
1455 size_t num_entries
);
1457 CEPH_RBD_API
int rbd_group_snap_create(rados_ioctx_t group_p
,
1458 const char *group_name
,
1459 const char *snap_name
);
1460 CEPH_RBD_API
int rbd_group_snap_create2(rados_ioctx_t group_p
,
1461 const char *group_name
,
1462 const char *snap_name
,
1464 CEPH_RBD_API
int rbd_group_snap_remove(rados_ioctx_t group_p
,
1465 const char *group_name
,
1466 const char *snap_name
);
1467 CEPH_RBD_API
int rbd_group_snap_rename(rados_ioctx_t group_p
,
1468 const char *group_name
,
1469 const char *old_snap_name
,
1470 const char *new_snap_name
);
1471 CEPH_RBD_API
int rbd_group_snap_list(rados_ioctx_t group_p
,
1472 const char *group_name
,
1473 rbd_group_snap_info_t
*snaps
,
1474 size_t group_snap_info_size
,
1475 size_t *num_entries
);
1476 CEPH_RBD_API
int rbd_group_snap_list_cleanup(rbd_group_snap_info_t
*snaps
,
1477 size_t group_snap_info_size
,
1478 size_t num_entries
);
1479 CEPH_RBD_API
int rbd_group_snap_rollback(rados_ioctx_t group_p
,
1480 const char *group_name
,
1481 const char *snap_name
);
1482 CEPH_RBD_API
int rbd_group_snap_rollback_with_progress(rados_ioctx_t group_p
,
1483 const char *group_name
,
1484 const char *snap_name
,
1485 librbd_progress_fn_t cb
,
1488 CEPH_RBD_API
int rbd_namespace_create(rados_ioctx_t io
,
1489 const char *namespace_name
);
1490 CEPH_RBD_API
int rbd_namespace_remove(rados_ioctx_t io
,
1491 const char *namespace_name
);
1492 CEPH_RBD_API
int rbd_namespace_list(rados_ioctx_t io
, char *namespace_names
,
1494 CEPH_RBD_API
int rbd_namespace_exists(rados_ioctx_t io
,
1495 const char *namespace_name
,
1498 CEPH_RBD_API
int rbd_pool_init(rados_ioctx_t io
, bool force
);
1500 CEPH_RBD_API
void rbd_pool_stats_create(rbd_pool_stats_t
*stats
);
1501 CEPH_RBD_API
void rbd_pool_stats_destroy(rbd_pool_stats_t stats
);
1502 CEPH_RBD_API
int rbd_pool_stats_option_add_uint64(rbd_pool_stats_t stats
,
1504 uint64_t* stat_val
);
1505 CEPH_RBD_API
int rbd_pool_stats_get(rados_ioctx_t io
, rbd_pool_stats_t stats
);
1508 * Register a quiesce/unquiesce watcher.
1510 * @param image the image to watch
1511 * @param quiesce_cb what to do when librbd wants to quiesce
1512 * @param unquiesce_cb what to do when librbd wants to unquiesce
1513 * @param arg opaque value to pass to the callbacks
1514 * @param handle where to store the internal id assigned to this watch
1515 * @returns 0 on success, negative error code on failure
1517 CEPH_RBD_API
int rbd_quiesce_watch(rbd_image_t image
,
1518 rbd_update_callback_t quiesce_cb
,
1519 rbd_update_callback_t unquiesce_cb
,
1520 void *arg
, uint64_t *handle
);
1523 * Notify quiesce is complete
1525 * @param image the image to notify
1526 * @param handle which watch is complete
1527 * @param r the return code
1529 CEPH_RBD_API
void rbd_quiesce_complete(rbd_image_t image
, uint64_t handle
,
1533 * Unregister a quiesce/unquiesce watcher.
1535 * @param image the image to unwatch
1536 * @param handle which watch to unregister
1537 * @returns 0 on success, negative error code on failure
1539 CEPH_RBD_API
int rbd_quiesce_unwatch(rbd_image_t image
, uint64_t handle
);
1542 #pragma GCC diagnostic pop
1549 #endif /* CEPH_LIBRBD_H */