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


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