Add 3rd argument to stat() extension.

6 files changed, 147 insertions, 101 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index a8810fad..82367979 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,9 @@
+2012-11-21         Arnold D. Robbins     <arnold@skeeve.com>
+
+	* gawk.texi: In API chapter, update behavior of stat function
+	in the filefuncs extension.  Update the code example and prose
+	to match the current code.
+
 2012-11-19         Arnold D. Robbins     <arnold@skeeve.com>
 
 	* gawk.texi: In API chapter, update behavior of readdir extension.
diff --git a/doc/gawk.info b/doc/gawk.info
index e99a6e81..9a66843c 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -23854,9 +23854,9 @@ numbered zero.
          return make_number(ret, result);
      }
 
-   The `stat()' built-in is more involved.  First comes a function that
-turns a numeric mode into a printable representation (e.g., 644 becomes
-`-rw-r--r--'). This is omitted here for brevity:
+   The `stat()' extension is more involved.  First comes a function
+that turns a numeric mode into a printable representation (e.g., 644
+becomes `-rw-r--r--'). This is omitted here for brevity:
 
      /* format_mode --- turn a stat mode field into something readable */
 
@@ -24027,15 +24027,20 @@ declarations and argument checking:
          awk_array_t array;
          int ret;
          struct stat sbuf;
+         int (*statfunc)(const char *path, struct stat *sbuf) = lstat;   /* default */
 
          assert(result != NULL);
 
-         if (do_lint && nargs != 2) {
-             lintwarn(ext_id,
-                      _("stat: called with wrong number of arguments"));
+         if (nargs != 2 && nargs != 3) {
+             if (do_lint)
+                 lintwarn(ext_id, _("stat: called with wrong number of arguments"));
              return make_number(-1, result);
          }
 
+   The third argument to `stat()' was not discussed previously. This
+argument is optional. If present, it causes `stat()' to use the `stat()'
+system call instead of the `lstat()' system call.
+
    Then comes the actual work. First, the function gets the arguments.
 Next, it gets the information for the file.  The code use `lstat()'
 (instead of `stat()') to get the file information, in case the file is
@@ -24048,14 +24053,18 @@ a symbolic link.  If there's an error, it sets `ERRNO' and returns:
              return make_number(-1, result);
          }
 
+         if (nargs == 3) {
+             statfunc = stat;
+         }
+
          name = file_param.str_value.str;
          array = array_param.array_cookie;
 
          /* always empty out the array */
          clear_array(array);
 
-         /* lstat the file, if error, set ERRNO and return */
-         ret = lstat(name, & sbuf);
+         /* stat the file, if error, set ERRNO and return */
+         ret = statfunc(name, & sbuf);
          if (ret < 0) {
              update_ERRNO_int(errno);
              return make_number(ret, result);
@@ -24235,10 +24244,13 @@ follows: The usage is:
      success or less than zero upon error.  In the latter case it
      updates `ERRNO'.
 
-`result = stat("/some/path", statdata)'
+`result = stat("/some/path", statdata [, follow])'
      The `stat()' function provides a hook into the `stat()' system
-     call. In fact, it uses `lstat()'.  It returns zero upon success or
-     less than zero upon error.  In the latter case it updates `ERRNO'.
+     call.  It returns zero upon success or less than zero upon error.
+     In the latter case it updates `ERRNO'.
+
+     By default, it uses the `lstat()' system call.  However, if passed
+     a third argument, it uses `stat()' instead.
 
      In all cases, it clears the `statdata' array.  When the call is
      successful, `stat()' fills the `statdata' array with information
@@ -32160,79 +32172,79 @@ Node: Finding Extensions955059
 Node: Extension Example955606
 Node: Internal File Description956344
 Node: Internal File Ops960032
-Ref: Internal File Ops-Footnote-1971116
-Node: Using Internal File Ops971256
-Ref: Using Internal File Ops-Footnote-1973612
-Node: Extension Samples973878
-Node: Extension Sample File Functions975321
-Node: Extension Sample Fnmatch983690
-Node: Extension Sample Fork985416
-Node: Extension Sample Ord986630
-Node: Extension Sample Readdir987406
-Node: Extension Sample Revout988910
-Node: Extension Sample Rev2way989503
-Node: Extension Sample Read write array990193
-Node: Extension Sample Readfile992076
-Node: Extension Sample API Tests992831
-Node: Extension Sample Time993356
-Node: gawkextlib994663
-Node: Language History997044
-Node: V7/SVR3.1998566
-Node: SVR41000887
-Node: POSIX1002329
-Node: BTL1003337
-Node: POSIX/GNU1004071
-Node: Common Extensions1009606
-Node: Ranges and Locales1010713
-Ref: Ranges and Locales-Footnote-11015331
-Ref: Ranges and Locales-Footnote-21015358
-Ref: Ranges and Locales-Footnote-31015618
-Node: Contributors1015839
-Node: Installation1020135
-Node: Gawk Distribution1021029
-Node: Getting1021513
-Node: Extracting1022339
-Node: Distribution contents1024031
-Node: Unix Installation1029253
-Node: Quick Installation1029870
-Node: Additional Configuration Options1031832
-Node: Configuration Philosophy1033309
-Node: Non-Unix Installation1035651
-Node: PC Installation1036109
-Node: PC Binary Installation1037408
-Node: PC Compiling1039256
-Node: PC Testing1042200
-Node: PC Using1043376
-Node: Cygwin1047561
-Node: MSYS1048561
-Node: VMS Installation1049075
-Node: VMS Compilation1049678
-Ref: VMS Compilation-Footnote-11050685
-Node: VMS Installation Details1050743
-Node: VMS Running1052378
-Node: VMS Old Gawk1053985
-Node: Bugs1054459
-Node: Other Versions1058311
-Node: Notes1063626
-Node: Compatibility Mode1064213
-Node: Additions1064996
-Node: Accessing The Source1065923
-Node: Adding Code1067349
-Node: New Ports1073391
-Node: Derived Files1077526
-Ref: Derived Files-Footnote-11082834
-Ref: Derived Files-Footnote-21082868
-Ref: Derived Files-Footnote-31083468
-Node: Future Extensions1083566
-Node: Basic Concepts1085053
-Node: Basic High Level1085734
-Ref: figure-general-flow1086005
-Ref: figure-process-flow1086604
-Ref: Basic High Level-Footnote-11089833
-Node: Basic Data Typing1090018
-Node: Glossary1093373
-Node: Copying1118684
-Node: GNU Free Documentation License1156241
-Node: Index1181378
+Ref: Internal File Ops-Footnote-1971479
+Node: Using Internal File Ops971619
+Ref: Using Internal File Ops-Footnote-1973975
+Node: Extension Samples974241
+Node: Extension Sample File Functions975684
+Node: Extension Sample Fnmatch984157
+Node: Extension Sample Fork985883
+Node: Extension Sample Ord987097
+Node: Extension Sample Readdir987873
+Node: Extension Sample Revout989377
+Node: Extension Sample Rev2way989970
+Node: Extension Sample Read write array990660
+Node: Extension Sample Readfile992543
+Node: Extension Sample API Tests993298
+Node: Extension Sample Time993823
+Node: gawkextlib995130
+Node: Language History997511
+Node: V7/SVR3.1999033
+Node: SVR41001354
+Node: POSIX1002796
+Node: BTL1003804
+Node: POSIX/GNU1004538
+Node: Common Extensions1010073
+Node: Ranges and Locales1011180
+Ref: Ranges and Locales-Footnote-11015798
+Ref: Ranges and Locales-Footnote-21015825
+Ref: Ranges and Locales-Footnote-31016085
+Node: Contributors1016306
+Node: Installation1020602
+Node: Gawk Distribution1021496
+Node: Getting1021980
+Node: Extracting1022806
+Node: Distribution contents1024498
+Node: Unix Installation1029720
+Node: Quick Installation1030337
+Node: Additional Configuration Options1032299
+Node: Configuration Philosophy1033776
+Node: Non-Unix Installation1036118
+Node: PC Installation1036576
+Node: PC Binary Installation1037875
+Node: PC Compiling1039723
+Node: PC Testing1042667
+Node: PC Using1043843
+Node: Cygwin1048028
+Node: MSYS1049028
+Node: VMS Installation1049542
+Node: VMS Compilation1050145
+Ref: VMS Compilation-Footnote-11051152
+Node: VMS Installation Details1051210
+Node: VMS Running1052845
+Node: VMS Old Gawk1054452
+Node: Bugs1054926
+Node: Other Versions1058778
+Node: Notes1064093
+Node: Compatibility Mode1064680
+Node: Additions1065463
+Node: Accessing The Source1066390
+Node: Adding Code1067816
+Node: New Ports1073858
+Node: Derived Files1077993
+Ref: Derived Files-Footnote-11083301
+Ref: Derived Files-Footnote-21083335
+Ref: Derived Files-Footnote-31083935
+Node: Future Extensions1084033
+Node: Basic Concepts1085520
+Node: Basic High Level1086201
+Ref: figure-general-flow1086472
+Ref: figure-process-flow1087071
+Ref: Basic High Level-Footnote-11090300
+Node: Basic Data Typing1090485
+Node: Glossary1093840
+Node: Copying1119151
+Node: GNU Free Documentation License1156708
+Node: Index1181845
 
 End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index 692811c0..f03cccd0 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -30927,7 +30927,7 @@ Finally, the function returns the return value to the @command{awk} level:
 @}
 @end example
 
-The @code{stat()} built-in is more involved.  First comes a function
+The @code{stat()} extension is more involved.  First comes a function
 that turns a numeric mode into a printable representation
 (e.g., 644 becomes @samp{-rw-r--r--}). This is omitted here for brevity:
 
@@ -31121,16 +31121,21 @@ do_stat(int nargs, awk_value_t *result)
     awk_array_t array;
     int ret;
     struct stat sbuf;
+    int (*statfunc)(const char *path, struct stat *sbuf) = lstat;   /* default */
 
     assert(result != NULL);
 
-    if (do_lint && nargs != 2) @{
-        lintwarn(ext_id,
-                 _("stat: called with wrong number of arguments"));
+    if (nargs != 2 && nargs != 3) @{
+        if (do_lint)
+            lintwarn(ext_id, _("stat: called with wrong number of arguments"));
         return make_number(-1, result);
     @}
 @end example
 
+The third argument to @code{stat()} was not discussed previously. This argument
+is optional. If present, it causes @code{stat()} to use the @code{stat()}
+system call instead of the @code{lstat()} system call.
+
 Then comes the actual work. First, the function gets the arguments.
 Next, it gets the information for the file.
 The code use @code{lstat()} (instead of @code{stat()})
@@ -31146,14 +31151,18 @@ If there's an error, it sets @code{ERRNO} and returns:
         return make_number(-1, result);
     @}
 
+    if (nargs == 3) @{
+        statfunc = stat;
+    @}
+
     name = file_param.str_value.str;
     array = array_param.array_cookie;
 
     /* always empty out the array */
     clear_array(array);
 
-    /* lstat the file, if error, set ERRNO and return */
-    ret = lstat(name, & sbuf);
+    /* stat the file, if error, set ERRNO and return */
+    ret = statfunc(name, & sbuf);
     if (ret < 0) @{
         update_ERRNO_int(errno);
         return make_number(ret, result);
@@ -31336,12 +31345,15 @@ system call to change the current directory.  It returns zero
 upon success or less than zero upon error.  In the latter case it updates
 @code{ERRNO}.
 
-@item result = stat("/some/path", statdata)
+@item result = stat("/some/path", statdata [, follow])
 The @code{stat()} function provides a hook into the
-@code{stat()} system call. In fact, it uses @code{lstat()}.
+@code{stat()} system call.
 It returns zero upon success or less than zero upon error.
 In the latter case it updates @code{ERRNO}.
 
+By default, it uses the @code{lstat()} system call.  However, if passed
+a third argument, it uses @code{stat()} instead.
+
 In all cases, it clears the @code{statdata} array.
 When the call is successful, @code{stat()} fills the @code{statdata}
 array with information retrieved from the filesystem, as follows:
diff --git a/extension/ChangeLog b/extension/ChangeLog
index f581eef3..ca47bf65 100644
--- a/extension/ChangeLog
+++ b/extension/ChangeLog
@@ -1,3 +1,9 @@
+2012-11-21         Arnold D. Robbins     <arnold@skeeve.com>
+
+	* filefuncs.c (do_stat): Optional third argument indicates to
+	use stat(2) instead of lstat(2).
+	* filefuncs.3am: Document same.
+
 2012-11-19         Arnold D. Robbins     <arnold@skeeve.com>
 
 	* readdir.c: Simplify code to always print file type and not
diff --git a/extension/filefuncs.3am b/extension/filefuncs.3am
index e0caba05..23800c47 100644
--- a/extension/filefuncs.3am
+++ b/extension/filefuncs.3am
@@ -1,4 +1,4 @@
-.TH FILEFUNCS 3am "Aug 08 2012" "Free Software Foundation" "GNU Awk Extension Modules"
+.TH FILEFUNCS 3am "Nov 21 2012" "Free Software Foundation" "GNU Awk Extension Modules"
 .SH NAME
 filefuncs \- provide some file related functionality to gawk
 .SH SYNOPSIS
@@ -7,7 +7,7 @@ filefuncs \- provide some file related functionality to gawk
 .sp
 result = chdir("/some/directory")
 .sp
-result = stat("/some/path", statdata)
+result = stat("/some/path", statdata [, follow])
 .sp
 flags = or(FTS_PHYSICAL, ...)
 .br
@@ -33,12 +33,16 @@ The
 .B stat()
 function provides a hook into the
 .IR stat (2)
-system call. In fact, it uses
-.IR lstat (2).
+system call.
 It returns zero
 upon success or less than zero upon error.
 In the latter case it updates
 .BR ERRNO .
+By default, it uses
+.IR lstat (2).
+However, if passed a third argument, it uses
+.IR stat (2),
+instead.
 .PP
 In all cases, it clears the
 .B statdata
diff --git a/extension/filefuncs.c b/extension/filefuncs.c
index 391ed11a..c8ef0534 100644
--- a/extension/filefuncs.c
+++ b/extension/filefuncs.c
@@ -341,11 +341,13 @@ do_stat(int nargs, awk_value_t *result)
 	awk_array_t array;
 	int ret;
 	struct stat sbuf;
+	int (*statfunc)(const char *path, struct stat *sbuf) = lstat;	/* default */
 
 	assert(result != NULL);
 
-	if (do_lint && nargs != 2) {
-		lintwarn(ext_id, _("stat: called with wrong number of arguments"));
+	if (nargs != 2 && nargs != 3) {
+		if (do_lint)
+			lintwarn(ext_id, _("stat: called with wrong number of arguments"));
 		return make_number(-1, result);
 	}
 
@@ -355,6 +357,10 @@ do_stat(int nargs, awk_value_t *result)
 		warning(ext_id, _("stat: bad parameters"));
 		return make_number(-1, result);
 	}
+	
+	if (nargs == 3) {
+		statfunc = stat;
+	}
 
 	name = file_param.str_value.str;
 	array = array_param.array_cookie;
@@ -362,8 +368,8 @@ do_stat(int nargs, awk_value_t *result)
 	/* always empty out the array */
 	clear_array(array);
 
-	/* lstat the file, if error, set ERRNO and return */
-	ret = lstat(name, & sbuf);
+	/* stat the file, if error, set ERRNO and return */
+	ret = statfunc(name, & sbuf);
 	if (ret < 0) {
 		update_ERRNO_int(errno);
 		return make_number(ret, result);