[thirdparty/strongswan.git] / linux / lib / libfreeswan / initsubnet.3

.TH IPSEC_INITSUBNET 3 "12 March 2002"
.\" RCSID $Id: initsubnet.3,v 1.1 2004/03/15 20:35:26 as Exp $
.SH NAME
ipsec initsubnet \- initialize an ip_subnet
.br
ipsec addrtosubnet \- initialize a singleton ip_subnet
.br
ipsec subnettypeof \- get address type of an ip_subnet
.br
ipsec masktocount \- convert subnet mask to bit count
.br
ipsec networkof \- get base address of an ip_subnet
.br
ipsec maskof \- get subnet mask of an ip_subnet
.SH SYNOPSIS
.B "#include <freeswan.h>"
.sp
.B "const char *initsubnet(const ip_address *addr,"
.ti +1c
.B "int maskbits, int clash, ip_subnet *dst);"
.br
.B "const char *addrtosubnet(const ip_address *addr,"
.ti +1c
.B "ip_subnet *dst);"
.sp
.B "int subnettypeof(const ip_subnet *src);"
.br
.B "int masktocount(const ip_address *src);"
.br
.B "void networkof(const ip_subnet *src, ip_address *dst);"
.br
.B "void maskof(const ip_subnet *src, ip_address *dst);"
.SH DESCRIPTION
The
.B <freeswan.h>
library uses an internal type
.I ip_subnet
to contain a description of an IP subnet
(base address plus mask).
These functions provide basic tools for creating and examining this type.
.PP
.I Initsubnet
initializes a variable
.I *dst
of type
.I ip_subnet
from a base address and
a count of mask bits.
The
.I clash
parameter specifies what to do if the base address includes
.B 1
bits outside the prefix specified by the mask
(that is, in the ``host number'' part of the address):
.RS
.IP '0' 5
zero out host-number bits
.IP 'x'
non-zero host-number bits are an error
.RE
.PP
.I Initsubnet
returns
.B NULL
for success and
a pointer to a string-literal error message for failure;
see DIAGNOSTICS.
.PP
.I Addrtosubnet
initializes an
.I ip_subnet
variable
.I *dst
to a ``singleton subnet'' containing the single address
.IR *addr .
It returns
.B NULL
for success and
a pointer to a string-literal error message for failure.
.PP
.I Subnettypeof
returns the address type of a subnet,
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 Masktocount
converts a subnet mask, expressed as an address, to a bit count
suitable for use with
.IR initsubnet .
It returns
.B \-1
for error; see DIAGNOSTICS.
.PP
.I Networkof
fills in
.I *dst
with the base address of subnet
.IR src .
.PP
.I Maskof
fills in
.I *dst
with the subnet mask of subnet
.IR src ,
expressed as an address.
.SH SEE ALSO
inet(3), ipsec_ttosubnet(3), ipsec_rangetosubnet(3)
.SH DIAGNOSTICS
Fatal errors in
.I initsubnet
are:
unknown address family;
unknown
.I clash
value;
impossible mask bit count;
non-zero host-number bits and
.I clash
is
.BR 'x' .
Fatal errors in
.I addrtosubnet
are:
unknown address family.
Fatal errors in
.I masktocount
are:
unknown address family;
mask bits not contiguous.
.SH HISTORY
Written for the FreeS/WAN project by Henry Spencer.
Commit	Line	Data
997358a6 MW	1	.TH IPSEC_INITSUBNET 3 "12 March 2002"
	2	.\" RCSID $Id: initsubnet.3,v 1.1 2004/03/15 20:35:26 as 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.