Based on the ncurses curs_terminfo.3x file. Still needs some work.

1 files changed, 455 insertions, 0 deletions

diff --git a/lib/libtermlib/terminfo.3 b/lib/libtermlib/terminfo.3
new file mode 100644
index 00000000000..c8cd0233b32
--- /dev/null
+++ b/lib/libtermlib/terminfo.3
@@ -0,0 +1,455 @@
+.\" $OpenBSD: terminfo.3,v 1.1 1997/11/29 01:17:20 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. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"	This product includes software developed by Todd C. Miller.
+.\" 4. 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 char *
+.Fn tparam "const char *str" "char *buffer" "int size" "..."
+.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,
+.Nm setupterm
+should be called.  Note that
+.Nm setupterm
+is automatically called by
+.Nm initscr
+and
+.Nm newterm .
+This defines the set of terminal-dependent variables [listed in
+.Xr terminfo 5 ].
+The
+.Nm terminfo
+variables
+.Dv lines
+and
+.Dv columns
+are initialized by
+.Nm setupterm
+as follows: If
+.Nm 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
+.Nm tparm
+to instantiate them.  All
+.Nm terminfo
+strings [including the output of
+.Nm tparm ]
+should be printed with
+.Nm tputs
+or
+.Nm putp .
+Call the
+.Nm 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
+.Nm reset_shell_mode
+and output
+.Nm exit_ca_mode
+before the shell is called and should output
+.Nm enter_ca_mode
+and call
+.Nm reset_prog_mode
+after returning from the shell.
+.Pp
+The
+.Nm 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
+.Dv term ;
+if
+.Dv term
+is null, the environment variable
+.Ev TERM
+is used.  All output is to file descriptor
+.Dv fildes
+which is initialized for output.  If
+.Dv errret
+is not null, then
+.Nm setupterm
+returns
+.Dv OK
+or
+.Dv ERR
+and stores a status value in the integer pointed to by
+.Dv errret .
+A status of
+.Li 1
+in
+.Dv 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
+.Dv errret
+is null,
+.Nm 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
+.Nm setterm
+routine is being replaced by
+.Nm 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
+.Nm setterm
+routine is included here for BSD compatibility, and is not recommended
+for new programs.
+.Pp
+The
+.Nm set_curterm
+routine sets the variable
+.Dv cur_term
+to
+.Dv nterm ,
+and makes all of the
+.Nm terminfo
+boolean, numeric, and string variables use the values from
+.Dv nterm .
+It returns the old value of
+.Dv cur_term .
+.Pp
+The
+.Nm del_curterm
+routine frees the space pointed to by
+.Dv oterm
+and makes it available for further use.  If
+.Dv 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
+.Nm setupterm
+has been called.
+.Pp
+The
+.Nm restartterm
+routine is similar to
+.Nm setupterm
+and
+.Nm 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
+.Nm tparm
+routine instantiates the string
+.Dv str
+with
+parameters
+.Dv pi .
+A pointer is returned to the result of
+.Dv str
+with the parameters applied.
+.Pp
+The
+.Nm tparam
+routine is included for compatibility with the GNU termcap
+implementation.  It works like
+.Nm tparm
+but you specify a buffer and buffer size to be filled with the expanded string.
+.Pp
+The
+.Nm tputs
+routine applies padding information to the string
+.Dv str
+and outputs it.  The
+.Dv str
+must be a terminfo string variable or the return value from
+.Nm tparm ,
+.Nm tgetstr ,
+or
+.Nm tgoto .
+.Dv affcnt
+is the number of lines affected, or 1 if not applicable.
+.Dv putc
+is a \fBputchar\fR-like routine to which the characters are
+passed, one at a time.
+.Pp
+The
+.Nm putp
+routine calls:
+.Bd -literal -offset indent
+tputs(str, 1, putchar)
+
+.Ed
+Note that the output of
+.Nm putp
+always goes to
+.Dv stdout ,
+not to the
+.Dv fildes
+specified in
+.Nm setupterm .
+.Pp
+The
+.Nm vidputs
+routine displays the string on the terminal in the video
+attribute mode
+.Dv attrs ,
+which is any combination of the attributes listed in
+.Xr curses 3 .
+The characters are passed to the
+\fBputchar\fR-like routine
+.Dv putc .
+.Pp
+The
+.Nm vidattr
+routine is like the
+.Nm vidputs
+routine, except that it outputs through
+.Nm putchar .
+.Pp
+The
+.Nm mvcur
+routine provides low-level cursor motion.  It takes
+effect immediately (rather than at the next refresh).
+.Pp
+The
+.Nm tigetflag ,
+.Nm tigetnum
+and
+.Nm tigetstr
+routines return the value of the capability corresponding to the
+.Nm terminfo
+.Dv capname
+passed to them, such as
+.Dv xenl .
+.Pp
+The
+.Nm tigetflag
+routine returns the value
+.Li -1
+if
+.Dv capname
+is not a boolean capability.
+.Pp
+The
+.Nm tigetnum
+routine returns the value
+.Li -2
+if
+.Dv capname
+is not a numeric capability.
+.Pp
+The
+.Nm tigetstr
+routine returns the value
+.Li (char *)-1
+if
+.Dv capname
+is not a string capability.
+.Pp
+The
+.Dv capname
+for each capability is given in the table column entitled
+.Dv 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
+.Nm setupterm
+routine should be used in place of
+.Nm setterm .
+It may be useful when you want to test for terminal capabilities without
+committing to the allocation of storage involved in
+.Nm initscr .
+.Pp
+Note that
+.Nm vidattr
+and
+.Nm vidputs
+may be macros.
+.Sh PORTABILITY
+The function
+.Nm 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,
+.Nm 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
+.Nm tputs
+has the type
+\fBint (*putc)(char)\fR.
+.Pp
+The XSI Curses standard prototypes
+.Nm 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