1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
5 <title>Reference</title>
6 <link rel="stylesheet" href="../luadoc.css" type="text/css" />
7 <!--meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/-->
14 <div id="product_logo"></div>
15 <div id="product_name"><big><b></b></big></div>
16 <div id="product_description"></div>
17 </div> <!-- id="product" -->
27 <li><a href="../index.html">Index</a></li>
38 <a href="../modules/luci.dispatcher.html">luci.dispatcher</a>
42 <a href="../modules/luci.http.protocol.html">luci.http.protocol</a>
46 <a href="../modules/luci.http.protocol.conditionals.html">luci.http.protocol.conditionals</a>
50 <a href="../modules/luci.http.protocol.date.html">luci.http.protocol.date</a>
54 <a href="../modules/luci.http.protocol.mime.html">luci.http.protocol.mime</a>
58 <a href="../modules/luci.i18n.html">luci.i18n</a>
62 <a href="../modules/luci.ip.html">luci.ip</a>
66 <a href="../modules/luci.ip.cidr.html">luci.ip.cidr</a>
70 <a href="../modules/luci.jsonc.html">luci.jsonc</a>
74 <a href="../modules/luci.jsonc.parser.html">luci.jsonc.parser</a>
78 <a href="../modules/luci.sys.init.html">luci.sys.init</a>
82 <a href="../modules/luci.sys.iptparser.html">luci.sys.iptparser</a>
86 <a href="../modules/luci.sys.net.html">luci.sys.net</a>
90 <a href="../modules/luci.sys.process.html">luci.sys.process</a>
94 <a href="../modules/luci.sys.user.html">luci.sys.user</a>
98 <a href="../modules/luci.sys.wifi.html">luci.sys.wifi</a>
102 <a href="../modules/nixio.html">nixio</a>
106 <a href="../modules/nixio.CHANGELOG.html">nixio.CHANGELOG</a>
110 <a href="../modules/nixio.CryptoHash.html">nixio.CryptoHash</a>
114 <a href="../modules/nixio.File.html">nixio.File</a>
117 <li><strong>nixio.README</strong></li>
120 <a href="../modules/nixio.Socket.html">nixio.Socket</a>
124 <a href="../modules/nixio.TLSContext.html">nixio.TLSContext</a>
128 <a href="../modules/nixio.TLSSocket.html">nixio.TLSSocket</a>
132 <a href="../modules/nixio.UnifiedIO.html">nixio.UnifiedIO</a>
136 <a href="../modules/nixio.bin.html">nixio.bin</a>
140 <a href="../modules/nixio.bit.html">nixio.bit</a>
144 <a href="../modules/nixio.crypto.html">nixio.crypto</a>
148 <a href="../modules/nixio.fs.html">nixio.fs</a>
163 </div><!-- id="navigation" -->
167 <h1>Class <code>nixio.README</code></h1>
170 General Information.</p>
182 <table class="table_list">
185 <td class="name" nowrap><a href="#Errorhandling">Errorhandling</a></td>
187 General error handling information.</td>
191 <td class="name" nowrap><a href="#Functions">Functions</a></td>
193 Function conventions.</td>
197 <td class="name" nowrap><a href="#Platforms">Platforms</a></td>
199 Platform information.</td>
203 <td class="name" nowrap><a href="#TLS-Crypto">TLS-Crypto</a></td>
205 Cryptography and TLS libraries.</td>
218 <h2><a name="tables"></a>Tables</h2>
221 <dt><a name="Errorhandling"></a><strong>Errorhandling</strong></dt>
223 General error handling information.
225 <li> Most of the functions available in this library may fail. If any error
226 occurs the function returns <strong>nil or false</strong>, an error code
227 (usually errno) and an additional error message text (if avaialable).</li>
228 <li>At the moment false is only returned when a non-blocking I/O function
229 fails with EAGAIN, EWOULDBLOCK or WSAEWOULDBLOCK for any others nil is
230 returned as first parameter. Therefore you can use false to write portable
231 non-blocking I/O applications.</li>
232 <li>Note that the function documentation does only mention the return values
233 in case of a successful operation.</li>
234 <li>You can find a table of common error numbers and other useful constants
235 like signal numbers in <strong>nixio.const</strong> e.g. nixio.const.EINVAL,
236 nixio.const.SIGTERM, etc. For portability there is a second error constant
237 table <strong>nixio.const_sock</strong> for socket error codes. This might
238 be important if you are dealing with Windows applications, on POSIX however
239 const_sock is just an alias for const.</li>
240 <li>With some exceptions - which are explicitely stated in the function
241 documentation - all blocking functions are signal-protected and will not fail
243 <li>On POSIX the SIGPIPE signal will be set to ignore upon initialization.
244 You should restore the default behaviour or set a custom signal handler
245 in your program after loading nixio if you need this behaviour.</li>
253 <dt><a name="Functions"></a><strong>Functions</strong></dt>
255 Function conventions.
256 <br />In general all functions are namend and behave like their POSIX API
257 counterparts - where applicable - applying the following rules:
259 <li>Functions should be named like the underlying POSIX API function ommiting
260 prefixes or suffixes - especially when placed in an object-context (
261 lockf -> File:lock, fsync -> File:sync, dup2 -> dup, ...)</li>
262 <li>If you are unclear about the behaviour of a function you should consult
263 your OS API documentation (e.g. the manpages).</li>
264 <li>If the name is significantly different from the POSIX-function, the
265 underlying function(s) are stated in the documentation.</li>
266 <li>Parameters should reflect those of the C-API, buffer length arguments and
267 by-reference parameters should be ommitted for pratical purposes.</li>
268 <li>If a C function accepts a bitfield as parameter, it should be translated
269 into lower case string flags representing the flags if the bitfield is the
270 last parameter and also ommiting prefixes or suffixes. (e.g. waitpid
271 (pid, &s, WNOHANG | WUNTRACED) -> waitpid(pid, "nohang", "untraced"),
272 getsockopt(fd, SOL_SOCKET, SO_REUSEADDR, &opt, sizeof(opt)) ->
273 Socket:getopt("socket", "reuseaddr"), etc.) </li>
274 <li>If it is not applicable to provide a string representation of the
275 bitfield a bitfield generator helper is provided. It is named FUNCTION_flags.
276 (open("/tmp/test", O_RDONLY | O_NONBLOCK) -> open("/tmp/test", open_flags(
277 "rdonly", "nonblock")))</li>
285 <dt><a name="Platforms"></a><strong>Platforms</strong></dt>
287 Platform information.
289 <li>The minimum platform requirements are a decent POSIX 2001 support.
290 Builds are more or less tested on Linux, Solaris and FreeBSD. Builds for
291 Windows XP SP1 and later can be compiled with MinGW either from Windows
292 itself or using the MinGW cross-compiler. Earlier versions of Windows are not
294 <li>In general all functions which don't have any remarks
295 in their documentation are available on all platforms.</li>
296 <li>Functions with a (POSIX), (Linux) or similar prefix are only available
297 on these specific platforms. Same appplies to parameters of functions
298 with a similar suffix.</li>
299 <li>Some functions might have limitations on some platforms. This should
300 be stated in the documentation. Please also consult your OS API
309 <dt><a name="TLS-Crypto"></a><strong>TLS-Crypto</strong></dt>
311 Cryptography and TLS libraries.
313 <li>Currently 3 underlying cryptography libraries are supported: openssl,
314 cyassl and axTLS. The name of the library in use is written to
315 <strong>nixio.tls_provider</strong></li>
316 <li>You should whenever possible use openssl or cyassl as axTLS has only
317 limited support. It does not provide support for non-blocking sockets and
318 is probably less audited than the other ones.</li>
319 <li>As the supported Windows versions are not suitable for embedded devices
320 axTLS is at the moment not supported on Windows.</li>
332 </div> <!-- id="content" -->
334 </div> <!-- id="main" -->
337 <p><a href="http://validator.w3.org/check?uri=referer"><img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0!" height="31" width="88" /></a></p>
338 </div> <!-- id="about" -->
340 </div> <!-- id="container" -->