Home Explore Help
Sign In
downstream
/
ncurses
Watch 2
Star 0
Fork 0
Files Issues 0 Pull Requests 0 Wiki
Tree: 8f86924345
Branches Tags
ncurses
/
doc
/
html
/
man
/
curs_terminfo.3x.html

curs_terminfo.3x.html 21 KB
History Raw

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354 
  1. <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
    2. 

  2. <!-- 
    3. 

  3.   ****************************************************************************
    4. 

  4.   * Copyright (c) 1999-2007,2008 Free Software Foundation, Inc.              *
    5. 

  5.   *                                                                          *
    6. 

  6.   * Permission is hereby granted, free of charge, to any person obtaining a  *
    7. 

  7.   * copy of this software and associated documentation files (the            *
    8. 

  8.   * "Software"), to deal in the Software without restriction, including      *
    9. 

  9.   * without limitation the rights to use, copy, modify, merge, publish,      *
    10. 

  10.   * distribute, distribute with modifications, sublicense, and/or sell       *
    11. 

  11.   * copies of the Software, and to permit persons to whom the Software is    *
    12. 

  12.   * furnished to do so, subject to the following conditions:                 *
    13. 

  13.   *                                                                          *
    14. 

  14.   * The above copyright notice and this permission notice shall be included  *
    15. 

  15.   * in all copies or substantial portions of the Software.                   *
    16. 

  16.   *                                                                          *
    17. 

  17.   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
    18. 

  18.   * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
    19. 

  19.   * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
    20. 

  20.   * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
    21. 

  21.   * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
    22. 

  22.   * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
    23. 

  23.   * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
    24. 

  24.   *                                                                          *
    25. 

  25.   * Except as contained in this notice, the name(s) of the above copyright   *
    26. 

  26.   * holders shall not be used in advertising or otherwise to promote the     *
    27. 

  27.   * sale, use or other dealings in this Software without prior written       *
    28. 

  28.   * authorization.                                                           *
    29. 

  29.   ****************************************************************************
    30. 

  30.   * @Id: curs_terminfo.3x,v 1.30 2008/08/16 20:53:27 tom Exp @
    31. 

  31. -->
    32. 

  32. <HTML>
    33. 

  33. <HEAD>
    34. 

  34. <TITLE>curs_terminfo 3x</TITLE>
    35. 

  35. <link rev=made href="mailto:bug-ncurses@gnu.org">
    36. 

  36. <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
    37. 

  37. </HEAD>
    38. 

  38. <BODY>
    39. 

  39. <H1>curs_terminfo 3x</H1>
    40. 

  40. <HR>
    41. 

  41. <PRE>
    42. 

  42. <!-- Manpage converted by man2html 3.0.1 -->
    43. 

  43. <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>                                     <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
    44. 

  44. 

  45. 

  46. 

  47. 

  48. </PRE>
    49. 

  49. <H2>NAME</H2><PRE>
    50. 

  50.        <STRONG>del_curterm</STRONG>, <STRONG>mvcur</STRONG>, <STRONG>putp</STRONG>, <STRONG>restartterm</STRONG>, <STRONG>set_curterm</STRONG>,
    51. 

  51.        <STRONG>setterm</STRONG>, <STRONG>setupterm</STRONG>, <STRONG>tigetflag</STRONG>, <STRONG>tigetnum</STRONG>, <STRONG>tigetstr</STRONG>, <STRONG>tparm</STRONG>,
    52. 

  52.        <STRONG>tputs</STRONG>, <STRONG>vid_attr</STRONG>, <STRONG>vid_puts</STRONG>, <STRONG>vidattr</STRONG>, <STRONG>vidputs</STRONG> - <STRONG>curses</STRONG>
    53. 

  53.        interfaces to terminfo database
    54. 

  54. 

  55. 

  56. </PRE>
    57. 

  57. <H2>SYNOPSIS</H2><PRE>
    58. 

  58.        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
    59. 

  59.        <STRONG>#include</STRONG> <STRONG>&lt;term.h&gt;</STRONG>
    60. 

  60. 

  61.        <STRONG>int</STRONG> <STRONG>setupterm(char</STRONG> <STRONG>*</STRONG><EM>term</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>fildes</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG><EM>errret</EM><STRONG>);</STRONG>
    62. 

  62.        <STRONG>int</STRONG> <STRONG>setterm(char</STRONG> <STRONG>*</STRONG><EM>term</EM><STRONG>);</STRONG>
    63. 

  63.        <STRONG>TERMINAL</STRONG> <STRONG>*set_curterm(TERMINAL</STRONG> <STRONG>*</STRONG><EM>nterm</EM><STRONG>);</STRONG>
    64. 

  64.        <STRONG>int</STRONG> <STRONG>del_curterm(TERMINAL</STRONG> <STRONG>*</STRONG><EM>oterm</EM><STRONG>);</STRONG>
    65. 

  65.        <STRONG>int</STRONG> <STRONG>restartterm(char</STRONG> <STRONG>*</STRONG><EM>term</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>fildes</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG><EM>errret</EM><STRONG>);</STRONG>
    66. 

  66.        <STRONG>char</STRONG> <STRONG>*tparm(char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>...);</STRONG>
    67. 

  67.        <STRONG>int</STRONG> <STRONG>tputs(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>affcnt</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>(*</STRONG><EM>putc</EM><STRONG>)(int));</STRONG>
    68. 

  68.        <STRONG>int</STRONG> <STRONG>putp(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>);</STRONG>
    69. 

  69.        <STRONG>int</STRONG> <STRONG>vidputs(chtype</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>(*</STRONG><EM>putc</EM><STRONG>)(int));</STRONG>
    70. 

  70.        <STRONG>int</STRONG> <STRONG>vidattr(chtype</STRONG> <EM>attrs</EM><STRONG>);</STRONG>
    71. 

  71.        <STRONG>int</STRONG> <STRONG>vid_puts(attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG><EM>opts</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>(*</STRONG><EM>putc</EM><STRONG>)(char));</STRONG>
    72. 

  72.        <STRONG>int</STRONG> <STRONG>vid_attr(attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG><EM>opts</EM><STRONG>);</STRONG>
    73. 

  73.        <STRONG>int</STRONG> <STRONG>mvcur(int</STRONG> <EM>oldrow</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>oldcol</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>newrow</EM>, int <EM>newcol</EM><STRONG>);</STRONG>
    74. 

  74.        <STRONG>int</STRONG> <STRONG>tigetflag(char</STRONG> <STRONG>*</STRONG><EM>capname</EM><STRONG>);</STRONG>
    75. 

  75.        <STRONG>int</STRONG> <STRONG>tigetnum(char</STRONG> <STRONG>*</STRONG><EM>capname</EM><STRONG>);</STRONG>
    76. 

  76.        <STRONG>char</STRONG> <STRONG>*tigetstr(char</STRONG> <STRONG>*</STRONG><EM>capname</EM><STRONG>);</STRONG>
    77. 

  77. 

  78. 

  79. </PRE>
    80. 

  80. <H2>DESCRIPTION</H2><PRE>
    81. 

  81.        These low-level routines must be called by  programs  that
    82. 

  82.        have to deal directly with the <STRONG>terminfo</STRONG> database to handle
    83. 

  83.        certain terminal capabilities, such as  programming  func-
    84. 

  84.        tion  keys.   For all other functionality, <STRONG>curses</STRONG> routines
    85. 

  85.        are more suitable and their use is recommended.
    86. 

  86. 

  87.        Initially, <STRONG>setupterm</STRONG> should  be  called.   Note  that  <STRONG>se-</STRONG>
    88. 

  88.        <STRONG>tupterm</STRONG>  is  automatically  called by <STRONG>initscr</STRONG> and <STRONG>newterm</STRONG>.
    89. 

  89.        This  defines  the  set  of  terminal-dependent  variables
    90. 

  90.        [listed in <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>].  The <STRONG>terminfo</STRONG> variables <STRONG>lines</STRONG> and
    91. 

  91.        <STRONG>columns</STRONG> are initialized by <STRONG>setupterm</STRONG> as follows:
    92. 

  92. 

  93.               If <STRONG>use_env(FALSE)</STRONG> has been called, values for <STRONG>lines</STRONG>
    94. 

  94.               and <STRONG>columns</STRONG> specified in <STRONG>terminfo</STRONG> are used.
    95. 

  95. 

  96.               Otherwise,  if  the environment variables <STRONG>LINES</STRONG> and
    97. 

  97.               <STRONG>COLUMNS</STRONG> exist, their values are used.  If these en-
    98. 

  98.               vironment variables do not exist and the program is
    99. 

  99.               running in a window, the  current  window  size  is
    100. 

  100.               used.   Otherwise,  if the environment variables do
    101. 

  101.               not exist, the values for <STRONG>lines</STRONG> and <STRONG>columns</STRONG>  speci-
    102. 

  102.               fied in the <STRONG>terminfo</STRONG> database are used.
    103. 

  103. 

  104.        The  header  files  <STRONG>curses.h</STRONG> and <STRONG>term.h</STRONG> should be included
    105. 

  105.        (in this order) to get the definitions for these  strings,
    106. 

  106.        numbers,  and  flags.   Parameterized  strings  should  be
    107. 

  107.        passed through <STRONG>tparm</STRONG> to instantiate  them.   All  <STRONG>terminfo</STRONG>
    108. 

  108.        strings  [including the output of <STRONG>tparm</STRONG>] should be printed
    109. 

  109.        with <STRONG>tputs</STRONG> or <STRONG>putp</STRONG>.  Call the <STRONG>reset_shell_mode</STRONG> to  restore
    110. 

  110.        the  tty modes before exiting [see <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>].  Pro-
    111. 

  111.        grams  which  use  cursor  addressing  should  output  <STRONG>en-</STRONG>
    112. 

  112.        <STRONG>ter_ca_mode</STRONG>  upon  startup  and should output <STRONG>exit_ca_mode</STRONG>
    113. 

  113.        before exiting.  Programs desiring  shell  escapes  should
    114. 

  114.        call
    115. 

  115. 

  116.        <STRONG>reset_shell_mode</STRONG>  and output <STRONG>exit_ca_mode</STRONG> before the shell
    117. 

  117.        is called and should output  <STRONG>enter_ca_mode</STRONG>  and  call  <STRONG>re-</STRONG>
    118. 

  118.        <STRONG>set_prog_mode</STRONG> after returning from the shell.
    119. 

  119. 

  120.        The <STRONG>setupterm</STRONG> routine reads in the <STRONG>terminfo</STRONG> database, ini-
    121. 

  121.        tializing the <STRONG>terminfo</STRONG> structures, but does not set up the
    122. 

  122.        output virtualization structures used by <STRONG>curses</STRONG>.  The ter-
    123. 

  123.        minal type is the character string <EM>term</EM>; if <EM>term</EM> is  null,
    124. 

  124.        the  environment  variable <STRONG>TERM</STRONG> is used.  All output is to
    125. 

  125.        file descriptor <STRONG>fildes</STRONG> which is  initialized  for  output.
    126. 

  126.        If  <EM>errret</EM>  is  not null, then <STRONG>setupterm</STRONG> returns <STRONG>OK</STRONG> or <STRONG>ERR</STRONG>
    127. 

  127.        and stores a status value in the integer pointed to by <EM>er-</EM>
    128. 

  128.        <EM>rret</EM>.   A  return value of <STRONG>OK</STRONG> combined with status of <STRONG>1</STRONG> in
    129. 

  129.        <EM>errret</EM> is normal.  If <STRONG>ERR</STRONG> is returned, examine <EM>errret</EM>:
    130. 

  130. 

  131.               <STRONG>1</STRONG>    means that the terminal is hardcopy, cannot be
    132. 

  132.                    used for curses applications.
    133. 

  133. 

  134.               <STRONG>0</STRONG>    means that the terminal could not be found, or
    135. 

  135.                    that it is a generic type, having  too  little
    136. 

  136.                    information for curses applications to run.
    137. 

  137. 

  138.               <STRONG>-1</STRONG>   means  that the <STRONG>terminfo</STRONG> database could not be
    139. 

  139.                    found.
    140. 

  140. 

  141.        If <EM>errret</EM> is null, <STRONG>setupterm</STRONG> prints an error message  upon
    142. 

  142.        finding an error and exits.  Thus, the simplest call is:
    143. 

  143. 

  144.              <STRONG>setupterm((char</STRONG> <STRONG>*)0,</STRONG> <STRONG>1,</STRONG> <STRONG>(int</STRONG> <STRONG>*)0);</STRONG>,
    145. 

  145. 

  146.        which  uses  all the defaults and sends the output to <STRONG>std-</STRONG>
    147. 

  147.        <STRONG>out</STRONG>.
    148. 

  148. 

  149.        The <STRONG>setterm</STRONG> routine is being replaced by  <STRONG>setupterm</STRONG>.   The
    150. 

  150.        call:
    151. 

  151. 

  152.              <STRONG>setupterm(</STRONG><EM>term</EM><STRONG>,</STRONG> <STRONG>1,</STRONG> <STRONG>(int</STRONG> <STRONG>*)0)</STRONG>
    153. 

  153. 

  154.        provides  the  same  functionality  as <STRONG>setterm(</STRONG><EM>term</EM><STRONG>)</STRONG>.  The
    155. 

  155.        <STRONG>setterm</STRONG> routine is included here  for  BSD  compatibility,
    156. 

  156.        and is not recommended for new programs.
    157. 

  157. 

  158.        The  <STRONG>set_curterm</STRONG>  routine  sets  the  variable <STRONG>cur_term</STRONG> to
    159. 

  159.        <EM>nterm</EM>, and makes all of the <STRONG>terminfo</STRONG> boolean, numeric, and
    160. 

  160.        string  variables  use  the values from <EM>nterm</EM>.  It returns
    161. 

  161.        the old value of <STRONG>cur_term</STRONG>.
    162. 

  162. 

  163.        The <STRONG>del_curterm</STRONG> routine frees  the  space  pointed  to  by
    164. 

  164.        <EM>oterm</EM> and makes it available for further use.  If <EM>oterm</EM> is
    165. 

  165.        the same as <STRONG>cur_term</STRONG>, references to any  of  the  <STRONG>terminfo</STRONG>
    166. 

  166.        boolean,  numeric, and string variables thereafter may re-
    167. 

  167.        fer to invalid memory locations  until  another  <STRONG>setupterm</STRONG>
    168. 

  168.        has been called.
    169. 

  169. 

  170.        The  <STRONG>restartterm</STRONG>  routine  is  similar  to  <STRONG>setupterm</STRONG>  and
    171. 

  171.        <STRONG>initscr</STRONG>, except that it is called after  restoring  memory
    172. 

  172.        to  a  previous  state (for example, when reloading a game
    173. 

  173.        saved as a core image dump).  It assumes that the  windows
    174. 

  174.        and the input and output options are the same as when mem-
    175. 

  175.        ory was saved, but the terminal type and baud rate may  be
    176. 

  176.        different.   Accordingly, it saves various tty state bits,
    177. 

  177.        calls <STRONG>setupterm</STRONG>, and then restores the bits.
    178. 

  178. 

  179.        The <STRONG>tparm</STRONG> routine instantiates the string <EM>str</EM> with parame-
    180. 

  180.        ters  <EM>pi</EM>.  A pointer is returned to the result of <EM>str</EM> with
    181. 

  181.        the parameters applied.
    182. 

  182. 

  183.        The <STRONG>tputs</STRONG>  routine  applies  padding  information  to  the
    184. 

  184.        string  <EM>str</EM>  and  outputs  it.  The <EM>str</EM> must be a terminfo
    185. 

  185.        string variable or the return value from  <STRONG>tparm</STRONG>,  <STRONG>tgetstr</STRONG>,
    186. 

  186.        or <STRONG>tgoto</STRONG>.  <EM>affcnt</EM> is the number of lines affected, or 1 if
    187. 

  187.        not applicable.  <EM>putc</EM> is a <STRONG>putchar</STRONG>-like routine  to  which
    188. 

  188.        the characters are passed, one at a time.
    189. 

  189. 

  190.        The  <STRONG>putp</STRONG> routine calls <STRONG>tputs(</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>1,</STRONG> <STRONG>putchar)</STRONG>.  Note that
    191. 

  191.        the output of <STRONG>putp</STRONG> always  goes  to  <STRONG>stdout</STRONG>,  not  to  the
    192. 

  192.        <EM>fildes</EM> specified in <STRONG>setupterm</STRONG>.
    193. 

  193. 

  194.        The <STRONG>vidputs</STRONG> routine displays the string on the terminal in
    195. 

  195.        the video attribute mode <EM>attrs</EM>, which is  any  combination
    196. 

  196.        of  the  attributes  listed in <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>.  The characters
    197. 

  197.        are passed to the <STRONG>putchar</STRONG>-like routine <EM>putc</EM>.
    198. 

  198. 

  199.        The <STRONG>vidattr</STRONG> routine is like the  <STRONG>vidputs</STRONG>  routine,  except
    200. 

  200.        that it outputs through <STRONG>putchar</STRONG>.
    201. 

  201. 

  202.        The  <STRONG>vid_attr</STRONG>  and <STRONG>vid_puts</STRONG> routines correspond to vidattr
    203. 

  203.        and vidputs, respectively.  They use a  set  of  arguments
    204. 

  204.        for  representing  the  video attributes plus color, i.e.,
    205. 

  205.        one of type attr_t for the attributes and one of short for
    206. 

  206.        the color_pair number.  The <STRONG>vid_attr</STRONG> and <STRONG>vid_puts</STRONG> routines
    207. 

  207.        are designed to use the attribute constants with  the  <EM>WA</EM><STRONG>_</STRONG>
    208. 

  208.        prefix.   The  opts  argument  is reserved for future use.
    209. 

  209.        Currently, applications must provide a  null  pointer  for
    210. 

  210.        that argument.
    211. 

  211. 

  212.        The  <STRONG>mvcur</STRONG>  routine  provides low-level cursor motion.  It
    213. 

  213.        takes effect immediately (rather  than  at  the  next  re-
    214. 

  214.        fresh).
    215. 

  215. 

  216.        The  <STRONG>tigetflag</STRONG>,  <STRONG>tigetnum</STRONG> and <STRONG>tigetstr</STRONG> routines return the
    217. 

  217.        value of the capability corresponding to the <STRONG>terminfo</STRONG> <EM>cap-</EM>
    218. 

  218.        <EM>name</EM> passed to them, such as <STRONG>xenl</STRONG>.
    219. 

  219. 

  220.        The  <STRONG>tigetflag</STRONG>  routine returns the value <STRONG>-1</STRONG> if <EM>capname</EM> is
    221. 

  221.        not a boolean capability, or <STRONG>0</STRONG> if it is canceled or absent
    222. 

  222.        from the terminal description.
    223. 

  223. 

  224.        The  <STRONG>tigetnum</STRONG>  routine  returns the value <STRONG>-2</STRONG> if <EM>capname</EM> is
    225. 

  225.        not a numeric capability, or <STRONG>-1</STRONG> if it is canceled  or  ab-
    226. 

  226.        sent from the terminal description.
    227. 

  227. 

  228.        The  <STRONG>tigetstr</STRONG> routine returns the value <STRONG>(char</STRONG> <STRONG>*)-1</STRONG> if <EM>cap-</EM>
    229. 

  229.        <EM>name</EM> is not a string capability, or <STRONG>0</STRONG> if it is canceled or
    230. 

  230.        absent from the terminal description.
    231. 

  231. 

  232.        The <EM>capname</EM> for each capability is given in the table col-
    233. 

  233.        umn entitled <EM>capname</EM> code in the capabilities  section  of
    234. 

  234.        <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.
    235. 

  235. 

  236.               <STRONG>char</STRONG> <STRONG>*boolnames[]</STRONG>, <STRONG>*boolcodes[]</STRONG>, <STRONG>*boolfnames[]</STRONG>
    237. 

  237. 

  238.               <STRONG>char</STRONG> <STRONG>*numnames[]</STRONG>, <STRONG>*numcodes[]</STRONG>, <STRONG>*numfnames[]</STRONG>
    239. 

  239. 

  240.               <STRONG>char</STRONG> <STRONG>*strnames[]</STRONG>, <STRONG>*strcodes[]</STRONG>, <STRONG>*strfnames[]</STRONG>
    241. 

  241. 

  242.        These  null-terminated  arrays  contain  the <EM>capnames</EM>, the
    243. 

  243.        <STRONG>termcap</STRONG> codes, and the full C names, for each of the  <STRONG>ter-</STRONG>
    244. 

  244.        <STRONG>minfo</STRONG> variables.
    245. 

  245. 

  246. 

  247. </PRE>
    248. 

  248. <H2>RETURN VALUE</H2><PRE>
    249. 

  249.        Routines  that  return  an integer return <STRONG>ERR</STRONG> upon failure
    250. 

  250.        and <STRONG>OK</STRONG> (SVr4 only specifies "an integer value  other  than
    251. 

  251.        <STRONG>ERR</STRONG>")  upon  successful completion, unless otherwise noted
    252. 

  252.        in the preceding routine descriptions.
    253. 

  253. 

  254.        Routines that return pointers always return <STRONG>NULL</STRONG> on error.
    255. 

  255. 

  256.        X/Open  defines  no error conditions.  In this implementa-
    257. 

  257.        tion
    258. 

  258. 

  259.               <STRONG>del_curterm</STRONG>
    260. 

  260.                    returns an error if its terminal parameter  is
    261. 

  261.                    null.
    262. 

  262. 

  263.               <STRONG>putp</STRONG> calls <STRONG>tputs</STRONG>, returning the same error-codes.
    264. 

  264. 

  265.               <STRONG>restartterm</STRONG>
    266. 

  266.                    returns an error if the associated call to <STRONG>se-</STRONG>
    267. 

  267.                    <STRONG>tupterm</STRONG> returns an error.
    268. 

  268. 

  269.               <STRONG>setupterm</STRONG>
    270. 

  270.                    returns an error if it cannot allocate  enough
    271. 

  271.                    memory, or create the initial windows (stdscr,
    272. 

  272.                    curscr, newscr).  Other error  conditions  are
    273. 

  273.                    documented above.
    274. 

  274. 

  275.               <STRONG>tputs</STRONG>
    276. 

  276.                    returns  an  error  if the string parameter is
    277. 

  277.                    null.  It does not detect I/O  errors:  X/Open
    278. 

  278.                    states  that <STRONG>tputs</STRONG> ignores the return value of
    279. 

  279.                    the output function <EM>putc</EM>.
    280. 

  280. 

  281. 

  282. </PRE>
    283. 

  283. <H2>NOTES</H2><PRE>
    284. 

  284.        The <STRONG>setupterm</STRONG> routine should be used in place of  <STRONG>setterm</STRONG>.
    285. 

  285.        It  may be useful when you want to test for terminal capa-
    286. 

  286.        bilities without committing to the allocation  of  storage
    287. 

  287.        involved in <STRONG>initscr</STRONG>.
    288. 

  288. 

  289.        Note that <STRONG>vidattr</STRONG> and <STRONG>vidputs</STRONG> may be macros.
    290. 

  290. 

  291. 

  292. </PRE>
    293. 

  293. <H2>PORTABILITY</H2><PRE>
    294. 

  294.        The  function  <STRONG>setterm</STRONG> is not described by X/Open and must
    295. 

  295.        be considered non-portable.  All other  functions  are  as
    296. 

  296.        described by X/Open.
    297. 

  297. 

  298.        <STRONG>setupterm</STRONG>  copies  the terminal name to the array <STRONG>ttytype</STRONG>.
    299. 

  299.        This is not part of X/Open Curses, but is assumed by  some
    300. 

  300.        applications.
    301. 

  301. 

  302.        In  System V Release 4, <STRONG>set_curterm</STRONG> has an <STRONG>int</STRONG> return type
    303. 

  303.        and returns <STRONG>OK</STRONG> or <STRONG>ERR</STRONG>.  We have chosen  to  implement  the
    304. 

  304.        X/Open Curses semantics.
    305. 

  305. 

  306.        In System V Release 4, the third argument of <STRONG>tputs</STRONG> has the
    307. 

  307.        type <STRONG>int</STRONG> <STRONG>(*putc)(char)</STRONG>.
    308. 

  308. 

  309.        At least one implementation of X/Open Curses (Solaris) re-
    310. 

  310.        turns  a value other than OK/ERR from <STRONG>tputs</STRONG>.  That returns
    311. 

  311.        the length of the string, and does no error-checking.
    312. 

  312. 

  313.        X/Open Curses prototypes <STRONG>tparm</STRONG> with a fixed number of  pa-
    314. 

  314.        rameters,  rather than a variable argument list.  This im-
    315. 

  315.        plementation uses a variable argument list.  Portable  ap-
    316. 

  316.        plications  should  provide 9 parameters after the format;
    317. 

  317.        zeroes are fine for this purpose.
    318. 

  318. 

  319.        X/Open notes that after calling <STRONG>mvcur</STRONG>,  the  curses  state
    320. 

  320.        may  not  match the actual terminal state, and that an ap-
    321. 

  321.        plication should touch and refresh the window  before  re-
    322. 

  322.        suming normal curses calls.  Both ncurses and System V Re-
    323. 

  323.        lease 4 curses implement <STRONG>mvcur</STRONG> using the SCREEN data allo-
    324. 

  324.        cated in either <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG>.  So though it is docu-
    325. 

  325.        mented as a terminfo function, <STRONG>mvcur</STRONG> is  really  a  curses
    326. 

  326.        function which is not well specified.
    327. 

  327. 

  328.        X/Open  states  that  the  old  location must be given for
    329. 

  329.        <STRONG>mvcur</STRONG>.  This implementation allows the caller to use  -1's
    330. 

  330.        for  the old ordinates.  In that case, the old location is
    331. 

  331.        unknown.
    332. 

  332. 

  333.        Extended terminal capability names, e.g.,  as  defined  by
    334. 

  334.        <STRONG>tic</STRONG> <STRONG>-x</STRONG>,  are  not  stored  in the arrays described in this
    335. 

  335.        section.
    336. 

  336. 

  337. 

  338. </PRE>
    339. 

  339. <H2>SEE ALSO</H2><PRE>
    340. 

  340.        <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>, <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>,  <STRONG>curs_term-</STRONG>
    341. 

  341.        <STRONG><A HREF="curs_termcap.3x.html">cap(3x)</A></STRONG>, <STRONG><A HREF="putc.3.html">putc(3)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>
    342. 

  342. 

  343. 

  344. 

  345.                                                       <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
    346. 

  346. </PRE>
    347. 

  347. <HR>
    348. 

  348. <ADDRESS>
    349. 

  349. Man(1) output converted with
    350. 

  350. <a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
    351. 

  351. </ADDRESS>
    352. 

  352. </BODY>
    353. 

  353. </HTML>
    354. 

  354.