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/types.h>      /* types needed by quota.h */
  47 .Fd #include <sys/quota.h>      /* for disk quotas */
  48 .Ft int
  49 .Fn quotactl "const char *path" "int cmd" "int id" "char *addr"
  50 .Sh DESCRIPTION
  51 The
  52 .Fn quotactl
  53 call enables, disables and
  54 manipulates filesystem quotas.
  55 A quota control command
  56 given by
  57 .Fa cmd
  58 operates on the given filename
  59 .Fa path
  60 for the given user
  61 .Fa id .
  62 The address of an optional command specific data structure,
  63 .Fa addr ,
  64 may be given; its interpretation
  65 is discussed below with each command.
  66 .Pp
  67 Currently quotas are supported only for the "ffs" and "hfs" filesystems.
  68 A command is composed of a primary command (see below)
  69 and a command type used to interpret the
  70 .Fa id .
  71 Types are supported for interpretation of user identifiers
  72 and group identifiers.
  73 The specific commands are:
  74 .Bl -tag -width Q_QUOTASTAT
  75 .It Dv Q_QUOTAON
  76 Enable disk quotas for the filesystem specified by
  77 .Fa path .
  78 The command type specifies the type of the quotas being enabled.
  79 The
  80 .Fa addr
  81 argument specifies a file from which to take the quotas.
  82 The quota file must exist;
  83 it is normally created with the
  84 .Xr quotacheck 8
  85 program.
  86 The
  87 .Fa id
  88 argument is unused.
  89 Only the super-user may turn quotas on.
  90 .It Dv Q_QUOTAOFF
  91 Disable disk quotas for the filesystem specified by
  92 .Fa path .
  93 The command type specifies the type of the quotas being disabled.
  94 The
  95 .Fa addr
  96 and
  97 .Fa id
  98 arguments are unused.
  99 Only the super-user may turn quotas off.
 100 .It Dv Q_GETQUOTA
 101 Get disk quota limits and current usage for the user or group
 102 (as determined by the command type) with identifier
 103 .Fa id .
 104 .Fa Addr
 105 is a pointer to a
 106 .Fa struct dqblk
 107 structure.
 108 .It Dv Q_SETQUOTA
 109 Set disk quota limits for the user or group
 110 (as determined by the command type) with identifier
 111 .Fa id .
 112 .Fa Addr
 113 is a pointer to a
 114 .Fa struct dqblk
 115 structure.
 116 The usage fields of the
 117 .Fa dqblk
 118 structure are ignored.
 119 This call is restricted to the super-user.
 120 .It Dv Q_SETUSE
 121 Set disk usage limits for the user or group
 122 (as determined by the command type) with identifier
 123 .Fa id .
 124 .Fa Addr
 125 is a pointer to a
 126 .Fa struct dqblk
 127 structure.
 128 Only the usage fields are used.
 129 This call is restricted to the super-user.
 130 .It Dv Q_SYNC
 131 Update the on-disk copy of quota usages.
 132 The command type specifies which type of quotas are to be updated.
 133 The
 134 .Fa id
 135 and
 136 .Fa addr
 137 parameters are ignored.
 138 .It Dv Q_QUOTASTAT
 139 Get the enable status for the filesystem specified by
 140 .Fa path .
 141 The command type specifies the type of the quotas whose
 142 status is being queried.
 143 .Fa Addr
 144 is a pointer to an integer.  Upon return,
 145 this integer will hold a zero value if quotas for the
 146 given type are not enabled and a non-zero value if
 147 quotas for the given type are enabled.
 148 The
 149 .Fa id
 150 parameter is ignored.
 151 .El
 152 .Sh RETURN VALUES
 153 A successful call returns 0,
 154 otherwise the value -1 is returned and the global variable
 155 .Va errno
 156 indicates the reason for the failure.
 157 .Sh ERRORS
 158 A
 159 .Fn quotactl
 160 call will fail if:
 161 .Bl -tag -width Er
 162 .It Bq Er ENOTSUP
 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 .Fa Cmd
 170 or the command type is invalid.
 171 .It Bq Er EACCES
 172 In
 173 .Dv Q_QUOTAON ,
 174 the quota file is not a plain file.
 175 .It Bq Er EACCES
 176 Search permission is denied for a component of a path prefix.
 177 .It Bq Er ENOTDIR
 178 A component of a path prefix was not a directory.
 179 .It Bq Er ENAMETOOLONG
 180 A component of a pathname exceeded
 181 .Dv {NAME_MAX}
 182 characters, or an entire path name exceeded
 183 .Dv {PATH_MAX}
 184 characters.
 185 .It Bq Er ENOENT
 186 A filename does not exist.
 187 .It Bq Er ELOOP
 188 Too many symbolic links were encountered in translating a pathname.
 189 .It Bq Er EROFS
 190 In
 191 .Dv Q_QUOTAON ,
 192 the quota file resides on a read-only filesystem.
 193 .It Bq Er EIO
 194 An
 195 .Tn I/O
 196 error occurred while reading from or writing
 197 to a file containing quotas.
 198 .It Bq Er EFAULT
 199 An invalid
 200 .Fa addr
 201 was supplied; the associated structure could not be copied in or out
 202 of the kernel.
 203 .It Bq Er EFAULT
 204 .Fa Path
 205 points outside the process's allocated address space.
 206 .It Bq Er EPERM
 207 The call was privileged and the caller was not the super-user.
 208 .El
 209 .Sh SEE ALSO
 210 .Xr quota 1 ,
 211 .Xr fstab 5 ,
 212 .Xr edquota 8 ,
 213 .Xr quotacheck 8 ,
 214 .Xr quotaon 8 ,
 215 .Xr repquota 8
 216 .Sh BUGS
 217 There should be some way to integrate this call with the resource
 218 limit interface provided by
 219 .Xr setrlimit 2
 220 and
 221 .Xr getrlimit 2 .
 222 .Sh HISTORY
 223 The
 224 .Fn quotactl
 225 function call appeared in
 226 .Bx 4.3 Reno .