-.\" $Id: curs_terminfo.3x,v 1.6 1996/06/15 22:45:50 tom Exp $
+.\"***************************************************************************
+.\" Copyright (c) 1999 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 *
+.\" "Software"), to deal in the Software without restriction, including *
+.\" without limitation the rights to use, copy, modify, merge, publish, *
+.\" distribute, distribute with modifications, sublicense, and/or sell *
+.\" copies of the Software, and to permit persons to whom the Software is *
+.\" furnished to do so, subject to the following conditions: *
+.\" *
+.\" The above copyright notice and this permission notice shall be included *
+.\" in all copies or substantial portions of the Software. *
+.\" *
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
+.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
+.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
+.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
+.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
+.\" *
+.\" Except as contained in this notice, the name(s) of the above copyright *
+.\" holders shall not be used in advertising or otherwise to promote the *
+.\" sale, use or other dealings in this Software without prior written *
+.\" authorization. *
+.\"***************************************************************************
+.\"
+.\" $Id: curs_terminfo.3x,v 1.12 1999/10/17 01:11:59 tom Exp $
.TH curs_terminfo 3X ""
.ds n 5
.SH NAME
.br
\fBchar *tparm(const char *str, ...);\fR
.br
-\fBchar *tparam(const char *str, char *buffer, int size, ...);\fR
-.br
\fBint tputs(const char *str, int affcnt, int (*putc)(int));\fR
.br
\fBint putp(const char *str);\fR
initializing the \fBterminfo\fR structures, but does not set up the
output virtualization structures used by \fBcurses\fR. The terminal
type is the character string \fIterm\fR; if \fIterm\fR is null, the
-environment variable \fBTERM\fR is used. All output is to file
-descriptor \fBfildes\fR which is initialized for output. If
-\fIerrret\fR is not null, then \fBsetupterm\fR returns \fBOK\fR or
+environment variable \fBTERM\fR is used.
+All output is to file descriptor \fBfildes\fR which is initialized for output.
+If \fIerrret\fR is not null,
+then \fBsetupterm\fR returns \fBOK\fR or
\fBERR\fR and stores a status value in the integer pointed to by
-\fIerrret\fR. A status of \fB1\fR in \fIerrret\fR is normal, \fB0\fR
-means that the terminal could not be found, and \fB-1\fR means that
-the \fBterminfo\fR database could not be found. If \fIerrret\fR is
+\fIerrret\fR.
+A return value of \fBOK\fR combined with status of \fB1\fR in \fIerrret\fR
+is normal.
+If \fBERR\fR is returned, examine \fIerrret\fR:
+.RS
+.TP 5
+.B 1
+means that the terminal is hardcopy, cannot be used for curses applications.
+.TP 5
+.B 0
+means that the terminal could not be found,
+or that it is a generic type,
+having too little information for curses applications to run.
+.TP 5
+.B -1
+means that the \fBterminfo\fR database could not be found.
+.RE
+.PP
+If \fIerrret\fR is
null, \fBsetupterm\fR prints an error message upon finding an error
and exits. Thus, the simplest call is:
parameters \fIpi\fR. A pointer is returned to the result of \fIstr\fR
with the parameters applied.
-The \fBtparam\fR routine is included for compatibility with the GNU termcap
-implementation. It works like \fBtparm\fR but you specify a buffer and buffer
-size to be filled with the expanded string.
-
The \fBtputs\fR routine applies padding information to the string
\fIstr\fR and outputs it. The \fIstr\fR must be a terminfo string
variable or the return value from \fBtparm\fR, \fBtgetstr\fR, or
\fIcapname\fR passed to them, such as \fBxenl\fR.
The \fBtigetflag\fR routine returns the value \fB-1\fR if
-\fIcapname\fR is not a boolean capability.
+\fIcapname\fR is not a boolean capability,
+or \fB0\fR if it is canceled or absent from the terminal description.
The \fBtigetnum\fR routine returns the value \fB-2\fR if
-\fIcapname\fR is not a numeric capability.
+\fIcapname\fR is not a numeric capability,
+or \fB-1\fR if it is canceled or absent from the terminal description.
The \fBtigetstr\fR routine returns the value \fB(char *)-1\fR
-if \fIcapname\fR is not a string capability.
+if \fIcapname\fR is not a string capability,
+or \fB0\fR if it is canceled or absent from the terminal description.
The \fIcapname\fR for each capability is given in the table column entitled
\fIcapname\fR code in the capabilities section of \fBterminfo\fR(\*n).
The XSI Curses standard prototypes \fBtparm\fR with a fixed number of parameters,
rather than a variable argument list.
+
+XSI notes that after calling \fBmvcur\fR, the curses state may not match the
+actual terminal state, and that an application should touch and refresh
+the window before resuming normal curses calls.
+Both ncurses and System V Release 4 curses implement \fBmvcur\fR using
+the SCREEN data allocated in either \fBinitscr\fR or \fBnewterm\fR.
+So though it is documented as a terminfo function,
+\fBmvcur\fR is really a curses function which is not well specified.
.SH SEE ALSO
\fBcurses\fR(3X), \fBcurs_initscr\fR(3X), \fBcurs_kernel\fR(3X), \fBcurs_termcap\fR(3X),
\fBputc\fR(3S), \fBterminfo\fR(\*n)
projects / ncurses.git / blobdiff