##
##  SA - Socket Address 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 lmtp2nntp, an LMTP speaking local
##  mailer which forwards mails as Usenet news articles via NNTP.
##  It can be found at http://www.ossp.com/pkg/lmtp2nntp/.
##
##  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: Unix manual page
##

=pod

=head1 NAME

B<SA> - Socket Address Library

=head1 SYNOPSIS

 #include "sa.h"


=head1 DESCRIPTION

B<SA> is a small abstraction library for creating C<struct sockaddr>
structures for use with the POSIX socket(3) API. The problem this
library solves is that the C<struct sockaddr> is just POSIX' old way
of passing different structures into a single API without the use of
C<void *> (which did not exist at the time socket(3) was invented).

B<SA> creates a C<struct sockaddr> which internally shadows C<struct
sockaddr_in> (for IPv4 addresses), C<struct sockaddr_in6> (for IPv6
addresses if supported by the underlying platform) and C<struct
sockaddr_un> (for local Unix domain socket addresses). Although there
are more variants, only these three are currently supported by B<SA>.

The result of a sa_create(3) call is a pointer to the following
structure:

 typedef struct {
  struct sockaddr *sa_buf;   /* pointer to struct sockaddr_xx */
  socklen_t        sa_len;   /* length of  struct sockaddr_xx */
  int              sa_proto; /* protocol identifier */
 } sa_t;

The following use cases are currently supported:

 sa_t *sa;
 int s;

 sa = sa_create(SA_UNIX, "/tmp/socket");
 sa = sa_create(SA_IP, "tcp", "mail.foo.dom", "25");
 sa = sa_create(SA_IP, "tcp", "127.0.0.1", "25");
 sa = sa_create(SA_IP, "tcp", ":::1", "25");

 s = socket(sa->sa_buf->sa_family, SOCK_STREAM, sa->sa_proto);
 connect(s, sa->sa_buf, sa->sa_len);

    :

 close(s);
 sa_destroy(ca);

=head1 AUTHOR

 Ralf S. Engelschall
 rse@engelschall.com
 www.engelschall.com

=cut