quotactl.2

   1 .TH QUOTACTL 2
   2 .SH NAME
   3 quotactl \- manipulate disk quotas
   4 .SH SYNOPSIS
   5 .nf
   6 .B #include <sys/quota.h>
   7 .B #include <xfs/xqm.h>
   8 .LP
   9 .B long quotactl(int cmd, char \(**special, qid_t id, caddr_t addr)
  10 .fi
  11 .SH DESCRIPTION
  12 .LP
  13 .IX  "filesystem"  "quotactl() disk quotas"  ""  "\fLquotactl()\fP \(em disk quotas"
  14 .IX  "quotactl() disk quotas"  ""  "\fLquotactl()\fP \(em disk quotas"
  15 .IX  "disk quotas quotactl()"  ""  "disk quotas \(em \fLquotactl()\fP"
  16 .LP
  17 The
  18 .B quotactl(\|)
  19 call manipulates disk quotas.
  20 .I cmd
  21 indicates a command to be applied to
  22 .SM UID
  23 .IR id
  24 or
  25 .SM GID
  26 .IR id .
  27 To set the type of quota use the
  28 .IR "QCMD(cmd, type)"
  29 macro.
  30 .I special
  31 is a pointer to a null-terminated string containing the path
  32 name of the block special device for the filesystem being manipulated.
  33 .I addr
  34 is the address of an optional, command specific, data structure
  35 which is copied in or out of the system.  The interpretation of
  36 .I addr
  37 is given with each command below.
  38 .TP 15
  39 .SB Q_QUOTAON
  40 Turn on quotas for a filesystem.
  41 .I id
  42 is the identification number of the quota format to be used. Format numbers
  43 are defined in the header file of appropriate format. Currently there are
  44 two supported quota formats whose numbers are defined by constants
  45 .IR QFMT_VFS_OLD
  46 (original quota format) and
  47 .IR QFMT_VFS_V0
  48 (new VFS v0 quota format).
  49 .IR addr
  50 points to the path name of file containing the quotas for the filesystem.
  51 The quota file must exist; it is normally created with the
  52 .BR quotacheck (8)
  53 program.  This call is restricted to the super-user.
  54 .TP
  55 .SB Q_QUOTAOFF
  56 Turn off quotas for a filesystem.
  57 .I addr
  58 and
  59 .I id
  60 are ignored.
  61 This call is restricted to the super-user.
  62 .TP
  63 .SB Q_GETQUOTA
  64 Get disk quota limits and current usage for user or group
  65 .IR id .
  66 .I addr
  67 is a pointer to an
  68 .B dqblk
  69 structure (defined in
  70 .BR <sys/quota.h> ).
  71 The field
  72 .I dqb_valid
  73 defines the entries in the structure which are set correctly. On
  74 .B Q_GETQUOTA
  75 call all entries are valid. Only the super-user may get the quotas
  76 of a user other than himself.
  77 .TP
  78 .SB Q_SETQUOTA
  79 Set current quota information for user or group
  80 .IR id .
  81 .I addr
  82 is a pointer to an
  83 .B dqblk
  84 structure (defined in
  85 .BR <sys/quota.h> ).
  86 The field
  87 .I dqb_valid
  88 defines which entries in the quota structure are valid and should be set. The constants for
  89 .I dqb_valid
  90 field are defined in the
  91 .B <sys/quota.h>
  92 header file. This call obsoletes calls
  93 .B Q_SETQLIM
  94 and
  95 .B Q_SETUSE
  96 in the previous quota interfaces. This call is restricted to the super-user.
  97 .TP
  98 .SB Q_GETINFO
  99 Get information (like grace times) about quotafile.
 100 .I addr
 101 should be a pointer to an
 102 .B dqinfo
 103 structure (defined in
 104 .IR <sys/quota.h> ).
 105 The
 106 .I dqi_valid
 107 field in the structure defines entries in it
 108 which are valid. On
 109 .B Q_GETINFO
 110 call all entries are valid.
 111 Parameter
 112 .I id
 113 is ignored.
 114 .TP
 115 .SB Q_SETINFO
 116 Set information about quotafile.
 117 .I addr
 118 should be a pointer to
 119 .B dqinfo
 120 structure (defined in
 121 .IR <sys/quota.h> ).
 122 The field
 123 .I dqi_valid
 124 defines which entries in the quota info structure are valid and should be set. The constants for
 125 .I dqi_valid
 126 field are defined in the
 127 .B <sys/quota.h>
 128 header file. This call obsoletes calls
 129 .B Q_SETGRACE
 130 and
 131 .B Q_SETFLAGS
 132 in the previous quota interfaces. Parameter
 133 .I id
 134 is ignored. This operation is restricted to super-user.
 135 .TP
 136 .SB Q_GETFMT
 137 Get quota format used on the specified filesystem.
 138 .I addr
 139 should be a pointer to a memory (4 bytes) where the format number will be stored.
 140 .TP
 141 .SB Q_SYNC
 142 Update the on-disk copy of quota usages for a filesystem.
 143 If
 144 .I special
 145 is null then all filesystems with active quotas are sync'ed.
 146 .I addr
 147 and
 148 .I id
 149 are ignored.
 150 .TP
 151 .SB Q_GETSTATS
 152 Get statistics and other generic information about quota subsystem.
 153 .I addr
 154 should be a pointer to
 155 .B dqstats
 156 structure (defined in
 157 .BR <sys/quota.h> )
 158 in which data should be stored.
 159 .I special
 160 and
 161 .I id
 162 are ignored. This call is obsolete and not supported by recent kernels.
 163 Files in
 164 .B /proc/sys/fs/quota/
 165 carry the information instead.
 166 .TP
 167 For XFS filesystems making use of the XFS Quota Manager (XQM), the above commands are bypassed and the following commands are used:
 168 .TP 15
 169 .SB Q_XQUOTAON
 170 Turn on quotas for an XFS filesystem.
 171 XFS provides the ability to turn on/off quota limit enforcement
 172 with quota accounting.
 173 Therefore, XFS expects the addr to be a pointer to an unsigned int
 174 that contains either the flags XFS_QUOTA_UDQ_ACCT and/or
 175 XFS_QUOTA_UDQ_ENFD (for user quota), or XFS_QUOTA_GDQ_ACCT and/or
 176 XFS_QUOTA_GDQ_ENFD (for group quota), as defined in
 177 .BR <xfs/xqm.h> .
 178 This call is restricted to the superuser.
 179 .TP
 180 .SB Q_XQUOTAOFF
 181 Turn off quotas for an XFS filesystem.
 182 As in Q_QUOTAON, XFS filesystems expect a pointer to an unsigned int
 183 that specifies whether quota accounting and/or limit enforcement need
 184 to be turned off.
 185 This call is restricted to the superuser.
 186 .TP
 187 .SB Q_XGETQUOTA
 188 Get disk quota limits and current usage for user
 189 .IR id .
 190 .I addr
 191 is a pointer to a
 192 .B fs_disk_quota
 193 structure (defined in
 194 .BR <xfs/xqm.h> ).
 195 Only the superuser may get the quotas of a user other than himself.
 196 .TP
 197 .SB Q_XSETQLIM
 198 Set disk quota limits for user
 199 .IR id .
 200 .I addr
 201 is a pointer to a
 202 .B fs_disk_quota
 203 structure (defined in
 204 .BR <xfs/xqm.h> ).
 205 This call is restricted to the superuser.
 206 .TP
 207 .SB Q_XGETQSTAT
 208 Returns a
 209 .B fs_quota_stat
 210 structure containing XFS filesystem specific quota information.
 211 This is useful in finding out how much space is spent to store quota
 212 information, and also to get quotaon/off status of a given local XFS
 213 filesystem.
 214 .TP
 215 .SB Q_XQUOTARM
 216 Free the disk space taken by disk quotas.
 217 Quotas must have already been turned off.
 218 .PP
 219 There is no command equivalent to
 220 .B Q_SYNC
 221 for XFS since
 222 .IR sync (1)
 223 writes quota information to disk (in addition to the other filesystem
 224 metadata it writes out).
 225 .SH RETURN VALUES
 226 .LP
 227 .B quotactl(\|)
 228 returns:
 229 .TP
 230 0
 231 on success.
 232 .TP
 233 \-1
 234 on failure and sets
 235 .B errno
 236 to indicate the error.
 237 .SH ERRORS
 238 .TP 15
 239 .SM EFAULT
 240 .I addr
 241 or
 242 .I special
 243 are invalid.
 244 .TP
 245 .SM ENOSYS
 246 The kernel has not been compiled with the
 247 .SB QUOTA
 248 option.
 249 .TP
 250 .SM EINVAL
 251 .IP
 252 .I cmd
 253 or
 254 .I type
 255 is invalid.
 256 .TP
 257 .SM ENOENT
 258 The file specified by
 259 .I special
 260 or
 261 .I addr
 262 does not exist.
 263 .TP
 264 .SM ENOTBLK
 265 .I special
 266 is not a block device.
 267 .TP
 268 .SM EPERM
 269 The call is privileged and the caller was not the super-user.
 270 .TP
 271 .SM ESRCH
 272 No disc quota is found for the indicated user. Quotas have not been turned on for this filesystem.
 273 .LP
 274 If
 275 .I cmd
 276 is
 277 .BR \s-1Q_SETQUOTA\s0 ,
 278 .B quotactl(\|)
 279 may also set errno to:
 280 .TP 15
 281 .SM ERANGE
 282 Specified limits are out of range allowed by quota format.
 283 .LP
 284 If
 285 .I cmd
 286 is
 287 .BR \s-1Q_QUOTAON\s0 ,
 288 .B quotactl(\|)
 289 may also set errno to:
 290 .TP 15
 291 .SM EACCES
 292 The quota file pointed to by
 293 .I addr
 294 exists but is not a regular file.
 295 .IP
 296 The quota file pointed to by
 297 .I addr
 298 exists but is not on the
 299 filesystem pointed to by
 300 .IR special .
 301 .TP
 302 .SM EINVAL
 303 The quota file is corrupted.
 304 .TP
 305 .SM ESRCH
 306 Specified quota format was not found.
 307 .TP
 308 .SM EBUSY
 309 .SB Q_QUOTAON
 310 attempted while another
 311 .SB Q_QUOTAON
 312 has already taken place.
 313 .SH "SEE ALSO"
 314 .BR quota (1),
 315 .BR getrlimit (2),
 316 .BR quotacheck (8),
 317 .BR quotaon (8)