LIBQUOTA(3)

LIBQUOTA(3) | Library Functions Manual | LIBQUOTA(3)

# 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.

February 13, 2012 | NetBSD 9.5