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