.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2007 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2016,2017 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_termcap.3x,v 1.22 2007/06/02 20:40:07 tom Exp $
+.\" $Id: curs_termcap.3x,v 1.33 2017/01/07 19:25:15 tom Exp $
.TH curs_termcap 3X ""
+.de bP
+.IP \(bu 4
+..
+.na
+.hy 0
.ds n 5
.SH NAME
+\fBPC\fR,
+\fBUP\fR,
+\fBBC\fR,
+\fBospeed\fR,
\fBtgetent\fR,
\fBtgetflag\fR,
\fBtgetnum\fR,
\fBtgetstr\fR,
\fBtgoto\fR,
-\fBtputs\fR - direct \fBcurses\fR interface to the terminfo capability database
+\fBtputs\fR \- direct \fBcurses\fR interface to the terminfo capability database
+.ad
+.hy
.SH SYNOPSIS
\fB#include <curses.h>\fR
.br
routines are emulated using the \fIterminfo\fR database. Thus, they
can only be used to query the capabilities of entries for which a
terminfo entry has been compiled.
+.SS INITIALIZATION
.PP
The \fBtgetent\fR routine loads the entry for \fIname\fR.
-It returns 1 on success, 0 if there is no such entry, and -1 if the
-terminfo database could not be found.
+It returns:
+.RS 3
+.TP 3
+1
+on success,
+.TP 3
+0
+if there is no such entry
+(or that it is a generic type, having too little information for curses
+applications to run), and
+.TP 3
+\-1
+if the terminfo database could not be found.
+.RE
+.PP
+This differs from the \fItermcap\fP library in two ways:
+.RS 3
+.bP
The emulation ignores the buffer pointer \fIbp\fR.
+The \fItermcap\fP library would store a copy of the terminal
+description in the area referenced by this pointer.
+However, ncurses stores its terminal descriptions in compiled
+binary form, which is not the same thing.
+.bP
+There is a difference in return codes.
+The \fItermcap\fP library does not check if the terminal
+description is marked with the \fIgeneric\fP capability,
+or if the terminal description has cursor-addressing.
+.RE
+.SS CAPABILITY VALUES
.PP
The \fBtgetflag\fR routine gets the boolean entry for \fIid\fR,
or zero if it is not available.
.PP
The \fBtgetnum\fR routine gets the numeric entry for \fIid\fR,
-or -1 if it is not available.
+or \-1 if it is not available.
.PP
The \fBtgetstr\fR routine returns the string entry for \fIid\fR,
or zero if it is not available.
Use \fBtputs\fR to output the returned string.
-The return value will also be copied to the buffer pointed to by \fIarea\fR,
+The \fIarea\fP parameter is used as follows:
+.RS 3
+.bP
+It is assumed to be the address of a pointer to a buffer managed by the
+calling application.
+.bP
+However, ncurses checks to ensure that \fBarea\fP is not NULL,
+and also that the resulting buffer pointer is not NULL.
+If either check fails, the \fIarea\fP parameter is ignored.
+.bP
+If the checks succeed, ncurses also copies the return value to
+the buffer pointed to by \fIarea\fR,
and the \fIarea\fR value will be updated to point past the null ending
this value.
+.bP
+The return value itself is an address in the terminal description which
+is loaded into memory.
+.RE
.PP
Only the first two characters of the \fBid\fR parameter of
\fBtgetflag\fR,
\fBtgetnum\fR and
\fBtgetstr\fR are compared in lookups.
+.SS FORMATTING CAPABILITIES
.PP
-The \fBtgoto\fR routine instantiates the parameters into the given capability.
-The output from this routine is to be passed to \fBtputs\fR.
+The \fBtgoto\fR routine expands the given capability using the parameters.
+.bP
+Because the capability may have padding characters,
+the output of \fBtgoto\fP should be passed to \fBtputs\fR
+rather than some other output function such as \fBprintf\fP.
+.bP
+While \fBtgoto\fP is assumed to be used for the two-parameter
+cursor positioning capability,
+termcap applications also use it for single-parameter capabilities.
+.IP
+Doing this shows a quirk in \fBtgoto\fP: most hardware
+terminals use cursor addressing with \fIrow\fP first,
+but the original developers of the termcap interface chose to
+put the \fIcolumn\fP parameter first.
+The \fBtgoto\fP function swaps the order of parameters.
+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).
.PP
The \fBtputs\fR routine is described on the \fBcurs_terminfo\fR(3X) manual
page. It can retrieve capabilities by either termcap or terminfo name.
+.SS GLOBAL VARIABLES
.PP
The variables
\fBPC\fR,
e.g., not distinguishing between input and output.
In particular, some applications are reported to declare and/or
modify \fBospeed\fR.
+.PP
+The comment that only the first two characters of the \fBid\fR parameter
+are used escapes many application developers.
+The original BSD 4.2 termcap library (and historical relics thereof)
+did not require a trailing null NUL on the parameter name passed
+to \fBtgetstr\fP, \fBtgetnum\fP and \fBtgetflag\fP.
+Some applications assume that the termcap interface does not require
+the trailing NUL for the parameter name.
+Taking into account these issues:
+.bP
+As a special case,
+\fBtgetflag\fP matched against a single-character identifier
+provided that was at the end of the terminal description.
+You should not rely upon this behavior in portable programs.
+This implementation disallows matches against single-character capability names.
+.bP
+This implementation disallows matches by the termcap interface against
+extended capability names which are longer than two characters.
.SH SEE ALSO
-\fBcurses\fR(3X), \fBterminfo\fR(\*n), \fBputc\fR(3).
-.\"#
-.\"# The following sets edit modes for GNU EMACS
-.\"# Local Variables:
-.\"# mode:nroff
-.\"# fill-column:79
-.\"# End:
+\fBcurses\fR(3X),
+\fBterminfo\fR(\*n),
+\fBterm_variables\fR(3X),
+\fBputc\fR(3).
+.sp
+http://invisible-island.net/ncurses/tctest.html