ncurses 6.4 - patch 20230408

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

diff --git a/man/curs_termcap.3x b/man/curs_termcap.3x
index e073d940cdd29003d908423090e2339a3653ea22..1630658d191db9c4ebb4f0f651c3e22112f60683 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.57 2023/04/08 21:43:01 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 no parameters,
+or more than two 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