*** /dev/null Sat Nov 23 09:45:31 2024
--- - Sat Nov 23 09:45:34 2024
***************
*** 0 ****
--- 1,129 ----
+
+ #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.3" stable_date="24-Jan-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\.3\.tar\.gz" unstable="sa-SNAP.*\.tar.gz">
+
+ <h2>Donation</h2>
+
+ <pkg_donation name="sa" return="$(BASE_URL)/pkg/lib/sa/">
+
|
