The openstat callable service gains access to a file, creates a file descriptor for it, and obtains its status.
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. |
|
AMODE 64 callers use BPX4OPS with the same parameters.
The name of a fullword that contains the length of the Pathname of the file that is to be opened.
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.
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.
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.
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).
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).
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.
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:
|
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:
The following reason code can accompany the return code: JRNoCTTY. |
ENOENT | Typical causes:
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. |
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.
For information about opening and creating files, see open (BPX1OPN, BPX4OPN) — Open a file.
See the usage notes.
For an example using this callable service, see BPX2OPN (openstat) example.