ossp-pkg/sa/sa.pod
1.5
##
## 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,
sa_rc_t.
=item B<Address Object Operations>:
sa_addr_create,
sa_addr_destroy.
=item B<Address Operations>:
sa_addr_u2a,
sa_addr_s2a,
sa_addr_a2u,
sa_addr_a2s.
=item B<Socket Object Operations>:
sa_create,
sa_destroy.
=item B<Socket Parameter Operations>:
sa_timeout,
sa_buffers.
=item B<Socket Connection Operations>:
sa_bind,
sa_connect,
sa_listen,
sa_accept,
sa_getremote,
sa_getlocal,
sa_getfd,
sa_shutdown.
=item B<Socket Input/Output Operations>:
sa_read,
sa_readfrom,
sa_readline,
sa_write,
sa_writeto,
sa_writef,
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<Type Abstraction>
Some other subtle details in the socket API make the life hard in
practice: C<socklen_t> and C<ssize_t>. These two types originally were
(and on some platforms still are) plain integers or unsigned integers
while POSIX later introduced own types for them. This is nasty, because
for full backward compatibility and type-correct API usage, 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> hides all this in its API.
=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_writef(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>
=item B<sa_rc_tt>
=back
=head1 FUNCTIONS
=head2 Address Object Operations
=over 4
=item sa_rc_t B<sa_addr_create>(sa_addr_t **I<saa>);
=item sa_rc_t B<sa_addr_destroy>(sa_addr_t *I<saa>);
=back
=head2 Address Operations
=over 4
=item sa_rc_t B<sa_addr_u2a>(sa_addr_t *I<saa>, const char *I<uri>, ...);
=item sa_rc_t B<sa_addr_s2a>(sa_addr_t *I<saa>, const struct sockaddr *I<sabuf>, socklen_t I<salen>);
=item sa_rc_t B<sa_addr_a2u>(sa_addr_t *I<saa>, char **I<uri>);
=item sa_rc_t B<sa_addr_a2s>(sa_addr_t *I<saa>, struct sockaddr **I<sabuf>, socklen_t *I<salen>);
=back
=head2 Socket 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 Socket Parameter Operations
=over 4
=item sa_rc_t B<sa_type>(sa_t *I<sa>, sa_type_t I<type>);
=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>);
=item sa_rc_t B<sa_getoption>(sa_t *I<sa>, int I<optname>, void *I<optval>, socklen_t *I<optlen>);
=item sa_rc_t B<sa_setoption>(sa_t *I<sa>, int I<optname>, const void *I<optval>, socklen_t I<optlen>);
=back
=head2 Socket 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_getfd>(sa_t *I<sa>, int *I<fd>);
=item sa_rc_t B<sa_shutdown>(sa_t *I<sa>, char *I<flags>);
=back
=head2 Socket 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_writef>(sa_t *I<sa>, const char *I<fmt>, ...);
=item sa_rc_t B<sa_flush>(sa_t *I<sa>);
=back
=head1 HISTORY
B<OSSP sa> was invented in August 2001 by Ralf S. Engelschall for use
inside the OSSP project. Its creation was prompted by the requirement
to implement an SMTP logging channel for B<OSSP l2> (logging library).
Its initial code was derived from a predecessor sub-library originally
written for socket address abstraction inside B<OSSP lmtp2nntp>.
=head1 AUTHORS
Ralf S. Engelschall
rse@engelschall.com
www.engelschall.com
=cut
