luci-app-adblock: fix function calls
[project/luci.git] / libs / luci-lib-ip / src / ip.luadoc
1 --- LuCI IP calculation and netlink access library.
2 module "luci.ip"
3
4 ---[[
5 Construct a new luci.ip.cidr instance and autodetect the address family.
6 Throws an error if the given strings do not represent a valid address or
7 if the given optional netmask is of a different family.
8 @class function
9 @sort 1
10 @name new
11 @param address  String containing a valid IPv4 or IPv6 address, optionally
12 with prefix size (CIDR notation) or netmask separated by slash.
13 @param netmask  String containing a valid IPv4 or IPv6 netmask or number
14 containing a prefix size in bits (`0..32` for IPv4,
15 `0..128` for IPv6). Overrides mask embedded in the first argument
16 if specified. (optional)
17 @return A `luci.ip.cidr` object representing the given
18 address/mask range.
19 @usage `addr = luci.ip.new("10.24.0.1/24")
20 addr = luci.ip.new("10.24.0.1/255.255.255.0")
21 addr = luci.ip.new("10.24.0.1", "255.255.255.0")        -- separate netmask
22 addr = luci.ip.new("10.24.0.1/24", 16)                  -- override netmask
23
24 addr6 = luci.ip.new("fe80::221:63ff:fe75:aa17/64")
25 addr6 = luci.ip.new("fe80::221:63ff:fe75:aa17/ffff:ffff:ffff:ffff::")
26 addr6 = luci.ip.new("fe80::221:63ff:fe75:aa17", "ffff:ffff:ffff:ffff::")
27 addr6 = luci.ip.new("fe80::221:63ff:fe75:aa17/64", 128) -- override netmask`
28 @see IPv4
29 @see IPv6
30 ]]
31
32 ---[[
33 Construct a new IPv4 luci.ip.cidr instance.
34 Throws an error if the given string does not represent a valid IPv4 address or
35 if the given optional netmask is of a different family.
36 @class function
37 @sort 2
38 @name IPv4
39 @param address  String containing a valid IPv4, optionally with prefix size
40 (CIDR notation) or netmask separated by slash.
41 @param netmask  String containing a valid IPv4 netmask or number
42 containing a prefix size between `0` and `32` bit.
43 Overrides mask embedded in the first argument if specified. (optional)
44 @return A `luci.ip.cidr` object representing the given IPv4 range.
45 @usage `addr = luci.ip.IPv4("10.24.0.1/24")
46 addr = luci.ip.IPv4("10.24.0.1/255.255.255.0")
47 addr = luci.ip.IPv4("10.24.0.1", "255.255.255.0")        -- separate netmask
48 addr = luci.ip.IPv4("10.24.0.1/24", 16)                  -- override netmask`
49 @see IPv6
50 ]]
51
52 ---[[
53 Construct a new IPv6 luci.ip.cidr instance.
54 Throws an error if the given string does not represent a valid IPv6 address or
55 if the given optional netmask is of a different family.
56 @class function
57 @sort 3
58 @name IPv6
59 @param address  String containing a valid IPv6, optionally with prefix size
60 (CIDR notation) or netmask separated by slash.
61 @param netmask  String containing a valid IPv4 netmask or number
62 containing a prefix size between `0` and `128` bit.
63 Overrides mask embedded in the first argument if specified. (optional)
64 @return A `luci.ip.cidr` object representing the given IPv6 range.
65 @usage `addr6 = luci.ip.IPv6("fe80::221:63ff:fe75:aa17/64")
66 addr6 = luci.ip.IPv6("fe80::221:63ff:fe75:aa17/ffff:ffff:ffff:ffff::")
67 addr6 = luci.ip.IPv6("fe80::221:63ff:fe75:aa17", "ffff:ffff:ffff:ffff::")
68 addr6 = luci.ip.IPv6("fe80::221:63ff:fe75:aa17/64", 128) -- override netmask`
69 @see IPv4
70 ]]
71
72 ---[[
73 Determine the route leading to the given destination.
74 @class function
75 @sort 4
76 @name route
77 @param address  A `luci.ip.cidr` instance or a string containing
78 a valid IPv4 or IPv6 range as specified by `luci.ip.new()`.
79 @return <p>Table containing the fields described below.</p>
80 <table id="routetable">
81 <tr><th>Field</th><th>Description</th></tr>
82 <tr><td>`type`<td>
83   <p>Route type with one of the following numeric values:</p>
84   <table>
85   <tr>
86         <td>`1`</td>
87         <td>`RTN_UNICAST` - Gateway or direct route</td>
88   </tr>
89   <tr>
90         <td>`2`</td>
91         <td>`RTN_LOCAL` - Accept locally</td>
92   </tr>
93   <tr>
94         <td>`3`</td>
95         <td>`RTN_BROADCAST` -
96             Accept locally as broadcast send as broadcast</td>
97   </tr>
98   <tr>
99         <td>`4`</td>
100         <td>`RTN_ANYCAST` -
101         Accept locally as broadcast but send as unicast</td>
102   </tr>
103   <tr>
104         <td>`5`</td>
105         <td>`RTN_MULTICAST` - Multicast route</td>
106   </tr>
107   </table>
108 </td></tr>
109 <tr>
110   <td>`family`</td>
111   <td>Number containing the route family, `4` for IPv4 or
112       `6` for IPv6</td>
113 </tr>
114 <tr>
115   <td>`dest`</td>
116   <td>Destination `luci.ip.cidr` instance</td>
117 </tr>
118 <tr>
119   <td>`gw`</td>
120   <td>Gateway `luci.ip.cidr` instance (optional)</td>
121 </tr>
122 <tr>
123   <td>`from`</td>
124   <td>Source address `luci.ip.cidr` instance (optional)</td>
125 </tr>
126 <tr>
127   <td>`src`</td>
128   <td>Preferred source `luci.ip.cidr` instance (optional)</td>
129 </tr>
130 <tr>
131   <td>`dev`</td>
132   <td>String containing the name of the outgoing interface</td>
133 </tr>
134 <tr>
135   <td>`iif`</td>
136   <td>String containing the name of the incoming interface (optional)</td>
137 </tr>
138 <tr>
139   <td>`table`</td>
140   <td>Number of the associated routing table (`0..65535`)</td>
141 </tr>
142 <tr>
143   <td>`proto`</td>
144   <td>Number of the associated routing protocol</td>
145 </tr>
146 <tr>
147   <td>`scope`</td>
148   <td>Number describing the scope of the route, most commonly
149       `0` for global or `253` for on-link</td>
150 </tr>
151 <tr>
152   <td>`metric`</td>
153   <td>Number describing the route metric (optional)</td>
154 </tr>
155 <tr>
156   <td>`expires`</td>
157   <td>Number of seconds the prefix is valid (IPv6 only, optional)</td>
158 </tr>
159 <tr>
160   <td>`error`</td>
161   <td>Route destination error code (optional)</td>
162 </tr>
163 </table>
164 @usage <ul>
165 <li>Find default gateway by getting route to Google's public NS server
166 `rt = luci.ip.route("8.8.8.8")
167 if rt ~= nil then
168         print("gateway is", rt.gw)
169 end`</li>
170 <li>Determine IPv6 upstream interface `rt = luci.ip.route("2001::/7")
171 if rt ~= nil then
172         print("ipv6 upstream device is", rt.dev)
173 end`</li>
174 </ul>
175 @see routes
176 ]]
177
178 ---[[
179 Fetch all routes, optionally matching the given criteria.
180 @class function
181 @sort 5
182 @name routes
183 @param filter  <p>Table containing one or more of the possible filter
184 critera described below (optional)</p><table>
185 <tr><th>Field</th><th>Description</th></tr>
186 <tr><td>`family`</td><td>
187  Number describing the address family to return - `4` selects
188  IPv4 routes, `6` IPv6 ones. Any other value selects both.
189 </td></tr>
190 <tr><td>`iif`</td><td>
191  String containing the incoming route interface to match.
192 </td></tr>
193 <tr><td>`oif`</td><td>
194  String containing the outgoing route interface to match.
195 </td></tr>
196 <tr><td>`type`</td><td>
197  Numeric type to match, e.g. `1` for unicast.
198 </td></tr>
199 <tr><td>`scope`</td><td>
200  Numeric scope to match, e.g. `253` for onlink.
201 </td></tr>
202 <tr><td>`proto`</td><td>
203  Numeric protocol to match, e.g. `2` for boot.
204 </td></tr>
205 <tr><td>`table`</td><td>
206  Numeric routing table to match (`0..65535`).
207 </td></tr>
208 <tr><td>`gw`</td><td>
209  String containing the gateway address to match. Can be in any notation
210  specified by `luci.ip.new()`. Prefix matching is performed when
211  comparing the routes, e.g. "192.168.1.0/24" would select routes with gateway
212  addresses `192.168.1.1 .. 192.168.1.255`.
213 </td></tr>
214 <tr><td>`dest`</td><td>
215  String containing the destination to match. Prefix matching is performed.
216 </td></tr>
217 <tr><td>`from`</td><td>
218  String containing the source address to match. Prefix matching is performed.
219 </td></tr>
220 <tr><td>`src`</td><td>
221  String containing the preferred source address to match.
222  Prefix matching is performed.
223 </td></tr>
224 <tr><td>`dest_exact`</td><td>
225  String containing the destination to match. Exact matching is performed,
226  e.g. `dest = "0.0.0.0/0"` would match <em>any</em> IPv4 route
227  while `dest_exact = "0.0.0.0/0"` will <em>only</em> match the
228  default route.
229 </td></tr>
230 <tr><td>`from_exact`</td><td>
231  String containing the source address to match. Exact matching is performed.
232 </td></tr>
233 </table>
234 @param callback  <p>Callback function to invoke for each found route
235 instead of returning one table of route objects (optional)</p>
236 @return If no callback function is provided, a table of routes
237 <a href="#routetable">as specified by `luci.ip.route()`</a>
238 is returned. If a callback function is given, it is invoked for each route
239 and nothing is returned.
240 @see route
241 @usage <ul>
242 <li>Find all IPv4 default routes:
243 `luci.ip.routes({ dest_exact = "0.0.0.0/0" }, function(rt)
244         print(rt.type, rt.gw, rt.dev)
245 end)`</li>
246 <li>Find all global IPv6 prefixes on the current system:
247 `luci.ip.routes({ from = "2001::/7" }, function(rt)
248         print(rt.from)
249 end)`</li>
250 <li>Fetch all IPv4 routes:
251 `routes = luci.ip.routes({ family = 4 })
252 for _, rt in ipairs(routes) do
253         print(rt.dest, rt.gw, rt.dev)
254 end`</li>
255 </ul>
256 ]]
257
258 ---[[
259 Fetches entries from the IPv4 ARP and IPv6 neighbour kernel table
260 @class function
261 @sort 6
262 @name neighbors
263 @param filter  <p>Table containing one or more of the possible filter
264 critera described below (optional)</p><table>
265 <tr><th>Field</th><th>Description</th></tr>
266 <tr><td>`family`</td><td>
267  Number describing the address family to return - `4` selects
268  IPv4 ARP, `6` select IPv6 neighbour entries. Any other value
269  selects both.
270 </td></tr>
271 <tr><td>`dev`</td><td>
272  String containing the associated interface to match.
273 </td></tr>
274 <tr><td>`dest`</td><td>
275  String containing the associated address to match. Can be in any notation
276  specified by `luci.ip.new()`. Prefix matching is performed when
277  comparing the addresses, e.g. "192.168.1.0/24" would select ARP entries
278  for `192.168.1.1 .. 192.168.1.255`.
279 </td></tr>
280 <tr><td>`mac`</td><td>
281  String containing MAC address to match.
282 </td></tr>
283 </table>
284 @param callback  <p>Callback function to invoke for each found neighbour
285 entry instead of returning one table of neighbour entries (optional)</p>
286 @return If no callback function is provided, a table of neighbour entries
287 is returned. If a callback function is given, it is invoked for each entry
288 and nothing is returned.
289
290 A neighbour entry is a table containing the following fields:
291
292 <table>
293 <tr><th>Field</th><th>Description</th></tr>
294 <tr>
295   <td>`family`</td>
296   <td>Number containing the neighbour entry family, `4` for IPv4
297       ARP or `6` for IPv6 NDP</td>
298 </tr>
299 <tr>
300   <td>`dev`</td>
301   <td>String containing the associated device of the neighbour entry</td>
302 </tr>
303 <tr>
304   <td>`dest`</td>
305   <td>IP address `luci.ip.cidr` instance</td>
306 </tr>
307 <tr>
308   <td>`mac`</td>
309   <td>String containing the associated MAC address</td>
310 </tr>
311 <tr>
312   <td>`router`</td>
313   <td>Boolean "true" if the neighbour entry is a router (IPv6, optional)</td>
314 </tr>
315 <tr>
316   <td>`proxy`</td>
317   <td>Boolean "true" if this is a proxy entry (optional)</td>
318 </tr>
319 <tr>
320   <td>`incomplete`</td>
321   <td>Boolean "true" if the entry is in incomplete state (optional)</td>
322 </tr>
323 <tr>
324   <td>`reachable`</td>
325   <td>Boolean "true" if the entry is in reachable state (optional)</td>
326 </tr>
327 <tr>
328   <td>`stale`</td>
329   <td>Boolean "true" if the entry is stale (optional)</td>
330 </tr>
331 <tr>
332   <td>`delay`</td>
333   <td>Boolean "true" if the entry is delayed (optional)</td>
334 </tr>
335 <tr>
336   <td>`probe`</td>
337   <td>Boolean "true" if the entry is in probe state (optional)</td>
338 </tr>
339 <tr>
340   <td>`failed`</td>
341   <td>Boolean "true" if the entry is in failed state (optional)</td>
342 </tr>
343 <tr>
344   <td>`noarp`</td>
345   <td>Boolean "true" if the entry is not caused by NDP or
346       ARP (optional)</td>
347 </tr>
348 <tr>
349   <td>`permanent`</td>
350   <td>Boolean "true" if the entry was statically configured from
351       userspace (optional)</td>
352 </tr>
353 </table>
354 @usage <ul>
355 <li>Find all ARP neighbours in the LAN:
356 `luci.ip.neighbors({ dest = "192.168.0.0/16" }, function(n)
357         print(n.dest, n.mac)
358 end)`</li>
359 <li>Find all active IPv6 addresses of host with given MAC:
360 `luci.ip.neighbors({ family = 6, mac = "00:21:63:75:aa:17" },
361         function(n)
362                 print(n.dest)
363         end)`</li>
364 </ul>
365 ]]
366
367 ---[[
368 Fetch basic device information
369 @class function
370 @sort 7
371 @name link
372 @param device  String containing the network device to query
373 @return  If the given interface is found, a table containing the fields
374 described below is returned, else an empty table.
375
376 <table>
377 <tr><th>Field</th><th>Description</th></tr>
378 <tr>
379   <td>`up`</td>
380   <td>Boolean indicating whether the device is in IFF_RUNNING state</td>
381 </tr>
382 <tr>
383   <td>`type`</td>
384   <td>Numeric value indicating the type of the device, e.g. `1`
385       for ethernet.</td>
386 </tr>
387 <tr>
388   <td>`name`</td>
389   <td>String containing the name of the device</td>
390 </tr>
391 <tr>
392   <td>`master`</td>
393   <td>If queried device is a bridge port, string containing the name of
394       parent bridge device (optional)</td>
395 </tr>
396 <tr>
397   <td>`mtu`</td>
398   <td>Number containing the current MTU of the device</td>
399 </tr>
400 <tr>
401   <td>`qlen`</td>
402   <td>Number containing the TX queue length of the device</td>
403 </tr>
404 <tr>
405   <td>`mac`</td>
406   <td>String containing the link local address of the device in
407       dotted hex notation</td>
408 </tr>
409 </table>
410 @usage <ul>
411 <li>Test whether device br-lan exists:
412 `print(luci.ip.link("br-lan").name ~= nil)
413 `</li>
414 <li>Query MAC address of eth0:
415 `print(luci.ip.link("eth0").mac)
416 `</li>
417 </ul>
418 ]]
419
420
421 --- IP CIDR Object.
422 -- Represents an IPv4 or IPv6 address range.
423 -- @cstyle instance
424 module "luci.ip.cidr"
425
426 ---[[
427 Checks whether the CIDR instance is an IPv4 address range
428
429 @class function
430 @sort 1
431 @name cidr.is4
432 @see cidr.is6
433 @return `true` if the CIDR is an IPv4 range, else `false`
434 ]]
435
436 ---[[
437 Checks whether the CIDR instance is within the private RFC1918 address space
438
439 @class function
440 @sort 2
441 @name cidr.is4rfc1918
442 @return `true` if the entire range of this CIDR lies within one of
443         the ranges `10.0.0.0-10.255.255.255`,
444         `172.16.0.0-172.31.0.0` or
445         `192.168.0.0-192.168.255.255`, else `false`.
446 @usage `local addr = luci.ip.new("192.168.45.2/24")
447 if addr:is4rfc1918() then
448         print("Is a private address")
449 end`
450 ]]
451
452 ---[[
453 Checks whether the CIDR instance is an IPv4 link local (Zeroconf) address
454
455 @class function
456 @sort 3
457 @name cidr.is4linklocal
458 @return `true` if the entire range of this CIDR lies within the range
459         the range `169.254.0.0-169.254.255.255`, else `false`.
460 @usage `local addr = luci.ip.new("169.254.34.125")
461 if addr:is4linklocal() then
462         print("Is a zeroconf address")
463 end`
464 ]]
465
466 ---[[
467 Checks whether the CIDR instance is an IPv6 address range
468
469 @class function
470 @sort 4
471 @name cidr.is6
472 @see cidr.is4
473 @return `true` if the CIDR is an IPv6 range, else `false`
474 ]]
475
476 ---[[
477 Checks whether the CIDR instance is an IPv6 link local address
478
479 @class function
480 @sort 5
481 @name cidr.is6linklocal
482 @return `true` if the entire range of this CIDR lies within the range
483         the `fe80::/10` range, else `false`.
484 @usage `local addr = luci.ip.new("fe92:53a:3216:af01:221:63ff:fe75:aa17/64")
485 if addr:is6linklocal() then
486         print("Is a linklocal address")
487 end`
488 ]]
489
490 ---[[
491 Checks whether the CIDR instance is an IPv6 mapped IPv4 address
492
493 @class function
494 @sort 6
495 @name cidr.is6mapped4
496 @return `true` if the address is an IPv6 mapped IPv4 address in the
497         form `::ffff:1.2.3.4`.
498 @usage `local addr = luci.ip.new("::ffff:192.168.1.1")
499 if addr:is6mapped4() then
500         print("Is a mapped IPv4 address")
501 end`
502 ]]
503
504 ---[[
505 Checks whether this CIDR instance is lower than the given argument.
506 The comparisation follows these rules:
507 <ul><li>An IPv4 address is always lower than an IPv6 address</li>
508 <li>Prefix sizes are ignored</li></ul>
509
510 @class function
511 @sort 7
512 @name cidr.lower
513 @param addr A `luci.ip.cidr` instance or a string convertable by
514         `luci.ip.new()` to compare against.
515 @return `true` if this CIDR is lower than the given address,
516         else `false`.
517 @usage `local addr = luci.ip.new("192.168.1.1")
518 print(addr:lower(addr)) -- false
519 print(addr:lower("10.10.10.10/24")) -- false
520 print(addr:lower(luci.ip.new("::1"))) -- true
521 print(addr:lower(luci.ip.new("192.168.200.1"))) -- true`
522 @see cidr.higher
523 @see cidr.equal
524 ]]
525
526 ---[[
527 Checks whether this CIDR instance is higher than the given argument.
528 The comparisation follows these rules:
529 <ul><li>An IPv4 address is always lower than an IPv6 address</li>
530 <li>Prefix sizes are ignored</li></ul>
531
532 @class function
533 @sort 8
534 @name cidr.higher
535 @param addr A `luci.ip.cidr` instance or a string convertable by
536         `luci.ip.new()` to compare against.
537 @return `true` if this CIDR is higher than the given address,
538         else `false`.
539 @usage `local addr = luci.ip.new("192.168.1.1")
540 print(addr:higher(addr)) -- false
541 print(addr:higher("10.10.10.10/24")) -- true
542 print(addr:higher(luci.ip.new("::1"))) -- false
543 print(addr:higher(luci.ip.new("192.168.200.1"))) -- false`
544 @see cidr.lower
545 @see cidr.equal
546 ]]
547
548 ---[[
549 Checks whether this CIDR instance is equal to the given argument.
550
551 @class function
552 @sort 9
553 @name cidr.equal
554 @param addr A `luci.ip.cidr` instance or a string convertable by
555         `luci.ip.new()` to compare against.
556 @return `true` if this CIDR is equal to the given address,
557         else `false`.
558 @usage `local addr = luci.ip.new("192.168.1.1")
559 print(addr:equal(addr)) -- true
560 print(addr:equal("192.168.1.1")) -- true
561 print(addr:equal(luci.ip.new("::1"))) -- false
562
563 local addr6 = luci.ip.new("::1")
564 print(addr6:equal("0:0:0:0:0:0:0:1/64")) -- true
565 print(addr6:equal(luci.ip.new("fe80::221:63ff:fe75:aa17"))) -- false`
566 @see cidr.lower
567 @see cidr.higher
568 ]]
569
570 ---[[
571 Get or set prefix size of CIDR instance.
572 If the optional mask parameter is given, the prefix size of this CIDR is altered
573 else the current prefix size is returned.
574
575 @class function
576 @sort 10
577 @name cidr.prefix
578 @param mask Either a number containing the number of bits (`0..32`
579         for IPv4, `0..128` for IPv6) or a string containing a valid
580         netmask (optional)
581 @return Bit count of the current prefix size
582 @usage `local range = luci.ip.new("192.168.1.1/255.255.255.0")
583 print(range:prefix()) -- 24
584
585 range:prefix(16)
586 print(range:prefix()) -- 16
587
588 range:prefix("255.255.255.255")
589 print(range:prefix()) -- 32`
590 ]]
591
592 ---[[
593 Derive network address of CIDR instance.
594
595 Returns a new CIDR instance representing the network address of this instance
596 with all host parts masked out. The used prefix size can be overridden by the
597 optional mask parameter.
598
599 @class function
600 @sort 11
601 @name cidr.network
602 @param mask Either a number containing the number of bits (`0..32`
603         for IPv4, `0..128` for IPv6) or a string containing a valid
604         netmask (optional)
605 @return CIDR instance representing the network address
606 @usage `local range = luci.ip.new("192.168.62.243/255.255.0.0")
607 print(range:network())                -- "192.168.0.0"
608 print(range:network(24))              -- "192.168.62.0"
609 print(range:network("255.255.255.0")) -- "192.168.62.0"
610
611 local range6 = luci.ip.new("fd9b:62b3:9cc5:0:221:63ff:fe75:aa17/64")
612 print(range6:network())               -- "fd9b:62b3:9cc5::"`
613 ]]
614
615 ---[[
616 Derive host address of CIDR instance.
617
618 This function essentially constructs a copy of this CIDR with the prefix size
619 set to `32` for IPv4 and `128` for IPv6.
620
621 @class function
622 @sort 12
623 @name cidr.host
624 @return CIDR instance representing the host address
625 @usage `local range = luci.ip.new("172.19.37.45/16")
626 print(range)        -- "172.19.37.45/16"
627 print(range:host()) -- "172.19.37.45"`
628 ]]
629
630 ---[[
631 Derive netmask of CIDR instance.
632
633 Constructs a CIDR instance representing the netmask of this instance. The used
634 prefix size can be overridden by the optional mask parameter.
635
636 @class function
637 @sort 13
638 @name cidr.mask
639 @param mask Either a number containing the number of bits (`0..32`
640         for IPv4, `0..128` for IPv6) or a string containing a valid
641         netmask (optional)
642 @return CIDR instance representing the netmask
643 @usage `local range = luci.ip.new("172.19.37.45/16")
644 print(range:mask())            -- "255.255.0.0"
645 print(range:mask(24))          -- "255.255.255.0"
646 print(range:mask("255.0.0.0")) -- "255.0.0.0"`
647 ]]
648
649 ---[[
650 Derive broadcast address of CIDR instance.
651
652 Constructs a CIDR instance representing the broadcast address of this instance.
653 The used prefix size can be overridden by the optional mask parameter.
654
655 This function has no effect on IPv6 instances, it will return nothing in this
656 case.
657
658 @class function
659 @sort 14
660 @name cidr.broadcast
661 @param mask Either a number containing the number of bits (`0..32`
662         for IPv4, `0..128` for IPv6) or a string containing a valid
663         netmask (optional)
664 @return Return a new CIDR instance representing the broadcast address if this
665         instance is an IPv4 range, else return nothing.
666 @usage `local range = luci.ip.new("172.19.37.45/16")
667 print(range:broadcast())            -- "172.19.255.255"
668 print(range:broadcast(24))          -- "172.19.37.255"
669 print(range:broadcast("255.0.0.0")) -- "172.255.255.255"`
670 ]]
671
672 ---[[
673 Derive mapped IPv4 address of CIDR instance.
674
675 Constructs a CIDR instance representing the IPv4 address of the IPv6 mapped
676 IPv4 address in this instance.
677
678 This function has no effect on IPv4 instances or IPv6 instances which are not a
679 mapped address, it will return nothing in this case.
680
681 @class function
682 @sort 15
683 @name cidr.mapped4
684 @return Return a new CIDR instance representing the IPv4 address if this
685         instance is an IPv6 mapped IPv4 address, else return nothing.
686 @usage `local addr = luci.ip.new("::ffff:172.16.19.1")
687 print(addr:mapped4()) -- "172.16.19.1"`
688 ]]
689
690 ---[[
691 Test whether CIDR contains given range.
692
693 @class function
694 @sort 16
695 @name cidr.contains
696 @param addr A `luci.ip.cidr` instance or a string convertable by
697         `luci.ip.new()` to test.
698 @return `true` if this instance fully contains the given address else
699         `false`.
700 @usage `local range = luci.ip.new("10.24.0.0/255.255.0.0")
701 print(range:contains("10.24.5.1"))  -- true
702 print(range:contains("::1"))        -- false
703 print(range:contains("10.0.0.0/8")) -- false
704
705 local range6 = luci.ip.new("fe80::/10")
706 print(range6:contains("fe80::221:63f:fe75:aa17/64"))         -- true
707 print(range6:contains("fd9b:6b3:c5:0:221:63f:fe75:aa17/64")) -- false`
708 ]]
709
710 ---[[
711 Add given amount to CIDR instance. If the result would overflow the maximum
712 address space, the result is set to the highest possible address.
713
714 @class function
715 @sort 17
716 @name cidr.add
717 @param amount A numeric value between 0 and 0xFFFFFFFF, a
718         `luci.ip.cidr` instance or a string convertable by
719         `luci.ip.new()`.
720 @param inplace If `true`, modify this instance instead of returning
721         a new derived CIDR instance.
722 @return <ul>
723         <li>When adding inplace: Return `true` if the addition succeded
724             or `false` when the addition overflowed.</li>
725         <li>When deriving new CIDR: Return new instance representing the value of
726         this instance plus the added amount or the highest possible address if
727             the addition overflowed the available address space.</li></ul>
728 @usage `local addr = luci.ip.new("192.168.1.1/24")
729 print(addr:add(250))         -- "192.168.1.251/24"
730 print(addr:add("0.0.99.0"))  -- "192.168.100.1/24"
731
732 addr:add(256, true)          -- true
733 print(addr)                  -- "192.168.2.1/24
734
735 addr:add("255.0.0.0", true)  -- false (overflow)
736 print(addr)                  -- "255.255.255.255/24
737
738 local addr6 = luci.ip.new("fe80::221:63f:fe75:aa17/64")
739 print(addr6:add(256))        -- "fe80::221:63f:fe75:ab17/64"
740 print(addr6:add("::ffff:0")) -- "fe80::221:640:fe74:aa17/64"
741
742 addr:add(256, true)          -- true
743 print(addr)                  -- "fe80::221:63f:fe75:ab17/64
744
745 addr:add("ffff::", true)     -- false (overflow)
746 print(addr)                  -- "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff/64"`
747 ]]
748
749 ---[[
750 Substract given amount from CIDR instance. If the result would under, the lowest
751 possible address is returned.
752
753 @class function
754 @sort 18
755 @name cidr.sub
756 @param amount A numeric value between 0 and 0xFFFFFFFF, a
757         `luci.ip.cidr` instance or a string convertable by
758         `luci.ip.new()`.
759 @param inplace If `true`, modify this instance instead of returning
760         a new derived CIDR instance.
761 @return <ul>
762         <li>When substracting inplace: Return `true` if the substraction
763             succeded or `false` when the substraction underflowed.</li>
764         <li>When deriving new CIDR: Return new instance representing the value of
765         this instance minus the substracted amount or the lowest address if
766             the substraction underflowed.</li></ul>
767 @usage `local addr = luci.ip.new("192.168.1.1/24")
768 print(addr:sub(256))         -- "192.168.0.1/24"
769 print(addr:sub("0.168.0.0")) -- "192.0.1.1/24"
770
771 addr:sub(256, true)          -- true
772 print(addr)                  -- "192.168.0.1/24
773
774 addr:sub("255.0.0.0", true)  -- false (underflow)
775 print(addr)                  -- "0.0.0.0/24
776
777 local addr6 = luci.ip.new("fe80::221:63f:fe75:aa17/64")
778 print(addr6:sub(256))        -- "fe80::221:63f:fe75:a917/64"
779 print(addr6:sub("::ffff:0")) -- "fe80::221:63e:fe76:aa17/64"
780
781 addr:sub(256, true)          -- true
782 print(addr)                  -- "fe80::221:63f:fe75:a917/64"
783
784 addr:sub("ffff::", true)     -- false (underflow)
785 print(addr)                  -- "::/64"`
786 ]]
787
788 ---[[
789 Calculate the lowest possible host address within this CIDR instance.
790
791 @class function
792 @sort 19
793 @name cidr.minhost
794 @return Returns a new CIDR instance representing the lowest host address
795         within this range.
796 @usage `local addr = luci.ip.new("192.168.123.56/24")
797 print(addr:minhost())  -- "192.168.123.1"
798
799 local addr6 = luci.ip.new("fd9b:62b3:9cc5:0:221:63ff:fe75:aa17/64")
800 print(addr6:minhost()) -- "fd9b:62b3:9cc5::1"`
801 ]]
802
803 ---[[
804 Calculate the highest possible host address within this CIDR instance.
805
806 @class function
807 @sort 20
808 @name cidr.maxhost
809 @return Returns a new CIDR instance representing the highest host address
810         within this range.
811 @usage `local addr = luci.ip.new("192.168.123.56/24")
812 print(addr:maxhost())  -- "192.168.123.254" (.255 is broadcast)
813
814 local addr6 = luci.ip.new("fd9b:62b3:9cc5:0:221:63ff:fe75:aa17/64")
815 print(addr6:maxhost()) -- "fd9b:62b3:9cc5:0:ffff:ffff:ffff:ffff"`
816 ]]
817
818 ---[[
819 Convert CIDR instance into string representation.
820
821 If the prefix size of instance is less than 32 for IPv4 or 128 for IPv6, the
822 address is returned in the form "address/prefix" otherwise just "address".
823
824 It is usually not required to call this function directly as CIDR objects
825 define it as __tostring function in the associated metatable.
826
827 @class function
828 @sort 21
829 @name cidr.string
830 @return Returns a string representing the range or address of this CIDR instance
831 ]]