859 lines
61 KiB
HTML
859 lines
61 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.12">
|
||
<title>UDP/datagram sockets | Node.js v12.22.12 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/dgram.html">
|
||
</head>
|
||
<body class="alt apidoc" id="api-section-dgram">
|
||
<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">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 active">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="dgram" class="interior">
|
||
<header>
|
||
<h1>Node.js v12.22.12 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="dgram.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/dgram.html">17.x</a></li>
|
||
<li><a href="https://nodejs.org/docs/latest-v16.x/api/dgram.html">16.x <b>LTS</b></a></li>
|
||
<li><a href="https://nodejs.org/docs/latest-v15.x/api/dgram.html">15.x</a></li>
|
||
<li><a href="https://nodejs.org/docs/latest-v14.x/api/dgram.html">14.x <b>LTS</b></a></li>
|
||
<li><a href="https://nodejs.org/docs/latest-v13.x/api/dgram.html">13.x</a></li>
|
||
<li><a href="https://nodejs.org/docs/latest-v12.x/api/dgram.html">12.x <b>LTS</b></a></li>
|
||
<li><a href="https://nodejs.org/docs/latest-v11.x/api/dgram.html">11.x</a></li>
|
||
<li><a href="https://nodejs.org/docs/latest-v10.x/api/dgram.html">10.x</a></li>
|
||
<li><a href="https://nodejs.org/docs/latest-v9.x/api/dgram.html">9.x</a></li>
|
||
<li><a href="https://nodejs.org/docs/latest-v8.x/api/dgram.html">8.x</a></li>
|
||
<li><a href="https://nodejs.org/docs/latest-v7.x/api/dgram.html">7.x</a></li>
|
||
<li><a href="https://nodejs.org/docs/latest-v6.x/api/dgram.html">6.x</a></li>
|
||
<li><a href="https://nodejs.org/docs/latest-v5.x/api/dgram.html">5.x</a></li>
|
||
<li><a href="https://nodejs.org/docs/latest-v4.x/api/dgram.html">4.x</a></li>
|
||
<li><a href="https://nodejs.org/docs/latest-v0.12.x/api/dgram.html">0.12.x</a></li>
|
||
<li><a href="https://nodejs.org/docs/latest-v0.10.x/api/dgram.html">0.10.x</a></li></ol>
|
||
</li>
|
||
|
||
<li class="edit_on_github"><a href="https://github.com/nodejs/node/edit/master/doc/api/dgram.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="#dgram_udp_datagram_sockets">UDP/datagram sockets</a></span>
|
||
<ul>
|
||
<li><a href="#dgram_class_dgram_socket">Class: <code>dgram.Socket</code></a>
|
||
<ul>
|
||
<li><a href="#dgram_event_close">Event: <code>'close'</code></a></li>
|
||
<li><a href="#dgram_event_connect">Event: <code>'connect'</code></a></li>
|
||
<li><a href="#dgram_event_error">Event: <code>'error'</code></a></li>
|
||
<li><a href="#dgram_event_listening">Event: <code>'listening'</code></a></li>
|
||
<li><a href="#dgram_event_message">Event: <code>'message'</code></a></li>
|
||
<li><a href="#dgram_socket_addmembership_multicastaddress_multicastinterface"><code>socket.addMembership(multicastAddress[, multicastInterface])</code></a></li>
|
||
<li><a href="#dgram_socket_addsourcespecificmembership_sourceaddress_groupaddress_multicastinterface"><code>socket.addSourceSpecificMembership(sourceAddress, groupAddress[, multicastInterface])</code></a></li>
|
||
<li><a href="#dgram_socket_address"><code>socket.address()</code></a></li>
|
||
<li><a href="#dgram_socket_bind_port_address_callback"><code>socket.bind([port][, address][, callback])</code></a></li>
|
||
<li><a href="#dgram_socket_bind_options_callback"><code>socket.bind(options[, callback])</code></a></li>
|
||
<li><a href="#dgram_socket_close_callback"><code>socket.close([callback])</code></a></li>
|
||
<li><a href="#dgram_socket_connect_port_address_callback"><code>socket.connect(port[, address][, callback])</code></a></li>
|
||
<li><a href="#dgram_socket_disconnect"><code>socket.disconnect()</code></a></li>
|
||
<li><a href="#dgram_socket_dropmembership_multicastaddress_multicastinterface"><code>socket.dropMembership(multicastAddress[, multicastInterface])</code></a></li>
|
||
<li><a href="#dgram_socket_dropsourcespecificmembership_sourceaddress_groupaddress_multicastinterface"><code>socket.dropSourceSpecificMembership(sourceAddress, groupAddress[, multicastInterface])</code></a></li>
|
||
<li><a href="#dgram_socket_getrecvbuffersize"><code>socket.getRecvBufferSize()</code></a></li>
|
||
<li><a href="#dgram_socket_getsendbuffersize"><code>socket.getSendBufferSize()</code></a></li>
|
||
<li><a href="#dgram_socket_ref"><code>socket.ref()</code></a></li>
|
||
<li><a href="#dgram_socket_remoteaddress"><code>socket.remoteAddress()</code></a></li>
|
||
<li><a href="#dgram_socket_send_msg_offset_length_port_address_callback"><code>socket.send(msg[, offset, length][, port][, address][, callback])</code></a>
|
||
<ul>
|
||
<li><a href="#dgram_note_about_udp_datagram_size">Note about UDP datagram size</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#dgram_socket_setbroadcast_flag"><code>socket.setBroadcast(flag)</code></a></li>
|
||
<li><a href="#dgram_socket_setmulticastinterface_multicastinterface"><code>socket.setMulticastInterface(multicastInterface)</code></a>
|
||
<ul>
|
||
<li><a href="#dgram_example_ipv6_outgoing_multicast_interface">Example: IPv6 outgoing multicast interface</a></li>
|
||
<li><a href="#dgram_example_ipv4_outgoing_multicast_interface">Example: IPv4 outgoing multicast interface</a></li>
|
||
<li><a href="#dgram_call_results">Call results</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#dgram_socket_setmulticastloopback_flag"><code>socket.setMulticastLoopback(flag)</code></a></li>
|
||
<li><a href="#dgram_socket_setmulticastttl_ttl"><code>socket.setMulticastTTL(ttl)</code></a></li>
|
||
<li><a href="#dgram_socket_setrecvbuffersize_size"><code>socket.setRecvBufferSize(size)</code></a></li>
|
||
<li><a href="#dgram_socket_setsendbuffersize_size"><code>socket.setSendBufferSize(size)</code></a></li>
|
||
<li><a href="#dgram_socket_setttl_ttl"><code>socket.setTTL(ttl)</code></a></li>
|
||
<li><a href="#dgram_socket_unref"><code>socket.unref()</code></a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#dgram_dgram_module_functions"><code>dgram</code> module functions</a>
|
||
<ul>
|
||
<li><a href="#dgram_dgram_createsocket_options_callback"><code>dgram.createSocket(options[, callback])</code></a></li>
|
||
<li><a href="#dgram_dgram_createsocket_type_callback"><code>dgram.createSocket(type[, callback])</code></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
|
||
<div id="apicontent">
|
||
<h1>UDP/datagram sockets<span><a class="mark" href="#dgram_udp_datagram_sockets" id="dgram_udp_datagram_sockets">#</a></span></h1>
|
||
|
||
<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.12/lib/dgram.js">lib/dgram.js</a></p>
|
||
<p>The <code>dgram</code> module provides an implementation of UDP datagram sockets.</p>
|
||
<pre><code class="language-js"><span class="hljs-keyword">const</span> dgram = <span class="hljs-built_in">require</span>(<span class="hljs-string">'dgram'</span>);
|
||
<span class="hljs-keyword">const</span> server = dgram.createSocket(<span class="hljs-string">'udp4'</span>);
|
||
|
||
server.on(<span class="hljs-string">'error'</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
|
||
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`server error:\n<span class="hljs-subst">${err.stack}</span>`</span>);
|
||
server.close();
|
||
});
|
||
|
||
server.on(<span class="hljs-string">'message'</span>, <span class="hljs-function">(<span class="hljs-params">msg, rinfo</span>) =></span> {
|
||
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`server got: <span class="hljs-subst">${msg}</span> from <span class="hljs-subst">${rinfo.address}</span>:<span class="hljs-subst">${rinfo.port}</span>`</span>);
|
||
});
|
||
|
||
server.on(<span class="hljs-string">'listening'</span>, <span class="hljs-function">() =></span> {
|
||
<span class="hljs-keyword">const</span> address = server.address();
|
||
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`server listening <span class="hljs-subst">${address.address}</span>:<span class="hljs-subst">${address.port}</span>`</span>);
|
||
});
|
||
|
||
server.bind(<span class="hljs-number">41234</span>);
|
||
<span class="hljs-comment">// Prints: server listening 0.0.0.0:41234</span></code></pre>
|
||
<h2>Class: <code>dgram.Socket</code><span><a class="mark" href="#dgram_class_dgram_socket" id="dgram_class_dgram_socket">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.1.99</span>
|
||
</div>
|
||
<ul>
|
||
<li>Extends: <a href="events.html#events_class_eventemitter" class="type"><EventEmitter></a></li>
|
||
</ul>
|
||
<p>Encapsulates the datagram functionality.</p>
|
||
<p>New instances of <code>dgram.Socket</code> are created using <a href="#dgram_dgram_createsocket_options_callback"><code>dgram.createSocket()</code></a>.
|
||
The <code>new</code> keyword is not to be used to create <code>dgram.Socket</code> instances.</p>
|
||
<h3>Event: <code>'close'</code><span><a class="mark" href="#dgram_event_close" id="dgram_event_close">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.1.99</span>
|
||
</div>
|
||
<p>The <code>'close'</code> event is emitted after a socket is closed with <a href="#dgram_socket_close_callback"><code>close()</code></a>.
|
||
Once triggered, no new <code>'message'</code> events will be emitted on this socket.</p>
|
||
<h3>Event: <code>'connect'</code><span><a class="mark" href="#dgram_event_connect" id="dgram_event_connect">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v12.0.0</span>
|
||
</div>
|
||
<p>The <code>'connect'</code> event is emitted after a socket is associated to a remote
|
||
address as a result of a successful <a href="#dgram_socket_connect_port_address_callback"><code>connect()</code></a> call.</p>
|
||
<h3>Event: <code>'error'</code><span><a class="mark" href="#dgram_event_error" id="dgram_event_error">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.1.99</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>exception</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
</ul>
|
||
<p>The <code>'error'</code> event is emitted whenever any error occurs. The event handler
|
||
function is passed a single <code>Error</code> object.</p>
|
||
<h3>Event: <code>'listening'</code><span><a class="mark" href="#dgram_event_listening" id="dgram_event_listening">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.1.99</span>
|
||
</div>
|
||
<p>The <code>'listening'</code> event is emitted once the <code>dgram.Socket</code> is addressable and
|
||
can receive data. This happens either explicitly with <code>socket.bind()</code> or
|
||
implicitly the first time data is sent using <code>socket.send()</code>.
|
||
Until the <code>dgram.Socket</code> is listening, the underlying system resources do not
|
||
exist and calls such as <code>socket.address()</code> and <code>socket.setTTL()</code> will fail.</p>
|
||
<h3>Event: <code>'message'</code><span><a class="mark" href="#dgram_event_message" id="dgram_event_message">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.1.99</span>
|
||
</div>
|
||
<p>The <code>'message'</code> event is emitted when a new datagram is available on a socket.
|
||
The event handler function is passed two arguments: <code>msg</code> and <code>rinfo</code>.</p>
|
||
<ul>
|
||
<li><code>msg</code> <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> The message.</li>
|
||
<li><code>rinfo</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> Remote address information.
|
||
<ul>
|
||
<li><code>address</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The sender 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> The address family (<code>'IPv4'</code> or <code>'IPv6'</code>).</li>
|
||
<li><code>port</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The sender port.</li>
|
||
<li><code>size</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The message size.</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>If the source address of the incoming packet is an IPv6 link-local
|
||
address, the interface name is added to the <code>address</code>. For
|
||
example, a packet received on the <code>en0</code> interface might have the
|
||
address field set to <code>'fe80::2618:1234:ab11:3b9c%en0'</code>, where <code>'%en0'</code>
|
||
is the interface name as a zone ID suffix.</p>
|
||
<h3><code>socket.addMembership(multicastAddress[, multicastInterface])</code><span><a class="mark" href="#dgram_socket_addmembership_multicastaddress_multicastinterface" id="dgram_socket_addmembership_multicastaddress_multicastinterface">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.6.9</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>multicastAddress</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
||
<li><code>multicastInterface</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
||
</ul>
|
||
<p>Tells the kernel to join a multicast group at the given <code>multicastAddress</code> and
|
||
<code>multicastInterface</code> using the <code>IP_ADD_MEMBERSHIP</code> socket option. If the
|
||
<code>multicastInterface</code> argument is not specified, the operating system will choose
|
||
one interface and will add membership to it. To add membership to every
|
||
available interface, call <code>addMembership</code> multiple times, once per interface.</p>
|
||
<p>When called on an unbound socket, this method will implicitly bind to a random
|
||
port, listening on all interfaces.</p>
|
||
<p>When sharing a UDP socket across multiple <code>cluster</code> workers, the
|
||
<code>socket.addMembership()</code> function must be called only once or an
|
||
<code>EADDRINUSE</code> error will occur:</p>
|
||
<pre><code class="language-js"><span class="hljs-keyword">const</span> cluster = <span class="hljs-built_in">require</span>(<span class="hljs-string">'cluster'</span>);
|
||
<span class="hljs-keyword">const</span> dgram = <span class="hljs-built_in">require</span>(<span class="hljs-string">'dgram'</span>);
|
||
<span class="hljs-keyword">if</span> (cluster.isMaster) {
|
||
cluster.fork(); <span class="hljs-comment">// Works ok.</span>
|
||
cluster.fork(); <span class="hljs-comment">// Fails with EADDRINUSE.</span>
|
||
} <span class="hljs-keyword">else</span> {
|
||
<span class="hljs-keyword">const</span> s = dgram.createSocket(<span class="hljs-string">'udp4'</span>);
|
||
s.bind(<span class="hljs-number">1234</span>, <span class="hljs-function">() =></span> {
|
||
s.addMembership(<span class="hljs-string">'224.0.0.114'</span>);
|
||
});
|
||
}</code></pre>
|
||
<h3><code>socket.addSourceSpecificMembership(sourceAddress, groupAddress[, multicastInterface])</code><span><a class="mark" href="#dgram_socket_addsourcespecificmembership_sourceaddress_groupaddress_multicastinterface" id="dgram_socket_addsourcespecificmembership_sourceaddress_groupaddress_multicastinterface">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v12.16.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>sourceAddress</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
||
<li><code>groupAddress</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
||
<li><code>multicastInterface</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
||
</ul>
|
||
<p>Tells the kernel to join a source-specific multicast channel at the given
|
||
<code>sourceAddress</code> and <code>groupAddress</code>, using the <code>multicastInterface</code> with the
|
||
<code>IP_ADD_SOURCE_MEMBERSHIP</code> socket option. If the <code>multicastInterface</code> argument
|
||
is not specified, the operating system will choose one interface and will add
|
||
membership to it. To add membership to every available interface, call
|
||
<code>socket.addSourceSpecificMembership()</code> multiple times, once per interface.</p>
|
||
<p>When called on an unbound socket, this method will implicitly bind to a random
|
||
port, listening on all interfaces.</p>
|
||
<h3><code>socket.address()</code><span><a class="mark" href="#dgram_socket_address" id="dgram_socket_address">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.1.99</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 an object containing the address information for a socket.
|
||
For UDP sockets, this object will contain <code>address</code>, <code>family</code> and <code>port</code>
|
||
properties.</p>
|
||
<p>This method throws <code>EBADF</code> if called on an unbound socket.</p>
|
||
<h3><code>socket.bind([port][, address][, callback])</code><span><a class="mark" href="#dgram_socket_bind_port_address_callback" id="dgram_socket_bind_port_address_callback">#</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>v0.10</td>
|
||
<td><p>The method was changed to an asynchronous execution model. Legacy code would need to be changed to pass a callback function to the method call.</p></td></tr>
|
||
<tr><td>v0.1.99</td>
|
||
<td><p><span>Added in: v0.1.99</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>port</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></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></li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> with no parameters. Called when binding is complete.</li>
|
||
</ul>
|
||
<p>For UDP sockets, causes the <code>dgram.Socket</code> to listen for datagram
|
||
messages on a named <code>port</code> and optional <code>address</code>. If <code>port</code> is not
|
||
specified or is <code>0</code>, the operating system will attempt to bind to a
|
||
random port. If <code>address</code> is not specified, the operating system will
|
||
attempt to listen on all addresses. Once binding is complete, a
|
||
<code>'listening'</code> event is emitted and the optional <code>callback</code> function is
|
||
called.</p>
|
||
<p>Specifying both a <code>'listening'</code> event listener and passing a
|
||
<code>callback</code> to the <code>socket.bind()</code> method is not harmful but not very
|
||
useful.</p>
|
||
<p>A bound datagram socket keeps the Node.js process running to receive
|
||
datagram messages.</p>
|
||
<p>If binding fails, an <code>'error'</code> event is generated. In rare case (e.g.
|
||
attempting to bind with a closed socket), an <a href="errors.html#errors_class_error"><code>Error</code></a> may be thrown.</p>
|
||
<p>Example of a UDP server listening on port 41234:</p>
|
||
<pre><code class="language-js"><span class="hljs-keyword">const</span> dgram = <span class="hljs-built_in">require</span>(<span class="hljs-string">'dgram'</span>);
|
||
<span class="hljs-keyword">const</span> server = dgram.createSocket(<span class="hljs-string">'udp4'</span>);
|
||
|
||
server.on(<span class="hljs-string">'error'</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
|
||
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`server error:\n<span class="hljs-subst">${err.stack}</span>`</span>);
|
||
server.close();
|
||
});
|
||
|
||
server.on(<span class="hljs-string">'message'</span>, <span class="hljs-function">(<span class="hljs-params">msg, rinfo</span>) =></span> {
|
||
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`server got: <span class="hljs-subst">${msg}</span> from <span class="hljs-subst">${rinfo.address}</span>:<span class="hljs-subst">${rinfo.port}</span>`</span>);
|
||
});
|
||
|
||
server.on(<span class="hljs-string">'listening'</span>, <span class="hljs-function">() =></span> {
|
||
<span class="hljs-keyword">const</span> address = server.address();
|
||
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`server listening <span class="hljs-subst">${address.address}</span>:<span class="hljs-subst">${address.port}</span>`</span>);
|
||
});
|
||
|
||
server.bind(<span class="hljs-number">41234</span>);
|
||
<span class="hljs-comment">// Prints: server listening 0.0.0.0:41234</span></code></pre>
|
||
<h3><code>socket.bind(options[, callback])</code><span><a class="mark" href="#dgram_socket_bind_options_callback" id="dgram_socket_bind_options_callback">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.11.14</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. 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"><integer></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></li>
|
||
<li><code>exclusive</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li>
|
||
<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></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></li>
|
||
</ul>
|
||
<p>For UDP sockets, causes the <code>dgram.Socket</code> to listen for datagram
|
||
messages on a named <code>port</code> and optional <code>address</code> that are passed as
|
||
properties of an <code>options</code> object passed as the first argument. If
|
||
<code>port</code> is not specified or is <code>0</code>, the operating system will attempt
|
||
to bind to a random port. If <code>address</code> is not specified, the operating
|
||
system will attempt to listen on all addresses. Once binding is
|
||
complete, a <code>'listening'</code> event is emitted and the optional <code>callback</code>
|
||
function is called.</p>
|
||
<p>The <code>options</code> object may contain a <code>fd</code> property. When a <code>fd</code> greater
|
||
than <code>0</code> is set, it will wrap around an existing socket with the given
|
||
file descriptor. In this case, the properties of <code>port</code> and <code>address</code>
|
||
will be ignored.</p>
|
||
<p>Specifying both a <code>'listening'</code> event listener and passing a
|
||
<code>callback</code> to the <code>socket.bind()</code> method is not harmful but not very
|
||
useful.</p>
|
||
<p>The <code>options</code> object may contain an additional <code>exclusive</code> property that is
|
||
used when using <code>dgram.Socket</code> objects with the <a href="cluster.html"><code>cluster</code></a> module. When
|
||
<code>exclusive</code> is set to <code>false</code> (the default), cluster workers will use the same
|
||
underlying socket handle allowing connection handling duties to be shared.
|
||
When <code>exclusive</code> is <code>true</code>, however, the handle is not shared and attempted
|
||
port sharing results in an error.</p>
|
||
<p>A bound datagram socket keeps the Node.js process running to receive
|
||
datagram messages.</p>
|
||
<p>If binding fails, an <code>'error'</code> event is generated. In rare case (e.g.
|
||
attempting to bind with a closed socket), an <a href="errors.html#errors_class_error"><code>Error</code></a> may be thrown.</p>
|
||
<p>An example socket listening on an exclusive port is shown below.</p>
|
||
<pre><code class="language-js">socket.bind({
|
||
<span class="hljs-attr">address</span>: <span class="hljs-string">'localhost'</span>,
|
||
<span class="hljs-attr">port</span>: <span class="hljs-number">8000</span>,
|
||
<span class="hljs-attr">exclusive</span>: <span class="hljs-literal">true</span>
|
||
});</code></pre>
|
||
<h3><code>socket.close([callback])</code><span><a class="mark" href="#dgram_socket_close_callback" id="dgram_socket_close_callback">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.1.99</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 socket has been closed.</li>
|
||
</ul>
|
||
<p>Close the underlying socket and stop listening for data on it. If a callback is
|
||
provided, it is added as a listener for the <a href="#dgram_event_close"><code>'close'</code></a> event.</p>
|
||
<h3><code>socket.connect(port[, address][, callback])</code><span><a class="mark" href="#dgram_socket_connect_port_address_callback" id="dgram_socket_connect_port_address_callback">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v12.0.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>port</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></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></li>
|
||
<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 connection is completed or on error.</li>
|
||
</ul>
|
||
<p>Associates the <code>dgram.Socket</code> to a remote address and port. Every
|
||
message sent by this handle is automatically sent to that destination. Also,
|
||
the socket will only receive messages from that remote peer.
|
||
Trying to call <code>connect()</code> on an already connected socket will result
|
||
in an <a href="errors.html#errors_err_socket_dgram_is_connected"><code>ERR_SOCKET_DGRAM_IS_CONNECTED</code></a> exception. If <code>address</code> is not
|
||
provided, <code>'127.0.0.1'</code> (for <code>udp4</code> sockets) or <code>'::1'</code> (for <code>udp6</code> sockets)
|
||
will be used by default. Once the connection is complete, a <code>'connect'</code> event
|
||
is emitted and the optional <code>callback</code> function is called. In case of failure,
|
||
the <code>callback</code> is called or, failing this, an <code>'error'</code> event is emitted.</p>
|
||
<h3><code>socket.disconnect()</code><span><a class="mark" href="#dgram_socket_disconnect" id="dgram_socket_disconnect">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v12.0.0</span>
|
||
</div>
|
||
<p>A synchronous function that disassociates a connected <code>dgram.Socket</code> from
|
||
its remote address. Trying to call <code>disconnect()</code> on an unbound or already
|
||
disconnected socket will result in an <a href="errors.html#errors_err_socket_dgram_not_connected"><code>ERR_SOCKET_DGRAM_NOT_CONNECTED</code></a>
|
||
exception.</p>
|
||
<h3><code>socket.dropMembership(multicastAddress[, multicastInterface])</code><span><a class="mark" href="#dgram_socket_dropmembership_multicastaddress_multicastinterface" id="dgram_socket_dropmembership_multicastaddress_multicastinterface">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.6.9</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>multicastAddress</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
||
<li><code>multicastInterface</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
||
</ul>
|
||
<p>Instructs the kernel to leave a multicast group at <code>multicastAddress</code> using the
|
||
<code>IP_DROP_MEMBERSHIP</code> socket option. This method is automatically called by the
|
||
kernel when the socket is closed or the process terminates, so most apps will
|
||
never have reason to call this.</p>
|
||
<p>If <code>multicastInterface</code> is not specified, the operating system will attempt to
|
||
drop membership on all valid interfaces.</p>
|
||
<h3><code>socket.dropSourceSpecificMembership(sourceAddress, groupAddress[, multicastInterface])</code><span><a class="mark" href="#dgram_socket_dropsourcespecificmembership_sourceaddress_groupaddress_multicastinterface" id="dgram_socket_dropsourcespecificmembership_sourceaddress_groupaddress_multicastinterface">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v12.16.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>sourceAddress</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
||
<li><code>groupAddress</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
||
<li><code>multicastInterface</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
||
</ul>
|
||
<p>Instructs the kernel to leave a source-specific multicast channel at the given
|
||
<code>sourceAddress</code> and <code>groupAddress</code> using the <code>IP_DROP_SOURCE_MEMBERSHIP</code>
|
||
socket option. This method is automatically called by the kernel when the
|
||
socket is closed or the process terminates, so most apps will never have
|
||
reason to call this.</p>
|
||
<p>If <code>multicastInterface</code> is not specified, the operating system will attempt to
|
||
drop membership on all valid interfaces.</p>
|
||
<h3><code>socket.getRecvBufferSize()</code><span><a class="mark" href="#dgram_socket_getrecvbuffersize" id="dgram_socket_getrecvbuffersize">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v8.7.0</span>
|
||
</div>
|
||
<ul>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> the <code>SO_RCVBUF</code> socket receive buffer size in bytes.</li>
|
||
</ul>
|
||
<p>This method throws <a href="errors.html#errors_err_socket_buffer_size"><code>ERR_SOCKET_BUFFER_SIZE</code></a> if called on an unbound socket.</p>
|
||
<h3><code>socket.getSendBufferSize()</code><span><a class="mark" href="#dgram_socket_getsendbuffersize" id="dgram_socket_getsendbuffersize">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v8.7.0</span>
|
||
</div>
|
||
<ul>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> the <code>SO_SNDBUF</code> socket send buffer size in bytes.</li>
|
||
</ul>
|
||
<p>This method throws <a href="errors.html#errors_err_socket_buffer_size"><code>ERR_SOCKET_BUFFER_SIZE</code></a> if called on an unbound socket.</p>
|
||
<h3><code>socket.ref()</code><span><a class="mark" href="#dgram_socket_ref" id="dgram_socket_ref">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.9.1</span>
|
||
</div>
|
||
<ul>
|
||
<li>Returns: <a href="dgram.html#dgram_class_dgram_socket" class="type"><dgram.Socket></a></li>
|
||
</ul>
|
||
<p>By default, binding a socket will cause it to block the Node.js process from
|
||
exiting as long as the socket is open. The <code>socket.unref()</code> method can be used
|
||
to exclude the socket from the reference counting that keeps the Node.js
|
||
process active. The <code>socket.ref()</code> method adds the socket back to the reference
|
||
counting and restores the default behavior.</p>
|
||
<p>Calling <code>socket.ref()</code> multiples times will have no additional effect.</p>
|
||
<p>The <code>socket.ref()</code> method returns a reference to the socket so calls can be
|
||
chained.</p>
|
||
<h3><code>socket.remoteAddress()</code><span><a class="mark" href="#dgram_socket_remoteaddress" id="dgram_socket_remoteaddress">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v12.0.0</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 an object containing the <code>address</code>, <code>family</code>, and <code>port</code> of the remote
|
||
endpoint. This method throws an <a href="errors.html#errors_err_socket_dgram_not_connected"><code>ERR_SOCKET_DGRAM_NOT_CONNECTED</code></a> exception
|
||
if the socket is not connected.</p>
|
||
<h3><code>socket.send(msg[, offset, length][, port][, address][, callback])</code><span><a class="mark" href="#dgram_socket_send_msg_offset_length_port_address_callback" id="dgram_socket_send_msg_offset_length_port_address_callback">#</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>v12.19.0</td>
|
||
<td><p>The <code>msg</code> parameter can now be any <code>TypedArray</code> or <code>DataView</code>.</p></td></tr>
|
||
<tr><td>v12.0.0</td>
|
||
<td><p>Added support for sending data on connected sockets.</p></td></tr>
|
||
<tr><td>v8.0.0</td>
|
||
<td><p>The <code>msg</code> parameter can be an <code>Uint8Array</code> now.</p></td></tr>
|
||
<tr><td>v8.0.0</td>
|
||
<td><p>The <code>address</code> parameter is always optional now.</p></td></tr>
|
||
<tr><td>v6.0.0</td>
|
||
<td><p>On success, <code>callback</code> will now be called with an <code>error</code> argument of <code>null</code> rather than <code>0</code>.</p></td></tr>
|
||
<tr><td>v5.7.0</td>
|
||
<td><p>The <code>msg</code> parameter can be an array now. Also, the <code>offset</code> and <code>length</code> parameters are optional now.</p></td></tr>
|
||
<tr><td>v0.1.99</td>
|
||
<td><p><span>Added in: v0.1.99</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>msg</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/TypedArray" class="type"><TypedArray></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView" class="type"><DataView></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/Reference/Global_Objects/Array" class="type"><Array></a> Message to be sent.</li>
|
||
<li><code>offset</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> Offset in the buffer where the message starts.</li>
|
||
<li><code>length</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> Number of bytes in the message.</li>
|
||
<li><code>port</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> Destination port.</li>
|
||
<li><code>address</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Destination host name or IP address.</li>
|
||
<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 message has been sent.</li>
|
||
</ul>
|
||
<p>Broadcasts a datagram on the socket.
|
||
For connectionless sockets, the destination <code>port</code> and <code>address</code> must be
|
||
specified. Connected sockets, on the other hand, will use their associated
|
||
remote endpoint, so the <code>port</code> and <code>address</code> arguments must not be set.</p>
|
||
<p>The <code>msg</code> argument contains the message to be sent.
|
||
Depending on its type, different behavior can apply. If <code>msg</code> is a <code>Buffer</code>,
|
||
any <code>TypedArray</code> or a <code>DataView</code>,
|
||
the <code>offset</code> and <code>length</code> specify the offset within the <code>Buffer</code> where the
|
||
message begins and the number of bytes in the message, respectively.
|
||
If <code>msg</code> is a <code>String</code>, then it is automatically converted to a <code>Buffer</code>
|
||
with <code>'utf8'</code> encoding. With messages that
|
||
contain multi-byte characters, <code>offset</code> and <code>length</code> will be calculated with
|
||
respect to <a href="buffer.html#buffer_static_method_buffer_bytelength_string_encoding">byte length</a> and not the character position.
|
||
If <code>msg</code> is an array, <code>offset</code> and <code>length</code> must not be specified.</p>
|
||
<p>The <code>address</code> argument is a string. If the value of <code>address</code> is a host name,
|
||
DNS will be used to resolve the address of the host. If <code>address</code> is not
|
||
provided or otherwise falsy, <code>'127.0.0.1'</code> (for <code>udp4</code> sockets) or <code>'::1'</code>
|
||
(for <code>udp6</code> sockets) will be used by default.</p>
|
||
<p>If the socket has not been previously bound with a call to <code>bind</code>, the socket
|
||
is assigned a random port number and is bound to the "all interfaces" address
|
||
(<code>'0.0.0.0'</code> for <code>udp4</code> sockets, <code>'::0'</code> for <code>udp6</code> sockets.)</p>
|
||
<p>An optional <code>callback</code> function may be specified to as a way of reporting
|
||
DNS errors or for determining when it is safe to reuse the <code>buf</code> object.
|
||
DNS lookups delay the time to send for at least one tick of the
|
||
Node.js event loop.</p>
|
||
<p>The only way to know for sure that the datagram has been sent is by using a
|
||
<code>callback</code>. If an error occurs and a <code>callback</code> is given, the error will be
|
||
passed as the first argument to the <code>callback</code>. If a <code>callback</code> is not given,
|
||
the error is emitted as an <code>'error'</code> event on the <code>socket</code> object.</p>
|
||
<p>Offset and length are optional but both <em>must</em> be set if either are used.
|
||
They are supported only when the first argument is a <code>Buffer</code>, a <code>TypedArray</code>,
|
||
or a <code>DataView</code>.</p>
|
||
<p>This method throws <a href="errors.html#errors_err_socket_bad_port"><code>ERR_SOCKET_BAD_PORT</code></a> if called on an unbound socket.</p>
|
||
<p>Example of sending a UDP packet to a port on <code>localhost</code>;</p>
|
||
<pre><code class="language-js"><span class="hljs-keyword">const</span> dgram = <span class="hljs-built_in">require</span>(<span class="hljs-string">'dgram'</span>);
|
||
<span class="hljs-keyword">const</span> message = Buffer.from(<span class="hljs-string">'Some bytes'</span>);
|
||
<span class="hljs-keyword">const</span> client = dgram.createSocket(<span class="hljs-string">'udp4'</span>);
|
||
client.send(message, <span class="hljs-number">41234</span>, <span class="hljs-string">'localhost'</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
|
||
client.close();
|
||
});</code></pre>
|
||
<p>Example of sending a UDP packet composed of multiple buffers to a port on
|
||
<code>127.0.0.1</code>;</p>
|
||
<pre><code class="language-js"><span class="hljs-keyword">const</span> dgram = <span class="hljs-built_in">require</span>(<span class="hljs-string">'dgram'</span>);
|
||
<span class="hljs-keyword">const</span> buf1 = Buffer.from(<span class="hljs-string">'Some '</span>);
|
||
<span class="hljs-keyword">const</span> buf2 = Buffer.from(<span class="hljs-string">'bytes'</span>);
|
||
<span class="hljs-keyword">const</span> client = dgram.createSocket(<span class="hljs-string">'udp4'</span>);
|
||
client.send([buf1, buf2], <span class="hljs-number">41234</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
|
||
client.close();
|
||
});</code></pre>
|
||
<p>Sending multiple buffers might be faster or slower depending on the
|
||
application and operating system. Run benchmarks to
|
||
determine the optimal strategy on a case-by-case basis. Generally speaking,
|
||
however, sending multiple buffers is faster.</p>
|
||
<p>Example of sending a UDP packet using a socket connected to a port on
|
||
<code>localhost</code>:</p>
|
||
<pre><code class="language-js"><span class="hljs-keyword">const</span> dgram = <span class="hljs-built_in">require</span>(<span class="hljs-string">'dgram'</span>);
|
||
<span class="hljs-keyword">const</span> message = Buffer.from(<span class="hljs-string">'Some bytes'</span>);
|
||
<span class="hljs-keyword">const</span> client = dgram.createSocket(<span class="hljs-string">'udp4'</span>);
|
||
client.connect(<span class="hljs-number">41234</span>, <span class="hljs-string">'localhost'</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
|
||
client.send(message, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
|
||
client.close();
|
||
});
|
||
});</code></pre>
|
||
<h4>Note about UDP datagram size<span><a class="mark" href="#dgram_note_about_udp_datagram_size" id="dgram_note_about_udp_datagram_size">#</a></span></h4>
|
||
<p>The maximum size of an IPv4/v6 datagram depends on the <code>MTU</code>
|
||
(Maximum Transmission Unit) and on the <code>Payload Length</code> field size.</p>
|
||
<ul>
|
||
<li>
|
||
<p>The <code>Payload Length</code> field is 16 bits wide, which means that a normal
|
||
payload cannot exceed 64K octets including the internet header and data
|
||
(65,507 bytes = 65,535 − 8 bytes UDP header − 20 bytes IP header);
|
||
this is generally true for loopback interfaces, but such long datagram
|
||
messages are impractical for most hosts and networks.</p>
|
||
</li>
|
||
<li>
|
||
<p>The <code>MTU</code> is the largest size a given link layer technology can support for
|
||
datagram messages. For any link, IPv4 mandates a minimum <code>MTU</code> of 68
|
||
octets, while the recommended <code>MTU</code> for IPv4 is 576 (typically recommended
|
||
as the <code>MTU</code> for dial-up type applications), whether they arrive whole or in
|
||
fragments.</p>
|
||
<p>For IPv6, the minimum <code>MTU</code> is 1280 octets. However, the mandatory minimum
|
||
fragment reassembly buffer size is 1500 octets. The value of 68 octets is
|
||
very small, since most current link layer technologies, like Ethernet, have a
|
||
minimum <code>MTU</code> of 1500.</p>
|
||
</li>
|
||
</ul>
|
||
<p>It is impossible to know in advance the MTU of each link through which
|
||
a packet might travel. Sending a datagram greater than the receiver <code>MTU</code> will
|
||
not work because the packet will get silently dropped without informing the
|
||
source that the data did not reach its intended recipient.</p>
|
||
<h3><code>socket.setBroadcast(flag)</code><span><a class="mark" href="#dgram_socket_setbroadcast_flag" id="dgram_socket_setbroadcast_flag">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.6.9</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>flag</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li>
|
||
</ul>
|
||
<p>Sets or clears the <code>SO_BROADCAST</code> socket option. When set to <code>true</code>, UDP
|
||
packets may be sent to a local interface's broadcast address.</p>
|
||
<p>This method throws <code>EBADF</code> if called on an unbound socket.</p>
|
||
<h3><code>socket.setMulticastInterface(multicastInterface)</code><span><a class="mark" href="#dgram_socket_setmulticastinterface_multicastinterface" id="dgram_socket_setmulticastinterface_multicastinterface">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v8.6.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>multicastInterface</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
||
</ul>
|
||
<p><em>All references to scope in this section are referring to
|
||
<a href="https://en.wikipedia.org/wiki/IPv6_address#Scoped_literal_IPv6_addresses">IPv6 Zone Indices</a>, which are defined by <a href="https://tools.ietf.org/html/rfc4007">RFC 4007</a>. In string form, an IP
|
||
with a scope index is written as <code>'IP%scope'</code> where scope is an interface name
|
||
or interface number.</em></p>
|
||
<p>Sets the default outgoing multicast interface of the socket to a chosen
|
||
interface or back to system interface selection. The <code>multicastInterface</code> must
|
||
be a valid string representation of an IP from the socket's family.</p>
|
||
<p>For IPv4 sockets, this should be the IP configured for the desired physical
|
||
interface. All packets sent to multicast on the socket will be sent on the
|
||
interface determined by the most recent successful use of this call.</p>
|
||
<p>For IPv6 sockets, <code>multicastInterface</code> should include a scope to indicate the
|
||
interface as in the examples that follow. In IPv6, individual <code>send</code> calls can
|
||
also use explicit scope in addresses, so only packets sent to a multicast
|
||
address without specifying an explicit scope are affected by the most recent
|
||
successful use of this call.</p>
|
||
<p>This method throws <code>EBADF</code> if called on an unbound socket.</p>
|
||
<h4>Example: IPv6 outgoing multicast interface<span><a class="mark" href="#dgram_example_ipv6_outgoing_multicast_interface" id="dgram_example_ipv6_outgoing_multicast_interface">#</a></span></h4>
|
||
<p>On most systems, where scope format uses the interface name:</p>
|
||
<pre><code class="language-js"><span class="hljs-keyword">const</span> socket = dgram.createSocket(<span class="hljs-string">'udp6'</span>);
|
||
|
||
socket.bind(<span class="hljs-number">1234</span>, <span class="hljs-function">() =></span> {
|
||
socket.setMulticastInterface(<span class="hljs-string">'::%eth1'</span>);
|
||
});</code></pre>
|
||
<p>On Windows, where scope format uses an interface number:</p>
|
||
<pre><code class="language-js"><span class="hljs-keyword">const</span> socket = dgram.createSocket(<span class="hljs-string">'udp6'</span>);
|
||
|
||
socket.bind(<span class="hljs-number">1234</span>, <span class="hljs-function">() =></span> {
|
||
socket.setMulticastInterface(<span class="hljs-string">'::%2'</span>);
|
||
});</code></pre>
|
||
<h4>Example: IPv4 outgoing multicast interface<span><a class="mark" href="#dgram_example_ipv4_outgoing_multicast_interface" id="dgram_example_ipv4_outgoing_multicast_interface">#</a></span></h4>
|
||
<p>All systems use an IP of the host on the desired physical interface:</p>
|
||
<pre><code class="language-js"><span class="hljs-keyword">const</span> socket = dgram.createSocket(<span class="hljs-string">'udp4'</span>);
|
||
|
||
socket.bind(<span class="hljs-number">1234</span>, <span class="hljs-function">() =></span> {
|
||
socket.setMulticastInterface(<span class="hljs-string">'10.0.0.2'</span>);
|
||
});</code></pre>
|
||
<h4>Call results<span><a class="mark" href="#dgram_call_results" id="dgram_call_results">#</a></span></h4>
|
||
<p>A call on a socket that is not ready to send or no longer open may throw a <em>Not
|
||
running</em> <a href="errors.html#errors_class_error"><code>Error</code></a>.</p>
|
||
<p>If <code>multicastInterface</code> can not be parsed into an IP then an <em>EINVAL</em>
|
||
<a href="errors.html#errors_class_systemerror"><code>System Error</code></a> is thrown.</p>
|
||
<p>On IPv4, if <code>multicastInterface</code> is a valid address but does not match any
|
||
interface, or if the address does not match the family then
|
||
a <a href="errors.html#errors_class_systemerror"><code>System Error</code></a> such as <code>EADDRNOTAVAIL</code> or <code>EPROTONOSUP</code> is thrown.</p>
|
||
<p>On IPv6, most errors with specifying or omitting scope will result in the socket
|
||
continuing to use (or returning to) the system's default interface selection.</p>
|
||
<p>A socket's address family's ANY address (IPv4 <code>'0.0.0.0'</code> or IPv6 <code>'::'</code>) can be
|
||
used to return control of the sockets default outgoing interface to the system
|
||
for future multicast packets.</p>
|
||
<h3><code>socket.setMulticastLoopback(flag)</code><span><a class="mark" href="#dgram_socket_setmulticastloopback_flag" id="dgram_socket_setmulticastloopback_flag">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.3.8</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>flag</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li>
|
||
</ul>
|
||
<p>Sets or clears the <code>IP_MULTICAST_LOOP</code> socket option. When set to <code>true</code>,
|
||
multicast packets will also be received on the local interface.</p>
|
||
<p>This method throws <code>EBADF</code> if called on an unbound socket.</p>
|
||
<h3><code>socket.setMulticastTTL(ttl)</code><span><a class="mark" href="#dgram_socket_setmulticastttl_ttl" id="dgram_socket_setmulticastttl_ttl">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.3.8</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>ttl</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
</ul>
|
||
<p>Sets the <code>IP_MULTICAST_TTL</code> socket option. While TTL generally stands for
|
||
"Time to Live", in this context it specifies the number of IP hops that a
|
||
packet is allowed to travel through, specifically for multicast traffic. Each
|
||
router or gateway that forwards a packet decrements the TTL. If the TTL is
|
||
decremented to 0 by a router, it will not be forwarded.</p>
|
||
<p>The <code>ttl</code> argument may be between 0 and 255. The default on most systems is <code>1</code>.</p>
|
||
<p>This method throws <code>EBADF</code> if called on an unbound socket.</p>
|
||
<h3><code>socket.setRecvBufferSize(size)</code><span><a class="mark" href="#dgram_socket_setrecvbuffersize_size" id="dgram_socket_setrecvbuffersize_size">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v8.7.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>size</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
</ul>
|
||
<p>Sets the <code>SO_RCVBUF</code> socket option. Sets the maximum socket receive buffer
|
||
in bytes.</p>
|
||
<p>This method throws <a href="errors.html#errors_err_socket_buffer_size"><code>ERR_SOCKET_BUFFER_SIZE</code></a> if called on an unbound socket.</p>
|
||
<h3><code>socket.setSendBufferSize(size)</code><span><a class="mark" href="#dgram_socket_setsendbuffersize_size" id="dgram_socket_setsendbuffersize_size">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v8.7.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>size</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
</ul>
|
||
<p>Sets the <code>SO_SNDBUF</code> socket option. Sets the maximum socket send buffer
|
||
in bytes.</p>
|
||
<p>This method throws <a href="errors.html#errors_err_socket_buffer_size"><code>ERR_SOCKET_BUFFER_SIZE</code></a> if called on an unbound socket.</p>
|
||
<h3><code>socket.setTTL(ttl)</code><span><a class="mark" href="#dgram_socket_setttl_ttl" id="dgram_socket_setttl_ttl">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.1.101</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>ttl</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
</ul>
|
||
<p>Sets the <code>IP_TTL</code> socket option. While TTL generally stands for "Time to Live",
|
||
in this context it specifies the number of IP hops that a packet is allowed to
|
||
travel through. Each router or gateway that forwards a packet decrements the
|
||
TTL. If the TTL is decremented to 0 by a router, it will not be forwarded.
|
||
Changing TTL values is typically done for network probes or when multicasting.</p>
|
||
<p>The <code>ttl</code> argument may be between between 1 and 255. The default on most systems
|
||
is 64.</p>
|
||
<p>This method throws <code>EBADF</code> if called on an unbound socket.</p>
|
||
<h3><code>socket.unref()</code><span><a class="mark" href="#dgram_socket_unref" id="dgram_socket_unref">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.9.1</span>
|
||
</div>
|
||
<ul>
|
||
<li>Returns: <a href="dgram.html#dgram_class_dgram_socket" class="type"><dgram.Socket></a></li>
|
||
</ul>
|
||
<p>By default, binding a socket will cause it to block the Node.js process from
|
||
exiting as long as the socket is open. The <code>socket.unref()</code> method can be used
|
||
to exclude the socket from the reference counting that keeps the Node.js
|
||
process active, allowing the process to exit even if the socket is still
|
||
listening.</p>
|
||
<p>Calling <code>socket.unref()</code> multiple times will have no addition effect.</p>
|
||
<p>The <code>socket.unref()</code> method returns a reference to the socket so calls can be
|
||
chained.</p>
|
||
<h2><code>dgram</code> module functions<span><a class="mark" href="#dgram_dgram_module_functions" id="dgram_dgram_module_functions">#</a></span></h2>
|
||
<h3><code>dgram.createSocket(options[, callback])</code><span><a class="mark" href="#dgram_dgram_createsocket_options_callback" id="dgram_dgram_createsocket_options_callback">#</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>v11.4.0</td>
|
||
<td><p>The <code>ipv6Only</code> option is supported.</p></td></tr>
|
||
<tr><td>v8.7.0</td>
|
||
<td><p>The <code>recvBufferSize</code> and <code>sendBufferSize</code> options are supported now.</p></td></tr>
|
||
<tr><td>v8.6.0</td>
|
||
<td><p>The <code>lookup</code> option is supported.</p></td></tr>
|
||
<tr><td>v0.11.13</td>
|
||
<td><p><span>Added in: v0.11.13</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> Available options are:
|
||
<ul>
|
||
<li><code>type</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The family of socket. Must be either <code>'udp4'</code> or <code>'udp6'</code>.
|
||
Required.</li>
|
||
<li><code>reuseAddr</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> When <code>true</code> <a href="#dgram_socket_bind_port_address_callback"><code>socket.bind()</code></a> will reuse the
|
||
address, even if another process has already bound a socket on it.
|
||
<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> Setting <code>ipv6Only</code> to <code>true</code> will
|
||
disable dual-stack support, i.e., binding to address <code>::</code> won't make
|
||
<code>0.0.0.0</code> be bound. <strong>Default:</strong> <code>false</code>.</li>
|
||
<li><code>recvBufferSize</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Sets the <code>SO_RCVBUF</code> socket value.</li>
|
||
<li><code>sendBufferSize</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Sets the <code>SO_SNDBUF</code> socket value.</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>
|
||
</li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> Attached as a listener for <code>'message'</code> events. Optional.</li>
|
||
<li>Returns: <a href="dgram.html#dgram_class_dgram_socket" class="type"><dgram.Socket></a></li>
|
||
</ul>
|
||
<p>Creates a <code>dgram.Socket</code> object. Once the socket is created, calling
|
||
<a href="#dgram_socket_bind_port_address_callback"><code>socket.bind()</code></a> will instruct the socket to begin listening for datagram
|
||
messages. When <code>address</code> and <code>port</code> are not passed to <a href="#dgram_socket_bind_port_address_callback"><code>socket.bind()</code></a> the
|
||
method will bind the socket to the "all interfaces" address on a random port
|
||
(it does the right thing for both <code>udp4</code> and <code>udp6</code> sockets). The bound address
|
||
and port can be retrieved using <a href="#dgram_socket_address"><code>socket.address().address</code></a> and
|
||
<a href="#dgram_socket_address"><code>socket.address().port</code></a>.</p>
|
||
<h3><code>dgram.createSocket(type[, callback])</code><span><a class="mark" href="#dgram_dgram_createsocket_type_callback" id="dgram_dgram_createsocket_type_callback">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.1.99</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>type</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Either <code>'udp4'</code> or <code>'udp6'</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> Attached as a listener to <code>'message'</code> events.</li>
|
||
<li>Returns: <a href="dgram.html#dgram_class_dgram_socket" class="type"><dgram.Socket></a></li>
|
||
</ul>
|
||
<p>Creates a <code>dgram.Socket</code> object of the specified <code>type</code>.</p>
|
||
<p>Once the socket is created, calling <a href="#dgram_socket_bind_port_address_callback"><code>socket.bind()</code></a> will instruct the
|
||
socket to begin listening for datagram messages. When <code>address</code> and <code>port</code> are
|
||
not passed to <a href="#dgram_socket_bind_port_address_callback"><code>socket.bind()</code></a> the method will bind the socket to the "all
|
||
interfaces" address on a random port (it does the right thing for both <code>udp4</code>
|
||
and <code>udp6</code> sockets). The bound address and port can be retrieved using
|
||
<a href="#dgram_socket_address"><code>socket.address().address</code></a> and <a href="#dgram_socket_address"><code>socket.address().port</code></a>.</p>
|
||
<!-- API END -->
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</body>
|
||
</html>
|