net [edit]

Functions (6)
- connect
- createConnection
- createServer
- isIP
- isIPv4
- isIPv6

3 - Stable

The net module provides you with an asynchronous network wrapper. It contains methods for creating both servers and clients (called streams). You can include this module in your code with require('net');

Example

Here is an example of an echo server which listens for connections on port 8124:

You can test this by using telnet:

telnet localhost 8124

To listen on the socket /tmp/echo.sock the third line from the last would just be changed to

server.listen('/tmp/echo.sock', function() { //'listening' listener

You can use nc to connect to a UNIX domain socket server:

nc -U /tmp/echo.sock

Methods

- net.connect(Object options[, Function connectionListener()])
- Aliased as: net.createConnection

Constructs a new socket object, and opens the socket to the given location. When the socket is established, the 'connect' event is emitted.

For TCP sockets, the 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.

For UNIX domain sockets, the options argument should be an object that specifies:

path: Path the client should connect to (Required).

Other common options include:

allowHalfOpen: if true, the socket won't automatically send a FIN packet when the other end of the socket sends a FIN packet. Defaults to false. See ['end'][] event for more information.

Example

Arguments

options	Object	Required. Properties to pass to the connection
connectionListener	Function	Required. Automatically set as a listener for the *`'connection'` event

- net.createConnection(options[, connectionListener()])
- Aliased as: net.createServer

- net.createServer([Object options = {"allowHalfOpen":false}][, Function connectionListener])
- Aliased as: net.createConnection

Creates a new TCP server.

If allowHalfOpen is true, then the socket won't automatically send FIN packet when the other end of the socket sends a FIN packet. The socket becomes non-readable, but still writable. You should call the end() method explicitly. See 'end' event for more information.

Arguments

options	Object	Required. An object with any options you want to include
connectionListener	Function	Required. Automatically set as a listener for the *`'connection'` event

- net.isIP(String input)
- - String

Tests if input is an IP address. Returns 0 for invalid strings, returns 4 for IP version 4 addresses, and returns 6 for IP version 6 addresses.

Arguments

input	String	Required. The data to check against

- net.isIPv4(String input)
- - String

Returns true if input is a version 4 IP address.

Arguments

input	String	Required. The data to check against

- net.isIPv6(String input)
- - String

Returns true if input is a version 6 IP address.

Arguments

input	String	Required. The data to check against

net.Server [edit]

Events (4)
Functions (4)
- address
- close
- listen
- pause
Properties (2)
- connections
- maxConnections

This class is used to create a TCP or UNIX server. A server is a net.Socket that can listen for new incoming connections.

Events

- net.Server.on("close", function())

Emitted when the server closes. Note that if connections exist, this event is not emitted until all connections are ended.

- net.Server.on("connection", function(net.Socket socket))

Emitted when a new connection is made.

Arguments

socket	net.Socket	Required. An instance of `net.Socket`

- net.Server.on("error", function(exception))

Emitted when an error occurs. The 'close' event is called directly following this event. See an example in the discussion of net.Server.listen

- net.Server.on("listening", function())

Emitted when the server has been bound after calling server.listen.

Methods

- net.Server.address()
- - Object

Returns the bound address, the address family name, and port of the server as reported by the operating system. Useful to find which port was assigned when giving getting an OS-assigned address.

This returns an object with three properties, like this:

{"address":"127.0.0.1", family: "IPv4", "port":2121}`

Example

- net.Server.close([Function callback()])

Stops the server from accepting new connections. This function is asynchronous, and the server is finally closed when it emits a `'close' event.

Arguments

callback	Function	Required. A function to call once the server closes

- net.Server.listen(Number port[, String host][, Number backlog = 511][, Function callback()])
- net.Server.listen(Number port[, Function callback()])
- net.Server.listen(Object handle[, Function callback()])

Begin accepting connections on the specified port and host. If the host is omitted, the server accepts connections directed to any IPv4 address (INADDR_ANY). A port value of zero will assign a random port.

If using the backlog signature: The actual length for backlog is determined by your OS through sysctl settings such as tcp_max_syn_backlogandsomaxconn` on linux. The default value of this parameter is 511 (not 512).

**If using the handle signature: This causes the server to accept connections on the specified handle, but it is presumed that the file descriptor or handle has already been bound to a port or domain socket.

Listening on a file descriptor is not supported on Windows.

The callback() is added as a listener for the net.Server's 'listening' event.

One issue some users run into is getting EADDRINUSE errors. This means that another server is already running on the requested port. One way of handling this would be to wait a second and then try again. This can be done with

server.on('error', function (e) {
  if (e.code == 'EADDRINUSE') {
    console.log('Address in use, retrying...');
    setTimeout(function () {
      server.close();
      server.listen(PORT, HOST);
    }, 1000);
  }
});

Note:

All sockets in Node.js set SO_REUSEADDR already.

Arguments

port	Number	Required. The port to connect to
host	String	Required. The name of the host to connect to
backlog	Number	Required. The maximum length of the queue of pending connection
callback	Function	Required. Automatically set as a listener for the *`'listening'` event
handle	Object	Required. Either a server or socket (anything with an underlying *`_handle` member), or a `{fd: <n>}` object

- net.Server.pause(Number msecs = 1000)

Stop accepting connections for the given number of milliseconds. This could be useful for throttling new connections against DoS attacks or other oversubscriptions.

Arguments

msecs	Number	Required. The number of milliseconds to pause for

Properties

- net.Server.connections()
- - Number

The number of concurrent connections on the server.

This becomes null when sending a socket to a child with child_process.fork().

- net.Server.maxConnections()
- - Number

Set this property to reject connections when the server's connection count gets high.

Warning:

It is not recommended to use this option once a socket has been sent to a child with child_process.fork().

net.Socket [edit]

Events (3)
Constructors (1)
- new
Functions (16)
Properties (5)

This object is an abstraction of a TCP or UNIX 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.

Constructors

- new net.Socket([Object options])

Constructs a new socket object.

options is an object with the following defaults:

{
  fd: null
  type: null
  allowHalfOpen: false
}

where

fd allows you to specify the existing file descriptor of socket.
type specifies the underlying protocol. It can be 'tcp4', 'tcp6', or 'unix'.
allowHalfOpen is a boolean indicating how the socket should end. For more information, see the createServer() method and the 'end' event.

Arguments

options	Object	Required. An object of options you can pass

Events

- net.Socket.on("connect", function())

Emitted when a socket connection is successfully established. For more information, see connect().

- net.Socket.on("data", function(Buffer | String data))

Emitted when data is received. The encoding of data is set by socket.setEncoding().

For more information, see the ReadableStream section.

Arguments

data	Buffer \| String	Required. A `Buffer` or `String`, depending on what it is

- net.Socket.on("end", function())

By default (when allowHalfOpen == false), the socket destroys its file descriptor once it has written out its pending write queue. However, by setting allowHalfOpen == true the socket won't automatically end() its side, allowing the user to write arbitrary amounts of data, with the caveat that the user is required to end() their side now.

Emitted when the other end of the socket sends a FIN packet.

Methods

- net.Socket.address()
- - Object

Returns the bound address, the address family name, and port of the socket as reported by the operating system.

Returns

Object	An object with three properties, that looks like this: *`{ port: 12346, family: 'IPv4', address: '127.0.0.1' }`

- net.Socket.close(Boolean had_error)

Emitted once the socket is fully closed.

Arguments

had_error	Boolean	Required. A `true` boolean if the socket was closed due to a *transmission error

- net.Socket.connect(Number port[, String host = "localhost"][, Function connectionListener()])

Opens the connection for a given socket. If port and host are given, then the socket is opened as a TCP socket. If a path is given, the socket is opened as a Unix socket to that path.

Normally this method isn't needed, as net.createConnection() opens the socket. Use this only if you are implementing a custom Socket or if a Socket is closed and you want to reuse it to connect to another server.

This function is asynchronous. When the 'connect' event is emitted the socket is established. If there is a problem connecting, the 'connect' event isn't emitted, and the 'error' event is emitted with the exception.

Arguments

port	Number	Required. The port to connect to
host	String	Required. The name of the host to connect to; it's entirely optional, as *you can just use `(port, connectListener)` if you wish
connectionListener	Function	Required. Automatically set as a listener for the *`'connection'` event

- net.Socket.destroy()

Ensures that no more I/O activity happens on this socket. Only necessary in case of errors (like with a parse error).

- net.Socket.drain()
- Related to: net.Socket.write

Emitted when the write buffer becomes empty. Can be used to throttle uploads.

- net.Socket.end([String data][, String encoding])

Half-closes the socket, i.e., it sends a FIN packet. It is possible the server can still send some data.

If data is specified, it's equivalent to calling socket.write(data, encoding) followed by socket.end().

Arguments

data	String	Required. The data to write first
encoding	String	Required. The encoding to use

- net.Socket.error(Error exception)

Emitted when an error occurs. The 'close' event is called directly following this event.

Arguments

exception	Error	Required. Any exceptions encountered

- net.Socket.pause()

Pauses the reading of data. That is, 'data' events are no longer emitted. Useful to throttle back an upload.

- net.Socket.resume()

Resumes reading after a call to pause().

- net.Socket.setEncoding([String encoding = null])

Sets the encoding for the socket as a Readable Stream.

For more information, see stream.ReadableStream.setEncoding().

Arguments

encoding	String	Required. The encoding to use (either `'ascii'`, `'utf8'`, or *`'base64'`)

- net.Socket.setKeepAlive([Boolean enable = false][, Number initialDelay = 0])

Enable and disable keep-alive functionality, and optionally set the initial delay before the first keepalive probe is sent on an idle socket.

Setting initialDelay to 0 for leaves the value unchanged from the default (or previous) setting.

Example

Arguments

enable	Boolean	Required. Enables or disables whether to stay alive
initialDelay	Number	Required. The delay (in milliseconds) between the last data *packet received and the first keepalive probe

- net.Socket.setNoDelay([Boolean noDelay = true])

Disables the Nagle algorithm. By default TCP connections use the Nagle algorithm, they buffer data before sending it off.

Arguments

noDelay	Boolean	Required. If `true`, immediately fires off data each time *`socket.write()` is called.

- net.Socket.setSecure()
- Deprecated

This function was used to upgrade the connection to SSL/TLS. See the TLS section for the new API.

- net.Socket.setTimeout(Number timeout[, Function callback()])

Sets the socket to timeout after timeout milliseconds of inactivity on the socket. By default net.Socket don't have a timeout.

When an idle timeout is triggered the socket will receive a 'timeout' event but the connection will not be severed. The user must manually end() or destroy() the socket.

If timeout is 0, then the existing idle timeout is disabled.

Arguments

timeout	Number	Required. The timeout length (in milliseconds)
callback	Function	Required. The function to execute as a one time listener for the *`'timeout'` event.

- net.Socket.timeout()
- Related to: net.Socket.setTimeout

Emitted if the socket times out from inactivity. This is only to notify that the socket has been idle. The user must manually close the connection.

- net.Socket.write(String data[, String encoding = "utf8"][, Function callback()])
- - Boolean

Sends data on the socket. The second parameter specifies the encoding in the case of a string—it defaults to UTF8 encoding.

Returns true if the entire data was flushed successfully to the kernel buffer. Returns false if all or part of the data was queued in user memory. 'drain' is emitted when the buffer is again free.

Arguments

data	String	Required. The data to write
encoding	String	Required. The encoding to use
callback	Function	Required. The callback to execute once the write is finished

Properties

- net.Socket.bufferSize()
- - Number

net.Socket has the property that socket.write() always works. This is to help users get up and running quickly. The computer can't always keep up with the amount of data that is written to a socket—the network connection simply might be too slow. Node.js will internally queue up the data written to a socket and send it out over the wire whenever it's possible. (Internally, it's polling on the socket's file descriptor for being writable.)

The consequence of this internal buffering is that memory may grow. This property shows the number of characters currently buffered to be written. The number of characters is approximately equal to the number of bytes to be written, but the buffer may contain strings, and the strings are lazily encoded, so the exact number of bytes is not known.

Note:

Users who experience a large or growing bufferSize should attempt to "throttle" the data flows in their program with pause() and resume().

- net.Socket.bytesRead()
- - Number

The amount of received bytes.

- net.Socket.bytesWritten()
- - Number

The amount of bytes sent.

- net.Socket.remoteAddress()
- - String

The string representation of the remote IP address. For example, '74.125.127.100' or '2001:4860:a005::68'.

- net.Socket.remotePort()
- - Number

The numeric representation of the remote port. For example, 80 or 21.

net.Server [edit]

Events (4)
Functions (4)
Properties (2)
- connections
- maxConnections

This class is used to create a TCP or UNIX server. A server is a net.Socket that can listen for new incoming connections.

Events

- net.Server.on("close", function())

Emitted when the server closes. Note that if connections exist, this event is not emitted until all connections are ended.

- net.Server.on("connection", function(net.Socket socket))

Emitted when a new connection is made.

Arguments

socket	net.Socket	Required. An instance of `net.Socket`

- net.Server.on("error", function(exception))

Emitted when an error occurs. The 'close' event is called directly following this event. See an example in the discussion of net.Server.listen

- net.Server.on("listening", function())

Emitted when the server has been bound after calling server.listen.

Methods

- net.Server.address()
- - Object

Returns the bound address, the address family name, and port of the server as reported by the operating system. Useful to find which port was assigned when giving getting an OS-assigned address.

This returns an object with three properties, like this:

{"address":"127.0.0.1", family: "IPv4", "port":2121}`

Example

- net.Server.close([Function callback()])

Stops the server from accepting new connections. This function is asynchronous, and the server is finally closed when it emits a `'close' event.

Arguments

callback	Function	Required. A function to call once the server closes

- net.Server.listen(Number port[, String host][, Number backlog = 511][, Function callback()])
- net.Server.listen(Number port[, Function callback()])
- net.Server.listen(Object handle[, Function callback()])

Listening on a file descriptor is not supported on Windows.

The callback() is added as a listener for the net.Server's 'listening' event.

server.on('error', function (e) {
  if (e.code == 'EADDRINUSE') {
    console.log('Address in use, retrying...');
    setTimeout(function () {
      server.close();
      server.listen(PORT, HOST);
    }, 1000);
  }
});

Note:

All sockets in Node.js set SO_REUSEADDR already.

Arguments

port	Number	Required. The port to connect to
host	String	Required. The name of the host to connect to
backlog	Number	Required. The maximum length of the queue of pending connection
callback	Function	Required. Automatically set as a listener for the *`'listening'` event
handle	Object	Required. Either a server or socket (anything with an underlying *`_handle` member), or a `{fd: <n>}` object

- net.Server.pause(Number msecs = 1000)

Stop accepting connections for the given number of milliseconds. This could be useful for throttling new connections against DoS attacks or other oversubscriptions.

Arguments

msecs	Number	Required. The number of milliseconds to pause for

Properties

- net.Server.connections()
- - Number

The number of concurrent connections on the server.

This becomes null when sending a socket to a child with child_process.fork().

- net.Server.maxConnections()
- - Number

Set this property to reject connections when the server's connection count gets high.

Warning:

It is not recommended to use this option once a socket has been sent to a child with child_process.fork().

net.Socket [edit]

Events (3)
Constructors (1)
- new
Functions (16)
Properties (5)

Constructors

- new net.Socket([Object options])

Constructs a new socket object.

options is an object with the following defaults:

{
  fd: null
  type: null
  allowHalfOpen: false
}

where

fd allows you to specify the existing file descriptor of socket.
type specifies the underlying protocol. It can be 'tcp4', 'tcp6', or 'unix'.
allowHalfOpen is a boolean indicating how the socket should end. For more information, see the createServer() method and the 'end' event.

Arguments

options	Object	Required. An object of options you can pass

Events

- net.Socket.on("connect", function())

Emitted when a socket connection is successfully established. For more information, see connect().

- net.Socket.on("data", function(Buffer | String data))

Emitted when data is received. The encoding of data is set by socket.setEncoding().

For more information, see the ReadableStream section.

Arguments

data	Buffer \| String	Required. A `Buffer` or `String`, depending on what it is

- net.Socket.on("end", function())

Emitted when the other end of the socket sends a FIN packet.

Methods

- net.Socket.address()
- - Object

Returns the bound address, the address family name, and port of the socket as reported by the operating system.

Returns

Object	An object with three properties, that looks like this: *`{ port: 12346, family: 'IPv4', address: '127.0.0.1' }`

- net.Socket.close(Boolean had_error)

Emitted once the socket is fully closed.

Arguments

had_error	Boolean	Required. A `true` boolean if the socket was closed due to a *transmission error

- net.Socket.connect(Number port[, String host = "localhost"][, Function connectionListener()])

Opens the connection for a given socket. If port and host are given, then the socket is opened as a TCP socket. If a path is given, the socket is opened as a Unix socket to that path.

Arguments

port	Number	Required. The port to connect to
host	String	Required. The name of the host to connect to; it's entirely optional, as *you can just use `(port, connectListener)` if you wish
connectionListener	Function	Required. Automatically set as a listener for the *`'connection'` event

- net.Socket.destroy()

Ensures that no more I/O activity happens on this socket. Only necessary in case of errors (like with a parse error).

- net.Socket.drain()
- Related to: net.Socket.write

Emitted when the write buffer becomes empty. Can be used to throttle uploads.

- net.Socket.end([String data][, String encoding])

Half-closes the socket, i.e., it sends a FIN packet. It is possible the server can still send some data.

If data is specified, it's equivalent to calling socket.write(data, encoding) followed by socket.end().

Arguments

data	String	Required. The data to write first
encoding	String	Required. The encoding to use

- net.Socket.error(Error exception)

Emitted when an error occurs. The 'close' event is called directly following this event.

Arguments

exception	Error	Required. Any exceptions encountered

- net.Socket.pause()

Pauses the reading of data. That is, 'data' events are no longer emitted. Useful to throttle back an upload.

- net.Socket.resume()

Resumes reading after a call to pause().

- net.Socket.setEncoding([String encoding = null])

Sets the encoding for the socket as a Readable Stream.

For more information, see stream.ReadableStream.setEncoding().

Arguments

encoding	String	Required. The encoding to use (either `'ascii'`, `'utf8'`, or *`'base64'`)

- net.Socket.setKeepAlive([Boolean enable = false][, Number initialDelay = 0])

Enable and disable keep-alive functionality, and optionally set the initial delay before the first keepalive probe is sent on an idle socket.

Setting initialDelay to 0 for leaves the value unchanged from the default (or previous) setting.

Example

Arguments

enable	Boolean	Required. Enables or disables whether to stay alive
initialDelay	Number	Required. The delay (in milliseconds) between the last data *packet received and the first keepalive probe

- net.Socket.setNoDelay([Boolean noDelay = true])

Disables the Nagle algorithm. By default TCP connections use the Nagle algorithm, they buffer data before sending it off.

Arguments

noDelay	Boolean	Required. If `true`, immediately fires off data each time *`socket.write()` is called.

- net.Socket.setSecure()
- Deprecated

This function was used to upgrade the connection to SSL/TLS. See the TLS section for the new API.

- net.Socket.setTimeout(Number timeout[, Function callback()])

Sets the socket to timeout after timeout milliseconds of inactivity on the socket. By default net.Socket don't have a timeout.

When an idle timeout is triggered the socket will receive a 'timeout' event but the connection will not be severed. The user must manually end() or destroy() the socket.

If timeout is 0, then the existing idle timeout is disabled.

Arguments

timeout	Number	Required. The timeout length (in milliseconds)
callback	Function	Required. The function to execute as a one time listener for the *`'timeout'` event.

- net.Socket.timeout()
- Related to: net.Socket.setTimeout

Emitted if the socket times out from inactivity. This is only to notify that the socket has been idle. The user must manually close the connection.

- net.Socket.write(String data[, String encoding = "utf8"][, Function callback()])
- - Boolean

Sends data on the socket. The second parameter specifies the encoding in the case of a string—it defaults to UTF8 encoding.

Arguments

data	String	Required. The data to write
encoding	String	Required. The encoding to use
callback	Function	Required. The callback to execute once the write is finished

Properties

- net.Socket.bufferSize()
- - Number

Note:

Users who experience a large or growing bufferSize should attempt to "throttle" the data flows in their program with pause() and resume().

- net.Socket.bytesRead()
- - Number

The amount of received bytes.

- net.Socket.bytesWritten()
- - Number

The amount of bytes sent.

- net.Socket.remoteAddress()
- - String

The string representation of the remote IP address. For example, '74.125.127.100' or '2001:4860:a005::68'.

- net.Socket.remotePort()
- - Number

The numeric representation of the remote port. For example, 80 or 21.

Modules

Globals

Concepts

net [edit]

Example

Methods

Example

Arguments

Arguments

Arguments

Arguments

Arguments

net.Server [edit]

Events

Arguments

Methods

Example

Arguments

Note:

Arguments

Arguments

Properties

Warning:

net.Socket [edit]

Constructors

Arguments

Events

Arguments

Methods

Returns

Arguments

Arguments

Arguments

Arguments

Arguments

Example

Arguments

Arguments

Arguments

Arguments

Properties

Note:

net.Server [edit]

Events

Arguments

Methods

Example

Arguments

Note:

Arguments

Arguments

Properties

Warning:

net.Socket [edit]

Constructors

Arguments

Events

Arguments

Methods

Returns

Arguments

Arguments

Arguments

Arguments

Arguments

Example

Arguments

Arguments

Arguments

Arguments

Properties

Note: