\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#391: Support for UDP Sockets in Tcl}
\date{October 26, 2011}
\author{Jeff Rogers}
\urlstyle{sf}
\setlength{\parskip}{1ex}
\setlength{\parindent}{0pt}
\def\tipversion$#1${\texttt{\$#1\$}}
\def\tiplangle#1{\ensuremath{<}}
\def\tiprangle#1{\ensuremath{>}}
\def\tipbar#1{\ensuremath{|}}
\def\tipmail#1#2{\(\langle\){\small\expandafter\url{#1@#2}}\(\rangle\)}
\ifx\pdfoutput\undefined
\newcommand{\tipimage}[2]{\typeout{Make sure you download #1.eps}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.eps}}{\includegraphics[width=0.8\textwidth]{#1.eps}}}
\newcommand{\tipxref}[1]{}
\newcommand{\tipxrefend}{}
\else
\newcommand{\tipimage}[2]{\typeout{Make sure you create #1.pdf}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.pdf}}{\includegraphics[width=0.8\textwidth]{#1.pdf}}}
\pdfcatalog{/PageMode /UseOutlines}
\newcommand{\tipxref}[1]{\pdfannotlink attr {/C [0.5 0.5 1.0] /Border [0 0 1]} goto name {#1}}
\newcommand{\tipxrefend}{\pdfendlink}
\fi
\newenvironment{tipabstract}{\begin{abstract}}{\end{abstract}}
\begin{document}\maketitle
\begin{center}\begin{tabularx}{\linewidth}{|r@{: }X|}\hline
\textbf{TIP \#391}&\textbf{Support for UDP Sockets in Tcl}\\\hline
Author&

Jeff Rogers \tipmail{dvrsn}{diphi.com}
\\
Created&Wednesday, \(\text{26}^{\text{th}}\) October 2011\\
Type&Project\\
Tcl Version&\(8.7\)\\
State&Withdrawn\\
Vote&Pending\\
Version&\tipversion$Revision: 1.3 $\\
Post History&\\
Obsoleted By&409\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This proposal is to add UDP socket support to the core in a clean and unobtrusive way.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

UDP is used for sending datagrams over the internet, which is an integral part of a number of protocols, notably including direct DNS queries in the majority of deployment. Thus, it is useful to be able have Tcl able to send and receive messages via UDP sockets, filling out a signficant missing feature.

UDP sockets have the same basic needs as tcp sockets --- creating, reading, writing. So it follows that they could be handled by the same basic commands.

\section{Specification}

The \textbf{socket} command should have a flag, \textbf{-udp}, added. This should work for both client and server sockets.

\begin{quote}
\textbf{socket -udp} ?\textbf{-myaddr} \textit{addr}? ?\textbf{-myport} \textit{port}? \textit{host port}
\end{quote}

\begin{quote}
\textbf{socket -udp -server} \textit{command} ?\textbf{-myaddr} \textit{addr}? \textit{port}
\end{quote}

To complement this, the sockets created by the above commands will have an additional configuration option, \textbf{-peeraddr}. This is a read/write option. It is used to set the peer address before a write, and to retrieve the peer address after a read. The peer address should persist until it is changed by a read or fconfigure.

When used on a UDP socket, \textbf{puts} sends a single message (sendmsg). If the data is too large to fit in a single message then an error is raised.

When reading from a udp socket, the data retuend will only ever be the contents of a single message in a single operation. Thus, \textbf{read} will return one entire message, and \textbf{read} with a bytecount or \textbf{gets} will read a new message into their buffer iff it is completely empty, and will return the requested data from that buffer.

Readable and writable fileevents should work naturally. 

\section{Example Usage}
\begingroup\small\begin{verbatim}
set udpsock [socket -udp 8.8.8.8 53]

fconfigure $udpsock -peeraddr {8.8.8.8 53}
puts $udpsock $packet

set packet [read $udpsock]
set peer [fconfigure $udpsock -peeraddr]
\end{verbatim}
\endgroup

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

\textit{TIP AutoGenerator --- written by Donal K. Fellows}
\end{document}
