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.protocol.html">luci.http.protocol</a>
  43         </li>
  44
  45         <li>
  46                 <a href="../modules/luci.http.protocol.conditionals.html">luci.http.protocol.conditionals</a>
  47         </li>
  48
  49         <li>
  50                 <a href="../modules/luci.http.protocol.date.html">luci.http.protocol.date</a>
  51         </li>
  52
  53         <li>
  54                 <a href="../modules/luci.http.protocol.mime.html">luci.http.protocol.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.jsonc.html">luci.jsonc</a>
  71         </li>
  72
  73         <li>
  74                 <a href="../modules/luci.jsonc.parser.html">luci.jsonc.parser</a>
  75         </li>
  76
  77         <li>
  78                 <a href="../modules/luci.sys.init.html">luci.sys.init</a>
  79         </li>
  80
  81         <li>
  82                 <a href="../modules/luci.sys.iptparser.html">luci.sys.iptparser</a>
  83         </li>
  84
  85         <li>
  86                 <a href="../modules/luci.sys.net.html">luci.sys.net</a>
  87         </li>
  88
  89         <li>
  90                 <a href="../modules/luci.sys.process.html">luci.sys.process</a>
  91         </li>
  92
  93         <li>
  94                 <a href="../modules/luci.sys.user.html">luci.sys.user</a>
  95         </li>
  96
  97         <li>
  98                 <a href="../modules/luci.sys.wifi.html">luci.sys.wifi</a>
  99         </li>
 100
 101         <li>
 102                 <a href="../modules/nixio.html">nixio</a>
 103         </li>
 104
 105         <li>
 106                 <a href="../modules/nixio.CHANGELOG.html">nixio.CHANGELOG</a>
 107         </li>
 108
 109         <li>
 110                 <a href="../modules/nixio.CryptoHash.html">nixio.CryptoHash</a>
 111         </li>
 112
 113         <li>
 114                 <a href="../modules/nixio.File.html">nixio.File</a>
 115         </li>
 116
 117         <li><strong>nixio.README</strong></li>
 118
 119         <li>
 120                 <a href="../modules/nixio.Socket.html">nixio.Socket</a>
 121         </li>
 122
 123         <li>
 124                 <a href="../modules/nixio.TLSContext.html">nixio.TLSContext</a>
 125         </li>
 126
 127         <li>
 128                 <a href="../modules/nixio.TLSSocket.html">nixio.TLSSocket</a>
 129         </li>
 130
 131         <li>
 132                 <a href="../modules/nixio.UnifiedIO.html">nixio.UnifiedIO</a>
 133         </li>
 134
 135         <li>
 136                 <a href="../modules/nixio.bin.html">nixio.bin</a>
 137         </li>
 138
 139         <li>
 140                 <a href="../modules/nixio.bit.html">nixio.bit</a>
 141         </li>
 142
 143         <li>
 144                 <a href="../modules/nixio.crypto.html">nixio.crypto</a>
 145         </li>
 146
 147         <li>
 148                 <a href="../modules/nixio.fs.html">nixio.fs</a>
 149         </li>
 150
 151 </ul>
 152
 153
 154
 155 <!-- File list -->
 156
 157
 158
 159
 160
 161
 162
 163 </div><!-- id="navigation" -->
 164
 165 <div id="content">
 166
 167 <h1>Class <code>nixio.README</code></h1>
 168
 169 <p>
 170  General Information.</p>
 171
 172
 173
 174
 175
 176
 177
 178
 179
 180
 181 <h2>Tables</h2>
 182 <table class="table_list">
 183
 184         <tr>
 185         <td class="name" nowrap><a href="#Errorhandling">Errorhandling</a></td>
 186         <td class="summary">
 187  General error handling information.</td>
 188         </tr>
 189
 190         <tr>
 191         <td class="name" nowrap><a href="#Functions">Functions</a></td>
 192         <td class="summary">
 193  Function conventions.</td>
 194         </tr>
 195
 196         <tr>
 197         <td class="name" nowrap><a href="#Platforms">Platforms</a></td>
 198         <td class="summary">
 199  Platform information.</td>
 200         </tr>
 201
 202         <tr>
 203         <td class="name" nowrap><a href="#TLS-Crypto">TLS-Crypto</a></td>
 204         <td class="summary">
 205  Cryptography and TLS libraries.</td>
 206         </tr>
 207
 208 </table>
 209
 210
 211
 212 <br/>
 213 <br/>
 214
 215
 216
 217
 218 <h2><a name="tables"></a>Tables</h2>
 219 <dl class="table">
 220
 221 <dt><a name="Errorhandling"></a><strong>Errorhandling</strong></dt>
 222 <dd>
 223  General error handling information.
 224  <ul>
 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
 242  with EINTR.</li>
 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>
 246  </ul>
 247
 248
 249
 250 </dd>
 251
 252
 253 <dt><a name="Functions"></a><strong>Functions</strong></dt>
 254 <dd>
 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:
 258  <ul>
 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>
 278  </ul>
 279
 280
 281
 282 </dd>
 283
 284
 285 <dt><a name="Platforms"></a><strong>Platforms</strong></dt>
 286 <dd>
 287  Platform information.
 288  <ul>
 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
 293  supported.</li>
 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
 301  documentation.</li>
 302  </ul>
 303
 304
 305
 306 </dd>
 307
 308
 309 <dt><a name="TLS-Crypto"></a><strong>TLS-Crypto</strong></dt>
 310 <dd>
 311  Cryptography and TLS libraries.
 312  <ul>
 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>
 321  </ul>
 322
 323
 324
 325 </dd>
 326
 327
 328 </dl>
 329
 330
 331
 332 </div> <!-- id="content" -->
 333
 334 </div> <!-- id="main" -->
 335
 336 <div id="about">
 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" -->
 339
 340 </div> <!-- id="container" -->
 341 </body>
 342 </html>