faccessx()--Determine File Accessibility for a Class of Users

 #include <unistd.h>

 int faccessx(int fildes, int amode, int who);  

The faccessx() function determines whether a file can be accessed by a specified class of users in a particular manner.

Adopted authority is not used.

Parameters

fildes

(Input) The file descriptor of the file that is having its accessibility checked.

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

(x'00') Tests whether the file exists

R_OK

(x'04') Tests whether the file can be accessed for reading

W_OK

(x'02') Tests whether the file can be accessed for writing

X_OK

(x'01') 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, faccessx() returns the [EINVAL] error.

who

(Input) The class of users whose authority is to be checked.

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

ACC_SELF

(x'00') Determines if specified access is permitted for the current thread. The effective user and group IDs are used.

Note: If the real and effective user ID are the same and the real and effective group ID are the same, the request is treated as ACC_INVOKER. See the Usage Notes for more details.

ACC_INVOKER

(x'01') Determines if specified access is permitted for the current thread. The effective user and group IDs are used.

ACC_OTHERS

(x'08') Determines if specified access is permitted for any user other than the object owner. Only one of R_OK, W_OK, and X_OK is permitted when who is ACC_OTHERS. Privileged users (users with *ALLOBJ special authority) are not considered in this check.

ACC_ALL

(x'20') Determines if specified access is permitted for all users. Only one of R_OK, W_OK, and X_OK is permitted when who is ACC_ALL. Privileged users (users with *ALLOBJ special authority) are not considered in this check.

Authorities

The following authorities are required if the who parameter is ACC_SELF or ACC_INVOKER. If ACC_SELF is specified, the effective UID and GID of the caller are used. If ACC_INVOKER is used, the real UID and GID of the caller are used.

Authorization Required for faccessx()

If the current thread has *ALLOBJ special authority, faccessx() with ACC_SELF or ACC_INVOKER will indicate success for R_OK, W_OK, or X_OK even if none of the permission bits are set.

Return Value

0

faccessx() was successful.

-1

faccessx() was not successful (or the specified access is not permitted for the class of users being checked). The errno global variable is set to indicate the error.

Error Conditions

If faccessx() 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. ACC_SELF Mapped to ACC_INVOKER

   Some physical file systems do not support ACC_SELF for the who parameter. However, faccessx() will change the who parameter from ACC_SELF to ACC_INVOKER if the caller's real and effective user ID are equal, and the caller's real and effective group ID are equal.

   
   
3. Network File System Differences

   The Network File System will only support the value ACC_INVOKER for the who parameter. If faccessx() is called on a file in a mounted Network File System directory with a value for who other than ACC_INVOKER, the call will return -1 and errno ENOTSUP. Note: If the value for who has been mapped from ACC_SELF to ACC_INVOKER as previously described, then ENOTSUP will not be returned.

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

   
   
4. QNTC File System Differences

   The QNTC File System will only support the value ACC_INVOKER for the who parameter. If faccessx() is called on a file in the QNTC File System with a value for who other than ACC_INVOKER, the call will return -1 and errno ENOTSUP.

   Note: If the value for who has been mapped from ACC_SELF to ACC_INVOKER as previously described, then ENOTSUP will not be returned.

   
   
5. QOPT File System Differences

   If the file descriptor refers to an object that exists on a volume formatted in Universal Disk Format (UDF), the authorization that is checked for the object follows the rules described in the previous table, Authorization Required for faccessx(). If the object exists on a volume formatted in some other media format, no authorization checks are made on the object. The volume authorization list is checked for the requested authority regardless of the volume media format.

   
   
6. QFileSvr.400 File System Differences
   
   

   The QFileSvr.400 File System will only support the value ACC_INVOKER for the who parameter. If faccessx() is called on a file in the QFileSvr.400 File System with a value for who other than ACC_INVOKER, the call will return -1 and errno ENOTSUP.

   Note: If the value for who has been mapped from ACC_SELF to ACC_INVOKER as previously described, then ENOTSUP will not be returned.

   
   
7. QNetWare File System Differences
   
   

   The QNetWare File System will only support the value ACC_INVOKER for the who parameter. If faccessx() is called on a file in the QNetWare File System with a value for who other than ACC_INVOKER, the call will return -1 and errno ENOTSUP.

   Note: If the value for who has been mapped from ACC_SELF to ACC_INVOKER as previously described, then ENOTSUP will not be returned.

Related Information

• The <unistd.h> file (see Header Files for UNIX-Type Functions)
• The <limits.h> file (see Header Files for UNIX-Type Functions)
• chmod()--Change File Authorizations
• open()--Open File
• access()--Determine File Accessibility
• accessx()--Determine File Accessibility for a Class of Users
• QlgAccessx()--Determine File Accessibility for a Class of Users (using NLS-enabled path name)
• QlgAccess()--Determine File Accessibility (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>
#include <fcntl.h>

main() {
  char path[]="/myfile";
  int fd;
  
  fd = open(path, O_RDONLY);
  if (fd == -1)
  {
    printf("Error opening file.\n");
    return;
  }
  
  if (faccessx(fd, R_OK, ACC_OTHERS) == 0)
      printf("Someone besides the owner has read access to '%s'\n", path);
  if (faccessx(fd, W_OK, ACC_OTHERS) == 0)
      printf("Someone besides the owner has write access to '%s'\n", path);
  if (faccessx(fd, X_OK, ACC_OTHERS) == 0)
      printf("Someone besides the owner has search access to '%s'\n", path);
  close(fd);
}

Output:

In this example faccessx() was called on a descriptor for '/myfile'. The following would be the output if someone other than the owner has *R authority, someone besides the owner has *W authority, and noone other than the owner has *X authority.

Someone besides the owner has read access to '/'
Someone besides the owner has write access to '/'