Skip to content

Commit

Permalink
doc: improve server.listen() random port
Browse files Browse the repository at this point in the history
Minor rewording related to making a server listen to a random port,
and added how to retrieve which port was randomly chosen by the OS.

Also changed documented `server.listen()` signature as it does in fact
not require `port` to be provided.

PR-URL: #7976
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
  • Loading branch information
phillipj committed Aug 5, 2016
1 parent 5d6d3ee commit 66af6a9
Show file tree
Hide file tree
Showing 2 changed files with 14 additions and 11 deletions.
8 changes: 5 additions & 3 deletions doc/api/http.md
Original file line number Diff line number Diff line change
Expand Up @@ -691,15 +691,17 @@ Start a UNIX socket server listening for connections on the given `path`.
This function is asynchronous. `callback` will be added as a listener for the
[`'listening'`][] event. See also [`net.Server.listen(path)`][].

### server.listen(port[, hostname][, backlog][, callback])
### server.listen([port][, hostname][, backlog][, callback])
<!-- YAML
added: v0.1.90
-->

Begin accepting connections on the specified `port` and `hostname`. If the
`hostname` is omitted, the server will accept connections on any IPv6 address
(`::`) when IPv6 is available, or any IPv4 address (`0.0.0.0`) otherwise. Use a
port value of `0` to have the operating system assign an available port.
(`::`) when IPv6 is available, or any IPv4 address (`0.0.0.0`) otherwise.
Omit the port argument, or use a port value of `0`, to have the operating system
assign a random port, which can be retrieved by using `server.address().port`
after the `'listening'` event has been emitted.

To listen to a unix socket, supply a filename instead of port and hostname.

Expand Down
17 changes: 9 additions & 8 deletions doc/api/net.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,8 +73,7 @@ var server = net.createServer((socket) => {

// grab a random port.
server.listen(() => {
address = server.address();
console.log('opened server on %j', address);
console.log('opened server on', server.address());
});
```

Expand Down Expand Up @@ -140,7 +139,7 @@ The last parameter `callback` will be added as a listener for the
[`'listening'`][] event.

The parameter `backlog` behaves the same as in
[`server.listen(port[, hostname][, backlog][, callback])`][`server.listen(port, host, backlog, callback)`].
[`server.listen([port][, hostname][, backlog][, callback])`][`server.listen(port, host, backlog, callback)`].

### server.listen(options[, callback])
<!-- YAML
Expand All @@ -157,7 +156,7 @@ added: v0.11.14

The `port`, `host`, and `backlog` properties of `options`, as well as the
optional callback function, behave as they do on a call to
[`server.listen(port[, hostname][, backlog][, callback])`][`server.listen(port, host, backlog, callback)`].
[`server.listen([port][, hostname][, backlog][, callback])`][`server.listen(port, host, backlog, callback)`].
Alternatively, the `path` option can be used to specify a UNIX socket.

If `exclusive` is `false` (default), then cluster workers will use the same
Expand Down Expand Up @@ -209,17 +208,19 @@ double-backslashes, such as:
path.join('\\\\?\\pipe', process.cwd(), 'myctl'))

The parameter `backlog` behaves the same as in
[`server.listen(port[, hostname][, backlog][, callback])`][`server.listen(port, host, backlog, callback)`].
[`server.listen([port][, hostname][, backlog][, callback])`][`server.listen(port, host, backlog, callback)`].

### server.listen(port[, hostname][, backlog][, callback])
### server.listen([port][, hostname][, backlog][, callback])
<!-- YAML
added: v0.1.90
-->

Begin accepting connections on the specified `port` and `hostname`. If the
`hostname` is omitted, the server will accept connections on any IPv6 address
(`::`) when IPv6 is available, or any IPv4 address (`0.0.0.0`) otherwise. Use a
port value of `0` to have the operating system assign an available port.
(`::`) when IPv6 is available, or any IPv4 address (`0.0.0.0`) otherwise.
Omit the port argument, or use a port value of `0`, to have the operating system
assign a random port, which can be retrieved by using `server.address().port`
after the `'listening'` event has been emitted.

Backlog is the maximum length of the queue of pending connections.
The actual length will be determined by the OS through sysctl settings such as
Expand Down

0 comments on commit 66af6a9

Please sign in to comment.