1.\" $NetBSD: virtdir.3,v 1.2 2007/12/02 19:31:46 wiz 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 75provides virtual directory functionality for the benefit of 76.Xr refuse 3 77file systems (and also for FUSE-based file systems). 78.Pp 79It uses the framework provided by the 80.Xr puffs 3 81subsystem, and, through that, the kernel interface provided by 82.Xr puffs 4 . 83.Pp 84The 85.Nm 86routines build up and manage a list of virtual directory entries. 87Each virtual directory entry is indexed by its full pathname within 88the file system. 89This is consistent with the way that 90.Xr refuse 3 91locates directory entries - by full pathname. 92.Pp 93The list of paths is sorted alphabetically. 94Each of these virtual directory entries has a distinct type - 95file 96.Pq Sq f , 97directory 98.Pq Sq d , 99or symbolic link 100.Pq Sq l . 101Additionally, an entry can point to a target - this 102is useful when modeling virtual directory entries which are 103symbolic links. 104The list contains three basic 105.Xr stat 2 106structures, which contain basic information for file, directory 107and symbolic link entries. 108This information can be specified at 109initialization time, and customized within the individual 110getattr operation routines as specified by the 111individual file systems. 112The 113.Nm 114functionality can also make virtual directory entries available 115on a per-directory basis 116to the caller by means of routines analogous to 117.Xr opendir 3 , 118.Xr readdir 3 , 119and 120.Xr closedir 3 . 121These are 122.Fn openvirtdir , 123.Fn readvirtdir , 124and 125.Fn closevirtdir , 126respectively. 127.Sh SEE ALSO 128.Xr puffs 3 , 129.Xr refuse 3 , 130.Xr puffs 4 131.Sh HISTORY 132An unsupported experimental version of 133.Nm 134first appeared in 135.Nx 5.0 . 136.Sh AUTHORS 137.An Alistair Crooks Aq agc@NetBSD.org 138