'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2003,2004 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2006,2007 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: ncurses.3x,v 1.70 2004/01/11 01:45:54 tom Exp $
+.\" $Id: ncurses.3x,v 1.86 2007/04/07 23:08:08 tom Exp $
.hy 0
.TH ncurses 3X ""
.ds n 5
of updating character screens with reasonable optimization. This
implementation is ``new curses'' (ncurses) and is the approved replacement for
4.4BSD classic curses, which has been discontinued.
+This describes \fBncurses\fR
+version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
.PP
The \fBncurses\fR routines emulate the \fBcurses\fR(3X) library of System V
Release 4 UNIX, and the XPG4 curses standard (XSI curses) but the \fBncurses\fR
library is freely redistributable in source form. Differences from the SVr4
-curses are summarized under the EXTENSIONS and BUGS sections below and
-described in detail in the EXTENSIONS and BUGS sections of individual man
-pages.
+curses are summarized under the \fBEXTENSIONS\fP and \fBPORTABILITY\fP sections below and
+described in detail in the respective \fBEXTENSIONS\fP, \fBPORTABILITY\fP and \fBBUGS\fP sections
+of individual man pages.
.PP
A program using these routines must be linked with the \fB-lncurses\fR option,
or (if it has been generated) with the debugging library \fB-lncurses_g\fR.
the names \fB-lcurses\fR and \fB-lcurses_g\fR.)
The ncurses_g library generates trace logs (in a file called 'trace' in the
current directory) that describe curses actions.
+See also the section on \fBALTERNATE CONFIGURATIONS\fP.
.PP
The \fBncurses\fR package supports: overall screen, window and pad
manipulation; output to windows and pads; reading terminal input; control over
.PP
Windows are referred to by variables declared as \fBWINDOW *\fR.
These data structures are manipulated with routines described here and
-elsewhere in the \fBncurses\fR manual pages. Among which the most basic
+elsewhere in the \fBncurses\fR manual pages. Among those, the most basic
routines are \fBmove\fR and \fBaddch\fR. More general versions of
these routines are included with names beginning with \fBw\fR,
allowing the user to specify a window. The routines not beginning
-with \fBw\fR affect \fBstdscr\fR.)
+with \fBw\fR affect \fBstdscr\fR.
.PP
After using routines to manipulate a window, \fBrefresh\fR is called,
telling \fBcurses\fR to make the user's CRT screen look like
flushinp/\fBcurs_util\fR(3X)
get_wch/\fBcurs_get_wch\fR(3X)
get_wstr/\fBcurs_get_wstr\fR(3X)
+getattrs/\fBcurs_attr\fR(3X)
+getbegx/\fBcurs_legacy\fR(3X)*
+getbegy/\fBcurs_legacy\fR(3X)*
getbegyx/\fBcurs_getyx\fR(3X)
getbkgd/\fBcurs_bkgd\fR(3X)
getbkgrnd/\fBcurs_bkgrnd\fR(3X)
getcchar/\fBcurs_getcchar\fR(3X)
getch/\fBcurs_getch\fR(3X)
+getcurx/\fBcurs_legacy\fR(3X)*
+getcury/\fBcurs_legacy\fR(3X)*
+getmaxx/\fBcurs_legacy\fR(3X)*
+getmaxy/\fBcurs_legacy\fR(3X)*
getmaxyx/\fBcurs_getyx\fR(3X)
getmouse/\fBcurs_mouse\fR(3X)*
getn_wstr/\fBcurs_get_wstr\fR(3X)
getnstr/\fBcurs_getstr\fR(3X)
+getparx/\fBcurs_legacy\fR(3X)*
+getpary/\fBcurs_legacy\fR(3X)*
getparyx/\fBcurs_getyx\fR(3X)
getstr/\fBcurs_getstr\fR(3X)
getsyx/\fBcurs_kernel\fR(3X)
instr/\fBcurs_instr\fR(3X)
intrflush/\fBcurs_inopts\fR(3X)
inwstr/\fBcurs_inwstr\fR(3X)
+is_cleared/\fBcurs_opaque\fR(3X)*
+is_idcok/\fBcurs_opaque\fR(3X)*
+is_idlok/\fBcurs_opaque\fR(3X)*
+is_immedok/\fBcurs_opaque\fR(3X)*
+is_keypad/\fBcurs_opaque\fR(3X)*
+is_leaveok/\fBcurs_opaque\fR(3X)*
is_linetouched/\fBcurs_touch\fR(3X)
+is_nodelay/\fBcurs_opaque\fR(3X)*
+is_notimeout/\fBcurs_opaque\fR(3X)*
+is_scrollok/\fBcurs_opaque\fR(3X)*
+is_syncok/\fBcurs_opaque\fR(3X)*
+is_term_resized/\fBresizeterm\fR(3X)*
is_wintouched/\fBcurs_touch\fR(3X)
isendwin/\fBcurs_initscr\fR(3X)
key_defined/\fBkey_defined\fR(3X)*
nocbreak/\fBcurs_inopts\fR(3X)
nodelay/\fBcurs_inopts\fR(3X)
noecho/\fBcurs_inopts\fR(3X)
+nofilter/\fBcurs_util\fR(3X)*
nonl/\fBcurs_outopts\fR(3X)
noqiflush/\fBcurs_inopts\fR(3X)
noraw/\fBcurs_inopts\fR(3X)
use_default_colors/\fBdefault_colors\fR(3X)*
use_env/\fBcurs_util\fR(3X)
use_extended_names/\fBcurs_extend\fR(3X)*
+use_legacy_coding/\fBlegacy_coding\fR(3X)*
vid_attr/\fBcurs_terminfo\fR(3X)
vid_puts/\fBcurs_terminfo\fR(3X)
vidattr/\fBcurs_terminfo\fR(3X)
Specify the width of the screen in characters.
Applications running in a windowing environment usually are able to
obtain the width of the window in which they are executing.
-If neither the $COLUMNS value nor the terminal's screen size is available,
+If neither the \fBCOLUMNS\fP value nor the terminal's screen size is available,
\fBncurses\fR uses the size which may be specified in the terminfo database
(i.e., the \fBcols\fR capability).
.IP
It is important that your application use a correct size for the screen.
-However, this is not always possible because your application may be
+This is not always possible because your application may be
running on a host which does not honor NAWS (Negotiations About Window
Size), or because you are temporarily running as another user.
+However, setting \fBCOLUMNS\fP and/or \fBLINES\fP overrides the library's
+use of the screen size obtained from the operating system.
.IP
-Either COLUMNS or LINES symbols may be specified independently.
+Either \fBCOLUMNS\fP or \fBLINES\fP symbols may be specified independently.
This is mainly useful to circumvent legacy misfeatures of terminal descriptions,
e.g., xterm which commonly specifies a 65 line screen.
For best results, \fBlines\fR and \fBcols\fR should not be specified in
a terminal description for terminals which are run as emulations.
.IP
-Use the \fBuse_env\fR function to disable this feature.
+Use the \fBuse_env\fR function to disable all use of external environment
+(including system calls) to determine the screen size.
.TP 5
ESCDELAY
Specifies the total time, in milliseconds, for which ncurses will
If your application makes heavy use of multiple-clicking, you may
wish to lengthen this default value because the timeout applies
to the composed multi-click event as well as the individual clicks.
+.IP
+In addition to the environment variable,
+this implementation provides a global variable with the same name.
+Portable applications should not rely upon the presence of ESCDELAY
+in either form,
+but setting the environment variable rather than the global variable
+does not create problems when compiling an application.
.TP 5
HOME
Tells \fBncurses\fR where your home directory is.
NCURSES_ASSUMED_COLORS
Override the compiled-in assumption that the
terminal's default colors are white-on-black
-(see \fBassume_default_colors\fR(3X)).
+(see \fBdefault_colors\fR(3X)).
You may set the foreground and background color values with this environment
variable by proving a 2-element list: foreground,background.
For example, to tell ncurses to not assume anything
To make it green-on-black, set it to "2,0".
Any positive value from zero to the terminfo \fBmax_colors\fR value is allowed.
.TP 5
+NCURSES_NO_HARD_TABS
+\fBNcurses\fP may use tabs as part of the cursor movement optimization.
+In some cases,
+your terminal driver may not handle these properly.
+Set this environment variable to disable the feature.
+You can also adjust your \fBstty\fP settings to avoid the problem.
+.TP 5
+NCURSES_NO_MAGIC_COOKIES
+Some terminals use a magic-cookie feature which requires special handling
+to make highlighting and other video attributes display properly.
+You can suppress the highlighting entirely for these terminals by
+setting this environment variable.
+.TP 5
NCURSES_NO_PADDING
Most of the terminal descriptions in the terminfo database are written
for real "hardware" terminals.
disables output buffering, leaving the output in the original (usually
line buffered) mode.
.TP 5
+NCURSES_NO_UTF8_ACS
+During initialization, the \fBncurses\fR library
+checks for special cases where VT100 line-drawing (and the corresponding
+alternate character set capabilities) described in the terminfo are known
+to be missing.
+Specifically, when running in a UTF-8 locale,
+the Linux console emulator and the GNU screen program ignore these.
+Ncurses checks the TERM environment variable for these.
+For other special cases, you should set this environment variable.
+Doing this tells ncurses to use Unicode values which correspond to
+the VT100 line-drawing glyphs.
+That works for the special cases cited,
+and is likely to work for terminal emulators.
+.IP
+When setting this variable, you should set it to a nonzero value.
+Setting it to zero (or to a nonnumber)
+disables the special check for Linux and screen.
+.TP 5
NCURSES_TRACE
During initialization, the \fBncurses\fR debugging library
checks the NCURSES_TRACE symbol.
current user is the superuser (root), or if the application uses setuid or
setgid permissions:
$TERMINFO, $TERMINFO_DIRS, $TERMPATH, as well as $HOME.
+.SH ALTERNATE CONFIGURATIONS
+Several different configurations are possible,
+depending on the configure script options used when building \fBncurses\fP.
+There are a few main options whose effects are visible to the applications
+developer using \fBncurses\fP:
+.TP 5
+--disable-overwrite
+The standard include for \fBncurses\fP is as noted in \fBSYNOPSIS\fP:
+.RS
+.sp
+\fB#include <curses.h>\fR
+.RE
+.IP
+This option is used to avoid filename conflicts when \fBncurses\fP
+is not the main implementation of curses of the computer.
+If \fBncurses\fP is installed disabling overwrite, it puts its headers in
+a subdirectory, e.g.,
+.RS
+.sp
+\fB#include <ncurses/curses.h>\fR
+.RE
+.IP
+It also omits a symbolic link which would allow you to use \fB-lcurses\fP
+to build executables.
+.TP 5
+--enable-widec
+The configure script renames the library and (if the \fB--disable-overwrite\fP
+option is used) puts the header files in a different subdirectory.
+All of the library names have a "w" appended to them,
+i.e., instead of
+.RS
+.sp
+\fB-lncurses\fR
+.RE
+.IP
+you link with
+.RS
+.sp
+\fB-lncursesw\fR
+.RE
+.IP
+You must also define \fB_XOPEN_SOURCE_EXTENDED\fP when compiling for the
+wide-character library to use the extended (wide-character) functions.
+The \fBcurses.h\fP file which is installed for the wide-character
+library is designed to be compatible with the normal library's header.
+Only the size of the \fBWINDOW\fP structure differs, and very few
+applications require more than a pointer to \fBWINDOW\fPs.
+If the headers are installed allowing overwrite,
+the wide-character library's headers should be installed last,
+to allow applications to be built using either library
+from the same set of headers.
+.TP 5
+--with-shared
+.TP
+--with-normal
+.TP
+--with-debug
+.TP
+--with-profile
+The shared and normal (static) library names differ by their suffixes,
+e.g., \fBlibncurses.so\fP and \fBlibncurses.a\fP.
+The debug and profiling libraries add a "_g" and a "_p" to the root
+names respectively,
+e.g., \fBlibncurses_g.a\fP and \fBlibncurses_p.a\fP.
+.TP 5
+--with-trace
+The \fBtrace\fP function normally resides in the debug library,
+but it is sometimes useful to configure this in the shared library.
+Configure scripts should check for the function's existence rather
+than assuming it is always in the debug library.
.SH FILES
.TP 5
@DATADIR@/tabset
\fBterminfo\fR(\*n) and related pages whose names begin "curs_" for detailed routine
descriptions.
.SH EXTENSIONS
-The \fBncurses\fR library can be compiled with an option (\fB\-DUSE_GETCAP\fR)
+The \fBncurses\fR library can be compiled with an option (\fB-DUSE_GETCAP\fR)
that falls back to the old-style /etc/termcap file if the terminal setup code
cannot find a terminfo entry corresponding to \fBTERM\fR. Use of this feature
is not recommended, as it essentially includes an entire termcap compiler in
the XSI Curses and \fBncurses\fR calls) are described in \fBPORTABILITY\fR
sections of the library man pages.
.PP
+This implementation also contains several extensions:
+.RS 5
+.PP
The routine \fBhas_key\fR is not part of XPG4, nor is it present in SVr4. See
the \fBcurs_getch\fR(3X) manual page for details.
.PP
-The routine \fBslk_attr\fR is not part of XPG4, nor is it present in SVr4. See
-the \fBcurs_slk\fR(3X) manual page for details.
+The routine \fBslk_attr\fR is not part of XPG4, nor is it present in SVr4.
+See the \fBcurs_slk\fR(3X) manual page for details.
.PP
The routines \fBgetmouse\fR, \fBmousemask\fR, \fBungetmouse\fR,
\fBmouseinterval\fR, and \fBwenclose\fR relating to mouse interfacing are not
-part of XPG4, nor are they present in SVr4. See the \fBcurs_mouse\fR(3X)
-manual page for details.
+part of XPG4, nor are they present in SVr4.
+See the \fBcurs_mouse\fR(3X) manual page for details.
+.PP
+The routine \fBmcprint\fR was not present in any previous curses implementation.
+See the \fBcurs_print\fR(3X) manual page for details.
.PP
-The routine \fBmcprint\fR was not present in any previous curses
-implementation. See the \fBcurs_print\fR(3X) manual page for details.
+The routine \fBwresize\fR is not part of XPG4, nor is it present in SVr4.
+See the \fBwresize\fR(3X) manual page for details.
.PP
-The routine \fBwresize\fR is not part of XPG4, nor is it present in SVr4. See
-the \fBwresize\fR(3X) manual page for details.
+The WINDOW structure's internal details can be hidden from application
+programs.
+See \fBcurs_opaque\fR(3X) for the discussion of \fBis_scrollok\fR, etc.
+.RE
.PP
In historic curses versions, delays embedded in the capabilities \fBcr\fR,
\fBind\fR, \fBcub1\fR, \fBff\fR and \fBtab\fR activated corresponding delay
projects / ncurses.git / blobdiff