NAME
__quotactl —
manipulate file system
quotas
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <sys/quota.h>
#include <sys/quotactl.h>
int
__quotactl(
const
char *path,
struct
quotactl_args *args);
DESCRIPTION
The
__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
libquota(3) interface.
The
__quotactl() function performs one of several
quota-related operations on the file system named by
path. The operation and arguments to that operation are
passed in the
args argument. The operation is stored in
the
qc_op member of
args. The
arguments are placed in a union such that the first and second arguments of
the operation
QUOTACTL_EXAMPLE
are found as the
members
u.example.qc_arg1 and
u.example.qc_arg2. The descriptions below will refer to
the operations as functions of the form
QUOTACTL_EXAMPLE(
int arg1,
int arg2) and elide the encoding of these arguments into
the
args structure. Explicit mention of the
path argument is also omitted.
There are fourteen quota control operations. These are:
-
-
- QUOTACTL_STAT(struct
quotastat *info)
- Information about the quota implementation on the selected
volume is returned in info. The
quotastat
structure contains the following
members:
-
-
- qs_implname
- A human-readable string describing the underlying
implementation of quotas. This is suitable for display to users (and
system administrators) but should not be interpreted by software. See
quota_getimplname(3).
-
-
- qs_numidtypes
- The number of ID types supported by this
implementation. See
quota_getnumidtypes(3).
-
-
- qs_numobjtypes
- The number of object types supported by this
implementation. See
quota_getnumobjtypes(3).
-
-
- qs_restrictions
- Flags identifying specific semantic limitations of the
implementation. See
quota_getrestrictions(3).
-
-
- QUOTACTL_IDTYPESTAT(int
idtype, struct quotaidtypestat *info)
- Information about a particular ID type on the selected
volume is returned in info. The
quotaidtypestat
structure contains the following
members:
-
-
- qis_name
- The name of the ID type. See
quota_idtype_getname(3).
-
-
- QUOTACTL_OBJYPESTAT(int
objtype, struct quotaobjtypestat *info)
- Information about a particular object type on the selected
volume is returned in info. The
quotaobjtypestat
structure contains the following
members:
-
-
- qos_name
- The name of the object type. See
quota_objtype_getname(3).
-
-
- qos_isbytes
- A flag that is nonzero if the object type is something
measured in bytes. See
quota_objtype_isbytes(3).
-
-
- QUOTACTL_GET(const
struct quotakey *key, struct quotaval *val)
- Return in val the quota information
selected by key. See
quota_get(3).
-
-
- QUOTACTL_PUT(const
struct quotakey *key, const struct quotaval
*val)
- The quota information selected by key
is updated to the values provided in 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 fsck(8) or
quotacheck(8) with
file-system-specific knowledge must be used to repair the on-disk
information. See
quota_put(3).
-
-
- QUOTACTL_DELETE(const
struct quotakey *key)
- The quota information selected by key
is removed. See
quota_delete(3).
-
-
- QUOTACTL_CURSOROPEN(struct
quotakcursor *cursor)
- A cursor for iterating the quota information is created.
The
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
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 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 libquota(3)
interface wraps the system call level quota cursors in a friendlier
interface. See
quota_opencursor(3).
-
-
- QUOTACTL_CURSORCLOSE(struct
quotakcursor *cursor)
- The cursor passed in is closed. See
quotacursor_close(3).
-
-
- 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
quotacursor_skipidtype(3).
-
-
- 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 maxnum quota records
are retrieved and stored into the arrays named by
keys and vals. The number of
records retrieved is stored into the variable pointed to by
ret. See
quotacursor_get(3)
and
quotacursor_getn(3).
-
-
- 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
ret. See
quotacursor_atend(3).
-
-
- QUOTACTL_CURSORREWIND(struct
quotakcursor *cursor)
- This operation updates the cursor state so that further
calls to QUOTACTL_CURSORGET() will begin again at the
start of the iteration. See
quotacursor_rewind(3).
-
-
- QUOTACTL_QUOTAON(int
idtype, const char *quotafile)
- This operation is accepted only by old-style
(“quota1”) quota implementations. Quotas for the ID type named
by idtype are switched on, and the file
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
QUOTACTL_QUOTAON() except in single-user mode. See
quotaon(8) for more
information. Normally quotaon 8 is run during the boot sequence after
quotacheck 8 . Also see
quota_quotaon(3).
-
-
- QUOTACTL_QUOTAOFF(int
idtype)
- This operation is accepted only by old-style
(“quota1”) quota implementations. Quotas for the ID type named
by 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
quota_quotaoff(3).
RETURN VALUES
On success,
__quotactl() returns 0. Otherwise the value -1 is
returned and an error code reflecting the reason for the failure is placed in
errno.
ERRORS
__quotactl() failures include:
-
-
- [
EFAULT
]
- A pointer points outside the process's allocated address
space.
-
-
- [
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.
-
-
- [
ENODEV
]
- The requested action was inappropriate for (or not
supported by) the selected volume.
-
-
- [
ENOENT
]
- No quota information exists for the requested key.
-
-
- [
ENOMEM
]
- Memory could not be allocated within the kernel.
-
-
- [
ENXIO
]
- The target file system type is capable of supporting
quotas, but quotas are not enabled on the selected volume.
-
-
- [
EOPNOTSUPP
]
- The target file system does not support quotas.
SEE ALSO
quota(1),
libquota(3),
fstab(5),
edquota(8),
quotacheck(8),
quotaon(8),
quotarestore(8),
repquota(8)
HISTORY
The original
quotactl() function call appeared in
4.3BSD-Reno. The current
__quotactl() interface appeared in
NetBSD
6.0.
BUGS
As of this writing the error returns that occur in practice are not always
completely consistent with the intent documented above.
There should be some way to integrate this call with the resource limit
interface provided by
setrlimit(2) and
getrlimit(2).