Merge branch 'xgawk'

1 files changed, 94 insertions, 20 deletions

diff --git a/doc/gawk.texi b/doc/gawk.texi
index 22215d93..d3f5c672 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -355,9 +355,12 @@ particular records in a file and perform operations upon them.
                                    uses.
 * AWKPATH Variable::               Searching directories for @command{awk}
                                    programs.
+* AWKLIBPATH Variable::            Searching directories for @command{awk}
+                                   shared libraries.
 * Other Environment Variables::    The environment variables.
 * Exit Status::                    @command{gawk}'s exit status.
 * Include Files::                  Including other files into your program.
+* Loading Shared Libraries::       Loading shared libraries into your program.
 * Obsolete::                       Obsolete Options and/or features.
 * Undocumented::                   Undocumented Options and Features.
 * Regexp Usage::                   How to Use Regular Expressions.
@@ -2927,6 +2930,7 @@ things in this @value{CHAPTER} that don't interest you right now.
 * Environment Variables::       The environment variables @command{gawk} uses.
 * Exit Status::                 @command{gawk}'s exit status.
 * Include Files::               Including other files into your program.
+* Loading Shared Libraries::    Loading shared libraries into your program.
 * Obsolete::                    Obsolete Options and/or features.
 * Undocumented::                Undocumented Options and Features.
 @end menu
@@ -3212,9 +3216,12 @@ that @command{gawk} accepts and then exit.
 @cindex @code{-l} option
 @cindex @code{--load} option
 @cindex loading, library
-Load a shared library @var{lib}. This searches for the library using the @env{AWKPATH}
-environment variable. The suffix @samp{.so} in the library name is optional.
+Load a shared library @var{lib}. This searches for the library using the @env{AWKLIBPATH}
+environment variable.  The correct library suffix for your platform will be
+supplied by default, so it need not be specified in the library name.
 The library initialization routine should be named @code{dlload()}.
+An alternative is to use the @samp{@@load} keyword inside the program to load
+a shared library.
 
 @item -L @r{[}value@r{]}
 @itemx --lint@r{[}=value@r{]}
@@ -3593,6 +3600,8 @@ behaves.
 @menu
 * AWKPATH Variable::            Searching directories for @command{awk}
                                 programs.
+* AWKLIBPATH Variable::         Searching directories for @command{awk}
+                                shared libraries.
 * Other Environment Variables:: The environment variables.
 @end menu
 
@@ -3668,6 +3677,21 @@ sense: the @env{AWKPATH} environment variable is used to find the program
 source files.  Once your program is running, all the files have been
 found, and @command{gawk} no longer needs to use @env{AWKPATH}.
 
+@node AWKLIBPATH Variable
+@subsection The @env{AWKLIBPATH} Environment Variable
+@cindex @env{AWKLIBPATH} environment variable
+@cindex directories, searching
+@cindex search paths
+@cindex search paths, for shared libraries
+@cindex differences in @command{awk} and @command{gawk}, @code{AWKLIBPATH} environment variable
+
+The @env{AWKLIBPATH} environment variable is similar to the @env{AWKPATH}
+variable, but it is used to search for shared libraries specified
+with the @option{-l} option rather than for source files.  If the library
+is not found, the path is searched again after adding the appropriate
+shared library suffix for the platform.  For example, on GNU/Linux systems,
+the suffix @samp{.so} is used.
+
 @node Other Environment Variables
 @subsection Other Environment Variables
 
@@ -3876,6 +3900,41 @@ As mentioned in @ref{AWKPATH Variable}, the current directory is always
 searched first for source files, before searching in @env{AWKPATH},
 and this also applies to files named with @samp{@@include}.
 
+@node Loading Shared Libraries
+@section Loading Shared Libraries Into Your Program
+
+This @value{SECTION} describes a feature that is specific to @command{gawk}.
+
+The @samp{@@load} keyword can be used to read external @command{awk} shared
+libraries.  This allows you to link in compiled code that may offer superior
+performance and/or give you access to extended capabilities not supported 
+by the @command{awk} language.  The @env{AWKLIBPATH} variable is used to
+search for the shared library.  Using @samp{@@load} is completely equivalent
+to using the @option{-l} command-line option.
+
+If the shared library is not initially found in @env{AWKLIBPATH}, another
+search is conducted after appending the platform's default shared library
+suffix to the filename.  For example, on GNU/Linux systems, the suffix
+@samp{.so} is used.
+
+@example
+$ @kbd{gawk '@@load "ordchr"; BEGIN @{print chr(65)@}'}
+@print{} A
+@end example
+
+@noindent
+This is equivalent to the following example:
+
+@example
+$ @kbd{gawk -lordchr 'BEGIN @{print chr(65)@}'}
+@print{} A
+@end example
+
+@noindent
+For command-line usage, the @option{-l} option is more convenient,
+but @samp{@@load} is useful for embedding inside an @command{awk} source file
+that requires access to a shared library.
+
 @node Obsolete
 @section Obsolete Options and/or Features
 
@@ -12797,7 +12856,9 @@ does not affect the environment passed on to any programs that
 Some operating systems may not have environment variables.
 On such systems, the @code{ENVIRON} array is empty (except for
 @w{@code{ENVIRON["AWKPATH"]}},
-@pxref{AWKPATH Variable}).
+@pxref{AWKPATH Variable} and
+@w{@code{ENVIRON["AWKLIBPATH"]}},
+@pxref{AWKLIBPATH Variable}).
 
 @cindex @command{gawk}, @code{ERRNO} variable in
 @cindex @code{ERRNO} variable
@@ -27959,6 +28020,11 @@ the @option{-f} command-line option
 (@pxref{Options}).
 
 @item
+The @env{AWKLIBPATH} environment variable for specifying a path search for
+the @option{-l} command-line option
+(@pxref{Options}).
+
+@item
 The ability to use GNU-style long-named options that start with @option{--}
 and the
 @option{--characters-as-bytes},
@@ -30328,21 +30394,29 @@ This is a convenience macro that calls @code{get_actual_argument()}.
 @cindex functions, return values@comma{} setting
 
 @cindex @code{ERRNO} variable
-@cindex @code{update_ERRNO()} internal function
-@cindex internal function, @code{update_ERRNO()}
-@item void update_ERRNO(void)
+@cindex @code{update_ERRNO_int()} internal function
+@cindex internal function, @code{update_ERRNO_int()}
+@item void update_ERRNO_int(int errno_saved)
 This function is called from within a C extension function to set
-the value of @command{gawk}'s @code{ERRNO} variable, based on the current
-value of the C @code{errno} global variable.
+the value of @command{gawk}'s @code{ERRNO} variable, based on the error
+value provided as the argument.
 It is provided as a convenience.
 
 @cindex @code{ERRNO} variable
-@cindex @code{update_ERRNO_saved()} internal function
-@cindex internal function, @code{update_ERRNO_saved()}
-@item void update_ERRNO_saved(int errno_saved)
+@cindex @code{update_ERRNO_string()} internal function
+@cindex internal function, @code{update_ERRNO_string()}
+@item void update_ERRNO_string(const char *string, enum errno_translate)
 This function is called from within a C extension function to set
-the value of @command{gawk}'s @code{ERRNO} variable, based on the error
-value provided as the argument.
+the value of @command{gawk}'s @code{ERRNO} variable to a given string.
+The second argument determines whether the string is translated before being
+installed into @code{ERRNO}.  It is provided as a convenience.
+
+@cindex @code{ERRNO} variable
+@cindex @code{unset_ERRNO()} internal function
+@cindex internal function, @code{unset_ERRNO()}
+@item void unset_ERRNO(void)
+This function is called from within a C extension function to set
+the value of @command{gawk}'s @code{ERRNO} variable to a null string.
 It is provided as a convenience.
 
 @cindex @code{ENVIRON} array
@@ -30468,11 +30542,11 @@ anywhere in the program.
 
 @command{gawk} has a list of directories where it searches for libraries.
 By default, the list includes directories that depend upon how gawk was built
-and installed (@pxref{AWKPATH Variable}). If you want @command{gawk}
+and installed (@pxref{AWKLIBPATH Variable}). If you want @command{gawk}
 to look for libraries in your private directory, you have to tell it.
-The way to do it is to set the @env{AWKPATH} environment variable
-(@pxref{AWKPATH Variable}).
-@command{gawk} supplies the default suffix @samp{.so} if it is not
+The way to do it is to set the @env{AWKLIBPATH} environment variable
+(@pxref{AWKLIBPATH Variable}).
+@command{gawk} supplies the default shared library platform suffix if it is not
 present in the name of the library.
 If the name of your library is @file{mylib.so}, you can simply type
 
@@ -30484,7 +30558,7 @@ and @command{gawk} will do everything necessary to load in your library,
 and then call your @code{dlload()} routine.
 
 You can always specify the library using an absolute pathname, in which
-case @command{gawk} will not use @env{AWKPATH} to search for it.
+case @command{gawk} will not use @env{AWKLIBPATH} to search for it.
 
 @node Sample Library
 @appendixsubsec Example: Directory and File Operation Built-ins
@@ -30706,7 +30780,7 @@ is updated.
     (void) force_string(newdir);
     ret = chdir(newdir->stptr);
     if (ret < 0)
-        update_ERRNO();
+        update_ERRNO_int(errno);
 @end example
 
 Finally, the function returns the return value to the @command{awk} level:
@@ -30775,7 +30849,7 @@ If there's an error, it sets @code{ERRNO} and returns:
     (void) force_string(file);
     ret = lstat(file->stptr, & sbuf);
     if (ret < 0) @{
-        update_ERRNO();
+        update_ERRNO_int(errno);
         return make_number((AWKNUM) ret);
     @}
 @end example