11cb0ef41Sopenharmony_ci<!DOCTYPE html> 21cb0ef41Sopenharmony_ci<html lang="en"> 31cb0ef41Sopenharmony_ci<head> 41cb0ef41Sopenharmony_ci <meta charset="utf-8"> 51cb0ef41Sopenharmony_ci <meta name="viewport" content="width=device-width"> 61cb0ef41Sopenharmony_ci <meta name="nodejs.org:node-version" content="v18.20.1"> 71cb0ef41Sopenharmony_ci <title>UDP/datagram sockets | Node.js v18.20.1 Documentation</title> 81cb0ef41Sopenharmony_ci <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:400,700,400italic&display=fallback"> 91cb0ef41Sopenharmony_ci <link rel="stylesheet" href="assets/style.css"> 101cb0ef41Sopenharmony_ci <link rel="stylesheet" href="assets/hljs.css"> 111cb0ef41Sopenharmony_ci <link rel="canonical" href="https://nodejs.org/api/dgram.html"> 121cb0ef41Sopenharmony_ci <script async defer src="assets/api.js" type="text/javascript"></script> 131cb0ef41Sopenharmony_ci <style>@media(max-width:558px){.with-42-chars>.js-flavor-selector{float:none;margin:0 0 1em auto;}}@media(max-width:542px){.with-40-chars>.js-flavor-selector{float:none;margin:0 0 1em auto;}}</style> 141cb0ef41Sopenharmony_ci</head> 151cb0ef41Sopenharmony_ci<body class="alt apidoc" id="api-section-dgram"> 161cb0ef41Sopenharmony_ci <div id="content" class="clearfix"> 171cb0ef41Sopenharmony_ci <div id="column2" class="interior"> 181cb0ef41Sopenharmony_ci <div id="intro" class="interior"> 191cb0ef41Sopenharmony_ci <a href="/" title="Go back to the home page"> 201cb0ef41Sopenharmony_ci Node.js 211cb0ef41Sopenharmony_ci </a> 221cb0ef41Sopenharmony_ci </div> 231cb0ef41Sopenharmony_ci <ul> 241cb0ef41Sopenharmony_ci<li><a href="documentation.html" class="nav-documentation">About this documentation</a></li> 251cb0ef41Sopenharmony_ci<li><a href="synopsis.html" class="nav-synopsis">Usage and example</a></li> 261cb0ef41Sopenharmony_ci</ul> 271cb0ef41Sopenharmony_ci<hr class="line"> 281cb0ef41Sopenharmony_ci<ul> 291cb0ef41Sopenharmony_ci<li><a href="assert.html" class="nav-assert">Assertion testing</a></li> 301cb0ef41Sopenharmony_ci<li><a href="async_context.html" class="nav-async_context">Asynchronous context tracking</a></li> 311cb0ef41Sopenharmony_ci<li><a href="async_hooks.html" class="nav-async_hooks">Async hooks</a></li> 321cb0ef41Sopenharmony_ci<li><a href="buffer.html" class="nav-buffer">Buffer</a></li> 331cb0ef41Sopenharmony_ci<li><a href="addons.html" class="nav-addons">C++ addons</a></li> 341cb0ef41Sopenharmony_ci<li><a href="n-api.html" class="nav-n-api">C/C++ addons with Node-API</a></li> 351cb0ef41Sopenharmony_ci<li><a href="embedding.html" class="nav-embedding">C++ embedder API</a></li> 361cb0ef41Sopenharmony_ci<li><a href="child_process.html" class="nav-child_process">Child processes</a></li> 371cb0ef41Sopenharmony_ci<li><a href="cluster.html" class="nav-cluster">Cluster</a></li> 381cb0ef41Sopenharmony_ci<li><a href="cli.html" class="nav-cli">Command-line options</a></li> 391cb0ef41Sopenharmony_ci<li><a href="console.html" class="nav-console">Console</a></li> 401cb0ef41Sopenharmony_ci<li><a href="corepack.html" class="nav-corepack">Corepack</a></li> 411cb0ef41Sopenharmony_ci<li><a href="crypto.html" class="nav-crypto">Crypto</a></li> 421cb0ef41Sopenharmony_ci<li><a href="debugger.html" class="nav-debugger">Debugger</a></li> 431cb0ef41Sopenharmony_ci<li><a href="deprecations.html" class="nav-deprecations">Deprecated APIs</a></li> 441cb0ef41Sopenharmony_ci<li><a href="diagnostics_channel.html" class="nav-diagnostics_channel">Diagnostics Channel</a></li> 451cb0ef41Sopenharmony_ci<li><a href="dns.html" class="nav-dns">DNS</a></li> 461cb0ef41Sopenharmony_ci<li><a href="domain.html" class="nav-domain">Domain</a></li> 471cb0ef41Sopenharmony_ci<li><a href="errors.html" class="nav-errors">Errors</a></li> 481cb0ef41Sopenharmony_ci<li><a href="events.html" class="nav-events">Events</a></li> 491cb0ef41Sopenharmony_ci<li><a href="fs.html" class="nav-fs">File system</a></li> 501cb0ef41Sopenharmony_ci<li><a href="globals.html" class="nav-globals">Globals</a></li> 511cb0ef41Sopenharmony_ci<li><a href="http.html" class="nav-http">HTTP</a></li> 521cb0ef41Sopenharmony_ci<li><a href="http2.html" class="nav-http2">HTTP/2</a></li> 531cb0ef41Sopenharmony_ci<li><a href="https.html" class="nav-https">HTTPS</a></li> 541cb0ef41Sopenharmony_ci<li><a href="inspector.html" class="nav-inspector">Inspector</a></li> 551cb0ef41Sopenharmony_ci<li><a href="intl.html" class="nav-intl">Internationalization</a></li> 561cb0ef41Sopenharmony_ci<li><a href="modules.html" class="nav-modules">Modules: CommonJS modules</a></li> 571cb0ef41Sopenharmony_ci<li><a href="esm.html" class="nav-esm">Modules: ECMAScript modules</a></li> 581cb0ef41Sopenharmony_ci<li><a href="module.html" class="nav-module">Modules: <code>node:module</code> API</a></li> 591cb0ef41Sopenharmony_ci<li><a href="packages.html" class="nav-packages">Modules: Packages</a></li> 601cb0ef41Sopenharmony_ci<li><a href="net.html" class="nav-net">Net</a></li> 611cb0ef41Sopenharmony_ci<li><a href="os.html" class="nav-os">OS</a></li> 621cb0ef41Sopenharmony_ci<li><a href="path.html" class="nav-path">Path</a></li> 631cb0ef41Sopenharmony_ci<li><a href="perf_hooks.html" class="nav-perf_hooks">Performance hooks</a></li> 641cb0ef41Sopenharmony_ci<li><a href="permissions.html" class="nav-permissions">Permissions</a></li> 651cb0ef41Sopenharmony_ci<li><a href="process.html" class="nav-process">Process</a></li> 661cb0ef41Sopenharmony_ci<li><a href="punycode.html" class="nav-punycode">Punycode</a></li> 671cb0ef41Sopenharmony_ci<li><a href="querystring.html" class="nav-querystring">Query strings</a></li> 681cb0ef41Sopenharmony_ci<li><a href="readline.html" class="nav-readline">Readline</a></li> 691cb0ef41Sopenharmony_ci<li><a href="repl.html" class="nav-repl">REPL</a></li> 701cb0ef41Sopenharmony_ci<li><a href="report.html" class="nav-report">Report</a></li> 711cb0ef41Sopenharmony_ci<li><a href="single-executable-applications.html" class="nav-single-executable-applications">Single executable applications</a></li> 721cb0ef41Sopenharmony_ci<li><a href="stream.html" class="nav-stream">Stream</a></li> 731cb0ef41Sopenharmony_ci<li><a href="string_decoder.html" class="nav-string_decoder">String decoder</a></li> 741cb0ef41Sopenharmony_ci<li><a href="test.html" class="nav-test">Test runner</a></li> 751cb0ef41Sopenharmony_ci<li><a href="timers.html" class="nav-timers">Timers</a></li> 761cb0ef41Sopenharmony_ci<li><a href="tls.html" class="nav-tls">TLS/SSL</a></li> 771cb0ef41Sopenharmony_ci<li><a href="tracing.html" class="nav-tracing">Trace events</a></li> 781cb0ef41Sopenharmony_ci<li><a href="tty.html" class="nav-tty">TTY</a></li> 791cb0ef41Sopenharmony_ci<li><a href="dgram.html" class="nav-dgram active">UDP/datagram</a></li> 801cb0ef41Sopenharmony_ci<li><a href="url.html" class="nav-url">URL</a></li> 811cb0ef41Sopenharmony_ci<li><a href="util.html" class="nav-util">Utilities</a></li> 821cb0ef41Sopenharmony_ci<li><a href="v8.html" class="nav-v8">V8</a></li> 831cb0ef41Sopenharmony_ci<li><a href="vm.html" class="nav-vm">VM</a></li> 841cb0ef41Sopenharmony_ci<li><a href="wasi.html" class="nav-wasi">WASI</a></li> 851cb0ef41Sopenharmony_ci<li><a href="webcrypto.html" class="nav-webcrypto">Web Crypto API</a></li> 861cb0ef41Sopenharmony_ci<li><a href="webstreams.html" class="nav-webstreams">Web Streams API</a></li> 871cb0ef41Sopenharmony_ci<li><a href="worker_threads.html" class="nav-worker_threads">Worker threads</a></li> 881cb0ef41Sopenharmony_ci<li><a href="zlib.html" class="nav-zlib">Zlib</a></li> 891cb0ef41Sopenharmony_ci</ul> 901cb0ef41Sopenharmony_ci<hr class="line"> 911cb0ef41Sopenharmony_ci<ul> 921cb0ef41Sopenharmony_ci<li><a href="https://github.com/nodejs/node" class="nav-https-github-com-nodejs-node">Code repository and issue tracker</a></li> 931cb0ef41Sopenharmony_ci</ul> 941cb0ef41Sopenharmony_ci </div> 951cb0ef41Sopenharmony_ci 961cb0ef41Sopenharmony_ci <div id="column1" data-id="dgram" class="interior"> 971cb0ef41Sopenharmony_ci <header class="header"> 981cb0ef41Sopenharmony_ci <div class="header-container"> 991cb0ef41Sopenharmony_ci <h1>Node.js v18.20.1 documentation</h1> 1001cb0ef41Sopenharmony_ci <button class="theme-toggle-btn" id="theme-toggle-btn" title="Toggle dark mode/light mode" aria-label="Toggle dark mode/light mode" hidden> 1011cb0ef41Sopenharmony_ci <svg xmlns="http://www.w3.org/2000/svg" class="icon dark-icon" height="24" width="24"> 1021cb0ef41Sopenharmony_ci <path fill="none" d="M0 0h24v24H0z" /> 1031cb0ef41Sopenharmony_ci <path d="M11.1 12.08c-2.33-4.51-.5-8.48.53-10.07C6.27 2.2 1.98 6.59 1.98 12c0 .14.02.28.02.42.62-.27 1.29-.42 2-.42 1.66 0 3.18.83 4.1 2.15A4.01 4.01 0 0111 18c0 1.52-.87 2.83-2.12 3.51.98.32 2.03.5 3.11.5 3.5 0 6.58-1.8 8.37-4.52-2.36.23-6.98-.97-9.26-5.41z"/> 1041cb0ef41Sopenharmony_ci <path d="M7 16h-.18C6.4 14.84 5.3 14 4 14c-1.66 0-3 1.34-3 3s1.34 3 3 3h3c1.1 0 2-.9 2-2s-.9-2-2-2z"/> 1051cb0ef41Sopenharmony_ci </svg> 1061cb0ef41Sopenharmony_ci <svg xmlns="http://www.w3.org/2000/svg" class="icon light-icon" height="24" width="24"> 1071cb0ef41Sopenharmony_ci <path d="M0 0h24v24H0z" fill="none" /> 1081cb0ef41Sopenharmony_ci <path d="M6.76 4.84l-1.8-1.79-1.41 1.41 1.79 1.79 1.42-1.41zM4 10.5H1v2h3v-2zm9-9.95h-2V3.5h2V.55zm7.45 3.91l-1.41-1.41-1.79 1.79 1.41 1.41 1.79-1.79zm-3.21 13.7l1.79 1.8 1.41-1.41-1.8-1.79-1.4 1.4zM20 10.5v2h3v-2h-3zm-8-5c-3.31 0-6 2.69-6 6s2.69 6 6 6 6-2.69 6-6-2.69-6-6-6zm-1 16.95h2V19.5h-2v2.95zm-7.45-3.91l1.41 1.41 1.79-1.8-1.41-1.41-1.79 1.8z"/> 1091cb0ef41Sopenharmony_ci </svg> 1101cb0ef41Sopenharmony_ci </button> 1111cb0ef41Sopenharmony_ci </div> 1121cb0ef41Sopenharmony_ci <div id="gtoc"> 1131cb0ef41Sopenharmony_ci <ul> 1141cb0ef41Sopenharmony_ci <li class="pinned-header">Node.js v18.20.1</li> 1151cb0ef41Sopenharmony_ci 1161cb0ef41Sopenharmony_ci <li class="picker-header"> 1171cb0ef41Sopenharmony_ci <a href="#"> 1181cb0ef41Sopenharmony_ci <span class="collapsed-arrow">►</span><span class="expanded-arrow">▼</span> 1191cb0ef41Sopenharmony_ci Table of contents 1201cb0ef41Sopenharmony_ci </a> 1211cb0ef41Sopenharmony_ci 1221cb0ef41Sopenharmony_ci <div class="picker"><div class="toc"><ul> 1231cb0ef41Sopenharmony_ci<li><span class="stability_2"><a href="#udpdatagram-sockets">UDP/datagram sockets</a></span> 1241cb0ef41Sopenharmony_ci<ul> 1251cb0ef41Sopenharmony_ci<li><a href="#class-dgramsocket">Class: <code>dgram.Socket</code></a> 1261cb0ef41Sopenharmony_ci<ul> 1271cb0ef41Sopenharmony_ci<li><a href="#event-close">Event: <code>'close'</code></a></li> 1281cb0ef41Sopenharmony_ci<li><a href="#event-connect">Event: <code>'connect'</code></a></li> 1291cb0ef41Sopenharmony_ci<li><a href="#event-error">Event: <code>'error'</code></a></li> 1301cb0ef41Sopenharmony_ci<li><a href="#event-listening">Event: <code>'listening'</code></a></li> 1311cb0ef41Sopenharmony_ci<li><a href="#event-message">Event: <code>'message'</code></a></li> 1321cb0ef41Sopenharmony_ci<li><a href="#socketaddmembershipmulticastaddress-multicastinterface"><code>socket.addMembership(multicastAddress[, multicastInterface])</code></a></li> 1331cb0ef41Sopenharmony_ci<li><a href="#socketaddsourcespecificmembershipsourceaddress-groupaddress-multicastinterface"><code>socket.addSourceSpecificMembership(sourceAddress, groupAddress[, multicastInterface])</code></a></li> 1341cb0ef41Sopenharmony_ci<li><a href="#socketaddress"><code>socket.address()</code></a></li> 1351cb0ef41Sopenharmony_ci<li><a href="#socketbindport-address-callback"><code>socket.bind([port][, address][, callback])</code></a></li> 1361cb0ef41Sopenharmony_ci<li><a href="#socketbindoptions-callback"><code>socket.bind(options[, callback])</code></a></li> 1371cb0ef41Sopenharmony_ci<li><a href="#socketclosecallback"><code>socket.close([callback])</code></a></li> 1381cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#socketsymbolasyncdispose"><code>socket[Symbol.asyncDispose]()</code></a></span></li> 1391cb0ef41Sopenharmony_ci<li><a href="#socketconnectport-address-callback"><code>socket.connect(port[, address][, callback])</code></a></li> 1401cb0ef41Sopenharmony_ci<li><a href="#socketdisconnect"><code>socket.disconnect()</code></a></li> 1411cb0ef41Sopenharmony_ci<li><a href="#socketdropmembershipmulticastaddress-multicastinterface"><code>socket.dropMembership(multicastAddress[, multicastInterface])</code></a></li> 1421cb0ef41Sopenharmony_ci<li><a href="#socketdropsourcespecificmembershipsourceaddress-groupaddress-multicastinterface"><code>socket.dropSourceSpecificMembership(sourceAddress, groupAddress[, multicastInterface])</code></a></li> 1431cb0ef41Sopenharmony_ci<li><a href="#socketgetrecvbuffersize"><code>socket.getRecvBufferSize()</code></a></li> 1441cb0ef41Sopenharmony_ci<li><a href="#socketgetsendbuffersize"><code>socket.getSendBufferSize()</code></a></li> 1451cb0ef41Sopenharmony_ci<li><a href="#socketgetsendqueuesize"><code>socket.getSendQueueSize()</code></a></li> 1461cb0ef41Sopenharmony_ci<li><a href="#socketgetsendqueuecount"><code>socket.getSendQueueCount()</code></a></li> 1471cb0ef41Sopenharmony_ci<li><a href="#socketref"><code>socket.ref()</code></a></li> 1481cb0ef41Sopenharmony_ci<li><a href="#socketremoteaddress"><code>socket.remoteAddress()</code></a></li> 1491cb0ef41Sopenharmony_ci<li><a href="#socketsendmsg-offset-length-port-address-callback"><code>socket.send(msg[, offset, length][, port][, address][, callback])</code></a> 1501cb0ef41Sopenharmony_ci<ul> 1511cb0ef41Sopenharmony_ci<li><a href="#note-about-udp-datagram-size">Note about UDP datagram size</a></li> 1521cb0ef41Sopenharmony_ci</ul> 1531cb0ef41Sopenharmony_ci</li> 1541cb0ef41Sopenharmony_ci<li><a href="#socketsetbroadcastflag"><code>socket.setBroadcast(flag)</code></a></li> 1551cb0ef41Sopenharmony_ci<li><a href="#socketsetmulticastinterfacemulticastinterface"><code>socket.setMulticastInterface(multicastInterface)</code></a> 1561cb0ef41Sopenharmony_ci<ul> 1571cb0ef41Sopenharmony_ci<li><a href="#example-ipv6-outgoing-multicast-interface">Example: IPv6 outgoing multicast interface</a></li> 1581cb0ef41Sopenharmony_ci<li><a href="#example-ipv4-outgoing-multicast-interface">Example: IPv4 outgoing multicast interface</a></li> 1591cb0ef41Sopenharmony_ci<li><a href="#call-results">Call results</a></li> 1601cb0ef41Sopenharmony_ci</ul> 1611cb0ef41Sopenharmony_ci</li> 1621cb0ef41Sopenharmony_ci<li><a href="#socketsetmulticastloopbackflag"><code>socket.setMulticastLoopback(flag)</code></a></li> 1631cb0ef41Sopenharmony_ci<li><a href="#socketsetmulticastttlttl"><code>socket.setMulticastTTL(ttl)</code></a></li> 1641cb0ef41Sopenharmony_ci<li><a href="#socketsetrecvbuffersizesize"><code>socket.setRecvBufferSize(size)</code></a></li> 1651cb0ef41Sopenharmony_ci<li><a href="#socketsetsendbuffersizesize"><code>socket.setSendBufferSize(size)</code></a></li> 1661cb0ef41Sopenharmony_ci<li><a href="#socketsetttlttl"><code>socket.setTTL(ttl)</code></a></li> 1671cb0ef41Sopenharmony_ci<li><a href="#socketunref"><code>socket.unref()</code></a></li> 1681cb0ef41Sopenharmony_ci</ul> 1691cb0ef41Sopenharmony_ci</li> 1701cb0ef41Sopenharmony_ci<li><a href="#nodedgram-module-functions"><code>node:dgram</code> module functions</a> 1711cb0ef41Sopenharmony_ci<ul> 1721cb0ef41Sopenharmony_ci<li><a href="#dgramcreatesocketoptions-callback"><code>dgram.createSocket(options[, callback])</code></a></li> 1731cb0ef41Sopenharmony_ci<li><a href="#dgramcreatesockettype-callback"><code>dgram.createSocket(type[, callback])</code></a></li> 1741cb0ef41Sopenharmony_ci</ul> 1751cb0ef41Sopenharmony_ci</li> 1761cb0ef41Sopenharmony_ci</ul> 1771cb0ef41Sopenharmony_ci</li> 1781cb0ef41Sopenharmony_ci</ul></div></div> 1791cb0ef41Sopenharmony_ci </li> 1801cb0ef41Sopenharmony_ci 1811cb0ef41Sopenharmony_ci 1821cb0ef41Sopenharmony_ci <li class="picker-header"> 1831cb0ef41Sopenharmony_ci <a href="#"> 1841cb0ef41Sopenharmony_ci <span class="collapsed-arrow">►</span><span class="expanded-arrow">▼</span> 1851cb0ef41Sopenharmony_ci Index 1861cb0ef41Sopenharmony_ci </a> 1871cb0ef41Sopenharmony_ci 1881cb0ef41Sopenharmony_ci <div class="picker"><ul> 1891cb0ef41Sopenharmony_ci<li><a href="documentation.html" class="nav-documentation">About this documentation</a></li> 1901cb0ef41Sopenharmony_ci<li><a href="synopsis.html" class="nav-synopsis">Usage and example</a></li> 1911cb0ef41Sopenharmony_ci 1921cb0ef41Sopenharmony_ci <li> 1931cb0ef41Sopenharmony_ci <a href="index.html">Index</a> 1941cb0ef41Sopenharmony_ci </li> 1951cb0ef41Sopenharmony_ci </ul> 1961cb0ef41Sopenharmony_ci 1971cb0ef41Sopenharmony_ci<hr class="line"> 1981cb0ef41Sopenharmony_ci<ul> 1991cb0ef41Sopenharmony_ci<li><a href="assert.html" class="nav-assert">Assertion testing</a></li> 2001cb0ef41Sopenharmony_ci<li><a href="async_context.html" class="nav-async_context">Asynchronous context tracking</a></li> 2011cb0ef41Sopenharmony_ci<li><a href="async_hooks.html" class="nav-async_hooks">Async hooks</a></li> 2021cb0ef41Sopenharmony_ci<li><a href="buffer.html" class="nav-buffer">Buffer</a></li> 2031cb0ef41Sopenharmony_ci<li><a href="addons.html" class="nav-addons">C++ addons</a></li> 2041cb0ef41Sopenharmony_ci<li><a href="n-api.html" class="nav-n-api">C/C++ addons with Node-API</a></li> 2051cb0ef41Sopenharmony_ci<li><a href="embedding.html" class="nav-embedding">C++ embedder API</a></li> 2061cb0ef41Sopenharmony_ci<li><a href="child_process.html" class="nav-child_process">Child processes</a></li> 2071cb0ef41Sopenharmony_ci<li><a href="cluster.html" class="nav-cluster">Cluster</a></li> 2081cb0ef41Sopenharmony_ci<li><a href="cli.html" class="nav-cli">Command-line options</a></li> 2091cb0ef41Sopenharmony_ci<li><a href="console.html" class="nav-console">Console</a></li> 2101cb0ef41Sopenharmony_ci<li><a href="corepack.html" class="nav-corepack">Corepack</a></li> 2111cb0ef41Sopenharmony_ci<li><a href="crypto.html" class="nav-crypto">Crypto</a></li> 2121cb0ef41Sopenharmony_ci<li><a href="debugger.html" class="nav-debugger">Debugger</a></li> 2131cb0ef41Sopenharmony_ci<li><a href="deprecations.html" class="nav-deprecations">Deprecated APIs</a></li> 2141cb0ef41Sopenharmony_ci<li><a href="diagnostics_channel.html" class="nav-diagnostics_channel">Diagnostics Channel</a></li> 2151cb0ef41Sopenharmony_ci<li><a href="dns.html" class="nav-dns">DNS</a></li> 2161cb0ef41Sopenharmony_ci<li><a href="domain.html" class="nav-domain">Domain</a></li> 2171cb0ef41Sopenharmony_ci<li><a href="errors.html" class="nav-errors">Errors</a></li> 2181cb0ef41Sopenharmony_ci<li><a href="events.html" class="nav-events">Events</a></li> 2191cb0ef41Sopenharmony_ci<li><a href="fs.html" class="nav-fs">File system</a></li> 2201cb0ef41Sopenharmony_ci<li><a href="globals.html" class="nav-globals">Globals</a></li> 2211cb0ef41Sopenharmony_ci<li><a href="http.html" class="nav-http">HTTP</a></li> 2221cb0ef41Sopenharmony_ci<li><a href="http2.html" class="nav-http2">HTTP/2</a></li> 2231cb0ef41Sopenharmony_ci<li><a href="https.html" class="nav-https">HTTPS</a></li> 2241cb0ef41Sopenharmony_ci<li><a href="inspector.html" class="nav-inspector">Inspector</a></li> 2251cb0ef41Sopenharmony_ci<li><a href="intl.html" class="nav-intl">Internationalization</a></li> 2261cb0ef41Sopenharmony_ci<li><a href="modules.html" class="nav-modules">Modules: CommonJS modules</a></li> 2271cb0ef41Sopenharmony_ci<li><a href="esm.html" class="nav-esm">Modules: ECMAScript modules</a></li> 2281cb0ef41Sopenharmony_ci<li><a href="module.html" class="nav-module">Modules: <code>node:module</code> API</a></li> 2291cb0ef41Sopenharmony_ci<li><a href="packages.html" class="nav-packages">Modules: Packages</a></li> 2301cb0ef41Sopenharmony_ci<li><a href="net.html" class="nav-net">Net</a></li> 2311cb0ef41Sopenharmony_ci<li><a href="os.html" class="nav-os">OS</a></li> 2321cb0ef41Sopenharmony_ci<li><a href="path.html" class="nav-path">Path</a></li> 2331cb0ef41Sopenharmony_ci<li><a href="perf_hooks.html" class="nav-perf_hooks">Performance hooks</a></li> 2341cb0ef41Sopenharmony_ci<li><a href="permissions.html" class="nav-permissions">Permissions</a></li> 2351cb0ef41Sopenharmony_ci<li><a href="process.html" class="nav-process">Process</a></li> 2361cb0ef41Sopenharmony_ci<li><a href="punycode.html" class="nav-punycode">Punycode</a></li> 2371cb0ef41Sopenharmony_ci<li><a href="querystring.html" class="nav-querystring">Query strings</a></li> 2381cb0ef41Sopenharmony_ci<li><a href="readline.html" class="nav-readline">Readline</a></li> 2391cb0ef41Sopenharmony_ci<li><a href="repl.html" class="nav-repl">REPL</a></li> 2401cb0ef41Sopenharmony_ci<li><a href="report.html" class="nav-report">Report</a></li> 2411cb0ef41Sopenharmony_ci<li><a href="single-executable-applications.html" class="nav-single-executable-applications">Single executable applications</a></li> 2421cb0ef41Sopenharmony_ci<li><a href="stream.html" class="nav-stream">Stream</a></li> 2431cb0ef41Sopenharmony_ci<li><a href="string_decoder.html" class="nav-string_decoder">String decoder</a></li> 2441cb0ef41Sopenharmony_ci<li><a href="test.html" class="nav-test">Test runner</a></li> 2451cb0ef41Sopenharmony_ci<li><a href="timers.html" class="nav-timers">Timers</a></li> 2461cb0ef41Sopenharmony_ci<li><a href="tls.html" class="nav-tls">TLS/SSL</a></li> 2471cb0ef41Sopenharmony_ci<li><a href="tracing.html" class="nav-tracing">Trace events</a></li> 2481cb0ef41Sopenharmony_ci<li><a href="tty.html" class="nav-tty">TTY</a></li> 2491cb0ef41Sopenharmony_ci<li><a href="dgram.html" class="nav-dgram active">UDP/datagram</a></li> 2501cb0ef41Sopenharmony_ci<li><a href="url.html" class="nav-url">URL</a></li> 2511cb0ef41Sopenharmony_ci<li><a href="util.html" class="nav-util">Utilities</a></li> 2521cb0ef41Sopenharmony_ci<li><a href="v8.html" class="nav-v8">V8</a></li> 2531cb0ef41Sopenharmony_ci<li><a href="vm.html" class="nav-vm">VM</a></li> 2541cb0ef41Sopenharmony_ci<li><a href="wasi.html" class="nav-wasi">WASI</a></li> 2551cb0ef41Sopenharmony_ci<li><a href="webcrypto.html" class="nav-webcrypto">Web Crypto API</a></li> 2561cb0ef41Sopenharmony_ci<li><a href="webstreams.html" class="nav-webstreams">Web Streams API</a></li> 2571cb0ef41Sopenharmony_ci<li><a href="worker_threads.html" class="nav-worker_threads">Worker threads</a></li> 2581cb0ef41Sopenharmony_ci<li><a href="zlib.html" class="nav-zlib">Zlib</a></li> 2591cb0ef41Sopenharmony_ci</ul> 2601cb0ef41Sopenharmony_ci<hr class="line"> 2611cb0ef41Sopenharmony_ci<ul> 2621cb0ef41Sopenharmony_ci<li><a href="https://github.com/nodejs/node" class="nav-https-github-com-nodejs-node">Code repository and issue tracker</a></li> 2631cb0ef41Sopenharmony_ci</ul></div> 2641cb0ef41Sopenharmony_ci </li> 2651cb0ef41Sopenharmony_ci 2661cb0ef41Sopenharmony_ci 2671cb0ef41Sopenharmony_ci <li class="picker-header"> 2681cb0ef41Sopenharmony_ci <a href="#"> 2691cb0ef41Sopenharmony_ci <span class="collapsed-arrow">►</span><span class="expanded-arrow">▼</span> 2701cb0ef41Sopenharmony_ci Other versions 2711cb0ef41Sopenharmony_ci </a> 2721cb0ef41Sopenharmony_ci <div class="picker"><ol id="alt-docs"><li><a href="https://nodejs.org/docs/latest-v21.x/api/dgram.html">21.x</a></li> 2731cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v20.x/api/dgram.html">20.x <b>LTS</b></a></li> 2741cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v19.x/api/dgram.html">19.x</a></li> 2751cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v18.x/api/dgram.html">18.x <b>LTS</b></a></li> 2761cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v17.x/api/dgram.html">17.x</a></li> 2771cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v16.x/api/dgram.html">16.x</a></li> 2781cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v15.x/api/dgram.html">15.x</a></li> 2791cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v14.x/api/dgram.html">14.x</a></li> 2801cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v13.x/api/dgram.html">13.x</a></li> 2811cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v12.x/api/dgram.html">12.x</a></li> 2821cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v11.x/api/dgram.html">11.x</a></li> 2831cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v10.x/api/dgram.html">10.x</a></li> 2841cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v9.x/api/dgram.html">9.x</a></li> 2851cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v8.x/api/dgram.html">8.x</a></li> 2861cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v7.x/api/dgram.html">7.x</a></li> 2871cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v6.x/api/dgram.html">6.x</a></li> 2881cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v5.x/api/dgram.html">5.x</a></li> 2891cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v4.x/api/dgram.html">4.x</a></li> 2901cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v0.12.x/api/dgram.html">0.12.x</a></li> 2911cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v0.10.x/api/dgram.html">0.10.x</a></li></ol></div> 2921cb0ef41Sopenharmony_ci </li> 2931cb0ef41Sopenharmony_ci 2941cb0ef41Sopenharmony_ci <li class="picker-header"> 2951cb0ef41Sopenharmony_ci <a href="#"> 2961cb0ef41Sopenharmony_ci <span class="collapsed-arrow">►</span><span class="expanded-arrow">▼</span> 2971cb0ef41Sopenharmony_ci Options 2981cb0ef41Sopenharmony_ci </a> 2991cb0ef41Sopenharmony_ci 3001cb0ef41Sopenharmony_ci <div class="picker"> 3011cb0ef41Sopenharmony_ci <ul> 3021cb0ef41Sopenharmony_ci <li> 3031cb0ef41Sopenharmony_ci <a href="all.html">View on single page</a> 3041cb0ef41Sopenharmony_ci </li> 3051cb0ef41Sopenharmony_ci <li> 3061cb0ef41Sopenharmony_ci <a href="dgram.json">View as JSON</a> 3071cb0ef41Sopenharmony_ci </li> 3081cb0ef41Sopenharmony_ci <li class="edit_on_github"><a href="https://github.com/nodejs/node/edit/main/doc/api/dgram.md">Edit on GitHub</a></li> 3091cb0ef41Sopenharmony_ci </ul> 3101cb0ef41Sopenharmony_ci </div> 3111cb0ef41Sopenharmony_ci </li> 3121cb0ef41Sopenharmony_ci </ul> 3131cb0ef41Sopenharmony_ci </div> 3141cb0ef41Sopenharmony_ci <hr> 3151cb0ef41Sopenharmony_ci </header> 3161cb0ef41Sopenharmony_ci 3171cb0ef41Sopenharmony_ci <details id="toc" open><summary>Table of contents</summary><ul> 3181cb0ef41Sopenharmony_ci<li><span class="stability_2"><a href="#udpdatagram-sockets">UDP/datagram sockets</a></span> 3191cb0ef41Sopenharmony_ci<ul> 3201cb0ef41Sopenharmony_ci<li><a href="#class-dgramsocket">Class: <code>dgram.Socket</code></a> 3211cb0ef41Sopenharmony_ci<ul> 3221cb0ef41Sopenharmony_ci<li><a href="#event-close">Event: <code>'close'</code></a></li> 3231cb0ef41Sopenharmony_ci<li><a href="#event-connect">Event: <code>'connect'</code></a></li> 3241cb0ef41Sopenharmony_ci<li><a href="#event-error">Event: <code>'error'</code></a></li> 3251cb0ef41Sopenharmony_ci<li><a href="#event-listening">Event: <code>'listening'</code></a></li> 3261cb0ef41Sopenharmony_ci<li><a href="#event-message">Event: <code>'message'</code></a></li> 3271cb0ef41Sopenharmony_ci<li><a href="#socketaddmembershipmulticastaddress-multicastinterface"><code>socket.addMembership(multicastAddress[, multicastInterface])</code></a></li> 3281cb0ef41Sopenharmony_ci<li><a href="#socketaddsourcespecificmembershipsourceaddress-groupaddress-multicastinterface"><code>socket.addSourceSpecificMembership(sourceAddress, groupAddress[, multicastInterface])</code></a></li> 3291cb0ef41Sopenharmony_ci<li><a href="#socketaddress"><code>socket.address()</code></a></li> 3301cb0ef41Sopenharmony_ci<li><a href="#socketbindport-address-callback"><code>socket.bind([port][, address][, callback])</code></a></li> 3311cb0ef41Sopenharmony_ci<li><a href="#socketbindoptions-callback"><code>socket.bind(options[, callback])</code></a></li> 3321cb0ef41Sopenharmony_ci<li><a href="#socketclosecallback"><code>socket.close([callback])</code></a></li> 3331cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#socketsymbolasyncdispose"><code>socket[Symbol.asyncDispose]()</code></a></span></li> 3341cb0ef41Sopenharmony_ci<li><a href="#socketconnectport-address-callback"><code>socket.connect(port[, address][, callback])</code></a></li> 3351cb0ef41Sopenharmony_ci<li><a href="#socketdisconnect"><code>socket.disconnect()</code></a></li> 3361cb0ef41Sopenharmony_ci<li><a href="#socketdropmembershipmulticastaddress-multicastinterface"><code>socket.dropMembership(multicastAddress[, multicastInterface])</code></a></li> 3371cb0ef41Sopenharmony_ci<li><a href="#socketdropsourcespecificmembershipsourceaddress-groupaddress-multicastinterface"><code>socket.dropSourceSpecificMembership(sourceAddress, groupAddress[, multicastInterface])</code></a></li> 3381cb0ef41Sopenharmony_ci<li><a href="#socketgetrecvbuffersize"><code>socket.getRecvBufferSize()</code></a></li> 3391cb0ef41Sopenharmony_ci<li><a href="#socketgetsendbuffersize"><code>socket.getSendBufferSize()</code></a></li> 3401cb0ef41Sopenharmony_ci<li><a href="#socketgetsendqueuesize"><code>socket.getSendQueueSize()</code></a></li> 3411cb0ef41Sopenharmony_ci<li><a href="#socketgetsendqueuecount"><code>socket.getSendQueueCount()</code></a></li> 3421cb0ef41Sopenharmony_ci<li><a href="#socketref"><code>socket.ref()</code></a></li> 3431cb0ef41Sopenharmony_ci<li><a href="#socketremoteaddress"><code>socket.remoteAddress()</code></a></li> 3441cb0ef41Sopenharmony_ci<li><a href="#socketsendmsg-offset-length-port-address-callback"><code>socket.send(msg[, offset, length][, port][, address][, callback])</code></a> 3451cb0ef41Sopenharmony_ci<ul> 3461cb0ef41Sopenharmony_ci<li><a href="#note-about-udp-datagram-size">Note about UDP datagram size</a></li> 3471cb0ef41Sopenharmony_ci</ul> 3481cb0ef41Sopenharmony_ci</li> 3491cb0ef41Sopenharmony_ci<li><a href="#socketsetbroadcastflag"><code>socket.setBroadcast(flag)</code></a></li> 3501cb0ef41Sopenharmony_ci<li><a href="#socketsetmulticastinterfacemulticastinterface"><code>socket.setMulticastInterface(multicastInterface)</code></a> 3511cb0ef41Sopenharmony_ci<ul> 3521cb0ef41Sopenharmony_ci<li><a href="#example-ipv6-outgoing-multicast-interface">Example: IPv6 outgoing multicast interface</a></li> 3531cb0ef41Sopenharmony_ci<li><a href="#example-ipv4-outgoing-multicast-interface">Example: IPv4 outgoing multicast interface</a></li> 3541cb0ef41Sopenharmony_ci<li><a href="#call-results">Call results</a></li> 3551cb0ef41Sopenharmony_ci</ul> 3561cb0ef41Sopenharmony_ci</li> 3571cb0ef41Sopenharmony_ci<li><a href="#socketsetmulticastloopbackflag"><code>socket.setMulticastLoopback(flag)</code></a></li> 3581cb0ef41Sopenharmony_ci<li><a href="#socketsetmulticastttlttl"><code>socket.setMulticastTTL(ttl)</code></a></li> 3591cb0ef41Sopenharmony_ci<li><a href="#socketsetrecvbuffersizesize"><code>socket.setRecvBufferSize(size)</code></a></li> 3601cb0ef41Sopenharmony_ci<li><a href="#socketsetsendbuffersizesize"><code>socket.setSendBufferSize(size)</code></a></li> 3611cb0ef41Sopenharmony_ci<li><a href="#socketsetttlttl"><code>socket.setTTL(ttl)</code></a></li> 3621cb0ef41Sopenharmony_ci<li><a href="#socketunref"><code>socket.unref()</code></a></li> 3631cb0ef41Sopenharmony_ci</ul> 3641cb0ef41Sopenharmony_ci</li> 3651cb0ef41Sopenharmony_ci<li><a href="#nodedgram-module-functions"><code>node:dgram</code> module functions</a> 3661cb0ef41Sopenharmony_ci<ul> 3671cb0ef41Sopenharmony_ci<li><a href="#dgramcreatesocketoptions-callback"><code>dgram.createSocket(options[, callback])</code></a></li> 3681cb0ef41Sopenharmony_ci<li><a href="#dgramcreatesockettype-callback"><code>dgram.createSocket(type[, callback])</code></a></li> 3691cb0ef41Sopenharmony_ci</ul> 3701cb0ef41Sopenharmony_ci</li> 3711cb0ef41Sopenharmony_ci</ul> 3721cb0ef41Sopenharmony_ci</li> 3731cb0ef41Sopenharmony_ci</ul></details> 3741cb0ef41Sopenharmony_ci 3751cb0ef41Sopenharmony_ci <div id="apicontent"> 3761cb0ef41Sopenharmony_ci <h2>UDP/datagram sockets<span><a class="mark" href="#udpdatagram-sockets" id="udpdatagram-sockets">#</a></span><a aria-hidden="true" class="legacy" id="dgram_udp_datagram_sockets"></a></h2> 3771cb0ef41Sopenharmony_ci 3781cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_2"><a href="documentation.html#stability-index">Stability: 2</a> - Stable</div><p></p> 3791cb0ef41Sopenharmony_ci 3801cb0ef41Sopenharmony_ci<p><strong>Source Code:</strong> <a href="https://github.com/nodejs/node/blob/v18.20.1/lib/dgram.js">lib/dgram.js</a></p> 3811cb0ef41Sopenharmony_ci<p>The <code>node:dgram</code> module provides an implementation of UDP datagram sockets.</p> 3821cb0ef41Sopenharmony_ci 3831cb0ef41Sopenharmony_ci<pre class="with-42-chars"><input class="js-flavor-selector" type="checkbox" checked aria-label="Show modern ES modules syntax"><code class="language-js mjs"><span class="hljs-keyword">import</span> dgram <span class="hljs-keyword">from</span> <span class="hljs-string">'node:dgram'</span>; 3841cb0ef41Sopenharmony_ci 3851cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> server = dgram.<span class="hljs-title function_">createSocket</span>(<span class="hljs-string">'udp4'</span>); 3861cb0ef41Sopenharmony_ci 3871cb0ef41Sopenharmony_ciserver.<span class="hljs-title function_">on</span>(<span class="hljs-string">'error'</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 3881cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">`server error:\n<span class="hljs-subst">${err.stack}</span>`</span>); 3891cb0ef41Sopenharmony_ci server.<span class="hljs-title function_">close</span>(); 3901cb0ef41Sopenharmony_ci}); 3911cb0ef41Sopenharmony_ci 3921cb0ef41Sopenharmony_ciserver.<span class="hljs-title function_">on</span>(<span class="hljs-string">'message'</span>, <span class="hljs-function">(<span class="hljs-params">msg, rinfo</span>) =></span> { 3931cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<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>); 3941cb0ef41Sopenharmony_ci}); 3951cb0ef41Sopenharmony_ci 3961cb0ef41Sopenharmony_ciserver.<span class="hljs-title function_">on</span>(<span class="hljs-string">'listening'</span>, <span class="hljs-function">() =></span> { 3971cb0ef41Sopenharmony_ci <span class="hljs-keyword">const</span> address = server.<span class="hljs-title function_">address</span>(); 3981cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">`server listening <span class="hljs-subst">${address.address}</span>:<span class="hljs-subst">${address.port}</span>`</span>); 3991cb0ef41Sopenharmony_ci}); 4001cb0ef41Sopenharmony_ci 4011cb0ef41Sopenharmony_ciserver.<span class="hljs-title function_">bind</span>(<span class="hljs-number">41234</span>); 4021cb0ef41Sopenharmony_ci<span class="hljs-comment">// Prints: server listening 0.0.0.0:41234</span></code><code class="language-js cjs"><span class="hljs-keyword">const</span> dgram = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:dgram'</span>); 4031cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> server = dgram.<span class="hljs-title function_">createSocket</span>(<span class="hljs-string">'udp4'</span>); 4041cb0ef41Sopenharmony_ci 4051cb0ef41Sopenharmony_ciserver.<span class="hljs-title function_">on</span>(<span class="hljs-string">'error'</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 4061cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">`server error:\n<span class="hljs-subst">${err.stack}</span>`</span>); 4071cb0ef41Sopenharmony_ci server.<span class="hljs-title function_">close</span>(); 4081cb0ef41Sopenharmony_ci}); 4091cb0ef41Sopenharmony_ci 4101cb0ef41Sopenharmony_ciserver.<span class="hljs-title function_">on</span>(<span class="hljs-string">'message'</span>, <span class="hljs-function">(<span class="hljs-params">msg, rinfo</span>) =></span> { 4111cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<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>); 4121cb0ef41Sopenharmony_ci}); 4131cb0ef41Sopenharmony_ci 4141cb0ef41Sopenharmony_ciserver.<span class="hljs-title function_">on</span>(<span class="hljs-string">'listening'</span>, <span class="hljs-function">() =></span> { 4151cb0ef41Sopenharmony_ci <span class="hljs-keyword">const</span> address = server.<span class="hljs-title function_">address</span>(); 4161cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">`server listening <span class="hljs-subst">${address.address}</span>:<span class="hljs-subst">${address.port}</span>`</span>); 4171cb0ef41Sopenharmony_ci}); 4181cb0ef41Sopenharmony_ci 4191cb0ef41Sopenharmony_ciserver.<span class="hljs-title function_">bind</span>(<span class="hljs-number">41234</span>); 4201cb0ef41Sopenharmony_ci<span class="hljs-comment">// Prints: server listening 0.0.0.0:41234</span></code><button class="copy-button">copy</button></pre> 4211cb0ef41Sopenharmony_ci<section><h3>Class: <code>dgram.Socket</code><span><a class="mark" href="#class-dgramsocket" id="class-dgramsocket">#</a></span><a aria-hidden="true" class="legacy" id="dgram_class_dgram_socket"></a></h3> 4221cb0ef41Sopenharmony_ci<div class="api_metadata"> 4231cb0ef41Sopenharmony_ci<span>Added in: v0.1.99</span> 4241cb0ef41Sopenharmony_ci</div> 4251cb0ef41Sopenharmony_ci<ul> 4261cb0ef41Sopenharmony_ci<li>Extends: <a href="events.html#class-eventemitter" class="type"><EventEmitter></a></li> 4271cb0ef41Sopenharmony_ci</ul> 4281cb0ef41Sopenharmony_ci<p>Encapsulates the datagram functionality.</p> 4291cb0ef41Sopenharmony_ci<p>New instances of <code>dgram.Socket</code> are created using <a href="#dgramcreatesocketoptions-callback"><code>dgram.createSocket()</code></a>. 4301cb0ef41Sopenharmony_ciThe <code>new</code> keyword is not to be used to create <code>dgram.Socket</code> instances.</p> 4311cb0ef41Sopenharmony_ci<h4>Event: <code>'close'</code><span><a class="mark" href="#event-close" id="event-close">#</a></span><a aria-hidden="true" class="legacy" id="dgram_event_close"></a></h4> 4321cb0ef41Sopenharmony_ci<div class="api_metadata"> 4331cb0ef41Sopenharmony_ci<span>Added in: v0.1.99</span> 4341cb0ef41Sopenharmony_ci</div> 4351cb0ef41Sopenharmony_ci<p>The <code>'close'</code> event is emitted after a socket is closed with <a href="#socketclosecallback"><code>close()</code></a>. 4361cb0ef41Sopenharmony_ciOnce triggered, no new <code>'message'</code> events will be emitted on this socket.</p> 4371cb0ef41Sopenharmony_ci<h4>Event: <code>'connect'</code><span><a class="mark" href="#event-connect" id="event-connect">#</a></span><a aria-hidden="true" class="legacy" id="dgram_event_connect"></a></h4> 4381cb0ef41Sopenharmony_ci<div class="api_metadata"> 4391cb0ef41Sopenharmony_ci<span>Added in: v12.0.0</span> 4401cb0ef41Sopenharmony_ci</div> 4411cb0ef41Sopenharmony_ci<p>The <code>'connect'</code> event is emitted after a socket is associated to a remote 4421cb0ef41Sopenharmony_ciaddress as a result of a successful <a href="#socketconnectport-address-callback"><code>connect()</code></a> call.</p> 4431cb0ef41Sopenharmony_ci<h4>Event: <code>'error'</code><span><a class="mark" href="#event-error" id="event-error">#</a></span><a aria-hidden="true" class="legacy" id="dgram_event_error"></a></h4> 4441cb0ef41Sopenharmony_ci<div class="api_metadata"> 4451cb0ef41Sopenharmony_ci<span>Added in: v0.1.99</span> 4461cb0ef41Sopenharmony_ci</div> 4471cb0ef41Sopenharmony_ci<ul> 4481cb0ef41Sopenharmony_ci<li><code>exception</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 4491cb0ef41Sopenharmony_ci</ul> 4501cb0ef41Sopenharmony_ci<p>The <code>'error'</code> event is emitted whenever any error occurs. The event handler 4511cb0ef41Sopenharmony_cifunction is passed a single <code>Error</code> object.</p> 4521cb0ef41Sopenharmony_ci<h4>Event: <code>'listening'</code><span><a class="mark" href="#event-listening" id="event-listening">#</a></span><a aria-hidden="true" class="legacy" id="dgram_event_listening"></a></h4> 4531cb0ef41Sopenharmony_ci<div class="api_metadata"> 4541cb0ef41Sopenharmony_ci<span>Added in: v0.1.99</span> 4551cb0ef41Sopenharmony_ci</div> 4561cb0ef41Sopenharmony_ci<p>The <code>'listening'</code> event is emitted once the <code>dgram.Socket</code> is addressable and 4571cb0ef41Sopenharmony_cican receive data. This happens either explicitly with <code>socket.bind()</code> or 4581cb0ef41Sopenharmony_ciimplicitly the first time data is sent using <code>socket.send()</code>. 4591cb0ef41Sopenharmony_ciUntil the <code>dgram.Socket</code> is listening, the underlying system resources do not 4601cb0ef41Sopenharmony_ciexist and calls such as <code>socket.address()</code> and <code>socket.setTTL()</code> will fail.</p> 4611cb0ef41Sopenharmony_ci<h4>Event: <code>'message'</code><span><a class="mark" href="#event-message" id="event-message">#</a></span><a aria-hidden="true" class="legacy" id="dgram_event_message"></a></h4> 4621cb0ef41Sopenharmony_ci<div class="api_metadata"> 4631cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 4641cb0ef41Sopenharmony_ci<table> 4651cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 4661cb0ef41Sopenharmony_ci<tr><td>v18.4.0</td> 4671cb0ef41Sopenharmony_ci<td><p>The <code>family</code> property now returns a string instead of a number.</p></td></tr> 4681cb0ef41Sopenharmony_ci<tr><td>v18.0.0</td> 4691cb0ef41Sopenharmony_ci<td><p>The <code>family</code> property now returns a number instead of a string.</p></td></tr> 4701cb0ef41Sopenharmony_ci<tr><td>v0.1.99</td> 4711cb0ef41Sopenharmony_ci<td><p><span>Added in: v0.1.99</span></p></td></tr> 4721cb0ef41Sopenharmony_ci</tbody></table> 4731cb0ef41Sopenharmony_ci</details> 4741cb0ef41Sopenharmony_ci</div> 4751cb0ef41Sopenharmony_ci<p>The <code>'message'</code> event is emitted when a new datagram is available on a socket. 4761cb0ef41Sopenharmony_ciThe event handler function is passed two arguments: <code>msg</code> and <code>rinfo</code>.</p> 4771cb0ef41Sopenharmony_ci<ul> 4781cb0ef41Sopenharmony_ci<li><code>msg</code> <a href="buffer.html#class-buffer" class="type"><Buffer></a> The message.</li> 4791cb0ef41Sopenharmony_ci<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. 4801cb0ef41Sopenharmony_ci<ul> 4811cb0ef41Sopenharmony_ci<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> 4821cb0ef41Sopenharmony_ci<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> 4831cb0ef41Sopenharmony_ci<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> 4841cb0ef41Sopenharmony_ci<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> 4851cb0ef41Sopenharmony_ci</ul> 4861cb0ef41Sopenharmony_ci</li> 4871cb0ef41Sopenharmony_ci</ul> 4881cb0ef41Sopenharmony_ci<p>If the source address of the incoming packet is an IPv6 link-local 4891cb0ef41Sopenharmony_ciaddress, the interface name is added to the <code>address</code>. For 4901cb0ef41Sopenharmony_ciexample, a packet received on the <code>en0</code> interface might have the 4911cb0ef41Sopenharmony_ciaddress field set to <code>'fe80::2618:1234:ab11:3b9c%en0'</code>, where <code>'%en0'</code> 4921cb0ef41Sopenharmony_ciis the interface name as a zone ID suffix.</p> 4931cb0ef41Sopenharmony_ci<h4><code>socket.addMembership(multicastAddress[, multicastInterface])</code><span><a class="mark" href="#socketaddmembershipmulticastaddress-multicastinterface" id="socketaddmembershipmulticastaddress-multicastinterface">#</a></span><a aria-hidden="true" class="legacy" id="dgram_socket_addmembership_multicastaddress_multicastinterface"></a></h4> 4941cb0ef41Sopenharmony_ci<div class="api_metadata"> 4951cb0ef41Sopenharmony_ci<span>Added in: v0.6.9</span> 4961cb0ef41Sopenharmony_ci</div> 4971cb0ef41Sopenharmony_ci<ul> 4981cb0ef41Sopenharmony_ci<li><code>multicastAddress</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 4991cb0ef41Sopenharmony_ci<li><code>multicastInterface</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 5001cb0ef41Sopenharmony_ci</ul> 5011cb0ef41Sopenharmony_ci<p>Tells the kernel to join a multicast group at the given <code>multicastAddress</code> and 5021cb0ef41Sopenharmony_ci<code>multicastInterface</code> using the <code>IP_ADD_MEMBERSHIP</code> socket option. If the 5031cb0ef41Sopenharmony_ci<code>multicastInterface</code> argument is not specified, the operating system will choose 5041cb0ef41Sopenharmony_cione interface and will add membership to it. To add membership to every 5051cb0ef41Sopenharmony_ciavailable interface, call <code>addMembership</code> multiple times, once per interface.</p> 5061cb0ef41Sopenharmony_ci<p>When called on an unbound socket, this method will implicitly bind to a random 5071cb0ef41Sopenharmony_ciport, listening on all interfaces.</p> 5081cb0ef41Sopenharmony_ci<p>When sharing a UDP socket across multiple <code>cluster</code> workers, the 5091cb0ef41Sopenharmony_ci<code>socket.addMembership()</code> function must be called only once or an 5101cb0ef41Sopenharmony_ci<code>EADDRINUSE</code> error will occur:</p> 5111cb0ef41Sopenharmony_ci 5121cb0ef41Sopenharmony_ci<pre class="with-40-chars"><input class="js-flavor-selector" type="checkbox" checked aria-label="Show modern ES modules syntax"><code class="language-js mjs"><span class="hljs-keyword">import</span> cluster <span class="hljs-keyword">from</span> <span class="hljs-string">'node:cluster'</span>; 5131cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> dgram <span class="hljs-keyword">from</span> <span class="hljs-string">'node:dgram'</span>; 5141cb0ef41Sopenharmony_ci 5151cb0ef41Sopenharmony_ci<span class="hljs-keyword">if</span> (cluster.<span class="hljs-property">isPrimary</span>) { 5161cb0ef41Sopenharmony_ci cluster.<span class="hljs-title function_">fork</span>(); <span class="hljs-comment">// Works ok.</span> 5171cb0ef41Sopenharmony_ci cluster.<span class="hljs-title function_">fork</span>(); <span class="hljs-comment">// Fails with EADDRINUSE.</span> 5181cb0ef41Sopenharmony_ci} <span class="hljs-keyword">else</span> { 5191cb0ef41Sopenharmony_ci <span class="hljs-keyword">const</span> s = dgram.<span class="hljs-title function_">createSocket</span>(<span class="hljs-string">'udp4'</span>); 5201cb0ef41Sopenharmony_ci s.<span class="hljs-title function_">bind</span>(<span class="hljs-number">1234</span>, <span class="hljs-function">() =></span> { 5211cb0ef41Sopenharmony_ci s.<span class="hljs-title function_">addMembership</span>(<span class="hljs-string">'224.0.0.114'</span>); 5221cb0ef41Sopenharmony_ci }); 5231cb0ef41Sopenharmony_ci}</code><code class="language-js cjs"><span class="hljs-keyword">const</span> cluster = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:cluster'</span>); 5241cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> dgram = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:dgram'</span>); 5251cb0ef41Sopenharmony_ci 5261cb0ef41Sopenharmony_ci<span class="hljs-keyword">if</span> (cluster.<span class="hljs-property">isPrimary</span>) { 5271cb0ef41Sopenharmony_ci cluster.<span class="hljs-title function_">fork</span>(); <span class="hljs-comment">// Works ok.</span> 5281cb0ef41Sopenharmony_ci cluster.<span class="hljs-title function_">fork</span>(); <span class="hljs-comment">// Fails with EADDRINUSE.</span> 5291cb0ef41Sopenharmony_ci} <span class="hljs-keyword">else</span> { 5301cb0ef41Sopenharmony_ci <span class="hljs-keyword">const</span> s = dgram.<span class="hljs-title function_">createSocket</span>(<span class="hljs-string">'udp4'</span>); 5311cb0ef41Sopenharmony_ci s.<span class="hljs-title function_">bind</span>(<span class="hljs-number">1234</span>, <span class="hljs-function">() =></span> { 5321cb0ef41Sopenharmony_ci s.<span class="hljs-title function_">addMembership</span>(<span class="hljs-string">'224.0.0.114'</span>); 5331cb0ef41Sopenharmony_ci }); 5341cb0ef41Sopenharmony_ci}</code><button class="copy-button">copy</button></pre> 5351cb0ef41Sopenharmony_ci<h4><code>socket.addSourceSpecificMembership(sourceAddress, groupAddress[, multicastInterface])</code><span><a class="mark" href="#socketaddsourcespecificmembershipsourceaddress-groupaddress-multicastinterface" id="socketaddsourcespecificmembershipsourceaddress-groupaddress-multicastinterface">#</a></span><a aria-hidden="true" class="legacy" id="dgram_socket_addsourcespecificmembership_sourceaddress_groupaddress_multicastinterface"></a></h4> 5361cb0ef41Sopenharmony_ci<div class="api_metadata"> 5371cb0ef41Sopenharmony_ci<span>Added in: v13.1.0, v12.16.0</span> 5381cb0ef41Sopenharmony_ci</div> 5391cb0ef41Sopenharmony_ci<ul> 5401cb0ef41Sopenharmony_ci<li><code>sourceAddress</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 5411cb0ef41Sopenharmony_ci<li><code>groupAddress</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 5421cb0ef41Sopenharmony_ci<li><code>multicastInterface</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 5431cb0ef41Sopenharmony_ci</ul> 5441cb0ef41Sopenharmony_ci<p>Tells the kernel to join a source-specific multicast channel at the given 5451cb0ef41Sopenharmony_ci<code>sourceAddress</code> and <code>groupAddress</code>, using the <code>multicastInterface</code> with the 5461cb0ef41Sopenharmony_ci<code>IP_ADD_SOURCE_MEMBERSHIP</code> socket option. If the <code>multicastInterface</code> argument 5471cb0ef41Sopenharmony_ciis not specified, the operating system will choose one interface and will add 5481cb0ef41Sopenharmony_cimembership to it. To add membership to every available interface, call 5491cb0ef41Sopenharmony_ci<code>socket.addSourceSpecificMembership()</code> multiple times, once per interface.</p> 5501cb0ef41Sopenharmony_ci<p>When called on an unbound socket, this method will implicitly bind to a random 5511cb0ef41Sopenharmony_ciport, listening on all interfaces.</p> 5521cb0ef41Sopenharmony_ci<h4><code>socket.address()</code><span><a class="mark" href="#socketaddress" id="socketaddress">#</a></span><a aria-hidden="true" class="legacy" id="dgram_socket_address"></a></h4> 5531cb0ef41Sopenharmony_ci<div class="api_metadata"> 5541cb0ef41Sopenharmony_ci<span>Added in: v0.1.99</span> 5551cb0ef41Sopenharmony_ci</div> 5561cb0ef41Sopenharmony_ci<ul> 5571cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a></li> 5581cb0ef41Sopenharmony_ci</ul> 5591cb0ef41Sopenharmony_ci<p>Returns an object containing the address information for a socket. 5601cb0ef41Sopenharmony_ciFor UDP sockets, this object will contain <code>address</code>, <code>family</code>, and <code>port</code> 5611cb0ef41Sopenharmony_ciproperties.</p> 5621cb0ef41Sopenharmony_ci<p>This method throws <code>EBADF</code> if called on an unbound socket.</p> 5631cb0ef41Sopenharmony_ci<h4><code>socket.bind([port][, address][, callback])</code><span><a class="mark" href="#socketbindport-address-callback" id="socketbindport-address-callback">#</a></span><a aria-hidden="true" class="legacy" id="dgram_socket_bind_port_address_callback"></a></h4> 5641cb0ef41Sopenharmony_ci<div class="api_metadata"> 5651cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 5661cb0ef41Sopenharmony_ci<table> 5671cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 5681cb0ef41Sopenharmony_ci<tr><td>v0.9.1</td> 5691cb0ef41Sopenharmony_ci<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> 5701cb0ef41Sopenharmony_ci<tr><td>v0.1.99</td> 5711cb0ef41Sopenharmony_ci<td><p><span>Added in: v0.1.99</span></p></td></tr> 5721cb0ef41Sopenharmony_ci</tbody></table> 5731cb0ef41Sopenharmony_ci</details> 5741cb0ef41Sopenharmony_ci</div> 5751cb0ef41Sopenharmony_ci<ul> 5761cb0ef41Sopenharmony_ci<li><code>port</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 5771cb0ef41Sopenharmony_ci<li><code>address</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 5781cb0ef41Sopenharmony_ci<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> 5791cb0ef41Sopenharmony_ci</ul> 5801cb0ef41Sopenharmony_ci<p>For UDP sockets, causes the <code>dgram.Socket</code> to listen for datagram 5811cb0ef41Sopenharmony_cimessages on a named <code>port</code> and optional <code>address</code>. If <code>port</code> is not 5821cb0ef41Sopenharmony_cispecified or is <code>0</code>, the operating system will attempt to bind to a 5831cb0ef41Sopenharmony_cirandom port. If <code>address</code> is not specified, the operating system will 5841cb0ef41Sopenharmony_ciattempt to listen on all addresses. Once binding is complete, a 5851cb0ef41Sopenharmony_ci<code>'listening'</code> event is emitted and the optional <code>callback</code> function is 5861cb0ef41Sopenharmony_cicalled.</p> 5871cb0ef41Sopenharmony_ci<p>Specifying both a <code>'listening'</code> event listener and passing a 5881cb0ef41Sopenharmony_ci<code>callback</code> to the <code>socket.bind()</code> method is not harmful but not very 5891cb0ef41Sopenharmony_ciuseful.</p> 5901cb0ef41Sopenharmony_ci<p>A bound datagram socket keeps the Node.js process running to receive 5911cb0ef41Sopenharmony_cidatagram messages.</p> 5921cb0ef41Sopenharmony_ci<p>If binding fails, an <code>'error'</code> event is generated. In rare case (e.g. 5931cb0ef41Sopenharmony_ciattempting to bind with a closed socket), an <a href="errors.html#class-error"><code>Error</code></a> may be thrown.</p> 5941cb0ef41Sopenharmony_ci<p>Example of a UDP server listening on port 41234:</p> 5951cb0ef41Sopenharmony_ci 5961cb0ef41Sopenharmony_ci<pre class="with-42-chars"><input class="js-flavor-selector" type="checkbox" checked aria-label="Show modern ES modules syntax"><code class="language-js mjs"><span class="hljs-keyword">import</span> dgram <span class="hljs-keyword">from</span> <span class="hljs-string">'node:dgram'</span>; 5971cb0ef41Sopenharmony_ci 5981cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> server = dgram.<span class="hljs-title function_">createSocket</span>(<span class="hljs-string">'udp4'</span>); 5991cb0ef41Sopenharmony_ci 6001cb0ef41Sopenharmony_ciserver.<span class="hljs-title function_">on</span>(<span class="hljs-string">'error'</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 6011cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">`server error:\n<span class="hljs-subst">${err.stack}</span>`</span>); 6021cb0ef41Sopenharmony_ci server.<span class="hljs-title function_">close</span>(); 6031cb0ef41Sopenharmony_ci}); 6041cb0ef41Sopenharmony_ci 6051cb0ef41Sopenharmony_ciserver.<span class="hljs-title function_">on</span>(<span class="hljs-string">'message'</span>, <span class="hljs-function">(<span class="hljs-params">msg, rinfo</span>) =></span> { 6061cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<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>); 6071cb0ef41Sopenharmony_ci}); 6081cb0ef41Sopenharmony_ci 6091cb0ef41Sopenharmony_ciserver.<span class="hljs-title function_">on</span>(<span class="hljs-string">'listening'</span>, <span class="hljs-function">() =></span> { 6101cb0ef41Sopenharmony_ci <span class="hljs-keyword">const</span> address = server.<span class="hljs-title function_">address</span>(); 6111cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">`server listening <span class="hljs-subst">${address.address}</span>:<span class="hljs-subst">${address.port}</span>`</span>); 6121cb0ef41Sopenharmony_ci}); 6131cb0ef41Sopenharmony_ci 6141cb0ef41Sopenharmony_ciserver.<span class="hljs-title function_">bind</span>(<span class="hljs-number">41234</span>); 6151cb0ef41Sopenharmony_ci<span class="hljs-comment">// Prints: server listening 0.0.0.0:41234</span></code><code class="language-js cjs"><span class="hljs-keyword">const</span> dgram = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:dgram'</span>); 6161cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> server = dgram.<span class="hljs-title function_">createSocket</span>(<span class="hljs-string">'udp4'</span>); 6171cb0ef41Sopenharmony_ci 6181cb0ef41Sopenharmony_ciserver.<span class="hljs-title function_">on</span>(<span class="hljs-string">'error'</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 6191cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">`server error:\n<span class="hljs-subst">${err.stack}</span>`</span>); 6201cb0ef41Sopenharmony_ci server.<span class="hljs-title function_">close</span>(); 6211cb0ef41Sopenharmony_ci}); 6221cb0ef41Sopenharmony_ci 6231cb0ef41Sopenharmony_ciserver.<span class="hljs-title function_">on</span>(<span class="hljs-string">'message'</span>, <span class="hljs-function">(<span class="hljs-params">msg, rinfo</span>) =></span> { 6241cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<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>); 6251cb0ef41Sopenharmony_ci}); 6261cb0ef41Sopenharmony_ci 6271cb0ef41Sopenharmony_ciserver.<span class="hljs-title function_">on</span>(<span class="hljs-string">'listening'</span>, <span class="hljs-function">() =></span> { 6281cb0ef41Sopenharmony_ci <span class="hljs-keyword">const</span> address = server.<span class="hljs-title function_">address</span>(); 6291cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">`server listening <span class="hljs-subst">${address.address}</span>:<span class="hljs-subst">${address.port}</span>`</span>); 6301cb0ef41Sopenharmony_ci}); 6311cb0ef41Sopenharmony_ci 6321cb0ef41Sopenharmony_ciserver.<span class="hljs-title function_">bind</span>(<span class="hljs-number">41234</span>); 6331cb0ef41Sopenharmony_ci<span class="hljs-comment">// Prints: server listening 0.0.0.0:41234</span></code><button class="copy-button">copy</button></pre> 6341cb0ef41Sopenharmony_ci<h4><code>socket.bind(options[, callback])</code><span><a class="mark" href="#socketbindoptions-callback" id="socketbindoptions-callback">#</a></span><a aria-hidden="true" class="legacy" id="dgram_socket_bind_options_callback"></a></h4> 6351cb0ef41Sopenharmony_ci<div class="api_metadata"> 6361cb0ef41Sopenharmony_ci<span>Added in: v0.11.14</span> 6371cb0ef41Sopenharmony_ci</div> 6381cb0ef41Sopenharmony_ci<ul> 6391cb0ef41Sopenharmony_ci<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: 6401cb0ef41Sopenharmony_ci<ul> 6411cb0ef41Sopenharmony_ci<li><code>port</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 6421cb0ef41Sopenharmony_ci<li><code>address</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 6431cb0ef41Sopenharmony_ci<li><code>exclusive</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 6441cb0ef41Sopenharmony_ci<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 6451cb0ef41Sopenharmony_ci</ul> 6461cb0ef41Sopenharmony_ci</li> 6471cb0ef41Sopenharmony_ci<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a></li> 6481cb0ef41Sopenharmony_ci</ul> 6491cb0ef41Sopenharmony_ci<p>For UDP sockets, causes the <code>dgram.Socket</code> to listen for datagram 6501cb0ef41Sopenharmony_cimessages on a named <code>port</code> and optional <code>address</code> that are passed as 6511cb0ef41Sopenharmony_ciproperties of an <code>options</code> object passed as the first argument. If 6521cb0ef41Sopenharmony_ci<code>port</code> is not specified or is <code>0</code>, the operating system will attempt 6531cb0ef41Sopenharmony_cito bind to a random port. If <code>address</code> is not specified, the operating 6541cb0ef41Sopenharmony_cisystem will attempt to listen on all addresses. Once binding is 6551cb0ef41Sopenharmony_cicomplete, a <code>'listening'</code> event is emitted and the optional <code>callback</code> 6561cb0ef41Sopenharmony_cifunction is called.</p> 6571cb0ef41Sopenharmony_ci<p>The <code>options</code> object may contain a <code>fd</code> property. When a <code>fd</code> greater 6581cb0ef41Sopenharmony_cithan <code>0</code> is set, it will wrap around an existing socket with the given 6591cb0ef41Sopenharmony_cifile descriptor. In this case, the properties of <code>port</code> and <code>address</code> 6601cb0ef41Sopenharmony_ciwill be ignored.</p> 6611cb0ef41Sopenharmony_ci<p>Specifying both a <code>'listening'</code> event listener and passing a 6621cb0ef41Sopenharmony_ci<code>callback</code> to the <code>socket.bind()</code> method is not harmful but not very 6631cb0ef41Sopenharmony_ciuseful.</p> 6641cb0ef41Sopenharmony_ci<p>The <code>options</code> object may contain an additional <code>exclusive</code> property that is 6651cb0ef41Sopenharmony_ciused when using <code>dgram.Socket</code> objects with the <a href="cluster.html"><code>cluster</code></a> module. When 6661cb0ef41Sopenharmony_ci<code>exclusive</code> is set to <code>false</code> (the default), cluster workers will use the same 6671cb0ef41Sopenharmony_ciunderlying socket handle allowing connection handling duties to be shared. 6681cb0ef41Sopenharmony_ciWhen <code>exclusive</code> is <code>true</code>, however, the handle is not shared and attempted 6691cb0ef41Sopenharmony_ciport sharing results in an error.</p> 6701cb0ef41Sopenharmony_ci<p>A bound datagram socket keeps the Node.js process running to receive 6711cb0ef41Sopenharmony_cidatagram messages.</p> 6721cb0ef41Sopenharmony_ci<p>If binding fails, an <code>'error'</code> event is generated. In rare case (e.g. 6731cb0ef41Sopenharmony_ciattempting to bind with a closed socket), an <a href="errors.html#class-error"><code>Error</code></a> may be thrown.</p> 6741cb0ef41Sopenharmony_ci<p>An example socket listening on an exclusive port is shown below.</p> 6751cb0ef41Sopenharmony_ci<pre><code class="language-js">socket.<span class="hljs-title function_">bind</span>({ 6761cb0ef41Sopenharmony_ci <span class="hljs-attr">address</span>: <span class="hljs-string">'localhost'</span>, 6771cb0ef41Sopenharmony_ci <span class="hljs-attr">port</span>: <span class="hljs-number">8000</span>, 6781cb0ef41Sopenharmony_ci <span class="hljs-attr">exclusive</span>: <span class="hljs-literal">true</span>, 6791cb0ef41Sopenharmony_ci});</code> <button class="copy-button">copy</button></pre> 6801cb0ef41Sopenharmony_ci<h4><code>socket.close([callback])</code><span><a class="mark" href="#socketclosecallback" id="socketclosecallback">#</a></span><a aria-hidden="true" class="legacy" id="dgram_socket_close_callback"></a></h4> 6811cb0ef41Sopenharmony_ci<div class="api_metadata"> 6821cb0ef41Sopenharmony_ci<span>Added in: v0.1.99</span> 6831cb0ef41Sopenharmony_ci</div> 6841cb0ef41Sopenharmony_ci<ul> 6851cb0ef41Sopenharmony_ci<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> 6861cb0ef41Sopenharmony_ci</ul> 6871cb0ef41Sopenharmony_ci<p>Close the underlying socket and stop listening for data on it. If a callback is 6881cb0ef41Sopenharmony_ciprovided, it is added as a listener for the <a href="#event-close"><code>'close'</code></a> event.</p> 6891cb0ef41Sopenharmony_ci<h4><code>socket[Symbol.asyncDispose]()</code><span><a class="mark" href="#socketsymbolasyncdispose" id="socketsymbolasyncdispose">#</a></span><a aria-hidden="true" class="legacy" id="dgram_socket_symbol_asyncdispose"></a></h4> 6901cb0ef41Sopenharmony_ci<div class="api_metadata"> 6911cb0ef41Sopenharmony_ci<span>Added in: v18.18.0</span> 6921cb0ef41Sopenharmony_ci</div> 6931cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - Experimental</div><p></p> 6941cb0ef41Sopenharmony_ci<p>Calls <a href="#socketclosecallback"><code>socket.close()</code></a> and returns a promise that fulfills when the 6951cb0ef41Sopenharmony_cisocket has closed.</p> 6961cb0ef41Sopenharmony_ci<h4><code>socket.connect(port[, address][, callback])</code><span><a class="mark" href="#socketconnectport-address-callback" id="socketconnectport-address-callback">#</a></span><a aria-hidden="true" class="legacy" id="dgram_socket_connect_port_address_callback"></a></h4> 6971cb0ef41Sopenharmony_ci<div class="api_metadata"> 6981cb0ef41Sopenharmony_ci<span>Added in: v12.0.0</span> 6991cb0ef41Sopenharmony_ci</div> 7001cb0ef41Sopenharmony_ci<ul> 7011cb0ef41Sopenharmony_ci<li><code>port</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 7021cb0ef41Sopenharmony_ci<li><code>address</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 7031cb0ef41Sopenharmony_ci<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> 7041cb0ef41Sopenharmony_ci</ul> 7051cb0ef41Sopenharmony_ci<p>Associates the <code>dgram.Socket</code> to a remote address and port. Every 7061cb0ef41Sopenharmony_cimessage sent by this handle is automatically sent to that destination. Also, 7071cb0ef41Sopenharmony_cithe socket will only receive messages from that remote peer. 7081cb0ef41Sopenharmony_ciTrying to call <code>connect()</code> on an already connected socket will result 7091cb0ef41Sopenharmony_ciin an <a href="errors.html#err_socket_dgram_is_connected"><code>ERR_SOCKET_DGRAM_IS_CONNECTED</code></a> exception. If <code>address</code> is not 7101cb0ef41Sopenharmony_ciprovided, <code>'127.0.0.1'</code> (for <code>udp4</code> sockets) or <code>'::1'</code> (for <code>udp6</code> sockets) 7111cb0ef41Sopenharmony_ciwill be used by default. Once the connection is complete, a <code>'connect'</code> event 7121cb0ef41Sopenharmony_ciis emitted and the optional <code>callback</code> function is called. In case of failure, 7131cb0ef41Sopenharmony_cithe <code>callback</code> is called or, failing this, an <code>'error'</code> event is emitted.</p> 7141cb0ef41Sopenharmony_ci<h4><code>socket.disconnect()</code><span><a class="mark" href="#socketdisconnect" id="socketdisconnect">#</a></span><a aria-hidden="true" class="legacy" id="dgram_socket_disconnect"></a></h4> 7151cb0ef41Sopenharmony_ci<div class="api_metadata"> 7161cb0ef41Sopenharmony_ci<span>Added in: v12.0.0</span> 7171cb0ef41Sopenharmony_ci</div> 7181cb0ef41Sopenharmony_ci<p>A synchronous function that disassociates a connected <code>dgram.Socket</code> from 7191cb0ef41Sopenharmony_ciits remote address. Trying to call <code>disconnect()</code> on an unbound or already 7201cb0ef41Sopenharmony_cidisconnected socket will result in an <a href="errors.html#err_socket_dgram_not_connected"><code>ERR_SOCKET_DGRAM_NOT_CONNECTED</code></a> 7211cb0ef41Sopenharmony_ciexception.</p> 7221cb0ef41Sopenharmony_ci<h4><code>socket.dropMembership(multicastAddress[, multicastInterface])</code><span><a class="mark" href="#socketdropmembershipmulticastaddress-multicastinterface" id="socketdropmembershipmulticastaddress-multicastinterface">#</a></span><a aria-hidden="true" class="legacy" id="dgram_socket_dropmembership_multicastaddress_multicastinterface"></a></h4> 7231cb0ef41Sopenharmony_ci<div class="api_metadata"> 7241cb0ef41Sopenharmony_ci<span>Added in: v0.6.9</span> 7251cb0ef41Sopenharmony_ci</div> 7261cb0ef41Sopenharmony_ci<ul> 7271cb0ef41Sopenharmony_ci<li><code>multicastAddress</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 7281cb0ef41Sopenharmony_ci<li><code>multicastInterface</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 7291cb0ef41Sopenharmony_ci</ul> 7301cb0ef41Sopenharmony_ci<p>Instructs the kernel to leave a multicast group at <code>multicastAddress</code> using the 7311cb0ef41Sopenharmony_ci<code>IP_DROP_MEMBERSHIP</code> socket option. This method is automatically called by the 7321cb0ef41Sopenharmony_cikernel when the socket is closed or the process terminates, so most apps will 7331cb0ef41Sopenharmony_cinever have reason to call this.</p> 7341cb0ef41Sopenharmony_ci<p>If <code>multicastInterface</code> is not specified, the operating system will attempt to 7351cb0ef41Sopenharmony_cidrop membership on all valid interfaces.</p> 7361cb0ef41Sopenharmony_ci<h4><code>socket.dropSourceSpecificMembership(sourceAddress, groupAddress[, multicastInterface])</code><span><a class="mark" href="#socketdropsourcespecificmembershipsourceaddress-groupaddress-multicastinterface" id="socketdropsourcespecificmembershipsourceaddress-groupaddress-multicastinterface">#</a></span><a aria-hidden="true" class="legacy" id="dgram_socket_dropsourcespecificmembership_sourceaddress_groupaddress_multicastinterface"></a></h4> 7371cb0ef41Sopenharmony_ci<div class="api_metadata"> 7381cb0ef41Sopenharmony_ci<span>Added in: v13.1.0, v12.16.0</span> 7391cb0ef41Sopenharmony_ci</div> 7401cb0ef41Sopenharmony_ci<ul> 7411cb0ef41Sopenharmony_ci<li><code>sourceAddress</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 7421cb0ef41Sopenharmony_ci<li><code>groupAddress</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 7431cb0ef41Sopenharmony_ci<li><code>multicastInterface</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 7441cb0ef41Sopenharmony_ci</ul> 7451cb0ef41Sopenharmony_ci<p>Instructs the kernel to leave a source-specific multicast channel at the given 7461cb0ef41Sopenharmony_ci<code>sourceAddress</code> and <code>groupAddress</code> using the <code>IP_DROP_SOURCE_MEMBERSHIP</code> 7471cb0ef41Sopenharmony_cisocket option. This method is automatically called by the kernel when the 7481cb0ef41Sopenharmony_cisocket is closed or the process terminates, so most apps will never have 7491cb0ef41Sopenharmony_cireason to call this.</p> 7501cb0ef41Sopenharmony_ci<p>If <code>multicastInterface</code> is not specified, the operating system will attempt to 7511cb0ef41Sopenharmony_cidrop membership on all valid interfaces.</p> 7521cb0ef41Sopenharmony_ci<h4><code>socket.getRecvBufferSize()</code><span><a class="mark" href="#socketgetrecvbuffersize" id="socketgetrecvbuffersize">#</a></span><a aria-hidden="true" class="legacy" id="dgram_socket_getrecvbuffersize"></a></h4> 7531cb0ef41Sopenharmony_ci<div class="api_metadata"> 7541cb0ef41Sopenharmony_ci<span>Added in: v8.7.0</span> 7551cb0ef41Sopenharmony_ci</div> 7561cb0ef41Sopenharmony_ci<ul> 7571cb0ef41Sopenharmony_ci<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> 7581cb0ef41Sopenharmony_ci</ul> 7591cb0ef41Sopenharmony_ci<p>This method throws <a href="errors.html#err_socket_buffer_size"><code>ERR_SOCKET_BUFFER_SIZE</code></a> if called on an unbound socket.</p> 7601cb0ef41Sopenharmony_ci<h4><code>socket.getSendBufferSize()</code><span><a class="mark" href="#socketgetsendbuffersize" id="socketgetsendbuffersize">#</a></span><a aria-hidden="true" class="legacy" id="dgram_socket_getsendbuffersize"></a></h4> 7611cb0ef41Sopenharmony_ci<div class="api_metadata"> 7621cb0ef41Sopenharmony_ci<span>Added in: v8.7.0</span> 7631cb0ef41Sopenharmony_ci</div> 7641cb0ef41Sopenharmony_ci<ul> 7651cb0ef41Sopenharmony_ci<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> 7661cb0ef41Sopenharmony_ci</ul> 7671cb0ef41Sopenharmony_ci<p>This method throws <a href="errors.html#err_socket_buffer_size"><code>ERR_SOCKET_BUFFER_SIZE</code></a> if called on an unbound socket.</p> 7681cb0ef41Sopenharmony_ci<h4><code>socket.getSendQueueSize()</code><span><a class="mark" href="#socketgetsendqueuesize" id="socketgetsendqueuesize">#</a></span><a aria-hidden="true" class="legacy" id="dgram_socket_getsendqueuesize"></a></h4> 7691cb0ef41Sopenharmony_ci<div class="api_metadata"> 7701cb0ef41Sopenharmony_ci<span>Added in: v18.8.0</span> 7711cb0ef41Sopenharmony_ci</div> 7721cb0ef41Sopenharmony_ci<ul> 7731cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Number of bytes queued for sending.</li> 7741cb0ef41Sopenharmony_ci</ul> 7751cb0ef41Sopenharmony_ci<h4><code>socket.getSendQueueCount()</code><span><a class="mark" href="#socketgetsendqueuecount" id="socketgetsendqueuecount">#</a></span><a aria-hidden="true" class="legacy" id="dgram_socket_getsendqueuecount"></a></h4> 7761cb0ef41Sopenharmony_ci<div class="api_metadata"> 7771cb0ef41Sopenharmony_ci<span>Added in: v18.8.0</span> 7781cb0ef41Sopenharmony_ci</div> 7791cb0ef41Sopenharmony_ci<ul> 7801cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Number of send requests currently in the queue awaiting 7811cb0ef41Sopenharmony_cito be processed.</li> 7821cb0ef41Sopenharmony_ci</ul> 7831cb0ef41Sopenharmony_ci<h4><code>socket.ref()</code><span><a class="mark" href="#socketref" id="socketref">#</a></span><a aria-hidden="true" class="legacy" id="dgram_socket_ref"></a></h4> 7841cb0ef41Sopenharmony_ci<div class="api_metadata"> 7851cb0ef41Sopenharmony_ci<span>Added in: v0.9.1</span> 7861cb0ef41Sopenharmony_ci</div> 7871cb0ef41Sopenharmony_ci<ul> 7881cb0ef41Sopenharmony_ci<li>Returns: <a href="dgram.html#class-dgramsocket" class="type"><dgram.Socket></a></li> 7891cb0ef41Sopenharmony_ci</ul> 7901cb0ef41Sopenharmony_ci<p>By default, binding a socket will cause it to block the Node.js process from 7911cb0ef41Sopenharmony_ciexiting as long as the socket is open. The <code>socket.unref()</code> method can be used 7921cb0ef41Sopenharmony_cito exclude the socket from the reference counting that keeps the Node.js 7931cb0ef41Sopenharmony_ciprocess active. The <code>socket.ref()</code> method adds the socket back to the reference 7941cb0ef41Sopenharmony_cicounting and restores the default behavior.</p> 7951cb0ef41Sopenharmony_ci<p>Calling <code>socket.ref()</code> multiples times will have no additional effect.</p> 7961cb0ef41Sopenharmony_ci<p>The <code>socket.ref()</code> method returns a reference to the socket so calls can be 7971cb0ef41Sopenharmony_cichained.</p> 7981cb0ef41Sopenharmony_ci<h4><code>socket.remoteAddress()</code><span><a class="mark" href="#socketremoteaddress" id="socketremoteaddress">#</a></span><a aria-hidden="true" class="legacy" id="dgram_socket_remoteaddress"></a></h4> 7991cb0ef41Sopenharmony_ci<div class="api_metadata"> 8001cb0ef41Sopenharmony_ci<span>Added in: v12.0.0</span> 8011cb0ef41Sopenharmony_ci</div> 8021cb0ef41Sopenharmony_ci<ul> 8031cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a></li> 8041cb0ef41Sopenharmony_ci</ul> 8051cb0ef41Sopenharmony_ci<p>Returns an object containing the <code>address</code>, <code>family</code>, and <code>port</code> of the remote 8061cb0ef41Sopenharmony_ciendpoint. This method throws an <a href="errors.html#err_socket_dgram_not_connected"><code>ERR_SOCKET_DGRAM_NOT_CONNECTED</code></a> exception 8071cb0ef41Sopenharmony_ciif the socket is not connected.</p> 8081cb0ef41Sopenharmony_ci<h4><code>socket.send(msg[, offset, length][, port][, address][, callback])</code><span><a class="mark" href="#socketsendmsg-offset-length-port-address-callback" id="socketsendmsg-offset-length-port-address-callback">#</a></span><a aria-hidden="true" class="legacy" id="dgram_socket_send_msg_offset_length_port_address_callback"></a></h4> 8091cb0ef41Sopenharmony_ci<div class="api_metadata"> 8101cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 8111cb0ef41Sopenharmony_ci<table> 8121cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 8131cb0ef41Sopenharmony_ci<tr><td>v17.0.0</td> 8141cb0ef41Sopenharmony_ci<td><p>The <code>address</code> parameter now only accepts a <code>string</code>, <code>null</code> or <code>undefined</code>.</p></td></tr> 8151cb0ef41Sopenharmony_ci<tr><td>v14.5.0, v12.19.0</td> 8161cb0ef41Sopenharmony_ci<td><p>The <code>msg</code> parameter can now be any <code>TypedArray</code> or <code>DataView</code>.</p></td></tr> 8171cb0ef41Sopenharmony_ci<tr><td>v12.0.0</td> 8181cb0ef41Sopenharmony_ci<td><p>Added support for sending data on connected sockets.</p></td></tr> 8191cb0ef41Sopenharmony_ci<tr><td>v8.0.0</td> 8201cb0ef41Sopenharmony_ci<td><p>The <code>msg</code> parameter can be an <code>Uint8Array</code> now.</p></td></tr> 8211cb0ef41Sopenharmony_ci<tr><td>v8.0.0</td> 8221cb0ef41Sopenharmony_ci<td><p>The <code>address</code> parameter is always optional now.</p></td></tr> 8231cb0ef41Sopenharmony_ci<tr><td>v6.0.0</td> 8241cb0ef41Sopenharmony_ci<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> 8251cb0ef41Sopenharmony_ci<tr><td>v5.7.0</td> 8261cb0ef41Sopenharmony_ci<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> 8271cb0ef41Sopenharmony_ci<tr><td>v0.1.99</td> 8281cb0ef41Sopenharmony_ci<td><p><span>Added in: v0.1.99</span></p></td></tr> 8291cb0ef41Sopenharmony_ci</tbody></table> 8301cb0ef41Sopenharmony_ci</details> 8311cb0ef41Sopenharmony_ci</div> 8321cb0ef41Sopenharmony_ci<ul> 8331cb0ef41Sopenharmony_ci<li><code>msg</code> <a href="buffer.html#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> 8341cb0ef41Sopenharmony_ci<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> 8351cb0ef41Sopenharmony_ci<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> 8361cb0ef41Sopenharmony_ci<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> 8371cb0ef41Sopenharmony_ci<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> 8381cb0ef41Sopenharmony_ci<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> 8391cb0ef41Sopenharmony_ci</ul> 8401cb0ef41Sopenharmony_ci<p>Broadcasts a datagram on the socket. 8411cb0ef41Sopenharmony_ciFor connectionless sockets, the destination <code>port</code> and <code>address</code> must be 8421cb0ef41Sopenharmony_cispecified. Connected sockets, on the other hand, will use their associated 8431cb0ef41Sopenharmony_ciremote endpoint, so the <code>port</code> and <code>address</code> arguments must not be set.</p> 8441cb0ef41Sopenharmony_ci<p>The <code>msg</code> argument contains the message to be sent. 8451cb0ef41Sopenharmony_ciDepending on its type, different behavior can apply. If <code>msg</code> is a <code>Buffer</code>, 8461cb0ef41Sopenharmony_ciany <code>TypedArray</code> or a <code>DataView</code>, 8471cb0ef41Sopenharmony_cithe <code>offset</code> and <code>length</code> specify the offset within the <code>Buffer</code> where the 8481cb0ef41Sopenharmony_cimessage begins and the number of bytes in the message, respectively. 8491cb0ef41Sopenharmony_ciIf <code>msg</code> is a <code>String</code>, then it is automatically converted to a <code>Buffer</code> 8501cb0ef41Sopenharmony_ciwith <code>'utf8'</code> encoding. With messages that 8511cb0ef41Sopenharmony_cicontain multi-byte characters, <code>offset</code> and <code>length</code> will be calculated with 8521cb0ef41Sopenharmony_cirespect to <a href="buffer.html#static-method-bufferbytelengthstring-encoding">byte length</a> and not the character position. 8531cb0ef41Sopenharmony_ciIf <code>msg</code> is an array, <code>offset</code> and <code>length</code> must not be specified.</p> 8541cb0ef41Sopenharmony_ci<p>The <code>address</code> argument is a string. If the value of <code>address</code> is a host name, 8551cb0ef41Sopenharmony_ciDNS will be used to resolve the address of the host. If <code>address</code> is not 8561cb0ef41Sopenharmony_ciprovided or otherwise nullish, <code>'127.0.0.1'</code> (for <code>udp4</code> sockets) or <code>'::1'</code> 8571cb0ef41Sopenharmony_ci(for <code>udp6</code> sockets) will be used by default.</p> 8581cb0ef41Sopenharmony_ci<p>If the socket has not been previously bound with a call to <code>bind</code>, the socket 8591cb0ef41Sopenharmony_ciis assigned a random port number and is bound to the "all interfaces" address 8601cb0ef41Sopenharmony_ci(<code>'0.0.0.0'</code> for <code>udp4</code> sockets, <code>'::0'</code> for <code>udp6</code> sockets.)</p> 8611cb0ef41Sopenharmony_ci<p>An optional <code>callback</code> function may be specified to as a way of reporting 8621cb0ef41Sopenharmony_ciDNS errors or for determining when it is safe to reuse the <code>buf</code> object. 8631cb0ef41Sopenharmony_ciDNS lookups delay the time to send for at least one tick of the 8641cb0ef41Sopenharmony_ciNode.js event loop.</p> 8651cb0ef41Sopenharmony_ci<p>The only way to know for sure that the datagram has been sent is by using a 8661cb0ef41Sopenharmony_ci<code>callback</code>. If an error occurs and a <code>callback</code> is given, the error will be 8671cb0ef41Sopenharmony_cipassed as the first argument to the <code>callback</code>. If a <code>callback</code> is not given, 8681cb0ef41Sopenharmony_cithe error is emitted as an <code>'error'</code> event on the <code>socket</code> object.</p> 8691cb0ef41Sopenharmony_ci<p>Offset and length are optional but both <em>must</em> be set if either are used. 8701cb0ef41Sopenharmony_ciThey are supported only when the first argument is a <code>Buffer</code>, a <code>TypedArray</code>, 8711cb0ef41Sopenharmony_cior a <code>DataView</code>.</p> 8721cb0ef41Sopenharmony_ci<p>This method throws <a href="errors.html#err_socket_bad_port"><code>ERR_SOCKET_BAD_PORT</code></a> if called on an unbound socket.</p> 8731cb0ef41Sopenharmony_ci<p>Example of sending a UDP packet to a port on <code>localhost</code>;</p> 8741cb0ef41Sopenharmony_ci 8751cb0ef41Sopenharmony_ci<pre class="with-42-chars"><input class="js-flavor-selector" type="checkbox" checked aria-label="Show modern ES modules syntax"><code class="language-js mjs"><span class="hljs-keyword">import</span> dgram <span class="hljs-keyword">from</span> <span class="hljs-string">'node:dgram'</span>; 8761cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> { <span class="hljs-title class_">Buffer</span> } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:buffer'</span>; 8771cb0ef41Sopenharmony_ci 8781cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> message = <span class="hljs-title class_">Buffer</span>.<span class="hljs-title function_">from</span>(<span class="hljs-string">'Some bytes'</span>); 8791cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> client = dgram.<span class="hljs-title function_">createSocket</span>(<span class="hljs-string">'udp4'</span>); 8801cb0ef41Sopenharmony_ciclient.<span class="hljs-title function_">send</span>(message, <span class="hljs-number">41234</span>, <span class="hljs-string">'localhost'</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 8811cb0ef41Sopenharmony_ci client.<span class="hljs-title function_">close</span>(); 8821cb0ef41Sopenharmony_ci});</code><code class="language-js cjs"><span class="hljs-keyword">const</span> dgram = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:dgram'</span>); 8831cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> { <span class="hljs-title class_">Buffer</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:buffer'</span>); 8841cb0ef41Sopenharmony_ci 8851cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> message = <span class="hljs-title class_">Buffer</span>.<span class="hljs-title function_">from</span>(<span class="hljs-string">'Some bytes'</span>); 8861cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> client = dgram.<span class="hljs-title function_">createSocket</span>(<span class="hljs-string">'udp4'</span>); 8871cb0ef41Sopenharmony_ciclient.<span class="hljs-title function_">send</span>(message, <span class="hljs-number">41234</span>, <span class="hljs-string">'localhost'</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 8881cb0ef41Sopenharmony_ci client.<span class="hljs-title function_">close</span>(); 8891cb0ef41Sopenharmony_ci});</code><button class="copy-button">copy</button></pre> 8901cb0ef41Sopenharmony_ci<p>Example of sending a UDP packet composed of multiple buffers to a port on 8911cb0ef41Sopenharmony_ci<code>127.0.0.1</code>;</p> 8921cb0ef41Sopenharmony_ci 8931cb0ef41Sopenharmony_ci<pre class="with-42-chars"><input class="js-flavor-selector" type="checkbox" checked aria-label="Show modern ES modules syntax"><code class="language-js mjs"><span class="hljs-keyword">import</span> dgram <span class="hljs-keyword">from</span> <span class="hljs-string">'node:dgram'</span>; 8941cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> { <span class="hljs-title class_">Buffer</span> } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:buffer'</span>; 8951cb0ef41Sopenharmony_ci 8961cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> buf1 = <span class="hljs-title class_">Buffer</span>.<span class="hljs-title function_">from</span>(<span class="hljs-string">'Some '</span>); 8971cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> buf2 = <span class="hljs-title class_">Buffer</span>.<span class="hljs-title function_">from</span>(<span class="hljs-string">'bytes'</span>); 8981cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> client = dgram.<span class="hljs-title function_">createSocket</span>(<span class="hljs-string">'udp4'</span>); 8991cb0ef41Sopenharmony_ciclient.<span class="hljs-title function_">send</span>([buf1, buf2], <span class="hljs-number">41234</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 9001cb0ef41Sopenharmony_ci client.<span class="hljs-title function_">close</span>(); 9011cb0ef41Sopenharmony_ci});</code><code class="language-js cjs"><span class="hljs-keyword">const</span> dgram = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:dgram'</span>); 9021cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> { <span class="hljs-title class_">Buffer</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:buffer'</span>); 9031cb0ef41Sopenharmony_ci 9041cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> buf1 = <span class="hljs-title class_">Buffer</span>.<span class="hljs-title function_">from</span>(<span class="hljs-string">'Some '</span>); 9051cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> buf2 = <span class="hljs-title class_">Buffer</span>.<span class="hljs-title function_">from</span>(<span class="hljs-string">'bytes'</span>); 9061cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> client = dgram.<span class="hljs-title function_">createSocket</span>(<span class="hljs-string">'udp4'</span>); 9071cb0ef41Sopenharmony_ciclient.<span class="hljs-title function_">send</span>([buf1, buf2], <span class="hljs-number">41234</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 9081cb0ef41Sopenharmony_ci client.<span class="hljs-title function_">close</span>(); 9091cb0ef41Sopenharmony_ci});</code><button class="copy-button">copy</button></pre> 9101cb0ef41Sopenharmony_ci<p>Sending multiple buffers might be faster or slower depending on the 9111cb0ef41Sopenharmony_ciapplication and operating system. Run benchmarks to 9121cb0ef41Sopenharmony_cidetermine the optimal strategy on a case-by-case basis. Generally speaking, 9131cb0ef41Sopenharmony_cihowever, sending multiple buffers is faster.</p> 9141cb0ef41Sopenharmony_ci<p>Example of sending a UDP packet using a socket connected to a port on 9151cb0ef41Sopenharmony_ci<code>localhost</code>:</p> 9161cb0ef41Sopenharmony_ci 9171cb0ef41Sopenharmony_ci<pre class="with-42-chars"><input class="js-flavor-selector" type="checkbox" checked aria-label="Show modern ES modules syntax"><code class="language-js mjs"><span class="hljs-keyword">import</span> dgram <span class="hljs-keyword">from</span> <span class="hljs-string">'node:dgram'</span>; 9181cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> { <span class="hljs-title class_">Buffer</span> } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:buffer'</span>; 9191cb0ef41Sopenharmony_ci 9201cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> message = <span class="hljs-title class_">Buffer</span>.<span class="hljs-title function_">from</span>(<span class="hljs-string">'Some bytes'</span>); 9211cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> client = dgram.<span class="hljs-title function_">createSocket</span>(<span class="hljs-string">'udp4'</span>); 9221cb0ef41Sopenharmony_ciclient.<span class="hljs-title function_">connect</span>(<span class="hljs-number">41234</span>, <span class="hljs-string">'localhost'</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 9231cb0ef41Sopenharmony_ci client.<span class="hljs-title function_">send</span>(message, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 9241cb0ef41Sopenharmony_ci client.<span class="hljs-title function_">close</span>(); 9251cb0ef41Sopenharmony_ci }); 9261cb0ef41Sopenharmony_ci});</code><code class="language-js cjs"><span class="hljs-keyword">const</span> dgram = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:dgram'</span>); 9271cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> { <span class="hljs-title class_">Buffer</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:buffer'</span>); 9281cb0ef41Sopenharmony_ci 9291cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> message = <span class="hljs-title class_">Buffer</span>.<span class="hljs-title function_">from</span>(<span class="hljs-string">'Some bytes'</span>); 9301cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> client = dgram.<span class="hljs-title function_">createSocket</span>(<span class="hljs-string">'udp4'</span>); 9311cb0ef41Sopenharmony_ciclient.<span class="hljs-title function_">connect</span>(<span class="hljs-number">41234</span>, <span class="hljs-string">'localhost'</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 9321cb0ef41Sopenharmony_ci client.<span class="hljs-title function_">send</span>(message, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 9331cb0ef41Sopenharmony_ci client.<span class="hljs-title function_">close</span>(); 9341cb0ef41Sopenharmony_ci }); 9351cb0ef41Sopenharmony_ci});</code><button class="copy-button">copy</button></pre> 9361cb0ef41Sopenharmony_ci<h5>Note about UDP datagram size<span><a class="mark" href="#note-about-udp-datagram-size" id="note-about-udp-datagram-size">#</a></span><a aria-hidden="true" class="legacy" id="dgram_note_about_udp_datagram_size"></a></h5> 9371cb0ef41Sopenharmony_ci<p>The maximum size of an IPv4/v6 datagram depends on the <code>MTU</code> 9381cb0ef41Sopenharmony_ci(Maximum Transmission Unit) and on the <code>Payload Length</code> field size.</p> 9391cb0ef41Sopenharmony_ci<ul> 9401cb0ef41Sopenharmony_ci<li> 9411cb0ef41Sopenharmony_ci<p>The <code>Payload Length</code> field is 16 bits wide, which means that a normal 9421cb0ef41Sopenharmony_cipayload cannot exceed 64K octets including the internet header and data 9431cb0ef41Sopenharmony_ci(65,507 bytes = 65,535 − 8 bytes UDP header − 20 bytes IP header); 9441cb0ef41Sopenharmony_cithis is generally true for loopback interfaces, but such long datagram 9451cb0ef41Sopenharmony_cimessages are impractical for most hosts and networks.</p> 9461cb0ef41Sopenharmony_ci</li> 9471cb0ef41Sopenharmony_ci<li> 9481cb0ef41Sopenharmony_ci<p>The <code>MTU</code> is the largest size a given link layer technology can support for 9491cb0ef41Sopenharmony_cidatagram messages. For any link, IPv4 mandates a minimum <code>MTU</code> of 68 9501cb0ef41Sopenharmony_cioctets, while the recommended <code>MTU</code> for IPv4 is 576 (typically recommended 9511cb0ef41Sopenharmony_cias the <code>MTU</code> for dial-up type applications), whether they arrive whole or in 9521cb0ef41Sopenharmony_cifragments.</p> 9531cb0ef41Sopenharmony_ci<p>For IPv6, the minimum <code>MTU</code> is 1280 octets. However, the mandatory minimum 9541cb0ef41Sopenharmony_cifragment reassembly buffer size is 1500 octets. The value of 68 octets is 9551cb0ef41Sopenharmony_civery small, since most current link layer technologies, like Ethernet, have a 9561cb0ef41Sopenharmony_ciminimum <code>MTU</code> of 1500.</p> 9571cb0ef41Sopenharmony_ci</li> 9581cb0ef41Sopenharmony_ci</ul> 9591cb0ef41Sopenharmony_ci<p>It is impossible to know in advance the MTU of each link through which 9601cb0ef41Sopenharmony_cia packet might travel. Sending a datagram greater than the receiver <code>MTU</code> will 9611cb0ef41Sopenharmony_cinot work because the packet will get silently dropped without informing the 9621cb0ef41Sopenharmony_cisource that the data did not reach its intended recipient.</p> 9631cb0ef41Sopenharmony_ci<h4><code>socket.setBroadcast(flag)</code><span><a class="mark" href="#socketsetbroadcastflag" id="socketsetbroadcastflag">#</a></span><a aria-hidden="true" class="legacy" id="dgram_socket_setbroadcast_flag"></a></h4> 9641cb0ef41Sopenharmony_ci<div class="api_metadata"> 9651cb0ef41Sopenharmony_ci<span>Added in: v0.6.9</span> 9661cb0ef41Sopenharmony_ci</div> 9671cb0ef41Sopenharmony_ci<ul> 9681cb0ef41Sopenharmony_ci<li><code>flag</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 9691cb0ef41Sopenharmony_ci</ul> 9701cb0ef41Sopenharmony_ci<p>Sets or clears the <code>SO_BROADCAST</code> socket option. When set to <code>true</code>, UDP 9711cb0ef41Sopenharmony_cipackets may be sent to a local interface's broadcast address.</p> 9721cb0ef41Sopenharmony_ci<p>This method throws <code>EBADF</code> if called on an unbound socket.</p> 9731cb0ef41Sopenharmony_ci<h4><code>socket.setMulticastInterface(multicastInterface)</code><span><a class="mark" href="#socketsetmulticastinterfacemulticastinterface" id="socketsetmulticastinterfacemulticastinterface">#</a></span><a aria-hidden="true" class="legacy" id="dgram_socket_setmulticastinterface_multicastinterface"></a></h4> 9741cb0ef41Sopenharmony_ci<div class="api_metadata"> 9751cb0ef41Sopenharmony_ci<span>Added in: v8.6.0</span> 9761cb0ef41Sopenharmony_ci</div> 9771cb0ef41Sopenharmony_ci<ul> 9781cb0ef41Sopenharmony_ci<li><code>multicastInterface</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 9791cb0ef41Sopenharmony_ci</ul> 9801cb0ef41Sopenharmony_ci<p><em>All references to scope in this section are referring to 9811cb0ef41Sopenharmony_ci<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 9821cb0ef41Sopenharmony_ciwith a scope index is written as <code>'IP%scope'</code> where scope is an interface name 9831cb0ef41Sopenharmony_cior interface number.</em></p> 9841cb0ef41Sopenharmony_ci<p>Sets the default outgoing multicast interface of the socket to a chosen 9851cb0ef41Sopenharmony_ciinterface or back to system interface selection. The <code>multicastInterface</code> must 9861cb0ef41Sopenharmony_cibe a valid string representation of an IP from the socket's family.</p> 9871cb0ef41Sopenharmony_ci<p>For IPv4 sockets, this should be the IP configured for the desired physical 9881cb0ef41Sopenharmony_ciinterface. All packets sent to multicast on the socket will be sent on the 9891cb0ef41Sopenharmony_ciinterface determined by the most recent successful use of this call.</p> 9901cb0ef41Sopenharmony_ci<p>For IPv6 sockets, <code>multicastInterface</code> should include a scope to indicate the 9911cb0ef41Sopenharmony_ciinterface as in the examples that follow. In IPv6, individual <code>send</code> calls can 9921cb0ef41Sopenharmony_cialso use explicit scope in addresses, so only packets sent to a multicast 9931cb0ef41Sopenharmony_ciaddress without specifying an explicit scope are affected by the most recent 9941cb0ef41Sopenharmony_cisuccessful use of this call.</p> 9951cb0ef41Sopenharmony_ci<p>This method throws <code>EBADF</code> if called on an unbound socket.</p> 9961cb0ef41Sopenharmony_ci<h5>Example: IPv6 outgoing multicast interface<span><a class="mark" href="#example-ipv6-outgoing-multicast-interface" id="example-ipv6-outgoing-multicast-interface">#</a></span><a aria-hidden="true" class="legacy" id="dgram_example_ipv6_outgoing_multicast_interface"></a></h5> 9971cb0ef41Sopenharmony_ci<p>On most systems, where scope format uses the interface name:</p> 9981cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> socket = dgram.<span class="hljs-title function_">createSocket</span>(<span class="hljs-string">'udp6'</span>); 9991cb0ef41Sopenharmony_ci 10001cb0ef41Sopenharmony_cisocket.<span class="hljs-title function_">bind</span>(<span class="hljs-number">1234</span>, <span class="hljs-function">() =></span> { 10011cb0ef41Sopenharmony_ci socket.<span class="hljs-title function_">setMulticastInterface</span>(<span class="hljs-string">'::%eth1'</span>); 10021cb0ef41Sopenharmony_ci});</code> <button class="copy-button">copy</button></pre> 10031cb0ef41Sopenharmony_ci<p>On Windows, where scope format uses an interface number:</p> 10041cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> socket = dgram.<span class="hljs-title function_">createSocket</span>(<span class="hljs-string">'udp6'</span>); 10051cb0ef41Sopenharmony_ci 10061cb0ef41Sopenharmony_cisocket.<span class="hljs-title function_">bind</span>(<span class="hljs-number">1234</span>, <span class="hljs-function">() =></span> { 10071cb0ef41Sopenharmony_ci socket.<span class="hljs-title function_">setMulticastInterface</span>(<span class="hljs-string">'::%2'</span>); 10081cb0ef41Sopenharmony_ci});</code> <button class="copy-button">copy</button></pre> 10091cb0ef41Sopenharmony_ci<h5>Example: IPv4 outgoing multicast interface<span><a class="mark" href="#example-ipv4-outgoing-multicast-interface" id="example-ipv4-outgoing-multicast-interface">#</a></span><a aria-hidden="true" class="legacy" id="dgram_example_ipv4_outgoing_multicast_interface"></a></h5> 10101cb0ef41Sopenharmony_ci<p>All systems use an IP of the host on the desired physical interface:</p> 10111cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> socket = dgram.<span class="hljs-title function_">createSocket</span>(<span class="hljs-string">'udp4'</span>); 10121cb0ef41Sopenharmony_ci 10131cb0ef41Sopenharmony_cisocket.<span class="hljs-title function_">bind</span>(<span class="hljs-number">1234</span>, <span class="hljs-function">() =></span> { 10141cb0ef41Sopenharmony_ci socket.<span class="hljs-title function_">setMulticastInterface</span>(<span class="hljs-string">'10.0.0.2'</span>); 10151cb0ef41Sopenharmony_ci});</code> <button class="copy-button">copy</button></pre> 10161cb0ef41Sopenharmony_ci<h5>Call results<span><a class="mark" href="#call-results" id="call-results">#</a></span><a aria-hidden="true" class="legacy" id="dgram_call_results"></a></h5> 10171cb0ef41Sopenharmony_ci<p>A call on a socket that is not ready to send or no longer open may throw a <em>Not 10181cb0ef41Sopenharmony_cirunning</em> <a href="errors.html#class-error"><code>Error</code></a>.</p> 10191cb0ef41Sopenharmony_ci<p>If <code>multicastInterface</code> can not be parsed into an IP then an <em>EINVAL</em> 10201cb0ef41Sopenharmony_ci<a href="errors.html#class-systemerror"><code>System Error</code></a> is thrown.</p> 10211cb0ef41Sopenharmony_ci<p>On IPv4, if <code>multicastInterface</code> is a valid address but does not match any 10221cb0ef41Sopenharmony_ciinterface, or if the address does not match the family then 10231cb0ef41Sopenharmony_cia <a href="errors.html#class-systemerror"><code>System Error</code></a> such as <code>EADDRNOTAVAIL</code> or <code>EPROTONOSUP</code> is thrown.</p> 10241cb0ef41Sopenharmony_ci<p>On IPv6, most errors with specifying or omitting scope will result in the socket 10251cb0ef41Sopenharmony_cicontinuing to use (or returning to) the system's default interface selection.</p> 10261cb0ef41Sopenharmony_ci<p>A socket's address family's ANY address (IPv4 <code>'0.0.0.0'</code> or IPv6 <code>'::'</code>) can be 10271cb0ef41Sopenharmony_ciused to return control of the sockets default outgoing interface to the system 10281cb0ef41Sopenharmony_cifor future multicast packets.</p> 10291cb0ef41Sopenharmony_ci<h4><code>socket.setMulticastLoopback(flag)</code><span><a class="mark" href="#socketsetmulticastloopbackflag" id="socketsetmulticastloopbackflag">#</a></span><a aria-hidden="true" class="legacy" id="dgram_socket_setmulticastloopback_flag"></a></h4> 10301cb0ef41Sopenharmony_ci<div class="api_metadata"> 10311cb0ef41Sopenharmony_ci<span>Added in: v0.3.8</span> 10321cb0ef41Sopenharmony_ci</div> 10331cb0ef41Sopenharmony_ci<ul> 10341cb0ef41Sopenharmony_ci<li><code>flag</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 10351cb0ef41Sopenharmony_ci</ul> 10361cb0ef41Sopenharmony_ci<p>Sets or clears the <code>IP_MULTICAST_LOOP</code> socket option. When set to <code>true</code>, 10371cb0ef41Sopenharmony_cimulticast packets will also be received on the local interface.</p> 10381cb0ef41Sopenharmony_ci<p>This method throws <code>EBADF</code> if called on an unbound socket.</p> 10391cb0ef41Sopenharmony_ci<h4><code>socket.setMulticastTTL(ttl)</code><span><a class="mark" href="#socketsetmulticastttlttl" id="socketsetmulticastttlttl">#</a></span><a aria-hidden="true" class="legacy" id="dgram_socket_setmulticastttl_ttl"></a></h4> 10401cb0ef41Sopenharmony_ci<div class="api_metadata"> 10411cb0ef41Sopenharmony_ci<span>Added in: v0.3.8</span> 10421cb0ef41Sopenharmony_ci</div> 10431cb0ef41Sopenharmony_ci<ul> 10441cb0ef41Sopenharmony_ci<li><code>ttl</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 10451cb0ef41Sopenharmony_ci</ul> 10461cb0ef41Sopenharmony_ci<p>Sets the <code>IP_MULTICAST_TTL</code> socket option. While TTL generally stands for 10471cb0ef41Sopenharmony_ci"Time to Live", in this context it specifies the number of IP hops that a 10481cb0ef41Sopenharmony_cipacket is allowed to travel through, specifically for multicast traffic. Each 10491cb0ef41Sopenharmony_cirouter or gateway that forwards a packet decrements the TTL. If the TTL is 10501cb0ef41Sopenharmony_cidecremented to 0 by a router, it will not be forwarded.</p> 10511cb0ef41Sopenharmony_ci<p>The <code>ttl</code> argument may be between 0 and 255. The default on most systems is <code>1</code>.</p> 10521cb0ef41Sopenharmony_ci<p>This method throws <code>EBADF</code> if called on an unbound socket.</p> 10531cb0ef41Sopenharmony_ci<h4><code>socket.setRecvBufferSize(size)</code><span><a class="mark" href="#socketsetrecvbuffersizesize" id="socketsetrecvbuffersizesize">#</a></span><a aria-hidden="true" class="legacy" id="dgram_socket_setrecvbuffersize_size"></a></h4> 10541cb0ef41Sopenharmony_ci<div class="api_metadata"> 10551cb0ef41Sopenharmony_ci<span>Added in: v8.7.0</span> 10561cb0ef41Sopenharmony_ci</div> 10571cb0ef41Sopenharmony_ci<ul> 10581cb0ef41Sopenharmony_ci<li><code>size</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 10591cb0ef41Sopenharmony_ci</ul> 10601cb0ef41Sopenharmony_ci<p>Sets the <code>SO_RCVBUF</code> socket option. Sets the maximum socket receive buffer 10611cb0ef41Sopenharmony_ciin bytes.</p> 10621cb0ef41Sopenharmony_ci<p>This method throws <a href="errors.html#err_socket_buffer_size"><code>ERR_SOCKET_BUFFER_SIZE</code></a> if called on an unbound socket.</p> 10631cb0ef41Sopenharmony_ci<h4><code>socket.setSendBufferSize(size)</code><span><a class="mark" href="#socketsetsendbuffersizesize" id="socketsetsendbuffersizesize">#</a></span><a aria-hidden="true" class="legacy" id="dgram_socket_setsendbuffersize_size"></a></h4> 10641cb0ef41Sopenharmony_ci<div class="api_metadata"> 10651cb0ef41Sopenharmony_ci<span>Added in: v8.7.0</span> 10661cb0ef41Sopenharmony_ci</div> 10671cb0ef41Sopenharmony_ci<ul> 10681cb0ef41Sopenharmony_ci<li><code>size</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 10691cb0ef41Sopenharmony_ci</ul> 10701cb0ef41Sopenharmony_ci<p>Sets the <code>SO_SNDBUF</code> socket option. Sets the maximum socket send buffer 10711cb0ef41Sopenharmony_ciin bytes.</p> 10721cb0ef41Sopenharmony_ci<p>This method throws <a href="errors.html#err_socket_buffer_size"><code>ERR_SOCKET_BUFFER_SIZE</code></a> if called on an unbound socket.</p> 10731cb0ef41Sopenharmony_ci<h4><code>socket.setTTL(ttl)</code><span><a class="mark" href="#socketsetttlttl" id="socketsetttlttl">#</a></span><a aria-hidden="true" class="legacy" id="dgram_socket_setttl_ttl"></a></h4> 10741cb0ef41Sopenharmony_ci<div class="api_metadata"> 10751cb0ef41Sopenharmony_ci<span>Added in: v0.1.101</span> 10761cb0ef41Sopenharmony_ci</div> 10771cb0ef41Sopenharmony_ci<ul> 10781cb0ef41Sopenharmony_ci<li><code>ttl</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 10791cb0ef41Sopenharmony_ci</ul> 10801cb0ef41Sopenharmony_ci<p>Sets the <code>IP_TTL</code> socket option. While TTL generally stands for "Time to Live", 10811cb0ef41Sopenharmony_ciin this context it specifies the number of IP hops that a packet is allowed to 10821cb0ef41Sopenharmony_citravel through. Each router or gateway that forwards a packet decrements the 10831cb0ef41Sopenharmony_ciTTL. If the TTL is decremented to 0 by a router, it will not be forwarded. 10841cb0ef41Sopenharmony_ciChanging TTL values is typically done for network probes or when multicasting.</p> 10851cb0ef41Sopenharmony_ci<p>The <code>ttl</code> argument may be between 1 and 255. The default on most systems 10861cb0ef41Sopenharmony_ciis 64.</p> 10871cb0ef41Sopenharmony_ci<p>This method throws <code>EBADF</code> if called on an unbound socket.</p> 10881cb0ef41Sopenharmony_ci<h4><code>socket.unref()</code><span><a class="mark" href="#socketunref" id="socketunref">#</a></span><a aria-hidden="true" class="legacy" id="dgram_socket_unref"></a></h4> 10891cb0ef41Sopenharmony_ci<div class="api_metadata"> 10901cb0ef41Sopenharmony_ci<span>Added in: v0.9.1</span> 10911cb0ef41Sopenharmony_ci</div> 10921cb0ef41Sopenharmony_ci<ul> 10931cb0ef41Sopenharmony_ci<li>Returns: <a href="dgram.html#class-dgramsocket" class="type"><dgram.Socket></a></li> 10941cb0ef41Sopenharmony_ci</ul> 10951cb0ef41Sopenharmony_ci<p>By default, binding a socket will cause it to block the Node.js process from 10961cb0ef41Sopenharmony_ciexiting as long as the socket is open. The <code>socket.unref()</code> method can be used 10971cb0ef41Sopenharmony_cito exclude the socket from the reference counting that keeps the Node.js 10981cb0ef41Sopenharmony_ciprocess active, allowing the process to exit even if the socket is still 10991cb0ef41Sopenharmony_cilistening.</p> 11001cb0ef41Sopenharmony_ci<p>Calling <code>socket.unref()</code> multiple times will have no addition effect.</p> 11011cb0ef41Sopenharmony_ci<p>The <code>socket.unref()</code> method returns a reference to the socket so calls can be 11021cb0ef41Sopenharmony_cichained.</p> 11031cb0ef41Sopenharmony_ci</section><section><h3><code>node:dgram</code> module functions<span><a class="mark" href="#nodedgram-module-functions" id="nodedgram-module-functions">#</a></span><a aria-hidden="true" class="legacy" id="dgram_node_dgram_module_functions"></a></h3> 11041cb0ef41Sopenharmony_ci<h4><code>dgram.createSocket(options[, callback])</code><span><a class="mark" href="#dgramcreatesocketoptions-callback" id="dgramcreatesocketoptions-callback">#</a></span><a aria-hidden="true" class="legacy" id="dgram_dgram_createsocket_options_callback"></a></h4> 11051cb0ef41Sopenharmony_ci<div class="api_metadata"> 11061cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 11071cb0ef41Sopenharmony_ci<table> 11081cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 11091cb0ef41Sopenharmony_ci<tr><td>v15.8.0</td> 11101cb0ef41Sopenharmony_ci<td><p>AbortSignal support was added.</p></td></tr> 11111cb0ef41Sopenharmony_ci<tr><td>v11.4.0</td> 11121cb0ef41Sopenharmony_ci<td><p>The <code>ipv6Only</code> option is supported.</p></td></tr> 11131cb0ef41Sopenharmony_ci<tr><td>v8.7.0</td> 11141cb0ef41Sopenharmony_ci<td><p>The <code>recvBufferSize</code> and <code>sendBufferSize</code> options are supported now.</p></td></tr> 11151cb0ef41Sopenharmony_ci<tr><td>v8.6.0</td> 11161cb0ef41Sopenharmony_ci<td><p>The <code>lookup</code> option is supported.</p></td></tr> 11171cb0ef41Sopenharmony_ci<tr><td>v0.11.13</td> 11181cb0ef41Sopenharmony_ci<td><p><span>Added in: v0.11.13</span></p></td></tr> 11191cb0ef41Sopenharmony_ci</tbody></table> 11201cb0ef41Sopenharmony_ci</details> 11211cb0ef41Sopenharmony_ci</div> 11221cb0ef41Sopenharmony_ci<ul> 11231cb0ef41Sopenharmony_ci<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: 11241cb0ef41Sopenharmony_ci<ul> 11251cb0ef41Sopenharmony_ci<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>. 11261cb0ef41Sopenharmony_ciRequired.</li> 11271cb0ef41Sopenharmony_ci<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="#socketbindport-address-callback"><code>socket.bind()</code></a> will reuse the 11281cb0ef41Sopenharmony_ciaddress, even if another process has already bound a socket on it. 11291cb0ef41Sopenharmony_ci<strong>Default:</strong> <code>false</code>.</li> 11301cb0ef41Sopenharmony_ci<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 11311cb0ef41Sopenharmony_cidisable dual-stack support, i.e., binding to address <code>::</code> won't make 11321cb0ef41Sopenharmony_ci<code>0.0.0.0</code> be bound. <strong>Default:</strong> <code>false</code>.</li> 11331cb0ef41Sopenharmony_ci<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> 11341cb0ef41Sopenharmony_ci<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> 11351cb0ef41Sopenharmony_ci<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#dnslookuphostname-options-callback"><code>dns.lookup()</code></a>.</li> 11361cb0ef41Sopenharmony_ci<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a> An AbortSignal that may be used to close a socket.</li> 11371cb0ef41Sopenharmony_ci</ul> 11381cb0ef41Sopenharmony_ci</li> 11391cb0ef41Sopenharmony_ci<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> 11401cb0ef41Sopenharmony_ci<li>Returns: <a href="dgram.html#class-dgramsocket" class="type"><dgram.Socket></a></li> 11411cb0ef41Sopenharmony_ci</ul> 11421cb0ef41Sopenharmony_ci<p>Creates a <code>dgram.Socket</code> object. Once the socket is created, calling 11431cb0ef41Sopenharmony_ci<a href="#socketbindport-address-callback"><code>socket.bind()</code></a> will instruct the socket to begin listening for datagram 11441cb0ef41Sopenharmony_cimessages. When <code>address</code> and <code>port</code> are not passed to <a href="#socketbindport-address-callback"><code>socket.bind()</code></a> the 11451cb0ef41Sopenharmony_cimethod will bind the socket to the "all interfaces" address on a random port 11461cb0ef41Sopenharmony_ci(it does the right thing for both <code>udp4</code> and <code>udp6</code> sockets). The bound address 11471cb0ef41Sopenharmony_ciand port can be retrieved using <a href="#socketaddress"><code>socket.address().address</code></a> and 11481cb0ef41Sopenharmony_ci<a href="#socketaddress"><code>socket.address().port</code></a>.</p> 11491cb0ef41Sopenharmony_ci<p>If the <code>signal</code> option is enabled, calling <code>.abort()</code> on the corresponding 11501cb0ef41Sopenharmony_ci<code>AbortController</code> is similar to calling <code>.close()</code> on the socket:</p> 11511cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> controller = <span class="hljs-keyword">new</span> <span class="hljs-title class_">AbortController</span>(); 11521cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> { signal } = controller; 11531cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> server = dgram.<span class="hljs-title function_">createSocket</span>({ <span class="hljs-attr">type</span>: <span class="hljs-string">'udp4'</span>, signal }); 11541cb0ef41Sopenharmony_ciserver.<span class="hljs-title function_">on</span>(<span class="hljs-string">'message'</span>, <span class="hljs-function">(<span class="hljs-params">msg, rinfo</span>) =></span> { 11551cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<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>); 11561cb0ef41Sopenharmony_ci}); 11571cb0ef41Sopenharmony_ci<span class="hljs-comment">// Later, when you want to close the server.</span> 11581cb0ef41Sopenharmony_cicontroller.<span class="hljs-title function_">abort</span>();</code> <button class="copy-button">copy</button></pre> 11591cb0ef41Sopenharmony_ci<h4><code>dgram.createSocket(type[, callback])</code><span><a class="mark" href="#dgramcreatesockettype-callback" id="dgramcreatesockettype-callback">#</a></span><a aria-hidden="true" class="legacy" id="dgram_dgram_createsocket_type_callback"></a></h4> 11601cb0ef41Sopenharmony_ci<div class="api_metadata"> 11611cb0ef41Sopenharmony_ci<span>Added in: v0.1.99</span> 11621cb0ef41Sopenharmony_ci</div> 11631cb0ef41Sopenharmony_ci<ul> 11641cb0ef41Sopenharmony_ci<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> 11651cb0ef41Sopenharmony_ci<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> 11661cb0ef41Sopenharmony_ci<li>Returns: <a href="dgram.html#class-dgramsocket" class="type"><dgram.Socket></a></li> 11671cb0ef41Sopenharmony_ci</ul> 11681cb0ef41Sopenharmony_ci<p>Creates a <code>dgram.Socket</code> object of the specified <code>type</code>.</p> 11691cb0ef41Sopenharmony_ci<p>Once the socket is created, calling <a href="#socketbindport-address-callback"><code>socket.bind()</code></a> will instruct the 11701cb0ef41Sopenharmony_cisocket to begin listening for datagram messages. When <code>address</code> and <code>port</code> are 11711cb0ef41Sopenharmony_cinot passed to <a href="#socketbindport-address-callback"><code>socket.bind()</code></a> the method will bind the socket to the "all 11721cb0ef41Sopenharmony_ciinterfaces" address on a random port (it does the right thing for both <code>udp4</code> 11731cb0ef41Sopenharmony_ciand <code>udp6</code> sockets). The bound address and port can be retrieved using 11741cb0ef41Sopenharmony_ci<a href="#socketaddress"><code>socket.address().address</code></a> and <a href="#socketaddress"><code>socket.address().port</code></a>.</p></section> 11751cb0ef41Sopenharmony_ci <!-- API END --> 11761cb0ef41Sopenharmony_ci </div> 11771cb0ef41Sopenharmony_ci </div> 11781cb0ef41Sopenharmony_ci </div> 11791cb0ef41Sopenharmony_ci</body> 11801cb0ef41Sopenharmony_ci</html> 1181