 |
Index for Section 2 |
|
 |
Alphabetical listing for O |
|
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 standards
as follows:
creat(): POSIX.1, XPG4, XPG4-UNIX
open(): POSIX.1, XPG4, XPG4-UNIX
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
path
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.
oflag
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 ORing special open processing flags. These
flags are defined in the fcntl.h header file and are described below.
mode
[DIGITAL] 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 ORing values 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. The opened file
descriptor is used by subsequent I/O functions, such as read() and write(),
to access that file.
The returned file descriptor is the lowest file descriptor not previously
open for that process.
Typically, no process can have more than OPEN_MAX file descriptors open
simultaneously.
[DIGITAL] The per-process soft descriptor limit is checked. This number
is configurable; the minimum value is 64. See getrlimit(2) and
setrlimit(2).
The open() and creat() functions, which suspend the calling process until
the request is completed, are redefined so that only the calling thread is
suspended.
The file offset, marking 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 bitwise-inclusive ORing
exactly one of the file access flags (O_RDONLY, O_WRONLY, or O_RDWR) with
one or more of the file status flags.
File Access Flags
The file access flags are as follows:
O_RDONLY
The file is open for reading only.
O_WRONLY
The file is open for writing only.
O_RDWR
The file is open for reading and writing.
Exactly one of the file access values (O_RDONLY, O_WRONLY, or O_RDWR) must
be specified. If none is set, O_RDONLY is assumed.
File Status Flags
File status flags that specify special open processing are as follows:
O_CREAT
If the file exists, this flag has no effect except as noted under
O_EXCL. 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.
[DIGITAL] However, when the sys_v_mode tunable is set to 1, the group
ID of the file is set to the group ID of the process. With
exception, if the S_ISGID bit of the parent directory is set, the
group ID of the file is set to the group ID of the parent directory.
If the group ID of the new file does not match the effective group of
the process or one of the supplementary group IDs of the process, 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 AND-ed with the
complement of the file mode creation mask of the process. Refer to
the System V Compatibility User's Guide for information on the System
V habitat.
·
The file permission and attribute bits are set to the value of the
mode parameter, modified as follows:
- All bits set in the process file mode creation mask are cleared.
- The set-user ID attribute (S_ISUID bit) is cleared.
- The set-group ID attribute (S_ISGID bit) is cleared.
- The S_ISVTX attribute 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).
The calling process must have write permission to the file's parent
directory with respect to all access control policies to create a new
file.
O_EXCL
If O_EXCL and O_CREAT are set, the open fails if the file exists.
O_NOCTTY
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
[DIGITAL] 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, which means that 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
O_TRUNC
If the file does not exist, this flag has no effect. If the file exists
and is a regular file, and if the file is successfully opened O_RDWR or
O_WRONLY:
·
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.
[DIGITAL] However, when the sys_v_mode tunable is set to 1, the file
exists and is a regular file. Its length is truncated to 0 and the
mode, owner, and group remain unchanged.
·
The set-user ID attribute of the file is cleared.
The open 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.
A program can request some control over when updates should be made
permanent for a regular file opened for write access.
The calling process must have write access to the file with respect to
all access policies.
File status flags that specify special processing for subsequent reads and
writes of the open file are as follows:
O_SYNC
If set, updates and writes to regular files and block devices are
synchronous updates for data and file attribute information. On return
from a function that performs an O_SYNC synchronous update (a write()
system call when O_SYNC is set), the calling process is assured that
all data and file attribute information for the file has been written
to permanent storage, even if the file is also open for deferred
update.
O_DSYNC
If set, updates and writes to regular files and block devices are
synchronous updates for data only. On return from a function that
performs an O_DSYNC synchronous update (a write() system call when
O_DSYNC is set), the calling process is assured that all data for the
file has been written to permanent storage. Use of O_DSYNC does not
guarantee that file-control information such as owner and modification
time are updated to permanent storage.
O_RSYNC
If set in combination with O_DSYNC, applies synchronized I/O data
integrity completion to read operations. The calling process is
assured that all pending writes of file data will have been written to
permanent storage prior to a read, and that the data image has been
successfully transferred to the calling process.
If set in combination with O_SYNC, applies synchronized I/O file
integrity completion to read operations. The calling process is
assured that all data and file attribute information will have been
written to permanent storage prior to a read, and that the data image
has been successfully transferred to the calling process.
If O_RSYNC is used alone, it has no effect.
O_APPEND
If set, the file pointer is set to the end of the file prior to each
write.
O_NONBLOCK, O_NDELAY
If set, the call to open() will not block and subsequent read() or
write() operations on the file will be nonblocking.
General Notes on oflag Parameter Flag Values
The effect of O_CREAT is immediate.
When opening a FIFO with O_RDONLY:
· If neither O_NDELAY nor O_NONBLOCK is set, the open() function blocks
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 without delay.
· If O_NDELAY or O_NONBLOCK is set, the open() function returns
immediately.
When opening a FIFO with O_WRONLY:
· If neither O_NDELAY nor O_NONBLOCK is set, the open() function blocks
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 a terminal device:
· If neither O_NDELAY nor O_NONBLOCK is set, the open() function blocks
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 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. Each STREAMS device driver may treat this option
differently.
RESTRICTIONS
Since a file newly created by creat() is write_only, an fdopen() call using
the r+ parameter fails when following 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, a nonnegative integer. Otherwise, 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:
[EACCES]
Search permission is denied on a component of the path prefix, or
the type of access specified by the oflag parameter is denied for
the named file, or the file does not exist and write permission is
denied for the parent directory, or O_TRUNC is specified and write
permission is denied.
[EAGAIN]
The O_TRUNC flag is set, the named file exists with enforced record
locking enabled and there are record locks on the file.
[EBUSY] The named file is a block device file and the block device is in
use by a mounted file system.
[EDQUOT]
The directory in which the entry for the new link is being placed
cannot be extended because the quota of disk blocks or i-nodes
defined for the user on the file system containing the directory
has been exhausted.
[EEXIST]
The O_CREAT and O_EXCL flags are set and the named file exists.
[EFAULT]
The path parameter is an invalid address.
[EINTR] A signal was caught by the open() function.
[EINVAL]
The owner or group ID is not a value supported by this
implementation.
[EIO] A hangup or error occurred during a STREAMS open().
[EISDIR]
The named file is a directory and write access is requested.
[DIGITAL] However, in a System V habitat, the named file is a
directory and the oflag permission is write or read/write.
[ELOOP] Too many links were encountered in translating path.
[EMFILE]
The system limit for open file descriptors per process has aleady
reached OPEN_MAX.
[DIGITAL] The system descriptor limit or the per-process soft
descriptor limit has already been reached.
[EMULTIHOP]
Components of path require hopping to multiple remote machines.
[ENAMETOOLONG]
The length of the path string exceeds PATH_MAX or a pathname
component is longer than NAME_MAX.
[ENETUNREACH]
[DIGITAL] The path parameter points to a remote machine and the
link to that machine is no longer active.
[ENFILE]
The system file table is full.
[ENOENT]
The O_CREAT flag is not set and the named file does not exist; or
O_CREAT is set and the path prefix does not exist; or the path
parameter points to the empty string.
[ENOMEM]
[DIGITAL] The system was unable to allocate kernel memory for more
file descriptors.
[ENOSPC]
The directory that would contain the new file cannot be extended,
the file does not exist, and O_CREAT is requested.
[ENOSR] Unable to allocate a stream.
[ENOTDIR]
A component of the path prefix is not a directory.
[ENXIO] 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.
[EOPNOTSUPP]
The named file is a socket bound to the file system (a UNIX domain
socket) and cannot be opened.
[EROFS] The named file resides on a read-only file system and write access
is required.
[DIGITAL] For NFS file access, if the open() or creat() function fails,
errno may also be set to one of the following values:
[EREMOTE]
Indicates a server's attempt to handle an NFS request by generating
a request to another NFS server, which is not allowed.
[ESTALE]
Indicates a stale NFS file handle. An opened file was deleted by
the server or another client; a client cannot open a file because
the server has unmounted or unexported the remote directory; or the
directory that contains an opened file was unmounted or unexported
by the server.
[ETIMEDOUT]
Indicates the connection timed out. For files that are mounted
with the soft option, either the server is down or there is a
network problem.
RELATED INFORMATION
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)