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, 2012 .Dt __QUOTACTL 2 .Os .Sh NAME .Nm __quotactl .Nd manipulate file system quotas .Sh LIBRARY .Lb libc .Sh SYNOPSIS n sys/quota.h n sys/quotactl.h .Ft int .Fn __quotactl "const char *path" "struct quotactl_args *args" .Sh DESCRIPTION The .Fn __quotactl call manipulates file system quotas. This is an internal interface and is documented for reference purposes only. All application and utility code should use the .Xr libquota 3 interface.
p The .Fn __quotactl function performs one of several quota-related operations on the file system named by .Fa path . The operation and arguments to that operation are passed in the .Fa args argument. The operation is stored in the .Fa qc_op member of .Fa args . The arguments are placed in a union such that the first and second arguments of the operation .Dv QUOTACTL_EXAMPLE are found as the members .Fa u.example.qc_arg1 and .Fa u.example.qc_arg2 . The descriptions below will refer to the operations as functions of the form .Fn QUOTACTL_EXAMPLE "int arg1" "int arg2" and elide the encoding of these arguments into the .Fa args structure. Explicit mention of the .Fa path argument is also omitted.
p
There are fourteen quota control operations.
These are:
l -tag -width abcdef ************************************************************
t Fn QUOTACTL_STAT "struct quotastat *info" Information about the quota implementation on the selected volume is
returned in
.Fa info .
The
.Dv quotastat
structure contains the following members:
l -tag -width qs_restrictions t qs_implname A human-readable string describing the underlying implementation of
quotas.
This is suitable for display to users
q and system administrators
but should not be interpreted by software.
See
.Xr quota_getimplname 3 .
t qs_numidtypes The number of ID types supported by this implementation.
See
.Xr quota_getnumidtypes 3 .
t qs_numobjtypes The number of object types supported by this implementation.
See
.Xr quota_getnumobjtypes 3 .
t qs_restrictions Flags identifying specific semantic limitations of the implementation.
See
.Xr quota_getrestrictions 3 .
.El
************************************************************
t Fn QUOTACTL_IDTYPESTAT "int idtype" "struct quotaidtypestat *info" Information about a particular ID type on the selected volume is
returned in
.Fa info .
The
.Dv quotaidtypestat
structure contains the following members:
l -tag -width qs_restrictions t qis_name The name of the ID type.
See
.Xr quota_idtype_getname 3 .
.El
************************************************************
t Fn QUOTACTL_OBJYPESTAT "int objtype" "struct quotaobjtypestat *info" Information about a particular object type on the selected volume is
returned in
.Fa info .
The
.Dv quotaobjtypestat
structure contains the following members:
l -tag -width qs_restrictions t qos_name The name of the object type.
See
.Xr quota_objtype_getname 3 .
t qos_isbytes A flag that is nonzero if the object type is something measured in
bytes.
See
.Xr quota_objtype_isbytes 3 .
.El
************************************************************
t Fn QUOTACTL_GET "const struct quotakey *key" "struct quotaval *val" Return in
.Fa val
the quota information selected by
.Fa key .
See
.Xr quota_get 3 .
************************************************************
t Fn QUOTACTL_PUT "const struct quotakey *key" "const struct quotaval *val" The quota information selected by
.Fa key
is updated to the values provided in
.Fa val .
Note that the current usage information, which is file system
meta-data, cannot be updated via this interface.
If the usage information is incorrect a tool such as
.Xr fsck 8
or
.Xr quotacheck 8
with file-system-specific knowledge must be used to repair the
on-disk information.
See
.Xr quota_put 3 .
************************************************************
t Fn QUOTACTL_DELETE "const struct quotakey *key" The quota information selected by
.Fa key
is removed.
See
.Xr quota_delete 3 .
************************************************************
t Fn QUOTACTL_CURSOROPEN "struct quotakcursor *cursor" A cursor for iterating the quota information is created.
The
.Dv quotakcursor
structure is a semi-opaque type holding the iteration state used by
the quota implementation.
The caller is responsible for allocating and maintaining storage for
the cursor.
Every cursor that is opened should be closed.
It is not specified whether a cursor remains valid if
.Xr memcpy 3
is used to move it to a different location in user memory.
It is not specified whether or how a cursor may be duplicated.
Passing an uninitialized, corrupted, or closed cursor to operations
other than
.Fn QUOTACTL_CURSOROPEN
will produce unspecified behavior.
As per general standards for system calls such actions must not
produce undefined or materially adverse behavior in the kernel;
however, the effect on a user process may be arbitrary.
The
.Xr libquota 3
interface wraps the system call level quota cursors in a friendlier
interface.
See
.Xr quota_opencursor 3 .
************************************************************
t Fn QUOTACTL_CURSORCLOSE "struct quotakcursor *cursor" The cursor passed in is closed.
See
.Xr quotacursor_close 3 .
************************************************************
t Fn QUOTACTL_CURSORSKIPIDTYPE "struct quotakcursor *cursor" "int idtype" This operation provides a hint that iteration can skip over a
particular ID type.
The implementation is not obliged to honor the hint.
See
.Xr quotacursor_skipidtype 3 .
************************************************************
t Fn QUOTACTL_CURSORGET "struct quotakcursor *cursor" "struct quotakey *keys" "struct quotaval *vals" "unsigned maxnum" "unsigned *ret" This operation retrieves data at the current cursor position and
advances it.
Up to
.Fa maxnum
quota records are retrieved and stored into the arrays named by
.Fa keys
and
.Fa vals .
The number of records retrieved is stored into the variable pointed to
by
.Fa ret .
See
.Xr quotacursor_get 3
and
.Xr quotacursor_getn 3 .
************************************************************
t Fn QUOTACTL_CURSORATEND "struct quotakcursor *cursor" "int *ret" This operation generates a nonzero value if the cursor has reached the
end of the available quota information and zero otherwise.
The generated value is stored into the variable pointed to by
.Fa ret .
See
.Xr quotacursor_atend 3 .
************************************************************
t Fn QUOTACTL_CURSORREWIND "struct quotakcursor *cursor" This operation updates the cursor state so that further calls to
.Fn QUOTACTL_CURSORGET
will begin again at the start of the iteration.
See
.Xr quotacursor_rewind 3 .
************************************************************
t Fn QUOTACTL_QUOTAON "int idtype" "const char *quotafile" This operation is accepted only by old-style
q Dq quota1
quota implementations.
Quotas for the ID type named by
.Fa idtype
are switched on, and the file
.Fa quotafile
is used to hold the quota information.
This operation can also be used when quotas are already switched on
to change the file used to hold the quota information.
Note however that as the current usage information in the file must be
consistent with the current state of the file system, in general it is
not safe to call
.Fn QUOTACTL_QUOTAON
except in single-user mode.
See
.Xr quotaon 8
for more information.
Normally
quotaon 8
is run during the boot sequence after
.Xr quotacheck 8 .
Also see
.Xr quota_quotaon 3 .
************************************************************
t Fn QUOTACTL_QUOTAOFF "int idtype" This operation is accepted only by old-style
q Dq quota1
quota implementations.
Quotas for the ID type named by
.Fa idtype
are switched off.
Once quotas are switched off the file system behaves as if no quotas
are present.
Normally
quotaoff 8
is run during the shutdown sequence.
Also see
.Xr quota_quotaoff 3 .
************************************************************
.El
.Sh RETURN VALUES
On success,
.Fn __quotactl
returns 0.
Otherwise the value -1 is returned and an error code reflecting the
reason for the failure is placed in
.Va errno .
.Sh ERRORS
.Fn __quotactl
failures include:
l -tag -width Er t Bq Er EFAULT A pointer points outside the process's allocated address space.
t Bq Er EINVAL The operation code was out of range; or
a requested ID or object type was out of range; or
a corrupted or invalid cursor was passed in.
t Bq Er ENODEV The requested action was inappropriate for
q or not supported by the selected volume. t Bq Er ENOENT No quota information exists for the requested key. t Bq Er ENOMEM Memory could not be allocated within the kernel. t Bq Er ENXIO The target file system type is capable of supporting quotas, but quotas are not enabled on the selected volume. t Bq Er EOPNOTSUPP The target file system does not support quotas. .El .Sh SEE ALSO .Xr quota 1 , .Xr libquota 3 , .Xr fstab 5 , .Xr edquota 8 , .Xr quotacheck 8 , .Xr quotaon 8 , .Xr quotarestore 8 , .Xr repquota 8 .Sh HISTORY The original .Fn quotactl function call appeared in x 4.3 Reno . The current .Fn __quotactl interface appeared in .Nx 6.0 . .Sh BUGS As of this writing the error returns that occur in practice are not always completely consistent with the intent documented above.
p There should be some way to integrate this call with the resource limit interface provided by .Xr setrlimit 2 and .Xr getrlimit 2 .
Indexes created Sun Sep 21 15:09:59 GMT 2025