~ubuntu-branches/debian/sid/ncurses/sid-200908151543

  * Copyright (c) 1998-2007,2008 Free Software Foundation, Inc.              *

  * @Id: ncurses.3x,v 1.91 2008/10/11 20:43:11 tom Exp @

       4.4BSD  classic curses, which has been discontinued.  This

       describes <STRONG>ncurses</STRONG> version 5.6 (patch 20081011).

 

       The <STRONG>ncurses</STRONG> library emulates  the  <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>  library  of

       System  V  Release  4  UNIX,  and XPG4 (X/Open Portability

       Guide) curses (also known as XSI curses).  XSI stands  for

       X/Open  System  Interfaces Extension.  The <STRONG>ncurses</STRONG> library

       is freely redistributable  in  source  form.   Differences

       from  the  SVr4 curses are summarized under the <STRONG>EXTENSIONS</STRONG>

       and <STRONG>PORTABILITY</STRONG> sections below and described in detail  in

       the  respective  <STRONG>EXTENSIONS</STRONG>, <STRONG>PORTABILITY</STRONG> and <STRONG>BUGS</STRONG> sections

       of individual man pages.

 

       The <STRONG>ncurses</STRONG> library also provides many useful  extensions,

       i.e.,  features  which  cannot  be implemented by a simple

       add-on library but which require access to  the  internals

       of the library.

 

       A  program  using  these  routines must be linked with the

       <STRONG>-lncurses</STRONG> option, or (if it has been generated)  with  the

       debugging  library  <STRONG>-lncurses_g</STRONG>.   (Your system integrator

       may also have installed these libraries  under  the  names

       tory)  that describe curses actions.  See also the section

       on <STRONG>ALTERNATE</STRONG> <STRONG>CONFIGURATIONS</STRONG>.

       The  library uses the locale which the calling program has

       initialized.  That is normally done with <STRONG>setlocale</STRONG>:

 

             <STRONG>setlocale(LC_ALL,</STRONG> <STRONG>"");</STRONG>

 

       If the locale is not initialized, the library assumes that

       characters  are  printable  as in ISO-8859-1, to work with

       certain legacy programs.  You should initialize the locale

       and  not  rely on specific details of the library when the

       locale has not been setup.

 

       The function <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG> must be called to initial-

       ize the library before any of the other routines that deal

       with windows and screens are  used.   The  routine  <STRONG>endwin</STRONG>

       must be called before exiting.

 

       To  get  character-at-a-time  input  without echoing (most

       interactive, screen oriented programs want this), the fol-

       lowing sequence should be used:

       that's done by the <STRONG><A HREF="panel.3x.html">panel(3x)</A></STRONG> library.  This means that you

       dows and not using <STRONG>stdscr</STRONG> at all.   Mixing  the  two  will

       Among those, the most basic routines are <STRONG>move</STRONG>  and  <STRONG>addch</STRONG>.

       window.   The routines not beginning with <STRONG>w</STRONG> affect <STRONG>stdscr</STRONG>.

       information read by <EM>terminfo</EM>.  This would affect a program

       value  <STRONG>TRUE</STRONG>  or <STRONG>FALSE</STRONG>; <EM>bf</EM> is always of type <STRONG>bool</STRONG>.  Most of

       the data types used in the library routines, such as  <STRONG>WIN-</STRONG>

       <STRONG>DOW</STRONG>,  <STRONG>SCREEN</STRONG>,  <STRONG>bool</STRONG>, and <STRONG>chtype</STRONG> are defined in <STRONG>&lt;curses.h&gt;</STRONG>.

       Types used for the terminfo routines such as <STRONG>TERMINAL</STRONG>  are

       defined in <STRONG>&lt;term.h&gt;</STRONG>.

 

       This  manual  page describes functions which may appear in

       any configuration of the library.  There  are  two  common

       configurations of the library:

 

              ncurses

                   the  "normal"  library,  which  handles  8-bit

                   characters.  The normal (8-bit) library stores

                   characters  combined with attributes in <STRONG>chtype</STRONG>

                   data.

 

                   Attributes alone (no corresponding  character)

                   may  be  stored  in  <STRONG>chtype</STRONG>  or the equivalent

                   <STRONG>attr_t</STRONG> data.  In  either  case,  the  data  is

                   stored in something like an integer.

 

                   Each  cell  (row  and  column)  in a <STRONG>WINDOW</STRONG> is

                   stored as a <STRONG>chtype</STRONG>.

 

              ncursesw

                   the so-called "wide"  library,  which  handles

                   multibyte   characters  (See  the  section  on

                   <STRONG>ALTERNATE</STRONG> <STRONG>CONFIGURATIONS</STRONG>).  The "wide" library

                   includes  all  of  the calls from the "normal"

                   library.  It adds about one third  more  calls

                   using data types which store multibyte charac-

                   ters:

 

                   <STRONG>cchar_t</STRONG>

                        corresponds to <STRONG>chtype</STRONG>.  However it  is  a

                        structure,  because  more  data is stored

                        than can fit into an integer.  The  char-

                        acters are large enough to require a full

                        integer value - and  there  may  be  more

                        than  one  character per cell.  The video

                        attributes and color are stored in  sepa-

                        rate fields of the structure.

 

                        Each cell (row and column) in a <STRONG>WINDOW</STRONG> is

                        stored as a <STRONG>cchar_t</STRONG>.

 

                   <STRONG>wchar_t</STRONG>

                        stores a "wide" character.  Like  <STRONG>chtype</STRONG>,

                        this may be an integer.

 

                   <STRONG>wint_t</STRONG>

                        stores  a <STRONG>wchar_t</STRONG> or <STRONG>WEOF</STRONG> - not the same,

                        though both may have the same size.

 

                   The  "wide"  library  provides  new  functions

                   which  are analogous to functions in the "nor-

                   mal" library.  There is  a  naming  convention

                   which  relates  many  of the normal/wide vari-

                   ants: a "_w" is inserted into the  name.   For

                   example, <STRONG>waddch</STRONG> becomes <STRONG>wadd_wch</STRONG>.

 

 

 

              getattrs                <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>

              getbegx                 <STRONG><A HREF="curs_legacy.3x.html">curs_legacy(3x)</A></STRONG>*

              getbegy                 <STRONG><A HREF="curs_legacy.3x.html">curs_legacy(3x)</A></STRONG>*

              getcurx                 <STRONG><A HREF="curs_legacy.3x.html">curs_legacy(3x)</A></STRONG>*

              getcury                 <STRONG><A HREF="curs_legacy.3x.html">curs_legacy(3x)</A></STRONG>*

              getmaxx                 <STRONG><A HREF="curs_legacy.3x.html">curs_legacy(3x)</A></STRONG>*

              getmaxy                 <STRONG><A HREF="curs_legacy.3x.html">curs_legacy(3x)</A></STRONG>*

              getparx                 <STRONG><A HREF="curs_legacy.3x.html">curs_legacy(3x)</A></STRONG>*

              getpary                 <STRONG><A HREF="curs_legacy.3x.html">curs_legacy(3x)</A></STRONG>*

              is_cleared              <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*

              is_idcok                <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*

              is_idlok                <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*

 

              is_immedok              <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*

              is_keypad               <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*

              is_leaveok              <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*

              is_nodelay              <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*

              is_notimeout            <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*

              is_scrollok             <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*

              is_syncok               <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*

              is_term_resized         <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG>*

 

              nofilter                <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>*

 

 

              use_legacy_coding       <STRONG><A HREF="legacy_coding.3x.html">legacy_coding(3x)</A></STRONG>*

 

            <STRONG><A HREF="default_colors.3x.html">default_colors(3x)</A></STRONG>).   You may set the foreground and

            background color values with this  environment  vari-

            able  by  proving  a 2-element list: foreground,back-

            ground.  For example, to tell ncurses to  not  assume

            anything  about  the colors, set this to "-1,-1".  To

            make it green-on-black, set it to "2,0".   Any  posi-

            tive value from zero to the terminfo <STRONG>max_colors</STRONG> value

            is allowed.

 

       NCURSES_GPM_TERMS

            This applies only to ncurses configured  to  use  the

            GPM interface.

 

            If present, the environment variable is a list of one

            or more terminal names against which the  TERM  envi-

            ronment  variable is matched.  Setting it to an empty

            value disables the GPM interface; using the  built-in

            support for xterm, etc.

 

            If  the  environment variable is absent, ncurses will

            attempt to open GPM if TERM contains "linux".

 

       NCURSES_NO_HARD_TABS

            <STRONG>Ncurses</STRONG> may use tabs as part of the  cursor  movement

            optimization.   In  some  cases, your terminal driver

            may not handle these properly.  Set this  environment

            variable to disable the feature.  You can also adjust

            your <STRONG>stty</STRONG> settings to avoid the problem.

 

       NCURSES_NO_MAGIC_COOKIES

            Some  terminals  use  a  magic-cookie  feature  which

            requires  special  handling  to make highlighting and

            other video attributes  display  properly.   You  can

            suppress  the  highlighting entirely for these termi-

            nals by setting this environment variable.

            windowing    environment    and    use   curses-based

            applications.  Terminal emulators can  duplicate  all

            of  the important aspects of a hardware terminal, but

            they do not have the  same  limitations.   The  chief

            limitation of a hardware terminal from the standpoint

            of your application is the  management  of  dataflow,

            i.e.,  timing.   Unless a hardware terminal is inter-

            faced into a terminal concentrator (which  does  flow

            control),   it  (or  your  application)  must  manage

            dataflow, preventing overruns.  The cheapest solution

            (no  hardware cost) is for your program to do this by

            pausing  after  operations  that  the  terminal  does

            slowly, such as clearing the display.

<H2>ALTERNATE CONFIGURATIONS</H2><PRE>

       Several  different  configurations are possible, depending

       on  the  configure  script  options  used  when   building

       <STRONG>ncurses</STRONG>.   There  are a few main options whose effects are

       visible to the applications developer using <STRONG>ncurses</STRONG>:

 

       --disable-overwrite

            The standard include for <STRONG>ncurses</STRONG> is as noted in  <STRONG>SYN-</STRONG>

            <STRONG>OPSIS</STRONG>:

 

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

 

            This  option is used to avoid filename conflicts when

            <STRONG>ncurses</STRONG> is not the main implementation of  curses  of

            the  computer.   If  <STRONG>ncurses</STRONG>  is  installed disabling

            overwrite, it puts its  headers  in  a  subdirectory,

            e.g.,

 

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

 

            It  also  omits a symbolic link which would allow you

            to use <STRONG>-lcurses</STRONG> to build executables.

 

       --enable-widec

            The configure script renames the library and (if  the

            <STRONG>--disable-overwrite</STRONG>  option  is used) puts the header

            files  in  a  different  subdirectory.   All  of  the

            library  names  have  a  "w"  appended to them, i.e.,

            instead of

 

            <STRONG>-lncurses</STRONG>

 

            you link with

 

            <STRONG>-lncursesw</STRONG>

 

            You must also define <STRONG>_XOPEN_SOURCE_EXTENDED</STRONG> when com-

            piling  for  the  wide-character  library  to use the

            extended (wide-character)  functions.   The  <STRONG>curses.h</STRONG>

            file   which  is  installed  for  the  wide-character

            library is designed to be compatible with the  normal

            library's header.  Only the size of the <STRONG>WINDOW</STRONG> struc-

            ture differs, and very few applications require  more

            than  a  pointer  to  <STRONG>WINDOW</STRONG>s.   If  the  headers are

            installed  allowing  overwrite,  the   wide-character

            library's  headers should be installed last, to allow

            applications to be built using  either  library  from

            the same set of headers.

 

       --with-shared

 

       --with-normal

 

       --with-debug

 

       --with-profile

            The  shared  and normal (static) library names differ

            by their  suffixes,  e.g.,  <STRONG>libncurses.so</STRONG>  and  <STRONG>libn-</STRONG>

            <STRONG>curses.a</STRONG>.   The  debug  and profiling libraries add a

            "_g" and a "_p" to the root names respectively, e.g.,

            <STRONG>libncurses_g.a</STRONG> and <STRONG>libncurses_p.a</STRONG>.

 

       --with-trace

            The  <STRONG>trace</STRONG>  function  normally  resides  in the debug

            library, but it is sometimes useful to configure this

            in  the  shared  library.   Configure  scripts should

            check for the function's existence rather than assum-

            ing it is always in the debug library.

 

 

</PRE>

            terminal capability database /usr/share/terminfo ter-

            minal capability database

       mouse  events on certain terminals (including xterm).  See

       mant with XSI Curses.  The EXTENDED XSI Curses functional-

       ity (including color support) is supported.

       A  small  number of local differences (that is, individual

       differences between the XSI Curses and <STRONG>ncurses</STRONG> calls)  are

       described  in  <STRONG>PORTABILITY</STRONG>  sections  of  the  library man

       This implementation also contains several extensions:

 

            The routine <STRONG>has_key</STRONG> is not part of XPG4,  nor  is  it

            present  in SVr4.  See the <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG> manual page

            for details.

 

            The routine <STRONG>slk_attr</STRONG> is not part of XPG4, nor  is  it

            present  in  SVr4.   See the <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG> manual page

            for details.

 

            The routines <STRONG>getmouse</STRONG>,  <STRONG>mousemask</STRONG>,  <STRONG>ungetmouse</STRONG>,  <STRONG>mou-</STRONG>

            <STRONG>seinterval</STRONG>,  and <STRONG>wenclose</STRONG> relating to mouse interfac-

            ing are not part of XPG4, nor  are  they  present  in

            SVr4.    See   the  <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>  manual  page  for

            details.

 

            The routine <STRONG>mcprint</STRONG> was not present in  any  previous

            curses implementation.  See the <STRONG><A HREF="curs_print.3x.html">curs_print(3x)</A></STRONG> manual

            page for details.

 

            The routine <STRONG>wresize</STRONG> is not part of XPG4,  nor  is  it

            present in SVr4.  See the <STRONG><A HREF="wresize.3x.html">wresize(3x)</A></STRONG> manual page for

            details.

 

            The WINDOW structure's internal details can be hidden

            from  application  programs.  See <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG> for

            the discussion of <STRONG>is_scrollok</STRONG>, etc.

 

       In historic curses versions, delays embedded in the  capa-

       delay bits in the UNIX tty driver.   In  this  implementa-

       tion,  all  padding  is  done  by sending NUL bytes.  This

       method is slightly more expensive, but narrows the  inter-

       face  to  the  UNIX kernel significantly and increases the

       package's portability correspondingly.

       The header  file  <STRONG>&lt;curses.h&gt;</STRONG>  automatically  includes  the

       If  standard  output from a <STRONG>ncurses</STRONG> program is re-directed

       to something which is not a tty, screen  updates  will  be

       Zeyd M. Ben-Halim, Eric  S.  Raymond,  Thomas  E.  Dickey.