From 403d2bffa6a073d372a5d1c3e809c17cb9880412 Mon Sep 17 00:00:00 2001 From: Tristian Flanagan Date: Thu, 5 Nov 2015 14:15:39 -0500 Subject: [PATCH] doc: sort net alphabetically Reorders, with minimal contextual duplication, the net documentation alphabetically. PR-URL: https://github.com/nodejs/node/pull/3662 Reviewed-By: Evan Lucas Reviewed-By: James M Snell Reviewed-By: Jeremiah Senkpiel --- doc/api/net.markdown | 1137 ++++++++++++++++++++++-------------------- 1 file changed, 591 insertions(+), 546 deletions(-) diff --git a/doc/api/net.markdown b/doc/api/net.markdown index 7b328adeab1..c2d8fb3e7c3 100644 --- a/doc/api/net.markdown +++ b/doc/api/net.markdown @@ -6,6 +6,597 @@ The `net` module provides you with an asynchronous network wrapper. It contains functions for creating both servers and clients (called streams). You can include this module with `require('net');`. +## Class: net.Server + +This class is used to create a TCP or local server. + +`net.Server` is an [EventEmitter][] with the following events: + +### Event: 'close' + +Emitted when the server closes. Note that if connections exist, this +event is not emitted until all connections are ended. + +### Event: 'connection' + +* {Socket object} The connection object + +Emitted when a new connection is made. `socket` is an instance of +`net.Socket`. + +### Event: 'error' + +* {Error Object} + +Emitted when an error occurs. The ['close'][] event will be called directly +following this event. See example in discussion of `server.listen`. + +### Event: 'listening' + +Emitted when the server has been bound after calling `server.listen`. + +### server.address() + +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. +Returns an object with three properties, e.g. +`{ port: 12346, family: 'IPv4', address: '127.0.0.1' }` + +Example: + + var server = net.createServer(function (socket) { + socket.end("goodbye\n"); + }); + + // grab a random port. + server.listen(function() { + address = server.address(); + console.log("opened server on %j", address); + }); + +Don't call `server.address()` until the `'listening'` event has been emitted. + +### server.close([callback]) + +Stops the server from accepting new connections and keeps existing +connections. This function is asynchronous, the server is finally +closed when all connections are ended and the server emits a ['close'][] event. +The optional `callback` will be called once the `'close'` event occurs. Unlike +that event, it will be called with an Error as its only argument if the server +was not open when it was closed. + +### server.connections + + Stability: 0 - Deprecated: Use [server.getConnections][] instead. + +The number of concurrent connections on the server. + +This becomes `null` when sending a socket to a child with +`child_process.fork()`. To poll forks and get current number of active +connections use asynchronous `server.getConnections` instead. + +### server.getConnections(callback) + +Asynchronously get the number of concurrent connections on the server. Works +when sockets were sent to forks. + +Callback should take two arguments `err` and `count`. + +### server.listen(handle[, callback]) + +* `handle` {Object} +* `callback` {Function} + +The `handle` object can be set to either a server or socket (anything +with an underlying `_handle` member), or a `{fd: }` object. + +This will cause 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. + +This function is asynchronous. When the server has been bound, +['listening'][] event will be emitted. +The last parameter `callback` will be added as a listener for the +['listening'][] event. + +### server.listen(options[, callback]) + +* `options` {Object} - Required. Supports the following properties: + * `port` {Number} - Optional. + * `host` {String} - Optional. + * `backlog` {Number} - Optional. + * `path` {String} - Optional. + * `exclusive` {Boolean} - Optional. +* `callback` {Function} - Optional. + +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, \[host\], \[backlog\], \[callback\]) +](#net_server_listen_port_hostname_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 +underlying handle, allowing connection handling duties to be shared. When +`exclusive` is `true`, the handle is not shared, and attempted port sharing +results in an error. An example which listens on an exclusive port is +shown below. + + server.listen({ + host: 'localhost', + port: 80, + exclusive: true + }); + +### server.listen(path[, callback]) + +* `path` {String} +* `callback` {Function} + +Start a local socket server listening for connections on the given `path`. + +This function is asynchronous. When the server has been bound, +['listening'][] event will be emitted. The last parameter `callback` +will be added as a listener for the ['listening'][] event. + +On UNIX, the local domain is usually known as the UNIX domain. The path is a +filesystem path name. It 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: + + net.createServer().listen( + path.join('\\\\?\\pipe', process.cwd(), 'myctl')) + +### server.listen(port[, hostname][, backlog][, callback]) + +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. A +port value of zero will assign a random port. + +Backlog is the maximum length of the queue of pending connections. +The actual length will be determined by your OS through sysctl settings such as +`tcp_max_syn_backlog` and `somaxconn` on linux. The default value of this +parameter is 511 (not 512). + +This function is asynchronous. When the server has been bound, +['listening'][] event will be emitted. The last parameter `callback` +will be added as a listener for the ['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) + +### server.maxConnections + +Set this property to reject connections when the server's connection count gets +high. + +It is not recommended to use this option once a socket has been sent to a child +with `child_process.fork()`. + +### server.ref() + +Opposite of `unref`, calling `ref` on a previously `unref`d server will *not* +let the program exit if it's the only server left (the default behavior). If +the server is `ref`d calling `ref` again will have no effect. + +Returns `server`. + +### server.unref() + +Calling `unref` on a server will allow the program to exit if this is the only +active server in the event system. If the server is already `unref`d calling +`unref` again will have no effect. + +Returns `server`. + +## Class: net.Socket + +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. + +### new net.Socket([options]) + +Construct a new socket object. + +`options` is an object with the following defaults: + + { 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 `createServer()` and `'end'` event. + +`net.Socket` instances are [EventEmitter][] with the following events: + +### Event: 'close' + +* `had_error` {Boolean} `true` if the socket had a transmission error. + +Emitted once the socket is fully closed. The argument `had_error` is a boolean +which says if the socket was closed due to a transmission error. + +### Event: 'connect' + +Emitted when a socket connection is successfully established. +See `connect()`. + +### Event: 'data' + +* {Buffer object} + +Emitted when data is received. The argument `data` will be a `Buffer` or +`String`. Encoding of data is set by `socket.setEncoding()`. +(See the [Readable Stream][] section for more information.) + +Note that the __data will be lost__ if there is no listener when a `Socket` +emits a `'data'` event. + +### Event: 'drain' + +Emitted when the write buffer becomes empty. Can be used to throttle uploads. + +See also: the return values of `socket.write()` + +### Event: 'end' + +Emitted when the other end of the socket sends a FIN packet. + +By default (`allowHalfOpen == false`) the socket will destroy its file +descriptor once it has written out its pending write queue. However, by +setting `allowHalfOpen == true` the socket will not 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. + +### Event: 'error' + +* {Error object} + +Emitted when an error occurs. The `'close'` event will be called directly +following this event. + +### Event: 'lookup' + +Emitted after resolving the hostname but before connecting. +Not applicable to UNIX sockets. + +* `err` {Error | Null} The error object. See [dns.lookup()][]. +* `address` {String} The IP address. +* `family` {String | Null} The address type. See [dns.lookup()][]. + +### Event: 'timeout' + +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. + +See also: `socket.setTimeout()` + +### socket.address() + +Returns the bound address, the address family name and port of the +socket as reported by the operating system. Returns an object with +three properties, e.g. +`{ port: 12346, family: 'IPv4', address: '127.0.0.1' }` + +### socket.bufferSize + +`net.Socket` has the property that `socket.write()` always works. This is to +help users get up and running quickly. The computer cannot 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 when it is possible. (Internally it is +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. +(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.) + +Users who experience large or growing `bufferSize` should attempt to +"throttle" the data flows in their program with `pause()` and `resume()`. + +### socket.bytesRead + +The amount of received bytes. + +### socket.bytesWritten + +The amount of bytes sent. + +### socket.connect(options[, connectListener]) + +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. + + - `localPort`: Local port to bind to for network connections. + + - `family` : Version of IP stack. Defaults to `4`. + + - `lookup` : Custom lookup function. Defaults to `dns.lookup`. + +For local domain sockets, `options` argument should be an object which +specifies: + + - `path`: Path the client should connect to (Required). + +Normally this method is not needed, as `net.createConnection` opens the +socket. Use this only if you are implementing a custom Socket. + +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. + +The `connectListener` parameter will be added as a listener for the +['connect'][] event. + +### socket.connect(path[, connectListener]) +### socket.connect(port[, host][, connectListener]) + +As [socket.connect(options[, connectListener])](#net_socket_connect_options_connectlistener), +with options either as either `{port: port, host: host}` or `{path: path}`. + +### socket.destroy() + +Ensures that no more I/O activity happens on this socket. Only necessary in +case of errors (parse error or so). + +### socket.end([data][, encoding]) + +Half-closes the socket. i.e., it sends a FIN packet. It is possible the +server will still send some data. + +If `data` is specified, it is equivalent to calling +`socket.write(data, encoding)` followed by `socket.end()`. + +### socket.localAddress + +The string representation of the local IP address the remote client is +connecting on. For example, if you are listening on `'0.0.0.0'` and the +client connects on `'192.168.1.1'`, the value would be `'192.168.1.1'`. + +### socket.localPort + +The numeric representation of the local port. For example, +`80` or `21`. + +### socket.pause() + +Pauses the reading of data. That is, `'data'` events will not be emitted. +Useful to throttle back an upload. + +### socket.ref() + +Opposite of `unref`, calling `ref` on a previously `unref`d socket will *not* +let the program exit if it's the only socket left (the default behavior). If +the socket is `ref`d calling `ref` again will have no effect. + +Returns `socket`. + +### socket.remoteAddress + +The string representation of the remote IP address. For example, +`'74.125.127.100'` or `'2001:4860:a005::68'`. + +### socket.remoteFamily + +The string representation of the remote IP family. `'IPv4'` or `'IPv6'`. + +### socket.remotePort + +The numeric representation of the remote port. For example, +`80` or `21`. + +### socket.resume() + +Resumes reading after a call to `pause()`. + +### socket.setEncoding([encoding]) + +Set the encoding for the socket as a Readable Stream. See +[stream.setEncoding()][] for more information. + +### socket.setKeepAlive([enable][, initialDelay]) + +Enable/disable keep-alive functionality, and optionally set the initial +delay before the first keepalive probe is sent on an idle socket. +`enable` defaults to `false`. + +Set `initialDelay` (in milliseconds) to set the delay between the last +data packet received and the first keepalive probe. Setting 0 for +initialDelay will leave the value unchanged from the default +(or previous) setting. Defaults to `0`. + +Returns `socket`. + +### socket.setNoDelay([noDelay]) + +Disables the Nagle algorithm. By default TCP connections use the Nagle +algorithm, they buffer data before sending it off. Setting `true` for +`noDelay` will immediately fire off data each time `socket.write()` is called. +`noDelay` defaults to `true`. + +Returns `socket`. + +### socket.setTimeout(timeout[, callback]) + +Sets the socket to timeout after `timeout` milliseconds of inactivity on +the socket. By default `net.Socket` do not 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. + +The optional `callback` parameter will be added as a one time listener for the +`'timeout'` event. + +Returns `socket`. + +### socket.unref() + +Calling `unref` on a socket will allow the program to exit if this is the only +active socket in the event system. If the socket is already `unref`d calling +`unref` again will have no effect. + +Returns `socket`. + +### socket.write(data[, encoding][, callback]) + +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'` will be emitted when the buffer is again free. + +The optional `callback` parameter will be executed when the data is finally +written out - this may not be immediately. + +## net.connect(options[, connectListener]) + +A factory function, which returns a new ['net.Socket'](#net_class_net_socket) +and automatically connects with the supplied `options`. + +The options are passed to both the ['net.Socket'](#net_class_net_socket) +constructor and the ['socket.connect'](#net_socket_connect_options_connectlistener) +method. + +The `connectListener` parameter will be added as a listener for the +['connect'][] event once. + +Here is an example of a client of the previously described echo server: + + var net = require('net'); + var client = net.connect({port: 8124}, + function() { //'connect' listener + console.log('connected to server!'); + client.write('world!\r\n'); + }); + client.on('data', function(data) { + console.log(data.toString()); + client.end(); + }); + client.on('end', function() { + console.log('disconnected from server'); + }); + +To connect on the socket `/tmp/echo.sock` the second line would just be +changed to + + var client = net.connect({path: '/tmp/echo.sock'}); + +## net.connect(path[, connectListener]) + +A factory function, which returns a new unix +['net.Socket'](#net_class_net_socket) and automatically connects to the +supplied `path`. + +The `connectListener` parameter will be added as a listener for the +['connect'][] event once. + +## net.connect(port[, host][, connectListener]) + +A factory function, which returns a new +['net.Socket'](#net_class_net_socket) and automatically connects to the +supplied `port` and `host`. + +If `host` is omitted, `'localhost'` will be assumed. + +The `connectListener` parameter will be added as a listener for the +['connect'][] event once. + +## net.createConnection(options[, connectListener]) + +A factory function, which returns a new ['net.Socket'](#net_class_net_socket) +and automatically connects with the supplied `options`. + +The options are passed to both the ['net.Socket'](#net_class_net_socket) +constructor and the ['socket.connect'](#net_socket_connect_options_connectlistener) +method. + +The `connectListener` parameter will be added as a listener for the +['connect'][] event once. + +Here is an example of a client of the previously described echo server: + + var net = require('net'); + var client = net.connect({port: 8124}, + function() { //'connect' listener + console.log('connected to server!'); + client.write('world!\r\n'); + }); + client.on('data', function(data) { + console.log(data.toString()); + client.end(); + }); + client.on('end', function() { + console.log('disconnected from server'); + }); + +To connect on the socket `/tmp/echo.sock` the second line would just be +changed to + + var client = net.connect({path: '/tmp/echo.sock'}); + +## net.createConnection(path[, connectListener]) + +A factory function, which returns a new unix +['net.Socket'](#net_class_net_socket) and automatically connects to the +supplied `path`. + +The `connectListener` parameter will be added as a listener for the +['connect'][] event once. + +## net.createConnection(port[, host][, connectListener]) + +A factory function, which returns a new +['net.Socket'](#net_class_net_socket) and automatically connects to the +supplied `port` and `host`. + +If `host` is omitted, `'localhost'` will be assumed. + +The `connectListener` parameter will be added as a listener for the +['connect'][] event once. + ## net.createServer([options][, connectionListener]) Creates a new server. The `connectionListener` argument is @@ -57,552 +648,6 @@ Use `nc` to connect to a UNIX domain socket server: nc -U /tmp/echo.sock -## net.connect(options[, connectListener]) -## net.createConnection(options[, connectListener]) - -A factory function, which returns a new ['net.Socket'](#net_class_net_socket) -and automatically connects with the supplied `options`. - -The options are passed to both the ['net.Socket'](#net_class_net_socket) -constructor and the ['socket.connect'](#net_socket_connect_options_connectlistener) -method. - -The `connectListener` parameter will be added as a listener for the -['connect'][] event once. - -Here is an example of a client of the previously described echo server: - - var net = require('net'); - var client = net.connect({port: 8124}, - function() { //'connect' listener - console.log('connected to server!'); - client.write('world!\r\n'); - }); - client.on('data', function(data) { - console.log(data.toString()); - client.end(); - }); - client.on('end', function() { - console.log('disconnected from server'); - }); - -To connect on the socket `/tmp/echo.sock` the second line would just be -changed to - - var client = net.connect({path: '/tmp/echo.sock'}); - -## net.connect(port[, host][, connectListener]) -## net.createConnection(port[, host][, connectListener]) - -A factory function, which returns a new -['net.Socket'](#net_class_net_socket) and automatically connects to the -supplied `port` and `host`. - -If `host` is omitted, `'localhost'` will be assumed. - -The `connectListener` parameter will be added as a listener for the -['connect'][] event once. - -## net.connect(path[, connectListener]) -## net.createConnection(path[, connectListener]) - -A factory function, which returns a new unix -['net.Socket'](#net_class_net_socket) and automatically connects to the -supplied `path`. - -The `connectListener` parameter will be added as a listener for the -['connect'][] event once. - -## Class: net.Server - -This class is used to create a TCP or local server. - -### server.listen(port[, hostname][, backlog][, callback]) - -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. A -port value of zero will assign a random port. - -Backlog is the maximum length of the queue of pending connections. -The actual length will be determined by your OS through sysctl settings such as -`tcp_max_syn_backlog` and `somaxconn` on linux. The default value of this -parameter is 511 (not 512). - -This function is asynchronous. When the server has been bound, -['listening'][] event will be emitted. The last parameter `callback` -will be added as a listener for the ['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) - - -### server.listen(path[, callback]) - -* `path` {String} -* `callback` {Function} - -Start a local socket server listening for connections on the given `path`. - -This function is asynchronous. When the server has been bound, -['listening'][] event will be emitted. The last parameter `callback` -will be added as a listener for the ['listening'][] event. - -On UNIX, the local domain is usually known as the UNIX domain. The path is a -filesystem path name. It 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: - - net.createServer().listen( - path.join('\\\\?\\pipe', process.cwd(), 'myctl')) - -### server.listen(handle[, callback]) - -* `handle` {Object} -* `callback` {Function} - -The `handle` object can be set to either a server or socket (anything -with an underlying `_handle` member), or a `{fd: }` object. - -This will cause 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. - -This function is asynchronous. When the server has been bound, -['listening'][] event will be emitted. -The last parameter `callback` will be added as a listener for the -['listening'][] event. - -### server.listen(options[, callback]) - -* `options` {Object} - Required. Supports the following properties: - * `port` {Number} - Optional. - * `host` {String} - Optional. - * `backlog` {Number} - Optional. - * `path` {String} - Optional. - * `exclusive` {Boolean} - Optional. -* `callback` {Function} - Optional. - -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, \[host\], \[backlog\], \[callback\]) -](#net_server_listen_port_hostname_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 -underlying handle, allowing connection handling duties to be shared. When -`exclusive` is `true`, the handle is not shared, and attempted port sharing -results in an error. An example which listens on an exclusive port is -shown below. - - server.listen({ - host: 'localhost', - port: 80, - exclusive: true - }); - -### server.close([callback]) - -Stops the server from accepting new connections and keeps existing -connections. This function is asynchronous, the server is finally -closed when all connections are ended and the server emits a ['close'][] event. -The optional `callback` will be called once the `'close'` event occurs. Unlike -that event, it will be called with an Error as its only argument if the server -was not open when it was closed. - -### server.address() - -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. -Returns an object with three properties, e.g. -`{ port: 12346, family: 'IPv4', address: '127.0.0.1' }` - -Example: - - var server = net.createServer(function (socket) { - socket.end("goodbye\n"); - }); - - // grab a random port. - server.listen(function() { - address = server.address(); - console.log("opened server on %j", address); - }); - -Don't call `server.address()` until the `'listening'` event has been emitted. - -### server.unref() - -Calling `unref` on a server will allow the program to exit if this is the only -active server in the event system. If the server is already `unref`d calling -`unref` again will have no effect. - -Returns `server`. - -### server.ref() - -Opposite of `unref`, calling `ref` on a previously `unref`d server will *not* -let the program exit if it's the only server left (the default behavior). If -the server is `ref`d calling `ref` again will have no effect. - -Returns `server`. - -### server.maxConnections - -Set this property to reject connections when the server's connection count gets -high. - -It is not recommended to use this option once a socket has been sent to a child -with `child_process.fork()`. - -### server.connections - - Stability: 0 - Deprecated: Use [server.getConnections][] instead. - -The number of concurrent connections on the server. - -This becomes `null` when sending a socket to a child with -`child_process.fork()`. To poll forks and get current number of active -connections use asynchronous `server.getConnections` instead. - -### server.getConnections(callback) - -Asynchronously get the number of concurrent connections on the server. Works -when sockets were sent to forks. - -Callback should take two arguments `err` and `count`. - -`net.Server` is an [EventEmitter][] with the following events: - -### Event: 'listening' - -Emitted when the server has been bound after calling `server.listen`. - -### Event: 'connection' - -* {Socket object} The connection object - -Emitted when a new connection is made. `socket` is an instance of -`net.Socket`. - -### Event: 'close' - -Emitted when the server closes. Note that if connections exist, this -event is not emitted until all connections are ended. - -### Event: 'error' - -* {Error Object} - -Emitted when an error occurs. The ['close'][] event will be called directly -following this event. See example in discussion of `server.listen`. - -## Class: net.Socket - -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. - -### new net.Socket([options]) - -Construct a new socket object. - -`options` is an object with the following defaults: - - { 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 `createServer()` and `'end'` event. - -### socket.connect(options[, connectListener]) - -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. - - - `localPort`: Local port to bind to for network connections. - - - `family` : Version of IP stack. Defaults to `4`. - - - `lookup` : Custom lookup function. Defaults to `dns.lookup`. - -For local domain sockets, `options` argument should be an object which -specifies: - - - `path`: Path the client should connect to (Required). - -Normally this method is not needed, as `net.createConnection` opens the -socket. Use this only if you are implementing a custom Socket. - -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. - -The `connectListener` parameter will be added as a listener for the -['connect'][] event. - -### socket.connect(port[, host][, connectListener]) -### socket.connect(path[, connectListener]) - -As [socket.connect(options[, connectListener])](#net_socket_connect_options_connectlistener), -with options either as either `{port: port, host: host}` or `{path: path}`. - -### socket.bufferSize - -`net.Socket` has the property that `socket.write()` always works. This is to -help users get up and running quickly. The computer cannot 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 when it is possible. (Internally it is -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. -(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.) - -Users who experience large or growing `bufferSize` should attempt to -"throttle" the data flows in their program with `pause()` and `resume()`. - - -### socket.setEncoding([encoding]) - -Set the encoding for the socket as a Readable Stream. See -[stream.setEncoding()][] for more information. - -### socket.write(data[, encoding][, callback]) - -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'` will be emitted when the buffer is again free. - -The optional `callback` parameter will be executed when the data is finally -written out - this may not be immediately. - -### socket.end([data][, encoding]) - -Half-closes the socket. i.e., it sends a FIN packet. It is possible the -server will still send some data. - -If `data` is specified, it is equivalent to calling -`socket.write(data, encoding)` followed by `socket.end()`. - -### socket.destroy() - -Ensures that no more I/O activity happens on this socket. Only necessary in -case of errors (parse error or so). - -### socket.pause() - -Pauses the reading of data. That is, `'data'` events will not be emitted. -Useful to throttle back an upload. - -### socket.resume() - -Resumes reading after a call to `pause()`. - -### socket.setTimeout(timeout[, callback]) - -Sets the socket to timeout after `timeout` milliseconds of inactivity on -the socket. By default `net.Socket` do not 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. - -The optional `callback` parameter will be added as a one time listener for the -`'timeout'` event. - -Returns `socket`. - -### socket.setNoDelay([noDelay]) - -Disables the Nagle algorithm. By default TCP connections use the Nagle -algorithm, they buffer data before sending it off. Setting `true` for -`noDelay` will immediately fire off data each time `socket.write()` is called. -`noDelay` defaults to `true`. - -Returns `socket`. - -### socket.setKeepAlive([enable][, initialDelay]) - -Enable/disable keep-alive functionality, and optionally set the initial -delay before the first keepalive probe is sent on an idle socket. -`enable` defaults to `false`. - -Set `initialDelay` (in milliseconds) to set the delay between the last -data packet received and the first keepalive probe. Setting 0 for -initialDelay will leave the value unchanged from the default -(or previous) setting. Defaults to `0`. - -Returns `socket`. - -### socket.address() - -Returns the bound address, the address family name and port of the -socket as reported by the operating system. Returns an object with -three properties, e.g. -`{ port: 12346, family: 'IPv4', address: '127.0.0.1' }` - -### socket.unref() - -Calling `unref` on a socket will allow the program to exit if this is the only -active socket in the event system. If the socket is already `unref`d calling -`unref` again will have no effect. - -Returns `socket`. - -### socket.ref() - -Opposite of `unref`, calling `ref` on a previously `unref`d socket will *not* -let the program exit if it's the only socket left (the default behavior). If -the socket is `ref`d calling `ref` again will have no effect. - -Returns `socket`. - -### socket.remoteAddress - -The string representation of the remote IP address. For example, -`'74.125.127.100'` or `'2001:4860:a005::68'`. - -### socket.remoteFamily - -The string representation of the remote IP family. `'IPv4'` or `'IPv6'`. - -### socket.remotePort - -The numeric representation of the remote port. For example, -`80` or `21`. - -### socket.localAddress - -The string representation of the local IP address the remote client is -connecting on. For example, if you are listening on `'0.0.0.0'` and the -client connects on `'192.168.1.1'`, the value would be `'192.168.1.1'`. - -### socket.localPort - -The numeric representation of the local port. For example, -`80` or `21`. - -### socket.bytesRead - -The amount of received bytes. - -### socket.bytesWritten - -The amount of bytes sent. - - -`net.Socket` instances are [EventEmitter][] with the following events: - -### Event: 'lookup' - -Emitted after resolving the hostname but before connecting. -Not applicable to UNIX sockets. - -* `err` {Error | Null} The error object. See [dns.lookup()][]. -* `address` {String} The IP address. -* `family` {String | Null} The address type. See [dns.lookup()][]. - -### Event: 'connect' - -Emitted when a socket connection is successfully established. -See `connect()`. - -### Event: 'data' - -* {Buffer object} - -Emitted when data is received. The argument `data` will be a `Buffer` or -`String`. Encoding of data is set by `socket.setEncoding()`. -(See the [Readable Stream][] section for more information.) - -Note that the __data will be lost__ if there is no listener when a `Socket` -emits a `'data'` event. - -### Event: 'end' - -Emitted when the other end of the socket sends a FIN packet. - -By default (`allowHalfOpen == false`) the socket will destroy its file -descriptor once it has written out its pending write queue. However, by -setting `allowHalfOpen == true` the socket will not 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. - - -### Event: 'timeout' - -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. - -See also: `socket.setTimeout()` - - -### Event: 'drain' - -Emitted when the write buffer becomes empty. Can be used to throttle uploads. - -See also: the return values of `socket.write()` - -### Event: 'error' - -* {Error object} - -Emitted when an error occurs. The `'close'` event will be called directly -following this event. - -### Event: 'close' - -* `had_error` {Boolean} `true` if the socket had a transmission error. - -Emitted once the socket is fully closed. The argument `had_error` is a boolean -which says if the socket was closed due to a transmission error. - ## net.isIP(input) Tests if input is an IP address. Returns 0 for invalid strings,