ossp-web/pkg/lib/sa/index.wml
#use wml::ossp area=pkg:lib subarea=sa
<title>OSSP sa</title>
<h1>Socket Abstraction</h1>
<img src="socket.png" alt="" align=right>
<h2>Abstract</h2>
<b>OSSP</b> sa is an abstraction library for the Unix socket application programming
interface (API) featuring stream and datagram oriented communication over Unix
Domain and Internet Domain (TCP and UDP) sockets. It provides the following
key features: address abstraction (local, IPv4, and IPv6), type abstraction,
I/O timeouts, I/O stream buffering and convenience I/O functions.
It provides the following key features:
<ul>
<li><b>Stand-Alone, Self-Contained, Embeddable</b>
<br>
<font size=-1>
Although there are various Open Source libraries available which provide
a similar abstraction approach, they all either lack important features
or unfortunately depend on other companion libraries. <b>OSSP sa</b> fills
this gap by providing all important features (see following points) as a
stand-alone and fully self-contained library. This way <b>OSSP sa</b> can be
trivially embedded as a sub-library into other libraries. It especially
provides additional support for namespace-safe embedding of its API in
order to avoid symbol conflicts.
</font>
<p>
<li><b>Address Abstraction</b>
<br>
<font size=-1>
Most of the ugliness in the Unix <i>Socket</i> API is the necessity to
have to deal with the various address structures (<tt>struct sockaddr_xx</tt>)
which exist because of both the different communication types and
addressing schemes. <b>OSSP sa</b> fully hides this by providing an abstract
and opaque address type (<tt>sa_addr_t</tt>) together with utility functions
which allow one to convert from the traditional <tt>struct sockaddr</tt> or
URI specification to the <tt>sa_addr_t</tt> and vice versa without having to
deal with special cases related to the underlying particular <tt>struct
sockaddr_xx</tt>. <b>OSSP sa</b> support <i>Unix Domain</i> and both IPv4 and IPv6
<i>Internet Domain</i> addressing.
</font>
<p>
<li><b>Type Abstraction</b>
<br>
<font size=-1>
Some other subtle details in the Unix <i>Socket</i> API make the life hard
in practice: <tt>socklen_t</tt> and <tt>ssize_t</tt>. These two types originally
were (and on some platforms still are) plain integers or unsigned
integers while POSIX later introduced own types for them (and even
revised these types after some time again). This is nasty, because
for 100% type-correct API usage (especially important on 64-bit
machines where pointers to different integer types make trouble), every
application has to check whether the newer types exists, and if not
provide own definitions which map to the still actually used integer
type on the underlying platform. <b>OSSP sa</b> hides most of this in its
API and for <tt>socklen_t</tt> provides a backward-compatibility definition.
Instead of <tt>ssize_t</tt> it can use <tt>size_t</tt> because <b>OSSP sa</b> does not use
traditional Unix return code semantics.
</font>
<p>
<li><b>I/O Timeouts</b>
<br>
<font size=-1>
Each I/O function in <b>OSSP sa</b> is aware of timeouts (set by
sa_timeout(3)), i.e., all I/O operations return <tt>SA_ERR_TMT</tt> if
the timeout expired before the I/O operation was able to succeed.
This allows one to easily program less-blocking network services.
<b>OSSP sa</b> internally implements these timeouts either through the
<tt>SO_</tt>{<tt>SND</tt>,<tt>RCV</tt>}<tt>TIMEO</tt> feature on more modern <i>Socket</i>
implementations or through traditional select(2). This way high
performance is achieved on modern platforms while the full functionality
still is available on older platforms.
</font>
<p>
<li><b>I/O Stream Buffering</b>
<br>
<font size=-1>
If <b>OSSP sa</b> is used for stream communication, internally all I/O
operations can be performed through input and/or output buffers (set
by sa_buffer(3)) for achieving higher I/O performance by doing I/O
operations on larger aggregated messages and with less required system
calls. Additionally if <b>OSSP sa</b> is used for stream communication, for
convenience reasons line-oriented reading (sa_readln(3)) and formatted
writing (see sa_writef(3)) is provided, modelled after STDIO's fgets(3)
and fprintf(3). Both features fully leverage from the I/O buffering.
</font>
</ul>
<h2>Documentation</h2>
<pkg_manpage name="sa" sect=3 path="/pkg/lib/sa/sa.pod">,
<pkg_manpage name="sa-config" sect=1 path="/pkg/lib/sa/sa-config.pod">.
<h2>Authors</h2>
<pkg_author name="Ralf S. Engelschall" mail="rse@engelschall.com">
<h2>Status</h2>
<pkg_status
name="sa" assign="rse" genesis="Jan-2001"
stable="1.2.6" stable_date="03-Oct-2005"
unstable="none" unstable_date="none"
done=100>
<h2>Source</h2>
<pkg_files
cvs=$(CVS_ROOT_URL)/pkg/lib/sa/
url=$(FTP_ROOT_URL)/pkg/lib/sa/
directory=$(FTP_ROOT_DIR)/pkg/lib/sa/
files="sa-*.tar.gz"
stable="sa-1\.2\.6\.tar\.gz" unstable="sa-SNAP.*\.tar.gz">
<h2>Donation</h2>
<pkg_donation name="sa" return="$(BASE_URL)/pkg/lib/sa/">
