lib/libc/sys/quotactl.2

   1 .\"     $NetBSD: quotactl.2,v 1.23 2004/05/13 10:20:58 wiz 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. Neither the name of the University nor the names of its contributors
  18 .\"    may be used to endorse or promote products derived from this software
  19 .\"    without specific prior written permission.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  24 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31 .\" SUCH DAMAGE.
  32 .\"
  33 .\"     @(#)quotactl.2  8.2 (Berkeley) 3/10/95
  34 .\"
  35 .Dd October 9, 2008
  36 .Dt QUOTACTL 2
  37 .Os
  38 .Sh NAME
  39 .Nm quotactl
  40 .Nd manipulate filesystem quotas
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  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 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 The address of an optional command specific data structure,
  60 .Fa addr ,
  61 may be given; its interpretation
  62 is discussed below with each command.
  63 .Pp
  64 Currently quotas are supported only for the ``ffs''
  65 and ``lfs'' filesystem.
  66 For both of them,
  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 ``ffs'' and ``lfs'' specific commands are:
  73 .Bl -tag -width Q_QUOTAON
  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 (defined in
 107 .Aq Pa ufs/ufs/quota.h ) .
 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 (defined in
 116 .Aq Pa ufs/ufs/quota.h ) .
 117 The usage fields of the
 118 .Fa dqblk
 119 structure are ignored.
 120 This call is restricted to the super-user.
 121 .It Dv Q_SETUSE
 122 Set disk usage 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 .Aq Pa ufs/ufs/quota.h ) .
 130 Only the usage fields are used.
 131 This call is restricted to the super-user.
 132 .It Dv Q_SYNC
 133 Update the on-disk copy of quota usages.
 134 The command type specifies which type of quotas are to be updated.
 135 The
 136 .Fa id
 137 and
 138 .Fa addr
 139 parameters are ignored.
 140 .El
 141 .Sh RETURN VALUES
 142 A successful call returns 0,
 143 otherwise the value \-1 is returned and the global variable
 144 .Va errno
 145 indicates the reason for the failure.
 146 .Sh ERRORS
 147 A
 148 .Fn quotactl
 149 call will fail if:
 150 .Bl -tag -width Er
 151 .It Bq Er EOPNOTSUPP
 152 The kernel has not been compiled with the
 153 .Dv QUOTA
 154 option.
 155 .It Bq Er EUSERS
 156 The quota table cannot be expanded.
 157 .It Bq Er EINVAL
 158 .Fa cmd
 159 or the command type is invalid.
 160 .It Bq Er EACCES
 161 In
 162 .Dv Q_QUOTAON ,
 163 the quota file is not a plain file, or
 164 search permission is denied for a component of a path prefix.
 165 .It Bq Er ENOTDIR
 166 A component of a path prefix was not a directory.
 167 .It Bq Er ENAMETOOLONG
 168 A component of a pathname exceeded
 169 .Dv {NAME_MAX}
 170 characters, or an entire path name exceeded
 171 .Dv {PATH_MAX}
 172 characters.
 173 .It Bq Er ENOENT
 174 A filename does not exist.
 175 .It Bq Er ELOOP
 176 Too many symbolic links were encountered in translating a pathname.
 177 .It Bq Er EROFS
 178 In
 179 .Dv Q_QUOTAON ,
 180 the quota file resides on a read-only filesystem.
 181 .It Bq Er EIO
 182 An
 183 .Tn I/O
 184 error occurred while reading from or writing
 185 to a file containing quotas.
 186 .It Bq Er EFAULT
 187 .Fa path
 188 points outside the process's allocated address space, or
 189 an invalid
 190 .Fa addr
 191 was supplied; the associated structure could not be copied in or out
 192 of the kernel.
 193 .It Bq Er EPERM
 194 The call was privileged and the caller was not the super-user.
 195 .El
 196 .Sh SEE ALSO
 197 .Xr quota 1 ,
 198 .Xr fstab 5 ,
 199 .Xr edquota 8 ,
 200 .Xr quotacheck 8 ,
 201 .Xr quotaon 8 ,
 202 .Xr repquota 8
 203 .Sh HISTORY
 204 The
 205 .Fn quotactl
 206 function call appeared in
 207 .Bx 4.3 Reno .
 208 .Sh BUGS
 209 There should be some way to integrate this call with the resource
 210 limit interface provided by
 211 .Xr setrlimit 2
 212 and
 213 .Xr getrlimit 2 .