]>
Commit | Line | Data |
---|---|---|
ee46c789 | 1 | /* |
7387863d DDAG |
2 | * FUSE: Filesystem in Userspace |
3 | * Copyright (C) 2001-2007 Miklos Szeredi <miklos@szeredi.hu> | |
4 | * | |
5 | * This program can be distributed under the terms of the GNU LGPLv2. | |
6 | * See the file COPYING.LIB. | |
7 | */ | |
ee46c789 DDAG |
8 | |
9 | #ifndef FUSE_LOWLEVEL_H_ | |
10 | #define FUSE_LOWLEVEL_H_ | |
11 | ||
7387863d DDAG |
12 | /** |
13 | * @file | |
ee46c789 DDAG |
14 | * |
15 | * Low level API | |
16 | * | |
17 | * IMPORTANT: you should define FUSE_USE_VERSION before including this | |
18 | * header. To use the newest API define it to 31 (recommended for any | |
19 | * new application). | |
20 | */ | |
21 | ||
22 | #ifndef FUSE_USE_VERSION | |
23 | #error FUSE_USE_VERSION not defined | |
24 | #endif | |
25 | ||
26 | #include "fuse_common.h" | |
27 | ||
ee46c789 DDAG |
28 | #include <sys/statvfs.h> |
29 | #include <sys/uio.h> | |
7387863d | 30 | #include <utime.h> |
ee46c789 | 31 | |
7387863d DDAG |
32 | /* |
33 | * Miscellaneous definitions | |
34 | */ | |
ee46c789 DDAG |
35 | |
36 | /** The node ID of the root inode */ | |
37 | #define FUSE_ROOT_ID 1 | |
38 | ||
39 | /** Inode number type */ | |
40 | typedef uint64_t fuse_ino_t; | |
41 | ||
42 | /** Request pointer type */ | |
43 | typedef struct fuse_req *fuse_req_t; | |
44 | ||
45 | /** | |
46 | * Session | |
47 | * | |
48 | * This provides hooks for processing requests, and exiting | |
49 | */ | |
50 | struct fuse_session; | |
51 | ||
52 | /** Directory entry parameters supplied to fuse_reply_entry() */ | |
53 | struct fuse_entry_param { | |
7387863d DDAG |
54 | /** |
55 | * Unique inode number | |
56 | * | |
57 | * In lookup, zero means negative entry (from version 2.5) | |
58 | * Returning ENOENT also means negative entry, but by setting zero | |
59 | * ino the kernel may cache negative entries for entry_timeout | |
60 | * seconds. | |
61 | */ | |
62 | fuse_ino_t ino; | |
63 | ||
64 | /** | |
65 | * Generation number for this entry. | |
66 | * | |
67 | * If the file system will be exported over NFS, the | |
68 | * ino/generation pairs need to be unique over the file | |
69 | * system's lifetime (rather than just the mount time). So if | |
70 | * the file system reuses an inode after it has been deleted, | |
71 | * it must assign a new, previously unused generation number | |
72 | * to the inode at the same time. | |
73 | * | |
74 | */ | |
75 | uint64_t generation; | |
76 | ||
77 | /** | |
78 | * Inode attributes. | |
79 | * | |
80 | * Even if attr_timeout == 0, attr must be correct. For example, | |
81 | * for open(), FUSE uses attr.st_size from lookup() to determine | |
82 | * how many bytes to request. If this value is not correct, | |
83 | * incorrect data will be returned. | |
84 | */ | |
85 | struct stat attr; | |
86 | ||
87 | /** | |
88 | * Validity timeout (in seconds) for inode attributes. If | |
89 | * attributes only change as a result of requests that come | |
90 | * through the kernel, this should be set to a very large | |
91 | * value. | |
92 | */ | |
93 | double attr_timeout; | |
94 | ||
95 | /** | |
96 | * Validity timeout (in seconds) for the name. If directory | |
97 | * entries are changed/deleted only as a result of requests | |
98 | * that come through the kernel, this should be set to a very | |
99 | * large value. | |
100 | */ | |
101 | double entry_timeout; | |
93e79851 HR |
102 | |
103 | /** | |
104 | * Flags for fuse_attr.flags that do not fit into attr. | |
105 | */ | |
106 | uint32_t attr_flags; | |
ee46c789 DDAG |
107 | }; |
108 | ||
109 | /** | |
110 | * Additional context associated with requests. | |
111 | * | |
112 | * Note that the reported client uid, gid and pid may be zero in some | |
113 | * situations. For example, if the FUSE file system is running in a | |
114 | * PID or user namespace but then accessed from outside the namespace, | |
115 | * there is no valid uid/pid/gid that could be reported. | |
116 | */ | |
117 | struct fuse_ctx { | |
7387863d DDAG |
118 | /** User ID of the calling process */ |
119 | uid_t uid; | |
ee46c789 | 120 | |
7387863d DDAG |
121 | /** Group ID of the calling process */ |
122 | gid_t gid; | |
ee46c789 | 123 | |
7387863d DDAG |
124 | /** Thread ID of the calling process */ |
125 | pid_t pid; | |
ee46c789 | 126 | |
7387863d DDAG |
127 | /** Umask of the calling process */ |
128 | mode_t umask; | |
ee46c789 DDAG |
129 | }; |
130 | ||
131 | struct fuse_forget_data { | |
7387863d DDAG |
132 | fuse_ino_t ino; |
133 | uint64_t nlookup; | |
ee46c789 DDAG |
134 | }; |
135 | ||
136 | /* 'to_set' flags in setattr */ | |
7387863d DDAG |
137 | #define FUSE_SET_ATTR_MODE (1 << 0) |
138 | #define FUSE_SET_ATTR_UID (1 << 1) | |
139 | #define FUSE_SET_ATTR_GID (1 << 2) | |
140 | #define FUSE_SET_ATTR_SIZE (1 << 3) | |
141 | #define FUSE_SET_ATTR_ATIME (1 << 4) | |
142 | #define FUSE_SET_ATTR_MTIME (1 << 5) | |
143 | #define FUSE_SET_ATTR_ATIME_NOW (1 << 7) | |
144 | #define FUSE_SET_ATTR_MTIME_NOW (1 << 8) | |
145 | #define FUSE_SET_ATTR_CTIME (1 << 10) | |
d64907ac | 146 | #define FUSE_SET_ATTR_KILL_SUIDGID (1 << 11) |
7387863d DDAG |
147 | |
148 | /* | |
149 | * Request methods and replies | |
150 | */ | |
ee46c789 DDAG |
151 | |
152 | /** | |
153 | * Low level filesystem operations | |
154 | * | |
155 | * Most of the methods (with the exception of init and destroy) | |
156 | * receive a request handle (fuse_req_t) as their first argument. | |
157 | * This handle must be passed to one of the specified reply functions. | |
158 | * | |
159 | * This may be done inside the method invocation, or after the call | |
160 | * has returned. The request handle is valid until one of the reply | |
161 | * functions is called. | |
162 | * | |
163 | * Other pointer arguments (name, fuse_file_info, etc) are not valid | |
164 | * after the call has returned, so if they are needed later, their | |
165 | * contents have to be copied. | |
166 | * | |
167 | * In general, all methods are expected to perform any necessary | |
168 | * permission checking. However, a filesystem may delegate this task | |
169 | * to the kernel by passing the `default_permissions` mount option to | |
170 | * `fuse_session_new()`. In this case, methods will only be called if | |
171 | * the kernel's permission check has succeeded. | |
172 | * | |
173 | * The filesystem sometimes needs to handle a return value of -ENOENT | |
174 | * from the reply function, which means, that the request was | |
175 | * interrupted, and the reply discarded. For example if | |
176 | * fuse_reply_open() return -ENOENT means, that the release method for | |
177 | * this file will not be called. | |
178 | */ | |
179 | struct fuse_lowlevel_ops { | |
7387863d DDAG |
180 | /** |
181 | * Initialize filesystem | |
182 | * | |
183 | * This function is called when libfuse establishes | |
184 | * communication with the FUSE kernel module. The file system | |
185 | * should use this module to inspect and/or modify the | |
186 | * connection parameters provided in the `conn` structure. | |
187 | * | |
188 | * Note that some parameters may be overwritten by options | |
189 | * passed to fuse_session_new() which take precedence over the | |
190 | * values set in this handler. | |
191 | * | |
192 | * There's no reply to this function | |
193 | * | |
194 | * @param userdata the user data passed to fuse_session_new() | |
195 | */ | |
196 | void (*init)(void *userdata, struct fuse_conn_info *conn); | |
197 | ||
198 | /** | |
199 | * Clean up filesystem. | |
200 | * | |
201 | * Called on filesystem exit. When this method is called, the | |
202 | * connection to the kernel may be gone already, so that eg. calls | |
203 | * to fuse_lowlevel_notify_* will fail. | |
204 | * | |
205 | * There's no reply to this function | |
206 | * | |
207 | * @param userdata the user data passed to fuse_session_new() | |
208 | */ | |
209 | void (*destroy)(void *userdata); | |
210 | ||
211 | /** | |
212 | * Look up a directory entry by name and get its attributes. | |
213 | * | |
214 | * Valid replies: | |
215 | * fuse_reply_entry | |
216 | * fuse_reply_err | |
217 | * | |
218 | * @param req request handle | |
219 | * @param parent inode number of the parent directory | |
220 | * @param name the name to look up | |
221 | */ | |
222 | void (*lookup)(fuse_req_t req, fuse_ino_t parent, const char *name); | |
223 | ||
224 | /** | |
225 | * Forget about an inode | |
226 | * | |
227 | * This function is called when the kernel removes an inode | |
228 | * from its internal caches. | |
229 | * | |
230 | * The inode's lookup count increases by one for every call to | |
231 | * fuse_reply_entry and fuse_reply_create. The nlookup parameter | |
232 | * indicates by how much the lookup count should be decreased. | |
233 | * | |
234 | * Inodes with a non-zero lookup count may receive request from | |
235 | * the kernel even after calls to unlink, rmdir or (when | |
236 | * overwriting an existing file) rename. Filesystems must handle | |
237 | * such requests properly and it is recommended to defer removal | |
238 | * of the inode until the lookup count reaches zero. Calls to | |
239 | * unlink, rmdir or rename will be followed closely by forget | |
240 | * unless the file or directory is open, in which case the | |
241 | * kernel issues forget only after the release or releasedir | |
242 | * calls. | |
243 | * | |
244 | * Note that if a file system will be exported over NFS the | |
245 | * inodes lifetime must extend even beyond forget. See the | |
246 | * generation field in struct fuse_entry_param above. | |
247 | * | |
248 | * On unmount the lookup count for all inodes implicitly drops | |
249 | * to zero. It is not guaranteed that the file system will | |
250 | * receive corresponding forget messages for the affected | |
251 | * inodes. | |
252 | * | |
253 | * Valid replies: | |
254 | * fuse_reply_none | |
255 | * | |
256 | * @param req request handle | |
257 | * @param ino the inode number | |
258 | * @param nlookup the number of lookups to forget | |
259 | */ | |
260 | void (*forget)(fuse_req_t req, fuse_ino_t ino, uint64_t nlookup); | |
261 | ||
262 | /** | |
263 | * Get file attributes. | |
264 | * | |
265 | * If writeback caching is enabled, the kernel may have a | |
266 | * better idea of a file's length than the FUSE file system | |
267 | * (eg if there has been a write that extended the file size, | |
268 | * but that has not yet been passed to the filesystem.n | |
269 | * | |
270 | * In this case, the st_size value provided by the file system | |
271 | * will be ignored. | |
272 | * | |
273 | * Valid replies: | |
274 | * fuse_reply_attr | |
275 | * fuse_reply_err | |
276 | * | |
277 | * @param req request handle | |
278 | * @param ino the inode number | |
279 | * @param fi for future use, currently always NULL | |
280 | */ | |
281 | void (*getattr)(fuse_req_t req, fuse_ino_t ino, struct fuse_file_info *fi); | |
282 | ||
283 | /** | |
284 | * Set file attributes | |
285 | * | |
286 | * In the 'attr' argument only members indicated by the 'to_set' | |
287 | * bitmask contain valid values. Other members contain undefined | |
288 | * values. | |
289 | * | |
290 | * Unless FUSE_CAP_HANDLE_KILLPRIV is disabled, this method is | |
291 | * expected to reset the setuid and setgid bits if the file | |
292 | * size or owner is being changed. | |
293 | * | |
294 | * If the setattr was invoked from the ftruncate() system call | |
295 | * under Linux kernel versions 2.6.15 or later, the fi->fh will | |
296 | * contain the value set by the open method or will be undefined | |
297 | * if the open method didn't set any value. Otherwise (not | |
298 | * ftruncate call, or kernel version earlier than 2.6.15) the fi | |
299 | * parameter will be NULL. | |
300 | * | |
301 | * Valid replies: | |
302 | * fuse_reply_attr | |
303 | * fuse_reply_err | |
304 | * | |
305 | * @param req request handle | |
306 | * @param ino the inode number | |
307 | * @param attr the attributes | |
308 | * @param to_set bit mask of attributes which should be set | |
309 | * @param fi file information, or NULL | |
310 | */ | |
311 | void (*setattr)(fuse_req_t req, fuse_ino_t ino, struct stat *attr, | |
312 | int to_set, struct fuse_file_info *fi); | |
313 | ||
314 | /** | |
315 | * Read symbolic link | |
316 | * | |
317 | * Valid replies: | |
318 | * fuse_reply_readlink | |
319 | * fuse_reply_err | |
320 | * | |
321 | * @param req request handle | |
322 | * @param ino the inode number | |
323 | */ | |
324 | void (*readlink)(fuse_req_t req, fuse_ino_t ino); | |
325 | ||
326 | /** | |
327 | * Create file node | |
328 | * | |
329 | * Create a regular file, character device, block device, fifo or | |
330 | * socket node. | |
331 | * | |
332 | * Valid replies: | |
333 | * fuse_reply_entry | |
334 | * fuse_reply_err | |
335 | * | |
336 | * @param req request handle | |
337 | * @param parent inode number of the parent directory | |
338 | * @param name to create | |
339 | * @param mode file type and mode with which to create the new file | |
340 | * @param rdev the device number (only valid if created file is a device) | |
341 | */ | |
342 | void (*mknod)(fuse_req_t req, fuse_ino_t parent, const char *name, | |
343 | mode_t mode, dev_t rdev); | |
344 | ||
345 | /** | |
346 | * Create a directory | |
347 | * | |
348 | * Valid replies: | |
349 | * fuse_reply_entry | |
350 | * fuse_reply_err | |
351 | * | |
352 | * @param req request handle | |
353 | * @param parent inode number of the parent directory | |
354 | * @param name to create | |
355 | * @param mode with which to create the new file | |
356 | */ | |
357 | void (*mkdir)(fuse_req_t req, fuse_ino_t parent, const char *name, | |
358 | mode_t mode); | |
359 | ||
360 | /** | |
361 | * Remove a file | |
362 | * | |
363 | * If the file's inode's lookup count is non-zero, the file | |
364 | * system is expected to postpone any removal of the inode | |
365 | * until the lookup count reaches zero (see description of the | |
366 | * forget function). | |
367 | * | |
368 | * Valid replies: | |
369 | * fuse_reply_err | |
370 | * | |
371 | * @param req request handle | |
372 | * @param parent inode number of the parent directory | |
373 | * @param name to remove | |
374 | */ | |
375 | void (*unlink)(fuse_req_t req, fuse_ino_t parent, const char *name); | |
376 | ||
377 | /** | |
378 | * Remove a directory | |
379 | * | |
380 | * If the directory's inode's lookup count is non-zero, the | |
381 | * file system is expected to postpone any removal of the | |
382 | * inode until the lookup count reaches zero (see description | |
383 | * of the forget function). | |
384 | * | |
385 | * Valid replies: | |
386 | * fuse_reply_err | |
387 | * | |
388 | * @param req request handle | |
389 | * @param parent inode number of the parent directory | |
390 | * @param name to remove | |
391 | */ | |
392 | void (*rmdir)(fuse_req_t req, fuse_ino_t parent, const char *name); | |
393 | ||
394 | /** | |
395 | * Create a symbolic link | |
396 | * | |
397 | * Valid replies: | |
398 | * fuse_reply_entry | |
399 | * fuse_reply_err | |
400 | * | |
401 | * @param req request handle | |
402 | * @param link the contents of the symbolic link | |
403 | * @param parent inode number of the parent directory | |
404 | * @param name to create | |
405 | */ | |
406 | void (*symlink)(fuse_req_t req, const char *link, fuse_ino_t parent, | |
407 | const char *name); | |
408 | ||
409 | /** | |
410 | * Rename a file | |
411 | * | |
412 | * If the target exists it should be atomically replaced. If | |
413 | * the target's inode's lookup count is non-zero, the file | |
414 | * system is expected to postpone any removal of the inode | |
415 | * until the lookup count reaches zero (see description of the | |
416 | * forget function). | |
417 | * | |
418 | * If this request is answered with an error code of ENOSYS, this is | |
419 | * treated as a permanent failure with error code EINVAL, i.e. all | |
420 | * future bmap requests will fail with EINVAL without being | |
421 | * send to the filesystem process. | |
422 | * | |
423 | * *flags* may be `RENAME_EXCHANGE` or `RENAME_NOREPLACE`. If | |
424 | * RENAME_NOREPLACE is specified, the filesystem must not | |
425 | * overwrite *newname* if it exists and return an error | |
426 | * instead. If `RENAME_EXCHANGE` is specified, the filesystem | |
427 | * must atomically exchange the two files, i.e. both must | |
428 | * exist and neither may be deleted. | |
429 | * | |
430 | * Valid replies: | |
431 | * fuse_reply_err | |
432 | * | |
433 | * @param req request handle | |
434 | * @param parent inode number of the old parent directory | |
435 | * @param name old name | |
436 | * @param newparent inode number of the new parent directory | |
437 | * @param newname new name | |
438 | */ | |
439 | void (*rename)(fuse_req_t req, fuse_ino_t parent, const char *name, | |
440 | fuse_ino_t newparent, const char *newname, | |
441 | unsigned int flags); | |
442 | ||
443 | /** | |
444 | * Create a hard link | |
445 | * | |
446 | * Valid replies: | |
447 | * fuse_reply_entry | |
448 | * fuse_reply_err | |
449 | * | |
450 | * @param req request handle | |
451 | * @param ino the old inode number | |
452 | * @param newparent inode number of the new parent directory | |
453 | * @param newname new name to create | |
454 | */ | |
455 | void (*link)(fuse_req_t req, fuse_ino_t ino, fuse_ino_t newparent, | |
456 | const char *newname); | |
457 | ||
458 | /** | |
459 | * Open a file | |
460 | * | |
461 | * Open flags are available in fi->flags. The following rules | |
462 | * apply. | |
463 | * | |
464 | * - Creation (O_CREAT, O_EXCL, O_NOCTTY) flags will be | |
465 | * filtered out / handled by the kernel. | |
466 | * | |
467 | * - Access modes (O_RDONLY, O_WRONLY, O_RDWR) should be used | |
468 | * by the filesystem to check if the operation is | |
469 | * permitted. If the ``-o default_permissions`` mount | |
470 | * option is given, this check is already done by the | |
471 | * kernel before calling open() and may thus be omitted by | |
472 | * the filesystem. | |
473 | * | |
474 | * - When writeback caching is enabled, the kernel may send | |
475 | * read requests even for files opened with O_WRONLY. The | |
476 | * filesystem should be prepared to handle this. | |
477 | * | |
478 | * - When writeback caching is disabled, the filesystem is | |
479 | * expected to properly handle the O_APPEND flag and ensure | |
480 | * that each write is appending to the end of the file. | |
481 | * | |
482 | * - When writeback caching is enabled, the kernel will | |
483 | * handle O_APPEND. However, unless all changes to the file | |
484 | * come through the kernel this will not work reliably. The | |
485 | * filesystem should thus either ignore the O_APPEND flag | |
486 | * (and let the kernel handle it), or return an error | |
487 | * (indicating that reliably O_APPEND is not available). | |
488 | * | |
489 | * Filesystem may store an arbitrary file handle (pointer, | |
490 | * index, etc) in fi->fh, and use this in other all other file | |
491 | * operations (read, write, flush, release, fsync). | |
492 | * | |
493 | * Filesystem may also implement stateless file I/O and not store | |
494 | * anything in fi->fh. | |
495 | * | |
496 | * There are also some flags (direct_io, keep_cache) which the | |
497 | * filesystem may set in fi, to change the way the file is opened. | |
498 | * See fuse_file_info structure in <fuse_common.h> for more details. | |
499 | * | |
500 | * If this request is answered with an error code of ENOSYS | |
501 | * and FUSE_CAP_NO_OPEN_SUPPORT is set in | |
502 | * `fuse_conn_info.capable`, this is treated as success and | |
503 | * future calls to open and release will also succeed without being | |
504 | * sent to the filesystem process. | |
505 | * | |
506 | * Valid replies: | |
507 | * fuse_reply_open | |
508 | * fuse_reply_err | |
509 | * | |
510 | * @param req request handle | |
511 | * @param ino the inode number | |
512 | * @param fi file information | |
513 | */ | |
514 | void (*open)(fuse_req_t req, fuse_ino_t ino, struct fuse_file_info *fi); | |
515 | ||
516 | /** | |
517 | * Read data | |
518 | * | |
519 | * Read should send exactly the number of bytes requested except | |
520 | * on EOF or error, otherwise the rest of the data will be | |
521 | * substituted with zeroes. An exception to this is when the file | |
522 | * has been opened in 'direct_io' mode, in which case the return | |
523 | * value of the read system call will reflect the return value of | |
524 | * this operation. | |
525 | * | |
526 | * fi->fh will contain the value set by the open method, or will | |
527 | * be undefined if the open method didn't set any value. | |
528 | * | |
529 | * Valid replies: | |
530 | * fuse_reply_buf | |
531 | * fuse_reply_iov | |
532 | * fuse_reply_data | |
533 | * fuse_reply_err | |
534 | * | |
535 | * @param req request handle | |
536 | * @param ino the inode number | |
537 | * @param size number of bytes to read | |
538 | * @param off offset to read from | |
539 | * @param fi file information | |
540 | */ | |
541 | void (*read)(fuse_req_t req, fuse_ino_t ino, size_t size, off_t off, | |
542 | struct fuse_file_info *fi); | |
543 | ||
544 | /** | |
545 | * Write data | |
546 | * | |
547 | * Write should return exactly the number of bytes requested | |
548 | * except on error. An exception to this is when the file has | |
549 | * been opened in 'direct_io' mode, in which case the return value | |
550 | * of the write system call will reflect the return value of this | |
551 | * operation. | |
552 | * | |
553 | * Unless FUSE_CAP_HANDLE_KILLPRIV is disabled, this method is | |
554 | * expected to reset the setuid and setgid bits. | |
555 | * | |
556 | * fi->fh will contain the value set by the open method, or will | |
557 | * be undefined if the open method didn't set any value. | |
558 | * | |
559 | * Valid replies: | |
560 | * fuse_reply_write | |
561 | * fuse_reply_err | |
562 | * | |
563 | * @param req request handle | |
564 | * @param ino the inode number | |
565 | * @param buf data to write | |
566 | * @param size number of bytes to write | |
567 | * @param off offset to write to | |
568 | * @param fi file information | |
569 | */ | |
570 | void (*write)(fuse_req_t req, fuse_ino_t ino, const char *buf, size_t size, | |
571 | off_t off, struct fuse_file_info *fi); | |
572 | ||
573 | /** | |
574 | * Flush method | |
575 | * | |
576 | * This is called on each close() of the opened file. | |
577 | * | |
578 | * Since file descriptors can be duplicated (dup, dup2, fork), for | |
579 | * one open call there may be many flush calls. | |
580 | * | |
581 | * Filesystems shouldn't assume that flush will always be called | |
582 | * after some writes, or that if will be called at all. | |
583 | * | |
584 | * fi->fh will contain the value set by the open method, or will | |
585 | * be undefined if the open method didn't set any value. | |
586 | * | |
587 | * NOTE: the name of the method is misleading, since (unlike | |
588 | * fsync) the filesystem is not forced to flush pending writes. | |
589 | * One reason to flush data is if the filesystem wants to return | |
590 | * write errors during close. However, such use is non-portable | |
591 | * because POSIX does not require [close] to wait for delayed I/O to | |
592 | * complete. | |
593 | * | |
594 | * If the filesystem supports file locking operations (setlk, | |
595 | * getlk) it should remove all locks belonging to 'fi->owner'. | |
596 | * | |
597 | * If this request is answered with an error code of ENOSYS, | |
598 | * this is treated as success and future calls to flush() will | |
599 | * succeed automatically without being send to the filesystem | |
600 | * process. | |
601 | * | |
602 | * Valid replies: | |
603 | * fuse_reply_err | |
604 | * | |
605 | * @param req request handle | |
606 | * @param ino the inode number | |
607 | * @param fi file information | |
608 | * | |
609 | * [close]: | |
610 | * http://pubs.opengroup.org/onlinepubs/9699919799/functions/close.html | |
611 | */ | |
612 | void (*flush)(fuse_req_t req, fuse_ino_t ino, struct fuse_file_info *fi); | |
613 | ||
614 | /** | |
615 | * Release an open file | |
616 | * | |
617 | * Release is called when there are no more references to an open | |
618 | * file: all file descriptors are closed and all memory mappings | |
619 | * are unmapped. | |
620 | * | |
621 | * For every open call there will be exactly one release call (unless | |
622 | * the filesystem is force-unmounted). | |
623 | * | |
624 | * The filesystem may reply with an error, but error values are | |
625 | * not returned to close() or munmap() which triggered the | |
626 | * release. | |
627 | * | |
628 | * fi->fh will contain the value set by the open method, or will | |
629 | * be undefined if the open method didn't set any value. | |
630 | * fi->flags will contain the same flags as for open. | |
631 | * | |
632 | * Valid replies: | |
633 | * fuse_reply_err | |
634 | * | |
635 | * @param req request handle | |
636 | * @param ino the inode number | |
637 | * @param fi file information | |
638 | */ | |
639 | void (*release)(fuse_req_t req, fuse_ino_t ino, struct fuse_file_info *fi); | |
640 | ||
641 | /** | |
642 | * Synchronize file contents | |
643 | * | |
644 | * If the datasync parameter is non-zero, then only the user data | |
645 | * should be flushed, not the meta data. | |
646 | * | |
647 | * If this request is answered with an error code of ENOSYS, | |
648 | * this is treated as success and future calls to fsync() will | |
649 | * succeed automatically without being send to the filesystem | |
650 | * process. | |
651 | * | |
652 | * Valid replies: | |
653 | * fuse_reply_err | |
654 | * | |
655 | * @param req request handle | |
656 | * @param ino the inode number | |
657 | * @param datasync flag indicating if only data should be flushed | |
658 | * @param fi file information | |
659 | */ | |
660 | void (*fsync)(fuse_req_t req, fuse_ino_t ino, int datasync, | |
661 | struct fuse_file_info *fi); | |
662 | ||
663 | /** | |
664 | * Open a directory | |
665 | * | |
666 | * Filesystem may store an arbitrary file handle (pointer, index, | |
667 | * etc) in fi->fh, and use this in other all other directory | |
668 | * stream operations (readdir, releasedir, fsyncdir). | |
669 | * | |
670 | * If this request is answered with an error code of ENOSYS and | |
671 | * FUSE_CAP_NO_OPENDIR_SUPPORT is set in `fuse_conn_info.capable`, | |
672 | * this is treated as success and future calls to opendir and | |
673 | * releasedir will also succeed without being sent to the filesystem | |
674 | * process. In addition, the kernel will cache readdir results | |
675 | * as if opendir returned FOPEN_KEEP_CACHE | FOPEN_CACHE_DIR. | |
676 | * | |
677 | * Valid replies: | |
678 | * fuse_reply_open | |
679 | * fuse_reply_err | |
680 | * | |
681 | * @param req request handle | |
682 | * @param ino the inode number | |
683 | * @param fi file information | |
684 | */ | |
685 | void (*opendir)(fuse_req_t req, fuse_ino_t ino, struct fuse_file_info *fi); | |
686 | ||
687 | /** | |
688 | * Read directory | |
689 | * | |
690 | * Send a buffer filled using fuse_add_direntry(), with size not | |
691 | * exceeding the requested size. Send an empty buffer on end of | |
692 | * stream. | |
693 | * | |
694 | * fi->fh will contain the value set by the opendir method, or | |
695 | * will be undefined if the opendir method didn't set any value. | |
696 | * | |
697 | * Returning a directory entry from readdir() does not affect | |
698 | * its lookup count. | |
699 | * | |
700 | * If off_t is non-zero, then it will correspond to one of the off_t | |
701 | * values that was previously returned by readdir() for the same | |
702 | * directory handle. In this case, readdir() should skip over entries | |
703 | * coming before the position defined by the off_t value. If entries | |
704 | * are added or removed while the directory handle is open, they filesystem | |
705 | * may still include the entries that have been removed, and may not | |
706 | * report the entries that have been created. However, addition or | |
707 | * removal of entries must never cause readdir() to skip over unrelated | |
708 | * entries or to report them more than once. This means | |
709 | * that off_t can not be a simple index that enumerates the entries | |
710 | * that have been returned but must contain sufficient information to | |
711 | * uniquely determine the next directory entry to return even when the | |
712 | * set of entries is changing. | |
713 | * | |
714 | * The function does not have to report the '.' and '..' | |
715 | * entries, but is allowed to do so. Note that, if readdir does | |
716 | * not return '.' or '..', they will not be implicitly returned, | |
717 | * and this behavior is observable by the caller. | |
718 | * | |
719 | * Valid replies: | |
720 | * fuse_reply_buf | |
721 | * fuse_reply_data | |
722 | * fuse_reply_err | |
723 | * | |
724 | * @param req request handle | |
725 | * @param ino the inode number | |
726 | * @param size maximum number of bytes to send | |
727 | * @param off offset to continue reading the directory stream | |
728 | * @param fi file information | |
729 | */ | |
730 | void (*readdir)(fuse_req_t req, fuse_ino_t ino, size_t size, off_t off, | |
731 | struct fuse_file_info *fi); | |
732 | ||
733 | /** | |
734 | * Release an open directory | |
735 | * | |
736 | * For every opendir call there will be exactly one releasedir | |
737 | * call (unless the filesystem is force-unmounted). | |
738 | * | |
739 | * fi->fh will contain the value set by the opendir method, or | |
740 | * will be undefined if the opendir method didn't set any value. | |
741 | * | |
742 | * Valid replies: | |
743 | * fuse_reply_err | |
744 | * | |
745 | * @param req request handle | |
746 | * @param ino the inode number | |
747 | * @param fi file information | |
748 | */ | |
749 | void (*releasedir)(fuse_req_t req, fuse_ino_t ino, | |
750 | struct fuse_file_info *fi); | |
751 | ||
752 | /** | |
753 | * Synchronize directory contents | |
754 | * | |
755 | * If the datasync parameter is non-zero, then only the directory | |
756 | * contents should be flushed, not the meta data. | |
757 | * | |
758 | * fi->fh will contain the value set by the opendir method, or | |
759 | * will be undefined if the opendir method didn't set any value. | |
760 | * | |
761 | * If this request is answered with an error code of ENOSYS, | |
762 | * this is treated as success and future calls to fsyncdir() will | |
763 | * succeed automatically without being send to the filesystem | |
764 | * process. | |
765 | * | |
766 | * Valid replies: | |
767 | * fuse_reply_err | |
768 | * | |
769 | * @param req request handle | |
770 | * @param ino the inode number | |
771 | * @param datasync flag indicating if only data should be flushed | |
772 | * @param fi file information | |
773 | */ | |
774 | void (*fsyncdir)(fuse_req_t req, fuse_ino_t ino, int datasync, | |
775 | struct fuse_file_info *fi); | |
776 | ||
777 | /** | |
778 | * Get file system statistics | |
779 | * | |
780 | * Valid replies: | |
781 | * fuse_reply_statfs | |
782 | * fuse_reply_err | |
783 | * | |
784 | * @param req request handle | |
785 | * @param ino the inode number, zero means "undefined" | |
786 | */ | |
787 | void (*statfs)(fuse_req_t req, fuse_ino_t ino); | |
788 | ||
789 | /** | |
790 | * Set an extended attribute | |
791 | * | |
792 | * If this request is answered with an error code of ENOSYS, this is | |
793 | * treated as a permanent failure with error code EOPNOTSUPP, i.e. all | |
794 | * future setxattr() requests will fail with EOPNOTSUPP without being | |
795 | * send to the filesystem process. | |
796 | * | |
797 | * Valid replies: | |
798 | * fuse_reply_err | |
799 | */ | |
800 | void (*setxattr)(fuse_req_t req, fuse_ino_t ino, const char *name, | |
801 | const char *value, size_t size, int flags); | |
802 | ||
803 | /** | |
804 | * Get an extended attribute | |
805 | * | |
806 | * If size is zero, the size of the value should be sent with | |
807 | * fuse_reply_xattr. | |
808 | * | |
809 | * If the size is non-zero, and the value fits in the buffer, the | |
810 | * value should be sent with fuse_reply_buf. | |
811 | * | |
812 | * If the size is too small for the value, the ERANGE error should | |
813 | * be sent. | |
814 | * | |
815 | * If this request is answered with an error code of ENOSYS, this is | |
816 | * treated as a permanent failure with error code EOPNOTSUPP, i.e. all | |
817 | * future getxattr() requests will fail with EOPNOTSUPP without being | |
818 | * send to the filesystem process. | |
819 | * | |
820 | * Valid replies: | |
821 | * fuse_reply_buf | |
822 | * fuse_reply_data | |
823 | * fuse_reply_xattr | |
824 | * fuse_reply_err | |
825 | * | |
826 | * @param req request handle | |
827 | * @param ino the inode number | |
828 | * @param name of the extended attribute | |
829 | * @param size maximum size of the value to send | |
830 | */ | |
831 | void (*getxattr)(fuse_req_t req, fuse_ino_t ino, const char *name, | |
832 | size_t size); | |
833 | ||
834 | /** | |
835 | * List extended attribute names | |
836 | * | |
837 | * If size is zero, the total size of the attribute list should be | |
838 | * sent with fuse_reply_xattr. | |
839 | * | |
840 | * If the size is non-zero, and the null character separated | |
841 | * attribute list fits in the buffer, the list should be sent with | |
842 | * fuse_reply_buf. | |
843 | * | |
844 | * If the size is too small for the list, the ERANGE error should | |
845 | * be sent. | |
846 | * | |
847 | * If this request is answered with an error code of ENOSYS, this is | |
848 | * treated as a permanent failure with error code EOPNOTSUPP, i.e. all | |
849 | * future listxattr() requests will fail with EOPNOTSUPP without being | |
850 | * send to the filesystem process. | |
851 | * | |
852 | * Valid replies: | |
853 | * fuse_reply_buf | |
854 | * fuse_reply_data | |
855 | * fuse_reply_xattr | |
856 | * fuse_reply_err | |
857 | * | |
858 | * @param req request handle | |
859 | * @param ino the inode number | |
860 | * @param size maximum size of the list to send | |
861 | */ | |
862 | void (*listxattr)(fuse_req_t req, fuse_ino_t ino, size_t size); | |
863 | ||
864 | /** | |
865 | * Remove an extended attribute | |
866 | * | |
867 | * If this request is answered with an error code of ENOSYS, this is | |
868 | * treated as a permanent failure with error code EOPNOTSUPP, i.e. all | |
869 | * future removexattr() requests will fail with EOPNOTSUPP without being | |
870 | * send to the filesystem process. | |
871 | * | |
872 | * Valid replies: | |
873 | * fuse_reply_err | |
874 | * | |
875 | * @param req request handle | |
876 | * @param ino the inode number | |
877 | * @param name of the extended attribute | |
878 | */ | |
879 | void (*removexattr)(fuse_req_t req, fuse_ino_t ino, const char *name); | |
880 | ||
881 | /** | |
882 | * Check file access permissions | |
883 | * | |
884 | * This will be called for the access() and chdir() system | |
885 | * calls. If the 'default_permissions' mount option is given, | |
886 | * this method is not called. | |
887 | * | |
888 | * This method is not called under Linux kernel versions 2.4.x | |
889 | * | |
890 | * If this request is answered with an error code of ENOSYS, this is | |
891 | * treated as a permanent success, i.e. this and all future access() | |
892 | * requests will succeed without being send to the filesystem process. | |
893 | * | |
894 | * Valid replies: | |
895 | * fuse_reply_err | |
896 | * | |
897 | * @param req request handle | |
898 | * @param ino the inode number | |
899 | * @param mask requested access mode | |
900 | */ | |
901 | void (*access)(fuse_req_t req, fuse_ino_t ino, int mask); | |
902 | ||
903 | /** | |
904 | * Create and open a file | |
905 | * | |
906 | * If the file does not exist, first create it with the specified | |
907 | * mode, and then open it. | |
908 | * | |
909 | * See the description of the open handler for more | |
910 | * information. | |
911 | * | |
912 | * If this method is not implemented or under Linux kernel | |
913 | * versions earlier than 2.6.15, the mknod() and open() methods | |
914 | * will be called instead. | |
915 | * | |
916 | * If this request is answered with an error code of ENOSYS, the handler | |
917 | * is treated as not implemented (i.e., for this and future requests the | |
918 | * mknod() and open() handlers will be called instead). | |
919 | * | |
920 | * Valid replies: | |
921 | * fuse_reply_create | |
922 | * fuse_reply_err | |
923 | * | |
924 | * @param req request handle | |
925 | * @param parent inode number of the parent directory | |
926 | * @param name to create | |
927 | * @param mode file type and mode with which to create the new file | |
928 | * @param fi file information | |
929 | */ | |
930 | void (*create)(fuse_req_t req, fuse_ino_t parent, const char *name, | |
931 | mode_t mode, struct fuse_file_info *fi); | |
932 | ||
933 | /** | |
934 | * Test for a POSIX file lock | |
935 | * | |
936 | * Valid replies: | |
937 | * fuse_reply_lock | |
938 | * fuse_reply_err | |
939 | * | |
940 | * @param req request handle | |
941 | * @param ino the inode number | |
942 | * @param fi file information | |
943 | * @param lock the region/type to test | |
944 | */ | |
945 | void (*getlk)(fuse_req_t req, fuse_ino_t ino, struct fuse_file_info *fi, | |
946 | struct flock *lock); | |
947 | ||
948 | /** | |
949 | * Acquire, modify or release a POSIX file lock | |
950 | * | |
951 | * For POSIX threads (NPTL) there's a 1-1 relation between pid and | |
952 | * owner, but otherwise this is not always the case. For checking | |
953 | * lock ownership, 'fi->owner' must be used. The l_pid field in | |
954 | * 'struct flock' should only be used to fill in this field in | |
955 | * getlk(). | |
956 | * | |
957 | * Note: if the locking methods are not implemented, the kernel | |
958 | * will still allow file locking to work locally. Hence these are | |
959 | * only interesting for network filesystems and similar. | |
960 | * | |
961 | * Valid replies: | |
962 | * fuse_reply_err | |
963 | * | |
964 | * @param req request handle | |
965 | * @param ino the inode number | |
966 | * @param fi file information | |
967 | * @param lock the region/type to set | |
968 | * @param sleep locking operation may sleep | |
969 | */ | |
970 | void (*setlk)(fuse_req_t req, fuse_ino_t ino, struct fuse_file_info *fi, | |
971 | struct flock *lock, int sleep); | |
972 | ||
973 | /** | |
974 | * Map block index within file to block index within device | |
975 | * | |
976 | * Note: This makes sense only for block device backed filesystems | |
977 | * mounted with the 'blkdev' option | |
978 | * | |
979 | * If this request is answered with an error code of ENOSYS, this is | |
980 | * treated as a permanent failure, i.e. all future bmap() requests will | |
981 | * fail with the same error code without being send to the filesystem | |
982 | * process. | |
983 | * | |
984 | * Valid replies: | |
985 | * fuse_reply_bmap | |
986 | * fuse_reply_err | |
987 | * | |
988 | * @param req request handle | |
989 | * @param ino the inode number | |
990 | * @param blocksize unit of block index | |
991 | * @param idx block index within file | |
992 | */ | |
993 | void (*bmap)(fuse_req_t req, fuse_ino_t ino, size_t blocksize, | |
994 | uint64_t idx); | |
995 | ||
996 | /** | |
997 | * Ioctl | |
998 | * | |
999 | * Note: For unrestricted ioctls (not allowed for FUSE | |
1000 | * servers), data in and out areas can be discovered by giving | |
1001 | * iovs and setting FUSE_IOCTL_RETRY in *flags*. For | |
1002 | * restricted ioctls, kernel prepares in/out data area | |
1003 | * according to the information encoded in cmd. | |
1004 | * | |
1005 | * Valid replies: | |
1006 | * fuse_reply_ioctl_retry | |
1007 | * fuse_reply_ioctl | |
1008 | * fuse_reply_ioctl_iov | |
1009 | * fuse_reply_err | |
1010 | * | |
1011 | * @param req request handle | |
1012 | * @param ino the inode number | |
1013 | * @param cmd ioctl command | |
1014 | * @param arg ioctl argument | |
1015 | * @param fi file information | |
1016 | * @param flags for FUSE_IOCTL_* flags | |
1017 | * @param in_buf data fetched from the caller | |
1018 | * @param in_bufsz number of fetched bytes | |
1019 | * @param out_bufsz maximum size of output data | |
1020 | * | |
1021 | * Note : the unsigned long request submitted by the application | |
1022 | * is truncated to 32 bits. | |
1023 | */ | |
1024 | void (*ioctl)(fuse_req_t req, fuse_ino_t ino, unsigned int cmd, void *arg, | |
1025 | struct fuse_file_info *fi, unsigned flags, const void *in_buf, | |
1026 | size_t in_bufsz, size_t out_bufsz); | |
1027 | ||
1028 | /** | |
1029 | * Poll for IO readiness | |
1030 | * | |
1031 | * Note: If ph is non-NULL, the client should notify | |
1032 | * when IO readiness events occur by calling | |
1033 | * fuse_lowlevel_notify_poll() with the specified ph. | |
1034 | * | |
1035 | * Regardless of the number of times poll with a non-NULL ph | |
1036 | * is received, single notification is enough to clear all. | |
1037 | * Notifying more times incurs overhead but doesn't harm | |
1038 | * correctness. | |
1039 | * | |
1040 | * The callee is responsible for destroying ph with | |
1041 | * fuse_pollhandle_destroy() when no longer in use. | |
1042 | * | |
1043 | * If this request is answered with an error code of ENOSYS, this is | |
1044 | * treated as success (with a kernel-defined default poll-mask) and | |
1045 | * future calls to pull() will succeed the same way without being send | |
1046 | * to the filesystem process. | |
1047 | * | |
1048 | * Valid replies: | |
1049 | * fuse_reply_poll | |
1050 | * fuse_reply_err | |
1051 | * | |
1052 | * @param req request handle | |
1053 | * @param ino the inode number | |
1054 | * @param fi file information | |
1055 | * @param ph poll handle to be used for notification | |
1056 | */ | |
1057 | void (*poll)(fuse_req_t req, fuse_ino_t ino, struct fuse_file_info *fi, | |
1058 | struct fuse_pollhandle *ph); | |
1059 | ||
1060 | /** | |
1061 | * Write data made available in a buffer | |
1062 | * | |
1063 | * This is a more generic version of the ->write() method. If | |
1064 | * FUSE_CAP_SPLICE_READ is set in fuse_conn_info.want and the | |
1065 | * kernel supports splicing from the fuse device, then the | |
1066 | * data will be made available in pipe for supporting zero | |
1067 | * copy data transfer. | |
1068 | * | |
1069 | * buf->count is guaranteed to be one (and thus buf->idx is | |
1070 | * always zero). The write_buf handler must ensure that | |
1071 | * bufv->off is correctly updated (reflecting the number of | |
1072 | * bytes read from bufv->buf[0]). | |
1073 | * | |
1074 | * Unless FUSE_CAP_HANDLE_KILLPRIV is disabled, this method is | |
1075 | * expected to reset the setuid and setgid bits. | |
1076 | * | |
1077 | * Valid replies: | |
1078 | * fuse_reply_write | |
1079 | * fuse_reply_err | |
1080 | * | |
1081 | * @param req request handle | |
1082 | * @param ino the inode number | |
1083 | * @param bufv buffer containing the data | |
1084 | * @param off offset to write to | |
1085 | * @param fi file information | |
1086 | */ | |
1087 | void (*write_buf)(fuse_req_t req, fuse_ino_t ino, struct fuse_bufvec *bufv, | |
1088 | off_t off, struct fuse_file_info *fi); | |
1089 | ||
7387863d DDAG |
1090 | /** |
1091 | * Forget about multiple inodes | |
1092 | * | |
1093 | * See description of the forget function for more | |
1094 | * information. | |
1095 | * | |
1096 | * Valid replies: | |
1097 | * fuse_reply_none | |
1098 | * | |
1099 | * @param req request handle | |
1100 | */ | |
1101 | void (*forget_multi)(fuse_req_t req, size_t count, | |
1102 | struct fuse_forget_data *forgets); | |
1103 | ||
1104 | /** | |
1105 | * Acquire, modify or release a BSD file lock | |
1106 | * | |
1107 | * Note: if the locking methods are not implemented, the kernel | |
1108 | * will still allow file locking to work locally. Hence these are | |
1109 | * only interesting for network filesystems and similar. | |
1110 | * | |
1111 | * Valid replies: | |
1112 | * fuse_reply_err | |
1113 | * | |
1114 | * @param req request handle | |
1115 | * @param ino the inode number | |
1116 | * @param fi file information | |
1117 | * @param op the locking operation, see flock(2) | |
1118 | */ | |
1119 | void (*flock)(fuse_req_t req, fuse_ino_t ino, struct fuse_file_info *fi, | |
1120 | int op); | |
1121 | ||
1122 | /** | |
1123 | * Allocate requested space. If this function returns success then | |
1124 | * subsequent writes to the specified range shall not fail due to the lack | |
1125 | * of free space on the file system storage media. | |
1126 | * | |
1127 | * If this request is answered with an error code of ENOSYS, this is | |
1128 | * treated as a permanent failure with error code EOPNOTSUPP, i.e. all | |
1129 | * future fallocate() requests will fail with EOPNOTSUPP without being | |
1130 | * send to the filesystem process. | |
1131 | * | |
1132 | * Valid replies: | |
1133 | * fuse_reply_err | |
1134 | * | |
1135 | * @param req request handle | |
1136 | * @param ino the inode number | |
1137 | * @param offset starting point for allocated region | |
1138 | * @param length size of allocated region | |
1139 | * @param mode determines the operation to be performed on the given range, | |
1140 | * see fallocate(2) | |
1141 | */ | |
1142 | void (*fallocate)(fuse_req_t req, fuse_ino_t ino, int mode, off_t offset, | |
1143 | off_t length, struct fuse_file_info *fi); | |
1144 | ||
1145 | /** | |
1146 | * Read directory with attributes | |
1147 | * | |
1148 | * Send a buffer filled using fuse_add_direntry_plus(), with size not | |
1149 | * exceeding the requested size. Send an empty buffer on end of | |
1150 | * stream. | |
1151 | * | |
1152 | * fi->fh will contain the value set by the opendir method, or | |
1153 | * will be undefined if the opendir method didn't set any value. | |
1154 | * | |
1155 | * In contrast to readdir() (which does not affect the lookup counts), | |
1156 | * the lookup count of every entry returned by readdirplus(), except "." | |
1157 | * and "..", is incremented by one. | |
1158 | * | |
1159 | * Valid replies: | |
1160 | * fuse_reply_buf | |
1161 | * fuse_reply_data | |
1162 | * fuse_reply_err | |
1163 | * | |
1164 | * @param req request handle | |
1165 | * @param ino the inode number | |
1166 | * @param size maximum number of bytes to send | |
1167 | * @param off offset to continue reading the directory stream | |
1168 | * @param fi file information | |
1169 | */ | |
1170 | void (*readdirplus)(fuse_req_t req, fuse_ino_t ino, size_t size, off_t off, | |
1171 | struct fuse_file_info *fi); | |
1172 | ||
1173 | /** | |
1174 | * Copy a range of data from one file to another | |
1175 | * | |
1176 | * Performs an optimized copy between two file descriptors without the | |
1177 | * additional cost of transferring data through the FUSE kernel module | |
1178 | * to user space (glibc) and then back into the FUSE filesystem again. | |
1179 | * | |
1180 | * In case this method is not implemented, glibc falls back to reading | |
1181 | * data from the source and writing to the destination. Effectively | |
1182 | * doing an inefficient copy of the data. | |
1183 | * | |
1184 | * If this request is answered with an error code of ENOSYS, this is | |
1185 | * treated as a permanent failure with error code EOPNOTSUPP, i.e. all | |
1186 | * future copy_file_range() requests will fail with EOPNOTSUPP without | |
1187 | * being send to the filesystem process. | |
1188 | * | |
1189 | * Valid replies: | |
1190 | * fuse_reply_write | |
1191 | * fuse_reply_err | |
1192 | * | |
1193 | * @param req request handle | |
1194 | * @param ino_in the inode number or the source file | |
1195 | * @param off_in starting point from were the data should be read | |
1196 | * @param fi_in file information of the source file | |
1197 | * @param ino_out the inode number or the destination file | |
1198 | * @param off_out starting point where the data should be written | |
1199 | * @param fi_out file information of the destination file | |
1200 | * @param len maximum size of the data to copy | |
1201 | * @param flags passed along with the copy_file_range() syscall | |
1202 | */ | |
1203 | void (*copy_file_range)(fuse_req_t req, fuse_ino_t ino_in, off_t off_in, | |
1204 | struct fuse_file_info *fi_in, fuse_ino_t ino_out, | |
1205 | off_t off_out, struct fuse_file_info *fi_out, | |
1206 | size_t len, int flags); | |
1207 | ||
1208 | /** | |
1209 | * Find next data or hole after the specified offset | |
1210 | * | |
1211 | * If this request is answered with an error code of ENOSYS, this is | |
1212 | * treated as a permanent failure, i.e. all future lseek() requests will | |
1213 | * fail with the same error code without being send to the filesystem | |
1214 | * process. | |
1215 | * | |
1216 | * Valid replies: | |
1217 | * fuse_reply_lseek | |
1218 | * fuse_reply_err | |
1219 | * | |
1220 | * @param req request handle | |
1221 | * @param ino the inode number | |
1222 | * @param off offset to start search from | |
1223 | * @param whence either SEEK_DATA or SEEK_HOLE | |
1224 | * @param fi file information | |
1225 | */ | |
1226 | void (*lseek)(fuse_req_t req, fuse_ino_t ino, off_t off, int whence, | |
1227 | struct fuse_file_info *fi); | |
ee46c789 DDAG |
1228 | }; |
1229 | ||
1230 | /** | |
1231 | * Reply with an error code or success. | |
1232 | * | |
1233 | * Possible requests: | |
1234 | * all except forget | |
1235 | * | |
1236 | * Whereever possible, error codes should be chosen from the list of | |
1237 | * documented error conditions in the corresponding system calls | |
1238 | * manpage. | |
1239 | * | |
1240 | * An error code of ENOSYS is sometimes treated specially. This is | |
1241 | * indicated in the documentation of the affected handler functions. | |
1242 | * | |
1243 | * The following requests may be answered with a zero error code: | |
1244 | * unlink, rmdir, rename, flush, release, fsync, fsyncdir, setxattr, | |
1245 | * removexattr, setlk. | |
1246 | * | |
1247 | * @param req request handle | |
1248 | * @param err the positive error value, or zero for success | |
1249 | * @return zero for success, -errno for failure to send reply | |
1250 | */ | |
1251 | int fuse_reply_err(fuse_req_t req, int err); | |
1252 | ||
1253 | /** | |
1254 | * Don't send reply | |
1255 | * | |
1256 | * Possible requests: | |
1257 | * forget | |
1258 | * forget_multi | |
1259 | * retrieve_reply | |
1260 | * | |
1261 | * @param req request handle | |
1262 | */ | |
1263 | void fuse_reply_none(fuse_req_t req); | |
1264 | ||
1265 | /** | |
1266 | * Reply with a directory entry | |
1267 | * | |
1268 | * Possible requests: | |
1269 | * lookup, mknod, mkdir, symlink, link | |
1270 | * | |
1271 | * Side effects: | |
1272 | * increments the lookup count on success | |
1273 | * | |
1274 | * @param req request handle | |
1275 | * @param e the entry parameters | |
1276 | * @return zero for success, -errno for failure to send reply | |
1277 | */ | |
1278 | int fuse_reply_entry(fuse_req_t req, const struct fuse_entry_param *e); | |
1279 | ||
1280 | /** | |
1281 | * Reply with a directory entry and open parameters | |
1282 | * | |
1283 | * currently the following members of 'fi' are used: | |
1284 | * fh, direct_io, keep_cache | |
1285 | * | |
1286 | * Possible requests: | |
1287 | * create | |
1288 | * | |
1289 | * Side effects: | |
1290 | * increments the lookup count on success | |
1291 | * | |
1292 | * @param req request handle | |
1293 | * @param e the entry parameters | |
1294 | * @param fi file information | |
1295 | * @return zero for success, -errno for failure to send reply | |
1296 | */ | |
1297 | int fuse_reply_create(fuse_req_t req, const struct fuse_entry_param *e, | |
7387863d | 1298 | const struct fuse_file_info *fi); |
ee46c789 DDAG |
1299 | |
1300 | /** | |
1301 | * Reply with attributes | |
1302 | * | |
1303 | * Possible requests: | |
1304 | * getattr, setattr | |
1305 | * | |
1306 | * @param req request handle | |
1307 | * @param attr the attributes | |
7387863d | 1308 | * @param attr_timeout validity timeout (in seconds) for the attributes |
ee46c789 DDAG |
1309 | * @return zero for success, -errno for failure to send reply |
1310 | */ | |
1311 | int fuse_reply_attr(fuse_req_t req, const struct stat *attr, | |
7387863d | 1312 | double attr_timeout); |
ee46c789 DDAG |
1313 | |
1314 | /** | |
1315 | * Reply with the contents of a symbolic link | |
1316 | * | |
1317 | * Possible requests: | |
1318 | * readlink | |
1319 | * | |
1320 | * @param req request handle | |
1321 | * @param link symbolic link contents | |
1322 | * @return zero for success, -errno for failure to send reply | |
1323 | */ | |
1324 | int fuse_reply_readlink(fuse_req_t req, const char *link); | |
1325 | ||
1326 | /** | |
1327 | * Reply with open parameters | |
1328 | * | |
1329 | * currently the following members of 'fi' are used: | |
1330 | * fh, direct_io, keep_cache | |
1331 | * | |
1332 | * Possible requests: | |
1333 | * open, opendir | |
1334 | * | |
1335 | * @param req request handle | |
1336 | * @param fi file information | |
1337 | * @return zero for success, -errno for failure to send reply | |
1338 | */ | |
1339 | int fuse_reply_open(fuse_req_t req, const struct fuse_file_info *fi); | |
1340 | ||
1341 | /** | |
1342 | * Reply with number of bytes written | |
1343 | * | |
1344 | * Possible requests: | |
1345 | * write | |
1346 | * | |
1347 | * @param req request handle | |
1348 | * @param count the number of bytes written | |
1349 | * @return zero for success, -errno for failure to send reply | |
1350 | */ | |
1351 | int fuse_reply_write(fuse_req_t req, size_t count); | |
1352 | ||
1353 | /** | |
1354 | * Reply with data | |
1355 | * | |
1356 | * Possible requests: | |
1357 | * read, readdir, getxattr, listxattr | |
1358 | * | |
1359 | * @param req request handle | |
1360 | * @param buf buffer containing data | |
1361 | * @param size the size of data in bytes | |
1362 | * @return zero for success, -errno for failure to send reply | |
1363 | */ | |
1364 | int fuse_reply_buf(fuse_req_t req, const char *buf, size_t size); | |
1365 | ||
1366 | /** | |
1367 | * Reply with data copied/moved from buffer(s) | |
1368 | * | |
ee46c789 DDAG |
1369 | * Possible requests: |
1370 | * read, readdir, getxattr, listxattr | |
1371 | * | |
1372 | * Side effects: | |
1373 | * when used to return data from a readdirplus() (but not readdir()) | |
1374 | * call, increments the lookup count of each returned entry by one | |
1375 | * on success. | |
1376 | * | |
1377 | * @param req request handle | |
1378 | * @param bufv buffer vector | |
ee46c789 DDAG |
1379 | * @return zero for success, -errno for failure to send reply |
1380 | */ | |
8c3fe75e | 1381 | int fuse_reply_data(fuse_req_t req, struct fuse_bufvec *bufv); |
ee46c789 DDAG |
1382 | |
1383 | /** | |
1384 | * Reply with data vector | |
1385 | * | |
1386 | * Possible requests: | |
1387 | * read, readdir, getxattr, listxattr | |
1388 | * | |
1389 | * @param req request handle | |
1390 | * @param iov the vector containing the data | |
1391 | * @param count the size of vector | |
1392 | * @return zero for success, -errno for failure to send reply | |
1393 | */ | |
1394 | int fuse_reply_iov(fuse_req_t req, const struct iovec *iov, int count); | |
1395 | ||
1396 | /** | |
1397 | * Reply with filesystem statistics | |
1398 | * | |
1399 | * Possible requests: | |
1400 | * statfs | |
1401 | * | |
1402 | * @param req request handle | |
1403 | * @param stbuf filesystem statistics | |
1404 | * @return zero for success, -errno for failure to send reply | |
1405 | */ | |
1406 | int fuse_reply_statfs(fuse_req_t req, const struct statvfs *stbuf); | |
1407 | ||
1408 | /** | |
1409 | * Reply with needed buffer size | |
1410 | * | |
1411 | * Possible requests: | |
1412 | * getxattr, listxattr | |
1413 | * | |
1414 | * @param req request handle | |
1415 | * @param count the buffer size needed in bytes | |
1416 | * @return zero for success, -errno for failure to send reply | |
1417 | */ | |
1418 | int fuse_reply_xattr(fuse_req_t req, size_t count); | |
1419 | ||
1420 | /** | |
1421 | * Reply with file lock information | |
1422 | * | |
1423 | * Possible requests: | |
1424 | * getlk | |
1425 | * | |
1426 | * @param req request handle | |
1427 | * @param lock the lock information | |
1428 | * @return zero for success, -errno for failure to send reply | |
1429 | */ | |
1430 | int fuse_reply_lock(fuse_req_t req, const struct flock *lock); | |
1431 | ||
1432 | /** | |
1433 | * Reply with block index | |
1434 | * | |
1435 | * Possible requests: | |
1436 | * bmap | |
1437 | * | |
1438 | * @param req request handle | |
1439 | * @param idx block index within device | |
1440 | * @return zero for success, -errno for failure to send reply | |
1441 | */ | |
1442 | int fuse_reply_bmap(fuse_req_t req, uint64_t idx); | |
1443 | ||
7387863d DDAG |
1444 | /* |
1445 | * Filling a buffer in readdir | |
1446 | */ | |
ee46c789 DDAG |
1447 | |
1448 | /** | |
1449 | * Add a directory entry to the buffer | |
1450 | * | |
1451 | * Buffer needs to be large enough to hold the entry. If it's not, | |
1452 | * then the entry is not filled in but the size of the entry is still | |
1453 | * returned. The caller can check this by comparing the bufsize | |
1454 | * parameter with the returned entry size. If the entry size is | |
1455 | * larger than the buffer size, the operation failed. | |
1456 | * | |
1457 | * From the 'stbuf' argument the st_ino field and bits 12-15 of the | |
1458 | * st_mode field are used. The other fields are ignored. | |
1459 | * | |
1460 | * *off* should be any non-zero value that the filesystem can use to | |
1461 | * identify the current point in the directory stream. It does not | |
1462 | * need to be the actual physical position. A value of zero is | |
1463 | * reserved to mean "from the beginning", and should therefore never | |
1464 | * be used (the first call to fuse_add_direntry should be passed the | |
1465 | * offset of the second directory entry). | |
1466 | * | |
1467 | * @param req request handle | |
1468 | * @param buf the point where the new entry will be added to the buffer | |
1469 | * @param bufsize remaining size of the buffer | |
1470 | * @param name the name of the entry | |
1471 | * @param stbuf the file attributes | |
1472 | * @param off the offset of the next entry | |
1473 | * @return the space needed for the entry | |
1474 | */ | |
1475 | size_t fuse_add_direntry(fuse_req_t req, char *buf, size_t bufsize, | |
7387863d | 1476 | const char *name, const struct stat *stbuf, off_t off); |
ee46c789 DDAG |
1477 | |
1478 | /** | |
1479 | * Add a directory entry to the buffer with the attributes | |
1480 | * | |
1481 | * See documentation of `fuse_add_direntry()` for more details. | |
1482 | * | |
1483 | * @param req request handle | |
1484 | * @param buf the point where the new entry will be added to the buffer | |
1485 | * @param bufsize remaining size of the buffer | |
1486 | * @param name the name of the entry | |
1487 | * @param e the directory entry | |
1488 | * @param off the offset of the next entry | |
1489 | * @return the space needed for the entry | |
1490 | */ | |
1491 | size_t fuse_add_direntry_plus(fuse_req_t req, char *buf, size_t bufsize, | |
7387863d DDAG |
1492 | const char *name, |
1493 | const struct fuse_entry_param *e, off_t off); | |
ee46c789 DDAG |
1494 | |
1495 | /** | |
1496 | * Reply to ask for data fetch and output buffer preparation. ioctl | |
1497 | * will be retried with the specified input data fetched and output | |
1498 | * buffer prepared. | |
1499 | * | |
1500 | * Possible requests: | |
1501 | * ioctl | |
1502 | * | |
1503 | * @param req request handle | |
1504 | * @param in_iov iovec specifying data to fetch from the caller | |
1505 | * @param in_count number of entries in in_iov | |
1506 | * @param out_iov iovec specifying addresses to write output to | |
1507 | * @param out_count number of entries in out_iov | |
1508 | * @return zero for success, -errno for failure to send reply | |
1509 | */ | |
7387863d DDAG |
1510 | int fuse_reply_ioctl_retry(fuse_req_t req, const struct iovec *in_iov, |
1511 | size_t in_count, const struct iovec *out_iov, | |
1512 | size_t out_count); | |
ee46c789 DDAG |
1513 | |
1514 | /** | |
1515 | * Reply to finish ioctl | |
1516 | * | |
1517 | * Possible requests: | |
1518 | * ioctl | |
1519 | * | |
1520 | * @param req request handle | |
1521 | * @param result result to be passed to the caller | |
1522 | * @param buf buffer containing output data | |
1523 | * @param size length of output data | |
1524 | */ | |
1525 | int fuse_reply_ioctl(fuse_req_t req, int result, const void *buf, size_t size); | |
1526 | ||
1527 | /** | |
1528 | * Reply to finish ioctl with iov buffer | |
1529 | * | |
1530 | * Possible requests: | |
1531 | * ioctl | |
1532 | * | |
1533 | * @param req request handle | |
1534 | * @param result result to be passed to the caller | |
1535 | * @param iov the vector containing the data | |
1536 | * @param count the size of vector | |
1537 | */ | |
1538 | int fuse_reply_ioctl_iov(fuse_req_t req, int result, const struct iovec *iov, | |
7387863d | 1539 | int count); |
ee46c789 DDAG |
1540 | |
1541 | /** | |
1542 | * Reply with poll result event mask | |
1543 | * | |
1544 | * @param req request handle | |
1545 | * @param revents poll result event mask | |
1546 | */ | |
1547 | int fuse_reply_poll(fuse_req_t req, unsigned revents); | |
1548 | ||
1549 | /** | |
1550 | * Reply with offset | |
1551 | * | |
1552 | * Possible requests: | |
1553 | * lseek | |
1554 | * | |
1555 | * @param req request handle | |
1556 | * @param off offset of next data or hole | |
1557 | * @return zero for success, -errno for failure to send reply | |
1558 | */ | |
1559 | int fuse_reply_lseek(fuse_req_t req, off_t off); | |
1560 | ||
7387863d DDAG |
1561 | /* |
1562 | * Notification | |
1563 | */ | |
ee46c789 DDAG |
1564 | |
1565 | /** | |
1566 | * Notify IO readiness event | |
1567 | * | |
1568 | * For more information, please read comment for poll operation. | |
1569 | * | |
1570 | * @param ph poll handle to notify IO readiness event for | |
1571 | */ | |
1572 | int fuse_lowlevel_notify_poll(struct fuse_pollhandle *ph); | |
1573 | ||
1574 | /** | |
1575 | * Notify to invalidate cache for an inode. | |
1576 | * | |
1577 | * Added in FUSE protocol version 7.12. If the kernel does not support | |
1578 | * this (or a newer) version, the function will return -ENOSYS and do | |
1579 | * nothing. | |
1580 | * | |
1581 | * If the filesystem has writeback caching enabled, invalidating an | |
1582 | * inode will first trigger a writeback of all dirty pages. The call | |
1583 | * will block until all writeback requests have completed and the | |
1584 | * inode has been invalidated. It will, however, not wait for | |
1585 | * completion of pending writeback requests that have been issued | |
1586 | * before. | |
1587 | * | |
1588 | * If there are no dirty pages, this function will never block. | |
1589 | * | |
1590 | * @param se the session object | |
1591 | * @param ino the inode number | |
1592 | * @param off the offset in the inode where to start invalidating | |
1593 | * or negative to invalidate attributes only | |
1594 | * @param len the amount of cache to invalidate or 0 for all | |
1595 | * @return zero for success, -errno for failure | |
1596 | */ | |
1597 | int fuse_lowlevel_notify_inval_inode(struct fuse_session *se, fuse_ino_t ino, | |
7387863d | 1598 | off_t off, off_t len); |
ee46c789 DDAG |
1599 | |
1600 | /** | |
1601 | * Notify to invalidate parent attributes and the dentry matching | |
1602 | * parent/name | |
1603 | * | |
1604 | * To avoid a deadlock this function must not be called in the | |
1605 | * execution path of a related filesytem operation or within any code | |
1606 | * that could hold a lock that could be needed to execute such an | |
1607 | * operation. As of kernel 4.18, a "related operation" is a lookup(), | |
1608 | * symlink(), mknod(), mkdir(), unlink(), rename(), link() or create() | |
1609 | * request for the parent, and a setattr(), unlink(), rmdir(), | |
1610 | * rename(), setxattr(), removexattr(), readdir() or readdirplus() | |
1611 | * request for the inode itself. | |
1612 | * | |
1613 | * When called correctly, this function will never block. | |
1614 | * | |
1615 | * Added in FUSE protocol version 7.12. If the kernel does not support | |
1616 | * this (or a newer) version, the function will return -ENOSYS and do | |
1617 | * nothing. | |
1618 | * | |
1619 | * @param se the session object | |
1620 | * @param parent inode number | |
1621 | * @param name file name | |
1622 | * @param namelen strlen() of file name | |
1623 | * @return zero for success, -errno for failure | |
1624 | */ | |
1625 | int fuse_lowlevel_notify_inval_entry(struct fuse_session *se, fuse_ino_t parent, | |
7387863d | 1626 | const char *name, size_t namelen); |
ee46c789 DDAG |
1627 | |
1628 | /** | |
1629 | * This function behaves like fuse_lowlevel_notify_inval_entry() with | |
1630 | * the following additional effect (at least as of Linux kernel 4.8): | |
1631 | * | |
1632 | * If the provided *child* inode matches the inode that is currently | |
1633 | * associated with the cached dentry, and if there are any inotify | |
1634 | * watches registered for the dentry, then the watchers are informed | |
1635 | * that the dentry has been deleted. | |
1636 | * | |
1637 | * To avoid a deadlock this function must not be called while | |
1638 | * executing a related filesytem operation or while holding a lock | |
1639 | * that could be needed to execute such an operation (see the | |
1640 | * description of fuse_lowlevel_notify_inval_entry() for more | |
1641 | * details). | |
1642 | * | |
1643 | * When called correctly, this function will never block. | |
1644 | * | |
1645 | * Added in FUSE protocol version 7.18. If the kernel does not support | |
1646 | * this (or a newer) version, the function will return -ENOSYS and do | |
1647 | * nothing. | |
1648 | * | |
1649 | * @param se the session object | |
1650 | * @param parent inode number | |
1651 | * @param child inode number | |
1652 | * @param name file name | |
1653 | * @param namelen strlen() of file name | |
1654 | * @return zero for success, -errno for failure | |
1655 | */ | |
7387863d DDAG |
1656 | int fuse_lowlevel_notify_delete(struct fuse_session *se, fuse_ino_t parent, |
1657 | fuse_ino_t child, const char *name, | |
1658 | size_t namelen); | |
ee46c789 DDAG |
1659 | |
1660 | /** | |
1661 | * Store data to the kernel buffers | |
1662 | * | |
1663 | * Synchronously store data in the kernel buffers belonging to the | |
1664 | * given inode. The stored data is marked up-to-date (no read will be | |
1665 | * performed against it, unless it's invalidated or evicted from the | |
1666 | * cache). | |
1667 | * | |
1668 | * If the stored data overflows the current file size, then the size | |
1669 | * is extended, similarly to a write(2) on the filesystem. | |
1670 | * | |
1671 | * If this function returns an error, then the store wasn't fully | |
1672 | * completed, but it may have been partially completed. | |
1673 | * | |
1674 | * Added in FUSE protocol version 7.15. If the kernel does not support | |
1675 | * this (or a newer) version, the function will return -ENOSYS and do | |
1676 | * nothing. | |
1677 | * | |
1678 | * @param se the session object | |
1679 | * @param ino the inode number | |
1680 | * @param offset the starting offset into the file to store to | |
1681 | * @param bufv buffer vector | |
ee46c789 DDAG |
1682 | * @return zero for success, -errno for failure |
1683 | */ | |
1684 | int fuse_lowlevel_notify_store(struct fuse_session *se, fuse_ino_t ino, | |
8c3fe75e | 1685 | off_t offset, struct fuse_bufvec *bufv); |
ee46c789 | 1686 | |
7387863d DDAG |
1687 | /* |
1688 | * Utility functions | |
1689 | */ | |
ee46c789 DDAG |
1690 | |
1691 | /** | |
1692 | * Get the userdata from the request | |
1693 | * | |
1694 | * @param req request handle | |
1695 | * @return the user data passed to fuse_session_new() | |
1696 | */ | |
1697 | void *fuse_req_userdata(fuse_req_t req); | |
1698 | ||
1699 | /** | |
1700 | * Get the context from the request | |
1701 | * | |
1702 | * The pointer returned by this function will only be valid for the | |
1703 | * request's lifetime | |
1704 | * | |
1705 | * @param req request handle | |
1706 | * @return the context structure | |
1707 | */ | |
1708 | const struct fuse_ctx *fuse_req_ctx(fuse_req_t req); | |
1709 | ||
ee46c789 DDAG |
1710 | /** |
1711 | * Callback function for an interrupt | |
1712 | * | |
1713 | * @param req interrupted request | |
1714 | * @param data user data | |
1715 | */ | |
1716 | typedef void (*fuse_interrupt_func_t)(fuse_req_t req, void *data); | |
1717 | ||
1718 | /** | |
1719 | * Register/unregister callback for an interrupt | |
1720 | * | |
1721 | * If an interrupt has already happened, then the callback function is | |
1722 | * called from within this function, hence it's not possible for | |
1723 | * interrupts to be lost. | |
1724 | * | |
1725 | * @param req request handle | |
1726 | * @param func the callback function or NULL for unregister | |
1727 | * @param data user data passed to the callback function | |
1728 | */ | |
1729 | void fuse_req_interrupt_func(fuse_req_t req, fuse_interrupt_func_t func, | |
7387863d | 1730 | void *data); |
ee46c789 DDAG |
1731 | |
1732 | /** | |
1733 | * Check if a request has already been interrupted | |
1734 | * | |
1735 | * @param req request handle | |
1736 | * @return 1 if the request has been interrupted, 0 otherwise | |
1737 | */ | |
1738 | int fuse_req_interrupted(fuse_req_t req); | |
1739 | ||
f6f3573c DDAG |
1740 | /** |
1741 | * Check if the session is connected via virtio | |
1742 | * | |
1743 | * @param se session object | |
1744 | * @return 1 if the session is a virtio session | |
1745 | */ | |
1746 | int fuse_lowlevel_is_virtio(struct fuse_session *se); | |
ee46c789 | 1747 | |
7387863d DDAG |
1748 | /* |
1749 | * Inquiry functions | |
1750 | */ | |
ee46c789 DDAG |
1751 | |
1752 | /** | |
1753 | * Print low-level version information to stdout. | |
1754 | */ | |
1755 | void fuse_lowlevel_version(void); | |
1756 | ||
1757 | /** | |
1758 | * Print available low-level options to stdout. This is not an | |
1759 | * exhaustive list, but includes only those options that may be of | |
1760 | * interest to an end-user of a file system. | |
1761 | */ | |
1762 | void fuse_lowlevel_help(void); | |
1763 | ||
1764 | /** | |
1765 | * Print available options for `fuse_parse_cmdline()`. | |
1766 | */ | |
1767 | void fuse_cmdline_help(void); | |
1768 | ||
7387863d DDAG |
1769 | /* |
1770 | * Filesystem setup & teardown | |
1771 | */ | |
ee46c789 DDAG |
1772 | |
1773 | struct fuse_cmdline_opts { | |
7387863d DDAG |
1774 | int foreground; |
1775 | int debug; | |
1776 | int nodefault_subtype; | |
7387863d DDAG |
1777 | int show_version; |
1778 | int show_help; | |
45018fbb | 1779 | int print_capabilities; |
f185621d | 1780 | int syslog; |
d240314a | 1781 | int log_level; |
7387863d | 1782 | unsigned int max_idle_threads; |
6dbb7168 | 1783 | unsigned long rlimit_nofile; |
ee46c789 DDAG |
1784 | }; |
1785 | ||
1786 | /** | |
1787 | * Utility function to parse common options for simple file systems | |
1788 | * using the low-level API. A help text that describes the available | |
1789 | * options can be printed with `fuse_cmdline_help`. A single | |
1790 | * non-option argument is treated as the mountpoint. Multiple | |
1791 | * non-option arguments will result in an error. | |
1792 | * | |
1793 | * If neither -o subtype= or -o fsname= options are given, a new | |
1794 | * subtype option will be added and set to the basename of the program | |
1795 | * (the fsname will remain unset, and then defaults to "fuse"). | |
1796 | * | |
1797 | * Known options will be removed from *args*, unknown options will | |
1798 | * remain. | |
1799 | * | |
1800 | * @param args argument vector (input+output) | |
1801 | * @param opts output argument for parsed options | |
1802 | * @return 0 on success, -1 on failure | |
1803 | */ | |
7387863d | 1804 | int fuse_parse_cmdline(struct fuse_args *args, struct fuse_cmdline_opts *opts); |
ee46c789 DDAG |
1805 | |
1806 | /** | |
1807 | * Create a low level session. | |
1808 | * | |
1809 | * Returns a session structure suitable for passing to | |
1810 | * fuse_session_mount() and fuse_session_loop(). | |
1811 | * | |
1812 | * This function accepts most file-system independent mount options | |
1813 | * (like context, nodev, ro - see mount(8)), as well as the general | |
1814 | * fuse mount options listed in mount.fuse(8) (e.g. -o allow_root and | |
1815 | * -o default_permissions, but not ``-o use_ino``). Instead of `-o | |
1816 | * debug`, debugging may also enabled with `-d` or `--debug`. | |
1817 | * | |
1818 | * If not all options are known, an error message is written to stderr | |
1819 | * and the function returns NULL. | |
1820 | * | |
1821 | * Option parsing skips argv[0], which is assumed to contain the | |
1822 | * program name. To prevent accidentally passing an option in | |
1823 | * argv[0], this element must always be present (even if no options | |
1824 | * are specified). It may be set to the empty string ('\0') if no | |
1825 | * reasonable value can be provided. | |
1826 | * | |
1827 | * @param args argument vector | |
1828 | * @param op the (low-level) filesystem operations | |
1829 | * @param op_size sizeof(struct fuse_lowlevel_ops) | |
1830 | * @param userdata user data | |
1831 | * | |
1832 | * @return the fuse session on success, NULL on failure | |
1833 | **/ | |
1834 | struct fuse_session *fuse_session_new(struct fuse_args *args, | |
7387863d DDAG |
1835 | const struct fuse_lowlevel_ops *op, |
1836 | size_t op_size, void *userdata); | |
ee46c789 DDAG |
1837 | |
1838 | /** | |
1839 | * Mount a FUSE file system. | |
1840 | * | |
ee46c789 DDAG |
1841 | * @param se session object |
1842 | * | |
1843 | * @return 0 on success, -1 on failure. | |
1844 | **/ | |
67aab022 | 1845 | int fuse_session_mount(struct fuse_session *se); |
ee46c789 DDAG |
1846 | |
1847 | /** | |
1848 | * Enter a single threaded, blocking event loop. | |
1849 | * | |
1850 | * When the event loop terminates because the connection to the FUSE | |
1851 | * kernel module has been closed, this function returns zero. This | |
1852 | * happens when the filesystem is unmounted regularly (by the | |
1853 | * filesystem owner or root running the umount(8) or fusermount(1) | |
1854 | * command), or if connection is explicitly severed by writing ``1`` | |
1855 | * to the``abort`` file in ``/sys/fs/fuse/connections/NNN``. The only | |
1856 | * way to distinguish between these two conditions is to check if the | |
1857 | * filesystem is still mounted after the session loop returns. | |
1858 | * | |
1859 | * When some error occurs during request processing, the function | |
1860 | * returns a negated errno(3) value. | |
1861 | * | |
1862 | * If the loop has been terminated because of a signal handler | |
1863 | * installed by fuse_set_signal_handlers(), this function returns the | |
1864 | * (positive) signal value that triggered the exit. | |
1865 | * | |
1866 | * @param se the session | |
1867 | * @return 0, -errno, or a signal value | |
1868 | */ | |
1869 | int fuse_session_loop(struct fuse_session *se); | |
1870 | ||
ee46c789 DDAG |
1871 | /** |
1872 | * Flag a session as terminated. | |
1873 | * | |
1874 | * This function is invoked by the POSIX signal handlers, when | |
1875 | * registered using fuse_set_signal_handlers(). It will cause any | |
1876 | * running event loops to terminate on the next opportunity. | |
1877 | * | |
1878 | * @param se the session | |
1879 | */ | |
1880 | void fuse_session_exit(struct fuse_session *se); | |
1881 | ||
1882 | /** | |
1883 | * Reset the terminated flag of a session | |
1884 | * | |
1885 | * @param se the session | |
1886 | */ | |
1887 | void fuse_session_reset(struct fuse_session *se); | |
1888 | ||
1889 | /** | |
1890 | * Query the terminated flag of a session | |
1891 | * | |
1892 | * @param se the session | |
1893 | * @return 1 if exited, 0 if not exited | |
1894 | */ | |
1895 | int fuse_session_exited(struct fuse_session *se); | |
1896 | ||
1897 | /** | |
1898 | * Ensure that file system is unmounted. | |
1899 | * | |
1900 | * In regular operation, the file system is typically unmounted by the | |
1901 | * user calling umount(8) or fusermount(1), which then terminates the | |
1902 | * FUSE session loop. However, the session loop may also terminate as | |
1903 | * a result of an explicit call to fuse_session_exit() (e.g. by a | |
1904 | * signal handler installed by fuse_set_signal_handler()). In this | |
1905 | * case the filesystem remains mounted, but any attempt to access it | |
1906 | * will block (while the filesystem process is still running) or give | |
1907 | * an ESHUTDOWN error (after the filesystem process has terminated). | |
1908 | * | |
1909 | * If the communication channel with the FUSE kernel module is still | |
1910 | * open (i.e., if the session loop was terminated by an explicit call | |
1911 | * to fuse_session_exit()), this function will close it and unmount | |
1912 | * the filesystem. If the communication channel has been closed by the | |
1913 | * kernel, this method will do (almost) nothing. | |
1914 | * | |
1915 | * NOTE: The above semantics mean that if the connection to the kernel | |
1916 | * is terminated via the ``/sys/fs/fuse/connections/NNN/abort`` file, | |
1917 | * this method will *not* unmount the filesystem. | |
1918 | * | |
1919 | * @param se the session | |
1920 | */ | |
1921 | void fuse_session_unmount(struct fuse_session *se); | |
1922 | ||
1923 | /** | |
1924 | * Destroy a session | |
1925 | * | |
1926 | * @param se the session | |
1927 | */ | |
1928 | void fuse_session_destroy(struct fuse_session *se); | |
1929 | ||
7387863d DDAG |
1930 | /* |
1931 | * Custom event loop support | |
1932 | */ | |
ee46c789 DDAG |
1933 | |
1934 | /** | |
1935 | * Return file descriptor for communication with kernel. | |
1936 | * | |
1937 | * The file selector can be used to integrate FUSE with a custom event | |
1938 | * loop. Whenever data is available for reading on the provided fd, | |
1939 | * the event loop should call `fuse_session_receive_buf` followed by | |
1940 | * `fuse_session_process_buf` to process the request. | |
1941 | * | |
1942 | * The returned file descriptor is valid until `fuse_session_unmount` | |
1943 | * is called. | |
1944 | * | |
1945 | * @param se the session | |
1946 | * @return a file descriptor | |
1947 | */ | |
1948 | int fuse_session_fd(struct fuse_session *se); | |
1949 | ||
1950 | /** | |
1951 | * Process a raw request supplied in a generic buffer | |
1952 | * | |
1953 | * The fuse_buf may contain a memory buffer or a pipe file descriptor. | |
1954 | * | |
1955 | * @param se the session | |
1956 | * @param buf the fuse_buf containing the request | |
1957 | */ | |
1958 | void fuse_session_process_buf(struct fuse_session *se, | |
7387863d | 1959 | const struct fuse_buf *buf); |
ee46c789 DDAG |
1960 | |
1961 | /** | |
1962 | * Read a raw request from the kernel into the supplied buffer. | |
1963 | * | |
1964 | * Depending on file system options, system capabilities, and request | |
1965 | * size the request is either read into a memory buffer or spliced | |
1966 | * into a temporary pipe. | |
1967 | * | |
1968 | * @param se the session | |
1969 | * @param buf the fuse_buf to store the request in | |
1970 | * @return the actual size of the raw request, or -errno on error | |
1971 | */ | |
1972 | int fuse_session_receive_buf(struct fuse_session *se, struct fuse_buf *buf); | |
1973 | ||
ee46c789 | 1974 | #endif /* FUSE_LOWLEVEL_H_ */ |