diff options
Diffstat (limited to 'doc/html/man/curs_termcap.3x.html')
-rw-r--r-- | doc/html/man/curs_termcap.3x.html | 138 |
1 files changed, 90 insertions, 48 deletions
diff --git a/doc/html/man/curs_termcap.3x.html b/doc/html/man/curs_termcap.3x.html index f62fc0c..7960750 100644 --- a/doc/html/man/curs_termcap.3x.html +++ b/doc/html/man/curs_termcap.3x.html @@ -1,7 +1,7 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <!-- **************************************************************************** - * Copyright (c) 1998-2007,2010 Free Software Foundation, Inc. * + * Copyright (c) 1998-2012,2013 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 * @@ -27,7 +27,7 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_termcap.3x,v 1.26 2010/12/04 18:38:55 tom Exp @ + * @Id: curs_termcap.3x,v 1.30 2013/01/19 15:58:48 tom Exp @ --> <HTML> <HEAD> @@ -79,39 +79,62 @@ bilities of entries for which a terminfo entry has been compiled. - The <STRONG>tgetent</STRONG> routine loads the entry for <EM>name</EM>. It returns - 1 on success, 0 if there is no such entry, and -1 if the - terminfo database could not be found. The emulation ig- - nores the buffer pointer <EM>bp</EM>. + <STRONG>INITIALIZATION</STRONG> + The <STRONG>tgetent</STRONG> routine loads the entry for <EM>name</EM>. It returns: + 1 on success, + + 0 if there is no such entry (or that it is a generic + type, having too little information for curses ap- + plications to run), and + + -1 if the terminfo database could not be found. + + This differs from the <EM>termcap</EM> library in two ways: + + <STRONG>o</STRONG> The emulation ignores the buffer pointer <EM>bp</EM>. The + <EM>termcap</EM> library would store a copy of the terminal + description in the area referenced by this pointer. + However, ncurses stores its terminal descriptions + in compiled binary form, which is not the same + thing. + + <STRONG>o</STRONG> There is a difference in return codes. The <EM>termcap</EM> + library does not check if the terminal description + is marked with the <EM>generic</EM> capability, or if the + terminal description has cursor-addressing. + + <STRONG>CAPABILITY</STRONG> <STRONG>VALUES</STRONG> The <STRONG>tgetflag</STRONG> routine gets the boolean entry for <EM>id</EM>, or ze- ro if it is not available. - The <STRONG>tgetnum</STRONG> routine gets the numeric entry for <EM>id</EM>, or -1 + The <STRONG>tgetnum</STRONG> routine gets the numeric entry for <EM>id</EM>, or -1 if it is not available. - The <STRONG>tgetstr</STRONG> routine returns the string entry for <EM>id</EM>, or - zero if it is not available. Use <STRONG>tputs</STRONG> to output the re- - turned string. The return value will also be copied to - the buffer pointed to by <EM>area</EM>, and the <EM>area</EM> value will be + The <STRONG>tgetstr</STRONG> routine returns the string entry for <EM>id</EM>, or + zero if it is not available. Use <STRONG>tputs</STRONG> to output the re- + turned string. The return value will also be copied to + the buffer pointed to by <EM>area</EM>, and the <EM>area</EM> value will be updated to point past the null ending this value. Only the first two characters of the <STRONG>id</STRONG> parameter of <STRONG>tget-</STRONG> <STRONG>flag</STRONG>, <STRONG>tgetnum</STRONG> and <STRONG>tgetstr</STRONG> are compared in lookups. - The <STRONG>tgoto</STRONG> routine instantiates the parameters into the - given capability. The output from this routine is to be + <STRONG>FORMATTING</STRONG> <STRONG>CAPABILITIES</STRONG> + The <STRONG>tgoto</STRONG> routine instantiates the parameters into the + given capability. The output from this routine is to be passed to <STRONG>tputs</STRONG>. - The <STRONG>tputs</STRONG> routine is described on the <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> + The <STRONG>tputs</STRONG> routine is described on the <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> manual page. It can retrieve capabilities by either term- cap or terminfo name. + <STRONG>GLOBAL</STRONG> <STRONG>VARIABLES</STRONG> The variables <STRONG>PC</STRONG>, <STRONG>UP</STRONG> and <STRONG>BC</STRONG> are set by <STRONG>tgetent</STRONG> to the ter- minfo entry's data for <STRONG>pad_char</STRONG>, <STRONG>cursor_up</STRONG> and - <STRONG>backspace_if_not_bs</STRONG>, respectively. <STRONG>UP</STRONG> is not used by + <STRONG>backspace_if_not_bs</STRONG>, respectively. <STRONG>UP</STRONG> is not used by ncurses. <STRONG>PC</STRONG> is used in the <STRONG>tdelay_output</STRONG> function. <STRONG>BC</STRONG> is - used in the <STRONG>tgoto</STRONG> emulation. The variable <STRONG>ospeed</STRONG> is set + used in the <STRONG>tgoto</STRONG> emulation. The variable <STRONG>ospeed</STRONG> is set by ncurses in a system-specific coding to reflect the ter- minal speed. @@ -119,7 +142,7 @@ </PRE> <H2>RETURN VALUE</H2><PRE> Except where explicitly noted, routines that return an in- - teger return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> (SVr4 only specifies + teger return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> (SVr4 only specifies "an integer value other than <STRONG>ERR</STRONG>") upon successful comple- tion. @@ -129,63 +152,82 @@ </PRE> <H2>BUGS</H2><PRE> If you call <STRONG>tgetstr</STRONG> to fetch <STRONG>ca</STRONG> or any other parameterized - string, be aware that it will be returned in terminfo no- + string, be aware that it will be returned in terminfo no- tation, not the older and not-quite-compatible termcap no- - tation. This will not cause problems if all you do with - it is call <STRONG>tgoto</STRONG> or <STRONG>tparm</STRONG>, which both expand terminfo- - style strings as terminfo. (The <STRONG>tgoto</STRONG> function, if con- - figured to support termcap, will check if the string is - indeed terminfo-style by looking for "%p" parameters or - "$<..>" delays, and invoke a termcap-style parser if the + tation. This will not cause problems if all you do with + it is call <STRONG>tgoto</STRONG> or <STRONG>tparm</STRONG>, which both expand terminfo- + style strings as terminfo. (The <STRONG>tgoto</STRONG> function, if con- + figured to support termcap, will check if the string is + indeed terminfo-style by looking for "%p" parameters or + "$<..>" delays, and invoke a termcap-style parser if the string does not appear to be terminfo). - Because terminfo conventions for representing padding in - string capabilities differ from termcap's, <STRONG>tputs("50");</STRONG> - will put out a literal "50" rather than busy-waiting for + Because terminfo conventions for representing padding in + string capabilities differ from termcap's, <STRONG>tputs("50");</STRONG> + will put out a literal "50" rather than busy-waiting for 50 milliseconds. Cope with it. - Note that termcap has nothing analogous to terminfo's <STRONG>sgr</STRONG> - string. One consequence of this is that termcap applica- - tions assume me (terminfo <STRONG>sgr0</STRONG>) does not reset the alter- - nate character set. This implementation checks for, and + Note that termcap has nothing analogous to terminfo's <STRONG>sgr</STRONG> + string. One consequence of this is that termcap applica- + tions assume me (terminfo <STRONG>sgr0</STRONG>) does not reset the alter- + nate character set. This implementation checks for, and modifies the data shown to the termcap interface to accom- modate termcap's limitation in this respect. </PRE> <H2>PORTABILITY</H2><PRE> - The XSI Curses standard, Issue 4 describes these func- - tions. However, they are marked TO BE WITHDRAWN and may + The XSI Curses standard, Issue 4 describes these func- + tions. However, they are marked TO BE WITHDRAWN and may be removed in future versions. - Neither the XSI Curses standard nor the SVr4 man pages - documented the return values of <STRONG>tgetent</STRONG> correctly, though - all three were in fact returned ever since SVr1. In par- - ticular, an omission in the XSI Curses documentation has - been misinterpreted to mean that <STRONG>tgetent</STRONG> returns <STRONG>OK</STRONG> or + Neither the XSI Curses standard nor the SVr4 man pages + documented the return values of <STRONG>tgetent</STRONG> correctly, though + all three were in fact returned ever since SVr1. In par- + ticular, an omission in the XSI Curses documentation has + been misinterpreted to mean that <STRONG>tgetent</STRONG> returns <STRONG>OK</STRONG> or <STRONG>ERR</STRONG>. Because the purpose of these functions is to provide - compatibility with the <EM>termcap</EM> library, that is a defect + compatibility with the <EM>termcap</EM> library, that is a defect in XCurses, Issue 4, Version 2 rather than in ncurses. - External variables are provided for support of certain - termcap applications. However, termcap applications' use + External variables are provided for support of certain + termcap applications. However, termcap applications' use of those variables is poorly documented, e.g., not distin- - guishing between input and output. In particular, some + guishing between input and output. In particular, some applications are reported to declare and/or modify <STRONG>ospeed</STRONG>. + The comment that only the first two characters of the <STRONG>id</STRONG> + parameter are used escapes many application developers. + The original BSD 4.2 termcap library (and historical + relics thereof) did not require a trailing null NUL on the + parameter name passed to <STRONG>tgetstr</STRONG>, <STRONG>tgetnum</STRONG> and <STRONG>tgetflag</STRONG>. + Some applications assume that the termcap interface does + not require the trailing NUL for the parameter name. Tak- + ing into account these issues: + + <STRONG>o</STRONG> As a special case, <STRONG>tgetflag</STRONG> matched against a single- + character identifier provided that was at the end of + the terminal description. You should not rely upon + this behavior in portable programs. This implementa- + tion disallows matches against single-character capa- + bility names. + + <STRONG>o</STRONG> This implementation disallows matches by the termcap + interface against extended capability names which are + longer than two characters. + </PRE> <H2>SEE ALSO</H2><PRE> - <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>, <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG>, <STRONG><A HREF="putc.3.html">putc(3)</A></STRONG>. + <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>, <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG>, <STRONG>putc(3)</STRONG>. + + http://invisible-island.net/ncurses/tctest.html <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG> </PRE> <HR> -<ADDRESS> -Man(1) output converted with -<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a> -</ADDRESS> +Man(1) output converted with <a href="http://invisible-island.net/scripts/readme.html#others_scripts">man2html</a> </BODY> </HTML> |