General description
Opens a
file and returns a number called a file descriptor.
The pathname argument
must be a z/OS UNIX file file name. You can use this file descriptor
to refer to the file in subsequent I/O operations, for example, read()
or write(). Each file opened by a process gets a new file descriptor.
Restriction: Using this function with FIFOs,
POSIX terminals, and character special files requires z/OS® XL C programs
running POSIX(ON).
The argument pathname is
a string giving the name of the file you want to open. The integer options specifies
options for the open operation by taking the bitwise inclusive-OR
of symbols defined in the fcntl.h header file. The options indicate
whether the file should be accessed for reading, writing, reading
and writing, and so on.
An additional argument (
...)
is required if the O_CREAT option is specified in
options.
This argument may be called the
mode and
has the
mode_t type. It specifies file permission
bits to be used when a file is created. All the file permission bits
are set to the bits of
mode, except for
those set in the file-mode creation mask of the process. Here is a
list of symbols that can be used for a mode.
- S_IRGRP
- Read permission for the file's group.
- S_IROTH
- Read permission for users other than the file owner.
- S_IRUSR
- Read permission for the file owner.
- S_IRWXG
- Read, write, and search or execute permission for the file's group.
S_IRWXG is the bitwise inclusive-OR of S_IRGRP, S_IWGRP, and S_IXGRP.
- S_IRWXO
- Read, write, and search or execute permission for users other
than the file owner. S_IRWXO is the bitwise inclusive-OR of S_IROTH,
S_IWOTH, and S_IXOTH.
- S_IRWXU
- Read, write, and search, or execute, for the file owner; S_IRWXG
is the bitwise inclusive-OR of S_IRUSR, S_IWUSR, and S_IXUSR.
- S_ISGID
- Privilege to set group ID (GID) for execution. When this file
is run through an exec function, the effective group ID of the process
is set to the group ID of the file, so that the process has the same
authority as the file owner rather than the authority of the actual
invoker.
- S_ISUID
- Privilege to set the user ID (UID) for execution. When this file
is run through an exec function, the effective user ID of the process
is set to the owner of the file, so that the process has the same
authority as the file owner rather than the authority of the actual
invoker.
- S_ISVTX
- Indicates shared text. Keep loaded as an executable file in storage.
- S_IWGRP
- Write permission for the file's group.
- S_IWOTH
- Write permission for users other than the file owner.
- S_IWUSR
- Write permission for the file owner.
- S_IXGRP
- Search permission (for a directory) or execute permission (for
a file) for the file's group.
- S_IXOTH
- Search permission for a directory, or execute permission for a
file, for users other than the file owner.
- S_IXUSR
- Search permission (for a directory) or execute permission (for
a file) for the file owner.
Most open operations position a
file
offset (an indicator showing where the next read or
write will take place in the file) at the beginning of the file; however,
there are options that can change this position. One of the following
must be
specified in the
options argument of the
open() operation:
- O_RDONLY
- Open for reading only
- O_WRONLY
- Open for writing only
- O_RDWR
- Open for both reading and writing
One or more of the following can also be specified
in
options:
- O_APPEND
- Positions the file offset at the end of the file before each write
operation.
- O_CREAT
- Indicates that the call to open() has a mode argument.
If the file being opened already exists O_CREAT has no effect
except when O_EXCL is also specified; see O_EXCL following.
If
the file being opened does not exist it is created. The user ID is
set to the effective ID of the process, and its group ID is set to
the group ID of its directory. File permission bits are set according
to mode.
If O_CREAT is specified
and the file did not previously exist a successful open() sets the
access time, change time, and modification time for the file. It
also updates the change time and modification time fields in the parent
directory.
- O_EXCL
-
If both O_EXCL and O_CREAT are specified open() fails if the
file already exists. If both O_EXCL and O_CREAT are specified and pathname names
a symbolic link open() fails regardless of the contents of the symbolic
link.
The check for the existence of the file and the creation
of the file if it does not exist is atomic with respect to other threads
executing open() naming the same filename in the same directory with
O_EXCL and O_CREAT set.
- O_NOCTTY
- If pathname specifies a terminal open()
does not make the terminal the controlling terminal of the process
(and the session). If O_NOCTTY is not specified the terminal becomes
the controlling terminal if the following conditions are true:
- The process is a session leader.
- There is no controlling terminal for the session.
- The terminal is not already a controlling terminal for another
session.
- O_NONBLOCK
- Has different meanings depending on the situation.
- When you are opening a FIFO special file with O_RDONLY or O_WRONLY:
If
O_NONBLOCK is specified a read-only open() returns immediately. A
write-only open() returns with an error if no other process has the
FIFO open for reading.
If O_NONBLOCK is not specified a read-only
open() blocks until another process opens the FIFO for writing. A
write-only open() blocks until another process opens the FIFO for
reading.
- When you are opening a character special file that supports a
nonblocking open(), O_NONBLOCK controls whether subsequent reads and
writes can block.
- O_TRUNC
- If the file is successfully opened with O_RDWR or O_WRONLY, this
will truncate the file to zero length if the file exists and is a
regular file. The mode and owner of the file are unchanged. This
option should not be used with O_RDONLY. O_TRUNC has no effect on
FIFO special files or directories.
If O_TRUNC is specified and
the file previously existed a successful open() updates the change
time and modification time for the file.
- O_SYNC
- Force synchronous update. If this flag is 1 every write() operation
on the file is written to permanent storage. That is, the file system
buffers are forced to permanent storage. See
fsync() also.
The program is assured that all data for the file
has been written to permanent storage on return from a function which
performs a synchronous update,
If pathname refers
to a STREAM file, oflag may be constructed
from O_NONBLOCK OR-ed with either O_RDONLY, O_WRONLY or O_RDWR.
Other flag values are not applicable to STREAMS devices and have no
effect on them. The value O_NONBLOCK affects the
operation of STREAMS drivers and certain functions applied to file
descriptors associated with STREAMS files. For STREAMS drivers, the
implementation of O_NONBLOCK is device-specific.
Note: z/OS UNIX services
do not supply any STREAMS devices or pseudodevices. It is impossible
for open() to return a valid STREAMS file descriptor.
The
largest value that can be represented correctly in an object of type
off_t is established as the offset maximum in the open file description.
Large
file support for z/OS UNIX files: Large z/OS UNIX files are supported
automatically for AMODE 64 C/C++ applications. AMODE 31 C/C++ applications
must be compiled with the option LANGLVL(LONGLONG) and define the
_LARGE_FILES feature test macro before any headers are included to
enable this function to operate on z/OS UNIX files that are larger
than 2 GB in size. File size and offset fields are enlarged to 63
bits in width. Therefore, any other function operating on the file
is required to define the _LARGE_FILES feature test macro as well.
Example
The following opens
an output file for appending:
int fd;
fd = open("outfile",O_WRONLY | O_APPEND);
The
following statement creates a new file with read/write/execute permissions
for the creating user. If the file already exists, open() fails.
fd = open("newfile",O_WRONLY|O_CREAT|O_EXCL,S_IRWXU);