ossp-pkg/sa/sa.pod
1.1
##
## 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