mynewt-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ad...@apache.org
Subject [10/11] incubator-mynewt-site git commit: File system documentation added. Closes pull request #27
Date Fri, 04 Mar 2016 08:41:44 GMT
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/45398e5f/mkdocs/search_index.json
----------------------------------------------------------------------
diff --git a/mkdocs/search_index.json b/mkdocs/search_index.json
index 7671675..da7cff5 100644
--- a/mkdocs/search_index.json
+++ b/mkdocs/search_index.json
@@ -3386,559 +3386,929 @@
             "title": "boot_write_status"
         }, 
         {
-            "location": "/os/modules/filesystem/", 
-            "text": "Filesystem\n\n\nMynewt provides a Flash File System abstraction layer (fs) to allow you to swap out the default Newtron File System (nffs) with a different file system of your choice. \n\n\nDescription\n\n\nThe default file system used in the Mynewt OS is the Newtron Flash File System (nffs). Hence the \nnffs\n egg description lists \nlibs/fs\n as a dependency. \n\n\negg.name: libs/nffs\negg.vers: 0.1\negg.identities: NFFS\negg.deps:\n    - libs/os\n    - libs/fs\n    - libs/testutil\n    - hw/hal\n\n\n\n\nIf the user wishes to use a different flash file system (say, \"ownffs\"), the directory containing \"ownffs\" code must include the \negg.yml\n file stating the dependency on \nlibs/fs\n listed as shown above. \"ownffs\" uses the \nlibs/fs\n API available in mynewt, thus minimizing changes to other parts of the project.\n\n\nNote that this generic file system (\nfs\n) API does not expose any file system detection, initialization, and formatting functions. The
 se function calls remain specific to the chosen file system. For example, Project Slinky uses the default Newtron File System (nffs) and therefore calls nffs_init() to initialize the nffs memory and data structures before any other file system operations are attempted. As shown below, the egg for Project Slinky includes the \nlibs/imgmgr\n egg which in turn includes the \nlibs/bootutil\n egg. The egg description for \nlibs/bootutil\n specifies \nfs/nffs\n as a dependency.\n\n\n\n    egg.name: project/slinky\n    egg.vers: 0.1\n    egg.deps:\n        - libs/os\n        - libs/console/full\n        - libs/shell\n        - libs/newtmgr\n        - libs/imgmgr\n        - sys/config\n        - sys/log\n        - sys/stats\n\n\n\n\n\n    egg.name: libs/imgmgr\n    egg.vers: 0.1\n    egg.deps:\n        - libs/newtmgr\n        - libs/bootutil\n    egg.deps.FS:\n        - fs/fs\n    egg.cflags.FS: -DFS_PRESENT\n\n\n\n\n\n    egg.name: libs/bootutil\n    egg.vers: 0.1 \n    egg.deps: \n       
  - fs/nffs\n        - libs/os \n        - libs/testutil\n        - hw/hal\n\n\n\n\nData Structures\n\n\nAPI\n\n\n   struct fs_file;\n\n\n\n\nThe functions available in this OS feature are:\n\n\n\n\nfs_open\n\n\nfs_close\n\n\nfs_read\n\n\nfs_write\n\n\nfs_seek\n\n\nfs_getpos\n\n\nfs_filelen\n\n\nfs_unlink\n\n\nfs_rename\n\n\nfs_mkdir\n\n\nfs_opendir\n\n\nfs_readdir\n\n\nfs_closedir\n\n\nfs_dirent_name\n\n\nfs_dirent_is_dir\n\n\n\n\nAdditional file system utilities that bundle some of the basic functions above are:\n\n\n\n\nfsutil_read_file\n\n\nfsutil_write_file\n\n\n\n\nAPI Reference\n\n\n\n\n fs_open \n\n\n    int\n    fs_open(const char *filename, uint8_t access_flags, struct fs_file **out_file);\n\n\n\n\nOpens a file at the specified path.  The result of opening a nonexistent file depends on the access flags specified.  All intermediate directories must already exist.\n\n\nThe mode strings passed to fopen() map to fs_open()'s access flags as follows:\n\n\n    \nr\n  -  FS_ACCESS_
 READ\n    \nr+\n -  FS_ACCESS_READ | FS_ACCESS_WRITE\n    \nw\n  -  FS_ACCESS_WRITE | FS_ACCESS_TRUNCATE\n    \nw+\n -  FS_ACCESS_READ | FS_ACCESS_WRITE | FS_ACCESS_TRUNCATE\n    \na\n  -  FS_ACCESS_WRITE | FS_ACCESS_APPEND\n    \na+\n -  FS_ACCESS_READ | FS_ACCESS_WRITE | FS_ACCESS_APPEND\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfilename\n\n\nPointer to the file created at the path of the specified filename\n\n\n\n\n\n\naccess_flags\n\n\nFlags controlling file access; see above table\n\n\n\n\n\n\nout_file\n\n\nOn success, a pointer to the newly-created file handle gets written here\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nnonzero on failure\n\n\n\n\nNotes\n\n\nThere is no concept of current working directory. Therefore all file names should start with '/'.\n\n\nExample\n\n\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n\n fs_close \n\n\n   int\n   fs_close(struct fs_file *file)\n\n\n\n\nCloses the specified file an
 d invalidates the file handle.  If the file has already been unlinked, and this is the last open handle to the file, this operation causes the file to be deleted from disk.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfile\n\n\nPointer to the file to close\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nnonzero on failure\n\n\n\n\nNotes\n\n\nDon't use file handle after closing the file.\n\n\nExample\n\n\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n\n fs_read \n\n\n   int\n   fs_read(struct fs_file *file, uint32_t len, void *out_data, uint32_t *out_len);\n\n\n\n\nReads data from the specified file.  If more data is requested than remains in the file, all available data is retrieved. Function returns in \nout_len\n the actual number of bytes read (less or equal to \nlen\n).\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfile\n\n\nPointer to the the file to read from\n\n\n\n\n\n\nlen\n\n\nThe number
  of bytes to attempt to read\n\n\n\n\n\n\nout_data\n\n\nThe destination buffer to read into\n\n\n\n\n\n\nout_len\n\n\nOn success, the number of bytes actually read gets written here.  Pass null if you don't care.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nnonzero on failure\n\n\n\n\nNotes\n\n\nThis type of short read results in a success return code.\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n\n fs_write \n\n\n   int\n   fs_write(struct fs_file *file, const void *data, int len);\n\n\n\n\nWrites the supplied data to the current offset of the specified file handle.  \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfile\n\n\nPointer to the file to write to\n\n\n\n\n\n\ndata\n\n\nThe data to write\n\n\n\n\n\n\nlen\n\n\nThe number of bytes to write\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nnonzero on failure\n\n\n\n\nNotes\n\n\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n fs_see
 k \n\n\n   int\n   fs_seek(struct fs_file *file, uint32_t offset);\n\n\n\n\nPositions a file's read and write pointer at the specified offset.  The offset is expressed as the number of bytes from the start of the file (i.e., seeking to offset 0 places the pointer at the first byte in the file). \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfile\n\n\nPointer to the file to reposition\n\n\n\n\n\n\noffset\n\n\nThe 0-based file offset to seek to\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nnonzero on failure\n\n\n\n\nNotes\n\n\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n fs_getpos \n\n\n   uint32_t\n   fs_getpos(const struct fs_file *file);\n\n\n\n\nRetrieves the current read and write position of the specified open file. \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfile\n\n\nPointer to the file to query\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\nThe file offset, in bytes\n\n\n\n\n
 Notes\n\n\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n fs_filelen \n\n\n   int\n   fs_filelen(const struct fs_file *file, uint32_t *out_len);\n\n\n\n\n\nRetrieves the current length of the specified open file.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfile\n\n\nPointer to the file to query\n\n\n\n\n\n\nout_len\n\n\nOn success, the number of bytes in the file gets written here\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nnonzero on failure\n\n\n\n\nNotes\n\n\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n fs_unlink \n\n\n   int\n   fs_unlink(const char *filename);\n\n\n\n\n\nUnlinks the file or directory at the specified path.  If the path refers to a directory, all the directory's descendants are recursively unlinked.  Any open file handles refering to an unlinked file remain valid, and can be read from and written to.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n
 \n\n\n\nfilename\n\n\nThe path of the file or directory to unlink\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nnonzero on failure\n\n\n\n\nNotes\n\n\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n fs_rename \n\n\n   int\n   fs_rename(const char *from, const char *to);\n\n\n\n\n\nPerforms a rename and / or move of the specified source path to the specified destination.  \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfrom\n\n\nThe source path\n\n\n\n\n\n\nto\n\n\nThe destination path\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nnonzero on failure\n\n\n\n\nNotes\n\n\nThe source path can refer to either a file or a directory.  All intermediate directories in the destination path must already exist.  If the source path refers to a file, the destination path must contain a full filename path, rather than just the new parent directory.  If an object already exists at the specified destination path, this func
 tion causes it to be unlinked prior to the rename (i.e., the destination gets clobbered).\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n fs_mkdir \n\n\n   int\n   fs_mkdir(const char *path);\n\n\n\n\n\nCreates the directory represented by the specified path.  \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\npath\n\n\nPointer to the directory to create\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nnonzero on failure.\n\n\n\n\nNotes\n\n\nAll intermediate directories must already exist.  The specified path must start with a '/' character.\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n fs_opendir \n\n\n\n   int\n   fs_opendir(const char *path, struct fs_dir **out_dir);\n\n\n\n\n\nOpens the directory at the specified path.  The directory's contents can be read with subsequent calls to fs_readdir().  When you are done with the directory handle, close it with fs_closedir(). \n\n\nArguments\n\n\n\n\n\n\n\n
 \nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\npath\n\n\nPointer to the directory to create\n\n\n\n\n\n\nout_dir\n\n\nOn success, points to the directory handle\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nFS_ENOENT if the specified directory does not exist (no such file)\n\n\nOther nonzero on error.\n\n\n\n\nNotes\n\n\nUnlinking files from the directory while it is open may result in unpredictable behavior.  New files can be created inside the directory.\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n fs_readdir \n\n\n   int\n   fs_readdir(struct fs_dir *dir, struct fs_dirent **out_dirent);\n\n\n\n\n\nReads the next entry in an open directory. \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\ndir\n\n\nThe directory handle to read from\n\n\n\n\n\n\nout_dirent\n\n\nOn success, points to the next child entry in the specified directory\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nFS_ENOENT if there are n
 o more entries in the parent directory\n\n\nOther nonzero on error.\n\n\n\n\nNotes\n\n\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n fs_closedir \n\n\n   int\n   fs_closedir(struct fs_dir *dir);\n\n\n\n\n\nCloses the specified directory handle. \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\ndir\n\n\nPointer to the directory to close\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nnonzero on failure\n\n\n\n\nNotes\n\n\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n fs_dirent_name \n\n\n   int\n   fs_dirent_name(const struct fs_dirent *dirent, size_t max_len,\n     char *out_name, uint8_t *out_name_len);\n\n\n\n\n\nRetrieves the filename of the specified directory entry. \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\ndirent\n\n\nPointer to the directory entry to query\n\n\n\n\n\n\nmax_len\n\n\nSize of the \"out_name\" character buffer\n\n\n\n\n\n\nout_name\n\n\nOn su
 ccess, the entry's filename is written here; always null-terminated\n\n\n\n\n\n\nout_name_len\n\n\nOn success, contains the actual length of the filename, NOT including the null-terminator\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nnonzero on failure\n\n\n\n\nNotes\n\n\nThe retrieved filename is always null-terminated.  To ensure enough space to hold the full filename plus a null-termintor, a destination buffer of size  (filename max length + 1) should be used.\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n fs_dirent_is_dir \n\n\n   int\n   fs_dirent_is_dir(const struct fs_dirent *dirent);\n\n\n\n\n\nTells you whether the specified directory entry is a sub-directory or a regular file. \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\ndirent\n\n\nPointer to the directory entry to query\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n1: The entry is a directory\n\n\n0: The entry is a regular file.\n\n\n\n\nNotes\n\n\n\n\nEx
 ample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n fsutil_read_file \n\n\n   int\n   fsutil_read_file(const char *path, uint32_t offset, uint32_t len, void *dst,\n                    uint32_t *out_len);\n\n\n\n\nCalls fs_open(), fs_read(), and fs_close() to open a file at the specified path, retrieve data from the file starting from the specified offset, and close the file and invalidate the file handle.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\npath\n\n\nPointer to the directory entry to query\n\n\n\n\n\n\noffset\n\n\nPosition of the file's read pointer\n\n\n\n\n\n\nlen\n\n\nNumber of bytes to attempt to read\n\n\n\n\n\n\ndst\n\n\nDestination buffer to read into\n\n\n\n\n\n\nout_len\n\n\nOn success, the number of bytes actually read gets written here.  Pass null if you don't care.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nnonzero on failure\n\n\n\n\nNotes\n\n\nThis is a convenience function. You can use it if the file
  is small (caller has enough buffer space to hold all the file contents in memory).\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n fsutil_write_file \n\n\n   int\n   fsutil_write_file(const char *path, const void *data, uint32_t len);\n\n\n\n\nCalls fs_open(), fs_write(), and fs_close() to open a file at the specified path, write the supplied data to the current offset of the specified file handle, and close the file and invalidate the file handle.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\npath\n\n\nPointer to the file to write to\n\n\n\n\n\n\ndata\n\n\nThe data to write\n\n\n\n\n\n\nlen\n\n\nThe number of bytes to write\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nnonzero on failure\n\n\n\n\nNotes\n\n\n\n\nExample\n\n\n\n\nInsert the code snippet here", 
-            "title": "File System Abstraction"
+            "location": "/os/modules/fs/fs/fs/", 
+            "text": "File System Abstraction\n\n\nMynewt provides a file system abstraction layer (\nfs/fs\n) to allow client code to be file system agnostic.  By accessing the file system via the \nfs/fs\n API, client code can perform file system operations without being tied to a particular implementation.  When possible, library code should use the \nfs/fs\n API rather than accessing the underlying file system directly.\n\n\nDescription\n\n\nApplications should aim to minimize the amount of code which depends on a particular file system implementation.  When possible, only depend on the \nfs/fs\n package.  In the simplest case, the only code which needs to know which file system is in use is the code which initializes the file system.  In terms of the Mynewt hierarchy, the \nproject\n package must depend on a specific file system package, while \nlibrary\n packages should only depend on \nfs/fs\n.\n\n\nThe following example illustrates how file system dependencies should be manag
 ed.  In the slinky application, the project is responsible for initializing the file system, so it depends on a concrete file system package called \nfs/nffs\n (Newtron Flash File System). The project explicitly initializes nffs via calls to \nnffs_init()\n, \nnffs_detect()\n and \nnffs_format()\n.\n\n\n# project/slinky/pkg.yml\n\npkg.name: project/slinky\npkg.vers: 0.8.0\npkg.deps:\n    - fs/nffs\n\n# [...]\n\n\n\n\n// project/slinky/src/main.c\n\n#include \nnffs/nffs.h\n\n\nint\nmain(int argc, char **argv)\n{\n    int rc;\n    int cnt;\n    struct nffs_area_desc descs[NFFS_AREA_MAX];\n\n    rc = nffs_init();\n    assert(rc == 0);\n\n    cnt = NFFS_AREA_MAX;\n    rc = flash_area_to_nffs_desc(FLASH_AREA_NFFS, \ncnt, descs);\n    assert(rc == 0);\n    if (nffs_detect(descs) == FS_ECORRUPT) {\n        rc = nffs_format(descs);\n        assert(rc == 0);\n    }\n    // [...]\n}\n\n\n\n\nOn the other hand, code which uses the file system after it has been initialized need only depend on \
 nfs/fs\n.  For example, the \nlibs/imgmgr\n package is a library which provides firmware upload and download functionality via the use of a file system.  This library is only used after the main project has initialized the file system, and therefore only depends on the \nfs/fs\n package.\n\n\n# libs/imgmgr/pkg.yml\npkg.name: libs/imgmgr\npkg.vers: 0.8.0\npkg.deps:\n    - fs/fs\n\n# [...]\n\n\n\n\nThe \nlibs/imgmgr\n package uses the \nfs/fs\n API for all file system operations.\n\n\nThread Safety\n\n\nAll \nfs/fs\n functions are thread safe.\n\n\nHeader Files\n\n\nAll code which uses the \nfs/fs\n package needs to include the following header:\n\n\n#include \nfs/fs.h\n\n\n\n\n\nData Structures\n\n\nAll \nfs/fs\n data structures are opaque to client code.\n\n\nstruct fs_file;\nstruct fs_dir;\nstruct fs_dirent;\n\n\n\n\nAPI\n\n\nFunctions in \nfs/fs\n that indicate success or failure do so with the following set of return codes:\n\n\n\n\nReturn Codes\n\n\n\n\nThe functions available i
 n this OS feature are:\n\n\n\n\nfs_close\n\n\nfs_closedir\n\n\nfs_dirent_is_dir\n\n\nfs_dirent_name\n\n\nfs_filelen\n\n\nfs_getpos\n\n\nfs_mkdir\n\n\nfs_open\n\n\nfs_opendir\n\n\nfs_read\n\n\nfs_readdir\n\n\nfs_rename\n\n\nfs_seek\n\n\nfs_unlink\n\n\nfs_write\n\n\n\n\nAdditional file system utilities that bundle some of the basic functions above are:\n\n\n\n\nfsutil_read_file\n\n\nfsutil_write_file", 
+            "title": "Overview"
         }, 
         {
-            "location": "/os/modules/filesystem/#filesystem", 
-            "text": "Mynewt provides a Flash File System abstraction layer (fs) to allow you to swap out the default Newtron File System (nffs) with a different file system of your choice.", 
-            "title": "Filesystem"
+            "location": "/os/modules/fs/fs/fs/#file-system-abstraction", 
+            "text": "Mynewt provides a file system abstraction layer ( fs/fs ) to allow client code to be file system agnostic.  By accessing the file system via the  fs/fs  API, client code can perform file system operations without being tied to a particular implementation.  When possible, library code should use the  fs/fs  API rather than accessing the underlying file system directly.", 
+            "title": "File System Abstraction"
         }, 
         {
-            "location": "/os/modules/filesystem/#description", 
-            "text": "The default file system used in the Mynewt OS is the Newtron Flash File System (nffs). Hence the  nffs  egg description lists  libs/fs  as a dependency.   egg.name: libs/nffs\negg.vers: 0.1\negg.identities: NFFS\negg.deps:\n    - libs/os\n    - libs/fs\n    - libs/testutil\n    - hw/hal  If the user wishes to use a different flash file system (say, \"ownffs\"), the directory containing \"ownffs\" code must include the  egg.yml  file stating the dependency on  libs/fs  listed as shown above. \"ownffs\" uses the  libs/fs  API available in mynewt, thus minimizing changes to other parts of the project.  Note that this generic file system ( fs ) API does not expose any file system detection, initialization, and formatting functions. These function calls remain specific to the chosen file system. For example, Project Slinky uses the default Newtron File System (nffs) and therefore calls nffs_init() to initialize the nffs memory and data structures before any other fil
 e system operations are attempted. As shown below, the egg for Project Slinky includes the  libs/imgmgr  egg which in turn includes the  libs/bootutil  egg. The egg description for  libs/bootutil  specifies  fs/nffs  as a dependency.  \n    egg.name: project/slinky\n    egg.vers: 0.1\n    egg.deps:\n        - libs/os\n        - libs/console/full\n        - libs/shell\n        - libs/newtmgr\n        - libs/imgmgr\n        - sys/config\n        - sys/log\n        - sys/stats  \n    egg.name: libs/imgmgr\n    egg.vers: 0.1\n    egg.deps:\n        - libs/newtmgr\n        - libs/bootutil\n    egg.deps.FS:\n        - fs/fs\n    egg.cflags.FS: -DFS_PRESENT  \n    egg.name: libs/bootutil\n    egg.vers: 0.1 \n    egg.deps: \n        - fs/nffs\n        - libs/os \n        - libs/testutil\n        - hw/hal", 
+            "location": "/os/modules/fs/fs/fs/#description", 
+            "text": "Applications should aim to minimize the amount of code which depends on a particular file system implementation.  When possible, only depend on the  fs/fs  package.  In the simplest case, the only code which needs to know which file system is in use is the code which initializes the file system.  In terms of the Mynewt hierarchy, the  project  package must depend on a specific file system package, while  library  packages should only depend on  fs/fs .  The following example illustrates how file system dependencies should be managed.  In the slinky application, the project is responsible for initializing the file system, so it depends on a concrete file system package called  fs/nffs  (Newtron Flash File System). The project explicitly initializes nffs via calls to  nffs_init() ,  nffs_detect()  and  nffs_format() .  # project/slinky/pkg.yml\n\npkg.name: project/slinky\npkg.vers: 0.8.0\npkg.deps:\n    - fs/nffs\n\n# [...]  // project/slinky/src/main.c\n\n#includ
 e  nffs/nffs.h \n\nint\nmain(int argc, char **argv)\n{\n    int rc;\n    int cnt;\n    struct nffs_area_desc descs[NFFS_AREA_MAX];\n\n    rc = nffs_init();\n    assert(rc == 0);\n\n    cnt = NFFS_AREA_MAX;\n    rc = flash_area_to_nffs_desc(FLASH_AREA_NFFS,  cnt, descs);\n    assert(rc == 0);\n    if (nffs_detect(descs) == FS_ECORRUPT) {\n        rc = nffs_format(descs);\n        assert(rc == 0);\n    }\n    // [...]\n}  On the other hand, code which uses the file system after it has been initialized need only depend on  fs/fs .  For example, the  libs/imgmgr  package is a library which provides firmware upload and download functionality via the use of a file system.  This library is only used after the main project has initialized the file system, and therefore only depends on the  fs/fs  package.  # libs/imgmgr/pkg.yml\npkg.name: libs/imgmgr\npkg.vers: 0.8.0\npkg.deps:\n    - fs/fs\n\n# [...]  The  libs/imgmgr  package uses the  fs/fs  API for all file system operations.", 
             "title": "Description"
         }, 
         {
-            "location": "/os/modules/filesystem/#data-structures", 
-            "text": "", 
+            "location": "/os/modules/fs/fs/fs/#thread-safety", 
+            "text": "All  fs/fs  functions are thread safe.", 
+            "title": "Thread Safety"
+        }, 
+        {
+            "location": "/os/modules/fs/fs/fs/#header-files", 
+            "text": "All code which uses the  fs/fs  package needs to include the following header:  #include  fs/fs.h", 
+            "title": "Header Files"
+        }, 
+        {
+            "location": "/os/modules/fs/fs/fs/#data-structures", 
+            "text": "All  fs/fs  data structures are opaque to client code.  struct fs_file;\nstruct fs_dir;\nstruct fs_dirent;", 
             "title": "Data Structures"
         }, 
         {
-            "location": "/os/modules/filesystem/#api", 
-            "text": "struct fs_file;  The functions available in this OS feature are:   fs_open  fs_close  fs_read  fs_write  fs_seek  fs_getpos  fs_filelen  fs_unlink  fs_rename  fs_mkdir  fs_opendir  fs_readdir  fs_closedir  fs_dirent_name  fs_dirent_is_dir   Additional file system utilities that bundle some of the basic functions above are:   fsutil_read_file  fsutil_write_file", 
+            "location": "/os/modules/fs/fs/fs/#api", 
+            "text": "Functions in  fs/fs  that indicate success or failure do so with the following set of return codes:   Return Codes   The functions available in this OS feature are:   fs_close  fs_closedir  fs_dirent_is_dir  fs_dirent_name  fs_filelen  fs_getpos  fs_mkdir  fs_open  fs_opendir  fs_read  fs_readdir  fs_rename  fs_seek  fs_unlink  fs_write   Additional file system utilities that bundle some of the basic functions above are:   fsutil_read_file  fsutil_write_file", 
             "title": "API"
         }, 
         {
-            "location": "/os/modules/filesystem/#api-reference", 
-            "text": "", 
-            "title": "API Reference"
+            "location": "/os/modules/fs/fs/fs_return_codes/", 
+            "text": "fs/fs Return Codes\n\n\nFunctions in \nfs/fs\n that indicate success or failure do so with the following set of return codes:\n\n\n\n\n\n\n\n\nReturn code\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nFS_EOK\n\n\nSuccess\n\n\n\n\n\n\nFS_ECORRUPT\n\n\nFile system corrupt\n\n\n\n\n\n\nFS_EHW\n\n\nError accessing storage medium\n\n\n\n\n\n\nFS_EOFFSET\n\n\nInvalid offset\n\n\n\n\n\n\nFS_EINVAL\n\n\nInvalid argument\n\n\n\n\n\n\nFS_ENOMEM\n\n\nInsufficient memory\n\n\n\n\n\n\nFS_ENOENT\n\n\nNo such file or directory\n\n\n\n\n\n\nFS_EEMPTY\n\n\nSpecified region is empty (internal only)\n\n\n\n\n\n\nFS_EFULL\n\n\nDisk full\n\n\n\n\n\n\nFS_EUNEXP\n\n\nDisk contains unexpected metadata\n\n\n\n\n\n\nFS_EOS\n\n\nOS error\n\n\n\n\n\n\nFS_EEXIST\n\n\nFile or directory already exists\n\n\n\n\n\n\nFS_EACCESS\n\n\nOperation prohibited by file open mode\n\n\n\n\n\n\nFS_EUNINIT\n\n\nFile system not initialized\n\n\n\n\n\n\n\n\nHeader file\n\n\n#include \nfs/fs.h", 
+            "title": "Return Codes"
+        }, 
+        {
+            "location": "/os/modules/fs/fs/fs_return_codes/#fsfs-return-codes", 
+            "text": "Functions in  fs/fs  that indicate success or failure do so with the following set of return codes:     Return code  Description      FS_EOK  Success    FS_ECORRUPT  File system corrupt    FS_EHW  Error accessing storage medium    FS_EOFFSET  Invalid offset    FS_EINVAL  Invalid argument    FS_ENOMEM  Insufficient memory    FS_ENOENT  No such file or directory    FS_EEMPTY  Specified region is empty (internal only)    FS_EFULL  Disk full    FS_EUNEXP  Disk contains unexpected metadata    FS_EOS  OS error    FS_EEXIST  File or directory already exists    FS_EACCESS  Operation prohibited by file open mode    FS_EUNINIT  File system not initialized", 
+            "title": "fs/fs Return Codes"
+        }, 
+        {
+            "location": "/os/modules/fs/fs/fs_return_codes/#header-file", 
+            "text": "#include  fs/fs.h", 
+            "title": "Header file"
+        }, 
+        {
+            "location": "/os/modules/fs/fs/fs_ops/", 
+            "text": "struct fs_ops\n\n\nstruct fs_ops {\n    int (*f_open)(const char *filename, uint8_t access_flags,\n              struct fs_file **out_file);\n    int (*f_close)(struct fs_file *file);\n    int (*f_read)(struct fs_file *file, uint32_t len, void *out_data,\n      uint32_t *out_len);\n    int (*f_write)(struct fs_file *file, const void *data, int len);\n\n    int (*f_seek)(struct fs_file *file, uint32_t offset);\n    uint32_t (*f_getpos)(const struct fs_file *file);\n    int (*f_filelen)(const struct fs_file *file, uint32_t *out_len);\n\n    int (*f_unlink)(const char *filename);\n    int (*f_rename)(const char *from, const char *to);\n    int (*f_mkdir)(const char *path);\n\n    int (*f_opendir)(const char *path, struct fs_dir **out_dir);\n    int (*f_readdir)(struct fs_dir *dir, struct fs_dirent **out_dirent);\n    int (*f_closedir)(struct fs_dir *dir);\n\n    int (*f_dirent_name)(const struct fs_dirent *dirent, size_t max_len,\n      char *out_name, uint8_t *out
 _name_len);\n    int (*f_dirent_is_dir)(const struct fs_dirent *dirent);\n\n    const char *f_name;\n};\n\n\n\n\nThis data structure consists of a set of function pointers.  Each function pointer corresponds to a file system operation.  When registering a file system with the abstraction layer, each function pointer must be pointed at the corresponding routine in the custom file system package.\n\n\nThe required behavior of each corresponding function is documented in the \nfile system abstraction layer API\n.\n\n\nHeader file\n\n\n#include \nfs/fs_if.h", 
+            "title": "struct fs_ops"
+        }, 
+        {
+            "location": "/os/modules/fs/fs/fs_ops/#struct-fs95ops", 
+            "text": "struct fs_ops {\n    int (*f_open)(const char *filename, uint8_t access_flags,\n              struct fs_file **out_file);\n    int (*f_close)(struct fs_file *file);\n    int (*f_read)(struct fs_file *file, uint32_t len, void *out_data,\n      uint32_t *out_len);\n    int (*f_write)(struct fs_file *file, const void *data, int len);\n\n    int (*f_seek)(struct fs_file *file, uint32_t offset);\n    uint32_t (*f_getpos)(const struct fs_file *file);\n    int (*f_filelen)(const struct fs_file *file, uint32_t *out_len);\n\n    int (*f_unlink)(const char *filename);\n    int (*f_rename)(const char *from, const char *to);\n    int (*f_mkdir)(const char *path);\n\n    int (*f_opendir)(const char *path, struct fs_dir **out_dir);\n    int (*f_readdir)(struct fs_dir *dir, struct fs_dirent **out_dirent);\n    int (*f_closedir)(struct fs_dir *dir);\n\n    int (*f_dirent_name)(const struct fs_dirent *dirent, size_t max_len,\n      char *out_name, uint8_t *out_name_len);\n    in
 t (*f_dirent_is_dir)(const struct fs_dirent *dirent);\n\n    const char *f_name;\n};  This data structure consists of a set of function pointers.  Each function pointer corresponds to a file system operation.  When registering a file system with the abstraction layer, each function pointer must be pointed at the corresponding routine in the custom file system package.  The required behavior of each corresponding function is documented in the  file system abstraction layer API .", 
+            "title": "struct fs_ops"
+        }, 
+        {
+            "location": "/os/modules/fs/fs/fs_ops/#header-file", 
+            "text": "#include  fs/fs_if.h", 
+            "title": "Header file"
+        }, 
+        {
+            "location": "/os/modules/fs/fs/fs_close/", 
+            "text": "fs_close\n\n\nint fs_close(struct fs_file *file)\n\n\n\n\nCloses the specified file and invalidates the file handle.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfile\n\n\nPointer to the file to close\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nFS error code\n on failure\n\n\n\n\nNotes\n\n\nIf the file has already been unlinked, and the file has no other open handles, the \nfs_close()\n function causes the file to be deleted from the disk.\n\n\nHeader file\n\n\n#include \nfs/fs.h\n\n\n\n\n\nExample\n\n\nThe below code opens the file \n/settings/config.txt\n for reading, reads some data, and then closes the file.\n\n\nint\nread_config(void)\n{\n    struct fs_file *file;\n    uint32_t bytes_read;\n    uint8_t buf[16];\n    int rc;\n\n    /* Open the file for reading. */\n    rc = fs_open(\n/settings/config.txt\n, FS_ACCESS_READ, \nfile);\n    if (rc != 0) {\n        return -1;\n    }\n\n    /* Read up to 16 bytes 
 from the file. */\n    rc = fs_read(file, sizeof buf, buf, \nbytes_read);\n    if (rc == 0) {\n        /* buf now contains up to 16 bytes of file data. */\n        console_printf(\nread %u bytes\\n\n, bytes_read)\n    }\n\n    /* Close the file. */\n    fs_close(file);\n\n    return rc == 0 ? 0 : -1;\n}", 
+            "title": "fs_close"
         }, 
         {
-            "location": "/os/modules/filesystem/#fs_open", 
-            "text": "int\n    fs_open(const char *filename, uint8_t access_flags, struct fs_file **out_file);  Opens a file at the specified path.  The result of opening a nonexistent file depends on the access flags specified.  All intermediate directories must already exist.  The mode strings passed to fopen() map to fs_open()'s access flags as follows:       r   -  FS_ACCESS_READ\n     r+  -  FS_ACCESS_READ | FS_ACCESS_WRITE\n     w   -  FS_ACCESS_WRITE | FS_ACCESS_TRUNCATE\n     w+  -  FS_ACCESS_READ | FS_ACCESS_WRITE | FS_ACCESS_TRUNCATE\n     a   -  FS_ACCESS_WRITE | FS_ACCESS_APPEND\n     a+  -  FS_ACCESS_READ | FS_ACCESS_WRITE | FS_ACCESS_APPEND", 
-            "title": " fs_open "
+            "location": "/os/modules/fs/fs/fs_close/#fs95close", 
+            "text": "int fs_close(struct fs_file *file)  Closes the specified file and invalidates the file handle.", 
+            "title": "fs_close"
         }, 
         {
-            "location": "/os/modules/filesystem/#arguments", 
-            "text": "Arguments  Description      filename  Pointer to the file created at the path of the specified filename    access_flags  Flags controlling file access; see above table    out_file  On success, a pointer to the newly-created file handle gets written here", 
+            "location": "/os/modules/fs/fs/fs_close/#arguments", 
+            "text": "Arguments  Description      file  Pointer to the file to close", 
             "title": "Arguments"
         }, 
         {
-            "location": "/os/modules/filesystem/#returned-values", 
-            "text": "0 on success  nonzero on failure", 
+            "location": "/os/modules/fs/fs/fs_close/#returned-values", 
+            "text": "0 on success  FS error code  on failure", 
             "title": "Returned values"
         }, 
         {
-            "location": "/os/modules/filesystem/#notes", 
-            "text": "There is no concept of current working directory. Therefore all file names should start with '/'.", 
+            "location": "/os/modules/fs/fs/fs_close/#notes", 
+            "text": "If the file has already been unlinked, and the file has no other open handles, the  fs_close()  function causes the file to be deleted from the disk.", 
             "title": "Notes"
         }, 
         {
-            "location": "/os/modules/filesystem/#example", 
-            "text": "Insert the code snippet here", 
+            "location": "/os/modules/fs/fs/fs_close/#header-file", 
+            "text": "#include  fs/fs.h", 
+            "title": "Header file"
+        }, 
+        {
+            "location": "/os/modules/fs/fs/fs_close/#example", 
+            "text": "The below code opens the file  /settings/config.txt  for reading, reads some data, and then closes the file.  int\nread_config(void)\n{\n    struct fs_file *file;\n    uint32_t bytes_read;\n    uint8_t buf[16];\n    int rc;\n\n    /* Open the file for reading. */\n    rc = fs_open( /settings/config.txt , FS_ACCESS_READ,  file);\n    if (rc != 0) {\n        return -1;\n    }\n\n    /* Read up to 16 bytes from the file. */\n    rc = fs_read(file, sizeof buf, buf,  bytes_read);\n    if (rc == 0) {\n        /* buf now contains up to 16 bytes of file data. */\n        console_printf( read %u bytes\\n , bytes_read)\n    }\n\n    /* Close the file. */\n    fs_close(file);\n\n    return rc == 0 ? 0 : -1;\n}", 
             "title": "Example"
         }, 
         {
-            "location": "/os/modules/filesystem/#fs_close", 
-            "text": "int\n   fs_close(struct fs_file *file)  Closes the specified file and invalidates the file handle.  If the file has already been unlinked, and this is the last open handle to the file, this operation causes the file to be deleted from disk.", 
-            "title": " fs_close "
+            "location": "/os/modules/fs/fs/fs_closedir/", 
+            "text": "fs_closedir\n\n\nint fs_closedir(struct fs_dir *dir)\n\n\n\n\nCloses the specified directory handle. \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\ndir\n\n\nThe name of the directory to close\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nFS error code\n on failure\n\n\n\n\nHeader file\n\n\n#include \nfs/fs.h\n\n\n\n\n\nExample\n\n\nThis example iterates through the contents of a directory, printing the name of each child node.  When the traversal is complete, the code closes the directory handle.\n\n\nint\ntraverse_dir(const char *dirname)\n{\n    struct fs_dirent *dirent;\n    struct fs_dir *dir;\n    char buf[64];\n    uint8_t name_len;\n    int rc;\n\n    rc = fs_opendir(dirname, \ndir);\n    if (rc != 0) {\n        return -1;\n    }\n\n    /* Iterate through the parent directory, printing the name of each child\n     * entry.  The loop only terminates via a function return.\n     */\n    while (1) {\n        /*
  Retrieve the next child node. */\n        rc = fs_readdir(dir, \ndirent); \n        if (rc == FS_ENOENT) {\n            /* Traversal complete. */\n            return 0;\n        } else if (rc != 0) {\n            /* Unexpected error. */\n            return -1;\n        }\n\n        /* Read the child node's name from the file system. */\n        rc = fs_dirent_name(dirent, sizeof buf, buf, \nname_len);\n        if (rc != 0) {\n            return -1;\n        }\n\n        /* Print the child node's name to the console. */\n        if (fs_dirent_is_dir(dirent)) {\n            console_printf(\n dir: \n);\n        } else {\n            console_printf(\nfile: \n);\n        }\n        console_printf(\n%s\\n\n, buf);\n    }\n}", 
+            "title": "fs_closedir"
         }, 
         {
-            "location": "/os/modules/filesystem/#arguments_1", 
-            "text": "Arguments  Description      file  Pointer to the file to close", 
+            "location": "/os/modules/fs/fs/fs_closedir/#fs95closedir", 
+            "text": "int fs_closedir(struct fs_dir *dir)  Closes the specified directory handle.", 
+            "title": "fs_closedir"
+        }, 
+        {
+            "location": "/os/modules/fs/fs/fs_closedir/#arguments", 
+            "text": "Arguments  Description      dir  The name of the directory to close", 
             "title": "Arguments"
         }, 
         {
-            "location": "/os/modules/filesystem/#returned-values_1", 
-            "text": "0 on success  nonzero on failure", 
+            "location": "/os/modules/fs/fs/fs_closedir/#returned-values", 
+            "text": "0 on success  FS error code  on failure", 
             "title": "Returned values"
         }, 
         {
-            "location": "/os/modules/filesystem/#notes_1", 
-            "text": "Don't use file handle after closing the file.", 
-            "title": "Notes"
+            "location": "/os/modules/fs/fs/fs_closedir/#header-file", 
+            "text": "#include  fs/fs.h", 
+            "title": "Header file"
         }, 
         {
-            "location": "/os/modules/filesystem/#example_1", 
-            "text": "Insert the code snippet here", 
+            "location": "/os/modules/fs/fs/fs_closedir/#example", 
+            "text": "This example iterates through the contents of a directory, printing the name of each child node.  When the traversal is complete, the code closes the directory handle.  int\ntraverse_dir(const char *dirname)\n{\n    struct fs_dirent *dirent;\n    struct fs_dir *dir;\n    char buf[64];\n    uint8_t name_len;\n    int rc;\n\n    rc = fs_opendir(dirname,  dir);\n    if (rc != 0) {\n        return -1;\n    }\n\n    /* Iterate through the parent directory, printing the name of each child\n     * entry.  The loop only terminates via a function return.\n     */\n    while (1) {\n        /* Retrieve the next child node. */\n        rc = fs_readdir(dir,  dirent); \n        if (rc == FS_ENOENT) {\n            /* Traversal complete. */\n            return 0;\n        } else if (rc != 0) {\n            /* Unexpected error. */\n            return -1;\n        }\n\n        /* Read the child node's name from the file system. */\n        rc = fs_dirent_name(dirent, sizeof buf, 
 buf,  name_len);\n        if (rc != 0) {\n            return -1;\n        }\n\n        /* Print the child node's name to the console. */\n        if (fs_dirent_is_dir(dirent)) {\n            console_printf(  dir:  );\n        } else {\n            console_printf( file:  );\n        }\n        console_printf( %s\\n , buf);\n    }\n}", 
             "title": "Example"
         }, 
         {
-            "location": "/os/modules/filesystem/#fs_read", 
-            "text": "int\n   fs_read(struct fs_file *file, uint32_t len, void *out_data, uint32_t *out_len);  Reads data from the specified file.  If more data is requested than remains in the file, all available data is retrieved. Function returns in  out_len  the actual number of bytes read (less or equal to  len ).", 
-            "title": " fs_read "
+            "location": "/os/modules/fs/fs/fs_dirent_is_dir/", 
+            "text": "fs_dirent_is_dir\n\n\nint fs_dirent_is_dir(const struct fs_dirent *dirent)\n\n\n\n\nTells you whether the specified directory entry is a sub-directory or a regular file. \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\ndirent\n\n\nPointer to the directory entry to query\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n1: The entry is a directory\n\n\n0: The entry is a regular file.\n\n\n\n\nHeader file\n\n\n#include \nfs/fs.h\n\n\n\n\n\nExample\n\n\nThis example iterates through the contents of a directory, printing the name of each child node.  When the traversal is complete, the code closes the directory handle.\n\n\nint\ntraverse_dir(const char *dirname)\n{\n    struct fs_dirent *dirent;\n    struct fs_dir *dir;\n    char buf[64];\n    uint8_t name_len;\n    int rc;\n\n    rc = fs_opendir(dirname, \ndir);\n    if (rc != 0) {\n        return -1;\n    }\n\n    /* Iterate through the parent directory, printing the name of each child\n   
   * entry.  The loop only terminates via a function return.\n     */\n    while (1) {\n        /* Retrieve the next child node. */\n        rc = fs_readdir(dir, \ndirent); \n        if (rc == FS_ENOENT) {\n            /* Traversal complete. */\n            return 0;\n        } else if (rc != 0) {\n            /* Unexpected error. */\n            return -1;\n        }\n\n        /* Read the child node's name from the file system. */\n        rc = fs_dirent_name(dirent, sizeof buf, buf, \nname_len);\n        if (rc != 0) {\n            return -1;\n        }\n\n        /* Print the child node's name to the console. */\n        if (fs_dirent_is_dir(dirent)) {\n            console_printf(\n dir: \n);\n        } else {\n            console_printf(\nfile: \n);\n        }\n        console_printf(\n%s\\n\n, buf);\n    }\n}", 
+            "title": "fs_dirent_is_dir"
         }, 
         {
-            "location": "/os/modules/filesystem/#arguments_2", 
-            "text": "Arguments  Description      file  Pointer to the the file to read from    len  The number of bytes to attempt to read    out_data  The destination buffer to read into    out_len  On success, the number of bytes actually read gets written here.  Pass null if you don't care.", 
+            "location": "/os/modules/fs/fs/fs_dirent_is_dir/#fs95dirent95is95dir", 
+            "text": "int fs_dirent_is_dir(const struct fs_dirent *dirent)  Tells you whether the specified directory entry is a sub-directory or a regular file.", 
+            "title": "fs_dirent_is_dir"
+        }, 
+        {
+            "location": "/os/modules/fs/fs/fs_dirent_is_dir/#arguments", 
+            "text": "Arguments  Description      dirent  Pointer to the directory entry to query", 
             "title": "Arguments"
         }, 
         {
-            "location": "/os/modules/filesystem/#returned-values_2", 
-            "text": "0 on success  nonzero on failure", 
+            "location": "/os/modules/fs/fs/fs_dirent_is_dir/#returned-values", 
+            "text": "1: The entry is a directory  0: The entry is a regular file.", 
             "title": "Returned values"
         }, 
         {
-            "location": "/os/modules/filesystem/#notes_2", 
-            "text": "This type of short read results in a success return code.", 
-            "title": "Notes"
+            "location": "/os/modules/fs/fs/fs_dirent_is_dir/#header-file", 
+            "text": "#include  fs/fs.h", 
+            "title": "Header file"
         }, 
         {
-            "location": "/os/modules/filesystem/#example_2", 
-            "text": "Insert the code snippet here", 
+            "location": "/os/modules/fs/fs/fs_dirent_is_dir/#example", 
+            "text": "This example iterates through the contents of a directory, printing the name of each child node.  When the traversal is complete, the code closes the directory handle.  int\ntraverse_dir(const char *dirname)\n{\n    struct fs_dirent *dirent;\n    struct fs_dir *dir;\n    char buf[64];\n    uint8_t name_len;\n    int rc;\n\n    rc = fs_opendir(dirname,  dir);\n    if (rc != 0) {\n        return -1;\n    }\n\n    /* Iterate through the parent directory, printing the name of each child\n     * entry.  The loop only terminates via a function return.\n     */\n    while (1) {\n        /* Retrieve the next child node. */\n        rc = fs_readdir(dir,  dirent); \n        if (rc == FS_ENOENT) {\n            /* Traversal complete. */\n            return 0;\n        } else if (rc != 0) {\n            /* Unexpected error. */\n            return -1;\n        }\n\n        /* Read the child node's name from the file system. */\n        rc = fs_dirent_name(dirent, sizeof buf, 
 buf,  name_len);\n        if (rc != 0) {\n            return -1;\n        }\n\n        /* Print the child node's name to the console. */\n        if (fs_dirent_is_dir(dirent)) {\n            console_printf(  dir:  );\n        } else {\n            console_printf( file:  );\n        }\n        console_printf( %s\\n , buf);\n    }\n}", 
             "title": "Example"
         }, 
         {
-            "location": "/os/modules/filesystem/#fs_write", 
-            "text": "int\n   fs_write(struct fs_file *file, const void *data, int len);  Writes the supplied data to the current offset of the specified file handle.", 
-            "title": " fs_write "
+            "location": "/os/modules/fs/fs/fs_dirent_name/", 
+            "text": "fs_dirent_name\n\n\nint fs_dirent_name(const struct fs_dirent *dirent, size_t max_len,\n                   char *out_name, uint8_t *out_name_len)\n\n\n\n\nRetrieves the filename of the specified directory entry. \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\ndirent\n\n\nPointer to the directory entry to query\n\n\n\n\n\n\nmax_len\n\n\nSize of the \"out_name\" character buffer\n\n\n\n\n\n\nout_name\n\n\nOn success, the entry's filename is written here; always null-terminated\n\n\n\n\n\n\nout_name_len\n\n\nOn success, contains the actual length of the filename, NOT including the null-terminator\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nFS error code\n on failure\n\n\n\n\nNotes\n\n\nThe retrieved filename is always null-terminated.  To ensure enough space to hold the full filename plus a null-termintor, a destination buffer of size \nfilename-max-length + 1\n should be used.\n\n\nHeader file\n\n\n#include \nfs/fs.
 h\n\n\n\n\n\nExample\n\n\nThis example iterates through the contents of a directory, printing the name of each child node.  When the traversal is complete, the code closes the directory handle.\n\n\nint\ntraverse_dir(const char *dirname)\n{\n    struct fs_dirent *dirent;\n    struct fs_dir *dir;\n    char buf[64];\n    uint8_t name_len;\n    int rc;\n\n    rc = fs_opendir(dirname, \ndir);\n    if (rc != 0) {\n        return -1;\n    }\n\n    /* Iterate through the parent directory, printing the name of each child\n     * entry.  The loop only terminates via a function return.\n     */\n    while (1) {\n        /* Retrieve the next child node. */\n        rc = fs_readdir(dir, \ndirent); \n        if (rc == FS_ENOENT) {\n            /* Traversal complete. */\n            return 0;\n        } else if (rc != 0) {\n            /* Unexpected error. */\n            return -1;\n        }\n\n        /* Read the child node's name from the file system. */\n        rc = fs_dirent_name(dirent, s
 izeof buf, buf, \nname_len);\n        if (rc != 0) {\n            return -1;\n        }\n\n        /* Print the child node's name to the console. */\n        if (fs_dirent_is_dir(dirent)) {\n            console_printf(\n dir: \n);\n        } else {\n            console_printf(\nfile: \n);\n        }\n        console_printf(\n%s\\n\n, buf);\n    }\n}", 
+            "title": "fs_dirent_name"
         }, 
         {
-            "location": "/os/modules/filesystem/#arguments_3", 
-            "text": "Arguments  Description      file  Pointer to the file to write to    data  The data to write    len  The number of bytes to write", 
+            "location": "/os/modules/fs/fs/fs_dirent_name/#fs95dirent95name", 
+            "text": "int fs_dirent_name(const struct fs_dirent *dirent, size_t max_len,\n                   char *out_name, uint8_t *out_name_len)  Retrieves the filename of the specified directory entry.", 
+            "title": "fs_dirent_name"
+        }, 
+        {
+            "location": "/os/modules/fs/fs/fs_dirent_name/#arguments", 
+            "text": "Arguments  Description      dirent  Pointer to the directory entry to query    max_len  Size of the \"out_name\" character buffer    out_name  On success, the entry's filename is written here; always null-terminated    out_name_len  On success, contains the actual length of the filename, NOT including the null-terminator", 
             "title": "Arguments"
         }, 
         {
-            "location": "/os/modules/filesystem/#returned-values_3", 
-            "text": "0 on success  nonzero on failure", 
+            "location": "/os/modules/fs/fs/fs_dirent_name/#returned-values", 
+            "text": "0 on success  FS error code  on failure", 
             "title": "Returned values"
         }, 
         {
-            "location": "/os/modules/filesystem/#notes_3", 
-            "text": "", 
+            "location": "/os/modules/fs/fs/fs_dirent_name/#notes", 
+            "text": "The retrieved filename is always null-terminated.  To ensure enough space to hold the full filename plus a null-termintor, a destination buffer of size  filename-max-length + 1  should be used.", 
             "title": "Notes"
         }, 
         {
-            "location": "/os/modules/filesystem/#example_3", 
-            "text": "Insert the code snippet here", 
+            "location": "/os/modules/fs/fs/fs_dirent_name/#header-file", 
+            "text": "#include  fs/fs.h", 
+            "title": "Header file"
+        }, 
+        {
+            "location": "/os/modules/fs/fs/fs_dirent_name/#example", 
+            "text": "This example iterates through the contents of a directory, printing the name of each child node.  When the traversal is complete, the code closes the directory handle.  int\ntraverse_dir(const char *dirname)\n{\n    struct fs_dirent *dirent;\n    struct fs_dir *dir;\n    char buf[64];\n    uint8_t name_len;\n    int rc;\n\n    rc = fs_opendir(dirname,  dir);\n    if (rc != 0) {\n        return -1;\n    }\n\n    /* Iterate through the parent directory, printing the name of each child\n     * entry.  The loop only terminates via a function return.\n     */\n    while (1) {\n        /* Retrieve the next child node. */\n        rc = fs_readdir(dir,  dirent); \n        if (rc == FS_ENOENT) {\n            /* Traversal complete. */\n            return 0;\n        } else if (rc != 0) {\n            /* Unexpected error. */\n            return -1;\n        }\n\n        /* Read the child node's name from the file system. */\n        rc = fs_dirent_name(dirent, sizeof buf, 
 buf,  name_len);\n        if (rc != 0) {\n            return -1;\n        }\n\n        /* Print the child node's name to the console. */\n        if (fs_dirent_is_dir(dirent)) {\n            console_printf(  dir:  );\n        } else {\n            console_printf( file:  );\n        }\n        console_printf( %s\\n , buf);\n    }\n}", 
             "title": "Example"
         }, 
         {
-            "location": "/os/modules/filesystem/#fs_seek", 
-            "text": "int\n   fs_seek(struct fs_file *file, uint32_t offset);  Positions a file's read and write pointer at the specified offset.  The offset is expressed as the number of bytes from the start of the file (i.e., seeking to offset 0 places the pointer at the first byte in the file).", 
-            "title": " fs_seek "
+            "location": "/os/modules/fs/fs/fs_filelen/", 
+            "text": "fs_filelen\n\n\nint fs_filelen(const struct fs_file *file, uint32_t *out_len)\n\n\n\n\nRetrieves the current length of the specified open file.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfile\n\n\nPointer to the file to query\n\n\n\n\n\n\nout_len\n\n\nOn success, the number of bytes in the file gets written here\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nFS error code\n on failure\n\n\n\n\nHeader file\n\n\n#include \nfs/fs.h\n\n\n\n\n\nExample\n\n\nint\nwrite_config(void)\n{\n    struct fs_file *file;\n    int rc;\n\n    /* If the file doesn't exist, create it.  If it does exist, truncate it to\n     * zero bytes.\n     */\n    rc = fs_open(\n/settings/config.txt\n, FS_ACCESS_WRITE | FS_ACCESS_TRUNCATE,\n                 \nfile);\n    if (rc == 0) {\n        /* Write 5 bytes of data to the file. */\n        rc = fs_write(file, \nhello\n, 5);\n        if (rc == 0) {\n            /* The file should now contain 
 exactly five bytes. */\n            assert(fs_filelen(file) == 5);\n        }\n\n        /* Close the file. */\n        fs_close(file);\n    }\n\n    return rc == 0 ? 0 : -1;\n}", 
+            "title": "fs_filelen"
         }, 
         {
-            "location": "/os/modules/filesystem/#arguments_4", 
-            "text": "Arguments  Description      file  Pointer to the file to reposition    offset  The 0-based file offset to seek to", 
+            "location": "/os/modules/fs/fs/fs_filelen/#fs95filelen", 
+            "text": "int fs_filelen(const struct fs_file *file, uint32_t *out_len)  Retrieves the current length of the specified open file.", 
+            "title": "fs_filelen"
+        }, 
+        {
+            "location": "/os/modules/fs/fs/fs_filelen/#arguments", 
+            "text": "Arguments  Description      file  Pointer to the file to query    out_len  On success, the number of bytes in the file gets written here", 
             "title": "Arguments"
         }, 
         {
-            "location": "/os/modules/filesystem/#returned-values_4", 
-            "text": "0 on success  nonzero on failure", 
+            "location": "/os/modules/fs/fs/fs_filelen/#returned-values", 
+            "text": "0 on success  FS error code  on failure", 
             "title": "Returned values"
         }, 
         {
-            "location": "/os/modules/filesystem/#notes_4", 
-            "text": "", 
-            "title": "Notes"
+            "location": "/os/modules/fs/fs/fs_filelen/#header-file", 
+            "text": "#include  fs/fs.h", 
+            "title": "Header file"
         }, 
         {
-            "location": "/os/modules/filesystem/#example_4", 
-            "text": "Insert the code snippet here", 
+            "location": "/os/modules/fs/fs/fs_filelen/#example", 
+            "text": "int\nwrite_config(void)\n{\n    struct fs_file *file;\n    int rc;\n\n    /* If the file doesn't exist, create it.  If it does exist, truncate it to\n     * zero bytes.\n     */\n    rc = fs_open( /settings/config.txt , FS_ACCESS_WRITE | FS_ACCESS_TRUNCATE,\n                  file);\n    if (rc == 0) {\n        /* Write 5 bytes of data to the file. */\n        rc = fs_write(file,  hello , 5);\n        if (rc == 0) {\n            /* The file should now contain exactly five bytes. */\n            assert(fs_filelen(file) == 5);\n        }\n\n        /* Close the file. */\n        fs_close(file);\n    }\n\n    return rc == 0 ? 0 : -1;\n}", 
             "title": "Example"
         }, 
         {
-            "location": "/os/modules/filesystem/#fs_getpos", 
-            "text": "uint32_t\n   fs_getpos(const struct fs_file *file);  Retrieves the current read and write position of the specified open file.", 
-            "title": " fs_getpos "
+            "location": "/os/modules/fs/fs/fs_getpos/", 
+            "text": "fs_getpos\n\n\nuint32_t fs_getpos(const struct fs_file *file)\n\n\n\n\nRetrieves the current read and write position of the specified open file. \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfile\n\n\nPointer to the file to query\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\nThe file offset, in bytes\n\n\n\n\nNotes\n\n\nIf a file is opened in append mode, its write pointer is always positioned at the end of the file.  Calling this function on such a file only indicates the read position.\n\n\nHeader file\n\n\n#include \nfs/fs.h", 
+            "title": "fs_getpos"
         }, 
         {
-            "location": "/os/modules/filesystem/#arguments_5", 
+            "location": "/os/modules/fs/fs/fs_getpos/#fs95getpos", 
+            "text": "uint32_t fs_getpos(const struct fs_file *file)  Retrieves the current read and write position of the specified open file.", 
+            "title": "fs_getpos"
+        }, 
+        {
+            "location": "/os/modules/fs/fs/fs_getpos/#arguments", 
             "text": "Arguments  Description      file  Pointer to the file to query", 
             "title": "Arguments"
         }, 
         {
-            "location": "/os/modules/filesystem/#returned-values_5", 
+            "location": "/os/modules/fs/fs/fs_getpos/#returned-values", 
             "text": "The file offset, in bytes", 
             "title": "Returned values"
         }, 
         {
-            "location": "/os/modules/filesystem/#notes_5", 
-            "text": "", 
+            "location": "/os/modules/fs/fs/fs_getpos/#notes", 
+            "text": "If a file is opened in append mode, its write pointer is always positioned at the end of the file.  Calling this function on such a file only indicates the read position.", 
             "title": "Notes"
         }, 
         {
-            "location": "/os/modules/filesystem/#example_5", 
-            "text": "Insert the code snippet here", 
-            "title": "Example"
+            "location": "/os/modules/fs/fs/fs_getpos/#header-file", 
+            "text": "#include  fs/fs.h", 
+            "title": "Header file"
         }, 
         {
-            "location": "/os/modules/filesystem/#fs_filelen", 
-            "text": "int\n   fs_filelen(const struct fs_file *file, uint32_t *out_len);  Retrieves the current length of the specified open file.", 
-            "title": " fs_filelen "
+            "location": "/os/modules/fs/fs/fs_mkdir/", 
+            "text": "fs_mkdir\n\n\nint fs_mkdir(const char *path)\n\n\n\n\nCreates the directory represented by the specified path.  \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\npath\n\n\nThe name of the directory to create\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nFS error code\n on failure.\n\n\n\n\nNotes\n\n\nAll intermediate directories must already exist.  The specified path must start with a '/' character.\n\n\nHeader file\n\n\n#include \nfs/fs.h\n\n\n\n\n\nExample\n\n\nThis example demonstrates creating a series of nested directories.\n\n\nint\ncreate_path(void)\n{\n    int rc;\n\n    rc = fs_mkdir(\n/data\n);\n    if (rc != 0) goto err;\n\n    rc = fs_mkdir(\n/data/logs\n);\n    if (rc != 0) goto err;\n\n    rc = fs_mkdir(\n/data/logs/temperature\n);\n    if (rc != 0) goto err;\n\n    rc = fs_mkdir(\n/data/logs/temperature/current\n);\n    if (rc != 0) goto err;\n\n    return 0;\n\nerr:\n    /* Clean up the incomplete dir
 ectory tree, if any. */\n    fs_unlink(\n/data\n);\n    return -1;\n}", 
+            "title": "fs_mkdir"
         }, 
         {
-            "location": "/os/modules/filesystem/#arguments_6", 
-            "text": "Arguments  Description      file  Pointer to the file to query    out_len  On success, the number of bytes in the file gets written here", 
+            "location": "/os/modules/fs/fs/fs_mkdir/#fs95mkdir", 
+            "text": "int fs_mkdir(const char *path)  Creates the directory represented by the specified path.", 
+            "title": "fs_mkdir"
+        }, 
+        {
+            "location": "/os/modules/fs/fs/fs_mkdir/#arguments", 
+            "text": "Arguments  Description      path  The name of the directory to create", 
             "title": "Arguments"
         }, 
         {
-            "location": "/os/modules/filesystem/#returned-values_6", 
-            "text": "0 on success  nonzero on failure", 
+            "location": "/os/modules/fs/fs/fs_mkdir/#returned-values", 
+            "text": "0 on success  FS error code  on failure.", 
             "title": "Returned values"
         }, 
         {
-            "location": "/os/modules/filesystem/#notes_6", 
-            "text": "", 
+            "location": "/os/modules/fs/fs/fs_mkdir/#notes", 
+            "text": "All intermediate directories must already exist.  The specified path must start with a '/' character.", 
             "title": "Notes"
         }, 
         {
-            "location": "/os/modules/filesystem/#example_6", 
-            "text": "Insert the code snippet here", 
+            "location": "/os/modules/fs/fs/fs_mkdir/#header-file", 
+            "text": "#include  fs/fs.h", 
+            "title": "Header file"
+        }, 
+        {
+            "location": "/os/modules/fs/fs/fs_mkdir/#example", 
+            "text": "This example demonstrates creating a series of nested directories.  int\ncreate_path(void)\n{\n    int rc;\n\n    rc = fs_mkdir( /data );\n    if (rc != 0) goto err;\n\n    rc = fs_mkdir( /data/logs );\n    if (rc != 0) goto err;\n\n    rc = fs_mkdir( /data/logs/temperature );\n    if (rc != 0) goto err;\n\n    rc = fs_mkdir( /data/logs/temperature/current );\n    if (rc != 0) goto err;\n\n    return 0;\n\nerr:\n    /* Clean up the incomplete directory tree, if any. */\n    fs_unlink( /data );\n    return -1;\n}", 
             "title": "Example"
         }, 
         {
-            "location": "/os/modules/filesystem/#fs_unlink", 
-            "text": "int\n   fs_unlink(const char *filename);  Unlinks the file or directory at the specified path.  If the path refers to a directory, all the directory's descendants are recursively unlinked.  Any open file handles refering to an unlinked file remain valid, and can be read from and written to.", 
-            "title": " fs_unlink "
+            "location": "/os/modules/fs/fs/fs_open/", 
+            "text": "fs_open\n\n\nint fs_open(const char *filename, uint8_t access_flags,\n            struct fs_file **out_file)\n\n\n\n\nOpens a file at the specified path.  The result of opening a nonexistent file depends on the access flags specified.  All intermediate directories must already exist.\n\n\nThe access flags are best understood by comparing them to their equivalent mode strings accepted by the C standard library function \nfopen()\n.\nThe mode strings passed to \nfopen()\n map to \nfs_open()\n's access flags as follows:\n\n\nr\n  -  FS_ACCESS_READ\n\nr+\n -  FS_ACCESS_READ  | FS_ACCESS_WRITE\n\nw\n  -  FS_ACCESS_WRITE | FS_ACCESS_TRUNCATE\n\nw+\n -  FS_ACCESS_READ  | FS_ACCESS_WRITE    | FS_ACCESS_TRUNCATE\n\na\n  -  FS_ACCESS_WRITE | FS_ACCESS_APPEND\n\na+\n -  FS_ACCESS_READ  | FS_ACCESS_WRITE    | FS_ACCESS_APPEND\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArgument\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfilename\n\n\nNull-terminated string indicating the full path of th
 e file to open\n\n\n\n\n\n\naccess_flags\n\n\nFlags controlling file access; see above table\n\n\n\n\n\n\nout_file\n\n\nOn success, a pointer to the newly-created file handle gets written here\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nFS error code\n on failure\n\n\n\n\nNotes\n\n\n\n\n\n\nThere is no concept of current working directory. Therefore all file names should start with '/'.\n\n\n\n\n\n\nAlways close files when you are done using them.  If you forget to close a file, the file stays open forever.  Do this too many times, and the underlying file system will run out of file handles, causing subsequent open operations to fail.  This type of bug is known as a file handle leak or a file descriptor leak.\n\n\n\n\n\n\nHeader file\n\n\n#include \nfs/fs.h\n\n\n\n\n\nExample\n\n\nThe below code opens the file \n/settings/config.txt\n for reading, reads some data, and then closes the file.\n\n\nint\nread_config(void)\n{\n    struct fs_file *file;\n    uint32_t bytes_
 read;\n    uint8_t buf[16];\n    int rc;\n\n    /* Open the file for reading. */\n    rc = fs_open(\n/settings/config.txt\n, FS_ACCESS_READ, \nfile);\n    if (rc != 0) {\n        return -1;\n    }\n\n    /* Read up to 16 bytes from the file. */\n    rc = fs_read(file, sizeof buf, buf, \nbytes_read);\n    if (rc == 0) {\n        /* buf now contains up to 16 bytes of file data. */\n        console_printf(\nread %u bytes\\n\n, bytes_read)\n    }\n\n    /* Close the file. */\n    fs_close(file);\n\n    return rc == 0 ? 0 : -1;\n}", 
+            "title": "fs_open"
         }, 
         {
-            "location": "/os/modules/filesystem/#arguments_7", 
-            "text": "Arguments  Description      filename  The path of the file or directory to unlink", 
+            "location": "/os/modules/fs/fs/fs_open/#fs95open", 
+            "text": "int fs_open(const char *filename, uint8_t access_flags,\n            struct fs_file **out_file)  Opens a file at the specified path.  The result of opening a nonexistent file depends on the access flags specified.  All intermediate directories must already exist.  The access flags are best understood by comparing them to their equivalent mode strings accepted by the C standard library function  fopen() .\nThe mode strings passed to  fopen()  map to  fs_open() 's access flags as follows:  r   -  FS_ACCESS_READ r+  -  FS_ACCESS_READ  | FS_ACCESS_WRITE w   -  FS_ACCESS_WRITE | FS_ACCESS_TRUNCATE w+  -  FS_ACCESS_READ  | FS_ACCESS_WRITE    | FS_ACCESS_TRUNCATE a   -  FS_ACCESS_WRITE | FS_ACCESS_APPEND a+  -  FS_ACCESS_READ  | FS_ACCESS_WRITE    | FS_ACCESS_APPEND", 
+            "title": "fs_open"
+        }, 
+        {
+            "location": "/os/modules/fs/fs/fs_open/#arguments", 
+            "text": "Argument  Description      filename  Null-terminated string indicating the full path of the file to open    access_flags  Flags controlling file access; see above table    out_file  On success, a pointer to the newly-created file handle gets written here", 
             "title": "Arguments"
         }, 
         {
-            "location": "/os/modules/filesystem/#returned-values_7", 
-            "text": "0 on success  nonzero on failure", 
+            "location": "/os/modules/fs/fs/fs_open/#returned-values", 
+            "text": "0 on success  FS error code  on failure", 
             "title": "Returned values"
         }, 
         {
-            "location": "/os/modules/filesystem/#notes_7", 
-            "text": "", 
+            "location": "/os/modules/fs/fs/fs_open/#notes", 
+            "text": "There is no concept of current working directory. Therefore all file names should start with '/'.    Always close files when you are done using them.  If you forget to close a file, the file stays open forever.  Do this too many times, and the underlying file system will run out of file handles, causing subsequent open operations to fail.  This type of bug is known as a file handle leak or a file descriptor leak.", 
             "title": "Notes"
         }, 
         {
-            "location": "/os/modules/filesystem/#example_7", 
-            "text": "Insert the code snippet here", 
+            "location": "/os/modules/fs/fs/fs_open/#header-file", 
+            "text": "#include  fs/fs.h", 
+            "title": "Header file"
+        }, 
+        {
+            "location": "/os/modules/fs/fs/fs_open/#example", 
+            "text": "The below code opens the file  /settings/config.txt  for reading, reads some data, and then closes the file.  int\nread_config(void)\n{\n    struct fs_file *file;\n    uint32_t bytes_read;\n    uint8_t buf[16];\n    int rc;\n\n    /* Open the file for reading. */\n    rc = fs_open( /settings/config.txt , FS_ACCESS_READ,  file);\n    if (rc != 0) {\n        return -1;\n    }\n\n    /* Read up to 16 bytes from the file. */\n    rc = fs_read(file, sizeof buf, buf,  bytes_read);\n    if (rc == 0) {\n        /* buf now contains up to 16 bytes of file data. */\n        console_printf( read %u bytes\\n , bytes_read)\n    }\n\n    /* Close the file. */\n    fs_close(file);\n\n    return rc == 0 ? 0 : -1;\n}", 
             "title": "Example"
         }, 
         {
-            "location": "/os/modules/filesystem/#fs_rename", 
-            "text": "int\n   fs_rename(const char *from, const char *to);  Performs a rename and / or move of the specified source path to the specified destination.", 
-            "title": " fs_rename "
+            "location": "/os/modules/fs/fs/fs_opendir/", 
+            "text": "fs_opendir\n\n\nint fs_opendir(const char *path, struct fs_dir **out_dir)\n\n\n\n\nOpens the directory at the specified path.  The directory's contents can be read with subsequent calls to fs_readdir().  When you are done with the directory handle, close it with fs_closedir(). \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\npath\n\n\nThe name of the directory to open\n\n\n\n\n\n\nout_dir\n\n\nOn success, points to the directory handle\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nFS_ENOENT if the specified directory does not exist\n\n\nOther \nFS error code\n on error.\n\n\n\n\nNotes\n\n\n\n\n\n\nUnlinking files from the directory while it is open may result in unpredictable behavior during subsequent calls to \nfs_readdir()\n.  New files can be created inside the directory without causing problems.\n\n\n\n\n\n\nAlways close a directory when you are done reading from it.  If you forget to close a directory, the dire
 ctory stays open forever.  Do this too many times, and the underlying file system will run out of directory handles, causing subsequent open operations to fail.  This type of bug is known as a file handle leak or a file descriptor leak.\n\n\n\n\n\n\nHeader file\n\n\n#include \nfs/fs.h\n\n\n\n\n\nExample\n\n\nThis example iterates through the contents of a directory, printing the name of each child node.  When the traversal is complete, the code closes the directory handle.\n\n\nint\ntraverse_dir(const char *dirname)\n{\n    struct fs_dirent *dirent;\n    struct fs_dir *dir;\n    char buf[64];\n    uint8_t name_len;\n    int rc;\n\n    rc = fs_opendir(dirname, \ndir);\n    if (rc != 0) {\n        return -1;\n    }\n\n    /* Iterate through the parent directory, printing the name of each child\n     * entry.  The loop only terminates via a function return.\n     */\n    while (1) {\n        /* Retrieve the next child node. */\n        rc = fs_readdir(dir, \ndirent); \n        if (rc =
 = FS_ENOENT) {\n            /* Traversal complete. */\n            return 0;\n        } else if (rc != 0) {\n            /* Unexpected error. */\n            return -1;\n        }\n\n        /* Read the child node's name from the file system. */\n        rc = fs_dirent_name(dirent, sizeof buf, buf, \nname_len);\n        if (rc != 0) {\n            return -1;\n        }\n\n        /* Print the child node's name to the console. */\n        if (fs_dirent_is_dir(dirent)) {\n            console_printf(\n dir: \n);\n        } else {\n            console_printf(\nfile: \n);\n        }\n        console_printf(\n%s\\n\n, buf);\n    }\n}", 
+            "title": "fs_opendir"
         }, 
         {
-            "location": "/os/modules/filesystem/#arguments_8", 
-            "text": "Arguments  Description      from  The source path    to  The destination path", 
+            "location": "/os/modules/fs/fs/fs_opendir/#fs95opendir", 
+            "text": "int fs_opendir(const char *path, struct fs_dir **out_dir)  Opens the directory at the specified path.  The directory's contents can be read with subsequent calls to fs_readdir().  When you are done with the directory handle, close it with fs_closedir().", 
+            "title": "fs_opendir"
+        }, 
+        {
+            "location": "/os/modules/fs/fs/fs_opendir/#arguments", 
+            "text": "Arguments  Description      path  The name of the directory to open    out_dir  On success, points to the directory handle", 
             "title": "Arguments"
         }, 
         {
-            "location": "/os/modules/filesystem/#returned-values_8", 
-            "text": "0 on success  nonzero on failure", 
+            "location": "/os/modules/fs/fs/fs_opendir/#returned-values", 
+            "text": "0 on success  FS_ENOENT if the specified directory does not exist  Other  FS error code  on error.", 
             "title": "Returned values"
         }, 
         {
-            "location": "/os/modules/filesystem/#notes_8", 
-            "text": "The source path can refer to either a file or a directory.  All intermediate directories in the destination path must already exist.  If the source path refers to a file, the destination path must contain a full filename path, rather than just the new parent directory.  If an object already exists at the specified destination path, this function causes it to be unlinked prior to the rename (i.e., the destination gets clobbered).", 
+            "location": "/os/modules/fs/fs/fs_opendir/#notes", 
+            "text": "Unlinking files from the directory while it is open may result in unpredictable behavior during subsequent calls to  fs_readdir() .  New files can be created inside the directory without causing problems.    Always close a directory when you are done reading from it.  If you forget to close a directory, the directory stays open forever.  Do this too many times, and the underlying file system will run out of directory handles, causing subsequent open operations to fail.  This type of bug is known as a file handle leak or a file descriptor leak.", 
             "title": "Notes"
         }, 
         {
-            "location": "/os/modules/filesystem/#example_8", 
-            "text": "Insert the code snippet here", 
+            "location": "/os/modules/fs/fs/fs_opendir/#header-file", 
+            "text": "#include  fs/fs.h", 
+            "title": "Header file"
+        }, 
+        {
+            "location": "/os/modules/fs/fs/fs_opendir/#example", 
+            "text": "This example iterates through the contents of a directory, printing the name of each child node.  When the traversal is complete, the code closes the directory handle.  int\ntraverse_dir(const char *dirname)\n{\n    struct fs_dirent *dirent;\n    struct fs_dir *dir;\n    char buf[64];\n    uint8_t name_len;\n    int rc;\n\n    rc = fs_opendir(dirname,  dir);\n    if (rc != 0) {\n        return -1;\n    }\n\n    /* Iterate through the parent directory, printing the name of each child\n     * entry.  The loop only terminates via a function return.\n     */\n    while (1) {\n        /* Retrieve the next child node. */\n        rc = fs_readdir(dir,  dirent); \n        if (rc == FS_ENOENT) {\n            /* Traversal complete. */\n            return 0;\n        } else if (rc != 0) {\n            /* Unexpected error. */\n            return -1;\n        }\n\n        /* Read the child node's name from the file system. */\n        rc = fs_dirent_name(dirent, sizeof buf, 
 buf,  name_len);\n        if (rc != 0) {\n            return -1;\n        }\n\n        /* Print the child node's name to the console. */\n        if (fs_dirent_is_dir(dirent)) {\n            console_printf(  dir:  );\n        } else {\n            console_printf( file:  );\n        }\n        console_printf( %s\\n , buf);\n    }\n}", 
             "title": "Example"
         }, 
         {
-            "location": "/os/modules/filesystem/#fs_mkdir", 
-            "text": "int\n   fs_mkdir(const char *path);  Creates the directory represented by the specified path.", 
-            "title": " fs_mkdir "
+            "location": "/os/modules/fs/fs/fs_read/", 
+            "text": "fs_read\n\n\nint fs_read(struct fs_file *file, uint32_t len, void *out_data, uint32_t *out_len)\n\n\n\n\nReads data from the specified file.  If more data is requested than remains in the file, all available data is retrieved and a success code is returned.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfile\n\n\nPointer to the the file to read from\n\n\n\n\n\n\nlen\n\n\nThe number of bytes to attempt to read\n\n\n\n\n\n\nout_data\n\n\nThe destination buffer to read into\n\n\n\n\n\n\nout_len\n\n\nOn success, the number of bytes actually read gets written here.  Pass null if you don't care.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nFS error code\n on failure\n\n\n\n\nHeader file\n\n\n#include \nfs/fs.h\n\n\n\n\n\nExample\n\n\nThe below code opens the file \n/settings/config.txt\n for reading, reads some data, and then closes the file.\n\n\nint\nread_config(void)\n{\n    struct fs_file *file;\n    uint32_t bytes_r
 ead;\n    uint8_t buf[16];\n    int rc;\n\n    /* Open the file for reading. */\n    rc = fs_open(\n/settings/config.txt\n, FS_ACCESS_READ, \nfile);\n    if (rc != 0) {\n        return -1;\n    }\n\n    /* Read up to 16 bytes from the file. */\n    rc = fs_read(file, sizeof buf, buf, \nbytes_read);\n    if (rc == 0) {\n        /* buf now contains up to 16 bytes of file data. */\n        console_printf(\nread %u bytes\\n\n, bytes_read)\n    }\n\n    /* Close the file. */\n    fs_close(file);\n\n    return rc == 0 ? 0 : -1;\n}", 
+            "title": "fs_read"
         }, 
         {
-            "location": "/os/modules/filesystem/#arguments_9", 
-            "text": "Arguments  Description      path  Pointer to the directory to create", 
+            "location": "/os/modules/fs/fs/fs_read/#fs95read", 
+            "text": "int fs_read(struct fs_file *file, uint32_t len, void *out_data, uint32_t *out_len)  Reads data from the specified file.  If more data is requested than remains in the file, all available data is retrieved and a success code is returned.", 
+            "title": "fs_read"
+        }, 
+        {
+            "location": "/os/modules/fs/fs/fs_read/#arguments", 
+            "text": "Arguments  Description      file  Pointer to the the file to read from    len  The number of bytes to attempt to read    out_data  The destination buffer to read into    out_len  On success, the number of bytes actually read gets written here.  Pass null if you don't care.", 
             "title": "Arguments"
         }, 
         {
-            "location": "/os/modules/filesystem/#returned-values_9", 
-            "text": "0 on success  nonzero on failure.", 
+            "location": "/os/modules/fs/fs/fs_read/#returned-values", 
+            "text": "0 on success  FS error code  on failure", 
             "title": "Returned values"
         }, 
         {
-            "location": "/os/modules/filesystem/#notes_9", 
-            "text": "All intermediate directories must already exist.  The specified path must start with a '/' character.", 
-            "title": "Notes"
+            "location": "/os/modules/fs/fs/fs_read/#header-file", 
+            "text": "#include  fs/fs.h", 
+            "title": "Header file"
         }, 
         {
-            "location": "/os/modules/filesystem/#example_9", 
-            "text": "Insert the code snippet here", 
+            "location": "/os/modules/fs/fs/fs_read/#example", 
+            "text": "The below code opens the file  /settings/config.txt  for reading, reads some data, and then closes the file.  int\nread_config(void)\n{\n    struct fs_file *file;\n    uint32_t bytes_read;\n    uint8_t buf[16];\n    int rc;\n\n    /* Open the file for reading. */\n    rc = fs_open( /settings/config.txt , FS_ACCESS_READ,  file);\n    if (rc != 0) {\n        return -1;\n    }\n\n    /* Read up to 16 bytes from the file. */\n    rc = fs_read(file, sizeof buf, buf,  bytes_read);\n    if (rc == 0) {\n        /* buf now contains up to 16 bytes of file data. */\n        console_printf( read %u bytes\\n , bytes_read)\n    }\n\n    /* Close the file. */\n    fs_close(file);\n\n    return rc == 0 ? 0 : -1;\n}", 
             "title": "Example"
         }, 
         {
-            "location": "/os/modules/filesystem/#fs_opendir", 
-            "text": "int\n   fs_opendir(const char *path, struct fs_dir **out_dir);  Opens the directory at the specified path.  The directory's contents can be read with subsequent calls to fs_readdir().  When you are done with the directory handle, close it with fs_closedir().", 
-            "title": " fs_opendir "
+            "location": "/os/modules/fs/fs/fs_readdir/", 
+            "text": "fs_readdir\n\n\nint fs_readdir(struct fs_dir *dir, struct fs_dirent **out_dirent);\n\n\n\n\nReads the next entry in an open directory. \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\ndir\n\n\nThe directory handle to read from\n\n\n\n\n\n\nout_dirent\n\n\nOn success, points to the next child entry in the specified directory\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nFS_ENOENT if there are no more entries in the parent directory\n\n\nOther \nFS error code\n on error.\n\n\n\n\nHeader file\n\n\n#include \nfs/fs.h\n\n\n\n\n\nExample\n\n\nThis example iterates through the contents of a directory, printing the name of each child node.  When the traversal is complete, the code closes the directory handle.\n\n\nint\ntraverse_dir(const char *dirname)\n{\n    struct fs_dirent *dirent;\n    struct fs_dir *dir;\n    char buf[64];\n    uint8_t name_len;\n    int rc;\n\n    rc = fs_opendir(dirname, \ndir);\n    if (rc != 0) {\n
         return -1;\n    }\n\n    /* Iterate through the parent directory, printing the name of each child\n     * entry.  The loop only terminates via a function return.\n     */\n    while (1) {\n        /* Retrieve the next child node. */\n        rc = fs_readdir(dir, \ndirent); \n        if (rc == FS_ENOENT) {\n            /* Traversal complete. */\n            return 0;\n        } else if (rc != 0) {\n            /* Unexpected error. */\n            return -1;\n        }\n\n        /* Read the child node's name from the file system. */\n        rc = fs_dirent_name(dirent, sizeof buf, buf, \nname_len);\n        if (rc != 0) {\n            return -1;\n        }\n\n        /* Print the child node's name to the console. */\n        if (fs_dirent_is_dir(dirent)) {\n            console_printf(\n dir: \n);\n        } else {\n            console_printf(\nfile: \n);\n        }\n        console_printf(\n%s\\n\n, buf);\n    }\n}", 
+            "title": "fs_readdir"
+        }, 
+        {
+            "location": "/os/modules/fs/fs/fs_readdir/#fs_readdir", 
+            "text": "int fs_readdir(struct fs_dir *dir, struct fs_dirent **out_dirent);  Reads the next entry in an open directory.", 
+            "title": "fs_readdir"
         }, 
         {
-            "location": "/os/modules/filesystem/#arguments_10", 
-            "text": "Arguments  Description      path  Pointer to the directory to create    out_dir  On success, points to the directory handle", 
+            "location": "/os/modules/fs/fs/fs_readdir/#arguments", 
+            "text": "Arguments  Description      dir  The directory handle to read from    out_dirent  On success, points to the next child entry in the specified directory", 
             "title": "Arguments"
         }, 
         {
-            "location": "/os/modules/filesystem/#returned-values_10", 
-            "text": "0 on success  FS_ENOENT if the specified directory does not exist (no such file)  Other nonzero on error.", 
+            "location": "/os/modules/fs/fs/fs_readdir/#returned-values", 
+            "text": "0 on success  FS_ENOENT if there are no more entries in the parent directory  Other  FS error code  on error.", 
             "title": "Returned values"
         }, 
         {
-            "location": "/os/modules/filesystem/#notes_10", 
-            "text": "Unlinking files from the directory while it is open may result in unpredictable behavior.  New files can be created inside the directory.", 
-            "title": "Notes"
+            "location": "/os/modules/fs/fs/fs_readdir/#header-file", 
+            "text": "#include  fs/fs.h", 
+            "title": "Header file"
         }, 
         {
-            "location": "/os/modules/filesystem/#example_10", 
-            "text": "Insert the code snippet here", 
+            "location": "/os/modules/fs/fs/fs_readdir/#example", 
+            "text": "This example iterates through the contents of a directory, printing the name of each child node.  When the traversal is complete, the code closes the directory handle.  int\ntraverse_dir(const char *dirname)\n{\n    struct fs_dirent *dirent;\n    struct fs_dir *dir;\n    char buf[64];\n    uint8_t name_len;\n    int rc;\n\n    rc = fs_opendir(dirname,  dir);\n    if (rc != 0) {\n        return -1;\n    }\n\n    /* Iterate through the parent directory, printing the name of each child\n     * entry.  The loop only terminates via a function return.\n     */\n    while (1) {\n        /* Retrieve the next child node. */\n        rc = fs_readdir(dir,  dirent); \n        if (rc == FS_ENOENT) {\n            /* Traversal complete. */\n            return 0;\n        } else if (rc != 0) {\n            /* Unexpected error. */\n            return -1;\n        }\n\n        /* Read the child node's name from the file system. */\n        rc = fs_dirent_name(dirent, sizeof buf, 
 buf,  name_len);\n        if (rc != 0) {\n            return -1;\n        }\n\n        /* Print the child node's name to the console. */\n        if (fs_dirent_is_dir(dirent)) {\n            console_printf(  dir:  );\n        } else {\n            console_printf( file:  );\n        }\n        console_printf( %s\\n , buf);\n    }\n}", 
             "title": "Example"
         }, 
         {
-            "location": "/os/modules/filesystem/#fs_readdir", 
-            "text": "int\n   fs_readdir(struct fs_dir *dir, struct fs_dirent **out_dirent);  Reads the next entry in an open directory.", 
-            "title": " fs_readdir "
+            "location": "/os/modules/fs/fs/fs_register/", 
+            "text": "fs_register\n\n\nint fs_register(const struct fs_ops *fops)\n\n\n\n\nRegisters a file system with the abstraction layer.  On success, all calls into \nfs/fs\n will use the registered file system.\n\n\nArguments\n\n\n\n\n\n\n\n\nArgument\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfops\n\n\nA pointer to const \nstruct fs_ops\n. Specifies which file system routines get mapped to the \nfs/fs\n API.  All function pointers must be filled in.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nFS_EEXIST\n if a file system has already been registered\n\n\n\n\nNotes\n\n\nOnly one file system can be registered.  The registered file system is mounted in the root directory (\n/\n).\n\n\nHeader file\n\n\n#include \nfs/fs.h", 
+            "title": "fs_register"
         }, 
         {
-            "location": "/os/modules/filesystem/#arguments_11", 
-            "text": "Arguments  Description      dir  The directory handle to read from    out_dirent  On success, points to the next child entry in the specified directory", 
+            "location": "/os/modules/fs/fs/fs_register/#fs95register", 
+            "text": "int fs_register(const struct fs_ops *fops)  Registers a file system with the abstraction layer.  On success, all calls into  fs/fs  will use the registered file system.", 
+            "title": "fs_register"
+        }, 
+        {
+            "location": "/os/modules/fs/fs/fs_register/#arguments", 
+            "text": "Argument  Description      fops  A pointer to const  struct fs_ops . Specifies which file system routines get mapped to the  fs/fs  API.  All function pointers must be filled in.", 
             "title": "Arguments"
         }, 
         {
-            "location": "/os/modules/filesystem/#return

<TRUNCATED>


Mime
View raw message