documentation/api/modules/luci.sys.process.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><strong>luci.sys.process</strong></li>
 114
 115         <li>
 116                 <a href="../modules/luci.sys.user.html">luci.sys.user</a>
 117         </li>
 118
 119         <li>
 120                 <a href="../modules/luci.sys.wifi.html">luci.sys.wifi</a>
 121         </li>
 122
 123         <li>
 124                 <a href="../modules/luci.util.html">luci.util</a>
 125         </li>
 126
 127         <li>
 128                 <a href="../modules/nixio.html">nixio</a>
 129         </li>
 130
 131         <li>
 132                 <a href="../modules/nixio.CHANGELOG.html">nixio.CHANGELOG</a>
 133         </li>
 134
 135         <li>
 136                 <a href="../modules/nixio.CryptoHash.html">nixio.CryptoHash</a>
 137         </li>
 138
 139         <li>
 140                 <a href="../modules/nixio.File.html">nixio.File</a>
 141         </li>
 142
 143         <li>
 144                 <a href="../modules/nixio.README.html">nixio.README</a>
 145         </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>luci.sys.process</code></h1>
 196
 197 <p>
 198
 199 LuCI system utilities / process related functions.
 200 </p>
 201
 202
 203
 204
 205
 206
 207
 208 <h2>Functions</h2>
 209 <table class="function_list">
 210
 211         <tr>
 212         <td class="name" nowrap><a href="#process.exec">exec</a>&nbsp;(commend, stdout, stderr, nowait)</td>
 213         <td class="summary">
 214
 215 Execute a process, optionally capturing stdio.</td>
 216         </tr>
 217
 218         <tr>
 219         <td class="name" nowrap><a href="#process.info">info</a>&nbsp;()</td>
 220         <td class="summary">
 221
 222 Get the current process id.</td>
 223         </tr>
 224
 225         <tr>
 226         <td class="name" nowrap><a href="#process.list">list</a>&nbsp;()</td>
 227         <td class="summary">
 228
 229 Retrieve information about currently running processes.</td>
 230         </tr>
 231
 232         <tr>
 233         <td class="name" nowrap><a href="#process.setgroup">setgroup</a>&nbsp;(gid)</td>
 234         <td class="summary">
 235
 236 Set the gid of a process identified by given pid.</td>
 237         </tr>
 238
 239         <tr>
 240         <td class="name" nowrap><a href="#process.setuser">setuser</a>&nbsp;(uid)</td>
 241         <td class="summary">
 242
 243 Set the uid of a process identified by given pid.</td>
 244         </tr>
 245
 246         <tr>
 247         <td class="name" nowrap><a href="#process.signal">signal</a>&nbsp;(pid, sig)</td>
 248         <td class="summary">
 249
 250 Send a signal to a process identified by given pid.</td>
 251         </tr>
 252
 253 </table>
 254
 255
 256
 257
 258
 259
 260 <br/>
 261 <br/>
 262
 263
 264 <h2><a name="functions"></a>Functions</h2>
 265 <dl class="function">
 266
 267
 268
 269 <dt><a name="process.exec"></a><strong>exec</strong>&nbsp;(commend, stdout, stderr, nowait)</dt>
 270 <dd>
 271
 272
 273 Execute a process, optionally capturing stdio.
 274
 275 Executes the process specified by the given argv vector, e.g.
 276 <code>{ "/bin/sh", "-c", "echo 1" }</code> and waits for it to terminate unless a true
 277 value has been passed for the "nowait" parameter.
 278
 279 When a function value is passed for the stdout or stderr arguments, the passed
 280 function is repeatedly called for each chunk read from the corresponding stdio
 281 stream. The read data is passed as string containing at most 4096 bytes at a
 282 time.
 283
 284 When a true, non-function value is passed for the stdout or stderr arguments,
 285 the data of the corresponding stdio stream is read into an internal string
 286 buffer and returned as "stdout" or "stderr" field respectively in the result
 287 table.
 288
 289 When a true value is passed to the nowait parameter, the function does not
 290 await process termination but returns as soon as all captured stdio streams
 291 have been closed or - if no streams are captured - immediately after launching
 292 the process.
 293
 294
 295
 296 <h3>Parameters</h3>
 297 <ul>
 298
 299         <li>
 300           commend: Table containing the argv vector to execute
 301         </li>
 302
 303         <li>
 304           stdout: Callback function or boolean to indicate capturing (optional)
 305         </li>
 306
 307         <li>
 308           stderr: Callback function or boolean to indicate capturing (optional)
 309         </li>
 310
 311         <li>
 312           nowait: Don't wait for process termination when true (optional)
 313         </li>
 314
 315 </ul>
 316
 317
 318
 319
 320
 321
 322 <h3>Return value:</h3>
 323 Table containing at least the fields "code" which holds the exit
 324             status of the invoked process or "-1" on error and "pid", which
 325             contains the process id assigned to the spawned process. When
 326             stdout and/or stderr capturing has been requested, it additionally
 327             contains "stdout" and "stderr" fields respectively, holding the
 328             captured stdio data as string.
 329
 330
 331
 332 </dd>
 333
 334
 335
 336
 337 <dt><a name="process.info"></a><strong>info</strong>&nbsp;()</dt>
 338 <dd>
 339
 340
 341 Get the current process id.
 342
 343
 344
 345
 346
 347
 348
 349
 350 <h3>Return value:</h3>
 351 Number containing the current pid
 352
 353
 354
 355 </dd>
 356
 357
 358
 359
 360 <dt><a name="process.list"></a><strong>list</strong>&nbsp;()</dt>
 361 <dd>
 362
 363
 364 Retrieve information about currently running processes.
 365
 366
 367
 368
 369
 370
 371
 372
 373 <h3>Return value:</h3>
 374 Table containing process information
 375
 376
 377
 378 </dd>
 379
 380
 381
 382
 383 <dt><a name="process.setgroup"></a><strong>setgroup</strong>&nbsp;(gid)</dt>
 384 <dd>
 385
 386
 387 Set the gid of a process identified by given pid.
 388
 389
 390
 391 <h3>Parameters</h3>
 392 <ul>
 393
 394         <li>
 395           gid: Number containing the Unix group id
 396         </li>
 397
 398 </ul>
 399
 400
 401
 402
 403
 404
 405 <h3>Return values:</h3>
 406 <ol>
 407
 408         <li>Boolean indicating successful operation
 409
 410         <li>String containing the error message if failed
 411
 412         <li>Number containing the error code if failed
 413
 414 </ol>
 415
 416
 417
 418 </dd>
 419
 420
 421
 422
 423 <dt><a name="process.setuser"></a><strong>setuser</strong>&nbsp;(uid)</dt>
 424 <dd>
 425
 426
 427 Set the uid of a process identified by given pid.
 428
 429
 430
 431 <h3>Parameters</h3>
 432 <ul>
 433
 434         <li>
 435           uid: Number containing the Unix user id
 436         </li>
 437
 438 </ul>
 439
 440
 441
 442
 443
 444
 445 <h3>Return values:</h3>
 446 <ol>
 447
 448         <li>Boolean indicating successful operation
 449
 450         <li>String containing the error message if failed
 451
 452         <li>Number containing the error code if failed
 453
 454 </ol>
 455
 456
 457
 458 </dd>
 459
 460
 461
 462
 463 <dt><a name="process.signal"></a><strong>signal</strong>&nbsp;(pid, sig)</dt>
 464 <dd>
 465
 466
 467 Send a signal to a process identified by given pid.
 468
 469
 470
 471 <h3>Parameters</h3>
 472 <ul>
 473
 474         <li>
 475           pid: Number containing the process id
 476         </li>
 477
 478         <li>
 479           sig: Signal to send (default: 15 [SIGTERM])
 480         </li>
 481
 482 </ul>
 483
 484
 485
 486
 487
 488
 489 <h3>Return values:</h3>
 490 <ol>
 491
 492         <li>Boolean indicating successful operation
 493
 494         <li>Number containing the error code if failed
 495
 496 </ol>
 497
 498
 499
 500 </dd>
 501
 502
 503 </dl>
 504
 505
 506
 507
 508
 509 </div> <!-- id="content" -->
 510
 511 </div> <!-- id="main" -->
 512
 513 <div id="about">
 514         <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>
 515 </div> <!-- id="about" -->
 516
 517 </div> <!-- id="container" -->
 518 </body>
 519 </html>