freeswan/lib/initaddr.3

   1 .TH IPSEC_INITADDR 3 "11 Sept 2000"
   2 .\" RCSID $Id: initaddr.3,v 1.6 2002/03/12 16:49:56 henry Exp $
   3 .SH NAME
   4 ipsec initaddr \- initialize an ip_address
   5 .br
   6 ipsec addrtypeof \- get address type of an ip_address
   7 .br
   8 ipsec addrlenof \- get length of address within an ip_address
   9 .br
  10 ipsec addrbytesof \- get copy of address within an ip_address
  11 .br
  12 ipsec addrbytesptr \- get pointer to address within an ip_address
  13 .SH SYNOPSIS
  14 .B "#include <freeswan.h>"
  15 .sp
  16 .B "const char *initaddr(const char *src, size_t srclen,"
  17 .ti +1c
  18 .B "int af, ip_address *dst);"
  19 .br
  20 .B "int addrtypeof(const ip_address *src);"
  21 .br
  22 .B "size_t addrlenof(const ip_address *src);"
  23 .br
  24 .B "size_t addrbytesof(const ip_address *src,"
  25 .ti +1c
  26 .B "unsigned char *dst, size_t dstlen);"
  27 .br
  28 .B "size_t addrbytesptr(const ip_address *src,"
  29 .ti +1c
  30 .B "const unsigned char **dst);"
  31 .SH DESCRIPTION
  32 The
  33 .B <freeswan.h>
  34 library uses an internal type
  35 .I ip_address
  36 to contain one of the (currently two) types of IP address.
  37 These functions provide basic tools for creating and examining this type.
  38 .PP
  39 .I Initaddr
  40 initializes a variable
  41 .I *dst
  42 of type
  43 .I ip_address
  44 from an address
  45 (in network byte order,
  46 indicated by a pointer
  47 .I src
  48 and a length
  49 .IR srclen )
  50 and an address family
  51 .I af
  52 (typically
  53 .B AF_INET
  54 or
  55 .BR AF_INET6 ).
  56 The length must be consistent with the address family.
  57 .PP
  58 .I Addrtypeof
  59 returns the address type of an address,
  60 normally
  61 .B AF_INET
  62 or
  63 .BR AF_INET6 .
  64 (The
  65 .B <freeswan.h>
  66 header file arranges to include the necessary headers for these
  67 names to be known.)
  68 .PP
  69 .I Addrlenof
  70 returns the size (in bytes) of the address within an
  71 .IR ip_address ,
  72 to permit storage allocation etc.
  73 .PP
  74 .I Addrbytesof
  75 copies the address within the
  76 .I ip_address
  77 .I src
  78 to the buffer indicated by the pointer
  79 .I dst
  80 and the length
  81 .IR dstlen ,
  82 and returns the address length (in bytes).
  83 If the address will not fit,
  84 as many bytes as will fit are copied;
  85 the returned length is still the full length.
  86 It is the caller's responsibility to check the
  87 returned value to ensure that there was enough room.
  88 .PP
  89 .I Addrbytesptr
  90 sets
  91 .I *dst
  92 to a pointer to the internal address within the
  93 .IR ip_address ,
  94 and returns the address length (in bytes).
  95 If
  96 .I dst
  97 is
  98 .BR NULL ,
  99 it just returns the address length.
 100 The pointer points to
 101 .B const
 102 to discourage misuse.
 103 .PP
 104 .I Initaddr
 105 returns
 106 .B NULL
 107 for success and
 108 a pointer to a string-literal error message for failure;
 109 see DIAGNOSTICS.
 110 .PP
 111 The functions which return
 112 .I size_t
 113 return
 114 .B 0
 115 for a failure.
 116 .SH SEE ALSO
 117 inet(3), ipsec_ttoaddr(3)
 118 .SH DIAGNOSTICS
 119 An unknown address family is a fatal error for any of these functions
 120 except
 121 .IR addrtypeof .
 122 An address-size mismatch is a fatal error for
 123 .IR initaddr .
 124 .SH HISTORY
 125 Written for the FreeS/WAN project by Henry Spencer.
 126 .SH BUGS
 127 .I Addrtypeof
 128 should probably have been named
 129 .IR addrfamilyof .