Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions doc/api/os.md
Original file line number Diff line number Diff line change
Expand Up @@ -504,6 +504,33 @@ On POSIX systems, the operating system release is determined by calling
available, `GetVersionExW()` will be used. See
<https://en.wikipedia.org/wiki/Uname#Examples> for more information.

## `os.guessFileDescriptorType(fd)`

<!-- YAML
added: REPLACEME
-->

* `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`.
Expand Down Expand Up @@ -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
Expand Down
6 changes: 6 additions & 0 deletions lib/internal/util.js
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,7 @@ const {

const {
codes: {
ERR_INVALID_FD,
ERR_NO_CRYPTO,
ERR_NO_TYPESCRIPT,
ERR_UNKNOWN_SIGNAL,
Expand Down Expand Up @@ -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];
}
Expand Down
3 changes: 2 additions & 1 deletion lib/os.js
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down Expand Up @@ -329,6 +329,7 @@ module.exports = {
uptime: getUptime,
version: getOSVersion,
machine: getMachine,
guessFileDescriptorType,
};

ObjectFreeze(constants.signals);
Expand Down
4 changes: 3 additions & 1 deletion src/node_util.cc
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}
}

Expand Down
28 changes: 28 additions & 0 deletions test/pseudo-tty/test-os-guessFileDescriptorType.js
Original file line number Diff line number Diff line change
@@ -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' }));
Empty file.
Loading