System Calls open(2)
NAME
open, openat - open a file
SYNOPSIS
#include
#include
#include
int open(const char *path, int oflag, /* modet mode */);
int openat(int fildes, const char *path, int oflag,
/* modet mode */);
DESCRIPTION
The open() function establishes the connection between a
file and a file descriptor. It creates an open file descrip-
tion that refers to a file and a file descriptor that refers
to that open file description. The file descriptor is used
by other I/O functions to refer to that file. The path argu-
ment points to a pathname naming the file.
The openat() function is identical to the open() function
except that the path argument is interpreted relative to the
starting point implied by the fildes argument. If the fildes
argument has the special value ATFDCWD, a relative path
argument will be resolved relative to the current working
directory. If the path argument is absolute, the fildes
argument is ignored.
The open() function returns a file descriptor for the named
file that is the lowest file descriptor not currently open
for that process. The open file description is new, and
therefore the file descriptor does not share it with any
other process in the system. The FDCLOEXEC file descriptor
flag associated with the new file descriptor is cleared.
The file offset used to mark the current position within the
file is set to the beginning of the file.
The file status flags and file access modes of the open file
description are set according to the value of oflag. The
mode argument is used only when OCREAT is specified (see
below.)
SunOS 5.11 Last change: 16 Jun 2008 1
System Calls open(2)
Values for oflag are constructed by a bitwise-inclusive-OR
of flags from the following list, defined in .
Applications must specify exactly one of the first three
values (file access modes) below in the value of oflag:
ORDONLY Open for reading only.
OWRONLY Open for writing only.
ORDWR Open for reading and writing. The result is
undefined if this flag is applied to a FIFO.
Any combination of the following may be used:
OAPEND
If set, the file offset is set to the end of the file
prior to each write.
OCREAT
Create the file if it does not exist. This flag requires
that the mode argument be specified.
If the file exists, this flag has no effect except as
noted under OEXCL below. Otherwise, the file is
created with the user ID of the file set to the effec-
tive user ID of the process. The group ID of the file is
set to the effective group IDs of the process, or if the
SISGID bit is set in the directory in which the file is
being created, the file's group ID is set to the group
ID of its parent directory. If the group ID of the new
file does not match the effective group ID or one of the
supplementary groups IDs, the SISGID bit is cleared.
The access permission bits (see ) of the
file mode are set to the value of mode, modified as fol-
lows (see creat(2)): a bitwise-AND is performed on the
file-mode bits and the corresponding bits in the comple-
ment of the process's file mode creation mask. Thus, all
bits set in the process's file mode creation mask (see
umask(2)) are correspondingly cleared in the file's per-
mission mask. The "save text image after execution bit"
of the mode is cleared (see chmod(2)). OSYNC Write I/O
operations on the file descriptor complete as defined by
synchronized I/O file integrity completion (see
fcntl.h(3HEAD) definition of OSYNC.) When bits other
than the file permission bits are set, the effect is
SunOS 5.11 Last change: 16 Jun 2008 2
System Calls open(2)
unspecified. The mode argument does not affect whether
the file is open for reading, writing or for both.
ODSYNC
Write I/O operations on the file descriptor complete as
defined by synchronized I/O data integrity completion.
OEXCL
If OCREAT and OEXCL are set, open() fails if the file
exists. 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 OEXCL and
OCREAT set. If OEXCL and OCREAT are set, and path
names a symbolic link, open() fails and sets errno to
EXIST, regardless of the contents of the symbolic link.
If OEXCL is set and OCREAT is not set, the result is
undefined.
OLARGEFILE
If set, the offset maximum in the open file description
is the largest value that can be represented correctly
in an object of type off64t.
ONOCTY
If set and path identifies a terminal device, open()
does not cause the terminal device to become the con-
trolling terminal for the process.
ONOFOLOW
If the path names a symbolic link, open() fails and sets
errno to ELOP.
ONOLINKS
If the link count of the named file is greater than 1,
open() fails and sets errno to EMLINK.
ONONBLOCK or ONDELAY
SunOS 5.11 Last change: 16 Jun 2008 3
System Calls open(2)
These flags can affect subsequent reads and writes (see
read(2) and write(2)). If both ONDELAY and ONONBLOCK
are set, ONONBLOCK takes precedence.
When opening a FIFO with ORDONLY or OWRONLY set:
o If ONONBLOCK or ONDELAY is set, an open() for
reading only returns without delay. An open()
for writing only returns an error if no process
currently has the file open for reading.
o If ONONBLOCK and ONDELAY are clear, an open()
for reading only blocks until a thread opens
the file for writing. An open() for writing
only blocks the calling thread until a thread
opens the file for reading.
After both ends of a FIFO have been opened, there is no
guarantee that further calls to open() ORDONLY
(OWRONLY) will synchronize with later calls to open()
OWRONLY (ORDONLY) until both ends of the FIFO have
been closed by all readers and writers. Any data writ-
ten into a FIFO will be lost if both ends of the FIFO
are closed before the data is read.
When opening a block special or character special file
that supports non-blocking opens:
o If ONONBLOCK or ONDELAY is set, the open()
function returns without blocking for the dev-
ice to be ready or available. Subsequent
behavior of the device is device-specific.
o If ONONBLOCK and ONDELAY are clear, the
open() function blocks the calling thread until
the device is ready or available before return-
ing.
Otherwise, the behavior of ONONBLOCK and ONDELAY is
unspecified.
ORSYNC
Read I/O operations on the file descriptor complete at
the same level of integrity as specified by the ODSYNC
and OSYNC flags. If both ODSYNC and ORSYNC are set in
oflag, all I/O operations on the file descriptor com-
plete as defined by synchronized I/O data integrity com-
pletion. If both OSYNC and ORSYNC are set in oflag,
all I/O operations on the file descriptor complete as
defined by synchronized I/O file integrity completion.
SunOS 5.11 Last change: 16 Jun 2008 4
System Calls open(2)
OSYNC
Write I/O operations on the file descriptor complete as
defined by synchronized I/O file integrity completion.
OTRUNC
If the file exists and is a regular file, and the file
is successfully opened ORDWR or OWRONLY, its length is
truncated to 0 and the mode and owner are unchanged. It
has no effect on FIFO special files or terminal device
files. Its effect on other file types is
implementation-dependent. The result of using OTRUNC
with ORDONLY is undefined.
OXATR
If set in openat(), a relative path argument is inter-
preted as a reference to an extended attribute of the
file associated with the supplied file descriptor. This
flag therefore requires the presence of a legal fildes
argument. If set in open(), the implied file descriptor
is that for the current working directory. Extended
attributes must be referenced with a relative path; pro-
viding an absolute path results in a normal file refer-
ence.
If OCREAT is set and the file did not previously exist,
upon successful completion, open() marks for update the
statime, stctime, and stmtime fields of the file and the
stctime and stmtime fields of the parent directory.
If OTRUNC is set and the file did previously exist, upon
successful completion, open() marks for update the stctime
and stmtime fields of the file.
If both the OSYNC and ODSYNC flags are set, the effect is
as if only the OSYNC flag was set.
If path refers to a STREAMS file, oflag may be constructed
from ONONBLOCK or ONODELAY OR-ed with either ORDONLY,
OWRONLY, or ORDWR. Other flag values are not applicable to
STREAMS devices and have no effect on them. The values
ONONBLOCK and ONODELAY affect the operation of STREAMS
drivers and certain functions (see read(2), getmsg(2),
SunOS 5.11 Last change: 16 Jun 2008 5
System Calls open(2)
putmsg(2), and write(2)) applied to file descriptors associ-
ated with STREAMS files. For STREAMS drivers, the implemen-
tation of ONONBLOCK and ONODELAY is device-specific.
When open() is invoked to open a named stream, and the
connld module (see connld(7M)) has been pushed on the pipe,
open() blocks until the server process has issued an
IRECVFD ioctl() (see streamio(7I)) to receive the file
descriptor.
If path names the master side of a pseudo-terminal device,
then it is unspecified whether open() locks the slave side
so that it cannot be opened. Portable applications must
call unlockpt(3C) before opening the slave side.
If the file is a regular file and the local file system is
mounted with the nbmand mount option, then a mandatory share
reservation is automatically obtained on the file. The share
reservation is obtained as if fcntl(2) were called with cmd
FSHARENBMAND and the fsharet values set as follows:
faccess Set to the type of read/write access for which
the file is opened.
fdeny FNODNY
fid The file descriptor value returned from open().
If path is a symbolic link and OCREAT and OEXCL are set,
the link is not followed.
Certain flag values can be set following open() as described
in fcntl(2).
The largest value that can be represented correctly in an
object of type offt is established as the offset maximum in
the open file description.
RETURN VALUES
Upon successful completion, the open() function opens the
file and return a non-negative integer representing the
lowest numbered unused file descriptor. Otherwise, -1 is
returned, errno is set to indicate the error, and no files
SunOS 5.11 Last change: 16 Jun 2008 6
System Calls open(2)
are created or modified.
ERORS
The open() and openat() functions will fail if:
EACES Search permission is denied on a component
of the path prefix.
The file exists and the permissions speci-
fied by oflag are denied.
The file does not exist and write permission
is denied for the parent directory of the
file to be created.
OTRUNC is specified and write permission is
denied.
The {PRIVFILEDACSEARCH} privilege allows
processes to search directories regardless
of permission bits. The
{PRIVFILEDACWRITE} privilege allows
processes to open files for writing regard-
less of permission bits. See privileges(5)
for special considerations when opening
files owned by UID 0 for writing. The
{PRIVFILEDACREAD} privilege allows
processes to open files for reading regard-
less of permission bits.
EAGAIN A mandatory share reservation could not be
obtained because the desired access con-
flicts with an existing fdeny share reser-
vation.
EBADF The file descriptor provided to openat() is
invalid.
EDQUOT The file does not exist, OCREAT is speci-
fied, and either the directory where the new
file entry is being placed cannot be
extended because the user's quota of disk
blocks on that file system has been
exhausted, or the user's quota of inodes on
the file system where the file is being
created has been exhausted.
SunOS 5.11 Last change: 16 Jun 2008 7
System Calls open(2)
EXIST The OCREAT and OEXCL flags are set and the
named file exists.
EILSEQ The path argument includes non-UTF8 charac-
ters and the file system accepts only file
names where all characters are part of the
UTF-8 character codeset.
EINTR A signal was caught during open().
EFAULT The path argument points to an illegal
address.
EINVAL The system does not support synchronized I/O
for this file, or the OXATR flag was sup-
plied and the underlying file system does
not support extended file attributes.
EIO The path argument names a STREAMS file and a
hangup or error occurred during the open().
EISDIR The named file is a directory and oflag
includes OWRONLY or ORDWR.
ELOP Too many symbolic links were encountered in
resolving path.
A loop exists in symbolic links encountered
during resolution of the path argument.
The ONOFOLOW flag is set and the final
component of path is a symbolic link.
EMFILE There are currently {OPENMAX} file descrip-
tors open in the calling process.
EMLINK The ONOLINKS flag is set and the named file
has a link count greater than 1.
EMULTIHOP Components of path require hopping to multi-
ple remote machines and the file system does
not allow it.
SunOS 5.11 Last change: 16 Jun 2008 8
System Calls open(2)
ENAMETOLONG The length of the path argument exceeds
{PATHMAX} or a pathname component is longer
than {NAMEMAX}.
ENFILE The maximum allowable number of files is
currently open in the system.
ENOENT The OCREAT flag is not set and the named
file does not exist; or the OCREAT flag is
set and either the path prefix does not
exist or the path argument points to an
empty string.
ENOLINK The path argument points to a remote
machine, and the link to that machine is no
longer active.
ENOSR The path argument names a STREAMS-based file
and the system is unable to allocate a
STREAM.
ENOSPC The directory or file system that would con-
tain the new file cannot be expanded, the
file does not exist, and OCREAT is speci-
fied.
ENOSYS The device specified by path does not sup-
port the open operation.
ENOTDIR A component of the path prefix is not a
directory or a relative path was supplied to
openat(), the OXATR flag was not supplied,
and the file descriptor does not refer to a
directory.
ENXIO The ONONBLOCK flag is set, the named file
is a FIFO, the OWRONLY flag is set, and no
process has the file open for reading; or
the named file is a character special or
block special file and the device associated
with this special file does not exist or has
been retired by the fault management frame-
work .
SunOS 5.11 Last change: 16 Jun 2008 9
System Calls open(2)
EOPNOTSUP An attempt was made to open a path that
corresponds to a AFUNIX socket.
EOVERFLOW The named file is a regular file and either
OLARGEFILE is not set and the size of the
file cannot be represented correctly in an
object of type offt or OLARGEFILE is set
and the size of the file cannot be
represented correctly in an object of type
off64t.
EROFS The named file resides on a read-only file
system and either OWRONLY, ORDWR, OCREAT
(if file does not exist), or OTRUNC is set
in the oflag argument.
The openat() function will fail if:
EBADF The fildes argument is not a valid open file
descriptor or is not ATFTCWD.
The open() function may fail if:
EAGAIN The path argument names the slave side of a
pseudo-terminal device that is locked.
EINVAL The value of the oflag argument is not
valid.
ENAMETOLONG Pathname resolution of a symbolic link pro-
duced an intermediate result whose length
exceeds {PATHMAX}.
ENOMEM The path argument names a STREAMS file and
the system is unable to allocate resources.
ETXTBSY The file is a pure procedure (shared text)
file that is being executed and oflag is
OWRONLY or ORDWR.
SunOS 5.11 Last change: 16 Jun 2008 10
System Calls open(2)
EXAMPLES
Example 1 Open a file for writing by the owner.
The following example opens the file /tmp/file, either by
creating it if it does not already exist, or by truncating
its length to 0 if it does exist. If the call creates a new
file, the access permission bits in the file mode of the
file are set to permit reading and writing by the owner, and
to permit reading only by group members and others.
If the call to open() is successful, the file is opened for
writing.
#include
...
int fd;
modet mode = SIRUSR SIWUSR SIRGRP SIROTH;
char *filename = "/tmp/file";
...
fd = open(filename, OWRONLY OCREAT OTRUNC, mode);
...
Example 2 Open a file using an existence check.
The following example uses the open() function to try to
create the LOCKFILE file and open it for writing. Since the
open() function specifies the OEXCL flag, the call fails if
the file already exists. In that case, the application
assumes that someone else is updating the password file and
exits.
#include
#include
#include
#define LOCKFILE "/etc/ptmp"
...
int pfd; /* Integer for file descriptor returned by open() call. */
...
if ((pfd = open(LOCKFILE, OWRONLY OCREAT OEXCL,
SIRUSR SIWUSR SIRGRP SIROTH)) == -1)
{
fprintf(stderr, "Cannot open /etc/ptmp. Try again later.\n");
exit(1);
}
...
SunOS 5.11 Last change: 16 Jun 2008 11
System Calls open(2)
Example 3 Open a file for writing.
The following example opens a file for writing, creating the
file if it does not already exist. If the file does exist,
the system truncates the file to zero bytes.
#include
#include
#include
#define LOCKFILE "/etc/ptmp"
...
int pfd;
char filename[PATHMAX]1];
...
if ((pfd = open(filename, OWRONLY OCREAT OTRUNC,
SIRUSR SIWUSR SIRGRP SIROTH)) == -1)
{
perror("Cannot open output file\n"); exit(1);
}
...
USAGE
The open() function has a transitional interface for 64-bit
file offsets. See lf64(5). Note that using open64() is
equivalent to using open() with OLARGEFILE set in oflag.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Committed
MT-Level Async-Signal-Safe
Standard For open(), see standards(5).
SEE ALSO
Intro(2), chmod(2), close(2), creat(2), dup(2), exec(2),
fcntl(2), getmsg(2), getrlimit(2), lseek(2), putmsg(2),
read(2), stat(2), umask(2), write(2), attropen(3C),
fcntl.h(3HEAD), stat.h(3HEAD), unlockpt(3C), attributes(5),
lf64(5), privileges(5), standards(5), connld(7M),
SunOS 5.11 Last change: 16 Jun 2008 12
System Calls open(2)
streamio(7I)
NOTES
Hierarchical Storage Management (HSM) file systems can some-
times cause long delays when opening a file, since HSM files
must be recalled from secondary storage.
SunOS 5.11 Last change: 16 Jun 2008 13
|
