Annotation of src/lib/libquota/libquota.3, Revision 1.5
1.5 ! wiz 1: .\" $NetBSD: libquota.3,v 1.4 2012/02/13 01:24:03 dholland Exp $
1.1 dholland 2: .\"
3: .\" Copyright (c) 2012 The NetBSD Foundation, Inc.
4: .\" All rights reserved.
5: .\"
6: .\" This code is derived from software contributed to The NetBSD Foundation
7: .\" by David A. Holland.
8: .\"
9: .\" Redistribution and use in source and binary forms, with or without
10: .\" modification, are permitted provided that the following conditions
11: .\" are met:
12: .\" 1. Redistributions of source code must retain the above copyright
13: .\" notice, this list of conditions and the following disclaimer.
14: .\" 2. Redistributions in binary form must reproduce the above copyright
15: .\" notice, this list of conditions and the following disclaimer in the
16: .\" documentation and/or other materials provided with the distribution.
17: .\"
18: .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19: .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20: .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21: .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22: .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23: .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24: .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25: .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26: .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27: .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28: .\" POSSIBILITY OF SUCH DAMAGE.
1.5 ! wiz 29: .Dd February 13, 2012
1.1 dholland 30: .Dt LIBQUOTA 3
31: .Os
32: .Sh NAME
33: .Nm libquota ,
34: .Nm quota_open ,
35: .Nm quota_close ,
36: .Nm quota_getmountdevice ,
37: .Nm quota_getmountpoint ,
38: .Nm quota_getimplname ,
1.4 dholland 39: .Nm quota_getrestrictions ,
1.1 dholland 40: .Nm quota_getnumidtypes ,
41: .Nm quota_getnumobjtypes ,
42: .Nm quota_idtype_getname ,
43: .Nm quota_objtype_getname ,
44: .Nm quota_objtype_isbytes ,
45: .Nm quota_get ,
46: .Nm quota_put ,
47: .Nm quota_delete ,
48: .Nm quota_opencursor ,
49: .Nm quotacursor_close ,
50: .Nm quotacursor_skipidtype ,
51: .Nm quotacursor_get ,
52: .Nm quotacursor_getn ,
53: .Nm quotacursor_atend ,
54: .Nm quotacursor_rewind ,
1.4 dholland 55: .Nm quota_quotaon ,
56: .Nm quota_quotaoff ,
1.1 dholland 57: .Nm quotaval_clear
58: .Nd disk quota access and control library
59: .Sh LIBRARY
60: .Lb libquota
61: .Sh SYNOPSIS
62: .In quota.h
63: .Ft struct quotahandle *
64: .Fn quota_open "const char *path"
65: .Ft void
66: .Fn quota_close "struct quotahandle *qh"
67: .Ft const char *
68: .Fn quota_getmountdevice "struct quotahandle *qh"
69: .Ft const char *
70: .Fn quota_getmountpoint "struct quotahandle *qh"
71: .Ft const char *
72: .Fn quota_getimplname "struct quotahandle *qh"
1.4 dholland 73: .Ft unsigned
74: .Fn quota_getrestrictions "struct quotahandle *qh"
1.3 dholland 75: .Ft int
1.1 dholland 76: .Fn quota_getnumidtypes "struct quotahandle *qh"
1.3 dholland 77: .Ft int
1.1 dholland 78: .Fn quota_getnumobjtypes "struct quotahandle *qh"
79: .Ft const char *
80: .Fn quota_idtype_getname "struct quotahandle *qh" "int idtype"
81: .Ft const char *
82: .Fn quota_objtype_getname "struct quotahandle *qh" "int objtype"
83: .Ft int
84: .Fn quota_objtype_isbytes "struct quotahandle *qh" "int objtype"
85: .Ft int
86: .Fn quota_get "struct quotahandle *qh" "const struct quotakey *key" "struct quotaval *val"
87: .Ft int
88: .Fn quota_put "struct quotahandle *qh" "const struct quotakey *key" "const struct quotaval *val"
89: .Ft int
90: .Fn quota_delete "struct quotahandle *qh" "const struct quotakey *key"
91: .Ft struct quotacursor *
92: .Fn quota_opencursor "struct quotahandle *qh"
93: .Ft void
94: .Fn quotacursor_close "struct quotacursor *qc"
95: .Ft int
96: .Fn quotacursor_skipidtype "struct quotacursor *qc" "int idtype"
97: .Ft int
98: .Fn quotacursor_get "struct quotacursor *qc" "struct quotakey *key" "const struct quotaval *val"
99: .Ft int
100: .Fn quotacursor_getn "struct quotacursor *qc" "struct quotakey *keys" "const struct quotaval *vals" "unsigned maxnum"
101: .Ft int
102: .Fn quotacursor_atend "struct quotacursor *qc"
103: .Ft int
104: .Fn quotacursor_rewind "struct quotacursor *qc"
1.4 dholland 105: .Ft int
106: .Fn quota_quotaon "struct quotahandle *qh" "int idtype"
107: .Ft int
108: .Fn quota_quotaoff "struct quotahandle *qh" "int idtype"
1.1 dholland 109: .Ft void
110: .Fn quotaval_clear "struct quotaval *qv"
111: .Sh DESCRIPTION
112: The
113: .Nm
114: library provides uniform access to disk quota functionality across all
115: file systems and file system types.
116: Programs should be linked with
117: .Fl lquota lrpcsvc .
118: .Pp
119: Quota information is organized as a key/value store, where the key
120: names a particular limit and the value contains information about that
121: limit.
122: The information includes a configured
123: .Em soft limit ,
124: .Em hard limit ,
125: and
126: .Em grace time ,
127: as well as the current usage and the expire time of any pending grace
128: period.
129: The soft limit may be exceeded temporarily, but only for the length of
130: time specified; after that further usage is rejected.
131: The hard limit may not be exceeded.
132: .Pp
133: Each mounted file system that supports quotas contains its own
134: key/value store for quota information.
135: .Pq The underlying representation may vary.
136: The library supports get, put, and delete operations, as well as a
137: cursor interface for iterating an entire store.
138: It also provides functions for inspecting the properties of a
139: particular file system's quota implementation.
140: .Pp
141: All functionality is accessed by first calling
142: .Fn quota_open
143: on a particular volume to get a handle for that volume's quota
144: information.
145: Other operations can be called at this point.
146: The
147: .Fn quota_close
148: function should be called when done to release internal resources.
149: .Ss Data Structures
150: The key part of the key/value schema is defined as
151: .Dv struct quotakey ,
152: which contains the following members:
153: .Bl -tag -width 4n
154: .It int qk_idtype
155: The type of principal (user, group, etc.) to retrieve quota
156: information for.
157: .It id_t qk_id
158: The ID number (uid, gid, etc.) to retrieve quota information for.
159: .It int qk_objtype
160: The type of file system resource (blocks, files, etc.) to retrieve
161: quota information for.
162: .El
163: The value part of the key/value schema is defined as
164: .Dv struct quotaval ,
165: which contains the following members:
166: .Bl -tag -width 4n
167: .It uint64_t qv_softlimit
168: The soft limit.
169: .It uint64_t qv_hardlimit
170: The hard limit.
171: .It uint64_t qv_usage
172: The current usage.
173: .It int64_t qv_expiretime
1.2 wiz 174: The time
1.1 dholland 175: .Pq in time_t terms
176: at which the current grace period, if any, expires.
177: .It int64_t qv_grace
178: The configured length of grace period.
179: .El
180: .Ss Constants
181: The basic ID and object types are predefined.
182: .Dv QUOTA_IDTYPE_USER
183: is the code number for quotas on users;
184: .Dv QUOTA_IDTYPE_GROUP
185: is the code number for quotas on groups.
186: Similarly,
187: .Dv QUOTA_OBJTYPE_BLOCKS
188: retrieves limits on file system blocks, while
189: .Dv QUOTA_OBJTYPE_FILES
190: retrieves limits on the number of existing files.
191: .Pp
192: Some backends support a default configuration; this can be accessed by
193: using
194: .Dv QUOTA_DEFAULTID
195: as the ID number.
196: .Pp
197: When no limit is in place, the value
198: .Dv QUOTA_NOLIMIT
199: appears in the limit fields of struct quotaval, and if no time is
200: indicated the value
201: .Dv QUOTA_NOTIME
202: appears in the time fields.
203: .Ss Quota v1
204: The historic BSD quota implementation for FFS, known as
205: .Dq quota v1 ,
206: has additional restrictions and requirements.
207: All file systems to be mounted with v1 quotas
208: .Em must
209: be listed in
210: .Xr fstab 5
211: with the
212: .Dv userquota
213: and/or
214: .Dv groupquota
215: mount options specified.
216: The tools
217: .Xr quotacheck 8
218: and
219: .Xr quotaon 8
220: must be used on quota v1 volumes before quotas become fully
221: operational, and
222: .Xr quotaoff 8
223: must be used at system shutdown time.
224: The
225: .Nm
226: library provides access to quota v1 data even before
227: .Xr quotaon 8
228: is called by direct access to the on-disk quota information.
229: However, this method is not recommended.
1.4 dholland 230: Note that the
231: .Dv userquota
232: and
233: .Dv groupquota
234: mount options are read and interpreted at quotaon time, not
235: .Xr mount 8
236: time.
237: This allowed historic implementations to avoid storing the path in the
238: kernel.
239: .Ss Semantic Restrictions
240: Some quota implementations are restricted in their functionality or
241: semantics.
242: The following restriction codes are defined to allow
243: .Nm libquota
244: client code to adapt or to provide more helpful diagnostic messages.
245: .Bl -tag -width 4n
246: .It QUOTA_RESTRICT_NEEDSQUOTACHECK
247: The quota implementation is a quota v1 system and requires the
248: old-style quota check and mount process as described in the
249: previous section.
250: .It QUOTA_RESTRICT_UNIFORMGRACE
251: The grace period for how long a quota can be over the soft limit can
252: be specified only once, globally, for all principals.
253: It is set via the default
254: .Pq Dv QUOTA_DEFAULTID
255: quota entry.
256: .It QUOTA_RESTRICT_32BIT
257: The values in struct quotaval are limited to 32 bits wide.
258: Larger values will be treated as
259: .Dv QUOTA_NOLIMIT .
260: .It QUOTA_RESTRICT_READONLY
261: The quota information is read-only.
262: Attempts to update it using
263: .Fn quota_put
264: or other functions will fail.
265: .El
1.1 dholland 266: .Ss Function Descriptions
267: .Bl -tag -width 4n
268: .It Fn quota_open
269: Open a volume for access with the quota library.
270: The
271: .Fa path
272: may be any file or file system object on the desired volume.
273: On success, returns a quota handle for further use.
1.2 wiz 274: On failure, returns
275: .Dv NULL
276: and sets
1.1 dholland 277: .Dv errno .
278: .It Fn quota_close
279: Close a quota handle previously created with
280: .Fn quota_open .
281: .It Fn quota_getmountdevice
282: Return the path of the device the target volume is mounted from.
283: This is retrieved with
1.2 wiz 284: .Xr statvfs 2 .
1.1 dholland 285: .It Fn quota_getmountpoint
286: Return the path in the directory tree where the target volume is
287: mounted.
288: This is retrieved with
1.2 wiz 289: .Xr statvfs 2 .
1.1 dholland 290: .It Fn quota_getimplname
291: Return a human-readable string describing the underlying quota
292: implementation.
293: Client programs should not attempt to interpret this string.
1.4 dholland 294: .It Fn quota_getrestrictions
295: Return the semantic restriction flags for the underlying quota
296: implementation.
297: The possible flags are described above.
1.1 dholland 298: .It Fn quota_getnumidtypes
299: Return the number of ID types supported by this volume.
300: Will ordinarily be two; ideally code using this library should be
301: prepared for other values, including possibly one.
302: However, as of this writing it is difficult to foresee any other
303: likely ID types beyond users and groups.
304: .It Fn quota_getnumobjtypes
305: Return the number of object types supported by this volume.
306: Will ordinarily be two; ideally code using this library should be
307: prepared for larger values.
308: As of this writing there are deployed file systems
309: .Pq though not in Nx
310: that support quotas for more than two object types.
311: .It Fn quota_idtype_getname
312: Return a printable name for an ID type.
313: .It Fn quota_objtype_getname
314: Return a printable name for an object type.
315: .It Fn quota_objtype_isbytes
316: Return true if the object type refers to something measured in bytes.
317: .Pq This can be used for calling Xr humanize_number 3 .
318: .It Fn quota_get
319: Return, in
320: .Fa val ,
321: the quota information associated with the quota key
322: .Fa key .
1.2 wiz 323: On failure, returns \-1 and sets
1.1 dholland 324: .Dv errno .
325: .It Fn quota_put
326: Update the quota information associated with the quota key
327: .Fa key
328: from the value
329: .Fa val .
330: Note that the current usage
331: .Pq which is maintained by the file system
332: cannot be updated via
333: .Nm .
334: If it becomes incorrect or corrupted,
335: .Xr quotacheck 8
336: or
337: .Xr fsck 8
338: must be used.
339: Also note that sufficient privilege is required.
1.2 wiz 340: On failure, returns \-1 and sets
1.1 dholland 341: .Dv errno .
342: .It Fn quota_delete
343: Remove the quota information associated with the quota key
344: .Fa key .
345: Depending on the backend implementation this might just blank it out
346: or might physically remove the quota record from disk.
347: Note that sufficient privilege is required.
1.2 wiz 348: On failure, returns \-1 and sets
1.1 dholland 349: .Dv errno .
350: .It Fn quota_opencursor
351: Prepare to iterate the store by creating a cursor.
352: The cursor starts at the beginning of the store.
353: On success, returns a pointer to a cursor object that can be used with
354: the quotacursor calls.
1.2 wiz 355: On failure, returns
356: .Dv NULL
357: and sets
1.1 dholland 358: .Dv errno .
359: .It Fn quotacursor_close
360: Destroy a cursor previously created with
361: .Fn quota_opencursor .
362: This releases internal storage.
363: .It Fn quotacursor_skipidtype
364: Hint to the implementation that the caller is not interested in
1.2 wiz 365: retrieving records with ID type
1.1 dholland 366: .Fa idtype .
367: As this is a hint, the implementation may ignore it; the caller should
368: still be prepared to receive and ignore such records.
1.2 wiz 369: On failure, returns \-1 and sets
1.1 dholland 370: .Dv errno .
371: .It Fn quotacursor_get
372: Retrieve the next record
373: .Pq key and value
374: from a cursor.
375: Note that records are not guaranteed to be returned in any particular
376: order.
1.2 wiz 377: On failure, returns \-1 and sets
1.1 dholland 378: .Dv errno .
379: .It Fn quotacursor_getn
380: Retrieve the next several keys and values from a cursor.
381: Up to
382: .Fa maxnum
383: keys and values will be stored in the arrays pointed to by the
384: .Fa keys
385: and
386: .Fa vals
387: arguments.
388: Returns the number of records retrieved.
1.2 wiz 389: On failure, returns \-1 and sets
1.1 dholland 390: .Dv errno .
391: .It Fn quotacursor_atend
392: Returns true if the cursor has reached the end of the quota store.
393: .It Fn quotacursor_rewind
394: Resets a cursor to point to the beginning of the quota store, allowing
395: another pass over the data.
1.4 dholland 396: .It Fn quota_quotaon
397: For old-style quota v1 implementations, this function enables quotas
398: for the specified ID type.
399: To ensure that the quota files are consistent with the file system
400: state,
401: .Xr quotacheck 8
402: must have been run beforehand.
403: As described above, the file system volume must be listed in
404: .Xr fstab 5
405: and the corresponding old-style mount option,
406: .Dv userquota
407: or
408: .Dv groupquota ,
409: must be set therein.
410: The path name for the quota file is retrieved from
411: .Xr fstab 5
412: and passed to the kernel.
413: This function will fail if used on newer quota implementations with
414: in-file-system quotas.
415: .It Fn quota_quotaoff
416: For old-style quotas, this function disables quotas for the specified
417: ID type.
418: This function will fail if used on newer quota implementations with
419: in-file-system quotas.
1.1 dholland 420: .It Fn quotaval_clear
421: A convenience function for initializing a struct quotaval instance
422: to the default empty state.
423: .El
424: .\" .Sh EXAMPLES
425: .\" XXX would be nice to have an example, particularly of iteration.
426: .Sh ERRORS
427: .\" XXX this is woefully incomplete, particularly about errors that
428: .\" can be generated inside file systems.
429: Error conditions include:
430: .Bl -tag -width Er
1.2 wiz 431: .\" .It Bq Er EBUSY
432: .\" .Fn quota_quotaon
433: .\" was attempted on a volume that is not a quota v1 volume.
434: .It Bq Er EDEADLK
435: An inconsistency was detected during
436: .Fn quotacursor_get
437: or
438: .Fn quotacursor_getn .
439: The application should discard information collected so far and use
440: .Fn quotacursor_rewind
441: to start the iteration over.
442: .It Bq Er ENOENT
443: The quota information requested from
444: .Fn quota_get
445: does not exist.
446: .It Bq Er ENXIO
1.1 dholland 447: The
448: .Fa path
449: passed to
450: .Fn quota_open
1.2 wiz 451: was on a volume whose quota support is not enabled.
452: .It Bq Er EOPNOTSUPP
1.1 dholland 453: The
454: .Fa path
455: passed to
456: .Fn quota_open
1.2 wiz 457: was on a volume that has no quota support.
458: Or, the iterator functions,
1.1 dholland 459: .Fn quota_put ,
460: or other unsupported operations were attempted on an NFS volume,
461: or on some other volume type that does not support the full
462: semantic range of quota information.
463: .El
464: .Sh SEE ALSO
465: .Xr quota 1 ,
466: .Xr edquota 8 ,
467: .Xr mount_ffs 8 ,
468: .Xr mount_nfs 8 ,
469: .Xr quotacheck 8 ,
470: .Xr quotaon 8 ,
471: .Xr repquota 8 ,
472: .Xr rpc.rquotad 8
473: .Sh HISTORY
474: The
475: .Nm
476: library first appeared in
477: .Nx 6.0 .
478: .Sh AUTHORS
479: The
480: .Nm
1.2 wiz 481: library was written by
482: .An David A. Holland .
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to libquota.3 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / lib / libquota