github.com/hanwen/go-fuse@v1.0.0/fuse/api.go (about) 1 // Copyright 2016 the Go-FUSE Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style 3 // license that can be found in the LICENSE file. 4 5 // Package fuse provides APIs to implement filesystems in 6 // userspace in terms of raw FUSE protocol. 7 // 8 // A filesystem is implemented by implementing its server that provides a 9 // RawFileSystem interface. Typically the server embeds 10 // NewDefaultRawFileSystem() and implements only subset of filesystem methods: 11 // 12 // type MyFS struct { 13 // fuse.RawFileSystem 14 // ... 15 // } 16 // 17 // func NewMyFS() *MyFS { 18 // return &MyFS{ 19 // RawFileSystem: fuse.NewDefaultRawFileSystem(), 20 // ... 21 // } 22 // } 23 // 24 // // Mkdir implements "mkdir" request handler. 25 // // 26 // // For other requests - not explicitly implemented by MyFS - ENOSYS 27 // // will be typically returned to client. 28 // func (fs *MyFS) Mkdir(...) { 29 // ... 30 // } 31 // 32 // Then the filesystem can be mounted and served to a client (typically OS 33 // kernel) by creating Server: 34 // 35 // fs := NewMyFS() // implements RawFileSystem 36 // fssrv, err := fuse.NewServer(fs, mountpoint, &fuse.MountOptions{...}) 37 // if err != nil { 38 // ... 39 // } 40 // 41 // and letting the server do its work: 42 // 43 // // either synchronously - .Serve() blocks until the filesystem is unmounted. 44 // fssrv.Serve() 45 // 46 // // or in the background - .Serve() is spawned in another goroutine, but 47 // // before interacting with fssrv from current context we have to wait 48 // // until the filesystem mounting is complete. 49 // go fssrv.Serve() 50 // err = fssrv.WaitMount() 51 // if err != nil { 52 // ... 53 // } 54 // 55 // The server will serve clients by dispatching their requests to the 56 // filesystem implementation and conveying responses back. For example "mkdir" 57 // FUSE request dispatches to call 58 // 59 // fs.Mkdir(*MkdirIn, ..., *EntryOut) 60 // 61 // "stat" to call 62 // 63 // fs.GetAttr(*GetAttrIn, *AttrOut) 64 // 65 // etc. Please refer to RawFileSystem documentation for details. 66 // 67 // Typically, each call of the API happens in its own 68 // goroutine, so take care to make the file system thread-safe. 69 // 70 // 71 // Higher level interfaces 72 // 73 // As said above this packages provides way to implement filesystems in terms of 74 // raw FUSE protocol. Additionally packages nodefs and pathfs provide ways to 75 // implement filesystem at higher levels: 76 // 77 // Package github.com/hanwen/go-fuse/fuse/nodefs provides way to implement 78 // filesystems in terms of inodes. This resembles kernel's idea of what a 79 // filesystem looks like. 80 // 81 // Package github.com/hanwen/go-fuse/fuse/pathfs provides way to implement 82 // filesystems in terms of path names. Working with path names is somewhat 83 // easier compared to inodes, however renames can be racy. Do not use pathfs if 84 // you care about correctness. 85 package fuse 86 87 // Types for users to implement. 88 89 // The result of Read is an array of bytes, but for performance 90 // reasons, we can also return data as a file-descriptor/offset/size 91 // tuple. If the backing store for a file is another filesystem, this 92 // reduces the amount of copying between the kernel and the FUSE 93 // server. The ReadResult interface captures both cases. 94 type ReadResult interface { 95 // Returns the raw bytes for the read, possibly using the 96 // passed buffer. The buffer should be larger than the return 97 // value from Size. 98 Bytes(buf []byte) ([]byte, Status) 99 100 // Size returns how many bytes this return value takes at most. 101 Size() int 102 103 // Done() is called after sending the data to the kernel. 104 Done() 105 } 106 107 type MountOptions struct { 108 AllowOther bool 109 110 // Options are passed as -o string to fusermount. 111 Options []string 112 113 // Default is _DEFAULT_BACKGROUND_TASKS, 12. This numbers 114 // controls the allowed number of requests that relate to 115 // async I/O. Concurrency for synchronous I/O is not limited. 116 MaxBackground int 117 118 // Write size to use. If 0, use default. This number is 119 // capped at the kernel maximum. 120 MaxWrite int 121 122 // Max read ahead to use. If 0, use default. This number is 123 // capped at the kernel maximum. 124 MaxReadAhead int 125 126 // If IgnoreSecurityLabels is set, all security related xattr 127 // requests will return NO_DATA without passing through the 128 // user defined filesystem. You should only set this if you 129 // file system implements extended attributes, and you are not 130 // interested in security labels. 131 IgnoreSecurityLabels bool // ignoring labels should be provided as a fusermount mount option. 132 133 // If given, use this buffer pool instead of the global one. 134 Buffers BufferPool 135 136 // If RememberInodes is set, we will never forget inodes. 137 // This may be useful for NFS. 138 RememberInodes bool 139 140 // Values shown in "df -T" and friends 141 // First column, "Filesystem" 142 FsName string 143 144 // Second column, "Type", will be shown as "fuse." + Name 145 Name string 146 147 // If set, wrap the file system in a single-threaded locking wrapper. 148 SingleThreaded bool 149 150 // If set, return ENOSYS for Getxattr calls, so the kernel does not issue any 151 // Xattr operations at all. 152 DisableXAttrs bool 153 154 // If set, print debugging information. 155 Debug bool 156 157 // If set, ask kernel to forward file locks to FUSE. If using, 158 // you must implement the GetLk/SetLk/SetLkw methods. 159 EnableLocks bool 160 } 161 162 // RawFileSystem is an interface close to the FUSE wire protocol. 163 // 164 // Unless you really know what you are doing, you should not implement 165 // this, but rather the nodefs.Node or pathfs.FileSystem interfaces; the 166 // details of getting interactions with open files, renames, and threading 167 // right etc. are somewhat tricky and not very interesting. 168 // 169 // Each FUSE request results in a corresponding method called by Server. 170 // Several calls may be made simultaneously, because the server typically calls 171 // each method in separate goroutine. 172 // 173 // A null implementation is provided by NewDefaultRawFileSystem. 174 type RawFileSystem interface { 175 String() string 176 177 // If called, provide debug output through the log package. 178 SetDebug(debug bool) 179 180 // Lookup is called by the kernel when the VFS wants to know 181 // about a file inside a directory. Many lookup calls can 182 // occur in parallel, but only one call happens for each (dir, 183 // name) pair. 184 Lookup(header *InHeader, name string, out *EntryOut) (status Status) 185 186 // Forget is called when the kernel discards entries from its 187 // dentry cache. This happens on unmount, and when the kernel 188 // is short on memory. Since it is not guaranteed to occur at 189 // any moment, and since there is no return value, Forget 190 // should not do I/O, as there is no channel to report back 191 // I/O errors. 192 Forget(nodeid, nlookup uint64) 193 194 // Attributes. 195 GetAttr(input *GetAttrIn, out *AttrOut) (code Status) 196 SetAttr(input *SetAttrIn, out *AttrOut) (code Status) 197 198 // Modifying structure. 199 Mknod(input *MknodIn, name string, out *EntryOut) (code Status) 200 Mkdir(input *MkdirIn, name string, out *EntryOut) (code Status) 201 Unlink(header *InHeader, name string) (code Status) 202 Rmdir(header *InHeader, name string) (code Status) 203 Rename(input *RenameIn, oldName string, newName string) (code Status) 204 Link(input *LinkIn, filename string, out *EntryOut) (code Status) 205 206 Symlink(header *InHeader, pointedTo string, linkName string, out *EntryOut) (code Status) 207 Readlink(header *InHeader) (out []byte, code Status) 208 Access(input *AccessIn) (code Status) 209 210 // Extended attributes. 211 GetXAttrSize(header *InHeader, attr string) (sz int, code Status) 212 GetXAttrData(header *InHeader, attr string) (data []byte, code Status) 213 ListXAttr(header *InHeader) (attributes []byte, code Status) 214 SetXAttr(input *SetXAttrIn, attr string, data []byte) Status 215 RemoveXAttr(header *InHeader, attr string) (code Status) 216 217 // File handling. 218 Create(input *CreateIn, name string, out *CreateOut) (code Status) 219 Open(input *OpenIn, out *OpenOut) (status Status) 220 Read(input *ReadIn, buf []byte) (ReadResult, Status) 221 222 // File locking 223 GetLk(input *LkIn, out *LkOut) (code Status) 224 SetLk(input *LkIn) (code Status) 225 SetLkw(input *LkIn) (code Status) 226 227 Release(input *ReleaseIn) 228 Write(input *WriteIn, data []byte) (written uint32, code Status) 229 Flush(input *FlushIn) Status 230 Fsync(input *FsyncIn) (code Status) 231 Fallocate(input *FallocateIn) (code Status) 232 233 // Directory handling 234 OpenDir(input *OpenIn, out *OpenOut) (status Status) 235 ReadDir(input *ReadIn, out *DirEntryList) Status 236 ReadDirPlus(input *ReadIn, out *DirEntryList) Status 237 ReleaseDir(input *ReleaseIn) 238 FsyncDir(input *FsyncIn) (code Status) 239 240 // 241 StatFs(input *InHeader, out *StatfsOut) (code Status) 242 243 // This is called on processing the first request. The 244 // filesystem implementation can use the server argument to 245 // talk back to the kernel (through notify methods). 246 Init(*Server) 247 }