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_H_ 10 #define FUSE_H_ 11 12 /** @file 13 * 14 * This file defines the library interface of FUSE 15 * 16 * IMPORTANT: you should define FUSE_USE_VERSION before including this header. 17 */ 18 19 #include "fuse_common.h" 20 21 #include <fcntl.h> 22 #include <time.h> 23 #include <sys/types.h> 24 #include <sys/stat.h> 25 #include <sys/statvfs.h> 26 #include <sys/uio.h> 27 28 #ifdef __cplusplus 29 extern "C" { 30 #endif 31 32 /* ----------------------------------------------------------- * 33 * Basic FUSE API * 34 * ----------------------------------------------------------- */ 35 36 /** Handle for a FUSE filesystem */ 37 struct fuse; 38 39 /** 40 * Readdir flags, passed to ->readdir() 41 */ 42 enum fuse_readdir_flags { 43 /** 44 * "Plus" mode. 45 * 46 * The kernel wants to prefill the inode cache during readdir. The 47 * filesystem may honour this by filling in the attributes and setting 48 * FUSE_FILL_DIR_FLAGS for the filler function. The filesystem may also 49 * just ignore this flag completely. 50 */ 51 FUSE_READDIR_PLUS = (1 << 0) 52 }; 53 54 /** 55 * Readdir flags, passed to fuse_fill_dir_t callback. 56 */ 57 enum fuse_fill_dir_flags { 58 /** 59 * "Plus" mode: all file attributes are valid 60 * 61 * The attributes are used by the kernel to prefill the inode cache 62 * during a readdir. 63 * 64 * It is okay to set FUSE_FILL_DIR_PLUS if FUSE_READDIR_PLUS is not set 65 * and vice versa. 66 */ 67 FUSE_FILL_DIR_PLUS = (1 << 1) 68 }; 69 70 /** Function to add an entry in a readdir() operation 71 * 72 * The *off* parameter can be any non-zero value that enables the 73 * filesystem to identify the current point in the directory 74 * stream. It does not need to be the actual physical position. A 75 * value of zero is reserved to indicate that seeking in directories 76 * is not supported. 77 * 78 * @param buf the buffer passed to the readdir() operation 79 * @param name the file name of the directory entry 80 * @param stbuf file attributes, can be NULL 81 * @param off offset of the next entry or zero 82 * @param flags fill flags 83 * @return 1 if buffer is full, zero otherwise 84 */ 85 typedef int (*fuse_fill_dir_t) (void *buf, const char *name, 86 const struct stat *stbuf, off_t off, 87 enum fuse_fill_dir_flags flags); 88 /** 89 * Configuration of the high-level API 90 * 91 * This structure is initialized from the arguments passed to 92 * fuse_new(), and then passed to the file system's init() handler 93 * which should ensure that the configuration is compatible with the 94 * file system implementation. 95 */ 96 struct fuse_config { 97 /** 98 * If `set_gid` is non-zero, the st_gid attribute of each file 99 * is overwritten with the value of `gid`. 100 */ 101 int set_gid; 102 unsigned int gid; 103 104 /** 105 * If `set_uid` is non-zero, the st_uid attribute of each file 106 * is overwritten with the value of `uid`. 107 */ 108 int set_uid; 109 unsigned int uid; 110 111 /** 112 * If `set_mode` is non-zero, the any permissions bits set in 113 * `umask` are unset in the st_mode attribute of each file. 114 */ 115 int set_mode; 116 unsigned int umask; 117 118 /** 119 * The timeout in seconds for which name lookups will be 120 * cached. 121 */ 122 double entry_timeout; 123 124 /** 125 * The timeout in seconds for which a negative lookup will be 126 * cached. This means, that if file did not exist (lookup 127 * returned ENOENT), the lookup will only be redone after the 128 * timeout, and the file/directory will be assumed to not 129 * exist until then. A value of zero means that negative 130 * lookups are not cached. 131 */ 132 double negative_timeout; 133 134 /** 135 * The timeout in seconds for which file/directory attributes 136 * (as returned by e.g. the `getattr` handler) are cached. 137 */ 138 double attr_timeout; 139 140 /** 141 * Allow requests to be interrupted 142 */ 143 int intr; 144 145 /** 146 * Specify which signal number to send to the filesystem when 147 * a request is interrupted. The default is hardcoded to 148 * USR1. 149 */ 150 int intr_signal; 151 152 /** 153 * Normally, FUSE assigns inodes to paths only for as long as 154 * the kernel is aware of them. With this option inodes are 155 * instead remembered for at least this many seconds. This 156 * will require more memory, but may be necessary when using 157 * applications that make use of inode numbers. 158 * 159 * A number of -1 means that inodes will be remembered for the 160 * entire life-time of the file-system process. 161 */ 162 int remember; 163 164 /** 165 * The default behavior is that if an open file is deleted, 166 * the file is renamed to a hidden file (.fuse_hiddenXXX), and 167 * only removed when the file is finally released. This 168 * relieves the filesystem implementation of having to deal 169 * with this problem. This option disables the hiding 170 * behavior, and files are removed immediately in an unlink 171 * operation (or in a rename operation which overwrites an 172 * existing file). 173 * 174 * It is recommended that you not use the hard_remove 175 * option. When hard_remove is set, the following libc 176 * functions fail on unlinked files (returning errno of 177 * ENOENT): read(2), write(2), fsync(2), close(2), f*xattr(2), 178 * ftruncate(2), fstat(2), fchmod(2), fchown(2) 179 */ 180 int hard_remove; 181 182 /** 183 * Honor the st_ino field in the functions getattr() and 184 * fill_dir(). This value is used to fill in the st_ino field 185 * in the stat(2), lstat(2), fstat(2) functions and the d_ino 186 * field in the readdir(2) function. The filesystem does not 187 * have to guarantee uniqueness, however some applications 188 * rely on this value being unique for the whole filesystem. 189 * 190 * Note that this does *not* affect the inode that libfuse 191 * and the kernel use internally (also called the "nodeid"). 192 */ 193 int use_ino; 194 195 /** 196 * If use_ino option is not given, still try to fill in the 197 * d_ino field in readdir(2). If the name was previously 198 * looked up, and is still in the cache, the inode number 199 * found there will be used. Otherwise it will be set to -1. 200 * If use_ino option is given, this option is ignored. 201 */ 202 int readdir_ino; 203 204 /** 205 * This option disables the use of page cache (file content cache) 206 * in the kernel for this filesystem. This has several affects: 207 * 208 * 1. Each read(2) or write(2) system call will initiate one 209 * or more read or write operations, data will not be 210 * cached in the kernel. 211 * 212 * 2. The return value of the read() and write() system calls 213 * will correspond to the return values of the read and 214 * write operations. This is useful for example if the 215 * file size is not known in advance (before reading it). 216 * 217 * Internally, enabling this option causes fuse to set the 218 * `direct_io` field of `struct fuse_file_info` - overwriting 219 * any value that was put there by the file system. 220 */ 221 int direct_io; 222 223 /** 224 * This option disables flushing the cache of the file 225 * contents on every open(2). This should only be enabled on 226 * filesystems where the file data is never changed 227 * externally (not through the mounted FUSE filesystem). Thus 228 * it is not suitable for network filesystems and other 229 * intermediate filesystems. 230 * 231 * NOTE: if this option is not specified (and neither 232 * direct_io) data is still cached after the open(2), so a 233 * read(2) system call will not always initiate a read 234 * operation. 235 * 236 * Internally, enabling this option causes fuse to set the 237 * `keep_cache` field of `struct fuse_file_info` - overwriting 238 * any value that was put there by the file system. 239 */ 240 int kernel_cache; 241 242 /** 243 * This option is an alternative to `kernel_cache`. Instead of 244 * unconditionally keeping cached data, the cached data is 245 * invalidated on open(2) if if the modification time or the 246 * size of the file has changed since it was last opened. 247 */ 248 int auto_cache; 249 250 /** 251 * The timeout in seconds for which file attributes are cached 252 * for the purpose of checking if auto_cache should flush the 253 * file data on open. 254 */ 255 int ac_attr_timeout_set; 256 double ac_attr_timeout; 257 258 /** 259 * If this option is given the file-system handlers for the 260 * following operations will not receive path information: 261 * read, write, flush, release, fallocate, fsync, readdir, 262 * releasedir, fsyncdir, lock, ioctl and poll. 263 * 264 * For the truncate, getattr, chmod, chown and utimens 265 * operations the path will be provided only if the struct 266 * fuse_file_info argument is NULL. 267 */ 268 int nullpath_ok; 269 270 /** 271 * The remaining options are used by libfuse internally and 272 * should not be touched. 273 */ 274 int show_help; 275 char *modules; 276 int debug; 277 }; 278 279 280 /** 281 * The file system operations: 282 * 283 * Most of these should work very similarly to the well known UNIX 284 * file system operations. A major exception is that instead of 285 * returning an error in 'errno', the operation should return the 286 * negated error value (-errno) directly. 287 * 288 * All methods are optional, but some are essential for a useful 289 * filesystem (e.g. getattr). Open, flush, release, fsync, opendir, 290 * releasedir, fsyncdir, access, create, truncate, lock, init and 291 * destroy are special purpose methods, without which a full featured 292 * filesystem can still be implemented. 293 * 294 * In general, all methods are expected to perform any necessary 295 * permission checking. However, a filesystem may delegate this task 296 * to the kernel by passing the `default_permissions` mount option to 297 * `fuse_new()`. In this case, methods will only be called if 298 * the kernel's permission check has succeeded. 299 * 300 * Almost all operations take a path which can be of any length. 301 */ 302 struct fuse_operations { 303 /** Get file attributes. 304 * 305 * Similar to stat(). The 'st_dev' and 'st_blksize' fields are 306 * ignored. The 'st_ino' field is ignored except if the 'use_ino' 307 * mount option is given. In that case it is passed to userspace, 308 * but libfuse and the kernel will still assign a different 309 * inode for internal use (called the "nodeid"). 310 * 311 * `fi` will always be NULL if the file is not currently open, but 312 * may also be NULL if the file is open. 313 */ 314 int (*getattr) (const char *, struct stat *, struct fuse_file_info *fi); 315 316 /** Read the target of a symbolic link 317 * 318 * The buffer should be filled with a null terminated string. The 319 * buffer size argument includes the space for the terminating 320 * null character. If the linkname is too long to fit in the 321 * buffer, it should be truncated. The return value should be 0 322 * for success. 323 */ 324 int (*readlink) (const char *, char *, size_t); 325 326 /** Create a file node 327 * 328 * This is called for creation of all non-directory, non-symlink 329 * nodes. If the filesystem defines a create() method, then for 330 * regular files that will be called instead. 331 */ 332 int (*mknod) (const char *, mode_t, dev_t); 333 334 /** Create a directory 335 * 336 * Note that the mode argument may not have the type specification 337 * bits set, i.e. S_ISDIR(mode) can be false. To obtain the 338 * correct directory type bits use mode|S_IFDIR 339 * */ 340 int (*mkdir) (const char *, mode_t); 341 342 /** Remove a file */ 343 int (*unlink) (const char *); 344 345 /** Remove a directory */ 346 int (*rmdir) (const char *); 347 348 /** Create a symbolic link */ 349 int (*symlink) (const char *, const char *); 350 351 /** Rename a file 352 * 353 * *flags* may be `RENAME_EXCHANGE` or `RENAME_NOREPLACE`. If 354 * RENAME_NOREPLACE is specified, the filesystem must not 355 * overwrite *newname* if it exists and return an error 356 * instead. If `RENAME_EXCHANGE` is specified, the filesystem 357 * must atomically exchange the two files, i.e. both must 358 * exist and neither may be deleted. 359 */ 360 int (*rename) (const char *, const char *, unsigned int flags); 361 362 /** Create a hard link to a file */ 363 int (*link) (const char *, const char *); 364 365 /** Change the permission bits of a file 366 * 367 * `fi` will always be NULL if the file is not currently open, but 368 * may also be NULL if the file is open. 369 */ 370 int (*chmod) (const char *, mode_t, struct fuse_file_info *fi); 371 372 /** Change the owner and group of a file 373 * 374 * `fi` will always be NULL if the file is not currently open, but 375 * may also be NULL if the file is open. 376 * 377 * Unless FUSE_CAP_HANDLE_KILLPRIV is disabled, this method is 378 * expected to reset the setuid and setgid bits. 379 */ 380 int (*chown) (const char *, uid_t, gid_t, struct fuse_file_info *fi); 381 382 /** Change the size of a file 383 * 384 * `fi` will always be NULL if the file is not currently open, but 385 * may also be NULL if the file is open. 386 * 387 * Unless FUSE_CAP_HANDLE_KILLPRIV is disabled, this method is 388 * expected to reset the setuid and setgid bits. 389 */ 390 int (*truncate) (const char *, off_t, struct fuse_file_info *fi); 391 392 /** Open a file 393 * 394 * Open flags are available in fi->flags. The following rules 395 * apply. 396 * 397 * - Creation (O_CREAT, O_EXCL, O_NOCTTY) flags will be 398 * filtered out / handled by the kernel. 399 * 400 * - Access modes (O_RDONLY, O_WRONLY, O_RDWR, O_EXEC, O_SEARCH) 401 * should be used by the filesystem to check if the operation is 402 * permitted. If the ``-o default_permissions`` mount option is 403 * given, this check is already done by the kernel before calling 404 * open() and may thus be omitted by the filesystem. 405 * 406 * - When writeback caching is enabled, the kernel may send 407 * read requests even for files opened with O_WRONLY. The 408 * filesystem should be prepared to handle this. 409 * 410 * - When writeback caching is disabled, the filesystem is 411 * expected to properly handle the O_APPEND flag and ensure 412 * that each write is appending to the end of the file. 413 * 414 * - When writeback caching is enabled, the kernel will 415 * handle O_APPEND. However, unless all changes to the file 416 * come through the kernel this will not work reliably. The 417 * filesystem should thus either ignore the O_APPEND flag 418 * (and let the kernel handle it), or return an error 419 * (indicating that reliably O_APPEND is not available). 420 * 421 * Filesystem may store an arbitrary file handle (pointer, 422 * index, etc) in fi->fh, and use this in other all other file 423 * operations (read, write, flush, release, fsync). 424 * 425 * Filesystem may also implement stateless file I/O and not store 426 * anything in fi->fh. 427 * 428 * There are also some flags (direct_io, keep_cache) which the 429 * filesystem may set in fi, to change the way the file is opened. 430 * See fuse_file_info structure in <fuse_common.h> for more details. 431 * 432 * If this request is answered with an error code of ENOSYS 433 * and FUSE_CAP_NO_OPEN_SUPPORT is set in 434 * `fuse_conn_info.capable`, this is treated as success and 435 * future calls to open will also succeed without being send 436 * to the filesystem process. 437 * 438 */ 439 int (*open) (const char *, struct fuse_file_info *); 440 441 /** Read data from an open file 442 * 443 * Read should return exactly the number of bytes requested except 444 * on EOF or error, otherwise the rest of the data will be 445 * substituted with zeroes. An exception to this is when the 446 * 'direct_io' mount option is specified, in which case the return 447 * value of the read system call will reflect the return value of 448 * this operation. 449 */ 450 int (*read) (const char *, char *, size_t, off_t, 451 struct fuse_file_info *); 452 453 /** Write data to an open file 454 * 455 * Write should return exactly the number of bytes requested 456 * except on error. An exception to this is when the 'direct_io' 457 * mount option is specified (see read operation). 458 * 459 * Unless FUSE_CAP_HANDLE_KILLPRIV is disabled, this method is 460 * expected to reset the setuid and setgid bits. 461 */ 462 int (*write) (const char *, const char *, size_t, off_t, 463 struct fuse_file_info *); 464 465 /** Get file system statistics 466 * 467 * The 'f_favail', 'f_fsid' and 'f_flag' fields are ignored 468 */ 469 int (*statfs) (const char *, struct statvfs *); 470 471 /** Possibly flush cached data 472 * 473 * BIG NOTE: This is not equivalent to fsync(). It's not a 474 * request to sync dirty data. 475 * 476 * Flush is called on each close() of a file descriptor, as opposed to 477 * release which is called on the close of the last file descriptor for 478 * a file. Under Linux, errors returned by flush() will be passed to 479 * userspace as errors from close(), so flush() is a good place to write 480 * back any cached dirty data. However, many applications ignore errors 481 * on close(), and on non-Linux systems, close() may succeed even if flush() 482 * returns an error. For these reasons, filesystems should not assume 483 * that errors returned by flush will ever be noticed or even 484 * delivered. 485 * 486 * NOTE: The flush() method may be called more than once for each 487 * open(). This happens if more than one file descriptor refers to an 488 * open file handle, e.g. due to dup(), dup2() or fork() calls. It is 489 * not possible to determine if a flush is final, so each flush should 490 * be treated equally. Multiple write-flush sequences are relatively 491 * rare, so this shouldn't be a problem. 492 * 493 * Filesystems shouldn't assume that flush will be called at any 494 * particular point. It may be called more times than expected, or not 495 * at all. 496 * 497 * [close]: http://pubs.opengroup.org/onlinepubs/9699919799/functions/close.html 498 */ 499 int (*flush) (const char *, struct fuse_file_info *); 500 501 /** Release an open file 502 * 503 * Release is called when there are no more references to an open 504 * file: all file descriptors are closed and all memory mappings 505 * are unmapped. 506 * 507 * For every open() call there will be exactly one release() call 508 * with the same flags and file handle. It is possible to 509 * have a file opened more than once, in which case only the last 510 * release will mean, that no more reads/writes will happen on the 511 * file. The return value of release is ignored. 512 */ 513 int (*release) (const char *, struct fuse_file_info *); 514 515 /** Synchronize file contents 516 * 517 * If the datasync parameter is non-zero, then only the user data 518 * should be flushed, not the meta data. 519 */ 520 int (*fsync) (const char *, int, struct fuse_file_info *); 521 522 /** Set extended attributes */ 523 int (*setxattr) (const char *, const char *, const char *, size_t, int); 524 525 /** Get extended attributes */ 526 int (*getxattr) (const char *, const char *, char *, size_t); 527 528 /** List extended attributes */ 529 int (*listxattr) (const char *, char *, size_t); 530 531 /** Remove extended attributes */ 532 int (*removexattr) (const char *, const char *); 533 534 /** Open directory 535 * 536 * Unless the 'default_permissions' mount option is given, 537 * this method should check if opendir is permitted for this 538 * directory. Optionally opendir may also return an arbitrary 539 * filehandle in the fuse_file_info structure, which will be 540 * passed to readdir, releasedir and fsyncdir. 541 */ 542 int (*opendir) (const char *, struct fuse_file_info *); 543 544 /** Read directory 545 * 546 * The filesystem may choose between two modes of operation: 547 * 548 * 1) The readdir implementation ignores the offset parameter, and 549 * passes zero to the filler function's offset. The filler 550 * function will not return '1' (unless an error happens), so the 551 * whole directory is read in a single readdir operation. 552 * 553 * 2) The readdir implementation keeps track of the offsets of the 554 * directory entries. It uses the offset parameter and always 555 * passes non-zero offset to the filler function. When the buffer 556 * is full (or an error happens) the filler function will return 557 * '1'. 558 */ 559 int (*readdir) (const char *, void *, fuse_fill_dir_t, off_t, 560 struct fuse_file_info *, enum fuse_readdir_flags); 561 562 /** Release directory 563 */ 564 int (*releasedir) (const char *, struct fuse_file_info *); 565 566 /** Synchronize directory contents 567 * 568 * If the datasync parameter is non-zero, then only the user data 569 * should be flushed, not the meta data 570 */ 571 int (*fsyncdir) (const char *, int, struct fuse_file_info *); 572 573 /** 574 * Initialize filesystem 575 * 576 * The return value will passed in the `private_data` field of 577 * `struct fuse_context` to all file operations, and as a 578 * parameter to the destroy() method. It overrides the initial 579 * value provided to fuse_main() / fuse_new(). 580 */ 581 void *(*init) (struct fuse_conn_info *conn, 582 struct fuse_config *cfg); 583 584 /** 585 * Clean up filesystem 586 * 587 * Called on filesystem exit. 588 */ 589 void (*destroy) (void *private_data); 590 591 /** 592 * Check file access permissions 593 * 594 * This will be called for the access() system call. If the 595 * 'default_permissions' mount option is given, this method is not 596 * called. 597 * 598 * This method is not called under Linux kernel versions 2.4.x 599 */ 600 int (*access) (const char *, int); 601 602 /** 603 * Create and open a file 604 * 605 * If the file does not exist, first create it with the specified 606 * mode, and then open it. 607 * 608 * If this method is not implemented or under Linux kernel 609 * versions earlier than 2.6.15, the mknod() and open() methods 610 * will be called instead. 611 */ 612 int (*create) (const char *, mode_t, struct fuse_file_info *); 613 614 /** 615 * Perform POSIX file locking operation 616 * 617 * The cmd argument will be either F_GETLK, F_SETLK or F_SETLKW. 618 * 619 * For the meaning of fields in 'struct flock' see the man page 620 * for fcntl(2). The l_whence field will always be set to 621 * SEEK_SET. 622 * 623 * For checking lock ownership, the 'fuse_file_info->owner' 624 * argument must be used. 625 * 626 * For F_GETLK operation, the library will first check currently 627 * held locks, and if a conflicting lock is found it will return 628 * information without calling this method. This ensures, that 629 * for local locks the l_pid field is correctly filled in. The 630 * results may not be accurate in case of race conditions and in 631 * the presence of hard links, but it's unlikely that an 632 * application would rely on accurate GETLK results in these 633 * cases. If a conflicting lock is not found, this method will be 634 * called, and the filesystem may fill out l_pid by a meaningful 635 * value, or it may leave this field zero. 636 * 637 * For F_SETLK and F_SETLKW the l_pid field will be set to the pid 638 * of the process performing the locking operation. 639 * 640 * Note: if this method is not implemented, the kernel will still 641 * allow file locking to work locally. Hence it is only 642 * interesting for network filesystems and similar. 643 */ 644 int (*lock) (const char *, struct fuse_file_info *, int cmd, 645 struct flock *); 646 647 /** 648 * Change the access and modification times of a file with 649 * nanosecond resolution 650 * 651 * This supersedes the old utime() interface. New applications 652 * should use this. 653 * 654 * `fi` will always be NULL if the file is not currently open, but 655 * may also be NULL if the file is open. 656 * 657 * See the utimensat(2) man page for details. 658 */ 659 int (*utimens) (const char *, const struct timespec tv[2], 660 struct fuse_file_info *fi); 661 662 /** 663 * Map block index within file to block index within device 664 * 665 * Note: This makes sense only for block device backed filesystems 666 * mounted with the 'blkdev' option 667 */ 668 int (*bmap) (const char *, size_t blocksize, uint64_t *idx); 669 670 #if FUSE_USE_VERSION < 35 671 int (*ioctl) (const char *, int cmd, void *arg, 672 struct fuse_file_info *, unsigned int flags, void *data); 673 #else 674 /** 675 * Ioctl 676 * 677 * flags will have FUSE_IOCTL_COMPAT set for 32bit ioctls in 678 * 64bit environment. The size and direction of data is 679 * determined by _IOC_*() decoding of cmd. For _IOC_NONE, 680 * data will be NULL, for _IOC_WRITE data is out area, for 681 * _IOC_READ in area and if both are set in/out area. In all 682 * non-NULL cases, the area is of _IOC_SIZE(cmd) bytes. 683 * 684 * If flags has FUSE_IOCTL_DIR then the fuse_file_info refers to a 685 * directory file handle. 686 * 687 * Note : the unsigned long request submitted by the application 688 * is truncated to 32 bits. 689 */ 690 int (*ioctl) (const char *, unsigned int cmd, void *arg, 691 struct fuse_file_info *, unsigned int flags, void *data); 692 #endif 693 694 /** 695 * Poll for IO readiness events 696 * 697 * Note: If ph is non-NULL, the client should notify 698 * when IO readiness events occur by calling 699 * fuse_notify_poll() with the specified ph. 700 * 701 * Regardless of the number of times poll with a non-NULL ph 702 * is received, single notification is enough to clear all. 703 * Notifying more times incurs overhead but doesn't harm 704 * correctness. 705 * 706 * The callee is responsible for destroying ph with 707 * fuse_pollhandle_destroy() when no longer in use. 708 */ 709 int (*poll) (const char *, struct fuse_file_info *, 710 struct fuse_pollhandle *ph, unsigned *reventsp); 711 712 /** Write contents of buffer to an open file 713 * 714 * Similar to the write() method, but data is supplied in a 715 * generic buffer. Use fuse_buf_copy() to transfer data to 716 * the destination. 717 * 718 * Unless FUSE_CAP_HANDLE_KILLPRIV is disabled, this method is 719 * expected to reset the setuid and setgid bits. 720 */ 721 int (*write_buf) (const char *, struct fuse_bufvec *buf, off_t off, 722 struct fuse_file_info *); 723 724 /** Store data from an open file in a buffer 725 * 726 * Similar to the read() method, but data is stored and 727 * returned in a generic buffer. 728 * 729 * No actual copying of data has to take place, the source 730 * file descriptor may simply be stored in the buffer for 731 * later data transfer. 732 * 733 * The buffer must be allocated dynamically and stored at the 734 * location pointed to by bufp. If the buffer contains memory 735 * regions, they too must be allocated using malloc(). The 736 * allocated memory will be freed by the caller. 737 */ 738 int (*read_buf) (const char *, struct fuse_bufvec **bufp, 739 size_t size, off_t off, struct fuse_file_info *); 740 /** 741 * Perform BSD file locking operation 742 * 743 * The op argument will be either LOCK_SH, LOCK_EX or LOCK_UN 744 * 745 * Nonblocking requests will be indicated by ORing LOCK_NB to 746 * the above operations 747 * 748 * For more information see the flock(2) manual page. 749 * 750 * Additionally fi->owner will be set to a value unique to 751 * this open file. This same value will be supplied to 752 * ->release() when the file is released. 753 * 754 * Note: if this method is not implemented, the kernel will still 755 * allow file locking to work locally. Hence it is only 756 * interesting for network filesystems and similar. 757 */ 758 int (*flock) (const char *, struct fuse_file_info *, int op); 759 760 /** 761 * Allocates space for an open file 762 * 763 * This function ensures that required space is allocated for specified 764 * file. If this function returns success then any subsequent write 765 * request to specified range is guaranteed not to fail because of lack 766 * of space on the file system media. 767 */ 768 int (*fallocate) (const char *, int, off_t, off_t, 769 struct fuse_file_info *); 770 771 /** 772 * Copy a range of data from one file to another 773 * 774 * Performs an optimized copy between two file descriptors without the 775 * additional cost of transferring data through the FUSE kernel module 776 * to user space (glibc) and then back into the FUSE filesystem again. 777 * 778 * In case this method is not implemented, applications are expected to 779 * fall back to a regular file copy. (Some glibc versions did this 780 * emulation automatically, but the emulation has been removed from all 781 * glibc release branches.) 782 */ 783 ssize_t (*copy_file_range) (const char *path_in, 784 struct fuse_file_info *fi_in, 785 off_t offset_in, const char *path_out, 786 struct fuse_file_info *fi_out, 787 off_t offset_out, size_t size, int flags); 788 789 /** 790 * Find next data or hole after the specified offset 791 */ 792 off_t (*lseek) (const char *, off_t off, int whence, struct fuse_file_info *); 793 }; 794 795 /** Extra context that may be needed by some filesystems 796 * 797 * The uid, gid and pid fields are not filled in case of a writepage 798 * operation. 799 */ 800 struct fuse_context { 801 /** Pointer to the fuse object */ 802 struct fuse *fuse; 803 804 /** User ID of the calling process */ 805 uid_t uid; 806 807 /** Group ID of the calling process */ 808 gid_t gid; 809 810 /** Process ID of the calling thread */ 811 pid_t pid; 812 813 /** Private filesystem data */ 814 void *private_data; 815 816 /** Umask of the calling process */ 817 mode_t umask; 818 }; 819 820 /** 821 * Main function of FUSE. 822 * 823 * This is for the lazy. This is all that has to be called from the 824 * main() function. 825 * 826 * This function does the following: 827 * - parses command line options, and handles --help and 828 * --version 829 * - installs signal handlers for INT, HUP, TERM and PIPE 830 * - registers an exit handler to unmount the filesystem on program exit 831 * - creates a fuse handle 832 * - registers the operations 833 * - calls either the single-threaded or the multi-threaded event loop 834 * 835 * Most file systems will have to parse some file-system specific 836 * arguments before calling this function. It is recommended to do 837 * this with fuse_opt_parse() and a processing function that passes 838 * through any unknown options (this can also be achieved by just 839 * passing NULL as the processing function). That way, the remaining 840 * options can be passed directly to fuse_main(). 841 * 842 * fuse_main() accepts all options that can be passed to 843 * fuse_parse_cmdline(), fuse_new(), or fuse_session_new(). 844 * 845 * Option parsing skips argv[0], which is assumed to contain the 846 * program name. This element must always be present and is used to 847 * construct a basic ``usage: `` message for the --help 848 * output. argv[0] may also be set to the empty string. In this case 849 * the usage message is suppressed. This can be used by file systems 850 * to print their own usage line first. See hello.c for an example of 851 * how to do this. 852 * 853 * Note: this is currently implemented as a macro. 854 * 855 * The following error codes may be returned from fuse_main(): 856 * 1: Invalid option arguments 857 * 2: No mount point specified 858 * 3: FUSE setup failed 859 * 4: Mounting failed 860 * 5: Failed to daemonize (detach from session) 861 * 6: Failed to set up signal handlers 862 * 7: An error occurred during the life of the file system 863 * 864 * @param argc the argument counter passed to the main() function 865 * @param argv the argument vector passed to the main() function 866 * @param op the file system operation 867 * @param private_data Initial value for the `private_data` 868 * field of `struct fuse_context`. May be overridden by the 869 * `struct fuse_operations.init` handler. 870 * @return 0 on success, nonzero on failure 871 * 872 * Example usage, see hello.c 873 */ 874 /* 875 int fuse_main(int argc, char *argv[], const struct fuse_operations *op, 876 void *private_data); 877 */ 878 #define fuse_main(argc, argv, op, private_data) \ 879 fuse_main_real(argc, argv, op, sizeof(*(op)), private_data) 880 881 /* ----------------------------------------------------------- * 882 * More detailed API * 883 * ----------------------------------------------------------- */ 884 885 /** 886 * Print available options (high- and low-level) to stdout. This is 887 * not an exhaustive list, but includes only those options that may be 888 * of interest to an end-user of a file system. 889 * 890 * The function looks at the argument vector only to determine if 891 * there are additional modules to be loaded (module=foo option), 892 * and attempts to call their help functions as well. 893 * 894 * @param args the argument vector. 895 */ 896 void fuse_lib_help(struct fuse_args *args); 897 898 /** 899 * Create a new FUSE filesystem. 900 * 901 * This function accepts most file-system independent mount options 902 * (like context, nodev, ro - see mount(8)), as well as the 903 * FUSE-specific mount options from mount.fuse(8). 904 * 905 * If the --help option is specified, the function writes a help text 906 * to stdout and returns NULL. 907 * 908 * Option parsing skips argv[0], which is assumed to contain the 909 * program name. This element must always be present and is used to 910 * construct a basic ``usage: `` message for the --help output. If 911 * argv[0] is set to the empty string, no usage message is included in 912 * the --help output. 913 * 914 * If an unknown option is passed in, an error message is written to 915 * stderr and the function returns NULL. 916 * 917 * @param args argument vector 918 * @param op the filesystem operations 919 * @param op_size the size of the fuse_operations structure 920 * @param private_data Initial value for the `private_data` 921 * field of `struct fuse_context`. May be overridden by the 922 * `struct fuse_operations.init` handler. 923 * @return the created FUSE handle 924 */ 925 #if FUSE_USE_VERSION == 30 926 struct fuse *fuse_new_30(struct fuse_args *args, const struct fuse_operations *op, 927 size_t op_size, void *private_data); 928 #define fuse_new(args, op, size, data) fuse_new_30(args, op, size, data) 929 #else 930 struct fuse *fuse_new(struct fuse_args *args, const struct fuse_operations *op, 931 size_t op_size, void *private_data); 932 #endif 933 934 /** 935 * Mount a FUSE file system. 936 * 937 * @param mountpoint the mount point path 938 * @param f the FUSE handle 939 * 940 * @return 0 on success, -1 on failure. 941 **/ 942 int fuse_mount(struct fuse *f, const char *mountpoint); 943 944 /** 945 * Unmount a FUSE file system. 946 * 947 * See fuse_session_unmount() for additional information. 948 * 949 * @param f the FUSE handle 950 **/ 951 void fuse_unmount(struct fuse *f); 952 953 /** 954 * Destroy the FUSE handle. 955 * 956 * NOTE: This function does not unmount the filesystem. If this is 957 * needed, call fuse_unmount() before calling this function. 958 * 959 * @param f the FUSE handle 960 */ 961 void fuse_destroy(struct fuse *f); 962 963 /** 964 * FUSE event loop. 965 * 966 * Requests from the kernel are processed, and the appropriate 967 * operations are called. 968 * 969 * For a description of the return value and the conditions when the 970 * event loop exits, refer to the documentation of 971 * fuse_session_loop(). 972 * 973 * @param f the FUSE handle 974 * @return see fuse_session_loop() 975 * 976 * See also: fuse_loop_mt() 977 */ 978 int fuse_loop(struct fuse *f); 979 980 /** 981 * Flag session as terminated 982 * 983 * This function will cause any running event loops to exit on 984 * the next opportunity. 985 * 986 * @param f the FUSE handle 987 */ 988 void fuse_exit(struct fuse *f); 989 990 #if FUSE_USE_VERSION < 32 991 int fuse_loop_mt_31(struct fuse *f, int clone_fd); 992 #define fuse_loop_mt(f, clone_fd) fuse_loop_mt_31(f, clone_fd) 993 #else 994 /** 995 * FUSE event loop with multiple threads 996 * 997 * Requests from the kernel are processed, and the appropriate 998 * operations are called. Request are processed in parallel by 999 * distributing them between multiple threads. 1000 * 1001 * For a description of the return value and the conditions when the 1002 * event loop exits, refer to the documentation of 1003 * fuse_session_loop(). 1004 * 1005 * Note: using fuse_loop() instead of fuse_loop_mt() means you are running in 1006 * single-threaded mode, and that you will not have to worry about reentrancy, 1007 * though you will have to worry about recursive lookups. In single-threaded 1008 * mode, FUSE will wait for one callback to return before calling another. 1009 * 1010 * Enabling multiple threads, by using fuse_loop_mt(), will cause FUSE to make 1011 * multiple simultaneous calls into the various callback functions given by your 1012 * fuse_operations record. 1013 * 1014 * If you are using multiple threads, you can enjoy all the parallel execution 1015 * and interactive response benefits of threads, and you get to enjoy all the 1016 * benefits of race conditions and locking bugs, too. Ensure that any code used 1017 * in the callback function of fuse_operations is also thread-safe. 1018 * 1019 * @param f the FUSE handle 1020 * @param config loop configuration 1021 * @return see fuse_session_loop() 1022 * 1023 * See also: fuse_loop() 1024 */ 1025 int fuse_loop_mt(struct fuse *f, struct fuse_loop_config *config); 1026 #endif 1027 1028 /** 1029 * Get the current context 1030 * 1031 * The context is only valid for the duration of a filesystem 1032 * operation, and thus must not be stored and used later. 1033 * 1034 * @return the context 1035 */ 1036 struct fuse_context *fuse_get_context(void); 1037 1038 /** 1039 * Get the current supplementary group IDs for the current request 1040 * 1041 * Similar to the getgroups(2) system call, except the return value is 1042 * always the total number of group IDs, even if it is larger than the 1043 * specified size. 1044 * 1045 * The current fuse kernel module in linux (as of 2.6.30) doesn't pass 1046 * the group list to userspace, hence this function needs to parse 1047 * "/proc/$TID/task/$TID/status" to get the group IDs. 1048 * 1049 * This feature may not be supported on all operating systems. In 1050 * such a case this function will return -ENOSYS. 1051 * 1052 * @param size size of given array 1053 * @param list array of group IDs to be filled in 1054 * @return the total number of supplementary group IDs or -errno on failure 1055 */ 1056 int fuse_getgroups(int size, gid_t list[]); 1057 1058 /** 1059 * Check if the current request has already been interrupted 1060 * 1061 * @return 1 if the request has been interrupted, 0 otherwise 1062 */ 1063 int fuse_interrupted(void); 1064 1065 /** 1066 * Invalidates cache for the given path. 1067 * 1068 * This calls fuse_lowlevel_notify_inval_inode internally. 1069 * 1070 * @return 0 on successful invalidation, negative error value otherwise. 1071 * This routine may return -ENOENT to indicate that there was 1072 * no entry to be invalidated, e.g., because the path has not 1073 * been seen before or has been forgotten; this should not be 1074 * considered to be an error. 1075 */ 1076 int fuse_invalidate_path(struct fuse *f, const char *path); 1077 1078 /** 1079 * The real main function 1080 * 1081 * Do not call this directly, use fuse_main() 1082 */ 1083 int fuse_main_real(int argc, char *argv[], const struct fuse_operations *op, 1084 size_t op_size, void *private_data); 1085 1086 /** 1087 * Start the cleanup thread when using option "remember". 1088 * 1089 * This is done automatically by fuse_loop_mt() 1090 * @param fuse struct fuse pointer for fuse instance 1091 * @return 0 on success and -1 on error 1092 */ 1093 int fuse_start_cleanup_thread(struct fuse *fuse); 1094 1095 /** 1096 * Stop the cleanup thread when using option "remember". 1097 * 1098 * This is done automatically by fuse_loop_mt() 1099 * @param fuse struct fuse pointer for fuse instance 1100 */ 1101 void fuse_stop_cleanup_thread(struct fuse *fuse); 1102 1103 /** 1104 * Iterate over cache removing stale entries 1105 * use in conjunction with "-oremember" 1106 * 1107 * NOTE: This is already done for the standard sessions 1108 * 1109 * @param fuse struct fuse pointer for fuse instance 1110 * @return the number of seconds until the next cleanup 1111 */ 1112 int fuse_clean_cache(struct fuse *fuse); 1113 1114 /* 1115 * Stacking API 1116 */ 1117 1118 /** 1119 * Fuse filesystem object 1120 * 1121 * This is opaque object represents a filesystem layer 1122 */ 1123 struct fuse_fs; 1124 1125 /* 1126 * These functions call the relevant filesystem operation, and return 1127 * the result. 1128 * 1129 * If the operation is not defined, they return -ENOSYS, with the 1130 * exception of fuse_fs_open, fuse_fs_release, fuse_fs_opendir, 1131 * fuse_fs_releasedir and fuse_fs_statfs, which return 0. 1132 */ 1133 1134 int fuse_fs_getattr(struct fuse_fs *fs, const char *path, struct stat *buf, 1135 struct fuse_file_info *fi); 1136 int fuse_fs_rename(struct fuse_fs *fs, const char *oldpath, 1137 const char *newpath, unsigned int flags); 1138 int fuse_fs_unlink(struct fuse_fs *fs, const char *path); 1139 int fuse_fs_rmdir(struct fuse_fs *fs, const char *path); 1140 int fuse_fs_symlink(struct fuse_fs *fs, const char *linkname, 1141 const char *path); 1142 int fuse_fs_link(struct fuse_fs *fs, const char *oldpath, const char *newpath); 1143 int fuse_fs_release(struct fuse_fs *fs, const char *path, 1144 struct fuse_file_info *fi); 1145 int fuse_fs_open(struct fuse_fs *fs, const char *path, 1146 struct fuse_file_info *fi); 1147 int fuse_fs_read(struct fuse_fs *fs, const char *path, char *buf, size_t size, 1148 off_t off, struct fuse_file_info *fi); 1149 int fuse_fs_read_buf(struct fuse_fs *fs, const char *path, 1150 struct fuse_bufvec **bufp, size_t size, off_t off, 1151 struct fuse_file_info *fi); 1152 int fuse_fs_write(struct fuse_fs *fs, const char *path, const char *buf, 1153 size_t size, off_t off, struct fuse_file_info *fi); 1154 int fuse_fs_write_buf(struct fuse_fs *fs, const char *path, 1155 struct fuse_bufvec *buf, off_t off, 1156 struct fuse_file_info *fi); 1157 int fuse_fs_fsync(struct fuse_fs *fs, const char *path, int datasync, 1158 struct fuse_file_info *fi); 1159 int fuse_fs_flush(struct fuse_fs *fs, const char *path, 1160 struct fuse_file_info *fi); 1161 int fuse_fs_statfs(struct fuse_fs *fs, const char *path, struct statvfs *buf); 1162 int fuse_fs_opendir(struct fuse_fs *fs, const char *path, 1163 struct fuse_file_info *fi); 1164 int fuse_fs_readdir(struct fuse_fs *fs, const char *path, void *buf, 1165 fuse_fill_dir_t filler, off_t off, 1166 struct fuse_file_info *fi, enum fuse_readdir_flags flags); 1167 int fuse_fs_fsyncdir(struct fuse_fs *fs, const char *path, int datasync, 1168 struct fuse_file_info *fi); 1169 int fuse_fs_releasedir(struct fuse_fs *fs, const char *path, 1170 struct fuse_file_info *fi); 1171 int fuse_fs_create(struct fuse_fs *fs, const char *path, mode_t mode, 1172 struct fuse_file_info *fi); 1173 int fuse_fs_lock(struct fuse_fs *fs, const char *path, 1174 struct fuse_file_info *fi, int cmd, struct flock *lock); 1175 int fuse_fs_flock(struct fuse_fs *fs, const char *path, 1176 struct fuse_file_info *fi, int op); 1177 int fuse_fs_chmod(struct fuse_fs *fs, const char *path, mode_t mode, 1178 struct fuse_file_info *fi); 1179 int fuse_fs_chown(struct fuse_fs *fs, const char *path, uid_t uid, gid_t gid, 1180 struct fuse_file_info *fi); 1181 int fuse_fs_truncate(struct fuse_fs *fs, const char *path, off_t size, 1182 struct fuse_file_info *fi); 1183 int fuse_fs_utimens(struct fuse_fs *fs, const char *path, 1184 const struct timespec tv[2], struct fuse_file_info *fi); 1185 int fuse_fs_access(struct fuse_fs *fs, const char *path, int mask); 1186 int fuse_fs_readlink(struct fuse_fs *fs, const char *path, char *buf, 1187 size_t len); 1188 int fuse_fs_mknod(struct fuse_fs *fs, const char *path, mode_t mode, 1189 dev_t rdev); 1190 int fuse_fs_mkdir(struct fuse_fs *fs, const char *path, mode_t mode); 1191 int fuse_fs_setxattr(struct fuse_fs *fs, const char *path, const char *name, 1192 const char *value, size_t size, int flags); 1193 int fuse_fs_getxattr(struct fuse_fs *fs, const char *path, const char *name, 1194 char *value, size_t size); 1195 int fuse_fs_listxattr(struct fuse_fs *fs, const char *path, char *list, 1196 size_t size); 1197 int fuse_fs_removexattr(struct fuse_fs *fs, const char *path, 1198 const char *name); 1199 int fuse_fs_bmap(struct fuse_fs *fs, const char *path, size_t blocksize, 1200 uint64_t *idx); 1201 #if FUSE_USE_VERSION < 35 1202 int fuse_fs_ioctl(struct fuse_fs *fs, const char *path, int cmd, 1203 void *arg, struct fuse_file_info *fi, unsigned int flags, 1204 void *data); 1205 #else 1206 int fuse_fs_ioctl(struct fuse_fs *fs, const char *path, unsigned int cmd, 1207 void *arg, struct fuse_file_info *fi, unsigned int flags, 1208 void *data); 1209 #endif 1210 int fuse_fs_poll(struct fuse_fs *fs, const char *path, 1211 struct fuse_file_info *fi, struct fuse_pollhandle *ph, 1212 unsigned *reventsp); 1213 int fuse_fs_fallocate(struct fuse_fs *fs, const char *path, int mode, 1214 off_t offset, off_t length, struct fuse_file_info *fi); 1215 ssize_t fuse_fs_copy_file_range(struct fuse_fs *fs, const char *path_in, 1216 struct fuse_file_info *fi_in, off_t off_in, 1217 const char *path_out, 1218 struct fuse_file_info *fi_out, off_t off_out, 1219 size_t len, int flags); 1220 off_t fuse_fs_lseek(struct fuse_fs *fs, const char *path, off_t off, int whence, 1221 struct fuse_file_info *fi); 1222 void fuse_fs_init(struct fuse_fs *fs, struct fuse_conn_info *conn, 1223 struct fuse_config *cfg); 1224 void fuse_fs_destroy(struct fuse_fs *fs); 1225 1226 int fuse_notify_poll(struct fuse_pollhandle *ph); 1227 1228 /** 1229 * Create a new fuse filesystem object 1230 * 1231 * This is usually called from the factory of a fuse module to create 1232 * a new instance of a filesystem. 1233 * 1234 * @param op the filesystem operations 1235 * @param op_size the size of the fuse_operations structure 1236 * @param private_data Initial value for the `private_data` 1237 * field of `struct fuse_context`. May be overridden by the 1238 * `struct fuse_operations.init` handler. 1239 * @return a new filesystem object 1240 */ 1241 struct fuse_fs *fuse_fs_new(const struct fuse_operations *op, size_t op_size, 1242 void *private_data); 1243 1244 /** 1245 * Factory for creating filesystem objects 1246 * 1247 * The function may use and remove options from 'args' that belong 1248 * to this module. 1249 * 1250 * For now the 'fs' vector always contains exactly one filesystem. 1251 * This is the filesystem which will be below the newly created 1252 * filesystem in the stack. 1253 * 1254 * @param args the command line arguments 1255 * @param fs NULL terminated filesystem object vector 1256 * @return the new filesystem object 1257 */ 1258 typedef struct fuse_fs *(*fuse_module_factory_t)(struct fuse_args *args, 1259 struct fuse_fs *fs[]); 1260 /** 1261 * Register filesystem module 1262 * 1263 * If the "-omodules=*name*_:..." option is present, filesystem 1264 * objects are created and pushed onto the stack with the *factory_* 1265 * function. 1266 * 1267 * @param name_ the name of this filesystem module 1268 * @param factory_ the factory function for this filesystem module 1269 */ 1270 #define FUSE_REGISTER_MODULE(name_, factory_) \ 1271 fuse_module_factory_t fuse_module_ ## name_ ## _factory = factory_ 1272 1273 /** Get session from fuse object */ 1274 struct fuse_session *fuse_get_session(struct fuse *f); 1275 1276 /** 1277 * Open a FUSE file descriptor and set up the mount for the given 1278 * mountpoint and flags. 1279 * 1280 * @param mountpoint reference to the mount in the file system 1281 * @param options mount options 1282 * @return the FUSE file descriptor or -1 upon error 1283 */ 1284 int fuse_open_channel(const char *mountpoint, const char *options); 1285 1286 #ifdef __cplusplus 1287 } 1288 #endif 1289 1290 #endif /* FUSE_H_ */ 1291