filepriv(S)

filepriv -- set, retrieve, or count the privileges associated with a file

Synopsis

   #include <sys/types.h>
   #include <priv.h>
   
   int filepriv(const char *path, int cmd, priv_t *privp, int nentries);

Description

The filepriv system call is used to set, retrieve, or count the privileges associated with a file. privp is defined as a pointer to an array of privilege descriptors each of which contains a privilege set and the identity of the requested privilege.

The path argument specifies an executable file. nentries is the number of entries contained in privp.

When setting privileges, filepriv changes the kernel privilege table, but not the Privilege Data File (PDF) file that is used to initialize privileges at system startup time. Privileges changed with filepriv are valid only until the next reboot, at which time the changes are lost and the privileges are as defined in the PDF.

The recognized cmds and their functions are described below:

PUTPRV: the fixed and inheritable privilege sets associated with the file indicated by path are set based on the privilege descriptor(s) contained in privp. The fixed and inheritable privilege sets resulting from the privilege descriptor(s) contained in privp must be disjoint. Privileges contained in either privilege set that are not in the maximum set of the calling process are ignored. The calling process must have the either the P_SETSPRIV privilege or the P_SETUPRIV privilege in its working set; if the privilege is P_SETUPRIV, the process must also have write access to the file named by path. If any argument is invalid, none of the file privileges is changed. The setting is absolute.
GETPRV: the fixed and inheritable privilege sets associated with the file indicated by path are returned in privp in the form of privilege descriptors. The calling process must have read access to the file named by path. None of the file privileges is changed.
CNTPRV: the return value is set to the number of privileges associated with the named file. The privp and nentries arguments are ignored. The calling process must have read access to the file named by path. None of the file privileges is changed.

Return values

On success, filepriv returns the number of privilege file descriptors. On failure, filepriv returns -1 and sets errno to identify the error.

Errors

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

ENOENT: A component of path does not exist.
ENOTDIR: A component of path is not a directory.
EINVAL: The cmd is invalid.
EINVAL: The cmd is GETPRV and privp is not large enough to hold the number of privileges associated with the named file.
EINVAL: The cmd is PUTPRV and (1) the file pointed to by path is not a regular executable file, (2) the fixed and inheritable privilege sets are not disjoint, (3) nentries is less than 0, or (4) privp includes undefined privileges.
EINVAL: The cmd is GETPRV or CNTPRV and the file pointed to by path is not a regular executable file.
EFAULT: An internal routine to retrieve file privileges or copy privileges to the calling process failed.
EACCES: The cmd is GETPRV or CNTPRV and the calling process does not have read access to the file named by path.
EACCES: The cmd is SETPRV, the calling process has only the P_SETUPRIV privilege, and write access is denied on the file named by path.
EPERM: The calling process does not have the P_SETSPRIV or the P_SETUPRIV privilege.
EAGAIN: There is insufficient kernel memory to allocate a privilege table entry when setting file privileges.
ENOPKG: The filepriv system call is not supported by the installed privilege mechanism.

References

intro(S), procpriv(S), procprivl(S), priv(M), privilege(M)