man/man2/quotactl[_fd].2: Document quotactl_fd() syscall; add link page

I based these changes on kernel commits [1], [2].  Man-page wording
changes inspired by [3].  Rationale for the syscall itself is from [4].

[1] linux.git 9dfa23c8de925041b7b45637a1a80a98a22f19dd
("quota: Add mountpath based quota support")
[2] linux.git 64c2c2c62f92339b176ea24403d8db16db36f9e6
("quota: Change quotactl_path() systcall to an fd-based one")
[3] <https://lore.kernel.org/all/20210304123541.30749-4-s.hauer@pengutronix.de/>
[4] <https://lwn.net/Articles/859679/>

Reviewed-by: Jan Kara <jack@suse.cz>
Signed-off-by: trillian <trillian@r9.pm>
Message-ID: <d89a3f923f2954d161a8d60e3002e1496d3327d5.1757174497.git.trillian@r9.pm>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

diff --git a/man/man2/quotactl.2 b/man/man2/quotactl.2
index 126426b8ae3a492fc211d86365a04b6b00db3abf..13848d50a5a1dabc8dd03a38145334dbc835f479 100644 (file)
--- a/man/man2/quotactl.2
+++ b/man/man2/quotactl.2
@@ -4,7 +4,7 @@
 .\"
 .TH quotactl 2 (date) "Linux man-pages (unreleased)"
 .SH NAME
-quotactl \- manipulate disk quotas
+quotactl, quotactl_fd \- manipulate disk quotas
 .SH LIBRARY
 Standard C library
 .RI ( libc ,\~ \-lc )
@@ -17,7 +17,19 @@ Standard C library
 .P
 .BI "int quotactl(int " op ", const char *_Nullable " special ", int " id ,
 .BI "             caddr_t " addr );
+.P
+.BR "#include <sys/syscall.h>" "    /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
+.P
+.BI "int syscall(SYS_quotactl_fd, int " fd ", int " op ", int " id \
+", caddr_t " addr );
 .fi
+.P
+.IR Note :
+glibc provides no wrapper for
+.BR quotactl_fd (),
+necessitating the use of
+.BR syscall (2).
 .SH DESCRIPTION
 The quota system can be used to set per-user, per-group, and per-project limits
 on the amount of disk space used on a filesystem.
@@ -31,7 +43,14 @@ after this, the soft limit counts as a hard limit.
 .P
 The
 .BR quotactl ()
-call manipulates disk quotas.
+and
+.BR quotactl_fd ()
+calls manipulate disk quotas.
+The difference between these functions is
+the way the filesystem being manipulated is specified,
+see description of the arguments below.
+See NOTES for why one variant might be preferred over the other.
+.P
 The
 .I op
 argument indicates an operation to be applied to the user or
@@ -56,11 +75,21 @@ The
 .I subop
 value is described below.
 .P
-The
+For
+.BR quotactl (),
+the
 .I special
 argument is a pointer to a null-terminated string containing the pathname
 of the (mounted) block special device for the filesystem being manipulated.
 .P
+For
+.BR quotactl_fd (),
+the
+.I fd
+argument is a file descriptor (which may be opened with the
+.B O_PATH
+flag) referring to a file or directory on the filesystem being manipulated.
+.P
 The
 .I addr
 argument is the address of an optional, operation-specific, data structure
@@ -118,6 +147,18 @@ field returned by the
 .B Q_GETINFO
 operation.
 .IP
+The
+.BR quotactl_fd ()
+variant of this system call ignores the
+.I addr
+and
+.I id
+arguments, so the
+.B Q_QUOTAON
+operation of
+.BR quotactl_fd ()
+is only suitable for work with hidden system inodes.
+.IP
 This operation requires privilege
 .RB ( CAP_SYS_ADMIN ).
 .TP
@@ -350,10 +391,14 @@ where the format number will be stored.
 .TP
 .B Q_SYNC
 Update the on-disk copy of quota usages for a filesystem.
-If
+For
+.BR quotactl (),
+if
 .I special
 is NULL, then all filesystems with active quotas are sync'ed.
-The
+.RB ( quotactl_fd ()
+always sync's only one filesystem.)
+In both cases, the
 .I addr
 and
 .I id
@@ -770,6 +815,7 @@ but there is no ID greater than or equal to
 .I id
 that has an active quota.
 .SH NOTES
+.SS Alternative XFS header
 Instead of
 .I <xfs/xqm.h>
 one can use
@@ -797,6 +843,28 @@ constants for the available quota types, but their values are the same as for
 constants without the
 .B XQM_
 prefix.
+.SS quotactl() versus quotactl_fd()
+The original
+.BR quotactl ()
+variant of this system call requires specifying
+the block device containing the filesystem to operate on.
+This makes it impossible to use
+in cases where the filesystem has no backing block device (e.g. tmpfs).
+Even when the block device does exist, it might be difficult to locate
+(requires scanning
+.I /proc/self/mounts
+and even some filesystem-specific parsing in the case of e.g. bcachefs).
+.BR quotactl_fd ()
+instead works on the mount point,
+which avoids this limitation and is simpler to use
+(since the filesystem to manipulate is typically specified by its mount
+point anyway).
+.SH STANDARDS
+Linux.
+.SH HISTORY
+.TP
+.BR quotactl_fd ()
+Linux 5.14.
 .SH SEE ALSO
 .BR quota (1),
 .BR getrlimit (2),

diff --git a/man/man2/quotactl_fd.2 b/man/man2/quotactl_fd.2
new file mode 100644 (file)
index 0000000..5f63187
--- /dev/null
+++ b/man/man2/quotactl_fd.2
@@ -0,0 +1 @@
+.so man2/quotactl.2