statacl or fstatacl Subroutine

Base Operating System and Extensions Technical Reference, Volume 2

statacl or fstatacl Subroutine

Purpose

Retrieves the access control information for a file.

Library

Standard C Library (libc.a)

Syntax

#include <sys/acl.h>
#include <sys/stat.h>

int statacl (Path, Command, ACL, ACLSize)
char *Path;
int Command;
struct acl *ACL;
int ACLSize;

int fstatacl (FileDescriptor, Command, ACL, ACLSize)
int FileDescriptor;
int Command;
struct acl *ACL;
int ACLSize;

Description

The statacl and fstatacl subroutines return the access control information for a file system object.

Parameters

Path

Specifies a pointer to the path name of a file.

FileDescriptor

Specifies the file descriptor of an open file.

Command

Specifies the mode of the path interpretation for Path, specifically whether to retrieve information about a symbolic link or mount point. Valid values for the Command parameter are defined in the stat.h file and include:

STX_LINK
STX_MOUNT
STX_NORMAL

ACL

Specifies a pointer to a buffer to contain the Access Control List (ACL) of the file system object. The format of an ACL is defined in the sys/acl.h file and includes the following members:

`acl_len`	Size of the Access Control List (ACL). Note: The entire ACL for a file cannot exceed one memory page (4096 bytes).
`acl_mode`	File mode. Note: The valid values for the `acl_mode` are defined in the sys/mode.h file.
`u_access`	Access permissions for the file owner.
`g_access`	Access permissions for the file group.
`o_access`	Access permissions for default class others.
`acl_ext[ ]`	An array of the extended entries for this access control list.

The members for the base ACL (owner, group, and others) may 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.

ACLSize

Specifies the size of the buffer to contain the ACL. If this value is too small, the first word of the ACL is set to the size of the buffer needed.

Return Values

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

Error Codes

The statacl subroutine fails 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 fstatacl subroutine fails if the following is true:

EBADF

The file descriptor FileDescriptor is not valid.

The statacl or fstatacl subroutine fails if one or more of the following are true:

EFAULT	The ACL parameter points to a location outside of the allocated address space of the process.
EINVAL	The Command parameter is not a value of STX_LINK, STX_MOUNT, STX_NORMAL.
ENOSPC	The ACLSize parameter indicates the buffer at ACL is too small to hold the Access Control List. In this case, the first word of the buffer is set to the size of the buffer required.
EIO	An I/O error occurred during the operation.

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

ETIMEDOUT

The connection timed out.

Implementation Specifics

These subroutines are part of Base Operating System (BOS) Runtime.

Related Information

The chacl subroutine, stat subroutine.

The acl_chg subroutine, acl_get subroutine, acl_put subroutine, acl_set subroutine.

The aclget command, aclput command, chmod command.

List of Security and Auditing Subroutines and Subroutines Overview in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.