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