"Fossies" - the Fresh Open Source Software Archive

Member "fuse-3.2.3/include/fuse.h" (11 May 2018, 42084 Bytes) of package /linux/misc/fuse-3.2.3.tar.xz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "fuse.h" see the Fossies "Dox" file reference documentation and the latest Fossies "Diffs" side-by-side code changes report: 3.2.2_vs_3.2.3.

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