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