open, creat - Open a file for reading or writing
#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 );
Interfaces documented on this reference page conform to
industry standards 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.
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 execute permissions of the file to be
created (requested by the O_CREAT flag in the open()
interface). If the file already exists, this parameter is
ignored. This parameter is constructed by logically OR-ing
values described in the <sys/mode.h> header file.
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 minimum
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 [Toc] [Back]
The file access flags, which specify read and write
access, are as follows: 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 specified. If exactly no value is set, the default
O_RDONLY is used.
File Status Flags [Toc] [Back]
The file status flags, which specify file open processing,
are as follows: 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 traditional
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 terminal
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 controlling
terminal for the process if both of the following
conditions 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 subsystem 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. However, 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 permanent 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 [Toc] [Back]
[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 [Toc] [Back]
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_NDELAY 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
available. Subsequent behavior of the device is devicespecific.
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.
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);
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.
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.
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)
[ Back ] |
