546 lines
13 KiB
Groff
546 lines
13 KiB
Groff
'\"macro stdmacro
|
|
.if n .pH 2/gen/open @(#)open 43.5 of 8/4/92
|
|
.\" Copyright 1992, 1991 UNIX System Laboratories, Inc.
|
|
.\" Copyright 1990, 1989 AT&T
|
|
.TH open 2
|
|
.SH NAME
|
|
\f4open\f1 \- open for reading or writing
|
|
.Op c p a
|
|
.SH C SYNOPSIS
|
|
\f4#include <sys/types.h>\f1
|
|
.br
|
|
\f4#include <sys/stat.h>\f1
|
|
.br
|
|
\f4#include <fcntl.h>\f1
|
|
.PP
|
|
\f4int open (const char \(**\f2path\fP, int \f2oflag\fP, ... /* mode_t \f2mode\fP */)\f1;
|
|
.Op
|
|
.Op f
|
|
.SH FORTRAN SYNOPSIS
|
|
.B #define O_RDONLY 0
|
|
.br
|
|
.B #define O_WRONLY 1
|
|
.br
|
|
.B #define O_RDWR 2
|
|
.br
|
|
.B #define O_ACCMODE 0x3
|
|
.br
|
|
.B #define O_NDELAY 0x04
|
|
.br
|
|
.B #define O_APPEND 0x08
|
|
.br
|
|
.B #define O_SYNC 0x10
|
|
.br
|
|
.B #define O_DSYNC 0x20
|
|
.br
|
|
.B #define O_RSYNC 0x40
|
|
.br
|
|
.B #define O_NONBLOCK 0x80
|
|
.br
|
|
.B #define O_CREAT 0x100
|
|
.br
|
|
.B #define O_TRUNC 0x200
|
|
.br
|
|
.B #define O_EXCL 0x400
|
|
.br
|
|
.B #define O_NOCTTY 0x800
|
|
.br
|
|
.B #define O_DIRECT 0x8000
|
|
.br
|
|
.B #define O_LCINVAL 0x20000
|
|
.br
|
|
.B #define O_LCFLUSH 0x40000
|
|
.br
|
|
.sp
|
|
.B "integer *4 function open (path, oflag, mode)"
|
|
.br
|
|
.B "character * (*) path"
|
|
.br
|
|
.B "integer *4 oflag, mode"
|
|
.Op
|
|
.SH DESCRIPTION
|
|
.I path\^
|
|
points to a
|
|
path name
|
|
naming a file.
|
|
\f4open\fP
|
|
opens a file descriptor for the named file
|
|
and sets the file status flags
|
|
according to the value of
|
|
.IR oflag .
|
|
.I oflag\^
|
|
values are constructed by OR-ing Flags
|
|
from the following list (only one of the first three flags below
|
|
may be used):
|
|
.PP
|
|
.TP 0.75i
|
|
\f4O_RDONLY\f1
|
|
Open for reading only.
|
|
.TP
|
|
\f4O_WRONLY\f1
|
|
Open for writing only.
|
|
.TP
|
|
\f4O_RDWR\f1
|
|
Open for reading and writing.
|
|
.TP
|
|
\f4O_NDELAY\f1 or \f4O_NONBLOCK\f1
|
|
These flags may affect subsequent reads and writes
|
|
[see
|
|
\f4read\fP(2)
|
|
and
|
|
\f4write\fP(2)].
|
|
If both
|
|
\f4O_NDELAY\f1
|
|
and
|
|
\f4O_NONBLOCK\f1
|
|
are set,
|
|
\f4O_NONBLOCK\f1
|
|
will take precedence.
|
|
.IP
|
|
When opening a FIFO with
|
|
\f4O_RDONLY\fP
|
|
or
|
|
\f4O_WRONLY\fP
|
|
set:
|
|
.IP "" 15n
|
|
If
|
|
\f4O_NDELAY\f1
|
|
or
|
|
\f4O_NONBLOCK\f1
|
|
is set:
|
|
An \f4open\fP for reading-only will return without delay;
|
|
an
|
|
\f4open\fP
|
|
for writing-only will return an error if no process
|
|
currently has the file open for reading.
|
|
.IP "" 15n
|
|
If
|
|
\f4O_NDELAY\f1
|
|
and
|
|
\f4O_NONBLOCK\f1
|
|
are clear:
|
|
An \f4open\fP for reading-only will block until a process
|
|
opens the file for writing;
|
|
an
|
|
\f4open\fP
|
|
for writing-only will block until a process
|
|
opens the file for reading.
|
|
.IP "" 0.75i
|
|
When opening a file associated with a communication line:
|
|
.IP "" 15n
|
|
If
|
|
\f4O_NDELAY\f1
|
|
or
|
|
\f4O_NONBLOCK\f1
|
|
is set:
|
|
The open will return without waiting for the device to be ready or
|
|
available; subsequent behavior of the device is device specific.
|
|
.IP "" 15n
|
|
If
|
|
\f4O_NDELAY\f1
|
|
and
|
|
\f4O_NONBLOCK\f1
|
|
are clear:
|
|
The open will block until the device is ready or available.
|
|
.TP 0.75i
|
|
\f4O_APPEND\f1
|
|
If set, the file pointer will be set to the end of the file
|
|
prior to each write.
|
|
.TP
|
|
\f4O_SYNC\f1
|
|
When opening a regular file, this flag affects subsequent writes.
|
|
If set, each
|
|
\f4write\fP(2)
|
|
will wait for both the file data and file status to be physically updated.
|
|
.TP
|
|
\f4O_DSYNC\f1
|
|
When opening a regular file, this flag affects subsequent writes.
|
|
If set, each
|
|
\f4write\fP(2)
|
|
will wait for the file data to be physically updated.
|
|
.TP
|
|
\f4O_RSYNC\f1
|
|
When opening a regular file, this flag affects subsequent reads.
|
|
If set, and either
|
|
\f4O_SYNC\fP
|
|
or
|
|
\f4O_DSYNC\fP
|
|
is set then each
|
|
\f4read\fP(2)
|
|
will wait for the file to be in the same state as
|
|
\f4O_SYNC\fP
|
|
or
|
|
\f4O_DSYNC\fP
|
|
would
|
|
require for writes.
|
|
.TP
|
|
\f4O_NOCTTY\f1
|
|
If set and the file is a terminal, the terminal will not be allocated as
|
|
the calling process's controlling terminal.
|
|
.TP
|
|
\f4O_CREAT\f1
|
|
If the file exists, this flag has no effect, except as noted under
|
|
\f4O_EXCL\f1
|
|
below.
|
|
Otherwise, the file is created and the owner
|
|
ID
|
|
of the file
|
|
is set to the effective
|
|
user
|
|
IDs
|
|
of the process,
|
|
the group
|
|
ID
|
|
of the file
|
|
is set to the effective group
|
|
IDs
|
|
of the process or to the group
|
|
.SM ID
|
|
of the directory in which the file is being created.
|
|
This is determined as follows:
|
|
.sp .5
|
|
.in +.5i
|
|
If the underlying filesystem was mounted with
|
|
the
|
|
.SM BSD
|
|
file creation semantics flag [see
|
|
\f4fstab\fP(4)]
|
|
or the
|
|
.SM
|
|
\f4S_ISGID\fP
|
|
bit is set [see
|
|
\f4chmod\fP(2)]
|
|
on the parent directory, then the group
|
|
.SM ID
|
|
of the new file is set to the group
|
|
.SM ID
|
|
of the parent directory, otherwise it is set to the
|
|
effective group
|
|
.SM ID
|
|
of the calling process.
|
|
.in -.5i
|
|
If the
|
|
group ID of the new file does not match the effective group ID or one of
|
|
the supplementary groups IDs, the
|
|
\f4S_ISGID\f1
|
|
bit is cleared.
|
|
The access permission bits of the file mode are set to the value of
|
|
\f2mode\f1, modified as follows [see
|
|
\f4creat\fP(2)]:
|
|
.IP "" 15n
|
|
All bits set in the file mode creation mask of the process are cleared
|
|
[see
|
|
\f4umask\fP(2)].
|
|
.IP "" 15n
|
|
The ``save text image after execution bit'' of the mode is cleared
|
|
[see
|
|
\f4chmod\fP(2)].
|
|
.TP 0.75i
|
|
\f4O_TRUNC \f1
|
|
If the file exists and is a regular file, and the file is successfully opened
|
|
\f4O_RDWR\f1
|
|
or
|
|
\f4O_WRONLY,\f1
|
|
its length is truncated to 0 and the mode and owner are unchanged. It
|
|
will have no effect on FIFO special files or terminal device files. It's
|
|
effect on other files types is implementation-dependent. The result of using
|
|
\f4O_TRUNC\f1
|
|
with
|
|
\f4O_RDONLY\f1
|
|
is undefined.
|
|
.TP
|
|
\f4O_EXCL\f1
|
|
If
|
|
\f4O_EXCL\fP
|
|
and
|
|
\f4O_CREAT\fP
|
|
are set,
|
|
\f4open\fP
|
|
will fail 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 processes executing \f4open\fP
|
|
naming the same filename in the same directory with \f4O_EXCL\fP and
|
|
\f4O_CREAT\fP set.
|
|
.TP
|
|
\f4O_LCFLUSH\fP
|
|
If set, when all copies of a file descriptor are closed, all modified
|
|
buffers associated with the file will be written back to the physical medium.
|
|
\f4O_LCFLUSH\fP is a Silicon Graphics extension.
|
|
.TP
|
|
\f4O_LCINVAL\fP
|
|
If set, when all copies of a file descriptor are closed, all modified
|
|
buffers associated with the file will be written back to the physical
|
|
medium, then invalidated, immediately freeing the buffers for other use.
|
|
The process doing the last close must be able to aquire write access at
|
|
the time of last close for the cache to be invalidated.
|
|
\f4O_LCINVAL\fP is a Silicon Graphics extension.
|
|
.TP
|
|
\f4O_DIRECT\fP
|
|
If set, all reads and writes on the resulting file descriptor will be
|
|
performed directly to or from the user program buffer, provided appropriate
|
|
size and alignment restrictions are met. Refer to the \f4F_SETFL\fP
|
|
and \f4F_DIOINFO\fP commands in the
|
|
\f4fcntl\fP(2)
|
|
manual entry for information about how to determine the alignment constraints.
|
|
\f4O_DIRECT\fP is a Silicon Graphics extension and is only supported on local
|
|
EFS and XFS file systems, and remote BDS file systems.
|
|
.RE
|
|
.PP
|
|
When opening a STREAMS file,
|
|
.I oflag
|
|
may be constructed from
|
|
\f4O_NDELAY\f1
|
|
or
|
|
\f4O_NONBLOCK\f1
|
|
OR-ed with either
|
|
\f4O_RDONLY\f1,
|
|
\f4O_WRONLY ,\f1
|
|
or
|
|
\f4O_RDWR\f1.
|
|
Other flag values are not applicable to STREAMS devices and have no
|
|
effect on them.
|
|
The values of \f4O_NDELAY\fP and \f4O_NONBLOCK\fP affect the operation of
|
|
STREAMS drivers and certain system calls
|
|
[see \f4read\fP(2), \f4getmsg\fP(2), \f4putmsg\fP(2), and \f4write\fP(2)].
|
|
For drivers, the implementation of \f4O_NDELAY\fP and \f4O_NONBLOCK\fP is
|
|
device specific.
|
|
Each STREAMS device driver may treat these options differently.
|
|
.PP
|
|
When \f4open\fP is invoked to open a named stream, and the \f4connld\fP module
|
|
[see \f4connld\fP(7)] has been pushed on the pipe, \f4open\fP blocks until
|
|
the server process has issued an \f4I_RECVFD ioctl\fP [see \f4streamio\fP(7)]
|
|
to receive the file descriptor.
|
|
.PP
|
|
If \f2path\fP is a symbolic link and \f4O_CREAT\fP and \f4O_EXCL\fP are set,
|
|
the link is not followed.
|
|
.PP
|
|
The file pointer used to mark the current position within the file
|
|
is set to the beginning of the file.
|
|
.PP
|
|
The new file descriptor is the lowest numbered file descriptor available
|
|
and is set to remain open across
|
|
\f4exec\fP
|
|
system calls
|
|
[see
|
|
\f4fcntl\fP(2)].
|
|
.PP
|
|
Certain flag values can be set following \f4open\fP as described in \f4fcntl\fP(2).
|
|
.PP
|
|
If \f4O_CREAT\fP is set and the file did not previously exist,
|
|
upon successful completion \f4open\fP marks for update the \f4st_atime\fP,
|
|
\f4st_ctime\fP and \f4st_mtime\fP fields of the file and the \f4st_ctime\fP
|
|
and \f4st_mtime\fP fields of the parent directory.
|
|
.PP
|
|
If \f4O_TRUNC\fP is set and the file did previously exist, upon successful
|
|
completion \f4open\fP marks for update the \f4st_ctime\fP and \f4st_mtime\fP
|
|
fields of the file.
|
|
.P
|
|
There is a system enforced limit on the number
|
|
of open file descriptors per process
|
|
.SM
|
|
\f4{OPEN_MAX}\fP,
|
|
whose value is returned by the
|
|
\f4getdtablesize\fP(2)
|
|
function.
|
|
.P
|
|
The named file is opened unless one or more of the following are true:
|
|
.TP 0.75i
|
|
\f4EACCES\fP
|
|
The file does not exist and write permission is denied by the parent
|
|
directory of the file to be created.
|
|
.TP
|
|
\f4EACCES\fP
|
|
\f4O_CREAT\fP or \f4O_TRUNC\f1
|
|
is specified and write permission is denied.
|
|
.TP
|
|
\f4EACCES\fP
|
|
A component of the
|
|
path prefix
|
|
denies search permission.
|
|
.TP
|
|
\f4EACCES\fP
|
|
The file is a character or block device file and the file system
|
|
in which it resides has been mounted with the
|
|
\f4nodev\fP
|
|
option [see
|
|
\f4fstab\fP(4)].
|
|
.TP
|
|
\f4EACCES\fP
|
|
.I oflag\^
|
|
permission is denied for an existing file.
|
|
.TP
|
|
\f4EAGAIN\fP
|
|
The file exists, \f4O_CREAT\fP or \f4O_TRUNC\fP are specified,
|
|
mandatory file/record locking is set,
|
|
and there are outstanding record locks on the file
|
|
[see \f4chmod\fP(2)].
|
|
.TP
|
|
\f4EBUSY\fP
|
|
\f2path\fP points to a device special file and the device is in the
|
|
closing state.
|
|
.TP
|
|
\f4EDQUOT\fP
|
|
\f4O_CREAT\fP
|
|
is specified,
|
|
the file does not exist,
|
|
and the directory in which the entry for the new file
|
|
is being placed cannot be extended either because the
|
|
user's quota of disk blocks on the file system
|
|
containing the directory has been exhausted or
|
|
the user's quota of inodes on the file system on
|
|
which the file is being created has been exhausted.
|
|
.TP
|
|
\f4EEXIST\fP
|
|
\f4O_CREAT\f1
|
|
and
|
|
\f4O_EXCL\f1
|
|
are set,
|
|
and the named file exists.
|
|
.TP
|
|
\f4EFAULT\fP
|
|
.I path\^
|
|
points outside the allocated address space of the process.
|
|
.TP
|
|
\f4EINTR\fP
|
|
A signal was caught during the
|
|
\f4open\fP
|
|
system call.
|
|
.TP
|
|
\f4EINVAL\fP
|
|
An attempt was made to open a file not in an EFS, XFS or BDS file system
|
|
with \f4O_DIRECT\fP set.
|
|
.TP
|
|
\f4EIO\fP
|
|
A hangup or error occurred during the open of the STREAMS-based device.
|
|
.TP
|
|
\f4EISDIR\fP
|
|
The named file is a directory and
|
|
.I oflag\^
|
|
is write or
|
|
read/write.
|
|
.TP
|
|
\f4ELOOP\fP
|
|
Too many symbolic links were encountered in translating \f2path\f1.
|
|
.TP
|
|
\f4EMFILE\fP
|
|
The process has too many open files [see
|
|
\f4getrlimit\fP(2)].
|
|
.\".TP
|
|
.\"\f4EMULTIHOP\fP
|
|
.\"Components of \f2path\f1 require hopping to
|
|
.\"multiple remote machines and the file system does not allow it.
|
|
.TP
|
|
\f4ENAMETOOLONG\fP
|
|
The length of the \f2path\f1 argument exceeds {\f4PATH_MAX\fP}, or the
|
|
length of a \f2path\f1 component exceeds {\f4NAME_MAX\fP} while
|
|
{\f4_POSIX_NO_TRUNC\fP} is in effect.
|
|
.TP
|
|
\f4ENFILE\fP
|
|
The system file table is full.
|
|
.TP
|
|
\f4ENODEV\fP
|
|
\f2path\fP points to a device special file and the device is not in the
|
|
activated state.
|
|
.TP
|
|
\f4ENOENT\fP
|
|
\f4O_CREAT\f1
|
|
is not set and the named file does not exist.
|
|
.TP
|
|
\f4ENOENT\fP
|
|
\f4O_CREAT\f1
|
|
is set and a component of the path prefix
|
|
does not exist or is the null pathname.
|
|
.\".TP
|
|
.\"\f4ENOLINK\fP
|
|
.\"\f2path\f1 points to a remote machine, and the link
|
|
.\"to that machine is no longer active.
|
|
.TP
|
|
\f4ENOMEM\fP
|
|
The system is unable to allocate a send descriptor.
|
|
.TP
|
|
\f4ENOSPC\fP
|
|
\f4O_CREAT \f1
|
|
and
|
|
\f4O_EXCL\f1
|
|
are set, and the file system is out of inodes or
|
|
the directory in which the entry for the new file is being placed
|
|
cannot be extended because there is no space left on the file
|
|
system containing the directory.
|
|
.TP
|
|
\f4ENOSPC\fP
|
|
\f4O_CREAT\fP is set and the directory that would contain the file
|
|
cannot be extended.
|
|
.TP
|
|
\f4ENOSR\fP
|
|
Unable to allocate a stream.
|
|
.TP
|
|
\f4ENOTDIR\fP
|
|
A component of the
|
|
path prefix
|
|
is not a directory.
|
|
.TP
|
|
\f4ENXIO\fP
|
|
The named file is a character special or block special file,
|
|
and the device associated with this special file does not exist.
|
|
.TP
|
|
\f4ENXIO\fP
|
|
\f4O_NDELAY\f1
|
|
or
|
|
\f4O_NONBLOCK\f1
|
|
is set, the named file is a FIFO,
|
|
\f4O_WRONLY\f1
|
|
is set, and no process has the file open for reading.
|
|
.TP
|
|
\f4ENXIO\fP
|
|
A STREAMS module or driver open routine failed.
|
|
.TP
|
|
\f4EOPNOTSUPP\fP
|
|
An attempt was made to open a socket (not currently supported).
|
|
.TP
|
|
\f4EPERM\fP
|
|
\f2path\fP points to a device special file, the device is in the setup
|
|
state, and the calling process does not have the \f4P_DEV\fP privilege.
|
|
.TP
|
|
\f4ETIMEDOUT\fP
|
|
The object of the open is located on a remote system which is not available [see \f4intro\fP(2)].
|
|
.TP
|
|
\f4EROFS\fP
|
|
The named file resides on a read-only file system and either
|
|
\f4O_WRONLY\f1,
|
|
\f4O_RDWR\f1,
|
|
\f4O_CREAT\f1,
|
|
or
|
|
\f4O_TRUNC\f1
|
|
is set in
|
|
.I oflag\^
|
|
(if the file does not exist).
|
|
.\".TP
|
|
.\"\f4ETXTBSY\fP
|
|
.\"The file is a pure procedure (shared text) file that is being executed and
|
|
.\".I oflag\^
|
|
.\"is write or read/write.
|
|
.SH "SEE ALSO"
|
|
\f4chmod\fP(2),
|
|
\f4close\fP(2),
|
|
\f4creat\fP(2),
|
|
\f4dup\fP(2),
|
|
\f4exec\fP(2),
|
|
\f4fcntl\fP(2),
|
|
\f4getdtablesize\fP(2),
|
|
\f4getmsg\fP(2),
|
|
\f4getrlimit\fP(2),
|
|
\f4intro\fP(2),
|
|
\f4lseek\fP(2),
|
|
\f4putmsg\fP(2),
|
|
\f4read\fP(2),
|
|
\f4stat\fP(2),
|
|
\f4stat\fP(5),
|
|
\f4umask\fP(2),
|
|
\f4write\fP(2)
|
|
.SH "DIAGNOSTICS"
|
|
Upon successful completion,
|
|
the file descriptor
|
|
is returned.
|
|
Otherwise, a value of \-1 is returned and \f4errno\fP
|
|
is set to indicate the error.
|