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