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 .\"     @(#)quotactl.2  8.2 (Berkeley) 3/10/95
  32 .\" $FreeBSD: src/lib/libc/sys/quotactl.2,v 1.12.2.7 2002/05/20 09:06:37 roam Exp $
  33 .\"
  34 .Dd February 21, 2020
  35 .Dt QUOTACTL 2
  36 .Os
  37 .Sh NAME
  38 .Nm quotactl
  39 .Nd manipulate filesystem quotas
  40 .Sh LIBRARY
  41 .Lb libc
  42 .Sh SYNOPSIS
  43 .In sys/types.h
  44 .In vfs/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 call enables, disables and
  51 manipulates filesystem 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 filesystem.
  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 filesystem 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 filesystem 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 .Fa Addr
 112 is a pointer to a
 113 .Fa struct dqblk
 114 structure (defined in
 115 .In ufs/ufs/quota.h ) .
 116 .It Dv Q_SETQUOTA
 117 Set disk quota limits for the user or group
 118 (as determined by the command type) with identifier
 119 .Fa id .
 120 .Fa Addr
 121 is a pointer to a
 122 .Fa struct dqblk
 123 structure (defined in
 124 .In ufs/ufs/quota.h ) .
 125 The usage fields of the
 126 .Fa dqblk
 127 structure are ignored.
 128 This call is restricted to the super-user.
 129 .It Dv Q_SETUSE
 130 Set disk usage limits for the user or group
 131 (as determined by the command type) with identifier
 132 .Fa id .
 133 .Fa Addr
 134 is a pointer to a
 135 .Fa struct dqblk
 136 structure (defined in
 137 .In ufs/ufs/quota.h ) .
 138 Only the usage fields are used.
 139 This call is restricted to the super-user.
 140 .It Dv Q_SYNC
 141 Update the on-disk copy of quota usages.
 142 The command type specifies which type of quotas are to be updated.
 143 The
 144 .Fa id
 145 and
 146 .Fa addr
 147 parameters are ignored.
 148 .El
 149 .Sh RETURN VALUES
 150 .Rv -std quotactl
 151 .Sh ERRORS
 152 A
 153 .Fn quotactl
 154 call will fail if:
 155 .Bl -tag -width Er
 156 .It Bq Er EOPNOTSUPP
 157 The kernel has not been compiled with the
 158 .Dv QUOTA
 159 option.
 160 .It Bq Er EUSERS
 161 The quota table cannot be expanded.
 162 .It Bq Er EINVAL
 163 .Fa Cmd
 164 or the command type is invalid.
 165 In
 166 .Dv Q_GETQUOTA
 167 and
 168 .Dv Q_SETQUOTA ,
 169 quotas are not currently enabled for this filesystem.
 170 .It Bq Er EACCES
 171 In
 172 .Dv Q_QUOTAON ,
 173 the quota file is not a plain file.
 174 .It Bq Er EACCES
 175 Search permission is denied for a component of a path prefix.
 176 .It Bq Er ENOTDIR
 177 A component of a path prefix was not a directory.
 178 .It Bq Er ENAMETOOLONG
 179 A component of either pathname exceeded 255 characters,
 180 or the entire length of either path name exceeded 1023 characters.
 181 .It Bq Er ENOENT
 182 A filename does not exist.
 183 .It Bq Er ELOOP
 184 Too many symbolic links were encountered in translating a pathname.
 185 .It Bq Er EROFS
 186 In
 187 .Dv Q_QUOTAON ,
 188 the quota file resides on a read-only filesystem.
 189 .It Bq Er EIO
 190 An
 191 .Tn I/O
 192 error occurred while reading from or writing
 193 to a file containing quotas.
 194 .It Bq Er EFAULT
 195 An invalid
 196 .Fa addr
 197 was supplied; the associated structure could not be copied in or out
 198 of the kernel.
 199 .It Bq Er EFAULT
 200 .Fa Path
 201 points outside the process's allocated address space.
 202 .It Bq Er EPERM
 203 The call was privileged and the caller was not the super-user.
 204 .El
 205 .Sh SEE ALSO
 206 .Xr quota 1 ,
 207 .Xr fstab 5 ,
 208 .Xr edquota 8 ,
 209 .Xr quotacheck 8 ,
 210 .Xr quotaon 8 ,
 211 .Xr repquota 8
 212 .Sh HISTORY
 213 The
 214 .Fn quotactl
 215 function call appeared in
 216 .Bx 4.3 Reno .
 217 .Sh BUGS
 218 There should be some way to integrate this call with the resource
 219 limit interface provided by
 220 .Xr setrlimit 2
 221 and
 222 .Xr getrlimit 2 .