ref: 6280c0f17bf3919cf6c2506fec6edfa0a7ec10fe
dir: /sys/man/2/9pfile/
.TH 9PFILE 2 .SH NAME Tree, alloctree, freetree, File, createfile, closefile, removefile, walkfile, opendirfile, readdirfile, closedirfile, hasperm \- in-memory file hierarchy .SH SYNOPSIS .ft L .nf #include <u.h> #include <libc.h> #include <fcall.h> #include <thread.h> #include <9p.h> .fi .PP .ft L .nf .ta \w'\fLFile 'u typedef struct File { Ref; Dir; void *aux; \fI...\fP } File; .fi .PP .ft L .nf .ta \w'\fLTree 'u typedef struct Tree { File *root; \fI...\fP } Tree; .fi .PP .ft L .nf .ta \w'\fLReaddir* 'u +4n +4n Tree* alloctree(char *uid, char *gid, ulong mode, void (*destroy)(File*)) void freetree(Tree *tree) File* createfile(File *dir, char *name, char *uid, ulong mode, void *aux) int removefile(File *file) void closefile(File *file) File* walkfile(File *dir, char *path) Readdir* opendirfile(File *dir) long readdirfile(Readdir *rdir, uchar *buf, long n, long o) void closedirfile(Readdir *rdir) int hasperm(File *file, char *uid, int p) .fi .SH DESCRIPTION .BR File s and .BR Tree s provide an in-memory file hierarchy intended for use in 9P file servers. .PP .I Alloctree creates a new tree of files, and .I freetree destroys it. The root of the tree (also the .B root element in the structure) will have mode .I mode and be owned by user .I uid and group .IR gid . .I Destroy is used when freeing .B File structures and is described later. .PP .BR File s (including directories) other than the root are created using .IR createfile , which attempts to create a file named .I name in the directory .IR dir . If created, the file will have owner .I uid and have a group inherited from the directory. .I Mode and the permissions of .I dir are used to calculate the permission bits for the file as described in .IR open (5). It is permissible for .I name to be a slash-separated path rather than a single element. .PP .I Removefile 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 returns zero on success, \-1 on error. It is correct to consider .I removefile to be .I closefile with the side effect of removing the file when possible. .PP .I Walkfile evaluates .I path relative to the directory .IR dir , returning the resulting file, or zero if the named file or any intermediate element does not exist. .PP The .B File structure's .B aux pointer may be used by the client for .RB per- File storage. .BR File s are reference-counted: if not zero, .I destroy (specified in the call to .IR alloctree ) will be called for each file when its last reference is removed or when the tree is freed. .I Destroy should take care of any necessary cleanup related to .BR aux . When creating new file references by copying pointers, call .I incref (see .IR lock (2)) to update the reference count. To note the removal of a reference to a file, call .IR closefile . .I Createfile and .I walkfile return new references. .IR Removefile , .IR closefile , and .I walkfile (but not .IR createfile ) consume the passed reference. .PP Directories may be read, yielding a directory entry structure (see .IR stat (5)) for each file in the directory. In order to allow concurrent reading of directories, clients must obtain a .B Readdir structure by calling .I opendirfile on a directory. Subsequent calls to .I readdirfile will each yield an integral number of machine-independent stat buffers, until end of directory. When finished, call .I closedirfile to free the .BR Readdir . .PP .I Hasperm does simplistic permission checking; it assumes only one-user groups named by uid and returns non-zero if .I uid has permission .I p (a bitwise-or of .BR AREAD , .BR AWRITE and .BR AEXEC ) according to .IB file ->mode \fR. 9P servers written using .B File trees will do standard permission checks automatically; .I hasperm may be called explicitly to do additional checks. A 9P server may link against a different .I hasperm implementation to provide more complex groups. .SH EXAMPLE The following code correctly handles references when elementwise walking a path and creating a file. .IP .EX f = tree->root; incref(f); for(i=0; i<n && f!=nil; i++) f = walkfile(f, elem[i]); if(f == nil) return nil; nf = createfile(f, "foo", "nls", 0666, nil); closefile(f); return nf; .EE .SH SOURCE .B /sys/src/lib9p/file.c .SH SEE ALSO .IR 9p (2) .SH BUGS The reference counting is cumbersome.