Module Name: src
Committed By: christos
Date: Sat May 21 17:06:45 UTC 2016
Modified Files:
src/lib/libedit: editline.3
Log Message:
Fix the prototype used by EL_GETCFN, mention the associated typedef
name, document the return values, expand the list of affected
functions, warn against using EL_GETCFN, and clarify some wording
and notation. (Ingo Schwarze)
To generate a diff of this commit:
cvs rdiff -u -r1.90 -r1.91 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.90 src/lib/libedit/editline.3:1.91
--- src/lib/libedit/editline.3:1.90 Mon May 9 17:27:55 2016
+++ src/lib/libedit/editline.3 Sat May 21 13:06:44 2016
@@ -1,4 +1,4 @@
-.\" $NetBSD: editline.3,v 1.90 2016/05/09 21:27:55 christos Exp $
+.\" $NetBSD: editline.3,v 1.91 2016/05/21 17:06:44 christos Exp $
.\"
.\" Copyright (c) 1997-2014 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -92,7 +92,7 @@
.Ft int
.Fn el_getc "EditLine *e" "char *ch"
.Ft int
-.Fn el_wgetc "EditLine *e" "wchar_t *ch"
+.Fn el_wgetc "EditLine *e" "wchar_t *wc"
.Ft void
.Fn el_push "EditLine *e" "const char *str"
.Ft void
@@ -255,13 +255,13 @@ or from the input stream written by
and
.Fn el_push
if that is not empty, and store it in
-.Fa ch .
+.Fa wc .
If an invalid or incomplete character is found, it is discarded,
.Va errno
is set to
.Er EILSEQ ,
and the next character is read and stored in
-.Fa ch .
+.Fa wc .
Returns 1 if a valid character was read, 0 on end of file, or \-1 on
.Xr read 2
failure.
@@ -503,18 +503,31 @@ unbuffered mode is disabled (the default
In unbuffered mode,
.Fn el_gets
will return immediately after processing a single character.
-.It Dv EL_GETCFN , Fa "int (*f)(EditLine *, char *c)"
-Define the character reading function as
-.Fa f ,
-which is to return the number of characters read and store them in
-.Fa c .
-This function is called internally by
-.Fn el_gets
+.It Dv EL_GETCFN , Fa "el_rfunc_t f"
+Whenever reading a character, use the function
+.Bd -ragged -offset indent -compact
+.Ft int
+.Fo f
+.Fa "EditLine *e"
+.Fa "wchar_t *wc"
+.Fc
+.Ed
+which stores the character in
+.Fa wc
+and returns 1 on success, 0 on end of file, or \-1 on I/O or encoding
+errors.
+Functions internally using it include
+.Fn el_wgets ,
+.Fn el_wgetc ,
+.Fn el_gets ,
and
.Fn el_getc .
-The builtin function can be set or restored with the special function
-name
-.Dq Dv EL_BUILTIN_GETCFN .
+Initially, a builtin function is installed, and replacing it
+is discouraged because writing such a function is very error prone.
+The builtin function can be restored at any time by passing the
+special value
+.Dv EL_BUILTIN_GETCFN
+instead of a function pointer.
.It Dv EL_CLIENTDATA , Fa "void *data"
Register
.Fa data
@@ -558,7 +571,7 @@ are supported, along with actual type of
.Bl -tag -width 4n
.It Dv EL_PROMPT , Fa "char *(*f)(EditLine *)" , Fa "char *c"
Set
-.Fa f .
+.Fa f
to a pointer to the function that displays the prompt.
If
.Fa c
@@ -567,7 +580,7 @@ is not
set it to the start/stop literal prompt character.
.It Dv EL_RPROMPT , Fa "char *(*f)(EditLine *)" , Fa "char *c"
Set
-.Fa f .
+.Fa f
to a pointer to the function that displays the prompt.
If
.Fa c
@@ -592,7 +605,7 @@ to the current value of that capability.
.It Dv EL_SIGNAL , Fa "int *s"
Set
.Fa s
-to non zero if
+to non-zero if
.Nm
has installed private signal handlers (see
.Fn el_get
@@ -601,10 +614,12 @@ above).
Set
.Fa c
to non-zero if editing is enabled.
-.It Dv EL_GETCFN , Fa "int (**f)(EditLine *, char *)"
-Return a pointer to the function that read characters, which is equal to
-.Dq Dv EL_BUILTIN_GETCFN
-in the case of the default builtin function.
+.It Dv EL_GETCFN , Fa "el_rfunc_t *f"
+Set
+.Fa f
+to a pointer to the function that reads characters, or to
+.Dv EL_BUILTIN_GETCFN
+if the builtin function is in use.
.It Dv EL_CLIENTDATA , Fa "void **data"
Set
.Fa data
