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