1.\" $NetBSD: puffs_path.3,v 1.4 2009/02/20 14:26:56 pooka 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 62The puffs library has the ability to provide full pathnames for backends 63which require them. 64Normal file systems should be constructed without the file system 65node tied to a file name and should not used routines described herein. 66An example of a file system where the backend requires filenames is 67.Xr mount_psshfs 8 . 68.Pp 69The features described here are enabled by passing 70.Dv PUFFS_FLAG_BUILDPATH 71to 72.Fn puffs_init . 73This facility requires to use puffs nodes to store the contents of the 74pathname. 75Either the address of the operation cookie must directly be that of the 76puffs node, or 77.Fn puffs_set_cmap 78must be used to set a mapping function from the cookie to the puffs 79node associated with the cookie. 80Finally, the root node for the file system must be set using 81.Fn puffs_setroot 82and the root path object retrieved using 83.Fn puffs_getrootpathobj 84and initialized. 85.Pp 86There are two different places a filename can be retrieved from. 87It is available for each puffs node after the node has been registered 88with the framework, i.e. 89.Em after 90the routine creating the node returns. 91In other words, there is a window between the node is created and 92when the pathname is available and multithreaded file systems must 93take this into account. 94The second place where a pathname is available is from the componentname 95.Vt struct puffs_pcn 96in operations which are passed one. 97These can be retrieved using the convenience macros 98.Fn PNPATH 99and 100.Fn PCNPATH 101for node and componentname, respectively. 102The type of object they return is 103.Vt void * . 104.Pp 105By default the framework manages "regular" filenames, which consist 106of directory names separated by "/" and a final component. 107If the file system wishes to use pathnames of this format, all it 108has to do it enable the feature. 109Everything else, including bookkeeping for node and directory renames, 110is done by the library. 111The callback routines described next provide the ability to build 112non-standard pathnames. 113A 114.Fn pu_foo_fn 115callback is set using the 116.Fn puffs_set_foo 117routine. 118.Pp 119This manual page is still unfinished. 120Please 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 126