path: root/lib/libfuse/fuse.3

.\" $OpenBSD: fuse.3,v 1.7 2013/06/14 20:49:06 syl Exp $
.\"
.\" Copyright (c) 2013 Sylvestre Gallon <ccna.syl@gmail.com>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: June 14 2013 $
.Dt FUSE 3
.Os
.Sh NAME
.Nm fuse ,
.Nm fuse_version ,
.Nm fuse_main ,
.Nm fuse_new ,
.Nm fuse_parse_cmdline ,
.Nm fuse_mount ,
.Nm fuse_remove_signal_handlers ,
.Nm fuse_set_signal_handlers ,
.Nm fuse_get_session ,
.Nm fuse_get_context ,
.Nm fuse_is_lib_option ,
.Nm fuse_loop ,
.Nm fuse_loop_mt ,
.Nm fuse_chan_fd ,
.Nm fuse_unmount ,
.Nm fuse_daemonize ,
.Nm fuse_destroy
.Nd FUSE implementation routines
.Sh SYNOPSIS
.In fuse.h
.Ft int
.Fn fuse_version "void"
.Ft int
.Fn fuse_main "int argc" "char **argv" "const struct fuse_operations *ops" \
    "void *data"
.Ft struct fuse *
.Fn fuse_new "struct fuse_chan *fc" "struct fuse_args *args" \
    "const struct fuse_operations *ops" "size_t size" "void *userdata"
.Ft int
.Fn fuse_parse_cmdline "struct fuse_args *args" "char **mp" "int *mt" "int *fg"
.Ft struct fuse_chan *
.Fn fuse_mount "const char *dir" "struct fuse_args *args"
.Ft void
.Fn fuse_remove_signal_handlers "struct fuse_session *se"
.Ft int
.Fn fuse_set_signal_handlers "struct fuse_session *se"
.Ft struct fuse_session *
.Fn fuse_get_session "struct fuse *f"
.Ft struct fuse_context *
.Fn fuse_get_context "void"
.Ft int
.Fn fuse_is_lib_option "const char *opt"
.Ft int
.Fn fuse_loop "struct fuse *fuse"
.Ft int
.Fn fuse_loop_mt "struct fuse *fuse"
.Ft int
.Fn fuse_chan_fd "struct fuse_chan *ch"
.Ft void
.Fn fuse_unmount "const char *dir" "struct fuse_chan *ch"
.Ft int
.Fn fuse_daemonize "int foreground"
.Ft void
.Fn fuse_destroy "struct fuse *f"
.Sh DESCRIPTION
The
.Nm
library provides routines to implement a filesystem in userspace.
.Pp
There are two ways of Implementing a Fuse filesystem.
You can implement a FS by calling only
.Fn fuse_main
and passing this function the
.Em ops
argument containing all the callbacks of the filesystem.
Or you can use all others functions.
.Ss FUNCTIONS
.Fn fuse_version
returns the fuse version number.
.Pp
.Fn fuse_new
returns a
.Fa struct fuse
that will be needed by
.Fn fuse_loop .
.Pp
.Fn fuse_parse_cmdline
parses the
.Fa struct fuse_args
given by the user and will set
.Fa mp
with a char * containing the mountpoint directory.
.Pp
.Fn fuse_mount
will look for an empty
.Xr fuse 4
device to create a connection.
If this function finds an available device it will open it for fuse
communication with the fuse VFS driver and will mount the filesystem.
This function will return a
.Fa struct fuse_chan
that will be needed by
.Fn fuse_new .
.Pp
.Fn fuse_remove_signal_handlers
I do not know yet what this function is supposed to do...
.Pp
.Fn fuse_set_signal_handlers
I do not know yet what this function is supposed to do...
.Pp
.Fn fuse_get_session
returns a pointer to the structure
.Fa fuse_session
contained in a
.Fa struct fuse .
.Pp
.Fn fuse_get_context
returns a pointer to the structure
.Fa fuse_context .
The returned fuse_context is only available during the lifetime of a fuse
operation.
.Pp
.Fn fuse_is_lib_option
checks if the string
.Fa opt
is an option handled by the libfuse or by the fuse client.
It returns 1 if it is handled by the lib and 0 otherwise.
.Pp
.Fn fuse_loop_mt
Do not use!
It is not supported yet (and we will probably never need it...)
.Pp
.Fn fuse_loop
is the main loop of a fuse program.
This function will look for fuse requests from kernel and will respond to them
using the
.Fa struct fuse_operation
present in the structure
.Fa fuse .
It will return only if something goes wrong
or if the kernel sends a
.Fa FUSE_DESTROY
opcode to libfuse.
.Pp
.Fn fuse_chan_fd
returns the filedescriptor used by the given
.Fa fuse_chan
structure.
.Pp
.Fn fuse_unmount
unmounts the
.Fa dir
mountpoint.
.Pp
.Fn fuse_daemonize
daemonises the fuse library.
It will permit to background the fuse program that will continue to handle
kernel filesystem opcodes.
.Pp
.Fn fuse_destroy
I do not know yet what this function is supposed to do...
.Sh EXAMPLES
Here is a simple example of a fuse implementation:
.Bd -literal
#include <errno.h>
#include <fuse.h>
#include <string.h>

static int
fs_readdir(const char *path, void *data, fuse_fill_dir_t filler,
    off_t off, struct fuse_file_info *ffi)
{
	if (strcmp(path, "/") != 0)
		return (-ENOENT);

	filler(data, ".", NULL, 0);
	filler(data, "..", NULL, 0);
	filler(data, "file", NULL, 0);
	return (0);
}

static int
fs_read(const char *path, char *buf, size_t size, off_t off,
    struct fuse_file_info *ffi)
{
	if (off >= 5)
		return (0);

	size = 5 - off;
	memcpy(buf, "data." + off, size);
	return (size);
}

static int
fs_open(const char *path, struct fuse_file_info *ffi)
{
	if (strncmp(path, "/file", 10) != 0)
		return (-ENOENT);

	if ((ffi->flags & 3) != O_RDONLY)
		return (-EACCES);

	return (0);
}

static int
fs_getattr(const char *path, struct stat *st)
{
	if (strcmp(path, "/") == 0) {
		st->st_blksize = 512;
		st->st_mode = 0755;
		st->st_nlink = 2;
	} else if (strcmp(path, "/file") == 0) {
		st->st_mode = 0644;
		st->st_blksize = 512;
		st->st_nlink = 1;
		st->st_size = 5;
	} else {
		return (-ENOENT);
	}

	return (0);
}

struct fuse_operations fsops = {
	.readdir = fs_readdir,
	.read = fs_read,
	.open = fs_open,
	.getattr = fs_getattr,
};

int
main(int ac, char **av)
{
	return (fuse_main(ac, av, &fsops, NULL));
}
.Ed
.Sh SEE ALSO
The
.Tn FUSE
specifications and orignal implementation can be found at:
.Lk http://fuse.sourceforge.net/
.Pp
.Xr fuse 4
.Sh HISTORY
The
.Nm
library first appeared in
.Ox 5.4 .
.Sh BUGS
This man page is woefully incomplete.