diff --git a/doc/api/os.md b/doc/api/os.md index a2592a2f20cc..dca23066974f 100644 --- a/doc/api/os.md +++ b/doc/api/os.md @@ -504,6 +504,33 @@ On POSIX systems, the operating system release is determined by calling available, `GetVersionExW()` will be used. See for more information. +## `os.guessFileDescriptorType(fd)` + + + +* `fd` {integer} The file descriptor number to try and guess the type of. + +* Returns: {string} + +Returns the type of the file descriptor passed in. If `fd` is not a non-negative +32-bit integer, an [`ERR_INVALID_FD`][] error is thrown. If `fd` does not refer +to an open file descriptor, `'UNKNOWN'` is returned. +A common use case for this function is checking whether standard input is passed into your process, +and if it is, if it can be consumed by the process. For example, on Unix systems, if the type is `TTY`, it means +you can prompt the user for new data while the process is running, and if it's `FILE` or `PIPE`, it means there is data +available, but you shouldn't try to prompt for more. + +Currently, the following types for a file descriptor can be returned: + +* `'TCP'` +* `'TTY'` +* `'UDP'` +* `'FILE'` +* `'PIPE'` +* `'UNKNOWN'` + ## OS constants The following constants are exported by `os.constants`. @@ -1370,6 +1397,7 @@ The following process scheduling constants are exported by [Android building]: https://github.com/nodejs/node/blob/HEAD/BUILDING.md#android [EUID]: https://en.wikipedia.org/wiki/User_identifier#Effective_user_ID +[`ERR_INVALID_FD`]: errors.md#err_invalid_fd [`SystemError`]: errors.md#class-systemerror [`process.arch`]: process.md#processarch [`process.platform`]: process.md#processplatform diff --git a/lib/internal/util.js b/lib/internal/util.js index 2f72e636ab90..08df5d5ee3fc 100644 --- a/lib/internal/util.js +++ b/lib/internal/util.js @@ -50,6 +50,7 @@ const { const { codes: { + ERR_INVALID_FD, ERR_NO_CRYPTO, ERR_NO_TYPESCRIPT, ERR_UNKNOWN_SIGNAL, @@ -857,7 +858,12 @@ function getCIDR(address, netmask, family) { } const handleTypes = ['TCP', 'TTY', 'UDP', 'FILE', 'PIPE', 'UNKNOWN']; + function guessHandleType(fd) { + if (typeof fd !== 'number' || fd >> 0 !== fd || fd < 0) { + throw new ERR_INVALID_FD(fd); + } + const type = _guessHandleType(fd); return handleTypes[type]; } diff --git a/lib/os.js b/lib/os.js index 5e53879bd6d5..34b228c4edb1 100644 --- a/lib/os.js +++ b/lib/os.js @@ -40,7 +40,7 @@ const { }, hideStackFrames, } = require('internal/errors'); -const { getCIDR } = require('internal/util'); +const { getCIDR, guessHandleType: guessFileDescriptorType } = require('internal/util'); const { validateInt32 } = require('internal/validators'); const { @@ -329,6 +329,7 @@ module.exports = { uptime: getUptime, version: getOSVersion, machine: getMachine, + guessFileDescriptorType, }; ObjectFreeze(constants.signals); diff --git a/src/node_util.cc b/src/node_util.cc index e19ba77e264d..2fceb403f609 100644 --- a/src/node_util.cc +++ b/src/node_util.cc @@ -209,7 +209,9 @@ static uint32_t GetUVHandleTypeCode(const uv_handle_type type) { case UV_UNKNOWN_HANDLE: return 5; default: - ABORT(); + // The type is known by libuv, just not exposed to JS land, so report it + // as `UNKNOWN`. + return 5; } } diff --git a/test/pseudo-tty/test-os-guessFileDescriptorType.js b/test/pseudo-tty/test-os-guessFileDescriptorType.js new file mode 100644 index 000000000000..0efb4780aa99 --- /dev/null +++ b/test/pseudo-tty/test-os-guessFileDescriptorType.js @@ -0,0 +1,28 @@ +'use strict'; + +require('../common'); +const assert = require('node:assert'); +const { guessFileDescriptorType } = require('os'); + +assert.strictEqual(guessFileDescriptorType(0), 'TTY'); +assert.strictEqual(guessFileDescriptorType(1), 'TTY'); +assert.strictEqual(guessFileDescriptorType(2), 'TTY'); + +assert.strictEqual(guessFileDescriptorType(55555), 'UNKNOWN'); +assert.strictEqual(guessFileDescriptorType(2 ** 31 - 1), 'UNKNOWN'); + +[ + -1, + 1.1, + '1', + [], + {}, + () => {}, + 2 ** 31, + true, + false, + 1n, + Symbol(), + undefined, + null, +].forEach((val) => assert.throws(() => guessFileDescriptorType(val), { code: 'ERR_INVALID_FD' })); diff --git a/test/pseudo-tty/test-os-guessFileDescriptorType.out b/test/pseudo-tty/test-os-guessFileDescriptorType.out new file mode 100644 index 000000000000..e69de29bb2d1