From 99a7f7988fd1ac4f276c056f34f94b88fbdf92c0 Mon Sep 17 00:00:00 2001 From: David Sterba Date: Tue, 17 May 2022 23:11:03 +0200 Subject: [PATCH] btrfs-progs: docs: convert btrfs-ioctl.asciidoc to RST Signed-off-by: David Sterba --- Documentation/Makefile.in | 1 - Documentation/btrfs-ioctl.asciidoc | 190 -------------------------- Documentation/btrfs-ioctl.rst | 205 +++++++++++++++++++++++++++++ Documentation/index.rst | 1 + 4 files changed, 206 insertions(+), 191 deletions(-) delete mode 100644 Documentation/btrfs-ioctl.asciidoc create mode 100644 Documentation/btrfs-ioctl.rst diff --git a/Documentation/Makefile.in b/Documentation/Makefile.in index 67cad134..ffc25386 100644 --- a/Documentation/Makefile.in +++ b/Documentation/Makefile.in @@ -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. diff --git a/Documentation/btrfs-ioctl.asciidoc b/Documentation/btrfs-ioctl.asciidoc deleted file mode 100644 index b7082f8a..00000000 --- a/Documentation/btrfs-ioctl.asciidoc +++ /dev/null @@ -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) diff --git a/Documentation/btrfs-ioctl.rst b/Documentation/btrfs-ioctl.rst new file mode 100644 index 00000000..a1de0948 --- /dev/null +++ b/Documentation/btrfs-ioctl.rst @@ -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) diff --git a/Documentation/index.rst b/Documentation/index.rst index 3cadc907..ca812b1b 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -52,3 +52,4 @@ Welcome to BTRFS documentation! project-index trouble-index Experimental + btrfs-ioctl