vxfacl (3)

NAME

vxacl, vxfacl - get or set a VxFS file’s Access Control List entries

SYNOPSIS

cc -I /opt/VRTSvxfs/include -L /opt/VRTSvxfs/lib
-l vxfsutil -ldl

#include <sys/types.h>

#include <vxfsutil.h>

int vxacl(char *pathname, int cmd, int nentries, vx_aclent_t *aclbufp);

int vxfacl(int fd, int cmd, int nentries, void *aclbufp);

AVAILABILITY

VRTSvxfs

DESCRIPTION

The vxacl() and vxfacl() functions get and set the Access Control List (ACL) entries and return the count of ACL entries associated with a file on a VxFS file system.

The fields are:
pathname Pathname of the file.
fd Open file descriptor of the file.
cmd Command to perform. Possible values for cmd are:
SETACL Stores nentries ACL entries that are specified in aclbufp in the file’s ACL. Any existing ACL on the file is replaced by the new ACL. This command can only be executed by a process that has an effective user ID equal to the owner of the file.
GETACL Fills buffer aclbufp with the file’s ACL entries. Read access to the file is not required.
GETACLCNT Returns the number of entries in the file’s ACL. Read access to the file is not required.
All directories in the pathname must be searchable for all of the cmd values.
nentries Number of ACL entries to which buffer aclbufp points.
aclbufp A pointer to the first element of an array of type vx_aclent_t. An ACL consists of a set of entries of type vx_aclent_t. The vx_aclent_t type is defined in the vxfsutil.h header file as follows:

typedef struct {
        int             a_type; /* ACL entry type */
        uid_t           a_id;   /* UID or GID */
        unsigned short  a_perm; /* entry permissions */
        unsigned short  a_pad;
} vx_aclent_t;


The entries are:
a_id User ID or group ID.
a_perm Permissions that are set on a_type, specified by a number. The number is the same as the permission numbers used with the chmod command.
a_type Type of ACL entry. Possible values for a_type are:
VX_USER_OBJ Permissions for the file owner.
VX_USER Permissions for a specific user.
VX_GROUP_OBJ Permissions for the file group owner.
VX_GROUP Permissions for a specific group.
VX_CLASS_OBJ ACL mask. The mask entry specifies the maximum permissions allowed for users, other than the owner, and groups. The mask is a quick way to change permissions on all the users and groups.
VX_OTHER_OBJ Permissions for users other than the file owner or members of the file group owner.
ACL entries are further divided into default and non-default entries, distinguished by the VX_ACL_DEFAULT bit. For default entries the VX_ACL_DEFAULT bit is logically OR’ed (|) into the a_type field. Only directories can contain default entries. If a file or directory is created in a directory that contains default ACL entries, the newly created file has permissions generated according to the intersection of the default ACL entries and the permissions requested at creation time. The umask is not applied if the directory contains default ACL entries. If default ACL entries are given for a specific user or users, or specific group or groups, a regular ACL is created. Otherwise, only the mode bits are initialized according to the intersection described above. If the newly created file is a directory, the parent’s default ACL entries are inherited as defaults, and thus propagated down through the hierarchy. Default ACL entries are only used when creating files. The access rights to the directory are controlled by its mode bits and non-default ACL entries.

The SETACL command requires the ACL entries to be in the following order:

1. One VX_USER_OBJ entry.
2. Zero or more additional VX_USER entries.
3. One VX_GROUP_OBJ entry.
4. Zero or more additional VX_GROUP entries.
5. At most one VX_CLASS_OBJ entry.
6. One VX_OTHER_OBJ entry.

If pathname points to a directory and there are default ACL entries, then following order is valid:

1. At most one default VX_USER_OBJ entry.
2. Zero or more default additional VX_USER entries.
3. At most one default VX_GROUP_OBJ entry.
4. Zero or more default additional VX_GROUP entries.
5. At most one default VX_CLASS_OBJ entry.
6. At most one default VX_OTHER_OBJ entry.

If VX_USER or VX_GROUP entries are specified, then the VX_CLASS_OBJ entry must be specified. If default VX_USER or default VX_GROUP entries are specified, then the default VX_CLASS_OBJ entry must be specified.

Entries of type VX_USER, default VX_USER, VX_GROUP, and default VX_GROUP do not contain duplicate entries. A duplicate entry is an entry of the same type containing the same numeric ID.

If the ACL contains no VX_USER or VX_GROUP entries, and a VX_GROUP_OBJ entry is specified, then a VX_CLASS_OBJ entry is also specified and the two entries have the same permissions. If the ACL contains no default VX_USER or default VX_GROUP entries, and a default VX_GROUP_OBJ entry is specified, then a default VX_CLASS_OBJ entry is also specified and the two entries have the same permissions.

The default list must have either all of VX_USER_OBJ, VX_GROUP_OBJ, and VX_OTHER_OBJ type entries, or no entries of these types.

If any of the above rules are violated, the function fails with errno set to EINVAL.

RETURN VALUES

Upon successful completion, vxacl() and vxfacl() return the number of ACL entries for the GETACL and GETACLCNT commands, and 0 for the SETACL command. On failure, vxacl() and vxfacl() return -1 and set errno to indicate the error.

ERRORS

EACCES The caller does not have access to a component of the pathname.
EINVAL cmd is not GETACL, SETACL, or GETACLCNT.
EINVAL cmd is SETACL and the ACL specified in aclbufp is not valid.
EIO A disk I/O error has occurred while storing or retrieving the ACL.
EPERM cmd is SETACL and the effective user ID of the caller does not match the owner of the file, and the caller is not the superuser.
ENOENT A component of the pathname does not exist.
ENOSPC cmd is GETACL and nentries is less than the number of entries in the file’s ACL,
ENOSPC cmd is SETACL and there is insufficient space in the file system to store the ACL.
ENOTDIR A component of the path specified by pathname is not a directory, or an attempt was made to set a default ACL on a file type other than a directory.
ENOEXEC The vxfsacl.so shared library is not present.
ENOTSUP The vxacl() or vxfacl() API is not supported.
EROFS cmd is SETACL and the file specified by pathname resides on a read-only file system.
EFAULT The pathname or aclbufp argument points to an illegal address.

SEE ALSO

vxgetacl(1), vxsetacl(1)


VxFS 5.1 SP1 vxfacl (3)