ncurses 6.4 - patch 20230610

[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  *
 .\" 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.                                                           *
 .\"***************************************************************************
 .\"
 .\" 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 `` ``
 .TH curs_termcap 3X ""
 .ie \n(.g .ds `` \(lq
 .el       .ds `` ``


@@ -66,17 +66,17 @@
 .br
 \fBextern @NCURSES_OSPEED@ ospeed;\fP
 .sp
 .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
 .br

-\fBint tgetflag(const char *\fP\fIid\fP\fB);\fP
+\fBint tgetflag(const char *\fIid\fB);\fR

 .br
 .br

-\fBint tgetnum(const char *\fP\fIid\fP\fB);\fP
+\fBint tgetnum(const char *\fIid\fB);\fR

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