1.\" $OpenBSD: fb_setup.9,v 1.4 2014/01/19 08:21:19 schwarze 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: January 19 2014 $ 18.Dt FB_SETUP 9 19.Os 20.Sh NAME 21.Nm fb_setup , 22.Nm fb_queue , 23.Nm fb_delete 24.Nd kernel messaging mechanism for file system in userland (FUSE) 25.Sh SYNOPSIS 26.In sys/fusebuf.h 27.Ft struct fusebuf * 28.Fn fb_setup "size_t size" "ino_t inode" "int type" "struct proc *p" 29.Ft int 30.Fn fb_queue "dev_t dev" "struct fusebuf *fbuf" 31.Ft void 32.Fn fb_delete "struct fusebuf *fbuf" 33.Bd -literal 34#define FUSEBUFMAXSIZE (4096*1024) 35#define FUSEBUFSIZE (sizeof(struct fusebuf)) 36 37struct fb_hdr { 38 SIMPLEQ_ENTRY(fusebuf) fh_next; 39 size_t fh_len; 40 int fh_err; 41 int fh_type; 42 ino_t fh_ino; 43 uint64_t fh_uuid; 44}; 45 46struct fb_io { 47 uint64_t fi_fd; 48 ino_t fi_ino; 49 off_t fi_off; 50 size_t fi_len; 51 mode_t fi_mode; 52 uint32_t fi_flags; 53}; 54 55struct fusebuf { 56 struct fb_hdr fb_hdr; 57 union { 58 struct statvfs FD_stat; 59 struct vattr FD_vattr; 60 struct fb_io FD_io; 61 62 } FD; 63 uint8_t *F_databuf; 64}; 65 66#define fb_next fb_hdr.fh_next 67#define fb_len fb_hdr.fh_len 68#define fb_err fb_hdr.fh_err 69#define fb_type fb_hdr.fh_type 70#define fb_ino fb_hdr.fh_ino 71#define fb_uuid fb_hdr.fh_uuid 72 73#define fb_stat FD.FD_stat 74#define fb_vattr FD.FD_vattr 75#define fb_io_fd FD.FD_io.fi_fd 76#define fb_io_ino FD.FD_io.fi_ino 77#define fb_io_off FD.FD_io.fi_off 78#define fb_io_len FD.FD_io.fi_len 79#define fb_io_mode FD.FD_io.fi_mode 80#define fb_io_flags FD.FD_io.fi_flags 81#define fb_dat F_databuf 82.Ed 83.Sh DESCRIPTION 84These functions provide a way to manage the kernel messaging mechanism for 85.Xr fuse 4 86file systems. 87It is based on 88.Xr mbuf 9 . 89.Pp 90Each FUSE operation fits in a fusebuf 91except for read, write, and readdirs, 92which are split into several fusebufs with a changing value in 93.Fa fb_io_off 94for each. 95The size of a fusebuf is 96.Fa FUSEBUFSIZE . 97.Pp 98A fusebuf structure is defined as an 99.Fa fb_hdr 100followed by a structure containing a union and a buffer 101.Fa F_Dat . 102The header contains the following elements: 103.Bl -tag -width foobarmoocow 104.It Fa fh_next 105A 106.Xr SIMPLEQ_ENTRY 3 107needed to store the different fusebufs stored with 108.Fn fb_queue . 109.It Fa fh_len 110Indicates the amount of data in 111.Fa F_dat . 112.It Fa fh_resid 113Used for partial 114.Xr fuse 4 115reads. 116If the read does not fill the fusebuf, the number of bytes of 117.Fa F_dat 118written in this field are stored. 119.It Fa fh_err 120Indicates the 121.Xr errno 2 122failure of a fusebuf. 123.It Fa fh_type 124Indicates the type of fusebuf transaction (see below). 125.It Fa fh_ino 126Indicates the inode on which the 127.Xr fuse 4 128operation is done. 129.It Fa fh_uuid 130UUID to track the answer. 131This number is generated with 132.Xr arc4random 9 . 133.El 134.Pp 135The 136.Fa fh_type 137variable can take the following values: 138.Pp 139.Bl -tag -compact -offset indent -width XXXXXXXXXXXXXXXXXX 140.It Dv FBT_LOOKUP 141The fusebuf is a lookup operation. 142.It Dv FBT_GETATTR 143The fusebuf is a gettattr operation. 144.It Dv FBT_SETATTR 145The fusebuf is a setattr operation. 146.It Dv FBT_READLINK 147The fusebuf is a readlink operation. 148.It Dv FBT_SYMLINK 149The fusebuf is a symlink operation. 150.It Dv FBT_MKNOD 151The fusebuf is a mknod operation. 152.It Dv FBT_MKDIR 153The fusebuf is a mkdir operation. 154.It Dv FBT_UNLINK 155The fusebuf is an unlink operation. 156.It Dv FBT_RMDIR 157The fusebuf is an rmdir operation. 158.It Dv FBT_RENAME 159The fusebuf is a rename operation. 160.It Dv FBT_LINK 161The fusebuf is a link operation. 162.It Dv FBT_OPEN 163The fusebuf is an open operation. 164.It Dv FBT_READ 165The fusebuf is a read operation. 166.It Dv FBT_WRITE 167The fusebuf is a write operation. 168.It Dv FBT_STATFS 169The fusebuf is a statfs operation. 170.It Dv FBT_RELEASE 171The fusebuf is a file close operation. 172.It Dv FBT_FSYNC 173The fusebuf is a file sync operation. 174.It Dv FBT_FLUSH 175The fusebuf is a flush operation. 176.It Dv FBT_INIT 177The fusebuf initializes the FUSE connection. 178.It Dv FBT_OPENDIR 179The fusebuf is an opendir operation. 180.It Dv FBT_READDIR 181The fusebuf is a readdir operation. 182.It Dv FBT_RELEASEDIR 183The fusebuf is a close dir operation. 184.It Dv FBT_FSYNCDIR 185The fusebuf is a dir sync operation. 186.It Dv FBT_ACCESS 187The fusebuf is an access operation. 188.It Dv FBT_CREATE 189The fusebuf is a create file operation. 190.It Dv FBT_DESTROY 191The fusebuf closes the FUSE connection. 192.El 193.Pp 194All the data needed by the FUSE clients is contained in the 195.Fa F_dat 196structure. 197This structure contains a union 198.Fa FD 199of frequently used type 200and a buffer 201.Fa F_databuf 202to send data to libfuse. 203The union contains the following elements: 204.Bl -tag -width foobarmoocow 205.It Fa FD_stat 206A struct 207.Xr statvfs 3 208filled in by the FUSE client statfs for the FUSE VFS statfs code. 209.It Fa FD_vattr 210Used by the getattr and setattr calls. 211.It Fa FD_io 212Contains all fields commonly used by FUSE client callbacks to 213provide information to FUSE vnops. 214It is used by access, readdir, release, releasedir, read, write, create, 215mkdir, and setattr. 216.El 217.Pp 218Setattr uses a struct fb_io and a struct vattr. 219Settattr uses 220.Fa FD_stat 221and encapsulates a struct fb_io in 222.Fa F_databuf 223with 224.Fa fbtod . 225.Pp 226Fusebufs can be deleted with the 227.Fn fb_delete 228helper. 229.Sh SEE ALSO 230.Xr errno 2 , 231.\".Xr fuse_main 3 , 232.Xr queue 3 , 233.Xr statvfs 3 , 234.Xr fuse 4 , 235.Xr arc4random 9 , 236.Xr mbuf 9 237.Sh HISTORY 238The 239.Nm 240API first appeared in 241.Ox 5.4 . 242