1Entering & leaving tty mode(3)      BrlAPI      Entering & leaving tty mode(3)
2
3
4

NAME

6       Entering & leaving tty mode - How to take control of ttys for direct
7       braille display / read.
8
9
10   Defines
11       #define BRLAPI_TTY_DEFAULT   -1
12
13   Functions
14       int BRLAPI_STDCALL brlapi_enterTtyMode (int tty, const char *driver)
15       int BRLAPI_STDCALL brlapi__enterTtyMode (brlapi_handle_t *handle, int
16           tty, const char *driver)
17       int BRLAPI_STDCALL brlapi_enterTtyModeWithPath (int *ttys, int count,
18           const char *driver)
19       int BRLAPI_STDCALL brlapi__enterTtyModeWithPath (brlapi_handle_t
20           *handle, int *ttys, int count, const char *driver)
21       int BRLAPI_STDCALL brlapi_leaveTtyMode (void)
22       int BRLAPI_STDCALL brlapi__leaveTtyMode (brlapi_handle_t *handle)
23       int BRLAPI_STDCALL brlapi_setFocus (int tty)
24       int BRLAPI_STDCALL brlapi__setFocus (brlapi_handle_t *handle, int tty)
25

Detailed Description

27       Before being able to write on the braille display, the application must
28       tell the server which tty it will handle.
29
30       The application must also specify how braille keys will be delivered to
31       it. Two ways are possible: key codes and commands:
32
33       · key codes are specific to each braille driver, since the raw key
34         code, as defined in the driver will be given for each key press.
35         Using them leads to building highly driver-dependent applications,
36         which can yet sometimes be useful to mimic existing proprietary
37         applications for instance.
38
39       · commands means that applications will get exactly the same values as
40         brltty. This allows driver-independent clients, which will hopefully
41         be nice to use with a lot of different terminals.
42
43       See also:
44           brlapi_readKey()
45

Define Documentation

47   #define BRLAPI_TTY_DEFAULT   -1
48       Select the default tty.
49
50       The library takes the following steps:
51
52       1.  Try to get the tty number from the WINDOWID environment variable
53           (for the xterm case).
54
55       2.  Try to get the tty number from the CONTROLVT environment variable.
56
57       3.  Read /proc/self/stat (on Linux).
58
59       See also:
60           brlapi_enterTtyMode()
61

Function Documentation

63   int BRLAPI_STDCALL brlapi__enterTtyMode (brlapi_handle_t * handle, int tty,
64       const char * driver)
65   int BRLAPI_STDCALL brlapi__enterTtyModeWithPath (brlapi_handle_t * handle,
66       int * ttys, int count, const char * driver)
67   int BRLAPI_STDCALL brlapi__leaveTtyMode (brlapi_handle_t * handle)
68   int BRLAPI_STDCALL brlapi__setFocus (brlapi_handle_t * handle, int tty)
69   int BRLAPI_STDCALL brlapi_enterTtyMode (int tty, const char * driver)
70       Ask for some tty, with some key mechanism
71
72       Parameters:
73           tty
74
75           · If tty>=0 then take control of the specified tty.
76
77           · If tty==BRLAPI_TTY_DEFAULT then take control of the default tty.
78
79           driver tells how the application wants brlapi_readKey() to return
80           key presses. NULL or '' means BRLTTY commands are required, whereas
81           a driver name means that raw key codes returned by this driver are
82           expected.
83
84       In an X window environment, WINDOWPATH might be useful. XFree86 >=4.4
85       defines an XFree86_VT root window property which exactly holds the used
86       VT, so that it should be given to brlapi_enterTtyMode. If it isn't
87       available, one may, right into .xsession and .xinitrc, grep X's log,
88       for instance:
89
90       WINDOWPATH='$(grep 'using VT number' '/var/log/Xorg.$(echo '$DISPLAY' |
91       sed -e 's/^.*::*\([0-9]*\).*$/\1/').log' | sed -e 's/^.*using VT number
92       \([0-9]*\).*$/\1/')'
93
94       WINDOWPATH and WINDOWID should be propagated when running remote
95       applications via ssh, for instance, along with BRLAPI_HOST and the
96       authorization key (see SendEnv in ssh_config(5) and AcceptEnv in
97       sshd_config(5))
98
99       Returns:
100           the used tty number on success, -1 on error
101
102       See also:
103           brlapi_leaveTtyMode() brlapi_readKey()
104
105   int BRLAPI_STDCALL brlapi_enterTtyModeWithPath (int * ttys, int count,
106       const char * driver)
107       Ask for some tty specified by its path in the tty tree, with some key
108       mechanism
109
110       Parameters:
111           ttys points on the array of ttys representing the tty path to be
112           got. Can be NULL if nttys is 0.
113           count gives the number of elements in ttys.
114           driver has the same meaning as in brlapi_enterTtyMode()
115
116       Providing nttys == 0 means to get the root.
117
118       See also:
119           brlapi_enterTtyMode()
120
121   int BRLAPI_STDCALL brlapi_leaveTtyMode (void)
122       Stop controlling the tty
123
124       Returns:
125           0 on success, -1 on error.
126
127       See also:
128           brlapi_enterTtyMode()
129
130   int BRLAPI_STDCALL brlapi_setFocus (int tty)
131       Tell the current tty to brltty
132
133       This is intended for focus tellers, such as brltty, xbrlapi, screen,
134       ... brlapi_enterTtyMode() must have been called beforehand to tell
135       where this focus applies in the tty tree.
136
137       Returns:
138           0 on success, -1 on error.
139
140       See also:
141           brlapi_enterTtyMode() brlapi_leaveTtyMode()
142
143Version 1.0                       4 Jun 2007    Entering & leaving tty mode(3)