ncurses 6.4 - patch 20230418

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

diff --git a/man/curs_termcap.3x b/man/curs_termcap.3x
index e073d940cdd29003d908423090e2339a3653ea22..080b31850395c981d018829ec46a647fa77ad8d8 100644 (file)
--- a/man/curs_termcap.3x
+++ b/man/curs_termcap.3x
@@ -1,5 +1,5 @@
 .\"***************************************************************************
-.\" Copyright 2018-2022,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.56 2022/02/12 20:05:11 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 `` ``
@@ -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