xref: /libuv/docs/src/tty.rst (revision 3e1733a0)
1
2.. _tty:
3
4:c:type:`uv_tty_t` --- TTY handle
5=================================
6
7TTY handles represent a stream for the console.
8
9:c:type:`uv_tty_t` is a 'subclass' of :c:type:`uv_stream_t`.
10
11
12Data types
13----------
14
15.. c:type:: uv_tty_t
16
17    TTY handle type.
18
19.. c:enum:: uv_tty_mode_t
20
21    .. versionadded:: 1.2.0
22
23    TTY mode type:
24
25    ::
26
27      typedef enum {
28          /* Initial/normal terminal mode */
29          UV_TTY_MODE_NORMAL,
30          /* Raw input mode (On Windows, ENABLE_WINDOW_INPUT is also enabled) */
31          UV_TTY_MODE_RAW,
32          /* Binary-safe I/O mode for IPC (Unix-only) */
33          UV_TTY_MODE_IO
34      } uv_tty_mode_t;
35
36.. c:enum:: uv_tty_vtermstate_t
37
38    Console virtual terminal mode type:
39
40    ::
41
42      typedef enum {
43          /*
44           * The console supports handling of virtual terminal sequences
45           * (Windows10 new console, ConEmu)
46           */
47          UV_TTY_SUPPORTED,
48          /* The console cannot process virtual terminal sequences.  (Legacy
49           * console)
50           */
51          UV_TTY_UNSUPPORTED
52      } uv_tty_vtermstate_t
53
54
55
56Public members
57^^^^^^^^^^^^^^
58
59N/A
60
61.. seealso:: The :c:type:`uv_stream_t` members also apply.
62
63
64API
65---
66
67.. c:function:: int uv_tty_init(uv_loop_t* loop, uv_tty_t* handle, uv_file fd, int unused)
68
69    Initialize a new TTY stream with the given file descriptor. Usually the
70    file descriptor will be:
71
72    * 0 = stdin
73    * 1 = stdout
74    * 2 = stderr
75
76    On Unix this function will determine the path of the fd of the terminal
77    using :man:`ttyname_r(3)`, open it, and use it if the passed file descriptor
78    refers to a TTY. This lets libuv put the tty in non-blocking mode without
79    affecting other processes that share the tty.
80
81    This function is not thread safe on systems that don't support
82    ioctl TIOCGPTN or TIOCPTYGNAME, for instance OpenBSD and Solaris.
83
84    .. note::
85        If reopening the TTY fails, libuv falls back to blocking writes.
86
87    .. versionchanged:: 1.23.1: the `readable` parameter is now unused and ignored.
88                        The correct value will now be auto-detected from the kernel.
89
90    .. versionchanged:: 1.9.0: the path of the TTY is determined by
91                        :man:`ttyname_r(3)`. In earlier versions libuv opened
92                        `/dev/tty` instead.
93
94    .. versionchanged:: 1.5.0: trying to initialize a TTY stream with a file
95                        descriptor that refers to a file returns `UV_EINVAL`
96                        on UNIX.
97
98.. c:function:: int uv_tty_set_mode(uv_tty_t* handle, uv_tty_mode_t mode)
99
100    .. versionchanged:: 1.2.0: the mode is specified as a
101                        :c:enum:`uv_tty_mode_t` value.
102
103    Set the TTY using the specified terminal mode.
104
105.. c:function:: int uv_tty_reset_mode(void)
106
107    To be called when the program exits. Resets TTY settings to default
108    values for the next process to take over.
109
110    This function is async signal-safe on Unix platforms but can fail with error
111    code ``UV_EBUSY`` if you call it when execution is inside
112    :c:func:`uv_tty_set_mode`.
113
114.. c:function:: int uv_tty_get_winsize(uv_tty_t* handle, int* width, int* height)
115
116    Gets the current Window size. On success it returns 0.
117
118.. seealso:: The :c:type:`uv_stream_t` API functions also apply.
119
120.. c:function:: void uv_tty_set_vterm_state(uv_tty_vtermstate_t state)
121
122    Controls whether console virtual terminal sequences are processed by libuv
123    or console.
124    Useful in particular for enabling ConEmu support of ANSI X3.64 and Xterm
125    256 colors. Otherwise Windows10 consoles are usually detected automatically.
126
127    This function is only meaningful on Windows systems. On Unix it is silently
128    ignored.
129
130    .. versionadded:: 1.33.0
131
132.. c:function:: int uv_tty_get_vterm_state(uv_tty_vtermstate_t* state)
133
134    Get the current state of whether console virtual terminal sequences are
135    handled by libuv or the console.
136
137    This function is not implemented on Unix, where it returns ``UV_ENOTSUP``.
138
139    .. versionadded:: 1.33.0
140
141