share/examples/refuse/virtdir/virtdir.3

   1 .\"     $NetBSD: virtdir.3,v 1.1 2007/04/15 15:10:57 agc Exp $
   2 .\"
   3 .\" Copyright © 2007 Alistair Crooks.  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 .\" 3. The name of the author may not be used to endorse or promote
  14 .\"    products derived from this software without specific prior written
  15 .\"    permission.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS
  18 .\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  19 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
  21 .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
  23 .\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  24 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  25 .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  26 .\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  27 .\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  28 .\"
  29 .Dd January 23, 2007
  30 .Dt VIRTDIR 3
  31 .Os
  32 .Sh NAME
  33 .Nm virtdir
  34 .Nd Utility routines for virtual directories for refuse operations
  35 .Sh SYNOPSIS
  36 .In virtdir.h
  37 .Ft int
  38 .Fo virtdir_init
  39 .Fa "virtdir_t *tree" "struct stat *dir" "struct stat *file" "struct stat *symlink"
  40 .Fc
  41 .Ft int
  42 .Fo virtdir_add
  43 .Fa "virtdir_t *tree" "const char *name" "size_t namesize" "uint8_t type" "char *target"
  44 .Fc
  45 .Ft int
  46 .Fo virtdir_del
  47 .Fa "virtdir_t *tree" "const char *name" "size_t namesize"
  48 .Fc
  49 .Ft int
  50 .Fo virtdir_find
  51 .Fa "virtdir_t *tree" "const char *name" "size_t namesize"
  52 .Fc
  53 .Ft int
  54 .Fo virtdir_find_tgt
  55 .Fa "virtdir_t *tree" "const char *name" "size_t namesize"
  56 .Fc
  57 .Ft void
  58 .Fo virtdir_drop
  59 .Fa "virtdir_t *tree"
  60 .Fc
  61 .Ft VIRTDIR *
  62 .Fo openvirtdir
  63 .Fa "virtdir_t *tree" "const char *directory"
  64 .Fc
  65 .Ft virt_dirent_t *
  66 .Fo readvirtdir
  67 .Fa "VIRTDIR *dirp"
  68 .Fc
  69 .Ft void
  70 .Fo closevirtdir
  71 .Fa "VIRTDIR *dirp"
  72 .Fc
  73 .Sh DESCRIPTION
  74 .Nm
  75 provides virtual directory functionality for the benefit of
  76 .Xr refuse 3
  77 file systems (and also for FUSE-based file systems).
  78 .Pp
  79 It uses the framework provided by the
  80 .Xr puffs 3
  81 subsystem, and, through that, the kernel interface provided by
  82 .Xr puffs 4 .
  83 .Pp
  84 The
  85 .Nm
  86 routines build up and manage a list of virtual directory entries.
  87 Each virtual directory entry is indexed by its full pathname within
  88 the file system.
  89 This is consistent with the way that
  90 .Xr refuse 3
  91 locates directory entries - by full pathname.
  92 .Pp
  93 The list of paths is sorted alphabetically.
  94 Each of these virtual directory entries has a distinct type -
  95 file
  96 .Pq Sq f ,
  97 directory
  98 .Pq Sq d ,
  99 or symbolic link
 100 .Pq Sq l .
 101 Additionally, an entry can point to a target - this
 102 is useful when modeling virtual directory entries which are
 103 symbolic links.
 104 The list contains three basic
 105 .Xr stat 2
 106 structures, which contain basic information for file, directory
 107 and symbolic link entries.
 108 This information can be specified at
 109 initialization time, and customized within the individual
 110 getattr operation routines as specified by the
 111 individual file systems.
 112 The
 113 .Nm
 114 functionality can also make virtual directory entries available
 115 on a per-directory basis
 116 to the caller by means of routines analogous to
 117 .Xr opendir 3 ,
 118 .Xr readdir 3 ,
 119 and
 120 .Xr closedir 3 .
 121 These are
 122 .Fn openvirtdir ,
 123 .Fn readvirtdir ,
 124 and
 125 .Fn closevirtdir ,
 126 respectively.
 127 .Sh SEE ALSO
 128 .Xr puffs 3 ,
 129 .Xr refuse 3 ,
 130 .Xr puffs 4
 131 .Sh HISTORY
 132 An unsupported experimental version of
 133 .Nm
 134 first appeared in
 135 .Nx 5.0 .
 136 .Sh AUTHORS
 137 .An Alistair Crooks Aq agc@NetBSD.org