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>

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) }
 
enum  fuse_fill_dir_flags { 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, int clone_fd)
 
struct fuse_contextfuse_get_context (void)
 
int fuse_getgroups (int size, gid_t list[])
 
int fuse_interrupted (void)
 
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)
 

Detailed Description

This file defines the library interface of FUSE

IMPORTANT: you should define FUSE_USE_VERSION before including this header.

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.

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 overriden by the struct fuse_operations.init handler.
Returns
0 on success, nonzero on failure

Example usage, see hello.c

◆ 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

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

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

◆ 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

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_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.

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

◆ 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

◆ 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

◆ 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 overriden by the struct fuse_operations.init handler.
Returns
a new filesystem object

◆ 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

◆ fuse_get_session()

struct fuse_session* fuse_get_session ( struct fuse *  f)

Get session from fuse object

◆ 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

◆ 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

◆ 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.

◆ 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()

◆ fuse_loop_mt()

int fuse_loop_mt ( struct fuse *  f,
int  clone_fd 
)

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
clone_fdwhether to use separate device fds for each thread (may increase performance)
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()

◆ 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.

◆ 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 overriden by the struct fuse_operations.init handler.
Returns
the created FUSE handle

◆ 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

◆ 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

◆ fuse_unmount()

void fuse_unmount ( struct fuse *  f)

Unmount a FUSE file system.

See fuse_session_unmount() for additional information.

Parameters
fthe FUSE handle