summaryrefslogtreecommitdiffstatshomepage
path: root/3rdparty/luv/docs.md
blob: 187dec24ff143a338a0359684e9a3e704a985396 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
# LibUV in Lua

The [luv][] project provides access to the multi-platform support library
[libuv][] to lua code.  It was primariliy developed for the [luvit][] project as
the `uv` builtin module, but can be used in other lua environments.

### TCP Echo Server Example

Here is a small example showing a TCP echo server:

```lua
local uv = require('uv')

local server = uv.new_tcp()
server:bind("127.0.0.1", 1337)
server:listen(128, function (err)
  assert(not err, err)
  local client = uv.new_tcp()
  server:accept(client)
  client:read_start(function (err, chunk)
    assert(not err, err)
    if chunk then
      client:write(chunk)
    else
      client:shutdown()
      client:close()
    end
  end)
end)
print("TCP server listening at 127.0.0.1 port 1337")
uv.run()
```

### Methods vs Functions

As a quick note, [libuv][] is a C library and as such, there are no such things
as methods.  The [luv][] bindings allow calling the libuv functions as either
functions or methods.  For example, calling `server:bind(host, port)` is
equivalent to calling `uv.tcp_bind(server, host, port)`.  All wrapped uv types
in lua have method shortcuts where is makes sense.  Some are even renamed
shorter like the `tcp_` prefix that removed in method form.  Under the hood it's
the exact same C function.

## Table Of Contents

The rest of the docs are organized by libuv type.  There is some hierarchy as
most types are considered handles and some are considered streams.

 - [`uv_loop_t`][] — Event loop
 - [`uv_handle_t`][] — Base handle
   - [`uv_timer_t`][] — Timer handle
   - [`uv_prepare_t`][] — Prepare handle
   - [`uv_check_t`][] — Check handle
   - [`uv_idle_t`][] — Idle handle
   - [`uv_async_t`][] — Async handle
   - [`uv_poll_t`][] — Poll handle
   - [`uv_signal_t`][] — Signal handle
   - [`uv_process_t`][] — Process handle
   - [`uv_stream_t`][] — Stream handle
     - [`uv_tcp_t`][] — TCP handle
     - [`uv_pipe_t`][] — Pipe handle
     - [`uv_tty_t`][] — TTY handle
   - [`uv_udp_t`][] — UDP handle
   - [`uv_fs_event_t`][] — FS Event handle
   - [`uv_fs_poll_t`][] — FS Poll handle
 - [Filesystem operations][]
 - [DNS utility functions][]
 - [Miscellaneous utilities][]

## `uv_loop_t` — Event loop

[`uv_loop_t`]: #uv_loop_t--event-loop

The event loop is the central part of libuv’s functionality. It takes care of
polling for i/o and scheduling callbacks to be run based on different sources of
events.

In [luv][], there is an implicit uv loop for every lua state that loads the
library.  You can use this library in an multithreaded environment as long as
each thread has it's own lua state with corresponsding own uv loop.

### `uv.loop_close()`

Closes all internal loop resources. This function must only be called once the
loop has finished its execution or it will raise a UV_EBUSY error.

### `uv.run([mode])`

> optional `mode` defaults to `"default"`

This function runs the event loop. It will act differently depending on the
specified mode:

 - `"default"`: Runs the event loop until there are no more active and
   referenced handles or requests. Always returns `false`.

 - `"once"`: Poll for i/o once. Note that this function blocks if there are no
   pending callbacks. Returns `false` when done (no active handles or requests
   left), or `true` if more callbacks are expected (meaning you should run
   the event loop again sometime in the future).

 - `"nowait"`: Poll for i/o once but don’t block if there are no
   pending callbacks. Returns `false` if done (no active handles or requests
   left), or `true` if more callbacks are expected (meaning you should run
   the event loop again sometime in the future).

Luvit will implicitly call `uv.run()` after loading user code, but if you use
the `luv` bindings directly, you need to call this after registering your
initial set of event callbacks to start the event loop.

### `uv.loop_alive()`

Returns true if there are active handles or request in the loop.

### `uv.stop()`

Stop the event loop, causing `uv_run()` to end as soon as possible. This
will happen not sooner than the next loop iteration. If this function was called
before blocking for i/o, the loop won’t block for i/o on this iteration.

### `uv.backend_fd()`

Get backend file descriptor. Only kqueue, epoll and event ports are supported.

This can be used in conjunction with `uv_run("nowait")` to poll in one thread
and run the event loop’s callbacks in another.

**Note**: Embedding a kqueue fd in another kqueue pollset doesn’t work on all
platforms. It’s not an error to add the fd but it never generates events.

### `uv.backend_timeout()`

Get the poll timeout. The return value is in milliseconds, or -1 for no timeout.

### `uv.now()`

Return the current timestamp in milliseconds. The timestamp is cached at the
start of the event loop tick, see `uv.update_time()` for details and rationale.

The timestamp increases monotonically from some arbitrary point in time. Don’t
make assumptions about the starting point, you will only get disappointed.

**Note**: Use `uv.hrtime()` if you need sub-millisecond granularity.

### `uv.update_time()`

Update the event loop’s concept of “now”. Libuv caches the current time at the
start of the event loop tick in order to reduce the number of time-related
system calls.

You won’t normally need to call this function unless you have callbacks that
block the event loop for longer periods of time, where “longer” is somewhat
subjective but probably on the order of a millisecond or more.

### `uv.walk(callback)`

Walk the list of handles: `callback` will be executed with the handle.

```lua
-- Example usage of uv.walk to close all handles that aren't already closing.
uv.walk(function (handle)
  if not handle:is_closing() then
    handle:close()
  end
end)
```

## `uv_handle_t` — Base handle

[`uv_handle_t`]: #uv_handle_t--base-handle

`uv_handle_t` is the base type for all libuv handle types.

Structures are aligned so that any libuv handle can be cast to `uv_handle_t`.
All API functions defined here work with any handle type.

### `uv.is_active(handle)`

> method form `handle:is_active()`

Returns `true` if the handle is active, `false` if it’s inactive. What “active”
means depends on the type of handle:

 - A [`uv_async_t`][] handle is always active and cannot be deactivated, except
   by closing it with uv_close().

 - A [`uv_pipe_t`][], [`uv_tcp_t`][], [`uv_udp_t`][], etc. handlebasically any
   handle that deals with i/ois active when it is doing something that
   involves i/o, like reading, writing, connecting, accepting new connections,
   etc.

 - A [`uv_check_t`][], [`uv_idle_t`][], [`uv_timer_t`][], etc. handle is active
   when it has been started with a call to `uv.check_start()`,
   `uv.idle_start()`, etc.

Rule of thumb: if a handle of type `uv_foo_t` has a `uv.foo_start()` function,
then it’s active from the moment that function is called. Likewise,
`uv.foo_stop()` deactivates the handle again.

### `uv.is_closing(handle)`

> method form `handle:is_closing()`

Returns `true` if the handle is closing or closed, `false` otherwise.

**Note**: This function should only be used between the initialization of the
handle and the arrival of the close callback.

### `uv.close(handle, callback)`

> method form `handle:close(callback)`

Request handle to be closed. `callback` will be called asynchronously after this
call. This MUST be called on each handle before memory is released.

Handles that wrap file descriptors are closed immediately but `callback` will
still be deferred to the next iteration of the event loop. It gives you a chance
to free up any resources associated with the handle.

In-progress requests, like `uv_connect_t` or `uv_write_t`, are cancelled and
have their callbacks called asynchronously with `status=UV_ECANCELED`.

### `uv.ref(handle)`

> method form `handle:ref()`

Reference the given handle. References are idempotent, that is, if a handle is
already referenced calling this function again will have no effect.

See [Reference counting][].

### `uv.unref(handle)`

> method form `handle:unref()`

Un-reference the given handle. References are idempotent, that is, if a handle
is not referenced calling this function again will have no effect.

See [Reference counting][].

### `uv.has_ref(handle)`

> method form `handle:has_ref()`

Returns `true` if the handle referenced, `false` otherwise.

See [Reference counting][].

### `uv.send_buffer_size(handle, [size]) -> size`

> method form `handle:send_buffer_size(size)`

Gets or sets the size of the send buffer that the operating system uses for the
socket.

If `size` is omitted, it will return the current send buffer size, otherwise it
will use `size` to set the new send buffer size.

This function works for TCP, pipe and UDP handles on Unix and for TCP and UDP
handles on Windows.

**Note**: Linux will set double the size and return double the size of the
original set value.

### `uv.recv_buffer_size(handle, [size])`

> method form `handle:recv_buffer_size(size)`

Gets or sets the size of the receive buffer that the operating system uses for
the socket.

If `size` is omitted, it will return the current receive buffer size, otherwise
it will use `size` to set the new receive buffer size.

This function works for TCP, pipe and UDP handles on Unix and for TCP and UDP
handles on Windows.

**Note**: Linux will set double the size and return double the size of the
original set value.

### `uv.fileno(handle)`

> method form `handle:fileno()`

Gets the platform dependent file descriptor equivalent.

The following handles are supported: TCP, pipes, TTY, UDP and poll. Passing any
other handle type will fail with UV_EINVAL.

If a handle doesn’t have an attached file descriptor yet or the handle itself
has been closed, this function will return UV_EBADF.

**Warning**: Be very careful when using this function. libuv assumes it’s in
control of the file descriptor so any change to it may lead to malfunction.

## Reference counting

[reference counting]: #reference-counting

The libuv event loop (if run in the default mode) will run until there are no
active and referenced handles left. The user can force the loop to exit early by
unreferencing handles which are active, for example by calling `uv.unref()`
after calling `uv.timer_start()`.

A handle can be referenced or unreferenced, the refcounting scheme doesn’t use a
counter, so both operations are idempotent.

All handles are referenced when active by default, see `uv.is_active()` for a
more detailed explanation on what being active involves.

## `uv_timer_t` — Timer handle

[`uv_timer_t`]: #uv_timer_t--timer-handle

Timer handles are used to schedule callbacks to be called in the future.

### `uv.new_timer() -> timer`

Creates and initializes a new `uv_timer_t`. Returns the lua userdata wrapping
it.

```lua
-- Creating a simple setTimeout wrapper
local function setTimeout(timeout, callback)
  local timer = uv.new_timer()
  timer:start(timeout, 0, function ()
    timer:stop()
    timer:close()
    callback()
  end)
  return timer
end

-- Creating a simple setInterval wrapper
local function setInterval(interval, callback)
  local timer = uv.new_timer()
  timer:start(interval, interval, function ()
    timer:stop()
    timer:close()
    callback()
  end)
  return timer
end

-- And clearInterval
local function clearInterval(timer)
  timer:stop()
  timer:close()
end
```

### `uv.timer_start(timer, timeout, repeat, callback)`

> method form `timer:start(timeout, repeat, callback)`

Start the timer. `timeout` and `repeat` are in milliseconds.

If `timeout` is zero, the callback fires on the next event loop iteration. If
`repeat` is non-zero, the callback fires first after timeout milliseconds and
then repeatedly after repeat milliseconds.

### `uv.timer_stop(timer)`

> method form `timer:stop()`

Stop the timer, the callback will not be called anymore.

### `uv.timer_again(timer)`

> method form `timer:again()`

Stop the timer, and if it is repeating restart it using the repeat value as the
timeout. If the timer has never been started before it raises `EINVAL`.

### `uv.timer_set_repeat(timer, repeat)`

> method form `timer:set_repeat(repeat)`

Set the repeat value in milliseconds.

**Note**: If the repeat value is set from a timer callback it does not
immediately take effect. If the timer was non-repeating before, it will   have
been stopped. If it was repeating, then the old repeat value will   have been
used to schedule the next timeout.

### `uv.timer_get_repeat(timer) -> repeat`

> method form `timer:get_repeat() -> repeat`

Get the timer repeat value.

## `uv_prepare_t` — Prepare handle

[`uv_prepare_t`]: #uv_prepare_t--prepare-handle

Prepare handles will run the given callback once per loop iteration, right before polling for i/o.

```lua
local prepare = uv.new_prepare()
prepare:start(function()
  print("Before I/O polling")
end)
```

### `uv.new_prepare() -> prepare`

Creates and initializes a new `uv_prepare_t`. Returns the lua userdata wrapping
it.

### `uv.prepare_start(prepare, callback)`

> method form `prepare:start(callback)`

Start the handle with the given callback.

### `uv.prepare_stop(prepare)`

> method form `prepare:stop()`

Stop the handle, the callback will no longer be called.

## `uv_check_t` — Check handle

[`uv_check_t`]: #uv_check_t--check-handle

Check handles will run the given callback once per loop iteration, right after
polling for i/o.

```lua
local check = uv.new_check()
check:start(function()
  print("After I/O polling")
end)
```

### `uv.new_check() -> check`

Creates and initializes a new `uv_check_t`. Returns the lua userdata wrapping
it.

### `uv.check_start(check, callback)`

> method form `check:start(callback)`

Start the handle with the given callback.

### `uv.check_stop(check)`

> method form `check:stop()`

Stop the handle, the callback will no longer be called.

## `uv_idle_t` — Idle handle

[`uv_idle_t`]: #uv_idle_t--idle-handle

Idle handles will run the given callback once per loop iteration, right before
the [`uv_prepare_t`][] handles.

**Note**: The notable difference with prepare handles is that when there are
active idle handles, the loop will perform a zero timeout poll instead of
blocking for i/o.

**Warning**: Despite the name, idle handles will get their callbacks called on
every loop iteration, not when the loop is actually “idle”.

```lua
local idle = uv.new_idle()
idle:start(function()
  print("Before I/O polling, no blocking")
end)
```
### `uv.new_idle() -> idle`

Creates and initializes a new `uv_idle_t`. Returns the lua userdata wrapping
it.

### `uv.idle_start(idle, callback)`

> method form `idle:start(callback)`

Start the handle with the given callback.

### `uv.idle_stop(check)`

> method form `idle:stop()`

Stop the handle, the callback will no longer be called.

## `uv_async_t` — Async handle

[`uv_async_t`]: #uv_async_t--async-handle

Async handles allow the user to “wakeup” the event loop and get a callback
called from another thread.

```lua
local async
async = uv.new_async(function()
  print("async operation ran")
  async:close()
end)

async:send()
```

### `uv.new_async(callback) -> async`

Creates and initializes a new `uv_async_t`. Returns the lua userdata wrapping
it. A NULL callback is allowed.

**Note**: Unlike other handle initialization functions, it immediately starts
the handle.

### `uv.async_send(async)`

> method form `async:send()`

Wakeup the event loop and call the async handle’s callback.

**Note**: It’s safe to call this function from any thread. The callback will be
called on the loop thread.

**Warning**: libuv will coalesce calls to `uv.async_send(async)`, that is, not
every call to it will yield an execution of the callback, the only guarantee is
that it will be called at least once. Thus, calling this function may not
wakeup the event loop if it was already called previously within a short period
of time.

## `uv_poll_t` — Poll handle

[`uv_poll_t`]: #uv_poll_t--poll-handle

Poll handles are used to watch file descriptors for readability and writability,
similar to the purpose of [poll(2)](http://linux.die.net/man/2/poll).

The purpose of poll handles is to enable integrating external libraries that
rely on the event loop to signal it about the socket status changes, like c-ares
or libssh2. Using `uv_poll_t` for any other purpose is not recommended;
`uv_tcp_t`, `uv_udp_t`, etc. provide an implementation that is faster and more
scalable than what can be achieved with `uv_poll_t`, especially on Windows.

It is possible that poll handles occasionally signal that a file descriptor is
readable or writable even when it isn’t. The user should therefore always be
prepared to handle EAGAIN or equivalent when it attempts to read from or write
to the fd.

It is not okay to have multiple active poll handles for the same socket, this
can cause libuv to busyloop or otherwise malfunction.

The user should not close a file descriptor while it is being polled by an
active poll handle. This can cause the handle to report an error, but it might
also start polling another socket. However the fd can be safely closed
immediately after a call to `uv.poll_stop()` or `uv.close()`.

**Note** On windows only sockets can be polled with poll handles. On Unix any
file descriptor that would be accepted by poll(2) can be used.


### `uv.new_poll(fd) -> poll`

Initialize the handle using a file descriptor.

The file descriptor is set to non-blocking mode.

### `uv.new_socket_poll(fd) -> poll`

Initialize the handle using a socket descriptor. On Unix this is identical to
`uv.poll_init()`. On windows it takes a SOCKET handle.

The socket is set to non-blocking mode.

### `uv.poll_start(poll, events, callback)`

> method form `poll:start()`

Starts polling the file descriptor. `events` is `"r"`, `"w"`, or `"rw"` and
translates to a bitmask made up of UV_READABLE and UV_WRITABLE. As soon as an
event is detected the callback will be called with status set to 0, and the
detected events set on the events field.

The user should not close the socket while the handle is active. If the user
does that anyway, the callback may be called reporting an error status, but this
is not guaranteed.

**Note** Calling `uv.poll_start()`` on a handle that is already active is fine.
Doing so will update the events mask that is being watched for.

## `uv.poll_stop(poll)`

> method form `poll:stop()`

Stop polling the file descriptor, the callback will no longer be called.

## `uv_signal_t` — Signal handle

[`uv_signal_t`]: #uv_signal_t--signal-handle

Signal handles implement Unix style signal handling on a per-event loop bases.

Reception of some signals is emulated on Windows:
* SIGINT is normally delivered when the user presses CTRL+C. However, like on
Unix, it is not generated when terminal raw mode is enabled.
* SIGBREAK is delivered when the user pressed CTRL + BREAK.
* SIGHUP is generated when the user closes the console window. On SIGHUP the
program is given approximately 10 seconds to perform cleanup. After that
Windows will unconditionally terminate it.
* SIGWINCH is raised whenever libuv detects that the console has been resized.
SIGWINCH is emulated by libuv when the program uses a uv_tty_t handle to write
to the console. SIGWINCH may not always be delivered in a timely manner; libuv
will only detect size changes when the cursor is being moved. When a readable
[`uv_tty_t`][] handle is used in raw mode, resizing the console buffer will
also trigger a SIGWINCH signal.

Watchers for other signals can be successfully created, but these signals are
never received. These signals are: SIGILL, SIGABRT, SIGFPE, SIGSEGV, SIGTERM
and SIGKILL.

Calls to raise() or abort() to programmatically raise a signal are not detected
by libuv; these will not trigger a signal watcher.

**Note**: On Linux SIGRT0 and SIGRT1 (signals 32 and 33) are used by the NPTL
pthreads library to manage threads. Installing watchers for those signals will
lead to unpredictable behavior and is strongly discouraged. Future versions of
libuv may simply reject them.

```lua
-- Create a new signal handler
local sigint = uv.new_signal()
-- Define a handler function
uv.signal_start(sigint, "sigint", function(signal)
print("got " .. signal .. ", shutting down")
os.exit(1)
end)
```

### `uv.new_signal() -> signal`

Creates and initializes a new `uv_signal_t`. Returns the lua userdata wrapping
it.

### `uv.signal_start(signal, signum, callback)`

> method form `signal:start(signum, callback)`

Start the handle with the given callback, watching for the given signal.

### `uv.signal_stop(signal)`

> method form `signal:stop()`

Stop the handle, the callback will no longer be called.

## `uv_process_t` — Process handle

[`uv_process_t`]: #uv_process_t--process-handle

Process handles will spawn a new process and allow the user to control it and
establish communication channels with it using streams.

### `uv.disable_stdio_inheritance()`

Disables inheritance for file descriptors / handles that this process inherited
from its parent. The effect is that child processes spawned by this process
don’t accidentally inherit these handles.

It is recommended to call this function as early in your program as possible,
before the inherited file descriptors can be closed or duplicated.

**Note** This function works on a best-effort basis: there is no guarantee that
libuv can discover all file descriptors that were inherited. In general it does
a better job on Windows than it does on Unix.

### `uv.spawn(file, options, onexit) -> process, pid`

Initializes the process handle and starts the process. If the process is
successfully spawned, this function will return the handle and pid of the child
process.

Possible reasons for failing to spawn would include (but not be limited to) the
file to execute not existing, not having permissions to use the setuid or setgid
specified, or not having enough memory to allocate for the new process.


```lua
local stdout = uv.new_pipe(false)
local stderr = uv.new_pipe(false)
local stdin = uv.new_pipe(false)

local handle, pid

local function onexit(code, signal)
  p("exit", {code=code,signal=signal})
end

local function onclose()
  p("close")
end

local function onread(err, chunk)
  assert(not err, err)
  if (chunk) then
    p("data", {data=chunk})
  else
    p("end")
  end
end

local function onshutdown()
  uv.close(handle, onclose)
end

handle, pid = uv.spawn("cat", {
  stdio = {stdin, stdout, stderr}
}, onexit)

p{
  handle=handle,
  pid=pid
}

uv.read_start(stdout, onread)
uv.read_start(stderr, onread)
uv.write(stdin, "Hello World")
uv.shutdown(stdin, onshutdown)
```

 - `options.args` - Command line arguments as a list of string. The first string
   should be the path to the program. On Windows this uses CreateProcess which
   concatenates the arguments into a string this can cause some strange errors.
   (See `options.verbatim` below for Windows.)
 - `options.stdio` - Set the file descriptors that will be made available to the
   child process. The convention is that the first entries are stdin, stdout,
   and stderr. (**Note** On Windows file descriptors after the third are
   available to the child process only if the child processes uses the MSVCRT
   runtime.)
 - `options.env` - Set environment variables for the new process.
 - `options.cwd` - Set current working directory for the subprocess.
 - `options.uid` - Set the child process' user id.
 - `options.gid` - Set the child process' group id.
 - `options.verbatim` - If true, do not wrap any arguments in quotes, or perform
   any other escaping, when converting the argument list into a command line
   string. This option is only meaningful on Windows systems. On Unix it is
   silently ignored.
 - `options.detached` - If true, spawn the child process in a detached state -
   this will make it a process group leader, and will effectively enable the
   child to keep running after the parent exits. Note that the child process
   will still keep the parent's event loop alive unless the parent process calls
   `uv.unref()` on the child's process handle.
 - `options.hide` - If true, hide the subprocess console window that would
   normally be created. This option is only meaningful on Windows systems. On
   Unix it is silently ignored.

The `options.stdio` entries can take many shapes.

- If they are numbers, then the child process inherits that same zero-indexed fd
  from the parent process.
- If `uv_stream_h` handles are passed in, those are used as a read-write pipe or
  inherited stream depending if the stream has a valid fd.
- Including `nil` placeholders means to ignore that fd in the child.

When the child process exits, the `onexit` callback will be called with exit
code and signal.

### `uv.process_kill(process, sigmun)`

> method form `process:kill(sigmun)`

Sends the specified signal to the given process handle.

### `uv.kill(pid, sigmun)`

Sends the specified signal to the given PID.

## `uv_stream_t` — Stream handle

[`uv_stream_t`]: #uv_stream_t--stream-handle

Stream handles provide an abstraction of a duplex communication channel.
[`uv_stream_t`][] is an abstract type, libuv provides 3 stream implementations in
the form of [`uv_tcp_t`][], [`uv_pipe_t`][] and [`uv_tty_t`][].

### `uv.shutdown(stream, [callback]) -> req`

> (method form `stream:shutdown([callback]) -> req`)

Shutdown the outgoing (write) side of a duplex stream. It waits for pending
write requests to complete. The callback is called after
shutdown is complete.

### `uv.listen(stream, backlog, callback)`

> (method form `stream:listen(backlog, callback)`)

Start listening for incoming connections. `backlog` indicates the number of
connections the kernel might queue, same as `listen(2)`. When a new incoming
connection is received the callback is called.

### `uv.accept(stream, client_stream)`

> (method form `stream:accept(client_stream)`)

This call is used in conjunction with `uv.listen()` to accept incoming
connections. Call this function after receiving a callback to accept the
connection.

When the connection callback is called it is guaranteed that this function
will complete successfully the first time. If you attempt to use it more than
once, it may fail. It is suggested to only call this function once per
connection call.

```lua
server:listen(128, function (err)
  local client = uv.new_tcp()
  server:accept(client)
end)
```

### `uv.read_start(stream, callback)`

> (method form `stream:read_start(callback)`)

Callback is of the form `(err, data)`.

Read data from an incoming stream. The callback will be made several times until
there is no more data to read or `uv.read_stop()` is called. When we’ve reached
EOF, `data` will be `nil`.

```lua
stream:read_start(function (err, chunk)
  if err then
    -- handle read error
  elseif chunk then
    -- handle data
  else
    -- handle disconnect
  end
end)
```

### `uv.read_stop(stream)`

> (method form `stream:read_stop()`)

Stop reading data from the stream. The read callback will no longer be called.

### `uv.write(stream, data, [callback])`

> (method form `stream:write(data, [callback])`)

Write data to stream.

`data` can either be a lua string or a table of strings.  If a table is passed
in, the C backend will use writev to send all strings in a single system call.

The optional `callback` is for knowing when the write is
complete.

### `uv.write2(stream, data, send_handle, callback)`

> (method form `stream:write2(data, send_handle, callback)`)

Extended write function for sending handles over a pipe. The pipe must be
initialized with ip option to `true`.

**Note: `send_handle` must be a TCP socket or pipe, which is a server or a
connection (listening or connected state). Bound sockets or pipes will be
assumed to be servers.

### `uv.try_write(stream, data)`

> (method form `stream:try_write(data)`)

Same as `uv.write()`, but won’t queue a write request if it can’t be completed
immediately.

Will return number of bytes written (can be less than the supplied buffer size).

### `uv.is_readable(stream)`

> (method form `stream:is_readable()`)

Returns `true` if the stream is readable, `false` otherwise.

### `uv.is_writable(stream)`

> (method form `stream:is_writable()`)

Returns `true` if the stream is writable, `false` otherwise.

### `uv.stream_set_blocking(stream, blocking)`

> (method form `stream:set_blocking(blocking)`)

Enable or disable blocking mode for a stream.

When blocking mode is enabled all writes complete synchronously. The interface
remains unchanged otherwise, e.g. completion or failure of the operation will
still be reported through a callback which is made asynchronously.

**Warning**: Relying too much on this API is not recommended. It is likely to
change significantly in the future. Currently this only works on Windows and
only for uv_pipe_t handles. Also libuv currently makes no ordering guarantee
when the blocking mode is changed after write requests have already been
submitted. Therefore it is recommended to set the blocking mode immediately
after opening or creating the stream.

## `uv_tcp_t` — TCP handle

[`uv_tcp_t`]: #uv_tcp_t--tcp-handle

TCP handles are used to represent both TCP streams and servers.

`uv_tcp_t` is a ‘subclass’ of [`uv_stream_t`][](#uv_stream_t--stream-handle).

### `uv.new_tcp() -> tcp`

Creates and initializes a new `uv_tcp_t`. Returns the lua userdata wrapping it.

### `uv.tcp_open(tcp, sock)`

> (method form `tcp:open(sock)`)

Open an existing file descriptor or SOCKET as a TCP handle.

**Note: The user is responsible for setting the file descriptor in non-blocking
mode.

### `uv.tcp_nodelay(tcp, enable)`

> (method form `tcp:nodelay(enable)`)

Enable / disable Nagle’s algorithm.

### `uv.tcp_keepalive(tcp, enable, [delay])`

> (method form `tcp:keepalive(enable, [delay])`)

Enable / disable TCP keep-alive. `delay` is the initial delay in seconds, ignored
when enable is `false`.

### `uv.tcp_simultaneous_accepts(tcp, enable)`

> (method form `tcp:simultaneous_accepts(enable)`)

Enable / disable simultaneous asynchronous accept requests that are queued by
the operating system when listening for new TCP connections.

This setting is used to tune a TCP server for the desired performance. Having
simultaneous accepts can significantly improve the rate of accepting connections
(which is why it is enabled by default) but may lead to uneven load distribution
in multi-process setups.

### `uv.tcp_bind(tcp, address, port)`

> (method form `tcp:bind(address, port)`)

Bind the handle to an address and port. `address` should be an IP address and
not a domain name.

When the port is already taken, you can expect to see an UV_EADDRINUSE error
from either `uv.tcp_bind()`, `uv.listen()` or `uv.tcp_connect()`. That is, a
successful call to this function does not guarantee that the call to `uv.listen()`
or `uv.tcp_connect()` will succeed as well.

Use a port of `0` to let the OS assign an ephemeral port.  You can look it up
later using `uv.tcp_getsockname()`.

### `uv.tcp_getsockname(tcp)`

> (method form `tcp:getsockname()`)

Get the current address to which the handle is bound.

### `uv.tcp_getpeername(tcp)`

> (method form `tcp:getpeername()`)

Get the address of the peer connected to the handle.

### `uv.tcp_connect(tcp, address, port, callback) -> req`

> (method form `tcp:connect(host, port, callback) -> req`)

### `uv.tcp_write_queue_size(tcp) -> size`

> (method form `tcp:write_queue_size() -> size`)

Establish an IPv4 or IPv6 TCP connection.

The callback is made when the connection has been established or when a
connection error happened.

```lua
local client = uv.new_tcp()
client:connect("127.0.0.1", 8080, function (err)
  -- check error and carry on.
end)
```

## `uv_pipe_t` — Pipe handle

[`uv_pipe_t`]: #uv_pipe_t--pipe-handle

Pipe handles provide an abstraction over local domain sockets on Unix and named
pipes on Windows.

```lua
local pipe = uv.new_pipe(false)

pipe:bind('/tmp/sock.test')

pipe:listen(128, function()
  local client = uv.new_pipe(false)
  pipe:accept(client)
  client:write("hello!\n")
  client:close()
end)
```

### `uv.new_pipe(ipc) -> pipe`

Creates and initializes a new `uv_pipe_t`. Returns the lua userdata wrapping
it. The `ipc` argument is a boolean to indicate if this pipe will be used for
handle passing between processes.

### `uv.pipe_open(file) -> pipe`

Open an existing file descriptor or [`uv_handle_t`][] as a pipe.

**Note**: The file descriptor is set to non-blocking mode.

### `uv.pipe_bind(pipe, name)`

> (method form `pipe:bind(name)`)

Bind the pipe to a file path (Unix) or a name (Windows).

**Note**: Paths on Unix get truncated to sizeof(sockaddr_un.sun_path) bytes,
typically between 92 and 108 bytes.

### `uv.pipe_connect(pipe, name, callback)`

> (method form `pipe:connect(name, callback)`)

Connect to the Unix domain socket or the named pipe.

**Note**: Paths on Unix get truncated to sizeof(sockaddr_un.sun_path) bytes,
typically between 92 and 108 bytes.

### `uv.pipe_getsockname(pipe)`

> (method form `pipe:getsockname()`)

Returns the name of the Unix domain socket or the named pipe.

### `uv.pipe_pending_instances(pipe, count)`

> (method form `pipe:pending_instances(count)`)

Set the number of pending pipe instance handles when the pipe server is waiting for connections.

**Note**: This setting applies to Windows only.

### `uv.pipe_pending_count(pipe)`

> (method form `pipe:pending_count()`)

Returns the pending pipe count for the named pipe.

### `uv.pipe_pending_type(pipe)`

> (method form `pipe:pending_type()`)

Used to receive handles over IPC pipes.

First - call [`uv.pipe_pending_count`][], if it’s > 0 then initialize a handle
of the given type, returned by [`uv.pipe_pending_type`][] and call
[`uv.accept(pipe, handle)`][].

## `uv_tty_t` — TTY handle

[`uv_tty_t`]: #uv_tty_t--tty-handle

TTY handles represent a stream for the console.

```lua
-- Simple echo program
local stdin = uv.new_tty(0, true)
local stdout = uv.new_tty(1, false)

stdin:read_start(function (err, data)
  assert(not err, err)
  if data then
    stdout:write(data)
  else
    stdin:close()
    stdout:close()
  end
end)
```

### uv.new_tty(fd, readable) -> tty

Initialize a new TTY stream with the given file descriptor. Usually the file
descriptor will be:

 - 0 - stdin
 - 1 - stdout
 - 2 - stderr

`readable, specifies if you plan on calling uv_read_start() with this stream.
`stdin is readable, stdout is not.

On Unix this function will try to open /dev/tty and use it if the passed file
descriptor refers to a TTY. This lets libuv put the tty in non-blocking mode
without affecting other processes that share the tty.

Note: If opening `/dev/tty` fails, libuv falls back to blocking writes for
non-readable TTY streams.

### uv.tty_set_mode(mode)

> (method form `tty:set_mode(mode)`)

Set the TTY using the specified terminal mode.

Parameter `mode` is a C enum with the following values:

- 0 - UV_TTY_MODE_NORMAL: Initial/normal terminal mode

- 1 - UV_TTY_MODE_RAW: Raw input mode (On Windows, ENABLE_WINDOW_INPUT is
  also enabled)

- 2 - UV_TTY_MODE_IO: Binary-safe I/O mode for IPC (Unix-only)

## uv.tty_reset_mode()

To be called when the program exits. Resets TTY settings to default values for
the next process to take over.

This function is async signal-safe on Unix platforms but can fail with error
code UV_EBUSY if you call it when execution is inside uv_tty_set_mode().

## uv.tty_get_winsize() -> w, h

> (method form `tty:get_winsize() -> w, h`)

Gets the current Window size.

## `uv_udp_t` — UDP handle

[`uv_udp_t`]: #uv_udp_t--udp-handle

UDP handles encapsulate UDP communication for both clients and servers.

### uv.new_udp() -> udp

Initialize a new UDP handle. The actual socket is created lazily.

### uv.udp_open(udp, fd)

> (method form `udp:open(fd)`)

Opens an existing file descriptor or Windows SOCKET as a UDP handle.

Unix only: The only requirement of the sock argument is that it follows the
datagram contract (works in unconnected mode, supports sendmsg()/recvmsg(),
etc). In other words, other datagram-type sockets like raw sockets or netlink
sockets can also be passed to this function.

The file descriptor is set to non-blocking mode.

Note: The passed file descriptor or SOCKET is not checked for its type, but
it’s required that it represents a valid datagram socket.

### uv.udp_bind(udp, host, port)

> (method form `udp:bind(host, port)`)

Bind the UDP handle to an IP address and port.

### uv.udp_getsockname(udp)

> (method form `udp:getsockname()`)

Get the local IP and port of the UDP handle.

### uv.udp_set_membership(udp, multicast_addr, interface_addr, membership)

> (method form `udp:set_membership(multicast_addr, interface_addr, membership)`)

Set membership for a multicast address.

`multicast_addr` is multicast address to set membership for.

`interface_addr` is interface address.

`membership` can be the string `"leave"` or `"join"`.

### uv.udp_set_multicast_loop(udp, on)

> (method form `udp:set_multicast_loop(on)`)

Set IP multicast loop flag. Makes multicast packets loop back to local
sockets.

`on` is a boolean.

### uv.udp_set_multicast_ttl(udp, tty)

> (method form `udp:set_multicast_ttl(tty)`)

Set the multicast ttl.

`ttl` is an integer 1 through 255.

### uv.udp_set_multicast_interface(udp, interface_addr)

> (method form `udp:set_multicast_interface(interface_addr)`)

Set the multicast interface to send or receive data on.

### uv.udp_set_broadcast(udp, on)

Set broadcast on or off.

> (method form `udp:set_broadcast(, on)`)

### uv.udp_set_ttl(udp, ttl)

> (method form `udp:set_ttl(ttl)`)

Set the time to live.

`ttl` is an integer 1 through 255.

### uv.udp_send(udp, data, host, port, callback)

> (method form `udp:send(data, host, port, callback)`)

Send data over the UDP socket. If the socket has not previously been bound
with `uv_udp_bind()` it will be bound to `0.0.0.0` (the “all interfaces” IPv4
address) and a random port number.

### uv.udp_try_send(udp, data, host, port)

> (method form `udp:try_send(data, host, port)`)

Same as `uv_udp_send()`, but won’t queue a send request if it can’t be
completed immediately.

### uv.udp_recv_start(udp, callback)

> (method form `udp:recv_start(callback)`)

Prepare for receiving data. If the socket has not previously been bound with
`uv_udp_bind()` it is bound to `0.0.0.0` (the “all interfaces” IPv4 address)
and a random port number.

### uv.udp_recv_stop(udp)

> (method form `udp:recv_stop()`)

## `uv_fs_event_t` — FS Event handle

[`uv_fs_event_t`]: #uv_fs_event_t--fs-event-handle

**TODO**: port docs from [docs.libuv.org](http://docs.libuv.org/en/v1.x/fs_event.html)
using [functions](https://github.com/luvit/luv/blob/25278a3871962cab29763692fdc3b270a7e96fe9/src/luv.c#L174-L177)
and [methods](https://github.com/luvit/luv/blob/25278a3871962cab29763692fdc3b270a7e96fe9/src/luv.c#L265-L270)
from [fs_event.c](https://github.com/luvit/luv/blob/master/src/fs_event.c)

## `uv_fs_poll_t` — FS Poll handle

[`uv_fs_poll_t`]: #uv_fs_poll_t--fs-poll-handle

**TODO**: port docs from [docs.libuv.org](http://docs.libuv.org/en/v1.x/fs_poll.html)
using [functions](https://github.com/luvit/luv/blob/25278a3871962cab29763692fdc3b270a7e96fe9/src/luv.c#L180-L183)
and [methods](https://github.com/luvit/luv/blob/25278a3871962cab29763692fdc3b270a7e96fe9/src/luv.c#L272-L277)
from [fs_poll.c](https://github.com/luvit/luv/blob/master/src/fs_poll.c)

## Filesystem operations

[Filesystem operations]:#filesystem-operations

**TODO**: port docs from [docs.libuv.org](http://docs.libuv.org/en/v1.x/fs.html)
using [functions](https://github.com/luvit/luv/blob/25278a3871962cab29763692fdc3b270a7e96fe9/src/luv.c#L186-L213)
from [fs.c](https://github.com/luvit/luv/blob/master/src/fs.c)

## DNS utility functions

[DNS utility functions]: #dns-utility-functions

**TODO**: port docs from [docs.libuv.org](http://docs.libuv.org/en/v1.x/dns.html)
using [functions](https://github.com/luvit/luv/blob/25278a3871962cab29763692fdc3b270a7e96fe9/src/luv.c#L216-L217)
from [dns.c](https://github.com/luvit/luv/blob/master/src/dns.c)

## Miscellaneous utilities

[Miscellaneous utilities]: #miscellaneous-utilities

**TODO**: port docs from [docs.libuv.org](http://docs.libuv.org/en/v1.x/misc.html)
using [functions](https://github.com/luvit/luv/blob/25278a3871962cab29763692fdc3b270a7e96fe9/src/luv.c#L220-L235)
from [misc.c](https://github.com/luvit/luv/blob/master/src/misc.c)

[luv]: https://github.com/luvit/luv
[luvit]: https://github.com/luvit/luvit
[libuv]: https://github.com/libuv/libuv