access()--Determine File Accessibility

 #include <unistd.h>

 int access(const char *path, int amode);  

The access() function determines whether a file can be accessed in a particular manner. When checking whether a job has appropriate permissions, access() looks at the real user ID (UID) and group ID (GID), not the effective IDs. Adopted authority is not used.

Parameters

path

(Input) A pointer to the null-terminated path name for the file to be checked for accessibility.

This parameter is assumed to be represented in the CCSID (coded character set identifier) currently in effect for the job. If the CCSID of the job is 65535, this parameter is assumed to be represented in the default CCSID of the job.

const char *path is the name of the file whose accessibility you want to determine. If the named file is a symbolic link, access() resolves the symbolic link.

See QlgAccess-- Determine File Accessibility (using NLS-enabled path name) for a description and an example of supplying the path in any CCSID.

amode

(Input) A bitwise representation of the access permissions to be checked.

The following symbols, which are defined in the <unistd.h> header file, can be used in amode:

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 existence of the file, you cannot use OR with any of the other symbols. If any other bits are set in amode, access() returns the [EINVAL] error.

If the job has *ALLOBJ special authority, access() will indicate success for R_OK, W_OK, or X_OK even if none of the permission bits are set.

Authorities

Authorization Required for access()

Return Value

0

access() was successful.

-1

access() was not successful (the specified access is not permitted). The errno global variable is set to indicate the error.

Error Conditions

If access() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.

If interaction with a file server is required to access the object, errno could indicate one of the following errors:

Error Messages

The following messages may be sent from this function:

Usage Notes

1. This function will fail with error code [ENOTSAFE] when both of the following conditions occur:
   • Where multiple threads exist in the job.
     
   • The object this function is operating on resides in a file system that is not threadsafe. Only the following file systems are threadsafe for this function:
     • "Root" (/)
     • QOpenSys
     • User-defined
     • QNTC
     • QSYS.LIB
     • Independent ASP QSYS.LIB
     • QOPT
     • Network File System
     • QFileSvr.400
   
   
2. Network File System Differences

   Local access to remote files through the Network File System may produce unexpected results due to conditions at the server. Once a file is open, subsequent requests to perform operations on the file can fail because file attributes are checked at the server on each request. If permissions on the file are made more restrictive at the server or the file is unlinked or made unavailable by the server for another client, your operation on an open file descriptor will fail when the local Network File System receives these updates. The local Network File System also impacts operations that retrieve file attributes. Recent changes at the server may not be available at your client yet, and old values may be returned from operations. (Several options on the Add Mounted File System (ADDMFS) command determine the time between refresh operations of local data.)

   
   
3. QOPT File System Differences

   If the object exists on a volume formatted in Universal Disk Format (UDF), the authorization that is checked for the object and preceding directories in the path name follows the rules described in Authorization Required for access() . If the object exists on a volume formatted in some other media format, no authorization checks are made on the object or preceding directories. The volume authorization list is checked for the requested authority regardless of the volume media format.

Related Information

• The <unistd.h> file (see Header Files for UNIX-Type Functions)
  
• The <limits.h> file (see Header Files for UNIX-Type Functions)
  
• accessx()--Determine File Accessibility for Class of Users
  
• chmod()--Change File Authorizations
  
• faccessx()--Determine File Accessibility for Class of Users
  
• open()--Open File
  
• QlgAccess--Determine File Accessibility using NLS-enabled path name)
  
• QlgAccessx()--Determine File Accessibility for Class of Users (using NLS-enabled path name)
  
• stat()--Get File Information

Example

See Code disclaimer information for information pertaining to code examples.

The following example determines how a file is accessed:

#include <stdio.h>
#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:

The output from a user with read and execute access is:

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