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