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

DESCRIPTION

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

BUGS

265       Garbage in, garbage out.  Always use cidrvalidate() before doing
266       anything with untrusted input.  Otherwise, "slightly" invalid input
267       will work (extraneous whitespace is generally OK), but the functions
268       will croak if you're totally off the wall.
269

AUTHOR

271       Sam Varshavchik <sam@email-scan.com>
272
273       With some contributions from David Cantrell <david@cantrell.org.uk>
274
275
276
277perl v5.34.0                      2021-07-22                      Net::CIDR(3)
Impressum