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.html">luci.http</a>
46 <a href="../modules/luci.http.protocol.html">luci.http.protocol</a>
50 <a href="../modules/luci.http.protocol.conditionals.html">luci.http.protocol.conditionals</a>
54 <a href="../modules/luci.http.protocol.date.html">luci.http.protocol.date</a>
58 <a href="../modules/luci.http.protocol.mime.html">luci.http.protocol.mime</a>
62 <a href="../modules/luci.i18n.html">luci.i18n</a>
66 <a href="../modules/luci.ip.html">luci.ip</a>
69 <li><strong>luci.ip.cidr</strong></li>
72 <a href="../modules/luci.json.html">luci.json</a>
76 <a href="../modules/luci.jsonc.html">luci.jsonc</a>
80 <a href="../modules/luci.jsonc.parser.html">luci.jsonc.parser</a>
84 <a href="../modules/luci.model.ipkg.html">luci.model.ipkg</a>
88 <a href="../modules/luci.model.uci.html">luci.model.uci</a>
92 <a href="../modules/luci.rpcc.html">luci.rpcc</a>
96 <a href="../modules/luci.rpcc.ruci.html">luci.rpcc.ruci</a>
100 <a href="../modules/luci.sys.html">luci.sys</a>
104 <a href="../modules/luci.sys.init.html">luci.sys.init</a>
108 <a href="../modules/luci.sys.iptparser.html">luci.sys.iptparser</a>
112 <a href="../modules/luci.sys.net.html">luci.sys.net</a>
116 <a href="../modules/luci.sys.process.html">luci.sys.process</a>
120 <a href="../modules/luci.sys.user.html">luci.sys.user</a>
124 <a href="../modules/luci.sys.wifi.html">luci.sys.wifi</a>
128 <a href="../modules/luci.util.html">luci.util</a>
132 <a href="../modules/nixio.html">nixio</a>
136 <a href="../modules/nixio.CHANGELOG.html">nixio.CHANGELOG</a>
140 <a href="../modules/nixio.CryptoHash.html">nixio.CryptoHash</a>
144 <a href="../modules/nixio.File.html">nixio.File</a>
148 <a href="../modules/nixio.README.html">nixio.README</a>
152 <a href="../modules/nixio.Socket.html">nixio.Socket</a>
156 <a href="../modules/nixio.TLSContext.html">nixio.TLSContext</a>
160 <a href="../modules/nixio.TLSSocket.html">nixio.TLSSocket</a>
164 <a href="../modules/nixio.UnifiedIO.html">nixio.UnifiedIO</a>
168 <a href="../modules/nixio.bin.html">nixio.bin</a>
172 <a href="../modules/nixio.bit.html">nixio.bit</a>
176 <a href="../modules/nixio.crypto.html">nixio.crypto</a>
180 <a href="../modules/nixio.fs.html">nixio.fs</a>
195 </div><!-- id="navigation" -->
199 <h1>Object Instance <code>luci.ip.cidr</code></h1>
203 Represents an IPv4 or IPv6 address range.</p>
212 <table class="function_list">
215 <td class="name" nowrap><a href="#cidr.is4">cidr:is4</a> ()</td>
218 Checks whether the CIDR instance is an IPv4 address range
223 <td class="name" nowrap><a href="#cidr.is4rfc1918">cidr:is4rfc1918</a> ()</td>
226 Checks whether the CIDR instance is within the private RFC1918 address space
231 <td class="name" nowrap><a href="#cidr.is4linklocal">cidr:is4linklocal</a> ()</td>
234 Checks whether the CIDR instance is an IPv4 link local (Zeroconf) address
239 <td class="name" nowrap><a href="#cidr.is6">cidr:is6</a> ()</td>
242 Checks whether the CIDR instance is an IPv6 address range
247 <td class="name" nowrap><a href="#cidr.is6linklocal">cidr:is6linklocal</a> ()</td>
250 Checks whether the CIDR instance is an IPv6 link local address
255 <td class="name" nowrap><a href="#cidr.is6mapped4">cidr:is6mapped4</a> ()</td>
258 Checks whether the CIDR instance is an IPv6 mapped IPv4 address
263 <td class="name" nowrap><a href="#cidr.lower">cidr:lower</a> (addr)</td>
266 Checks whether this CIDR instance is lower than the given argument.</td>
270 <td class="name" nowrap><a href="#cidr.higher">cidr:higher</a> (addr)</td>
273 Checks whether this CIDR instance is higher than the given argument.</td>
277 <td class="name" nowrap><a href="#cidr.equal">cidr:equal</a> (addr)</td>
280 Checks whether this CIDR instance is equal to the given argument.</td>
284 <td class="name" nowrap><a href="#cidr.prefix">cidr:prefix</a> (mask)</td>
287 Get or set prefix size of CIDR instance.</td>
291 <td class="name" nowrap><a href="#cidr.network">cidr:network</a> (mask)</td>
294 Derive network address of CIDR instance.</td>
298 <td class="name" nowrap><a href="#cidr.host">cidr:host</a> ()</td>
301 Derive host address of CIDR instance.</td>
305 <td class="name" nowrap><a href="#cidr.mask">cidr:mask</a> (mask)</td>
308 Derive netmask of CIDR instance.</td>
312 <td class="name" nowrap><a href="#cidr.broadcast">cidr:broadcast</a> (mask)</td>
315 Derive broadcast address of CIDR instance.</td>
319 <td class="name" nowrap><a href="#cidr.mapped4">cidr:mapped4</a> ()</td>
322 Derive mapped IPv4 address of CIDR instance.</td>
326 <td class="name" nowrap><a href="#cidr.contains">cidr:contains</a> (addr)</td>
329 Test whether CIDR contains given range.</td>
333 <td class="name" nowrap><a href="#cidr.add">cidr:add</a> (amount, inplace)</td>
336 Add given amount to CIDR instance.</td>
340 <td class="name" nowrap><a href="#cidr.sub">cidr:sub</a> (amount, inplace)</td>
343 Substract given amount from CIDR instance.</td>
347 <td class="name" nowrap><a href="#cidr.minhost">cidr:minhost</a> ()</td>
350 Calculate the lowest possible host address within this CIDR instance.</td>
354 <td class="name" nowrap><a href="#cidr.maxhost">cidr:maxhost</a> ()</td>
357 Calculate the highest possible host address within this CIDR instance.</td>
361 <td class="name" nowrap><a href="#cidr.string">cidr:string</a> ()</td>
364 Convert CIDR instance into string representation.</td>
378 <h2><a name="functions"></a>Functions</h2>
379 <dl class="function">
383 <dt><a name="cidr.is4"></a><strong>cidr:is4</strong> ()</dt>
387 Checks whether the CIDR instance is an IPv4 address range
396 <h3>Return value:</h3>
397 <code>true</code> if the CIDR is an IPv4 range, else <code>false</code>
404 <li><a href="#cidr.is6">
415 <dt><a name="cidr.is4rfc1918"></a><strong>cidr:is4rfc1918</strong> ()</dt>
419 Checks whether the CIDR instance is within the private RFC1918 address space
427 <pre>local addr = luci.ip.new("192.168.45.2/24")
428 if addr:is4rfc1918() then
429 print("Is a private address")
434 <h3>Return value:</h3>
435 <code>true</code> if the entire range of this CIDR lies within one of
436 the ranges <code>10.0.0.0-10.255.255.255</code>,
437 <code>172.16.0.0-172.31.0.0</code> or
438 <code>192.168.0.0-192.168.255.255</code>, else <code>false</code>.
447 <dt><a name="cidr.is4linklocal"></a><strong>cidr:is4linklocal</strong> ()</dt>
451 Checks whether the CIDR instance is an IPv4 link local (Zeroconf) address
459 <pre>local addr = luci.ip.new("169.254.34.125")
460 if addr:is4linklocal() then
461 print("Is a zeroconf address")
466 <h3>Return value:</h3>
467 <code>true</code> if the entire range of this CIDR lies within the range
468 the range <code>169.254.0.0-169.254.255.255</code>, else <code>false</code>.
477 <dt><a name="cidr.is6"></a><strong>cidr:is6</strong> ()</dt>
481 Checks whether the CIDR instance is an IPv6 address range
490 <h3>Return value:</h3>
491 <code>true</code> if the CIDR is an IPv6 range, else <code>false</code>
498 <li><a href="#cidr.is4">
509 <dt><a name="cidr.is6linklocal"></a><strong>cidr:is6linklocal</strong> ()</dt>
513 Checks whether the CIDR instance is an IPv6 link local address
521 <pre>local addr = luci.ip.new("fe92:53a:3216:af01:221:63ff:fe75:aa17/64")
522 if addr:is6linklocal() then
523 print("Is a linklocal address")
528 <h3>Return value:</h3>
529 <code>true</code> if the entire range of this CIDR lies within the range
530 the <code>fe80::/10</code> range, else <code>false</code>.
539 <dt><a name="cidr.is6mapped4"></a><strong>cidr:is6mapped4</strong> ()</dt>
543 Checks whether the CIDR instance is an IPv6 mapped IPv4 address
551 <pre>local addr = luci.ip.new("::ffff:192.168.1.1")
552 if addr:is6mapped4() then
553 print("Is a mapped IPv4 address")
558 <h3>Return value:</h3>
559 <code>true</code> if the address is an IPv6 mapped IPv4 address in the
560 form <code>::ffff:1.2.3.4</code>.
569 <dt><a name="cidr.lower"></a><strong>cidr:lower</strong> (addr)</dt>
573 Checks whether this CIDR instance is lower than the given argument.
574 The comparisation follows these rules:
575 <ul><li>An IPv4 address is always lower than an IPv6 address</li>
576 <li>Prefix sizes are ignored</li></ul>
584 addr: A <code>luci.ip.cidr</code> instance or a string convertable by
585 <code>luci.ip.new()</code> to compare against.
594 <pre>local addr = luci.ip.new("192.168.1.1")
595 print(addr:lower(addr)) -- false
596 print(addr:lower("10.10.10.10/24")) -- false
597 print(addr:lower(luci.ip.new("::1"))) -- true
598 print(addr:lower(luci.ip.new("192.168.200.1"))) -- true</pre>
602 <h3>Return value:</h3>
603 <code>true</code> if this CIDR is lower than the given address,
604 else <code>false</code>.
611 <li><a href="#cidr.higher">
615 <li><a href="#cidr.equal">
626 <dt><a name="cidr.higher"></a><strong>cidr:higher</strong> (addr)</dt>
630 Checks whether this CIDR instance is higher than the given argument.
631 The comparisation follows these rules:
632 <ul><li>An IPv4 address is always lower than an IPv6 address</li>
633 <li>Prefix sizes are ignored</li></ul>
641 addr: A <code>luci.ip.cidr</code> instance or a string convertable by
642 <code>luci.ip.new()</code> to compare against.
651 <pre>local addr = luci.ip.new("192.168.1.1")
652 print(addr:higher(addr)) -- false
653 print(addr:higher("10.10.10.10/24")) -- true
654 print(addr:higher(luci.ip.new("::1"))) -- false
655 print(addr:higher(luci.ip.new("192.168.200.1"))) -- false</pre>
659 <h3>Return value:</h3>
660 <code>true</code> if this CIDR is higher than the given address,
661 else <code>false</code>.
668 <li><a href="#cidr.lower">
672 <li><a href="#cidr.equal">
683 <dt><a name="cidr.equal"></a><strong>cidr:equal</strong> (addr)</dt>
687 Checks whether this CIDR instance is equal to the given argument.
695 addr: A <code>luci.ip.cidr</code> instance or a string convertable by
696 <code>luci.ip.new()</code> to compare against.
705 <pre>local addr = luci.ip.new("192.168.1.1")
706 print(addr:equal(addr)) -- true
707 print(addr:equal("192.168.1.1")) -- true
708 print(addr:equal(luci.ip.new("::1"))) -- false
710 local addr6 = luci.ip.new("::1")
711 print(addr6:equal("0:0:0:0:0:0:0:1/64")) -- true
712 print(addr6:equal(luci.ip.new("fe80::221:63ff:fe75:aa17"))) -- false</pre>
716 <h3>Return value:</h3>
717 <code>true</code> if this CIDR is equal to the given address,
718 else <code>false</code>.
725 <li><a href="#cidr.lower">
729 <li><a href="#cidr.higher">
740 <dt><a name="cidr.prefix"></a><strong>cidr:prefix</strong> (mask)</dt>
744 Get or set prefix size of CIDR instance.
745 If the optional mask parameter is given, the prefix size of this CIDR is altered
746 else the current prefix size is returned.
754 mask: Either a number containing the number of bits (<code>0..32</code>
755 for IPv4, <code>0..128</code> for IPv6) or a string containing a valid
765 <pre>local range = luci.ip.new("192.168.1.1/255.255.255.0")
766 print(range:prefix()) -- 24
769 print(range:prefix()) -- 16
771 range:prefix("255.255.255.255")
772 print(range:prefix()) -- 32</pre>
776 <h3>Return value:</h3>
777 Bit count of the current prefix size
786 <dt><a name="cidr.network"></a><strong>cidr:network</strong> (mask)</dt>
790 Derive network address of CIDR instance.
792 Returns a new CIDR instance representing the network address of this instance
793 with all host parts masked out. The used prefix size can be overridden by the
794 optional mask parameter.
802 mask: Either a number containing the number of bits (<code>0..32</code>
803 for IPv4, <code>0..128</code> for IPv6) or a string containing a valid
813 <pre>local range = luci.ip.new("192.168.62.243/255.255.0.0")
814 print(range:network()) -- "192.168.0.0"
815 print(range:network(24)) -- "192.168.62.0"
816 print(range:network("255.255.255.0")) -- "192.168.62.0"
818 local range6 = luci.ip.new("fd9b:62b3:9cc5:0:221:63ff:fe75:aa17/64")
819 print(range6:network()) -- "fd9b:62b3:9cc5::"</pre>
823 <h3>Return value:</h3>
824 CIDR instance representing the network address
833 <dt><a name="cidr.host"></a><strong>cidr:host</strong> ()</dt>
837 Derive host address of CIDR instance.
839 This function essentially constructs a copy of this CIDR with the prefix size
840 set to <code>32</code> for IPv4 and <code>128</code> for IPv6.
848 <pre>local range = luci.ip.new("172.19.37.45/16")
849 print(range) -- "172.19.37.45/16"
850 print(range:host()) -- "172.19.37.45"</pre>
854 <h3>Return value:</h3>
855 CIDR instance representing the host address
864 <dt><a name="cidr.mask"></a><strong>cidr:mask</strong> (mask)</dt>
868 Derive netmask of CIDR instance.
870 Constructs a CIDR instance representing the netmask of this instance. The used
871 prefix size can be overridden by the optional mask parameter.
879 mask: Either a number containing the number of bits (<code>0..32</code>
880 for IPv4, <code>0..128</code> for IPv6) or a string containing a valid
890 <pre>local range = luci.ip.new("172.19.37.45/16")
891 print(range:mask()) -- "255.255.0.0"
892 print(range:mask(24)) -- "255.255.255.0"
893 print(range:mask("255.0.0.0")) -- "255.0.0.0"</pre>
897 <h3>Return value:</h3>
898 CIDR instance representing the netmask
907 <dt><a name="cidr.broadcast"></a><strong>cidr:broadcast</strong> (mask)</dt>
911 Derive broadcast address of CIDR instance.
913 Constructs a CIDR instance representing the broadcast address of this instance.
914 The used prefix size can be overridden by the optional mask parameter.
916 This function has no effect on IPv6 instances, it will return nothing in this
925 mask: Either a number containing the number of bits (<code>0..32</code>
926 for IPv4, <code>0..128</code> for IPv6) or a string containing a valid
936 <pre>local range = luci.ip.new("172.19.37.45/16")
937 print(range:broadcast()) -- "172.19.255.255"
938 print(range:broadcast(24)) -- "172.19.37.255"
939 print(range:broadcast("255.0.0.0")) -- "172.255.255.255"</pre>
943 <h3>Return value:</h3>
944 Return a new CIDR instance representing the broadcast address if this
945 instance is an IPv4 range, else return nothing.
954 <dt><a name="cidr.mapped4"></a><strong>cidr:mapped4</strong> ()</dt>
958 Derive mapped IPv4 address of CIDR instance.
960 Constructs a CIDR instance representing the IPv4 address of the IPv6 mapped
961 IPv4 address in this instance.
963 This function has no effect on IPv4 instances or IPv6 instances which are not a
964 mapped address, it will return nothing in this case.
972 <pre>local addr = luci.ip.new("::ffff:172.16.19.1")
973 print(addr:mapped4()) -- "172.16.19.1"</pre>
977 <h3>Return value:</h3>
978 Return a new CIDR instance representing the IPv4 address if this
979 instance is an IPv6 mapped IPv4 address, else return nothing.
988 <dt><a name="cidr.contains"></a><strong>cidr:contains</strong> (addr)</dt>
992 Test whether CIDR contains given range.
1000 addr: A <code>luci.ip.cidr</code> instance or a string convertable by
1001 <code>luci.ip.new()</code> to test.
1010 <pre>local range = luci.ip.new("10.24.0.0/255.255.0.0")
1011 print(range:contains("10.24.5.1")) -- true
1012 print(range:contains("::1")) -- false
1013 print(range:contains("10.0.0.0/8")) -- false
1015 local range6 = luci.ip.new("fe80::/10")
1016 print(range6:contains("fe80::221:63f:fe75:aa17/64")) -- true
1017 print(range6:contains("fd9b:6b3:c5:0:221:63f:fe75:aa17/64")) -- false</pre>
1021 <h3>Return value:</h3>
1022 <code>true</code> if this instance fully contains the given address else
1032 <dt><a name="cidr.add"></a><strong>cidr:add</strong> (amount, inplace)</dt>
1036 Add given amount to CIDR instance. If the result would overflow the maximum
1037 address space, the result is set to the highest possible address.
1045 amount: A numeric value between 0 and 0xFFFFFFFF, a
1046 <code>luci.ip.cidr</code> instance or a string convertable by
1047 <code>luci.ip.new()</code>.
1051 inplace: If <code>true</code>, modify this instance instead of returning
1052 a new derived CIDR instance.
1061 <pre>local addr = luci.ip.new("192.168.1.1/24")
1062 print(addr:add(250)) -- "192.168.1.251/24"
1063 print(addr:add("0.0.99.0")) -- "192.168.100.1/24"
1065 addr:add(256, true) -- true
1066 print(addr) -- "192.168.2.1/24
1068 addr:add("255.0.0.0", true) -- false (overflow)
1069 print(addr) -- "255.255.255.255/24
1071 local addr6 = luci.ip.new("fe80::221:63f:fe75:aa17/64")
1072 print(addr6:add(256)) -- "fe80::221:63f:fe75:ab17/64"
1073 print(addr6:add("::ffff:0")) -- "fe80::221:640:fe74:aa17/64"
1075 addr:add(256, true) -- true
1076 print(addr) -- "fe80::221:63f:fe75:ab17/64
1078 addr:add("ffff::", true) -- false (overflow)
1079 print(addr) -- "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff/64"</pre>
1083 <h3>Return value:</h3>
1085 <li>When adding inplace: Return <code>true</code> if the addition succeded
1086 or <code>false</code> when the addition overflowed.</li>
1087 <li>When deriving new CIDR: Return new instance representing the value of
1088 this instance plus the added amount or the highest possible address if
1089 the addition overflowed the available address space.</li></ul>
1098 <dt><a name="cidr.sub"></a><strong>cidr:sub</strong> (amount, inplace)</dt>
1102 Substract given amount from CIDR instance. If the result would under, the lowest
1103 possible address is returned.
1111 amount: A numeric value between 0 and 0xFFFFFFFF, a
1112 <code>luci.ip.cidr</code> instance or a string convertable by
1113 <code>luci.ip.new()</code>.
1117 inplace: If <code>true</code>, modify this instance instead of returning
1118 a new derived CIDR instance.
1127 <pre>local addr = luci.ip.new("192.168.1.1/24")
1128 print(addr:sub(256)) -- "192.168.0.1/24"
1129 print(addr:sub("0.168.0.0")) -- "192.0.1.1/24"
1131 addr:sub(256, true) -- true
1132 print(addr) -- "192.168.0.1/24
1134 addr:sub("255.0.0.0", true) -- false (underflow)
1135 print(addr) -- "0.0.0.0/24
1137 local addr6 = luci.ip.new("fe80::221:63f:fe75:aa17/64")
1138 print(addr6:sub(256)) -- "fe80::221:63f:fe75:a917/64"
1139 print(addr6:sub("::ffff:0")) -- "fe80::221:63e:fe76:aa17/64"
1141 addr:sub(256, true) -- true
1142 print(addr) -- "fe80::221:63f:fe75:a917/64"
1144 addr:sub("ffff::", true) -- false (underflow)
1145 print(addr) -- "::/64"</pre>
1149 <h3>Return value:</h3>
1151 <li>When substracting inplace: Return <code>true</code> if the substraction
1152 succeded or <code>false</code> when the substraction underflowed.</li>
1153 <li>When deriving new CIDR: Return new instance representing the value of
1154 this instance minus the substracted amount or the lowest address if
1155 the substraction underflowed.</li></ul>
1164 <dt><a name="cidr.minhost"></a><strong>cidr:minhost</strong> ()</dt>
1168 Calculate the lowest possible host address within this CIDR instance.
1176 <pre>local addr = luci.ip.new("192.168.123.56/24")
1177 print(addr:minhost()) -- "192.168.123.1"
1179 local addr6 = luci.ip.new("fd9b:62b3:9cc5:0:221:63ff:fe75:aa17/64")
1180 print(addr6:minhost()) -- "fd9b:62b3:9cc5::1"</pre>
1184 <h3>Return value:</h3>
1185 Returns a new CIDR instance representing the lowest host address
1195 <dt><a name="cidr.maxhost"></a><strong>cidr:maxhost</strong> ()</dt>
1199 Calculate the highest possible host address within this CIDR instance.
1207 <pre>local addr = luci.ip.new("192.168.123.56/24")
1208 print(addr:maxhost()) -- "192.168.123.254" (.255 is broadcast)
1210 local addr6 = luci.ip.new("fd9b:62b3:9cc5:0:221:63ff:fe75:aa17/64")
1211 print(addr6:maxhost()) -- "fd9b:62b3:9cc5:0:ffff:ffff:ffff:ffff"</pre>
1215 <h3>Return value:</h3>
1216 Returns a new CIDR instance representing the highest host address
1226 <dt><a name="cidr.string"></a><strong>cidr:string</strong> ()</dt>
1230 Convert CIDR instance into string representation.
1232 If the prefix size of instance is less than 32 for IPv4 or 128 for IPv6, the
1233 address is returned in the form "address/prefix" otherwise just "address".
1235 It is usually not required to call this function directly as CIDR objects
1236 define it as __tostring function in the associated metatable.
1245 <h3>Return value:</h3>
1246 Returns a string representing the range or address of this CIDR instance
1259 </div> <!-- id="content" -->
1261 </div> <!-- id="main" -->
1264 <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>
1265 </div> <!-- id="about" -->
1267 </div> <!-- id="container" -->