*luv-file-system-operations* *uv_fs_t*

Most file system functions can operate synchronously or asynchronously. When a
synchronous version is called (by omitting a callback), the function will
immediately return the results of the FS call. When an asynchronous version is
called (by providing a callback), the function will immediately return a
`uv_fs_t userdata` and asynchronously execute its callback; if an error is
encountered, the first and only argument passed to the callback will be the
`err` error string; if the operation completes successfully, the first
argument will be `nil` and the remaining arguments will be the results of the
FS call.

Synchronous and asynchronous versions of `readFile` (with naive error
handling) are implemented below as an example:

    >lua
    local function readFileSync(path)
      local fd = assert(uv.fs_open(path, "r", 438))
      local stat = assert(uv.fs_fstat(fd))
      local data = assert(uv.fs_read(fd, stat.size, 0))
      assert(uv.fs_close(fd))
      return data
    end

    local data = readFileSync("main.lua")
    print("synchronous read", data)
<

    >lua
    local function readFile(path, callback)
      uv.fs_open(path, "r", 438, function(err, fd)
        assert(not err, err)
        uv.fs_fstat(fd, function(err, stat)
          assert(not err, err)
          uv.fs_read(fd, stat.size, 0, function(err, data)
            assert(not err, err)
            uv.fs_close(fd, function(err)
              assert(not err, err)
              return callback(data)
            end)
          end)
        end)
      end)
    end

    readFile("main.lua", function(data)
      print("asynchronous read", data)
    end)
<

uv.fs_close({fd} [, {callback}])                                 *uv.fs_close()*

                Parameters:
                - `fd`: `integer`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `success`: `boolean` or `nil`

                Equivalent to `close(2)`.

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

                Returns (async version): `uv_fs_t userdata`

uv.fs_open({path}, {flags}, {mode} [, {callback}])                *uv.fs_open()*

                Parameters:
                - `path`: `string`
                - `flags`: `string` or `integer`
                - `mode`: `integer` (octal `chmod(1)` mode, e.g.
                  `tonumber('644', 8)`)
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `fd`: `integer` or `nil`

                Equivalent to `open(2)`. Access `flags` may be an integer or
                one of: `"r"`, `"rs"`, `"sr"`, `"r+"`, `"rs+"`, `"sr+"`,
                `"w"`, `"wx"`, `"xw"`, `"w+"`, `"wx+"`, `"xw+"`, `"a"`,
                `"ax"`, `"xa"`, `"a+"`, `"ax+"`, or "`xa+`".

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

                Returns (async version): `uv_fs_t userdata`

                Note: On Windows, libuv uses `CreateFileW` and thus the file
                is always opened in binary mode. Because of this, the
                `O_BINARY` and `O_TEXT` flags are not supported.

uv.fs_read({fd}, {size} [, {offset} [, {callback}]])              *uv.fs_read()*

                Parameters:
                - `fd`: `integer`
                - `size`: `integer`
                - `offset`: `integer` or `nil`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `data`: `string` or `nil`

                Equivalent to `preadv(2)`. Returns any data. An empty string
                indicates EOF.

                If `offset` is nil or omitted, it will default to `-1`, which
                indicates "use and update the current file offset."

                Note: When `offset`