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