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