NAME
libquota,
quota_open,
quota_close,
quota_getmountdevice,
quota_getmountpoint,
quota_getimplname,
quota_getrestrictions,
quota_getnumidtypes,
quota_getnumobjtypes,
quota_idtype_getname,
quota_objtype_getname,
quota_objtype_isbytes,
quota_get,
quota_put,
quota_delete,
quota_opencursor,
quotacursor_close,
quotacursor_skipidtype,
quotacursor_get,
quotacursor_getn,
quotacursor_atend,
quotacursor_rewind,
quota_quotaon,
quota_quotaoff,
quotaval_clear —
disk quota access and control library
LIBRARY
Disk Quota Access and Control Library (libquota,
-lquota)
SYNOPSIS
#include <quota.h>
struct quotahandle *
quota_open(
const
char *path);
void
quota_close(
struct
quotahandle *qh);
const char *
quota_getmountdevice(
struct
quotahandle *qh);
const char *
quota_getmountpoint(
struct
quotahandle *qh);
const char *
quota_getimplname(
struct
quotahandle *qh);
unsigned
quota_getrestrictions(
struct
quotahandle *qh);
int
quota_getnumidtypes(
struct
quotahandle *qh);
int
quota_getnumobjtypes(
struct
quotahandle *qh);
const char *
quota_idtype_getname(
struct
quotahandle *qh,
int
idtype);
const char *
quota_objtype_getname(
struct
quotahandle *qh,
int
objtype);
int
quota_objtype_isbytes(
struct
quotahandle *qh,
int
objtype);
int
quota_get(
struct
quotahandle *qh,
const
struct quotakey *key,
struct quotaval *val);
int
quota_put(
struct
quotahandle *qh,
const
struct quotakey *key,
const
struct quotaval *val);
int
quota_delete(
struct
quotahandle *qh,
const
struct quotakey *key);
struct quotacursor *
quota_opencursor(
struct
quotahandle *qh);
void
quotacursor_close(
struct
quotacursor *qc);
int
quotacursor_skipidtype(
struct
quotacursor *qc,
int
idtype);
int
quotacursor_get(
struct
quotacursor *qc,
struct
quotakey *key,
const struct
quotaval *val);
int
quotacursor_getn(
struct
quotacursor *qc,
struct
quotakey *keys,
const
struct quotaval *vals,
unsigned maxnum);
int
quotacursor_atend(
struct
quotacursor *qc);
int
quotacursor_rewind(
struct
quotacursor *qc);
int
quota_quotaon(
struct
quotahandle *qh,
int
idtype);
int
quota_quotaoff(
struct
quotahandle *qh,
int
idtype);
void
quotaval_clear(
struct
quotaval *qv);
DESCRIPTION
The
libquota library provides uniform access to disk quota
functionality across all file systems and file system types. Programs should
be linked with
-lquota -lrpcsvc.
Quota information is organized as a key/value store, where the key names a
particular limit and the value contains information about that limit. The
information includes a configured
soft limit,
hard limit, and
grace time, as well as the
current usage and the expire time of any pending grace period. The soft limit
may be exceeded temporarily, but only for the length of time specified; after
that further usage is rejected. The hard limit may not be exceeded.
Each mounted file system that supports quotas contains its own key/value store
for quota information. (The underlying representation may vary.) The library
supports get, put, and delete operations, as well as a cursor interface for
iterating an entire store. It also provides functions for inspecting the
properties of a particular file system's quota implementation.
All functionality is accessed by first calling
quota_open() on
a particular volume to get a handle for that volume's quota information. Other
operations can be called at this point. The
quota_close()
function should be called when done to release internal resources.
Data Structures
The key part of the key/value schema is defined as
struct
quotakey
, which contains the following members:
-
-
- int qk_idtype
- The type of principal (user, group, etc.) to retrieve quota
information for.
-
-
- id_t qk_id
- The ID number (uid, gid, etc.) to retrieve quota
information for.
-
-
- int qk_objtype
- The type of file system resource (blocks, files, etc.) to
retrieve quota information for.
The value part of the key/value schema is defined as
struct
quotaval
, which contains the following members:
-
-
- uint64_t qv_softlimit
- The soft limit.
-
-
- uint64_t qv_hardlimit
- The hard limit.
-
-
- uint64_t qv_usage
- The current usage.
-
-
- int64_t qv_expiretime
- The time (in time_t terms) at which the current grace
period, if any, expires.
-
-
- int64_t qv_grace
- The configured length of grace period.
Constants
The basic ID and object types are predefined.
QUOTA_IDTYPE_USER
is the code number for quotas on
users;
QUOTA_IDTYPE_GROUP
is the code number for
quotas on groups. Similarly,
QUOTA_OBJTYPE_BLOCKS
retrieves limits on file system blocks, while
QUOTA_OBJTYPE_FILES
retrieves limits on the number of
existing files.
Some backends support a default configuration; this can be accessed by using
QUOTA_DEFAULTID
as the ID number.
When no limit is in place, the value
QUOTA_NOLIMIT
appears in the limit fields of struct quotaval, and if no time is indicated
the value
QUOTA_NOTIME
appears in the time fields.
Quota v1
The historic BSD quota implementation for FFS, known as “quota v1”,
has additional restrictions and requirements. All file systems to be mounted
with v1 quotas
must be listed in
fstab(5) with the
userquota
and/or
groupquota
mount options specified. The tools
quotacheck(8) and
quotaon(8) must be used on
quota v1 volumes before quotas become fully operational, and
quotaoff(8) must be used at
system shutdown time. The
libquota library provides access
to quota v1 data even before
quotaon(8) is called by direct
access to the on-disk quota information. However, this method is not
recommended. Note that the
userquota
and
groupquota
mount options are read and interpreted at
quotaon time, not
mount(8) time.
This allowed historic implementations to avoid storing the path in the kernel.
Semantic Restrictions
Some quota implementations are restricted in their functionality or semantics.
The following restriction codes are defined to allow
libquota client code to adapt or to provide more helpful
diagnostic messages.
-
-
- QUOTA_RESTRICT_NEEDSQUOTACHECK
- The quota implementation is a quota v1 system and requires
the old-style quota check and mount process as described in the previous
section.
-
-
- QUOTA_RESTRICT_UNIFORMGRACE
- The grace period for how long a quota can be over the soft
limit can be specified only once, globally, for all principals. It is set
via the default (
QUOTA_DEFAULTID
) quota
entry.
-
-
- QUOTA_RESTRICT_32BIT
- The values in struct quotaval are limited to 32 bits wide.
Larger values will be treated as
QUOTA_NOLIMIT
.
-
-
- QUOTA_RESTRICT_READONLY
- The quota information is read-only. Attempts to update it
using quota_put() or other functions will fail.
Function Descriptions
-
-
- quota_open()
- Open a volume for access with the quota library. The
path may be any file or file system object on the
desired volume. On success, returns a quota handle for further use. On
failure, returns
NULL
and sets
errno
.
-
-
- quota_close()
- Close a quota handle previously created with
quota_open().
-
-
- quota_getmountdevice()
- Return the path of the device the target volume is mounted
from. This is retrieved with
statvfs(2).
-
-
- quota_getmountpoint()
- Return the path in the directory tree where the target
volume is mounted. This is retrieved with
statvfs(2).
-
-
- quota_getimplname()
- Return a human-readable string describing the underlying
quota implementation. Client programs should not attempt to interpret this
string.
-
-
- quota_getrestrictions()
- Return the semantic restriction flags for the underlying
quota implementation. The possible flags are described above.
-
-
- quota_getnumidtypes()
- Return the number of ID types supported by this volume.
Will ordinarily be two; ideally code using this library should be prepared
for other values, including possibly one. However, as of this writing it
is difficult to foresee any other likely ID types beyond users and
groups.
-
-
- quota_getnumobjtypes()
- Return the number of object types supported by this volume.
Will ordinarily be two; ideally code using this library should be prepared
for larger values. As of this writing there are deployed file systems
(though not in NetBSD) that support quotas for
more than two object types.
-
-
- quota_idtype_getname()
- Return a printable name for an ID type.
-
-
- quota_objtype_getname()
- Return a printable name for an object type.
-
-
- quota_objtype_isbytes()
- Return true if the object type refers to something measured
in bytes. (This can be used for calling
humanize_number(3)).
-
-
- quota_get()
- Return, in val, the quota information
associated with the quota key key. On failure,
returns -1 and sets
errno
.
-
-
- quota_put()
- Update the quota information associated with the quota key
key from the value val. Note
that the current usage (which is maintained by the file system) cannot be
updated via libquota. If it becomes incorrect or
corrupted, quotacheck(8)
or fsck(8) must be used. Also
note that sufficient privilege is required. On failure, returns -1 and
sets
errno
.
-
-
- quota_delete()
- Remove the quota information associated with the quota key
key. Depending on the backend implementation this
might just blank it out or might physically remove the quota record from
disk. Note that sufficient privilege is required. On failure, returns -1
and sets
errno
.
-
-
- quota_opencursor()
- Prepare to iterate the store by creating a cursor. The
cursor starts at the beginning of the store. On success, returns a pointer
to a cursor object that can be used with the quotacursor calls. On
failure, returns
NULL
and sets
errno
.
-
-
- quotacursor_close()
- Destroy a cursor previously created with
quota_opencursor(). This releases internal storage.
-
-
- quotacursor_skipidtype()
- Hint to the implementation that the caller is not
interested in retrieving records with ID type
idtype. As this is a hint, the implementation may
ignore it; the caller should still be prepared to receive and ignore such
records. On failure, returns -1 and sets
errno
.
-
-
- quotacursor_get()
- Retrieve the next record (key and value) from a cursor.
Note that records are not guaranteed to be returned in any particular
order. On failure, returns -1 and sets
errno
.
-
-
- quotacursor_getn()
- Retrieve the next several keys and values from a cursor. Up
to maxnum keys and values will be stored in the
arrays pointed to by the keys and
vals arguments. Returns the number of records
retrieved. On failure, returns -1 and sets
errno
.
-
-
- quotacursor_atend()
- Returns true if the cursor has reached the end of the quota
store.
-
-
- quotacursor_rewind()
- Resets a cursor to point to the beginning of the quota
store, allowing another pass over the data.
-
-
- quota_quotaon()
- For old-style quota v1 implementations, this function
enables quotas for the specified ID type. To ensure that the quota files
are consistent with the file system state,
quotacheck(8) must have
been run beforehand. As described above, the file system volume must be
listed in fstab(5) and the
corresponding old-style mount option,
userquota
or
groupquota
, must be set therein. The path name for
the quota file is retrieved from
fstab(5) and passed to the
kernel. This function will fail if used on newer quota implementations
with in-file-system quotas.
-
-
- quota_quotaoff()
- For old-style quotas, this function disables quotas for the
specified ID type. This function will fail if used on newer quota
implementations with in-file-system quotas.
-
-
- quotaval_clear()
- A convenience function for initializing a struct quotaval
instance to the default empty state.
ERRORS
Error conditions include:
-
-
- [
EDEADLK
]
- An inconsistency was detected during
quotacursor_get() or
quotacursor_getn(). The application should discard
information collected so far and use
quotacursor_rewind() to start the iteration over.
-
-
- [
ENOENT
]
- The quota information requested from
quota_get() does not exist.
-
-
- [
ENXIO
]
- The path passed to
quota_open() was on a volume whose quota support is not
enabled.
-
-
- [
EOPNOTSUPP
]
- The path passed to
quota_open() was on a volume that has no quota support.
Or, the iterator functions, quota_put(), or other
unsupported operations were attempted on an NFS volume, or on some other
volume type that does not support the full semantic range of quota
information.
SEE ALSO
quota(1),
edquota(8),
mount_ffs(8),
mount_nfs(8),
quotacheck(8),
quotaon(8),
repquota(8),
rpc.rquotad(8)
HISTORY
The
libquota library first appeared in
NetBSD
6.0.
AUTHORS
The
libquota library was written by
David A.
Holland.