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

RETURN VALUE

700       Routines that return an integer return ERR upon failure and an  integer
701       value other than ERR upon successful completion, unless otherwise noted
702       in the routine descriptions.
703
704       As a general rule, routines check for null pointers passed  as  parame‐
705       ters, and handle this as an error.
706
707       All  macros  return  the  value  of  the  w  version, except setscrreg,
708       wsetscrreg, getyx,  getbegyx,  and  getmaxyx.   The  return  values  of
709       setscrreg,  wsetscrreg,  getyx,  getbegyx,  and  getmaxyx are undefined
710       (i.e., these should not be used as the right-hand  side  of  assignment
711       statements).
712
713       Functions  with  a  “mv”  prefix  first perform a cursor movement using
714       wmove, and return an error if the position is outside the window, or if
715       the window pointer is null.  Most “mv”-prefixed functions (except vari‐
716       adic functions such as mvprintw) are provided both as macros and  func‐
717       tions.
718
719       Routines that return pointers return NULL on error.
720

ENVIRONMENT

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

ALTERNATE CONFIGURATIONS

1067       Several different configurations are possible, depending on the config‐
1068       ure script options used when building ncurses.  There are  a  few  main
1069       options  whose  effects are visible to the applications developer using
1070       ncurses:
1071
1072       --disable-overwrite
1073            The standard include for ncurses is as noted in SYNOPSIS:
1074
1075                #include <curses.h>
1076
1077            This option is used to avoid filename conflicts  when  ncurses  is
1078            not the main implementation of curses of the computer.  If ncurses
1079            is installed disabling overwrite, it puts its headers in a  subdi‐
1080            rectory, e.g.,
1081
1082                #include <ncurses/curses.h>
1083
1084            It  also  omits  a  symbolic  link  which  would  allow you to use
1085            -lcurses to build executables.
1086
1087       --enable-widec
1088            The configure script  renames  the  library  and  (if  the  --dis‐
1089            able-overwrite  option is used) puts the header files in a differ‐
1090            ent subdirectory.  All of the library names have a “w” appended to
1091            them, i.e., instead of
1092
1093                -lncurses
1094
1095            you link with
1096
1097                -lncursesw
1098
1099            You  must  also  enable  the wide-character features in the header
1100            file when compiling for the wide-character library to use the  ex‐
1101            tended (wide-character) functions.  The symbol which enables these
1102            features has changed since XSI Curses, Issue 4:
1103
1104            •   Originally, the wide-character  feature  required  the  symbol
1105                _XOPEN_SOURCE_EXTENDED  but  that  was  only  valid  for  XPG4
1106                (1996).
1107
1108            •   Later, that was deemed conflicting with _XOPEN_SOURCE  defined
1109                to 500.
1110
1111            •   As  of  mid-2018,  none of the features in this implementation
1112                require a _XOPEN_SOURCE feature greater  than  600.   However,
1113                X/Open Curses, Issue 7 (2009) recommends defining it to 700.
1114
1115            •   Alternatively,   you   can  enable  the  feature  by  defining
1116                NCURSES_WIDECHAR with the caveat that some other  header  file
1117                than  curses.h  may require a specific value for _XOPEN_SOURCE
1118                (or a system-specific symbol).
1119
1120            The curses.h file which is installed for  the  wide-character  li‐
1121            brary  is  designed  to  be  compatible  with the normal library's
1122            header.  Only the size of the WINDOW structure differs,  and  very
1123            few applications require more than a pointer to WINDOWs.
1124
1125            If  the headers are installed allowing overwrite, the wide-charac‐
1126            ter library's headers should be installed last, to allow  applica‐
1127            tions  to be built using either library from the same set of head‐
1128            ers.
1129
1130       --with-pthread
1131            The configure script renames the  library.   All  of  the  library
1132            names  have  a “t” appended to them (before any “w” added by --en‐
1133            able-widec).
1134
1135            The global variables such as LINES are replaced by macros to allow
1136            read-only access.  At the same time, setter-functions are provided
1137            to set these values.  Some applications  (very  few)  may  require
1138            changes to work with this convention.
1139
1140       --with-shared
1141
1142       --with-normal
1143
1144       --with-debug
1145
1146       --with-profile
1147            The  shared and normal (static) library names differ by their suf‐
1148            fixes, e.g., libncurses.so and libncurses.a.  The debug  and  pro‐
1149            filing  libraries  add a “_g” and a “_p” to the root names respec‐
1150            tively, e.g., libncurses_g.a and libncurses_p.a.
1151
1152       --with-termlib
1153            Low-level functions which do not depend upon whether  the  library
1154            supports wide-characters, are provided in the tinfo library.
1155
1156            By  doing  this, it is possible to share the tinfo library between
1157            wide/normal configurations as well as reduce the size of  the  li‐
1158            brary when only low-level functions are needed.
1159
1160            Those functions are described in these pages:
1161
1162            •   curs_extend(3X) - miscellaneous curses extensions
1163
1164            •   curs_inopts(3X) - curses input options
1165
1166            •   curs_kernel(3X) - low-level curses routines
1167
1168            •   curs_termattrs(3X) - curses environment query routines
1169
1170            •   curs_termcap(3X) - curses emulation of termcap
1171
1172            •   curs_terminfo(3X) - curses interfaces to terminfo database
1173
1174            •   curs_util(3X) - miscellaneous curses utility routines
1175
1176       --with-trace
1177            The  trace  function normally resides in the debug library, but it
1178            is sometimes useful to configure this in the shared library.  Con‐
1179            figure  scripts  should  check for the function's existence rather
1180            than assuming it is always in the debug library.
1181

FILES

1183       /usr/share/tabset
1184            directory containing initialization files for the  terminal  capa‐
1185            bility database /usr/share/terminfo terminal capability database
1186

SEE ALSO

1188       terminfo(5)  and  related  pages whose names begin “curs_” for detailed
1189       routine descriptions.
1190       curs_variables(3X)
1191       user_caps(5) for user-defined capabilities
1192

EXTENSIONS

1194       The ncurses library can be compiled with an option (-DUSE_GETCAP)  that
1195       falls  back  to  the  old-style /etc/termcap file if the terminal setup
1196       code cannot find a terminfo entry corresponding to TERM.  Use  of  this
1197       feature  is not recommended, as it essentially includes an entire term‐
1198       cap compiler in the ncurses startup code, at significant cost  in  core
1199       and startup cycles.
1200
1201       The  ncurses  library includes facilities for capturing mouse events on
1202       certain terminals (including xterm).   See  the  curs_mouse(3X)  manual
1203       page for details.
1204
1205       The ncurses library includes facilities for responding to window resiz‐
1206       ing events, e.g., when running in an xterm.  See the resizeterm(3X) and
1207       wresize(3X)  manual pages for details.  In addition, the library may be
1208       configured with a SIGWINCH handler.
1209
1210       The ncurses library extends the fixed set of function key  capabilities
1211       of  terminals by allowing the application designer to define additional
1212       key sequences at runtime.  See the define_key(3X) key_defined(3X),  and
1213       keyok(3X) manual pages for details.
1214
1215       The ncurses library can exploit the capabilities of terminals which im‐
1216       plement the ISO-6429 SGR 39 and SGR 49 controls, which allow an  appli‐
1217       cation  to reset the terminal to its original foreground and background
1218       colors.  From the users' perspective, the application is able  to  draw
1219       colored  text on a background whose color is set independently, provid‐
1220       ing better control over color contrasts.   See  the  default_colors(3X)
1221       manual page for details.
1222
1223       The  ncurses library includes a function for directing application out‐
1224       put  to  a  printer  attached  to  the  terminal   device.    See   the
1225       curs_print(3X) manual page for details.
1226

PORTABILITY

1228       The  ncurses  library  is intended to be BASE-level conformant with XSI
1229       Curses.  The EXTENDED XSI Curses functionality  (including  color  sup‐
1230       port) is supported.
1231
1232       A  small  number  of local differences (that is, individual differences
1233       between the XSI Curses and ncurses calls) are described in  PORTABILITY
1234       sections of the library man pages.
1235
1236   Error checking
1237       In  many cases, X/Open Curses is vague about error conditions, omitting
1238       some of the SVr4 documentation.
1239
1240       Unlike other implementations, this one checks parameters such as point‐
1241       ers  to WINDOW structures to ensure they are not null.  The main reason
1242       for providing this behavior is to guard against programmer error.   The
1243       standard  interface  does  not provide a way for the library to tell an
1244       application which of several possible errors were detected.  Relying on
1245       this (or some other) extension will adversely affect the portability of
1246       curses applications.
1247
1248   Extensions versus portability
1249       Most of the extensions provided by ncurses have not been  standardized.
1250       Some  have  been  incorporated  into other implementations, such as PD‐
1251       Curses or NetBSD curses.  Here are a few to consider:
1252
1253       •   The routine has_key is not part of XPG4, nor is it present in SVr4.
1254           See the curs_getch(3X) manual page for details.
1255
1256       •   The  routine  slk_attr  is  not  part of XPG4, nor is it present in
1257           SVr4.  See the curs_slk(3X) manual page for details.
1258
1259       •   The routines getmouse, mousemask,  ungetmouse,  mouseinterval,  and
1260           wenclose  relating  to  mouse interfacing are not part of XPG4, nor
1261           are they present in SVr4.  See the curs_mouse(3X) manual  page  for
1262           details.
1263
1264       •   The  routine  mcprint was not present in any previous curses imple‐
1265           mentation.  See the curs_print(3X) manual page for details.
1266
1267       •   The routine wresize is not part of XPG4, nor is it present in SVr4.
1268           See the wresize(3X) manual page for details.
1269
1270       •   The WINDOW structure's internal details can be hidden from applica‐
1271           tion programs.  See curs_opaque(3X) for the discussion of is_scrol‐
1272           lok, etc.
1273
1274       •   This  implementation  can be configured to provide rudimentary sup‐
1275           port for multi-threaded applications.  See curs_threads(3X) for de‐
1276           tails.
1277
1278       •   This  implementation  can  also  be  configured to provide a set of
1279           functions which improve the ability  to  manage  multiple  screens.
1280           See curs_sp_funcs(3X) for details.
1281
1282   Padding differences
1283       In  historic  curses  versions, delays embedded in the capabilities cr,
1284       ind, cub1, ff and tab activated corresponding delay bits  in  the  UNIX
1285       tty driver.  In this implementation, all padding is done by sending NUL
1286       bytes.  This method is slightly more expensive, but narrows the  inter‐
1287       face  to  the  UNIX  kernel  significantly  and increases the package's
1288       portability correspondingly.
1289
1290   Header files
1291       The header file <curses.h>  automatically  includes  the  header  files
1292       <stdio.h> and <unctrl.h>.
1293
1294       X/Open Curses has more to say, but does not finish the story:
1295
1296           The  inclusion  of <curses.h> may make visible all symbols from the
1297           headers <stdio.h>, <term.h>, <termios.h>, and <wchar.h>.
1298
1299       Here is a more complete story:
1300
1301       •   Starting  with  BSD  curses,  all  implementations  have   included
1302           <stdio.h>.
1303
1304           BSD  curses  included  <curses.h>  and  <unctrl.h> from an internal
1305           header "curses.ext" ("ext" was a short name for externs).
1306
1307           BSD curses used <stdio.h> internally (for printw  and  scanw),  but
1308           nothing in <curses.h> itself relied upon <stdio.h>.
1309
1310       •   SVr2  curses  added newterm(3X), which relies upon <stdio.h>.  That
1311           is, the function prototype uses FILE.
1312
1313           SVr4 curses added putwin and getwin, which also use <stdio.h>.
1314
1315           X/Open Curses documents all three of these functions.
1316
1317           SVr4 curses and X/Open Curses do not require the developer  to  in‐
1318           clude  <stdio.h> before including <curses.h>.  Both document curses
1319           showing <curses.h> as the only required header.
1320
1321           As a result, standard <curses.h> will always include <stdio.h>.
1322
1323       •   X/Open Curses is inconsistent with respect to SVr4 regarding  <unc‐
1324           trl.h>.
1325
1326           As   noted  in  curs_util(3X),  ncurses  includes  <unctrl.h>  from
1327           <curses.h> (like SVr4).
1328
1329       •   X/Open's comments about <term.h> and <termios.h> may refer to HP-UX
1330           and AIX:
1331
1332           HP-UX curses includes <term.h> from <curses.h> to declare setupterm
1333           in curses.h, but ncurses (and Solaris curses) do not.
1334
1335           AIX curses includes <term.h> and <termios.h>.  Again, ncurses  (and
1336           Solaris curses) do not.
1337
1338       •   X/Open  says  that <curses.h> may include <term.h>, but there is no
1339           requirement that it do that.
1340
1341           Some  programs  use  functions  declared  in  both  <curses.h>  and
1342           <term.h>,  and  must include both headers in the same module.  Very
1343           old versions of AIX curses required including <curses.h> before in‐
1344           cluding <term.h>.
1345
1346           Because  ncurses  header files include the headers needed to define
1347           datatypes used in the headers, ncurses header files can be included
1348           in  any  order.  But for portability, you should include <curses.h>
1349           before <term.h>.
1350
1351       •   X/Open Curses says "may make visible" because  including  a  header
1352           file does not necessarily make all symbols in it visible (there are
1353           ifdef's to consider).
1354
1355           For instance, in ncurses <wchar.h> may be included  if  the  proper
1356           symbol  is defined, and if ncurses is configured for wide-character
1357           support.  If the header is included, its symbols may be made  visi‐
1358           ble.  That depends on the value used for _XOPEN_SOURCE feature test
1359           macro.
1360
1361       •   X/Open Curses documents one required header,  in  a  special  case:
1362           <stdarg.h>   before  <curses.h>  to  prototype  the  vw_printw  and
1363           vw_scanw functions (as well as the obsolete the vwprintw  and  vws‐
1364           canw functions).  Each of those uses a va_list parameter.
1365
1366           The  two  obsolete  functions  were  introduced in SVr3.  The other
1367           functions were introduced  in  X/Open  Curses.   In  between,  SVr4
1368           curses  provided  for the possibility that an application might in‐
1369           clude either <varargs.h> or <stdarg.h>.  Initially, that  was  done
1370           by  using  void*  for the va_list parameter.  Later, a special type
1371           (defined in <stdio.h>) was introduced, to allow for compiler  type-
1372           checking.  That special type is always available, because <stdio.h>
1373           is always included by <curses.h>.
1374
1375           None of the X/Open Curses implementations require an application to
1376           include  <stdarg.h>  before <curses.h> because they either have al‐
1377           lowed for a special type, or (like ncurses) include <stdarg.h>  di‐
1378           rectly to provide a portable interface.
1379

NOTES

1381       If  standard  output from a ncurses program is re-directed to something
1382       which is not a tty, screen updates will be directed to standard  error.
1383       This was an undocumented feature of AT&T System V Release 3 curses.
1384

AUTHORS

1386       Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey.  Based on pcurses
1387       by Pavel Curtis.
1388
1389
1390
1391                                                                   ncurses(3X)
Impressum