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