Updated manual page.

diff --git a/doc/udp.man b/doc/udp.man
index 6ad1e3c668efa62b18598dd48e302a0113b9e1de..8d634c25b46eed5106a3aaa8c2bcd1e837d4d66f 100644 (file)
--- a/doc/udp.man
+++ b/doc/udp.man
@@ -3,7 +3,7 @@
           script from tcllib: dtplite -o udp.n nroff udp.man
                               dtplite -o udp.html html udp.man
 }]
-[manpage_begin udp n 1.0.8]
+[manpage_begin udp n 1.0.9]
 [copyright {1999-2000 Columbia University; all rights reserved}]
 [moddesc {Tcl UDP extension}]
 [titledesc {Create UDP sockets in Tcl}]
@@ -21,12 +21,17 @@ Tcl command [cmd fconfigure].
 
 [list_begin definitions]
 
-[call [cmd "udp_open"] [opt "[arg port]"]]
+[call [cmd "udp_open"] [opt "[arg port]"] [opt "[arg keywordlist]"]]
 
 [cmd udp_open] will open a UDP socket. If [arg port] is specified the UDP
 socket will be opened on that port. Otherwise the system will choose a port
 and the user can use the [cmd udp_conf] command to obtain the port number
 if required.
+[nl]
+From version 1.0.9 a second argument may be provided. The only valid value is
+'reuse' although others may be added in the future. The reuse keyword sets the
+SO_REUSEADDR socket option and permits multiple sockets to be bound to the same
+address/port combination.
 
 [call [cmd "udp_conf"] [arg "sock"] [arg "host"] [arg "port"]]
 
@@ -41,7 +46,8 @@ writing data to the UDP socket.
 [emph Deprecated] in favour of the standard Tcl [cmd fconfigure] command.
 [nl]
 In addition to being used to configure the remote host, the [cmd "udp_conf"]
-command is used to obtain information about the UDP socket.
+command is used to obtain information about the UDP socket. NOTE all these options
+are now available using the standard Tcl [cmd fconfigure] command.
 
 [list_begin definitions]
 
@@ -70,17 +76,25 @@ packet. The system default for multicast is 1 which restricts the packet
 to the local subnet. To permit packets to pass routers, you must increase the
 ttl. A value of 31 should keep it within a site, while 255 is global.
 
+[lst_item "[arg -mcastadd] groupaddr"]
+[lst_item "[arg -mcastdrop] groupaddr"]
+[lst_item "[arg -mcastgroups]"]
 
-[list_end]
-
-[nl]
-[call [cmd "udp_conf"] [opt "[arg -mcastadd] groupaddr"]]
-[call [cmd "udp_conf"] [opt "[arg -mcastdrop] groupaddr"]]
-
-[package tcludp] sockets can support IPv4 multicast operations. To recieve
+[package tcludp] sockets can support IPv4 multicast operations. To receive
 multicast packets the application has to notify the operating system that
 it should join a particular multicast group. These are specified as addresses
-in the range 224.0.0.0 to 239.255.255.255. 
+in the range 224.0.0.0 to 239.255.255.255.
+[nl]
+To view the current set of multicast groups for a channel use [arg -mcastgroups]
+
+[lst_item "[arg -mcastloop\ [opt boolean]]"]
+
+With multicast udp the system can choose to receive packets that it has sent
+or it can drop them. This is known as multicast loopback and can be controlled
+using this option. By default the value is true and your application will receive
+its own transmissions.
+
+[list_end]
 
 [call [cmd "udp_peek"] [arg "sock"] [opt [arg "buffersize"]]]
 

diff --git a/doc/udp.n b/doc/udp.n
index 51a6b653e0449748caef85ae99b452e5da306dd7..4617019a97ffad98cdfdb763eb483712cdfa967b 100644 (file)
--- a/doc/udp.n
+++ b/doc/udp.n
@@ -1,5 +1,5 @@
 '\"
-'\" Generated from file '../../tcludp/doc/udp.man' by tcllib/doctools with format 'nroff'
+'\" Generated from file 'udp.man' by tcllib/doctools with format 'nroff'
 '\" Copyright (c) 1999-2000 Columbia University; all rights reserved
 '\"
 '\" -*- tcl -*- doctools manpage
@@ -8,50 +8,56 @@
 '\"                               dtplite -o udp.html html udp.man
 '\"
 .so man.macros
-.TH "udp" n 1.0.7 udp "Tcl UDP extension"
+.TH "udp" n 1.0.9 udp "Tcl UDP extension"
 .BS
-.SH "NAME"
+.SH NAME
 udp \- Create UDP sockets in Tcl
-.SH "SYNOPSIS"
+.SH SYNOPSIS
 package require \fBTcl  8.2\fR
 .sp
 package require \fBudp  1.0\fR
 .sp
-\fBudp_open\fR ?\fIport\fR?
+\fBudp_open\fR ?\fIport\fR? ?\fIkeywordlist\fR?
 .sp
 \fBudp_conf\fR \fIsock\fR \fIhost\fR \fIport\fR
 .sp
 \fBudp_conf\fR \fIsock\fR \fI?-myport?\fR \fI?-remote?\fR \fI?-peer?\fR \fI?-broadcast bool?\fR \fI?-ttl count?\fR
 .sp
-\fBudp_conf\fR ?\fI-mcastadd\fR groupaddr?
-.sp
-\fBudp_conf\fR ?\fI-mcastdrop\fR groupaddr?
-.sp
 \fBudp_peek\fR \fIsock\fR ?\fIbuffersize\fR?
 .sp
 .BE
-.SH "DESCRIPTION"
+.SH DESCRIPTION
 This package provides support for using UDP through Tcl. The package provides
 a new channel type and attempts to permit the use of packet oriented UDP
 over stream oriented Tcl channels. The package defined three commands but
 \fBudp_conf\fR should be considered depreciated in favour of the standard
 Tcl command \fBfconfigure\fR.
-.SH "COMMANDS"
+.SH COMMANDS
 .TP
-\fBudp_open\fR ?\fIport\fR?
+\fBudp_open\fR ?\fIport\fR? ?\fIkeywordlist\fR?
 \fBudp_open\fR will open a UDP socket. If \fIport\fR is specified the UDP
 socket will be opened on that port. Otherwise the system will choose a port
 and the user can use the \fBudp_conf\fR command to obtain the port number
 if required.
+.sp
+From version 1.0.9 a second argument may be provided. The only valid value is
+\'reuse' although others may be added in the future. The reuse keyword sets the
+SO_REUSEADDR socket option and permits multiple sockets to be bound to the same
+address/port combination.
 .TP
 \fBudp_conf\fR \fIsock\fR \fIhost\fR \fIport\fR
+\fIDeprecated\fR in favour of the standard Tcl \fBfconfigure\fR command.
+.sp
 \fBudp_conf\fR in this configuration is used to specify the remote destination
 for packets written to this \fIsock\fR. You must call this command before
 writing data to the UDP socket.
 .TP
 \fBudp_conf\fR \fIsock\fR \fI?-myport?\fR \fI?-remote?\fR \fI?-peer?\fR \fI?-broadcast bool?\fR \fI?-ttl count?\fR
+\fIDeprecated\fR in favour of the standard Tcl \fBfconfigure\fR command.
+.sp
 In addition to being used to configure the remote host, the \fBudp_conf\fR
-command is used to obtain information about the UDP socket.
+command is used to obtain information about the UDP socket. NOTE all these options
+are now available using the standard Tcl \fBfconfigure\fR command.
 .RS
 .TP
 \fI-myport\fR
@@ -77,21 +83,30 @@ multicast packets this is important in specifying the distribution of the
 packet. The system default for multicast is 1 which restricts the packet
 to the local subnet. To permit packets to pass routers, you must increase the
 ttl. A value of 31 should keep it within a site, while 255 is global.
-.RE
-.sp
 .TP
-\fBudp_conf\fR ?\fI-mcastadd\fR groupaddr?
+\fI-mcastadd\fR groupaddr
+.TP
+\fI-mcastdrop\fR groupaddr
 .TP
-\fBudp_conf\fR ?\fI-mcastdrop\fR groupaddr?
-\fBtcludp\fR sockets can support IPv4 multicast operations. To recieve
+\fI-mcastgroups\fR
+\fBtcludp\fR sockets can support IPv4 multicast operations. To receive
 multicast packets the application has to notify the operating system that
 it should join a particular multicast group. These are specified as addresses
 in the range 224.0.0.0 to 239.255.255.255.
+.sp
+To view the current set of multicast groups for a channel use \fI-mcastgroups\fR
+.TP
+\fI-mcastloop ?boolean?\fR
+With multicast udp the system can choose to receive packets that it has sent
+or it can drop them. This is known as multicast loopback and can be controlled
+using this option. By default the value is true and your application will receive
+its own transmissions.
+.RE
 .TP
 \fBudp_peek\fR \fIsock\fR ?\fIbuffersize\fR?
 Examine a packet without removing it from the buffer.
 This function is not available on windows.
-.SH "EXAMPLES"
+.SH EXAMPLES
 .PP
 .nf
 
@@ -155,7 +170,7 @@ vwait ::forever
 exit
 
 .fi
-.SH "HISTORY"
+.SH HISTORY
 Some of the code in this extension is copied from Michael Miller's tcludp
 package. (http://www.neosoft.com/tcl/ftparchive/sorted/comm/tcludp-1.0/)
 Compared with Michael's UDP extension, this extension provides Windows
@@ -166,9 +181,9 @@ Enhancements to support binary data and to setup the package for the Tcl
 Extension Architecture by Pat Thoyts.
 .SH "SEE ALSO"
 socket(n)
-.SH "KEYWORDS"
+.SH KEYWORDS
 networking, socket, udp
-.SH "COPYRIGHT"
+.SH COPYRIGHT
 .nf
 Copyright (c) 1999-2000 Columbia University; all rights reserved