Index: ossp-pkg/sa/TODO
RCS File: /v/ossp/cvs/ossp-pkg/sa/TODO,v
co -q -kk -p'1.1' '/v/ossp/cvs/ossp-pkg/sa/TODO,v' | diff -u /dev/null - -L'ossp-pkg/sa/TODO' 2>/dev/null
--- ossp-pkg/sa/TODO
+++ -	2024-05-07 04:03:05.154834960 +0200
@@ -0,0 +1,17 @@
+
+Goals:
+1. struct sockaddr * abstraction
+2. ssize_t abstraction
+3. cache socket descriptors weil kein close existiert
+4. jede funktion hat timeout-possibility (connect_smart!)
+5. optional readline and buffering functionality
+
+TODO:
+buffer == 0 -> fully unbuffered
+timeout == 0 -> fully blocking
+
+- Unix domain sockets support
+- aufpassen dasz fuer read/write STREAM socket ist
+- aufpassen dasz fuer readfrom/writeto DGRAM socket ist
+- destructor fuer sa_addr_t?
+
Index: ossp-pkg/sa/sa.h
RCS File: /v/ossp/cvs/ossp-pkg/sa/sa.h,v
co -q -kk -p'1.1' '/v/ossp/cvs/ossp-pkg/sa/sa.h,v' | diff -u /dev/null - -L'ossp-pkg/sa/sa.h' 2>/dev/null
--- ossp-pkg/sa/sa.h
+++ -	2024-05-07 04:03:05.157598680 +0200
@@ -0,0 +1,90 @@
+/*
+**  SA - OSSP Socket Abstraction Library
+**  Copyright (c) 2001 The OSSP Project (http://www.ossp.org/)
+**  Copyright (c) 2001 Cable & Wireless Deutschland (http://www.cw.com/de/)
+**
+**  This file is part of OSSP SA, a socket abstraction library which
+**  can be found at http://www.ossp.org/pkg/sa/.
+**
+**  Permission to use, copy, modify, and distribute this software for
+**  any purpose with or without fee is hereby granted, provided that
+**  the above copyright notice and this permission notice appear in all
+**  copies.
+**
+**  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
+**  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+**  MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+**  IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
+**  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+**  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+**  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+**  USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+**  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+**  OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+**  OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+**  SUCH DAMAGE.
+**
+**  sa.h: socket abstraction API
+*/
+
+#ifndef __SA_H__
+#define __SA_H__
+
+/* system definitions of "size_t", "socklen_t", "struct sockaddr" */
+#include <string.h>
+#include <sys/types.h>
+#include <sys/socket.h>
+
+/* socket address abstraction object type */
+struct sa_addr_st;
+typedef struct sa_addr_st sa_addr_t;
+
+/* socket abstraction object type */
+struct sa_st;
+typedef struct sa_st sa_t;
+
+/* return codes */
+typedef enum {
+    SA_OK,
+    SA_ERR_ARG,
+    SA_ERR_USE,
+    SA_ERR_MEM,
+    SA_ERR_SYS,
+    SA_ERR_INT
+} sa_rc_t;
+
+/* address operations */
+sa_rc_t sa_u2a      (sa_addr_t **saa, const char *uri, ...);
+sa_rc_t sa_s2a      (sa_addr_t **saa, const struct sockaddr *sabuf, socklen_t salen);
+sa_rc_t sa_a2u      (const sa_addr_t *saa, char **uri);
+sa_rc_t sa_a2s      (const sa_addr_t *saa, struct sockaddr **sabuf, socklen_t *salen);
+
+/* object operations */
+sa_rc_t sa_create   (sa_t **sa);
+sa_rc_t sa_destroy  (sa_t *sa);
+
+/* parameter operations */
+sa_rc_t sa_timeout  (sa_t *sa, long sec, long usec);
+sa_rc_t sa_buffers  (sa_t *sa, size_t rsize, size_t wsize);
+
+/* connection operations */
+sa_rc_t sa_bind     (sa_t *sa, sa_addr_t *laddr);
+sa_rc_t sa_connect  (sa_t *sa, sa_addr_t *raddr);
+sa_rc_t sa_listen   (sa_t *sa, int backlog);
+sa_rc_t sa_accept   (sa_t *sa, sa_addr_t **caddr, sa_t **csa);
+sa_rc_t sa_getremote(sa_t *sa, sa_addr_t **raddr);
+sa_rc_t sa_getlocal (sa_t *sa, sa_addr_t **laddr);
+sa_rc_t sa_getfd    (sa_t *sa, int *fd);
+sa_rc_t sa_shutdown (sa_t *sa, char *flags);
+
+/* input/output operations */
+sa_rc_t sa_read     (sa_t *sa, char *buf, size_t buflen, size_t *bufdone);
+sa_rc_t sa_readfrom (sa_t *sa, char *buf, size_t buflen, size_t *bufdone, sa_addr_t **raddr);
+sa_rc_t sa_readline (sa_t *sa, char *buf, size_t buflen, size_t *bufdone);
+sa_rc_t sa_write    (sa_t *sa, const char *buf, size_t buflen, size_t *bufdone);
+sa_rc_t sa_writeto  (sa_t *sa, const char *buf, size_t buflen, size_t *bufdone, sa_addr_t *raddr);
+sa_rc_t sa_printf   (sa_t *sa, const char *fmt, ...);
+sa_rc_t sa_flush    (sa_t *sa);
+
+#endif /* __SA_H__ */
+
Index: ossp-pkg/sa/sa.pod
RCS File: /v/ossp/cvs/ossp-pkg/sa/sa.pod,v
co -q -kk -p'1.1' '/v/ossp/cvs/ossp-pkg/sa/sa.pod,v' | diff -u /dev/null - -L'ossp-pkg/sa/sa.pod' 2>/dev/null
--- ossp-pkg/sa/sa.pod
+++ -	2024-05-07 04:03:05.160463488 +0200
@@ -0,0 +1,219 @@
+##
+##  SA - OSSP Socket Abstraction Library
+##  Copyright (c) 2001 The OSSP Project (http://www.ossp.org/)
+##  Copyright (c) 2001 Cable & Wireless Deutschland (http://www.cw.com/de/)
+##
+##  This file is part of OSSP SA, a socket abstraction library which
+##  can be found at http://www.ossp.org/pkg/sa/.
+##
+##  Permission to use, copy, modify, and distribute this software for
+##  any purpose with or without fee is hereby granted, provided that
+##  the above copyright notice and this permission notice appear in all
+##  copies.
+##
+##  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
+##  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+##  MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+##  IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
+##  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+##  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+##  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+##  USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+##  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+##  OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+##  OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+##  SUCH DAMAGE.
+##
+##  sa.pod: socket abstraction library manual page
+##
+
+=pod
+
+=head1 NAME
+
+B<OSSP sa> - Socket Abstraction Library
+
+=head1 SYNOPSIS
+
+=over 4
+
+=item B<Abstract Data Types>:
+
+sa_addr_t,
+sa_t.
+
+=item B<Address Operations>:
+
+sa_u2a,
+sa_s2a,
+sa_a2u,
+sa_a2s.
+            
+=item B<Object Operations>:
+
+sa_create,
+sa_destroy. 
+            
+=item B<Parameter Operations>:
+
+sa_timeout,
+sa_buffers. 
+            
+=item B<Connection Operations>:
+
+sa_bind,
+sa_connect,
+sa_listen,
+sa_accept,  
+sa_getremote,
+sa_getlocal,
+sa_shutdown.
+
+=item B<Input/Output Operations>:
+            
+sa_read,
+sa_readfrom,
+sa_readline,
+sa_write,
+sa_writeto,
+sa_printf,
+sa_flush.   
+
+=back
+
+=head1 DESCRIPTION
+
+B<OSSP sa> is a thin abstraction library for the BSD socket interface
+for use in conjunction with TCP and UDP protocols. It provides the
+following key features:
+
+=over 4
+
+=item B<Address Abstraction>
+
+Most of the uglyness in the BSD socket API is the necessarity to have to
+deal with the various address structures (C<struct sockaddr_xx>) which
+exist because of both the different network protocols and addressing
+schemes. B<OSSP sa> fully hides this by providing an abstract and
+opaque address type (C<sa_addr_t>) together with four utility functions
+which allow one to convert from the old C<struct sockaddr> and an URL
+specification (C<{tcp,udp}://<host>[:<port>]>) to the C<sa_addr_t> and
+vice versa.
+
+=item B<I/O Timeouts>
+
+Each function of B<OSSP sa> is aware of a central timeout (set by
+sa_timeout(3)), i.e., all I/O operations return C<SA_ERR_SYS> and
+C<errno> set to C<ETIMEDOUT> if this timeout expired before the
+operation was able to succeed. This allows one to easily program
+less-blocking network services.
+
+=item B<Buffered I/O>
+
+If B<OSSP sa> is used for TCP-based stream I/O, internally all I/O
+operations can be performed through input and output buffers (set
+by sa_buffers(3)) for achieving higher I/O performance by doing I/O
+operations on larger messages.
+
+=item B<Convinience I/O Functions>
+
+If B<OSSP sa> is used for TCP-based stream I/O, for convinience reasons
+line reading (sa_readline(3)) and output formatting (sa_printf(3))
+functions are provided, modelled after STDIO's fgets(3) and fprintf(3).
+
+=back
+
+=head1 DATA TYPES
+
+=over 4
+
+=item B<sa_addr_t>
+
+=item B<sa_t>
+
+=back
+
+=head1 FUNCTIONS
+
+=head2 Address Operations
+
+=over 4
+
+=item sa_rc_t B<sa_u2a>(sa_addr_t **I<saa>, const char *I<uri>, ...);
+
+=item sa_rc_t B<sa_s2a>(sa_addr_t **I<saa>, const struct sockaddr *I<sabuf>, socklen_t I<salen>);
+
+=item sa_rc_t B<sa_a2u>(const sa_addr_t *I<saa>, char **I<uri>);
+
+=item sa_rc_t B<sa_a2s>(const sa_addr_t *I<saa>, struct sockaddr **I<sabuf>, socklen_t *I<salen>);
+
+=back
+            
+=head2 Object Operations
+
+=over 4
+
+=item sa_rc_t B<sa_create>(sa_t **I<sa>);
+
+=item sa_rc_t B<sa_destroy>(sa_t *I<sa>);
+
+=back
+            
+=head2 Parameter Operations
+
+=over 4
+
+=item sa_rc_t B<sa_timeout>(sa_t *I<sa>, long I<sec>, long I<usec>);
+
+=item sa_rc_t B<sa_buffers>(sa_t *I<sa>, size_t I<rsize>, size_t I<wsize>);
+
+=back
+            
+=head2 Connection Operations
+
+=over 4
+
+=item sa_rc_t B<sa_bind>(sa_t *I<sa>, sa_addr_t *I<laddr>);
+
+=item sa_rc_t B<sa_connect>(sa_t *I<sa>, sa_addr_t *I<raddr>);
+
+=item sa_rc_t B<sa_listen>(sa_t *I<sa>, int I<backlog>);
+
+=item sa_rc_t B<sa_accept>(sa_t *I<sa>, sa_addr_t **I<caddr>, sa_t **I<csa>);
+
+=item sa_rc_t B<sa_getremote>(sa_t *I<sa>, sa_addr_t **I<raddr>);
+
+=item sa_rc_t B<sa_getlocal>(sa_t *I<sa>, sa_addr_t **I<laddr>);
+
+=item sa_rc_t B<sa_shutdown>(sa_t *I<sa>, char *I<flags>);
+
+=back
+
+=head2 Input/Output Operations
+
+=over 4
+
+=item sa_rc_t B<sa_read>(sa_t *I<sa>, char *I<buf>, size_t I<buflen>, size_t *I<bufdone>);
+
+=item sa_rc_t B<sa_readfrom>(sa_t *I<sa>, char *I<buf>, size_t I<buflen>, size_t *I<bufdone>, sa_addr_t **I<raddr>);
+
+=item sa_rc_t B<sa_readline>(sa_t *I<sa>, char *I<buf>, size_t I<buflen>, size_t *I<bufdone>);
+
+=item sa_rc_t B<sa_write>(sa_t *I<sa>, const char *I<buf>, size_t I<buflen>, size_t *I<bufdone>);
+
+=item sa_rc_t B<sa_writeto>(sa_t *I<sa>, const char *I<buf>, size_t I<buflen>, size_t *I<bufdone>, sa_addr_t *I<raddr>);
+
+=item sa_rc_t B<sa_printf>(sa_t *I<sa>, const char *I<fmt>, ...);
+
+=item sa_rc_t B<sa_flush>(sa_t *I<sa>);
+
+=back
+
+=head1 AUTHORS
+
+ Ralf S. Engelschall
+ rse@engelschall.com
+ www.engelschall.com
+
+=cut
+