1 /* FUSE: Filesystem in Userspace 2 Copyright (C) 2001-2007 Miklos Szeredi <[email protected]> 3 4 This program can be distributed under the terms of the GNU LGPLv2. 5 See the file COPYING.LIB. 6 */ 7 8 /** @file */ 9 10 #if !defined(FUSE_H_) && !defined(FUSE_LOWLEVEL_H_) 11 #error "Never include <fuse_common.h> directly; use <fuse.h> or <fuse_lowlevel.h> instead." 12 #endif 13 14 #ifndef FUSE_COMMON_H_ 15 #define FUSE_COMMON_H_ 16 17 #ifdef HAVE_LIBFUSE_PRIVATE_CONFIG_H 18 #include "fuse_config.h" 19 #endif 20 21 #include "libfuse_config.h" 22 23 #include "fuse_opt.h" 24 #include "fuse_log.h" 25 #include <stdint.h> 26 #include <sys/types.h> 27 28 #define FUSE_MAKE_VERSION(maj, min) ((maj) * 100 + (min)) 29 #define FUSE_VERSION FUSE_MAKE_VERSION(FUSE_MAJOR_VERSION, FUSE_MINOR_VERSION) 30 31 #ifdef __cplusplus 32 extern "C" { 33 #endif 34 35 /** 36 * Information about an open file. 37 * 38 * File Handles are created by the open, opendir, and create methods and closed 39 * by the release and releasedir methods. Multiple file handles may be 40 * concurrently open for the same file. Generally, a client will create one 41 * file handle per file descriptor, though in some cases multiple file 42 * descriptors can share a single file handle. 43 */ 44 struct fuse_file_info { 45 /** Open flags. Available in open(), release() and create() */ 46 int flags; 47 48 /** In case of a write operation indicates if this was caused 49 by a delayed write from the page cache. If so, then the 50 context's pid, uid, and gid fields will not be valid, and 51 the *fh* value may not match the *fh* value that would 52 have been sent with the corresponding individual write 53 requests if write caching had been disabled. */ 54 unsigned int writepage : 1; 55 56 /** Can be filled in by open/create, to use direct I/O on this file. */ 57 unsigned int direct_io : 1; 58 59 /** Can be filled in by open and opendir. It signals the kernel that any 60 currently cached data (ie., data that the filesystem provided the 61 last time the file/directory was open) need not be invalidated when 62 the file/directory is closed. */ 63 unsigned int keep_cache : 1; 64 65 /** Can be filled by open/create, to allow parallel direct writes on this 66 * file */ 67 unsigned int parallel_direct_writes : 1; 68 69 /** Indicates a flush operation. Set in flush operation, also 70 maybe set in highlevel lock operation and lowlevel release 71 operation. */ 72 unsigned int flush : 1; 73 74 /** Can be filled in by open, to indicate that the file is not 75 seekable. */ 76 unsigned int nonseekable : 1; 77 78 /* Indicates that flock locks for this file should be 79 released. If set, lock_owner shall contain a valid value. 80 May only be set in ->release(). */ 81 unsigned int flock_release : 1; 82 83 /** Can be filled in by opendir. It signals the kernel to 84 enable caching of entries returned by readdir(). Has no 85 effect when set in other contexts (in particular it does 86 nothing when set by open()). */ 87 unsigned int cache_readdir : 1; 88 89 /** Can be filled in by open, to indicate that flush is not needed 90 on close. */ 91 unsigned int noflush : 1; 92 93 /** Padding. Reserved for future use*/ 94 unsigned int padding : 23; 95 unsigned int padding2 : 32; 96 97 /** File handle id. May be filled in by filesystem in create, 98 * open, and opendir(). Available in most other file operations on the 99 * same file handle. */ 100 uint64_t fh; 101 102 /** Passthrough file handle id. May be filled in by filesystem in 103 * create and open. It is used to create a passthrough connection 104 * between FUSE file and lower file system file. */ 105 uint32_t passthrough_fh; 106 107 /** Lock owner id. Available in locking operations and flush */ 108 uint64_t lock_owner; 109 110 /** Requested poll events. Available in ->poll. Only set on kernels 111 which support it. If unsupported, this field is set to zero. */ 112 uint32_t poll_events; 113 114 /** Passthrough backing file id. May be filled in by filesystem in 115 * create and open. It is used to create a passthrough connection 116 * between FUSE file and backing file. */ 117 int32_t backing_id; 118 }; 119 120 121 122 /** 123 * Configuration parameters passed to fuse_session_loop_mt() and 124 * fuse_loop_mt(). 125 * Deprecated and replaced by a newer private struct in FUSE API 126 * version 312 (FUSE_MAKE_VERSION(3, 12) 127 */ 128 #if FUSE_USE_VERSION < FUSE_MAKE_VERSION(3, 12) 129 struct fuse_loop_config_v1; /* forward declarition */ 130 struct fuse_loop_config { 131 #else 132 struct fuse_loop_config_v1 { 133 #endif 134 /** 135 * whether to use separate device fds for each thread 136 * (may increase performance) 137 */ 138 int clone_fd; 139 140 /** 141 * The maximum number of available worker threads before they 142 * start to get deleted when they become idle. If not 143 * specified, the default is 10. 144 * 145 * Adjusting this has performance implications; a very small number 146 * of threads in the pool will cause a lot of thread creation and 147 * deletion overhead and performance may suffer. When set to 0, a new 148 * thread will be created to service every operation. 149 */ 150 unsigned int max_idle_threads; 151 }; 152 153 154 /************************************************************************** 155 * Capability bits for 'fuse_conn_info.capable' and 'fuse_conn_info.want' * 156 **************************************************************************/ 157 158 /** 159 * Indicates that the filesystem supports asynchronous read requests. 160 * 161 * If this capability is not requested/available, the kernel will 162 * ensure that there is at most one pending read request per 163 * file-handle at any time, and will attempt to order read requests by 164 * increasing offset. 165 * 166 * This feature is enabled by default when supported by the kernel. 167 */ 168 #define FUSE_CAP_ASYNC_READ (1 << 0) 169 170 /** 171 * Indicates that the filesystem supports "remote" locking. 172 * 173 * This feature is enabled by default when supported by the kernel, 174 * and if getlk() and setlk() handlers are implemented. 175 */ 176 #define FUSE_CAP_POSIX_LOCKS (1 << 1) 177 178 /** 179 * Indicates that the filesystem supports the O_TRUNC open flag. If 180 * disabled, and an application specifies O_TRUNC, fuse first calls 181 * truncate() and then open() with O_TRUNC filtered out. 182 * 183 * This feature is enabled by default when supported by the kernel. 184 */ 185 #define FUSE_CAP_ATOMIC_O_TRUNC (1 << 3) 186 187 /** 188 * Indicates that the filesystem supports lookups of "." and "..". 189 * 190 * When this flag is set, the filesystem must be prepared to receive requests 191 * for invalid inodes (i.e., for which a FORGET request was received or 192 * which have been used in a previous instance of the filesystem daemon) and 193 * must not reuse node-ids (even when setting generation numbers). 194 * 195 * This feature is disabled by default. 196 */ 197 #define FUSE_CAP_EXPORT_SUPPORT (1 << 4) 198 199 /** 200 * Indicates that the kernel should not apply the umask to the 201 * file mode on create operations. 202 * 203 * This feature is disabled by default. 204 */ 205 #define FUSE_CAP_DONT_MASK (1 << 6) 206 207 /** 208 * Indicates that libfuse should try to use splice() when writing to 209 * the fuse device. This may improve performance. 210 * 211 * This feature is disabled by default. 212 */ 213 #define FUSE_CAP_SPLICE_WRITE (1 << 7) 214 215 /** 216 * Indicates that libfuse should try to move pages instead of copying when 217 * writing to / reading from the fuse device. This may improve performance. 218 * 219 * This feature is disabled by default. 220 */ 221 #define FUSE_CAP_SPLICE_MOVE (1 << 8) 222 223 /** 224 * Indicates that libfuse should try to use splice() when reading from 225 * the fuse device. This may improve performance. 226 * 227 * This feature is enabled by default when supported by the kernel and 228 * if the filesystem implements a write_buf() handler. 229 */ 230 #define FUSE_CAP_SPLICE_READ (1 << 9) 231 232 /** 233 * If set, the calls to flock(2) will be emulated using POSIX locks and must 234 * then be handled by the filesystem's setlock() handler. 235 * 236 * If not set, flock(2) calls will be handled by the FUSE kernel module 237 * internally (so any access that does not go through the kernel cannot be taken 238 * into account). 239 * 240 * This feature is enabled by default when supported by the kernel and 241 * if the filesystem implements a flock() handler. 242 */ 243 #define FUSE_CAP_FLOCK_LOCKS (1 << 10) 244 245 /** 246 * Indicates that the filesystem supports ioctl's on directories. 247 * 248 * This feature is enabled by default when supported by the kernel. 249 */ 250 #define FUSE_CAP_IOCTL_DIR (1 << 11) 251 252 /** 253 * Traditionally, while a file is open the FUSE kernel module only 254 * asks the filesystem for an update of the file's attributes when a 255 * client attempts to read beyond EOF. This is unsuitable for 256 * e.g. network filesystems, where the file contents may change 257 * without the kernel knowing about it. 258 * 259 * If this flag is set, FUSE will check the validity of the attributes 260 * on every read. If the attributes are no longer valid (i.e., if the 261 * *attr_timeout* passed to fuse_reply_attr() or set in `struct 262 * fuse_entry_param` has passed), it will first issue a `getattr` 263 * request. If the new mtime differs from the previous value, any 264 * cached file *contents* will be invalidated as well. 265 * 266 * This flag should always be set when available. If all file changes 267 * go through the kernel, *attr_timeout* should be set to a very large 268 * number to avoid unnecessary getattr() calls. 269 * 270 * This feature is enabled by default when supported by the kernel. 271 */ 272 #define FUSE_CAP_AUTO_INVAL_DATA (1 << 12) 273 274 /** 275 * Indicates that the filesystem supports readdirplus. 276 * 277 * This feature is enabled by default when supported by the kernel and if the 278 * filesystem implements a readdirplus() handler. 279 */ 280 #define FUSE_CAP_READDIRPLUS (1 << 13) 281 282 /** 283 * Indicates that the filesystem supports adaptive readdirplus. 284 * 285 * If FUSE_CAP_READDIRPLUS is not set, this flag has no effect. 286 * 287 * If FUSE_CAP_READDIRPLUS is set and this flag is not set, the kernel 288 * will always issue readdirplus() requests to retrieve directory 289 * contents. 290 * 291 * If FUSE_CAP_READDIRPLUS is set and this flag is set, the kernel 292 * will issue both readdir() and readdirplus() requests, depending on 293 * how much information is expected to be required. 294 * 295 * As of Linux 4.20, the algorithm is as follows: when userspace 296 * starts to read directory entries, issue a READDIRPLUS request to 297 * the filesystem. If any entry attributes have been looked up by the 298 * time userspace requests the next batch of entries continue with 299 * READDIRPLUS, otherwise switch to plain READDIR. This will reasult 300 * in eg plain "ls" triggering READDIRPLUS first then READDIR after 301 * that because it doesn't do lookups. "ls -l" should result in all 302 * READDIRPLUS, except if dentries are already cached. 303 * 304 * This feature is enabled by default when supported by the kernel and 305 * if the filesystem implements both a readdirplus() and a readdir() 306 * handler. 307 */ 308 #define FUSE_CAP_READDIRPLUS_AUTO (1 << 14) 309 310 /** 311 * Indicates that the filesystem supports asynchronous direct I/O submission. 312 * 313 * If this capability is not requested/available, the kernel will ensure that 314 * there is at most one pending read and one pending write request per direct 315 * I/O file-handle at any time. 316 * 317 * This feature is enabled by default when supported by the kernel. 318 */ 319 #define FUSE_CAP_ASYNC_DIO (1 << 15) 320 321 /** 322 * Indicates that writeback caching should be enabled. This means that 323 * individual write request may be buffered and merged in the kernel 324 * before they are send to the filesystem. 325 * 326 * This feature is disabled by default. 327 */ 328 #define FUSE_CAP_WRITEBACK_CACHE (1 << 16) 329 330 /** 331 * Indicates support for zero-message opens. If this flag is set in 332 * the `capable` field of the `fuse_conn_info` structure, then the 333 * filesystem may return `ENOSYS` from the open() handler to indicate 334 * success. Further attempts to open files will be handled in the 335 * kernel. (If this flag is not set, returning ENOSYS will be treated 336 * as an error and signaled to the caller). 337 * 338 * Setting this flag in the `want` field enables this behavior automatically 339 * within libfuse for low level API users. If non-low level users wish to have 340 * this behavior you must return `ENOSYS` from the open() handler on supporting 341 * kernels. 342 */ 343 #define FUSE_CAP_NO_OPEN_SUPPORT (1 << 17) 344 345 /** 346 * Indicates support for parallel directory operations. If this flag 347 * is unset, the FUSE kernel module will ensure that lookup() and 348 * readdir() requests are never issued concurrently for the same 349 * directory. 350 */ 351 #define FUSE_CAP_PARALLEL_DIROPS (1 << 18) 352 353 /** 354 * Indicates support for POSIX ACLs. 355 * 356 * If this feature is enabled, the kernel will cache and have 357 * responsibility for enforcing ACLs. ACL will be stored as xattrs and 358 * passed to userspace, which is responsible for updating the ACLs in 359 * the filesystem, keeping the file mode in sync with the ACL, and 360 * ensuring inheritance of default ACLs when new filesystem nodes are 361 * created. Note that this requires that the file system is able to 362 * parse and interpret the xattr representation of ACLs. 363 * 364 * Enabling this feature implicitly turns on the 365 * ``default_permissions`` mount option (even if it was not passed to 366 * mount(2)). 367 * 368 * This feature is disabled by default. 369 */ 370 #define FUSE_CAP_POSIX_ACL (1 << 19) 371 372 /** 373 * Indicates that the filesystem is responsible for unsetting 374 * setuid and setgid bits when a file is written, truncated, or 375 * its owner is changed. 376 * 377 * This feature is disabled by default. 378 */ 379 #define FUSE_CAP_HANDLE_KILLPRIV (1 << 20) 380 381 /** 382 * Indicates that the filesystem is responsible for unsetting 383 * setuid and setgid bit and additionally cap (stored as xattr) when a 384 * file is written, truncated, or its owner is changed. 385 * Upon write/truncate suid/sgid is only killed if caller 386 * does not have CAP_FSETID. Additionally upon 387 * write/truncate sgid is killed only if file has group 388 * execute permission. (Same as Linux VFS behavior). 389 * KILLPRIV_V2 requires handling of 390 * - FUSE_OPEN_KILL_SUIDGID (set in struct fuse_create_in::open_flags) 391 * - FATTR_KILL_SUIDGID (set in struct fuse_setattr_in::valid) 392 * - FUSE_WRITE_KILL_SUIDGID (set in struct fuse_write_in::write_flags) 393 * 394 * This feature is disabled by default. 395 */ 396 #define FUSE_CAP_HANDLE_KILLPRIV_V2 (1 << 21) 397 398 /** 399 * Indicates that the kernel supports caching symlinks in its page cache. 400 * 401 * When this feature is enabled, symlink targets are saved in the page cache. 402 * You can invalidate a cached link by calling: 403 * `fuse_lowlevel_notify_inval_inode(se, ino, 0, 0);` 404 * 405 * This feature is disabled by default. 406 * If the kernel supports it (>= 4.20), you can enable this feature by 407 * setting this flag in the `want` field of the `fuse_conn_info` structure. 408 */ 409 #define FUSE_CAP_CACHE_SYMLINKS (1 << 23) 410 411 /** 412 * Indicates support for zero-message opendirs. If this flag is set in 413 * the `capable` field of the `fuse_conn_info` structure, then the filesystem 414 * may return `ENOSYS` from the opendir() handler to indicate success. Further 415 * opendir and releasedir messages will be handled in the kernel. (If this 416 * flag is not set, returning ENOSYS will be treated as an error and signalled 417 * to the caller.) 418 * 419 * Setting this flag in the `want` field enables this behavior automatically 420 * within libfuse for low level API users. If non-low level users with to have 421 * this behavior you must return `ENOSYS` from the opendir() handler on 422 * supporting kernels. 423 */ 424 #define FUSE_CAP_NO_OPENDIR_SUPPORT (1 << 24) 425 426 /** 427 * Indicates support for invalidating cached pages only on explicit request. 428 * 429 * If this flag is set in the `capable` field of the `fuse_conn_info` structure, 430 * then the FUSE kernel module supports invalidating cached pages only on 431 * explicit request by the filesystem through fuse_lowlevel_notify_inval_inode() 432 * or fuse_invalidate_path(). 433 * 434 * By setting this flag in the `want` field of the `fuse_conn_info` structure, 435 * the filesystem is responsible for invalidating cached pages through explicit 436 * requests to the kernel. 437 * 438 * Note that setting this flag does not prevent the cached pages from being 439 * flushed by OS itself and/or through user actions. 440 * 441 * Note that if both FUSE_CAP_EXPLICIT_INVAL_DATA and FUSE_CAP_AUTO_INVAL_DATA 442 * are set in the `capable` field of the `fuse_conn_info` structure then 443 * FUSE_CAP_AUTO_INVAL_DATA takes precedence. 444 * 445 * This feature is disabled by default. 446 */ 447 #define FUSE_CAP_EXPLICIT_INVAL_DATA (1 << 25) 448 449 /** 450 * Indicates support that dentries can be expired. 451 * 452 * Expiring dentries, instead of invalidating them, makes a difference for 453 * overmounted dentries, where plain invalidation would detach all submounts 454 * before dropping the dentry from the cache. If only expiry is set on the 455 * dentry, then any overmounts are left alone and until ->d_revalidate() 456 * is called. 457 * 458 * Note: ->d_revalidate() is not called for the case of following a submount, 459 * so invalidation will only be triggered for the non-overmounted case. 460 * The dentry could also be mounted in a different mount instance, in which case 461 * any submounts will still be detached. 462 */ 463 #define FUSE_CAP_EXPIRE_ONLY (1 << 26) 464 465 /** 466 * Indicates that an extended 'struct fuse_setxattr' is used by the kernel 467 * side - extra_flags are passed, which are used (as of now by acl) processing. 468 * For example FUSE_SETXATTR_ACL_KILL_SGID might be set. 469 */ 470 #define FUSE_CAP_SETXATTR_EXT (1 << 27) 471 472 /** 473 * Files opened with FUSE_DIRECT_IO do not support MAP_SHARED mmap. This restriction 474 * is relaxed through FUSE_CAP_DIRECT_IO_RELAX (kernel flag: FUSE_DIRECT_IO_RELAX). 475 * MAP_SHARED is disabled by default for FUSE_DIRECT_IO, as this flag can be used to 476 * ensure coherency between mount points (or network clients) and with kernel page 477 * cache as enforced by mmap that cannot be guaranteed anymore. 478 */ 479 #define FUSE_CAP_DIRECT_IO_ALLOW_MMAP (1 << 28) 480 481 /** 482 * Indicates support for passthrough mode access for read/write operations. 483 * 484 * If this flag is set in the `capable` field of the `fuse_conn_info` 485 * structure, then the FUSE kernel module supports redirecting read/write 486 * operations to the backing file instead of letting them to be handled 487 * by the FUSE daemon. 488 * 489 * This feature is disabled by default. 490 */ 491 #define FUSE_CAP_PASSTHROUGH_UPSTREAM (1 << 29) 492 493 /** 494 * Indicates support for passthrough mode access for read/write operations. 495 * 496 * If this flag is set in the `capable` field of the `fuse_conn_info` 497 * structure, then the FUSE kernel module supports redirecting read/write 498 * operations to the lower file system instead of letting them to be handled 499 * by the FUSE daemon. 500 * 501 * This feature is disabled by default. 502 */ 503 #define FUSE_CAP_PASSTHROUGH (1LL << 63) 504 505 /** 506 * Ioctl flags 507 * 508 * FUSE_IOCTL_COMPAT: 32bit compat ioctl on 64bit machine 509 * FUSE_IOCTL_UNRESTRICTED: not restricted to well-formed ioctls, retry allowed 510 * FUSE_IOCTL_RETRY: retry with new iovecs 511 * FUSE_IOCTL_DIR: is a directory 512 * 513 * FUSE_IOCTL_MAX_IOV: maximum of in_iovecs + out_iovecs 514 */ 515 #define FUSE_IOCTL_COMPAT (1 << 0) 516 #define FUSE_IOCTL_UNRESTRICTED (1 << 1) 517 #define FUSE_IOCTL_RETRY (1 << 2) 518 #define FUSE_IOCTL_DIR (1 << 4) 519 520 #define FUSE_IOCTL_MAX_IOV 256 521 522 /** 523 * Connection information, passed to the ->init() method 524 * 525 * Some of the elements are read-write, these can be changed to 526 * indicate the value requested by the filesystem. The requested 527 * value must usually be smaller than the indicated value. 528 */ 529 struct fuse_conn_info { 530 /** 531 * Major version of the protocol (read-only) 532 */ 533 unsigned proto_major; 534 535 /** 536 * Minor version of the protocol (read-only) 537 */ 538 unsigned proto_minor; 539 540 /** 541 * Maximum size of the write buffer 542 */ 543 unsigned max_write; 544 545 /** 546 * Maximum size of read requests. A value of zero indicates no 547 * limit. However, even if the filesystem does not specify a 548 * limit, the maximum size of read requests will still be 549 * limited by the kernel. 550 * 551 * NOTE: For the time being, the maximum size of read requests 552 * must be set both here *and* passed to fuse_session_new() 553 * using the ``-o max_read=<n>`` mount option. At some point 554 * in the future, specifying the mount option will no longer 555 * be necessary. 556 */ 557 unsigned max_read; 558 559 /** 560 * Maximum readahead 561 */ 562 unsigned max_readahead; 563 564 /** 565 * Capability flags that the kernel supports (read-only) 566 */ 567 uint64_t capable; 568 569 /** 570 * Capability flags that the filesystem wants to enable. 571 * 572 * libfuse attempts to initialize this field with 573 * reasonable default values before calling the init() handler. 574 */ 575 uint64_t want; 576 577 /** 578 * Maximum number of pending "background" requests. A 579 * background request is any type of request for which the 580 * total number is not limited by other means. As of kernel 581 * 4.8, only two types of requests fall into this category: 582 * 583 * 1. Read-ahead requests 584 * 2. Asynchronous direct I/O requests 585 * 586 * Read-ahead requests are generated (if max_readahead is 587 * non-zero) by the kernel to preemptively fill its caches 588 * when it anticipates that userspace will soon read more 589 * data. 590 * 591 * Asynchronous direct I/O requests are generated if 592 * FUSE_CAP_ASYNC_DIO is enabled and userspace submits a large 593 * direct I/O request. In this case the kernel will internally 594 * split it up into multiple smaller requests and submit them 595 * to the filesystem concurrently. 596 * 597 * Note that the following requests are *not* background 598 * requests: writeback requests (limited by the kernel's 599 * flusher algorithm), regular (i.e., synchronous and 600 * buffered) userspace read/write requests (limited to one per 601 * thread), asynchronous read requests (Linux's io_submit(2) 602 * call actually blocks, so these are also limited to one per 603 * thread). 604 */ 605 unsigned max_background; 606 607 /** 608 * Kernel congestion threshold parameter. If the number of pending 609 * background requests exceeds this number, the FUSE kernel module will 610 * mark the filesystem as "congested". This instructs the kernel to 611 * expect that queued requests will take some time to complete, and to 612 * adjust its algorithms accordingly (e.g. by putting a waiting thread 613 * to sleep instead of using a busy-loop). 614 */ 615 unsigned congestion_threshold; 616 617 /** 618 * When FUSE_CAP_WRITEBACK_CACHE is enabled, the kernel is responsible 619 * for updating mtime and ctime when write requests are received. The 620 * updated values are passed to the filesystem with setattr() requests. 621 * However, if the filesystem does not support the full resolution of 622 * the kernel timestamps (nanoseconds), the mtime and ctime values used 623 * by kernel and filesystem will differ (and result in an apparent 624 * change of times after a cache flush). 625 * 626 * To prevent this problem, this variable can be used to inform the 627 * kernel about the timestamp granularity supported by the file-system. 628 * The value should be power of 10. The default is 1, i.e. full 629 * nano-second resolution. Filesystems supporting only second resolution 630 * should set this to 1000000000. 631 */ 632 unsigned time_gran; 633 634 /** 635 * When FUSE_CAP_PASSTHROUGH is enabled, this is the maximum allowed 636 * stacking depth of the backing files. In current kernel, the maximum 637 * allowed stack depth if FILESYSTEM_MAX_STACK_DEPTH (2), which includes 638 * the FUSE passthrough layer, so the maximum stacking depth for backing 639 * files is 1. 640 * 641 * The default is FUSE_BACKING_STACKED_UNDER (0), meaning that the 642 * backing files cannot be on a stacked filesystem, but another stacked 643 * filesystem can be stacked over this FUSE passthrough filesystem. 644 * 645 * Set this to FUSE_BACKING_STACKED_OVER (1) if backing files may be on 646 * a stacked filesystem, such as overlayfs or another FUSE passthrough. 647 * In this configuration, another stacked filesystem cannot be stacked 648 * over this FUSE passthrough filesystem. 649 */ 650 #define FUSE_BACKING_STACKED_UNDER (0) 651 #define FUSE_BACKING_STACKED_OVER (1) 652 unsigned max_backing_stack_depth; 653 654 /** 655 * For future use. 656 */ 657 unsigned reserved[21]; 658 }; 659 660 struct fuse_session; 661 struct fuse_pollhandle; 662 struct fuse_conn_info_opts; 663 664 /** 665 * This function parses several command-line options that can be used 666 * to override elements of struct fuse_conn_info. The pointer returned 667 * by this function should be passed to the 668 * fuse_apply_conn_info_opts() method by the file system's init() 669 * handler. 670 * 671 * Before using this function, think twice if you really want these 672 * parameters to be adjustable from the command line. In most cases, 673 * they should be determined by the file system internally. 674 * 675 * The following options are recognized: 676 * 677 * -o max_write=N sets conn->max_write 678 * -o max_readahead=N sets conn->max_readahead 679 * -o max_background=N sets conn->max_background 680 * -o congestion_threshold=N sets conn->congestion_threshold 681 * -o async_read sets FUSE_CAP_ASYNC_READ in conn->want 682 * -o sync_read unsets FUSE_CAP_ASYNC_READ in conn->want 683 * -o atomic_o_trunc sets FUSE_CAP_ATOMIC_O_TRUNC in conn->want 684 * -o no_remote_lock Equivalent to -o no_remote_flock,no_remote_posix_lock 685 * -o no_remote_flock Unsets FUSE_CAP_FLOCK_LOCKS in conn->want 686 * -o no_remote_posix_lock Unsets FUSE_CAP_POSIX_LOCKS in conn->want 687 * -o [no_]splice_write (un-)sets FUSE_CAP_SPLICE_WRITE in conn->want 688 * -o [no_]splice_move (un-)sets FUSE_CAP_SPLICE_MOVE in conn->want 689 * -o [no_]splice_read (un-)sets FUSE_CAP_SPLICE_READ in conn->want 690 * -o [no_]auto_inval_data (un-)sets FUSE_CAP_AUTO_INVAL_DATA in conn->want 691 * -o readdirplus=no unsets FUSE_CAP_READDIRPLUS in conn->want 692 * -o readdirplus=yes sets FUSE_CAP_READDIRPLUS and unsets 693 * FUSE_CAP_READDIRPLUS_AUTO in conn->want 694 * -o readdirplus=auto sets FUSE_CAP_READDIRPLUS and 695 * FUSE_CAP_READDIRPLUS_AUTO in conn->want 696 * -o [no_]async_dio (un-)sets FUSE_CAP_ASYNC_DIO in conn->want 697 * -o [no_]writeback_cache (un-)sets FUSE_CAP_WRITEBACK_CACHE in conn->want 698 * -o time_gran=N sets conn->time_gran 699 * 700 * Known options will be removed from *args*, unknown options will be 701 * passed through unchanged. 702 * 703 * @param args argument vector (input+output) 704 * @return parsed options 705 **/ 706 struct fuse_conn_info_opts* fuse_parse_conn_info_opts(struct fuse_args *args); 707 708 /** 709 * This function applies the (parsed) parameters in *opts* to the 710 * *conn* pointer. It may modify the following fields: wants, 711 * max_write, max_readahead, congestion_threshold, max_background, 712 * time_gran. A field is only set (or unset) if the corresponding 713 * option has been explicitly set. 714 */ 715 void fuse_apply_conn_info_opts(struct fuse_conn_info_opts *opts, 716 struct fuse_conn_info *conn); 717 718 /** 719 * Go into the background 720 * 721 * @param foreground if true, stay in the foreground 722 * @return 0 on success, -1 on failure 723 */ 724 int fuse_daemonize(int foreground); 725 726 /** 727 * Get the version of the library 728 * 729 * @return the version 730 */ 731 int fuse_version(void); 732 733 /** 734 * Get the full package version string of the library 735 * 736 * @return the package version 737 */ 738 const char *fuse_pkgversion(void); 739 740 /** 741 * Destroy poll handle 742 * 743 * @param ph the poll handle 744 */ 745 void fuse_pollhandle_destroy(struct fuse_pollhandle *ph); 746 747 /* ----------------------------------------------------------- * 748 * Data buffer * 749 * ----------------------------------------------------------- */ 750 751 /** 752 * Buffer flags 753 */ 754 enum fuse_buf_flags { 755 /** 756 * Buffer contains a file descriptor 757 * 758 * If this flag is set, the .fd field is valid, otherwise the 759 * .mem fields is valid. 760 */ 761 FUSE_BUF_IS_FD = (1 << 1), 762 763 /** 764 * Seek on the file descriptor 765 * 766 * If this flag is set then the .pos field is valid and is 767 * used to seek to the given offset before performing 768 * operation on file descriptor. 769 */ 770 FUSE_BUF_FD_SEEK = (1 << 2), 771 772 /** 773 * Retry operation on file descriptor 774 * 775 * If this flag is set then retry operation on file descriptor 776 * until .size bytes have been copied or an error or EOF is 777 * detected. 778 */ 779 FUSE_BUF_FD_RETRY = (1 << 3) 780 }; 781 782 /** 783 * Buffer copy flags 784 */ 785 enum fuse_buf_copy_flags { 786 /** 787 * Don't use splice(2) 788 * 789 * Always fall back to using read and write instead of 790 * splice(2) to copy data from one file descriptor to another. 791 * 792 * If this flag is not set, then only fall back if splice is 793 * unavailable. 794 */ 795 FUSE_BUF_NO_SPLICE = (1 << 1), 796 797 /** 798 * Force splice 799 * 800 * Always use splice(2) to copy data from one file descriptor 801 * to another. If splice is not available, return -EINVAL. 802 */ 803 FUSE_BUF_FORCE_SPLICE = (1 << 2), 804 805 /** 806 * Try to move data with splice. 807 * 808 * If splice is used, try to move pages from the source to the 809 * destination instead of copying. See documentation of 810 * SPLICE_F_MOVE in splice(2) man page. 811 */ 812 FUSE_BUF_SPLICE_MOVE = (1 << 3), 813 814 /** 815 * Don't block on the pipe when copying data with splice 816 * 817 * Makes the operations on the pipe non-blocking (if the pipe 818 * is full or empty). See SPLICE_F_NONBLOCK in the splice(2) 819 * man page. 820 */ 821 FUSE_BUF_SPLICE_NONBLOCK= (1 << 4) 822 }; 823 824 /** 825 * Single data buffer 826 * 827 * Generic data buffer for I/O, extended attributes, etc... Data may 828 * be supplied as a memory pointer or as a file descriptor 829 */ 830 struct fuse_buf { 831 /** 832 * Size of data in bytes 833 */ 834 size_t size; 835 836 /** 837 * Buffer flags 838 */ 839 enum fuse_buf_flags flags; 840 841 /** 842 * Memory pointer 843 * 844 * Used unless FUSE_BUF_IS_FD flag is set. 845 */ 846 void *mem; 847 848 /** 849 * File descriptor 850 * 851 * Used if FUSE_BUF_IS_FD flag is set. 852 */ 853 int fd; 854 855 /** 856 * File position 857 * 858 * Used if FUSE_BUF_FD_SEEK flag is set. 859 */ 860 off_t pos; 861 }; 862 863 /** 864 * Data buffer vector 865 * 866 * An array of data buffers, each containing a memory pointer or a 867 * file descriptor. 868 * 869 * Allocate dynamically to add more than one buffer. 870 */ 871 struct fuse_bufvec { 872 /** 873 * Number of buffers in the array 874 */ 875 size_t count; 876 877 /** 878 * Index of current buffer within the array 879 */ 880 size_t idx; 881 882 /** 883 * Current offset within the current buffer 884 */ 885 size_t off; 886 887 /** 888 * Array of buffers 889 */ 890 struct fuse_buf buf[1]; 891 }; 892 893 /** 894 * libfuse version a file system was compiled with. Should be filled in from 895 * defines in 'libfuse_config.h' 896 */ 897 struct libfuse_version 898 { 899 int major; 900 int minor; 901 int hotfix; 902 int padding; 903 }; 904 905 /* Initialize bufvec with a single buffer of given size */ 906 #define FUSE_BUFVEC_INIT(size__) \ 907 ((struct fuse_bufvec) { \ 908 /* .count= */ 1, \ 909 /* .idx = */ 0, \ 910 /* .off = */ 0, \ 911 /* .buf = */ { /* [0] = */ { \ 912 /* .size = */ (size__), \ 913 /* .flags = */ (enum fuse_buf_flags) 0, \ 914 /* .mem = */ NULL, \ 915 /* .fd = */ -1, \ 916 /* .pos = */ 0, \ 917 } } \ 918 } ) 919 920 /** 921 * Get total size of data in a fuse buffer vector 922 * 923 * @param bufv buffer vector 924 * @return size of data 925 */ 926 size_t fuse_buf_size(const struct fuse_bufvec *bufv); 927 928 /** 929 * Copy data from one buffer vector to another 930 * 931 * @param dst destination buffer vector 932 * @param src source buffer vector 933 * @param flags flags controlling the copy 934 * @return actual number of bytes copied or -errno on error 935 */ 936 ssize_t fuse_buf_copy(struct fuse_bufvec *dst, struct fuse_bufvec *src, 937 enum fuse_buf_copy_flags flags); 938 939 /* ----------------------------------------------------------- * 940 * Signal handling * 941 * ----------------------------------------------------------- */ 942 943 /** 944 * Exit session on HUP, TERM and INT signals and ignore PIPE signal 945 * 946 * Stores session in a global variable. May only be called once per 947 * process until fuse_remove_signal_handlers() is called. 948 * 949 * Once either of the POSIX signals arrives, the signal handler calls 950 * fuse_session_exit(). 951 * 952 * @param se the session to exit 953 * @return 0 on success, -1 on failure 954 * 955 * See also: 956 * fuse_remove_signal_handlers() 957 */ 958 int fuse_set_signal_handlers(struct fuse_session *se); 959 960 /** 961 * Restore default signal handlers 962 * 963 * Resets global session. After this fuse_set_signal_handlers() may 964 * be called again. 965 * 966 * @param se the same session as given in fuse_set_signal_handlers() 967 * 968 * See also: 969 * fuse_set_signal_handlers() 970 */ 971 void fuse_remove_signal_handlers(struct fuse_session *se); 972 973 /** 974 * Create and set default config for fuse_session_loop_mt and fuse_loop_mt. 975 * 976 * @return anonymous config struct 977 */ 978 struct fuse_loop_config *fuse_loop_cfg_create(void); 979 980 /** 981 * Free the config data structure 982 */ 983 void fuse_loop_cfg_destroy(struct fuse_loop_config *config); 984 985 /** 986 * fuse_loop_config setter to set the number of max idle threads. 987 */ 988 void fuse_loop_cfg_set_idle_threads(struct fuse_loop_config *config, 989 unsigned int value); 990 991 /** 992 * fuse_loop_config setter to set the number of max threads. 993 */ 994 void fuse_loop_cfg_set_max_threads(struct fuse_loop_config *config, 995 unsigned int value); 996 997 /** 998 * fuse_loop_config setter to enable the clone_fd feature 999 */ 1000 void fuse_loop_cfg_set_clone_fd(struct fuse_loop_config *config, 1001 unsigned int value); 1002 1003 /** 1004 * Convert old config to more recernt fuse_loop_config2 1005 * 1006 * @param config current config2 type 1007 * @param v1_conf older config1 type (below FUSE API 312) 1008 */ 1009 void fuse_loop_cfg_convert(struct fuse_loop_config *config, 1010 struct fuse_loop_config_v1 *v1_conf); 1011 1012 /* ----------------------------------------------------------- * 1013 * Compatibility stuff * 1014 * ----------------------------------------------------------- */ 1015 1016 #if !defined(FUSE_USE_VERSION) || FUSE_USE_VERSION < 30 1017 # error only API version 30 or greater is supported 1018 #endif 1019 1020 #ifdef __cplusplus 1021 } 1022 #endif 1023 1024 1025 /* 1026 * This interface uses 64 bit off_t. 1027 * 1028 * On 32bit systems please add -D_FILE_OFFSET_BITS=64 to your compile flags! 1029 */ 1030 1031 #if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 201112L) 1032 _Static_assert(sizeof(off_t) == 8, "fuse: off_t must be 64bit"); 1033 #else 1034 struct _fuse_off_t_must_be_64bit_dummy_struct \ 1035 { unsigned _fuse_off_t_must_be_64bit:((sizeof(off_t) == 8) ? 1 : -1); }; 1036 #endif 1037 1038 #endif /* FUSE_COMMON_H_ */ 1039