Skip to content

doc: improve server.listen() random port #7976

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
phillipj wants to merge 1 commit into from
Closed

doc: improve server.listen() random port #7976

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
doc: improve server.listen() random port 
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
phillipj committed Aug 5, 2016
commit 57e95d9c4c5977d17363b2fff5aaad8b250fe4bc
8 changes: 5 additions & 3 deletions doc/api/http.md
View file
Open in desktop
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
View file
Open in desktop
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