ncurses 6.2 - patch 20210109
[ncurses.git] / man / curs_terminfo.3x
index 844098e6a917de512b3a33d89f4ae5d5531d95ff..9120a04b9a9820406ddb77b8edd25beb81665e9a 100644 (file)
@@ -1,5 +1,6 @@
 .\"***************************************************************************
 .\"***************************************************************************
-.\" Copyright (c) 1999-2017,2018 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            *
 .\"                                                                          *
 .\" 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.                                                           *
 .\"***************************************************************************
 .\"
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_terminfo.3x,v 1.58 2018/04/07 21:09:12 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 `` ``
 .TH curs_terminfo 3X ""
 .ie \n(.g .ds `` \(lq
 .el       .ds `` ``
@@ -45,7 +46,6 @@
 \fBputp\fR,
 \fBrestartterm\fR,
 \fBset_curterm\fR,
 \fBputp\fR,
 \fBrestartterm\fR,
 \fBset_curterm\fR,
-\fBsetterm\fR,
 \fBsetupterm\fR,
 \fBtigetflag\fR,
 \fBtigetnum\fR,
 \fBsetupterm\fR,
 \fBtigetflag\fR,
 \fBtigetnum\fR,
@@ -62,7 +62,6 @@
 .SH SYNOPSIS
 .nf
 \fB#include <curses.h>\fR
 .SH SYNOPSIS
 .nf
 \fB#include <curses.h>\fR
-.br
 \fB#include <term.h>\fR
 .sp
 \fBTERMINAL *cur_term;\fR
 \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
 .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
 \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
 .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.
 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.
 .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
 \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
 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
 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)].
 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
 .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
 .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
 .\" ***************************************************************************
 .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
 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.
 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.
@@ -291,7 +295,8 @@ 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
 \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.
+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.
 .bP
 \fIaffcnt\fR is the number of lines affected, or 1 if
 not applicable.
@@ -305,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
 .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 \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
 They use a set of arguments for representing the video attributes plus color,
 i.e.,
 .bP
@@ -329,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
 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
 .\" ***************************************************************************
 .SS Terminal Capability Functions
 .PP
@@ -374,7 +385,7 @@ These null-terminated arrays contain
 .bP
 the short terminfo names (\*(``codes\*(''),
 .bP
 .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
 .bP
 the long terminfo names (\*(``fnames\*('')
 .PP
@@ -389,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
 .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
 .PP
 Routines that return pointers always return \fBNULL\fR on error.
 .PP
@@ -421,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
 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
 .SH PORTABILITY
 .SS Legacy functions
 .PP