Add and document new quoat_on and quota_off functions.

1 files changed, 85 insertions, 46 deletions

diff --git a/lib/libutil/quotafile.3 b/lib/libutil/quotafile.3
index d0c27d730b89..d2134c505306 100644
--- a/lib/libutil/quotafile.3
+++ b/lib/libutil/quotafile.3
@@ -30,14 +30,16 @@
 .Os
 .Sh NAME
 .Nm quota_open
+.Nm quota_close
+.Nm quota_on
+.Nm quota_off
+.Nm quota_read
+.Nm quota_write_limits
+.Nm quota_write_usage
 .Nm quota_fsname
 .Nm quota_qfname
 .Nm quota_maxid
 .Nm quota_check_path
-.Nm quota_read
-.Nm quota_write_limits
-.Nm quota_write_usage
-.Nm quota_close
 .Nd "Manipulate quotas"
 .Sh LIBRARY
 .Lb libutil
@@ -50,22 +52,26 @@
 .In libutil.h
 .Ft "struct quotafile *"
 .Fn quota_open "struct fstab *fs" "int quotatype" "int openflags"
-.Ft "const char *"
-.Fn quota_fsname "const struct quotafile *qf"
-.Ft "const char *"
-.Fn quota_qfname "const struct quotafile *qf"
 .Ft int
-.Fn quota_maxid "const struct quotafile *qf"
+.Fn quota_close "struct quotafile *qf"
 .Ft int
-.Fn quota_check_path "const struct quotafile *qf" "const char *path"
+.Fn quota_on "const struct quotafile *qf"
+.Ft int
+.Fn quota_off "const struct quotafile *qf"
 .Ft int
 .Fn quota_read "struct quotafile *qf" "struct dqblk *dqb" "int id"
 .Ft int
 .Fn quota_write_limits "struct quotafile *qf" "struct dqblk *dqb" "int id"
 .Ft int
 .Fn quota_write_usage "struct quotafile *qf" "struct dqblk *dqb" "int id"
+.Ft "const char *"
+.Fn quota_fsname "const struct quotafile *qf"
+.Ft "const char *"
+.Fn quota_qfname "const struct quotafile *qf"
 .Ft int
-.Fn quota_close "struct quotafile *qf"
+.Fn quota_maxid "const struct quotafile *qf"
+.Ft int
+.Fn quota_check_path "const struct quotafile *qf" "const char *path"
 .Sh DESCRIPTION
 These functions are designed to simplify access to filesystem quotas.
 If quotas are active on a filesystem,
@@ -103,46 +109,48 @@ flag should be specified if a new quota file of the requested type
 should be created if it does not already exist.
 .Pp
 The
-.Fn quota_fsname
-function returns a pointer to a buffer containing the path to the root
-of the file system that corresponds to its
-.Va qf
-argument, as listed in
-.Pa /etc/fstab .
-Note that this may be a symbolic link to the actual directory.
+.Fn quota_close
+function closes any open file descriptors and frees any storage
+associated with the filesystem and quota type referenced by
+.Va qf .
 .Pp
 The
-.Fn quota_qfname
-function returns a pointer to a buffer containing the name of the
-quota file that corresponds to its
+.Fn quota_on
+function enables quotas for the filesystem associated with its
 .Va qf
-argument.
-Note that this may be a symbolic link to the actual file.
-.Pp
+argument which may have been opened
+.Dv O_RDONLY
+or
+.Dv O_RDWR .
 The
-.Fn quota_maxid
-function returns the maximum user (or group)
-.Va id
-contained in the quota file associated with its
-.Va qf
-argument.
+.Fn quota_on
+function returns 0 if successful;
+otherwise the value\~-1 is returned and the global variable
+.Va errno
+is set to indicate the error, see
+.Xr quotactl 2
+for the possible errors.
 .Pp
 The
-.Fn quota_check_path
-function checks if the specified path is within the filesystem that
-corresponds to its
+.Fn quota_off
+function disables quotas for the filesystem associated with its
 .Va qf
-argument.
-If the
-.Va path
-argument refers to a symbolic link,
-.Fn quota_check_path
-will follow it.
+argument which may have been opened
+.Dv O_RDONLY
+or
+.Dv O_RDWR .
+The
+.Fn quota_off
+function returns 0 if successful;
+otherwise the value\~-1 is returned and the global variable
+.Va errno
+is set to indicate the error, see
+.Xr quotactl 2
+for the possible errors.
 .Pp
 The
 .Fn quota_read
-function reads the quota from the filesystem and quota type referenced
-by
+function reads the quota from the filesystem and quota type referenced by
 .Va qf
 for the user (or group) specified by
 .Va id
@@ -176,10 +184,41 @@ quota structure pointed to by
 .Va dqb .
 .Pp
 The
-.Fn quota_close
-function closes any open file descriptors and frees any storage
-associated with the filesystem and quota type referenced by
-.Va qf .
+.Fn quota_fsname
+function returns a pointer to a buffer containing the path to the root
+of the file system that corresponds to its
+.Va qf
+argument, as listed in
+.Pa /etc/fstab .
+Note that this may be a symbolic link to the actual directory.
+.Pp
+The
+.Fn quota_qfname
+function returns a pointer to a buffer containing the name of the
+quota file that corresponds to its
+.Va qf
+argument.
+Note that this may be a symbolic link to the actual file.
+.Pp
+The
+.Fn quota_maxid
+function returns the maximum user (or group)
+.Va id
+contained in the quota file associated with its
+.Va qf
+argument.
+.Pp
+The
+.Fn quota_check_path
+function checks if the specified path is within the filesystem that
+corresponds to its
+.Va qf
+argument.
+If the
+.Va path
+argument refers to a symbolic link,
+.Fn quota_check_path
+will follow it.
 .Sh IMPLEMENTATION NOTES
 If the underlying quota file is in the old 32-bit format, limit and
 usage values written to the quota file will be clipped to 32 bits.
@@ -230,4 +269,4 @@ The
 functions and this manual page were written by
 .An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org 
 and
-.An Marshall Kirk McKusick .
+.An Marshall Kirk McKusick Aq mckusick@mckusick.com .