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