From 964f956cb850c63ca2d666b7af05c8e830f43f25 Mon Sep 17 00:00:00 2001 From: patthoyts Date: Wed, 11 Apr 2007 00:06:54 +0000 Subject: [PATCH] Updated manual page. --- doc/udp.man | 36 ++++++++++++++++++++++---------- doc/udp.n | 59 +++++++++++++++++++++++++++++++++-------------------- 2 files changed, 62 insertions(+), 33 deletions(-) diff --git a/doc/udp.man b/doc/udp.man index 6ad1e3c..8d634c2 100644 --- 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 51a6b65..4617019 100644 --- 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 -- 2.23.0