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