ncurses 6.0 - patch 20160820
[ncurses.git] / doc / html / man / ncurses.3x.html
index d451806af80121f17a349c8f2bf69fba4f2ccf7d..2e9e92eb4cde4e3f8fa2a4b0395bbed67b9d8a73 100644 (file)
 
 
 
-</PRE>
-<H2><a name="h2-NAME">NAME</a></H2><PRE>
+</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
        <STRONG>ncurses</STRONG> - CRT screen handling and optimization package
 
 
-</PRE>
-<H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
+</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
 
 
-</PRE>
-<H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
+</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
        The  <STRONG>ncurses</STRONG>  library  routines  give the user a terminal-
        independent method of updating character screens with rea-
        sonable optimization.  This implementation is "new curses"
        (ncurses) and is the approved replacement for 4.4BSD clas-
        sic  curses,  which has been discontinued.  This describes
-       <STRONG>ncurses</STRONG> version 6.0 (patch 20151024).
+       <STRONG>ncurses</STRONG> version 6.0 (patch 20160820).
 
        The <STRONG>ncurses</STRONG> library emulates the curses library of  System
        V  Release  4  UNIX,  and  XPG4 (X/Open Portability Guide)
@@ -97,8 +94,7 @@
        access to low-level terminal-manipulation routines.
 
 
-</PRE>
-<H3><a name="h3-Initialization">Initialization</a></H3><PRE>
+</PRE><H3><a name="h3-Initialization">Initialization</a></H3><PRE>
        The  library uses the locale which the calling program has
        initialized.  That is normally done with <STRONG>setlocale</STRONG>:
 
        for doing this.  [See <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> for further details.]
 
 
-</PRE>
-<H3><a name="h3-Datatypes">Datatypes</a></H3><PRE>
+</PRE><H3><a name="h3-Datatypes">Datatypes</a></H3><PRE>
        The <STRONG>ncurses</STRONG> library permits manipulation  of  data  struc-
        tures,  called  <EM>windows</EM>,  which  can be thought of as two-
        dimensional arrays of characters representing all or  part
        <STRONG>&lt;curses.h&gt;</STRONG>, such as <STRONG>A_REVERSE</STRONG>, <STRONG>ACS_HLINE</STRONG>, and <STRONG>KEY_LEFT</STRONG>.
 
 
-</PRE>
-<H3><a name="h3-Environment-variables">Environment variables</a></H3><PRE>
+</PRE><H3><a name="h3-Environment-variables">Environment variables</a></H3><PRE>
        If the environment variables <STRONG>LINES</STRONG> and <STRONG>COLUMNS</STRONG> are set, or
        if  the program is executing in a window environment, line
        and column information in the  environment  will  override
        <STRONG>curscr</STRONG> can be used in only a few routines.
 
 
-</PRE>
-<H3><a name="h3-Routine-and-Argument-Names">Routine and Argument Names</a></H3><PRE>
+</PRE><H3><a name="h3-Routine-and-Argument-Names">Routine and Argument Names</a></H3><PRE>
        Many  <STRONG>curses</STRONG> routines have two or more versions.  The rou-
        tines prefixed with <STRONG>w</STRONG> require a window argument.  The rou-
        tines prefixed with <STRONG>p</STRONG> require a pad argument.  Those with-
                becomes <STRONG>wadd_wch</STRONG>.
 
 
-</PRE>
-<H3><a name="h3-Routine-Name-Index">Routine Name Index</a></H3><PRE>
+</PRE><H3><a name="h3-Routine-Name-Index">Routine Name Index</a></H3><PRE>
        The following table lists each <STRONG>curses</STRONG> routine and the name
        of the manual page on which  it  is  described.   Routines
        flagged  with  `*'  are ncurses-specific, not described by
               wvline_set              <STRONG><A HREF="curs_border_set.3x.html">curs_border_set(3x)</A></STRONG>
 
 
-</PRE>
-<H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
+</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
        Routines that return an integer return  <STRONG>ERR</STRONG>  upon  failure
        and  an  integer value other than <STRONG>ERR</STRONG> upon successful com-
        pletion, unless otherwise noted in  the  routine  descrip-
        Routines that return pointers return <STRONG>NULL</STRONG> on error.
 
 
-</PRE>
-<H2><a name="h2-ENVIRONMENT">ENVIRONMENT</a></H2><PRE>
+</PRE><H2><a name="h2-ENVIRONMENT">ENVIRONMENT</a></H2><PRE>
        The following environment symbols are useful for customiz-
        ing the runtime behavior of the <STRONG>ncurses</STRONG> library.  The most
        important ones have been already discussed in detail.
        it does not happen to be a single character.
 
 
-</PRE>
-<H3><a name="h3-BAUDRATE">BAUDRATE</a></H3><PRE>
+</PRE><H3><a name="h3-BAUDRATE">BAUDRATE</a></H3><PRE>
        The  debugging  library  checks  this environment variable
        when the application has redirected output to a file.  The
        variable's  numeric value is used for the baudrate.  If no
        costs that depend on baudrate.
 
 
-</PRE>
-<H3><a name="h3-COLUMNS">COLUMNS</a></H3><PRE>
+</PRE><H3><a name="h3-COLUMNS">COLUMNS</a></H3><PRE>
        Specify the width of the screen in  characters.   Applica-
        tions  running in a windowing environment usually are able
        to obtain the width of the window in which they  are  exe-
        system calls or the terminal database.
 
 
-</PRE>
-<H3><a name="h3-ESCDELAY">ESCDELAY</a></H3><PRE>
+</PRE><H3><a name="h3-ESCDELAY">ESCDELAY</a></H3><PRE>
        Specifies  the  total  time,  in  milliseconds,  for which
        ncurses will await a character sequence, e.g., a  function
        key.   The default value, 1000 milliseconds, is enough for
        lems when compiling an application.
 
 
-</PRE>
-<H3><a name="h3-HOME">HOME</a></H3><PRE>
+</PRE><H3><a name="h3-HOME">HOME</a></H3><PRE>
        Tells <STRONG>ncurses</STRONG> where your home directory is.  That is where
        it may read and write auxiliary terminal descriptions:
 
        $HOME/.terminfo
 
 
-</PRE>
-<H3><a name="h3-LINES">LINES</a></H3><PRE>
+</PRE><H3><a name="h3-LINES">LINES</a></H3><PRE>
        Like  COLUMNS, specify the height of the screen in charac-
        ters.  See COLUMNS for a detailed description.
 
 
-</PRE>
-<H3><a name="h3-MOUSE_BUTTONS_123">MOUSE_BUTTONS_123</a></H3><PRE>
+</PRE><H3><a name="h3-MOUSE_BUTTONS_123">MOUSE_BUTTONS_123</a></H3><PRE>
        This applies only to the OS/2 EMX port.  It specifies  the
        order  of  buttons  on the mouse.  OS/2 numbers a 3-button
        mouse inconsistently from other platforms:
        or 321.  If it is not specified, <STRONG>ncurses</STRONG> uses 132.
 
 
-</PRE>
-<H3><a name="h3-NCURSES_ASSUMED_COLORS">NCURSES_ASSUMED_COLORS</a></H3><PRE>
+</PRE><H3><a name="h3-NCURSES_ASSUMED_COLORS">NCURSES_ASSUMED_COLORS</a></H3><PRE>
        Override the compiled-in assumption  that  the  terminal's
        default   colors   are  white-on-black  (see  <STRONG>default_col-</STRONG>
        <STRONG><A HREF="default_colors.3x.html">ors(3x)</A></STRONG>).  You may set the foreground and background color
        value is allowed.
 
 
-</PRE>
-<H3><a name="h3-NCURSES_CONSOLE2">NCURSES_CONSOLE2</a></H3><PRE>
+</PRE><H3><a name="h3-NCURSES_CONSOLE2">NCURSES_CONSOLE2</a></H3><PRE>
        This applies only to the MinGW port of ncurses.
 
        The <STRONG>Console2</STRONG> program's handling of the  Microsoft  Console
        same effect.
 
 
-</PRE>
-<H3><a name="h3-NCURSES_GPM_TERMS">NCURSES_GPM_TERMS</a></H3><PRE>
+</PRE><H3><a name="h3-NCURSES_GPM_TERMS">NCURSES_GPM_TERMS</a></H3><PRE>
        This applies only to ncurses configured  to  use  the  GPM
        interface.
 
        attempt to open GPM if TERM contains "linux".
 
 
-</PRE>
-<H3><a name="h3-NCURSES_NO_HARD_TABS">NCURSES_NO_HARD_TABS</a></H3><PRE>
+</PRE><H3><a name="h3-NCURSES_NO_HARD_TABS">NCURSES_NO_HARD_TABS</a></H3><PRE>
        <STRONG>Ncurses</STRONG> may use tabs as part of the cursor movement  opti-
        mization.   In  some  cases,  your terminal driver may not
        handle these properly.  Set this environment  variable  to
        environment variable.
 
 
-</PRE>
-<H3><a name="h3-NCURSES_NO_PADDING">NCURSES_NO_PADDING</a></H3><PRE>
+</PRE><H3><a name="h3-NCURSES_NO_PADDING">NCURSES_NO_PADDING</a></H3><PRE>
        Most of the terminal descriptions in the terminfo database
        are written for real "hardware"  terminals.   Many  people
        use  terminal  emulators which run in a windowing environ-
        part of special control sequences such as <EM>flash</EM>.
 
 
-</PRE>
-<H3><a name="h3-NCURSES_NO_SETBUF">NCURSES_NO_SETBUF</a></H3><PRE>
+</PRE><H3><a name="h3-NCURSES_NO_SETBUF">NCURSES_NO_SETBUF</a></H3><PRE>
        This setting is obsolete.  Before changes
 
           <STRONG>o</STRONG>   started with 5.9 patch 20120825 and
        level curses calls do not.
 
 
-</PRE>
-<H3><a name="h3-NCURSES_NO_UTF8_ACS">NCURSES_NO_UTF8_ACS</a></H3><PRE>
+</PRE><H3><a name="h3-NCURSES_NO_UTF8_ACS">NCURSES_NO_UTF8_ACS</a></H3><PRE>
        During initialization, the <STRONG>ncurses</STRONG> library checks for spe-
        cial cases where VT100 line-drawing (and the corresponding
        alternate character set  capabilities)  described  in  the
        interface.
 
 
-</PRE>
-<H3><a name="h3-NCURSES_TRACE">NCURSES_TRACE</a></H3><PRE>
+</PRE><H3><a name="h3-NCURSES_TRACE">NCURSES_TRACE</a></H3><PRE>
        During   initialization,  the  <STRONG>ncurses</STRONG>  debugging  library
        checks the NCURSES_TRACE environment variable.  If  it  is
        defined, to a numeric value, <STRONG>ncurses</STRONG> calls the <STRONG>trace</STRONG> func-
        See <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG> for more information.
 
 
-</PRE>
-<H3><a name="h3-TERM">TERM</a></H3><PRE>
+</PRE><H3><a name="h3-TERM">TERM</a></H3><PRE>
        Denotes  your  terminal  type.  Each terminal type is dis-
        tinct, though many are similar.
 
        match that setting.
 
 
-</PRE>
-<H3><a name="h3-TERMCAP">TERMCAP</a></H3><PRE>
+</PRE><H3><a name="h3-TERMCAP">TERMCAP</a></H3><PRE>
        If  the  <STRONG>ncurses</STRONG>  library has been configured with <EM>termcap</EM>
        support, <STRONG>ncurses</STRONG> will check for a  terminal's  description
        in  termcap  form  if  it is not available in the terminfo
        mation, e.g., /etc/termcap.
 
 
-</PRE>
-<H3><a name="h3-TERMINFO">TERMINFO</a></H3><PRE>
+</PRE><H3><a name="h3-TERMINFO">TERMINFO</a></H3><PRE>
        Overrides the directory in which <STRONG>ncurses</STRONG> searches for your
        terminal description.  This is the simplest, but  not  the
        only  way to change the list of directories.  The complete
                  MINFO variable)
 
 
-</PRE>
-<H3><a name="h3-TERMINFO_DIRS">TERMINFO_DIRS</a></H3><PRE>
+</PRE><H3><a name="h3-TERMINFO_DIRS">TERMINFO_DIRS</a></H3><PRE>
        Specifies  a  list  of  directories to search for terminal
        descriptions.  The list is separated by colons (i.e., ":")
        on Unix, semicolons on OS/2 EMX.
        of a termcap file.
 
 
-</PRE>
-<H3><a name="h3-TERMPATH">TERMPATH</a></H3><PRE>
+</PRE><H3><a name="h3-TERMPATH">TERMPATH</a></H3><PRE>
        If TERMCAP does not hold a file name then  <STRONG>ncurses</STRONG>  checks
        the  TERMPATH  environment  variable.   This  is a list of
        filenames separated by spaces or  colons  (i.e.,  ":")  on
        $TERMINFO, $TERMINFO_DIRS, $TERMPATH, as well as $HOME.
 
 
-</PRE>
-<H2><a name="h2-ALTERNATE-CONFIGURATIONS">ALTERNATE CONFIGURATIONS</a></H2><PRE>
+</PRE><H2><a name="h2-ALTERNATE-CONFIGURATIONS">ALTERNATE CONFIGURATIONS</a></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
             ing it is always in the debug library.
 
 
-</PRE>
-<H2><a name="h2-FILES">FILES</a></H2><PRE>
+</PRE><H2><a name="h2-FILES">FILES</a></H2><PRE>
        /usr/share/tabset
             directory  containing  initialization  files  for the
             terminal capability database /usr/share/terminfo ter-
             minal capability database
 
 
-</PRE>
-<H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
+</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
        <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>  and  related  pages whose names begin "curs_"
        for detailed routine descriptions.
        <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>
 
 
-</PRE>
-<H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
+</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
        The  <STRONG>ncurses</STRONG>  library  can  be  compiled  with  an  option
        (<STRONG>-DUSE_GETCAP</STRONG>) that falls back to the old-style /etc/term-
        cap file if the terminal setup code cannot find a terminfo
        device.  See the <STRONG><A HREF="curs_print.3x.html">curs_print(3x)</A></STRONG> manual page for details.
 
 
-</PRE>
-<H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
+</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
        The  <STRONG>ncurses</STRONG>  library is intended to be BASE-level confor-
        mant with XSI Curses.  The EXTENDED XSI Curses functional-
        ity (including color support) is supported.
        package's portability correspondingly.
 
 
-</PRE>
-<H2><a name="h2-NOTES">NOTES</a></H2><PRE>
+</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
        The header  file  <STRONG>&lt;curses.h&gt;</STRONG>  automatically  includes  the
        header files <STRONG>&lt;stdio.h&gt;</STRONG> and <STRONG>&lt;unctrl.h&gt;</STRONG>.
 
        ture of AT&amp;T System V Release 3 curses.
 
 
-</PRE>
-<H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
+</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
        Zeyd M. Ben-Halim, Eric  S.  Raymond,  Thomas  E.  Dickey.
        Based on pcurses by Pavel Curtis.