NAME

       udp - Create UDP sockets in Tcl

SYNOPSIS

       package require Tcl  8.2

       package require udp  1.0

       udp_open ?port?

       udp_conf sock host port

       udp_conf sock ?-myport? ?-remote? ?-peer? ?-broadcast bool? ?-ttl count?

       udp_conf ?-mcastadd groupaddr?

       udp_conf ?-mcastdrop groupaddr?

       udp_peek sock ?buffersize?

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  udp_conf should be considered
       depreciated in favour of the standard Tcl command fconfigure.

COMMANDS

       udp_open ?port?
              udp_open will open a UDP socket. If 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
              udp_conf command to obtain the port number if required.

       udp_conf sock host port
              udp_conf in this configuration is  used  to  specify  the  remote  destination  for
              packets written to this sock. You must call this command before writing data to the
              UDP socket.

       udp_conf sock ?-myport? ?-remote? ?-peer? ?-broadcast bool? ?-ttl count?
              In addition to being used to configure the remote host,  the  udp_conf  command  is
              used to obtain information about the UDP socket.

              -myport
                     Returns the local port number of the socket.

              -remote
                     Returns  the remote hostname and port number as set using udp_conf sock host
                     port.

              -peer  Returns the remote hostname and port number for  the  packet  most  recently
                     received by this socket.

              -broadcast ?boolean?
                     UDP packets can listen and send on the broadcast address. For some systems a
                     flag must be set on the socket to use  broadcast.   With  no  argument  this
                     option  will  return  the  broadcast  setting.  With  a boolean argument the
                     setting can be modified.

              -ttl ?count?
                     The time-to-live is given as the number of router hops the  packet  may  do.
                     For  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.

       udp_conf ?-mcastadd groupaddr?

       udp_conf ?-mcastdrop groupaddr?
              tcludp sockets can support IPv4 multicast operations. To recieve 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.

       udp_peek sock ?buffersize?
              Examine  a  packet  without  removing  it  from  the  buffer.  This function is not
              available on windows.

EXAMPLES

       # Send data to a remote UDP socket
       proc udp_puts {host port} {
           set s [udp_open]
           fconfigure $s -remote [list $host $port]
           puts $s "Hello, World"
           close $f
       }

       # A simple UDP server
       package require udp

       proc udpEventHandler {sock} {
           set pkt [read $sock]
           set peer [fconfigure $sock -peer]
           puts "$peer: [string length $pkt] {$pkt}"
           return
       }

       proc udp_listen {port} {
           set srv [udp_open $port]
           fconfigure $srv -buffering none -translation binary
           fileevent $srv readable [list ::udpEventHandler $srv]
           puts "Listening on udp port: [fconfigure $srv -myport]"
           return $srv
       }

       set sock [udp_listen 53530]
       vwait forever
       close $sock

       # A multicast demo.
       proc udpEvent {chan} {
           set data [read $chan]
           set peer [fconfigure $chan -peer]
           puts "$peer [string length $data] '$data'"
           if {[string match "QUIT*" $data]} {
               close $chan
               set ::forever 1
           }
           return
       }

       set group 224.5.1.21
       set port  7771
       set s [udp_open $port]
       fconfigure $s -buffering none -blocking 0
       fconfigure $s -mcastadd $group -remote [list $group $port]
       fileevent $s readable [list udpEvent $s]
       puts -nonewline $s "hello, world"
       set ::forever 0
       vwait ::forever
       exit

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 support and provides the ability  of  using
       'gets/puts' to read/write the socket. In addition, it provides more configuration ability.

       Enhancements  to  support  binary  data  and  to  setup  the package for the Tcl Extension
       Architecture by Pat Thoyts.

SEE ALSO

       socket(3tcl)

KEYWORDS

       networking, socket, udp

COPYRIGHT

       Copyright (c) 1999-2000 Columbia University; all rights reserved