lib/libpuffs/puffs_node.3

   1 .\"     $NetBSD: puffs_node.3,v 1.5 2009/05/13 22:42:31 wiz 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 June 24, 2007
  27 .Dt PUFFS_NODE 3
  28 .Os
  29 .Sh NAME
  30 .Nm puffs_node
  31 .Nd puffs node routines
  32 .Sh LIBRARY
  33 .Lb libpuffs
  34 .Sh SYNOPSIS
  35 .In puffs.h
  36 .Ft struct puffs_node *
  37 .Fn puffs_pn_new "struct puffs_usermount *pu" "void *priv"
  38 .Ft void *
  39 .Fo puffs_nodewalk_fn
  40 .Fa "struct puffs_usermount *pu" "struct puffs_node *pn" "void *arg"
  41 .Fc
  42 .Ft void *
  43 .Fo puffs_pn_nodewalk
  44 .Fa "struct puffs_usermount *pu" "puffs_nodewalk_fn nwfn" "void *arg"
  45 .Fc
  46 .Ft void
  47 .Fn puffs_pn_remove "struct puffs_node *pn"
  48 .Ft void
  49 .Fn puffs_pn_put "struct puffs_node *pn"
  50 .Sh DESCRIPTION
  51 .Bl -tag -width xxxx
  52 .It Fn puffs_pn_new pu priv
  53 Create a new node and attach it to the mountpoint
  54 .Ar pu .
  55 The argument
  56 .Ar priv
  57 can be used for associating file system specific data with the new
  58 node and will not be accessed by puffs.
  59 .It Fn puffs_nodewalk_fn pu pn arg
  60 A callback for
  61 .Fn puffs_nodewalk .
  62 The list of nodes is iterated in the argument
  63 .Ar pn
  64 and the argument
  65 .Ar arg
  66 is the argument given to
  67 .Fn puffs_nodewalk .
  68 .It Fn puffs_nodewalk pu nwfn arg
  69 Walk all nodes associted with the mountpoint
  70 .Ar pu
  71 and call
  72 .Fn nwfn
  73 for them.
  74 The walk is aborted if
  75 .Fn puffs_nodewalk_fn
  76 returns a value which is not
  77 .Dv NULL .
  78 This value is also returned this function.
  79 In case the whole set of nodes is traversed,
  80 .Dv NULL
  81 is returned.
  82 This function is useful for example in handling the
  83 .Fn puffs_fs_sync
  84 callback, when cached data for every node should be flushed to stable
  85 storage.
  86 .It Fn puffs_pn_remove pn
  87 Signal that a node has been removed from the file system, but do not
  88 yet release resources associated with the node.
  89 This will prevent the nodewalk functions from accessing the node.
  90 If necessary, this is usually called from
  91 .Fn puffs_node_remove
  92 and
  93 .Fn puffs_node_rmdir .
  94 .It Fn puffs_pn_put pn
  95 Free all resources associated with node
  96 .Ar pn .
  97 This is typically called from
  98 .Fn puffs_node_reclaim .
  99 .El
 100 .Sh SEE ALSO
 101 .Xr puffs 3