X-Git-Url: http://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_util.3x;h=fb912b65f3285cda0d9d0fbe831c1f595e22de83;hp=73b599ec4dd377e6c7c7e59ed512ecb5c50a882a;hb=96d6b16de0d487e5d3aed0302a179dbce11b5d96;hpb=b6d7123594f6959ad0a6602b3952d9e6abe261a0

diff --git a/man/curs_util.3x b/man/curs_util.3x
index 73b599ec..fb912b65 100644
--- a/man/curs_util.3x
+++ b/man/curs_util.3x
@@ -1,5 +1,5 @@
 .\"***************************************************************************
-.\" Copyright (c) 1998-2006,2007 Free Software Foundation, Inc.              *
+.\" Copyright (c) 1998-2008,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            *
@@ -26,8 +26,11 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_util.3x,v 1.23 2007/02/24 15:59:07 tom Exp $
+.\" $Id: curs_util.3x,v 1.32 2010/12/04 18:38:55 tom Exp $
 .TH curs_util 3X ""
+.de bP
+.IP \(bu 4
+..
 .na
 .hy 0
 .SH NAME
@@ -41,7 +44,7 @@
 \fBputwin\fR,
 \fBunctrl\fR,
 \fBuse_env\fR,
-\fBwunctrl\fR - miscellaneous \fBcurses\fR utility routines
+\fBwunctrl\fR \- miscellaneous \fBcurses\fR utility routines
 .ad
 .hy
 .SH SYNOPSIS
@@ -75,12 +78,33 @@ representation of the character \fIc\fR, ignoring attributes.
 Control characters are displayed in the \fB^\fR\fIX\fR notation.
 Printing characters are displayed as is.
 The corresponding \fBwunctrl\fR returns a printable representation of
-a wide-character.
+a wide character.
 .PP
-The \fBkeyname\fR routine returns a character string corresponding to the key \fIc\fR.
+The \fBkeyname\fR routine returns a character string corresponding to the key \fIc\fR:
+.RS 3
+.bP
+Printable characters are displayed as themselves, e.g., a one-character string containing the key.
+.bP
 Control characters are displayed in the \fB^\fR\fIX\fR notation.
-Values above 128 are either meta characters, shown in the \fBM-\fR\fIX\fR notation,
-or the names of function keys, or null.
+.bP
+DEL (character 127) is displayed as \fB^?\fP.
+.bP
+Values above 128 are either meta characters
+(if the screen has not been initialized,
+or if \fBmeta\fP has been called with a TRUE parameter),
+shown in the \fBM\-\fR\fIX\fR notation,
+or are displayed as themselves.
+In the latter case, the values may not be printable;
+this follows the X/Open specification.
+.bP
+Values above 256 may be the names of the names of function keys.
+.bP
+Otherwise (if there is no corresponding name) the function returns null,
+to denote an error.
+X/Open also lists an "UNKNOWN KEY" return value, which some implementations
+return rather than null.
+.RE
+.LP
 The corresponding \fBkey_name\fR returns a character string corresponding
 to the wide-character value \fIw\fR.
 The two functions do not return the same set of strings;
@@ -134,11 +158,14 @@ Routines that return pointers return \fBNULL\fR on error.
 .PP
 X/Open does not define any error conditions.
 In this implementation
-.RS
+.RS 3
 .TP 5
 \fBflushinp\fR
 returns an error if the terminal was not initialized.
 .TP 5
+\fBmeta\fR
+returns an error if the terminal was not initialized.
+.TP 5
 \fBputwin\fP
 returns an error if the associated \fBfwrite\fP calls return an error.
 .RE
@@ -146,6 +173,26 @@ returns an error if the associated \fBfwrite\fP calls return an error.
 The XSI Curses standard, Issue 4 describes these functions.
 It states that \fBunctrl\fR and \fBwunctrl\fR will return a null pointer if
 unsuccessful, but does not define any error conditions.
+This implementation checks for three cases:
+.RS 3
+.bP
+the parameter is a 7-bit US\-ASCII code.
+This is the case that X/Open Curses documented.
+.bP
+the parameter is in the range 128\-159, i.e., a C1 control code.
+If \fBuse_legacy_coding\fP has been called with a \fB2\fP parameter,
+\fBunctrl\fP returns the parameter, i.e., a one-character string with
+the parameter as the first character.
+Otherwise, it returns ``~@'', ``~A'', etc., analogous to ``^@'', ``^A'', C0 controls.
+.IP
+X/Open Curses does not document whether \fBunctrl\fP can be called before
+initializing curses.
+This implementation permits that,
+and returns the ``~@'', etc., values in that case.
+.bP
+parameter values outside the 0 to 255 range.
+\fBunctrl\fP returns a null pointer.
+.RE
 .PP
 The SVr4 documentation describes the action of \fBfilter\fR only in the vaguest
 terms.  The description here is adapted from the XSI Curses standard (which
@@ -157,21 +204,34 @@ showing C1 controls from the upper-128 codes with a `~' prefix rather than `^'.
 Other implementations have different conventions.
 For example, they may show both sets of control characters with `^',
 and strip the parameter to 7 bits.
-Or they may ignore C1 controls and treat all of the upper-1280 codes as
+Or they may ignore C1 controls and treat all of the upper-128 codes as
 printable.
 This implementation uses 8 bits but does not modify the string to reflect
 locale.
 The \fBuse_legacy_coding\fP function allows the caller to
 change the output of \fBunctrl\fP.
 .PP
+Likewise, the \fBmeta\fP function allows the caller to change the
+output of \fBkeyname\fP, i.e.,
+it determines whether to use the `M\-' prefix
+for ``meta'' keys (codes in the range 128 to 255).
+Both \fBuse_legacy_coding\fP and \fBmeta\fP succeed only after
+curses is initialized. 
+X/Open Curses does not document the treatment of codes 128 to 159.
+When treating them as ``meta'' keys
+(or if \fBkeyname\fP is called before initializing curses),
+this implementation returns strings ``M\-^@'', ``M\-^A'', etc.
+.PP
 The \fBkeyname\fP function may return the names of user-defined
-string capabilities which are defined in the terminfo entry via the \fB-x\fP
+string capabilities which are defined in the terminfo entry via the \fB\-x\fP
 option of \fBtic\fP.
 This implementation automatically assigns at run-time keycodes to 
 user-defined strings which begin with "k".
 The keycodes start at KEY_MAX, but are not guaranteed to be 
 the same value for different runs because user-defined codes are
 merged from all terminal descriptions which have been loaded.
+The \fBuse_extended_names\fP function controls whether this data is
+loaded when the terminal description is read by the library.
 .PP
 The \fBnofilter\fP routine is specific to ncurses.
 It was not supported on Version 7, BSD or System V implementations.
@@ -182,10 +242,6 @@ be conditioned using NCURSES_VERSION.
 \fBcurses\fR(3X),
 \fBcurs_initscr\fR(3X),
 \fBcurs_kernel\fR(3X),
-\fBcurs_scr_dump\fR(3X).
-.\"#
-.\"# The following sets edit modes for GNU EMACS
-.\"# Local Variables:
-.\"# mode:nroff
-.\"# fill-column:79
-.\"# End:
+\fBcurs_scr_dump\fR(3X),
+\fBcurs_variables\fR(3X),
+\fBlegacy_coding\fR(3X).