1Net::CIDR(3)          User Contributed Perl Documentation         Net::CIDR(3)
2
3
4

NAME

6       Net::CIDR - Manipulate IPv4/IPv6 netblocks in CIDR notation
7

SYNOPSIS

9           use Net::CIDR;
10
11           use Net::CIDR ':all';
12
13           print join("\n",
14                 Net::CIDR::range2cidr("192.168.0.0-192.168.255.255",
15                                       "10.0.0.0-10.3.255.255"))
16                      . "\n";
17           #
18           # Output from above:
19           #
20           # 192.168.0.0/16
21           # 10.0.0.0/14
22
23           print join("\n",
24                 Net::CIDR::range2cidr(
25                       "dead:beef::-dead:beef:ffff:ffff:ffff:ffff:ffff:ffff"))
26                      . "\n";
27
28           #
29           # Output from above:
30           #
31           # dead:beef::/32
32
33           print join("\n",
34                    Net::CIDR::range2cidr("192.168.1.0-192.168.2.255"))
35                         . "\n";
36           #
37           # Output from above:
38           #
39           # 192.168.1.0/24
40           # 192.168.2.0/24
41
42           print join("\n", Net::CIDR::cidr2range("192.168.0.0/16")) . "\n";
43           #
44           # Output from above:
45           #
46           # 192.168.0.0-192.168.255.255
47
48           print join("\n", Net::CIDR::cidr2range("dead::beef::/46")) . "\n";
49           #
50           # Output from above:
51           #
52           # dead:beef::-dead:beef:3:ffff:ffff:ffff:ffff:ffff
53
54           @list=("192.168.0.0/24");
55           @list=Net::CIDR::cidradd("192.168.1.0-192.168.1.255", @list);
56
57           print join("\n", @list) . "\n";
58           #
59           # Output from above:
60           #
61           # 192.168.0.0/23
62
63           print join("\n", Net::CIDR::cidr2octets("192.168.0.0/22")) . "\n";
64           #
65           # Output from above:
66           #
67           # 192.168.0
68           # 192.168.1
69           # 192.168.2
70           # 192.168.3
71
72           print join("\n", Net::CIDR::cidr2octets("dead::beef::/46")) . "\n";
73           #
74           # Output from above:
75           #
76           # dead:beef:0000
77           # dead:beef:0001
78           # dead:beef:0002
79           # dead:beef:0003
80
81           @list=("192.168.0.0/24");
82           print Net::CIDR::cidrlookup("192.168.0.12", @list);
83           #
84           # Output from above:
85           #
86           # 1
87
88           @list = Net::CIDR::addr2cidr("192.168.0.31");
89           print join("\n", @list);
90           #
91           # Output from above:
92           #
93           # 192.168.0.31/32
94           # 192.168.0.30/31
95           # 192.168.0.28/30
96           # 192.168.0.24/29
97           # 192.168.0.16/28
98           # 192.168.0.0/27
99           # 192.168.0.0/26
100           # 192.168.0.0/25
101           # 192.168.0.0/24
102           # 192.168.0.0/23
103           # [and so on]
104
105           print Net::CIDR::addrandmask2cidr("195.149.50.61", "255.255.255.248")."\n";
106           #
107           # Output from above:
108           #
109           # 195.149.50.56/29
110

DESCRIPTION

112       The Net::CIDR package contains functions that manipulate lists of IP
113       netblocks expressed in CIDR notation.  The Net::CIDR functions handle
114       both IPv4 and IPv6 addresses.
115
116   @cidr_list=Net::CIDR::range2cidr(@range_list);
117       Each element in the @range_list is a string "start-finish", where
118       "start" is the first IP address and "finish" is the last IP address.
119       range2cidr() converts each range into an equivalent CIDR netblock.  It
120       returns a list of netblocks except in the case where it is given only
121       one parameter and is called in scalar context.
122
123       For example:
124
125           @a=Net::CIDR::range2cidr("192.168.0.0-192.168.255.255");
126
127       The result is a one-element array, with $a[0] being "192.168.0.0/16".
128       range2cidr() processes each "start-finish" element in @range_list
129       separately.  But if invoked like so:
130
131           $a=Net::CIDR::range2cidr("192.168.0.0-192.168.255.255");
132
133       The result is a scalar "192.168.0.0/16".
134
135       Where each element cannot be expressed as a single CIDR netblock
136       range2cidr() will generate as many CIDR netblocks as are necessary to
137       cover the full range of IP addresses.  Example:
138
139           @a=Net::CIDR::range2cidr("192.168.1.0-192.168.2.255");
140
141       The result is a two element array: ("192.168.1.0/24","192.168.2.0/24");
142
143           @a=Net::CIDR::range2cidr(
144                          "d08c:43::-d08c:43:ffff:ffff:ffff:ffff:ffff:ffff");
145
146       The result is an one element array: ("d08c:43::/32") that reflects this
147       IPv6 netblock in CIDR notation.
148
149       range2cidr() does not merge adjacent or overlapping netblocks in
150       @range_list.
151
152   @range_list=Net::CIDR::cidr2range(@cidr_list);
153       The cidr2range() functions converts a netblock list in CIDR notation to
154       a list of "start-finish" IP address ranges:
155
156           @a=Net::CIDR::cidr2range("10.0.0.0/14", "192.168.0.0/24");
157
158       The result is a two-element array: ("10.0.0.0-10.3.255.255",
159       "192.168.0.0-192.168.0.255").
160
161           @a=Net::CIDR::cidr2range("d08c:43::/32");
162
163       The result is a one-element array:
164       ("d08c:43::-d08c:43:ffff:ffff:ffff:ffff:ffff:ffff").
165
166       cidr2range() does not merge adjacent or overlapping netblocks in
167       @cidr_list.
168
169   @netblock_list = Net::CIDR::addr2cidr($address);
170       The addr2cidr function takes an IP address and returns a list of all
171       the CIDR netblocks it might belong to:
172
173           @a=Net::CIDR::addr2cidr('192.168.0.31');
174
175       The result is a thirtythree-element array: ('192.168.0.31/32',
176       '192.168.0.30/31', '192.168.0.28/30', '192.168.0.24/29',
177        [and so on]) consisting of all the possible subnets containing this
178       address from 0.0.0.0/0 to address/32.
179
180       Any addresses supplied to addr2cidr after the first will be ignored.
181       It works similarly for IPv6 addresses, returning a list of one hundred
182       and twenty nine elements.
183
184   $cidr=Net::CIDR::addrandmask2cidr($address, $netmask);
185       The addrandmask2cidr function takes an IP address and a netmask, and
186       returns the CIDR range whose size fits the netmask and which contains
187       the address.  It is an error to supply one parameter in IPv4-ish format
188       and the other in IPv6-ish format, and it is an error to supply a
189       netmask which does not consist solely of 1 bits followed by 0 bits.
190       For example, '255.255.248.192' is an invalid netmask, as is
191       '255.255.255.32' because both contain 0 bits in between 1 bits.
192
193       Technically speaking both of those *are* valid netmasks, but a) you'd
194       have to be insane to use them, and b) there's no corresponding CIDR
195       range.
196
197   @octet_list=Net::CIDR::cidr2octets(@cidr_list);
198       cidr2octets() takes @cidr_list and returns a list of leading octets
199       representing those netblocks.  Example:
200
201           @octet_list=Net::CIDR::cidr2octets("10.0.0.0/14", "192.168.0.0/24");
202
203       The result is the following five-element array: ("10.0", "10.1",
204       "10.2", "10.3", "192.168.0").
205
206       For IPv6 addresses, the hexadecimal words in the resulting list are
207       zero-padded:
208
209           @octet_list=Net::CIDR::cidr2octets("::dead:beef:0:0/110");
210
211       The result is a four-element array:
212       ("0000:0000:0000:0000:dead:beef:0000",
213       "0000:0000:0000:0000:dead:beef:0001",
214       "0000:0000:0000:0000:dead:beef:0002",
215       "0000:0000:0000:0000:dead:beef:0003").  Prefixes of IPv6 CIDR blocks
216       should be even multiples of 16 bits, otherwise they can potentially
217       expand out to a 32,768-element array, each!
218
219   @cidr_list=Net::CIDR::cidradd($block, @cidr_list);
220       The cidradd() functions allows a CIDR list to be built one CIDR
221       netblock at a time, merging adjacent and overlapping ranges.  $block is
222       a single netblock, expressed as either "start-finish", or
223       "address/prefix".  Example:
224
225           @cidr_list=Net::CIDR::range2cidr("192.168.0.0-192.168.0.255");
226           @cidr_list=Net::CIDR::cidradd("10.0.0.0/8", @cidr_list);
227           @cidr_list=Net::CIDR::cidradd("192.168.1.0-192.168.1.255", @cidr_list);
228
229       The result is a two-element array: ("10.0.0.0/8", "192.168.0.0/23").
230       IPv6 addresses are handled in an analogous fashion.
231
232   $found=Net::CIDR::cidrlookup($ip, @cidr_list);
233       Search for $ip in @cidr_list.  $ip can be a single IP address, or a
234       netblock in CIDR or start-finish notation.  lookup() returns 1 if $ip
235       overlaps any netblock in @cidr_list, 0 if not.
236
237   $ip=Net::CIDR::cidrvalidate($ip);
238       Validate whether $ip is a valid IPv4 or IPv6 address, or a CIDR.
239       Returns its argument or undef.  Spaces are removed, and IPv6
240       hexadecimal address are converted to lowercase.
241
242       $ip with less than four octets gets filled out with additional octets,
243       and the modified value gets returned. This turns "192.168/16" into a
244       proper "192.168.0.0/16".
245
246       If $ip contains a "/", it must be a valid CIDR, otherwise it must be a
247       valid IPv4 or an IPv6 address.
248
249       A technically invalid CIDR, such as "192.168.0.1/24" fails validation,
250       returning undef.
251

BUGS

253       Garbage in, garbage out.  Always use cidrvalidate() before doing
254       anything with untrusted input.  Otherwise, "slightly" invalid input
255       will work (extraneous whitespace is generally OK), but the functions
256       will croak if you're totally off the wall.
257

AUTHOR

259       Sam Varshavchik <sam@email-scan.com>
260
261       With some contributions from David Cantrell <david@cantrell.org.uk>
262
263
264
265perl v5.30.1                      2020-01-30                      Net::CIDR(3)
Impressum