| <!doctype html> |
| <html lang="en"> |
| <head> |
| <meta charset="utf-8"> |
| <title>UDP / Datagram Sockets Node.js v0.10.24 Manual & Documentation</title> |
| <link rel="stylesheet" href="assets/style.css"> |
| <link rel="stylesheet" href="assets/sh.css"> |
| <link rel="canonical" href="http://nodejs.org/api/dgram.html"> |
| </head> |
| <body class="alt apidoc" id="api-section-dgram"> |
| <div id="intro" class="interior"> |
| <a href="/" title="Go back to the home page"> |
| <img id="logo" src="http://nodejs.org/images/logo-light.png" alt="node.js"> |
| </a> |
| </div> |
| <div id="content" class="clearfix"> |
| <div id="column2" class="interior"> |
| <ul> |
| <li><a href="/" class="home">Home</a></li> |
| <li><a href="/download/" class="download">Download</a></li> |
| <li><a href="/about/" class="about">About</a></li> |
| <li><a href="http://npmjs.org/" class="npm">npm Registry</a></li> |
| <li><a href="http://nodejs.org/api/" class="docs current">Docs</a></li> |
| <li><a href="http://blog.nodejs.org" class="blog">Blog</a></li> |
| <li><a href="/community/" class="community">Community</a></li> |
| <li><a href="/logos/" class="logos">Logos</a></li> |
| <li><a href="http://jobs.nodejs.org/" class="jobs">Jobs</a></li> |
| </ul> |
| <p class="twitter"><a href="http://twitter.com/nodejs">@nodejs</a></p> |
| </div> |
| |
| <div id="column1" class="interior"> |
| <header> |
| <h1>Node.js v0.10.24 Manual & Documentation</h1> |
| <div id="gtoc"> |
| <p> |
| <a href="index.html" name="toc">Index</a> | |
| <a href="all.html">View on single page</a> | |
| <a href="dgram.json">View as JSON</a> |
| </p> |
| </div> |
| <hr> |
| </header> |
| |
| <div id="toc"> |
| <h2>Table of Contents</h2> |
| <ul> |
| <li><a href="#dgram_udp_datagram_sockets">UDP / Datagram Sockets</a><ul> |
| <li><a href="#dgram_dgram_createsocket_type_callback">dgram.createSocket(type, [callback])</a></li> |
| <li><a href="#dgram_class_dgram_socket">Class: dgram.Socket</a><ul> |
| <li><a href="#dgram_event_message">Event: 'message'</a></li> |
| <li><a href="#dgram_event_listening">Event: 'listening'</a></li> |
| <li><a href="#dgram_event_close">Event: 'close'</a></li> |
| <li><a href="#dgram_event_error">Event: 'error'</a></li> |
| <li><a href="#dgram_socket_send_buf_offset_length_port_address_callback">socket.send(buf, offset, length, port, address, [callback])</a></li> |
| <li><a href="#dgram_socket_bind_port_address_callback">socket.bind(port, [address], [callback])</a></li> |
| <li><a href="#dgram_socket_close">socket.close()</a></li> |
| <li><a href="#dgram_socket_address">socket.address()</a></li> |
| <li><a href="#dgram_socket_setbroadcast_flag">socket.setBroadcast(flag)</a></li> |
| <li><a href="#dgram_socket_setttl_ttl">socket.setTTL(ttl)</a></li> |
| <li><a href="#dgram_socket_setmulticastttl_ttl">socket.setMulticastTTL(ttl)</a></li> |
| <li><a href="#dgram_socket_setmulticastloopback_flag">socket.setMulticastLoopback(flag)</a></li> |
| <li><a href="#dgram_socket_addmembership_multicastaddress_multicastinterface">socket.addMembership(multicastAddress, [multicastInterface])</a></li> |
| <li><a href="#dgram_socket_dropmembership_multicastaddress_multicastinterface">socket.dropMembership(multicastAddress, [multicastInterface])</a></li> |
| <li><a href="#dgram_socket_unref">socket.unref()</a></li> |
| <li><a href="#dgram_socket_ref">socket.ref()</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| |
| </div> |
| |
| <div id="apicontent"> |
| <h1>UDP / Datagram Sockets<span><a class="mark" href="#dgram_udp_datagram_sockets" id="dgram_udp_datagram_sockets">#</a></span></h1> |
| <pre class="api_stability_3">Stability: 3 - Stable</pre><!-- name=dgram --> |
| |
| <p>Datagram sockets are available through <code>require('dgram')</code>. |
| |
| </p> |
| <p>Important note: the behavior of <code>dgram.Socket#bind()</code> has changed in v0.10 |
| and is always asynchronous now. If you have code that looks like this: |
| |
| </p> |
| <pre><code>var s = dgram.createSocket('udp4'); |
| s.bind(1234); |
| s.addMembership('224.0.0.114');</code></pre> |
| <p>You have to change it to this: |
| |
| </p> |
| <pre><code>var s = dgram.createSocket('udp4'); |
| s.bind(1234, function() { |
| s.addMembership('224.0.0.114'); |
| });</code></pre> |
| <h2>dgram.createSocket(type, [callback])<span><a class="mark" href="#dgram_dgram_createsocket_type_callback" id="dgram_dgram_createsocket_type_callback">#</a></span></h2> |
| <div class="signature"><ul> |
| <li><code>type</code> String. Either 'udp4' or 'udp6'</li> |
| <li><code>callback</code> Function. Attached as a listener to <code>message</code> events. |
| Optional</li> |
| <li>Returns: Socket object</li> |
| </div></ul> |
| <p>Creates a datagram Socket of the specified types. Valid types are <code>udp4</code> |
| and <code>udp6</code>. |
| |
| </p> |
| <p>Takes an optional callback which is added as a listener for <code>message</code> events. |
| |
| </p> |
| <p>Call <code>socket.bind</code> if you want to receive datagrams. <code>socket.bind()</code> will bind |
| to the "all interfaces" address on a random port (it does the right thing for |
| both <code>udp4</code> and <code>udp6</code> sockets). You can then retrieve the address and port |
| with <code>socket.address().address</code> and <code>socket.address().port</code>. |
| |
| </p> |
| <h2>Class: dgram.Socket<span><a class="mark" href="#dgram_class_dgram_socket" id="dgram_class_dgram_socket">#</a></span></h2> |
| <p>The dgram Socket class encapsulates the datagram functionality. It |
| should be created via <code>dgram.createSocket(type, [callback])</code>. |
| |
| </p> |
| <h3>Event: 'message'<span><a class="mark" href="#dgram_event_message" id="dgram_event_message">#</a></span></h3> |
| <div class="signature"><ul> |
| <li><code>msg</code> Buffer object. The message</li> |
| <li><code>rinfo</code> Object. Remote address information</li> |
| </div></ul> |
| <p>Emitted when a new datagram is available on a socket. <code>msg</code> is a <code>Buffer</code> and <code>rinfo</code> is |
| an object with the sender's address information and the number of bytes in the datagram. |
| |
| </p> |
| <h3>Event: 'listening'<span><a class="mark" href="#dgram_event_listening" id="dgram_event_listening">#</a></span></h3> |
| <p>Emitted when a socket starts listening for datagrams. This happens as soon as UDP sockets |
| are created. |
| |
| </p> |
| <h3>Event: 'close'<span><a class="mark" href="#dgram_event_close" id="dgram_event_close">#</a></span></h3> |
| <p>Emitted when a socket is closed with <code>close()</code>. No new <code>message</code> events will be emitted |
| on this socket. |
| |
| </p> |
| <h3>Event: 'error'<span><a class="mark" href="#dgram_event_error" id="dgram_event_error">#</a></span></h3> |
| <div class="signature"><ul> |
| <li><code>exception</code> Error object</li> |
| </div></ul> |
| <p>Emitted when an error occurs. |
| |
| </p> |
| <h3>socket.send(buf, offset, length, port, address, [callback])<span><a class="mark" href="#dgram_socket_send_buf_offset_length_port_address_callback" id="dgram_socket_send_buf_offset_length_port_address_callback">#</a></span></h3> |
| <div class="signature"><ul> |
| <li><code>buf</code> Buffer object. Message to be sent</li> |
| <li><code>offset</code> Integer. Offset in the buffer where the message starts.</li> |
| <li><code>length</code> Integer. Number of bytes in the message.</li> |
| <li><code>port</code> Integer. Destination port.</li> |
| <li><code>address</code> String. Destination hostname or IP address.</li> |
| <li><code>callback</code> Function. Called when the message has been sent. Optional.</li> |
| </div></ul> |
| <p>For UDP sockets, the destination port and address must be specified. A string |
| may be supplied for the <code>address</code> parameter, and it will be resolved with DNS. |
| |
| </p> |
| <p>If the address is omitted or is an empty string, <code>'0.0.0.0'</code> or <code>'::0'</code> is used |
| instead. Depending on the network configuration, those defaults may or may not |
| work; it's best to be explicit about the destination address. |
| |
| </p> |
| <p>If the socket has not been previously bound with a call to <code>bind</code>, it gets |
| assigned a random port number and is bound to the "all interfaces" address |
| (<code>'0.0.0.0'</code> for <code>udp4</code> sockets, <code>'::0'</code> for <code>udp6</code> sockets.) |
| |
| </p> |
| <p>An optional callback may be specified to detect DNS errors or for determining |
| when it's safe to reuse the <code>buf</code> object. Note that DNS lookups delay the time |
| to send for at least one tick. The only way to know for sure that the datagram |
| has been sent is by using a callback. |
| |
| </p> |
| <p>Example of sending a UDP packet to a random port on <code>localhost</code>; |
| |
| </p> |
| <pre><code>var dgram = require('dgram'); |
| var message = new Buffer("Some bytes"); |
| var client = dgram.createSocket("udp4"); |
| client.send(message, 0, message.length, 41234, "localhost", function(err, bytes) { |
| client.close(); |
| });</code></pre> |
| <p><strong>A Note about UDP datagram size</strong> |
| |
| </p> |
| <p>The maximum size of an <code>IPv4/v6</code> datagram depends on the <code>MTU</code> (<em>Maximum Transmission Unit</em>) |
| and on the <code>Payload Length</code> field size. |
| |
| </p> |
| <ul> |
| <li><p>The <code>Payload Length</code> field is <code>16 bits</code> wide, which means that a normal payload |
| cannot be larger than 64K octets including internet header and data |
| (65,507 bytes = 65,535 − 8 bytes UDP header − 20 bytes IP header); |
| this is generally true for loopback interfaces, but such long datagrams |
| are impractical for most hosts and networks.</p> |
| </li> |
| <li><p>The <code>MTU</code> is the largest size a given link layer technology can support for datagrams. |
| For any link, <code>IPv4</code> mandates a minimum <code>MTU</code> of <code>68</code> octets, while the recommended <code>MTU</code> |
| for IPv4 is <code>576</code> (typically recommended as the <code>MTU</code> for dial-up type applications), |
| whether they arrive whole or in fragments.</p> |
| <p>For <code>IPv6</code>, the minimum <code>MTU</code> is <code>1280</code> octets, however, the mandatory minimum |
| fragment reassembly buffer size is <code>1500</code> octets. |
| The value of <code>68</code> octets is very small, since most current link layer technologies have |
| a minimum <code>MTU</code> of <code>1500</code> (like Ethernet).</p> |
| </li> |
| </ul> |
| <p>Note that it's impossible to know in advance the MTU of each link through which |
| a packet might travel, and that generally sending a datagram greater than |
| the (receiver) <code>MTU</code> won't work (the packet gets silently dropped, without |
| informing the source that the data did not reach its intended recipient). |
| |
| </p> |
| <h3>socket.bind(port, [address], [callback])<span><a class="mark" href="#dgram_socket_bind_port_address_callback" id="dgram_socket_bind_port_address_callback">#</a></span></h3> |
| <div class="signature"><ul> |
| <li><code>port</code> Integer</li> |
| <li><code>address</code> String, Optional</li> |
| <li><code>callback</code> Function with no parameters, Optional. Callback when |
| binding is done.</li> |
| </div></ul> |
| <p>For UDP sockets, listen for datagrams on a named <code>port</code> and optional |
| <code>address</code>. If <code>address</code> is not specified, the OS will try to listen on |
| all addresses. After binding is done, a "listening" event is emitted |
| and the <code>callback</code>(if specified) is called. Specifying both a |
| "listening" event listener and <code>callback</code> is not harmful but not very |
| useful. |
| |
| </p> |
| <p>A bound datagram socket keeps the node process running to receive |
| datagrams. |
| |
| </p> |
| <p>If binding fails, an "error" event is generated. In rare case (e.g. |
| binding a closed socket), an <code>Error</code> may be thrown by this method. |
| |
| </p> |
| <p>Example of a UDP server listening on port 41234: |
| |
| </p> |
| <pre><code>var dgram = require("dgram"); |
| |
| var server = dgram.createSocket("udp4"); |
| |
| server.on("error", function (err) { |
| console.log("server error:\n" + err.stack); |
| server.close(); |
| }); |
| |
| server.on("message", function (msg, rinfo) { |
| console.log("server got: " + msg + " from " + |
| rinfo.address + ":" + rinfo.port); |
| }); |
| |
| server.on("listening", function () { |
| var address = server.address(); |
| console.log("server listening " + |
| address.address + ":" + address.port); |
| }); |
| |
| server.bind(41234); |
| // server listening 0.0.0.0:41234</code></pre> |
| <h3>socket.close()<span><a class="mark" href="#dgram_socket_close" id="dgram_socket_close">#</a></span></h3> |
| <p>Close the underlying socket and stop listening for data on it. |
| |
| </p> |
| <h3>socket.address()<span><a class="mark" href="#dgram_socket_address" id="dgram_socket_address">#</a></span></h3> |
| <p>Returns an object containing the address information for a socket. For UDP sockets, |
| this object will contain <code>address</code> , <code>family</code> and <code>port</code>. |
| |
| </p> |
| <h3>socket.setBroadcast(flag)<span><a class="mark" href="#dgram_socket_setbroadcast_flag" id="dgram_socket_setbroadcast_flag">#</a></span></h3> |
| <div class="signature"><ul> |
| <li><code>flag</code> Boolean</li> |
| </div></ul> |
| <p>Sets or clears the <code>SO_BROADCAST</code> socket option. When this option is set, UDP packets |
| may be sent to a local interface's broadcast address. |
| |
| </p> |
| <h3>socket.setTTL(ttl)<span><a class="mark" href="#dgram_socket_setttl_ttl" id="dgram_socket_setttl_ttl">#</a></span></h3> |
| <div class="signature"><ul> |
| <li><code>ttl</code> Integer</li> |
| </div></ul> |
| <p>Sets the <code>IP_TTL</code> socket option. TTL stands for "Time to Live," but in this context it |
| specifies the number of IP hops that a packet is allowed to go through. Each router or |
| gateway that forwards a packet decrements the TTL. If the TTL is decremented to 0 by a |
| router, it will not be forwarded. Changing TTL values is typically done for network |
| probes or when multicasting. |
| |
| </p> |
| <p>The argument to <code>setTTL()</code> is a number of hops between 1 and 255. The default on most |
| systems is 64. |
| |
| </p> |
| <h3>socket.setMulticastTTL(ttl)<span><a class="mark" href="#dgram_socket_setmulticastttl_ttl" id="dgram_socket_setmulticastttl_ttl">#</a></span></h3> |
| <div class="signature"><ul> |
| <li><code>ttl</code> Integer</li> |
| </div></ul> |
| <p>Sets the <code>IP_MULTICAST_TTL</code> socket option. TTL stands for "Time to Live," but in this |
| context it specifies the number of IP hops that a packet is allowed to go through, |
| specifically for multicast traffic. Each router or gateway that forwards a packet |
| decrements the TTL. If the TTL is decremented to 0 by a router, it will not be forwarded. |
| |
| </p> |
| <p>The argument to <code>setMulticastTTL()</code> is a number of hops between 0 and 255. The default on most |
| systems is 1. |
| |
| </p> |
| <h3>socket.setMulticastLoopback(flag)<span><a class="mark" href="#dgram_socket_setmulticastloopback_flag" id="dgram_socket_setmulticastloopback_flag">#</a></span></h3> |
| <div class="signature"><ul> |
| <li><code>flag</code> Boolean</li> |
| </div></ul> |
| <p>Sets or clears the <code>IP_MULTICAST_LOOP</code> socket option. When this option is set, multicast |
| packets will also be received on the local interface. |
| |
| </p> |
| <h3>socket.addMembership(multicastAddress, [multicastInterface])<span><a class="mark" href="#dgram_socket_addmembership_multicastaddress_multicastinterface" id="dgram_socket_addmembership_multicastaddress_multicastinterface">#</a></span></h3> |
| <div class="signature"><ul> |
| <li><code>multicastAddress</code> String</li> |
| <li><code>multicastInterface</code> String, Optional</li> |
| </div></ul> |
| <p>Tells the kernel to join a multicast group with <code>IP_ADD_MEMBERSHIP</code> socket option. |
| |
| </p> |
| <p>If <code>multicastInterface</code> is not specified, the OS will try to add membership to all valid |
| interfaces. |
| |
| </p> |
| <h3>socket.dropMembership(multicastAddress, [multicastInterface])<span><a class="mark" href="#dgram_socket_dropmembership_multicastaddress_multicastinterface" id="dgram_socket_dropmembership_multicastaddress_multicastinterface">#</a></span></h3> |
| <div class="signature"><ul> |
| <li><code>multicastAddress</code> String</li> |
| <li><code>multicastInterface</code> String, Optional</li> |
| </div></ul> |
| <p>Opposite of <code>addMembership</code> - tells the kernel to leave a multicast group with |
| <code>IP_DROP_MEMBERSHIP</code> socket option. This is automatically called by the kernel |
| when the socket is closed or process terminates, so most apps will never need to call |
| this. |
| |
| </p> |
| <p>If <code>multicastInterface</code> is not specified, the OS will try to drop membership to all valid |
| interfaces. |
| |
| </p> |
| <h3>socket.unref()<span><a class="mark" href="#dgram_socket_unref" id="dgram_socket_unref">#</a></span></h3> |
| <p>Calling <code>unref</code> on a socket will allow the program to exit if this is the only |
| active socket in the event system. If the socket is already <code>unref</code>d calling |
| <code>unref</code> again will have no effect. |
| |
| </p> |
| <h3>socket.ref()<span><a class="mark" href="#dgram_socket_ref" id="dgram_socket_ref">#</a></span></h3> |
| <p>Opposite of <code>unref</code>, calling <code>ref</code> on a previously <code>unref</code>d socket will <em>not</em> |
| let the program exit if it's the only socket left (the default behavior). If |
| the socket is <code>ref</code>d calling <code>ref</code> again will have no effect. |
| </p> |
| |
| </div> |
| </div> |
| </div> |
| <div id="footer"> |
| <a href="http://joyent.com" class="joyent-logo">Joyent</a> |
| <ul class="clearfix"> |
| <li><a href="/">Node.js</a></li> |
| <li><a href="/download/">Download</a></li> |
| <li><a href="/about/">About</a></li> |
| <li><a href="http://npmjs.org/">npm Registry</a></li> |
| <li><a href="http://nodejs.org/api/">Docs</a></li> |
| <li><a href="http://blog.nodejs.org">Blog</a></li> |
| <li><a href="/community/">Community</a></li> |
| <li><a href="/logos/">Logos</a></li> |
| <li><a href="http://jobs.nodejs.org/">Jobs</a></li> |
| <li><a href="http://twitter.com/nodejs" class="twitter">@nodejs</a></li> |
| </ul> |
| |
| <p>Copyright <a href="http://joyent.com/">Joyent, Inc</a>, Node.js is a <a href="/trademark-policy.pdf">trademark</a> of Joyent, Inc. View <a href="https://raw.github.com/joyent/node/v0.10.24/LICENSE">license</a>.</p> |
| </div> |
| |
| <script src="../sh_main.js"></script> |
| <script src="../sh_javascript.min.js"></script> |
| <script>highlight(undefined, undefined, 'pre');</script> |
| <script> |
| window._gaq = [['_setAccount', 'UA-10874194-2'], ['_trackPageview']]; |
| (function(d, t) { |
| var g = d.createElement(t), |
| s = d.getElementsByTagName(t)[0]; |
| g.src = '//www.google-analytics.com/ga.js'; |
| s.parentNode.insertBefore(g, s); |
| }(document, 'script')); |
| </script> |
| </body> |
| </html> |
| |