Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 implementa-
     tion.

     All functionality is accessed by first calling quota_open() on a particu-
     lar 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 infor-
	   mation 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 se-
     mantics.  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 im-
	   plementation.  Client programs should not attempt to	interpret this
	   string.

     quota_getrestrictions()
	   Return the semantic restriction flags for the underlying quota im-
	   plementation.  The possible flags are described above.

     quota_getnumidtypes()
	   Return the number of	ID types supported by this volume.  Will ordi-
	   narily 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	pre-
	   pared 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 in-
	   correct 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 re-
	   trieving records with ID type idtype.  As this is a hint, the im-
	   plementation	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 re-
	   trieved.  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, al-
	   lowing another pass over the	data.

     quota_quotaon()
	   For old-style quota v1 implementations, this	function enables quo-
	   tas 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 speci-
	   fied	ID type.  This function	will fail if used on newer quota im-
	   plementations 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 at-
			tempted	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

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | ERRORS | SEE ALSO | HISTORY | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=libquota&sektion=3&manpath=NetBSD+6.0>

home | help