bsd/man/man2/quotactl.2

   1 .\"     $NetBSD: quotactl.2,v 1.8 1995/02/27 12:35:43 cgd Exp $
   2 .\"
   3 .\" Copyright (c) 1983, 1990, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to Berkeley by
   7 .\" Robert Elz at The University of Melbourne.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\" 3. All advertising materials mentioning features or use of this software
  18 .\"    must display the following acknowledgement:
  19 .\"     This product includes software developed by the University of
  20 .\"     California, Berkeley and its contributors.
  21 .\" 4. Neither the name of the University nor the names of its contributors
  22 .\"    may be used to endorse or promote products derived from this software
  23 .\"    without specific prior written permission.
  24 .\"
  25 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  26 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  27 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  28 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  29 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  30 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  31 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  32 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  33 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  34 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  35 .\" SUCH DAMAGE.
  36 .\"
  37 .\"     @(#)quotactl.2  8.1 (Berkeley) 6/4/93
  38 .\"
  39 .Dd June 4, 1993
  40 .Dt QUOTACTL 2
  41 .Os
  42 .Sh NAME
  43 .Nm quotactl
  44 .Nd manipulate filesystem quotas
  45 .Sh SYNOPSIS
  46 .Fd #include <sys/quota.h>      /* for disk quotas */
  47 .Ft int
  48 .Fn quotactl "const char *path" "int cmd" "int id" "char *addr"
  49 .Sh DESCRIPTION
  50 The
  51 .Fn quotactl
  52 call enables, disables and
  53 manipulates filesystem quotas.
  54 A quota control command
  55 given by
  56 .Fa cmd
  57 operates on the given filename
  58 .Fa path
  59 for the given user
  60 .Fa id .
  61 The address of an optional command specific data structure,
  62 .Fa addr ,
  63 may be given; its interpretation
  64 is discussed below with each command.
  65 .Pp
  66 Currently quotas are supported only for the "ffs" and "hfs" filesystems.
  67 A command is composed of a primary command (see below)
  68 and a command type used to interpret the
  69 .Fa id .
  70 Types are supported for interpretation of user identifiers
  71 and group identifiers.
  72 The specific commands are:
  73 .Bl -tag -width Q_QUOTASTAT
  74 .It Dv Q_QUOTAON
  75 Enable disk quotas for the filesystem specified by
  76 .Fa path .
  77 The command type specifies the type of the quotas being enabled.
  78 The
  79 .Fa addr
  80 argument specifies a file from which to take the quotas.
  81 The quota file must exist;
  82 it is normally created with the
  83 .Xr quotacheck 8
  84 program.
  85 The
  86 .Fa id
  87 argument is unused.
  88 Only the super-user may turn quotas on.
  89 .It Dv Q_QUOTAOFF
  90 Disable disk quotas for the filesystem specified by
  91 .Fa path .
  92 The command type specifies the type of the quotas being disabled.
  93 The
  94 .Fa addr
  95 and
  96 .Fa id
  97 arguments are unused.
  98 Only the super-user may turn quotas off.
  99 .It Dv Q_GETQUOTA
 100 Get disk quota limits and current usage for the user or group
 101 (as determined by the command type) with identifier
 102 .Fa id .
 103 .Fa Addr
 104 is a pointer to a
 105 .Fa struct dqblk
 106 structure.
 107 .It Dv Q_SETQUOTA
 108 Set disk quota limits 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.
 115 The usage fields of the
 116 .Fa dqblk
 117 structure are ignored.
 118 This call is restricted to the super-user.
 119 .It Dv Q_SETUSE
 120 Set disk usage limits for the user or group
 121 (as determined by the command type) with identifier
 122 .Fa id .
 123 .Fa Addr
 124 is a pointer to a
 125 .Fa struct dqblk
 126 structure.
 127 Only the usage fields are used.
 128 This call is restricted to the super-user.
 129 .It Dv Q_SYNC
 130 Update the on-disk copy of quota usages.
 131 The command type specifies which type of quotas are to be updated.
 132 The
 133 .Fa id
 134 and
 135 .Fa addr
 136 parameters are ignored.
 137 .It Dv Q_QUOTASTAT
 138 Get the enable status for the filesystem specified by
 139 .Fa path .
 140 The command type specifies the type of the quotas whose
 141 status is being queried.
 142 .Fa Addr
 143 is a pointer to an integer.  Upon return,
 144 this integer will hold a zero value if quotas for the
 145 given type are not enabled and a non-zero value if
 146 quotas for the given type are enabled.
 147 The
 148 .Fa id
 149 parameter is ignored.
 150 .El
 151 .Sh RETURN VALUES
 152 A successful call returns 0,
 153 otherwise the value -1 is returned and the global variable
 154 .Va errno
 155 indicates the reason for the failure.
 156 .Sh ERRORS
 157 A
 158 .Fn quotactl
 159 call will fail if:
 160 .Bl -tag -width Er
 161 .It Bq Er ENOTSUP
 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 .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 a pathname exceeded
 180 .Dv {NAME_MAX}
 181 characters, or an entire path name exceeded
 182 .Dv {PATH_MAX}
 183 characters.
 184 .It Bq Er ENOENT
 185 A filename does not exist.
 186 .It Bq Er ELOOP
 187 Too many symbolic links were encountered in translating a pathname.
 188 .It Bq Er EROFS
 189 In
 190 .Dv Q_QUOTAON ,
 191 the quota file resides on a read-only filesystem.
 192 .It Bq Er EIO
 193 An
 194 .Tn I/O
 195 error occurred while reading from or writing
 196 to a file containing quotas.
 197 .It Bq Er EFAULT
 198 An invalid
 199 .Fa addr
 200 was supplied; the associated structure could not be copied in or out
 201 of the kernel.
 202 .It Bq Er EFAULT
 203 .Fa Path
 204 points outside the process's allocated address space.
 205 .It Bq Er EPERM
 206 The call was privileged and the caller was not the super-user.
 207 .El
 208 .Sh SEE ALSO
 209 .Xr quota 1 ,
 210 .Xr fstab 5 ,
 211 .Xr edquota 8 ,
 212 .Xr quotacheck 8 ,
 213 .Xr quotaon 8 ,
 214 .Xr repquota 8
 215 .Sh BUGS
 216 There should be some way to integrate this call with the resource
 217 limit interface provided by
 218 .Xr setrlimit 2
 219 and
 220 .Xr getrlimit 2 .
 221 .Sh HISTORY
 222 The
 223 .Fn quotactl
 224 function call appeared in
 225 .Bx 4.3 Reno .