NetBSD-5.0.2/share/examples/refuse/virtdir/virtdir.3

.\"	$NetBSD: virtdir.3,v 1.2 2007/12/02 19:31:46 wiz Exp $
.\"
.\" Copyright © 2007 Alistair Crooks.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. The name of the author may not be used to endorse or promote
.\"    products derived from this software without specific prior written
.\"    permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS
.\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
.\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
.\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
.\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd January 23, 2007
.Dt VIRTDIR 3
.Os
.Sh NAME
.Nm virtdir
.Nd Utility routines for virtual directories for refuse operations
.Sh SYNOPSIS
.In virtdir.h
.Ft int
.Fo virtdir_init
.Fa "virtdir_t *tree" "struct stat *dir" "struct stat *file" "struct stat *symlink"
.Fc
.Ft int
.Fo virtdir_add
.Fa "virtdir_t *tree" "const char *name" "size_t namesize" "uint8_t type" "char *target"
.Fc
.Ft int
.Fo virtdir_del
.Fa "virtdir_t *tree" "const char *name" "size_t namesize"
.Fc
.Ft int
.Fo virtdir_find
.Fa "virtdir_t *tree" "const char *name" "size_t namesize"
.Fc
.Ft int
.Fo virtdir_find_tgt
.Fa "virtdir_t *tree" "const char *name" "size_t namesize"
.Fc
.Ft void
.Fo virtdir_drop
.Fa "virtdir_t *tree"
.Fc
.Ft VIRTDIR *
.Fo openvirtdir
.Fa "virtdir_t *tree" "const char *directory"
.Fc
.Ft virt_dirent_t *
.Fo readvirtdir
.Fa "VIRTDIR *dirp"
.Fc
.Ft void
.Fo closevirtdir
.Fa "VIRTDIR *dirp"
.Fc
.Sh DESCRIPTION
.Nm
provides virtual directory functionality for the benefit of
.Xr refuse 3
file systems (and also for FUSE-based file systems).
.Pp
It uses the framework provided by the
.Xr puffs 3
subsystem, and, through that, the kernel interface provided by
.Xr puffs 4 .
.Pp
The
.Nm
routines build up and manage a list of virtual directory entries.
Each virtual directory entry is indexed by its full pathname within
the file system.
This is consistent with the way that
.Xr refuse 3
locates directory entries - by full pathname.
.Pp
The list of paths is sorted alphabetically.
Each of these virtual directory entries has a distinct type -
file
.Pq Sq f ,
directory
.Pq Sq d ,
or symbolic link
.Pq Sq l .
Additionally, an entry can point to a target - this
is useful when modeling virtual directory entries which are
symbolic links.
The list contains three basic
.Xr stat 2
structures, which contain basic information for file, directory
and symbolic link entries.
This information can be specified at
initialization time, and customized within the individual
getattr operation routines as specified by the
individual file systems.
The
.Nm
functionality can also make virtual directory entries available
on a per-directory basis
to the caller by means of routines analogous to
.Xr opendir 3 ,
.Xr readdir 3 ,
and
.Xr closedir 3 .
These are
.Fn openvirtdir ,
.Fn readvirtdir ,
and
.Fn closevirtdir ,
respectively.
.Sh SEE ALSO
.Xr puffs 3 ,
.Xr refuse 3 ,
.Xr puffs 4
.Sh HISTORY
An unsupported experimental version of
.Nm
first appeared in
.Nx 5.0 .
.Sh AUTHORS
.An Alistair Crooks Aq agc@NetBSD.org