ncurses 5.7 - patch 20110115
[ncurses.git] / man / curs_termattrs.3x
index 5c65d3c573eabd51889e084f3b5251dbfd88fd8b..0f0294cd5696d8dea10c34cf55f9c44d9f9e9e4d 100644 (file)
@@ -1,24 +1,67 @@
+.\"***************************************************************************
+.\" Copyright (c) 1998-2007,2010 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            *
+.\" "Software"), to deal in the Software without restriction, including      *
+.\" without limitation the rights to use, copy, modify, merge, publish,      *
+.\" distribute, distribute with modifications, sublicense, and/or sell       *
+.\" copies of the Software, and to permit persons to whom the Software is    *
+.\" furnished to do so, subject to the following conditions:                 *
+.\"                                                                          *
+.\" The above copyright notice and this permission notice shall be included  *
+.\" in all copies or substantial portions of the Software.                   *
+.\"                                                                          *
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
+.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
+.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
+.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
+.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
+.\"                                                                          *
+.\" Except as contained in this notice, the name(s) of the above copyright   *
+.\" holders shall not be used in advertising or otherwise to promote the     *
+.\" sale, use or other dealings in this Software without prior written       *
+.\" authorization.                                                           *
+.\"***************************************************************************
+.\"
+.\" $Id: curs_termattrs.3x,v 1.12 2010/12/04 18:40:45 tom Exp $
 .TH curs_termattrs 3X ""
 .SH NAME
-\fBbaudrate\fR, \fBerasechar\fR, \fBhas_ic\fR,
-\fBhas_il\fR, \fBkillchar\fR, \fBlongname\fR, \fBtermattrs\fR,
-\fBtermname\fR - \fBcurses\fR environment query routines
+\fBbaudrate\fR,
+\fBerasechar\fR,
+\fBerasewchar\fR,
+\fBhas_ic\fR,
+\fBhas_il\fR,
+\fBkillchar\fR,
+\fBkillwchar\fR,
+\fBlongname\fR,
+\fBterm_attrs\fR,
+\fBtermattrs\fR,
+\fBtermname\fR \- \fBcurses\fR environment query routines
 .SH SYNOPSIS
 \fB#include <curses.h>\fR
-
+.PP
 \fBint baudrate(void);\fR
 .br
 \fBchar erasechar(void);\fR
 .br
-\fBint has_ic(void);\fR
+\fBint erasewchar(wchar_t *\fR\fIch\fR\fB);\fR
 .br
-\fBint has_il(void);\fR
+\fBbool has_ic(void);\fR
+.br
+\fBbool has_il(void);\fR
 .br
 \fBchar killchar(void);\fR
 .br
+\fBint killwchar(wchar_t *\fR\fIch\fR\fB);\fR
+.br
 \fBchar *longname(void);\fR
 .br
-\fBattr_t termattrs(void);\fR
+\fBattr_t term_attrs(void);\fR
+.br
+\fBchtype termattrs(void);\fR
 .br
 \fBchar *termname(void);\fR
 .br
 The \fBbaudrate\fR routine returns the output speed of the terminal.  The
 number returned is in bits per second, for example \fB9600\fR, and is an
 integer.
-
+.PP
 The \fBerasechar\fR routine returns the user's current erase character.
-
+.PP
+The \fBerasewchar\fR routine stores the current erase character
+in the location referenced by \fIch\fR.
+If no erase character has been defined, the routine fails
+and the location referenced by \fIch\fR is not changed.
+.PP
 The \fBhas_ic\fR routine is true if the terminal has insert- and delete-
 character capabilities.
-
+.PP
 The \fBhas_il\fR routine is true if the terminal has insert- and delete-line
 capabilities, or can simulate them using scrolling regions.  This might
 be used to determine if it would be appropriate to turn on physical
 scrolling using \fBscrollok\fR.
-
+.PP
 The \fBkillchar\fR routine returns the user's current line kill character.
-
+.PP
+The \fBkillwchar\fR routine stores the current line-kill character
+in the location referenced by \fIch\fR.
+If no line-kill character has been defined,
+the routine fails and the location referenced by \fIch\fR is not changed.
+.PP
 The \fBlongname\fR routine returns a pointer to a static area
 containing a verbose description of the current terminal.  The maximum
 length of a verbose description is 128 characters.  It is defined only
@@ -47,19 +100,20 @@ overwritten by each call to \fBnewterm\fR and is not restored by
 \fBset_term\fR, so the value should be saved between calls to
 \fBnewterm\fR if \fBlongname\fR is going to be used with multiple
 terminals.
-
-If a given terminal doesn't support a video attribute that an
+.PP
+If a given terminal does not support a video attribute that an
 application program is trying to use, \fBcurses\fR may substitute a
-different video attribute for it.  The \fBtermattrs\fR function
-returns a logical \fBOR\fR of all video attributes supported by the
-terminal.  This information is useful when a \fBcurses\fR program
+different video attribute for it.
+The \fBtermattrs\fR and \fBterm_attrs\fR functions
+return a logical \fBOR\fR of all video attributes supported by the
+terminal using \fIA_\fR and \fIWA_\fR constants respectively.
+This information is useful when a \fBcurses\fR program
 needs complete control over the appearance of the screen.
-
-The \fBtermname\fR routine returns the value of the environmental
-variable \fBTERM\fR (truncated to 14 characters).
+.PP
+The \fBtermname\fR routine returns the terminal name used by \fBsetupterm\fR.
 .SH RETURN VALUE
 \fBlongname\fR and \fBtermname\fR return \fBNULL\fR on error.
-
+.PP
 Routines that return an integer return \fBERR\fR upon failure and \fBOK\fR
 (SVr4 only specifies "an integer value other than \fBERR\fR") upon successful
 completion.
@@ -68,11 +122,7 @@ Note that \fBtermattrs\fR may be a macro.
 .SH PORTABILITY
 The XSI Curses standard, Issue 4 describes these functions.  It changes the
 return type of \fBtermattrs\fR to the new type \fBattr_t\fR.
+Most versions of curses truncate the result returned by \fBtermname\fR to
+14 characters.
 .SH SEE ALSO
 \fBcurses\fR(3X), \fBcurs_initscr\fR(3X), \fBcurs_outopts\fR(3X)
-.\"#
-.\"# The following sets edit modes for GNU EMACS
-.\"# Local Variables:
-.\"# mode:nroff
-.\"# fill-column:79
-.\"# End: