258 lines
10 KiB
HTML
258 lines
10 KiB
HTML
<head>
|
|
<title>9p-file(3) - 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>9P-FILE(3)</b><td align=right><b>9P-FILE(3)</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>
|
|
|
|
Tree, alloctree, freetree, File, createfile, closefile, removefile,
|
|
walkfile, opendirfile, readdirfile, closedirfile, hasperm – in-memory
|
|
file hierarchy<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>
|
|
|
|
<tt><font size=+1>#include <u.h><br>
|
|
#include <libc.h><br>
|
|
#include <fcall.h><br>
|
|
#include <thread.h><br>
|
|
#include <9p.h><br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
typedef struct File<br>
|
|
{<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>
|
|
|
|
Ref;<br>
|
|
Dir;<br>
|
|
void*aux;<br>
|
|
|
|
</table>
|
|
|
|
</table>
|
|
</font></tt>
|
|
<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>
|
|
|
|
<i>...<br>
|
|
</i>
|
|
</table>
|
|
|
|
</table>
|
|
<tt><font size=+1>} File;<br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
typedef struct Tree<br>
|
|
{<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>
|
|
|
|
File *root;<br>
|
|
|
|
</table>
|
|
|
|
</table>
|
|
</font></tt>
|
|
<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>
|
|
|
|
<i>...<br>
|
|
</i>
|
|
</table>
|
|
|
|
</table>
|
|
<tt><font size=+1>} Tree;<br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
Tree* alloctree(char *uid, char *gid, ulong mode,<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>
|
|
|
|
void (*destroy)(File*))<br>
|
|
|
|
</table>
|
|
|
|
</table>
|
|
void freetree(Tree *tree)<br>
|
|
File* createfile(File *dir, char *name, char *uid,<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>
|
|
|
|
ulong mode, void *aux)<br>
|
|
|
|
</table>
|
|
|
|
</table>
|
|
int removefile(File *file)<br>
|
|
void closefile(File *file)<br>
|
|
File* walkfile(File *dir, char *path)<br>
|
|
Readdir* opendirfile(File *dir)<br>
|
|
long readdirfile(Readdir *rdir, char *buf, long n)<br>
|
|
void closedirfile(Readdir *rdir)<br>
|
|
int hasperm(File *file, char *uid, int p)<br>
|
|
</font></tt>
|
|
</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>
|
|
|
|
<tt><font size=+1>File</font></tt>s and <tt><font size=+1>Tree</font></tt>s provide an in-memory file hierarchy intended for
|
|
use in 9P file servers.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
<i>Alloctree</i> creates a new tree of files, and <i>freetree</i> destroys it.
|
|
The root of the tree (also the <tt><font size=+1>root</font></tt> element in the structure)
|
|
will have mode <i>mode</i> and be owned by user <i>uid</i> and group <i>gid</i>. <i>Destroy</i>
|
|
is used when freeing <tt><font size=+1>File</font></tt> structures and is described later.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
<tt><font size=+1>File</font></tt>s (including directories) other than the root are created
|
|
using <i>createfile</i>, which attempts to create a file named <i>name</i> in
|
|
the directory <i>dir</i>. If created, the file will have owner <i>uid</i> and
|
|
have a group inherited from the directory. <i>Mode</i> and the permissions
|
|
of <i>dir</i> are used to calculate the permission bits for the file
|
|
as
|
|
described in <i>open</i>(9p). It is permissible for <i>name</i> to be a slash-separated
|
|
path rather than a single element.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
<i>Removefile</i> removes a file from the file tree. The file will not
|
|
be freed until the last reference to it has been removed. Directories
|
|
may only be removed when empty. <i>Removefile</i> returns zero on success,
|
|
–1 on error. It is correct to consider <i>removefile</i> to be <i>closefile</i>
|
|
with the side effect of removing the file when possible.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
<i>Walkfile</i> evaluates <i>path</i> relative to the directory <i>dir</i>, returning
|
|
the resulting file, or zero if the named file or any intermediate
|
|
element does not exist.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
The <tt><font size=+1>File</font></tt> structure’s <tt><font size=+1>aux</font></tt> pointer may be used by the client for
|
|
per-<tt><font size=+1>File</font></tt> storage. <tt><font size=+1>File</font></tt>s are reference-counted: if not zero, <i>destroy</i>
|
|
(specified in the call to <i>alloctree</i>) will be called for each file
|
|
when its last reference is removed or when the tree is freed.
|
|
<i>Destroy</i> should take care of any necessary cleanup related to
|
|
<tt><font size=+1>aux</font></tt>. When creating new file references by copying pointers, call
|
|
<i>incref</i> (see <a href="../man3/lock.html"><i>lock</i>(3)</a>) to update the reference count. To note the
|
|
removal of a reference to a file, call <i>closefile</i>. <i>Createfile</i> and
|
|
<i>walkfile</i> return new references. <i>Removefile</i>, <i>closefile</i>, and <i>walkfile</i>
|
|
(but not <i>createfile</i>) consume the passed reference.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
Directories may be read, yielding a directory entry structure
|
|
(see <i>stat</i>(9p)) for each file in the directory. In order to allow
|
|
concurrent reading of directories, clients must obtain a <tt><font size=+1>Readdir</font></tt>
|
|
structure by calling <i>opendirfile</i> on a directory. Subsequent calls
|
|
to <i>readdirfile</i> will each yield an integral number of machine-
|
|
independent stat buffers, until end of directory. When finished,
|
|
call <i>closedirfile</i> to free the <tt><font size=+1>Readdir</font></tt>.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
<i>Hasperm</i> does simplistic permission checking; it assumes only one-user
|
|
groups named by uid and returns non-zero if <i>uid</i> has permission
|
|
<i>p</i> (a bitwise-or of <tt><font size=+1>AREAD</font></tt>, <tt><font size=+1>AWRITE</font></tt> and <tt><font size=+1>AEXEC</font></tt>) according to <i>file</i><tt><font size=+1>−>mode</font></tt>.
|
|
9P servers written using <tt><font size=+1>File</font></tt> trees will do standard permission
|
|
checks automatically; <i>hasperm</i> may be
|
|
called explicitly to do additional checks. A 9P server may link
|
|
against a different <i>hasperm</i> implementation to provide more complex
|
|
groups.<br>
|
|
|
|
</table>
|
|
<p><font size=+1><b>EXAMPLE </b></font><br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
The following code correctly handles references when elementwise
|
|
walking a path and creating a file.<br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
<tt><font size=+1>f = tree−>root;<br>
|
|
incref(f);<br>
|
|
for(i=0; i<n && f!=nil; i++)<br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
f = walkfile(f, elem[i]);<br>
|
|
|
|
</table>
|
|
if(f == nil)<br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
return nil;<br>
|
|
|
|
</table>
|
|
nf = createfile(f, "foo", "nls", 0666, nil);<br>
|
|
closefile(f);<br>
|
|
return nf;<br>
|
|
</font></tt>
|
|
</table>
|
|
|
|
</table>
|
|
<p><font size=+1><b>SOURCE </b></font><br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
<tt><font size=+1>/usr/local/plan9/src/lib9p/file.c<br>
|
|
</font></tt>
|
|
</table>
|
|
<p><font size=+1><b>SEE ALSO </b></font><br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
<a href="../man3/9p.html"><i>9p</i>(3)</a><br>
|
|
|
|
</table>
|
|
<p><font size=+1><b>BUGS </b></font><br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
The reference counting is cumbersome.<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>
|