include/fuse_common.h

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