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