[src/trunk]: src/lib/libedit Fix el_{w, }getc documentation (Ingo Schwarze)

[christos <christos%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/da6f44e4d168
branches:  trunk
changeset: 343751:da6f44e4d168
user:      christos <christos%NetBSD.org@localhost>
date:      Wed Feb 24 19:45:48 2016 +0000

description:
Fix el_{w,}getc documentation (Ingo Schwarze)

diffstat:

 lib/libedit/editline.3 |  54 ++++++++++++++++++++++++++++++++++++++++++-------
 1 files changed, 46 insertions(+), 8 deletions(-)

diffs (76 lines):

diff -r 35566e92561b -r da6f44e4d168 lib/libedit/editline.3
--- a/lib/libedit/editline.3    Wed Feb 24 18:28:54 2016 +0000
+++ b/lib/libedit/editline.3    Wed Feb 24 19:45:48 2016 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: editline.3,v 1.86 2016/02/24 18:28:54 christos Exp $
+.\"    $NetBSD: editline.3,v 1.87 2016/02/24 19:45:48 christos Exp $
 .\"
 .\" Copyright (c) 1997-2014 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -173,6 +173,16 @@
 library).
 Programs should be linked with
 .Fl ledit ltermcap .
+.Pp
+The
+.Nm
+library respects the
+.Dv LC_CTYPE
+locale set by the application program and never uses
+.Xr setlocale 3
+to change the locale.
+The only locales supported are UTF-8 and the default C or POSIX locale.
+If any other locale is set, behaviour is undefined.
 .Sh LINE EDITING FUNCTIONS
 The line editing functions use a common data structure,
 .Fa EditLine ,
@@ -238,14 +248,42 @@
 The return value may not remain valid across calls to
 .Fn el_gets
 and must be copied if the data is to be retained.
+.It Fn el_wgetc
+Read a wide character from the tty, respecting the current locale,
+or from the input stream written by
+.Fn el_wpush
+and
+.Fn el_push
+if that is not empty, and store it in
+.Fa ch .
+If an invalid or incomplete character is found, it is discarded,
+.Va errno
+is set to
+.Dv EILSEQ ,
+and the next character is read and stored in
+.Fa ch .
+Returns 1 if a valid character was read, 0 on end of file, or -1 on
+.Xr read 2
+failure.
+In the latter case,
+.Va errno
+is set to indicate the error.
 .It Fn el_getc
-Read a character from the tty.
-.Fa ch
-is modified to contain the character read.
-Returns the number of characters read if successful, \-1 otherwise,
-in which case
-.Dv errno
-can be inspected for the cause.
+Read a wide character as described for
+.Fn el_wgetc
+and return 0 on end of file or -1 on failure.
+If the wide character can be represented as a single-byte character,
+convert it with
+.Xr wctob 3 ,
+store the result in
+.Fa ch ,
+and return 1; otherwise, set
+.Va errno
+to
+.Dv ERANGE
+and return -1.
+In the C or POSIX locale, this simply reads a byte, but for any other
+locale, including UTF-8, this is rarely useful.
 .It Fn el_push
 Pushes
 .Fa str