quotactl Subroutine

Purpose

Manipulates disk quotas.

Library

Standard C Library (libc.a)

Syntax

#include <sys/fs/quota_common.h>

int quotactl (Path, Cmd, ID, Addr) int Cmd, ID; char * Addr, * Path;

Description

The quotactl subroutine enables, disables, and manipulates disk quotas for file systems on which quotas have been enabled.

On AIX®, disk quotas are supported by the legacy Journaled File System (JFS) and the enhanced Journaled File System (JFS2).

The Cmd parameter is constructed through use of the QCMD(Qcmd, type) macro contained within the sys/fs/quota_common.h file. The Qcmd parameter specifies the quota control command. The type parameter specifies either user (USRQUOTA) or group (GRPQUOTA) quota type.

The valid values for the Cmd parameter in all supported file system types are:

Q_QUOTAON: Enables disk quotas for the file system specified by the Path parameter. The Addr parameter specifies a file from which to take the quotas. The quota file must exist; it is normally created with the quotacheck command. The ID parameter is unused. Root user authority is required to enable quotas. By specifying the new quota file path in the Addr parameter, the quotactl command can also be used to change the quota file that is being used without first disabling disk quotas.
Q_QUOTAOFF: Disables disk quotas for the file system specified by the Path parameter. The Addr and ID arguments are unused. Root user authority is required to disable quotas.

Additional JFS specific values for the Cmd parameter are as follows:

Q_GETQUOTA: Gets disk quota limits and current usage for a user or group specified by the ID parameter. The Addr parameter points to a dqblk buffer to hold the returned information. The dqblk structure is defined in the jfs/quota.h file. Root user authority is required if the ID value is not the current ID of the caller.
Q_SETQUOTA: Sets disk quota limits for the user or group specified by the ID parameter. The Addr parameter points to a dqblk buffer containing the new quota limits. The dqblk structure is defined in the jfs/quota.h file. Root user authority is required to set quotas.
Q_SETUSE: Sets disk usage limits for the user or group specified by the ID parameter. The Addr parameter points to a dqblk buffer containing the new usage limits. The dqblk structure is defined in the jfs/quota.h file. Root user authority is required to set disk usage limits.

Additional JFS2 specific values for the Cmd parameter are as follows:

Q_J2GETQUOTA: Gets quota limits, current usage, and time remaining in grace periods for the user or group specified by the ID parameter. The Addr parameter points to a quota64_t buffer to hold the returned information. The quota64_t structure is defined in the quota_common.h file. Root user authority is required if the ID value is not the current ID of the caller.
Q_J2PUTQUOTA: Updates (replaces) the current usage values for the user or group specified by the ID parameter. The Addr parameter points to a quota64_t buffer holding the new information. The quota64_t structure is defined in the quota_common.h file. Root user authority is required.
Q_J2GETLIMIT: Gets quota limits information for the Limits Class specified by the ID parameter. The Addr parameter points to a j2qlimit_t buffer to hold the returned information. The j2qlimit_t structure is defined in the j2/j2_quota.h file. Root user authority is required.
Q_J2PUTLIMIT: Updates quota limits information for the Limits Class specified by the ID parameter. The Addr parameter points to a j2qlimit_t buffer holding the new information. The j2qlimit_t structure is defined in the j2/j2_quota.h file. Root user authority is required.
Q_J2NEWLIMIT: Creates a new Limits Class and updates it with the quota limits information from Addr. The ID parameter is ignored. The Addr parameter points to a j2qlimit_t buffer holding the new information. The j2qlimit_t structure is updated with the new Limits Class ID and returned to the user. The j2qlimit_t structure is defined in the j2/j2_quota.h file. Root user authority is required.
Q_J2RMVLIMIT: Marks the Limits Class specified by the ID parameter as deleted. Any Usage record referencing a deleted Limits Class is now limited by the default Limits Class. The Addr parameter is ignored. Root user authority is required.
Q_J2DEFLIMIT: Sets the Limits Class specified by the ID parameter as the default Limits Class. The Addr parameter is ignored. Root user authority is required.
Q_J2USELIMIT: Binds a Usage record to the Limits Class specified by the ID parameter. The Limits Class must be valid; otherwise, ENOENT is returned. Use the Addr parameter to pass a pointer to the user ID or group ID. Root user authority is required.
Q_J2GETNEXTQ: Returns the ID of the next allocated, nondeleted Limits Class higher than the ID specified by the ID parameter. The Addr parameter points to a buffer containing a uid_t structure. Root user authority is required.
Q_J2INITFILE: Initializes an existing quota file. The Addr and ID parameters are ignored. Root user authority is required.
Q_J2QUOTACHK: Performs a consistency check on an existing quota file. If any of the control data within the file is invalid or inconsistent, Q_J2QUOTACHK attempts to reconstruct the control data based on existing quota data in the file. If no qwuota data can be recognized, the file is initialized. The Addr and ID parameters are ignored. Root user authority is required.
Q_J2DELQUOTA: Deletes the passed-in users or groups if there are no files owned by them. The space is returned to the quota file free list so it can be reused. The Addr parameter points to an array of qid_t elements, with at most MAXDELIDS elements. The ID parameter contains the count of the elements in the array. The qid_t type is defined in the j2/j2_quota.h file and the MAXDELIDS is defined in the sys/fs/quota_common.h file. Root user authority is required to delete quotas.

Parameters

Item	Description
Path	Specifies the path name of any file within the mounted file system to which the quota control command is to be applied. Typically, this would be the mount point of the file system.
Cmd	Specifies the quota control command to be applied and whether it is applied to a user or group quota.
ID	Specifies the user or group ID to which the quota control command applies. The ID parameter is interpreted by the specified quota type. The JFS file system supports quotas for IDs within the range of MINDQUID through MAXDQID; JFS2 supports all IDs.
Addr	Points to the address of an optional, command-specific, data structure that is copied in or out of the system. The interpretation of the Addr parameter for each quota control command is given above.

Return Values

A successful call returns 0; otherwise, the value -1 is returned and the errno global variable indicates the reason for the failure.

Error Codes

A quotactl subroutine will fail when one of the following occurs:

Item	Description
EACCES	In the Q_QUOTAON command, the quota file is not a regular file.
EACCES	Search permission is denied for a component of a path prefix.
EFAULT	An invalid Addr parameter is supplied; the associated structure could not be copied in or out of the kernel.
EFAULT	The Path parameter points outside the process's allocated address space.
EINVAL	The specified quota control command or quota type is invalid.
EINVAL	Path name contains a character with the high-order bit set.
EINVAL	The ID parameter is outside of the supported range of MINDQID through MAXDQID (JFS only).
EINVAL	The ID parameter is negative or larger than MAXDELIDS when deleting quota entries (JFS2 only).
EIO	An I/O error occurred while reading or writing the quotas file.
ELOOP	Too many symbolic links were encountered in translating a path name.
ENAMETOOLONG	A component of either path name exceeded 255 characters, or the entire length of either path name exceeded 1023 characters.
ENOENT	A file name does not exist.
ENOTBLK	Mounted file system is not a block device.
ENOTDIR	A component of a path prefix is not a directory.
EOPNOTSUPP	The file system does not support quotas.
EPERM	The quota control commands is privileged and the caller did not have root user authority.
EROFS	In the Q_QUOTAON command, the quota file resides on a read-only file system.
EUSERS	The in-core quota table cannot be expanded (JFS only).
ENOMEM	Unable to allocate memory.