diff options
Diffstat (limited to 'libs')
| -rw-r--r-- | libs/luci-lib-ip/src/ip.luadoc | 831 |
1 files changed, 831 insertions, 0 deletions
diff --git a/libs/luci-lib-ip/src/ip.luadoc b/libs/luci-lib-ip/src/ip.luadoc new file mode 100644 index 000000000..00738832c --- /dev/null +++ b/libs/luci-lib-ip/src/ip.luadoc @@ -0,0 +1,831 @@ +--- LuCI IP calculation and netlink access library. +module "luci.ip" + +---[[ +Construct a new luci.ip.cidr instance and autodetect the address family. +Throws an error if the given strings do not represent a valid address or +if the given optional netmask is of a different family. +@class function +@sort 1 +@name new +@param address String containing a valid IPv4 or IPv6 address, optionally +with prefix size (CIDR notation) or netmask separated by slash. +@param netmask String containing a valid IPv4 or IPv6 netmask or number +containing a prefix size in bits (`0..32` for IPv4, +`0..128` for IPv6). Overrides mask embedded in the first argument +if specified. (optional) +@return A `luci.ip.cidr` object representing the given +address/mask range. +@usage `addr = luci.ip.new("10.24.0.1/24") +addr = luci.ip.new("10.24.0.1/255.255.255.0") +addr = luci.ip.new("10.24.0.1", "255.255.255.0") -- separate netmask +addr = luci.ip.new("10.24.0.1/24", 16) -- override netmask + +addr6 = luci.ip.new("fe80::221:63ff:fe75:aa17/64") +addr6 = luci.ip.new("fe80::221:63ff:fe75:aa17/ffff:ffff:ffff:ffff::") +addr6 = luci.ip.new("fe80::221:63ff:fe75:aa17", "ffff:ffff:ffff:ffff::") +addr6 = luci.ip.new("fe80::221:63ff:fe75:aa17/64", 128) -- override netmask` +@see IPv4 +@see IPv6 +]] + +---[[ +Construct a new IPv4 luci.ip.cidr instance. +Throws an error if the given string does not represent a valid IPv4 address or +if the given optional netmask is of a different family. +@class function +@sort 2 +@name IPv4 +@param address String containing a valid IPv4, optionally with prefix size +(CIDR notation) or netmask separated by slash. +@param netmask String containing a valid IPv4 netmask or number +containing a prefix size between `0` and `32` bit. +Overrides mask embedded in the first argument if specified. (optional) +@return A `luci.ip.cidr` object representing the given IPv4 range. +@usage `addr = luci.ip.new("10.24.0.1/24") +addr = luci.ip.new("10.24.0.1/255.255.255.0") +addr = luci.ip.new("10.24.0.1", "255.255.255.0") -- separate netmask +addr = luci.ip.new("10.24.0.1/24", 16) -- override netmask` +@see IPv6 +]] + +---[[ +Construct a new IPv6 luci.ip.cidr instance. +Throws an error if the given string does not represent a valid IPv6 address or +if the given optional netmask is of a different family. +@class function +@sort 3 +@name IPv6 +@param address String containing a valid IPv6, optionally with prefix size +(CIDR notation) or netmask separated by slash. +@param netmask String containing a valid IPv4 netmask or number +containing a prefix size between `0` and `128` bit. +Overrides mask embedded in the first argument if specified. (optional) +@return A `luci.ip.cidr` object representing the given IPv6 range. +@usage `addr6 = luci.ip.new("fe80::221:63ff:fe75:aa17/64") +addr6 = luci.ip.new("fe80::221:63ff:fe75:aa17/ffff:ffff:ffff:ffff::") +addr6 = luci.ip.new("fe80::221:63ff:fe75:aa17", "ffff:ffff:ffff:ffff::") +addr6 = luci.ip.new("fe80::221:63ff:fe75:aa17/64", 128) -- override netmask` +@see IPv4 +]] + +---[[ +Determine the route leading to the given destination. +@class function +@sort 4 +@name route +@param address A `luci.ip.cidr` instance or a string containing +a valid IPv4 or IPv6 range as specified by `luci.ip.new()`. +@return <p>Table containing the fields described below.</p> +<table id="routetable"> +<tr><th>Field</th><th>Description</th></tr> +<tr><td>`type`<td> + <p>Route type with one of the following numeric values:</p> + <table> + <tr> + <td>`1`</td> + <td>`RTN_UNICAST` - Gateway or direct route</td> + </tr> + <tr> + <td>`2`</td> + <td>`RTN_LOCAL` - Accept locally</td> + </tr> + <tr> + <td>`3`</td> + <td>`RTN_BROADCAST` - + Accept locally as broadcast send as broadcast</td> + </tr> + <tr> + <td>`4`</td> + <td>`RTN_ANYCAST` - + Accept locally as broadcast but send as unicast</td> + </tr> + <tr> + <td>`5`</td> + <td>`RTN_MULTICAST` - Multicast route</td> + </tr> + </table> +</td></tr> +<tr> + <td>`family`</td> + <td>Number containing the route family, `4` for IPv4 or + `6` for IPv6</td> +</tr> +<tr> + <td>`dest`</td> + <td>Destination `luci.ip.cidr` instance</td> +</tr> +<tr> + <td>`gw`</td> + <td>Gateway `luci.ip.cidr` instance (optional)</td> +</tr> +<tr> + <td>`from`</td> + <td>Source address `luci.ip.cidr` instance (optional)</td> +</tr> +<tr> + <td>`src`</td> + <td>Preferred source `luci.ip.cidr` instance (optional)</td> +</tr> +<tr> + <td>`dev`</td> + <td>String containing the name of the outgoing interface</td> +</tr> +<tr> + <td>`iif`</td> + <td>String containing the name of the incoming interface (optional)</td> +</tr> +<tr> + <td>`table`</td> + <td>Number of the associated routing table (`0..65535`)</td> +</tr> +<tr> + <td>`proto`</td> + <td>Number of the associated routing protocol</td> +</tr> +<tr> + <td>`scope`</td> + <td>Number describing the scope of the route, most commonly + `0` for global or `253` for on-link</td> +</tr> +<tr> + <td>`metric`</td> + <td>Number describing the route metric (optional)</td> +</tr> +<tr> + <td>`expires`</td> + <td>Number of seconds the prefix is valid (IPv6 only, optional)</td> +</tr> +<tr> + <td>`error`</td> + <td>Route destination error code (optional)</td> +</tr> +</table> +@usage <ul> +<li>Find default gateway by getting route to Google's public NS server +`rt = luci.ip.route("8.8.8.8") +if rt ~= nil then + print("gateway is", rt.gw) +end`</li> +<li>Determine IPv6 upstream interface `rt = luci.ip.route("2001::/7") +if rt ~= nil then + print("ipv6 upstream device is", rt.dev) +end`</li> +</ul> +@see routes +]] + +---[[ +Fetch all routes, optionally matching the given criteria. +@class function +@sort 5 +@name routes +@param filter <p>Table containing one or more of the possible filter +critera described below (optional)</p><table> +<tr><th>Field</th><th>Description</th></tr> +<tr><td>`family`</td><td> + Number describing the address family to return - `4` selects + IPv4 routes, `6` IPv6 ones. Any other value selects both. +</td></tr> +<tr><td>`iif`</td><td> + String containing the incoming route interface to match. +</td></tr> +<tr><td>`oif`</td><td> + String containing the outgoing route interface to match. +</td></tr> +<tr><td>`type`</td><td> + Numeric type to match, e.g. `1` for unicast. +</td></tr> +<tr><td>`scope`</td><td> + Numeric scope to match, e.g. `253` for onlink. +</td></tr> +<tr><td>`proto`</td><td> + Numeric protocol to match, e.g. `2` for boot. +</td></tr> +<tr><td>`table`</td><td> + Numeric routing table to match (`0..65535`). +</td></tr> +<tr><td>`gw`</td><td> + String containing the gateway address to match. Can be in any notation + specified by `luci.ip.new()`. Prefix matching is performed when + comparing the routes, e.g. "192.168.1.0/24" would select routes with gateway + addresses `192.168.1.1 .. 192.168.1.255`. +</td></tr> +<tr><td>`dest`</td><td> + String containing the destination to match. Prefix matching is performed. +</td></tr> +<tr><td>`from`</td><td> + String containing the source address to match. Prefix matching is performed. +</td></tr> +<tr><td>`src`</td><td> + String containing the preferred source address to match. + Prefix matching is performed. +</td></tr> +<tr><td>`dest_exact`</td><td> + String containing the destination to match. Exact matching is performed, + e.g. `dest = "0.0.0.0/0"` would match <em>any</em> IPv4 route + while `dest_exact = "0.0.0.0/0"` will <em>only</em> match the + default route. +</td></tr> +<tr><td>`from_exact`</td><td> + String containing the source address to match. Exact matching is performed. +</td></tr> +</table> +@param callback <p>Callback function to invoke for each found route +instead of returning one table of route objects (optional)</p> +@return If no callback function is provided, a table of routes +<a href="#routetable">as specified by `luci.ip.route()`</a> +is returned. If a callback function is given, it is invoked for each route +and nothing is returned. +@see route +@usage <ul> +<li>Find all IPv4 default routes: +`luci.ip.routes({ dest_exact = "0.0.0.0/0" }, function(rt) + print(rt.type, rt.gw, rt.dev) +end)`</li> +<li>Find all global IPv6 prefixes on the current system: +`luci.ip.routes({ from = "2001::/7" }, function(rt) + print(rt.from) +end)`</li> +<li>Fetch all IPv4 routes: +`routes = luci.ip.routes({ family = 4 }) +for _, rt in ipairs(routes) do + print(rt.dest, rt.gw, rt.dev) +end`</li> +</ul> +]] + +---[[ +Fetches entries from the IPv4 ARP and IPv6 neighbour kernel table +@class function +@sort 6 +@name neighbors +@param filter <p>Table containing one or more of the possible filter +critera described below (optional)</p><table> +<tr><th>Field</th><th>Description</th></tr> +<tr><td>`family`</td><td> + Number describing the address family to return - `4` selects + IPv4 ARP, `6` select IPv6 neighbour entries. Any other value + selects both. +</td></tr> +<tr><td>`dev`</td><td> + String containing the associated interface to match. +</td></tr> +<tr><td>`dest`</td><td> + String containing the associated address to match. Can be in any notation + specified by `luci.ip.new()`. Prefix matching is performed when + comparing the addresses, e.g. "192.168.1.0/24" would select ARP entries + for `192.168.1.1 .. 192.168.1.255`. +</td></tr> +<tr><td>`mac`</td><td> + String containing MAC address to match. +</td></tr> +</table> +@param callback <p>Callback function to invoke for each found neighbour +entry instead of returning one table of neighbour entries (optional)</p> +@return If no callback function is provided, a table of neighbour entries +is returned. If a callback function is given, it is invoked for each entry +and nothing is returned. + +A neighbour entry is a table containing the following fields: + +<table> +<tr><th>Field</th><th>Description</th></tr> +<tr> + <td>`family`</td> + <td>Number containing the neighbour entry family, `4` for IPv4 + ARP or `6` for IPv6 NDP</td> +</tr> +<tr> + <td>`dev`</td> + <td>String containing the associated device of the neighbour entry</td> +</tr> +<tr> + <td>`dest`</td> + <td>IP address `luci.ip.cidr` instance</td> +</tr> +<tr> + <td>`mac`</td> + <td>String containing the associated MAC address</td> +</tr> +<tr> + <td>`router`</td> + <td>Boolean "true" if the neighbour entry is a router (IPv6, optional)</td> +</tr> +<tr> + <td>`proxy`</td> + <td>Boolean "true" if this is a proxy entry (optional)</td> +</tr> +<tr> + <td>`incomplete`</td> + <td>Boolean "true" if the entry is in incomplete state (optional)</td> +</tr> +<tr> + <td>`reachable`</td> + <td>Boolean "true" if the entry is in reachable state (optional)</td> +</tr> +<tr> + <td>`stale`</td> + <td>Boolean "true" if the entry is stale (optional)</td> +</tr> +<tr> + <td>`delay`</td> + <td>Boolean "true" if the entry is delayed (optional)</td> +</tr> +<tr> + <td>`probe`</td> + <td>Boolean "true" if the entry is in probe state (optional)</td> +</tr> +<tr> + <td>`failed`</td> + <td>Boolean "true" if the entry is in failed state (optional)</td> +</tr> +<tr> + <td>`noarp`</td> + <td>Boolean "true" if the entry is not caused by NDP or + ARP (optional)</td> +</tr> +<tr> + <td>`permanent`</td> + <td>Boolean "true" if the entry was statically configured from + userspace (optional)</td> +</tr> +</table> +@usage <ul> +<li>Find all ARP neighbours in the LAN: +`luci.ip.neighbors({ dest = "192.168.0.0/16" }, function(n) + print(n.dest, n.mac) +end)`</li> +<li>Find all active IPv6 addresses of host with given MAC: +`luci.ip.neighbors({ family = 6, mac = "00:21:63:75:aa:17" }, + function(n) + print(n.dest) + end)`</li> +</ul> +]] + +---[[ +Fetch basic device information +@class function +@sort 7 +@name link +@param device String containing the network device to query +@return If the given interface is found, a table containing the fields +described below is returned, else an empty table. + +<table> +<tr><th>Field</th><th>Description</th></tr> +<tr> + <td>`up`</td> + <td>Boolean indicating whether the device is in IFF_RUNNING state</td> +</tr> +<tr> + <td>`type`</td> + <td>Numeric value indicating the type of the device, e.g. `1` + for ethernet.</td> +</tr> +<tr> + <td>`name`</td> + <td>String containing the name of the device</td> +</tr> +<tr> + <td>`master`</td> + <td>If queried device is a bridge port, string containing the name of + parent bridge device (optional)</td> +</tr> +<tr> + <td>`mtu`</td> + <td>Number containing the current MTU of the device</td> +</tr> +<tr> + <td>`qlen`</td> + <td>Number containing the TX queue length of the device</td> +</tr> +<tr> + <td>`mac`</td> + <td>String containing the link local address of the device in + dotted hex notation</td> +</tr> +</table> +@usage <ul> +<li>Test whether device br-lan exists: +`print(luci.ip.link("br-lan").name ~= nil) +`</li> +<li>Query MAC address of eth0: +`print(luci.ip.link("eth0").mac) +`</li> +</ul> +]] + + +--- IP CIDR Object. +-- Represents an IPv4 or IPv6 address range. +-- @cstyle instance +module "luci.ip.cidr" + +---[[ +Checks whether the CIDR instance is an IPv4 address range + +@class function +@sort 1 +@name cidr.is4 +@see cidr.is6 +@return `true` if the CIDR is an IPv4 range, else `false` +]] + +---[[ +Checks whether the CIDR instance is within the private RFC1918 address space + +@class function +@sort 2 +@name cidr.is4rfc1918 +@return `true` if the entire range of this CIDR lies within one of + the ranges `10.0.0.0-10.255.255.255`, + `172.16.0.0-172.31.0.0` or + `192.168.0.0-192.168.255.255`, else `false`. +@usage `local addr = luci.ip.new("192.168.45.2/24") +if addr:is4rfc1918() then + print("Is a private address") +end` +]] + +---[[ +Checks whether the CIDR instance is an IPv4 link local (Zeroconf) address + +@class function +@sort 3 +@name cidr.is4linklocal +@return `true` if the entire range of this CIDR lies within the range + the range `169.254.0.0-169.254.255.255`, else `false`. +@usage `local addr = luci.ip.new("169.254.34.125") +if addr:is4linklocal() then + print("Is a zeroconf address") +end` +]] + +---[[ +Checks whether the CIDR instance is an IPv6 address range + +@class function +@sort 4 +@name cidr.is6 +@see cidr.is4 +@return `true` if the CIDR is an IPv6 range, else `false` +]] + +---[[ +Checks whether the CIDR instance is an IPv6 link local address + +@class function +@sort 5 +@name cidr.is6linklocal +@return `true` if the entire range of this CIDR lies within the range + the `fe80::/10` range, else `false`. +@usage `local addr = luci.ip.new("fe92:53a:3216:af01:221:63ff:fe75:aa17/64") +if addr:is6linklocal() then + print("Is a linklocal address") +end` +]] + +---[[ +Checks whether the CIDR instance is an IPv6 mapped IPv4 address + +@class function +@sort 6 +@name cidr.is6mapped4 +@return `true` if the address is an IPv6 mapped IPv4 address in the + form `::ffff:1.2.3.4`. +@usage `local addr = luci.ip.new("::ffff:192.168.1.1") +if addr:is6mapped4() then + print("Is a mapped IPv4 address") +end` +]] + +---[[ +Checks whether this CIDR instance is lower than the given argument. +The comparisation follows these rules: +<ul><li>An IPv4 address is always lower than an IPv6 address</li> +<li>Prefix sizes are ignored</li></ul> + +@class function +@sort 7 +@name cidr.lower +@param addr A `luci.ip.cidr` instance or a string convertable by + `luci.ip.new()` to compare against. +@return `true` if this CIDR is lower than the given address, + else `false`. +@usage `local addr = luci.ip.new("192.168.1.1") +print(addr:lower(addr)) -- false +print(addr:lower("10.10.10.10/24")) -- false +print(addr:lower(luci.ip.new("::1"))) -- true +print(addr:lower(luci.ip.new("192.168.200.1"))) -- true` +@see cidr.higher +@see cidr.equal +]] + +---[[ +Checks whether this CIDR instance is higher than the given argument. +The comparisation follows these rules: +<ul><li>An IPv4 address is always lower than an IPv6 address</li> +<li>Prefix sizes are ignored</li></ul> + +@class function +@sort 8 +@name cidr.higher +@param addr A `luci.ip.cidr` instance or a string convertable by + `luci.ip.new()` to compare against. +@return `true` if this CIDR is higher than the given address, + else `false`. +@usage `local addr = luci.ip.new("192.168.1.1") +print(addr:higher(addr)) -- false +print(addr:higher("10.10.10.10/24")) -- true +print(addr:higher(luci.ip.new("::1"))) -- false +print(addr:higher(luci.ip.new("192.168.200.1"))) -- false` +@see cidr.lower +@see cidr.equal +]] + +---[[ +Checks whether this CIDR instance is equal to the given argument. + +@class function +@sort 9 +@name cidr.equal +@param addr A `luci.ip.cidr` instance or a string convertable by + `luci.ip.new()` to compare against. +@return `true` if this CIDR is equal to the given address, + else `false`. +@usage `local addr = luci.ip.new("192.168.1.1") +print(addr:equal(addr)) -- true +print(addr:equal("192.168.1.1")) -- true +print(addr:equal(luci.ip.new("::1"))) -- false + +local addr6 = luci.ip.new("::1") +print(addr6:equal("0:0:0:0:0:0:0:1/64")) -- true +print(addr6:equal(luci.ip.new("fe80::221:63ff:fe75:aa17"))) -- false` +@see cidr.lower +@see cidr.higher +]] + +---[[ +Get or set prefix size of CIDR instance. +If the optional mask parameter is given, the prefix size of this CIDR is altered +else the current prefix size is returned. + +@class function +@sort 10 +@name cidr.prefix +@param mask Either a number containing the number of bits (`0..32` + for IPv4, `0..128` for IPv6) or a string containing a valid + netmask (optional) +@return Bit count of the current prefix size +@usage `local range = luci.ip.new("192.168.1.1/255.255.255.0") +print(range:prefix()) -- 24 + +range:prefix(16) +print(range:prefix()) -- 16 + +range:prefix("255.255.255.255") +print(range:prefix()) -- 32` +]] + +---[[ +Derive network address of CIDR instance. + +Returns a new CIDR instance representing the network address of this instance +with all host parts masked out. The used prefix size can be overridden by the +optional mask parameter. + +@class function +@sort 11 +@name cidr.network +@param mask Either a number containing the number of bits (`0..32` + for IPv4, `0..128` for IPv6) or a string containing a valid + netmask (optional) +@return CIDR instance representing the network address +@usage `local range = luci.ip.new("192.168.62.243/255.255.0.0") +print(range:network()) -- "192.168.0.0" +print(range:network(24)) -- "192.168.62.0" +print(range:network("255.255.255.0")) -- "192.168.62.0" + +local range6 = luci.ip.new("fd9b:62b3:9cc5:0:221:63ff:fe75:aa17/64") +print(range6:network()) -- "fd9b:62b3:9cc5::"` +]] + +---[[ +Derive host address of CIDR instance. + +This function essentially constructs a copy of this CIDR with the prefix size +set to `32` for IPv4 and `128` for IPv6. + +@class function +@sort 12 +@name cidr.host +@return CIDR instance representing the host address +@usage `local range = luci.ip.new("172.19.37.45/16") +print(range) -- "172.19.37.45/16" +print(range:host()) -- "172.19.37.45"` +]] + +---[[ +Derive netmask of CIDR instance. + +Constructs a CIDR instance representing the netmask of this instance. The used +prefix size can be overridden by the optional mask parameter. + +@class function +@sort 13 +@name cidr.mask +@param mask Either a number containing the number of bits (`0..32` + for IPv4, `0..128` for IPv6) or a string containing a valid + netmask (optional) +@return CIDR instance representing the netmask +@usage `local range = luci.ip.new("172.19.37.45/16") +print(range:mask()) -- "255.255.0.0" +print(range:mask(24)) -- "255.255.255.0" +print(range:mask("255.0.0.0")) -- "255.0.0.0"` +]] + +---[[ +Derive broadcast address of CIDR instance. + +Constructs a CIDR instance representing the broadcast address of this instance. +The used prefix size can be overridden by the optional mask parameter. + +This function has no effect on IPv6 instances, it will return nothing in this +case. + +@class function +@sort 14 +@name cidr.broadcast +@param mask Either a number containing the number of bits (`0..32` + for IPv4, `0..128` for IPv6) or a string containing a valid + netmask (optional) +@return Return a new CIDR instance representing the broadcast address if this + instance is an IPv4 range, else return nothing. +@usage `local range = luci.ip.new("172.19.37.45/16") +print(range:broadcast()) -- "172.19.255.255" +print(range:broadcast(24)) -- "172.19.37.255" +print(range:broadcast("255.0.0.0")) -- "172.255.255.255"` +]] + +---[[ +Derive mapped IPv4 address of CIDR instance. + +Constructs a CIDR instance representing the IPv4 address of the IPv6 mapped +IPv4 address in this instance. + +This function has no effect on IPv4 instances or IPv6 instances which are not a +mapped address, it will return nothing in this case. + +@class function +@sort 15 +@name cidr.mapped4 +@return Return a new CIDR instance representing the IPv4 address if this + instance is an IPv6 mapped IPv4 address, else return nothing. +@usage `local addr = luci.ip.new("::ffff:172.16.19.1") +print(addr:mapped4()) -- "172.16.19.1"` +]] + +---[[ +Test whether CIDR contains given range. + +@class function +@sort 16 +@name cidr.contains +@param addr A `luci.ip.cidr` instance or a string convertable by + `luci.ip.new()` to test. +@return `true` if this instance fully contains the given address else + `false`. +@usage `local range = luci.ip.new("10.24.0.0/255.255.0.0") +print(range:contains("10.24.5.1")) -- true +print(range:contains("::1")) -- false +print(range:contains("10.0.0.0/8")) -- false + +local range6 = luci.ip.new("fe80::/10") +print(range6:contains("fe80::221:63f:fe75:aa17/64")) -- true +print(range6:contains("fd9b:6b3:c5:0:221:63f:fe75:aa17/64")) -- false` +]] + +---[[ +Add given amount to CIDR instance. If the result would overflow the maximum +address space, the result is set to the highest possible address. + +@class function +@sort 17 +@name cidr.add +@param amount A numeric value between 0 and 0xFFFFFFFF, a + `luci.ip.cidr` instance or a string convertable by + `luci.ip.new()`. +@param inplace If `true`, modify this instance instead of returning + a new derived CIDR instance. +@return <ul> + <li>When adding inplace: Return `true` if the addition succeded + or `false` when the addition overflowed.</li> + <li>When deriving new CIDR: Return new instance representing the value of + this instance plus the added amount or the highest possible address if + the addition overflowed the available address space.</li></ul> +@usage `local addr = luci.ip.new("192.168.1.1/24") +print(addr:add(250)) -- "192.168.1.251/24" +print(addr:add("0.0.99.0")) -- "192.168.100.1/24" + +addr:add(256, true) -- true +print(addr) -- "192.168.2.1/24 + +addr:add("255.0.0.0", true) -- false (overflow) +print(addr) -- "255.255.255.255/24 + +local addr6 = luci.ip.new("fe80::221:63f:fe75:aa17/64") +print(addr6:add(256)) -- "fe80::221:63f:fe75:ab17/64" +print(addr6:add("::ffff:0")) -- "fe80::221:640:fe74:aa17/64" + +addr:add(256, true) -- true +print(addr) -- "fe80::221:63f:fe75:ab17/64 + +addr:add("ffff::", true) -- false (overflow) +print(addr) -- "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff/64"` +]] + +---[[ +Substract given amount from CIDR instance. If the result would under, the lowest +possible address is returned. + +@class function +@sort 18 +@name cidr.sub +@param amount A numeric value between 0 and 0xFFFFFFFF, a + `luci.ip.cidr` instance or a string convertable by + `luci.ip.new()`. +@param inplace If `true`, modify this instance instead of returning + a new derived CIDR instance. +@return <ul> + <li>When substracting inplace: Return `true` if the substraction + succeded or `false` when the substraction underflowed.</li> + <li>When deriving new CIDR: Return new instance representing the value of + this instance minus the substracted amount or the lowest address if + the substraction underflowed.</li></ul> +@usage `local addr = luci.ip.new("192.168.1.1/24") +print(addr:sub(256)) -- "192.168.0.1/24" +print(addr:sub("0.168.0.0")) -- "192.0.1.1/24" + +addr:sub(256, true) -- true +print(addr) -- "192.168.0.1/24 + +addr:sub("255.0.0.0", true) -- false (underflow) +print(addr) -- "0.0.0.0/24 + +local addr6 = luci.ip.new("fe80::221:63f:fe75:aa17/64") +print(addr6:sub(256)) -- "fe80::221:63f:fe75:a917/64" +print(addr6:sub("::ffff:0")) -- "fe80::221:63e:fe76:aa17/64" + +addr:sub(256, true) -- true +print(addr) -- "fe80::221:63f:fe75:a917/64" + +addr:sub("ffff::", true) -- false (underflow) +print(addr) -- "::/64"` +]] + +---[[ +Calculate the lowest possible host address within this CIDR instance. + +@class function +@sort 19 +@name cidr.minhost +@return Returns a new CIDR instance representing the lowest host address + within this range. +@usage `local addr = luci.ip.new("192.168.123.56/24") +print(addr:minhost()) -- "192.168.123.1" + +local addr6 = luci.ip.new("fd9b:62b3:9cc5:0:221:63ff:fe75:aa17/64") +print(addr6:minhost()) -- "fd9b:62b3:9cc5::1"` +]] + +---[[ +Calculate the highest possible host address within this CIDR instance. + +@class function +@sort 20 +@name cidr.maxhost +@return Returns a new CIDR instance representing the highest host address + within this range. +@usage `local addr = luci.ip.new("192.168.123.56/24") +print(addr:maxhost()) -- "192.168.123.254" (.255 is broadcast) + +local addr6 = luci.ip.new("fd9b:62b3:9cc5:0:221:63ff:fe75:aa17/64") +print(addr6:maxhost()) -- "fd9b:62b3:9cc5:0:ffff:ffff:ffff:ffff"` +]] + +---[[ +Convert CIDR instance into string representation. + +If the prefix size of instance is less than 32 for IPv4 or 128 for IPv6, the +address is returned in the form "address/prefix" otherwise just "address". + +It is usually not required to call this function directly as CIDR objects +define it as __tostring function in the associated metatable. + +@class function +@sort 21 +@name cidr.string +@return Returns a string representing the range or address of this CIDR instance +]] |