mergerfs/vendored/libfuse/include/fuse_common.h

#pragma once

#include "extern_c.h"
#include "fuse_conn_info.hpp"
#include "fuse_opt.h"
#include "fuse_timeouts.h"

#include <stdint.h>
#include <sys/types.h>

/* This interface uses 64 bit off_t */
#if _FILE_OFFSET_BITS != 64
#error Please add -D_FILE_OFFSET_BITS=64 to your compile flags!
#endif

#define FUSE_DEFAULT_MAX_PAGES_PER_REQ 32
#define FUSE_DEFAULT_MAX_MAX_PAGES 256

EXTERN_C_BEGIN

/**
 * Information about open files
 *
 * Changed in version 2.5
 */
typedef struct fuse_file_info_t fuse_file_info_t;
struct fuse_file_info_t
{
  /** Open flags. Available in open() and release() */
  int flags;

  /** In case of a write operation indicates if this was caused by a
      writepage */
  uint32_t writepage : 1;

  /** Can be filled in by open, to use direct I/O on this file.
      Introduced in version 2.4 */
  uint32_t direct_io : 1;

  /** Can be filled in by open, to indicate, that cached file data
      need not be invalidated.  Introduced in version 2.4 */
  uint32_t keep_cache : 1;

  /** Indicates a flush operation.  Set in flush operation, also
      maybe set in highlevel lock operation and lowlevel release
      operation.	Introduced in version 2.6 */
  uint32_t flush : 1;

  /** Can be filled in by open, to indicate that the file is not
      seekable.  Introduced in version 2.8 */
  uint32_t nonseekable : 1;

  /* Indicates that flock locks for this file should be
     released.  If set, lock_owner shall contain a valid value.
     May only be set in ->release().  Introduced in version
     2.9 */
  uint32_t flock_release : 1;

  /* Requests the kernel to cache entries returned by readdir */
  uint32_t cache_readdir : 1;

  uint32_t auto_cache : 1;

  uint32_t parallel_direct_writes:1;

  uint32_t noflush:1;
  uint32_t passthrough:1;

  /** File handle.  May be filled in by filesystem in open().
      Available in all other file operations */
  uint64_t fh;

  int32_t  backing_id;

  /** Lock owner id.  Available in locking operations and flush */
  uint64_t lock_owner;
};

/**
 * Capability bits for 'fuse_conn_info_t.capable' and 'fuse_conn_info_t.want'
 *
 * FUSE_CAP_ASYNC_READ: filesystem supports asynchronous read requests
 * FUSE_CAP_POSIX_LOCKS: filesystem supports "remote" locking
 * FUSE_CAP_ATOMIC_O_TRUNC: filesystem handles the O_TRUNC open flag
 * FUSE_CAP_EXPORT_SUPPORT: filesystem handles lookups of "." and ".."
 * FUSE_CAP_BIG_WRITES: filesystem can handle write size larger than 4kB
 * FUSE_CAP_DONT_MASK: don't apply umask to file mode on create operations
 * FUSE_CAP_SPLICE_WRITE: ability to use splice() to write to the fuse device
 * FUSE_CAP_SPLICE_MOVE: ability to move data to the fuse device with splice()
 * FUSE_CAP_SPLICE_READ: ability to use splice() to read from the fuse device
 * FUSE_CAP_IOCTL_DIR: ioctl support on directories
 * FUSE_CAP_CACHE_SYMLINKS: cache READLINK responses
 */
#define FUSE_CAP_ASYNC_READ           (1ULL << 0)
#define FUSE_CAP_POSIX_LOCKS          (1ULL << 1)
#define FUSE_CAP_ATOMIC_O_TRUNC       (1ULL << 3)
#define FUSE_CAP_EXPORT_SUPPORT       (1ULL << 4)
#define FUSE_CAP_BIG_WRITES           (1ULL << 5)
#define FUSE_CAP_DONT_MASK            (1ULL << 6)
/* Same values as the FUSE_SPLICE_WRITE/MOVE/READ wire
   flags in fuse_kernel.h */
#define FUSE_CAP_SPLICE_WRITE         (1ULL << 7)
#define FUSE_CAP_SPLICE_MOVE          (1ULL << 8)
#define FUSE_CAP_SPLICE_READ          (1ULL << 9)
#define FUSE_CAP_FLOCK_LOCKS          (1ULL << 10)
#define FUSE_CAP_IOCTL_DIR            (1ULL << 11)
#define FUSE_CAP_READDIR_PLUS         (1ULL << 13)
#define FUSE_CAP_READDIR_PLUS_AUTO    (1ULL << 14)
#define FUSE_CAP_ASYNC_DIO            (1ULL << 15)
#define FUSE_CAP_WRITEBACK_CACHE      (1ULL << 16)
#define FUSE_CAP_PARALLEL_DIROPS      (1ULL << 18)
#define FUSE_CAP_POSIX_ACL            (1ULL << 19)
#define FUSE_CAP_CACHE_SYMLINKS       (1ULL << 20)
#define FUSE_CAP_MAX_PAGES            (1ULL << 21)
#define FUSE_CAP_SETXATTR_EXT         (1ULL << 22)
#define FUSE_CAP_DIRECT_IO_ALLOW_MMAP (1ULL << 23)
#define FUSE_CAP_CREATE_SUPP_GROUP    (1ULL << 24)
#define FUSE_CAP_PASSTHROUGH          (1ULL << 25)
#define FUSE_CAP_HANDLE_KILLPRIV      (1ULL << 26)
#define FUSE_CAP_HANDLE_KILLPRIV_V2   (1ULL << 27)
#define FUSE_CAP_ALLOW_IDMAP          (1ULL << 28)

/**
 * Ioctl flags
 *
 * FUSE_IOCTL_COMPAT: 32bit compat ioctl on 64bit machine
 * FUSE_IOCTL_UNRESTRICTED: not restricted to well-formed ioctls, retry allowed
 * FUSE_IOCTL_RETRY: retry with new iovecs
 * FUSE_IOCTL_DIR: is a directory
 *
 * FUSE_IOCTL_MAX_IOV: maximum of in_iovecs + out_iovecs
 */
#define FUSE_IOCTL_COMPAT	(1 << 0)
#define FUSE_IOCTL_UNRESTRICTED	(1 << 1)
#define FUSE_IOCTL_RETRY	(1 << 2)
#define FUSE_IOCTL_DIR		(1 << 4)

#define FUSE_IOCTL_MAX_IOV	256

struct fuse_session;
struct fuse_chan;
struct fuse_pollhandle_t;
typedef struct fuse_pollhandle_t fuse_pollhandle_t;

/**
 * Mount a FUSE filesystem.
 *
 * This function creates a FUSE mount and returns the /dev/fuse file descriptor.
 * The file descriptor is stored in the session for internal use.
 *
 * @param mountpoint the mount point path
 * @param args argument vector
 * @return the /dev/fuse file descriptor on success, -1 on failure
 */
int fuse_mount(const char *mountpoint, struct fuse_args *args);

/**
 * Umount a FUSE mountpoint
 *
 * @param mountpoint the mount point path
 * @param fd the /dev/fuse file descriptor (or -1 if already closed)
 */
void fuse_unmount(const char *mountpoint, int fd);

/**
 * Parse common options
 *
 * The following options are parsed:
 *
 *   '-f'	     foreground
 *   '-d' '-odebug'  foreground, but keep the debug option
 *   '-h' '--help'   help
 *   '-ho'	     help without header
 *   '-ofsname=..'   file system name, if not present, then set to the program
 *		     name
 *
 * All parameters may be NULL
 *
 * @param args argument vector
 * @param mountpoint the returned mountpoint, should be freed after use
 * @param foreground set to 1 if one of the relevant options is present
 * @return 0 on success, -1 on failure
 */
int fuse_parse_cmdline(struct fuse_args  *args,
                       char             **mountpoint,
                       int               *foreground);

/**
 * Go into the background
 *
 * @param foreground if true, stay in the foreground
 * @return 0 on success, -1 on failure
 */
int fuse_daemonize(int foreground);

/**
 * Get the version of the library
 *
 * @return the version
 */
int fuse_version(void);

/**
 * Destroy poll handle
 *
 * @param ph the poll handle
 */
void fuse_pollhandle_destroy(fuse_pollhandle_t *ph);

/* ----------------------------------------------------------- *
 * Data buffer						       *
 * ----------------------------------------------------------- */

/**
 * Buffer flags
 */
enum fuse_buf_flags {
  /**
   * Buffer contains a file descriptor
   *
   * If this flag is set, the .fd field is valid, otherwise the
   * .mem fields is valid.
   */
  FUSE_BUF_IS_FD		= (1 << 1),

  /**
   * Seek on the file descriptor
   *
   * If this flag is set then the .pos field is valid and is
   * used to seek to the given offset before performing
   * operation on file descriptor.
   */
  FUSE_BUF_FD_SEEK	= (1 << 2),

  /**
   * Retry operation on file descriptor
   *
   * If this flag is set then retry operation on file descriptor
   * until .size bytes have been copied or an error or EOF is
   * detected.
   */
  FUSE_BUF_FD_RETRY	= (1 << 3),
};

/**
 * Buffer copy flags
 */
enum fuse_buf_copy_flags {
  /**
   * Don't use splice(2)
   *
   * Always fall back to using read and write instead of
   * splice(2) to copy data from one file descriptor to another.
   *
   * If this flag is not set, then only fall back if splice is
   * unavailable.
   */
  FUSE_BUF_NO_SPLICE	= (1 << 1),

  /**
   * Force splice
   *
   * Always use splice(2) to copy data from one file descriptor
   * to another.  If splice is not available, return -EINVAL.
   */
  FUSE_BUF_FORCE_SPLICE	= (1 << 2),

  /**
   * Try to move data with splice.
   *
   * If splice is used, try to move pages from the source to the
   * destination instead of copying.  See documentation of
   * SPLICE_F_MOVE in splice(2) man page.
   */
  FUSE_BUF_SPLICE_MOVE	= (1 << 3),

  /**
   * Don't block on the pipe when copying data with splice
   *
   * Makes the operations on the pipe non-blocking (if the pipe
   * is full or empty).  See SPLICE_F_NONBLOCK in the splice(2)
   * man page.
   */
  FUSE_BUF_SPLICE_NONBLOCK= (1 << 4),
};

/**
 * Single data buffer
 *
 * Generic data buffer for I/O, extended attributes, etc...  Data may
 * be supplied as a memory pointer or as a file descriptor
 */
struct fuse_buf {
  /**
   * Size of data in bytes
   */
  size_t size;

  /**
   * Buffer flags
   */
  enum fuse_buf_flags flags;

  /**
   * Memory pointer
   *
   * Used unless FUSE_BUF_IS_FD flag is set.
   */
  void *mem;

  /**
   * File descriptor
   *
   * Used if FUSE_BUF_IS_FD flag is set.
   */
  int fd;

  /**
   * File position
   *
   * Used if FUSE_BUF_FD_SEEK flag is set.
   */
  off_t pos;
};

/* Gather buffer declarations */
#define FUSE_BUFVEC_INIT(size__)                                        \
  /* cppcheck-suppress unassignedVariable */                            \
  (struct fuse_bufvec) {                                                \
    /* .count= */ 1,                                                    \
    /* .idx =  */ 0,                                                    \
    /* .off =  */ 0,                                                    \
    { /* .size =  */ (size__), /* .flags = */ (enum fuse_buf_flags) 0, \
      /* .mem =   */ nullptr,    /* .fd = */ -1, /* .pos = */ 0, }      \
  }

struct fuse_bufvec {
  /**
   * Number of buffers in the array
   */
  size_t count;

  /**
   * Current buffer index
   */
  size_t idx;

  /**
   * Current offset in the buffer
   */
  size_t off;

  /**
   * Array of buffers
   */
  struct fuse_buf buf[1];
};

/**
 * Get the total size of data in a fuse buffer vector
 *
 * @param bufv buffer vector
 * @return computed number of bytes
 */
size_t fuse_buf_size(const struct fuse_bufvec *bufv);

/**
 * Copy data from one buffer vector to another
 *
 * This is mostly useful for a filesystem that uses
 * buffers to refer to the data being written or read
 *
 * @param dstv destination buffer vector
 * @param srcv source buffer vector
 * @param flags flags passed to the buffer copy
 * @return actual number of bytes copied or -errno on error
 */
ssize_t fuse_buf_copy(struct fuse_bufvec *dstv, struct fuse_bufvec *srcv,
                      enum fuse_buf_copy_flags flags);

/* ----------------------------------------------------------- *
 * Signal handling					       *
 * ----------------------------------------------------------- */

/**
 * Exit session on HUP, TERM and INT signals and ignore PIPE signal
 *
 * Stores session in a global variable.	 May only be called once per
 * process until fuse_remove_signal_handlers() is called.
 *
 * @param se the session to exit
 * @return 0 on success, -1 on failure
 */
int fuse_set_signal_handlers(struct fuse_session *se);

/**
 * Restore default signal handlers
 *
 * Resets global session.  After this fuse_set_signal_handlers() may
 * be called again.
 *
 * @param se the same session as given in fuse_set_signal_handlers()
 */
void fuse_remove_signal_handlers(struct fuse_session *se);

EXTERN_C_END

/* C++-only convenience, deliberately declared OUTSIDE EXTERN_C_BEGIN/
   EXTERN_C_END above: this is not part of the C-linkage libfuse-
   compatible API, just a small typed factory used by the splice
   read/write handlers (src/fuse_read_buf.cpp, src/fuse_write_buf.cpp,
   vendored/libfuse/lib/fuse.cpp's fuse_lib_write) so they build a
   single-entry, fd-referencing fuse_bufvec through one call instead of
   each hand-assigning buf[0].flags/fd/pos individually. */
static
inline
struct fuse_bufvec
fuse_bufvec_fd(const int            fd_,
               const off_t          pos_,
               const size_t         size_,
               const fuse_buf_flags flags_)
{
  struct fuse_bufvec bufv = FUSE_BUFVEC_INIT(size_);

  bufv.buf[0].flags = flags_;
  bufv.buf[0].fd    = fd_;
  bufv.buf[0].pos   = pos_;

  return bufv;
}