Skip to content
Search

Libuv:Filesystem

lastmod 2018-08-17created 2016-04-015 edits

libuv provides a wide variety of cross-platform sync and async filesystem operations. All functions defined in this document take a callback, which is allowed to be NULL. If the callback is NULL the request is completed synchronously, otherwise it will be performed asynchronously.

All file operations are run on the threadpool, see Thread pool work scheduling for information on the threadpool size.

Introduce

The libuv file system can operate in two ways: synchronous and asynchronous.

  • To operate synchronously, pass NULL as the callback. In that case, check the libuv error code in the return value.
  • To operate asynchronously, pass a callback; the return value is 0.

Note

By default, the libuv file system behaves differently from socket commands.

  • Socket commands use the non-blocking commands provided by the OS,
  • whereas the file system blocks internally within the function.

However, the file system can apply calls through the thread pool and register a notification (notify) with the event loop.

File R/W 

/**
 * open, creat - open and possibly create a file or device.
 *
 * @return
 *  return the new file descriptor, or -1 if an error occurred.
 *
 * @warning
 *  On Windows libuv uses CreateFileW and thus the file is always opened in binary mode. @n
 *  Because of this the O_BINARY and O_TEXT flags are not supported.
 *
 * @see <http://docs.libuv.org/en/v1.x/fs.html>
 * @see <http://linux.die.net/man/2/open>
 */
int open(std::string const & path, int flags = (FILE_OPEN_FLAG_READ_WRITE | FILE_OPEN_CREATE), int mode = 0644)
{
    uv_fs_t request;
    int result = uv_fs_open(nullptr, &request, path.c_str(), flags, mode, nullptr);
    uv_fs_req_cleanup(&request);

    // Assert Check:
    //  - Source code: uv/test/test-fs-event.c
    //  - Method prototype: static void create_file(const char* name)
    return result;
}

/**
 * @return
 *  Returns zero on success.
 *
 * @see <http://docs.libuv.org/en/v1.x/fs.html>
 * @see <http://linux.die.net/man/2/close>
 */
bool close(int fd)
{
    uv_fs_t request;
    int result = uv_fs_close(nullptr, &request, static_cast<uv_file>(fd), nullptr);
    uv_fs_req_cleanup(&request);

    // Assert Check:
    //  - Source code: uv/test/test-fs-event.c
    //  - Method prototype: static void create_file(const char* name)
    return (result == 0 ? true : false);
}

/**
 * @return
 *  On success, return the number of bytes written.
 *
 * @see <http://docs.libuv.org/en/v1.x/fs.html>
 * @see <http://linux.die.net/man/2/pwritev>
 */
int write(int fd, char const * buffer, std::size_t buffer_size, int64_t offset)
{
    uv_fs_t request;
    uv_buf_t buf;
    buf.len = buffer_size;
    buf.base = const_cast<char*>(buffer);
    int result = uv_fs_write(nullptr, &request, static_cast<uv_file>(fd), &buf, 1, offset, nullptr);
    uv_fs_req_cleanup(&request);

    return result;
}

/**
 * @return
 *  On success, return the number of bytes read.
 *
 * @see <http://docs.libuv.org/en/v1.x/fs.html>
 * @see <http://linux.die.net/man/2/preadv>
 */
int read(int fd, char * buffer, std::size_t buffer_size, int64_t offset)
{
    uv_fs_t request;
    uv_buf_t buf;
    buf.len = buffer_size;
    buf.base = buffer;
    int result = uv_fs_read(nullptr, &request, static_cast<uv_file>(fd), &buf, 1, offset, nullptr);
    uv_fs_req_cleanup(&request);

    return result;
}

See also

Favorite site

sitemap