acl_put or acl_fput Subroutine

Purpose

Sets AIXC ACL type access control information of a file.

Library

Security Library (libc.a)

Syntax

#include <sys/access.h>

int acl_put (PathAccessFree)
char * Path;
char * Access;
int  Free;

int acl_fput (FileDescriptorAccessFree)
int  FileDescriptor;
char * Access;
int  Free;

Description

The acl_put and acl_fput subroutines set the access control information of a file system object. This information is contained in a buffer returned by a call to the acl_get or acl_fget subroutine. The structure of the data in this buffer is unspecified. However, the entire Access Control List (ACL) for a file cannot exceed one memory page (4096 bytes) in size. Note that acl_put/acl_fput operation could fail if the existing ACL associated with the file system object is of a different kind or if the underlying physical file system does not support AIXC ACL type. It is recommended that applications make use of aclx_put and aclx_fput subroutines to set the ACL instead of acl_put/acl_fput routines.

Parameters

Item Description
Path Specifies the path name of a file.
FileDescriptor Specifies the file descriptor of an open file.
Access Specifies a pointer to the buffer containing the access control information.
Free Specifies whether the buffer space is to be deallocated. The following values are valid:
0
Space is not deallocated.
1
Space is deallocated.

Return Values

On successful completion, the acl_put and acl_fput subroutines return a value of 0. Otherwise, -1 is returned and the errno global variable is set to indicate the error.

Error Codes

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

Item Description
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.
ELOOP Too many symbolic links were encountered in translating the Path parameter.
ENAMETOOLONG A component of the Path parameter exceeded 255 characters, or the entire Path parameter exceeded 1023 characters.
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.
ENOENT A symbolic link was named, but the file to which it refers does not exist.
ENOTDIR A component of the Path prefix is not a directory.
ESTALE The process' root or current directory is located in a virtual file system that has been unmounted.

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

Item Description
EBADF The FileDescriptor parameter is not a valid file descriptor.

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

Item Description
EINVAL The Access parameter does not point to a valid access control buffer.
EINVAL The Free parameter is not 0 or 1.
EIO An I/O error occurred during the operation.
EROFS The named file resides on a read-only file system.

If Network File System (NFS) is installed on your system, the acl_put and acl_fput 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:

Item Description
Event Information
chacl Path
fchacl FileDescriptor