diff options
Diffstat (limited to 'lib/libncurses/curs_termin.3')
-rw-r--r-- | lib/libncurses/curs_termin.3 | 190 |
1 files changed, 190 insertions, 0 deletions
diff --git a/lib/libncurses/curs_termin.3 b/lib/libncurses/curs_termin.3 new file mode 100644 index 0000000..862b943 --- /dev/null +++ b/lib/libncurses/curs_termin.3 @@ -0,0 +1,190 @@ +.TH curs_terminfo 3X "" +.ds n 5 +.SH NAME +\fBcurs_terminfo\fR: \fBsetupterm\fR, \fBsetterm\fR, +\fBset_curterm\fR, \fBdel_curterm\fR, \fBrestartterm\fR, \fBtparm\fR, +\fBtputs\fR, \fBputp\fR, \fBvidputs\fR, \fBvidattr\fR, \fBmvcur\fR, +\fBtigetflag\fR, \fBtigetnum\fR, \fBtigetstr\fR - \fBncurses\fR +interfaces to terminfo database +.SH SYNOPSIS +\fB#include <ncurses.h>\fR +.br +\fB#include <term.h>\fR + +\fBint setupterm(char *term, int fildes, int *errret);\fR +.br +\fBint setterm(char *term);\fR +.br +\fBint set_curterm(TERMINAL *nterm);\fR +.br +\fBint del_curterm(TERMINAL *oterm);\fR +.br +\fBint restartterm(char *term, int fildes, int *errret);\fR +.br +\fBchar *tparm(char *str, long int p1, long int p2, long int p3, + long int p4, long int p5, long int p6, long int p7,\fR + long int p8, long int p9);\fR +\fBint tputs(char *str, int affcnt, int (*putc)(char));\fR +.br +\fBint putp(char *str);\fR +.br +\fBint vidputs(chtype attrs, int (*putc)(char));\fR +.br +\fBint vidattr(chtype attrs);\fR +.br +\fBint mvcur(int oldrow, int oldcol, int newrow, int newcol);\fR +.br +\fBint tigetflag(char *capname);\fR +.br +\fBint tigetnum(char *capname);\fR +.br +\fBint tigetstr(char *capname);\fR +.br +.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 +functionality, \fBncurses\fR routines are more suitable and their use is +recommended. + +Initially, \fBsetupterm\fR should be called. Note that +\fBsetupterm\fR is automatically called by \fBinitscr\fR and +\fBnewterm\fR. This defines the set of terminal-dependent variables +[listed in \fBterminfo\fR(\*n)]. The \fBterminfo\fR variables +\fBlines\fR and \fBcolumns\fR are initialized by \fBsetupterm\fR as +follows: If \fBuse_env(FALSE)\fR has been called, values for +\fBlines\fR and \fBcolumns\fR specified in \fBterminfo\fR are used. +Otherwise, if the environment variables \fBLINES\fR and \fBCOLUMNS\fR +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 +values for \fBlines\fR and \fBcolumns\fR specified in the +\fBterminfo\fR database are used. + +The header files \fBncurses.h\fR and \fBnterm.h\fR should be included (in this +order) to get the definitions for these strings, numbers, and flags (these +correspond to the SVr4 headers \fBcurses.h\fR and \fBterm.h\fR). 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 the \fBreset_shell_mode\fR to restore the +tty modes before exiting [see \fBcurs_kernel\fR(3X)]. Programs which use +cursor addressing should output \fBenter_ca_mode\fR upon startup and should +output \fBexit_ca_mode\fR before exiting. Programs desiring shell escapes +should call + +\fBreset_shell_mode\fR and output \fBexit_ca_mode\fR before the shell +is called and should output \fBenter_ca_mode\fR and call +\fBreset_prog_mode\fR after returning from the shell. + +The \fBsetupterm\fR routine reads in the \fBterminfo\fR database, +initializing the \fBterminfo\fR structures, but does not set up the +output virtualization structures used by \fBncurses\fR. The terminal +type is the character string \fIterm\fR; if \fIterm\fR is null, the +environment variable \fBTERM\fR is used. All output is to file +descriptor \fBfildes\fR which is initialized for output. If +\fIerrret\fR is not null, then \fBsetupterm\fR returns \fBOK\fR or +\fBERR\fR and stores a status value in the integer pointed to by +\fIerrret\fR. A status of \fB1\fR in \fIerrret\fR is normal, \fB0\fR +means that the terminal could not be found, and \fB-1\fR means that +the \fBterminfo\fR database could not be found. If \fIerrret\fR is +null, \fBsetupterm\fR prints an error message upon finding an error +and exits. Thus, the simplest call is: + + \fBsetupterm((char *)0, 1, (int *)0);\fR, + +which uses all the defaults and sends the output to \fBstdout\fR. + +The \fBsetterm\fR routine is being replaced by \fBsetupterm\fR. The call: + + \fBsetupterm(\fR\fIterm\fR\fB, 1, (int *)0)\fR + +provides the same functionality as \fBsetterm(\fR\fIterm\fR\fB)\fR. +The \fBsetterm\fR routine is included here for BSD compatibility, and +is not recommended for new programs. + +The \fBset_curterm\fR routine sets the variable \fBcur_term\fR to +\fInterm\fR, and makes all of the \fBterminfo\fR boolean, numeric, and +string variables use the values from \fInterm\fR. + +The \fBdel_curterm\fR routine frees the space pointed to by +\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. + +The \fBrestartterm\fR routine is similar to \fBsetupterm\fR and +\fBinitscr\fR, except that it is called after restoring memory to a +previous state. It assumes that the windows and the input and output +options are the same as when memory was saved, but the terminal type +and baud rate may be different. + +The \fBtparm\fR routine instantiates the string \fIstr\fR with +parameters \fIpi\fR. A pointer is returned to the result of \fIstr\fR +with the parameters applied. + +The \fBtputs\fR routine applies padding information to the string +\fIstr\fR and outputs it. The \fIstr\fR must be a terminfo string +variable or the return value from \fBtparm\fR, \fBtgetstr\fR, or +\fBtgoto\fR. \fIaffcnt\fR is the number of lines affected, or 1 if +not applicable. \fIputc\fR is a \fBputchar\fR-like routine to which +the characters are passed, one at a time. + +The \fBputp\fR routine calls \fBtputs(\fR\fIstr\fR\fB, 1, putchar)\fR. +Note that the output of \fBputp\fR always goes to \fBstdout\fR, not to +the \fIfildes\fR specified in \fBsetupterm\fR. + +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 \fBncurses\fR(3X). The characters are passed to +the \fBputchar\fR-like routine \fIputc\fR. + +The \fBvidattr\fR routine is like the \fBvidputs\fR routine, except +that it outputs through \fBputchar\fR. + +The \fBmvcur\fR routine provides low-level cursor motion. It takes +effect immediately (rather than at the next refresh). + +The \fBtigetflag\fR, \fBtigetnum\fR and \fBtigetstr\fR routines return +the value of the capability corresponding to the \fBterminfo\fR +\fIcapname\fR passed to them, such as \fBxenl\fR. + +With the \fBtigetflag\fR routine, the value \fB-1\fR is returned if +\fIcapname\fR is not a boolean capability. + +With the \fBtigetnum\fR routine, the value \fB-2\fR is returned if +\fIcapname\fR is not a numeric capability. + +With the \fBtigetstr\fR routine, the value \fB(char *)-1\fR is +returned if \fIcapname\fR is not a string capability. + +The \fIcapname\fR for each capability is given in the table column entitled +\fIcapname\fR code in the capabilities section of \fBterminfo\fR(\*n). + +\fBchar *boolnames\fR, \fB*boolcodes\fR, \fB*boolfnames\fR + +\fBchar *numnames\fR, \fB*numcodes\fR, \fB*numfnames\fR + +\fBchar *strnames\fR, \fB*strcodes\fR, \fB*strfnames\fR + +These null-terminated arrays contain the \fIcapnames\fR, the +\fBtermcap\fR codes, and the full C names, for each of the +\fBterminfo\fR variables. +.SH RETURN VALUE +All routines return the integer \fBERR\fR upon failure and an integer value +other than \fBERR\fR upon successful completion, unless otherwise noted in the +preceding routine descriptions. + +Routines that return pointers always return \fBNULL\fR on error. +.SH NOTES +The \fBsetupterm\fR routine should be used in place of \fBsetterm\fR. + +Note that \fBvidattr\fR and \fBvidputs\fR may be macros. +.SH SEE ALSO +\fBncurses\fR(3X), \fBcurs_initscr\fR(3X), \fBcurs_kernel\fR(3X), \fBcurs_termcap\fR(3X), +\fBputc\fR(3S), \fBterminfo\fR(\*n) +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: |