Module Name: src
Committed By: christos
Date: Wed Feb 24 19:45:48 UTC 2016
Modified Files:
src/lib/libedit: editline.3
Log Message:
Fix el_{w,}getc documentation (Ingo Schwarze)
To generate a diff of this commit:
cvs rdiff -u -r1.86 -r1.87 src/lib/libedit/editline.3
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/lib/libedit/editline.3
diff -u src/lib/libedit/editline.3:1.86 src/lib/libedit/editline.3:1.87
--- src/lib/libedit/editline.3:1.86 Wed Feb 24 13:28:54 2016
+++ src/lib/libedit/editline.3 Wed Feb 24 14:45:48 2016
@@ -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 (which needs the
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 @@ contains the error code that caused it.
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
