1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: general improvements to os.md copy

Browse Source 
PR-URL: https://github.com/nodejs/node/pull/7124
Reviewed-By: Brian White <mscdex@mscdex.net>
This commit is contained in:
James M Snell 2016-06-02 18:04:05 -07:00
parent f3d5efa3ee
commit ecc48a154d
1 changed files with 227 additions and 117 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

344
doc/api/os.md
View File

@ -2,25 +2,36 @@
Stability: 2 - Stable
Provides a few basic operating-system related utility functions.
The `os` module provides a number of operating system-related utility methods.
It can be accessed using:
Use `require('os')` to access this module.
```js
const os = require('os');
```
## os.EOL
<!-- YAML
added: v0.7.8
-->
A constant defining the appropriate End-of-line marker for the operating
system.
A string constant defining the operating system-specific end-of-line marker:
* `\n` on POSIX
* `\r\n` on Windows
## os.arch()
<!-- YAML
added: v0.5.0
-->
Returns the operating system CPU architecture. Possible values are `'x64'`,
`'arm'` and `'ia32'`. Returns the value of [`process.arch`][].
The `os.arch()` method returns a string identifying the operating system CPU
architecture *for which the Node.js binary was compiled*.
The current possible values are: `'arm'`, `'arm64'`, `'ia32'`, `'mips'`,
`'mipsel'`, `'ppc'`, `'ppc64'`, `'s390'`, `'s390x'`, `'x32'`, `'x64'`, and
`'x86'`.
Equivalent to [`process.arch`][].
## os.constants
@ -33,80 +44,116 @@ defined are described in [OS Constants][].
added: v0.3.3
-->
Returns an array of objects containing information about each CPU/core
installed: model, speed (in MHz), and times (an object containing the number of
milliseconds the CPU/core spent in: user, nice, sys, idle, and irq).
The `os.cpus()` method returns an array of objects containing information about
each CPU/core installed.
Example inspection of os.cpus:
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.
For example:
```js
[ { model: 'Intel(R) Core(TM) i7 CPU 860 @ 2.80GHz',
[
{
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',
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',
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',
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 } },
{ model: 'Intel(R) Core(TM) i7 CPU 860 @ 2.80GHz',
times: {
user: 256880,
nice: 0,
sys: 19430,
idle: 1070905480,
irq: 20
}
},
{
model: 'Intel(R) Core(TM) i7 CPU 860 @ 2.80GHz',
speed: 2926,
times:
{ user: 511580,
nice: 20,
sys: 40900,
idle: 1070842510,
irq: 0 } },
{ model: 'Intel(R) Core(TM) i7 CPU 860 @ 2.80GHz',
times: {
user: 511580,
nice: 20,
sys: 40900,
idle: 1070842510,
irq: 0
}
},
{
model: 'Intel(R) Core(TM) i7 CPU 860 @ 2.80GHz',
speed: 2926,
times:
{ user: 291660,
nice: 0,
sys: 34360,
idle: 1070888000,
irq: 10 } },
{ model: 'Intel(R) Core(TM) i7 CPU 860 @ 2.80GHz',
times: {
user: 291660,
nice: 0,
sys: 34360,
idle: 1070888000,
irq: 10
}
},
{
model: 'Intel(R) Core(TM) i7 CPU 860 @ 2.80GHz',
speed: 2926,
times:
{ user: 308260,
nice: 0,
sys: 55410,
idle: 1071129970,
irq: 880 } },
{ model: 'Intel(R) Core(TM) i7 CPU 860 @ 2.80GHz',
times: {
user: 308260,
nice: 0,
sys: 55410,
idle: 1071129970,
irq: 880
}
},
{
model: 'Intel(R) Core(TM) i7 CPU 860 @ 2.80GHz',
speed: 2926,
times:
{ user: 266450,
nice: 1480,
sys: 34920,
idle: 1072572010,
irq: 30 } } ]
times: {
user: 266450,
nice: 1480,
sys: 34920,
idle: 1072572010,
irq: 30
}
}
]
```
Note that since `nice` values are UNIX centric in Windows the `nice` values of
*Note*: Because `nice` values are UNIX-specific, on Windows the `nice` values of
all processors are always 0.
## os.endianness()
@ -114,124 +161,186 @@ all processors are always 0.
added: v0.9.4
-->
Returns the endianness of the CPU. Possible values are `'BE'` for big endian
or `'LE'` for little endian.
The `os.endianness()` method returns a string identifying the endianness of the
CPU *for which the Node.js binary was compiled*.
Possible values are:
* `'BE'` for big endian
* `'LE'` for little endian.
## os.freemem()
<!-- YAML
added: v0.3.3
-->
Returns the amount of free system memory in bytes.
The `os.freemem()` method returns the amount of free system memory in bytes as
an integer.
## os.homedir()
<!-- YAML
added: v2.3.0
-->
Returns the home directory of the current user.
The `os.homedir()` method returns the home directory of the current user as a
string.
## os.hostname()
<!-- YAML
added: v0.3.3
-->
Returns the hostname of the operating system.
The `os.hostname()` method returns the hostname of the operating system as a
string.
## os.loadavg()
<!-- YAML
added: v0.3.3
-->
Returns an array containing the 1, 5, and 15 minute load averages.
The `os.loadavg()` method 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. As a rule of thumb, the load
average should ideally be less than the number of logical CPUs in the system.
The load average is a very UNIX-y concept; there is no real equivalent on
Windows platforms. That is why this function always returns `[0, 0, 0]` on
Windows.
The load average is a UNIX-specific concept with no real equivalent on
Windows platforms. On Windows, the return value is always `[0, 0, 0]`.
## os.networkInterfaces()
<!-- YAML
added: v0.6.0
-->
Get a list of network interfaces:
The `os.networkInterfaces()` method returns an object containing only 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 address
* `netmask` {String} The IPv4 or IPv6 network mask
* `family` {String} Either `IPv4` or `IPv6`
* `mac` {String} The MAC address of the network interface
* `internal` {boolean} `true` if the network interface is a loopback or
similar interface that is not remotely accessible; otherwise `false`
* `scopeid` {number} The numeric IPv6 scope ID (only specified when `family`
is `IPv6`)
```js
{ lo:
[ { address: '127.0.0.1',
netmask: '255.0.0.0',
family: 'IPv4',
mac: '00:00:00:00:00:00',
internal: true },
{ address: '::1',
netmask: 'ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff',
family: 'IPv6',
mac: '00:00:00:00:00:00',
internal: true } ],
eth0:
[ { address: '192.168.1.108',
netmask: '255.255.255.0',
family: 'IPv4',
mac: '01:02:03:0a:0b:0c',
internal: false },
{ address: 'fe80::a00:27ff:fe4e:66a1',
netmask: 'ffff:ffff:ffff:ffff::',
family: 'IPv6',
mac: '01:02:03:0a:0b:0c',
internal: false } ] }
{
lo: [
{
address: '127.0.0.1',
netmask: '255.0.0.0',
family: 'IPv4',
mac: '00:00:00:00:00:00',
internal: true
},
{
address: '::1',
netmask: 'ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff',
family: 'IPv6',
mac: '00:00:00:00:00:00',
internal: true
}
],
eth0: [
{
address: '192.168.1.108',
netmask: '255.255.255.0',
family: 'IPv4',
mac: '01:02:03:0a:0b:0c',
internal: false
},
{
address: 'fe80::a00:27ff:fe4e:66a1',
netmask: 'ffff:ffff:ffff:ffff::',
family: 'IPv6',
mac: '01:02:03:0a:0b:0c',
internal: false
}
]
}
```
Note that due to the underlying implementation this will only return network
interfaces that have been assigned an address.
## os.platform()
<!-- YAML
added: v0.5.0
-->
Returns the operating system platform. Possible values are `'darwin'`,
`'freebsd'`, `'linux'`, `'sunos'` or `'win32'`. Returns the value of
[`process.platform`][].
The `os.platform()` method returns a string identifying the operating system
platform as set during compile time of Node.js.
Currently possible values are:
* `'aix'`
* `'darwin'`
* `'freebsd'`
* `'linux'`
* `'openbsd'`
* `'sunos'`
* `'win32'`
Equivalent to [`process.platform`][].
*Note*: The value `'android'` may also be returned if the Node.js is built on
the Android operating system. However, Android support in Node.js is considered
to be experimental at this time.
## os.release()
<!-- YAML
added: v0.3.3
-->
Returns the operating system release.
The `os.release()` method returns a string identifying the operating system
release.
*Note*: On POSIX systems, the operating system release is determined by calling
uname(3). On Windows, `GetVersionExW()` is used. Please see
https://en.wikipedia.org/wiki/Uname#Examples for more information.
## os.tmpdir()
<!-- YAML
added: v0.9.9
-->
Returns the operating system's default directory for temporary files.
The `os.tmpdir()` method returns a string specifying the operating system's
default directory for temporary files.
## os.totalmem()
<!-- YAML
added: v0.3.3
-->
Returns the total amount of system memory in bytes.
The `os.totalmem()` method returns the total amount of system memory in bytes
as an integer.
## os.type()
<!-- YAML
added: v0.3.3
-->
Returns the operating system name. For example `'Linux'` on Linux, `'Darwin'`
on OS X and `'Windows_NT'` on Windows.
The `os.type()` method returns a string identifying the operating system name
as returned by uname(3). For example `'Linux'` on Linux, `'Darwin'` on OS X and
`'Windows_NT'` on Windows.
Please see https://en.wikipedia.org/wiki/Uname#Examples for additional
information about the output of running uname(3) on various operating systems.
## os.uptime()
<!-- YAML
added: v0.3.3
-->
Returns the system uptime in seconds.
The `os.uptime()` method returns the system uptime in number of seconds.
*Note*: Within Node.js' internals, this number is represented as a `double`.
However, fractional seconds are not returned and the value can typically be
treated as an integer.
## os.userInfo([options])
<!-- YAML
@ -243,13 +352,14 @@ added: v6.0.0
If `encoding` is set to `'buffer'`, the `username`, `shell`, and `homedir`
values will be `Buffer` instances. (Default: 'utf8')
Returns a subset of the password file entry for the current effective user. The
The `os.userInfo()` method 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 `userInfo()` comes directly from the
operating system. This differs from the result of `os.homedir()`, which queries
several environment variables for the home directory before falling back to the
The value of `homedir` returned by `os.userInfo()` is provided by the operating
system. This differs from the result of `os.homedir()`, which queries several
environment variables for the home directory before falling back to the
operating system response.
## OS Constants
@ -273,7 +383,7 @@ The following signal constants are exported by `os.constants.signals`:
</tr>
<tr>
<td><code>SIGINT</code></td>
<td>Sent to indicate when a user wishes to interrupt a process
<td>Sent to indicate when a user wishes to interrupt a process
(`(Ctrl+C)`).</td>
</tr>
<tr>
@ -304,7 +414,7 @@ The following signal constants are exported by `os.constants.signals`:
</tr>
<tr>
<td><code>SIGFPE</code></td>
<td>Sent to a process to notify that it has performed an illegal arithmetic
<td>Sent to a process to notify that it has performed an illegal arithmetic
operation.</td>
</tr>
<tr>