mirror of
https://github.com/kdave/btrfs-progs
synced 2025-01-22 21:43:35 +00:00
1eb7b11303
The user transaction ioctls have been removed in kernel 4.17 by commit
7a5a07a81062 ("btrfs: Remove userspace transaction ioctls"), the
definitions are not relevant and can be removed.
The numbers could be reused in the future, eg. when there are no
maintained LTS kernels older than 4.19.
Signed-off-by: David Sterba <dsterba@suse.com>
191 lines
5.4 KiB
Plaintext
191 lines
5.4 KiB
Plaintext
btrfs-ioctl(3)
|
|
==============
|
|
|
|
NAME
|
|
----
|
|
|
|
btrfs-ioctl - documentation for the ioctl interface to btrfs
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
|
|
The ioctl() system call is a way how to request custom actions performed on a
|
|
filesystem beyond the standard interfaces (like syscalls). An ioctl is
|
|
specified by a number and an associated data structure that implement a
|
|
feature, usually not available in other filesystems. The number of ioctls grows
|
|
over time and in some cases get promoted to a VFS-level ioctl once other
|
|
filesystems adopt the functionality. Backward compatibility is maintained
|
|
and a formerly private ioctl number could become available on the VFS level.
|
|
|
|
|
|
DATA STRUCTURES AND DEFINITIONS
|
|
-------------------------------
|
|
|
|
[verse]
|
|
struct btrfs_ioctl_vol_args {
|
|
__s64 fd;
|
|
char name[BTRFS_PATH_NAME_MAX + 1];
|
|
};
|
|
|
|
[verse]
|
|
struct btrfs_ioctl_vol_args_v2 {
|
|
\__s64 fd;
|
|
\__u64 transid;
|
|
\__u64 flags;
|
|
union {
|
|
struct {
|
|
\__u64 size;
|
|
struct btrfs_qgroup_inherit \__user *qgroup_inherit;
|
|
};
|
|
__u64 unused[4];
|
|
};
|
|
char name[BTRFS_SUBVOL_NAME_MAX + 1];
|
|
};
|
|
|
|
[verse]
|
|
BTRFS_SUBVOL_NAME_MAX = 4039
|
|
BTRFS_PATH_NAME_MAX = 4087
|
|
|
|
OVERVIEW
|
|
--------
|
|
|
|
The ioctls are defined by a number and associated with a data structure that
|
|
contains further information. All ioctls use file descriptor (fd) as a reference
|
|
point, it could be the filesystem or a directory inside the filesystem.
|
|
|
|
An ioctl can be used in the following schematic way:
|
|
|
|
----------------
|
|
struct btrfs_ioctl_args args;
|
|
|
|
memset(&args, 0, sizeof(args));
|
|
args.key = value;
|
|
ret = ioctl(fd, BTRFS_IOC_NUMBER, &args);
|
|
----------------
|
|
|
|
The 'fd' is the entry point to the filesystem and for most ioctls it does not
|
|
matter which file or directory is that. Where it matters it's explicitly
|
|
mentioned. The 'args' is the associated data structure for the request. It's
|
|
strongly recommended to initialize the whole structure to zeros as this is
|
|
future-proof when the ioctl gets further extensions. Not doing that could lead
|
|
to mismatch of old userspace and new kernel versions, or vice versa.
|
|
The 'BTRFS_IOC_NUMBER' is says which operation should be done on the given
|
|
arguments. Some ioctls take a specific data structure, some of them share a
|
|
common one, no argument structure ioctls exist too.
|
|
|
|
The library 'libbtrfsutil' wraps a few ioctls for convenience. Using raw ioctls
|
|
is not discouraged but may be cumbersome though it does not need additional
|
|
library dependency. Backward compatibility is guaranteed and incompatible
|
|
changes usually lead to a new version of the ioctl. Enhancements of existing
|
|
ioctls can happen and depend on additional flags to be set. Zeroed unused
|
|
space is commonly understood as a mechanism to communicate the compatibility
|
|
between kernel and userspace and thus zeroing is really important. In exceptional
|
|
cases this is not enough and further flags need to be passed to distinguish
|
|
between zero as implicit unused initialization and a valid zero value. Such
|
|
cases are documented.
|
|
|
|
LIST OF IOCTLS
|
|
--------------
|
|
|
|
BTRFS_IOC_SUBVOL_CREATE -- (obsolete) create a subvolume
|
|
BTRFS_IOC_SNAP_CREATE
|
|
BTRFS_IOC_DEFRAG
|
|
BTRFS_IOC_RESIZE
|
|
BTRFS_IOC_SCAN_DEV
|
|
BTRFS_IOC_SYNC
|
|
BTRFS_IOC_CLONE
|
|
BTRFS_IOC_ADD_DEV
|
|
BTRFS_IOC_RM_DEV
|
|
BTRFS_IOC_BALANCE
|
|
BTRFS_IOC_CLONE_RANGE
|
|
BTRFS_IOC_SUBVOL_CREATE
|
|
BTRFS_IOC_SNAP_DESTROY
|
|
BTRFS_IOC_DEFRAG_RANGE
|
|
BTRFS_IOC_TREE_SEARCH
|
|
BTRFS_IOC_TREE_SEARCH_V2
|
|
BTRFS_IOC_INO_LOOKUP
|
|
BTRFS_IOC_DEFAULT_SUBVOL
|
|
BTRFS_IOC_SPACE_INFO
|
|
BTRFS_IOC_START_SYNC
|
|
BTRFS_IOC_WAIT_SYNC
|
|
BTRFS_IOC_SNAP_CREATE_V2
|
|
BTRFS_IOC_SUBVOL_CREATE_V2 -- create a subvolume
|
|
BTRFS_IOC_SUBVOL_GETFLAGS
|
|
BTRFS_IOC_SUBVOL_SETFLAGS
|
|
BTRFS_IOC_SCRUB
|
|
BTRFS_IOC_SCRUB_CANCEL
|
|
BTRFS_IOC_SCRUB_PROGRESS
|
|
BTRFS_IOC_DEV_INFO
|
|
BTRFS_IOC_FS_INFO
|
|
BTRFS_IOC_BALANCE_V2
|
|
BTRFS_IOC_BALANCE_CTL
|
|
BTRFS_IOC_BALANCE_PROGRESS
|
|
BTRFS_IOC_INO_PATHS
|
|
BTRFS_IOC_LOGICAL_INO
|
|
BTRFS_IOC_SET_RECEIVED_SUBVOL
|
|
BTRFS_IOC_SEND
|
|
BTRFS_IOC_DEVICES_READY
|
|
BTRFS_IOC_QUOTA_CTL
|
|
BTRFS_IOC_QGROUP_ASSIGN
|
|
BTRFS_IOC_QGROUP_CREATE
|
|
BTRFS_IOC_QGROUP_LIMIT
|
|
BTRFS_IOC_QUOTA_RESCAN
|
|
BTRFS_IOC_QUOTA_RESCAN_STATUS
|
|
BTRFS_IOC_QUOTA_RESCAN_WAIT
|
|
BTRFS_IOC_GET_FSLABEL
|
|
BTRFS_IOC_SET_FSLABEL
|
|
BTRFS_IOC_GET_DEV_STATS
|
|
BTRFS_IOC_DEV_REPLACE
|
|
BTRFS_IOC_FILE_EXTENT_SAME
|
|
BTRFS_IOC_GET_FEATURES
|
|
BTRFS_IOC_SET_FEATURES
|
|
BTRFS_IOC_GET_SUPPORTED_FEATURES
|
|
|
|
DETAILED DESCRIPTION
|
|
--------------------
|
|
|
|
BTRFS_IOC_SUBVOL_CREATE
|
|
~~~~~~~~~~~~~~~~~~~~~~~
|
|
NOTE: obsoleted by BTRFS_IOC_SUBVOL_CREATE_V2
|
|
|
|
_(since: 3.0, obsoleted: 4.0)_ Create a subvolume.
|
|
|
|
[horizontal]
|
|
ioctl fd:: file descriptor of the parent directory of the new subvolume
|
|
argument type:: struct btrfs_ioctl_vol_args
|
|
fd:: ignored
|
|
name:: name of the subvolume, although the buffer can be almost 4k, the file
|
|
size is limited by linux VFS to 255 characters and must not contain a slash
|
|
('/')
|
|
|
|
|
|
BTRFS_IOC_SUBVOL_CREATE_V2
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
NOTE: obsoletes BTRFS_IOC_SUBVOL_CREATE
|
|
|
|
_(since: 3.6)_ Create a subvolume, qgroup inheritance can be specified.
|
|
|
|
[horizontal]
|
|
ioctl fd:: file descriptor of the parent directory of the new subvolume
|
|
argument type:: struct btrfs_ioctl_vol_args_v2
|
|
fd:: ignored
|
|
transid:: ignored
|
|
flags:: ignored
|
|
size:: ...
|
|
qgroup_inherit:: ...
|
|
name:: name of the subvolume, although the buffer can be almost 4k, the file
|
|
size is limited by linux VFS to 255 characters and must not contain a slash
|
|
('/')
|
|
devid:: ...
|
|
|
|
|
|
AVAILABILITY
|
|
------------
|
|
*btrfs* is part of btrfs-progs.
|
|
Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
|
|
further details.
|
|
|
|
SEE ALSO
|
|
--------
|
|
`ioctl`(2)
|