API cleanups and doc additions.

13 files changed, 118 insertions, 28 deletions

diff --git a/extension/ChangeLog b/extension/ChangeLog
index 09068dc7..8889420d 100644
--- a/extension/ChangeLog
+++ b/extension/ChangeLog
@@ -1,3 +1,12 @@
+2012-10-14         Arnold D. Robbins     <arnold@skeeve.com>
+
+	* readdir.c, revoutput.c, revtwoway.c: Adjust for name change
+	of IOBUF_PUBLIC to awk_input_buf_t. Additional sanitizing in
+	revoutput.c to use `revoutput' everywhere instead of `revout'.
+	* revoutput.3am: New file.
+	* filefuncs.3am, fnmatch.3am, fork.3am, ordchr.3am, readdir.3am,
+	readfile.3am, rwarray.3am, time.3am: Add ref to revoutput(3am).
+
 2012-10-11         Arnold D. Robbins     <arnold@skeeve.com>
 
 	* textext.c (try_modify_environ): Save array cookie in a separate
diff --git a/extension/filefuncs.3am b/extension/filefuncs.3am
index 592dc070..e0caba05 100644
--- a/extension/filefuncs.3am
+++ b/extension/filefuncs.3am
@@ -324,6 +324,7 @@ distribution for an example.
 .IR ordchr (3am),
 .IR readdir (3am),
 .IR readfile (3am),
+.IR revoutput (3am),
 .IR rwarray (3am),
 .IR time (3am).
 .PP
diff --git a/extension/fnmatch.3am b/extension/fnmatch.3am
index b35f626d..c84e9ae1 100644
--- a/extension/fnmatch.3am
+++ b/extension/fnmatch.3am
@@ -87,6 +87,7 @@ if (fnmatch("*.a", "foo.c", flags) == FNM_NOMATCH)
 .IR ordchr (3am),
 .IR readdir (3am),
 .IR readfile (3am),
+.IR revoutput (3am),
 .IR rwarray (3am),
 .IR time (3am).
 .PP
diff --git a/extension/fork.3am b/extension/fork.3am
index 9e545a14..9d89aa56 100644
--- a/extension/fork.3am
+++ b/extension/fork.3am
@@ -62,6 +62,7 @@ else
 .IR ordchr (3am),
 .IR readdir (3am),
 .IR readfile (3am),
+.IR revoutput (3am),
 .IR rwarray (3am),
 .IR time (3am).
 .PP
diff --git a/extension/ordchr.3am b/extension/ordchr.3am
index 343c49b0..86312a3a 100644
--- a/extension/ordchr.3am
+++ b/extension/ordchr.3am
@@ -46,6 +46,7 @@ printf("The string value of 65 is %s\en", chr(65))
 .IR fork (3am),
 .IR readdir (3am),
 .IR readfile (3am),
+.IR revoutput (3am),
 .IR rwarray (3am),
 .IR time (3am).
 .SH AUTHOR
diff --git a/extension/readdir.3am b/extension/readdir.3am
index 5e03f491..9d60b054 100644
--- a/extension/readdir.3am
+++ b/extension/readdir.3am
@@ -95,6 +95,7 @@ BEGIN { FS = "/" }
 .IR fork (3am),
 .IR ordchr (3am),
 .IR readfile (3am),
+.IR revoutput (3am),
 .IR rwarray (3am),
 .IR time (3am).
 .PP
diff --git a/extension/readdir.c b/extension/readdir.c
index 5f937fb9..7d126d03 100644
--- a/extension/readdir.c
+++ b/extension/readdir.c
@@ -146,7 +146,7 @@ typedef struct open_directory {
 /* dir_get_record --- get one record at a time out of a directory */
 
 static int
-dir_get_record(char **out, struct iobuf_public *iobuf, int *errcode,
+dir_get_record(char **out, awk_input_buf_t *iobuf, int *errcode,
 		char **rt_start, size_t *rt_len)
 {
 	DIR *dp;
@@ -200,7 +200,7 @@ dir_get_record(char **out, struct iobuf_public *iobuf, int *errcode,
 /* dir_close --- close up when done */
 
 static void
-dir_close(struct iobuf_public *iobuf)
+dir_close(awk_input_buf_t *iobuf)
 {
 	open_directory_t *the_dir;
 
@@ -218,8 +218,8 @@ dir_close(struct iobuf_public *iobuf)
 
 /* dir_can_take_file --- return true if we want the file */
 
-static int
-dir_can_take_file(const IOBUF_PUBLIC *iobuf)
+static awk_bool_t
+dir_can_take_file(const awk_input_buf_t *iobuf)
 {
 	if (iobuf == NULL)
 		return 0;
@@ -233,8 +233,8 @@ dir_can_take_file(const IOBUF_PUBLIC *iobuf)
  * and no state has changed since then.
  */
 
-static int
-dir_take_control_of(IOBUF_PUBLIC *iobuf)
+static awk_bool_t
+dir_take_control_of(awk_input_buf_t *iobuf)
 {
 	DIR *dp;
 	open_directory_t *the_dir;
diff --git a/extension/readfile.3am b/extension/readfile.3am
index f68850a4..8daec423 100644
--- a/extension/readfile.3am
+++ b/extension/readfile.3am
@@ -39,6 +39,7 @@ if (contents == "" && ERRNO != "") {
 .IR fork (3am),
 .IR ordchr (3am),
 .IR readdir (3am),
+.IR revoutput (3am),
 .IR rwarray (3am),
 .IR time (3am).
 .SH AUTHOR
diff --git a/extension/revoutput.3am b/extension/revoutput.3am
new file mode 100644
index 00000000..61e34124
--- /dev/null
+++ b/extension/revoutput.3am
@@ -0,0 +1,73 @@
+.TH REVOUTPUT 3am "Oct 14 2012" "Free Software Foundation" "GNU Awk Extension Modules"
+.SH NAME
+revoutput \- Reverse output strings sample extension
+.SH SYNOPSIS
+.ft CW
+@load "revoutput"
+.sp
+BEGIN { REVOUT = 1 }    # Reverse all output strings
+.ft R
+.SH DESCRIPTION
+The
+.I revoutput
+extension
+adds a simple output wrapper that reverses the characters in each output
+line.
+It's main purpose is to show how to write an output wrapper, although
+it may be mildy amusing for the unwary.
+... .SH BUGS
+.SH EXAMPLE
+.ft CW
+.nf
+@load "revoutput"
+
+BEGIN {
+    REVOUT = 1
+    print "hello, world" > "/dev/stdout"
+}
+.fi
+.ft R
+.PP
+The output from this program is:
+.PP
+.ft CW
+.nf
+dlrow ,olleh
+.fi
+.ft R
+.SH "SEE ALSO"
+.IR "GAWK: Effective AWK Programming" ,
+.IR filefuncs (3am),
+.IR fnmatch (3am),
+.IR fork (3am),
+.IR ordchr (3am),
+.IR readdir (3am),
+.IR readfile (3am),
+.IR rwarray (3am),
+.IR time (3am).
+.SH AUTHOR
+Arnold Robbins,
+.BR arnold@skeeve.com .
+.SH COPYING PERMISSIONS
+Copyright \(co 2012
+Free Software Foundation, Inc.
+.PP
+Permission is granted to make and distribute verbatim copies of
+this manual page provided the copyright notice and this permission
+notice are preserved on all copies.
+.ig
+Permission is granted to process this file through troff and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual page).
+..
+.PP
+Permission is granted to copy and distribute modified versions of this
+manual page under the conditions for verbatim copying, provided that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+.PP
+Permission is granted to copy and distribute translations of this
+manual page into another language, under the above conditions for
+modified versions, except that this permission notice may be stated in
+a translation approved by the Foundation.
diff --git a/extension/revoutput.c b/extension/revoutput.c
index 7430e61b..0366672b 100644
--- a/extension/revoutput.c
+++ b/extension/revoutput.c
@@ -49,8 +49,8 @@ static const gawk_api_t *api;	/* for convenience macros to work */
 static awk_ext_id_t *ext_id;
 static const char *ext_version = "revoutput extension: version 1.0";
 
-static awk_bool_t init_revout(void);
-static awk_bool_t (*init_func)(void) = init_revout;
+static awk_bool_t init_revoutput(void);
+static awk_bool_t (*init_func)(void) = init_revoutput;
 
 int plugin_is_GPL_compatible;
 
@@ -71,10 +71,10 @@ rev_fwrite(const void *buf, size_t size, size_t count, FILE *fp, void *opaque)
 }
 
 
-/* revout_can_take_file --- return true if we want the file */
+/* revoutput_can_take_file --- return true if we want the file */
 
-static int
-revout_can_take_file(const awk_output_buf_t *outbuf)
+static awk_bool_t
+revoutput_can_take_file(const awk_output_buf_t *outbuf)
 {
 	awk_value_t value;
 
@@ -88,13 +88,13 @@ revout_can_take_file(const awk_output_buf_t *outbuf)
 }
 
 /*
- * revout_take_control_of --- set up output wrapper.
- * We can assume that revout_can_take_file just returned true,
+ * revoutput_take_control_of --- set up output wrapper.
+ * We can assume that revoutput_can_take_file just returned true,
  * and no state has changed since then.
  */
 
-static int
-revout_take_control_of(awk_output_buf_t *outbuf)
+static awk_bool_t
+revoutput_take_control_of(awk_output_buf_t *outbuf)
 {
 	if (outbuf == NULL)
 		return 0;
@@ -105,16 +105,16 @@ revout_take_control_of(awk_output_buf_t *outbuf)
 }
 
 static awk_output_wrapper_t output_wrapper = {
-	"revout",
-	revout_can_take_file,
-	revout_take_control_of,
+	"revoutput",
+	revoutput_can_take_file,
+	revoutput_take_control_of,
 	NULL
 };
 
-/* init_revout --- set things ups */
+/* init_revoutput --- set things ups */
 
 static awk_bool_t
-init_revout()
+init_revoutput()
 {
 	awk_value_t value;
 
@@ -122,7 +122,7 @@ init_revout()
 
 	make_number(0.0, & value);	/* init to false */
 	if (! sym_update("REVOUT", & value)) {
-		warning(ext_id, _("revout: could not initialize REVOUT variable"));
+		warning(ext_id, _("revoutput: could not initialize REVOUT variable"));
 
 		return 0;
 	}
@@ -136,4 +136,4 @@ static awk_ext_func_t func_table[] = {
 
 /* define the dl_load function using the boilerplate macro */
 
-dl_load_func(func_table, revout, "")
+dl_load_func(func_table, revoutput, "")
diff --git a/extension/revtwoway.c b/extension/revtwoway.c
index 0c1d9b00..0008d634 100644
--- a/extension/revtwoway.c
+++ b/extension/revtwoway.c
@@ -55,7 +55,7 @@ static awk_bool_t (*init_func)(void) = init_revtwoway;
 int plugin_is_GPL_compatible;
 
 /*
- * Use this variable to provide a value != INVALID_HANDLE in the IOBUF_PUBLIC
+ * Use this variable to provide a value != INVALID_HANDLE in the awk_input_buf_t
  * and != NULL in the awk_output_buf_t.  The idea is to have a value that
  * is greater than the largest allowable file descriptor.
  */
@@ -128,7 +128,7 @@ close_two_proc_data(two_way_proc_data_t *proc_data)
 /* rev2way_get_record --- get one record at a time out of a directory */
 
 static int
-rev2way_get_record(char **out, struct iobuf_public *iobuf, int *errcode,
+rev2way_get_record(char **out, awk_input_buf_t *iobuf, int *errcode,
 		char **rt_start, size_t *rt_len)
 {
 	int len = 0;	/* for now */
@@ -166,7 +166,7 @@ rev2way_get_record(char **out, struct iobuf_public *iobuf, int *errcode,
 /* rev2way_close --- close up input side when done */
 
 static void
-rev2way_close(struct iobuf_public *iobuf)
+rev2way_close(awk_input_buf_t *iobuf)
 {
 	two_way_proc_data_t *proc_data;
 
@@ -262,7 +262,7 @@ rev2way_fclose(FILE *fp, void *opaque)
 
 /* revtwoway_can_two_way --- return true if we want the file */
 
-static int
+static awk_bool_t
 revtwoway_can_take_two_way(const char *name)
 {
 	return (name != NULL && strcmp(name, "/magic/mirror") == 0);
@@ -274,8 +274,8 @@ revtwoway_can_take_two_way(const char *name)
  * and no state has changed since then.
  */
 
-static int
-revtwoway_take_control_of(const char *name, IOBUF_PUBLIC *inbuf, awk_output_buf_t *outbuf)
+static awk_bool_t
+revtwoway_take_control_of(const char *name, awk_input_buf_t *inbuf, awk_output_buf_t *outbuf)
 {
 	two_way_proc_data_t *proc_data;
 
diff --git a/extension/rwarray.3am b/extension/rwarray.3am
index c68e4b4a..571736d3 100644
--- a/extension/rwarray.3am
+++ b/extension/rwarray.3am
@@ -72,6 +72,7 @@ ret = reada("arraydump.bin", array)
 .IR ordchr (3am),
 .IR readdir (3am),
 .IR readfile (3am),
+.IR revoutput (3am),
 .IR time (3am).
 .SH AUTHOR
 Arnold Robbins,
diff --git a/extension/time.3am b/extension/time.3am
index eba015bb..42d9bf35 100644
--- a/extension/time.3am
+++ b/extension/time.3am
@@ -54,6 +54,7 @@ printf "Pausing for a while... " ; sleep(2.5) ; print "done"
 .IR ordchr (3am),
 .IR readdir (3am),
 .IR readfile (3am),
+.IR revoutput (3am),
 .IR rwarray (3am).
 .PP
 .IR gettimeofday (2),