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