X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_terminfo.3x;h=bd3bb6a46947644310428c44ed40fcf4ccd8728c;hp=c160cebbf2b2005b56d265117e7b3f1d68316098;hb=321b81e6b3fa425daddac02420d862100dc3aac8;hpb=8d3ea9021573747ecd129228ba7782a03243f62c;ds=sidebyside diff --git a/man/curs_terminfo.3x b/man/curs_terminfo.3x index c160cebb..bd3bb6a4 100644 --- a/man/curs_terminfo.3x +++ b/man/curs_terminfo.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright (c) 1999-2016,2017 Free Software Foundation, Inc. * +.\" Copyright (c) 1999-2017,2018 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 +26,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_terminfo.3x,v 1.57 2017/11/21 00:46:31 tom Exp $ +.\" $Id: curs_terminfo.3x,v 1.60 2018/07/28 22:08:59 tom Exp $ .TH curs_terminfo 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -115,7 +115,8 @@ .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. .SS Initialization @@ -140,14 +141,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 +219,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 +256,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 +293,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 +313,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,7 +338,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 @@ -386,8 +399,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