X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_terminfo.3x;h=9120a04b9a9820406ddb77b8edd25beb81665e9a;hp=01772467c8070b17bb87114cd9539bbce7bbbcb2;hb=152c5a605234b7ea36ba3a03ec07e124bb6aac75;hpb=06078d3fa68db669ed37178c01873546b4b28745;ds=sidebyside diff --git a/man/curs_terminfo.3x b/man/curs_terminfo.3x index 01772467..9120a04b 100644 --- a/man/curs_terminfo.3x +++ b/man/curs_terminfo.3x @@ -1,5 +1,6 @@ .\"*************************************************************************** -.\" Copyright (c) 1999-2016,2017 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.56 2017/11/18 23:47:37 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 \fR -.br \fB#include \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 @@ -115,9 +112,18 @@ .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. +.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. @@ -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 -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 -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 -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)]. @@ -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 -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 -.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 @@ -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 -\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. @@ -286,9 +290,13 @@ Its numeric parameters are integers (int) rather than longs. The \fBtputs\fR routine applies padding information to the string \fIstr\fR and outputs it: .bP -The \fIstr\fR must be a terminfo string -variable or the return value from \fBtparm\fR, \fBtgetstr\fR, or -\fBtgoto\fR. +The \fIstr\fR parameter must be a terminfo string +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 +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. @@ -302,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 -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 \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 @@ -326,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 -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\fP because SystemV did this +(see \fBHISTORY\fP). .\" *************************************************************************** .SS Terminal Capability Functions .PP @@ -371,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 @@ -386,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 -(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 @@ -418,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\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 @@ -503,7 +642,7 @@ In System V Release 4, the third argument of \fBtputs\fR has the type \fBint (*putc)(char)\fR. .PP At least one implementation of X/Open Curses (Solaris) returns a value -other than OK/ERR from \fBtputs\fP. +other than \fBOK\fP/\fBERR\fP from \fBtputs\fP. That returns the length of the string, and does no error-checking. .PP X/Open notes that after calling \fBmvcur\fR, the curses state may not match the