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