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