aclipc(S)

aclipc -- get or set an IPC object's ACL, return the number of ACL entries

Synopsis

   #include <sys/types.h>
   #include <acl.h>
   
   int aclipc(int type, int id, int cmd,
   	int nentries, struct acl *aclbufp);

Description

aclipc gets or sets an IPC object's ACL, or returns the number of ACL entries. To get the ACL, the user must have read access to the object. To set an ACL, the user must be the owner or creator of the object or have the P_OWNER privilege.

nentries

specifies how many ACL entries fit into buffer aclbufp.

aclbufp

is a pointer to the acl struct which contains the following fields:

   	int	a_type;	/* entry type */
   	uid_t	a_id;	/* user or group ID */
   	ushort	a_perm;	/* entry permissions */

The values for a_type are:

USER_OJB: Permissions for the owner of the object.
USER: Permissions for additional users.
GROUP_OBJ: Permissions for members of the owning group of the object.
GROUP: Permissions for members of additional groups.
CLASS_OBJ: Maximum permissions granted to the file group class.
OTHER_OBJ: Permissions for other users.

type

must be one of the following:

IPC_SHM: id must be a valid shared memory identifier returned by shmget.
IPC_SEM: id must be a valid semaphore identifier returned by semget.
IPC_MSG: id must be a valid message queue identifier returned by msgget.

cmd

must be one of the following:

ACL_GET: The ACL information for the IPC object specified by type and id is copied into the user supplied buffer aclbufp . nentries specifies the number of ACL entries that will fit into aclbufp. The user must have read access to the IPC object.
ACL_SET: The ACL for the IPC object specified by type and id is set to the ACL entries in the user supplied buffer aclbufp. nentries specifies the number of ACL entries currently in aclbufp. The entries in aclbufp must be valid and in the proper ACL order [see acl(S)]. The user must have P_OWNER privilege, or be the creator or owner of the object, to alter the IPC object.
ACL_CNT: Returns the number of ACL entries for the IPC object specified by type and id nentries and aclbufp are ignored. The user must have read access to the IPC object.

When the ACL for an IPC object is set, the permission mode (in ipc_perm) may change. The first three bits of the permission mode are set to the permissions of the object user entry. The middle three bits of the permission mode are set to the ORed value of the permissions for the additional users, object group, and additional group entries. The last three bits of the permission mode are set to the permissions of the other entry. See intro(S) for a description of ipc_perm. See acl(S) for a description of ACLs.

For cmd ACL_SET, the aclipc call will succeed if all of the following are true:

There is exactly one entry each of type USER_OBJ, GROUP_OBJ, CLASS_OBJ, and OTHER_OBJ.
Entries of type USER or GROUP may not contain duplicate entries. A duplicate entry is one of the same type containing the same numeric ID.
If an ACL contains no entries of type USER and no entries of type GROUP, then the entries of type GROUP_OBJ and CLASS_OBJ must have the same permissions.

Return values

On success, aclipc returns the number of ACL entries for cmd ACL_CNT and ACL_GET, and 0 for cmd ACL_SET. On failure, aclipc returns -1 and sets errno to identify the error.

Errors

In the following conditions, aclipc fails and sets errno to:

EINVAL: type is not one of IPC_SHM, IPC_SEM, or IPC_MSG.
EINVAL: id is not a valid type identifier.
EINVAL: cmd is not one of ACL_GET, ACL_SET, or ACL_CNT.
EINVAL: cmd is ACL_SET and the ACL entries in aclbufp are not valid or in proper order.
EPERM: cmd is ACL_SET and the user does not have P_OWNER privilege and is neither the creator nor owner of the IPC object.
EINVAL: cmd is ACL_SET and the security level of the calling process is not equal to the security level of the IPC object.
EINVAL: cmd is ACL_GET or ACL_CNT and the security level of the calling process is dominated by the security level of the IPC object.
EACCES: cmd is ACL_GET or ACL_CNT and the user does not have discretionary read access to the IPC object.
ENOSPC: cmd is ACL_GET and the number of ACL entries for the IPC object exceeds nentries.
ENOSPC: cmd is ACL_SET and nentries is greater than the tunable parameter aclmax.
EINVAL: cmd is ACL_SET and the number of ACL entries is less than the number of mandatory ACL entries (4).
EFAULT: cmd is ACL_GET and an attempt is made to copy ACL entries beyond the user's address space; this is possible if nentries is larger than the number of ACL entries that aclbufp can hold.
EFAULT: cmd is ACL_SET and an attempt is made to copy from outside the user's address space.

References

acl(S), aclsort(S), intro(S), msgget(S), semget(S), shmget(S)