.\"***************************************************************************
-.\" 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 *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_terminfo.3x,v 1.66 2020/10/31 23:15:44 tom Exp $
+.\" $Id: curs_terminfo.3x,v 1.75 2021/06/17 21:11:08 tom Exp $
.TH curs_terminfo 3X ""
.ie \n(.g .ds `` \(lq
.el .ds `` ``
\fBputp\fR,
\fBrestartterm\fR,
\fBset_curterm\fR,
-\fBsetterm\fR,
\fBsetupterm\fR,
\fBtigetflag\fR,
\fBtigetnum\fR,
.hy
.SH SYNOPSIS
.nf
+\fB#include <curses.h>\fR
\fB#include <term.h>\fR
.sp
\fBTERMINAL *cur_term;\fR
.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
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.
.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
.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.
.\" ***************************************************************************
.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
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
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.
_ _
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,
projects / ncurses.git / blobdiff