HP 3000 Manuals HP 3000 Manuals
open
Opens a file and returns its file descriptor.
Syntax
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
int open (const char *pathname, int oflag, ...);
Parameters
pathname A pointer to a string containing a pathname of a file to be
opened. The pathname must be terminated by a null character.
oflag A value specifying the file status and file access modes of
the file to be opened. If O_CREAT is specified, the mode of
the file must be passed in a third parameter, modes.
The value of oflag is the bitwise inclusive OR of flags from
the following two lists (defined in <fcntl.h>).
Only one of the following three flags must be specified in
oflag:
O_RDONLY Open for reading only.
O_WRONLY Open for writing only.
O_RDWR Open for both reading and writing.
If the file is opened O_WRONLY or O_RDWR, the st_mtime file
time field is marked for update. If the file is opened
O_RDONLY or O_RDWR, the st_atime file time field is marked for
update.
Any combination of the following optional flags may also be
specified in oflag:
O_APPEND The file offset is set to the end of the file prior
to each write.
O_CREAT This option requires a third parameter, mode, which
is of type mode_t. If the optional third parameter
is not passed when O_CREAT is specified, open()
attempts to read invalid data off the stack, and
the results are indeterminate. If the file exists,
this flag has no effect, except as noted under
O_EXCL, below.
If the file is created, the following occurs:
* The file offset is set to the beginning of
the file (where the offset position is 0).
* The file's UID is set to the effective UID
of the calling process.
* The file's GID is set to the GID of the
directory in which the file is being
created.
* The access permission bits of the file are
set to mode and modified by the file mode
creation mask of the calling process.
* The following file time fields are marked
for update:
* The file's st_atime, st_ctime and
st_mtime time fields.
* The parent directory's st_ctime and
st_mtime time fields.
O_EXCL The file is opened for exclusive access by the
calling process. An error results if both O_EXCL
and O_CREAT are specified for an existing file.
An existing file can be opened with O_EXCL and
without O_CREAT only if the file is not currently
open by another process (otherwise, an error
results).
O_TRUNC If the file exists and opened O_TRUNC and either
O_RDWR or O_WRONLY, it is truncated to zero length
and the mode and owner remain unchanged. The file
offset is set to the beginning of the file (where
the offset position is 0).
An error results if the file is opened O_TRUNC and
O_RDONLY.
If O_TRUNC is specified for an existing file, the
st_ctime and st_mtime time fields of the file are
marked for update.
If oflag specifies O_CREAT, mode, a structure of type mode_t,
must be passed to specify the access permission bits that the
file is to be created with. Access permission bits are set by
ORing any combination of the following macros:
S_IRWXU Set file owner class read, write, and execute
(if a file) or search (if a directory)
permission bits.
S_IRUSR Set file owner class read permission bit.
S_IWUSR Set file owner class write permission bit.
S_IXUSR Set file owner class execute (if a file) or
search (if a directory) permission bit.
S_IRWXG Set file group class read, write, and execute
(if a file) or search (if a directory)
permission bits.
S_IRGRP Set file group class read permission bit.
S_IWGRP Set file group class write permission bit.
S_IXGRP Set file group class execute (if a file) or
search (if a directory) permission bit.
S_IRWXO Set file other class read, write, and execute
(if a file), or search (if a directory)
permission bits.
S_IROTH Set file other class read permission bit.
S_IWOTH Set file other class write permission bit.
S_IXOTH Set file other class execute (if a file) or
search (if a directory) permission bit.
Bits that are not access permission bits must contain zeros,
or an error is returned.
Return Values
>=0 Success. A nonnegative integer is returned representing the
lowest numbered file descriptor not open by the calling
process.
-1 An error occurred. The file is not opened, and errno is set
to indicate the error condition.
Description
The open() function establishes the connection between a file specified
by pathname and a file descriptor. It creates an open file description
that refers to the 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 the file.
The open() function returns a file descriptor for the specified file,
which is the lowest file descriptor not currently open for the calling
process. The open file description is new; therefore, the file
descriptor does not share it with any other process in the system.
Implementation Considerations
Refer to the EACCES, EMFILE, EEXCL, EFAULT, EIMPL, EINVAL, and ESYSERR
error descriptions below.
Pipes (or FIFOs), device special files, and read-only file systems are
not supported through POSIX/iX interfaces and cannot be opened by open().
Device files are inherited from the parent process, which has them opened
as STDIN_FILENO, STDOUT_FILENO, and STDERR_FILENO.
The GID of a newly created file is set to the GID of the directory in
which the file is created.
MPE/iX file equations are ignored by open().
The calling process must have the correct access permissions as defined
by either an attached ACD or by the MPE/iX file security matrix. For
example, a file opened O_RDONLY must have either ACD read access or
MPE/iX read access. A file opened O_WRONLY or O_RDWR must have either
ACD write access and append access or MPE/iX write access and append
access.
Signals generated for the calling process during execution of open() are
deferred from delivery until completion of this function.
Errors
If an error occurs, errno is set to one of the following values:
EACCES CAUSE One of the following:
* The calling process does not have search
permission to a component of the pathname.
* The file does not exist and the calling
process does not have write permission to the
parent directory of the file to be created.
* The file exists and the permissions specified
by oflag are denied.
* Both O_TRUNC and O_RDONLY were specified.
* Both O_APPEND and O_RDONLY were specified.
* An MPE/iX lockword is associated with the
file.
ACTION One of the following:
* Make sure that the calling process has search
permission to all directory components of the
pathname.
* Make sure that the calling process has write
permission to the parent directory of the file
to be created.
* Specify valid and compatible flags in oflag.
* Remove the MPE/iX lockword.
EEXCL CAUSE Attempt to open an existing file exclusively failed
because file is already opened.
ACTION Check for ownership of previously opened file. Check
file's permission bits.
Table 4-0. (cont.)
EEXIST CAUSE O_CREAT and O_EXCL are set, and the named file
exists.
ACTION Open the file a different way, or remove the file.
EFAULT CAUSE The system detected a NULL or bad address in
attempting to use the pathname parameter, or the
pathname was not terminated by a null character.
ACTION Make sure that the pointer is correctly initialized.
EIMPL CAUSE One of the following:
* The specified file is not a byte-stream file.
* The pathname began with two slash characters
(//).
* Bits in mode that are not file permission bits
did not contain zeros.
* An attempt was made to create a file in an
MPE/iX account.
* An attempt was made to create a file with a
name that exceeds 16 characters in the root
directory or an MPE/iX group.
ACTION One of the following:
* Open only byte-stream files.
* Do not begin a pathname with two slash
characters (//).
* Set bits in mode that are not file permission
bits to zero.
* Do not create files in an MPE/iX account.
* Do not attempt to create a file with a name
which exceeds 16 characters in the root
directory or an MPE/iX group.
EINVAL CAUSE More than one of the following three open flags were
specified in oflag: O_WRONLY, O_RDONLY, and O_RDWR.
ACTION Specify only one of the open flags in oflag.
EISDIR CAUSE The pathname specifies a directory to be opened.
ACTION Use opendir() to open a directory file.
Table 4-0. (cont.)
EMFILE CAUSE The number of open files and directories would exceed
{OPEN_MAX}, the limit of opened files per process.
ACTION Reduce the number of files and directories opened by
the calling process.
ENAMETOOLONG CAUSE One of the following:
* The length of the pathname exceeds the
{PATH_MAX} limit (defined in the file
<limits.h>).
* A component of the pathname is longer than
{NAME_MAX} (defined in <limits.h>), and
{_POSIX_NO_TRUNC} is in effect for that
directory.
ACTION Make sure that both the component's length and the
full pathname length do not exceed the {NAME_MAX} or
{PATH_MAX} limits.
ENOENT CAUSE The O_CREAT option is not set, and the named file
does not exist; or the O_CREAT option is set, and the
pathname does not exist; or pathname points to an
empty string.
ACTION Specify a valid pathname.
ENOSPC CAUSE Creation of the file would exceed the disk space
limits imposed by the MPE/iX accounting facility, or
there is not enough free disk space to create the
file.
ACTION Extend accounting limits for the directory in which
the file is located, or free up disk space.
ENOTDIR CAUSE A component of the pathname is not a directory.
ACTION Specify a valid pathname.
ESYSERR CAUSE An operating system error has occurred that does not
map directly to any of the above errors.
ACTION Examine the MPE/iX error stack for the type of system
error.
See Also
close(), creat(), dup(), execl(), execv(), <fcntl.h>, lseek(), read(),
<signal.h>, fstat(), stat(), <stat.h>, write(), umask(), POSIX.1 (Section
5.3.1)