lib/libutil/quotafile.3

   1 .\"-
   2 .\" Copyright (c) 2009 Dag-Erling Coïdan Smørgrav and
   3 .\" Marshall Kirk McKusick. All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   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.
  13 .\"
  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
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd December 28, 2009
  29 .Dt QUOTAFILE 3
  30 .Os
  31 .Sh NAME
  32 .Nm quota_open
  33 .Nm quota_close
  34 .Nm quota_on
  35 .Nm quota_off
  36 .Nm quota_read
  37 .Nm quota_write_limits
  38 .Nm quota_write_usage
  39 .Nm quota_fsname
  40 .Nm quota_qfname
  41 .Nm quota_maxid
  42 .Nm quota_check_path
  43 .Nm quota_convert
  44 .Nd "Manipulate quotas"
  45 .Sh LIBRARY
  46 .Lb libutil
  47 .Sh SYNOPSIS
  48 .In sys/param.h
  49 .In sys/mount.h
  50 .In ufs/ufs/quota.h
  51 .In fcntl.h
  52 .In fstab.h
  53 .In libutil.h
  54 .Ft "struct quotafile *"
  55 .Fn quota_open "struct fstab *fs" "int quotatype" "int openflags"
  56 .Ft int
  57 .Fn quota_close "struct quotafile *qf"
  58 .Ft int
  59 .Fn quota_on "const struct quotafile *qf"
  60 .Ft int
  61 .Fn quota_off "const struct quotafile *qf"
  62 .Ft int
  63 .Fn quota_read "struct quotafile *qf" "struct dqblk *dqb" "int id"
  64 .Ft int
  65 .Fn quota_write_limits "struct quotafile *qf" "struct dqblk *dqb" "int id"
  66 .Ft int
  67 .Fn quota_write_usage "struct quotafile *qf" "struct dqblk *dqb" "int id"
  68 .Ft "const char *"
  69 .Fn quota_fsname "const struct quotafile *qf"
  70 .Ft "const char *"
  71 .Fn quota_qfname "const struct quotafile *qf"
  72 .Ft int
  73 .Fn quota_maxid "const struct quotafile *qf"
  74 .Ft int
  75 .Fn quota_check_path "const struct quotafile *qf" "const char *path"
  76 .Ft int
  77 .Fn quota_convert "struct quotafile *qf" "int wordsize"
  78 .Sh DESCRIPTION
  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
  82 .Fn quotactl
  83 system call.
  84 If quotas are not active,
  85 these functions will access them by reading and writing
  86 the quota files directly.
  87 .Pp
  88 The
  89 .Fn quota_open
  90 function takes a pointer to an
  91 .Vt fstab
  92 entry corresponding to the filesystem on which quotas
  93 are to be accessed.
  94 The
  95 .Va quotatype
  96 field indicates the type of quotas being sought, either
  97 .Dv USRQUOTA
  98 or
  99 .Dv GRPQUOTA .
 100 The
 101 .Va openflags
 102 are those used by the
 103 .Fn open
 104 system call, usually either
 105 .Dv O_RDONLY
 106 if the quotas are just to be read, or
 107 .Dv O_RDWR
 108 if the quotas are to be updated.
 109 The
 110 .Dv O_CREAT
 111 flag should be specified if a new quota file of the requested type
 112 should be created if it does not already exist.
 113 .Pp
 114 The
 115 .Fn quota_close
 116 function closes any open file descriptors and frees any storage
 117 associated with the filesystem and quota type referenced by
 118 .Va qf .
 119 .Pp
 120 The
 121 .Fn quota_on
 122 function enables quotas for the filesystem associated with its
 123 .Va qf
 124 argument which may have been opened with
 125 .Dv O_RDONLY
 126 or
 127 .Dv O_RDWR .
 128 The
 129 .Fn quota_on
 130 function returns 0 if successful;
 131 otherwise the value\~-1 is returned and the global variable
 132 .Va errno
 133 is set to indicate the error, see
 134 .Xr quotactl 2
 135 for the possible errors.
 136 .Pp
 137 The
 138 .Fn quota_off
 139 function disables quotas for the filesystem associated with its
 140 .Va qf
 141 argument which may have been opened with
 142 .Dv O_RDONLY
 143 or
 144 .Dv O_RDWR .
 145 The
 146 .Fn quota_off
 147 function returns 0 if successful;
 148 otherwise the value\~-1 is returned and the global variable
 149 .Va errno
 150 is set to indicate the error, see
 151 .Xr quotactl 2
 152 for the possible errors.
 153 .Pp
 154 The
 155 .Fn quota_read
 156 function reads the quota from the filesystem and quota type referenced by
 157 .Va qf
 158 for the user (or group) specified by
 159 .Va id
 160 into the
 161 .Vt dqblk
 162 quota structure pointed to by
 163 .Va dqb .
 164 .Pp
 165 The
 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
 169 .Va qf
 170 for the user (or group) specified by
 171 .Va id
 172 from the
 173 .Vt dqblk
 174 quota structure pointed to by
 175 .Va dqb .
 176 .Pp
 177 The
 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
 181 .Va qf
 182 for the user (or group) specified by
 183 .Va id
 184 from the
 185 .Vt dqblk
 186 quota structure pointed to by
 187 .Va dqb .
 188 .Pp
 189 The
 190 .Fn quota_fsname
 191 function returns a pointer to a buffer containing the path to the root
 192 of the file system that corresponds to its
 193 .Va qf
 194 argument, as listed in
 195 .Pa /etc/fstab .
 196 Note that this may be a symbolic link to the actual directory.
 197 .Pp
 198 The
 199 .Fn quota_qfname
 200 function returns a pointer to a buffer containing the name of the
 201 quota file that corresponds to its
 202 .Va qf
 203 argument.
 204 Note that this may be a symbolic link to the actual file.
 205 .Pp
 206 The
 207 .Fn quota_maxid
 208 function returns the maximum user (or group)
 209 .Va id
 210 contained in the quota file associated with its
 211 .Va qf
 212 argument.
 213 .Pp
 214 The
 215 .Fn quota_check_path
 216 function checks if the specified path is within the filesystem that
 217 corresponds to its
 218 .Va qf
 219 argument.
 220 If the
 221 .Va path
 222 argument refers to a symbolic link,
 223 .Fn quota_check_path
 224 will follow it.
 225 .Pp
 226 The
 227 .Fn quota_convert
 228 function converts the quota file associated with its
 229 .Va qf
 230 argument to the data size specified by its
 231 .Va wordsize
 232 argument.
 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.
 235 The
 236 .Fn quota_convert
 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.
 242 .Sh RETURN VALUES
 243 If the filesystem has quotas associated with it,
 244 .Fn quota_open
 245 returns a pointer to a
 246 .Vt quotafile
 247 structure used in subsequent quota access calls.
 248 If the filesystem has no quotas, or access permission is denied
 249 .Dv NULL
 250 is returned and
 251 .Va errno
 252 is set to indicate the error.
 253 .Pp
 254 The
 255 .Fn quota_check_path
 256 function returns\~1 for a positive result and\~0 for a negative
 257 result.
 258 If an error occurs, it returns\~-1 and sets
 259 .Va errno
 260 to indicate the error.
 261 .Pp
 262 The
 263 .Fn quota_read ,
 264 .Fn quota_write_limits ,
 265 .Fn quota_write_usage ,
 266 .Fn quota_convert ,
 267 and
 268 .Fn quota_close
 269 functions return zero on success.
 270 On error they return\~-1
 271 and set
 272 .Va errno
 273 to indicate the error.
 274 .Sh SEE ALSO
 275 .Xr quotactl 2 ,
 276 .Xr quota.user 5 ,
 277 .Xr quota.group 5
 278 .Sh HISTORY
 279 The
 280 .Nm quotafile
 281 functions first appeared in
 282 .Fx 8.1 .
 283 .Sh AUTHORS
 284 .An -nosplit
 285 The
 286 .Nm quotafile
 287 functions and this manual page were written by
 288 .An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org
 289 and
 290 .An Marshall Kirk McKusick Aq mckusick@mckusick.com .