1Net::CIDR(3) User Contributed Perl Documentation Net::CIDR(3)
2
3
4
6 Net::CIDR - Manipulate IPv4/IPv6 netblocks in CIDR notation
7
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
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
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
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)