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 17 #include "fuse_common.h" 18 19 #include <fcntl.h> 20 #include <time.h> 21 #include <utime.h> 22 #include <sys/types.h> 23 #include <sys/stat.h> 24 #include <sys/statvfs.h> 25 26 #ifdef __cplusplus 27 extern "C" { 28 #endif 29 30 /* ----------------------------------------------------------- * 31 * Basic FUSE API * 32 * ----------------------------------------------------------- */ 33 34 /** Handle for a FUSE filesystem */ 35 struct fuse; 36 37 /** Structure containing a raw command */ 38 struct fuse_cmd; 39 40 /** Function to add an entry in a readdir() operation 41 * 42 * @param buf the buffer passed to the readdir() operation 43 * @param name the file name of the directory entry 44 * @param stat file attributes, can be NULL 45 * @param off offset of the next entry or zero 46 * @return 1 if buffer is full, zero otherwise 47 */ 48 typedef int (*fuse_fill_dir_t) (void *buf, const char *name, 49 const struct stat *stbuf, off_t off); 50 51 /** 52 * The file system operations: 53 * 54 * Most of these should work very similarly to the well known UNIX 55 * file system operations. A major exception is that instead of 56 * returning an error in 'errno', the operation should return the 57 * negated error value (-errno) directly. 58 * 59 * All methods are optional, but some are essential for a useful 60 * filesystem (e.g. getattr). Open, flush, release, fsync, opendir, 61 * releasedir, fsyncdir, access, create, ftruncate, fgetattr, lock, 62 * init and destroy are special purpose methods, without which a full 63 * featured filesystem can still be implemented. 64 * 65 * Almost all operations take a path which can be of any length. 66 * 67 * Changed in fuse 2.8.0 (regardless of API version) 68 * Previously, paths were limited to a length of PATH_MAX. 69 */ 70 71 struct fuse_operations { 72 /** Get file attributes. 73 * 74 * Similar to stat(). The 'st_dev' and 'st_blksize' fields are 75 * ignored. The 'st_ino' field is ignored except if the 'use_ino' 76 * mount option is given. 77 */ 78 int (*getattr) (const char *, struct stat *); 79 80 /** Read the target of a symbolic link 81 * 82 * The buffer should be filled with a null terminated string. The 83 * buffer size argument includes the space for the terminating 84 * null character. If the linkname is too long to fit in the 85 * buffer, it should be truncated. The return value should be 0 86 * for success. 87 */ 88 int (*readlink) (const char *, char *, size_t); 89 90 /** Create a file node 91 * 92 * This is called for creation of all non-directory, non-symlink 93 * nodes. If the filesystem defines a create() method, then for 94 * regular files that will be called instead. 95 */ 96 int (*mknod) (const char *, mode_t, dev_t); 97 98 /** Create a directory 99 * 100 * Note that the mode argument may not have the type specification 101 * bits set, i.e. S_ISDIR(mode) can be false. To obtain the 102 * correct directory type bits use mode|S_IFDIR 103 * */ 104 int (*mkdir) (const char *, mode_t); 105 106 /** Remove a file */ 107 int (*unlink) (const char *); 108 109 /** Remove a directory */ 110 int (*rmdir) (const char *); 111 112 /** Create a symbolic link */ 113 int (*symlink) (const char *, const char *); 114 115 /** Rename a file */ 116 int (*rename) (const char *, const char *); 117 118 /** Create a hard link to a file */ 119 int (*link) (const char *, const char *); 120 121 /** Change the permission bits of a file */ 122 int (*chmod) (const char *, mode_t); 123 124 /** Change the owner and group of a file */ 125 int (*chown) (const char *, uid_t, gid_t); 126 127 /** Change the size of a file */ 128 int (*truncate) (const char *, off_t); 129 130 /** Change the access and/or modification times of a file 131 * 132 * Deprecated, use utimens() instead. 133 */ 134 int (*utime) (const char *, struct utimbuf *); 135 136 /** File open operation 137 * 138 * No creation (O_CREAT, O_EXCL) and by default also no 139 * truncation (O_TRUNC) flags will be passed to open(). If an 140 * application specifies O_TRUNC, fuse first calls truncate() 141 * and then open(). Only if 'atomic_o_trunc' has been 142 * specified and kernel version is 2.6.24 or later, O_TRUNC is 143 * passed on to open. 144 * 145 * Unless the 'default_permissions' mount option is given, 146 * open should check if the operation is permitted for the 147 * given flags. Optionally open may also return an arbitrary 148 * filehandle in the fuse_file_info structure, which will be 149 * passed to all file operations. 150 * 151 * Changed in version 2.2 152 */ 153 int (*open) (const char *, struct fuse_file_info *); 154 155 /** Read data from an open file 156 * 157 * Read should return exactly the number of bytes requested except 158 * on EOF or error, otherwise the rest of the data will be 159 * substituted with zeroes. An exception to this is when the 160 * 'direct_io' mount option is specified, in which case the return 161 * value of the read system call will reflect the return value of 162 * this operation. 163 * 164 * Changed in version 2.2 165 */ 166 int (*read) (const char *, char *, size_t, off_t, 167 struct fuse_file_info *); 168 169 /** Write data to an open file 170 * 171 * Write should return exactly the number of bytes requested 172 * except on error. An exception to this is when the 'direct_io' 173 * mount option is specified (see read operation). 174 * 175 * Changed in version 2.2 176 */ 177 int (*write) (const char *, const char *, size_t, off_t, 178 struct fuse_file_info *); 179 180 /** Get file system statistics 181 * 182 * The 'f_frsize', 'f_favail', 'f_fsid' and 'f_flag' fields are ignored 183 * 184 * Replaced 'struct statfs' parameter with 'struct statvfs' in 185 * version 2.5 186 */ 187 int (*statfs) (const char *, struct statvfs *); 188 189 /** Possibly flush cached data 190 * 191 * BIG NOTE: This is not equivalent to fsync(). It's not a 192 * request to sync dirty data. 193 * 194 * Flush is called on each close() of a file descriptor. So if a 195 * filesystem wants to return write errors in close() and the file 196 * has cached dirty data, this is a good place to write back data 197 * and return any errors. Since many applications ignore close() 198 * errors this is not always useful. 199 * 200 * NOTE: The flush() method may be called more than once for each 201 * open(). This happens if more than one file descriptor refers 202 * to an opened file due to dup(), dup2() or fork() calls. It is 203 * not possible to determine if a flush is final, so each flush 204 * should be treated equally. Multiple write-flush sequences are 205 * relatively rare, so this shouldn't be a problem. 206 * 207 * Filesystems shouldn't assume that flush will always be called 208 * after some writes, or that if will be called at all. 209 * 210 * Changed in version 2.2 211 */ 212 int (*flush) (const char *, struct fuse_file_info *); 213 214 /** Release an open file 215 * 216 * Release is called when there are no more references to an open 217 * file: all file descriptors are closed and all memory mappings 218 * are unmapped. 219 * 220 * For every open() call there will be exactly one release() call 221 * with the same flags and file descriptor. It is possible to 222 * have a file opened more than once, in which case only the last 223 * release will mean, that no more reads/writes will happen on the 224 * file. The return value of release is ignored. 225 * 226 * Changed in version 2.2 227 */ 228 int (*release) (const char *, struct fuse_file_info *); 229 230 /** Synchronize file contents 231 * 232 * If the datasync parameter is non-zero, then only the user data 233 * should be flushed, not the meta data. 234 * 235 * Changed in version 2.2 236 */ 237 int (*fsync) (const char *, int, struct fuse_file_info *); 238 239 /** Set extended attributes */ 240 int (*setxattr) (const char *, const char *, const char *, size_t, int); 241 242 /** Get extended attributes */ 243 int (*getxattr) (const char *, const char *, char *, size_t); 244 245 /** List extended attributes */ 246 int (*listxattr) (const char *, char *, size_t); 247 248 /** Remove extended attributes */ 249 int (*removexattr) (const char *, const char *); 250 251 /** Open directory 252 * 253 * This method should check if the open operation is permitted for 254 * this directory 255 * 256 * Introduced in version 2.3 257 */ 258 int (*opendir) (const char *, struct fuse_file_info *); 259 260 /** Read directory 261 * 262 * The filesystem may choose between two modes of operation: 263 * 264 * 1) The readdir implementation ignores the offset parameter, and 265 * passes zero to the filler function's offset. The filler 266 * function will not return '1' (unless an error happens), so the 267 * whole directory is read in a single readdir operation. 268 * 269 * 2) The readdir implementation keeps track of the offsets of the 270 * directory entries. It uses the offset parameter and always 271 * passes non-zero offset to the filler function. When the buffer 272 * is full (or an error happens) the filler function will return 273 * '1'. 274 * 275 * Introduced in version 2.3 276 */ 277 int (*readdir) (const char *, void *, fuse_fill_dir_t, off_t, 278 struct fuse_file_info *); 279 280 /** Release directory 281 * 282 * Introduced in version 2.3 283 */ 284 int (*releasedir) (const char *, struct fuse_file_info *); 285 286 /** Synchronize directory contents 287 * 288 * If the datasync parameter is non-zero, then only the user data 289 * should be flushed, not the meta data 290 * 291 * Introduced in version 2.3 292 */ 293 int (*fsyncdir) (const char *, int, struct fuse_file_info *); 294 295 /** 296 * Initialize filesystem 297 * 298 * The return value will passed in the private_data field of 299 * fuse_context to all file operations and as a parameter to the 300 * destroy() method. 301 * 302 * Introduced in version 2.3 303 * Changed in version 2.6 304 */ 305 void *(*init) (struct fuse_conn_info *conn); 306 307 /** 308 * Clean up filesystem 309 * 310 * Called on filesystem exit. 311 * 312 * Introduced in version 2.3 313 */ 314 void (*destroy) (void *); 315 316 /** 317 * Check file access permissions 318 * 319 * This will be called for the access() system call. If the 320 * 'default_permissions' mount option is given, this method is not 321 * called. 322 * 323 * This method is not called under Linux kernel versions 2.4.x 324 * 325 * Introduced in version 2.5 326 */ 327 int (*access) (const char *, int); 328 329 /** 330 * Create and open a file 331 * 332 * If the file does not exist, first create it with the specified 333 * mode, and then open it. 334 * 335 * If this method is not implemented or under Linux kernel 336 * versions earlier than 2.6.15, the mknod() and open() methods 337 * will be called instead. 338 * 339 * Introduced in version 2.5 340 */ 341 int (*create) (const char *, mode_t, struct fuse_file_info *); 342 343 /** 344 * Change the size of an open file 345 * 346 * This method is called instead of the truncate() method if the 347 * truncation was invoked from an ftruncate() system call. 348 * 349 * If this method is not implemented or under Linux kernel 350 * versions earlier than 2.6.15, the truncate() method will be 351 * called instead. 352 * 353 * Introduced in version 2.5 354 */ 355 int (*ftruncate) (const char *, off_t, struct fuse_file_info *); 356 357 /** 358 * Get attributes from an open file 359 * 360 * This method is called instead of the getattr() method if the 361 * file information is available. 362 * 363 * Currently this is only called after the create() method if that 364 * is implemented (see above). Later it may be called for 365 * invocations of fstat() too. 366 * 367 * Introduced in version 2.5 368 */ 369 int (*fgetattr) (const char *, struct stat *, struct fuse_file_info *); 370 371 /** 372 * Perform POSIX file locking operation 373 * 374 * The cmd argument will be either F_GETLK, F_SETLK or F_SETLKW. 375 * 376 * For the meaning of fields in 'struct flock' see the man page 377 * for fcntl(2). The l_whence field will always be set to 378 * SEEK_SET. 379 * 380 * For checking lock ownership, the 'fuse_file_info->owner' 381 * argument must be used. 382 * 383 * For F_GETLK operation, the library will first check currently 384 * held locks, and if a conflicting lock is found it will return 385 * information without calling this method. This ensures, that 386 * for local locks the l_pid field is correctly filled in. The 387 * results may not be accurate in case of race conditions and in 388 * the presence of hard links, but it's unlikly that an 389 * application would rely on accurate GETLK results in these 390 * cases. If a conflicting lock is not found, this method will be 391 * called, and the filesystem may fill out l_pid by a meaningful 392 * value, or it may leave this field zero. 393 * 394 * For F_SETLK and F_SETLKW the l_pid field will be set to the pid 395 * of the process performing the locking operation. 396 * 397 * Note: if this method is not implemented, the kernel will still 398 * allow file locking to work locally. Hence it is only 399 * interesting for network filesystems and similar. 400 * 401 * Introduced in version 2.6 402 */ 403 int (*lock) (const char *, struct fuse_file_info *, int cmd, 404 struct flock *); 405 406 /** 407 * Change the access and modification times of a file with 408 * nanosecond resolution 409 * 410 * Introduced in version 2.6 411 */ 412 int (*utimens) (const char *, const struct timespec tv[2]); 413 414 /** 415 * Map block index within file to block index within device 416 * 417 * Note: This makes sense only for block device backed filesystems 418 * mounted with the 'blkdev' option 419 * 420 * Introduced in version 2.6 421 */ 422 int (*bmap) (const char *, size_t blocksize, uint64_t *idx); 423 424 /** 425 * Ioctl 426 * 427 * flags will have FUSE_IOCTL_COMPAT set for 32bit ioctls in 428 * 64bit environment. The size and direction of data is 429 * determined by _IOC_*() decoding of cmd. For _IOC_NONE, 430 * data will be NULL, for _IOC_WRITE data is out area, for 431 * _IOC_READ in area and if both are set in/out area. In all 432 * non-NULL cases, the area is of _IOC_SIZE(cmd) bytes. 433 * 434 * Introduced in version 2.8 435 * 436 * Note : the unsigned long request submitted by the application 437 * is truncated to 32 bits, and forwarded as a signed int. 438 */ 439 int (*ioctl) (const char *, int cmd, void *arg, 440 struct fuse_file_info *, unsigned int flags, void *data); 441 442 /* 443 * The flags below have been discarded, they should not be used 444 */ 445 unsigned int flag_nullpath_ok : 1; 446 /** 447 * Reserved flags, don't set 448 */ 449 unsigned int flag_reserved : 30; 450 451 }; 452 453 /** Extra context that may be needed by some filesystems 454 * 455 * The uid, gid and pid fields are not filled in case of a writepage 456 * operation. 457 */ 458 struct fuse_context { 459 /** Pointer to the fuse object */ 460 struct fuse *fuse; 461 462 /** User ID of the calling process */ 463 uid_t uid; 464 465 /** Group ID of the calling process */ 466 gid_t gid; 467 468 /** Thread ID of the calling process */ 469 pid_t pid; 470 471 /** Private filesystem data */ 472 void *private_data; 473 474 /** Umask of the calling process (introduced in version 2.8) */ 475 mode_t umask; 476 }; 477 478 /* ----------------------------------------------------------- * 479 * More detailed API * 480 * ----------------------------------------------------------- */ 481 482 /** 483 * Create a new FUSE filesystem. 484 * 485 * @param ch the communication channel 486 * @param args argument vector 487 * @param op the filesystem operations 488 * @param op_size the size of the fuse_operations structure 489 * @param user_data user data supplied in the context during the init() method 490 * @return the created FUSE handle 491 */ 492 struct fuse *fuse_new(struct fuse_chan *ch, struct fuse_args *args, 493 const struct fuse_operations *op, size_t op_size, 494 void *user_data); 495 496 /** 497 * Destroy the FUSE handle. 498 * 499 * The communication channel attached to the handle is also destroyed. 500 * 501 * NOTE: This function does not unmount the filesystem. If this is 502 * needed, call fuse_unmount() before calling this function. 503 * 504 * @param f the FUSE handle 505 */ 506 void fuse_destroy(struct fuse *f); 507 508 /** 509 * FUSE event loop. 510 * 511 * Requests from the kernel are processed, and the appropriate 512 * operations are called. 513 * 514 * @param f the FUSE handle 515 * @return 0 if no error occurred, -1 otherwise 516 */ 517 int fuse_loop(struct fuse *f); 518 519 /** 520 * Exit from event loop 521 * 522 * @param f the FUSE handle 523 */ 524 void fuse_exit(struct fuse *f); 525 526 /** 527 * Get the current context 528 * 529 * The context is only valid for the duration of a filesystem 530 * operation, and thus must not be stored and used later. 531 * 532 * @return the context 533 */ 534 struct fuse_context *fuse_get_context(void); 535 536 /** 537 * Check if a request has already been interrupted 538 * 539 * @param req request handle 540 * @return 1 if the request has been interrupted, 0 otherwise 541 */ 542 int fuse_interrupted(void); 543 544 /* 545 * Stacking API 546 */ 547 548 /** 549 * Fuse filesystem object 550 * 551 * This is opaque object represents a filesystem layer 552 */ 553 struct fuse_fs; 554 555 /* 556 * These functions call the relevant filesystem operation, and return 557 * the result. 558 * 559 * If the operation is not defined, they return -ENOSYS, with the 560 * exception of fuse_fs_open, fuse_fs_release, fuse_fs_opendir, 561 * fuse_fs_releasedir and fuse_fs_statfs, which return 0. 562 */ 563 564 int fuse_fs_getattr(struct fuse_fs *fs, const char *path, struct stat *buf); 565 int fuse_fs_fgetattr(struct fuse_fs *fs, const char *path, struct stat *buf, 566 struct fuse_file_info *fi); 567 int fuse_fs_rename(struct fuse_fs *fs, const char *oldpath, 568 const char *newpath); 569 int fuse_fs_unlink(struct fuse_fs *fs, const char *path); 570 int fuse_fs_rmdir(struct fuse_fs *fs, const char *path); 571 int fuse_fs_symlink(struct fuse_fs *fs, const char *linkname, 572 const char *path); 573 int fuse_fs_link(struct fuse_fs *fs, const char *oldpath, const char *newpath); 574 int fuse_fs_release(struct fuse_fs *fs, const char *path, 575 struct fuse_file_info *fi); 576 int fuse_fs_open(struct fuse_fs *fs, const char *path, 577 struct fuse_file_info *fi); 578 int fuse_fs_read(struct fuse_fs *fs, const char *path, char *buf, size_t size, 579 off_t off, struct fuse_file_info *fi); 580 int fuse_fs_write(struct fuse_fs *fs, const char *path, const char *buf, 581 size_t size, off_t off, struct fuse_file_info *fi); 582 int fuse_fs_fsync(struct fuse_fs *fs, const char *path, int datasync, 583 struct fuse_file_info *fi); 584 int fuse_fs_flush(struct fuse_fs *fs, const char *path, 585 struct fuse_file_info *fi); 586 int fuse_fs_statfs(struct fuse_fs *fs, const char *path, struct statvfs *buf); 587 int fuse_fs_opendir(struct fuse_fs *fs, const char *path, 588 struct fuse_file_info *fi); 589 int fuse_fs_readdir(struct fuse_fs *fs, const char *path, void *buf, 590 fuse_fill_dir_t filler, off_t off, 591 struct fuse_file_info *fi); 592 int fuse_fs_fsyncdir(struct fuse_fs *fs, const char *path, int datasync, 593 struct fuse_file_info *fi); 594 int fuse_fs_releasedir(struct fuse_fs *fs, const char *path, 595 struct fuse_file_info *fi); 596 int fuse_fs_create(struct fuse_fs *fs, const char *path, mode_t mode, 597 struct fuse_file_info *fi); 598 int fuse_fs_lock(struct fuse_fs *fs, const char *path, 599 struct fuse_file_info *fi, int cmd, struct flock *lock); 600 int fuse_fs_chmod(struct fuse_fs *fs, const char *path, mode_t mode); 601 int fuse_fs_chown(struct fuse_fs *fs, const char *path, uid_t uid, gid_t gid); 602 int fuse_fs_truncate(struct fuse_fs *fs, const char *path, off_t size); 603 int fuse_fs_ftruncate(struct fuse_fs *fs, const char *path, off_t size, 604 struct fuse_file_info *fi); 605 int fuse_fs_utimens(struct fuse_fs *fs, const char *path, 606 const struct timespec tv[2]); 607 int fuse_fs_access(struct fuse_fs *fs, const char *path, int mask); 608 int fuse_fs_readlink(struct fuse_fs *fs, const char *path, char *buf, 609 size_t len); 610 int fuse_fs_mknod(struct fuse_fs *fs, const char *path, mode_t mode, 611 dev_t rdev); 612 int fuse_fs_mkdir(struct fuse_fs *fs, const char *path, mode_t mode); 613 int fuse_fs_setxattr(struct fuse_fs *fs, const char *path, const char *name, 614 const char *value, size_t size, int flags); 615 int fuse_fs_getxattr(struct fuse_fs *fs, const char *path, const char *name, 616 char *value, size_t size); 617 int fuse_fs_listxattr(struct fuse_fs *fs, const char *path, char *list, 618 size_t size); 619 int fuse_fs_removexattr(struct fuse_fs *fs, const char *path, 620 const char *name); 621 int fuse_fs_bmap(struct fuse_fs *fs, const char *path, size_t blocksize, 622 uint64_t *idx); 623 int fuse_fs_ioctl(struct fuse_fs *fs, const char *path, int cmd, void *arg, 624 struct fuse_file_info *fi, unsigned int flags, void *data); 625 void fuse_fs_init(struct fuse_fs *fs, struct fuse_conn_info *conn); 626 void fuse_fs_destroy(struct fuse_fs *fs); 627 628 /** 629 * Create a new fuse filesystem object 630 * 631 * This is usually called from the factory of a fuse module to create 632 * a new instance of a filesystem. 633 * 634 * @param op the filesystem operations 635 * @param op_size the size of the fuse_operations structure 636 * @param user_data user data supplied in the context during the init() method 637 * @return a new filesystem object 638 */ 639 struct fuse_fs *fuse_fs_new(const struct fuse_operations *op, size_t op_size, 640 void *user_data); 641 642 #ifdef __SOLARIS__ 643 644 /** 645 * Filesystem module 646 * 647 * Filesystem modules are registered with the FUSE_REGISTER_MODULE() 648 * macro. 649 * 650 * If the "-omodules=modname:..." option is present, filesystem 651 * objects are created and pushed onto the stack with the 'factory' 652 * function. 653 */ 654 struct fuse_module { 655 /** 656 * Name of filesystem 657 */ 658 const char *name; 659 660 /** 661 * Factory for creating filesystem objects 662 * 663 * The function may use and remove options from 'args' that belong 664 * to this module. 665 * 666 * For now the 'fs' vector always contains exactly one filesystem. 667 * This is the filesystem which will be below the newly created 668 * filesystem in the stack. 669 * 670 * @param args the command line arguments 671 * @param fs NULL terminated filesystem object vector 672 * @return the new filesystem object 673 */ 674 struct fuse_fs *(*factory)(struct fuse_args *args, struct fuse_fs *fs[]); 675 676 struct fuse_module *next; 677 struct fusemod_so *so; 678 int ctr; 679 }; 680 681 #endif /* __SOLARIS__ */ 682 683 /* ----------------------------------------------------------- * 684 * Advanced API for event handling, don't worry about this... * 685 * ----------------------------------------------------------- */ 686 687 /* NOTE: the following functions are deprecated, and will be removed 688 from the 3.0 API. Use the lowlevel session functions instead */ 689 690 /** Get session from fuse object */ 691 struct fuse_session *fuse_get_session(struct fuse *f); 692 693 #ifdef __cplusplus 694 } 695 #endif 696 697 #endif /* _FUSE_H_ */ 698