open (BPX1OPN, BPX4OPN) — Open a file

Function

The open callable service gains access to a file and creates a file descriptor for it.

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 name of the file to be opened. The length of this field is specified in Pathname_length.

Path names can begin with or without a slash.

• A path name that begins with a slash is an absolute pathname. The slash refers to the root directory, and the search for the file starts at the root directory.
• A path name 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 descriptions of the options, see 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 the caller grants to itself, to its groups, and to any user. See BPXYMODE — Map the mode constants of the file services.

If create or exclusive create is not specified on the Options parameter, the Mode parameter is ignored.

The file type is mapped by the BPXYFTYP macro; see BPXYFTYP — File type definitions.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the open service stores the file descriptor if the file was 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 open service stores the return code. The open service returns Return_code only if Return_value is -1. For a list of return code values, see Return codes (errnos) in z/OS UNIX System Services Messages and Codes. The open service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EACCES	Reasons for being denied access include these: The calling process does not have permission to search one of the directories specified in the Pathname parameter. The calling process does not have permission to open the file in the way specified by the Options parameter. The file does not exist, and write permission for the parent directory in which the file would have been created is denied to the calling process. The truncate option was specified, but the process does not have write permission for the file.
EAGAIN	Resources were temporarily unavailable.
EBUSY	The path name specifies a master pseudoterminal that is either already in use or for which the corresponding slave is open, or the file is open by a remote NFS client with a share reservation that conflicts with the requested operation
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 open 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 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 either reached the maximum number of file descriptors it can have open, or the current pipe limit was exceeded. Refer to the reason code that was provided.
ENAMETOOLONG	The path name is longer than 1023 characters, or a component of the path name is longer than 255 characters. File names cannot be truncated.
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 request did not specify that the file was to be created, but the file named by Pathname was not found. The request asked for the file 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 intended to hold a new file has insufficient space.
ENOTDIR	A component of Pathname is not a directory.
ENXIO	The open request specified write-only and nonblock for a FIFO special file, but no process has the file open for reading. For pseudoterminals, it can mean that the minor number 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 open service stores the reason code. The open service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. For a list of reason codes, see Reason codes in z/OS UNIX System Services Messages and Codes.

Usage notes

1. When a file is created with the Create or Exclusive_create options of the Options parameter, the file permission bits as specified in the Mode parameter are modified by the process's file creation mask (see umask (BPX1UMK, BPX4UMK) — Set the file mode creation mask), and then used to set the file permission bits of the file that is being created.
   The file's owner ID is set to the process's effective user ID (UID). By default, the owning GID is set to that of the parent directory. However, if the FILE.GROUPOWNER.SETGID profile exists in the UNIXPRIV class, the owning GID is determined by the set-gid bit of the parent directory, as follows:

   • If the parent's set-gid bit is on, the owning GID is set to that of the parent directory.
   • If the parent's set-gid bit is off, the owning GID is set to the effective GID of the process.
2. Exclusive Create Option: If the exclusive create bit is set and the create bit is not set, the exclusive create bit is ignored.
3. Truncate Option: Turning on the truncate bit opens the file as though it had been created earlier, but never written into. The mode and owner of the file do not change (although the change time and modification time do); but the file's contents are discarded. The file offset, which indicates where the next write is to occur, points to the first byte of the file.
4. Nonblock Option: A FIFO special file is a shared file from which the first data written is the first data read. The Nonblock option is a way of coordinating write and read requests between processes that share a FIFO special file. Provided that no other conditions interfere with opening the file successfully, it works as follows:
   • If a file is opened read-only and Nonblock is specified, the open request succeeds. Control returns to the caller immediately.
   • If a file is opened write-only and Nonblock is specified, the open request completes successfully, provided that another process has the file open for reading. If another process does not have the file open for reading, the request ends with Return_value set to -1.
   • If a file is opened read-only and Nonblock is omitted, the request is blocked (control is not returned to the caller) until another process opens the file for writing.
   • If a file is opened write-only and Nonblock is omitted, the request is blocked (control is not returned to the caller) until another process opens the file for reading.
5. Synchronous Update Option: When this bit is set, the program is assured that all data updates have been written to permanent storage.
6. Sharing files with NFS clients on Windows workstations: Some remote NFS clients can open files on ø in such a way that no one else can open that file until the first program has finished and closed the file. This is done through the use of share reservations that prohibit others from concurrently opening the same file in certain ways. The share reservations are: Deny_Read, Deny_Write, Deny_Both, and Deny_None. If a file is open by an NFS client and a subsequent attempt to open it for reading or writing is made which is currently denied by the NFS client's share reservation, the open request will either block or return with EBUSY, depending on the O_NonBlock option that was specified. Conversely, if a file is open by a local program and an NFS client then attempts to open it and deny the type of access that is already established, the client's open request will fail.

Related services

• close (BPX1CLO, BPX4CLO) — Close a file
• exec (BPX1EXC, BPX4EXC) — Run a program
• fcntl (BPX1FCT, BPX4FCT) — Control open file descriptors
• lseek (BPX1LSK, BPX4LSK) — Change a file's offset
• read (BPX1RED, BPX4RED) — Read from a file or socket
• stat (BPX1STA, BPX4STA) — Get status information about a file by path name
• write (BPX1WRT, BPX4WRT) — Write to a file or a socket
• umask (BPX1UMK, BPX4UMK) — Set the file mode creation mask

Characteristics and restrictions

See Usage notes.

MVS-related information

The Execution access requested bit is used by the exec service (see exec (BPX1EXC, BPX4EXC) — Run a program) to verify that the process has permission to run the specified file. When the open service succeeds, the specified file is treated as read-only for this case.