mirror of https://gitee.com/openkylin/nodejs.git
1297 lines
93 KiB
HTML
1297 lines
93 KiB
HTML
<!doctype html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta name="viewport" content="width=device-width">
|
|
<meta name="nodejs.org:node-version" content="v12.22.9">
|
|
<title>Net | Node.js v12.22.9 Documentation</title>
|
|
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:400,700,400italic&display=fallback">
|
|
<link rel="stylesheet" href="assets/style.css">
|
|
<link rel="stylesheet" href="assets/hljs.css">
|
|
<link rel="canonical" href="https://nodejs.org/api/net.html">
|
|
</head>
|
|
<body class="alt apidoc" id="api-section-net">
|
|
<div id="content" class="clearfix">
|
|
<div id="column2" class="interior">
|
|
<div id="intro" class="interior">
|
|
<a href="/" title="Go back to the home page">
|
|
Node.js
|
|
</a>
|
|
</div>
|
|
<ul>
|
|
<li><a href="documentation.html" class="nav-documentation">About this documentation</a></li>
|
|
<li><a href="synopsis.html" class="nav-synopsis">Usage and example</a></li>
|
|
</ul>
|
|
<hr class="line">
|
|
<ul>
|
|
<li><a href="assert.html" class="nav-assert">Assertion testing</a></li>
|
|
<li><a href="async_hooks.html" class="nav-async_hooks">Async hooks</a></li>
|
|
<li><a href="buffer.html" class="nav-buffer">Buffer</a></li>
|
|
<li><a href="addons.html" class="nav-addons">C++ Addons</a></li>
|
|
<li><a href="n-api.html" class="nav-n-api">C/C++ Addons with N-API</a></li>
|
|
<li><a href="embedding.html" class="nav-embedding">C++ Embedder API</a></li>
|
|
<li><a href="child_process.html" class="nav-child_process">Child Processes</a></li>
|
|
<li><a href="cluster.html" class="nav-cluster">Cluster</a></li>
|
|
<li><a href="cli.html" class="nav-cli">Command line options</a></li>
|
|
<li><a href="console.html" class="nav-console">Console</a></li>
|
|
<li><a href="crypto.html" class="nav-crypto">Crypto</a></li>
|
|
<li><a href="debugger.html" class="nav-debugger">Debugger</a></li>
|
|
<li><a href="deprecations.html" class="nav-deprecations">Deprecated APIs</a></li>
|
|
<li><a href="dns.html" class="nav-dns">DNS</a></li>
|
|
<li><a href="domain.html" class="nav-domain">Domain</a></li>
|
|
<li><a href="errors.html" class="nav-errors">Errors</a></li>
|
|
<li><a href="events.html" class="nav-events">Events</a></li>
|
|
<li><a href="fs.html" class="nav-fs">File system</a></li>
|
|
<li><a href="globals.html" class="nav-globals">Globals</a></li>
|
|
<li><a href="http.html" class="nav-http">HTTP</a></li>
|
|
<li><a href="http2.html" class="nav-http2">HTTP/2</a></li>
|
|
<li><a href="https.html" class="nav-https">HTTPS</a></li>
|
|
<li><a href="inspector.html" class="nav-inspector">Inspector</a></li>
|
|
<li><a href="intl.html" class="nav-intl">Internationalization</a></li>
|
|
<li><a href="modules.html" class="nav-modules">Modules: CommonJS modules</a></li>
|
|
<li><a href="esm.html" class="nav-esm">Modules: ECMAScript modules</a></li>
|
|
<li><a href="module.html" class="nav-module">Modules: <code>module</code> API</a></li>
|
|
<li><a href="packages.html" class="nav-packages">Modules: Packages</a></li>
|
|
<li><a href="net.html" class="nav-net active">Net</a></li>
|
|
<li><a href="os.html" class="nav-os">OS</a></li>
|
|
<li><a href="path.html" class="nav-path">Path</a></li>
|
|
<li><a href="perf_hooks.html" class="nav-perf_hooks">Performance hooks</a></li>
|
|
<li><a href="policy.html" class="nav-policy">Policies</a></li>
|
|
<li><a href="process.html" class="nav-process">Process</a></li>
|
|
<li><a href="punycode.html" class="nav-punycode">Punycode</a></li>
|
|
<li><a href="querystring.html" class="nav-querystring">Query strings</a></li>
|
|
<li><a href="readline.html" class="nav-readline">Readline</a></li>
|
|
<li><a href="repl.html" class="nav-repl">REPL</a></li>
|
|
<li><a href="report.html" class="nav-report">Report</a></li>
|
|
<li><a href="stream.html" class="nav-stream">Stream</a></li>
|
|
<li><a href="string_decoder.html" class="nav-string_decoder">String decoder</a></li>
|
|
<li><a href="timers.html" class="nav-timers">Timers</a></li>
|
|
<li><a href="tls.html" class="nav-tls">TLS/SSL</a></li>
|
|
<li><a href="tracing.html" class="nav-tracing">Trace events</a></li>
|
|
<li><a href="tty.html" class="nav-tty">TTY</a></li>
|
|
<li><a href="dgram.html" class="nav-dgram">UDP/datagram</a></li>
|
|
<li><a href="url.html" class="nav-url">URL</a></li>
|
|
<li><a href="util.html" class="nav-util">Utilities</a></li>
|
|
<li><a href="v8.html" class="nav-v8">V8</a></li>
|
|
<li><a href="vm.html" class="nav-vm">VM</a></li>
|
|
<li><a href="wasi.html" class="nav-wasi">WASI</a></li>
|
|
<li><a href="worker_threads.html" class="nav-worker_threads">Worker threads</a></li>
|
|
<li><a href="zlib.html" class="nav-zlib">Zlib</a></li>
|
|
</ul>
|
|
<hr class="line">
|
|
<ul>
|
|
<li><a href="https://github.com/nodejs/node" class="nav-https-github-com-nodejs-node">Code repository and issue tracker</a></li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div id="column1" data-id="net" class="interior">
|
|
<header>
|
|
<h1>Node.js v12.22.9 Documentation</h1>
|
|
<div id="gtoc">
|
|
<ul>
|
|
<li>
|
|
<a href="index.html">Index</a>
|
|
</li>
|
|
<li>
|
|
<a href="all.html">View on single page</a>
|
|
</li>
|
|
<li>
|
|
<a href="net.json">View as JSON</a>
|
|
</li>
|
|
|
|
<li class="version-picker">
|
|
<a href="#">View another version <span>▼</span></a>
|
|
<ol class="version-picker"><li><a href="https://nodejs.org/docs/latest-v17.x/api/net.html">17.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v16.x/api/net.html">16.x <b>LTS</b></a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v15.x/api/net.html">15.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v14.x/api/net.html">14.x <b>LTS</b></a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v13.x/api/net.html">13.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v12.x/api/net.html">12.x <b>LTS</b></a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v11.x/api/net.html">11.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v10.x/api/net.html">10.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v9.x/api/net.html">9.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v8.x/api/net.html">8.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v7.x/api/net.html">7.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v6.x/api/net.html">6.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v5.x/api/net.html">5.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v4.x/api/net.html">4.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v0.12.x/api/net.html">0.12.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v0.10.x/api/net.html">0.10.x</a></li></ol>
|
|
</li>
|
|
|
|
<li class="edit_on_github"><a href="https://github.com/nodejs/node/edit/master/doc/api/net.md"><span class="github_icon"><svg height="16" width="16" viewBox="0 0 16.1 16.1" fill="currentColor"><path d="M8 0a8 8 0 0 0-2.5 15.6c.4 0 .5-.2.5-.4v-1.5c-2 .4-2.5-.5-2.7-1 0-.1-.5-.9-.8-1-.3-.2-.7-.6 0-.6.6 0 1 .6 1.2.8.7 1.2 1.9 1 2.4.7 0-.5.2-.9.5-1-1.8-.3-3.7-1-3.7-4 0-.9.3-1.6.8-2.2 0-.2-.3-1 .1-2 0 0 .7-.3 2.2.7a7.4 7.4 0 0 1 4 0c1.5-1 2.2-.8 2.2-.8.5 1.1.2 2 .1 2.1.5.6.8 1.3.8 2.2 0 3-1.9 3.7-3.6 4 .3.2.5.7.5 1.4v2.2c0 .2.1.5.5.4A8 8 0 0 0 16 8a8 8 0 0 0-8-8z"/></svg></span>Edit on GitHub</a></li>
|
|
</ul>
|
|
</div>
|
|
<hr>
|
|
</header>
|
|
|
|
<div id="toc">
|
|
<h2>Table of Contents</h2>
|
|
<ul>
|
|
<li><span class="stability_2"><a href="#net_net">Net</a></span>
|
|
<ul>
|
|
<li><a href="#net_ipc_support">IPC support</a>
|
|
<ul>
|
|
<li><a href="#net_identifying_paths_for_ipc_connections">Identifying paths for IPC connections</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#net_class_net_server">Class: <code>net.Server</code></a>
|
|
<ul>
|
|
<li><a href="#net_new_net_server_options_connectionlistener"><code>new net.Server([options][, connectionListener])</code></a></li>
|
|
<li><a href="#net_event_close">Event: <code>'close'</code></a></li>
|
|
<li><a href="#net_event_connection">Event: <code>'connection'</code></a></li>
|
|
<li><a href="#net_event_error">Event: <code>'error'</code></a></li>
|
|
<li><a href="#net_event_listening">Event: <code>'listening'</code></a></li>
|
|
<li><a href="#net_server_address"><code>server.address()</code></a></li>
|
|
<li><a href="#net_server_close_callback"><code>server.close([callback])</code></a></li>
|
|
<li><span class="stability_0"><a href="#net_server_connections"><code>server.connections</code></a></span></li>
|
|
<li><a href="#net_server_getconnections_callback"><code>server.getConnections(callback)</code></a></li>
|
|
<li><a href="#net_server_listen"><code>server.listen()</code></a>
|
|
<ul>
|
|
<li><a href="#net_server_listen_handle_backlog_callback"><code>server.listen(handle[, backlog][, callback])</code></a></li>
|
|
<li><a href="#net_server_listen_options_callback"><code>server.listen(options[, callback])</code></a></li>
|
|
<li><a href="#net_server_listen_path_backlog_callback"><code>server.listen(path[, backlog][, callback])</code></a></li>
|
|
<li><a href="#net_server_listen_port_host_backlog_callback"><code>server.listen([port[, host[, backlog]]][, callback])</code></a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#net_server_listening"><code>server.listening</code></a></li>
|
|
<li><a href="#net_server_maxconnections"><code>server.maxConnections</code></a></li>
|
|
<li><a href="#net_server_ref"><code>server.ref()</code></a></li>
|
|
<li><a href="#net_server_unref"><code>server.unref()</code></a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#net_class_net_socket">Class: <code>net.Socket</code></a>
|
|
<ul>
|
|
<li><a href="#net_new_net_socket_options"><code>new net.Socket([options])</code></a></li>
|
|
<li><a href="#net_event_close_1">Event: <code>'close'</code></a></li>
|
|
<li><a href="#net_event_connect">Event: <code>'connect'</code></a></li>
|
|
<li><a href="#net_event_data">Event: <code>'data'</code></a></li>
|
|
<li><a href="#net_event_drain">Event: <code>'drain'</code></a></li>
|
|
<li><a href="#net_event_end">Event: <code>'end'</code></a></li>
|
|
<li><a href="#net_event_error_1">Event: <code>'error'</code></a></li>
|
|
<li><a href="#net_event_lookup">Event: <code>'lookup'</code></a></li>
|
|
<li><a href="#net_event_ready">Event: <code>'ready'</code></a></li>
|
|
<li><a href="#net_event_timeout">Event: <code>'timeout'</code></a></li>
|
|
<li><a href="#net_socket_address"><code>socket.address()</code></a></li>
|
|
<li><a href="#net_socket_buffersize"><code>socket.bufferSize</code></a></li>
|
|
<li><a href="#net_socket_bytesread"><code>socket.bytesRead</code></a></li>
|
|
<li><a href="#net_socket_byteswritten"><code>socket.bytesWritten</code></a></li>
|
|
<li><a href="#net_socket_connect"><code>socket.connect()</code></a>
|
|
<ul>
|
|
<li><a href="#net_socket_connect_options_connectlistener"><code>socket.connect(options[, connectListener])</code></a></li>
|
|
<li><a href="#net_socket_connect_path_connectlistener"><code>socket.connect(path[, connectListener])</code></a></li>
|
|
<li><a href="#net_socket_connect_port_host_connectlistener"><code>socket.connect(port[, host][, connectListener])</code></a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#net_socket_connecting"><code>socket.connecting</code></a></li>
|
|
<li><a href="#net_socket_destroy_error"><code>socket.destroy([error])</code></a></li>
|
|
<li><a href="#net_socket_destroyed"><code>socket.destroyed</code></a></li>
|
|
<li><a href="#net_socket_end_data_encoding_callback"><code>socket.end([data[, encoding]][, callback])</code></a></li>
|
|
<li><a href="#net_socket_localaddress"><code>socket.localAddress</code></a></li>
|
|
<li><a href="#net_socket_localport"><code>socket.localPort</code></a></li>
|
|
<li><a href="#net_socket_pause"><code>socket.pause()</code></a></li>
|
|
<li><a href="#net_socket_pending"><code>socket.pending</code></a></li>
|
|
<li><a href="#net_socket_ref"><code>socket.ref()</code></a></li>
|
|
<li><a href="#net_socket_remoteaddress"><code>socket.remoteAddress</code></a></li>
|
|
<li><a href="#net_socket_remotefamily"><code>socket.remoteFamily</code></a></li>
|
|
<li><a href="#net_socket_remoteport"><code>socket.remotePort</code></a></li>
|
|
<li><a href="#net_socket_resume"><code>socket.resume()</code></a></li>
|
|
<li><a href="#net_socket_setencoding_encoding"><code>socket.setEncoding([encoding])</code></a></li>
|
|
<li><a href="#net_socket_setkeepalive_enable_initialdelay"><code>socket.setKeepAlive([enable][, initialDelay])</code></a></li>
|
|
<li><a href="#net_socket_setnodelay_nodelay"><code>socket.setNoDelay([noDelay])</code></a></li>
|
|
<li><a href="#net_socket_settimeout_timeout_callback"><code>socket.setTimeout(timeout[, callback])</code></a></li>
|
|
<li><a href="#net_socket_unref"><code>socket.unref()</code></a></li>
|
|
<li><a href="#net_socket_write_data_encoding_callback"><code>socket.write(data[, encoding][, callback])</code></a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#net_net_connect"><code>net.connect()</code></a>
|
|
<ul>
|
|
<li><a href="#net_net_connect_options_connectlistener"><code>net.connect(options[, connectListener])</code></a></li>
|
|
<li><a href="#net_net_connect_path_connectlistener"><code>net.connect(path[, connectListener])</code></a></li>
|
|
<li><a href="#net_net_connect_port_host_connectlistener"><code>net.connect(port[, host][, connectListener])</code></a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#net_net_createconnection"><code>net.createConnection()</code></a>
|
|
<ul>
|
|
<li><a href="#net_net_createconnection_options_connectlistener"><code>net.createConnection(options[, connectListener])</code></a></li>
|
|
<li><a href="#net_net_createconnection_path_connectlistener"><code>net.createConnection(path[, connectListener])</code></a></li>
|
|
<li><a href="#net_net_createconnection_port_host_connectlistener"><code>net.createConnection(port[, host][, connectListener])</code></a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#net_net_createserver_options_connectionlistener"><code>net.createServer([options][, connectionListener])</code></a></li>
|
|
<li><a href="#net_net_isip_input"><code>net.isIP(input)</code></a></li>
|
|
<li><a href="#net_net_isipv4_input"><code>net.isIPv4(input)</code></a></li>
|
|
<li><a href="#net_net_isipv6_input"><code>net.isIPv6(input)</code></a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div id="apicontent">
|
|
<h1>Net<span><a class="mark" href="#net_net" id="net_net">#</a></span></h1>
|
|
|
|
<!--lint disable maximum-line-length-->
|
|
<p></p><div class="api_stability api_stability_2"><a href="documentation.html#documentation_stability_index">Stability: 2</a> - Stable</div><p></p>
|
|
<p><strong>Source Code:</strong> <a href="https://github.com/nodejs/node/blob/v12.22.9/lib/net.js">lib/net.js</a></p>
|
|
<p>The <code>net</code> module provides an asynchronous network API for creating stream-based
|
|
TCP or <a href="#net_ipc_support">IPC</a> servers (<a href="#net_net_createserver_options_connectionlistener"><code>net.createServer()</code></a>) and clients
|
|
(<a href="#net_net_createconnection"><code>net.createConnection()</code></a>).</p>
|
|
<p>It can be accessed using:</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> net = <span class="hljs-built_in">require</span>(<span class="hljs-string">'net'</span>);</code></pre>
|
|
<h2>IPC support<span><a class="mark" href="#net_ipc_support" id="net_ipc_support">#</a></span></h2>
|
|
<p>The <code>net</code> module supports IPC with named pipes on Windows, and Unix domain
|
|
sockets on other operating systems.</p>
|
|
<h3>Identifying paths for IPC connections<span><a class="mark" href="#net_identifying_paths_for_ipc_connections" id="net_identifying_paths_for_ipc_connections">#</a></span></h3>
|
|
<p><a href="#net_net_connect"><code>net.connect()</code></a>, <a href="#net_net_createconnection"><code>net.createConnection()</code></a>, <a href="#net_server_listen"><code>server.listen()</code></a> and
|
|
<a href="#net_socket_connect"><code>socket.connect()</code></a> take a <code>path</code> parameter to identify IPC endpoints.</p>
|
|
<p>On Unix, the local domain is also known as the Unix domain. The path is a
|
|
filesystem pathname. It gets truncated to an OS-dependent length of
|
|
<code>sizeof(sockaddr_un.sun_path) - 1</code>. Typical values are 107 bytes on Linux and
|
|
103 bytes on macOS. If a Node.js API abstraction creates the Unix domain socket,
|
|
it will unlink the Unix domain socket as well. For example,
|
|
<a href="#net_net_createserver_options_connectionlistener"><code>net.createServer()</code></a> may create a Unix domain socket and
|
|
<a href="#net_server_close_callback"><code>server.close()</code></a> will unlink it. But if a user creates the Unix domain
|
|
socket outside of these abstractions, the user will need to remove it. The same
|
|
applies when a Node.js API creates a Unix domain socket but the program then
|
|
crashes. In short, a Unix domain socket will be visible in the filesystem and
|
|
will persist until unlinked.</p>
|
|
<p>On Windows, the local domain is implemented using a named pipe. The path <em>must</em>
|
|
refer to an entry in <code>\\?\pipe\</code> or <code>\\.\pipe\</code>. Any characters are permitted,
|
|
but the latter may do some processing of pipe names, such as resolving <code>..</code>
|
|
sequences. Despite how it might look, the pipe namespace is flat. Pipes will
|
|
<em>not persist</em>. They are removed when the last reference to them is closed.
|
|
Unlike Unix domain sockets, Windows will close and remove the pipe when the
|
|
owning process exits.</p>
|
|
<p>JavaScript string escaping requires paths to be specified with extra backslash
|
|
escaping such as:</p>
|
|
<pre><code class="language-js">net.createServer().listen(
|
|
path.join(<span class="hljs-string">'\\\\?\\pipe'</span>, process.cwd(), <span class="hljs-string">'myctl'</span>));</code></pre>
|
|
<h2>Class: <code>net.Server</code><span><a class="mark" href="#net_class_net_server" id="net_class_net_server">#</a></span></h2>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.90</span>
|
|
</div>
|
|
<ul>
|
|
<li>Extends: <a href="events.html#events_class_eventemitter" class="type"><EventEmitter></a></li>
|
|
</ul>
|
|
<p>This class is used to create a TCP or <a href="#net_ipc_support">IPC</a> server.</p>
|
|
<h3><code>new net.Server([options][, connectionListener])</code><span><a class="mark" href="#net_new_net_server_options_connectionlistener" id="net_new_net_server_options_connectionlistener">#</a></span></h3>
|
|
<ul>
|
|
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> See
|
|
<a href="#net_net_createserver_options_connectionlistener"><code>net.createServer([options][, connectionListener])</code></a>.</li>
|
|
<li><code>connectionListener</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> Automatically set as a listener for the
|
|
<a href="#net_event_connection"><code>'connection'</code></a> event.</li>
|
|
<li>Returns: <a href="net.html#net_class_net_server" class="type"><net.Server></a></li>
|
|
</ul>
|
|
<p><code>net.Server</code> is an <a href="events.html#events_class_eventemitter"><code>EventEmitter</code></a> with the following events:</p>
|
|
<h3>Event: <code>'close'</code><span><a class="mark" href="#net_event_close" id="net_event_close">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.5.0</span>
|
|
</div>
|
|
<p>Emitted when the server closes. If connections exist, this
|
|
event is not emitted until all connections are ended.</p>
|
|
<h3>Event: <code>'connection'</code><span><a class="mark" href="#net_event_connection" id="net_event_connection">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.90</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="net.html#net_class_net_socket" class="type"><net.Socket></a> The connection object</li>
|
|
</ul>
|
|
<p>Emitted when a new connection is made. <code>socket</code> is an instance of
|
|
<code>net.Socket</code>.</p>
|
|
<h3>Event: <code>'error'</code><span><a class="mark" href="#net_event_error" id="net_event_error">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.90</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
|
</ul>
|
|
<p>Emitted when an error occurs. Unlike <a href="#net_class_net_socket"><code>net.Socket</code></a>, the <a href="#net_event_close"><code>'close'</code></a>
|
|
event will <strong>not</strong> be emitted directly following this event unless
|
|
<a href="#net_server_close_callback"><code>server.close()</code></a> is manually called. See the example in discussion of
|
|
<a href="#net_server_listen"><code>server.listen()</code></a>.</p>
|
|
<h3>Event: <code>'listening'</code><span><a class="mark" href="#net_event_listening" id="net_event_listening">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.90</span>
|
|
</div>
|
|
<p>Emitted when the server has been bound after calling <a href="#net_server_listen"><code>server.listen()</code></a>.</p>
|
|
<h3><code>server.address()</code><span><a class="mark" href="#net_server_address" id="net_server_address">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.90</span>
|
|
</div>
|
|
<ul>
|
|
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type" class="type"><null></a></li>
|
|
</ul>
|
|
<p>Returns the bound <code>address</code>, the address <code>family</code> name, and <code>port</code> of the server
|
|
as reported by the operating system if listening on an IP socket
|
|
(useful to find which port was assigned when getting an OS-assigned address):
|
|
<code>{ port: 12346, family: 'IPv4', address: '127.0.0.1' }</code>.</p>
|
|
<p>For a server listening on a pipe or Unix domain socket, the name is returned
|
|
as a string.</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> server = net.createServer(<span class="hljs-function">(<span class="hljs-params">socket</span>) =></span> {
|
|
socket.end(<span class="hljs-string">'goodbye\n'</span>);
|
|
}).on(<span class="hljs-string">'error'</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
|
|
<span class="hljs-comment">// Handle errors here.</span>
|
|
<span class="hljs-keyword">throw</span> err;
|
|
});
|
|
|
|
<span class="hljs-comment">// Grab an arbitrary unused port.</span>
|
|
server.listen(<span class="hljs-function">() =></span> {
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'opened server on'</span>, server.address());
|
|
});</code></pre>
|
|
<p><code>server.address()</code> returns <code>null</code> before the <code>'listening'</code> event has been
|
|
emitted or after calling <code>server.close()</code>.</p>
|
|
<h3><code>server.close([callback])</code><span><a class="mark" href="#net_server_close_callback" id="net_server_close_callback">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.90</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> Called when the server is closed.</li>
|
|
<li>Returns: <a href="net.html#net_class_net_server" class="type"><net.Server></a></li>
|
|
</ul>
|
|
<p>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 <a href="#net_event_close"><code>'close'</code></a> event.
|
|
The optional <code>callback</code> will be called once the <code>'close'</code> event occurs. Unlike
|
|
that event, it will be called with an <code>Error</code> as its only argument if the server
|
|
was not open when it was closed.</p>
|
|
<h3><code>server.connections</code><span><a class="mark" href="#net_server_connections" id="net_server_connections">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.2.0</span><span>Deprecated since: v0.9.7</span>
|
|
</div>
|
|
<p></p><div class="api_stability api_stability_0"><a href="documentation.html#documentation_stability_index">Stability: 0</a> - Deprecated: Use <a href="#net_server_getconnections_callback"><code>server.getConnections()</code></a> instead.</div><p></p>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type" class="type"><null></a></li>
|
|
</ul>
|
|
<p>The number of concurrent connections on the server.</p>
|
|
<p>This becomes <code>null</code> when sending a socket to a child with
|
|
<a href="child_process.html#child_process_child_process_fork_modulepath_args_options"><code>child_process.fork()</code></a>. To poll forks and get current number of active
|
|
connections, use asynchronous <a href="#net_server_getconnections_callback"><code>server.getConnections()</code></a> instead.</p>
|
|
<h3><code>server.getConnections(callback)</code><span><a class="mark" href="#net_server_getconnections_callback" id="net_server_getconnections_callback">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.9.7</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a></li>
|
|
<li>Returns: <a href="net.html#net_class_net_server" class="type"><net.Server></a></li>
|
|
</ul>
|
|
<p>Asynchronously get the number of concurrent connections on the server. Works
|
|
when sockets were sent to forks.</p>
|
|
<p>Callback should take two arguments <code>err</code> and <code>count</code>.</p>
|
|
<h3><code>server.listen()</code><span><a class="mark" href="#net_server_listen" id="net_server_listen">#</a></span></h3>
|
|
<p>Start a server listening for connections. A <code>net.Server</code> can be a TCP or
|
|
an <a href="#net_ipc_support">IPC</a> server depending on what it listens to.</p>
|
|
<p>Possible signatures:</p>
|
|
<ul>
|
|
<li><a href="#net_server_listen_handle_backlog_callback"><code>server.listen(handle[, backlog][, callback])</code></a></li>
|
|
<li><a href="#net_server_listen_options_callback"><code>server.listen(options[, callback])</code></a></li>
|
|
<li><a href="#net_server_listen_path_backlog_callback"><code>server.listen(path[, backlog][, callback])</code></a>
|
|
for <a href="#net_ipc_support">IPC</a> servers</li>
|
|
<li>
|
|
<a href="#net_server_listen_port_host_backlog_callback">
|
|
<code>server.listen([port[, host[, backlog]]][, callback])</code></a>
|
|
for TCP servers
|
|
</li>
|
|
</ul>
|
|
<p>This function is asynchronous. When the server starts listening, the
|
|
<a href="#net_event_listening"><code>'listening'</code></a> event will be emitted. The last parameter <code>callback</code>
|
|
will be added as a listener for the <a href="#net_event_listening"><code>'listening'</code></a> event.</p>
|
|
<p>All <code>listen()</code> methods can take a <code>backlog</code> parameter to specify the maximum
|
|
length of the queue of pending connections. The actual length will be determined
|
|
by the OS through sysctl settings such as <code>tcp_max_syn_backlog</code> and <code>somaxconn</code>
|
|
on Linux. The default value of this parameter is 511 (not 512).</p>
|
|
<p>All <a href="#net_class_net_socket"><code>net.Socket</code></a> are set to <code>SO_REUSEADDR</code> (see <a href="https://man7.org/linux/man-pages/man7/socket.7.html"><code>socket(7)</code></a> for
|
|
details).</p>
|
|
<p>The <code>server.listen()</code> method can be called again if and only if there was an
|
|
error during the first <code>server.listen()</code> call or <code>server.close()</code> has been
|
|
called. Otherwise, an <code>ERR_SERVER_ALREADY_LISTEN</code> error will be thrown.</p>
|
|
<p>One of the most common errors raised when listening is <code>EADDRINUSE</code>.
|
|
This happens when another server is already listening on the requested
|
|
<code>port</code>/<code>path</code>/<code>handle</code>. One way to handle this would be to retry
|
|
after a certain amount of time:</p>
|
|
<pre><code class="language-js">server.on(<span class="hljs-string">'error'</span>, <span class="hljs-function">(<span class="hljs-params">e</span>) =></span> {
|
|
<span class="hljs-keyword">if</span> (e.code === <span class="hljs-string">'EADDRINUSE'</span>) {
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'Address in use, retrying...'</span>);
|
|
<span class="hljs-built_in">setTimeout</span>(<span class="hljs-function">() =></span> {
|
|
server.close();
|
|
server.listen(PORT, HOST);
|
|
}, <span class="hljs-number">1000</span>);
|
|
}
|
|
});</code></pre>
|
|
<h4><code>server.listen(handle[, backlog][, callback])</code><span><a class="mark" href="#net_server_listen_handle_backlog_callback" id="net_server_listen_handle_backlog_callback">#</a></span></h4>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.5.10</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>handle</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a></li>
|
|
<li><code>backlog</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Common parameter of <a href="#net_server_listen"><code>server.listen()</code></a> functions</li>
|
|
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a></li>
|
|
<li>Returns: <a href="net.html#net_class_net_server" class="type"><net.Server></a></li>
|
|
</ul>
|
|
<p>Start a server listening for connections on a given <code>handle</code> that has
|
|
already been bound to a port, a Unix domain socket, or a Windows named pipe.</p>
|
|
<p>The <code>handle</code> object can be either a server, a socket (anything with an
|
|
underlying <code>_handle</code> member), or an object with an <code>fd</code> member that is a
|
|
valid file descriptor.</p>
|
|
<p>Listening on a file descriptor is not supported on Windows.</p>
|
|
<h4><code>server.listen(options[, callback])</code><span><a class="mark" href="#net_server_listen_options_callback" id="net_server_listen_options_callback">#</a></span></h4>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v11.4.0</td>
|
|
<td><p>The <code>ipv6Only</code> option is supported.</p></td></tr>
|
|
<tr><td>v0.11.14</td>
|
|
<td><p><span>Added in: v0.11.14</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> Required. Supports the following properties:
|
|
<ul>
|
|
<li><code>port</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
|
<li><code>host</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Will be ignored if <code>port</code> is specified. See
|
|
<a href="#net_identifying_paths_for_ipc_connections">Identifying paths for IPC connections</a>.</li>
|
|
<li><code>backlog</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Common parameter of <a href="#net_server_listen"><code>server.listen()</code></a>
|
|
functions.</li>
|
|
<li><code>exclusive</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> <strong>Default:</strong> <code>false</code></li>
|
|
<li><code>readableAll</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> For IPC servers makes the pipe readable
|
|
for all users. <strong>Default:</strong> <code>false</code>.</li>
|
|
<li><code>writableAll</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> For IPC servers makes the pipe writable
|
|
for all users. <strong>Default:</strong> <code>false</code>.</li>
|
|
<li><code>ipv6Only</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> For TCP servers, setting <code>ipv6Only</code> to <code>true</code> will
|
|
disable dual-stack support, i.e., binding to host <code>::</code> won't make
|
|
<code>0.0.0.0</code> be bound. <strong>Default:</strong> <code>false</code>.</li>
|
|
</ul>
|
|
</li>
|
|
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
|
functions.</li>
|
|
<li>Returns: <a href="net.html#net_class_net_server" class="type"><net.Server></a></li>
|
|
</ul>
|
|
<p>If <code>port</code> is specified, it behaves the same as
|
|
<a href="#net_server_listen_port_host_backlog_callback">
|
|
<code>server.listen([port[, host[, backlog]]][, callback])</code></a>.
|
|
Otherwise, if <code>path</code> is specified, it behaves the same as
|
|
<a href="#net_server_listen_path_backlog_callback"><code>server.listen(path[, backlog][, callback])</code></a>.
|
|
If none of them is specified, an error will be thrown.</p>
|
|
<p>If <code>exclusive</code> is <code>false</code> (default), then cluster workers will use the same
|
|
underlying handle, allowing connection handling duties to be shared. When
|
|
<code>exclusive</code> is <code>true</code>, the handle is not shared, and attempted port sharing
|
|
results in an error. An example which listens on an exclusive port is
|
|
shown below.</p>
|
|
<pre><code class="language-js">server.listen({
|
|
<span class="hljs-attr">host</span>: <span class="hljs-string">'localhost'</span>,
|
|
<span class="hljs-attr">port</span>: <span class="hljs-number">80</span>,
|
|
<span class="hljs-attr">exclusive</span>: <span class="hljs-literal">true</span>
|
|
});</code></pre>
|
|
<p>Starting an IPC server as root may cause the server path to be inaccessible for
|
|
unprivileged users. Using <code>readableAll</code> and <code>writableAll</code> will make the server
|
|
accessible for all users.</p>
|
|
<h4><code>server.listen(path[, backlog][, callback])</code><span><a class="mark" href="#net_server_listen_path_backlog_callback" id="net_server_listen_path_backlog_callback">#</a></span></h4>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.90</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Path the server should listen to. See
|
|
<a href="#net_identifying_paths_for_ipc_connections">Identifying paths for IPC connections</a>.</li>
|
|
<li><code>backlog</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Common parameter of <a href="#net_server_listen"><code>server.listen()</code></a> functions.</li>
|
|
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>.</li>
|
|
<li>Returns: <a href="net.html#net_class_net_server" class="type"><net.Server></a></li>
|
|
</ul>
|
|
<p>Start an <a href="#net_ipc_support">IPC</a> server listening for connections on the given <code>path</code>.</p>
|
|
<h4><code>server.listen([port[, host[, backlog]]][, callback])</code><span><a class="mark" href="#net_server_listen_port_host_backlog_callback" id="net_server_listen_port_host_backlog_callback">#</a></span></h4>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.90</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>port</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
|
<li><code>host</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
<li><code>backlog</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Common parameter of <a href="#net_server_listen"><code>server.listen()</code></a> functions.</li>
|
|
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>.</li>
|
|
<li>Returns: <a href="net.html#net_class_net_server" class="type"><net.Server></a></li>
|
|
</ul>
|
|
<p>Start a TCP server listening for connections on the given <code>port</code> and <code>host</code>.</p>
|
|
<p>If <code>port</code> is omitted or is 0, the operating system will assign an arbitrary
|
|
unused port, which can be retrieved by using <code>server.address().port</code>
|
|
after the <a href="#net_event_listening"><code>'listening'</code></a> event has been emitted.</p>
|
|
<p>If <code>host</code> is omitted, the server will accept connections on the
|
|
<a href="https://en.wikipedia.org/wiki/IPv6_address#Unspecified_address">unspecified IPv6 address</a> (<code>::</code>) when IPv6 is available, or the
|
|
<a href="https://en.wikipedia.org/wiki/0.0.0.0">unspecified IPv4 address</a> (<code>0.0.0.0</code>) otherwise.</p>
|
|
<p>In most operating systems, listening to the <a href="https://en.wikipedia.org/wiki/IPv6_address#Unspecified_address">unspecified IPv6 address</a> (<code>::</code>)
|
|
may cause the <code>net.Server</code> to also listen on the <a href="https://en.wikipedia.org/wiki/0.0.0.0">unspecified IPv4 address</a>
|
|
(<code>0.0.0.0</code>).</p>
|
|
<h3><code>server.listening</code><span><a class="mark" href="#net_server_listening" id="net_server_listening">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v5.7.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Indicates whether or not the server is listening for connections.</li>
|
|
</ul>
|
|
<h3><code>server.maxConnections</code><span><a class="mark" href="#net_server_maxconnections" id="net_server_maxconnections">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.2.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
|
</ul>
|
|
<p>Set this property to reject connections when the server's connection count gets
|
|
high.</p>
|
|
<p>It is not recommended to use this option once a socket has been sent to a child
|
|
with <a href="child_process.html#child_process_child_process_fork_modulepath_args_options"><code>child_process.fork()</code></a>.</p>
|
|
<h3><code>server.ref()</code><span><a class="mark" href="#net_server_ref" id="net_server_ref">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.9.1</span>
|
|
</div>
|
|
<ul>
|
|
<li>Returns: <a href="net.html#net_class_net_server" class="type"><net.Server></a></li>
|
|
</ul>
|
|
<p>Opposite of <code>unref()</code>, calling <code>ref()</code> on a previously <code>unref</code>ed server will
|
|
<em>not</em> let the program exit if it's the only server left (the default behavior).
|
|
If the server is <code>ref</code>ed calling <code>ref()</code> again will have no effect.</p>
|
|
<h3><code>server.unref()</code><span><a class="mark" href="#net_server_unref" id="net_server_unref">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.9.1</span>
|
|
</div>
|
|
<ul>
|
|
<li>Returns: <a href="net.html#net_class_net_server" class="type"><net.Server></a></li>
|
|
</ul>
|
|
<p>Calling <code>unref()</code> 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 <code>unref</code>ed calling
|
|
<code>unref()</code> again will have no effect.</p>
|
|
<h2>Class: <code>net.Socket</code><span><a class="mark" href="#net_class_net_socket" id="net_class_net_socket">#</a></span></h2>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.3.4</span>
|
|
</div>
|
|
<ul>
|
|
<li>Extends: <a href="stream.html#stream_class_stream_duplex" class="type"><stream.Duplex></a></li>
|
|
</ul>
|
|
<p>This class is an abstraction of a TCP socket or a streaming <a href="#net_ipc_support">IPC</a> endpoint
|
|
(uses named pipes on Windows, and Unix domain sockets otherwise). It is also
|
|
an <a href="events.html#events_class_eventemitter"><code>EventEmitter</code></a>.</p>
|
|
<p>A <code>net.Socket</code> can be created by the user and used directly to interact with
|
|
a server. For example, it is returned by <a href="#net_net_createconnection"><code>net.createConnection()</code></a>,
|
|
so the user can use it to talk to the server.</p>
|
|
<p>It can also 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
|
|
<a href="#net_event_connection"><code>'connection'</code></a> event emitted on a <a href="#net_class_net_server"><code>net.Server</code></a>, so the user can use
|
|
it to interact with the client.</p>
|
|
<h3><code>new net.Socket([options])</code><span><a class="mark" href="#net_new_net_socket_options" id="net_new_net_socket_options">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.3.4</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> Available options are:
|
|
<ul>
|
|
<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> If specified, wrap around an existing socket with
|
|
the given file descriptor, otherwise a new socket will be created.</li>
|
|
<li><code>allowHalfOpen</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Indicates whether half-opened TCP connections
|
|
are allowed. See <a href="#net_net_createserver_options_connectionlistener"><code>net.createServer()</code></a> and the <a href="#net_event_end"><code>'end'</code></a> event
|
|
for details. <strong>Default:</strong> <code>false</code>.</li>
|
|
<li><code>readable</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Allow reads on the socket when an <code>fd</code> is passed,
|
|
otherwise ignored. <strong>Default:</strong> <code>false</code>.</li>
|
|
<li><code>writable</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Allow writes on the socket when an <code>fd</code> is passed,
|
|
otherwise ignored. <strong>Default:</strong> <code>false</code>.</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns: <a href="net.html#net_class_net_socket" class="type"><net.Socket></a></li>
|
|
</ul>
|
|
<p>Creates a new socket object.</p>
|
|
<p>The newly created socket can be either a TCP socket or a streaming <a href="#net_ipc_support">IPC</a>
|
|
endpoint, depending on what it <a href="#net_socket_connect"><code>connect()</code></a> to.</p>
|
|
<h3>Event: <code>'close'</code><span><a class="mark" href="#net_event_close_1" id="net_event_close_1">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.90</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>hadError</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> <code>true</code> if the socket had a transmission error.</li>
|
|
</ul>
|
|
<p>Emitted once the socket is fully closed. The argument <code>hadError</code> is a boolean
|
|
which says if the socket was closed due to a transmission error.</p>
|
|
<h3>Event: <code>'connect'</code><span><a class="mark" href="#net_event_connect" id="net_event_connect">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.90</span>
|
|
</div>
|
|
<p>Emitted when a socket connection is successfully established.
|
|
See <a href="#net_net_createconnection"><code>net.createConnection()</code></a>.</p>
|
|
<h3>Event: <code>'data'</code><span><a class="mark" href="#net_event_data" id="net_event_data">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.90</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
</ul>
|
|
<p>Emitted when data is received. The argument <code>data</code> will be a <code>Buffer</code> or
|
|
<code>String</code>. Encoding of data is set by <a href="#net_socket_setencoding_encoding"><code>socket.setEncoding()</code></a>.</p>
|
|
<p>The data will be lost if there is no listener when a <code>Socket</code>
|
|
emits a <code>'data'</code> event.</p>
|
|
<h3>Event: <code>'drain'</code><span><a class="mark" href="#net_event_drain" id="net_event_drain">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.90</span>
|
|
</div>
|
|
<p>Emitted when the write buffer becomes empty. Can be used to throttle uploads.</p>
|
|
<p>See also: the return values of <code>socket.write()</code>.</p>
|
|
<h3>Event: <code>'end'</code><span><a class="mark" href="#net_event_end" id="net_event_end">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.90</span>
|
|
</div>
|
|
<p>Emitted when the other end of the socket sends a FIN packet, thus ending the
|
|
readable side of the socket.</p>
|
|
<p>By default (<code>allowHalfOpen</code> is <code>false</code>) the socket will send a FIN packet
|
|
back and destroy its file descriptor once it has written out its pending
|
|
write queue. However, if <code>allowHalfOpen</code> is set to <code>true</code>, the socket will
|
|
not automatically <a href="#net_socket_end_data_encoding_callback"><code>end()</code></a> its writable side, allowing the
|
|
user to write arbitrary amounts of data. The user must call
|
|
<a href="#net_socket_end_data_encoding_callback"><code>end()</code></a> explicitly to close the connection (i.e. sending a
|
|
FIN packet back).</p>
|
|
<h3>Event: <code>'error'</code><span><a class="mark" href="#net_event_error_1" id="net_event_error_1">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.90</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
|
</ul>
|
|
<p>Emitted when an error occurs. The <code>'close'</code> event will be called directly
|
|
following this event.</p>
|
|
<h3>Event: <code>'lookup'</code><span><a class="mark" href="#net_event_lookup" id="net_event_lookup">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v5.10.0</td>
|
|
<td><p>The <code>host</code> parameter is supported now.</p></td></tr>
|
|
<tr><td>v0.11.3</td>
|
|
<td><p><span>Added in: v0.11.3</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<p>Emitted after resolving the host name but before connecting.
|
|
Not applicable to Unix sockets.</p>
|
|
<ul>
|
|
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type" class="type"><null></a> The error object. See <a href="dns.html#dns_dns_lookup_hostname_options_callback"><code>dns.lookup()</code></a>.</li>
|
|
<li><code>address</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The IP address.</li>
|
|
<li><code>family</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type" class="type"><null></a> The address type. See <a href="dns.html#dns_dns_lookup_hostname_options_callback"><code>dns.lookup()</code></a>.</li>
|
|
<li><code>host</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The host name.</li>
|
|
</ul>
|
|
<h3>Event: <code>'ready'</code><span><a class="mark" href="#net_event_ready" id="net_event_ready">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v9.11.0</span>
|
|
</div>
|
|
<p>Emitted when a socket is ready to be used.</p>
|
|
<p>Triggered immediately after <code>'connect'</code>.</p>
|
|
<h3>Event: <code>'timeout'</code><span><a class="mark" href="#net_event_timeout" id="net_event_timeout">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.90</span>
|
|
</div>
|
|
<p>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.</p>
|
|
<p>See also: <a href="#net_socket_settimeout_timeout_callback"><code>socket.setTimeout()</code></a>.</p>
|
|
<h3><code>socket.address()</code><span><a class="mark" href="#net_socket_address" id="net_socket_address">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.90</span>
|
|
</div>
|
|
<ul>
|
|
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a></li>
|
|
</ul>
|
|
<p>Returns the bound <code>address</code>, the address <code>family</code> name and <code>port</code> of the
|
|
socket as reported by the operating system:
|
|
<code>{ port: 12346, family: 'IPv4', address: '127.0.0.1' }</code></p>
|
|
<h3><code>socket.bufferSize</code><span><a class="mark" href="#net_socket_buffersize" id="net_socket_buffersize">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.3.8</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
|
</ul>
|
|
<p>This property shows the number of characters buffered for writing. The buffer
|
|
may contain strings whose length after encoding is not yet known. So this number
|
|
is only an approximation of the number of bytes in the buffer.</p>
|
|
<p><code>net.Socket</code> has the property that <code>socket.write()</code> 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.</p>
|
|
<p>The consequence of this internal buffering is that memory may grow.
|
|
Users who experience large or growing <code>bufferSize</code> should attempt to
|
|
"throttle" the data flows in their program with
|
|
<a href="#net_socket_pause"><code>socket.pause()</code></a> and <a href="#net_socket_resume"><code>socket.resume()</code></a>.</p>
|
|
<h3><code>socket.bytesRead</code><span><a class="mark" href="#net_socket_bytesread" id="net_socket_bytesread">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.5.3</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
|
</ul>
|
|
<p>The amount of received bytes.</p>
|
|
<h3><code>socket.bytesWritten</code><span><a class="mark" href="#net_socket_byteswritten" id="net_socket_byteswritten">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.5.3</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
|
</ul>
|
|
<p>The amount of bytes sent.</p>
|
|
<h3><code>socket.connect()</code><span><a class="mark" href="#net_socket_connect" id="net_socket_connect">#</a></span></h3>
|
|
<p>Initiate a connection on a given socket.</p>
|
|
<p>Possible signatures:</p>
|
|
<ul>
|
|
<li><a href="#net_socket_connect_options_connectlistener"><code>socket.connect(options[, connectListener])</code></a></li>
|
|
<li><a href="#net_socket_connect_path_connectlistener"><code>socket.connect(path[, connectListener])</code></a>
|
|
for <a href="#net_ipc_support">IPC</a> connections.</li>
|
|
<li><a href="#net_socket_connect_port_host_connectlistener"><code>socket.connect(port[, host][, connectListener])</code></a>
|
|
for TCP connections.</li>
|
|
<li>Returns: <a href="net.html#net_class_net_socket" class="type"><net.Socket></a> The socket itself.</li>
|
|
</ul>
|
|
<p>This function is asynchronous. When the connection is established, the
|
|
<a href="#net_event_connect"><code>'connect'</code></a> event will be emitted. If there is a problem connecting,
|
|
instead of a <a href="#net_event_connect"><code>'connect'</code></a> event, an <a href="#net_event_error_1"><code>'error'</code></a> event will be emitted with
|
|
the error passed to the <a href="#net_event_error_1"><code>'error'</code></a> listener.
|
|
The last parameter <code>connectListener</code>, if supplied, will be added as a listener
|
|
for the <a href="#net_event_connect"><code>'connect'</code></a> event <strong>once</strong>.</p>
|
|
<p>This function should only be used for reconnecting a socket after
|
|
<code>'close'</code> has been emitted or otherwise it may lead to undefined
|
|
behavior.</p>
|
|
<h4><code>socket.connect(options[, connectListener])</code><span><a class="mark" href="#net_socket_connect_options_connectlistener" id="net_socket_connect_options_connectlistener">#</a></span></h4>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v12.10.0</td>
|
|
<td><p>Added <code>onread</code> option.</p></td></tr>
|
|
<tr><td>v6.0.0</td>
|
|
<td><p>The <code>hints</code> option defaults to <code>0</code> in all cases now. Previously, in the absence of the <code>family</code> option it would default to <code>dns.ADDRCONFIG | dns.V4MAPPED</code>.</p></td></tr>
|
|
<tr><td>v5.11.0</td>
|
|
<td><p>The <code>hints</code> option is supported now.</p></td></tr>
|
|
<tr><td>v0.1.90</td>
|
|
<td><p><span>Added in: v0.1.90</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a></li>
|
|
<li><code>connectListener</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> Common parameter of <a href="#net_socket_connect"><code>socket.connect()</code></a>
|
|
methods. Will be added as a listener for the <a href="#net_event_connect"><code>'connect'</code></a> event once.</li>
|
|
<li>Returns: <a href="net.html#net_class_net_socket" class="type"><net.Socket></a> The socket itself.</li>
|
|
</ul>
|
|
<p>Initiate a connection on a given socket. Normally this method is not needed,
|
|
the socket should be created and opened with <a href="#net_net_createconnection"><code>net.createConnection()</code></a>. Use
|
|
this only when implementing a custom Socket.</p>
|
|
<p>For TCP connections, available <code>options</code> are:</p>
|
|
<ul>
|
|
<li><code>port</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Required. Port the socket should connect to.</li>
|
|
<li><code>host</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Host the socket should connect to. <strong>Default:</strong> <code>'localhost'</code>.</li>
|
|
<li><code>localAddress</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Local address the socket should connect from.</li>
|
|
<li><code>localPort</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Local port the socket should connect from.</li>
|
|
<li><code>family</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a>: Version of IP stack. Must be <code>4</code>, <code>6</code>, or <code>0</code>. The value
|
|
<code>0</code> indicates that both IPv4 and IPv6 addresses are allowed. <strong>Default:</strong> <code>0</code>.</li>
|
|
<li><code>hints</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Optional <a href="dns.html#dns_supported_getaddrinfo_flags"><code>dns.lookup()</code> hints</a>.</li>
|
|
<li><code>lookup</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> Custom lookup function. <strong>Default:</strong> <a href="dns.html#dns_dns_lookup_hostname_options_callback"><code>dns.lookup()</code></a>.</li>
|
|
</ul>
|
|
<p>For <a href="#net_ipc_support">IPC</a> connections, available <code>options</code> are:</p>
|
|
<ul>
|
|
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Required. Path the client should connect to.
|
|
See <a href="#net_identifying_paths_for_ipc_connections">Identifying paths for IPC connections</a>. If provided, the TCP-specific
|
|
options above are ignored.</li>
|
|
</ul>
|
|
<p>For both types, available <code>options</code> include:</p>
|
|
<ul>
|
|
<li><code>onread</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> If specified, incoming data is stored in a single <code>buffer</code>
|
|
and passed to the supplied <code>callback</code> when data arrives on the socket.
|
|
This will cause the streaming functionality to not provide any data.
|
|
The socket will emit events like <code>'error'</code>, <code>'end'</code>, and <code>'close'</code>
|
|
as usual. Methods like <code>pause()</code> and <code>resume()</code> will also behave as
|
|
expected.
|
|
<ul>
|
|
<li><code>buffer</code> <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array" class="type"><Uint8Array></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> Either a reusable chunk of memory to
|
|
use for storing incoming data or a function that returns such.</li>
|
|
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> This function is called for every chunk of incoming
|
|
data. Two arguments are passed to it: the number of bytes written to
|
|
<code>buffer</code> and a reference to <code>buffer</code>. Return <code>false</code> from this function to
|
|
implicitly <code>pause()</code> the socket. This function will be executed in the
|
|
global context.</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<p>Following is an example of a client using the <code>onread</code> option:</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> net = <span class="hljs-built_in">require</span>(<span class="hljs-string">'net'</span>);
|
|
net.connect({
|
|
<span class="hljs-attr">port</span>: <span class="hljs-number">80</span>,
|
|
<span class="hljs-attr">onread</span>: {
|
|
<span class="hljs-comment">// Reuses a 4KiB Buffer for every read from the socket.</span>
|
|
<span class="hljs-attr">buffer</span>: Buffer.alloc(<span class="hljs-number">4</span> * <span class="hljs-number">1024</span>),
|
|
<span class="hljs-attr">callback</span>: <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">nread, buf</span>) </span>{
|
|
<span class="hljs-comment">// Received data is available in `buf` from 0 to `nread`.</span>
|
|
<span class="hljs-built_in">console</span>.log(buf.toString(<span class="hljs-string">'utf8'</span>, <span class="hljs-number">0</span>, nread));
|
|
}
|
|
}
|
|
});</code></pre>
|
|
<h4><code>socket.connect(path[, connectListener])</code><span><a class="mark" href="#net_socket_connect_path_connectlistener" id="net_socket_connect_path_connectlistener">#</a></span></h4>
|
|
<ul>
|
|
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Path the client should connect to. See
|
|
<a href="#net_identifying_paths_for_ipc_connections">Identifying paths for IPC connections</a>.</li>
|
|
<li><code>connectListener</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> Common parameter of <a href="#net_socket_connect"><code>socket.connect()</code></a>
|
|
methods. Will be added as a listener for the <a href="#net_event_connect"><code>'connect'</code></a> event once.</li>
|
|
<li>Returns: <a href="net.html#net_class_net_socket" class="type"><net.Socket></a> The socket itself.</li>
|
|
</ul>
|
|
<p>Initiate an <a href="#net_ipc_support">IPC</a> connection on the given socket.</p>
|
|
<p>Alias to
|
|
<a href="#net_socket_connect_options_connectlistener"><code>socket.connect(options[, connectListener])</code></a>
|
|
called with <code>{ path: path }</code> as <code>options</code>.</p>
|
|
<h4><code>socket.connect(port[, host][, connectListener])</code><span><a class="mark" href="#net_socket_connect_port_host_connectlistener" id="net_socket_connect_port_host_connectlistener">#</a></span></h4>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.90</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>port</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Port the client should connect to.</li>
|
|
<li><code>host</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Host the client should connect to.</li>
|
|
<li><code>connectListener</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> Common parameter of <a href="#net_socket_connect"><code>socket.connect()</code></a>
|
|
methods. Will be added as a listener for the <a href="#net_event_connect"><code>'connect'</code></a> event once.</li>
|
|
<li>Returns: <a href="net.html#net_class_net_socket" class="type"><net.Socket></a> The socket itself.</li>
|
|
</ul>
|
|
<p>Initiate a TCP connection on the given socket.</p>
|
|
<p>Alias to
|
|
<a href="#net_socket_connect_options_connectlistener"><code>socket.connect(options[, connectListener])</code></a>
|
|
called with <code>{port: port, host: host}</code> as <code>options</code>.</p>
|
|
<h3><code>socket.connecting</code><span><a class="mark" href="#net_socket_connecting" id="net_socket_connecting">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v6.1.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li>
|
|
</ul>
|
|
<p>If <code>true</code>,
|
|
<a href="#net_socket_connect_options_connectlistener"><code>socket.connect(options[, connectListener])</code></a> was
|
|
called and has not yet finished. It will stay <code>true</code> until the socket becomes
|
|
connected, then it is set to <code>false</code> and the <code>'connect'</code> event is emitted. Note
|
|
that the
|
|
<a href="#net_socket_connect_options_connectlistener"><code>socket.connect(options[, connectListener])</code></a>
|
|
callback is a listener for the <code>'connect'</code> event.</p>
|
|
<h3><code>socket.destroy([error])</code><span><a class="mark" href="#net_socket_destroy_error" id="net_socket_destroy_error">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.90</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>error</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a></li>
|
|
<li>Returns: <a href="net.html#net_class_net_socket" class="type"><net.Socket></a></li>
|
|
</ul>
|
|
<p>Ensures that no more I/O activity happens on this socket.
|
|
Destroys the stream and closes the connection.</p>
|
|
<p>See <a href="stream.html#stream_writable_destroy_error"><code>writable.destroy()</code></a> for further details.</p>
|
|
<h3><code>socket.destroyed</code><span><a class="mark" href="#net_socket_destroyed" id="net_socket_destroyed">#</a></span></h3>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Indicates if the connection is destroyed or not. Once a
|
|
connection is destroyed no further data can be transferred using it.</li>
|
|
</ul>
|
|
<p>See <a href="stream.html#stream_writable_destroyed"><code>writable.destroyed</code></a> for further details.</p>
|
|
<h3><code>socket.end([data[, encoding]][, callback])</code><span><a class="mark" href="#net_socket_end_data_encoding_callback" id="net_socket_end_data_encoding_callback">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.90</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>data</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array" class="type"><Uint8Array></a></li>
|
|
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Only used when data is <code>string</code>. <strong>Default:</strong> <code>'utf8'</code>.</li>
|
|
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> Optional callback for when the socket is finished.</li>
|
|
<li>Returns: <a href="net.html#net_class_net_socket" class="type"><net.Socket></a> The socket itself.</li>
|
|
</ul>
|
|
<p>Half-closes the socket. i.e., it sends a FIN packet. It is possible the
|
|
server will still send some data.</p>
|
|
<p>See <a href="stream.html#stream_writable_end_chunk_encoding_callback"><code>writable.end()</code></a> for further details.</p>
|
|
<h3><code>socket.localAddress</code><span><a class="mark" href="#net_socket_localaddress" id="net_socket_localaddress">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.9.6</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
</ul>
|
|
<p>The string representation of the local IP address the remote client is
|
|
connecting on. For example, in a server listening on <code>'0.0.0.0'</code>, if a client
|
|
connects on <code>'192.168.1.1'</code>, the value of <code>socket.localAddress</code> would be
|
|
<code>'192.168.1.1'</code>.</p>
|
|
<h3><code>socket.localPort</code><span><a class="mark" href="#net_socket_localport" id="net_socket_localport">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.9.6</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
|
</ul>
|
|
<p>The numeric representation of the local port. For example, <code>80</code> or <code>21</code>.</p>
|
|
<h3><code>socket.pause()</code><span><a class="mark" href="#net_socket_pause" id="net_socket_pause">#</a></span></h3>
|
|
<ul>
|
|
<li>Returns: <a href="net.html#net_class_net_socket" class="type"><net.Socket></a> The socket itself.</li>
|
|
</ul>
|
|
<p>Pauses the reading of data. That is, <a href="#net_event_data"><code>'data'</code></a> events will not be emitted.
|
|
Useful to throttle back an upload.</p>
|
|
<h3><code>socket.pending</code><span><a class="mark" href="#net_socket_pending" id="net_socket_pending">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v11.2.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li>
|
|
</ul>
|
|
<p>This is <code>true</code> if the socket is not connected yet, either because <code>.connect()</code>
|
|
has not yet been called or because it is still in the process of connecting
|
|
(see <a href="#net_socket_connecting"><code>socket.connecting</code></a>).</p>
|
|
<h3><code>socket.ref()</code><span><a class="mark" href="#net_socket_ref" id="net_socket_ref">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.9.1</span>
|
|
</div>
|
|
<ul>
|
|
<li>Returns: <a href="net.html#net_class_net_socket" class="type"><net.Socket></a> The socket itself.</li>
|
|
</ul>
|
|
<p>Opposite of <code>unref()</code>, calling <code>ref()</code> on a previously <code>unref</code>ed socket will
|
|
<em>not</em> let the program exit if it's the only socket left (the default behavior).
|
|
If the socket is <code>ref</code>ed calling <code>ref</code> again will have no effect.</p>
|
|
<h3><code>socket.remoteAddress</code><span><a class="mark" href="#net_socket_remoteaddress" id="net_socket_remoteaddress">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.5.10</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
</ul>
|
|
<p>The string representation of the remote IP address. For example,
|
|
<code>'74.125.127.100'</code> or <code>'2001:4860:a005::68'</code>. Value may be <code>undefined</code> if
|
|
the socket is destroyed (for example, if the client disconnected).</p>
|
|
<h3><code>socket.remoteFamily</code><span><a class="mark" href="#net_socket_remotefamily" id="net_socket_remotefamily">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.11.14</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
</ul>
|
|
<p>The string representation of the remote IP family. <code>'IPv4'</code> or <code>'IPv6'</code>.</p>
|
|
<h3><code>socket.remotePort</code><span><a class="mark" href="#net_socket_remoteport" id="net_socket_remoteport">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.5.10</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
|
</ul>
|
|
<p>The numeric representation of the remote port. For example, <code>80</code> or <code>21</code>.</p>
|
|
<h3><code>socket.resume()</code><span><a class="mark" href="#net_socket_resume" id="net_socket_resume">#</a></span></h3>
|
|
<ul>
|
|
<li>Returns: <a href="net.html#net_class_net_socket" class="type"><net.Socket></a> The socket itself.</li>
|
|
</ul>
|
|
<p>Resumes reading after a call to <a href="#net_socket_pause"><code>socket.pause()</code></a>.</p>
|
|
<h3><code>socket.setEncoding([encoding])</code><span><a class="mark" href="#net_socket_setencoding_encoding" id="net_socket_setencoding_encoding">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.90</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
<li>Returns: <a href="net.html#net_class_net_socket" class="type"><net.Socket></a> The socket itself.</li>
|
|
</ul>
|
|
<p>Set the encoding for the socket as a <a href="stream.html#stream_class_stream_readable">Readable Stream</a>. See
|
|
<a href="stream.html#stream_readable_setencoding_encoding"><code>readable.setEncoding()</code></a> for more information.</p>
|
|
<h3><code>socket.setKeepAlive([enable][, initialDelay])</code><span><a class="mark" href="#net_socket_setkeepalive_enable_initialdelay" id="net_socket_setkeepalive_enable_initialdelay">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.92</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>enable</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> <strong>Default:</strong> <code>false</code></li>
|
|
<li><code>initialDelay</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> <strong>Default:</strong> <code>0</code></li>
|
|
<li>Returns: <a href="net.html#net_class_net_socket" class="type"><net.Socket></a> The socket itself.</li>
|
|
</ul>
|
|
<p>Enable/disable keep-alive functionality, and optionally set the initial
|
|
delay before the first keepalive probe is sent on an idle socket.</p>
|
|
<p>Set <code>initialDelay</code> (in milliseconds) to set the delay between the last
|
|
data packet received and the first keepalive probe. Setting <code>0</code> for
|
|
<code>initialDelay</code> will leave the value unchanged from the default
|
|
(or previous) setting.</p>
|
|
<h3><code>socket.setNoDelay([noDelay])</code><span><a class="mark" href="#net_socket_setnodelay_nodelay" id="net_socket_setnodelay_nodelay">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.90</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>noDelay</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> <strong>Default:</strong> <code>true</code></li>
|
|
<li>Returns: <a href="net.html#net_class_net_socket" class="type"><net.Socket></a> The socket itself.</li>
|
|
</ul>
|
|
<p>Enable/disable the use of Nagle's algorithm.</p>
|
|
<p>When a TCP connection is created, it will have Nagle's algorithm enabled.</p>
|
|
<p>Nagle's algorithm delays data before it is sent via the network. It attempts
|
|
to optimize throughput at the expense of latency.</p>
|
|
<p>Passing <code>true</code> for <code>noDelay</code> or not passing an argument will disable Nagle's
|
|
algorithm for the socket. Passing <code>false</code> for <code>noDelay</code> will enable Nagle's
|
|
algorithm.</p>
|
|
<h3><code>socket.setTimeout(timeout[, callback])</code><span><a class="mark" href="#net_socket_settimeout_timeout_callback" id="net_socket_settimeout_timeout_callback">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.90</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>timeout</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
|
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a></li>
|
|
<li>Returns: <a href="net.html#net_class_net_socket" class="type"><net.Socket></a> The socket itself.</li>
|
|
</ul>
|
|
<p>Sets the socket to timeout after <code>timeout</code> milliseconds of inactivity on
|
|
the socket. By default <code>net.Socket</code> do not have a timeout.</p>
|
|
<p>When an idle timeout is triggered the socket will receive a <a href="#net_event_timeout"><code>'timeout'</code></a>
|
|
event but the connection will not be severed. The user must manually call
|
|
<a href="#net_socket_end_data_encoding_callback"><code>socket.end()</code></a> or <a href="#net_socket_destroy_error"><code>socket.destroy()</code></a> to end the connection.</p>
|
|
<pre><code class="language-js">socket.setTimeout(<span class="hljs-number">3000</span>);
|
|
socket.on(<span class="hljs-string">'timeout'</span>, <span class="hljs-function">() =></span> {
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'socket timeout'</span>);
|
|
socket.end();
|
|
});</code></pre>
|
|
<p>If <code>timeout</code> is 0, then the existing idle timeout is disabled.</p>
|
|
<p>The optional <code>callback</code> parameter will be added as a one-time listener for the
|
|
<a href="#net_event_timeout"><code>'timeout'</code></a> event.</p>
|
|
<h3><code>socket.unref()</code><span><a class="mark" href="#net_socket_unref" id="net_socket_unref">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.9.1</span>
|
|
</div>
|
|
<ul>
|
|
<li>Returns: <a href="net.html#net_class_net_socket" class="type"><net.Socket></a> The socket itself.</li>
|
|
</ul>
|
|
<p>Calling <code>unref()</code> 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 <code>unref</code>ed calling
|
|
<code>unref()</code> again will have no effect.</p>
|
|
<h3><code>socket.write(data[, encoding][, callback])</code><span><a class="mark" href="#net_socket_write_data_encoding_callback" id="net_socket_write_data_encoding_callback">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.90</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>data</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array" class="type"><Uint8Array></a></li>
|
|
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Only used when data is <code>string</code>. <strong>Default:</strong> <code>utf8</code>.</li>
|
|
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a></li>
|
|
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li>
|
|
</ul>
|
|
<p>Sends data on the socket. The second parameter specifies the encoding in the
|
|
case of a string. It defaults to UTF8 encoding.</p>
|
|
<p>Returns <code>true</code> if the entire data was flushed successfully to the kernel
|
|
buffer. Returns <code>false</code> if all or part of the data was queued in user memory.
|
|
<a href="#net_event_drain"><code>'drain'</code></a> will be emitted when the buffer is again free.</p>
|
|
<p>The optional <code>callback</code> parameter will be executed when the data is finally
|
|
written out, which may not be immediately.</p>
|
|
<p>See <code>Writable</code> stream <a href="stream.html#stream_writable_write_chunk_encoding_callback"><code>write()</code></a> method for more
|
|
information.</p>
|
|
<h2><code>net.connect()</code><span><a class="mark" href="#net_net_connect" id="net_net_connect">#</a></span></h2>
|
|
<p>Aliases to
|
|
<a href="#net_net_createconnection"><code>net.createConnection()</code></a>.</p>
|
|
<p>Possible signatures:</p>
|
|
<ul>
|
|
<li><a href="#net_net_connect_options_connectlistener"><code>net.connect(options[, connectListener])</code></a></li>
|
|
<li><a href="#net_net_connect_path_connectlistener"><code>net.connect(path[, connectListener])</code></a> for <a href="#net_ipc_support">IPC</a>
|
|
connections.</li>
|
|
<li><a href="#net_net_connect_port_host_connectlistener"><code>net.connect(port[, host][, connectListener])</code></a>
|
|
for TCP connections.</li>
|
|
</ul>
|
|
<h3><code>net.connect(options[, connectListener])</code><span><a class="mark" href="#net_net_connect_options_connectlistener" id="net_net_connect_options_connectlistener">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.7.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a></li>
|
|
<li><code>connectListener</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a></li>
|
|
<li>Returns: <a href="net.html#net_class_net_socket" class="type"><net.Socket></a></li>
|
|
</ul>
|
|
<p>Alias to
|
|
<a href="#net_net_createconnection_options_connectlistener"><code>net.createConnection(options[, connectListener])</code></a>.</p>
|
|
<h3><code>net.connect(path[, connectListener])</code><span><a class="mark" href="#net_net_connect_path_connectlistener" id="net_net_connect_path_connectlistener">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.90</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
<li><code>connectListener</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a></li>
|
|
<li>Returns: <a href="net.html#net_class_net_socket" class="type"><net.Socket></a></li>
|
|
</ul>
|
|
<p>Alias to
|
|
<a href="#net_net_createconnection_path_connectlistener"><code>net.createConnection(path[, connectListener])</code></a>.</p>
|
|
<h3><code>net.connect(port[, host][, connectListener])</code><span><a class="mark" href="#net_net_connect_port_host_connectlistener" id="net_net_connect_port_host_connectlistener">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.90</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>port</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
|
<li><code>host</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
<li><code>connectListener</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a></li>
|
|
<li>Returns: <a href="net.html#net_class_net_socket" class="type"><net.Socket></a></li>
|
|
</ul>
|
|
<p>Alias to
|
|
<a href="#net_net_createconnection_port_host_connectlistener"><code>net.createConnection(port[, host][, connectListener])</code></a>.</p>
|
|
<h2><code>net.createConnection()</code><span><a class="mark" href="#net_net_createconnection" id="net_net_createconnection">#</a></span></h2>
|
|
<p>A factory function, which creates a new <a href="#net_class_net_socket"><code>net.Socket</code></a>,
|
|
immediately initiates connection with <a href="#net_socket_connect"><code>socket.connect()</code></a>,
|
|
then returns the <code>net.Socket</code> that starts the connection.</p>
|
|
<p>When the connection is established, a <a href="#net_event_connect"><code>'connect'</code></a> event will be emitted
|
|
on the returned socket. The last parameter <code>connectListener</code>, if supplied,
|
|
will be added as a listener for the <a href="#net_event_connect"><code>'connect'</code></a> event <strong>once</strong>.</p>
|
|
<p>Possible signatures:</p>
|
|
<ul>
|
|
<li><a href="#net_net_createconnection_options_connectlistener"><code>net.createConnection(options[, connectListener])</code></a></li>
|
|
<li><a href="#net_net_createconnection_path_connectlistener"><code>net.createConnection(path[, connectListener])</code></a>
|
|
for <a href="#net_ipc_support">IPC</a> connections.</li>
|
|
<li><a href="#net_net_createconnection_port_host_connectlistener"><code>net.createConnection(port[, host][, connectListener])</code></a>
|
|
for TCP connections.</li>
|
|
</ul>
|
|
<p>The <a href="#net_net_connect"><code>net.connect()</code></a> function is an alias to this function.</p>
|
|
<h3><code>net.createConnection(options[, connectListener])</code><span><a class="mark" href="#net_net_createconnection_options_connectlistener" id="net_net_createconnection_options_connectlistener">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.90</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> Required. Will be passed to both the
|
|
<a href="#net_new_net_socket_options"><code>new net.Socket([options])</code></a> call and the
|
|
<a href="#net_socket_connect_options_connectlistener"><code>socket.connect(options[, connectListener])</code></a>
|
|
method.</li>
|
|
<li><code>connectListener</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> Common parameter of the
|
|
<a href="#net_net_createconnection"><code>net.createConnection()</code></a> functions. If supplied, will be added as
|
|
a listener for the <a href="#net_event_connect"><code>'connect'</code></a> event on the returned socket once.</li>
|
|
<li>Returns: <a href="net.html#net_class_net_socket" class="type"><net.Socket></a> The newly created socket used to start the connection.</li>
|
|
</ul>
|
|
<p>For available options, see
|
|
<a href="#net_new_net_socket_options"><code>new net.Socket([options])</code></a>
|
|
and <a href="#net_socket_connect_options_connectlistener"><code>socket.connect(options[, connectListener])</code></a>.</p>
|
|
<p>Additional options:</p>
|
|
<ul>
|
|
<li><code>timeout</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> If set, will be used to call
|
|
<a href="#net_socket_settimeout_timeout_callback"><code>socket.setTimeout(timeout)</code></a> after the socket is created, but before
|
|
it starts the connection.</li>
|
|
</ul>
|
|
<p>Following is an example of a client of the echo server described
|
|
in the <a href="#net_net_createserver_options_connectionlistener"><code>net.createServer()</code></a> section:</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> net = <span class="hljs-built_in">require</span>(<span class="hljs-string">'net'</span>);
|
|
<span class="hljs-keyword">const</span> client = net.createConnection({ <span class="hljs-attr">port</span>: <span class="hljs-number">8124</span> }, <span class="hljs-function">() =></span> {
|
|
<span class="hljs-comment">// 'connect' listener.</span>
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'connected to server!'</span>);
|
|
client.write(<span class="hljs-string">'world!\r\n'</span>);
|
|
});
|
|
client.on(<span class="hljs-string">'data'</span>, <span class="hljs-function">(<span class="hljs-params">data</span>) =></span> {
|
|
<span class="hljs-built_in">console</span>.log(data.toString());
|
|
client.end();
|
|
});
|
|
client.on(<span class="hljs-string">'end'</span>, <span class="hljs-function">() =></span> {
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'disconnected from server'</span>);
|
|
});</code></pre>
|
|
<p>To connect on the socket <code>/tmp/echo.sock</code>:</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> client = net.createConnection({ <span class="hljs-attr">path</span>: <span class="hljs-string">'/tmp/echo.sock'</span> });</code></pre>
|
|
<h3><code>net.createConnection(path[, connectListener])</code><span><a class="mark" href="#net_net_createconnection_path_connectlistener" id="net_net_createconnection_path_connectlistener">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.90</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Path the socket should connect to. Will be passed to
|
|
<a href="#net_socket_connect_path_connectlistener"><code>socket.connect(path[, connectListener])</code></a>.
|
|
See <a href="#net_identifying_paths_for_ipc_connections">Identifying paths for IPC connections</a>.</li>
|
|
<li><code>connectListener</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> Common parameter of the
|
|
<a href="#net_net_createconnection"><code>net.createConnection()</code></a> functions, an "once" listener for the
|
|
<code>'connect'</code> event on the initiating socket. Will be passed to
|
|
<a href="#net_socket_connect_path_connectlistener"><code>socket.connect(path[, connectListener])</code></a>.</li>
|
|
<li>Returns: <a href="net.html#net_class_net_socket" class="type"><net.Socket></a> The newly created socket used to start the connection.</li>
|
|
</ul>
|
|
<p>Initiates an <a href="#net_ipc_support">IPC</a> connection.</p>
|
|
<p>This function creates a new <a href="#net_class_net_socket"><code>net.Socket</code></a> with all options set to default,
|
|
immediately initiates connection with
|
|
<a href="#net_socket_connect_path_connectlistener"><code>socket.connect(path[, connectListener])</code></a>,
|
|
then returns the <code>net.Socket</code> that starts the connection.</p>
|
|
<h3><code>net.createConnection(port[, host][, connectListener])</code><span><a class="mark" href="#net_net_createconnection_port_host_connectlistener" id="net_net_createconnection_port_host_connectlistener">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.90</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>port</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Port the socket should connect to. Will be passed to
|
|
<a href="#net_socket_connect_port_host_connectlistener"><code>socket.connect(port[, host][, connectListener])</code></a>.</li>
|
|
<li><code>host</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Host the socket should connect to. Will be passed to
|
|
<a href="#net_socket_connect_port_host_connectlistener"><code>socket.connect(port[, host][, connectListener])</code></a>.
|
|
<strong>Default:</strong> <code>'localhost'</code>.</li>
|
|
<li><code>connectListener</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> Common parameter of the
|
|
<a href="#net_net_createconnection"><code>net.createConnection()</code></a> functions, an "once" listener for the
|
|
<code>'connect'</code> event on the initiating socket. Will be passed to
|
|
<a href="#net_socket_connect_port_host_connectlistener"><code>socket.connect(port[, host][, connectListener])</code></a>.</li>
|
|
<li>Returns: <a href="net.html#net_class_net_socket" class="type"><net.Socket></a> The newly created socket used to start the connection.</li>
|
|
</ul>
|
|
<p>Initiates a TCP connection.</p>
|
|
<p>This function creates a new <a href="#net_class_net_socket"><code>net.Socket</code></a> with all options set to default,
|
|
immediately initiates connection with
|
|
<a href="#net_socket_connect_port_host_connectlistener"><code>socket.connect(port[, host][, connectListener])</code></a>,
|
|
then returns the <code>net.Socket</code> that starts the connection.</p>
|
|
<h2><code>net.createServer([options][, connectionListener])</code><span><a class="mark" href="#net_net_createserver_options_connectionlistener" id="net_net_createserver_options_connectionlistener">#</a></span></h2>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.5.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
|
<ul>
|
|
<li><code>allowHalfOpen</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Indicates whether half-opened TCP
|
|
connections are allowed. <strong>Default:</strong> <code>false</code>.</li>
|
|
<li><code>pauseOnConnect</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Indicates whether the socket should be
|
|
paused on incoming connections. <strong>Default:</strong> <code>false</code>.</li>
|
|
</ul>
|
|
</li>
|
|
<li><code>connectionListener</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> Automatically set as a listener for the
|
|
<a href="#net_event_connection"><code>'connection'</code></a> event.</li>
|
|
<li>Returns: <a href="net.html#net_class_net_server" class="type"><net.Server></a></li>
|
|
</ul>
|
|
<p>Creates a new TCP or <a href="#net_ipc_support">IPC</a> server.</p>
|
|
<p>If <code>allowHalfOpen</code> is set to <code>true</code>, when the other end of the socket
|
|
sends a FIN packet, the server will only send a FIN packet back when
|
|
<a href="#net_socket_end_data_encoding_callback"><code>socket.end()</code></a> is explicitly called, until then the connection is
|
|
half-closed (non-readable but still writable). See <a href="#net_event_end"><code>'end'</code></a> event
|
|
and <a href="https://tools.ietf.org/html/rfc1122">RFC 1122</a> (section 4.2.2.13) for more information.</p>
|
|
<p>If <code>pauseOnConnect</code> is set to <code>true</code>, then the socket associated with each
|
|
incoming connection will be paused, and no data will be read from its handle.
|
|
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
|
|
<a href="#net_socket_resume"><code>socket.resume()</code></a>.</p>
|
|
<p>The server can be a TCP server or an <a href="#net_ipc_support">IPC</a> server, depending on what it
|
|
<a href="#net_server_listen"><code>listen()</code></a> to.</p>
|
|
<p>Here is an example of an TCP echo server which listens for connections
|
|
on port 8124:</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> net = <span class="hljs-built_in">require</span>(<span class="hljs-string">'net'</span>);
|
|
<span class="hljs-keyword">const</span> server = net.createServer(<span class="hljs-function">(<span class="hljs-params">c</span>) =></span> {
|
|
<span class="hljs-comment">// 'connection' listener.</span>
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'client connected'</span>);
|
|
c.on(<span class="hljs-string">'end'</span>, <span class="hljs-function">() =></span> {
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'client disconnected'</span>);
|
|
});
|
|
c.write(<span class="hljs-string">'hello\r\n'</span>);
|
|
c.pipe(c);
|
|
});
|
|
server.on(<span class="hljs-string">'error'</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
|
|
<span class="hljs-keyword">throw</span> err;
|
|
});
|
|
server.listen(<span class="hljs-number">8124</span>, <span class="hljs-function">() =></span> {
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'server bound'</span>);
|
|
});</code></pre>
|
|
<p>Test this by using <code>telnet</code>:</p>
|
|
<pre><code class="language-console"><span class="hljs-meta">$</span><span class="bash"> telnet localhost 8124</span></code></pre>
|
|
<p>To listen on the socket <code>/tmp/echo.sock</code>:</p>
|
|
<pre><code class="language-js">server.listen(<span class="hljs-string">'/tmp/echo.sock'</span>, <span class="hljs-function">() =></span> {
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'server bound'</span>);
|
|
});</code></pre>
|
|
<p>Use <code>nc</code> to connect to a Unix domain socket server:</p>
|
|
<pre><code class="language-console"><span class="hljs-meta">$</span><span class="bash"> nc -U /tmp/echo.sock</span></code></pre>
|
|
<h2><code>net.isIP(input)</code><span><a class="mark" href="#net_net_isip_input" id="net_net_isip_input">#</a></span></h2>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.3.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>input</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
|
</ul>
|
|
<p>Tests if input is an IP address. Returns <code>0</code> for invalid strings,
|
|
returns <code>4</code> for IP version 4 addresses, and returns <code>6</code> for IP version 6
|
|
addresses.</p>
|
|
<h2><code>net.isIPv4(input)</code><span><a class="mark" href="#net_net_isipv4_input" id="net_net_isipv4_input">#</a></span></h2>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.3.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>input</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li>
|
|
</ul>
|
|
<p>Returns <code>true</code> if input is a version 4 IP address, otherwise returns <code>false</code>.</p>
|
|
<h2><code>net.isIPv6(input)</code><span><a class="mark" href="#net_net_isipv6_input" id="net_net_isipv6_input">#</a></span></h2>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.3.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>input</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li>
|
|
</ul>
|
|
<p>Returns <code>true</code> if input is a version 6 IP address, otherwise returns <code>false</code>.</p>
|
|
<!-- API END -->
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html>
|