.TH IPSEC_INITADDR 3 "11 Sept 2000"
.\" RCSID $Id: initaddr.3,v 1.1 2004/03/15 20:35:26 as Exp $
.SH NAME
ipsec initaddr \- initialize an ip_address
.br
ipsec addrtypeof \- get address type of an ip_address
.br
ipsec addrlenof \- get length of address within an ip_address
.br
ipsec addrbytesof \- get copy of address within an ip_address
.br
ipsec addrbytesptr \- get pointer to address within an ip_address
.SH SYNOPSIS
.B "#include <freeswan.h>"
.sp
.B "const char *initaddr(const char *src, size_t srclen,"
.ti +1c
.B "int af, ip_address *dst);"
.br
.B "int addrtypeof(const ip_address *src);"
.br
.B "size_t addrlenof(const ip_address *src);"
.br
.B "size_t addrbytesof(const ip_address *src,"
.ti +1c
.B "unsigned char *dst, size_t dstlen);"
.br
.B "size_t addrbytesptr(const ip_address *src,"
.ti +1c
.B "const unsigned char **dst);"
.SH DESCRIPTION
The
.B <freeswan.h>
library uses an internal type
.I ip_address
to contain one of the (currently two) types of IP address.
These functions provide basic tools for creating and examining this type.
.PP
.I Initaddr
initializes a variable
.I *dst
of type
.I ip_address
from an address
(in network byte order,
indicated by a pointer
.I src
and a length
.IR srclen )
and an address family
.I af
(typically
.B AF_INET
or
.BR AF_INET6 ).
The length must be consistent with the address family.
.PP
.I Addrtypeof
returns the address type of an address,
normally
.B AF_INET
or
.BR AF_INET6 .
(The
.B <freeswan.h>
header file arranges to include the necessary headers for these
names to be known.)
.PP
.I Addrlenof
returns the size (in bytes) of the address within an
.IR ip_address ,
to permit storage allocation etc.
.PP
.I Addrbytesof
copies the address within the
.I ip_address
.I src
to the buffer indicated by the pointer
.I dst
and the length
.IR dstlen ,
and returns the address length (in bytes).
If the address will not fit,
as many bytes as will fit are copied;
the returned length is still the full length.
It is the caller's responsibility to check the
returned value to ensure that there was enough room.
.PP
.I Addrbytesptr
sets
.I *dst
to a pointer to the internal address within the
.IR ip_address ,
and returns the address length (in bytes).
If
.I dst
is
.BR NULL ,
it just returns the address length.
The pointer points to
.B const
to discourage misuse.
.PP
.I Initaddr
returns
.B NULL
for success and
a pointer to a string-literal error message for failure;
see DIAGNOSTICS.
.PP
The functions which return
.I size_t
return
.B 0
for a failure.
.SH SEE ALSO
inet(3), ipsec_ttoaddr(3)
.SH DIAGNOSTICS
An unknown address family is a fatal error for any of these functions
except
.IR addrtypeof .
An address-size mismatch is a fatal error for
.IR initaddr .
.SH HISTORY
Written for the FreeS/WAN project by Henry Spencer.
.SH BUGS
.I Addrtypeof
should probably have been named
.IR addrfamilyof .