"Fossies" - the Fresh Open Source Software Archive

Member "fuse-3.2.1/include/fuse_lowlevel.h" (14 Nov 2017, 62440 Bytes) of package /linux/misc/fuse-3.2.1.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_lowlevel.h" see the Fossies "Dox" file reference documentation and the last Fossies "Diffs" side-by-side code changes report: 3.1.1_vs_3.2.0.

    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_LOWLEVEL_H_
   10 #define FUSE_LOWLEVEL_H_
   11 
   12 /** @file
   13  *
   14  * Low level API
   15  *
   16  * IMPORTANT: you should define FUSE_USE_VERSION before including this
   17  * header.  To use the newest API define it to 31 (recommended for any
   18  * new application).
   19  */
   20 
   21 #ifndef FUSE_USE_VERSION
   22 #error FUSE_USE_VERSION not defined
   23 #endif
   24 
   25 #include "fuse_common.h"
   26 
   27 #include <utime.h>
   28 #include <fcntl.h>
   29 #include <sys/types.h>
   30 #include <sys/stat.h>
   31 #include <sys/statvfs.h>
   32 #include <sys/uio.h>
   33 
   34 #ifdef __cplusplus
   35 extern "C" {
   36 #endif
   37 
   38 /* ----------------------------------------------------------- *
   39  * Miscellaneous definitions                       *
   40  * ----------------------------------------------------------- */
   41 
   42 /** The node ID of the root inode */
   43 #define FUSE_ROOT_ID 1
   44 
   45 /** Inode number type */
   46 typedef uint64_t fuse_ino_t;
   47 
   48 /** Request pointer type */
   49 typedef struct fuse_req *fuse_req_t;
   50 
   51 /**
   52  * Session
   53  *
   54  * This provides hooks for processing requests, and exiting
   55  */
   56 struct fuse_session;
   57 
   58 /** Directory entry parameters supplied to fuse_reply_entry() */
   59 struct fuse_entry_param {
   60     /** Unique inode number
   61      *
   62      * In lookup, zero means negative entry (from version 2.5)
   63      * Returning ENOENT also means negative entry, but by setting zero
   64      * ino the kernel may cache negative entries for entry_timeout
   65      * seconds.
   66      */
   67     fuse_ino_t ino;
   68 
   69     /** Generation number for this entry.
   70      *
   71      * If the file system will be exported over NFS, the
   72      * ino/generation pairs need to be unique over the file
   73      * system's lifetime (rather than just the mount time). So if
   74      * the file system reuses an inode after it has been deleted,
   75      * it must assign a new, previously unused generation number
   76      * to the inode at the same time.
   77      *
   78      * The generation must be non-zero, otherwise FUSE will treat
   79      * it as an error.
   80      *
   81      */
   82     uint64_t generation;
   83 
   84     /** Inode attributes.
   85      *
   86      * Even if attr_timeout == 0, attr must be correct. For example,
   87      * for open(), FUSE uses attr.st_size from lookup() to determine
   88      * how many bytes to request. If this value is not correct,
   89      * incorrect data will be returned.
   90      */
   91     struct stat attr;
   92 
   93     /** Validity timeout (in seconds) for inode attributes. If
   94         attributes only change as a result of requests that come
   95         through the kernel, this should be set to a very large
   96         value. */
   97     double attr_timeout;
   98 
   99     /** Validity timeout (in seconds) for the name. If directory
  100         entries are changed/deleted only as a result of requests
  101         that come through the kernel, this should be set to a very
  102         large value. */
  103     double entry_timeout;
  104 };
  105 
  106 /**
  107  * Additional context associated with requests.
  108  *
  109  * Note that the reported client uid, gid and pid may be zero in some
  110  * situations. For example, if the FUSE file system is running in a
  111  * PID or user namespace but then accessed from outside the namespace,
  112  * there is no valid uid/pid/gid that could be reported.
  113  */
  114 struct fuse_ctx {
  115     /** User ID of the calling process */
  116     uid_t uid;
  117 
  118     /** Group ID of the calling process */
  119     gid_t gid;
  120 
  121     /** Thread ID of the calling process */
  122     pid_t pid;
  123 
  124     /** Umask of the calling process */
  125     mode_t umask;
  126 };
  127 
  128 struct fuse_forget_data {
  129     fuse_ino_t ino;
  130     uint64_t nlookup;
  131 };
  132 
  133 /* 'to_set' flags in setattr */
  134 #define FUSE_SET_ATTR_MODE  (1 << 0)
  135 #define FUSE_SET_ATTR_UID   (1 << 1)
  136 #define FUSE_SET_ATTR_GID   (1 << 2)
  137 #define FUSE_SET_ATTR_SIZE  (1 << 3)
  138 #define FUSE_SET_ATTR_ATIME (1 << 4)
  139 #define FUSE_SET_ATTR_MTIME (1 << 5)
  140 #define FUSE_SET_ATTR_ATIME_NOW (1 << 7)
  141 #define FUSE_SET_ATTR_MTIME_NOW (1 << 8)
  142 #define FUSE_SET_ATTR_CTIME (1 << 10)
  143 
  144 /* ----------------------------------------------------------- *
  145  * Request methods and replies                     *
  146  * ----------------------------------------------------------- */
  147 
  148 /**
  149  * Low level filesystem operations
  150  *
  151  * Most of the methods (with the exception of init and destroy)
  152  * receive a request handle (fuse_req_t) as their first argument.
  153  * This handle must be passed to one of the specified reply functions.
  154  *
  155  * This may be done inside the method invocation, or after the call
  156  * has returned.  The request handle is valid until one of the reply
  157  * functions is called.
  158  *
  159  * Other pointer arguments (name, fuse_file_info, etc) are not valid
  160  * after the call has returned, so if they are needed later, their
  161  * contents have to be copied.
  162  *
  163  * In general, all methods are expected to perform any necessary
  164  * permission checking. However, a filesystem may delegate this task
  165  * to the kernel by passing the `default_permissions` mount option to
  166  * `fuse_session_new()`. In this case, methods will only be called if
  167  * the kernel's permission check has succeeded.
  168  *
  169  * The filesystem sometimes needs to handle a return value of -ENOENT
  170  * from the reply function, which means, that the request was
  171  * interrupted, and the reply discarded.  For example if
  172  * fuse_reply_open() return -ENOENT means, that the release method for
  173  * this file will not be called.
  174  */
  175 struct fuse_lowlevel_ops {
  176     /**
  177      * Initialize filesystem
  178      *
  179      * This function is called when libfuse establishes
  180      * communication with the FUSE kernel module. The file system
  181      * should use this module to inspect and/or modify the
  182      * connection parameters provided in the `conn` structure.
  183      *
  184      * Note that some parameters may be overwritten by options
  185      * passed to fuse_session_new() which take precedence over the
  186      * values set in this handler.
  187      *
  188      * There's no reply to this function
  189      *
  190      * @param userdata the user data passed to fuse_session_new()
  191      */
  192     void (*init) (void *userdata, struct fuse_conn_info *conn);
  193 
  194     /**
  195      * Clean up filesystem.
  196      *
  197      * Called on filesystem exit. When this method is called, the
  198      * connection to the kernel may be gone already, so that eg. calls
  199      * to fuse_lowlevel_notify_* will fail.
  200      *
  201      * There's no reply to this function
  202      *
  203      * @param userdata the user data passed to fuse_session_new()
  204      */
  205     void (*destroy) (void *userdata);
  206 
  207     /**
  208      * Look up a directory entry by name and get its attributes.
  209      *
  210      * Valid replies:
  211      *   fuse_reply_entry
  212      *   fuse_reply_err
  213      *
  214      * @param req request handle
  215      * @param parent inode number of the parent directory
  216      * @param name the name to look up
  217      */
  218     void (*lookup) (fuse_req_t req, fuse_ino_t parent, const char *name);
  219 
  220     /**
  221      * Forget about an inode
  222      *
  223      * This function is called when the kernel removes an inode
  224      * from its internal caches.
  225      *
  226      * The inode's lookup count increases by one for every call to
  227      * fuse_reply_entry and fuse_reply_create. The nlookup parameter
  228      * indicates by how much the lookup count should be decreased.
  229      *
  230      * Inodes with a non-zero lookup count may receive request from
  231      * the kernel even after calls to unlink, rmdir or (when
  232      * overwriting an existing file) rename. Filesystems must handle
  233      * such requests properly and it is recommended to defer removal
  234      * of the inode until the lookup count reaches zero. Calls to
  235      * unlink, rmdir or rename will be followed closely by forget
  236      * unless the file or directory is open, in which case the
  237      * kernel issues forget only after the release or releasedir
  238      * calls.
  239      *
  240      * Note that if a file system will be exported over NFS the
  241      * inodes lifetime must extend even beyond forget. See the
  242      * generation field in struct fuse_entry_param above.
  243      *
  244      * On unmount the lookup count for all inodes implicitly drops
  245      * to zero. It is not guaranteed that the file system will
  246      * receive corresponding forget messages for the affected
  247      * inodes.
  248      *
  249      * Valid replies:
  250      *   fuse_reply_none
  251      *
  252      * @param req request handle
  253      * @param ino the inode number
  254      * @param nlookup the number of lookups to forget
  255      */
  256     void (*forget) (fuse_req_t req, fuse_ino_t ino, uint64_t nlookup);
  257 
  258     /**
  259      * Get file attributes.
  260      *
  261      * If writeback caching is enabled, the kernel may have a
  262      * better idea of a file's length than the FUSE file system
  263      * (eg if there has been a write that extended the file size,
  264      * but that has not yet been passed to the filesystem.n
  265      *
  266      * In this case, the st_size value provided by the file system
  267      * will be ignored.
  268      *
  269      * Valid replies:
  270      *   fuse_reply_attr
  271      *   fuse_reply_err
  272      *
  273      * @param req request handle
  274      * @param ino the inode number
  275      * @param fi for future use, currently always NULL
  276      */
  277     void (*getattr) (fuse_req_t req, fuse_ino_t ino,
  278              struct fuse_file_info *fi);
  279 
  280     /**
  281      * Set file attributes
  282      *
  283      * In the 'attr' argument only members indicated by the 'to_set'
  284      * bitmask contain valid values.  Other members contain undefined
  285      * values.
  286      *
  287      * Unless FUSE_CAP_HANDLE_KILLPRIV is disabled, this method is
  288      * expected to reset the setuid and setgid bits if the file
  289      * size or owner is being changed.
  290      *
  291      * If the setattr was invoked from the ftruncate() system call
  292      * under Linux kernel versions 2.6.15 or later, the fi->fh will
  293      * contain the value set by the open method or will be undefined
  294      * if the open method didn't set any value.  Otherwise (not
  295      * ftruncate call, or kernel version earlier than 2.6.15) the fi
  296      * parameter will be NULL.
  297      *
  298      * Valid replies:
  299      *   fuse_reply_attr
  300      *   fuse_reply_err
  301      *
  302      * @param req request handle
  303      * @param ino the inode number
  304      * @param attr the attributes
  305      * @param to_set bit mask of attributes which should be set
  306      * @param fi file information, or NULL
  307      */
  308     void (*setattr) (fuse_req_t req, fuse_ino_t ino, struct stat *attr,
  309              int to_set, struct fuse_file_info *fi);
  310 
  311     /**
  312      * Read symbolic link
  313      *
  314      * Valid replies:
  315      *   fuse_reply_readlink
  316      *   fuse_reply_err
  317      *
  318      * @param req request handle
  319      * @param ino the inode number
  320      */
  321     void (*readlink) (fuse_req_t req, fuse_ino_t ino);
  322 
  323     /**
  324      * Create file node
  325      *
  326      * Create a regular file, character device, block device, fifo or
  327      * socket node.
  328      *
  329      * Valid replies:
  330      *   fuse_reply_entry
  331      *   fuse_reply_err
  332      *
  333      * @param req request handle
  334      * @param parent inode number of the parent directory
  335      * @param name to create
  336      * @param mode file type and mode with which to create the new file
  337      * @param rdev the device number (only valid if created file is a device)
  338      */
  339     void (*mknod) (fuse_req_t req, fuse_ino_t parent, const char *name,
  340                mode_t mode, dev_t rdev);
  341 
  342     /**
  343      * Create a directory
  344      *
  345      * Valid replies:
  346      *   fuse_reply_entry
  347      *   fuse_reply_err
  348      *
  349      * @param req request handle
  350      * @param parent inode number of the parent directory
  351      * @param name to create
  352      * @param mode with which to create the new file
  353      */
  354     void (*mkdir) (fuse_req_t req, fuse_ino_t parent, const char *name,
  355                mode_t mode);
  356 
  357     /**
  358      * Remove a file
  359      *
  360      * If the file's inode's lookup count is non-zero, the file
  361      * system is expected to postpone any removal of the inode
  362      * until the lookup count reaches zero (see description of the
  363      * forget function).
  364      *
  365      * Valid replies:
  366      *   fuse_reply_err
  367      *
  368      * @param req request handle
  369      * @param parent inode number of the parent directory
  370      * @param name to remove
  371      */
  372     void (*unlink) (fuse_req_t req, fuse_ino_t parent, const char *name);
  373 
  374     /**
  375      * Remove a directory
  376      *
  377      * If the directory's inode's lookup count is non-zero, the
  378      * file system is expected to postpone any removal of the
  379      * inode until the lookup count reaches zero (see description
  380      * of the forget function).
  381      *
  382      * Valid replies:
  383      *   fuse_reply_err
  384      *
  385      * @param req request handle
  386      * @param parent inode number of the parent directory
  387      * @param name to remove
  388      */
  389     void (*rmdir) (fuse_req_t req, fuse_ino_t parent, const char *name);
  390 
  391     /**
  392      * Create a symbolic link
  393      *
  394      * Valid replies:
  395      *   fuse_reply_entry
  396      *   fuse_reply_err
  397      *
  398      * @param req request handle
  399      * @param link the contents of the symbolic link
  400      * @param parent inode number of the parent directory
  401      * @param name to create
  402      */
  403     void (*symlink) (fuse_req_t req, const char *link, fuse_ino_t parent,
  404              const char *name);
  405 
  406     /** Rename a file
  407      *
  408      * If the target exists it should be atomically replaced. If
  409      * the target's inode's lookup count is non-zero, the file
  410      * system is expected to postpone any removal of the inode
  411      * until the lookup count reaches zero (see description of the
  412      * forget function).
  413      *
  414      * If this request is answered with an error code of ENOSYS, this is
  415      * treated as a permanent failure with error code EINVAL, i.e. all
  416      * future bmap requests will fail with EINVAL without being
  417      * send to the filesystem process.
  418      *
  419      * *flags* may be `RENAME_EXCHANGE` or `RENAME_NOREPLACE`. If
  420      * RENAME_NOREPLACE is specified, the filesystem must not
  421      * overwrite *newname* if it exists and return an error
  422      * instead. If `RENAME_EXCHANGE` is specified, the filesystem
  423      * must atomically exchange the two files, i.e. both must
  424      * exist and neither may be deleted.
  425      *
  426      * Valid replies:
  427      *   fuse_reply_err
  428      *
  429      * @param req request handle
  430      * @param parent inode number of the old parent directory
  431      * @param name old name
  432      * @param newparent inode number of the new parent directory
  433      * @param newname new name
  434      */
  435     void (*rename) (fuse_req_t req, fuse_ino_t parent, const char *name,
  436             fuse_ino_t newparent, const char *newname,
  437             unsigned int flags);
  438 
  439     /**
  440      * Create a hard link
  441      *
  442      * Valid replies:
  443      *   fuse_reply_entry
  444      *   fuse_reply_err
  445      *
  446      * @param req request handle
  447      * @param ino the old inode number
  448      * @param newparent inode number of the new parent directory
  449      * @param newname new name to create
  450      */
  451     void (*link) (fuse_req_t req, fuse_ino_t ino, fuse_ino_t newparent,
  452               const char *newname);
  453 
  454     /**
  455      * Open a file
  456      *
  457      * Open flags are available in fi->flags. The following rules
  458      * apply.
  459      *
  460      *  - Creation (O_CREAT, O_EXCL, O_NOCTTY) flags will be
  461      *    filtered out / handled by the kernel.
  462      *
  463      *  - Access modes (O_RDONLY, O_WRONLY, O_RDWR) should be used
  464      *    by the filesystem to check if the operation is
  465      *    permitted.  If the ``-o default_permissions`` mount
  466      *    option is given, this check is already done by the
  467      *    kernel before calling open() and may thus be omitted by
  468      *    the filesystem.
  469      *
  470      *  - When writeback caching is enabled, the kernel may send
  471      *    read requests even for files opened with O_WRONLY. The
  472      *    filesystem should be prepared to handle this.
  473      *
  474      *  - When writeback caching is disabled, the filesystem is
  475      *    expected to properly handle the O_APPEND flag and ensure
  476      *    that each write is appending to the end of the file.
  477      * 
  478          *  - When writeback caching is enabled, the kernel will
  479      *    handle O_APPEND. However, unless all changes to the file
  480      *    come through the kernel this will not work reliably. The
  481      *    filesystem should thus either ignore the O_APPEND flag
  482      *    (and let the kernel handle it), or return an error
  483      *    (indicating that reliably O_APPEND is not available).
  484      *
  485      * Filesystem may store an arbitrary file handle (pointer,
  486      * index, etc) in fi->fh, and use this in other all other file
  487      * operations (read, write, flush, release, fsync).
  488      *
  489      * Filesystem may also implement stateless file I/O and not store
  490      * anything in fi->fh.
  491      *
  492      * There are also some flags (direct_io, keep_cache) which the
  493      * filesystem may set in fi, to change the way the file is opened.
  494      * See fuse_file_info structure in <fuse_common.h> for more details.
  495      *
  496      * If this request is answered with an error code of ENOSYS
  497      * and FUSE_CAP_NO_OPEN_SUPPORT is set in
  498      * `fuse_conn_info.capable`, this is treated as success and
  499      * future calls to open will also succeed without being send
  500      * to the filesystem process.
  501      *
  502      * Valid replies:
  503      *   fuse_reply_open
  504      *   fuse_reply_err
  505      *
  506      * @param req request handle
  507      * @param ino the inode number
  508      * @param fi file information
  509      */
  510     void (*open) (fuse_req_t req, fuse_ino_t ino,
  511               struct fuse_file_info *fi);
  512 
  513     /**
  514      * Read data
  515      *
  516      * Read should send exactly the number of bytes requested except
  517      * on EOF or error, otherwise the rest of the data will be
  518      * substituted with zeroes.  An exception to this is when the file
  519      * has been opened in 'direct_io' mode, in which case the return
  520      * value of the read system call will reflect the return value of
  521      * this operation.
  522      *
  523      * fi->fh will contain the value set by the open method, or will
  524      * be undefined if the open method didn't set any value.
  525      *
  526      * Valid replies:
  527      *   fuse_reply_buf
  528      *   fuse_reply_iov
  529      *   fuse_reply_data
  530      *   fuse_reply_err
  531      *
  532      * @param req request handle
  533      * @param ino the inode number
  534      * @param size number of bytes to read
  535      * @param off offset to read from
  536      * @param fi file information
  537      */
  538     void (*read) (fuse_req_t req, fuse_ino_t ino, size_t size, off_t off,
  539               struct fuse_file_info *fi);
  540 
  541     /**
  542      * Write data
  543      *
  544      * Write should return exactly the number of bytes requested
  545      * except on error.  An exception to this is when the file has
  546      * been opened in 'direct_io' mode, in which case the return value
  547      * of the write system call will reflect the return value of this
  548      * operation.
  549      *
  550      * Unless FUSE_CAP_HANDLE_KILLPRIV is disabled, this method is
  551      * expected to reset the setuid and setgid bits.
  552      *
  553      * fi->fh will contain the value set by the open method, or will
  554      * be undefined if the open method didn't set any value.
  555      *
  556      * Valid replies:
  557      *   fuse_reply_write
  558      *   fuse_reply_err
  559      *
  560      * @param req request handle
  561      * @param ino the inode number
  562      * @param buf data to write
  563      * @param size number of bytes to write
  564      * @param off offset to write to
  565      * @param fi file information
  566      */
  567     void (*write) (fuse_req_t req, fuse_ino_t ino, const char *buf,
  568                size_t size, off_t off, struct fuse_file_info *fi);
  569 
  570     /**
  571      * Flush method
  572      *
  573      * This is called on each close() of the opened file.
  574      *
  575      * Since file descriptors can be duplicated (dup, dup2, fork), for
  576      * one open call there may be many flush calls.
  577      *
  578      * Filesystems shouldn't assume that flush will always be called
  579      * after some writes, or that if will be called at all.
  580      *
  581      * fi->fh will contain the value set by the open method, or will
  582      * be undefined if the open method didn't set any value.
  583      *
  584      * NOTE: the name of the method is misleading, since (unlike
  585      * fsync) the filesystem is not forced to flush pending writes.
  586      * One reason to flush data, is if the filesystem wants to return
  587      * write errors.
  588      *
  589      * If the filesystem supports file locking operations (setlk,
  590      * getlk) it should remove all locks belonging to 'fi->owner'.
  591      *
  592      * If this request is answered with an error code of ENOSYS,
  593      * this is treated as success and future calls to flush() will
  594      * succeed automatically without being send to the filesystem
  595      * process.
  596      *
  597      * Valid replies:
  598      *   fuse_reply_err
  599      *
  600      * @param req request handle
  601      * @param ino the inode number
  602      * @param fi file information
  603      */
  604     void (*flush) (fuse_req_t req, fuse_ino_t ino,
  605                struct fuse_file_info *fi);
  606 
  607     /**
  608      * Release an open file
  609      *
  610      * Release is called when there are no more references to an open
  611      * file: all file descriptors are closed and all memory mappings
  612      * are unmapped.
  613      *
  614      * For every open call there will be exactly one release call.
  615      *
  616      * The filesystem may reply with an error, but error values are
  617      * not returned to close() or munmap() which triggered the
  618      * release.
  619      *
  620      * fi->fh will contain the value set by the open method, or will
  621      * be undefined if the open method didn't set any value.
  622      * fi->flags will contain the same flags as for open.
  623      *
  624      * Valid replies:
  625      *   fuse_reply_err
  626      *
  627      * @param req request handle
  628      * @param ino the inode number
  629      * @param fi file information
  630      */
  631     void (*release) (fuse_req_t req, fuse_ino_t ino,
  632              struct fuse_file_info *fi);
  633 
  634     /**
  635      * Synchronize file contents
  636      *
  637      * If the datasync parameter is non-zero, then only the user data
  638      * should be flushed, not the meta data.
  639      *
  640      * If this request is answered with an error code of ENOSYS,
  641      * this is treated as success and future calls to fsync() will
  642      * succeed automatically without being send to the filesystem
  643      * process.
  644      *
  645      * Valid replies:
  646      *   fuse_reply_err
  647      *
  648      * @param req request handle
  649      * @param ino the inode number
  650      * @param datasync flag indicating if only data should be flushed
  651      * @param fi file information
  652      */
  653     void (*fsync) (fuse_req_t req, fuse_ino_t ino, int datasync,
  654                struct fuse_file_info *fi);
  655 
  656     /**
  657      * Open a directory
  658      *
  659      * Filesystem may store an arbitrary file handle (pointer, index,
  660      * etc) in fi->fh, and use this in other all other directory
  661      * stream operations (readdir, releasedir, fsyncdir).
  662      *
  663      * Filesystem may also implement stateless directory I/O and not
  664      * store anything in fi->fh, though that makes it impossible to
  665      * implement standard conforming directory stream operations in
  666      * case the contents of the directory can change between opendir
  667      * and releasedir.
  668      *
  669      * Valid replies:
  670      *   fuse_reply_open
  671      *   fuse_reply_err
  672      *
  673      * @param req request handle
  674      * @param ino the inode number
  675      * @param fi file information
  676      */
  677     void (*opendir) (fuse_req_t req, fuse_ino_t ino,
  678              struct fuse_file_info *fi);
  679 
  680     /**
  681      * Read directory
  682      *
  683      * Send a buffer filled using fuse_add_direntry(), with size not
  684      * exceeding the requested size.  Send an empty buffer on end of
  685      * stream.
  686      *
  687      * fi->fh will contain the value set by the opendir method, or
  688      * will be undefined if the opendir method didn't set any value.
  689      *
  690      * Returning a directory entry from readdir() does not affect
  691      * its lookup count.
  692      *
  693      * The function does not have to report the '.' and '..'
  694      * entries, but is allowed to do so.
  695      *
  696      * Valid replies:
  697      *   fuse_reply_buf
  698      *   fuse_reply_data
  699      *   fuse_reply_err
  700      *
  701      * @param req request handle
  702      * @param ino the inode number
  703      * @param size maximum number of bytes to send
  704      * @param off offset to continue reading the directory stream
  705      * @param fi file information
  706      */
  707     void (*readdir) (fuse_req_t req, fuse_ino_t ino, size_t size, off_t off,
  708              struct fuse_file_info *fi);
  709 
  710     /**
  711      * Release an open directory
  712      *
  713      * For every opendir call there will be exactly one releasedir
  714      * call.
  715      *
  716      * fi->fh will contain the value set by the opendir method, or
  717      * will be undefined if the opendir method didn't set any value.
  718      *
  719      * Valid replies:
  720      *   fuse_reply_err
  721      *
  722      * @param req request handle
  723      * @param ino the inode number
  724      * @param fi file information
  725      */
  726     void (*releasedir) (fuse_req_t req, fuse_ino_t ino,
  727                 struct fuse_file_info *fi);
  728 
  729     /**
  730      * Synchronize directory contents
  731      *
  732      * If the datasync parameter is non-zero, then only the directory
  733      * contents should be flushed, not the meta data.
  734      *
  735      * fi->fh will contain the value set by the opendir method, or
  736      * will be undefined if the opendir method didn't set any value.
  737      *
  738      * If this request is answered with an error code of ENOSYS,
  739      * this is treated as success and future calls to fsyncdir() will
  740      * succeed automatically without being send to the filesystem
  741      * process.
  742      *
  743      * Valid replies:
  744      *   fuse_reply_err
  745      *
  746      * @param req request handle
  747      * @param ino the inode number
  748      * @param datasync flag indicating if only data should be flushed
  749      * @param fi file information
  750      */
  751     void (*fsyncdir) (fuse_req_t req, fuse_ino_t ino, int datasync,
  752               struct fuse_file_info *fi);
  753 
  754     /**
  755      * Get file system statistics
  756      *
  757      * Valid replies:
  758      *   fuse_reply_statfs
  759      *   fuse_reply_err
  760      *
  761      * @param req request handle
  762      * @param ino the inode number, zero means "undefined"
  763      */
  764     void (*statfs) (fuse_req_t req, fuse_ino_t ino);
  765 
  766     /**
  767      * Set an extended attribute
  768      *
  769      * If this request is answered with an error code of ENOSYS, this is
  770      * treated as a permanent failure with error code EOPNOTSUPP, i.e. all
  771      * future setxattr() requests will fail with EOPNOTSUPP without being
  772      * send to the filesystem process.
  773      *
  774      * Valid replies:
  775      *   fuse_reply_err
  776      */
  777     void (*setxattr) (fuse_req_t req, fuse_ino_t ino, const char *name,
  778               const char *value, size_t size, int flags);
  779 
  780     /**
  781      * Get an extended attribute
  782      *
  783      * If size is zero, the size of the value should be sent with
  784      * fuse_reply_xattr.
  785      *
  786      * If the size is non-zero, and the value fits in the buffer, the
  787      * value should be sent with fuse_reply_buf.
  788      *
  789      * If the size is too small for the value, the ERANGE error should
  790      * be sent.
  791      *
  792      * If this request is answered with an error code of ENOSYS, this is
  793      * treated as a permanent failure with error code EOPNOTSUPP, i.e. all
  794      * future getxattr() requests will fail with EOPNOTSUPP without being
  795      * send to the filesystem process.
  796      *
  797      * Valid replies:
  798      *   fuse_reply_buf
  799      *   fuse_reply_data
  800      *   fuse_reply_xattr
  801      *   fuse_reply_err
  802      *
  803      * @param req request handle
  804      * @param ino the inode number
  805      * @param name of the extended attribute
  806      * @param size maximum size of the value to send
  807      */
  808     void (*getxattr) (fuse_req_t req, fuse_ino_t ino, const char *name,
  809               size_t size);
  810 
  811     /**
  812      * List extended attribute names
  813      *
  814      * If size is zero, the total size of the attribute list should be
  815      * sent with fuse_reply_xattr.
  816      *
  817      * If the size is non-zero, and the null character separated
  818      * attribute list fits in the buffer, the list should be sent with
  819      * fuse_reply_buf.
  820      *
  821      * If the size is too small for the list, the ERANGE error should
  822      * be sent.
  823      *
  824      * If this request is answered with an error code of ENOSYS, this is
  825      * treated as a permanent failure with error code EOPNOTSUPP, i.e. all
  826      * future listxattr() requests will fail with EOPNOTSUPP without being
  827      * send to the filesystem process.
  828      *
  829      * Valid replies:
  830      *   fuse_reply_buf
  831      *   fuse_reply_data
  832      *   fuse_reply_xattr
  833      *   fuse_reply_err
  834      *
  835      * @param req request handle
  836      * @param ino the inode number
  837      * @param size maximum size of the list to send
  838      */
  839     void (*listxattr) (fuse_req_t req, fuse_ino_t ino, size_t size);
  840 
  841     /**
  842      * Remove an extended attribute
  843      *
  844      * If this request is answered with an error code of ENOSYS, this is
  845      * treated as a permanent failure with error code EOPNOTSUPP, i.e. all
  846      * future removexattr() requests will fail with EOPNOTSUPP without being
  847      * send to the filesystem process.
  848      *
  849      * Valid replies:
  850      *   fuse_reply_err
  851      *
  852      * @param req request handle
  853      * @param ino the inode number
  854      * @param name of the extended attribute
  855      */
  856     void (*removexattr) (fuse_req_t req, fuse_ino_t ino, const char *name);
  857 
  858     /**
  859      * Check file access permissions
  860      *
  861      * This will be called for the access() system call.  If the
  862      * 'default_permissions' mount option is given, this method is not
  863      * called.
  864      *
  865      * This method is not called under Linux kernel versions 2.4.x
  866      *
  867      * If this request is answered with an error code of ENOSYS, this is
  868      * treated as a permanent success, i.e. this and all future access()
  869      * requests will succeed without being send to the filesystem process.
  870      *
  871      * Valid replies:
  872      *   fuse_reply_err
  873      *
  874      * @param req request handle
  875      * @param ino the inode number
  876      * @param mask requested access mode
  877      */
  878     void (*access) (fuse_req_t req, fuse_ino_t ino, int mask);
  879 
  880     /**
  881      * Create and open a file
  882      *
  883      * If the file does not exist, first create it with the specified
  884      * mode, and then open it.
  885      *
  886      * See the description of the open handler for more
  887      * information.
  888      *
  889      * If this method is not implemented or under Linux kernel
  890      * versions earlier than 2.6.15, the mknod() and open() methods
  891      * will be called instead.
  892      *
  893      * If this request is answered with an error code of ENOSYS, the handler
  894      * is treated as not implemented (i.e., for this and future requests the
  895      * mknod() and open() handlers will be called instead).
  896      *
  897      * Valid replies:
  898      *   fuse_reply_create
  899      *   fuse_reply_err
  900      *
  901      * @param req request handle
  902      * @param parent inode number of the parent directory
  903      * @param name to create
  904      * @param mode file type and mode with which to create the new file
  905      * @param fi file information
  906      */
  907     void (*create) (fuse_req_t req, fuse_ino_t parent, const char *name,
  908             mode_t mode, struct fuse_file_info *fi);
  909 
  910     /**
  911      * Test for a POSIX file lock
  912      *
  913      * Valid replies:
  914      *   fuse_reply_lock
  915      *   fuse_reply_err
  916      *
  917      * @param req request handle
  918      * @param ino the inode number
  919      * @param fi file information
  920      * @param lock the region/type to test
  921      */
  922     void (*getlk) (fuse_req_t req, fuse_ino_t ino,
  923                struct fuse_file_info *fi, struct flock *lock);
  924 
  925     /**
  926      * Acquire, modify or release a POSIX file lock
  927      *
  928      * For POSIX threads (NPTL) there's a 1-1 relation between pid and
  929      * owner, but otherwise this is not always the case.  For checking
  930      * lock ownership, 'fi->owner' must be used.  The l_pid field in
  931      * 'struct flock' should only be used to fill in this field in
  932      * getlk().
  933      *
  934      * Note: if the locking methods are not implemented, the kernel
  935      * will still allow file locking to work locally.  Hence these are
  936      * only interesting for network filesystems and similar.
  937      *
  938      * Valid replies:
  939      *   fuse_reply_err
  940      *
  941      * @param req request handle
  942      * @param ino the inode number
  943      * @param fi file information
  944      * @param lock the region/type to set
  945      * @param sleep locking operation may sleep
  946      */
  947     void (*setlk) (fuse_req_t req, fuse_ino_t ino,
  948                struct fuse_file_info *fi,
  949                struct flock *lock, int sleep);
  950 
  951     /**
  952      * Map block index within file to block index within device
  953      *
  954      * Note: This makes sense only for block device backed filesystems
  955      * mounted with the 'blkdev' option
  956      *
  957      * If this request is answered with an error code of ENOSYS, this is
  958      * treated as a permanent failure, i.e. all future bmap() requests will
  959      * fail with the same error code without being send to the filesystem
  960      * process.
  961      *
  962      * Valid replies:
  963      *   fuse_reply_bmap
  964      *   fuse_reply_err
  965      *
  966      * @param req request handle
  967      * @param ino the inode number
  968      * @param blocksize unit of block index
  969      * @param idx block index within file
  970      */
  971     void (*bmap) (fuse_req_t req, fuse_ino_t ino, size_t blocksize,
  972               uint64_t idx);
  973 
  974     /**
  975      * Ioctl
  976      *
  977      * Note: For unrestricted ioctls (not allowed for FUSE
  978      * servers), data in and out areas can be discovered by giving
  979      * iovs and setting FUSE_IOCTL_RETRY in *flags*.  For
  980      * restricted ioctls, kernel prepares in/out data area
  981      * according to the information encoded in cmd.
  982      *
  983      * Valid replies:
  984      *   fuse_reply_ioctl_retry
  985      *   fuse_reply_ioctl
  986      *   fuse_reply_ioctl_iov
  987      *   fuse_reply_err
  988      *
  989      * @param req request handle
  990      * @param ino the inode number
  991      * @param cmd ioctl command
  992      * @param arg ioctl argument
  993      * @param fi file information
  994      * @param flags for FUSE_IOCTL_* flags
  995      * @param in_buf data fetched from the caller
  996      * @param in_bufsz number of fetched bytes
  997      * @param out_bufsz maximum size of output data
  998      */
  999     void (*ioctl) (fuse_req_t req, fuse_ino_t ino, int cmd, void *arg,
 1000                struct fuse_file_info *fi, unsigned flags,
 1001                const void *in_buf, size_t in_bufsz, size_t out_bufsz);
 1002 
 1003     /**
 1004      * Poll for IO readiness
 1005      *
 1006      * Note: If ph is non-NULL, the client should notify
 1007      * when IO readiness events occur by calling
 1008      * fuse_lowlevel_notify_poll() with the specified ph.
 1009      *
 1010      * Regardless of the number of times poll with a non-NULL ph
 1011      * is received, single notification is enough to clear all.
 1012      * Notifying more times incurs overhead but doesn't harm
 1013      * correctness.
 1014      *
 1015      * The callee is responsible for destroying ph with
 1016      * fuse_pollhandle_destroy() when no longer in use.
 1017      *
 1018      * If this request is answered with an error code of ENOSYS, this is
 1019      * treated as success (with a kernel-defined default poll-mask) and
 1020      * future calls to pull() will succeed the same way without being send
 1021      * to the filesystem process.
 1022      *
 1023      * Valid replies:
 1024      *   fuse_reply_poll
 1025      *   fuse_reply_err
 1026      *
 1027      * @param req request handle
 1028      * @param ino the inode number
 1029      * @param fi file information
 1030      * @param ph poll handle to be used for notification
 1031      */
 1032     void (*poll) (fuse_req_t req, fuse_ino_t ino, struct fuse_file_info *fi,
 1033               struct fuse_pollhandle *ph);
 1034 
 1035     /**
 1036      * Write data made available in a buffer
 1037      *
 1038      * This is a more generic version of the ->write() method.  If
 1039      * FUSE_CAP_SPLICE_READ is set in fuse_conn_info.want and the
 1040      * kernel supports splicing from the fuse device, then the
 1041      * data will be made available in pipe for supporting zero
 1042      * copy data transfer.
 1043      *
 1044      * buf->count is guaranteed to be one (and thus buf->idx is
 1045      * always zero). The write_buf handler must ensure that
 1046      * bufv->off is correctly updated (reflecting the number of
 1047      * bytes read from bufv->buf[0]).
 1048      *
 1049      * Unless FUSE_CAP_HANDLE_KILLPRIV is disabled, this method is
 1050      * expected to reset the setuid and setgid bits.
 1051      *
 1052      * Valid replies:
 1053      *   fuse_reply_write
 1054      *   fuse_reply_err
 1055      *
 1056      * @param req request handle
 1057      * @param ino the inode number
 1058      * @param bufv buffer containing the data
 1059      * @param off offset to write to
 1060      * @param fi file information
 1061      */
 1062     void (*write_buf) (fuse_req_t req, fuse_ino_t ino,
 1063                struct fuse_bufvec *bufv, off_t off,
 1064                struct fuse_file_info *fi);
 1065 
 1066     /**
 1067      * Callback function for the retrieve request
 1068      *
 1069      * Valid replies:
 1070      *  fuse_reply_none
 1071      *
 1072      * @param req request handle
 1073      * @param cookie user data supplied to fuse_lowlevel_notify_retrieve()
 1074      * @param ino the inode number supplied to fuse_lowlevel_notify_retrieve()
 1075      * @param offset the offset supplied to fuse_lowlevel_notify_retrieve()
 1076      * @param bufv the buffer containing the returned data
 1077      */
 1078     void (*retrieve_reply) (fuse_req_t req, void *cookie, fuse_ino_t ino,
 1079                 off_t offset, struct fuse_bufvec *bufv);
 1080 
 1081     /**
 1082      * Forget about multiple inodes
 1083      *
 1084      * See description of the forget function for more
 1085      * information.
 1086      *
 1087      * Valid replies:
 1088      *   fuse_reply_none
 1089      *
 1090      * @param req request handle
 1091      */
 1092     void (*forget_multi) (fuse_req_t req, size_t count,
 1093                   struct fuse_forget_data *forgets);
 1094 
 1095     /**
 1096      * Acquire, modify or release a BSD file lock
 1097      *
 1098      * Note: if the locking methods are not implemented, the kernel
 1099      * will still allow file locking to work locally.  Hence these are
 1100      * only interesting for network filesystems and similar.
 1101      *
 1102      * Valid replies:
 1103      *   fuse_reply_err
 1104      *
 1105      * @param req request handle
 1106      * @param ino the inode number
 1107      * @param fi file information
 1108      * @param op the locking operation, see flock(2)
 1109      */
 1110     void (*flock) (fuse_req_t req, fuse_ino_t ino,
 1111                struct fuse_file_info *fi, int op);
 1112 
 1113     /**
 1114      * Allocate requested space. If this function returns success then
 1115      * subsequent writes to the specified range shall not fail due to the lack
 1116      * of free space on the file system storage media.
 1117      *
 1118      * If this request is answered with an error code of ENOSYS, this is
 1119      * treated as a permanent failure with error code EOPNOTSUPP, i.e. all
 1120      * future fallocate() requests will fail with EOPNOTSUPP without being
 1121      * send to the filesystem process.
 1122      *
 1123      * Valid replies:
 1124      *   fuse_reply_err
 1125      *
 1126      * @param req request handle
 1127      * @param ino the inode number
 1128      * @param offset starting point for allocated region
 1129      * @param length size of allocated region
 1130      * @param mode determines the operation to be performed on the given range,
 1131      *             see fallocate(2)
 1132      */
 1133     void (*fallocate) (fuse_req_t req, fuse_ino_t ino, int mode,
 1134                off_t offset, off_t length, struct fuse_file_info *fi);
 1135 
 1136     /**
 1137      * Read directory with attributes
 1138      *
 1139      * Send a buffer filled using fuse_add_direntry_plus(), with size not
 1140      * exceeding the requested size.  Send an empty buffer on end of
 1141      * stream.
 1142      *
 1143      * fi->fh will contain the value set by the opendir method, or
 1144      * will be undefined if the opendir method didn't set any value.
 1145      *
 1146      * In contrast to readdir() (which does not affect the lookup counts),
 1147      * the lookup count of every entry returned by readdirplus(), except "."
 1148      * and "..", is incremented by one.
 1149      *
 1150      * Valid replies:
 1151      *   fuse_reply_buf
 1152      *   fuse_reply_data
 1153      *   fuse_reply_err
 1154      *
 1155      * @param req request handle
 1156      * @param ino the inode number
 1157      * @param size maximum number of bytes to send
 1158      * @param off offset to continue reading the directory stream
 1159      * @param fi file information
 1160      */
 1161     void (*readdirplus) (fuse_req_t req, fuse_ino_t ino, size_t size, off_t off,
 1162              struct fuse_file_info *fi);
 1163 };
 1164 
 1165 /**
 1166  * Reply with an error code or success.
 1167  *
 1168  * Possible requests:
 1169  *   all except forget
 1170  *
 1171  * Whereever possible, error codes should be chosen from the list of
 1172  * documented error conditions in the corresponding system calls
 1173  * manpage.
 1174  *
 1175  * An error code of ENOSYS is sometimes treated specially. This is
 1176  * indicated in the documentation of the affected handler functions.
 1177  *
 1178  * The following requests may be answered with a zero error code:
 1179  * unlink, rmdir, rename, flush, release, fsync, fsyncdir, setxattr,
 1180  * removexattr, setlk.
 1181  *
 1182  * @param req request handle
 1183  * @param err the positive error value, or zero for success
 1184  * @return zero for success, -errno for failure to send reply
 1185  */
 1186 int fuse_reply_err(fuse_req_t req, int err);
 1187 
 1188 /**
 1189  * Don't send reply
 1190  *
 1191  * Possible requests:
 1192  *   forget
 1193  *   forget_multi
 1194  *   retrieve_reply
 1195  *
 1196  * @param req request handle
 1197  */
 1198 void fuse_reply_none(fuse_req_t req);
 1199 
 1200 /**
 1201  * Reply with a directory entry
 1202  *
 1203  * Possible requests:
 1204  *   lookup, mknod, mkdir, symlink, link
 1205  *
 1206  * Side effects:
 1207  *   increments the lookup count on success
 1208  *
 1209  * @param req request handle
 1210  * @param e the entry parameters
 1211  * @return zero for success, -errno for failure to send reply
 1212  */
 1213 int fuse_reply_entry(fuse_req_t req, const struct fuse_entry_param *e);
 1214 
 1215 /**
 1216  * Reply with a directory entry and open parameters
 1217  *
 1218  * currently the following members of 'fi' are used:
 1219  *   fh, direct_io, keep_cache
 1220  *
 1221  * Possible requests:
 1222  *   create
 1223  *
 1224  * Side effects:
 1225  *   increments the lookup count on success
 1226  *
 1227  * @param req request handle
 1228  * @param e the entry parameters
 1229  * @param fi file information
 1230  * @return zero for success, -errno for failure to send reply
 1231  */
 1232 int fuse_reply_create(fuse_req_t req, const struct fuse_entry_param *e,
 1233               const struct fuse_file_info *fi);
 1234 
 1235 /**
 1236  * Reply with attributes
 1237  *
 1238  * Possible requests:
 1239  *   getattr, setattr
 1240  *
 1241  * @param req request handle
 1242  * @param attr the attributes
 1243  * @param attr_timeout  validity timeout (in seconds) for the attributes
 1244  * @return zero for success, -errno for failure to send reply
 1245  */
 1246 int fuse_reply_attr(fuse_req_t req, const struct stat *attr,
 1247             double attr_timeout);
 1248 
 1249 /**
 1250  * Reply with the contents of a symbolic link
 1251  *
 1252  * Possible requests:
 1253  *   readlink
 1254  *
 1255  * @param req request handle
 1256  * @param link symbolic link contents
 1257  * @return zero for success, -errno for failure to send reply
 1258  */
 1259 int fuse_reply_readlink(fuse_req_t req, const char *link);
 1260 
 1261 /**
 1262  * Reply with open parameters
 1263  *
 1264  * currently the following members of 'fi' are used:
 1265  *   fh, direct_io, keep_cache
 1266  *
 1267  * Possible requests:
 1268  *   open, opendir
 1269  *
 1270  * @param req request handle
 1271  * @param fi file information
 1272  * @return zero for success, -errno for failure to send reply
 1273  */
 1274 int fuse_reply_open(fuse_req_t req, const struct fuse_file_info *fi);
 1275 
 1276 /**
 1277  * Reply with number of bytes written
 1278  *
 1279  * Possible requests:
 1280  *   write
 1281  *
 1282  * @param req request handle
 1283  * @param count the number of bytes written
 1284  * @return zero for success, -errno for failure to send reply
 1285  */
 1286 int fuse_reply_write(fuse_req_t req, size_t count);
 1287 
 1288 /**
 1289  * Reply with data
 1290  *
 1291  * Possible requests:
 1292  *   read, readdir, getxattr, listxattr
 1293  *
 1294  * @param req request handle
 1295  * @param buf buffer containing data
 1296  * @param size the size of data in bytes
 1297  * @return zero for success, -errno for failure to send reply
 1298  */
 1299 int fuse_reply_buf(fuse_req_t req, const char *buf, size_t size);
 1300 
 1301 /**
 1302  * Reply with data copied/moved from buffer(s)
 1303  *
 1304  * Zero copy data transfer ("splicing") will be used under
 1305  * the following circumstances:
 1306  *
 1307  * 1. FUSE_CAP_SPLICE_WRITE is set in fuse_conn_info.want, and
 1308  * 2. the kernel supports splicing from the fuse device
 1309  *    (FUSE_CAP_SPLICE_WRITE is set in fuse_conn_info.capable), and
 1310  * 3. *flags* does not contain FUSE_BUF_NO_SPLICE
 1311  * 4. The amount of data that is provided in file-descriptor backed
 1312  *    buffers (i.e., buffers for which bufv[n].flags == FUSE_BUF_FD)
 1313  *    is at least twice the page size.
 1314  *
 1315  * In order for SPLICE_F_MOVE to be used, the following additional
 1316  * conditions have to be fulfilled:
 1317  *
 1318  * 1. FUSE_CAP_SPLICE_MOVE is set in fuse_conn_info.want, and
 1319  * 2. the kernel supports it (i.e, FUSE_CAP_SPLICE_MOVE is set in
 1320       fuse_conn_info.capable), and
 1321  * 3. *flags* contains FUSE_BUF_SPLICE_MOVE
 1322  *
 1323  * Note that, if splice is used, the data is actually spliced twice:
 1324  * once into a temporary pipe (to prepend header data), and then again
 1325  * into the kernel. If some of the provided buffers are memory-backed,
 1326  * the data in them is copied in step one and spliced in step two.
 1327  *
 1328  * The FUSE_BUF_SPLICE_FORCE_SPLICE and FUSE_BUF_SPLICE_NONBLOCK flags
 1329  * are silently ignored.
 1330  *
 1331  * Possible requests:
 1332  *   read, readdir, getxattr, listxattr
 1333  *
 1334  * Side effects:
 1335  *   when used to return data from a readdirplus() (but not readdir())
 1336  *   call, increments the lookup count of each returned entry by one
 1337  *   on success.
 1338  *
 1339  * @param req request handle
 1340  * @param bufv buffer vector
 1341  * @param flags flags controlling the copy
 1342  * @return zero for success, -errno for failure to send reply
 1343  */
 1344 int fuse_reply_data(fuse_req_t req, struct fuse_bufvec *bufv,
 1345             enum fuse_buf_copy_flags flags);
 1346 
 1347 /**
 1348  * Reply with data vector
 1349  *
 1350  * Possible requests:
 1351  *   read, readdir, getxattr, listxattr
 1352  *
 1353  * @param req request handle
 1354  * @param iov the vector containing the data
 1355  * @param count the size of vector
 1356  * @return zero for success, -errno for failure to send reply
 1357  */
 1358 int fuse_reply_iov(fuse_req_t req, const struct iovec *iov, int count);
 1359 
 1360 /**
 1361  * Reply with filesystem statistics
 1362  *
 1363  * Possible requests:
 1364  *   statfs
 1365  *
 1366  * @param req request handle
 1367  * @param stbuf filesystem statistics
 1368  * @return zero for success, -errno for failure to send reply
 1369  */
 1370 int fuse_reply_statfs(fuse_req_t req, const struct statvfs *stbuf);
 1371 
 1372 /**
 1373  * Reply with needed buffer size
 1374  *
 1375  * Possible requests:
 1376  *   getxattr, listxattr
 1377  *
 1378  * @param req request handle
 1379  * @param count the buffer size needed in bytes
 1380  * @return zero for success, -errno for failure to send reply
 1381  */
 1382 int fuse_reply_xattr(fuse_req_t req, size_t count);
 1383 
 1384 /**
 1385  * Reply with file lock information
 1386  *
 1387  * Possible requests:
 1388  *   getlk
 1389  *
 1390  * @param req request handle
 1391  * @param lock the lock information
 1392  * @return zero for success, -errno for failure to send reply
 1393  */
 1394 int fuse_reply_lock(fuse_req_t req, const struct flock *lock);
 1395 
 1396 /**
 1397  * Reply with block index
 1398  *
 1399  * Possible requests:
 1400  *   bmap
 1401  *
 1402  * @param req request handle
 1403  * @param idx block index within device
 1404  * @return zero for success, -errno for failure to send reply
 1405  */
 1406 int fuse_reply_bmap(fuse_req_t req, uint64_t idx);
 1407 
 1408 /* ----------------------------------------------------------- *
 1409  * Filling a buffer in readdir                     *
 1410  * ----------------------------------------------------------- */
 1411 
 1412 /**
 1413  * Add a directory entry to the buffer
 1414  *
 1415  * Buffer needs to be large enough to hold the entry.  If it's not,
 1416  * then the entry is not filled in but the size of the entry is still
 1417  * returned.  The caller can check this by comparing the bufsize
 1418  * parameter with the returned entry size.  If the entry size is
 1419  * larger than the buffer size, the operation failed.
 1420  *
 1421  * From the 'stbuf' argument the st_ino field and bits 12-15 of the
 1422  * st_mode field are used.  The other fields are ignored.
 1423  *
 1424  * *off* should be any non-zero value that the filesystem can use to
 1425  * identify the current point in the directory stream. It does not
 1426  * need to be the actual physical position. A value of zero is
 1427  * reserved to mean "from the beginning", and should therefore never
 1428  * be used (the first call to fuse_add_direntry should be passed the
 1429  * offset of the second directory entry).
 1430  *
 1431  * @param req request handle
 1432  * @param buf the point where the new entry will be added to the buffer
 1433  * @param bufsize remaining size of the buffer
 1434  * @param name the name of the entry
 1435  * @param stbuf the file attributes
 1436  * @param off the offset of the next entry
 1437  * @return the space needed for the entry
 1438  */
 1439 size_t fuse_add_direntry(fuse_req_t req, char *buf, size_t bufsize,
 1440              const char *name, const struct stat *stbuf,
 1441              off_t off);
 1442 
 1443 /**
 1444  * Add a directory entry to the buffer with the attributes
 1445  *
 1446  * See documentation of `fuse_add_direntryt()` for more details.
 1447  *
 1448  * @param req request handle
 1449  * @param buf the point where the new entry will be added to the buffer
 1450  * @param bufsize remaining size of the buffer
 1451  * @param name the name of the entry
 1452  * @param e the directory entry
 1453  * @param off the offset of the next entry
 1454  * @return the space needed for the entry
 1455  */
 1456 size_t fuse_add_direntry_plus(fuse_req_t req, char *buf, size_t bufsize,
 1457                   const char *name,
 1458                   const struct fuse_entry_param *e, off_t off);
 1459 
 1460 /**
 1461  * Reply to ask for data fetch and output buffer preparation.  ioctl
 1462  * will be retried with the specified input data fetched and output
 1463  * buffer prepared.
 1464  *
 1465  * Possible requests:
 1466  *   ioctl
 1467  *
 1468  * @param req request handle
 1469  * @param in_iov iovec specifying data to fetch from the caller
 1470  * @param in_count number of entries in in_iov
 1471  * @param out_iov iovec specifying addresses to write output to
 1472  * @param out_count number of entries in out_iov
 1473  * @return zero for success, -errno for failure to send reply
 1474  */
 1475 int fuse_reply_ioctl_retry(fuse_req_t req,
 1476                const struct iovec *in_iov, size_t in_count,
 1477                const struct iovec *out_iov, size_t out_count);
 1478 
 1479 /**
 1480  * Reply to finish ioctl
 1481  *
 1482  * Possible requests:
 1483  *   ioctl
 1484  *
 1485  * @param req request handle
 1486  * @param result result to be passed to the caller
 1487  * @param buf buffer containing output data
 1488  * @param size length of output data
 1489  */
 1490 int fuse_reply_ioctl(fuse_req_t req, int result, const void *buf, size_t size);
 1491 
 1492 /**
 1493  * Reply to finish ioctl with iov buffer
 1494  *
 1495  * Possible requests:
 1496  *   ioctl
 1497  *
 1498  * @param req request handle
 1499  * @param result result to be passed to the caller
 1500  * @param iov the vector containing the data
 1501  * @param count the size of vector
 1502  */
 1503 int fuse_reply_ioctl_iov(fuse_req_t req, int result, const struct iovec *iov,
 1504              int count);
 1505 
 1506 /**
 1507  * Reply with poll result event mask
 1508  *
 1509  * @param req request handle
 1510  * @param revents poll result event mask
 1511  */
 1512 int fuse_reply_poll(fuse_req_t req, unsigned revents);
 1513 
 1514 /* ----------------------------------------------------------- *
 1515  * Notification                            *
 1516  * ----------------------------------------------------------- */
 1517 
 1518 /**
 1519  * Notify IO readiness event
 1520  *
 1521  * For more information, please read comment for poll operation.
 1522  *
 1523  * @param ph poll handle to notify IO readiness event for
 1524  */
 1525 int fuse_lowlevel_notify_poll(struct fuse_pollhandle *ph);
 1526 
 1527 /**
 1528  * Notify to invalidate cache for an inode.
 1529  *
 1530  * Added in FUSE protocol version 7.12. If the kernel does not support
 1531  * this (or a newer) version, the function will return -ENOSYS and do
 1532  * nothing.
 1533  *
 1534  * @param se the session object
 1535  * @param ino the inode number
 1536  * @param off the offset in the inode where to start invalidating
 1537  *            or negative to invalidate attributes only
 1538  * @param len the amount of cache to invalidate or 0 for all
 1539  * @return zero for success, -errno for failure
 1540  */
 1541 int fuse_lowlevel_notify_inval_inode(struct fuse_session *se, fuse_ino_t ino,
 1542                      off_t off, off_t len);
 1543 
 1544 /**
 1545  * Notify to invalidate parent attributes and the dentry matching
 1546  * parent/name
 1547  *
 1548  * To avoid a deadlock don't call this function from a filesystem
 1549  * operation and don't call it with a lock held that can also be held
 1550  * by a filesystem operation.
 1551  *
 1552  * Added in FUSE protocol version 7.12. If the kernel does not support
 1553  * this (or a newer) version, the function will return -ENOSYS and do
 1554  * nothing.
 1555  *
 1556  * @param se the session object
 1557  * @param parent inode number
 1558  * @param name file name
 1559  * @param namelen strlen() of file name
 1560  * @return zero for success, -errno for failure
 1561  */
 1562 int fuse_lowlevel_notify_inval_entry(struct fuse_session *se, fuse_ino_t parent,
 1563                      const char *name, size_t namelen);
 1564 
 1565 /**
 1566  * This function behaves like fuse_lowlevel_notify_inval_entry() with
 1567  * the following additional effect (at least as of Linux kernel 4.8):
 1568  *
 1569  * If the provided *child* inode matches the inode that is currently
 1570  * associated with the cached dentry, and if there are any inotify
 1571  * watches registered for the dentry, then the watchers are informed
 1572  * that the dentry has been deleted.
 1573  *
 1574  * To avoid a deadlock don't call this function from a filesystem
 1575  * operation and don't call it with a lock held that can also be held
 1576  * by a filesystem operation.
 1577  *
 1578  * Added in FUSE protocol version 7.18. If the kernel does not support
 1579  * this (or a newer) version, the function will return -ENOSYS and do
 1580  * nothing.
 1581  *
 1582  * @param se the session object
 1583  * @param parent inode number
 1584  * @param child inode number
 1585  * @param name file name
 1586  * @param namelen strlen() of file name
 1587  * @return zero for success, -errno for failure
 1588  */
 1589 int fuse_lowlevel_notify_delete(struct fuse_session *se,
 1590                 fuse_ino_t parent, fuse_ino_t child,
 1591                 const char *name, size_t namelen);
 1592 
 1593 /**
 1594  * Store data to the kernel buffers
 1595  *
 1596  * Synchronously store data in the kernel buffers belonging to the
 1597  * given inode.  The stored data is marked up-to-date (no read will be
 1598  * performed against it, unless it's invalidated or evicted from the
 1599  * cache).
 1600  *
 1601  * If the stored data overflows the current file size, then the size
 1602  * is extended, similarly to a write(2) on the filesystem.
 1603  *
 1604  * If this function returns an error, then the store wasn't fully
 1605  * completed, but it may have been partially completed.
 1606  *
 1607  * Added in FUSE protocol version 7.15. If the kernel does not support
 1608  * this (or a newer) version, the function will return -ENOSYS and do
 1609  * nothing.
 1610  *
 1611  * @param se the session object
 1612  * @param ino the inode number
 1613  * @param offset the starting offset into the file to store to
 1614  * @param bufv buffer vector
 1615  * @param flags flags controlling the copy
 1616  * @return zero for success, -errno for failure
 1617  */
 1618 int fuse_lowlevel_notify_store(struct fuse_session *se, fuse_ino_t ino,
 1619                    off_t offset, struct fuse_bufvec *bufv,
 1620                    enum fuse_buf_copy_flags flags);
 1621 /**
 1622  * Retrieve data from the kernel buffers
 1623  *
 1624  * Retrieve data in the kernel buffers belonging to the given inode.
 1625  * If successful then the retrieve_reply() method will be called with
 1626  * the returned data.
 1627  *
 1628  * Only present pages are returned in the retrieve reply.  Retrieving
 1629  * stops when it finds a non-present page and only data prior to that
 1630  * is returned.
 1631  *
 1632  * If this function returns an error, then the retrieve will not be
 1633  * completed and no reply will be sent.
 1634  *
 1635  * This function doesn't change the dirty state of pages in the kernel
 1636  * buffer.  For dirty pages the write() method will be called
 1637  * regardless of having been retrieved previously.
 1638  *
 1639  * Added in FUSE protocol version 7.15. If the kernel does not support
 1640  * this (or a newer) version, the function will return -ENOSYS and do
 1641  * nothing.
 1642  *
 1643  * @param se the session object
 1644  * @param ino the inode number
 1645  * @param size the number of bytes to retrieve
 1646  * @param offset the starting offset into the file to retrieve from
 1647  * @param cookie user data to supply to the reply callback
 1648  * @return zero for success, -errno for failure
 1649  */
 1650 int fuse_lowlevel_notify_retrieve(struct fuse_session *se, fuse_ino_t ino,
 1651                   size_t size, off_t offset, void *cookie);
 1652 
 1653 
 1654 /* ----------------------------------------------------------- *
 1655  * Utility functions                           *
 1656  * ----------------------------------------------------------- */
 1657 
 1658 /**
 1659  * Get the userdata from the request
 1660  *
 1661  * @param req request handle
 1662  * @return the user data passed to fuse_session_new()
 1663  */
 1664 void *fuse_req_userdata(fuse_req_t req);
 1665 
 1666 /**
 1667  * Get the context from the request
 1668  *
 1669  * The pointer returned by this function will only be valid for the
 1670  * request's lifetime
 1671  *
 1672  * @param req request handle
 1673  * @return the context structure
 1674  */
 1675 const struct fuse_ctx *fuse_req_ctx(fuse_req_t req);
 1676 
 1677 /**
 1678  * Get the current supplementary group IDs for the specified request
 1679  *
 1680  * Similar to the getgroups(2) system call, except the return value is
 1681  * always the total number of group IDs, even if it is larger than the
 1682  * specified size.
 1683  *
 1684  * The current fuse kernel module in linux (as of 2.6.30) doesn't pass
 1685  * the group list to userspace, hence this function needs to parse
 1686  * "/proc/$TID/task/$TID/status" to get the group IDs.
 1687  *
 1688  * This feature may not be supported on all operating systems.  In
 1689  * such a case this function will return -ENOSYS.
 1690  *
 1691  * @param req request handle
 1692  * @param size size of given array
 1693  * @param list array of group IDs to be filled in
 1694  * @return the total number of supplementary group IDs or -errno on failure
 1695  */
 1696 int fuse_req_getgroups(fuse_req_t req, int size, gid_t list[]);
 1697 
 1698 /**
 1699  * Callback function for an interrupt
 1700  *
 1701  * @param req interrupted request
 1702  * @param data user data
 1703  */
 1704 typedef void (*fuse_interrupt_func_t)(fuse_req_t req, void *data);
 1705 
 1706 /**
 1707  * Register/unregister callback for an interrupt
 1708  *
 1709  * If an interrupt has already happened, then the callback function is
 1710  * called from within this function, hence it's not possible for
 1711  * interrupts to be lost.
 1712  *
 1713  * @param req request handle
 1714  * @param func the callback function or NULL for unregister
 1715  * @param data user data passed to the callback function
 1716  */
 1717 void fuse_req_interrupt_func(fuse_req_t req, fuse_interrupt_func_t func,
 1718                  void *data);
 1719 
 1720 /**
 1721  * Check if a request has already been interrupted
 1722  *
 1723  * @param req request handle
 1724  * @return 1 if the request has been interrupted, 0 otherwise
 1725  */
 1726 int fuse_req_interrupted(fuse_req_t req);
 1727 
 1728 
 1729 /* ----------------------------------------------------------- *
 1730  * Inquiry functions                                           *
 1731  * ----------------------------------------------------------- */
 1732 
 1733 /**
 1734  * Print low-level version information to stdout.
 1735  */
 1736 void fuse_lowlevel_version(void);
 1737 
 1738 /**
 1739  * Print available low-level options to stdout. This is not an
 1740  * exhaustive list, but includes only those options that may be of
 1741  * interest to an end-user of a file system.
 1742  */
 1743 void fuse_lowlevel_help(void);
 1744 
 1745 /**
 1746  * Print available options for `fuse_parse_cmdline()`.
 1747  */
 1748 void fuse_cmdline_help(void);
 1749 
 1750 /* ----------------------------------------------------------- *
 1751  * Filesystem setup & teardown                                 *
 1752  * ----------------------------------------------------------- */
 1753 
 1754 struct fuse_cmdline_opts {
 1755     int singlethread;
 1756     int foreground;
 1757     int debug;
 1758     int nodefault_subtype;
 1759     char *mountpoint;
 1760     int show_version;
 1761     int show_help;
 1762     int clone_fd;
 1763     unsigned int max_idle_threads;
 1764 };
 1765 
 1766 /**
 1767  * Utility function to parse common options for simple file systems
 1768  * using the low-level API. A help text that describes the available
 1769  * options can be printed with `fuse_cmdline_help`. A single
 1770  * non-option argument is treated as the mountpoint. Multiple
 1771  * non-option arguments will result in an error.
 1772  *
 1773  * If neither -o subtype= or -o fsname= options are given, a new
 1774  * subtype option will be added and set to the basename of the program
 1775  * (the fsname will remain unset, and then defaults to "fuse").
 1776  *
 1777  * Known options will be removed from *args*, unknown options will
 1778  * remain.
 1779  *
 1780  * @param args argument vector (input+output)
 1781  * @param opts output argument for parsed options
 1782  * @return 0 on success, -1 on failure
 1783  */
 1784 int fuse_parse_cmdline(struct fuse_args *args,
 1785                struct fuse_cmdline_opts *opts);
 1786 
 1787 /**
 1788  * Create a low level session.
 1789  *
 1790  * Returns a session structure suitable for passing to
 1791  * fuse_session_mount() and fuse_session_loop().
 1792  *
 1793  * This function accepts most file-system independent mount options
 1794  * (like context, nodev, ro - see mount(8)), as well as the general
 1795  * fuse mount options listed in mount.fuse(8) (e.g. -o allow_root and
 1796  * -o default_permissions, but not ``-o use_ino``).  Instead of `-o
 1797  * debug`, debugging may also enabled with `-d` or `--debug`.
 1798  *
 1799  * If not all options are known, an error message is written to stderr
 1800  * and the function returns NULL.
 1801  *
 1802  * Option parsing skips argv[0], which is assumed to contain the
 1803  * program name. To prevent accidentially passing an option in
 1804  * argv[0], this element must always be present (even if no options
 1805  * are specified). It may be set to the empty string ('\0') if no
 1806  * reasonable value can be provided.
 1807  *
 1808  * @param args argument vector
 1809  * @param op the (low-level) filesystem operations
 1810  * @param op_size sizeof(struct fuse_lowlevel_ops)
 1811  * @param userdata user data
 1812  *
 1813  * @return the fuse session on success, NULL on failure
 1814  **/
 1815 struct fuse_session *fuse_session_new(struct fuse_args *args,
 1816                       const struct fuse_lowlevel_ops *op,
 1817                       size_t op_size, void *userdata);
 1818 
 1819 /**
 1820  * Mount a FUSE file system.
 1821  *
 1822  * @param mountpoint the mount point path
 1823  * @param se session object
 1824  *
 1825  * @return 0 on success, -1 on failure.
 1826  **/
 1827 int fuse_session_mount(struct fuse_session *se, const char *mountpoint);
 1828 
 1829 /**
 1830  * Enter a single threaded, blocking event loop.
 1831  *
 1832  * When the event loop terminates because the connection to the FUSE
 1833  * kernel module has been closed, this function returns zero. This
 1834  * happens when the filesystem is unmounted regularly (by the
 1835  * filesystem owner or root running the umount(8) or fusermount(1)
 1836  * command), or if connection is explicitly severed by writing ``1``
 1837  * to the``abort`` file in ``/sys/fs/fuse/connections/NNN``. The only
 1838  * way to distinguish between these two conditions is to check if the
 1839  * filesystem is still mounted after the session loop returns.
 1840  *
 1841  * When some error occurs during request processing, the function
 1842  * returns a negated errno(3) value.
 1843  *
 1844  * If the loop has been terminated because of a signal handler
 1845  * installed by fuse_set_signal_handlers(), this function returns the
 1846  * (positive) signal value that triggered the exit.
 1847  *
 1848  * @param se the session
 1849  * @return 0, -errno, or a signal value
 1850  */
 1851 int fuse_session_loop(struct fuse_session *se);
 1852 
 1853 /**
 1854  * Enter a multi-threaded event loop.
 1855  *
 1856  * For a description of the return value and the conditions when the
 1857  * event loop exits, refer to the documentation of
 1858  * fuse_session_loop().
 1859  *
 1860  * @param se the session
 1861  * @param config session loop configuration 
 1862  * @return see fuse_session_loop()
 1863  */
 1864 #if FUSE_USE_VERSION < 32
 1865 int fuse_session_loop_mt_31(struct fuse_session *se, int clone_fd);
 1866 #define fuse_session_loop_mt(se, clone_fd) fuse_session_loop_mt_31(se, clone_fd)
 1867 #else
 1868 int fuse_session_loop_mt(struct fuse_session *se, struct fuse_loop_config *config);
 1869 #endif
 1870 
 1871 /**
 1872  * Flag a session as terminated.
 1873  *
 1874  * This function is invoked by the POSIX signal handlers, when
 1875  * registered using fuse_set_signal_handlers(). It will cause any
 1876  * running event loops to terminate on the next opportunity.
 1877  *
 1878  * @param se the session
 1879  */
 1880 void fuse_session_exit(struct fuse_session *se);
 1881 
 1882 /**
 1883  * Reset the terminated flag of a session
 1884  *
 1885  * @param se the session
 1886  */
 1887 void fuse_session_reset(struct fuse_session *se);
 1888 
 1889 /**
 1890  * Query the terminated flag of a session
 1891  *
 1892  * @param se the session
 1893  * @return 1 if exited, 0 if not exited
 1894  */
 1895 int fuse_session_exited(struct fuse_session *se);
 1896 
 1897 /**
 1898  * Ensure that file system is unmounted.
 1899  *
 1900  * In regular operation, the file system is typically unmounted by the
 1901  * user calling umount(8) or fusermount(1), which then terminates the
 1902  * FUSE session loop. However, the session loop may also terminate as
 1903  * a result of an explicit call to fuse_session_exit() (e.g. by a
 1904  * signal handler installed by fuse_set_signal_handler()). In this
 1905  * case the filesystem remains mounted, but any attempt to access it
 1906  * will block (while the filesystem process is still running) or give
 1907  * an ESHUTDOWN error (after the filesystem process has terminated).
 1908  *
 1909  * If the communication channel with the FUSE kernel module is still
 1910  * open (i.e., if the session loop was terminated by an explicit call
 1911  * to fuse_session_exit()), this function will close it and unmount
 1912  * the filesystem. If the communication channel has been closed by the
 1913  * kernel, this method will do (almost) nothing.
 1914  *
 1915  * NOTE: The above semantics mean that if the connection to the kernel
 1916  * is terminated via the ``/sys/fs/fuse/connections/NNN/abort`` file,
 1917  * this method will *not* unmount the filesystem.
 1918  *
 1919  * @param se the session
 1920  */
 1921 void fuse_session_unmount(struct fuse_session *se);
 1922 
 1923 /**
 1924  * Destroy a session
 1925  *
 1926  * @param se the session
 1927  */
 1928 void fuse_session_destroy(struct fuse_session *se);
 1929 
 1930 /* ----------------------------------------------------------- *
 1931  * Custom event loop support                                   *
 1932  * ----------------------------------------------------------- */
 1933 
 1934 /**
 1935  * Return file descriptor for communication with kernel.
 1936  *
 1937  * The file selector can be used to integrate FUSE with a custom event
 1938  * loop. Whenever data is available for reading on the provided fd,
 1939  * the event loop should call `fuse_session_receive_buf` followed by
 1940  * `fuse_session_process_buf` to process the request.
 1941  *
 1942  * The returned file descriptor is valid until `fuse_session_unmount`
 1943  * is called.
 1944  *
 1945  * @param se the session
 1946  * @return a file descriptor
 1947  */
 1948 int fuse_session_fd(struct fuse_session *se);
 1949 
 1950 /**
 1951  * Process a raw request supplied in a generic buffer
 1952  *
 1953  * The fuse_buf may contain a memory buffer or a pipe file descriptor.
 1954  *
 1955  * @param se the session
 1956  * @param buf the fuse_buf containing the request
 1957  */
 1958 void fuse_session_process_buf(struct fuse_session *se,
 1959                   const struct fuse_buf *buf);
 1960 
 1961 /**
 1962  * Read a raw request from the kernel into the supplied buffer.
 1963  *
 1964  * Depending on file system options, system capabilities, and request
 1965  * size the request is either read into a memory buffer or spliced
 1966  * into a temporary pipe.
 1967  *
 1968  * @param se the session
 1969  * @param buf the fuse_buf to store the request in
 1970  * @return the actual size of the raw request, or -errno on error
 1971  */
 1972 int fuse_session_receive_buf(struct fuse_session *se, struct fuse_buf *buf);
 1973 
 1974 #ifdef __cplusplus
 1975 }
 1976 #endif
 1977 
 1978 #endif /* FUSE_LOWLEVEL_H_ */