Module Name: src Committed By: bouyer Date: Fri Feb 11 12:35:27 UTC 2011
Modified Files: src/lib/libc/sys [bouyer-quota2]: quotactl.2 Log Message: Describe the new quotactl interface To generate a diff of this commit: cvs rdiff -u -r1.26 -r1.26.2.1 src/lib/libc/sys/quotactl.2 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
Modified files: Index: src/lib/libc/sys/quotactl.2 diff -u src/lib/libc/sys/quotactl.2:1.26 src/lib/libc/sys/quotactl.2:1.26.2.1 --- src/lib/libc/sys/quotactl.2:1.26 Mon May 31 12:16:20 2010 +++ src/lib/libc/sys/quotactl.2 Fri Feb 11 12:35:27 2011 @@ -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