documentation/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/nixio.html">nixio</a>
 131         </li>
 132
 133         <li>
 134                 <a href="../modules/nixio.CHANGELOG.html">nixio.CHANGELOG</a>
 135         </li>
 136
 137         <li>
 138                 <a href="../modules/nixio.CryptoHash.html">nixio.CryptoHash</a>
 139         </li>
 140
 141         <li>
 142                 <a href="../modules/nixio.File.html">nixio.File</a>
 143         </li>
 144
 145         <li><strong>nixio.README</strong></li>
 146
 147         <li>
 148                 <a href="../modules/nixio.Socket.html">nixio.Socket</a>
 149         </li>
 150
 151         <li>
 152                 <a href="../modules/nixio.TLSContext.html">nixio.TLSContext</a>
 153         </li>
 154
 155         <li>
 156                 <a href="../modules/nixio.TLSSocket.html">nixio.TLSSocket</a>
 157         </li>
 158
 159         <li>
 160                 <a href="../modules/nixio.UnifiedIO.html">nixio.UnifiedIO</a>
 161         </li>
 162
 163         <li>
 164                 <a href="../modules/nixio.bin.html">nixio.bin</a>
 165         </li>
 166
 167         <li>
 168                 <a href="../modules/nixio.bit.html">nixio.bit</a>
 169         </li>
 170
 171         <li>
 172                 <a href="../modules/nixio.crypto.html">nixio.crypto</a>
 173         </li>
 174
 175         <li>
 176                 <a href="../modules/nixio.fs.html">nixio.fs</a>
 177         </li>
 178
 179 </ul>
 180
 181
 182
 183 <!-- File list -->
 184
 185
 186
 187
 188
 189
 190
 191 </div><!-- id="navigation" -->
 192
 193 <div id="content">
 194
 195 <h1>Class <code>nixio.README</code></h1>
 196
 197 <p>
 198  General Information.</p>
 199
 200
 201
 202
 203
 204
 205
 206
 207
 208
 209 <h2>Tables</h2>
 210 <table class="table_list">
 211
 212         <tr>
 213         <td class="name" nowrap><a href="#Errorhandling">Errorhandling</a></td>
 214         <td class="summary">
 215  General error handling information.</td>
 216         </tr>
 217
 218         <tr>
 219         <td class="name" nowrap><a href="#Functions">Functions</a></td>
 220         <td class="summary">
 221  Function conventions.</td>
 222         </tr>
 223
 224         <tr>
 225         <td class="name" nowrap><a href="#Platforms">Platforms</a></td>
 226         <td class="summary">
 227  Platform information.</td>
 228         </tr>
 229
 230         <tr>
 231         <td class="name" nowrap><a href="#TLS-Crypto">TLS-Crypto</a></td>
 232         <td class="summary">
 233  Cryptography and TLS libraries.</td>
 234         </tr>
 235
 236 </table>
 237
 238
 239
 240 <br/>
 241 <br/>
 242
 243
 244
 245
 246 <h2><a name="tables"></a>Tables</h2>
 247 <dl class="table">
 248
 249 <dt><a name="Errorhandling"></a><strong>Errorhandling</strong></dt>
 250 <dd>
 251  General error handling information.
 252  <ul>
 253  <li> Most of the functions available in this library may fail. If any error
 254  occurs the function returns <strong>nil or false</strong>, an error code
 255  (usually errno) and an additional error message text (if avaialable).</li>
 256  <li>At the moment false is only returned when a non-blocking I/O function
 257  fails with EAGAIN, EWOULDBLOCK or WSAEWOULDBLOCK for any others nil is
 258  returned as first parameter. Therefore you can use false to write portable
 259  non-blocking I/O applications.</li>
 260  <li>Note that the function documentation does only mention the return values
 261  in case of a successful operation.</li>
 262  <li>You can find a table of common error numbers and other useful constants
 263  like signal numbers in <strong>nixio.const</strong> e.g. nixio.const.EINVAL,
 264  nixio.const.SIGTERM, etc. For portability there is a second error constant
 265  table <strong>nixio.const_sock</strong> for socket error codes. This might
 266  be important if you are dealing with Windows applications, on POSIX however
 267  const_sock is just an alias for const.</li>
 268  <li>With some exceptions - which are explicitly stated in the function
 269  documentation - all blocking functions are signal-protected and will not fail
 270  with EINTR.</li>
 271  <li>On POSIX the SIGPIPE signal will be set to ignore upon initialization.
 272  You should restore the default behaviour or set a custom signal handler
 273  in your program after loading nixio if you need this behaviour.</li>
 274  </ul>
 275
 276
 277
 278 </dd>
 279
 280
 281 <dt><a name="Functions"></a><strong>Functions</strong></dt>
 282 <dd>
 283  Function conventions.
 284  <br />In general all functions are namend and behave like their POSIX API
 285  counterparts - where applicable - applying the following rules:
 286  <ul>
 287  <li>Functions should be named like the underlying POSIX API function omitting
 288  prefixes or suffixes - especially when placed in an object-context (
 289  lockf -> File:lock, fsync -> File:sync, dup2 -> dup, ...)</li>
 290  <li>If you are unclear about the behaviour of a function you should consult
 291  your OS API documentation (e.g. the manpages).</li>
 292  <li>If the name is significantly different from the POSIX-function, the
 293  underlying function(s) are stated in the documentation.</li>
 294  <li>Parameters should reflect those of the C-API, buffer length arguments and
 295  by-reference parameters should be omitted for practical purposes.</li>
 296  <li>If a C function accepts a bitfield as parameter, it should be translated
 297  into lower case string flags representing the flags if the bitfield is the
 298  last parameter and also omitting prefixes or suffixes. (e.g.  waitpid
 299  (pid, &s, WNOHANG | WUNTRACED) -> waitpid(pid, "nohang", "untraced"),
 300  getsockopt(fd, SOL_SOCKET, SO_REUSEADDR, &opt, sizeof(opt)) ->
 301  Socket:getopt("socket", "reuseaddr"), etc.) </li>
 302  <li>If it is not applicable to provide a string representation of the
 303  bitfield a bitfield generator helper is provided. It is named FUNCTION_flags.
 304  (open("/tmp/test", O_RDONLY | O_NONBLOCK) -> open("/tmp/test", open_flags(
 305  "rdonly", "nonblock")))</li>
 306  </ul>
 307
 308
 309
 310 </dd>
 311
 312
 313 <dt><a name="Platforms"></a><strong>Platforms</strong></dt>
 314 <dd>
 315  Platform information.
 316  <ul>
 317  <li>The minimum platform requirements are a decent POSIX 2001 support.
 318  Builds are more or less tested on Linux, Solaris and FreeBSD. Builds for
 319  Windows XP SP1 and later can be compiled with MinGW either from Windows
 320  itself or using the MinGW cross-compiler. Earlier versions of Windows are not
 321  supported.</li>
 322  <li>In general all functions which don't have any remarks
 323  in their documentation are available on all platforms.</li>
 324  <li>Functions with a (POSIX), (Linux) or similar prefix are only available
 325  on these specific platforms. Same appplies to parameters of functions
 326  with a similar suffix.</li>
 327  <li>Some functions might have limitations on some platforms. This should
 328  be stated in the documentation. Please also consult your OS API
 329  documentation.</li>
 330  </ul>
 331
 332
 333
 334 </dd>
 335
 336
 337 <dt><a name="TLS-Crypto"></a><strong>TLS-Crypto</strong></dt>
 338 <dd>
 339  Cryptography and TLS libraries.
 340  <ul>
 341  <li>Currently 3 underlying cryptography libraries are supported: openssl,
 342  cyassl and axTLS. The name of the library in use is written to
 343  <strong>nixio.tls_provider</strong></li>
 344  <li>You should whenever possible use openssl or cyassl as axTLS has only
 345  limited support. It does not provide support for non-blocking sockets and
 346  is probably less audited than the other ones.</li>
 347  <li>As the supported Windows versions are not suitable for embedded devices
 348  axTLS is at the moment not supported on Windows.</li>
 349  </ul>
 350
 351
 352
 353 </dd>
 354
 355
 356 </dl>
 357
 358
 359
 360 </div> <!-- id="content" -->
 361
 362 </div> <!-- id="main" -->
 363
 364 <div id="about">
 365         <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>
 366 </div> <!-- id="about" -->
 367
 368 </div> <!-- id="container" -->
 369 </body>
 370 </html>