From: Jo-Philipp Wich Date: Tue, 1 Sep 2015 10:19:27 +0000 (+0200) Subject: Add generated documentation to repository X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=2e6118888156b66d8a84e6487de12d5ba88a6a6e;p=oweals%2Fluci.git Add generated documentation to repository Signed-off-by: Jo-Philipp Wich --- diff --git a/doc/index.html b/doc/index.html new file mode 100644 index 000000000..b6ea1cb5d --- /dev/null +++ b/doc/index.html @@ -0,0 +1,363 @@ + + + + Reference + + + + + +
+ +
+ +
+
+
+ +
+ + + +
+ + + +

Modules

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
luci.dispatcher
luci.http.protocol
luci.http.protocol.conditionals
luci.http.protocol.date
luci.http.protocol.mime
luci.i18n
luci.ip + LuCI IP calculation and netlink access library.
luci.ip.cidr + IP CIDR Object.
luci.jsonc + LuCI JSON parsing and serialization library.
luci.jsonc.parser + LuCI JSON parser instance.
luci.sys.init + +LuCI system utilities / init related functions.
luci.sys.iptparser
luci.sys.net + +LuCI system utilities / network related functions.
luci.sys.process + +LuCI system utilities / process related functions.
luci.sys.user + +LuCI system utilities / user related functions.
luci.sys.wifi + +LuCI system utilities / wifi related functions.
nixio + General POSIX IO library.
nixio.CHANGELOG + Changes and improvements.
nixio.CryptoHash + Cryptographical Hash and HMAC object.
nixio.File + Large File Object.
nixio.README + General Information.
nixio.Socket + Socket Object.
nixio.TLSContext + Transport Layer Security Context Object.
nixio.TLSSocket + TLS Socket Object.
nixio.UnifiedIO + Unified high-level I/O utility API for Files, Sockets and TLS-Sockets.
nixio.bin + Binary operations and conversion.
nixio.bit + Bitfield operators and mainpulation functions.
nixio.crypto + Cryptographical library.
nixio.fs + Low-level and high-level filesystem manipulation library.
+ + + + + + +
+ +
+ +
+

Valid XHTML 1.0!

+
+ +
+ + diff --git a/doc/luadoc.css b/doc/luadoc.css new file mode 100644 index 000000000..f9f974951 --- /dev/null +++ b/doc/luadoc.css @@ -0,0 +1,285 @@ +body { + margin-left: 1em; + margin-right: 1em; + font-family: arial, helvetica, geneva, sans-serif; + background-color:#ffffff; margin:0px; +} + +code { + font-family: "Andale Mono", monospace; +} + +tt { + font-family: "Andale Mono", monospace; +} + +body, td, th { font-size: 11pt; } + +h1, h2, h3, h4 { margin-left: 0em; } + +textarea, pre, tt { font-size:10pt; } +body, td, th { color:#000000; } +small { font-size:0.85em; } +h1 { font-size:1.5em; } +h2 { font-size:1.25em; } +h3 { font-size:1.15em; } +h4 { font-size:1.06em; } + +a:link { font-weight:bold; color: #004080; text-decoration: none; } +a:visited { font-weight:bold; color: #006699; text-decoration: none; } +a:link:hover { text-decoration:underline; } +hr { color:#cccccc } +img { border-width: 0px; } + + +h3 { padding: 1em 0 0.5em; } + +p { margin-left: 1em; } + +p.name { + font-family: "Andale Mono", monospace; + padding-top: 1em; + margin-left: 0em; +} + +blockquote { margin-left: 3em; } + +pre.example { + background-color: rgb(245, 245, 245); + border-top-width: 1px; + border-right-width: 1px; + border-bottom-width: 1px; + border-left-width: 1px; + border-top-style: solid; + border-right-style: solid; + border-bottom-style: solid; + border-left-style: solid; + border-top-color: silver; + border-right-color: silver; + border-bottom-color: silver; + border-left-color: silver; + padding: 1em; + margin-left: 1em; + margin-right: 1em; + font-family: "Andale Mono", monospace; + font-size: smaller; +} + + +hr { + margin-left: 0em; + background: #00007f; + border: 0px; + height: 1px; +} + +ul { list-style-type: disc; } + +table.index { border: 1px #00007f; } +table.index td { text-align: left; vertical-align: top; } +table.index ul { padding-top: 0em; margin-top: 0em; } + +table { + border: 1px solid black; + border-collapse: collapse; + margin: 1em auto; +} +th { + border: 1px solid black; + padding: 0.5em; +} +td { + border: 1px solid black; + padding: 0.5em; +} +div.header, div.footer { margin-left: 0em; } + +#container +{ + margin-left: 1em; + margin-right: 1em; + background-color: #f0f0f0; +} + +#product +{ + text-align: center; + border-bottom: 1px solid #cccccc; + background-color: #ffffff; +} + +#product big { + font-size: 2em; +} + +#product_logo +{ +} + +#product_name +{ +} + +#product_description +{ +} + +#main +{ + background-color: #f0f0f0; + border-left: 2px solid #cccccc; +} + +#navigation +{ + float: left; + width: 18em; + margin: 0; + vertical-align: top; + background-color: #f0f0f0; + overflow:visible; +} + +#navigation h1 { + background-color:#e7e7e7; + font-size:1.1em; + color:#000000; + text-align:left; + margin:0px; + padding:0.2em; + border-top:1px solid #dddddd; + border-bottom:1px solid #dddddd; +} + +#navigation ul +{ + font-size:1em; + list-style-type: none; + padding: 0; + margin: 1px; +} + +#navigation li +{ + text-indent: -1em; + margin: 0em 0em 0em 0.5em; + display: block; + padding: 3px 0px 0px 12px; +} + +#navigation li li a +{ + padding: 0px 3px 0px -1em; +} + +#content +{ + margin-left: 18em; + padding: 1em; + border-left: 2px solid #cccccc; + border-right: 2px solid #cccccc; + background-color: #ffffff; +} + +#about +{ + clear: both; + margin: 0; + padding: 5px; + border-top: 2px solid #cccccc; + background-color: #ffffff; +} + +@media print { + body { + font: 12pt "Times New Roman", "TimeNR", Times, serif; + } + a { font-weight:bold; color: #004080; text-decoration: underline; } + + #main { background-color: #ffffff; border-left: 0px; } + #container { margin-left: 2%; margin-right: 2%; background-color: #ffffff; } + + #content { margin-left: 0px; padding: 1em; border-left: 0px; border-right: 0px; background-color: #ffffff; } + + #navigation { display: none; + } + pre.example { + font-family: "Andale Mono", monospace; + font-size: 10pt; + page-break-inside: avoid; + } +} + +table.module_list td +{ + border-width: 1px; + padding: 3px; + border-style: solid; + border-color: #cccccc; +} +table.module_list td.name { background-color: #f0f0f0; } +table.module_list td.summary { width: 100%; } + +table.file_list +{ + border-width: 1px; + border-style: solid; + border-color: #cccccc; + border-collapse: collapse; +} +table.file_list td +{ + border-width: 1px; + padding: 3px; + border-style: solid; + border-color: #cccccc; +} +table.file_list td.name { background-color: #f0f0f0; } +table.file_list td.summary { width: 100%; } + + +table.function_list +{ + border-width: 1px; + border-style: solid; + border-color: #cccccc; + border-collapse: collapse; +} +table.function_list td +{ + border-width: 1px; + padding: 3px; + border-style: solid; + border-color: #cccccc; +} +table.function_list td.name { background-color: #f0f0f0; } +table.function_list td.summary { width: 100%; } + + +table.table_list +{ + border-width: 1px; + border-style: solid; + border-color: #cccccc; + border-collapse: collapse; +} +table.table_list td +{ + border-width: 1px; + padding: 3px; + border-style: solid; + border-color: #cccccc; +} +table.table_list td.name { background-color: #f0f0f0; } +table.table_list td.summary { width: 100%; } + +dl.function dt {border-top: 1px solid #ccc; padding-top: 1em;} +dl.function dd {padding: 0.5em 0;} +dl.function h3 {margin: 0; font-size: medium;} + +dl.table dt {border-top: 1px solid #ccc; padding-top: 1em;} +dl.table dd {padding-bottom: 1em;} +dl.table h3 {padding: 0; margin: 0; font-size: medium;} + +#TODO: make module_list, file_list, function_list, table_list inherit from a list + diff --git a/doc/modules/luci.dispatcher.html b/doc/modules/luci.dispatcher.html new file mode 100644 index 000000000..63abb9735 --- /dev/null +++ b/doc/modules/luci.dispatcher.html @@ -0,0 +1,1119 @@ + + + + Reference + + + + + +
+ +
+ +
+
+
+ +
+ + + +
+ +

Class luci.dispatcher

+ +

+ + + + + + + +

Functions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
_ () + +No-op function used to mark translation entries for menu labels.
alias (...) + +Create a redirect to another dispatching node.
arcombine (trg1, trg2) + +Create a combined dispatching target for non argv and argv requests.
assign (path, clone, title, order) + +Clone a node of the dispatching tree to another position.
build_url (...) + +Build the URL relative to the server webroot from given virtual path.
call (name, ...) + +Create a function-call dispatching target.
cbi (model) + +Create a CBI model dispatching target.
createindex () + +Generate the dispatching index using the native file-cache based strategy.
createtree () + +Create the dispatching tree from the index.
dispatch (request) + +Dispatches a LuCI virtual path.
entry (path, target, title, order) + +Create a new dispatching node and define common parameters.
error404 (message) + +Send a 404 error code and render the "error404" template if available.
error500 (message) + +Send a 500 error code and render the "error500" template if available.
firstchild () + +Alias the first (lowest order) page automatically + +
form (model) + +Create a CBI form model dispatching target.
get (...) + +Fetch or create a dispatching node without setting the target module or + +enabling the node.
httpdispatch (request) + +Dispatch an HTTP request.
modifier (func, order) + +Register a tree modifier.
node (...) + +Fetch or create a new dispatching node.
node_childs (node) + +Return a sorted table of visible childs within a given node +
node_visible (node) + +Check whether a dispatch node shall be visible +
rewrite (n, ...) + +Rewrite the first x path values of the request.
template (name) + +Create a template render dispatching target.
translate (text) + +Access the luci.i18n translate() api.
+ + + + + + +
+
+ + +

Functions

+
+ + + +
_ ()
+
+ + +No-op function used to mark translation entries for menu labels. + +This function does not actually translate the given argument but +is used by build/i18n-scan.pl to find translatable entries. + + + + + + + + + + +
+ + + + +
alias (...)
+
+ + +Create a redirect to another dispatching node. + + + +

Parameters

+
    + +
  • + ...: Virtual path destination +
    • + +
+ + + + + + + + +
+ + + + +
arcombine (trg1, trg2)
+
+ + +Create a combined dispatching target for non argv and argv requests. + + + +

Parameters

+
    + +
  • + trg1: Overview Target +
    • + +
  • + trg2: Detail Target +
    • + +
+ + + + + + + + +
+ + + + +
assign (path, clone, title, order)
+
+ + +Clone a node of the dispatching tree to another position. + + + +

Parameters

+
    + +
  • + path: Virtual path destination +
    • + +
  • + clone: Virtual path source +
    • + +
  • + title: Destination node title (optional) +
    • + +
  • + order: Destination node order value (optional) +
    • + +
+ + + + + + +

Return value:

+Dispatching tree node + + + +
+ + + + +
build_url (...)
+
+ + +Build the URL relative to the server webroot from given virtual path. + + + +

Parameters

+
    + +
  • + ...: Virtual path +
    • + +
+ + + + + + +

Return value:

+Relative URL + + + +
+ + + + +
call (name, ...)
+
+ + +Create a function-call dispatching target. + + + +

Parameters

+
    + +
  • + name: Target function of local controller +
    • + +
  • + ...: Additional parameters passed to the function +
    • + +
+ + + + + + + + +
+ + + + +
cbi (model)
+
+ + +Create a CBI model dispatching target. + + + +

Parameters

+
    + +
  • + model: CBI model to be rendered +
    • + +
+ + + + + + + + +
+ + + + +
createindex ()
+
+ + +Generate the dispatching index using the native file-cache based strategy. + + + + + + + + + + + +
+ + + + +
createtree ()
+
+ + +Create the dispatching tree from the index. + +Build the index before if it does not exist yet. + + + + + + + + + + +
+ + + + +
dispatch (request)
+
+ + +Dispatches a LuCI virtual path. + + + +

Parameters

+
    + +
  • + request: Virtual path +
    • + +
+ + + + + + + + +
+ + + + +
entry (path, target, title, order)
+
+ + +Create a new dispatching node and define common parameters. + + + +

Parameters

+
    + +
  • + path: Virtual path +
    • + +
  • + target: Target function to call when dispatched. +
    • + +
  • + title: Destination node title +
    • + +
  • + order: Destination node order value (optional) +
    • + +
+ + + + + + +

Return value:

+Dispatching tree node + + + +
+ + + + +
error404 (message)
+
+ + +Send a 404 error code and render the "error404" template if available. + + + +

Parameters

+
    + +
  • + message: Custom error message (optional) +
    • + +
+ + + + + + +

Return value:

+false + + + +
+ + + + +
error500 (message)
+
+ + +Send a 500 error code and render the "error500" template if available. + + + +

Parameters

+
    + +
  • + message: Custom error message (optional)# +
    • + +
+ + + + + + +

Return value:

+false + + + +
+ + + + +
firstchild ()
+
+ + +Alias the first (lowest order) page automatically + + + + + + + + + + + +
+ + + + +
form (model)
+
+ + +Create a CBI form model dispatching target. + + + +

Parameters

+
    + +
  • + model: CBI form model tpo be rendered +
    • + +
+ + + + + + + + +
+ + + + +
get (...)
+
+ + +Fetch or create a dispatching node without setting the target module or + +enabling the node. + + +

Parameters

+
    + +
  • + ...: Virtual path +
    • + +
+ + + + + + +

Return value:

+Dispatching tree node + + + +
+ + + + +
httpdispatch (request)
+
+ + +Dispatch an HTTP request. + + + +

Parameters

+
    + +
  • + request: LuCI HTTP Request object +
    • + +
+ + + + + + + + +
+ + + + +
modifier (func, order)
+
+ + +Register a tree modifier. + + + +

Parameters

+
    + +
  • + func: Modifier function +
    • + +
  • + order: Modifier order value (optional) +
    • + +
+ + + + + + + + +
+ + + + +
node (...)
+
+ + +Fetch or create a new dispatching node. + + + +

Parameters

+
    + +
  • + ...: Virtual path +
    • + +
+ + + + + + +

Return value:

+Dispatching tree node + + + +
+ + + + +
node_childs (node)
+
+ + +Return a sorted table of visible childs within a given node + + + +

Parameters

+
    + +
  • + node: Dispatch node +
    • + +
+ + + + + + +

Return value:

+Ordered table of child node names + + + +
+ + + + +
node_visible (node)
+
+ + +Check whether a dispatch node shall be visible + + + +

Parameters

+
    + +
  • + node: Dispatch node +
    • + +
+ + + + + + +

Return value:

+Boolean indicating whether the node should be visible + + + +
+ + + + +
rewrite (n, ...)
+
+ + +Rewrite the first x path values of the request. + + + +

Parameters

+
    + +
  • + n: Number of path values to replace +
    • + +
  • + ...: Virtual path to replace removed path values with +
    • + +
+ + + + + + + + +
+ + + + +
template (name)
+
+ + +Create a template render dispatching target. + + + +

Parameters

+
    + +
  • + name: Template to be rendered +
    • + +
+ + + + + + + + +
+ + + + +
translate (text)
+
+ + +Access the luci.i18n translate() api. + + + +

Parameters

+
    + +
  • + text: Text to translate +
    • + +
+ + + + + + + + +
+ + +
+ + + + + +
+ +
+ +
+

Valid XHTML 1.0!

+
+ +
+ + diff --git a/doc/modules/luci.http.protocol.conditionals.html b/doc/modules/luci.http.protocol.conditionals.html new file mode 100644 index 000000000..e216a47df --- /dev/null +++ b/doc/modules/luci.http.protocol.conditionals.html @@ -0,0 +1,524 @@ + + + + Reference + + + + + +
+ +
+ +
+
+
+ +
+ + + +
+ +

Class luci.http.protocol.conditionals

+ +

+ + + + + + + +

Functions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
if_match (req, stat) + +14.24 / If-Match + +Test whether the given message object contains an "If-Match" header and +compare it against the given stat object.
if_modified_since (req, stat) + +14.25 / If-Modified-Since + +Test whether the given message object contains an "If-Modified-Since" header +and compare it against the given stat object.
if_none_match (req, stat) + +14.26 / If-None-Match + +Test whether the given message object contains an "If-None-Match" header and +compare it against the given stat object.
if_range (req, stat) + +14.27 / If-Range + +The If-Range header is currently not implemented due to the lack of general +byte range stuff in luci.http.protocol .
if_unmodified_since (req, stat) + +14.28 / If-Unmodified-Since + +Test whether the given message object contains an "If-Unmodified-Since" +header and compare it against the given stat object.
mk_etag (stat) + +Implement 14.19 / ETag.
+ + + + + + +
+
+ + +

Functions

+
+ + + +
if_match (req, stat)
+
+ + +14.24 / If-Match + +Test whether the given message object contains an "If-Match" header and +compare it against the given stat object. + + +

Parameters

+
    + +
  • + req: HTTP request message object +
    • + +
  • + stat: A file.stat object +
    • + +
+ + + + + + +

Return values:

+
    + +
  1. Boolean indicating whether the precondition is ok + +
  2. Alternative status code if the precondition failed + +
+ + + +
+ + + + +
if_modified_since (req, stat)
+
+ + +14.25 / If-Modified-Since + +Test whether the given message object contains an "If-Modified-Since" header +and compare it against the given stat object. + + +

Parameters

+
    + +
  • + req: HTTP request message object +
    • + +
  • + stat: A file.stat object +
    • + +
+ + + + + + +

Return values:

+
    + +
  1. Boolean indicating whether the precondition is ok + +
  2. Alternative status code if the precondition failed + +
  3. Table containing extra HTTP headers if the precondition failed + +
+ + + +
+ + + + +
if_none_match (req, stat)
+
+ + +14.26 / If-None-Match + +Test whether the given message object contains an "If-None-Match" header and +compare it against the given stat object. + + +

Parameters

+
    + +
  • + req: HTTP request message object +
    • + +
  • + stat: A file.stat object +
    • + +
+ + + + + + +

Return values:

+
    + +
  1. Boolean indicating whether the precondition is ok + +
  2. Alternative status code if the precondition failed + +
  3. Table containing extra HTTP headers if the precondition failed + +
+ + + +
+ + + + +
if_range (req, stat)
+
+ + +14.27 / If-Range + +The If-Range header is currently not implemented due to the lack of general +byte range stuff in luci.http.protocol . This function will always return +false, 412 to indicate a failed precondition. + + +

Parameters

+
    + +
  • + req: HTTP request message object +
    • + +
  • + stat: A file.stat object +
    • + +
+ + + + + + +

Return values:

+
    + +
  1. Boolean indicating whether the precondition is ok + +
  2. Alternative status code if the precondition failed + +
+ + + +
+ + + + +
if_unmodified_since (req, stat)
+
+ + +14.28 / If-Unmodified-Since + +Test whether the given message object contains an "If-Unmodified-Since" +header and compare it against the given stat object. + + +

Parameters

+
    + +
  • + req: HTTP request message object +
    • + +
  • + stat: A file.stat object +
    • + +
+ + + + + + +

Return values:

+
    + +
  1. Boolean indicating whether the precondition is ok + +
  2. Alternative status code if the precondition failed + +
+ + + +
+ + + + +
mk_etag (stat)
+
+ + +Implement 14.19 / ETag. + + + +

Parameters

+
    + +
  • + stat: A file.stat structure +
    • + +
+ + + + + + +

Return value:

+String containing the generated tag suitable for ETag headers + + + +
+ + +
+ + + + + +
+ +
+ +
+

Valid XHTML 1.0!

+
+ +
+ + diff --git a/doc/modules/luci.http.protocol.date.html b/doc/modules/luci.http.protocol.date.html new file mode 100644 index 000000000..57c7eede5 --- /dev/null +++ b/doc/modules/luci.http.protocol.date.html @@ -0,0 +1,378 @@ + + + + Reference + + + + + +
+ +
+ +
+
+
+ +
+ + + +
+ +

Class luci.http.protocol.date

+ +

+ + + + + + + +

Functions

+ + + + + + + + + + + + + + + + + + + + + + +
compare (d1, d2) + +Compare two dates which can either be unix epoch times or HTTP date strings.
to_http (time) + +Convert the given unix epoch time to valid HTTP date string.
to_unix (data) + +Parse given HTTP date string and convert it to unix epoch time.
tz_offset (tz) + +Return the time offset in seconds between the UTC and given time zone.
+ + + + + + +
+
+ + +

Functions

+
+ + + +
compare (d1, d2)
+
+ + +Compare two dates which can either be unix epoch times or HTTP date strings. + + + +

Parameters

+
    + +
  • + d1: The first date or epoch time to compare +
    • + +
  • + d2: The first date or epoch time to compare +
    • + +
+ + + + + + +

Return values:

+
    + +
  1. -1 - if d1 is lower then d2 + +
  2. 0 - if both dates are equal + +
  3. 1 - if d1 is higher then d2 + +
+ + + +
+ + + + +
to_http (time)
+
+ + +Convert the given unix epoch time to valid HTTP date string. + + + +

Parameters

+
    + +
  • + time: Unix epoch time +
    • + +
+ + + + + + +

Return value:

+String containing the formatted date + + + +
+ + + + +
to_unix (data)
+
+ + +Parse given HTTP date string and convert it to unix epoch time. + + + +

Parameters

+
    + +
  • + data: String containing the date +
    • + +
+ + + + + + +

Return value:

+Unix epoch time + + + +
+ + + + +
tz_offset (tz)
+
+ + +Return the time offset in seconds between the UTC and given time zone. + + + +

Parameters

+
    + +
  • + tz: Symbolic or numeric timezone specifier +
    • + +
+ + + + + + +

Return value:

+Time offset to UTC in seconds + + + +
+ + +
+ + + + + +
+ +
+ +
+

Valid XHTML 1.0!

+
+ +
+ + diff --git a/doc/modules/luci.http.protocol.html b/doc/modules/luci.http.protocol.html new file mode 100644 index 000000000..b443ef58b --- /dev/null +++ b/doc/modules/luci.http.protocol.html @@ -0,0 +1,721 @@ + + + + Reference + + + + + +
+ +
+ +
+
+
+ +
+ + + +
+ +

Class luci.http.protocol

+ +

+ + + + + + + +

Functions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
header_source (sock) + +Creates a ltn12 source from the given socket.
mimedecode_message_body (src, msg, filecb) + +Decode a mime encoded http message body with multipart/form-data + +Content-Type.
parse_message_body (src, msg, filecb) + +Try to extract and decode a http message body from the given ltn12 source.
parse_message_header (src) + +Try to extract an http message header including information like protocol + +version, message headers and resulting CGI environment variables from the +given ltn12 source.
urldecode (str, no_plus) + +Decode an urlencoded string - optionally without decoding + +the "+" sign to " " - and return the decoded string.
urldecode_message_body (src, msg) + +Decode an urlencoded http message body with application/x-www-urlencoded + +Content-Type.
urldecode_params (url, tbl) + +Extract and split urlencoded data pairs, separated bei either "&" or ";" + +from given url or string.
urlencode (str) + +Encode given string to x-www-urlencoded format.
urlencode_params (tbl) + +Encode each key-value-pair in given table to x-www-urlencoded format, + +separated by "&".
+ + + + + + +
+
+ + +

Functions

+
+ + + +
header_source (sock)
+
+ + +Creates a ltn12 source from the given socket. The source will return it's + +data line by line with the trailing \r\n stripped of. + + +

Parameters

+
    + +
  • + sock: Readable network socket +
    • + +
+ + + + + + +

Return value:

+Ltn12 source function + + + +
+ + + + +
mimedecode_message_body (src, msg, filecb)
+
+ + +Decode a mime encoded http message body with multipart/form-data + +Content-Type. Stores all extracted data associated with its parameter name +in the params table withing the given message object. Multiple parameter +values are stored as tables, ordinary ones as strings. +If an optional file callback function is given then it is feeded with the +file contents chunk by chunk and only the extracted file name is stored +within the params table. The callback function will be called subsequently +with three arguments: + o Table containing decoded (name, file) and raw (headers) mime header data + o String value containing a chunk of the file data + o Boolean which indicates wheather the current chunk is the last one (eof) + + +

Parameters

+
    + +
  • + src: Ltn12 source function +
    • + +
  • + msg: HTTP message object +
    • + +
  • + filecb: File callback function (optional) +
    • + +
+ + + + + + +

Return values:

+
    + +
  1. Value indicating successful operation (not nil means "ok") + +
  2. String containing the error if unsuccessful + +
+ + + +

See also:

+ + +
+ + + + +
parse_message_body (src, msg, filecb)
+
+ + +Try to extract and decode a http message body from the given ltn12 source. + +This function will examine the Content-Type within the given message object +to select the appropriate content decoder. +Currently the application/x-www-urlencoded and application/form-data +mime types are supported. If the encountered content encoding can't be +handled then the whole message body will be stored unaltered as "content" +property within the given message object. + + +

Parameters

+
    + +
  • + src: Ltn12 source function +
    • + +
  • + msg: HTTP message object +
    • + +
  • + filecb: File data callback (optional, see mimedecode_message_body()) +
    • + +
+ + + + + + +

Return values:

+
    + +
  1. Value indicating successful operation (not nil means "ok") + +
  2. String containing the error if unsuccessful + +
+ + + +

See also:

+ + +
+ + + + +
parse_message_header (src)
+
+ + +Try to extract an http message header including information like protocol + +version, message headers and resulting CGI environment variables from the +given ltn12 source. + + +

Parameters

+
    + +
  • + src: Ltn12 source function +
    • + +
+ + + + + + +

Return value:

+HTTP message object + + + +

See also:

+ + +
+ + + + +
urldecode (str, no_plus)
+
+ + +Decode an urlencoded string - optionally without decoding + +the "+" sign to " " - and return the decoded string. + + +

Parameters

+
    + +
  • + str: Input string in x-www-urlencoded format +
    • + +
  • + no_plus: Don't decode "+" signs to spaces +
    • + +
+ + + + + + +

Return value:

+The decoded string + + + +

See also:

+ + +
+ + + + +
urldecode_message_body (src, msg)
+
+ + +Decode an urlencoded http message body with application/x-www-urlencoded + +Content-Type. Stores all extracted data associated with its parameter name +in the params table withing the given message object. Multiple parameter +values are stored as tables, ordinary ones as strings. + + +

Parameters

+
    + +
  • + src: Ltn12 source function +
    • + +
  • + msg: HTTP message object +
    • + +
+ + + + + + +

Return values:

+
    + +
  1. Value indicating successful operation (not nil means "ok") + +
  2. String containing the error if unsuccessful + +
+ + + +

See also:

+ + +
+ + + + +
urldecode_params (url, tbl)
+
+ + +Extract and split urlencoded data pairs, separated bei either "&" or ";" + +from given url or string. Returns a table with urldecoded values. +Simple parameters are stored as string values associated with the parameter +name within the table. Parameters with multiple values are stored as array +containing the corresponding values. + + +

Parameters

+
    + +
  • + url: The url or string which contains x-www-urlencoded form data +
    • + +
  • + tbl: Use the given table for storing values (optional) +
    • + +
+ + + + + + +

Return value:

+Table containing the urldecoded parameters + + + +

See also:

+ + +
+ + + + +
urlencode (str)
+
+ + +Encode given string to x-www-urlencoded format. + + + +

Parameters

+
    + +
  • + str: String to encode +
    • + +
+ + + + + + +

Return value:

+String containing the encoded data + + + +

See also:

+ + +
+ + + + +
urlencode_params (tbl)
+
+ + +Encode each key-value-pair in given table to x-www-urlencoded format, + +separated by "&". Tables are encoded as parameters with multiple values by +repeating the parameter name with each value. + + +

Parameters

+
    + +
  • + tbl: Table with the values +
    • + +
+ + + + + + +

Return value:

+String containing encoded values + + + +

See also:

+ + +
+ + +
+ + + + + +
+ +
+ +
+

Valid XHTML 1.0!

+
+ +
+ + diff --git a/doc/modules/luci.http.protocol.mime.html b/doc/modules/luci.http.protocol.mime.html new file mode 100644 index 000000000..96b594d2d --- /dev/null +++ b/doc/modules/luci.http.protocol.mime.html @@ -0,0 +1,294 @@ + + + + Reference + + + + + +
+ +
+ +
+
+
+ +
+ + + +
+ +

Class luci.http.protocol.mime

+ +

+ + + + + + + +

Functions

+ + + + + + + + + + + + +
to_ext (mimetype) + +Return corresponding extension for a given mime type or nil if the + +given mime-type is unknown.
to_mime (filename) + +Extract extension from a filename and return corresponding mime-type or + +"application/octet-stream" if the extension is unknown.
+ + + + + + +
+
+ + +

Functions

+
+ + + +
to_ext (mimetype)
+
+ + +Return corresponding extension for a given mime type or nil if the + +given mime-type is unknown. + + +

Parameters

+
    + +
  • + mimetype: The mimetype to retrieve the extension from +
    • + +
+ + + + + + +

Return value:

+String with the extension or nil for unknown type + + + +
+ + + + +
to_mime (filename)
+
+ + +Extract extension from a filename and return corresponding mime-type or + +"application/octet-stream" if the extension is unknown. + + +

Parameters

+
    + +
  • + filename: The filename for which the mime type is guessed +
    • + +
+ + + + + + +

Return value:

+String containign the determined mime type + + + +
+ + +
+ + + + + +
+ +
+ +
+

Valid XHTML 1.0!

+
+ +
+ + diff --git a/doc/modules/luci.i18n.html b/doc/modules/luci.i18n.html new file mode 100644 index 000000000..2db6e168f --- /dev/null +++ b/doc/modules/luci.i18n.html @@ -0,0 +1,532 @@ + + + + Reference + + + + + +
+ +
+ +
+
+
+ +
+ + + +
+ +

Class luci.i18n

+ +

+ + + + + + + +

Functions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
clear () + +Clear the translation table.
load (file, lang, force) + +Load a translation and copy its data into the translation table.
loadc (file, force) + +Load a translation file using the default translation language.
setlanguage (lang) + +Set the context default translation language.
string (key) + +Return the translated value for a specific translation key + +and ensure that the returned value is a Lua string value.
stringf (key, ...) + +Return the translated value for a specific translation key and use it as sprintf pattern.
translate (key) + +Return the translated value for a specific translation key.
translatef (key, ...) + +Return the translated value for a specific translation key and use it as sprintf pattern.
+ + + + + + +
+
+ + +

Functions

+
+ + + +
clear ()
+
+ + +Clear the translation table. + + + + + + + + + + + +
+ + + + +
load (file, lang, force)
+
+ + +Load a translation and copy its data into the translation table. + + + +

Parameters

+
    + +
  • + file: Language file +
    • + +
  • + lang: Two-letter language code +
    • + +
  • + force: Force reload even if already loaded (optional) +
    • + +
+ + + + + + +

Return value:

+Success status + + + +
+ + + + +
loadc (file, force)
+
+ + +Load a translation file using the default translation language. + +Alternatively load the translation of the fallback language. + + +

Parameters

+
    + +
  • + file: Language file +
    • + +
  • + force: Force reload even if already loaded (optional) +
    • + +
+ + + + + + + + +
+ + + + +
setlanguage (lang)
+
+ + +Set the context default translation language. + + + +

Parameters

+
    + +
  • + lang: Two-letter language code +
    • + +
+ + + + + + + + +
+ + + + +
string (key)
+
+ + +Return the translated value for a specific translation key + +and ensure that the returned value is a Lua string value. +This is the same as calling tostring(translate(...)) + + +

Parameters

+
    + +
  • + key: Default translation text +
    • + +
+ + + + + + +

Return value:

+Translated string + + + +
+ + + + +
stringf (key, ...)
+
+ + +Return the translated value for a specific translation key and use it as sprintf pattern. + +Ensure that the returned value is a Lua string value. +This is the same as calling tostring(translatef(...)) + + +

Parameters

+
    + +
  • + key: Default translation text +
    • + +
  • + ...: Format parameters +
    • + +
+ + + + + + +

Return value:

+Translated and formatted string + + + +
+ + + + +
translate (key)
+
+ + +Return the translated value for a specific translation key. + + + +

Parameters

+
    + +
  • + key: Default translation text +
    • + +
+ + + + + + +

Return value:

+Translated string + + + +
+ + + + +
translatef (key, ...)
+
+ + +Return the translated value for a specific translation key and use it as sprintf pattern. + + + +

Parameters

+
    + +
  • + key: Default translation text +
    • + +
  • + ...: Format parameters +
    • + +
+ + + + + + +

Return value:

+Translated and formatted string + + + +
+ + +
+ + + + + +
+ +
+ +
+

Valid XHTML 1.0!

+
+ +
+ + diff --git a/doc/modules/luci.ip.cidr.html b/doc/modules/luci.ip.cidr.html new file mode 100644 index 000000000..2bd3400b5 --- /dev/null +++ b/doc/modules/luci.ip.cidr.html @@ -0,0 +1,1237 @@ + + + + Reference + + + + + +
+ +
+ +
+
+
+ +
+ + + +
+ +

Object Instance luci.ip.cidr

+ +

+ IP CIDR Object. + Represents an IPv4 or IPv6 address range.

+ + + + + + + +

Functions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
cidr:is4 () + +Checks whether the CIDR instance is an IPv4 address range +
cidr:is4rfc1918 () + +Checks whether the CIDR instance is within the private RFC1918 address space +
cidr:is4linklocal () + +Checks whether the CIDR instance is an IPv4 link local (Zeroconf) address +
cidr:is6 () + +Checks whether the CIDR instance is an IPv6 address range +
cidr:is6linklocal () + +Checks whether the CIDR instance is an IPv6 link local address +
cidr:is6mapped4 () + +Checks whether the CIDR instance is an IPv6 mapped IPv4 address +
cidr:lower (addr) + +Checks whether this CIDR instance is lower than the given argument.
cidr:higher (addr) + +Checks whether this CIDR instance is higher than the given argument.
cidr:equal (addr) + +Checks whether this CIDR instance is equal to the given argument.
cidr:prefix (mask) + +Get or set prefix size of CIDR instance.
cidr:network (mask) + +Derive network address of CIDR instance.
cidr:host () + +Derive host address of CIDR instance.
cidr:mask (mask) + +Derive netmask of CIDR instance.
cidr:broadcast (mask) + +Derive broadcast address of CIDR instance.
cidr:mapped4 () + +Derive mapped IPv4 address of CIDR instance.
cidr:contains (addr) + +Test whether CIDR contains given range.
cidr:add (amount, inplace) + +Add given amount to CIDR instance.
cidr:sub (amount, inplace) + +Substract given amount from CIDR instance.
cidr:minhost () + +Calculate the lowest possible host address within this CIDR instance.
cidr:maxhost () + +Calculate the highest possible host address within this CIDR instance.
cidr:string () + +Convert CIDR instance into string representation.
+ + + + + + +
+
+ + +

Functions

+
+ + + +
cidr:is4 ()
+
+ + +Checks whether the CIDR instance is an IPv4 address range + + + + + + + + +

Return value:

+true if the CIDR is an IPv4 range, else false + + + +

See also:

+ + +
+ + + + +
cidr:is4rfc1918 ()
+
+ + +Checks whether the CIDR instance is within the private RFC1918 address space + + + + + + +

Usage:

+
local addr = luci.ip.new("192.168.45.2/24") 
+if addr:is4rfc1918() then 
+	print("Is a private address") 
+end
+ + + +

Return value:

+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. + + + +
+ + + + +
cidr:is4linklocal ()
+
+ + +Checks whether the CIDR instance is an IPv4 link local (Zeroconf) address + + + + + + +

Usage:

+
local addr = luci.ip.new("169.254.34.125") 
+if addr:is4linklocal() then 
+	print("Is a zeroconf address") 
+end
+ + + +

Return value:

+true if the entire range of this CIDR lies within the range + the range 169.254.0.0-169.254.255.255, else false. + + + +
+ + + + +
cidr:is6 ()
+
+ + +Checks whether the CIDR instance is an IPv6 address range + + + + + + + + +

Return value:

+true if the CIDR is an IPv6 range, else false + + + +

See also:

+ + +
+ + + + +
cidr:is6linklocal ()
+
+ + +Checks whether the CIDR instance is an IPv6 link local address + + + + + + +

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
+ + + +

Return value:

+true if the entire range of this CIDR lies within the range + the fe80::/10 range, else false. + + + +
+ + + + +
cidr:is6mapped4 ()
+
+ + +Checks whether the CIDR instance is an IPv6 mapped IPv4 address + + + + + + +

Usage:

+
local addr = luci.ip.new("::ffff:192.168.1.1") 
+if addr:is6mapped4() then 
+	print("Is a mapped IPv4 address") 
+end
+ + + +

Return value:

+true if the address is an IPv6 mapped IPv4 address in the + form ::ffff:1.2.3.4. + + + +
+ + + + +
cidr:lower (addr)
+
+ + +Checks whether this CIDR instance is lower than the given argument. +The comparisation follows these rules: +
  • An IPv4 address is always lower than an IPv6 address
    • +
  • Prefix sizes are ignored
+ + + +

Parameters

+
    + +
  • + addr: A luci.ip.cidr instance or a string convertable by + luci.ip.new() to compare against. +
    • + +
+ + + + +

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
+ + + +

Return value:

+true if this CIDR is lower than the given address, + else false. + + + +

See also:

+ + +
+ + + + +
cidr:higher (addr)
+
+ + +Checks whether this CIDR instance is higher than the given argument. +The comparisation follows these rules: +
  • An IPv4 address is always lower than an IPv6 address
    • +
  • Prefix sizes are ignored
+ + + +

Parameters

+
    + +
  • + addr: A luci.ip.cidr instance or a string convertable by + luci.ip.new() to compare against. +
    • + +
+ + + + +

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
+ + + +

Return value:

+true if this CIDR is higher than the given address, + else false. + + + +

See also:

+ + +
+ + + + +
cidr:equal (addr)
+
+ + +Checks whether this CIDR instance is equal to the given argument. + + + +

Parameters

+
    + +
  • + addr: A luci.ip.cidr instance or a string convertable by + luci.ip.new() to compare against. +
    • + +
+ + + + +

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
+ + + +

Return value:

+true if this CIDR is equal to the given address, + else false. + + + +

See also:

+ + +
+ + + + +
cidr:prefix (mask)
+
+ + +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. + + + +

Parameters

+
    + +
  • + 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) +
    • + +
+ + + + +

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
+ + + +

Return value:

+Bit count of the current prefix size + + + +
+ + + + +
cidr:network (mask)
+
+ + +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. + + + +

Parameters

+
    + +
  • + 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) +
    • + +
+ + + + +

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::"
+ + + +

Return value:

+CIDR instance representing the network address + + + +
+ + + + +
cidr:host ()
+
+ + +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. + + + + + + +

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"
+ + + +

Return value:

+CIDR instance representing the host address + + + +
+ + + + +
cidr:mask (mask)
+
+ + +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. + + + +

Parameters

+
    + +
  • + 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) +
    • + +
+ + + + +

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"
+ + + +

Return value:

+CIDR instance representing the netmask + + + +
+ + + + +
cidr:broadcast (mask)
+
+ + +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. + + + +

Parameters

+
    + +
  • + 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) +
    • + +
+ + + + +

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"
+ + + +

Return value:

+Return a new CIDR instance representing the broadcast address if this + instance is an IPv4 range, else return nothing. + + + +
+ + + + +
cidr:mapped4 ()
+
+ + +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. + + + + + + +

Usage:

+
local addr = luci.ip.new("::ffff:172.16.19.1") 
+print(addr:mapped4()) -- "172.16.19.1"
+ + + +

Return value:

+Return a new CIDR instance representing the IPv4 address if this + instance is an IPv6 mapped IPv4 address, else return nothing. + + + +
+ + + + +
cidr:contains (addr)
+
+ + +Test whether CIDR contains given range. + + + +

Parameters

+
    + +
  • + addr: A luci.ip.cidr instance or a string convertable by + luci.ip.new() to test. +
    • + +
+ + + + +

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
+ + + +

Return value:

+true if this instance fully contains the given address else + false. + + + +
+ + + + +
cidr:add (amount, inplace)
+
+ + +Add given amount to CIDR instance. If the result would overflow the maximum +address space, the result is set to the highest possible address. + + + +

Parameters

+
    + +
  • + amount: A numeric value between 0 and 0xFFFFFFFF, a + luci.ip.cidr instance or a string convertable by + luci.ip.new(). +
    • + +
  • + inplace: If true, modify this instance instead of returning + a new derived CIDR instance. +
    • + +
+ + + + +

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"
+ + + +

Return value:

+
    +
  • When adding inplace: Return true if the addition succeded + or false when the addition overflowed.
    • +
  • 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.
+ + + +
+ + + + +
cidr:sub (amount, inplace)
+
+ + +Substract given amount from CIDR instance. If the result would under, the lowest +possible address is returned. + + + +

Parameters

+
    + +
  • + amount: A numeric value between 0 and 0xFFFFFFFF, a + luci.ip.cidr instance or a string convertable by + luci.ip.new(). +
    • + +
  • + inplace: If true, modify this instance instead of returning + a new derived CIDR instance. +
    • + +
+ + + + +

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"
+ + + +

Return value:

+
    +
  • When substracting inplace: Return true if the substraction + succeded or false when the substraction underflowed.
    • +
  • 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.
+ + + +
+ + + + +
cidr:minhost ()
+
+ + +Calculate the lowest possible host address within this CIDR instance. + + + + + + +

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"
+ + + +

Return value:

+Returns a new CIDR instance representing the lowest host address + within this range. + + + +
+ + + + +
cidr:maxhost ()
+
+ + +Calculate the highest possible host address within this CIDR instance. + + + + + + +

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"
+ + + +

Return value:

+Returns a new CIDR instance representing the highest host address + within this range. + + + +
+ + + + +
cidr:string ()
+
+ + +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. + + + + + + + + +

Return value:

+Returns a string representing the range or address of this CIDR instance + + + +
+ + +
+ + + + + +
+ +
+ +
+

Valid XHTML 1.0!

+
+ +
+ + diff --git a/doc/modules/luci.ip.html b/doc/modules/luci.ip.html new file mode 100644 index 000000000..8a78da204 --- /dev/null +++ b/doc/modules/luci.ip.html @@ -0,0 +1,902 @@ + + + + Reference + + + + + +
+ +
+ +
+
+
+ +
+ + + +
+ +

Class luci.ip

+ +

+ LuCI IP calculation and netlink access library.

+ + + + + + + +

Functions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
new (address, netmask) + +Construct a new luci.ip.cidr instance and autodetect the address family.
IPv4 (address, netmask) + +Construct a new IPv4 luci.ip.cidr instance.
IPv6 (address, netmask) + +Construct a new IPv6 luci.ip.cidr instance.
route (address) + +Determine the route leading to the given destination.
routes (filter, callback) + +Fetch all routes, optionally matching the given criteria.
neighbors (filter, callback) + +Fetches entries from the IPv4 ARP and IPv6 neighbour kernel table
link (device) + +Fetch basic device information
+ + + + + + +
+
+ + +

Functions

+
+ + + +
new (address, netmask)
+
+ + +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. + + +

Parameters

+
    + +
  • + address: String containing a valid IPv4 or IPv6 address, optionally +with prefix size (CIDR notation) or netmask separated by slash. +
    • + +
  • + 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) +
    • + +
+ + + + +

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
+ + + +

Return value:

+A luci.ip.cidr object representing the given +address/mask range. + + + +

See also:

+ + +
+ + + + +
IPv4 (address, netmask)
+
+ + +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. + + +

Parameters

+
    + +
  • + address: String containing a valid IPv4, optionally with prefix size +(CIDR notation) or netmask separated by slash. +
    • + +
  • + 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) +
    • + +
+ + + + +

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
+ + + +

Return value:

+A luci.ip.cidr object representing the given IPv4 range. + + + +

See also:

+ + +
+ + + + +
IPv6 (address, netmask)
+
+ + +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. + + +

Parameters

+
    + +
  • + address: String containing a valid IPv6, optionally with prefix size +(CIDR notation) or netmask separated by slash. +
    • + +
  • + 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) +
    • + +
+ + + + +

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
+ + + +

Return value:

+A luci.ip.cidr object representing the given IPv6 range. + + + +

See also:

+ + +
+ + + + +
route (address)
+
+ + +Determine the route leading to the given destination. + + +

Parameters

+
    + +
  • + address: A luci.ip.cidr instance or a string containing +a valid IPv4 or IPv6 range as specified by luci.ip.new(). +
    • + +
+ + + + +

Usage:

+
    +
  • 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
    • +
  • Determine IPv6 upstream interface 
    rt = luci.ip.route("2001::/7") 
+if rt ~= nil then 
+	print("ipv6 upstream device is", rt.dev) 
+end
    • +
+ + + +

Return value:

+

Table containing the fields described below.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
type +

Route type with one of the following numeric values:

+ + + + + + + + + + + + + + + + + + + + + +
1RTN_UNICAST - Gateway or direct route
2RTN_LOCAL - Accept locally
3RTN_BROADCAST - + Accept locally as broadcast send as broadcast
4RTN_ANYCAST - + Accept locally as broadcast but send as unicast
5RTN_MULTICAST - Multicast route
+
familyNumber containing the route family, 4 for IPv4 or + 6 for IPv6
destDestination luci.ip.cidr instance
gwGateway luci.ip.cidr instance (optional)
fromSource address luci.ip.cidr instance (optional)
srcPreferred source luci.ip.cidr instance (optional)
devString containing the name of the outgoing interface
iifString containing the name of the incoming interface (optional)
tableNumber of the associated routing table (0..65535)
protoNumber of the associated routing protocol
scopeNumber describing the scope of the route, most commonly + 0 for global or 253 for on-link
metricNumber describing the route metric (optional)
expiresNumber of seconds the prefix is valid (IPv6 only, optional)
errorRoute destination error code (optional)
+ + + +

See also:

+ + +
+ + + + +
routes (filter, callback)
+
+ + +Fetch all routes, optionally matching the given criteria. + + +

Parameters

+
    + +
  • + filter:

    Table containing one or more of the possible filter +critera described below (optional)

    + + + + + + + + + + + + + + +
    FieldDescription
    family + Number describing the address family to return - 4 selects + IPv4 routes, 6 IPv6 ones. Any other value selects both. +
    iif + String containing the incoming route interface to match. +
    oif + String containing the outgoing route interface to match. +
    type + Numeric type to match, e.g. 1 for unicast. +
    scope + Numeric scope to match, e.g. 253 for onlink. +
    proto + Numeric protocol to match, e.g. 2 for boot. +
    table + Numeric routing table to match (0..65535). +
    gw + 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. +
    dest + String containing the destination to match. Prefix matching is performed. +
    from + String containing the source address to match. Prefix matching is performed. +
    src + String containing the preferred source address to match. + Prefix matching is performed. +
    dest_exact + String containing the destination to match. Exact matching is performed, + e.g. dest = "0.0.0.0/0" would match any IPv4 route + while dest_exact = "0.0.0.0/0" will only match the + default route. +
    from_exact + String containing the source address to match. Exact matching is performed. +
    +
    • + +
  • + callback:

    Callback function to invoke for each found route +instead of returning one table of route objects (optional)

    +
    • + +
+ + + + +

Usage:

+
    +
  • 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)
    • +
  • Find all global IPv6 prefixes on the current system: +
    luci.ip.routes({ from = "2001::/7" }, function(rt) 
+	print(rt.from) 
+end)
    • +
  • Fetch all IPv4 routes: +
    routes = luci.ip.routes({ family = 4 }) 
+for _, rt in ipairs(routes) do 
+	print(rt.dest, rt.gw, rt.dev) 
+end
    • +
+ + + +

Return value:

+If no callback function is provided, a table of routes +as specified by luci.ip.route() +is returned. If a callback function is given, it is invoked for each route +and nothing is returned. + + + +

See also:

+ + +
+ + + + +
neighbors (filter, callback)
+
+ + +Fetches entries from the IPv4 ARP and IPv6 neighbour kernel table + + +

Parameters

+
    + +
  • + filter:

    Table containing one or more of the possible filter +critera described below (optional)

    + + + + + +
    FieldDescription
    family + Number describing the address family to return - 4 selects + IPv4 ARP, 6 select IPv6 neighbour entries. Any other value + selects both. +
    dev + String containing the associated interface to match. +
    dest + 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. +
    mac + String containing MAC address to match. +
    +
    • + +
  • + callback:

    Callback function to invoke for each found neighbour +entry instead of returning one table of neighbour entries (optional)

    +
    • + +
+ + + + +

Usage:

+
    +
  • Find all ARP neighbours in the LAN: +
    luci.ip.neighbors({ dest = "192.168.0.0/16" }, function(n) 
+	print(n.dest, n.mac) 
+end)
    • +
  • 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)
    • +
+ + + +

Return value:

+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: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
familyNumber containing the neighbour entry family, 4 for IPv4 + ARP or 6 for IPv6 NDP
devString containing the associated device of the neighbour entry
destIP address luci.ip.cidr instance
macString containing the associated MAC address
routerBoolean "true" if the neighbour entry is a router (IPv6, optional)
proxyBoolean "true" if this is a proxy entry (optional)
incompleteBoolean "true" if the entry is in incomplete state (optional)
reachableBoolean "true" if the entry is in reachable state (optional)
staleBoolean "true" if the entry is stale (optional)
delayBoolean "true" if the entry is delayed (optional)
probeBoolean "true" if the entry is in probe state (optional)
failedBoolean "true" if the entry is in failed state (optional)
noarpBoolean "true" if the entry is not caused by NDP or + ARP (optional)
permanentBoolean "true" if the entry was statically configured from + userspace (optional)
+ + + +
+ + + + +
link (device)
+
+ + +Fetch basic device information + + +

Parameters

+
    + +
  • + device: String containing the network device to query +
    • + +
+ + + + +

Usage:

+
    +
  • Test whether device br-lan exists: +
    print(luci.ip.link("br-lan").name ~= nil) 
+
    • +
  • Query MAC address of eth0: +
    print(luci.ip.link("eth0").mac) 
+
    • +
+ + + +

Return value:

+If the given interface is found, a table containing the fields +described below is returned, else an empty table. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
upBoolean indicating whether the device is in IFF_RUNNING state
typeNumeric value indicating the type of the device, e.g. 1 + for ethernet.
nameString containing the name of the device
masterIf queried device is a bridge port, string containing the name of + parent bridge device (optional)
mtuNumber containing the current MTU of the device
qlenNumber containing the TX queue length of the device
macString containing the link local address of the device in + dotted hex notation
+ + + +
+ + +
+ + + + + +
+ +
+ +
+

Valid XHTML 1.0!

+
+ +
+ + diff --git a/doc/modules/luci.jsonc.html b/doc/modules/luci.jsonc.html new file mode 100644 index 000000000..3d0a9ad2b --- /dev/null +++ b/doc/modules/luci.jsonc.html @@ -0,0 +1,365 @@ + + + + Reference + + + + + +
+ +
+ +
+
+
+ +
+ + + +
+ +

Class luci.jsonc

+ +

+ LuCI JSON parsing and serialization library. + The luci.jsonc class is a high level Lua binding to the JSON-C library to + allow reading and writing JSON data with minimal overhead.

+ + + + + + + +

Functions

+ + + + + + + + + + + + + + + + + +
new () + +Construct a new luci.jsonc.parser instance.
parse (json) + +Parse a complete JSON string and convert it into a Lua data structure.
stringify (data, pretty) + +Convert given Lua data into a JSON string.
+ + + + + + +
+
+ + +

Functions

+
+ + + +
new ()
+
+ + +Construct a new luci.jsonc.parser instance. + + + + + +

Usage:

+parser = luci.jsonc.new() + + + +

Return value:

+A luci.jsonc.parser object representing a JSON-C tokener. + + + +
+ + + + +
parse (json)
+
+ + +Parse a complete JSON string and convert it into a Lua data structure. + + +

Parameters

+
    + +
  • + json: A string containing the JSON data to parse, must be either a + JSON array or a JSON object. +
    • + +
+ + + + +

Usage:

+
data = luci.jsonc.parse('{ "name": "John", "age": 34 }') 
+print(data.name)  -- "John"
+ + + +

Return value:

+On success, a table containing the parsed JSON data is returned, on + failure the function returns nil and a string containing the reason of + the parse error. + + + +

See also:

+ + +
+ + + + +
stringify (data, pretty)
+
+ + +Convert given Lua data into a JSON string. + +This function recursively converts the given Lua data into a JSON string, +ignoring any unsupported data. Lua tables are converted into JSON arrays if they +only contain integer keys, mixed tables are turned into JSON objects with any +existing numeric keys converted into strings. + +Lua functions, coroutines and userdata objects are ignored and Lua numbers are +converted to integers if they do not contain fractional values. + + + +

Parameters

+
    + +
  • + data: The Lua data to convert, can be a table, string, boolean or number. +
    • + +
  • + pretty: A boolean value indicating whether the resulting JSON should be + pretty printed. +
    • + +
+ + + + +

Usage:

+
json = luci.jsonc.stringify({ item = true, values = { 1, 2, 3 } }) 
+print(json)  -- '{"item":true,"values":[1,2,3]}'
+ + + +

Return value:

+Returns a string containing the JSON representation of the given Lua + data. + + + +

See also:

+ + +
+ + +
+ + + + + +
+ +
+ +
+

Valid XHTML 1.0!

+
+ +
+ + diff --git a/doc/modules/luci.jsonc.parser.html b/doc/modules/luci.jsonc.parser.html new file mode 100644 index 000000000..4c93a0f79 --- /dev/null +++ b/doc/modules/luci.jsonc.parser.html @@ -0,0 +1,428 @@ + + + + Reference + + + + + +
+ +
+ +
+
+
+ +
+ + + +
+ +

Object Instance luci.jsonc.parser

+ +

+ LuCI JSON parser instance. + A JSON parser instance is useful to parse JSON data chunk by chunk, without + the need to assemble all data in advance.

+ + + + + + + +

Functions

+ + + + + + + + + + + + + + + + + + + + + + +
parser:parse (json) + +Parses one chunk of JSON data.
parser:get () + +Convert parsed JSON data into Lua table.
parser:set (data) + +Put Lua data into the parser.
parser:stringify (pretty) + +Serialize current parser state as JSON.
+ + + + + + +
+
+ + +

Functions

+
+ + + +
parser:parse (json)
+
+ + +Parses one chunk of JSON data. + + + +

Parameters

+
    + +
  • + json: String containing the JSON fragment to parse +
    • + +
+ + + + +

Usage:

+
parser = luci.jsonc.new() 
+ 
+while true do 
+	chunk = ...  -- fetch a cunk of data, e.g. from a socket 
+	finish, errmsg = parser.parse(chunk) 
+ 
+	if finish == nil then 
+		error("Cannot parse JSON: " .. errmsg) 
+	end 
+ 
+	if finish == true then 
+		break 
+	end 
+end
+ + + +

Return value:

+
    +
  • true if a complete JSON object has been parsed and no further input is + expected.
    • +
  • false if further input is required
    • +
  • nil if an error was encountered while parsing the current chunk. + In this case a string describing the parse error is returned as second + value.
+ + + +

See also:

+ + +
+ + + + +
parser:get ()
+
+ + +Convert parsed JSON data into Lua table. + + + + + + +

Usage:

+
parser = luci.jsonc.new() 
+parser:parse('{ "example": "test" }') 
+ 
+data = parser:get() 
+print(data.example)  -- "test"
+ + + +

Return value:

+Parsed JSON object converted into a Lua table or nil if the parser + didn't finish or encountered an error. + + + +

See also:

+ + +
+ + + + +
parser:set (data)
+
+ + +Put Lua data into the parser. + + + +

Parameters

+
    + +
  • + data: Lua data to put into the parser object. The data is converted to an + internal JSON representation that can be dumped with stringify(). + The conversion follows the rules described in luci.jsonc.stringify. +
    • + +
+ + + + +

Usage:

+
parser = luci.jsonc.new() 
+parser:set({ "some", "data" })
+ + + +

Return value:

+Nothing is returned. + + + +

See also:

+ + +
+ + + + +
parser:stringify (pretty)
+
+ + +Serialize current parser state as JSON. + + + +

Parameters

+
    + +
  • + pretty: A boolean value indicating whether the resulting JSON should be pretty printed. +
    • + +
+ + + + +

Usage:

+
parser = luci.jsonc.new() 
+parser:parse('{ "example": "test" }') 
+print(parser:serialize())  -- '{"example":"test"}'
+ + + +

Return value:

+Returns the serialized JSON data of this parser instance. + + + +
+ + +
+ + + + + +
+ +
+ +
+

Valid XHTML 1.0!

+
+ +
+ + diff --git a/doc/modules/luci.sys.init.html b/doc/modules/luci.sys.init.html new file mode 100644 index 000000000..3e311ed8e --- /dev/null +++ b/doc/modules/luci.sys.init.html @@ -0,0 +1,484 @@ + + + + Reference + + + + + +
+ +
+ +
+
+
+ +
+ + + +
+ +

Class luci.sys.init

+ +

+ +LuCI system utilities / init related functions. +

+ + + + + + + +

Functions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
disable (name) + +Disable the given init script +
enable (name) + +Enable the given init script +
enabled (name) + +Test whether the given init script is enabled +
index (name) + +Get the index of he given init script +
names () + +Get the names of all installed init scripts +
start (name) + +Start the given init script +
stop (name) + +Stop the given init script +
+ + + + + + +
+
+ + +

Functions

+
+ + + +
disable (name)
+
+ + +Disable the given init script + + + +

Parameters

+
    + +
  • + name: Name of the init script +
    • + +
+ + + + + + +

Return value:

+Boolean indicating success + + + +
+ + + + +
enable (name)
+
+ + +Enable the given init script + + + +

Parameters

+
    + +
  • + name: Name of the init script +
    • + +
+ + + + + + +

Return value:

+Boolean indicating success + + + +
+ + + + +
enabled (name)
+
+ + +Test whether the given init script is enabled + + + +

Parameters

+
    + +
  • + name: Name of the init script +
    • + +
+ + + + + + +

Return value:

+Boolean indicating whether init is enabled + + + +
+ + + + +
index (name)
+
+ + +Get the index of he given init script + + + +

Parameters

+
    + +
  • + name: Name of the init script +
    • + +
+ + + + + + +

Return value:

+Numeric index value + + + +
+ + + + +
names ()
+
+ + +Get the names of all installed init scripts + + + + + + + + +

Return value:

+Table containing the names of all inistalled init scripts + + + +
+ + + + +
start (name)
+
+ + +Start the given init script + + + +

Parameters

+
    + +
  • + name: Name of the init script +
    • + +
+ + + + + + +

Return value:

+Boolean indicating success + + + +
+ + + + +
stop (name)
+
+ + +Stop the given init script + + + +

Parameters

+
    + +
  • + name: Name of the init script +
    • + +
+ + + + + + +

Return value:

+Boolean indicating success + + + +
+ + +
+ + + + + +
+ +
+ +
+

Valid XHTML 1.0!

+
+ +
+ + diff --git a/doc/modules/luci.sys.iptparser.html b/doc/modules/luci.sys.iptparser.html new file mode 100644 index 000000000..8055d4652 --- /dev/null +++ b/doc/modules/luci.sys.iptparser.html @@ -0,0 +1,434 @@ + + + + Reference + + + + + +
+ +
+ +
+
+
+ +
+ + + +
+ +

Object Instance luci.sys.iptparser

+ +

+ + + + + + + +

Functions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IptParser (family) + +Create a new iptables parser object.
IptParser:chain (table, chain) + +Return the given firewall chain within the given table name.
IptParser:chains (table) + +Find the names of all chains within the given table name.
IptParser:is_custom_target (target) + +Test whether the given target points to a custom chain.
IptParser:resync () + +Rebuild the internal lookup table, for example when rules have changed + +through external commands.
IptParser:tables () + +Find the names of all tables.
+ + + + + + +
+
+ + +

Functions

+
+ + + +
IptParser (family)
+
+ + +Create a new iptables parser object. + + + +

Parameters

+
    + +
  • + family: Number specifying the address family. 4 for IPv4, 6 for IPv6 +
    • + +
+ + + + + + +

Return value:

+IptParser instance + + + +
+ + + + +
IptParser:chain (table, chain)
+
+ + +Return the given firewall chain within the given table name. + + + +

Parameters

+
    + +
  • + table: String containing the table name +
    • + +
  • + chain: String containing the chain name +
    • + +
+ + + + + + +

Return value:

+Table containing the fields "policy", "packets", "bytes" + and "rules". The "rules" field is a table of rule tables. + + + +
+ + + + +
IptParser:chains (table)
+
+ + +Find the names of all chains within the given table name. + + + +

Parameters

+
    + +
  • + table: String containing the table name +
    • + +
+ + + + + + +

Return value:

+Table of chain names in the order they occur. + + + +
+ + + + +
IptParser:is_custom_target (target)
+
+ + +Test whether the given target points to a custom chain. + + + +

Parameters

+
    + +
  • + target: String containing the target action +
    • + +
+ + + + + + +

Return value:

+Boolean indicating whether target is a custom chain. + + + +
+ + + + +
IptParser:resync ()
+
+ + +Rebuild the internal lookup table, for example when rules have changed + +through external commands. + + + + + + + +

Return value:

+nothing + + + +
+ + + + +
IptParser:tables ()
+
+ + +Find the names of all tables. + + + + + + + + +

Return value:

+Table of table names. + + + +
+ + +
+ + + + + +
+ +
+ +
+

Valid XHTML 1.0!

+
+ +
+ + diff --git a/doc/modules/luci.sys.net.html b/doc/modules/luci.sys.net.html new file mode 100644 index 000000000..82fcea474 --- /dev/null +++ b/doc/modules/luci.sys.net.html @@ -0,0 +1,940 @@ + + + + Reference + + + + + +
+ +
+ +
+
+
+ +
+ + + +
+ +

Class luci.sys.net

+ +

+ +LuCI system utilities / network related functions. +

+ + + + + + + +

Functions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
call (...) + +Execute a given shell command and return the error code +
dmesg () + +Retrieves the output of the "dmesg" command.
exec (command) + +Execute a given shell command and capture its standard output +
getenv (var) + +Retrieve environment variables.
hostname (String) + +Get or set the current hostname.
httpget (url, stream, target) + +Returns the contents of a documented referred by an URL.
mounts () + +Retrieve information about currently mounted file systems.
arptable () + +Returns the current arp-table entries as two-dimensional table.
conntrack () + +Returns conntrack information +
deviceinfo () + +Return information about available network interfaces.
devices () + +Determine the names of available network interfaces.
ipv4_hints () + +Returns a two-dimensional table of IPv4 address hints.
ipv6_hints () + +Returns a two-dimensional table of IPv6 address hints.
mac_hints () + +Returns a two-dimensional table of mac address hints.
pingtest (host) + +Tests whether the given host responds to ping probes.
routes () + +Returns the current kernel routing table entries.
routes6 () + +Returns the current ipv6 kernel routing table entries.
reboot () + +Initiate a system reboot.
syslog () + +Retrieves the output of the "logread" command.
uniqueid (bytes) + +Generates a random id with specified length.
uptime () + +Returns the current system uptime stats.
+ + + + + + +
+
+ + +

Functions

+
+ + + +
call (...)
+
+ + +Execute a given shell command and return the error code + + + +

Parameters

+
    + +
  • + ...: Command to call +
    • + +
+ + + + + + +

Return value:

+Error code of the command + + + +
+ + + + +
dmesg ()
+
+ + +Retrieves the output of the "dmesg" command. + + + + + + + + +

Return value:

+String containing the current log buffer + + + +
+ + + + +
exec (command)
+
+ + +Execute a given shell command and capture its standard output + + + +

Parameters

+
    + +
  • + command: Command to call +
    • + +
+ + + + + + +

Return value:

+String containg the return the output of the command + + + +
+ + + + +
getenv (var)
+
+ + +Retrieve environment variables. If no variable is given then a table + +containing the whole environment is returned otherwise this function returns +the corresponding string value for the given name or nil if no such variable +exists. + + +

Parameters

+
    + +
  • + var: Name of the environment variable to retrieve (optional) +
    • + +
+ + + + + + +

Return values:

+
    + +
  1. String containg the value of the specified variable + +
  2. Table containing all variables if no variable name is given + +
+ + + +
+ + + + +
hostname (String)
+
+ + +Get or set the current hostname. + + + +

Parameters

+
    + +
  • + String: containing a new hostname to set (optional) +
    • + +
+ + + + + + +

Return value:

+String containing the system hostname + + + +
+ + + + +
httpget (url, stream, target)
+
+ + +Returns the contents of a documented referred by an URL. + + + +

Parameters

+
    + +
  • + url: The URL to retrieve +
    • + +
  • + stream: Return a stream instead of a buffer +
    • + +
  • + target: Directly write to target file name +
    • + +
+ + + + + + +

Return value:

+String containing the contents of given the URL + + + +
+ + + + +
mounts ()
+
+ + +Retrieve information about currently mounted file systems. + + + + + + + + +

Return value:

+Table containing mount information + + + +
+ + + + +
arptable ()
+
+ + +Returns the current arp-table entries as two-dimensional table. + + + + + + + + +

Return value:

+Table of table containing the current arp entries. + The following fields are defined for arp entry objects: + { "IP address", "HW address", "HW type", "Flags", "Mask", "Device" } + + + +
+ + + + +
conntrack ()
+
+ + +Returns conntrack information + + + + + + + + +

Return value:

+Table with the currently tracked IP connections + + + +
+ + + + +
deviceinfo ()
+
+ + +Return information about available network interfaces. + + + + + + + + +

Return value:

+Table containing all current interface names and their information + + + +
+ + + + +
devices ()
+
+ + +Determine the names of available network interfaces. + + + + + + + + +

Return value:

+Table containing all current interface names + + + +
+ + + + +
ipv4_hints ()
+
+ + +Returns a two-dimensional table of IPv4 address hints. + + + + + + + + +

Return value:

+Table of table containing known hosts from various sources. + Each entry contains the values in the following order: + [ "ip", "name" ] + + + +
+ + + + +
ipv6_hints ()
+
+ + +Returns a two-dimensional table of IPv6 address hints. + + + + + + + + +

Return value:

+Table of table containing known hosts from various sources. + Each entry contains the values in the following order: + [ "ip", "name" ] + + + +
+ + + + +
mac_hints ()
+
+ + +Returns a two-dimensional table of mac address hints. + + + + + + + + +

Return value:

+Table of table containing known hosts from various sources. + Each entry contains the values in the following order: + [ "mac", "name" ] + + + +
+ + + + +
pingtest (host)
+
+ + +Tests whether the given host responds to ping probes. + + + +

Parameters

+
    + +
  • + host: String containing a hostname or IPv4 address +
    • + +
+ + + + + + +

Return value:

+Number containing 0 on success and >= 1 on error + + + +
+ + + + +
routes ()
+
+ + +Returns the current kernel routing table entries. + + + + + + + + +

Return value:

+Table of tables with properties of the corresponding routes. + The following fields are defined for route entry tables: + { "dest", "gateway", "metric", "refcount", "usecount", "irtt", + "flags", "device" } + + + +
+ + + + +
routes6 ()
+
+ + +Returns the current ipv6 kernel routing table entries. + + + + + + + + +

Return value:

+Table of tables with properties of the corresponding routes. + The following fields are defined for route entry tables: + { "source", "dest", "nexthop", "metric", "refcount", "usecount", + "flags", "device" } + + + +
+ + + + +
reboot ()
+
+ + +Initiate a system reboot. + + + + + + + + +

Return value:

+Return value of os.execute() + + + +
+ + + + +
syslog ()
+
+ + +Retrieves the output of the "logread" command. + + + + + + + + +

Return value:

+String containing the current log buffer + + + +
+ + + + +
uniqueid (bytes)
+
+ + +Generates a random id with specified length. + + + +

Parameters

+
    + +
  • + bytes: Number of bytes for the unique id +
    • + +
+ + + + + + +

Return value:

+String containing hex encoded id + + + +
+ + + + +
uptime ()
+
+ + +Returns the current system uptime stats. + + + + + + + + +

Return value:

+String containing total uptime in seconds + + + +
+ + +
+ + + + + +
+ +
+ +
+

Valid XHTML 1.0!

+
+ +
+ + diff --git a/doc/modules/luci.sys.process.html b/doc/modules/luci.sys.process.html new file mode 100644 index 000000000..d664bca1d --- /dev/null +++ b/doc/modules/luci.sys.process.html @@ -0,0 +1,416 @@ + + + + Reference + + + + + +
+ +
+ +
+
+
+ +
+ + + +
+ +

Class luci.sys.process

+ +

+ +LuCI system utilities / process related functions. +

+ + + + + + + +

Functions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
info () + +Get the current process id.
list () + +Retrieve information about currently running processes.
setgroup (gid) + +Set the gid of a process identified by given pid.
setuser (uid) + +Set the uid of a process identified by given pid.
signal (pid, sig) + +Send a signal to a process identified by given pid.
+ + + + + + +
+
+ + +

Functions

+
+ + + +
info ()
+
+ + +Get the current process id. + + + + + + + + +

Return value:

+Number containing the current pid + + + +
+ + + + +
list ()
+
+ + +Retrieve information about currently running processes. + + + + + + + + +

Return value:

+Table containing process information + + + +
+ + + + +
setgroup (gid)
+
+ + +Set the gid of a process identified by given pid. + + + +

Parameters

+
    + +
  • + gid: Number containing the Unix group id +
    • + +
+ + + + + + +

Return values:

+
    + +
  1. Boolean indicating successful operation + +
  2. String containing the error message if failed + +
  3. Number containing the error code if failed + +
+ + + +
+ + + + +
setuser (uid)
+
+ + +Set the uid of a process identified by given pid. + + + +

Parameters

+
    + +
  • + uid: Number containing the Unix user id +
    • + +
+ + + + + + +

Return values:

+
    + +
  1. Boolean indicating successful operation + +
  2. String containing the error message if failed + +
  3. Number containing the error code if failed + +
+ + + +
+ + + + +
signal (pid, sig)
+
+ + +Send a signal to a process identified by given pid. + + + +

Parameters

+
    + +
  • + pid: Number containing the process id +
    • + +
  • + sig: Signal to send (default: 15 [SIGTERM]) +
    • + +
+ + + + + + +

Return values:

+
    + +
  1. Boolean indicating successful operation + +
  2. Number containing the error code if failed + +
+ + + +
+ + +
+ + + + + +
+ +
+ +
+

Valid XHTML 1.0!

+
+ +
+ + diff --git a/doc/modules/luci.sys.user.html b/doc/modules/luci.sys.user.html new file mode 100644 index 000000000..976dac612 --- /dev/null +++ b/doc/modules/luci.sys.user.html @@ -0,0 +1,384 @@ + + + + Reference + + + + + +
+ +
+ +
+
+
+ +
+ + + +
+ +

Class luci.sys.user

+ +

+ +LuCI system utilities / user related functions. +

+ + + + + + + +

Functions

+ + + + + + + + + + + + + + + + + + + + + + +
getuser (uid) + +Retrieve user informations for given uid.
checkpasswd (username, pass) + +Test whether given string matches the password of a given system user.
getpasswd (username) + +Retrieve the current user password hash.
setpasswd (username, password) + +Change the password of given user.
+ + + + + + +
+
+ + +

Functions

+
+ + + +
getuser (uid)
+
+ + +Retrieve user informations for given uid. + + + +

Parameters

+
    + +
  • + uid: Number containing the Unix user id +
    • + +
+ + + + + + +

Return value:

+Table containing the following fields: + { "uid", "gid", "name", "passwd", "dir", "shell", "gecos" } + + + +
+ + + + +
checkpasswd (username, pass)
+
+ + +Test whether given string matches the password of a given system user. + + + +

Parameters

+
    + +
  • + username: String containing the Unix user name +
    • + +
  • + pass: String containing the password to compare +
    • + +
+ + + + + + +

Return value:

+Boolean indicating wheather the passwords are equal + + + +
+ + + + +
getpasswd (username)
+
+ + +Retrieve the current user password hash. + + + +

Parameters

+
    + +
  • + username: String containing the username to retrieve the password for +
    • + +
+ + + + + + +

Return values:

+
    + +
  1. String containing the hash or nil if no password is set. + +
  2. Password database entry + +
+ + + +
+ + + + +
setpasswd (username, password)
+
+ + +Change the password of given user. + + + +

Parameters

+
    + +
  • + username: String containing the Unix user name +
    • + +
  • + password: String containing the password to compare +
    • + +
+ + + + + + +

Return value:

+Number containing 0 on success and >= 1 on error + + + +
+ + +
+ + + + + +
+ +
+ +
+

Valid XHTML 1.0!

+
+ +
+ + diff --git a/doc/modules/luci.sys.wifi.html b/doc/modules/luci.sys.wifi.html new file mode 100644 index 000000000..1a3a997a3 --- /dev/null +++ b/doc/modules/luci.sys.wifi.html @@ -0,0 +1,252 @@ + + + + Reference + + + + + +
+ +
+ +
+
+
+ +
+ + + +
+ +

Class luci.sys.wifi

+ +

+ +LuCI system utilities / wifi related functions. +

+ + + + + + + +

Functions

+ + + + + + + +
getiwinfo (ifname) + +Get wireless information for given interface.
+ + + + + + +
+
+ + +

Functions

+
+ + + +
getiwinfo (ifname)
+
+ + +Get wireless information for given interface. + + + +

Parameters

+
    + +
  • + ifname: String containing the interface name +
    • + +
+ + + + + + +

Return value:

+A wrapped iwinfo object instance + + + +
+ + +
+ + + + + +
+ +
+ +
+

Valid XHTML 1.0!

+
+ +
+ + diff --git a/doc/modules/nixio.CHANGELOG.html b/doc/modules/nixio.CHANGELOG.html new file mode 100644 index 000000000..a9e0dcc07 --- /dev/null +++ b/doc/modules/nixio.CHANGELOG.html @@ -0,0 +1,258 @@ + + + + Reference + + + + + +
+ +
+ +
+
+
+ +
+ + + +
+ +

Class nixio.CHANGELOG

+ +

+ Changes and improvements.

+ + + + + + + + + + +

Tables

+ + + + + + + + + + + + +
0.2 + Initial Release.
0.3 + Service Release.
+ + + +
+
+ + + + +

Tables

+
+ +
0.2
+
+ Initial Release. +
    +
  • Initial Release
    • +
+ + + +
+ + +
0.3
+
+ Service Release. +
    +
  • Added getifaddrs() function.
    • +
  • Added getsockopt(), setsockopt(), getsockname() and getpeername() + directly to TLS-socket objects unifying the socket interface.
    • +
  • Added support for CyaSSL as cryptographical backend.
    • +
  • Added support for x509 certificates in DER format.
    • +
  • Added support for splice() in UnifiedIO.copyz().
    • +
  • Added interface to inject chunks into UnifiedIO.linesource() buffer.
    • +
  • Changed TLS behaviour to explicitely separate servers and clients.
    • +
  • Fixed usage of signed datatype breaking Base64 decoding.
    • +
  • Fixed namespace clashes for nixio.fs.
    • +
  • Fixed splice() support for some exotic C libraries.
    • +
  • Reconfigure axTLS cryptographical provider and mark it as obsolete.
    • +
+ + + +
+ + +
+ + + +
+ +
+ +
+

Valid XHTML 1.0!

+
+ +
+ + diff --git a/doc/modules/nixio.CryptoHash.html b/doc/modules/nixio.CryptoHash.html new file mode 100644 index 000000000..e7f28bb5d --- /dev/null +++ b/doc/modules/nixio.CryptoHash.html @@ -0,0 +1,284 @@ + + + + Reference + + + + + +
+ +
+ +
+
+
+ +
+ + + +
+ +

Object Instance nixio.CryptoHash

+ +

+ Cryptographical Hash and HMAC object.

+ + + + + + + +

Functions

+ + + + + + + + + + + + +
CryptoHash:final () + Finalize the hash and return the digest.
CryptoHash:update (chunk) + Add another chunk of data to be hashed.
+ + + + + + +
+
+ + +

Functions

+
+ + + +
CryptoHash:final ()
+
+ + Finalize the hash and return the digest. + + + + + +

Usage:

+You cannot call update on a hash object that was already finalized + you can however call final multiple times to get the digest. + + + +

Return values:

+
    + +
  1. hexdigest + +
  2. buffer containing binary digest + +
+ + + +
+ + + + +
CryptoHash:update (chunk)
+
+ + Add another chunk of data to be hashed. + + +

Parameters

+
    + +
  • + chunk: Chunk of data +
    • + +
+ + + + + + +

Return value:

+CryptoHash object (self) + + + +
+ + +
+ + + + + +
+ +
+ +
+

Valid XHTML 1.0!

+
+ +
+ + diff --git a/doc/modules/nixio.File.html b/doc/modules/nixio.File.html new file mode 100644 index 000000000..c4f9ab866 --- /dev/null +++ b/doc/modules/nixio.File.html @@ -0,0 +1,641 @@ + + + + Reference + + + + + +
+ +
+ +
+
+
+ +
+ + + +
+ +

Object Instance nixio.File

+ +

+ Large File Object. + Large file operations are supported up to 52 bits if the Lua number type is + double (default).

+ + + + + + + +

Functions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
File:close () + Close the file descriptor.
File:fileno () + Get the number of the filedescriptor.
File:lock (command, length) + Apply or test a lock on the file.
File:read (length) + Read from a file descriptor.
File:seek (offset, whence) + Reposition read / write offset of the file descriptor.
File:setblocking (blocking) + (POSIX) Set the blocking mode of the file descriptor.
File:stat (field) + Get file status and attributes.
File:sync (data_only) + Synchronizes the file with the storage device.
File:tell () + Return the current read / write offset of the file descriptor.
File:write (buffer, offset, length) + Write to the file descriptor.
+ + + + + + +
+
+ + +

Functions

+
+ + + +
File:close ()
+
+ + Close the file descriptor. + + + + + + + +

Return value:

+true + + + +
+ + + + +
File:fileno ()
+
+ + Get the number of the filedescriptor. + + + + + + + +

Return value:

+file descriptor number + + + +
+ + + + +
File:lock (command, length)
+
+ + Apply or test a lock on the file. + + +

Parameters

+
    + +
  • + command: Locking Command ["lock", "tlock", "ulock", "test"] +
    • + +
  • + length: Amount of Bytes to lock from current offset (optional) +
    • + +
+ + + + +

Usage

+
    + +
  • This function calls lockf() on POSIX and _locking() on Windows. + +
  • The "lock" command is blocking, "tlock" is non-blocking, + "ulock" unlocks and "test" only tests for the lock. + +
  • The "test" command is not available on Windows. + +
  • Locks are by default advisory on POSIX, but mandatory on Windows. + +
+ + + +

Return value:

+true + + + +
+ + + + +
File:read (length)
+
+ + Read from a file descriptor. + + +

Parameters

+
    + +
  • + length: Amount of data to read (in Bytes). +
    • + +
+ + + + +

Usage

+
    + +
  • Warning: It is not guaranteed that all requested data + is read at once especially when dealing with pipes. + You have to check the return value - the length of the buffer actually read - + or use the safe IO functions in the high-level IO utility module. + +
  • The length of the return buffer is limited by the (compile time) + nixio buffersize which is nixio.const.buffersize (8192 by default). + Any read request greater than that will be safely truncated to this value. + +
+ + + +

Return value:

+buffer containing data successfully read + + + +
+ + + + +
File:seek (offset, whence)
+
+ + Reposition read / write offset of the file descriptor. + The seek will be done either from the beginning of the file or relative + to the current position or relative to the end. + + +

Parameters

+
    + +
  • + offset: File Offset +
    • + +
  • + whence: Starting point ["set", "cur", "end"] +
    • + +
+ + + + +

Usage:

+This function calls lseek(). + + + +

Return value:

+new (absolute) offset position + + + +
+ + + + +
File:setblocking (blocking)
+
+ + (POSIX) Set the blocking mode of the file descriptor. + + +

Parameters

+
    + +
  • + blocking: (boolean) +
    • + +
+ + + + + + +

Return value:

+true + + + +
+ + + + +
File:stat (field)
+
+ + Get file status and attributes. + + +

Parameters

+
    + +
  • + field: Only return a specific field, not the whole table (optional) +
    • + +
+ + + + +

Usage:

+This function calls fstat(). + + + +

Return value:

+Table containing:
    +
  • atime = Last access timestamp
    • +
  • blksize = Blocksize (POSIX only)
    • +
  • blocks = Blocks used (POSIX only)
    • +
  • ctime = Creation timestamp
    • +
  • dev = Device ID
    • +
  • gid = Group ID
    • +
  • ino = Inode
    • +
  • modedec = Mode converted into a decimal number
    • +
  • modestr = Mode as string as returned by ls -l
    • +
  • mtime = Last modification timestamp
    • +
  • nlink = Number of links
    • +
  • rdev = Device ID (if special file)
    • +
  • size = Size in bytes
    • +
  • type = ["reg", "dir", "chr", "blk", "fifo", "lnk", "sock"]
    • +
  • uid = User ID
    • +
+ + + +
+ + + + +
File:sync (data_only)
+
+ + Synchronizes the file with the storage device. + Returns when the file is successfully written to the disk. + + +

Parameters

+
    + +
  • + data_only: Do not synchronize the metadata. (optional, boolean) +
    • + +
+ + + + +

Usage

+
    + +
  • This function calls fsync() when data_only equals false + otherwise fdatasync(), on Windows _commit() is used instead. + +
  • fdatasync() is only supported by Linux and Solaris. For other systems + the data_only parameter is ignored and fsync() is always called. + +
+ + + +

Return value:

+true + + + +
+ + + + +
File:tell ()
+
+ + Return the current read / write offset of the file descriptor. + + + + + +

Usage:

+This function calls lseek() with offset 0 from the current position. + + + +

Return value:

+offset position + + + +
+ + + + +
File:write (buffer, offset, length)
+
+ + Write to the file descriptor. + + +

Parameters

+
    + +
  • + buffer: Buffer holding the data to be written. +
    • + +
  • + offset: Offset to start reading the buffer from. (optional) +
    • + +
  • + length: Length of chunk to read from the buffer. (optional) +
    • + +
+ + + + +

Usage

+
    + +
  • Warning: It is not guaranteed that all data + in the buffer is written at once especially when dealing with pipes. + You have to check the return value - the number of bytes actually written - + or use the safe IO functions in the high-level IO utility module. + +
  • Unlike standard Lua indexing the lowest offset and default is 0. + +
+ + + +

Return value:

+number of bytes written + + + +
+ + +
+ + + + + +
+ +
+ +
+

Valid XHTML 1.0!

+
+ +
+ + diff --git a/doc/modules/nixio.README.html b/doc/modules/nixio.README.html new file mode 100644 index 000000000..94182a0ee --- /dev/null +++ b/doc/modules/nixio.README.html @@ -0,0 +1,342 @@ + + + + Reference + + + + + +
+ +
+ +
+
+
+ +
+ + + +
+ +

Class nixio.README

+ +

+ General Information.

+ + + + + + + + + + +

Tables

+ + + + + + + + + + + + + + + + + + + + + + +
Errorhandling + General error handling information.
Functions + Function conventions.
Platforms + Platform information.
TLS-Crypto + Cryptography and TLS libraries.
+ + + +
+
+ + + + +

Tables

+
+ +
Errorhandling
+
+ General error handling information. +
    +
  • Most of the functions available in this library may fail. If any error + occurs the function returns nil or false, an error code + (usually errno) and an additional error message text (if avaialable).
    • +
  • At the moment false is only returned when a non-blocking I/O function + fails with EAGAIN, EWOULDBLOCK or WSAEWOULDBLOCK for any others nil is + returned as first parameter. Therefore you can use false to write portable + non-blocking I/O applications.
    • +
  • Note that the function documentation does only mention the return values + in case of a successful operation.
    • +
  • You can find a table of common error numbers and other useful constants + like signal numbers in nixio.const e.g. nixio.const.EINVAL, + nixio.const.SIGTERM, etc. For portability there is a second error constant + table nixio.const_sock for socket error codes. This might + be important if you are dealing with Windows applications, on POSIX however + const_sock is just an alias for const.
    • +
  • With some exceptions - which are explicitely stated in the function + documentation - all blocking functions are signal-protected and will not fail + with EINTR.
    • +
  • On POSIX the SIGPIPE signal will be set to ignore upon initialization. + You should restore the default behaviour or set a custom signal handler + in your program after loading nixio if you need this behaviour.
    • +
+ + + +
+ + +
Functions
+
+ Function conventions. +
In general all functions are namend and behave like their POSIX API + counterparts - where applicable - applying the following rules: +
    +
  • Functions should be named like the underlying POSIX API function ommiting + prefixes or suffixes - especially when placed in an object-context ( + lockf -> File:lock, fsync -> File:sync, dup2 -> dup, ...)
    • +
  • If you are unclear about the behaviour of a function you should consult + your OS API documentation (e.g. the manpages).
    • +
  • If the name is significantly different from the POSIX-function, the + underlying function(s) are stated in the documentation.
    • +
  • Parameters should reflect those of the C-API, buffer length arguments and + by-reference parameters should be ommitted for pratical purposes.
    • +
  • If a C function accepts a bitfield as parameter, it should be translated + into lower case string flags representing the flags if the bitfield is the + last parameter and also ommiting prefixes or suffixes. (e.g. waitpid + (pid, &s, WNOHANG | WUNTRACED) -> waitpid(pid, "nohang", "untraced"), + getsockopt(fd, SOL_SOCKET, SO_REUSEADDR, &opt, sizeof(opt)) -> + Socket:getopt("socket", "reuseaddr"), etc.)
    • +
  • If it is not applicable to provide a string representation of the + bitfield a bitfield generator helper is provided. It is named FUNCTION_flags. + (open("/tmp/test", O_RDONLY | O_NONBLOCK) -> open("/tmp/test", open_flags( + "rdonly", "nonblock")))
    • +
+ + + +
+ + +
Platforms
+
+ Platform information. +
    +
  • The minimum platform requirements are a decent POSIX 2001 support. + Builds are more or less tested on Linux, Solaris and FreeBSD. Builds for + Windows XP SP1 and later can be compiled with MinGW either from Windows + itself or using the MinGW cross-compiler. Earlier versions of Windows are not + supported.
    • +
  • In general all functions which don't have any remarks + in their documentation are available on all platforms.
    • +
  • Functions with a (POSIX), (Linux) or similar prefix are only available + on these specific platforms. Same appplies to parameters of functions + with a similar suffix.
    • +
  • Some functions might have limitations on some platforms. This should + be stated in the documentation. Please also consult your OS API + documentation.
    • +
+ + + +
+ + +
TLS-Crypto
+
+ Cryptography and TLS libraries. +
    +
  • Currently 3 underlying cryptography libraries are supported: openssl, + cyassl and axTLS. The name of the library in use is written to + nixio.tls_provider
    • +
  • You should whenever possible use openssl or cyassl as axTLS has only + limited support. It does not provide support for non-blocking sockets and + is probably less audited than the other ones.
    • +
  • As the supported Windows versions are not suitable for embedded devices + axTLS is at the moment not supported on Windows.
    • +
+ + + +
+ + +
+ + + +
+ +
+ +
+

Valid XHTML 1.0!

+
+ +
+ + diff --git a/doc/modules/nixio.Socket.html b/doc/modules/nixio.Socket.html new file mode 100644 index 000000000..ccb10250a --- /dev/null +++ b/doc/modules/nixio.Socket.html @@ -0,0 +1,1001 @@ + + + + Reference + + + + + +
+ +
+ +
+
+
+ +
+ + + +
+ +

Object Instance nixio.Socket

+ +

+ Socket Object. + Supports IPv4, IPv6 and UNIX (POSIX only) families.

+ + + + + + + +

Functions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Socket:accept () + Accept a connection on the socket.
Socket:bind (host, port) + Bind the socket to a network address.
Socket:close () + Close the socket.
Socket:connect (host, port) + Connect the socket to a network address.
Socket:fileno () + Get the number of the filedescriptor.
Socket:getopt (level, option) + Get a socket option.
Socket:getpeername () + Get the peer address of a socket.
Socket:getsockname () + Get the local address of a socket.
Socket:listen (backlog) + Listen for connections on the socket.
Socket:read  (length) + Receive a message on the socket (This is an alias for recv).
Socket:recv  (length) + Receive a message on the socket.
Socket:recvfrom (length) + Receive a message on the socket including the senders source address.
Socket:send (buffer, offset, length) + Send a message on the socket.
Socket:sendto (buffer, host, port, offset, length) + Send a message on the socket specifying the destination.
Socket:setblocking (blocking) + Set the blocking mode of the socket.
Socket:setopt (level, option, value) + Set a socket option.
Socket:shutdown (how) + Shut down part of a full-duplex connection.
Socket:write (buffer, offset, length) + Send a message on the socket (This is an alias for send).
+ + + + + + +
+
+ + +

Functions

+
+ + + +
Socket:accept ()
+
+ + Accept a connection on the socket. + + + + + + + +

Return values:

+
    + +
  1. Socket Object + +
  2. Peer IP-Address + +
  3. Peer Port + +
+ + + +
+ + + + +
Socket:bind (host, port)
+
+ + Bind the socket to a network address. + + +

Parameters

+
    + +
  • + host: Host (optional, default: all addresses) +
    • + +
  • + port: Port or service description +
    • + +
+ + + + +

Usage

+
    + +
  • This function calls getaddrinfo() and bind() but NOT listen(). + +
  • If host is a domain name it will be looked up and bind() + tries the IP-Addresses in the order returned by the DNS resolver + until the bind succeeds. + +
  • UNIX sockets ignore the port, + and interpret host as a socket path. + +
+ + + +

Return value:

+true + + + +
+ + + + +
Socket:close ()
+
+ + Close the socket. + + + + + + + +

Return value:

+true + + + +
+ + + + +
Socket:connect (host, port)
+
+ + Connect the socket to a network address. + + +

Parameters

+
    + +
  • + host: Hostname or IP-Address (optional, default: localhost) +
    • + +
  • + port: Port or service description +
    • + +
+ + + + +

Usage

+
    + +
  • This function calls getaddrinfo() and connect(). + +
  • If host is a domain name it will be looked up and connect() + tries the IP-Addresses in the order returned by the DNS resolver + until the connect succeeds. + +
  • UNIX sockets ignore the port, + and interpret host as a socket path. + +
+ + + +

Return value:

+true + + + +
+ + + + +
Socket:fileno ()
+
+ + Get the number of the filedescriptor. + + + + + + + +

Return value:

+file descriptor number + + + +
+ + + + +
Socket:getopt (level, option)
+
+ + Get a socket option. + + +

Parameters

+
    + +
  • + level: Level ["socket", "tcp", "ip", "ipv6"] +
    • + +
  • + option: Option ["keepalive", "reuseaddr", "sndbuf", "rcvbuf", + "priority", "broadcast", "linger", "sndtimeo", "rcvtimeo", "dontroute", + "bindtodevice", "error", "oobinline", "cork" (TCP), "nodelay" (TCP), + "mtu" (IP, IPv6), "hdrincl" (IP), "multicast_ttl" (IP), "multicast_loop" + (IP, IPv6), "multicast_if" (IP, IPv6), "v6only" (IPv6), "multicast_hops" + (IPv6), "add_membership" (IP, IPv6), "drop_membership" (IP, IPv6)] +
    • + +
+ + + + + + +

Return value:

+Value + + + +
+ + + + +
Socket:getpeername ()
+
+ + Get the peer address of a socket. + + + + + + + +

Return values:

+
    + +
  1. IP-Address + +
  2. Port + +
+ + + +
+ + + + +
Socket:getsockname ()
+
+ + Get the local address of a socket. + + + + + + + +

Return values:

+
    + +
  1. IP-Address + +
  2. Port + +
+ + + +
+ + + + +
Socket:listen (backlog)
+
+ + Listen for connections on the socket. + + +

Parameters

+
    + +
  • + backlog: Length of queue for pending connections +
    • + +
+ + + + + + +

Return value:

+true + + + +
+ + + + +
Socket:read  (length)
+
+ + Receive a message on the socket (This is an alias for recv). + See the recvfrom description for more details. + + +

Parameters

+
    + +
  • + length: Amount of data to read (in Bytes). +
    • + +
+ + + + + + +

Return value:

+buffer containing data successfully read + + + +

See also:

+ + +
+ + + + +
Socket:recv  (length)
+
+ + Receive a message on the socket. + This function is identical to recvfrom except that it does not return + the sender's source address. See the recvfrom description for more details. + + +

Parameters

+
    + +
  • + length: Amount of data to read (in Bytes). +
    • + +
+ + + + + + +

Return value:

+buffer containing data successfully read + + + +

See also:

+ + +
+ + + + +
Socket:recvfrom (length)
+
+ + Receive a message on the socket including the senders source address. + + +

Parameters

+
    + +
  • + length: Amount of data to read (in Bytes). +
    • + +
+ + + + +

Usage

+
    + +
  • Warning: It is not guaranteed that all requested data + is read at once. + You have to check the return value - the length of the buffer actually read - + or use the safe IO functions in the high-level IO utility module. + +
  • The length of the return buffer is limited by the (compile time) + nixio buffersize which is nixio.const.buffersize (8192 by default). + Any read request greater than that will be safely truncated to this value. + +
+ + + +

Return values:

+
    + +
  1. buffer containing data successfully read + +
  2. host IP-Address of the sender + +
  3. port Port of the sender + +
+ + + +
+ + + + +
Socket:send (buffer, offset, length)
+
+ + Send a message on the socket. + This function is identical to sendto except for the missing destination + paramters. See the sendto description for a detailed description. + + +

Parameters

+
    + +
  • + buffer: Buffer holding the data to be written. +
    • + +
  • + offset: Offset to start reading the buffer from. (optional) +
    • + +
  • + length: Length of chunk to read from the buffer. (optional) +
    • + +
+ + + + + + +

Return value:

+number of bytes written + + + +

See also:

+ + +
+ + + + +
Socket:sendto (buffer, host, port, offset, length)
+
+ + Send a message on the socket specifying the destination. + + +

Parameters

+
    + +
  • + buffer: Buffer holding the data to be written. +
    • + +
  • + host: Target IP-Address +
    • + +
  • + port: Target Port +
    • + +
  • + offset: Offset to start reading the buffer from. (optional) +
    • + +
  • + length: Length of chunk to read from the buffer. (optional) +
    • + +
+ + + + +

Usage

+
    + +
  • Warning: It is not guaranteed that all data + in the buffer is written at once. + You have to check the return value - the number of bytes actually written - + or use the safe IO functions in the high-level IO utility module. + +
  • Unlike standard Lua indexing the lowest offset and default is 0. + +
+ + + +

Return value:

+number of bytes written + + + +
+ + + + +
Socket:setblocking (blocking)
+
+ + Set the blocking mode of the socket. + + +

Parameters

+
    + +
  • + blocking: (boolean) +
    • + +
+ + + + + + +

Return value:

+true + + + +
+ + + + +
Socket:setopt (level, option, value)
+
+ + Set a socket option. + + +

Parameters

+
    + +
  • + level: Level ["socket", "tcp", "ip", "ipv6"] +
    • + +
  • + option: Option ["keepalive", "reuseaddr", "sndbuf", "rcvbuf", + "priority", "broadcast", "linger", "sndtimeo", "rcvtimeo", "dontroute", + "bindtodevice", "error", "oobinline", "cork" (TCP), "nodelay" (TCP), + "mtu" (IP, IPv6), "hdrincl" (IP), "multicast_ttl" (IP), "multicast_loop" + (IP, IPv6), "multicast_if" (IP, IPv6), "v6only" (IPv6), "multicast_hops" + (IPv6), "add_membership" (IP, IPv6), "drop_membership" (IP, IPv6)] +
    • + +
  • + value: Value +
    • + +
+ + + + + + +

Return value:

+true + + + +
+ + + + +
Socket:shutdown (how)
+
+ + Shut down part of a full-duplex connection. + + +

Parameters

+
    + +
  • + how: (optional, default: rdwr) ["rdwr", "rd", "wr"] +
    • + +
+ + + + + + +

Return value:

+true + + + +
+ + + + +
Socket:write (buffer, offset, length)
+
+ + Send a message on the socket (This is an alias for send). + See the sendto description for a detailed description. + + +

Parameters

+
    + +
  • + buffer: Buffer holding the data to be written. +
    • + +
  • + offset: Offset to start reading the buffer from. (optional) +
    • + +
  • + length: Length of chunk to read from the buffer. (optional) +
    • + +
+ + + + + + +

Return value:

+number of bytes written + + + +

See also:

+ + +
+ + +
+ + + + + +
+ +
+ +
+

Valid XHTML 1.0!

+
+ +
+ + diff --git a/doc/modules/nixio.TLSContext.html b/doc/modules/nixio.TLSContext.html new file mode 100644 index 000000000..a0f630974 --- /dev/null +++ b/doc/modules/nixio.TLSContext.html @@ -0,0 +1,447 @@ + + + + Reference + + + + + +
+ +
+ +
+
+
+ +
+ + + +
+ +

Object Instance nixio.TLSContext

+ +

+ Transport Layer Security Context Object.

+ + + + + + + +

Functions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TLSContext:create (socket) + Create a TLS Socket from a socket descriptor.
TLSContext:set_cert (path) + Assign a PEM certificate to this context.
TLSContext:set_ciphers (cipherlist) + Set the available ciphers for this context.
TLSContext:set_key (path) + Assign a PEM private key to this context.
TLSContext:set_verify (flag1, ...) + Set the verification flags of this context.
TLSContext:set_verify_depth (depth) + Set the verification depth of this context.
+ + + + + + +
+
+ + +

Functions

+
+ + + +
TLSContext:create (socket)
+
+ + Create a TLS Socket from a socket descriptor. + + +

Parameters

+
    + +
  • + socket: Socket Object +
    • + +
+ + + + + + +

Return value:

+TLSSocket Object + + + +
+ + + + +
TLSContext:set_cert (path)
+
+ + Assign a PEM certificate to this context. + + +

Parameters

+
    + +
  • + path: Certificate File path +
    • + +
+ + + + +

Usage:

+This function calls SSL_CTX_use_certificate_chain_file(). + + + +

Return value:

+true + + + +
+ + + + +
TLSContext:set_ciphers (cipherlist)
+
+ + Set the available ciphers for this context. + + +

Parameters

+
    + +
  • + cipherlist: String containing a list of ciphers +
    • + +
+ + + + +

Usage:

+This function calls SSL_CTX_set_cipher_list(). + + + +

Return value:

+true + + + +
+ + + + +
TLSContext:set_key (path)
+
+ + Assign a PEM private key to this context. + + +

Parameters

+
    + +
  • + path: Private Key File path +
    • + +
+ + + + +

Usage:

+This function calls SSL_CTX_use_PrivateKey_file(). + + + +

Return value:

+true + + + +
+ + + + +
TLSContext:set_verify (flag1, ...)
+
+ + Set the verification flags of this context. + + +

Parameters

+
    + +
  • + flag1: First Flag ["none", "peer", "verify_fail_if_no_peer_cert", + "client_once"] +
    • + +
  • + ...: More Flags [-"-] +
    • + +
+ + + + +

Usage:

+This function calls SSL_CTX_set_verify(). + + + +

Return value:

+true + + + +
+ + + + +
TLSContext:set_verify_depth (depth)
+
+ + Set the verification depth of this context. + + +

Parameters

+
    + +
  • + depth: Depth +
    • + +
+ + + + +

Usage:

+This function calls SSL_CTX_set_verify_depth(). + + + +

Return value:

+true + + + +
+ + +
+ + + + + +
+ +
+ +
+

Valid XHTML 1.0!

+
+ +
+ + diff --git a/doc/modules/nixio.TLSSocket.html b/doc/modules/nixio.TLSSocket.html new file mode 100644 index 000000000..36b31f344 --- /dev/null +++ b/doc/modules/nixio.TLSSocket.html @@ -0,0 +1,543 @@ + + + + Reference + + + + + +
+ +
+ +
+
+
+ +
+ + + +
+ +

Object Instance nixio.TLSSocket

+ +

+ TLS Socket Object. + TLS Sockets contain the underlying socket and context in the fields + "socket" and "context".

+ + + + + + + +

Functions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TLSSocket:accept () + Wait for a TLS handshake from a client.
TLSSocket:connect () + Initiate the TLS handshake as client with the server.
TLSSocket:read  (length) + Receive a message on the socket (This is an alias for recv).
TLSSocket:recv (length) + Receive a message on the socket.
TLSSocket:send (buffer, offset, length) + Send a message to the socket.
TLSSocket:shutdown () + Shut down the TLS connection.
TLSSocket:write (buffer, offset, length) + Send a message on the socket (This is an alias for send).
+ + + + + + +
+
+ + +

Functions

+
+ + + +
TLSSocket:accept ()
+
+ + Wait for a TLS handshake from a client. + + + + + +

Usage

+
    + +
  • This function calls SSL_accept(). + +
  • You have to call either connect or accept before transmitting data. + +
+ + + +

Return value:

+true + + + +

See also:

+ + +
+ + + + +
TLSSocket:connect ()
+
+ + Initiate the TLS handshake as client with the server. + + + + + +

Usage

+
    + +
  • This function calls SSL_connect(). + +
  • You have to call either connect or accept before transmitting data. + +
+ + + +

Return value:

+true + + + +

See also:

+ + +
+ + + + +
TLSSocket:read  (length)
+
+ + Receive a message on the socket (This is an alias for recv). + See the recv description for more details. + + +

Parameters

+
    + +
  • + length: Amount of data to read (in Bytes). +
    • + +
+ + + + + + +

Return value:

+buffer containing data successfully read + + + +

See also:

+ + +
+ + + + +
TLSSocket:recv (length)
+
+ + Receive a message on the socket. + + +

Parameters

+
    + +
  • + length: Amount of data to read (in Bytes). +
    • + +
+ + + + +

Usage

+
    + +
  • This function calls SSL_read(). + +
  • Warning: It is not guaranteed that all requested data + is read at once. + You have to check the return value - the length of the buffer actually read - + or use the safe IO functions in the high-level IO utility module. + +
  • The length of the return buffer is limited by the (compile time) + nixio buffersize which is nixio.const.buffersize (8192 by default). + Any read request greater than that will be safely truncated to this value. + +
+ + + +

Return value:

+buffer containing data successfully read + + + +
+ + + + +
TLSSocket:send (buffer, offset, length)
+
+ + Send a message to the socket. + + +

Parameters

+
    + +
  • + buffer: Buffer holding the data to be written. +
    • + +
  • + offset: Offset to start reading the buffer from. (optional) +
    • + +
  • + length: Length of chunk to read from the buffer. (optional) +
    • + +
+ + + + +

Usage

+
    + +
  • This function calls SSL_write(). + +
  • Warning: It is not guaranteed that all data + in the buffer is written at once. + You have to check the return value - the number of bytes actually written - + or use the safe IO functions in the high-level IO utility module. + +
  • Unlike standard Lua indexing the lowest offset and default is 0. + +
+ + + +

Return value:

+number of bytes written + + + +
+ + + + +
TLSSocket:shutdown ()
+
+ + Shut down the TLS connection. + + + + + +

Usage:

+This function calls SSL_shutdown(). + + + +

Return value:

+true + + + +
+ + + + +
TLSSocket:write (buffer, offset, length)
+
+ + Send a message on the socket (This is an alias for send). + See the send description for a detailed description. + + +

Parameters

+
    + +
  • + buffer: Buffer holding the data to be written. +
    • + +
  • + offset: Offset to start reading the buffer from. (optional) +
    • + +
  • + length: Length of chunk to read from the buffer. (optional) +
    • + +
+ + + + + + +

Return value:

+number of bytes written + + + +

See also:

+ + +
+ + +
+ + + + + +
+ +
+ +
+

Valid XHTML 1.0!

+
+ +
+ + diff --git a/doc/modules/nixio.UnifiedIO.html b/doc/modules/nixio.UnifiedIO.html new file mode 100644 index 000000000..576c23fed --- /dev/null +++ b/doc/modules/nixio.UnifiedIO.html @@ -0,0 +1,735 @@ + + + + Reference + + + + + +
+ +
+ +
+
+
+ +
+ + + +
+ +

Object Instance nixio.UnifiedIO

+ +

+ Unified high-level I/O utility API for Files, Sockets and TLS-Sockets. + These functions are added to the object function tables by doing + require "nixio.util", can be used on all nixio IO Descriptors and + are based on the shared low-level read() and write() functions.

+ + + + + + + +

Functions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
UnifiedIO:blocksource (blocksize, limit) + Create a block-based iterator.
UnifiedIO:close () + Close the descriptor.
UnifiedIO:copy (fdout, size) + Copy data from the current descriptor to another one.
UnifiedIO:copyz (fdout, size) + Copy data from the current descriptor to another one using kernel-space + copying if possible.
UnifiedIO:is_file () + Test whether the I/O-Descriptor is a file.
UnifiedIO:is_socket () + Test whether the I/O-Descriptor is a socket.
UnifiedIO:is_tls_socket () + Test whether the I/O-Descriptor is a TLS socket.
UnifiedIO:linesource (limit) + Create a line-based iterator.
UnifiedIO:readall (length) + Read a block of data and wait until all data is available.
UnifiedIO:sink (close_when_done) + Create a sink.
UnifiedIO:writeall (block) + Write a block of data and wait until all data is written.
+ + + + + + +
+
+ + +

Functions

+
+ + + +
UnifiedIO:blocksource (blocksize, limit)
+
+ + Create a block-based iterator. + + +

Parameters

+
    + +
  • + blocksize: Advisory blocksize (optional) +
    • + +
  • + limit: Amount of data to consume (optional) +
    • + +
+ + + + +

Usage

+
    + +
  • This function uses the low-level read function of the descriptor. + +
  • The blocksize given is only advisory and to be seen as an upper limit, + if an underlying read returns less bytes the chunk is nevertheless returned. + +
  • If the limit parameter is ommited, the iterator returns data + until an end-of-file, end-of-stream, connection shutdown or similar happens. + +
  • The iterator will not buffer so it is safe to mix with calls to read. + +
  • If the descriptor is non-blocking the iterator may fail with EAGAIN. + +
  • The iterator can be used as an LTN12 source. + +
+ + + +

Return value:

+Block-based Iterator + + + +
+ + + + +
UnifiedIO:close ()
+
+ + Close the descriptor. + + + + + +

Usage:

+If the descriptor is a TLS-socket the underlying descriptor is + closed without touching the TLS connection. + + + +

Return value:

+true + + + +
+ + + + +
UnifiedIO:copy (fdout, size)
+
+ + Copy data from the current descriptor to another one. + + +

Parameters

+
    + +
  • + fdout: Target Descriptor +
    • + +
  • + size: Bytes to copy (optional) +
    • + +
+ + + + +

Usage

+
    + +
  • This function uses the blocksource function of the source descriptor + and the sink function of the target descriptor. + +
  • If the limit parameter is ommited, data is copied + until an end-of-file, end-of-stream, connection shutdown or similar happens. + +
  • If the descriptor is non-blocking the function may fail with EAGAIN. + +
+ + + +

Return values:

+
    + +
  1. bytes that were successfully written if no error occured + +
  2. - reserved for error code - + +
  3. - reserved for error message - + +
  4. bytes that were successfully written even if an error occured + +
+ + + +
+ + + + +
UnifiedIO:copyz (fdout, size)
+
+ + Copy data from the current descriptor to another one using kernel-space + copying if possible. + + +

Parameters

+
    + +
  • + fdout: Target Descriptor +
    • + +
  • + size: Bytes to copy (optional) +
    • + +
+ + + + +

Usage

+
    + +
  • This function uses the sendfile() syscall to copy the data or the + blocksource function of the source descriptor and the sink function + of the target descriptor as a fallback mechanism. + +
  • If the limit parameter is ommited, data is copied + until an end-of-file, end-of-stream, connection shutdown or similar happens. + +
  • If the descriptor is non-blocking the function may fail with EAGAIN. + +
+ + + +

Return values:

+
    + +
  1. bytes that were successfully written if no error occured + +
  2. - reserved for error code - + +
  3. - reserved for error message - + +
  4. bytes that were successfully written even if an error occured + +
+ + + +
+ + + + +
UnifiedIO:is_file ()
+
+ + Test whether the I/O-Descriptor is a file. + + + + + + + +

Return value:

+boolean + + + +
+ + + + +
UnifiedIO:is_socket ()
+
+ + Test whether the I/O-Descriptor is a socket. + + + + + + + +

Return value:

+boolean + + + +
+ + + + +
UnifiedIO:is_tls_socket ()
+
+ + Test whether the I/O-Descriptor is a TLS socket. + + + + + + + +

Return value:

+boolean + + + +
+ + + + +
UnifiedIO:linesource (limit)
+
+ + Create a line-based iterator. + Lines may end with either \n or \r\n, these control chars are not included + in the return value. + + +

Parameters

+
    + +
  • + limit: Line limit +
    • + +
+ + + + +

Usage

+
    + +
  • This function uses the low-level read function of the descriptor. + +
  • Note: This function uses an internal buffer to read + ahead. Do NOT mix calls to read(all) and the returned iterator. If you want + to stop reading line-based and want to use the read(all) functions instead + you can pass "true" to the iterator which will flush the buffer + and return the bufferd data. + +
  • If the limit parameter is ommited, this function uses the nixio + buffersize (8192B by default). + +
  • If the descriptor is non-blocking the iterator may fail with EAGAIN. + +
  • The iterator can be used as an LTN12 source. + +
+ + + +

Return value:

+Line-based Iterator + + + +
+ + + + +
UnifiedIO:readall (length)
+
+ + Read a block of data and wait until all data is available. + + +

Parameters

+
    + +
  • + length: Bytes to read (optional) +
    • + +
+ + + + +

Usage

+
    + +
  • This function uses the low-level read function of the descriptor. + +
  • If the length parameter is ommited, this function returns all data + that can be read before an end-of-file, end-of-stream, connection shutdown + or similar happens. + +
  • If the descriptor is non-blocking this function may fail with EAGAIN. + +
+ + + +

Return values:

+
    + +
  1. data that was successfully read if no error occured + +
  2. - reserved for error code - + +
  3. - reserved for error message - + +
  4. data that was successfully read even if an error occured + +
+ + + +
+ + + + +
UnifiedIO:sink (close_when_done)
+
+ + Create a sink. + This sink will simply write all data that it receives and optionally + close the descriptor afterwards. + + +

Parameters

+
    + +
  • + close_when_done: (optional, boolean) +
    • + +
+ + + + +

Usage

+
    + +
  • This function uses the writeall function of the descriptor. + +
  • If the descriptor is non-blocking the sink may fail with EAGAIN. + +
  • The iterator can be used as an LTN12 sink. + +
+ + + +

Return value:

+Sink + + + +
+ + + + +
UnifiedIO:writeall (block)
+
+ + Write a block of data and wait until all data is written. + + +

Parameters

+
    + +
  • + block: Bytes to write +
    • + +
+ + + + +

Usage

+
    + +
  • This function uses the low-level write function of the descriptor. + +
  • If the descriptor is non-blocking this function may fail with EAGAIN. + +
+ + + +

Return values:

+
    + +
  1. bytes that were successfully written if no error occured + +
  2. - reserved for error code - + +
  3. - reserved for error message - + +
  4. bytes that were successfully written even if an error occured + +
+ + + +
+ + +
+ + + + + +
+ +
+ +
+

Valid XHTML 1.0!

+
+ +
+ + diff --git a/doc/modules/nixio.bin.html b/doc/modules/nixio.bin.html new file mode 100644 index 000000000..33421b743 --- /dev/null +++ b/doc/modules/nixio.bin.html @@ -0,0 +1,395 @@ + + + + Reference + + + + + +
+ +
+ +
+
+
+ +
+ + + +
+ +

Class nixio.bin

+ +

+ Binary operations and conversion.

+ + + + + + + +

Functions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
b64decode (buffer) + Base64 decode a given buffer.
b64encode (buffer) + Base64 encode a given buffer.
crc32 (buffer, initial) + Calculate the CRC32 value of a buffer.
hexlify (buffer) + Return a hexadecimal ASCII represantation of the content of a buffer.
unhexlify (hexvalue) + Return a binary buffer from a hexadecimal ASCII representation.
+ + + + + + +
+
+ + +

Functions

+
+ + + +
b64decode (buffer)
+
+ + Base64 decode a given buffer. + + +

Parameters

+
    + +
  • + buffer: Base 64 Encoded data +
    • + +
+ + + + + + +

Return value:

+binary data + + + +
+ + + + +
b64encode (buffer)
+
+ + Base64 encode a given buffer. + + +

Parameters

+
    + +
  • + buffer: Buffer +
    • + +
+ + + + + + +

Return value:

+base64 encoded buffer + + + +
+ + + + +
crc32 (buffer, initial)
+
+ + Calculate the CRC32 value of a buffer. + + +

Parameters

+
    + +
  • + buffer: Buffer +
    • + +
  • + initial: Initial CRC32 value (optional) +
    • + +
+ + + + + + +

Return value:

+crc32 value + + + +
+ + + + +
hexlify (buffer)
+
+ + Return a hexadecimal ASCII represantation of the content of a buffer. + + +

Parameters

+
    + +
  • + buffer: Buffer +
    • + +
+ + + + + + +

Return value:

+representation using characters [0-9a-f] + + + +
+ + + + +
unhexlify (hexvalue)
+
+ + Return a binary buffer from a hexadecimal ASCII representation. + + +

Parameters

+
    + +
  • + hexvalue: representation using characters [0-9a-f] +
    • + +
+ + + + + + +

Return value:

+binary data + + + +
+ + +
+ + + + + +
+ +
+ +
+

Valid XHTML 1.0!

+
+ +
+ + diff --git a/doc/modules/nixio.bit.html b/doc/modules/nixio.bit.html new file mode 100644 index 000000000..80940afff --- /dev/null +++ b/doc/modules/nixio.bit.html @@ -0,0 +1,712 @@ + + + + Reference + + + + + +
+ +
+ +
+
+
+ +
+ + + +
+ +

Class nixio.bit

+ +

+ Bitfield operators and mainpulation functions. + Can be used as a drop-in replacement for bitlib.

+ + + + + + + +

Functions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
arshift (oper, shift) + Arithmetically right shift a number.
band (oper1, oper2, ...) + Bitwise AND several numbers.
bnot (oper) + Invert given number.
bor (oper1, oper2, ...) + Bitwise OR several numbers.
bxor (oper1, oper2, ...) + Bitwise XOR several numbers.
cast (oper) + Cast a number to the bit-operating range.
check (bitfield, flag1, ...) + Checks whether given flags are set in a bitfield.
div (oper1, oper2, ...) + Integer division of 2 or more numbers.
lshift (oper, shift) + Left shift a number.
rshift (oper, shift) + Right shift a number.
set (bitfield, flag1, ...) + Sets one or more flags of a bitfield.
unset (bitfield, flag1, ...) + Unsets one or more flags of a bitfield.
+ + + + + + +
+
+ + +

Functions

+
+ + + +
arshift (oper, shift)
+
+ + Arithmetically right shift a number. + + +

Parameters

+
    + +
  • + oper: number +
    • + +
  • + shift: bits to shift +
    • + +
+ + + + + + +

Return value:

+number + + + +
+ + + + +
band (oper1, oper2, ...)
+
+ + Bitwise AND several numbers. + + +

Parameters

+
    + +
  • + oper1: First Operand +
    • + +
  • + oper2: Second Operand +
    • + +
  • + ...: More Operands +
    • + +
+ + + + + + +

Return value:

+number + + + +
+ + + + +
bnot (oper)
+
+ + Invert given number. + + +

Parameters

+
    + +
  • + oper: Operand +
    • + +
+ + + + + + +

Return value:

+number + + + +
+ + + + +
bor (oper1, oper2, ...)
+
+ + Bitwise OR several numbers. + + +

Parameters

+
    + +
  • + oper1: First Operand +
    • + +
  • + oper2: Second Operand +
    • + +
  • + ...: More Operands +
    • + +
+ + + + + + +

Return value:

+number + + + +
+ + + + +
bxor (oper1, oper2, ...)
+
+ + Bitwise XOR several numbers. + + +

Parameters

+
    + +
  • + oper1: First Operand +
    • + +
  • + oper2: Second Operand +
    • + +
  • + ...: More Operands +
    • + +
+ + + + + + +

Return value:

+number + + + +
+ + + + +
cast (oper)
+
+ + Cast a number to the bit-operating range. + + +

Parameters

+
    + +
  • + oper: number +
    • + +
+ + + + + + +

Return value:

+number + + + +
+ + + + +
check (bitfield, flag1, ...)
+
+ + Checks whether given flags are set in a bitfield. + + +

Parameters

+
    + +
  • + bitfield: Bitfield +
    • + +
  • + flag1: First Flag +
    • + +
  • + ...: More Flags +
    • + +
+ + + + + + +

Return value:

+true when all flags are set, otherwise false + + + +
+ + + + +
div (oper1, oper2, ...)
+
+ + Integer division of 2 or more numbers. + + +

Parameters

+
    + +
  • + oper1: Operand 1 +
    • + +
  • + oper2: Operand 2 +
    • + +
  • + ...: More Operands +
    • + +
+ + + + + + +

Return value:

+number + + + +
+ + + + +
lshift (oper, shift)
+
+ + Left shift a number. + + +

Parameters

+
    + +
  • + oper: number +
    • + +
  • + shift: bits to shift +
    • + +
+ + + + + + +

Return value:

+number + + + +
+ + + + +
rshift (oper, shift)
+
+ + Right shift a number. + + +

Parameters

+
    + +
  • + oper: number +
    • + +
  • + shift: bits to shift +
    • + +
+ + + + + + +

Return value:

+number + + + +
+ + + + +
set (bitfield, flag1, ...)
+
+ + Sets one or more flags of a bitfield. + + +

Parameters

+
    + +
  • + bitfield: Bitfield +
    • + +
  • + flag1: First Flag +
    • + +
  • + ...: More Flags +
    • + +
+ + + + + + +

Return value:

+altered bitfield + + + +
+ + + + +
unset (bitfield, flag1, ...)
+
+ + Unsets one or more flags of a bitfield. + + +

Parameters

+
    + +
  • + bitfield: Bitfield +
    • + +
  • + flag1: First Flag +
    • + +
  • + ...: More Flags +
    • + +
+ + + + + + +

Return value:

+altered bitfield + + + +
+ + +
+ + + + + +
+ +
+ +
+

Valid XHTML 1.0!

+
+ +
+ + diff --git a/doc/modules/nixio.crypto.html b/doc/modules/nixio.crypto.html new file mode 100644 index 000000000..d74cf5c8f --- /dev/null +++ b/doc/modules/nixio.crypto.html @@ -0,0 +1,287 @@ + + + + Reference + + + + + +
+ +
+ +
+
+
+ +
+ + + +
+ +

Class nixio.crypto

+ +

+ Cryptographical library.

+ + + + + + + +

Functions

+ + + + + + + + + + + + +
hash (algo) + Create a hash object.
hmac (algo, key) + Create a HMAC object.
+ + + + + + +
+
+ + +

Functions

+
+ + + +
hash (algo)
+
+ + Create a hash object. + + +

Parameters

+
    + +
  • + algo: Algorithm ["sha1", "md5"] +
    • + +
+ + + + + + +

Return value:

+CryptoHash Object + + + +
+ + + + +
hmac (algo, key)
+
+ + Create a HMAC object. + + +

Parameters

+
    + +
  • + algo: Algorithm ["sha1", "md5"] +
    • + +
  • + key: HMAC-Key +
    • + +
+ + + + + + +

Return value:

+CryptoHash Object + + + +
+ + +
+ + + + + +
+ +
+ +
+

Valid XHTML 1.0!

+
+ +
+ + diff --git a/doc/modules/nixio.fs.html b/doc/modules/nixio.fs.html new file mode 100644 index 000000000..359f02395 --- /dev/null +++ b/doc/modules/nixio.fs.html @@ -0,0 +1,1530 @@ + + + + Reference + + + + + +
+ +
+ +
+
+
+ +
+ + + +
+ +

Class nixio.fs

+ +

+ Low-level and high-level filesystem manipulation library.

+ + + + + + + +

Functions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
access (path, mode1, ...) + Check user's permission on a file.
basename (path) + Strip the directory part from a path.
chmod (path, mode) + Change the file mode.
chown (path, user, group) + (POSIX) Change owner and group of a file.
copy (src, dest) + Copy a file, directory or symlink non-recursively preserving file mode, + timestamps, owner and group.
copyr (src, dest) + Copy a file, directory or symlink recursively preserving file mode, + timestamps, owner and group.
datacopy (src, dest, limit) + Copy data between files.
dir (path) + Iterate over the entries of a directory.
dirname (path) + Strip the base from a path.
glob (pattern) + (POSIX) Find pathnames matching a pattern.
lchown (path, user, group) + (POSIX) Change owner and group of a file and do not resolve + if target is a symlink.
link (oldpath, newpath) + Create a hard link.
lstat (path, field) + Get file status and attributes and do not resolve if target is a symlink.
mkdir (path, mode) + Create a new directory.
mkdirr (dest, mode) + Create a directory and all needed parent directories recursively.
mkfifo (path, mode) + (POSIX) Create a FIFO (named pipe).
move (src, dest) + Rename a file, directory or symlink non-recursively across filesystems.
mover (src, dest) + Rename a file, directory or symlink recursively across filesystems.
readfile (path, limit) + Read the contents of a file into a buffer.
readlink (path) + (POSIX) Read the target of a symbolic link.
realpath (path) + Return the cannonicalized absolute pathname.
remove (path) + Remove a file or directory.
rename (src, dest) + Renames a file or directory.
rmdir (path) + Remove an empty directory.
stat (path, field) + Get file status and attributes.
statvfs (path) + (POSIX) Get filesystem statistics.
symlink (oldpath, newpath) + (POSIX) Create a symbolic link.
unlink (path) + Delete a name and - if no links are left - the associated file.
utimes (path, actime, mtime) + Change file last access and last modification time.
writefile (path, data) + Write a buffer into a file truncating the file first.
+ + + + + + +
+
+ + +

Functions

+
+ + + +
access (path, mode1, ...)
+
+ + Check user's permission on a file. + + +

Parameters

+
    + +
  • + path: Path +
    • + +
  • + mode1: First Mode to check ["f", "r", "w", "x"] +
    • + +
  • + ...: More Modes to check [-"-] +
    • + +
+ + + + + + +

Return value:

+true + + + +
+ + + + +
basename (path)
+
+ + Strip the directory part from a path. + + +

Parameters

+
    + +
  • + path: Path +
    • + +
+ + + + +

Usage:

+This function cannot fail and will never return nil. + + + +

Return value:

+basename + + + +
+ + + + +
chmod (path, mode)
+
+ + Change the file mode. + + +

Parameters

+
    + +
  • + path: Path +
    • + +
  • + mode: File mode + [decimal mode number, "[-r][-w][-xsS][-r][-w][-xsS][-r][-w][-xtT]"] +
    • + +
+ + + + +

Usage

+
    + +
  • Windows only supports setting the write-protection through the + "Writable to others" bit. + +
  • Notice: The mode-flag for the functions + open, mkdir, mkfifo are affected by the umask. + +
+ + + +

Return value:

+true + + + +

See also:

+ + +
+ + + + +
chown (path, user, group)
+
+ + (POSIX) Change owner and group of a file. + + +

Parameters

+
    + +
  • + path: Path +
    • + +
  • + user: User ID or Username (optional) +
    • + +
  • + group: Group ID or Groupname (optional) +
    • + +
+ + + + + + +

Return value:

+true + + + +
+ + + + +
copy (src, dest)
+
+ + Copy a file, directory or symlink non-recursively preserving file mode, + timestamps, owner and group. + + +

Parameters

+
    + +
  • + src: Source path +
    • + +
  • + dest: Destination path +
    • + +
+ + + + +

Usage:

+The destination must always be a full destination path e.g. do not + omit the basename even if source and destination basename are equal. + + + +

Return value:

+true + + + +
+ + + + +
copyr (src, dest)
+
+ + Copy a file, directory or symlink recursively preserving file mode, + timestamps, owner and group. + + +

Parameters

+
    + +
  • + src: Source path +
    • + +
  • + dest: Destination path +
    • + +
+ + + + +

Usage:

+The destination must always be a full destination path e.g. do not + omit the basename even if source and destination basename are equal. + + + +

Return value:

+true + + + +
+ + + + +
datacopy (src, dest, limit)
+
+ + Copy data between files. + + +

Parameters

+
    + +
  • + src: Source file path +
    • + +
  • + dest: Destination file path +
    • + +
  • + limit: Maximum bytes to copy (optional) +
    • + +
+ + + + + + +

Return value:

+true + + + +
+ + + + +
dir (path)
+
+ + Iterate over the entries of a directory. + + +

Parameters

+
    + +
  • + path: Path +
    • + +
+ + + + +

Usage:

+The special entries "." and ".." are omitted. + + + +

Return value:

+directory iterator returning one entry per call + + + +
+ + + + +
dirname (path)
+
+ + Strip the base from a path. + + +

Parameters

+
    + +
  • + path: Path +
    • + +
+ + + + +

Usage:

+This function cannot fail and will never return nil. + + + +

Return value:

+dirname + + + +
+ + + + +
glob (pattern)
+
+ + (POSIX) Find pathnames matching a pattern. + + +

Parameters

+
    + +
  • + pattern: Pattern +
    • + +
+ + + + + + +

Return values:

+
    + +
  1. path iterator + +
  2. number of matches + +
+ + + +
+ + + + +
lchown (path, user, group)
+
+ + (POSIX) Change owner and group of a file and do not resolve + if target is a symlink. + + +

Parameters

+
    + +
  • + path: Path +
    • + +
  • + user: User ID or Username (optional) +
    • + +
  • + group: Group ID or Groupname (optional) +
    • + +
+ + + + + + +

Return value:

+true + + + +
+ + + + +
link (oldpath, newpath)
+
+ + Create a hard link. + + +

Parameters

+
    + +
  • + oldpath: Path +
    • + +
  • + newpath: Path +
    • + +
+ + + + +

Usage:

+This function calls link() on POSIX and CreateHardLink() on Windows. + + + +

Return value:

+true + + + +
+ + + + +
lstat (path, field)
+
+ + Get file status and attributes and do not resolve if target is a symlink. + + +

Parameters

+
    + +
  • + path: Path +
    • + +
  • + field: Only return a specific field, not the whole table (optional) +
    • + +
+ + + + + + +

Return value:

+Table containing attributes (see stat for a detailed description) + + + +

See also:

+ + +
+ + + + +
mkdir (path, mode)
+
+ + Create a new directory. + + +

Parameters

+
    + +
  • + path: Path +
    • + +
  • + mode: File mode (optional, see chmod and umask) +
    • + +
+ + + + + + +

Return value:

+true + + + +

See also:

+ + +
+ + + + +
mkdirr (dest, mode)
+
+ + Create a directory and all needed parent directories recursively. + + +

Parameters

+
    + +
  • + dest: Destination path +
    • + +
  • + mode: File mode (optional, see chmod and umask) +
    • + +
+ + + + + + +

Return value:

+true + + + +

See also:

+ + +
+ + + + +
mkfifo (path, mode)
+
+ + (POSIX) Create a FIFO (named pipe). + + +

Parameters

+
    + +
  • + path: Path +
    • + +
  • + mode: File mode (optional, see chmod and umask) +
    • + +
+ + + + + + +

Return value:

+true + + + +

See also:

+ + +
+ + + + +
move (src, dest)
+
+ + Rename a file, directory or symlink non-recursively across filesystems. + + +

Parameters

+
    + +
  • + src: Source path +
    • + +
  • + dest: Destination path +
    • + +
+ + + + +

Usage:

+The destination must always be a full destination path e.g. do not + omit the basename even if source and destination basename are equal. + + + +

Return value:

+true + + + +
+ + + + +
mover (src, dest)
+
+ + Rename a file, directory or symlink recursively across filesystems. + + +

Parameters

+
    + +
  • + src: Source path +
    • + +
  • + dest: Destination path +
    • + +
+ + + + +

Usage:

+The destination must always be a full destination path e.g. do not + omit the basename even if source and destination basename are equal. + + + +

Return value:

+true + + + +
+ + + + +
readfile (path, limit)
+
+ + Read the contents of a file into a buffer. + + +

Parameters

+
    + +
  • + path: Path +
    • + +
  • + limit: Maximum bytes to read (optional) +
    • + +
+ + + + + + +

Return value:

+file contents + + + +
+ + + + +
readlink (path)
+
+ + (POSIX) Read the target of a symbolic link. + + +

Parameters

+
    + +
  • + path: Path +
    • + +
+ + + + + + +

Return value:

+target path + + + +
+ + + + +
realpath (path)
+
+ + Return the cannonicalized absolute pathname. + + +

Parameters

+
    + +
  • + path: Path +
    • + +
+ + + + + + +

Return value:

+absolute path + + + +
+ + + + +
remove (path)
+
+ + Remove a file or directory. + + +

Parameters

+
    + +
  • + path: Path +
    • + +
+ + + + + + +

Return value:

+true + + + +
+ + + + +
rename (src, dest)
+
+ + Renames a file or directory. + + +

Parameters

+
    + +
  • + src: Source path +
    • + +
  • + dest: Destination path +
    • + +
+ + + + +

Usage:

+It is normally not possible to rename files accross fileystems. + + + +

Return value:

+true + + + +
+ + + + +
rmdir (path)
+
+ + Remove an empty directory. + + +

Parameters

+
    + +
  • + path: Path +
    • + +
+ + + + + + +

Return value:

+true + + + +
+ + + + +
stat (path, field)
+
+ + Get file status and attributes. + + +

Parameters

+
    + +
  • + path: Path +
    • + +
  • + field: Only return a specific field, not the whole table (optional) +
    • + +
+ + + + + + +

Return value:

+Table containing:
    +
  • atime = Last access timestamp
    • +
  • blksize = Blocksize (POSIX only)
    • +
  • blocks = Blocks used (POSIX only)
    • +
  • ctime = Creation timestamp
    • +
  • dev = Device ID
    • +
  • gid = Group ID
    • +
  • ino = Inode
    • +
  • modedec = Mode converted into a decimal number
    • +
  • modestr = Mode as string as returned by ls -l
    • +
  • mtime = Last modification timestamp
    • +
  • nlink = Number of links
    • +
  • rdev = Device ID (if special file)
    • +
  • size = Size in bytes
    • +
  • type = ["reg", "dir", "chr", "blk", "fifo", "lnk", "sock"]
    • +
  • uid = User ID
    • +
+ + + +
+ + + + +
statvfs (path)
+
+ + (POSIX) Get filesystem statistics. + + +

Parameters

+
    + +
  • + path: Path to any file within the filesystem. +
    • + +
+ + + + + + +

Return value:

+Table containing:
    +
  • bavail = available blocks
    • +
  • bfree = free blocks
    • +
  • blocks = number of fragments
    • +
  • frsize = fragment size
    • +
  • favail = available inodes
    • +
  • ffree = free inodes
    • +
  • files = inodes
    • +
  • flag = flags
    • +
  • fsid = filesystem ID
    • +
  • namemax = maximum filename length
    • +
+ + + +
+ + + + +
symlink (oldpath, newpath)
+
+ + (POSIX) Create a symbolic link. + + +

Parameters

+
    + +
  • + oldpath: Path +
    • + +
  • + newpath: Path +
    • + +
+ + + + + + +

Return value:

+true + + + +
+ + + + +
unlink (path)
+
+ + Delete a name and - if no links are left - the associated file. + + +

Parameters

+
    + +
  • + path: Path +
    • + +
+ + + + + + +

Return value:

+true + + + +
+ + + + +
utimes (path, actime, mtime)
+
+ + Change file last access and last modification time. + + +

Parameters

+
    + +
  • + path: Path +
    • + +
  • + actime: Last access timestamp (optional, default: current time) +
    • + +
  • + mtime: Last modification timestamp (optional, default: actime) +
    • + +
+ + + + + + +

Return value:

+true + + + +
+ + + + +
writefile (path, data)
+
+ + Write a buffer into a file truncating the file first. + + +

Parameters

+
    + +
  • + path: Path +
    • + +
  • + data: Data to write +
    • + +
+ + + + + + +

Return value:

+true + + + +
+ + +
+ + + + + +
+ +
+ +
+

Valid XHTML 1.0!

+
+ +
+ + diff --git a/doc/modules/nixio.html b/doc/modules/nixio.html new file mode 100644 index 000000000..8b0f84b1a --- /dev/null +++ b/doc/modules/nixio.html @@ -0,0 +1,2373 @@ + + + + Reference + + + + + +
+ +
+ +
+
+
+ +
+ + + +
+ +

Class nixio

+ +

+ General POSIX IO library.

+ + + + + + + +

Functions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
bind (host, port, family, socktype) + Create a new socket and bind it to a network address.
chdir (path) + Change the working directory.
closelog () + (POSIX) Close the connection to the system logger.
connect (host, port, family, socktype) + Create a new socket and connect to a network address.
crypt (key, salt) + (POSIX) Encrypt a user password.
dup (oldfd, newfd) + Duplicate a file descriptor.
errno () + Get the last system error code.
exec (executable, ...) + Execute a file to replace the current process.
exece (executable, arguments, environment) + Execute a file with a custom environment to replace the current process.
execp (executable, ...) + Invoke the shell and execute a file to replace the current process.
fork () + (POSIX) Clone the current process.
getaddrinfo (host, family, service) + Look up a hostname and service via DNS.
getcwd () + Get the current working directory.
getenv (variable) + Get the current environment table or a specific environment variable.
getgid () + (POSIX) Get the group id of the current process.
getgr (group) + (POSIX) Get all or a specific user group.
getifaddrs () + (Linux, BSD) Get a list of available network interfaces and their addresses.
getnameinfo (ipaddr) + Reverse look up an IP-Address via DNS.
getpid () + Get the ID of the current process.
getppid () + (POSIX) Get the parent process id of the current process.
getproto (proto) + Get all or a specifc proto entry.
getprotobyname (name) + Get protocol entry by name.
getprotobynumber (proto) + Get protocol entry by number.
getpw (user) + (POSIX) Get all or a specific user account.
getsp (user) + (Linux, Solaris) Get all or a specific shadow password entry.
getuid () + (POSIX) Get the user id of the current process.
kill (target, signal) + (POSIX) Send a signal to one or more processes.
nanosleep (seconds, nanoseconds) + Sleep for a specified amount of time.
nice (nice) + (POSIX) Change priority of current process.
open (path, flags, mode) + Open a file.
open_flags (flag1, ...) + Generate flags for a call to open().
openlog (ident, flag1, ...) + (POSIX) Open a connection to the system logger.
pipe () + Create a pipe.
poll (fds, timeout) + Wait for some event on a file descriptor.
poll_flags (mode1, ...) + Generate events-bitfield or parse revents-bitfield for poll.
sendfile (socket, file, length) + (POSIX) Send data from a file to a socket in kernel-space.
setenv (variable, value) + Set or unset a environment variable.
setgid (gid) + (POSIX) Set the group id of the current process.
setlogmask (priority) + (POSIX) Set the logmask of the system logger for current process.
setsid () + (POSIX) Create a new session and set the process group ID.
setuid (gid) + (POSIX) Set the user id of the current process.
signal (signal, handler) + Ignore or use set the default handler for a signal.
socket (domain, type) + Create a new socket.
splice (fdin, fdout, length, flags) + (Linux) Send data from / to a pipe in kernel-space.
splice_flags (flag1, ...) + (Linux) Generate a flag bitfield for a call to splice.
strerror (errno) + Get the error message for the corresponding error code.
sysinfo () + (Linux) Get overall system statistics.
syslog (priority) + (POSIX) Write a message to the system logger.
times () + (POSIX) Get process times.
tls (mode) + Create a new TLS context.
umask (mask) + Sets the file mode creation mask.
uname () + (POSIX) Get information about current system and kernel.
waitpid (pid, flag1, ...) + (POSIX) Wait for a process to change state.
+ + + + + + +
+
+ + +

Functions

+
+ + + +
bind (host, port, family, socktype)
+
+ + Create a new socket and bind it to a network address. + This function is a shortcut for calling nixio.socket and then bind() + on the socket object. + + +

Parameters

+
    + +
  • + host: Hostname or IP-Address (optional, default: all addresses) +
    • + +
  • + port: Port or service description +
    • + +
  • + family: Address family ["any", "inet", "inet6"] +
    • + +
  • + socktype: Socket Type ["stream", "dgram"] +
    • + +
+ + + + +

Usage

+
    + +
  • This functions calls getaddrinfo(), socket(), + setsockopt() and bind() but NOT listen(). + +
  • The reuseaddr-option is automatically set before binding. + +
+ + + +

Return value:

+Socket Object + + + +
+ + + + +
chdir (path)
+
+ + Change the working directory. + + +

Parameters

+
    + +
  • + path: New working directory +
    • + +
+ + + + + + +

Return value:

+true + + + +
+ + + + +
closelog ()
+
+ + (POSIX) Close the connection to the system logger. + + + + + + + + + +
+ + + + +
connect (host, port, family, socktype)
+
+ + Create a new socket and connect to a network address. + This function is a shortcut for calling nixio.socket and then connect() + on the socket object. + + +

Parameters

+
    + +
  • + host: Hostname or IP-Address (optional, default: localhost) +
    • + +
  • + port: Port or service description +
    • + +
  • + family: Address family ["any", "inet", "inet6"] +
    • + +
  • + socktype: Socket Type ["stream", "dgram"] +
    • + +
+ + + + +

Usage:

+This functions calls getaddrinfo(), socket() and connect(). + + + +

Return value:

+Socket Object + + + +
+ + + + +
crypt (key, salt)
+
+ + (POSIX) Encrypt a user password. + + +

Parameters

+
    + +
  • + key: Key +
    • + +
  • + salt: Salt +
    • + +
+ + + + + + +

Return value:

+password hash + + + +
+ + + + +
dup (oldfd, newfd)
+
+ + Duplicate a file descriptor. + + +

Parameters

+
    + +
  • + oldfd: Old descriptor [File Object, Socket Object (POSIX only)] +
    • + +
  • + newfd: New descriptor to serve as copy (optional) +
    • + +
+ + + + +

Usage:

+This funcation calls dup2() if newfd is set, otherwise dup(). + + + +

Return value:

+File Object of new descriptor + + + +
+ + + + +
errno ()
+
+ + Get the last system error code. + + + + + + + +

Return value:

+Error code + + + +
+ + + + +
exec (executable, ...)
+
+ + Execute a file to replace the current process. + + +

Parameters

+
    + +
  • + executable: Executable +
    • + +
  • + ...: Parameters +
    • + +
+ + + + +

Usage

+
    + +
  • The name of the executable is automatically passed as argv[0] + +
  • This function does not return on success. + +
+ + + + + +
+ + + + +
exece (executable, arguments, environment)
+
+ + Execute a file with a custom environment to replace the current process. + + +

Parameters

+
    + +
  • + executable: Executable +
    • + +
  • + arguments: Argument Table +
    • + +
  • + environment: Environment Table (optional) +
    • + +
+ + + + +

Usage

+
    + +
  • The name of the executable is automatically passed as argv[0] + +
  • This function does not return on success. + +
+ + + + + +
+ + + + +
execp (executable, ...)
+
+ + Invoke the shell and execute a file to replace the current process. + + +

Parameters

+
    + +
  • + executable: Executable +
    • + +
  • + ...: Parameters +
    • + +
+ + + + +

Usage

+
    + +
  • The name of the executable is automatically passed as argv[0] + +
  • This function does not return on success. + +
+ + + + + +
+ + + + +
fork ()
+
+ + (POSIX) Clone the current process. + + + + + + + +

Return value:

+the child process id for the parent process, 0 for the child process + + + +
+ + + + +
getaddrinfo (host, family, service)
+
+ + Look up a hostname and service via DNS. + + +

Parameters

+
    + +
  • + host: hostname to lookup (optional) +
    • + +
  • + family: address family ["any", "inet", "inet6"] +
    • + +
  • + service: service name or port (optional) +
    • + +
+ + + + + + +

Return value:

+Table containing one or more tables containing:
    +
  • family = ["inet", "inet6"]
    • +
  • socktype = ["stream", "dgram", "raw"]
    • +
  • address = Resolved IP-Address
    • +
  • port = Resolved Port (if service was given)
    • +
+ + + +
+ + + + +
getcwd ()
+
+ + Get the current working directory. + + + + + + + +

Return value:

+workign directory + + + +
+ + + + +
getenv (variable)
+
+ + Get the current environment table or a specific environment variable. + + +

Parameters

+
    + +
  • + variable: Variable (optional) +
    • + +
+ + + + + + +

Return value:

+environment table or single environment variable + + + +
+ + + + +
getgid ()
+
+ + (POSIX) Get the group id of the current process. + + + + + + + +

Return value:

+process group id + + + +
+ + + + +
getgr (group)
+
+ + (POSIX) Get all or a specific user group. + + +

Parameters

+
    + +
  • + group: Group ID or groupname (optional) +
    • + +
+ + + + + + +

Return value:

+Table containing:
    +
  • name = Group Name
    • +
  • gid = Group ID
    • +
  • passwd = Password
    • +
  • mem = {Member #1, Member #2, ...}
    • +
+ + + +
+ + + + +
getifaddrs ()
+
+ + (Linux, BSD) Get a list of available network interfaces and their addresses. + + + + + + + +

Return value:

+Table containing one or more tables containing:
    +
  • name = Interface Name
    • +
  • family = ["inet", "inet6", "packet"]
    • +
  • addr = Interface Address (IPv4, IPv6, MAC, ...)
    • +
  • broadaddr = Broadcast Address
    • +
  • dstaddr = Destination Address (Point-to-Point)
    • +
  • netmask = Netmask (if available)
    • +
  • prefix = Prefix (if available)
    • +
  • flags = Table of interface flags (up, multicast, loopback, ...)
    • +
  • data = Statistics (Linux, "packet"-family)
    • +
  • hatype = Hardware Type Identifier (Linix, "packet"-family)
    • +
  • ifindex = Interface Index (Linux, "packet"-family)
    • +
+ + + +
+ + + + +
getnameinfo (ipaddr)
+
+ + Reverse look up an IP-Address via DNS. + + +

Parameters

+
    + +
  • + ipaddr: IPv4 or IPv6-Address +
    • + +
+ + + + + + +

Return value:

+FQDN + + + +
+ + + + +
getpid ()
+
+ + Get the ID of the current process. + + + + + + + +

Return value:

+process id + + + +
+ + + + +
getppid ()
+
+ + (POSIX) Get the parent process id of the current process. + + + + + + + +

Return value:

+parent process id + + + +
+ + + + +
getproto (proto)
+
+ + Get all or a specifc proto entry. + + +

Parameters

+
    + +
  • + proto: protocol number or name to lookup (optional) +
    • + +
+ + + + + + +

Return value:

+Table (or if no parameter is given, a table of tables) + containing the following fields:
    +
  • name = Protocol Name
    • +
  • proto = Protocol Number
    • +
  • aliases = Table of alias names
    • +
+ + + +
+ + + + +
getprotobyname (name)
+
+ + Get protocol entry by name. + + +

Parameters

+
    + +
  • + name: protocol name to lookup +
    • + +
+ + + + +

Usage:

+This function returns nil if the given protocol is unknown. + + + +

Return value:

+Table containing the following fields:
    +
  • name = Protocol Name
    • +
  • proto = Protocol Number
    • +
  • aliases = Table of alias names
    • +
+ + + +
+ + + + +
getprotobynumber (proto)
+
+ + Get protocol entry by number. + + +

Parameters

+
    + +
  • + proto: protocol number to lookup +
    • + +
+ + + + +

Usage:

+This function returns nil if the given protocol is unknown. + + + +

Return value:

+Table containing the following fields:
    +
  • name = Protocol Name
    • +
  • proto = Protocol Number
    • +
  • aliases = Table of alias names
    • +
+ + + +
+ + + + +
getpw (user)
+
+ + (POSIX) Get all or a specific user account. + + +

Parameters

+
    + +
  • + user: User ID or username (optional) +
    • + +
+ + + + + + +

Return value:

+Table containing:
    +
  • name = Name
    • +
  • uid = ID
    • +
  • gid = Group ID
    • +
  • passwd = Password
    • +
  • dir = Home directory
    • +
  • gecos = Information
    • +
  • shell = Shell
    • +
+ + + +
+ + + + +
getsp (user)
+
+ + (Linux, Solaris) Get all or a specific shadow password entry. + + +

Parameters

+
    + +
  • + user: username (optional) +
    • + +
+ + + + + + +

Return value:

+Table containing:
    +
  • namp = Name
    • +
  • expire = Expiration Date
    • +
  • flag = Flags
    • +
  • inact = Inactivity Date
    • +
  • lstchg = Last change
    • +
  • max = Maximum
    • +
  • min = Minimum
    • +
  • warn = Warning
    • +
  • pwdp = Password Hash
    • +
+ + + +
+ + + + +
getuid ()
+
+ + (POSIX) Get the user id of the current process. + + + + + + + +

Return value:

+process user id + + + +
+ + + + +
kill (target, signal)
+
+ + (POSIX) Send a signal to one or more processes. + + +

Parameters

+
    + +
  • + target: Target process of process group. +
    • + +
  • + signal: Signal to send +
    • + +
+ + + + + + +

Return value:

+true + + + +
+ + + + +
nanosleep (seconds, nanoseconds)
+
+ + Sleep for a specified amount of time. + + +

Parameters

+
    + +
  • + seconds: Seconds to wait (optional) +
    • + +
  • + nanoseconds: Nanoseconds to wait (optional) +
    • + +
+ + + + +

Usage

+
    + +
  • Not all systems support nanosecond precision but you can expect + to have at least maillisecond precision. + +
  • This function is not signal-protected and may fail with EINTR. + +
+ + + +

Return value:

+true + + + +
+ + + + +
nice (nice)
+
+ + (POSIX) Change priority of current process. + + +

Parameters

+
    + +
  • + nice: Nice Value +
    • + +
+ + + + + + +

Return value:

+true + + + +
+ + + + +
open (path, flags, mode)
+
+ + Open a file. + + +

Parameters

+
    + +
  • + path: Filesystem path to open +
    • + +
  • + flags: Flag string or number (see open_flags). + ["r", "r+", "w", "w+", "a", "a+"] +
    • + +
  • + mode: File mode for newly created files (see chmod, umask). +
    • + +
+ + + + +

Usage:

+Although this function also supports the traditional fopen() + file flags it does not create a file stream but uses the open() syscall. + + + +

Return value:

+File Object + + + +

See also:

+ + +
+ + + + +
open_flags (flag1, ...)
+
+ + Generate flags for a call to open(). + + +

Parameters

+
    + +
  • + flag1: First Flag ["append", "creat", "excl", "nonblock", "ndelay", + "sync", "trunc", "rdonly", "wronly", "rdwr"] +
    • + +
  • + ...: More Flags [-"-] +
    • + +
+ + + + +

Usage

+
    + +
  • This function cannot fail and will never return nil. + +
  • The "nonblock" and "ndelay" flags are aliases. + +
  • The "nonblock", "ndelay" and "sync" flags are no-ops on Windows. + +
+ + + +

Return value:

+flag to be used as second paramter to open + + + +
+ + + + +
openlog (ident, flag1, ...)
+
+ + (POSIX) Open a connection to the system logger. + + +

Parameters

+
    + +
  • + ident: Identifier +
    • + +
  • + flag1: Flag 1 ["cons", "nowait", "pid", "perror", "ndelay", "odelay"] +
    • + +
  • + ...: More flags [-"-] +
    • + +
+ + + + + + + + +
+ + + + +
pipe ()
+
+ + Create a pipe. + + + + + + + +

Return values:

+
    + +
  1. File Object of the read end + +
  2. File Object of the write end + +
+ + + +
+ + + + +
poll (fds, timeout)
+
+ + Wait for some event on a file descriptor. + poll() sets the revents-field of the tables provided by fds to a bitfield + indicating the events that occured. + + +

Parameters

+
    + +
  • + fds: Table containing one or more tables containing
      +
    • fd = I/O Descriptor [Socket Object, File Object (POSIX)]
      • +
    • events = events to wait for (bitfield generated with poll_flags)
      • +
    +
    • + +
  • + timeout: Timeout in milliseconds +
    • + +
+ + + + +

Usage

+
    + +
  • This function works in-place on the provided table and only + writes the revents field, you can use other fields on your demand. + +
  • All metamethods on the tables provided as fds are ignored. + +
  • The revents-fields are not reset when the call times out. + You have to check the first return value to be 0 to handle this case. + +
  • If you want to wait on a TLS-Socket you have to use the underlying + socket instead. + +
  • On Windows poll is emulated through select(), can only be used + on socket descriptors and cannot take more than 64 descriptors per call. + +
  • This function is not signal-protected and may fail with EINTR. + +
+ + + +

Return values:

+
    + +
  1. number of ready IO descriptors + +
  2. the fds-table with revents-fields set + +
+ + + +

See also:

+ + +
+ + + + +
poll_flags (mode1, ...)
+
+ + Generate events-bitfield or parse revents-bitfield for poll. + + +

Parameters

+
    + +
  • + mode1: revents-Flag bitfield returned from poll to parse OR + ["in", "out", "err", "pri" (POSIX), "hup" (POSIX), "nval" (POSIX)] +
    • + +
  • + ...: More mode strings for generating the flag [-"-] +
    • + +
+ + + + + + +

Return value:

+table with boolean fields reflecting the mode parameter + OR bitfield to use for the events-Flag field + + + +

See also:

+ + +
+ + + + +
sendfile (socket, file, length)
+
+ + (POSIX) Send data from a file to a socket in kernel-space. + + +

Parameters

+
    + +
  • + socket: Socket Object +
    • + +
  • + file: File Object +
    • + +
  • + length: Amount of data to send (in Bytes). +
    • + +
+ + + + + + +

Return value:

+bytes sent + + + +
+ + + + +
setenv (variable, value)
+
+ + Set or unset a environment variable. + + +

Parameters

+
    + +
  • + variable: Variable +
    • + +
  • + value: Value (optional) +
    • + +
+ + + + +

Usage:

+The environment variable will be unset if value is ommited. + + + +

Return value:

+true + + + +
+ + + + +
setgid (gid)
+
+ + (POSIX) Set the group id of the current process. + + +

Parameters

+
    + +
  • + gid: New Group ID +
    • + +
+ + + + + + +

Return value:

+true + + + +
+ + + + +
setlogmask (priority)
+
+ + (POSIX) Set the logmask of the system logger for current process. + + +

Parameters

+
    + +
  • + priority: Priority ["emerg", "alert", "crit", "err", "warning", + "notice", "info", "debug"] +
    • + +
+ + + + + + + + +
+ + + + +
setsid ()
+
+ + (POSIX) Create a new session and set the process group ID. + + + + + + + +

Return value:

+session id + + + +
+ + + + +
setuid (gid)
+
+ + (POSIX) Set the user id of the current process. + + +

Parameters

+
    + +
  • + gid: New User ID +
    • + +
+ + + + + + +

Return value:

+true + + + +
+ + + + +
signal (signal, handler)
+
+ + Ignore or use set the default handler for a signal. + + +

Parameters

+
    + +
  • + signal: Signal +
    • + +
  • + handler: ["ign", "dfl"] +
    • + +
+ + + + + + +

Return value:

+true + + + +
+ + + + +
socket (domain, type)
+
+ + Create a new socket. + + +

Parameters

+
    + +
  • + domain: Domain ["inet", "inet6", "unix"] +
    • + +
  • + type: Type ["stream", "dgram", "raw"] +
    • + +
+ + + + + + +

Return value:

+Socket Object + + + +
+ + + + +
splice (fdin, fdout, length, flags)
+
+ + (Linux) Send data from / to a pipe in kernel-space. + + +

Parameters

+
    + +
  • + fdin: Input I/O descriptor +
    • + +
  • + fdout: Output I/O descriptor +
    • + +
  • + length: Amount of data to send (in Bytes). +
    • + +
  • + flags: (optional, bitfield generated by splice_flags) +
    • + +
+ + + + + + +

Return value:

+bytes sent + + + +

See also:

+ + +
+ + + + +
splice_flags (flag1, ...)
+
+ + (Linux) Generate a flag bitfield for a call to splice. + + +

Parameters

+
    + +
  • + flag1: First Flag ["move", "nonblock", "more"] +
    • + +
  • + ...: More flags [-"-] +
    • + +
+ + + + + + +

Return value:

+Flag bitfield + + + +

See also:

+ + +
+ + + + +
strerror (errno)
+
+ + Get the error message for the corresponding error code. + + +

Parameters

+
    + +
  • + errno: System error code +
    • + +
+ + + + + + +

Return value:

+Error message + + + +
+ + + + +
sysinfo ()
+
+ + (Linux) Get overall system statistics. + + + + + + + +

Return value:

+Table containing:
    +
  • uptime = system uptime in seconds
    • +
  • loads = {loadavg1, loadavg5, loadavg15}
    • +
  • totalram = total RAM
    • +
  • freeram = free RAM
    • +
  • sharedram = shared RAM
    • +
  • bufferram = buffered RAM
    • +
  • totalswap = total SWAP
    • +
  • freeswap = free SWAP
    • +
  • procs = number of running processes
    • +
+ + + +
+ + + + +
syslog (priority)
+
+ + (POSIX) Write a message to the system logger. + + +

Parameters

+
    + +
  • + priority: Priority ["emerg", "alert", "crit", "err", "warning", + "notice", "info", "debug"] +
    • + +
+ + + + + + + + +
+ + + + +
times ()
+
+ + (POSIX) Get process times. + + + + + + + +

Return value:

+Table containing:
    +
  • utime = user time
    • +
  • utime = system time
    • +
  • cutime = children user time
    • +
  • cstime = children system time
    • +
+ + + +
+ + + + +
tls (mode)
+
+ + Create a new TLS context. + + +

Parameters

+
    + +
  • + mode: TLS-Mode ["client", "server"] +
    • + +
+ + + + + + +

Return value:

+TLSContext Object + + + +
+ + + + +
umask (mask)
+
+ + Sets the file mode creation mask. + + +

Parameters

+
    + +
  • + mask: New creation mask (see chmod for format specifications) +
    • + +
+ + + + + + +

Return values:

+
    + +
  1. the old umask as decimal mode number + +
  2. the old umask as mode string + +
+ + + +
+ + + + +
uname ()
+
+ + (POSIX) Get information about current system and kernel. + + + + + + + +

Return value:

+Table containing:
    +
  • sysname = operating system
    • +
  • nodename = network name (usually hostname)
    • +
  • release = OS release
    • +
  • version = OS version
    • +
  • machine = hardware identifier
    • +
+ + + +
+ + + + +
waitpid (pid, flag1, ...)
+
+ + (POSIX) Wait for a process to change state. + + +

Parameters

+
    + +
  • + pid: Process ID (optional, default: any childprocess) +
    • + +
  • + flag1: Flag (optional) ["nohang", "untraced", "continued"] +
    • + +
  • + ...: More Flags [-"-] +
    • + +
+ + + + +

Usage:

+If the "nohang" is given this function becomes non-blocking. + + + +

Return values:

+
    + +
  1. process id of child or 0 if no child has changed state + +
  2. ["exited", "signaled", "stopped"] + +
  3. [exit code, terminate signal, stop signal] + +
+ + + +
+ + +
+ + + + + +
+ +
+ +
+

Valid XHTML 1.0!

+
+ +
+ +