Flesh this out a bit more. Unfortunately it's still unfinished,

and I don't know when I'll get a chance to finish it.

lib/libpuffs/puffs_path.3

@@ -1,4 +1,4 @@
-.\"	$NetBSD: puffs_path.3,v 1.2 2007/12/01 19:18:51 wiz Exp $
+.\"	$NetBSD: puffs_path.3,v 1.3 2007/12/27 18:50:42 pooka Exp $
 .\"
 .\" Copyright (c) 2007 Antti Kantee.  All rights reserved.
 .\"
@@ -23,7 +23,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd January 19, 2007
+.Dd December 27, 2007
 .Dt PUFFS_PATH 3
 .Os
 .Sh NAME
@@ -33,6 +33,31 @@
 .Lb libpuffs
 .Sh SYNOPSIS
 .In puffs.h
+.Ft int
+.Fo pu_pathbuild_fn
+.Fa "struct puffs_usermount *pu" "const struct puffs_pathobj *po_dir"
+.Fa "const struct puffs_pathobj *po_comp" "size_t offset"
+.Fa "struct puffs_pathobj *po_new"
+.Fc
+.Ft int
+.Fo pu_pathtransform_fn
+.Fa "struct puffs_usermount *pu" "const struct puffs_pathobj *po_base"
+.Fa "const struct puffs_cn *pcn" "struct puffs_pathobj *po_new"
+.Fc
+.Ft int
+.Fo pu_pathcmp_fn
+.Fa "struct puffs_usermount *pu" "struct puffs_pathobj *po1"
+.Fa "struct puffs_pathobj *po2" "size_t checklen" "int checkprefix"
+.Fc
+.Ft void
+.Fn pu_pathfree_fn "struct puffs_usermount *pu" "struct puffs_pathobj *po"
+.Ft int
+.Fo pu_namemod_fn
+.Fa "struct puffs_usermount *pu" "struct puffs_pathobj *po_dir"
+.Fa "struct puffs_cn *pcn"
+.Fc
+.Ft struct puffs_pathobj *
+.Fn puffs_getrootpathobj "struct puffs_usermount *pu"
 .Sh DESCRIPTION
 .Em IMPORTANT NOTE!
 This document describes interfaces which are not yet guaranteed to be
@@ -43,11 +68,67 @@ 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
+The puffs library has the ability to provide full 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.
+An example of a file system where the backend requires filenames is
+.Xr mount_psshfs 8 .
 .Pp
-This manual page is under construction.
+The features described here are enabled by passing
+.Dv PUFFS_FLAG_BUILDPATH
+to
+.Fn puffs_init .
+This facility requires to use puffs nodes to store the contents of the
+pathname.
+Either the address of the operation cookie must directly be that of the
+puffs node, or
+.Fn puffs_set_cmap
+must be used to set a mapping function from the cookie to the puffs
+node associated with the cookie.
+Finally, the root node for the file system must be set using
+.Fn puffs_setroot
+and the root path object retrieved using
+.Fn puffs_getrootpathobj
+and initialized.
+.Pp
+There are two different places a filename can be retrieved from.
+It is available for each puffs node after the node has been registered
+with the framework, i.e.
+.Em after
+the routine creating the node returns.
+In other words, there is a window between the node is created and
+when the pathname is available and multithreaded file systems must
+take this into account.
+The second place where a pathname is available is from the componentname
+.Vt struct puffs_pcn
+in operations which are passed one.
+These can be retrieved using the convenience macros
+.Fn PNPATH
+and
+.Fn PCNPATH
+for node and componentname, respectively.
+The type of object they return is
+.Vt void * .
+.Pp
+By default the framework manages "regular" filenames, which consist
+of directory names separated by "/" and a final component.
+If the file system wishes to use pathnames of this format, all it
+has to do it enable the feature.
+Everything else, including bookkeeping for node and directory renames,
+is done by the library.
+The callback routines described next provide the ability to build
+non-standard pathnames.
+A
+.Fn pu_foo_fn
+callback is set using the
+.Fn puffs_set_foo
+routine.
+.Pp
+This manual page is still unfinished.
+Please take a number and wait in line.
 .Sh SEE ALSO
-.Xr puffs 3
+.Xr puffs 3 ,
+.Xr puffs_node 3 ,
+.Xr mount_psshfs 8 ,
+.Xr mount_sysctlfs 8