ncurses 6.4 - patch 20230429

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

diff --git a/man/curs_termcap.3x b/man/curs_termcap.3x
index 83d7f1c80e87330a5fc96dba861752792a6016e0..080b31850395c981d018829ec46a647fa77ad8d8 100644 (file)
--- a/man/curs_termcap.3x
+++ b/man/curs_termcap.3x
@@ -1,5 +1,5 @@
 .\"***************************************************************************
-.\" Copyright 2018-2021,2022 Thomas E. Dickey                                *
+.\" Copyright 2018-2022,2023 Thomas E. Dickey                                *
 .\" Copyright 1998-2017,2018 Free Software Foundation, Inc.                  *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
@@ -27,7 +27,7 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_termcap.3x,v 1.55 2022/01/01 23:49:07 tom Exp $
+.\" $Id: curs_termcap.3x,v 1.58 2023/04/16 18:16:40 tom Exp $
 .TH curs_termcap 3X ""
 .ie \n(.g .ds `` \(lq
 .el       .ds `` ``
@@ -66,17 +66,17 @@
 .br
 \fBextern @NCURSES_OSPEED@ ospeed;\fP
 .sp
-\fBint tgetent(char *\fP\fIbp\fP\fB, const char *\fP\fIname\fP\fB);\fP
+\fBint tgetent(char *\fIbp\fB, const char *\fIname\fB);\fR
 .br
-\fBint tgetflag(const char *\fP\fIid\fP\fB);\fP
+\fBint tgetflag(const char *\fIid\fB);\fR
 .br
-\fBint tgetnum(const char *\fP\fIid\fP\fB);\fP
+\fBint tgetnum(const char *\fIid\fB);\fR
 .br
-\fBchar *tgetstr(const char *\fP\fIid\fP\fB, char **\fP\fIarea\fP\fB);\fP
+\fBchar *tgetstr(const char *\fIid\fB, char **\fIarea\fB);\fR
 .br
-\fBchar *tgoto(const char *\fP\fIcap\fP\fB, int \fP\fIcol\fP\fB, int \fP\fIrow\fP\fB);\fP
+\fBchar *tgoto(const char *\fIcap\fB, int \fIcol\fB, int \fIrow\fB);\fR
 .br
-\fBint tputs(const char *\fP\fIstr\fP\fB, int \fP\fIaffcnt\fP\fB, int (*\fP\fIputc\fP\fB)(int));\fP
+\fBint tputs(const char *\fIstr\fB, int \fIaffcnt\fB, int (*\fIputc\fB)(int));\fR
 .br
 .SH DESCRIPTION
 These routines are included as a conversion aid for programs that use
@@ -173,7 +173,13 @@ It does this also for calls requiring only a single parameter.
 In that case, the first parameter is merely a placeholder.
 .bP
 Normally the ncurses library is compiled with terminfo support.
-In that case, \fBtgoto\fP uses \fBtparm\fP(3X) (a more capable formatter).
+In that case, \fBtgoto\fP uses an internal version of
+\fBtparm\fP(3X) (a more capable formatter).
+.IP
+With terminfo support, \fBtgoto\fP is able to use some of the terminfo
+features, but not all.
+In particular, it allows only numeric parameters;
+\fBtparm\fP supports string parameters.
 .IP
 However, \fBtparm\fP is not a \fItermcap\fP feature,
 and portable \fItermcap\fP applications should not rely upon its availability.
@@ -229,6 +235,20 @@ routines that return an integer return \fBERR\fP upon failure and \fBOK\fP
 completion.
 .PP
 Routines that return pointers return \fBNULL\fP on error.
+.PP
+A few special cases apply:
+.bP
+If the terminal database has not been initialized,
+these return an error.
+.bP
+The calls with a string parameter (\fBtgoto\fP, \fBtputs\fP)
+check if the string is null, or cancelled.
+Those return an error.
+.bP
+A call to \fBtgoto\fP using a capability with string parameters is an error.
+.bP
+A call to \fBtgoto\fP using a capability with more than two parameters
+is an error.
 .SH BUGS
 If you call \fBtgetstr\fP to fetch \fBca\fP or any other parameterized string,
 be aware that it will be returned in terminfo notation, not the older and