libfuse: fuse-3.3.2/include/fuse.h File Reference

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_31 (struct fuse *f, int clone_fd)
struct fuse_context * | fuse_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)

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

Parameters

  argc | the argument counter passed to the main() function
  argv | the argument vector passed to the main() function
  op | the file system operation
  private_data | Initial 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 829 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 1207 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 enableds 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

  buf | the buffer passed to the readdir() operation
  name | the file name of the directory entry
  stat | file attributes, can be NULL
  off | offset of the next entry or zero
  flags | fill 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

  args | the command line arguments
  fs | NULL terminated filesystem object vector

Returns
  the new filesystem object

Definition at line 1195 of file fuse.h.

## Enumeration Type Documentation

## ◆ fuse_fill_dir_flags

enum 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

enum 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

  fuse | struct fuse pointer for fuse instance

Returns
  the number of seconds until the next cleanup

Definition at line 4232 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

  f | the FUSE handle

Definition at line 4862 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

  f | the FUSE handle

Definition at line 4410 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

  op | the filesystem operations
  op_size | the size of the fuse_operations structure
  private_data | Initial 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

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

  op | the filesystem operations
  op_size | the size of the fuse_operations structure
  private_data | Initial 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

Definition at line 4618 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 4415 of file fuse.c.

## ◆ fuse_get_session()

struct fuse_session* fuse_get_session | ( | struct fuse * | f | ) |

Get session from fuse object

Definition at line 4317 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

  size | size of given array
  list | array of group IDs to be filled in

Returns
  the total number of supplementary group IDs or -errno on failure

Definition at line 4425 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 4434 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 4444 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

  args | the argument vector.

Definition at line 4508 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

  f | the FUSE handle

Returns
  see fuse_session_loop()

See also: fuse_loop_mt()

Definition at line 4374 of file fuse.c.

## ◆ fuse_loop_mt_31()

int fuse_loop_mt_31 | ( | 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

  f | the FUSE handle
  config | loop configuration

Returns
  see fuse_session_loop()

See also: fuse_loop()

Definition at line 4402 of file fuse.c.

## ◆ 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 274 of file helper.c.

## ◆ fuse_mount()

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

Mount a FUSE file system.

Parameters

  mountpoint | the mount point path
  f | the FUSE handle

Returns
  0 on success, -1 on failure.

Definition at line 4909 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

  args | argument vector
  op | the filesystem operations
  op_size | the size of the fuse_operations structure
  private_data | Initial 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_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

  fuse | struct fuse pointer for fuse instance

Returns
  0 on success and -1 on error

Definition at line 4666 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

  fuse | struct fuse pointer for fuse instance

Definition at line 4674 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

  f | the FUSE handle

Definition at line 4914 of file fuse.c.