| blob | 09f8bb207b17c0ef3722b2cbcbbdbb0677b701e3 |
1 .\" $NetBSD: ukfs.3,v 1.9 2009/09/14 20:54:34 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
33 ukfs Library (libukfs, \-lukfs)
34 .Sh SYNOPSIS
35 .In rump/ukfs.h
36 .Sh DESCRIPTION
37 The
38 .Nm
39 library provides direct access to file systems without having to
40 specially mount a file system.
41 Therefore, accessing a file system through
42 .Nm
43 requires no special kernel support apart from standard POSIX functionality.
44 As
45 .Nm
46 is built upon
47 .Xr rump 3 ,
48 all kernel file systems which are supported by rump are available.
49 It allows to write utilities for accessing file systems without having
50 to duplicate file system internals knowledge already present in kernel
51 file system drivers.
52 .Pp
53 .Nm
54 provides a high-level pathname based interface for accessing file systems.
55 If a lower level interface it desired,
56 .Xr rump 3
57 should be used directly.
58 However, much like system calls, the interfaces of
59 .Nm ,
60 are self-contained and require no tracking and release of resources.
61 The only exception is the file system handle
62 .Ft struct ukfs
63 which 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
86 intializes the library and must be called once per process using
87 .Nm .
88 .Pp
89 .Fn ukfs_modload
90 is used at runtime to dynamically load a library which contains a
91 file system module.
92 For this to succeed, the
93 .Xr rump 3
94 library and the module targetted must be compiled with compatible kernel
95 versions and the application must be dynamically linked.
96 Additionally, since this routine does not handle dependencies, all the
97 dependencies of the library must be loaded beforehand.
98 The routine returns \-1 for fatal error, 0 for dependency failure and 1
99 for success.
100 .Pp
101 .Fn ukfs_modload_dir
102 loads all
103 .Xr rump 3
104 file system modules in directory
105 .Fa dirname .
106 It looks for libraries which begin with
107 .Pa librumpfs_
108 and end in
109 .Pa .so .
110 The routine tries to handle dependencies by retrying to load libraries
111 which failed due to dependencies.
112 .Fn ukfs_modload_dir
113 returns the number of vfs modules loaded or sets errno and
114 returns \-1 in case of a fatal error in directory searching.
115 In case a fatal error occurs after some modules have already been
116 loaded, the number of loaded module is returned.
117 Fatal errors in loading the modules themselves are ignored and
118 .Fn ukfs_modload
119 should be used directly if finegrained error reporting is desired.
120 .Pp
121 It should be noted that the above routines affect the whole process,
122 not just a specific instance of
123 .Nm .
124 It is preferable to call them from only one thread, as the underlying
125 dynamic library interfaces may not be threadsafe.
126 .Pp
127 .Fn ukfs_vfstypes
128 queries the available file system types and returns a nul-terminated
129 list of types separated by spaces in
130 .Fa buf .
131 The format of the list is equivalent to the one returned by
132 .Xr sysctl 3
133 on the name
134 .Pa vfs.generic.fstypes .
135 The function returns the length of the string without the trailing nul
136 or \-1 for error.
137 Notably, the return value 0 means there are no file systems available.
138 If there is not enough room in the caller's buffer for all file system
139 types, as many as fit will be returned.
140 .Pp
141 .Fn ukfs_mount
142 intializes a file system image.
143 The handle resulting from the operation is passed to all other routines
144 and identifies the instance of the mount analoguous to what a pathname
145 specifies in a normally mounted file system.
146 The parameters are the following:
147 .Bl -tag -width XXX -offset indent
148 .It vfsname
149 Name of the file system to be used, e.g.
150 .Dv MOUNT_FFS .
151 .It devpath
152 Path of file system image.
153 It can be either a regular file, device or, if the file system does
154 not support the concept of a device, an abitrary string, e.g. network
155 address.
156 .It mountpath
157 Path where the file system is mounted to.
158 This parameter is used only by the file system being mounted.
159 Most of the time
160 .Dv UKFS_DEFAULTMP
161 is the correct path.
162 .It mntflags
163 Flags as passed to the
164 .Xr mount 2
165 system call, for example
166 .Dv MNT_RDONLY .
167 In addition to generic parameters, file system specific parameters such as
168 .Dv MNT_LOG
169 (ffs) may be passed here.
170 .It arg
171 File system private argument structure.
172 This is passed directly to the file system.
173 It must match what
174 .Fa vfsname
175 expects.
176 .It alen
177 Size of said structure.
178 .El
179 .Pp
180 The
181 .Fn ukfs_mount_disk
182 function must be used to mount disk-based file systems.
183 It takes the same arguments as
184 .Fn ukfs_mount ,
185 except for an additional argument signifying the
186 .Fa partition
187 number.
188 If the image
189 .Fa devpath
190 contains a disklabel, this value specifies the number of the partition
191 within the image used as the file system backend.
192 If
193 .Fa devpath
194 does not contain a disklabel, the value
195 .Dv UKFS_PARTITION_NONE
196 must be used to signal that the file system backend is the entire
197 image.
198 .Pp
199 .Fn ukfs_release
200 unmounts the file system and releases the resources associated with
201 .Fa ukfs .
202 The return value signals the return value of the unmount operation.
203 If non-zero,
204 .Fa ukfs
205 will continue to remain valid.
206 The possible values for flags are:
207 .Bl -tag -width XUKFS_RELFLAG_NOUNMOUT -offset indent
208 .It Dv UKFS_RELFLAG_NOUNMOUNT
209 Do not unmount file system, just release ukfs handle.
210 Release always succeeds.
211 .It Dv UKFS_RELFLAG_FORCE
212 Forcefully unmount the file system.
213 This means that any busy nodes (due to e.g.
214 .Fn ukfs_chdir )
215 will be ignored.
216 Release 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
281 The above routines operate like their system call counterparts and the
282 system call manual pages without the ukfs_ prefix should be referred to
283 for further information on the parameters.
284 .Pp
285 The only call which modifies
286 .Fa ukfs
287 state is
288 .Fn ukfs_chdir .
289 It works like
290 .Xr chdir 2
291 in the sense that it affects the interpretation of relative paths.
292 If succesful, all relative pathnames will be resolved starting from the
293 current directory.
294 Currently the call affects all accesses to that particular
295 .Fa ,
296 but 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
303 Builds a directory hierarchy.
304 Unlike mkdir, the
305 .Fa pathname
306 argument may contain multiple levels of hierarchy.
307 It is not considered an error if any of the directories specified exist
308 already.
309 .Sh SEE ALSO
310 .Xr rump 3
311 .Sh HISTORY
312 .Nm
313 first appeared in
314 .Nx 5.0 .
315 .Sh AUTHORS
316 .An Antti Kantee Aq pooka@cs.hut.fi
317 .Sh NOTES
318 .Nm
319 should be considered experimental technology and may change without warning.
320 .Sh BUGS
321 On Linux, dynamically linked binaries can include support for only
322 one file system due to restrictions with the dynamic linker.
323 If more are desired, they must be loaded at runtime using
324 .Fn ukfs_modload .
325 Even though
326 .Nx
327 does not have this restriction, portable programs should load all
328 file system drivers dynamically.