ncurses 5.9 - patch 20111217
[ncurses.git] / man / ncurses.3x
index ba360e5c80601a2b88ee99e5a72ad780e7d26d9b..14900d94efd73868e5e5cef17d5e0e6ea0d1ba10 100644 (file)
@@ -1,6 +1,6 @@
 '\" t
 .\"***************************************************************************
-.\" Copyright (c) 1998-2009,2010 Free Software Foundation, Inc.              *
+.\" Copyright (c) 1998-2010,2011 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            *
@@ -27,7 +27,7 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: ncurses.3x,v 1.98 2010/09/18 20:17:20 tom Exp $
+.\" $Id: ncurses.3x,v 1.106 2011/12/17 23:19:59 tom Exp $
 .hy 0
 .TH ncurses 3X ""
 .de bP
@@ -108,9 +108,9 @@ Most programs would additionally use the sequence:
 .sp
 Before a \fBcurses\fR program is run, the tab stops of the terminal
 should be set and its initialization strings, if defined, must be output.
-This can be done by executing the \fBtput init\fR command
+This can be done by executing the \fB@TPUT@ init\fR command
 after the shell environment variable \fBTERM\fR has been exported.
-\fBtset(1)\fR is usually responsible for doing this.
+\fB@TSET@(1)\fR is usually responsible for doing this.
 [See \fBterminfo\fR(\*n) for further details.]
 .PP
 The \fBncurses\fR library permits manipulation of data structures,
@@ -734,6 +734,9 @@ Routines that return an integer return \fBERR\fR upon failure and an
 integer value other than \fBERR\fR upon successful completion, unless
 otherwise noted in the routine descriptions.
 .PP
+As a general rule, routines check for null pointers passed as parameters,
+and handle this as an error.
+.PP
 All macros return the value of the \fBw\fR version, except \fBsetscrreg\fR,
 \fBwsetscrreg\fR, \fBgetyx\fR, \fBgetbegyx\fR, and \fBgetmaxyx\fR.
 The return values of \fBsetscrreg\fR, \fBwsetscrreg\fR, \fBgetyx\fR, \fBgetbegyx\fR, and
@@ -930,6 +933,28 @@ and is likely to work for terminal emulators.
 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".
+.IP
+As an alternative to the environment variable,
+ncurses checks for an extended terminfo capability \fBU8\fP.
+This is a numeric capability which can be compiled using \fB@TIC@\ \-x\fP.
+For example
+.RS 5
+.sp
+.nf
+# linux console, if patched to provide working
+# VT100 shift-in/shift-out, with corresponding font.
+linux-vt100|linux console with VT100 line-graphics,
+       U8#0, use=linux,
+.sp
+# uxterm with vt100Graphics resource set to false
+xterm-utf8|xterm relying on UTF-8 line-graphics,
+       U8#1, use=xterm,
+.fi
+.RE
+.IP
+The name "U8" is chosen to be two characters,
+to permit it to be used by applications that use ncurses'
+termcap interface.
 .TP 5
 NCURSES_TRACE
 During initialization, the \fBncurses\fR debugging library
@@ -982,6 +1007,13 @@ Specifies a list of directories to search for terminal descriptions.
 The list is separated by colons (i.e., ":") on Unix, semicolons on OS/2 EMX.
 All of the terminal descriptions are in terminfo form, which makes
 a subdirectory named for the first letter of the terminal names therein.
+.IP
+If \fBncurses\fP is built with a hashed database,
+then each entry in this list can also be the path of the corresponding
+database file.
+.IP
+If \fBncurses\fP is built with a support for reading termcap files
+directly, then an entry in this list may be the path of a termcap file.
 .TP 5
 TERMPATH
 If TERMCAP does not hold a file name then \fBncurses\fR checks
@@ -1073,6 +1105,8 @@ terminal capability database
 .SH SEE ALSO
 \fBterminfo\fR(\*n) and related pages whose names begin "curs_" for detailed routine
 descriptions.
+.br
+\fBcurs_variables\fR(3X) 
 .SH EXTENSIONS
 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
@@ -1120,30 +1154,45 @@ A small number of local differences (that is, individual differences between
 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
+Unlike other implementations, this one checks parameters such as pointers
+to WINDOW structures to ensure they are not null.
+The main reason for providing this behavior is to guard against programmer
+error.
+The standard interface does not provide a way for the library
+to tell an application which of several possible errors were detected.
+Relying on this (or some other) extension will adversely affect the
+portability of curses applications.
 .PP
+This implementation also contains several extensions:
+.bP
 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
+.bP
 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
+.bP
 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.
-.PP
+.bP
 The routine \fBmcprint\fR was not present in any previous curses implementation.
 See the \fBcurs_print\fR(3X) manual page for details.
-.PP
+.bP
 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
+.bP
 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
+.bP
+This implementation can be configured to provide rudimentary support
+for multi-threaded applications.
+See \fBcurs_threads\fR(3X) for details.
+.bP
+This implementation can also be configured to provide a set of functions which
+improve the ability to manage multiple screens.
+See \fBcurs_sp_funcs\fR(3X) for details.
 .PP
 In historic curses versions, delays embedded in the capabilities \fBcr\fR,
 \fBind\fR, \fBcub1\fR, \fBff\fR and \fBtab\fR activated corresponding delay
@@ -1162,9 +1211,3 @@ This was an undocumented feature of AT&T System V Release 3 curses.
 .SH AUTHORS
 Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey.
 Based on pcurses by Pavel Curtis.
-.\"#
-.\"# The following sets edit modes for GNU EMACS
-.\"# Local Variables:
-.\"# mode:nroff
-.\"# fill-column:79
-.\"# End: