acl(2)

NAME

acl() — set a file's Access Control List (ACL) information; JFS File Systems only

SYNOPSIS

#include <sys/types.h> 
#include <aclv.h> 
int acl(char *pathp, int cmd, int nentries, struct acl *aclbufp); 

DESCRIPTION

The acl() system call is used to manipulate ACLs on JFS file system objects.

pathp

points to a path name naming a file.

nentries

specifies how many ACL entries are pointed to by aclbufp.

aclbufp

is a pointer to the first element of an array of struct acl. This type is defined in <sys/acl.h> as follows:

struct acl { 
        int     a_type;        /* entry type */ 
        uid_t   a_id;          /* user or group ID */ 
        ushort  a_perm;        /* entry permissions */ 
}; 

The values for a_type are:

USER_OBJ: Permissions for the owner of the object.
USER: Permissions for additional users.
GROUP_OBJ: Permissions for members of the owning group of the object.
GROUP: Permissions for members of additional groups.
CLASS_OBJ: Maximum permissions granted to the file group class.
OTHER_OBJ: Permissions for other users.
DEF_USER_OBJ: Default permissions for the object owner.
DEF_USER: Default permissions for additional users.
DEF_GROUP_OBJ: Default permissions for members of the owning group of the object.
DEF_GROUP: Default permissions for members of additional groups
DEF_CLASS_OBJ: Default maximum permissions granted to the file group class.
DEF_OTHER_OBJ: Default permissions for other users.

cmd

The following values for cmd are available:

ACL_SET: nentries ACL entries, specified in buffer aclbufp, are stored in the file's ACL. Any existing ACL on the file is replaced by the new ACL. All directories in the path name must be searchable.
ACL_GET: Buffer aclbufp is filled with the file's ACL entries. Discretionary read access to the file is not required, but all directories in the path name must be searchable.
ACL_CNT: The number of entries in the file's ACL is returned. Discretionary read access to the file is not required, but all directories in the path name must be searchable.

For command ACL_SET, the acl() call will succeed if and only if all of the following are true:

There is exactly one entry each of type USER_OBJ, GROUP_OBJ, CLASS_OBJ, and OTHER_OBJ.
If pathp points to a directory, there is at most one entry each of type DEF_USER_OBJ, DEF_GROUP_OBJ, DEF_CLASS_OBJ, and DEF_OTHER_OBJ.
Entries of type USER, GROUP, DEF_USER, or DEF_GROUP do not contain duplicate entries. A duplicate entry is one of the same type containing the same numeric ID.
If the ACL contains no entries of type USER and no entries of type GROUP, then the entries of type GROUP_OBJ and CLASS_OBJ have the same permissions.
If the ACL contains no entries of type DEF_USER and no entries of type DEF_GROUP, and an entry of type DEF_GROUP_OBJ is specified, then an entry of type DEF_CLASS_OBJ is also specified and the two entries have the same permissions.

Security Restrictions

The ACL_SET value for cmd can only be executed by a process that has an effective user ID equal to the owner of the file, or by the superuser, or by a user with the OWNER privilege.

See privileges(5) for more information about privileged access on systems that support fine-grained privileges.

RETURN VALUE

acl() returns the following values:

n: Successful completion. Returns the number of ACL entries for cmd ACL_CNT and ACL_GET.
0: Successful completion. Returns 0 for cmd ACL_SET.
-1: Failure. errno is set to indicate the error.

ERRORS

If acl() fails, the ACL is unchanged, and errno is set to one of the following values:

EACCES: The caller does not have access to a component of the path name.
EINVAL: cmd is not ACL_GET, ACL_SET, or ACL_CNT.
EINVAL: cmd is ACL_SET and nentries is less than the number of mandatory ACL entries (4).
EINVAL: cmd is ACL_SET and the ACL specified in aclbufp is not valid (see above discussion, and aclsort(3C)).
EIO: A disk I/O error has occurred while storing or retrieving the ACL.
EPERM: cmd is ACL_SET and the effective user ID of the caller does not match the owner of the file, and the caller is not the superuser or a user with OWNER privilege.
ENOENT: A component of the path does not exist.
ENOSPC: cmd is ACL_GET and nentries is less than the number of entries in the file's ACL.
ENOSPC: cmd is ACL_SET and there is insufficient space to store the ACL.
ENOSPC: cmd is ACL_SET and nentries is greater than NACLVENTRIES, which is defined in <sys/aclv.h>.
ENOTDIR: A component of the path specified by pathp is not a directory.
ENOTDIR: cmd is ACL_SET and an attempt is made to set a default ACL on a file type other than a directory.
ENOSYS: cmd is ACL_SET, the file specified by pathp resides on a local non-JFS file system, and additional entries were specified in the ACL.
EOPNOTSUPP: cmd is ACL_SET, the file specified by pathp resides on a nonlocal file system, and additional entries were specified in the ACL.
EROFS: cmd is ACL_SET and the file specified by pathp resides on a file system that is mounted read-only.
EFAULT: aclbufp points to an illegal address.

acl(2)

Technical documentation

» Table of Contents

» Index