1curses(3CURSES) Curses Library Functions curses(3CURSES)
2
6 curses - CRT screen handling and optimization package
7
9 cc [ flag... ] file.. .-lcurses [ library... ]
10 #include <curses.h>
11
14 The curses library routines give the user a terminal-independent method
15 of updating character screens with reasonable optimization.
16 The curses package allows: overall screen, window and pad manipula‐
19 tion; output to windows and pads; reading terminal input; control over
20 terminal and curses input and output options; environment query rou‐
21 tines; color manipulation; use of soft label keys; terminfo access; and
22 access to low-level curses routines.
23 To initialize the routines, the routine initscr() or newterm() must be
26 called before any of the other routines that deal with windows and
27 screens are used. The routine endwin() must be called before exiting.
28 To get character-at-a-time input without echoing (most interactive,
29 screen oriented programs want this), the following sequence should be
30 used:
31 initscr,cbreak,noecho;
34 Most programs would additionally use the sequence:
37 nonl,intrflush(stdscr,FALSE),keypad(stdscr,TRUE);
40 Before a curses program is run, the tab stops of the terminal should be
43 set and its initialization strings, if defined, must be output. This
44 can be done by executing the tput init command after the shell environ‐
45 ment variable TERM has been exported. (See terminfo(4) for further
46 details.)
47 The curses library permits manipulation of data structures, called win‐
50 dows, which can be thought of as two-dimensional arrays of characters
51 representing all or part of a CRT screen. A default window called std‐
52 scr, which is the size of the terminal screen, is supplied. Others may
53 be created with newwin(3CURSES).
54 Windows are referred to by variables declared as WINDOW *. These data
57 structures are manipulated with routines described on 3CURSES pages
58 (whose names begin "curs_"). Among which the most basic routines are
59 move(3CURSES) and addch(3CURSES). More general versions of these rou‐
60 tines are included with names beginning with w, allowing the user to
61 specify a window. The routines not beginning with w affect stdscr.
62 After using routines to manipulate a window, refresh(3CURSES) is
65 called, telling curses to make the user's CRT screen look like stdscr.
66 The characters in a window are actually of type chtype, (character and
67 attribute data) so that other information about the character may also
68 be stored with each character.
69 Special windows called pads may also be manipulated. These are windows
72 which are not constrained to the size of the screen and whose contents
73 need not be completely displayed. See curs_pad(3CURSES) for more infor‐
74 mation.
75 In addition to drawing characters on the screen, video attributes and
78 colors may be included, causing the characters to show up in such modes
79 as underlined, in reverse video, or in color on terminals that support
80 such display enhancements. Line drawing characters may be specified to
81 be output. On input, curses is also able to translate arrow and func‐
82 tion keys that transmit escape sequences into single values. The video
83 attributes, line drawing characters, and input values use names,
84 defined in <curses.h>, such as A_REVERSE, ACS_HLINE, and KEY_LEFT.
85 If the environment variables LINES and COLUMNS are set, or if the pro‐
88 gram is executing in a window environment, line and column information
89 in the environment will override information read by terminfo. This
90 would effect a program running in an AT&T 630 layer, for example, where
91 the size of a screen is changeable.
92 If the environment variable TERMINFO is defined, any program using
95 curses checks for a local terminal definition before checking in the
96 standard place. For example, if TERM is set to att4424, then the com‐
97 piled terminal definition is found in
98 /usr/share/lib/terminfo/a/att4424.
101 (The `a' is copied from the first letter of att4424 to avoid creation
104 of huge directories.) However, if TERMINFO is set to $HOME/myterms,
105 curses first checks
106 $HOME/myterms/a/att4424,
109 and if that fails, it then checks
112 /usr/share/lib/terminfo/a/att4424.
115 This is useful for developing experimental definitions or when write
118 permission in /usr/share/lib/terminfo is not available.
119 The integer variables LINES and COLS are defined in <curses.h> and will
122 be filled in by initscr with the size of the screen. The constants TRUE
123 and FALSE have the values 1 and 0, respectively.
124 The curses routines also define the WINDOW * variable curscr which is
127 used for certain low-level operations like clearing and redrawing a
128 screen containing garbage. The curscr can be used in only a few rou‐
129 tines.
130 International Functions
132 The number of bytes and the number of columns to hold a character from
133 the supplementary character set is locale-specific (locale category
134 LC_CTYPE) and can be specified in the character class table.
135 For editing, operating at the character level is entirely appropriate.
138 For screen formatting, arbitrary movement of characters on screen is
139 not desirable.
140 Overwriting characters (addch, for example) operates on a screen level.
143 Overwriting a character by a character that requires a different number
144 of columns may produce orphaned columns. These orphaned columns are
145 filled with background characters.
146 Inserting characters (insch, for example) operates on a character level
149 (that is, at the character boundaries). The specified character is
150 inserted right before the character, regardless of which column of a
151 character the cursor points to. Before insertion, the cursor position
152 is adjusted to the first column of the character.
153 As with inserting characters, deleting characters (delch, for example)
156 operates on a character level (that is, at the character boundaries).
157 The character at the cursor is deleted whichever column of the charac‐
158 ter the cursor points to. Before deletion, the cursor position is
159 adjusted to the first column of the character.
160 A multi-column character cannot be put on the last column of a line.
163 When such attempts are made, the last column is set to the background
164 character. In addition, when such an operation creates orphaned col‐
165 umns, the orphaned columns are filled with background characters.
166 Overlapping and overwriting a window follows the operation of overwrit‐
169 ing characters around its edge. The orphaned columns, if any, are han‐
170 dled as in the character operations.
171 The cursor is allowed to be placed anywhere in a window. If the inser‐
174 tion or deletion is made when the cursor points to the second or later
175 column position of a character that holds multiple columns, the cursor
176 is adjusted to the first column of the character before the insertion
177 or deletion.
178 Routine and Argument Names
180 Many curses routines have two or more versions. The routines prefixed
181 with w require a window argument. The routines prefixed with p require
182 a pad argument. Those without a prefix generally use stdscr.
183 The routines prefixed with mv require an x and y coordinate to move to
186 before performing the appropriate action. The mv routines imply a call
187 to move(3CURSES) before the call to the other routine. The coordinate y
188 always refers to the row (of the window), and x always refers to the
189 column. The upper left-hand corner is always (0,0), not (1,1).
190 The routines prefixed with mvw take both a window argument and x and y
193 coordinates. The window argument is always specified before the coordi‐
194 nates.
195 In each case, win is the window affected, and pad is the pad affected;
198 win and pad are always pointers to type WINDOW
199 Option setting routines require a Boolean flag bf with the value TRUE
202 or FALSE; bf is always of type bool. The variables ch and attrs below
203 are always of type chtype. The types WINDOW, SCREEN, bool, and chtype
204 are defined in <curses.h>. The type TERMINAL is defined in <term.h>.
205 All other arguments are integers.
206 Routine Name Index
208 The following table lists each curses routine and the name of the man‐
209 ual page on which it is described.
210 curses Routine Name Manual Page Name
212 addch curs_addch(3CURSES)
215 addchnstr curs_addchstr(3CURSES)
218 addchstr curs_addchstr(3CURSES)
221 addnstr curs_addstr(3CURSES)
224 addnwstr curs_addwstr(3CURSES)
227 addstr curs_addstr(3CURSES)
230 addwch curs_addwch(3CURSES)
233 addwchnstr curs_addwchstr(3CURSES)
236 addwchstr curs_addwchstr(3CURSES)
239 addwstr curs_addwstr(3CURSES)
242 adjcurspos curs_alecompat(3CURSES)
245 attroff curs_attr(3CURSES)
248 attron curs_attr(3CURSES)
251 attrset curs_attr(3CURSES)
254 baudrate curs_termattrs(3CURSES)
257 beep curs_beep(3CURSES)
260 bkgd curs_bkgd(3CURSES)
263 bkgdset curs_bkgd(3CURSES)
266 border curs_border(3CURSES)
269 box curs_border(3CURSES)
272 can_change_color curs_color(3CURSES)
275 cbreak curs_inopts(3CURSES)
278 clear curs_clear(3CURSES)
281 clearok curs_outopts(3CURSES)
284 clrtobot curs_clear(3CURSES)
287 clrtoeol curs_clear(3CURSES)
290 color_content curs_color(3CURSES)
293 copywin curs_overlay(3CURSES)
296 curs_set curs_kernel(3CURSES)
299 def_prog_mode curs_kernel(3CURSES)
302 def_shell_mode curs_kernel(3CURSES)
305 del_curterm curs_terminfo(3CURSES)
308 delay_output curs_util(3CURSES)
311 delch curs_delch(3CURSES)
314 deleteln curs_deleteln(3CURSES)
317 delscreen curs_initscr(3CURSES)
320 delwin curs_window(3CURSES)
323 derwin curs_window(3CURSES)
326 doupdate curs_refresh(3CURSES)
329 dupwin curs_window(3CURSES)
332 echo curs_inopts(3CURSES)
335 echochar curs_addch(3CURSES)
338 echowchar curs_addwch(3CURSES)
341 endwin curs_initscr(3CURSES)
344 erase curs_clear(3CURSES)
347 erasechar curs_termattrs(3CURSES)
350 filter curs_util(3CURSES)
353 flash curs_beep(3CURSES)
356 flushinp curs_util(3CURSES)
359 getbegyx curs_getyx(3CURSES)
362 getch curs_getch(3CURSES)
365 getmaxyx curs_getyx(3CURSES)
368 getnwstr curs_getwstr(3CURSES)
371 getparyx curs_getyx(3CURSES)
374 getstr curs_getstr(3CURSES)
377 getsyx curs_kernel(3CURSES)
380 getwch curs_getwch(3CURSES)
383 getwin curs_util(3CURSES)
386 getwstr curs_getwstr(3CURSES)
389 getyx curs_getyx(3CURSES)
392 halfdelay curs_inopts(3CURSES)
395 has_colors curs_color(3CURSES)
398 has_ic curs_termattrs(3CURSES)
401 has_il curs_termattrs(3CURSES)
404 idcok curs_outopts(3CURSES)
407 idlok curs_outopts(3CURSES)
410 immedok curs_outopts(3CURSES)
413 inch curs_inch(3CURSES)
416 inchnstr curs_inchstr(3CURSES)
419 inchstr curs_inchstr(3CURSES)
422 init_color curs_color(3CURSES)
425 init_pair curs_color(3CURSES)
428 initscr curs_initscr(3CURSES)
431 innstr curs_instr(3CURSES)
434 innwstr curs_inwstr(3CURSES)
437 insch curs_insch(3CURSES)
440 insdelln curs_deleteln(3CURSES)
443 insertln curs_deleteln(3CURSES)
446 insnstr curs_insstr(3CURSES)
449 insnwstr curs_inswstr(3CURSES)
452 insstr curs_insstr(3CURSES)
455 instr curs_instr(3CURSES)
458 inswch curs_inswch(3CURSES)
461 inswstr curs_inswstr(3CURSES)
464 intrflush curs_inopts(3CURSES)
467 inwch curs_inwch(3CURSES)
470 inwchnstr curs_inwchstr(3CURSES)
473 inwchstr curs_inwchstr(3CURSES)
476 inwstr curs_inwstr(3CURSES)
479 is_linetouched curs_touch(3CURSES)
482 is_wintouched curs_touch(3CURSES)
485 isendwin curs_initscr(3CURSES)
488 keyname curs_util(3CURSES)
491 keypad curs_inopts(3CURSES)
494 killchar curs_termattrs(3CURSES)
497 leaveok curs_outopts(3CURSES)
500 longname curs_termattrs(3CURSES)
503 meta curs_inopts(3CURSES)
506 move curs_move(3CURSES)
509 movenextch curs_alecompat(3CURSES)
512 moveprevch curs_alecompat(3CURSES)
515 mvaddch curs_addch(3CURSES)
518 mvaddchnstr curs_addchstr(3CURSES)
521 mvaddchstr curs_addchstr(3CURSES)
524 mvaddnstr curs_addstr(3CURSES)
527 mvaddnwstr curs_addwstr(3CURSES)
530 mvaddstr curs_addstr(3CURSES)
533 mvaddwch curs_addwch(3CURSES)
536 mvaddwchnstr curs_addwchstr(3CURSES)
539 mvaddwchstr curs_addwchstr(3CURSES)
542 mvaddwstr curs_addwstr(3CURSES)
545 mvcur curs_terminfo(3CURSES)
548 mvdelch curs_delch(3CURSES)
551 mvderwin curs_window(3CURSES)
554 mvgetch curs_getch(3CURSES)
557 mvgetnwstr curs_getwstr(3CURSES)
560 mvgetstr curs_getstr(3CURSES)
563 mvgetwch curs_getwch(3CURSES)
566 mvgetwstr curs_getwstr(3CURSES)
569 mvinch curs_inch(3CURSES)
572 mvinchnstr curs_inchstr(3CURSES)
575 mvinchstr curs_inchstr(3CURSES)
578 mvinnstr curs_instr(3CURSES)
581 mvinnwstr curs_inwstr(3CURSES)
584 mvinsch curs_insch(3CURSES)
587 mvinsnstr curs_insstr(3CURSES)
590 mvinsnwstr curs_inswstr(3CURSES)
593 mvinsstr curs_insstr(3CURSES)
596 mvinstr curs_instr(3CURSES)
599 mvinswch curs_inswch(3CURSES)
602 mvinswstr curs_inswstr(3CURSES)
605 mvinwch curs_inwch(3CURSES)
608 mvinwchnstr curs_inwchstr(3CURSES)
611 mvinwchstr curs_inwchstr(3CURSES)
614 mvinwstr curs_inwstr(3CURSES)
617 mvprintw curs_printw(3CURSES)
620 mvscanw curs_scanw(3CURSES)
623 mvwaddch curs_addch(3CURSES)
626 mvwaddchnstr curs_addchstr(3CURSES)
629 mvwaddchstr curs_addchstr(3CURSES)
632 mvwaddnstr curs_addstr(3CURSES)
635 mvwaddnwstr curs_addwstr(3CURSES)
638 mvwaddstr curs_addstr(3CURSES)
641 mvwaddwch curs_addwch(3CURSES)
644 mvwaddwchnstr curs_addwchstr(3CURSES)
647 mvwaddwchstr curs_addwchstr(3CURSES)
650 mvwaddwstr curs_addwstr(3CURSES)
653 mvwdelch curs_delch(3CURSES)
656 mvwgetch curs_getch(3CURSES)
659 mvwgetnwstr curs_getwstr(3CURSES)
662 mvwgetstr curs_getstr(3CURSES)
665 mvwgetwch curs_getwch(3CURSES)
668 mvwgetwstr curs_getwstr(3CURSES)
671 mvwin curs_window(3CURSES)
674 mvwinch curs_inch(3CURSES)
677 mvwinchnstr curs_inchstr(3CURSES)
680 mvwinchstr curs_inchstr(3CURSES)
683 mvwinnstr curs_instr(3CURSES)
686 mvwinnwstr curs_inwstr(3CURSES)
689 mvwinsch curs_insch(3CURSES)
692 mvwinsnstr curs_insstr(3CURSES)
695 mvwinsstr curs_insstr(3CURSES)
698 mvwinstr curs_instr(3CURSES)
701 mvwinswch curs_inswch(3CURSES)
704 mvwinswstr curs_inswstr(3CURSES)
707 mvwinwch curs_inwch(3CURSES)
710 mvwinwchnstr curs_inwchstr(3CURSES)
713 mvwinwchstr curs_inwchstr(3CURSES)
716 mvwinwstr curs_inwstr(3CURSES)
719 mvwprintw curs_printw(3CURSES)
722 mvwscanw curs_scanw(3CURSES)
725 napms curs_kernel(3CURSES)
728 newpad curs_pad(3CURSES)
731 newterm curs_initscr(3CURSES)
734 newwin curs_window(3CURSES)
737 nl curs_outopts(3CURSES)
740 nocbreak curs_inopts(3CURSES)
743 nodelay curs_inopts(3CURSES)
746 noecho curs_inopts(3CURSES)
749 nonl curs_outopts(3CURSES)
752 noqiflush curs_inopts(3CURSES)
755 noraw curs_inopts(3CURSES)
758 notimeout curs_inopts(3CURSES)
761 overlay curs_overlay(3CURSES)
764 overwrite curs_overlay(3CURSES)
767 pair_content curs_color(3CURSES)
770 pechochar curs_pad(3CURSES)
773 pechowchar curs_pad(3CURSES)
776 pnoutrefresh curs_pad(3CURSES)
779 prefresh curs_pad(3CURSES)
782 printw curs_printw(3CURSES)
785 putp curs_terminfo(3CURSES)
788 putwin curs_util(3CURSES)
791 qiflush curs_inopts(3CURSES)
794 raw curs_inopts(3CURSES)
797 redrawwin curs_refresh(3CURSES)
800 refresh curs_refresh(3CURSES)
803 reset_prog_mode curs_kernel(3CURSES)
806 reset_shell_mode curs_kernel(3CURSES)
809 resetty curs_kernel(3CURSES)
812 restartterm curs_terminfo(3CURSES)
815 ripoffline curs_kernel(3CURSES)
818 savetty curs_kernel(3CURSES)
821 scanw curs_scanw(3CURSES)
824 scr_dump curs_scr_dump(3CURSES)
827 scr_init curs_scr_dump(3CURSES)
830 scr_restore curs_scr_dump(3CURSES)
833 scr_set curs_scr_dump(3CURSES)
836 scroll curs_scroll(3CURSES)
839 scrollok curs_outopts(3CURSES)
842 set_curterm curs_terminfo(3CURSES)
845 set_term curs_initscr(3CURSES)
848 setscrreg curs_outopts(3CURSES)
851 setsyx curs_kernel(3CURSES)
854 setterm curs_terminfo(3CURSES)
857 setupterm curs_terminfo(3CURSES)
860 slk_attroff curs_slk(3CURSES)
863 slk_attron curs_slk(3CURSES)
866 slk_attrset curs_slk(3CURSES)
869 slk_clear curs_slk(3CURSES)
872 slk_init curs_slk(3CURSES)
875 slk_label curs_slk(3CURSES)
878 slk_noutrefresh curs_slk(3CURSES)
881 slk_refresh curs_slk(3CURSES)
884 slk_restore curs_slk(3CURSES)
887 slk_set curs_slk(3CURSES)
890 slk_touch curs_slk(3CURSES)
893 srcl curs_scroll(3CURSES)
896 standend curs_attr(3CURSES)
899 standout curs_attr(3CURSES)
902 start_color curs_color(3CURSES)
905 subpad curs_pad(3CURSES)
908 subwin curs_window(3CURSES)
911 syncok curs_window(3CURSES)
914 termattrs curs_termattrs(3CURSES)
917 termname curs_termattrs(3CURSES)
920 tgetent curs_termcap(3CURSES)
923 tgetflag curs_termcap(3CURSES)
926 tgetnum curs_termcap(3CURSES)
929 tgetstr curs_termcap(3CURSES)
932 tgoto curs_termcap(3CURSES)
935 tigetflag curs_terminfo(3CURSES)
938 tigetnum curs_terminfo(3CURSES)
941 tigetstr curs_terminfo(3CURSES)
944 timeout curs_inopts(3CURSES)
947 touchline curs_touch(3CURSES)
950 touchwin curs_touch(3CURSES)
953 tparm curs_terminfo(3CURSES)
956 tputs curs_terminfo(3CURSES)
959 typeahead curs_inopts(3CURSES)
962 unctrl curs_util(3CURSES)
965 ungetch curs_getch(3CURSES)
968 ungetwch curs_getwch(3CURSES)
971 untouchwin curs_touch(3CURSES)
974 use_env curs_util(3CURSES)
977 vidattr curs_terminfo(3CURSES)
980 vidputs curs_terminfo(3CURSES)
983 vwprintw curs_printw(3CURSES)
986 vwscanw curs_scanw(3CURSES)
989 waddch curs_addch(3CURSES)
992 waddchnstr curs_addchstr(3CURSES)
995 waddchstr curs_addchstr(3CURSES)
998 waddnstr curs_addstr(3CURSES)
1001 waddnwstr curs_addwstr(3CURSES)
1004 waddstr curs_addstr(3CURSES)
1007 waddwch curs_addwch(3CURSES)
1010 waddwchnstr curs_addwchstr(3CURSES)
1013 waddwchstr curs_addwchstr(3CURSES)
1016 waddwstr curs_addwstr(3CURSES)
1019 wadjcurspos curs_alecompat(3CURSES)
1022 wattroff curs_attr(3CURSES)
1025 wattron curs_attr(3CURSES)
1028 wattrset curs_attr(3CURSES)
1031 wbkgd curs_bkgd(3CURSES)
1034 wbkgdset curs_bkgd(3CURSES)
1037 wborder curs_border(3CURSES)
1040 wclear curs_clear(3CURSES)
1043 wclrtobot curs_clear(3CURSES)
1046 wclrtoeol curs_clear(3CURSES)
1049 wcursyncup curs_window(3CURSES)
1052 wdelch curs_delch(3CURSES)
1055 wdeleteln curs_deleteln(3CURSES)
1058 wechochar curs_addch(3CURSES)
1061 wechowchar curs_addwch(3CURSES)
1064 werase curs_clear(3CURSES)
1067 wgetch curs_getch(3CURSES)
1070 wgetnstr curs_getstr(3CURSES)
1073 wgetnwstr curs_getwstr(3CURSES)
1076 wgetstr curs_getstr(3CURSES)
1079 wgetwch curs_getwch(3CURSES)
1082 wgetwstr curs_getwstr(3CURSES)
1085 whline curs_border(3CURSES)
1088 winch curs_inch(3CURSES)
1091 winchnstr curs_inchstr(3CURSES)
1094 winchstr curs_inchstr(3CURSES)
1097 winnstr curs_instr(3CURSES)
1100 winnwstr curs_inwstr(3CURSES)
1103 winsch curs_insch(3CURSES)
1106 winsdelln curs_deleteln(3CURSES)
1109 winsertln curs_deleteln(3CURSES)
1112 winsnstr curs_insstr(3CURSES)
1115 winsnwstr curs_inswstr(3CURSES)
1118 winsstr curs_insstr(3CURSES)
1121 winstr curs_instr(3CURSES)
1124 winswch curs_inswch(3CURSES)
1127 winswstr curs_inswstr(3CURSES)
1130 winwch curs_inwch(3CURSES)
1133 winwchnstr curs_inwchstr(3CURSES)
1136 winwchstr curs_inwchstr(3CURSES)
1139 winwstr curs_inwstr(3CURSES)
1142 wmove curs_move(3CURSES)
1145 wmovenextch curs_alecompat(3CURSES)
1148 wmoveprevch curs_alecompat(3CURSES)
1151 wnoutrefresh curs_refresh(3CURSES)
1154 wprintw curs_printw(3CURSES)
1157 wredrawln curs_refresh(3CURSES)
1160 wrefresh curs_refresh(3CURSES)
1163 wscanw curs_scanw(3CURSES)
1166 wscrl curs_scroll(3CURSES)
1169 wsetscrreg curs_outopts(3CURSES)
1172 wstandend curs_attr(3CURSES)
1175 wstandout curs_attr(3CURSES)
1178 wsyncdown curs_window(3CURSES)
1181 wsyncup curs_window(3CURSES)
1184 wtimeout curs_inopts(3CURSES)
1187 wtouchln curs_touch(3CURSES)
1190 wvline curs_border(3CURSES)
1193
1196 Routines that return an integer return ERR upon failure and an integer
1197 value other than ERR upon successful completion, unless otherwise noted
1198 in the routine descriptions.
1199 All macros return the value of the w version, except setscrreg(),
1202 wsetscrreg(), getyx(), getbegyx(), and getmaxyx(). The return values of
1203 setscrreg(), wsetscrreg(), getyx(), getbegyx(), and getmaxyx() are
1204 undefined (that is, these should not be used as the right-hand side of
1205 assignment statements).
1206 Routines that return pointers return NULL on error.
1209
1211 See attributes(5) for descriptions of the following attributes:
1212 ┌─────────────────────────────┬─────────────────────────────┐
1217 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
1218 ├─────────────────────────────┼─────────────────────────────┤
1219 │MT-Level │Unsafe │
1220 └─────────────────────────────┴─────────────────────────────┘
1221
1223 curses(3XCURSES), libcurses(3LIB), libcurses(3XCURSES), terminfo(4),
1224 attributes(5)
1225
1227 The header <curses.h> automatically includes the headers <stdio.h> and
1228 <unctrl.h>.
1229SunOS 5.11 23 Oct 2001 curses(3CURSES)