]>
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 KF |
118 | .TP |
119 | .BR FUSE_INIT " ( 25 )" | |
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 MK |
134 | Note that the protocol version may affect the layout of any structure |
135 | in the protocol (including this one). | |
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 KF |
178 | .TP |
179 | .BR FUSE_GETATTR " ( 3 )" | |
180 | .in +4n | |
181 | .nf | |
182 | struct fuse_getattr_in { | |
7260a6e1 MK |
183 | uint32_t getattr_flags; |
184 | uint32_t dummy; | |
185 | uint64_t fh; /* Set only if | |
186 | (getattr_flags & FUSE_GETATTR_FH) | |
5963519c KF |
187 | }; |
188 | .fi | |
189 | .in | |
190 | ||
191 | As usual, the filesystem object operated on is indicated by | |
7260a6e1 | 192 | .IR header\->nodeid . |
5963519c KF |
193 | The daemon should compute the attributes |
194 | of this object and reply with the following message: | |
195 | .in +4n | |
7260a6e1 | 196 | |
5963519c KF |
197 | .nf |
198 | struct fuse_attr { | |
7260a6e1 MK |
199 | uint64_t ino; |
200 | uint64_t size; | |
201 | uint64_t blocks; | |
202 | uint64_t atime; | |
203 | uint64_t mtime; | |
204 | uint64_t ctime; | |
205 | uint32_t atimensec; | |
206 | uint32_t mtimensec; | |
207 | uint32_t ctimensec; | |
208 | uint32_t mode; | |
209 | uint32_t nlink; | |
210 | uint32_t uid; | |
211 | uint32_t gid; | |
212 | uint32_t rdev; | |
213 | uint32_t blksize; | |
214 | uint32_t padding; | |
5963519c | 215 | }; |
7260a6e1 | 216 | |
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; | |
5963519c KF |
222 | struct fuse_attr attr; |
223 | }; | |
224 | .fi | |
225 | .in | |
226 | ||
227 | The fields of | |
228 | .I struct fuse_attr | |
72e830cc MK |
229 | describe the attributes of the required file. |
230 | For the interpretation of these fields, see | |
7260a6e1 | 231 | .BR stat (2). |
5963519c KF |
232 | .TP |
233 | .BR FUSE_ACCESS " ( 34 )" | |
234 | ||
235 | .in +4n | |
236 | .nf | |
237 | struct fuse_access_in { | |
7260a6e1 MK |
238 | uint32_t mask; |
239 | uint32_t padding; | |
5963519c KF |
240 | }; |
241 | .fi | |
242 | .in | |
243 | ||
244 | If the | |
245 | .I default_permissions | |
72e830cc MK |
246 | mount options is not used, this request may be used for permissions checking. |
247 | No reply data is expected, but errors may be indicated | |
5963519c KF |
248 | as usual in the reply header (in particular, access denied errors |
249 | may be indicated, by setting such field to | |
7260a6e1 | 250 | .BR \-EACCES ). |
5963519c KF |
251 | .TP |
252 | .BR FUSE_OPEN " ( 14 ) and " FUSE_OPENDIR " ( 34 )" | |
253 | .in +4n | |
254 | .nf | |
255 | struct fuse_open_in { | |
7260a6e1 MK |
256 | uint32_t flags; /* The flags that were passed |
257 | to the open(2) */ | |
258 | uint32_t unused; | |
5963519c KF |
259 | }; |
260 | .fi | |
261 | .in | |
262 | ||
263 | The requested operation is to open the node indicated by | |
7260a6e1 MK |
264 | .IR header\->nodeid . |
265 | The exact semantics of what this means will depend on the | |
72e830cc MK |
266 | filesystem being implemented. |
267 | However, at the very least the | |
7260a6e1 | 268 | filesystem should validate that the requested |
5963519c | 269 | .I flags |
7260a6e1 MK |
270 | are valid for the indicated resource and then send a reply with the |
271 | following format: | |
5963519c KF |
272 | |
273 | .in +4n | |
274 | .nf | |
275 | ||
276 | struct fuse_open_out { | |
7260a6e1 MK |
277 | uint64_t fh; |
278 | uint32_t open_flags; | |
279 | uint32_t padding; | |
5963519c KF |
280 | }; |
281 | ||
282 | .fi | |
283 | .in | |
284 | ||
7260a6e1 | 285 | The |
5963519c | 286 | .I fh |
7260a6e1 MK |
287 | field is an opaque identifier that the kernel will use to refer |
288 | to this resource | |
289 | The | |
290 | .I open_flags | |
291 | field is a bit mask of any number of | |
5963519c KF |
292 | .B FOPEN_* |
293 | flags, which indicate properties of this file handle to the kernel. | |
5963519c KF |
294 | .TP |
295 | .BR FUSE_READ " ( 15 ) and " FUSE_READDIR " ( 28 )" | |
296 | .in +4n | |
297 | .nf | |
298 | ||
299 | struct fuse_read_in { | |
7260a6e1 MK |
300 | uint64_t fh; |
301 | uint64_t offset; | |
302 | uint32_t size; | |
303 | uint32_t read_flags; | |
304 | uint64_t lock_owner; | |
305 | uint32_t flags; | |
306 | uint32_t padding; | |
5963519c KF |
307 | }; |
308 | ||
309 | .fi | |
310 | .in | |
311 | ||
7260a6e1 | 312 | The requested action is to read up to |
5963519c KF |
313 | .I size |
314 | bytes of the file or directory, starting at | |
7260a6e1 MK |
315 | .IR offset . |
316 | The bytes should be returned directly following the out header, | |
5963519c | 317 | with no further special out structure. |
5963519c KF |
318 | .TP |
319 | .BR FUSE_INTERRUPT " ( 36 )" | |
320 | .in +4n | |
321 | .nf | |
322 | struct fuse_interrupt_in { | |
7260a6e1 | 323 | uint64_t unique; |
5963519c KF |
324 | }; |
325 | .fi | |
326 | .in | |
327 | ||
328 | The requested action is to cancel the pending operation indicated by | |
7260a6e1 | 329 | .IR unique . |
72e830cc MK |
330 | This request requires no response. |
331 | However, receipt of this message does | |
332 | not by itself cancel the indicated operation. | |
7260a6e1 MK |
333 | The kernel will still expect a reply to said operation (e.g., an |
334 | .I EINTR | |
335 | error or a short read). | |
72e830cc | 336 | At most one |
5963519c | 337 | .B FUSE_INTERRUPT |
72e830cc MK |
338 | request will be issued for a given operation. |
339 | After issuing said operation, | |
7260a6e1 | 340 | the kernel will wait uninterruptibly for completion of the indicated request. |
5963519c KF |
341 | .TP |
342 | .BR FUSE_LOOKUP " ( 1 )" | |
5963519c KF |
343 | Directly following the header is a filename to be looked up in the directory |
344 | indicated by | |
7260a6e1 MK |
345 | .IR header\->nodeid . |
346 | The expected reply is of the form: | |
5963519c KF |
347 | |
348 | .in +4n | |
349 | .nf | |
350 | struct fuse_entry_out { | |
7260a6e1 | 351 | uint64_t nodeid; /* Inode ID */ |
5d69a98a | 352 | uint64_t generation; /* Inode generation */ |
7260a6e1 MK |
353 | uint64_t entry_valid; |
354 | uint64_t attr_valid; | |
355 | uint32_t entry_valid_nsec; | |
356 | uint32_t attr_valid_nsec; | |
5963519c KF |
357 | struct fuse_attr attr; |
358 | }; | |
359 | .fi | |
360 | .in | |
361 | ||
5d69a98a MK |
362 | The combination of |
363 | .I nodeid | |
364 | and | |
365 | .I generation | |
366 | must be unique for the filesystem's lifetime. | |
367 | ||
5963519c KF |
368 | The interpretation of timeouts and |
369 | .I attr | |
7260a6e1 MK |
370 | is as for |
371 | .BR FUSE_GETATTR . | |
5963519c KF |
372 | .TP |
373 | .BR FUSE_FLUSH " ( 36 )" | |
374 | .in +4n | |
375 | .nf | |
376 | struct fuse_flush_in { | |
7260a6e1 MK |
377 | uint64_t fh; |
378 | uint32_t unused; | |
379 | uint32_t padding; | |
380 | uint64_t lock_owner; | |
5963519c KF |
381 | }; |
382 | .fi | |
383 | .in | |
384 | ||
385 | The requested action is to flush any pending changes to the indicated | |
72e830cc MK |
386 | file handle. |
387 | No reply data is expected. | |
388 | However, an empty reply message | |
5963519c | 389 | still needs to be issued once the flush operation is complete. |
5963519c KF |
390 | .TP |
391 | .BR FUSE_RELEASE " ( 18 ) and " FUSE_RELEASEDIR " ( 29 )" | |
392 | .in +4n | |
393 | .nf | |
394 | struct fuse_release_in { | |
7260a6e1 MK |
395 | uint64_t fh; |
396 | uint32_t flags; | |
397 | uint32_t release_flags; | |
398 | uint64_t lock_owner; | |
5963519c KF |
399 | }; |
400 | .fi | |
401 | .in | |
402 | ||
7260a6e1 | 403 | These are the converse of |
5963519c | 404 | .BR FUSE_OPEN |
7260a6e1 | 405 | and |
5963519c | 406 | .BR FUSE_OPENDIR |
72e830cc MK |
407 | respectively. |
408 | The daemon may now free any resources associated with the | |
5963519c KF |
409 | file handle |
410 | .I fh | |
72e830cc | 411 | as the kernel will no longer refer to it. |
7260a6e1 | 412 | There is no reply data associated with this request, |
72e830cc | 413 | but a reply still needs to be issued once the request has |
5963519c | 414 | been completely processed. |
5963519c KF |
415 | .TP |
416 | .BR FUSE_STATFS " ( 17 )" | |
417 | This operation implements | |
7260a6e1 MK |
418 | .BR statfs (2) |
419 | for this filesystem. | |
72e830cc | 420 | There is no input data associated with this request. |
5963519c | 421 | The expected reply data has the following structure: |
7260a6e1 | 422 | |
5963519c KF |
423 | .in +4n |
424 | .nf | |
425 | struct fuse_kstatfs { | |
7260a6e1 MK |
426 | uint64_t blocks; |
427 | uint64_t bfree; | |
428 | uint64_t bavail; | |
429 | uint64_t files; | |
430 | uint64_t ffree; | |
431 | uint32_t bsize; | |
432 | uint32_t namelen; | |
433 | uint32_t frsize; | |
434 | uint32_t padding; | |
435 | uint32_t spare[6]; | |
5963519c | 436 | }; |
7260a6e1 | 437 | |
5963519c KF |
438 | struct fuse_statfs_out { |
439 | struct fuse_kstatfs st; | |
440 | }; | |
441 | .fi | |
442 | .in | |
443 | ||
444 | For the interpretation of these fields, see | |
7260a6e1 | 445 | .BR statfs (2). |
5963519c | 446 | .SH ERRORS |
7260a6e1 | 447 | .TP |
5963519c KF |
448 | .B EPERM |
449 | Returned from operations on a | |
450 | .I /dev/fuse | |
7260a6e1 MK |
451 | file descriptor that has not been mounted. |
452 | .TP | |
5963519c KF |
453 | .B EIO |
454 | Returned from | |
7260a6e1 | 455 | .BR read (2) |
5963519c KF |
456 | operations when the kernel's request is too large for the provided buffer. |
457 | ||
458 | .IR Note : | |
459 | There are various ways in which incorrect use of these interfaces can cause | |
460 | operations on the provided filesystem's files and directories to fail with | |
7260a6e1 MK |
461 | .BR EIO . |
462 | Among the possible incorrect uses are | |
463 | .IP * 3 | |
464 | changing | |
5963519c | 465 | .I mode & S_IFMT |
7260a6e1 MK |
466 | for an inode that has previously been reported to the kernel; or |
467 | .IP * | |
468 | giving replies to the kernel that are shorter than what the kernel expected. | |
469 | .TP | |
5963519c KF |
470 | .B EINVAL |
471 | Returned from | |
7260a6e1 | 472 | .BR write (2) |
72e830cc MK |
473 | if validation of the reply failed. |
474 | Note all mistakes in replies will be caught by this validation. | |
475 | However, basic mistakes, such as short replies or an incorrect | |
5963519c KF |
476 | .I unique |
477 | value. | |
7260a6e1 | 478 | .TP |
5963519c KF |
479 | .B E2BIG |
480 | Returned from | |
7260a6e1 | 481 | .BR read (2) |
5963519c | 482 | operations when the kernel's request is too large for the provided buffer |
7260a6e1 MK |
483 | and the request was |
484 | .BR FUSE_SETXATTR . | |
485 | .TP | |
5963519c | 486 | .B ENODEV |
7260a6e1 | 487 | Returned from either operation if the FUSE filesystem was unmounted. |