release/src/router/ntfs-3g/include/fuse-lite/fuse.h

   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         unsigned int flag_nullpath_ok : 1;
 424
 425         /**
 426          * Flag indicating that the filesystem accepts special
 427          * UTIME_NOW and UTIME_OMIT values in its utimens operation.
 428          */
 429         unsigned int flag_utime_omit_ok : 1;
 430
 431         /**
 432          * Reserved flags, don't set
 433          */
 434         unsigned int flag_reserved : 30;
 435
 436 };
 437
 438 /** Extra context that may be needed by some filesystems
 439  *
 440  * The uid, gid and pid fields are not filled in case of a writepage
 441  * operation.
 442  */
 443 struct fuse_context {
 444         /** Pointer to the fuse object */
 445         struct fuse *fuse;
 446
 447         /** User ID of the calling process */
 448         uid_t uid;
 449
 450         /** Group ID of the calling process */
 451         gid_t gid;
 452
 453         /** Thread ID of the calling process */
 454         pid_t pid;
 455
 456         /** Private filesystem data */
 457         void *private_data;
 458
 459 #ifdef POSIXACLS
 460         /** Umask of the calling process (introduced in version 2.8) */
 461         mode_t umask;
 462 #endif
 463 };
 464
 465 /* ----------------------------------------------------------- *
 466  * More detailed API                                           *
 467  * ----------------------------------------------------------- */
 468
 469 /**
 470  * Create a new FUSE filesystem.
 471  *
 472  * @param ch the communication channel
 473  * @param args argument vector
 474  * @param op the filesystem operations
 475  * @param op_size the size of the fuse_operations structure
 476  * @param user_data user data supplied in the context during the init() method
 477  * @return the created FUSE handle
 478  */
 479 struct fuse *fuse_new(struct fuse_chan *ch, struct fuse_args *args,
 480                       const struct fuse_operations *op, size_t op_size,
 481                       void *user_data);
 482
 483 /**
 484  * Destroy the FUSE handle.
 485  *
 486  * The communication channel attached to the handle is also destroyed.
 487  *
 488  * NOTE: This function does not unmount the filesystem.  If this is
 489  * needed, call fuse_unmount() before calling this function.
 490  *
 491  * @param f the FUSE handle
 492  */
 493 void fuse_destroy(struct fuse *f);
 494
 495 /**
 496  * FUSE event loop.
 497  *
 498  * Requests from the kernel are processed, and the appropriate
 499  * operations are called.
 500  *
 501  * @param f the FUSE handle
 502  * @return 0 if no error occurred, -1 otherwise
 503  */
 504 int fuse_loop(struct fuse *f);
 505
 506 /**
 507  * Exit from event loop
 508  *
 509  * @param f the FUSE handle
 510  */
 511 void fuse_exit(struct fuse *f);
 512
 513 /**
 514  * Get the current context
 515  *
 516  * The context is only valid for the duration of a filesystem
 517  * operation, and thus must not be stored and used later.
 518  *
 519  * @return the context
 520  */
 521 struct fuse_context *fuse_get_context(void);
 522
 523 /**
 524  * Check if a request has already been interrupted
 525  *
 526  * @param req request handle
 527  * @return 1 if the request has been interrupted, 0 otherwise
 528  */
 529 int fuse_interrupted(void);
 530
 531 /*
 532  * Stacking API
 533  */
 534
 535 /**
 536  * Fuse filesystem object
 537  *
 538  * This is opaque object represents a filesystem layer
 539  */
 540 struct fuse_fs;
 541
 542 /*
 543  * These functions call the relevant filesystem operation, and return
 544  * the result.
 545  *
 546  * If the operation is not defined, they return -ENOSYS, with the
 547  * exception of fuse_fs_open, fuse_fs_release, fuse_fs_opendir,
 548  * fuse_fs_releasedir and fuse_fs_statfs, which return 0.
 549  */
 550
 551 int fuse_fs_getattr(struct fuse_fs *fs, const char *path, struct stat *buf);
 552 int fuse_fs_fgetattr(struct fuse_fs *fs, const char *path, struct stat *buf,
 553                      struct fuse_file_info *fi);
 554 int fuse_fs_rename(struct fuse_fs *fs, const char *oldpath,
 555                    const char *newpath);
 556 int fuse_fs_unlink(struct fuse_fs *fs, const char *path);
 557 int fuse_fs_rmdir(struct fuse_fs *fs, const char *path);
 558 int fuse_fs_symlink(struct fuse_fs *fs, const char *linkname,
 559                     const char *path);
 560 int fuse_fs_link(struct fuse_fs *fs, const char *oldpath, const char *newpath);
 561 int fuse_fs_release(struct fuse_fs *fs,  const char *path,
 562                     struct fuse_file_info *fi);
 563 int fuse_fs_open(struct fuse_fs *fs, const char *path,
 564                  struct fuse_file_info *fi);
 565 int fuse_fs_read(struct fuse_fs *fs, const char *path, char *buf, size_t size,
 566                  off_t off, struct fuse_file_info *fi);
 567 int fuse_fs_write(struct fuse_fs *fs, const char *path, const char *buf,
 568                   size_t size, off_t off, struct fuse_file_info *fi);
 569 int fuse_fs_fsync(struct fuse_fs *fs, const char *path, int datasync,
 570                   struct fuse_file_info *fi);
 571 int fuse_fs_flush(struct fuse_fs *fs, const char *path,
 572                   struct fuse_file_info *fi);
 573 int fuse_fs_statfs(struct fuse_fs *fs, const char *path, struct statvfs *buf);
 574 int fuse_fs_opendir(struct fuse_fs *fs, const char *path,
 575                     struct fuse_file_info *fi);
 576 int fuse_fs_readdir(struct fuse_fs *fs, const char *path, void *buf,
 577                     fuse_fill_dir_t filler, off_t off,
 578                     struct fuse_file_info *fi);
 579 int fuse_fs_fsyncdir(struct fuse_fs *fs, const char *path, int datasync,
 580                      struct fuse_file_info *fi);
 581 int fuse_fs_releasedir(struct fuse_fs *fs, const char *path,
 582                        struct fuse_file_info *fi);
 583 int fuse_fs_create(struct fuse_fs *fs, const char *path, mode_t mode,
 584                    struct fuse_file_info *fi);
 585 int fuse_fs_lock(struct fuse_fs *fs, const char *path,
 586                  struct fuse_file_info *fi, int cmd, struct flock *lock);
 587 int fuse_fs_chmod(struct fuse_fs *fs, const char *path, mode_t mode);
 588 int fuse_fs_chown(struct fuse_fs *fs, const char *path, uid_t uid, gid_t gid);
 589 int fuse_fs_truncate(struct fuse_fs *fs, const char *path, off_t size);
 590 int fuse_fs_ftruncate(struct fuse_fs *fs, const char *path, off_t size,
 591                       struct fuse_file_info *fi);
 592 int fuse_fs_utimens(struct fuse_fs *fs, const char *path,
 593                     const struct timespec tv[2]);
 594 int fuse_fs_access(struct fuse_fs *fs, const char *path, int mask);
 595 int fuse_fs_readlink(struct fuse_fs *fs, const char *path, char *buf,
 596                      size_t len);
 597 int fuse_fs_mknod(struct fuse_fs *fs, const char *path, mode_t mode,
 598                   dev_t rdev);
 599 int fuse_fs_mkdir(struct fuse_fs *fs, const char *path, mode_t mode);
 600 int fuse_fs_setxattr(struct fuse_fs *fs, const char *path, const char *name,
 601                      const char *value, size_t size, int flags);
 602 int fuse_fs_getxattr(struct fuse_fs *fs, const char *path, const char *name,
 603                      char *value, size_t size);
 604 int fuse_fs_listxattr(struct fuse_fs *fs, const char *path, char *list,
 605                       size_t size);
 606 int fuse_fs_removexattr(struct fuse_fs *fs, const char *path,
 607                         const char *name);
 608 int fuse_fs_bmap(struct fuse_fs *fs, const char *path, size_t blocksize,
 609                  uint64_t *idx);
 610 void fuse_fs_init(struct fuse_fs *fs, struct fuse_conn_info *conn);
 611 void fuse_fs_destroy(struct fuse_fs *fs);
 612
 613 /**
 614  * Create a new fuse filesystem object
 615  *
 616  * This is usually called from the factory of a fuse module to create
 617  * a new instance of a filesystem.
 618  *
 619  * @param op the filesystem operations
 620  * @param op_size the size of the fuse_operations structure
 621  * @param user_data user data supplied in the context during the init() method
 622  * @return a new filesystem object
 623  */
 624 struct fuse_fs *fuse_fs_new(const struct fuse_operations *op, size_t op_size,
 625                             void *user_data);
 626
 627 #ifdef __SOLARIS__
 628
 629 /**
 630  * Filesystem module
 631  *
 632  * Filesystem modules are registered with the FUSE_REGISTER_MODULE()
 633  * macro.
 634  *
 635  * If the "-omodules=modname:..." option is present, filesystem
 636  * objects are created and pushed onto the stack with the 'factory'
 637  * function.
 638  */
 639 struct fuse_module {
 640     /**
 641      * Name of filesystem
 642      */
 643     const char *name;
 644
 645     /**
 646      * Factory for creating filesystem objects
 647      *
 648      * The function may use and remove options from 'args' that belong
 649      * to this module.
 650      *
 651      * For now the 'fs' vector always contains exactly one filesystem.
 652      * This is the filesystem which will be below the newly created
 653      * filesystem in the stack.
 654      *
 655      * @param args the command line arguments
 656      * @param fs NULL terminated filesystem object vector
 657      * @return the new filesystem object
 658      */
 659     struct fuse_fs *(*factory)(struct fuse_args *args, struct fuse_fs *fs[]);
 660
 661     struct fuse_module *next;
 662     struct fusemod_so *so;
 663     int ctr;
 664 };
 665
 666 #endif /* __SOLARIS__ */
 667
 668 /* ----------------------------------------------------------- *
 669  * Advanced API for event handling, don't worry about this...  *
 670  * ----------------------------------------------------------- */
 671
 672 /* NOTE: the following functions are deprecated, and will be removed
 673    from the 3.0 API.  Use the lowlevel session functions instead */
 674
 675 /** Get session from fuse object */
 676 struct fuse_session *fuse_get_session(struct fuse *f);
 677
 678 #ifdef __cplusplus
 679 }
 680 #endif
 681
 682 #endif /* _FUSE_H_ */