libfuse
Data Structures | Macros | Typedefs | Enumerations | Functions
fuse.h File Reference
#include "fuse_common.h"
#include <fcntl.h>
#include <time.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <sys/statvfs.h>
#include <sys/uio.h>

Go to the source code of this file.

Data Structures

struct  fuse_config
 
struct  fuse_operations
 
struct  fuse_context
 

Macros

#define fuse_main(argc, argv, op, private_data)   fuse_main_real(argc, argv, op, sizeof(*(op)), private_data)
 
#define FUSE_REGISTER_MODULE(name_, factory_)   fuse_module_factory_t fuse_module_ ## name_ ## _factory = factory_
 

Typedefs

typedef int(* fuse_fill_dir_t) (void *buf, const char *name, const struct stat *stbuf, off_t off, enum fuse_fill_dir_flags flags)
 
typedef struct fuse_fs *(* fuse_module_factory_t) (struct fuse_args *args, struct fuse_fs *fs[])
 

Enumerations

enum  fuse_readdir_flags { FUSE_READDIR_PLUS = (1 << 0), FUSE_READDIR_PLUS = (1 << 0), FUSE_READDIR_PLUS = (1 << 0), FUSE_READDIR_PLUS = (1 << 0) }
 
enum  fuse_fill_dir_flags { FUSE_FILL_DIR_PLUS = (1 << 1), FUSE_FILL_DIR_PLUS = (1 << 1), FUSE_FILL_DIR_PLUS = (1 << 1), FUSE_FILL_DIR_PLUS = (1 << 1) }
 

Functions

void fuse_lib_help (struct fuse_args *args)
 
struct fuse * fuse_new (struct fuse_args *args, const struct fuse_operations *op, size_t op_size, void *private_data)
 
int fuse_mount (struct fuse *f, const char *mountpoint)
 
void fuse_unmount (struct fuse *f)
 
void fuse_destroy (struct fuse *f)
 
int fuse_loop (struct fuse *f)
 
void fuse_exit (struct fuse *f)
 
int fuse_loop_mt (struct fuse *f, struct fuse_loop_config *config)
 
struct fuse_contextfuse_get_context (void)
 
int fuse_getgroups (int size, gid_t list[])
 
int fuse_interrupted (void)
 
int fuse_invalidate_path (struct fuse *f, const char *path)
 
int fuse_main_real (int argc, char *argv[], const struct fuse_operations *op, size_t op_size, void *private_data)
 
int fuse_start_cleanup_thread (struct fuse *fuse)
 
void fuse_stop_cleanup_thread (struct fuse *fuse)
 
int fuse_clean_cache (struct fuse *fuse)
 
struct fuse_fs * fuse_fs_new (const struct fuse_operations *op, size_t op_size, void *private_data)
 
struct fuse_session * fuse_get_session (struct fuse *f)
 
int fuse_open_channel (const char *mountpoint, const char *options)
 

Detailed Description

This file defines the library interface of FUSE

IMPORTANT: you should define FUSE_USE_VERSION before including this header.

Definition in file fuse.h.

Macro Definition Documentation

◆ fuse_main

#define fuse_main (   argc,
  argv,
  op,
  private_data 
)    fuse_main_real(argc, argv, op, sizeof(*(op)), private_data)

Main function of FUSE.

This is for the lazy. This is all that has to be called from the main() function.

This function does the following:

  • parses command line options, and handles –help and –version
  • installs signal handlers for INT, HUP, TERM and PIPE
  • registers an exit handler to unmount the filesystem on program exit
  • creates a fuse handle
  • registers the operations
  • calls either the single-threaded or the multi-threaded event loop

Most file systems will have to parse some file-system specific arguments before calling this function. It is recommended to do this with fuse_opt_parse() and a processing function that passes through any unknown options (this can also be achieved by just passing NULL as the processing function). That way, the remaining options can be passed directly to fuse_main().

fuse_main() accepts all options that can be passed to fuse_parse_cmdline(), fuse_new(), or fuse_session_new().

Option parsing skips argv[0], which is assumed to contain the program name. This element must always be present and is used to construct a basic usage: message for the –help output. argv[0] may also be set to the empty string. In this case the usage message is suppressed. This can be used by file systems to print their own usage line first. See hello.c for an example of how to do this.

Note: this is currently implemented as a macro.

The following error codes may be returned from fuse_main(): 1: Invalid option arguments 2: No mount point specified 3: FUSE setup failed 4: Mounting failed 5: Failed to daemonize (detach from session) 6: Failed to set up signal handlers 7: An error occured during the life of the file system

Parameters
argcthe argument counter passed to the main() function
argvthe argument vector passed to the main() function
opthe file system operation
private_dataInitial value for the private_data field of struct fuse_context. May be overridden by the struct fuse_operations.init handler.
Returns
0 on success, nonzero on failure

Example usage, see hello.c

Definition at line 875 of file fuse.h.

◆ FUSE_REGISTER_MODULE

#define FUSE_REGISTER_MODULE (   name_,
  factory_ 
)    fuse_module_factory_t fuse_module_ ## name_ ## _factory = factory_

Register filesystem module

If the "-omodules=*name*_:..." option is present, filesystem objects are created and pushed onto the stack with the factory_ function.

Parameters
name_the name of this filesystem module
factory_the factory function for this filesystem module

Definition at line 1267 of file fuse.h.

Typedef Documentation

◆ fuse_fill_dir_t

typedef int(* fuse_fill_dir_t) (void *buf, const char *name, const struct stat *stbuf, off_t off, enum fuse_fill_dir_flags flags)

Function to add an entry in a readdir() operation

The off parameter can be any non-zero value that enables the filesystem to identify the current point in the directory stream. It does not need to be the actual physical position. A value of zero is reserved to indicate that seeking in directories is not supported.

Parameters
bufthe buffer passed to the readdir() operation
namethe file name of the directory entry
statfile attributes, can be NULL
offoffset of the next entry or zero
flagsfill flags
Returns
1 if buffer is full, zero otherwise

Definition at line 82 of file fuse.h.

◆ fuse_module_factory_t

typedef struct fuse_fs*(* fuse_module_factory_t) (struct fuse_args *args, struct fuse_fs *fs[])

Factory for creating filesystem objects

The function may use and remove options from 'args' that belong to this module.

For now the 'fs' vector always contains exactly one filesystem. This is the filesystem which will be below the newly created filesystem in the stack.

Parameters
argsthe command line arguments
fsNULL terminated filesystem object vector
Returns
the new filesystem object

Definition at line 1255 of file fuse.h.

Enumeration Type Documentation

◆ fuse_fill_dir_flags

Enumerator
FUSE_FILL_DIR_PLUS 

"Plus" mode: all file attributes are valid

The attributes are used by the kernel to prefill the inode cache during a readdir.

It is okay to set FUSE_FILL_DIR_PLUS if FUSE_READDIR_PLUS is not set and vice versa.

FUSE_FILL_DIR_PLUS 

"Plus" mode: all file attributes are valid

The attributes are used by the kernel to prefill the inode cache during a readdir.

It is okay to set FUSE_FILL_DIR_PLUS if FUSE_READDIR_PLUS is not set and vice versa.

FUSE_FILL_DIR_PLUS 

"Plus" mode: all file attributes are valid

The attributes are used by the kernel to prefill the inode cache during a readdir.

It is okay to set FUSE_FILL_DIR_PLUS if FUSE_READDIR_PLUS is not set and vice versa.

FUSE_FILL_DIR_PLUS 

"Plus" mode: all file attributes are valid

The attributes are used by the kernel to prefill the inode cache during a readdir.

It is okay to set FUSE_FILL_DIR_PLUS if FUSE_READDIR_PLUS is not set and vice versa.

Definition at line 54 of file fuse.h.

◆ fuse_readdir_flags

Readdir flags, passed to ->readdir()

Enumerator
FUSE_READDIR_PLUS 

"Plus" mode.

The kernel wants to prefill the inode cache during readdir. The filesystem may honour this by filling in the attributes and setting FUSE_FILL_DIR_FLAGS for the filler function. The filesystem may also just ignore this flag completely.

FUSE_READDIR_PLUS 

"Plus" mode.

The kernel wants to prefill the inode cache during readdir. The filesystem may honour this by filling in the attributes and setting FUSE_FILL_DIR_FLAGS for the filler function. The filesystem may also just ignore this flag completely.

FUSE_READDIR_PLUS 

"Plus" mode.

The kernel wants to prefill the inode cache during readdir. The filesystem may honour this by filling in the attributes and setting FUSE_FILL_DIR_FLAGS for the filler function. The filesystem may also just ignore this flag completely.

FUSE_READDIR_PLUS 

"Plus" mode.

The kernel wants to prefill the inode cache during readdir. The filesystem may honour this by filling in the attributes and setting FUSE_FILL_DIR_FLAGS for the filler function. The filesystem may also just ignore this flag completely.

Definition at line 42 of file fuse.h.

Function Documentation

◆ fuse_clean_cache()

int fuse_clean_cache ( struct fuse *  fuse)

Iterate over cache removing stale entries use in conjunction with "-oremember"

NOTE: This is already done for the standard sessions

Parameters
fusestruct fuse pointer for fuse instance
Returns
the number of seconds until the next cleanup

Definition at line 4417 of file fuse.c.

◆ fuse_destroy()

void fuse_destroy ( struct fuse *  f)

Destroy the FUSE handle.

NOTE: This function does not unmount the filesystem. If this is needed, call fuse_unmount() before calling this function.

Parameters
fthe FUSE handle

Definition at line 5053 of file fuse.c.

◆ fuse_exit()

void fuse_exit ( struct fuse *  f)

Flag session as terminated

This function will cause any running event loops to exit on the next opportunity.

Parameters
fthe FUSE handle

Definition at line 4597 of file fuse.c.

◆ fuse_fs_new()

struct fuse_fs* fuse_fs_new ( const struct fuse_operations op,
size_t  op_size,
void *  private_data 
)

Create a new fuse filesystem object

This is usually called from the factory of a fuse module to create a new instance of a filesystem.

Parameters
opthe filesystem operations
op_sizethe size of the fuse_operations structure
private_dataInitial value for the private_data field of struct fuse_context. May be overridden by the struct fuse_operations.init handler.
Returns
a new filesystem object

Definition at line 4806 of file fuse.c.

◆ fuse_get_context()

struct fuse_context* fuse_get_context ( void  )

Get the current context

The context is only valid for the duration of a filesystem operation, and thus must not be stored and used later.

Returns
the context

Definition at line 4602 of file fuse.c.

◆ fuse_get_session()

struct fuse_session* fuse_get_session ( struct fuse *  f)

Get session from fuse object

Definition at line 4504 of file fuse.c.

◆ fuse_getgroups()

int fuse_getgroups ( int  size,
gid_t  list[] 
)

Get the current supplementary group IDs for the current request

Similar to the getgroups(2) system call, except the return value is always the total number of group IDs, even if it is larger than the specified size.

The current fuse kernel module in linux (as of 2.6.30) doesn't pass the group list to userspace, hence this function needs to parse "/proc/$TID/task/$TID/status" to get the group IDs.

This feature may not be supported on all operating systems. In such a case this function will return -ENOSYS.

Parameters
sizesize of given array
listarray of group IDs to be filled in
Returns
the total number of supplementary group IDs or -errno on failure

Definition at line 4612 of file fuse.c.

◆ fuse_interrupted()

int fuse_interrupted ( void  )

Check if the current request has already been interrupted

Returns
1 if the request has been interrupted, 0 otherwise

Definition at line 4621 of file fuse.c.

◆ fuse_invalidate_path()

int fuse_invalidate_path ( struct fuse *  f,
const char *  path 
)

Invalidates cache for the given path.

This calls fuse_lowlevel_notify_inval_inode internally.

Returns
0 on successful invalidation, negative error value otherwise. This routine may return -ENOENT to indicate that there was no entry to be invalidated, e.g., because the path has not been seen before or has been forgotten; this should not be considered to be an error.

Definition at line 4631 of file fuse.c.

◆ fuse_lib_help()

void fuse_lib_help ( struct fuse_args args)

Print available options (high- and low-level) to stdout. This is not an exhaustive list, but includes only those options that may be of interest to an end-user of a file system.

The function looks at the argument vector only to determine if there are additional modules to be loaded (module=foo option), and attempts to call their help functions as well.

Parameters
argsthe argument vector.

Definition at line 4696 of file fuse.c.

◆ fuse_loop()

int fuse_loop ( struct fuse *  f)

FUSE event loop.

Requests from the kernel are processed, and the appropriate operations are called.

For a description of the return value and the conditions when the event loop exits, refer to the documentation of fuse_session_loop().

Parameters
fthe FUSE handle
Returns
see fuse_session_loop()

See also: fuse_loop_mt()

Definition at line 4561 of file fuse.c.

◆ fuse_loop_mt()

int fuse_loop_mt ( struct fuse *  f,
struct fuse_loop_config config 
)

FUSE event loop with multiple threads

Requests from the kernel are processed, and the appropriate operations are called. Request are processed in parallel by distributing them between multiple threads.

For a description of the return value and the conditions when the event loop exits, refer to the documentation of fuse_session_loop().

Note: using fuse_loop() instead of fuse_loop_mt() means you are running in single-threaded mode, and that you will not have to worry about reentrancy, though you will have to worry about recursive lookups. In single-threaded mode, FUSE will wait for one callback to return before calling another.

Enabling multiple threads, by using fuse_loop_mt(), will cause FUSE to make multiple simultaneous calls into the various callback functions given by your fuse_operations record.

If you are using multiple threads, you can enjoy all the parallel execution and interactive response benefits of threads, and you get to enjoy all the benefits of race conditions and locking bugs, too. Ensure that any code used in the callback function of fuse_operations is also thread-safe.

Parameters
fthe FUSE handle
configloop configuration
Returns
see fuse_session_loop()

See also: fuse_loop()

◆ fuse_main_real()

int fuse_main_real ( int  argc,
char *  argv[],
const struct fuse_operations op,
size_t  op_size,
void *  private_data 
)

The real main function

Do not call this directly, use fuse_main()

Definition at line 279 of file helper.c.

◆ fuse_mount()

int fuse_mount ( struct fuse *  f,
const char *  mountpoint 
)

Mount a FUSE file system.

Parameters
mountpointthe mount point path
fthe FUSE handle
Returns
0 on success, -1 on failure.

Definition at line 5103 of file fuse.c.

◆ fuse_new()

struct fuse* fuse_new ( struct fuse_args args,
const struct fuse_operations op,
size_t  op_size,
void *  private_data 
)

Create a new FUSE filesystem.

This function accepts most file-system independent mount options (like context, nodev, ro - see mount(8)), as well as the FUSE-specific mount options from mount.fuse(8).

If the –help option is specified, the function writes a help text to stdout and returns NULL.

Option parsing skips argv[0], which is assumed to contain the program name. This element must always be present and is used to construct a basic usage: message for the –help output. If argv[0] is set to the empty string, no usage message is included in the –help output.

If an unknown option is passed in, an error message is written to stderr and the function returns NULL.

Parameters
argsargument vector
opthe filesystem operations
op_sizethe size of the fuse_operations structure
private_dataInitial value for the private_data field of struct fuse_context. May be overridden by the struct fuse_operations.init handler.
Returns
the created FUSE handle

◆ fuse_open_channel()

int fuse_open_channel ( const char *  mountpoint,
const char *  options 
)

Open a FUSE file descriptor and set up the mount for the given mountpoint and flags.

Parameters
mountpointreference to the mount in the file system
optionsmount options
Returns
the FUSE file descriptor or -1 upon error

Definition at line 424 of file helper.c.

◆ fuse_start_cleanup_thread()

int fuse_start_cleanup_thread ( struct fuse *  fuse)

Start the cleanup thread when using option "remember".

This is done automatically by fuse_loop_mt()

Parameters
fusestruct fuse pointer for fuse instance
Returns
0 on success and -1 on error

Definition at line 4854 of file fuse.c.

◆ fuse_stop_cleanup_thread()

void fuse_stop_cleanup_thread ( struct fuse *  fuse)

Stop the cleanup thread when using option "remember".

This is done automatically by fuse_loop_mt()

Parameters
fusestruct fuse pointer for fuse instance

Definition at line 4862 of file fuse.c.

◆ fuse_unmount()

void fuse_unmount ( struct fuse *  f)

Unmount a FUSE file system.

See fuse_session_unmount() for additional information.

Parameters
fthe FUSE handle

Definition at line 5108 of file fuse.c.