diff options
Diffstat (limited to 'doc/gawk.texi')
| -rw-r--r-- | doc/gawk.texi | 114 |
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 |