HP-UX Reference (11i v2 03/08) - 2 System Calls (vol 5)

g
getaccess(2) getaccess(2)
NAME
getaccess - get a user’s effective access rights to a file
SYNOPSIS
#include <sys/getaccess.h>
int getaccess(
const char *path,
uid_t uid,
int ngroups,
const gid_t *gidset,
void *label,
void *privs
);
DESCRIPTION
getaccess() identifies the access rights (read, write, execute/search) a specific user
ID has to an exist-
ing file. path points to a path name of a file. If the call succeeds, it returns a value of zero or greater,
representing the specified user’s effective access rights (modes) to the file. The rights are expressed as the
logical
OR of bits (R_OK, W_OK
, and X_OK) whose values are defined in the header <unistd.h>. A
return of zero means that access is denied.
The uid parameter is a user
ID. Special values, defined in <sys/getaccess.h
>, represent the calling
process’s effective, real, or saved user
ID:
UID_EUID Effective user ID.
UID_RUID Real user ID.
UID_SUID Saved user ID.
ngroups is the number of group IDs in gidset , not to exceed NGROUPS_MAX +1(
NGROUPS_MAX is
defined in <
limits.h>). If the ngroups parameter is positive, the gidset parameter is an array of group
ID values to use in the check. If ngroups is a recognized negative value, gidset is ignored. Special nega-
tive values of ngroups, defined in <sys/getaccess.h
>, represent various combinations of the
process’s effective, real, or saved user
ID and its supplementary groups list:
NGROUPS_EGID Use process’s effective group ID only.
NGROUPS_RGID Use process’s real group ID only.
NGROUPS_SGID Use process’s saved group ID only.
NGROUPS_SUPP Use process’s supplementary groups only.
NGROUPS_EGID_SUPP
Use process’s effective group ID plus supplementary groups.
NGROUPS_RGID_SUPP
Use process’s real group ID plus supplementary groups.
NGROUPS_SGID_SUPP
Use process’s saved group ID plus supplementary groups.
The label and privs parameters are placeholders for future extensions. For now, the values of these
parameters must be
(void *) 0.
The access check rules for access control lists are described in acl (5) and aclv (5). In addition, the
W_OK
bit is cleared for files on read-only file systems or shared-text programs being executed. Note that as in
access (2), the X_OK bit is not turned off for shared-text programs open for writing because there is no
easy way to know that a file open for writing is a shared-text program.
If the caller’s user
ID is 0, or if it is UID_EUID, UID_RUID,or UID_SUID (see <sys/getaccess.h
>)
and the process’s respective user
ID is 0, R_OK and W_OK are always set except when W_OK is cleared
for files on read-only file systems or shared-text programs being executed. X_OK is set if and only if the
file is not a regular file or the execute bit is set in any of the file’s ACL entries.
getaccess() checks each directory component of path by first using the caller’s effective user ID,
effective group ID, and supplementary groups list, regardless of the user ID specified. An error occurs,
distinct from ‘‘no access allowed,’’ if the caller cannot search the path to the file. (In this case it is inap-
propriate for the caller to learn anything about the file.)
Comparison of access(2) and getaccess(2)
The following table compares various attributes of
access() and getaccess().
Section 2−−78 Hewlett-Packard Company − 1 − HP-UX 11i Version 2: August 2003