Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.


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.

NetBSD 10.99                   February 13, 2012                  NetBSD 10.99