1.\" $NetBSD: ukfs.3,v 1.10 2009/11/22 18:14:49 pooka Exp $ 2.\" 3.\" Copyright (c) 2008 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 November 22, 2009 27.Dt UKFS 3 28.Os 29.Sh NAME 30.Nm ukfs 31.Nd user kernel file system library interface 32.Sh LIBRARY 33ukfs Library (libukfs, \-lukfs) 34.Sh SYNOPSIS 35.In rump/ukfs.h 36.Sh DESCRIPTION 37The 38.Nm 39library provides direct access to file systems without having to 40specially mount a file system. 41Therefore, accessing a file system through 42.Nm 43requires no special kernel support apart from standard POSIX functionality. 44As 45.Nm 46is built upon 47.Xr rump 3 , 48all kernel file systems which are supported by rump are available. 49It allows to write utilities for accessing file systems without having 50to duplicate file system internals knowledge already present in kernel 51file system drivers. 52.Pp 53.Nm 54provides a high-level pathname based interface for accessing file systems. 55If a lower level interface it desired, 56.Xr rump 3 57should be used directly. 58However, much like system calls, the interfaces of 59.Nm , 60are self-contained and require no tracking and release of resources. 61The only exception is the file system handle 62.Ft struct ukfs 63which should be released after use. 64.Sh INITIALIZATION 65.Bl -ohang 66.It Ft int 67.Fn ukfs_init 68.It Ft int 69.Fn ukfs_modload "const char *fname" 70.It Ft int 71.Fn ukfs_modload_dir "const char *dirname" 72.It Ft ssize_t 73.Fn ukfs_vfstypes "char *buf" "size_t buflen" 74.It Ft struct ukfs * 75.Fn ukfs_mount "const char *vfsname" "const char *devpath" \ 76"const char *mountpath" "int mntflags" "void *arg" "size_t alen" 77.It Ft struct ukfs * 78.Fn ukfs_mount_disk "const char *vfsname" "const char *devpath" \ 79"int partition" "const char *mountpath" "int mntflags" \ 80"void *arg" "size_t alen" 81.It Ft int 82.Fn ukfs_release "struct ukfs *ukfs" "int flags" 83.El 84.Pp 85.Fn ukfs_init 86intializes the library and must be called once per process using 87.Nm . 88.Pp 89.Fn ukfs_modload 90is used at runtime to dynamically load a library which contains a 91file system module. 92For this to succeed, the 93.Xr rump 3 94library and the module targetted must be compiled with compatible kernel 95versions and the application must be dynamically linked. 96Additionally, since this routine does not handle dependencies, all the 97dependencies of the library must be loaded beforehand. 98The routine returns \-1 for fatal error, 0 for dependency failure and 1 99for success. 100.Pp 101.Fn ukfs_modload_dir 102loads all 103.Xr rump 3 104file system modules in directory 105.Fa dirname . 106It looks for libraries which begin with 107.Pa librumpfs_ 108and end in 109.Pa .so . 110The routine tries to handle dependencies by retrying to load libraries 111which failed due to dependencies. 112.Fn ukfs_modload_dir 113returns the number of vfs modules loaded or sets errno and 114returns \-1 in case of a fatal error in directory searching. 115In case a fatal error occurs after some modules have already been 116loaded, the number of loaded module is returned. 117Fatal errors in loading the modules themselves are ignored and 118.Fn ukfs_modload 119should be used directly if finegrained error reporting is desired. 120.Pp 121It should be noted that the above routines affect the whole process, 122not just a specific instance of 123.Nm . 124It is preferable to call them from only one thread, as the underlying 125dynamic library interfaces may not be threadsafe. 126.Pp 127.Fn ukfs_vfstypes 128queries the available file system types and returns a nul-terminated 129list of types separated by spaces in 130.Fa buf . 131The format of the list is equivalent to the one returned by 132.Xr sysctl 3 133on the name 134.Pa vfs.generic.fstypes . 135The function returns the length of the string without the trailing nul 136or \-1 for error. 137Notably, the return value 0 means there are no file systems available. 138If there is not enough room in the caller's buffer for all file system 139types, as many as fit will be returned. 140.Pp 141.Fn ukfs_mount 142intializes a file system image. 143The handle resulting from the operation is passed to all other routines 144and identifies the instance of the mount analoguous to what a pathname 145specifies in a normally mounted file system. 146The parameters are the following: 147.Bl -tag -width XXX -offset indent 148.It vfsname 149Name of the file system to be used, e.g. 150.Dv MOUNT_FFS . 151.It devpath 152Path of file system image. 153It can be either a regular file, device or, if the file system does 154not support the concept of a device, an abitrary string, e.g. network 155address. 156.It mountpath 157Path where the file system is mounted to. 158This parameter is used only by the file system being mounted. 159Most of the time 160.Dv UKFS_DEFAULTMP 161is the correct path. 162.It mntflags 163Flags as passed to the 164.Xr mount 2 165system call, for example 166.Dv MNT_RDONLY . 167In addition to generic parameters, file system specific parameters such as 168.Dv MNT_LOG 169(ffs) may be passed here. 170.It arg 171File system private argument structure. 172This is passed directly to the file system. 173It must match what 174.Fa vfsname 175expects. 176.It alen 177Size of said structure. 178.El 179.Pp 180The 181.Fn ukfs_mount_disk 182function must be used to mount disk-based file systems. 183It takes the same arguments as 184.Fn ukfs_mount , 185except for an additional argument signifying the 186.Fa partition 187number. 188If the image 189.Fa devpath 190contains a disklabel, this value specifies the number of the partition 191within the image used as the file system backend. 192If 193.Fa devpath 194does not contain a disklabel, the value 195.Dv UKFS_PARTITION_NONE 196must be used to signal that the file system backend is the entire 197image. 198.Pp 199.Fn ukfs_release 200unmounts the file system and releases the resources associated with 201.Fa ukfs . 202The return value signals the return value of the unmount operation. 203If non-zero, 204.Fa ukfs 205will continue to remain valid. 206The possible values for flags are: 207.Bl -tag -width XUKFS_RELFLAG_NOUNMOUT -offset indent 208.It Dv UKFS_RELFLAG_NOUNMOUNT 209Do not unmount file system, just release ukfs handle. 210Release always succeeds. 211.It Dv UKFS_RELFLAG_FORCE 212Forcefully unmount the file system. 213This means that any busy nodes (due to e.g. 214.Fn ukfs_chdir ) 215will be ignored. 216Release always succeeds. 217.El 218.Sh OPERATION 219.Bl -ohang 220.It Ft int 221.Fn ukfs_chdir "struct ukfs *ukfs" "const char *path" 222.It Ft int 223.Fn ukfs_getdents "struct ukfs *ukfs" "const char *dirname" "off_t *off" \ 224"uint8_t *buf" "size_t bufsize" 225.It Ft ssize_t 226.Fn ukfs_read "struct ukfs *ukfs" "const char *filename" "off_t off" \ 227"uint8_t *buf" "size_t bufsize" 228.It Ft ssize_t 229.Fn ukfs_write "struct ukfs *ukfs" "const char *filename" "off_t off" \ 230"uint8_t *buf" "size_t bufsize" 231.It Ft int 232.Fn ukfs_create "struct ukfs *ukfs" "const char *filename" "mode_t mode" 233.It Ft int 234.Fn ukfs_mknod "struct ukfs *ukfs" "const char *path" "mode_t mode" "dev_t dev" 235.It Ft int 236.Fn ukfs_mkfifo "struct ukfs *ukfs" "const char *path" "mode_t mode" 237.It Ft int 238.Fn ukfs_mkdir "struct ukfs *ukfs" "const char *filename" "mode_t mode" 239.It Ft int 240.Fn ukfs_remove "struct ukfs *ukfs" "const char *filename" 241.It Ft int 242.Fn ukfs_rmdir "struct ukfs *ukfs" "const char *filename" 243.It Ft int 244.Fn ukfs_link "struct ukfs *ukfs" "const char *filename" "const char *f_create" 245.It Ft int 246.Fn ukfs_symlink "struct ukfs *ukfs" "const char *filename" \ 247"const char *linkname" 248.It Ft ssize_t 249.Fn ukfs_readlink "struct ukfs *ukfs" "const char *filename" \ 250"char *linkbuf" "size_t buflen" 251.It Ft int 252.Fn ukfs_rename "struct ukfs *ukfs" "const char *from" "const char *to" 253.It Ft int 254.Fn ukfs_stat "struct ukfs *ukfs" "const char *filename" \ 255"struct stat *file_stat" 256.It Ft int 257.Fn ukfs_lstat "struct ukfs *ukfs" "const char *filename" \ 258"struct stat *file_stat" 259.It Ft int 260.Fn ukfs_chmod "struct ukfs *ukfs" "const char *filename" "mode_t mode" 261.It Ft int 262.Fn ukfs_lchmod "struct ukfs *ukfs" "const char *filename" "mode_t mode" 263.It Ft int 264.Fn ukfs_chown "struct ukfs *ukfs" "const char *filename" "uid_t uid" \ 265"gid_t gid" 266.It Ft int 267.Fn ukfs_lchown "struct ukfs *ukfs" "const char *filename" "uid_t uid" \ 268"gid_t gid" 269.It Ft int 270.Fn ukfs_chflags "struct ukfs *ukfs" "const char *filename" "u_long flags" 271.It Ft int 272.Fn ukfs_lchflags "struct ukfs *ukfs" "const char *filename" "u_long flags" 273.It Ft int 274.Fn ukfs_utimes "struct ukfs *ukfs" "const char *filename" \ 275"const struct timeval *tptr" 276.It Ft int 277.Fn ukfs_lutimes "struct ukfs *ukfs" "const char *filename" \ 278"const struct timeval *tptr" 279.El 280.Pp 281The above routines operate like their system call counterparts and the 282system call manual pages without the ukfs_ prefix should be referred to 283for further information on the parameters. 284.Pp 285The only call which modifies 286.Fa ukfs 287state is 288.Fn ukfs_chdir . 289It works like 290.Xr chdir 2 291in the sense that it affects the interpretation of relative paths. 292If succesful, all relative pathnames will be resolved starting from the 293current directory. 294Currently the call affects all accesses to that particular 295.Fa , 296but it might be later changed to be thread private. 297.Sh UTILITIES 298.Bl -ohang 299.It Ft int 300.Fn ukfs_util_builddirs "struct ukfs *ukfs" "const char *pathname" "mode_t mode" 301.El 302.Pp 303Builds a directory hierarchy. 304Unlike mkdir, the 305.Fa pathname 306argument may contain multiple levels of hierarchy. 307It is not considered an error if any of the directories specified exist 308already. 309.Sh SEE ALSO 310.Xr rump 3 311.Sh HISTORY 312.Nm 313first appeared in 314.Nx 5.0 . 315.Sh AUTHORS 316.An Antti Kantee Aq pooka@cs.hut.fi 317.Sh NOTES 318.Nm 319should be considered experimental technology and may change without warning. 320.Sh BUGS 321On Linux, dynamically linked binaries can include support for only 322one file system due to restrictions with the dynamic linker. 323If more are desired, they must be loaded at runtime using 324.Fn ukfs_modload . 325Even though 326.Nx 327does not have this restriction, portable programs should load all 328file system drivers dynamically. 329