ncurses 4.2
[ncurses.git] / man / ncurses.3x
1 '\" t
2 .\" $Id: ncurses.3x,v 1.23 1998/02/15 02:05:44 tom Exp $
3 .TH ncurses 3X ""
4 .ds n 5
5 .ds d @DATADIR@/terminfo
6 .SH NAME
7 \fBncurses\fR - CRT screen handling and optimization package
8 .SH SYNOPSIS
9 \fB#include <curses.h>\fR
10 .br
11 .SH DESCRIPTION
12 The \fBcurses\fR library routines give the user a terminal-independent method
13 of updating character screens with reasonable optimization.  This
14 implementation is ``new curses'' (ncurses) and is the approved replacement for
15 4.4BSD classic curses, which has been discontinued.
16
17 The \fBncurses\fR routines emulate the \fBcurses\fR(3X) library of System V
18 Release 4 UNIX, and the XPG4 curses standard (XSI curses) but the \fBncurses\fR
19 library is freely redistributable in source form.  Differences from the SVr4
20 curses are summarized under the EXTENSIONS and BUGS sections below and
21 described in detail in the EXTENSIONS and BUGS sections of individual man
22 pages.
23
24 A program using these routines must be linked with the \fB-lncurses\fR option,
25 or (if it has been generated) with the debugging library \fB-lncurses_g\fR. 
26 (Your system integrator may also have installed these libraries under
27 the names \fB-lcurses\fR and \fB-lcurses_g\fR.)
28 The ncurses_g library generates trace logs (in a file called 'trace' in the
29 current directory) that describe curses actions.
30
31 The \fBncurses\fR package supports: overall screen, window and pad
32 manipulation; output to windows and pads; reading terminal input; control over
33 terminal and \fBcurses\fR input and output options; environment query
34 routines; color manipulation; use of soft label keys; terminfo capabilities;
35 and access to low-level terminal-manipulation routines.
36
37 To initialize the routines, the routine \fBinitscr\fR or \fBnewterm\fR
38 must be called before any of the other routines that deal with windows
39 and screens are used.  The routine \fBendwin\fR must be called before
40 exiting.  To get character-at-a-time input without echoing (most
41 interactive, screen oriented programs want this), the following
42 sequence should be used:
43
44       \fBinitscr(); cbreak(); noecho();\fR
45
46 Most programs would additionally use the sequence:
47
48       \fBnonl();\fR
49       \fBintrflush(stdscr, FALSE);\fR
50       \fBkeypad(stdscr, TRUE);\fR
51
52 Before a \fBcurses\fR program is run, the tab stops of the terminal
53 should be set and its initialization strings, if defined, must be
54 output.  This can be done by executing the \fBtput init\fR command
55 after the shell environment variable \fBTERM\fR has been exported.
56 \fBtset(1)\fR is usually responsible for doing this.
57 [See \fBterminfo\fR(\*n) for further details.]
58
59 The \fBcurses\fR library permits manipulation of data structures,
60 called \fIwindows\fR, which can be thought of as two-dimensional
61 arrays of characters representing all or part of a CRT screen.  A
62 default window called \fBstdscr\fR, which is the size of the terminal
63 screen, is supplied.  Others may be created with \fBnewwin\fR.
64
65 Note that \fBcurses\fR does not handle overlapping windows, that's done by
66 the \fBpanel\fR(3X) library. This means that you can either use
67 \fBstdscr\fR or divide the screen into tiled windows and not using
68 \fBstdscr\fR at all. Mixing the two will result in unpredictable, and
69 undesired, effects.
70
71 Windows are referred to by variables declared as \fBWINDOW *\fR.
72 These data structures are manipulated with routines described here and
73 elsewhere in the \fBncurses\fR manual pages.  Among which the most basic
74 routines are \fBmove\fR and \fBaddch\fR.  More general versions of
75 these routines are included with names beginning with \fBw\fR,
76 allowing the user to specify a window.  The routines not beginning
77 with \fBw\fR affect \fBstdscr\fR.)
78
79 After using routines to manipulate a window, \fBrefresh\fR is called,
80 telling \fBcurses\fR to make the user's CRT screen look like
81 \fBstdscr\fR.  The characters in a window are actually of type
82 \fBchtype\fR, (character and attribute data) so that other information
83 about the character may also be stored with each character.
84
85 Special windows called \fIpads\fR may also be manipulated.  These are windows
86 which are not constrained to the size of the screen and whose contents need not
87 be completely displayed.  See \fBcurs_pad\fR(3X) for more information.
88
89 In addition to drawing characters on the screen, video attributes and colors
90 may be supported, causing the characters to show up in such modes as
91 underlined, in reverse video, or in color on terminals that support such
92 display enhancements.  Line drawing characters may be specified to be output.
93 On input, \fBcurses\fR is also able to translate arrow and function keys that
94 transmit escape sequences into single values.  The video attributes, line
95 drawing characters, and input values use names, defined in \fB<curses.h>\fR,
96 such as \fBA_REVERSE\fR, \fBACS_HLINE\fR, and \fBKEY_LEFT\fR.
97
98 If the environment variables \fBLINES\fR and \fBCOLUMNS\fR are set, or if the
99 program is executing in a window environment, line and column information in
100 the environment will override information read by \fIterminfo\fR.  This would
101 effect a program running in an AT&T 630 layer, for example, where the size of a
102 screen is changeable.
103
104 If the environment variable \fBTERMINFO\fR is defined, any program using
105 \fBcurses\fR checks for a local terminal definition before checking in the
106 standard place.  For example, if \fBTERM\fR is set to \fBatt4424\fR, then the
107 compiled terminal definition is found in
108
109       \fB\*d/a/att4424\fR.
110
111 (The \fBa\fR is copied from the first letter of \fBatt4424\fR to avoid
112 creation of huge directories.)  However, if \fBTERMINFO\fR is set to
113 \fB$HOME/myterms\fR, \fBcurses\fR first checks
114
115       \fB$HOME/myterms/a/att4424\fR,
116
117 and if that fails, it then checks
118
119       \fB\*d/a/att4424\fR.
120
121 This is useful for developing experimental definitions or when write
122 permission in \fB\*d\fR is not available.
123
124 The integer variables \fBLINES\fR and \fBCOLS\fR are defined in
125 \fB<curses.h>\fR and will be filled in by \fBinitscr\fR with the size of the
126 screen.  The constants \fBTRUE\fR and \fBFALSE\fR have the values \fB1\fR and
127 \fB0\fR, respectively.
128
129 The \fBcurses\fR routines also define the \fBWINDOW *\fR variable \fBcurscr\fR
130 which is used for certain low-level operations like clearing and redrawing a
131 screen containing garbage.  The \fBcurscr\fR can be used in only a few
132 routines.
133
134 .SS Routine and Argument Names
135 Many \fBcurses\fR routines have two or more versions.  The routines prefixed
136 with \fBw\fR require a window argument.  The routines prefixed with \fBp\fR
137 require a pad argument.  Those without a prefix generally use \fBstdscr\fR.
138
139 The routines prefixed with \fBmv\fR require a \fIy\fR and \fIx\fR
140 coordinate to move to before performing the appropriate action.  The
141 \fBmv\fR routines imply a call to \fBmove\fR before the call to the
142 other routine.  The coordinate \fIy\fR always refers to the row (of
143 the window), and \fIx\fR always refers to the column.  The upper
144 left-hand corner is always (0,0), not (1,1).
145
146 The routines prefixed with \fBmvw\fR take both a window argument and
147 \fIx\fR and \fIy\fR coordinates.  The window argument is always
148 specified before the coordinates.
149
150 In each case, \fIwin\fR is the window affected, and \fIpad\fR is the
151 pad affected; \fIwin\fR and \fIpad\fR are always pointers to type
152 \fBWINDOW\fR.
153
154 Option setting routines require a Boolean flag \fIbf\fR with the value
155 \fBTRUE\fR or \fBFALSE\fR; \fIbf\fR is always of type \fBbool\fR.  The
156 variables \fIch\fR and \fIattrs\fR below are always of type
157 \fBchtype\fR.  The types \fBWINDOW\fR, \fBSCREEN\fR, \fBbool\fR, and
158 \fBchtype\fR are defined in \fB<curses.h>\fR.  The type \fBTERMINAL\fR
159 is defined in \fB<term.h>\fR.  All other arguments are integers.
160
161 .SS Routine Name Index
162 The following table lists each \fBcurses\fR routine and the name of
163 the manual page on which it is described.  Routines flagged with `*'
164 are ncurses-specific, not described by XPG4 or present in SVr4.
165
166 .TS
167 center tab(/);
168 l l
169 l l .
170 \fBcurses\fR Routine Name/Manual Page Name
171 =
172 addch/\fBcurs_addch\fR(3X)
173 addchnstr/\fBcurs_addchstr\fR(3X)
174 addchstr/\fBcurs_addchstr\fR(3X)
175 addnstr/\fBcurs_addstr\fR(3X)
176 addstr/\fBcurs_addstr\fR(3X)
177 attroff/\fBcurs_attr\fR(3X)
178 attron/\fBcurs_attr\fR(3X)
179 attrset/\fBcurs_attr\fR(3X)
180 baudrate/\fBcurs_termattrs\fR(3X)
181 beep/\fBcurs_beep\fR(3X)
182 bkgd/\fBcurs_bkgd\fR(3X)
183 bkgdset/\fBcurs_bkgd\fR(3X)
184 border/\fBcurs_border\fR(3X)
185 box/\fBcurs_border\fR(3X)
186 can_change_color/\fBcurs_color\fR(3X)
187 cbreak/\fBcurs_inopts\fR(3X)
188 clear/\fBcurs_clear\fR(3X)
189 clearok/\fBcurs_outopts\fR(3X)
190 clrtobot/\fBcurs_clear\fR(3X)
191 clrtoeol/\fBcurs_clear\fR(3X)
192 color_content/\fBcurs_color\fR(3X)
193 copywin/\fBcurs_overlay\fR(3X)
194 curs_set/\fBcurs_kernel\fR(3X)
195 def_prog_mode/\fBcurs_kernel\fR(3X)
196 def_shell_mode/\fBcurs_kernel\fR(3X)
197 define_key/\fBdefine_key\fR(3X)*
198 del_curterm/\fBcurs_terminfo\fR(3X)
199 delay_output/\fBcurs_util\fR(3X)
200 delch/\fBcurs_delch\fR(3X)
201 deleteln/\fBcurs_deleteln\fR(3X)
202 delscreen/\fBcurs_initscr\fR(3X)
203 delwin/\fBcurs_window\fR(3X)
204 derwin/\fBcurs_window\fR(3X)
205 doupdate/\fBcurs_refresh\fR(3X)
206 dupwin/\fBcurs_window\fR(3X)
207 echo/\fBcurs_inopts\fR(3X)
208 echochar/\fBcurs_addch\fR(3X)
209 endwin/\fBcurs_initscr\fR(3X)
210 erase/\fBcurs_clear\fR(3X)
211 erasechar/\fBcurs_termattrs\fR(3X)
212 filter/\fBcurs_util\fR(3X)
213 flash/\fBcurs_beep\fR(3X)
214 flushinp/\fBcurs_util\fR(3X)
215 getbegyx/\fBcurs_getyx\fR(3X)
216 getch/\fBcurs_getch\fR(3X)
217 getmaxyx/\fBcurs_getyx\fR(3X)
218 getmouse/\fBcurs_mouse\fR(3X)*
219 getparyx/\fBcurs_getyx\fR(3X)
220 getstr/\fBcurs_getstr\fR(3X)
221 getsyx/\fBcurs_kernel\fR(3X)
222 getwin/\fBcurs_util\fR(3X)
223 getyx/\fBcurs_getyx\fR(3X)
224 halfdelay/\fBcurs_inopts\fR(3X)
225 has_colors/\fBcurs_color\fR(3X)
226 has_ic/\fBcurs_termattrs\fR(3X)
227 has_il/\fBcurs_termattrs\fR(3X)
228 has_key/\fBcurs_getch\fR(3X)*
229 hline/\fBcurs_border\fR(3X)
230 idcok/\fBcurs_outopts\fR(3X)
231 idlok/\fBcurs_outopts\fR(3X)
232 immedok/\fBcurs_outopts\fR(3X)
233 inch/\fBcurs_inch\fR(3X)
234 inchnstr/\fBcurs_inchstr\fR(3X)
235 inchstr/\fBcurs_inchstr\fR(3X)
236 init_color/\fBcurs_color\fR(3X)
237 init_pair/\fBcurs_color\fR(3X)
238 initscr/\fBcurs_initscr\fR(3X)
239 innstr/\fBcurs_instr\fR(3X)
240 insch/\fBcurs_insch\fR(3X)
241 insdelln/\fBcurs_deleteln\fR(3X)
242 insertln/\fBcurs_deleteln\fR(3X)
243 insnstr/\fBcurs_insstr\fR(3X)
244 insstr/\fBcurs_insstr\fR(3X)
245 instr/\fBcurs_instr\fR(3X)
246 intrflush/\fBcurs_inopts\fR(3X)
247 is_linetouched/\fBcurs_touch\fR(3X)
248 is_wintouched/\fBcurs_touch\fR(3X)
249 isendwin/\fBcurs_initscr\fR(3X)
250 keyname/\fBcurs_util\fR(3X)
251 keyok/\fBkeyok\fR(3X)*
252 keypad/\fBcurs_inopts\fR(3X)
253 killchar/\fBcurs_termattrs\fR(3X)
254 leaveok/\fBcurs_outopts\fR(3X)
255 longname/\fBcurs_termattrs\fR(3X)
256 mcprint/\fBcurs_print\fR(3X)*
257 meta/\fBcurs_inopts\fR(3X)
258 mouseinterval/\fBcurs_mouse\fR(3X)*
259 mousemask/\fBcurs_mouse\fR(3X)*
260 move/\fBcurs_move\fR(3X)
261 mvaddch/\fBcurs_addch\fR(3X)
262 mvaddchnstr/\fBcurs_addchstr\fR(3X)
263 mvaddchstr/\fBcurs_addchstr\fR(3X)
264 mvaddnstr/\fBcurs_addstr\fR(3X)
265 mvaddstr/\fBcurs_addstr\fR(3X)
266 mvcur/\fBcurs_terminfo\fR(3X)
267 mvdelch/\fBcurs_delch\fR(3X)
268 mvderwin/\fBcurs_window\fR(3X)
269 mvgetch/\fBcurs_getch\fR(3X)
270 mvgetstr/\fBcurs_getstr\fR(3X)
271 mvinch/\fBcurs_inch\fR(3X)
272 mvinchnstr/\fBcurs_inchstr\fR(3X)
273 mvinchstr/\fBcurs_inchstr\fR(3X)
274 mvinnstr/\fBcurs_instr\fR(3X)
275 mvinsch/\fBcurs_insch\fR(3X)
276 mvinsnstr/\fBcurs_insstr\fR(3X)
277 mvinsstr/\fBcurs_insstr\fR(3X)
278 mvinstr/\fBcurs_instr\fR(3X)
279 mvprintw/\fBcurs_printw\fR(3X)
280 mvscanw/\fBcurs_scanw\fR(3X)
281 mvwaddch/\fBcurs_addch\fR(3X)
282 mvwaddchnstr/\fBcurs_addchstr\fR(3X)
283 mvwaddchstr/\fBcurs_addchstr\fR(3X)
284 mvwaddnstr/\fBcurs_addstr\fR(3X)
285 mvwaddstr/\fBcurs_addstr\fR(3X)
286 mvwdelch/\fBcurs_delch\fR(3X)
287 mvwgetch/\fBcurs_getch\fR(3X)
288 mvwgetstr/\fBcurs_getstr\fR(3X)
289 mvwin/\fBcurs_window\fR(3X)
290 mvwinch/\fBcurs_inch\fR(3X)
291 mvwinchnstr/\fBcurs_inchstr\fR(3X)
292 mvwinchstr/\fBcurs_inchstr\fR(3X)
293 mvwinnstr/\fBcurs_instr\fR(3X)
294 mvwinsch/\fBcurs_insch\fR(3X)
295 mvwinsnstr/\fBcurs_insstr\fR(3X)
296 mvwinsstr/\fBcurs_insstr\fR(3X)
297 mvwinstr/\fBcurs_instr\fR(3X)
298 mvwprintw/\fBcurs_printw\fR(3X)
299 mvwscanw/\fBcurs_scanw\fR(3X)
300 napms/\fBcurs_kernel\fR(3X)
301 newpad/\fBcurs_pad\fR(3X)
302 newterm/\fBcurs_initscr\fR(3X)
303 newwin/\fBcurs_window\fR(3X)
304 nl/\fBcurs_outopts\fR(3X)
305 nocbreak/\fBcurs_inopts\fR(3X)
306 nodelay/\fBcurs_inopts\fR(3X)
307 noecho/\fBcurs_inopts\fR(3X)
308 nonl/\fBcurs_outopts\fR(3X)
309 noqiflush/\fBcurs_inopts\fR(3X)
310 noraw/\fBcurs_inopts\fR(3X)
311 notimeout/\fBcurs_inopts\fR(3X)
312 overlay/\fBcurs_overlay\fR(3X)
313 overwrite/\fBcurs_overlay\fR(3X)
314 pair_content/\fBcurs_color\fR(3X)
315 pechochar/\fBcurs_pad\fR(3X)
316 pnoutrefresh/\fBcurs_pad\fR(3X)
317 prefresh/\fBcurs_pad\fR(3X)
318 printw/\fBcurs_printw\fR(3X)
319 putp/\fBcurs_terminfo\fR(3X)
320 putwin/\fBcurs_util\fR(3X)
321 qiflush/\fBcurs_inopts\fR(3X)
322 raw/\fBcurs_inopts\fR(3X)
323 redrawwin/\fBcurs_refresh\fR(3X)
324 refresh/\fBcurs_refresh\fR(3X)
325 reset_prog_mode/\fBcurs_kernel\fR(3X)
326 reset_shell_mode/\fBcurs_kernel\fR(3X)
327 resetty/\fBcurs_kernel\fR(3X)
328 resizeterm/\fBresizeterm\fR(3X)*
329 restartterm/\fBcurs_terminfo\fR(3X)
330 ripoffline/\fBcurs_kernel\fR(3X)
331 savetty/\fBcurs_kernel\fR(3X)
332 scanw/\fBcurs_scanw\fR(3X)
333 scr_dump/\fBcurs_scr_dump\fR(3X)
334 scr_init/\fBcurs_scr_dump\fR(3X)
335 scr_restore/\fBcurs_scr_dump\fR(3X)
336 scr_set/\fBcurs_scr_dump\fR(3X)
337 scrl/\fBcurs_scroll\fR(3X)
338 scroll/\fBcurs_scroll\fR(3X)
339 scrollok/\fBcurs_outopts\fR(3X)
340 set_curterm/\fBcurs_terminfo\fR(3X)
341 set_term/\fBcurs_initscr\fR(3X)
342 setscrreg/\fBcurs_outopts\fR(3X)
343 setsyx/\fBcurs_kernel\fR(3X)
344 setterm/\fBcurs_terminfo\fR(3X)
345 setupterm/\fBcurs_terminfo\fR(3X)
346 slk_attr/\fBcurs_slk\fR(3X)*
347 slk_attroff/\fBcurs_slk\fR(3X)
348 slk_attron/\fBcurs_slk\fR(3X)
349 slk_attrset/\fBcurs_slk\fR(3X)
350 slk_clear/\fBcurs_slk\fR(3X)
351 slk_init/\fBcurs_slk\fR(3X)
352 slk_label/\fBcurs_slk\fR(3X)
353 slk_noutrefresh/\fBcurs_slk\fR(3X)
354 slk_refresh/\fBcurs_slk\fR(3X)
355 slk_restore/\fBcurs_slk\fR(3X)
356 slk_set/\fBcurs_slk\fR(3X)
357 slk_touch/\fBcurs_slk\fR(3X)
358 standend/\fBcurs_attr\fR(3X)
359 standout/\fBcurs_attr\fR(3X)
360 start_color/\fBcurs_color\fR(3X)
361 subpad/\fBcurs_pad\fR(3X)
362 subwin/\fBcurs_window\fR(3X)
363 syncok/\fBcurs_window\fR(3X)
364 termattrs/\fBcurs_termattrs\fR(3X)
365 termname/\fBcurs_termattrs\fR(3X)
366 tgetent/\fBcurs_termcap\fR(3X)
367 tgetflag/\fBcurs_termcap\fR(3X)
368 tgetnum/\fBcurs_termcap\fR(3X)
369 tgetstr/\fBcurs_termcap\fR(3X)
370 tgoto/\fBcurs_termcap\fR(3X)
371 tigetflag/\fBcurs_terminfo\fR(3X)
372 tigetnum/\fBcurs_terminfo\fR(3X)
373 tigetstr/\fBcurs_terminfo\fR(3X)
374 timeout/\fBcurs_inopts\fR(3X)
375 touchline/\fBcurs_touch\fR(3X)
376 touchwin/\fBcurs_touch\fR(3X)
377 tparm/\fBcurs_terminfo\fR(3X)
378 tputs/\fBcurs_termcap\fR(3X)
379 tputs/\fBcurs_terminfo\fR(3X)
380 typeahead/\fBcurs_inopts\fR(3X)
381 unctrl/\fBcurs_util\fR(3X)
382 ungetch/\fBcurs_getch\fR(3X)
383 ungetmouse/\fBcurs_mouse\fR(3X)*
384 untouchwin/\fBcurs_touch\fR(3X)
385 use_default_colors/\fBdft_fgbg\fR(3X)*
386 use_env/\fBcurs_util\fR(3X)
387 vidattr/\fBcurs_terminfo\fR(3X)
388 vidputs/\fBcurs_terminfo\fR(3X)
389 vline/\fBcurs_border\fR(3X)
390 vwprintw/\fBcurs_printw\fR(3X)
391 vwscanw/\fBcurs_scanw\fR(3X)
392 waddch/\fBcurs_addch\fR(3X)
393 waddchnstr/\fBcurs_addchstr\fR(3X)
394 waddchstr/\fBcurs_addchstr\fR(3X)
395 waddnstr/\fBcurs_addstr\fR(3X)
396 waddstr/\fBcurs_addstr\fR(3X)
397 wattroff/\fBcurs_attr\fR(3X)
398 wattron/\fBcurs_attr\fR(3X)
399 wattrset/\fBcurs_attr\fR(3X)
400 wbkgd/\fBcurs_bkgd\fR(3X)
401 wbkgdset/\fBcurs_bkgd\fR(3X)
402 wborder/\fBcurs_border\fR(3X)
403 wclear/\fBcurs_clear\fR(3X)
404 wclrtobot/\fBcurs_clear\fR(3X)
405 wclrtoeol/\fBcurs_clear\fR(3X)
406 wcursyncup/\fBcurs_window\fR(3X)
407 wdelch/\fBcurs_delch\fR(3X)
408 wdeleteln/\fBcurs_deleteln\fR(3X)
409 wechochar/\fBcurs_addch\fR(3X)
410 wenclose/\fBcurs_mouse\fR(3X)*
411 werase/\fBcurs_clear\fR(3X)
412 wgetch/\fBcurs_getch\fR(3X)
413 wgetnstr/\fBcurs_getstr\fR(3X)
414 wgetstr/\fBcurs_getstr\fR(3X)
415 whline/\fBcurs_border\fR(3X)
416 winch/\fBcurs_inch\fR(3X)
417 winchnstr/\fBcurs_inchstr\fR(3X)
418 winchstr/\fBcurs_inchstr\fR(3X)
419 winnstr/\fBcurs_instr\fR(3X)
420 winsch/\fBcurs_insch\fR(3X)
421 winsdelln/\fBcurs_deleteln\fR(3X)
422 winsertln/\fBcurs_deleteln\fR(3X)
423 winsnstr/\fBcurs_insstr\fR(3X)
424 winsstr/\fBcurs_insstr\fR(3X)
425 winstr/\fBcurs_instr\fR(3X)
426 wmove/\fBcurs_move\fR(3X)
427 wnoutrefresh/\fBcurs_refresh\fR(3X)
428 wprintw/\fBcurs_printw\fR(3X)
429 wredrawln/\fBcurs_refresh\fR(3X)
430 wrefresh/\fBcurs_refresh\fR(3X)
431 wresize/\fBwresize\fR(3X)*
432 wscanw/\fBcurs_scanw\fR(3X)
433 wscrl/\fBcurs_scroll\fR(3X)
434 wsetscrreg/\fBcurs_outopts\fR(3X)
435 wstandend/\fBcurs_attr\fR(3X)
436 wstandout/\fBcurs_attr\fR(3X)
437 wsyncdown/\fBcurs_window\fR(3X)
438 wsyncup/\fBcurs_window\fR(3X)
439 wtimeout/\fBcurs_inopts\fR(3X)
440 wtouchln/\fBcurs_touch\fR(3X)
441 wvline/\fBcurs_border\fR(3X)
442 .TE
443 .SH RETURN VALUE
444 Routines that return an integer return \fBERR\fR upon failure and an
445 integer value other than \fBERR\fR upon successful completion, unless
446 otherwise noted in the routine descriptions.
447
448 All macros return the value of the \fBw\fR version, except \fBsetscrreg\fR,
449 \fBwsetscrreg\fR, \fBgetyx\fR, \fBgetbegyx\fR, \fBgetmaxyx\fR.  The return
450 values of \fBsetscrreg\fR, \fBwsetscrreg\fR, \fBgetyx\fR, \fBgetbegyx\fR, and
451 \fBgetmaxyx\fR are undefined (\fIi\fR.\fIe\fR., these should not be used as the
452 right-hand side of assignment statements).
453
454 Routines that return pointers return \fBNULL\fR on error.
455 .SH SEE ALSO
456 \fBterminfo\fR(\*n) and 3X pages whose names begin "curs_" for detailed routine
457 descriptions.
458 .SH EXTENSIONS
459 The \fBcurses\fR library can be compiled with an option (\fB-DTERMCAP_FILE\fR)
460 that falls back to the old-style /etc/termcap file if the terminal setup code
461 cannot find a terminfo entry corresponding to \fBTERM\fR.  Use of this feature
462 is not recommended, as it essentially includes an entire termcap compiler in
463 the \fBcurses\fR startup code, at significant cost in core and startup cycles.
464
465 Compiling with \fB-DTERMCAP_FILE\fR changes the library's initialization
466 sequence in a way intended to mimic the behavior of 4.4BSD curses.  If there is
467 no local or system terminfo entry matching \fBTERM\fR, then the library looks
468 for termcap entries in the following places: (1) if \fBTERMINFO\fR is
469 undefined, in the file named by \fBTERMCAP_FILE\fR; (2) if \fBTERMINFO\fR is
470 defined and begins with a slash, it is interpreted as the name of a termcap
471 file to search for \fBTERM\fR; (3) otherwise, if \fBTERMINFO\fR has a leading
472 string that looks like a terminal entry name list, and it matches \fBTERM\fR,
473 the contents of \fBTERMINFO\fR is interpreted as a termcap; (4) if
474 \fBTERMINFO\fR looks like a termcap but doesn't match \fBTERM\fR, the termcap
475 file is searched for among the colon-separated paths in the environment
476 variable \fBTERMPATHS\fR if that is defined, and in ~/.termcap and the file
477 value of \fBTERMCAP_FILE\fR otherwise.
478
479 Versions of \fBcurses\fR compiled on PC clones support display of the PC ROM
480 characters (including ROM characters 0-31, which stock SVr4 curses cannot
481 display). See the EXTENSIONS sections of \fBcurs_addch\fR(3X) and
482 \fBcurs_attr\fR(3X).
483
484 The \fBcurses\fR library includes facilities for capturing mouse events on
485 certain terminals (including xterm). See the \fBcurs_mouse\fR(3X)
486 manual page for details.
487
488 The \fBcurses\fR library includes a function for directing application output
489 to a printer attached to the terminal device.  See the \fBcurs_print\fR(3X)
490 manual page for details.
491 .SH PORTABILITY
492 The \fBcurses\fR library is intended to be BASE-level conformant with the XSI
493 Curses standard.  Certain portions of the EXTENDED XSI Curses functionality
494 (including color support) are supported.  The following EXTENDED XSI Curses
495 calls in support of wide (multibyte) characters are not yet implemented:
496 \fBaddnwstr\fB,
497 \fBaddwstr\fB,
498 \fBmvaddnwstr\fB,
499 \fBmvwaddnwstr\fB,
500 \fBmvaddwstr\fB,
501 \fBwaddnwstr\fB,
502 \fBwaddwstr\fB,
503 \fBadd_wch\fB,
504 \fBwadd_wch\fB,
505 \fBmvadd_wch\fB,
506 \fBmvwadd_wch\fB,
507 \fBadd_wchnstr\fB,
508 \fBadd_wchstr\fB,
509 \fBwadd_wchnstr\fB,
510 \fBwadd_wchstr\fB,
511 \fBmvadd_wchnstr\fB,
512 \fBmvadd_wchstr\fB,
513 \fBmvwadd_wchnstr\fB,
514 \fBmvwadd_wchstr\fB,
515 \fBbkgrndset\fB,
516 \fBbkgrnd\fB,
517 \fBgetbkgrnd\fB,
518 \fBwbkgrnd\fB,
519 \fBwbkgrndset\fB,
520 \fBwgetbkgrnd\fB,
521 \fBborder_set\fB,
522 \fBwborder_set\fB,
523 \fBbox_set\fB,
524 \fBhline_set\fB,
525 \fBmvhline_set\fB,
526 \fBmvvline_set\fB,
527 \fBmvwhline_set\fB,
528 \fBmvwvline_set\fB,
529 \fBwhline_set\fB,
530 \fBvhline_set\fB,
531 \fBwvline_set\fB,
532 \fBecho_wchar\fB,
533 \fBwecho_wchar\fB,
534 \fBerasewchar\fB,
535 \fBkillwchar\fB,
536 \fBget_wch\fB,
537 \fBmvget_wch\fB,
538 \fBmvwget_ch\fB,
539 \fBwget_wch\fB,
540 \fBgetwchtype\fB,
541 \fBget_wstr\fB,
542 \fBgetn_wstr\fB,
543 \fBwget_wstr\fB,
544 \fBwgetn_wstr\fB,
545 \fBmvget_wstr\fB,
546 \fBmvgetn_wstr\fB,
547 \fBmvwget_wstr\fB,
548 \fBmvwgetn_wstr\fB,
549 \fBinnwstr\fB,
550 \fBinwstr\fB,
551 \fBwinnwstr\fB,
552 \fBwinwstr\fB,
553 \fBmvinnwstr\fB,
554 \fBmvinwstr\fB,
555 \fBmvwinnwstr\fB,
556 \fBmvwinwstr\fB,
557 \fBins_nwstr\fB,
558 \fBins_wstr\fB,
559 \fBmvins_nwstr\fB,
560 \fBmvins_wstr\fB,
561 \fBmvwins_nwstr\fB,
562 \fBmvwins_wstr\fB,
563 \fBwins_nwstr\fB,
564 \fBwins_wstr\fB,
565 \fBins_wch\fB,
566 \fBwins_wch\fB,
567 \fBmvins_wch\fB,
568 \fBmvwins_wch\fB,
569 \fBin_wch\fB,
570 \fBwin_wch\fB,
571 \fBmvin_wch\fB,
572 \fBmvwin_wch\fB,
573 \fBinwchstr\fB,
574 \fBinwchnstr\fB,
575 \fBwinwchstr\fB,
576 \fBwinwchnstr\fB,
577 \fBmvinwchstr\fB,
578 \fBmvinwchnstr\fB,
579 \fBmvinwchstr\fB,
580 \fBmvwinwchnstr\fB.
581 .PP
582 A small number of local differences (that is, individual differences between
583 the XSI Curses and \fBcurses\fR calls) are described in \fBPORTABILITY\fR
584 sections of the library man pages.
585 .PP
586 The routine \fBhas_key\fR is not part of XPG4, nor is it present in SVr4.  See
587 the \fBcurs_getch\fR(3X) manual page for details.
588 .PP
589 The routine \fBslk_attr\fR is not part of XPG4, nor is it present in SVr4.  See
590 the \fBcurs_slk\fR(3X) manual page for details.
591 .PP
592 The routines \fBgetmouse\fR, \fBmousemask\fR, \fBungetmouse\fR,
593 \fBmouseinterval\fR, and \fBwenclose\fR relating to mouse interfacing are not
594 part of XPG4, nor are they present in SVr4.  See the \fBcurs_mouse\fR(3X)
595 manual page for details.
596 .PP
597 The routine \fBmcprint\fR was not present in any previous curses
598 implementation.  See the \fBcurs_print\fR(3X) manual page for details.
599 .PP
600 The routine \fBwresize\fR is not part of XPG4, nor is it present in SVr4.  See
601 the \fBwresize\fR(3X) manual page for details.
602 .PP
603 In historic curses versions, delays embedded in the capabilities \fBcr\fR,
604 \fBind\fR, \fBcub1\fR, \fBff\fR and \fBtab\fR activated corresponding delay
605 bits in the UNIX tty driver.  In this implementation, all padding is done by
606 NUL sends.  This method is slightly more expensive, but narrows the interface
607 to the UNIX kernel significantly and increases the package's portability
608 correspondingly.
609 .PP
610 In the XSI standard and SVr4 manual pages, many entry points have prototype
611 arguments of the for \fBchar *const\fR (or \fBcchar_t *const\fR, or \fBwchar_t
612 *const\fR, or \fBvoid *const\fR).  Depending on one's interpretation of the
613 ANSI C standard (see section 3.5.4.1), these declarations are either (a)
614 meaningless, or (b) meaningless and illegal.  The declaration \fBconst char
615 *x\fR is a modifiable pointer to unmodifiable data, but \fBchar *const x\fR' is
616 an unmodifiable pointer to modifiable data.  Given that C passes arguments by
617 value, \fB<type> *const\fR as a formal type is at best dubious.  Some compilers
618 choke on the prototypes.  Therefore, in this implementation, they have been
619 changed to \fBconst <type> *\fR globally.
620 .SH NOTES
621 The header file \fB<curses.h>\fR automatically includes the header files
622 \fB<stdio.h>\fR and \fB<unctrl.h>\fR.
623
624 If standard output from a \fBcurses\fR program is re-directed to something
625 which is not a tty, screen updates will be directed to standard error.  This
626 was an undocumented feature of AT&T System V Release 3 curses.
627 .SH AUTHORS
628 Zeyd M. Ben-Halim, Eric S. Raymond.  Descends from the original pcurses
629 by Pavel Curtis.
630 .\"#
631 .\"# The following sets edit modes for GNU EMACS
632 .\"# Local Variables:
633 .\"# mode:nroff
634 .\"# fill-column:79
635 .\"# End: