.\"***************************************************************************
-.\" Copyright 2018-2020,2021 Thomas E. Dickey *
+.\" Copyright 2018-2022,2023 Thomas E. Dickey *
.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_terminfo.3x,v 1.79 2021/12/25 21:34:58 tom Exp $
+.\" $Id: curs_terminfo.3x,v 1.87 2023/06/10 15:51:45 tom Exp $
.TH curs_terminfo 3X ""
.ie \n(.g .ds `` \(lq
.el .ds `` ``
\fBtigetnum\fP,
\fBtigetstr\fP,
\fBtiparm\fP,
+\fBtiparm_s\fP,
+\fBtiscan_s\fP,
\fBtparm\fP,
\fBtputs\fP,
\fBvid_attr\fP,
\fBconst char * const strcodes[];\fP
\fBconst char * const strfnames[];\fP
.sp
-\fBint setupterm(const char *\fP\fIterm\fP\fB, int \fP\fIfiledes\fP\fB, int *\fP\fIerrret\fP\fB);\fP
+\fBint setupterm(const char *\fIterm\fB, int \fIfiledes\fB, int *\fIerrret\fB);\fR
.br
-\fBTERMINAL *set_curterm(TERMINAL *\fP\fInterm\fP\fB);\fP
+\fBTERMINAL *set_curterm(TERMINAL *\fInterm\fB);\fR
.br
-\fBint del_curterm(TERMINAL *\fP\fIoterm\fP\fB);\fP
+\fBint del_curterm(TERMINAL *\fIoterm\fB);\fR
.br
-\fBint restartterm(const char *\fP\fIterm\fP\fB, int \fP\fIfiledes\fP\fB, int *\fP\fIerrret\fP\fB);\fP
+\fBint restartterm(const char *\fIterm\fB, int \fIfiledes\fB, int *\fIerrret\fB);\fR
.sp
-\fBchar *tparm(const char *\fP\fIstr\fP\fB, ...);\fP
+\fBchar *tparm(const char *\fIstr\fB, ...);\fR
.br
-\fBint tputs(const char *\fP\fIstr\fP\fB, int \fP\fIaffcnt\fP\fB, int (*\fP\fIputc\fP\fB)(int));\fP
+ \fIor\fP
.br
-\fBint putp(const char *\fP\fIstr\fP\fB);\fP
+\fBchar *tparm(const char *\fIstr\fB, long \fIp1 ... \fBlong \fIp9\fB);\fR
.sp
-\fBint vidputs(chtype \fP\fIattrs\fP\fB, int (*\fP\fIputc\fP\fB)(int));\fP
+\fBint tputs(const char *\fIstr\fB, int \fIaffcnt\fB, int (*\fIputc\fB)(int));\fR
.br
-\fBint vidattr(chtype \fP\fIattrs\fP\fB);\fP
+\fBint putp(const char *\fIstr\fB);\fR
+.sp
+\fBint vidputs(chtype \fIattrs\fB, int (*\fIputc\fB)(int));\fR
+.br
+\fBint vidattr(chtype \fIattrs\fB);\fR
.br
-\fBint vid_puts(attr_t \fP\fIattrs\fP\fB, short \fP\fIpair\fP\fB, void *\fP\fIopts\fP\fB, int (*\fP\fIputc\fP\fB)(int));\fP
+\fBint vid_puts(attr_t \fIattrs\fB, short \fIpair\fB, void *\fIopts\fB, int (*\fIputc\fB)(int));\fR
.br
-\fBint vid_attr(attr_t \fP\fIattrs\fP\fB, short \fP\fIpair\fP\fB, void *\fP\fIopts\fP\fB);\fP
+\fBint vid_attr(attr_t \fIattrs\fB, short \fIpair\fB, void *\fIopts\fB);\fR
.sp
-\fBint mvcur(int \fP\fIoldrow\fP\fB, int \fP\fIoldcol\fP\fB, int \fP\fInewrow\fP, int \fP\fInewcol\fP\fB);\fP
+\fBint mvcur(int \fIoldrow\fB, int \fIoldcol\fB, int \fInewrow\fR, int \fInewcol\fB);\fR
.sp
-\fBint tigetflag(const char *\fP\fIcapname\fP\fB);\fP
+\fBint tigetflag(const char *\fIcapname\fB);\fR
.br
-\fBint tigetnum(const char *\fP\fIcapname\fP\fB);\fP
+\fBint tigetnum(const char *\fIcapname\fB);\fR
.br
-\fBchar *tigetstr(const char *\fP\fIcapname\fP\fB);\fP
+\fBchar *tigetstr(const char *\fIcapname\fB);\fR
.sp
-\fBchar *tiparm(const char *\fP\fIstr\fP\fB, ...);\fP
+\fBchar *tiparm(const char *\fIstr\fB, ...);\fR
+.sp
+/* extensions */
+.br
+\fBchar *tiparm_s(int \fIexpected\fB, int \fImask\fB, const char *\fIstr\fB, ...);\fR
+.br
+\fBint tiscan_s(int *\fIexpected\fB, int *\fImask\fB, const char *\fIstr\fB);\fR
.br
.fi
.SH DESCRIPTION
If \fIterm\fP is null, the environment variable \fBTERM\fP is used.
.TP 5
\fIfiledes\fP
-is the file descriptor used for all output.
+is the file descriptor used for getting and setting terminal I/O modes.
+.IP
+Higher-level applications use \fBnewterm\fP(3X) for initializing the terminal,
+passing an output \fIstream\fP rather than a \fIdescriptor\fP.
+In curses, the two are the same because \fBnewterm\fP calls \fBsetupterm\fP,
+passing the file descriptor derived from its output stream parameter.
.TP 5
\fIerrret\fP
points to an optional location where an error status can be returned to
having too little information for curses applications to run.
.IP
\fBsetupterm\fP determines if the entry is a generic type by
-checking the \fBgn\fP (\fBgeneric\fP) capability.
+checking the \fBgn\fP (\fBgeneric_type\fP) capability.
.TP 5
.B \-1
means that the \fBterminfo\fP database could not be found.
\fBtiparm\fP is a newer form of \fBtparm\fP which uses \fI<stdarg.h>\fP
rather than a fixed-parameter list.
Its numeric parameters are integers (int) rather than longs.
+.PP
+Both \fBtparm\fP and \fBtiparm\fP assume that the application passes
+parameters consistent with the terminal description.
+Two extensions are provided as alternatives to deal with untrusted data:
+.bP
+\fBtiparm_s\fP is an extension which is a safer formatting function
+than \fBtparm\fR or \fBtiparm\fR,
+because it allows the developer to tell the curses
+library how many parameters to expect in the parameter list,
+and which may be string parameters.
+.IP
+The \fImask\fP parameter has one bit set for each of the parameters
+(up to 9) which will be passed as char* rather than numbers.
+.bP
+The extension \fBtiscan_s\fP allows the application
+to inspect a formatting capability to see what the curses library would assume.
.\" ***************************************************************************
.SS Output Functions
.PP
\fIputc\fP is a \fBputchar\fP-like routine to which
the characters are passed, one at a time.
.PP
-The \fBputp\fP routine calls \fBtputs(\fP\fIstr\fP\fB, 1, putchar)\fP.
+The \fBputp\fR routine calls \fBtputs(\fIstr\fB, 1, putchar)\fR.
The output of \fBputp\fP always goes to \fBstdout\fP, rather than
the \fIfiledes\fP specified in \fBsetupterm\fP.
.PP
.PP
The \fBmvcur\fP routine provides low-level cursor motion.
It takes effect immediately (rather than at the next refresh).
+Unlike the other low-level output functions,
+which either write to the standard output or pass an output function parameter,
+\fBmvcur\fP uses an output file descriptor derived from
+the output stream parameter of \fBnewterm\fP(3X).
.PP
While \fBputp\fP and \fBmvcur\fP are low-level functions which
do not use the high-level curses state,
.br
\fBconst char *strnames[]\fP, \fB*strcodes[]\fP, \fB*strfnames[]\fP
.RE
+.\" ***************************************************************************
+.SS Releasing Memory
+Each successful call to \fBsetupterm\fP allocates memory to hold the terminal
+description.
+As a side-effect, it sets \fBcur_term\fP to point to this memory.
+If an application calls
+.sp
+ \fBdel_curterm(cur_term);\fP
+.sp
+the memory will be freed.
+.PP
+The formatting functions \fBtparm\fP and \fBtiparm\fP extend the storage
+allocated by \fBsetupterm\fP:
+.bP
+the \*(``static\*('' terminfo variables [a-z].
+Before ncurses 6.3, those were shared by all screens.
+With ncurses 6.3, those are allocated per screen.
+See \fBterminfo\fP(\*n) for details.
+.bP
+to improve performance, ncurses 6.3 caches the result of analyzing terminfo
+strings for their parameter types.
+That is stored as a binary tree referenced from the \fBTERMINAL\fP structure.
+.PP
+The higher-level \fBinitscr\fP and \fBnewterm\fP functions use \fBsetupterm\fP.
+Normally they do not free this memory, but it is possible to do that using
+the \fBdelscreen\fP(3X) function.
+.\" ***************************************************************************
.SH RETURN VALUE
Routines that return an integer return \fBERR\fP upon failure and \fBOK\fP
(SVr4 only specifies \*(``an integer value other than \fBERR\fP\*('')
create the initial windows (stdscr, curscr, newscr).
Other error conditions are documented above.
.TP 5
+\fBtparm\fP
+returns a null if the capability would require unexpected parameters,
+e.g., too many, too few, or incorrect types
+(strings where integers are expected, or vice versa).
+.TP 5
\fBtputs\fP
returns an error if the string parameter is null.
It does not detect I/O errors:
The manual page notes that the \fBsetterm\fP routine
was replaced by \fBsetupterm\fP, stating that the call:
.sp
- \fBsetupterm(\fP\fIterm\fP\fB, 1, (int *)0)\fP
+ \fBsetupterm(\fIterm\fB, 1, (int *)0)\fR
.sp
-provides the same functionality as \fBsetterm(\fP\fIterm\fP\fB)\fP,
+provides the same functionality as \fBsetterm(\fIterm\fB)\fR,
and is not recommended for new programs.
This implementation provides each of those symbols
as macros for BSD compatibility,
The functions marked \*(``obsolete\*('' remained in use
by the Unix \fBvi\fP(1) editor.
.SH PORTABILITY
+.SS Extensions
+The functions marked as extensions were designed for \fBncurses\fP(3X),
+and are not found in SVr4 curses, 4.4BSD curses,
+or any other previous version of curses.
+.PP
.SS Legacy functions
.PP
X/Open notes that \fBvidattr\fP and \fBvidputs\fP may be macros.
.IP
In response to review comments by Thomas E. Dickey,
X/Open Curses Issue 7 proposed the \fBtiparm\fP function in mid-2009.
+.IP
+While \fBtiparm\fP is always provided in ncurses,
+the older form is only available as a build-time configuration option.
+If not specially configured, \fBtparm\fP is the same as \fBtiparm\fP.
+.PP
+Both forms of \fBtparm\fP have drawbacks:
+.bP
+Most of the calls to \fBtparm\fP use only one or two parameters.
+Passing nine on each call is awkward.
+.IP
+Using \fBlong\fP for the numeric parameter type is a workaround
+to make the parameter use the same amount of stack as a pointer.
+That approach dates back to the mid-1980s, before C was standarized.
+Since then, there is a standard
+(and pointers are not required to fit in a long).
+.bP
+Providing the right number of parameters for a variadic function
+such as \fBtiparm\fP can be a problem, in particular for string parameters.
+However, only a few terminfo capabilities use string parameters
+(e.g., the ones used for programmable function keys).
+.IP
+The ncurses library checks usage of these capabilities,
+and returns an error if the capability mishandles string parameters.
+But it cannot check if a calling program provides strings in the right
+places for the \fBtparm\fP calls.
+.IP
+The \fB@TPUT@\fR(1) program checks its use of these capabilities with a table,
+so that it calls \fBtparm\fP correctly.
.SS Special TERM treatment
.PP
If configured to use the terminal-driver,
.bP
\fBsetupterm\fP interprets a missing/empty TERM variable as the
special value \*(``unknown\*(''.
+.IP
+SVr4 curses uses the
+special value \*(``dumb\*(''.
+.IP
+The difference between the two is that
+the former uses the \fBgn\fP (\fBgeneric_type\fR) terminfo capability,
+while the latter does not.
+A generic terminal is unsuitable for full-screen applications.
.bP
\fBsetupterm\fP allows explicit use of the
the windows console driver by checking if $TERM is set to
\fBcurses\fP(3X),
\fBcurs_initscr\fP(3X),
\fBcurs_kernel\fP(3X),
+\fBcurs_memleaks\fP(3X),
\fBcurs_termcap\fP(3X),
\fBcurs_variables\fP(3X),
\fBterm_variables\fP(3X),
projects / ncurses.git / blobdiff