open


>>-open--pathname--o_flags--+------+---------------------------><
                            '-mode-'

Function

open invokes the open callable service to access a file and create a file descriptor for it. The file descriptor is returned in RETVAL.

Parameters

pathname

A pathname for the file.

o_flags

One or more numeric values that describe how the file is to be opened. You can specify a numeric value (see REXX predefined variables) or any of the predefined variables that begin with O_ used to derive the appropriate numeric value. For example, the numeric values 128+3 or 131 or the predefined variables o_creat+o_rdwr could be used to specify how the file is to be opened:

Variable	Description
O_APPEND	Set the offset to EOF before each write.
O_CREAT	Create the file if it does not exist.
O_EXCL	Fail if the file does exist and O_CREAT is set.
O_NOCTTY	Do not make this file a controlling terminal for the calling process.
O_NONBLOCK	Do not block an open, a read, or a write on the file (do not wait for terminal input).
O_RDONLY	Open for read-only.
O_RDWR	Open for read and write.
O_SYNC	Force synchronous updates.
O_TRUNC	Write, starting at the beginning of the file.
O_WRONLY	Open for write-only.

mode

A three- or four-digit number, corresponding to the access permission bits. If this optional parameter is not supplied, the mode is defaulted to 000, which is useful for opening an existing file. For an explanation of how mode is handled if you are creating a file, see the usage notes below.

Each digit must be in the range 0–7, and at least three digits must be specified. For more information on permissions, see Setting permissions for files and directories.

Usage notes

When a file is created with the O_CREAT or O_EXCL options, the file permission bits as specified in the mode parameter are modified by the process's file creation mask (see umask), and then used to set the file permission bits of the file being created.

O_EXCL option: If the O_EXCL bit is set and the create bit is not set, the O_EXCL bit is ignored.

O_TRUNC option: Turning on the O_TRUNC 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.

O_NONBLOCK option: A FIFO special file is a shared file from which the first data written is the first data read. The O_NONBLOCK option is a way of coordinating write and read requests between processes sharing a FIFO special file. It works this way, provided that no other conditions interfere with opening the file successfully:

If a file is opened read-only and O_NONBLOCK is specified, the open request succeeds. Control returns to the caller immediately.
If a file is opened write-only and O_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 RETVAL set to -1.
If a file is opened read-only and O_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 O_NONBLOCK is omitted, the request is blocked (control is not returned to the caller) until another process opens the file for reading.
If the O_SYNC update option is used, the program is assured that all data updates have been written to permanent storage.

Example

To open or create the file /u/linda/my.exec with read-write-execute permission for the owner, and to read and write starting at the beginning of the file:

"open /u/linda/my.exec" o_rdwr+o_trunc+o_creat 700