247 lines
4.6 KiB
Text
247 lines
4.6 KiB
Text
.TH OPEN 5
|
|
.SH NAME
|
|
open, create \- prepare a fid for I/O on an existing or new file
|
|
.SH SYNOPSIS
|
|
.ta \w'\fLTcreate 'u
|
|
.IR size [4]
|
|
.B Topen
|
|
.IR tag [2]
|
|
.IR fid [4]
|
|
.IR mode [1]
|
|
.br
|
|
.IR size [4]
|
|
.B Ropen
|
|
.IR tag [2]
|
|
.IR qid [13]
|
|
.IR iounit [4]
|
|
.PP
|
|
.IR size [4]
|
|
.B Tcreate
|
|
.IR tag [2]
|
|
.IR fid [4]
|
|
.IR name [ s ]
|
|
.IR perm [4]
|
|
.IR mode [1]
|
|
.br
|
|
.IR size [4]
|
|
.B Rcreate
|
|
.IR tag [2]
|
|
.IR qid [13]
|
|
.IR iounit [4]
|
|
.SH DESCRIPTION
|
|
The
|
|
.B open
|
|
request asks the file server to check permissions and
|
|
prepare a fid for I/O with subsequent
|
|
.B read
|
|
and
|
|
.B write
|
|
messages.
|
|
The
|
|
.I mode
|
|
field determines the type of I/O:
|
|
0
|
|
(called
|
|
.BR OREAD
|
|
in
|
|
.BR <libc.h> ),
|
|
1
|
|
.RB ( OWRITE ),
|
|
2
|
|
.RB ( ORDWR ),
|
|
and 3
|
|
.RB ( OEXEC )
|
|
mean
|
|
.I
|
|
read access, write access, read and write access,
|
|
and
|
|
.I
|
|
execute access,
|
|
to be checked against the permissions for the file.
|
|
In addition, if
|
|
.I mode
|
|
has the
|
|
.B OTRUNC
|
|
.RB ( 0x10 )
|
|
bit set,
|
|
the file is to be truncated, which requires write permission
|
|
(if
|
|
the file is append-only, and permission is granted, the
|
|
.B open
|
|
succeeds but the file will not be truncated);
|
|
if the
|
|
.I mode
|
|
has the
|
|
.B ORCLOSE
|
|
.RB ( 0x40 )
|
|
bit set, the file is to be removed when the fid
|
|
is clunked, which requires permission to remove the file from its directory.
|
|
All other bits in
|
|
.I mode
|
|
should be zero.
|
|
It is illegal to write a directory, truncate it, or attempt to remove it on close.
|
|
If the file is marked for exclusive use (see
|
|
.IR stat (5)),
|
|
only one client can have the file open at any time.
|
|
That is, after such a file has been opened,
|
|
further opens will fail until
|
|
.I fid
|
|
has been clunked.
|
|
All these permissions are checked at the time of the
|
|
.B open
|
|
request; subsequent changes to the permissions of files do not affect
|
|
the ability to read, write, or remove an open file.
|
|
.PP
|
|
The
|
|
.B create
|
|
request asks the file server to create a new file
|
|
with the
|
|
.I name
|
|
supplied, in the directory
|
|
.RI ( dir )
|
|
represented by
|
|
.IR fid ,
|
|
and requires write permission in the directory.
|
|
The owner of the file is the implied user id of the request,
|
|
the group of the file is the same as
|
|
.IR dir ,
|
|
and the permissions are the value of
|
|
.ce
|
|
.B "perm & (~0666 | (dir.perm & 0666))"
|
|
if a regular file is being created and
|
|
.ce
|
|
.B "perm & (~0777 | (dir.perm & 0777))"
|
|
if a directory is being created.
|
|
This means, for example, that if the
|
|
.B create
|
|
allows read permission to others, but the containing directory
|
|
does not, then the created file will not allow others to read the file.
|
|
.PP
|
|
Finally, the newly created file is opened according to
|
|
.IR mode ,
|
|
and
|
|
.I fid
|
|
will represent the newly opened file.
|
|
.I Mode
|
|
is not checked against the permissions in
|
|
.IR perm .
|
|
The
|
|
.I qid
|
|
for the new file is returned with the
|
|
.B create
|
|
reply message.
|
|
.PP
|
|
Directories are created by setting the
|
|
.B DMDIR
|
|
bit
|
|
.RB ( 0x80000000 )
|
|
in the
|
|
.IR perm .
|
|
.PP
|
|
The names
|
|
.B .
|
|
and
|
|
.B ..
|
|
are special; it is illegal to create files with these names.
|
|
.PP
|
|
It is an error for either of these messages if the fid
|
|
is already the product of a successful
|
|
.B open
|
|
or
|
|
.B create
|
|
message.
|
|
.PP
|
|
An attempt to
|
|
.B create
|
|
a file in a directory where the given
|
|
.I name
|
|
already exists will be rejected;
|
|
in this case, the
|
|
.I create
|
|
system call
|
|
(see
|
|
.IR open (2))
|
|
uses
|
|
.B open
|
|
with truncation.
|
|
The algorithm used by the
|
|
.IR create
|
|
system call
|
|
is:
|
|
first walk to the directory to contain the file.
|
|
If that fails, return an error.
|
|
Next
|
|
.B walk
|
|
to the specified file.
|
|
If the
|
|
.B walk
|
|
succeeds, send a request to
|
|
.B open
|
|
and truncate the file and return the result, successful or not.
|
|
If the
|
|
.B walk
|
|
fails, send a create message.
|
|
If that fails, it may be because the file was created by another
|
|
process after the previous walk failed, so (once) try the
|
|
.B walk
|
|
and
|
|
.B open
|
|
again.
|
|
.PP
|
|
For the behavior of
|
|
.I create
|
|
on a union directory, see
|
|
.IR bind (2).
|
|
.PP
|
|
The
|
|
.B iounit
|
|
field returned by
|
|
.B open
|
|
and
|
|
.B create
|
|
may be zero.
|
|
If it is not, it is the maximum number of bytes that are guaranteed to
|
|
be read from or written to the file without breaking the I/O transfer
|
|
into multiple 9P messages; see
|
|
.IR read (5).
|
|
.SH ENTRY POINTS
|
|
.I Open
|
|
and
|
|
.I create
|
|
both generate
|
|
.B open
|
|
messages; only
|
|
.I create
|
|
generates a
|
|
.B create
|
|
message.
|
|
The
|
|
.B iounit
|
|
associated with an open file may be discovered by calling
|
|
.IR iounit (2).
|
|
.PP
|
|
For programs that need atomic file creation, without the race
|
|
that exists in the
|
|
.B open-create
|
|
sequence described above,
|
|
the kernel does the following.
|
|
If the
|
|
.B OEXCL
|
|
.RB ( 0x1000 )
|
|
bit is set in the
|
|
.I mode
|
|
for a
|
|
.B create
|
|
system call,
|
|
the
|
|
.B open
|
|
message is not sent; the kernel issues only the
|
|
.BR create .
|
|
Thus, if the file exists,
|
|
.B create
|
|
will draw an error, but if it doesn't and the
|
|
.B create
|
|
system call succeeds, the process issuing the
|
|
.B create
|
|
is guaranteed to be the one that created the file.
|
|
|