[src/trunk]: src/lib/libquota duh, forgot to cvs add

[dholland <dholland%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/9985a91065f6
branches:  trunk
changeset: 773055:9985a91065f6
user:      dholland <dholland%NetBSD.org@localhost>
date:      Wed Jan 25 21:11:45 2012 +0000

description:
duh, forgot to cvs add

diffstat:

 lib/libquota/libquota.3 |  405 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 405 insertions(+), 0 deletions(-)

diffs (truncated from 409 to 300 lines):

diff -r 55dd59c7bc17 -r 9985a91065f6 lib/libquota/libquota.3
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/lib/libquota/libquota.3   Wed Jan 25 21:11:45 2012 +0000
@@ -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.