Skip to content

Commit

Permalink
doc: dgram: reword dgram.Socket#send() docs
Browse files Browse the repository at this point in the history
Make it clear that the address argument is not really optional and fix
some Engrish and long lines while we're here.

Fixes nodejs#6433.
  • Loading branch information
bnoordhuis committed Oct 29, 2013
1 parent 4b5e6a3 commit 0c5981b
Showing 1 changed file with 19 additions and 15 deletions.
34 changes: 19 additions & 15 deletions doc/api/dgram.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -72,21 +72,25 @@ Emitted when an error occurs.
* `buf` Buffer object. 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 IP
* `callback` Function. Callback when message is done being delivered.
Optional.

For UDP sockets, the destination port and IP address must be specified. A string
may be supplied for the `address` parameter, and it will be resolved with DNS. An
optional callback may be specified to detect any DNS errors and when `buf` may be
re-used. Note that DNS lookups will delay the time that a send takes place, at
least until the next tick. The only way to know for sure that a send has taken place
is to use the callback.

If the socket has not been previously bound with a call to `bind`, it's
assigned a random port number and bound to the "all interfaces" address
(0.0.0.0 for `udp4` sockets, ::0 for `udp6` sockets).
* `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.

Example of sending a UDP packet to a random port on `localhost`;

Expand Down

0 comments on commit 0c5981b

Please sign in to comment.