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 # if defined(__FreeBSD__) || defined(__HAIKU__) 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_ */ 506