chacl or fchacl Subroutine

Purpose

Changes the AIXC ACL type access control information of a file.

Library

Standard C Library (libc.a)

Syntax

#include <sys/acl.h>
#include <sys/mode.h>
int chacl ( Path,  ACL,  ACLSize)
char *Path;
struct acl *ACL;
int ACLSize;
int fchacl ( FileDescriptor, ACL, ACLSize)
int FileDescriptor;
struct acl *ACL;
int ACLSize;

Description

The chacl and fchacl subroutines set the access control attributes of a file according to the AIXC ACL Access Control List (ACL) structure pointed to by the ACL parameter. Note that these routines could fail if the current ACL associated with the file system object is of a different type or if the underlying physical file system does not support AIXC ACL type. It is strongly recommended that applications stop using these interfaces and instead make use of aclx_get /aclx_fget and aclx_put/aclx_fput subroutines to change the ACL.

Parameters

Item Description
Path Specifies the path name of the file.
ACL Specifies the AIXC ACL to be established on the file. The format of an AIXC ACL is defined in the sys/acl.h file and contains the following members:
acl_len
Specifies the size of the ACL (Access Control List) in bytes, including the base entries.

Note: The entire ACL for a file cannot exceed one memory page (4096 bytes).
acl_mode
Specifies the file mode.

The following bits in the acl_mode member are defined in the sys/mode.h file and are significant for this subroutine:

S_ISUID
Enables the setuid attribute on an executable file.
S_ISGID
Enables the setgid attribute on an executable file. Enables the group-inheritance attribute on a directory.
S_ISVTX
Enables linking restrictions on a directory.
S_IXACL
Enables extended ACL entry processing. If this attribute is not set, only the base entries (owner, group, and default) are used for access authorization checks.

Other bits in the mode, including the following, are ignored:

u_access
Specifies access permissions for the file owner.
g_access
Specifies access permissions for the file group.
o_access
Specifies access permissions for the default class of others.
acl_ext[]
Specifies an array of the extended entries for this access control list.

The members for the base ACL (owner, group, and others) can contain the following bits, which are defined in the sys/access.h file:

R_ACC
Allows read permission.
W_ACC
Allows write permission.
X_ACC
Allows execute or search permission.
FileDescriptor Specifies the file descriptor of an open file.
ACLSize Specifies the size of the buffer containing the ACL.
Note: The chacl subroutine requires the Path, ACL, and ACLSize parameters. The fchacl subroutine requires the FileDescriptor, ACL, and ACLSize parameters.

ACL Data Structure for chacl

Each access control list structure consists of one struct acl structure containing one or more struct acl_entry structures with one or more struct ace_id structures.

If the struct ace_id structure has id_type set to ACEID_USER or ACEID_GROUP, there is only one id_data element. To add multiple IDs to an ACL you must specify multiple struct ace_id structures when id_type is set to ACEID_USER or ACEID_GROUP. In this case, no error is returned for the multiple elements, and the access checking examines only the first element. Specifically, the errno value EINVAL is not returned for acl_len being incorrect in the ACL structure although more than one uid or gid is specified.

Return Values

Upon successful completion, the chacl and fchacl subroutines return a value of 0. If the chacl or fchacl subroutine fails, a value of -1 is returned, and the errno global variable is set to indicate the error.

Error Codes

The chacl subroutine fails and the access control information for a file remains unchanged if one or more of the following are true:

Item Description
ENOTDIR A component of the Path prefix is not a directory.
ENOENT A component of the Path does not exist or has the disallow truncation attribute (see the ulimit subroutine).
ENOENT The Path parameter was null.
EACCES Search permission is denied on a component of the Path prefix.
EFAULT The Path parameter points to a location outside of the allocated address space of the process.
ESTALE The process' root or current directory is located in a virtual file system that has been unmounted.
ELOOP Too many symbolic links were encountered in translating the Path parameter.
ENOENT A symbolic link was named, but the file to which it refers does not exist.
ENAMETOOLONG A component of the Path parameter exceeded 255 characters, or the entire Path parameter exceeded 1023 characters.

The chacl or fchacl subroutine fails and the access control information for a file remains unchanged if one or more of the following are true:

Item Description
EROFS The file specified by the Path parameter resides on a read-only file system.
EFAULT The ACL parameter points to a location outside of the allocated address space of the process.
EINVAL The ACL parameter does not point to a valid ACL.
EINVAL The acl_len member in the ACL is not valid.
EIO An I/O error occurred during the operation.
ENOSPC The size of the ACL parameter exceeds the system limit of one memory page (4KB).
EPERM The effective user ID does not match the ID of the owner of the file, and the invoker does not have root user authority.

The fchacl subroutine fails and the file permissions remain unchanged if the following is true:

Item Description
EBADF The file descriptor FileDescriptor is not valid.

If Network File System (NFS) is installed on your system, the chacl and fchacl subroutines can also fail if the following is true:

Item Description
ETIMEDOUT The connection timed out.

Security

Access Control: The invoker must have search permission for all components of the Path prefix.

Auditing Events:

Event Information
chacl Path
fchacl FileDescriptor