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

RETURN VALUE

672       Routines  that return an integer return ERR upon failure and an integer
673       value other than ERR upon successful completion, unless otherwise noted
674       in the routine descriptions.
675
676       All  macros  return  the  value  of  the  w  version, except setscrreg,
677       wsetscrreg, getyx,  getbegyx,  and  getmaxyx.   The  return  values  of
678       setscrreg,  wsetscrreg,  getyx,  getbegyx,  and  getmaxyx are undefined
679       (i.e., these should not be used as the right-hand  side  of  assignment
680       statements).
681
682       Routines that return pointers return NULL on error.
683

ENVIRONMENT

685       The  following  environment symbols are useful for customizing the run‐
686       time behavior of the ncurses library.  The  most  important  ones  have
687       been already discussed in detail.
688
689       BAUDRATE
690            The  debugging  library  checks  this  environment symbol when the
691            application has redirected output to a file.  The symbol's numeric
692            value  is  used  for  the baudrate.  If no value is found, ncurses
693            uses 9600.  This allows testers to construct repeatable test-cases
694            that take into account costs that depend on baudrate.
695
696       CC   When  set,  change occurrences of the command_character (i.e., the
697            cmdch capability) of the loaded terminfo entries to the  value  of
698            this symbol.  Very few terminfo entries provide this feature.
699
700            Because this name is also used in development environments to rep‐
701            resent the C compiler's name, ncurses ignores it if  it  does  not
702            happen to be a single character.
703
704       COLUMNS
705            Specify  the width of the screen in characters.  Applications run‐
706            ning in a windowing environment usually are  able  to  obtain  the
707            width  of  the window in which they are executing.  If neither the
708            COLUMNS value nor the terminal's screen size is available, ncurses
709            uses  the  size  which  may  be specified in the terminfo database
710            (i.e., the cols capability).
711
712            It is important that your application use a correct size  for  the
713            screen.   This is not always possible because your application may
714            be running on a host which does not honor NAWS (Negotiations About
715            Window  Size),  or  because you are temporarily running as another
716            user.   However,  setting  COLUMNS  and/or  LINES  overrides   the
717            library's  use of the screen size obtained from the operating sys‐
718            tem.
719
720            Either COLUMNS or LINES symbols may  be  specified  independently.
721            This is mainly useful to circumvent legacy misfeatures of terminal
722            descriptions, e.g., xterm  which  commonly  specifies  a  65  line
723            screen.   For best results, lines and cols should not be specified
724            in a terminal description for terminals which are  run  as  emula‐
725            tions.
726
727            Use  the  use_env function to disable all use of external environ‐
728            ment (including system calls) to determine the screen size.
729
730       ESCDELAY
731            Specifies the total time, in milliseconds, for which ncurses  will
732            await  a  character  sequence,  e.g., a function key.  The default
733            value, 1000 milliseconds, is enough for most uses.  However, it is
734            made a variable to accommodate unusual applications.
735
736            The  most  common instance where you may wish to change this value
737            is to work with slow hosts, e.g., running on a  network.   If  the
738            host  cannot read characters rapidly enough, it will have the same
739            effect as if the terminal did not send characters rapidly  enough.
740            The library will still see a timeout.
741
742            Note that xterm mouse events are built up from character sequences
743            received from the xterm.  If your application makes heavy  use  of
744            multiple-clicking,  you  may  wish  to lengthen this default value
745            because the timeout applies to the composed multi-click  event  as
746            well as the individual clicks.
747
748            In  addition to the environment variable, this implementation pro‐
749            vides a global variable with the same name.  Portable applications
750            should  not rely upon the presence of ESCDELAY in either form, but
751            setting the environment variable rather than the  global  variable
752            does not create problems when compiling an application.
753
754       HOME Tells  ncurses where your home directory is.  That is where it may
755            read and write auxiliary terminal descriptions:
756
757            $HOME/.termcap
758            $HOME/.terminfo
759
760       LINES
761            Like COLUMNS, specify the height of the screen in characters.  See
762            COLUMNS for a detailed description.
763
764       MOUSE_BUTTONS_123
765            This applies only to the OS/2 EMX port.  It specifies the order of
766            buttons on the mouse.  OS/2 numbers  a  3-button  mouse  inconsis‐
767            tently from other platforms:
768
769            1 = left
770            2 = right
771            3 = middle.
772
773            This  symbol  lets  you  customize  the mouse.  The symbol must be
774            three numeric digits 1-3 in any order, e.g., 123 or 321.  If it is
775            not specified, ncurses uses 132.
776
777       NCURSES_ASSUMED_COLORS
778            Override  the  compiled-in  assumption that the terminal's default
779            colors are white-on-black (see default_colors(3X)).  You  may  set
780            the  foreground  and background color values with this environment
781            variable by proving a 2-element list: foreground,background.   For
782            example,  to tell ncurses to not assume anything about the colors,
783            set this to "-1,-1".  To make it green-on-black, set it to  "2,0".
784            Any  positive  value from zero to the terminfo max_colors value is
785            allowed.
786
787       NCURSES_GPM_TERMS
788            This applies only to ncurses configured to use the GPM interface.
789
790            If present, the environment variable is a list of one or more ter‐
791            minal  names  against  which  the  TERM  environment  variable  is
792            matched.  Setting it to an empty value disables the GPM interface;
793            using the built-in support for xterm, etc.
794
795            If  the  environment  variable  is absent, ncurses will attempt to
796            open GPM if TERM contains "linux".
797
798       NCURSES_NO_HARD_TABS
799            Ncurses may use tabs as part of the cursor movement  optimization.
800            In some cases, your terminal driver may not handle these properly.
801            Set this environment variable to disable  the  feature.   You  can
802            also adjust your stty settings to avoid the problem.
803
804       NCURSES_NO_MAGIC_COOKIES
805            Some  terminals  use a magic-cookie feature which requires special
806            handling to make highlighting and other video  attributes  display
807            properly.   You  can  suppress the highlighting entirely for these
808            terminals by setting this environment variable.
809
810       NCURSES_NO_PADDING
811            Most of the terminal descriptions in  the  terminfo  database  are
812            written  for  real "hardware" terminals.  Many people use terminal
813            emulators which run in a windowing  environment  and  use  curses-
814            based  applications.   Terminal emulators can duplicate all of the
815            important aspects of a hardware terminal, but they do not have the
816            same  limitations.   The  chief  limitation of a hardware terminal
817            from the standpoint of  your  application  is  the  management  of
818            dataflow,  i.e., timing.  Unless a hardware terminal is interfaced
819            into a terminal concentrator (which does  flow  control),  it  (or
820            your  application) must manage dataflow, preventing overruns.  The
821            cheapest solution (no hardware cost) is for  your  program  to  do
822            this  by  pausing  after operations that the terminal does slowly,
823            such as clearing the display.
824
825            As a result, many terminal descriptions (including the vt100) have
826            delay times embedded.  You may wish to use these descriptions, but
827            not want to pay the performance penalty.
828
829            Set the NCURSES_NO_PADDING symbol to  disable  all  but  mandatory
830            padding.   Mandatory  padding is used as a part of special control
831            sequences such as flash.
832
833       NCURSES_NO_SETBUF
834            Normally ncurses enables buffered output during terminal  initial‐
835            ization.   This  is  done (as in SVr4 curses) for performance rea‐
836            sons.  For testing purposes, both of ncurses and certain  applica‐
837            tions, this feature is made optional.  Setting the NCURSES_NO_SET‐
838            BUF variable disables output buffering, leaving the output in  the
839            original (usually line buffered) mode.
840
841       NCURSES_NO_UTF8_ACS
842            During  initialization,  the  ncurses  library  checks for special
843            cases where VT100 line-drawing (and  the  corresponding  alternate
844            character set capabilities) described in the terminfo are known to
845            be missing.  Specifically, when running in  a  UTF-8  locale,  the
846            Linux  console  emulator  and the GNU screen program ignore these.
847            Ncurses checks the TERM environment variable for these.  For other
848            special  cases,  you  should set this environment variable.  Doing
849            this tells ncurses to use Unicode values which correspond  to  the
850            VT100  line-drawing  glyphs.   That  works  for  the special cases
851            cited, and is likely to work for terminal emulators.
852
853            When setting this variable, you should set it to a nonzero  value.
854            Setting  it to zero (or to a nonnumber) disables the special check
855            for "linux" and "screen".
856
857       NCURSES_TRACE
858            During initialization, the ncurses debugging  library  checks  the
859            NCURSES_TRACE  symbol.   If  it  is  defined,  to a numeric value,
860            ncurses calls the trace function, using that value  as  the  argu‐
861            ment.
862
863            The  argument  values, which are defined in curses.h, provide sev‐
864            eral types of information.  When running with traces enabled, your
865            application will write the file trace to the current directory.
866
867       TERM Denotes  your  terminal  type.   Each  terminal  type is distinct,
868            though many are similar.
869
870       TERMCAP
871            If the ncurses library has been configured with  termcap  support,
872            ncurses will check for a terminal's description in termcap form if
873            it is not available in the terminfo database.
874
875            The TERMCAP symbol contains either a  terminal  description  (with
876            newlines  stripped out), or a file name telling where the informa‐
877            tion denoted by the TERM symbol exists.  In either  case,  setting
878            it directs ncurses to ignore the usual place for this information,
879            e.g., /etc/termcap.
880
881       TERMINFO
882            Overrides the directory in which ncurses searches for your  termi‐
883            nal  description.   This  is the simplest, but not the only way to
884            change the list of directories.  The complete list of  directories
885            in order follows:
886
887            -  the  last directory to which ncurses wrote, if any, is searched
888               first
889
890            -  the directory specified by the TERMINFO symbol
891
892            -  $HOME/.terminfo
893
894            -  directories listed in the TERMINFO_DIRS symbol
895
896            -  one or more directories whose names are configured and compiled
897               into the ncurses library, e.g., /usr/share/terminfo
898
899       TERMINFO_DIRS
900            Specifies  a  list  of directories to search for terminal descrip‐
901            tions.  The list is separated by colons (i.e., ":") on Unix, semi‐
902            colons  on OS/2 EMX.  All of the terminal descriptions are in ter‐
903            minfo form, which makes a subdirectory named for the first  letter
904            of the terminal names therein.
905
906       TERMPATH
907            If  TERMCAP  does  not  hold  a  file name then ncurses checks the
908            TERMPATH symbol.  This is a list of filenames separated by  spaces
909            or  colons  (i.e.,  ":")  on Unix, semicolons on OS/2 EMX.  If the
910            TERMPATH symbol is not set, ncurses looks in the files  /etc/term‐
911            cap, /usr/share/misc/termcap and $HOME/.termcap, in that order.
912
913       The library may be configured to disregard the following variables when
914       the current user is the superuser (root), or if  the  application  uses
915       setuid  or setgid permissions: $TERMINFO, $TERMINFO_DIRS, $TERMPATH, as
916       well as $HOME.
917

ALTERNATE CONFIGURATIONS

919       Several different configurations are possible, depending on the config‐
920       ure  script  options  used when building ncurses.  There are a few main
921       options whose effects are visible to the applications  developer  using
922       ncurses:
923
924       --disable-overwrite
925            The standard include for ncurses is as noted in SYNOPSIS:
926
927            #include <curses.h>
928
929            This  option  is  used to avoid filename conflicts when ncurses is
930            not the main implementation of curses of the computer.  If ncurses
931            is  installed disabling overwrite, it puts its headers in a subdi‐
932            rectory, e.g.,
933
934            #include <ncurses/curses.h>
935
936            It also omits a  symbolic  link  which  would  allow  you  to  use
937            -lcurses to build executables.
938
939       --enable-widec
940            The  configure  script  renames the library and (if the --disable-
941            overwrite option is used) puts the header  files  in  a  different
942            subdirectory.   All  of  the  library names have a "w" appended to
943            them, i.e., instead of
944
945            -lncurses
946
947            you link with
948
949            -lncursesw
950
951            You must also define _XOPEN_SOURCE_EXTENDED when compiling for the
952            wide-character  library to use the extended (wide-character) func‐
953            tions.  The curses.h file which is installed for the  wide-charac‐
954            ter library is designed to be compatible with the normal library's
955            header.  Only the size of the WINDOW structure differs,  and  very
956            few  applications  require more than a pointer to WINDOWs.  If the
957            headers  are  installed  allowing  overwrite,  the  wide-character
958            library's  headers should be installed last, to allow applications
959            to be built using either library from the same set of headers.
960
961       --with-shared
962
963       --with-normal
964
965       --with-debug
966
967       --with-profile
968            The shared and normal (static) library names differ by their  suf‐
969            fixes,  e.g.,  libncurses.so and libncurses.a.  The debug and pro‐
970            filing libraries add a "_g" and a "_p" to the root  names  respec‐
971            tively, e.g., libncurses_g.a and libncurses_p.a.
972
973       --with-trace
974            The  trace  function normally resides in the debug library, but it
975            is sometimes useful to configure this in the shared library.  Con‐
976            figure  scripts  should  check for the function's existence rather
977            than assuming it is always in the debug library.
978

FILES

980       /usr/share/tabset
981            directory containing initialization files for the  terminal  capa‐
982            bility database /usr/share/terminfo terminal capability database
983

SEE ALSO

985       terminfo(5)  and  related  pages whose names begin "curs_" for detailed
986       routine descriptions.
987

EXTENSIONS

989       The ncurses library can be compiled with an option (-DUSE_GETCAP)  that
990       falls  back  to  the  old-style /etc/termcap file if the terminal setup
991       code cannot find a terminfo entry corresponding to TERM.  Use  of  this
992       feature  is not recommended, as it essentially includes an entire term‐
993       cap compiler in the ncurses startup code, at significant cost  in  core
994       and startup cycles.
995
996       The  ncurses  library includes facilities for capturing mouse events on
997       certain terminals (including xterm).   See  the  curs_mouse(3X)  manual
998       page for details.
999
1000       The ncurses library includes facilities for responding to window resiz‐
1001       ing events, e.g., when running in an xterm.  See the resizeterm(3X) and
1002       wresize(3X)  manual pages for details.  In addition, the library may be
1003       configured with a SIGWINCH handler.
1004
1005       The ncurses library extends the fixed set of function key  capabilities
1006       of  terminals by allowing the application designer to define additional
1007       key sequences at runtime.  See the define_key(3X) key_defined(3X),  and
1008       keyok(3X) manual pages for details.
1009
1010       The  ncurses  library  can  exploit the capabilities of terminals which
1011       implement the ISO-6429 SGR 39 and  SGR  49  controls,  which  allow  an
1012       application  to reset the terminal to its original foreground and back‐
1013       ground colors.  From the users' perspective, the application is able to
1014       draw  colored  text  on  a background whose color is set independently,
1015       providing better control over color contrasts.   See  the  default_col‐
1016       ors(3X) manual page for details.
1017
1018       The  ncurses library includes a function for directing application out‐
1019       put  to  a  printer  attached  to  the  terminal   device.    See   the
1020       curs_print(3X) manual page for details.
1021

PORTABILITY

1023       The  ncurses  library  is intended to be BASE-level conformant with XSI
1024       Curses.  The EXTENDED XSI Curses functionality  (including  color  sup‐
1025       port) is supported.
1026
1027       A  small  number  of local differences (that is, individual differences
1028       between the XSI Curses and ncurses calls) are described in  PORTABILITY
1029       sections of the library man pages.
1030
1031       This implementation also contains several extensions:
1032
1033            The  routine  has_key  is  not  part of XPG4, nor is it present in
1034            SVr4.  See the curs_getch(3X) manual page for details.
1035
1036            The routine slk_attr is not part of XPG4, nor  is  it  present  in
1037            SVr4.  See the curs_slk(3X) manual page for details.
1038
1039            The  routines  getmouse, mousemask, ungetmouse, mouseinterval, and
1040            wenclose relating to mouse interfacing are not part of  XPG4,  nor
1041            are  they present in SVr4.  See the curs_mouse(3X) manual page for
1042            details.
1043
1044            The routine mcprint was not present in any previous curses  imple‐
1045            mentation.  See the curs_print(3X) manual page for details.
1046
1047            The  routine  wresize  is  not  part of XPG4, nor is it present in
1048            SVr4.  See the wresize(3X) manual page for details.
1049
1050            The WINDOW structure's internal details can be hidden from  appli‐
1051            cation  programs.   See  curs_opaque(3X)  for  the  discussion  of
1052            is_scrollok, etc.
1053
1054       In historic curses versions, delays embedded in  the  capabilities  cr,
1055       ind,  cub1,  ff  and tab activated corresponding delay bits in the UNIX
1056       tty driver.  In this implementation, all padding is done by sending NUL
1057       bytes.   This method is slightly more expensive, but narrows the inter‐
1058       face to the UNIX  kernel  significantly  and  increases  the  package's
1059       portability correspondingly.
1060

NOTES

1062       The  header  file  <curses.h>  automatically  includes the header files
1063       <stdio.h> and <unctrl.h>.
1064
1065       If standard output from a ncurses program is re-directed  to  something
1066       which  is not a tty, screen updates will be directed to standard error.
1067       This was an undocumented feature of AT&T System V Release 3 curses.
1068

AUTHORS

1070       Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey.  Based on pcurses
1071       by Pavel Curtis.
1072
1073
1074
1075                                                                   ncurses(3X)
Impressum