docs/api/modules/nixio.README.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
   2    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html>
   4 <head>
   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"/-->
   8 </head>
   9
  10 <body>
  11 <div id="container">
  12
  13 <div id="product">
  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" -->
  18
  19 <div id="main">
  20
  21 <div id="navigation">
  22
  23
  24 <h1>LuaDoc</h1>
  25 <ul>
  26
  27         <li><a href="../index.html">Index</a></li>
  28
  29 </ul>
  30
  31
  32 <!-- Module list -->
  33
  34 <h1>Modules</h1>
  35 <ul>
  36
  37         <li>
  38                 <a href="../modules/luci.dispatcher.html">luci.dispatcher</a>
  39         </li>
  40
  41         <li>
  42                 <a href="../modules/luci.http.html">luci.http</a>
  43         </li>
  44
  45         <li>
  46                 <a href="../modules/luci.http.conditionals.html">luci.http.conditionals</a>
  47         </li>
  48
  49         <li>
  50                 <a href="../modules/luci.http.date.html">luci.http.date</a>
  51         </li>
  52
  53         <li>
  54                 <a href="../modules/luci.http.mime.html">luci.http.mime</a>
  55         </li>
  56
  57         <li>
  58                 <a href="../modules/luci.i18n.html">luci.i18n</a>
  59         </li>
  60
  61         <li>
  62                 <a href="../modules/luci.ip.html">luci.ip</a>
  63         </li>
  64
  65         <li>
  66                 <a href="../modules/luci.ip.cidr.html">luci.ip.cidr</a>
  67         </li>
  68
  69         <li>
  70                 <a href="../modules/luci.json.html">luci.json</a>
  71         </li>
  72
  73         <li>
  74                 <a href="../modules/luci.jsonc.html">luci.jsonc</a>
  75         </li>
  76
  77         <li>
  78                 <a href="../modules/luci.jsonc.parser.html">luci.jsonc.parser</a>
  79         </li>
  80
  81         <li>
  82                 <a href="../modules/luci.model.ipkg.html">luci.model.ipkg</a>
  83         </li>
  84
  85         <li>
  86                 <a href="../modules/luci.model.uci.html">luci.model.uci</a>
  87         </li>
  88
  89         <li>
  90                 <a href="../modules/luci.rpcc.html">luci.rpcc</a>
  91         </li>
  92
  93         <li>
  94                 <a href="../modules/luci.rpcc.ruci.html">luci.rpcc.ruci</a>
  95         </li>
  96
  97         <li>
  98                 <a href="../modules/luci.sys.html">luci.sys</a>
  99         </li>
 100
 101         <li>
 102                 <a href="../modules/luci.sys.init.html">luci.sys.init</a>
 103         </li>
 104
 105         <li>
 106                 <a href="../modules/luci.sys.iptparser.html">luci.sys.iptparser</a>
 107         </li>
 108
 109         <li>
 110                 <a href="../modules/luci.sys.net.html">luci.sys.net</a>
 111         </li>
 112
 113         <li>
 114                 <a href="../modules/luci.sys.process.html">luci.sys.process</a>
 115         </li>
 116
 117         <li>
 118                 <a href="../modules/luci.sys.user.html">luci.sys.user</a>
 119         </li>
 120
 121         <li>
 122                 <a href="../modules/luci.sys.wifi.html">luci.sys.wifi</a>
 123         </li>
 124
 125         <li>
 126                 <a href="../modules/luci.util.html">luci.util</a>
 127         </li>
 128
 129         <li>
 130                 <a href="../modules/luci.xml.html">luci.xml</a>
 131         </li>
 132
 133         <li>
 134                 <a href="../modules/nixio.html">nixio</a>
 135         </li>
 136
 137         <li>
 138                 <a href="../modules/nixio.CHANGELOG.html">nixio.CHANGELOG</a>
 139         </li>
 140
 141         <li>
 142                 <a href="../modules/nixio.CryptoHash.html">nixio.CryptoHash</a>
 143         </li>
 144
 145         <li>
 146                 <a href="../modules/nixio.File.html">nixio.File</a>
 147         </li>
 148
 149         <li><strong>nixio.README</strong></li>
 150
 151         <li>
 152                 <a href="../modules/nixio.Socket.html">nixio.Socket</a>
 153         </li>
 154
 155         <li>
 156                 <a href="../modules/nixio.TLSContext.html">nixio.TLSContext</a>
 157         </li>
 158
 159         <li>
 160                 <a href="../modules/nixio.TLSSocket.html">nixio.TLSSocket</a>
 161         </li>
 162
 163         <li>
 164                 <a href="../modules/nixio.UnifiedIO.html">nixio.UnifiedIO</a>
 165         </li>
 166
 167         <li>
 168                 <a href="../modules/nixio.bin.html">nixio.bin</a>
 169         </li>
 170
 171         <li>
 172                 <a href="../modules/nixio.bit.html">nixio.bit</a>
 173         </li>
 174
 175         <li>
 176                 <a href="../modules/nixio.crypto.html">nixio.crypto</a>
 177         </li>
 178
 179         <li>
 180                 <a href="../modules/nixio.fs.html">nixio.fs</a>
 181         </li>
 182
 183 </ul>
 184
 185
 186
 187 <!-- File list -->
 188
 189
 190
 191
 192
 193
 194
 195 </div><!-- id="navigation" -->
 196
 197 <div id="content">
 198
 199 <h1>Class <code>nixio.README</code></h1>
 200
 201 <p>
 202  General Information.</p>
 203
 204
 205
 206
 207
 208
 209
 210
 211
 212
 213 <h2>Tables</h2>
 214 <table class="table_list">
 215
 216         <tr>
 217         <td class="name" nowrap><a href="#Errorhandling">Errorhandling</a></td>
 218         <td class="summary">
 219  General error handling information.</td>
 220         </tr>
 221
 222         <tr>
 223         <td class="name" nowrap><a href="#Functions">Functions</a></td>
 224         <td class="summary">
 225  Function conventions.</td>
 226         </tr>
 227
 228         <tr>
 229         <td class="name" nowrap><a href="#Platforms">Platforms</a></td>
 230         <td class="summary">
 231  Platform information.</td>
 232         </tr>
 233
 234         <tr>
 235         <td class="name" nowrap><a href="#TLS-Crypto">TLS-Crypto</a></td>
 236         <td class="summary">
 237  Cryptography and TLS libraries.</td>
 238         </tr>
 239
 240 </table>
 241
 242
 243
 244 <br/>
 245 <br/>
 246
 247
 248
 249
 250 <h2><a name="tables"></a>Tables</h2>
 251 <dl class="table">
 252
 253 <dt><a name="Errorhandling"></a><strong>Errorhandling</strong></dt>
 254 <dd>
 255  General error handling information.
 256  <ul>
 257  <li> Most of the functions available in this library may fail. If any error
 258  occurs the function returns <strong>nil or false</strong>, an error code
 259  (usually errno) and an additional error message text (if avaialable).</li>
 260  <li>At the moment false is only returned when a non-blocking I/O function
 261  fails with EAGAIN, EWOULDBLOCK or WSAEWOULDBLOCK for any others nil is
 262  returned as first parameter. Therefore you can use false to write portable
 263  non-blocking I/O applications.</li>
 264  <li>Note that the function documentation does only mention the return values
 265  in case of a successful operation.</li>
 266  <li>You can find a table of common error numbers and other useful constants
 267  like signal numbers in <strong>nixio.const</strong> e.g. nixio.const.EINVAL,
 268  nixio.const.SIGTERM, etc. For portability there is a second error constant
 269  table <strong>nixio.const_sock</strong> for socket error codes. This might
 270  be important if you are dealing with Windows applications, on POSIX however
 271  const_sock is just an alias for const.</li>
 272  <li>With some exceptions - which are explicitly stated in the function
 273  documentation - all blocking functions are signal-protected and will not fail
 274  with EINTR.</li>
 275  <li>On POSIX the SIGPIPE signal will be set to ignore upon initialization.
 276  You should restore the default behaviour or set a custom signal handler
 277  in your program after loading nixio if you need this behaviour.</li>
 278  </ul>
 279
 280
 281
 282 </dd>
 283
 284
 285 <dt><a name="Functions"></a><strong>Functions</strong></dt>
 286 <dd>
 287  Function conventions.
 288  <br />In general all functions are namend and behave like their POSIX API
 289  counterparts - where applicable - applying the following rules:
 290  <ul>
 291  <li>Functions should be named like the underlying POSIX API function omitting
 292  prefixes or suffixes - especially when placed in an object-context (
 293  lockf -> File:lock, fsync -> File:sync, dup2 -> dup, ...)</li>
 294  <li>If you are unclear about the behaviour of a function you should consult
 295  your OS API documentation (e.g. the manpages).</li>
 296  <li>If the name is significantly different from the POSIX-function, the
 297  underlying function(s) are stated in the documentation.</li>
 298  <li>Parameters should reflect those of the C-API, buffer length arguments and
 299  by-reference parameters should be omitted for practical purposes.</li>
 300  <li>If a C function accepts a bitfield as parameter, it should be translated
 301  into lower case string flags representing the flags if the bitfield is the
 302  last parameter and also omitting prefixes or suffixes. (e.g.  waitpid
 303  (pid, &s, WNOHANG | WUNTRACED) -> waitpid(pid, "nohang", "untraced"),
 304  getsockopt(fd, SOL_SOCKET, SO_REUSEADDR, &opt, sizeof(opt)) ->
 305  Socket:getopt("socket", "reuseaddr"), etc.) </li>
 306  <li>If it is not applicable to provide a string representation of the
 307  bitfield a bitfield generator helper is provided. It is named FUNCTION_flags.
 308  (open("/tmp/test", O_RDONLY | O_NONBLOCK) -> open("/tmp/test", open_flags(
 309  "rdonly", "nonblock")))</li>
 310  </ul>
 311
 312
 313
 314 </dd>
 315
 316
 317 <dt><a name="Platforms"></a><strong>Platforms</strong></dt>
 318 <dd>
 319  Platform information.
 320  <ul>
 321  <li>The minimum platform requirements are a decent POSIX 2001 support.
 322  Builds are more or less tested on Linux, Solaris and FreeBSD. Builds for
 323  Windows XP SP1 and later can be compiled with MinGW either from Windows
 324  itself or using the MinGW cross-compiler. Earlier versions of Windows are not
 325  supported.</li>
 326  <li>In general all functions which don't have any remarks
 327  in their documentation are available on all platforms.</li>
 328  <li>Functions with a (POSIX), (Linux) or similar prefix are only available
 329  on these specific platforms. Same appplies to parameters of functions
 330  with a similar suffix.</li>
 331  <li>Some functions might have limitations on some platforms. This should
 332  be stated in the documentation. Please also consult your OS API
 333  documentation.</li>
 334  </ul>
 335
 336
 337
 338 </dd>
 339
 340
 341 <dt><a name="TLS-Crypto"></a><strong>TLS-Crypto</strong></dt>
 342 <dd>
 343  Cryptography and TLS libraries.
 344  <ul>
 345  <li>Currently 3 underlying cryptography libraries are supported: openssl,
 346  cyassl and axTLS. The name of the library in use is written to
 347  <strong>nixio.tls_provider</strong></li>
 348  <li>You should whenever possible use openssl or cyassl as axTLS has only
 349  limited support. It does not provide support for non-blocking sockets and
 350  is probably less audited than the other ones.</li>
 351  <li>As the supported Windows versions are not suitable for embedded devices
 352  axTLS is at the moment not supported on Windows.</li>
 353  </ul>
 354
 355
 356
 357 </dd>
 358
 359
 360 </dl>
 361
 362
 363
 364 </div> <!-- id="content" -->
 365
 366 </div> <!-- id="main" -->
 367
 368 <div id="about">
 369         <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>
 370 </div> <!-- id="about" -->
 371
 372 </div> <!-- id="container" -->
 373 </body>
 374 </html>