From c39eabbec4a46f6c49662be923cbed0b50740351 Mon Sep 17 00:00:00 2001 From: Tristian Flanagan Date: Wed, 4 Nov 2015 11:30:26 -0500 Subject: [PATCH] doc: sort dgram alphabetically Reorders, with no contextual changes, the dgram documentation alphabetically. PR-URL: https://github.com/nodejs/node/pull/3662 Reviewed-By: Evan Lucas Reviewed-By: James M Snell Reviewed-By: Jeremiah Senkpiel --- doc/api/dgram.markdown | 301 ++++++++++++++++++++--------------------- 1 file changed, 149 insertions(+), 152 deletions(-) diff --git a/doc/api/dgram.markdown b/doc/api/dgram.markdown index 72ea2130581d6b..fce88d0fdc2d2f 100644 --- a/doc/api/dgram.markdown +++ b/doc/api/dgram.markdown @@ -20,66 +20,11 @@ You have to change it to this: s.addMembership('224.0.0.114'); }); - -## dgram.createSocket(type[, callback]) - -* `type` String. Either 'udp4' or 'udp6' -* `callback` Function. Attached as a listener to `message` events. - Optional -* Returns: Socket object - -Creates a datagram Socket of the specified types. Valid types are `udp4` -and `udp6`. - -Takes an optional callback which is added as a listener for `message` events. - -Call `socket.bind()` if you want to receive datagrams. `socket.bind()` will -bind to the "all interfaces" address on a random port (it does the right thing -for both `udp4` and `udp6` sockets). You can then retrieve the address and port -with `socket.address().address` and `socket.address().port`. - -## dgram.createSocket(options[, callback]) -* `options` Object -* `callback` Function. Attached as a listener to `message` events. -* Returns: Socket object - -The `options` object should contain a `type` field of either `udp4` or `udp6` -and an optional boolean `reuseAddr` field. - -When `reuseAddr` is `true` `socket.bind()` will reuse the address, even if -another process has already bound a socket on it. `reuseAddr` defaults to -`false`. - -Takes an optional callback which is added as a listener for `message` events. - -Call `socket.bind()` if you want to receive datagrams. `socket.bind()` will -bind to the "all interfaces" address on a random port (it does the right thing -for both `udp4` and `udp6` sockets). You can then retrieve the address and port -with `socket.address().address` and `socket.address().port`. - ## Class: dgram.Socket The dgram Socket class encapsulates the datagram functionality. It should be created via `dgram.createSocket(...)` -### Event: 'message' - -* `msg` Buffer object. The message -* `rinfo` Object. Remote address information - -Emitted when a new datagram is available on a socket. `msg` is a `Buffer` and -`rinfo` is an object with the sender's address information: - - socket.on('message', function(msg, rinfo) { - console.log('Received %d bytes from %s:%d\n', - msg.length, rinfo.address, rinfo.port); - }); - -### Event: 'listening' - -Emitted when a socket starts listening for datagrams. This happens as soon as UDP sockets -are created. - ### Event: 'close' Emitted after a socket is closed with `close()`. No new `message` events will be emitted @@ -91,72 +36,38 @@ on this socket. Emitted when an error occurs. -### socket.send(buf, offset, length, port, address[, callback]) - -* `buf` Buffer object or string. Message to be sent -* `offset` Integer. Offset in the buffer where the message starts. -* `length` Integer. Number of bytes in the message. -* `port` Integer. Destination port. -* `address` String. Destination hostname or IP address. -* `callback` Function. Called when the message has been sent. Optional. - -For UDP sockets, the destination port and address must be specified. A string -may be supplied for the `address` parameter, and it will be resolved with DNS. - -If the address is omitted or is an empty string, `'0.0.0.0'` or `'::0'` 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. +### Event: 'listening' -If the socket has not been previously bound with a call to `bind`, it gets -assigned a random port number and is bound to the "all interfaces" address -(`'0.0.0.0'` for `udp4` sockets, `'::0'` for `udp6` sockets.) +Emitted when a socket starts listening for datagrams. This happens as soon as UDP sockets +are created. -An optional callback may be specified to detect DNS errors or for determining -when it's safe to reuse the `buf` 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. If an error occurs and a callback is -given, the error will be the first argument to the callback. If a callback is -not given, the error is emitted as an `'error'` event on the `socket` object. +### Event: 'message' -With consideration for multi-byte characters, `offset` and `length` will -be calculated with respect to -[byte length](buffer.html#buffer_class_method_buffer_bytelength_string_encoding) -and not the character position. +* `msg` Buffer object. The message +* `rinfo` Object. Remote address information -Example of sending a UDP packet to a random port on `localhost`; +Emitted when a new datagram is available on a socket. `msg` is a `Buffer` and +`rinfo` is an object with the sender's address information: - 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) { - client.close(); + socket.on('message', function(msg, rinfo) { + console.log('Received %d bytes from %s:%d\n', + msg.length, rinfo.address, rinfo.port); }); -**A Note about UDP datagram size** +### socket.addMembership(multicastAddress[, multicastInterface]) -The maximum size of an `IPv4/v6` datagram depends on the `MTU` (_Maximum Transmission Unit_) -and on the `Payload Length` field size. +* `multicastAddress` String +* `multicastInterface` String, Optional -- The `Payload Length` field is `16 bits` 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. +Tells the kernel to join a multicast group with `IP_ADD_MEMBERSHIP` socket option. -- The `MTU` is the largest size a given link layer technology can support for datagrams. - For any link, `IPv4` mandates a minimum `MTU` of `68` octets, while the recommended `MTU` - for IPv4 is `576` (typically recommended as the `MTU` for dial-up type applications), - whether they arrive whole or in fragments. +If `multicastInterface` is not specified, the OS will try to add membership to all valid +interfaces. - For `IPv6`, the minimum `MTU` is `1280` octets, however, the mandatory minimum - fragment reassembly buffer size is `1500` octets. - The value of `68` octets is very small, since most current link layer technologies have - a minimum `MTU` of `1500` (like Ethernet). +### socket.address() -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) `MTU` won't work (the packet gets silently dropped, without -informing the source that the data did not reach its intended recipient). +Returns an object containing the address information for a socket. For UDP sockets, +this object will contain `address` , `family` and `port`. ### socket.bind([port][, address][, callback]) @@ -204,7 +115,6 @@ Example of a UDP server listening on port 41234: server.bind(41234); // server listening 0.0.0.0:41234 - ### socket.bind(options[, callback]) * `options` {Object} - Required. Supports the following properties: @@ -230,16 +140,90 @@ shown below. exclusive: true }); - ### socket.close([callback]) Close the underlying socket and stop listening for data on it. If a callback is provided, it is added as a listener for the ['close'](#dgram_event_close) event. -### socket.address() +### socket.dropMembership(multicastAddress[, multicastInterface]) -Returns an object containing the address information for a socket. For UDP sockets, -this object will contain `address` , `family` and `port`. +* `multicastAddress` String +* `multicastInterface` String, Optional + +Opposite of `addMembership` - tells the kernel to leave a multicast group with +`IP_DROP_MEMBERSHIP` 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. + +If `multicastInterface` is not specified, the OS will try to drop membership to all valid +interfaces. + +### socket.send(buf, offset, length, port, address[, callback]) + +* `buf` Buffer object or string. Message to be sent +* `offset` Integer. Offset in the buffer where the message starts. +* `length` Integer. Number of bytes in the message. +* `port` Integer. Destination port. +* `address` String. Destination hostname or IP address. +* `callback` Function. Called when the message has been sent. Optional. + +For UDP sockets, the destination port and address must be specified. A string +may be supplied for the `address` parameter, and it will be resolved with DNS. + +If the address is omitted or is an empty string, `'0.0.0.0'` or `'::0'` 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. + +If the socket has not been previously bound with a call to `bind`, it gets +assigned a random port number and is bound to the "all interfaces" address +(`'0.0.0.0'` for `udp4` sockets, `'::0'` for `udp6` sockets.) + +An optional callback may be specified to detect DNS errors or for determining +when it's safe to reuse the `buf` 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. If an error occurs and a callback is +given, the error will be the first argument to the callback. If a callback is +not given, the error is emitted as an `'error'` event on the `socket` object. + +With consideration for multi-byte characters, `offset` and `length` will +be calculated with respect to +[byte length](buffer.html#buffer_class_method_buffer_bytelength_string_encoding) +and not the character position. + +Example of sending a UDP packet to a random port on `localhost`; + + 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) { + client.close(); + }); + +**A Note about UDP datagram size** + +The maximum size of an `IPv4/v6` datagram depends on the `MTU` (_Maximum Transmission Unit_) +and on the `Payload Length` field size. + +- The `Payload Length` field is `16 bits` 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. + +- The `MTU` is the largest size a given link layer technology can support for datagrams. + For any link, `IPv4` mandates a minimum `MTU` of `68` octets, while the recommended `MTU` + for IPv4 is `576` (typically recommended as the `MTU` for dial-up type applications), + whether they arrive whole or in fragments. + + For `IPv6`, the minimum `MTU` is `1280` octets, however, the mandatory minimum + fragment reassembly buffer size is `1500` octets. + The value of `68` octets is very small, since most current link layer technologies have + a minimum `MTU` of `1500` (like Ethernet). + +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) `MTU` won't work (the packet gets silently dropped, without +informing the source that the data did not reach its intended recipient). ### socket.setBroadcast(flag) @@ -248,18 +232,12 @@ this object will contain `address` , `family` and `port`. Sets or clears the `SO_BROADCAST` socket option. When this option is set, UDP packets may be sent to a local interface's broadcast address. -### socket.setTTL(ttl) - -* `ttl` Integer +### socket.setMulticastLoopback(flag) -Sets the `IP_TTL` 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. +* `flag` Boolean -The argument to `setTTL()` is a number of hops between 1 and 255. The default on most -systems is 64. +Sets or clears the `IP_MULTICAST_LOOP` socket option. When this option is set, multicast +packets will also be received on the local interface. ### socket.setMulticastTTL(ttl) @@ -273,35 +251,26 @@ decrements the TTL. If the TTL is decremented to 0 by a router, it will not be f The argument to `setMulticastTTL()` is a number of hops between 0 and 255. The default on most systems is 1. -### socket.setMulticastLoopback(flag) - -* `flag` Boolean - -Sets or clears the `IP_MULTICAST_LOOP` socket option. When this option is set, multicast -packets will also be received on the local interface. - -### socket.addMembership(multicastAddress[, multicastInterface]) - -* `multicastAddress` String -* `multicastInterface` String, Optional +### socket.setTTL(ttl) -Tells the kernel to join a multicast group with `IP_ADD_MEMBERSHIP` socket option. +* `ttl` Integer -If `multicastInterface` is not specified, the OS will try to add membership to all valid -interfaces. +Sets the `IP_TTL` 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. -### socket.dropMembership(multicastAddress[, multicastInterface]) +The argument to `setTTL()` is a number of hops between 1 and 255. The default on most +systems is 64. -* `multicastAddress` String -* `multicastInterface` String, Optional +### socket.ref() -Opposite of `addMembership` - tells the kernel to leave a multicast group with -`IP_DROP_MEMBERSHIP` 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. +Opposite of `unref`, calling `ref` on a previously `unref`d socket will *not* +let the program exit if it's the only socket left (the default behavior). If +the socket is `ref`d calling `ref` again will have no effect. -If `multicastInterface` is not specified, the OS will try to drop membership to all valid -interfaces. +Returns `socket`. ### socket.unref() @@ -311,10 +280,38 @@ active socket in the event system. If the socket is already `unref`d calling Returns `socket`. -### socket.ref() +## dgram.createSocket(options[, callback]) +* `options` Object +* `callback` Function. Attached as a listener to `message` events. +* Returns: Socket object -Opposite of `unref`, calling `ref` on a previously `unref`d socket will *not* -let the program exit if it's the only socket left (the default behavior). If -the socket is `ref`d calling `ref` again will have no effect. +The `options` object should contain a `type` field of either `udp4` or `udp6` +and an optional boolean `reuseAddr` field. -Returns `socket`. +When `reuseAddr` is `true` `socket.bind()` will reuse the address, even if +another process has already bound a socket on it. `reuseAddr` defaults to +`false`. + +Takes an optional callback which is added as a listener for `message` events. + +Call `socket.bind()` if you want to receive datagrams. `socket.bind()` will +bind to the "all interfaces" address on a random port (it does the right thing +for both `udp4` and `udp6` sockets). You can then retrieve the address and port +with `socket.address().address` and `socket.address().port`. + +## dgram.createSocket(type[, callback]) + +* `type` String. Either 'udp4' or 'udp6' +* `callback` Function. Attached as a listener to `message` events. + Optional +* Returns: Socket object + +Creates a datagram Socket of the specified types. Valid types are `udp4` +and `udp6`. + +Takes an optional callback which is added as a listener for `message` events. + +Call `socket.bind()` if you want to receive datagrams. `socket.bind()` will +bind to the "all interfaces" address on a random port (it does the right thing +for both `udp4` and `udp6` sockets). You can then retrieve the address and port +with `socket.address().address` and `socket.address().port`.