149 lines
3.3 KiB
Plaintext
149 lines
3.3 KiB
Plaintext
.TH OPEN 2
|
|
.SH NAME
|
|
open, create, close \- open a file for reading or writing, create file
|
|
.SH SYNOPSIS
|
|
.B #include <u.h>
|
|
.br
|
|
.B #include <libc.h>
|
|
.PP
|
|
.B
|
|
int open(char *file, int omode)
|
|
.PP
|
|
.B
|
|
int create(char *file, int omode, ulong perm)
|
|
.PP
|
|
.B
|
|
int close(int fd)
|
|
.SH DESCRIPTION
|
|
.I Open
|
|
opens the
|
|
.I file
|
|
for I/O and returns an associated file descriptor.
|
|
.I Omode
|
|
is one of
|
|
.BR OREAD ,
|
|
.BR OWRITE ,
|
|
.BR ORDWR ,
|
|
or
|
|
.BR OEXEC ,
|
|
asking for permission to read, write, read and write, or execute, respectively.
|
|
In addition, there are three values that can be ORed with the
|
|
.IR omode :
|
|
.B OTRUNC
|
|
says to truncate the file
|
|
to zero length before opening it;
|
|
.B OCEXEC
|
|
says to close the file when an
|
|
.IR exec (2)
|
|
or
|
|
.I execl
|
|
system call is made;
|
|
and
|
|
.B ORCLOSE
|
|
says to remove the file when it is closed (by everyone who has a copy of the file descriptor).
|
|
.I Open
|
|
fails if the file does not exist or the user does not have
|
|
permission to open it for the requested purpose
|
|
(see
|
|
.IR stat (2)
|
|
for a description of permissions).
|
|
The user must have write permission on the
|
|
.I file
|
|
if the
|
|
.B OTRUNC
|
|
bit is set.
|
|
For the
|
|
.I open
|
|
system call
|
|
(unlike the implicit
|
|
.I open
|
|
in
|
|
.IR exec (2)),
|
|
.B OEXEC
|
|
is actually identical to
|
|
.BR OREAD .
|
|
.PP
|
|
.I Create
|
|
creates a new
|
|
.I file
|
|
or prepares to rewrite an existing
|
|
.IR file ,
|
|
opens it according to
|
|
.I omode
|
|
(as described for
|
|
.IR open ),
|
|
and returns an associated file descriptor.
|
|
If the file is new,
|
|
the owner is set to the userid of the creating process group;
|
|
the group to that of the containing directory;
|
|
the permissions to
|
|
.I perm
|
|
ANDed with the permissions of the containing directory.
|
|
If the file already exists,
|
|
it is truncated to 0 length,
|
|
and the permissions, owner, and group remain unchanged.
|
|
The created file is a directory if the
|
|
.B DMDIR
|
|
bit is set in
|
|
.IR perm ,
|
|
an exclusive-use file if the
|
|
.B DMEXCL
|
|
bit is set, and an append-only file if the
|
|
.B DMAPPEND
|
|
bit is set.
|
|
Exclusive-use files may be open for I/O by only one client at a time,
|
|
but the file descriptor may become invalid if no I/O is done
|
|
for an extended period; see
|
|
.IR open (5).
|
|
.PP
|
|
.I Create
|
|
fails if the path up to the last element of
|
|
.I file
|
|
cannot be evaluated, if the user doesn't have write permission
|
|
in the final directory, if the file already exists and
|
|
does not permit the access defined by
|
|
.IR omode ,
|
|
or if there are no free file descriptors.
|
|
In the last case, the file may be created even when
|
|
an error is returned.
|
|
If the file is new and the directory in which it is created is
|
|
a union directory (see
|
|
.IR intro (2))
|
|
then the constituent directory where the file is created
|
|
depends on the structure of the union: see
|
|
.IR bind (2).
|
|
.PP
|
|
Since
|
|
.I create
|
|
may succeed even if the file exists, a special mechanism is necessary
|
|
for those applications that require an atomic create operation.
|
|
If the
|
|
.B OEXCL
|
|
.RB ( 0x1000 )
|
|
bit is set in the
|
|
.I mode
|
|
for a
|
|
.IR create,
|
|
the call succeeds only if the file does not already exist;
|
|
see
|
|
.IR open (5)
|
|
for details.
|
|
.PP
|
|
.I Close
|
|
closes the file associated with a file descriptor.
|
|
Provided the file descriptor is a valid open descriptor,
|
|
.I close
|
|
is guaranteed to close it; there will be no error.
|
|
Files are closed automatically upon termination of a process;
|
|
.I close
|
|
allows the file descriptor to be reused.
|
|
.SH SOURCE
|
|
.B /sys/src/libc/9syscall
|
|
.SH SEE ALSO
|
|
.IR intro (2),
|
|
.IR bind (2),
|
|
.IR stat (2)
|
|
.SH DIAGNOSTICS
|
|
These functions set
|
|
.IR errstr .
|