1.\" $OpenBSD: fuse_new.3,v 1.7 2022/03/31 17:27:17 naddy Exp $ 2.\" 3.\" Copyright (c) 2013 Sylvestre Gallon <ccna.syl@gmail.com> 4.\" Copyright (c) 2018 Helg Bredow <helg@openbsd.org> 5.\" 6.\" Permission to use, copy, modify, and distribute this software for any 7.\" purpose with or without fee is hereby granted, provided that the above 8.\" copyright notice and this permission notice appear in all copies. 9.\" 10.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 11.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 12.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 13.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 14.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 15.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 16.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 17.\" 18.Dd $Mdocdate: March 31 2022 $ 19.Dt FUSE_NEW 3 20.Os 21.Sh NAME 22.Nm fuse_new 23.Nd FUSE implementation routine to initialise the FUSE connection 24.Sh SYNOPSIS 25.In fuse.h 26.Ft struct fuse * 27.Fn fuse_new "struct fuse_chan *fc" "struct fuse_args *args" \ 28 "const struct fuse_operations *ops" "unused size_t size" \ 29 "void *userdata" 30.Sh DESCRIPTION 31Initialises the FUSE library on the channel returned by 32.Xr fuse_mount 3 . 33.Pp 34FUSE operations work in the same way as their UNIX file system 35counterparts. 36A major exception is that these routines return 37a negated errno value (-errno) on failure. 38.Pp 39All operations are optional but a functional file system will want to 40implement at least statfs, readdir, open, read and getattr. 41FUSE will return ENOSYS if any operation other than flush, fsync or 42fsyncdir is not implemented. 43.Pp 44The first parameter to each of these operations (except for init and 45terminate) is a NULL terminated string representing the full path to 46the file or directory, relative to the root of this file system, that 47is being operated on. 48.Bd -literal 49struct fuse_operations { 50 int (*getattr)(const char *, struct stat *); 51 int (*readlink)(const char *, char *, size_t); 52 int (*getdir)(const char *, fuse_dirh_t, fuse_dirfil_t); 53 int (*mknod)(const char *, mode_t, dev_t); 54 int (*mkdir)(const char *, mode_t); 55 int (*unlink)(const char *); 56 int (*rmdir)(const char *); 57 int (*symlink)(const char *, const char *); 58 int (*rename)(const char *, const char *); 59 int (*link)(const char *, const char *); 60 int (*chmod)(const char *, mode_t); 61 int (*chown)(const char *, uid_t, gid_t); 62 int (*truncate)(const char *, off_t); 63 int (*utime)(const char *, struct utimbuf *); 64 int (*open)(const char *, struct fuse_file_info *); 65 int (*read)(const char *, char *, size_t, off_t, 66 struct fuse_file_info *); 67 int (*write)(const char *, const char *, size_t, off_t, 68 struct fuse_file_info *); 69 int (*statfs)(const char *, struct statvfs *); 70 int (*flush)(const char *, struct fuse_file_info *); 71 int (*release)(const char *, struct fuse_file_info *); 72 int (*fsync)(const char *, int, struct fuse_file_info *); 73 int (*setxattr)(const char *, const char *, const char *, 74 size_t int); 75 int (*getxattr)(const char *, const char *, char *, size_t); 76 int (*listxattr)(const char *, char *, size_t); 77 int (*removexattr)(const char *, const char *); 78 int (*opendir)(const char *, struct fuse_file_info *); 79 int (*readdir)(const char *, void *, fuse_fill_dir_t, off_t, 80 struct fuse_file_info *); 81 int (*releasedir)(const char *, struct fuse_file_info *); 82 int (*fsyncdir)(const char *, int, struct fuse_file_info *); 83 void *(*init)(struct fuse_conn_info *); 84 void (*destroy)(void *); 85 int (*access)(const char *, int); 86 int (*create)(const char *, mode_t, struct fuse_file_info *); 87 int (*ftruncate)(const char *, off_t, struct fuse_file_info *); 88 int (*fgetattr)(const char *, struct stat *, struct 89 fuse_file_info *); 90 int (*lock)(const char *, struct fuse_file_info *, int, 91 struct flock *); 92 int (*utimens)(const char *, const struct timespec *); 93 int (*bmap)(const char *, size_t , uint64_t *); 94}; 95.Ed 96.Pp 97The order of calls is: 98.Bd -literal -offset indent 99init 100\&... 101opendir 102readdir 103releasedir 104open 105read 106write 107\&... 108flush 109release 110\&... 111destroy 112.Ed 113.Bl -tag -width "releasedir" 114.It access 115Not implemented. 116.Ox 117always behaves as if the default_permissions mount option was specified. 118See 119.Xr fuse_mount 3 . 120.It chmod 121Called when file access permissions are changed. 122.It chown 123Called when either the file owner or group is changed. 124.It create 125Not implemented on 126.Ox . 127File systems must implement mknod instead. 128In the reference implementation this is an atomic operation that both 129creates and opens the file. 130There is no equivalent in the 131.Ox 132VFS. 133.It flush 134Called when the file is closed by the 135.Xr close 2 136system call. 137This is the only way for a file system to return an error on close. 138.It fsync 139Optional function that implements 140.Xr fsync 2 141and 142.Xr fdatasync 2 . 143The datasync parameter specifies whether the operation is as a result 144of a call to 145.Xr fdatasync 2 146and is currently always 0 (false). 147ffi.fh_id will contain the file handle returned by the file system when 148the file was opened. 149.It fsyncdir 150Not implemented. 151.It getattr 152Corresponds to the 153.Xr stat 2 154system call. 155Flags and extended attributes are ignored. 156This operation is mandatory. 157.It getxattr 158Not implemented. 159.It getdir 160Deprecated. 161File system should implement readdir instead. 162.It mknod 163Called on 164.Xr open 2 165and 166.Xr mknod 2 167to create regular files, pipes and device special files. 168.It open 169Called on 170.Xr open 2 . 171Due to the difference between FUSE and the 172.Ox 173VFS, 174open will only be called once for each file 175for every different combination of flags provided to 176.Xr open 2 . 177The O_CREAT and O_TRUNC flags are never passed from the kernel to open, 178the mknod and truncate operations are invoked before open instead. 179.It opendir 180Called when a directory is opened for reading. 181.It release 182Called when there are no more references to the file. 183.It releasedir 184Called when there are no more references to the directory. 185.It setattr 186Equivalent to 187.Xr chown 2 188and 189.Xr chmod 2 190system calls. 191Setting file flags is not supported. 192.It setxattr 193Not implemented. 194.El 195.Pp 196Options supported by args are: 197.Bl -tag -width "readdir_ino" 198.It debug, -d 199Print debug information to stdout. 200.It gid=%u 201The GID that will be reported as the group for all files by getattr. 202.It hard_remove 203Immediately delete a file even if it's currently open by a process. 204Otherwise FUSE will temporarily rename the file and only delete it when 205it is no longer referenced. 206This is to avoid the file system having to deal with this situation. 207This is always set on 208.Ox . 209.It readdir_ino 210Similar to use_ino but the file system's inode number is only reported 211for readdir. 212This is always set on 213.Ox 214because it's required by 215.Xr getcwd 3 . 216.It uid=%u 217The UID that will be reported as the owner for all files by getattr. 218.It umask=%o 219The file mode mask applied to the permission for all files by getattr. 220.It use_ino 221By default, FUSE will return an internal inode number for getattr and 222readdir and this will be different every time the file system is 223mounted. 224If this is set, the file system's own inode number will be 225reported instead. 226Useful only for file system that have inode numbers. 227.El 228.Sh SEE ALSO 229.Xr fuse_get_context 3 , 230.Xr fuse_main 3 , 231.Xr fuse_mount 3 232.Sh STANDARDS 233The 234.Fn fuse_new 235function conforms to FUSE 2.6. 236.Sh HISTORY 237The 238.Fn fuse_new 239function first appeared in 240.Ox 5.4 . 241.Sh AUTHORS 242.An Sylvestre Gallon Aq Mt ccna.syl@gmail.com 243.An Helg Bredow Aq Mt helg@openbsd.org 244