open(2)open(2)NAME
open, creat - Open a file for reading or writing
SYNOPSIS
#include <fcntl.h> #include <sys/stat.h> #include <sys/types.h>
int open(
const char *path,
int oflag [,
mode_t mode] ); int creat(
const char *path,
mode_t mode );
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
creat(), open(): POSIX.1, XSH4.0, XSH4.2, XSH5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
Specifies the file to be opened or created. If the path parameter
refers to a symbolic link, the open() function opens the file pointed
to by the symbolic link. Specifies the type of access, special open
processing, the type of update, and the initial state of the open file.
The parameter value is constructed by logically OR-ing special open
processing flags. These flags are defined in the <fcntl.h> header file
and are described in DESCRIPTION. Specifies the read, write, and exe‐
cute permissions of the file to be created (requested by the O_CREAT
flag in the open() interface). If the file already exists, this parame‐
ter is ignored. This parameter is constructed by logically OR-ing val‐
ues described in the <sys/mode.h> header file.
DESCRIPTION
The following two function calls are equivalent:
creat(path, mode);
open(path, O_WRONLY | O_CREAT | O_TRUNC, mode);
The open() and creat() functions establish a connection between the
file named by the path parameter and a file descriptor. Subsequent I/O
functions, such as read() and
write(), use the open file descriptor to access the file.
The file descriptor returned for a file is the lowest file descriptor
not previously opened for that process. In most cases, a process cannot
have more than OPEN_MAX file descriptors open simultaneously. The per-
process soft descriptor limit can be configured at run time. The mini‐
mum value is 64. See getrlimit(2) and setrlimit(2).
The open() and creat() functions suspend the calling process until the
calling thread is suspended.
When an open() or creat() function is called, the file offset, which
marks the current position within the file, is set to the beginning of
the file. The new file descriptor is set to remain open across exec
functions (see fcntl(2)).
The file status flags and file access flags are designated by the oflag
parameter. The oflag parameter is constructed by a bitwise-inclusive OR
operation on exactly one of the file access flags with one or more of
the file status flags.
File Access Flags
The file access flags, which specify read and write access, are as fol‐
lows: The file is open only for reading. The file is open only for
writing. The file is open for reading and writing.
Only one file access value (O_RDONLY, O_WRONLY, or O_RDWR) can be spec‐
ified. If exactly no value is set, the default O_RDONLY is used.
File Status Flags
The file status flags, which specify file open processing, are as fol‐
lows: If the file exists, this flag has no effect, except as described
under the O_EXCL flag. If the file does not exist, a regular file is
created with the following characteristics: The owner ID of the file is
set to the effective user ID of the process. The group ID of the file
is set to the group ID of its parent directory.
However, when the vfs subsystem attribute sys_v_mode is set to
1, the group ID of the file is set either to the group ID of the
process or, if the S_ISGID bit of the parent directory is set,
to the group ID of the parent directory.
If the group ID of the new file does not match the process's
effective group ID or one of its supplementary group IDs, the
S_ISGID bit of the new file is cleared.
The access permission bits of the file mode are set to the value
of mode as follows: The corresponding bits are logically AND-ed
with the complement of the file mode creation mask for the
process. The file permission and attribute bits are set to the
value of the mode parameter, which is modified as follows: All
bits in the file mode whose corresponding bits in the file mode
creation mask are set are cleared. The set-user ID attribute
(S_ISUID bit) is cleared. The set-group ID attribute (S_ISGID
bit) is cleared. The access control list of the new file is set
to WILDCARD (discretionary access to the file according to tra‐
ditional UNIX rules).
To create a new file, the calling process must have permission
to write to the file's parent directory with respect to all
access control policies. If the file exists and O_EXCL and
O_CREAT are set, the open will fail. If the path parameter
identifies a terminal device, this flag assures that the termi‐
nal device does not become the controlling terminal for the
process.
System V Compatibility
In the Tru64 UNIX operating system, O_NOCTTY is set by default
and cannot be unset. In the System V habitat, however, O_NOCTTY
is not set by default, and a terminal device can become the con‐
trolling terminal for the process if both of the following con‐
ditions are met: The process does not already have a controlling
terminal. The terminal device pointed to by path is not already
a controlling terminal. If the file does not exist, this flag
has no effect.
If the file exists, is a regular file, and is successfully
opened with O_WRONLY or O_RDWR, the following occurs: The length
of the file is truncated to 0 (zero). The owner and group of
the file are unchanged. The set-user ID attribute of the file
mode is cleared, unless the vfs subsystem variable sys_v_mode is
set to 1. In this case, the file length is truncated to 0 and
the mode, owner, and group are not changed. The set-user ID
attribute of the file is cleared.
The open operation fails if either of the following conditions
is true: The file supports enforced record locks and another
process has locked a portion of the file. The file does not
allow write access.
If the oflag parameter also specifies O_SYNC, O_DSYNC, or
O_RSYNC, the truncation becomes a synchronous update.
A program can request some control over when updates should be
made permanent for a regular file that is opened for write
access.
The calling process must have write access to the file with
respect to all access policies. [Tru64 UNIX] If this flag is
set and the last component of path is a symbolic link, open()
will fail, even if the symbolic link points to a non-existent
file.
File status flags that specify special processing for subsequent reads
and writes of the open file are as follows: If set, and if the vfs sub‐
system variable strict_posix_osync is set to 1 (enabled), updates and
writes to regular files and block devices will synchronously update
data and file attribute information. When a function that performs an
O_SYNC synchronous update (a write() system call when O_SYNC is set)
returns, the calling process is assured that all data and file
attribute information has been written to permanent storage, even if a
file is also open for deferred (asynchronous) update. If the
strict_posix_osync variable is set to 0, updates and writes to regular
files and block devices synchronously update only data (see the O_DSYNC
flag). If set, updates and writes to regular files and block devices
will synchronously update only the data and file attributes that are
required to retrieve data. For example, this occurs when a file is
extended. When a function returns that performs an O_DSYNC synchronous
update (a write() system call when O_DSYNC is set), the calling process
is assured that all data has been written to permanent storage. How‐
ever, using O_DSYNC does not guarantee that file-control information,
such as owner and modification time, is updated to permanent storage.
If set and if O_DSYNC is set, enables synchronized I/O data integrity
for read operations. The calling process is assured that all pending
file data writes are written to permanent storage prior to a read.
If set, and if O_SYNC is set, enables synchronized I/O file
integrity for read operations. The calling process is assured
that all data and file attribute information is written to per‐
manent storage prior to a read.
If O_RSYNC is used alone, it has no effect. If set, the file
pointer is set to the end of the file prior to each write. If
set, the call to open() will not block, and subsequent read() or
write() operations on the file will be nonblocking.
AdvFS-Only File Flag
[Tru64 UNIX] The following file flag is used only with AdvFS, and is
ignored by all other file systems. Enables direct I/O on a file. Also
enables direct I/O for all processes that have opened the file. Note
that you cannot enable direct I/O for a data logging file or for a file
that is mmap'ed. In addition, you cannot mmap a file that has direct
I/O enabled.
General Notes on oflag Parameter Flag Values
The effect of O_CREAT is immediate.
When opening a FIFO with O_RDONLY: If O_NDELAY or O_NONBLOCK is not
set, the open() function is blocked until another process opens the
file for writing. If the file is already open for writing (even by the
calling process), the open() function returns immediately. If O_NDELAY
or O_NONBLOCK is set, the open() function returns immediately.
When opening a FIFO with O_WRONLY: If O_NDELAY or O_NONBLOCK is not
set, the open() function is blocked until another process opens the
file for reading. If the file is already open for reading (even by the
calling process), the open() function returns without delay. If O_NDE‐
LAY or O_NONBLOCK is set, the open() function returns an error if no
process currently has the file open for reading.
When opening a block special or character special file that supports
nonblocking opens (such as from a terminal device): If O_NDELAY or
O_NONBLOCK is not set, the open() function is blocked until the device
is ready or available. If O_NDELAY or O_NONBLOCK is set, the open()
function returns without waiting for the device to be ready or avail‐
able. Subsequent behavior of the device is device-specific.
When opening a STREAMS file, oflag may be constructed from O_NDELAY or
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 of O_NDELAY or NON_BLOCK affects the operation of
STREAMS drivers and certain system calls. See read(2), getmsg(2),
putmsg(2), and write(2). For drivers, the implementation of O_NDELAY or
NON_BLOCK is device-specific. Different STREAMS device drivers may
treat this option differently.
RESTRICTIONS
Since a file newly created by creat() is write only, an fdopen() call
using the r+ parameter fails if it follows a creat() call. A solution
to this problem is to create the file using a call that adheres to the
following format:
open (path, O_RDWR | O_CREAT, 0666);
RETURN VALUES
On successful completion, the open() and creat() functions return the
file descriptor, which is a nonnegative integer. If the open fails, a
value of -1 is returned and errno is set to indicate the error.
ERRORS
If the open() or creat() function fails, errno may be set to one of the
following values: One of the following occurred: Search permission is
denied on a component of the path prefix, the type of access specified
by the oflag parameter is denied for the named file, the file does not
exist and write permission is denied for the parent directory, or
O_TRUNC is specified and write permission is denied. The O_TRUNC flag
is set, the named file exists with enforced record locking enabled, and
record locks are put on the file. The named file is a block device
file and the block device is in use by a mounted file system. The
directory in which the entry for the new link is being placed cannot be
extended, because the quota of disk blocks (or inodes that are defined
for the user on the file system containing the directory) has been
exhausted. The O_CREAT and O_EXCL flags are set and the named file
exists. The path parameter is an invalid address. A signal was caught
by the open() function. The owner or group ID is not a value supported
by this implementation, or the O_DIRECTIO flag was specified and the
file is already opened for atomic write data logging or is mmap'ed.
[Tru64 UNIX] O_CREAT was requested and an I/O error occurred when
updating the directory. The named file is a directory and write access
was requested.
In a System V habitat, the named file is a directory and the
oflag permission is write or read/write. Too many symbolic
links were encountered in translating path. The system limit
for open file descriptors per process has already reached the
OPEN_MAX limit, or the per-process soft descriptor limit has
already been reached. The length of the path string exceeds
PATH_MAX or a pathname component is longer than NAME_MAX. The
path parameter points to a remote machine and the link to that
machine is no longer active. The system file table is full.
One of the following applies: The O_CREAT flag is not set and
the named file does not exist, the O_CREATflag is set and the
path prefix does not exist, or the path parameter points to an
empty string. The system was unable to allocate kernel memory
for more file descriptors. The directory that would contain the
new file cannot be extended, the file does not exist, and
O_CREAT is requested. Unable to allocate a stream. A component
of the path prefix is not a directory. [Tru64 UNIX] The
O_NOFOLLOW flag is set and the last component of the path value
is a symbolic link. One of the following applies:
The named file is a character special or block special file and
the device associated with this special file does not exist.
The named file is a multiplexed special file and the channel
number is outside of the valid range, or no more channels are
available.
The O_NONBLOCK flag is set, the named file is a FIFO, O_WRONLY
is set, and no process has the file open for reading.
A STREAMS module or driver open routine failed. The named file
is a socket bound to the file system (a UNIX domain socket) and
cannot be opened. The named file resides on a read-only file
system and write access is required.
For NFS file access, if the open() or creat() function fails, errno may
be set to one of the following values: A server attempted to handle an
NFS request by generating a request to another NFS server, which is not
allowed. A stale NFS file handle exists. One of the following
occurred: An open file was deleted by the server or another client, the
server unmounted or unexported the remote directory, or the server
unmounted or unexported the directory that contains an open file. A
connection time-out occurred. For files that are mounted with the soft
option, the server is down or there is a network problem.
SEE ALSO
Functions: chmod(2), close(2), fcntl(2), getmsg(2), lseek(2),
putmsg(2), read(2), stat(2), truncate(2), umask(2), write(2), lockf(3)
Standards: standards(5)open(2)
