lib/libutil/quotafile.3

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