1.\" $OpenBSD: fuse_main.3,v 1.2 2016/05/18 17:36:24 jmc Exp $ 2.\" 3.\" Copyright (c) 2013 Sylvestre Gallon <ccna.syl@gmail.com> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: May 18 2016 $ 18.Dt FUSE_MAIN 3 19.Os 20.Sh NAME 21.Nm fuse_main , 22.Nm fuse_version , 23.Nm fuse_new , 24.Nm fuse_parse_cmdline , 25.Nm fuse_mount , 26.Nm fuse_remove_signal_handlers , 27.Nm fuse_set_signal_handlers , 28.Nm fuse_get_session , 29.Nm fuse_get_context , 30.Nm fuse_is_lib_option , 31.Nm fuse_loop , 32.Nm fuse_loop_mt , 33.Nm fuse_chan_fd , 34.Nm fuse_unmount , 35.Nm fuse_daemonize , 36.Nm fuse_destroy , 37.Nm fuse_teardown 38.Nd FUSE implementation routines 39.Sh SYNOPSIS 40.In fuse.h 41.Ft int 42.Fn fuse_main "int argc" "char **argv" "const struct fuse_operations *ops" \ 43 "void *data" 44.Ft int 45.Fn fuse_version "void" 46.Ft struct fuse * 47.Fn fuse_new "struct fuse_chan *fc" "struct fuse_args *args" \ 48 "const struct fuse_operations *ops" "size_t size" "void *userdata" 49.Ft int 50.Fn fuse_parse_cmdline "struct fuse_args *args" "char **mp" "int *mt" "int *fg" 51.Ft struct fuse_chan * 52.Fn fuse_mount "const char *dir" "struct fuse_args *args" 53.Ft void 54.Fn fuse_remove_signal_handlers "struct fuse_session *se" 55.Ft int 56.Fn fuse_set_signal_handlers "struct fuse_session *se" 57.Ft struct fuse_session * 58.Fn fuse_get_session "struct fuse *f" 59.Ft struct fuse_context * 60.Fn fuse_get_context "void" 61.Ft int 62.Fn fuse_is_lib_option "const char *opt" 63.Ft int 64.Fn fuse_loop "struct fuse *fuse" 65.Ft int 66.Fn fuse_loop_mt "struct fuse *fuse" 67.Ft int 68.Fn fuse_chan_fd "struct fuse_chan *ch" 69.Ft void 70.Fn fuse_unmount "const char *dir" "struct fuse_chan *ch" 71.Ft int 72.Fn fuse_daemonize "int foreground" 73.Ft void 74.Fn fuse_destroy "struct fuse *f" 75.Ft void 76.Fn fuse_teardown "struct fuse *f" "char *mp" 77.Sh DESCRIPTION 78The FUSE library provides routines to implement a filesystem in userspace. 79.Pp 80There are two ways of implementing a FUSE filesystem: 81by calling only 82.Fn fuse_main 83and passing this function the 84.Em ops 85argument containing all the callbacks of the filesystem, 86or by using the other functions, 87as detailed below. 88.Pp 89.Fn fuse_version 90returns the FUSE version number. 91.Pp 92.Fn fuse_new 93returns a 94.Fa struct fuse 95that will be needed by 96.Fn fuse_loop . 97.Pp 98.Fn fuse_parse_cmdline 99parses the 100.Fa struct fuse_args 101given by the user and will set 102.Fa mp 103with a char * containing the mountpoint directory. 104.Pp 105.Fn fuse_mount 106looks for an empty 107.Xr fuse 4 108device to create a connection. 109If this function finds an available device it will open it for FUSE 110communication with the FUSE VFS driver and will mount the filesystem. 111This function will return a 112.Fa struct fuse_chan 113that will be needed by 114.Fn fuse_new . 115.Pp 116.Fn fuse_remove_signal_handlers 117is currently undocumented. 118.Pp 119.Fn fuse_set_signal_handlers 120is currently undocumented. 121.Pp 122.Fn fuse_get_session 123returns a pointer to the structure 124.Fa fuse_session 125contained in a 126.Fa struct fuse . 127.Pp 128.Fn fuse_get_context 129returns a pointer to the structure 130.Fa fuse_context . 131The returned fuse_context is only available during the lifetime of a FUSE 132operation. 133.Pp 134.Fn fuse_is_lib_option 135checks if the string 136.Fa opt 137is an option handled by libfuse or by the FUSE client. 138It returns 1 if it is handled by the lib and 0 otherwise. 139.Pp 140.Fn fuse_loop_mt 141is unsupported. 142.Pp 143.Fn fuse_loop 144is the main loop of a FUSE program. 145This function looks for FUSE requests from the kernel and responds to them 146using the 147.Fa struct fuse_operation 148present in the structure 149.Fa fuse . 150It will return only if something goes wrong 151or if the kernel sends a 152.Fa FUSE_DESTROY 153opcode to libfuse. 154.Pp 155.Fn fuse_chan_fd 156returns the filedescriptor used by the given 157.Fa fuse_chan 158structure. 159.Pp 160.Fn fuse_unmount 161unmounts the 162.Fa dir 163mountpoint. 164.Pp 165.Fn fuse_daemonize 166daemonises the FUSE library. 167It runs the FUSE program in the background, 168whilst continuing to handle kernel filesystem opcodes. 169.Pp 170.Fn fuse_destroy 171is currently undocumented. 172.Pp 173.Fn fuse_teardown 174calls 175.Fn fuse_unmount 176and 177.Fn fuse_destroy . 178.Sh EXAMPLES 179Here is a simple example of a FUSE implementation: 180.Bd -literal 181#include <errno.h> 182#include <fuse.h> 183#include <string.h> 184 185static int 186fs_readdir(const char *path, void *data, fuse_fill_dir_t filler, 187 off_t off, struct fuse_file_info *ffi) 188{ 189 if (strcmp(path, "/") != 0) 190 return (-ENOENT); 191 192 filler(data, ".", NULL, 0); 193 filler(data, "..", NULL, 0); 194 filler(data, "file", NULL, 0); 195 return (0); 196} 197 198static int 199fs_read(const char *path, char *buf, size_t size, off_t off, 200 struct fuse_file_info *ffi) 201{ 202 if (off >= 5) 203 return (0); 204 205 size = 5 - off; 206 memcpy(buf, "data." + off, size); 207 return (size); 208} 209 210static int 211fs_open(const char *path, struct fuse_file_info *ffi) 212{ 213 if (strncmp(path, "/file", 10) != 0) 214 return (-ENOENT); 215 216 if ((ffi->flags & 3) != O_RDONLY) 217 return (-EACCES); 218 219 return (0); 220} 221 222static int 223fs_getattr(const char *path, struct stat *st) 224{ 225 if (strcmp(path, "/") == 0) { 226 st->st_blksize = 512; 227 st->st_mode = 0755; 228 st->st_nlink = 2; 229 } else if (strcmp(path, "/file") == 0) { 230 st->st_mode = 0644; 231 st->st_blksize = 512; 232 st->st_nlink = 1; 233 st->st_size = 5; 234 } else { 235 return (-ENOENT); 236 } 237 238 return (0); 239} 240 241struct fuse_operations fsops = { 242 .readdir = fs_readdir, 243 .read = fs_read, 244 .open = fs_open, 245 .getattr = fs_getattr, 246}; 247 248int 249main(int ac, char **av) 250{ 251 return (fuse_main(ac, av, &fsops, NULL)); 252} 253.Ed 254.Sh SEE ALSO 255.Xr fuse 4 256.Sh STANDARDS 257The original FUSE specification can be found at 258.Lk http://libfuse.github.io/doxygen/ . 259The original implementation can be found at 260.Lk https://github.com/libfuse/libfuse/ . 261.Sh HISTORY 262The FUSE library first appeared in 263.Ox 5.4 . 264.Sh BUGS 265This man page is woefully incomplete. 266