154 lines
8.3 KiB
HTML
154 lines
8.3 KiB
HTML
<head>
|
|
<title>open(9P) - Plan 9 from User Space</title>
|
|
<meta content="text/html; charset=utf-8" http-equiv=Content-Type>
|
|
</head>
|
|
<body bgcolor=#ffffff>
|
|
<table border=0 cellpadding=0 cellspacing=0 width=100%>
|
|
<tr height=10><td>
|
|
<tr><td width=20><td>
|
|
<tr><td width=20><td><b>OPEN(9P)</b><td align=right><b>OPEN(9P)</b>
|
|
<tr><td width=20><td colspan=2>
|
|
<br>
|
|
<p><font size=+1><b>NAME </b></font><br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
open, create – prepare a fid for I/O on an existing or new file<br>
|
|
|
|
</table>
|
|
<p><font size=+1><b>SYNOPSIS </b></font><br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
<i>size</i>[4] <tt><font size=+1>Topen</font></tt> <i>tag</i>[2] <i>fid</i>[4] <i>mode</i>[1]<br>
|
|
<i>size</i>[4] <tt><font size=+1>Ropen</font></tt> <i>tag</i>[2] <i>qid</i>[13] <i>iounit</i>[4]
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
<i>size</i>[4] <tt><font size=+1>Tcreate</font></tt> <i>tag</i>[2] <i>fid</i>[4] <i>name</i>[<i>s</i>] <i>perm</i>[4] <i>mode</i>[1]<br>
|
|
<i>size</i>[4] <tt><font size=+1>Rcreate</font></tt> <i>tag</i>[2] <i>qid</i>[13] <i>iounit</i>[4]<br>
|
|
|
|
</table>
|
|
<p><font size=+1><b>DESCRIPTION </b></font><br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
The <tt><font size=+1>open</font></tt> request asks the file server to check permissions and
|
|
prepare a fid for I/O with subsequent <tt><font size=+1>read</font></tt> and <tt><font size=+1>write</font></tt> messages.
|
|
The <i>mode</i> field determines the type of I/O: 0 (called <tt><font size=+1>OREAD</font></tt> in
|
|
<tt><font size=+1><libc.h></font></tt>), 1 (<tt><font size=+1>OWRITE</font></tt>), 2 (<tt><font size=+1>ORDWR</font></tt>), and 3 (<tt><font size=+1>OEXEC</font></tt>) mean <i>read access,
|
|
write access, read and write access,</i> and <i>execute
|
|
access,</i> to be checked against the permissions for the file. In
|
|
addition, if <i>mode</i> has the <tt><font size=+1>OTRUNC</font></tt> (<tt><font size=+1>0x10</font></tt>) bit set, the file is to
|
|
be truncated, which requires write permission (if the file is
|
|
append-only, and permission is granted, the <tt><font size=+1>open</font></tt> succeeds but
|
|
the file will not be truncated); if the <i>mode</i> has the <tt><font size=+1>ORCLOSE</font></tt> (<tt><font size=+1>0x40</font></tt>)
|
|
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</i> 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 <i>stat</i>(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</i> has been clunked. All these
|
|
permissions are checked at the time of the <tt><font size=+1>open</font></tt> request; subsequent
|
|
changes to the permissions of files do not affect the ability
|
|
to read, write, or remove an open file.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
The <tt><font size=+1>create</font></tt> request asks the file server to create a new file with
|
|
the <i>name</i> supplied, in the directory (<i>dir</i>) represented by <i>fid</i>,
|
|
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 <i>dir</i>, and the permissions are the value of
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
<tt><font size=+1>perm & (~0666 | (dir.perm & 0666)) <br>
|
|
</font></tt>
|
|
</table>
|
|
|
|
</table>
|
|
if a regular file is being created and<br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
<tt><font size=+1>perm & (~0777 | (dir.perm & 0777)) <br>
|
|
</font></tt>
|
|
</table>
|
|
|
|
</table>
|
|
if a directory is being created. This means, for example, that
|
|
if the <tt><font size=+1>create</font></tt> allows read permission to others, but the containing
|
|
directory does not, then the created file will not allow others
|
|
to read the file.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
Finally, the newly created file is opened according to <i>mode</i>, and
|
|
<i>fid</i> will represent the newly opened file. <i>Mode</i> is not checked
|
|
against the permissions in <i>perm</i>. The <i>qid</i> for the new file is returned
|
|
with the <tt><font size=+1>create</font></tt> reply message.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
Directories are created by setting the <tt><font size=+1>DMDIR</font></tt> bit (<tt><font size=+1>0x80000000</font></tt>)
|
|
in the <i>perm</i>.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
The names <tt><font size=+1>.</font></tt> and <tt><font size=+1>..</font></tt> are special; it is illegal to create files
|
|
with these names.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
It is an error for either of these messages if the fid is already
|
|
the product of a successful <tt><font size=+1>open</font></tt> or <tt><font size=+1>create</font></tt> message.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
An attempt to <tt><font size=+1>create</font></tt> a file in a directory where the given <i>name</i>
|
|
already exists will be rejected; in this case, the <i>fscreate</i> call
|
|
(see <a href="../man3/9pclient.html"><i>9pclient</i>(3)</a>) uses <tt><font size=+1>open</font></tt> with truncation. The algorithm used
|
|
by the <i>create</i> system call is: first walk to the directory to contain
|
|
the file. If that fails, return an error. Next <tt><font size=+1>walk</font></tt> to the
|
|
specified file. If the <tt><font size=+1>walk</font></tt> succeeds, send a request to <tt><font size=+1>open</font></tt> and
|
|
truncate the file and return the result, successful or not. If
|
|
the <tt><font size=+1>walk</font></tt> 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 <tt><font size=+1>walk</font></tt> and <tt><font size=+1>open</font></tt> again.
|
|
|
|
</table>
|
|
<p><font size=+1><b>ENTRY POINTS </b></font><br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
<i>Fsopen</i> and <i>fscreate</i> (see <a href="../man3/9pclient.html"><i>9pclient</i>(3)</a>) both generate <tt><font size=+1>open</font></tt> messages;
|
|
only <i>fscreate</i> generates a <tt><font size=+1>create</font></tt> message. The <tt><font size=+1>iounit</font></tt> associated
|
|
with an open file may be discovered by calling <i>fsiounit</i>.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
For programs that need atomic file creation, without the race
|
|
that exists in the <tt><font size=+1>open−create</font></tt> sequence described above, <i>fscreate</i>
|
|
does the following. If the <tt><font size=+1>OEXCL</font></tt> (<tt><font size=+1>0x1000</font></tt>) bit is set in the <i>mode</i>
|
|
for a <i>fscreate</i> call, the <tt><font size=+1>open</font></tt> message is not sent; the kernel
|
|
issues only the <tt><font size=+1>create</font></tt>. Thus, if the file exists, <i>fscreate
|
|
</i>will draw an error, but if it doesn’t and the <i>fscreate</i> call succeeds,
|
|
the process issuing the <i>fscreate</i> is guaranteed to be the one that
|
|
created the file.<br>
|
|
|
|
</table>
|
|
|
|
<td width=20>
|
|
<tr height=20><td>
|
|
</table>
|
|
<!-- TRAILER -->
|
|
<table border=0 cellpadding=0 cellspacing=0 width=100%>
|
|
<tr height=15><td width=10><td><td width=10>
|
|
<tr><td><td>
|
|
<center>
|
|
<a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a>
|
|
</center>
|
|
</table>
|
|
<!-- TRAILER -->
|
|
</body></html>
|