doc/api/os.md
<!-- source_link=lib/os.js -->Stability: 2 - Stable
The node:os module provides operating system-related utility methods and
properties. It can be accessed using:
import os from 'node:os';
const os = require('node:os');
os.EOLThe operating system-specific end-of-line marker.
\n on POSIX\r\n on Windowsos.availableParallelism()Returns an estimate of the default amount of parallelism a program should use. Always returns a value greater than zero.
This function is a small wrapper about libuv's uv_available_parallelism().
os.arch()Returns the operating system CPU architecture for which the Node.js binary was
compiled. Possible values are 'arm', 'arm64', 'ia32', 'loong64',
'mips', 'mipsel', 'ppc64', 'riscv64', 's390x', and 'x64'.
The return value is equivalent to process.arch.
os.constantsContains commonly used operating system-specific constants for error codes, process signals, and so on. The specific constants defined are described in OS constants.
os.cpus()Returns an array of objects containing information about each logical CPU core.
The array will be empty if no CPU information is available, such as if the
/proc file system is unavailable.
The properties included on each object include:
model {string}speed {number} (in MHz)times {Object}
user {number} The number of milliseconds the CPU has spent in user mode.nice {number} The number of milliseconds the CPU has spent in nice mode.sys {number} The number of milliseconds the CPU has spent in sys mode.idle {number} The number of milliseconds the CPU has spent in idle mode.irq {number} The number of milliseconds the CPU has spent in irq mode.[
{
model: 'Intel(R) Core(TM) i7 CPU 860 @ 2.80GHz',
speed: 2926,
times: {
user: 252020,
nice: 0,
sys: 30340,
idle: 1070356870,
irq: 0,
},
},
{
model: 'Intel(R) Core(TM) i7 CPU 860 @ 2.80GHz',
speed: 2926,
times: {
user: 306960,
nice: 0,
sys: 26980,
idle: 1071569080,
irq: 0,
},
},
{
model: 'Intel(R) Core(TM) i7 CPU 860 @ 2.80GHz',
speed: 2926,
times: {
user: 248450,
nice: 0,
sys: 21750,
idle: 1070919370,
irq: 0,
},
},
{
model: 'Intel(R) Core(TM) i7 CPU 860 @ 2.80GHz',
speed: 2926,
times: {
user: 256880,
nice: 0,
sys: 19430,
idle: 1070905480,
irq: 20,
},
},
]
nice values are POSIX-only. On Windows, the nice values of all processors
are always 0.
os.cpus().length should not be used to calculate the amount of parallelism
available to an application. Use
os.availableParallelism() for this purpose.
os.devNullThe platform-specific file path of the null device.
\\.\nul on Windows/dev/null on POSIXos.endianness()Returns a string identifying the endianness of the CPU for which the Node.js binary was compiled.
Possible values are 'BE' for big endian and 'LE' for little endian.
os.freemem()Returns the amount of free system memory in bytes as an integer.
os.getPriority([pid])pid {integer} The process ID to retrieve scheduling priority for.
Default: 0.Returns the scheduling priority for the process specified by pid. If pid is
not provided or is 0, the priority of the current process is returned.
os.homedir()Returns the string path of the current user's home directory.
On POSIX, it uses the $HOME environment variable if defined. Otherwise it
uses the effective UID to look up the user's home directory.
On Windows, it uses the USERPROFILE environment variable if defined.
Otherwise it uses the path to the profile directory of the current user.
os.hostname()Returns the host name of the operating system as a string.
os.loadavg()Returns an array containing the 1, 5, and 15 minute load averages.
The load average is a measure of system activity calculated by the operating system and expressed as a fractional number.
The load average is a Unix-specific concept. On Windows, the return value is
always [0, 0, 0].
os.machine()Returns the machine type as a string, such as arm, arm64, aarch64,
mips, mips64, ppc64, ppc64le, s390x, i386, i686, x86_64.
On POSIX systems, the machine type is determined by calling
uname(3). On Windows, RtlGetVersion() is used, and if it is not
available, GetVersionExW() will be used. See
https://en.wikipedia.org/wiki/Uname#Examples for more information.
os.networkInterfaces()Returns an object containing network interfaces that have been assigned a network address.
Each key on the returned object identifies a network interface. The associated value is an array of objects that each describe an assigned network address.
The properties available on the assigned network address object include:
address {string} The assigned IPv4 or IPv6 addressnetmask {string} The IPv4 or IPv6 network maskfamily {string} Either IPv4 or IPv6mac {string} The MAC address of the network interfaceinternal {boolean} true if the network interface is a loopback or
similar interface that is not remotely accessible; otherwise falsescopeid {number} The numeric IPv6 scope ID (only specified when family
is IPv6)cidr {string} The assigned IPv4 or IPv6 address with the routing prefix
in CIDR notation. If the netmask is invalid, this property is set
to null.{
lo: [
{
address: '127.0.0.1',
netmask: '255.0.0.0',
family: 'IPv4',
mac: '00:00:00:00:00:00',
internal: true,
cidr: '127.0.0.1/8'
},
{
address: '::1',
netmask: 'ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff',
family: 'IPv6',
mac: '00:00:00:00:00:00',
scopeid: 0,
internal: true,
cidr: '::1/128'
}
],
eth0: [
{
address: '192.168.1.108',
netmask: '255.255.255.0',
family: 'IPv4',
mac: '01:02:03:0a:0b:0c',
internal: false,
cidr: '192.168.1.108/24'
},
{
address: 'fe80::a00:27ff:fe4e:66a1',
netmask: 'ffff:ffff:ffff:ffff::',
family: 'IPv6',
mac: '01:02:03:0a:0b:0c',
scopeid: 1,
internal: false,
cidr: 'fe80::a00:27ff:fe4e:66a1/64'
}
]
}
os.platform()Returns a string identifying the operating system platform for which
the Node.js binary was compiled. The value is set at compile time.
Possible values are 'aix', 'darwin', 'freebsd','linux',
'openbsd', 'sunos', and 'win32'.
The return value is equivalent to process.platform.
The value 'android' may also be returned if Node.js is built on the Android
operating system. Android support is experimental.
os.release()Returns the operating system as a string.
On POSIX systems, the operating system release is determined by calling
uname(3). On Windows, GetVersionExW() is used. See
https://en.wikipedia.org/wiki/Uname#Examples for more information.
os.setPriority([pid, ]priority)pid {integer} The process ID to set scheduling priority for.
Default: 0.priority {integer} The scheduling priority to assign to the process.Attempts to set the scheduling priority for the process specified by pid. If
pid is not provided or is 0, the process ID of the current process is used.
The priority input must be an integer between -20 (high priority) and 19
(low priority). Due to differences between Unix priority levels and Windows
priority classes, priority is mapped to one of six priority constants in
os.constants.priority. When retrieving a process priority level, this range
mapping may cause the return value to be slightly different on Windows. To avoid
confusion, set priority to one of the priority constants.
On Windows, setting priority to PRIORITY_HIGHEST requires elevated user
privileges. Otherwise the set priority will be silently reduced to
PRIORITY_HIGH.
os.tmpdir()Returns the operating system's default directory for temporary files as a string.
On Windows, the result can be overridden by TEMP and TMP environment variables, and
TEMP takes precedence over TMP. If neither is set, it defaults to %SystemRoot%\temp
or %windir%\temp.
On non-Windows platforms, TMPDIR, TMP and TEMP environment variables will be checked
to override the result of this method, in the described order. If none of them is set, it
defaults to /tmp.
Some operating system distributions would either configure TMPDIR (non-Windows) or
TEMP and TMP (Windows) by default without additional configurations by the system
administrators. The result of os.tmpdir() typically reflects the system preference
unless it's explicitly overridden by the users.
os.totalmem()Returns the total amount of system memory in bytes as an integer.
os.type()Returns the operating system name as returned by uname(3). For example, it
returns 'Linux' on Linux, 'Darwin' on macOS, and 'Windows_NT' on Windows.
See https://en.wikipedia.org/wiki/Uname#Examples for additional information
about the output of running uname(3) on various operating systems.
os.uptime()Returns the system uptime in number of seconds.
os.userInfo([options])options {Object}
encoding {string} Character encoding used to interpret resulting strings.
If encoding is set to 'buffer', the username, shell, and homedir
values will be Buffer instances. Default: 'utf8'.Returns information about the currently effective user. On POSIX platforms,
this is typically a subset of the password file. The returned object includes
the username, uid, gid, shell, and homedir. On Windows, the uid and
gid fields are -1, and shell is null.
The value of homedir returned by os.userInfo() is provided by the operating
system. This differs from the result of os.homedir(), which queries
environment variables for the home directory before falling back to the
operating system response.
Throws a SystemError if a user has no username or homedir.
os.version()Returns a string identifying the kernel version.
On POSIX systems, the operating system release is determined by calling
uname(3). On Windows, RtlGetVersion() is used, and if it is not
available, GetVersionExW() will be used. See
https://en.wikipedia.org/wiki/Uname#Examples for more information.
The following constants are exported by os.constants.
Not all constants will be available on every operating system.
The following signal constants are exported by os.constants.signals.
The following error constants are exported by os.constants.errno.
The following error codes are specific to the Windows operating system.
<table> <tr> <th>Constant</th> <th>Description</th> </tr> <tr> <td><code>WSAEINTR</code></td> <td>Indicates an interrupted function call.</td> </tr> <tr> <td><code>WSAEBADF</code></td> <td>Indicates an invalid file handle.</td> </tr> <tr> <td><code>WSAEACCES</code></td> <td>Indicates insufficient permissions to complete the operation.</td> </tr> <tr> <td><code>WSAEFAULT</code></td> <td>Indicates an invalid pointer address.</td> </tr> <tr> <td><code>WSAEINVAL</code></td> <td>Indicates that an invalid argument was passed.</td> </tr> <tr> <td><code>WSAEMFILE</code></td> <td>Indicates that there are too many open files.</td> </tr> <tr> <td><code>WSAEWOULDBLOCK</code></td> <td>Indicates that a resource is temporarily unavailable.</td> </tr> <tr> <td><code>WSAEINPROGRESS</code></td> <td>Indicates that an operation is currently in progress.</td> </tr> <tr> <td><code>WSAEALREADY</code></td> <td>Indicates that an operation is already in progress.</td> </tr> <tr> <td><code>WSAENOTSOCK</code></td> <td>Indicates that the resource is not a socket.</td> </tr> <tr> <td><code>WSAEDESTADDRREQ</code></td> <td>Indicates that a destination address is required.</td> </tr> <tr> <td><code>WSAEMSGSIZE</code></td> <td>Indicates that the message size is too long.</td> </tr> <tr> <td><code>WSAEPROTOTYPE</code></td> <td>Indicates the wrong protocol type for the socket.</td> </tr> <tr> <td><code>WSAENOPROTOOPT</code></td> <td>Indicates a bad protocol option.</td> </tr> <tr> <td><code>WSAEPROTONOSUPPORT</code></td> <td>Indicates that the protocol is not supported.</td> </tr> <tr> <td><code>WSAESOCKTNOSUPPORT</code></td> <td>Indicates that the socket type is not supported.</td> </tr> <tr> <td><code>WSAEOPNOTSUPP</code></td> <td>Indicates that the operation is not supported.</td> </tr> <tr> <td><code>WSAEPFNOSUPPORT</code></td> <td>Indicates that the protocol family is not supported.</td> </tr> <tr> <td><code>WSAEAFNOSUPPORT</code></td> <td>Indicates that the address family is not supported.</td> </tr> <tr> <td><code>WSAEADDRINUSE</code></td> <td>Indicates that the network address is already in use.</td> </tr> <tr> <td><code>WSAEADDRNOTAVAIL</code></td> <td>Indicates that the network address is not available.</td> </tr> <tr> <td><code>WSAENETDOWN</code></td> <td>Indicates that the network is down.</td> </tr> <tr> <td><code>WSAENETUNREACH</code></td> <td>Indicates that the network is unreachable.</td> </tr> <tr> <td><code>WSAENETRESET</code></td> <td>Indicates that the network connection has been reset.</td> </tr> <tr> <td><code>WSAECONNABORTED</code></td> <td>Indicates that the connection has been aborted.</td> </tr> <tr> <td><code>WSAECONNRESET</code></td> <td>Indicates that the connection has been reset by the peer.</td> </tr> <tr> <td><code>WSAENOBUFS</code></td> <td>Indicates that there is no buffer space available.</td> </tr> <tr> <td><code>WSAEISCONN</code></td> <td>Indicates that the socket is already connected.</td> </tr> <tr> <td><code>WSAENOTCONN</code></td> <td>Indicates that the socket is not connected.</td> </tr> <tr> <td><code>WSAESHUTDOWN</code></td> <td>Indicates that data cannot be sent after the socket has been shutdown.</td> </tr> <tr> <td><code>WSAETOOMANYREFS</code></td> <td>Indicates that there are too many references.</td> </tr> <tr> <td><code>WSAETIMEDOUT</code></td> <td>Indicates that the connection has timed out.</td> </tr> <tr> <td><code>WSAECONNREFUSED</code></td> <td>Indicates that the connection has been refused.</td> </tr> <tr> <td><code>WSAELOOP</code></td> <td>Indicates that a name cannot be translated.</td> </tr> <tr> <td><code>WSAENAMETOOLONG</code></td> <td>Indicates that a name was too long.</td> </tr> <tr> <td><code>WSAEHOSTDOWN</code></td> <td>Indicates that a network host is down.</td> </tr> <tr> <td><code>WSAEHOSTUNREACH</code></td> <td>Indicates that there is no route to a network host.</td> </tr> <tr> <td><code>WSAENOTEMPTY</code></td> <td>Indicates that the directory is not empty.</td> </tr> <tr> <td><code>WSAEPROCLIM</code></td> <td>Indicates that there are too many processes.</td> </tr> <tr> <td><code>WSAEUSERS</code></td> <td>Indicates that the user quota has been exceeded.</td> </tr> <tr> <td><code>WSAEDQUOT</code></td> <td>Indicates that the disk quota has been exceeded.</td> </tr> <tr> <td><code>WSAESTALE</code></td> <td>Indicates a stale file handle reference.</td> </tr> <tr> <td><code>WSAEREMOTE</code></td> <td>Indicates that the item is remote.</td> </tr> <tr> <td><code>WSASYSNOTREADY</code></td> <td>Indicates that the network subsystem is not ready.</td> </tr> <tr> <td><code>WSAVERNOTSUPPORTED</code></td> <td>Indicates that the <code>winsock.dll</code> version is out of range.</td> </tr> <tr> <td><code>WSANOTINITIALISED</code></td> <td>Indicates that successful WSAStartup has not yet been performed.</td> </tr> <tr> <td><code>WSAEDISCON</code></td> <td>Indicates that a graceful shutdown is in progress.</td> </tr> <tr> <td><code>WSAENOMORE</code></td> <td>Indicates that there are no more results.</td> </tr> <tr> <td><code>WSAECANCELLED</code></td> <td>Indicates that an operation has been canceled.</td> </tr> <tr> <td><code>WSAEINVALIDPROCTABLE</code></td> <td>Indicates that the procedure call table is invalid.</td> </tr> <tr> <td><code>WSAEINVALIDPROVIDER</code></td> <td>Indicates an invalid service provider.</td> </tr> <tr> <td><code>WSAEPROVIDERFAILEDINIT</code></td> <td>Indicates that the service provider failed to initialized.</td> </tr> <tr> <td><code>WSASYSCALLFAILURE</code></td> <td>Indicates a system call failure.</td> </tr> <tr> <td><code>WSASERVICE_NOT_FOUND</code></td> <td>Indicates that a service was not found.</td> </tr> <tr> <td><code>WSATYPE_NOT_FOUND</code></td> <td>Indicates that a class type was not found.</td> </tr> <tr> <td><code>WSA_E_NO_MORE</code></td> <td>Indicates that there are no more results.</td> </tr> <tr> <td><code>WSA_E_CANCELLED</code></td> <td>Indicates that the call was canceled.</td> </tr> <tr> <td><code>WSAEREFUSED</code></td> <td>Indicates that a database query was refused.</td> </tr> </table>If available on the operating system, the following constants
are exported in os.constants.dlopen. See dlopen(3) for detailed
information.
The following process scheduling constants are exported by
os.constants.priority.