| .\"*************************************************************************** |
| .\" Copyright (c) 1998-2013,2015 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 * |
| .\" "Software"), to deal in the Software without restriction, including * |
| .\" without limitation the rights to use, copy, modify, merge, publish, * |
| .\" distribute, distribute with modifications, sublicense, and/or sell * |
| .\" copies of the Software, and to permit persons to whom the Software is * |
| .\" furnished to do so, subject to the following conditions: * |
| .\" * |
| .\" The above copyright notice and this permission notice shall be included * |
| .\" in all copies or substantial portions of the Software. * |
| .\" * |
| .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * |
| .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * |
| .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * |
| .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * |
| .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * |
| .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * |
| .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * |
| .\" * |
| .\" Except as contained in this notice, the name(s) of the above copyright * |
| .\" holders shall not be used in advertising or otherwise to promote the * |
| .\" sale, use or other dealings in this Software without prior written * |
| .\" authorization. * |
| .\"*************************************************************************** |
| .\" |
| .\" $Id: curs_termcap.3x,v 1.31 2015/04/26 00:49:10 tom Exp $ |
| .TH curs_termcap 3X "" |
| .de bP |
| .IP \(bu 4 |
| .. |
| .na |
| .hy 0 |
| .ds n 5 |
| .SH NAME |
| \fBPC\fR, |
| \fBUP\fR, |
| \fBBC\fR, |
| \fBospeed\fR, |
| \fBtgetent\fR, |
| \fBtgetflag\fR, |
| \fBtgetnum\fR, |
| \fBtgetstr\fR, |
| \fBtgoto\fR, |
| \fBtputs\fR \- direct \fBcurses\fR interface to the terminfo capability database |
| .ad |
| .hy |
| .SH SYNOPSIS |
| \fB#include <curses.h>\fR |
| .br |
| \fB#include <term.h>\fR |
| .sp |
| \fBextern char PC;\fR |
| .br |
| \fBextern char * UP;\fR |
| .br |
| \fBextern char * BC;\fR |
| .br |
| \fBextern @NCURSES_OSPEED@ ospeed;\fR |
| .sp |
| \fBint tgetent(char *bp, const char *name);\fR |
| .br |
| \fBint tgetflag(char *id);\fR |
| .br |
| \fBint tgetnum(char *id);\fR |
| .br |
| \fBchar *tgetstr(char *id, char **area);\fR |
| .br |
| \fBchar *tgoto(const char *cap, int col, int row);\fR |
| .br |
| \fBint tputs(const char *str, int affcnt, int (*putc)(int));\fR |
| .br |
| .SH DESCRIPTION |
| These routines are included as a conversion aid for programs that use |
| the \fItermcap\fR library. Their parameters are the same and the |
| routines are emulated using the \fIterminfo\fR database. Thus, they |
| can only be used to query the capabilities of entries for which a |
| terminfo entry has been compiled. |
| .SS INITIALIZATION |
| .PP |
| The \fBtgetent\fR routine loads the entry for \fIname\fR. |
| It returns: |
| .RS 3 |
| .TP 3 |
| 1 |
| on success, |
| .TP 3 |
| 0 |
| if there is no such entry |
| (or that it is a generic type, having too little information for curses |
| applications to run), and |
| .TP 3 |
| \-1 |
| if the terminfo database could not be found. |
| .RE |
| .PP |
| This differs from the \fItermcap\fP library in two ways: |
| .RS 3 |
| .bP |
| The emulation ignores the buffer pointer \fIbp\fR. |
| The \fItermcap\fP 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. |
| .bP |
| There is a difference in return codes. |
| The \fItermcap\fP library does not check if the terminal |
| description is marked with the \fIgeneric\fP capability, |
| or if the terminal description has cursor-addressing. |
| .RE |
| .SS CAPABILITY VALUES |
| .PP |
| The \fBtgetflag\fR routine gets the boolean entry for \fIid\fR, |
| or zero if it is not available. |
| .PP |
| The \fBtgetnum\fR routine gets the numeric entry for \fIid\fR, |
| or \-1 if it is not available. |
| .PP |
| The \fBtgetstr\fR routine returns the string entry for \fIid\fR, |
| or zero if it is not available. |
| Use \fBtputs\fR to output the returned string. |
| The \fIarea\fP parameter is used as follows: |
| .RS 3 |
| .bP |
| It is assumed to be the address of a pointer to a buffer managed by the |
| calling application. |
| .bP |
| However, ncurses checks to ensure that \fBarea\fP is not NULL, |
| and also that the resulting buffer pointer is not NULL. |
| If either check fails, the \fIarea\fP parameter is ignored. |
| .bP |
| If the checks succeed, ncurses also copies the return value to |
| the buffer pointed to by \fIarea\fR, |
| and the \fIarea\fR value will be updated to point past the null ending |
| this value. |
| .bP |
| The return value itself is an address in the terminal description which |
| is loaded into memory. |
| .RE |
| .PP |
| Only the first two characters of the \fBid\fR parameter of |
| \fBtgetflag\fR, |
| \fBtgetnum\fR and |
| \fBtgetstr\fR are compared in lookups. |
| .SS FORMATTING CAPABILITIES |
| .PP |
| The \fBtgoto\fR routine instantiates the parameters into the given capability. |
| The output from this routine is to be passed to \fBtputs\fR. |
| .PP |
| The \fBtputs\fR routine is described on the \fBcurs_terminfo\fR(3X) manual |
| page. It can retrieve capabilities by either termcap or terminfo name. |
| .SS GLOBAL VARIABLES |
| .PP |
| The variables |
| \fBPC\fR, |
| \fBUP\fR and |
| \fBBC\fR |
| are set by \fBtgetent\fR to the terminfo entry's data for |
| \fBpad_char\fR, |
| \fBcursor_up\fR and |
| \fBbackspace_if_not_bs\fR, |
| respectively. |
| \fBUP\fR is not used by ncurses. |
| \fBPC\fR is used in the \fBtdelay_output\fR function. |
| \fBBC\fR is used in the \fBtgoto\fR emulation. |
| The variable \fBospeed\fR is set by ncurses in a system-specific coding |
| to reflect the terminal speed. |
| . |
| .SH RETURN VALUE |
| Except where explicitly noted, |
| 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. |
| .PP |
| Routines that return pointers return \fBNULL\fR on error. |
| .SH BUGS |
| If you call \fBtgetstr\fR to fetch \fBca\fR or any other parameterized string, |
| be aware that it will be returned in terminfo notation, not the older and |
| not-quite-compatible termcap notation. This will not cause problems if all |
| you do with it is call \fBtgoto\fR or \fBtparm\fR, which both expand |
| terminfo-style strings as terminfo. |
| (The \fBtgoto\fR function, if configured 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). |
| .PP |
| Because terminfo conventions for representing padding in string capabilities |
| differ from termcap's, \fBtputs("50");\fR will put out a literal "50" rather |
| than busy-waiting for 50 milliseconds. Cope with it. |
| .PP |
| Note that termcap has nothing analogous to terminfo's \fBsgr\fR string. |
| One consequence of this is that termcap applications assume \fRme\fR |
| (terminfo \fBsgr0\fR) does not reset the alternate character set. |
| This implementation checks for, and modifies the data shown to the |
| termcap interface to accommodate termcap's limitation in this respect. |
| .SH PORTABILITY |
| The XSI Curses standard, Issue 4 describes these functions. However, they |
| are marked TO BE WITHDRAWN and may be removed in future versions. |
| .PP |
| Neither the XSI Curses standard nor the SVr4 man pages documented the return |
| values of \fBtgetent\fR correctly, though all three were in fact returned ever |
| since SVr1. |
| In particular, an omission in the XSI Curses documentation has been |
| misinterpreted to mean that \fBtgetent\fR returns \fBOK\fR or \fBERR\fR. |
| Because the purpose of these functions is to provide compatibility with |
| the \fItermcap\fR library, that is a defect in XCurses, Issue 4, Version 2 |
| rather than in ncurses. |
| .PP |
| External variables are provided for support of certain termcap applications. |
| However, termcap applications' use of those variables is poorly documented, |
| e.g., not distinguishing between input and output. |
| In particular, some applications are reported to declare and/or |
| modify \fBospeed\fR. |
| .PP |
| The comment that only the first two characters of the \fBid\fR 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 \fBtgetstr\fP, \fBtgetnum\fP and \fBtgetflag\fP. |
| Some applications assume that the termcap interface does not require |
| the trailing NUL for the parameter name. |
| Taking into account these issues: |
| .bP |
| As a special case, |
| \fBtgetflag\fP 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 implementation disallows matches against single-character capability names. |
| .bP |
| This implementation disallows matches by the termcap interface against |
| extended capability names which are longer than two characters. |
| .SH SEE ALSO |
| \fBcurses\fR(3X), |
| \fBterminfo\fR(\*n), |
| \fBterm_variables\fR(3X), |
| \fBputc\fR(3). |
| .sp |
| http://invisible-island.net/ncurses/tctest.html |