1CIDR(3) User Contributed Perl Documentation CIDR(3)
2
6 Net::CIDR - Manipulate IPv4/IPv6 netblocks in CIDR notation
7
9 use Net::CIDR;
10 use Net::CIDR ':all';
12 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 print join("\n",
24 Net::CIDR::range2cidr(
25 "dead:beef::-dead:beef:ffff:ffff:ffff:ffff:ffff:ffff"))
26 . "\n";
27 #
29 # Output from above:
30 #
31 # dead:beef::/32
32 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 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 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 @list=("192.168.0.0/24");
55 @list=Net::CIDR::cidradd("192.168.1.0-192.168.1.255", @list);
56 print join("\n", @list) . "\n";
58 #
59 # Output from above:
60 #
61 # 192.168.0.0/23
62 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 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 @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 @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 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
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 @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 For example:
124 @a=Net::CIDR::range2cidr("192.168.0.0-192.168.255.255");
126 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 $a=Net::CIDR::range2cidr("192.168.0.0-192.168.255.255");
132 The result is a scalar "192.168.0.0/16".
134 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 @a=Net::CIDR::range2cidr("192.168.1.0-192.168.2.255");
140 The result is a two element array: ("192.168.1.0/24","192.168.2.0/24");
142 @a=Net::CIDR::range2cidr(
144 "d08c:43::-d08c:43:ffff:ffff:ffff:ffff:ffff:ffff");
145 The result is an one element array: ("d08c:43::/32") that reflects this
147 IPv6 netblock in CIDR notation.
148 range2cidr() does not merge adjacent or overlapping netblocks in
150 @range_list.
151 @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 @a=Net::CIDR::cidr2range("10.0.0.0/14", "192.168.0.0/24");
157 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 @a=Net::CIDR::cidr2range("d08c:43::/32");
162 The result is a one-element array:
164 ("d08c:43::-d08c:43:ffff:ffff:ffff:ffff:ffff:ffff").
165 cidr2range() does not merge adjacent or overlapping netblocks in
167 @cidr_list.
168 @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 @a=Net::CIDR::addr2cidr('192.168.0.31');
174 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 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 $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 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 @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 @octet_list=Net::CIDR::cidr2octets("10.0.0.0/14", "192.168.0.0/24");
202 The result is the following five-element array: ("10.0", "10.1",
204 "10.2", "10.3", "192.168.0").
205 For IPv6 addresses, the hexadecimal words in the resulting list are
207 zero-padded:
208 @octet_list=Net::CIDR::cidr2octets("::dead:beef:0:0/110");
210 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 @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 @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 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 $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 $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 $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 If $ip contains a "/", it must be a valid CIDR, otherwise it must be a
247 valid IPv4 or an IPv6 address.
248 A technically invalid CIDR, such as "192.168.0.1/24" fails validation,
250 returning undef.
251
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
259 Sam Varshavchik <sam@email-scan.com>
260 With some contributions from David Cantrell <david@cantrell.org.uk>
262perl v5.28.0 2018-06-11 CIDR(3)