Usage notes

This service is intended only for use by a z/OS® UNIX System Services file system and by z/OS UNIX System Services servers. The service contains support for z/OS UNIX System Services servers, but cannot be directly invoked by an z/OS UNIX System Services server.

An access list may contain a maximum of 1024 entries.

R_setfacl will manage the bit in the File Security Packet (FSP) which indicates the presence of an ACL of a given type. That is, when an ACL is successfully added (by using either the add or modify operation), R_setfacl will turn on the appropriate bit in IFSP_FLAG2 (either IFSP_Access_Acl, IFSP_File_Model_Acl, or IFSP_Dir_Model_Acl). For a delete operation, or an add or modify operation which results in an empty ACL, RACF® will turn off the appropriate bit in IFSP_FLAG2 .

When a modify operation is specified, requests to delete ACL entries are processed before requests to add or modify entries.

If a modify operation is specified and an ACL does not exist, it will be created. Likewise, if a modify request for a specific ACL entry is specified, and that entry does not exist, it will be created.

If a delete request is specified, but an ACL does not exist, the request will be ignored. Likewise, if a delete request for a specific ACL entry is specified, and that entry does not exist, it will be ignored.

If an add request is specified, and an ACL already exists, it will be replaced in accordance with the contents of the RACL_Edit structure pointed to by the ACL_Update parameter. If there is no RACL_Edit in this context, the existing ACL will be deleted.

If a delete request is specified, and a RACL_Edit structure is also contained within the structure pointed to by the ACL_Update parameter, then the RACL_Edit is ignored and the ACL is deleted.

An audit record (or records) is optionally written, depending on the audit options in effect for the system.

The parameter list passed to this service is a variable-length (VL) parameter list. The high-order bit of the last field must be set to mark the end of the parameter list.

The caller must pass in the length and address of a buffer which contains the ACL being modified, or in which a new ACL is to be created. The buffer must be large enough to contain the maximum size ACL. The length and address fields are contained within the CRED, and different field names are used depending on which ACL is being created, modified, or deleted. For an access ACL, use CredAccAcl and CredAccAclLen. For a directory model ACL, use CredDirModelAcl and CredDirModelAclLen. For a file model ACL, use CredFileModelAcl and CredFileModelAclLen.

R_setfacl will perform validation on the ACL passed into the service as part of the RACL_Edit parameter of IRRPCOMP. An error in this ACL will result in a SAF return code 8, RACF return code 8, and RACF reason code 16 (decimal). If an error is detected, the FACL_ErrOff field within this ACL mapping will be updated with the offset (from the start of the header) to the header field or ACL entry in error. Some of the items validated are: eye catcher = "FACL", version = 1, length is large enough to contain the number of entries specified in FACL_Num_Entry, the ACL contains at least one entry, ACL entry type is 1 or 2, and UID/GID value is greater than or equal to 0.

An error with the input parameter list will result in a SAF return code 8, RACF return code 8, and RACF reason code 24 (decimal). Some of the items validated are: all addresses in the parameter list are non-zero, the variable-length parameter list bit is set, the ACL_Update_Length parameter specifies a length which is large enough to contain the ACL_Update area, the operation type and ACL type specified in the ACL_Update area are valid, and the pointers in the CRED which point to ACL buffers are non-zero and point to an area which is large enough to contain the ACL.