[src/bouyer-quota2]: src/lib/libc/sys Describe the new quotactl interface

[bouyer <bouyer%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/38d6741d578a
branches:  bouyer-quota2
changeset: 761158:38d6741d578a
user:      bouyer <bouyer%NetBSD.org@localhost>
date:      Fri Feb 11 12:35:27 2011 +0000

description:
Describe the new quotactl interface

diffstat:

 lib/libc/sys/quotactl.2 |  245 +++++++++++++++++++++++------------------------
 1 files changed, 118 insertions(+), 127 deletions(-)

diffs (293 lines):

diff -r 68cf6a746789 -r 38d6741d578a lib/libc/sys/quotactl.2
--- a/lib/libc/sys/quotactl.2   Fri Feb 11 11:38:44 2011 +0000
+++ b/lib/libc/sys/quotactl.2   Fri Feb 11 12:35:27 2011 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: quotactl.2,v 1.26 2010/05/31 12:16:20 njoly Exp $
+.\"    $NetBSD: quotactl.2,v 1.26.2.1 2011/02/11 12:35:27 bouyer Exp $
 .\"
 .\" Copyright (c) 1983, 1990, 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -32,7 +32,7 @@
 .\"
 .\"    @(#)quotactl.2  8.2 (Berkeley) 3/10/95
 .\"
-.Dd October 9, 2008
+.Dd February 11, 2011
 .Dt QUOTACTL 2
 .Os
 .Sh NAME
@@ -41,102 +41,117 @@
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
-.In ufs/ufs/quota.h
+.In prop/proplib.h
+.In sys/quota.h
 .Ft int
-.Fn quotactl "const char *path" "int cmd" "int id" "void *addr"
+.Fn quotactl "const char *path" "struct plistref *pref"
 .Sh DESCRIPTION
 The
 .Fn quotactl
-call enables, disables and
-manipulates filesystem quotas.
-A quota control command
-given by
-.Fa cmd
+call manipulates filesystem quotas.
+A quota control command described by 
+.Fa "struct plistref *"
 operates on the given filename
-.Fa path
-for the given user
-.Fa id .
-The address of an optional command specific data structure,
-.Fa addr ,
-may be given; its interpretation
-is discussed below with each command.
-.Pp
-Currently quotas are supported only for the ``ffs''
-and ``lfs'' filesystem.
-For both of them,
-a command is composed of a primary command (see below)
-and a command type used to interpret the
-.Fa id .
-Types are supported for interpretation of user identifiers
-and group identifiers.
-The ``ffs'' and ``lfs'' specific commands are:
-.Bl -tag -width Q_QUOTAON
-.It Dv Q_QUOTAON
-Enable disk quotas for the filesystem specified by
-.Fa path .
-The command type specifies the type of the quotas being enabled.
-The
-.Fa addr
-argument specifies a file from which to take the quotas.
-The quota file must exist;
-it is normally created with the
-.Xr quotacheck 8
-program.
-The
-.Fa id
-argument is unused.
-Only the super-user may turn quotas on.
-.It Dv Q_QUOTAOFF
-Disable disk quotas for the filesystem specified by
 .Fa path .
-The command type specifies the type of the quotas being disabled.
-The
-.Fa addr
-and
-.Fa id
-arguments are unused.
-Only the super-user may turn quotas off.
-.It Dv Q_GETQUOTA
-Get disk quota limits and current usage for the user or group
-(as determined by the command type) with identifier
-.Fa id .
-.Fa addr
-is a pointer to a
-.Fa struct dqblk
-structure (defined in
-.In ufs/ufs/quota.h ) .
-.It Dv Q_SETQUOTA
-Set disk quota limits for the user or group
-(as determined by the command type) with identifier
-.Fa id .
-.Fa addr
-is a pointer to a
-.Fa struct dqblk
-structure (defined in
-.In ufs/ufs/quota.h ) .
-The usage fields of the
-.Fa dqblk
-structure are ignored.
-This call is restricted to the super-user.
-.It Dv Q_SETUSE
-Set disk usage for the user or group
-(as determined by the command type) with identifier
-.Fa id .
-.Fa addr
-is a pointer to a
-.Fa struct dqblk
-structure (defined in
-.In ufs/ufs/quota.h ) .
-Only the usage fields are used.
-This call is restricted to the super-user.
-.It Dv Q_SYNC
-Update the on-disk copy of quota usages.
-The command type specifies which type of quotas are to be updated.
-The
-.Fa id
-and
-.Fa addr
-parameters are ignored.
+.Pp
+The top-level object of the property list sent to the kernel is a dictionary.
+It holds an integer with key "interface version", which must be 1 at this 
+time.
+The key "commands" holds an array of dictionaries, each dictionary
+describe a command.
+.Pp
+A command dictionary has the following keys:
+.Bl -tag -width command
+.It Dv command 
+A string describing the command to execute.
+.It Dv data
+An array of arguments to the command.
+.It Dv type
+A string describing the type of quota to address. At this time this can
+be either "user" or "group".
+.El
+.Pp
+The data array is an array of dictionaries, the dictionary structure
+depends on the command.
+If the comman takes no arguments, the array must be present and empty.
+A dictionary describing a quota entry is common to many commands arguments
+or replies.
+It has the following keys:
+.Bl -tag -width block
+.It Dv block
+A dictionary describing quota values and limits for block usage.
+.It Dv file
+A dictionary describing quota values and limits for inode usage.
+.It Dv id
+either an unigned integer, or the string "default".
+If this key is an integer, the value is the user or group id this quota entry
+belongs to.
+If this key is the string "default", this quota entry describe the
+default quotas for this filesystem.
+.El
+.Pp
+The block or file dictionaries have the following structures:
+.Bl -tag -width expire time
+.It Dv usage
+an unsigned integer which contains the current usage.
+.It Dv soft
+unsigned integer containing the soft limit.
+The value defined by the macro UQUAD_MAX means there is no limit.
+.It Dv hard
+unsigned integer containing the hard limit.
+The value defined by the macro UQUAD_MAX means there is no limit.
+.It Dv grace time
+integer, the grace delay in seconds which should be applied when usage
+goes over the soft limit.
+.It Dv expire time
+integer, the time (in seconds since epoch) at which the grace delay expires.
+This key is only valid when usage is over the soft limit.
+.El
+.Pp
+On return the "struct plistref *" contains an updated plist.
+It has the same structure as the plist sent to the kernel.
+The command dictionary gains an additionnal key "return", and integer holding
+an errno which is the status of the comamnd.
+The data array is updated with replies from the command.
+.Pp
+Commands are:
+.Bl -tag -width "get version"
+.It Dv "get version"
+get the kernel quota version implementation for the specified filesystem and
+type.
+The data array in the reply has a single dictionary, which has a single
+integer key "version".
+At this time version can be "1" (the legacy quota implementation, with usages
+and limits stored in an external file) or "2" (the new quota implementation,
+where usages and limits are integrated in the filesystem metadatas).
+.It Dv "get"
+Get a quota entry for the specified id.
+The command argument is one or more "id" keys.
+The command reply is the requested quota entries, as described above.
+.It Dv "getall"
+Get all quota entries (kernel quota version 2 only).
+This command takes no arguments, the reply is all the existing quota entries
+for this filesystem and type.
+.It Dv "set"
+create or update quota limits.
+Argument is one or more quota entries holding the updated quota limits.
+There is no reply.
+.It Dv "clear"
+clear specified quota entries (kernel quota version 2 only).
+Each quota entry is either returned to the free list if both block and
+file usage is 0, or limits are reverted to the default values otherwise.
+The command argument is one or more "id" keys.
+There is no reply.
+.It Dv quotaon
+enable the specifed quota type on the specified filesystem (kernel quota
+version 1 only).
+Argument is a string with key "quotafile", which contains the path
+to the external file holding usages and limits.
+There is no reply.
+.It Dv quotaoff
+disable the specifed quota type on the specified filesystem (kernel quota
+version 1 only).
+There is no arguments and no replies.
 .El
 .Sh RETURN VALUES
 A successful call returns 0,
@@ -149,55 +164,31 @@
 call will fail if:
 .Bl -tag -width Er
 .It Bq Er EOPNOTSUPP
-The kernel has not been compiled with the
+Either the kernel has not been compiled with the
 .Dv QUOTA
-option.
-.It Bq Er EUSERS
-The quota table cannot be expanded.
+or
+.Dv QUOTA2
+options, or the mounted filesystem doesn't support quota.
+.It Bq Er ENOMEM
+Memory could not be allocated to handle the plist.
 .It Bq Er EINVAL
-.Fa cmd
-or the command type is invalid.
-.It Bq Er EACCES
-In
-.Dv Q_QUOTAON ,
-the quota file is not a plain file, or
-search permission is denied for a component of a path prefix.
-.It Bq Er ENOTDIR
-A component of a path prefix was not a directory.
-.It Bq Er ENAMETOOLONG
-A component of a pathname exceeded
-.Brq Dv NAME_MAX
-characters, or an entire path name exceeded
-.Brq Dv PATH_MAX
-characters.
-.It Bq Er ENOENT
-A filename does not exist.
-.It Bq Er ELOOP
-Too many symbolic links were encountered in translating a pathname.
-.It Bq Er EROFS
-In
-.Dv Q_QUOTAON ,
-the quota file resides on a read-only filesystem.
-.It Bq Er EIO
-An
-.Tn I/O
-error occurred while reading from or writing
-to a file containing quotas.
+The plist is invalid.
 .It Bq Er EFAULT
-.Fa path
+.Fa struct plistref *
 points outside the process's allocated address space, or
 an invalid
 .Fa addr
 was supplied; the associated structure could not be copied in or out
 of the kernel.
-.It Bq Er EPERM
-The call was privileged and the caller was not the super-user.
 .El
 .Sh SEE ALSO
 .Xr quota 1 ,
+.Xr proplib 3 ,
+.Xr prop_send_syscall 3 ,
 .Xr fstab 5 ,
 .Xr edquota 8 ,
 .Xr quotacheck 8 ,
+.Xr quotactl 8 ,
 .Xr quotaon 8 ,
 .Xr repquota 8
 .Sh HISTORY