ncurses 6.2 - patch 20210109
[ncurses.git] / man / curs_terminfo.3x
index bd3bb6a46947644310428c44ed40fcf4ccd8728c..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            *
@@ -26,7 +27,7 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_terminfo.3x,v 1.60 2018/07/28 22:08:59 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
@@ -119,6 +116,14 @@ 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.
@@ -226,14 +231,6 @@ Thus, the simplest call is:
 .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
@@ -339,8 +336,12 @@ 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).
+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
@@ -384,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
@@ -432,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