btrfs-progs: docs: convert btrfs-ioctl.asciidoc to RST
Signed-off-by: David Sterba <dsterba@suse.com>
This commit is contained in:
David Sterba
parent
fa8c64ec29
commit
99a7f7988f
|
|
@ -1,5 +1,4 @@
|
|||
# Source files for manual pages are listed in conf.py in variable man_pages
|
||||
# To convert: btrfs-ioctl.asciidoc
|
||||
|
||||
# You can set these variables from the command line, and also from the
|
||||
# environment for the first two.
|
||||
|
|
|
|||
|
|
@ -1,190 +0,0 @@
|
|||
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)
|
||||
|
|
@ -0,0 +1,205 @@
|
|||
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
|
||||
-------------------------------
|
||||
|
||||
.. code-block::
|
||||
|
||||
struct btrfs_ioctl_vol_args {
|
||||
__s64 fd;
|
||||
char name[BTRFS_PATH_NAME_MAX + 1];
|
||||
};
|
||||
|
||||
.. code-block::
|
||||
|
||||
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];
|
||||
};
|
||||
|
||||
.. code-block::
|
||||
|
||||
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:
|
||||
|
||||
.. code-block::
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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)
|
||||
|
|
@ -52,3 +52,4 @@ Welcome to BTRFS documentation!
|
|||
project-index
|
||||
trouble-index
|
||||
Experimental
|
||||
btrfs-ioctl
|
||||
|
|
|
|||
Loading…
Reference in New Issue