1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
5 <title>Reference</title>
6 <link rel="stylesheet" href="../luadoc.css" type="text/css" />
7 <!--meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/-->
14 <div id="product_logo"></div>
15 <div id="product_name"><big><b></b></big></div>
16 <div id="product_description"></div>
17 </div> <!-- id="product" -->
27 <li><a href="../index.html">Index</a></li>
38 <a href="../modules/luci.dispatcher.html">luci.dispatcher</a>
42 <a href="../modules/luci.http.protocol.html">luci.http.protocol</a>
46 <a href="../modules/luci.http.protocol.conditionals.html">luci.http.protocol.conditionals</a>
50 <a href="../modules/luci.http.protocol.date.html">luci.http.protocol.date</a>
54 <a href="../modules/luci.http.protocol.mime.html">luci.http.protocol.mime</a>
58 <a href="../modules/luci.i18n.html">luci.i18n</a>
62 <a href="../modules/luci.ip.html">luci.ip</a>
65 <li><strong>luci.ip.cidr</strong></li>
68 <a href="../modules/luci.jsonc.html">luci.jsonc</a>
72 <a href="../modules/luci.jsonc.parser.html">luci.jsonc.parser</a>
76 <a href="../modules/luci.sys.init.html">luci.sys.init</a>
80 <a href="../modules/luci.sys.iptparser.html">luci.sys.iptparser</a>
84 <a href="../modules/luci.sys.net.html">luci.sys.net</a>
88 <a href="../modules/luci.sys.process.html">luci.sys.process</a>
92 <a href="../modules/luci.sys.user.html">luci.sys.user</a>
96 <a href="../modules/luci.sys.wifi.html">luci.sys.wifi</a>
100 <a href="../modules/nixio.html">nixio</a>
104 <a href="../modules/nixio.CHANGELOG.html">nixio.CHANGELOG</a>
108 <a href="../modules/nixio.CryptoHash.html">nixio.CryptoHash</a>
112 <a href="../modules/nixio.File.html">nixio.File</a>
116 <a href="../modules/nixio.README.html">nixio.README</a>
120 <a href="../modules/nixio.Socket.html">nixio.Socket</a>
124 <a href="../modules/nixio.TLSContext.html">nixio.TLSContext</a>
128 <a href="../modules/nixio.TLSSocket.html">nixio.TLSSocket</a>
132 <a href="../modules/nixio.UnifiedIO.html">nixio.UnifiedIO</a>
136 <a href="../modules/nixio.bin.html">nixio.bin</a>
140 <a href="../modules/nixio.bit.html">nixio.bit</a>
144 <a href="../modules/nixio.crypto.html">nixio.crypto</a>
148 <a href="../modules/nixio.fs.html">nixio.fs</a>
163 </div><!-- id="navigation" -->
167 <h1>Object Instance <code>luci.ip.cidr</code></h1>
171 Represents an IPv4 or IPv6 address range.</p>
180 <table class="function_list">
183 <td class="name" nowrap><a href="#cidr.is4">cidr:is4</a> ()</td>
186 Checks whether the CIDR instance is an IPv4 address range
191 <td class="name" nowrap><a href="#cidr.is4rfc1918">cidr:is4rfc1918</a> ()</td>
194 Checks whether the CIDR instance is within the private RFC1918 address space
199 <td class="name" nowrap><a href="#cidr.is4linklocal">cidr:is4linklocal</a> ()</td>
202 Checks whether the CIDR instance is an IPv4 link local (Zeroconf) address
207 <td class="name" nowrap><a href="#cidr.is6">cidr:is6</a> ()</td>
210 Checks whether the CIDR instance is an IPv6 address range
215 <td class="name" nowrap><a href="#cidr.is6linklocal">cidr:is6linklocal</a> ()</td>
218 Checks whether the CIDR instance is an IPv6 link local address
223 <td class="name" nowrap><a href="#cidr.is6mapped4">cidr:is6mapped4</a> ()</td>
226 Checks whether the CIDR instance is an IPv6 mapped IPv4 address
231 <td class="name" nowrap><a href="#cidr.lower">cidr:lower</a> (addr)</td>
234 Checks whether this CIDR instance is lower than the given argument.</td>
238 <td class="name" nowrap><a href="#cidr.higher">cidr:higher</a> (addr)</td>
241 Checks whether this CIDR instance is higher than the given argument.</td>
245 <td class="name" nowrap><a href="#cidr.equal">cidr:equal</a> (addr)</td>
248 Checks whether this CIDR instance is equal to the given argument.</td>
252 <td class="name" nowrap><a href="#cidr.prefix">cidr:prefix</a> (mask)</td>
255 Get or set prefix size of CIDR instance.</td>
259 <td class="name" nowrap><a href="#cidr.network">cidr:network</a> (mask)</td>
262 Derive network address of CIDR instance.</td>
266 <td class="name" nowrap><a href="#cidr.host">cidr:host</a> ()</td>
269 Derive host address of CIDR instance.</td>
273 <td class="name" nowrap><a href="#cidr.mask">cidr:mask</a> (mask)</td>
276 Derive netmask of CIDR instance.</td>
280 <td class="name" nowrap><a href="#cidr.broadcast">cidr:broadcast</a> (mask)</td>
283 Derive broadcast address of CIDR instance.</td>
287 <td class="name" nowrap><a href="#cidr.mapped4">cidr:mapped4</a> ()</td>
290 Derive mapped IPv4 address of CIDR instance.</td>
294 <td class="name" nowrap><a href="#cidr.contains">cidr:contains</a> (addr)</td>
297 Test whether CIDR contains given range.</td>
301 <td class="name" nowrap><a href="#cidr.add">cidr:add</a> (amount, inplace)</td>
304 Add given amount to CIDR instance.</td>
308 <td class="name" nowrap><a href="#cidr.sub">cidr:sub</a> (amount, inplace)</td>
311 Substract given amount from CIDR instance.</td>
315 <td class="name" nowrap><a href="#cidr.minhost">cidr:minhost</a> ()</td>
318 Calculate the lowest possible host address within this CIDR instance.</td>
322 <td class="name" nowrap><a href="#cidr.maxhost">cidr:maxhost</a> ()</td>
325 Calculate the highest possible host address within this CIDR instance.</td>
329 <td class="name" nowrap><a href="#cidr.string">cidr:string</a> ()</td>
332 Convert CIDR instance into string representation.</td>
346 <h2><a name="functions"></a>Functions</h2>
347 <dl class="function">
351 <dt><a name="cidr.is4"></a><strong>cidr:is4</strong> ()</dt>
355 Checks whether the CIDR instance is an IPv4 address range
364 <h3>Return value:</h3>
365 <code>true</code> if the CIDR is an IPv4 range, else <code>false</code>
372 <li><a href="#cidr.is6">
383 <dt><a name="cidr.is4rfc1918"></a><strong>cidr:is4rfc1918</strong> ()</dt>
387 Checks whether the CIDR instance is within the private RFC1918 address space
395 <pre>local addr = luci.ip.new("192.168.45.2/24")
396 if addr:is4rfc1918() then
397 print("Is a private address")
402 <h3>Return value:</h3>
403 <code>true</code> if the entire range of this CIDR lies within one of
404 the ranges <code>10.0.0.0-10.255.255.255</code>,
405 <code>172.16.0.0-172.31.0.0</code> or
406 <code>192.168.0.0-192.168.255.255</code>, else <code>false</code>.
415 <dt><a name="cidr.is4linklocal"></a><strong>cidr:is4linklocal</strong> ()</dt>
419 Checks whether the CIDR instance is an IPv4 link local (Zeroconf) address
427 <pre>local addr = luci.ip.new("169.254.34.125")
428 if addr:is4linklocal() then
429 print("Is a zeroconf address")
434 <h3>Return value:</h3>
435 <code>true</code> if the entire range of this CIDR lies within the range
436 the range <code>169.254.0.0-169.254.255.255</code>, else <code>false</code>.
445 <dt><a name="cidr.is6"></a><strong>cidr:is6</strong> ()</dt>
449 Checks whether the CIDR instance is an IPv6 address range
458 <h3>Return value:</h3>
459 <code>true</code> if the CIDR is an IPv6 range, else <code>false</code>
466 <li><a href="#cidr.is4">
477 <dt><a name="cidr.is6linklocal"></a><strong>cidr:is6linklocal</strong> ()</dt>
481 Checks whether the CIDR instance is an IPv6 link local address
489 <pre>local addr = luci.ip.new("fe92:53a:3216:af01:221:63ff:fe75:aa17/64")
490 if addr:is6linklocal() then
491 print("Is a linklocal address")
496 <h3>Return value:</h3>
497 <code>true</code> if the entire range of this CIDR lies within the range
498 the <code>fe80::/10</code> range, else <code>false</code>.
507 <dt><a name="cidr.is6mapped4"></a><strong>cidr:is6mapped4</strong> ()</dt>
511 Checks whether the CIDR instance is an IPv6 mapped IPv4 address
519 <pre>local addr = luci.ip.new("::ffff:192.168.1.1")
520 if addr:is6mapped4() then
521 print("Is a mapped IPv4 address")
526 <h3>Return value:</h3>
527 <code>true</code> if the address is an IPv6 mapped IPv4 address in the
528 form <code>::ffff:1.2.3.4</code>.
537 <dt><a name="cidr.lower"></a><strong>cidr:lower</strong> (addr)</dt>
541 Checks whether this CIDR instance is lower than the given argument.
542 The comparisation follows these rules:
543 <ul><li>An IPv4 address is always lower than an IPv6 address</li>
544 <li>Prefix sizes are ignored</li></ul>
552 addr: A <code>luci.ip.cidr</code> instance or a string convertable by
553 <code>luci.ip.new()</code> to compare against.
562 <pre>local addr = luci.ip.new("192.168.1.1")
563 print(addr:lower(addr)) -- false
564 print(addr:lower("10.10.10.10/24")) -- false
565 print(addr:lower(luci.ip.new("::1"))) -- true
566 print(addr:lower(luci.ip.new("192.168.200.1"))) -- true</pre>
570 <h3>Return value:</h3>
571 <code>true</code> if this CIDR is lower than the given address,
572 else <code>false</code>.
579 <li><a href="#cidr.higher">
583 <li><a href="#cidr.equal">
594 <dt><a name="cidr.higher"></a><strong>cidr:higher</strong> (addr)</dt>
598 Checks whether this CIDR instance is higher than the given argument.
599 The comparisation follows these rules:
600 <ul><li>An IPv4 address is always lower than an IPv6 address</li>
601 <li>Prefix sizes are ignored</li></ul>
609 addr: A <code>luci.ip.cidr</code> instance or a string convertable by
610 <code>luci.ip.new()</code> to compare against.
619 <pre>local addr = luci.ip.new("192.168.1.1")
620 print(addr:higher(addr)) -- false
621 print(addr:higher("10.10.10.10/24")) -- true
622 print(addr:higher(luci.ip.new("::1"))) -- false
623 print(addr:higher(luci.ip.new("192.168.200.1"))) -- false</pre>
627 <h3>Return value:</h3>
628 <code>true</code> if this CIDR is higher than the given address,
629 else <code>false</code>.
636 <li><a href="#cidr.lower">
640 <li><a href="#cidr.equal">
651 <dt><a name="cidr.equal"></a><strong>cidr:equal</strong> (addr)</dt>
655 Checks whether this CIDR instance is equal to the given argument.
663 addr: A <code>luci.ip.cidr</code> instance or a string convertable by
664 <code>luci.ip.new()</code> to compare against.
673 <pre>local addr = luci.ip.new("192.168.1.1")
674 print(addr:equal(addr)) -- true
675 print(addr:equal("192.168.1.1")) -- true
676 print(addr:equal(luci.ip.new("::1"))) -- false
678 local addr6 = luci.ip.new("::1")
679 print(addr6:equal("0:0:0:0:0:0:0:1/64")) -- true
680 print(addr6:equal(luci.ip.new("fe80::221:63ff:fe75:aa17"))) -- false</pre>
684 <h3>Return value:</h3>
685 <code>true</code> if this CIDR is equal to the given address,
686 else <code>false</code>.
693 <li><a href="#cidr.lower">
697 <li><a href="#cidr.higher">
708 <dt><a name="cidr.prefix"></a><strong>cidr:prefix</strong> (mask)</dt>
712 Get or set prefix size of CIDR instance.
713 If the optional mask parameter is given, the prefix size of this CIDR is altered
714 else the current prefix size is returned.
722 mask: Either a number containing the number of bits (<code>0..32</code>
723 for IPv4, <code>0..128</code> for IPv6) or a string containing a valid
733 <pre>local range = luci.ip.new("192.168.1.1/255.255.255.0")
734 print(range:prefix()) -- 24
737 print(range:prefix()) -- 16
739 range:prefix("255.255.255.255")
740 print(range:prefix()) -- 32</pre>
744 <h3>Return value:</h3>
745 Bit count of the current prefix size
754 <dt><a name="cidr.network"></a><strong>cidr:network</strong> (mask)</dt>
758 Derive network address of CIDR instance.
760 Returns a new CIDR instance representing the network address of this instance
761 with all host parts masked out. The used prefix size can be overridden by the
762 optional mask parameter.
770 mask: Either a number containing the number of bits (<code>0..32</code>
771 for IPv4, <code>0..128</code> for IPv6) or a string containing a valid
781 <pre>local range = luci.ip.new("192.168.62.243/255.255.0.0")
782 print(range:network()) -- "192.168.0.0"
783 print(range:network(24)) -- "192.168.62.0"
784 print(range:network("255.255.255.0")) -- "192.168.62.0"
786 local range6 = luci.ip.new("fd9b:62b3:9cc5:0:221:63ff:fe75:aa17/64")
787 print(range6:network()) -- "fd9b:62b3:9cc5::"</pre>
791 <h3>Return value:</h3>
792 CIDR instance representing the network address
801 <dt><a name="cidr.host"></a><strong>cidr:host</strong> ()</dt>
805 Derive host address of CIDR instance.
807 This function essentially constructs a copy of this CIDR with the prefix size
808 set to <code>32</code> for IPv4 and <code>128</code> for IPv6.
816 <pre>local range = luci.ip.new("172.19.37.45/16")
817 print(range) -- "172.19.37.45/16"
818 print(range:host()) -- "172.19.37.45"</pre>
822 <h3>Return value:</h3>
823 CIDR instance representing the host address
832 <dt><a name="cidr.mask"></a><strong>cidr:mask</strong> (mask)</dt>
836 Derive netmask of CIDR instance.
838 Constructs a CIDR instance representing the netmask of this instance. The used
839 prefix size can be overridden by the optional mask parameter.
847 mask: Either a number containing the number of bits (<code>0..32</code>
848 for IPv4, <code>0..128</code> for IPv6) or a string containing a valid
858 <pre>local range = luci.ip.new("172.19.37.45/16")
859 print(range:mask()) -- "255.255.0.0"
860 print(range:mask(24)) -- "255.255.255.0"
861 print(range:mask("255.0.0.0")) -- "255.0.0.0"</pre>
865 <h3>Return value:</h3>
866 CIDR instance representing the netmask
875 <dt><a name="cidr.broadcast"></a><strong>cidr:broadcast</strong> (mask)</dt>
879 Derive broadcast address of CIDR instance.
881 Constructs a CIDR instance representing the broadcast address of this instance.
882 The used prefix size can be overridden by the optional mask parameter.
884 This function has no effect on IPv6 instances, it will return nothing in this
893 mask: Either a number containing the number of bits (<code>0..32</code>
894 for IPv4, <code>0..128</code> for IPv6) or a string containing a valid
904 <pre>local range = luci.ip.new("172.19.37.45/16")
905 print(range:broadcast()) -- "172.19.255.255"
906 print(range:broadcast(24)) -- "172.19.37.255"
907 print(range:broadcast("255.0.0.0")) -- "172.255.255.255"</pre>
911 <h3>Return value:</h3>
912 Return a new CIDR instance representing the broadcast address if this
913 instance is an IPv4 range, else return nothing.
922 <dt><a name="cidr.mapped4"></a><strong>cidr:mapped4</strong> ()</dt>
926 Derive mapped IPv4 address of CIDR instance.
928 Constructs a CIDR instance representing the IPv4 address of the IPv6 mapped
929 IPv4 address in this instance.
931 This function has no effect on IPv4 instances or IPv6 instances which are not a
932 mapped address, it will return nothing in this case.
940 <pre>local addr = luci.ip.new("::ffff:172.16.19.1")
941 print(addr:mapped4()) -- "172.16.19.1"</pre>
945 <h3>Return value:</h3>
946 Return a new CIDR instance representing the IPv4 address if this
947 instance is an IPv6 mapped IPv4 address, else return nothing.
956 <dt><a name="cidr.contains"></a><strong>cidr:contains</strong> (addr)</dt>
960 Test whether CIDR contains given range.
968 addr: A <code>luci.ip.cidr</code> instance or a string convertable by
969 <code>luci.ip.new()</code> to test.
978 <pre>local range = luci.ip.new("10.24.0.0/255.255.0.0")
979 print(range:contains("10.24.5.1")) -- true
980 print(range:contains("::1")) -- false
981 print(range:contains("10.0.0.0/8")) -- false
983 local range6 = luci.ip.new("fe80::/10")
984 print(range6:contains("fe80::221:63f:fe75:aa17/64")) -- true
985 print(range6:contains("fd9b:6b3:c5:0:221:63f:fe75:aa17/64")) -- false</pre>
989 <h3>Return value:</h3>
990 <code>true</code> if this instance fully contains the given address else
1000 <dt><a name="cidr.add"></a><strong>cidr:add</strong> (amount, inplace)</dt>
1004 Add given amount to CIDR instance. If the result would overflow the maximum
1005 address space, the result is set to the highest possible address.
1013 amount: A numeric value between 0 and 0xFFFFFFFF, a
1014 <code>luci.ip.cidr</code> instance or a string convertable by
1015 <code>luci.ip.new()</code>.
1019 inplace: If <code>true</code>, modify this instance instead of returning
1020 a new derived CIDR instance.
1029 <pre>local addr = luci.ip.new("192.168.1.1/24")
1030 print(addr:add(250)) -- "192.168.1.251/24"
1031 print(addr:add("0.0.99.0")) -- "192.168.100.1/24"
1033 addr:add(256, true) -- true
1034 print(addr) -- "192.168.2.1/24
1036 addr:add("255.0.0.0", true) -- false (overflow)
1037 print(addr) -- "255.255.255.255/24
1039 local addr6 = luci.ip.new("fe80::221:63f:fe75:aa17/64")
1040 print(addr6:add(256)) -- "fe80::221:63f:fe75:ab17/64"
1041 print(addr6:add("::ffff:0")) -- "fe80::221:640:fe74:aa17/64"
1043 addr:add(256, true) -- true
1044 print(addr) -- "fe80::221:63f:fe75:ab17/64
1046 addr:add("ffff::", true) -- false (overflow)
1047 print(addr) -- "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff/64"</pre>
1051 <h3>Return value:</h3>
1053 <li>When adding inplace: Return <code>true</code> if the addition succeded
1054 or <code>false</code> when the addition overflowed.</li>
1055 <li>When deriving new CIDR: Return new instance representing the value of
1056 this instance plus the added amount or the highest possible address if
1057 the addition overflowed the available address space.</li></ul>
1066 <dt><a name="cidr.sub"></a><strong>cidr:sub</strong> (amount, inplace)</dt>
1070 Substract given amount from CIDR instance. If the result would under, the lowest
1071 possible address is returned.
1079 amount: A numeric value between 0 and 0xFFFFFFFF, a
1080 <code>luci.ip.cidr</code> instance or a string convertable by
1081 <code>luci.ip.new()</code>.
1085 inplace: If <code>true</code>, modify this instance instead of returning
1086 a new derived CIDR instance.
1095 <pre>local addr = luci.ip.new("192.168.1.1/24")
1096 print(addr:sub(256)) -- "192.168.0.1/24"
1097 print(addr:sub("0.168.0.0")) -- "192.0.1.1/24"
1099 addr:sub(256, true) -- true
1100 print(addr) -- "192.168.0.1/24
1102 addr:sub("255.0.0.0", true) -- false (underflow)
1103 print(addr) -- "0.0.0.0/24
1105 local addr6 = luci.ip.new("fe80::221:63f:fe75:aa17/64")
1106 print(addr6:sub(256)) -- "fe80::221:63f:fe75:a917/64"
1107 print(addr6:sub("::ffff:0")) -- "fe80::221:63e:fe76:aa17/64"
1109 addr:sub(256, true) -- true
1110 print(addr) -- "fe80::221:63f:fe75:a917/64"
1112 addr:sub("ffff::", true) -- false (underflow)
1113 print(addr) -- "::/64"</pre>
1117 <h3>Return value:</h3>
1119 <li>When substracting inplace: Return <code>true</code> if the substraction
1120 succeded or <code>false</code> when the substraction underflowed.</li>
1121 <li>When deriving new CIDR: Return new instance representing the value of
1122 this instance minus the substracted amount or the lowest address if
1123 the substraction underflowed.</li></ul>
1132 <dt><a name="cidr.minhost"></a><strong>cidr:minhost</strong> ()</dt>
1136 Calculate the lowest possible host address within this CIDR instance.
1144 <pre>local addr = luci.ip.new("192.168.123.56/24")
1145 print(addr:minhost()) -- "192.168.123.1"
1147 local addr6 = luci.ip.new("fd9b:62b3:9cc5:0:221:63ff:fe75:aa17/64")
1148 print(addr6:minhost()) -- "fd9b:62b3:9cc5::1"</pre>
1152 <h3>Return value:</h3>
1153 Returns a new CIDR instance representing the lowest host address
1163 <dt><a name="cidr.maxhost"></a><strong>cidr:maxhost</strong> ()</dt>
1167 Calculate the highest possible host address within this CIDR instance.
1175 <pre>local addr = luci.ip.new("192.168.123.56/24")
1176 print(addr:maxhost()) -- "192.168.123.254" (.255 is broadcast)
1178 local addr6 = luci.ip.new("fd9b:62b3:9cc5:0:221:63ff:fe75:aa17/64")
1179 print(addr6:maxhost()) -- "fd9b:62b3:9cc5:0:ffff:ffff:ffff:ffff"</pre>
1183 <h3>Return value:</h3>
1184 Returns a new CIDR instance representing the highest host address
1194 <dt><a name="cidr.string"></a><strong>cidr:string</strong> ()</dt>
1198 Convert CIDR instance into string representation.
1200 If the prefix size of instance is less than 32 for IPv4 or 128 for IPv6, the
1201 address is returned in the form "address/prefix" otherwise just "address".
1203 It is usually not required to call this function directly as CIDR objects
1204 define it as __tostring function in the associated metatable.
1213 <h3>Return value:</h3>
1214 Returns a string representing the range or address of this CIDR instance
1227 </div> <!-- id="content" -->
1229 </div> <!-- id="main" -->
1232 <p><a href="http://validator.w3.org/check?uri=referer"><img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0!" height="31" width="88" /></a></p>
1233 </div> <!-- id="about" -->
1235 </div> <!-- id="container" -->