|
Hopefully, this page is exactly what you are looking for, but if not, you can always find further assistance on Unix/Linux Forum!
System Calls open(2)
NAME
open, openat - open a file
SYNOPSIS
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
int open(const char *path, int oflag, /* mode_t mode */);
int openat(int fildes, const char *path, int oflag, /*
mode_t 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
argument 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 AT_FDCWD, 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 FD_CLOEXEC 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 O_CREAT is specified (see
below.)
Values for oflag are constructed by a bitwise-inclusive-OR
of flags from the following list, defined in <fcntl.h>.
Applications must specify exactly one of the first three
values (file access modes) below in the value of oflag:
O_RDONLY Open for reading only.
SunOS 5.10 Last change: 2 Jul 2004 1
System Calls open(2)
O_WRONLY Open for writing only.
O_RDWR 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:
O_APPEND
If set, the file offset is set to the end of the file
prior to each write.
O_CREAT
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 O_EXCL 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
S_ISGID 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 S_ISGID bit is cleared.
The access permission bits (see <sys/stat.h>) 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)). O_SYNC Write I/O
operations on the file descriptor complete as defined by
synchronized I/O file integrity completion (see
fcntl.h(3HEAD) definition of O_SYNC.) When bits other
than the file permission bits are set, the effect is
unspecified. The mode argument does not affect whether
the file is open for reading, writing or for both.
SunOS 5.10 Last change: 2 Jul 2004 2
System Calls open(2)
O_DSYNC
Write I/O operations on the file descriptor complete as
defined by synchronized I/O data integrity completion.
O_EXCL
If O_CREAT and O_EXCL 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 O_EXCL and
O_CREAT set. If O_EXCL and O_CREAT are set, and path
names a symbolic link, open() fails and sets errno to
EEXIST, regardless of the contents of the symbolic link.
If O_EXCL is set and O_CREAT is not set, the result is
undefined.
O_LARGEFILE
If set, the offset maximum in the open file description
is the largest value that can be represented correctly
in an object of type off64_t.
O_NOCTTY
If set and path identifies a terminal device, open()
does not cause the terminal device to become the con-
trolling terminal for the process.
O_NOFOLLOW
If the path names a symbolic link, open() fails and sets
errno to ELOOP.
O_NOLINKS
If the link count of the named file is greater than 1,
open() fails and sets errno to EMLINK.
SunOS 5.10 Last change: 2 Jul 2004 3
System Calls open(2)
O_NONBLOCK or O_NDELAY
These flags can affect subsequent reads and writes (see
read(2) and write(2)). If both O_NDELAY and O_NONBLOCK
are set, O_NONBLOCK takes precedence.
When opening a FIFO with O_RDONLY or O_WRONLY set:
o If O_NONBLOCK or O_NDELAY is set, an open() for
reading only returns without delay. Anopen() for
writing only returns an error if no process
currently has the file open for reading.
o If O_NONBLOCK and O_NDELAY are clear, an open() for
reading only blocks until a thread opens the file
for writing. Anopen() 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() O_RDONLY
(O_WRONLY) will synchronize with later calls to open()
O_WRONLY (O_RDONLY) 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 O_NONBLOCK or O_NDELAY is set, the open() func-
tion returns without blocking for the device to be
ready or available. Subsequent behavior of the dev-
ice is device-specific.
o If O_NONBLOCK and O_NDELAY are clear, the open()
function blocks the calling thread until the device
is ready or available before returning.
Otherwise, the behavior of O_NONBLOCK and O_NDELAY is
unspecified.
O_RSYNC
Read I/O operations on the file descriptor complete at
the same level of integrity as specified by the O_DSYNC
and O_SYNC flags. If both O_DSYNC and O_RSYNC are set
in oflag, all I/O operations on the file descriptor
SunOS 5.10 Last change: 2 Jul 2004 4
System Calls open(2)
complete as defined by synchronized I/O data integrity
completion. If both O_SYNC and O_RSYNC are set in
oflag, all I/O operations on the file descriptor com-
plete as defined by synchronized I/O file integrity com-
pletion.
O_SYNC
Write I/O operations on the file descriptor complete as
defined by synchronized I/O file integrity completion.
O_TRUNC
If the file exists and is a regular file, and the file
is successfully opened O_RDWR or O_WRONLY, 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 O_TRUNC
with O_RDONLY is undefined.
O_XATTR
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 O_CREAT is set and the file did not previously exist,
upon successful completion, open() marks for update the
st_atime, st_ctime, and st_mtime fields of the file and the
st_ctime and st_mtime fields of the parent directory.
If O_TRUNC is set and the file did previously exist, upon
successful completion, open() marks for update the st_ctime
and st_mtime fields of the file.
If both the O_SYNC and O_DSYNC flags are set, the effect is
as if only the O_SYNC flag was set.
SunOS 5.10 Last change: 2 Jul 2004 5
System Calls open(2)
If path refers to a STREAMS file, oflag may be constructed
from O_NONBLOCK or O_NODELAY 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 values
O_NONBLOCK and O_NODELAY affect the operation of STREAMS
drivers and certain functions (see read(2), getmsg(2),
putmsg(2), and write(2)) applied to file descriptors associ-
ated with STREAMS files. For STREAMS drivers, the implemen-
tation of O_NONBLOCK and O_NODELAY 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
I_RECVFD 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 path is a symbolic link and O_CREAT and O_EXCL 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 off_t 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
are created or modified.
ERRORS
The open() and openat() functions will fail if:
EACCES 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.
O_TRUNC is specified and write permission is
SunOS 5.10 Last change: 2 Jul 2004 6
System Calls open(2)
denied.
The {PRIV_FILE_DAC_SEARCH} privilege allows
processes to search directories regardless
of permission bits. The
{PRIV_FILE_DAC_WRITE} 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
{PRIV_FILE_DAC_READ} privilege allows
processes to open files for reading regard-
less of permission bits.
EBADF The file descriptor provided to openat() is
invalid.
EDQUOT The file does not exist, O_CREAT 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.
EEXIST The O_CREAT and O_EXCL flags are set and the
named file exists.
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 O_XATTR flag was sup-
plied and the underlying file system does
not support extended file attributes.
SunOS 5.10 Last change: 2 Jul 2004 7
System Calls open(2)
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 O_WRONLY or O_RDWR.
ELOOP Too many symbolic links were encountered in
resolving path.
A loop exists in symbolic links encountered
during resolution of the path argument.
The O_NOFOLLOW flag is set and the final
component of path is a symbolic link.
EMFILE There are currently {OPEN_MAX} file descrip-
tors open in the calling process.
EMLINK The O_NOLINKS 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.
ENAMETOOLONG The length of the path argument exceeds
{PATH_MAX} or a pathname component is longer
than {NAME_MAX}.
ENFILE The maximum allowable number of files is
currently open in the system.
ENOENT The O_CREAT flag is not set and the named
file does not exist; or the O_CREAT flag is
set and either the path prefix does not
exist or the path argument points to an
SunOS 5.10 Last change: 2 Jul 2004 8
System Calls open(2)
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 O_CREAT 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 O_XATTR flag was not supplied,
and the file descriptor does not refer to a
directory.
ENXIO The O_NONBLOCK flag is set, the named file
is a FIFO, the O_WRONLY 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.
EOPNOTSUPP An attempt was made to open a path that
corresponds to a AF_UNIX socket.
EOVERFLOW The named file is a regular file and either
O_LARGEFILE is not set and the size of the
SunOS 5.10 Last change: 2 Jul 2004 9
System Calls open(2)
file cannot be represented correctly in an
object of type off_t or O_LARGEFILE is set
and the size of the file cannot be
represented correctly in an object of type
off64_t.
EROFS The named file resides on a read-only file
system and either O_WRONLY, O_RDWR, O_CREAT
(if file does not exist), or O_TRUNC 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 AT_FTCWD.
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.
ENAMETOOLONG Pathname resolution of a symbolic link pro-
duced an intermediate result whose length
exceeds {PATH_MAX}.
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
O_WRONLY or O_RDWR.
SunOS 5.10 Last change: 2 Jul 2004 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 <fcntl.h>
...
int fd;
mode_t mode = S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH;
char *filename = "/tmp/file";
...
fd = open(filename, O_WRONLY | O_CREAT | O_TRUNC, 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 O_EXCL 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 <fcntl.h>
#include <stdio.h>
#include <stdlib.h>
#define LOCKFILE "/etc/ptmp"
...
int pfd; /* Integer for file descriptor returned by open() call. */
...
if ((pfd = open(LOCKFILE, O_WRONLY | O_CREAT | O_EXCL,
S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH)) == -1)
{
fprintf(stderr, "Cannot open /etc/ptmp. Try again later.\n");
exit(1);
}
...
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,
SunOS 5.10 Last change: 2 Jul 2004 11
System Calls open(2)
the system truncates the file to zero bytes.
#include <fcntl.h>
#include <stdio.h>
#include <stdlib.h>
#define LOCKFILE "/etc/ptmp"
...
int pfd;
char filename[PATH_MAX+1];
...
if ((pfd = open(filename, O_WRONLY | O_CREAT | O_TRUNC,
S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH)) == -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 O_LARGEFILE set in oflag.
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | See below. |
|_____________________________|_____________________________|
| MT-Level | Async-Signal-Safe |
|_____________________________|_____________________________|
The open() function is Standard. The openat() function is
Evolving.
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),
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.10 Last change: 2 Jul 2004 12
Man(1) output converted with
man2html and wrapped by fishsponge
This page was generated on Wed Sep 12 11:27:03 GMT 2007
|
Your favourite pages:
No pages logged yet... Top 10 most popular pages:
prstat man page (24541 hits)
(Solaris 10 11_06)
netcat man page (17692 hits)
(Suse Linux 10.1)
ssh-socks5-proxy-connect man page (13521 hits)
(Solaris 10 11_06)
signal man page (12550 hits)
(Suse Linux 10.1)
startproc man page (11987 hits)
(Suse Linux 10.1)
raidctl man page (11353 hits)
(Solaris 10 11_06)
adv_cap_autoneg man page (10283 hits)
(Solaris 10 11_06)
sqlite3 man page (9728 hits)
(openSUSE 10.2)
CPAN man page (8947 hits)
(Suse Linux 10.1)
BusyBox man page (7698 hits)
(Suse Linux 10.1)
|
Man Pages 
