@ -3,20 +3,52 @@
> Stability: 2 - Stable
The `net` module provides an asynchronous network API for creating stream-based
servers ([`net.createServer()`][]) and clients ([`net.createConnection()`][])
that implement TCP or local communications (domain sockets on UNIX, named pipes
on Windows). It can be accessed using:
TCP or [IPC][] servers ([`net.createServer()`][]) and clients
([`net.createConnection()`][]).
It can be accessed using:
```js
const net = require('net');
```
## IPC Support
The `net` module supports IPC with named pipes on Windows, and UNIX domain
sockets on other operating systems.
### Identifying paths for IPC connections
[`net.connect()`][], [`net.createConnection()`][], [`server.listen()`][] and
[`socket.connect()`][] take a `path` parameter to identify IPC endpoints.
On UNIX, the local domain is also known as the UNIX domain. The path is a
filesystem path name. It gets truncated to `sizeof(sockaddr_un.sun_path) - 1` ,
which varies on different operating system between 91 and 107 bytes.
The typical values are 107 on Linux and 103 on OS X. The path is
subject to the same naming conventions and permissions checks as would be done
on file creation. It will be visible in the filesystem, and will *persist until
unlinked*.
On Windows, the local domain is implemented using a named pipe. The path *must*
refer to an entry in `\\?\pipe\` or `\\.\pipe\` . Any characters are permitted,
but the latter may do some processing of pipe names, such as resolving `..`
sequences. Despite appearances, the pipe name space is flat. Pipes will *not
persist*, they are removed when the last reference to them is closed. Do not
forget JavaScript string escaping requires paths to be specified with
double-backslashes, such as:
```js
net.createServer().listen(
path.join('\\\\?\\pipe', process.cwd(), 'myctl'))
```
## Class: net.Server
<!-- YAML
added: v0.1.90
-->
This class is used to create a TCP or local server.
This class is used to create a TCP or [IPC][] server.
## new net.Server([options][, connectionListener])
@ -129,17 +161,14 @@ Callback should take two arguments `err` and `count`.
### server.listen()
Start a server listening for connections. A `net.Server` can be a TCP or
local (domain sockets on UNIX, named pipes on Windows) server depending on
what it listens to.
*Note*: Unix named pipes (FIFOs) are not supported.
a [IPC][] server depending on what it listens to.
Possible signatures:
* [`server.listen(handle[, backlog][, callback])`][`server.listen(handle)`]
* [`server.listen(options[, callback])`][`server.listen(options)`]
* [`server.listen(path[, backlog][, callback])`][`server.listen(path)`]
for local servers
for [IPC][] servers
* [`server.listen([port][, host][, backlog][, callback])`][`server.listen(port, host)`]
for TCP servers
@ -201,13 +230,14 @@ added: v0.11.14
-->
* `options` {Object} Required. Supports the following properties:
* `port` {number} Optional.
* `host` {string} Optional.
* `path` {string} Optional. Will be ignored if `port` is specified.
* `backlog` {number} Optional. Common parameter of [`server.listen()`][]
* `port` {number}
* `host` {string}
* `path` {string} Will be ignored if `port` is specified. See
[Identifying paths for IPC connections][].
* `backlog` {number} Common parameter of [`server.listen()`][]
functions
* `exclusive` {boolean} Optional. Default to `false`
* `callback` {Function} Optional. Common parameter of [`server.listen()`][]
* `exclusive` {boolean} Default to `false`
* `callback` {Function} Common parameter of [`server.listen()`][]
functions
If `port` is specified, it behaves the same as
@ -235,32 +265,12 @@ server.listen({
added: v0.1.90
-->
* `path` {string}
* `path` {String} Path the server should listen to. See
[Identifying paths for IPC connections][].
* `backlog` {number} Common parameter of [`server.listen()`][] functions
* `callback` {Function} Common parameter of [`server.listen()`][] functions
Start a local socket server listening for connections on the given `path` .
On UNIX, the local domain is usually known as the UNIX domain. The path is a
filesystem path name. It gets truncated to `sizeof(sockaddr_un.sun_path)`
bytes, decreased by 1. It varies on different operating system between 91 and
107 bytes. The typical values are 107 on Linux and 103 on OS X. The path is
subject to the same naming conventions and permissions checks as would be done
on file creation, will be visible in the filesystem, and will *persist until
unlinked*.
On Windows, the local domain is implemented using a named pipe. The path *must*
refer to an entry in `\\?\pipe\` or `\\.\pipe\` . Any characters are permitted,
but the latter may do some processing of pipe names, such as resolving `..`
sequences. Despite appearances, the pipe name space is flat. Pipes will *not
persist*, they are removed when the last reference to them is closed. Do not
forget JavaScript string escaping requires paths to be specified with
double-backslashes, such as:
```js
net.createServer().listen(
path.join('\\\\?\\pipe', process.cwd(), 'myctl'))
```
Start a [IPC][] server listening for connections on the given `path` .
#### server.listen([port][, host][, backlog][, callback])
<!-- YAML
@ -331,35 +341,41 @@ Returns `server`.
added: v0.3.4
-->
This object is an abstraction of a TCP or local socket. `net.Socket`
instances implement a duplex Stream interface. They can be created by the
user and used as a client (with [`connect()`][]) or they can be created by Node.js
and passed to the user through the `'connection'` event of a server.
This class is an abstraction of a TCP socket or a streaming [IPC][] endpoint
(uses named pipes on Windows, and UNIX domain sockets otherwise). A
`net.Socket` is also a [duplex stream][], so it can be both readable and
writable, and it is also a [`EventEmitter`][].
A `net.Socket` can be created by the user and used directly to interact with
a server. For example, it is returned by [`net.createConnection()`][],
so the user can use it to talk to the server.
It can also be be created by Node.js and passed to the user when a connection
is received. For example, it is passed to the listeners of a
[`'connection'`][] event emitted on a [`net.Server`][], so the user can use
it to interact with the client.
### new net.Socket([options])
<!-- YAML
added: v0.3.4
-->
Construct a new socket object.
Creates a new socket object.
`options` is an object with the following defaults:
* `options` {Object} Available options are:
* `fd` : {number} If specified, wrap around an existing socket with
the given file descriptor, otherwise a new socket will be created.
* `allowHalfOpen` {boolean} Indicates whether half-opened TCP connections
are allowed. See [`net.createServer()`][] and the [`'end'`][] event
for details. Defaults to `false` .
* `readable` {boolean} Allow reads on the socket when a `fd` is passed,
otherwise ignored. Defaults to `false` .
* `writable` {boolean} Allow reads on the socket when a `fd` is passed,
otherwise ignored. Defaults to `false` .
* Returns: {net.Socket}
```js
{
fd: null,
allowHalfOpen: false,
readable: false,
writable: false
}
```
`fd` allows you to specify the existing file descriptor of socket.
Set `readable` and/or `writable` to `true` to allow reads and/or writes on this
socket (NOTE: Works only when `fd` is passed).
About `allowHalfOpen` , refer to [`net.createServer()`][] and [`'end'`][] event.
`net.Socket` instances are [`EventEmitter`][] with the following events:
The newly created socket can be either a TCP socket or a streaming [IPC][]
endpoint, depending on what it [`connect()`][`socket.connect()`] to.
### Event: 'close'
<!-- YAML
@ -377,7 +393,7 @@ added: v0.1.90
-->
Emitted when a socket connection is successfully established.
See [`connect()`][].
See [`net. createC onnection ()`][].
### Event: 'data'
<!-- YAML
@ -501,7 +517,26 @@ added: v0.5.3
The amount of bytes sent.
### socket.connect(options[, connectListener])
### socket.connect()
Initiate a connection on a given socket.
Possible signatures:
* [socket.connect(options[, connectListener])][`socket.connect(options)`]
* [socket.connect(path[, connectListener])][`socket.connect(path)`]
for [IPC][] connections.
* [socket.connect(port[, host][, connectListener])][`socket.connect(port, host)`]
for TCP connections.
This function is asynchronous. When the connection is established, the
[`'connect'`][] event will be emitted. If there is a problem connecting,
instead of a [`'connect'`][] event, an [`'error'`][] event will be emitted with
the error passed to the [`'error'`][] listener.
The last parameter `connectListener` , if supplied, will be added as a listener
for the [`'connect'`][] event **once** .
#### socket.connect(options[, connectListener])
<!-- YAML
added: v0.1.90
changes:
@ -515,56 +550,72 @@ changes:
description: The `hints` option is supported now.
-->
Opens the connection for a given socket.
For TCP sockets, `options` argument should be an object which specifies:
- `port` : Port the client should connect to (Required).
- `host` : Host the client should connect to. Defaults to `'localhost'` .
- `localAddress` : Local interface to bind to for network connections.
* `options` {Object}
* `connectListener` {Function} Common parameter of [`socket.connect()`][]
methods. Will be added as a listener for the [`'connect'`][] event once.
* Returns: {net.Socket} The socket itself.
- `localPort` : Local port to bind to for network connections.
Initiate a connection on a given socket. Normally this method is not needed,
the socket should be created and opened with [`net.createConnection()`][]. Use
this only if you are implementing a custom Socket.
- `family` : Version of IP stack. Defaults to `4` .
For TCP connections, available `options` are:
- `hints` : [`dns.lookup()` hints][]. Defaults to `0` .
* `port` {number} Required. Port the socket should connect to.
* `host` {string} Host the socket should connect to. Defaults to `'localhost'` .
* `localAddress` {string} Local address the socket should connect from.
* `localPort` {number} Local port the socket should connect from.
* `family` {number}: Version of IP stack, can be either 4 or 6. Defaults to 4.
* `hints` {number} Optional [`dns.lookup()` hints][].
* `lookup` {Function} Custom lookup function. Defaults to [`dns.lookup()`][].
- `lookup` : Custom lookup function. Defaults to `dns.lookup` .
For [IPC][] connections, available `options` are:
For local domain sockets, `options` argument should be an object which
specifies:
* `path` {string} Required. Path the client should connect to.
See [Identifying paths for IPC connections][].
- `path` : Path the client should connect to (Required).
#### socket.connect(path[, connectListener])
Normally this method is not needed, as `net.createConnection` opens the
socket. Use this only if you are implementing a custom Socket.
* `path` {string} Path the client should connect to. See
[Identifying paths for IPC connections][].
* `connectListener` {Function} Common parameter of [`socket.connect()`][]
methods. Will be added as a listener for the [`'connect'`][] event once.
* Returns: {net.Socket} The socket itself.
This function is asynchronous. When the [`'connect'`][] event is emitted the
socket is established. If there is a problem connecting, the `'connect'` event
will not be emitted, the [`'error'`][] event will be emitted with the exception.
Initiate an [IPC][] connection on the given socket.
The `connectListener` parameter will be added as a listener for the
[`'connect'`][] event.
Alias to
[`socket.connect(options[, connectListener])`][`socket.connect(options)`]
called with `{ path: path }` as `options` .
### socket.connect(path[, connectListener])
### socket.connect(port[, host][, connectListener])
#### socket.connect(port[, host][, connectListener])
<!-- YAML
added: v0.1.90
-->
As [`socket.connect(options[, connectListener])`][`socket.connect(options, connectListener)`],
with options as either `{port: port, host: host}` or `{path: path}` .
* `port` {number} Port the client should connect to.
* `host` {string} Host the client should connect to.
* `connectListener` {Function} Common parameter of [`socket.connect()`][]
methods. Will be added as a listener for the [`'connect'`][] event once.
* Returns: {net.Socket} The socket itself.
Initiate a TCP connection on the given socket.
Alias to
[`socket.connect(options[, connectListener])`][`socket.connect(options)`]
called with `{port: port, host: host}` as `options` .
### socket.connecting
<!-- YAML
added: v6.1.0
-->
If `true` - [`socket.connect(options[, connectListener])`][`socket.connect(options, connectListener)`] was called and
haven't yet finished. Will be set to `false` before emitting `connect` event
and/or calling [`socket.connect(options[, connectListener])`][`socket.connect(options, connectListener)`]'s callback.
If `true` -
[`socket.connect(options[, connectListener])`][`socket.connect(options)`]
was called and haven't yet finished. Will be set to `false` before emitting
`connect` event and/or calling
[`socket.connect(options[, connectListener])`][`socket.connect(options)`]'s
callback.
### socket.destroy([exception])
<!-- YAML
@ -743,84 +794,85 @@ buffer. Returns `false` if all or part of the data was queued in user memory.
The optional `callback` parameter will be executed when the data is finally
written out - this may not be immediately.
## net.connect(options[, connectListener])
<!-- YAML
added: v0.7.0
-->
A factory function, which returns a new [`net.Socket`][] and automatically
connects with the supplied `options` .
The options are passed to both the [`net.Socket`][] constructor and the
[`socket.connect`][] method.
## net.connect()
The `connectListener` parameter will be added as a listener for the
[`'connect'`][] event once .
Aliases to
[`net.createConnection()`][`net.createConnection()`].
Here is an example of a client of the previously described echo server:
```js
const net = require('net');
const client = net.connect({port: 8124}, () => {
// 'connect' listener
console.log('connected to server!');
client.write('world!\r\n');
});
client.on('data', (data) => {
console.log(data.toString());
client.end();
});
client.on('end', () => {
console.log('disconnected from server');
});
```
Possible signatures:
To connect on the socket `/tmp/echo.sock` the second line would just be
changed to
* [`net.connect(options[, connectListener])`][`net.connect(options)`]
* [`net.connect(path[, connectListener])`][`net.connect(path)`] for [IPC][]
connections.
* [`net.connect(port[, host][, connectListener])`][`net.connect(port, host)`]
for TCP connections.
```js
const client = net.connect({path: '/tmp/echo.sock'});
```
### net.connect(options[, connectListener])
<!-- YAML
added: v0.7.0
-->
Alias to
[`net.createConnection(options[, connectListener])`][`net.createConnection(options)`].
## net.connect(path[, connectListener])
### net.connect(path[, connectListener])
<!-- YAML
added: v0.1.90
-->
A factory function, which returns a new unix [`net.Socket`][] and automatically
connects to the supplied `path` .
The `connectListener` parameter will be added as a listener for the
[`'connect'`][] event once.
Alias to
[`net.createConnection(path[, connectListener])`][`net.createConnection(path)`].
## net.connect(port[, host][, connectListener])
### net.connect(port[, host][, connectListener])
<!-- YAML
added: v0.1.90
-->
A factory function, which returns a new [`net.Socket`][] and automatically
connects to the supplied `port` and `host` .
Alias to
[`net.createConnection(port[, host][, connectListener])`][`net.createConnection(port, host)`].
## net.createConnection()
If `host` is omitted, `'localhost'` will be assumed.
A factory function, which creates a new [`net.Socket`][],
immediately initiates connection with [`socket.connect()`][],
then returns the `net.Socket` that starts the connection.
The `connectListener` parameter will be added as a listener for the
[`'connect'`][] event once.
When the connection is established, a [`'connect'`][] event will be emitted
on the returned socket. The last parameter `connectListener` , if supplied,
will be added as a listener for the [`'connect'`][] event **once** .
## net.createConnection(options[, connectListener])
Possible signatures:
* [`net.createConnection(options[, connectListener])`][`net.createConnection(options)`]
* [`net.createConnection(path[, connectListener])`][`net.createConnection(path)`]
for [IPC][] connections.
* [`net.createConnection(port[, host][, connectListener])`][`net.createConnection(port, host)`]
for TCP connections.
*Note*: the [`net.connect()`][] function is an alias to this function.
### net.createConnection(options[, connectListener])
<!-- YAML
added: v0.1.90
-->
A factory function, which returns a new [`net.Socket`][] and automatically
connects with the supplied `options` .
* `options` {Object} Required. Will be passed to both the
[`new net.Socket([options])`][`new net.Socket(options)`] call and the
[`socket.connect(options[, connectListener])`][`socket.connect(options)`]
method.
* `connectListener` {Function} Common parameter of the
[`net.createConnection()`][] functions. If supplied, will be added as
a listener for the [`'connect'`][] event on the returned socket once.
* Returns: {net.Socket} The newly created socket used to start the connection.
The options are passed to both the [`net.Socket`][] constructor and the
[`socket.connect`][] method.
For available options, see
[`new net.Socket([options])`][`new net.Socket(options)`]
and [`socket.connect(options[, connectListener])`][`socket.connect(options)`].
Passing `timeout` as an option will call [`socket.setTimeout()`][] after the socket is created, but before it is connecting.
Additional options:
The `connectListener` parameter will be added as a listener for the
[`'connect'`][] event once.
* `timeout` {number} If set, will be used to call
[`socket.setTimeout(timeout)`][] after the socket is created, but before
it starts the connection.
Here is an example of a client of the previously described echo server:
@ -844,39 +896,59 @@ To connect on the socket `/tmp/echo.sock` the second line would just be
changed to
```js
const client = net.connect({path: '/tmp/echo.sock'});
const client = net.createC onnection ({path: '/tmp/echo.sock'});
```
## net.createConnection(path[, connectListener])
### net.createConnection(path[, connectListener])
<!-- YAML
added: v0.1.90
-->
A factory function, which returns a new unix [`net.Socket`][] and automatically
connects to the supplied `path` .
* `path` {string} Path the socket should connect to. Will be passed to
[`socket.connect(path[, connectListener])`][`socket.connect(path)`].
See [Identifying paths for IPC connections][].
* `connectListener` {Function} Common parameter of the
[`net.createConnection()`][] functions, an "once" listener for the
`'connect'` event on the initiating socket. Will be passed to
[`socket.connect(path[, connectListener])`][`socket.connect(path)`].
* Returns: {net.Socket} The newly created socket used to start the connection.
Initiates an [IPC][] connection.
The `connectListener` parameter will be added as a listener for the
[`'connect'`][] event once.
This function creates a new [`net.Socket`][] with all options set to default,
immediately initiates connection with
[`socket.connect(path[, connectListener])`][`socket.connect(path)`],
then returns the `net.Socket` that starts the connection.
## net.createConnection(port[, host][, connectListener])
### net.createConnection(port[, host][, connectListener])
<!-- YAML
added: v0.1.90
-->
A factory function, which returns a new [`net.Socket`][] and automatically
connects to the supplied `port` and `host` .
* `port` {number} Port the socket should connect to. Will be passed to
[`socket.connect(port[, host][, connectListener])`][`socket.connect(port, host)`].
* `host` {string} Host the socket should connect to. Defaults to `'localhost'` .
Will be passed to
[`socket.connect(port[, host][, connectListener])`][`socket.connect(port, host)`].
* `connectListener` {Function} Common parameter of the
[`net.createConnection()`][] functions, an "once" listener for the
`'connect'` event on the initiating socket. Will be passed to
[`socket.connect(path[, connectListener])`][`socket.connect(port, host)`].
* Returns: {net.Socket} The newly created socket used to start the connection.
If `host` is omitted, `'localhost'` will be assumed.
Initiates a TCP connection .
The `connectListener` parameter will be added as a listener for the
[`'connect'`][] event once.
This function creates a new [`net.Socket`][] with all options set to default,
immediately initiates connection with
[`socket.connect(port[, host][, connectListener])`][`socket.connect(port, host)`],
then returns the `net.Socket` that starts the connection.
## net.createServer([options][, connectionListener])
<!-- YAML
added: v0.5.0
-->
Creates a new TCP or local server.
Creates a new TCP or [IPC][] server.
* `options` {Object}
* `allowHalfOpen` {boolean} Default to `false` . Indicates whether half-opened
@ -898,7 +970,7 @@ This allows connections to be passed between processes without any data being
read by the original process. To begin reading data from a paused socket, call
[`socket.resume()`][].
The server can be a TCP server or a local server, depending on what it
The server can be a TCP server or a [IPC][] server, depending on what it
[`listen()`][`server.listen()`] to.
Here is an example of an TCP echo server which listens for connections
@ -978,14 +1050,22 @@ Returns true if input is a version 6 IP address, otherwise returns false.
[`'listening'`]: #net_event_listening
[`'timeout'`]: #net_event_timeout
[`child_process.fork()`]: child_process.html#child_process_child_process_fork_modulepath_args_options
[`connect()`]: #net_socket_connect_options_connectlistener
[`dns.lookup()`]: dns.html#dns_dns_lookup_hostname_options_callback
[`dns.lookup()` hints]: dns.html#dns_supported_getaddrinfo_flags
[`EventEmitter`]: events.html#events_class_eventemitter
[`net.createConnection()`]: #net_net_createconnection_options_connectlistener
[`net.connect()`]: #net_net_connect
[`net.connect(options)`]: #net_net_connect_options_connectlistener
[`net.connect(path)`]: #net_net_connect_path_connectlistener
[`net.connect(port, host)`]: #net_net_connect_port_host_connectlistener
[`net.connect()`]: #net_net_connect
[`net.createConnection()`]: #net_net_createconnection
[`net.createConnection(options)`]: #net_net_createconnection_options_connectlistener
[`net.createConnection(path)`]: #net_net_createconnection_path_connectlistener
[`net.createConnection(port, host)`]: #net_net_createconnection_port_host_connectlistener
[`net.createServer()`]: #net_net_createserver_options_connectionlistener
[`net.Server`]: #net_class_net_server
[`net.Socket`]: #net_class_net_socket
[`new net.Socket(options)`]: #net_new_net_socket_options
[`server.getConnections()`]: #net_server_getconnections_callback
[`server.listen()`]: #net_server_listen
[`server.listen(handle)`]: #net_server_listen_handle_backlog_callback
@ -993,15 +1073,21 @@ Returns true if input is a version 6 IP address, otherwise returns false.
[`server.listen(path)`]: #net_server_listen_path_backlog_callback
[`server.listen(port, host)`]: #net_server_listen_port_host_backlog_callback
[`server.close()`]: #net_server_close_callback
[`socket.connect(options, connectListener)`]: #net_socket_connect_options_connectlistener
[`socket.connect`]: #net_socket_connect_options_connectlistener
[`socket.connect()`]: #net_socket_connect
[`socket.connect(options)`]: #net_socket_connect_options_connectlistener
[`socket.connect(path)`]: #net_socket_connect_path_connectlistener
[`socket.connect(port, host)`]: #net_socket_connect_port_host_connectlistener
[`socket.destroy()`]: #net_socket_destroy_exception
[`socket.end()`]: #net_socket_end_data_encoding
[`socket.setTimeout()`]: #net_socket_settimeout_timeout_callback
[`socket.setTimeout(timeout)`]: #net_socket_settimeout_timeout_callback
[`socket.resume()`]: #net_socket_resume
[`socket.pause()`]: #net_socket_pause
[`stream.setEncoding()`]: stream.html#stream_readable_setencoding_encoding
[duplex stream]: stream.html#stream_class_stream_duplex
[half-closed]: https://tools.ietf.org/html/rfc1122#section-4.2.2.13
[Identifying paths for IPC connections]: #net_identifying_paths_for_ipc_connections
[IPC]: #net_ipc_support
[Readable Stream]: stream.html#stream_class_stream_readable
[socket(7)]: http://man7.org/linux/man-pages/man7/socket.7.html
[unspecified IPv6 address]: https://en.wikipedia.org/wiki/IPv6_address#Unspecified_address
Joyee Cheung
8 years ago