diff options
Diffstat (limited to 'ncurses-5.2/doc/html/man/curs_terminfo.3x.html')
| -rw-r--r-- | ncurses-5.2/doc/html/man/curs_terminfo.3x.html | 296 |
1 files changed, 296 insertions, 0 deletions
diff --git a/ncurses-5.2/doc/html/man/curs_terminfo.3x.html b/ncurses-5.2/doc/html/man/curs_terminfo.3x.html new file mode 100644 index 0000000..8a53cbc --- /dev/null +++ b/ncurses-5.2/doc/html/man/curs_terminfo.3x.html @@ -0,0 +1,296 @@ +<HTML> +<BODY> +<PRE> +<!-- Manpage converted by man2html 3.0.1 --> + +</PRE> +<H2>NAME</H2><PRE> + <B>setupterm</B>, <B>setterm</B>, <B>set_curterm</B>, <B>del_curterm</B>, <B>restartterm</B>, + <B>tparm</B>, <B>tputs</B>, <B>putp</B>, <B>vidputs</B>, <B>vidattr</B>, <B>mvcur</B>, <B>tigetflag</B>, + <B>tigetnum</B>, <B>tigetstr</B> - <B>curses</B> interfaces to terminfo + database + + +</PRE> +<H2>SYNOPSIS</H2><PRE> + <B>#include</B> <B><curses.h></B> + <B>#include</B> <B><term.h></B> + + <B>int</B> <B>setupterm(const</B> <B>char</B> <B>*term,</B> <B>int</B> <B>fildes,</B> <B>int</B> <B>*errret);</B> + <B>int</B> <B>setterm(const</B> <B>char</B> <B>*term);</B> + <B>TERMINAL</B> <B>*set_curterm(TERMINAL</B> <B>*nterm);</B> + <B>int</B> <B>del_curterm(TERMINAL</B> <B>*oterm);</B> + <B>int</B> <B>restartterm(const</B> <B>char</B> <B>*term,</B> <B>int</B> <B>fildes,</B> <B>int</B> + <B>*errret);</B> + <B>char</B> <B>*tparm(const</B> <B>char</B> <B>*str,</B> <B>...);</B> + <B>int</B> <B>tputs(const</B> <B>char</B> <B>*str,</B> <B>int</B> <B>affcnt,</B> <B>int</B> <B>(*putc)(int));</B> + <B>int</B> <B>putp(const</B> <B>char</B> <B>*str);</B> + <B>int</B> <B>vidputs(chtype</B> <B>attrs,</B> <B>int</B> <B>(*putc)(char));</B> + <B>int</B> <B>vidattr(chtype</B> <B>attrs);</B> + <B>int</B> <B>mvcur(int</B> <B>oldrow,</B> <B>int</B> <B>oldcol,</B> <B>int</B> <B>newrow,</B> <B>int</B> <B>newcol);</B> + <B>int</B> <B>tigetflag(const</B> <B>char</B> <B>*capname);</B> + <B>int</B> <B>tigetnum(const</B> <B>char</B> <B>*capname);</B> + <B>char</B> <B>*tigetstr(const</B> <B>char</B> <B>*capname);</B> + + +</PRE> +<H2>DESCRIPTION</H2><PRE> + These low-level routines must be called by programs that + have to deal directly with the <B>terminfo</B> database to handle + certain terminal capabilities, such as programming func- + tion keys. For all other functionality, <B>curses</B> routines + are more suitable and their use is recommended. + + Initially, <B>setupterm</B> should be called. Note that + <B>setupterm</B> is automatically called by <B>initscr</B> and <B>newterm</B>. + This defines the set of terminal-dependent variables + [listed in <B><A HREF="terminfo.5.html">terminfo(5)</A></B>]. The <B>terminfo</B> variables <B>lines</B> and + <B>columns</B> are initialized by <B>setupterm</B> as follows: If + <B>use_env(FALSE)</B> has been called, values for <B>lines</B> and + <B>columns</B> specified in <B>terminfo</B> are used. Otherwise, if the + environment variables <B>LINES</B> and <B>COLUMNS</B> exist, their val- + ues 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 <B>lines</B> and <B>columns</B> specified in + the <B>terminfo</B> database are used. + + The header files <B>curses.h</B> and <B>term.h</B> should be included + (in this order) to get the definitions for these strings, + numbers, and flags. Parameterized strings should be + passed through <B>tparm</B> to instantiate them. All <B>terminfo</B> + strings [including the output of <B>tparm</B>] should be printed + with <B>tputs</B> or <B>putp</B>. Call the <B>reset_shell_mode</B> to restore + the tty modes before exiting [see <B><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></B>]. + Programs which use cursor addressing should output + <B>enter_ca_mode</B> upon startup and should output <B>exit_ca_mode</B> + before exiting. Programs desiring shell escapes should + call + + <B>reset_shell_mode</B> and output <B>exit_ca_mode</B> before the shell + is called and should output <B>enter_ca_mode</B> and call + <B>reset_prog_mode</B> after returning from the shell. + + The <B>setupterm</B> routine reads in the <B>terminfo</B> database, ini- + tializing the <B>terminfo</B> structures, but does not set up the + output virtualization structures used by <B>curses</B>. The ter- + minal type is the character string <I>term</I>; if <I>term</I> is null, + the environment variable <B>TERM</B> is used. All output is to + file descriptor <B>fildes</B> which is initialized for output. + If <I>errret</I> is not null, then <B>setupterm</B> returns <B>OK</B> or <B>ERR</B> + and stores a status value in the integer pointed to by + <I>errret</I>. A return value of <B>OK</B> combined with status of <B>1</B> in + <I>errret</I> is normal. If <B>ERR</B> is returned, examine <I>errret</I>: + + <B>1</B> means that the terminal is hardcopy, cannot be + used for curses applications. + + <B>0</B> means that the terminal could not be found, or + that it is a generic type, having too little + information for curses applications to run. + + <B>-1</B> means that the <B>terminfo</B> database could not be + found. + + If <I>errret</I> is null, <B>setupterm</B> prints an error message upon + finding an error and exits. Thus, the simplest call is: + + <B>setupterm((char</B> <B>*)0,</B> <B>1,</B> <B>(int</B> <B>*)0);</B>, + + which uses all the defaults and sends the output to <B>std-</B> + <B>out</B>. + + The <B>setterm</B> routine is being replaced by <B>setupterm</B>. The + call: + + <B>setupterm(</B><I>term</I><B>,</B> <B>1,</B> <B>(int</B> <B>*)0)</B> + + provides the same functionality as <B>setterm(</B><I>term</I><B>)</B>. The + <B>setterm</B> routine is included here for BSD compatibility, + and is not recommended for new programs. + + The <B>set_curterm</B> routine sets the variable <B>cur_term</B> to + <I>nterm</I>, and makes all of the <B>terminfo</B> boolean, numeric, and + string variables use the values from <I>nterm</I>. It returns + the old value of <B>cur_term</B>. + + The <B>del_curterm</B> routine frees the space pointed to by + <I>oterm</I> and makes it available for further use. If <I>oterm</I> is + the same as <B>cur_term</B>, references to any of the <B>terminfo</B> + boolean, numeric, and string variables thereafter may + refer to invalid memory locations until another <B>setupterm</B> + has been called. + + The <B>restartterm</B> routine is similar to <B>setupterm</B> and + <B>initscr</B>, except that it is called after restoring memory + to a previous state (for example, when reloading a game + saved as a core image dump). It assumes that the windows + and the input and output options are the same as when mem- + ory was saved, but the terminal type and baud rate may be + different. Accordingly, it saves various tty state bits, + does a setupterm, and then restores the bits. + + The <B>tparm</B> routine instantiates the string <I>str</I> with parame- + ters <I>pi</I>. A pointer is returned to the result of <I>str</I> with + the parameters applied. + + The <B>tputs</B> routine applies padding information to the + string <I>str</I> and outputs it. The <I>str</I> must be a terminfo + string variable or the return value from <B>tparm</B>, <B>tgetstr</B>, + or <B>tgoto</B>. <I>affcnt</I> is the number of lines affected, or 1 if + not applicable. <I>putc</I> is a <B>putchar</B>-like routine to which + the characters are passed, one at a time. + + The <B>putp</B> routine calls <B>tputs(</B><I>str</I><B>,</B> <B>1,</B> <B>putchar)</B>. Note that + the output of <B>putp</B> always goes to <B>stdout</B>, not to the + <I>fildes</I> specified in <B>setupterm</B>. + + The <B>vidputs</B> routine displays the string on the terminal in + the video attribute mode <I>attrs</I>, which is any combination + of the attributes listed in <B><A HREF="ncurses.3x.html">curses(3x)</A></B>. The characters + are passed to the <B>putchar</B>-like routine <I>putc</I>. + + The <B>vidattr</B> routine is like the <B>vidputs</B> routine, except + that it outputs through <B>putchar</B>. + + The <B>mvcur</B> routine provides low-level cursor motion. It + takes effect immediately (rather than at the next + refresh). + + The <B>tigetflag</B>, <B>tigetnum</B> and <B>tigetstr</B> routines return the + value of the capability corresponding to the <B>terminfo</B> <I>cap-</I> + <I>name</I> passed to them, such as <B>xenl</B>. + + The <B>tigetflag</B> routine returns the value <B>-1</B> if <I>capname</I> is + not a boolean capability, or <B>0</B> if it is canceled or absent + from the terminal description. + + The <B>tigetnum</B> routine returns the value <B>-2</B> if <I>capname</I> is + not a numeric capability, or <B>-1</B> if it is canceled or + absent from the terminal description. + + The <B>tigetstr</B> routine returns the value <B>(char</B> <B>*)-1</B> if + <I>capname</I> is not a string capability, or <B>0</B> if it is canceled + or absent from the terminal description. + + The <I>capname</I> for each capability is given in the table col- + umn entitled <I>capname</I> code in the capabilities section of + <B><A HREF="terminfo.5.html">terminfo(5)</A></B>. + + <B>char</B> <B>*boolnames</B>, <B>*boolcodes</B>, <B>*boolfnames</B> + + <B>char</B> <B>*numnames</B>, <B>*numcodes</B>, <B>*numfnames</B> + + <B>char</B> <B>*strnames</B>, <B>*strcodes</B>, <B>*strfnames</B> + + These null-terminated arrays contain the <I>capnames</I>, the + <B>termcap</B> codes, and the full C names, for each of the <B>ter-</B> + <B>minfo</B> variables. + + +</PRE> +<H2>RETURN VALUE</H2><PRE> + Routines that return an integer return <B>ERR</B> upon failure + and <B>OK</B> (SVr4 only specifies "an integer value other than + <B>ERR</B>") upon successful completion, unless otherwise noted + in the preceding routine descriptions. + + Routines that return pointers always return <B>NULL</B> on error. + + +</PRE> +<H2>NOTES</H2><PRE> + The <B>setupterm</B> routine should be used in place of <B>setterm</B>. + It may be useful when you want to test for terminal capa- + bilities without committing to the allocation of storage + involved in <B>initscr</B>. + + Note that <B>vidattr</B> and <B>vidputs</B> may be macros. + + +</PRE> +<H2>PORTABILITY</H2><PRE> + The function <B>setterm</B> is not described in the XSI Curses + standard and must be considered non-portable. All other + functions are as described in the XSI curses standard. + + In System V Release 4, <B>set_curterm</B> has an <B>int</B> return type + and returns <B>OK</B> or <B>ERR</B>. We have chosen to implement the + XSI Curses semantics. + + In System V Release 4, the third argument of <B>tputs</B> has the + type <B>int</B> <B>(*putc)(char)</B>. + + The XSI Curses standard prototypes <B>tparm</B> with a fixed num- + ber of parameters, rather than a variable argument list. + + XSI notes that after calling <B>mvcur</B>, the curses state may + not match the actual terminal state, and that an applica- + tion should touch and refresh the window before resuming + normal curses calls. Both ncurses and System V Release 4 + curses implement <B>mvcur</B> using the SCREEN data allocated in + either <B>initscr</B> or <B>newterm</B>. So though it is documented as + a terminfo function, <B>mvcur</B> is really a curses function + which is not well specified. + + +</PRE> +<H2>SEE ALSO</H2><PRE> + <B><A HREF="ncurses.3x.html">curses(3x)</A></B>, <B><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></B>, <B><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></B>, <B>curs_term-</B> + <B><A HREF="cap.3x.html">cap(3x)</A></B>, <B><A HREF="putc.3S.html">putc(3S)</A></B>, <B><A HREF="terminfo.5.html">terminfo(5)</A></B> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +</PRE> +<HR> +<ADDRESS> +Man(1) output converted with +<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a> +</ADDRESS> +</BODY> +</HTML> |