Index: ossp-web/pkg/lib/sa/index.wml
RCS File: /v/ossp/cvs/ossp-web/pkg/lib/sa/index.wml,v
co -q -kk -p'1.21' '/v/ossp/cvs/ossp-web/pkg/lib/sa/index.wml,v' | diff -u /dev/null - -L'ossp-web/pkg/lib/sa/index.wml' 2>/dev/null
--- ossp-web/pkg/lib/sa/index.wml
+++ -	2025-04-04 18:08:29.531132414 +0200
@@ -0,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/">
+