.\" $OpenBSD: fuse.3,v 1.3 2013/06/03 19:13:21 tedu 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 3 2013 $
.Dt FUSE 3
.Os
.Sh NAME
.Nm fuse ,
.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_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
.Fd #include \*[Lt]fuse.h\*[Gt]
.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 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 routine to implement a filesystem in userspace.
.Ss INTRODUCTION
There is two way of Implementing a Fuse filesystem. You can implement a fs only
by calling
.Fn fuse_main
and giving this function the
.Em ops
argument containing all the callbacks of your filesystems. Or you can use all
others functions.
.Ss FUNCTIONS
.Fn fuse_new
Fuse new return a
.Fa struct fuse
That will be needed by
.Fn fuse_loop
.Pp
.Fn fuse_parse_cmdline
This function will parse 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 find an available device it will
open it to use 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 on the structure
.Fa fuse_session
contained in a
.Fa struct fuse
.Pp
.Fn fuse_is_lib_option
check 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 in the other case.
.Pp
.Fn fuse_loop_mt
Do not use! It is not supported yet (and we will probably never need it...)
.Pp
.Fn fuse_loop
This is the mainloop of a fuse program. This function will look for fuse
request from kernel and will respond to it using the
.Fa struct fuse_operation
present in the structure
.Fa fuse.
It will return only if something goes wrong
or if the kernel send 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
unmount the
.Fa dir
mountpoint.
.Pp
.Fn fuse_daemonize
daemonise the fuse library. It will permit to background the fuse program that
will continue to handles kernel filesystems opcodes.
.Pp
.Fn fuse_destroy
I do not know yet what this function is supposed to do...
.Sh EXAMPLE
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