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
  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 Currently quotas are supported only for the
  69 .Dq ufs
  70 file system.
  71 For
  72 .Dq ufs ,
  73 a command is composed of a primary command (see below)
  74 and a command type used to interpret the
  75 .Fa id .
  76 Types are supported for interpretation of user identifiers (USRQUOTA)
  77 and group identifiers (GRPQUOTA).
  78 The
  79 .Dq ufs
  80 specific commands are:
  81 .Bl -tag -width Q_QUOTAOFFxx
  82 .It Dv Q_QUOTAON
  83 Enable disk quotas for the file system specified by
  84 .Fa path .
  85 The command type specifies the type of the quotas being enabled.
  86 The
  87 .Fa addr
  88 argument specifies a file from which to take the quotas.
  89 The quota file must exist;
  90 it is normally created with the
  91 .Xr quotacheck 8
  92 program.
  93 The
  94 .Fa id
  95 argument is unused.
  96 Only the super-user may turn quotas on.
  97 .It Dv Q_QUOTAOFF
  98 Disable disk quotas for the file system specified by
  99 .Fa path .
 100 The command type specifies the type of the quotas being disabled.
 101 The
 102 .Fa addr
 103 and
 104 .Fa id
 105 arguments are unused.
 106 Only the super-user may turn quotas off.
 107 .It Dv Q_GETQUOTA
 108 Get disk quota limits and current usage for the user or group
 109 (as determined by the command type) with identifier
 110 .Fa id .
 111 The
 112 .Fa addr
 113 argument
 114 is a pointer to a
 115 .Fa struct dqblk
 116 structure (defined in
 117 .In ufs/ufs/quota.h ) .
 118 .It Dv Q_SETQUOTA
 119 Set disk quota limits for the user or group
 120 (as determined by the command type) with identifier
 121 .Fa id .
 122 The
 123 .Fa addr
 124 argument
 125 is a pointer to a
 126 .Fa struct dqblk
 127 structure (defined in
 128 .In ufs/ufs/quota.h ) .
 129 The usage fields of the
 130 .Fa dqblk
 131 structure are ignored.
 132 This system call is restricted to the super-user.
 133 .It Dv Q_SETUSE
 134 Set disk usage limits for the user or group
 135 (as determined by the command type) with identifier
 136 .Fa id .
 137 The
 138 .Fa addr
 139 argument
 140 is a pointer to a
 141 .Fa struct dqblk
 142 structure (defined in
 143 .In ufs/ufs/quota.h ) .
 144 Only the usage fields are used.
 145 This system call is restricted to the super-user.
 146 .It Dv Q_SYNC
 147 Update the on-disk copy of quota usages.
 148 The command type specifies which type of quotas are to be updated.
 149 The
 150 .Fa id
 151 and
 152 .Fa addr
 153 arguments are ignored.
 154 .El
 155 .Sh RETURN VALUES
 156 .Rv -std quotactl
 157 .Sh ERRORS
 158 The
 159 .Fn quotactl
 160 system call will fail if:
 161 .Bl -tag -width Er
 162 .It Bq Er EOPNOTSUPP
 163 The kernel has not been compiled with the
 164 .Dv QUOTA
 165 option.
 166 .It Bq Er EUSERS
 167 The quota table cannot be expanded.
 168 .It Bq Er EINVAL
 169 The
 170 .Fa cmd
 171 argument
 172 or the command type is invalid.
 173 In
 174 .Dv Q_GETQUOTA
 175 and
 176 .Dv Q_SETQUOTA ,
 177 quotas are not currently enabled for this file system.
 178 .It Bq Er EACCES
 179 In
 180 .Dv Q_QUOTAON ,
 181 the quota file is not a plain file.
 182 .It Bq Er EACCES
 183 Search permission is denied for a component of a path prefix.
 184 .It Bq Er ENOTDIR
 185 A component of a path prefix was not a directory.
 186 .It Bq Er ENAMETOOLONG
 187 A component of either pathname exceeded 255 characters,
 188 or the entire length of either path name exceeded 1023 characters.
 189 .It Bq Er ENOENT
 190 A filename does not exist.
 191 .It Bq Er ELOOP
 192 Too many symbolic links were encountered in translating a pathname.
 193 .It Bq Er EROFS
 194 In
 195 .Dv Q_QUOTAON ,
 196 the quota file resides on a read-only file system.
 197 .It Bq Er EIO
 198 An
 199 .Tn I/O
 200 error occurred while reading from or writing
 201 to a file containing quotas.
 202 .It Bq Er EFAULT
 203 An invalid
 204 .Fa addr
 205 was supplied; the associated structure could not be copied in or out
 206 of the kernel.
 207 .It Bq Er EFAULT
 208 The
 209 .Fa path
 210 argument
 211 points outside the process's allocated address space.
 212 .It Bq Er EPERM
 213 The call was privileged and the caller was not the super-user.
 214 .El
 215 .Sh SEE ALSO
 216 .Xr quota 1 ,
 217 .Xr fstab 5 ,
 218 .Xr edquota 8 ,
 219 .Xr quotacheck 8 ,
 220 .Xr quotaon 8 ,
 221 .Xr repquota 8
 222 .Sh HISTORY
 223 The
 224 .Fn quotactl
 225 system call appeared in
 226 .Bx 4.3 Reno .
 227 .Sh BUGS
 228 There should be some way to integrate this call with the resource
 229 limit interface provided by
 230 .Xr setrlimit 2
 231 and
 232 .Xr getrlimit 2 .