X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;ds=sidebyside;f=man%2Fcurs_terminfo.3x;h=6bb5dc205078e50d96363c43708f4aff8702564f;hb=63d26709472433a4660c88461162252bf0e5fde8;hp=041c58f0852e6e4e11f456946bc262c4317aef72;hpb=47d2fb4537d9ad5bb14f4810561a327930ca4280;p=ncurses.git diff --git a/man/curs_terminfo.3x b/man/curs_terminfo.3x index 041c58f0..6bb5dc20 100644 --- 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 * @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_terminfo.3x,v 1.64 2020/02/02 23:34:34 tom 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 `` `` @@ -46,7 +46,6 @@ \fBputp\fR, \fBrestartterm\fR, \fBset_curterm\fR, -\fBsetterm\fR, \fBsetupterm\fR, \fBtigetflag\fR, \fBtigetnum\fR, @@ -63,7 +62,6 @@ .SH SYNOPSIS .nf \fB#include \fR -.br \fB#include \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 -\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 @@ -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. +.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. @@ -227,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 @@ -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 +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\fP rather than a fixed-parameter list. @@ -291,7 +293,10 @@ Its numeric parameters are integers (int) rather than longs. .\" *************************************************************************** .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 @@ -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. -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\fP because SystemV did this +(see \fBHISTORY\fP). .\" *************************************************************************** .SS Terminal Capability Functions .PP @@ -385,7 +394,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 @@ -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 +.\" *************************************************************************** +.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\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. @@ -504,13 +539,13 @@ 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 +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, @@ -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. +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 -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