Skip to content
This repository has been archived by the owner on Apr 22, 2023. It is now read-only.

Commit

Permalink
docs: remove unix dgram documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
bnoordhuis committed Aug 24, 2011
1 parent bba432f commit 48f4b2b
Showing 1 changed file with 6 additions and 73 deletions.
79 changes: 6 additions & 73 deletions doc/api/dgram.markdown
@@ -1,7 +1,6 @@
## UDP / Datagram Sockets

Datagram sockets are available through `require('dgram')`. Datagrams are most commonly
handled as IP/UDP messages but they can also be used over Unix domain sockets.
Datagram sockets are available through `require('dgram')`.

### Event: 'message'

Expand All @@ -15,7 +14,7 @@ an object with the sender's address information and the number of bytes in the d
`function () { }`

Emitted when a socket starts listening for datagrams. This happens as soon as UDP sockets
are created. Unix domain sockets do not start listening until calling `bind()` on them.
are created.

### Event: 'close'

Expand All @@ -26,8 +25,8 @@ on this socket.

### dgram.createSocket(type, [callback])

Creates a datagram socket of the specified types. Valid types are:
`udp4`, `udp6`, and `unix_dgram`.
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.

Expand All @@ -36,27 +35,6 @@ 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.send(buf, offset, length, path, [callback])

For Unix domain datagram sockets, the destination address is a pathname in the filesystem.
An optional callback may be supplied that is invoked after the `sendto` call is completed
by the OS. It is not safe to re-use `buf` until the callback is invoked. Note that
unless the socket is bound to a pathname with `bind()` there is no way to receive messages
on this socket.

Example of sending a message to syslogd on OSX via Unix domain socket `/var/run/syslog`:

var dgram = require('dgram');
var message = new Buffer("A message to log.");
var client = dgram.createSocket("unix_dgram");
client.send(message, 0, message.length, "/var/run/syslog",
function (err, bytes) {
if (err) {
throw err;
}
console.log("Wrote " + bytes + " bytes to socket.");
});

### dgram.send(buf, offset, length, port, address, [callback])

For UDP sockets, the destination port and IP address must be specified. A string
Expand All @@ -68,7 +46,7 @@ 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 IPv4-only systems, ::0 for IPv6 and dual stack systems).
(0.0.0.0 for `udp4` sockets, ::0 for `udp6` sockets).

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

Expand All @@ -79,50 +57,6 @@ Example of sending a UDP packet to a random port on `localhost`;
client.close();


### dgram.bind(path)

For Unix domain datagram sockets, start listening for incoming datagrams on a
socket specified by `path`. Note that clients may `send()` without `bind()`,
but no datagrams will be received without a `bind()`.

Example of a Unix domain datagram server that echoes back all messages it receives:

var dgram = require("dgram");
var serverPath = "/tmp/dgram_server_sock";
var server = dgram.createSocket("unix_dgram");

server.on("message", function (msg, rinfo) {
console.log("got: " + msg + " from " + rinfo.address);
server.send(msg, 0, msg.length, rinfo.address);
});

server.on("listening", function () {
console.log("server listening " + server.address().address);
})

server.bind(serverPath);

Example of a Unix domain datagram client that talks to this server:

var dgram = require("dgram");
var serverPath = "/tmp/dgram_server_sock";
var clientPath = "/tmp/dgram_client_sock";

var message = new Buffer("A message at " + (new Date()));

var client = dgram.createSocket("unix_dgram");

client.on("message", function (msg, rinfo) {
console.log("got: " + msg + " from " + rinfo.address);
});

client.on("listening", function () {
console.log("client listening " + client.address().address);
client.send(message, 0, message.length, serverPath);
});

client.bind(clientPath);

### dgram.bind(port, [address])

For UDP sockets, listen for datagrams on a named `port` and optional `address`. If
Expand Down Expand Up @@ -156,8 +90,7 @@ Close the underlying socket and stop listening for data on it.
### dgram.address()

Returns an object containing the address information for a socket. For UDP sockets,
this object will contain `address` and `port`. For Unix domain sockets, it will contain
only `address`.
this object will contain `address` and `port`.

### dgram.setBroadcast(flag)

Expand Down

0 comments on commit 48f4b2b

Please sign in to comment.