lib/libc/sys/quotactl.2

   1 .\" Copyright (c) 1983, 1990, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" Robert Elz at The University of Melbourne.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 4. Neither the name of the University nor the names of its contributors
  16 .\"    may be used to endorse or promote products derived from this software
  17 .\"    without specific prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  22 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  29 .\" SUCH DAMAGE.
  30 .\"
  31 .\"     @(#)quotactl.2  8.2 (Berkeley) 3/10/95
  32 .\" $FreeBSD$
  33 .\"
  34 .Dd March 5, 1999
  35 .Dt QUOTACTL 2
  36 .Os
  37 .Sh NAME
  38 .Nm quotactl
  39 .Nd manipulate file system quotas
  40 .Sh LIBRARY
  41 .Lb libc
  42 .Sh SYNOPSIS
  43 .In sys/types.h
  44 .In ufs/ufs/quota.h
  45 .Ft int
  46 .Fn quotactl "const char *path" "int cmd" "int id" "void *addr"
  47 .Sh DESCRIPTION
  48 The
  49 .Fn quotactl
  50 system call enables, disables and
  51 manipulates file system quotas.
  52 A quota control command
  53 given by
  54 .Fa cmd
  55 operates on the given filename
  56 .Fa path
  57 for the given user or group
  58 .Fa id .
  59 (NOTE: One should use the QCMD macro defined in
  60 .In ufs/ufs/quota.h
  61 to formulate the value for
  62 .Fa cmd . )
  63 The address of an optional command specific data structure,
  64 .Fa addr ,
  65 may be given; its interpretation
  66 is discussed below with each command.
  67 .Pp
  68 For commands that use the
  69 .Fa id
  70 identifier, it must be either -1 or any positive value.
  71 The value of -1 indicates that the current UID or GID should be used.
  72 Any other negative value will return an error.
  73 .Pp
  74 Currently quotas are supported only for the
  75 .Dq ufs
  76 file system.
  77 For
  78 .Dq ufs ,
  79 a command is composed of a primary command (see below)
  80 and a command type used to interpret the
  81 .Fa id .
  82 Types are supported for interpretation of user identifiers (USRQUOTA)
  83 and group identifiers (GRPQUOTA).
  84 The
  85 .Dq ufs
  86 specific commands are:
  87 .Bl -tag -width Q_GETQUOTASIZEx
  88 .It Dv Q_QUOTAON
  89 Enable disk quotas for the file system specified by
  90 .Fa path .
  91 The command type specifies the type of the quotas being enabled.
  92 The
  93 .Fa addr
  94 argument specifies a file from which to take the quotas.
  95 The quota file must exist;
  96 it is normally created with the
  97 .Xr quotacheck 8
  98 program.
  99 The
 100 .Fa id
 101 argument is unused.
 102 Only the super-user may turn quotas on.
 103 .It Dv Q_QUOTAOFF
 104 Disable disk quotas for the file system specified by
 105 .Fa path .
 106 The command type specifies the type of the quotas being disabled.
 107 The
 108 .Fa addr
 109 and
 110 .Fa id
 111 arguments are unused.
 112 Only the super-user may turn quotas off.
 113 .It Dv Q_GETQUOTASIZE
 114 Get the wordsize used to represent the quotas for the user or group
 115 (as determined by the command type).
 116 Possible values are 32 for the old-style quota file
 117 and 64 for the new-style quota file.
 118 The
 119 .Fa addr
 120 argument is a pointer to an integer into which the size is stored.
 121 The identifier
 122 .Fa id
 123 is not used.
 124 .It Dv Q_GETQUOTA
 125 Get disk quota limits and current usage for the user or group
 126 (as determined by the command type) with identifier
 127 .Fa id .
 128 The
 129 .Fa addr
 130 argument
 131 is a pointer to a
 132 .Fa struct dqblk
 133 structure (defined in
 134 .In ufs/ufs/quota.h ) .
 135 .It Dv Q_SETQUOTA
 136 Set disk quota limits for the user or group
 137 (as determined by the command type) with identifier
 138 .Fa id .
 139 The
 140 .Fa addr
 141 argument
 142 is a pointer to a
 143 .Fa struct dqblk
 144 structure (defined in
 145 .In ufs/ufs/quota.h ) .
 146 The usage fields of the
 147 .Fa dqblk
 148 structure are ignored.
 149 This system call is restricted to the super-user.
 150 .It Dv Q_SETUSE
 151 Set disk usage limits for the user or group
 152 (as determined by the command type) with identifier
 153 .Fa id .
 154 The
 155 .Fa addr
 156 argument
 157 is a pointer to a
 158 .Fa struct dqblk
 159 structure (defined in
 160 .In ufs/ufs/quota.h ) .
 161 Only the usage fields are used.
 162 This system call is restricted to the super-user.
 163 .It Dv Q_SYNC
 164 Update the on-disk copy of quota usages.
 165 The command type specifies which type of quotas are to be updated.
 166 The
 167 .Fa id
 168 and
 169 .Fa addr
 170 arguments are ignored.
 171 .El
 172 .Sh RETURN VALUES
 173 .Rv -std quotactl
 174 .Sh ERRORS
 175 The
 176 .Fn quotactl
 177 system call will fail if:
 178 .Bl -tag -width Er
 179 .It Bq Er EOPNOTSUPP
 180 The kernel has not been compiled with the
 181 .Dv QUOTA
 182 option.
 183 .It Bq Er EUSERS
 184 The quota table cannot be expanded.
 185 .It Bq Er EINVAL
 186 The
 187 .Fa cmd
 188 argument
 189 or the command type is invalid.
 190 In
 191 .Dv Q_GETQUOTASIZE ,
 192 .Dv Q_GETQUOTA ,
 193 .Dv Q_SETQUOTA ,
 194 and
 195 .Dv Q_SETUSE ,
 196 quotas are not currently enabled for this file system.
 197 .Pp
 198 The
 199 .Fa id
 200 argument to
 201 .Dv Q_GETQUOTA ,
 202 .Dv Q_SETQUOTA
 203 or
 204 .Dv Q_SETUSE
 205 is a negative value.
 206 .It Bq Er EACCES
 207 In
 208 .Dv Q_QUOTAON ,
 209 the quota file is not a plain file.
 210 .It Bq Er EACCES
 211 Search permission is denied for a component of a path prefix.
 212 .It Bq Er ENOTDIR
 213 A component of a path prefix was not a directory.
 214 .It Bq Er ENAMETOOLONG
 215 A component of either pathname exceeded 255 characters,
 216 or the entire length of either path name exceeded 1023 characters.
 217 .It Bq Er ENOENT
 218 A filename does not exist.
 219 .It Bq Er ELOOP
 220 Too many symbolic links were encountered in translating a pathname.
 221 .It Bq Er EROFS
 222 In
 223 .Dv Q_QUOTAON ,
 224 either the file system on which quotas are to be enabled is mounted read-only
 225 or the quota file resides on a read-only file system.
 226 .It Bq Er EIO
 227 An
 228 .Tn I/O
 229 error occurred while reading from or writing
 230 to a file containing quotas.
 231 .It Bq Er EFAULT
 232 An invalid
 233 .Fa addr
 234 was supplied; the associated structure could not be copied in or out
 235 of the kernel.
 236 .It Bq Er EFAULT
 237 The
 238 .Fa path
 239 argument
 240 points outside the process's allocated address space.
 241 .It Bq Er EPERM
 242 The call was privileged and the caller was not the super-user.
 243 .El
 244 .Sh SEE ALSO
 245 .Xr quota 1 ,
 246 .Xr fstab 5 ,
 247 .Xr edquota 8 ,
 248 .Xr quotacheck 8 ,
 249 .Xr quotaon 8 ,
 250 .Xr repquota 8
 251 .Sh HISTORY
 252 The
 253 .Fn quotactl
 254 system call appeared in
 255 .Bx 4.3 Reno .
 256 .Sh BUGS
 257 There should be some way to integrate this call with the resource
 258 limit interface provided by
 259 .Xr setrlimit 2
 260 and
 261 .Xr getrlimit 2 .