unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (HP-UX-11.11)
Page:
Section:
Apropos / Subsearch:
optional field



 getaccess(2)							getaccess(2)




 NAME
      getaccess - get a user's effective access rights to a file

 SYNOPSIS
      #include <&lt&lt&lt;sys/getaccess.h>&gt&gt&gt;

      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
      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 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.



 Hewlett-Packard Company	    - 1 -   HP-UX Release 11i: November 2000






 getaccess(2)							getaccess(2)




      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 inappropriate 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().

	   access()			      getaccess()
      +=================================================================+
      | checks all ACL entries	       |   same				|
      | (HFS and JFS File Systems only)|				|
      +-----------------------------------------------------------------+
      | uses real uid, real gid, and   |   uses specified uid and groups|
      | supplementary groups list      |   list; macros available	|
      |				       |   for typical values		|
      +-----------------------------------------------------------------+
      | checks specific mode value,    |   returns all mode bits, each	|
      | returns succeed or fail	       |   on or off			|
      +-----------------------------------------------------------------+
      | checks path to file using      |   same				|
      | caller's effective ID	       |				|
      +-----------------------------------------------------------------+
      | W_OK false if shared-text      |   same				|
      | file currently being executed  |				|
      +-----------------------------------------------------------------+
      | W_OK false if file on	       |   same				|
      | read-only file system	       |				|
      +-----------------------------------------------------------------+
      | X_OK not modified for file     |   same				|
      | currently open for writing     |				|



 Hewlett-Packard Company	    - 2 -   HP-UX Release 11i: November 2000






 getaccess(2)							getaccess(2)




      +-----------------------------------------------------------------+
      | R_OK and W_OK always true for  |   same				|
      | superuser (except as above)    |				|
      +-----------------------------------------------------------------+
      | X_OK always true for	       |   X_OK true for super-user	|
      | superuser		       |   if file is not a regular	|
      |				       |   file OR execute is set in	|
      |				       |   any ACL entry		|
      +-----------------------------------------------------------------+

 RETURN VALUE
      Upon successful completion, getaccess() returns a non-negative value
      representing the access rights of the specified user to the specified
      file.  If an error occurs, a value of -1 is returned and 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 NGROUPS + 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.




 Hewlett-Packard Company	    - 3 -   HP-UX Release 11i: November 2000






 getaccess(2)							getaccess(2)




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

	   #include <&lt&lt&lt;unistd.h>&gt&gt&gt;
	   #include <&lt&lt&lt;sys/getaccess.h>&gt&gt&gt;

	   int mode;
	   mode = getaccess ("test", UID_EUID, NGROUPS_EGID_SUPP,
		  (int *) 0, (void *) 0, (void *) 0);
	   if ((mode >&gt&gt&gt;= 0) &&amp&amp&amp;&&amp&amp&amp; (mode &&amp&amp&amp; 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, &&amp&amp&amp; gid,
		  (void *) 0, (void *) 0);

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

	   #include <limits.h>
	   int gidset [NGROUPS_MAX + 1];
	   int ngroups;

	   gidset [0] = getegid();
	   ngroups = 1 + getgroups (NGROUPS_MAX, & gidset [1]);

 AUTHOR
      getaccess() was developed by HP.

 SEE ALSO
      access(2), acl(2), chmod(2), getacl(2), setacl(2), stat(2), acl(5),
      aclv(5), unistd(5).

















 Hewlett-Packard Company	    - 4 -   HP-UX Release 11i: November 2000