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