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  */
 103 #define FUSE_CAP_ASYNC_READ     (1 << 0)
 104 #define FUSE_CAP_POSIX_LOCKS    (1 << 1)
 105 #define FUSE_CAP_ATOMIC_O_TRUNC (1 << 3)
 106 #define FUSE_CAP_EXPORT_SUPPORT (1 << 4)
 107 #define FUSE_CAP_BIG_WRITES     (1 << 5)
 108 #define FUSE_CAP_DONT_MASK      (1 << 6)
 109 #define FUSE_CAP_SPLICE_WRITE   (1 << 7)
 110 #define FUSE_CAP_SPLICE_MOVE    (1 << 8)
 111 #define FUSE_CAP_SPLICE_READ    (1 << 9)
 112 #define FUSE_CAP_FLOCK_LOCKS    (1 << 10)
 113
 114 /**
 115  * Ioctl flags
 116  *
 117  * FUSE_IOCTL_COMPAT: 32bit compat ioctl on 64bit machine
 118  * FUSE_IOCTL_UNRESTRICTED: not restricted to well-formed ioctls, retry allowed
 119  * FUSE_IOCTL_RETRY: retry with new iovecs
 120  *
 121  * FUSE_IOCTL_MAX_IOV: maximum of in_iovecs + out_iovecs
 122  */
 123 #define FUSE_IOCTL_COMPAT       (1 << 0)
 124 #define FUSE_IOCTL_UNRESTRICTED (1 << 1)
 125 #define FUSE_IOCTL_RETRY        (1 << 2)
 126
 127 #define FUSE_IOCTL_MAX_IOV      256
 128
 129 /**
 130  * Connection information, passed to the ->init() method
 131  *
 132  * Some of the elements are read-write, these can be changed to
 133  * indicate the value requested by the filesystem.  The requested
 134  * value must usually be smaller than the indicated value.
 135  */
 136 struct fuse_conn_info {
 137         /**
 138          * Major version of the protocol (read-only)
 139          */
 140         unsigned proto_major;
 141
 142         /**
 143          * Minor version of the protocol (read-only)
 144          */
 145         unsigned proto_minor;
 146
 147         /**
 148          * Is asynchronous read supported (read-write)
 149          */
 150         unsigned async_read;
 151
 152         /**
 153          * Maximum size of the write buffer
 154          */
 155         unsigned max_write;
 156
 157         /**
 158          * Maximum readahead
 159          */
 160         unsigned max_readahead;
 161
 162         /**
 163          * Capability flags, that the kernel supports
 164          */
 165         unsigned capable;
 166
 167         /**
 168          * Capability flags, that the filesystem wants to enable
 169          */
 170         unsigned want;
 171
 172         /**
 173          * Maximum number of backgrounded requests
 174          */
 175         unsigned max_background;
 176
 177         /**
 178          * Kernel congestion threshold parameter
 179          */
 180         unsigned congestion_threshold;
 181
 182         /**
 183          * For future use.
 184          */
 185         unsigned reserved[23];
 186 };
 187
 188 struct fuse_session;
 189 struct fuse_chan;
 190 struct fuse_pollhandle;
 191
 192 /**
 193  * Create a FUSE mountpoint
 194  *
 195  * Returns a control file descriptor suitable for passing to
 196  * fuse_new()
 197  *
 198  * @param mountpoint the mount point path
 199  * @param args argument vector
 200  * @return the communication channel on success, NULL on failure
 201  */
 202 struct fuse_chan *fuse_mount(const char *mountpoint, struct fuse_args *args);
 203
 204 /**
 205  * Umount a FUSE mountpoint
 206  *
 207  * @param mountpoint the mount point path
 208  * @param ch the communication channel
 209  */
 210 void fuse_unmount(const char *mountpoint, struct fuse_chan *ch);
 211
 212 /**
 213  * Parse common options
 214  *
 215  * The following options are parsed:
 216  *
 217  *   '-f'            foreground
 218  *   '-d' '-odebug'  foreground, but keep the debug option
 219  *   '-s'            single threaded
 220  *   '-h' '--help'   help
 221  *   '-ho'           help without header
 222  *   '-ofsname=..'   file system name, if not present, then set to the program
 223  *                   name
 224  *
 225  * All parameters may be NULL
 226  *
 227  * @param args argument vector
 228  * @param mountpoint the returned mountpoint, should be freed after use
 229  * @param multithreaded set to 1 unless the '-s' option is present
 230  * @param foreground set to 1 if one of the relevant options is present
 231  * @return 0 on success, -1 on failure
 232  */
 233 int fuse_parse_cmdline(struct fuse_args *args, char **mountpoint,
 234                        int *multithreaded, int *foreground);
 235
 236 /**
 237  * Go into the background
 238  *
 239  * @param foreground if true, stay in the foreground
 240  * @return 0 on success, -1 on failure
 241  */
 242 int fuse_daemonize(int foreground);
 243
 244 /**
 245  * Get the version of the library
 246  *
 247  * @return the version
 248  */
 249 int fuse_version(void);
 250
 251 /**
 252  * Destroy poll handle
 253  *
 254  * @param ph the poll handle
 255  */
 256 void fuse_pollhandle_destroy(struct fuse_pollhandle *ph);
 257
 258 /* ----------------------------------------------------------- *
 259  * Data buffer                                                 *
 260  * ----------------------------------------------------------- */
 261
 262 /**
 263  * Buffer flags
 264  */
 265 enum fuse_buf_flags {
 266         /**
 267          * Buffer contains a file descriptor
 268          *
 269          * If this flag is set, the .fd field is valid, otherwise the
 270          * .mem fields is valid.
 271          */
 272         FUSE_BUF_IS_FD          = (1 << 1),
 273
 274         /**
 275          * Seek on the file descriptor
 276          *
 277          * If this flag is set then the .pos field is valid and is
 278          * used to seek to the given offset before performing
 279          * operation on file descriptor.
 280          */
 281         FUSE_BUF_FD_SEEK        = (1 << 2),
 282
 283         /**
 284          * Retry operation on file descriptor
 285          *
 286          * If this flag is set then retry operation on file descriptor
 287          * until .size bytes have been copied or an error or EOF is
 288          * detected.
 289          */
 290         FUSE_BUF_FD_RETRY       = (1 << 3),
 291 };
 292
 293 /**
 294  * Buffer copy flags
 295  */
 296 enum fuse_buf_copy_flags {
 297         /**
 298          * Don't use splice(2)
 299          *
 300          * Always fall back to using read and write instead of
 301          * splice(2) to copy data from one file descriptor to another.
 302          *
 303          * If this flag is not set, then only fall back if splice is
 304          * unavailable.
 305          */
 306         FUSE_BUF_NO_SPLICE      = (1 << 1),
 307
 308         /**
 309          * Force splice
 310          *
 311          * Always use splice(2) to copy data from one file descriptor
 312          * to another.  If splice is not available, return -EINVAL.
 313          */
 314         FUSE_BUF_FORCE_SPLICE   = (1 << 2),
 315
 316         /**
 317          * Try to move data with splice.
 318          *
 319          * If splice is used, try to move pages from the source to the
 320          * destination instead of copying.  See documentation of
 321          * SPLICE_F_MOVE in splice(2) man page.
 322          */
 323         FUSE_BUF_SPLICE_MOVE    = (1 << 3),
 324
 325         /**
 326          * Don't block on the pipe when copying data with splice
 327          *
 328          * Makes the operations on the pipe non-blocking (if the pipe
 329          * is full or empty).  See SPLICE_F_NONBLOCK in the splice(2)
 330          * man page.
 331          */
 332         FUSE_BUF_SPLICE_NONBLOCK= (1 << 4),
 333 };
 334
 335 /**
 336  * Single data buffer
 337  *
 338  * Generic data buffer for I/O, extended attributes, etc...  Data may
 339  * be supplied as a memory pointer or as a file descriptor
 340  */
 341 struct fuse_buf {
 342         /**
 343          * Size of data in bytes
 344          */
 345         size_t size;
 346
 347         /**
 348          * Buffer flags
 349          */
 350         enum fuse_buf_flags flags;
 351
 352         /**
 353          * Memory pointer
 354          *
 355          * Used unless FUSE_BUF_IS_FD flag is set.
 356          */
 357         void *mem;
 358
 359         /**
 360          * File descriptor
 361          *
 362          * Used if FUSE_BUF_IS_FD flag is set.
 363          */
 364         int fd;
 365
 366         /**
 367          * File position
 368          *
 369          * Used if FUSE_BUF_FD_SEEK flag is set.
 370          */
 371         off_t pos;
 372 };
 373
 374 /**
 375  * Data buffer vector
 376  *
 377  * An array of data buffers, each containing a memory pointer or a
 378  * file descriptor.
 379  *
 380  * Allocate dynamically to add more than one buffer.
 381  */
 382 struct fuse_bufvec {
 383         /**
 384          * Number of buffers in the array
 385          */
 386         size_t count;
 387
 388         /**
 389          * Index of current buffer within the array
 390          */
 391         size_t idx;
 392
 393         /**
 394          * Current offset within the current buffer
 395          */
 396         size_t off;
 397
 398         /**
 399          * Array of buffers
 400          */
 401         struct fuse_buf buf[1];
 402 };
 403
 404 /* Initialize bufvec with a single buffer of given size */
 405 #define FUSE_BUFVEC_INIT(size__)                                \
 406         ((struct fuse_bufvec) {                                 \
 407                 /* .count= */ 1,                                \
 408                 /* .idx =  */ 0,                                \
 409                 /* .off =  */ 0,                                \
 410                 /* .buf =  */ { /* [0] = */ {                   \
 411                         /* .size =  */ (size__),                \
 412                         /* .flags = */ (enum fuse_buf_flags) 0, \
 413                         /* .mem =   */ NULL,                    \
 414                         /* .fd =    */ -1,                      \
 415                         /* .pos =   */ 0,                       \
 416                 } }                                             \
 417         } )
 418
 419 /**
 420  * Get total size of data in a fuse buffer vector
 421  *
 422  * @param bufv buffer vector
 423  * @return size of data
 424  */
 425 size_t fuse_buf_size(const struct fuse_bufvec *bufv);
 426
 427 /**
 428  * Copy data from one buffer vector to another
 429  *
 430  * @param dst destination buffer vector
 431  * @param src source buffer vector
 432  * @param flags flags controlling the copy
 433  * @return actual number of bytes copied or -errno on error
 434  */
 435 ssize_t fuse_buf_copy(struct fuse_bufvec *dst, struct fuse_bufvec *src,
 436                       enum fuse_buf_copy_flags flags);
 437
 438 /* ----------------------------------------------------------- *
 439  * Signal handling                                             *
 440  * ----------------------------------------------------------- */
 441
 442 /**
 443  * Exit session on HUP, TERM and INT signals and ignore PIPE signal
 444  *
 445  * Stores session in a global variable.  May only be called once per
 446  * process until fuse_remove_signal_handlers() is called.
 447  *
 448  * @param se the session to exit
 449  * @return 0 on success, -1 on failure
 450  */
 451 int fuse_set_signal_handlers(struct fuse_session *se);
 452
 453 /**
 454  * Restore default signal handlers
 455  *
 456  * Resets global session.  After this fuse_set_signal_handlers() may
 457  * be called again.
 458  *
 459  * @param se the same session as given in fuse_set_signal_handlers()
 460  */
 461 void fuse_remove_signal_handlers(struct fuse_session *se);
 462
 463 /* ----------------------------------------------------------- *
 464  * Compatibility stuff                                         *
 465  * ----------------------------------------------------------- */
 466
 467 #if FUSE_USE_VERSION < 26
 468 #    ifdef __FreeBSD__
 469 #        if FUSE_USE_VERSION < 25
 470 #            error On FreeBSD API version 25 or greater must be used
 471 #        endif
 472 #    endif
 473 #    include "fuse_common_compat.h"
 474 #    undef FUSE_MINOR_VERSION
 475 #    undef fuse_main
 476 #    define fuse_unmount fuse_unmount_compat22
 477 #    if FUSE_USE_VERSION == 25
 478 #        define FUSE_MINOR_VERSION 5
 479 #        define fuse_mount fuse_mount_compat25
 480 #    elif FUSE_USE_VERSION == 24 || FUSE_USE_VERSION == 22
 481 #        define FUSE_MINOR_VERSION 4
 482 #        define fuse_mount fuse_mount_compat22
 483 #    elif FUSE_USE_VERSION == 21
 484 #        define FUSE_MINOR_VERSION 1
 485 #        define fuse_mount fuse_mount_compat22
 486 #    elif FUSE_USE_VERSION == 11
 487 #        warning Compatibility with API version 11 is deprecated
 488 #        undef FUSE_MAJOR_VERSION
 489 #        define FUSE_MAJOR_VERSION 1
 490 #        define FUSE_MINOR_VERSION 1
 491 #        define fuse_mount fuse_mount_compat1
 492 #    else
 493 #        error Compatibility with API version other than 21, 22, 24, 25 and 11 not supported
 494 #    endif
 495 #endif
 496
 497 #ifdef __cplusplus
 498 }
 499 #endif
 500
 501 #endif /* _FUSE_COMMON_H_ */