2 * Copyright (C) 2018 Facebook
4 * This file is part of libbtrfsutil.
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.
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.
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/>.
28 #define BTRFS_UTIL_VERSION_MAJOR 1
29 #define BTRFS_UTIL_VERSION_MINOR 0
30 #define BTRFS_UTIL_VERSION_PATCH 0
37 * enum btrfs_util_error - libbtrfsutil error codes.
39 * All functions in libbtrfsutil that can return an error return this type and
42 enum btrfs_util_error {
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,
69 * btrfs_util_strerror() - Convert a libtrfsutil error code to a string
71 * @err: The error to convert.
73 * Return: Error description.
75 const char *btrfs_util_strerror(enum btrfs_util_error err);
78 * btrfs_util_sync() - Force a sync on a specific Btrfs filesystem.
79 * @path: Path on a Btrfs filesystem.
81 * Return: %BTRFS_UTIL_OK on success, non-zero error code on failure.
83 enum btrfs_util_error btrfs_util_sync(const char *path);
86 * btrfs_util_sync_fd() - See btrfs_util_sync().
88 enum btrfs_util_error btrfs_util_sync_fd(int fd);
91 * btrfs_util_start_sync() - Start a sync on a specific Btrfs filesystem but
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.
97 * Return: %BTRFS_UTIL_OK on success, non-zero error code on failure.
99 enum btrfs_util_error btrfs_util_start_sync(const char *path,
103 * btrfs_util_start_sync_fd() - See btrfs_util_start_sync().
105 enum btrfs_util_error btrfs_util_start_sync_fd(int fd, uint64_t *transid);
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.
112 * Return: %BTRFS_UTIL_OK on success, non-zero error code on failure.
114 enum btrfs_util_error btrfs_util_wait_sync(const char *path, uint64_t transid);
117 * btrfs_util_wait_sync_fd() - See btrfs_util_wait_sync().
119 enum btrfs_util_error btrfs_util_wait_sync_fd(int fd, uint64_t transid);
122 * btrfs_util_is_subvolume() - Return whether a given path is a Btrfs subvolume.
123 * @path: Path to check.
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.
130 enum btrfs_util_error btrfs_util_is_subvolume(const char *path);
133 * btrfs_util_is_subvolume_fd() - See btrfs_util_is_subvolume().
135 enum btrfs_util_error btrfs_util_is_subvolume_fd(int fd);
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.
142 * Return: %BTRFS_UTIL_OK on success, non-zero error code on failure.
144 enum btrfs_util_error btrfs_util_subvolume_id(const char *path,
148 * btrfs_util_subvolume_id_fd() - See btrfs_util_subvolume_id().
150 enum btrfs_util_error btrfs_util_subvolume_id_fd(int fd, uint64_t *id_ret);
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.
160 * This requires appropriate privilege (CAP_SYS_ADMIN).
162 * Return: %BTRFS_UTIL_OK on success, non-zero error code on failure.
164 enum btrfs_util_error btrfs_util_subvolume_path(const char *path, uint64_t id,
168 * btrfs_util_subvolume_path_fd() - See btrfs_util_subvolume_path().
170 enum btrfs_util_error btrfs_util_subvolume_path_fd(int fd, uint64_t id,
174 * struct btrfs_util_subvolume_info - Information about a Btrfs subvolume.
176 struct btrfs_util_subvolume_info {
177 /** @id: ID of this subvolume, unique across the filesystem. */
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
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.
195 /** @flags: On-disk root item flags. */
198 /** @uuid: UUID of this subvolume. */
202 * @parent_uuid: UUID of the subvolume this subvolume is a snapshot of,
203 * or all zeroes if this subvolume is not a snapshot.
205 uint8_t parent_uuid[16];
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.
213 uint8_t received_uuid[16];
215 /** @generation: Transaction ID of the subvolume root. */
219 * @ctransid: Transaction ID when an inode in this subvolume was last
224 /** @otransid: Transaction ID when this subvolume was created. */
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.
235 * @rtransid: Transaction ID when this subvolume was received, or zero
236 * if this subvolume was not received. See the note on @received_uuid.
240 /** @ctime: Time when an inode in this subvolume was last changed. */
241 struct timespec ctime;
243 /** @otime: Time when this subvolume was created. */
244 struct timespec otime;
247 * @stime: Not well-defined, usually zero unless it was set otherwise.
248 * See the note on @received_uuid.
250 struct timespec stime;
253 * @rtime: Time when this subvolume was received, or zero if this
254 * subvolume was not received. See the note on @received_uuid.
256 struct timespec rtime;
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.
269 * This requires appropriate privilege (CAP_SYS_ADMIN).
271 * Return: %BTRFS_UTIL_OK on success, non-zero error code on failure.
273 enum btrfs_util_error btrfs_util_subvolume_info(const char *path, uint64_t id,
274 struct btrfs_util_subvolume_info *subvol);
277 * btrfs_util_subvolume_info_fd() - See btrfs_util_subvolume_info().
279 enum btrfs_util_error btrfs_util_subvolume_info_fd(int fd, uint64_t id,
280 struct btrfs_util_subvolume_info *subvol);
282 struct btrfs_util_qgroup_inherit;
285 * btrfs_util_create_subvolume() - Create a new subvolume.
286 * @path: Where to create the subvolume.
287 * @flags: Must be zero.
288 * @async_transid: If not NULL, create the subvolume asynchronously (i.e.,
289 * without waiting for it to commit it to disk) and return the transaction ID
290 * that it was created in. This transaction ID can be waited on with
291 * btrfs_util_wait_sync().
292 * @qgroup_inherit: Qgroups to inherit from, or NULL.
294 * Return: %BTRFS_UTIL_OK on success, non-zero error code on failure.
296 enum btrfs_util_error btrfs_util_create_subvolume(const char *path, int flags,
297 uint64_t *async_transid,
298 struct btrfs_util_qgroup_inherit *qgroup_inherit);
301 * btrfs_util_create_subvolume_fd() - Create a new subvolume given its parent
303 * @parent_fd: File descriptor of the parent directory where the subvolume
305 * @name: Name of the subvolume to create.
306 * @flags: See btrfs_util_create_subvolume().
307 * @async_transid: See btrfs_util_create_subvolume().
308 * @qgroup_inherit: See btrfs_util_create_subvolume().
310 * Return: %BTRFS_UTIL_OK on success, non-zero error code on failure.
312 enum btrfs_util_error btrfs_util_create_subvolume_fd(int parent_fd,
315 uint64_t *async_transid,
316 struct btrfs_util_qgroup_inherit *qgroup_inherit);
319 * btrfs_util_create_qgroup_inherit() - Create a qgroup inheritance specifier
320 * for btrfs_util_create_subvolume() or btrfs_util_create_snapshot().
321 * @flags: Must be zero.
322 * @ret: Returned qgroup inheritance specifier.
324 * The returned structure must be freed with
325 * btrfs_util_destroy_qgroup_inherit().
327 * Return: %BTRFS_UTIL_OK on success, non-zero error code on failure.
329 enum btrfs_util_error btrfs_util_create_qgroup_inherit(int flags,
330 struct btrfs_util_qgroup_inherit **ret);
333 * btrfs_util_destroy_qgroup_inherit() - Destroy a qgroup inheritance specifier
334 * previously created with btrfs_util_create_qgroup_inherit().
335 * @inherit: Specifier to destroy.
337 void btrfs_util_destroy_qgroup_inherit(struct btrfs_util_qgroup_inherit *inherit);
340 * btrfs_util_qgroup_inherit_add_group() - Add inheritance from a qgroup to a
341 * qgroup inheritance specifier.
342 * @inherit: Specifier to modify. May be reallocated.
343 * @qgroupid: ID of qgroup to inherit from.
345 * Return: %BTRFS_UTIL_OK on success, non-zero error code on failure.
347 enum btrfs_util_error btrfs_util_qgroup_inherit_add_group(struct btrfs_util_qgroup_inherit **inherit,
351 * btrfs_util_qgroup_inherit_get_groups() - Get the qgroups a qgroup inheritance
352 * specifier contains.
353 * @inherit: Qgroup inheritance specifier.
354 * @groups: Returned array of qgroup IDs.
355 * @n: Returned number of entries in the @groups array.
357 void btrfs_util_qgroup_inherit_get_groups(const struct btrfs_util_qgroup_inherit *inherit,
358 const uint64_t **groups, size_t *n);
364 #endif /* BTRFS_UTIL_H */