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 <stddef.h>
  24 #include <stdint.h>
  25
  26 #define BTRFS_UTIL_VERSION_MAJOR 1
  27 #define BTRFS_UTIL_VERSION_MINOR 0
  28 #define BTRFS_UTIL_VERSION_PATCH 0
  29
  30 #ifdef __cplusplus
  31 extern "C" {
  32 #endif
  33
  34 /**
  35  * enum btrfs_util_error - libbtrfsutil error codes.
  36  *
  37  * All functions in libbtrfsutil that can return an error return this type and
  38  * set errno.
  39  */
  40 enum btrfs_util_error {
  41         BTRFS_UTIL_OK,
  42         BTRFS_UTIL_ERROR_STOP_ITERATION,
  43         BTRFS_UTIL_ERROR_NO_MEMORY,
  44         BTRFS_UTIL_ERROR_INVALID_ARGUMENT,
  45         BTRFS_UTIL_ERROR_NOT_BTRFS,
  46         BTRFS_UTIL_ERROR_NOT_SUBVOLUME,
  47         BTRFS_UTIL_ERROR_SUBVOLUME_NOT_FOUND,
  48         BTRFS_UTIL_ERROR_OPEN_FAILED,
  49         BTRFS_UTIL_ERROR_RMDIR_FAILED,
  50         BTRFS_UTIL_ERROR_UNLINK_FAILED,
  51         BTRFS_UTIL_ERROR_STAT_FAILED,
  52         BTRFS_UTIL_ERROR_STATFS_FAILED,
  53         BTRFS_UTIL_ERROR_SEARCH_FAILED,
  54         BTRFS_UTIL_ERROR_INO_LOOKUP_FAILED,
  55         BTRFS_UTIL_ERROR_SUBVOL_GETFLAGS_FAILED,
  56         BTRFS_UTIL_ERROR_SUBVOL_SETFLAGS_FAILED,
  57         BTRFS_UTIL_ERROR_SUBVOL_CREATE_FAILED,
  58         BTRFS_UTIL_ERROR_SNAP_CREATE_FAILED,
  59         BTRFS_UTIL_ERROR_SNAP_DESTROY_FAILED,
  60         BTRFS_UTIL_ERROR_DEFAULT_SUBVOL_FAILED,
  61         BTRFS_UTIL_ERROR_SYNC_FAILED,
  62         BTRFS_UTIL_ERROR_START_SYNC_FAILED,
  63         BTRFS_UTIL_ERROR_WAIT_SYNC_FAILED,
  64 };
  65
  66 /**
  67  * btrfs_util_strerror() - Convert a libtrfsutil error code to a string
  68  * description.
  69  * @err: The error to convert.
  70  *
  71  * Return: Error description.
  72  */
  73 const char *btrfs_util_strerror(enum btrfs_util_error err);
  74
  75 /**
  76  * btrfs_util_sync() - Force a sync on a specific Btrfs filesystem.
  77  * @path: Path on a Btrfs filesystem.
  78  *
  79  * Return: %BTRFS_UTIL_OK on success, non-zero error code on failure.
  80  */
  81 enum btrfs_util_error btrfs_util_sync(const char *path);
  82
  83 /**
  84  * btrfs_util_sync_fd() - See btrfs_util_sync().
  85  */
  86 enum btrfs_util_error btrfs_util_sync_fd(int fd);
  87
  88 /**
  89  * btrfs_util_start_sync() - Start a sync on a specific Btrfs filesystem but
  90  * don't wait for it.
  91  * @path: Path on a Btrfs filesystem.
  92  * @transid: Returned transaction ID which can be waited on with
  93  * btrfs_util_wait_sync(). This can be %NULL.
  94  *
  95  * Return: %BTRFS_UTIL_OK on success, non-zero error code on failure.
  96  */
  97 enum btrfs_util_error btrfs_util_start_sync(const char *path,
  98                                             uint64_t *transid);
  99
 100 /**
 101  * btrfs_util_start_sync_fd() - See btrfs_util_start_sync().
 102  */
 103 enum btrfs_util_error btrfs_util_start_sync_fd(int fd, uint64_t *transid);
 104
 105 /**
 106  * btrfs_util_wait_sync() - Wait for a transaction with a given ID to sync.
 107  * @path: Path on a Btrfs filesystem.
 108  * @transid: Transaction ID to wait for, or zero for the current transaction.
 109  *
 110  * Return: %BTRFS_UTIL_OK on success, non-zero error code on failure.
 111  */
 112 enum btrfs_util_error btrfs_util_wait_sync(const char *path, uint64_t transid);
 113
 114 /**
 115  * btrfs_util_wait_sync_fd() - See btrfs_util_wait_sync().
 116  */
 117 enum btrfs_util_error btrfs_util_wait_sync_fd(int fd, uint64_t transid);
 118
 119 /**
 120  * btrfs_util_is_subvolume() - Return whether a given path is a Btrfs subvolume.
 121  * @path: Path to check.
 122  *
 123  * Return: %BTRFS_UTIL_OK if @path is a Btrfs subvolume,
 124  * %BTRFS_UTIL_ERROR_NOT_BTRFS if @path is not on a Btrfs filesystem,
 125  * %BTRFS_UTIL_ERROR_NOT_SUBVOLUME if @path is not a subvolume, non-zero error
 126  * code on any other failure.
 127  */
 128 enum btrfs_util_error btrfs_util_is_subvolume(const char *path);
 129
 130 /**
 131  * btrfs_util_is_subvolume_fd() - See btrfs_util_is_subvolume().
 132  */
 133 enum btrfs_util_error btrfs_util_is_subvolume_fd(int fd);
 134
 135 /**
 136  * btrfs_util_subvolume_id() - Get the ID of the subvolume containing a path.
 137  * @path: Path on a Btrfs filesystem.
 138  * @id_ret: Returned subvolume ID.
 139  *
 140  * Return: %BTRFS_UTIL_OK on success, non-zero error code on failure.
 141  */
 142 enum btrfs_util_error btrfs_util_subvolume_id(const char *path,
 143                                               uint64_t *id_ret);
 144
 145 /**
 146  * btrfs_util_subvolume_id_fd() - See btrfs_util_subvolume_id().
 147  */
 148 enum btrfs_util_error btrfs_util_subvolume_id_fd(int fd, uint64_t *id_ret);
 149
 150 /**
 151  * btrfs_util_subvolume_path() - Get the path of the subvolume with a given ID
 152  * relative to the filesystem root.
 153  * @path: Path on a Btrfs filesystem.
 154  * @id: ID of subvolume to set as the default. If zero is given, the subvolume
 155  * ID of @path is used.
 156  * @path_ret: Returned path.
 157  *
 158  * This requires appropriate privilege (CAP_SYS_ADMIN).
 159  *
 160  * Return: %BTRFS_UTIL_OK on success, non-zero error code on failure.
 161  */
 162 enum btrfs_util_error btrfs_util_subvolume_path(const char *path, uint64_t id,
 163                                                 char **path_ret);
 164
 165 /**
 166  * btrfs_util_subvolume_path_fd() - See btrfs_util_subvolume_path().
 167  */
 168 enum btrfs_util_error btrfs_util_subvolume_path_fd(int fd, uint64_t id,
 169                                                    char **path_ret);
 170
 171 struct btrfs_util_qgroup_inherit;
 172
 173 /**
 174  * btrfs_util_create_subvolume() - Create a new subvolume.
 175  * @path: Where to create the subvolume.
 176  * @flags: Must be zero.
 177  * @async_transid: If not NULL, create the subvolume asynchronously (i.e.,
 178  * without waiting for it to commit it to disk) and return the transaction ID
 179  * that it was created in. This transaction ID can be waited on with
 180  * btrfs_util_wait_sync().
 181  * @qgroup_inherit: Qgroups to inherit from, or NULL.
 182  *
 183  * Return: %BTRFS_UTIL_OK on success, non-zero error code on failure.
 184  */
 185 enum btrfs_util_error btrfs_util_create_subvolume(const char *path, int flags,
 186                                                   uint64_t *async_transid,
 187                                                   struct btrfs_util_qgroup_inherit *qgroup_inherit);
 188
 189 /**
 190  * btrfs_util_create_subvolume_fd() - Create a new subvolume given its parent
 191  * and name.
 192  * @parent_fd: File descriptor of the parent directory where the subvolume
 193  * should be created.
 194  * @name: Name of the subvolume to create.
 195  * @flags: See btrfs_util_create_subvolume().
 196  * @async_transid: See btrfs_util_create_subvolume().
 197  * @qgroup_inherit: See btrfs_util_create_subvolume().
 198  *
 199  * Return: %BTRFS_UTIL_OK on success, non-zero error code on failure.
 200  */
 201 enum btrfs_util_error btrfs_util_create_subvolume_fd(int parent_fd,
 202                                                      const char *name,
 203                                                      int flags,
 204                                                      uint64_t *async_transid,
 205                                                      struct btrfs_util_qgroup_inherit *qgroup_inherit);
 206
 207 /**
 208  * btrfs_util_create_qgroup_inherit() - Create a qgroup inheritance specifier
 209  * for btrfs_util_create_subvolume() or btrfs_util_create_snapshot().
 210  * @flags: Must be zero.
 211  * @ret: Returned qgroup inheritance specifier.
 212  *
 213  * The returned structure must be freed with
 214  * btrfs_util_destroy_qgroup_inherit().
 215  *
 216  * Return: %BTRFS_UTIL_OK on success, non-zero error code on failure.
 217  */
 218 enum btrfs_util_error btrfs_util_create_qgroup_inherit(int flags,
 219                                                        struct btrfs_util_qgroup_inherit **ret);
 220
 221 /**
 222  * btrfs_util_destroy_qgroup_inherit() - Destroy a qgroup inheritance specifier
 223  * previously created with btrfs_util_create_qgroup_inherit().
 224  * @inherit: Specifier to destroy.
 225  */
 226 void btrfs_util_destroy_qgroup_inherit(struct btrfs_util_qgroup_inherit *inherit);
 227
 228 /**
 229  * btrfs_util_qgroup_inherit_add_group() - Add inheritance from a qgroup to a
 230  * qgroup inheritance specifier.
 231  * @inherit: Specifier to modify. May be reallocated.
 232  * @qgroupid: ID of qgroup to inherit from.
 233  *
 234  * Return: %BTRFS_UTIL_OK on success, non-zero error code on failure.
 235  */
 236 enum btrfs_util_error btrfs_util_qgroup_inherit_add_group(struct btrfs_util_qgroup_inherit **inherit,
 237                                                           uint64_t qgroupid);
 238
 239 /**
 240  * btrfs_util_qgroup_inherit_get_groups() - Get the qgroups a qgroup inheritance
 241  * specifier contains.
 242  * @inherit: Qgroup inheritance specifier.
 243  * @groups: Returned array of qgroup IDs.
 244  * @n: Returned number of entries in the @groups array.
 245  */
 246 void btrfs_util_qgroup_inherit_get_groups(const struct btrfs_util_qgroup_inherit *inherit,
 247                                           const uint64_t **groups, size_t *n);
 248
 249 #ifdef __cplusplus
 250 }
 251 #endif
 252
 253 #endif /* BTRFS_UTIL_H */