From 9f7aa6f8686ccdcbb3fd012f700a5e551445d30d Mon Sep 17 00:00:00 2001 From: Matteo Collina Date: Sun, 7 Feb 2016 12:08:55 +0100 Subject: [PATCH] doc: clarify dgram socket.send() multi-buffer support Fixes: #5124 See: https://github.com/nodejs/node/pull/4374 PR-URL: https://github.com/nodejs/node/pull/5130 Reviewed-By: Rich Trott Reviewed-By: James M Snell --- doc/api/dgram.markdown | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/doc/api/dgram.markdown b/doc/api/dgram.markdown index 0872f311a56290..33175c69768439 100644 --- a/doc/api/dgram.markdown +++ b/doc/api/dgram.markdown @@ -185,11 +185,12 @@ never have reason to call this. If `multicastInterface` is not specified, the operating system will attempt to drop membership on all valid interfaces. -### socket.send(buf, offset, length, port, address[, callback]) +### socket.send(msg, [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. +* `msg` Buffer object, string, or an array of either. Message to be + sent. +* `offset` Integer. Optional. Offset in the buffer where the message starts. +* `length` Integer. Optional. 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. @@ -197,11 +198,15 @@ drop membership on all valid interfaces. Broadcasts a datagram on the socket. The destination `port` and `address` must be specified. -The `buf` argument is a [`Buffer`] object containing the message. The `offset` -and `length` specify the offset within the `Buffer` where the message begins -and the number of bytes in the message, respectively. With messages that +The `msg` argument containins the message to be sent. +Depending on its type, different behavior can apply. If `msg` is a `Buffer`, +the `offset` and `length` specify the offset within the `Buffer` where the +message begins and the number of bytes in the message, respectively. +If `msg` is a `String`, then it is automatically converted to a `Buffer` +with `'utf8'` enecoding. With messages that contain multi-byte characters, `offset` and `length` will be calculated with respect to [byte length][] and not the character position. +If `msg` is an array, `offset` and `length` must not be specified. The `address` argument is a string. If the value of `address` is a host name, DNS will be used to resolve the address of the host. If the `address` is not