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 .\" 3. 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 .Dd March 30, 2020
  32 .Dt QUOTACTL 2
  33 .Os
  34 .Sh NAME
  35 .Nm quotactl
  36 .Nd manipulate file system quotas
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .In sys/types.h
  41 .In ufs/ufs/quota.h
  42 .Ft int
  43 .Fn quotactl "const char *path" "int cmd" "int id" "void *addr"
  44 .Sh DESCRIPTION
  45 The
  46 .Fn quotactl
  47 system call enables, disables and
  48 manipulates file system quotas.
  49 A quota control command
  50 given by
  51 .Fa cmd
  52 operates on the given filename
  53 .Fa path
  54 for the given user or group
  55 .Fa id .
  56 (NOTE: One should use the QCMD macro defined in
  57 .In ufs/ufs/quota.h
  58 to formulate the value for
  59 .Fa cmd . )
  60 The address of an optional command specific data structure,
  61 .Fa addr ,
  62 may be given; its interpretation
  63 is discussed below with each command.
  64 .Pp
  65 For commands that use the
  66 .Fa id
  67 identifier, it must be either -1 or any positive value.
  68 The value of -1 indicates that the current UID or GID should be used.
  69 Any other negative value will return an error.
  70 .Pp
  71 Currently quotas are supported only for the
  72 .Dq ufs
  73 file system.
  74 For
  75 .Dq ufs ,
  76 a command is composed of a primary command (see below)
  77 and a command type used to interpret the
  78 .Fa id .
  79 Types are supported for interpretation of user identifiers (USRQUOTA)
  80 and group identifiers (GRPQUOTA).
  81 The
  82 .Dq ufs
  83 specific commands are:
  84 .Bl -tag -width Q_GETQUOTASIZEx
  85 .It Dv Q_QUOTAON
  86 Enable disk quotas for the file system specified by
  87 .Fa path .
  88 The command type specifies the type of the quotas being enabled.
  89 The
  90 .Fa addr
  91 argument specifies a file from which to take the quotas.
  92 The quota file must exist;
  93 it is normally created with the
  94 .Xr quotacheck 8
  95 program.
  96 The
  97 .Fa id
  98 argument is unused.
  99 Only the super-user may turn quotas on.
 100 .It Dv Q_QUOTAOFF
 101 Disable disk quotas for the file system specified by
 102 .Fa path .
 103 The command type specifies the type of the quotas being disabled.
 104 The
 105 .Fa addr
 106 and
 107 .Fa id
 108 arguments are unused.
 109 Only the super-user may turn quotas off.
 110 .It Dv Q_GETQUOTASIZE
 111 Get the wordsize used to represent the quotas for the user or group
 112 (as determined by the command type).
 113 Possible values are 32 for the old-style quota file
 114 and 64 for the new-style quota file.
 115 The
 116 .Fa addr
 117 argument is a pointer to an integer into which the size is stored.
 118 The identifier
 119 .Fa id
 120 is not used.
 121 .It Dv Q_GETQUOTA
 122 Get disk quota limits and current usage for the user or group
 123 (as determined by the command type) with identifier
 124 .Fa id .
 125 The
 126 .Fa addr
 127 argument
 128 is a pointer to a
 129 .Fa struct dqblk
 130 structure (defined in
 131 .In ufs/ufs/quota.h ) .
 132 .It Dv Q_SETQUOTA
 133 Set disk quota limits for the user or group
 134 (as determined by the command type) with identifier
 135 .Fa id .
 136 The
 137 .Fa addr
 138 argument
 139 is a pointer to a
 140 .Fa struct dqblk
 141 structure (defined in
 142 .In ufs/ufs/quota.h ) .
 143 The usage fields of the
 144 .Fa dqblk
 145 structure are ignored.
 146 This system call is restricted to the super-user.
 147 .It Dv Q_SETUSE
 148 Set disk usage limits for the user or group
 149 (as determined by the command type) with identifier
 150 .Fa id .
 151 The
 152 .Fa addr
 153 argument
 154 is a pointer to a
 155 .Fa struct dqblk
 156 structure (defined in
 157 .In ufs/ufs/quota.h ) .
 158 Only the usage fields are used.
 159 This system call is restricted to the super-user.
 160 .It Dv Q_SYNC
 161 Update the on-disk copy of quota usages.
 162 The command type specifies which type of quotas are to be updated.
 163 The
 164 .Fa id
 165 and
 166 .Fa addr
 167 arguments are ignored.
 168 .El
 169 .Sh RETURN VALUES
 170 .Rv -std quotactl
 171 .Sh ERRORS
 172 The
 173 .Fn quotactl
 174 system call will fail if:
 175 .Bl -tag -width Er
 176 .It Bq Er EOPNOTSUPP
 177 The kernel has not been compiled with the
 178 .Dv QUOTA
 179 option.
 180 .It Bq Er EUSERS
 181 The quota table cannot be expanded.
 182 .It Bq Er EINVAL
 183 The
 184 .Fa cmd
 185 argument
 186 or the command type is invalid.
 187 In
 188 .Dv Q_GETQUOTASIZE ,
 189 .Dv Q_GETQUOTA ,
 190 .Dv Q_SETQUOTA ,
 191 and
 192 .Dv Q_SETUSE ,
 193 quotas are not currently enabled for this file system.
 194 .Pp
 195 The
 196 .Fa id
 197 argument to
 198 .Dv Q_GETQUOTA ,
 199 .Dv Q_SETQUOTA
 200 or
 201 .Dv Q_SETUSE
 202 is a negative value.
 203 .It Bq Er EACCES
 204 In
 205 .Dv Q_QUOTAON ,
 206 the quota file is not a plain file.
 207 .It Bq Er EACCES
 208 Search permission is denied for a component of a path prefix.
 209 .It Bq Er ENOTDIR
 210 A component of a path prefix was not a directory.
 211 .It Bq Er ENAMETOOLONG
 212 A component of either pathname exceeded 255 characters,
 213 or the entire length of either path name exceeded 1023 characters.
 214 .It Bq Er ENOENT
 215 A filename does not exist.
 216 .It Bq Er ELOOP
 217 Too many symbolic links were encountered in translating a pathname.
 218 .It Bq Er EROFS
 219 In
 220 .Dv Q_QUOTAON ,
 221 either the file system on which quotas are to be enabled is mounted read-only
 222 or the quota file resides on a read-only file system.
 223 .It Bq Er EIO
 224 An
 225 .Tn I/O
 226 error occurred while reading from or writing
 227 to a file containing quotas.
 228 .It Bq Er EINTEGRITY
 229 Corrupted data was detected while reading from the file system.
 230 .It Bq Er EFAULT
 231 An invalid
 232 .Fa addr
 233 was supplied; the associated structure could not be copied in or out
 234 of the kernel.
 235 .It Bq Er EFAULT
 236 The
 237 .Fa path
 238 argument
 239 points outside the process's allocated address space.
 240 .It Bq Er EPERM
 241 The call was privileged and the caller was not the super-user.
 242 .El
 243 .Sh SEE ALSO
 244 .Xr quota 1 ,
 245 .Xr fstab 5 ,
 246 .Xr edquota 8 ,
 247 .Xr quotacheck 8 ,
 248 .Xr quotaon 8 ,
 249 .Xr repquota 8
 250 .Sh HISTORY
 251 The
 252 .Fn quotactl
 253 system call appeared in
 254 .Bx 4.3 Reno .
 255 .Sh BUGS
 256 There should be some way to integrate this call with the resource
 257 limit interface provided by
 258 .Xr setrlimit 2
 259 and
 260 .Xr getrlimit 2 .