]>
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 MK |
180 | .\" FIXME It looks like this is for implementing a stat(2) type of |
181 | .\" operation. There needs to be a sentence here describing what | |
182 | .\" this option does. | |
183 | ||
5963519c KF |
184 | .in +4n |
185 | .nf | |
186 | struct fuse_getattr_in { | |
7260a6e1 MK |
187 | uint32_t getattr_flags; |
188 | uint32_t dummy; | |
189 | uint64_t fh; /* Set only if | |
190 | (getattr_flags & FUSE_GETATTR_FH) | |
5963519c KF |
191 | }; |
192 | .fi | |
193 | .in | |
194 | ||
195 | As usual, the filesystem object operated on is indicated by | |
7260a6e1 | 196 | .IR header\->nodeid . |
5963519c KF |
197 | The daemon should compute the attributes |
198 | of this object and reply with the following message: | |
199 | .in +4n | |
7260a6e1 | 200 | |
5963519c KF |
201 | .nf |
202 | struct fuse_attr { | |
7260a6e1 MK |
203 | uint64_t ino; |
204 | uint64_t size; | |
205 | uint64_t blocks; | |
206 | uint64_t atime; | |
207 | uint64_t mtime; | |
208 | uint64_t ctime; | |
209 | uint32_t atimensec; | |
210 | uint32_t mtimensec; | |
211 | uint32_t ctimensec; | |
212 | uint32_t mode; | |
213 | uint32_t nlink; | |
214 | uint32_t uid; | |
215 | uint32_t gid; | |
216 | uint32_t rdev; | |
217 | uint32_t blksize; | |
218 | uint32_t padding; | |
5963519c | 219 | }; |
7260a6e1 | 220 | |
5963519c KF |
221 | struct fuse_attr_out { |
222 | /* Attribute cache duration (seconds + nanoseconds) */ | |
7260a6e1 MK |
223 | uint64_t attr_valid; |
224 | uint32_t attr_valid_nsec; | |
225 | uint32_t dummy; | |
5963519c KF |
226 | struct fuse_attr attr; |
227 | }; | |
228 | .fi | |
229 | .in | |
230 | ||
231 | The fields of | |
232 | .I struct fuse_attr | |
72e830cc MK |
233 | describe the attributes of the required file. |
234 | For the interpretation of these fields, see | |
7260a6e1 | 235 | .BR stat (2). |
5963519c | 236 | .TP |
ac3c78bd | 237 | .BR FUSE_ACCESS |
5963519c KF |
238 | |
239 | .in +4n | |
240 | .nf | |
241 | struct fuse_access_in { | |
7260a6e1 MK |
242 | uint32_t mask; |
243 | uint32_t padding; | |
5963519c KF |
244 | }; |
245 | .fi | |
246 | .in | |
247 | ||
248 | If the | |
249 | .I default_permissions | |
72e830cc MK |
250 | mount options is not used, this request may be used for permissions checking. |
251 | No reply data is expected, but errors may be indicated | |
5963519c KF |
252 | as usual in the reply header (in particular, access denied errors |
253 | may be indicated, by setting such field to | |
551e8425 | 254 | .\" FIXME What does "such field" mean? The 'error' field? |
7260a6e1 | 255 | .BR \-EACCES ). |
5963519c | 256 | .TP |
ac3c78bd | 257 | .BR FUSE_OPEN " and " FUSE_OPENDIR |
5963519c KF |
258 | .in +4n |
259 | .nf | |
260 | struct fuse_open_in { | |
7260a6e1 MK |
261 | uint32_t flags; /* The flags that were passed |
262 | to the open(2) */ | |
263 | uint32_t unused; | |
5963519c KF |
264 | }; |
265 | .fi | |
266 | .in | |
267 | ||
268 | The requested operation is to open the node indicated by | |
7260a6e1 MK |
269 | .IR header\->nodeid . |
270 | The exact semantics of what this means will depend on the | |
72e830cc MK |
271 | filesystem being implemented. |
272 | However, at the very least the | |
7260a6e1 | 273 | filesystem should validate that the requested |
5963519c | 274 | .I flags |
7260a6e1 MK |
275 | are valid for the indicated resource and then send a reply with the |
276 | following format: | |
5963519c KF |
277 | |
278 | .in +4n | |
279 | .nf | |
280 | ||
281 | struct fuse_open_out { | |
7260a6e1 MK |
282 | uint64_t fh; |
283 | uint32_t open_flags; | |
284 | uint32_t padding; | |
5963519c KF |
285 | }; |
286 | ||
287 | .fi | |
288 | .in | |
289 | ||
7260a6e1 | 290 | The |
5963519c | 291 | .I fh |
7260a6e1 MK |
292 | field is an opaque identifier that the kernel will use to refer |
293 | to this resource | |
294 | The | |
295 | .I open_flags | |
0bc65f95 MK |
296 | field is a bit mask of any number of the flags |
297 | that indicate properties of this file handle to the kernel: | |
298 | .RS 7 | |
299 | .TP 18 | |
300 | .BR FOPEN_DIRECT_IO | |
301 | Bypass page cache for this open file. | |
302 | .TP | |
303 | .BR FOPEN_KEEP_CACHE | |
304 | Don't invalidate the data cache on open. | |
305 | .TP | |
306 | .BR FOPEN_NONSEEKABLE | |
307 | The file is not seekable. | |
308 | .RE | |
5963519c | 309 | .TP |
ac3c78bd | 310 | .BR FUSE_READ " and " FUSE_READDIR |
5963519c KF |
311 | .in +4n |
312 | .nf | |
313 | ||
314 | struct fuse_read_in { | |
7260a6e1 MK |
315 | uint64_t fh; |
316 | uint64_t offset; | |
317 | uint32_t size; | |
318 | uint32_t read_flags; | |
319 | uint64_t lock_owner; | |
320 | uint32_t flags; | |
321 | uint32_t padding; | |
5963519c KF |
322 | }; |
323 | ||
324 | .fi | |
325 | .in | |
326 | ||
7260a6e1 | 327 | The requested action is to read up to |
5963519c KF |
328 | .I size |
329 | bytes of the file or directory, starting at | |
7260a6e1 | 330 | .IR offset . |
a2027c8f MK |
331 | .\" FIXME |
332 | .\" In the following, what are "out header" and "out structure"? | |
7260a6e1 | 333 | The bytes should be returned directly following the out header, |
5963519c | 334 | with no further special out structure. |
5963519c | 335 | .TP |
ac3c78bd | 336 | .BR FUSE_INTERRUPT |
5963519c KF |
337 | .in +4n |
338 | .nf | |
339 | struct fuse_interrupt_in { | |
7260a6e1 | 340 | uint64_t unique; |
5963519c KF |
341 | }; |
342 | .fi | |
343 | .in | |
344 | ||
345 | The requested action is to cancel the pending operation indicated by | |
7260a6e1 | 346 | .IR unique . |
72e830cc MK |
347 | This request requires no response. |
348 | However, receipt of this message does | |
349 | not by itself cancel the indicated operation. | |
7260a6e1 MK |
350 | The kernel will still expect a reply to said operation (e.g., an |
351 | .I EINTR | |
352 | error or a short read). | |
72e830cc | 353 | At most one |
5963519c | 354 | .B FUSE_INTERRUPT |
72e830cc MK |
355 | request will be issued for a given operation. |
356 | After issuing said operation, | |
7260a6e1 | 357 | the kernel will wait uninterruptibly for completion of the indicated request. |
5963519c | 358 | .TP |
ac3c78bd | 359 | .BR FUSE_LOOKUP |
5963519c KF |
360 | Directly following the header is a filename to be looked up in the directory |
361 | indicated by | |
7260a6e1 MK |
362 | .IR header\->nodeid . |
363 | The expected reply is of the form: | |
5963519c KF |
364 | |
365 | .in +4n | |
366 | .nf | |
367 | struct fuse_entry_out { | |
3280cb6b MK |
368 | uint64_t nodeid; /* Inode ID */ |
369 | uint64_t generation; /* Inode generation */ | |
7260a6e1 MK |
370 | uint64_t entry_valid; |
371 | uint64_t attr_valid; | |
372 | uint32_t entry_valid_nsec; | |
373 | uint32_t attr_valid_nsec; | |
5963519c KF |
374 | struct fuse_attr attr; |
375 | }; | |
376 | .fi | |
377 | .in | |
378 | ||
5d69a98a MK |
379 | The combination of |
380 | .I nodeid | |
381 | and | |
382 | .I generation | |
383 | must be unique for the filesystem's lifetime. | |
384 | ||
5963519c KF |
385 | The interpretation of timeouts and |
386 | .I attr | |
7260a6e1 MK |
387 | is as for |
388 | .BR FUSE_GETATTR . | |
5963519c | 389 | .TP |
ac3c78bd | 390 | .BR FUSE_FLUSH |
5963519c KF |
391 | .in +4n |
392 | .nf | |
393 | struct fuse_flush_in { | |
7260a6e1 MK |
394 | uint64_t fh; |
395 | uint32_t unused; | |
396 | uint32_t padding; | |
397 | uint64_t lock_owner; | |
5963519c KF |
398 | }; |
399 | .fi | |
400 | .in | |
401 | ||
402 | The requested action is to flush any pending changes to the indicated | |
72e830cc MK |
403 | file handle. |
404 | No reply data is expected. | |
405 | However, an empty reply message | |
5963519c | 406 | still needs to be issued once the flush operation is complete. |
5963519c | 407 | .TP |
ac3c78bd | 408 | .BR FUSE_RELEASE " and " FUSE_RELEASEDIR |
5963519c KF |
409 | .in +4n |
410 | .nf | |
411 | struct fuse_release_in { | |
7260a6e1 MK |
412 | uint64_t fh; |
413 | uint32_t flags; | |
414 | uint32_t release_flags; | |
415 | uint64_t lock_owner; | |
5963519c KF |
416 | }; |
417 | .fi | |
418 | .in | |
419 | ||
7260a6e1 | 420 | These are the converse of |
5963519c | 421 | .BR FUSE_OPEN |
7260a6e1 | 422 | and |
5963519c | 423 | .BR FUSE_OPENDIR |
72e830cc MK |
424 | respectively. |
425 | The daemon may now free any resources associated with the | |
5963519c KF |
426 | file handle |
427 | .I fh | |
72e830cc | 428 | as the kernel will no longer refer to it. |
7260a6e1 | 429 | There is no reply data associated with this request, |
72e830cc | 430 | but a reply still needs to be issued once the request has |
5963519c | 431 | been completely processed. |
5963519c | 432 | .TP |
ac3c78bd | 433 | .BR FUSE_STATFS |
5963519c | 434 | This operation implements |
7260a6e1 MK |
435 | .BR statfs (2) |
436 | for this filesystem. | |
72e830cc | 437 | There is no input data associated with this request. |
5963519c | 438 | The expected reply data has the following structure: |
7260a6e1 | 439 | |
5963519c KF |
440 | .in +4n |
441 | .nf | |
442 | struct fuse_kstatfs { | |
7260a6e1 MK |
443 | uint64_t blocks; |
444 | uint64_t bfree; | |
445 | uint64_t bavail; | |
446 | uint64_t files; | |
447 | uint64_t ffree; | |
448 | uint32_t bsize; | |
449 | uint32_t namelen; | |
450 | uint32_t frsize; | |
451 | uint32_t padding; | |
452 | uint32_t spare[6]; | |
5963519c | 453 | }; |
7260a6e1 | 454 | |
5963519c KF |
455 | struct fuse_statfs_out { |
456 | struct fuse_kstatfs st; | |
457 | }; | |
458 | .fi | |
459 | .in | |
460 | ||
461 | For the interpretation of these fields, see | |
7260a6e1 | 462 | .BR statfs (2). |
5963519c | 463 | .SH ERRORS |
7260a6e1 | 464 | .TP |
5963519c KF |
465 | .B EPERM |
466 | Returned from operations on a | |
467 | .I /dev/fuse | |
7260a6e1 MK |
468 | file descriptor that has not been mounted. |
469 | .TP | |
5963519c KF |
470 | .B EIO |
471 | Returned from | |
7260a6e1 | 472 | .BR read (2) |
5963519c KF |
473 | operations when the kernel's request is too large for the provided buffer. |
474 | ||
475 | .IR Note : | |
476 | There are various ways in which incorrect use of these interfaces can cause | |
477 | operations on the provided filesystem's files and directories to fail with | |
7260a6e1 MK |
478 | .BR EIO . |
479 | Among the possible incorrect uses are | |
480 | .IP * 3 | |
481 | changing | |
5963519c | 482 | .I mode & S_IFMT |
7260a6e1 MK |
483 | for an inode that has previously been reported to the kernel; or |
484 | .IP * | |
485 | giving replies to the kernel that are shorter than what the kernel expected. | |
486 | .TP | |
5963519c KF |
487 | .B EINVAL |
488 | Returned from | |
7260a6e1 | 489 | .BR write (2) |
72e830cc | 490 | if validation of the reply failed. |
53c028d1 | 491 | Not all mistakes in replies will be caught by this validation. |
72e830cc | 492 | However, basic mistakes, such as short replies or an incorrect |
5963519c | 493 | .I unique |
53c028d1 | 494 | value, are detected. |
7260a6e1 | 495 | .TP |
5963519c KF |
496 | .B E2BIG |
497 | Returned from | |
7260a6e1 | 498 | .BR read (2) |
5963519c | 499 | operations when the kernel's request is too large for the provided buffer |
7260a6e1 MK |
500 | and the request was |
501 | .BR FUSE_SETXATTR . | |
502 | .TP | |
5963519c | 503 | .B ENODEV |
996925d5 MK |
504 | Returned from |
505 | .BR read (2) | |
506 | and | |
507 | .BR write (2) | |
508 | if the FUSE filesystem was unmounted. | |
abf2a19d MK |
509 | .SH CONFORMING TO |
510 | The FUSE filesystem is Linux-specific. | |
2949f098 MK |
511 | .SH NOTES |
512 | The following messages are not yet documented in this manual page: | |
513 | ||
514 | .in +8n | |
515 | .nf | |
516 | .BR FUSE_BATCH_FORGET | |
517 | .BR FUSE_BMAP | |
518 | .BR FUSE_CREATE | |
519 | .BR FUSE_DESTROY | |
520 | .BR FUSE_FALLOCATE | |
521 | .BR FUSE_FORGET | |
522 | .BR FUSE_FSYNC | |
523 | .BR FUSE_FSYNCDIR | |
524 | .BR FUSE_GETLK | |
525 | .BR FUSE_GETXATTR | |
526 | .BR FUSE_IOCTL | |
527 | .BR FUSE_LINK | |
528 | .BR FUSE_LISTXATTR | |
529 | .BR FUSE_LSEEK | |
530 | .BR FUSE_MKDIR | |
531 | .BR FUSE_MKNOD | |
532 | .BR FUSE_NOTIFY_REPLY | |
533 | .BR FUSE_POLL | |
534 | .BR FUSE_READDIRPLUS | |
535 | .BR FUSE_READLINK | |
536 | .BR FUSE_REMOVEXATTR | |
537 | .BR FUSE_RENAME | |
538 | .BR FUSE_RENAME2 | |
539 | .BR FUSE_RMDIR | |
540 | .BR FUSE_SETATTR | |
541 | .BR FUSE_SETLK | |
542 | .BR FUSE_SETLKW | |
543 | .BR FUSE_SYMLINK | |
544 | .BR FUSE_UNLINK | |
545 | .BR FUSE_WRITE | |
546 | .fi | |
547 | .in | |
548 | .\" It looks like the following are undocumented so far. It probably would | |
549 | .\" be kind to list these in the man page | |
70992218 MK |
550 | .SH SEE ALSO |
551 | .BR fusermount (1), | |
552 | .BR mount.fuse (8) |