ncurses 5.9 - patch 20130713

[ncurses.git] / man / curs_terminfo.3x

diff --git a/man/curs_terminfo.3x b/man/curs_terminfo.3x
index 4412a6a69c354b29f8faf30c8d6d612b340a0ab1..12d4b0fe044d17ac80d8ab3ebc120e4c35a0b96c 100644 (file)
--- a/man/curs_terminfo.3x
+++ b/man/curs_terminfo.3x
@@ -1,5 +1,5 @@
 .\"***************************************************************************
 .\"***************************************************************************

-.\" Copyright (c) 1999-2007,2008 Free Software Foundation, Inc.              *
+.\" Copyright (c) 1999-2011,2013 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            *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
 .\" copy of this software and associated documentation files (the            *


@@ -26,8 +26,11 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"

-.\" $Id: curs_terminfo.3x,v 1.30 2008/08/16 20:53:27 tom Exp $
+.\" $Id: curs_terminfo.3x,v 1.38 2013/07/13 23:12:13 tom Exp $

 .TH curs_terminfo 3X ""
 .TH curs_terminfo 3X ""

+.de bP
+.IP \(bu 4
+..

 .ds n 5
 .na
 .hy 0
 .ds n 5
 .na
 .hy 0


@@ -42,12 +45,13 @@
 \fBtigetflag\fR,
 \fBtigetnum\fR,
 \fBtigetstr\fR,
 \fBtigetflag\fR,
 \fBtigetnum\fR,
 \fBtigetstr\fR,

+\fBtiparm\fR,

 \fBtparm\fR,
 \fBtputs\fR,
 \fBvid_attr\fR,
 \fBvid_puts\fR,
 \fBvidattr\fR,
 \fBtparm\fR,
 \fBtputs\fR,
 \fBvid_attr\fR,
 \fBvid_puts\fR,
 \fBvidattr\fR,

-\fBvidputs\fR - \fBcurses\fR interfaces to terminfo database
+\fBvidputs\fR \- \fBcurses\fR interfaces to terminfo database

 .ad
 .hy
 .SH SYNOPSIS
 .ad
 .hy
 .SH SYNOPSIS


@@ -76,7 +80,7 @@
 .br
 \fBint vidattr(chtype \fR\fIattrs\fR\fB);\fR
 .br
 .br
 \fBint vidattr(chtype \fR\fIattrs\fR\fB);\fR
 .br

-\fBint vid_puts(attr_t \fR\fIattrs\fR\fB, short \fR\fIpair\fR\fB, void *\fR\fIopts\fR\fB, int (*\fR\fIputc\fR\fB)(char));\fR
+\fBint vid_puts(attr_t \fR\fIattrs\fR\fB, short \fR\fIpair\fR\fB, void *\fR\fIopts\fR\fB, int (*\fR\fIputc\fR\fB)(int));\fR

 .br
 \fBint vid_attr(attr_t \fR\fIattrs\fR\fB, short \fR\fIpair\fR\fB, void *\fR\fIopts\fR\fB);\fR
 .br
 .br
 \fBint vid_attr(attr_t \fR\fIattrs\fR\fB, short \fR\fIpair\fR\fB, void *\fR\fIopts\fR\fB);\fR
 .br


@@ -88,6 +92,8 @@
 .br
 \fBchar *tigetstr(char *\fR\fIcapname\fR\fB);\fR
 .br
 .br
 \fBchar *tigetstr(char *\fR\fIcapname\fR\fB);\fR
 .br

+\fBchar *tiparm(const char *\fR\fIstr\fR\fB, ...);\fR
+.br

 .fi
 .SH DESCRIPTION
 These low-level routines must be called by programs that have to deal
 .fi
 .SH DESCRIPTION
 These low-level routines must be called by programs that have to deal


@@ -147,13 +153,19 @@ If \fBERR\fR is returned, examine \fIerrret\fR:
 .TP 5
 .B 1
 means that the terminal is hardcopy, cannot be used for curses applications.
 .TP 5
 .B 1
 means that the terminal is hardcopy, cannot be used for curses applications.

+.IP
+\fBsetupterm\fP determines if the entry is a hardcopy type by
+checking the \fIhc\fP (\fIhardcopy\fP) capability.

 .TP 5
 .B 0
 means that the terminal could not be found,
 or that it is a generic type,
 having too little information for curses applications to run.
 .TP 5
 .B 0
 means that the terminal could not be found,
 or that it is a generic type,
 having too little information for curses applications to run.

+.IP
+\fBsetupterm\fP determines if the entry is a generic type by
+checking the \fIgn\fP (\fIgeneric\fP) capability.

 .TP 5
 .TP 5

-.B -1
+.B \-1

 means that the \fBterminfo\fR database could not be found.
 .RE
 .PP
 means that the \fBterminfo\fR database could not be found.
 .RE
 .PP


@@ -196,6 +208,10 @@ The \fBtparm\fR routine instantiates the string \fIstr\fR with
 parameters \fIpi\fR.  A pointer is returned to the result of \fIstr\fR
 with the parameters applied.
 .PP
 parameters \fIpi\fR.  A pointer is returned to the result of \fIstr\fR
 with the parameters applied.
 .PP

+\fBtiparm\fP is a newer form of \fBtparm\fP which uses \fI<stdarg.h>\fP
+rather than a fixed-parameter list.
+Its numeric parameters are integers (int) rather than longs.
+.PP

 The \fBtputs\fR routine applies padding information to the string
 \fIstr\fR and outputs it.  The \fIstr\fR must be a terminfo string
 variable or the return value from \fBtparm\fR, \fBtgetstr\fR, or
 The \fBtputs\fR routine applies padding information to the string
 \fIstr\fR and outputs it.  The \fIstr\fR must be a terminfo string
 variable or the return value from \fBtparm\fR, \fBtgetstr\fR, or


@@ -233,15 +249,15 @@ The \fBtigetflag\fR, \fBtigetnum\fR and \fBtigetstr\fR routines return
 the value of the capability corresponding to the \fBterminfo\fR
 \fIcapname\fR passed to them, such as \fBxenl\fR.
 .PP
 the value of the capability corresponding to the \fBterminfo\fR
 \fIcapname\fR passed to them, such as \fBxenl\fR.
 .PP

-The \fBtigetflag\fR routine returns the value \fB-1\fR if
+The \fBtigetflag\fR routine returns the value \fB\-1\fR if

 \fIcapname\fR is not a boolean capability,
 or \fB0\fR if it is canceled or absent from the terminal description.
 .PP
 \fIcapname\fR is not a boolean capability,
 or \fB0\fR if it is canceled or absent from the terminal description.
 .PP

-The \fBtigetnum\fR routine returns the value \fB-2\fR if
+The \fBtigetnum\fR routine returns the value \fB\-2\fR if

 \fIcapname\fR is not a numeric capability,
 \fIcapname\fR is not a numeric capability,

-or \fB-1\fR if it is canceled or absent from the terminal description.
+or \fB\-1\fR if it is canceled or absent from the terminal description.

 .PP
 .PP

-The \fBtigetstr\fR routine returns the value \fB(char *)-1\fR
+The \fBtigetstr\fR routine returns the value \fB(char *)\-1\fR

 if \fIcapname\fR is not a string capability,
 or \fB0\fR if it is canceled or absent from the terminal description.
 .PP
 if \fIcapname\fR is not a string capability,
 or \fB0\fR if it is canceled or absent from the terminal description.
 .PP


@@ -268,7 +284,7 @@ Routines that return pointers always return \fBNULL\fR on error.
 .PP
 X/Open defines no error conditions.
 In this implementation
 .PP
 X/Open defines no error conditions.
 In this implementation

-.RS
+.RS 5

 .TP 5
 \fBdel_curterm\fP
 returns an error
 .TP 5
 \fBdel_curterm\fP
 returns an error


@@ -306,6 +322,31 @@ be considered non-portable.  All other functions are as described by X/Open.
 \fBsetupterm\fP copies the terminal name to the array \fBttytype\fP.
 This is not part of X/Open Curses, but is assumed by some applications.
 .PP
 \fBsetupterm\fP copies the terminal name to the array \fBttytype\fP.
 This is not part of X/Open Curses, but is assumed by some applications.
 .PP

+If configured to use the terminal-driver,
+e.g., for the MinGW port,
+.bP
+\fBsetupterm\fP interprets a missing/empty TERM variable as the
+special value ``unknown''.
+.bP
+\fBsetupterm\fP allows explicit use of the
+the windows console driver by checking if $TERM is set to
+``#win32con'' or an abbreviation of that string.
+.PP
+Older versions of \fBncurses\fP assumed that the file descriptor passed to
+\fBsetupterm\fP from \fBinitscr\fP or \fBnewterm\fP uses buffered I/O,
+and would write to the corresponding stream.
+In addition to the limitation that the terminal was left in block-buffered
+mode on exit (like SystemV curses),
+it was problematic because \fBncurses\fP
+did not allow a reliable way to cleanup on receiving SIGTSTP.
+The current version uses output buffers managed directly by \fBncurses\fP.
+Some of the low-level functions described in this manual page write
+to the standard output.
+They are not signal-safe.
+The high-level functions in \fBncurses\fP use
+alternate versions of these functions
+using the more reliable buffering scheme.
+.PP

 In System V Release 4, \fBset_curterm\fR has an \fBint\fR return type and
 returns \fBOK\fR or \fBERR\fR.  We have chosen to implement the X/Open Curses
 semantics.
 In System V Release 4, \fBset_curterm\fR has an \fBint\fR return type and
 returns \fBOK\fR or \fBERR\fR.  We have chosen to implement the X/Open Curses
 semantics.


@@ -319,34 +360,34 @@ That returns the length of the string, and does no error-checking.
 .PP
 X/Open Curses prototypes \fBtparm\fR with a fixed number of parameters,
 rather than a variable argument list.
 .PP
 X/Open Curses prototypes \fBtparm\fR with a fixed number of parameters,
 rather than a variable argument list.

-This implementation uses a variable argument list.
+This implementation uses a variable argument list, but can be
+configured to use the fixed-parameter list.

 Portable applications should provide 9 parameters after the format;
 zeroes are fine for this purpose.
 .PP
 Portable applications should provide 9 parameters after the format;
 zeroes are fine for this purpose.
 .PP

+In response to comments by Thomas E. Dickey,
+X/Open Curses Issue 7 proposed the \fBtiparam\fP function in mid-2009.
+.PP

 X/Open notes that after calling \fBmvcur\fR, the curses state may not match the
 actual terminal state, and that an application should touch and refresh
 the window before resuming normal curses calls.
 X/Open notes that after calling \fBmvcur\fR, the curses state may not match the
 actual terminal state, and that an application should touch and refresh
 the window before resuming normal curses calls.

-Both ncurses and System V Release 4 curses implement \fBmvcur\fR using
+Both \fBncurses\fP and System V Release 4 curses implement \fBmvcur\fR using

 the SCREEN data allocated in either \fBinitscr\fR or \fBnewterm\fR.
 So though it is documented as a terminfo function,
 \fBmvcur\fR is really a curses function which is not well specified.
 .PP
 X/Open states that the old location must be given for \fBmvcur\fP.
 the SCREEN data allocated in either \fBinitscr\fR or \fBnewterm\fR.
 So though it is documented as a terminfo function,
 \fBmvcur\fR is really a curses function which is not well specified.
 .PP
 X/Open states that the old location must be given for \fBmvcur\fP.

-This implementation allows the caller to use -1's for the old ordinates.
+This implementation allows the caller to use \-1's for the old ordinates.

 In that case, the old location is unknown.
 .PP
 In that case, the old location is unknown.
 .PP

-Extended terminal capability names, e.g., as defined by \fBtic\ -x\fP,
+Extended terminal capability names, e.g., as defined by \fB@TIC@\ \-x\fP,

 are not stored in the arrays described in this section.
 .SH SEE ALSO
 \fBcurses\fR(3X),
 \fBcurs_initscr\fR(3X),
 \fBcurs_kernel\fR(3X),
 \fBcurs_termcap\fR(3X),
 are not stored in the arrays described in this section.
 .SH SEE ALSO
 \fBcurses\fR(3X),
 \fBcurs_initscr\fR(3X),
 \fBcurs_kernel\fR(3X),
 \fBcurs_termcap\fR(3X),

+\fBcurs_variables\fR(3X),
+\fBterm_variables\fR(3X),

 \fBputc\fR(3),
 \fBterminfo\fR(\*n)
 \fBputc\fR(3),
 \fBterminfo\fR(\*n)

-.\"#
-.\"# The following sets edit modes for GNU EMACS
-.\"# Local Variables:
-.\"# mode:nroff
-.\"# fill-column:79
-.\"# End: