access (BPX1ACC, BPX4ACC) — Determine if a file can be accessed

Function

The access callable service determines whether the caller can access a file. You identify the file by its pathname.

Requirements

Parameters

Pathname_length

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains the length of the pathname of the file.

Pathname

Supplied parameter

Type:

Character string

Character set:

No restriction

Length:

Specified by the Pathname_length parameter

The name of a field that contains the pathname of the file to be checked for accessibility. The length of this field is specified in Pathname_length.

Pathnames can begin with or without a slash.

• A pathname that begins with a slash is an absolute pathname. The slash refers to the root directory. The search for the file starts at the root directory.
• A pathname that does not begin with a slash is a relative pathname. The search for the file starts at the working directory.

Access_mode

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword field that indicates the accessibility to be tested. This field is mapped by the BPXYACC macro. The values for this field are:

ACC_F_OK

Test for file existence. This is the default value.

ACC_R_OK

Test for permission to read.

ACC_W_OK

Test for permission to write.

ACC_X_OK

Test for permission to execute or search.

ACCWAIT

If an asynchronous mount is in progress, wait for it to complete.

ACCDEVNO

Return the devno of the file in Return_value.

ACCEFFID

Use the effective ID rather than the real ID to check for permission.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the access service returns 0 if the request completes successfully (that is, the file exists or access is permitted), or -1 if the request is not successful, or the file cannot be accessed in the specified way.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the access service stores the return code. The access service returns Return_code only if Return_value is -1. See z/OS UNIX System Services Messages and Codes for a complete list of possible return code values. The access service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EACCES	The calling process does not have appropriate permissions to access the file in the ways specified by the Access_Mode parameter, or does not have search permission for some component of the Pathname prefix.
EINVAL	The Access_Mode parameter is incorrect. The following reason code unique to the access service can accompany the return code: JRInvalidAMODE.
ELOOP	A loop exists in symbolic links that were encountered during resolution of the Pathname argument. This error is issued if more than 24 symbolic links are detected in the resolution of Pathname.
ENAMETOOLONG	Pathname is longer than 1023 characters, or some component of the pathname is longer than 255 characters. Name truncation is not supported.
ENOENT	No file named Pathname was found, or no Pathname was specified. The following reason code unique to the access service can accompany the return code: JRFileNotThere.
ENOTDIR	A component of the Pathname prefix is not a directory.
EROFS	The Access_Mode parameter is testing for write access to a read-only file system. The following reason code unique to the access service can accompany the return code: JRReadOnlyFS.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword where the access service stores the reason code. The access service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. See z/OS UNIX System Services Messages and Codes for the reason codes.

Usage notes

1. Testing for file permission is based on the real user ID (UID) and real group ID (GID), unless the ACCEFFID bit has been set on. In that case, the effective ID is used for the test.
2. The caller can test for the existence of a file, or for access to the file, but not for both.
3. In testing for permission, the caller can test for any combination of read, write, and execute permission. If the caller is testing a combination of permissions, Return_value indicates failure if any one of the accesses is not permitted.
4. If the caller has appropriate privileges (see Authorization), the access test is successful even if the permission bits are off, except when testing for execute permission. When the caller tests for execute permission, at least one of the execute permission bits must be on for the test to be successful.
5. If the Access_mode parameter is zero, the service performs the existence test, ACC_F_OK.

Related services

• chmod (BPX1CHM, BPX4CHM) — Change the mode of a file or directory
• open (BPX1OPN, BPX4OPN) — Open a file
• stat (BPX1STA, BPX4STA) — Get status information about a file by pathname

Characteristics and restrictions

There are no restrictions on the use of the access service.