File System Operations: Opendir, Readdir, Closedir, Statfs

45th chunk of `runtime/doc/luvref.txt`

72aa1fd94643c9cf668fe4e13a1081b5938f11dce97931ca0000000100000fa0

 `path`: `string`
                - `new_path`: `string`
                - `flags`: `table`, `integer`, or `nil`
                  - `excl`: `boolean`
                  - `ficlone`: `boolean`
                  - `ficlone_force`: `boolean`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `success`: `boolean` or `nil`

                Copies a file from path to new_path. If the `flags` parameter
                is omitted, then the 3rd parameter will be treated as the
                `callback`.

                Returns (sync version): `boolean` or `fail`

                Returns (async version): `uv_fs_t userdata`

uv.fs_opendir({path} [, {callback} [, {entries}]])             *uv.fs_opendir()*

                Parameters:
                - `path`: `string`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `dir`: `luv_dir_t userdata` or `nil`
                - `entries`: `integer` or `nil`

                Opens path as a directory stream. Returns a handle that the
                user can pass to |uv.fs_readdir()|. The `entries` parameter
                defines the maximum number of entries that should be returned
                by each call to |uv.fs_readdir()|.

                Returns (sync version): `luv_dir_t userdata` or `fail`

                Returns (async version): `uv_fs_t userdata`

uv.fs_readdir({dir} [, {callback}])                            *uv.fs_readdir()*

                > method form `dir:readdir([callback])`

                Parameters:
                - `dir`: `luv_dir_t userdata`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `entries`: `table` or `nil` (see below)

                Iterates over the directory stream `luv_dir_t` returned by a
                successful |uv.fs_opendir()| call. A table of data tables is
                returned where the number of entries `n` is equal to or less
                than the `entries` parameter used in the associated
                |uv.fs_opendir()| call.

                Returns (sync version): `table` or `fail`
                - `[1, 2, 3, ..., n]` : `table`
                  - `name` : `string`
                  - `type` : `string`

                Returns (async version): `uv_fs_t userdata`

uv.fs_closedir({dir} [, {callback}])                          *uv.fs_closedir()*

                > method form `dir:closedir([callback])`

                Parameters:
                - `dir`: `luv_dir_t userdata`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `success`: `boolean` or `nil`

                Closes a directory stream returned by a successful
                |uv.fs_opendir()| call.

                Returns (sync version): `boolean` or `fail`

                Returns (async version): `uv_fs_t userdata`

uv.fs_statfs({path} [, {callback}])                             *uv.fs_statfs()*

                Parameters:
                - `path`: `string`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `table` or `nil` (see below)

                Equivalent to `statfs(2)`.

                Returns `table` or `nil`
                - `type` : `integer`
                - `bsize` : `integer`
                - `blocks` : `integer`
                - `bfree` : `integer`
                - `bavail` : `integer`
                - `files` : `integer`
                - `ffree` : `integer`

==============================================================================
THREAD POOL WORK SCHEDULING

Title: File System Operations: Opendir, Readdir, Closedir, Statfs

Summary

This section describes file system operations for directory handling and file system statistics. It details `uv.fs_opendir` (opens a directory stream), `uv.fs_readdir` (iterates through a directory stream, returning entries), `uv.fs_closedir` (closes a directory stream), and `uv.fs_statfs` (retrieves file system statistics, equivalent to statfs(2)). The parameters, return values (both synchronous and asynchronous), and related C functions are provided for each function.