aboutsummaryrefslogtreecommitdiff
path: root/docs/modules/system.html
diff options
context:
space:
mode:
Diffstat (limited to 'docs/modules/system.html')
-rw-r--r--docs/modules/system.html1418
1 files changed, 1418 insertions, 0 deletions
diff --git a/docs/modules/system.html b/docs/modules/system.html
new file mode 100644
index 0000000..0423e37
--- /dev/null
+++ b/docs/modules/system.html
@@ -0,0 +1,1418 @@
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<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
5<head>
6 <title>Lua-System docs</title>
7 <link rel="stylesheet" href="../ldoc.css" type="text/css" />
8</head>
9<body>
10
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
20<div id="main">
21
22
23<!-- Menu -->
24
25<div id="navigation">
26<br/>
27<h1>Lua-System</h1>
28
29
30<ul>
31 <li><a href="../index.html">Index</a></li>
32</ul>
33
34<h2>Contents</h2>
35<ul>
36<li><a href="#Fields">Fields</a></li>
37<li><a href="#Environment">Environment </a></li>
38<li><a href="#Random">Random </a></li>
39<li><a href="#Terminal">Terminal </a></li>
40<li><a href="#Time">Time </a></li>
41</ul>
42
43
44<h2>Modules</h2>
45<ul class="nowrap">
46 <li><strong>system</strong></li>
47</ul>
48<h2>Classes</h2>
49<ul class="nowrap">
50 <li><a href="../classes/bitflags.html">bitflags</a></li>
51</ul>
52<h2>Topics</h2>
53<ul class="">
54 <li><a href="../topics/01-introduction.md.html">1. Introduction</a></li>
55 <li><a href="../topics/02-development.md.html">2. Development</a></li>
56 <li><a href="../topics/03-terminal.md.html">3. Terminal functionality</a></li>
57 <li><a href="../topics/CHANGELOG.md.html">CHANGELOG</a></li>
58 <li><a href="../topics/LICENSE.md.html">MIT License</a></li>
59</ul>
60<h2>Examples</h2>
61<ul class="nowrap">
62 <li><a href="../examples/compat.lua.html">compat.lua</a></li>
63 <li><a href="../examples/flag_debugging.lua.html">flag_debugging.lua</a></li>
64 <li><a href="../examples/password_input.lua.html">password_input.lua</a></li>
65 <li><a href="../examples/read.lua.html">read.lua</a></li>
66 <li><a href="../examples/readline.lua.html">readline.lua</a></li>
67 <li><a href="../examples/spinner.lua.html">spinner.lua</a></li>
68 <li><a href="../examples/spiral_snake.lua.html">spiral_snake.lua</a></li>
69 <li><a href="../examples/terminalsize.lua.html">terminalsize.lua</a></li>
70</ul>
71
72</div>
73
74<div id="content">
75
76<h1>Module <code>system</code></h1>
77<p>Platform independent system calls for Lua.</p>
78<p>
79
80</p>
81
82
83<h2><a href="#Fields">Fields</a></h2>
84<table class="function_list">
85 <tr>
86 <td class="name" nowrap><a href="#windows">windows</a></td>
87 <td class="summary">Flag to identify Windows.</td>
88 </tr>
89</table>
90<h2><a href="#Environment">Environment </a></h2>
91<table class="function_list">
92 <tr>
93 <td class="name" nowrap><a href="#getenv">getenv (name)</a></td>
94 <td class="summary">Gets the value of an environment variable.</td>
95 </tr>
96 <tr>
97 <td class="name" nowrap><a href="#getenvs">getenvs ()</a></td>
98 <td class="summary">Returns a table with all environment variables.</td>
99 </tr>
100 <tr>
101 <td class="name" nowrap><a href="#setenv">setenv (name[, value])</a></td>
102 <td class="summary">Sets an environment variable.</td>
103 </tr>
104</table>
105<h2><a href="#Random">Random </a></h2>
106<table class="function_list">
107 <tr>
108 <td class="name" nowrap><a href="#random">random ([length=1])</a></td>
109 <td class="summary">Generate random bytes.</td>
110 </tr>
111</table>
112<h2><a href="#Terminal">Terminal </a></h2>
113<table class="function_list">
114 <tr>
115 <td class="name" nowrap><a href="#CODEPAGE_UTF8">CODEPAGE_UTF8</a></td>
116 <td class="summary">UTF8 codepage.</td>
117 </tr>
118 <tr>
119 <td class="name" nowrap><a href="#_readkey">_readkey ()</a></td>
120 <td class="summary">Reads a key from the console non-blocking.</td>
121 </tr>
122 <tr>
123 <td class="name" nowrap><a href="#autotermrestore">autotermrestore ()</a></td>
124 <td class="summary">Backs up terminal settings and restores them on application exit.</td>
125 </tr>
126 <tr>
127 <td class="name" nowrap><a href="#getconsolecp">getconsolecp ()</a></td>
128 <td class="summary">Gets the current console code page (Windows).</td>
129 </tr>
130 <tr>
131 <td class="name" nowrap><a href="#getconsoleflags">getconsoleflags (file)</a></td>
132 <td class="summary">Gets console flags (Windows).</td>
133 </tr>
134 <tr>
135 <td class="name" nowrap><a href="#getconsoleoutputcp">getconsoleoutputcp ()</a></td>
136 <td class="summary">Gets the current console output code page (Windows).</td>
137 </tr>
138 <tr>
139 <td class="name" nowrap><a href="#getnonblock">getnonblock (fd)</a></td>
140 <td class="summary">Gets non-blocking mode status for a file (Posix).</td>
141 </tr>
142 <tr>
143 <td class="name" nowrap><a href="#isatty">isatty (file)</a></td>
144 <td class="summary">Checks if a file-handle is a TTY.</td>
145 </tr>
146 <tr>
147 <td class="name" nowrap><a href="#listconsoleflags">listconsoleflags (fh)</a></td>
148 <td class="summary">Debug function for console flags (Windows).</td>
149 </tr>
150 <tr>
151 <td class="name" nowrap><a href="#listtermflags">listtermflags (fh)</a></td>
152 <td class="summary">Debug function for terminal flags (Posix).</td>
153 </tr>
154 <tr>
155 <td class="name" nowrap><a href="#readansi">readansi (timeout)</a></td>
156 <td class="summary">Reads a single key, if it is the start of ansi escape sequence then it reads
157 the full sequence.</td>
158 </tr>
159 <tr>
160 <td class="name" nowrap><a href="#readkey">readkey (timeout)</a></td>
161 <td class="summary">Reads a single byte from the console, with a timeout.</td>
162 </tr>
163 <tr>
164 <td class="name" nowrap><a href="#setconsolecp">setconsolecp (cp)</a></td>
165 <td class="summary">Sets the current console code page (Windows).</td>
166 </tr>
167 <tr>
168 <td class="name" nowrap><a href="#setconsoleflags">setconsoleflags (file, bitflags)</a></td>
169 <td class="summary">Sets the console flags (Windows).</td>
170 </tr>
171 <tr>
172 <td class="name" nowrap><a href="#setconsoleoutputcp">setconsoleoutputcp (cp)</a></td>
173 <td class="summary">Sets the current console output code page (Windows).</td>
174 </tr>
175 <tr>
176 <td class="name" nowrap><a href="#setnonblock">setnonblock (fd, make_non_block)</a></td>
177 <td class="summary">Enables or disables non-blocking mode for a file (Posix).</td>
178 </tr>
179 <tr>
180 <td class="name" nowrap><a href="#tcgetattr">tcgetattr (fd)</a></td>
181 <td class="summary">Get termios state (Posix).</td>
182 </tr>
183 <tr>
184 <td class="name" nowrap><a href="#tcsetattr">tcsetattr (fd, actions, termios)</a></td>
185 <td class="summary">Set termios state (Posix).</td>
186 </tr>
187 <tr>
188 <td class="name" nowrap><a href="#termbackup">termbackup ()</a></td>
189 <td class="summary">Returns a backup of terminal settings for stdin/out/err.</td>
190 </tr>
191 <tr>
192 <td class="name" nowrap><a href="#termrestore">termrestore (backup)</a></td>
193 <td class="summary">Restores terminal settings from a backup</td>
194 </tr>
195 <tr>
196 <td class="name" nowrap><a href="#termsize">termsize ()</a></td>
197 <td class="summary">Get the size of the terminal in rows and columns.</td>
198 </tr>
199 <tr>
200 <td class="name" nowrap><a href="#termwrap">termwrap (f)</a></td>
201 <td class="summary">Wraps a function to automatically restore terminal settings upon returning.</td>
202 </tr>
203 <tr>
204 <td class="name" nowrap><a href="#utf8cwidth">utf8cwidth (utf8_char)</a></td>
205 <td class="summary">Get the width of a utf8 character for terminal display.</td>
206 </tr>
207 <tr>
208 <td class="name" nowrap><a href="#utf8swidth">utf8swidth (utf8_string)</a></td>
209 <td class="summary">Get the width of a utf8 string for terminal display.</td>
210 </tr>
211</table>
212<h2><a href="#Time">Time </a></h2>
213<table class="function_list">
214 <tr>
215 <td class="name" nowrap><a href="#gettime">gettime ()</a></td>
216 <td class="summary">Get system time.</td>
217 </tr>
218 <tr>
219 <td class="name" nowrap><a href="#monotime">monotime ()</a></td>
220 <td class="summary">Get monotonic time.</td>
221 </tr>
222 <tr>
223 <td class="name" nowrap><a href="#sleep">sleep (seconds[, precision=16])</a></td>
224 <td class="summary">Sleep without a busy loop.</td>
225 </tr>
226</table>
227
228<br/>
229<br/>
230
231
232 <h2 class="section-header "><a name="Fields"></a>Fields</h2>
233
234 <dl class="function">
235 <dt>
236 <a name = "windows"></a>
237 <strong>windows</strong>
238 </dt>
239 <dd>
240 Flag to identify Windows.
241
242
243 <ul>
244 <li><span class="parameter">windows</span>
245 <code>true</code> if on Windows, <code>false</code> otherwise.
246 </li>
247 </ul>
248
249
250
251
252
253</dd>
254</dl>
255 <h2 class="section-header "><a name="Environment"></a>Environment </h2>
256
257 <dl class="function">
258 <dt>
259 <a name = "getenv"></a>
260 <strong>getenv (name)</strong>
261 </dt>
262 <dd>
263 Gets the value of an environment variable. </p>
264
265<p><strong>NOTE</strong>: Windows has multiple copies of environment variables. For this reason,
266the <a href="../modules/system.html#setenv">setenv</a> function will not work with Lua's <a href="https://www.lua.org/manual/5.4/manual.html#pdf-os.getenv">os.getenv</a> on Windows. If you want
267to use <a href="../modules/system.html#setenv">setenv</a> then consider patching <a href="https://www.lua.org/manual/5.4/manual.html#pdf-os.getenv">os.getenv</a> with this implementation of <a href="../modules/system.html#getenv">getenv</a>.
268
269
270 <h3>Parameters:</h3>
271 <ul>
272 <li><span class="parameter">name</span>
273 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
274 name of the environment variable
275 </li>
276 </ul>
277
278 <h3>Returns:</h3>
279 <ol>
280
281 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a> or <span class="type">nil</span></span>
282 value of the environment variable, or nil if the variable is not set
283 </ol>
284
285
286
287
288</dd>
289 <dt>
290 <a name = "getenvs"></a>
291 <strong>getenvs ()</strong>
292 </dt>
293 <dd>
294 Returns a table with all environment variables.
295
296
297
298 <h3>Returns:</h3>
299 <ol>
300
301 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.6">table</a></span>
302 table with all environment variables and their values
303 </ol>
304
305
306
307
308</dd>
309 <dt>
310 <a name = "setenv"></a>
311 <strong>setenv (name[, value])</strong>
312 </dt>
313 <dd>
314 Sets an environment variable. </p>
315
316<p><strong>NOTE</strong>: Windows has multiple copies of environment variables. For this reason, the
317<a href="../modules/system.html#setenv">setenv</a> function will not work with Lua's <a href="https://www.lua.org/manual/5.4/manual.html#pdf-os.getenv">os.getenv</a> on Windows. If you want to use
318it then consider patching <a href="https://www.lua.org/manual/5.4/manual.html#pdf-os.getenv">os.getenv</a> with the implementation of <a href="../modules/system.html#getenv">system.getenv</a>.
319
320
321 <h3>Parameters:</h3>
322 <ul>
323 <li><span class="parameter">name</span>
324 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
325 name of the environment variable
326 </li>
327 <li><span class="parameter">value</span>
328 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
329 value of the environment variable, if <code>nil</code> the variable will be deleted (on
330Windows, setting an empty string, will also delete the variable)
331 (<em>optional</em>)
332 </li>
333 </ul>
334
335 <h3>Returns:</h3>
336 <ol>
337
338 <span class="types"><span class="type">boolean</span></span>
339 success
340 </ol>
341
342
343
344
345</dd>
346</dl>
347 <h2 class="section-header "><a name="Random"></a>Random </h2>
348
349 <dl class="function">
350 <dt>
351 <a name = "random"></a>
352 <strong>random ([length=1])</strong>
353 </dt>
354 <dd>
355 Generate random bytes.
356This uses <code>CryptGenRandom()</code> on Windows, and <code>/dev/urandom</code> on other platforms. It will return the
357requested number of bytes, or an error, never a partial result.
358
359
360 <h3>Parameters:</h3>
361 <ul>
362 <li><span class="parameter">length</span>
363 <span class="types"><span class="type">int</span></span>
364 number of bytes to get
365 (<em>default</em> 1)
366 </li>
367 </ul>
368
369 <h3>Returns:</h3>
370 <ol>
371
372 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
373 string of random bytes
374 </ol>
375 <h3>Or</h3>
376 <ol>
377 <li>
378 <span class="types"><span class="type">nil</span></span>
379
380
381</li>
382 <li>
383 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
384 error message</li>
385 </ol>
386
387
388
389
390</dd>
391</dl>
392 <h2 class="section-header has-description"><a name="Terminal"></a>Terminal </h2>
393
394 <div class="section-description">
395 Unix: see https://blog.nelhage.com/2009/12/a-brief-introduction-to-termios-termios3-and-stty/</p>
396
397<p> Windows: see https://learn.microsoft.com/en-us/windows/console/console-reference
398 </div>
399 <dl class="function">
400 <dt>
401 <a name = "CODEPAGE_UTF8"></a>
402 <strong>CODEPAGE_UTF8</strong>
403 </dt>
404 <dd>
405 UTF8 codepage.
406 To be used with <a href="../modules/system.html#setconsoleoutputcp">system.setconsoleoutputcp</a> and <a href="../modules/system.html#setconsolecp">system.setconsolecp</a>.
407
408
409 <ul>
410 <li><span class="parameter">CODEPAGE_UTF8</span>
411 The Windows CodePage for UTF8.
412 </li>
413 </ul>
414
415
416
417
418
419</dd>
420 <dt>
421 <a name = "_readkey"></a>
422 <strong>_readkey ()</strong>
423 </dt>
424 <dd>
425 Reads a key from the console non-blocking. This function should not be called
426directly, but through the <a href="../modules/system.html#readkey">system.readkey</a> or <a href="../modules/system.html#readansi">system.readansi</a> functions. It
427will return the next byte from the input stream, or <code>nil</code> if no key was pressed.</p>
428
429<p>On Posix, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdin">io.stdin</a> must be set to non-blocking mode using <a href="../modules/system.html#setnonblock">setnonblock</a>
430and canonical mode must be turned off using <a href="../modules/system.html#tcsetattr">tcsetattr</a>,
431before calling this function. Otherwise it will block. No conversions are
432done on Posix, so the byte read is returned as-is.</p>
433
434<p>On Windows this reads a wide character and converts it to UTF-8. Multi-byte
435sequences will be buffered internally and returned one byte at a time.
436
437
438
439 <h3>Returns:</h3>
440 <ol>
441
442 <span class="types"><span class="type">integer</span></span>
443 the byte read from the input stream
444 </ol>
445 <h3>Or</h3>
446 <ol>
447
448 <span class="types"><span class="type">nil</span></span>
449 if no key was pressed
450 </ol>
451 <h3>Or</h3>
452 <ol>
453 <li>
454 <span class="types"><span class="type">nil</span></span>
455 on error</li>
456 <li>
457 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
458 error message</li>
459 <li>
460 <span class="types"><span class="type">int</span></span>
461 errnum (on posix)</li>
462 </ol>
463
464
465
466
467</dd>
468 <dt>
469 <a name = "autotermrestore"></a>
470 <strong>autotermrestore ()</strong>
471 </dt>
472 <dd>
473 Backs up terminal settings and restores them on application exit.
474 Calls <a href="../modules/system.html#termbackup">termbackup</a> to back up terminal settings and sets up a GC method to
475 automatically restore them on application exit (also works on Lua 5.1).
476
477
478
479 <h3>Returns:</h3>
480 <ol>
481
482 <span class="types"><span class="type">boolean</span></span>
483 true
484 </ol>
485 <h3>Or</h3>
486 <ol>
487 <li>
488 <span class="types"><span class="type">nil</span></span>
489 if the backup was already created</li>
490 <li>
491 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
492 error message</li>
493 </ol>
494
495
496
497
498</dd>
499 <dt>
500 <a name = "getconsolecp"></a>
501 <strong>getconsolecp ()</strong>
502 </dt>
503 <dd>
504 Gets the current console code page (Windows).
505
506
507
508 <h3>Returns:</h3>
509 <ol>
510
511 <span class="types"><span class="type">int</span></span>
512 the current code page (always 65001 on Posix systems)
513 </ol>
514
515
516
517
518</dd>
519 <dt>
520 <a name = "getconsoleflags"></a>
521 <strong>getconsoleflags (file)</strong>
522 </dt>
523 <dd>
524 Gets console flags (Windows).
525The <code>CIF_</code> and <code>COF_</code> constants are available on the module table. Where <code>CIF</code> are the
526input flags (for use with <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdin">io.stdin</a>) and <code>COF</code> are the output flags (for use with
527<a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdout">io.stdout</a>/<a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stderr">io.stderr</a>).</p>
528
529<p><em>Note</em>: See <a href="https://learn.microsoft.com/en-us/windows/console/setconsolemode">setconsolemode documentation</a>
530for more information on the flags.
531
532
533 <h3>Parameters:</h3>
534 <ul>
535 <li><span class="parameter">file</span>
536 <span class="types"><span class="type">file</span></span>
537 file handle to operate on, one of <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdin">io.stdin</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdout">io.stdout</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stderr">io.stderr</a>
538 </li>
539 </ul>
540
541 <h3>Returns:</h3>
542 <ol>
543
544 <span class="types"><a class="type" href="../classes/bitflags.html#">bitflags</a></span>
545 the current console flags.
546 </ol>
547 <h3>Or</h3>
548 <ol>
549 <li>
550 <span class="types"><span class="type">nil</span></span>
551
552
553</li>
554 <li>
555 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
556 error message</li>
557 </ol>
558
559
560
561 <h3>Usage:</h3>
562 <ul>
563 <pre class="example"><span class="keyword">local</span> system = <span class="global">require</span>(<span class="string">'system'</span>)
564
565<span class="keyword">local</span> flags = system.<span class="function-name">getconsoleflags</span>(<span class="global">io</span>.stdout)
566<span class="global">print</span>(<span class="string">"Current stdout flags:"</span>, <span class="global">tostring</span>(flags))
567
568<span class="keyword">if</span> flags:<span class="function-name">has_all_of</span>(system.COF_VIRTUAL_TERMINAL_PROCESSING + system.COF_PROCESSED_OUTPUT) <span class="keyword">then</span>
569 <span class="global">print</span>(<span class="string">"Both flags are set"</span>)
570<span class="keyword">else</span>
571 <span class="global">print</span>(<span class="string">"At least one flag is not set"</span>)
572<span class="keyword">end</span></pre>
573 </ul>
574
575</dd>
576 <dt>
577 <a name = "getconsoleoutputcp"></a>
578 <strong>getconsoleoutputcp ()</strong>
579 </dt>
580 <dd>
581 Gets the current console output code page (Windows).
582
583
584
585 <h3>Returns:</h3>
586 <ol>
587
588 <span class="types"><span class="type">int</span></span>
589 the current code page (always 65001 on Posix systems)
590 </ol>
591
592
593
594
595</dd>
596 <dt>
597 <a name = "getnonblock"></a>
598 <strong>getnonblock (fd)</strong>
599 </dt>
600 <dd>
601 Gets non-blocking mode status for a file (Posix).
602
603
604 <h3>Parameters:</h3>
605 <ul>
606 <li><span class="parameter">fd</span>
607 <span class="types"><span class="type">file</span></span>
608 file handle to operate on, one of <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdin">io.stdin</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdout">io.stdout</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stderr">io.stderr</a>
609 </li>
610 </ul>
611
612 <h3>Returns:</h3>
613 <ol>
614
615 <span class="types"><span class="type">bool</span></span>
616 <code>true</code> if set to non-blocking, <code>false</code> if not. Always returns <code>false</code> on Windows.
617 </ol>
618 <h3>Or</h3>
619 <ol>
620 <li>
621 <span class="types"><span class="type">nil</span></span>
622
623
624</li>
625 <li>
626 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
627 error message</li>
628 <li>
629 <span class="types"><span class="type">int</span></span>
630 errnum</li>
631 </ol>
632
633
634
635
636</dd>
637 <dt>
638 <a name = "isatty"></a>
639 <strong>isatty (file)</strong>
640 </dt>
641 <dd>
642 Checks if a file-handle is a TTY.
643
644
645 <h3>Parameters:</h3>
646 <ul>
647 <li><span class="parameter">file</span>
648 <span class="types"><span class="type">file</span></span>
649 the file-handle to check, one of <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdin">io.stdin</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdout">io.stdout</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stderr">io.stderr</a>.
650 </li>
651 </ul>
652
653 <h3>Returns:</h3>
654 <ol>
655
656 <span class="types"><span class="type">boolean</span></span>
657 true if the file is a tty
658 </ol>
659
660
661
662 <h3>Usage:</h3>
663 <ul>
664 <pre class="example"><span class="keyword">local</span> system = <span class="global">require</span>(<span class="string">'system'</span>)
665<span class="keyword">if</span> system.<span class="function-name">isatty</span>(<span class="global">io</span>.stdin) <span class="keyword">then</span>
666 <span class="comment">-- enable ANSI coloring etc on Windows, does nothing in Posix.
667</span> <span class="keyword">local</span> flags = system.<span class="function-name">getconsoleflags</span>(<span class="global">io</span>.stdout)
668 system.<span class="function-name">setconsoleflags</span>(<span class="global">io</span>.stdout, flags + sys.COF_VIRTUAL_TERMINAL_PROCESSING)
669<span class="keyword">end</span></pre>
670 </ul>
671
672</dd>
673 <dt>
674 <a name = "listconsoleflags"></a>
675 <strong>listconsoleflags (fh)</strong>
676 </dt>
677 <dd>
678 Debug function for console flags (Windows).
679 Pretty prints the current flags set for the handle.
680
681
682 <h3>Parameters:</h3>
683 <ul>
684 <li><span class="parameter">fh</span>
685 file handle (<a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdin">io.stdin</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdout">io.stdout</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stderr">io.stderr</a>)
686 </li>
687 </ul>
688
689
690
691
692 <h3>Usage:</h3>
693 <ul>
694 <pre class="example"><span class="comment">-- Print the flags for stdin/out/err
695</span>system.<span class="function-name">listconsoleflags</span>(<span class="global">io</span>.stdin)
696system.<span class="function-name">listconsoleflags</span>(<span class="global">io</span>.stdout)
697system.<span class="function-name">listconsoleflags</span>(<span class="global">io</span>.stderr)</pre>
698 </ul>
699
700</dd>
701 <dt>
702 <a name = "listtermflags"></a>
703 <strong>listtermflags (fh)</strong>
704 </dt>
705 <dd>
706 Debug function for terminal flags (Posix).
707 Pretty prints the current flags set for the handle.
708
709
710 <h3>Parameters:</h3>
711 <ul>
712 <li><span class="parameter">fh</span>
713 file handle (<a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdin">io.stdin</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdout">io.stdout</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stderr">io.stderr</a>)
714 </li>
715 </ul>
716
717
718
719
720 <h3>Usage:</h3>
721 <ul>
722 <pre class="example"><span class="comment">-- Print the flags for stdin/out/err
723</span>system.<span class="function-name">listconsoleflags</span>(<span class="global">io</span>.stdin)
724system.<span class="function-name">listconsoleflags</span>(<span class="global">io</span>.stdout)
725system.<span class="function-name">listconsoleflags</span>(<span class="global">io</span>.stderr)</pre>
726 </ul>
727
728</dd>
729 <dt>
730 <a name = "readansi"></a>
731 <strong>readansi (timeout)</strong>
732 </dt>
733 <dd>
734 Reads a single key, if it is the start of ansi escape sequence then it reads
735 the full sequence. The key can be a multi-byte string in case of multibyte UTF-8 character.
736 This function uses <a href="../modules/system.html#readkey">system.readkey</a>, and hence <a href="../modules/system.html#sleep">system.sleep</a> to wait until either a key is
737 available or the timeout is reached.
738 It returns immediately if a key is available or if <code>timeout</code> is less than or equal to <code>0</code>.
739 In case of an ANSI sequence, it will return the full sequence as a string.
740
741
742 <h3>Parameters:</h3>
743 <ul>
744 <li><span class="parameter">timeout</span>
745 <span class="types"><span class="type">number</span></span>
746 the timeout in seconds.
747 </li>
748 </ul>
749
750 <h3>Returns:</h3>
751 <ol>
752 <li>
753 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
754 the character that was received (can be multi-byte), or a complete ANSI sequence</li>
755 <li>
756 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
757 the type of input: <code>&quot;char&quot;</code> for a single key, <code>&quot;ansi&quot;</code> for an ANSI sequence</li>
758 </ol>
759 <h3>Or</h3>
760 <ol>
761 <li>
762 <span class="types"><span class="type">nil</span></span>
763 in case of an error</li>
764 <li>
765 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
766 error message; <code>&quot;timeout&quot;</code> if the timeout was reached.</li>
767 <li>
768 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
769 partial result in case of an error while reading a sequence, the sequence so far.</li>
770 </ol>
771
772
773
774
775</dd>
776 <dt>
777 <a name = "readkey"></a>
778 <strong>readkey (timeout)</strong>
779 </dt>
780 <dd>
781 Reads a single byte from the console, with a timeout.
782 This function uses <a href="../modules/system.html#sleep">system.sleep</a> to wait until either a byte is available or the timeout is reached.
783 The sleep period is exponentially backing off, starting at 0.0125 seconds, with a maximum of 0.2 seconds.
784 It returns immediately if a byte is available or if <code>timeout</code> is less than or equal to <code>0</code>.</p>
785
786<p> Using <a href="../modules/system.html#readansi">system.readansi</a> is preferred over this function. Since this function can leave stray/invalid
787 byte-sequences in the input buffer, while <a href="../modules/system.html#readansi">system.readansi</a> reads full ANSI and UTF8 sequences.
788
789
790 <h3>Parameters:</h3>
791 <ul>
792 <li><span class="parameter">timeout</span>
793 <span class="types"><span class="type">number</span></span>
794 the timeout in seconds.
795 </li>
796 </ul>
797
798 <h3>Returns:</h3>
799 <ol>
800
801 <span class="types"><span class="type">byte</span></span>
802 the byte value that was read.
803 </ol>
804 <h3>Or</h3>
805 <ol>
806 <li>
807 <span class="types"><span class="type">nil</span></span>
808 if no key was read</li>
809 <li>
810 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
811 error message; <code>&quot;timeout&quot;</code> if the timeout was reached.</li>
812 </ol>
813
814
815
816
817</dd>
818 <dt>
819 <a name = "setconsolecp"></a>
820 <strong>setconsolecp (cp)</strong>
821 </dt>
822 <dd>
823 Sets the current console code page (Windows).
824
825
826 <h3>Parameters:</h3>
827 <ul>
828 <li><span class="parameter">cp</span>
829 <span class="types"><span class="type">int</span></span>
830 the code page to set, use <a href="../modules/system.html#CODEPAGE_UTF8">system.CODEPAGE_UTF8</a> (65001) for UTF-8
831 </li>
832 </ul>
833
834 <h3>Returns:</h3>
835 <ol>
836
837 <span class="types"><span class="type">bool</span></span>
838 <code>true</code> on success (always <code>true</code> on Posix systems)
839 </ol>
840
841
842
843
844</dd>
845 <dt>
846 <a name = "setconsoleflags"></a>
847 <strong>setconsoleflags (file, bitflags)</strong>
848 </dt>
849 <dd>
850 Sets the console flags (Windows).
851The <code>CIF_</code> and <code>COF_</code> constants are available on the module table. Where <code>CIF</code> are the
852input flags (for use with <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdin">io.stdin</a>) and <code>COF</code> are the output flags (for use with
853<a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdout">io.stdout</a>/<a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stderr">io.stderr</a>).</p>
854
855<p>To see flag status and constant names check <a href="../modules/system.html#listconsoleflags">listconsoleflags</a>.</p>
856
857<p>Note: not all combinations of flags are allowed, as some are mutually exclusive or mutually required.
858See <a href="https://learn.microsoft.com/en-us/windows/console/setconsolemode">setconsolemode documentation</a>
859
860
861 <h3>Parameters:</h3>
862 <ul>
863 <li><span class="parameter">file</span>
864 <span class="types"><span class="type">file</span></span>
865 file handle to operate on, one of <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdin">io.stdin</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdout">io.stdout</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stderr">io.stderr</a>
866 </li>
867 <li><span class="parameter">bitflags</span>
868 <span class="types"><a class="type" href="../classes/bitflags.html#">bitflags</a></span>
869 the flags to set/unset
870 </li>
871 </ul>
872
873 <h3>Returns:</h3>
874 <ol>
875
876 <span class="types"><span class="type">boolean</span></span>
877 <code>true</code> on success
878 </ol>
879 <h3>Or</h3>
880 <ol>
881 <li>
882 <span class="types"><span class="type">nil</span></span>
883
884
885</li>
886 <li>
887 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
888 error message</li>
889 </ol>
890
891
892
893 <h3>Usage:</h3>
894 <ul>
895 <pre class="example"><span class="keyword">local</span> system = <span class="global">require</span>(<span class="string">'system'</span>)
896system.<span class="function-name">listconsoleflags</span>(<span class="global">io</span>.stdout) <span class="comment">-- List all the available flags and their current status
897</span>
898<span class="keyword">local</span> flags = system.<span class="function-name">getconsoleflags</span>(<span class="global">io</span>.stdout)
899<span class="global">assert</span>(system.<span class="function-name">setconsoleflags</span>(<span class="global">io</span>.stdout,
900 flags + system.COF_VIRTUAL_TERMINAL_PROCESSING)
901
902system.<span class="function-name">listconsoleflags</span>(<span class="global">io</span>.stdout) <span class="comment">-- List again to check the differences</span></pre>
903 </ul>
904
905</dd>
906 <dt>
907 <a name = "setconsoleoutputcp"></a>
908 <strong>setconsoleoutputcp (cp)</strong>
909 </dt>
910 <dd>
911 Sets the current console output code page (Windows).
912
913
914 <h3>Parameters:</h3>
915 <ul>
916 <li><span class="parameter">cp</span>
917 <span class="types"><span class="type">int</span></span>
918 the code page to set, use <a href="../modules/system.html#CODEPAGE_UTF8">system.CODEPAGE_UTF8</a> (65001) for UTF-8
919 </li>
920 </ul>
921
922 <h3>Returns:</h3>
923 <ol>
924
925 <span class="types"><span class="type">bool</span></span>
926 <code>true</code> on success (always <code>true</code> on Posix systems)
927 </ol>
928
929
930
931
932</dd>
933 <dt>
934 <a name = "setnonblock"></a>
935 <strong>setnonblock (fd, make_non_block)</strong>
936 </dt>
937 <dd>
938 Enables or disables non-blocking mode for a file (Posix).
939
940
941 <h3>Parameters:</h3>
942 <ul>
943 <li><span class="parameter">fd</span>
944 <span class="types"><span class="type">file</span></span>
945 file handle to operate on, one of <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdin">io.stdin</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdout">io.stdout</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stderr">io.stderr</a>
946 </li>
947 <li><span class="parameter">make_non_block</span>
948 <span class="types"><span class="type">boolean</span></span>
949 a truthy value will enable non-blocking mode, a falsy value will disable it.
950 </li>
951 </ul>
952
953 <h3>Returns:</h3>
954 <ol>
955
956 <span class="types"><span class="type">bool</span></span>
957 <code>true</code>, if successful
958 </ol>
959 <h3>Or</h3>
960 <ol>
961 <li>
962 <span class="types"><span class="type">nil</span></span>
963
964
965</li>
966 <li>
967 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
968 error message</li>
969 <li>
970 <span class="types"><span class="type">int</span></span>
971 errnum</li>
972 </ol>
973
974
975 <h3>See also:</h3>
976 <ul>
977 <a href="../modules/system.html#getnonblock">getnonblock</a>
978 </ul>
979
980 <h3>Usage:</h3>
981 <ul>
982 <pre class="example"><span class="keyword">local</span> sys = <span class="global">require</span>(<span class="string">'system'</span>)
983
984<span class="comment">-- set io.stdin to non-blocking mode
985</span><span class="keyword">local</span> old_setting = sys.<span class="function-name">getnonblock</span>(<span class="global">io</span>.stdin)
986sys.<span class="function-name">setnonblock</span>(<span class="global">io</span>.stdin, <span class="keyword">true</span>)
987
988<span class="comment">-- do stuff
989</span>
990<span class="comment">-- restore old setting
991</span>sys.<span class="function-name">setnonblock</span>(<span class="global">io</span>.stdin, old_setting)</pre>
992 </ul>
993
994</dd>
995 <dt>
996 <a name = "tcgetattr"></a>
997 <strong>tcgetattr (fd)</strong>
998 </dt>
999 <dd>
1000
1001<p>Get termios state (Posix).
1002The terminal attributes is a table with the following fields:</p>
1003
1004<ul>
1005 <li><code>iflag</code> input flags</li>
1006 <li><code>oflag</code> output flags</li>
1007 <li><code>lflag</code> local flags</li>
1008 <li><code>cflag</code> control flags</li>
1009 <li><code>ispeed</code> input speed</li>
1010 <li><code>ospeed</code> output speed</li>
1011 <li><code>cc</code> control characters</li>
1012</ul>
1013
1014
1015
1016
1017 <h3>Parameters:</h3>
1018 <ul>
1019 <li><span class="parameter">fd</span>
1020 <span class="types"><span class="type">file</span></span>
1021 file handle to operate on, one of <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdin">io.stdin</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdout">io.stdout</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stderr">io.stderr</a>
1022 </li>
1023 </ul>
1024
1025 <h3>Returns:</h3>
1026 <ol>
1027
1028 error message if failed
1029 </ol>
1030 <h3>Or</h3>
1031 <ol>
1032
1033 <span class="types"><span class="type">termios</span></span>
1034 terminal attributes, if successful. On Windows the bitflags are all 0, and the <code>cc</code> table is empty.
1035 </ol>
1036 <h3>Or</h3>
1037 <ol>
1038 <li>
1039 <span class="types"><span class="type">nil</span></span>
1040
1041
1042</li>
1043 <li>
1044 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
1045 error message</li>
1046 <li>
1047 <span class="types"><span class="type">int</span></span>
1048 errnum</li>
1049 </ol>
1050
1051
1052
1053 <h3>Usage:</h3>
1054 <ul>
1055 <pre class="example"><span class="keyword">local</span> system = <span class="global">require</span>(<span class="string">'system'</span>)
1056
1057<span class="keyword">local</span> status = <span class="global">assert</span>(<span class="function-name">tcgetattr</span>(<span class="global">io</span>.stdin))
1058<span class="keyword">if</span> status.iflag:<span class="function-name">has_all_of</span>(system.I_IGNBRK) <span class="keyword">then</span>
1059 <span class="global">print</span>(<span class="string">"Ignoring break condition"</span>)
1060<span class="keyword">end</span></pre>
1061 </ul>
1062
1063</dd>
1064 <dt>
1065 <a name = "tcsetattr"></a>
1066 <strong>tcsetattr (fd, actions, termios)</strong>
1067 </dt>
1068 <dd>
1069 Set termios state (Posix).
1070This function will set the flags as given.</p>
1071
1072<p>The <code>I_</code>, <code>O_</code>, and <code>L_</code> constants are available on the module table. They are the respective
1073flags for the <code>iflags</code>, <code>oflags</code>, and <code>lflags</code> bitmasks.</p>
1074
1075<p>To see flag status and constant names check <a href="../modules/system.html#listtermflags">listtermflags</a>. For their meaning check
1076<a href="https://www.man7.org/linux/man-pages/man3/termios.3.html">the manpage</a>.</p>
1077
1078<p><em>Note</em>: only <code>iflag</code>, <code>oflag</code>, and <code>lflag</code> are supported at the moment. The other fields are ignored.
1079
1080
1081 <h3>Parameters:</h3>
1082 <ul>
1083 <li><span class="parameter">fd</span>
1084 <span class="types"><span class="type">file</span></span>
1085 file handle to operate on, one of <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdin">io.stdin</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdout">io.stdout</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stderr">io.stderr</a>
1086 </li>
1087 <li><span class="parameter">actions</span>
1088 <span class="types"><span class="type">integer</span></span>
1089 one of <code>TCSANOW</code>, <code>TCSADRAIN</code>, <code>TCSAFLUSH</code>
1090 </li>
1091 <li><span class="parameter">termios</span> a table with bitflag fields:
1092 <ul>
1093 <li><span class="parameter">iflag</span>
1094 <span class="types"><a class="type" href="../classes/bitflags.html#">bitflags</a></span>
1095 if given will set the input flags
1096 (<em>optional</em>)
1097 </li>
1098 <li><span class="parameter">oflag</span>
1099 <span class="types"><a class="type" href="../classes/bitflags.html#">bitflags</a></span>
1100 if given will set the output flags
1101 (<em>optional</em>)
1102 </li>
1103 <li><span class="parameter">lflag</span>
1104 <span class="types"><a class="type" href="../classes/bitflags.html#">bitflags</a></span>
1105 if given will set the local flags
1106 (<em>optional</em>)
1107 </li>
1108 </li></ul>
1109 </ul>
1110
1111 <h3>Returns:</h3>
1112 <ol>
1113
1114 <span class="types"><span class="type">bool</span></span>
1115 <code>true</code>, if successful. Always returns <code>true</code> on Windows.
1116 </ol>
1117 <h3>Or</h3>
1118 <ol>
1119 <li>
1120 nil</li>
1121 <li>
1122 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
1123 error message</li>
1124 <li>
1125 <span class="types"><span class="type">int</span></span>
1126 errnum</li>
1127 </ol>
1128
1129
1130
1131 <h3>Usage:</h3>
1132 <ul>
1133 <pre class="example"><span class="keyword">local</span> system = <span class="global">require</span>(<span class="string">'system'</span>)
1134
1135<span class="keyword">local</span> status = <span class="global">assert</span>(<span class="function-name">tcgetattr</span>(<span class="global">io</span>.stdin))
1136<span class="keyword">if</span> <span class="keyword">not</span> status.lflag:<span class="function-name">has_all_of</span>(system.L_ECHO) <span class="keyword">then</span>
1137 <span class="comment">-- if echo is off, turn echoing newlines on
1138</span> <span class="function-name">tcsetattr</span>(<span class="global">io</span>.stdin, system.TCSANOW, { lflag = status.lflag + system.L_ECHONL }))
1139<span class="keyword">end</span></pre>
1140 </ul>
1141
1142</dd>
1143 <dt>
1144 <a name = "termbackup"></a>
1145 <strong>termbackup ()</strong>
1146 </dt>
1147 <dd>
1148 Returns a backup of terminal settings for stdin/out/err.
1149 Handles terminal/console flags, Windows codepage, and non-block flags on the streams.
1150 Backs up terminal/console flags only if a stream is a tty.
1151
1152
1153
1154 <h3>Returns:</h3>
1155 <ol>
1156
1157 table with backup of terminal settings
1158 </ol>
1159
1160
1161
1162
1163</dd>
1164 <dt>
1165 <a name = "termrestore"></a>
1166 <strong>termrestore (backup)</strong>
1167 </dt>
1168 <dd>
1169 Restores terminal settings from a backup
1170
1171
1172 <h3>Parameters:</h3>
1173 <ul>
1174 <li><span class="parameter">backup</span>
1175 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.6">table</a></span>
1176 the backup of terminal settings, see <a href="../modules/system.html#termbackup">termbackup</a>.
1177 </li>
1178 </ul>
1179
1180 <h3>Returns:</h3>
1181 <ol>
1182
1183 <span class="types"><span class="type">boolean</span></span>
1184 true
1185 </ol>
1186
1187
1188
1189
1190</dd>
1191 <dt>
1192 <a name = "termsize"></a>
1193 <strong>termsize ()</strong>
1194 </dt>
1195 <dd>
1196 Get the size of the terminal in rows and columns.
1197
1198
1199
1200 <h3>Returns:</h3>
1201 <ol>
1202 <li>
1203 <span class="types"><span class="type">int</span></span>
1204 the number of rows</li>
1205 <li>
1206 <span class="types"><span class="type">int</span></span>
1207 the number of columns</li>
1208 </ol>
1209 <h3>Or</h3>
1210 <ol>
1211 <li>
1212 <span class="types"><span class="type">nil</span></span>
1213
1214
1215</li>
1216 <li>
1217 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
1218 error message</li>
1219 </ol>
1220
1221
1222
1223
1224</dd>
1225 <dt>
1226 <a name = "termwrap"></a>
1227 <strong>termwrap (f)</strong>
1228 </dt>
1229 <dd>
1230 Wraps a function to automatically restore terminal settings upon returning.
1231 Calls <a href="../modules/system.html#termbackup">termbackup</a> before calling the function and <a href="../modules/system.html#termrestore">termrestore</a> after.
1232
1233
1234 <h3>Parameters:</h3>
1235 <ul>
1236 <li><span class="parameter">f</span>
1237 <span class="types"><span class="type">function</span></span>
1238 function to wrap
1239 </li>
1240 </ul>
1241
1242 <h3>Returns:</h3>
1243 <ol>
1244
1245 <span class="types"><span class="type">function</span></span>
1246 wrapped function
1247 </ol>
1248
1249
1250
1251
1252</dd>
1253 <dt>
1254 <a name = "utf8cwidth"></a>
1255 <strong>utf8cwidth (utf8_char)</strong>
1256 </dt>
1257 <dd>
1258 Get the width of a utf8 character for terminal display.
1259
1260
1261 <h3>Parameters:</h3>
1262 <ul>
1263 <li><span class="parameter">utf8_char</span>
1264 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
1265 the utf8 character to check, only the width of the first character will be returned
1266 </li>
1267 </ul>
1268
1269 <h3>Returns:</h3>
1270 <ol>
1271
1272 <span class="types"><span class="type">int</span></span>
1273 the display width in columns of the first character in the string (0 for an empty string)
1274 </ol>
1275 <h3>Or</h3>
1276 <ol>
1277 <li>
1278 <span class="types"><span class="type">nil</span></span>
1279
1280
1281</li>
1282 <li>
1283 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
1284 error message</li>
1285 </ol>
1286
1287
1288
1289
1290</dd>
1291 <dt>
1292 <a name = "utf8swidth"></a>
1293 <strong>utf8swidth (utf8_string)</strong>
1294 </dt>
1295 <dd>
1296 Get the width of a utf8 string for terminal display.
1297
1298
1299 <h3>Parameters:</h3>
1300 <ul>
1301 <li><span class="parameter">utf8_string</span>
1302 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
1303 the utf8 string to check
1304 </li>
1305 </ul>
1306
1307 <h3>Returns:</h3>
1308 <ol>
1309
1310 <span class="types"><span class="type">int</span></span>
1311 the display width of the string in columns (0 for an empty string)
1312 </ol>
1313 <h3>Or</h3>
1314 <ol>
1315 <li>
1316 <span class="types"><span class="type">nil</span></span>
1317
1318
1319</li>
1320 <li>
1321 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
1322 error message</li>
1323 </ol>
1324
1325
1326
1327
1328</dd>
1329</dl>
1330 <h2 class="section-header "><a name="Time"></a>Time </h2>
1331
1332 <dl class="function">
1333 <dt>
1334 <a name = "gettime"></a>
1335 <strong>gettime ()</strong>
1336 </dt>
1337 <dd>
1338 Get system time.
1339The time is returned as the seconds since the epoch (1 January 1970 00:00:00).
1340
1341
1342
1343 <h3>Returns:</h3>
1344 <ol>
1345
1346 <span class="types"><span class="type">number</span></span>
1347 seconds (fractional)
1348 </ol>
1349
1350
1351
1352
1353</dd>
1354 <dt>
1355 <a name = "monotime"></a>
1356 <strong>monotime ()</strong>
1357 </dt>
1358 <dd>
1359 Get monotonic time.
1360The time is returned as the seconds since system start.
1361
1362
1363
1364 <h3>Returns:</h3>
1365 <ol>
1366
1367 <span class="types"><span class="type">number</span></span>
1368 seconds (fractional)
1369 </ol>
1370
1371
1372
1373
1374</dd>
1375 <dt>
1376 <a name = "sleep"></a>
1377 <strong>sleep (seconds[, precision=16])</strong>
1378 </dt>
1379 <dd>
1380 Sleep without a busy loop.
1381This function will sleep, without doing a busy-loop and wasting CPU cycles.
1382
1383
1384 <h3>Parameters:</h3>
1385 <ul>
1386 <li><span class="parameter">seconds</span>
1387 <span class="types"><span class="type">number</span></span>
1388 seconds to sleep (fractional).
1389 </li>
1390 <li><span class="parameter">precision</span>
1391 <span class="types"><span class="type">integer</span></span>
1392 minimum stepsize in milliseconds (Windows only, ignored elsewhere)
1393 (<em>default</em> 16)
1394 </li>
1395 </ul>
1396
1397 <h3>Returns:</h3>
1398 <ol>
1399
1400 <code>true</code> on success, or <code>nil+err</code> on failure
1401 </ol>
1402
1403
1404
1405
1406</dd>
1407</dl>
1408
1409
1410</div> <!-- id="content" -->
1411</div> <!-- id="main" -->
1412<div id="about">
1413<i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i>
1414<i style="float:right;">Last updated 2024-06-20 23:11:37 </i>
1415</div> <!-- id="about" -->
1416</div> <!-- id="container" -->
1417</body>
1418</html>
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-12-24 17:21:40 +0000