include/fuse_common.h

   1 /*
   2   FUSE: Filesystem in Userspace
   3   Copyright (C) 2001-2007  Miklos Szeredi <miklos@szeredi.hu>
   4
   5   This program can be distributed under the terms of the GNU LGPLv2.
   6   See the file COPYING.LIB.
   7 */
   8
   9 /** @file */
  10
  11 #if !defined(_FUSE_H_) && !defined(_FUSE_LOWLEVEL_H_)
  12 #error "Never include <fuse_common.h> directly; use <fuse.h> or <fuse_lowlevel.h> instead."
  13 #endif
  14
  15 #ifndef _FUSE_COMMON_H_
  16 #define _FUSE_COMMON_H_
  17
  18 #include "fuse_opt.h"
  19 #include <stdint.h>
  20 #include <sys/types.h>
  21
  22 /** Major version of FUSE library interface */
  23 #define FUSE_MAJOR_VERSION 2
  24
  25 /** Minor version of FUSE library interface */
  26 #define FUSE_MINOR_VERSION 9
  27
  28 #define FUSE_MAKE_VERSION(maj, min)  ((maj) * 10 + (min))
  29 #define FUSE_VERSION FUSE_MAKE_VERSION(FUSE_MAJOR_VERSION, FUSE_MINOR_VERSION)
  30
  31 /* This interface uses 64 bit off_t */
  32 #if _FILE_OFFSET_BITS != 64
  33 #error Please add -D_FILE_OFFSET_BITS=64 to your compile flags!
  34 #endif
  35
  36 #ifdef __cplusplus
  37 extern "C" {
  38 #endif
  39
  40 /**
  41  * Information about open files
  42  *
  43  * Changed in version 2.5
  44  */
  45 struct fuse_file_info {
  46         /** Open flags.  Available in open() and release() */
  47         int flags;
  48
  49         /** Old file handle, don't use */
  50         unsigned long fh_old;
  51
  52         /** In case of a write operation indicates if this was caused by a
  53             writepage */
  54         int writepage;
  55
  56         /** Can be filled in by open, to use direct I/O on this file.
  57             Introduced in version 2.4 */
  58         unsigned int direct_io : 1;
  59
  60         /** Can be filled in by open, to indicate, that cached file data
  61             need not be invalidated.  Introduced in version 2.4 */
  62         unsigned int keep_cache : 1;
  63
  64         /** Indicates a flush operation.  Set in flush operation, also
  65             maybe set in highlevel lock operation and lowlevel release
  66             operation.  Introduced in version 2.6 */
  67         unsigned int flush : 1;
  68
  69         /** Can be filled in by open, to indicate that the file is not
  70             seekable.  Introduced in version 2.8 */
  71         unsigned int nonseekable : 1;
  72
  73         /* Indicates that flock locks for this file should be
  74            released.  If set, lock_owner shall contain a valid value.
  75            May only be set in ->release().  Introduced in version
  76            2.9 */
  77         unsigned int flock_release : 1;
  78
  79         /** Padding.  Do not use*/
  80         unsigned int padding : 27;
  81
  82         /** File handle.  May be filled in by filesystem in open().
  83             Available in all other file operations */
  84         uint64_t fh;
  85
  86         /** Lock owner id.  Available in locking operations and flush */
  87         uint64_t lock_owner;
  88 };
  89
  90 /**
  91  * Capability bits for 'fuse_conn_info.capable' and 'fuse_conn_info.want'
  92  *
  93  * FUSE_CAP_ASYNC_READ: filesystem supports asynchronous read requests
  94  * FUSE_CAP_POSIX_LOCKS: filesystem supports "remote" locking
  95  * FUSE_CAP_ATOMIC_O_TRUNC: filesystem handles the O_TRUNC open flag
  96  * FUSE_CAP_EXPORT_SUPPORT: filesystem handles lookups of "." and ".."
  97  * FUSE_CAP_BIG_WRITES: filesystem can handle write size larger than 4kB
  98  * FUSE_CAP_DONT_MASK: don't apply umask to file mode on create operations
  99  * FUSE_CAP_SPLICE_WRITE: ability to use splice() to write to the fuse device
 100  * FUSE_CAP_SPLICE_MOVE: ability to move data to the fuse device with splice()
 101  * FUSE_CAP_SPLICE_READ: ability to use splice() to read from the fuse device
 102  * FUSE_CAP_IOCTL_DIR: ioctl support on directories
 103  */
 104 #define FUSE_CAP_ASYNC_READ     (1 << 0)
 105 #define FUSE_CAP_POSIX_LOCKS    (1 << 1)
 106 #define FUSE_CAP_ATOMIC_O_TRUNC (1 << 3)
 107 #define FUSE_CAP_EXPORT_SUPPORT (1 << 4)
 108 #define FUSE_CAP_BIG_WRITES     (1 << 5)
 109 #define FUSE_CAP_DONT_MASK      (1 << 6)
 110 #define FUSE_CAP_SPLICE_WRITE   (1 << 7)
 111 #define FUSE_CAP_SPLICE_MOVE    (1 << 8)
 112 #define FUSE_CAP_SPLICE_READ    (1 << 9)
 113 #define FUSE_CAP_FLOCK_LOCKS    (1 << 10)
 114 #define FUSE_CAP_IOCTL_DIR      (1 << 11)
 115
 116 /**
 117  * Ioctl flags
 118  *
 119  * FUSE_IOCTL_COMPAT: 32bit compat ioctl on 64bit machine
 120  * FUSE_IOCTL_UNRESTRICTED: not restricted to well-formed ioctls, retry allowed
 121  * FUSE_IOCTL_RETRY: retry with new iovecs
 122  * FUSE_IOCTL_DIR: is a directory
 123  *
 124  * FUSE_IOCTL_MAX_IOV: maximum of in_iovecs + out_iovecs
 125  */
 126 #define FUSE_IOCTL_COMPAT       (1 << 0)
 127 #define FUSE_IOCTL_UNRESTRICTED (1 << 1)
 128 #define FUSE_IOCTL_RETRY        (1 << 2)
 129 #define FUSE_IOCTL_DIR          (1 << 4)
 130
 131 #define FUSE_IOCTL_MAX_IOV      256
 132
 133 /**
 134  * Connection information, passed to the ->init() method
 135  *
 136  * Some of the elements are read-write, these can be changed to
 137  * indicate the value requested by the filesystem.  The requested
 138  * value must usually be smaller than the indicated value.
 139  */
 140 struct fuse_conn_info {
 141         /**
 142          * Major version of the protocol (read-only)
 143          */
 144         unsigned proto_major;
 145
 146         /**
 147          * Minor version of the protocol (read-only)
 148          */
 149         unsigned proto_minor;
 150
 151         /**
 152          * Is asynchronous read supported (read-write)
 153          */
 154         unsigned async_read;
 155
 156         /**
 157          * Maximum size of the write buffer
 158          */
 159         unsigned max_write;
 160
 161         /**
 162          * Maximum readahead
 163          */
 164         unsigned max_readahead;
 165
 166         /**
 167          * Capability flags, that the kernel supports
 168          */
 169         unsigned capable;
 170
 171         /**
 172          * Capability flags, that the filesystem wants to enable
 173          */
 174         unsigned want;
 175
 176         /**
 177          * Maximum number of backgrounded requests
 178          */
 179         unsigned max_background;
 180
 181         /**
 182          * Kernel congestion threshold parameter
 183          */
 184         unsigned congestion_threshold;
 185
 186         /**
 187          * For future use.
 188          */
 189         unsigned reserved[23];
 190 };
 191
 192 struct fuse_session;
 193 struct fuse_chan;
 194 struct fuse_pollhandle;
 195
 196 /**
 197  * Create a FUSE mountpoint
 198  *
 199  * Returns a control file descriptor suitable for passing to
 200  * fuse_new()
 201  *
 202  * @param mountpoint the mount point path
 203  * @param args argument vector
 204  * @return the communication channel on success, NULL on failure
 205  */
 206 struct fuse_chan *fuse_mount(const char *mountpoint, struct fuse_args *args);
 207
 208 /**
 209  * Umount a FUSE mountpoint
 210  *
 211  * @param mountpoint the mount point path
 212  * @param ch the communication channel
 213  */
 214 void fuse_unmount(const char *mountpoint, struct fuse_chan *ch);
 215
 216 /**
 217  * Parse common options
 218  *
 219  * The following options are parsed:
 220  *
 221  *   '-f'            foreground
 222  *   '-d' '-odebug'  foreground, but keep the debug option
 223  *   '-s'            single threaded
 224  *   '-h' '--help'   help
 225  *   '-ho'           help without header
 226  *   '-ofsname=..'   file system name, if not present, then set to the program
 227  *                   name
 228  *
 229  * All parameters may be NULL
 230  *
 231  * @param args argument vector
 232  * @param mountpoint the returned mountpoint, should be freed after use
 233  * @param multithreaded set to 1 unless the '-s' option is present
 234  * @param foreground set to 1 if one of the relevant options is present
 235  * @return 0 on success, -1 on failure
 236  */
 237 int fuse_parse_cmdline(struct fuse_args *args, char **mountpoint,
 238                        int *multithreaded, int *foreground);
 239
 240 /**
 241  * Go into the background
 242  *
 243  * @param foreground if true, stay in the foreground
 244  * @return 0 on success, -1 on failure
 245  */
 246 int fuse_daemonize(int foreground);
 247
 248 /**
 249  * Get the version of the library
 250  *
 251  * @return the version
 252  */
 253 int fuse_version(void);
 254
 255 /**
 256  * Destroy poll handle
 257  *
 258  * @param ph the poll handle
 259  */
 260 void fuse_pollhandle_destroy(struct fuse_pollhandle *ph);
 261
 262 /* ----------------------------------------------------------- *
 263  * Data buffer                                                 *
 264  * ----------------------------------------------------------- */
 265
 266 /**
 267  * Buffer flags
 268  */
 269 enum fuse_buf_flags {
 270         /**
 271          * Buffer contains a file descriptor
 272          *
 273          * If this flag is set, the .fd field is valid, otherwise the
 274          * .mem fields is valid.
 275          */
 276         FUSE_BUF_IS_FD          = (1 << 1),
 277
 278         /**
 279          * Seek on the file descriptor
 280          *
 281          * If this flag is set then the .pos field is valid and is
 282          * used to seek to the given offset before performing
 283          * operation on file descriptor.
 284          */
 285         FUSE_BUF_FD_SEEK        = (1 << 2),
 286
 287         /**
 288          * Retry operation on file descriptor
 289          *
 290          * If this flag is set then retry operation on file descriptor
 291          * until .size bytes have been copied or an error or EOF is
 292          * detected.
 293          */
 294         FUSE_BUF_FD_RETRY       = (1 << 3),
 295 };
 296
 297 /**
 298  * Buffer copy flags
 299  */
 300 enum fuse_buf_copy_flags {
 301         /**
 302          * Don't use splice(2)
 303          *
 304          * Always fall back to using read and write instead of
 305          * splice(2) to copy data from one file descriptor to another.
 306          *
 307          * If this flag is not set, then only fall back if splice is
 308          * unavailable.
 309          */
 310         FUSE_BUF_NO_SPLICE      = (1 << 1),
 311
 312         /**
 313          * Force splice
 314          *
 315          * Always use splice(2) to copy data from one file descriptor
 316          * to another.  If splice is not available, return -EINVAL.
 317          */
 318         FUSE_BUF_FORCE_SPLICE   = (1 << 2),
 319
 320         /**
 321          * Try to move data with splice.
 322          *
 323          * If splice is used, try to move pages from the source to the
 324          * destination instead of copying.  See documentation of
 325          * SPLICE_F_MOVE in splice(2) man page.
 326          */
 327         FUSE_BUF_SPLICE_MOVE    = (1 << 3),
 328
 329         /**
 330          * Don't block on the pipe when copying data with splice
 331          *
 332          * Makes the operations on the pipe non-blocking (if the pipe
 333          * is full or empty).  See SPLICE_F_NONBLOCK in the splice(2)
 334          * man page.
 335          */
 336         FUSE_BUF_SPLICE_NONBLOCK= (1 << 4),
 337 };
 338
 339 /**
 340  * Single data buffer
 341  *
 342  * Generic data buffer for I/O, extended attributes, etc...  Data may
 343  * be supplied as a memory pointer or as a file descriptor
 344  */
 345 struct fuse_buf {
 346         /**
 347          * Size of data in bytes
 348          */
 349         size_t size;
 350
 351         /**
 352          * Buffer flags
 353          */
 354         enum fuse_buf_flags flags;
 355
 356         /**
 357          * Memory pointer
 358          *
 359          * Used unless FUSE_BUF_IS_FD flag is set.
 360          */
 361         void *mem;
 362
 363         /**
 364          * File descriptor
 365          *
 366          * Used if FUSE_BUF_IS_FD flag is set.
 367          */
 368         int fd;
 369
 370         /**
 371          * File position
 372          *
 373          * Used if FUSE_BUF_FD_SEEK flag is set.
 374          */
 375         off_t pos;
 376 };
 377
 378 /**
 379  * Data buffer vector
 380  *
 381  * An array of data buffers, each containing a memory pointer or a
 382  * file descriptor.
 383  *
 384  * Allocate dynamically to add more than one buffer.
 385  */
 386 struct fuse_bufvec {
 387         /**
 388          * Number of buffers in the array
 389          */
 390         size_t count;
 391
 392         /**
 393          * Index of current buffer within the array
 394          */
 395         size_t idx;
 396
 397         /**
 398          * Current offset within the current buffer
 399          */
 400         size_t off;
 401
 402         /**
 403          * Array of buffers
 404          */
 405         struct fuse_buf buf[1];
 406 };
 407
 408 /* Initialize bufvec with a single buffer of given size */
 409 #define FUSE_BUFVEC_INIT(size__)                                \
 410         ((struct fuse_bufvec) {                                 \
 411                 /* .count= */ 1,                                \
 412                 /* .idx =  */ 0,                                \
 413                 /* .off =  */ 0,                                \
 414                 /* .buf =  */ { /* [0] = */ {                   \
 415                         /* .size =  */ (size__),                \
 416                         /* .flags = */ (enum fuse_buf_flags) 0, \
 417                         /* .mem =   */ NULL,                    \
 418                         /* .fd =    */ -1,                      \
 419                         /* .pos =   */ 0,                       \
 420                 } }                                             \
 421         } )
 422
 423 /**
 424  * Get total size of data in a fuse buffer vector
 425  *
 426  * @param bufv buffer vector
 427  * @return size of data
 428  */
 429 size_t fuse_buf_size(const struct fuse_bufvec *bufv);
 430
 431 /**
 432  * Copy data from one buffer vector to another
 433  *
 434  * @param dst destination buffer vector
 435  * @param src source buffer vector
 436  * @param flags flags controlling the copy
 437  * @return actual number of bytes copied or -errno on error
 438  */
 439 ssize_t fuse_buf_copy(struct fuse_bufvec *dst, struct fuse_bufvec *src,
 440                       enum fuse_buf_copy_flags flags);
 441
 442 /* ----------------------------------------------------------- *
 443  * Signal handling                                             *
 444  * ----------------------------------------------------------- */
 445
 446 /**
 447  * Exit session on HUP, TERM and INT signals and ignore PIPE signal
 448  *
 449  * Stores session in a global variable.  May only be called once per
 450  * process until fuse_remove_signal_handlers() is called.
 451  *
 452  * @param se the session to exit
 453  * @return 0 on success, -1 on failure
 454  */
 455 int fuse_set_signal_handlers(struct fuse_session *se);
 456
 457 /**
 458  * Restore default signal handlers
 459  *
 460  * Resets global session.  After this fuse_set_signal_handlers() may
 461  * be called again.
 462  *
 463  * @param se the same session as given in fuse_set_signal_handlers()
 464  */
 465 void fuse_remove_signal_handlers(struct fuse_session *se);
 466
 467 /* ----------------------------------------------------------- *
 468  * Compatibility stuff                                         *
 469  * ----------------------------------------------------------- */
 470
 471 #if FUSE_USE_VERSION < 26
 472 #    ifdef __FreeBSD__
 473 #        if FUSE_USE_VERSION < 25
 474 #            error On FreeBSD API version 25 or greater must be used
 475 #        endif
 476 #    endif
 477 #    include "fuse_common_compat.h"
 478 #    undef FUSE_MINOR_VERSION
 479 #    undef fuse_main
 480 #    define fuse_unmount fuse_unmount_compat22
 481 #    if FUSE_USE_VERSION == 25
 482 #        define FUSE_MINOR_VERSION 5
 483 #        define fuse_mount fuse_mount_compat25
 484 #    elif FUSE_USE_VERSION == 24 || FUSE_USE_VERSION == 22
 485 #        define FUSE_MINOR_VERSION 4
 486 #        define fuse_mount fuse_mount_compat22
 487 #    elif FUSE_USE_VERSION == 21
 488 #        define FUSE_MINOR_VERSION 1
 489 #        define fuse_mount fuse_mount_compat22
 490 #    elif FUSE_USE_VERSION == 11
 491 #        warning Compatibility with API version 11 is deprecated
 492 #        undef FUSE_MAJOR_VERSION
 493 #        define FUSE_MAJOR_VERSION 1
 494 #        define FUSE_MINOR_VERSION 1
 495 #        define fuse_mount fuse_mount_compat1
 496 #    else
 497 #        error Compatibility with API version other than 21, 22, 24, 25 and 11 not supported
 498 #    endif
 499 #endif
 500
 501 #ifdef __cplusplus
 502 }
 503 #endif
 504
 505 #endif /* _FUSE_COMMON_H_ */