X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_terminfo.3x;h=229da5d63b6c30c5ef9c1034f970f6438a86ea11;hp=844098e6a917de512b3a33d89f4ae5d5531d95ff;hb=a6eb34d7fec8170a8715f9e53ca2f96452dd30dd;hpb=02c4e383be9337e73a0e75844dfd1047745adb28 diff --git a/man/curs_terminfo.3x b/man/curs_terminfo.3x index 844098e6..229da5d6 100644 --- a/man/curs_terminfo.3x +++ b/man/curs_terminfo.3x @@ -1,5 +1,6 @@ .\"*************************************************************************** -.\" Copyright (c) 1999-2017,2018 Free Software Foundation, Inc. * +.\" Copyright 2018,2020 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.58 2018/04/07 21:09:12 tom Exp $ +.\" $Id: curs_terminfo.3x,v 1.67 2020/11/07 23:49:07 tom Exp $ .TH curs_terminfo 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -61,8 +62,6 @@ .hy .SH SYNOPSIS .nf -\fB#include \fR -.br \fB#include \fR .sp \fBTERMINAL *cur_term;\fR @@ -115,9 +114,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 +148,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,7 +226,8 @@ 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 @@ -250,7 +263,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. @@ -291,7 +305,8 @@ 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. +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. @@ -305,14 +320,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 @@ -329,7 +345,8 @@ 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 +The \fBmvcur\fR routine provides low-level cursor motion. +It takes effect immediately (rather than at the next refresh). .\" *************************************************************************** .SS Terminal Capability Functions @@ -374,7 +391,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 @@ -389,8 +406,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 @@ -421,6 +439,104 @@ It does not detect I/O errors: X/Open states that \fBtputs\fP ignores the return value of the output function \fIputc\fP. .RE +.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