ncurses 6.2 - patch 20210515
[ncurses.git] / man / curs_terminfo.3x
1 .\"***************************************************************************
2 .\" Copyright 2018-2020,2021 Thomas E. Dickey                                *
3 .\" Copyright 1998-2016,2017 Free Software Foundation, Inc.                  *
4 .\"                                                                          *
5 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
6 .\" copy of this software and associated documentation files (the            *
7 .\" "Software"), to deal in the Software without restriction, including      *
8 .\" without limitation the rights to use, copy, modify, merge, publish,      *
9 .\" distribute, distribute with modifications, sublicense, and/or sell       *
10 .\" copies of the Software, and to permit persons to whom the Software is    *
11 .\" furnished to do so, subject to the following conditions:                 *
12 .\"                                                                          *
13 .\" The above copyright notice and this permission notice shall be included  *
14 .\" in all copies or substantial portions of the Software.                   *
15 .\"                                                                          *
16 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
17 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
18 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
19 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
20 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
21 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
22 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
23 .\"                                                                          *
24 .\" Except as contained in this notice, the name(s) of the above copyright   *
25 .\" holders shall not be used in advertising or otherwise to promote the     *
26 .\" sale, use or other dealings in this Software without prior written       *
27 .\" authorization.                                                           *
28 .\"***************************************************************************
29 .\"
30 .\" $Id: curs_terminfo.3x,v 1.74 2021/03/06 16:05:19 tom Exp $
31 .TH curs_terminfo 3X ""
32 .ie \n(.g .ds `` \(lq
33 .el       .ds `` ``
34 .ie \n(.g .ds '' \(rq
35 .el       .ds '' ''
36 .de bP
37 .ie n  .IP \(bu 4
38 .el    .IP \(bu 2
39 ..
40 .ds n 5
41 .na
42 .hy 0
43 .SH NAME
44 \fBdel_curterm\fR,
45 \fBmvcur\fR,
46 \fBputp\fR,
47 \fBrestartterm\fR,
48 \fBset_curterm\fR,
49 \fBsetupterm\fR,
50 \fBtigetflag\fR,
51 \fBtigetnum\fR,
52 \fBtigetstr\fR,
53 \fBtiparm\fR,
54 \fBtparm\fR,
55 \fBtputs\fR,
56 \fBvid_attr\fR,
57 \fBvid_puts\fR,
58 \fBvidattr\fR,
59 \fBvidputs\fR \- \fBcurses\fR interfaces to terminfo database
60 .ad
61 .hy
62 .SH SYNOPSIS
63 .nf
64 \fB#include <curses.h>\fR
65 \fB#include <term.h>\fR
66 .sp
67 \fBTERMINAL *cur_term;\fR
68 .sp
69 \fBconst char * const boolnames[];\fP
70 \fBconst char * const boolcodes[];\fP
71 \fBconst char * const boolfnames[];\fP
72 \fBconst char * const numnames[];\fP
73 \fBconst char * const numcodes[];\fP
74 \fBconst char * const numfnames[];\fP
75 \fBconst char * const strnames[];\fP
76 \fBconst char * const strcodes[];\fP
77 \fBconst char * const strfnames[];\fP
78 .sp
79 \fBint setupterm(const char *\fR\fIterm\fR\fB, int \fR\fIfiledes\fR\fB, int *\fR\fIerrret\fR\fB);\fR
80 .br
81 \fBTERMINAL *set_curterm(TERMINAL *\fR\fInterm\fR\fB);\fR
82 .br
83 \fBint del_curterm(TERMINAL *\fR\fIoterm\fR\fB);\fR
84 .br
85 \fBint restartterm(const char *\fR\fIterm\fR\fB, int \fR\fIfiledes\fR\fB, int *\fR\fIerrret\fR\fB);\fR
86 .sp
87 \fBchar *tparm(const char *\fR\fIstr\fR\fB, ...);\fR
88 .br
89 \fBint tputs(const char *\fR\fIstr\fR\fB, int \fR\fIaffcnt\fR\fB, int (*\fR\fIputc\fR\fB)(int));\fR
90 .br
91 \fBint putp(const char *\fR\fIstr\fR\fB);\fR
92 .sp
93 \fBint vidputs(chtype \fR\fIattrs\fR\fB, int (*\fR\fIputc\fR\fB)(int));\fR
94 .br
95 \fBint vidattr(chtype \fR\fIattrs\fR\fB);\fR
96 .br
97 \fBint vid_puts(attr_t \fR\fIattrs\fR\fB, short \fR\fIpair\fR\fB, void *\fR\fIopts\fR\fB, int (*\fR\fIputc\fR\fB)(int));\fR
98 .br
99 \fBint vid_attr(attr_t \fR\fIattrs\fR\fB, short \fR\fIpair\fR\fB, void *\fR\fIopts\fR\fB);\fR
100 .sp
101 \fBint mvcur(int \fR\fIoldrow\fR\fB, int \fR\fIoldcol\fR\fB, int \fR\fInewrow\fR, int \fR\fInewcol\fR\fB);\fR
102 .sp
103 \fBint tigetflag(const char *\fR\fIcapname\fR\fB);\fR
104 .br
105 \fBint tigetnum(const char *\fR\fIcapname\fR\fB);\fR
106 .br
107 \fBchar *tigetstr(const char *\fR\fIcapname\fR\fB);\fR
108 .sp
109 \fBchar *tiparm(const char *\fR\fIstr\fR\fB, ...);\fR
110 .br
111 .fi
112 .SH DESCRIPTION
113 These low-level routines must be called by programs that have to deal
114 directly with the \fBterminfo\fR database to handle certain terminal
115 capabilities, such as programming function keys.
116 For all other
117 functionality, \fBcurses\fR routines are more suitable and their use is
118 recommended.
119 .PP
120 None of these functions use (or are aware of) multibyte character strings
121 such as UTF-8:
122 .bP
123 capability names use the POSIX portable character set
124 .bP
125 capability string values have no associated encoding;
126 they are strings of 8-bit characters.
127 .SS Initialization
128 .PP
129 Initially, \fBsetupterm\fR should be called.
130 The high-level curses functions \fBinitscr\fR and
131 \fBnewterm\fR call \fBsetupterm\fP to initialize the
132 low-level set of terminal-dependent variables
133 [listed in \fBterminfo\fR(\*n)].
134 .PP
135 Applications can use the
136 terminal capabilities either directly (via header definitions),
137 or by special functions.
138 The header files \fBcurses.h\fR and \fBterm.h\fR should be included (in this
139 order) to get the definitions for these strings, numbers, and flags.
140 .PP
141 The \fBterminfo\fR variables
142 \fBlines\fR and \fBcolumns\fR are initialized by \fBsetupterm\fR as
143 follows:
144 .bP
145 If \fBuse_env(FALSE)\fR has been called, values for
146 \fBlines\fR and \fBcolumns\fR specified in \fBterminfo\fR are used.
147 .bP
148 Otherwise, if the environment variables \fBLINES\fR and \fBCOLUMNS\fR
149 exist, their values are used.
150 If these environment variables do not
151 exist and the program is running in a window, the current window size
152 is used.
153 Otherwise, if the environment variables do not exist, the
154 values for \fBlines\fR and \fBcolumns\fR specified in the
155 \fBterminfo\fR database are used.
156 .PP
157 Parameterized strings should be passed through \fBtparm\fR to instantiate them.
158 All \fBterminfo\fR strings
159 (including the output of \fBtparm\fR)
160 should be printed
161 with \fBtputs\fR or \fBputp\fR.
162 Call \fBreset_shell_mode\fR to restore the
163 tty modes before exiting [see \fBcurs_kernel\fR(3X)].
164 .PP
165 Programs which use
166 cursor addressing should
167 .bP
168 output \fBenter_ca_mode\fR upon startup and
169 .bP
170 output \fBexit_ca_mode\fR before exiting.
171 .PP
172 Programs which execute shell subprocesses should
173 .bP
174 call \fBreset_shell_mode\fR and
175 output \fBexit_ca_mode\fR before the shell
176 is called and
177 .bP
178 output \fBenter_ca_mode\fR and
179 call \fBreset_prog_mode\fR after returning from the shell.
180 .PP
181 The \fBsetupterm\fR routine reads in the \fBterminfo\fR database,
182 initializing the \fBterminfo\fR structures, but does not set up the
183 output virtualization structures used by \fBcurses\fR.
184 These are its parameters:
185 .RS 3
186 .TP 5
187 \fIterm\fP
188 is the terminal type, a character string.
189 If \fIterm\fR is null, the environment variable \fBTERM\fR is used.
190 .TP 5
191 \fIfiledes\fP
192 is the file descriptor used for all output.
193 .TP 5
194 \fIerrret\fP
195 points to an optional location where an error status can be returned to
196 the caller.
197 If \fIerrret\fR is not null,
198 then \fBsetupterm\fR returns \fBOK\fR or
199 \fBERR\fR and stores a status value in the integer pointed to by
200 \fIerrret\fR.
201 A return value of \fBOK\fR combined with status of \fB1\fR in \fIerrret\fR
202 is normal.
203 .IP
204 If \fBERR\fR is returned, examine \fIerrret\fR:
205 .RS
206 .TP 5
207 .B 1
208 means that the terminal is hardcopy, cannot be used for curses applications.
209 .IP
210 \fBsetupterm\fP determines if the entry is a hardcopy type by
211 checking the \fBhc\fP (\fBhardcopy\fP) capability.
212 .TP 5
213 .B 0
214 means that the terminal could not be found,
215 or that it is a generic type,
216 having too little information for curses applications to run.
217 .IP
218 \fBsetupterm\fP determines if the entry is a generic type by
219 checking the \fBgn\fP (\fBgeneric\fP) capability.
220 .TP 5
221 .B \-1
222 means that the \fBterminfo\fR database could not be found.
223 .RE
224 .IP
225 If \fIerrret\fR is
226 null, \fBsetupterm\fR prints an error message upon finding an error
227 and exits.
228 Thus, the simplest call is:
229 .sp
230       \fBsetupterm((char *)0, 1, (int *)0);\fR,
231 .sp
232 which uses all the defaults and sends the output to \fBstdout\fR.
233 .RE
234 .\" ***************************************************************************
235 .SS The Terminal State
236 .PP
237 The \fBsetupterm\fR routine stores its information about the terminal
238 in a \fBTERMINAL\fP structure pointed to by the global variable \fBcur_term\fP.
239 If it detects an error,
240 or decides that the terminal is unsuitable (hardcopy or generic),
241 it discards this information,
242 making it not available to applications.
243 .PP
244 If \fBsetupterm\fP is called repeatedly for the same terminal type,
245 it will reuse the information.
246 It maintains only one copy of a given terminal's capabilities in memory.
247 If it is called for different terminal types,
248 \fBsetupterm\fP allocates new storage for each set of terminal capabilities.
249 .PP
250 The \fBset_curterm\fR routine sets \fBcur_term\fR to
251 \fInterm\fR, and makes all of the \fBterminfo\fR boolean, numeric, and
252 string variables use the values from \fInterm\fR.
253 It returns the old value of \fBcur_term\fR.
254 .PP
255 The \fBdel_curterm\fR routine frees the space pointed to by
256 \fIoterm\fR and makes it available for further use.
257 If \fIoterm\fR is
258 the same as \fBcur_term\fR, references to any of the \fBterminfo\fR
259 boolean, numeric, and string variables thereafter may refer to invalid
260 memory locations until another \fBsetupterm\fR has been called.
261 .PP
262 The \fBrestartterm\fR routine is similar to \fBsetupterm\fR and \fBinitscr\fR,
263 except that it is called after restoring memory to a previous state (for
264 example, when reloading a game saved as a core image dump).
265 \fBrestartterm\fP assumes that the windows and the input and output options
266 are the same as when memory was saved,
267 but the terminal type and baud rate may be different.
268 Accordingly, \fBrestartterm\fP saves various tty state bits,
269 calls \fBsetupterm\fP, and then restores the bits.
270 .\" ***************************************************************************
271 .SS Formatting Output
272 .PP
273 The \fBtparm\fR routine instantiates the string \fIstr\fR with
274 parameters \fIpi\fR.  A pointer is returned to the result of \fIstr\fR
275 with the parameters applied.
276 Application developers should keep in mind these quirks of the interface:
277 .bP
278 Although \fBtparm\fP's actual parameters may be integers or strings,
279 the prototype expects \fBlong\fP (integer) values.
280 .bP
281 Aside from the \fBset_attributes\fP (\fBsgr\fP) capability,
282 most terminal capabilities require no more than one or two parameters.
283 .bP
284 Padding information is ignored by \fBtparm\fP;
285 it is interpreted by \fBtputs\fP.
286 .bP
287 The capability string is null-terminated.
288 Use \*(``\\200\*('' where an ASCII NUL is needed in the output.
289 .PP
290 \fBtiparm\fP is a newer form of \fBtparm\fP which uses \fI<stdarg.h>\fP
291 rather than a fixed-parameter list.
292 Its numeric parameters are integers (int) rather than longs.
293 .\" ***************************************************************************
294 .SS Output Functions
295 .PP
296 The \fBtputs\fR routine applies padding information
297 (i.e., by interpreting marker embedded in the terminfo capability
298 such as \*(``$<5>\*('' as 5 milliseconds)
299 to the string
300 \fIstr\fR and outputs it:
301 .bP
302 The \fIstr\fR parameter must be a terminfo string
303 variable or the return value from
304 \fBtparm\fR, \fBtiparm\fP, \fBtgetstr\fR, or \fBtgoto\fR.
305 .IP
306 The \fBtgetstr\fP and \fBtgoto\fP functions are part of the \fItermcap\fP
307 interface,
308 which happens to share this function name with the \fIterminfo\fP interface.
309 .bP
310 \fIaffcnt\fR is the number of lines affected, or 1 if
311 not applicable.
312 .bP
313 \fIputc\fR is a \fBputchar\fR-like routine to which
314 the characters are passed, one at a time.
315 .PP
316 The \fBputp\fR routine calls \fBtputs(\fR\fIstr\fR\fB, 1, putchar)\fR.
317 The output of \fBputp\fR always goes to \fBstdout\fR, rather than
318 the \fIfiledes\fR specified in \fBsetupterm\fR.
319 .PP
320 The \fBvidputs\fR routine displays the string on the terminal in the
321 video attribute mode \fIattrs\fR, which is any combination of the
322 attributes listed in \fBcurses\fR(3X).
323 The characters are passed to
324 the \fBputchar\fR-like routine \fIputc\fR.
325 .PP
326 The \fBvidattr\fR routine is like the \fBvidputs\fR routine, except
327 that it outputs through \fBputchar\fR.
328 .PP
329 The \fBvid_attr\fR and \fBvid_puts\fR routines correspond
330 to vidattr and vidputs, respectively.
331 They use a set of arguments for representing the video attributes plus color,
332 i.e.,
333 .bP
334 \fIattrs\fP of type \fBattr_t\fP for the attributes and
335 .bP
336 \fIpair\fP of type \fBshort\fP for the color-pair number.
337 .PP
338 The \fBvid_attr\fR and \fBvid_puts\fR routines
339 are designed to use the attribute constants with the \fIWA_\fR prefix.
340 .PP
341 X/Open Curses reserves the \fIopts\fP argument for future use,
342 saying that applications must provide a null pointer for that argument.
343 As an extension,
344 this implementation allows \fIopts\fP to be used as a pointer to \fBint\fP,
345 which overrides the \fIpair\fP (\fBshort\fP) argument.
346 .PP
347 The \fBmvcur\fR routine provides low-level cursor motion.
348 It takes effect immediately (rather than at the next refresh).
349 .PP
350 While \fBputp\fR and \fBmvcur\fP are low-level functions which
351 do not use the high-level curses state,
352 they are declared in \fB<curses.h>\fP because SystemV did this
353 (see \fBHISTORY\fP).
354 .\" ***************************************************************************
355 .SS Terminal Capability Functions
356 .PP
357 The \fBtigetflag\fR, \fBtigetnum\fR and \fBtigetstr\fR routines return
358 the value of the capability corresponding to the \fBterminfo\fR
359 \fIcapname\fR passed to them, such as \fBxenl\fR.
360 The \fIcapname\fR for each capability is given in the table column entitled
361 \fIcapname\fR code in the capabilities section of \fBterminfo\fR(\*n).
362 .PP
363 These routines return special values to denote errors.
364 .PP
365 The \fBtigetflag\fR routine returns
366 .TP
367 \fB\-1\fR
368 if \fIcapname\fR is not a boolean capability,
369 or
370 .TP
371 \fB0\fR
372 if it is canceled or absent from the terminal description.
373 .PP
374 The \fBtigetnum\fR routine returns
375 .TP
376 \fB\-2\fR
377 if \fIcapname\fR is not a numeric capability, or
378 .TP
379 \fB\-1\fR
380 if it is canceled or absent from the terminal description.
381 .PP
382 The \fBtigetstr\fR routine returns
383 .TP
384 \fB(char *)\-1\fR
385 if \fIcapname\fR is not a string capability,
386 or
387 .TP
388 \fB0\fR
389 if it is canceled or absent from the terminal description.
390 .\" ***************************************************************************
391 .SS Terminal Capability Names
392 .PP
393 These null-terminated arrays contain
394 .bP
395 the short terminfo names (\*(``codes\*(''),
396 .bP
397 the \fBtermcap\fR names (\*(``names\*(''), and
398 .bP
399 the long terminfo names (\*(``fnames\*('')
400 .PP
401 for each of the predefined \fBterminfo\fR variables:
402 .sp
403 .RS
404 \fBconst char *boolnames[]\fR, \fB*boolcodes[]\fR, \fB*boolfnames[]\fR
405 .br
406 \fBconst char *numnames[]\fR, \fB*numcodes[]\fR, \fB*numfnames[]\fR
407 .br
408 \fBconst char *strnames[]\fR, \fB*strcodes[]\fR, \fB*strfnames[]\fR
409 .RE
410 .SH RETURN VALUE
411 Routines that return an integer return \fBERR\fR upon failure and \fBOK\fR
412 (SVr4 only specifies \*(``an integer value other than \fBERR\fR\*('')
413 upon successful completion,
414 unless otherwise noted in the preceding routine descriptions.
415 .PP
416 Routines that return pointers always return \fBNULL\fR on error.
417 .PP
418 X/Open defines no error conditions.
419 In this implementation
420 .RS 3
421 .TP 5
422 \fBdel_curterm\fP
423 returns an error
424 if its terminal parameter is null.
425 .TP 5
426 \fBputp\fP
427 calls \fBtputs\fP, returning the same error-codes.
428 .TP 5
429 \fBrestartterm\fP
430 returns an error
431 if the associated call to \fBsetupterm\fP returns an error.
432 .TP 5
433 \fBsetupterm\fP
434 returns an error
435 if it cannot allocate enough memory, or
436 create the initial windows (stdscr, curscr, newscr).
437 Other error conditions are documented above.
438 .TP 5
439 \fBtputs\fP
440 returns an error if the string parameter is null.
441 It does not detect I/O errors:
442 X/Open states that \fBtputs\fP ignores the return value
443 of the output function \fIputc\fP.
444 .RE
445 .\" ***************************************************************************
446 .SS Compatibility macros
447 This implementation provides a few macros for compatibility with systems
448 before SVr4 (see \fBHISTORY\fP).
449 Those include
450 \fBcrmode\fP,
451 \fBfixterm\fP,
452 \fBgettmode\fP,
453 \fBnocrmode\fP,
454 \fBresetterm\fP,
455 \fBsaveterm\fP, and
456 \fBsetterm\fP.
457 .PP
458 In SVr4, those are found in \fB<curses.h>\fP,
459 but except for \fBsetterm\fR, are likewise macros.
460 The one function, \fBsetterm\fR, is mentioned in the manual page.
461 The manual page notes that the \fBsetterm\fR routine
462 was replaced by \fBsetupterm\fR, stating that the call:
463 .sp
464       \fBsetupterm(\fR\fIterm\fR\fB, 1, (int *)0)\fR
465 .sp
466 provides the same functionality as \fBsetterm(\fR\fIterm\fR\fB)\fR,
467 and is not recommended for new programs.
468 This implementation provides each of those symbols
469 as macros for BSD compatibility,
470 .\" ***************************************************************************
471 .SH HISTORY
472 .PP
473 SVr2 introduced the terminfo feature.
474 Its programming manual mentioned these low-level functions:
475 .TS
476 l l
477 _ _
478 l l.
479 \fBFunction\fR  \fBDescription\fR
480 fixterm restore tty to \*(``in curses\*('' state
481 gettmode        establish current tty modes
482 mvcur   low level cursor motion
483 putp    T{
484 utility function that uses \fBtputs\fP to send characters via \fBputchar\fP.
485 T}
486 resetterm       set tty modes to \*(``out of curses\*('' state
487 resetty reset tty flags to stored value
488 saveterm        save current modes as \*(``in curses\*('' state
489 savetty store current tty flags
490 setterm establish terminal with given type
491 setupterm       establish terminal with given type
492 tparm   instantiate a string expression with parameters
493 tputs   apply padding information to a string
494 vidattr like \fBvidputs\fP, but outputs through \fBputchar\fP
495 vidputs T{
496 output a string to put terminal in a specified video attribute mode
497 T}
498 .TE
499 .PP
500 The programming manual also mentioned
501 functions provided for termcap compatibility
502 (commenting that they \*(``may go away at a later date\*(''):
503 .TS
504 l l
505 _ _
506 l l.
507 \fBFunction\fR  \fBDescription\fR
508 tgetent look up termcap entry for given \fIname\fP
509 tgetflag        get boolean entry for given \fIid\fP
510 tgetnum get numeric entry for given \fIid\fP
511 tgetstr get string entry for given \fIid\fP
512 tgoto   apply parameters to given capability
513 tputs   T{
514 apply padding to capability, calling a function to put characters
515 T}
516 .TE
517 .PP
518 Early terminfo programs obtained capability values from the
519 \fBTERMINAL\fP structure initialized by \fBsetupterm\fR.
520 .PP
521 SVr3 extended terminfo by adding functions to retrieve capability values
522 (like the termcap interface),
523 and reusing tgoto and tputs:
524 .TS
525 l l
526 _ _
527 l l.
528 \fBFunction\fR  \fBDescription\fR
529 tigetflag       get boolean entry for given \fIid\fP
530 tigetnum        get numeric entry for given \fIid\fP
531 tigetstr        get string entry for given \fIid\fP
532 .TE
533 .PP
534 SVr3 also replaced several of the SVr2 terminfo functions
535 which had no counterpart in the termcap interface,
536 documenting them as obsolete:
537 .TS
538 l l
539 _ _
540 l l.
541 \fBFunction\fR  \fBReplaced by\fP
542 crmode  cbreak  
543 fixterm reset_prog_mode 
544 gettmode        N/A     
545 nocrmode        nocbreak        
546 resetterm       reset_shell_mode        
547 saveterm        def_prog_mode   
548 setterm setupterm       
549 .TE
550 .PP
551 SVr3 kept the \fBmvcur\fP, \fBvidattr\fP and \fBvidputs\fP functions,
552 along with \fBputp\fP, \fBtparm\fP and \fBtputs\fP.
553 The latter were needed to support padding,
554 and handling functions such as \fBvidattr\fP
555 (which used more than the two parameters supported by \fBtgoto\fP).
556 .PP
557 SVr3 introduced the functions for switching between terminal
558 descriptions, e.g., \fBset_curterm\fP.
559 The various global variables such as \fBboolnames\fP were mentioned
560 in the programming manual at this point.
561 .PP
562 SVr4 added the \fBvid_attr\fP and \fBvid_puts\fP functions.
563 .PP
564 There are other low-level functions declared in the curses header files
565 on Unix systems,
566 but none were documented.
567 The functions marked \*(``obsolete\*('' remained in use
568 by the Unix \fBvi\fP editor.
569 .SH PORTABILITY
570 .SS Legacy functions
571 .PP
572 X/Open notes that \fBvidattr\fR and \fBvidputs\fR may be macros.
573 .PP
574 The function \fBsetterm\fR is not described by X/Open and must
575 be considered non-portable.
576 All other functions are as described by X/Open.
577 .SS Legacy data
578 .PP
579 \fBsetupterm\fP copies the terminal name to the array \fBttytype\fP.
580 This is not part of X/Open Curses, but is assumed by some applications.
581 .PP
582 Other implementions may not declare the capability name arrays.
583 Some provide them without declaring them.
584 X/Open does not specify them.
585 .PP
586 Extended terminal capability names, e.g., as defined by \fB@TIC@\ \-x\fP,
587 are not stored in the arrays described here.
588 .SS Output buffering
589 .PP
590 Older versions of \fBncurses\fP assumed that the file descriptor passed to
591 \fBsetupterm\fP from \fBinitscr\fP or \fBnewterm\fP uses buffered I/O,
592 and would write to the corresponding stream.
593 In addition to the limitation that the terminal was left in block-buffered
594 mode on exit (like System V curses),
595 it was problematic because \fBncurses\fP
596 did not allow a reliable way to cleanup on receiving SIGTSTP.
597 .PP
598 The current version (ncurses6)
599 uses output buffers managed directly by \fBncurses\fP.
600 Some of the low-level functions described in this manual page write
601 to the standard output.
602 They are not signal-safe.
603 The high-level functions in \fBncurses\fP use
604 alternate versions of these functions
605 using the more reliable buffering scheme.
606 .SS Function prototypes
607 .PP
608 The X/Open Curses prototypes are based on the SVr4 curses header declarations,
609 which were defined at the same time the C language was first standardized in
610 the late 1980s.
611 .bP
612 X/Open Curses uses \fBconst\fP less effectively than a later design might,
613 in some cases applying it needlessly to values are already constant,
614 and in most cases overlooking parameters which normally would use \fBconst\fP.
615 Using constant parameters for functions which do not use \fBconst\fP
616 may prevent the program from compiling.
617 On the other hand, \fIwritable strings\fP are an obsolescent feature.
618 .IP
619 As an extension, this implementation can be configured to change the
620 function prototypes to use the \fBconst\fP keyword.
621 The ncurses ABI 6 enables this feature by default.
622 .bP
623 X/Open Curses prototypes \fBtparm\fR with a fixed number of parameters,
624 rather than a variable argument list.
625 .IP
626 This implementation uses a variable argument list, but can be
627 configured to use the fixed-parameter list.
628 Portable applications should provide 9 parameters after the format;
629 zeroes are fine for this purpose.
630 .IP
631 In response to review comments by Thomas E. Dickey,
632 X/Open Curses Issue 7 proposed the \fBtiparm\fP function in mid-2009.
633 .SS Special TERM treatment
634 .PP
635 If configured to use the terminal-driver,
636 e.g., for the MinGW port,
637 .bP
638 \fBsetupterm\fP interprets a missing/empty TERM variable as the
639 special value \*(``unknown\*(''.
640 .bP
641 \fBsetupterm\fP allows explicit use of the
642 the windows console driver by checking if $TERM is set to
643 \*(``#win32con\*('' or an abbreviation of that string.
644 .SS Other portability issues
645 .PP
646 In System V Release 4, \fBset_curterm\fR has an \fBint\fR return type and
647 returns \fBOK\fR or \fBERR\fR.  We have chosen to implement the X/Open Curses
648 semantics.
649 .PP
650 In System V Release 4, the third argument of \fBtputs\fR has the type
651 \fBint (*putc)(char)\fR.
652 .PP
653 At least one implementation of X/Open Curses (Solaris) returns a value
654 other than \fBOK\fP/\fBERR\fP from \fBtputs\fP.
655 That returns the length of the string, and does no error-checking.
656 .PP
657 X/Open notes that after calling \fBmvcur\fR, the curses state may not match the
658 actual terminal state, and that an application should touch and refresh
659 the window before resuming normal curses calls.
660 Both \fBncurses\fP and System V Release 4 curses implement \fBmvcur\fR using
661 the SCREEN data allocated in either \fBinitscr\fR or \fBnewterm\fR.
662 So though it is documented as a terminfo function,
663 \fBmvcur\fR is really a curses function which is not well specified.
664 .PP
665 X/Open states that the old location must be given for \fBmvcur\fP.
666 This implementation allows the caller to use \-1's for the old ordinates.
667 In that case, the old location is unknown.
668 .SH SEE ALSO
669 \fBcurses\fR(3X),
670 \fBcurs_initscr\fR(3X),
671 \fBcurs_kernel\fR(3X),
672 \fBcurs_termcap\fR(3X),
673 \fBcurs_variables\fR(3X),
674 \fBterm_variables\fR(3X),
675 \fBputc\fR(3),
676 \fBterminfo\fR(\*n)