20060303-partial

1 files changed, 250 insertions, 0 deletions

diff --git a/man/5/open b/man/5/open
new file mode 100644
index 00000000..5551384e
--- /dev/null
+++ b/man/5/open
@@ -0,0 +1,250 @@
+.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)