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