X-Git-Url: http://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_termcap.3x.html;h=32699b3c48124e988b2c43782276f74236236c0f;hb=eb51b1ea1f75a0ec17c9c5937cb28df1e8eeec56;hp=c17b02300bf31d36585262dd47fda413dccc2f47;hpb=71c0306f0824ef2b10c4c5813fb003db48f3012e;p=ncurses.git diff --git a/doc/html/man/curs_termcap.3x.html b/doc/html/man/curs_termcap.3x.html index c17b0230..32699b3c 100644 --- a/doc/html/man/curs_termcap.3x.html +++ b/doc/html/man/curs_termcap.3x.html @@ -1,7 +1,7 @@ - - + + + curs_termcap 3x - - + + -

curs_termcap 3x

-
+

curs_termcap 3x

-
-curs_termcap(3x)                                       curs_termcap(3x)
+curs_termcap(3x)                                              curs_termcap(3x)
 
 
 
 
-
-

NAME

-       tgetent, tgetflag, tgetnum, tgetstr, tgoto, tputs - direct
-       curses interface to the terminfo capability database
+

NAME

+       PC, UP, BC, ospeed, tgetent, tgetflag, tgetnum, tgetstr, tgoto, tputs -
+       curses emulation of termcap
 
 
-
-

SYNOPSIS

+

SYNOPSIS

        #include <curses.h>
        #include <term.h>
 
@@ -61,130 +60,328 @@
        extern char * BC;
        extern short ospeed;
 
-       int tgetent(char *bp, const char *name);
-       int tgetflag(char *id);
-       int tgetnum(char *id);
-       char *tgetstr(char *id, char **area);
-       char *tgoto(const char *cap, int col, int row);
-       int tputs(const char *str, int affcnt, int (*putc)(int));
+       int tgetent(char *bp, const char *name);
+       int tgetflag(const char *id);
+       int tgetnum(const char *id);
+       char *tgetstr(const char *id, char **area);
+       char *tgoto(const char *cap, int col, int row);
+       int tputs(const char *str, int affcnt, int (*putc)(int));
 
 
-
-

DESCRIPTION

-       These routines are included as a conversion aid  for  pro-
-       grams  that use the termcap library.  Their parameters are
-       the same and the routines are emulated using the  terminfo
-       database.   Thus, they can only be used to query the capa-
-       bilities of entries for which a terminfo  entry  has  been
-       compiled.
-
-       The  tgetent routine loads the entry for name.  It returns
-       1 on success, 0 if there is no such entry, and -1  if  the
-       terminfo  database  could  not  be  found.   The emulation
-       ignores the buffer pointer bp.
-
-       The tgetflag routine gets the boolean  entry  for  id,  or
-       zero if it is not available.
-
-       The  tgetnum  routine gets the numeric entry for id, or -1
-       if it is not available.
-
-       The tgetstr routine returns the string entry  for  id,  or
-       zero  if  it  is  not  available.  Use tputs to output the
-       returned string.  The return value will also be copied  to
-       the  buffer pointed to by area, and the area value will be
-       updated to point past the null ending this value.
-
-       Only the first two characters of the id parameter of tget-
-       flag, tgetnum and tgetstr are compared in lookups.
-
-       The  tgoto  routine  instantiates  the parameters into the
-       given capability.  The output from this routine is  to  be
-       passed to tputs.
-
-       The  tputs  routine  is described on the curs_terminfo(3x)
-       manual page.  It can retrieve capabilities by either term-
-       cap or terminfo name.
-
-       The variables PC, UP and BC are set by tgetent to the ter-
-       minfo   entry's   data   for   pad_char,   cursor_up   and
-       backspace_if_not_bs,  respectively.   UP  is  not  used by
-       ncurses.  PC is used in the tdelay_output function.  BC is
-       used  in  the tgoto emulation.  The variable ospeed is set
-       by ncurses in a system-specific coding to reflect the ter-
-       minal speed.
+

DESCRIPTION

+       These routines are included as a conversion aid for programs  that  use
+       the  termcap  library.  Their parameters are the same, but the routines
+       are emulated using the terminfo database.  Thus, they can only be  used
+       to  query  the  capabilities  of entries for which a terminfo entry has
+       been compiled.
 
 
-
-

RETURN VALUE

-       Except  where  explicitly  noted,  routines that return an
-       integer return ERR upon failure and OK (SVr4  only  speci-
-       fies  "an  integer  value other than ERR") upon successful
-       completion.
+

Initialization

+       The tgetent routine loads the entry for name.  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 applications to run), and
+
+          -1 if the terminfo database could not be found.
+
+       This differs from the termcap library in two ways:
+
+          o   The  emulation  ignores  the buffer pointer bp.  The termcap li-
+              brary would store a copy of the terminal description in the area
+              referenced  by this pointer.  However, ncurses stores its termi-
+              nal descriptions in compiled binary form, which is not the  same
+              thing.
+
+          o   There is a difference in return codes.  The termcap library does
+              not check if the terminal description is marked with the generic
+              capability,  or  if the terminal description has cursor-address-
+              ing.
+
+
+

Capability Values

+       The tgetflag routine gets the boolean entry for id, or zero  if  it  is
+       not available.
+
+       The  tgetnum  routine gets the numeric entry for id, or -1 if it is not
+       available.
+
+       The tgetstr routine returns the string entry for id, or zero if  it  is
+       not  available.  Use tputs to output the returned string.  The area pa-
+       rameter is used as follows:
+
+          o   It is assumed to be the address of a pointer to a buffer managed
+              by the calling application.
+
+          o   However, ncurses checks to ensure that area is not NULL, and al-
+              so that the resulting buffer pointer is  not  NULL.   If  either
+              check fails, the area parameter is ignored.
+
+          o   If  the  checks succeed, ncurses also copies the return value to
+              the buffer pointed to by area, and the area value will be updat-
+              ed to point past the null ending this value.
+
+          o   The  return  value itself is an address in the terminal descrip-
+              tion which is loaded into memory.
+
+       Only the first two characters of the id parameter of tgetflag,  tgetnum
+       and tgetstr are compared in lookups.
+
+
+

Formatting Capabilities

+       The tgoto routine expands the given capability using the parameters.
+
+       o   Because  the  capability may have padding characters, the output of
+           tgoto should be passed to tputs rather than some other output func-
+           tion such as printf(3).
+
+       o   While  tgoto is assumed to be used for the two-parameter cursor po-
+           sitioning capability, termcap applications also use it for  single-
+           parameter capabilities.
+
+           Doing this shows a quirk in tgoto: most hardware terminals use cur-
+           sor addressing with row first, but the original developers  of  the
+           termcap  interface  chose  to  put the column parameter first.  The
+           tgoto function swaps the order of parameters.  It  does  this  also
+           for  calls  requiring  only  a single parameter.  In that case, the
+           first parameter is merely a placeholder.
+
+       o   Normally the ncurses library is compiled with terminfo support.  In
+           that  case, tgoto uses an internal version of tparm(3x) (a more ca-
+           pable formatter).
+
+           With terminfo support, tgoto is able to use some  of  the  terminfo
+           features,  but  not all.  In particular, it allows only numeric pa-
+           rameters; tparm supports string parameters.
+
+           However, tparm is not a termcap feature, and portable  termcap  ap-
+           plications should not rely upon its availability.
+
+       The  tputs  routine  is described on the curs_terminfo(3x) manual page.
+       It can retrieve capabilities by either termcap or terminfo name.
+
+
+

Global Variables

+       The variables PC, UP and BC are set by tgetent to the terminfo  entry's
+       data for pad_char, cursor_up and backspace_if_not_bs, respectively.  UP
+       is not used by ncurses.  PC is used in the tdelay_output function.   BC
+       is  used in the tgoto emulation.  The variable ospeed is set by ncurses
+       in a system-specific coding to reflect the terminal speed.
+
+
+

Releasing Memory

+       The termcap functions provide no  means  for  freeing  memory,  because
+       legacy  termcap  implementations used only the buffer areas provided by
+       the caller via tgetent and tgetstr.  Those buffers are unused  in  ter-
+       minfo.
+
+       On the other hand, terminfo allocates memory.  It uses setupterm to re-
+       trieve the data used by tgetent and the functions which return capabil-
+       ity values such as tgetstr.  One could use
+
+            del_curterm(cur_term);
+
+
+       to  free  this  memory,  but  there  is an additional complication with
+       ncurses.  It uses a fixed-size pool of storage locations, one per  set-
+       ting  of  the TERM variable when tgetent is called.  The screen(1) pro-
+       gram relies upon this arrangement, to improve its performance.
+
+       An application which uses only the low-level  termcap  functions  could
+       free the memory using del_curterm, because the pool is freed using oth-
+       er functions (see curs_memleaks(3x)).
+
+
+

RETURN VALUE

+       Except where explicitly noted, routines that return an  integer  return
+       ERR  upon  failure  and OK (SVr4 only specifies "an integer value other
+       than ERR") upon successful completion.
 
        Routines that return pointers return NULL on error.
 
+       A few special cases apply:
 
-
-

BUGS

-       If you call tgetstr to fetch ca 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 tgoto or tparm,  which  both  expand  terminfo-
-       style  strings  as terminfo.  (The tgoto 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,  tputs("50");
-       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  sgr
-       string.   One consequence of this is that termcap applica-
-       tions assume me (terminfo sgr0) 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.
+       o   If the terminal database has not been initialized, these return  an
+           error.
 
+       o   The  calls  with  a  string  parameter  (tgoto, tputs) check if the
+           string is null, or cancelled.  Those return an error.
 
-
-

PORTABILITY

-       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 tgetent 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 tgetent returns OK or
-       ERR.  Because the purpose of these functions is to provide
-       compatibility  with  the termcap 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
-       of those variables is poorly documented, e.g., not distin-
-       guishing  between  input  and output.  In particular, some
-       applications are reported to declare and/or modify ospeed.
+       o   A call to tgoto using a capability with string parameters is an er-
+           ror.
 
+       o   A call to tgoto using a capability with no parameters, or more than
+           two is an error.
 
-
-

SEE ALSO

-       curses(3x), terminfo(5), putc(3).
+
+

BUGS

+       If you call tgetstr to fetch ca 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 tgoto or tparm, which both expand terminfo-
+       style strings as terminfo.  (The tgoto function, if configured to  sup-
+       port  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 capa-
+       bilities differ from termcap's, users can be surprised:
+
+       o   tputs("50") in a terminfo system will put out a literal "50" rather
+           than busy-waiting for 50 milliseconds.
+
+       o   However,  if  ncurses is configured to support termcap, it may also
+           have been configured to support the BSD-style padding.
+
+           In that case, tputs inspects strings passed to it, looking for dig-
+           its at the beginning of the string.
+
+           tputs("50") in a termcap system may wait for 50 milliseconds rather
+           than put out a literal "50"
+
+       Note that termcap has nothing analogous to terminfo's sgr string.   One
+       consequence  of  this  is that termcap applications assume me (terminfo
+       sgr0) does not reset the alternate character set.  This  implementation
+       checks for, and modifies the data shown to the termcap interface to ac-
+       commodate termcap's limitation in this respect.
+
+
+

PORTABILITY

+
+

Standards

+       These functions are provided for supporting  legacy  applications,  and
+       should not be used in new programs:
+
+       o   The XSI Curses standard, Issue 4 describes these functions.  Howev-
+           er, they are marked TO BE WITHDRAWN and may be  removed  in  future
+           versions.
+
+       o   X/Open Curses, Issue 5 (December 2007) marked the termcap interface
+           (along with vwprintw and vwscanw) as withdrawn.
+
+       Neither the XSI Curses standard nor the SVr4 man pages  documented  the
+       return  values  of tgetent correctly, though all three were in fact re-
+       turned ever since SVr1.  In particular, an omission in the  XSI  Curses
+       documentation  has  been misinterpreted to mean that tgetent returns OK
+       or ERR.  Because the purpose of these functions is to provide  compati-
+       bility  with the termcap library, that is a defect in XCurses, Issue 4,
+       Version 2 rather than in ncurses.
+
+
+

Compatibility with BSD Termcap

+       External variables are provided for support of certain termcap applica-
+       tions.  However, termcap applications' use of those variables is poorly
+       documented, e.g., not distinguishing between input and output.  In par-
+       ticular,  some  applications  are reported to declare and/or modify os-
+       peed.
+
+       The comment that only the first two characters of the id 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 tgetstr, tgetnum and tgetflag.
+       Some applications assume that the termcap interface  does  not  require
+       the trailing NUL for the parameter name.  Taking into account these is-
+       sues:
+
+       o   As a special case,  tgetflag  matched  against  a  single-character
+           identifier  provided  that  was at the end of the terminal descrip-
+           tion.  You should not rely upon this behavior in portable programs.
+           This  implementation disallows matches against single-character ca-
+           pability names.
+
+       o   This implementation disallows  matches  by  the  termcap  interface
+           against extended capability names which are longer than two charac-
+           ters.
+
+       The BSD termcap function tgetent returns the text of a termcap entry in
+       the  buffer  passed  as an argument.  This library (like other terminfo
+       implementations) does not store terminal descriptions as text.  It sets
+       the buffer contents to a null-terminated string.
+
+
+

Other Compatibility

+       This  library includes a termcap.h header, for compatibility with other
+       implementations.  But the header is rarely used because the  other  im-
+       plementations are not strictly compatible.
+
+       The original BSD termcap (through 4.3BSD) had no header file which gave
+       function prototypes, because that was a feature of ANSI C.  BSD termcap
+       was  written  several  years before C was standardized.  However, there
+       were two different termcap.h header files in the BSD sources:
+
+       o   One was used internally by the jove editor in 2BSD through  4.4BSD.
+           It defined global symbols for the termcap variables which it used.
+
+       o   The  other  appeared in 4.4BSD Lite Release 2 (mid-1993) as part of
+           libedit (also known as the editline library).  The CSRG source his-
+           tory  shows  that  this  was added in mid-1992.  The libedit header
+           file was used internally, as a convenience for compiling the  edit-
+           line library.  It declared function prototypes, but no global vari-
+           ables.
+
+       The header file from libedit was added to NetBSD's termcap  library  in
+       mid-1994.
+
+       Meanwhile,  GNU  termcap  was under development, starting in 1990.  The
+       first release (termcap 1.0) in 1991 included a termcap.h  header.   The
+       second  release  (termcap 1.1) in September 1992 modified the header to
+       use const for the function prototypes in the header where one would ex-
+       pect  the parameters to be read-only.  This was a difference versus the
+       original BSD termcap.  The prototype for tputs also  differed,  but  in
+       that instance, it was libedit which differed from BSD termcap.
+
+       A copy of GNU termcap 1.3 was bundled with bash in mid-1993, to support
+       the readline(3) library.
+
+       A termcap.h file was provided in ncurses 1.8.1 (November  1993).   That
+       reflected influence by emacs(1) (rather than jove(1)) and GNU termcap:
+
+       o   it provided declarations for a few global symbols used by emacs
+
+       o   it provided function prototypes (using const).
+
+       o   a prototype for tparam (a GNU termcap feature) was provided.
+
+       Later (in mid-1996) the tparam function was removed from ncurses.  As a
+       result, there are differences between any of the four  implementations,
+       which  must  be  taken into account by programs which can work with all
+       termcap library interfaces.
+
+
+

SEE ALSO

+       curses(3x), putc(3), term_variables(3x), terminfo(5).
+
+       https://invisible-island.net/ncurses/tctest.html
 
 
 
-                                                       curs_termcap(3x)
+                                                              curs_termcap(3x)
 
-
-
-Man(1) output converted with -man2html -
+