Tcl UDP

Check-in [d9c46224c6]
Login
Bounty program for improvements to Tcl and certain Tcl packages.
Tcl 2019 Conference, Houston/TX, US, Nov 4-8
Send your abstracts to tclconference@googlegroups.com
or submit via the online form by Sep 9.

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Store HTML docs in repo since generation at install time mandates availability of mpexpand
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256:d9c46224c60d5c0aeb44681f320ff1caeb5d39e3953c95a500d47cb7be4fb2f0
User & Date: apnadkarni 2017-12-26 14:27:27
Context
2018-10-01
23:14
Modifications to allow udp to compile under 8.7+ Leaf check-in: 565c05d10a user: seandeelywoods tags: trunk
2017-12-26
14:27
Store HTML docs in repo since generation at install time mandates availability of mpexpand check-in: d9c46224c6 user: apnadkarni tags: trunk
2017-12-23
10:22
Update to V1.1 of nmake rules check-in: 032223d40a user: apnadkarni tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to .fossil-settings/crlf-glob.

     1      1   win/*.vc
     2      2   win/README.win
            3  +*.html

Added doc/udp.html.

            1  +
            2  +<!DOCTYPE html><html><head>
            3  +<title>udp - Tcl UDP extension</title>
            4  +<style type="text/css"><!--
            5  +    HTML {
            6  +	background: 	#FFFFFF;
            7  +	color: 		black;
            8  +    }
            9  +    BODY {
           10  +	background: 	#FFFFFF;
           11  +	color:	 	black;
           12  +    }
           13  +    DIV.doctools {
           14  +	margin-left:	10%;
           15  +	margin-right:	10%;
           16  +    }
           17  +    DIV.doctools H1,DIV.doctools H2 {
           18  +	margin-left:	-5%;
           19  +    }
           20  +    H1, H2, H3, H4 {
           21  +	margin-top: 	1em;
           22  +	font-family:	sans-serif;
           23  +	font-size:	large;
           24  +	color:		#005A9C;
           25  +	background: 	transparent;
           26  +	text-align:		left;
           27  +    }
           28  +    H1.doctools_title {
           29  +	text-align: center;
           30  +    }
           31  +    UL,OL {
           32  +	margin-right: 0em;
           33  +	margin-top: 3pt;
           34  +	margin-bottom: 3pt;
           35  +    }
           36  +    UL LI {
           37  +	list-style: disc;
           38  +    }
           39  +    OL LI {
           40  +	list-style: decimal;
           41  +    }
           42  +    DT {
           43  +	padding-top: 	1ex;
           44  +    }
           45  +    UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
           46  +	font:		normal 12pt/14pt sans-serif;
           47  +	list-style:	none;
           48  +    }
           49  +    LI.doctools_section, LI.doctools_subsection {
           50  +	list-style: 	none;
           51  +	margin-left: 	0em;
           52  +	text-indent:	0em;
           53  +	padding: 	0em;
           54  +    }
           55  +    PRE {
           56  +	display: 	block;
           57  +	font-family:	monospace;
           58  +	white-space:	pre;
           59  +	margin:		0%;
           60  +	padding-top:	0.5ex;
           61  +	padding-bottom:	0.5ex;
           62  +	padding-left:	1ex;
           63  +	padding-right:	1ex;
           64  +	width:		100%;
           65  +    }
           66  +    PRE.doctools_example {
           67  +	color: 		black;
           68  +	background: 	#f5dcb3;
           69  +	border:		1px solid black;
           70  +    }
           71  +    UL.doctools_requirements LI, UL.doctools_syntax LI {
           72  +	list-style: 	none;
           73  +	margin-left: 	0em;
           74  +	text-indent:	0em;
           75  +	padding:	0em;
           76  +    }
           77  +    DIV.doctools_synopsis {
           78  +	color: 		black;
           79  +	background: 	#80ffff;
           80  +	border:		1px solid black;
           81  +	font-family:	serif;
           82  +	margin-top: 	1em;
           83  +	margin-bottom: 	1em;
           84  +    }
           85  +    UL.doctools_syntax {
           86  +	margin-top: 	1em;
           87  +	border-top:	1px solid black;
           88  +    }
           89  +    UL.doctools_requirements {
           90  +	margin-bottom: 	1em;
           91  +	border-bottom:	1px solid black;
           92  +    }
           93  +--></style>
           94  +<link rel="stylesheet" href="manpage.css" type="text/css"></head>
           95  +<!-- Generated from file 'udp.man' by tcllib/doctools with format 'html'
           96  +   -->
           97  +<!-- Copyright &amp;copy; 1999-2000 Columbia University; all rights reserved
           98  +   -->
           99  +<!-- udp.n
          100  +   -->
          101  +<body><div class="doctools">
          102  +<h1 class="doctools_title">udp(n) 1.0.11  &quot;Tcl UDP extension&quot;</h1>
          103  +<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
          104  +<p>udp - Create UDP sockets in Tcl</p>
          105  +</div>
          106  +<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
          107  +<ul class="doctools_toc">
          108  +<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
          109  +<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
          110  +<li class="doctools_section"><a href="#section1">Description</a></li>
          111  +<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
          112  +<li class="doctools_section"><a href="#section3">EXAMPLES</a></li>
          113  +<li class="doctools_section"><a href="#section4">HISTORY</a></li>
          114  +<li class="doctools_section"><a href="#see-also">See Also</a></li>
          115  +<li class="doctools_section"><a href="#keywords">Keywords</a></li>
          116  +<li class="doctools_section"><a href="#copyright">Copyright</a></li>
          117  +</ul>
          118  +</div>
          119  +<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
          120  +<div class="doctools_synopsis">
          121  +<ul class="doctools_requirements">
          122  +<li>package require <b class="pkgname">Tcl 8.2</b></li>
          123  +<li>package require <b class="pkgname">udp 1.0.11</b></li>
          124  +</ul>
          125  +<ul class="doctools_syntax">
          126  +<li><a href="#1"><b class="cmd">udp_open</b> <span class="opt">?<i class="arg">port</i>?</span> <span class="opt">?<i class="arg">reuse</i>?</span> <span class="opt">?<i class="arg">ipv6</i>?</span></a></li>
          127  +<li><a href="#2"><b class="cmd">udp_conf</b> <i class="arg">sock</i> <i class="arg">host</i> <i class="arg">port</i></a></li>
          128  +<li><a href="#3"><b class="cmd">udp_conf</b> <i class="arg">sock</i> <i class="arg"><span class="opt">?-myport?</span></i> <i class="arg"><span class="opt">?-remote?</span></i> <i class="arg"><span class="opt">?-peer?</span></i> <i class="arg"><span class="opt">?-broadcast bool?</span></i> <i class="arg"><span class="opt">?-ttl count?</span></i> <i class="arg"><span class="opt">?-mcastadd &quot;groupaddr <span class="opt">?netwif?</span>&quot;?</span></i> <i class="arg"><span class="opt">?-mcastdrop &quot;groupaddr <span class="opt">?netwif?</span>&quot;?</span></i> <i class="arg"><span class="opt">?-mcastgroups?</span></i> <i class="arg"><span class="opt">?-mcastloop bool?</span></i></a></li>
          129  +<li><a href="#4"><b class="cmd">udp_peek</b> <i class="arg">sock</i> <span class="opt">?<i class="arg">buffersize</i>?</span></a></li>
          130  +</ul>
          131  +</div>
          132  +</div>
          133  +<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
          134  +<p>This package provides support for using UDP through Tcl. The package provides
          135  +a new channel type and attempts to permit the use of packet oriented UDP
          136  +over stream oriented Tcl channels. The package defined three commands but
          137  +<b class="cmd">udp_conf</b> should be considered depreciated in favour of the standard
          138  +Tcl command <b class="cmd">fconfigure</b>.</p>
          139  +</div>
          140  +<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
          141  +<dl class="doctools_definitions">
          142  +<dt><a name="1"><b class="cmd">udp_open</b> <span class="opt">?<i class="arg">port</i>?</span> <span class="opt">?<i class="arg">reuse</i>?</span> <span class="opt">?<i class="arg">ipv6</i>?</span></a></dt>
          143  +<dd><p><b class="cmd">udp_open</b> will open a UDP socket. If a <i class="arg">port</i> is specified the UDP
          144  +socket will be opened on that port. Otherwise the system will choose a port
          145  +and the user can use the <b class="cmd">udp_conf</b> command to obtain the port number
          146  +if required.</p>
          147  +<p>The following keywords can be used to specify options on the opened socket.</p>
          148  +<dl class="doctools_definitions">
          149  +<dt><i class="arg">reuse</i></dt>
          150  +<dd><p>Using this keyword sets the SO_REUSEADDR socket option which permits multiple sockets to 
          151  +be bound to the same address/port combination.</p></dd>
          152  +<dt><i class="arg">ipv6</i></dt>
          153  +<dd><p>By default a IPv4 socket is created. When keyword <i class="arg">ipv6</i> is specified an IPv6
          154  +socket is opened.</p></dd>
          155  +</dl></dd>
          156  +<dt><a name="2"><b class="cmd">udp_conf</b> <i class="arg">sock</i> <i class="arg">host</i> <i class="arg">port</i></a></dt>
          157  +<dd><p><em>Deprecated</em> in favour of the standard Tcl <b class="cmd">fconfigure</b> command.</p>
          158  +<p><b class="cmd">udp_conf</b> in this configuration is used to specify the remote destination
          159  +for packets written to this <i class="arg">sock</i>. You must call this command before
          160  +writing data to the UDP socket.</p></dd>
          161  +<dt><a name="3"><b class="cmd">udp_conf</b> <i class="arg">sock</i> <i class="arg"><span class="opt">?-myport?</span></i> <i class="arg"><span class="opt">?-remote?</span></i> <i class="arg"><span class="opt">?-peer?</span></i> <i class="arg"><span class="opt">?-broadcast bool?</span></i> <i class="arg"><span class="opt">?-ttl count?</span></i> <i class="arg"><span class="opt">?-mcastadd &quot;groupaddr <span class="opt">?netwif?</span>&quot;?</span></i> <i class="arg"><span class="opt">?-mcastdrop &quot;groupaddr <span class="opt">?netwif?</span>&quot;?</span></i> <i class="arg"><span class="opt">?-mcastgroups?</span></i> <i class="arg"><span class="opt">?-mcastloop bool?</span></i></a></dt>
          162  +<dd><p><em>Deprecated</em> in favour of the standard Tcl <b class="cmd">fconfigure</b> command.</p>
          163  +<p>In addition to being used to configure the remote host, the <b class="cmd">udp_conf</b>
          164  +command is used to obtain information about the UDP socket. NOTE all these options
          165  +are now available using the standard Tcl <b class="cmd">fconfigure</b> command.</p>
          166  +<dl class="doctools_definitions">
          167  +<dt><i class="arg">-myport</i></dt>
          168  +<dd><p>Returns the local port number of the socket.</p></dd>
          169  +<dt><i class="arg">-remote</i></dt>
          170  +<dd><p>Returns the remote hostname and port number as set using 
          171  +<b class="cmd">udp_conf</b> <i class="arg">sock</i> <i class="arg">host</i> <i class="arg">port</i>.</p></dd>
          172  +<dt><i class="arg">-peer</i></dt>
          173  +<dd><p>Returns the remote hostname and port number for the packet most recently
          174  +received by this socket.</p></dd>
          175  +<dt><i class="arg">-broadcast <span class="opt">?boolean?</span></i></dt>
          176  +<dd><p>UDP packets can listen and send on the broadcast address. For some systems 
          177  +a flag must be set on the socket to use broadcast. 
          178  +With no argument this option will return the broadcast setting. With a 
          179  +boolean argument the setting can be modified. This option is not permitted when
          180  +using IPv6.</p></dd>
          181  +<dt><i class="arg">-ttl <span class="opt">?count?</span></i></dt>
          182  +<dd><p>The time-to-live is given as the number of router hops the packet may do. For
          183  +multicast packets this is important in specifying the distribution of the
          184  +packet. The system default for multicast is 1 which restricts the packet 
          185  +to the local subnet. To permit packets to pass routers, you must increase the
          186  +ttl. A value of 31 should keep it within a site, while 255 is global.</p></dd>
          187  +<dt><i class="arg">-mcastadd</i> groupaddr</dt>
          188  +<dd></dd>
          189  +<dt><i class="arg">-mcastadd</i> &quot;groupaddr netwif&quot;</dt>
          190  +<dd></dd>
          191  +<dt><i class="arg">-mcastdrop</i> groupaddr</dt>
          192  +<dd></dd>
          193  +<dt><i class="arg">-mcastdrop</i> &quot;groupaddr netwif&quot;</dt>
          194  +<dd></dd>
          195  +<dt><i class="arg">-mcastgroups</i></dt>
          196  +<dd><p><b class="package">tcludp</b> sockets can support IPv4 and IPv6 multicast operations. To receive
          197  +multicast packets the application has to notify the operating system that
          198  +it should join a particular multicast group. For IPv4 these are specified as addresses
          199  +in the range 224.0.0.0 to 239.255.255.255.</p>
          200  +<p>When specifying only the <i class="arg">groupaddr</i> the system will determine the network interface to use. 
          201  +Specifying the <i class="arg">netwif</i> will join a multicast group on a specific network interface.
          202  +This is useful on a multihomed system with multiple network interfaces.
          203  +On windows you must specify the network interface index. For other platforms the network
          204  +interface (e.g. 'eth0') name can be specified.</p>
          205  +<p>To view the current set of multicast groups for a channel use <i class="arg">-mcastgroups</i></p></dd>
          206  +<dt><i class="arg">-mcastloop <span class="opt">?boolean?</span></i></dt>
          207  +<dd><p>With multicast udp the system can choose to receive packets that it has sent
          208  +or it can drop them. This is known as multicast loopback and can be controlled
          209  +using this option. By default the value is true and your application will receive
          210  +its own transmissions.</p></dd>
          211  +</dl></dd>
          212  +<dt><a name="4"><b class="cmd">udp_peek</b> <i class="arg">sock</i> <span class="opt">?<i class="arg">buffersize</i>?</span></a></dt>
          213  +<dd><p>Examine a packet without removing it from the buffer. Option <i class="arg">buffersize</i> specifies the 
          214  +maximum buffer size. Value must be between 0 and 16.</p>
          215  +<p>This function is not available on windows.</p></dd>
          216  +</dl>
          217  +</div>
          218  +<div id="section3" class="doctools_section"><h2><a name="section3">EXAMPLES</a></h2>
          219  +<pre class="doctools_example">
          220  +# Send data to a remote UDP socket
          221  +proc udp_puts {host port} {
          222  +    set s [udp_open]
          223  +    fconfigure $s -remote [list $host $port]
          224  +    puts $s &quot;Hello, World&quot;
          225  +    close $f
          226  +}
          227  +</pre>
          228  +<pre class="doctools_example">
          229  +# A simple UDP server
          230  +package require udp
          231  +proc udpEventHandler {sock} {
          232  +    set pkt [read $sock]
          233  +    set peer [fconfigure $sock -peer]
          234  +    puts &quot;$peer: [string length $pkt] {$pkt}&quot;
          235  +    return
          236  +}
          237  +proc udp_listen {port} {
          238  +    set srv [udp_open $port]
          239  +    fconfigure $srv -buffering none -translation binary
          240  +    fileevent $srv readable [list ::udpEventHandler $srv]
          241  +    puts &quot;Listening on udp port: [fconfigure $srv -myport]&quot;
          242  +    return $srv
          243  +}
          244  +set sock [udp_listen 53530]
          245  +vwait forever
          246  +close $sock
          247  +</pre>
          248  +<pre class="doctools_example">
          249  +# A multicast demo.
          250  +proc udpEvent {chan} {
          251  +    set data [read $chan]
          252  +    set peer [fconfigure $chan -peer]
          253  +    puts &quot;$peer [string length $data] '$data'&quot;
          254  +    if {[string match &quot;QUIT*&quot; $data]} {
          255  +        close $chan
          256  +        set ::forever 1
          257  +    }
          258  +    return
          259  +}
          260  +set group 224.5.1.21
          261  +set port  7771
          262  +set s [udp_open $port]
          263  +fconfigure $s -buffering none -blocking 0
          264  +fconfigure $s -mcastadd $group -remote [list $group $port]
          265  +fileevent $s readable [list udpEvent $s]
          266  +puts -nonewline $s &quot;hello, world&quot;
          267  +set ::forever 0
          268  +vwait ::forever
          269  +exit
          270  +</pre>
          271  +</div>
          272  +<div id="section4" class="doctools_section"><h2><a name="section4">HISTORY</a></h2>
          273  +<p>Some of the code in this extension is copied from Michael Miller's tcludp
          274  +package. (http://www.neosoft.com/tcl/ftparchive/sorted/comm/tcludp-1.0/)
          275  +Compared with Michael's UDP extension, this extension provides Windows
          276  +support and provides the ability of using 'gets/puts' to read/write
          277  +the socket. In addition, it provides more configuration ability.</p>
          278  +<p>Enhancements to support binary data and to setup the package for the Tcl
          279  +Extension Architecture by Pat Thoyts.</p>
          280  +<p>Support for IPv6 and allowing a multicast join on a specific network interface is added by Huub Eikens.</p>
          281  +</div>
          282  +<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
          283  +<p>socket(n)</p>
          284  +</div>
          285  +<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
          286  +<p>networking, socket, udp</p>
          287  +</div>
          288  +<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
          289  +<p>Copyright &copy; 1999-2000 Columbia University; all rights reserved</p>
          290  +</div>
          291  +</div></body></html>

Changes to win/makefile.vc.

    28     28   
    29     29   
    30     30   # Define the standard targets
    31     31   !include "$(_RULESDIR)\targets.vc"
    32     32   
    33     33   # Project specific targets
    34     34   
    35         -install:    default-install-demos
           35  +install:    default-install-demos default-install-docs-html
    36     36   pkgindex:   default-pkgindex
    37     37   
    38     38   # Implicit rule to generate html from man files
    39         -# NOTE: this requires doctools from tcllib
           39  +# NOTE: this requires doctools from tcllib hence it is not intended
           40  +# to be run during install. Rather, use it to generate a new version
           41  +# of HTML docs to be stored in the repository.
    40     42   DOC2HTML = $(TCLSH) "$(TOOLSDIR)\mpexpand.tcl" html
    41     43   {$(DOCDIR)}.man{$(OUT_DIR)}.html:
    42     44   	$(DOC2HTML) $< $@
    43     45           @$(TCLSH) <<
    44     46   set name $(@:\=/)
    45     47   set f [open $$name r]; set d [read $$f]; close $$f
    46     48   set d [regsub {</head>} $$d {<link rel="stylesheet" href="manpage.css" type="text/css"></head>}]
................................................................................
    47     49   set f [open $$name w]; puts -nonewline $$f $$d; close $$f
    48     50   <<
    49     51   
    50     52   .SUFFIXES: .man
    51     53   
    52     54   # Cannot use default-install-docs because we generate docs on the fly
    53     55   doc:        setup $(PRJ_DOCS)
    54         -install-docs: doc
    55         -	@echo Installing documentation to '$(DOC_INSTALL_DIR)'
    56         -	@if not exist $(DOC_INSTALL_DIR)\NUL mkdir "$(DOC_INSTALL_DIR)"
    57         -	@$(CPY) "$(DOCDIR)\manpage.css" "$(DOC_INSTALL_DIR)\" >NUL
    58         -	@for %i in ($(PRJ_DOCS)) do @$(CPY) %i "$(DOC_INSTALL_DIR)\" > NUL
    59     56   
    60     57