Changes the permissions on a file.
Standard C Library (libc.a)
#include <sys/acl.h> #include <sys/mode.h>
int chacl ( Path, ACL, ACLSize)
struct acl *ACL;
int fchacl ( FileDescriptor, ACL, ACLSize)
struct acl *ACL;
The chacl and fchacl subroutines set the access control attributes of a file according to the Access Control List (ACL) structure pointed to by the ACL parameter.
|Path||Specifies the path name of the file.|
|ACL||Specifies the ACL to be established on the file. The format of an
ACL is defined in the sys/acl.h file and contains the
The following bits in the acl_mode member are defined in the sys/mode.h file and are significant for this subroutine:
Other bits in the mode, including the following, are ignored:
The members for the base ACL (owner, group, and others) can contain the following bits, which are defined in the sys/access.h file:
|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.
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.
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.
The chacl subroutine
fails and the access control information for a file remains unchanged if one
or more of the following are true:
|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:
|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
|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:
|ETIMEDOUT||The connection timed out.|
Access Control: The invoker must have search permission for all components of the Path prefix.
These subroutines are part of Base Operating System (BOS) Runtime.
The acl_chg (acl_chg or acl_fchg Subroutine) subroutine, acl_get (acl_get or acl_fget Subroutine) subroutine, acl_put (acl_put or acl_fput Subroutine) subroutine, acl_set (acl_set or acl_fset Subroutine) subroutine, chmod (chmod or fchmod Subroutine) subroutine, stat subroutine, statacl subroutine.
The aclget command, aclput command.
List of Security and Auditing Subroutines and Subroutines Overview in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.