Jump to content United States-English
HP.com Home Products and Services Support and Drivers Solutions How to Buy
» Contact HP
More options
HP.com home
HP-UX Reference > G

getaccess(2)

HP-UX 11i Version 3: February 2007
» 

Technical documentation

» Feedback
Content starts here

 » Table of Contents

 » Index

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 existing 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 sysconf(_SC_NGROUPS_MAX) + 1. 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 negative 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.

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 inappropriate for the caller to learn anything about the file.)

Comparison of access and getaccess

The following table compares various attributes of access() and getaccess().

access()getaccess()
Checks all ACL entries (HFS and JFS File Systems only)Same
Uses real uid, real gid, and supplementary groups listUses specified uid and groups list; macros available for typical values
Checks specific mode value, returns succeed or failReturns all mode bits, each on or off
Checks path to file using caller's effective IDsSame
W_OK false if shared-text file currently being executedSame
W_OK false if file on read-only file systemSame
X_OK not modified for file currently open for writingSame
R_OK and W_OK always true for superuser (except as described in Security Restrictions) or users with DAC_READ and DAC_WRITE privileges.Same
X_OK always true for superuser or users with DAC_READ and DAC_WRITE privileges. See privileges(5) for more information about privileged access on systems that support fine-grained privileges.X_OK true for superuser or users with DAC_READ and DAC_WRITE privilege if file is not a regular:file or execute is set in. See privileges(5) for more information about privileged access on systems that support fine-grained privileges.

Security Restrictions

If the caller's user ID is 0, or has the DACREAD and DACWRITE privilege, 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.

See privileges(5) for more information about privileged access on systems that support fine-grained privileges.

RETURN VALUE

getaccess() returns the following values:

>0

Successful completion. Returns a non-negative value representing the access rights of the specified user to the specified file.

-1

Failure. errno is set to indicate the error.

ERRORS

getaccess() fails if any of the following conditions are encountered:

EACCES

A component of the path prefix denies search permission to the caller.

EFAULT

path or gidset points outside the allocated address space of the process. The reliable detection of this error is implementation dependent.

EINVAL

ngroups is invalid; ngroups is either zero, an unrecognized negative value, or a value larger than sysconf(_SC_NGROUPS_MAX) + 1.

EINVAL

gidset contains an invalid group ID value.

EINVAL

The value of label or privs is not a null pointer.

ELOOP

Too many symbolic links were encountered in translating the path name.

ENAMETOOLONG

The length of the specified path name exceeds PATH_MAX bytes, or the length of a component of the path name exceeds NAME_MAX bytes while _POSIX_NO_TRUNC is in effect.

ENOENT

The named file does not exist (for example, path is null or a component of path does not exist).

ENOTDIR

A component of the path prefix is not a directory.

EOPNOTSUPP

getaccess() is not supported on some types of remote files.

EXAMPLES

The following call determines the caller's effective access rights to file test and succeeds if the user has read access:

#include <unistd.h> #include <sys/getaccess.h> int mode; mode = getaccess ("test", UID_EUID, NGROUPS_EGID_SUPP, (int *) 0, (void *) 0, (void *) 0); if ((mode >= 0) && (mode & R_OK)) ...

Here is one way to test access rights to file /tmp/hold for user ID 23, group ID 109:

int gid = 109; int mode; mode = getaccess ("/tmp/hold", 23, 1, & gid, (void *) 0, (void *) 0);

Should the need arise, the following code builds a gidset that includes the process's effective group ID:

#include <sys/types.h> #include <unistd.h> gid_t *gidset; int ngroups; int ngroups_max; ngroups_max = sysconf(_SC_NGROUPS_MAX) + 1; gidset = (gid_t *)malloc(ngroups_max * sizeof(gid_t)); gidset[0] = getegid(); ngroups = 1 + getgroups (ngroups_max - 1, &gidset[1]);

AUTHOR

getaccess() was developed by HP.

Printable version
Privacy statement Using this site means you accept its terms Feedback to webmaster
© 1983-2007 Hewlett-Packard Development Company, L.P.