freeswan/lib/initsubnet.3

   1 .TH IPSEC_INITSUBNET 3 "12 March 2002"
   2 .\" RCSID $Id: initsubnet.3,v 1.4 2002/03/12 16:52:08 henry Exp $
   3 .SH NAME
   4 ipsec initsubnet \- initialize an ip_subnet
   5 .br
   6 ipsec addrtosubnet \- initialize a singleton ip_subnet
   7 .br
   8 ipsec subnettypeof \- get address type of an ip_subnet
   9 .br
  10 ipsec masktocount \- convert subnet mask to bit count
  11 .br
  12 ipsec networkof \- get base address of an ip_subnet
  13 .br
  14 ipsec maskof \- get subnet mask of an ip_subnet
  15 .SH SYNOPSIS
  16 .B "#include <freeswan.h>"
  17 .sp
  18 .B "const char *initsubnet(const ip_address *addr,"
  19 .ti +1c
  20 .B "int maskbits, int clash, ip_subnet *dst);"
  21 .br
  22 .B "const char *addrtosubnet(const ip_address *addr,"
  23 .ti +1c
  24 .B "ip_subnet *dst);"
  25 .sp
  26 .B "int subnettypeof(const ip_subnet *src);"
  27 .br
  28 .B "int masktocount(const ip_address *src);"
  29 .br
  30 .B "void networkof(const ip_subnet *src, ip_address *dst);"
  31 .br
  32 .B "void maskof(const ip_subnet *src, ip_address *dst);"
  33 .SH DESCRIPTION
  34 The
  35 .B <freeswan.h>
  36 library uses an internal type
  37 .I ip_subnet
  38 to contain a description of an IP subnet
  39 (base address plus mask).
  40 These functions provide basic tools for creating and examining this type.
  41 .PP
  42 .I Initsubnet
  43 initializes a variable
  44 .I *dst
  45 of type
  46 .I ip_subnet
  47 from a base address and
  48 a count of mask bits.
  49 The
  50 .I clash
  51 parameter specifies what to do if the base address includes
  52 .B 1
  53 bits outside the prefix specified by the mask
  54 (that is, in the ``host number'' part of the address):
  55 .RS
  56 .IP '0' 5
  57 zero out host-number bits
  58 .IP 'x'
  59 non-zero host-number bits are an error
  60 .RE
  61 .PP
  62 .I Initsubnet
  63 returns
  64 .B NULL
  65 for success and
  66 a pointer to a string-literal error message for failure;
  67 see DIAGNOSTICS.
  68 .PP
  69 .I Addrtosubnet
  70 initializes an
  71 .I ip_subnet
  72 variable
  73 .I *dst
  74 to a ``singleton subnet'' containing the single address
  75 .IR *addr .
  76 It returns
  77 .B NULL
  78 for success and
  79 a pointer to a string-literal error message for failure.
  80 .PP
  81 .I Subnettypeof
  82 returns the address type of a subnet,
  83 normally
  84 .B AF_INET
  85 or
  86 .BR AF_INET6 .
  87 (The
  88 .B <freeswan.h>
  89 header file arranges to include the necessary headers for these
  90 names to be known.)
  91 .PP
  92 .I Masktocount
  93 converts a subnet mask, expressed as an address, to a bit count
  94 suitable for use with
  95 .IR initsubnet .
  96 It returns
  97 .B \-1
  98 for error; see DIAGNOSTICS.
  99 .PP
 100 .I Networkof
 101 fills in
 102 .I *dst
 103 with the base address of subnet
 104 .IR src .
 105 .PP
 106 .I Maskof
 107 fills in
 108 .I *dst
 109 with the subnet mask of subnet
 110 .IR src ,
 111 expressed as an address.
 112 .SH SEE ALSO
 113 inet(3), ipsec_ttosubnet(3), ipsec_rangetosubnet(3)
 114 .SH DIAGNOSTICS
 115 Fatal errors in
 116 .I initsubnet
 117 are:
 118 unknown address family;
 119 unknown
 120 .I clash
 121 value;
 122 impossible mask bit count;
 123 non-zero host-number bits and
 124 .I clash
 125 is
 126 .BR 'x' .
 127 Fatal errors in
 128 .I addrtosubnet
 129 are:
 130 unknown address family.
 131 Fatal errors in
 132 .I masktocount
 133 are:
 134 unknown address family;
 135 mask bits not contiguous.
 136 .SH HISTORY
 137 Written for the FreeS/WAN project by Henry Spencer.