Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.

UKFS(3)                    Library Functions Manual                    UKFS(3)

     ukfs - user kernel file system library interface

     ukfs Library (libukfs, -lukfs)

     #include <rump/ukfs.h>

     The ukfs library provides direct access to file systems without having to
     specially mount a file system.  Therefore, accessing a file system
     through ukfs requires no special kernel support apart from standard POSIX
     functionality.  As ukfs is built upon rump(3) kernels, all kernel file
     systems which are supported by rump kernels are available.  It allows to
     write utilities for accessing file systems without having to duplicate
     file system internals knowledge already present in kernel file system

     ukfs provides a high-level pathname based interface for accessing file
     systems.  If a lower level interface it desired, rump(3) kernels should
     be used directly.  However, much like system calls, the interfaces of
     ukfs are self-contained and require no tracking and release of resources.
     The only exception is the file system handle struct ukfs which should be
     released after use.


     ukfs_modload(const char *fname)

     ukfs_modload_dir(const char *dirname)

     ukfs_vfstypes(char *buf, size_t buflen)

     struct ukfs *
     ukfs_mount(const char *vfsname, const char *devpath, const char
     *mountpath, int mntflags, void *arg, size_t alen)

     struct ukfs *
     ukfs_mount_disk(const char *vfsname, const char *devpath, int partition,
     const char *mountpath, int mntflags, void *arg, size_t alen)

     ukfs_release(struct ukfs *ukfs, int flags)

     ukfs_init() initializes the library and must be called once per process
     using ukfs.

     ukfs_modload() is used at runtime to dynamically load a library which
     contains a file system module.  For this to succeed, the rump(3) kernel
     and the module targeted must be compiled with compatible kernel versions
     and the application must be dynamically linked.  Additionally, since this
     routine does not handle dependencies, all the dependencies of the library
     must be loaded beforehand.  The routine returns -1 for fatal error, 0 for
     dependency failure and 1 for success.

     ukfs_modload_dir() loads all rump(3) kernel file system components in
     directory dirname.  It looks for libraries which begin with librumpfs_
     and end in .so.  The routine tries to handle dependencies by retrying to
     load libraries which failed due to dependencies.  ukfs_modload_dir()
     returns the number of vfs modules loaded or sets errno and returns -1 in
     case of a fatal error in directory searching.  In case a fatal error
     occurs after some modules have already been loaded, the number of loaded
     module is returned.  Fatal errors in loading the modules themselves are
     ignored and ukfs_modload() should be used directly if finegrained error
     reporting is desired.

     It should be noted that the above routines affect the whole process, not
     just a specific instance of ukfs.  It is preferable to call them from
     only one thread, as the underlying dynamic library interfaces may not be

     ukfs_vfstypes() queries the available file system types and returns a
     nul-terminated list of types separated by spaces in buf.  The format of
     the list is equivalent to the one returned by sysctl(3) on the name
     vfs.generic.fstypes.  The function returns the length of the string
     without the trailing nul or -1 for error.  Notably, the return value 0
     means there are no file systems available.  If there is not enough room
     in the caller's buffer for all file system types, as many as fit will be

     ukfs_mount() initializes a file system image.  The handle resulting from
     the operation is passed to all other routines and identifies the instance
     of the mount analogous to what a pathname specifies in a normally mounted
     file system.  The parameters are the following:

                Name of the file system to be used, e.g.  MOUNT_FFS.

                Path of file system image.  It can be either a regular file,
                device or, if the file system does not support the concept of
                a device, an arbitrary string, e.g. network address.

                Path where the file system is mounted to.  This parameter is
                used only by the file system being mounted.  Most of the time
                UKFS_DEFAULTMP is the correct path.

                Flags as passed to the mount(2) system call, for example
                MNT_RDONLY.  In addition to generic parameters, file system
                specific parameters such as MNT_LOG (ffs) may be passed here.

           arg  File system private argument structure.  This is passed
                directly to the file system.  It must match what vfsname

                Size of said structure.

     The ukfs_mount_disk() function must be used to mount disk-based file
     systems.  It takes the same arguments as ukfs_mount(), except for an
     additional argument signifying the partition number.  If the image
     devpath contains a disklabel, this value specifies the number of the
     partition within the image used as the file system backend.  If devpath
     does not contain a disklabel, the value UKFS_PARTITION_NONE must be used
     to signal that the file system backend is the entire image.

     ukfs_release() unmounts the file system and releases the resources
     associated with ukfs.  The return value signals the return value of the
     unmount operation.  If non-zero, ukfs will continue to remain valid.  The
     possible values for flags are:

           UKFS_RELFLAG_NOUNMOUNT  Do not unmount file system, just release
                                   ukfs handle.  Release always succeeds.

           UKFS_RELFLAG_FORCE      Forcefully unmount the file system.  This
                                   means that any busy nodes (due to e.g.
                                   ukfs_chdir()) will be ignored.  Release
                                   always succeeds.

     ukfs_chdir(struct ukfs *ukfs, const char *path)

     ukfs_getdents(struct ukfs *ukfs, const char *dirname, off_t *off, uint8_t
     *buf, size_t bufsize)

     ukfs_read(struct ukfs *ukfs, const char *filename, off_t off, uint8_t
     *buf, size_t bufsize)

     ukfs_write(struct ukfs *ukfs, const char *filename, off_t off, uint8_t
     *buf, size_t bufsize)

     ukfs_create(struct ukfs *ukfs, const char *filename, mode_t mode)

     ukfs_mknod(struct ukfs *ukfs, const char *path, mode_t mode, dev_t dev)

     ukfs_mkfifo(struct ukfs *ukfs, const char *path, mode_t mode)

     ukfs_mkdir(struct ukfs *ukfs, const char *filename, mode_t mode)

     ukfs_remove(struct ukfs *ukfs, const char *filename)

     ukfs_rmdir(struct ukfs *ukfs, const char *filename)

     ukfs_link(struct ukfs *ukfs, const char *filename, const char *f_create)

     ukfs_symlink(struct ukfs *ukfs, const char *filename, const char

     ukfs_readlink(struct ukfs *ukfs, const char *filename, char *linkbuf,
     size_t buflen)

     ukfs_rename(struct ukfs *ukfs, const char *from, const char *to)

     ukfs_stat(struct ukfs *ukfs, const char *filename, struct stat

     ukfs_lstat(struct ukfs *ukfs, const char *filename, struct stat

     ukfs_chmod(struct ukfs *ukfs, const char *filename, mode_t mode)

     ukfs_lchmod(struct ukfs *ukfs, const char *filename, mode_t mode)

     ukfs_chown(struct ukfs *ukfs, const char *filename, uid_t uid, gid_t gid)

     ukfs_lchown(struct ukfs *ukfs, const char *filename, uid_t uid, gid_t

     ukfs_chflags(struct ukfs *ukfs, const char *filename, u_long flags)

     ukfs_lchflags(struct ukfs *ukfs, const char *filename, u_long flags)

     ukfs_utimes(struct ukfs *ukfs, const char *filename, const struct timeval

     ukfs_lutimes(struct ukfs *ukfs, const char *filename, const struct
     timeval *tptr)

     The above routines operate like their system call counterparts and the
     system call manual pages without the ukfs_ prefix should be referred to
     for further information on the parameters.

     The only call which modifies ukfs state is ukfs_chdir().  It works like
     chdir(2) in the sense that it affects the interpretation of relative
     paths.  If successful, all relative pathnames will be resolved starting
     from the current directory.  Currently the call affects all accesses to
     that particular ukfs, but it might be later changed to be thread private.

     ukfs_util_builddirs(struct ukfs *ukfs, const char *pathname, mode_t mode)

     Builds a directory hierarchy.  Unlike mkdir, the pathname argument may
     contain multiple levels of hierarchy.  It is not considered an error if
     any of the directories specified exist already.


     ukfs first appeared in NetBSD 5.0.

     Antti Kantee <pooka@cs.hut.fi>

     ukfs was an early attempt at an interface for kernel file systems running
     in userspace.

NetBSD 9.99                     March 12, 2018                     NetBSD 9.99