Gets the access control information for a file system object.
Security Library (libc.a)
#include <sys/acl.h>int aclx_get (Path, ctl_flags, acl_type, acl, acl_sz, mode_info)
char * Path;
uint64_t ctl_flags;
acl_type_t * acl_type;
void * acl;
size_t * acl_sz;
mode_t * mode_info;int aclx_fget (FileDescriptor, ctl_flags, acl_type, acl, acl_sz, mode_info)
int FileDescriptor;
uint64_t ctl_flags;
acl_type_t * acl_type;
void * acl;
size_t * acl_sz;
mode_t * mode_info;The aclx_get and aclx_fget subroutines retrieve the access control information for a file system object in the native ACL format. Native ACL format is the format as defined for the particular ACL type in the system. These subroutines are advanced versions of the acl_get and acl_fget subroutines and should be used instead of the older versions. The aclx_get and aclx_fget subroutines provide for more control for the user to interact with the underlying file system directly.
In the earlier versions (acl_get or acl_fget), OS libraries found out the ACL size from the file system and allocated the required memory buffer space to hold the ACL information. The caller does all this now with the aclx_get and aclx_fget subroutines. Callers are responsible for finding out the size and allocating memory for the ACL information, and later freeing the same memory after it is used. These subroutines allow for an acl_type input and output argument. The data specified in this argument can be set to a particular ACL type and a request for the ACL on the file system object of the same type. Some physical file systems might do emulation to return the ACL type requested, if the ACL type that exists on the file system object is different. If the acl_type pointer points to a data area with a value of ACL_ANY or 0, then the underlying physical file system has to return the type of the ACL associated with the file system object.
The ctl_flags parameter is a bit mask that allows for control over the aclx_get requests.
The value returned by these subroutines can be use as an argument to the aclx_get or aclx_fget subroutines to copy or restore the access control information.
| Item | Description |
|---|---|
| Path | Specifies the path name of the file system object. |
| FileDescriptor | Specifies the file descriptor of an open file. |
| ctl_flags | This 64-bit sized bit mask provides control over the ACL
retrieval. The following flag value is defined:
|
| acl_type | Points to a buffer that will hold ACL type information. The
ACL type is 64 bits in size and is unique on the system. The caller
can provide an ACL type in this area and a request for the ACL on
the file system object of the same type. If the ACL type requested
does not match the one on the file system object, the physical file
system might return an error or emulate and provide the ACL information
in the ACL type format requested. If the caller does not know the
ACL type and wants to retrieve the ACL associated with the file system
object, then the caller should set the buffer value pointed to by acl_type to ACL_ANY or
0. The supported ACL types are ACLX and NFS4. |
| acl | Points to a buffer where the ACL retrieved is stored. The size of this buffer is indicated by the acl_sz parameter. |
| acl_sz | Indicates the size of the buffer area passed through the acl parameter. |
| mode_info | Pointer to a buffer where the mode word associated with the file system object is returned. Note that this mode word's meaning and formations depend entirely on the ACL type concerned. |
On successful completion, the aclx_get and aclx_get subroutines return a value of 0. Otherwise, -1 is returned and the errno global variable is set to indicate the error.
The aclx_get subroutine fails if one or more of the following is 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 aclx_fget subroutine fails if the following is true:
| Item | Description |
|---|---|
| EBADF | The FileDescriptor parameter is not a valid file descriptor. |
The aclx_get or aclx_fget subroutine fails if one or more of the following is true:
| Item | Description |
|---|---|
| EINVAL | Invalid input parameter. The same error can be returned if an invalid acl_type is specified as input to this routine. |
| EIO | An I/O error occurred during the operation. |
| ENOSPC | Input buffer size acl_sz is not sufficient to store the ACL data in acl. |
If Network File System (NFS) is installed on your system, the aclx_get and aclx_fget subroutines can also fail if the following condition is true:
| Item | Description |
|---|---|
| ETIMEDOUT | The connection timed out. |
Access Control: The invoker must have search permission for all components of the Path prefix.
Auditing Events: None