diff --git a/doc/api/net.md b/doc/api/net.md index 67e7abfa8eda7c..d20e6bf767e047 100644 --- a/doc/api/net.md +++ b/doc/api/net.md @@ -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 -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]) -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]) -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' Emitted when a socket connection is successfully established. -See [`connect()`][]. +See [`net.createConnection()`][]. ### Event: 'data' -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]) -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 -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]) - -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]) + +Alias to +[`net.createConnection(options[, connectListener])`][`net.createConnection(options)`]. -## net.connect(path[, connectListener]) +### net.connect(path[, connectListener]) -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]) -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]) -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.createConnection({path: '/tmp/echo.sock'}); ``` -## net.createConnection(path[, connectListener]) +### net.createConnection(path[, connectListener]) -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]) -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]) -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