ceph/src/include/rbd/librbd.h

   1 // -*- mode:C; tab-width:8; c-basic-offset:2; indent-tabs-mode:t -*-
   2 // vim: ts=8 sw=2 smarttab
   3 /*
   4  * Ceph - scalable distributed file system
   5  *
   6  * Copyright (C) 2011 New Dream Network
   7  *
   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.
  12  *
  13  */
  14
  15 #ifndef CEPH_LIBRBD_H
  16 #define CEPH_LIBRBD_H
  17
  18 #ifdef __cplusplus
  19 extern "C" {
  20 #endif
  21
  22 #include <netinet/in.h>
  23 #if defined(__linux__)
  24 #include <linux/types.h>
  25 #elif defined(__FreeBSD__)
  26 #include <sys/types.h>
  27 #endif
  28 #include <stdbool.h>
  29 #include <string.h>
  30 #include <sys/uio.h>
  31 #include "../rados/librados.h"
  32 #include "features.h"
  33
  34 #define LIBRBD_VER_MAJOR 1
  35 #define LIBRBD_VER_MINOR 15
  36 #define LIBRBD_VER_EXTRA 0
  37
  38 #define LIBRBD_VERSION(maj, min, extra) ((maj << 16) + (min << 8) + extra)
  39
  40 #define LIBRBD_VERSION_CODE LIBRBD_VERSION(LIBRBD_VER_MAJOR, LIBRBD_VER_MINOR, LIBRBD_VER_EXTRA)
  41
  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_LOCKING 1
  46 #define LIBRBD_SUPPORTS_INVALIDATE 1
  47 #define LIBRBD_SUPPORTS_IOVEC 1
  48 #define LIBRBD_SUPPORTS_WATCH 0
  49 #define LIBRBD_SUPPORTS_WRITESAME 1
  50
  51 #if __GNUC__ >= 4
  52   #define CEPH_RBD_API          __attribute__ ((visibility ("default")))
  53   #define CEPH_RBD_DEPRECATED   __attribute__((deprecated))
  54   #pragma GCC diagnostic push
  55   #pragma GCC diagnostic ignored "-Wdeprecated-declarations"
  56 #else
  57   #define CEPH_RBD_API
  58   #define CEPH_RBD_DEPRECATED
  59 #endif
  60
  61 #define RBD_FLAG_OBJECT_MAP_INVALID   (1<<0)
  62 #define RBD_FLAG_FAST_DIFF_INVALID    (1<<1)
  63
  64 #define RBD_MIRROR_IMAGE_STATUS_LOCAL_MIRROR_UUID ""
  65
  66 typedef void *rbd_image_t;
  67 typedef void *rbd_image_options_t;
  68 typedef void *rbd_pool_stats_t;
  69
  70 typedef void *rbd_completion_t;
  71 typedef void (*rbd_callback_t)(rbd_completion_t cb, void *arg);
  72
  73 typedef int (*librbd_progress_fn_t)(uint64_t offset, uint64_t total, void *ptr);
  74
  75 typedef void (*rbd_update_callback_t)(void *arg);
  76
  77 typedef enum {
  78   RBD_SNAP_NAMESPACE_TYPE_USER   = 0,
  79   RBD_SNAP_NAMESPACE_TYPE_GROUP  = 1,
  80   RBD_SNAP_NAMESPACE_TYPE_TRASH  = 2,
  81   RBD_SNAP_NAMESPACE_TYPE_MIRROR = 3,
  82 } rbd_snap_namespace_type_t;
  83
  84 typedef struct {
  85   char *id;
  86   char *name;
  87 } rbd_image_spec_t;
  88
  89 typedef struct {
  90   int64_t pool_id;
  91   char *pool_name;
  92   char *pool_namespace;
  93   char *image_id;
  94   char *image_name;
  95   bool trash;
  96 } rbd_linked_image_spec_t;
  97
  98 typedef struct {
  99   uint64_t id;
 100   rbd_snap_namespace_type_t namespace_type;
 101   char *name;
 102 } rbd_snap_spec_t;
 103
 104 typedef struct {
 105   uint64_t id;
 106   uint64_t size;
 107   const char *name;
 108 } rbd_snap_info_t;
 109
 110 typedef struct {
 111   const char *pool_name;
 112   const char *image_name;
 113   const char *image_id;
 114   bool trash;
 115 } rbd_child_info_t;
 116
 117 #define RBD_MAX_IMAGE_NAME_SIZE 96
 118 #define RBD_MAX_BLOCK_NAME_SIZE 24
 119
 120 #define RBD_SNAP_REMOVE_UNPROTECT       1 << 0
 121 #define RBD_SNAP_REMOVE_FLATTEN         1 << 1
 122 #define RBD_SNAP_REMOVE_FORCE           (RBD_SNAP_REMOVE_UNPROTECT | RBD_SNAP_REMOVE_FLATTEN)
 123
 124 /**
 125  * These types used to in set_image_notification to indicate the type of event
 126  * socket passed in.
 127  */
 128 enum {
 129   EVENT_TYPE_PIPE = 1,
 130   EVENT_TYPE_EVENTFD = 2
 131 };
 132
 133 typedef struct {
 134   uint64_t size;
 135   uint64_t obj_size;
 136   uint64_t num_objs;
 137   int order;
 138   char block_name_prefix[RBD_MAX_BLOCK_NAME_SIZE]; /* deprecated */
 139   int64_t parent_pool;                             /* deprecated */
 140   char parent_name[RBD_MAX_IMAGE_NAME_SIZE];       /* deprecated */
 141 } rbd_image_info_t;
 142
 143 typedef enum {
 144   RBD_MIRROR_MODE_DISABLED, /* mirroring is disabled */
 145   RBD_MIRROR_MODE_IMAGE,    /* mirroring enabled on a per-image basis */
 146   RBD_MIRROR_MODE_POOL      /* mirroring enabled on all journaled images */
 147 } rbd_mirror_mode_t;
 148
 149 typedef enum {
 150   RBD_MIRROR_PEER_DIRECTION_RX    = 0,
 151   RBD_MIRROR_PEER_DIRECTION_TX    = 1,
 152   RBD_MIRROR_PEER_DIRECTION_RX_TX = 2
 153 } rbd_mirror_peer_direction_t;
 154
 155 typedef struct {
 156   char *uuid;
 157   char *cluster_name;
 158   char *client_name;
 159 } rbd_mirror_peer_t CEPH_RBD_DEPRECATED;
 160
 161 typedef struct {
 162   char *uuid;
 163   rbd_mirror_peer_direction_t direction;
 164   char *site_name;
 165   char *mirror_uuid;
 166   char *client_name;
 167   time_t last_seen;
 168 } rbd_mirror_peer_site_t;
 169
 170 #define RBD_MIRROR_PEER_ATTRIBUTE_NAME_MON_HOST "mon_host"
 171 #define RBD_MIRROR_PEER_ATTRIBUTE_NAME_KEY      "key"
 172
 173 typedef enum {
 174   RBD_MIRROR_IMAGE_MODE_JOURNAL  = 0,
 175   RBD_MIRROR_IMAGE_MODE_SNAPSHOT = 1,
 176 } rbd_mirror_image_mode_t;
 177
 178 typedef enum {
 179   RBD_MIRROR_IMAGE_DISABLING = 0,
 180   RBD_MIRROR_IMAGE_ENABLED = 1,
 181   RBD_MIRROR_IMAGE_DISABLED = 2
 182 } rbd_mirror_image_state_t;
 183
 184 typedef struct {
 185   char *global_id;
 186   rbd_mirror_image_state_t state;
 187   bool primary;
 188 } rbd_mirror_image_info_t;
 189
 190 typedef enum {
 191   MIRROR_IMAGE_STATUS_STATE_UNKNOWN         = 0,
 192   MIRROR_IMAGE_STATUS_STATE_ERROR           = 1,
 193   MIRROR_IMAGE_STATUS_STATE_SYNCING         = 2,
 194   MIRROR_IMAGE_STATUS_STATE_STARTING_REPLAY = 3,
 195   MIRROR_IMAGE_STATUS_STATE_REPLAYING       = 4,
 196   MIRROR_IMAGE_STATUS_STATE_STOPPING_REPLAY = 5,
 197   MIRROR_IMAGE_STATUS_STATE_STOPPED         = 6,
 198 } rbd_mirror_image_status_state_t;
 199
 200 typedef struct {
 201   char *name;
 202   rbd_mirror_image_info_t info;
 203   rbd_mirror_image_status_state_t state;
 204   char *description;
 205   time_t last_update;
 206   bool up;
 207 } rbd_mirror_image_status_t CEPH_RBD_DEPRECATED;
 208
 209 typedef struct {
 210   char *mirror_uuid;
 211   rbd_mirror_image_status_state_t state;
 212   char *description;
 213   time_t last_update;
 214   bool up;
 215 } rbd_mirror_image_site_status_t;
 216
 217 typedef struct {
 218   char *name;
 219   rbd_mirror_image_info_t info;
 220   uint32_t site_statuses_count;
 221   rbd_mirror_image_site_status_t *site_statuses;
 222 } rbd_mirror_image_global_status_t;
 223
 224 typedef enum {
 225   RBD_GROUP_IMAGE_STATE_ATTACHED,
 226   RBD_GROUP_IMAGE_STATE_INCOMPLETE
 227 } rbd_group_image_state_t;
 228
 229 typedef struct {
 230   char *name;
 231   int64_t pool;
 232   rbd_group_image_state_t state;
 233 } rbd_group_image_info_t;
 234
 235 typedef struct {
 236   char *name;
 237   int64_t pool;
 238 } rbd_group_info_t;
 239
 240 typedef enum {
 241   RBD_GROUP_SNAP_STATE_INCOMPLETE,
 242   RBD_GROUP_SNAP_STATE_COMPLETE
 243 } rbd_group_snap_state_t;
 244
 245 typedef struct {
 246   char *name;
 247   rbd_group_snap_state_t state;
 248 } rbd_group_snap_info_t;
 249
 250 typedef struct {
 251   int64_t group_pool;
 252   char *group_name;
 253   char *group_snap_name;
 254 } rbd_snap_group_namespace_t;
 255
 256 typedef enum {
 257   RBD_SNAP_MIRROR_STATE_PRIMARY,
 258   RBD_SNAP_MIRROR_STATE_PRIMARY_DEMOTED,
 259   RBD_SNAP_MIRROR_STATE_NON_PRIMARY,
 260   RBD_SNAP_MIRROR_STATE_NON_PRIMARY_DEMOTED
 261 } rbd_snap_mirror_state_t;
 262
 263 typedef struct {
 264   rbd_snap_mirror_state_t state;
 265   size_t mirror_peer_uuids_count;
 266   char *mirror_peer_uuids;
 267   bool complete;
 268   char *primary_mirror_uuid;
 269   uint64_t primary_snap_id;
 270   uint64_t last_copied_object_number;
 271 } rbd_snap_mirror_namespace_t;
 272
 273 typedef enum {
 274   RBD_LOCK_MODE_EXCLUSIVE = 0,
 275   RBD_LOCK_MODE_SHARED = 1,
 276 } rbd_lock_mode_t;
 277
 278 CEPH_RBD_API void rbd_version(int *major, int *minor, int *extra);
 279
 280 /* image options */
 281 enum {
 282   RBD_IMAGE_OPTION_FORMAT = 0,
 283   RBD_IMAGE_OPTION_FEATURES = 1,
 284   RBD_IMAGE_OPTION_ORDER = 2,
 285   RBD_IMAGE_OPTION_STRIPE_UNIT = 3,
 286   RBD_IMAGE_OPTION_STRIPE_COUNT = 4,
 287   RBD_IMAGE_OPTION_JOURNAL_ORDER = 5,
 288   RBD_IMAGE_OPTION_JOURNAL_SPLAY_WIDTH = 6,
 289   RBD_IMAGE_OPTION_JOURNAL_POOL = 7,
 290   RBD_IMAGE_OPTION_FEATURES_SET = 8,
 291   RBD_IMAGE_OPTION_FEATURES_CLEAR = 9,
 292   RBD_IMAGE_OPTION_DATA_POOL = 10,
 293   RBD_IMAGE_OPTION_FLATTEN = 11,
 294   RBD_IMAGE_OPTION_CLONE_FORMAT = 12,
 295   RBD_IMAGE_OPTION_MIRROR_IMAGE_MODE = 13,
 296 };
 297
 298 typedef enum {
 299   RBD_TRASH_IMAGE_SOURCE_USER = 0,
 300   RBD_TRASH_IMAGE_SOURCE_MIRRORING = 1,
 301   RBD_TRASH_IMAGE_SOURCE_MIGRATION = 2,
 302   RBD_TRASH_IMAGE_SOURCE_REMOVING = 3,
 303   RBD_TRASH_IMAGE_SOURCE_USER_PARENT = 4,
 304 } rbd_trash_image_source_t;
 305
 306 typedef struct {
 307   char *id;
 308   char *name;
 309   rbd_trash_image_source_t source;
 310   time_t deletion_time;
 311   time_t deferment_end_time;
 312 } rbd_trash_image_info_t;
 313
 314 typedef struct {
 315   char *addr;
 316   int64_t id;
 317   uint64_t cookie;
 318 } rbd_image_watcher_t;
 319
 320 typedef enum {
 321   RBD_IMAGE_MIGRATION_STATE_UNKNOWN = -1,
 322   RBD_IMAGE_MIGRATION_STATE_ERROR = 0,
 323   RBD_IMAGE_MIGRATION_STATE_PREPARING = 1,
 324   RBD_IMAGE_MIGRATION_STATE_PREPARED = 2,
 325   RBD_IMAGE_MIGRATION_STATE_EXECUTING = 3,
 326   RBD_IMAGE_MIGRATION_STATE_EXECUTED = 4,
 327 } rbd_image_migration_state_t;
 328
 329 typedef struct {
 330   int64_t source_pool_id;
 331   char *source_pool_namespace;
 332   char *source_image_name;
 333   char *source_image_id;
 334   int64_t dest_pool_id;
 335   char *dest_pool_namespace;
 336   char *dest_image_name;
 337   char *dest_image_id;
 338   rbd_image_migration_state_t state;
 339   char *state_description;
 340 } rbd_image_migration_status_t;
 341
 342 typedef enum {
 343   RBD_CONFIG_SOURCE_CONFIG = 0,
 344   RBD_CONFIG_SOURCE_POOL = 1,
 345   RBD_CONFIG_SOURCE_IMAGE = 2,
 346 } rbd_config_source_t;
 347
 348 typedef struct {
 349   char *name;
 350   char *value;
 351   rbd_config_source_t source;
 352 } rbd_config_option_t;
 353
 354 typedef enum {
 355   RBD_POOL_STAT_OPTION_IMAGES,
 356   RBD_POOL_STAT_OPTION_IMAGE_PROVISIONED_BYTES,
 357   RBD_POOL_STAT_OPTION_IMAGE_MAX_PROVISIONED_BYTES,
 358   RBD_POOL_STAT_OPTION_IMAGE_SNAPSHOTS,
 359   RBD_POOL_STAT_OPTION_TRASH_IMAGES,
 360   RBD_POOL_STAT_OPTION_TRASH_PROVISIONED_BYTES,
 361   RBD_POOL_STAT_OPTION_TRASH_MAX_PROVISIONED_BYTES,
 362   RBD_POOL_STAT_OPTION_TRASH_SNAPSHOTS
 363 } rbd_pool_stat_option_t;
 364
 365 CEPH_RBD_API void rbd_image_options_create(rbd_image_options_t* opts);
 366 CEPH_RBD_API void rbd_image_options_destroy(rbd_image_options_t opts);
 367 CEPH_RBD_API int rbd_image_options_set_string(rbd_image_options_t opts,
 368                                               int optname, const char* optval);
 369 CEPH_RBD_API int rbd_image_options_set_uint64(rbd_image_options_t opts,
 370                                               int optname, uint64_t optval);
 371 CEPH_RBD_API int rbd_image_options_get_string(rbd_image_options_t opts,
 372                                               int optname, char* optval,
 373                                               size_t maxlen);
 374 CEPH_RBD_API int rbd_image_options_get_uint64(rbd_image_options_t opts,
 375                                               int optname, uint64_t* optval);
 376 CEPH_RBD_API int rbd_image_options_is_set(rbd_image_options_t opts,
 377                                           int optname, bool* is_set);
 378 CEPH_RBD_API int rbd_image_options_unset(rbd_image_options_t opts, int optname);
 379 CEPH_RBD_API void rbd_image_options_clear(rbd_image_options_t opts);
 380 CEPH_RBD_API int rbd_image_options_is_empty(rbd_image_options_t opts);
 381
 382 /* helpers */
 383 CEPH_RBD_API void rbd_image_spec_cleanup(rbd_image_spec_t *image);
 384 CEPH_RBD_API void rbd_image_spec_list_cleanup(rbd_image_spec_t *images,
 385                                               size_t num_images);
 386 CEPH_RBD_API void rbd_linked_image_spec_cleanup(rbd_linked_image_spec_t *image);
 387 CEPH_RBD_API void rbd_linked_image_spec_list_cleanup(
 388     rbd_linked_image_spec_t *images, size_t num_images);
 389 CEPH_RBD_API void rbd_snap_spec_cleanup(rbd_snap_spec_t *snap);
 390
 391 /* images */
 392 CEPH_RBD_API int rbd_list(rados_ioctx_t io, char *names, size_t *size)
 393   CEPH_RBD_DEPRECATED;
 394 CEPH_RBD_API int rbd_list2(rados_ioctx_t io, rbd_image_spec_t* images,
 395                            size_t *max_images);
 396
 397 CEPH_RBD_API int rbd_create(rados_ioctx_t io, const char *name, uint64_t size,
 398                             int *order);
 399 CEPH_RBD_API int rbd_create2(rados_ioctx_t io, const char *name, uint64_t size,
 400                              uint64_t features, int *order);
 401 /**
 402  * create new rbd image
 403  *
 404  * The stripe_unit must be a factor of the object size (1 << order).
 405  * The stripe_count can be one (no intra-object striping) or greater
 406  * than one.  The RBD_FEATURE_STRIPINGV2 must be specified if the
 407  * stripe_unit != the object size and the stripe_count is != 1.
 408  *
 409  * @param io ioctx
 410  * @param name image name
 411  * @param size image size in bytes
 412  * @param features initial feature bits
 413  * @param order object/block size, as a power of two (object size == 1 << order)
 414  * @param stripe_unit stripe unit size, in bytes.
 415  * @param stripe_count number of objects to stripe over before looping
 416  * @return 0 on success, or negative error code
 417  */
 418 CEPH_RBD_API int rbd_create3(rados_ioctx_t io, const char *name, uint64_t size,
 419                              uint64_t features, int *order,
 420                              uint64_t stripe_unit, uint64_t stripe_count);
 421 CEPH_RBD_API int rbd_create4(rados_ioctx_t io, const char *name, uint64_t size,
 422                              rbd_image_options_t opts);
 423 CEPH_RBD_API int rbd_clone(rados_ioctx_t p_ioctx, const char *p_name,
 424                            const char *p_snapname, rados_ioctx_t c_ioctx,
 425                            const char *c_name, uint64_t features, int *c_order);
 426 CEPH_RBD_API int rbd_clone2(rados_ioctx_t p_ioctx, const char *p_name,
 427                             const char *p_snapname, rados_ioctx_t c_ioctx,
 428                             const char *c_name, uint64_t features, int *c_order,
 429                             uint64_t stripe_unit, int stripe_count);
 430 CEPH_RBD_API int rbd_clone3(rados_ioctx_t p_ioctx, const char *p_name,
 431                             const char *p_snapname, rados_ioctx_t c_ioctx,
 432                             const char *c_name, rbd_image_options_t c_opts);
 433 CEPH_RBD_API int rbd_remove(rados_ioctx_t io, const char *name);
 434 CEPH_RBD_API int rbd_remove_with_progress(rados_ioctx_t io, const char *name,
 435                                           librbd_progress_fn_t cb,
 436                                           void *cbdata);
 437 CEPH_RBD_API int rbd_rename(rados_ioctx_t src_io_ctx, const char *srcname,
 438                             const char *destname);
 439
 440 CEPH_RBD_API int rbd_trash_move(rados_ioctx_t io, const char *name,
 441                                 uint64_t delay);
 442 CEPH_RBD_API int rbd_trash_get(rados_ioctx_t io, const char *id,
 443                                rbd_trash_image_info_t *info);
 444 CEPH_RBD_API void rbd_trash_get_cleanup(rbd_trash_image_info_t *info);
 445 CEPH_RBD_API int rbd_trash_list(rados_ioctx_t io,
 446                                 rbd_trash_image_info_t *trash_entries,
 447                                 size_t *num_entries);
 448 CEPH_RBD_API void rbd_trash_list_cleanup(rbd_trash_image_info_t *trash_entries,
 449                                          size_t num_entries);
 450 CEPH_RBD_API int rbd_trash_purge(rados_ioctx_t io, time_t expire_ts, float threshold);
 451 CEPH_RBD_API int rbd_trash_purge_with_progress(rados_ioctx_t io, time_t expire_ts,
 452                                                float threshold, librbd_progress_fn_t cb,
 453                                                void* cbdata);
 454 CEPH_RBD_API int rbd_trash_remove(rados_ioctx_t io, const char *id, bool force);
 455 CEPH_RBD_API int rbd_trash_remove_with_progress(rados_ioctx_t io,
 456                                                 const char *id,
 457                                                 bool force,
 458                                                 librbd_progress_fn_t cb,
 459                                                 void *cbdata);
 460 CEPH_RBD_API int rbd_trash_restore(rados_ioctx_t io, const char *id,
 461                                    const char *name);
 462
 463 /* migration */
 464 CEPH_RBD_API int rbd_migration_prepare(rados_ioctx_t ioctx,
 465                                        const char *image_name,
 466                                        rados_ioctx_t dest_ioctx,
 467                                        const char *dest_image_name,
 468                                        rbd_image_options_t opts);
 469 CEPH_RBD_API int rbd_migration_execute(rados_ioctx_t ioctx,
 470                                        const char *image_name);
 471 CEPH_RBD_API int rbd_migration_execute_with_progress(rados_ioctx_t ioctx,
 472                                                      const char *image_name,
 473                                                      librbd_progress_fn_t cb,
 474                                                      void *cbdata);
 475 CEPH_RBD_API int rbd_migration_abort(rados_ioctx_t ioctx,
 476                                      const char *image_name);
 477 CEPH_RBD_API int rbd_migration_abort_with_progress(rados_ioctx_t ioctx,
 478                                                    const char *image_name,
 479                                                    librbd_progress_fn_t cb,
 480                                                    void *cbdata);
 481 CEPH_RBD_API int rbd_migration_commit(rados_ioctx_t ioctx,
 482                                       const char *image_name);
 483 CEPH_RBD_API int rbd_migration_commit_with_progress(rados_ioctx_t ioctx,
 484                                                     const char *image_name,
 485                                                     librbd_progress_fn_t cb,
 486                                                     void *cbdata);
 487 CEPH_RBD_API int rbd_migration_status(rados_ioctx_t ioctx,
 488                                       const char *image_name,
 489                                       rbd_image_migration_status_t *status,
 490                                       size_t status_size);
 491 CEPH_RBD_API void rbd_migration_status_cleanup(
 492     rbd_image_migration_status_t *status);
 493
 494 /* pool mirroring */
 495 CEPH_RBD_API int rbd_mirror_site_name_get(rados_t cluster,
 496                                           char *name, size_t *max_len);
 497 CEPH_RBD_API int rbd_mirror_site_name_set(rados_t cluster,
 498                                           const char *name);
 499
 500 CEPH_RBD_API int rbd_mirror_mode_get(rados_ioctx_t io_ctx,
 501                                      rbd_mirror_mode_t *mirror_mode);
 502 CEPH_RBD_API int rbd_mirror_mode_set(rados_ioctx_t io_ctx,
 503                                      rbd_mirror_mode_t mirror_mode);
 504
 505 CEPH_RBD_API int rbd_mirror_uuid_get(rados_ioctx_t io_ctx,
 506                                      char *uuid, size_t *max_len);
 507
 508 CEPH_RBD_API int rbd_mirror_peer_bootstrap_create(
 509     rados_ioctx_t io_ctx, char *token, size_t *max_len);
 510 CEPH_RBD_API int rbd_mirror_peer_bootstrap_import(
 511     rados_ioctx_t io_ctx, rbd_mirror_peer_direction_t direction,
 512     const char *token);
 513
 514 CEPH_RBD_API int rbd_mirror_peer_site_add(
 515     rados_ioctx_t io_ctx, char *uuid, size_t uuid_max_length,
 516     rbd_mirror_peer_direction_t direction, const char *site_name,
 517     const char *client_name);
 518 CEPH_RBD_API int rbd_mirror_peer_site_set_name(
 519     rados_ioctx_t io_ctx, const char *uuid, const char *site_name);
 520 CEPH_RBD_API int rbd_mirror_peer_site_set_client_name(
 521     rados_ioctx_t io_ctx, const char *uuid, const char *client_name);
 522 CEPH_RBD_API int rbd_mirror_peer_site_set_direction(
 523     rados_ioctx_t io_ctx, const char *uuid,
 524     rbd_mirror_peer_direction_t direction);
 525 CEPH_RBD_API int rbd_mirror_peer_site_remove(
 526     rados_ioctx_t io_ctx, const char *uuid);
 527 CEPH_RBD_API int rbd_mirror_peer_site_list(
 528     rados_ioctx_t io_ctx, rbd_mirror_peer_site_t *peers, int *max_peers);
 529 CEPH_RBD_API void rbd_mirror_peer_site_list_cleanup(
 530     rbd_mirror_peer_site_t *peers, int max_peers);
 531 CEPH_RBD_API int rbd_mirror_peer_site_get_attributes(
 532     rados_ioctx_t p, const char *uuid, char *keys, size_t *max_key_len,
 533     char *values, size_t *max_value_len, size_t *key_value_count);
 534 CEPH_RBD_API int rbd_mirror_peer_site_set_attributes(
 535     rados_ioctx_t p, const char *uuid, const char *keys, const char *values,
 536     size_t key_value_count);
 537
 538 CEPH_RBD_API int rbd_mirror_image_global_status_list(
 539     rados_ioctx_t io_ctx, const char *start_id, size_t max, char **image_ids,
 540     rbd_mirror_image_global_status_t *images, size_t *len);
 541 CEPH_RBD_API void rbd_mirror_image_global_status_list_cleanup(
 542     char **image_ids, rbd_mirror_image_global_status_t *images, size_t len);
 543
 544 /* rbd_mirror_peer_ commands are deprecated to rbd_mirror_peer_site_
 545  * equivalents */
 546 CEPH_RBD_API int rbd_mirror_peer_add(
 547     rados_ioctx_t io_ctx, char *uuid, size_t uuid_max_length,
 548     const char *cluster_name, const char *client_name)
 549   CEPH_RBD_DEPRECATED;
 550 CEPH_RBD_API int rbd_mirror_peer_remove(
 551     rados_ioctx_t io_ctx, const char *uuid)
 552   CEPH_RBD_DEPRECATED;
 553 CEPH_RBD_API int rbd_mirror_peer_list(
 554     rados_ioctx_t io_ctx, rbd_mirror_peer_t *peers, int *max_peers)
 555   CEPH_RBD_DEPRECATED;
 556 CEPH_RBD_API void rbd_mirror_peer_list_cleanup(
 557     rbd_mirror_peer_t *peers, int max_peers)
 558   CEPH_RBD_DEPRECATED;
 559 CEPH_RBD_API int rbd_mirror_peer_set_client(
 560     rados_ioctx_t io_ctx, const char *uuid, const char *client_name)
 561   CEPH_RBD_DEPRECATED;
 562 CEPH_RBD_API int rbd_mirror_peer_set_cluster(
 563     rados_ioctx_t io_ctx, const char *uuid, const char *cluster_name)
 564   CEPH_RBD_DEPRECATED;
 565 CEPH_RBD_API int rbd_mirror_peer_get_attributes(
 566     rados_ioctx_t p, const char *uuid, char *keys, size_t *max_key_len,
 567     char *values, size_t *max_value_len, size_t *key_value_count)
 568   CEPH_RBD_DEPRECATED;
 569 CEPH_RBD_API int rbd_mirror_peer_set_attributes(
 570     rados_ioctx_t p, const char *uuid, const char *keys, const char *values,
 571     size_t key_value_count)
 572   CEPH_RBD_DEPRECATED;
 573
 574 /* rbd_mirror_image_status_list_ commands are deprecard to
 575  * rbd_mirror_image_global_status_list_ commands */
 576
 577 CEPH_RBD_API int rbd_mirror_image_status_list(
 578     rados_ioctx_t io_ctx, const char *start_id, size_t max, char **image_ids,
 579     rbd_mirror_image_status_t *images, size_t *len)
 580   CEPH_RBD_DEPRECATED;
 581 CEPH_RBD_API void rbd_mirror_image_status_list_cleanup(
 582     char **image_ids, rbd_mirror_image_status_t *images, size_t len)
 583   CEPH_RBD_DEPRECATED;
 584
 585 CEPH_RBD_API int rbd_mirror_image_status_summary(
 586     rados_ioctx_t io_ctx, rbd_mirror_image_status_state_t *states, int *counts,
 587     size_t *maxlen);
 588
 589 CEPH_RBD_API int rbd_mirror_image_instance_id_list(rados_ioctx_t io_ctx,
 590                                                    const char *start_id,
 591                                                    size_t max, char **image_ids,
 592                                                    char **instance_ids,
 593                                                    size_t *len);
 594 CEPH_RBD_API void rbd_mirror_image_instance_id_list_cleanup(char **image_ids,
 595                                                             char **instance_ids,
 596                                                             size_t len);
 597 CEPH_RBD_API int rbd_mirror_image_info_list(
 598     rados_ioctx_t io_ctx, rbd_mirror_image_mode_t *mode_filter,
 599     const char *start_id, size_t max, char **image_ids,
 600     rbd_mirror_image_mode_t *mode_entries,
 601     rbd_mirror_image_info_t *info_entries, size_t *num_entries);
 602 CEPH_RBD_API void rbd_mirror_image_info_list_cleanup(
 603     char **image_ids, rbd_mirror_image_info_t *info_entries,
 604     size_t num_entries);
 605
 606 /* pool metadata */
 607 CEPH_RBD_API int rbd_pool_metadata_get(rados_ioctx_t io_ctx, const char *key,
 608                                        char *value, size_t *val_len);
 609 CEPH_RBD_API int rbd_pool_metadata_set(rados_ioctx_t io_ctx, const char *key,
 610                                        const char *value);
 611 CEPH_RBD_API int rbd_pool_metadata_remove(rados_ioctx_t io_ctx,
 612                                           const char *key);
 613 CEPH_RBD_API int rbd_pool_metadata_list(rados_ioctx_t io_ctx, const char *start,
 614                                         uint64_t max, char *keys,
 615                                         size_t *key_len, char *values,
 616                                         size_t *vals_len);
 617
 618 CEPH_RBD_API int rbd_config_pool_list(rados_ioctx_t io_ctx,
 619                                       rbd_config_option_t *options,
 620                                       int *max_options);
 621 CEPH_RBD_API void rbd_config_pool_list_cleanup(rbd_config_option_t *options,
 622                                                int max_options);
 623
 624 CEPH_RBD_API int rbd_open(rados_ioctx_t io, const char *name,
 625                           rbd_image_t *image, const char *snap_name);
 626 CEPH_RBD_API int rbd_open_by_id(rados_ioctx_t io, const char *id,
 627                                 rbd_image_t *image, const char *snap_name);
 628
 629 CEPH_RBD_API int rbd_aio_open(rados_ioctx_t io, const char *name,
 630                               rbd_image_t *image, const char *snap_name,
 631                               rbd_completion_t c);
 632 CEPH_RBD_API int rbd_aio_open_by_id(rados_ioctx_t io, const char *id,
 633                                     rbd_image_t *image, const char *snap_name,
 634                                     rbd_completion_t c);
 635
 636 /**
 637  * Open an image in read-only mode.
 638  *
 639  * This is intended for use by clients that cannot write to a block
 640  * device due to cephx restrictions. There will be no watch
 641  * established on the header object, since a watch is a write. This
 642  * means the metadata reported about this image (parents, snapshots,
 643  * size, etc.) may become stale. This should not be used for
 644  * long-running operations, unless you can be sure that one of these
 645  * properties changing is safe.
 646  *
 647  * Attempting to write to a read-only image will return -EROFS.
 648  *
 649  * @param io ioctx to determine the pool the image is in
 650  * @param name image name
 651  * @param image where to store newly opened image handle
 652  * @param snap_name name of snapshot to open at, or NULL for no snapshot
 653  * @returns 0 on success, negative error code on failure
 654  */
 655 CEPH_RBD_API int rbd_open_read_only(rados_ioctx_t io, const char *name,
 656                                     rbd_image_t *image, const char *snap_name);
 657 CEPH_RBD_API int rbd_open_by_id_read_only(rados_ioctx_t io, const char *id,
 658                                           rbd_image_t *image, const char *snap_name);
 659 CEPH_RBD_API int rbd_aio_open_read_only(rados_ioctx_t io, const char *name,
 660                                         rbd_image_t *image, const char *snap_name,
 661                                         rbd_completion_t c);
 662 CEPH_RBD_API int rbd_aio_open_by_id_read_only(rados_ioctx_t io, const char *id,
 663                                               rbd_image_t *image, const char *snap_name,
 664                                               rbd_completion_t c);
 665 CEPH_RBD_API int rbd_features_to_string(uint64_t features, char *str_features,
 666                                         size_t *size);
 667 CEPH_RBD_API int rbd_features_from_string(const char *str_features, uint64_t *features);
 668 CEPH_RBD_API int rbd_close(rbd_image_t image);
 669 CEPH_RBD_API int rbd_aio_close(rbd_image_t image, rbd_completion_t c);
 670 CEPH_RBD_API int rbd_resize(rbd_image_t image, uint64_t size);
 671 CEPH_RBD_API int rbd_resize2(rbd_image_t image, uint64_t size, bool allow_shrink,
 672                              librbd_progress_fn_t cb, void *cbdata);
 673 CEPH_RBD_API int rbd_resize_with_progress(rbd_image_t image, uint64_t size,
 674                              librbd_progress_fn_t cb, void *cbdata);
 675 CEPH_RBD_API int rbd_stat(rbd_image_t image, rbd_image_info_t *info,
 676                           size_t infosize);
 677 CEPH_RBD_API int rbd_get_old_format(rbd_image_t image, uint8_t *old);
 678 CEPH_RBD_API int rbd_get_size(rbd_image_t image, uint64_t *size);
 679 CEPH_RBD_API int rbd_get_features(rbd_image_t image, uint64_t *features);
 680 CEPH_RBD_API int rbd_update_features(rbd_image_t image, uint64_t features,
 681                                      uint8_t enabled);
 682 CEPH_RBD_API int rbd_get_op_features(rbd_image_t image, uint64_t *op_features);
 683 CEPH_RBD_API int rbd_get_stripe_unit(rbd_image_t image, uint64_t *stripe_unit);
 684 CEPH_RBD_API int rbd_get_stripe_count(rbd_image_t image,
 685                                       uint64_t *stripe_count);
 686
 687 CEPH_RBD_API int rbd_get_create_timestamp(rbd_image_t image,
 688                                           struct timespec *timestamp);
 689 CEPH_RBD_API int rbd_get_access_timestamp(rbd_image_t image,
 690                                           struct timespec *timestamp);
 691 CEPH_RBD_API int rbd_get_modify_timestamp(rbd_image_t image,
 692                                           struct timespec *timestamp);
 693
 694 CEPH_RBD_API int rbd_get_overlap(rbd_image_t image, uint64_t *overlap);
 695 CEPH_RBD_API int rbd_get_name(rbd_image_t image, char *name, size_t *name_len);
 696 CEPH_RBD_API int rbd_get_id(rbd_image_t image, char *id, size_t id_len);
 697 CEPH_RBD_API int rbd_get_block_name_prefix(rbd_image_t image,
 698                                            char *prefix, size_t prefix_len);
 699 CEPH_RBD_API int64_t rbd_get_data_pool_id(rbd_image_t image);
 700
 701 CEPH_RBD_API int rbd_get_parent_info(rbd_image_t image,
 702                                      char *parent_poolname, size_t ppoolnamelen,
 703                                      char *parent_name, size_t pnamelen,
 704                                      char *parent_snapname,
 705                                      size_t psnapnamelen)
 706   CEPH_RBD_DEPRECATED;
 707 CEPH_RBD_API int rbd_get_parent_info2(rbd_image_t image,
 708                                       char *parent_poolname,
 709                                       size_t ppoolnamelen,
 710                                       char *parent_name, size_t pnamelen,
 711                                       char *parent_id, size_t pidlen,
 712                                       char *parent_snapname,
 713                                       size_t psnapnamelen)
 714   CEPH_RBD_DEPRECATED;
 715 CEPH_RBD_API int rbd_get_parent(rbd_image_t image,
 716                                 rbd_linked_image_spec_t *parent_image,
 717                                 rbd_snap_spec_t *parent_snap);
 718
 719 CEPH_RBD_API int rbd_get_flags(rbd_image_t image, uint64_t *flags);
 720 CEPH_RBD_API int rbd_get_group(rbd_image_t image, rbd_group_info_t *group_info,
 721                                size_t group_info_size);
 722 CEPH_RBD_API int rbd_set_image_notification(rbd_image_t image, int fd, int type);
 723
 724 /* exclusive lock feature */
 725 CEPH_RBD_API int rbd_is_exclusive_lock_owner(rbd_image_t image, int *is_owner);
 726 CEPH_RBD_API int rbd_lock_acquire(rbd_image_t image, rbd_lock_mode_t lock_mode);
 727 CEPH_RBD_API int rbd_lock_release(rbd_image_t image);
 728 CEPH_RBD_API int rbd_lock_get_owners(rbd_image_t image,
 729                                      rbd_lock_mode_t *lock_mode,
 730                                      char **lock_owners,
 731                                      size_t *max_lock_owners);
 732 CEPH_RBD_API void rbd_lock_get_owners_cleanup(char **lock_owners,
 733                                               size_t lock_owner_count);
 734 CEPH_RBD_API int rbd_lock_break(rbd_image_t image, rbd_lock_mode_t lock_mode,
 735                                 const char *lock_owner);
 736
 737 /* object map feature */
 738 CEPH_RBD_API int rbd_rebuild_object_map(rbd_image_t image,
 739                                         librbd_progress_fn_t cb, void *cbdata);
 740
 741 CEPH_RBD_API int rbd_copy(rbd_image_t image, rados_ioctx_t dest_io_ctx,
 742                           const char *destname);
 743 CEPH_RBD_API int rbd_copy2(rbd_image_t src, rbd_image_t dest);
 744 CEPH_RBD_API int rbd_copy3(rbd_image_t src, rados_ioctx_t dest_io_ctx,
 745                            const char *destname, rbd_image_options_t dest_opts);
 746 CEPH_RBD_API int rbd_copy4(rbd_image_t src, rados_ioctx_t dest_io_ctx,
 747                            const char *destname, rbd_image_options_t dest_opts,
 748                            size_t sparse_size);
 749 CEPH_RBD_API int rbd_copy_with_progress(rbd_image_t image, rados_ioctx_t dest_p,
 750                                         const char *destname,
 751                                         librbd_progress_fn_t cb, void *cbdata);
 752 CEPH_RBD_API int rbd_copy_with_progress2(rbd_image_t src, rbd_image_t dest,
 753                                          librbd_progress_fn_t cb, void *cbdata);
 754 CEPH_RBD_API int rbd_copy_with_progress3(rbd_image_t image,
 755                                          rados_ioctx_t dest_p,
 756                                          const char *destname,
 757                                          rbd_image_options_t dest_opts,
 758                                          librbd_progress_fn_t cb, void *cbdata);
 759 CEPH_RBD_API int rbd_copy_with_progress4(rbd_image_t image,
 760                                          rados_ioctx_t dest_p,
 761                                          const char *destname,
 762                                          rbd_image_options_t dest_opts,
 763                                          librbd_progress_fn_t cb, void *cbdata,
 764                                          size_t sparse_size);
 765
 766 /* deep copy */
 767 CEPH_RBD_API int rbd_deep_copy(rbd_image_t src, rados_ioctx_t dest_io_ctx,
 768                                const char *destname,
 769                                rbd_image_options_t dest_opts);
 770 CEPH_RBD_API int rbd_deep_copy_with_progress(rbd_image_t image,
 771                                              rados_ioctx_t dest_io_ctx,
 772                                              const char *destname,
 773                                              rbd_image_options_t dest_opts,
 774                                              librbd_progress_fn_t cb,
 775                                              void *cbdata);
 776
 777 /* snapshots */
 778 CEPH_RBD_API int rbd_snap_list(rbd_image_t image, rbd_snap_info_t *snaps,
 779                                int *max_snaps);
 780 CEPH_RBD_API void rbd_snap_list_end(rbd_snap_info_t *snaps);
 781 CEPH_RBD_API int rbd_snap_exists(rbd_image_t image, const char *snapname, bool *exists);
 782 CEPH_RBD_API int rbd_snap_create(rbd_image_t image, const char *snapname);
 783 CEPH_RBD_API int rbd_snap_remove(rbd_image_t image, const char *snapname);
 784 CEPH_RBD_API int rbd_snap_remove2(rbd_image_t image, const char *snap_name,
 785                                   uint32_t flags, librbd_progress_fn_t cb,
 786                                   void *cbdata);
 787 CEPH_RBD_API int rbd_snap_remove_by_id(rbd_image_t image, uint64_t snap_id);
 788 CEPH_RBD_API int rbd_snap_rollback(rbd_image_t image, const char *snapname);
 789 CEPH_RBD_API int rbd_snap_rollback_with_progress(rbd_image_t image,
 790                                                  const char *snapname,
 791                                                  librbd_progress_fn_t cb,
 792                                                  void *cbdata);
 793 CEPH_RBD_API int rbd_snap_rename(rbd_image_t image, const char *snapname,
 794                                  const char* dstsnapsname);
 795 /**
 796  * Prevent a snapshot from being deleted until it is unprotected.
 797  *
 798  * @param snap_name which snapshot to protect
 799  * @returns 0 on success, negative error code on failure
 800  * @returns -EBUSY if snap is already protected
 801  */
 802 CEPH_RBD_API int rbd_snap_protect(rbd_image_t image, const char *snap_name);
 803 /**
 804  * Allow a snaphshot to be deleted.
 805  *
 806  * @param snap_name which snapshot to unprotect
 807  * @returns 0 on success, negative error code on failure
 808  * @returns -EINVAL if snap is not protected
 809  */
 810 CEPH_RBD_API int rbd_snap_unprotect(rbd_image_t image, const char *snap_name);
 811 /**
 812  * Determine whether a snapshot is protected.
 813  *
 814  * @param snap_name which snapshot query
 815  * @param is_protected where to store the result (0 or 1)
 816  * @returns 0 on success, negative error code on failure
 817  */
 818 CEPH_RBD_API int rbd_snap_is_protected(rbd_image_t image, const char *snap_name,
 819                                        int *is_protected);
 820 /**
 821  * Get the current snapshot limit for an image. If no limit is set,
 822  * UINT64_MAX is returned.
 823  *
 824  * @param limit pointer where the limit will be stored on success
 825  * @returns 0 on success, negative error code on failure
 826  */
 827 CEPH_RBD_API int rbd_snap_get_limit(rbd_image_t image, uint64_t *limit);
 828
 829 /**
 830  * Set a limit for the number of snapshots that may be taken of an image.
 831  *
 832  * @param limit the maximum number of snapshots allowed in the future.
 833  * @returns 0 on success, negative error code on failure
 834  */
 835 CEPH_RBD_API int rbd_snap_set_limit(rbd_image_t image, uint64_t limit);
 836
 837 /**
 838  * Get the timestamp of a snapshot for an image.
 839  *
 840  * @param snap_id the snap id of a snapshot of input image.
 841  * @param timestamp the timestamp of input snapshot.
 842  * @returns 0 on success, negative error code on failure
 843  */
 844 CEPH_RBD_API int rbd_snap_get_timestamp(rbd_image_t image, uint64_t snap_id, struct timespec *timestamp);
 845
 846 CEPH_RBD_API int rbd_snap_set(rbd_image_t image, const char *snapname);
 847 CEPH_RBD_API int rbd_snap_set_by_id(rbd_image_t image, uint64_t snap_id);
 848 CEPH_RBD_API int rbd_snap_get_name(rbd_image_t image, uint64_t snap_id, char *snapname, size_t *name_len);
 849 CEPH_RBD_API int rbd_snap_get_id(rbd_image_t image, const char *snapname, uint64_t *snap_id);
 850
 851 CEPH_RBD_API int rbd_snap_get_namespace_type(rbd_image_t image,
 852                                              uint64_t snap_id,
 853                                              rbd_snap_namespace_type_t *namespace_type);
 854 CEPH_RBD_API int rbd_snap_get_group_namespace(rbd_image_t image,
 855                                               uint64_t snap_id,
 856                                               rbd_snap_group_namespace_t *group_snap,
 857                                               size_t group_snap_size);
 858 CEPH_RBD_API int rbd_snap_group_namespace_cleanup(rbd_snap_group_namespace_t *group_snap,
 859                                                   size_t group_snap_size);
 860 CEPH_RBD_API int rbd_snap_get_trash_namespace(rbd_image_t image,
 861                                               uint64_t snap_id,
 862                                               char* original_name,
 863                                               size_t max_length);
 864 CEPH_RBD_API int rbd_snap_get_mirror_namespace(
 865     rbd_image_t image, uint64_t snap_id,
 866     rbd_snap_mirror_namespace_t *mirror_snap, size_t mirror_snap_size);
 867 CEPH_RBD_API int rbd_snap_mirror_namespace_cleanup(
 868     rbd_snap_mirror_namespace_t *mirror_snap, size_t mirror_snap_size);
 869
 870 CEPH_RBD_API int rbd_flatten(rbd_image_t image);
 871
 872 CEPH_RBD_API int rbd_flatten_with_progress(rbd_image_t image,
 873                                            librbd_progress_fn_t cb,
 874                                            void *cbdata);
 875
 876 CEPH_RBD_API int rbd_sparsify(rbd_image_t image, size_t sparse_size);
 877
 878 CEPH_RBD_API int rbd_sparsify_with_progress(rbd_image_t image,
 879                                             size_t sparse_size,
 880                                             librbd_progress_fn_t cb,
 881                                             void *cbdata);
 882
 883 /**
 884  * List all images that are cloned from the image at the
 885  * snapshot that is set via rbd_snap_set().
 886  *
 887  * This iterates over all pools, so it should be run by a user with
 888  * read access to all of them. pools_len and images_len are filled in
 889  * with the number of bytes put into the pools and images buffers.
 890  *
 891  * If the provided buffers are too short, the required lengths are
 892  * still filled in, but the data is not and -ERANGE is returned.
 893  * Otherwise, the buffers are filled with the pool and image names
 894  * of the children, with a '\0' after each.
 895  *
 896  * @param image which image (and implicitly snapshot) to list clones of
 897  * @param pools buffer in which to store pool names
 898  * @param pools_len number of bytes in pools buffer
 899  * @param images buffer in which to store image names
 900  * @param images_len number of bytes in images buffer
 901  * @returns number of children on success, negative error code on failure
 902  * @returns -ERANGE if either buffer is too short
 903  */
 904 CEPH_RBD_API ssize_t rbd_list_children(rbd_image_t image, char *pools,
 905                                        size_t *pools_len, char *images,
 906                                        size_t *images_len)
 907   CEPH_RBD_DEPRECATED;
 908 CEPH_RBD_API int rbd_list_children2(rbd_image_t image,
 909                                     rbd_child_info_t *children,
 910                                     int *max_children)
 911   CEPH_RBD_DEPRECATED;
 912 CEPH_RBD_API void rbd_list_child_cleanup(rbd_child_info_t *child)
 913   CEPH_RBD_DEPRECATED;
 914 CEPH_RBD_API void rbd_list_children_cleanup(rbd_child_info_t *children,
 915                                             size_t num_children)
 916   CEPH_RBD_DEPRECATED;
 917
 918 CEPH_RBD_API int rbd_list_children3(rbd_image_t image,
 919                                     rbd_linked_image_spec_t *images,
 920                                     size_t *max_images);
 921
 922 CEPH_RBD_API int rbd_list_descendants(rbd_image_t image,
 923                                       rbd_linked_image_spec_t *images,
 924                                       size_t *max_images);
 925
 926 /**
 927  * @defgroup librbd_h_locking Advisory Locking
 928  *
 929  * An rbd image may be locking exclusively, or shared, to facilitate
 930  * e.g. live migration where the image may be open in two places at once.
 931  * These locks are intended to guard against more than one client
 932  * writing to an image without coordination. They don't need to
 933  * be used for snapshots, since snapshots are read-only.
 934  *
 935  * Currently locks only guard against locks being acquired.
 936  * They do not prevent anything else.
 937  *
 938  * A locker is identified by the internal rados client id of the
 939  * holder and a user-defined cookie. This (client id, cookie) pair
 940  * must be unique for each locker.
 941  *
 942  * A shared lock also has a user-defined tag associated with it. Each
 943  * additional shared lock must specify the same tag or lock
 944  * acquisition will fail. This can be used by e.g. groups of hosts
 945  * using a clustered filesystem on top of an rbd image to make sure
 946  * they're accessing the correct image.
 947  *
 948  * @{
 949  */
 950 /**
 951  * List clients that have locked the image and information about the lock.
 952  *
 953  * The number of bytes required in each buffer is put in the
 954  * corresponding size out parameter. If any of the provided buffers
 955  * are too short, -ERANGE is returned after these sizes are filled in.
 956  *
 957  * @param exclusive where to store whether the lock is exclusive (1) or shared (0)
 958  * @param tag where to store the tag associated with the image
 959  * @param tag_len number of bytes in tag buffer
 960  * @param clients buffer in which locker clients are stored, separated by '\0'
 961  * @param clients_len number of bytes in the clients buffer
 962  * @param cookies buffer in which locker cookies are stored, separated by '\0'
 963  * @param cookies_len number of bytes in the cookies buffer
 964  * @param addrs buffer in which locker addresses are stored, separated by '\0'
 965  * @param addrs_len number of bytes in the clients buffer
 966  * @returns number of lockers on success, negative error code on failure
 967  * @returns -ERANGE if any of the buffers are too short
 968  */
 969 CEPH_RBD_API ssize_t rbd_list_lockers(rbd_image_t image, int *exclusive,
 970                                       char *tag, size_t *tag_len,
 971                                       char *clients, size_t *clients_len,
 972                                       char *cookies, size_t *cookies_len,
 973                                       char *addrs, size_t *addrs_len);
 974
 975 /**
 976  * Take an exclusive lock on the image.
 977  *
 978  * @param image the image to lock
 979  * @param cookie user-defined identifier for this instance of the lock
 980  * @returns 0 on success, negative error code on failure
 981  * @returns -EBUSY if the lock is already held by another (client, cookie) pair
 982  * @returns -EEXIST if the lock is already held by the same (client, cookie) pair
 983  */
 984 CEPH_RBD_API int rbd_lock_exclusive(rbd_image_t image, const char *cookie);
 985
 986 /**
 987  * Take a shared lock on the image.
 988  *
 989  * Other clients may also take a shared lock, as lock as they use the
 990  * same tag.
 991  *
 992  * @param image the image to lock
 993  * @param cookie user-defined identifier for this instance of the lock
 994  * @param tag user-defined identifier for this shared use of the lock
 995  * @returns 0 on success, negative error code on failure
 996  * @returns -EBUSY if the lock is already held by another (client, cookie) pair
 997  * @returns -EEXIST if the lock is already held by the same (client, cookie) pair
 998  */
 999 CEPH_RBD_API int rbd_lock_shared(rbd_image_t image, const char *cookie,
1000                                  const char *tag);
1001
1002 /**
1003  * Release a shared or exclusive lock on the image.
1004  *
1005  * @param image the image to unlock
1006  * @param cookie user-defined identifier for the instance of the lock
1007  * @returns 0 on success, negative error code on failure
1008  * @returns -ENOENT if the lock is not held by the specified (client, cookie) pair
1009  */
1010 CEPH_RBD_API int rbd_unlock(rbd_image_t image, const char *cookie);
1011
1012 /**
1013  * Release a shared or exclusive lock that was taken by the specified client.
1014  *
1015  * @param image the image to unlock
1016  * @param client the entity holding the lock (as given by rbd_list_lockers())
1017  * @param cookie user-defined identifier for the instance of the lock to break
1018  * @returns 0 on success, negative error code on failure
1019  * @returns -ENOENT if the lock is not held by the specified (client, cookie) pair
1020  */
1021 CEPH_RBD_API int rbd_break_lock(rbd_image_t image, const char *client,
1022                                 const char *cookie);
1023
1024 /** @} locking */
1025
1026 /* I/O */
1027 CEPH_RBD_API ssize_t rbd_read(rbd_image_t image, uint64_t ofs, size_t len,
1028                               char *buf);
1029 /*
1030  * @param op_flags: see librados.h constants beginning with LIBRADOS_OP_FLAG
1031  */
1032 CEPH_RBD_API ssize_t rbd_read2(rbd_image_t image, uint64_t ofs, size_t len,
1033                                char *buf, int op_flags);
1034 /* DEPRECATED; use rbd_read_iterate2 */
1035 CEPH_RBD_API int64_t rbd_read_iterate(rbd_image_t image, uint64_t ofs, size_t len,
1036                                       int (*cb)(uint64_t, size_t, const char *, void *),
1037                                       void *arg);
1038
1039 /**
1040  * iterate read over an image
1041  *
1042  * Reads each region of the image and calls the callback.  If the
1043  * buffer pointer passed to the callback is NULL, the given extent is
1044  * defined to be zeros (a hole).  Normally the granularity for the
1045  * callback is the image stripe size.
1046  *
1047  * @param image image to read
1048  * @param ofs offset to start from
1049  * @param len bytes of source image to cover
1050  * @param cb callback for each region
1051  * @returns 0 success, error otherwise
1052  */
1053 CEPH_RBD_API int rbd_read_iterate2(rbd_image_t image, uint64_t ofs, uint64_t len,
1054                                    int (*cb)(uint64_t, size_t, const char *, void *),
1055                                    void *arg);
1056 /**
1057  * get difference between two versions of an image
1058  *
1059  * This will return the differences between two versions of an image
1060  * via a callback, which gets the offset and length and a flag
1061  * indicating whether the extent exists (1), or is known/defined to
1062  * be zeros (a hole, 0).  If the source snapshot name is NULL, we
1063  * interpret that as the beginning of time and return all allocated
1064  * regions of the image.  The end version is whatever is currently
1065  * selected for the image handle (either a snapshot or the writeable
1066  * head).
1067  *
1068  * @param fromsnapname start snapshot name, or NULL
1069  * @param ofs start offset
1070  * @param len len in bytes of region to report on
1071  * @param include_parent 1 if full history diff should include parent
1072  * @param whole_object 1 if diff extents should cover whole object
1073  * @param cb callback to call for each allocated region
1074  * @param arg argument to pass to the callback
1075  * @returns 0 on success, or negative error code on error
1076  */
1077 CEPH_RBD_API int rbd_diff_iterate(rbd_image_t image,
1078                                   const char *fromsnapname,
1079                                   uint64_t ofs, uint64_t len,
1080                                   int (*cb)(uint64_t, size_t, int, void *),
1081                                   void *arg);
1082 CEPH_RBD_API int rbd_diff_iterate2(rbd_image_t image,
1083                                    const char *fromsnapname,
1084                                    uint64_t ofs, uint64_t len,
1085                                    uint8_t include_parent, uint8_t whole_object,
1086                                    int (*cb)(uint64_t, size_t, int, void *),
1087                                    void *arg);
1088 CEPH_RBD_API ssize_t rbd_write(rbd_image_t image, uint64_t ofs, size_t len,
1089                                const char *buf);
1090 /*
1091  * @param op_flags: see librados.h constants beginning with LIBRADOS_OP_FLAG
1092  */
1093 CEPH_RBD_API ssize_t rbd_write2(rbd_image_t image, uint64_t ofs, size_t len,
1094                                 const char *buf, int op_flags);
1095 CEPH_RBD_API int rbd_discard(rbd_image_t image, uint64_t ofs, uint64_t len);
1096 CEPH_RBD_API ssize_t rbd_writesame(rbd_image_t image, uint64_t ofs, size_t len,
1097                                    const char *buf, size_t data_len, int op_flags);
1098 CEPH_RBD_API ssize_t rbd_compare_and_write(rbd_image_t image, uint64_t ofs,
1099                                            size_t len, const char *cmp_buf,
1100                                            const char *buf, uint64_t *mismatch_off,
1101                                            int op_flags);
1102
1103 CEPH_RBD_API int rbd_aio_write(rbd_image_t image, uint64_t off, size_t len,
1104                                const char *buf, rbd_completion_t c);
1105
1106 /*
1107  * @param op_flags: see librados.h constants beginning with LIBRADOS_OP_FLAG
1108  */
1109 CEPH_RBD_API int rbd_aio_write2(rbd_image_t image, uint64_t off, size_t len,
1110                                 const char *buf, rbd_completion_t c,
1111                                 int op_flags);
1112 CEPH_RBD_API int rbd_aio_writev(rbd_image_t image, const struct iovec *iov,
1113                                 int iovcnt, uint64_t off, rbd_completion_t c);
1114 CEPH_RBD_API int rbd_aio_read(rbd_image_t image, uint64_t off, size_t len,
1115                               char *buf, rbd_completion_t c);
1116 /*
1117  * @param op_flags: see librados.h constants beginning with LIBRADOS_OP_FLAG
1118  */
1119 CEPH_RBD_API int rbd_aio_read2(rbd_image_t image, uint64_t off, size_t len,
1120                                char *buf, rbd_completion_t c, int op_flags);
1121 CEPH_RBD_API int rbd_aio_readv(rbd_image_t image, const struct iovec *iov,
1122                                int iovcnt, uint64_t off, rbd_completion_t c);
1123 CEPH_RBD_API int rbd_aio_discard(rbd_image_t image, uint64_t off, uint64_t len,
1124                                  rbd_completion_t c);
1125 CEPH_RBD_API int rbd_aio_writesame(rbd_image_t image, uint64_t off, size_t len,
1126                                    const char *buf, size_t data_len,
1127                                    rbd_completion_t c, int op_flags);
1128 CEPH_RBD_API ssize_t rbd_aio_compare_and_write(rbd_image_t image,
1129                                                uint64_t off, size_t len,
1130                                                const char *cmp_buf, const char *buf,
1131                                                rbd_completion_t c, uint64_t *mismatch_off,
1132                                                int op_flags);
1133
1134 CEPH_RBD_API int rbd_aio_create_completion(void *cb_arg,
1135                                            rbd_callback_t complete_cb,
1136                                            rbd_completion_t *c);
1137 CEPH_RBD_API int rbd_aio_is_complete(rbd_completion_t c);
1138 CEPH_RBD_API int rbd_aio_wait_for_complete(rbd_completion_t c);
1139 CEPH_RBD_API ssize_t rbd_aio_get_return_value(rbd_completion_t c);
1140 CEPH_RBD_API void *rbd_aio_get_arg(rbd_completion_t c);
1141 CEPH_RBD_API void rbd_aio_release(rbd_completion_t c);
1142 CEPH_RBD_API int rbd_flush(rbd_image_t image);
1143 /**
1144  * Start a flush if caching is enabled. Get a callback when
1145  * the currently pending writes are on disk.
1146  *
1147  * @param image the image to flush writes to
1148  * @param c what to call when flushing is complete
1149  * @returns 0 on success, negative error code on failure
1150  */
1151 CEPH_RBD_API int rbd_aio_flush(rbd_image_t image, rbd_completion_t c);
1152
1153 /**
1154  * Drop any cached data for an image
1155  *
1156  * @param image the image to invalidate cached data for
1157  * @returns 0 on success, negative error code on failure
1158  */
1159 CEPH_RBD_API int rbd_invalidate_cache(rbd_image_t image);
1160
1161 CEPH_RBD_API int rbd_poll_io_events(rbd_image_t image, rbd_completion_t *comps, int numcomp);
1162
1163 CEPH_RBD_API int rbd_metadata_get(rbd_image_t image, const char *key, char *value, size_t *val_len);
1164 CEPH_RBD_API int rbd_metadata_set(rbd_image_t image, const char *key, const char *value);
1165 CEPH_RBD_API int rbd_metadata_remove(rbd_image_t image, const char *key);
1166 /**
1167  * List all metadatas associated with this image.
1168  *
1169  * This iterates over all metadatas, key_len and val_len are filled in
1170  * with the number of bytes put into the keys and values buffers.
1171  *
1172  * If the provided buffers are too short, the required lengths are
1173  * still filled in, but the data is not and -ERANGE is returned.
1174  * Otherwise, the buffers are filled with the keys and values
1175  * of the image, with a '\0' after each.
1176  *
1177  * @param image which image (and implicitly snapshot) to list clones of
1178  * @param start_after which name to begin listing after
1179  *        (use the empty string to start at the beginning)
1180  * @param max the maximum number of names to lis(if 0 means no limit)
1181  * @param keys buffer in which to store pool names
1182  * @param keys_len number of bytes in pools buffer
1183  * @param values buffer in which to store image names
1184  * @param vals_len number of bytes in images buffer
1185  * @returns number of children on success, negative error code on failure
1186  * @returns -ERANGE if either buffer is too short
1187  */
1188 CEPH_RBD_API int rbd_metadata_list(rbd_image_t image, const char *start, uint64_t max,
1189     char *keys, size_t *key_len, char *values, size_t *vals_len);
1190
1191 // RBD image mirroring support functions
1192 CEPH_RBD_API int rbd_mirror_image_enable(rbd_image_t image) CEPH_RBD_DEPRECATED;
1193 CEPH_RBD_API int rbd_mirror_image_enable2(rbd_image_t image,
1194                                           rbd_mirror_image_mode_t mode);
1195 CEPH_RBD_API int rbd_mirror_image_disable(rbd_image_t image, bool force);
1196 CEPH_RBD_API int rbd_mirror_image_promote(rbd_image_t image, bool force);
1197 CEPH_RBD_API int rbd_mirror_image_demote(rbd_image_t image);
1198 CEPH_RBD_API int rbd_mirror_image_resync(rbd_image_t image);
1199 CEPH_RBD_API int rbd_mirror_image_create_snapshot(rbd_image_t image,
1200                                                   uint64_t *snap_id);
1201 CEPH_RBD_API int rbd_mirror_image_get_info(rbd_image_t image,
1202                                            rbd_mirror_image_info_t *mirror_image_info,
1203                                            size_t info_size);
1204 CEPH_RBD_API void rbd_mirror_image_get_info_cleanup(
1205     rbd_mirror_image_info_t *mirror_image_info);
1206 CEPH_RBD_API int rbd_mirror_image_get_mode(rbd_image_t image,
1207                                            rbd_mirror_image_mode_t *mode);
1208
1209 CEPH_RBD_API int rbd_mirror_image_get_global_status(
1210     rbd_image_t image,
1211     rbd_mirror_image_global_status_t *mirror_image_global_status,
1212     size_t status_size);
1213 CEPH_RBD_API void rbd_mirror_image_global_status_cleanup(
1214     rbd_mirror_image_global_status_t *mirror_image_global_status);
1215
1216 CEPH_RBD_API int rbd_mirror_image_get_status(
1217     rbd_image_t image, rbd_mirror_image_status_t *mirror_image_status,
1218     size_t status_size)
1219   CEPH_RBD_DEPRECATED;
1220
1221 CEPH_RBD_API int rbd_mirror_image_get_instance_id(rbd_image_t image,
1222                                                   char *instance_id,
1223                                                   size_t *id_max_length);
1224 CEPH_RBD_API int rbd_aio_mirror_image_promote(rbd_image_t image, bool force,
1225                                               rbd_completion_t c);
1226 CEPH_RBD_API int rbd_aio_mirror_image_demote(rbd_image_t image,
1227                                              rbd_completion_t c);
1228 CEPH_RBD_API int rbd_aio_mirror_image_get_info(rbd_image_t image,
1229                                                rbd_mirror_image_info_t *mirror_image_info,
1230                                                size_t info_size,
1231                                                rbd_completion_t c);
1232
1233 CEPH_RBD_API int rbd_aio_mirror_image_get_global_status(
1234     rbd_image_t image,
1235     rbd_mirror_image_global_status_t *mirror_global_image_status,
1236     size_t status_size, rbd_completion_t c);
1237 CEPH_RBD_API int rbd_aio_mirror_image_get_status(
1238     rbd_image_t image, rbd_mirror_image_status_t *mirror_image_status,
1239     size_t status_size, rbd_completion_t c)
1240   CEPH_RBD_DEPRECATED;
1241
1242 // RBD groups support functions
1243 CEPH_RBD_API int rbd_group_create(rados_ioctx_t p, const char *name);
1244 CEPH_RBD_API int rbd_group_remove(rados_ioctx_t p, const char *name);
1245 CEPH_RBD_API int rbd_group_list(rados_ioctx_t p, char *names, size_t *size);
1246 CEPH_RBD_API int rbd_group_rename(rados_ioctx_t p, const char *src_name,
1247                                   const char *dest_name);
1248 CEPH_RBD_API int rbd_group_info_cleanup(rbd_group_info_t *group_info,
1249                                         size_t group_info_size);
1250
1251 /**
1252  * Register an image metadata change watcher.
1253  *
1254  * @param image the image to watch
1255  * @param handle where to store the internal id assigned to this watch
1256  * @param watch_cb what to do when a notify is received on this image
1257  * @param arg opaque value to pass to the callback
1258  * @returns 0 on success, negative error code on failure
1259  */
1260 CEPH_RBD_API int rbd_update_watch(rbd_image_t image, uint64_t *handle,
1261                                   rbd_update_callback_t watch_cb, void *arg);
1262
1263 /**
1264  * Unregister an image watcher.
1265  *
1266  * @param image the image to unwatch
1267  * @param handle which watch to unregister
1268  * @returns 0 on success, negative error code on failure
1269  */
1270 CEPH_RBD_API int rbd_update_unwatch(rbd_image_t image, uint64_t handle);
1271
1272 /**
1273  * List any watchers of an image.
1274  *
1275  * Watchers will be allocated and stored in the passed watchers array. If there
1276  * are more watchers than max_watchers, -ERANGE will be returned and the number
1277  * of watchers will be stored in max_watchers.
1278  *
1279  * The caller should call rbd_watchers_list_cleanup when finished with the list
1280  * of watchers.
1281  *
1282  * @param image the image to list watchers for.
1283  * @param watchers an array to store watchers in.
1284  * @param max_watchers capacity of the watchers array.
1285  * @returns 0 on success, negative error code on failure.
1286  * @returns -ERANGE if there are too many watchers for the passed array.
1287  * @returns the number of watchers in max_watchers.
1288  */
1289 CEPH_RBD_API int rbd_watchers_list(rbd_image_t image,
1290                                    rbd_image_watcher_t *watchers,
1291                                    size_t *max_watchers);
1292
1293 CEPH_RBD_API void rbd_watchers_list_cleanup(rbd_image_watcher_t *watchers,
1294                                             size_t num_watchers);
1295
1296 CEPH_RBD_API int rbd_config_image_list(rbd_image_t image,
1297                                        rbd_config_option_t *options,
1298                                        int *max_options);
1299 CEPH_RBD_API void rbd_config_image_list_cleanup(rbd_config_option_t *options,
1300                                                 int max_options);
1301
1302 CEPH_RBD_API int rbd_group_image_add(rados_ioctx_t group_p,
1303                                      const char *group_name,
1304                                      rados_ioctx_t image_p,
1305                                      const char *image_name);
1306 CEPH_RBD_API int rbd_group_image_remove(rados_ioctx_t group_p,
1307                                         const char *group_name,
1308                                         rados_ioctx_t image_p,
1309                                         const char *image_name);
1310 CEPH_RBD_API int rbd_group_image_remove_by_id(rados_ioctx_t group_p,
1311                                               const char *group_name,
1312                                               rados_ioctx_t image_p,
1313                                               const char *image_id);
1314 CEPH_RBD_API int rbd_group_image_list(rados_ioctx_t group_p,
1315                                       const char *group_name,
1316                                       rbd_group_image_info_t *images,
1317                                       size_t group_image_info_size,
1318                                       size_t *num_entries);
1319 CEPH_RBD_API int rbd_group_image_list_cleanup(rbd_group_image_info_t *images,
1320                                               size_t group_image_info_size,
1321                                               size_t num_entries);
1322
1323 CEPH_RBD_API int rbd_group_snap_create(rados_ioctx_t group_p,
1324                                        const char *group_name,
1325                                        const char *snap_name);
1326 CEPH_RBD_API int rbd_group_snap_remove(rados_ioctx_t group_p,
1327                                        const char *group_name,
1328                                        const char *snap_name);
1329 CEPH_RBD_API int rbd_group_snap_rename(rados_ioctx_t group_p,
1330                                        const char *group_name,
1331                                        const char *old_snap_name,
1332                                        const char *new_snap_name);
1333 CEPH_RBD_API int rbd_group_snap_list(rados_ioctx_t group_p,
1334                                      const char *group_name,
1335                                      rbd_group_snap_info_t *snaps,
1336                                      size_t group_snap_info_size,
1337                                      size_t *num_entries);
1338 CEPH_RBD_API int rbd_group_snap_list_cleanup(rbd_group_snap_info_t *snaps,
1339                                              size_t group_snap_info_size,
1340                                              size_t num_entries);
1341 CEPH_RBD_API int rbd_group_snap_rollback(rados_ioctx_t group_p,
1342                                          const char *group_name,
1343                                          const char *snap_name);
1344 CEPH_RBD_API int rbd_group_snap_rollback_with_progress(rados_ioctx_t group_p,
1345                                                        const char *group_name,
1346                                                        const char *snap_name,
1347                                                        librbd_progress_fn_t cb,
1348                                                        void *cbdata);
1349
1350 CEPH_RBD_API int rbd_namespace_create(rados_ioctx_t io,
1351                                       const char *namespace_name);
1352 CEPH_RBD_API int rbd_namespace_remove(rados_ioctx_t io,
1353                                       const char *namespace_name);
1354 CEPH_RBD_API int rbd_namespace_list(rados_ioctx_t io, char *namespace_names,
1355                                     size_t *size);
1356 CEPH_RBD_API int rbd_namespace_exists(rados_ioctx_t io,
1357                                       const char *namespace_name,
1358                                       bool *exists);
1359
1360 CEPH_RBD_API int rbd_pool_init(rados_ioctx_t io, bool force);
1361
1362 CEPH_RBD_API void rbd_pool_stats_create(rbd_pool_stats_t *stats);
1363 CEPH_RBD_API void rbd_pool_stats_destroy(rbd_pool_stats_t stats);
1364 CEPH_RBD_API int rbd_pool_stats_option_add_uint64(rbd_pool_stats_t stats,
1365                                                   int stat_option,
1366                                                   uint64_t* stat_val);
1367 CEPH_RBD_API int rbd_pool_stats_get(rados_ioctx_t io, rbd_pool_stats_t stats);
1368
1369 #if __GNUC__ >= 4
1370   #pragma GCC diagnostic pop
1371 #endif
1372
1373 #ifdef __cplusplus
1374 }
1375 #endif
1376
1377 #endif /* CEPH_LIBRBD_H */