]> git.proxmox.com Git - ceph.git/blob - ceph/src/include/rbd/librbd.h
projects / ceph.git / blob
? search:


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