2 .\" Copyright (c) 2009 Dag-Erling Coïdan Smørgrav and
3 .\" Marshall Kirk McKusick. All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
37 .Nm quota_write_limits
44 .Nd "Manipulate quotas"
54 .Ft "struct quotafile *"
55 .Fn quota_open "struct fstab *fs" "int quotatype" "int openflags"
57 .Fn quota_close "struct quotafile *qf"
59 .Fn quota_on "const struct quotafile *qf"
61 .Fn quota_off "const struct quotafile *qf"
63 .Fn quota_read "struct quotafile *qf" "struct dqblk *dqb" "int id"
65 .Fn quota_write_limits "struct quotafile *qf" "struct dqblk *dqb" "int id"
67 .Fn quota_write_usage "struct quotafile *qf" "struct dqblk *dqb" "int id"
69 .Fn quota_fsname "const struct quotafile *qf"
71 .Fn quota_qfname "const struct quotafile *qf"
73 .Fn quota_maxid "const struct quotafile *qf"
75 .Fn quota_check_path "const struct quotafile *qf" "const char *path"
77 .Fn quota_convert "struct quotafile *qf" "int wordsize"
79 These functions are designed to simplify access to filesystem quotas.
80 If quotas are active on a filesystem,
81 these functions will access them directly from the kernel using the
84 If quotas are not active,
85 these functions will access them by reading and writing
86 the quota files directly.
90 function takes a pointer to an
92 entry corresponding to the filesystem on which quotas
96 field indicates the type of quotas being sought, either
102 are those used by the
104 system call, usually either
106 if the quotas are just to be read, or
108 if the quotas are to be updated.
111 flag should be specified if a new quota file of the requested type
112 should be created if it does not already exist.
116 function closes any open file descriptors and frees any storage
117 associated with the filesystem and quota type referenced by
122 function enables quotas for the filesystem associated with its
124 argument which may have been opened with
130 function returns 0 if successful;
131 otherwise the value\~-1 is returned and the global variable
133 is set to indicate the error, see
135 for the possible errors.
139 function disables quotas for the filesystem associated with its
141 argument which may have been opened with
147 function returns 0 if successful;
148 otherwise the value\~-1 is returned and the global variable
150 is set to indicate the error, see
152 for the possible errors.
156 function reads the quota from the filesystem and quota type referenced by
158 for the user (or group) specified by
162 quota structure pointed to by
166 .Fn quota_write_limits
167 function updates the limit fields (but not the usage fields)
168 for the filesystem and quota type referenced by
170 for the user (or group) specified by
174 quota structure pointed to by
178 .Fn quota_write_usage
179 function updates the usage fields (but not the limit fields)
180 for the filesystem and quota type referenced by
182 for the user (or group) specified by
186 quota structure pointed to by
191 function returns a pointer to a buffer containing the path to the root
192 of the file system that corresponds to its
194 argument, as listed in
196 Note that this may be a symbolic link to the actual directory.
200 function returns a pointer to a buffer containing the name of the
201 quota file that corresponds to its
204 Note that this may be a symbolic link to the actual file.
208 function returns the maximum user (or group)
210 contained in the quota file associated with its
216 function checks if the specified path is within the filesystem that
222 argument refers to a symbolic link,
228 function converts the quota file associated with its
230 argument to the data size specified by its
233 The supported wordsize arguments are 32 for the old 32-bit
234 quota file format and 64 for the new 64-bit quota file format.
237 function may only be called to operate on quota files that
238 are not currently active.
239 .Sh IMPLEMENTATION NOTES
240 If the underlying quota file is in or converted to the old 32-bit format,
241 limit and usage values written to the quota file will be clipped to 32 bits.
243 If the filesystem has quotas associated with it,
245 returns a pointer to a
247 structure used in subsequent quota access calls.
248 If the filesystem has no quotas, or access permission is denied
252 is set to indicate the error.
256 function returns\~1 for a positive result and\~0 for a negative
258 If an error occurs, it returns\~-1 and sets
260 to indicate the error.
264 .Fn quota_write_limits ,
265 .Fn quota_write_usage ,
269 functions return zero on success.
270 On error they return\~-1
273 to indicate the error.
281 functions first appeared in
287 functions and this manual page were written by
288 .An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org
290 .An Marshall Kirk McKusick Aq mckusick@mckusick.com .