Provided by: tcl-udp_1.0.11-2_amd64 bug

NAME

       udp - Create UDP sockets in Tcl

SYNOPSIS

       package require Tcl  8.2

       package require udp  1.0.11

       udp_open ?port? ?reuse? ?ipv6?

       udp_conf sock host port

       udp_conf  sock  ?-myport?  ?-remote?  ?-peer?  ?-broadcast  bool?  ?-ttl count? ?-mcastadd
       "groupaddr ?netwif?"? ?-mcastdrop "groupaddr ?netwif?"? ?-mcastgroups? ?-mcastloop bool?

       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? ?reuse? ?ipv6?
              udp_open  will  open  a  UDP  socket. If a 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.

              The following keywords can be used to specify options on the opened socket.

              reuse  Using  this  keyword  sets  the  SO_REUSEADDR  socket  option  which permits
                     multiple sockets to be bound to the same address/port combination.

              ipv6   By default a IPv4 socket is created. When keyword ipv6 is specified an  IPv6
                     socket is opened.

       udp_conf sock host port
              Deprecated in favour of the standard Tcl fconfigure command.

              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? ?-mcastadd
       "groupaddr ?netwif?"? ?-mcastdrop "groupaddr ?netwif?"? ?-mcastgroups? ?-mcastloop bool?
              Deprecated in favour of the standard Tcl fconfigure command.

              In addition to being used to configure the remote host,  the  udp_conf  command  is
              used  to  obtain  information  about the UDP socket. NOTE all these options are now
              available using the standard Tcl fconfigure command.

              -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. This option is not permitted when using IPv6.

              -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.

              -mcastadd groupaddr

              -mcastadd "groupaddr netwif"

              -mcastdrop groupaddr

              -mcastdrop "groupaddr netwif"

              -mcastgroups
                     tcludp  sockets  can  support IPv4 and IPv6 multicast operations. To receive
                     multicast packets the application has to notify the operating system that it
                     should  join  a  particular multicast group. For IPv4 these are specified as
                     addresses in the range 224.0.0.0 to 239.255.255.255.

                     When specifying only the groupaddr the system  will  determine  the  network
                     interface  to  use.   Specifying the netwif will join a multicast group on a
                     specific network interface.  This is useful  on  a  multihomed  system  with
                     multiple  network  interfaces.   On  windows  you  must  specify the network
                     interface index. For other platforms the  network  interface  (e.g.  'eth0')
                     name can be specified.

                     To view the current set of multicast groups for a channel use -mcastgroups

              -mcastloop ?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.

       udp_peek sock ?buffersize?
              Examine a packet without removing it from the buffer. Option  buffersize  specifies
              the maximum buffer size. Value must be between 0 and 16.

              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.

       Support for IPv6 and allowing a multicast join on a specific network interface is added by
       Huub Eikens.

SEE ALSO

       socket(3tcl)

KEYWORDS

       networking, socket, udp

COPYRIGHT

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