Unix/Linux Go Back    


NetBSD 6.1.5 - man page for libquota (netbsd section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


LIBQUOTA(3)			   BSD 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
     library ``libquota''

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 imple-
     mentation.

     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 fol-
     lowing 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 quo-
     tas 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 ker-
     nel.

   Semantic Restrictions
     Some quota implementations are restricted in their functionality or semantics.  The follow-
     ing 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; ide-
	   ally 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 vol-
	   ume 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 sup-
			port.  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.

BSD					February 13, 2012				      BSD
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 09:55 PM.