diff options
author | Saúl Ibarra Corretgé <saghul@gmail.com> | 2016-09-01 10:18:47 +0200 |
---|---|---|
committer | Saúl Ibarra Corretgé <saghul@gmail.com> | 2016-09-02 09:57:25 +0200 |
commit | 6938f6b0bdbcfd40d7e0cdd3ff298cf46b3dca0d (patch) | |
tree | 9c293546e11022a164ff2ee64ea79caf50459973 /docs/src | |
parent | a7dfee3b02c70ca872c750fc60860d238623be69 (diff) | |
download | libuv-6938f6b0bdbcfd40d7e0cdd3ff298cf46b3dca0d.tar.gz libuv-6938f6b0bdbcfd40d7e0cdd3ff298cf46b3dca0d.zip |
doc: document uv_fs_realpath caveats
Fixes: https://github.com/libuv/libuv/issues/1017
PR-URL: https://github.com/libuv/libuv/pull/1026
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Imran Iqbal <imran@imraniqbal.org>
Diffstat (limited to 'docs/src')
-rw-r--r-- | docs/src/fs.rst | 21 |
1 files changed, 20 insertions, 1 deletions
diff --git a/docs/src/fs.rst b/docs/src/fs.rst index 50c0de46..8e4a98f2 100644 --- a/docs/src/fs.rst +++ b/docs/src/fs.rst @@ -288,7 +288,26 @@ API .. c:function:: int uv_fs_realpath(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb) - Equivalent to :man:`realpath(3)` on Unix. Windows uses ``GetFinalPathNameByHandle()``. + Equivalent to :man:`realpath(3)` on Unix. Windows uses `GetFinalPathNameByHandle <https://msdn.microsoft.com/en-us/library/windows/desktop/aa364962(v=vs.85).aspx>`_. + + .. warning:: + This function has certain platform specific caveats that were discovered when used in Node. + + * macOS and other BSDs: this function will fail with UV_ELOOP if more than 32 symlinks are + found while resolving the given path. This limit is hardcoded and cannot be sidestepped. + * Windows: while this function works in the common case, there are a number of corner cases + where it doesn't: + + - Paths in ramdisk volumes created by tools which sidestep the Volume Manager (such as ImDisk) + cannot be resolved. + - Inconsistent casing when using drive letters. + - Resolved path bypasses subst'd drives. + + While this function can still be used, it's not recommended if scenarios such as the + above need to be supported. + + The background story and some more details on these issues can be checked + `here <https://github.com/nodejs/node/issues/7726>`_. .. note:: This function is not implemented on Windows XP and Windows Server 2003. |