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