/doc/net.tex

%
% Copyright (c) 1997-1998, 2000, 2001 University of Utah and the Flux Group.
% All rights reserved.
% 
% The University of Utah grants you the right to copy and reproduce this
% document or portions thereof for academic, research, evaluation, and
% personal use only, provided that (1) the title page appears prominently,
% and (2) these copyright and permission notices are retained in all copies.
% To arrange for alternate terms, contact the University of Utah at
% csl-dist@cs.utah.edu or +1-801-585-3271.
%
% -*- LaTeX -*-

\label{net}

\section{Introduction}

	The \oskit{} networking framework encompasses a collection of COM
	interfaces used by the client operating system to invoke the 
	networking libraries.
	The individual networking libraries supply additional interfaces to
	the client operating system for initialization, and may supply
	additional interfaces for supporting extended features unique to
	particular networking protocol implementations.

%	COM is described at 
%%	\htmladdnormallinkfoot{http://www.microsoft.com/oledev/olecom/title.htm}%
%		{http://www.microsoft.com/oledev/olecom/title.htm}
%	and in
%	chapter (\ref{com}).

	\emph{At this point, we have only one interface, the oskit_socket 
	interface, defined. Additional interfaces for configuration, 
	routing, etc., are future work.}

\apiintf{oskit_socket}{Socket Interface}

	The \texttt{oskit_socket} COM interface defines an interface which
	capture the semantics of a socket as defined in the corresponding
	POSIX/CAE standards.
	The \texttt{oskit_socket} COM interface inherits from 
	\texttt{oskit_posixio}. It can be queried for an \texttt{oskit_stream} 
	interface. This query will always be successful, but the resulting
	\texttt{oskit_stream} instance might not support all methods.
	Generally, at least \texttt{read} and \texttt{write} will be supported.
	The \texttt{oskit_socket} COM interface provides in addition to 
	the \texttt{oskit_posixio} COM interface the following methods:

\begin{csymlist}
\item[accept]	
	accept a connection on a socket

\item[bind]
	bind a name to a socket

\item[connect]
	initiate a connection on a socket

\item[shutdown]
	shut down part of a full-duplex connection

\item[listen]
	listen for connections on a socket	

\item[getsockname]
	get socket name

\item[getpeername]
	get name of connected peer

\item[getsockopt]
	get options on sockets

\item[setsockopt]
	set options on sockets

\item[sendto]
	send a message from a socket

\item[recvfrom]
	receive a message from a socket

\item[sendmsg]
	send a message from a socket

\item[recvmsg]
	receive a message from a socket

\end{csymlist}

	Note that these methods are not minimal, but correspond very 
    closely to the traditional BSD interfaces.

    \begin{quote}
	{\bf Note:} the following paragraphs have a certain likelihood
	to change. The main reason for this is the obviously undesirable
	connection between the way socket factories and the socket interface
	interact. On a more positive note, everything right now is so
	close to the BSD interfaces that the reader familiar with those
	shouldn't have any problems understanding these.
    \end{quote}

\api{oskit_socket_factory_t}{socket factories}
\begin{apisyn}
        \cinclude{oskit/net/socket.h}

	\funcproto oskit_error_t 
		oskit_socket_factory_create(
		    oskit_socket_factory_t *factory,
		    oskit_u32_t domain, 
		    oskit_u32_t type, 
		    oskit_u32_t protocol,
		    \outparam oskit_socket_t **newsocket);
\end{apisyn}

\begin{apidesc}
    Socket instances are created by \emph{socket factories}. 

    A socket factory is an instance of the \texttt{oskit_socket_factory}
    COM interface.  Implementations of this interface will be provided
    by the networking stack(s) included in the \oskit{}.
    This interface implements a single method corresponding to the 
    \texttt{socket(2)} call in addition to the \texttt{oskit_iunknown}
    interface.

    Each instance of socket has a type and a protocol associated with it. 
    This type and protocol is given to the socket by its factory, and
    cannot be changed during the lifetime of that socket instance.
\end{apidesc}

\begin{apiparm}
	\item[factory] The socket factory used to create this socket.

	\item[domain] The \emph{domain} parameter specifies a communications
	domain within which communication will take place; 
	this selects the protocol family which should be used.
	Some common formats are

	\begin{tabular}{ll}
	\texttt{OSKIT_PF_LOCAL}     &   
		Host-internal protocols \\
	\texttt{OSKIT_PF_INET} 	   &
		DARPA Internet protocols \\
	\texttt{OSKIT_PF_ISO}       &   
		ISO protocols \\
	\texttt{OSKIT_PF_CCITT}     &   
		ITU-T protocols, like X.25 \\
	\texttt{OSKIT_PF_NS}        &   
		Xerox Network Systems protocols \\
	\end{tabular}

	\texttt{OSKIT_PF_INET} is the only format for 
	    which the \oskit{} currently contains an implementation.

	\item[type] The socket will have the indicated \emph{type}, which
	specifies the semantics of communication.  Currently defined types are

	\begin{tabular}{ll}
	\texttt{OSKIT_SOCK_STREAM}    &       stream socket \\
	\texttt{OSKIT_SOCK_DGRAM}     &       datagram socket \\
	\texttt{OSKIT_SOCK_RAW}       &       raw-protocol interface \\
	\texttt{OSKIT_SOCK_RDM}       &       reliably-delivered message \\
	\texttt{OSKIT_SOCK_SEQPACKET} &       sequenced packet stream \\
	\end{tabular}

	An \texttt{OSKIT_SOCK_STREAM} type provides sequenced, reliable, two-way
	connection based byte streams.  An out-of-band data transmission 
	mechanism may be supported.  An \texttt{OSKIT_SOCK_DGRAM} socket supports
	datagrams (connectionless, unreliable messages of a fixed (typically 
	small) maximum length).
	An \texttt{OSKIT_SOCK_SEQPACKET} socket may provide a sequenced, 
	reliable, two-way connection-based data transmission path for
	datagrams of fixed maximum length.
	\texttt{OSKIT_SOCK_RAW} sockets provide access to internal network 
	protocols and interfaces.

	\item[protocol]
	The \emph{protocol} specifies a particular protocol to be used with the
	socket.
	Normally only a single protocol exists to support a particular socket
	type within a given protocol family.  However, it is possible that 
	many protocols may exist, in which case a particular protocol must 
	be specified. The protocol number to use is particular to the
	communication domain in which communication is to take place.

	Protocols for the \texttt{OSKIT_PF_INET} protocol family are defined 
	in \texttt{oskit/c/netinet/in.h}.

	\item[newsocket] The new \texttt{oskit_socket_t} instance that
		was created.
\end{apiparm}

\begin{apiret}
	Returns 0 on success, or an error code specified in
	{\tt <oskit/error.h>}, on error.
\end{apiret}

%
% accept()
%

\api{accept}{accept a connection on a socket}
\begin{apisyn}
	\cinclude{oskit/net/socket.h}

	\funcproto oskit_error_t
	oskit_socket_accept(oskit_socket_t *s, 
		\outparam struct oskit_sockaddr *name,
		\inoutparam oskit_size_t *anamelen,
		\outparam struct oskit_socket **newopenso);
\end{apisyn}

\begin{apidesc}
	The \texttt{accept} method extracts the first connection request
	on the queue of pending connections, creates a new socket 
	with the same properties of s and returns it.
	The socket must have been bound to an address with \texttt{bind}
	and it must be listening for connections after a \texttt{listen}.

	If no pending connections are present on the queue, \texttt{accept} 
	blocks the caller until a connection is present.
\end{apidesc}

\begin{apiparm}
	\item[s]
		The socket from which connections are to accepted.

	\item[name]
		Filled with the address of the connecting entity as known
		to the communication layer.

	\item[anamelen]
		Initially, the amount of space pointed to by name,
		on return it will contain the amount actually used.

	\item[newopenso]
		Newly created socket.

\end{apiparm}

\begin{apiret}
	Returns 0 on success, or an error code specified in
	{\tt <oskit/error.h>}, on error.
\end{apiret}

%
% bind()
%

\api{bind}{bind a name to a socket}
\begin{apisyn}
        \cinclude{oskit/net/socket.h}

        \funcproto oskit_error_t
        oskit_socket_bind(oskit_socket_t *s,
		const struct oskit_sockaddr *name,
		oskit_size_t namelen);
\end{apisyn}

\begin{apidesc}
	\texttt{bind} assigns a name to an unnamed socket.
	When a socket is created, it exists in a name space (address family) 
	but has no name assigned. \texttt{bind} requests that 
	\emph{name} be assigned to the socket.

\end{apidesc}

\begin{apiparm}
        \item[s]
                The socket to which a name is to be bound.

        \item[name]
                The name to which the socket is to be bound.

        \item[namelen]
                The length of \emph{name} in bytes.

\end{apiparm}

\begin{apiret}
        Returns 0 on success, or an error code specified in
        {\tt <oskit/error.h>}, on error.
\end{apiret}

%
% connect()
%

\api{connect}{initiate a connection on a socket}
\begin{apisyn}
        \cinclude{oskit/net/socket.h}

        \funcproto oskit_error_t
        oskit_socket_connect(oskit_socket_t *s,
		 const struct oskit_sockaddr *name,
		 oskit_size_t namelen);
\end{apisyn}

\begin{apidesc}
	If \emph{s} is of type \texttt{OSKIT_SOCK_DGRAM}, this call
	specifies the peer with which the socket is to be associated; this 
	address is that to which datagrams are to be sent, and the only address
	from which datagrams are to be received.  If the socket is of type
	\texttt{OSKIT_SOCK_STREAM}, this call attempts to make a connection 
	to another socket.
	The other socket is specified by \emph{name}, which is an address 
	in the communications space of the socket. 
	Each communications space interprets the \emph{name} parameter
	in its own way. Generally, stream sockets may successfully
	\texttt{connect} only once; datagram sockets may use 
	\texttt{connect} multiple times to change their association.  
	Datagram sockets may dissolve the association by connecting to 
	an invalid address, such as a null address.
\end{apidesc}

\begin{apiparm}
        \item[s]
                The socket from which the connection is to be initiated.

        \item[name]
                The address of the entity to which the connection is
		to be established. 

	\item[namelen]
		The length of \emph{name} in bytes.

\end{apiparm}

\begin{apiret}
        Returns 0 on success, or an error code specified in
        {\tt <oskit/error.h>}, on error.
\end{apiret}

%
% shutdown()
%

\api{shutdown}{shut down part of a full-duplex connection}
\begin{apisyn}
        \cinclude{oskit/net/socket.h}

        \funcproto oskit_error_t
        oskit_socket_shutdown(oskit_socket_t *s,
		 oskit_u32_t how);
\end{apisyn}

\begin{apidesc}
	The \texttt{shutdown} call causes all or part of a full-duplex 
	connection on the socket \emph{s} to be shut down.  
\end{apidesc}

\begin{apiparm}
        \item[s]
                The socket which is to be shut down.

        \item[how]
                Specifies what is to be disallowed:
		\begin{itemize}
		\item[how = 0]	receives
		\item[how = 1]	sends
		\item[how = 2]	sends and receives
		\end{itemize}

\end{apiparm}

\begin{apiret}
        Returns 0 on success, or an error code specified in
        {\tt <oskit/error.h>}, on error.
\end{apiret}

%
% listen()
%

\api{listen}{listen for connections on a socket}
\begin{apisyn}
        \cinclude{oskit/net/socket.h}

        \funcproto oskit_error_t
        oskit_socket_listen(oskit_socket_t *s,
		 oskit_u32_t backlog);
\end{apisyn}

\begin{apidesc}
	A willingness to accept incoming connections and a queue limit 
	for incoming connections are specified with \texttt{listen},
	and then the connections are accepted with \texttt{accept}.
	The \texttt{listen} call applies only to sockets of type
	\texttt{OSKIT_SOCK_STREAM} or  \texttt{OSKIT_SOCK_SEQPACKET}.

	The \emph{backlog} parameter defines the maximum length the queue of
	pending connections may grow to. 
	If a connection request arrives with the queue full the client may 
	receive an error with an indication of connection refused, or, if
	the underlying protocol supports retransmission, the request may
	be ignored so that retries may succeed.
\end{apidesc}

\begin{apiparm}
        \item[s]
                The socket where connections will be accepted.

        \item[backlog]
		Maximum number of pending connections.

\end{apiparm}

\begin{apiret}
        Returns 0 on success, or an error code specified in
        {\tt <oskit/error.h>}, on error.
\end{apiret}

%
% getsockname()
%

\api{getsockname}{get socket name}
\begin{apisyn}
        \cinclude{oskit/net/socket.h}

        \funcproto oskit_error_t
        oskit_socket_getsockname(oskit_socket_t *s,
		\outparam struct oskit_sockaddr *asa,
                \inoutparam oskit_size_t *anamelen);
\end{apisyn}

\begin{apidesc}
	\texttt{getsockname} returns the current name for the specified socket.
\end{apidesc}

\begin{apiparm}
        \item[s]
                The socket whose name is to be determined.

        \item[name]
                Contains the name of the socket upon return.

        \item[anamelen]
                Initially, the amount of space pointed to by name,
                on return it will contain the amount actually used, i.e.,
		the actual size of the name.

\end{apiparm}

\begin{apiret}
        Returns 0 on success, or an error code specified in
        {\tt <oskit/error.h>}, on error.
\end{apiret}

%
% getpeername()
%

\api{getpeername}{get name of connected peer}
\begin{apisyn}
        \cinclude{oskit/net/socket.h}

        \funcproto oskit_error_t
        oskit_socket_getpeername(oskit_socket_t *s,
		\outparam struct oskit_sockaddr *asa,
		\inoutparam oskit_size_t *anamelen);
\end{apisyn}

\begin{apidesc}
	\texttt{getpeername} returns the name of the peer connected to socket
	\emph{s}. 
\end{apidesc}

\begin{apiparm}
        \item[s]
                The socket connected to the peer whose name is to be returned. 

        \item[name]
		Contains the peer's name upon return.

        \item[anamelen]
                Initially, the amount of space pointed to by name,
                on return it will contain the amount actually used.
		The name is truncated if the buffer provided is too small.

\end{apiparm}

\begin{apiret}
        Returns 0 on success, or an error code specified in
        {\tt <oskit/error.h>}, on error.
\end{apiret}

%
% getsockoption()
%

\api{getsockopt}{get options on sockets}
\begin{apisyn}
        \cinclude{oskit/net/socket.h}

        \funcproto oskit_error_t
        oskit_socket_getsockopt(oskit_socket_t *s,
		 oskit_u32_t level,
		 oskit_u32_t name, 
		\outparam void *val,
		\inoutparam oskit_size_t *valsize);
\end{apisyn}

\begin{apidesc}
	Get the current options
	associated with a socket.  Options may exist at multiple protocol 
	levels. 
\end{apidesc}

\begin{apiparm}
        \item[s]
                The socket whose options are to be queried or set.

        \item[level]
		The level at which the option resides.
		See \texttt{setsockopt} for details.

        \item[name]
		\emph{name} and any specified options are passed
		uninterpreted to the appropriate protocol module
		for interpretation.
		See \texttt{setsockopt} for details.

        \item[val, valsize]
		The parameters \emph{val} and \emph{valsize}
		are used to access option values.
		For \texttt{getsockopt}, \emph{valsize} initially contains the 
		size of the buffer pointed to by \emph{val},
		and modified on return
		to indicate the actual size of the value returned.
		If no option value is to be supplied or returned,
		\emph{val} may be \texttt{NULL}.
\end{apiparm}

\begin{apiret}
        Returns 0 on success, or an error code specified in
        {\tt <oskit/error.h>}, on error.
\end{apiret}

\api{setsockopt}{set options on sockets}
\begin{apisyn}
        \cinclude{oskit/net/socket.h}

        \funcproto oskit_error_t
        oskit_socket_setsockopt(oskit_socket_t *s,
		 oskit_u32_t level,
		 oskit_u32_t name, 
		 const void *val, 
		 oskit_size_t valsize);
\end{apisyn}

\begin{apidesc}
	\texttt{setsockopt} manipulates the options
	associated with a socket.  Options may exist at multiple protocol 
	levels. 

\end{apidesc}

\begin{apiparm}
        \item[s]
                The socket whose options are to be queried or set.

        \item[level] When manipulating socket options the level at 
	which the option resides and the name of the option must be 
	specified.  To manipulate options at the socket level, \emph{level} 
	is specified as \texttt{OSKIT_SOL_SOCKET}. To manipulate options
	at any other level the protocol number of the appropriate protocol 
	controlling the option is supplied.  For example, to indicate that an
	option is to be interpreted by the TCP protocol, \emph{level} 
	should be set to \texttt{IPPROTO_TCP}.

        \item[name]
	\emph{name} and any specified options are passed uninterpreted to the
	appropriate protocol module for interpretation.
	Definitions for socket level options are described below.
	Options at other protocol levels vary in format and name.

	Most socket-level options utilize an \texttt{int} parameter for 
	\emph{val}. For \texttt{setsockopt}, the parameter should be
	non-zero to enable a boolean option, or zero if the option is 
	to be disabled.
	\texttt{OSKIT_SO_LINGER} uses a \texttt{struct oskit_linger}
	parameter, which specifies the desired state of the option
	and the linger interval (see below).
	%% is that really so?
	\texttt{OSKIT_SO_SNDTIMEO} and \texttt{OSKIT_SO_RCVTIMEO}
	use a \texttt{struct timeval} parameter, defined in 
	\texttt{<oskit/c/sys/time.h>}

	The following options are recognized at the socket level.  Except as 
	noted, each may be examined with \texttt{getsockopt} and set with
	\texttt{setsockopt}.

	\begin{tabular}{ll}
           \texttt{OSKIT_SO_DEBUG} &
		        enables recording of debugging information \\
           \texttt{OSKIT_SO_REUSEADDR} &
		    enables local address reuse \\
           \texttt{OSKIT_SO_REUSEPORT} &
		    enables duplicate address and port bindings \\
           \texttt{OSKIT_SO_KEEPALIVE} &
		    enables keep connections alive \\
           \texttt{OSKIT_SO_DONTROUTE} &
		    enables routing bypass for outgoing messages \\
           \texttt{OSKIT_SO_LINGER} &
		       linger on close if data present \\
           \texttt{OSKIT_SO_BROADCAST} &
		    enables permission to transmit broadcast messages \\
           \texttt{OSKIT_SO_OOBINLINE} &
		    enables reception of out-of-band data in band \\
           \texttt{OSKIT_SO_SNDBUF} &
		       set buffer size for output \\
           \texttt{OSKIT_SO_RCVBUF} &
		       set buffer size for input \\

           \texttt{OSKIT_SO_SNDLOWAT} &
		     set minimum count for output \\
           \texttt{OSKIT_SO_RCVLOWAT} &
		     set minimum count for input \\
           \texttt{OSKIT_SO_SNDTIMEO} &
		     set timeout value for output \\
           \texttt{OSKIT_SO_RCVTIMEO} &
		     set timeout value for input \\
           \texttt{OSKIT_SO_TYPE} &
		         get the type of the socket (get only) \\
           \texttt{OSKIT_SO_ERROR} &
		        get and clear error on the socket (get only) \\
	\end{tabular}

	\texttt{OSKIT_SO_DEBUG} enables debugging in the underlying 
   	protocol modules.
	\texttt{OSKIT_SO_REUSEADDR} indicates that the rules used in 
	validating addresses supplied in \texttt{bind}
	should allow reuse of local addresses.
	\texttt{OSKIT_SO_REUSEPORT} allows completely duplicate bindings 
	by multiple clients if they all set \texttt{OSKIT_SO_REUSEPORT} 
	before binding the port. This option permits multiple instances
	of a program to each receive UDP/IP multicast or
	broadcast datagrams destined for the bound port.
	\texttt{OSKIT_SO_KEEPALIVE} enables the periodic transmission of 
	messages on a connected socket. Should the
	connected party fail to respond to these messages, the connection is 
	considered broken and clients using the socket are notified
	when attempting to send data.
	% XXX:
	% ...via a SIGPIPE signal. Yeah, right.
	\texttt{OSKIT_SO_DONTROUTE} indicates that outgoing 
	messages should bypass the standard routing facilities.
	Instead, messages are directed to the appropriate network interface
	according to the network portion of the destination address.

	\texttt{OSKIT_SO_LINGER} controls the action taken when unsent 
	messages are queued on a socket and the socket is released.
	If the socket promises reliable delivery of data and 
	\texttt{OSKIT_SO_LINGER} is set, the system will block on the last
	\texttt{release} attempt until it is able to transmit the data
	or until it decides it is unable to deliver the information
	(a timeout period, termed the linger interval, is specified in the 
	\texttt{setsockopt} call when \texttt{OSKIT_SO_LINGER} is requested.
	If \texttt{OSKIT_SO_LINGER} is disabled, the last \texttt{release}
	will succeed immediately. % is that really true???

	The option \texttt{OSKIT_SO_BROADCAST} requests permission to send 
	broadcast datagrams on the socket.  Broadcast was a privileged 
	operation in earlier versions of the system.  With protocols that 
	support out-of-band data, the \texttt{OSKIT_SO_OOBINLINE} option 
	requests that out-of-band data be placed in the normal data input 
	queue as received; it will then be accessible with \texttt{recv}
	or \texttt{read} calls without the \texttt{OSKIT_MSG_OOB} flag.  
	Some protocols always behave as if this option were set.  

	\texttt{OSKIT_SO_SNDBUF} and \texttt{OSKIT_SO_RCVBUF} are options 
	to adjust the normal buffer sizes allocated for output and input 
	buffers, respectively.  The buffer size may be increased for 
	high-volume connections, or may be decreased to limit the possible 
	backlog of incoming data.  An absolute limit may be places on 
	these values.

	\texttt{OSKIT_SO_SNDLOWAT} is an option to set the minimum count 
	for output operations. Most output operations process all of the 
	data supplied by the call, delivering data to the protocol for 
	transmission and blocking as necessary for flow control.  
	Nonblocking output operations will process as much data as permitted 
	subject to flow control without blocking, but will process no data 
	if flow control does not allow the smaller of the low water
	mark value or the entire request to be processed.  

	% See, there you go: we NEED select().
	% A select(2) operation
        % testing the ability to write to a socket will return true only if 
	% the low water mark amount could be processed.  

	The default value for \texttt{OSKIT_SO_SNDLOWAT}
	is set to a convenient size for network efficiency, often 1024.

        \texttt{OSKIT_SO_RCVLOWAT} is an option to set the minimum count 
	for input operations.
	In general, receive calls will block until any (non-zero) amount of data
	is received, then return with the smaller of the amount available or the
	amount requested.  The default value for \texttt{OSKIT_SO_RCVLOWAT} is 1.
	If \texttt{OSKIT_SO_RCVLOWAT} is set to a larger value, blocking 
	receive calls normally wait until they have received the smaller of 
	the low water mark value or the requested amount.  Receive calls may 
	still return less than the low water mark if an error occurs, a signal 
	is caught, or the type of data next in the receive queue is different 
	than that returned.

	\texttt{OSKIT_SO_SNDTIMEO} is an option to set a timeout value for 
	output operations.
	It accepts a \texttt{struct timeval} parameter with the number 
	of seconds and microseconds used to limit waits for output operations 
	to complete.  If a send operation has blocked for this much time, 
	it returns with a partial count or with the error 
	\texttt{OSKIT_EWOULDBLOCK} if no data were sent.  

	% FreeBSD says: In the current implementation, 
	This timer is restarted each time additional data 
	are delivered to the protocol, implying that the limit applies to 
	output portions ranging in size from the low water mark to the 
	high water mark for output.  

	\texttt{OSKIT_SO_RCVTIMEO} is an option to set a timeout value for 
	input operations.  It accepts a struct timeval parameter with the 
	number of seconds and microseconds used to limit waits for input 
	operations to complete.

	% FreeBSD says: In the current implementation, 
	This timer is restarted each time additional data are received by 
	the protocol, and thus the limit is in effect
	an inactivity timer.  If a receive operation has been blocked for this
	much time without receiving additional data, it returns with a short
	count or with the error \texttt{OSKIT_EWOULDBLOCK} if no data were 
	received.

	Finally, \texttt{OSKIT_SO_TYPE} and \texttt{OSKIT_SO_ERROR} are options 
	used only with \texttt{getsockopt}.
	\texttt{OSKIT_SO_TYPE} returns the type of the socket, such as 
	\texttt{OSKIT_SOCK_STREAM}.  
	\texttt{OSKIT_SO_ERROR} returns any 
	pending error on the socket and clears the error status.  
	It may be used to check for asynchronous errors on connected datagram 
	sockets or for other asynchronous errors.
	
        \item[val, valsize]
	The parameters \emph{val} and \emph{valsize}
	are used to access option values for \texttt{setsockopt}.
	If no option value is to be supplied or returned, \emph{val} may be
	\texttt{NULL}.

\end{apiparm}

\begin{apiret}
        Returns 0 on success, or an error code specified in
        {\tt <oskit/error.h>}, on error.
\end{apiret}

%
% recvfrom, recvmsg
%

\api{recvfrom, recvmsg}{receive a message from a socket}
\begin{apisyn}
        \cinclude{oskit/net/socket.h}

	\funcproto oskit_error_t
	oskit_socket_recvfrom(oskit_socket_t *s, 
			    \outparam void *buf,
                            oskit_size_t len, oskit_u32_t flags,
                            \outparam struct oskit_sockaddr *from, 
			    \inoutparam oskit_size_t *fromlen,
                            \outparam oskit_size_t *retval);

        \funcproto oskit_error_t
        oskit_socket_recvmsg(oskit_socket_t *s,
                            \inoutparam struct oskit_msghdr *msg, 
			    oskit_u32_t flags,
                            \outparam oskit_size_t *retval);
\end{apisyn}

\begin{apidesc}
	\texttt{recvfrom} and \texttt{recvmsg} are used to receive messages
	from a socket, and may be used to receive data on a socket whether 
	or not it is connection-oriented.

	\textbf{Note: } The \texttt{recv} library function 
	can be implemented using \texttt{recvfrom} with a nil \emph{from}
	parameter. 
	% BSD says:
	% As it is redundant, it may not be supported in future releases.

	If no messages are available at the socket, the receive call waits 
	for a message to arrive.
	% BSD says:
	% unless the socket is nonblocking (see fcntl(2))  in
	% which case the value -1 is returned and the external variable 
	% errno set to EAGAIN. 
	The receive calls normally return any data available,
	up to the requested amount, rather than waiting for receipt of the 
	full amount equested; this behavior is affected by the socket-level
	options \texttt{OSKIT_SO_RCVLOWAT} and \texttt{OSKIT_SO_RCVTIMEO}
	described in \texttt{getsockopt}.

	% BSD says:
	% The select(2) call may be used to determine when more data arrive.

\end{apidesc}

\begin{apiparm}
        \item[s]
                The socket from the message is to be received.

	\item[buf] Buffer in which the message is to be copied.

	\item[len] Length of the buffer provided.

	\item[flags]
		The \emph{flags} argument is formed by or'ing one or more 
		of the values:

		\begin{tabular}{ll}
		\texttt{OSKIT_MSG_OOB} 	 & process out-of-band data
		    \\
		\texttt{OSKIT_MSG_PEEK} 	 & peek at incoming message
		    \\
		\texttt{OSKIT_MSG_WAITALL}& wait for full request or error
		    \\
		\end{tabular}

		The \texttt{OSKIT_MSG_OOB} flag requests receipt of 
		out-of-band data that would not be received in the normal 
		data stream.
		Some protocols place expedited data
		at the head of the normal data queue, and thus this flag cannot
		be used with such protocols.
		The \texttt{OSKIT_MSG_PEEK} flag causes the receive 
		operation to return data from the beginning of the receive
		queue without removing that data from the queue.
		Thus, a subsequent receive call will return the same data.
		The \texttt{OSKIT_MSG_WAITALL} flag requests that the operation
		block until the full request is satisfied. 
		However, the call may still return less data than requested if
		an error or disconnect occurs, or the next data to be received 
		is of a different type than that returned.

        \item[from]
		If \emph{from} is non-nil, and the socket is not 
		connection-oriented, the source address of the message is
		filled in.  
	\item[fromlen]
		Initialized to the size of the buffer associated with 
		\emph{from}, and modified on return to indicate the actual 
		size of the address stored there.
	
	\item[msg] The \texttt{recvmsg} method uses a 
		\texttt{struct oskit_msghdr} structure to minimize the number
		of directly supplied parameters. 

\cstruct{oskit_msghdr}{
        oskit_addr_t     msg_name;               /* optional address */
        oskit_u32_t      msg_namelen;            /* size of address */
        struct  oskit_iovec *msg_iov;            /* scatter/gather array */
        oskit_u32_t      msg_iovlen;             /* \# elements in msg_iov */
        oskit_addr_t     msg_control;            /* ancillary data, see below */
        oskit_u32_t      msg_controllen;         /* ancillary data buffer len */
        oskit_u32_t      msg_flags;              /* flags on received message */
};

	Here \emph{msg_name} and \emph{msg_namelen} 
	specify the destination address if the socket is unconnected;
	\emph{msg_name} may be given as a null pointer if no names are desired 
	or required.
	\emph{msg_iov} and \emph{msg_iovlen} describe scatter gather
	locations. 
	
	\emph{msg_control}, which has length \emph{msg_controllen},
	points to a buffer for other protocol control related
	messages or other miscellaneous ancillary data.

    % BSD says:
    % The messages are of the form:
    %
    % struct cmsghdr {
    %     u_int   cmsg_len;       /* data byte count, including hdr */
    %     int     cmsg_level;     /* originating protocol */
    %     int     cmsg_type;      /* protocol-specific type */
    % /* followed by
    %     u_char  cmsg_data[]; */
    % };
    % As an example, one could use this to learn of changes in the data-stream
    % in XNS/SPP, or in ISO, to obtain user-connection-request data by request-
    % ing a recvmsg with no data buffer provided immediately after an accept()
    % call.
    %
    % Open file descriptors are now passed as ancillary data for AF_UNIX domain
    % sockets, with cmsg_level set to SOL_SOCKET and cmsg_type set to
    % SCM_RIGHTS.

	The \emph{msg_flags} field is set on return according to the message 
	received. \texttt{OSKIT_MSG_EOR}  indicates end-of-record; the data 
	returned completed a record (generally used with sockets of type
	\texttt{OSKIT_SOCK_SEQPACKET}). \texttt{OSKIT_MSG_TRUNC} indicates
	that the trailing portion of a datagram was discarded because
	the datagram was larger than the buffer supplied.
	\texttt{OSKIT_CMSG_TRUNC} indicates that some
	control data were discarded due to lack of space in the
	buffer for ancillary data. \texttt{OSKIT_MSG_OOB} is returned to
	indicate that expedited or out-of-band data were received.

        \item[retval]
                Contains the number of characters received, i.e., the total
		length of the message upon return.
		If a message is too long to fit in the supplied buffer,
		excess bytes may be discarded depending on the type of socket 
		the message is received from.

\end{apiparm}

\begin{apiret}
        Returns 0 on success, or an error code specified in
        {\tt <oskit/error.h>}, on error.
\end{apiret}

%
% sendto, sendmsg
%

\api{sendto, sendmsg}{send a message from a socket}
\begin{apisyn}
        \cinclude{oskit/net/socket.h}

        \funcproto oskit_error_t
	oskit_socket_sendto(oskit_socket_t *s, 
		    const void *buf,
                    oskit_size_t len, 
		    oskit_u32_t flags,
                    const struct oskit_sockaddr *to, 
		    oskit_size_t tolen,
                    \outparam oskit_size_t *retval);

        \funcproto oskit_error_t
        oskit_socket_sendmsg(oskit_socket_t *s,
                    const struct oskit_msghdr *msg, 
		    oskit_u32_t flags,
                    \outparam oskit_size_t *retval);

\end{apisyn}

\begin{apidesc}
	\texttt{sendto}, \texttt{sendmsg} are used to transmit
	a message to another socket. 
	The C library \texttt{send} may be implemented by passing a
	NULL \emph{to} parameter. It may be used only when the socket 
	is in a connected state, while \texttt{sendto} and 
	\texttt{sendmsg} may generally be used at any time.

	Send will block if no messages space is available at the socket 
	to hold the message to be transmitted.
	% in BSD 
	% unless the socket has been placed in non-blocking I/O mode.
	% The select(2) call may be used to determine when it is possible 
	% to send more data.

\end{apidesc}

\begin{apiparm}
        \item[s]
                The socket from which the message is to be sent.

	\item[buf]

	\item[len] \emph{len} gives the length of the message.
	If the message is too long to pass atomically through the underlying
	protocol, the error \texttt{OSKIT_EMSGSIZE} is returned,
	and the message is not transmitted.

	\item[flags]
	The \emph{flags}
	parameter may include one or more of the following:

	\begin{tabular}{ll}
	\texttt{OSKIT_MSG_OOB} &
	            process out-of-band data \\
        \texttt{OSKIT_MSG_PEEK} &
	            peek at incoming message \\
        \texttt{OSKIT_MSG_DONTROUTE} &
		    bypass routing, use direct interface \\
        \texttt{OSKIT_MSG_EOR} &
	            data completes record 	\\
        \texttt{OSKIT_MSG_EOF} &
	            data completes transaction \\
	\end{tabular}
	
	The flag \texttt{OSKIT_MSG_OOB} is used to send ``out-of-band''
	data on sockets that support this notion 
	(e.g. \texttt{OSKIT_SOCK_STREAM}); the underlying protocol
	must also support ``out-of-band'' data.
	\texttt{OSKIT_MSG_EOR} is used to indicate a record
	 mark for protocols which support the concept.
	\texttt{OSKIT_MSG_EOF}  requests that the
	sender side of a socket be shut down, and that an appropriate
	indication be sent at the end of the specified data;
	this flag is only implemented for \texttt{OSKIT_SOCK_STREAM}
	sockets in the \texttt{OSKIT_PF_INET} protocol family.

	\item[to, tolen]
	  The address of the target is given by \emph{to} with \emph{tolen}
	  specifying its size.

	\item[msg] 
	See \texttt{recvmsg} for a description of the 
	\texttt{oskit_msghdr} structure.

	\item[retval]
	Upon return \emph{*retval} contains the number of characters sent. 

\end{apiparm}

\begin{apiret}
        Returns 0 on success.
	No indication of failure to deliver is implicit in a send.
	Locally detected errors are indicated by an error code specified in
        {\tt <oskit/error.h>}.
\end{apiret}