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