OPEN(5) OPEN(5)
NAME
open, create - prepare a fid for I/O on an existing or new
file
SYNOPSIS
size[4] Topen tag[2] fid[4] mode[1]
size[4] Ropen tag[2] qid[13] iounit[4]
size[4] Tcreate tag[2] fid[4] name[s] perm[4] mode[1]
size[4] Rcreate tag[2] qid[13] iounit[4]
DESCRIPTION
The open request asks the file server to check permissions
and prepare a fid for I/O with subsequent read and write
messages. The mode field determines the type of I/O: 0
(called OREAD in Sys), 1 (OWRITE), 2 (ORDWR), and 3 (OEXEC)
mean read access, write access, read and write access, and
execute access, to be checked against the permissions for
the file. In addition, if mode has the OTRUNC (16r10) bit
set, the file is to be truncated, which requires write per-
mission (if the file is append-only, and permission is
granted, the open succeeds but the file will not be trun-
cated); if the mode has the ORCLOSE (16r40) 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 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
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 fid has been clunked. All these per-
missions are checked at the time of the open request; subse-
quent changes to the permissions of files do not affect the
ability to read, write, or remove an open file.
The create request asks the file server to create a new file
with the name supplied, in the directory (dir) represented
by 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 dir, and the permissions
are the value of
perm & (~8r666 | (dir.perm & 8r666))
if a regular file is being created and
perm & (~8r777 | (dir.perm & 8r777))
if a directory is being created. This means, for example,
that if the create allows read permission to others, but the
containing directory does not, then the created file will
not allow others to read the file.
Finally, the newly created file is opened according to mode,
Page 1 Plan 9 (printed 12/22/24)
OPEN(5) OPEN(5)
and fid will represent the newly opened file. Mode is not
checked against the permissions in perm. The qid for the new
file is returned with the create reply message.
Directories are created by setting the DMDIR bit
(16r80000000) in the perm.
The names . and .. are special; it is illegal to create
files with these names.
It is an error for either of these messages if the fid is
already the product of a successful open or create message.
An attempt to create a file in a directory where the given
name already exists will be rejected; in this case, the
create system call (see sys-open(2)) uses open with trunca-
tion. The algorithm used by the create system call is:
first walk to the directory to contain the file. If that
fails, return an error. Next walk to the specified file.
If the walk succeeds, send a request to open and truncate
the file and return the result, successful or not. If the
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 walk and open again.
For the behavior of create on a union directory, see sys-
bind(2).
The iounit field returned by open and 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 Styx messages; see
read(5).
ENTRY POINTS
Open and create both generate open messages; only create
generates a create message. The iounit associated with an
open file may be discovered by calling sys-iounit(2).
For programs that need atomic file creation, without the
race that exists in the open-create sequence described
above, the kernel does the following. If the OEXCL
(16r1000) bit is set in the mode for a create system call,
the open message is not sent; the kernel issues only the
create. Thus, if the file exists, create will draw an
error, but if it doesn't and the create system call suc-
ceeds, the process issuing the create is guaranteed to be
the one that created the file.
SEE ALSO
sys-bind(2), sys-open(2), stat(5)
Page 2 Plan 9 (printed 12/22/24)