summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDavid Sterba <dsterba@suse.com>2017-09-11 20:26:04 +0200
committerDavid Sterba <dsterba@suse.com>2017-09-25 15:18:09 +0200
commitbc2c60ad31fd8933a0c138d6c2a5c9bc495b97ce (patch)
treed2607a4fcd67cc235d6bbf9bc8ef022bec1ebb13
parent509af95c9281549cc93805aca19ed6e7f8de024a (diff)
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>
-rw-r--r--Documentation/Makefile.in22
-rw-r--r--Documentation/btrfs-ioctl.asciidoc140
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)