2 * FUSE: Filesystem in Userspace
3 * Copyright (C) 2001-2007 Miklos Szeredi <miklos@szeredi.hu>
5 * This program can be distributed under the terms of the GNU LGPLv2.
6 * See the file COPYING.LIB.
14 * This file defines the library interface of FUSE
16 * IMPORTANT: you should define FUSE_USE_VERSION before including this header.
19 #include "fuse_common.h"
23 #include <sys/statvfs.h>
24 #include <sys/types.h>
32 /** Handle for a FUSE filesystem */
36 * Readdir flags, passed to ->readdir()
38 enum fuse_readdir_flags
{
42 * The kernel wants to prefill the inode cache during readdir. The
43 * filesystem may honour this by filling in the attributes and setting
44 * FUSE_FILL_DIR_FLAGS for the filler function. The filesystem may also
45 * just ignore this flag completely.
47 FUSE_READDIR_PLUS
= (1 << 0),
50 enum fuse_fill_dir_flags
{
52 * "Plus" mode: all file attributes are valid
54 * The attributes are used by the kernel to prefill the inode cache
57 * It is okay to set FUSE_FILL_DIR_PLUS if FUSE_READDIR_PLUS is not set
60 FUSE_FILL_DIR_PLUS
= (1 << 1),
64 * Function to add an entry in a readdir() operation
66 * The *off* parameter can be any non-zero value that enables the
67 * filesystem to identify the current point in the directory
68 * stream. It does not need to be the actual physical position. A
69 * value of zero is reserved to indicate that seeking in directories
72 * @param buf the buffer passed to the readdir() operation
73 * @param name the file name of the directory entry
74 * @param stat file attributes, can be NULL
75 * @param off offset of the next entry or zero
76 * @param flags fill flags
77 * @return 1 if buffer is full, zero otherwise
79 typedef int (*fuse_fill_dir_t
)(void *buf
, const char *name
,
80 const struct stat
*stbuf
, off_t off
,
81 enum fuse_fill_dir_flags flags
);
83 * Configuration of the high-level API
85 * This structure is initialized from the arguments passed to
86 * fuse_new(), and then passed to the file system's init() handler
87 * which should ensure that the configuration is compatible with the
88 * file system implementation.
92 * If `set_gid` is non-zero, the st_gid attribute of each file
93 * is overwritten with the value of `gid`.
99 * If `set_uid` is non-zero, the st_uid attribute of each file
100 * is overwritten with the value of `uid`.
106 * If `set_mode` is non-zero, the any permissions bits set in
107 * `umask` are unset in the st_mode attribute of each file.
113 * The timeout in seconds for which name lookups will be
116 double entry_timeout
;
119 * The timeout in seconds for which a negative lookup will be
120 * cached. This means, that if file did not exist (lookup
121 * retuned ENOENT), the lookup will only be redone after the
122 * timeout, and the file/directory will be assumed to not
123 * exist until then. A value of zero means that negative
124 * lookups are not cached.
126 double negative_timeout
;
129 * The timeout in seconds for which file/directory attributes
130 * (as returned by e.g. the `getattr` handler) are cached.
135 * Allow requests to be interrupted
140 * Specify which signal number to send to the filesystem when
141 * a request is interrupted. The default is hardcoded to
147 * Normally, FUSE assigns inodes to paths only for as long as
148 * the kernel is aware of them. With this option inodes are
149 * instead remembered for at least this many seconds. This
150 * will require more memory, but may be necessary when using
151 * applications that make use of inode numbers.
153 * A number of -1 means that inodes will be remembered for the
154 * entire life-time of the file-system process.
159 * The default behavior is that if an open file is deleted,
160 * the file is renamed to a hidden file (.fuse_hiddenXXX), and
161 * only removed when the file is finally released. This
162 * relieves the filesystem implementation of having to deal
163 * with this problem. This option disables the hiding
164 * behavior, and files are removed immediately in an unlink
165 * operation (or in a rename operation which overwrites an
168 * It is recommended that you not use the hard_remove
169 * option. When hard_remove is set, the following libc
170 * functions fail on unlinked files (returning errno of
171 * ENOENT): read(2), write(2), fsync(2), close(2), f*xattr(2),
172 * ftruncate(2), fstat(2), fchmod(2), fchown(2)
177 * Honor the st_ino field in the functions getattr() and
178 * fill_dir(). This value is used to fill in the st_ino field
179 * in the stat(2), lstat(2), fstat(2) functions and the d_ino
180 * field in the readdir(2) function. The filesystem does not
181 * have to guarantee uniqueness, however some applications
182 * rely on this value being unique for the whole filesystem.
184 * Note that this does *not* affect the inode that libfuse
185 * and the kernel use internally (also called the "nodeid").
190 * If use_ino option is not given, still try to fill in the
191 * d_ino field in readdir(2). If the name was previously
192 * looked up, and is still in the cache, the inode number
193 * found there will be used. Otherwise it will be set to -1.
194 * If use_ino option is given, this option is ignored.
199 * This option disables the use of page cache (file content cache)
200 * in the kernel for this filesystem. This has several affects:
202 * 1. Each read(2) or write(2) system call will initiate one
203 * or more read or write operations, data will not be
204 * cached in the kernel.
206 * 2. The return value of the read() and write() system calls
207 * will correspond to the return values of the read and
208 * write operations. This is useful for example if the
209 * file size is not known in advance (before reading it).
211 * Internally, enabling this option causes fuse to set the
212 * `direct_io` field of `struct fuse_file_info` - overwriting
213 * any value that was put there by the file system.
218 * This option disables flushing the cache of the file
219 * contents on every open(2). This should only be enabled on
220 * filesystems where the file data is never changed
221 * externally (not through the mounted FUSE filesystem). Thus
222 * it is not suitable for network filesystems and other
223 * intermediate filesystems.
225 * NOTE: if this option is not specified (and neither
226 * direct_io) data is still cached after the open(2), so a
227 * read(2) system call will not always initiate a read
230 * Internally, enabling this option causes fuse to set the
231 * `keep_cache` field of `struct fuse_file_info` - overwriting
232 * any value that was put there by the file system.
237 * This option is an alternative to `kernel_cache`. Instead of
238 * unconditionally keeping cached data, the cached data is
239 * invalidated on open(2) if if the modification time or the
240 * size of the file has changed since it was last opened.
245 * The timeout in seconds for which file attributes are cached
246 * for the purpose of checking if auto_cache should flush the
249 int ac_attr_timeout_set
;
250 double ac_attr_timeout
;
253 * If this option is given the file-system handlers for the
254 * following operations will not receive path information:
255 * read, write, flush, release, fsync, readdir, releasedir,
256 * fsyncdir, lock, ioctl and poll.
258 * For the truncate, getattr, chmod, chown and utimens
259 * operations the path will be provided only if the struct
260 * fuse_file_info argument is NULL.
265 * The remaining options are used by libfuse internally and
266 * should not be touched.
275 * The file system operations:
277 * Most of these should work very similarly to the well known UNIX
278 * file system operations. A major exception is that instead of
279 * returning an error in 'errno', the operation should return the
280 * negated error value (-errno) directly.
282 * All methods are optional, but some are essential for a useful
283 * filesystem (e.g. getattr). Open, flush, release, fsync, opendir,
284 * releasedir, fsyncdir, access, create, truncate, lock, init and
285 * destroy are special purpose methods, without which a full featured
286 * filesystem can still be implemented.
288 * In general, all methods are expected to perform any necessary
289 * permission checking. However, a filesystem may delegate this task
290 * to the kernel by passing the `default_permissions` mount option to
291 * `fuse_new()`. In this case, methods will only be called if
292 * the kernel's permission check has succeeded.
294 * Almost all operations take a path which can be of any length.
296 struct fuse_operations
{
298 * Get file attributes.
300 * Similar to stat(). The 'st_dev' and 'st_blksize' fields are
301 * ignored. The 'st_ino' field is ignored except if the 'use_ino'
302 * mount option is given. In that case it is passed to userspace,
303 * but libfuse and the kernel will still assign a different
304 * inode for internal use (called the "nodeid").
306 * `fi` will always be NULL if the file is not currently open, but
307 * may also be NULL if the file is open.
309 int (*getattr
)(const char *, struct stat
*, struct fuse_file_info
*fi
);
312 * Read the target of a symbolic link
314 * The buffer should be filled with a null terminated string. The
315 * buffer size argument includes the space for the terminating
316 * null character. If the linkname is too long to fit in the
317 * buffer, it should be truncated. The return value should be 0
320 int (*readlink
)(const char *, char *, size_t);
325 * This is called for creation of all non-directory, non-symlink
326 * nodes. If the filesystem defines a create() method, then for
327 * regular files that will be called instead.
329 int (*mknod
)(const char *, mode_t
, dev_t
);
334 * Note that the mode argument may not have the type specification
335 * bits set, i.e. S_ISDIR(mode) can be false. To obtain the
336 * correct directory type bits use mode|S_IFDIR
338 int (*mkdir
)(const char *, mode_t
);
341 int (*unlink
)(const char *);
343 /** Remove a directory */
344 int (*rmdir
)(const char *);
346 /** Create a symbolic link */
347 int (*symlink
)(const char *, const char *);
352 * *flags* may be `RENAME_EXCHANGE` or `RENAME_NOREPLACE`. If
353 * RENAME_NOREPLACE is specified, the filesystem must not
354 * overwrite *newname* if it exists and return an error
355 * instead. If `RENAME_EXCHANGE` is specified, the filesystem
356 * must atomically exchange the two files, i.e. both must
357 * exist and neither may be deleted.
359 int (*rename
)(const char *, const char *, unsigned int flags
);
361 /** Create a hard link to a file */
362 int (*link
)(const char *, const char *);
365 * Change the permission bits of a file
367 * `fi` will always be NULL if the file is not currenlty open, but
368 * may also be NULL if the file is open.
370 int (*chmod
)(const char *, mode_t
, struct fuse_file_info
*fi
);
373 * Change the owner and group of a file
375 * `fi` will always be NULL if the file is not currenlty open, but
376 * may also be NULL if the file is open.
378 * Unless FUSE_CAP_HANDLE_KILLPRIV is disabled, this method is
379 * expected to reset the setuid and setgid bits.
381 int (*chown
)(const char *, uid_t
, gid_t
, struct fuse_file_info
*fi
);
384 * Change the size of a file
386 * `fi` will always be NULL if the file is not currenlty open, but
387 * may also be NULL if the file is open.
389 * Unless FUSE_CAP_HANDLE_KILLPRIV is disabled, this method is
390 * expected to reset the setuid and setgid bits.
392 int (*truncate
)(const char *, off_t
, struct fuse_file_info
*fi
);
397 * Open flags are available in fi->flags. The following rules
400 * - Creation (O_CREAT, O_EXCL, O_NOCTTY) flags will be
401 * filtered out / handled by the kernel.
403 * - Access modes (O_RDONLY, O_WRONLY, O_RDWR, O_EXEC, O_SEARCH)
404 * should be used by the filesystem to check if the operation is
405 * permitted. If the ``-o default_permissions`` mount option is
406 * given, this check is already done by the kernel before calling
407 * open() and may thus be omitted by the filesystem.
409 * - When writeback caching is enabled, the kernel may send
410 * read requests even for files opened with O_WRONLY. The
411 * filesystem should be prepared to handle this.
413 * - When writeback caching is disabled, the filesystem is
414 * expected to properly handle the O_APPEND flag and ensure
415 * that each write is appending to the end of the file.
417 * - When writeback caching is enabled, the kernel will
418 * handle O_APPEND. However, unless all changes to the file
419 * come through the kernel this will not work reliably. The
420 * filesystem should thus either ignore the O_APPEND flag
421 * (and let the kernel handle it), or return an error
422 * (indicating that reliably O_APPEND is not available).
424 * Filesystem may store an arbitrary file handle (pointer,
425 * index, etc) in fi->fh, and use this in other all other file
426 * operations (read, write, flush, release, fsync).
428 * Filesystem may also implement stateless file I/O and not store
429 * anything in fi->fh.
431 * There are also some flags (direct_io, keep_cache) which the
432 * filesystem may set in fi, to change the way the file is opened.
433 * See fuse_file_info structure in <fuse_common.h> for more details.
435 * If this request is answered with an error code of ENOSYS
436 * and FUSE_CAP_NO_OPEN_SUPPORT is set in
437 * `fuse_conn_info.capable`, this is treated as success and
438 * future calls to open will also succeed without being send
439 * to the filesystem process.
442 int (*open
)(const char *, struct fuse_file_info
*);
445 * Read data from an open file
447 * Read should return exactly the number of bytes requested except
448 * on EOF or error, otherwise the rest of the data will be
449 * substituted with zeroes. An exception to this is when the
450 * 'direct_io' mount option is specified, in which case the return
451 * value of the read system call will reflect the return value of
454 int (*read
)(const char *, char *, size_t, off_t
, struct fuse_file_info
*);
457 * Write data to an open file
459 * Write should return exactly the number of bytes requested
460 * except on error. An exception to this is when the 'direct_io'
461 * mount option is specified (see read operation).
463 * Unless FUSE_CAP_HANDLE_KILLPRIV is disabled, this method is
464 * expected to reset the setuid and setgid bits.
466 int (*write
)(const char *, const char *, size_t, off_t
,
467 struct fuse_file_info
*);
470 * Get file system statistics
472 * The 'f_favail', 'f_fsid' and 'f_flag' fields are ignored
474 int (*statfs
)(const char *, struct statvfs
*);
477 * Possibly flush cached data
479 * BIG NOTE: This is not equivalent to fsync(). It's not a
480 * request to sync dirty data.
482 * Flush is called on each close() of a file descriptor, as opposed to
483 * release which is called on the close of the last file descriptor for
484 * a file. Under Linux, errors returned by flush() will be passed to
485 * userspace as errors from close(), so flush() is a good place to write
486 * back any cached dirty data. However, many applications ignore errors
487 * on close(), and on non-Linux systems, close() may succeed even if flush()
488 * returns an error. For these reasons, filesystems should not assume
489 * that errors returned by flush will ever be noticed or even
492 * NOTE: The flush() method may be called more than once for each
493 * open(). This happens if more than one file descriptor refers to an
494 * open file handle, e.g. due to dup(), dup2() or fork() calls. It is
495 * not possible to determine if a flush is final, so each flush should
496 * be treated equally. Multiple write-flush sequences are relatively
497 * rare, so this shouldn't be a problem.
499 * Filesystems shouldn't assume that flush will be called at any
500 * particular point. It may be called more times than expected, or not
504 * http://pubs.opengroup.org/onlinepubs/9699919799/functions/close.html
506 int (*flush
)(const char *, struct fuse_file_info
*);
509 * Release an open file
511 * Release is called when there are no more references to an open
512 * file: all file descriptors are closed and all memory mappings
515 * For every open() call there will be exactly one release() call
516 * with the same flags and file handle. It is possible to
517 * have a file opened more than once, in which case only the last
518 * release will mean, that no more reads/writes will happen on the
519 * file. The return value of release is ignored.
521 int (*release
)(const char *, struct fuse_file_info
*);
524 * Synchronize file contents
526 * If the datasync parameter is non-zero, then only the user data
527 * should be flushed, not the meta data.
529 int (*fsync
)(const char *, int, struct fuse_file_info
*);
531 /** Set extended attributes */
532 int (*setxattr
)(const char *, const char *, const char *, size_t, int);
534 /** Get extended attributes */
535 int (*getxattr
)(const char *, const char *, char *, size_t);
537 /** List extended attributes */
538 int (*listxattr
)(const char *, char *, size_t);
540 /** Remove extended attributes */
541 int (*removexattr
)(const char *, const char *);
546 * Unless the 'default_permissions' mount option is given,
547 * this method should check if opendir is permitted for this
548 * directory. Optionally opendir may also return an arbitrary
549 * filehandle in the fuse_file_info structure, which will be
550 * passed to readdir, releasedir and fsyncdir.
552 int (*opendir
)(const char *, struct fuse_file_info
*);
557 * The filesystem may choose between two modes of operation:
559 * 1) The readdir implementation ignores the offset parameter, and
560 * passes zero to the filler function's offset. The filler
561 * function will not return '1' (unless an error happens), so the
562 * whole directory is read in a single readdir operation.
564 * 2) The readdir implementation keeps track of the offsets of the
565 * directory entries. It uses the offset parameter and always
566 * passes non-zero offset to the filler function. When the buffer
567 * is full (or an error happens) the filler function will return
570 int (*readdir
)(const char *, void *, fuse_fill_dir_t
, off_t
,
571 struct fuse_file_info
*, enum fuse_readdir_flags
);
576 int (*releasedir
)(const char *, struct fuse_file_info
*);
579 * Synchronize directory contents
581 * If the datasync parameter is non-zero, then only the user data
582 * should be flushed, not the meta data
584 int (*fsyncdir
)(const char *, int, struct fuse_file_info
*);
587 * Initialize filesystem
589 * The return value will passed in the `private_data` field of
590 * `struct fuse_context` to all file operations, and as a
591 * parameter to the destroy() method. It overrides the initial
592 * value provided to fuse_main() / fuse_new().
594 void *(*init
)(struct fuse_conn_info
*conn
, struct fuse_config
*cfg
);
597 * Clean up filesystem
599 * Called on filesystem exit.
601 void (*destroy
)(void *private_data
);
604 * Check file access permissions
606 * This will be called for the access() system call. If the
607 * 'default_permissions' mount option is given, this method is not
610 * This method is not called under Linux kernel versions 2.4.x
612 int (*access
)(const char *, int);
615 * Create and open a file
617 * If the file does not exist, first create it with the specified
618 * mode, and then open it.
620 * If this method is not implemented or under Linux kernel
621 * versions earlier than 2.6.15, the mknod() and open() methods
622 * will be called instead.
624 int (*create
)(const char *, mode_t
, struct fuse_file_info
*);
627 * Perform POSIX file locking operation
629 * The cmd argument will be either F_GETLK, F_SETLK or F_SETLKW.
631 * For the meaning of fields in 'struct flock' see the man page
632 * for fcntl(2). The l_whence field will always be set to
635 * For checking lock ownership, the 'fuse_file_info->owner'
636 * argument must be used.
638 * For F_GETLK operation, the library will first check currently
639 * held locks, and if a conflicting lock is found it will return
640 * information without calling this method. This ensures, that
641 * for local locks the l_pid field is correctly filled in. The
642 * results may not be accurate in case of race conditions and in
643 * the presence of hard links, but it's unlikely that an
644 * application would rely on accurate GETLK results in these
645 * cases. If a conflicting lock is not found, this method will be
646 * called, and the filesystem may fill out l_pid by a meaningful
647 * value, or it may leave this field zero.
649 * For F_SETLK and F_SETLKW the l_pid field will be set to the pid
650 * of the process performing the locking operation.
652 * Note: if this method is not implemented, the kernel will still
653 * allow file locking to work locally. Hence it is only
654 * interesting for network filesystems and similar.
656 int (*lock
)(const char *, struct fuse_file_info
*, int cmd
, struct flock
*);
659 * Change the access and modification times of a file with
660 * nanosecond resolution
662 * This supersedes the old utime() interface. New applications
665 * `fi` will always be NULL if the file is not currenlty open, but
666 * may also be NULL if the file is open.
668 * See the utimensat(2) man page for details.
670 int (*utimens
)(const char *, const struct timespec tv
[2],
671 struct fuse_file_info
*fi
);
674 * Map block index within file to block index within device
676 * Note: This makes sense only for block device backed filesystems
677 * mounted with the 'blkdev' option
679 int (*bmap
)(const char *, size_t blocksize
, uint64_t *idx
);
684 * flags will have FUSE_IOCTL_COMPAT set for 32bit ioctls in
685 * 64bit environment. The size and direction of data is
686 * determined by _IOC_*() decoding of cmd. For _IOC_NONE,
687 * data will be NULL, for _IOC_WRITE data is out area, for
688 * _IOC_READ in area and if both are set in/out area. In all
689 * non-NULL cases, the area is of _IOC_SIZE(cmd) bytes.
691 * If flags has FUSE_IOCTL_DIR then the fuse_file_info refers to a
692 * directory file handle.
694 * Note : the unsigned long request submitted by the application
695 * is truncated to 32 bits.
697 int (*ioctl
)(const char *, unsigned int cmd
, void *arg
,
698 struct fuse_file_info
*, unsigned int flags
, void *data
);
701 * Poll for IO readiness events
703 * Note: If ph is non-NULL, the client should notify
704 * when IO readiness events occur by calling
705 * fuse_notify_poll() with the specified ph.
707 * Regardless of the number of times poll with a non-NULL ph
708 * is received, single notification is enough to clear all.
709 * Notifying more times incurs overhead but doesn't harm
712 * The callee is responsible for destroying ph with
713 * fuse_pollhandle_destroy() when no longer in use.
715 int (*poll
)(const char *, struct fuse_file_info
*,
716 struct fuse_pollhandle
*ph
, unsigned *reventsp
);
719 * Write contents of buffer to an open file
721 * Similar to the write() method, but data is supplied in a
722 * generic buffer. Use fuse_buf_copy() to transfer data to
725 * Unless FUSE_CAP_HANDLE_KILLPRIV is disabled, this method is
726 * expected to reset the setuid and setgid bits.
728 int (*write_buf
)(const char *, struct fuse_bufvec
*buf
, off_t off
,
729 struct fuse_file_info
*);
732 * Store data from an open file in a buffer
734 * Similar to the read() method, but data is stored and
735 * returned in a generic buffer.
737 * No actual copying of data has to take place, the source
738 * file descriptor may simply be stored in the buffer for
739 * later data transfer.
741 * The buffer must be allocated dynamically and stored at the
742 * location pointed to by bufp. If the buffer contains memory
743 * regions, they too must be allocated using malloc(). The
744 * allocated memory will be freed by the caller.
746 int (*read_buf
)(const char *, struct fuse_bufvec
**bufp
, size_t size
,
747 off_t off
, struct fuse_file_info
*);
749 * Perform BSD file locking operation
751 * The op argument will be either LOCK_SH, LOCK_EX or LOCK_UN
753 * Nonblocking requests will be indicated by ORing LOCK_NB to
754 * the above operations
756 * For more information see the flock(2) manual page.
758 * Additionally fi->owner will be set to a value unique to
759 * this open file. This same value will be supplied to
760 * ->release() when the file is released.
762 * Note: if this method is not implemented, the kernel will still
763 * allow file locking to work locally. Hence it is only
764 * interesting for network filesystems and similar.
766 int (*flock
)(const char *, struct fuse_file_info
*, int op
);
769 * Allocates space for an open file
771 * This function ensures that required space is allocated for specified
772 * file. If this function returns success then any subsequent write
773 * request to specified range is guaranteed not to fail because of lack
774 * of space on the file system media.
776 int (*fallocate
)(const char *, int, off_t
, off_t
, struct fuse_file_info
*);
779 * Copy a range of data from one file to another
781 * Performs an optimized copy between two file descriptors without the
782 * additional cost of transferring data through the FUSE kernel module
783 * to user space (glibc) and then back into the FUSE filesystem again.
785 * In case this method is not implemented, glibc falls back to reading
786 * data from the source and writing to the destination. Effectively
787 * doing an inefficient copy of the data.
789 ssize_t (*copy_file_range
)(const char *path_in
,
790 struct fuse_file_info
*fi_in
, off_t offset_in
,
791 const char *path_out
,
792 struct fuse_file_info
*fi_out
, off_t offset_out
,
793 size_t size
, int flags
);
796 * Find next data or hole after the specified offset
798 off_t (*lseek
)(const char *, off_t off
, int whence
,
799 struct fuse_file_info
*);
803 * Extra context that may be needed by some filesystems
805 * The uid, gid and pid fields are not filled in case of a writepage
808 struct fuse_context
{
809 /** Pointer to the fuse object */
812 /** User ID of the calling process */
815 /** Group ID of the calling process */
818 /** Process ID of the calling thread */
821 /** Private filesystem data */
824 /** Umask of the calling process */
829 * Main function of FUSE.
831 * This is for the lazy. This is all that has to be called from the
834 * This function does the following:
835 * - parses command line options, and handles --help and
837 * - installs signal handlers for INT, HUP, TERM and PIPE
838 * - registers an exit handler to unmount the filesystem on program exit
839 * - creates a fuse handle
840 * - registers the operations
841 * - calls either the single-threaded or the multi-threaded event loop
843 * Most file systems will have to parse some file-system specific
844 * arguments before calling this function. It is recommended to do
845 * this with fuse_opt_parse() and a processing function that passes
846 * through any unknown options (this can also be achieved by just
847 * passing NULL as the processing function). That way, the remaining
848 * options can be passed directly to fuse_main().
850 * fuse_main() accepts all options that can be passed to
851 * fuse_parse_cmdline(), fuse_new(), or fuse_session_new().
853 * Option parsing skips argv[0], which is assumed to contain the
854 * program name. This element must always be present and is used to
855 * construct a basic ``usage: `` message for the --help
856 * output. argv[0] may also be set to the empty string. In this case
857 * the usage message is suppressed. This can be used by file systems
858 * to print their own usage line first. See hello.c for an example of
861 * Note: this is currently implemented as a macro.
863 * The following error codes may be returned from fuse_main():
864 * 1: Invalid option arguments
865 * 2: No mount point specified
866 * 3: FUSE setup failed
868 * 5: Failed to daemonize (detach from session)
869 * 6: Failed to set up signal handlers
870 * 7: An error occured during the life of the file system
872 * @param argc the argument counter passed to the main() function
873 * @param argv the argument vector passed to the main() function
874 * @param op the file system operation
875 * @param private_data Initial value for the `private_data`
876 * field of `struct fuse_context`. May be overridden by the
877 * `struct fuse_operations.init` handler.
878 * @return 0 on success, nonzero on failure
880 * Example usage, see hello.c
883 * int fuse_main(int argc, char *argv[], const struct fuse_operations *op,
884 * void *private_data);
886 #define fuse_main(argc, argv, op, private_data) \
887 fuse_main_real(argc, argv, op, sizeof(*(op)), private_data)
894 * Print available options (high- and low-level) to stdout. This is
895 * not an exhaustive list, but includes only those options that may be
896 * of interest to an end-user of a file system.
898 * The function looks at the argument vector only to determine if
899 * there are additional modules to be loaded (module=foo option),
900 * and attempts to call their help functions as well.
902 * @param args the argument vector.
904 void fuse_lib_help(struct fuse_args
*args
);
907 * Create a new FUSE filesystem.
909 * This function accepts most file-system independent mount options
910 * (like context, nodev, ro - see mount(8)), as well as the
911 * FUSE-specific mount options from mount.fuse(8).
913 * If the --help option is specified, the function writes a help text
914 * to stdout and returns NULL.
916 * Option parsing skips argv[0], which is assumed to contain the
917 * program name. This element must always be present and is used to
918 * construct a basic ``usage: `` message for the --help output. If
919 * argv[0] is set to the empty string, no usage message is included in
922 * If an unknown option is passed in, an error message is written to
923 * stderr and the function returns NULL.
925 * @param args argument vector
926 * @param op the filesystem operations
927 * @param op_size the size of the fuse_operations structure
928 * @param private_data Initial value for the `private_data`
929 * field of `struct fuse_context`. May be overridden by the
930 * `struct fuse_operations.init` handler.
931 * @return the created FUSE handle
933 #if FUSE_USE_VERSION == 30
934 struct fuse
*fuse_new_30(struct fuse_args
*args
,
935 const struct fuse_operations
*op
, size_t op_size
,
937 #define fuse_new(args, op, size, data) fuse_new_30(args, op, size, data)
939 struct fuse
*fuse_new(struct fuse_args
*args
, const struct fuse_operations
*op
,
940 size_t op_size
, void *private_data
);
944 * Mount a FUSE file system.
946 * @param mountpoint the mount point path
947 * @param f the FUSE handle
949 * @return 0 on success, -1 on failure.
951 int fuse_mount(struct fuse
*f
, const char *mountpoint
);
954 * Unmount a FUSE file system.
956 * See fuse_session_unmount() for additional information.
958 * @param f the FUSE handle
960 void fuse_unmount(struct fuse
*f
);
963 * Destroy the FUSE handle.
965 * NOTE: This function does not unmount the filesystem. If this is
966 * needed, call fuse_unmount() before calling this function.
968 * @param f the FUSE handle
970 void fuse_destroy(struct fuse
*f
);
975 * Requests from the kernel are processed, and the appropriate
976 * operations are called.
978 * For a description of the return value and the conditions when the
979 * event loop exits, refer to the documentation of
980 * fuse_session_loop().
982 * @param f the FUSE handle
983 * @return see fuse_session_loop()
985 * See also: fuse_loop_mt()
987 int fuse_loop(struct fuse
*f
);
990 * Flag session as terminated
992 * This function will cause any running event loops to exit on
993 * the next opportunity.
995 * @param f the FUSE handle
997 void fuse_exit(struct fuse
*f
);
1000 * Get the current context
1002 * The context is only valid for the duration of a filesystem
1003 * operation, and thus must not be stored and used later.
1005 * @return the context
1007 struct fuse_context
*fuse_get_context(void);
1010 * Get the current supplementary group IDs for the current request
1012 * Similar to the getgroups(2) system call, except the return value is
1013 * always the total number of group IDs, even if it is larger than the
1016 * The current fuse kernel module in linux (as of 2.6.30) doesn't pass
1017 * the group list to userspace, hence this function needs to parse
1018 * "/proc/$TID/task/$TID/status" to get the group IDs.
1020 * This feature may not be supported on all operating systems. In
1021 * such a case this function will return -ENOSYS.
1023 * @param size size of given array
1024 * @param list array of group IDs to be filled in
1025 * @return the total number of supplementary group IDs or -errno on failure
1027 int fuse_getgroups(int size
, gid_t list
[]);
1030 * Check if the current request has already been interrupted
1032 * @return 1 if the request has been interrupted, 0 otherwise
1034 int fuse_interrupted(void);
1037 * Invalidates cache for the given path.
1039 * This calls fuse_lowlevel_notify_inval_inode internally.
1041 * @return 0 on successful invalidation, negative error value otherwise.
1042 * This routine may return -ENOENT to indicate that there was
1043 * no entry to be invalidated, e.g., because the path has not
1044 * been seen before or has been forgotten; this should not be
1045 * considered to be an error.
1047 int fuse_invalidate_path(struct fuse
*f
, const char *path
);
1050 * The real main function
1052 * Do not call this directly, use fuse_main()
1054 int fuse_main_real(int argc
, char *argv
[], const struct fuse_operations
*op
,
1055 size_t op_size
, void *private_data
);
1058 * Start the cleanup thread when using option "remember".
1060 * This is done automatically by fuse_loop_mt()
1061 * @param fuse struct fuse pointer for fuse instance
1062 * @return 0 on success and -1 on error
1064 int fuse_start_cleanup_thread(struct fuse
*fuse
);
1067 * Stop the cleanup thread when using option "remember".
1069 * This is done automatically by fuse_loop_mt()
1070 * @param fuse struct fuse pointer for fuse instance
1072 void fuse_stop_cleanup_thread(struct fuse
*fuse
);
1075 * Iterate over cache removing stale entries
1076 * use in conjunction with "-oremember"
1078 * NOTE: This is already done for the standard sessions
1080 * @param fuse struct fuse pointer for fuse instance
1081 * @return the number of seconds until the next cleanup
1083 int fuse_clean_cache(struct fuse
*fuse
);
1090 * Fuse filesystem object
1092 * This is opaque object represents a filesystem layer
1097 * These functions call the relevant filesystem operation, and return
1100 * If the operation is not defined, they return -ENOSYS, with the
1101 * exception of fuse_fs_open, fuse_fs_release, fuse_fs_opendir,
1102 * fuse_fs_releasedir and fuse_fs_statfs, which return 0.
1105 int fuse_fs_getattr(struct fuse_fs
*fs
, const char *path
, struct stat
*buf
,
1106 struct fuse_file_info
*fi
);
1107 int fuse_fs_rename(struct fuse_fs
*fs
, const char *oldpath
, const char *newpath
,
1108 unsigned int flags
);
1109 int fuse_fs_unlink(struct fuse_fs
*fs
, const char *path
);
1110 int fuse_fs_rmdir(struct fuse_fs
*fs
, const char *path
);
1111 int fuse_fs_symlink(struct fuse_fs
*fs
, const char *linkname
, const char *path
);
1112 int fuse_fs_link(struct fuse_fs
*fs
, const char *oldpath
, const char *newpath
);
1113 int fuse_fs_release(struct fuse_fs
*fs
, const char *path
,
1114 struct fuse_file_info
*fi
);
1115 int fuse_fs_open(struct fuse_fs
*fs
, const char *path
,
1116 struct fuse_file_info
*fi
);
1117 int fuse_fs_read(struct fuse_fs
*fs
, const char *path
, char *buf
, size_t size
,
1118 off_t off
, struct fuse_file_info
*fi
);
1119 int fuse_fs_read_buf(struct fuse_fs
*fs
, const char *path
,
1120 struct fuse_bufvec
**bufp
, size_t size
, off_t off
,
1121 struct fuse_file_info
*fi
);
1122 int fuse_fs_write(struct fuse_fs
*fs
, const char *path
, const char *buf
,
1123 size_t size
, off_t off
, struct fuse_file_info
*fi
);
1124 int fuse_fs_write_buf(struct fuse_fs
*fs
, const char *path
,
1125 struct fuse_bufvec
*buf
, off_t off
,
1126 struct fuse_file_info
*fi
);
1127 int fuse_fs_fsync(struct fuse_fs
*fs
, const char *path
, int datasync
,
1128 struct fuse_file_info
*fi
);
1129 int fuse_fs_flush(struct fuse_fs
*fs
, const char *path
,
1130 struct fuse_file_info
*fi
);
1131 int fuse_fs_statfs(struct fuse_fs
*fs
, const char *path
, struct statvfs
*buf
);
1132 int fuse_fs_opendir(struct fuse_fs
*fs
, const char *path
,
1133 struct fuse_file_info
*fi
);
1134 int fuse_fs_readdir(struct fuse_fs
*fs
, const char *path
, void *buf
,
1135 fuse_fill_dir_t filler
, off_t off
,
1136 struct fuse_file_info
*fi
, enum fuse_readdir_flags flags
);
1137 int fuse_fs_fsyncdir(struct fuse_fs
*fs
, const char *path
, int datasync
,
1138 struct fuse_file_info
*fi
);
1139 int fuse_fs_releasedir(struct fuse_fs
*fs
, const char *path
,
1140 struct fuse_file_info
*fi
);
1141 int fuse_fs_create(struct fuse_fs
*fs
, const char *path
, mode_t mode
,
1142 struct fuse_file_info
*fi
);
1143 int fuse_fs_lock(struct fuse_fs
*fs
, const char *path
,
1144 struct fuse_file_info
*fi
, int cmd
, struct flock
*lock
);
1145 int fuse_fs_flock(struct fuse_fs
*fs
, const char *path
,
1146 struct fuse_file_info
*fi
, int op
);
1147 int fuse_fs_chmod(struct fuse_fs
*fs
, const char *path
, mode_t mode
,
1148 struct fuse_file_info
*fi
);
1149 int fuse_fs_chown(struct fuse_fs
*fs
, const char *path
, uid_t uid
, gid_t gid
,
1150 struct fuse_file_info
*fi
);
1151 int fuse_fs_truncate(struct fuse_fs
*fs
, const char *path
, off_t size
,
1152 struct fuse_file_info
*fi
);
1153 int fuse_fs_utimens(struct fuse_fs
*fs
, const char *path
,
1154 const struct timespec tv
[2], struct fuse_file_info
*fi
);
1155 int fuse_fs_access(struct fuse_fs
*fs
, const char *path
, int mask
);
1156 int fuse_fs_readlink(struct fuse_fs
*fs
, const char *path
, char *buf
,
1158 int fuse_fs_mknod(struct fuse_fs
*fs
, const char *path
, mode_t mode
,
1160 int fuse_fs_mkdir(struct fuse_fs
*fs
, const char *path
, mode_t mode
);
1161 int fuse_fs_setxattr(struct fuse_fs
*fs
, const char *path
, const char *name
,
1162 const char *value
, size_t size
, int flags
);
1163 int fuse_fs_getxattr(struct fuse_fs
*fs
, const char *path
, const char *name
,
1164 char *value
, size_t size
);
1165 int fuse_fs_listxattr(struct fuse_fs
*fs
, const char *path
, char *list
,
1167 int fuse_fs_removexattr(struct fuse_fs
*fs
, const char *path
, const char *name
);
1168 int fuse_fs_bmap(struct fuse_fs
*fs
, const char *path
, size_t blocksize
,
1170 int fuse_fs_ioctl(struct fuse_fs
*fs
, const char *path
, unsigned int cmd
,
1171 void *arg
, struct fuse_file_info
*fi
, unsigned int flags
,
1173 int fuse_fs_poll(struct fuse_fs
*fs
, const char *path
,
1174 struct fuse_file_info
*fi
, struct fuse_pollhandle
*ph
,
1175 unsigned *reventsp
);
1176 int fuse_fs_fallocate(struct fuse_fs
*fs
, const char *path
, int mode
,
1177 off_t offset
, off_t length
, struct fuse_file_info
*fi
);
1178 ssize_t
fuse_fs_copy_file_range(struct fuse_fs
*fs
, const char *path_in
,
1179 struct fuse_file_info
*fi_in
, off_t off_in
,
1180 const char *path_out
,
1181 struct fuse_file_info
*fi_out
, off_t off_out
,
1182 size_t len
, int flags
);
1183 off_t
fuse_fs_lseek(struct fuse_fs
*fs
, const char *path
, off_t off
, int whence
,
1184 struct fuse_file_info
*fi
);
1185 void fuse_fs_init(struct fuse_fs
*fs
, struct fuse_conn_info
*conn
,
1186 struct fuse_config
*cfg
);
1187 void fuse_fs_destroy(struct fuse_fs
*fs
);
1189 int fuse_notify_poll(struct fuse_pollhandle
*ph
);
1192 * Create a new fuse filesystem object
1194 * This is usually called from the factory of a fuse module to create
1195 * a new instance of a filesystem.
1197 * @param op the filesystem operations
1198 * @param op_size the size of the fuse_operations structure
1199 * @param private_data Initial value for the `private_data`
1200 * field of `struct fuse_context`. May be overridden by the
1201 * `struct fuse_operations.init` handler.
1202 * @return a new filesystem object
1204 struct fuse_fs
*fuse_fs_new(const struct fuse_operations
*op
, size_t op_size
,
1205 void *private_data
);
1208 * Factory for creating filesystem objects
1210 * The function may use and remove options from 'args' that belong
1213 * For now the 'fs' vector always contains exactly one filesystem.
1214 * This is the filesystem which will be below the newly created
1215 * filesystem in the stack.
1217 * @param args the command line arguments
1218 * @param fs NULL terminated filesystem object vector
1219 * @return the new filesystem object
1221 typedef struct fuse_fs
*(*fuse_module_factory_t
)(struct fuse_args
*args
,
1222 struct fuse_fs
*fs
[]);
1224 * Register filesystem module
1226 * If the "-omodules=*name*_:..." option is present, filesystem
1227 * objects are created and pushed onto the stack with the *factory_*
1230 * @param name_ the name of this filesystem module
1231 * @param factory_ the factory function for this filesystem module
1233 #define FUSE_REGISTER_MODULE(name_, factory_) \
1234 fuse_module_factory_t fuse_module_##name_##_factory = factory_
1236 /** Get session from fuse object */
1237 struct fuse_session
*fuse_get_session(struct fuse
*f
);
1240 * Open a FUSE file descriptor and set up the mount for the given
1241 * mountpoint and flags.
1243 * @param mountpoint reference to the mount in the file system
1244 * @param options mount options
1245 * @return the FUSE file descriptor or -1 upon error
1247 int fuse_open_channel(const char *mountpoint
, const char *options
);
1249 #endif /* FUSE_H_ */