Bring the documentation slightly more into sync with the current
reality. It's still really a far cry from proper documentation, though.
This commit is contained in:
pooka
parent
cf6c447564
commit
809ae5f803
|
|
@ -1,4 +1,4 @@
|
|||
# $NetBSD: Makefile,v 1.9 2007/01/15 00:39:02 pooka Exp $
|
||||
# $NetBSD: Makefile,v 1.10 2007/01/19 21:10:55 pooka Exp $
|
||||
#
|
||||
|
||||
.include <bsd.own.mk>
|
||||
|
|
@ -8,7 +8,7 @@ WARNS= 4
|
|||
LIB= puffs
|
||||
SRCS= puffs.c callcontext.c creds.c flush.c null.c opdump.c \
|
||||
paths.c pnode.c requests.c subr.c
|
||||
MAN= puffs.3
|
||||
MAN= puffs.3 puffs_cc.3 puffs_flush.3 puffs_node.3 puffs_path.3
|
||||
INCS= puffs.h puffsdump.h
|
||||
INCSDIR= /usr/include
|
||||
LINTFLAGS+=-S -w
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
.\" $NetBSD: puffs.3,v 1.7 2006/12/01 15:31:25 pooka Exp $
|
||||
.\" $NetBSD: puffs.3,v 1.8 2007/01/19 21:10:55 pooka Exp $
|
||||
.\"
|
||||
.\" Copyright (c) 2006 Antti Kantee. All rights reserved.
|
||||
.\" Copyright (c) 2006, 2007 Antti Kantee. All rights reserved.
|
||||
.\"
|
||||
.\" Redistribution and use in source and binary forms, with or without
|
||||
.\" modification, are permitted provided that the following conditions
|
||||
|
|
@ -23,7 +23,7 @@
|
|||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
||||
.\" SUCH DAMAGE.
|
||||
.\"
|
||||
.Dd December 1, 2006
|
||||
.Dd January 19, 2007
|
||||
.Dt PUFFS 3
|
||||
.Os
|
||||
.Sh NAME
|
||||
|
|
@ -35,129 +35,129 @@
|
|||
.In puffs.h
|
||||
.Ft struct puffs_usermount *
|
||||
.Fo puffs_mount
|
||||
.Fa "struct puffs_vfsops *pvfs" "struct puffs_vnops *pvn"
|
||||
.Fa "const char *dir" "int mntflags" "const char *puffsname"
|
||||
.Fa "struct puffs_ops *pops" "const char *dir" "int mntflags"
|
||||
.Fa "const char *puffsname" "void *private"
|
||||
.Fa "uint32_t pflags" "size_t maxreqlen"
|
||||
.Fc
|
||||
.Ft int
|
||||
.Fn puffs_mainloop "struct puffs_usermount *pu" "int flags"
|
||||
.Fo puffs_start
|
||||
.Fa "struct puffs_usermount *pu" "void *rootcookie" "struct statvfs *svfsb"
|
||||
.Fc
|
||||
.Ft int
|
||||
.Fn puffs_oneop "struct puffs_usermount *pu" "uint8_t *buf" "size_t buflen"
|
||||
.Fn puffs_mainloop "struct puffs_usermount *pu" "int flags"
|
||||
.Ft int
|
||||
.Fn puffs_getselectable "struct puffs_usermount *pu"
|
||||
.Ft int
|
||||
.Fn puffs_setblockingmode "struct puffs_usermount *pu" "int mode"
|
||||
.Ft int
|
||||
.Fn puffs_vfs_mount "struct puffs_usermount *pu" "void **rootcookie"
|
||||
.Fn puffs_fs_unmount "struct puffs_cc *pcc" "int flags" "pid_t pid"
|
||||
.Ft int
|
||||
.Fn puffs_vfs_unmount "struct puffs_usermount *pu" "int flags" "pid_t pid"
|
||||
.Ft int
|
||||
.Fo puffs_vfs_statvfs
|
||||
.Fa "struct puffs_usermount *pu" "struct statvfs *sbp" "pid_t pid"
|
||||
.Fo puffs_fs_statvfs
|
||||
.Fa "struct puffs_cc *pcc" "struct statvfs *sbp" "pid_t pid"
|
||||
.Fc
|
||||
.Ft int
|
||||
.Fo puffs_vfs_sync
|
||||
.Fa "struct puffs_usermount *pu" "int waitfor" "const struct puffs_cred *cred"
|
||||
.Fo puffs_fs_sync
|
||||
.Fa "struct puffs_cc *pcc" "int waitfor" "const struct puffs_cred *cred"
|
||||
.Fa "pid_t pid"
|
||||
.Fc
|
||||
.Ft int
|
||||
.Fo puffs_vn_lookup
|
||||
.Fa "struct puffs_usermount *pu" "void *opc" "void **newnode"
|
||||
.Fo puffs_node_lookup
|
||||
.Fa "struct puffs_cc *pcc" "void *opc" "void **newnode"
|
||||
.Fa "enum vtype *newtype" "voff_t *newsize" "dev_t *newrdev"
|
||||
.Fa "const struct puffs_cn *pcn"
|
||||
.Fc
|
||||
.Ft int
|
||||
.Fo puffs_vn_getattr
|
||||
.Fa "struct puffs_usermount *pu" "void *opc" "struct vattr *va"
|
||||
.Fo puffs_node_getattr
|
||||
.Fa "struct puffs_cc *pcc" "void *opc" "struct vattr *va"
|
||||
.Fa "const struct puffs_cred *pcr" "pid_t pid"
|
||||
.Fc
|
||||
.Ft int
|
||||
.Fo puffs_vn_setattr
|
||||
.Fa "struct puffs_usermount *pu" "void *opc" "const struct vattr *va"
|
||||
.Fo puffs_node_setattr
|
||||
.Fa "struct puffs_cc *pcc" "void *opc" "const struct vattr *va"
|
||||
.Fa "const struct puffs_cred *pcr" "pid_t pid"
|
||||
.Fc
|
||||
.Ft int
|
||||
.Fo puffs_vn_create
|
||||
.Fa "struct puffs_usermount *pu" "void *opc" "void **newnode"
|
||||
.Fo puffs_node_create
|
||||
.Fa "struct puffs_cc *pcc" "void *opc" "void **newnode"
|
||||
.Fa "const struct puffs_cn *pcn" "const struct vattr *va"
|
||||
.Fc
|
||||
.Ft int
|
||||
.Fo puffs_vn_remove
|
||||
.Fa "struct puffs_usermount *pu" "void *opc" "void *targ"
|
||||
.Fo puffs_node_remove
|
||||
.Fa "struct puffs_cc *pcc" "void *opc" "void *targ"
|
||||
.Fa "const struct puffs_cn *pcn"
|
||||
.Fc
|
||||
.Ft int
|
||||
.Fo puffs_vn_mkdir
|
||||
.Fa "struct puffs_usermount *pu" "void *opc" "void **newnode"
|
||||
.Fo puffs_node_mkdir
|
||||
.Fa "struct puffs_cc *pcc" "void *opc" "void **newnode"
|
||||
.Fa "const struct puffs_cn *pcn" "const struct vattr *va"
|
||||
.Fc
|
||||
.Ft int
|
||||
.Fo puffs_vn_rmdir
|
||||
.Fa "struct puffs_usermount *pu" "void *opc" "void *targ"
|
||||
.Fo puffs_node_rmdir
|
||||
.Fa "struct puffs_cc *pcc" "void *opc" "void *targ"
|
||||
.Fa "const struct puffs_cn *pcn"
|
||||
.Fc
|
||||
.Ft int
|
||||
.Fo puffs_vn_readdir
|
||||
.Fa "struct puffs_usermount *pu" "void *opc" "struct dirent *dent"
|
||||
.Fo puffs_node_readdir
|
||||
.Fa "struct puffs_cc *pcc" "void *opc" "struct dirent *dent"
|
||||
.Fa "const struct puffs_cred *pcr" "off_t *readoff" "size_t *reslen"
|
||||
.Fc
|
||||
.Ft int
|
||||
.Fo puffs_vn_rename
|
||||
.Fa "struct puffs_usermount *pu" "void *opc" "void *src"
|
||||
.Fo puffs_node_rename
|
||||
.Fa "struct puffs_cc *pcc" "void *opc" "void *src"
|
||||
.Fa "const struct puffs_cn *pcn_src" "void *targ_dir" "void *targ"
|
||||
.Fa "const struct puffs_cn *pcn_targ"
|
||||
.Fc
|
||||
.Ft int
|
||||
.Fo puffs_vn_link
|
||||
.Fa "struct puffs_usermount *pu" "void *opc" "void *targ"
|
||||
.Fo puffs_node_link
|
||||
.Fa "struct puffs_cc *pcc" "void *opc" "void *targ"
|
||||
.Fa "const struct puffs_cn *pcn"
|
||||
.Fc
|
||||
.Ft int
|
||||
.Fo puffs_vn_symlink
|
||||
.Fa "struct puffs_usermount *pu" "void *opc" "void **newnode"
|
||||
.Fo puffs_node_symlink
|
||||
.Fa "struct puffs_cc *pcc" "void *opc" "void **newnode"
|
||||
.Fa "const struct puffs_cn *pcn_src" "const struct vattr *va"
|
||||
.Fa "const char *link_target"
|
||||
.Fc
|
||||
.Ft int
|
||||
.Fo puffs_vn_readlink
|
||||
.Fa "struct puffs_usermount *pu" "void *opc" "const struct puffs_cred *cred"
|
||||
.Fo puffs_node_readlink
|
||||
.Fa "struct puffs_cc *pcc" "void *opc" "const struct puffs_cred *cred"
|
||||
.Fa "char *link" "size_t *linklen"
|
||||
.Fc
|
||||
.Ft int
|
||||
.Fo puffs_vn_mknod
|
||||
.Fa "struct puffs_usermount *pu" "void *opc" "void **newnode"
|
||||
.Fo puffs_node_mknod
|
||||
.Fa "struct puffs_cc *pcc" "void *opc" "void **newnode"
|
||||
.Fa "const struct puffs_cn *pcn" "const struct vattr *va"
|
||||
.Fc
|
||||
.Ft int
|
||||
.Fo puffs_vn_open
|
||||
.Fa "struct puffs_usermount *pu" "void *opc" "int flags"
|
||||
.Fo puffs_node_open
|
||||
.Fa "struct puffs_cc *pcc" "void *opc" "int flags"
|
||||
.Fa "const struct puffs_cred *pcr" "pid_t pid"
|
||||
.Fc
|
||||
.Ft int
|
||||
.Fo puffs_vn_close
|
||||
.Fa "struct puffs_usermount *pu" "void *opc" "int flags"
|
||||
.Fo puffs_node_close
|
||||
.Fa "struct puffs_cc *pcc" "void *opc" "int flags"
|
||||
.Fa "const struct puffs_cred *pcr" "pid_t pid"
|
||||
.Fc
|
||||
.Ft int
|
||||
.Fo puffs_vn_access
|
||||
.Fa "struct puffs_usermount *pu" "void *opc" "int mode"
|
||||
.Fo puffs_node_access
|
||||
.Fa "struct puffs_cc *pcc" "void *opc" "int mode"
|
||||
.Fa "struct puffs_cred *pcr" "pid_t pid"
|
||||
.Fc
|
||||
.Ft int
|
||||
.Fo puffs_vn_read
|
||||
.Fa "struct puffs_usermount *pu" "void *opc" "uint8_t *buf"
|
||||
.Fo puffs_node_read
|
||||
.Fa "struct puffs_cc *pcc" "void *opc" "uint8_t *buf"
|
||||
.Fa "off_t offset" "size_t *resid" "const struct puffs_cred *pcr" "int ioflag"
|
||||
.Fc
|
||||
.Ft int
|
||||
.Fo puffs_vn_write
|
||||
.Fa "struct puffs_usermount *pu" "void *opc" "uint8_t *buf"
|
||||
.Fo puffs_node_write
|
||||
.Fa "struct puffs_cc *pcc" "void *opc" "uint8_t *buf"
|
||||
.Fa "off_t offset" "size_t *resid" "const struct puffs_cred *pcr" "int ioflag"
|
||||
.Fc
|
||||
.Ft int
|
||||
.Fn puffs_vn_reclaim "struct puffs_usermount *pu" "void *opc" "pid_t pid"
|
||||
.Fn puffs_node_reclaim "struct puffs_cc *pcc" "void *opc" "pid_t pid"
|
||||
.Ft int
|
||||
.Fo puffs_vn_inactive
|
||||
.Fa "struct puffs_usermount *pu" "void *opc" "pid_t pid" "int *refcount"
|
||||
.Fo puffs_node_inactive
|
||||
.Fa "struct puffs_cc *pcc" "void *opc" "pid_t pid" "int *refcount"
|
||||
.Fc
|
||||
.Sh DESCRIPTION
|
||||
.Em IMPORTANT NOTE!
|
||||
|
|
@ -185,21 +185,24 @@ takes execution context away from the caller and automatically handles
|
|||
all requests by using the callbacks.
|
||||
Alternatively, control can be kept with the caller and operations
|
||||
handled manually.
|
||||
In the latter case the function
|
||||
.Fn puffs_oneop
|
||||
can be helpful.
|
||||
.Ss Library operation
|
||||
The file system is mounted using
|
||||
.Fn puffs_vfs_mount .
|
||||
The callbacks are passed as the fields in the structures
|
||||
.Fa pvfs
|
||||
and
|
||||
.Fa pvn .
|
||||
The ones intended to be used should initialized to point to the correct
|
||||
routines before calling and the rest should be set to zero.
|
||||
.Fn puffs_mount .
|
||||
The callbacks are passed as the fields in the structure
|
||||
.Fa pops .
|
||||
They can be initialized using the macro
|
||||
.Fn PUFFSOP_SET pops fsname type opname ,
|
||||
which will initialize the operation
|
||||
.Fn puffs_type_opname
|
||||
in
|
||||
.Fa pops
|
||||
to
|
||||
.Fn fsname_type_opname .
|
||||
All operations are initialized to a default state with the call
|
||||
.Fn PUFFSOP_INIT pops .
|
||||
All of the VFS routines are mandatory, but all of the node operations
|
||||
with the exception of
|
||||
.Fn puffs_vfs_lookup
|
||||
.Fn puffs_fs_lookup
|
||||
are optional.
|
||||
However, leaving operations blank will naturally have an effect on the
|
||||
features available from the file system implementation.
|
||||
|
|
@ -216,9 +219,40 @@ Flags for
|
|||
.Nm
|
||||
can be given via
|
||||
.Fa pflags .
|
||||
Currently
|
||||
.Dv PUFFS_FLAG_OPDUMP
|
||||
is supported, this dumps each received operation to stdout before handling it.
|
||||
Currently the following flags are supported:
|
||||
.Bl -tag -width "XPUFFS_KFLAG_BUILDPATHX"
|
||||
.It Dv PUFFS_KFLAG_NOCACHE
|
||||
Do not cache anything in the kernel.
|
||||
Currently this means not using the page cache for regular files or
|
||||
the name cache (directory entry cache) for all files.
|
||||
This is useful if the file system does not want to include flushing
|
||||
and invalidation logic in case it is possible to modify the backend
|
||||
from "under" our view of the file system (a distributed file system,
|
||||
for example).
|
||||
.It Dv PUFFS_KFLAG_ALLOPS
|
||||
This flag requests that all operations are sent to userspace.
|
||||
Normally the kernel shortcircuits unimplemented operations.
|
||||
This flag is mostly useful for debugging purposes.
|
||||
.It Dv PUFFS_FLAG_BUILDPATH
|
||||
The framework will build a complete path name, which is supplied
|
||||
with each operation and can be found from the
|
||||
.Va pn_po.po_full_pcn
|
||||
field in a
|
||||
.Vt struct puffs_node .
|
||||
The option assumes that the framework can map a cookie to a
|
||||
.Vt struct puffs_node .
|
||||
See
|
||||
.Sx Cookies
|
||||
for more information on cookie mapping.
|
||||
See
|
||||
.Xr puffs_path 3
|
||||
for more information on library calls involving paths.
|
||||
.It Dv PUFFS_FLAG_OPDUMP
|
||||
This option makes the framework dump a textual representation of
|
||||
each operation before executing it.
|
||||
It is useful for debugging purposes.
|
||||
.El
|
||||
.Pp
|
||||
Finally, the maximum operation buffer length is requested by
|
||||
.Fa maxreqlen .
|
||||
The field
|
||||
|
|
@ -228,7 +262,7 @@ should always be consulted after the mount call returns.
|
|||
Supplying 0 as this parameter will make the kernel choose the longest
|
||||
possible buffer length.
|
||||
In case of success,
|
||||
.Fn puffs_vfs_mount
|
||||
.Fn puffs_fs_mount
|
||||
returns the address of the user mount instance.
|
||||
Otherwise,
|
||||
.Dv NULL
|
||||
|
|
@ -247,16 +281,6 @@ is used to pass
|
|||
.Fn puffs_mainloop
|
||||
will also detach from the terminal.
|
||||
.Pp
|
||||
To handle a single operation,
|
||||
.Fn puffs_oneop
|
||||
can be used.
|
||||
The buffer for the request should be supplied by the caller and, if
|
||||
possible, should match the buffer length gotten from mount.
|
||||
In case the request was succefully handled (orthogonal to if the
|
||||
request itself was a success from the file system point of view),
|
||||
0 is returned.
|
||||
Otherwise, \-1 is returned and errno is set.
|
||||
.Pp
|
||||
.Fn puffs_getselectable
|
||||
can be used to query a handle to do I/O multiplexing with:
|
||||
.Xr select 2 ,
|
||||
|
|
@ -271,6 +295,13 @@ Acceptable values for the argument are
|
|||
.Dv PUFFSDEV_BLOCK
|
||||
and
|
||||
.Dv PUFFSDEV_NONBLOCK .
|
||||
.Pp
|
||||
After the correct setup for the library has been established and the
|
||||
backend has been initialized, the file system is made operational
|
||||
by calling
|
||||
.Fn puffs_start .
|
||||
Immediately after the return of this function the file system must
|
||||
be ready to process requests.
|
||||
.Ss Cookies
|
||||
Every file (regular file, directory, device node, ...) instance is
|
||||
attached to the kernel using a cookie.
|
||||
|
|
@ -278,8 +309,21 @@ A cookie should uniquely map to a file during its lifetime.
|
|||
If file instances are kept in memory, a simple strategy is to use
|
||||
the virtual address of the structure describing the file.
|
||||
The cookie can be recycled when
|
||||
.Fn puffs_vn_reclaim
|
||||
.Fn puffs_node_reclaim
|
||||
is called for a node.
|
||||
.Pp
|
||||
For some operations (such as building paths) the framework needs to map
|
||||
the cookie to the framework-level structure describing a file,
|
||||
.Vt struct puffs_node .
|
||||
It is advisable to simply use the
|
||||
.Vt struct puffs_node
|
||||
address as a cookie and store file system specific data in the private
|
||||
portion of
|
||||
.Vt struct puffs_node .
|
||||
The library assumes this by default.
|
||||
If it is not desireable, the file system implementation can call
|
||||
.Fn puffs_set_cookiemap
|
||||
to provide an alternative cookie-to-node mapping function.
|
||||
.Ss File system callbacks
|
||||
The callbacks do all the actual work in implementing the file system.
|
||||
Currently they are fairly close to the vfs and vnode operations in
|
||||
|
|
@ -289,16 +333,9 @@ itself.
|
|||
.Pp
|
||||
All callbacks can be prototyped with the file system name and operation
|
||||
name using the macro
|
||||
.Fn PUFFSVFS_PROTOS fsname .
|
||||
.Fn PUFFSOP_PROTOS fsname .
|
||||
.Pp
|
||||
.Fn puffs_vfs_mount
|
||||
should handle all operations which are necessary to mount the file
|
||||
system, e.g. open backing storage, check magic numbers, open a network
|
||||
connection, authenticate, etc.
|
||||
It returns the file system root directory cookie in
|
||||
.Fa rootcookie .
|
||||
.Pp
|
||||
.Fn puffs_vfs_statvfs
|
||||
.Fn puffs_fs_statvfs
|
||||
should fill in the following fields of
|
||||
.Fa sbp :
|
||||
.Bd -literal
|
||||
|
|
@ -320,14 +357,14 @@ The process requiring this information is given by
|
|||
.Fa pid .
|
||||
.Pp
|
||||
The file system should be sychronized to storage when
|
||||
.Fn puffs_vfs_sync
|
||||
.Fn puffs_fs_sync
|
||||
is called.
|
||||
The
|
||||
.Fa waitfor
|
||||
parameter should handled similarly as inside the kernel.
|
||||
.Pp
|
||||
The file system should be unmounted when
|
||||
.Fn puffs_vfs_unmount
|
||||
.Fn puffs_fs_unmount
|
||||
is called.
|
||||
If the flag
|
||||
.Dv MNT_FORCE
|
||||
|
|
@ -347,12 +384,8 @@ The return value 0 signals success, else an appropriate errno value
|
|||
should be returned.
|
||||
Please note that neither this list nor the descriptions are complete.
|
||||
.Pp
|
||||
The callbacks can be prototyped according to file system name by
|
||||
using the macro
|
||||
.Fn PUFFSVN_PROTOS fsname .
|
||||
.Pp
|
||||
The
|
||||
.Fn puffs_vn_lookup
|
||||
.Fn puffs_node_lookup
|
||||
function is used to locate nodes.
|
||||
The implementation should match the name in
|
||||
.Fa pcn
|
||||
|
|
@ -379,11 +412,11 @@ Failure in these cases can be signalled by returning another appropriate
|
|||
error code, for example
|
||||
.Er EACCESS .
|
||||
.Pp
|
||||
.Fn puffs_vn_getattr
|
||||
.Fn puffs_node_getattr
|
||||
fills out a struct vattr pointed to by
|
||||
.Fa va .
|
||||
.Pp
|
||||
.Fn puffs_vn_setattr
|
||||
.Fn puffs_node_setattr
|
||||
sets the attributes in
|
||||
.Fa va .
|
||||
Instead of setting everything according to that file, only fields which
|
||||
|
|
@ -392,28 +425,28 @@ are not marked
|
|||
should be set.
|
||||
.Pp
|
||||
A file node is created in the directory specified by the cookie when
|
||||
.Fn puffs_vn_create
|
||||
.Fn puffs_node_create
|
||||
is called.
|
||||
The attributes are specified by
|
||||
.Fa va
|
||||
and the cookie for the newly created node should be returned in
|
||||
.Fa newnode .
|
||||
Similarly,
|
||||
.Fn puffs_vn_mkdir
|
||||
.Fn puffs_node_mkdir
|
||||
creates a directory.
|
||||
.Pp
|
||||
.Fn puffs_vn_remove
|
||||
.Fn puffs_node_remove
|
||||
removes the file
|
||||
.Fa targ
|
||||
from the directory indicated by the cookie.
|
||||
Similarly,
|
||||
.Fn puffs_vn_rmdir
|
||||
.Fn puffs_node_rmdir
|
||||
removes a directory.
|
||||
The name of the directory entry to remove is described by
|
||||
.Fa pcn .
|
||||
.Pp
|
||||
To read directory entries,
|
||||
.Fn puffs_vn_readdir
|
||||
.Fn puffs_node_readdir
|
||||
is called.
|
||||
It should store directories as struct dirents in the space pointed to by
|
||||
.Fa dent .
|
||||
|
|
@ -435,26 +468,26 @@ In case the directory was exhausted, the parameters should not be
|
|||
modified to signal end-of-directory.
|
||||
.Pp
|
||||
A node rename is done by calling
|
||||
.Fn puffs_vn_rename .
|
||||
.Fn puffs_node_rename .
|
||||
If the destination file cookie is non-null, it must be removed
|
||||
and the new entry overwritten atomically.
|
||||
The directory entry names to be used are described by the
|
||||
struct puffs_cn's (cf. create and remove).
|
||||
.Pp
|
||||
A hard link is created by
|
||||
.Fn puffs_vn_link .
|
||||
.Fn puffs_node_link .
|
||||
In practice this means adding a directory entry described by
|
||||
.Fa pcn
|
||||
to the cookied directory and the entry pointing to the target node.
|
||||
.Pp
|
||||
A symbolic link in turn is created by
|
||||
.Fn puffs_vn_symlink .
|
||||
.Fn puffs_node_symlink .
|
||||
It is similar to creating a regular file, except that
|
||||
.Fa link_target
|
||||
specifies the target of the link which should be set for the link.
|
||||
.Pp
|
||||
To read the target of a symbolic link,
|
||||
.Fa puffs_vn_readlink
|
||||
.Fa puffs_node_readlink
|
||||
is called.
|
||||
The path in the link target should be copied to
|
||||
.Fa link
|
||||
|
|
@ -462,29 +495,29 @@ and the length without the terminating nul set in
|
|||
.Fa linklen .
|
||||
.Pp
|
||||
A device node is created using
|
||||
.Fn puffs_vn_mknod .
|
||||
.Fn puffs_node_mknod .
|
||||
The only difference to creating a normal file is that the attribute
|
||||
struct contains the device identifier in
|
||||
.Fa va-\*[Gt]va_rdev .
|
||||
.Pp
|
||||
Files are opened with a call to
|
||||
.Fn puffs_vn_open .
|
||||
.Fn puffs_node_open .
|
||||
Most of the time this can be left unimplemented, unless special
|
||||
resource allocation is required.
|
||||
.Pp
|
||||
.Fn puffs_vn_close
|
||||
.Fn puffs_node_close
|
||||
releases all the resources allocated by
|
||||
.Fn puffs_vn_open .
|
||||
.Fn puffs_node_open .
|
||||
.Pp
|
||||
To check if access of type
|
||||
.Va mode
|
||||
to a file is allowed,
|
||||
.Fn puffs_vn_access
|
||||
.Fn puffs_node_access
|
||||
is called.
|
||||
This controls file access, not e.g.
|
||||
.Fn puffs_vn_open .
|
||||
.Fn puffs_node_open .
|
||||
.Pp
|
||||
.Fn puffs_vn_read
|
||||
.Fn puffs_node_read
|
||||
reads the contents of a file.
|
||||
It will gather the data from
|
||||
.Fa offset
|
||||
|
|
@ -500,7 +533,7 @@ The parameter
|
|||
should be set to indicate the amount of request NOT completed.
|
||||
In the normal case this should be 0.
|
||||
.Pp
|
||||
.Fn puffs_vn_write
|
||||
.Fn puffs_node_write
|
||||
writes data to a file at
|
||||
.Fa offset
|
||||
extending the file if necessary.
|
||||
|
|
@ -512,24 +545,28 @@ In case the flag
|
|||
.Dv PUFFS_IO_APPEND
|
||||
is specified, the data should be appended to the end of the file.
|
||||
.Pp
|
||||
.Fn puffs_vn_reclaim
|
||||
.Fn puffs_node_reclaim
|
||||
signals that the cookie will no longer be referenced without a further
|
||||
call to
|
||||
.Fn puffs_vn_lookup .
|
||||
.Fn puffs_node_lookup .
|
||||
This information can be used to free resources and specifically release
|
||||
a file for which no directory entries remain.
|
||||
.Pp
|
||||
.Fn puffs_vn_inactive
|
||||
.Fn puffs_node_inactive
|
||||
signals that the kernel has released its last reference to the node.
|
||||
However, the cookie must still remain valid until
|
||||
.Fn puffs_vn_reclaim
|
||||
.Fn puffs_node_reclaim
|
||||
is called.
|
||||
The file system should return its internal reference count on the file
|
||||
(usually number of links to the file) in
|
||||
.Fa refcount .
|
||||
If this is zero, the kernel will call reclaim immediately.
|
||||
.Sh SEE ALSO
|
||||
.Xr puffs 4
|
||||
.Xr puffs 4 ,
|
||||
.Xr puffs_cc 3 ,
|
||||
.Xr puffs_flush 3 ,
|
||||
.Xr puffs_node 3 ,
|
||||
.Xr puffs_path 3
|
||||
.Sh HISTORY
|
||||
An unsupported experimental version of
|
||||
.Nm
|
||||
|
|
@ -538,10 +575,4 @@ first appeared in
|
|||
.Sh AUTHORS
|
||||
.An Antti Kantee Aq pooka@iki.fi
|
||||
.Sh BUGS
|
||||
struct puffs_node is of questionable content.
|
||||
Especially the use of
|
||||
.Va pn_va
|
||||
should be avoided.
|
||||
.Pp
|
||||
Operations which require arbitrary blocking periods are not well handled
|
||||
by the library in this version.
|
||||
Under construction.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,85 @@
|
|||
.\" $NetBSD: puffs_cc.3,v 1.1 2007/01/19 21:10:55 pooka Exp $
|
||||
.\"
|
||||
.\" Copyright (c) 2007 Antti Kantee. All rights reserved.
|
||||
.\"
|
||||
.\" Redistribution and use in source and binary forms, with or without
|
||||
.\" modification, are permitted provided that the following conditions
|
||||
.\" are met:
|
||||
.\" 1. Redistributions of source code must retain the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer.
|
||||
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer in the
|
||||
.\" documentation and/or other materials provided with the distribution.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
||||
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||||
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
||||
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
||||
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
||||
.\" SUCH DAMAGE.
|
||||
.\"
|
||||
.Dd January 19, 2007
|
||||
.Dt PUFFS_CC 3
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm puffs_cc
|
||||
.Nd puffs continuation routines
|
||||
.Sh LIBRARY
|
||||
.Lb libpuffs
|
||||
.Sh SYNOPSIS
|
||||
.In puffs.h
|
||||
.Ft struct puffs_usermount *
|
||||
.Fn puffs_cc_getusermount "struct puffs_cc *"
|
||||
.Ft void
|
||||
.Fn puffs_cc_yield(struct puffs_cc *pcc)
|
||||
.Ft void
|
||||
.Fn puffs_cc_continue(struct puffs_cc *pcc)
|
||||
.Sh DESCRIPTION
|
||||
.Em IMPORTANT NOTE!
|
||||
This document describes interfaces which are not yet guaranteed to be
|
||||
stable.
|
||||
In case you update your system sources, please recompile everything
|
||||
and fix complation errors.
|
||||
If your sources are out-of-sync, incorrect operation may result.
|
||||
The interfaces in this document will most likely be hugely simplified
|
||||
in later versions or made transparent to the implementation.
|
||||
.Pp
|
||||
These functions enable the use of continuations within the framework.
|
||||
Every operation callback within a file system implementation is
|
||||
automatically passed an opaque cookie,
|
||||
.Va pcc ,
|
||||
to be used as a continuation handle.
|
||||
.Pp
|
||||
File systems using continuations should define their own even loop
|
||||
instead of using
|
||||
.Fn puffs_mainloop .
|
||||
.Pp
|
||||
Calling
|
||||
.Fn puffs_cc_yield
|
||||
will suspend and save the current execution context and return control
|
||||
to the previous point.
|
||||
Likewise, calling
|
||||
.Fn puffs_cc_continue
|
||||
will suspend current execution and return control to where it was before
|
||||
before calling
|
||||
.Fn puffs_cc_yield .
|
||||
.Pp
|
||||
Before calling
|
||||
.Fn puffs_cc_yield
|
||||
a file system will typically want to record some cookie value into its
|
||||
own internal bookkeeping.
|
||||
This cookie should be hooked to the
|
||||
.Va pcc
|
||||
so that the correct continuation can be continued when the event it
|
||||
was waiting for triggers.
|
||||
.Pp
|
||||
The puffs ssh file system is supposed to be the canonical example
|
||||
for the use of the continuation framework.
|
||||
.Sh SEE ALSO
|
||||
.Xr mount_psshfs 8 ,
|
||||
.Xr puffs 3
|
||||
|
|
@ -0,0 +1,64 @@
|
|||
.\" $NetBSD: puffs_flush.3,v 1.1 2007/01/19 21:10:55 pooka Exp $
|
||||
.\"
|
||||
.\" Copyright (c) 2007 Antti Kantee. All rights reserved.
|
||||
.\"
|
||||
.\" Redistribution and use in source and binary forms, with or without
|
||||
.\" modification, are permitted provided that the following conditions
|
||||
.\" are met:
|
||||
.\" 1. Redistributions of source code must retain the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer.
|
||||
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer in the
|
||||
.\" documentation and/or other materials provided with the distribution.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
||||
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||||
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
||||
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
||||
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
||||
.\" SUCH DAMAGE.
|
||||
.\"
|
||||
.Dd January 19, 2007
|
||||
.Dt PUFFS_FLUSH 3
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm puffs_flush
|
||||
.Nd puffs kernel cache flushing and invalidation routines
|
||||
.Sh LIBRARY
|
||||
.Lb libpuffs
|
||||
.Sh SYNOPSIS
|
||||
.In puffs.h
|
||||
.Ft int
|
||||
.Fn puffs_inval_namecache_dir "struct puffs_usermount *pu" "void *cookie"
|
||||
.Ft int
|
||||
.Fn puffs_inval_namecache_all "struct puffs_usermount *pu"
|
||||
.Sh DESCRIPTION
|
||||
.Em IMPORTANT NOTE!
|
||||
This document describes interfaces which are not yet guaranteed to be
|
||||
stable.
|
||||
In case you update your system sources, please recompile everything
|
||||
and fix complation errors.
|
||||
If your sources are out-of-sync, incorrect operation may result.
|
||||
The interfaces in this document will most likely be hugely simplified
|
||||
in later versions or made transparent to the implementation.
|
||||
.Pp
|
||||
These routines are used inform the kernel that any information it might
|
||||
have cached is no longer valid.
|
||||
Currently only two are supported.
|
||||
.Fn puffs_inval_namecache_dir
|
||||
invalidates the name cache for a given directory.
|
||||
The argument
|
||||
.Va cookie
|
||||
should describe an existing and valid directory cookie for the file
|
||||
system.
|
||||
Similarly,
|
||||
.Fn puffs_inval_namecache_all
|
||||
invalidates the name cache for the entire file system
|
||||
(this routine might go away).
|
||||
.Sh SEE ALSO
|
||||
.Xr puffs 3
|
||||
|
|
@ -0,0 +1,79 @@
|
|||
.\" $NetBSD: puffs_node.3,v 1.1 2007/01/19 21:10:55 pooka Exp $
|
||||
.\"
|
||||
.\" Copyright (c) 2007 Antti Kantee. All rights reserved.
|
||||
.\"
|
||||
.\" Redistribution and use in source and binary forms, with or without
|
||||
.\" modification, are permitted provided that the following conditions
|
||||
.\" are met:
|
||||
.\" 1. Redistributions of source code must retain the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer.
|
||||
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer in the
|
||||
.\" documentation and/or other materials provided with the distribution.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
||||
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||||
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
||||
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
||||
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
||||
.\" SUCH DAMAGE.
|
||||
.\"
|
||||
.Dd January 19, 2007
|
||||
.Dt PUFFS_NODE 3
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm puffs_node
|
||||
.Nd puffs node routines
|
||||
.Sh LIBRARY
|
||||
.Lb libpuffs
|
||||
.Sh SYNOPSIS
|
||||
.In puffs.h
|
||||
.Ft struct puffs_node *
|
||||
.Fn puffs_pn_new "struct puffs_usermount *pu" "void *priv"
|
||||
.Ft void
|
||||
.Fn puffs_pn_put "struct puffs_node *pn"
|
||||
.Ft void *
|
||||
.Fo puffs_nodewalk_fn
|
||||
.Fa "struct puffs_usermount *pu" "struct puffs_node *pn" "void *arg"
|
||||
.Fc
|
||||
.Ft void *
|
||||
.Fo puffs_pn_nodewalk
|
||||
.Fa "struct puffs_usermount *pu" "puffs_nodewalk_fn" "void *arg"
|
||||
.Fc
|
||||
.Sh DESCRIPTION
|
||||
.Em IMPORTANT NOTE!
|
||||
This document describes interfaces which are not yet guaranteed to be
|
||||
stable.
|
||||
In case you update your system sources, please recompile everything
|
||||
and fix complation errors.
|
||||
If your sources are out-of-sync, incorrect operation may result.
|
||||
The interfaces in this document will most likely be hugely simplified
|
||||
in later versions or made transparent to the implementation.
|
||||
.Pp
|
||||
It should especially be noted, that it is yet completely unsure, how
|
||||
much of the internals contents of
|
||||
.Vt struct puffs_node
|
||||
will be exposed to file systems in the end.
|
||||
.Pp
|
||||
Nodes are allocated and released by using
|
||||
.Fn puffs_pn_new
|
||||
and
|
||||
.Fn puffs_pn_put ,
|
||||
respectively.
|
||||
The argument
|
||||
.Fa priv
|
||||
can be used to store file system specific information.
|
||||
.Pp
|
||||
The list of all nodes in a file system can be traversed by calling
|
||||
.Fn puffs_pn_nodewalk .
|
||||
This is useful for example in handling the
|
||||
.Fn puffs_fs_sync
|
||||
callback, when cached data for every node should be flushed to stable
|
||||
storage.
|
||||
.Sh SEE ALSO
|
||||
.Xr puffs 3
|
||||
|
|
@ -0,0 +1,53 @@
|
|||
.\" $NetBSD: puffs_path.3,v 1.1 2007/01/19 21:10:55 pooka Exp $
|
||||
.\"
|
||||
.\" Copyright (c) 2007 Antti Kantee. All rights reserved.
|
||||
.\"
|
||||
.\" Redistribution and use in source and binary forms, with or without
|
||||
.\" modification, are permitted provided that the following conditions
|
||||
.\" are met:
|
||||
.\" 1. Redistributions of source code must retain the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer.
|
||||
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer in the
|
||||
.\" documentation and/or other materials provided with the distribution.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
||||
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||||
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
||||
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
||||
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
||||
.\" SUCH DAMAGE.
|
||||
.\"
|
||||
.Dd January 19, 2007
|
||||
.Dt PUFFS_PATH 3
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm puffs_path
|
||||
.Nd puffs pathbuilding routines
|
||||
.Sh LIBRARY
|
||||
.Lb libpuffs
|
||||
.Sh SYNOPSIS
|
||||
.In puffs.h
|
||||
.Sh DESCRIPTION
|
||||
.Em IMPORTANT NOTE!
|
||||
This document describes interfaces which are not yet guaranteed to be
|
||||
stable.
|
||||
In case you update your system sources, please recompile everything
|
||||
and fix complation errors.
|
||||
If your sources are out-of-sync, incorrect operation may result.
|
||||
The interfaces in this document will most likely be hugely simplified
|
||||
in later versions or made transparent to the implementation.
|
||||
.Pp
|
||||
The puffs library has the ability to provide pathnames for backends
|
||||
which require them.
|
||||
Normal file systems should be constructed without the file system
|
||||
node tied to a file name and should not used routines described herein.
|
||||
.Pp
|
||||
This manual page is under construction.
|
||||
.Sh SEE ALSO
|
||||
.Xr puffs 3
|
||||
Loading…
Reference in New Issue