.\" $OpenBSD: terminfo.3,v 1.4 1998/06/21 22:13:51 millert Exp $
.\"
.\" Copyright (c) 1997 Todd C. Miller <Todd.Miller@courtesan.com>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL
.\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
.\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
.\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
.\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd November 28, 1997
.Dt TERMINFO 3
.Os
.Sh NAME
.Nm setupterm ,
.Nm setterm ,
.Nm set_curterm ,
.Nm del_curterm ,
.Nm restartterm ,
.Nm tparm ,
.Nm tputs ,
.Nm putp ,
.Nm vidputs ,
.Nm vidattr ,
.Nm mvcur ,
.Nm tigetflag ,
.Nm tigetnum ,
.Nm tigetstr
.Nd interfaces to the terminfo database
.Sh SYNOPSIS
.Fd #include <term.h>
.Ft int
.Fn setupterm "const char *term" "int fildes" "int *errret"
.Ft int
.Fn setterm "const char *term"
.Ft TERMINAL *
.Fn set_curterm "TERMINAL *nterm"
.Ft int
.Fn del_curterm "TERMINAL *oterm"
.Ft int
.Fn restartterm "const char *term" "int fildes" "int *errret"
.Ft char *
.Fn tparm "const char *str" "..."
.Ft int
.Fn tputs "const char *str" "int affcnt" "int (*putc)(int))"
.Ft int
.Fn putp "const char *str"
.Ft int
.Fn vidputs "chtype attrs" "int (*putc)(char))"
.Ft int
.Fn vidattr "chtype attrs"
.Ft int
.Fn mvcur "int oldrow" "int oldcol" "int newrow" "int newcol"
.Ft int
.Fn tigetflag "const char *capname"
.Ft int
.Fn tigetnum "const char *capname"
.Ft char *
.Fn tigetstr "const char *capname"
.Sh DESCRIPTION
These low-level routines must be called by programs that have
to deal directly with the
.Nm terminfo
database to handle certain terminal capabilities, such as
programming function keys.  For all other functionality,
.Xr curses 3
routines are more suitable and their use is recommended.
.Pp
Initially,
.Fn setupterm
should be called.  Note that
.Fn setupterm
is automatically called by
.Fn initscr
and
.Fn newterm .
This defines the set of terminal-dependent variables [listed in
.Xr terminfo 5 ].
The
.Fn terminfo
variables
.Dv lines
and
.Dv columns
are initialized by
.Fn setupterm
as follows: If
.Fn use_env FALSE
has been called, values for
.Dv lines
and
.Dv columns
specified in
.Nm terminfo
are used.  Otherwise, if the environment variables
.Ev LINES
and
.Ev COLUMNS
exist, their values are used.  If these environment variables do not
exist and the program is running in a window, the current window size
is used.  Otherwise, if the environment variables do not exist, the
values for
.Dv lines
and
.Dv columns
specified in the
.Nm terminfo
database are used.
.Pp
The header file
.Nm term.h
should be included to get the definitions for these strings, numbers,
and flags.  Parameterized strings should be passed through
.Fn tparm
to instantiate them.  All
.Nm terminfo
strings [including the output of
.Fn tparm ]
should be printed with
.Fn tputs
or
.Fn putp .
Call the
.Fn reset_shell_mode
function to restore the tty modes before exiting [see
.Xr curs_kernel 3 ].
Programs which use cursor addressing should output
.Nm enter_ca_mode
upon startup and should output
.Nm exit_ca_mode
before exiting.  Programs desiring shell escapes should call
.Fn reset_shell_mode
and output
.Nm exit_ca_mode
before the shell is called and should output
.Nm enter_ca_mode
and call
.Fn reset_prog_mode
after returning from the shell.
.Pp
The
.Fn setupterm
routine reads in the
.Nm terminfo
database, initializing the
.Nm terminfo
structures, but does not set up the output virtualization structures
used by
.Xr curses 3 .
The terminal type is the character string
.Ar term ;
if
.Ar term
is null, the environment variable
.Ev TERM
is used.  All output is to file descriptor
.Ar fildes
which is initialized for output.  If
.Ar errret
is not null, then
.Fn setupterm
returns
.Dv OK
or
.Dv ERR
and stores a status value in the integer pointed to by
.Ar errret .
A status of
.Li 1
in
.Ar errret
is normal,
.Li 0
means that the terminal could not be found, and
.Li -1
means that the
.Nm terminfo
database could not be found.  If
.Ar errret
is null,
.Fn setupterm
prints an error message upon finding an error and exits.  Thus,
the simplest call is:
.Bd -literal -offset indent
setupterm((char *)0, 1, (int *)0);

.Ed
which uses all the defaults and sends the output to
.Dv stdout .
.Pp
The
.Fn setterm
routine is being replaced by
.Fn setupterm .
The call:
.Bd -literal -offset indent
setupterm(term, 1, (int *)0);

.Ed
provides the same functionality as:
.Bd -literal -offset indent
setterm(term);

.Ed
The
.Fn setterm
routine is included here for BSD compatibility, and is not recommended
for new programs.
.Pp
The
.Fn set_curterm
routine sets the variable
.Dv cur_term
to
.Ar nterm ,
and makes all of the
.Nm terminfo
boolean, numeric, and string variables use the values from
.Ar nterm .
It returns the old value of
.Dv cur_term .
.Pp
The
.Fn del_curterm
routine frees the space pointed to by
.Ar oterm
and makes it available for further use.  If
.Ar oterm
is the same as
.Dv cur_term ,
references to any of the
.Nm terminfo
boolean, numeric, and string variables thereafter may refer to
invalid memory locations until another
.Fn setupterm
has been called.
.Pp
The
.Fn restartterm
routine is similar to
.Fn setupterm
and
.Fn initscr ,
except that it is called after restoring memory to a previous state (for
example, when reloading a game saved as a core image dump).  It assumes that
the windows and the input and output options are the same as when memory was
saved, but the terminal type and baud rate may be different.  Accordingly,
it saves various tty state bits, does a setupterm, and then restores the bits.
.Pp
The
.Fn tparm
routine instantiates the string
.Ar str ,
substituting the parameters %p1 through %p9
with the values of
.Ar p1  
through  
.Ar p9 .
A pointer is returned to the result of
.Ar str
with the parameters applied.
.Pp
The
.Fn tputs
routine applies padding information to the string
.Ar str
and outputs it.  The
.Ar str
must be a terminfo string variable or the return value from
.Fn tparm ,
.Fn tgetstr ,
or
.Fn tgoto .
.Ar affcnt
is the number of lines affected, or 1 if not applicable.
.Ar putc
is a \fBputchar\fR-like routine to which the characters are
passed, one at a time.
.Pp
The
.Fn putp
routine calls:
.Bd -literal -offset indent
tputs(str, 1, putchar)

.Ed
Note that the output of
.Fn putp
always goes to
.Dv stdout ,
not to the
.Ar fildes
specified in
.Fn setupterm .
.Pp
The
.Fn vidputs
routine displays the string on the terminal in the video
attribute mode
.Ar attrs ,
which is any combination of the attributes listed in
.Xr curses 3 .
The characters are passed to the
\fBputchar\fR-like routine
.Ar putc .
.Pp
The
.Fn vidattr
routine is like the
.Fn vidputs
routine, except that it outputs through
.Fn putchar .
.Pp
The
.Fn mvcur
routine provides low-level cursor motion.  It takes
effect immediately (rather than at the next refresh).
.Pp
The
.Fn tigetflag ,
.Fn tigetnum
and
.Fn tigetstr
routines return the value of the capability corresponding to the
.Fn terminfo
.Ar capname
passed to them, such as
.Dv xenl .
.Pp
The
.Fn tigetflag
routine returns the value
.Li -1
if
.Ar capname
is not a boolean capability.
.Pp
The
.Fn tigetnum
routine returns the value
.Li -2
if
.Ar capname
is not a numeric capability.
.Pp
The
.Fn tigetstr
routine returns the value
.Li (char *)-1
if
.Ar capname
is not a string capability.
.Pp
The
.Ar capname
for each capability is given in the table column entitled
.Ar capname
code in the capabilities section of
.Xr terminfo 5 .
.Pp
.\" XXX - finish converting these
\fBchar *boolnames\fR, \fB*boolcodes\fR, \fB*boolfnames\fR
.Pp
\fBchar *numnames\fR, \fB*numcodes\fR, \fB*numfnames\fR
.Pp
\fBchar *strnames\fR, \fB*strcodes\fR, \fB*strfnames\fR
.Pp
These null-terminated arrays contain the \fIcapnames\fR, the
\fBtermcap\fR codes, and the full C names, for each of the
\fBterminfo\fR variables.
.Sh RETURN VALUE
Routines that return an integer return
.Dv ERR
upon failure and
.Dv OK
(SVr4 only specifies
.Dq "an integer value other than ERR" )
upon successful completion, unless otherwise noted in the
preceding routine descriptions.
.Pp
Routines that return pointers always return
.Dv NULL
on error.
.Sh NOTES
The
.Fn setupterm
routine should be used in place of
.Fn setterm .
It may be useful when you want to test for terminal capabilities without
committing to the allocation of storage involved in
.Fn initscr .
.Pp
Note that
.Fn vidattr
and
.Fn vidputs
may be macros.
.Sh PORTABILITY
The function
.Fn setterm
is not described in the XSI Curses standard and must be considered
non-portable.  All other functions are as described in the XSI curses standard.
.Pp
In System V Release 4,
.Fn set_curterm
has an
.Dv int
return type and returns
.Dv OK
or
.Dv ERR .
We have chosen to implement the XSI Curses semantics.
.Pp
In System V Release 4, the third argument of
.Fn tputs
has the type
\fBint (*putc)(char)\fR.
.Pp
The XSI Curses standard prototypes
.Fn tparm
with a fixed number of parameters, rather than a variable argument list.
.Sh SEE ALSO
.Xr curses 3
.Xr curs_initscr 3 ,
.Xr curs_kernel 3 ,
.Xr curs_termcap 3 ,
.Xr putc 3 ,
.Xr terminfo 5