diff --git a/doc/api/net.md b/doc/api/net.md index 505337871a8904..5bd3a23722fb1c 100644 --- a/doc/api/net.md +++ b/doc/api/net.md @@ -7,17 +7,26 @@ functions for creating both servers and clients (called streams). You can includ 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' + * {net.Socket} The connection object @@ -25,6 +34,9 @@ Emitted when a new connection is made. `socket` is an instance of `net.Socket`. ### Event: 'error' + * {Error} @@ -32,10 +44,16 @@ 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. @@ -63,6 +81,9 @@ server.listen(() => { 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 @@ -72,6 +93,10 @@ 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. @@ -82,6 +107,9 @@ This becomes `null` when sending a socket to a child with 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. @@ -89,6 +117,9 @@ when sockets were sent to forks. Callback should take two arguments `err` and `count`. ### server.listen(handle[, backlog][, callback]) + * `handle` {Object} * `backlog` {Number} @@ -112,6 +143,9 @@ The parameter `backlog` behaves the same as in [`server.listen(port[, hostname][, backlog][, callback])`][`server.listen(port, host, backlog, callback)`]. ### server.listen(options[, callback]) + * `options` {Object} - Required. Supports the following properties: * `port` {Number} - Optional. @@ -141,6 +175,9 @@ server.listen({ ``` ### server.listen(path[, backlog][, callback]) + * `path` {String} * `backlog` {Number} @@ -175,6 +212,9 @@ 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]) + Begin accepting connections on the specified `port` and `hostname`. If the `hostname` is omitted, the server will accept connections on any IPv6 address @@ -209,11 +249,17 @@ server.on('error', (e) => { (Note: All sockets in Node.js are set `SO_REUSEADDR`.) ### server.listening + A Boolean indicating whether or not the server is listening for connections. ### server.maxConnections + Set this property to reject connections when the server's connection count gets high. @@ -222,6 +268,9 @@ 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 @@ -230,6 +279,9 @@ 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 @@ -238,6 +290,9 @@ active server in the event system. If the server is already `unref`d calling 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 @@ -245,6 +300,9 @@ user and used as a client (with [`connect()`][]) or they can be created by Node. and passed to the user through the `'connection'` event of a server. ### new net.Socket([options]) + Construct a new socket object. @@ -267,6 +325,9 @@ 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. @@ -274,11 +335,17 @@ 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} @@ -290,12 +357,18 @@ 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. @@ -306,6 +379,9 @@ 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} @@ -313,6 +389,9 @@ 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. @@ -323,6 +402,9 @@ Not applicable to UNIX sockets. * `host` {String} The hostname. ### 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. @@ -330,6 +412,9 @@ 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 @@ -337,6 +422,9 @@ 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 @@ -355,14 +443,23 @@ 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. @@ -399,22 +496,34 @@ The `connectListener` parameter will be added as a listener for the ### socket.connect(path[, connectListener]) ### socket.connect(port[, host][, connectListener]) + As [`socket.connect(options[, connectListener])`][`socket.connect(options, connectListener)`], with options either as either `{port: port, host: host}` or `{path: path}`. ### socket.connecting + 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. ### 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. @@ -423,12 +532,18 @@ 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`. @@ -439,6 +554,9 @@ 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 @@ -447,16 +565,25 @@ 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'`. Value may be `undefined` if the socket is destroyed (for example, if the client disconnected). ### 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`. @@ -466,11 +593,17 @@ The numeric representation of the remote port. For example, 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. @@ -484,6 +617,9 @@ initialDelay will leave the value unchanged from the default 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 @@ -493,6 +629,9 @@ algorithm, they buffer data before sending it off. Setting `true` for 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. @@ -509,6 +648,9 @@ The optional `callback` parameter will be added as a one time listener for the 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 @@ -517,6 +659,9 @@ active socket in the event system. If the socket is already `unref`d calling 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. @@ -529,6 +674,9 @@ 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`][] and automatically connects with the supplied `options`. @@ -565,6 +713,9 @@ const client = net.connect({path: '/tmp/echo.sock'}); ``` ## net.connect(path[, connectListener]) + A factory function, which returns a new unix [`net.Socket`][] and automatically connects to the supplied `path`. @@ -573,6 +724,9 @@ 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`][] and automatically connects to the supplied `port` and `host`. @@ -583,6 +737,9 @@ 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`][] and automatically connects with the supplied `options`. @@ -619,6 +776,9 @@ const client = net.connect({path: '/tmp/echo.sock'}); ``` ## net.createConnection(path[, connectListener]) + A factory function, which returns a new unix [`net.Socket`][] and automatically connects to the supplied `path`. @@ -627,6 +787,9 @@ 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`][] and automatically connects to the supplied `port` and `host`. @@ -637,6 +800,9 @@ 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 automatically set as a listener for the [`'connection'`][] event. @@ -704,17 +870,26 @@ nc -U /tmp/echo.sock ``` ## net.isIP(input) + 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. ## net.isIPv4(input) + Returns true if input is a version 4 IP address, otherwise returns false. ## net.isIPv6(input) + Returns true if input is a version 6 IP address, otherwise returns false.