ncurses 5.6 - patch 20070224

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

diff --git a/man/curs_terminfo.3x b/man/curs_terminfo.3x
index d5c9bf68275baddcdde584601f7995ccbda17e4a..6de95b05066d2d6a754fb5e953ab3a0383948e81 100644 (file)
--- a/man/curs_terminfo.3x
+++ b/man/curs_terminfo.3x
@@ -1,5 +1,5 @@
 .\"***************************************************************************
 .\"***************************************************************************

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


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

-.\" $Id: curs_terminfo.3x,v 1.18 2003/12/27 18:48:59 tom Exp $
+.\" $Id: curs_terminfo.3x,v 1.26 2007/02/24 16:37:50 tom Exp $

 .TH curs_terminfo 3X ""
 .ds n 5
 .TH curs_terminfo 3X ""
 .ds n 5

+.na
+.hy 0

 .SH NAME
 \fBdel_curterm\fR,
 \fBmvcur\fR,
 .SH NAME
 \fBdel_curterm\fR,
 \fBmvcur\fR,


@@ -46,6 +48,8 @@
 \fBvid_puts\fR,
 \fBvidattr\fR,
 \fBvidputs\fR - \fBcurses\fR interfaces to terminfo database
 \fBvid_puts\fR,
 \fBvidattr\fR,
 \fBvidputs\fR - \fBcurses\fR interfaces to terminfo database

+.ad
+.hy

 .SH SYNOPSIS
 .nf
 \fB#include <curses.h>\fR
 .SH SYNOPSIS
 .nf
 \fB#include <curses.h>\fR


@@ -60,7 +64,7 @@
 .br
 \fBint del_curterm(TERMINAL *\fR\fIoterm\fR\fB);\fR
 .br
 .br
 \fBint del_curterm(TERMINAL *\fR\fIoterm\fR\fB);\fR
 .br

-\fBint restartterm(const char *\fR\fIterm\fR\fB, int \fR\fIfildes\fR\fB, int *\fR\fIerrret\fR\fB);\fR
+\fBint restartterm(char *\fR\fIterm\fR\fB, int \fR\fIfildes\fR\fB, int *\fR\fIerrret\fR\fB);\fR

 .br
 \fBchar *tparm(char *\fR\fIstr\fR\fB, ...);\fR
 .br
 .br
 \fBchar *tparm(char *\fR\fIstr\fR\fB, ...);\fR
 .br


@@ -150,15 +154,15 @@ means that the \fBterminfo\fR database could not be found.
 If \fIerrret\fR is
 null, \fBsetupterm\fR prints an error message upon finding an error
 and exits.  Thus, the simplest call is:
 If \fIerrret\fR is
 null, \fBsetupterm\fR prints an error message upon finding an error
 and exits.  Thus, the simplest call is:

-
+.sp

       \fBsetupterm((char *)0, 1, (int *)0);\fR,
       \fBsetupterm((char *)0, 1, (int *)0);\fR,

-
+.sp

 which uses all the defaults and sends the output to \fBstdout\fR.
 .PP
 The \fBsetterm\fR routine is being replaced by \fBsetupterm\fR.  The call:
 which uses all the defaults and sends the output to \fBstdout\fR.
 .PP
 The \fBsetterm\fR routine is being replaced by \fBsetupterm\fR.  The call:

-
+.sp

       \fBsetupterm(\fR\fIterm\fR\fB, 1, (int *)0)\fR
       \fBsetupterm(\fR\fIterm\fR\fB, 1, (int *)0)\fR

-
+.sp

 provides the same functionality as \fBsetterm(\fR\fIterm\fR\fB)\fR.
 The \fBsetterm\fR routine is included here for BSD compatibility, and
 is not recommended for new programs.
 provides the same functionality as \fBsetterm(\fR\fIterm\fR\fB)\fR.
 The \fBsetterm\fR routine is included here for BSD compatibility, and
 is not recommended for new programs.


@@ -236,13 +240,15 @@ or \fB0\fR if it is canceled or absent from the terminal description.
 .PP
 The \fIcapname\fR for each capability is given in the table column entitled
 \fIcapname\fR code in the capabilities section of \fBterminfo\fR(\*n).
 .PP
 The \fIcapname\fR for each capability is given in the table column entitled
 \fIcapname\fR code in the capabilities section of \fBterminfo\fR(\*n).

-
-\fBchar *boolnames\fR, \fB*boolcodes\fR, \fB*boolfnames\fR
-
-\fBchar *numnames\fR, \fB*numcodes\fR, \fB*numfnames\fR
-
-\fBchar *strnames\fR, \fB*strcodes\fR, \fB*strfnames\fR
-
+.sp
+.RS
+\fBchar *boolnames[]\fR, \fB*boolcodes[]\fR, \fB*boolfnames[]\fR
+.sp
+\fBchar *numnames[]\fR, \fB*numcodes[]\fR, \fB*numfnames[]\fR
+.sp
+\fBchar *strnames[]\fR, \fB*strcodes[]\fR, \fB*strfnames[]\fR
+.RE
+.PP

 These null-terminated arrays contain the \fIcapnames\fR, the
 \fBtermcap\fR codes, and the full C names, for each of the
 \fBterminfo\fR variables.
 These null-terminated arrays contain the \fIcapnames\fR, the
 \fBtermcap\fR codes, and the full C names, for each of the
 \fBterminfo\fR variables.


@@ -252,6 +258,25 @@ Routines that return an integer return \fBERR\fR upon failure and \fBOK\fR
 completion, unless otherwise noted in the preceding routine descriptions.
 .PP
 Routines that return pointers always return \fBNULL\fR on error.
 completion, unless otherwise noted in the preceding routine descriptions.
 .PP
 Routines that return pointers always return \fBNULL\fR on error.

+.PP
+X/Open defines no error conditions.
+In this implementation
+.RS
+.TP 5
+\fBdel_curterm\fP
+returns an error
+if its terminal parameter is null.
+.TP 5
+\fBrestartterm\fP
+returns an error
+if the associated call to \fBsetupterm\fP returns an error.
+.TP 5
+\fBsetupterm\fP
+returns an error
+if it cannot allocate enough memory, or
+create the initial windows (stdscr, curscr, newscr).
+Other error conditions are documented above.
+.RE

 .SH NOTES
 The \fBsetupterm\fR routine should be used in place of \fBsetterm\fR.
 It may be useful when you want to test for terminal capabilities without
 .SH NOTES
 The \fBsetupterm\fR routine should be used in place of \fBsetterm\fR.
 It may be useful when you want to test for terminal capabilities without


@@ -283,9 +308,16 @@ Both ncurses 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.
 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
+XSI states that the old location must be given.
+This implementation allows the caller to use -1's for the old ordinates.
+In that case, the old location is unknown.
+.PP
+Extended terminal capability names, e.g., as defined by \fBtic\ -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),
 .SH SEE ALSO
 \fBcurses\fR(3X), \fBcurs_initscr\fR(3X), \fBcurs_kernel\fR(3X), \fBcurs_termcap\fR(3X),

-\fBputc\fR(3S), \fBterminfo\fR(\*n)
+\fBputc\fR(3), \fBterminfo\fR(\*n)

 .\"#
 .\"# The following sets edit modes for GNU EMACS
 .\"# Local Variables:
 .\"#
 .\"# The following sets edit modes for GNU EMACS
 .\"# Local Variables: