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