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