another update from CVS HEAD, for QA
[alioth/jupp.git] / tty.h
1 /*
2  *      TTY interface header file
3  *      Copyright
4  *              (C) 1992 Joseph H. Allen
5  *
6  *      This file is part of JOE (Joe's Own Editor)
7  */
8 #ifndef _JOE_TTY_H
9 #define _JOE_TTY_H 1
10
11 #ifdef EXTERN_CMD_C
12 __IDSTRING(rcsid_tty_h, "$MirOS: contrib/code/jupp/tty.h,v 1.14 2017/12/08 02:04:01 tg Exp $");
13 #endif
14
15 /* void ttopen(void);  Open the tty (attached to stdin) for use inside of JOE
16  *
17  * (0) Call sigjoe()
18  *     There is also 'void ttopnn(void)' which does not do this step.
19  *
20  * (1) fflush(stdout)
21  *
22  * (2) Save the current state of the tty
23  *
24  * (3) Disable CR/LF/NL input translations,
25  *     Disable all output processing,
26  *     Disable echo and line editing, and
27  *     Place tty in character at a time mode.
28  *     (basically, disable all processing except for XON/XOFF if it's set)
29  *
30  * (4) Set this new tty state without loosing any typeahead (by using the
31  *     proper ioctl).
32  *
33  * (5) Store the baud rate in the global variable 'baud'
34  *
35  * (6) Divide the baud rate into the constant DIVIDEND and store the result
36  *     in the global variable 'upc'.  This should come out to the number
37  *     of microseconds needed to send each character.  The constant 'DIVIDEND'
38  *     should be chosen so that 'upc' reflects the real throughput of the
39  *     tty, not the theoretical best throughput.
40  *
41  * (7) Create an output buffer of a size which depends on 'upc' and the
42  *     constant 'TIMES'.  'TIMES' is the number of times per second JOE
43  *     should check for typeahead.  Since we only check for typehead after
44  *     the output buffer is flushed, 'upc' and the size of the output buffer
45  *     determine how often this occurs.  So for example if 'upc'==1000 (~9600
46  *     baud) and 'TIMES'==3, the output buffer size is set to 333 characters.
47  *     Each time this buffer is completely flushed, 1/3 of a second will go by.
48  */
49 void ttopen(void);
50 void ttopnn(void);
51 extern unsigned long upc;
52 extern unsigned baud;
53
54 #define TIMES 3
55 #define DIVIDEND 10000000
56
57 /* void ttclose(void);  Restore the tty back to its original mode.
58  *
59  * (1) ttyflsh()
60  *
61  * (2) Restore the original tty mode which aopen() had saved.  Do this without
62  *     loosing any typeahead.
63  *
64  * (3) Call signrm().  There is also 'void ttyclsn(void)' which does not do
65  *     the this step.
66  */
67 void ttclose(void);
68 void ttclsn(void);
69
70 /* int ttgetc(void);  Flush the output and get the next character from the tty
71  *
72  * (1) ttflsh()
73  *
74  * (2) Read the next input character
75  *     If the input closed, call 'ttsig' with 0 as its argument.
76  *
77  * (3) Clear 'have'
78  */
79 int ttgetc(void);
80
81 /* void ttputc(char c);  Write a character to the output buffer.  If it becomes
82  * full, call ttflsh()
83  */
84 extern int obufp;
85 extern int obufsiz;
86 extern unsigned char *obuf;
87
88 #define ttputc(c) do {          \
89         obuf[obufp++] = (c);    \
90         if (obufp == obufsiz)   \
91                 ttflsh();       \
92 } while (/* CONSTCOND */ 0)
93
94 /* void ttputs(char *s);  Write a string to the output buffer.  Any time the
95  * output buffer gets full, call ttflsh()
96  */
97 void ttputs(unsigned char *s);
98
99 /* void ttsusp(void);  Suspend the process, or if the UNIX can't do it, call
100  * ttshell(NULL)
101  */
102 void ttsusp(void);
103
104 /* int ttflsh(void);  Flush the output buffer and check for typeahead.
105  *
106  * (1) write() any characters in the output buffer to the tty and then sleep
107  *     for the amount of time it should take for the written characters to get
108  *     to the tty.  This is so that any buffering between the editor and the
109  *     tty is defeated.  If this is not done, the screen update will not be
110  *     able to defer for typeahead.
111  *
112  *     The best way to do the sleep (possible only on systems with the
113  *     setitimer call) is to set a timer for the necessary amount, write the
114  *     characters to the tty, and then sleep until the timer expires.
115  *
116  *     If this can't be done, it's usually ok to 'write' and then to sleep for
117  *     the necessary amount of time.  However, you will notice delays in the
118  *     screen update if the 'write' actually takes any significant amount of
119  *     time to execute (it usually takes none since all it usually does is
120  *     write to an operating system output buffer).
121  *
122  * (2) The way we check for typeahead is to put the TTY in nonblocking mode
123  *     and attempt to read a character.  If one could be read, the global
124  *     variable 'have' is set to indicate that there is typeahead pending and
125  *     the character is stored in a single character buffer until ttgetc
126  *     is called.  If the global variable 'leave' is set, the check for
127  *     typeahead is disabled.  This is so that once the program knows that it's
128  *     about to exit, it doesn't eat the first character of your typeahead if
129  *     ttflsh gets called.  'leave' should also be set before shell escapes and
130  *     suspends.
131  */
132 int ttflsh(void);
133
134 extern int have;
135 extern int leave;
136
137 /* void ttsig(int n);  Signal handler you provide.  This is called if the
138  * editor gets a hangup signal, termination signal or if the input closes.
139  * It is called with 'n' set to the number of the caught signal or 0 if the
140  * input closed.
141  */
142 RETSIGTYPE ttsig(int sig) __attribute__((__noreturn__));
143
144 /* void ttgtsz(int *x,int *y);  Get size of screen from ttsize/winsize
145  * structure */
146 void ttgtsz(int *x, int *y);
147
148 /* You don't have to call these: ttopen/ttclose does it for you.  These
149  * may be needed to make your own shell escape sequences.
150  */
151
152 /* void sigjoe(void);  Set the signal handling for joe.  I.E., ignore all
153  * signals the user can generate from the keyboard (SIGINT, SIGPIPE)
154  * and trap the software terminate and hangup signals (SIGTERM, SIGHUP) so
155  * that 'ttsig' gets called.
156  */
157 void sigjoe(void);
158
159 /* void signrm(int inchild);  Set above signals back to their default values.
160  */
161 void signrm(int);
162
163 /* MPX *mpxmk(int fd,int pid,
164  *             void (*func)(),void *object,
165  *             void (*die)(),void *dieobj,
166  *            );
167  *
168  * Create an asynchronous input source handler for a process
169  *   Child process id in 'pid'
170  *   File descriptor to get input from in 'fd'
171  *   Function to call with received characters in 'func'
172  *   Function to call when process dies in 'die'
173  *   The first arg passed to func and die is object and dieobj
174  */
175 MPX *mpxmk(int *ptyfd, const unsigned char *cmd, unsigned char **args,
176     void (*func)(B *, unsigned char *, int), void *object,
177     void (*die)(B *), void *dieobj);
178
179
180 extern int noxon;
181 extern int Baud;
182
183 void tickoff(void);
184 void tickon(void);
185
186 #endif