access() — Determine whether a file can be accessed

Standards

Standards / Extensions	C or C++	Dependencies
ISO C XPG4 XPG4.2 C99 Single UNIX Specification, Version 3	both

Format

#define _POSIX_SOURCE
#include <unistd.h>

int access(const char *pathname, int how);

General description

Determines how an HFS file can be accessed. When checking to see if a process has appropriate permissions, access() looks at the real user ID (UID) and group ID (GID), not the effective IDs.

pathname is the name of the file whose accessibility you want to test. The how argument indicates the access modes you want to test. The following symbols are defined in the unistd.h header file for use in the how argument:

F_OK: Tests whether the file exists.
R_OK: Tests whether the file can be accessed for reading.
W_OK: Tests whether the file can be accessed for writing.
X_OK: Tests whether the file can be accessed for execution.

You can take the bitwise inclusive-OR of any or all of the last three symbols to test several access modes at once. If you are using F_OK to test for the file's existence, you cannot use OR with any of the other symbols.

Returned value

If the specified access is permitted, access() returns 0.

If the given file cannot be accessed in the specified way, access() returns -1 and sets errno to one of the following values:

Error Code: Description
EACCES: The process does not have appropriate permissions to access the file in the specified way, or does not have search permission on some component of the pathname prefix.
EINVAL: The value of how is incorrect.
ELOOP: A loop exists in the symbolic links.
ENAMETOOLONG: pathname is longer than PATH_MAX characters. The PATH_MAX value is determined using pathconf().
ENOENT: There is no file named pathname, or the pathname argument is an empty string.
ENOTDIR: Some component of the pathname prefix is not a directory.
EROFS: The argument how has specified write access for a file on a read-only file system.

Returned value for POSIX C

The following errno values behave differently when a program is running with POSIX(ON):

Error Code: Description
ELOOP: A loop exists in the symbolic links. This error is issued if the number of symbolic links detected in the resolution is greater than POSIX_SYMLOOP (a value defined in the limits.h header file).
ENAMETOOLONG: pathname is longer than PATH_MAX characters, or some component of pathname is longer than NAME_MAX, when _POSIX_NO_TRUNC (defined in the unistd.h header file) is in effect. The PATH_MAX and NAME_MAX values are determined using pathconf().

Example

CELEBA03

⁄* CELEBA03

   The following example determines how a file is accessed.

 *⁄
#define _POSIX_SOURCE
#include <stdio.h>
#undef _POSIX_SOURCE
#include <unistd.h>

main() {
  char path[]="⁄";

  if (access(path, F_OK) != 0)
    printf("'%s' does not exist!\n", path);
  else {
    if (access(path, R_OK) == 0)
      printf("You have read access to '%s'\n", path);
    if (access(path, W_OK) == 0)
      printf("You have write access to '%s'\n", path);
    if (access(path, X_OK) == 0)
      printf("You have search access to '%s'\n", path);
  }
}

Output: From a non-superuser:

You have read access to '/'
You have search access to '/'