1 files changed, 249 insertions, 0 deletions
diff --git a/man/man9/open.9p b/man/man9/open.9p
new file mode 100644
index 00000000..b8ed973a
--- /dev/null
+++ b/man/man9/open.9p
@@ -0,0 +1,249 @@
+.TH OPEN 9P 
+.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 (9P)),
+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 fscreate
+call
+(see
+.IR 9pclient (3))
+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 (9P).
+.SH ENTRY POINTS
+.I Fsopen
+and
+.I fscreate
+(see
+.IR 9pclient (3))
+both generate
+.B open
+messages; only
+.I fscreate
+generates a
+.B create
+message.
+The
+.B iounit
+associated with an open file may be discovered by calling
+.IR fsiounit .
+.PP
+For programs that need atomic file creation, without the race
+that exists in the
+.B open-create
+sequence described above,
+.IR fscreate
+does the following.
+If the
+.B OEXCL
+.RB ( 0x1000 )
+bit is set in the
+.I mode
+for a
+.I fscreate
+call,
+the
+.B open
+message is not sent; the kernel issues only the
+.BR create .
+Thus, if the file exists,
+.I fscreate
+will draw an error, but if it doesn't and the
+.I fscreate
+call succeeds, the process issuing the
+.I fscreate
+is guaranteed to be the one that created the file.