lib/libpuffs/puffs_path.3

   1 .\"     $NetBSD: puffs_path.3,v 1.3.10.1 2009/02/24 03:45:56 snj Exp $
   2 .\"
   3 .\" Copyright (c) 2007 Antti Kantee.  All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .Dd December 27, 2007
  27 .Dt PUFFS_PATH 3
  28 .Os
  29 .Sh NAME
  30 .Nm puffs_path
  31 .Nd puffs pathbuilding routines
  32 .Sh LIBRARY
  33 .Lb libpuffs
  34 .Sh SYNOPSIS
  35 .In puffs.h
  36 .Ft int
  37 .Fo pu_pathbuild_fn
  38 .Fa "struct puffs_usermount *pu" "const struct puffs_pathobj *po_dir"
  39 .Fa "const struct puffs_pathobj *po_comp" "size_t offset"
  40 .Fa "struct puffs_pathobj *po_new"
  41 .Fc
  42 .Ft int
  43 .Fo pu_pathtransform_fn
  44 .Fa "struct puffs_usermount *pu" "const struct puffs_pathobj *po_base"
  45 .Fa "const struct puffs_cn *pcn" "struct puffs_pathobj *po_new"
  46 .Fc
  47 .Ft int
  48 .Fo pu_pathcmp_fn
  49 .Fa "struct puffs_usermount *pu" "struct puffs_pathobj *po1"
  50 .Fa "struct puffs_pathobj *po2" "size_t checklen" "int checkprefix"
  51 .Fc
  52 .Ft void
  53 .Fn pu_pathfree_fn "struct puffs_usermount *pu" "struct puffs_pathobj *po"
  54 .Ft int
  55 .Fo pu_namemod_fn
  56 .Fa "struct puffs_usermount *pu" "struct puffs_pathobj *po_dir"
  57 .Fa "struct puffs_cn *pcn"
  58 .Fc
  59 .Ft struct puffs_pathobj *
  60 .Fn puffs_getrootpathobj "struct puffs_usermount *pu"
  61 .Sh DESCRIPTION
  62 The puffs library has the ability to provide full pathnames for backends
  63 which require them.
  64 Normal file systems should be constructed without the file system
  65 node tied to a file name and should not used routines described herein.
  66 An example of a file system where the backend requires filenames is
  67 .Xr mount_psshfs 8 .
  68 .Pp
  69 The features described here are enabled by passing
  70 .Dv PUFFS_FLAG_BUILDPATH
  71 to
  72 .Fn puffs_init .
  73 This facility requires to use puffs nodes to store the contents of the
  74 pathname.
  75 Either the address of the operation cookie must directly be that of the
  76 puffs node, or
  77 .Fn puffs_set_cmap
  78 must be used to set a mapping function from the cookie to the puffs
  79 node associated with the cookie.
  80 Finally, the root node for the file system must be set using
  81 .Fn puffs_setroot
  82 and the root path object retrieved using
  83 .Fn puffs_getrootpathobj
  84 and initialized.
  85 .Pp
  86 There are two different places a filename can be retrieved from.
  87 It is available for each puffs node after the node has been registered
  88 with the framework, i.e.
  89 .Em after
  90 the routine creating the node returns.
  91 In other words, there is a window between the node is created and
  92 when the pathname is available and multithreaded file systems must
  93 take this into account.
  94 The second place where a pathname is available is from the componentname
  95 .Vt struct puffs_pcn
  96 in operations which are passed one.
  97 These can be retrieved using the convenience macros
  98 .Fn PNPATH
  99 and
 100 .Fn PCNPATH
 101 for node and componentname, respectively.
 102 The type of object they return is
 103 .Vt void * .
 104 .Pp
 105 By default the framework manages "regular" filenames, which consist
 106 of directory names separated by "/" and a final component.
 107 If the file system wishes to use pathnames of this format, all it
 108 has to do it enable the feature.
 109 Everything else, including bookkeeping for node and directory renames,
 110 is done by the library.
 111 The callback routines described next provide the ability to build
 112 non-standard pathnames.
 113 A
 114 .Fn pu_foo_fn
 115 callback is set using the
 116 .Fn puffs_set_foo
 117 routine.
 118 .Pp
 119 This manual page is still unfinished.
 120 Please take a number and wait in line.
 121 .Sh SEE ALSO
 122 .Xr puffs 3 ,
 123 .Xr puffs_node 3 ,
 124 .Xr mount_psshfs 8 ,
 125 .Xr mount_sysctlfs 8