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#ifndef _FUSE_H_ 10#define _FUSE_H_ 11 12/** @file 13 * 14 * This file defines the library interface of FUSE 15 */ 16 17#include "fuse_common.h" 18 19#include <fcntl.h> 20#include <time.h> 21#include <utime.h> 22#include <sys/types.h> 23#include <sys/stat.h> 24#include <sys/statvfs.h> 25 26#ifdef __cplusplus 27extern "C" { 28#endif 29 30/* ----------------------------------------------------------- * 31 * Basic FUSE API * 32 * ----------------------------------------------------------- */ 33 34/** Handle for a FUSE filesystem */ 35struct fuse; 36 37/** Structure containing a raw command */ 38struct fuse_cmd; 39 40/** Function to add an entry in a readdir() operation 41 * 42 * @param buf the buffer passed to the readdir() operation 43 * @param name the file name of the directory entry 44 * @param stat file attributes, can be NULL 45 * @param off offset of the next entry or zero 46 * @return 1 if buffer is full, zero otherwise 47 */ 48typedef int (*fuse_fill_dir_t) (void *buf, const char *name, 49 const struct stat *stbuf, off_t off); 50 51/** 52 * The file system operations: 53 * 54 * Most of these should work very similarly to the well known UNIX 55 * file system operations. A major exception is that instead of 56 * returning an error in 'errno', the operation should return the 57 * negated error value (-errno) directly. 58 * 59 * All methods are optional, but some are essential for a useful 60 * filesystem (e.g. getattr). Open, flush, release, fsync, opendir, 61 * releasedir, fsyncdir, access, create, ftruncate, fgetattr, lock, 62 * init and destroy are special purpose methods, without which a full 63 * featured filesystem can still be implemented. 64 * 65 * Almost all operations take a path which can be of any length. 66 * 67 * Changed in fuse 2.8.0 (regardless of API version) 68 * Previously, paths were limited to a length of PATH_MAX. 69 */ 70struct fuse_operations { 71 /** Get file attributes. 72 * 73 * Similar to stat(). The 'st_dev' and 'st_blksize' fields are 74 * ignored. The 'st_ino' field is ignored except if the 'use_ino' 75 * mount option is given. 76 */ 77 int (*getattr) (const char *, struct stat *); 78 79 /** Read the target of a symbolic link 80 * 81 * The buffer should be filled with a null terminated string. The 82 * buffer size argument includes the space for the terminating 83 * null character. If the linkname is too long to fit in the 84 * buffer, it should be truncated. The return value should be 0 85 * for success. 86 */ 87 int (*readlink) (const char *, char *, size_t); 88 89 /** Create a file node 90 * 91 * This is called for creation of all non-directory, non-symlink 92 * nodes. If the filesystem defines a create() method, then for 93 * regular files that will be called instead. 94 */ 95 int (*mknod) (const char *, mode_t, dev_t); 96 97 /** Create a directory 98 * 99 * Note that the mode argument may not have the type specification 100 * bits set, i.e. S_ISDIR(mode) can be false. To obtain the 101 * correct directory type bits use mode|S_IFDIR 102 * */ 103 int (*mkdir) (const char *, mode_t); 104 105 /** Remove a file */ 106 int (*unlink) (const char *); 107 108 /** Remove a directory */ 109 int (*rmdir) (const char *); 110 111 /** Create a symbolic link */ 112 int (*symlink) (const char *, const char *); 113 114 /** Rename a file */ 115 int (*rename) (const char *, const char *); 116 117 /** Create a hard link to a file */ 118 int (*link) (const char *, const char *); 119 120 /** Change the permission bits of a file */ 121 int (*chmod) (const char *, mode_t); 122 123 /** Change the owner and group of a file */ 124 int (*chown) (const char *, uid_t, gid_t); 125 126 /** Change the size of a file */ 127 int (*truncate) (const char *, off_t); 128 129 /** Change the access and/or modification times of a file 130 * 131 * Deprecated, use utimens() instead. 132 */ 133 int (*utime) (const char *, struct utimbuf *); 134 135 /** File open operation 136 * 137 * No creation (O_CREAT, O_EXCL) and by default also no 138 * truncation (O_TRUNC) flags will be passed to open(). If an 139 * application specifies O_TRUNC, fuse first calls truncate() 140 * and then open(). Only if 'atomic_o_trunc' has been 141 * specified and kernel version is 2.6.24 or later, O_TRUNC is 142 * passed on to open. 143 * 144 * Unless the 'default_permissions' mount option is given, 145 * open should check if the operation is permitted for the 146 * given flags. Optionally open may also return an arbitrary 147 * filehandle in the fuse_file_info structure, which will be 148 * passed to all file operations. 149 * 150 * Changed in version 2.2 151 */ 152 int (*open) (const char *, struct fuse_file_info *); 153 154 /** Read data from an open file 155 * 156 * Read should return exactly the number of bytes requested except 157 * on EOF or error, otherwise the rest of the data will be 158 * substituted with zeroes. An exception to this is when the 159 * 'direct_io' mount option is specified, in which case the return 160 * value of the read system call will reflect the return value of 161 * this operation. 162 * 163 * Changed in version 2.2 164 */ 165 int (*read) (const char *, char *, size_t, off_t, 166 struct fuse_file_info *); 167 168 /** Write data to an open file 169 * 170 * Write should return exactly the number of bytes requested 171 * except on error. An exception to this is when the 'direct_io' 172 * mount option is specified (see read operation). 173 * 174 * Changed in version 2.2 175 */ 176 int (*write) (const char *, const char *, size_t, off_t, 177 struct fuse_file_info *); 178 179 /** Get file system statistics 180 * 181 * The 'f_frsize', 'f_favail', 'f_fsid' and 'f_flag' fields are ignored 182 * 183 * Replaced 'struct statfs' parameter with 'struct statvfs' in 184 * version 2.5 185 */ 186 int (*statfs) (const char *, struct statvfs *); 187 188 /** Possibly flush cached data 189 * 190 * BIG NOTE: This is not equivalent to fsync(). It's not a 191 * request to sync dirty data. 192 * 193 * Flush is called on each close() of a file descriptor. So if a 194 * filesystem wants to return write errors in close() and the file 195 * has cached dirty data, this is a good place to write back data 196 * and return any errors. Since many applications ignore close() 197 * errors this is not always useful. 198 * 199 * NOTE: The flush() method may be called more than once for each 200 * open(). This happens if more than one file descriptor refers 201 * to an opened file due to dup(), dup2() or fork() calls. It is 202 * not possible to determine if a flush is final, so each flush 203 * should be treated equally. Multiple write-flush sequences are 204 * relatively rare, so this shouldn't be a problem. 205 * 206 * Filesystems shouldn't assume that flush will always be called 207 * after some writes, or that if will be called at all. 208 * 209 * Changed in version 2.2 210 */ 211 int (*flush) (const char *, struct fuse_file_info *); 212 213 /** Release an open file 214 * 215 * Release is called when there are no more references to an open 216 * file: all file descriptors are closed and all memory mappings 217 * are unmapped. 218 * 219 * For every open() call there will be exactly one release() call 220 * with the same flags and file descriptor. It is possible to 221 * have a file opened more than once, in which case only the last 222 * release will mean, that no more reads/writes will happen on the 223 * file. The return value of release is ignored. 224 * 225 * Changed in version 2.2 226 */ 227 int (*release) (const char *, struct fuse_file_info *); 228 229 /** Synchronize file contents 230 * 231 * If the datasync parameter is non-zero, then only the user data 232 * should be flushed, not the meta data. 233 * 234 * Changed in version 2.2 235 */ 236 int (*fsync) (const char *, int, struct fuse_file_info *); 237 238 /** Set extended attributes */ 239 int (*setxattr) (const char *, const char *, const char *, size_t, int); 240 241 /** Get extended attributes */ 242 int (*getxattr) (const char *, const char *, char *, size_t); 243 244 /** List extended attributes */ 245 int (*listxattr) (const char *, char *, size_t); 246 247 /** Remove extended attributes */ 248 int (*removexattr) (const char *, const char *); 249 250 /** Open directory 251 * 252 * This method should check if the open operation is permitted for 253 * this directory 254 * 255 * Introduced in version 2.3 256 */ 257 int (*opendir) (const char *, struct fuse_file_info *); 258 259 /** Read directory 260 * 261 * The filesystem may choose between two modes of operation: 262 * 263 * 1) The readdir implementation ignores the offset parameter, and 264 * passes zero to the filler function's offset. The filler 265 * function will not return '1' (unless an error happens), so the 266 * whole directory is read in a single readdir operation. 267 * 268 * 2) The readdir implementation keeps track of the offsets of the 269 * directory entries. It uses the offset parameter and always 270 * passes non-zero offset to the filler function. When the buffer 271 * is full (or an error happens) the filler function will return 272 * '1'. 273 * 274 * Introduced in version 2.3 275 */ 276 int (*readdir) (const char *, void *, fuse_fill_dir_t, off_t, 277 struct fuse_file_info *); 278 279 /** Release directory 280 * 281 * Introduced in version 2.3 282 */ 283 int (*releasedir) (const char *, struct fuse_file_info *); 284 285 /** Synchronize directory contents 286 * 287 * If the datasync parameter is non-zero, then only the user data 288 * should be flushed, not the meta data 289 * 290 * Introduced in version 2.3 291 */ 292 int (*fsyncdir) (const char *, int, struct fuse_file_info *); 293 294 /** 295 * Initialize filesystem 296 * 297 * The return value will passed in the private_data field of 298 * fuse_context to all file operations and as a parameter to the 299 * destroy() method. 300 * 301 * Introduced in version 2.3 302 * Changed in version 2.6 303 */ 304 void *(*init) (struct fuse_conn_info *conn); 305 306 /** 307 * Clean up filesystem 308 * 309 * Called on filesystem exit. 310 * 311 * Introduced in version 2.3 312 */ 313 void (*destroy) (void *); 314 315 /** 316 * Check file access permissions 317 * 318 * This will be called for the access() system call. If the 319 * 'default_permissions' mount option is given, this method is not 320 * called. 321 * 322 * This method is not called under Linux kernel versions 2.4.x 323 * 324 * Introduced in version 2.5 325 */ 326 int (*access) (const char *, int); 327 328 /** 329 * Create and open a file 330 * 331 * If the file does not exist, first create it with the specified 332 * mode, and then open it. 333 * 334 * If this method is not implemented or under Linux kernel 335 * versions earlier than 2.6.15, the mknod() and open() methods 336 * will be called instead. 337 * 338 * Introduced in version 2.5 339 */ 340 int (*create) (const char *, mode_t, struct fuse_file_info *); 341 342 /** 343 * Change the size of an open file 344 * 345 * This method is called instead of the truncate() method if the 346 * truncation was invoked from an ftruncate() system call. 347 * 348 * If this method is not implemented or under Linux kernel 349 * versions earlier than 2.6.15, the truncate() method will be 350 * called instead. 351 * 352 * Introduced in version 2.5 353 */ 354 int (*ftruncate) (const char *, off_t, struct fuse_file_info *); 355 356 /** 357 * Get attributes from an open file 358 * 359 * This method is called instead of the getattr() method if the 360 * file information is available. 361 * 362 * Currently this is only called after the create() method if that 363 * is implemented (see above). Later it may be called for 364 * invocations of fstat() too. 365 * 366 * Introduced in version 2.5 367 */ 368 int (*fgetattr) (const char *, struct stat *, struct fuse_file_info *); 369 370 /** 371 * Perform POSIX file locking operation 372 * 373 * The cmd argument will be either F_GETLK, F_SETLK or F_SETLKW. 374 * 375 * For the meaning of fields in 'struct flock' see the man page 376 * for fcntl(2). The l_whence field will always be set to 377 * SEEK_SET. 378 * 379 * For checking lock ownership, the 'fuse_file_info->owner' 380 * argument must be used. 381 * 382 * For F_GETLK operation, the library will first check currently 383 * held locks, and if a conflicting lock is found it will return 384 * information without calling this method. This ensures, that 385 * for local locks the l_pid field is correctly filled in. The 386 * results may not be accurate in case of race conditions and in 387 * the presence of hard links, but it's unlikly that an 388 * application would rely on accurate GETLK results in these 389 * cases. If a conflicting lock is not found, this method will be 390 * called, and the filesystem may fill out l_pid by a meaningful 391 * value, or it may leave this field zero. 392 * 393 * For F_SETLK and F_SETLKW the l_pid field will be set to the pid 394 * of the process performing the locking operation. 395 * 396 * Note: if this method is not implemented, the kernel will still 397 * allow file locking to work locally. Hence it is only 398 * interesting for network filesystems and similar. 399 * 400 * Introduced in version 2.6 401 */ 402 int (*lock) (const char *, struct fuse_file_info *, int cmd, 403 struct flock *); 404 405 /** 406 * Change the access and modification times of a file with 407 * nanosecond resolution 408 * 409 * Introduced in version 2.6 410 */ 411 int (*utimens) (const char *, const struct timespec tv[2]); 412 413 /** 414 * Map block index within file to block index within device 415 * 416 * Note: This makes sense only for block device backed filesystems 417 * mounted with the 'blkdev' option 418 * 419 * Introduced in version 2.6 420 */ 421 int (*bmap) (const char *, size_t blocksize, uint64_t *idx); 422}; 423 424/** Extra context that may be needed by some filesystems 425 * 426 * The uid, gid and pid fields are not filled in case of a writepage 427 * operation. 428 */ 429struct fuse_context { 430 /** Pointer to the fuse object */ 431 struct fuse *fuse; 432 433 /** User ID of the calling process */ 434 uid_t uid; 435 436 /** Group ID of the calling process */ 437 gid_t gid; 438 439 /** Thread ID of the calling process */ 440 pid_t pid; 441 442 /** Private filesystem data */ 443 void *private_data; 444}; 445 446/* ----------------------------------------------------------- * 447 * More detailed API * 448 * ----------------------------------------------------------- */ 449 450/** 451 * Create a new FUSE filesystem. 452 * 453 * @param ch the communication channel 454 * @param args argument vector 455 * @param op the filesystem operations 456 * @param op_size the size of the fuse_operations structure 457 * @param user_data user data supplied in the context during the init() method 458 * @return the created FUSE handle 459 */ 460struct fuse *fuse_new(struct fuse_chan *ch, struct fuse_args *args, 461 const struct fuse_operations *op, size_t op_size, 462 void *user_data); 463 464/** 465 * Destroy the FUSE handle. 466 * 467 * The communication channel attached to the handle is also destroyed. 468 * 469 * NOTE: This function does not unmount the filesystem. If this is 470 * needed, call fuse_unmount() before calling this function. 471 * 472 * @param f the FUSE handle 473 */ 474void fuse_destroy(struct fuse *f); 475 476/** 477 * FUSE event loop. 478 * 479 * Requests from the kernel are processed, and the appropriate 480 * operations are called. 481 * 482 * @param f the FUSE handle 483 * @return 0 if no error occurred, -1 otherwise 484 */ 485int fuse_loop(struct fuse *f); 486 487/** 488 * Exit from event loop 489 * 490 * @param f the FUSE handle 491 */ 492void fuse_exit(struct fuse *f); 493 494/** 495 * Get the current context 496 * 497 * The context is only valid for the duration of a filesystem 498 * operation, and thus must not be stored and used later. 499 * 500 * @return the context 501 */ 502struct fuse_context *fuse_get_context(void); 503 504/** 505 * Check if a request has already been interrupted 506 * 507 * @param req request handle 508 * @return 1 if the request has been interrupted, 0 otherwise 509 */ 510int fuse_interrupted(void); 511 512/* 513 * Stacking API 514 */ 515 516/** 517 * Fuse filesystem object 518 * 519 * This is opaque object represents a filesystem layer 520 */ 521struct fuse_fs; 522 523/* 524 * These functions call the relevant filesystem operation, and return 525 * the result. 526 * 527 * If the operation is not defined, they return -ENOSYS, with the 528 * exception of fuse_fs_open, fuse_fs_release, fuse_fs_opendir, 529 * fuse_fs_releasedir and fuse_fs_statfs, which return 0. 530 */ 531 532int fuse_fs_getattr(struct fuse_fs *fs, const char *path, struct stat *buf); 533int fuse_fs_fgetattr(struct fuse_fs *fs, const char *path, struct stat *buf, 534 struct fuse_file_info *fi); 535int fuse_fs_rename(struct fuse_fs *fs, const char *oldpath, 536 const char *newpath); 537int fuse_fs_unlink(struct fuse_fs *fs, const char *path); 538int fuse_fs_rmdir(struct fuse_fs *fs, const char *path); 539int fuse_fs_symlink(struct fuse_fs *fs, const char *linkname, 540 const char *path); 541int fuse_fs_link(struct fuse_fs *fs, const char *oldpath, const char *newpath); 542int fuse_fs_release(struct fuse_fs *fs, const char *path, 543 struct fuse_file_info *fi); 544int fuse_fs_open(struct fuse_fs *fs, const char *path, 545 struct fuse_file_info *fi); 546int fuse_fs_read(struct fuse_fs *fs, const char *path, char *buf, size_t size, 547 off_t off, struct fuse_file_info *fi); 548int fuse_fs_write(struct fuse_fs *fs, const char *path, const char *buf, 549 size_t size, off_t off, struct fuse_file_info *fi); 550int fuse_fs_fsync(struct fuse_fs *fs, const char *path, int datasync, 551 struct fuse_file_info *fi); 552int fuse_fs_flush(struct fuse_fs *fs, const char *path, 553 struct fuse_file_info *fi); 554int fuse_fs_statfs(struct fuse_fs *fs, const char *path, struct statvfs *buf); 555int fuse_fs_opendir(struct fuse_fs *fs, const char *path, 556 struct fuse_file_info *fi); 557int fuse_fs_readdir(struct fuse_fs *fs, const char *path, void *buf, 558 fuse_fill_dir_t filler, off_t off, 559 struct fuse_file_info *fi); 560int fuse_fs_fsyncdir(struct fuse_fs *fs, const char *path, int datasync, 561 struct fuse_file_info *fi); 562int fuse_fs_releasedir(struct fuse_fs *fs, const char *path, 563 struct fuse_file_info *fi); 564int fuse_fs_create(struct fuse_fs *fs, const char *path, mode_t mode, 565 struct fuse_file_info *fi); 566int fuse_fs_lock(struct fuse_fs *fs, const char *path, 567 struct fuse_file_info *fi, int cmd, struct flock *lock); 568int fuse_fs_chmod(struct fuse_fs *fs, const char *path, mode_t mode); 569int fuse_fs_chown(struct fuse_fs *fs, const char *path, uid_t uid, gid_t gid); 570int fuse_fs_truncate(struct fuse_fs *fs, const char *path, off_t size); 571int fuse_fs_ftruncate(struct fuse_fs *fs, const char *path, off_t size, 572 struct fuse_file_info *fi); 573int fuse_fs_utimens(struct fuse_fs *fs, const char *path, 574 const struct timespec tv[2]); 575int fuse_fs_access(struct fuse_fs *fs, const char *path, int mask); 576int fuse_fs_readlink(struct fuse_fs *fs, const char *path, char *buf, 577 size_t len); 578int fuse_fs_mknod(struct fuse_fs *fs, const char *path, mode_t mode, 579 dev_t rdev); 580int fuse_fs_mkdir(struct fuse_fs *fs, const char *path, mode_t mode); 581int fuse_fs_setxattr(struct fuse_fs *fs, const char *path, const char *name, 582 const char *value, size_t size, int flags); 583int fuse_fs_getxattr(struct fuse_fs *fs, const char *path, const char *name, 584 char *value, size_t size); 585int fuse_fs_listxattr(struct fuse_fs *fs, const char *path, char *list, 586 size_t size); 587int fuse_fs_removexattr(struct fuse_fs *fs, const char *path, 588 const char *name); 589int fuse_fs_bmap(struct fuse_fs *fs, const char *path, size_t blocksize, 590 uint64_t *idx); 591void fuse_fs_init(struct fuse_fs *fs, struct fuse_conn_info *conn); 592void fuse_fs_destroy(struct fuse_fs *fs); 593 594/** 595 * Create a new fuse filesystem object 596 * 597 * This is usually called from the factory of a fuse module to create 598 * a new instance of a filesystem. 599 * 600 * @param op the filesystem operations 601 * @param op_size the size of the fuse_operations structure 602 * @param user_data user data supplied in the context during the init() method 603 * @return a new filesystem object 604 */ 605struct fuse_fs *fuse_fs_new(const struct fuse_operations *op, size_t op_size, 606 void *user_data); 607 608/* ----------------------------------------------------------- * 609 * Advanced API for event handling, don't worry about this... * 610 * ----------------------------------------------------------- */ 611 612/* NOTE: the following functions are deprecated, and will be removed 613 from the 3.0 API. Use the lowlevel session functions instead */ 614 615/** Get session from fuse object */ 616struct fuse_session *fuse_get_session(struct fuse *f); 617 618#ifdef __cplusplus 619} 620#endif 621 622#endif /* _FUSE_H_ */ 623