freeswan/lib/rangetosubnet.3

   1 .TH IPSEC_RANGETOSUBNET 3 "8 Sept 2000"
   2 .\" RCSID $Id: rangetosubnet.3,v 1.3 2000/09/08 18:09:09 henry Exp $
   3 .SH NAME
   4 ipsec rangetosubnet \- convert address range to subnet
   5 .SH SYNOPSIS
   6 .B "#include <freeswan.h>"
   7 .sp
   8 .B "const char *rangetosubnet(const ip_address *start,"
   9 .ti +1c
  10 .B "const ip_address *stop, ip_subnet *dst);"
  11 .SH DESCRIPTION
  12 .I Rangetosubnet
  13 accepts two IP addresses which define an address range,
  14 from
  15 .I start
  16 to
  17 .I stop
  18 inclusive,
  19 and converts this to a subnet if possible.
  20 The addresses must both be IPv4 or both be IPv6,
  21 and the address family of the resulting subnet is the same.
  22 .PP
  23 .I Rangetosubnet
  24 returns NULL for success and
  25 a pointer to a string-literal error message for failure;
  26 see DIAGNOSTICS.
  27 .SH SEE ALSO
  28 ipsec_initsubnet(3), ipsec_ttosubnet(3)
  29 .SH DIAGNOSTICS
  30 Fatal errors in
  31 .I rangetosubnet
  32 are:
  33 mixed address families;
  34 unknown address family;
  35 .I start
  36 and
  37 .I stop
  38 do not define a subnet.
  39 .SH HISTORY
  40 Written for the FreeS/WAN project by Henry Spencer.
  41 .SH BUGS
  42 The restriction of error reports to literal strings
  43 (so that callers don't need to worry about freeing them or copying them)
  44 does limit the precision of error reporting.
  45 .PP
  46 The error-reporting convention lends itself
  47 to slightly obscure code,
  48 because many readers will not think of NULL as signifying success.
  49 A good way to make it clearer is to write something like:
  50 .PP
  51 .RS
  52 .nf
  53 .B "const char *error;"
  54 .sp
  55 .B "error = rangetosubnet( /* ... */ );"
  56 .B "if (error != NULL) {"
  57 .B "        /* something went wrong */"
  58 .fi
  59 .RE