include/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  * IMPORTANT: you should define FUSE_USE_VERSION before including this
  17  * header.  To use the newest API define it to 26 (recommended for any
  18  * new application), to use the old API define it to 21 (default) 22
  19  * or 25, to use the even older 1.X API define it to 11.
  20  */
  21
  22 #ifndef FUSE_USE_VERSION
  23 #define FUSE_USE_VERSION 21
  24 #endif
  25
  26 #include "fuse_common.h"
  27
  28 #include <fcntl.h>
  29 #include <time.h>
  30 #include <utime.h>
  31 #include <sys/types.h>
  32 #include <sys/stat.h>
  33 #include <sys/statvfs.h>
  34 #include <sys/uio.h>
  35
  36 #ifdef __cplusplus
  37 extern "C" {
  38 #endif
  39
  40 /* ----------------------------------------------------------- *
  41  * Basic FUSE API                                              *
  42  * ----------------------------------------------------------- */
  43
  44 /** Handle for a FUSE filesystem */
  45 struct fuse;
  46
  47 /** Structure containing a raw command */
  48 struct fuse_cmd;
  49
  50 /** Function to add an entry in a readdir() operation
  51  *
  52  * @param buf the buffer passed to the readdir() operation
  53  * @param name the file name of the directory entry
  54  * @param stat file attributes, can be NULL
  55  * @param off offset of the next entry or zero
  56  * @return 1 if buffer is full, zero otherwise
  57  */
  58 typedef int (*fuse_fill_dir_t) (void *buf, const char *name,
  59                                 const struct stat *stbuf, off_t off);
  60
  61 /* Used by deprecated getdir() method */
  62 typedef struct fuse_dirhandle *fuse_dirh_t;
  63 typedef int (*fuse_dirfil_t) (fuse_dirh_t h, const char *name, int type,
  64                               ino_t ino);
  65
  66 /**
  67  * The file system operations:
  68  *
  69  * Most of these should work very similarly to the well known UNIX
  70  * file system operations.  A major exception is that instead of
  71  * returning an error in 'errno', the operation should return the
  72  * negated error value (-errno) directly.
  73  *
  74  * All methods are optional, but some are essential for a useful
  75  * filesystem (e.g. getattr).  Open, flush, release, fsync, opendir,
  76  * releasedir, fsyncdir, access, create, ftruncate, fgetattr, lock,
  77  * init and destroy are special purpose methods, without which a full
  78  * featured filesystem can still be implemented.
  79  *
  80  * Almost all operations take a path which can be of any length.
  81  *
  82  * Changed in fuse 2.8.0 (regardless of API version)
  83  * Previously, paths were limited to a length of PATH_MAX.
  84  *
  85  * See http://fuse.sourceforge.net/wiki/ for more information.  There
  86  * is also a snapshot of the relevant wiki pages in the doc/ folder.
  87  */
  88 struct fuse_operations {
  89         /** Get file attributes.
  90          *
  91          * Similar to stat().  The 'st_dev' and 'st_blksize' fields are
  92          * ignored.      The 'st_ino' field is ignored except if the 'use_ino'
  93          * mount option is given.
  94          */
  95         int (*getattr) (const char *, struct stat *);
  96
  97         /** Read the target of a symbolic link
  98          *
  99          * The buffer should be filled with a null terminated string.  The
 100          * buffer size argument includes the space for the terminating
 101          * null character.      If the linkname is too long to fit in the
 102          * buffer, it should be truncated.      The return value should be 0
 103          * for success.
 104          */
 105         int (*readlink) (const char *, char *, size_t);
 106
 107         /* Deprecated, use readdir() instead */
 108         int (*getdir) (const char *, fuse_dirh_t, fuse_dirfil_t);
 109
 110         /** Create a file node
 111          *
 112          * This is called for creation of all non-directory, non-symlink
 113          * nodes.  If the filesystem defines a create() method, then for
 114          * regular files that will be called instead.
 115          */
 116         int (*mknod) (const char *, mode_t, dev_t);
 117
 118         /** Create a directory
 119          *
 120          * Note that the mode argument may not have the type specification
 121          * bits set, i.e. S_ISDIR(mode) can be false.  To obtain the
 122          * correct directory type bits use  mode|S_IFDIR
 123          * */
 124         int (*mkdir) (const char *, mode_t);
 125
 126         /** Remove a file */
 127         int (*unlink) (const char *);
 128
 129         /** Remove a directory */
 130         int (*rmdir) (const char *);
 131
 132         /** Create a symbolic link */
 133         int (*symlink) (const char *, const char *);
 134
 135         /** Rename a file */
 136         int (*rename) (const char *, const char *);
 137
 138         /** Create a hard link to a file */
 139         int (*link) (const char *, const char *);
 140
 141         /** Change the permission bits of a file */
 142         int (*chmod) (const char *, mode_t);
 143
 144         /** Change the owner and group of a file */
 145         int (*chown) (const char *, uid_t, gid_t);
 146
 147         /** Change the size of a file */
 148         int (*truncate) (const char *, off_t);
 149
 150         /** Change the access and/or modification times of a file
 151          *
 152          * Deprecated, use utimens() instead.
 153          */
 154         int (*utime) (const char *, struct utimbuf *);
 155
 156         /** File open operation
 157          *
 158          * No creation (O_CREAT, O_EXCL) and by default also no
 159          * truncation (O_TRUNC) flags will be passed to open(). If an
 160          * application specifies O_TRUNC, fuse first calls truncate()
 161          * and then open(). Only if 'atomic_o_trunc' has been
 162          * specified and kernel version is 2.6.24 or later, O_TRUNC is
 163          * passed on to open.
 164          *
 165          * Unless the 'default_permissions' mount option is given,
 166          * open should check if the operation is permitted for the
 167          * given flags. Optionally open may also return an arbitrary
 168          * filehandle in the fuse_file_info structure, which will be
 169          * passed to all file operations.
 170          *
 171          * Changed in version 2.2
 172          */
 173         int (*open) (const char *, struct fuse_file_info *);
 174
 175         /** Read data from an open file
 176          *
 177          * Read should return exactly the number of bytes requested except
 178          * on EOF or error, otherwise the rest of the data will be
 179          * substituted with zeroes.      An exception to this is when the
 180          * 'direct_io' mount option is specified, in which case the return
 181          * value of the read system call will reflect the return value of
 182          * this operation.
 183          *
 184          * Changed in version 2.2
 185          */
 186         int (*read) (const char *, char *, size_t, off_t,
 187                      struct fuse_file_info *);
 188
 189         /** Write data to an open file
 190          *
 191          * Write should return exactly the number of bytes requested
 192          * except on error.      An exception to this is when the 'direct_io'
 193          * mount option is specified (see read operation).
 194          *
 195          * Changed in version 2.2
 196          */
 197         int (*write) (const char *, const char *, size_t, off_t,
 198                       struct fuse_file_info *);
 199
 200         /** Get file system statistics
 201          *
 202          * The 'f_frsize', 'f_favail', 'f_fsid' and 'f_flag' fields are ignored
 203          *
 204          * Replaced 'struct statfs' parameter with 'struct statvfs' in
 205          * version 2.5
 206          */
 207         int (*statfs) (const char *, struct statvfs *);
 208
 209         /** Possibly flush cached data
 210          *
 211          * BIG NOTE: This is not equivalent to fsync().  It's not a
 212          * request to sync dirty data.
 213          *
 214          * Flush is called on each close() of a file descriptor.  So if a
 215          * filesystem wants to return write errors in close() and the file
 216          * has cached dirty data, this is a good place to write back data
 217          * and return any errors.  Since many applications ignore close()
 218          * errors this is not always useful.
 219          *
 220          * NOTE: The flush() method may be called more than once for each
 221          * open().      This happens if more than one file descriptor refers
 222          * to an opened file due to dup(), dup2() or fork() calls.      It is
 223          * not possible to determine if a flush is final, so each flush
 224          * should be treated equally.  Multiple write-flush sequences are
 225          * relatively rare, so this shouldn't be a problem.
 226          *
 227          * Filesystems shouldn't assume that flush will always be called
 228          * after some writes, or that if will be called at all.
 229          *
 230          * Changed in version 2.2
 231          */
 232         int (*flush) (const char *, struct fuse_file_info *);
 233
 234         /** Release an open file
 235          *
 236          * Release is called when there are no more references to an open
 237          * file: all file descriptors are closed and all memory mappings
 238          * are unmapped.
 239          *
 240          * For every open() call there will be exactly one release() call
 241          * with the same flags and file descriptor.      It is possible to
 242          * have a file opened more than once, in which case only the last
 243          * release will mean, that no more reads/writes will happen on the
 244          * file.  The return value of release is ignored.
 245          *
 246          * Changed in version 2.2
 247          */
 248         int (*release) (const char *, struct fuse_file_info *);
 249
 250         /** Synchronize file contents
 251          *
 252          * If the datasync parameter is non-zero, then only the user data
 253          * should be flushed, not the meta data.
 254          *
 255          * Changed in version 2.2
 256          */
 257         int (*fsync) (const char *, int, struct fuse_file_info *);
 258
 259         /** Set extended attributes */
 260         int (*setxattr) (const char *, const char *, const char *, size_t, int);
 261
 262         /** Get extended attributes */
 263         int (*getxattr) (const char *, const char *, char *, size_t);
 264
 265         /** List extended attributes */
 266         int (*listxattr) (const char *, char *, size_t);
 267
 268         /** Remove extended attributes */
 269         int (*removexattr) (const char *, const char *);
 270
 271         /** Open directory
 272          *
 273          * Unless the 'default_permissions' mount option is given,
 274          * this method should check if opendir is permitted for this
 275          * directory. Optionally opendir may also return an arbitrary
 276          * filehandle in the fuse_file_info structure, which will be
 277          * passed to readdir, closedir and fsyncdir.
 278          *
 279          * Introduced in version 2.3
 280          */
 281         int (*opendir) (const char *, struct fuse_file_info *);
 282
 283         /** Read directory
 284          *
 285          * This supersedes the old getdir() interface.  New applications
 286          * should use this.
 287          *
 288          * The filesystem may choose between two modes of operation:
 289          *
 290          * 1) The readdir implementation ignores the offset parameter, and
 291          * passes zero to the filler function's offset.  The filler
 292          * function will not return '1' (unless an error happens), so the
 293          * whole directory is read in a single readdir operation.  This
 294          * works just like the old getdir() method.
 295          *
 296          * 2) The readdir implementation keeps track of the offsets of the
 297          * directory entries.  It uses the offset parameter and always
 298          * passes non-zero offset to the filler function.  When the buffer
 299          * is full (or an error happens) the filler function will return
 300          * '1'.
 301          *
 302          * Introduced in version 2.3
 303          */
 304         int (*readdir) (const char *, void *, fuse_fill_dir_t, off_t,
 305                         struct fuse_file_info *);
 306
 307         /** Release directory
 308          *
 309          * Introduced in version 2.3
 310          */
 311         int (*releasedir) (const char *, struct fuse_file_info *);
 312
 313         /** Synchronize directory contents
 314          *
 315          * If the datasync parameter is non-zero, then only the user data
 316          * should be flushed, not the meta data
 317          *
 318          * Introduced in version 2.3
 319          */
 320         int (*fsyncdir) (const char *, int, struct fuse_file_info *);
 321
 322         /**
 323          * Initialize filesystem
 324          *
 325          * The return value will passed in the private_data field of
 326          * fuse_context to all file operations and as a parameter to the
 327          * destroy() method.
 328          *
 329          * Introduced in version 2.3
 330          * Changed in version 2.6
 331          */
 332         void *(*init) (struct fuse_conn_info *conn);
 333
 334         /**
 335          * Clean up filesystem
 336          *
 337          * Called on filesystem exit.
 338          *
 339          * Introduced in version 2.3
 340          */
 341         void (*destroy) (void *);
 342
 343         /**
 344          * Check file access permissions
 345          *
 346          * This will be called for the access() system call.  If the
 347          * 'default_permissions' mount option is given, this method is not
 348          * called.
 349          *
 350          * This method is not called under Linux kernel versions 2.4.x
 351          *
 352          * Introduced in version 2.5
 353          */
 354         int (*access) (const char *, int);
 355
 356         /**
 357          * Create and open a file
 358          *
 359          * If the file does not exist, first create it with the specified
 360          * mode, and then open it.
 361          *
 362          * If this method is not implemented or under Linux kernel
 363          * versions earlier than 2.6.15, the mknod() and open() methods
 364          * will be called instead.
 365          *
 366          * Introduced in version 2.5
 367          */
 368         int (*create) (const char *, mode_t, struct fuse_file_info *);
 369
 370         /**
 371          * Change the size of an open file
 372          *
 373          * This method is called instead of the truncate() method if the
 374          * truncation was invoked from an ftruncate() system call.
 375          *
 376          * If this method is not implemented or under Linux kernel
 377          * versions earlier than 2.6.15, the truncate() method will be
 378          * called instead.
 379          *
 380          * Introduced in version 2.5
 381          */
 382         int (*ftruncate) (const char *, off_t, struct fuse_file_info *);
 383
 384         /**
 385          * Get attributes from an open file
 386          *
 387          * This method is called instead of the getattr() method if the
 388          * file information is available.
 389          *
 390          * Currently this is only called after the create() method if that
 391          * is implemented (see above).  Later it may be called for
 392          * invocations of fstat() too.
 393          *
 394          * Introduced in version 2.5
 395          */
 396         int (*fgetattr) (const char *, struct stat *, struct fuse_file_info *);
 397
 398         /**
 399          * Perform POSIX file locking operation
 400          *
 401          * The cmd argument will be either F_GETLK, F_SETLK or F_SETLKW.
 402          *
 403          * For the meaning of fields in 'struct flock' see the man page
 404          * for fcntl(2).  The l_whence field will always be set to
 405          * SEEK_SET.
 406          *
 407          * For checking lock ownership, the 'fuse_file_info->owner'
 408          * argument must be used.
 409          *
 410          * For F_GETLK operation, the library will first check currently
 411          * held locks, and if a conflicting lock is found it will return
 412          * information without calling this method.      This ensures, that
 413          * for local locks the l_pid field is correctly filled in.      The
 414          * results may not be accurate in case of race conditions and in
 415          * the presence of hard links, but it's unlikely that an
 416          * application would rely on accurate GETLK results in these
 417          * cases.  If a conflicting lock is not found, this method will be
 418          * called, and the filesystem may fill out l_pid by a meaningful
 419          * value, or it may leave this field zero.
 420          *
 421          * For F_SETLK and F_SETLKW the l_pid field will be set to the pid
 422          * of the process performing the locking operation.
 423          *
 424          * Note: if this method is not implemented, the kernel will still
 425          * allow file locking to work locally.  Hence it is only
 426          * interesting for network filesystems and similar.
 427          *
 428          * Introduced in version 2.6
 429          */
 430         int (*lock) (const char *, struct fuse_file_info *, int cmd,
 431                      struct flock *);
 432
 433         /**
 434          * Change the access and modification times of a file with
 435          * nanosecond resolution
 436          *
 437          * This supersedes the old utime() interface.  New applications
 438          * should use this.
 439          *
 440          * See the utimensat(2) man page for details.
 441          *
 442          * Introduced in version 2.6
 443          */
 444         int (*utimens) (const char *, const struct timespec tv[2]);
 445
 446         /**
 447          * Map block index within file to block index within device
 448          *
 449          * Note: This makes sense only for block device backed filesystems
 450          * mounted with the 'blkdev' option
 451          *
 452          * Introduced in version 2.6
 453          */
 454         int (*bmap) (const char *, size_t blocksize, uint64_t *idx);
 455
 456         /**
 457          * Flag indicating that the filesystem can accept a NULL path
 458          * as the first argument for the following operations:
 459          *
 460          * read, write, flush, release, fsync, readdir, releasedir,
 461          * fsyncdir, ftruncate, fgetattr, lock, ioctl and poll
 462          *
 463          * If this flag is set these operations continue to work on
 464          * unlinked files even if "-ohard_remove" option was specified.
 465          */
 466         unsigned int flag_nullpath_ok:1;
 467
 468         /**
 469          * Flag indicating that the path need not be calculated for
 470          * the following operations:
 471          *
 472          * read, write, flush, release, fsync, readdir, releasedir,
 473          * fsyncdir, ftruncate, fgetattr, lock, ioctl and poll
 474          *
 475          * Closely related to flag_nullpath_ok, but if this flag is
 476          * set then the path will not be calculaged even if the file
 477          * wasn't unlinked.  However the path can still be non-NULL if
 478          * it needs to be calculated for some other reason.
 479          */
 480         unsigned int flag_nopath:1;
 481
 482         /**
 483          * Flag indicating that the filesystem accepts special
 484          * UTIME_NOW and UTIME_OMIT values in its utimens operation.
 485          */
 486         unsigned int flag_utime_omit_ok:1;
 487
 488         /**
 489          * Reserved flags, don't set
 490          */
 491         unsigned int flag_reserved:29;
 492
 493         /**
 494          * Ioctl
 495          *
 496          * flags will have FUSE_IOCTL_COMPAT set for 32bit ioctls in
 497          * 64bit environment.  The size and direction of data is
 498          * determined by _IOC_*() decoding of cmd.  For _IOC_NONE,
 499          * data will be NULL, for _IOC_WRITE data is out area, for
 500          * _IOC_READ in area and if both are set in/out area.  In all
 501          * non-NULL cases, the area is of _IOC_SIZE(cmd) bytes.
 502          *
 503          * Introduced in version 2.8
 504          */
 505         int (*ioctl) (const char *, int cmd, void *arg,
 506                       struct fuse_file_info *, unsigned int flags, void *data);
 507
 508         /**
 509          * Poll for IO readiness events
 510          *
 511          * Note: If ph is non-NULL, the client should notify
 512          * when IO readiness events occur by calling
 513          * fuse_notify_poll() with the specified ph.
 514          *
 515          * Regardless of the number of times poll with a non-NULL ph
 516          * is received, single notification is enough to clear all.
 517          * Notifying more times incurs overhead but doesn't harm
 518          * correctness.
 519          *
 520          * The callee is responsible for destroying ph with
 521          * fuse_pollhandle_destroy() when no longer in use.
 522          *
 523          * Introduced in version 2.8
 524          */
 525         int (*poll) (const char *, struct fuse_file_info *,
 526                      struct fuse_pollhandle *ph, unsigned *reventsp);
 527
 528         /** Write contents of buffer to an open file
 529          *
 530          * Similar to the write() method, but data is supplied in a
 531          * generic buffer.  Use fuse_buf_copy() to transfer data to
 532          * the destination.
 533          *
 534          * Introduced in version 2.9
 535          */
 536         int (*write_buf) (const char *, struct fuse_bufvec *buf, off_t off,
 537                           struct fuse_file_info *);
 538
 539         /** Store data from an open file in a buffer
 540          *
 541          * Similar to the read() method, but data is stored and
 542          * returned in a generic buffer.
 543          *
 544          * No actual copying of data has to take place, the source
 545          * file descriptor may simply be stored in the buffer for
 546          * later data transfer.
 547          *
 548          * The buffer must be allocated dynamically and stored at the
 549          * location pointed to by bufp.  If the buffer contains memory
 550          * regions, they too must be allocated using malloc().  The
 551          * allocated memory will be freed by the caller.
 552          *
 553          * Introduced in version 2.9
 554          */
 555         int (*read_buf) (const char *, struct fuse_bufvec **bufp,
 556                          size_t size, off_t off, struct fuse_file_info *);
 557         /**
 558          * Perform BSD file locking operation
 559          *
 560          * The op argument will be either LOCK_SH, LOCK_EX or LOCK_UN
 561          *
 562          * Nonblocking requests will be indicated by ORing LOCK_NB to
 563          * the above operations
 564          *
 565          * For more information see the flock(2) manual page.
 566          *
 567          * Additionally fi->owner will be set to a value unique to
 568          * this open file.  This same value will be supplied to
 569          * ->release() when the file is released.
 570          *
 571          * Note: if this method is not implemented, the kernel will still
 572          * allow file locking to work locally.  Hence it is only
 573          * interesting for network filesystems and similar.
 574          *
 575          * Introduced in version 2.9
 576          */
 577         int (*flock) (const char *, struct fuse_file_info *, int op);
 578
 579         /**
 580          * Allocates space for an open file
 581          *
 582          * This function ensures that required space is allocated for specified
 583          * file.  If this function returns success then any subsequent write
 584          * request to specified range is guaranteed not to fail because of lack
 585          * of space on the file system media.
 586          *
 587          * Introduced in version 2.9.1
 588          */
 589         int (*fallocate) (const char *, int, off_t, off_t,
 590                           struct fuse_file_info *);
 591 };
 592
 593 /** Extra context that may be needed by some filesystems
 594  *
 595  * The uid, gid and pid fields are not filled in case of a writepage
 596  * operation.
 597  */
 598 struct fuse_context {
 599         /** Pointer to the fuse object */
 600         struct fuse *fuse;
 601
 602         /** User ID of the calling process */
 603         uid_t uid;
 604
 605         /** Group ID of the calling process */
 606         gid_t gid;
 607
 608         /** Thread ID of the calling process */
 609         pid_t pid;
 610
 611         /** Private filesystem data */
 612         void *private_data;
 613
 614         /** Umask of the calling process (introduced in version 2.8) */
 615         mode_t umask;
 616 };
 617
 618 /**
 619  * Main function of FUSE.
 620  *
 621  * This is for the lazy.  This is all that has to be called from the
 622  * main() function.
 623  *
 624  * This function does the following:
 625  *   - parses command line options (-d -s and -h)
 626  *   - passes relevant mount options to the fuse_mount()
 627  *   - installs signal handlers for INT, HUP, TERM and PIPE
 628  *   - registers an exit handler to unmount the filesystem on program exit
 629  *   - creates a fuse handle
 630  *   - registers the operations
 631  *   - calls either the single-threaded or the multi-threaded event loop
 632  *
 633  * Note: this is currently implemented as a macro.
 634  *
 635  * @param argc the argument counter passed to the main() function
 636  * @param argv the argument vector passed to the main() function
 637  * @param op the file system operation
 638  * @param user_data user data supplied in the context during the init() method
 639  * @return 0 on success, nonzero on failure
 640  */
 641 /*
 642   int fuse_main(int argc, char *argv[], const struct fuse_operations *op,
 643   void *user_data);
 644 */
 645 #define fuse_main(argc, argv, op, user_data)                            \
 646         fuse_main_real(argc, argv, op, sizeof(*(op)), user_data)
 647
 648 /* ----------------------------------------------------------- *
 649  * More detailed API                                           *
 650  * ----------------------------------------------------------- */
 651
 652 /**
 653  * Create a new FUSE filesystem.
 654  *
 655  * @param ch the communication channel
 656  * @param args argument vector
 657  * @param op the filesystem operations
 658  * @param op_size the size of the fuse_operations structure
 659  * @param user_data user data supplied in the context during the init() method
 660  * @return the created FUSE handle
 661  */
 662 struct fuse *fuse_new(struct fuse_chan *ch, struct fuse_args *args,
 663                       const struct fuse_operations *op, size_t op_size,
 664                       void *user_data);
 665
 666 /**
 667  * Destroy the FUSE handle.
 668  *
 669  * The communication channel attached to the handle is also destroyed.
 670  *
 671  * NOTE: This function does not unmount the filesystem.  If this is
 672  * needed, call fuse_unmount() before calling this function.
 673  *
 674  * @param f the FUSE handle
 675  */
 676 void fuse_destroy(struct fuse *f);
 677
 678 /**
 679  * FUSE event loop.
 680  *
 681  * Requests from the kernel are processed, and the appropriate
 682  * operations are called.
 683  *
 684  * @param f the FUSE handle
 685  * @return 0 if no error occurred, -1 otherwise
 686  */
 687 int fuse_loop(struct fuse *f);
 688
 689 /**
 690  * Exit from event loop
 691  *
 692  * @param f the FUSE handle
 693  */
 694 void fuse_exit(struct fuse *f);
 695
 696 /**
 697  * FUSE event loop with multiple threads
 698  *
 699  * Requests from the kernel are processed, and the appropriate
 700  * operations are called.  Request are processed in parallel by
 701  * distributing them between multiple threads.
 702  *
 703  * Calling this function requires the pthreads library to be linked to
 704  * the application.
 705  *
 706  * @param f the FUSE handle
 707  * @return 0 if no error occurred, -1 otherwise
 708  */
 709 int fuse_loop_mt(struct fuse *f);
 710
 711 /**
 712  * Get the current context
 713  *
 714  * The context is only valid for the duration of a filesystem
 715  * operation, and thus must not be stored and used later.
 716  *
 717  * @return the context
 718  */
 719 struct fuse_context *fuse_get_context(void);
 720
 721 /**
 722  * Get the current supplementary group IDs for the current request
 723  *
 724  * Similar to the getgroups(2) system call, except the return value is
 725  * always the total number of group IDs, even if it is larger than the
 726  * specified size.
 727  *
 728  * The current fuse kernel module in linux (as of 2.6.30) doesn't pass
 729  * the group list to userspace, hence this function needs to parse
 730  * "/proc/$TID/task/$TID/status" to get the group IDs.
 731  *
 732  * This feature may not be supported on all operating systems.  In
 733  * such a case this function will return -ENOSYS.
 734  *
 735  * @param size size of given array
 736  * @param list array of group IDs to be filled in
 737  * @return the total number of supplementary group IDs or -errno on failure
 738  */
 739 int fuse_getgroups(int size, gid_t list[]);
 740
 741 /**
 742  * Check if the current request has already been interrupted
 743  *
 744  * @return 1 if the request has been interrupted, 0 otherwise
 745  */
 746 int fuse_interrupted(void);
 747
 748 /**
 749  * Obsolete, doesn't do anything
 750  *
 751  * @return -EINVAL
 752  */
 753 int fuse_invalidate(struct fuse *f, const char *path);
 754
 755 /* Deprecated, don't use */
 756 int fuse_is_lib_option(const char *opt);
 757
 758 /**
 759  * The real main function
 760  *
 761  * Do not call this directly, use fuse_main()
 762  */
 763 int fuse_main_real(int argc, char *argv[], const struct fuse_operations *op,
 764                    size_t op_size, void *user_data);
 765
 766 /**
 767  * Start the cleanup thread when using option "remember".
 768  *
 769  * This is done automatically by fuse_loop_mt()
 770  * @param fuse struct fuse pointer for fuse instance
 771  * @return 0 on success and -1 on error
 772  */
 773 int fuse_start_cleanup_thread(struct fuse *fuse);
 774
 775 /**
 776  * Stop the cleanup thread when using option "remember".
 777  *
 778  * This is done automatically by fuse_loop_mt()
 779  * @param fuse struct fuse pointer for fuse instance
 780  */
 781 void fuse_stop_cleanup_thread(struct fuse *fuse);
 782
 783 /**
 784  * Iterate over cache removing stale entries
 785  * use in conjunction with "-oremember"
 786  *
 787  * NOTE: This is already done for the standard sessions
 788  *
 789  * @param fuse struct fuse pointer for fuse instance
 790  * @return the number of seconds until the next cleanup
 791  */
 792 int fuse_clean_cache(struct fuse *fuse);
 793
 794 /*
 795  * Stacking API
 796  */
 797
 798 /**
 799  * Fuse filesystem object
 800  *
 801  * This is opaque object represents a filesystem layer
 802  */
 803 struct fuse_fs;
 804
 805 /*
 806  * These functions call the relevant filesystem operation, and return
 807  * the result.
 808  *
 809  * If the operation is not defined, they return -ENOSYS, with the
 810  * exception of fuse_fs_open, fuse_fs_release, fuse_fs_opendir,
 811  * fuse_fs_releasedir and fuse_fs_statfs, which return 0.
 812  */
 813
 814 int fuse_fs_getattr(struct fuse_fs *fs, const char *path, struct stat *buf);
 815 int fuse_fs_fgetattr(struct fuse_fs *fs, const char *path, struct stat *buf,
 816                      struct fuse_file_info *fi);
 817 int fuse_fs_rename(struct fuse_fs *fs, const char *oldpath,
 818                    const char *newpath);
 819 int fuse_fs_unlink(struct fuse_fs *fs, const char *path);
 820 int fuse_fs_rmdir(struct fuse_fs *fs, const char *path);
 821 int fuse_fs_symlink(struct fuse_fs *fs, const char *linkname,
 822                     const char *path);
 823 int fuse_fs_link(struct fuse_fs *fs, const char *oldpath, const char *newpath);
 824 int fuse_fs_release(struct fuse_fs *fs,  const char *path,
 825                     struct fuse_file_info *fi);
 826 int fuse_fs_open(struct fuse_fs *fs, const char *path,
 827                  struct fuse_file_info *fi);
 828 int fuse_fs_read(struct fuse_fs *fs, const char *path, char *buf, size_t size,
 829                  off_t off, struct fuse_file_info *fi);
 830 int fuse_fs_read_buf(struct fuse_fs *fs, const char *path,
 831                      struct fuse_bufvec **bufp, size_t size, off_t off,
 832                      struct fuse_file_info *fi);
 833 int fuse_fs_write(struct fuse_fs *fs, const char *path, const char *buf,
 834                   size_t size, off_t off, struct fuse_file_info *fi);
 835 int fuse_fs_write_buf(struct fuse_fs *fs, const char *path,
 836                       struct fuse_bufvec *buf, off_t off,
 837                       struct fuse_file_info *fi);
 838 int fuse_fs_fsync(struct fuse_fs *fs, const char *path, int datasync,
 839                   struct fuse_file_info *fi);
 840 int fuse_fs_flush(struct fuse_fs *fs, const char *path,
 841                   struct fuse_file_info *fi);
 842 int fuse_fs_statfs(struct fuse_fs *fs, const char *path, struct statvfs *buf);
 843 int fuse_fs_opendir(struct fuse_fs *fs, const char *path,
 844                     struct fuse_file_info *fi);
 845 int fuse_fs_readdir(struct fuse_fs *fs, const char *path, void *buf,
 846                     fuse_fill_dir_t filler, off_t off,
 847                     struct fuse_file_info *fi);
 848 int fuse_fs_fsyncdir(struct fuse_fs *fs, const char *path, int datasync,
 849                      struct fuse_file_info *fi);
 850 int fuse_fs_releasedir(struct fuse_fs *fs, const char *path,
 851                        struct fuse_file_info *fi);
 852 int fuse_fs_create(struct fuse_fs *fs, const char *path, mode_t mode,
 853                    struct fuse_file_info *fi);
 854 int fuse_fs_lock(struct fuse_fs *fs, const char *path,
 855                  struct fuse_file_info *fi, int cmd, struct flock *lock);
 856 int fuse_fs_flock(struct fuse_fs *fs, const char *path,
 857                   struct fuse_file_info *fi, int op);
 858 int fuse_fs_chmod(struct fuse_fs *fs, const char *path, mode_t mode);
 859 int fuse_fs_chown(struct fuse_fs *fs, const char *path, uid_t uid, gid_t gid);
 860 int fuse_fs_truncate(struct fuse_fs *fs, const char *path, off_t size);
 861 int fuse_fs_ftruncate(struct fuse_fs *fs, const char *path, off_t size,
 862                       struct fuse_file_info *fi);
 863 int fuse_fs_utimens(struct fuse_fs *fs, const char *path,
 864                     const struct timespec tv[2]);
 865 int fuse_fs_access(struct fuse_fs *fs, const char *path, int mask);
 866 int fuse_fs_readlink(struct fuse_fs *fs, const char *path, char *buf,
 867                      size_t len);
 868 int fuse_fs_mknod(struct fuse_fs *fs, const char *path, mode_t mode,
 869                   dev_t rdev);
 870 int fuse_fs_mkdir(struct fuse_fs *fs, const char *path, mode_t mode);
 871 int fuse_fs_setxattr(struct fuse_fs *fs, const char *path, const char *name,
 872                      const char *value, size_t size, int flags);
 873 int fuse_fs_getxattr(struct fuse_fs *fs, const char *path, const char *name,
 874                      char *value, size_t size);
 875 int fuse_fs_listxattr(struct fuse_fs *fs, const char *path, char *list,
 876                       size_t size);
 877 int fuse_fs_removexattr(struct fuse_fs *fs, const char *path,
 878                         const char *name);
 879 int fuse_fs_bmap(struct fuse_fs *fs, const char *path, size_t blocksize,
 880                  uint64_t *idx);
 881 int fuse_fs_ioctl(struct fuse_fs *fs, const char *path, int cmd, void *arg,
 882                   struct fuse_file_info *fi, unsigned int flags, void *data);
 883 int fuse_fs_poll(struct fuse_fs *fs, const char *path,
 884                  struct fuse_file_info *fi, struct fuse_pollhandle *ph,
 885                  unsigned *reventsp);
 886 int fuse_fs_fallocate(struct fuse_fs *fs, const char *path, int mode,
 887                  off_t offset, off_t length, struct fuse_file_info *fi);
 888 void fuse_fs_init(struct fuse_fs *fs, struct fuse_conn_info *conn);
 889 void fuse_fs_destroy(struct fuse_fs *fs);
 890
 891 int fuse_notify_poll(struct fuse_pollhandle *ph);
 892
 893 /**
 894  * Create a new fuse filesystem object
 895  *
 896  * This is usually called from the factory of a fuse module to create
 897  * a new instance of a filesystem.
 898  *
 899  * @param op the filesystem operations
 900  * @param op_size the size of the fuse_operations structure
 901  * @param user_data user data supplied in the context during the init() method
 902  * @return a new filesystem object
 903  */
 904 struct fuse_fs *fuse_fs_new(const struct fuse_operations *op, size_t op_size,
 905                             void *user_data);
 906
 907 /**
 908  * Filesystem module
 909  *
 910  * Filesystem modules are registered with the FUSE_REGISTER_MODULE()
 911  * macro.
 912  *
 913  * If the "-omodules=modname:..." option is present, filesystem
 914  * objects are created and pushed onto the stack with the 'factory'
 915  * function.
 916  */
 917 struct fuse_module {
 918         /**
 919          * Name of filesystem
 920          */
 921         const char *name;
 922
 923         /**
 924          * Factory for creating filesystem objects
 925          *
 926          * The function may use and remove options from 'args' that belong
 927          * to this module.
 928          *
 929          * For now the 'fs' vector always contains exactly one filesystem.
 930          * This is the filesystem which will be below the newly created
 931          * filesystem in the stack.
 932          *
 933          * @param args the command line arguments
 934          * @param fs NULL terminated filesystem object vector
 935          * @return the new filesystem object
 936          */
 937         struct fuse_fs *(*factory)(struct fuse_args *args,
 938                                    struct fuse_fs *fs[]);
 939
 940         struct fuse_module *next;
 941         struct fusemod_so *so;
 942         int ctr;
 943 };
 944
 945 /**
 946  * Register a filesystem module
 947  *
 948  * This function is used by FUSE_REGISTER_MODULE and there's usually
 949  * no need to call it directly
 950  */
 951 void fuse_register_module(struct fuse_module *mod);
 952
 953 /**
 954  * Register filesystem module
 955  *
 956  * For the parameters, see description of the fields in 'struct
 957  * fuse_module'
 958  */
 959 #define FUSE_REGISTER_MODULE(name_, factory_)                             \
 960         static __attribute__((constructor)) void name_ ## _register(void) \
 961         {                                                                 \
 962                 static struct fuse_module mod =                           \
 963                         { #name_, factory_, NULL, NULL, 0 };              \
 964                 fuse_register_module(&mod);                               \
 965         }
 966
 967
 968 /* ----------------------------------------------------------- *
 969  * Advanced API for event handling, don't worry about this...  *
 970  * ----------------------------------------------------------- */
 971
 972 /* NOTE: the following functions are deprecated, and will be removed
 973    from the 3.0 API.  Use the lowlevel session functions instead */
 974
 975 /** Function type used to process commands */
 976 typedef void (*fuse_processor_t)(struct fuse *, struct fuse_cmd *, void *);
 977
 978 /** This is the part of fuse_main() before the event loop */
 979 struct fuse *fuse_setup(int argc, char *argv[],
 980                         const struct fuse_operations *op, size_t op_size,
 981                         char **mountpoint, int *multithreaded,
 982                         void *user_data);
 983
 984 /** This is the part of fuse_main() after the event loop */
 985 void fuse_teardown(struct fuse *fuse, char *mountpoint);
 986
 987 /** Read a single command.  If none are read, return NULL */
 988 struct fuse_cmd *fuse_read_cmd(struct fuse *f);
 989
 990 /** Process a single command */
 991 void fuse_process_cmd(struct fuse *f, struct fuse_cmd *cmd);
 992
 993 /** Multi threaded event loop, which calls the custom command
 994     processor function */
 995 int fuse_loop_mt_proc(struct fuse *f, fuse_processor_t proc, void *data);
 996
 997 /** Return the exited flag, which indicates if fuse_exit() has been
 998     called */
 999 int fuse_exited(struct fuse *f);
1000
1001 /** This function is obsolete and implemented as a no-op */
1002 void fuse_set_getcontext_func(struct fuse_context *(*func)(void));
1003
1004 /** Get session from fuse object */
1005 struct fuse_session *fuse_get_session(struct fuse *f);
1006
1007 /* ----------------------------------------------------------- *
1008  * Compatibility stuff                                         *
1009  * ----------------------------------------------------------- */
1010
1011 #if FUSE_USE_VERSION < 26
1012 #  include "fuse_compat.h"
1013 #  undef fuse_main
1014 #  if FUSE_USE_VERSION == 25
1015 #    define fuse_main(argc, argv, op)                           \
1016         fuse_main_real_compat25(argc, argv, op, sizeof(*(op)))
1017 #    define fuse_new fuse_new_compat25
1018 #    define fuse_setup fuse_setup_compat25
1019 #    define fuse_teardown fuse_teardown_compat22
1020 #    define fuse_operations fuse_operations_compat25
1021 #  elif FUSE_USE_VERSION == 22
1022 #    define fuse_main(argc, argv, op)                           \
1023         fuse_main_real_compat22(argc, argv, op, sizeof(*(op)))
1024 #    define fuse_new fuse_new_compat22
1025 #    define fuse_setup fuse_setup_compat22
1026 #    define fuse_teardown fuse_teardown_compat22
1027 #    define fuse_operations fuse_operations_compat22
1028 #    define fuse_file_info fuse_file_info_compat
1029 #  elif FUSE_USE_VERSION == 24
1030 #    error Compatibility with high-level API version 24 not supported
1031 #  else
1032 #    define fuse_dirfil_t fuse_dirfil_t_compat
1033 #    define __fuse_read_cmd fuse_read_cmd
1034 #    define __fuse_process_cmd fuse_process_cmd
1035 #    define __fuse_loop_mt fuse_loop_mt_proc
1036 #    if FUSE_USE_VERSION == 21
1037 #      define fuse_operations fuse_operations_compat2
1038 #      define fuse_main fuse_main_compat2
1039 #      define fuse_new fuse_new_compat2
1040 #      define __fuse_setup fuse_setup_compat2
1041 #      define __fuse_teardown fuse_teardown_compat22
1042 #      define __fuse_exited fuse_exited
1043 #      define __fuse_set_getcontext_func fuse_set_getcontext_func
1044 #    else
1045 #      define fuse_statfs fuse_statfs_compat1
1046 #      define fuse_operations fuse_operations_compat1
1047 #      define fuse_main fuse_main_compat1
1048 #      define fuse_new fuse_new_compat1
1049 #      define FUSE_DEBUG FUSE_DEBUG_COMPAT1
1050 #    endif
1051 #  endif
1052 #endif
1053
1054 #ifdef __cplusplus
1055 }
1056 #endif
1057
1058 #endif /* _FUSE_H_ */