udp

udp(n)                                                                    udp(n)



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(n)

KEYWORDS
       networking, socket, udp

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




Tcl UDP extension                    1.0.11                               udp(n)