1.\" $OpenBSD: fb_setup.9,v 1.7 2017/11/30 11:29:03 helg 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: November 30 2017 $ 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 stat FD_attr; 60 struct fb_io FD_io; 61 62 } FD; 63 uint8_t *fb_dat; 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_attr FD.FD_attr 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.Ed 82.Sh DESCRIPTION 83These functions provide a way to manage the kernel messaging mechanism for 84.Xr fuse 4 85file systems. 86It is based on 87.Xr mbuf 9 . 88.Pp 89Each FUSE operation fits in a fusebuf 90except for read, write, and readdirs, 91which are split into several fusebufs with a changing value in 92.Fa fb_io_off 93for each. 94The size of a fusebuf is 95.Fa FUSEBUFSIZE . 96.Pp 97A fusebuf structure is defined as an 98.Fa fb_hdr 99followed by a structure containing a union and a buffer 100.Fa F_Dat . 101The header contains the following elements: 102.Bl -tag -width foobarmoocow 103.It Fa fh_next 104A 105.Xr SIMPLEQ_ENTRY 3 106needed to store the different fusebufs stored with 107.Fn fb_queue . 108.It Fa fh_len 109Indicates the amount of data in 110.Fa F_dat . 111.It Fa fh_resid 112Used for partial 113.Xr fuse 4 114reads. 115If the read does not fill the fusebuf, the number of bytes of 116.Fa F_dat 117written in this field are stored. 118.It Fa fh_err 119Indicates the 120.Xr errno 2 121failure of a fusebuf. 122.It Fa fh_type 123Indicates the type of fusebuf transaction (see below). 124.It Fa fh_ino 125Indicates the inode on which the 126.Xr fuse 4 127operation is done. 128.It Fa fh_uuid 129UUID to track the answer. 130This number is generated with 131.Xr arc4random 9 . 132.El 133.Pp 134The 135.Fa fh_type 136variable can take the following values: 137.Pp 138.Bl -tag -compact -offset indent -width XXXXXXXXXXXXXXXXXX 139.It Dv FBT_LOOKUP 140The fusebuf is a lookup operation. 141.It Dv FBT_GETATTR 142The fusebuf is a gettattr operation. 143.It Dv FBT_SETATTR 144The fusebuf is a setattr operation. 145.It Dv FBT_READLINK 146The fusebuf is a readlink operation. 147.It Dv FBT_SYMLINK 148The fusebuf is a symlink operation. 149.It Dv FBT_MKNOD 150The fusebuf is a mknod operation. 151.It Dv FBT_MKDIR 152The fusebuf is a mkdir operation. 153.It Dv FBT_UNLINK 154The fusebuf is an unlink operation. 155.It Dv FBT_RMDIR 156The fusebuf is an rmdir operation. 157.It Dv FBT_RENAME 158The fusebuf is a rename operation. 159.It Dv FBT_LINK 160The fusebuf is a link operation. 161.It Dv FBT_OPEN 162The fusebuf is an open operation. 163.It Dv FBT_READ 164The fusebuf is a read operation. 165.It Dv FBT_WRITE 166The fusebuf is a write operation. 167.It Dv FBT_STATFS 168The fusebuf is a statfs operation. 169.It Dv FBT_RELEASE 170The fusebuf is a file close operation. 171.It Dv FBT_FSYNC 172The fusebuf is a file sync operation. 173.It Dv FBT_FLUSH 174The fusebuf is a flush operation. 175.It Dv FBT_INIT 176The fusebuf initializes the FUSE connection. 177.It Dv FBT_OPENDIR 178The fusebuf is an opendir operation. 179.It Dv FBT_READDIR 180The fusebuf is a readdir operation. 181.It Dv FBT_RELEASEDIR 182The fusebuf is a close dir operation. 183.It Dv FBT_FSYNCDIR 184The fusebuf is a dir sync operation. 185.It Dv FBT_ACCESS 186The fusebuf is an access operation. 187.It Dv FBT_DESTROY 188The fusebuf closes the FUSE connection. 189.El 190.Pp 191All the data needed by the FUSE clients is contained in the 192.Fa F_dat 193structure. 194This structure contains a union 195.Fa FD 196of frequently used type 197and a buffer 198.Fa F_databuf 199to send data to libfuse. 200The union contains the following elements: 201.Bl -tag -width foobarmoocow 202.It Fa FD_stat 203A struct 204.Xr statvfs 3 205filled in by the FUSE client statfs for the FUSE VFS statfs code. 206.It Fa FD_attr 207Used by the getattr and setattr calls. 208.It Fa FD_io 209Contains all fields commonly used by FUSE client callbacks to 210provide information to FUSE vnops. 211It is used by access, readdir, release, releasedir, read, write, 212mkdir, and setattr. 213.El 214.Pp 215Setattr uses a struct fb_io and a struct stat. 216Settattr uses 217.Fa FD_stat 218and encapsulates a struct fb_io in 219.Fa F_databuf 220with 221.Fa fbtod . 222.Pp 223Fusebufs can be deleted with the 224.Fn fb_delete 225helper. 226.Sh SEE ALSO 227.Xr errno 2 , 228.Xr fuse_main 3 , 229.Xr queue 3 , 230.Xr statvfs 3 , 231.Xr fuse 4 , 232.Xr arc4random 9 , 233.Xr mbuf 9 234.Sh HISTORY 235The 236.Nm 237API first appeared in 238.Ox 5.4 . 239