ncurses 6.2 - patch 20210109
[ncurses.git] / man / curs_terminfo.3x
index c160cebbf2b2005b56d265117e7b3f1d68316098..9120a04b9a9820406ddb77b8edd25beb81665e9a 100644 (file)
@@ -1,5 +1,6 @@
 .\"***************************************************************************
-.\" Copyright (c) 1999-2016,2017 Free Software Foundation, Inc.              *
+.\" Copyright 2018-2020,2021 Thomas E. Dickey                                *
+.\" Copyright 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            *
@@ -26,7 +27,7 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_terminfo.3x,v 1.57 2017/11/21 00:46:31 tom Exp $
+.\" $Id: curs_terminfo.3x,v 1.72 2021/01/02 23:50:04 tom Exp $
 .TH curs_terminfo 3X ""
 .ie \n(.g .ds `` \(lq
 .el       .ds `` ``
@@ -45,7 +46,6 @@
 \fBputp\fR,
 \fBrestartterm\fR,
 \fBset_curterm\fR,
-\fBsetterm\fR,
 \fBsetupterm\fR,
 \fBtigetflag\fR,
 \fBtigetnum\fR,
@@ -62,7 +62,6 @@
 .SH SYNOPSIS
 .nf
 \fB#include <curses.h>\fR
-.br
 \fB#include <term.h>\fR
 .sp
 \fBTERMINAL *cur_term;\fR
@@ -79,8 +78,6 @@
 .sp
 \fBint setupterm(const char *\fR\fIterm\fR\fB, int \fR\fIfiledes\fR\fB, int *\fR\fIerrret\fR\fB);\fR
 .br
-\fBint setterm(const char *\fR\fIterm\fR\fB);\fR
-.br
 \fBTERMINAL *set_curterm(TERMINAL *\fR\fInterm\fR\fB);\fR
 .br
 \fBint del_curterm(TERMINAL *\fR\fIoterm\fR\fB);\fR
 .SH DESCRIPTION
 These low-level routines must be called by programs that have to deal
 directly with the \fBterminfo\fR database to handle certain terminal
-capabilities, such as programming function keys.  For all other
+capabilities, such as programming function keys.
+For all other
 functionality, \fBcurses\fR routines are more suitable and their use is
 recommended.
+.PP
+None of these functions use (or are aware of) multibyte character strings
+such as UTF-8:
+.bP
+capability names use the POSIX portable character set
+.bP
+capability string values have no associated encoding;
+they are strings of 8-bit characters.
 .SS Initialization
 .PP
 Initially, \fBsetupterm\fR should be called.
@@ -140,14 +146,18 @@ If \fBuse_env(FALSE)\fR has been called, values for
 \fBlines\fR and \fBcolumns\fR specified in \fBterminfo\fR are used.
 .bP
 Otherwise, if the environment variables \fBLINES\fR and \fBCOLUMNS\fR
-exist, their values are used.  If these environment variables do not
+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
+is used.
+Otherwise, if the environment variables do not exist, the
 values for \fBlines\fR and \fBcolumns\fR specified in the
 \fBterminfo\fR database are used.
 .PP
-Parameterized strings should be passed through \fBtparm\fR to instantiate them. 
-All \fBterminfo\fR strings [including the output of \fBtparm\fR] should be printed
+Parameterized strings should be passed through \fBtparm\fR to instantiate them.
+All \fBterminfo\fR strings
+(including the output of \fBtparm\fR)
+should be printed
 with \fBtputs\fR or \fBputp\fR.
 Call \fBreset_shell_mode\fR to restore the
 tty modes before exiting [see \fBcurs_kernel\fR(3X)].
@@ -214,20 +224,13 @@ means that the \fBterminfo\fR database could not be found.
 .IP
 If \fIerrret\fR is
 null, \fBsetupterm\fR prints an error message upon finding an error
-and exits.  Thus, the simplest call is:
+and exits.
+Thus, the simplest call is:
 .sp
       \fBsetupterm((char *)0, 1, (int *)0);\fR,
 .sp
 which uses all the defaults and sends the output to \fBstdout\fR.
 .RE
-.PP
-The \fBsetterm\fR routine was replaced by \fBsetupterm\fR.  The call:
-.sp
-      \fBsetupterm(\fR\fIterm\fR\fB, 1, (int *)0)\fR
-.sp
-provides the same functionality as \fBsetterm(\fR\fIterm\fR\fB)\fR.
-The \fBsetterm\fR routine is provided for BSD compatibility, and
-is not recommended for new programs.
 .\" ***************************************************************************
 .SS The Terminal State
 .PP
@@ -250,7 +253,8 @@ string variables use the values from \fInterm\fR.
 It returns the old value of \fBcur_term\fR.
 .PP
 The \fBdel_curterm\fR routine frees the space pointed to by
-\fIoterm\fR and makes it available for further use.  If \fIoterm\fR is
+\fIoterm\fR and makes it available for further use.
+If \fIoterm\fR is
 the same as \fBcur_term\fR, references to any of the \fBterminfo\fR
 boolean, numeric, and string variables thereafter may refer to invalid
 memory locations until another \fBsetupterm\fR has been called.
@@ -286,9 +290,13 @@ Its numeric parameters are integers (int) rather than longs.
 The \fBtputs\fR routine applies padding information to the string
 \fIstr\fR and outputs it:
 .bP
-The \fIstr\fR must be a terminfo string
-variable or the return value from \fBtparm\fR, \fBtgetstr\fR, or
-\fBtgoto\fR.
+The \fIstr\fR parameter must be a terminfo string
+variable or the return value from
+\fBtparm\fR, \fBtiparm\fP, \fBtgetstr\fR, or \fBtgoto\fR.
+.IP
+The \fBtgetstr\fP and \fBtgoto\fP functions are part of the \fItermcap\fP
+interface,
+which happens to share this function name with the \fIterminfo\fP interface.
 .bP
 \fIaffcnt\fR is the number of lines affected, or 1 if
 not applicable.
@@ -302,14 +310,15 @@ the \fIfiledes\fR specified in \fBsetupterm\fR.
 .PP
 The \fBvidputs\fR routine displays the string on the terminal in the
 video attribute mode \fIattrs\fR, which is any combination of the
-attributes listed in \fBcurses\fR(3X).  The characters are passed to
+attributes listed in \fBcurses\fR(3X).
+The characters are passed to
 the \fBputchar\fR-like routine \fIputc\fR.
 .PP
 The \fBvidattr\fR routine is like the \fBvidputs\fR routine, except
 that it outputs through \fBputchar\fR.
 .PP
-The \fBvid_attr\fR and \fBvid_puts\fR routines correspond to vidattr and vidputs,
-respectively.
+The \fBvid_attr\fR and \fBvid_puts\fR routines correspond
+to vidattr and vidputs, respectively.
 They use a set of arguments for representing the video attributes plus color,
 i.e.,
 .bP
@@ -326,8 +335,13 @@ As an extension,
 this implementation allows \fIopts\fP to be used as a pointer to \fBint\fP,
 which overrides the \fIpair\fP (\fBshort\fP) argument.
 .PP
-The \fBmvcur\fR routine provides low-level cursor motion.  It takes
-effect immediately (rather than at the next refresh).
+The \fBmvcur\fR routine provides low-level cursor motion.
+It takes effect immediately (rather than at the next refresh).
+.PP
+While \fBputp\fR and \fBmvcur\fP are low-level functions which
+do not use the high-level curses state,
+they are declared in \fB<curses.h>\fP because SystemV did this
+(see \fBHISTORY\fP).
 .\" ***************************************************************************
 .SS Terminal Capability Functions
 .PP
@@ -371,7 +385,7 @@ These null-terminated arrays contain
 .bP
 the short terminfo names (\*(``codes\*(''),
 .bP
-the \fBtermcap\fR names (\*(``names\*('', and
+the \fBtermcap\fR names (\*(``names\*(''), and
 .bP
 the long terminfo names (\*(``fnames\*('')
 .PP
@@ -386,8 +400,9 @@ for each of the predefined \fBterminfo\fR variables:
 .RE
 .SH RETURN VALUE
 Routines that return an integer return \fBERR\fR upon failure and \fBOK\fR
-(SVr4 only specifies \*(``an integer value other than \fBERR\fR\*('') upon successful
-completion, unless otherwise noted in the preceding routine descriptions.
+(SVr4 only specifies \*(``an integer value other than \fBERR\fR\*('')
+upon successful completion,
+unless otherwise noted in the preceding routine descriptions.
 .PP
 Routines that return pointers always return \fBNULL\fR on error.
 .PP
@@ -418,6 +433,130 @@ It does not detect I/O errors:
 X/Open states that \fBtputs\fP ignores the return value
 of the output function \fIputc\fP.
 .RE
+.\" ***************************************************************************
+.SS Compatibility macros
+This implementation provides a few macros for compatibility with systems
+before SVr4 (see \fBHISTORY\fP).
+Those include
+\fBcrmode\fP,
+\fBfixterm\fP,
+\fBgettmode\fP,
+\fBnocrmode\fP,
+\fBresetterm\fP,
+\fBsaveterm\fP, and
+\fBsetterm\fP.
+.PP
+In SVr4, those are found in \fB<curses.h>\fP,
+but except for \fBsetterm\fR, are likewise macros.
+The one function, \fBsetterm\fR, is mentioned in the manual page.
+The manual page notes that the \fBsetterm\fR routine
+was replaced by \fBsetupterm\fR, stating that the call:
+.sp
+      \fBsetupterm(\fR\fIterm\fR\fB, 1, (int *)0)\fR
+.sp
+provides the same functionality as \fBsetterm(\fR\fIterm\fR\fB)\fR,
+and is not recommended for new programs.
+This implementation provides each of those symbols
+as macros for BSD compatibility,
+.\" ***************************************************************************
+.SH HISTORY
+.PP
+SVr2 introduced the terminfo feature.
+Its programming manual mentioned these low-level functions:
+.TS
+l l
+_ _
+l l.
+\fBFunction\fR \fBDescription\fR
+fixterm        restore tty to \*(``in curses\*('' state
+gettmode       establish current tty modes
+mvcur  low level cursor motion
+putp   T{
+utility function that uses \fBtputs\fP to send characters via \fBputchar\fP.
+T}
+resetterm      set tty modes to \*(``out of curses\*('' state
+resetty        reset tty flags to stored value
+saveterm       save current modes as \*(``in curses\*('' state
+savetty        store current tty flags
+setterm        establish terminal with given type
+setupterm      establish terminal with given type
+tparm  instantiate a string expression with parameters
+tputs  apply padding information to a string
+vidattr        like \fBvidputs\fP, but outputs through \fBputchar\fP
+vidputs        T{
+output a string to put terminal in a specified video attribute mode
+T}
+.TE
+.PP
+The programming manual also mentioned
+functions provided for termcap compatibility
+(commenting that they \*(``may go away at a later date\*(''):
+.TS
+l l
+_ _
+l l.
+\fBFunction\fR \fBDescription\fR
+tgetent        look up termcap entry for given \fIname\fP
+tgetflag       get boolean entry for given \fIid\fP
+tgetnum        get numeric entry for given \fIid\fP
+tgetstr        get string entry for given \fIid\fP
+tgoto  apply parameters to given capability
+tputs  T{
+apply padding to capability, calling a function to put characters
+T}
+.TE
+.PP
+Early terminfo programs obtained capability values from the
+\fBTERMINAL\fP structure initialized by \fBsetupterm\fR.
+.PP
+SVr3 extended terminfo by adding functions to retrieve capability values
+(like the termcap interface),
+and reusing tgoto and tputs:
+.TS
+l l
+_ _
+l l.
+\fBFunction\fR \fBDescription\fR
+tigetflag      get boolean entry for given \fIid\fP
+tigetnum       get numeric entry for given \fIid\fP
+tigetstr       get string entry for given \fIid\fP
+.TE
+.PP
+SVr3 also replaced several of the SVr2 terminfo functions
+which had no counterpart in the termcap interface,
+documenting them as obsolete:
+.TS
+l l
+_ _
+l l.
+\fBFunction\fR \fBReplaced by\fP
+crmode cbreak  
+fixterm        reset_prog_mode 
+gettmode       N/A     
+nocrmode       nocbreak        
+resetterm      reset_shell_mode        
+saveterm       def_prog_mode   
+setterm        setupterm       
+.TE
+.PP
+SVr3 kept the \fBmvcur\fP, \fBvidattr\fP and \fBvidputs\fP functions,
+along with \fBputp\fP, \fBtparm\fP and \fBtputs\fP.
+The latter were needed to support padding,
+and handling functions such as \fBvidattr\fP
+(which used more than the two parameters supported by \fBtgoto\fP).
+.PP
+SVr3 introduced the functions for switching between terminal
+descriptions, e.g., \fBset_curterm\fP.
+The various global variables such as \fBboolnames\fP were mentioned
+in the programming manual at this point.
+.PP
+SVr4 added the \fBvid_attr\fP and \fBvid_puts\fP functions.
+.PP
+There are other low-level functions declared in the curses header files
+on Unix systems,
+but none were documented.
+The functions marked \*(``obsolete\*('' remained in use
+by the Unix \fBvi\fP editor.
 .SH PORTABILITY
 .SS Legacy functions
 .PP