abi/stat.md

+Get the metadata/statistics for a file, directory or other file system item.
+
+### Syntax ###
+
+```cpp
+#include <sys/stat.h>
+
+int fstat (const char *filename, struct stat *st);
+```
+
+### Parameters ###
+
+ *  `filename`
+
+    Path to the file to retrieve the `stat` structure for.
+
+ *  `st`
+
+    Pointer to a `stat` structure that will receive the information.
+
+### Return Value ###
+
+The return value is null if successful. Otherwise, the return value is negative
+and errno is set:
+
+ *  **ENOENT**
+
+    No such file or directory.
+
+ *  **ENOSYS**
+
+    The system call is not supported for this file system, or not implemented.
+
+### Remarks ###
+
+The `stat` structure is as follows:
+
+```cpp
+struct stat
+{
+	dev_t st_dev;
+	ino_t st_ino;
+	mode_t st_mode;
+	nlink_t st_nlink;
+	uid_t st_uid;
+	gid_t st_gid;
+	dev_t st_rdev;
+	off_t st_size;
+	time_t st_atime;
+	time_t st_mtime;
+	time_t st_ctime;
+	blksize_t st_blksize;
+	blkcnt_t st_blocks;
+};
+```
+
+Note that, being a microcontroller OS, most fields are left blank. The fields
+that will contain usable information are:
+
+ *  `st_mode`
+
+    Bitfield that may be accessed by the macros in the header file. The first
+    part describes the type of file, and may be one of the following:
+
+     * `S_IFBLK`: Block device. Typically disk drives.
+     * `S_IFCHR`: Char device. Typically device drivers.
+     * `S_IFIFO`: FIFO (pipe in our terminology).
+     * `S_IFREG`: Regular file.
+     * `S_IFDIR`: Directory.
+     * `S_IFLNK`: Link.
+     * `S_IFSOCK`: Network socket.
+
+    The bitfield also contains the access rights of the file (read/write/exec
+    permissions). The following definitions define the bits that are used:
+
+     * `S_IRUSR`: Owner user read access.
+     * `S_IWUSR`: Owner user write access.
+     * `S_IXUSR`: Owner user execute access.
+     * `S_IRWXU`: Bitwise or of the above three.
+
+     * `S_IRGRP`: Group read access.
+     * `S_IWGRP`: Group write access.
+     * `S_IXGRP`: Group execute access.
+     * `S_IRWXG`: Bitwise or of the above three.
+
+     * `S_IROTH`: Anyone read access.
+     * `S_IWOTH`: Anyone write access.
+     * `S_IXOTH`: Anyone execute access.
+     * `S_IRWXO`: Bitwise or of the above three.
+
+    **Note:** At the time of writing, only the KFS care about the access rights.
+    You may show the access rights of a file or directory contents with the
+    `ls -l` command.
+
+ *  `st_size`
+
+    The size of the object in bytes. PipeFS will return the buffer size
+    available to the pipe. Other special file systems may return a fixed size,
+    depending on the characteristics of that file system.