← Back to branch summary

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

« back to all changes in this revision

Viewing changes to doc/html/man/ncurses.3x.html

  • Committer: Package Import Robot
  • Author(s): Sven Joachim
  • Date: 2015-08-17 18:01:53 UTC
  • mfrom: (1.32.11)
  • Revision ID: package-import@ubuntu.com-20150817180153-ywf02awpkuzvqwdv
Tags: 6.0+20150810-1
http://bugs.debian.org/790548
http://bugs.debian.org/788610
* New upstream release.
  - Fix comparison against "/usr/include" in misc/gen-pkgconfig.in
    (Closes: #790548).
* Configure with "--with-abi-version=5", upstream defaults to abi 6 now.
* Configure with "--with-versioned-syms" (Closes: #788610).
  - Bump minimal versions of all symbols as well as shlibs to 6.
* After building the wide library, install it into a temporary
  scratchdir so that test/configure can find the necessary auxiliary
  files (see #786436).
* Drop the libncursesw5-dev build-dependency.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/html/man/ncurses.3x.html
1
1
<!-- 
2
2
  * t
3
3
  ****************************************************************************
4
 
  * Copyright (c) 1998-2013,2014 Free Software Foundation, Inc.              *
 
4
  * Copyright (c) 1998-2014,2015 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            *
27
27
  * sale, use or other dealings in this Software without prior written       *
28
28
  * authorization.                                                           *
29
29
  ****************************************************************************
30
 
  * @Id: ncurses.3x,v 1.119 2014/08/09 20:54:30 tom Exp @
 
30
  * @Id: ncurses.3x,v 1.124 2015/08/08 14:57:51 tom Exp @
31
31
-->
32
32
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
33
33
<HTML>
63
63
       sonable optimization.  This implementation is "new curses"
64
64
       (ncurses) and is the approved replacement for 4.4BSD clas-
65
65
       sic  curses,  which has been discontinued.  This describes
66
 
       <STRONG>ncurses</STRONG> version 5.9 (patch 20150516).
 
66
       <STRONG>ncurses</STRONG> version 6.0 (patch 20150808).
67
67
 
68
68
       The <STRONG>ncurses</STRONG> library emulates the curses library of  System
69
69
       V  Release  4  UNIX,  and  XPG4 (X/Open Portability Guide)
96
96
       lation; use of soft label keys; terminfo capabilities; and
97
97
       access to low-level terminal-manipulation routines.
98
98
 
 
99
 
 
100
</PRE>
 
101
<H3><a name="h3-Initialization">Initialization</a></H3><PRE>
99
102
       The  library uses the locale which the calling program has
100
103
       initialized.  That is normally done with <STRONG>setlocale</STRONG>:
101
104
 
131
134
       <STRONG>TERM</STRONG>  has  been  exported.  <STRONG>tset(1)</STRONG> is usually responsible
132
135
       for doing this.  [See <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> for further details.]
133
136
 
 
137
 
 
138
</PRE>
 
139
<H3><a name="h3-Datatypes">Datatypes</a></H3><PRE>
134
140
       The <STRONG>ncurses</STRONG> library permits manipulation  of  data  struc-
135
141
       tures,  called  <EM>windows</EM>,  which  can be thought of as two-
136
142
       dimensional arrays of characters representing all or  part
175
181
       characters,   and  input  values  use  names,  defined  in
176
182
       <STRONG>&lt;curses.h&gt;</STRONG>, such as <STRONG>A_REVERSE</STRONG>, <STRONG>ACS_HLINE</STRONG>, and <STRONG>KEY_LEFT</STRONG>.
177
183
 
 
184
 
 
185
</PRE>
 
186
<H3><a name="h3-Environment-variables">Environment variables</a></H3><PRE>
178
187
       If the environment variables <STRONG>LINES</STRONG> and <STRONG>COLUMNS</STRONG> are set, or
179
188
       if  the program is executing in a window environment, line
180
189
       and column information in the  environment  will  override
248
257
       any  configuration  of  the library.  There are two common
249
258
       configurations of the library:
250
259
 
251
 
              ncurses
252
 
                   the  "normal"  library,  which  handles  8-bit
253
 
                   characters.  The normal (8-bit) library stores
254
 
                   characters combined with attributes in  <STRONG>chtype</STRONG>
255
 
                   data.
256
 
 
257
 
                   Attributes  alone (no corresponding character)
258
 
                   may be stored  in  <STRONG>chtype</STRONG>  or  the  equivalent
259
 
                   <STRONG>attr_t</STRONG>  data.   In  either  case,  the data is
260
 
                   stored in something like an integer.
261
 
 
262
 
                   Each cell (row and  column)  in  a  <STRONG>WINDOW</STRONG>  is
263
 
                   stored as a <STRONG>chtype</STRONG>.
264
 
 
265
 
              ncursesw
266
 
                   the  so-called  "wide"  library, which handles
267
 
                   multibyte  characters  (see  the  section   on
268
 
                   <STRONG>ALTERNATE</STRONG> <STRONG>CONFIGURATIONS</STRONG>).  The "wide" library
269
 
                   includes all of the calls  from  the  "normal"
270
 
                   library.   It  adds about one third more calls
271
 
                   using data types which store multibyte charac-
272
 
                   ters:
273
 
 
274
 
                   <STRONG>cchar_t</STRONG>
275
 
                        corresponds  to  <STRONG>chtype</STRONG>.  However it is a
276
 
                        structure, because more  data  is  stored
277
 
                        than  can fit into an integer.  The char-
278
 
                        acters are large enough to require a full
279
 
                        integer  value  -  and  there may be more
280
 
                        than one character per cell.   The  video
281
 
                        attributes  and color are stored in sepa-
282
 
                        rate fields of the structure.
283
 
 
284
 
                        Each cell (row and column) in a <STRONG>WINDOW</STRONG> is
285
 
                        stored as a <STRONG>cchar_t</STRONG>.
286
 
 
287
 
                   <STRONG>wchar_t</STRONG>
288
 
                        stores  a "wide" character.  Like <STRONG>chtype</STRONG>,
289
 
                        this may be an integer.
290
 
 
291
 
                   <STRONG>wint_t</STRONG>
292
 
                        stores a <STRONG>wchar_t</STRONG> or <STRONG>WEOF</STRONG> - not the  same,
293
 
                        though both may have the same size.
294
 
 
295
 
                   The  "wide"  library  provides  new  functions
296
 
                   which are analogous to functions in the  "nor-
297
 
                   mal"  library.   There  is a naming convention
298
 
                   which relates many of  the  normal/wide  vari-
299
 
                   ants:  a  "_w" is inserted into the name.  For
300
 
                   example, <STRONG>waddch</STRONG> becomes <STRONG>wadd_wch</STRONG>.
 
260
          <EM>ncurses</EM>
 
261
               the "normal" library, which handles 8-bit  charac-
 
262
               ters.   The  normal (8-bit) library stores charac-
 
263
               ters combined with attributes in <STRONG>chtype</STRONG> data.
 
264
 
 
265
               Attributes alone (no corresponding character)  may
 
266
               be stored in <STRONG>chtype</STRONG> or the equivalent <STRONG>attr_t</STRONG> data.
 
267
               In either case, the data is  stored  in  something
 
268
               like an integer.
 
269
 
 
270
               Each  cell  (row and column) in a <STRONG>WINDOW</STRONG> is stored
 
271
               as a <STRONG>chtype</STRONG>.
 
272
 
 
273
          <EM>ncursesw</EM>
 
274
               the so-called "wide" library, which handles multi-
 
275
               byte characters (see the section on <STRONG>ALTERNATE</STRONG> <STRONG>CON-</STRONG>
 
276
               <STRONG>FIGURATIONS</STRONG>).  The "wide" library includes all  of
 
277
               the  calls  from  the  "normal"  library.  It adds
 
278
               about one third more calls using data types  which
 
279
               store multibyte characters:
 
280
 
 
281
               <STRONG>cchar_t</STRONG>
 
282
                    corresponds  to  <STRONG>chtype</STRONG>.   However  it  is  a
 
283
                    structure, because more data is  stored  than
 
284
                    can  fit into an integer.  The characters are
 
285
                    large enough to require a full integer  value
 
286
                    -  and  there  may be more than one character
 
287
                    per cell.  The video attributes and color are
 
288
                    stored in separate fields of the structure.
 
289
 
 
290
                    Each  cell  (row  and  column) in a <STRONG>WINDOW</STRONG> is
 
291
                    stored as a <STRONG>cchar_t</STRONG>.
 
292
 
 
293
               <STRONG>wchar_t</STRONG>
 
294
                    stores a "wide" character.  Like <STRONG>chtype</STRONG>, this
 
295
                    may be an integer.
 
296
 
 
297
               <STRONG>wint_t</STRONG>
 
298
                    stores  a  <STRONG>wchar_t</STRONG>  or  <STRONG>WEOF</STRONG>  - not the same,
 
299
                    though both may have the same size.
 
300
 
 
301
               The "wide" library provides  new  functions  which
 
302
               are   analogous   to  functions  in  the  "normal"
 
303
               library.   There  is  a  naming  convention  which
 
304
               relates  many  of the normal/wide variants: a "_w"
 
305
               is inserted into the name.   For  example,  <STRONG>waddch</STRONG>
 
306
               becomes <STRONG>wadd_wch</STRONG>.
301
307
 
302
308
 
303
309
</PRE>
304
310
<H3><a name="h3-Routine-Name-Index">Routine Name Index</a></H3><PRE>
305
311
       The following table lists each <STRONG>curses</STRONG> routine and the name
306
 
       of  the  manual  page  on which it is described.  Routines
307
 
       flagged with `*' are ncurses-specific,  not  described  by
 
312
       of the manual page on which  it  is  described.   Routines
 
313
       flagged  with  `*'  are ncurses-specific, not described by
308
314
       XPG4 or present in SVr4.
309
315
 
310
316
              <STRONG>curses</STRONG> Routine Name     Manual Page Name
314
320
              _nc_free_and_exit       <STRONG><A HREF="curs_memleaks.3x.html">curs_memleaks(3x)</A></STRONG>*
315
321
              _nc_freeall             <STRONG><A HREF="curs_memleaks.3x.html">curs_memleaks(3x)</A></STRONG>*
316
322
              _nc_tracebits           <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG>*
317
 
 
318
323
              _traceattr              <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG>*
319
324
              _traceattr2             <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG>*
320
325
              _tracechar              <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG>*
 
326
 
321
327
              _tracechtype            <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG>*
322
328
              _tracechtype2           <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG>*
323
329
              _tracedump              <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG>*
380
386
              echochar                <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>
381
387
              endwin                  <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>
382
388
              erase                   <STRONG><A HREF="curs_clear.3x.html">curs_clear(3x)</A></STRONG>
383
 
 
384
389
              erasechar               <STRONG><A HREF="curs_termattrs.3x.html">curs_termattrs(3x)</A></STRONG>
385
390
              erasewchar              <STRONG><A HREF="curs_termattrs.3x.html">curs_termattrs(3x)</A></STRONG>
386
391
              filter                  <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>
387
392
              flash                   <STRONG><A HREF="curs_beep.3x.html">curs_beep(3x)</A></STRONG>
 
393
 
388
394
              flushinp                <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>
389
395
              get_wch                 <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG>
390
396
              get_wstr                <STRONG><A HREF="curs_get_wstr.3x.html">curs_get_wstr(3x)</A></STRONG>
446
452
              is_cleared              <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*
447
453
              is_idcok                <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*
448
454
              is_idlok                <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*
449
 
 
450
455
              is_immedok              <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*
451
456
              is_keypad               <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*
452
457
              is_leaveok              <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*
453
458
              is_linetouched          <STRONG><A HREF="curs_touch.3x.html">curs_touch(3x)</A></STRONG>
454
459
              is_nodelay              <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*
 
460
 
455
461
              is_notimeout            <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*
 
462
              is_pad                  <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*
456
463
              is_scrollok             <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*
 
464
              is_subwin               <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*
457
465
              is_syncok               <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*
458
466
              is_term_resized         <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG>*
459
467
              is_wintouched           <STRONG><A HREF="curs_touch.3x.html">curs_touch(3x)</A></STRONG>
512
520
              mvinsstr                <STRONG><A HREF="curs_insstr.3x.html">curs_insstr(3x)</A></STRONG>
513
521
              mvinstr                 <STRONG><A HREF="curs_instr.3x.html">curs_instr(3x)</A></STRONG>
514
522
              mvinwstr                <STRONG><A HREF="curs_inwstr.3x.html">curs_inwstr(3x)</A></STRONG>
515
 
 
516
523
              mvprintw                <STRONG><A HREF="curs_printw.3x.html">curs_printw(3x)</A></STRONG>
517
524
              mvscanw                 <STRONG><A HREF="curs_scanw.3x.html">curs_scanw(3x)</A></STRONG>
518
525
              mvvline                 <STRONG><A HREF="curs_border.3x.html">curs_border(3x)</A></STRONG>
519
526
              mvvline_set             <STRONG><A HREF="curs_border_set.3x.html">curs_border_set(3x)</A></STRONG>
 
527
 
520
528
              mvwadd_wch              <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>
521
529
              mvwadd_wchnstr          <STRONG><A HREF="curs_add_wchstr.3x.html">curs_add_wchstr(3x)</A></STRONG>
522
530
              mvwadd_wchstr           <STRONG><A HREF="curs_add_wchstr.3x.html">curs_add_wchstr(3x)</A></STRONG>
578
586
              pnoutrefresh            <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>
579
587
              prefresh                <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>
580
588
              printw                  <STRONG><A HREF="curs_printw.3x.html">curs_printw(3x)</A></STRONG>
581
 
 
582
589
              putp                    <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
583
590
              putwin                  <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>
584
591
              qiflush                 <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>
585
592
              raw                     <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>
586
593
              redrawwin               <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>
 
594
 
587
595
              refresh                 <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>
588
596
              reset_prog_mode         <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>
589
597
              reset_shell_mode        <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>
590
598
              resetty                 <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>
 
599
              resize_term             <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG>*
591
600
              resizeterm              <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG>*
592
601
              restartterm             <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
593
602
              ripoffline              <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>
640
649
              tigetflag               <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
641
650
              tigetnum                <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
642
651
              tigetstr                <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
 
652
              tiparm                  <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>*
643
653
              timeout                 <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>
644
654
              touchline               <STRONG><A HREF="curs_touch.3x.html">curs_touch(3x)</A></STRONG>
645
655
              touchwin                <STRONG><A HREF="curs_touch.3x.html">curs_touch(3x)</A></STRONG>
646
656
              tparm                   <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
647
 
 
648
657
              tputs                   <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>
649
658
              tputs                   <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
650
659
              trace                   <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG>*
651
660
              typeahead               <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>
 
661
 
652
662
              unctrl                  <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>
653
663
              unget_wch               <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG>
654
664
              ungetch                 <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>
708
718
              wget_wstr               <STRONG><A HREF="curs_get_wstr.3x.html">curs_get_wstr(3x)</A></STRONG>
709
719
              wgetbkgrnd              <STRONG><A HREF="curs_bkgrnd.3x.html">curs_bkgrnd(3x)</A></STRONG>
710
720
              wgetch                  <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>
 
721
              wgetdelay               <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*
711
722
              wgetn_wstr              <STRONG><A HREF="curs_get_wstr.3x.html">curs_get_wstr(3x)</A></STRONG>
712
723
              wgetnstr                <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG>
713
 
 
 
724
              wgetparent              <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*
 
725
              wgetscrreg              <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*
714
726
              wgetstr                 <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG>
715
727
              whline                  <STRONG><A HREF="curs_border.3x.html">curs_border(3x)</A></STRONG>
 
728
 
716
729
              whline_set              <STRONG><A HREF="curs_border_set.3x.html">curs_border_set(3x)</A></STRONG>
717
730
              win_wch                 <STRONG><A HREF="curs_in_wch.3x.html">curs_in_wch(3x)</A></STRONG>
718
731
              win_wchnstr             <STRONG><A HREF="curs_in_wchstr.3x.html">curs_in_wchstr(3x)</A></STRONG>
755
768
 
756
769
</PRE>
757
770
<H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
758
 
       Routines  that  return  an integer return <STRONG>ERR</STRONG> upon failure
759
 
       and an integer value other than <STRONG>ERR</STRONG> upon  successful  com-
760
 
       pletion,  unless  otherwise  noted in the routine descrip-
 
771
       Routines that return an integer return  <STRONG>ERR</STRONG>  upon  failure
 
772
       and  an  integer value other than <STRONG>ERR</STRONG> upon successful com-
 
773
       pletion, unless otherwise noted in  the  routine  descrip-
761
774
       tions.
762
775
 
763
776
       As a general rule, routines check for null pointers passed
764
777
       as parameters, and handle this as an error.
765
778
 
766
 
       All  macros  return  the  value  of  the <STRONG>w</STRONG> version, except
 
779
       All macros return the  value  of  the  <STRONG>w</STRONG>  version,  except
767
780
       <STRONG>setscrreg</STRONG>, <STRONG>wsetscrreg</STRONG>, <STRONG>getyx</STRONG>, <STRONG>getbegyx</STRONG>, and <STRONG>getmaxyx</STRONG>.  The
768
 
       return  values  of <STRONG>setscrreg</STRONG>, <STRONG>wsetscrreg</STRONG>, <STRONG>getyx</STRONG>, <STRONG>getbegyx</STRONG>,
 
781
       return values of <STRONG>setscrreg</STRONG>, <STRONG>wsetscrreg</STRONG>,  <STRONG>getyx</STRONG>,  <STRONG>getbegyx</STRONG>,
769
782
       and <STRONG>getmaxyx</STRONG> are undefined (i.e., these should not be used
770
783
       as the right-hand side of assignment statements).
771
784
 
778
791
       ing the runtime behavior of the <STRONG>ncurses</STRONG> library.  The most
779
792
       important ones have been already discussed in detail.
780
793
 
781
 
       CC   When set, change occurrences of the command_character
782
 
            (i.e., the <STRONG>cmdch</STRONG> capability) of the  loaded  terminfo
783
 
            entries to the value of this variable.  Very few ter-
784
 
            minfo entries provide this feature.
785
 
 
786
 
            Because this name is also used in  development  envi-
787
 
            ronments  to represent the C compiler's name, <STRONG>ncurses</STRONG>
788
 
            ignores it if it does not happen to be a single char-
789
 
            acter.
790
 
 
791
 
       BAUDRATE
792
 
            The  debugging  library checks this environment vari-
793
 
            able when the application has redirected output to  a
794
 
            file.   The  variable's numeric value is used for the
795
 
            baudrate.  If no value is found, <STRONG>ncurses</STRONG>  uses  9600.
796
 
            This  allows  testers  to  construct repeatable test-
797
 
            cases that take into account  costs  that  depend  on
798
 
            baudrate.
799
 
 
800
 
       COLUMNS
801
 
            Specify  the  width  of  the  screen  in  characters.
802
 
            Applications running in a windowing environment  usu-
803
 
            ally  are  able  to obtain the width of the window in
804
 
            which they are executing.   If  neither  the  <STRONG>COLUMNS</STRONG>
805
 
            value  nor  the  terminal's screen size is available,
806
 
            <STRONG>ncurses</STRONG> uses the size which may be specified  in  the
807
 
            terminfo database (i.e., the <STRONG>cols</STRONG> capability).
808
 
 
809
 
            It  is  important that your application use a correct
810
 
            size for the screen.  This  is  not  always  possible
811
 
            because  your  application  may  be running on a host
812
 
            which does not honor NAWS (Negotiations About  Window
813
 
            Size),  or  because  you  are  temporarily running as
814
 
            another user.  However, setting <STRONG>COLUMNS</STRONG> and/or  <STRONG>LINES</STRONG>
815
 
            overrides  the  library's  use  of  the  screen  size
816
 
            obtained from the operating system.
817
 
 
818
 
            Either <STRONG>COLUMNS</STRONG> or  <STRONG>LINES</STRONG>  symbols  may  be  specified
819
 
            independently.   This  is mainly useful to circumvent
820
 
            legacy misfeatures of  terminal  descriptions,  e.g.,
821
 
            xterm which commonly specifies a 65 line screen.  For
822
 
            best results, <STRONG>lines</STRONG> and <STRONG>cols</STRONG> should not be  specified
823
 
            in a terminal description for terminals which are run
824
 
            as emulations.
825
 
 
826
 
            Use the <STRONG>use_env</STRONG> function to disable all use of exter-
827
 
            nal  environment  (but not including system calls) to
828
 
            determine the screen size.  Use the <STRONG>use_tioctl</STRONG>  func-
829
 
            tion  to  update <STRONG>COLUMNS</STRONG> or <STRONG>LINES</STRONG> to match the screen
830
 
            size obtained from system calls or the terminal data-
831
 
            base.
832
 
 
833
 
       ESCDELAY
834
 
            Specifies  the total time, in milliseconds, for which
835
 
            ncurses will await  a  character  sequence,  e.g.,  a
836
 
            function  key.  The default value, 1000 milliseconds,
837
 
            is enough for most uses.  However, it is made a vari-
838
 
            able to accommodate unusual applications.
839
 
 
840
 
            The most common instance where you may wish to change
841
 
            this value is to work with slow hosts, e.g.,  running
842
 
            on  a  network.   If  the host cannot read characters
843
 
            rapidly enough, it will have the same  effect  as  if
844
 
            the  terminal did not send characters rapidly enough.
845
 
            The library will still see a timeout.
846
 
 
847
 
            Note that xterm mouse events are built up from  char-
848
 
            acter  sequences  received  from  the xterm.  If your
849
 
            application makes heavy use of multiple-clicking, you
850
 
            may  wish  to lengthen this default value because the
851
 
            timeout applies to the composed multi-click event  as
852
 
            well as the individual clicks.
853
 
 
854
 
            In  addition to the environment variable, this imple-
855
 
            mentation provides a global variable  with  the  same
856
 
            name.  Portable applications should not rely upon the
857
 
            presence of ESCDELAY in either form, but setting  the
858
 
            environment  variable rather than the global variable
859
 
            does not create problems when compiling  an  applica-
860
 
            tion.
861
 
 
862
 
       HOME Tells  <STRONG>ncurses</STRONG> where your home directory is.  That is
863
 
            where  it  may  read  and  write  auxiliary  terminal
864
 
            descriptions:
865
 
 
866
 
            $HOME/.termcap
867
 
            $HOME/.terminfo
868
 
 
869
 
       LINES
870
 
            Like  COLUMNS,  specify  the  height of the screen in
871
 
            characters.  See COLUMNS for a detailed description.
872
 
 
873
 
       MOUSE_BUTTONS_123
874
 
            This applies only to the OS/2 EMX port.  It specifies
875
 
            the  order  of  buttons on the mouse.  OS/2 numbers a
876
 
            3-button mouse inconsistently from other platforms:
877
 
 
878
 
            1 = left
879
 
            2 = right
880
 
            3 = middle.
881
 
 
882
 
            This variable lets  you  customize  the  mouse.   The
883
 
            variable  must  be  three  numeric  digits 1-3 in any
884
 
            order, e.g., 123 or 321.  If  it  is  not  specified,
885
 
            <STRONG>ncurses</STRONG> uses 132.
886
 
 
887
 
       NCURSES_ASSUMED_COLORS
888
 
            Override  the  compiled-in assumption that the termi-
889
 
            nal's  default   colors   are   white-on-black   (see
890
 
            <STRONG><A HREF="default_colors.3x.html">default_colors(3x)</A></STRONG>).   You may set the foreground and
891
 
            background color values with this  environment  vari-
892
 
            able  by  proving  a 2-element list: foreground,back-
893
 
            ground.  For example, to tell ncurses to  not  assume
894
 
            anything  about  the colors, set this to "-1,-1".  To
895
 
            make it green-on-black, set it to "2,0".   Any  posi-
896
 
            tive value from zero to the terminfo <STRONG>max_colors</STRONG> value
897
 
            is allowed.
898
 
 
899
 
       NCURSES_CONSOLE2
900
 
            This applies only to the MinGW port of ncurses.
901
 
 
902
 
            The <STRONG>Console2</STRONG> program's handling of the Microsoft Con-
903
 
            sole API call <STRONG>CreateConsoleScreenBuffer</STRONG> is defective.
904
 
            Applications which use this will hang.   However,  it
905
 
            is  possible  to  simulate the action of this call by
906
 
            mapping coordinates, explicitly saving and  restoring
907
 
            the  original  screen contents.  Setting the environ-
908
 
            ment variable <STRONG>NCGDB</STRONG> has the same effect.
909
 
 
910
 
       NCURSES_GPM_TERMS
911
 
            This applies only to ncurses configured  to  use  the
912
 
            GPM interface.
913
 
 
914
 
            If present, the environment variable is a list of one
915
 
            or more terminal names against which the  TERM  envi-
916
 
            ronment  variable is matched.  Setting it to an empty
917
 
            value disables the GPM interface; using the  built-in
918
 
            support for xterm, etc.
919
 
 
920
 
            If  the  environment variable is absent, ncurses will
921
 
            attempt to open GPM if TERM contains "linux".
922
 
 
923
 
       NCURSES_NO_HARD_TABS
924
 
            <STRONG>Ncurses</STRONG> may use tabs as part of the  cursor  movement
925
 
            optimization.   In  some  cases, your terminal driver
926
 
            may not handle these properly.  Set this  environment
927
 
            variable to disable the feature.  You can also adjust
928
 
            your <STRONG>stty</STRONG> settings to avoid the problem.
929
 
 
930
 
       NCURSES_NO_MAGIC_COOKIE
931
 
            Some  terminals  use  a  magic-cookie  feature  which
932
 
            requires  special  handling  to make highlighting and
933
 
            other video attributes  display  properly.   You  can
934
 
            suppress  the  highlighting entirely for these termi-
935
 
            nals by setting this environment variable.
936
 
 
937
 
       NCURSES_NO_PADDING
938
 
            Most of the terminal  descriptions  in  the  terminfo
939
 
            database  are  written for real "hardware" terminals.
940
 
            Many people use terminal emulators  which  run  in  a
941
 
            windowing  environment  and use curses-based applica-
942
 
            tions.  Terminal emulators can duplicate all  of  the
943
 
            important aspects of a hardware terminal, but they do
944
 
            not have the same limitations.  The chief  limitation
945
 
            of  a  hardware  terminal from the standpoint of your
946
 
            application is the management of dataflow, i.e., tim-
947
 
            ing.  Unless a hardware terminal is interfaced into a
948
 
            terminal concentrator (which does flow  control),  it
949
 
            (or  your application) must manage dataflow, prevent-
950
 
            ing overruns.  The  cheapest  solution  (no  hardware
951
 
            cost) is for your program to do this by pausing after
952
 
            operations that the terminal  does  slowly,  such  as
953
 
            clearing the display.
954
 
 
955
 
            As  a  result,  many terminal descriptions (including
956
 
            the vt100) have delay times embedded.  You  may  wish
957
 
            to  use  these  descriptions, but not want to pay the
958
 
            performance penalty.
959
 
 
960
 
            Set the NCURSES_NO_PADDING  environment  variable  to
961
 
            disable all but mandatory padding.  Mandatory padding
962
 
            is used as a part of special control  sequences  such
963
 
            as <EM>flash</EM>.
964
 
 
965
 
       NCURSES_NO_SETBUF
966
 
            This setting is obsolete.  Before changes
967
 
 
968
 
            <STRONG>o</STRONG>   started with 5.9 patch 20120825 and
969
 
 
970
 
            <STRONG>o</STRONG>   continued though 5.9 patch 20130126
971
 
 
972
 
            <STRONG>ncurses</STRONG>  enabled buffered output during terminal ini-
973
 
            tialization.  This was done (as in SVr4  curses)  for
974
 
            performance  reasons.   For testing purposes, both of
975
 
            <STRONG>ncurses</STRONG> and certain applications,  this  feature  was
976
 
            made  optional.   Setting the NCURSES_NO_SETBUF vari-
977
 
            able disabled output buffering, leaving the output in
978
 
            the original (usually line buffered) mode.
979
 
 
980
 
            In  the  current implementation, ncurses performs its
981
 
            own buffering and does not require  this  workaround.
982
 
            It does not modify the buffering of the standard out-
983
 
            put.
984
 
 
985
 
            The reason for the change was to  make  the  behavior
986
 
            for  interrupts  and  other signals more robust.  One
987
 
            drawback is  that  certain  nonconventional  programs
988
 
            would mix ordinary stdio calls with ncurses calls and
989
 
            (usually) work.  This is  no  longer  possible  since
990
 
            ncurses is not using the buffered standard output but
991
 
            its own output (to the same file descriptor).   As  a
992
 
            special  case, the low-level calls such as <STRONG>putp</STRONG> still
993
 
            use the standard output.  But high-level curses calls
994
 
            do not.
995
 
 
996
 
       NCURSES_NO_UTF8_ACS
997
 
            During initialization, the <STRONG>ncurses</STRONG> library checks for
998
 
            special cases where VT100 line-drawing (and the  cor-
999
 
            responding   alternate  character  set  capabilities)
1000
 
            described in the terminfo are known  to  be  missing.
1001
 
            Specifically,  when  running  in  a UTF-8 locale, the
1002
 
            Linux console emulator and  the  GNU  screen  program
1003
 
            ignore  these.   Ncurses  checks the TERM environment
1004
 
            variable for these.  For  other  special  cases,  you
1005
 
            should  set  this  environment  variable.  Doing this
1006
 
            tells ncurses to use Unicode values which  correspond
1007
 
            to the VT100 line-drawing glyphs.  That works for the
1008
 
            special cases cited, and is likely to work for termi-
1009
 
            nal emulators.
1010
 
 
1011
 
            When  setting  this  variable, you should set it to a
1012
 
            nonzero value.  Setting it to zero (or to  a  nonnum-
1013
 
            ber)  disables  the  special  check  for  "linux" and
1014
 
            "screen".
1015
 
 
1016
 
            As  an  alternative  to  the  environment   variable,
1017
 
            ncurses  checks  for  an extended terminfo capability
1018
 
            <STRONG>U8</STRONG>.  This is a numeric capability which can  be  com-
1019
 
            piled using <STRONG>tic</STRONG> <STRONG>-x</STRONG>.  For example
1020
 
 
1021
 
            # linux console, if patched to provide working
1022
 
            # VT100 shift-in/shift-out, with corresponding font.
1023
 
            linux-vt100|linux console with VT100 line-graphics,
1024
 
                    U8#0, use=linux,
1025
 
 
1026
 
            # uxterm with vt100Graphics resource set to false
1027
 
            xterm-utf8|xterm relying on UTF-8 line-graphics,
1028
 
                    U8#1, use=xterm,
1029
 
 
1030
 
            The name "U8" is chosen to be two characters, to per-
1031
 
            mit it to be used by applications that  use  ncurses'
1032
 
            termcap interface.
1033
 
 
1034
 
       NCURSES_TRACE
1035
 
            During  initialization, the <STRONG>ncurses</STRONG> debugging library
1036
 
            checks the NCURSES_TRACE environment variable.  If it
1037
 
            is  defined,  to  a  numeric value, <STRONG>ncurses</STRONG> calls the
1038
 
            <STRONG>trace</STRONG> function, using that value as the argument.
1039
 
 
1040
 
            The argument values, which are defined  in  <STRONG>curses.h</STRONG>,
1041
 
            provide  several  types of information.  When running
1042
 
            with traces enabled, your application will write  the
1043
 
            file <STRONG>trace</STRONG> to the current directory.
1044
 
 
1045
 
       TERM Denotes  your  terminal  type.  Each terminal type is
1046
 
            distinct, though many are similar.
1047
 
 
1048
 
            <STRONG>TERM</STRONG> is commonly set by terminal  emulators  to  help
1049
 
            applications  find  a  workable terminal description.
1050
 
            Some of those choose a popular  approximation,  e.g.,
1051
 
            "ansi",  "vt100",  "xterm"  rather than an exact fit.
1052
 
            Not infrequently, your application will have problems
1053
 
            with that approach, e.g., incorrect function-key def-
1054
 
            initions.
1055
 
 
1056
 
            If you set <STRONG>TERM</STRONG> in your environment, it has no effect
1057
 
            on  the  operation of the terminal emulator.  It only
1058
 
            affects the way applications work within  the  termi-
1059
 
            nal.  Likewise, as a general rule (<STRONG>xterm</STRONG> being a rare
1060
 
            exception), terminal emulators  which  allow  you  to
1061
 
            specify <STRONG>TERM</STRONG> as a parameter or configuration value do
1062
 
            not change their behavior to match that setting.
1063
 
 
1064
 
       TERMCAP
1065
 
            If the <STRONG>ncurses</STRONG> library has been configured with <EM>term-</EM>
1066
 
            <EM>cap</EM>  support,  <STRONG>ncurses</STRONG>  will  check  for a terminal's
1067
 
            description in termcap form if it is not available in
1068
 
            the terminfo database.
1069
 
 
1070
 
            The  TERMCAP  environment  variable contains either a
1071
 
            terminal description (with newlines stripped out), or
1072
 
            a  file name telling where the information denoted by
1073
 
            the TERM  environment  variable  exists.   In  either
1074
 
            case,  setting it directs <STRONG>ncurses</STRONG> to ignore the usual
1075
 
            place for this information, e.g., /etc/termcap.
1076
 
 
1077
 
       TERMINFO
1078
 
            Overrides the directory in which <STRONG>ncurses</STRONG> searches for
1079
 
            your terminal description.  This is the simplest, but
1080
 
            not the only way to change the list  of  directories.
1081
 
            The complete list of directories in order follows:
1082
 
 
1083
 
            <STRONG>o</STRONG>   the  last  directory  to  which <STRONG>ncurses</STRONG> wrote, if
1084
 
                any, is searched first
1085
 
 
1086
 
            <STRONG>o</STRONG>   the directory specified by the TERMINFO  environ-
1087
 
                ment variable
1088
 
 
1089
 
            <STRONG>o</STRONG>   $HOME/.terminfo
1090
 
 
1091
 
            <STRONG>o</STRONG>   directories  listed in the TERMINFO_DIRS environ-
1092
 
                ment variable
1093
 
 
1094
 
            <STRONG>o</STRONG>   one or more directories whose names  are  config-
1095
 
                ured and compiled into the ncurses library, i.e.,
1096
 
 
1097
 
                <STRONG>o</STRONG>   /usr/local/ncurses/share/ter-
1098
 
                    minfo:/usr/share/terminfo  (corresponding  to
1099
 
                    the TERMINFO_DIRS variable)
1100
 
 
1101
 
                <STRONG>o</STRONG>   /usr/share/terminfo   (corresponding  to  the
1102
 
                    TERMINFO variable)
1103
 
 
1104
 
       TERMINFO_DIRS
1105
 
            Specifies a list of directories to search for  termi-
1106
 
            nal  descriptions.   The  list is separated by colons
1107
 
            (i.e., ":") on Unix, semicolons on OS/2 EMX.
1108
 
 
1109
 
            All of the  terminal  descriptions  are  in  terminfo
1110
 
            form.  Normally these are stored in a directory tree,
1111
 
            using subdirectories named by the first letter of the
1112
 
            terminal names therein.
1113
 
 
1114
 
            If <STRONG>ncurses</STRONG> is built with a hashed database, then each
1115
 
            entry in this list can also be the path of the corre-
1116
 
            sponding database file.
1117
 
 
1118
 
            If  <STRONG>ncurses</STRONG> is built with a support for reading term-
1119
 
            cap files directly, then an entry in this list may be
1120
 
            the path of a termcap file.
1121
 
 
1122
 
       TERMPATH
1123
 
            If  TERMCAP  does  not  hold a file name then <STRONG>ncurses</STRONG>
1124
 
            checks the TERMPATH environment variable.  This is  a
1125
 
            list  of  filenames  separated  by  spaces  or colons
1126
 
            (i.e., ":") on Unix, semicolons on OS/2 EMX.
1127
 
 
1128
 
            If the TERMPATH  environment  variable  is  not  set,
1129
 
            <STRONG>ncurses</STRONG>    looks    in    the   files   /etc/termcap,
1130
 
            /usr/share/misc/termcap and $HOME/.termcap,  in  that
1131
 
            order.
 
794
   <STRONG>CC</STRONG>
 
795
       When set,  change  occurrences  of  the  command_character
 
796
       (i.e.,  the  <STRONG>cmdch</STRONG>  capability)  of  the  loaded  terminfo
 
797
       entries to the value of this variable.  Very few  terminfo
 
798
       entries provide this feature.
 
799
 
 
800
       Because this name is also used in development environments
 
801
       to represent the C compiler's name, <STRONG>ncurses</STRONG> ignores it  if
 
802
       it does not happen to be a single character.
 
803
 
 
804
 
 
805
</PRE>
 
806
<H3><a name="h3-BAUDRATE">BAUDRATE</a></H3><PRE>
 
807
       The  debugging  library  checks  this environment variable
 
808
       when the application has redirected output to a file.  The
 
809
       variable's  numeric value is used for the baudrate.  If no
 
810
       value is found, <STRONG>ncurses</STRONG> uses 9600.  This allows testers to
 
811
       construct  repeatable  test-cases  that  take into account
 
812
       costs that depend on baudrate.
 
813
 
 
814
 
 
815
</PRE>
 
816
<H3><a name="h3-COLUMNS">COLUMNS</a></H3><PRE>
 
817
       Specify the width of the screen in  characters.   Applica-
 
818
       tions  running in a windowing environment usually are able
 
819
       to obtain the width of the window in which they  are  exe-
 
820
       cuting.   If  neither the <STRONG>COLUMNS</STRONG> value nor the terminal's
 
821
       screen size is available, <STRONG>ncurses</STRONG> uses the size which  may
 
822
       be  specified  in  the  terminfo  database (i.e., the <STRONG>cols</STRONG>
 
823
       capability).
 
824
 
 
825
       It is important that your application use a  correct  size
 
826
       for  the screen.  This is not always possible because your
 
827
       application may be running on a host which does not  honor
 
828
       NAWS  (Negotiations About Window Size), or because you are
 
829
       temporarily running as  another  user.   However,  setting
 
830
       <STRONG>COLUMNS</STRONG>  and/or  <STRONG>LINES</STRONG>  overrides the library's use of the
 
831
       screen size obtained from the operating system.
 
832
 
 
833
       Either <STRONG>COLUMNS</STRONG> or <STRONG>LINES</STRONG> symbols may be specified  indepen-
 
834
       dently.   This  is mainly useful to circumvent legacy mis-
 
835
       features of terminal descriptions, e.g., xterm which  com-
 
836
       monly specifies a 65 line screen.  For best results, <STRONG>lines</STRONG>
 
837
       and <STRONG>cols</STRONG> should not be specified in a terminal description
 
838
       for terminals which are run as emulations.
 
839
 
 
840
       Use  the  <STRONG>use_env</STRONG>  function to disable all use of external
 
841
       environment (but not including system calls) to  determine
 
842
       the  screen  size.   Use the <STRONG>use_tioctl</STRONG> function to update
 
843
       <STRONG>COLUMNS</STRONG> or <STRONG>LINES</STRONG> to match the screen  size  obtained  from
 
844
       system calls or the terminal database.
 
845
 
 
846
 
 
847
</PRE>
 
848
<H3><a name="h3-ESCDELAY">ESCDELAY</a></H3><PRE>
 
849
       Specifies  the  total  time,  in  milliseconds,  for which
 
850
       ncurses will await a character sequence, e.g., a  function
 
851
       key.   The default value, 1000 milliseconds, is enough for
 
852
       most uses.  However, it is made a variable to  accommodate
 
853
       unusual applications.
 
854
 
 
855
       The most common instance where you may wish to change this
 
856
       value is to work with slow hosts, e.g., running on a  net-
 
857
       work.   If the host cannot read characters rapidly enough,
 
858
       it will have the same effect as if the  terminal  did  not
 
859
       send  characters  rapidly  enough.  The library will still
 
860
       see a timeout.
 
861
 
 
862
       Note that xterm mouse events are built up  from  character
 
863
       sequences  received  from  the xterm.  If your application
 
864
       makes heavy use of  multiple-clicking,  you  may  wish  to
 
865
       lengthen this default value because the timeout applies to
 
866
       the composed multi-click event as well as  the  individual
 
867
       clicks.
 
868
 
 
869
       In  addition to the environment variable, this implementa-
 
870
       tion provides a global variable with the same name.   Por-
 
871
       table  applications  should  not rely upon the presence of
 
872
       ESCDELAY in either form, but setting the environment vari-
 
873
       able rather than the global variable does not create prob-
 
874
       lems when compiling an application.
 
875
 
 
876
 
 
877
</PRE>
 
878
<H3><a name="h3-HOME">HOME</a></H3><PRE>
 
879
       Tells <STRONG>ncurses</STRONG> where your home directory is.  That is where
 
880
       it may read and write auxiliary terminal descriptions:
 
881
 
 
882
       $HOME/.termcap
 
883
       $HOME/.terminfo
 
884
 
 
885
 
 
886
</PRE>
 
887
<H3><a name="h3-LINES">LINES</a></H3><PRE>
 
888
       Like  COLUMNS, specify the height of the screen in charac-
 
889
       ters.  See COLUMNS for a detailed description.
 
890
 
 
891
 
 
892
</PRE>
 
893
<H3><a name="h3-MOUSE_BUTTONS_123">MOUSE_BUTTONS_123</a></H3><PRE>
 
894
       This applies only to the OS/2 EMX port.  It specifies  the
 
895
       order  of  buttons  on the mouse.  OS/2 numbers a 3-button
 
896
       mouse inconsistently from other platforms:
 
897
 
 
898
       1 = left
 
899
       2 = right
 
900
       3 = middle.
 
901
 
 
902
       This variable lets you customize the mouse.  The  variable
 
903
       must  be  three numeric digits 1-3 in any order, e.g., 123
 
904
       or 321.  If it is not specified, <STRONG>ncurses</STRONG> uses 132.
 
905
 
 
906
 
 
907
</PRE>
 
908
<H3><a name="h3-NCURSES_ASSUMED_COLORS">NCURSES_ASSUMED_COLORS</a></H3><PRE>
 
909
       Override the compiled-in assumption  that  the  terminal's
 
910
       default   colors   are  white-on-black  (see  <STRONG>default_col-</STRONG>
 
911
       <STRONG><A HREF="default_colors.3x.html">ors(3x)</A></STRONG>).  You may set the foreground and background color
 
912
       values  with this environment variable by proving a 2-ele-
 
913
       ment list: foreground,background.  For  example,  to  tell
 
914
       ncurses  to not assume anything about the colors, set this
 
915
       to "-1,-1".  To make it green-on-black, set it  to  "2,0".
 
916
       Any  positive  value  from zero to the terminfo <STRONG>max_colors</STRONG>
 
917
       value is allowed.
 
918
 
 
919
 
 
920
</PRE>
 
921
<H3><a name="h3-NCURSES_CONSOLE2">NCURSES_CONSOLE2</a></H3><PRE>
 
922
       This applies only to the MinGW port of ncurses.
 
923
 
 
924
       The <STRONG>Console2</STRONG> program's handling of the  Microsoft  Console
 
925
       API call <STRONG>CreateConsoleScreenBuffer</STRONG> is defective.  Applica-
 
926
       tions which use this will hang.  However, it  is  possible
 
927
       to  simulate  the  action  of this call by mapping coordi-
 
928
       nates, explicitly saving and restoring the original screen
 
929
       contents.   Setting the environment variable <STRONG>NCGDB</STRONG> has the
 
930
       same effect.
 
931
 
 
932
 
 
933
</PRE>
 
934
<H3><a name="h3-NCURSES_GPM_TERMS">NCURSES_GPM_TERMS</a></H3><PRE>
 
935
       This applies only to ncurses configured  to  use  the  GPM
 
936
       interface.
 
937
 
 
938
       If  present,  the environment variable is a list of one or
 
939
       more terminal names against  which  the  TERM  environment
 
940
       variable  is  matched.   Setting it to an empty value dis-
 
941
       ables the GPM interface; using the  built-in  support  for
 
942
       xterm, etc.
 
943
 
 
944
       If  the  environment  variable  is  absent,  ncurses  will
 
945
       attempt to open GPM if TERM contains "linux".
 
946
 
 
947
 
 
948
</PRE>
 
949
<H3><a name="h3-NCURSES_NO_HARD_TABS">NCURSES_NO_HARD_TABS</a></H3><PRE>
 
950
       <STRONG>Ncurses</STRONG> may use tabs as part of the cursor movement  opti-
 
951
       mization.   In  some  cases,  your terminal driver may not
 
952
       handle these properly.  Set this environment  variable  to
 
953
       disable  the  feature.  You can also adjust your <STRONG>stty</STRONG> set-
 
954
       tings to avoid the problem.  NCURSES_NO_MAGIC_COOKIE  Some
 
955
       terminals  use  a magic-cookie feature which requires spe-
 
956
       cial  handling  to  make  highlighting  and  other   video
 
957
       attributes  display  properly.  You can suppress the high-
 
958
       lighting entirely for  these  terminals  by  setting  this
 
959
       environment variable.
 
960
 
 
961
 
 
962
</PRE>
 
963
<H3><a name="h3-NCURSES_NO_PADDING">NCURSES_NO_PADDING</a></H3><PRE>
 
964
       Most of the terminal descriptions in the terminfo database
 
965
       are written for real "hardware"  terminals.   Many  people
 
966
       use  terminal  emulators which run in a windowing environ-
 
967
       ment and use curses-based applications.   Terminal  emula-
 
968
       tors can duplicate all of the important aspects of a hard-
 
969
       ware terminal, but they do not have the same  limitations.
 
970
       The  chief  limitation  of  a  hardware  terminal from the
 
971
       standpoint  of  your  application  is  the  management  of
 
972
       dataflow,  i.e.,  timing.   Unless  a hardware terminal is
 
973
       interfaced into a terminal concentrator (which  does  flow
 
974
       control),  it  (or your application) must manage dataflow,
 
975
       preventing overruns.  The cheapest solution  (no  hardware
 
976
       cost)  is  for  your  program  to do this by pausing after
 
977
       operations that the terminal does slowly, such as clearing
 
978
       the display.
 
979
 
 
980
       As  a  result,  many  terminal descriptions (including the
 
981
       vt100) have delay times embedded.  You  may  wish  to  use
 
982
       these  descriptions,  but  not want to pay the performance
 
983
       penalty.
 
984
 
 
985
       Set the NCURSES_NO_PADDING environment variable to disable
 
986
       all but mandatory padding.  Mandatory padding is used as a
 
987
       part of special control sequences such as <EM>flash</EM>.
 
988
 
 
989
 
 
990
</PRE>
 
991
<H3><a name="h3-NCURSES_NO_SETBUF">NCURSES_NO_SETBUF</a></H3><PRE>
 
992
       This setting is obsolete.  Before changes
 
993
 
 
994
          <STRONG>o</STRONG>   started with 5.9 patch 20120825 and
 
995
 
 
996
          <STRONG>o</STRONG>   continued though 5.9 patch 20130126
 
997
 
 
998
       <STRONG>ncurses</STRONG> enabled buffered output during  terminal  initial-
 
999
       ization.   This  was  done (as in SVr4 curses) for perfor-
 
1000
       mance reasons.  For testing purposes, both of <STRONG>ncurses</STRONG>  and
 
1001
       certain  applications,  this  feature  was  made optional.
 
1002
       Setting the  NCURSES_NO_SETBUF  variable  disabled  output
 
1003
       buffering,  leaving  the  output  in the original (usually
 
1004
       line buffered) mode.
 
1005
 
 
1006
       In the current implementation, ncurses  performs  its  own
 
1007
       buffering  and  does not require this workaround.  It does
 
1008
       not modify the buffering of the standard output.
 
1009
 
 
1010
       The reason for the change was to  make  the  behavior  for
 
1011
       interrupts and other signals more robust.  One drawback is
 
1012
       that certain nonconventional programs would  mix  ordinary
 
1013
       stdio  calls  with ncurses calls and (usually) work.  This
 
1014
       is no longer possible  since  ncurses  is  not  using  the
 
1015
       buffered  standard  output but its own output (to the same
 
1016
       file descriptor).  As a special case, the low-level  calls
 
1017
       such  as  <STRONG>putp</STRONG>  still  use the standard output.  But high-
 
1018
       level curses calls do not.
 
1019
 
 
1020
 
 
1021
</PRE>
 
1022
<H3><a name="h3-NCURSES_NO_UTF8_ACS">NCURSES_NO_UTF8_ACS</a></H3><PRE>
 
1023
       During initialization, the <STRONG>ncurses</STRONG> library checks for spe-
 
1024
       cial cases where VT100 line-drawing (and the corresponding
 
1025
       alternate character set  capabilities)  described  in  the
 
1026
       terminfo are known to be missing.  Specifically, when run-
 
1027
       ning in a UTF-8 locale, the Linux console emulator and the
 
1028
       GNU  screen program ignore these.  Ncurses checks the TERM
 
1029
       environment variable for these.  For other special  cases,
 
1030
       you  should  set  this  environment  variable.  Doing this
 
1031
       tells ncurses to use Unicode values  which  correspond  to
 
1032
       the VT100 line-drawing glyphs.  That works for the special
 
1033
       cases cited, and is likely to work for terminal emulators.
 
1034
 
 
1035
       When setting this variable, you should set it to a nonzero
 
1036
       value.   Setting  it  to zero (or to a nonnumber) disables
 
1037
       the special check for "linux" and "screen".
 
1038
 
 
1039
       As an alternative to  the  environment  variable,  ncurses
 
1040
       checks  for an extended terminfo capability <STRONG>U8</STRONG>.  This is a
 
1041
       numeric capability which can  be  compiled  using  <STRONG>tic</STRONG> <STRONG>-x</STRONG>.
 
1042
       For example
 
1043
 
 
1044
          # linux console, if patched to provide working
 
1045
          # VT100 shift-in/shift-out, with corresponding font.
 
1046
          linux-vt100|linux console with VT100 line-graphics,
 
1047
                  U8#0, use=linux,
 
1048
 
 
1049
          # uxterm with vt100Graphics resource set to false
 
1050
          xterm-utf8|xterm relying on UTF-8 line-graphics,
 
1051
                  U8#1, use=xterm,
 
1052
 
 
1053
       The name "U8" is chosen to be two characters, to permit it
 
1054
       to be used  by  applications  that  use  ncurses'  termcap
 
1055
       interface.
 
1056
 
 
1057
 
 
1058
</PRE>
 
1059
<H3><a name="h3-NCURSES_TRACE">NCURSES_TRACE</a></H3><PRE>
 
1060
       During   initialization,  the  <STRONG>ncurses</STRONG>  debugging  library
 
1061
       checks the NCURSES_TRACE environment variable.  If  it  is
 
1062
       defined, to a numeric value, <STRONG>ncurses</STRONG> calls the <STRONG>trace</STRONG> func-
 
1063
       tion, using that value as the argument.
 
1064
 
 
1065
       The argument values, which are defined in  <STRONG>curses.h</STRONG>,  pro-
 
1066
       vide  several  types  of  information.   When running with
 
1067
       traces enabled, your application will write the file <STRONG>trace</STRONG>
 
1068
       to the current directory.
 
1069
 
 
1070
       See <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG> for more information.
 
1071
 
 
1072
 
 
1073
</PRE>
 
1074
<H3><a name="h3-TERM">TERM</a></H3><PRE>
 
1075
       Denotes  your  terminal  type.  Each terminal type is dis-
 
1076
       tinct, though many are similar.
 
1077
 
 
1078
       <STRONG>TERM</STRONG> is commonly set by terminal emulators to help  appli-
 
1079
       cations  find  a  workable  terminal description.  Some of
 
1080
       those  choose  a  popular  approximation,  e.g.,   "ansi",
 
1081
       "vt100",  "xterm"  rather  than  an exact fit.  Not infre-
 
1082
       quently, your application will  have  problems  with  that
 
1083
       approach, e.g., incorrect function-key definitions.
 
1084
 
 
1085
       If  you  set <STRONG>TERM</STRONG> in your environment, it has no effect on
 
1086
       the operation of the terminal emulator.  It  only  affects
 
1087
       the  way applications work within the terminal.  Likewise,
 
1088
       as a general rule (<STRONG>xterm</STRONG> being a rare exception), terminal
 
1089
       emulators  which  allow you to specify <STRONG>TERM</STRONG> as a parameter
 
1090
       or configuration value do not  change  their  behavior  to
 
1091
       match that setting.
 
1092
 
 
1093
 
 
1094
</PRE>
 
1095
<H3><a name="h3-TERMCAP">TERMCAP</a></H3><PRE>
 
1096
       If  the  <STRONG>ncurses</STRONG>  library has been configured with <EM>termcap</EM>
 
1097
       support, <STRONG>ncurses</STRONG> will check for a  terminal's  description
 
1098
       in  termcap  form  if  it is not available in the terminfo
 
1099
       database.
 
1100
 
 
1101
       The TERMCAP environment variable contains either a  termi-
 
1102
       nal  description  (with  newlines stripped out), or a file
 
1103
       name telling where the information  denoted  by  the  TERM
 
1104
       environment  variable  exists.  In either case, setting it
 
1105
       directs <STRONG>ncurses</STRONG> to ignore the usual place for this  infor-
 
1106
       mation, e.g., /etc/termcap.
 
1107
 
 
1108
 
 
1109
</PRE>
 
1110
<H3><a name="h3-TERMINFO">TERMINFO</a></H3><PRE>
 
1111
       Overrides the directory in which <STRONG>ncurses</STRONG> searches for your
 
1112
       terminal description.  This is the simplest, but  not  the
 
1113
       only  way to change the list of directories.  The complete
 
1114
       list of directories in order follows:
 
1115
 
 
1116
          <STRONG>o</STRONG>   the last directory to which <STRONG>ncurses</STRONG> wrote, if  any,
 
1117
              is searched first
 
1118
 
 
1119
          <STRONG>o</STRONG>   the directory specified by the TERMINFO environment
 
1120
              variable
 
1121
 
 
1122
          <STRONG>o</STRONG>   $HOME/.terminfo
 
1123
 
 
1124
          <STRONG>o</STRONG>   directories listed in the TERMINFO_DIRS environment
 
1125
              variable
 
1126
 
 
1127
          <STRONG>o</STRONG>   one  or more directories whose names are configured
 
1128
              and compiled into the ncurses library, i.e.,
 
1129
 
 
1130
             <STRONG>o</STRONG>   /usr/local/ncurses/share/ter-
 
1131
                 minfo:/usr/share/terminfo  (corresponding to the
 
1132
                 TERMINFO_DIRS variable)
 
1133
 
 
1134
             <STRONG>o</STRONG>   /usr/share/terminfo (corresponding to  the  TER-
 
1135
                 MINFO variable)
 
1136
 
 
1137
 
 
1138
</PRE>
 
1139
<H3><a name="h3-TERMINFO_DIRS">TERMINFO_DIRS</a></H3><PRE>
 
1140
       Specifies  a  list  of  directories to search for terminal
 
1141
       descriptions.  The list is separated by colons (i.e., ":")
 
1142
       on Unix, semicolons on OS/2 EMX.
 
1143
 
 
1144
       All  of  the  terminal  descriptions are in terminfo form.
 
1145
       Normally these are stored in a directory tree, using  sub-
 
1146
       directories  named  by  the  first  letter of the terminal
 
1147
       names therein.
 
1148
 
 
1149
       If <STRONG>ncurses</STRONG> is built with  a  hashed  database,  then  each
 
1150
       entry in this list can also be the path of the correspond-
 
1151
       ing database file.
 
1152
 
 
1153
       If <STRONG>ncurses</STRONG> is built with a  support  for  reading  termcap
 
1154
       files directly, then an entry in this list may be the path
 
1155
       of a termcap file.
 
1156
 
 
1157
 
 
1158
</PRE>
 
1159
<H3><a name="h3-TERMPATH">TERMPATH</a></H3><PRE>
 
1160
       If TERMCAP does not hold a file name then  <STRONG>ncurses</STRONG>  checks
 
1161
       the  TERMPATH  environment  variable.   This  is a list of
 
1162
       filenames separated by spaces or  colons  (i.e.,  ":")  on
 
1163
       Unix, semicolons on OS/2 EMX.
 
1164
 
 
1165
       If  the  TERMPATH environment variable is not set, <STRONG>ncurses</STRONG>
 
1166
       looks in the files  /etc/termcap,  /usr/share/misc/termcap
 
1167
       and $HOME/.termcap, in that order.
1132
1168
 
1133
1169
       The  library  may be configured to disregard the following
1134
1170
       variables when the current user is the  superuser  (root),
1135
1171
       or if the application uses setuid or setgid permissions:
1136
1172
 
1137
 
              $TERMINFO,  $TERMINFO_DIRS,  $TERMPATH,  as well as
1138
 
              $HOME.
 
1173
       $TERMINFO, $TERMINFO_DIRS, $TERMPATH, as well as $HOME.
1139
1174
 
1140
1175
 
1141
1176
</PRE>
1142
1177
<H2><a name="h2-ALTERNATE-CONFIGURATIONS">ALTERNATE CONFIGURATIONS</a></H2><PRE>
1143
 
       Several different configurations are  possible,  depending
1144
 
       on   the  configure  script  options  used  when  building
1145
 
       <STRONG>ncurses</STRONG>.  There are a few main options whose  effects  are
 
1178
       Several  different  configurations are possible, depending
 
1179
       on  the  configure  script  options  used  when   building
 
1180
       <STRONG>ncurses</STRONG>.   There  are a few main options whose effects are
1146
1181
       visible to the applications developer using <STRONG>ncurses</STRONG>:
1147
1182
 
1148
1183
       --disable-overwrite
1149
 
            The  standard include for <STRONG>ncurses</STRONG> is as noted in <STRONG>SYN-</STRONG>
 
1184
            The standard include for <STRONG>ncurses</STRONG> is as noted in  <STRONG>SYN-</STRONG>
1150
1185
            <STRONG>OPSIS</STRONG>:
1151
1186
 
1152
 
            <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
 
1187
          <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
1153
1188
 
1154
 
            This option is used to avoid filename conflicts  when
1155
 
            <STRONG>ncurses</STRONG>  is  not the main implementation of curses of
1156
 
            the computer.   If  <STRONG>ncurses</STRONG>  is  installed  disabling
1157
 
            overwrite,  it  puts  its  headers in a subdirectory,
 
1189
            This  option is used to avoid filename conflicts when
 
1190
            <STRONG>ncurses</STRONG> is not the main implementation of  curses  of
 
1191
            the  computer.   If  <STRONG>ncurses</STRONG>  is  installed disabling
 
1192
            overwrite, it puts its  headers  in  a  subdirectory,
1158
1193
            e.g.,
1159
1194
 
1160
 
            <STRONG>#include</STRONG> <STRONG>&lt;ncurses/curses.h&gt;</STRONG>
 
1195
          <STRONG>#include</STRONG> <STRONG>&lt;ncurses/curses.h&gt;</STRONG>
1161
1196
 
1162
 
            It also omits a symbolic link which would  allow  you
 
1197
            It  also  omits a symbolic link which would allow you
1163
1198
            to use <STRONG>-lcurses</STRONG> to build executables.
1164
1199
 
1165
1200
       --enable-widec
1166
 
            The  configure script renames the library and (if the
1167
 
            <STRONG>--disable-overwrite</STRONG> option is used) puts  the  header
 
1201
            The configure script renames the library and (if  the
 
1202
            <STRONG>--disable-overwrite</STRONG>  option  is used) puts the header
1168
1203
            files  in  a  different  subdirectory.   All  of  the
1169
 
            library names have a  "w"  appended  to  them,  i.e.,
 
1204
            library  names  have  a  "w"  appended to them, i.e.,
1170
1205
            instead of
1171
1206
 
1172
 
            <STRONG>-lncurses</STRONG>
 
1207
          <STRONG>-lncurses</STRONG>
1173
1208
 
1174
1209
            you link with
1175
1210
 
1176
 
            <STRONG>-lncursesw</STRONG>
 
1211
          <STRONG>-lncursesw</STRONG>
1177
1212
 
1178
1213
            You must also define <STRONG>_XOPEN_SOURCE_EXTENDED</STRONG> when com-
1179
 
            piling for the  wide-character  library  to  use  the
1180
 
            extended  (wide-character)  functions.   The <STRONG>curses.h</STRONG>
1181
 
            file  which  is  installed  for  the   wide-character
1182
 
            library  is designed to be compatible with the normal
 
1214
            piling  for  the  wide-character  library  to use the
 
1215
            extended (wide-character)  functions.   The  <STRONG>curses.h</STRONG>
 
1216
            file   which  is  installed  for  the  wide-character
 
1217
            library is designed to be compatible with the  normal
1183
1218
            library's header.  Only the size of the <STRONG>WINDOW</STRONG> struc-
1184
 
            ture  differs, and very few applications require more
1185
 
            than a  pointer  to  <STRONG>WINDOW</STRONG>s.   If  the  headers  are
1186
 
            installed   allowing  overwrite,  the  wide-character
1187
 
            library's headers should be installed last, to  allow
1188
 
            applications  to  be  built using either library from
 
1219
            ture differs, and very few applications require  more
 
1220
            than  a  pointer  to  <STRONG>WINDOW</STRONG>s.   If  the  headers are
 
1221
            installed  allowing  overwrite,  the   wide-character
 
1222
            library's  headers should be installed last, to allow
 
1223
            applications to be built using  either  library  from
1189
1224
            the same set of headers.
1190
1225
 
1191
1226
       --with-pthread
1193
1228
            library names have a "t" appended to them (before any
1194
1229
            "w" added by <STRONG>--enable-widec</STRONG>).
1195
1230
 
1196
 
            The global variables such as <STRONG>LINES</STRONG>  are  replaced  by
1197
 
            macros  to allow read-only access.  At the same time,
1198
 
            setter-functions are provided to  set  these  values.
1199
 
            Some  applications  (very few) may require changes to
 
1231
            The  global  variables  such as <STRONG>LINES</STRONG> are replaced by
 
1232
            macros to allow read-only access.  At the same  time,
 
1233
            setter-functions  are  provided  to set these values.
 
1234
            Some applications (very few) may require  changes  to
1200
1235
            work with this convention.
1201
1236
 
1202
1237
       --with-shared
1206
1241
       --with-debug
1207
1242
 
1208
1243
       --with-profile
1209
 
            The shared and normal (static) library  names  differ
1210
 
            by  their  suffixes,  e.g.,  <STRONG>libncurses.so</STRONG>  and <STRONG>libn-</STRONG>
1211
 
            <STRONG>curses.a</STRONG>.  The debug and profiling  libraries  add  a
 
1244
            The  shared  and normal (static) library names differ
 
1245
            by their  suffixes,  e.g.,  <STRONG>libncurses.so</STRONG>  and  <STRONG>libn-</STRONG>
 
1246
            <STRONG>curses.a</STRONG>.   The  debug  and profiling libraries add a
1212
1247
            "_g" and a "_p" to the root names respectively, e.g.,
1213
1248
            <STRONG>libncurses_g.a</STRONG> and <STRONG>libncurses_p.a</STRONG>.
1214
1249
 
1215
1250
       --with-trace
1216
 
            The <STRONG>trace</STRONG> function  normally  resides  in  the  debug
 
1251
            The  <STRONG>trace</STRONG>  function  normally  resides  in the debug
1217
1252
            library, but it is sometimes useful to configure this
1218
 
            in the  shared  library.   Configure  scripts  should
 
1253
            in  the  shared  library.   Configure  scripts should
1219
1254
            check for the function's existence rather than assum-
1220
1255
            ing it is always in the debug library.
1221
1256
 
1223
1258
</PRE>
1224
1259
<H2><a name="h2-FILES">FILES</a></H2><PRE>
1225
1260
       /usr/share/tabset
1226
 
            directory containing  initialization  files  for  the
 
1261
            directory  containing  initialization  files  for the
1227
1262
            terminal capability database /usr/share/terminfo ter-
1228
1263
            minal capability database
1229
1264
 
1230
1265
 
1231
1266
</PRE>
1232
1267
<H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
1233
 
       <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> and related pages whose  names  begin  "curs_"
 
1268
       <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>  and  related  pages whose names begin "curs_"
1234
1269
       for detailed routine descriptions.
1235
1270
       <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>
1236
1271
 
1240
1275
       The  <STRONG>ncurses</STRONG>  library  can  be  compiled  with  an  option
1241
1276
       (<STRONG>-DUSE_GETCAP</STRONG>) that falls back to the old-style /etc/term-
1242
1277
       cap file if the terminal setup code cannot find a terminfo
1243
 
       entry corresponding to <STRONG>TERM</STRONG>.  Use of this feature  is  not
1244
 
       recommended,  as it essentially includes an entire termcap
1245
 
       compiler in the <STRONG>ncurses</STRONG> startup code, at significant  cost
 
1278
       entry  corresponding  to <STRONG>TERM</STRONG>.  Use of this feature is not
 
1279
       recommended, as it essentially includes an entire  termcap
 
1280
       compiler  in the <STRONG>ncurses</STRONG> startup code, at significant cost
1246
1281
       in core and startup cycles.
1247
1282
 
1248
 
       The  <STRONG>ncurses</STRONG>  library  includes  facilities  for capturing
1249
 
       mouse events on certain terminals (including xterm).   See
 
1283
       The <STRONG>ncurses</STRONG>  library  includes  facilities  for  capturing
 
1284
       mouse  events on certain terminals (including xterm).  See
1250
1285
       the <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG> manual page for details.
1251
1286
 
1252
 
       The  <STRONG>ncurses</STRONG> library includes facilities for responding to
1253
 
       window resizing events, e.g., when running  in  an  xterm.
1254
 
       See  the  <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG>  and <STRONG><A HREF="wresize.3x.html">wresize(3x)</A></STRONG> manual pages for
1255
 
       details.  In addition, the library may be configured  with
 
1287
       The <STRONG>ncurses</STRONG> library includes facilities for responding  to
 
1288
       window  resizing  events,  e.g., when running in an xterm.
 
1289
       See the <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG> and <STRONG><A HREF="wresize.3x.html">wresize(3x)</A></STRONG>  manual  pages  for
 
1290
       details.   In addition, the library may be configured with
1256
1291
       a SIGWINCH handler.
1257
1292
 
1258
 
       The  <STRONG>ncurses</STRONG> library extends the fixed set of function key
1259
 
       capabilities of  terminals  by  allowing  the  application
1260
 
       designer  to  define  additional key sequences at runtime.
 
1293
       The <STRONG>ncurses</STRONG> library extends the fixed set of function  key
 
1294
       capabilities  of  terminals  by  allowing  the application
 
1295
       designer to define additional key  sequences  at  runtime.
1261
1296
       See the <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG> <STRONG><A HREF="key_defined.3x.html">key_defined(3x)</A></STRONG>, and <STRONG><A HREF="keyok.3x.html">keyok(3x)</A></STRONG> man-
1262
1297
       ual pages for details.
1263
1298
 
1264
1299
       The <STRONG>ncurses</STRONG> library can exploit the capabilities of termi-
1265
 
       nals which implement the ISO-6429 SGR 39 and SGR  49  con-
 
1300
       nals  which  implement the ISO-6429 SGR 39 and SGR 49 con-
1266
1301
       trols, which allow an application to reset the terminal to
1267
 
       its original foreground and background colors.   From  the
1268
 
       users'  perspective,  the application is able to draw col-
1269
 
       ored text on a background  whose  color  is  set  indepen-
1270
 
       dently,  providing  better  control  over color contrasts.
 
1302
       its  original  foreground and background colors.  From the
 
1303
       users' perspective, the application is able to  draw  col-
 
1304
       ored  text  on  a  background  whose color is set indepen-
 
1305
       dently, providing better  control  over  color  contrasts.
1271
1306
       See the <STRONG><A HREF="default_colors.3x.html">default_colors(3x)</A></STRONG> manual page for details.
1272
1307
 
1273
 
       The <STRONG>ncurses</STRONG> library  includes  a  function  for  directing
1274
 
       application  output  to a printer attached to the terminal
 
1308
       The  <STRONG>ncurses</STRONG>  library  includes  a  function for directing
 
1309
       application output to a printer attached to  the  terminal
1275
1310
       device.  See the <STRONG><A HREF="curs_print.3x.html">curs_print(3x)</A></STRONG> manual page for details.
1276
1311
 
1277
1312
 
1278
1313
</PRE>
1279
1314
<H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
1280
 
       The <STRONG>ncurses</STRONG> library is intended to be  BASE-level  confor-
 
1315
       The  <STRONG>ncurses</STRONG>  library is intended to be BASE-level confor-
1281
1316
       mant with XSI Curses.  The EXTENDED XSI Curses functional-
1282
1317
       ity (including color support) is supported.
1283
1318
 
1284
 
       A small number of local differences (that  is,  individual
1285
 
       differences  between the XSI Curses and <STRONG>ncurses</STRONG> calls) are
1286
 
       described in  <STRONG>PORTABILITY</STRONG>  sections  of  the  library  man
 
1319
       A  small  number of local differences (that is, individual
 
1320
       differences between the XSI Curses and <STRONG>ncurses</STRONG> calls)  are
 
1321
       described  in  <STRONG>PORTABILITY</STRONG>  sections  of  the  library man
1287
1322
       pages.
1288
1323
 
1289
 
       Unlike  other  implementations, this one checks parameters
1290
 
       such as pointers to WINDOW structures to ensure  they  are
1291
 
       not  null.  The main reason for providing this behavior is
 
1324
       Unlike other implementations, this one  checks  parameters
 
1325
       such  as  pointers to WINDOW structures to ensure they are
 
1326
       not null.  The main reason for providing this behavior  is
1292
1327
       to guard against programmer error.  The standard interface
1293
1328
       does not provide a way for the library to tell an applica-
1294
 
       tion which  of  several  possible  errors  were  detected.
1295
 
       Relying  on  this (or some other) extension will adversely
 
1329
       tion  which  of  several  possible  errors  were detected.
 
1330
       Relying on this (or some other) extension  will  adversely
1296
1331
       affect the portability of curses applications.
1297
1332
 
1298
1333
       This implementation also contains several extensions:
1299
1334
 
1300
 
       <STRONG>o</STRONG>   The routine <STRONG>has_key</STRONG> is not part of  XPG4,  nor  is  it
1301
 
           present  in  SVr4.  See the <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG> manual page
 
1335
       <STRONG>o</STRONG>   The  routine  <STRONG>has_key</STRONG>  is  not part of XPG4, nor is it
 
1336
           present in SVr4.  See the <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>  manual  page
1302
1337
           for details.
1303
1338
 
1304
 
       <STRONG>o</STRONG>   The routine <STRONG>slk_attr</STRONG> is not part of XPG4,  nor  is  it
 
1339
       <STRONG>o</STRONG>   The  routine  <STRONG>slk_attr</STRONG>  is not part of XPG4, nor is it
1305
1340
           present in SVr4.  See the <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG> manual page for
1306
1341
           details.
1307
1342
 
1308
1343
       <STRONG>o</STRONG>   The routines <STRONG>getmouse</STRONG>, <STRONG>mousemask</STRONG>, <STRONG>ungetmouse</STRONG>, <STRONG>mousein-</STRONG>
1309
1344
           <STRONG>terval</STRONG>, and <STRONG>wenclose</STRONG> relating to mouse interfacing are
1310
 
           not part of XPG4, nor are they present in  SVr4.   See
 
1345
           not  part  of XPG4, nor are they present in SVr4.  See
1311
1346
           the <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG> manual page for details.
1312
1347
 
1313
 
       <STRONG>o</STRONG>   The  routine  <STRONG>mcprint</STRONG>  was not present in any previous
1314
 
           curses implementation.  See the <STRONG><A HREF="curs_print.3x.html">curs_print(3x)</A></STRONG>  manual
 
1348
       <STRONG>o</STRONG>   The routine <STRONG>mcprint</STRONG> was not present  in  any  previous
 
1349
           curses  implementation.  See the <STRONG><A HREF="curs_print.3x.html">curs_print(3x)</A></STRONG> manual
1315
1350
           page for details.
1316
1351
 
1317
 
       <STRONG>o</STRONG>   The  routine  <STRONG>wresize</STRONG>  is  not part of XPG4, nor is it
1318
 
           present in SVr4.  See the <STRONG><A HREF="wresize.3x.html">wresize(3x)</A></STRONG> manual page  for
 
1352
       <STRONG>o</STRONG>   The routine <STRONG>wresize</STRONG> is not part of  XPG4,  nor  is  it
 
1353
           present  in SVr4.  See the <STRONG><A HREF="wresize.3x.html">wresize(3x)</A></STRONG> manual page for
1319
1354
           details.
1320
1355
 
1321
 
       <STRONG>o</STRONG>   The  WINDOW structure's internal details can be hidden
1322
 
           from application programs.   See  <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>  for
 
1356
       <STRONG>o</STRONG>   The WINDOW structure's internal details can be  hidden
 
1357
           from  application  programs.   See <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG> for
1323
1358
           the discussion of <STRONG>is_scrollok</STRONG>, etc.
1324
1359
 
1325
1360
       <STRONG>o</STRONG>   This implementation can be configured to provide rudi-
1326
 
           mentary support for multi-threaded applications.   See
 
1361
           mentary  support for multi-threaded applications.  See
1327
1362
           <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG> for details.
1328
1363
 
1329
 
       <STRONG>o</STRONG>   This  implementation can also be configured to provide
 
1364
       <STRONG>o</STRONG>   This implementation can also be configured to  provide
1330
1365
           a set of functions which improve the ability to manage
1331
1366
           multiple screens.  See <STRONG><A HREF="curs_sp_funcs.3x.html">curs_sp_funcs(3x)</A></STRONG> for details.
1332
1367
 
1333
 
       In  historic curses versions, delays embedded in the capa-
 
1368
       In historic curses versions, delays embedded in the  capa-
1334
1369
       bilities <STRONG>cr</STRONG>, <STRONG>ind</STRONG>, <STRONG>cub1</STRONG>, <STRONG>ff</STRONG> and <STRONG>tab</STRONG> activated corresponding
1335
 
       delay  bits  in  the UNIX tty driver.  In this implementa-
1336
 
       tion, all padding is done  by  sending  NUL  bytes.   This
1337
 
       method  is slightly more expensive, but narrows the inter-
1338
 
       face to the UNIX kernel significantly  and  increases  the
 
1370
       delay bits in the UNIX tty driver.   In  this  implementa-
 
1371
       tion,  all  padding  is  done  by sending NUL bytes.  This
 
1372
       method is slightly more expensive, but narrows the  inter-
 
1373
       face  to  the  UNIX kernel significantly and increases the
1339
1374
       package's portability correspondingly.
1340
1375
 
1341
1376
 
1342
1377
</PRE>
1343
1378
<H2><a name="h2-NOTES">NOTES</a></H2><PRE>
1344
 
       The  header  file  <STRONG>&lt;curses.h&gt;</STRONG>  automatically  includes the
 
1379
       The header  file  <STRONG>&lt;curses.h&gt;</STRONG>  automatically  includes  the
1345
1380
       header files <STRONG>&lt;stdio.h&gt;</STRONG> and <STRONG>&lt;unctrl.h&gt;</STRONG>.
1346
1381
 
1347
 
       If standard output from a <STRONG>ncurses</STRONG> program  is  re-directed
1348
 
       to  something  which  is not a tty, screen updates will be
 
1382
       If  standard  output from a <STRONG>ncurses</STRONG> program is re-directed
 
1383
       to something which is not a tty, screen  updates  will  be
1349
1384
       directed to standard error.  This was an undocumented fea-
1350
1385
       ture of AT&amp;T System V Release 3 curses.
1351
1386
 
1352
1387
 
1353
1388
</PRE>
1354
1389
<H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
1355
 
       Zeyd  M.  Ben-Halim,  Eric  S.  Raymond, Thomas E. Dickey.
 
1390
       Zeyd M. Ben-Halim, Eric  S.  Raymond,  Thomas  E.  Dickey.
1356
1391
       Based on pcurses by Pavel Curtis.
1357
1392
 
1358
1393
 
1365
1400
<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
1366
1401
<li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
1367
1402
<ul>
 
1403
<li><a href="#h3-Initialization">Initialization</a></li>
 
1404
<li><a href="#h3-Datatypes">Datatypes</a></li>
 
1405
<li><a href="#h3-Environment-variables">Environment variables</a></li>
1368
1406
<li><a href="#h3-Routine-and-Argument-Names">Routine and Argument Names</a></li>
1369
1407
<li><a href="#h3-Routine-Name-Index">Routine Name Index</a></li>
1370
1408
</ul>
1371
1409
</li>
1372
1410
<li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
1373
 
<li><a href="#h2-ENVIRONMENT">ENVIRONMENT</a></li>
 
1411
<li><a href="#h2-ENVIRONMENT">ENVIRONMENT</a>
 
1412
<ul>
 
1413
<li><a href="#h3-BAUDRATE">BAUDRATE</a></li>
 
1414
<li><a href="#h3-COLUMNS">COLUMNS</a></li>
 
1415
<li><a href="#h3-ESCDELAY">ESCDELAY</a></li>
 
1416
<li><a href="#h3-HOME">HOME</a></li>
 
1417
<li><a href="#h3-LINES">LINES</a></li>
 
1418
<li><a href="#h3-MOUSE_BUTTONS_123">MOUSE_BUTTONS_123</a></li>
 
1419
<li><a href="#h3-NCURSES_ASSUMED_COLORS">NCURSES_ASSUMED_COLORS</a></li>
 
1420
<li><a href="#h3-NCURSES_CONSOLE2">NCURSES_CONSOLE2</a></li>
 
1421
<li><a href="#h3-NCURSES_GPM_TERMS">NCURSES_GPM_TERMS</a></li>
 
1422
<li><a href="#h3-NCURSES_NO_HARD_TABS">NCURSES_NO_HARD_TABS</a></li>
 
1423
<li><a href="#h3-NCURSES_NO_PADDING">NCURSES_NO_PADDING</a></li>
 
1424
<li><a href="#h3-NCURSES_NO_SETBUF">NCURSES_NO_SETBUF</a></li>
 
1425
<li><a href="#h3-NCURSES_NO_UTF8_ACS">NCURSES_NO_UTF8_ACS</a></li>
 
1426
<li><a href="#h3-NCURSES_TRACE">NCURSES_TRACE</a></li>
 
1427
<li><a href="#h3-TERM">TERM</a></li>
 
1428
<li><a href="#h3-TERMCAP">TERMCAP</a></li>
 
1429
<li><a href="#h3-TERMINFO">TERMINFO</a></li>
 
1430
<li><a href="#h3-TERMINFO_DIRS">TERMINFO_DIRS</a></li>
 
1431
<li><a href="#h3-TERMPATH">TERMPATH</a></li>
 
1432
</ul>
 
1433
</li>
1374
1434
<li><a href="#h2-ALTERNATE-CONFIGURATIONS">ALTERNATE CONFIGURATIONS</a></li>
1375
1435
<li><a href="#h2-FILES">FILES</a></li>
1376
1436
<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>