1ncurses(3X)                                                        ncurses(3X)
2
3
4

NAME

6       ncurses - CRT screen handling and optimization package
7

SYNOPSIS

9       #include <curses.h>
10

DESCRIPTION

12       The  ncurses  library  routines  give  the  user a terminal-independent
13       method of updating  character  screens  with  reasonable  optimization.
14       This  implementation  is  “new  curses”  (ncurses)  and is the approved
15       replacement for 4.4BSD classic curses,  which  has  been  discontinued.
16       This describes ncurses version 6.1 (patch 20191109).
17
18       The  ncurses  library emulates the curses library of System V Release 4
19       UNIX, and XPG4 (X/Open Portability Guide) curses  (also  known  as  XSI
20       curses).   XSI  stands  for  X/Open  System  Interfaces Extension.  The
21       ncurses library is freely redistributable in source form.   Differences
22       from  the SVr4 curses are summarized under the EXTENSIONS and PORTABIL‐
23       ITY sections below and described in detail  in  the  respective  EXTEN‐
24       SIONS, PORTABILITY and BUGS sections of individual man pages.
25
26       The  ncurses  library  also provides many useful extensions, i.e., fea‐
27       tures which cannot be implemented by a simple add-on library but  which
28       require access to the internals of the library.
29
30       A  program  using  these  routines  must  be  linked with the -lncurses
31       option, or (if it  has  been  generated)  with  the  debugging  library
32       -lncurses_g.   (Your  system  integrator  may also have installed these
33       libraries under the names  -lcurses  and  -lcurses_g.)   The  ncurses_g
34       library  generates  trace logs (in a file called 'trace' in the current
35       directory) that describe curses  actions.   See  also  the  section  on
36       ALTERNATE CONFIGURATIONS.
37
38       The  ncurses package supports: overall screen, window and pad manipula‐
39       tion; output to windows and pads; reading terminal input; control  over
40       terminal  and  curses  input and output options; environment query rou‐
41       tines; color manipulation; use of soft label keys;  terminfo  capabili‐
42       ties; and access to low-level terminal-manipulation routines.
43
44   Initialization
45       The  library uses the locale which the calling program has initialized.
46       That is normally done with setlocale:
47
48           setlocale(LC_ALL, "");
49
50       If the locale is not initialized, the library assumes  that  characters
51       are  printable  as in ISO-8859-1, to work with certain legacy programs.
52       You should initialize the locale and not rely on  specific  details  of
53       the library when the locale has not been setup.
54
55       The  function  initscr  or  newterm  must  be  called to initialize the
56       library before any of the other routines that  deal  with  windows  and
57       screens  are  used.  The routine endwin(3X) must be called before exit‐
58       ing.
59
60       To get character-at-a-time input  without  echoing  (most  interactive,
61       screen  oriented  programs want this), the following sequence should be
62       used:
63
64           initscr(); cbreak(); noecho();
65
66       Most programs would additionally use the sequence:
67
68           nonl();
69           intrflush(stdscr, FALSE);
70           keypad(stdscr, TRUE);
71
72       Before a curses program is run, the tab stops of the terminal should be
73       set  and  its initialization strings, if defined, must be output.  This
74       can be done by executing the tput init command after the shell environ‐
75       ment  variable  TERM has been exported.  tset(1) is usually responsible
76       for doing this.  [See terminfo(5) for further details.]
77
78   Datatypes
79       The ncurses library permits manipulation  of  data  structures,  called
80       windows,  which  can be thought of as two-dimensional arrays of charac‐
81       ters representing all or part of a CRT screen.  A default window called
82       stdscr,  which is the size of the terminal screen, is supplied.  Others
83       may be created with newwin.
84
85       Note that curses does not handle overlapping windows,  that's  done  by
86       the  panel(3X)  library.   This means that you can either use stdscr or
87       divide the screen into tiled windows and not using stdscr at all.  Mix‐
88       ing the two will result in unpredictable, and undesired, effects.
89
90       Windows  are referred to by variables declared as WINDOW *.  These data
91       structures are manipulated with routines described here  and  elsewhere
92       in  the ncurses manual pages.  Among those, the most basic routines are
93       move and addch.  More general versions of these routines  are  included
94       with  names  beginning  with  w, allowing the user to specify a window.
95       The routines not beginning with w affect stdscr.
96
97       After using routines to manipulate a  window,  refresh(3X)  is  called,
98       telling  curses  to  make  the user's CRT screen look like stdscr.  The
99       characters in a window are actually  of  type  chtype,  (character  and
100       attribute  data) so that other information about the character may also
101       be stored with each character.
102
103       Special windows called pads may also be manipulated.  These are windows
104       which  are not constrained to the size of the screen and whose contents
105       need not be completely displayed.  See curs_pad(3X) for  more  informa‐
106       tion.
107
108       In  addition  to drawing characters on the screen, video attributes and
109       colors may be supported, causing the characters  to  show  up  in  such
110       modes  as  underlined,  in reverse video, or in color on terminals that
111       support such display enhancements.   Line  drawing  characters  may  be
112       specified  to  be  output.   On input, curses is also able to translate
113       arrow and function keys that transmit escape sequences into single val‐
114       ues.   The  video attributes, line drawing characters, and input values
115       use names, defined in <curses.h>, such  as  A_REVERSE,  ACS_HLINE,  and
116       KEY_LEFT.
117
118   Environment variables
119       If  the environment variables LINES and COLUMNS are set, or if the pro‐
120       gram is executing in a window environment, line and column  information
121       in  the  environment  will override information read by terminfo.  This
122       would affect a program running in an AT&T 630 layer, for example, where
123       the size of a screen is changeable (see ENVIRONMENT).
124
125       If  the  environment  variable  TERMINFO  is defined, any program using
126       curses checks for a local terminal definition before  checking  in  the
127       standard  place.  For example, if TERM is set to att4424, then the com‐
128       piled terminal definition is found in
129
130           /usr/share/terminfo/a/att4424.
131
132       (The a is copied from the first letter of att4424 to avoid creation  of
133       huge  directories.)   However,  if  TERMINFO  is  set to $HOME/myterms,
134       curses first checks
135
136           $HOME/myterms/a/att4424,
137
138       and if that fails, it then checks
139
140           /usr/share/terminfo/a/att4424.
141
142       This is useful for developing experimental definitions  or  when  write
143       permission in /usr/share/terminfo is not available.
144
145       The integer variables LINES and COLS are defined in <curses.h> and will
146       be filled in by initscr with the size of  the  screen.   The  constants
147       TRUE and FALSE have the values 1 and 0, respectively.
148
149       The  curses  routines also define the WINDOW * variable curscr which is
150       used for certain low-level operations like  clearing  and  redrawing  a
151       screen  containing  garbage.  The curscr can be used in only a few rou‐
152       tines.
153
154   Routine and Argument Names
155       Many curses routines have two or more versions.  The routines  prefixed
156       with w require a window argument.  The routines prefixed with p require
157       a pad argument.  Those without a prefix generally use stdscr.
158
159       The routines prefixed with mv require a y and x coordinate to  move  to
160       before performing the appropriate action.  The mv routines imply a call
161       to move before the call to the other routine.  The coordinate y  always
162       refers  to  the row (of the window), and x always refers to the column.
163       The upper left-hand corner is always (0,0), not (1,1).
164
165       The routines prefixed with mvw take both a window argument and x and  y
166       coordinates.   The window argument is always specified before the coor‐
167       dinates.
168
169       In each case, win is the window affected, and pad is the pad  affected;
170       win and pad are always pointers to type WINDOW.
171
172       Option  setting  routines require a Boolean flag bf with the value TRUE
173       or FALSE; bf is always of type bool.  Most of the data  types  used  in
174       the  library  routines,  such  as  WINDOW, SCREEN, bool, and chtype are
175       defined in <curses.h>.  Types used for the terminfo  routines  such  as
176       TERMINAL are defined in <term.h>.
177
178       This manual page describes functions which may appear in any configura‐
179       tion of the library.   There  are  two  common  configurations  of  the
180       library:
181
182          ncurses
183               the "normal" library, which handles 8-bit characters.  The nor‐
184               mal (8-bit) library stores characters combined with  attributes
185               in chtype data.
186
187               Attributes  alone (no corresponding character) may be stored in
188               chtype or the equivalent attr_t data.  In either case, the data
189               is stored in something like an integer.
190
191               Each cell (row and column) in a WINDOW is stored as a chtype.
192
193          ncursesw
194               the  so-called  "wide" library, which handles multibyte charac‐
195               ters (see the section on ALTERNATE CONFIGURATIONS).  The "wide"
196               library  includes  all  of the calls from the "normal" library.
197               It adds about one third more calls using data types which store
198               multibyte characters:
199
200               cchar_t
201                    corresponds to chtype.  However it is a structure, because
202                    more data is stored than can fit  into  an  integer.   The
203                    characters  are  large  enough  to  require a full integer
204                    value - and there may be more than one character per cell.
205                    The  video  attributes  and  color  are stored in separate
206                    fields of the structure.
207
208                    Each cell (row and column) in a  WINDOW  is  stored  as  a
209                    cchar_t.
210
211               wchar_t
212                    stores  a  "wide"  character.  Like chtype, this may be an
213                    integer.
214
215               wint_t
216                    stores a wchar_t or WEOF - not the same, though  both  may
217                    have the same size.
218
219               The  "wide"  library provides new functions which are analogous
220               to functions in the "normal" library.  There is a  naming  con‐
221               vention  which relates many of the normal/wide variants: a "_w"
222               is  inserted  into  the  name.   For  example,  waddch  becomes
223               wadd_wch.
224
225   Routine Name Index
226       The  following table lists each curses routine and the name of the man‐
227       ual page on which it is  described.   Routines  flagged  with  “*”  are
228       ncurses-specific, not described by XPG4 or present in SVr4.
229
230                    curses Routine Name      Manual Page Name
231                    ─────────────────────────────────────────────
232                    COLOR_PAIR               curs_color(3X)
233                    PAIR_NUMBER              curs_attr(3X)
234                    _nc_free_and_exit        curs_memleaks(3X)*
235                    _nc_freeall              curs_memleaks(3X)*
236                    _nc_tracebits            curs_trace(3X)*
237                    _traceattr               curs_trace(3X)*
238                    _traceattr2              curs_trace(3X)*
239                    _tracechar               curs_trace(3X)*
240                    _tracechtype             curs_trace(3X)*
241                    _tracechtype2            curs_trace(3X)*
242                    _tracedump               curs_trace(3X)*
243                    _tracef                  curs_trace(3X)*
244                    _tracemouse              curs_trace(3X)*
245                    add_wch                  curs_add_wch(3X)
246                    add_wchnstr              curs_add_wchstr(3X)
247                    add_wchstr               curs_add_wchstr(3X)
248                    addch                    curs_addch(3X)
249                    addchnstr                curs_addchstr(3X)
250                    addchstr                 curs_addchstr(3X)
251                    addnstr                  curs_addstr(3X)
252                    addnwstr                 curs_addwstr(3X)
253                    addstr                   curs_addstr(3X)
254                    addwstr                  curs_addwstr(3X)
255                    alloc_pair               new_pair(3X)*
256                    assume_default_colors    default_colors(3X)*
257                    attr_get                 curs_attr(3X)
258                    attr_off                 curs_attr(3X)
259                    attr_on                  curs_attr(3X)
260                    attr_set                 curs_attr(3X)
261                    attroff                  curs_attr(3X)
262                    attron                   curs_attr(3X)
263                    attrset                  curs_attr(3X)
264
265                    baudrate                 curs_termattrs(3X)
266                    beep                     curs_beep(3X)
267                    bkgd                     curs_bkgd(3X)
268                    bkgdset                  curs_bkgd(3X)
269                    bkgrnd                   curs_bkgrnd(3X)
270                    bkgrndset                curs_bkgrnd(3X)
271                    border                   curs_border(3X)
272                    border_set               curs_border_set(3X)
273                    box                      curs_border(3X)
274                    box_set                  curs_border_set(3X)
275                    can_change_color         curs_color(3X)
276                    cbreak                   curs_inopts(3X)
277                    chgat                    curs_attr(3X)
278                    clear                    curs_clear(3X)
279                    clearok                  curs_outopts(3X)
280                    clrtobot                 curs_clear(3X)
281                    clrtoeol                 curs_clear(3X)
282                    color_content            curs_color(3X)
283                    color_set                curs_attr(3X)
284                    copywin                  curs_overlay(3X)
285                    curs_set                 curs_kernel(3X)
286                    curses_version           curs_extend(3X)*
287                    def_prog_mode            curs_kernel(3X)
288                    def_shell_mode           curs_kernel(3X)
289                    define_key               define_key(3X)*
290                    del_curterm              curs_terminfo(3X)
291                    delay_output             curs_util(3X)
292                    delch                    curs_delch(3X)
293                    deleteln                 curs_deleteln(3X)
294                    delscreen                curs_initscr(3X)
295                    delwin                   curs_window(3X)
296                    derwin                   curs_window(3X)
297                    doupdate                 curs_refresh(3X)
298                    dupwin                   curs_window(3X)
299                    echo                     curs_inopts(3X)
300                    echo_wchar               curs_add_wch(3X)
301                    echochar                 curs_addch(3X)
302                    endwin                   curs_initscr(3X)
303                    erase                    curs_clear(3X)
304                    erasechar                curs_termattrs(3X)
305                    erasewchar               curs_termattrs(3X)
306                    extended_color_content   curs_color(3X)*
307                    extended_pair_content    curs_color(3X)*
308                    extended_slk_color       curs_slk(3X)*
309                    filter                   curs_util(3X)
310                    find_pair                new_pair(3X)*
311                    flash                    curs_beep(3X)
312                    flushinp                 curs_util(3X)
313                    free_pair                new_pair(3X)*
314                    get_wch                  curs_get_wch(3X)
315                    get_wstr                 curs_get_wstr(3X)
316                    getattrs                 curs_attr(3X)
317                    getbegx                  curs_legacy(3X)*
318                    getbegy                  curs_legacy(3X)*
319                    getbegyx                 curs_getyx(3X)
320                    getbkgd                  curs_bkgd(3X)
321                    getbkgrnd                curs_bkgrnd(3X)
322                    getcchar                 curs_getcchar(3X)
323                    getch                    curs_getch(3X)
324                    getcurx                  curs_legacy(3X)*
325                    getcury                  curs_legacy(3X)*
326                    getmaxx                  curs_legacy(3X)*
327                    getmaxy                  curs_legacy(3X)*
328                    getmaxyx                 curs_getyx(3X)
329                    getmouse                 curs_mouse(3X)*
330
331                    getn_wstr                curs_get_wstr(3X)
332                    getnstr                  curs_getstr(3X)
333                    getparx                  curs_legacy(3X)*
334                    getpary                  curs_legacy(3X)*
335                    getparyx                 curs_getyx(3X)
336                    getstr                   curs_getstr(3X)
337                    getsyx                   curs_kernel(3X)
338                    getwin                   curs_util(3X)
339                    getyx                    curs_getyx(3X)
340                    halfdelay                curs_inopts(3X)
341                    has_colors               curs_color(3X)
342                    has_ic                   curs_termattrs(3X)
343                    has_il                   curs_termattrs(3X)
344                    has_key                  curs_getch(3X)*
345                    hline                    curs_border(3X)
346                    hline_set                curs_border_set(3X)
347                    idcok                    curs_outopts(3X)
348                    idlok                    curs_outopts(3X)
349                    immedok                  curs_outopts(3X)
350                    in_wch                   curs_in_wch(3X)
351                    in_wchnstr               curs_in_wchstr(3X)
352                    in_wchstr                curs_in_wchstr(3X)
353                    inch                     curs_inch(3X)
354                    inchnstr                 curs_inchstr(3X)
355                    inchstr                  curs_inchstr(3X)
356                    init_color               curs_color(3X)
357                    init_extended_color      curs_color(3X)*
358                    init_extended_pair       curs_color(3X)*
359                    init_pair                curs_color(3X)
360                    initscr                  curs_initscr(3X)
361                    innstr                   curs_instr(3X)
362                    innwstr                  curs_inwstr(3X)
363                    ins_nwstr                curs_ins_wstr(3X)
364                    ins_wch                  curs_ins_wch(3X)
365                    ins_wstr                 curs_ins_wstr(3X)
366                    insch                    curs_insch(3X)
367                    insdelln                 curs_deleteln(3X)
368                    insertln                 curs_deleteln(3X)
369                    insnstr                  curs_insstr(3X)
370                    insstr                   curs_insstr(3X)
371                    instr                    curs_instr(3X)
372                    intrflush                curs_inopts(3X)
373                    inwstr                   curs_inwstr(3X)
374                    is_cleared               curs_opaque(3X)*
375                    is_idcok                 curs_opaque(3X)*
376                    is_idlok                 curs_opaque(3X)*
377                    is_immedok               curs_opaque(3X)*
378                    is_keypad                curs_opaque(3X)*
379                    is_leaveok               curs_opaque(3X)*
380                    is_linetouched           curs_touch(3X)
381                    is_nodelay               curs_opaque(3X)*
382                    is_notimeout             curs_opaque(3X)*
383                    is_pad                   curs_opaque(3X)*
384                    is_scrollok              curs_opaque(3X)*
385                    is_subwin                curs_opaque(3X)*
386                    is_syncok                curs_opaque(3X)*
387                    is_term_resized          resizeterm(3X)*
388                    is_wintouched            curs_touch(3X)
389                    isendwin                 curs_initscr(3X)
390                    key_defined              key_defined(3X)*
391                    key_name                 curs_util(3X)
392                    keybound                 keybound(3X)*
393                    keyname                  curs_util(3X)
394                    keyok                    keyok(3X)*
395                    keypad                   curs_inopts(3X)
396
397                    killchar                 curs_termattrs(3X)
398                    killwchar                curs_termattrs(3X)
399                    leaveok                  curs_outopts(3X)
400                    longname                 curs_termattrs(3X)
401                    mcprint                  curs_print(3X)*
402                    meta                     curs_inopts(3X)
403                    mouse_trafo              curs_mouse(3X)*
404                    mouseinterval            curs_mouse(3X)*
405                    mousemask                curs_mouse(3X)*
406                    move                     curs_move(3X)
407                    mvadd_wch                curs_add_wch(3X)
408                    mvadd_wchnstr            curs_add_wchstr(3X)
409                    mvadd_wchstr             curs_add_wchstr(3X)
410                    mvaddch                  curs_addch(3X)
411                    mvaddchnstr              curs_addchstr(3X)
412                    mvaddchstr               curs_addchstr(3X)
413                    mvaddnstr                curs_addstr(3X)
414                    mvaddnwstr               curs_addwstr(3X)
415                    mvaddstr                 curs_addstr(3X)
416                    mvaddwstr                curs_addwstr(3X)
417                    mvchgat                  curs_attr(3X)
418                    mvcur                    curs_terminfo(3X)
419                    mvdelch                  curs_delch(3X)
420                    mvderwin                 curs_window(3X)
421                    mvget_wch                curs_get_wch(3X)
422                    mvget_wstr               curs_get_wstr(3X)
423                    mvgetch                  curs_getch(3X)
424                    mvgetn_wstr              curs_get_wstr(3X)
425                    mvgetnstr                curs_getstr(3X)
426                    mvgetstr                 curs_getstr(3X)
427                    mvhline                  curs_border(3X)
428                    mvhline_set              curs_border_set(3X)
429                    mvin_wch                 curs_in_wch(3X)
430                    mvin_wchnstr             curs_in_wchstr(3X)
431                    mvin_wchstr              curs_in_wchstr(3X)
432                    mvinch                   curs_inch(3X)
433                    mvinchnstr               curs_inchstr(3X)
434                    mvinchstr                curs_inchstr(3X)
435                    mvinnstr                 curs_instr(3X)
436                    mvinnwstr                curs_inwstr(3X)
437                    mvins_nwstr              curs_ins_wstr(3X)
438                    mvins_wch                curs_ins_wch(3X)
439                    mvins_wstr               curs_ins_wstr(3X)
440                    mvinsch                  curs_insch(3X)
441                    mvinsnstr                curs_insstr(3X)
442                    mvinsstr                 curs_insstr(3X)
443                    mvinstr                  curs_instr(3X)
444                    mvinwstr                 curs_inwstr(3X)
445                    mvprintw                 curs_printw(3X)
446                    mvscanw                  curs_scanw(3X)
447                    mvvline                  curs_border(3X)
448                    mvvline_set              curs_border_set(3X)
449                    mvwadd_wch               curs_add_wch(3X)
450                    mvwadd_wchnstr           curs_add_wchstr(3X)
451                    mvwadd_wchstr            curs_add_wchstr(3X)
452                    mvwaddch                 curs_addch(3X)
453                    mvwaddchnstr             curs_addchstr(3X)
454                    mvwaddchstr              curs_addchstr(3X)
455                    mvwaddnstr               curs_addstr(3X)
456                    mvwaddnwstr              curs_addwstr(3X)
457                    mvwaddstr                curs_addstr(3X)
458                    mvwaddwstr               curs_addwstr(3X)
459                    mvwchgat                 curs_attr(3X)
460                    mvwdelch                 curs_delch(3X)
461                    mvwget_wch               curs_get_wch(3X)
462
463                    mvwget_wstr              curs_get_wstr(3X)
464                    mvwgetch                 curs_getch(3X)
465                    mvwgetn_wstr             curs_get_wstr(3X)
466                    mvwgetnstr               curs_getstr(3X)
467                    mvwgetstr                curs_getstr(3X)
468                    mvwhline                 curs_border(3X)
469                    mvwhline_set             curs_border_set(3X)
470                    mvwin                    curs_window(3X)
471                    mvwin_wch                curs_in_wch(3X)
472                    mvwin_wchnstr            curs_in_wchstr(3X)
473                    mvwin_wchstr             curs_in_wchstr(3X)
474                    mvwinch                  curs_inch(3X)
475                    mvwinchnstr              curs_inchstr(3X)
476                    mvwinchstr               curs_inchstr(3X)
477                    mvwinnstr                curs_instr(3X)
478                    mvwinnwstr               curs_inwstr(3X)
479                    mvwins_nwstr             curs_ins_wstr(3X)
480                    mvwins_wch               curs_ins_wch(3X)
481                    mvwins_wstr              curs_ins_wstr(3X)
482                    mvwinsch                 curs_insch(3X)
483                    mvwinsnstr               curs_insstr(3X)
484                    mvwinsstr                curs_insstr(3X)
485                    mvwinstr                 curs_instr(3X)
486                    mvwinwstr                curs_inwstr(3X)
487                    mvwprintw                curs_printw(3X)
488                    mvwscanw                 curs_scanw(3X)
489                    mvwvline                 curs_border(3X)
490                    mvwvline_set             curs_border_set(3X)
491                    napms                    curs_kernel(3X)
492                    newpad                   curs_pad(3X)
493                    newterm                  curs_initscr(3X)
494                    newwin                   curs_window(3X)
495                    nl                       curs_outopts(3X)
496                    nocbreak                 curs_inopts(3X)
497                    nodelay                  curs_inopts(3X)
498                    noecho                   curs_inopts(3X)
499                    nofilter                 curs_util(3X)*
500                    nonl                     curs_outopts(3X)
501                    noqiflush                curs_inopts(3X)
502                    noraw                    curs_inopts(3X)
503                    notimeout                curs_inopts(3X)
504                    overlay                  curs_overlay(3X)
505                    overwrite                curs_overlay(3X)
506                    pair_content             curs_color(3X)
507                    pechochar                curs_pad(3X)
508                    pnoutrefresh             curs_pad(3X)
509                    prefresh                 curs_pad(3X)
510                    printw                   curs_printw(3X)
511                    putp                     curs_terminfo(3X)
512                    putwin                   curs_util(3X)
513                    qiflush                  curs_inopts(3X)
514                    raw                      curs_inopts(3X)
515                    redrawwin                curs_refresh(3X)
516                    refresh                  curs_refresh(3X)
517                    reset_prog_mode          curs_kernel(3X)
518                    reset_shell_mode         curs_kernel(3X)
519                    resetty                  curs_kernel(3X)
520                    resize_term              resizeterm(3X)*
521                    resizeterm               resizeterm(3X)*
522                    restartterm              curs_terminfo(3X)
523                    ripoffline               curs_kernel(3X)
524                    savetty                  curs_kernel(3X)
525                    scanw                    curs_scanw(3X)
526                    scr_dump                 curs_scr_dump(3X)
527                    scr_init                 curs_scr_dump(3X)
528
529                    scr_restore              curs_scr_dump(3X)
530                    scr_set                  curs_scr_dump(3X)
531                    scrl                     curs_scroll(3X)
532                    scroll                   curs_scroll(3X)
533                    scrollok                 curs_outopts(3X)
534                    set_curterm              curs_terminfo(3X)
535                    set_term                 curs_initscr(3X)
536                    setcchar                 curs_getcchar(3X)
537                    setscrreg                curs_outopts(3X)
538                    setsyx                   curs_kernel(3X)
539                    setterm                  curs_terminfo(3X)
540                    setupterm                curs_terminfo(3X)
541                    slk_attr                 curs_slk(3X)*
542                    slk_attr_off             curs_slk(3X)
543                    slk_attr_on              curs_slk(3X)
544                    slk_attr_set             curs_slk(3X)
545                    slk_attroff              curs_slk(3X)
546                    slk_attron               curs_slk(3X)
547                    slk_attrset              curs_slk(3X)
548                    slk_clear                curs_slk(3X)
549                    slk_color                curs_slk(3X)
550                    slk_init                 curs_slk(3X)
551                    slk_label                curs_slk(3X)
552                    slk_noutrefresh          curs_slk(3X)
553                    slk_refresh              curs_slk(3X)
554                    slk_restore              curs_slk(3X)
555                    slk_set                  curs_slk(3X)
556                    slk_touch                curs_slk(3X)
557                    standend                 curs_attr(3X)
558                    standout                 curs_attr(3X)
559                    start_color              curs_color(3X)
560                    subpad                   curs_pad(3X)
561                    subwin                   curs_window(3X)
562                    syncok                   curs_window(3X)
563                    term_attrs               curs_termattrs(3X)
564                    termattrs                curs_termattrs(3X)
565                    termname                 curs_termattrs(3X)
566                    tgetent                  curs_termcap(3X)
567                    tgetflag                 curs_termcap(3X)
568                    tgetnum                  curs_termcap(3X)
569                    tgetstr                  curs_termcap(3X)
570                    tgoto                    curs_termcap(3X)
571                    tigetflag                curs_terminfo(3X)
572                    tigetnum                 curs_terminfo(3X)
573                    tigetstr                 curs_terminfo(3X)
574                    timeout                  curs_inopts(3X)
575                    tiparm                   curs_terminfo(3X)*
576                    touchline                curs_touch(3X)
577                    touchwin                 curs_touch(3X)
578                    tparm                    curs_terminfo(3X)
579                    tputs                    curs_termcap(3X)
580                    tputs                    curs_terminfo(3X)
581                    trace                    curs_trace(3X)*
582                    typeahead                curs_inopts(3X)
583                    unctrl                   curs_util(3X)
584                    unget_wch                curs_get_wch(3X)
585                    ungetch                  curs_getch(3X)
586                    ungetmouse               curs_mouse(3X)*
587                    untouchwin               curs_touch(3X)
588                    use_default_colors       default_colors(3X)*
589                    use_env                  curs_util(3X)
590                    use_extended_names       curs_extend(3X)*
591                    use_legacy_coding        legacy_coding(3X)*
592                    use_tioctl               curs_util(3X)*
593                    vid_attr                 curs_terminfo(3X)
594
595                    vid_puts                 curs_terminfo(3X)
596                    vidattr                  curs_terminfo(3X)
597                    vidputs                  curs_terminfo(3X)
598                    vline                    curs_border(3X)
599                    vline_set                curs_border_set(3X)
600                    vw_printw                curs_printw(3X)
601                    vw_scanw                 curs_scanw(3X)
602                    vwprintw                 curs_printw(3X)
603                    vwscanw                  curs_scanw(3X)
604                    wadd_wch                 curs_add_wch(3X)
605                    wadd_wchnstr             curs_add_wchstr(3X)
606                    wadd_wchstr              curs_add_wchstr(3X)
607                    waddch                   curs_addch(3X)
608                    waddchnstr               curs_addchstr(3X)
609                    waddchstr                curs_addchstr(3X)
610                    waddnstr                 curs_addstr(3X)
611                    waddnwstr                curs_addwstr(3X)
612                    waddstr                  curs_addstr(3X)
613                    waddwstr                 curs_addwstr(3X)
614                    wattr_get                curs_attr(3X)
615                    wattr_off                curs_attr(3X)
616                    wattr_on                 curs_attr(3X)
617                    wattr_set                curs_attr(3X)
618                    wattroff                 curs_attr(3X)
619                    wattron                  curs_attr(3X)
620                    wattrset                 curs_attr(3X)
621                    wbkgd                    curs_bkgd(3X)
622                    wbkgdset                 curs_bkgd(3X)
623                    wbkgrnd                  curs_bkgrnd(3X)
624                    wbkgrndset               curs_bkgrnd(3X)
625                    wborder                  curs_border(3X)
626                    wborder_set              curs_border_set(3X)
627                    wchgat                   curs_attr(3X)
628                    wclear                   curs_clear(3X)
629                    wclrtobot                curs_clear(3X)
630                    wclrtoeol                curs_clear(3X)
631                    wcolor_set               curs_attr(3X)
632                    wcursyncup               curs_window(3X)
633                    wdelch                   curs_delch(3X)
634                    wdeleteln                curs_deleteln(3X)
635                    wecho_wchar              curs_add_wch(3X)
636                    wechochar                curs_addch(3X)
637                    wenclose                 curs_mouse(3X)*
638                    werase                   curs_clear(3X)
639                    wget_wch                 curs_get_wch(3X)
640                    wget_wstr                curs_get_wstr(3X)
641                    wgetbkgrnd               curs_bkgrnd(3X)
642                    wgetch                   curs_getch(3X)
643                    wgetdelay                curs_opaque(3X)*
644                    wgetn_wstr               curs_get_wstr(3X)
645                    wgetnstr                 curs_getstr(3X)
646                    wgetparent               curs_opaque(3X)*
647                    wgetscrreg               curs_opaque(3X)*
648                    wgetstr                  curs_getstr(3X)
649                    whline                   curs_border(3X)
650                    whline_set               curs_border_set(3X)
651                    win_wch                  curs_in_wch(3X)
652                    win_wchnstr              curs_in_wchstr(3X)
653                    win_wchstr               curs_in_wchstr(3X)
654                    winch                    curs_inch(3X)
655                    winchnstr                curs_inchstr(3X)
656                    winchstr                 curs_inchstr(3X)
657                    winnstr                  curs_instr(3X)
658                    winnwstr                 curs_inwstr(3X)
659                    wins_nwstr               curs_ins_wstr(3X)
660
661                    wins_wch                 curs_ins_wch(3X)
662                    wins_wstr                curs_ins_wstr(3X)
663                    winsch                   curs_insch(3X)
664                    winsdelln                curs_deleteln(3X)
665                    winsertln                curs_deleteln(3X)
666                    winsnstr                 curs_insstr(3X)
667                    winsstr                  curs_insstr(3X)
668                    winstr                   curs_instr(3X)
669                    winwstr                  curs_inwstr(3X)
670                    wmouse_trafo             curs_mouse(3X)*
671                    wmove                    curs_move(3X)
672                    wnoutrefresh             curs_refresh(3X)
673                    wprintw                  curs_printw(3X)
674                    wredrawln                curs_refresh(3X)
675                    wrefresh                 curs_refresh(3X)
676                    wresize                  wresize(3X)*
677                    wscanw                   curs_scanw(3X)
678                    wscrl                    curs_scroll(3X)
679                    wsetscrreg               curs_outopts(3X)
680                    wstandend                curs_attr(3X)
681                    wstandout                curs_attr(3X)
682                    wsyncdown                curs_window(3X)
683                    wsyncup                  curs_window(3X)
684                    wtimeout                 curs_inopts(3X)
685                    wtouchln                 curs_touch(3X)
686                    wunctrl                  curs_util(3X)
687                    wvline                   curs_border(3X)
688                    wvline_set               curs_border_set(3X)
689

RETURN VALUE

691       Routines  that return an integer return ERR upon failure and an integer
692       value other than ERR upon successful completion, unless otherwise noted
693       in the routine descriptions.
694
695       As  a  general rule, routines check for null pointers passed as parame‐
696       ters, and handle this as an error.
697
698       All macros return  the  value  of  the  w  version,  except  setscrreg,
699       wsetscrreg,  getyx,  getbegyx,  and  getmaxyx.   The  return  values of
700       setscrreg, wsetscrreg, getyx,  getbegyx,  and  getmaxyx  are  undefined
701       (i.e.,  these  should  not be used as the right-hand side of assignment
702       statements).
703
704       Routines that return pointers return NULL on error.
705

ENVIRONMENT

707       The following environment symbols are useful for customizing  the  run‐
708       time  behavior  of  the  ncurses library.  The most important ones have
709       been already discussed in detail.
710
711   CC command-character
712       When set, change occurrences of the command_character (i.e., the  cmdch
713       capability)  of  the loaded terminfo entries to the value of this vari‐
714       able.  Very few terminfo entries provide this feature.
715
716       Because this name is also used in development environments to represent
717       the C compiler's name, ncurses ignores it if it does not happen to be a
718       single character.
719
720   BAUDRATE
721       The debugging library checks this environment variable when the  appli‐
722       cation  has  redirected output to a file.  The variable's numeric value
723       is used for the baudrate.  If no value is  found,  ncurses  uses  9600.
724       This  allows  testers to construct repeatable test-cases that take into
725       account costs that depend on baudrate.
726
727   COLUMNS
728       Specify the width of the screen in characters.  Applications running in
729       a  windowing  environment  usually  are able to obtain the width of the
730       window in which they are executing.  If neither the COLUMNS  value  nor
731       the  terminal's  screen  size is available, ncurses uses the size which
732       may be specified in the terminfo database (i.e., the cols capability).
733
734       It is important that your  application  use  a  correct  size  for  the
735       screen.   This  is  not always possible because your application may be
736       running on a host which does not honor NAWS (Negotiations About  Window
737       Size),  or  because  you are temporarily running as another user.  How‐
738       ever, setting COLUMNS and/or LINES overrides the library's use  of  the
739       screen size obtained from the operating system.
740
741       Either  COLUMNS  or LINES symbols may be specified independently.  This
742       is mainly useful to circumvent legacy misfeatures of terminal  descrip‐
743       tions, e.g., xterm which commonly specifies a 65 line screen.  For best
744       results, lines and cols should not be specified in a terminal  descrip‐
745       tion for terminals which are run as emulations.
746
747       Use  the  use_env  function  to disable all use of external environment
748       (but not including system calls) to determine the screen size.  Use the
749       use_tioctl function to update COLUMNS or LINES to match the screen size
750       obtained from system calls or the terminal database.
751
752   ESCDELAY
753       Specifies the total time, in milliseconds, for which ncurses will await
754       a  character  sequence,  e.g., a function key.  The default value, 1000
755       milliseconds, is enough for most uses.  However, it is made a  variable
756       to accommodate unusual applications.
757
758       The  most common instance where you may wish to change this value is to
759       work with slow hosts, e.g., running on a network.  If the  host  cannot
760       read  characters rapidly enough, it will have the same effect as if the
761       terminal did not send characters  rapidly  enough.   The  library  will
762       still see a timeout.
763
764       Note  that  xterm  mouse  events  are built up from character sequences
765       received from the xterm.  If your application makes heavy use of multi‐
766       ple-clicking,  you  may wish to lengthen this default value because the
767       timeout applies to the composed multi-click event as well as the  indi‐
768       vidual clicks.
769
770       In addition to the environment variable, this implementation provides a
771       global variable with the same name.  Portable applications  should  not
772       rely  upon  the  presence  of  ESCDELAY in either form, but setting the
773       environment variable rather than the global variable  does  not  create
774       problems when compiling an application.
775
776   HOME
777       Tells  ncurses where your home directory is.  That is where it may read
778       and write auxiliary terminal descriptions:
779
780           $HOME/.termcap
781           $HOME/.terminfo
782
783   LINES
784       Like COLUMNS, specify the height of the screen in characters.  See COL‐
785       UMNS for a detailed description.
786
787   MOUSE_BUTTONS_123
788       This applies only to the OS/2 EMX port.  It specifies the order of but‐
789       tons on the mouse.  OS/2 numbers a 3-button mouse  inconsistently  from
790       other platforms:
791
792           1 = left
793           2 = right
794           3 = middle.
795
796       This variable lets you customize the mouse.  The variable must be three
797       numeric digits 1-3 in any order, e.g., 123 or 321.  If it is not speci‐
798       fied, ncurses uses 132.
799
800   NCURSES_ASSUMED_COLORS
801       Override  the compiled-in assumption that the terminal's default colors
802       are white-on-black (see default_colors(3X)).  You  may  set  the  fore‐
803       ground  and  background  color values with this environment variable by
804       proving a 2-element list: foreground,background.  For example, to  tell
805       ncurses  to  not assume anything about the colors, set this to "-1,-1".
806       To make it green-on-black, set it to "2,0".  Any  positive  value  from
807       zero to the terminfo max_colors value is allowed.
808
809   NCURSES_CONSOLE2
810       This applies only to the MinGW port of ncurses.
811
812       The  Console2 program's handling of the Microsoft Console API call Cre‐
813       ateConsoleScreenBuffer is defective.  Applications which use this  will
814       hang.   However,  it is possible to simulate the action of this call by
815       mapping coordinates,  explicitly  saving  and  restoring  the  original
816       screen  contents.   Setting the environment variable NCGDB has the same
817       effect.
818
819   NCURSES_GPM_TERMS
820       This applies only to ncurses configured to use the GPM interface.
821
822       If present, the environment variable is a list of one or more  terminal
823       names  against which the TERM environment variable is matched.  Setting
824       it to an empty value disables the GPM  interface;  using  the  built-in
825       support for xterm, etc.
826
827       If the environment variable is absent, ncurses will attempt to open GPM
828       if TERM contains "linux".
829
830   NCURSES_NO_HARD_TABS
831       Ncurses may use tabs as part of the cursor movement  optimization.   In
832       some  cases,  your  terminal driver may not handle these properly.  Set
833       this environment variable to disable the feature.  You can also  adjust
834       your stty settings to avoid the problem.
835
836   NCURSES_NO_MAGIC_COOKIE
837       Some  terminals  use a magic-cookie feature which requires special han‐
838       dling to make highlighting and other video attributes display properly.
839       You  can suppress the highlighting entirely for these terminals by set‐
840       ting this environment variable.
841
842   NCURSES_NO_PADDING
843       Most of the terminal descriptions in the terminfo database are  written
844       for  real  "hardware"  terminals.   Many  people use terminal emulators
845       which run in a windowing environment and use curses-based applications.
846       Terminal  emulators  can  duplicate  all  of the important aspects of a
847       hardware terminal, but they do not  have  the  same  limitations.   The
848       chief  limitation  of  a  hardware terminal from the standpoint of your
849       application is the management of  dataflow,  i.e.,  timing.   Unless  a
850       hardware  terminal  is  interfaced  into a terminal concentrator (which
851       does flow control), it (or your application) must manage dataflow, pre‐
852       venting overruns.  The cheapest solution (no hardware cost) is for your
853       program to do this by pausing after operations that the  terminal  does
854       slowly, such as clearing the display.
855
856       As  a  result,  many  terminal  descriptions (including the vt100) have
857       delay times embedded.  You may wish to use these descriptions, but  not
858       want to pay the performance penalty.
859
860       Set  the  NCURSES_NO_PADDING  environment  variable  to disable all but
861       mandatory padding.  Mandatory padding is used as a part of special con‐
862       trol sequences such as flash.
863
864   NCURSES_NO_SETBUF
865       This setting is obsolete.  Before changes
866
867          ·   started with 5.9 patch 20120825 and
868
869          ·   continued though 5.9 patch 20130126
870
871       ncurses  enabled  buffered output during terminal initialization.  This
872       was done (as in SVr4 curses) for performance reasons.  For testing pur‐
873       poses,  both of ncurses and certain applications, this feature was made
874       optional.   Setting  the  NCURSES_NO_SETBUF  variable  disabled  output
875       buffering,  leaving  the output in the original (usually line buffered)
876       mode.
877
878       In the current implementation, ncurses performs its own  buffering  and
879       does  not require this workaround.  It does not modify the buffering of
880       the standard output.
881
882       The reason for the change was to make the behavior for  interrupts  and
883       other  signals  more  robust.   One drawback is that certain nonconven‐
884       tional programs would mix ordinary stdio calls with ncurses  calls  and
885       (usually)  work.  This is no longer possible since ncurses is not using
886       the buffered standard output but its  own  output  (to  the  same  file
887       descriptor).  As a special case, the low-level calls such as putp still
888       use the standard output.  But high-level curses calls do not.
889
890   NCURSES_NO_UTF8_ACS
891       During initialization, the ncurses library  checks  for  special  cases
892       where VT100 line-drawing (and the corresponding alternate character set
893       capabilities) described in  the  terminfo  are  known  to  be  missing.
894       Specifically,  when running in a UTF-8 locale, the Linux console emula‐
895       tor and the GNU screen program ignore these.  Ncurses checks  the  TERM
896       environment  variable  for  these.  For other special cases, you should
897       set this environment variable.  Doing this tells ncurses to use Unicode
898       values  which  correspond to the VT100 line-drawing glyphs.  That works
899       for the special cases cited, and is likely to work for terminal  emula‐
900       tors.
901
902       When setting this variable, you should set it to a nonzero value.  Set‐
903       ting it to zero (or to a nonnumber)  disables  the  special  check  for
904       "linux" and "screen".
905
906       As  an  alternative  to the environment variable, ncurses checks for an
907       extended terminfo capability U8.  This is a  numeric  capability  which
908       can be compiled using tic -x.  For example
909
910          # linux console, if patched to provide working
911          # VT100 shift-in/shift-out, with corresponding font.
912          linux-vt100|linux console with VT100 line-graphics,
913                  U8#0, use=linux,
914
915          # uxterm with vt100Graphics resource set to false
916          xterm-utf8|xterm relying on UTF-8 line-graphics,
917                  U8#1, use=xterm,
918
919       The  name  "U8" is chosen to be two characters, to permit it to be used
920       by applications that use ncurses' termcap interface.
921
922   NCURSES_TRACE
923       During  initialization,  the  ncurses  debugging  library  checks   the
924       NCURSES_TRACE  environment  variable.   If  it is defined, to a numeric
925       value, ncurses calls the trace function, using that value as the  argu‐
926       ment.
927
928       The  argument  values,  which  are defined in curses.h, provide several
929       types of information.  When running with traces enabled, your  applica‐
930       tion will write the file trace to the current directory.
931
932       See curs_trace(3X) for more information.
933
934   TERM
935       Denotes  your  terminal  type.   Each terminal type is distinct, though
936       many are similar.
937
938       TERM is commonly set by terminal emulators to help applications find  a
939       workable terminal description.  Some of those choose a popular approxi‐
940       mation, e.g., “ansi”, “vt100”, “xterm” rather than an exact  fit.   Not
941       infrequently,  your  application will have problems with that approach,
942       e.g., incorrect function-key definitions.
943
944       If you set TERM in your environment, it has no effect on the  operation
945       of  the  terminal  emulator.  It only affects the way applications work
946       within the terminal.  Likewise, as a general rule (xterm being  a  rare
947       exception),  terminal  emulators  which  allow you to specify TERM as a
948       parameter or configuration value do not change their behavior to  match
949       that setting.
950
951   TERMCAP
952       If  the  ncurses  library  has  been  configured  with termcap support,
953       ncurses will check for a terminal's description in termcap form  if  it
954       is not available in the terminfo database.
955
956       The TERMCAP environment variable contains either a terminal description
957       (with newlines stripped out), or a file name telling where the informa‐
958       tion  denoted by the TERM environment variable exists.  In either case,
959       setting it directs ncurses to ignore the usual place for this  informa‐
960       tion, e.g., /etc/termcap.
961
962   TERMINFO
963       ncurses  can  be  configured  to read from multiple terminal databases.
964       The TERMINFO variable overrides the location for the  default  terminal
965       database.   Terminal  descriptions  (in  terminal format) are stored in
966       terminal databases:
967
968       ·   Normally these are stored in a directory tree, using subdirectories
969           named by the first letter of the terminal names therein.
970
971           This is the scheme used in System V, which legacy Unix systems use,
972           and the TERMINFO variable is used by curses applications  on  those
973           systems to override the default location of the terminal database.
974
975       ·   If  ncurses  is  built  to use hashed databases, then each entry in
976           this list may be the path of a hashed database file, e.g.,
977
978               /usr/share/terminfo.db
979
980           rather than
981
982               /usr/share/terminfo/
983
984           The hashed database uses less disk-space and  is  a  little  faster
985           than  the  directory  tree.   However, some applications assume the
986           existence of the directory tree, reading it  directly  rather  than
987           using the terminfo library calls.
988
989       ·   If  ncurses  is  built  with  a  support  for reading termcap files
990           directly, then an entry in this list may be the path of  a  termcap
991           file.
992
993       ·   If the TERMINFO variable begins with “hex:” or “b64:”, ncurses uses
994           the remainder of that variable as a compiled terminal  description.
995           You might produce the base64 format using infocmp(1M):
996
997               TERMINFO="$(infocmp -0 -Q2 -q)"
998               export TERMINFO
999
1000           The  compiled description is used if it corresponds to the terminal
1001           identified by the TERM variable.
1002
1003       Setting TERMINFO is the simplest, but not the only way to set  location
1004       of  the default terminal database.  The complete list of database loca‐
1005       tions in order follows:
1006
1007          ·   the last terminal database to which ncurses wrote,  if  any,  is
1008              searched first
1009
1010          ·   the location specified by the TERMINFO environment variable
1011
1012          ·   $HOME/.terminfo
1013
1014          ·   locations listed in the TERMINFO_DIRS environment variable
1015
1016          ·   one  or  more  locations whose names are configured and compiled
1017              into the ncurses library, i.e.,
1018
1019             ·   no default value (corresponding to  the  TERMINFO_DIRS  vari‐
1020                 able)
1021
1022             ·   /usr/share/terminfo (corresponding to the TERMINFO variable)
1023
1024   TERMINFO_DIRS
1025       Specifies  a  list  of  locations  to search for terminal descriptions.
1026       Each location in the list is a terminal database as  described  in  the
1027       section  on  the  TERMINFO  variable.   The list is separated by colons
1028       (i.e., ":") on Unix, semicolons on OS/2 EMX.
1029
1030       There is no corresponding feature in System V terminfo; it is an exten‐
1031       sion developed for ncurses.
1032
1033   TERMPATH
1034       If  TERMCAP  does not hold a file name then ncurses checks the TERMPATH
1035       environment variable.  This is a list of filenames separated by  spaces
1036       or colons (i.e., ":") on Unix, semicolons on OS/2 EMX.
1037
1038       If  the  TERMPATH environment variable is not set, ncurses looks in the
1039       files
1040
1041           /etc/termcap, /usr/share/misc/termcap and $HOME/.termcap,
1042
1043       in that order.
1044
1045       The library may be configured to disregard the following variables when
1046       the  current  user  is the superuser (root), or if the application uses
1047       setuid or setgid permissions:
1048
1049           $TERMINFO, $TERMINFO_DIRS, $TERMPATH, as well as $HOME.
1050

ALTERNATE CONFIGURATIONS

1052       Several different configurations are possible, depending on the config‐
1053       ure  script  options  used when building ncurses.  There are a few main
1054       options whose effects are visible to the applications  developer  using
1055       ncurses:
1056
1057       --disable-overwrite
1058            The standard include for ncurses is as noted in SYNOPSIS:
1059
1060                #include <curses.h>
1061
1062            This  option  is  used to avoid filename conflicts when ncurses is
1063            not the main implementation of curses of the computer.  If ncurses
1064            is  installed disabling overwrite, it puts its headers in a subdi‐
1065            rectory, e.g.,
1066
1067                #include <ncurses/curses.h>
1068
1069            It also omits a  symbolic  link  which  would  allow  you  to  use
1070            -lcurses to build executables.
1071
1072       --enable-widec
1073            The  configure  script  renames  the  library  and  (if the --dis‐
1074            able-overwrite option is used) puts the header files in a  differ‐
1075            ent subdirectory.  All of the library names have a "w" appended to
1076            them, i.e., instead of
1077
1078                -lncurses
1079
1080            you link with
1081
1082                -lncursesw
1083
1084            You must also enable the wide-character  features  in  the  header
1085            file  when  compiling  for  the  wide-character library to use the
1086            extended (wide-character) functions.   The  symbol  which  enables
1087            these features has changed since XSI Curses, Issue 4:
1088
1089            ·   Originally,  the  wide-character  feature  required the symbol
1090                _XOPEN_SOURCE_EXTENDED  but  that  was  only  valid  for  XPG4
1091                (1996).
1092
1093            ·   Later,  that was deemed conflicting with _XOPEN_SOURCE defined
1094                to 500.
1095
1096            ·   As of mid-2018, none of the features  in  this  implementation
1097                require  a  _XOPEN_SOURCE  feature greater than 600.  However,
1098                X/Open Curses, Issue 7 (2009) recommends defining it to 700.
1099
1100            ·   Alternatively,  you  can  enable  the  feature   by   defining
1101                NCURSES_WIDECHAR  with  the caveat that some other header file
1102                than curses.h may require a specific value  for  _XOPEN_SOURCE
1103                (or a system-specific symbol).
1104
1105            The  curses.h  file  which  is  installed  for  the wide-character
1106            library is designed to be compatible  with  the  normal  library's
1107            header.   Only  the size of the WINDOW structure differs, and very
1108            few applications require more than a pointer to WINDOWs.
1109
1110            If the headers are installed allowing overwrite, the  wide-charac‐
1111            ter  library's headers should be installed last, to allow applica‐
1112            tions to be built using either library from the same set of  head‐
1113            ers.
1114
1115       --with-pthread
1116            The  configure  script  renames  the  library.  All of the library
1117            names have a "t"  appended  to  them  (before  any  "w"  added  by
1118            --enable-widec).
1119
1120            The global variables such as LINES are replaced by macros to allow
1121            read-only access.  At the same time, setter-functions are provided
1122            to  set  these  values.   Some applications (very few) may require
1123            changes to work with this convention.
1124
1125       --with-shared
1126
1127       --with-normal
1128
1129       --with-debug
1130
1131       --with-profile
1132            The shared and normal (static) library names differ by their  suf‐
1133            fixes,  e.g.,  libncurses.so and libncurses.a.  The debug and pro‐
1134            filing libraries add a "_g" and a "_p" to the root  names  respec‐
1135            tively, e.g., libncurses_g.a and libncurses_p.a.
1136
1137       --with-trace
1138            The  trace  function normally resides in the debug library, but it
1139            is sometimes useful to configure this in the shared library.  Con‐
1140            figure  scripts  should  check for the function's existence rather
1141            than assuming it is always in the debug library.
1142

FILES

1144       /usr/share/tabset
1145            directory containing initialization files for the  terminal  capa‐
1146            bility database /usr/share/terminfo terminal capability database
1147

SEE ALSO

1149       terminfo(5)  and  related  pages whose names begin "curs_" for detailed
1150       routine descriptions.
1151       curs_variables(3X)
1152       user_caps(5) for user-defined capabilities
1153

EXTENSIONS

1155       The ncurses library can be compiled with an option (-DUSE_GETCAP)  that
1156       falls  back  to  the  old-style /etc/termcap file if the terminal setup
1157       code cannot find a terminfo entry corresponding to TERM.  Use  of  this
1158       feature  is not recommended, as it essentially includes an entire term‐
1159       cap compiler in the ncurses startup code, at significant cost  in  core
1160       and startup cycles.
1161
1162       The  ncurses  library includes facilities for capturing mouse events on
1163       certain terminals (including xterm).   See  the  curs_mouse(3X)  manual
1164       page for details.
1165
1166       The ncurses library includes facilities for responding to window resiz‐
1167       ing events, e.g., when running in an xterm.  See the resizeterm(3X) and
1168       wresize(3X)  manual pages for details.  In addition, the library may be
1169       configured with a SIGWINCH handler.
1170
1171       The ncurses library extends the fixed set of function key  capabilities
1172       of  terminals by allowing the application designer to define additional
1173       key sequences at runtime.  See the define_key(3X) key_defined(3X),  and
1174       keyok(3X) manual pages for details.
1175
1176       The  ncurses  library  can  exploit the capabilities of terminals which
1177       implement the ISO-6429 SGR 39 and  SGR  49  controls,  which  allow  an
1178       application  to reset the terminal to its original foreground and back‐
1179       ground colors.  From the users' perspective, the application is able to
1180       draw  colored  text  on  a background whose color is set independently,
1181       providing better control over color contrasts.   See  the  default_col‐
1182       ors(3X) manual page for details.
1183
1184       The  ncurses library includes a function for directing application out‐
1185       put  to  a  printer  attached  to  the  terminal   device.    See   the
1186       curs_print(3X) manual page for details.
1187

PORTABILITY

1189       The  ncurses  library  is intended to be BASE-level conformant with XSI
1190       Curses.  The EXTENDED XSI Curses functionality  (including  color  sup‐
1191       port) is supported.
1192
1193       A  small  number  of local differences (that is, individual differences
1194       between the XSI Curses and ncurses calls) are described in  PORTABILITY
1195       sections of the library man pages.
1196
1197       Unlike other implementations, this one checks parameters such as point‐
1198       ers to WINDOW structures to ensure they are not null.  The main  reason
1199       for  providing this behavior is to guard against programmer error.  The
1200       standard interface does not provide a way for the library  to  tell  an
1201       application which of several possible errors were detected.  Relying on
1202       this (or some other) extension will adversely affect the portability of
1203       curses applications.
1204
1205       This implementation also contains several extensions:
1206
1207       ·   The routine has_key is not part of XPG4, nor is it present in SVr4.
1208           See the curs_getch(3X) manual page for details.
1209
1210       ·   The routine slk_attr is not part of XPG4,  nor  is  it  present  in
1211           SVr4.  See the curs_slk(3X) manual page for details.
1212
1213       ·   The  routines  getmouse,  mousemask, ungetmouse, mouseinterval, and
1214           wenclose relating to mouse interfacing are not part  of  XPG4,  nor
1215           are  they  present in SVr4.  See the curs_mouse(3X) manual page for
1216           details.
1217
1218       ·   The routine mcprint was not present in any previous  curses  imple‐
1219           mentation.  See the curs_print(3X) manual page for details.
1220
1221       ·   The routine wresize is not part of XPG4, nor is it present in SVr4.
1222           See the wresize(3X) manual page for details.
1223
1224       ·   The WINDOW structure's internal details can be hidden from applica‐
1225           tion programs.  See curs_opaque(3X) for the discussion of is_scrol‐
1226           lok, etc.
1227
1228       ·   This implementation can be configured to provide  rudimentary  sup‐
1229           port  for  multi-threaded  applications.   See curs_threads(3X) for
1230           details.
1231
1232       ·   This implementation can also be configured  to  provide  a  set  of
1233           functions  which  improve  the  ability to manage multiple screens.
1234           See curs_sp_funcs(3X) for details.
1235
1236       In historic curses versions, delays embedded in  the  capabilities  cr,
1237       ind,  cub1,  ff  and tab activated corresponding delay bits in the UNIX
1238       tty driver.  In this implementation, all padding is done by sending NUL
1239       bytes.   This method is slightly more expensive, but narrows the inter‐
1240       face to the UNIX  kernel  significantly  and  increases  the  package's
1241       portability correspondingly.
1242

NOTES

1244       The  header  file  <curses.h>  automatically  includes the header files
1245       <stdio.h> and <unctrl.h>.
1246
1247       If standard output from a ncurses program is re-directed  to  something
1248       which  is not a tty, screen updates will be directed to standard error.
1249       This was an undocumented feature of AT&T System V Release 3 curses.
1250

AUTHORS

1252       Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey.  Based on pcurses
1253       by Pavel Curtis.
1254
1255
1256
1257                                                                   ncurses(3X)
Impressum