libbtrfsutil: add btrfs_util_deleted_subvolumes()
[platform/upstream/btrfs-progs.git] / libbtrfsutil / btrfsutil.h
1 /*
2  * Copyright (C) 2018 Facebook
3  *
4  * This file is part of libbtrfsutil.
5  *
6  * libbtrfsutil is free software: you can redistribute it and/or modify
7  * it under the terms of the GNU Lesser General Public License as published by
8  * the Free Software Foundation, either version 3 of the License, or
9  * (at your option) any later version.
10  *
11  * libbtrfsutil is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  * GNU Lesser General Public License for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public License
17  * along with libbtrfsutil.  If not, see <http://www.gnu.org/licenses/>.
18  */
19
20 #ifndef BTRFS_UTIL_H
21 #define BTRFS_UTIL_H
22
23 #include <stdbool.h>
24 #include <stddef.h>
25 #include <stdint.h>
26 #include <sys/time.h>
27
28 #define BTRFS_UTIL_VERSION_MAJOR 1
29 #define BTRFS_UTIL_VERSION_MINOR 0
30 #define BTRFS_UTIL_VERSION_PATCH 0
31
32 #ifdef __cplusplus
33 extern "C" {
34 #endif
35
36 /**
37  * enum btrfs_util_error - libbtrfsutil error codes.
38  *
39  * All functions in libbtrfsutil that can return an error return this type and
40  * set errno.
41  */
42 enum btrfs_util_error {
43         BTRFS_UTIL_OK,
44         BTRFS_UTIL_ERROR_STOP_ITERATION,
45         BTRFS_UTIL_ERROR_NO_MEMORY,
46         BTRFS_UTIL_ERROR_INVALID_ARGUMENT,
47         BTRFS_UTIL_ERROR_NOT_BTRFS,
48         BTRFS_UTIL_ERROR_NOT_SUBVOLUME,
49         BTRFS_UTIL_ERROR_SUBVOLUME_NOT_FOUND,
50         BTRFS_UTIL_ERROR_OPEN_FAILED,
51         BTRFS_UTIL_ERROR_RMDIR_FAILED,
52         BTRFS_UTIL_ERROR_UNLINK_FAILED,
53         BTRFS_UTIL_ERROR_STAT_FAILED,
54         BTRFS_UTIL_ERROR_STATFS_FAILED,
55         BTRFS_UTIL_ERROR_SEARCH_FAILED,
56         BTRFS_UTIL_ERROR_INO_LOOKUP_FAILED,
57         BTRFS_UTIL_ERROR_SUBVOL_GETFLAGS_FAILED,
58         BTRFS_UTIL_ERROR_SUBVOL_SETFLAGS_FAILED,
59         BTRFS_UTIL_ERROR_SUBVOL_CREATE_FAILED,
60         BTRFS_UTIL_ERROR_SNAP_CREATE_FAILED,
61         BTRFS_UTIL_ERROR_SNAP_DESTROY_FAILED,
62         BTRFS_UTIL_ERROR_DEFAULT_SUBVOL_FAILED,
63         BTRFS_UTIL_ERROR_SYNC_FAILED,
64         BTRFS_UTIL_ERROR_START_SYNC_FAILED,
65         BTRFS_UTIL_ERROR_WAIT_SYNC_FAILED,
66 };
67
68 /**
69  * btrfs_util_strerror() - Convert a libtrfsutil error code to a string
70  * description.
71  * @err: The error to convert.
72  *
73  * Return: Error description.
74  */
75 const char *btrfs_util_strerror(enum btrfs_util_error err);
76
77 /**
78  * btrfs_util_sync() - Force a sync on a specific Btrfs filesystem.
79  * @path: Path on a Btrfs filesystem.
80  *
81  * Return: %BTRFS_UTIL_OK on success, non-zero error code on failure.
82  */
83 enum btrfs_util_error btrfs_util_sync(const char *path);
84
85 /**
86  * btrfs_util_sync_fd() - See btrfs_util_sync().
87  */
88 enum btrfs_util_error btrfs_util_sync_fd(int fd);
89
90 /**
91  * btrfs_util_start_sync() - Start a sync on a specific Btrfs filesystem but
92  * don't wait for it.
93  * @path: Path on a Btrfs filesystem.
94  * @transid: Returned transaction ID which can be waited on with
95  * btrfs_util_wait_sync(). This can be %NULL.
96  *
97  * Return: %BTRFS_UTIL_OK on success, non-zero error code on failure.
98  */
99 enum btrfs_util_error btrfs_util_start_sync(const char *path,
100                                             uint64_t *transid);
101
102 /**
103  * btrfs_util_start_sync_fd() - See btrfs_util_start_sync().
104  */
105 enum btrfs_util_error btrfs_util_start_sync_fd(int fd, uint64_t *transid);
106
107 /**
108  * btrfs_util_wait_sync() - Wait for a transaction with a given ID to sync.
109  * @path: Path on a Btrfs filesystem.
110  * @transid: Transaction ID to wait for, or zero for the current transaction.
111  *
112  * Return: %BTRFS_UTIL_OK on success, non-zero error code on failure.
113  */
114 enum btrfs_util_error btrfs_util_wait_sync(const char *path, uint64_t transid);
115
116 /**
117  * btrfs_util_wait_sync_fd() - See btrfs_util_wait_sync().
118  */
119 enum btrfs_util_error btrfs_util_wait_sync_fd(int fd, uint64_t transid);
120
121 /**
122  * btrfs_util_is_subvolume() - Return whether a given path is a Btrfs subvolume.
123  * @path: Path to check.
124  *
125  * Return: %BTRFS_UTIL_OK if @path is a Btrfs subvolume,
126  * %BTRFS_UTIL_ERROR_NOT_BTRFS if @path is not on a Btrfs filesystem,
127  * %BTRFS_UTIL_ERROR_NOT_SUBVOLUME if @path is not a subvolume, non-zero error
128  * code on any other failure.
129  */
130 enum btrfs_util_error btrfs_util_is_subvolume(const char *path);
131
132 /**
133  * btrfs_util_is_subvolume_fd() - See btrfs_util_is_subvolume().
134  */
135 enum btrfs_util_error btrfs_util_is_subvolume_fd(int fd);
136
137 /**
138  * btrfs_util_subvolume_id() - Get the ID of the subvolume containing a path.
139  * @path: Path on a Btrfs filesystem.
140  * @id_ret: Returned subvolume ID.
141  *
142  * Return: %BTRFS_UTIL_OK on success, non-zero error code on failure.
143  */
144 enum btrfs_util_error btrfs_util_subvolume_id(const char *path,
145                                               uint64_t *id_ret);
146
147 /**
148  * btrfs_util_subvolume_id_fd() - See btrfs_util_subvolume_id().
149  */
150 enum btrfs_util_error btrfs_util_subvolume_id_fd(int fd, uint64_t *id_ret);
151
152 /**
153  * btrfs_util_subvolume_path() - Get the path of the subvolume with a given ID
154  * relative to the filesystem root.
155  * @path: Path on a Btrfs filesystem.
156  * @id: ID of subvolume to set as the default. If zero is given, the subvolume
157  * ID of @path is used.
158  * @path_ret: Returned path.
159  *
160  * This requires appropriate privilege (CAP_SYS_ADMIN).
161  *
162  * Return: %BTRFS_UTIL_OK on success, non-zero error code on failure.
163  */
164 enum btrfs_util_error btrfs_util_subvolume_path(const char *path, uint64_t id,
165                                                 char **path_ret);
166
167 /**
168  * btrfs_util_subvolume_path_fd() - See btrfs_util_subvolume_path().
169  */
170 enum btrfs_util_error btrfs_util_subvolume_path_fd(int fd, uint64_t id,
171                                                    char **path_ret);
172
173 /**
174  * struct btrfs_util_subvolume_info - Information about a Btrfs subvolume.
175  */
176 struct btrfs_util_subvolume_info {
177         /** @id: ID of this subvolume, unique across the filesystem. */
178         uint64_t id;
179
180         /**
181          * @parent_id: ID of the subvolume which contains this subvolume, or
182          * zero for the root subvolume (BTRFS_FS_TREE_OBJECTID) or orphaned
183          * subvolumes (i.e., subvolumes which have been deleted but not yet
184          * cleaned up).
185          */
186         uint64_t parent_id;
187
188         /**
189          * @dir_id: Inode number of the directory containing this subvolume in
190          * the parent subvolume, or zero for the root subvolume
191          * (BTRFS_FS_TREE_OBJECTID) or orphaned subvolumes.
192          */
193         uint64_t dir_id;
194
195         /** @flags: On-disk root item flags. */
196         uint64_t flags;
197
198         /** @uuid: UUID of this subvolume. */
199         uint8_t uuid[16];
200
201         /**
202          * @parent_uuid: UUID of the subvolume this subvolume is a snapshot of,
203          * or all zeroes if this subvolume is not a snapshot.
204          */
205         uint8_t parent_uuid[16];
206
207         /**
208          * @received_uuid: UUID of the subvolume this subvolume was received
209          * from, or all zeroes if this subvolume was not received. Note that
210          * this field, @stransid, @rtransid, @stime, and @rtime are set manually
211          * by userspace after a subvolume is received.
212          */
213         uint8_t received_uuid[16];
214
215         /** @generation: Transaction ID of the subvolume root. */
216         uint64_t generation;
217
218         /**
219          * @ctransid: Transaction ID when an inode in this subvolume was last
220          * changed.
221          */
222         uint64_t ctransid;
223
224         /** @otransid: Transaction ID when this subvolume was created. */
225         uint64_t otransid;
226
227         /**
228          * @stransid: Transaction ID of the sent subvolume this subvolume was
229          * received from, or zero if this subvolume was not received. See the
230          * note on @received_uuid.
231          */
232         uint64_t stransid;
233
234         /**
235          * @rtransid: Transaction ID when this subvolume was received, or zero
236          * if this subvolume was not received. See the note on @received_uuid.
237          */
238         uint64_t rtransid;
239
240         /** @ctime: Time when an inode in this subvolume was last changed. */
241         struct timespec ctime;
242
243         /** @otime: Time when this subvolume was created. */
244         struct timespec otime;
245
246         /**
247          * @stime: Not well-defined, usually zero unless it was set otherwise.
248          * See the note on @received_uuid.
249          */
250         struct timespec stime;
251
252         /**
253          * @rtime: Time when this subvolume was received, or zero if this
254          * subvolume was not received. See the note on @received_uuid.
255          */
256         struct timespec rtime;
257 };
258
259 /**
260  * btrfs_util_subvolume_info() - Get information about a subvolume.
261  * @path: Path in a Btrfs filesystem. This may be any path in the filesystem; it
262  * does not have to refer to a subvolume unless @id is zero.
263  * @id: ID of subvolume to get information about. If zero is given, the
264  * subvolume ID of @path is used.
265  * @subvol: Returned subvolume information. This can be %NULL if you just want
266  * to check whether the subvolume exists; %BTRFS_UTIL_ERROR_SUBVOLUME_NOT_FOUND
267  * will be returned if it does not.
268  *
269  * This requires appropriate privilege (CAP_SYS_ADMIN).
270  *
271  * Return: %BTRFS_UTIL_OK on success, non-zero error code on failure.
272  */
273 enum btrfs_util_error btrfs_util_subvolume_info(const char *path, uint64_t id,
274                                                 struct btrfs_util_subvolume_info *subvol);
275
276 /**
277  * btrfs_util_subvolume_info_fd() - See btrfs_util_subvolume_info().
278  */
279 enum btrfs_util_error btrfs_util_subvolume_info_fd(int fd, uint64_t id,
280                                                    struct btrfs_util_subvolume_info *subvol);
281
282 /**
283  * btrfs_util_get_subvolume_read_only() - Get whether a subvolume is read-only.
284  * @path: Subvolume path.
285  * @ret: Returned read-only flag.
286  *
287  * Return: %BTRFS_UTIL_OK on success, non-zero error code on failure.
288  */
289 enum btrfs_util_error btrfs_util_get_subvolume_read_only(const char *path,
290                                                          bool *ret);
291
292 /**
293  * btrfs_util_get_subvolume_read_only_fd() - See
294  * btrfs_util_get_subvolume_read_only().
295  */
296 enum btrfs_util_error btrfs_util_get_subvolume_read_only_fd(int fd, bool *ret);
297
298 /**
299  * btrfs_util_set_subvolume_read_only() - Set whether a subvolume is read-only.
300  * @path: Subvolume path.
301  * @read_only: New value of read-only flag.
302  *
303  * This requires appropriate privilege (CAP_SYS_ADMIN).
304  *
305  * Return: %BTRFS_UTIL_OK on success, non-zero error code on failure.
306  */
307 enum btrfs_util_error btrfs_util_set_subvolume_read_only(const char *path,
308                                                          bool read_only);
309
310 /**
311  * btrfs_util_set_subvolume_read_only_fd() - See
312  * btrfs_util_set_subvolume_read_only().
313  */
314 enum btrfs_util_error btrfs_util_set_subvolume_read_only_fd(int fd,
315                                                             bool read_only);
316
317 /**
318  * btrfs_util_get_default_subvolume() - Get the default subvolume for a
319  * filesystem.
320  * @path: Path on a Btrfs filesystem.
321  * @id_ret: Returned subvolume ID.
322  *
323  * This requires appropriate privilege (CAP_SYS_ADMIN).
324  *
325  * Return: %BTRFS_UTIL_OK on success, non-zero error code on failure.
326  */
327 enum btrfs_util_error btrfs_util_get_default_subvolume(const char *path,
328                                                        uint64_t *id_ret);
329
330 /**
331  * btrfs_util_get_default_subvolume_fd() - See
332  * btrfs_util_get_default_subvolume().
333  */
334 enum btrfs_util_error btrfs_util_get_default_subvolume_fd(int fd,
335                                                           uint64_t *id_ret);
336
337 /**
338  * btrfs_util_set_default_subvolume() - Set the default subvolume for a
339  * filesystem.
340  * @path: Path in a Btrfs filesystem. This may be any path in the filesystem; it
341  * does not have to refer to a subvolume unless @id is zero.
342  * @id: ID of subvolume to set as the default. If zero is given, the subvolume
343  * ID of @path is used.
344  *
345  * This requires appropriate privilege (CAP_SYS_ADMIN).
346  *
347  * Return: %BTRFS_UTIL_OK on success, non-zero error code on failure.
348  */
349 enum btrfs_util_error btrfs_util_set_default_subvolume(const char *path,
350                                                        uint64_t id);
351
352 /**
353  * btrfs_util_set_default_subvolume_fd() - See
354  * btrfs_util_set_default_subvolume().
355  */
356 enum btrfs_util_error btrfs_util_set_default_subvolume_fd(int fd, uint64_t id);
357
358 struct btrfs_util_qgroup_inherit;
359
360 /**
361  * btrfs_util_create_subvolume() - Create a new subvolume.
362  * @path: Where to create the subvolume.
363  * @flags: Must be zero.
364  * @async_transid: If not NULL, create the subvolume asynchronously (i.e.,
365  * without waiting for it to commit it to disk) and return the transaction ID
366  * that it was created in. This transaction ID can be waited on with
367  * btrfs_util_wait_sync().
368  * @qgroup_inherit: Qgroups to inherit from, or NULL.
369  *
370  * Return: %BTRFS_UTIL_OK on success, non-zero error code on failure.
371  */
372 enum btrfs_util_error btrfs_util_create_subvolume(const char *path, int flags,
373                                                   uint64_t *async_transid,
374                                                   struct btrfs_util_qgroup_inherit *qgroup_inherit);
375
376 /**
377  * btrfs_util_create_subvolume_fd() - Create a new subvolume given its parent
378  * and name.
379  * @parent_fd: File descriptor of the parent directory where the subvolume
380  * should be created.
381  * @name: Name of the subvolume to create.
382  * @flags: See btrfs_util_create_subvolume().
383  * @async_transid: See btrfs_util_create_subvolume().
384  * @qgroup_inherit: See btrfs_util_create_subvolume().
385  *
386  * Return: %BTRFS_UTIL_OK on success, non-zero error code on failure.
387  */
388 enum btrfs_util_error btrfs_util_create_subvolume_fd(int parent_fd,
389                                                      const char *name,
390                                                      int flags,
391                                                      uint64_t *async_transid,
392                                                      struct btrfs_util_qgroup_inherit *qgroup_inherit);
393
394 /**
395  * BTRFS_UTIL_CREATE_SNAPSHOT_RECURSIVE - Also snapshot subvolumes beneath the
396  * source subvolume onto the same location on the new snapshot.
397  *
398  * Note that this is currently implemented in userspace non-atomically. Because
399  * it modifies the newly-created snapshot, it cannot be combined with
400  * %BTRFS_UTIL_CREATE_SNAPSHOT_READ_ONLY. It requires appropriate privilege
401  * (CAP_SYS_ADMIN).
402  */
403 #define BTRFS_UTIL_CREATE_SNAPSHOT_RECURSIVE (1 << 0)
404 /**
405  * BTRFS_UTIL_CREATE_SNAPSHOT_READ_ONLY - Create a read-only snapshot.
406  */
407 #define BTRFS_UTIL_CREATE_SNAPSHOT_READ_ONLY (1 << 1)
408 #define BTRFS_UTIL_CREATE_SNAPSHOT_MASK ((1 << 2) - 1)
409
410 /**
411  * btrfs_util_create_snapshot() - Create a new snapshot from a source subvolume
412  * path.
413  * @source: Path of the existing subvolume to snapshot.
414  * @path: Where to create the snapshot.
415  * @flags: Bitmask of BTRFS_UTIL_CREATE_SNAPSHOT_* flags.
416  * @async_transid: See btrfs_util_create_subvolume(). If
417  * %BTRFS_UTIL_CREATE_SNAPSHOT_RECURSIVE was in @flags, then this will contain
418  * the largest transaction ID of all created subvolumes.
419  * @qgroup_inherit: See btrfs_util_create_subvolume().
420  *
421  * Return: %BTRFS_UTIL_OK on success, non-zero error code on failure.
422  */
423 enum btrfs_util_error btrfs_util_create_snapshot(const char *source,
424                                                  const char *path, int flags,
425                                                  uint64_t *async_transid,
426                                                  struct btrfs_util_qgroup_inherit *qgroup_inherit);
427
428 /**
429  * btrfs_util_create_snapshot_fd() - See btrfs_util_create_snapshot().
430  */
431 enum btrfs_util_error btrfs_util_create_snapshot_fd(int fd, const char *path,
432                                                     int flags,
433                                                     uint64_t *async_transid,
434                                                     struct btrfs_util_qgroup_inherit *qgroup_inherit);
435
436 /**
437  * btrfs_util_create_snapshot_fd2() - Create a new snapshot from a source
438  * subvolume file descriptor and a target parent file descriptor and name.
439  * @fd: File descriptor of the existing subvolume to snapshot.
440  * @parent_fd: File descriptor of the parent directory where the snapshot should
441  * be created.
442  * @name: Name of the snapshot to create.
443  * @flags: See btrfs_util_create_snapshot().
444  * @async_transid: See btrfs_util_create_snapshot().
445  * @qgroup_inherit: See btrfs_util_create_snapshot().
446  */
447 enum btrfs_util_error btrfs_util_create_snapshot_fd2(int fd, int parent_fd,
448                                                      const char *name,
449                                                      int flags,
450                                                      uint64_t *async_transid,
451                                                      struct btrfs_util_qgroup_inherit *qgroup_inherit);
452
453 /**
454  * BTRFS_UTIL_DELETE_SUBVOLUME_RECURSIVE - Delete subvolumes beneath the given
455  * subvolume before attempting to delete the given subvolume.
456  *
457  * If this flag is not used, deleting a subvolume with child subvolumes is an
458  * error. Note that this is currently implemented in userspace non-atomically.
459  * It requires appropriate privilege (CAP_SYS_ADMIN).
460  */
461 #define BTRFS_UTIL_DELETE_SUBVOLUME_RECURSIVE (1 << 0)
462 #define BTRFS_UTIL_DELETE_SUBVOLUME_MASK ((1 << 1) - 1)
463
464 /**
465  * btrfs_util_delete_subvolume() - Delete a subvolume or snapshot.
466  * @path: Path of the subvolume to delete.
467  * @flags: Bitmask of BTRFS_UTIL_DELETE_SUBVOLUME_* flags.
468  *
469  * Return: %BTRFS_UTIL_OK on success, non-zero error code on failure.
470  */
471 enum btrfs_util_error btrfs_util_delete_subvolume(const char *path, int flags);
472
473 /**
474  * btrfs_util_delete_subvolume_fd() - Delete a subvolume or snapshot given its
475  * parent and name.
476  * @parent_fd: File descriptor of the subvolume's parent directory.
477  * @name: Name of the subvolume.
478  * @flags: See btrfs_util_delete_subvolume().
479  *
480  * Return: %BTRFS_UTIL_OK on success, non-zero error code on failure.
481  */
482 enum btrfs_util_error btrfs_util_delete_subvolume_fd(int parent_fd,
483                                                      const char *name,
484                                                      int flags);
485
486 struct btrfs_util_subvolume_iterator;
487
488 /**
489  * BTRFS_UTIL_SUBVOLUME_ITERATOR_POST_ORDER - Iterate post-order. The default
490  * behavior is pre-order, e.g., foo will be yielded before foo/bar. If this flag
491  * is specified, foo/bar will be yielded before foo.
492  */
493 #define BTRFS_UTIL_SUBVOLUME_ITERATOR_POST_ORDER (1 << 0)
494 #define BTRFS_UTIL_SUBVOLUME_ITERATOR_MASK ((1 << 1) - 1)
495
496 /**
497  * btrfs_util_create_subvolume_iterator() - Create an iterator over subvolumes
498  * in a Btrfs filesystem.
499  * @path: Path in a Btrfs filesystem. This may be any path in the filesystem; it
500  * does not have to refer to a subvolume unless @top is zero.
501  * @top: List subvolumes beneath (but not including) the subvolume with this ID.
502  * If zero is given, the subvolume ID of @path is used. To list all subvolumes,
503  * pass %BTRFS_FS_TREE_OBJECTID (i.e., 5). The returned paths are relative to
504  * the subvolume with this ID.
505  * @flags: Bitmask of BTRFS_UTIL_SUBVOLUME_ITERATOR_* flags.
506  * @ret: Returned iterator.
507  *
508  * The returned iterator must be freed with
509  * btrfs_util_destroy_subvolume_iterator().
510  *
511  * Return: %BTRFS_UTIL_OK on success, non-zero error code on failure.
512  */
513 enum btrfs_util_error btrfs_util_create_subvolume_iterator(const char *path,
514                                                            uint64_t top,
515                                                            int flags,
516                                                            struct btrfs_util_subvolume_iterator **ret);
517
518 /**
519  * btrfs_util_create_subvolume_iterator_fd() - See
520  * btrfs_util_create_subvolume_iterator().
521  */
522 enum btrfs_util_error btrfs_util_create_subvolume_iterator_fd(int fd,
523                                                               uint64_t top,
524                                                               int flags,
525                                                               struct btrfs_util_subvolume_iterator **ret);
526
527 /**
528  * btrfs_util_destroy_subvolume_iterator() - Destroy a subvolume iterator
529  * previously created by btrfs_util_create_subvolume_iterator().
530  * @iter: Iterator to destroy.
531  */
532 void btrfs_util_destroy_subvolume_iterator(struct btrfs_util_subvolume_iterator *iter);
533
534 /**
535  * btrfs_util_subvolume_iterator_fd() - Get the file descriptor associated with
536  * a subvolume iterator.
537  * @iter: Iterator to get.
538  *
539  * This can be used to get the file descriptor opened by
540  * btrfs_util_create_subvolume_iterator() in order to use it for other
541  * functions.
542  *
543  * Return: File descriptor.
544  */
545 int btrfs_util_subvolume_iterator_fd(const struct btrfs_util_subvolume_iterator *iter);
546
547 /**
548  * btrfs_util_subvolume_iterator_next() - Get the next subvolume from a
549  * subvolume iterator.
550  * @iter: Subvolume iterator.
551  * @path_ret: Returned subvolume path, relative to the subvolume ID used to
552  * create the iterator. May be %NULL.
553  * Must be freed with free().
554  * @id_ret: Returned subvolume ID. May be %NULL.
555  *
556  * This requires appropriate privilege (CAP_SYS_ADMIN).
557  *
558  * Return: %BTRFS_UTIL_OK on success, %BTRFS_UTIL_ERROR_STOP_ITERATION if there
559  * are no more subvolumes, non-zero error code on failure.
560  */
561 enum btrfs_util_error btrfs_util_subvolume_iterator_next(struct btrfs_util_subvolume_iterator *iter,
562                                                          char **path_ret,
563                                                          uint64_t *id_ret);
564
565 /**
566  * btrfs_util_subvolume_iterator_next_info() - Get information about the next
567  * subvolume for a subvolume iterator.
568  * @iter: Subvolume iterator.
569  * @path_ret: See btrfs_util_subvolume_iterator_next().
570  * @subvol: Returned subvolume information.
571  *
572  * This convenience function basically combines
573  * btrfs_util_subvolume_iterator_next() and btrfs_util_subvolume_info().
574  *
575  * This requires appropriate privilege (CAP_SYS_ADMIN).
576  *
577  * Return: See btrfs_util_subvolume_iterator_next().
578  */
579 enum btrfs_util_error btrfs_util_subvolume_iterator_next_info(struct btrfs_util_subvolume_iterator *iter,
580                                                               char **path_ret,
581                                                               struct btrfs_util_subvolume_info *subvol);
582
583 /**
584  * btrfs_util_deleted_subvolumes() - Get a list of subvolume which have been
585  * deleted but not yet cleaned up.
586  * @path: Path on a Btrfs filesystem.
587  * @ids: Returned array of subvolume IDs.
588  * @n: Returned number of IDs in the @ids array.
589  *
590  * This requires appropriate privilege (CAP_SYS_ADMIN).
591  *
592  * Return: %BTRFS_UTIL_OK on success, non-zero error code on failure.
593  */
594 enum btrfs_util_error btrfs_util_deleted_subvolumes(const char *path,
595                                                     uint64_t **ids,
596                                                     size_t *n);
597
598 /**
599  * btrfs_util_deleted_subvolumes_fd() - See btrfs_util_deleted_subvolumes().
600  */
601 enum btrfs_util_error btrfs_util_deleted_subvolumes_fd(int fd, uint64_t **ids,
602                                                        size_t *n);
603
604 /**
605  * btrfs_util_create_qgroup_inherit() - Create a qgroup inheritance specifier
606  * for btrfs_util_create_subvolume() or btrfs_util_create_snapshot().
607  * @flags: Must be zero.
608  * @ret: Returned qgroup inheritance specifier.
609  *
610  * The returned structure must be freed with
611  * btrfs_util_destroy_qgroup_inherit().
612  *
613  * Return: %BTRFS_UTIL_OK on success, non-zero error code on failure.
614  */
615 enum btrfs_util_error btrfs_util_create_qgroup_inherit(int flags,
616                                                        struct btrfs_util_qgroup_inherit **ret);
617
618 /**
619  * btrfs_util_destroy_qgroup_inherit() - Destroy a qgroup inheritance specifier
620  * previously created with btrfs_util_create_qgroup_inherit().
621  * @inherit: Specifier to destroy.
622  */
623 void btrfs_util_destroy_qgroup_inherit(struct btrfs_util_qgroup_inherit *inherit);
624
625 /**
626  * btrfs_util_qgroup_inherit_add_group() - Add inheritance from a qgroup to a
627  * qgroup inheritance specifier.
628  * @inherit: Specifier to modify. May be reallocated.
629  * @qgroupid: ID of qgroup to inherit from.
630  *
631  * Return: %BTRFS_UTIL_OK on success, non-zero error code on failure.
632  */
633 enum btrfs_util_error btrfs_util_qgroup_inherit_add_group(struct btrfs_util_qgroup_inherit **inherit,
634                                                           uint64_t qgroupid);
635
636 /**
637  * btrfs_util_qgroup_inherit_get_groups() - Get the qgroups a qgroup inheritance
638  * specifier contains.
639  * @inherit: Qgroup inheritance specifier.
640  * @groups: Returned array of qgroup IDs.
641  * @n: Returned number of entries in the @groups array.
642  */
643 void btrfs_util_qgroup_inherit_get_groups(const struct btrfs_util_qgroup_inherit *inherit,
644                                           const uint64_t **groups, size_t *n);
645
646 #ifdef __cplusplus
647 }
648 #endif
649
650 #endif /* BTRFS_UTIL_H */