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 */