ncurses 6.3 - patch 20211030

[ncurses.git] / man / curs_terminfo.3x

diff --git a/man/curs_terminfo.3x b/man/curs_terminfo.3x
index 54eb08a88eaa779318bbfa14c3e1da9b2d24d4a1..6bb5dc205078e50d96363c43708f4aff8702564f 100644 (file)
--- a/man/curs_terminfo.3x
+++ b/man/curs_terminfo.3x
@@ -1,5 +1,5 @@
 .\"***************************************************************************
 .\"***************************************************************************

-.\" Copyright 2018,2020 Thomas E. Dickey                                     *
+.\" 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  *
 .\" Copyright 1998-2016,2017 Free Software Foundation, Inc.                  *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *


@@ -27,7 +27,7 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"

-.\" $Id: curs_terminfo.3x,v 1.65 2020/09/29 20:07:42 Rueben.Thomas Exp $
+.\" $Id: curs_terminfo.3x,v 1.76 2021/09/04 19:58:03 tom Exp $

 .TH curs_terminfo 3X ""
 .ie \n(.g .ds `` \(lq
 .el       .ds `` ``
 .TH curs_terminfo 3X ""
 .ie \n(.g .ds `` \(lq
 .el       .ds `` ``


@@ -46,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,


@@ -63,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


@@ -80,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


@@ -120,6 +116,14 @@ capabilities, such as programming function keys.
 For all other
 functionality, \fBcurses\fR routines are more suitable and their use is
 recommended.
 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.
 .SS Initialization
 .PP
 Initially, \fBsetupterm\fR should be called.


@@ -227,14 +231,6 @@ Thus, the simplest call is:
 .sp
 which uses all the defaults and sends the output to \fBstdout\fR.
 .RE
 .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


@@ -284,6 +280,12 @@ the prototype expects \fBlong\fP (integer) values.
 .bP
 Aside from the \fBset_attributes\fP (\fBsgr\fP) capability,
 most terminal capabilities require no more than one or two parameters.
 .bP
 Aside from the \fBset_attributes\fP (\fBsgr\fP) capability,
 most terminal capabilities require no more than one or two parameters.

+.bP
+Padding information is ignored by \fBtparm\fP;
+it is interpreted by \fBtputs\fP.
+.bP
+The capability string is null-terminated.
+Use \*(``\\200\*('' where an ASCII NUL is needed in the output.

 .PP
 \fBtiparm\fP is a newer form of \fBtparm\fP which uses \fI<stdarg.h>\fP
 rather than a fixed-parameter list.
 .PP
 \fBtiparm\fP is a newer form of \fBtparm\fP which uses \fI<stdarg.h>\fP
 rather than a fixed-parameter list.


@@ -291,7 +293,10 @@ Its numeric parameters are integers (int) rather than longs.
 .\" ***************************************************************************
 .SS Output Functions
 .PP
 .\" ***************************************************************************
 .SS Output Functions
 .PP

-The \fBtputs\fR routine applies padding information to the string
+The \fBtputs\fR routine applies padding information
+(i.e., by interpreting marker embedded in the terminfo capability
+such as \*(``$<5>\*('' as 5 milliseconds)
+to the string

 \fIstr\fR and outputs it:
 .bP
 The \fIstr\fR parameter must be a terminfo string
 \fIstr\fR and outputs it:
 .bP
 The \fIstr\fR parameter must be a terminfo string


@@ -340,8 +345,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.
 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
 .\" ***************************************************************************
 .SS Terminal Capability Functions
 .PP


@@ -433,6 +442,32 @@ 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.
 .SH HISTORY
 .PP
 SVr2 introduced the terminfo feature.


@@ -504,13 +539,13 @@ l l
 _ _
 l l.
 \fBFunction\fR \fBReplaced by\fP
 _ _
 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       
+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,
 .TE
 .PP
 SVr3 kept the \fBmvcur\fP, \fBvidattr\fP and \fBvidputs\fP functions,


@@ -521,8 +556,14 @@ and handling functions such as \fBvidattr\fP
 .PP
 SVr3 introduced the functions for switching between terminal
 descriptions, e.g., \fBset_curterm\fP.
 .PP
 SVr3 introduced the functions for switching between terminal
 descriptions, e.g., \fBset_curterm\fP.

+Some of that was incremental improvements to the SVr2 library:
+.bP
+The \fBTERMINAL\fP type definition was introduced in SVr3.01,
+for the \fBterm\fP structure provided in SVr2.
+.bP

 The various global variables such as \fBboolnames\fP were mentioned
 The various global variables such as \fBboolnames\fP were mentioned

-in the programming manual at this point.
+in the programming manual at this point,
+though the variables were provided in SVr2.

 .PP
 SVr4 added the \fBvid_attr\fP and \fBvid_puts\fP functions.
 .PP
 .PP
 SVr4 added the \fBvid_attr\fP and \fBvid_puts\fP functions.
 .PP