NetBSD/lib/libc/sys/quotactl.2

.\"	$NetBSD: quotactl.2,v 1.29 2011/03/25 17:15:26 njoly Exp $
.\"
.\" Copyright (c) 1983, 1990, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" Robert Elz at The University of Melbourne.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	@(#)quotactl.2	8.2 (Berkeley) 3/10/95
.\"
.Dd February 11, 2011
.Dt QUOTACTL 2
.Os
.Sh NAME
.Nm quotactl
.Nd manipulate file system quotas
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In prop/proplib.h
.In sys/quota.h
.Ft int
.Fn quotactl "const char *path" "struct plistref *pref"
.Sh DESCRIPTION
The
.Fn quotactl
call manipulates file system quotas.
A quota control command described by
.Fa "struct plistref *"
operates on the given filename
.Fa path .
.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 command 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 unsigned 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 file system.
.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
.Dv UQUAD_MAX
means there is no limit.
.It Dv hard
unsigned integer containing the hard limit.
The value defined by the macro
.Dv 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 additional key "return", and integer holding
an errno which is the status of the command.
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 file system 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 file system metadata).
.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 file system 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 specified quota type on the specified file system (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 specified quota type on the specified file system (kernel quota
version 1 only).
There is no arguments and no replies.
.El
.Sh RETURN VALUES
A successful call returns 0,
otherwise the value \-1 is returned and the global variable
.Va errno
indicates the reason for the failure.
.Sh FILES
Example of usage of the
.Nm
syscall, with construction of the pref argument an interpretation of
the reply, can be found in the following
.Nx
source files:
.Bl -tag
.It src/usr.bin/quota/getvfsquota.c
.It src/usr.sbin/repquota/repquota.c
.It src/usr.sbin/edquota/edquota.c
.It src/usr.sbin/quotaon/quotaon.c
.It src/sys/ufs/ufs/quota2_prop.c
.El
.Sh ERRORS
A
.Fn quotactl
call will fail if:
.Bl -tag -width Er
.It Bq Er EFAULT
.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 EINVAL
The plist is invalid.
.It Bq Er ENOMEM
Memory could not be allocated to handle the plist.
.It Bq Er EOPNOTSUPP
Either the kernel has not been compiled with the
.Dv QUOTA
or
.Dv QUOTA2
options, or the mounted file system doesn't support quota.
.El
.Sh SEE ALSO
.Xr quota 1 ,
.Xr prop_send_syscall 3 ,
.Xr proplib 3 ,
.Xr fstab 5 ,
.Xr edquota 8 ,
.Xr quotacheck 8 ,
.Xr quotactl 8 ,
.Xr quotaon 8 ,
.Xr repquota 8
.Sh HISTORY
The
.Fn quotactl
function call appeared in
.Bx 4.3 Reno .
.Sh BUGS
There should be some way to integrate this call with the resource
limit interface provided by
.Xr setrlimit 2
and
.Xr getrlimit 2 .