.TH OPEN 5 .SH NAMEopen, 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 DESCRIPTIONThe.B openrequest asks the file server to check permissions andprepare a fid for I/O with subsequent.B readand.B writemessages.The.I modefield determines the type of I/O:0(called.BR OREADin.BR Sys ),1.RB ( OWRITE ),2.RB ( ORDWR ),and 3.RB ( OEXEC )mean.Iread access, write access, read and write access,and.Iexecute access,to be checked against the permissions for the file.In addition, if.I modehas the.B OTRUNC.RB ( 16r10 )bit set,the file is to be truncated, which requires write permission(ifthe file is append-only, and permission is granted, the.B opensucceeds but the file will not be truncated);if the.I modehas the.B ORCLOSE.RB ( 16r40 )bit set, the file is to be removed when the fidis clunked, which requires permission to remove the file from its directory.All other bits in.I modeshould 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 fidhas been clunked.All these permissions are checked at the time of the.B openrequest; subsequent changes to the permissions of files do not affectthe ability to read, write, or remove an open file..PPThe .B createrequest asks the file server to create a new filewith the .I namesupplied, 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 & (~8r666 | (dir.perm & 8r666))"if a regular file is being created and.ce.B "perm & (~8r777 | (dir.perm & 8r777))"if a directory is being created.This means, for example, that if the.B createallows read permission to others, but the containing directorydoes not, then the created file will not allow others to read the file..PPFinally, the newly created file is opened according to.IR mode ,and.I fidwill represent the newly opened file..I Modeis not checked against the permissions in.IR perm .The.I qidfor the new file is returned with the.B createreply message..PPDirectories are created by setting the.B DMDIRbit.RB ( 16r80000000 )in the.IR perm ..PPThe names.B .and.B ..are special; it is illegal to create files with these names..PPIt is an error for either of these messages if the fidis already the product of a successful.B openor.B createmessage..PPAn attempt to.B createa file in a directory where the given.I namealready exists will be rejected;in this case, the.I createsystem call(see.IR sys-open (2))uses.B openwith truncation.The algorithm used by the.IR createsystem callis:first walk to the directory to contain the file.If that fails, return an error.Next.B walkto the specified file.If the.B walksucceeds, send a request to.B openand truncate the file and return the result, successful or not.If the.B walkfails, send a create message.If that fails, it may be because the file was created by anotherprocess after the previous walk failed, so (once) try the.B walkand.B openagain..PPFor the behavior of.I createon a union directory, see.IR sys-bind (2)..PPThe.B iounitfield returned by.B openand.B createmay be zero.If it is not, it is the maximum number of bytes that are guaranteed tobe read from or written to the file without breaking the I/O transferinto multiple Styx messages; see.IR read (5)..SH ENTRY POINTS.I Openand.I createboth generate.B openmessages; only.I creategenerates a.B createmessage.The.B iounitassociated with an open file may be discovered by calling.IR sys-iounit (2)..PPFor programs that need atomic file creation, without the racethat exists in the.B open-createsequence described above,the kernel does the following.If the.B OEXCL.RB ( 16r1000 )bit is set in the.I modefor a.B createsystem call,the.B openmessage is not sent; the kernel issues only the.BR create .Thus, if the file exists,.B createwill draw an error, but if it doesn't and the.B createsystem call succeeds, the process issuing the.B createis guaranteed to be the one that created the file..SH SEE ALSO.IR sys-bind (2),.IR sys-open (2),.IR stat (5)
.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 Sys ),
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 ( 16r10 )
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 ( 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
.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 & (~8r666 | (dir.perm & 8r666))"
if a regular file is being created and
.ce
.B "perm & (~8r777 | (dir.perm & 8r777))"
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 ( 16r80000000 )
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 sys-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 sys-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 Styx 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 sys-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 ( 16r1000 )
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.
.SH SEE ALSO
.IR sys-bind (2),
.IR sys-open (2),
.IR stat (5)