Module Name: src
Committed By: dholland
Date: Wed Jan 25 21:11:45 UTC 2012
Added Files:
src/lib/libquota: libquota.3
Log Message:
duh, forgot to cvs add
To generate a diff of this commit:
cvs rdiff -u -r0 -r1.1 src/lib/libquota/libquota.3
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Added files:
Index: src/lib/libquota/libquota.3
diff -u /dev/null src/lib/libquota/libquota.3:1.1
--- /dev/null Wed Jan 25 21:11:45 2012
+++ src/lib/libquota/libquota.3 Wed Jan 25 21:11:45 2012
@@ -0,0 +1,405 @@
+.\" $NetBSD: libquota.3,v 1.1 2012/01/25 21:11:45 dholland Exp $
+.\"
+.\" Copyright (c) 2012 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by David A. Holland.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.Dd January 24, 2012
+.Dt LIBQUOTA 3
+.Os
+.Sh NAME
+.Nm libquota ,
+.Nm quota_open ,
+.Nm quota_close ,
+.Nm quota_getmountdevice ,
+.Nm quota_getmountpoint ,
+.Nm quota_getimplname ,
+.Nm quota_getnumidtypes ,
+.Nm quota_getnumobjtypes ,
+.Nm quota_idtype_getname ,
+.Nm quota_objtype_getname ,
+.Nm quota_objtype_isbytes ,
+.Nm quota_get ,
+.Nm quota_put ,
+.Nm quota_delete ,
+.Nm quota_opencursor ,
+.Nm quotacursor_close ,
+.Nm quotacursor_skipidtype ,
+.Nm quotacursor_get ,
+.Nm quotacursor_getn ,
+.Nm quotacursor_atend ,
+.Nm quotacursor_rewind ,
+.Nm quotaval_clear
+.Nd disk quota access and control library
+.Sh LIBRARY
+.Lb libquota
+.Sh SYNOPSIS
+.In quota.h
+.Ft struct quotahandle *
+.Fn quota_open "const char *path"
+.Ft void
+.Fn quota_close "struct quotahandle *qh"
+.Ft const char *
+.Fn quota_getmountdevice "struct quotahandle *qh"
+.Ft const char *
+.Fn quota_getmountpoint "struct quotahandle *qh"
+.Ft const char *
+.Fn quota_getimplname "struct quotahandle *qh"
+.Ft unsigned
+.Fn quota_getnumidtypes "struct quotahandle *qh"
+.Ft unsigned
+.Fn quota_getnumobjtypes "struct quotahandle *qh"
+.Ft const char *
+.Fn quota_idtype_getname "struct quotahandle *qh" "int idtype"
+.Ft const char *
+.Fn quota_objtype_getname "struct quotahandle *qh" "int objtype"
+.Ft int
+.Fn quota_objtype_isbytes "struct quotahandle *qh" "int objtype"
+.Ft int
+.Fn quota_get "struct quotahandle *qh" "const struct quotakey *key" "struct quotaval *val"
+.Ft int
+.Fn quota_put "struct quotahandle *qh" "const struct quotakey *key" "const struct quotaval *val"
+.Ft int
+.Fn quota_delete "struct quotahandle *qh" "const struct quotakey *key"
+.Ft struct quotacursor *
+.Fn quota_opencursor "struct quotahandle *qh"
+.Ft void
+.Fn quotacursor_close "struct quotacursor *qc"
+.Ft int
+.Fn quotacursor_skipidtype "struct quotacursor *qc" "int idtype"
+.Ft int
+.Fn quotacursor_get "struct quotacursor *qc" "struct quotakey *key" "const struct quotaval *val"
+.Ft int
+.Fn quotacursor_getn "struct quotacursor *qc" "struct quotakey *keys" "const struct quotaval *vals" "unsigned maxnum"
+.Ft int
+.Fn quotacursor_atend "struct quotacursor *qc"
+.Ft int
+.Fn quotacursor_rewind "struct quotacursor *qc"
+.Ft void
+.Fn quotaval_clear "struct quotaval *qv"
+.Sh DESCRIPTION
+The
+.Nm
+library provides uniform access to disk quota functionality across all
+file systems and file system types.
+Programs should be linked with
+.Fl lquota lrpcsvc .
+.Pp
+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
+.Em soft limit ,
+.Em hard limit ,
+and
+.Em 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.
+.Pp
+Each mounted file system that supports quotas contains its own
+key/value store for quota information.
+.Pq 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.
+.Pp
+All functionality is accessed by first calling
+.Fn 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
+.Fn quota_close
+function should be called when done to release internal resources.
+.Ss Data Structures
+The key part of the key/value schema is defined as
+.Dv struct quotakey ,
+which contains the following members:
+.Bl -tag -width 4n
+.It int qk_idtype
+The type of principal (user, group, etc.) to retrieve quota
+information for.
+.It id_t qk_id
+The ID number (uid, gid, etc.) to retrieve quota information for.
+.It int qk_objtype
+The type of file system resource (blocks, files, etc.) to retrieve
+quota information for.
+.El
+The value part of the key/value schema is defined as
+.Dv struct quotaval ,
+which contains the following members:
+.Bl -tag -width 4n
+.It uint64_t qv_softlimit
+The soft limit.
+.It uint64_t qv_hardlimit
+The hard limit.
+.It uint64_t qv_usage
+The current usage.
+.It int64_t qv_expiretime
+The time
+.Pq in time_t terms
+at which the current grace period, if any, expires.
+.It int64_t qv_grace
+The configured length of grace period.
+.El
+.Ss Constants
+The basic ID and object types are predefined.
+.Dv QUOTA_IDTYPE_USER
+is the code number for quotas on users;
+.Dv QUOTA_IDTYPE_GROUP
+is the code number for quotas on groups.
+Similarly,
+.Dv QUOTA_OBJTYPE_BLOCKS
+retrieves limits on file system blocks, while
+.Dv QUOTA_OBJTYPE_FILES
+retrieves limits on the number of existing files.
+.Pp
+Some backends support a default configuration; this can be accessed by
+using
+.Dv QUOTA_DEFAULTID
+as the ID number.
+.Pp
+When no limit is in place, the value
+.Dv QUOTA_NOLIMIT
+appears in the limit fields of struct quotaval, and if no time is
+indicated the value
+.Dv QUOTA_NOTIME
+appears in the time fields.
+.Ss Quota v1
+The historic BSD quota implementation for FFS, known as
+.Dq quota v1 ,
+has additional restrictions and requirements.
+All file systems to be mounted with v1 quotas
+.Em must
+be listed in
+.Xr fstab 5
+with the
+.Dv userquota
+and/or
+.Dv groupquota
+mount options specified.
+The tools
+.Xr quotacheck 8
+and
+.Xr quotaon 8
+must be used on quota v1 volumes before quotas become fully
+operational, and
+.Xr quotaoff 8
+must be used at system shutdown time.
+The
+.Nm
+library provides access to quota v1 data even before
+.Xr quotaon 8
+is called by direct access to the on-disk quota information.
+However, this method is not recommended.
+.Ss Function Descriptions
+.Bl -tag -width 4n
+.It Fn quota_open
+Open a volume for access with the quota library.
+The
+.Fa 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
+.Dv errno .
+.It Fn quota_close
+Close a quota handle previously created with
+.Fn quota_open .
+.It Fn quota_getmountdevice
+Return the path of the device the target volume is mounted from.
+This is retrieved with
+.Xr statvfs 3 .
+.It Fn quota_getmountpoint
+Return the path in the directory tree where the target volume is
+mounted.
+This is retrieved with
+.Xr statvfs 3 .
+.It Fn quota_getimplname
+Return a human-readable string describing the underlying quota
+implementation.
+Client programs should not attempt to interpret this string.
+.It Fn 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.
+.It Fn 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
+.Pq though not in Nx
+that support quotas for more than two object types.
+.It Fn quota_idtype_getname
+Return a printable name for an ID type.
+.It Fn quota_objtype_getname
+Return a printable name for an object type.
+.It Fn quota_objtype_isbytes
+Return true if the object type refers to something measured in bytes.
+.Pq This can be used for calling Xr humanize_number 3 .
+.It Fn quota_get
+Return, in
+.Fa val ,
+the quota information associated with the quota key
+.Fa key .
+On failure, returns -1 and sets
+.Dv errno .
+.It Fn quota_put
+Update the quota information associated with the quota key
+.Fa key
+from the value
+.Fa val .
+Note that the current usage
+.Pq which is maintained by the file system
+cannot be updated via
+.Nm .
+If it becomes incorrect or corrupted,
+.Xr quotacheck 8
+or
+.Xr fsck 8
+must be used.
+Also note that sufficient privilege is required.
+On failure, returns -1 and sets
+.Dv errno .
+.It Fn quota_delete
+Remove the quota information associated with the quota key
+.Fa 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
+.Dv errno .
+.It Fn 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
+.Dv errno .
+.It Fn quotacursor_close
+Destroy a cursor previously created with
+.Fn quota_opencursor .
+This releases internal storage.
+.It Fn quotacursor_skipidtype
+Hint to the implementation that the caller is not interested in
+retriving records with ID type
+.Fa 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
+.Dv errno .
+.It Fn quotacursor_get
+Retrieve the next record
+.Pq 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
+.Dv errno .
+.It Fn quotacursor_getn
+Retrieve the next several keys and values from a cursor.
+Up to
+.Fa maxnum
+keys and values will be stored in the arrays pointed to by the
+.Fa keys
+and
+.Fa vals
+arguments.
+Returns the number of records retrieved.
+On failure, returns -1 and sets
+.Dv errno .
+.It Fn quotacursor_atend
+Returns true if the cursor has reached the end of the quota store.
+.It Fn quotacursor_rewind
+Resets a cursor to point to the beginning of the quota store, allowing
+another pass over the data.
+.It Fn quotaval_clear
+A convenience function for initializing a struct quotaval instance
+to the default empty state.
+.El
+.\" .Sh EXAMPLES
+.\" XXX would be nice to have an example, particularly of iteration.
+.Sh ERRORS
+.\" XXX this is woefully incomplete, particularly about errors that
+.\" can be generated inside file systems.
+Error conditions include:
+.Bl -tag -width Er
+.It Bq Er EOPNOTSUPP
+The
+.Fa path
+passed to
+.Fn quota_open
+was on a volume that has no quota support.
+.It Bq Er ENXIO
+The
+.Fa path
+passed to
+.Fn quota_open
+was on a volume whose quota support is not enabled.
+.It Bq Er EOPNOTSUPP
+The iterator functions,
+.Fn 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.
+.It Bq Er ENOENT
+The quota information requested from
+.Fn quota_get
+does not exist.
+.It Bq Er EDEADLK
+An inconsistency was detected during
+.Fn quotacursor_get
+or
+.Fn quotacursor_getn .
+The application should discard information collected so far and use
+.Fn quotacursor_rewind
+to start the iteration over.
+.\" .It Bq Er EBUSY
+.\" .Fn quota_quotaon
+.\" was attempted on a volume that is not a quota v1 volume.
+.El
+.Sh SEE ALSO
+.Xr quota 1 ,
+.Xr edquota 8 ,
+.Xr mount_ffs 8 ,
+.Xr mount_nfs 8 ,
+.Xr quotacheck 8 ,
+.Xr quotaon 8 ,
+.Xr repquota 8 ,
+.Xr rpc.rquotad 8
+.Sh HISTORY
+The
+.Nm
+library first appeared in
+.Nx 6.0 .
+.Sh AUTHORS
+The
+.Nm
+library was written by David A. Holland.
