 |
Index for
Section 2 |
|
 |
Alphabetical
listing for O |
|
 |
Bottom of
page |
|
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(), 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
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 OR-ing special open processing flags. These
flags are defined in the <fcntl.h> header file and are described in
DESCRIPTION.
mode
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.
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 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
The file access flags, which specify read and write access, are as follows:
O_RDONLY
The file is open only for reading.
O_WRONLY
The file is open only for writing.
O_RDWR
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
The file status flags, which specify file open processing, are as follows:
O_CREAT
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.
O_EXCL
If the file exists and O_EXCL and O_CREAT are set, the open will fail.
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
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.
O_TRUNC
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.
O_NOFOLLOW
[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:
O_SYNC
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).
O_DSYNC
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.
O_RSYNC
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.
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.
AdvFS-Only File Flag
[Tru64 UNIX] The following file flag is used only with AdvFS, and is
ignored by all other file systems.
O_DIRECTIO
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_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 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:
[EACCES]
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.
[EAGAIN]
The O_TRUNC flag is set, the named file exists with enforced record
locking enabled, and record locks are put 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 inodes that
are 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,
or the O_DIRECTIO flag was specified and the file is already opened for
atomic write data logging or is mmap'ed.
[EIO]
[Tru64 UNIX] O_CREAT was requested and an I/O error occurred when
updating the directory.
[EISDIR]
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.
[ELOOP]
Too many symbolic links were encountered in translating path.
[EMFILE]
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.
[ENAMETOOLONG]
The length of the path string exceeds PATH_MAX or a pathname component
is longer than NAME_MAX.
[ENETUNREACH]
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]
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.
[ENOMEM]
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.
[ENOTSUP]
[Tru64 UNIX] The O_NOFOLLOW flag is set and the last component of the
path value is a symbolic link.
[ENXIO]
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.
[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.
For NFS file access, if the open() or creat() function fails, errno may be
set to one of the following values:
[EREMOTE]
A server attempted to handle an NFS request by generating a request to
another NFS server, which is not allowed.
[ESTALE]
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.
[ETIMEDOUT]
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)
|
Index for
Section 2 |
|
|
Alphabetical
listing for O |
|
 |
Top of
page |
|