diff --git a/docs/src/fs.rst b/docs/src/fs.rst index 01a48e8e..31b8a43a 100644 --- a/docs/src/fs.rst +++ b/docs/src/fs.rst @@ -200,9 +200,13 @@ Public members .. c:member:: ssize_t uv_fs_t.result - Result of the request. < 0 means error, success otherwise. On requests such - as :c:func:`uv_fs_read` or :c:func:`uv_fs_write` it indicates the amount of - data that was read or written, respectively. + Result of the request. < 0 means error, success otherwise. This field is always set, regardless + of the request being sync or async. + + For synchronous calls, the result of each operation is this field. + + Check each function's documentation to check if the field has + an extended meaning. .. c:member:: uv_stat_t uv_fs_t.statbuf @@ -221,8 +225,10 @@ API .. c:function:: void uv_fs_req_cleanup(uv_fs_t* req) - Cleanup request. Must be called after a request is finished to deallocate - any memory libuv might have allocated. + Cleanup request. Must be called after a request is finished to cleanup + any resources libuv might have allocated. + + It must be called for all requests, regardless of success or failure. .. c:function:: int uv_fs_close(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_fs_cb cb) @@ -232,6 +238,17 @@ API Equivalent to :man:`open(2)`. + The `req->result` field contains the opened file descriptor, of < 0 for error. + + The `flags` argument has different semantics depending on the OS: + + - On Unix, they are directly passed to :man:`open(2)`. + - On Windows, the following flags are implemented, emulating Unix semantics: `UV_FS_O_APPEND`, + `UV_FS_O_CREAT`, `UV_FS_O_EXCL`, `UV_FS_O_FILEMAP`, `UV_FS_O_RANDOM`, `UV_FS_O_RDONLY`, + `UV_FS_O_RDWR`, `UV_FS_O_SEQUENTIAL`, `UV_FS_O_SHORT_LIVED`, `UV_FS_O_TEMPORARY`, + `UV_FS_O_TRUNC`, `UV_FS_O_WRONLY`, `UV_FS_O_DIRECT`, `UV_FS_O_DSYNC`, `UV_FS_O_EXLOCK`, + `UV_FS_O_SYNC`. + .. 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 @@ -242,6 +259,8 @@ API Equivalent to :man:`preadv(2)`. If the `offset` argument is `-1`, then the current file offset is used and updated. + The result in `req->result` indicates the amount of bytes read, if > 0. + .. warning:: On Windows, under non-MSVC environments (e.g. when GCC or Clang is used to build libuv), files opened using ``UV_FS_O_FILEMAP`` may cause a fatal @@ -256,6 +275,8 @@ API Equivalent to :man:`pwritev(2)`. If the `offset` argument is `-1`, then the current file offset is used and updated. + The result in `req->result` indicates the amount of bytes written, if > 0. + .. warning:: On Windows, under non-MSVC environments (e.g. when GCC or Clang is used to build libuv), files opened using ``UV_FS_O_FILEMAP`` may cause a fatal diff --git a/docs/src/handle.rst b/docs/src/handle.rst index 2b1b8eec..b42716a6 100644 --- a/docs/src/handle.rst +++ b/docs/src/handle.rst @@ -156,6 +156,10 @@ API `close_cb` can be `NULL` in cases where no cleanup or deallocation is necessary. + .. warning:: + Calling this function multiple times is not supported and will produce + a crash. + .. c:function:: void uv_ref(uv_handle_t* handle) Reference the given handle. References are idempotent, that is, if a handle diff --git a/docs/src/threading.rst b/docs/src/threading.rst index 2edf3a89..233be386 100644 --- a/docs/src/threading.rst +++ b/docs/src/threading.rst @@ -162,19 +162,26 @@ Threads .. versionadded:: 1.50.0 .. c:function:: int uv_thread_setpriority(uv_thread_t tid, int priority) + If the function succeeds, the return value is 0. If the function fails, the return value is less than zero. + Sets the scheduling priority of the thread specified by tid. It requires elevated privilege to set specific priorities on some platforms. - The priority can be set to the following constants. UV_THREAD_PRIORITY_HIGHEST, - UV_THREAD_PRIORITY_ABOVE_NORMAL, UV_THREAD_PRIORITY_NORMAL, - UV_THREAD_PRIORITY_BELOW_NORMAL, UV_THREAD_PRIORITY_LOWEST. + + The priority can be set to the following constants: `UV_THREAD_PRIORITY_HIGHEST`, + `UV_THREAD_PRIORITY_ABOVE_NORMAL`, `UV_THREAD_PRIORITY_NORMAL`, + `UV_THREAD_PRIORITY_BELOW_NORMAL`, `UV_THREAD_PRIORITY_LOWEST`. + .. c:function:: int uv_thread_getpriority(uv_thread_t tid, int* priority) + If the function succeeds, the return value is 0. If the function fails, the return value is less than zero. + Retrieves the scheduling priority of the thread specified by tid. The value in the output parameter priority is platform dependent. - For Linux, when schedule policy is SCHED_OTHER (default), priority is 0. + + For Linux, when schedule policy is `SCHED_OTHER` (default), priority is 0. Thread-local storage ^^^^^^^^^^^^^^^^^^^^