acl_set_file() — Set an ACL by file name

Standards

Standards / Extensions C or C++ Dependencies

z/OS UNIX

 both z/OS V1R3

Format

#define _OPEN_SYS	1
#include <sys/acl.h>

int     acl_set_file (char *path_p, acl_type_t type_d, lacl_t acl_d, short OpType,
		acl_entry_t *entry_p);

General description

Use access control lists (ACLs) in conjunction with permission bits to control access to files and directories. Currently, ACLs are supported by the HFS, TFS, and zFS file systems. You must know whether your security product supports ACLs and what rules are used when determining file access. See z/OS UNIX System Services Planning for details.

The acl_set_file() function associates the type_d ACL with the object referred to by file name path_p. The effective UID of the subject must match the owner of the object or the subject must have appropriate privileges.

If the type_d is the directory/file default and the object referred to by file name path_p is not a directory, then the function will fail.

The acl_set_file() function will succeed only if the ACL is valid as defined by the acl_valid() function.

Upon successful completion, acl_set_file() will set the ACL of the object. For type_d = ACL_ACCESS, acl_set_file() will also set the base ACL entries. The base ACL entries only apply to ACl_ACCESS ACL type, so for any other type the base ACL entries are ignored.

The OpType determines whether the ACL is updated or replaced.
OpType
Action
ACL_ADD
replace the whole ACL with the given extended and base ACL entries
ACL_MODIFY
update the ACL with the given extended and/or base ACL entries (if individual extended ACL entries are marked for deletion, then ACL_MODIFY removes them)
ACL_DELETE
delete from the ACL the specified extended ACL entries; marks the individual extended ACL entries for deletion (cannot delete base ACL entries)
If Optype is ACL_MODIFY, the setting will modify the existing extended ACL entries and add new ones if they do not exist. Both ACL entry's mask and value are used to determine ACL entry's permission to set.

If OpType is ACL_ADD, the existing ACL is replaced by the new one. Only extended ACL entry's value is used to determine permissions to set. The object's previous ACL will no longer be in effect. If the object had no ACL, a new one is added for both ACL_MODIFY and ACL_ADD.

Similarly, for OpType = ACL_ADD, base ACL entries are replaced with the new values specified (mask field is ignored). All three base ACL entries (ACL_USER, ACL_GROUP, and ACL_OTHER) must be specified. For OpType = ACL_MODIFY, the base ACL entries are modified with the specified values (both mask and value fields are used).

For Optype = ACL_MODIFY only the base ACL entries to be changed need to be specified. The Optype = ACL_DELETE does not apply to base ACL entries since they cannot be removed. Every file always has base ACL entries.

If the acl_set_file() is unsuccessful, the ACL of the object referred to by argument path_p is not changed.

The ordering of entries within ACL referred to by acl_d may be changed. The first call to acl_get_entry() following the call to acl_set_file() obtains the first extended ACL entry as ordered by the system.

Returned value

Upon successful completion, the function returns a value of zero.

If any of the following conditions occur, the acl_set_file() function will return a value of -1 and set errno to the corresponding value:

Error Code
Description
EACCES
Search permission is denied for a component of the path prefix or the object exists and the subject does not have appropriate access rights.
E2BIG
The ACL has more extended ACL entries than are allowed.
ENOENT
The named object does not exist or the path_p argument points to an empty string.
EBADF
The fd argument is not a valid file descriptor.
EINVAL
Argument acl_d does not point to a valid ACL structure.
ENOSPC
The directory or file system that would contain the new ACL cannot be extended or the file system is out of space.
ENOTDIR
The type_d specified was directory/file default but the argument path_p does not refer to a directory.
ENAMETOOLONG
The length of the path name argument exceeds PATH_MAX, or a path name component is longer than NAME_MAX and {_POSIX_NO_TRUNC} is in effect for that file. For symbolic links, the length of the path name string substituted for a symbolic link exceeds PATH_MAX. PATH_MAX and NAME_MAX values can be determined by using pathconf().
EMVSERR
Other internal RACF® error (more information in errno2)

The function will return -2 and set errno to EINVAL if the base ACL entry is not unique or is not a valid type or for ACL_ADD, there are less than 3 base ACL entries. The entry_p will be NULL.

The function will return -3 and set errno to EINVAL if the extended ACL entry is not unique or is not a valid type. The entry_p, if not NULL, will point to the extended ACL entry in error.

Related information

Parent topic: Library functions