# Virtual Filesystem Component

[中文]

## Overview

Virtual filesystem (VFS) component provides a unified interface for drivers which can perform operations on file-like objects. These can be real filesystems (FAT, SPIFFS, etc.) or device drivers which provide a file-like interface.

This component allows C library functions, such as fopen and fprintf, to work with FS drivers. At a high level, each FS driver is mounted at some path prefix. When one of C library functions needs to open a file, the VFS component searches for the FS driver associated with the file path and forwards the call to that driver. VFS also forwards read, write, and other calls for the given file to the same FS driver.

For example, one can mount a FAT filesystem driver at the `/fat` prefix and call `fopen("/fat/file.txt", "w")`. Then the VFS component calls the function `open` of the FAT driver and pass the argument `/file.txt` to it together with appropriate mode flags. All subsequent calls to C library functions for the returned `FILE*` stream will also be forwarded to the FAT driver.

## FS Registration

To register an FS driver, an application needs to define an instance of the `esp_vfs_fs_ops_t` structure and populate it with function pointers to FS APIs:

Warning

The API version without a context pointer is deprecated, and will be removed in the future. See Context Aware Filesystem for details.

    // Both esp_vfs_fs_ops_t and its subcomponents have to have static storage
    static const esp_vfs_dir_ops_t myfs_dir = {
        .stat = &myfs_stat,
    };

    static const esp_vfs_fs_ops_t myfs = {
        .write = &myfs_write,
        .open = &myfs_open,
        .close = &myfs_close,
        .read = &myfs_read,
        .dir = &myfs_dir,
    };

    ESP_ERROR_CHECK(esp_vfs_register_fs("/data", &myfs, ESP_VFS_FLAG_STATIC, NULL));

### Non-static `esp_vfs_fs_ops_t`

The recommended approach for registering filesystem is to use statically allocated `esp_vfs_fs_ops_t` alongside `ESP_VFS_FLAG_STATIC`, as it is more memory efficient. In cases where using static allocation is not possible, `ESP_VFS_FLAG_STATIC` can be replaced with `ESP_VFS_FLAG_DEFAULT`. This tells VFS to make a deep copy of the passed structure in RAM, this copy will be managed by VFS component.

    // Possibly local scope
    {
        esp_vfs_dir_ops_t myfs_dir = {
            .stat = &myfs_stat,
        };

        bool some_condition = false;

        esp_vfs_fs_ops_t myfs = {
            .write = some_condition ? &myfs_special_write : &myfs_write,
            // ... other members
            .dir = &myfs_dir,
        };

        ESP_ERROR_CHECK(esp_vfs_register_fs("/data", &myfs, ESP_VFS_FLAG_DEFAULT, NULL));
    }

### Context Aware Filesystem

In some cases, it might be beneficial or even necessary to pass some context to the filesystem functions, such as a mountpoint-specific file descriptor table, when multiple instances of FS are mounted. For this reason, `esp_vfs_fs_ops_t` contains a second version of each member with `_p` suffix; for example, `read` function has a corresponding `read_p` function. These functions take an additional first argument. When registering the FS, `ESP_VFS_FLAG_CONTEXT_PTR` needs to be specified and the context pointer should be passed as the last argument.

    ssize_t myfs_write(myfs_t* fs, int fd, const void * data, size_t size);

    // In definition of esp_vfs_fs_ops_t:
        .write_p = &myfs_write,
    // ... other members initialized

    // When registering FS, pass the ESP_VFS_FLAG_CONTEXT_PTR flag, alongside FS context pointer as the third and fourth arguments, respectively
    // (hypothetical myfs_mount function is used for illustrative purposes)
    myfs_t* myfs_inst1 = myfs_mount(partition1->offset, partition1->size);
    ESP_ERROR_CHECK(esp_vfs_register_fs("/data1", &myfs, ESP_VFS_FLAG_STATIC | ESP_VFS_FLAG_CONTEXT_PTR, myfs_inst1));

    // Can register another instance:
    myfs_t* myfs_inst2 = myfs_mount(partition2->offset, partition2->size);
    ESP_ERROR_CHECK(esp_vfs_register_fs("/data2", &myfs, ESP_VFS_FLAG_STATIC | ESP_VFS_FLAG_CONTEXT_PTR, myfs_inst2));

## Synchronous Input/Output Multiplexing

Synchronous input/output multiplexing by `select()` is supported in the VFS component. The implementation works in the following way.

1. `select()` is called with file descriptors which could belong to various VFS drivers.

2. The file descriptors are divided into groups each belonging to one VFS driver.

3. The file descriptors belonging to non-socket VFS drivers are handed over to the given VFS drivers by `start_select()`, described later on this page. This function represents the driver-specific implementation of `select()` for the given driver. This should be a non-blocking call which means the function should immediately return after setting up the environment for checking events related to the given file descriptors.

4. The file descriptors belonging to the socket VFS driver are handed over to the socket driver by `socket_select()` described later on this page. This is a blocking call which means that it will return only if there is an event related to socket file descriptors or a non-socket driver signals `socket_select()` to exit.

5. Results are collected from each VFS driver and all drivers are stopped by de-initialization of the environment for checking events.

6. The `select()` call ends and returns the appropriate results.

### Non-Socket VFS Drivers

If you want to use `select()` with a file descriptor belonging to a non-socket VFS driver, then you need to register the driver with functions `start_select()` and `end_select()` similarly to the following example:

    // In definition of esp_vfs_select_ops_t:
        .start_select = &uart_start_select,
        .end_select = &uart_end_select,
    // ... other members initialized

`start_select()` is called for setting up the environment for detection of read/write/error conditions on file descriptors belonging to the given VFS driver.

`end_select()` is called to stop/deinitialize/free the environment which was setup by `start_select()`.

Note

`end_select()` might be called without a previous `start_select()` call in some rare circumstances. `end_select()` should fail gracefully if this is the case (i.e., should not crash but return an error instead).

Please refer to the reference implementation for the UART peripheral in esp_driver_uart/src/uart_vfs.c and most particularly to the functions `uart_vfs_dev_register()`, `uart_start_select()`, and `uart_end_select()` for more information.

Please check the following examples that demonstrate the use of `select()` with VFS file descriptors:

- peripherals/uart/uart_select

- system/select

### Socket VFS Drivers

A socket VFS driver is using its own internal implementation of `select()` and non-socket VFS drivers notify it upon read/write/error conditions.

A socket VFS driver needs to be registered with the following functions defined:

    // In definition of esp_vfs_select_ops_t:
        .socket_select = &lwip_select,
        .get_socket_select_semaphore = &lwip_get_socket_select_semaphore,
        .stop_socket_select = &lwip_stop_socket_select,
        .stop_socket_select_isr = &lwip_stop_socket_select_isr,
    // ... other members initialized

`socket_select()` is the internal implementation of `select()` for the socket driver. It works only with file descriptors belonging to the socket VFS.

`get_socket_select_semaphore()` returns the signalization object (semaphore) which is used in non-socket drivers to stop the waiting in `socket_select()`.

`stop_socket_select()` call is used to stop the waiting in `socket_select()` by passing the object returned by `get_socket_select_semaphore()`.

`stop_socket_select_isr()` has the same functionality as `stop_socket_select()` but it can be used from ISR.

Please see lwip/port/esp32xx/vfs_lwip.c for a reference socket driver implementation using LWIP.

Note

If you use `select()` for socket file descriptors only then you can disable the CONFIG_VFS_SUPPORT_SELECT option to reduce the code size and improve performance.

You should not change the socket driver during an active `select()` call or you might experience some undefined behavior.

## Paths

Each registered FS has a path prefix associated with it. This prefix can be considered as a "mount point" of this partition.

In case when mount points are nested, the mount point with the longest matching path prefix is used when opening the file. For instance, suppose that the following filesystems are registered in VFS:

- FS 1 on /data

- FS 2 on /data/static

Then:

- FS 1 will be used when opening a file called `/data/log.txt`

- FS 2 will be used when opening a file called `/data/static/index.html`

- Even if `/index.html"` does not exist in FS 2, FS 1 will not be searched for `/static/index.html`.

As a general rule, mount point names must start with the path separator (`/`) and must contain at least one character after path separator. However, an empty mount point name is also supported and might be used in cases when an application needs to provide a "fallback" filesystem or to override VFS functionality altogether. Such filesystem will be used if no prefix matches the path given.

VFS does not handle dots (`.`) in path names in any special way. VFS does not treat `..` as a reference to the parent directory. In the above example, using a path `/data/static/../log.txt` will not result in a call to FS 1 to open `/log.txt`. Specific FS drivers (such as FATFS) might handle dots in file names differently.

When opening files, the FS driver receives only relative paths to files. For example:

1. The `myfs` driver is registered with `/data` as a path prefix.

2. The application calls `fopen("/data/config.json", ...)`.

3. The VFS component calls `myfs_open("/config.json", ...)`.

4. The `myfs` driver opens the `/config.json` file.

VFS does not impose any limit on total file path length, but it does limit the FS path prefix to `ESP_VFS_PATH_MAX` characters. Individual FS drivers may have their own filename length limitations.

## File Descriptors

File descriptors are small positive integers from `0` to `FD_SETSIZE - 1`, where `FD_SETSIZE` is defined in `sys/select.h`. The largest file descriptors (configured by `CONFIG_LWIP_MAX_SOCKETS`) are reserved for sockets. The VFS component contains a lookup-table called `s_fd_table` for mapping global file descriptors to VFS driver indexes registered in the `s_vfs` array.

Standard I/O streams (`stdin`, `stdout`, `stderr`) are mapped to file descriptors `0`, `1`, and `2` respectively. For more information on standard I/O, see Standard I/O and Console Output.

## `eventfd()`

`eventfd()` call is a powerful tool to notify a `select()` based loop of custom events. The `eventfd()` implementation in ESP-IDF is generally the same as described in man(2) eventfd except for:

- `esp_vfs_eventfd_register()` has to be called before calling `eventfd()`

- Options `EFD_CLOEXEC`, `EFD_NONBLOCK` and `EFD_SEMAPHORE` are not supported in flags.

- Option `EFD_SUPPORT_ISR` has been added in flags. This flag is required to read and write the eventfd in an interrupt handler.

Note that creating an eventfd with `EFD_SUPPORT_ISR` will cause interrupts to be temporarily disabled when reading, writing the file and during the beginning and the ending of the `select()` when this file is set.

## Well Known VFS Devices

IDF defines several VFS devices that can be used by applications. These devices are, among others:

- `/dev/uart/<UART NUMBER>` - file mapping to an UART opened with the VFS driver. The UART number is the number of the UART peripheral.

- `/dev/null` - file that discards all data written to it and returns EOF when read. It is automatically created if CONFIG_VFS_INITIALIZE_DEV_NULL is enabled.

- `/dev/console` - file that is connected to the primary and secondary outputs specified in the menuconfig by CONFIG_ESP_CONSOLE_UART and CONFIG_ESP_CONSOLE_SECONDARY respectively. More information can be found here Standard I/O and Console Output.

## Application Examples

- system/eventfd demonstrates how to use `eventfd()` to collect events from tasks and ISRs in a `select()` based main loop, using two tasks and a timer ISR (interrupt service routine) callback.

- system/select demonstrates how to use synchronous I/O multiplexing with the `select()` function, using UART and socket file descriptors, and configuring both to act as loopbacks to receive messages sent from other tasks.

- storage/semihost_vfs demonstrates how to use the semihosting VFS driver, including registering a host directory, redirecting stdout from UART to a file on the host, and reading and printing the content of a text file.

## API Reference

### Header File

- components/vfs/include/esp_vfs.h

- This header file can be included with:

  >     #include "esp_vfs.h"

- This header file is a part of the API provided by the `vfs` component. To declare that your component depends on `vfs`, add the following to your CMakeLists.txt:

  >     REQUIRES vfs

  > or

  >     PRIV_REQUIRES vfs

### Functions

ssize_t esp_vfs_write(struct _reent *r, int fd, const void *data, size_t size)

  These functions are to be used in esp_libc syscall table. They will be called by esp_libc when it needs to use any of the syscalls.

off_t esp_vfs_lseek(struct _reent *r, int fd, off_t size, int mode)

ssize_t esp_vfs_read(struct _reent *r, int fd, void *dst, size_t size)

int esp_vfs_open(struct _reent *r, const char *path, int flags, int mode)

int esp_vfs_close(struct _reent *r, int fd)

int esp_vfs_fstat(struct _reent *r, int fd, struct stat *st)

int esp_vfs_stat(struct _reent *r, const char *path, struct stat *st)

int esp_vfs_link(struct _reent *r, const char *n1, const char *n2)

int esp_vfs_unlink(struct _reent *r, const char *path)

int esp_vfs_rename(struct _reent *r, const char *src, const char *dst)

int esp_vfs_utime(const char *path, const struct utimbuf *times)

esp_err_t esp_vfs_register(const char *base_path, const esp_vfs_t *vfs, void *ctx)

  Register a virtual filesystem for given path prefix.

  Parameters:

    - base_path -- file path prefix associated with the filesystem. Must be a zero-terminated C string, may be empty. If not empty, must be up to ESP_VFS_PATH_MAX characters long, and at least 2 characters long. Name must start with a "/" and must not end with "/". For example, "/data" or "/dev/spi" are valid. These VFSes would then be called to handle file paths such as "/data/myfile.txt" or "/dev/spi/0". In the special case of an empty base_path, a "fallback" VFS is registered. Such VFS will handle paths which are not matched by any other registered VFS.

    - vfs -- Pointer to esp_vfs_t, a structure which maps syscalls to the filesystem driver functions. VFS component doesn't assume ownership of this pointer.

    - ctx -- If vfs->flags has ESP_VFS_FLAG_CONTEXT_PTR set, a pointer which should be passed to VFS functions. Otherwise, NULL.

  Returns:

    ESP_OK if successful, ESP_ERR_NO_MEM if too many VFSes are registered.

esp_err_t esp_vfs_register_with_id(const esp_vfs_t *vfs, void *ctx, esp_vfs_id_t *vfs_id)

  Special case function for registering a VFS that uses a method other than open() to open new file descriptors. In comparison with esp_vfs_register_fd_range, this function doesn't pre-registers an interval of file descriptors. File descriptors can be registered later, by using esp_vfs_register_fd.

  Parameters:

    - vfs -- Pointer to esp_vfs_t. Meaning is the same as for esp_vfs_register().

    - ctx -- Pointer to context structure. Meaning is the same as for esp_vfs_register().

    - vfs_id -- Here will be written the VFS ID which can be passed to esp_vfs_register_fd for registering file descriptors.

  Returns:

    ESP_OK if successful, ESP_ERR_NO_MEM if too many VFSes are registered, ESP_ERR_INVALID_ARG if the file descriptor boundaries are incorrect.

esp_err_t esp_vfs_unregister(const char *base_path)

  Unregister a virtual filesystem for given path prefix

  Parameters:

    base_path -- file prefix previously used in esp_vfs_register call

  Returns:

    ESP_OK if successful, ESP_ERR_INVALID_STATE if VFS for given prefix hasn't been registered

esp_err_t esp_vfs_unregister_with_id(esp_vfs_id_t vfs_id)

  Unregister a virtual filesystem with the given index

  Parameters:

    vfs_id -- The VFS ID returned by esp_vfs_register_with_id

  Returns:

    ESP_OK if successful, ESP_ERR_INVALID_STATE if VFS for the given index hasn't been registered

esp_err_t esp_vfs_register_fd(esp_vfs_id_t vfs_id, int *fd)

  Special function for registering another file descriptor for a VFS registered by esp_vfs_register_with_id. This function should only be used to register permanent file descriptors (socket fd) that are not removed after being closed.

  Parameters:

    - vfs_id -- VFS identificator returned by esp_vfs_register_with_id.

    - fd -- The registered file descriptor will be written to this address.

  Returns:

    ESP_OK if the registration is successful, ESP_ERR_NO_MEM if too many file descriptors are registered, ESP_ERR_INVALID_ARG if the arguments are incorrect.

esp_err_t esp_vfs_register_fd_with_local_fd(esp_vfs_id_t vfs_id, int local_fd, bool permanent, int *fd)

  Special function for registering another file descriptor with given local_fd for a VFS registered by esp_vfs_register_with_id.

  Parameters:

    - vfs_id -- VFS identificator returned by esp_vfs_register_with_id.

    - local_fd -- The fd in the local vfs. Passing -1 will set the local fd as the (*fd) value.

    - permanent -- Whether the fd should be treated as permanent (not removed after close())

    - fd -- The registered file descriptor will be written to this address.

  Returns:

    ESP_OK if the registration is successful, ESP_ERR_NO_MEM if too many file descriptors are registered, ESP_ERR_INVALID_ARG if the arguments are incorrect.

esp_err_t esp_vfs_unregister_fd(esp_vfs_id_t vfs_id, int fd)

  Special function for unregistering a file descriptor belonging to a VFS registered by esp_vfs_register_with_id.

  Parameters:

    - vfs_id -- VFS identificator returned by esp_vfs_register_with_id.

    - fd -- File descriptor which should be unregistered.

  Returns:

    ESP_OK if the registration is successful, ESP_ERR_INVALID_ARG if the arguments are incorrect.

int esp_vfs_select(int nfds, fd_set *readfds, fd_set *writefds, fd_set *errorfds, struct timeval *timeout)

  Synchronous I/O multiplexing which implements the functionality of POSIX select() for VFS.

  Parameters:

    - nfds -- Specifies the range of descriptors which should be checked. The first nfds descriptors will be checked in each set.

    - readfds -- If not NULL, then points to a descriptor set that on input specifies which descriptors should be checked for being ready to read, and on output indicates which descriptors are ready to read.

    - writefds -- If not NULL, then points to a descriptor set that on input specifies which descriptors should be checked for being ready to write, and on output indicates which descriptors are ready to write.

    - errorfds -- If not NULL, then points to a descriptor set that on input specifies which descriptors should be checked for error conditions, and on output indicates which descriptors have error conditions.

    - timeout -- If not NULL, then points to timeval structure which specifies the time period after which the functions should time-out and return. If it is NULL, then the function will not time-out. Note that the timeout period is rounded up to the system tick and incremented by one.

  Returns:

    The number of descriptors set in the descriptor sets, or -1 when an error (specified by errno) have occurred.

void esp_vfs_select_triggered(esp_vfs_select_sem_t sem)

  Notification from a VFS driver about a read/write/error condition.

  This function is called when the VFS driver detects a read/write/error condition as it was requested by the previous call to start_select.

  Parameters:

    sem -- semaphore structure which was passed to the driver by the start_select call

void esp_vfs_select_triggered_isr(esp_vfs_select_sem_t sem, BaseType_t *woken)

  Notification from a VFS driver about a read/write/error condition (ISR version)

  This function is called when the VFS driver detects a read/write/error condition as it was requested by the previous call to start_select.

  Parameters:

    - sem -- semaphore structure which was passed to the driver by the start_select call

    - woken -- is set to pdTRUE if the function wakes up a task with higher priority

ssize_t esp_vfs_pread(int fd, void *dst, size_t size, off_t offset)

  Implements the VFS layer of POSIX pread()

  Parameters:

    - fd -- File descriptor used for read

    - dst -- Pointer to the buffer where the output will be written

    - size -- Number of bytes to be read

    - offset -- Starting offset of the read

  Returns:

    A positive return value indicates the number of bytes read. -1 is return on failure and errno is set accordingly.

ssize_t esp_vfs_pwrite(int fd, const void *src, size_t size, off_t offset)

  Implements the VFS layer of POSIX pwrite()

  Parameters:

    - fd -- File descriptor used for write

    - src -- Pointer to the buffer from where the output will be read

    - size -- Number of bytes to write

    - offset -- Starting offset of the write

  Returns:

    A positive return value indicates the number of bytes written. -1 is return on failure and errno is set accordingly.

void esp_vfs_dump_fds(FILE *fp)

  Dump the existing VFS FDs data to FILE* fp.

  Dump the FDs in the format:

              <VFS Path Prefix>-<FD seen by App>-<FD seen by driver>

         where:
          VFS Path Prefix   : file prefix used in the esp_vfs_register call
          FD seen by App    : file descriptor returned by the vfs to the application for the path prefix
          FD seen by driver : file descriptor used by the driver for the same file prefix.

  Parameters:

    fp -- File descriptor where data will be dumped

void esp_vfs_dump_registered_paths(FILE *fp)

  Dump all registered FSs to the provided FILE*.

  Dump the FSs in the format:

             <index>:<VFS Path Prefix> -> <VFS entry ptr>

         where:
             index           : internal index in the table of registered FSs (the same as returned when registering fd with id)
             VFS Path Prefix : file prefix used in the esp_vfs_register call or "NULL"
             VFS entry ptr   : pointer to the esp_vfs_fs_ops_t struct used internally when resolving the calls

  Parameters:

    fp -- File descriptor where data will be dumped

### Structures

struct esp_vfs_t

  VFS definition structure.

  This structure should be filled with pointers to corresponding FS driver functions.

  VFS component will translate all FDs so that the filesystem implementation sees them starting at zero. The caller sees a global FD which is prefixed with an pre-filesystem-implementation.

  Some FS implementations expect some state (e.g. pointer to some structure) to be passed in as a first argument. For these implementations, populate the members of this structure which have _p suffix, set flags member to ESP_VFS_FLAG_CONTEXT_PTR and provide the context pointer to esp_vfs_register function. If the implementation doesn't use this extra argument, populate the members without _p suffix and set flags member to ESP_VFS_FLAG_DEFAULT.

  If the FS driver doesn't provide some of the functions, set corresponding members to NULL.

  Note

  Prefer using esp_vfs_fs_ops_t with esp_vfs_register_fs*() instead.

  Public Members

  int flags

    ESP_VFS_FLAG_CONTEXT_PTR and/or ESP_VFS_FLAG_READONLY_FS or ESP_VFS_FLAG_DEFAULT

  ssize_t (*write_p)(void *p, int fd, const void *data, size_t size)

    Write with context pointer

  ssize_t (*write)(int fd, const void *data, size_t size)

    Write without context pointer

  off_t (*lseek_p)(void *p, int fd, off_t size, int mode)

    Seek with context pointer

  off_t (*lseek)(int fd, off_t size, int mode)

    Seek without context pointer

  ssize_t (*read_p)(void *ctx, int fd, void *dst, size_t size)

    Read with context pointer

  ssize_t (*read)(int fd, void *dst, size_t size)

    Read without context pointer

  ssize_t (*pread_p)(void *ctx, int fd, void *dst, size_t size, off_t offset)

    pread with context pointer

  ssize_t (*pread)(int fd, void *dst, size_t size, off_t offset)

    pread without context pointer

  ssize_t (*pwrite_p)(void *ctx, int fd, const void *src, size_t size, off_t offset)

    pwrite with context pointer

  ssize_t (*pwrite)(int fd, const void *src, size_t size, off_t offset)

    pwrite without context pointer

  int (*open_p)(void *ctx, const char *path, int flags, int mode)

    open with context pointer

  int (*open)(const char *path, int flags, int mode)

    open without context pointer

  int (*close_p)(void *ctx, int fd)

    close with context pointer

  int (*close)(int fd)

    close without context pointer

  int (*fstat_p)(void *ctx, int fd, struct stat *st)

    fstat with context pointer

  int (*fstat)(int fd, struct stat *st)

    fstat without context pointer

  int (*stat_p)(void *ctx, const char *path, struct stat *st)

    stat with context pointer

  int (*stat)(const char *path, struct stat *st)

    stat without context pointer

  int (*link_p)(void *ctx, const char *n1, const char *n2)

    link with context pointer

  int (*link)(const char *n1, const char *n2)

    link without context pointer

  int (*unlink_p)(void *ctx, const char *path)

    unlink with context pointer

  int (*unlink)(const char *path)

    unlink without context pointer

  int (*rename_p)(void *ctx, const char *src, const char *dst)

    rename with context pointer

  int (*rename)(const char *src, const char *dst)

    rename without context pointer

  DIR *(*opendir_p)(void *ctx, const char *name)

    opendir with context pointer

  DIR *(*opendir)(const char *name)

    opendir without context pointer

  struct dirent *(*readdir_p)(void *ctx, DIR *pdir)

    readdir with context pointer

  struct dirent *(*readdir)(DIR *pdir)

    readdir without context pointer

  int (*readdir_r_p)(void *ctx, DIR *pdir, struct dirent *entry, struct dirent **out_dirent)

    readdir_r with context pointer

  int (*readdir_r)(DIR *pdir, struct dirent *entry, struct dirent **out_dirent)

    readdir_r without context pointer

  long (*telldir_p)(void *ctx, DIR *pdir)

    telldir with context pointer

  long (*telldir)(DIR *pdir)

    telldir without context pointer

  void (*seekdir_p)(void *ctx, DIR *pdir, long offset)

    seekdir with context pointer

  void (*seekdir)(DIR *pdir, long offset)

    seekdir without context pointer

  int (*closedir_p)(void *ctx, DIR *pdir)

    closedir with context pointer

  int (*closedir)(DIR *pdir)

    closedir without context pointer

  int (*mkdir_p)(void *ctx, const char *name, mode_t mode)

    mkdir with context pointer

  int (*mkdir)(const char *name, mode_t mode)

    mkdir without context pointer

  int (*rmdir_p)(void *ctx, const char *name)

    rmdir with context pointer

  int (*rmdir)(const char *name)

    rmdir without context pointer

  int (*fcntl_p)(void *ctx, int fd, int cmd, int arg)

    fcntl with context pointer

  int (*fcntl)(int fd, int cmd, int arg)

    fcntl without context pointer

  int (*ioctl_p)(void *ctx, int fd, int cmd, va_list args)

    ioctl with context pointer

  int (*ioctl)(int fd, int cmd, va_list args)

    ioctl without context pointer

  int (*fsync_p)(void *ctx, int fd)

    fsync with context pointer

  int (*fsync)(int fd)

    fsync without context pointer

  int (*access_p)(void *ctx, const char *path, int amode)

    access with context pointer

  int (*access)(const char *path, int amode)

    access without context pointer

  int (*truncate_p)(void *ctx, const char *path, off_t length)

    truncate with context pointer

  int (*truncate)(const char *path, off_t length)

    truncate without context pointer

  int (*ftruncate_p)(void *ctx, int fd, off_t length)

    ftruncate with context pointer

  int (*ftruncate)(int fd, off_t length)

    ftruncate without context pointer

  int (*utime_p)(void *ctx, const char *path, const struct utimbuf *times)

    utime with context pointer

  int (*utime)(const char *path, const struct utimbuf *times)

    utime without context pointer

  esp_err_t (*start_select)(int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, esp_vfs_select_sem_t sem, void **end_select_args)

    start_select is called for setting up synchronous I/O multiplexing of the desired file descriptors in the given VFS

  int (*socket_select)(int nfds, fd_set *readfds, fd_set *writefds, fd_set *errorfds, struct timeval *timeout)

    socket select function for socket FDs with the functionality of POSIX select(); this should be set only for the socket VFS

  void (*stop_socket_select)(void *sem)

    called by VFS to interrupt the socket_select call when select is activated from a non-socket VFS driver; set only for the socket driver

  void (*stop_socket_select_isr)(void *sem, BaseType_t *woken)

    stop_socket_select which can be called from ISR; set only for the socket driver

  void *(*get_socket_select_semaphore)(void)

    end_select is called to stop the I/O multiplexing and deinitialize the environment created by start_select for the given VFS

  esp_err_t (*end_select)(void *end_select_args)

    get_socket_select_semaphore returns semaphore allocated in the socket driver; set only for the socket driver

### Macros

MAX_FDS

  Maximum number of (global) file descriptors.

ESP_VFS_PATH_MAX

  Maximum length of path prefix (not including zero terminator)

ESP_VFS_FLAG_DEFAULT

  Default value of flags member in esp_vfs_fs_ops_t structure.

ESP_VFS_FLAG_CONTEXT_PTR

  Flag which indicates that FS needs extra context pointer in syscalls.

ESP_VFS_FLAG_READONLY_FS

  Flag which indicates that FS is located on read-only partition.

ESP_VFS_FLAG_STATIC

  Flag which indicates that VFS structure should be freed upon unregistering.

  Note

  Free if false, do not free if true

### Header File

- components/vfs/include/esp_vfs_ops.h

- This header file can be included with:

  >     #include "esp_vfs_ops.h"

- This header file is a part of the API provided by the `vfs` component. To declare that your component depends on `vfs`, add the following to your CMakeLists.txt:

  >     REQUIRES vfs

  > or

  >     PRIV_REQUIRES vfs

### Functions

esp_err_t esp_vfs_register_fs(const char *base_path, const esp_vfs_fs_ops_t *vfs, int flags, void *ctx)

  Register a virtual filesystem for given path prefix.

  Parameters:

    - base_path -- file path prefix associated with the filesystem. Must be a zero-terminated C string, may be empty. If not empty, must be up to ESP_VFS_PATH_MAX characters long, and at least 2 characters long. Name must start with a "/" and must not end with "/". For example, "/data" or "/dev/spi" are valid. These VFSes would then be called to handle file paths such as "/data/myfile.txt" or "/dev/spi/0". In the special case of an empty base_path, a "fallback" VFS is registered. Such VFS will handle paths which are not matched by any other registered VFS.

    - vfs -- Pointer to esp_vfs_fs_ops_t, a structure which maps syscalls to the filesystem driver functions. VFS component does not assume ownership of this struct, but see flags for more info

    - flags -- Set of binary flags controlling how the registered FS should be treated

      - ESP_VFS_FLAG_STATIC - if this flag is specified VFS assumes the provided esp_vfs_fs_ops_t and all its subcomponents are statically allocated, if it is not enabled a deep copy of the provided struct will be created, which will be managed by the VFS component

      - ESP_VFS_FLAG_CONTEXT_PTR - If set, the VFS will use the context-aware versions of the filesystem operation functions (suffixed with `_p`) in `esp_vfs_fs_ops_t` and its subcomponents. The `ctx` parameter will be passed as the context argument when these functions are invoked.

    - ctx -- Context pointer for fs operation functions, see the ESP_VFS_FLAG_CONTEXT_PTR. Should be `NULL` if not used.

  Returns:

    ESP_OK if successful, ESP_ERR_NO_MEM if too many FSes are registered.

esp_err_t esp_vfs_register_fs_with_id(const esp_vfs_fs_ops_t *vfs, int flags, void *ctx, esp_vfs_id_t *id)

  Analog of esp_vfs_register_with_id which accepts esp_vfs_fs_ops_t instead.

esp_err_t esp_vfs_unregister_fs(const char *base_path)

  Alias for esp_vfs_unregister for naming consistency

esp_err_t esp_vfs_unregister_fs_with_id(esp_vfs_id_t id)

  Alias for esp_vfs_unregister_with_id for naming consistency

### Structures

struct esp_vfs_select_sem_t

  VFS semaphore type for select()

  Public Members

  bool is_sem_local

    type of "sem" is SemaphoreHandle_t when true, defined by socket driver otherwise

  void *sem

    semaphore instance

struct esp_vfs_dir_ops_t

  Struct containing function pointers to directory related functionality.

  Public Members

  const esp_vfs_stat_ctx_op_t stat_p

    stat with context pointer

  const esp_vfs_stat_op_t stat

    stat without context pointer

  const esp_vfs_link_ctx_op_t link_p

    link with context pointer

  const esp_vfs_link_op_t link

    link without context pointer

  const esp_vfs_unlink_ctx_op_t unlink_p

    unlink with context pointer

  const esp_vfs_unlink_op_t unlink

    unlink without context pointer

  const esp_vfs_rename_ctx_op_t rename_p

    rename with context pointer

  const esp_vfs_rename_op_t rename

    rename without context pointer

  const esp_vfs_opendir_ctx_op_t opendir_p

    opendir with context pointer

  const esp_vfs_opendir_op_t opendir

    opendir without context pointer

  const esp_vfs_readdir_ctx_op_t readdir_p

    readdir with context pointer

  const esp_vfs_readdir_op_t readdir

    readdir without context pointer

  const esp_vfs_readdir_r_ctx_op_t readdir_r_p

    readdir_r with context pointer

  const esp_vfs_readdir_r_op_t readdir_r

    readdir_r without context pointer

  const esp_vfs_telldir_ctx_op_t telldir_p

    telldir with context pointer

  const esp_vfs_telldir_op_t telldir

    telldir without context pointer

  const esp_vfs_seekdir_ctx_op_t seekdir_p

    seekdir with context pointer

  const esp_vfs_seekdir_op_t seekdir

    seekdir without context pointer

  const esp_vfs_closedir_ctx_op_t closedir_p

    closedir with context pointer

  const esp_vfs_closedir_op_t closedir

    closedir without context pointer

  const esp_vfs_mkdir_ctx_op_t mkdir_p

    mkdir with context pointer

  const esp_vfs_mkdir_op_t mkdir

    mkdir without context pointer

  const esp_vfs_rmdir_ctx_op_t rmdir_p

    rmdir with context pointer

  const esp_vfs_rmdir_op_t rmdir

    rmdir without context pointer

  const esp_vfs_access_ctx_op_t access_p

    access with context pointer

  const esp_vfs_access_op_t access

    access without context pointer

  const esp_vfs_truncate_ctx_op_t truncate_p

    truncate with context pointer

  const esp_vfs_truncate_op_t truncate

    truncate without context pointer

  const esp_vfs_ftruncate_ctx_op_t ftruncate_p

    ftruncate with context pointer

  const esp_vfs_ftruncate_op_t ftruncate

    ftruncate without context pointer

  const esp_vfs_utime_ctx_op_t utime_p

    utime with context pointer

  const esp_vfs_utime_op_t utime

    utime without context pointer

struct esp_vfs_select_ops_t

  Struct containing function pointers to select related functionality.

  Public Members

  const esp_vfs_start_select_op_t start_select

    start_select is called for setting up synchronous I/O multiplexing of the desired file descriptors in the given VFS

  const esp_vfs_socket_select_op_t socket_select

    socket select function for socket FDs with the functionality of POSIX select(); this should be set only for the socket VFS

  const esp_vfs_stop_socket_select_op_t stop_socket_select

    called by VFS to interrupt the socket_select call when select is activated from a non-socket VFS driver; set only for the socket driver

  const esp_vfs_stop_socket_select_isr_op_t stop_socket_select_isr

    stop_socket_select which can be called from ISR; set only for the socket driver

  const esp_vfs_get_socket_select_semaphore_op_t get_socket_select_semaphore

    end_select is called to stop the I/O multiplexing and deinitialize the environment created by start_select for the given VFS

  const esp_vfs_end_select_op_t end_select

    get_socket_select_semaphore returns semaphore allocated in the socket driver; set only for the socket driver

struct esp_vfs_fs_ops_t

  Main struct of the minified vfs API, containing basic function pointers as well as pointers to the other subcomponents.

  Public Members

  const esp_vfs_write_ctx_op_t write_p

    Write with context pointer

  const esp_vfs_write_op_t write

    Write without context pointer

  const esp_vfs_lseek_ctx_op_t lseek_p

    Seek with context pointer

  const esp_vfs_lseek_op_t lseek

    Seek without context pointer

  const esp_vfs_read_ctx_op_t read_p

    Read with context pointer

  const esp_vfs_read_op_t read

    Read without context pointer

  const esp_vfs_pread_ctx_op_t pread_p

    pread with context pointer

  const esp_vfs_pread_op_t pread

    pread without context pointer

  const esp_vfs_pwrite_ctx_op_t pwrite_p

    pwrite with context pointer

  const esp_vfs_pwrite_op_t pwrite

    pwrite without context pointer

  const esp_vfs_open_ctx_op_t open_p

    open with context pointer

  const esp_vfs_open_op_t open

    open without context pointer

  const esp_vfs_close_ctx_op_t close_p

    close with context pointer

  const esp_vfs_close_op_t close

    close without context pointer

  const esp_vfs_fstat_ctx_op_t fstat_p

    fstat with context pointer

  const esp_vfs_fstat_op_t fstat

    fstat without context pointer

  const esp_vfs_fcntl_ctx_op_t fcntl_p

    fcntl with context pointer

  const esp_vfs_fcntl_op_t fcntl

    fcntl without context pointer

  const esp_vfs_ioctl_ctx_op_t ioctl_p

    ioctl with context pointer

  const esp_vfs_ioctl_op_t ioctl

    ioctl without context pointer

  const esp_vfs_fsync_ctx_op_t fsync_p

    fsync with context pointer

  const esp_vfs_fsync_op_t fsync

    fsync without context pointer

  const esp_vfs_dir_ops_t *const dir

    pointer to the dir subcomponent

  const esp_vfs_select_ops_t *const select

    pointer to the select subcomponent

### Type Definitions

typedef int esp_vfs_id_t

typedef int (*esp_vfs_stat_ctx_op_t)(void *ctx, const char *path, struct stat *st)

  stat with context pointer

typedef int (*esp_vfs_stat_op_t)(const char *path, struct stat *st)

  stat without context pointer

typedef int (*esp_vfs_link_ctx_op_t)(void *ctx, const char *n1, const char *n2)

  link with context pointer

typedef int (*esp_vfs_link_op_t)(const char *n1, const char *n2)

  link without context pointer

typedef int (*esp_vfs_unlink_ctx_op_t)(void *ctx, const char *path)

  unlink with context pointer

typedef int (*esp_vfs_unlink_op_t)(const char *path)

  unlink without context pointer

typedef int (*esp_vfs_rename_ctx_op_t)(void *ctx, const char *src, const char *dst)

  rename with context pointer

typedef int (*esp_vfs_rename_op_t)(const char *src, const char *dst)

  rename without context pointer

typedef DIR *(*esp_vfs_opendir_ctx_op_t)(void *ctx, const char *name)

  opendir with context pointer

typedef DIR *(*esp_vfs_opendir_op_t)(const char *name)

  opendir without context pointer

typedef struct dirent *(*esp_vfs_readdir_ctx_op_t)(void *ctx, DIR *pdir)

  readdir with context pointer

typedef struct dirent *(*esp_vfs_readdir_op_t)(DIR *pdir)

  readdir without context pointer

typedef int (*esp_vfs_readdir_r_ctx_op_t)(void *ctx, DIR *pdir, struct dirent *entry, struct dirent **out)

  readdir_r with context pointer

typedef int (*esp_vfs_readdir_r_op_t)(DIR *pdir, struct dirent *entry, struct dirent **out)

  readdir_r without context pointer

typedef long (*esp_vfs_telldir_ctx_op_t)(void *ctx, DIR *pdir)

  telldir with context pointer

typedef long (*esp_vfs_telldir_op_t)(DIR *pdir)

  telldir without context pointer

typedef void (*esp_vfs_seekdir_ctx_op_t)(void *ctx, DIR *pdir, long offset)

  seekdir with context pointer

typedef void (*esp_vfs_seekdir_op_t)(DIR *pdir, long offset)

  seekdir without context pointer

typedef int (*esp_vfs_closedir_ctx_op_t)(void *ctx, DIR *pdir)

  closedir with context pointer

typedef int (*esp_vfs_closedir_op_t)(DIR *pdir)

  closedir without context pointer

typedef int (*esp_vfs_mkdir_ctx_op_t)(void *ctx, const char *name, mode_t mode)

  mkdir with context pointer

typedef int (*esp_vfs_mkdir_op_t)(const char *name, mode_t mode)

  mkdir without context pointer

typedef int (*esp_vfs_rmdir_ctx_op_t)(void *ctx, const char *name)

  rmdir with context pointer

typedef int (*esp_vfs_rmdir_op_t)(const char *name)

  rmdir without context pointer

typedef int (*esp_vfs_access_ctx_op_t)(void *ctx, const char *path, int amode)

  access with context pointer

typedef int (*esp_vfs_access_op_t)(const char *path, int amode)

  access without context pointer

typedef int (*esp_vfs_truncate_ctx_op_t)(void *ctx, const char *path, off_t length)

  truncate with context pointer

typedef int (*esp_vfs_truncate_op_t)(const char *path, off_t length)

  truncate without context pointer

typedef int (*esp_vfs_ftruncate_ctx_op_t)(void *ctx, int fd, off_t length)

  ftruncate with context pointer

typedef int (*esp_vfs_ftruncate_op_t)(int fd, off_t length)

  ftruncate without context pointer

typedef int (*esp_vfs_utime_ctx_op_t)(void *ctx, const char *path, const struct utimbuf *times)

  utime with context pointer

typedef int (*esp_vfs_utime_op_t)(const char *path, const struct utimbuf *times)

  utime without context pointer

typedef esp_err_t (*esp_vfs_start_select_op_t)(int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, esp_vfs_select_sem_t sem, void **end_select_args)

typedef int (*esp_vfs_socket_select_op_t)(int nfds, fd_set *readfds, fd_set *writefds, fd_set *errorfds, struct timeval *timeout)

typedef void (*esp_vfs_stop_socket_select_op_t)(void *sem)

typedef void (*esp_vfs_stop_socket_select_isr_op_t)(void *sem, BaseType_t *woken)

typedef void *(*esp_vfs_get_socket_select_semaphore_op_t)(void)

typedef esp_err_t (*esp_vfs_end_select_op_t)(void *end_select_args)

typedef ssize_t (*esp_vfs_write_ctx_op_t)(void *ctx, int fd, const void *data, size_t size)

  Write with context pointer

typedef ssize_t (*esp_vfs_write_op_t)(int fd, const void *data, size_t size)

  Write without context pointer

typedef off_t (*esp_vfs_lseek_ctx_op_t)(void *ctx, int fd, off_t size, int mode)

  Seek with context pointer

typedef off_t (*esp_vfs_lseek_op_t)(int fd, off_t size, int mode)

  Seek without context pointer

typedef ssize_t (*esp_vfs_read_ctx_op_t)(void *ctx, int fd, void *dst, size_t size)

  Read with context pointer

typedef ssize_t (*esp_vfs_read_op_t)(int fd, void *dst, size_t size)

  Read without context pointer

typedef ssize_t (*esp_vfs_pread_ctx_op_t)(void *ctx, int fd, void *dst, size_t size, off_t offset)

  pread with context pointer

typedef ssize_t (*esp_vfs_pread_op_t)(int fd, void *dst, size_t size, off_t offset)

  pread without context pointer

typedef ssize_t (*esp_vfs_pwrite_ctx_op_t)(void *ctx, int fd, const void *src, size_t size, off_t offset)

  pwrite with context pointer

typedef ssize_t (*esp_vfs_pwrite_op_t)(int fd, const void *src, size_t size, off_t offset)

  pwrite without context pointer

typedef int (*esp_vfs_open_ctx_op_t)(void *ctx, const char *path, int flags, int mode)

  open with context pointer

typedef int (*esp_vfs_open_op_t)(const char *path, int flags, int mode)

  open without context pointer

typedef int (*esp_vfs_close_ctx_op_t)(void *ctx, int fd)

  close with context pointer

typedef int (*esp_vfs_close_op_t)(int fd)

  close without context pointer

typedef int (*esp_vfs_fstat_ctx_op_t)(void *ctx, int fd, struct stat *st)

  fstat with context pointer

typedef int (*esp_vfs_fstat_op_t)(int fd, struct stat *st)

  fstat without context pointer

typedef int (*esp_vfs_fcntl_ctx_op_t)(void *ctx, int fd, int cmd, int arg)

  fcntl with context pointer

typedef int (*esp_vfs_fcntl_op_t)(int fd, int cmd, int arg)

  fcntl without context pointer

typedef int (*esp_vfs_ioctl_ctx_op_t)(void *ctx, int fd, int cmd, va_list args)

  ioctl with context pointer

typedef int (*esp_vfs_ioctl_op_t)(int fd, int cmd, va_list args)

  ioctl without context pointer

typedef int (*esp_vfs_fsync_ctx_op_t)(void *ctx, int fd)

  fsync with context pointer

typedef int (*esp_vfs_fsync_op_t)(int fd)

  fsync without context pointer

### Header File

- components/vfs/include/esp_vfs_dev.h

- This header file can be included with:

  >     #include "esp_vfs_dev.h"

- This header file is a part of the API provided by the `vfs` component. To declare that your component depends on `vfs`, add the following to your CMakeLists.txt:

  >     REQUIRES vfs

  > or

  >     PRIV_REQUIRES vfs

### Header File

- components/esp_driver_uart/include/driver/uart_vfs.h

- This header file can be included with:

  >     #include "driver/uart_vfs.h"

- This header file is a part of the API provided by the `esp_driver_uart` component. To declare that your component depends on `esp_driver_uart`, add the following to your CMakeLists.txt:

  >     REQUIRES esp_driver_uart

  > or

  >     PRIV_REQUIRES esp_driver_uart

### Functions

void uart_vfs_dev_register(void)

  Add /dev/uart virtual filesystem driver.

  This function is called from startup code to enable serial output

int uart_vfs_dev_port_set_rx_line_endings(int uart_num, esp_line_endings_t mode)

  Set the line endings expected to be received on specified UART.

  This specifies the conversion between line endings received on UART and newlines ('

  ', LF) passed into stdin:

  - ESP_LINE_ENDINGS_CRLF: convert CRLF to LF

  - ESP_LINE_ENDINGS_CR: convert CR to LF

  - ESP_LINE_ENDINGS_LF: no modification

  Note

  this function is not thread safe w.r.t. reading from UART

  Parameters:

    - uart_num -- the UART number

    - mode -- line endings to send to UART

  Returns:

    0 if succeeded, or -1 when an error (specified by errno) have occurred.

int uart_vfs_dev_port_set_tx_line_endings(int uart_num, esp_line_endings_t mode)

  Set the line endings to sent to specified UART.

  This specifies the conversion between newlines ('

  ', LF) on stdout and line endings sent over UART:

  - ESP_LINE_ENDINGS_CRLF: convert LF to CRLF

  - ESP_LINE_ENDINGS_CR: convert LF to CR

  - ESP_LINE_ENDINGS_LF: no modification

  Note

  this function is not thread safe w.r.t. writing to UART

  Parameters:

    - uart_num -- the UART number

    - mode -- line endings to send to UART

  Returns:

    0 if succeeded, or -1 when an error (specified by errno) have occurred.

void uart_vfs_dev_use_nonblocking(int uart_num)

  set VFS to use simple functions for reading and writing UART

  Read is non-blocking, write is busy waiting until TX FIFO has enough space. These functions are used by default.

  Parameters:

    uart_num -- UART peripheral number

void uart_vfs_dev_use_driver(int uart_num)

  set VFS to use UART driver for reading and writing

  Note

  Application must configure UART driver before calling these functions With these functions, read and write are blocking and interrupt-driven.

  Parameters:

    uart_num -- UART peripheral number

### Header File

- components/vfs/include/esp_vfs_eventfd.h

- This header file can be included with:

  >     #include "esp_vfs_eventfd.h"

- This header file is a part of the API provided by the `vfs` component. To declare that your component depends on `vfs`, add the following to your CMakeLists.txt:

  >     REQUIRES vfs

  > or

  >     PRIV_REQUIRES vfs

### Functions

esp_err_t esp_vfs_eventfd_register(const esp_vfs_eventfd_config_t *config)

  Registers the event vfs.

  Returns:

    ESP_OK if successful, ESP_ERR_NO_MEM if too many VFSes are registered.

esp_err_t esp_vfs_eventfd_unregister(void)

  Unregisters the event vfs.

  Returns:

    ESP_OK if successful, ESP_ERR_INVALID_STATE if VFS for given prefix hasn't been registered

int eventfd(unsigned int initval, int flags)

### Structures

struct esp_vfs_eventfd_config_t

  Eventfd vfs initialization settings.

  Public Members

  size_t max_fds

    The maximum number of eventfds supported

### Macros

EFD_SUPPORT_ISR

ESP_VFS_EVENTD_CONFIG_DEFAULT()

### Header File

- components/vfs/include/esp_vfs_null.h

- This header file can be included with:

  >     #include "esp_vfs_null.h"

- This header file is a part of the API provided by the `vfs` component. To declare that your component depends on `vfs`, add the following to your CMakeLists.txt:

  >     REQUIRES vfs

  > or

  >     PRIV_REQUIRES vfs

### Functions

esp_err_t esp_vfs_null_register(void)

  Register filesystem for /dev/null.

  Returns:

    ESP_OK on success; any other value indicates an error

Was this page helpful?

- Thank you! We received your feedback.
- If you have any comments, fill in Espressif Documentation Feedback Form.

- We value your feedback.
- Let us know how we can improve this page by filling in Espressif Documentation Feedback Form.