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