ncurses 6.4 - patch 20230415

[ncurses.git] / man / curs_terminfo.3x

diff --git a/man/curs_terminfo.3x b/man/curs_terminfo.3x
index 52e94d8d9c81a7252478ec9f86cace13036bedbe..dfb27629b53de7ee5cb1b1951459bd953bb712b5 100644 (file)
--- a/man/curs_terminfo.3x
+++ b/man/curs_terminfo.3x
@@ -1,5 +1,5 @@
 .\"***************************************************************************
 .\"***************************************************************************

-.\" 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  *
 .\" Copyright 1998-2016,2017 Free Software Foundation, Inc.                  *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *


@@ -27,7 +27,7 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
 .\" 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 `` ``
 .TH curs_terminfo 3X ""
 .ie \n(.g .ds `` \(lq
 .el       .ds `` ``


@@ -76,37 +76,41 @@
 \fBconst char * const strcodes[];\fP
 \fBconst char * const strfnames[];\fP
 .sp
 \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
 .br

-\fBTERMINAL *set_curterm(TERMINAL *\fP\fInterm\fP\fB);\fP
+\fBTERMINAL *set_curterm(TERMINAL *\fInterm\fB);\fR

 .br
 .br

-\fBint del_curterm(TERMINAL *\fP\fIoterm\fP\fB);\fP
+\fBint del_curterm(TERMINAL *\fIoterm\fB);\fR

 .br
 .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
 .sp

-\fBchar *tparm(const char *\fP\fIstr\fP\fB, ...);\fP
+\fBchar *tparm(const char *\fIstr\fB, ...);\fR

 .br
 .br

-\fBint tputs(const char *\fP\fIstr\fP\fB, int \fP\fIaffcnt\fP\fB, int (*\fP\fIputc\fP\fB)(int));\fP
+       \fIor\fP

 .br
 .br

-\fBint putp(const char *\fP\fIstr\fP\fB);\fP
+\fBchar *tparm(const char *\fIstr\fB, long \fIp1 ... \fBlong \fIp9\fB);\fR

 .sp
 .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
 .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
 .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
 .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
 .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
 .sp

-\fBint tigetflag(const char *\fP\fIcapname\fP\fB);\fP
+\fBint tigetflag(const char *\fIcapname\fB);\fR

 .br
 .br

-\fBint tigetnum(const char *\fP\fIcapname\fP\fB);\fP
+\fBint tigetnum(const char *\fIcapname\fB);\fR

 .br
 .br

-\fBchar *tigetstr(const char *\fP\fIcapname\fP\fB);\fP
+\fBchar *tigetstr(const char *\fIcapname\fB);\fR

 .sp
 .sp

-\fBchar *tiparm(const char *\fP\fIstr\fP\fB, ...);\fP
+\fBchar *tiparm(const char *\fIstr\fB, ...);\fR

 .br
 .fi
 .SH DESCRIPTION
 .br
 .fi
 .SH DESCRIPTION


@@ -313,7 +317,7 @@ not applicable.
 \fIputc\fP is a \fBputchar\fP-like routine to which
 the characters are passed, one at a time.
 .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
 The output of \fBputp\fP always goes to \fBstdout\fP, rather than
 the \fIfiledes\fP specified in \fBsetupterm\fP.
 .PP


@@ -410,7 +414,8 @@ for each of the predefined \fBterminfo\fP variables:
 .\" ***************************************************************************
 .SS Releasing Memory
 Each successful call to \fBsetupterm\fP allocates memory to hold the terminal
 .\" ***************************************************************************
 .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
 If an application calls
 .sp
        \fBdel_curterm(cur_term);\fP


@@ -462,6 +467,11 @@ if it cannot allocate enough memory, or
 create the initial windows (stdscr, curscr, newscr).
 Other error conditions are documented above.
 .TP 5
 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:
 \fBtputs\fP
 returns an error if the string parameter is null.
 It does not detect I/O errors:


@@ -487,9 +497,9 @@ The one function, \fBsetterm\fP, is mentioned in the manual page.
 The manual page notes that the \fBsetterm\fP routine
 was replaced by \fBsetupterm\fP, stating that the call:
 .sp
 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
 .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,
 and is not recommended for new programs.
 This implementation provides each of those symbols
 as macros for BSD compatibility,


@@ -662,6 +672,34 @@ zeroes are fine for this purpose.
 .IP
 In response to review comments by Thomas E. Dickey,
 X/Open Curses Issue 7 proposed the \fBtiparm\fP function in mid-2009.
 .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,
 .SS Special TERM treatment
 .PP
 If configured to use the terminal-driver,