From bc2c60ad31fd8933a0c138d6c2a5c9bc495b97ce Mon Sep 17 00:00:00 2001 From: David Sterba Date: Mon, 11 Sep 2017 20:26:04 +0200 Subject: 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 --- Documentation/Makefile.in | 22 ++++-- Documentation/btrfs-ioctl.asciidoc | 140 +++++++++++++++++++++++++++++++++++++ 2 files changed, 155 insertions(+), 7 deletions(-) create mode 100644 Documentation/btrfs-ioctl.asciidoc (limited to 'Documentation') 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) -- cgit v1.2.3