src/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_LOCKING 1
  45 #define LIBRBD_SUPPORTS_INVALIDATE 1
  46 #define LIBRBD_SUPPORTS_IOVEC 1
  47 #define LIBRBD_SUPPORTS_WATCH 0
  48 #define LIBRBD_SUPPORTS_WRITESAME 1
  49
  50 #if __GNUC__ >= 4
  51   #define CEPH_RBD_API    __attribute__ ((visibility ("default")))
  52 #else
  53   #define CEPH_RBD_API
  54 #endif
  55
  56 #define RBD_FLAG_OBJECT_MAP_INVALID   (1<<0)
  57 #define RBD_FLAG_FAST_DIFF_INVALID    (1<<1)
  58
  59 typedef void *rbd_snap_t;
  60 typedef void *rbd_image_t;
  61 typedef void *rbd_image_options_t;
  62
  63 typedef void *rbd_completion_t;
  64 typedef void (*rbd_callback_t)(rbd_completion_t cb, void *arg);
  65
  66 typedef int (*librbd_progress_fn_t)(uint64_t offset, uint64_t total, void *ptr);
  67
  68 typedef void (*rbd_update_callback_t)(void *arg);
  69
  70 typedef struct {
  71   uint64_t id;
  72   uint64_t size;
  73   const char *name;
  74 } rbd_snap_info_t;
  75
  76 #define RBD_MAX_IMAGE_NAME_SIZE 96
  77 #define RBD_MAX_BLOCK_NAME_SIZE 24
  78
  79 #define RBD_SNAP_REMOVE_UNPROTECT       1 << 0
  80 #define RBD_SNAP_REMOVE_FLATTEN         1 << 1
  81 #define RBD_SNAP_REMOVE_FORCE           (RBD_SNAP_REMOVE_UNPROTECT | RBD_SNAP_REMOVE_FLATTEN)
  82
  83 /**
  84  * These types used to in set_image_notification to indicate the type of event
  85  * socket passed in.
  86  */
  87 enum {
  88   EVENT_TYPE_PIPE = 1,
  89   EVENT_TYPE_EVENTFD = 2
  90 };
  91
  92 typedef struct {
  93   uint64_t size;
  94   uint64_t obj_size;
  95   uint64_t num_objs;
  96   int order;
  97   char block_name_prefix[RBD_MAX_BLOCK_NAME_SIZE]; /* deprecated */
  98   int64_t parent_pool;                             /* deprecated */
  99   char parent_name[RBD_MAX_IMAGE_NAME_SIZE];       /* deprecated */
 100 } rbd_image_info_t;
 101
 102 typedef enum {
 103   RBD_MIRROR_MODE_DISABLED, /* mirroring is disabled */
 104   RBD_MIRROR_MODE_IMAGE,    /* mirroring enabled on a per-image basis */
 105   RBD_MIRROR_MODE_POOL      /* mirroring enabled on all journaled images */
 106 } rbd_mirror_mode_t;
 107
 108 typedef struct {
 109   char *uuid;
 110   char *cluster_name;
 111   char *client_name;
 112 } rbd_mirror_peer_t;
 113
 114 typedef enum {
 115   RBD_MIRROR_IMAGE_DISABLING = 0,
 116   RBD_MIRROR_IMAGE_ENABLED = 1,
 117   RBD_MIRROR_IMAGE_DISABLED = 2
 118 } rbd_mirror_image_state_t;
 119
 120 typedef struct {
 121   char *global_id;
 122   rbd_mirror_image_state_t state;
 123   bool primary;
 124 } rbd_mirror_image_info_t;
 125
 126 typedef enum {
 127   MIRROR_IMAGE_STATUS_STATE_UNKNOWN         = 0,
 128   MIRROR_IMAGE_STATUS_STATE_ERROR           = 1,
 129   MIRROR_IMAGE_STATUS_STATE_SYNCING         = 2,
 130   MIRROR_IMAGE_STATUS_STATE_STARTING_REPLAY = 3,
 131   MIRROR_IMAGE_STATUS_STATE_REPLAYING       = 4,
 132   MIRROR_IMAGE_STATUS_STATE_STOPPING_REPLAY = 5,
 133   MIRROR_IMAGE_STATUS_STATE_STOPPED         = 6,
 134 } rbd_mirror_image_status_state_t;
 135
 136 typedef struct {
 137   char *name;
 138   rbd_mirror_image_info_t info;
 139   rbd_mirror_image_status_state_t state;
 140   char *description;
 141   time_t last_update;
 142   bool up;
 143 } rbd_mirror_image_status_t;
 144
 145 typedef enum {
 146   RBD_LOCK_MODE_EXCLUSIVE = 0,
 147   RBD_LOCK_MODE_SHARED = 1,
 148 } rbd_lock_mode_t;
 149
 150 CEPH_RBD_API void rbd_version(int *major, int *minor, int *extra);
 151
 152 /* image options */
 153 enum {
 154   RBD_IMAGE_OPTION_FORMAT = 0,
 155   RBD_IMAGE_OPTION_FEATURES = 1,
 156   RBD_IMAGE_OPTION_ORDER = 2,
 157   RBD_IMAGE_OPTION_STRIPE_UNIT = 3,
 158   RBD_IMAGE_OPTION_STRIPE_COUNT = 4,
 159   RBD_IMAGE_OPTION_JOURNAL_ORDER = 5,
 160   RBD_IMAGE_OPTION_JOURNAL_SPLAY_WIDTH = 6,
 161   RBD_IMAGE_OPTION_JOURNAL_POOL = 7,
 162   RBD_IMAGE_OPTION_FEATURES_SET = 8,
 163   RBD_IMAGE_OPTION_FEATURES_CLEAR = 9,
 164   RBD_IMAGE_OPTION_DATA_POOL = 10
 165 };
 166
 167 typedef enum {
 168   RBD_TRASH_IMAGE_SOURCE_USER = 0,
 169   RBD_TRASH_IMAGE_SOURCE_MIRRORING = 1
 170 } rbd_trash_image_source_t;
 171
 172 typedef struct {
 173   char *id;
 174   char *name;
 175   rbd_trash_image_source_t source;
 176   time_t deletion_time;
 177   time_t deferment_end_time;
 178 } rbd_trash_image_info_t;
 179
 180 CEPH_RBD_API void rbd_image_options_create(rbd_image_options_t* opts);
 181 CEPH_RBD_API void rbd_image_options_destroy(rbd_image_options_t opts);
 182 CEPH_RBD_API int rbd_image_options_set_string(rbd_image_options_t opts,
 183                                               int optname, const char* optval);
 184 CEPH_RBD_API int rbd_image_options_set_uint64(rbd_image_options_t opts,
 185                                               int optname, uint64_t optval);
 186 CEPH_RBD_API int rbd_image_options_get_string(rbd_image_options_t opts,
 187                                               int optname, char* optval,
 188                                               size_t maxlen);
 189 CEPH_RBD_API int rbd_image_options_get_uint64(rbd_image_options_t opts,
 190                                               int optname, uint64_t* optval);
 191 CEPH_RBD_API int rbd_image_options_is_set(rbd_image_options_t opts,
 192                                           int optname, bool* is_set);
 193 CEPH_RBD_API int rbd_image_options_unset(rbd_image_options_t opts, int optname);
 194 CEPH_RBD_API void rbd_image_options_clear(rbd_image_options_t opts);
 195 CEPH_RBD_API int rbd_image_options_is_empty(rbd_image_options_t opts);
 196
 197 /* images */
 198 CEPH_RBD_API int rbd_list(rados_ioctx_t io, char *names, size_t *size);
 199 CEPH_RBD_API int rbd_create(rados_ioctx_t io, const char *name, uint64_t size,
 200                             int *order);
 201 CEPH_RBD_API int rbd_create2(rados_ioctx_t io, const char *name, uint64_t size,
 202                              uint64_t features, int *order);
 203 /**
 204  * create new rbd image
 205  *
 206  * The stripe_unit must be a factor of the object size (1 << order).
 207  * The stripe_count can be one (no intra-object striping) or greater
 208  * than one.  The RBD_FEATURE_STRIPINGV2 must be specified if the
 209  * stripe_unit != the object size and the stripe_count is != 1.
 210  *
 211  * @param io ioctx
 212  * @param name image name
 213  * @param size image size in bytes
 214  * @param features initial feature bits
 215  * @param order object/block size, as a power of two (object size == 1 << order)
 216  * @param stripe_unit stripe unit size, in bytes.
 217  * @param stripe_count number of objects to stripe over before looping
 218  * @return 0 on success, or negative error code
 219  */
 220 CEPH_RBD_API int rbd_create3(rados_ioctx_t io, const char *name, uint64_t size,
 221                              uint64_t features, int *order,
 222                              uint64_t stripe_unit, uint64_t stripe_count);
 223 CEPH_RBD_API int rbd_create4(rados_ioctx_t io, const char *name, uint64_t size,
 224                              rbd_image_options_t opts);
 225 CEPH_RBD_API int rbd_clone(rados_ioctx_t p_ioctx, const char *p_name,
 226                            const char *p_snapname, rados_ioctx_t c_ioctx,
 227                            const char *c_name, uint64_t features, int *c_order);
 228 CEPH_RBD_API int rbd_clone2(rados_ioctx_t p_ioctx, const char *p_name,
 229                             const char *p_snapname, rados_ioctx_t c_ioctx,
 230                             const char *c_name, uint64_t features, int *c_order,
 231                             uint64_t stripe_unit, int stripe_count);
 232 CEPH_RBD_API int rbd_clone3(rados_ioctx_t p_ioctx, const char *p_name,
 233                             const char *p_snapname, rados_ioctx_t c_ioctx,
 234                             const char *c_name, rbd_image_options_t c_opts);
 235 CEPH_RBD_API int rbd_remove(rados_ioctx_t io, const char *name);
 236 CEPH_RBD_API int rbd_remove_with_progress(rados_ioctx_t io, const char *name,
 237                                           librbd_progress_fn_t cb,
 238                                           void *cbdata);
 239 CEPH_RBD_API int rbd_rename(rados_ioctx_t src_io_ctx, const char *srcname,
 240                             const char *destname);
 241
 242 CEPH_RBD_API int rbd_trash_move(rados_ioctx_t io, const char *name,
 243                                 uint64_t delay);
 244 CEPH_RBD_API int rbd_trash_get(rados_ioctx_t io, const char *id,
 245                                rbd_trash_image_info_t *info);
 246 CEPH_RBD_API void rbd_trash_get_cleanup(rbd_trash_image_info_t *info);
 247 CEPH_RBD_API int rbd_trash_list(rados_ioctx_t io,
 248                                 rbd_trash_image_info_t *trash_entries,
 249                                 size_t *num_entries);
 250 CEPH_RBD_API void rbd_trash_list_cleanup(rbd_trash_image_info_t *trash_entries,
 251                                          size_t num_entries);
 252 CEPH_RBD_API int rbd_trash_remove(rados_ioctx_t io, const char *id, bool force);
 253 CEPH_RBD_API int rbd_trash_remove_with_progress(rados_ioctx_t io, const char *id,
 254                                                 bool force, librbd_progress_fn_t cb,
 255                                                 void *cbdata);
 256 CEPH_RBD_API int rbd_trash_restore(rados_ioctx_t io, const char *id,
 257                                    const char *name);
 258
 259 /* pool mirroring */
 260 CEPH_RBD_API int rbd_mirror_mode_get(rados_ioctx_t io_ctx,
 261                                      rbd_mirror_mode_t *mirror_mode);
 262 CEPH_RBD_API int rbd_mirror_mode_set(rados_ioctx_t io_ctx,
 263                                      rbd_mirror_mode_t mirror_mode);
 264 CEPH_RBD_API int rbd_mirror_peer_add(rados_ioctx_t io_ctx,
 265                                      char *uuid, size_t uuid_max_length,
 266                                      const char *cluster_name,
 267                                      const char *client_name);
 268 CEPH_RBD_API int rbd_mirror_peer_remove(rados_ioctx_t io_ctx,
 269                                         const char *uuid);
 270 CEPH_RBD_API int rbd_mirror_peer_list(rados_ioctx_t io_ctx,
 271                                       rbd_mirror_peer_t *peers, int *max_peers);
 272 CEPH_RBD_API void rbd_mirror_peer_list_cleanup(rbd_mirror_peer_t *peers,
 273                                                int max_peers);
 274 CEPH_RBD_API int rbd_mirror_peer_set_client(rados_ioctx_t io_ctx,
 275                                             const char *uuid,
 276                                             const char *client_name);
 277 CEPH_RBD_API int rbd_mirror_peer_set_cluster(rados_ioctx_t io_ctx,
 278                                              const char *uuid,
 279                                              const char *cluster_name);
 280 CEPH_RBD_API int rbd_mirror_image_status_list(rados_ioctx_t io_ctx,
 281                                               const char *start_id, size_t max,
 282                                               char **image_ids,
 283                                               rbd_mirror_image_status_t *images,
 284                                               size_t *len);
 285 CEPH_RBD_API void rbd_mirror_image_status_list_cleanup(char **image_ids,
 286     rbd_mirror_image_status_t *images, size_t len);
 287 CEPH_RBD_API int rbd_mirror_image_status_summary(rados_ioctx_t io_ctx,
 288     rbd_mirror_image_status_state_t *states, int *counts, size_t *maxlen);
 289
 290 CEPH_RBD_API int rbd_open(rados_ioctx_t io, const char *name,
 291                           rbd_image_t *image, const char *snap_name);
 292 CEPH_RBD_API int rbd_open_by_id(rados_ioctx_t io, const char *id,
 293                                 rbd_image_t *image, const char *snap_name);
 294
 295 CEPH_RBD_API int rbd_aio_open(rados_ioctx_t io, const char *name,
 296                               rbd_image_t *image, const char *snap_name,
 297                               rbd_completion_t c);
 298 CEPH_RBD_API int rbd_aio_open_by_id(rados_ioctx_t io, const char *id,
 299                                     rbd_image_t *image, const char *snap_name,
 300                                     rbd_completion_t c);
 301
 302 /**
 303  * Open an image in read-only mode.
 304  *
 305  * This is intended for use by clients that cannot write to a block
 306  * device due to cephx restrictions. There will be no watch
 307  * established on the header object, since a watch is a write. This
 308  * means the metadata reported about this image (parents, snapshots,
 309  * size, etc.) may become stale. This should not be used for
 310  * long-running operations, unless you can be sure that one of these
 311  * properties changing is safe.
 312  *
 313  * Attempting to write to a read-only image will return -EROFS.
 314  *
 315  * @param io ioctx to determine the pool the image is in
 316  * @param name image name
 317  * @param image where to store newly opened image handle
 318  * @param snap_name name of snapshot to open at, or NULL for no snapshot
 319  * @returns 0 on success, negative error code on failure
 320  */
 321 CEPH_RBD_API int rbd_open_read_only(rados_ioctx_t io, const char *name,
 322                                     rbd_image_t *image, const char *snap_name);
 323 CEPH_RBD_API int rbd_open_by_id_read_only(rados_ioctx_t io, const char *id,
 324                                           rbd_image_t *image, const char *snap_name);
 325 CEPH_RBD_API int rbd_aio_open_read_only(rados_ioctx_t io, const char *name,
 326                                         rbd_image_t *image, const char *snap_name,
 327                                         rbd_completion_t c);
 328 CEPH_RBD_API int rbd_aio_open_by_id_read_only(rados_ioctx_t io, const char *id,
 329                                               rbd_image_t *image, const char *snap_name,
 330                                               rbd_completion_t c);
 331 CEPH_RBD_API int rbd_close(rbd_image_t image);
 332 CEPH_RBD_API int rbd_aio_close(rbd_image_t image, rbd_completion_t c);
 333 CEPH_RBD_API int rbd_resize(rbd_image_t image, uint64_t size);
 334 CEPH_RBD_API int rbd_resize2(rbd_image_t image, uint64_t size, bool allow_shrink,
 335                              librbd_progress_fn_t cb, void *cbdata);
 336 CEPH_RBD_API int rbd_resize_with_progress(rbd_image_t image, uint64_t size,
 337                              librbd_progress_fn_t cb, void *cbdata);
 338 CEPH_RBD_API int rbd_stat(rbd_image_t image, rbd_image_info_t *info,
 339                           size_t infosize);
 340 CEPH_RBD_API int rbd_get_old_format(rbd_image_t image, uint8_t *old);
 341 CEPH_RBD_API int rbd_get_size(rbd_image_t image, uint64_t *size);
 342 CEPH_RBD_API int rbd_get_features(rbd_image_t image, uint64_t *features);
 343 CEPH_RBD_API int rbd_update_features(rbd_image_t image, uint64_t features,
 344                                      uint8_t enabled);
 345 CEPH_RBD_API int rbd_get_stripe_unit(rbd_image_t image, uint64_t *stripe_unit);
 346 CEPH_RBD_API int rbd_get_stripe_count(rbd_image_t image,
 347                                       uint64_t *stripe_count);
 348
 349 CEPH_RBD_API int rbd_get_create_timestamp(rbd_image_t image,
 350                                           struct timespec *timestamp);
 351
 352 CEPH_RBD_API int rbd_get_overlap(rbd_image_t image, uint64_t *overlap);
 353 CEPH_RBD_API int rbd_get_id(rbd_image_t image, char *id, size_t id_len);
 354 CEPH_RBD_API int rbd_get_block_name_prefix(rbd_image_t image,
 355                                            char *prefix, size_t prefix_len);
 356 CEPH_RBD_API int64_t rbd_get_data_pool_id(rbd_image_t image);
 357 CEPH_RBD_API int rbd_get_parent_info(rbd_image_t image,
 358                                      char *parent_poolname, size_t ppoolnamelen,
 359                                      char *parent_name, size_t pnamelen,
 360                                      char *parent_snapname,
 361                                      size_t psnapnamelen);
 362 CEPH_RBD_API int rbd_get_parent_info2(rbd_image_t image,
 363                                       char *parent_poolname,
 364                                       size_t ppoolnamelen,
 365                                       char *parent_name, size_t pnamelen,
 366                                       char *parent_id, size_t pidlen,
 367                                       char *parent_snapname,
 368                                       size_t psnapnamelen);
 369 CEPH_RBD_API int rbd_get_flags(rbd_image_t image, uint64_t *flags);
 370 CEPH_RBD_API int rbd_set_image_notification(rbd_image_t image, int fd, int type);
 371
 372 /* exclusive lock feature */
 373 CEPH_RBD_API int rbd_is_exclusive_lock_owner(rbd_image_t image, int *is_owner);
 374 CEPH_RBD_API int rbd_lock_acquire(rbd_image_t image, rbd_lock_mode_t lock_mode);
 375 CEPH_RBD_API int rbd_lock_release(rbd_image_t image);
 376 CEPH_RBD_API int rbd_lock_get_owners(rbd_image_t image,
 377                                      rbd_lock_mode_t *lock_mode,
 378                                      char **lock_owners,
 379                                      size_t *max_lock_owners);
 380 CEPH_RBD_API void rbd_lock_get_owners_cleanup(char **lock_owners,
 381                                               size_t lock_owner_count);
 382 CEPH_RBD_API int rbd_lock_break(rbd_image_t image, rbd_lock_mode_t lock_mode,
 383                                 const char *lock_owner);
 384
 385 /* object map feature */
 386 CEPH_RBD_API int rbd_rebuild_object_map(rbd_image_t image,
 387                                         librbd_progress_fn_t cb, void *cbdata);
 388
 389 CEPH_RBD_API int rbd_copy(rbd_image_t image, rados_ioctx_t dest_io_ctx,
 390                           const char *destname);
 391 CEPH_RBD_API int rbd_copy2(rbd_image_t src, rbd_image_t dest);
 392 CEPH_RBD_API int rbd_copy3(rbd_image_t src, rados_ioctx_t dest_io_ctx,
 393                            const char *destname, rbd_image_options_t dest_opts);
 394 CEPH_RBD_API int rbd_copy4(rbd_image_t src, rados_ioctx_t dest_io_ctx,
 395                            const char *destname, rbd_image_options_t dest_opts,
 396                            size_t sparse_size);
 397 CEPH_RBD_API int rbd_copy_with_progress(rbd_image_t image, rados_ioctx_t dest_p,
 398                                         const char *destname,
 399                                         librbd_progress_fn_t cb, void *cbdata);
 400 CEPH_RBD_API int rbd_copy_with_progress2(rbd_image_t src, rbd_image_t dest,
 401                                          librbd_progress_fn_t cb, void *cbdata);
 402 CEPH_RBD_API int rbd_copy_with_progress3(rbd_image_t image,
 403                                          rados_ioctx_t dest_p,
 404                                          const char *destname,
 405                                          rbd_image_options_t dest_opts,
 406                                          librbd_progress_fn_t cb, void *cbdata);
 407 CEPH_RBD_API int rbd_copy_with_progress4(rbd_image_t image,
 408                                          rados_ioctx_t dest_p,
 409                                          const char *destname,
 410                                          rbd_image_options_t dest_opts,
 411                                          librbd_progress_fn_t cb, void *cbdata,
 412                                          size_t sparse_size);
 413
 414 /* snapshots */
 415 CEPH_RBD_API int rbd_snap_list(rbd_image_t image, rbd_snap_info_t *snaps,
 416                                int *max_snaps);
 417 CEPH_RBD_API void rbd_snap_list_end(rbd_snap_info_t *snaps);
 418 CEPH_RBD_API int rbd_snap_create(rbd_image_t image, const char *snapname);
 419 CEPH_RBD_API int rbd_snap_remove(rbd_image_t image, const char *snapname);
 420 CEPH_RBD_API int rbd_snap_remove2(rbd_image_t image, const char *snap_name, uint32_t flags,
 421                                   librbd_progress_fn_t cb, void *cbdata);
 422 CEPH_RBD_API int rbd_snap_rollback(rbd_image_t image, const char *snapname);
 423 CEPH_RBD_API int rbd_snap_rollback_with_progress(rbd_image_t image,
 424                                                  const char *snapname,
 425                                                  librbd_progress_fn_t cb,
 426                                                  void *cbdata);
 427 CEPH_RBD_API int rbd_snap_rename(rbd_image_t image, const char *snapname,
 428                                  const char* dstsnapsname);
 429 /**
 430  * Prevent a snapshot from being deleted until it is unprotected.
 431  *
 432  * @param snap_name which snapshot to protect
 433  * @returns 0 on success, negative error code on failure
 434  * @returns -EBUSY if snap is already protected
 435  */
 436 CEPH_RBD_API int rbd_snap_protect(rbd_image_t image, const char *snap_name);
 437 /**
 438  * Allow a snaphshot to be deleted.
 439  *
 440  * @param snap_name which snapshot to unprotect
 441  * @returns 0 on success, negative error code on failure
 442  * @returns -EINVAL if snap is not protected
 443  */
 444 CEPH_RBD_API int rbd_snap_unprotect(rbd_image_t image, const char *snap_name);
 445 /**
 446  * Determine whether a snapshot is protected.
 447  *
 448  * @param snap_name which snapshot query
 449  * @param is_protected where to store the result (0 or 1)
 450  * @returns 0 on success, negative error code on failure
 451  */
 452 CEPH_RBD_API int rbd_snap_is_protected(rbd_image_t image, const char *snap_name,
 453                                        int *is_protected);
 454 /**
 455  * Get the current snapshot limit for an image. If no limit is set,
 456  * UINT64_MAX is returned.
 457  *
 458  * @param limit pointer where the limit will be stored on success
 459  * @returns 0 on success, negative error code on failure
 460  */
 461 CEPH_RBD_API int rbd_snap_get_limit(rbd_image_t image, uint64_t *limit);
 462
 463 /**
 464  * Set a limit for the number of snapshots that may be taken of an image.
 465  *
 466  * @param limit the maximum number of snapshots allowed in the future.
 467  * @returns 0 on success, negative error code on failure
 468  */
 469 CEPH_RBD_API int rbd_snap_set_limit(rbd_image_t image, uint64_t limit);
 470
 471 /**
 472  * Get the timestamp of a snapshot for an image.
 473  *
 474  * @param snap_id the snap id of a snapshot of input image.
 475  * @param timestamp the timestamp of input snapshot.
 476  * @returns 0 on success, negative error code on failure
 477  */
 478 CEPH_RBD_API int rbd_snap_get_timestamp(rbd_image_t image, uint64_t snap_id, struct timespec *timestamp);
 479
 480 CEPH_RBD_API int rbd_snap_set(rbd_image_t image, const char *snapname);
 481
 482 CEPH_RBD_API int rbd_flatten(rbd_image_t image);
 483
 484 CEPH_RBD_API int rbd_flatten_with_progress(rbd_image_t image,
 485                                            librbd_progress_fn_t cb,
 486                                            void *cbdata);
 487
 488 /**
 489  * List all images that are cloned from the image at the
 490  * snapshot that is set via rbd_snap_set().
 491  *
 492  * This iterates over all pools, so it should be run by a user with
 493  * read access to all of them. pools_len and images_len are filled in
 494  * with the number of bytes put into the pools and images buffers.
 495  *
 496  * If the provided buffers are too short, the required lengths are
 497  * still filled in, but the data is not and -ERANGE is returned.
 498  * Otherwise, the buffers are filled with the pool and image names
 499  * of the children, with a '\0' after each.
 500  *
 501  * @param image which image (and implicitly snapshot) to list clones of
 502  * @param pools buffer in which to store pool names
 503  * @param pools_len number of bytes in pools buffer
 504  * @param images buffer in which to store image names
 505  * @param images_len number of bytes in images buffer
 506  * @returns number of children on success, negative error code on failure
 507  * @returns -ERANGE if either buffer is too short
 508  */
 509 CEPH_RBD_API ssize_t rbd_list_children(rbd_image_t image, char *pools,
 510                                        size_t *pools_len, char *images,
 511                                        size_t *images_len);
 512
 513 /**
 514  * @defgroup librbd_h_locking Advisory Locking
 515  *
 516  * An rbd image may be locking exclusively, or shared, to facilitate
 517  * e.g. live migration where the image may be open in two places at once.
 518  * These locks are intended to guard against more than one client
 519  * writing to an image without coordination. They don't need to
 520  * be used for snapshots, since snapshots are read-only.
 521  *
 522  * Currently locks only guard against locks being acquired.
 523  * They do not prevent anything else.
 524  *
 525  * A locker is identified by the internal rados client id of the
 526  * holder and a user-defined cookie. This (client id, cookie) pair
 527  * must be unique for each locker.
 528  *
 529  * A shared lock also has a user-defined tag associated with it. Each
 530  * additional shared lock must specify the same tag or lock
 531  * acquisition will fail. This can be used by e.g. groups of hosts
 532  * using a clustered filesystem on top of an rbd image to make sure
 533  * they're accessing the correct image.
 534  *
 535  * @{
 536  */
 537 /**
 538  * List clients that have locked the image and information about the lock.
 539  *
 540  * The number of bytes required in each buffer is put in the
 541  * corresponding size out parameter. If any of the provided buffers
 542  * are too short, -ERANGE is returned after these sizes are filled in.
 543  *
 544  * @param exclusive where to store whether the lock is exclusive (1) or shared (0)
 545  * @param tag where to store the tag associated with the image
 546  * @param tag_len number of bytes in tag buffer
 547  * @param clients buffer in which locker clients are stored, separated by '\0'
 548  * @param clients_len number of bytes in the clients buffer
 549  * @param cookies buffer in which locker cookies are stored, separated by '\0'
 550  * @param cookies_len number of bytes in the cookies buffer
 551  * @param addrs buffer in which locker addresses are stored, separated by '\0'
 552  * @param addrs_len number of bytes in the clients buffer
 553  * @returns number of lockers on success, negative error code on failure
 554  * @returns -ERANGE if any of the buffers are too short
 555  */
 556 CEPH_RBD_API ssize_t rbd_list_lockers(rbd_image_t image, int *exclusive,
 557                                       char *tag, size_t *tag_len,
 558                                       char *clients, size_t *clients_len,
 559                                       char *cookies, size_t *cookies_len,
 560                                       char *addrs, size_t *addrs_len);
 561
 562 /**
 563  * Take an exclusive lock on the image.
 564  *
 565  * @param image the image to lock
 566  * @param cookie user-defined identifier for this instance of the lock
 567  * @returns 0 on success, negative error code on failure
 568  * @returns -EBUSY if the lock is already held by another (client, cookie) pair
 569  * @returns -EEXIST if the lock is already held by the same (client, cookie) pair
 570  */
 571 CEPH_RBD_API int rbd_lock_exclusive(rbd_image_t image, const char *cookie);
 572
 573 /**
 574  * Take a shared lock on the image.
 575  *
 576  * Other clients may also take a shared lock, as lock as they use the
 577  * same tag.
 578  *
 579  * @param image the image to lock
 580  * @param cookie user-defined identifier for this instance of the lock
 581  * @param tag user-defined identifier for this shared use of the lock
 582  * @returns 0 on success, negative error code on failure
 583  * @returns -EBUSY if the lock is already held by another (client, cookie) pair
 584  * @returns -EEXIST if the lock is already held by the same (client, cookie) pair
 585  */
 586 CEPH_RBD_API int rbd_lock_shared(rbd_image_t image, const char *cookie,
 587                                  const char *tag);
 588
 589 /**
 590  * Release a shared or exclusive lock on the image.
 591  *
 592  * @param image the image to unlock
 593  * @param cookie user-defined identifier for the instance of the lock
 594  * @returns 0 on success, negative error code on failure
 595  * @returns -ENOENT if the lock is not held by the specified (client, cookie) pair
 596  */
 597 CEPH_RBD_API int rbd_unlock(rbd_image_t image, const char *cookie);
 598
 599 /**
 600  * Release a shared or exclusive lock that was taken by the specified client.
 601  *
 602  * @param image the image to unlock
 603  * @param client the entity holding the lock (as given by rbd_list_lockers())
 604  * @param cookie user-defined identifier for the instance of the lock to break
 605  * @returns 0 on success, negative error code on failure
 606  * @returns -ENOENT if the lock is not held by the specified (client, cookie) pair
 607  */
 608 CEPH_RBD_API int rbd_break_lock(rbd_image_t image, const char *client,
 609                                 const char *cookie);
 610
 611 /** @} locking */
 612
 613 /* I/O */
 614 CEPH_RBD_API ssize_t rbd_read(rbd_image_t image, uint64_t ofs, size_t len,
 615                               char *buf);
 616 /*
 617  * @param op_flags: see librados.h constants beginning with LIBRADOS_OP_FLAG
 618  */
 619 CEPH_RBD_API ssize_t rbd_read2(rbd_image_t image, uint64_t ofs, size_t len,
 620                                char *buf, int op_flags);
 621 /* DEPRECATED; use rbd_read_iterate2 */
 622 CEPH_RBD_API int64_t rbd_read_iterate(rbd_image_t image, uint64_t ofs, size_t len,
 623                                       int (*cb)(uint64_t, size_t, const char *, void *),
 624                                       void *arg);
 625
 626 /**
 627  * iterate read over an image
 628  *
 629  * Reads each region of the image and calls the callback.  If the
 630  * buffer pointer passed to the callback is NULL, the given extent is
 631  * defined to be zeros (a hole).  Normally the granularity for the
 632  * callback is the image stripe size.
 633  *
 634  * @param image image to read
 635  * @param ofs offset to start from
 636  * @param len bytes of source image to cover
 637  * @param cb callback for each region
 638  * @returns 0 success, error otherwise
 639  */
 640 CEPH_RBD_API int rbd_read_iterate2(rbd_image_t image, uint64_t ofs, uint64_t len,
 641                                    int (*cb)(uint64_t, size_t, const char *, void *),
 642                                    void *arg);
 643 /**
 644  * get difference between two versions of an image
 645  *
 646  * This will return the differences between two versions of an image
 647  * via a callback, which gets the offset and length and a flag
 648  * indicating whether the extent exists (1), or is known/defined to
 649  * be zeros (a hole, 0).  If the source snapshot name is NULL, we
 650  * interpret that as the beginning of time and return all allocated
 651  * regions of the image.  The end version is whatever is currently
 652  * selected for the image handle (either a snapshot or the writeable
 653  * head).
 654  *
 655  * @param fromsnapname start snapshot name, or NULL
 656  * @param ofs start offset
 657  * @param len len in bytes of region to report on
 658  * @param include_parent 1 if full history diff should include parent
 659  * @param whole_object 1 if diff extents should cover whole object
 660  * @param cb callback to call for each allocated region
 661  * @param arg argument to pass to the callback
 662  * @returns 0 on success, or negative error code on error
 663  */
 664 CEPH_RBD_API int rbd_diff_iterate(rbd_image_t image,
 665                                   const char *fromsnapname,
 666                                   uint64_t ofs, uint64_t len,
 667                                   int (*cb)(uint64_t, size_t, int, void *),
 668                                   void *arg);
 669 CEPH_RBD_API int rbd_diff_iterate2(rbd_image_t image,
 670                                    const char *fromsnapname,
 671                                    uint64_t ofs, uint64_t len,
 672                                    uint8_t include_parent, uint8_t whole_object,
 673                                    int (*cb)(uint64_t, size_t, int, void *),
 674                                    void *arg);
 675 CEPH_RBD_API ssize_t rbd_write(rbd_image_t image, uint64_t ofs, size_t len,
 676                                const char *buf);
 677 /*
 678  * @param op_flags: see librados.h constants beginning with LIBRADOS_OP_FLAG
 679  */
 680 CEPH_RBD_API ssize_t rbd_write2(rbd_image_t image, uint64_t ofs, size_t len,
 681                                 const char *buf, int op_flags);
 682 CEPH_RBD_API int rbd_discard(rbd_image_t image, uint64_t ofs, uint64_t len);
 683 CEPH_RBD_API ssize_t rbd_writesame(rbd_image_t image, uint64_t ofs, size_t len,
 684                                    const char *buf, size_t data_len, int op_flags);
 685 CEPH_RBD_API ssize_t rbd_compare_and_write(rbd_image_t image, uint64_t ofs,
 686                                            size_t len, const char *cmp_buf,
 687                                            const char *buf, uint64_t *mismatch_off,
 688                                            int op_flags);
 689
 690 CEPH_RBD_API int rbd_aio_write(rbd_image_t image, uint64_t off, size_t len,
 691                                const char *buf, rbd_completion_t c);
 692
 693 /*
 694  * @param op_flags: see librados.h constants beginning with LIBRADOS_OP_FLAG
 695  */
 696 CEPH_RBD_API int rbd_aio_write2(rbd_image_t image, uint64_t off, size_t len,
 697                                 const char *buf, rbd_completion_t c,
 698                                 int op_flags);
 699 CEPH_RBD_API int rbd_aio_writev(rbd_image_t image, const struct iovec *iov,
 700                                 int iovcnt, uint64_t off, rbd_completion_t c);
 701 CEPH_RBD_API int rbd_aio_read(rbd_image_t image, uint64_t off, size_t len,
 702                               char *buf, rbd_completion_t c);
 703 /*
 704  * @param op_flags: see librados.h constants beginning with LIBRADOS_OP_FLAG
 705  */
 706 CEPH_RBD_API int rbd_aio_read2(rbd_image_t image, uint64_t off, size_t len,
 707                                char *buf, rbd_completion_t c, int op_flags);
 708 CEPH_RBD_API int rbd_aio_readv(rbd_image_t image, const struct iovec *iov,
 709                                int iovcnt, uint64_t off, rbd_completion_t c);
 710 CEPH_RBD_API int rbd_aio_discard(rbd_image_t image, uint64_t off, uint64_t len,
 711                                  rbd_completion_t c);
 712 CEPH_RBD_API int rbd_aio_writesame(rbd_image_t image, uint64_t off, size_t len,
 713                                    const char *buf, size_t data_len,
 714                                    rbd_completion_t c, int op_flags);
 715 CEPH_RBD_API ssize_t rbd_aio_compare_and_write(rbd_image_t image,
 716                                                uint64_t off, size_t len,
 717                                                const char *cmp_buf, const char *buf,
 718                                                rbd_completion_t c, uint64_t *mismatch_off,
 719                                                int op_flags);
 720
 721 CEPH_RBD_API int rbd_aio_create_completion(void *cb_arg,
 722                                            rbd_callback_t complete_cb,
 723                                            rbd_completion_t *c);
 724 CEPH_RBD_API int rbd_aio_is_complete(rbd_completion_t c);
 725 CEPH_RBD_API int rbd_aio_wait_for_complete(rbd_completion_t c);
 726 CEPH_RBD_API ssize_t rbd_aio_get_return_value(rbd_completion_t c);
 727 CEPH_RBD_API void *rbd_aio_get_arg(rbd_completion_t c);
 728 CEPH_RBD_API void rbd_aio_release(rbd_completion_t c);
 729 CEPH_RBD_API int rbd_flush(rbd_image_t image);
 730 /**
 731  * Start a flush if caching is enabled. Get a callback when
 732  * the currently pending writes are on disk.
 733  *
 734  * @param image the image to flush writes to
 735  * @param c what to call when flushing is complete
 736  * @returns 0 on success, negative error code on failure
 737  */
 738 CEPH_RBD_API int rbd_aio_flush(rbd_image_t image, rbd_completion_t c);
 739
 740 /**
 741  * Drop any cached data for an image
 742  *
 743  * @param image the image to invalidate cached data for
 744  * @returns 0 on success, negative error code on failure
 745  */
 746 CEPH_RBD_API int rbd_invalidate_cache(rbd_image_t image);
 747
 748 CEPH_RBD_API int rbd_poll_io_events(rbd_image_t image, rbd_completion_t *comps, int numcomp);
 749
 750 CEPH_RBD_API int rbd_metadata_get(rbd_image_t image, const char *key, char *value, size_t *val_len);
 751 CEPH_RBD_API int rbd_metadata_set(rbd_image_t image, const char *key, const char *value);
 752 CEPH_RBD_API int rbd_metadata_remove(rbd_image_t image, const char *key);
 753 /**
 754  * List all metadatas associated with this image.
 755  *
 756  * This iterates over all metadatas, key_len and val_len are filled in
 757  * with the number of bytes put into the keys and values buffers.
 758  *
 759  * If the provided buffers are too short, the required lengths are
 760  * still filled in, but the data is not and -ERANGE is returned.
 761  * Otherwise, the buffers are filled with the keys and values
 762  * of the image, with a '\0' after each.
 763  *
 764  * @param image which image (and implicitly snapshot) to list clones of
 765  * @param start_after which name to begin listing after
 766  *        (use the empty string to start at the beginning)
 767  * @param max the maximum number of names to lis(if 0 means no limit)
 768  * @param keys buffer in which to store pool names
 769  * @param keys_len number of bytes in pools buffer
 770  * @param values buffer in which to store image names
 771  * @param vals_len number of bytes in images buffer
 772  * @returns number of children on success, negative error code on failure
 773  * @returns -ERANGE if either buffer is too short
 774  */
 775 CEPH_RBD_API int rbd_metadata_list(rbd_image_t image, const char *start, uint64_t max,
 776     char *keys, size_t *key_len, char *values, size_t *vals_len);
 777
 778 // RBD image mirroring support functions
 779 CEPH_RBD_API int rbd_mirror_image_enable(rbd_image_t image);
 780 CEPH_RBD_API int rbd_mirror_image_disable(rbd_image_t image, bool force);
 781 CEPH_RBD_API int rbd_mirror_image_promote(rbd_image_t image, bool force);
 782 CEPH_RBD_API int rbd_mirror_image_demote(rbd_image_t image);
 783 CEPH_RBD_API int rbd_mirror_image_resync(rbd_image_t image);
 784 CEPH_RBD_API int rbd_mirror_image_get_info(rbd_image_t image,
 785                                            rbd_mirror_image_info_t *mirror_image_info,
 786                                            size_t info_size);
 787 CEPH_RBD_API int rbd_mirror_image_get_status(rbd_image_t image,
 788                                              rbd_mirror_image_status_t *mirror_image_status,
 789                                              size_t status_size);
 790 CEPH_RBD_API int rbd_aio_mirror_image_promote(rbd_image_t image, bool force,
 791                                               rbd_completion_t c);
 792 CEPH_RBD_API int rbd_aio_mirror_image_demote(rbd_image_t image,
 793                                              rbd_completion_t c);
 794 CEPH_RBD_API int rbd_aio_mirror_image_get_info(rbd_image_t image,
 795                                                rbd_mirror_image_info_t *mirror_image_info,
 796                                                size_t info_size,
 797                                                rbd_completion_t c);
 798 CEPH_RBD_API int rbd_aio_mirror_image_get_status(rbd_image_t image,
 799                                                  rbd_mirror_image_status_t *mirror_image_status,
 800                                                  size_t status_size,
 801                                                  rbd_completion_t c);
 802
 803 /**
 804  * Register an image metadata change watcher.
 805  *
 806  * @param image the image to watch
 807  * @param handle where to store the internal id assigned to this watch
 808  * @param watch_cb what to do when a notify is received on this image
 809  * @param arg opaque value to pass to the callback
 810  * @returns 0 on success, negative error code on failure
 811  */
 812 CEPH_RBD_API int rbd_update_watch(rbd_image_t image, uint64_t *handle,
 813                                   rbd_update_callback_t watch_cb, void *arg);
 814
 815 /**
 816  * Unregister an image watcher.
 817  *
 818  * @param image the image to unwatch
 819  * @param handle which watch to unregister
 820  * @returns 0 on success, negative error code on failure
 821  */
 822 CEPH_RBD_API int rbd_update_unwatch(rbd_image_t image, uint64_t handle);
 823
 824 #ifdef __cplusplus
 825 }
 826 #endif
 827
 828 #endif