From cb137eb15914a6436c55e8faeeb181021496be0d Mon Sep 17 00:00:00 2001 From: Ben Noordhuis Date: Tue, 7 Nov 2017 21:16:36 +0100 Subject: [PATCH] doc: document fs.realpath.native() Mea culpa, somehow I managed to drop the documentation commit while merging the pull request. This should have been included in commit 74023c072c ("fs: expose realpath(3) bindings") from this month. PR-URL: https://github.com/nodejs/node/pull/17059 Refs: https://github.com/nodejs/node/pull/15776 Reviewed-By: Anna Henningsen Reviewed-By: Colin Ihrig Reviewed-By: Evan Lucas Reviewed-By: Luigi Pinca Reviewed-By: Refael Ackermann --- doc/api/fs.md | 79 ++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 75 insertions(+), 4 deletions(-) diff --git a/doc/api/fs.md b/doc/api/fs.md index 06f889e47fba1f..c282b418d3b6f9 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -2028,8 +2028,21 @@ changes: * `err` {Error} * `resolvedPath` {string|Buffer} -Asynchronous realpath(3). The `callback` gets two arguments `(err, -resolvedPath)`. May use `process.cwd` to resolve relative paths. +Asynchronously computes the canonical pathname by resolving `.`, `..` and +symbolic links. + +Note that "canonical" does not mean "unique": hard links and bind mounts can +expose a file system entity through many pathnames. + +This function behaves like realpath(3), with some exceptions: + +1. No case conversion is performed on case-insensitive file systems. + +2. The maximum number of symbolic links is platform-independent and generally + (much) higher than what the native realpath(3) implementation supports. + +The `callback` gets two arguments `(err, resolvedPath)`. May use `process.cwd` +to resolve relative paths. Only paths that can be converted to UTF8 strings are supported. @@ -2041,6 +2054,33 @@ the path returned will be passed as a `Buffer` object. *Note*: If `path` resolves to a socket or a pipe, the function will return a system dependent name for that object. +## fs.realpath.native(path[, options], callback) + + +* `path` {string|Buffer|URL} +* `options` {string|Object} + * `encoding` {string} **Default:** `'utf8'` +* `callback` {Function} + * `err` {Error} + * `resolvedPath` {string|Buffer} + +Asynchronous realpath(3). + +The `callback` gets two arguments `(err, resolvedPath)`. + +Only paths that can be converted to UTF8 strings are supported. + +The optional `options` argument can be a string specifying an encoding, or an +object with an `encoding` property specifying the character encoding to use for +the path passed to the callback. If the `encoding` is set to `'buffer'`, +the path returned will be passed as a `Buffer` object. + +*Note*: On Linux, when Node.js is linked against musl libc, the procfs file +system must be mounted on `/proc` in order for this function to work. Glibc +does not have this restriction. + ## fs.realpathSync(path[, options]) + +* `path` {string|Buffer|URL} +* `options` {string|Object} + * `encoding` {string} **Default:** `'utf8'` + +Synchronous realpath(3). + +Only paths that can be converted to UTF8 strings are supported. + +The optional `options` argument can be a string specifying an encoding, or an +object with an `encoding` property specifying the character encoding to use for +the path passed to the callback. If the `encoding` is set to `'buffer'`, +the path returned will be passed as a `Buffer` object. + +*Note*: On Linux, when Node.js is linked against musl libc, the procfs file +system must be mounted on `/proc` in order for this function to work. Glibc +does not have this restriction. + ## fs.rename(oldPath, newPath, callback)