PageRenderTime 50ms CodeModel.GetById 2ms app.highlight 36ms RepoModel.GetById 1ms app.codeStats 0ms

/doc/net.tex

https://bitbucket.org/mischief/oskit
LaTeX | 1024 lines | 753 code | 185 blank | 86 comment | 0 complexity | a4a343caf23ea7ef0e77df2543d4a2da MD5 | raw file
   1%
   2% Copyright (c) 1997-1998, 2000, 2001 University of Utah and the Flux Group.
   3% All rights reserved.
   4% 
   5% The University of Utah grants you the right to copy and reproduce this
   6% document or portions thereof for academic, research, evaluation, and
   7% personal use only, provided that (1) the title page appears prominently,
   8% and (2) these copyright and permission notices are retained in all copies.
   9% To arrange for alternate terms, contact the University of Utah at
  10% csl-dist@cs.utah.edu or +1-801-585-3271.
  11%
  12% -*- LaTeX -*-
  13
  14\label{net}
  15
  16\section{Introduction}
  17
  18	The \oskit{} networking framework encompasses a collection of COM
  19	interfaces used by the client operating system to invoke the 
  20	networking libraries.
  21	The individual networking libraries supply additional interfaces to
  22	the client operating system for initialization, and may supply
  23	additional interfaces for supporting extended features unique to
  24	particular networking protocol implementations.
  25
  26%	COM is described at 
  27%%	\htmladdnormallinkfoot{http://www.microsoft.com/oledev/olecom/title.htm}%
  28%		{http://www.microsoft.com/oledev/olecom/title.htm}
  29%	and in
  30%	chapter (\ref{com}).
  31
  32	\emph{At this point, we have only one interface, the oskit_socket 
  33	interface, defined. Additional interfaces for configuration, 
  34	routing, etc., are future work.}
  35
  36\apiintf{oskit_socket}{Socket Interface}
  37
  38	The \texttt{oskit_socket} COM interface defines an interface which
  39	capture the semantics of a socket as defined in the corresponding
  40	POSIX/CAE standards.
  41	The \texttt{oskit_socket} COM interface inherits from 
  42	\texttt{oskit_posixio}. It can be queried for an \texttt{oskit_stream} 
  43	interface. This query will always be successful, but the resulting
  44	\texttt{oskit_stream} instance might not support all methods.
  45	Generally, at least \texttt{read} and \texttt{write} will be supported.
  46	The \texttt{oskit_socket} COM interface provides in addition to 
  47	the \texttt{oskit_posixio} COM interface the following methods:
  48
  49\begin{csymlist}
  50\item[accept]	
  51	accept a connection on a socket
  52
  53\item[bind]
  54	bind a name to a socket
  55
  56\item[connect]
  57	initiate a connection on a socket
  58
  59\item[shutdown]
  60	shut down part of a full-duplex connection
  61
  62\item[listen]
  63	listen for connections on a socket	
  64
  65\item[getsockname]
  66	get socket name
  67
  68\item[getpeername]
  69	get name of connected peer
  70
  71\item[getsockopt]
  72	get options on sockets
  73
  74\item[setsockopt]
  75	set options on sockets
  76
  77\item[sendto]
  78	send a message from a socket
  79
  80\item[recvfrom]
  81	receive a message from a socket
  82
  83\item[sendmsg]
  84	send a message from a socket
  85
  86\item[recvmsg]
  87	receive a message from a socket
  88
  89\end{csymlist}
  90
  91	Note that these methods are not minimal, but correspond very 
  92    closely to the traditional BSD interfaces.
  93
  94    \begin{quote}
  95	{\bf Note:} the following paragraphs have a certain likelihood
  96	to change. The main reason for this is the obviously undesirable
  97	connection between the way socket factories and the socket interface
  98	interact. On a more positive note, everything right now is so
  99	close to the BSD interfaces that the reader familiar with those
 100	shouldn't have any problems understanding these.
 101    \end{quote}
 102
 103\api{oskit_socket_factory_t}{socket factories}
 104\begin{apisyn}
 105        \cinclude{oskit/net/socket.h}
 106
 107	\funcproto oskit_error_t 
 108		oskit_socket_factory_create(
 109		    oskit_socket_factory_t *factory,
 110		    oskit_u32_t domain, 
 111		    oskit_u32_t type, 
 112		    oskit_u32_t protocol,
 113		    \outparam oskit_socket_t **newsocket);
 114\end{apisyn}
 115
 116\begin{apidesc}
 117    Socket instances are created by \emph{socket factories}. 
 118
 119    A socket factory is an instance of the \texttt{oskit_socket_factory}
 120    COM interface.  Implementations of this interface will be provided
 121    by the networking stack(s) included in the \oskit{}.
 122    This interface implements a single method corresponding to the 
 123    \texttt{socket(2)} call in addition to the \texttt{oskit_iunknown}
 124    interface.
 125
 126    Each instance of socket has a type and a protocol associated with it. 
 127    This type and protocol is given to the socket by its factory, and
 128    cannot be changed during the lifetime of that socket instance.
 129\end{apidesc}
 130
 131\begin{apiparm}
 132	\item[factory] The socket factory used to create this socket.
 133
 134	\item[domain] The \emph{domain} parameter specifies a communications
 135	domain within which communication will take place; 
 136	this selects the protocol family which should be used.
 137	Some common formats are
 138
 139	\begin{tabular}{ll}
 140	\texttt{OSKIT_PF_LOCAL}     &   
 141		Host-internal protocols \\
 142	\texttt{OSKIT_PF_INET} 	   &
 143		DARPA Internet protocols \\
 144	\texttt{OSKIT_PF_ISO}       &   
 145		ISO protocols \\
 146	\texttt{OSKIT_PF_CCITT}     &   
 147		ITU-T protocols, like X.25 \\
 148	\texttt{OSKIT_PF_NS}        &   
 149		Xerox Network Systems protocols \\
 150	\end{tabular}
 151
 152	\texttt{OSKIT_PF_INET} is the only format for 
 153	    which the \oskit{} currently contains an implementation.
 154
 155	\item[type] The socket will have the indicated \emph{type}, which
 156	specifies the semantics of communication.  Currently defined types are
 157
 158	\begin{tabular}{ll}
 159	\texttt{OSKIT_SOCK_STREAM}    &       stream socket \\
 160	\texttt{OSKIT_SOCK_DGRAM}     &       datagram socket \\
 161	\texttt{OSKIT_SOCK_RAW}       &       raw-protocol interface \\
 162	\texttt{OSKIT_SOCK_RDM}       &       reliably-delivered message \\
 163	\texttt{OSKIT_SOCK_SEQPACKET} &       sequenced packet stream \\
 164	\end{tabular}
 165
 166	An \texttt{OSKIT_SOCK_STREAM} type provides sequenced, reliable, two-way
 167	connection based byte streams.  An out-of-band data transmission 
 168	mechanism may be supported.  An \texttt{OSKIT_SOCK_DGRAM} socket supports
 169	datagrams (connectionless, unreliable messages of a fixed (typically 
 170	small) maximum length).
 171	An \texttt{OSKIT_SOCK_SEQPACKET} socket may provide a sequenced, 
 172	reliable, two-way connection-based data transmission path for
 173	datagrams of fixed maximum length.
 174	\texttt{OSKIT_SOCK_RAW} sockets provide access to internal network 
 175	protocols and interfaces.
 176
 177	\item[protocol]
 178	The \emph{protocol} specifies a particular protocol to be used with the
 179	socket.
 180	Normally only a single protocol exists to support a particular socket
 181	type within a given protocol family.  However, it is possible that 
 182	many protocols may exist, in which case a particular protocol must 
 183	be specified. The protocol number to use is particular to the
 184	communication domain in which communication is to take place.
 185
 186	Protocols for the \texttt{OSKIT_PF_INET} protocol family are defined 
 187	in \texttt{oskit/c/netinet/in.h}.
 188
 189	\item[newsocket] The new \texttt{oskit_socket_t} instance that
 190		was created.
 191\end{apiparm}
 192
 193\begin{apiret}
 194	Returns 0 on success, or an error code specified in
 195	{\tt <oskit/error.h>}, on error.
 196\end{apiret}
 197
 198%
 199% accept()
 200%
 201
 202\api{accept}{accept a connection on a socket}
 203\begin{apisyn}
 204	\cinclude{oskit/net/socket.h}
 205
 206	\funcproto oskit_error_t
 207	oskit_socket_accept(oskit_socket_t *s, 
 208		\outparam struct oskit_sockaddr *name,
 209		\inoutparam oskit_size_t *anamelen,
 210		\outparam struct oskit_socket **newopenso);
 211\end{apisyn}
 212
 213\begin{apidesc}
 214	The \texttt{accept} method extracts the first connection request
 215	on the queue of pending connections, creates a new socket 
 216	with the same properties of s and returns it.
 217	The socket must have been bound to an address with \texttt{bind}
 218	and it must be listening for connections after a \texttt{listen}.
 219
 220	If no pending connections are present on the queue, \texttt{accept} 
 221	blocks the caller until a connection is present.
 222\end{apidesc}
 223
 224\begin{apiparm}
 225	\item[s]
 226		The socket from which connections are to accepted.
 227
 228	\item[name]
 229		Filled with the address of the connecting entity as known
 230		to the communication layer.
 231
 232	\item[anamelen]
 233		Initially, the amount of space pointed to by name,
 234		on return it will contain the amount actually used.
 235
 236	\item[newopenso]
 237		Newly created socket.
 238
 239\end{apiparm}
 240
 241\begin{apiret}
 242	Returns 0 on success, or an error code specified in
 243	{\tt <oskit/error.h>}, on error.
 244\end{apiret}
 245
 246%
 247% bind()
 248%
 249
 250\api{bind}{bind a name to a socket}
 251\begin{apisyn}
 252        \cinclude{oskit/net/socket.h}
 253
 254        \funcproto oskit_error_t
 255        oskit_socket_bind(oskit_socket_t *s,
 256		const struct oskit_sockaddr *name,
 257		oskit_size_t namelen);
 258\end{apisyn}
 259
 260\begin{apidesc}
 261	\texttt{bind} assigns a name to an unnamed socket.
 262	When a socket is created, it exists in a name space (address family) 
 263	but has no name assigned. \texttt{bind} requests that 
 264	\emph{name} be assigned to the socket.
 265
 266\end{apidesc}
 267
 268\begin{apiparm}
 269        \item[s]
 270                The socket to which a name is to be bound.
 271
 272        \item[name]
 273                The name to which the socket is to be bound.
 274
 275        \item[namelen]
 276                The length of \emph{name} in bytes.
 277
 278\end{apiparm}
 279
 280\begin{apiret}
 281        Returns 0 on success, or an error code specified in
 282        {\tt <oskit/error.h>}, on error.
 283\end{apiret}
 284
 285%
 286% connect()
 287%
 288
 289\api{connect}{initiate a connection on a socket}
 290\begin{apisyn}
 291        \cinclude{oskit/net/socket.h}
 292
 293        \funcproto oskit_error_t
 294        oskit_socket_connect(oskit_socket_t *s,
 295		 const struct oskit_sockaddr *name,
 296		 oskit_size_t namelen);
 297\end{apisyn}
 298
 299\begin{apidesc}
 300	If \emph{s} is of type \texttt{OSKIT_SOCK_DGRAM}, this call
 301	specifies the peer with which the socket is to be associated; this 
 302	address is that to which datagrams are to be sent, and the only address
 303	from which datagrams are to be received.  If the socket is of type
 304	\texttt{OSKIT_SOCK_STREAM}, this call attempts to make a connection 
 305	to another socket.
 306	The other socket is specified by \emph{name}, which is an address 
 307	in the communications space of the socket. 
 308	Each communications space interprets the \emph{name} parameter
 309	in its own way. Generally, stream sockets may successfully
 310	\texttt{connect} only once; datagram sockets may use 
 311	\texttt{connect} multiple times to change their association.  
 312	Datagram sockets may dissolve the association by connecting to 
 313	an invalid address, such as a null address.
 314\end{apidesc}
 315
 316\begin{apiparm}
 317        \item[s]
 318                The socket from which the connection is to be initiated.
 319
 320        \item[name]
 321                The address of the entity to which the connection is
 322		to be established. 
 323
 324	\item[namelen]
 325		The length of \emph{name} in bytes.
 326
 327\end{apiparm}
 328
 329\begin{apiret}
 330        Returns 0 on success, or an error code specified in
 331        {\tt <oskit/error.h>}, on error.
 332\end{apiret}
 333
 334%
 335% shutdown()
 336%
 337
 338\api{shutdown}{shut down part of a full-duplex connection}
 339\begin{apisyn}
 340        \cinclude{oskit/net/socket.h}
 341
 342        \funcproto oskit_error_t
 343        oskit_socket_shutdown(oskit_socket_t *s,
 344		 oskit_u32_t how);
 345\end{apisyn}
 346
 347\begin{apidesc}
 348	The \texttt{shutdown} call causes all or part of a full-duplex 
 349	connection on the socket \emph{s} to be shut down.  
 350\end{apidesc}
 351
 352\begin{apiparm}
 353        \item[s]
 354                The socket which is to be shut down.
 355
 356        \item[how]
 357                Specifies what is to be disallowed:
 358		\begin{itemize}
 359		\item[how = 0]	receives
 360		\item[how = 1]	sends
 361		\item[how = 2]	sends and receives
 362		\end{itemize}
 363
 364\end{apiparm}
 365
 366\begin{apiret}
 367        Returns 0 on success, or an error code specified in
 368        {\tt <oskit/error.h>}, on error.
 369\end{apiret}
 370
 371%
 372% listen()
 373%
 374
 375\api{listen}{listen for connections on a socket}
 376\begin{apisyn}
 377        \cinclude{oskit/net/socket.h}
 378
 379        \funcproto oskit_error_t
 380        oskit_socket_listen(oskit_socket_t *s,
 381		 oskit_u32_t backlog);
 382\end{apisyn}
 383
 384\begin{apidesc}
 385	A willingness to accept incoming connections and a queue limit 
 386	for incoming connections are specified with \texttt{listen},
 387	and then the connections are accepted with \texttt{accept}.
 388	The \texttt{listen} call applies only to sockets of type
 389	\texttt{OSKIT_SOCK_STREAM} or  \texttt{OSKIT_SOCK_SEQPACKET}.
 390
 391	The \emph{backlog} parameter defines the maximum length the queue of
 392	pending connections may grow to. 
 393	If a connection request arrives with the queue full the client may 
 394	receive an error with an indication of connection refused, or, if
 395	the underlying protocol supports retransmission, the request may
 396	be ignored so that retries may succeed.
 397\end{apidesc}
 398
 399\begin{apiparm}
 400        \item[s]
 401                The socket where connections will be accepted.
 402
 403        \item[backlog]
 404		Maximum number of pending connections.
 405
 406\end{apiparm}
 407
 408\begin{apiret}
 409        Returns 0 on success, or an error code specified in
 410        {\tt <oskit/error.h>}, on error.
 411\end{apiret}
 412
 413%
 414% getsockname()
 415%
 416
 417\api{getsockname}{get socket name}
 418\begin{apisyn}
 419        \cinclude{oskit/net/socket.h}
 420
 421        \funcproto oskit_error_t
 422        oskit_socket_getsockname(oskit_socket_t *s,
 423		\outparam struct oskit_sockaddr *asa,
 424                \inoutparam oskit_size_t *anamelen);
 425\end{apisyn}
 426
 427\begin{apidesc}
 428	\texttt{getsockname} returns the current name for the specified socket.
 429\end{apidesc}
 430
 431\begin{apiparm}
 432        \item[s]
 433                The socket whose name is to be determined.
 434
 435        \item[name]
 436                Contains the name of the socket upon return.
 437
 438        \item[anamelen]
 439                Initially, the amount of space pointed to by name,
 440                on return it will contain the amount actually used, i.e.,
 441		the actual size of the name.
 442
 443\end{apiparm}
 444
 445\begin{apiret}
 446        Returns 0 on success, or an error code specified in
 447        {\tt <oskit/error.h>}, on error.
 448\end{apiret}
 449
 450%
 451% getpeername()
 452%
 453
 454\api{getpeername}{get name of connected peer}
 455\begin{apisyn}
 456        \cinclude{oskit/net/socket.h}
 457
 458        \funcproto oskit_error_t
 459        oskit_socket_getpeername(oskit_socket_t *s,
 460		\outparam struct oskit_sockaddr *asa,
 461		\inoutparam oskit_size_t *anamelen);
 462\end{apisyn}
 463
 464\begin{apidesc}
 465	\texttt{getpeername} returns the name of the peer connected to socket
 466	\emph{s}. 
 467\end{apidesc}
 468
 469\begin{apiparm}
 470        \item[s]
 471                The socket connected to the peer whose name is to be returned. 
 472
 473        \item[name]
 474		Contains the peer's name upon return.
 475
 476        \item[anamelen]
 477                Initially, the amount of space pointed to by name,
 478                on return it will contain the amount actually used.
 479		The name is truncated if the buffer provided is too small.
 480
 481\end{apiparm}
 482
 483\begin{apiret}
 484        Returns 0 on success, or an error code specified in
 485        {\tt <oskit/error.h>}, on error.
 486\end{apiret}
 487
 488%
 489% getsockoption()
 490%
 491
 492\api{getsockopt}{get options on sockets}
 493\begin{apisyn}
 494        \cinclude{oskit/net/socket.h}
 495
 496        \funcproto oskit_error_t
 497        oskit_socket_getsockopt(oskit_socket_t *s,
 498		 oskit_u32_t level,
 499		 oskit_u32_t name, 
 500		\outparam void *val,
 501		\inoutparam oskit_size_t *valsize);
 502\end{apisyn}
 503
 504\begin{apidesc}
 505	Get the current options
 506	associated with a socket.  Options may exist at multiple protocol 
 507	levels. 
 508\end{apidesc}
 509
 510\begin{apiparm}
 511        \item[s]
 512                The socket whose options are to be queried or set.
 513
 514        \item[level]
 515		The level at which the option resides.
 516		See \texttt{setsockopt} for details.
 517
 518        \item[name]
 519		\emph{name} and any specified options are passed
 520		uninterpreted to the appropriate protocol module
 521		for interpretation.
 522		See \texttt{setsockopt} for details.
 523
 524        \item[val, valsize]
 525		The parameters \emph{val} and \emph{valsize}
 526		are used to access option values.
 527		For \texttt{getsockopt}, \emph{valsize} initially contains the 
 528		size of the buffer pointed to by \emph{val},
 529		and modified on return
 530		to indicate the actual size of the value returned.
 531		If no option value is to be supplied or returned,
 532		\emph{val} may be \texttt{NULL}.
 533\end{apiparm}
 534
 535\begin{apiret}
 536        Returns 0 on success, or an error code specified in
 537        {\tt <oskit/error.h>}, on error.
 538\end{apiret}
 539
 540\api{setsockopt}{set options on sockets}
 541\begin{apisyn}
 542        \cinclude{oskit/net/socket.h}
 543
 544        \funcproto oskit_error_t
 545        oskit_socket_setsockopt(oskit_socket_t *s,
 546		 oskit_u32_t level,
 547		 oskit_u32_t name, 
 548		 const void *val, 
 549		 oskit_size_t valsize);
 550\end{apisyn}
 551
 552\begin{apidesc}
 553	\texttt{setsockopt} manipulates the options
 554	associated with a socket.  Options may exist at multiple protocol 
 555	levels. 
 556
 557\end{apidesc}
 558
 559\begin{apiparm}
 560        \item[s]
 561                The socket whose options are to be queried or set.
 562
 563        \item[level] When manipulating socket options the level at 
 564	which the option resides and the name of the option must be 
 565	specified.  To manipulate options at the socket level, \emph{level} 
 566	is specified as \texttt{OSKIT_SOL_SOCKET}. To manipulate options
 567	at any other level the protocol number of the appropriate protocol 
 568	controlling the option is supplied.  For example, to indicate that an
 569	option is to be interpreted by the TCP protocol, \emph{level} 
 570	should be set to \texttt{IPPROTO_TCP}.
 571
 572        \item[name]
 573	\emph{name} and any specified options are passed uninterpreted to the
 574	appropriate protocol module for interpretation.
 575	Definitions for socket level options are described below.
 576	Options at other protocol levels vary in format and name.
 577
 578	Most socket-level options utilize an \texttt{int} parameter for 
 579	\emph{val}. For \texttt{setsockopt}, the parameter should be
 580	non-zero to enable a boolean option, or zero if the option is 
 581	to be disabled.
 582	\texttt{OSKIT_SO_LINGER} uses a \texttt{struct oskit_linger}
 583	parameter, which specifies the desired state of the option
 584	and the linger interval (see below).
 585	%% is that really so?
 586	\texttt{OSKIT_SO_SNDTIMEO} and \texttt{OSKIT_SO_RCVTIMEO}
 587	use a \texttt{struct timeval} parameter, defined in 
 588	\texttt{<oskit/c/sys/time.h>}
 589
 590	The following options are recognized at the socket level.  Except as 
 591	noted, each may be examined with \texttt{getsockopt} and set with
 592	\texttt{setsockopt}.
 593
 594	\begin{tabular}{ll}
 595           \texttt{OSKIT_SO_DEBUG} &
 596		        enables recording of debugging information \\
 597           \texttt{OSKIT_SO_REUSEADDR} &
 598		    enables local address reuse \\
 599           \texttt{OSKIT_SO_REUSEPORT} &
 600		    enables duplicate address and port bindings \\
 601           \texttt{OSKIT_SO_KEEPALIVE} &
 602		    enables keep connections alive \\
 603           \texttt{OSKIT_SO_DONTROUTE} &
 604		    enables routing bypass for outgoing messages \\
 605           \texttt{OSKIT_SO_LINGER} &
 606		       linger on close if data present \\
 607           \texttt{OSKIT_SO_BROADCAST} &
 608		    enables permission to transmit broadcast messages \\
 609           \texttt{OSKIT_SO_OOBINLINE} &
 610		    enables reception of out-of-band data in band \\
 611           \texttt{OSKIT_SO_SNDBUF} &
 612		       set buffer size for output \\
 613           \texttt{OSKIT_SO_RCVBUF} &
 614		       set buffer size for input \\
 615
 616           \texttt{OSKIT_SO_SNDLOWAT} &
 617		     set minimum count for output \\
 618           \texttt{OSKIT_SO_RCVLOWAT} &
 619		     set minimum count for input \\
 620           \texttt{OSKIT_SO_SNDTIMEO} &
 621		     set timeout value for output \\
 622           \texttt{OSKIT_SO_RCVTIMEO} &
 623		     set timeout value for input \\
 624           \texttt{OSKIT_SO_TYPE} &
 625		         get the type of the socket (get only) \\
 626           \texttt{OSKIT_SO_ERROR} &
 627		        get and clear error on the socket (get only) \\
 628	\end{tabular}
 629
 630	\texttt{OSKIT_SO_DEBUG} enables debugging in the underlying 
 631   	protocol modules.
 632	\texttt{OSKIT_SO_REUSEADDR} indicates that the rules used in 
 633	validating addresses supplied in \texttt{bind}
 634	should allow reuse of local addresses.
 635	\texttt{OSKIT_SO_REUSEPORT} allows completely duplicate bindings 
 636	by multiple clients if they all set \texttt{OSKIT_SO_REUSEPORT} 
 637	before binding the port. This option permits multiple instances
 638	of a program to each receive UDP/IP multicast or
 639	broadcast datagrams destined for the bound port.
 640	\texttt{OSKIT_SO_KEEPALIVE} enables the periodic transmission of 
 641	messages on a connected socket. Should the
 642	connected party fail to respond to these messages, the connection is 
 643	considered broken and clients using the socket are notified
 644	when attempting to send data.
 645	% XXX:
 646	% ...via a SIGPIPE signal. Yeah, right.
 647	\texttt{OSKIT_SO_DONTROUTE} indicates that outgoing 
 648	messages should bypass the standard routing facilities.
 649	Instead, messages are directed to the appropriate network interface
 650	according to the network portion of the destination address.
 651
 652	\texttt{OSKIT_SO_LINGER} controls the action taken when unsent 
 653	messages are queued on a socket and the socket is released.
 654	If the socket promises reliable delivery of data and 
 655	\texttt{OSKIT_SO_LINGER} is set, the system will block on the last
 656	\texttt{release} attempt until it is able to transmit the data
 657	or until it decides it is unable to deliver the information
 658	(a timeout period, termed the linger interval, is specified in the 
 659	\texttt{setsockopt} call when \texttt{OSKIT_SO_LINGER} is requested.
 660	If \texttt{OSKIT_SO_LINGER} is disabled, the last \texttt{release}
 661	will succeed immediately. % is that really true???
 662
 663	The option \texttt{OSKIT_SO_BROADCAST} requests permission to send 
 664	broadcast datagrams on the socket.  Broadcast was a privileged 
 665	operation in earlier versions of the system.  With protocols that 
 666	support out-of-band data, the \texttt{OSKIT_SO_OOBINLINE} option 
 667	requests that out-of-band data be placed in the normal data input 
 668	queue as received; it will then be accessible with \texttt{recv}
 669	or \texttt{read} calls without the \texttt{OSKIT_MSG_OOB} flag.  
 670	Some protocols always behave as if this option were set.  
 671
 672	\texttt{OSKIT_SO_SNDBUF} and \texttt{OSKIT_SO_RCVBUF} are options 
 673	to adjust the normal buffer sizes allocated for output and input 
 674	buffers, respectively.  The buffer size may be increased for 
 675	high-volume connections, or may be decreased to limit the possible 
 676	backlog of incoming data.  An absolute limit may be places on 
 677	these values.
 678
 679	\texttt{OSKIT_SO_SNDLOWAT} is an option to set the minimum count 
 680	for output operations. Most output operations process all of the 
 681	data supplied by the call, delivering data to the protocol for 
 682	transmission and blocking as necessary for flow control.  
 683	Nonblocking output operations will process as much data as permitted 
 684	subject to flow control without blocking, but will process no data 
 685	if flow control does not allow the smaller of the low water
 686	mark value or the entire request to be processed.  
 687
 688	% See, there you go: we NEED select().
 689	% A select(2) operation
 690        % testing the ability to write to a socket will return true only if 
 691	% the low water mark amount could be processed.  
 692
 693	The default value for \texttt{OSKIT_SO_SNDLOWAT}
 694	is set to a convenient size for network efficiency, often 1024.
 695
 696        \texttt{OSKIT_SO_RCVLOWAT} is an option to set the minimum count 
 697	for input operations.
 698	In general, receive calls will block until any (non-zero) amount of data
 699	is received, then return with the smaller of the amount available or the
 700	amount requested.  The default value for \texttt{OSKIT_SO_RCVLOWAT} is 1.
 701	If \texttt{OSKIT_SO_RCVLOWAT} is set to a larger value, blocking 
 702	receive calls normally wait until they have received the smaller of 
 703	the low water mark value or the requested amount.  Receive calls may 
 704	still return less than the low water mark if an error occurs, a signal 
 705	is caught, or the type of data next in the receive queue is different 
 706	than that returned.
 707
 708	\texttt{OSKIT_SO_SNDTIMEO} is an option to set a timeout value for 
 709	output operations.
 710	It accepts a \texttt{struct timeval} parameter with the number 
 711	of seconds and microseconds used to limit waits for output operations 
 712	to complete.  If a send operation has blocked for this much time, 
 713	it returns with a partial count or with the error 
 714	\texttt{OSKIT_EWOULDBLOCK} if no data were sent.  
 715
 716	% FreeBSD says: In the current implementation, 
 717	This timer is restarted each time additional data 
 718	are delivered to the protocol, implying that the limit applies to 
 719	output portions ranging in size from the low water mark to the 
 720	high water mark for output.  
 721
 722	\texttt{OSKIT_SO_RCVTIMEO} is an option to set a timeout value for 
 723	input operations.  It accepts a struct timeval parameter with the 
 724	number of seconds and microseconds used to limit waits for input 
 725	operations to complete.
 726
 727	% FreeBSD says: In the current implementation, 
 728	This timer is restarted each time additional data are received by 
 729	the protocol, and thus the limit is in effect
 730	an inactivity timer.  If a receive operation has been blocked for this
 731	much time without receiving additional data, it returns with a short
 732	count or with the error \texttt{OSKIT_EWOULDBLOCK} if no data were 
 733	received.
 734
 735	Finally, \texttt{OSKIT_SO_TYPE} and \texttt{OSKIT_SO_ERROR} are options 
 736	used only with \texttt{getsockopt}.
 737	\texttt{OSKIT_SO_TYPE} returns the type of the socket, such as 
 738	\texttt{OSKIT_SOCK_STREAM}.  
 739	\texttt{OSKIT_SO_ERROR} returns any 
 740	pending error on the socket and clears the error status.  
 741	It may be used to check for asynchronous errors on connected datagram 
 742	sockets or for other asynchronous errors.
 743	
 744        \item[val, valsize]
 745	The parameters \emph{val} and \emph{valsize}
 746	are used to access option values for \texttt{setsockopt}.
 747	If no option value is to be supplied or returned, \emph{val} may be
 748	\texttt{NULL}.
 749
 750\end{apiparm}
 751
 752\begin{apiret}
 753        Returns 0 on success, or an error code specified in
 754        {\tt <oskit/error.h>}, on error.
 755\end{apiret}
 756
 757%
 758% recvfrom, recvmsg
 759%
 760
 761\api{recvfrom, recvmsg}{receive a message from a socket}
 762\begin{apisyn}
 763        \cinclude{oskit/net/socket.h}
 764
 765	\funcproto oskit_error_t
 766	oskit_socket_recvfrom(oskit_socket_t *s, 
 767			    \outparam void *buf,
 768                            oskit_size_t len, oskit_u32_t flags,
 769                            \outparam struct oskit_sockaddr *from, 
 770			    \inoutparam oskit_size_t *fromlen,
 771                            \outparam oskit_size_t *retval);
 772
 773        \funcproto oskit_error_t
 774        oskit_socket_recvmsg(oskit_socket_t *s,
 775                            \inoutparam struct oskit_msghdr *msg, 
 776			    oskit_u32_t flags,
 777                            \outparam oskit_size_t *retval);
 778\end{apisyn}
 779
 780\begin{apidesc}
 781	\texttt{recvfrom} and \texttt{recvmsg} are used to receive messages
 782	from a socket, and may be used to receive data on a socket whether 
 783	or not it is connection-oriented.
 784
 785	\textbf{Note: } The \texttt{recv} library function 
 786	can be implemented using \texttt{recvfrom} with a nil \emph{from}
 787	parameter. 
 788	% BSD says:
 789	% As it is redundant, it may not be supported in future releases.
 790
 791	If no messages are available at the socket, the receive call waits 
 792	for a message to arrive.
 793	% BSD says:
 794	% unless the socket is nonblocking (see fcntl(2))  in
 795	% which case the value -1 is returned and the external variable 
 796	% errno set to EAGAIN. 
 797	The receive calls normally return any data available,
 798	up to the requested amount, rather than waiting for receipt of the 
 799	full amount equested; this behavior is affected by the socket-level
 800	options \texttt{OSKIT_SO_RCVLOWAT} and \texttt{OSKIT_SO_RCVTIMEO}
 801	described in \texttt{getsockopt}.
 802
 803	% BSD says:
 804	% The select(2) call may be used to determine when more data arrive.
 805
 806\end{apidesc}
 807
 808\begin{apiparm}
 809        \item[s]
 810                The socket from the message is to be received.
 811
 812	\item[buf] Buffer in which the message is to be copied.
 813
 814	\item[len] Length of the buffer provided.
 815
 816	\item[flags]
 817		The \emph{flags} argument is formed by or'ing one or more 
 818		of the values:
 819
 820		\begin{tabular}{ll}
 821		\texttt{OSKIT_MSG_OOB} 	 & process out-of-band data
 822		    \\
 823		\texttt{OSKIT_MSG_PEEK} 	 & peek at incoming message
 824		    \\
 825		\texttt{OSKIT_MSG_WAITALL}& wait for full request or error
 826		    \\
 827		\end{tabular}
 828
 829		The \texttt{OSKIT_MSG_OOB} flag requests receipt of 
 830		out-of-band data that would not be received in the normal 
 831		data stream.
 832		Some protocols place expedited data
 833		at the head of the normal data queue, and thus this flag cannot
 834		be used with such protocols.
 835		The \texttt{OSKIT_MSG_PEEK} flag causes the receive 
 836		operation to return data from the beginning of the receive
 837		queue without removing that data from the queue.
 838		Thus, a subsequent receive call will return the same data.
 839		The \texttt{OSKIT_MSG_WAITALL} flag requests that the operation
 840		block until the full request is satisfied. 
 841		However, the call may still return less data than requested if
 842		an error or disconnect occurs, or the next data to be received 
 843		is of a different type than that returned.
 844
 845        \item[from]
 846		If \emph{from} is non-nil, and the socket is not 
 847		connection-oriented, the source address of the message is
 848		filled in.  
 849	\item[fromlen]
 850		Initialized to the size of the buffer associated with 
 851		\emph{from}, and modified on return to indicate the actual 
 852		size of the address stored there.
 853	
 854	\item[msg] The \texttt{recvmsg} method uses a 
 855		\texttt{struct oskit_msghdr} structure to minimize the number
 856		of directly supplied parameters. 
 857
 858\cstruct{oskit_msghdr}{
 859        oskit_addr_t     msg_name;               /* optional address */
 860        oskit_u32_t      msg_namelen;            /* size of address */
 861        struct  oskit_iovec *msg_iov;            /* scatter/gather array */
 862        oskit_u32_t      msg_iovlen;             /* \# elements in msg_iov */
 863        oskit_addr_t     msg_control;            /* ancillary data, see below */
 864        oskit_u32_t      msg_controllen;         /* ancillary data buffer len */
 865        oskit_u32_t      msg_flags;              /* flags on received message */
 866};
 867
 868	Here \emph{msg_name} and \emph{msg_namelen} 
 869	specify the destination address if the socket is unconnected;
 870	\emph{msg_name} may be given as a null pointer if no names are desired 
 871	or required.
 872	\emph{msg_iov} and \emph{msg_iovlen} describe scatter gather
 873	locations. 
 874	
 875	\emph{msg_control}, which has length \emph{msg_controllen},
 876	points to a buffer for other protocol control related
 877	messages or other miscellaneous ancillary data.
 878
 879    % BSD says:
 880    % The messages are of the form:
 881    %
 882    % struct cmsghdr {
 883    %     u_int   cmsg_len;       /* data byte count, including hdr */
 884    %     int     cmsg_level;     /* originating protocol */
 885    %     int     cmsg_type;      /* protocol-specific type */
 886    % /* followed by
 887    %     u_char  cmsg_data[]; */
 888    % };
 889    % As an example, one could use this to learn of changes in the data-stream
 890    % in XNS/SPP, or in ISO, to obtain user-connection-request data by request-
 891    % ing a recvmsg with no data buffer provided immediately after an accept()
 892    % call.
 893    %
 894    % Open file descriptors are now passed as ancillary data for AF_UNIX domain
 895    % sockets, with cmsg_level set to SOL_SOCKET and cmsg_type set to
 896    % SCM_RIGHTS.
 897
 898	The \emph{msg_flags} field is set on return according to the message 
 899	received. \texttt{OSKIT_MSG_EOR}  indicates end-of-record; the data 
 900	returned completed a record (generally used with sockets of type
 901	\texttt{OSKIT_SOCK_SEQPACKET}). \texttt{OSKIT_MSG_TRUNC} indicates
 902	that the trailing portion of a datagram was discarded because
 903	the datagram was larger than the buffer supplied.
 904	\texttt{OSKIT_CMSG_TRUNC} indicates that some
 905	control data were discarded due to lack of space in the
 906	buffer for ancillary data. \texttt{OSKIT_MSG_OOB} is returned to
 907	indicate that expedited or out-of-band data were received.
 908
 909        \item[retval]
 910                Contains the number of characters received, i.e., the total
 911		length of the message upon return.
 912		If a message is too long to fit in the supplied buffer,
 913		excess bytes may be discarded depending on the type of socket 
 914		the message is received from.
 915
 916\end{apiparm}
 917
 918\begin{apiret}
 919        Returns 0 on success, or an error code specified in
 920        {\tt <oskit/error.h>}, on error.
 921\end{apiret}
 922
 923%
 924% sendto, sendmsg
 925%
 926
 927\api{sendto, sendmsg}{send a message from a socket}
 928\begin{apisyn}
 929        \cinclude{oskit/net/socket.h}
 930
 931        \funcproto oskit_error_t
 932	oskit_socket_sendto(oskit_socket_t *s, 
 933		    const void *buf,
 934                    oskit_size_t len, 
 935		    oskit_u32_t flags,
 936                    const struct oskit_sockaddr *to, 
 937		    oskit_size_t tolen,
 938                    \outparam oskit_size_t *retval);
 939
 940        \funcproto oskit_error_t
 941        oskit_socket_sendmsg(oskit_socket_t *s,
 942                    const struct oskit_msghdr *msg, 
 943		    oskit_u32_t flags,
 944                    \outparam oskit_size_t *retval);
 945
 946\end{apisyn}
 947
 948\begin{apidesc}
 949	\texttt{sendto}, \texttt{sendmsg} are used to transmit
 950	a message to another socket. 
 951	The C library \texttt{send} may be implemented by passing a
 952	NULL \emph{to} parameter. It may be used only when the socket 
 953	is in a connected state, while \texttt{sendto} and 
 954	\texttt{sendmsg} may generally be used at any time.
 955
 956	Send will block if no messages space is available at the socket 
 957	to hold the message to be transmitted.
 958	% in BSD 
 959	% unless the socket has been placed in non-blocking I/O mode.
 960	% The select(2) call may be used to determine when it is possible 
 961	% to send more data.
 962
 963\end{apidesc}
 964
 965\begin{apiparm}
 966        \item[s]
 967                The socket from which the message is to be sent.
 968
 969	\item[buf]
 970
 971	\item[len] \emph{len} gives the length of the message.
 972	If the message is too long to pass atomically through the underlying
 973	protocol, the error \texttt{OSKIT_EMSGSIZE} is returned,
 974	and the message is not transmitted.
 975
 976	\item[flags]
 977	The \emph{flags}
 978	parameter may include one or more of the following:
 979
 980	\begin{tabular}{ll}
 981	\texttt{OSKIT_MSG_OOB} &
 982	            process out-of-band data \\
 983        \texttt{OSKIT_MSG_PEEK} &
 984	            peek at incoming message \\
 985        \texttt{OSKIT_MSG_DONTROUTE} &
 986		    bypass routing, use direct interface \\
 987        \texttt{OSKIT_MSG_EOR} &
 988	            data completes record 	\\
 989        \texttt{OSKIT_MSG_EOF} &
 990	            data completes transaction \\
 991	\end{tabular}
 992	
 993	The flag \texttt{OSKIT_MSG_OOB} is used to send ``out-of-band''
 994	data on sockets that support this notion 
 995	(e.g. \texttt{OSKIT_SOCK_STREAM}); the underlying protocol
 996	must also support ``out-of-band'' data.
 997	\texttt{OSKIT_MSG_EOR} is used to indicate a record
 998	 mark for protocols which support the concept.
 999	\texttt{OSKIT_MSG_EOF}  requests that the
1000	sender side of a socket be shut down, and that an appropriate
1001	indication be sent at the end of the specified data;
1002	this flag is only implemented for \texttt{OSKIT_SOCK_STREAM}
1003	sockets in the \texttt{OSKIT_PF_INET} protocol family.
1004
1005	\item[to, tolen]
1006	  The address of the target is given by \emph{to} with \emph{tolen}
1007	  specifying its size.
1008
1009	\item[msg] 
1010	See \texttt{recvmsg} for a description of the 
1011	\texttt{oskit_msghdr} structure.
1012
1013	\item[retval]
1014	Upon return \emph{*retval} contains the number of characters sent. 
1015
1016\end{apiparm}
1017
1018\begin{apiret}
1019        Returns 0 on success.
1020	No indication of failure to deliver is implicit in a send.
1021	Locally detected errors are indicated by an error code specified in
1022        {\tt <oskit/error.h>}.
1023\end{apiret}
1024