openstat (BPX2OPN, BPX4OPS) — Open a file and obtain status information

Function

The openstat callable service gains access to a file, creates a file descriptor for it, and obtains its status.

Requirements

Operation Environment
Authorization: Supervisor state or problem state, any PSW key
Dispatchable unit mode: Task
Cross memory mode: PASN = HASN
AMODE (BPX2OPN): 31-bit
AMODE (BPX4OPS): 64-bit
ASC mode: Primary mode
Interrupt status: Enabled for interrupts
Locks: Unlocked
Control parameters: All parameters must be addressable by the caller and in the primary address space.

Format

CALL  BPX2OPN,(Pathname_length,
               Pathname,
               Options,
               Mode,
               Status_area_length,
               Status_area,
               Return_value,
               Return_code,
               Reason_code)

AMODE 64 callers use BPX4OPS with the same parameters.

Parameters

Pathname_length
Supplied parameter
Type:
Integer
Length:
Fullword

The name of a fullword that contains the length of the Pathname of the file that is to be opened.

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 name of the file that is to be opened. 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.
Options
Supplied parameter
Type:
Structure
Length:
Fullword

The name of a fullword that contains the binary flags that describe how the file is to be opened. For a description of the options, see the options described for the open callable service in Usage notes.

Options are mapped by the BPXYOPNF macro; see BPXYOPNF — Map flag values for open.

Mode
Supplied parameter
Type:
Structure
Length:
Fullword

The name of a fullword in which the mode field is specified. The mode field, which is mapped by BPXYMODE, specifies the file type and the permissions granted by the caller to itself, to its groups, and to any user. SeeBPXYFTYP — File type definitions.

Status_area_length
Supplied parameter
Type:
Integer
Length:
Fullword

The name of the fullword that contains the length of the Status_area parameter. To determine the value of Status_area_length, use the BPXYSTAT macro (see BPXYSTAT — Map the response structure for stat).

Status_area
Supplied and returned parameter
Type:
Structure
Length:
The length of BPXYSTAT or Status_area_length, whichever is less.

The name of an area to which the openstat service returns the status information for the file. Status_area is mapped by the BPXYSTAT macro (see BPXYSTAT — Map the response structure for stat).

Return_value
Returned parameter
Type:
Integer
Length:
Fullword

The name of a fullword in which the openstat service stores the file descriptor, if the file is opened successfully; or -1, if it is not successful.

Return_code
Returned parameter
Type:
Integer
Length:
Fullword

The name of a fullword in which the openstat service stores the return code. The openstat 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 openstat service can return one of the following values in the Return_code parameter:

Return_code Explanation
EACCES The calling process was denied access for one of the following reasons:
  • The calling process does not have permission to search one of the directories that was specified in the Pathname parameter.
  • The calling process does not have permission to open the file in the way that was specified on the Options parameter.
  • The file does not exist, and the calling process does not have permission to write into files in the directory in which the file would have been created.
  • The truncate option was specified, but the calling process does not have write permission for the file.
EAGAIN Resources were temporarily unavailable.
EBUSY The Pathname parameter specified a master pseudoterminal that is already in use, or for which the corresponding slave is open.
EEXIST The exclusive create option was specified, but the file already exists. The following reason code can accompany the return code: JRFileExistsExclFlagSet.
EFBIG A request to create a new file is prohibited because the file size limit for the process is set to 0.
EINTR

The openstat operation was interrupted by a signal.
EINVAL The Options parameter does not specify a valid combination of the O_RDONLY, O_WRONLY and O_TRUNC bits; or the file type that was specified in the Mode parameter is not valid. The following reason codes can accompany the return code: JRInvOpenFlags and JROpenFlagConflict.
EISDIR The file that is specified by Pathname is a directory, and the Options parameter specifies write or read/write access. The following reason code can accompany the return code: JRDirWriteRequest.
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.
EMFILE The process has reached the maximum number of file descriptors it can have open.
ENAMETOOLONG Pathname is longer than 1023 characters, or a component of the pathname is longer than 255 characters. Filename truncation is not supported.
ENFILE The maximum number of file descriptors that can be open has been reached.
ENODEV Typical causes:
  • An attempt was made to open a character special file for a device that is not supported.
  • An attempt was made to open a character special file for a device that is not yet initialized.

The following reason code can accompany the return code: JRNoCTTY.
ENOENT Typical causes:
  • The openstat request did not specify that the file was to be created, but the file that was named by Pathname was not found.
  • The openstat request specified that the file was to be created, but some component of Pathname was not found, or the Pathname parameter was blank.

The following reason codes can accompany the return code: JREndingSlashOCreat, JRNoFileNoCreatFlag, and JRQuiescing.
ENOSPC The directory or file system that was intended to hold a new file has insufficient space.
ENOTDIR A component of Pathname is not a directory.
ENXIO The openstat request specified write-only and nonblock for a FIFO special file, but no process has the file open for reading. For pseudoterminals, this could mean that the minor number that is associated with the pathname is too big.
EPERM The caller is not permitted to open the specified slave pseudoterminal; or the corresponding master is not yet open. EPERM is also returned if the slave is closed with HUPCL set and an attempt is made to reopen it.
EROFS The Pathname parameter names a file on a read-only file system, but options that would allow the file to be altered were specified: write-only, read/write, truncate, or (for a new file) create. The following reason codes can accompany the return code: JRReadOnlyFileSetWriteReq and JRReadOnlyFileSetCreatReq.
Reason_code
Returned parameter
Type:
Integer
Length:
Fullword

The name of a fullword in which the openstat service stores the reason code. The openstat 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

For information about opening and creating files, see open (BPX1OPN, BPX4OPN) — Open a file.

Related services

Characteristics and restrictions

See the usage notes.

Examples

For an example using this callable service, see BPX2OPN (openstat) example.

Parent topic: Callable services descriptions