.\"***************************************************************************
-.\" Copyright 2018-2021,2022 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.80 2022/01/01 21:50:06 tom Exp $
+.\" $Id: curs_terminfo.3x,v 1.84 2023/04/09 08:13:16 tom Exp $
.TH curs_terminfo 3X ""
.ie \n(.g .ds `` \(lq
.el .ds `` ``
\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
.br
.fi
.SH DESCRIPTION
\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
.\" ***************************************************************************
.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.
+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
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,
.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,
projects / ncurses.git / blobdiff