Merge remote-tracking branch 'remotes/mst/tags/for_upstream' into staging
[qemu.git] / tools / virtiofsd / fuse_lowlevel.h
1 /*
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 */
8
9 #ifndef FUSE_LOWLEVEL_H_
10 #define FUSE_LOWLEVEL_H_
11
12 /**
13 * @file
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
28 #include <sys/statvfs.h>
29 #include <sys/uio.h>
30 #include <utime.h>
31
32 /*
33 * Miscellaneous definitions
34 */
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 {
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;
102
103 /**
104 * Flags for fuse_attr.flags that do not fit into attr.
105 */
106 uint32_t attr_flags;
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 {
118 /** User ID of the calling process */
119 uid_t uid;
120
121 /** Group ID of the calling process */
122 gid_t gid;
123
124 /** Thread ID of the calling process */
125 pid_t pid;
126
127 /** Umask of the calling process */
128 mode_t umask;
129 };
130
131 struct fuse_forget_data {
132 fuse_ino_t ino;
133 uint64_t nlookup;
134 };
135
136 /* 'to_set' flags in setattr */
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)
146 #define FUSE_SET_ATTR_KILL_SUIDGID (1 << 11)
147
148 /*
149 * Request methods and replies
150 */
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 {
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 uint32_t setxattr_flags);
803
804 /**
805 * Get an extended attribute
806 *
807 * If size is zero, the size of the value should be sent with
808 * fuse_reply_xattr.
809 *
810 * If the size is non-zero, and the value fits in the buffer, the
811 * value should be sent with fuse_reply_buf.
812 *
813 * If the size is too small for the value, the ERANGE error should
814 * be sent.
815 *
816 * If this request is answered with an error code of ENOSYS, this is
817 * treated as a permanent failure with error code EOPNOTSUPP, i.e. all
818 * future getxattr() requests will fail with EOPNOTSUPP without being
819 * send to the filesystem process.
820 *
821 * Valid replies:
822 * fuse_reply_buf
823 * fuse_reply_data
824 * fuse_reply_xattr
825 * fuse_reply_err
826 *
827 * @param req request handle
828 * @param ino the inode number
829 * @param name of the extended attribute
830 * @param size maximum size of the value to send
831 */
832 void (*getxattr)(fuse_req_t req, fuse_ino_t ino, const char *name,
833 size_t size);
834
835 /**
836 * List extended attribute names
837 *
838 * If size is zero, the total size of the attribute list should be
839 * sent with fuse_reply_xattr.
840 *
841 * If the size is non-zero, and the null character separated
842 * attribute list fits in the buffer, the list should be sent with
843 * fuse_reply_buf.
844 *
845 * If the size is too small for the list, the ERANGE error should
846 * be sent.
847 *
848 * If this request is answered with an error code of ENOSYS, this is
849 * treated as a permanent failure with error code EOPNOTSUPP, i.e. all
850 * future listxattr() requests will fail with EOPNOTSUPP without being
851 * send to the filesystem process.
852 *
853 * Valid replies:
854 * fuse_reply_buf
855 * fuse_reply_data
856 * fuse_reply_xattr
857 * fuse_reply_err
858 *
859 * @param req request handle
860 * @param ino the inode number
861 * @param size maximum size of the list to send
862 */
863 void (*listxattr)(fuse_req_t req, fuse_ino_t ino, size_t size);
864
865 /**
866 * Remove an extended attribute
867 *
868 * If this request is answered with an error code of ENOSYS, this is
869 * treated as a permanent failure with error code EOPNOTSUPP, i.e. all
870 * future removexattr() requests will fail with EOPNOTSUPP without being
871 * send to the filesystem process.
872 *
873 * Valid replies:
874 * fuse_reply_err
875 *
876 * @param req request handle
877 * @param ino the inode number
878 * @param name of the extended attribute
879 */
880 void (*removexattr)(fuse_req_t req, fuse_ino_t ino, const char *name);
881
882 /**
883 * Check file access permissions
884 *
885 * This will be called for the access() and chdir() system
886 * calls. If the 'default_permissions' mount option is given,
887 * this method is not called.
888 *
889 * This method is not called under Linux kernel versions 2.4.x
890 *
891 * If this request is answered with an error code of ENOSYS, this is
892 * treated as a permanent success, i.e. this and all future access()
893 * requests will succeed without being send to the filesystem process.
894 *
895 * Valid replies:
896 * fuse_reply_err
897 *
898 * @param req request handle
899 * @param ino the inode number
900 * @param mask requested access mode
901 */
902 void (*access)(fuse_req_t req, fuse_ino_t ino, int mask);
903
904 /**
905 * Create and open a file
906 *
907 * If the file does not exist, first create it with the specified
908 * mode, and then open it.
909 *
910 * See the description of the open handler for more
911 * information.
912 *
913 * If this method is not implemented or under Linux kernel
914 * versions earlier than 2.6.15, the mknod() and open() methods
915 * will be called instead.
916 *
917 * If this request is answered with an error code of ENOSYS, the handler
918 * is treated as not implemented (i.e., for this and future requests the
919 * mknod() and open() handlers will be called instead).
920 *
921 * Valid replies:
922 * fuse_reply_create
923 * fuse_reply_err
924 *
925 * @param req request handle
926 * @param parent inode number of the parent directory
927 * @param name to create
928 * @param mode file type and mode with which to create the new file
929 * @param fi file information
930 */
931 void (*create)(fuse_req_t req, fuse_ino_t parent, const char *name,
932 mode_t mode, struct fuse_file_info *fi);
933
934 /**
935 * Test for a POSIX file lock
936 *
937 * Valid replies:
938 * fuse_reply_lock
939 * fuse_reply_err
940 *
941 * @param req request handle
942 * @param ino the inode number
943 * @param fi file information
944 * @param lock the region/type to test
945 */
946 void (*getlk)(fuse_req_t req, fuse_ino_t ino, struct fuse_file_info *fi,
947 struct flock *lock);
948
949 /**
950 * Acquire, modify or release a POSIX file lock
951 *
952 * For POSIX threads (NPTL) there's a 1-1 relation between pid and
953 * owner, but otherwise this is not always the case. For checking
954 * lock ownership, 'fi->owner' must be used. The l_pid field in
955 * 'struct flock' should only be used to fill in this field in
956 * getlk().
957 *
958 * Note: if the locking methods are not implemented, the kernel
959 * will still allow file locking to work locally. Hence these are
960 * only interesting for network filesystems and similar.
961 *
962 * Valid replies:
963 * fuse_reply_err
964 *
965 * @param req request handle
966 * @param ino the inode number
967 * @param fi file information
968 * @param lock the region/type to set
969 * @param sleep locking operation may sleep
970 */
971 void (*setlk)(fuse_req_t req, fuse_ino_t ino, struct fuse_file_info *fi,
972 struct flock *lock, int sleep);
973
974 /**
975 * Map block index within file to block index within device
976 *
977 * Note: This makes sense only for block device backed filesystems
978 * mounted with the 'blkdev' option
979 *
980 * If this request is answered with an error code of ENOSYS, this is
981 * treated as a permanent failure, i.e. all future bmap() requests will
982 * fail with the same error code without being send to the filesystem
983 * process.
984 *
985 * Valid replies:
986 * fuse_reply_bmap
987 * fuse_reply_err
988 *
989 * @param req request handle
990 * @param ino the inode number
991 * @param blocksize unit of block index
992 * @param idx block index within file
993 */
994 void (*bmap)(fuse_req_t req, fuse_ino_t ino, size_t blocksize,
995 uint64_t idx);
996
997 /**
998 * Ioctl
999 *
1000 * Note: For unrestricted ioctls (not allowed for FUSE
1001 * servers), data in and out areas can be discovered by giving
1002 * iovs and setting FUSE_IOCTL_RETRY in *flags*. For
1003 * restricted ioctls, kernel prepares in/out data area
1004 * according to the information encoded in cmd.
1005 *
1006 * Valid replies:
1007 * fuse_reply_ioctl_retry
1008 * fuse_reply_ioctl
1009 * fuse_reply_ioctl_iov
1010 * fuse_reply_err
1011 *
1012 * @param req request handle
1013 * @param ino the inode number
1014 * @param cmd ioctl command
1015 * @param arg ioctl argument
1016 * @param fi file information
1017 * @param flags for FUSE_IOCTL_* flags
1018 * @param in_buf data fetched from the caller
1019 * @param in_bufsz number of fetched bytes
1020 * @param out_bufsz maximum size of output data
1021 *
1022 * Note : the unsigned long request submitted by the application
1023 * is truncated to 32 bits.
1024 */
1025 void (*ioctl)(fuse_req_t req, fuse_ino_t ino, unsigned int cmd, void *arg,
1026 struct fuse_file_info *fi, unsigned flags, const void *in_buf,
1027 size_t in_bufsz, size_t out_bufsz);
1028
1029 /**
1030 * Poll for IO readiness
1031 *
1032 * Note: If ph is non-NULL, the client should notify
1033 * when IO readiness events occur by calling
1034 * fuse_lowlevel_notify_poll() with the specified ph.
1035 *
1036 * Regardless of the number of times poll with a non-NULL ph
1037 * is received, single notification is enough to clear all.
1038 * Notifying more times incurs overhead but doesn't harm
1039 * correctness.
1040 *
1041 * The callee is responsible for destroying ph with
1042 * fuse_pollhandle_destroy() when no longer in use.
1043 *
1044 * If this request is answered with an error code of ENOSYS, this is
1045 * treated as success (with a kernel-defined default poll-mask) and
1046 * future calls to pull() will succeed the same way without being send
1047 * to the filesystem process.
1048 *
1049 * Valid replies:
1050 * fuse_reply_poll
1051 * fuse_reply_err
1052 *
1053 * @param req request handle
1054 * @param ino the inode number
1055 * @param fi file information
1056 * @param ph poll handle to be used for notification
1057 */
1058 void (*poll)(fuse_req_t req, fuse_ino_t ino, struct fuse_file_info *fi,
1059 struct fuse_pollhandle *ph);
1060
1061 /**
1062 * Write data made available in a buffer
1063 *
1064 * This is a more generic version of the ->write() method. If
1065 * FUSE_CAP_SPLICE_READ is set in fuse_conn_info.want and the
1066 * kernel supports splicing from the fuse device, then the
1067 * data will be made available in pipe for supporting zero
1068 * copy data transfer.
1069 *
1070 * buf->count is guaranteed to be one (and thus buf->idx is
1071 * always zero). The write_buf handler must ensure that
1072 * bufv->off is correctly updated (reflecting the number of
1073 * bytes read from bufv->buf[0]).
1074 *
1075 * Unless FUSE_CAP_HANDLE_KILLPRIV is disabled, this method is
1076 * expected to reset the setuid and setgid bits.
1077 *
1078 * Valid replies:
1079 * fuse_reply_write
1080 * fuse_reply_err
1081 *
1082 * @param req request handle
1083 * @param ino the inode number
1084 * @param bufv buffer containing the data
1085 * @param off offset to write to
1086 * @param fi file information
1087 */
1088 void (*write_buf)(fuse_req_t req, fuse_ino_t ino, struct fuse_bufvec *bufv,
1089 off_t off, struct fuse_file_info *fi);
1090
1091 /**
1092 * Forget about multiple inodes
1093 *
1094 * See description of the forget function for more
1095 * information.
1096 *
1097 * Valid replies:
1098 * fuse_reply_none
1099 *
1100 * @param req request handle
1101 */
1102 void (*forget_multi)(fuse_req_t req, size_t count,
1103 struct fuse_forget_data *forgets);
1104
1105 /**
1106 * Acquire, modify or release a BSD file lock
1107 *
1108 * Note: if the locking methods are not implemented, the kernel
1109 * will still allow file locking to work locally. Hence these are
1110 * only interesting for network filesystems and similar.
1111 *
1112 * Valid replies:
1113 * fuse_reply_err
1114 *
1115 * @param req request handle
1116 * @param ino the inode number
1117 * @param fi file information
1118 * @param op the locking operation, see flock(2)
1119 */
1120 void (*flock)(fuse_req_t req, fuse_ino_t ino, struct fuse_file_info *fi,
1121 int op);
1122
1123 /**
1124 * Allocate requested space. If this function returns success then
1125 * subsequent writes to the specified range shall not fail due to the lack
1126 * of free space on the file system storage media.
1127 *
1128 * If this request is answered with an error code of ENOSYS, this is
1129 * treated as a permanent failure with error code EOPNOTSUPP, i.e. all
1130 * future fallocate() requests will fail with EOPNOTSUPP without being
1131 * send to the filesystem process.
1132 *
1133 * Valid replies:
1134 * fuse_reply_err
1135 *
1136 * @param req request handle
1137 * @param ino the inode number
1138 * @param offset starting point for allocated region
1139 * @param length size of allocated region
1140 * @param mode determines the operation to be performed on the given range,
1141 * see fallocate(2)
1142 */
1143 void (*fallocate)(fuse_req_t req, fuse_ino_t ino, int mode, off_t offset,
1144 off_t length, struct fuse_file_info *fi);
1145
1146 /**
1147 * Read directory with attributes
1148 *
1149 * Send a buffer filled using fuse_add_direntry_plus(), with size not
1150 * exceeding the requested size. Send an empty buffer on end of
1151 * stream.
1152 *
1153 * fi->fh will contain the value set by the opendir method, or
1154 * will be undefined if the opendir method didn't set any value.
1155 *
1156 * In contrast to readdir() (which does not affect the lookup counts),
1157 * the lookup count of every entry returned by readdirplus(), except "."
1158 * and "..", is incremented by one.
1159 *
1160 * Valid replies:
1161 * fuse_reply_buf
1162 * fuse_reply_data
1163 * fuse_reply_err
1164 *
1165 * @param req request handle
1166 * @param ino the inode number
1167 * @param size maximum number of bytes to send
1168 * @param off offset to continue reading the directory stream
1169 * @param fi file information
1170 */
1171 void (*readdirplus)(fuse_req_t req, fuse_ino_t ino, size_t size, off_t off,
1172 struct fuse_file_info *fi);
1173
1174 /**
1175 * Copy a range of data from one file to another
1176 *
1177 * Performs an optimized copy between two file descriptors without the
1178 * additional cost of transferring data through the FUSE kernel module
1179 * to user space (glibc) and then back into the FUSE filesystem again.
1180 *
1181 * In case this method is not implemented, glibc falls back to reading
1182 * data from the source and writing to the destination. Effectively
1183 * doing an inefficient copy of the data.
1184 *
1185 * If this request is answered with an error code of ENOSYS, this is
1186 * treated as a permanent failure with error code EOPNOTSUPP, i.e. all
1187 * future copy_file_range() requests will fail with EOPNOTSUPP without
1188 * being send to the filesystem process.
1189 *
1190 * Valid replies:
1191 * fuse_reply_write
1192 * fuse_reply_err
1193 *
1194 * @param req request handle
1195 * @param ino_in the inode number or the source file
1196 * @param off_in starting point from were the data should be read
1197 * @param fi_in file information of the source file
1198 * @param ino_out the inode number or the destination file
1199 * @param off_out starting point where the data should be written
1200 * @param fi_out file information of the destination file
1201 * @param len maximum size of the data to copy
1202 * @param flags passed along with the copy_file_range() syscall
1203 */
1204 void (*copy_file_range)(fuse_req_t req, fuse_ino_t ino_in, off_t off_in,
1205 struct fuse_file_info *fi_in, fuse_ino_t ino_out,
1206 off_t off_out, struct fuse_file_info *fi_out,
1207 size_t len, int flags);
1208
1209 /**
1210 * Find next data or hole after the specified offset
1211 *
1212 * If this request is answered with an error code of ENOSYS, this is
1213 * treated as a permanent failure, i.e. all future lseek() requests will
1214 * fail with the same error code without being send to the filesystem
1215 * process.
1216 *
1217 * Valid replies:
1218 * fuse_reply_lseek
1219 * fuse_reply_err
1220 *
1221 * @param req request handle
1222 * @param ino the inode number
1223 * @param off offset to start search from
1224 * @param whence either SEEK_DATA or SEEK_HOLE
1225 * @param fi file information
1226 */
1227 void (*lseek)(fuse_req_t req, fuse_ino_t ino, off_t off, int whence,
1228 struct fuse_file_info *fi);
1229 };
1230
1231 /**
1232 * Reply with an error code or success.
1233 *
1234 * Possible requests:
1235 * all except forget
1236 *
1237 * Whereever possible, error codes should be chosen from the list of
1238 * documented error conditions in the corresponding system calls
1239 * manpage.
1240 *
1241 * An error code of ENOSYS is sometimes treated specially. This is
1242 * indicated in the documentation of the affected handler functions.
1243 *
1244 * The following requests may be answered with a zero error code:
1245 * unlink, rmdir, rename, flush, release, fsync, fsyncdir, setxattr,
1246 * removexattr, setlk.
1247 *
1248 * @param req request handle
1249 * @param err the positive error value, or zero for success
1250 * @return zero for success, -errno for failure to send reply
1251 */
1252 int fuse_reply_err(fuse_req_t req, int err);
1253
1254 /**
1255 * Don't send reply
1256 *
1257 * Possible requests:
1258 * forget
1259 * forget_multi
1260 * retrieve_reply
1261 *
1262 * @param req request handle
1263 */
1264 void fuse_reply_none(fuse_req_t req);
1265
1266 /**
1267 * Reply with a directory entry
1268 *
1269 * Possible requests:
1270 * lookup, mknod, mkdir, symlink, link
1271 *
1272 * Side effects:
1273 * increments the lookup count on success
1274 *
1275 * @param req request handle
1276 * @param e the entry parameters
1277 * @return zero for success, -errno for failure to send reply
1278 */
1279 int fuse_reply_entry(fuse_req_t req, const struct fuse_entry_param *e);
1280
1281 /**
1282 * Reply with a directory entry and open parameters
1283 *
1284 * currently the following members of 'fi' are used:
1285 * fh, direct_io, keep_cache
1286 *
1287 * Possible requests:
1288 * create
1289 *
1290 * Side effects:
1291 * increments the lookup count on success
1292 *
1293 * @param req request handle
1294 * @param e the entry parameters
1295 * @param fi file information
1296 * @return zero for success, -errno for failure to send reply
1297 */
1298 int fuse_reply_create(fuse_req_t req, const struct fuse_entry_param *e,
1299 const struct fuse_file_info *fi);
1300
1301 /**
1302 * Reply with attributes
1303 *
1304 * Possible requests:
1305 * getattr, setattr
1306 *
1307 * @param req request handle
1308 * @param attr the attributes
1309 * @param attr_timeout validity timeout (in seconds) for the attributes
1310 * @return zero for success, -errno for failure to send reply
1311 */
1312 int fuse_reply_attr(fuse_req_t req, const struct stat *attr,
1313 double attr_timeout);
1314
1315 /**
1316 * Reply with the contents of a symbolic link
1317 *
1318 * Possible requests:
1319 * readlink
1320 *
1321 * @param req request handle
1322 * @param link symbolic link contents
1323 * @return zero for success, -errno for failure to send reply
1324 */
1325 int fuse_reply_readlink(fuse_req_t req, const char *link);
1326
1327 /**
1328 * Reply with open parameters
1329 *
1330 * currently the following members of 'fi' are used:
1331 * fh, direct_io, keep_cache
1332 *
1333 * Possible requests:
1334 * open, opendir
1335 *
1336 * @param req request handle
1337 * @param fi file information
1338 * @return zero for success, -errno for failure to send reply
1339 */
1340 int fuse_reply_open(fuse_req_t req, const struct fuse_file_info *fi);
1341
1342 /**
1343 * Reply with number of bytes written
1344 *
1345 * Possible requests:
1346 * write
1347 *
1348 * @param req request handle
1349 * @param count the number of bytes written
1350 * @return zero for success, -errno for failure to send reply
1351 */
1352 int fuse_reply_write(fuse_req_t req, size_t count);
1353
1354 /**
1355 * Reply with data
1356 *
1357 * Possible requests:
1358 * read, readdir, getxattr, listxattr
1359 *
1360 * @param req request handle
1361 * @param buf buffer containing data
1362 * @param size the size of data in bytes
1363 * @return zero for success, -errno for failure to send reply
1364 */
1365 int fuse_reply_buf(fuse_req_t req, const char *buf, size_t size);
1366
1367 /**
1368 * Reply with data copied/moved from buffer(s)
1369 *
1370 * Possible requests:
1371 * read, readdir, getxattr, listxattr
1372 *
1373 * Side effects:
1374 * when used to return data from a readdirplus() (but not readdir())
1375 * call, increments the lookup count of each returned entry by one
1376 * on success.
1377 *
1378 * @param req request handle
1379 * @param bufv buffer vector
1380 * @return zero for success, -errno for failure to send reply
1381 */
1382 int fuse_reply_data(fuse_req_t req, struct fuse_bufvec *bufv);
1383
1384 /**
1385 * Reply with data vector
1386 *
1387 * Possible requests:
1388 * read, readdir, getxattr, listxattr
1389 *
1390 * @param req request handle
1391 * @param iov the vector containing the data
1392 * @param count the size of vector
1393 * @return zero for success, -errno for failure to send reply
1394 */
1395 int fuse_reply_iov(fuse_req_t req, const struct iovec *iov, int count);
1396
1397 /**
1398 * Reply with filesystem statistics
1399 *
1400 * Possible requests:
1401 * statfs
1402 *
1403 * @param req request handle
1404 * @param stbuf filesystem statistics
1405 * @return zero for success, -errno for failure to send reply
1406 */
1407 int fuse_reply_statfs(fuse_req_t req, const struct statvfs *stbuf);
1408
1409 /**
1410 * Reply with needed buffer size
1411 *
1412 * Possible requests:
1413 * getxattr, listxattr
1414 *
1415 * @param req request handle
1416 * @param count the buffer size needed in bytes
1417 * @return zero for success, -errno for failure to send reply
1418 */
1419 int fuse_reply_xattr(fuse_req_t req, size_t count);
1420
1421 /**
1422 * Reply with file lock information
1423 *
1424 * Possible requests:
1425 * getlk
1426 *
1427 * @param req request handle
1428 * @param lock the lock information
1429 * @return zero for success, -errno for failure to send reply
1430 */
1431 int fuse_reply_lock(fuse_req_t req, const struct flock *lock);
1432
1433 /**
1434 * Reply with block index
1435 *
1436 * Possible requests:
1437 * bmap
1438 *
1439 * @param req request handle
1440 * @param idx block index within device
1441 * @return zero for success, -errno for failure to send reply
1442 */
1443 int fuse_reply_bmap(fuse_req_t req, uint64_t idx);
1444
1445 /*
1446 * Filling a buffer in readdir
1447 */
1448
1449 /**
1450 * Add a directory entry to the buffer
1451 *
1452 * Buffer needs to be large enough to hold the entry. If it's not,
1453 * then the entry is not filled in but the size of the entry is still
1454 * returned. The caller can check this by comparing the bufsize
1455 * parameter with the returned entry size. If the entry size is
1456 * larger than the buffer size, the operation failed.
1457 *
1458 * From the 'stbuf' argument the st_ino field and bits 12-15 of the
1459 * st_mode field are used. The other fields are ignored.
1460 *
1461 * *off* should be any non-zero value that the filesystem can use to
1462 * identify the current point in the directory stream. It does not
1463 * need to be the actual physical position. A value of zero is
1464 * reserved to mean "from the beginning", and should therefore never
1465 * be used (the first call to fuse_add_direntry should be passed the
1466 * offset of the second directory entry).
1467 *
1468 * @param req request handle
1469 * @param buf the point where the new entry will be added to the buffer
1470 * @param bufsize remaining size of the buffer
1471 * @param name the name of the entry
1472 * @param stbuf the file attributes
1473 * @param off the offset of the next entry
1474 * @return the space needed for the entry
1475 */
1476 size_t fuse_add_direntry(fuse_req_t req, char *buf, size_t bufsize,
1477 const char *name, const struct stat *stbuf, off_t off);
1478
1479 /**
1480 * Add a directory entry to the buffer with the attributes
1481 *
1482 * See documentation of `fuse_add_direntry()` for more details.
1483 *
1484 * @param req request handle
1485 * @param buf the point where the new entry will be added to the buffer
1486 * @param bufsize remaining size of the buffer
1487 * @param name the name of the entry
1488 * @param e the directory entry
1489 * @param off the offset of the next entry
1490 * @return the space needed for the entry
1491 */
1492 size_t fuse_add_direntry_plus(fuse_req_t req, char *buf, size_t bufsize,
1493 const char *name,
1494 const struct fuse_entry_param *e, off_t off);
1495
1496 /**
1497 * Reply to ask for data fetch and output buffer preparation. ioctl
1498 * will be retried with the specified input data fetched and output
1499 * buffer prepared.
1500 *
1501 * Possible requests:
1502 * ioctl
1503 *
1504 * @param req request handle
1505 * @param in_iov iovec specifying data to fetch from the caller
1506 * @param in_count number of entries in in_iov
1507 * @param out_iov iovec specifying addresses to write output to
1508 * @param out_count number of entries in out_iov
1509 * @return zero for success, -errno for failure to send reply
1510 */
1511 int fuse_reply_ioctl_retry(fuse_req_t req, const struct iovec *in_iov,
1512 size_t in_count, const struct iovec *out_iov,
1513 size_t out_count);
1514
1515 /**
1516 * Reply to finish ioctl
1517 *
1518 * Possible requests:
1519 * ioctl
1520 *
1521 * @param req request handle
1522 * @param result result to be passed to the caller
1523 * @param buf buffer containing output data
1524 * @param size length of output data
1525 */
1526 int fuse_reply_ioctl(fuse_req_t req, int result, const void *buf, size_t size);
1527
1528 /**
1529 * Reply to finish ioctl with iov buffer
1530 *
1531 * Possible requests:
1532 * ioctl
1533 *
1534 * @param req request handle
1535 * @param result result to be passed to the caller
1536 * @param iov the vector containing the data
1537 * @param count the size of vector
1538 */
1539 int fuse_reply_ioctl_iov(fuse_req_t req, int result, const struct iovec *iov,
1540 int count);
1541
1542 /**
1543 * Reply with poll result event mask
1544 *
1545 * @param req request handle
1546 * @param revents poll result event mask
1547 */
1548 int fuse_reply_poll(fuse_req_t req, unsigned revents);
1549
1550 /**
1551 * Reply with offset
1552 *
1553 * Possible requests:
1554 * lseek
1555 *
1556 * @param req request handle
1557 * @param off offset of next data or hole
1558 * @return zero for success, -errno for failure to send reply
1559 */
1560 int fuse_reply_lseek(fuse_req_t req, off_t off);
1561
1562 /*
1563 * Notification
1564 */
1565
1566 /**
1567 * Notify IO readiness event
1568 *
1569 * For more information, please read comment for poll operation.
1570 *
1571 * @param ph poll handle to notify IO readiness event for
1572 */
1573 int fuse_lowlevel_notify_poll(struct fuse_pollhandle *ph);
1574
1575 /**
1576 * Notify to invalidate cache for an inode.
1577 *
1578 * Added in FUSE protocol version 7.12. If the kernel does not support
1579 * this (or a newer) version, the function will return -ENOSYS and do
1580 * nothing.
1581 *
1582 * If the filesystem has writeback caching enabled, invalidating an
1583 * inode will first trigger a writeback of all dirty pages. The call
1584 * will block until all writeback requests have completed and the
1585 * inode has been invalidated. It will, however, not wait for
1586 * completion of pending writeback requests that have been issued
1587 * before.
1588 *
1589 * If there are no dirty pages, this function will never block.
1590 *
1591 * @param se the session object
1592 * @param ino the inode number
1593 * @param off the offset in the inode where to start invalidating
1594 * or negative to invalidate attributes only
1595 * @param len the amount of cache to invalidate or 0 for all
1596 * @return zero for success, -errno for failure
1597 */
1598 int fuse_lowlevel_notify_inval_inode(struct fuse_session *se, fuse_ino_t ino,
1599 off_t off, off_t len);
1600
1601 /**
1602 * Notify to invalidate parent attributes and the dentry matching
1603 * parent/name
1604 *
1605 * To avoid a deadlock this function must not be called in the
1606 * execution path of a related filesystem operation or within any code
1607 * that could hold a lock that could be needed to execute such an
1608 * operation. As of kernel 4.18, a "related operation" is a lookup(),
1609 * symlink(), mknod(), mkdir(), unlink(), rename(), link() or create()
1610 * request for the parent, and a setattr(), unlink(), rmdir(),
1611 * rename(), setxattr(), removexattr(), readdir() or readdirplus()
1612 * request for the inode itself.
1613 *
1614 * When called correctly, this function will never block.
1615 *
1616 * Added in FUSE protocol version 7.12. If the kernel does not support
1617 * this (or a newer) version, the function will return -ENOSYS and do
1618 * nothing.
1619 *
1620 * @param se the session object
1621 * @param parent inode number
1622 * @param name file name
1623 * @param namelen strlen() of file name
1624 * @return zero for success, -errno for failure
1625 */
1626 int fuse_lowlevel_notify_inval_entry(struct fuse_session *se, fuse_ino_t parent,
1627 const char *name, size_t namelen);
1628
1629 /**
1630 * This function behaves like fuse_lowlevel_notify_inval_entry() with
1631 * the following additional effect (at least as of Linux kernel 4.8):
1632 *
1633 * If the provided *child* inode matches the inode that is currently
1634 * associated with the cached dentry, and if there are any inotify
1635 * watches registered for the dentry, then the watchers are informed
1636 * that the dentry has been deleted.
1637 *
1638 * To avoid a deadlock this function must not be called while
1639 * executing a related filesystem operation or while holding a lock
1640 * that could be needed to execute such an operation (see the
1641 * description of fuse_lowlevel_notify_inval_entry() for more
1642 * details).
1643 *
1644 * When called correctly, this function will never block.
1645 *
1646 * Added in FUSE protocol version 7.18. If the kernel does not support
1647 * this (or a newer) version, the function will return -ENOSYS and do
1648 * nothing.
1649 *
1650 * @param se the session object
1651 * @param parent inode number
1652 * @param child inode number
1653 * @param name file name
1654 * @param namelen strlen() of file name
1655 * @return zero for success, -errno for failure
1656 */
1657 int fuse_lowlevel_notify_delete(struct fuse_session *se, fuse_ino_t parent,
1658 fuse_ino_t child, const char *name,
1659 size_t namelen);
1660
1661 /**
1662 * Store data to the kernel buffers
1663 *
1664 * Synchronously store data in the kernel buffers belonging to the
1665 * given inode. The stored data is marked up-to-date (no read will be
1666 * performed against it, unless it's invalidated or evicted from the
1667 * cache).
1668 *
1669 * If the stored data overflows the current file size, then the size
1670 * is extended, similarly to a write(2) on the filesystem.
1671 *
1672 * If this function returns an error, then the store wasn't fully
1673 * completed, but it may have been partially completed.
1674 *
1675 * Added in FUSE protocol version 7.15. If the kernel does not support
1676 * this (or a newer) version, the function will return -ENOSYS and do
1677 * nothing.
1678 *
1679 * @param se the session object
1680 * @param ino the inode number
1681 * @param offset the starting offset into the file to store to
1682 * @param bufv buffer vector
1683 * @return zero for success, -errno for failure
1684 */
1685 int fuse_lowlevel_notify_store(struct fuse_session *se, fuse_ino_t ino,
1686 off_t offset, struct fuse_bufvec *bufv);
1687
1688 /*
1689 * Utility functions
1690 */
1691
1692 /**
1693 * Get the userdata from the request
1694 *
1695 * @param req request handle
1696 * @return the user data passed to fuse_session_new()
1697 */
1698 void *fuse_req_userdata(fuse_req_t req);
1699
1700 /**
1701 * Get the context from the request
1702 *
1703 * The pointer returned by this function will only be valid for the
1704 * request's lifetime
1705 *
1706 * @param req request handle
1707 * @return the context structure
1708 */
1709 const struct fuse_ctx *fuse_req_ctx(fuse_req_t req);
1710
1711 /**
1712 * Callback function for an interrupt
1713 *
1714 * @param req interrupted request
1715 * @param data user data
1716 */
1717 typedef void (*fuse_interrupt_func_t)(fuse_req_t req, void *data);
1718
1719 /**
1720 * Register/unregister callback for an interrupt
1721 *
1722 * If an interrupt has already happened, then the callback function is
1723 * called from within this function, hence it's not possible for
1724 * interrupts to be lost.
1725 *
1726 * @param req request handle
1727 * @param func the callback function or NULL for unregister
1728 * @param data user data passed to the callback function
1729 */
1730 void fuse_req_interrupt_func(fuse_req_t req, fuse_interrupt_func_t func,
1731 void *data);
1732
1733 /**
1734 * Check if a request has already been interrupted
1735 *
1736 * @param req request handle
1737 * @return 1 if the request has been interrupted, 0 otherwise
1738 */
1739 int fuse_req_interrupted(fuse_req_t req);
1740
1741 /**
1742 * Check if the session is connected via virtio
1743 *
1744 * @param se session object
1745 * @return 1 if the session is a virtio session
1746 */
1747 int fuse_lowlevel_is_virtio(struct fuse_session *se);
1748
1749 /*
1750 * Inquiry functions
1751 */
1752
1753 /**
1754 * Print low-level version information to stdout.
1755 */
1756 void fuse_lowlevel_version(void);
1757
1758 /**
1759 * Print available low-level options to stdout. This is not an
1760 * exhaustive list, but includes only those options that may be of
1761 * interest to an end-user of a file system.
1762 */
1763 void fuse_lowlevel_help(void);
1764
1765 /**
1766 * Print available options for `fuse_parse_cmdline()`.
1767 */
1768 void fuse_cmdline_help(void);
1769
1770 /*
1771 * Filesystem setup & teardown
1772 */
1773
1774 struct fuse_cmdline_opts {
1775 int foreground;
1776 int debug;
1777 int nodefault_subtype;
1778 int show_version;
1779 int show_help;
1780 int print_capabilities;
1781 int syslog;
1782 int log_level;
1783 unsigned int max_idle_threads;
1784 unsigned long rlimit_nofile;
1785 };
1786
1787 /**
1788 * Utility function to parse common options for simple file systems
1789 * using the low-level API. A help text that describes the available
1790 * options can be printed with `fuse_cmdline_help`. A single
1791 * non-option argument is treated as the mountpoint. Multiple
1792 * non-option arguments will result in an error.
1793 *
1794 * If neither -o subtype= or -o fsname= options are given, a new
1795 * subtype option will be added and set to the basename of the program
1796 * (the fsname will remain unset, and then defaults to "fuse").
1797 *
1798 * Known options will be removed from *args*, unknown options will
1799 * remain.
1800 *
1801 * @param args argument vector (input+output)
1802 * @param opts output argument for parsed options
1803 * @return 0 on success, -1 on failure
1804 */
1805 int fuse_parse_cmdline(struct fuse_args *args, struct fuse_cmdline_opts *opts);
1806
1807 /**
1808 * Create a low level session.
1809 *
1810 * Returns a session structure suitable for passing to
1811 * fuse_session_mount() and fuse_session_loop().
1812 *
1813 * This function accepts most file-system independent mount options
1814 * (like context, nodev, ro - see mount(8)), as well as the general
1815 * fuse mount options listed in mount.fuse(8) (e.g. -o allow_root and
1816 * -o default_permissions, but not ``-o use_ino``). Instead of `-o
1817 * debug`, debugging may also enabled with `-d` or `--debug`.
1818 *
1819 * If not all options are known, an error message is written to stderr
1820 * and the function returns NULL.
1821 *
1822 * Option parsing skips argv[0], which is assumed to contain the
1823 * program name. To prevent accidentally passing an option in
1824 * argv[0], this element must always be present (even if no options
1825 * are specified). It may be set to the empty string ('\0') if no
1826 * reasonable value can be provided.
1827 *
1828 * @param args argument vector
1829 * @param op the (low-level) filesystem operations
1830 * @param op_size sizeof(struct fuse_lowlevel_ops)
1831 * @param userdata user data
1832 *
1833 * @return the fuse session on success, NULL on failure
1834 **/
1835 struct fuse_session *fuse_session_new(struct fuse_args *args,
1836 const struct fuse_lowlevel_ops *op,
1837 size_t op_size, void *userdata);
1838
1839 /**
1840 * Mount a FUSE file system.
1841 *
1842 * @param se session object
1843 *
1844 * @return 0 on success, -1 on failure.
1845 **/
1846 int fuse_session_mount(struct fuse_session *se);
1847
1848 /**
1849 * Enter a single threaded, blocking event loop.
1850 *
1851 * When the event loop terminates because the connection to the FUSE
1852 * kernel module has been closed, this function returns zero. This
1853 * happens when the filesystem is unmounted regularly (by the
1854 * filesystem owner or root running the umount(8) or fusermount(1)
1855 * command), or if connection is explicitly severed by writing ``1``
1856 * to the``abort`` file in ``/sys/fs/fuse/connections/NNN``. The only
1857 * way to distinguish between these two conditions is to check if the
1858 * filesystem is still mounted after the session loop returns.
1859 *
1860 * When some error occurs during request processing, the function
1861 * returns a negated errno(3) value.
1862 *
1863 * If the loop has been terminated because of a signal handler
1864 * installed by fuse_set_signal_handlers(), this function returns the
1865 * (positive) signal value that triggered the exit.
1866 *
1867 * @param se the session
1868 * @return 0, -errno, or a signal value
1869 */
1870 int fuse_session_loop(struct fuse_session *se);
1871
1872 /**
1873 * Flag a session as terminated.
1874 *
1875 * This function is invoked by the POSIX signal handlers, when
1876 * registered using fuse_set_signal_handlers(). It will cause any
1877 * running event loops to terminate on the next opportunity.
1878 *
1879 * @param se the session
1880 */
1881 void fuse_session_exit(struct fuse_session *se);
1882
1883 /**
1884 * Reset the terminated flag of a session
1885 *
1886 * @param se the session
1887 */
1888 void fuse_session_reset(struct fuse_session *se);
1889
1890 /**
1891 * Query the terminated flag of a session
1892 *
1893 * @param se the session
1894 * @return 1 if exited, 0 if not exited
1895 */
1896 int fuse_session_exited(struct fuse_session *se);
1897
1898 /**
1899 * Ensure that file system is unmounted.
1900 *
1901 * In regular operation, the file system is typically unmounted by the
1902 * user calling umount(8) or fusermount(1), which then terminates the
1903 * FUSE session loop. However, the session loop may also terminate as
1904 * a result of an explicit call to fuse_session_exit() (e.g. by a
1905 * signal handler installed by fuse_set_signal_handler()). In this
1906 * case the filesystem remains mounted, but any attempt to access it
1907 * will block (while the filesystem process is still running) or give
1908 * an ESHUTDOWN error (after the filesystem process has terminated).
1909 *
1910 * If the communication channel with the FUSE kernel module is still
1911 * open (i.e., if the session loop was terminated by an explicit call
1912 * to fuse_session_exit()), this function will close it and unmount
1913 * the filesystem. If the communication channel has been closed by the
1914 * kernel, this method will do (almost) nothing.
1915 *
1916 * NOTE: The above semantics mean that if the connection to the kernel
1917 * is terminated via the ``/sys/fs/fuse/connections/NNN/abort`` file,
1918 * this method will *not* unmount the filesystem.
1919 *
1920 * @param se the session
1921 */
1922 void fuse_session_unmount(struct fuse_session *se);
1923
1924 /**
1925 * Destroy a session
1926 *
1927 * @param se the session
1928 */
1929 void fuse_session_destroy(struct fuse_session *se);
1930
1931 /*
1932 * Custom event loop support
1933 */
1934
1935 /**
1936 * Return file descriptor for communication with kernel.
1937 *
1938 * The file selector can be used to integrate FUSE with a custom event
1939 * loop. Whenever data is available for reading on the provided fd,
1940 * the event loop should call `fuse_session_receive_buf` followed by
1941 * `fuse_session_process_buf` to process the request.
1942 *
1943 * The returned file descriptor is valid until `fuse_session_unmount`
1944 * is called.
1945 *
1946 * @param se the session
1947 * @return a file descriptor
1948 */
1949 int fuse_session_fd(struct fuse_session *se);
1950
1951 /**
1952 * Process a raw request supplied in a generic buffer
1953 *
1954 * The fuse_buf may contain a memory buffer or a pipe file descriptor.
1955 *
1956 * @param se the session
1957 * @param buf the fuse_buf containing the request
1958 */
1959 void fuse_session_process_buf(struct fuse_session *se,
1960 const struct fuse_buf *buf);
1961
1962 /**
1963 * Read a raw request from the kernel into the supplied buffer.
1964 *
1965 * Depending on file system options, system capabilities, and request
1966 * size the request is either read into a memory buffer or spliced
1967 * into a temporary pipe.
1968 *
1969 * @param se the session
1970 * @param buf the fuse_buf to store the request in
1971 * @return the actual size of the raw request, or -errno on error
1972 */
1973 int fuse_session_receive_buf(struct fuse_session *se, struct fuse_buf *buf);
1974
1975 #endif /* FUSE_LOWLEVEL_H_ */