X-Git-Url: http://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_termcap.3x.html;h=36c4e7acdd9440ca030b81168ebfd76ba72eabe3;hb=027d0c57c4c4d6690e8d8727888d3282dbe9aa86;hp=9a168994c249d6db31795bd3ed9c6b6ab2bf9616;hpb=55ccd2b959766810cf7db8d1c4462f338ce0afc8;p=ncurses.git diff --git a/doc/html/man/curs_termcap.3x.html b/doc/html/man/curs_termcap.3x.html index 9a168994..36c4e7ac 100644 --- a/doc/html/man/curs_termcap.3x.html +++ b/doc/html/man/curs_termcap.3x.html @@ -1,7 +1,6 @@ - + + + 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 - direct curses interface to the terminfo
+       capability database
 
 
 
-

SYNOPSIS

+

SYNOPSIS

        #include <curses.h>
        #include <term.h>
-       extern char PC; extern char * UP; extern char * BC; extern
-       short ospeed;
+
+       extern char PC;
+       extern char * UP;
+       extern char * BC;
+       extern short ospeed;
+
        int tgetent(char *bp, const char *name);
        int tgetflag(char *id);
        int tgetnum(char *id);
@@ -66,7 +71,7 @@
 
 
 
-

DESCRIPTION

+

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
@@ -74,114 +79,193 @@
        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.
+
+

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 ap-
+             plications to run), and
+
+          -1 if the terminfo database could not be found.
+
+       This differs from the termcap library in two ways:
 
-       The tgetnum routine gets the numeric entry for id,  or  -1
+          o   The emulation ignores the buffer pointer  bp.   The
+              termcap  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.
+
+          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-addressing.
+
+
+
+

CAPABILITY VALUES

+       The tgetflag routine gets the boolean entry for id, or ze-
+       ro 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.
+       The tgetstr routine returns the string entry  for  id,  or
+       zero  if it is not available.  Use tputs to output the re-
+       turned string.  The area parameter 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 also that the resulting buffer pointer is
+              not  NULL.  If either check fails, the area parame-
+              ter is ignored.
+
+          o   If the checks succeed, ncurses also copies the  re-
+              turn  value  to  the buffer pointed to by area, and
+              the area value will be updated to  point  past  the
+              null ending this value.
+
+          o   The return value itself is an address in the termi-
+              nal description which is loaded into memory.
 
        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
+
+
+

FORMATTING CAPABILITIES

+       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)
+       The  tputs  routine  is described on the curs_terminfo(3x)
        manual page.  It can retrieve capabilities by either term-
        cap or terminfo name.
 
+
+
+

GLOBAL VARIABLES

        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
+       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
+       used  in  the tgoto emulation.  The variable ospeed is set
        by ncurses in a system-specific coding to reflect the ter-
        minal speed.
 
 
-
 
-

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 success-
-       ful completion.
+

RETURN VALUE

+       Except where explicitly noted, routines that return an in-
+       teger return ERR upon failure and OK (SVr4 only  specifies
+       "an integer value other than ERR") upon successful comple-
+       tion.
 
        Routines that return pointers return NULL on error.
 
 
 
-

BUGS

+

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 won't 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  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
+       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 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
+       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.
 
 
 
-

PORTABILITY

-       The XSI Curses standard, Issue  4  describes  these  func-
-       tions.   However,  they are marked TO BE WITHDRAWN and may
+

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
+       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
+       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
+       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 ospeed.
 
+       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.  Tak-
+       ing into account these issues:
+
+       o   As  a special case, tgetflag 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.
+
+       o   This implementation disallows matches by  the  termcap
+           interface  against extended capability names which are
+           longer than two characters.
+
 
 
-

SEE ALSO

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

SEE ALSO

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