ncurses 5.9 - patch 20120114
[ncurses.git] / doc / html / man / curs_termcap.3x.html
index f62fc0ca997feb1b010cd70ce4b7388651de4b2c..a51993397750069c732fc61d7267e88eb91a4a42 100644 (file)
@@ -1,7 +1,7 @@
 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
 <!-- 
   ****************************************************************************
-  * Copyright (c) 1998-2007,2010 Free Software Foundation, Inc.              *
+  * Copyright (c) 1998-2010,2011 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.27 2011/10/15 21:11:24 tom Exp @
 -->
 <HTML>
 <HEAD>
        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>.
+       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:
+
+          -  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.
+
+          -  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.
 
        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
+       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.
 
        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.
 
 </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.
 
 </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
-       "$&lt;..&gt;"  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
+       "$&lt;..&gt;" 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>.