aboutsummaryrefslogtreecommitdiff
path: root/docs/src
diff options
context:
space:
mode:
authorSaúl Ibarra Corretgé <saghul@gmail.com>2016-09-01 10:18:47 +0200
committerSaúl Ibarra Corretgé <saghul@gmail.com>2016-09-02 09:57:25 +0200
commit6938f6b0bdbcfd40d7e0cdd3ff298cf46b3dca0d (patch)
tree9c293546e11022a164ff2ee64ea79caf50459973 /docs/src
parenta7dfee3b02c70ca872c750fc60860d238623be69 (diff)
downloadlibuv-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.rst21
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.