btrfs-progs: docs: start ioctl documentation manual page

Start documenting the ioctl interface to btrfs. The overall structure
should be settled, the formatting of the ioctl description may change in
the future, newly added ioctl descriptions should follow the examples of
BTRFS_IOC_SUBVOL_CREATE.

The document is not finished yet and will not be installed until most of
ioctls' details are filled in.

Signed-off-by: David Sterba <dsterba@suse.com>

2 files changed, 155 insertions, 7 deletions

diff --git a/Documentation/Makefile.in b/Documentation/Makefile.in
index 539c6b55..bdc3dc3f 100644
--- a/Documentation/Makefile.in
+++ b/Documentation/Makefile.in
@@ -32,19 +32,19 @@ MAN8_TXT += btrfs-property.asciidoc
 # Category 5 manual page
 MAN5_TXT += btrfs-man5.asciidoc
 
-MAN_TXT = $(MAN8_TXT) $(MAN5_TXT)
+MAN3_TXT += btrfs-ioctl.asciidoc
+
+MAN_TXT = $(MAN3_TXT) $(MAN8_TXT) $(MAN5_TXT)
 MAN_XML = $(patsubst %.asciidoc,%.xml,$(MAN_TXT))
 MAN_HTML = $(patsubst %.asciidoc,%.html,$(MAN_TXT))
-
-DOC_MAN5 = $(patsubst %.asciidoc,%.5,$(MAN5_TXT))
+GZ_MAN3 = $(patsubst %.asciidoc,%.3.gz,$(MAN3_TXT))
 GZ_MAN5 = $(patsubst %.asciidoc,%.5.gz,$(MAN5_TXT))
-
-DOC_MAN8 = $(patsubst %.asciidoc,%.8,$(MAN8_TXT))
 GZ_MAN8 = $(patsubst %.asciidoc,%.8.gz,$(MAN8_TXT))
 
 mandir ?= $(prefix)/share/man
-man8dir = $(mandir)/man8
+man3dir = $(mandir)/man3
 man5dir = $(mandir)/man5
+man8dir = $(mandir)/man8
 
 ASCIIDOC = @ASCIIDOC@
 ASCIIDOC_EXTRA =
@@ -72,7 +72,8 @@ endif
 endif
 
 all: man
-man: man5 man8
+man: man3 man5 man8
+man3: $(GZ_MAN3)
 man5: $(GZ_MAN5)
 man8: $(GZ_MAN8)
 html: $(MAN_HTML)
@@ -99,12 +100,19 @@ uninstall:
 clean:
 	$(QUIET_RM)$(RM) -f *.xml *.xml+ *.5 *.5.gz *.8 *.8.gz *.html
 
+%.3.gz : %.3
+	$(QUIET_GZIP)$(GZIPCMD) -n -c $< > $@
+
 %.5.gz : %.5
 	$(QUIET_GZIP)$(GZIPCMD) -n -c $< > $@
 
 %.8.gz : %.8
 	$(QUIET_GZIP)$(GZIPCMD) -n -c $< > $@
 
+%.3 : %.xml
+	$(QUIET_XMLTO)$(RM) -f $@ && \
+	$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
+
 %.5 : %.xml
 	$(QUIET_XMLTO)$(RM) -f $@ && \
 	$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
diff --git a/Documentation/btrfs-ioctl.asciidoc b/Documentation/btrfs-ioctl.asciidoc
new file mode 100644
index 00000000..11bf62b1
--- /dev/null
+++ b/Documentation/btrfs-ioctl.asciidoc
@@ -0,0 +1,140 @@
+btrfs-ioctl(3)
+================
+
+NAME
+----
+
+btrfs-ioctl - documentation for the ioctl interface to btrfs
+
+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
+
+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_TRANS_START
+ BTRFS_IOC_TRANS_END
+ 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:: 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:: 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)