]>
Commit | Line | Data |
---|---|---|
5963519c KF |
1 | .\" Copyright (c) 2016 Julia Computing Inc, Keno Fischer |
2 | .\" Description based on include/uapi/fuse.h and code in fs/fuse | |
3 | .\" | |
4 | .\" %%%LICENSE_START(VERBATIM) | |
5 | .\" Permission is granted to make and distribute verbatim copies of this | |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
13 | .\" | |
14 | .\" Since the Linux kernel and libraries are constantly changing, this | |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
17 | .\" the use of the information contained herein. The author(s) may not | |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
21 | .\" | |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
5963519c KF |
24 | .\" %%%LICENSE_END |
25 | .\" | |
26 | .TH FUSE 4 2016-12-10 "Linux" "Linux Programmer's Manual" | |
27 | .SH NAME | |
28 | /dev/fuse \- Filesystem in Userspace (FUSE) device | |
29 | .SH SYNOPSIS | |
30 | .nf | |
31 | .B #include <linux/fuse.h> | |
32 | .nf | |
33 | .SH DESCRIPTION | |
34 | ||
35 | This device is the primary interface between the FUSE filesystem driver | |
7260a6e1 | 36 | and a user-space process wishing to provide the filesystem (referred to |
5963519c | 37 | in the rest of this manual page as the |
7260a6e1 | 38 | .IR "filesystem daemon" ). |
5963519c | 39 | This manual page is intended for those |
72e830cc MK |
40 | interested in understanding the kernel interface itself. |
41 | Those implementing a FUSE filesystem may wish to make use of | |
7260a6e1 MK |
42 | a user-space library such as |
43 | .I libfuse | |
44 | that abstracts away the low-level interface. | |
5963519c KF |
45 | |
46 | At its core, FUSE is a simple client-server protocol, in which the Linux | |
72e830cc | 47 | kernel is the client and the daemon is the server. |
7260a6e1 | 48 | After obtaining a file descriptor for this device, the daemon may |
5963519c KF |
49 | .BR read (2) |
50 | requests from that file descriptor and is expected to | |
51 | .BR write (2) | |
7260a6e1 MK |
52 | back its replies. |
53 | It is important to note that a file descriptor is | |
54 | associated with a unique FUSE filesystem. | |
72e830cc MK |
55 | In particular, opening a second copy of this device, |
56 | will not allow access to resources created | |
5963519c | 57 | through the first file descriptor (and vice versa). |
7260a6e1 | 58 | .\" |
5963519c KF |
59 | .SS The basic protocol |
60 | Every message that is read by the daemon begins with a header described by | |
7260a6e1 | 61 | the following structure: |
5963519c KF |
62 | |
63 | .in +4n | |
64 | .nf | |
65 | struct fuse_in_header { | |
7260a6e1 MK |
66 | uint32_t len; /* Total length of the data, |
67 | including this header */ | |
68 | uint32_t opcode; /* The kind of operation (see below) */ | |
69 | uint64_t unique; /* A unique identifier for this request */ | |
70 | uint64_t nodeid; /* ID of the filesystem object | |
71 | being operated on */ | |
72 | uint32_t uid; /* UID of the requesting process */ | |
73 | uint32_t gid; /* GID of the requesting process */ | |
74 | uint32_t pid; /* PID of the requesting process */ | |
75 | uint32_t padding; | |
5963519c KF |
76 | }; |
77 | .fi | |
78 | .in | |
79 | ||
7260a6e1 MK |
80 | The header is followed by a variable-length data portion |
81 | (which may be empty) specific to the requested operation | |
5963519c | 82 | (the requested operation is indicated by |
7260a6e1 | 83 | .IR opcode ). |
5963519c | 84 | |
72e830cc | 85 | The daemon should then process the request and if applicable send |
7260a6e1 | 86 | a reply (almost all operations require a reply; if they do not, |
72e830cc | 87 | this is documented below), by performing a |
7260a6e1 | 88 | .BR write (2) |
72e830cc MK |
89 | to the file descriptor. |
90 | All replies must start with the following header: | |
5963519c KF |
91 | |
92 | .in +4n | |
93 | .nf | |
7260a6e1 MK |
94 | struct fuse_out_header { |
95 | uint32_t len; /* Total length of data written to | |
96 | the file descriptor */ | |
97 | int32_t error; /* Any error that occurred (0 if none) */ | |
98 | uint64_t unique; /* The value from the | |
99 | corresponding request */ | |
100 | }; | |
5963519c KF |
101 | .fi |
102 | .in | |
103 | ||
7260a6e1 MK |
104 | This header is also followed by (potentially empty) variable-sized |
105 | data depending on the executed request. | |
106 | However, if the reply is an error reply (i.e., | |
107 | .I error | |
108 | is set), | |
5963519c | 109 | then no further payload data should be sent, independent of the request. |
7260a6e1 | 110 | .\" |
5963519c | 111 | .SS Exchanged messages |
72e830cc MK |
112 | This section should contain documentation for each of the messages |
113 | in the protocol. | |
114 | This manual page is currently incomplete, | |
115 | so not all messages are documented. | |
116 | For each message, first the struct sent by the kernel is given, | |
117 | followed by a description of the semantics of the message. | |
5963519c | 118 | .TP |
ac3c78bd | 119 | .BR FUSE_INIT |
5963519c KF |
120 | |
121 | .in +4n | |
122 | .nf | |
123 | struct fuse_init_in { | |
7260a6e1 MK |
124 | uint32_t major; |
125 | uint32_t minor; | |
126 | uint32_t max_readahead; /* Since protocol v7.6 */ | |
127 | uint32_t flags; /* Since protocol v7.6 */ | |
5963519c KF |
128 | }; |
129 | .fi | |
130 | .in | |
131 | ||
72e830cc | 132 | This is the first request sent by the kernel to the daemon. |
7260a6e1 | 133 | It is used to negotiate the protocol version and other filesystem parameters. |
72e830cc | 134 | Note that the protocol version may affect the layout of any structure |
83b87d65 | 135 | in the protocol (including this structure). |
72e830cc MK |
136 | The daemon must thus remember the negotiated version |
137 | and flags for each session. | |
138 | As of the writing of this man page, | |
139 | the highest supported kernel protocol version is | |
7260a6e1 | 140 | .IR 7.26 . |
5963519c KF |
141 | |
142 | Users should be aware that the descriptions in this manual page | |
143 | may be incomplete or incorrect for older or more recent protocol versions. | |
144 | ||
7260a6e1 MK |
145 | The reply for this request has the following format: |
146 | ||
5963519c KF |
147 | .in +4n |
148 | .nf | |
149 | struct fuse_init_out { | |
7260a6e1 MK |
150 | uint32_t major; |
151 | uint32_t minor; | |
152 | uint32_t max_readahead; /* Since v7.6 */ | |
153 | uint32_t flags; /* Since v7.6; some flags bits | |
154 | were introduced later */ | |
155 | uint16_t max_background; /* Since v7.13 */ | |
156 | uint16_t congestion_threshold; /* Since v7.13 */ | |
157 | uint32_t max_write; /* Since v7.5 */ | |
158 | uint32_t time_gran; /* Since v7.6 */ | |
159 | uint32_t unused[9]; | |
5963519c KF |
160 | }; |
161 | .fi | |
162 | .in | |
163 | ||
7260a6e1 | 164 | If the major version supported by the kernel is larger than that supported |
5963519c KF |
165 | by the daemon, the reply shall consist of only |
166 | .I uint32_t major | |
72e830cc MK |
167 | (following the usual header), |
168 | indicating the largest major version supported by the daemon. | |
169 | The kernel will then issue a new | |
7260a6e1 | 170 | .B FUSE_INIT |
72e830cc MK |
171 | request conforming to the older version. |
172 | In the reverse case, the daemon should | |
5963519c KF |
173 | quietly fall back to the kernel's major version. |
174 | ||
72e830cc MK |
175 | The negotiated minor version is considered to be the minimum |
176 | of the minor versions provided by the daemon and the kernel and | |
177 | both parties should use the protocol corresponding to said minor version. | |
5963519c | 178 | .TP |
ac3c78bd | 179 | .BR FUSE_GETATTR |
f8fe67a1 | 180 | |
5963519c KF |
181 | .in +4n |
182 | .nf | |
183 | struct fuse_getattr_in { | |
7260a6e1 MK |
184 | uint32_t getattr_flags; |
185 | uint32_t dummy; | |
186 | uint64_t fh; /* Set only if | |
187 | (getattr_flags & FUSE_GETATTR_FH) | |
5963519c KF |
188 | }; |
189 | .fi | |
190 | .in | |
191 | ||
4085d7ab KF |
192 | The requested operation is to compute the attributes to be returned |
193 | by | |
194 | .BR stat(2) | |
195 | and similar operations for the given file system object. | |
196 | The object for which the attributes should be computed is indicated | |
197 | either by | |
198 | .IR header\->nodeid | |
199 | or, if the | |
200 | .IR FUSE_GETATTR_FH | |
201 | flag is set, by the file handle | |
202 | .IR fh. | |
203 | The latter case of operation is analogous to | |
204 | .BR fstat(2). | |
7260a6e1 | 205 | |
4085d7ab KF |
206 | For performance reasons, these attributes may be cached in the kernel for |
207 | a specified duration of time. While the cache timeout has not been exceeded, | |
208 | the attributes will be served from the cache and will not cause additional | |
209 | .B FUSE_GETATTR | |
210 | requests. | |
7260a6e1 | 211 | |
4085d7ab KF |
212 | The computed attributes and the requested |
213 | cache timeout should then be returned in the following structure: | |
214 | ||
215 | .in +4n | |
216 | .nf | |
5963519c KF |
217 | struct fuse_attr_out { |
218 | /* Attribute cache duration (seconds + nanoseconds) */ | |
7260a6e1 MK |
219 | uint64_t attr_valid; |
220 | uint32_t attr_valid_nsec; | |
221 | uint32_t dummy; | |
4085d7ab KF |
222 | struct fuse_attr { |
223 | uint64_t ino; | |
224 | uint64_t size; | |
225 | uint64_t blocks; | |
226 | uint64_t atime; | |
227 | uint64_t mtime; | |
228 | uint64_t ctime; | |
229 | uint32_t atimensec; | |
230 | uint32_t mtimensec; | |
231 | uint32_t ctimensec; | |
232 | uint32_t mode; | |
233 | uint32_t nlink; | |
234 | uint32_t uid; | |
235 | uint32_t gid; | |
236 | uint32_t rdev; | |
237 | uint32_t blksize; | |
238 | uint32_t padding; | |
239 | } attr; | |
5963519c KF |
240 | }; |
241 | .fi | |
242 | .in | |
243 | ||
5963519c | 244 | .TP |
ac3c78bd | 245 | .BR FUSE_ACCESS |
5963519c KF |
246 | |
247 | .in +4n | |
248 | .nf | |
249 | struct fuse_access_in { | |
7260a6e1 MK |
250 | uint32_t mask; |
251 | uint32_t padding; | |
5963519c KF |
252 | }; |
253 | .fi | |
254 | .in | |
255 | ||
256 | If the | |
257 | .I default_permissions | |
72e830cc MK |
258 | mount options is not used, this request may be used for permissions checking. |
259 | No reply data is expected, but errors may be indicated | |
4085d7ab KF |
260 | as usual by setting the |
261 | .I error | |
262 | field in the reply header (in particular, access denied errors | |
263 | may be indicated by returning | |
7260a6e1 | 264 | .BR \-EACCES ). |
5963519c | 265 | .TP |
ac3c78bd | 266 | .BR FUSE_OPEN " and " FUSE_OPENDIR |
5963519c KF |
267 | .in +4n |
268 | .nf | |
269 | struct fuse_open_in { | |
7260a6e1 MK |
270 | uint32_t flags; /* The flags that were passed |
271 | to the open(2) */ | |
272 | uint32_t unused; | |
5963519c KF |
273 | }; |
274 | .fi | |
275 | .in | |
276 | ||
277 | The requested operation is to open the node indicated by | |
7260a6e1 MK |
278 | .IR header\->nodeid . |
279 | The exact semantics of what this means will depend on the | |
72e830cc MK |
280 | filesystem being implemented. |
281 | However, at the very least the | |
7260a6e1 | 282 | filesystem should validate that the requested |
5963519c | 283 | .I flags |
7260a6e1 MK |
284 | are valid for the indicated resource and then send a reply with the |
285 | following format: | |
5963519c KF |
286 | |
287 | .in +4n | |
288 | .nf | |
289 | ||
290 | struct fuse_open_out { | |
7260a6e1 MK |
291 | uint64_t fh; |
292 | uint32_t open_flags; | |
293 | uint32_t padding; | |
5963519c KF |
294 | }; |
295 | ||
296 | .fi | |
297 | .in | |
298 | ||
7260a6e1 | 299 | The |
5963519c | 300 | .I fh |
7260a6e1 MK |
301 | field is an opaque identifier that the kernel will use to refer |
302 | to this resource | |
303 | The | |
304 | .I open_flags | |
0bc65f95 MK |
305 | field is a bit mask of any number of the flags |
306 | that indicate properties of this file handle to the kernel: | |
307 | .RS 7 | |
308 | .TP 18 | |
309 | .BR FOPEN_DIRECT_IO | |
310 | Bypass page cache for this open file. | |
311 | .TP | |
312 | .BR FOPEN_KEEP_CACHE | |
313 | Don't invalidate the data cache on open. | |
314 | .TP | |
315 | .BR FOPEN_NONSEEKABLE | |
316 | The file is not seekable. | |
317 | .RE | |
5963519c | 318 | .TP |
ac3c78bd | 319 | .BR FUSE_READ " and " FUSE_READDIR |
5963519c KF |
320 | .in +4n |
321 | .nf | |
322 | ||
323 | struct fuse_read_in { | |
7260a6e1 MK |
324 | uint64_t fh; |
325 | uint64_t offset; | |
326 | uint32_t size; | |
327 | uint32_t read_flags; | |
328 | uint64_t lock_owner; | |
329 | uint32_t flags; | |
330 | uint32_t padding; | |
5963519c KF |
331 | }; |
332 | ||
333 | .fi | |
334 | .in | |
335 | ||
7260a6e1 | 336 | The requested action is to read up to |
5963519c KF |
337 | .I size |
338 | bytes of the file or directory, starting at | |
7260a6e1 | 339 | .IR offset . |
4085d7ab | 340 | The bytes should be returned directly following the usual reply header. |
5963519c | 341 | .TP |
ac3c78bd | 342 | .BR FUSE_INTERRUPT |
5963519c KF |
343 | .in +4n |
344 | .nf | |
345 | struct fuse_interrupt_in { | |
7260a6e1 | 346 | uint64_t unique; |
5963519c KF |
347 | }; |
348 | .fi | |
349 | .in | |
350 | ||
351 | The requested action is to cancel the pending operation indicated by | |
7260a6e1 | 352 | .IR unique . |
72e830cc MK |
353 | This request requires no response. |
354 | However, receipt of this message does | |
355 | not by itself cancel the indicated operation. | |
7260a6e1 MK |
356 | The kernel will still expect a reply to said operation (e.g., an |
357 | .I EINTR | |
358 | error or a short read). | |
72e830cc | 359 | At most one |
5963519c | 360 | .B FUSE_INTERRUPT |
72e830cc MK |
361 | request will be issued for a given operation. |
362 | After issuing said operation, | |
7260a6e1 | 363 | the kernel will wait uninterruptibly for completion of the indicated request. |
5963519c | 364 | .TP |
ac3c78bd | 365 | .BR FUSE_LOOKUP |
5963519c KF |
366 | Directly following the header is a filename to be looked up in the directory |
367 | indicated by | |
7260a6e1 MK |
368 | .IR header\->nodeid . |
369 | The expected reply is of the form: | |
5963519c KF |
370 | |
371 | .in +4n | |
372 | .nf | |
373 | struct fuse_entry_out { | |
3280cb6b MK |
374 | uint64_t nodeid; /* Inode ID */ |
375 | uint64_t generation; /* Inode generation */ | |
7260a6e1 MK |
376 | uint64_t entry_valid; |
377 | uint64_t attr_valid; | |
378 | uint32_t entry_valid_nsec; | |
379 | uint32_t attr_valid_nsec; | |
5963519c KF |
380 | struct fuse_attr attr; |
381 | }; | |
382 | .fi | |
383 | .in | |
384 | ||
5d69a98a MK |
385 | The combination of |
386 | .I nodeid | |
387 | and | |
388 | .I generation | |
389 | must be unique for the filesystem's lifetime. | |
390 | ||
5963519c KF |
391 | The interpretation of timeouts and |
392 | .I attr | |
7260a6e1 MK |
393 | is as for |
394 | .BR FUSE_GETATTR . | |
5963519c | 395 | .TP |
ac3c78bd | 396 | .BR FUSE_FLUSH |
5963519c KF |
397 | .in +4n |
398 | .nf | |
399 | struct fuse_flush_in { | |
7260a6e1 MK |
400 | uint64_t fh; |
401 | uint32_t unused; | |
402 | uint32_t padding; | |
403 | uint64_t lock_owner; | |
5963519c KF |
404 | }; |
405 | .fi | |
406 | .in | |
407 | ||
408 | The requested action is to flush any pending changes to the indicated | |
72e830cc MK |
409 | file handle. |
410 | No reply data is expected. | |
411 | However, an empty reply message | |
5963519c | 412 | still needs to be issued once the flush operation is complete. |
5963519c | 413 | .TP |
ac3c78bd | 414 | .BR FUSE_RELEASE " and " FUSE_RELEASEDIR |
5963519c KF |
415 | .in +4n |
416 | .nf | |
417 | struct fuse_release_in { | |
7260a6e1 MK |
418 | uint64_t fh; |
419 | uint32_t flags; | |
420 | uint32_t release_flags; | |
421 | uint64_t lock_owner; | |
5963519c KF |
422 | }; |
423 | .fi | |
424 | .in | |
425 | ||
7260a6e1 | 426 | These are the converse of |
5963519c | 427 | .BR FUSE_OPEN |
7260a6e1 | 428 | and |
5963519c | 429 | .BR FUSE_OPENDIR |
72e830cc MK |
430 | respectively. |
431 | The daemon may now free any resources associated with the | |
5963519c KF |
432 | file handle |
433 | .I fh | |
72e830cc | 434 | as the kernel will no longer refer to it. |
7260a6e1 | 435 | There is no reply data associated with this request, |
72e830cc | 436 | but a reply still needs to be issued once the request has |
5963519c | 437 | been completely processed. |
5963519c | 438 | .TP |
ac3c78bd | 439 | .BR FUSE_STATFS |
5963519c | 440 | This operation implements |
7260a6e1 MK |
441 | .BR statfs (2) |
442 | for this filesystem. | |
72e830cc | 443 | There is no input data associated with this request. |
5963519c | 444 | The expected reply data has the following structure: |
7260a6e1 | 445 | |
5963519c KF |
446 | .in +4n |
447 | .nf | |
448 | struct fuse_kstatfs { | |
7260a6e1 MK |
449 | uint64_t blocks; |
450 | uint64_t bfree; | |
451 | uint64_t bavail; | |
452 | uint64_t files; | |
453 | uint64_t ffree; | |
454 | uint32_t bsize; | |
455 | uint32_t namelen; | |
456 | uint32_t frsize; | |
457 | uint32_t padding; | |
458 | uint32_t spare[6]; | |
5963519c | 459 | }; |
7260a6e1 | 460 | |
5963519c KF |
461 | struct fuse_statfs_out { |
462 | struct fuse_kstatfs st; | |
463 | }; | |
464 | .fi | |
465 | .in | |
466 | ||
467 | For the interpretation of these fields, see | |
7260a6e1 | 468 | .BR statfs (2). |
5963519c | 469 | .SH ERRORS |
7260a6e1 | 470 | .TP |
5963519c KF |
471 | .B EPERM |
472 | Returned from operations on a | |
473 | .I /dev/fuse | |
7260a6e1 MK |
474 | file descriptor that has not been mounted. |
475 | .TP | |
5963519c KF |
476 | .B EIO |
477 | Returned from | |
7260a6e1 | 478 | .BR read (2) |
5963519c KF |
479 | operations when the kernel's request is too large for the provided buffer. |
480 | ||
481 | .IR Note : | |
482 | There are various ways in which incorrect use of these interfaces can cause | |
483 | operations on the provided filesystem's files and directories to fail with | |
7260a6e1 MK |
484 | .BR EIO . |
485 | Among the possible incorrect uses are | |
486 | .IP * 3 | |
487 | changing | |
5963519c | 488 | .I mode & S_IFMT |
7260a6e1 MK |
489 | for an inode that has previously been reported to the kernel; or |
490 | .IP * | |
491 | giving replies to the kernel that are shorter than what the kernel expected. | |
492 | .TP | |
5963519c KF |
493 | .B EINVAL |
494 | Returned from | |
7260a6e1 | 495 | .BR write (2) |
72e830cc | 496 | if validation of the reply failed. |
53c028d1 | 497 | Not all mistakes in replies will be caught by this validation. |
72e830cc | 498 | However, basic mistakes, such as short replies or an incorrect |
5963519c | 499 | .I unique |
53c028d1 | 500 | value, are detected. |
7260a6e1 | 501 | .TP |
5963519c KF |
502 | .B E2BIG |
503 | Returned from | |
7260a6e1 | 504 | .BR read (2) |
5963519c | 505 | operations when the kernel's request is too large for the provided buffer |
7260a6e1 MK |
506 | and the request was |
507 | .BR FUSE_SETXATTR . | |
508 | .TP | |
5963519c | 509 | .B ENODEV |
996925d5 MK |
510 | Returned from |
511 | .BR read (2) | |
512 | and | |
513 | .BR write (2) | |
514 | if the FUSE filesystem was unmounted. | |
abf2a19d MK |
515 | .SH CONFORMING TO |
516 | The FUSE filesystem is Linux-specific. | |
2949f098 MK |
517 | .SH NOTES |
518 | The following messages are not yet documented in this manual page: | |
519 | ||
520 | .in +8n | |
521 | .nf | |
522 | .BR FUSE_BATCH_FORGET | |
523 | .BR FUSE_BMAP | |
524 | .BR FUSE_CREATE | |
525 | .BR FUSE_DESTROY | |
526 | .BR FUSE_FALLOCATE | |
527 | .BR FUSE_FORGET | |
528 | .BR FUSE_FSYNC | |
529 | .BR FUSE_FSYNCDIR | |
530 | .BR FUSE_GETLK | |
531 | .BR FUSE_GETXATTR | |
532 | .BR FUSE_IOCTL | |
533 | .BR FUSE_LINK | |
534 | .BR FUSE_LISTXATTR | |
535 | .BR FUSE_LSEEK | |
536 | .BR FUSE_MKDIR | |
537 | .BR FUSE_MKNOD | |
538 | .BR FUSE_NOTIFY_REPLY | |
539 | .BR FUSE_POLL | |
540 | .BR FUSE_READDIRPLUS | |
541 | .BR FUSE_READLINK | |
542 | .BR FUSE_REMOVEXATTR | |
543 | .BR FUSE_RENAME | |
544 | .BR FUSE_RENAME2 | |
545 | .BR FUSE_RMDIR | |
546 | .BR FUSE_SETATTR | |
547 | .BR FUSE_SETLK | |
548 | .BR FUSE_SETLKW | |
549 | .BR FUSE_SYMLINK | |
550 | .BR FUSE_UNLINK | |
551 | .BR FUSE_WRITE | |
552 | .fi | |
553 | .in | |
554 | .\" It looks like the following are undocumented so far. It probably would | |
555 | .\" be kind to list these in the man page | |
70992218 MK |
556 | .SH SEE ALSO |
557 | .BR fusermount (1), | |
558 | .BR mount.fuse (8) |