[src/trunk]: src/lib/libedit Fix the prototype used by EL_GETCFN, mention the...

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

details:   https://anonhg.NetBSD.org/src/rev/ce29b9b40321
branches:  trunk
changeset: 345355:ce29b9b40321
user:      christos <christos%NetBSD.org@localhost>
date:      Sat May 21 17:06:44 2016 +0000

description:
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)

diffstat:

 lib/libedit/editline.3 |  57 +++++++++++++++++++++++++++++++------------------
 1 files changed, 36 insertions(+), 21 deletions(-)

diffs (120 lines):

diff -r 0281ce32634f -r ce29b9b40321 lib/libedit/editline.3
--- a/lib/libedit/editline.3    Sat May 21 16:23:10 2016 +0000
+++ b/lib/libedit/editline.3    Sat May 21 17:06:44 2016 +0000
@@ -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 @@
 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 @@
 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 @@
 .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 @@
 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 @@
 .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 @@
 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