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