LCOV - code coverage report
Current view: top level - zephyr/fs - fs.h Coverage Total Hit
Test: new.info Lines: 98.5 % 66 65
Test Date: 2025-09-25 19:22:35

            Line data    Source code
       1            0 : /*
       2              :  * Copyright (c) 2016 Intel Corporation.
       3              :  * Copyright (c) 2020-2024 Nordic Semiconductor ASA
       4              :  *
       5              :  * SPDX-License-Identifier: Apache-2.0
       6              :  */
       7              : 
       8              : #ifndef ZEPHYR_INCLUDE_FS_FS_H_
       9              : #define ZEPHYR_INCLUDE_FS_FS_H_
      10              : 
      11              : #include <sys/types.h>
      12              : 
      13              : #include <zephyr/sys/dlist.h>
      14              : #include <zephyr/fs/fs_interface.h>
      15              : 
      16              : #ifdef __cplusplus
      17              : extern "C" {
      18              : #endif
      19              : 
      20              : /**
      21              :  * @brief File System APIs
      22              :  * @defgroup file_system_api File System APIs
      23              :  * @since 1.5
      24              :  * @version 1.0.0
      25              :  * @ingroup os_services
      26              :  * @{
      27              :  */
      28              : struct fs_file_system_t;
      29              : 
      30              : /**
      31              :  * @brief Enumeration for directory entry types
      32              :  */
      33            1 : enum fs_dir_entry_type {
      34              :         /** Identifier for file entry */
      35              :         FS_DIR_ENTRY_FILE = 0,
      36              :         /** Identifier for directory entry */
      37              :         FS_DIR_ENTRY_DIR
      38              : };
      39              : 
      40              : /** @brief Enumeration to uniquely identify file system types.
      41              :  *
      42              :  * Zephyr supports in-tree file systems and external ones.  Each
      43              :  * requires a unique identifier used to register the file system
      44              :  * implementation and to associate a mount point with the file system
      45              :  * type.  This anonymous enum defines global identifiers for the
      46              :  * in-tree file systems.
      47              :  *
      48              :  * External file systems should be registered using unique identifiers
      49              :  * starting at @c FS_TYPE_EXTERNAL_BASE.  It is the responsibility of
      50              :  * applications that use external file systems to ensure that these
      51              :  * identifiers are unique if multiple file system implementations are
      52              :  * used by the application.
      53              :  */
      54            1 : enum {
      55              :         /** Identifier for in-tree FatFS file system. */
      56              :         FS_FATFS = 0,
      57              : 
      58              :         /** Identifier for in-tree LittleFS file system. */
      59              :         FS_LITTLEFS,
      60              : 
      61              :         /** Identifier for in-tree Ext2 file system. */
      62              :         FS_EXT2,
      63              : 
      64              :         /** Identifier for in-tree Virtiofs file system. */
      65              :         FS_VIRTIOFS,
      66              : 
      67              :         /** Base identifier for external file systems. */
      68              :         FS_TYPE_EXTERNAL_BASE,
      69              : };
      70              : 
      71              : /** Flag prevents formatting device if requested file system not found */
      72            1 : #define FS_MOUNT_FLAG_NO_FORMAT BIT(0)
      73              : /** Flag makes mounted file system read-only */
      74            1 : #define FS_MOUNT_FLAG_READ_ONLY BIT(1)
      75              : /** Flag used in pre-defined mount structures that are to be mounted
      76              :  * on startup.
      77              :  *
      78              :  * This flag has no impact in user-defined mount structures.
      79              :  */
      80            1 : #define FS_MOUNT_FLAG_AUTOMOUNT BIT(2)
      81              : /** Flag requests file system driver to use Disk Access API. When the flag is
      82              :  * set to the fs_mount_t.flags prior to fs_mount call, a file system
      83              :  * needs to use the Disk Access API, otherwise mount callback for the driver
      84              :  * should return -ENOTSUP; when the flag is not set the file system driver
      85              :  * should use Flash API by default, unless it only supports Disc Access API.
      86              :  * When file system will use Disk Access API and the flag is not set, the mount
      87              :  * callback for the file system should set the flag on success.
      88              :  */
      89            1 : #define FS_MOUNT_FLAG_USE_DISK_ACCESS BIT(3)
      90              : 
      91              : /**
      92              :  * @brief File system mount info structure
      93              :  */
      94            1 : struct fs_mount_t {
      95              :         /** Entry for the fs_mount_list list */
      96            1 :         sys_dnode_t node;
      97              :         /** File system type */
      98            1 :         int type;
      99              :         /** Mount point directory name (ex: "/fatfs") */
     100            1 :         const char *mnt_point;
     101              :         /** Pointer to file system specific data */
     102            1 :         void *fs_data;
     103              :         /** Pointer to backend storage device */
     104            1 :         void *storage_dev;
     105              :         /* The following fields are filled by file system core */
     106              :         /** Length of Mount point string */
     107            1 :         size_t mountp_len;
     108              :         /** Pointer to File system interface of the mount point */
     109            1 :         const struct fs_file_system_t *fs;
     110              :         /** Mount flags */
     111            1 :         uint8_t flags;
     112              : };
     113              : 
     114              : /**
     115              :  * @brief Structure to receive file or directory information
     116              :  *
     117              :  * Used in functions that read the directory entries to get
     118              :  * file or directory information.
     119              :  */
     120            1 : struct fs_dirent {
     121              :         /**
     122              :          * File/directory type (FS_DIR_ENTRY_FILE or FS_DIR_ENTRY_DIR)
     123              :          */
     124            1 :         enum fs_dir_entry_type type;
     125              :         /** Name of file or directory */
     126            1 :         char name[MAX_FILE_NAME + 1];
     127              :         /** Size of file (0 if directory). */
     128            1 :         size_t size;
     129              : };
     130              : 
     131              : /**
     132              :  * @brief Structure to receive volume statistics
     133              :  *
     134              :  * Used to retrieve information about total and available space
     135              :  * in the volume.
     136              :  */
     137            1 : struct fs_statvfs {
     138              :         /** Optimal transfer block size */
     139            1 :         unsigned long f_bsize;
     140              :         /** Allocation unit size */
     141            1 :         unsigned long f_frsize;
     142              :         /** Size of FS in f_frsize units */
     143            1 :         unsigned long f_blocks;
     144              :         /** Number of free blocks */
     145            1 :         unsigned long f_bfree;
     146              : };
     147              : 
     148              : 
     149              : /**
     150              :  * @name fs_open open and creation mode flags
     151              :  * @{
     152              :  */
     153              : /** Open for read flag */
     154            1 : #define FS_O_READ       0x01
     155              : /** Open for write flag */
     156            1 : #define FS_O_WRITE      0x02
     157              : /** Open for read-write flag combination */
     158            1 : #define FS_O_RDWR       (FS_O_READ | FS_O_WRITE)
     159              : /** Bitmask for read and write flags */
     160            1 : #define FS_O_MODE_MASK  0x03
     161              : 
     162              : /** Create file if it does not exist */
     163            1 : #define FS_O_CREATE     0x10
     164              : /** Open/create file for append */
     165            1 : #define FS_O_APPEND     0x20
     166              : /** Truncate the file while opening */
     167            1 : #define FS_O_TRUNC      0x40
     168              : /** Bitmask for open/create flags */
     169            1 : #define FS_O_FLAGS_MASK 0x70
     170              : 
     171              : 
     172              : /** Bitmask for open flags */
     173            1 : #define FS_O_MASK       (FS_O_MODE_MASK | FS_O_FLAGS_MASK)
     174              : /**
     175              :  * @}
     176              :  */
     177              : 
     178              : /**
     179              :  * @name fs_seek whence parameter values
     180              :  * @{
     181              :  */
     182              : #ifndef FS_SEEK_SET
     183              : /** Seek from the beginning of file */
     184            1 : #define FS_SEEK_SET     0
     185              : #endif
     186              : #ifndef FS_SEEK_CUR
     187              : /** Seek from a current position */
     188            1 : #define FS_SEEK_CUR     1
     189              : #endif
     190              : #ifndef FS_SEEK_END
     191              : /** Seek from the end of file */
     192            1 : #define FS_SEEK_END     2
     193              : #endif
     194              : /**
     195              :  * @}
     196              :  */
     197              : 
     198              : /**
     199              :  * @brief Get the common mount flags for an fstab entry.
     200              : 
     201              :  * @param node_id the node identifier for a child entry in a
     202              :  * zephyr,fstab node.
     203              :  * @return a value suitable for initializing an fs_mount_t flags
     204              :  * member.
     205              :  */
     206            1 : #define FSTAB_ENTRY_DT_MOUNT_FLAGS(node_id)                             \
     207              :         ((DT_PROP(node_id, automount) ? FS_MOUNT_FLAG_AUTOMOUNT : 0)    \
     208              :          | (DT_PROP(node_id, read_only) ? FS_MOUNT_FLAG_READ_ONLY : 0)  \
     209              :          | (DT_PROP(node_id, no_format) ? FS_MOUNT_FLAG_NO_FORMAT : 0)  \
     210              :          | (DT_PROP(node_id, disk_access) ? FS_MOUNT_FLAG_USE_DISK_ACCESS : 0))
     211              : 
     212              : /**
     213              :  * @brief Get the mount-point from an fstab entry.
     214              :  *
     215              :  * @param node_id The node identifier for a child entry in a zephyr,fstab node.
     216              :  * @return The mount-point path.
     217              :  */
     218            1 : #define FSTAB_ENTRY_DT_MOUNT_POINT(node_id) \
     219              :         DT_PROP(node_id, mount_point)
     220              : 
     221              : /**
     222              :  * @brief Get the mount-point from an fstab entry.
     223              :  *
     224              :  * @param inst Instance number
     225              :  * @return The mount-point path.
     226              :  */
     227            1 : #define FSTAB_ENTRY_DT_INST_MOUNT_POINT(inst) \
     228              :         DT_INST_PROP(inst, mount_point)
     229              : 
     230              : /**
     231              :  * @brief The name under which a zephyr,fstab entry mount structure is
     232              :  * defined.
     233              :  *
     234              :  * @param node_id the node identifier for a child entry in a zephyr,fstab node.
     235              :  */
     236            1 : #define FS_FSTAB_ENTRY(node_id) _CONCAT(z_fsmp_, node_id)
     237              : 
     238              : /**
     239              :  * @brief Generate a declaration for the externally defined fstab
     240              :  * entry.
     241              :  *
     242              :  * This will evaluate to the name of a struct fs_mount_t object.
     243              :  *
     244              :  * @param node_id the node identifier for a child entry in a zephyr,fstab node.
     245              :  */
     246            1 : #define FS_FSTAB_DECLARE_ENTRY(node_id)         \
     247              :         extern struct fs_mount_t FS_FSTAB_ENTRY(node_id)
     248              : 
     249              : /**
     250              :  * @brief Initialize fs_file_t object
     251              :  *
     252              :  * Initializes the fs_file_t object; the function needs to be invoked
     253              :  * on object before first use with fs_open.
     254              :  *
     255              :  * @param zfp Pointer to file object
     256              :  *
     257              :  */
     258            1 : static inline void fs_file_t_init(struct fs_file_t *zfp)
     259              : {
     260              :         zfp->filep = NULL;
     261              :         zfp->mp = NULL;
     262              :         zfp->flags = 0;
     263              : }
     264              : 
     265              : /**
     266              :  * @brief Initialize fs_dir_t object
     267              :  *
     268              :  * Initializes the fs_dir_t object; the function needs to be invoked
     269              :  * on object before first use with fs_opendir.
     270              :  *
     271              :  * @param zdp Pointer to file object
     272              :  *
     273              :  */
     274            1 : static inline void fs_dir_t_init(struct fs_dir_t *zdp)
     275              : {
     276              :         zdp->dirp = NULL;
     277              :         zdp->mp = NULL;
     278              : }
     279              : 
     280              : /**
     281              :  * @brief Open or create file
     282              :  *
     283              :  * Opens or possibly creates a file and associates a stream with it.
     284              :  * Successfully opened file, when no longer in use, should be closed
     285              :  * with fs_close().
     286              :  *
     287              :  * @details
     288              :  * @p flags can be 0 or a binary combination of one or more of the following
     289              :  * identifiers:
     290              :  *   - @c FS_O_READ open for read
     291              :  *   - @c FS_O_WRITE open for write
     292              :  *   - @c FS_O_RDWR open for read/write (<tt>FS_O_READ | FS_O_WRITE</tt>)
     293              :  *   - @c FS_O_CREATE create file if it does not exist
     294              :  *   - @c FS_O_APPEND move to end of file before each write
     295              :  *   - @c FS_O_TRUNC truncate the file
     296              :  *
     297              :  * @warning If @p flags are set to 0 the function will open file, if it exists
     298              :  *          and is accessible, but you will have no read/write access to it.
     299              :  *
     300              :  * @param zfp Pointer to a file object
     301              :  * @param file_name The name of a file to open
     302              :  * @param flags The mode flags
     303              :  *
     304              :  * @retval 0 on success;
     305              :  * @retval -EBUSY when zfp is already used;
     306              :  * @retval -EINVAL when a bad file name is given;
     307              :  * @retval -EROFS when opening read-only file for write, or attempting to
     308              :  *         create a file on a system that has been mounted with the
     309              :  *         FS_MOUNT_FLAG_READ_ONLY flag;
     310              :  * @retval -ENOENT when the file does not exist at the path;
     311              :  * @retval -ENOTSUP when not implemented by underlying file system driver;
     312              :  * @retval -EACCES when trying to truncate a file without opening it for write.
     313              :  * @retval <0 an other negative errno code, depending on a file system back-end.
     314              :  */
     315            1 : int fs_open(struct fs_file_t *zfp, const char *file_name, fs_mode_t flags);
     316              : 
     317              : /**
     318              :  * @brief Close file
     319              :  *
     320              :  * Flushes the associated stream and closes the file.
     321              :  *
     322              :  * @param zfp Pointer to the file object
     323              :  *
     324              :  * @retval 0 on success;
     325              :  * @retval -ENOTSUP when not implemented by underlying file system driver;
     326              :  * @retval <0 a negative errno code on error.
     327              :  */
     328            1 : int fs_close(struct fs_file_t *zfp);
     329              : 
     330              : /**
     331              :  * @brief Unlink file
     332              :  *
     333              :  * Deletes the specified file or directory
     334              :  *
     335              :  * @param path Path to the file or directory to delete
     336              :  *
     337              :  * @retval 0 on success;
     338              :  * @retval -EINVAL when a bad file name is given;
     339              :  * @retval -EROFS if file is read-only, or when file system has been mounted
     340              :  *         with the FS_MOUNT_FLAG_READ_ONLY flag;
     341              :  * @retval -ENOTSUP when not implemented by underlying file system driver;
     342              :  * @retval <0 an other negative errno code on error.
     343              :  */
     344            1 : int fs_unlink(const char *path);
     345              : 
     346              : /**
     347              :  * @brief Rename file or directory
     348              :  *
     349              :  * Performs a rename and / or move of the specified source path to the
     350              :  * specified destination.  The source path can refer to either a file or a
     351              :  * directory.  All intermediate directories in the destination path must
     352              :  * already exist.  If the source path refers to a file, the destination path
     353              :  * must contain a full filename path, rather than just the new parent
     354              :  * directory.  If an object already exists at the specified destination path,
     355              :  * this function causes it to be unlinked prior to the rename (i.e., the
     356              :  * destination gets clobbered).
     357              :  * @note Current implementation does not allow moving files between mount
     358              :  * points.
     359              :  *
     360              :  * @param from The source path
     361              :  * @param to The destination path
     362              :  *
     363              :  * @retval 0 on success;
     364              :  * @retval -EINVAL when a bad file name is given, or when rename would cause move
     365              :  *         between mount points;
     366              :  * @retval -EROFS if file is read-only, or when file system has been mounted
     367              :  *         with the FS_MOUNT_FLAG_READ_ONLY flag;
     368              :  * @retval -ENOTSUP when not implemented by underlying file system driver;
     369              :  * @retval <0 an other negative errno code on error.
     370              :  */
     371            1 : int fs_rename(const char *from, const char *to);
     372              : 
     373              : /**
     374              :  * @brief Read file
     375              :  *
     376              :  * Reads up to @p size bytes of data to @p ptr pointed buffer, returns number
     377              :  * of bytes read.  A returned value may be lower than @p size if there were
     378              :  * fewer bytes available than requested.
     379              :  *
     380              :  * @param zfp Pointer to the file object
     381              :  * @param ptr Pointer to the data buffer
     382              :  * @param size Number of bytes to be read
     383              :  *
     384              :  * @retval >=0 a number of bytes read, on success;
     385              :  * @retval -EBADF when invoked on zfp that represents unopened/closed file;
     386              :  * @retval -ENOTSUP when not implemented by underlying file system driver;
     387              :  * @retval <0 a negative errno code on error.
     388              :  */
     389            1 : ssize_t fs_read(struct fs_file_t *zfp, void *ptr, size_t size);
     390              : 
     391              : /**
     392              :  * @brief Write file
     393              :  *
     394              :  * Attempts to write @p size number of bytes to the specified file.
     395              :  * If a negative value is returned from the function, the file pointer has not
     396              :  * been advanced.
     397              :  * If the function returns a non-negative number that is lower than @p size,
     398              :  * the global @c errno variable should be checked for an error code,
     399              :  * as the device may have no free space for data.
     400              :  *
     401              :  * @param zfp Pointer to the file object
     402              :  * @param ptr Pointer to the data buffer
     403              :  * @param size Number of bytes to be written
     404              :  *
     405              :  * @retval >=0 a number of bytes written, on success;
     406              :  * @retval -EBADF when invoked on zfp that represents unopened/closed file;
     407              :  * @retval -ENOTSUP when not implemented by underlying file system driver;
     408              :  * @retval <0 an other negative errno code on error.
     409              :  */
     410            1 : ssize_t fs_write(struct fs_file_t *zfp, const void *ptr, size_t size);
     411              : 
     412              : /**
     413              :  * @brief Seek file
     414              :  *
     415              :  * Moves the file position to a new location in the file. The @p offset is added
     416              :  * to file position based on the @p whence parameter.
     417              :  *
     418              :  * @param zfp Pointer to the file object
     419              :  * @param offset Relative location to move the file pointer to
     420              :  * @param whence Relative location from where offset is to be calculated.
     421              :  * - @c FS_SEEK_SET for the beginning of the file;
     422              :  * - @c FS_SEEK_CUR for the current position;
     423              :  * - @c FS_SEEK_END for the end of the file.
     424              :  *
     425              :  * @retval 0 on success;
     426              :  * @retval -EBADF when invoked on zfp that represents unopened/closed file;
     427              :  * @retval -ENOTSUP if not supported by underlying file system driver;
     428              :  * @retval <0 an other negative errno code on error.
     429              :  */
     430            1 : int fs_seek(struct fs_file_t *zfp, off_t offset, int whence);
     431              : 
     432              : /**
     433              :  * @brief Get current file position.
     434              :  *
     435              :  * Retrieves and returns the current position in the file stream.
     436              :  *
     437              :  * @param zfp Pointer to the file object
     438              :  *
     439              :  * @retval >= 0 a current position in file;
     440              :  * @retval -EBADF when invoked on zfp that represents unopened/closed file;
     441              :  * @retval -ENOTSUP if not supported by underlying file system driver;
     442              :  * @retval <0 an other negative errno code on error.
     443              :  *
     444              :  * The current revision does not validate the file object.
     445              :  */
     446            1 : off_t fs_tell(struct fs_file_t *zfp);
     447              : 
     448              : /**
     449              :  * @brief Truncate or extend an open file to a given size
     450              :  *
     451              :  * Truncates the file to the new length if it is shorter than the current
     452              :  * size of the file. Expands the file if the new length is greater than the
     453              :  * current size of the file. The expanded region would be filled with zeroes.
     454              :  *
     455              :  * @note In the case of expansion, if the volume got full during the
     456              :  * expansion process, the function will expand to the maximum possible length
     457              :  * and return success.  Caller should check if the expanded size matches the
     458              :  * requested length.
     459              :  *
     460              :  * @param zfp Pointer to the file object
     461              :  * @param length New size of the file in bytes
     462              :  *
     463              :  * @retval 0 on success;
     464              :  * @retval -EBADF when invoked on zfp that represents unopened/closed file;
     465              :  * @retval -ENOTSUP when not implemented by underlying file system driver;
     466              :  * @retval <0 an other negative errno code on error.
     467              :  */
     468            1 : int fs_truncate(struct fs_file_t *zfp, off_t length);
     469              : 
     470              : /**
     471              :  * @brief Flush cached write data buffers of an open file
     472              :  *
     473              :  * The function flushes the cache of an open file; it can be invoked to ensure
     474              :  * data gets written to the storage media immediately, e.g. to avoid data loss
     475              :  * in case if power is removed unexpectedly.
     476              :  * @note Closing a file will cause caches to be flushed correctly so the
     477              :  * function need not be called when the file is being closed.
     478              :  *
     479              :  * @param zfp Pointer to the file object
     480              :  *
     481              :  * @retval 0 on success;
     482              :  * @retval -EBADF when invoked on zfp that represents unopened/closed file;
     483              :  * @retval -ENOTSUP when not implemented by underlying file system driver;
     484              :  * @retval <0 a negative errno code on error.
     485              :  */
     486            1 : int fs_sync(struct fs_file_t *zfp);
     487              : 
     488              : /**
     489              :  * @brief Directory create
     490              :  *
     491              :  * Creates a new directory using specified path.
     492              :  *
     493              :  * @param path Path to the directory to create
     494              :  *
     495              :  * @retval 0 on success;
     496              :  * @retval -EEXIST if entry of given name exists;
     497              :  * @retval -EROFS if @p path is within read-only directory, or when
     498              :  *         file system has been mounted with the FS_MOUNT_FLAG_READ_ONLY flag;
     499              :  * @retval -ENOTSUP when not implemented by underlying file system driver;
     500              :  * @retval <0 an other negative errno code on error
     501              :  */
     502            1 : int fs_mkdir(const char *path);
     503              : 
     504              : /**
     505              :  * @brief Directory open
     506              :  *
     507              :  * Opens an existing directory specified by the path.
     508              :  *
     509              :  * @param zdp Pointer to the directory object
     510              :  * @param path Path to the directory to open
     511              :  *
     512              :  * @retval 0 on success;
     513              :  * @retval -EINVAL when a bad directory path is given;
     514              :  * @retval -EBUSY when zdp is already used;
     515              :  * @retval -ENOTSUP when not implemented by underlying file system driver;
     516              :  * @retval <0 a negative errno code on error.
     517              :  */
     518            1 : int fs_opendir(struct fs_dir_t *zdp, const char *path);
     519              : 
     520              : /**
     521              :  * @brief Directory read entry
     522              :  *
     523              :  * Reads directory entries of an open directory. In end-of-dir condition,
     524              :  * the function will return 0 and set the <tt>entry->name[0]</tt> to 0.
     525              :  *
     526              :  * @note: Most existing underlying file systems do not generate POSIX
     527              :  * special directory entries "." or "..".  For consistency the
     528              :  * abstraction layer will remove these from lower layer results so
     529              :  * higher layers see consistent results.
     530              :  *
     531              :  * @param zdp Pointer to the directory object
     532              :  * @param entry Pointer to zfs_dirent structure to read the entry into
     533              :  *
     534              :  * @retval 0 on success or end-of-dir;
     535              :  * @retval -ENOENT when no such directory found;
     536              :  * @retval -ENOTSUP when not implemented by underlying file system driver;
     537              :  * @retval <0 a negative errno code on error.
     538              :  */
     539            1 : int fs_readdir(struct fs_dir_t *zdp, struct fs_dirent *entry);
     540              : 
     541              : /**
     542              :  * @brief Directory close
     543              :  *
     544              :  * Closes an open directory.
     545              :  *
     546              :  * @param zdp Pointer to the directory object
     547              :  *
     548              :  * @retval 0 on success;
     549              :  * @retval -ENOTSUP when not implemented by underlying file system driver;
     550              :  * @retval <0 a negative errno code on error.
     551              :  */
     552            1 : int fs_closedir(struct fs_dir_t *zdp);
     553              : 
     554              : /**
     555              :  * @brief Mount filesystem
     556              :  *
     557              :  * Perform steps needed for mounting a file system like
     558              :  * calling the file system specific mount function and adding
     559              :  * the mount point to mounted file system list.
     560              :  *
     561              :  * @note Current implementation of ELM FAT driver allows only following mount
     562              :  * points: "/RAM:","/NAND:","/CF:","/SD:","/SD2:","/USB:","/USB2:","/USB3:"
     563              :  * or mount points that consist of single digit, e.g: "/0:", "/1:" and so forth.
     564              :  *
     565              :  * @param mp Pointer to the fs_mount_t structure.  Referenced object
     566              :  *           is not changed if the mount operation failed.
     567              :  *           A reference is captured in the fs infrastructure if the
     568              :  *           mount operation succeeds, and the application must not
     569              :  *           mutate the structure contents until fs_unmount is
     570              :  *           successfully invoked on the same pointer.
     571              :  *
     572              :  * @retval 0 on success;
     573              :  * @retval -ENOENT when file system type has not been registered;
     574              :  * @retval -ENOTSUP when not supported by underlying file system driver;
     575              :  *         when @c FS_MOUNT_FLAG_USE_DISK_ACCESS is set but driver does not
     576              :  *         support it.
     577              :  * @retval -EROFS if system requires formatting but @c FS_MOUNT_FLAG_READ_ONLY
     578              :  *         has been set;
     579              :  * @retval <0 an other negative errno code on error.
     580              :  */
     581            1 : int fs_mount(struct fs_mount_t *mp);
     582              : 
     583              : /**
     584              :  * @brief Unmount filesystem
     585              :  *
     586              :  * Perform steps needed to unmount a file system like
     587              :  * calling the file system specific unmount function and removing
     588              :  * the mount point from mounted file system list.
     589              :  *
     590              :  * @param mp Pointer to the fs_mount_t structure
     591              :  *
     592              :  * @retval 0 on success;
     593              :  * @retval -EINVAL if no system has been mounted at given mount point;
     594              :  * @retval -ENOTSUP when not supported by underlying file system driver;
     595              :  * @retval <0 an other negative errno code on error.
     596              :  */
     597            1 : int fs_unmount(struct fs_mount_t *mp);
     598              : 
     599              : /**
     600              :  * @brief Get path of mount point at index
     601              :  *
     602              :  * This function iterates through the list of mount points and returns
     603              :  * the directory name of the mount point at the given @p index.
     604              :  * On success @p index is incremented and @p name is set to the mount directory
     605              :  * name.  If a mount point with the given @p index does not exist, @p name will
     606              :  * be set to @c NULL.
     607              :  *
     608              :  * @param index Pointer to mount point index
     609              :  * @param name Pointer to pointer to path name
     610              :  *
     611              :  * @retval 0 on success;
     612              :  * @retval -ENOENT if there is no mount point with given index.
     613              :  */
     614            1 : int fs_readmount(int *index, const char **name);
     615              : 
     616              : /**
     617              :  * @brief File or directory status
     618              :  *
     619              :  * Checks the status of a file or directory specified by the @p path.
     620              :  * @note The file on a storage device may not be updated until it is closed.
     621              :  *
     622              :  * @param path Path to the file or directory
     623              :  * @param entry Pointer to the zfs_dirent structure to fill if the file or
     624              :  * directory exists.
     625              :  *
     626              :  * @retval 0 on success;
     627              :  * @retval -EINVAL when a bad directory or file name is given;
     628              :  * @retval -ENOENT when no such directory or file is found;
     629              :  * @retval -ENOTSUP when not supported by underlying file system driver;
     630              :  * @retval <0 negative errno code on error.
     631              :  */
     632            1 : int fs_stat(const char *path, struct fs_dirent *entry);
     633              : 
     634              : /**
     635              :  * @brief Retrieves statistics of the file system volume
     636              :  *
     637              :  * Returns the total and available space in the file system volume.
     638              :  *
     639              :  * @param path Path to the mounted directory
     640              :  * @param stat Pointer to the zfs_statvfs structure to receive the fs
     641              :  * statistics.
     642              :  *
     643              :  * @retval 0 on success;
     644              :  * @retval -EINVAL when a bad path to a directory, or a file, is given;
     645              :  * @retval -ENOTSUP when not implemented by underlying file system driver;
     646              :  * @retval <0 an other negative errno code on error.
     647              :  */
     648            1 : int fs_statvfs(const char *path, struct fs_statvfs *stat);
     649              : 
     650              : /**
     651              :  * @brief Create fresh file system
     652              :  *
     653              :  * @param fs_type Type of file system to create.
     654              :  * @param dev_id Id of storage device.
     655              :  * @param cfg Backend dependent init object. If NULL then default configuration is used.
     656              :  * @param flags Additional flags for file system implementation.
     657              :  *
     658              :  * @retval 0 on success;
     659              :  * @retval <0 negative errno code on error.
     660              :  */
     661            1 : int fs_mkfs(int fs_type, uintptr_t dev_id, void *cfg, int flags);
     662              : 
     663              : /**
     664              :  * @brief Register a file system
     665              :  *
     666              :  * Register file system with virtual file system.
     667              :  * Number of allowed file system types to be registered is controlled with the
     668              :  * CONFIG_FILE_SYSTEM_MAX_TYPES Kconfig option.
     669              :  *
     670              :  * @param type Type of file system (ex: @c FS_FATFS)
     671              :  * @param fs Pointer to File system
     672              :  *
     673              :  * @retval 0 on success;
     674              :  * @retval -EALREADY when a file system of a given type has already been registered;
     675              :  * @retval -ENOSCP when there is no space left, in file system registry, to add
     676              :  *         this file system type.
     677              :  */
     678            1 : int fs_register(int type, const struct fs_file_system_t *fs);
     679              : 
     680              : /**
     681              :  * @brief Unregister a file system
     682              :  *
     683              :  * Unregister file system from virtual file system.
     684              :  *
     685              :  * @param type Type of file system (ex: @c FS_FATFS)
     686              :  * @param fs Pointer to File system
     687              :  *
     688              :  * @retval 0 on success;
     689              :  * @retval -EINVAL when file system of a given type has not been registered.
     690              :  */
     691            1 : int fs_unregister(int type, const struct fs_file_system_t *fs);
     692              : 
     693              : /**
     694              :  * @}
     695              :  */
     696              : 
     697              : 
     698              : #ifdef __cplusplus
     699              : }
     700              : #endif
     701              : 
     702              : #endif /* ZEPHYR_INCLUDE_FS_FS_H_ */
        

Generated by: LCOV version 2.0-1