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            *
@@ -26,9 +26,11 @@
 .\" 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
+.na
+.hy 0
 .SH NAME
 \fBdel_curterm\fR,
 \fBmvcur\fR,
@@ -46,6 +48,8 @@
 \fBvid_puts\fR,
 \fBvidattr\fR,
 \fBvidputs\fR - \fBcurses\fR interfaces to terminfo database
+.ad
+.hy
 .SH SYNOPSIS
 .nf
 \fB#include <curses.h>\fR
@@ -60,7 +64,7 @@
 .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
@@ -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:
-
+.sp
       \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:
-
+.sp
       \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.
@@ -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).
-
-\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.
@@ -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.
+.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
@@ -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.
+.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),
-\fBputc\fR(3S), \fBterminfo\fR(\*n)
+\fBputc\fR(3), \fBterminfo\fR(\*n)
 .\"#
 .\"# The following sets edit modes for GNU EMACS
 .\"# Local Variables: