LIBUDP(3) — UNIX Programmer’s Manual

NAME

libudp − UDP user library

SYNOPSIS

#include <udp/udp.h> struct udpcon ∗
udpopen(fcon, fport, lcon, lport, tout, sbufs, rbufs)
netaddr fcon;
port_t fport;
netaddr lcon;
port_t lport;
int tout;
int sbufs;
int rbufs; udpclose(uc)
struct udpcon ∗uc; udpwrite(uc, buf, len)
struct udpcon ∗uc;
struct udp ∗buf;
int len; udpread(uc, buf, len)
struct udpcon ∗uc;
struct udp ∗buf;
int len; int udpdebug; (load with -ludp)

DESCRIPTION

libudp is a user library for creating and using UDP or User Datagram Protocol over the same network(s) that TCP/IP runs over. UDP is a "connectionless" protocol so data may be lost and it is up to the user to retransmit it, detect error conditions with remote UDP based servers and handle dead, flaky or hung connections using timeouts. The library provides the facility for creating a UDP connection that is simply based on preventing users on the same machine from getting other people’s packets by checking local port, local address, remote port and remote address. The system (not the library) checks the supplied parameters and insures that packets not specified for set of parameters are not received. Through out the rest of the document, the word connection is used to indicate this checking and is not an indication that packets will not be not lost or acked. udpopen opens a udp connection and returns a pointer to a udp connection block allocated by the library. fcon and lcon parameters specify the foreign and local host addresses respectively. If the local address is zero then preferred local address is used. If the remote host is zero then it is expected the user will supply that later when calling udpwrite and the system will allow any packet from any host to be read. fport and lport parameters specify the foreign and local host port addresses respectively. One of these is usuaully a rendez-vous or well-known-service port for types of services. If the local host port is zero then one is assigned. If the remote host port is zero then it is expected it will be set later when udpwrite is called and the system will allow any packet from any remote host port to received. sbufs and rbufs specify the number of send and receive buffers specified. A value of zero will cause the system to give you the default number of buffers. tout is used later for receiving packets and determines how long udpread will be allowed to spend trying to receive a packet. A negative value indicates udpread will wait forever, zero indicates it should return the first available packet if one exists or return immediately and a positive value indicates the number of seconds to wait before returning. udpclose closes a udp connection and deallocates the connection block. udpwrite and udpread are used to send and receive udp packets respectively. The supplied buffer address is used to send the data and is modified by udpwrite to contain any of the specified address and port parameters. The supplied length is the number of data bytes in the UDP packet data section or the length of the buffer minus the length of the UDP header in bytes which the library automatically adds and subtracts accordinlg. All the neccessary address, port and length words are byte swapped to be in the right order for UDP. The user is responsible for byte swapping any short and long words sent and received in the data section. udpdebug is a debugging word with each bit used to cause the library routines to print out various pieces of information.

UDPD_STAT
bit enables printing of various pieces of information about the network file.

UDPD_WRITE
bit enables printing of any header of all UDP packets sent before the actual write call.

UDPD_DROP
bit enables printing of an error message indicating the write call failed and the packet was dropped. All UDROP errors are automatically retried.

UDPD_READ
bit enables printing of the header for all UDP packets received.

FILES

/usr/cmu/lib/libudp.a
/usr/cmu/include/net/swap.h
/usr/cmu/include/bbnnet/netlib.h
/usr/cmu/include/bbnnet/net/net.h
/usr/cmu/include/bbnnet/net/con.h
/usr/cmu/include/bbnnet/net/udp.h
/usr/cmu/include/udp/udp.h

DIAGNOSTICS

udpopen returns zero if the network open failed or the subsequent memory allocation fails. It tries the network connection first before the memory allocation and if the memory allocation fails, it will close the network connection. udpread and udpwrite will return the number of UDP data section bytes actually received or sent respectively. If an error happens then a negative length will be returned and errno can be checked for the failure. It will return ENETSTAT in many cases and an NETGETS ioctl call will have to be done on the uc_fd field of the connection block.

BUGS

There is an operating system bug which occasionally prevents the udpread call from returning immediately. If this happens, it will return in 1 second.

HISTORY

23-May-85 Rudy Nedved (ern) at Carnegie-Mellon University
Finish document started by Glenn Marcy documenting the UDP library package created by Mark Zaremsky, Mike Accetta and Glenn Marcy.

7th Edition — 5/23/85

Museum

Related Articles