The grand merge: dgawk and pgawk folded into gawk.

1 files changed, 255 insertions, 189 deletions

diff --git a/doc/gawk.texi b/doc/gawk.texi
index dfd620f6..13681850 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -290,7 +290,7 @@ particular records in a file and perform operations upon them.
 * Library Functions::              A Library of @command{awk} Functions.
 * Sample Programs::                Many @command{awk} programs with complete
                                    explanations.
-* Debugger::                       The @code{dgawk} debugger.
+* Debugger::                       The @code{gawk} debugger.
 * Language History::               The evolution of the @command{awk}
                                    language.
 * Installation::                   Installing @command{gawk} under various
@@ -614,23 +614,23 @@ particular records in a file and perform operations upon them.
 * Anagram Program::                Finding anagrams from a dictionary.
 * Signature Program::              People do amazing things with too much time
                                    on their hands.
-* Debugging::                      Introduction to @command{dgawk}.
-* Debugging Concepts::             Debugging In General.
+* Debugging::                      Introduction to @command{gawk} Debugger.
+* Debugging Concepts::             Debugging in General.
 * Debugging Terms::                Additional Debugging Concepts.
 * Awk Debugging::                  Awk Debugging.
-* Sample dgawk session::           Sample @command{dgawk} session.
-* dgawk invocation::               @command{dgawk} Invocation.
-* Finding The Bug::                Finding The Bug.
-* List of Debugger Commands::      Main @command{dgawk} Commands.
-* Breakpoint Control::             Control of breakpoints.
-* Dgawk Execution Control::        Control of execution.
-* Viewing And Changing Data::      Viewing and changing data.
-* Dgawk Stack::                    Dealing with the stack.
-* Dgawk Info::                     Obtaining information about the program and
-                                   the debugger state.
-* Miscellaneous Dgawk Commands::   Miscellaneous Commands.
+* Sample Debugging Session::       Sample Debugging Session.
+* Debugger Invocation::            How to Start the Debugger.
+* Finding The Bug::                Finding the Bug.
+* List of Debugger Commands::      Main Commands.
+* Breakpoint Control::             Control of Breakpoints.
+* Debugger Execution Control::     Control of Execution.
+* Viewing And Changing Data::      Viewing and Changing Data.
+* Execution Stack::                Dealing with the Stack.
+* Debugger Info::                  Obtaining Information about the Program and
+                                   the Debugger State.
+* Miscellaneous Debugger Commands:: Miscellaneous Commands.
 * Readline Support::               Readline Support.
-* Dgawk Limitations::              Limitations and future plans.
+* Limitations::                    Limitations and Future Plans.
 * V7/SVR3.1::                      The major changes between V7 and System V
                                    Release 3.1.
 * SVR4::                           Minor changes between System V Releases 3.1
@@ -686,6 +686,7 @@ particular records in a file and perform operations upon them.
 * Internals::                      A brief look at some @command{gawk}
                                    internals.
 * Plugin License::                 A note about licensing.
+* Loading Extensions::             How to load dynamic extensions.
 * Sample Library::                 A example of new functions.
 * Internal File Description::      What the new functions will do.
 * Internal File Ops::              The code for internal file operations.
@@ -1164,8 +1165,7 @@ provide many sample @command{awk} programs.
 Reading them allows you to see @command{awk}
 solving real problems.
 
-@ref{Debugger}, describes the @command{awk} debugger,
-@command{dgawk}.
+@ref{Debugger}, describes the @command{awk} debugger.
 
 @ref{Language History},
 describes how the @command{awk} language has evolved since
@@ -3101,6 +3101,19 @@ inadvertently use global variables that you meant to be local.
 (This is a particularly easy mistake to make with simple variable
 names like @code{i}, @code{j}, etc.)
 
+@item -D@r{[}@var{file}@r{]}
+@itemx --debug=@r{[}@var{file}@r{]}
+@cindex @code{-D} option
+@cindex @code{--debug} option
+@cindex @command{awk} debugging, enabling
+Enable debugging of @command{awk} programs
+(@pxref{Debugging}).
+By default, the debugger reads commands interactively from the terminal.
+The optional @var{file} argument allows you to specify a file with a list
+of commands for the debugger to execute non-interactively.
+No space is allowed between the @option{-D} and @var{file}, if
+@var{file} is supplied.
+
 @item -e @var{program-text}
 @itemx --source @var{program-text}
 @cindex @code{-e} option
@@ -3166,6 +3179,15 @@ for information about this option.
 Print a ``usage'' message summarizing the short and long style options
 that @command{gawk} accepts and then exit.
 
+@item -l @var{lib}
+@itemx --load @var{lib}
+@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.
+The library initialization routine should be named @code{dlload()}.
+
 @item -L @r{[}value@r{]}
 @itemx --lint@r{[}=value@r{]}
 @cindex @code{-l} option
@@ -3212,6 +3234,18 @@ Use with care.
 Force the use of the locale's decimal point character
 when parsing numeric input data (@pxref{Locales}).
 
+@item -o@r{[}@var{file}@r{]}
+@itemx --pretty-print@r{[}=@var{file}@r{]}
+@cindex @code{-o} option
+@cindex @code{--pretty-print} option
+@cindex @command{awk} enabling
+Enable pretty-printing of @command{awk} programs.
+By default, output program is created in a file named @file{awkprof.out}.
+The optional @var{file} argument allows you to specify a different
+@value{FN} for the output.
+No space is allowed between the @option{-o} and @var{file}, if
+@var{file} is supplied.
+
 @item -O
 @itemx --optimize
 @cindex @code{--optimize} option
@@ -3224,7 +3258,7 @@ maintainer hopes to add more optimizations over time.
 @itemx --profile@r{[}=@var{file}@r{]}
 @cindex @code{-p} option
 @cindex @code{--profile} option
-@cindex @command{awk} programs, profiling, enabling
+@cindex @command{awk} profiling, enabling
 Enable profiling of @command{awk} programs
 (@pxref{Profiling}).
 By default, profiles are created in a file named @file{awkprof.out}.
@@ -3233,10 +3267,8 @@ The optional @var{file} argument allows you to specify a different
 No space is allowed between the @option{-p} and @var{file}, if
 @var{file} is supplied.
 
-When run with @command{gawk}, the profile is just a ``pretty printed'' version
-of the program.  When run with @command{pgawk}, the profile contains execution
-counts for each statement in the program in the left margin, and function
-call counts for each function.
+The profile contains execution counts for each statement in the program
+in the left margin, and function call counts for each function.
 
 @item -P
 @itemx --posix
@@ -3300,14 +3332,6 @@ This is now @command{gawk}'s default behavior.
 Nevertheless, this option remains both for backward compatibility,
 and for use in combination with the @option{--traditional} option.
 
-@item -R @var{file}
-@itemx --command=@var{file}
-@cindex @code{-R} option
-@cindex @code{--command} option
-@command{dgawk} only.
-Read @command{dgawk} debugger options and commands from @var{file}.
-@xref{Dgawk Info}, for more information.
-
 @item -S
 @itemx --sandbox
 @cindex @code{-S} option
@@ -3704,7 +3728,7 @@ into smaller, more manageable pieces, and also lets you reuse common @command{aw
 code from various @command{awk} scripts.  In other words, you can group
 together @command{awk} functions, used to carry out specific tasks,
 into external files. These files can be used just like function libraries,
-using the @samp{@@include} keyword in conjunction with the @code{AWKPATH}
+using the @samp{@@include} keyword in conjunction with the @env{AWKPATH}
 environment variable.
 
 Let's see an example.
@@ -18954,40 +18978,32 @@ extensive examples.
 @cindex @command{awk} programs, profiling
 @c STARTOFRANGE proawk
 @cindex profiling @command{awk} programs
-@c STARTOFRANGE pgawk
-@cindex @command{pgawk} program
-@cindex profiling @command{gawk}, See @command{pgawk} program
-
-You may produce execution
-traces of your @command{awk} programs.
-This is done with a specially compiled version of @command{gawk},
-called @command{pgawk} (``profiling @command{gawk}'').
-
+@cindex profiling @command{gawk}
 @cindex @code{awkprof.out} file
 @cindex files, @code{awkprof.out}
-@cindex @command{pgawk} program, @code{awkprof.out} file
-@command{pgawk} is identical in every way to @command{gawk}, except that when
-it has finished running, it creates a profile of your program in a file
-named @file{awkprof.out}.
-Because it is profiling, it also executes up to 45% slower than
+
+You may produce execution traces of your @command{awk} programs.
+This is done by passing the option @option{--profile} to @command{gawk}.
+When @command{gawk} has finished running, it creates a profile of your program in a file
+named @file{awkprof.out}. Because it is profiling, it also executes up to 45% slower than
 @command{gawk} normally does.
 
 @cindex @code{--profile} option
 As shown in the following example,
 the @option{--profile} option can be used to change the name of the file
-where @command{pgawk} will write the profile:
+where @command{gawk} will write the profile:
 
 @example
-pgawk --profile=myprog.prof -f myprog.awk data1 data2
+gawk --profile=myprog.prof -f myprog.awk data1 data2
 @end example
 
 @noindent
-In the above example, @command{pgawk} places the profile in
+In the above example, @command{gawk} places the profile in
 @file{myprog.prof} instead of in @file{awkprof.out}.
 
-Here is a sample
-session showing a simple @command{awk} program, its input data, and the
-results from running @command{pgawk}.  First, the @command{awk} program:
+Here is a sample session showing a simple @command{awk} program, its input data, and the
+results from running @command{gawk} with the @option{--profile} option.
+First, the @command{awk} program:
 
 @example
 BEGIN @{ print "First BEGIN rule" @}
@@ -19027,12 +19043,12 @@ foo
 junk
 @end example
 
-Here is the @file{awkprof.out} that results from running @command{pgawk}
-on this program and data (this example also illustrates that @command{awk}
+Here is the @file{awkprof.out} that results from running the @command{gawk}
+profiler on this program and data (this example also illustrates that @command{awk}
 programmers sometimes have to work late):
 
-@cindex @code{BEGIN} pattern, @command{pgawk} program
-@cindex @code{END} pattern, @command{pgawk} program
+@cindex @code{BEGIN} pattern
+@cindex @code{END} pattern
 @example
         # gawk profile, created Sun Aug 13 00:00:15 2000
 
@@ -19124,15 +19140,15 @@ keyword indicates how many times the function was called.
 The counts next to the statements in the body show how many times
 those statements were executed.
 
-@cindex @code{@{@}} (braces), @command{pgawk} program
-@cindex braces (@code{@{@}}), @command{pgawk} program
+@cindex @code{@{@}} (braces)
+@cindex braces (@code{@{@}})
 @item
 The layout uses ``K&R'' style with TABs.
 Braces are used everywhere, even when
 the body of an @code{if}, @code{else}, or loop is only a single statement.
 
-@cindex @code{()} (parentheses), @command{pgawk} program
-@cindex parentheses @code{()}, @command{pgawk} program
+@cindex @code{()} (parentheses)
+@cindex parentheses @code{()}
 @item
 Parentheses are used only where needed, as indicated by the structure
 of the program and the precedence rules.
@@ -19155,16 +19171,16 @@ Similarly, if
 the target of a redirection isn't a scalar, it gets parenthesized.
 
 @item
-@command{pgawk} supplies leading comments in
+@command{gawk} supplies leading comments in
 front of the @code{BEGIN} and @code{END} rules,
 the pattern/action rules, and the functions.
 
 @end itemize
 
 The profiled version of your program may not look exactly like what you
-typed when you wrote it.  This is because @command{pgawk} creates the
+typed when you wrote it.  This is because @command{gawk} creates the
 profiled version by ``pretty printing'' its internal representation of
-the program.  The advantage to this is that @command{pgawk} can produce
+the program.  The advantage to this is that @command{gawk} can produce
 a standard representation.  The disadvantage is that all source-code
 comments are lost, as are the distinctions among multiple @code{BEGIN},
 @code{END}, @code{BEGINFILE}, and @code{ENDFILE} rules.  Also, things such as:
@@ -19186,15 +19202,16 @@ come out as:
 which is correct, but possibly surprising.
 
 @cindex profiling @command{awk} programs, dynamically
-@cindex @command{pgawk} program, dynamic profiling
+@cindex @command{gawk} program, dynamic profiling
 Besides creating profiles when a program has completed,
-@command{pgawk} can produce a profile while it is running.
+@command{gawk} can produce a profile while it is running.
 This is useful if your @command{awk} program goes into an
 infinite loop and you want to see what has been executed.
-To use this feature, run @command{pgawk} in the background:
+To use this feature, run @command{gawk} with the @option{--profile}
+option in the background:
 
 @example
-$ @kbd{pgawk -f myprog &}
+$ @kbd{gawk --profile -f myprog &}
 [1] 13992
 @end example
 
@@ -19205,7 +19222,7 @@ $ @kbd{pgawk -f myprog &}
 @noindent
 The shell prints a job number and process ID number; in this case, 13992.
 Use the @command{kill} command to send the @code{USR1} signal
-to @command{pgawk}:
+to @command{gawk}:
 
 @example
 $ @kbd{kill -USR1 13992}
@@ -19213,8 +19230,8 @@ $ @kbd{kill -USR1 13992}
 
 @noindent
 As usual, the profiled version of the program is written to
-@file{awkprof.out}, or to a different file if you use the @option{--profile}
-option.
+@file{awkprof.out}, or to a different file if one specified with
+the @option{--profile} option.
 
 Along with the regular profile, as shown earlier, the profile
 includes a trace of any active functions:
@@ -19228,7 +19245,7 @@ includes a trace of any active functions:
 # -- main --
 @end example
 
-You may send @command{pgawk} the @code{USR1} signal as many times as you like.
+You may send @command{gawk} the @code{USR1} signal as many times as you like.
 Each time, the profile and function call trace are appended to the output
 profile file.
 
@@ -19236,7 +19253,7 @@ profile file.
 @cindex @code{SIGHUP} signal
 @cindex signals, @code{HUP}/@code{SIGHUP}
 If you use the @code{HUP} signal instead of the @code{USR1} signal,
-@command{pgawk} produces the profile and the function call trace and then exits.
+@command{gawk} produces the profile and the function call trace and then exits.
 
 @cindex @code{INT} signal (MS-Windows)
 @cindex @code{SIGINT} signal (MS-Windows)
@@ -19244,21 +19261,20 @@ If you use the @code{HUP} signal instead of the @code{USR1} signal,
 @cindex @code{QUIT} signal (MS-Windows)
 @cindex @code{SIGQUIT} signal (MS-Windows)
 @cindex signals, @code{QUIT}/@code{SIGQUIT} (MS-Windows)
-When @command{pgawk} runs on MS-Windows systems, it uses the
+When @command{gawk} runs on MS-Windows systems, it uses the
 @code{INT} and @code{QUIT} signals for producing the profile and, in
-the case of the @code{INT} signal, @command{pgawk} exits.  This is
+the case of the @code{INT} signal, @command{gawk} exits.  This is
 because these systems don't support the @command{kill} command, so the
 only signals you can deliver to a program are those generated by the
 keyboard.  The @code{INT} signal is generated by the
 @kbd{@value{CTL}-@key{C}} or @kbd{@value{CTL}-@key{BREAK}} key, while the
 @code{QUIT} signal is generated by the @kbd{@value{CTL}-@key{\}} key.
 
-Finally, regular @command{gawk} also accepts the @option{--profile} option.
+Finally, @command{gawk} also accepts another option @option{--pretty-print}.
 When called this way, @command{gawk} ``pretty prints'' the program into
 @file{awkprof.out}, without any execution counts.
 @c ENDOFRANGE advgaw
 @c ENDOFRANGE gawadv
-@c ENDOFRANGE pgawk
 @c ENDOFRANGE awkp
 @c ENDOFRANGE proawk
 
@@ -25140,41 +25156,41 @@ BEGIN {
 @c FIXME: Add more indexing.
 
 @node Debugger
-@chapter @command{dgawk}: The @command{awk} Debugger
-@cindex @command{dgawk}
+@chapter Debugging @command{awk} Programs
+@cindex debugging @command{awk} programs
 
 It would be nice if computer programs worked perfectly the first time they
 were run, but in real life, this rarely happens for programs of
 any complexity.  Thus, most programming languages have facilities available
 for ``debugging'' programs, and now @command{awk} is no exception.
 
-The @command{dgawk} debugger is purposely modeled after
+The @command{gawk} debugger is purposely modeled after
 @uref{http://www.gnu.org/software/gdb/, the GNU Debugger (GDB)}
 command-line debugger.  If you are familiar with GDB, learning
-@command{dgawk} is easy.
+how to use @command{gawk} for debugging your program is easy.
 
 @menu
-* Debugging::                   Introduction to @command{dgawk}.
-* Sample dgawk session::        Sample @command{dgawk} session.
-* List of Debugger Commands::   Main @command{dgawk} Commands.
-* Readline Support::            Readline Support.
-* Dgawk Limitations::           Limitations and future plans.
+* Debugging::                   Introduction to @command{gawk} debugger.
+* Sample Debugging Session::    Sample debugging session.
+* List of Debugger Commands::   Main debugger commands.
+* Readline Support::            Readline support.
+* Limitations::                 Limitations and future plans.
 @end menu
 
 @node Debugging
-@section Introduction to @command{dgawk}
+@section Introduction to @command{gawk} Debugger
 
 This @value{SECTION} introduces debugging in general and begins
 the discussion of debugging in @command{gawk}.
 
 @menu
-* Debugging Concepts::          Debugging In General.
+* Debugging Concepts::          Debugging in General.
 * Debugging Terms::             Additional Debugging Concepts.
 * Awk Debugging::               Awk Debugging.
 @end menu
 
 @node Debugging Concepts
-@subsection Debugging In General
+@subsection Debugging in General
 
 (If you have used debuggers in other languages, you may want to skip
 ahead to the next section on the specific features of the @command{awk}
@@ -25220,8 +25236,7 @@ functional program that you or someone else wrote).
 @subsection Additional Debugging Concepts
 
 Before diving in to the details, we need to introduce several
-important concepts that apply to just about all debuggers, including
-@command{dgawk}.
+important concepts that apply to just about all debuggers.
 The following list defines terms used throughout the rest of
 this @value{CHAPTER}.
 
@@ -25240,7 +25255,7 @@ that contains the function's parameters, local variables, and return value,
 as well as any other ``bookkeeping'' information needed to manage the
 call stack.  This data area is termed a @dfn{stack frame}.
 
-@command{gawk} also follows this model, and @command{dgawk} gives you
+@command{gawk} also follows this model, and gives you
 access to the call stack and to each stack frame. You can see the
 call stack, as well as from where each function on the stack was
 invoked. Commands that print the call stack print information about
@@ -25285,48 +25300,48 @@ each line of @command{awk} code.  The debugger provides the opportunity
 to look at the individual primitive instructions carried out
 by the higher-level @command{awk} commands.
 
-@node Sample dgawk session
-@section Sample @command{dgawk} session
+@node Sample Debugging Session
+@section Sample Debugging Session
 
-In order to illustrate the use of @command{dgawk}, let's look at a sample
+In order to illustrate the use of @command{gawk} as a debugger, let's look at a sample
 debugging session.  We will use the @command{awk} implementation of the
 POSIX @command{uniq} command described earlier (@pxref{Uniq Program})
 as our example.
 
 @menu
-* dgawk invocation::            @command{dgawk} Invocation.
-* Finding The Bug::             Finding The Bug.
+* Debugger Invocation::         How to Start the Debugger.
+* Finding The Bug::             Finding the Bug.
 @end menu
 
-@node dgawk invocation
-@subsection @command{dgawk} Invocation
+@node Debugger Invocation
+@subsection How to Start the Debugger
 
-Starting @command{dgawk} is exactly like running @command{awk}.  The
-file(s) containing the program and any supporting code are given on the
-command line as arguments to one or more @option{-f} options.
-(@command{dgawk} is not designed to debug command-line
-programs, only programs contained in files.)  In our case,
-we call @command{dgawk} like this:
+Starting the debugger is almost exactly like running @command{awk}, except you have to
+pass an additional option @option{--debug} or the corresponding short option @option{-D}.
+The file(s) containing the program and any supporting code are given on the command
+line as arguments to one or more @option{-f} options. (@command{gawk} is not designed
+to debug command-line programs, only programs contained in files.)  In our case,
+we invoke the debugger like this:
 
 @example
-$ @kbd{dgawk -f getopt.awk -f join.awk -f uniq.awk inputfile}
+$ @kbd{gawk -D -f getopt.awk -f join.awk -f uniq.awk inputfile}
 @end example
 
 @noindent
 where both @file{getopt.awk} and @file{uniq.awk} are in @env{$AWKPATH}.
 (Experienced users of GDB or similar debuggers should note that
 this syntax is slightly different from what they are used to.
-With @command{dgawk}, the arguments for running the program are given
+With @command{gawk} debugger, the arguments for running the program are given
 in the command line to the debugger rather than as part of the @code{run}
 command at the debugger prompt.)
 
 Instead of immediately running the program on @file{inputfile}, as
-@command{gawk} would ordinarily do, @command{dgawk} merely loads all
+@command{gawk} would ordinarily do, the debugger merely loads all
 the program source files, compiles them internally, and then gives
 us a prompt:
 
 @example
-dgawk>
+gawk>
 @end example
 
 @noindent
@@ -25334,7 +25349,7 @@ from which we can issue commands to the debugger.  At this point, no
 code has been executed.
 
 @node Finding The Bug
-@subsection Finding The Bug
+@subsection Finding the Bug
 
 Let's say that we are having a problem using (a faulty version of)
 @file{uniq.awk} in the ``field-skipping'' mode, and it doesn't seem to be
@@ -25370,7 +25385,7 @@ a breakpoint in @file{uniq.awk} is at the beginning of the function
 the breakpoint, use the @code{b} (breakpoint) command:
 
 @example
-dgawk> @kbd{b are_equal}
+gawk> @kbd{b are_equal}
 @print{} Breakpoint 1 set at file `awklib/eg/prog/uniq.awk', line 64
 @end example
 
@@ -25379,22 +25394,22 @@ Now type @samp{r} or @samp{run} and the program runs until it hits
 the breakpoint for the first time:
 
 @example
-dgawk> @kbd{r}
+gawk> @kbd{r}
 @print{} Starting program:
 @print{} Stopping in Rule ...
 @print{} Breakpoint 1, are_equal(n, m, clast, cline, alast, aline)
          at `awklib/eg/prog/uniq.awk':64
 @print{} 64          if (fcount == 0 && charcount == 0)
-dgawk>
+gawk>
 @end example
 
 Now we can look at what's going on inside our program.  First of all,
 let's see how we got to where we are.  At the prompt, we type @samp{bt}
-(short for ``backtrace''), and @command{dgawk} responds with a
+(short for ``backtrace''), and the debugger responds with a
 listing of the current stack frames:
 
 @example
-dgawk> @kbd{bt}
+gawk> @kbd{bt}
 @print{} #0  are_equal(n, m, clast, cline, alast, aline)
          at `awklib/eg/prog/uniq.awk':69
 @print{} #1  in main() at `awklib/eg/prog/uniq.awk':89
@@ -25409,11 +25424,11 @@ the key to finding the source of the problem.)
 Now that we're in @code{are_equal()}, we can start looking at the values
 of some variables.  Let's say we type @samp{p n}
 (@code{p} is short for ``print'').  We would expect to see the value of
-@code{n}, a parameter to @code{are_equal()}.  Actually, @command{dgawk}
+@code{n}, a parameter to @code{are_equal()}.  Actually, the debugger
 gives us:
 
 @example
-dgawk> @kbd{p n}
+gawk> @kbd{p n}
 @print{} n = untyped variable
 @end example
 
@@ -25424,7 +25439,7 @@ function was called without arguments (@pxref{Function Calls}).
 A more useful variable to display might be the current record:
 
 @example
-dgawk> @kbd{p $0}
+gawk> @kbd{p $0}
 @print{} $0 = string ("gawk is a wonderful program!")
 @end example
 
@@ -25433,7 +25448,7 @@ This might be a bit puzzling at first since this is the second line of
 our test input above.  Let's look at @code{NR}:
 
 @example
-dgawk> @kbd{p NR}
+gawk> @kbd{p NR}
 @print{} NR = number (2)
 @end example
 
@@ -25452,7 +25467,7 @@ NR == 1 @{
 OK, let's just check that that rule worked correctly:
 
 @example
-dgawk> @kbd{p last}
+gawk> @kbd{p last}
 @print{} last = string ("awk is a wonderful program!")
 @end example
 
@@ -25463,7 +25478,7 @@ be inside this function.  To investigate further, we must begin
 @samp{n} (for ``next''):
 
 @example
-dgawk> @kbd{n}
+gawk> @kbd{n}
 @print{} 67          if (fcount > 0) @{
 @end example
 
@@ -25483,9 +25498,9 @@ Continuing to step, we now get to the splitting of the current and
 last records:
 
 @example
-dgawk> @kbd{n}
+gawk> @kbd{n}
 @print{} 68              n = split(last, alast)
-dgawk> @kbd{n}
+gawk> @kbd{n}
 @print{} 69              m = split($0, aline)
 @end example
 
@@ -25493,7 +25508,7 @@ At this point, we should be curious to see what our records were split
 into, so we try to look:
 
 @example
-dgawk> @kbd{p n m alast aline}
+gawk> @kbd{p n m alast aline}
 @print{} n = number (5)
 @print{} m = number (5)
 @print{} alast = array, 5 elements
@@ -25512,7 +25527,7 @@ inside the array?
 The first choice would be to use subscripts:
 
 @example
-dgawk> @kbd{p alast[0]}
+gawk> @kbd{p alast[0]}
 @print{} "0" not in array `alast'
 @end example
 
@@ -25520,16 +25535,16 @@ dgawk> @kbd{p alast[0]}
 Oops!
 
 @example
-dgawk> @kbd{p alast[1]}
+gawk> @kbd{p alast[1]}
 @print{} alast["1"] = string ("awk")
 @end example
 
 This would be kind of slow for a 100-member array, though, so
-@command{dgawk} provides a shortcut (reminiscent of another language
+@command{gawk} provides a shortcut (reminiscent of another language
 not to be mentioned):
 
 @example
-dgawk> @kbd{p @@alast}
+gawk> @kbd{p @@alast}
 @print{} alast["1"] = string ("awk")
 @print{} alast["2"] = string ("is")
 @print{} alast["3"] = string ("a")
@@ -25541,9 +25556,9 @@ It looks like we got this far OK.  Let's take another step
 or two:
 
 @example
-dgawk> @kbd{n}
+gawk> @kbd{n}
 @print{} 70              clast = join(alast, fcount, n)
-dgawk> @kbd{n}
+gawk> @kbd{n}
 @print{} 71              cline = join(aline, fcount, m)
 @end example
 
@@ -25553,7 +25568,7 @@ the virtual record to compare, and if the first field was numbered zero,
 this would work.  Let's look at what we've got:
 
 @example
-dgawk> @kbd{p cline clast}
+gawk> @kbd{p cline clast}
 @print{} cline = string ("gawk is a wonderful program!")
 @print{} clast = string ("awk is a wonderful program!")
 @end example
@@ -25562,10 +25577,10 @@ Hey, those look pretty familiar!  They're just our original, unaltered,
 input records.  A little thinking (the human brain is still the best
 debugging tool), and we realize that we were off by one!
 
-We get out of @command{dgawk}:
+We get out of the debugger:
 
 @example
-dgawk> @kbd{q}
+gawk> @kbd{q}
 @print{} The program is running. Exit anyway (y/n)? @kbd{y}
 @end example
 
@@ -25581,9 +25596,9 @@ cline = join(aline, fcount+1, m)
 and problem solved!
 
 @node List of Debugger Commands
-@section Main @command{dgawk} Commands
+@section Main Debugger Commands
 
-The @command{dgawk} command set can be divided into the
+The @command{gawk} debugger command set can be divided into the
 following categories:
 
 @itemize @bullet{}
@@ -25610,24 +25625,24 @@ Miscellaneous
 Each of these are discussed in the following subsections.
 In the following descriptions, commands which may be abbreviated
 show the abbreviation on a second description line.
-A @command{dgawk} command name may also be truncated if that partial
-name is unambiguous. @command{dgawk} has the built-in capability to
+A debugger command name may also be truncated if that partial
+name is unambiguous. The debugger has the built-in capability to
 automatically repeat the previous command when just hitting @key{Enter}.
 This works for the commands @code{list}, @code{next}, @code{nexti}, @code{step}, @code{stepi}
 and @code{continue} executed without any argument.
 
 @menu
-* Breakpoint Control::          Control of breakpoints.
-* Dgawk Execution Control::     Control of execution.
-* Viewing And Changing Data::   Viewing and changing data.
-* Dgawk Stack::                 Dealing with the stack.
-* Dgawk Info::                  Obtaining information about the program and
-                                the debugger state.
-* Miscellaneous Dgawk Commands:: Miscellaneous Commands.
+* Breakpoint Control::          Control of Breakpoints.
+* Debugger Execution Control::  Control of Execution.
+* Viewing And Changing Data::   Viewing and Changing Data.
+* Execution Stack::             Dealing with the Stack.
+* Debugger Info::               Obtaining Information about the Program and
+                                the Debugger State.
+* Miscellaneous Debugger Commands:: Miscellaneous Commands.
 @end menu
 
 @node Breakpoint Control
-@subsection Control Of Breakpoints
+@subsection Control of Breakpoints
 
 As we saw above, the first thing you probably want to do in a debugging
 session is to get your breakpoints set up, since otherwise your program
@@ -25662,10 +25677,10 @@ Each breakpoint is assigned a number which can be used to delete it from
 the breakpoint list using the @code{delete} command.
 
 With a breakpoint, you may also supply a condition.  This is an
-@command{awk} expression (enclosed in double quotes) that @command{dgawk}
+@command{awk} expression (enclosed in double quotes) that the debugger
 evaluates whenever the breakpoint is reached. If the condition is true,
-then @command{dgawk} stops execution and prompts for a command. Otherwise,
-@command{dgawk} continues executing the program.
+then the debugger stops execution and prompts for a command. Otherwise,
+it continues executing the program.
 
 @cindex debugger commands, @code{clear}
 @cindex @code{clear} debugger command
@@ -25691,10 +25706,10 @@ Delete breakpoint(s) set at entry to function @var{function}.
 @cindex @code{condition} debugger command
 @item @code{condition} @var{n} @code{"@var{expression}"}
 Add a condition to existing breakpoint or watchpoint @var{n}. The
-condition is an @command{awk} expression that @command{dgawk} evaluates
+condition is an @command{awk} expression that the debugger evaluates
 whenever the breakpoint or watchpoint is reached. If the condition is true, then
-@command{dgawk} stops execution and prompts for a command. Otherwise,
-@command{dgawk} continues executing the program. If the condition expression is
+the debugger stops execution and prompts for a command. Otherwise,
+the debugger continues executing the program. If the condition expression is
 not specified, any existing condition is removed; i.e., the breakpoint or
 watchpoint is made unconditional. 
 
@@ -25750,7 +25765,7 @@ Set a temporary breakpoint (enabled for only one stop).
 The arguments are the same as for @code{break}.
 @end table
 
-@node Dgawk Execution Control
+@node Debugger Execution Control
 @subsection Control of Execution
 
 Now that your breakpoints are ready, you can start running the program
@@ -25779,14 +25794,14 @@ in the list that resumes execution (e.g., @code{continue}) terminates the list
 For example:
 
 @example
-dgawk> @kbd{commands}
+gawk> @kbd{commands}
 > @kbd{silent}
 > @kbd{printf "A silent breakpoint; i = %d\n", i}
 > @kbd{info locals}
 > @kbd{set i = 10}
 > @kbd{continue}
 > @kbd{end}
-dgawk>
+gawk>
 @end example
 
 @cindex debugger commands, @code{c} (@code{continue})
@@ -25836,7 +25851,7 @@ and the caller of that frame becomes the innermost frame.
 @cindex @code{r} debugger command (alias for @code{run})
 @item @code{run}
 @itemx @code{r}
-Start/restart execution of the program. When restarting, @command{dgawk}
+Start/restart execution of the program. When restarting, the debugger
 retains the current breakpoints, watchpoints, command history,
 automatic display variables, and debugger options.
 
@@ -25859,7 +25874,7 @@ stopping, unless it encounters a breakpoint or watchpoint.
 @itemx @code{si} [@var{count}]
 Execute one (or @var{count}) instruction(s), stepping inside function calls.
 (For illustration of what is meant by an ``instruction'' in @command{gawk},
-see the output shown under @code{dump} in @ref{Miscellaneous Dgawk Commands}.)
+see the output shown under @code{dump} in @ref{Miscellaneous Debugger Commands}.)
 
 @cindex debugger commands, @code{u} (@code{until})
 @cindex debugger commands, @code{until}
@@ -25887,7 +25902,7 @@ The value of the variable or field is displayed each time the program stops.
 Each variable added to the list is identified by a unique number:
 
 @example
-dgawk> @kbd{display x}
+gawk> @kbd{display x}
 @print{} 10: x = 1
 @end example
 
@@ -25924,7 +25939,7 @@ Print the value of a @command{gawk} variable or field.
 Fields must be referenced by constants:
 
 @example
-dgawk> @kbd{print $3}
+gawk> @kbd{print $3}
 @end example
 
 @noindent
@@ -25966,16 +25981,16 @@ You can also set special @command{awk} variables, such as @code{FS},
 @item @code{watch} @var{var} | @code{$}@var{n} [@code{"@var{expression}"}]
 @itemx @code{w} @var{var} | @code{$}@var{n} [@code{"@var{expression}"}]
 Add variable @var{var} (or field @code{$@var{n}}) to the watch list.
-@command{dgawk} then stops whenever
+The debugger then stops whenever
 the value of the variable or field changes. Each watched item is assigned a
 number which can be used to delete it from the watch list using the
 @code{unwatch} command.
 
 With a watchpoint, you may also supply a condition.  This is an
-@command{awk} expression (enclosed in double quotes) that @command{dgawk}
+@command{awk} expression (enclosed in double quotes) that the debugger
 evaluates whenever the watchpoint is reached. If the condition is true,
-then @command{dgawk} stops execution and prompts for a command. Otherwise,
-@command{dgawk} continues executing the program.
+then the debugger stops execution and prompts for a command. Otherwise,
+@command{gawk} continues executing the program.
 
 @cindex debugger commands, @code{undisplay}
 @cindex @code{undisplay} debugger command
@@ -25991,8 +26006,8 @@ watch list.
 
 @end table
 
-@node Dgawk Stack
-@subsection Dealing With The Stack
+@node Execution Stack
+@subsection Dealing with the Stack
 
 Whenever you run a program which contains any function calls,
 @command{gawk} maintains a stack of all of the function calls leading up
@@ -26036,12 +26051,12 @@ Move @var{count} (default 1) frames up the stack toward the outermost frame.
 Then select and print the frame.
 @end table
 
-@node Dgawk Info
-@subsection Obtaining Information About The Program and The Debugger State
+@node Debugger Info
+@subsection Obtaining Information about the Program and the Debugger State
 
 Besides looking at the values of variables, there is often a need to get
 other sorts of information about the state of your program and of the
-debugging environment itself.  @command{dgawk} has one command which
+debugging environment itself.  The @command{gawk} debugger has one command which
 provides this information, appropriately called @code{info}.  @code{info}
 is used with one of a number of arguments that tell it exactly what
 you want to know:
@@ -26079,7 +26094,7 @@ Local variables of the selected frame.
 @item source
 The name of the current source file. Each time the program stops, the
 current source file is the file containing the current instruction.
-When @command{dgawk} first starts, the current source file is the first file
+When the debugger first starts, the current source file is the first file
 included via the @option{-f} option. The
 @samp{list @var{filename}:@var{lineno}} command can
 be used at any time to change the current source.
@@ -26115,7 +26130,7 @@ The available options are:
 @c nested table
 @table @code
 @item history_size
-The maximum number of lines to keep in the history file @file{./.dgawk_history}.
+The maximum number of lines to keep in the history file @file{./.gawk_history}.
 The default is 100.
 
 @item listsize
@@ -26127,14 +26142,14 @@ to standard output. An empty string (@code{""}) resets output to
 standard output.
 
 @item prompt
-The debugger prompt. The default is @samp{@w{dgawk> }}.
+The debugger prompt. The default is @samp{@w{gawk> }}.
 
 @item save_history @r{[}on @r{|} off@r{]}
-Save command history to file @file{./.dgawk_history}.
+Save command history to file @file{./.gawk_history}.
 The default is @code{on}.
 
 @item save_options @r{[}on @r{|} off@r{]}
-Save current options to file @file{./.dgawkrc} upon exit.
+Save current options to file @file{./.gawkrc} upon exit.
 The default is @code{on}.
 Options are read back in to the next session upon startup.
 
@@ -26154,16 +26169,16 @@ Empty lines are ignored; they do @emph{not}
 repeat the last command.
 You can't restart the program by having more than one @code{run}
 command in the file. Also, the list of commands may include additional
-@code{source} commands; however, @command{dgawk} will not source the
+@code{source} commands; however, the @command{gawk} debugger will not source the
 same file more than once in order to avoid infinite recursion.
 
 In addition to, or instead of the @code{source} command, you can use
-the @option{-R @var{file}} or @option{--command=@var{file}} command-line
+the @option{-D @var{file}} or @option{--debug=@var{file}} command-line
 options to execute commands from a file non-interactively
 (@pxref{Options}.
 @end table
 
-@node Miscellaneous Dgawk Commands
+@node Miscellaneous Debugger Commands
 @subsection Miscellaneous Commands
 
 There are a few more commands which do not fit into the
@@ -26181,7 +26196,7 @@ partial dump of Davide Brini's obfuscated code
 (@pxref{Signature Program}) demonstrates:
 
 @smallexample
-dgawk> @kbd{dump}
+gawk> @kbd{dump}
 @print{}        # BEGIN
 @print{}
 @print{} [     2:0x89faef4] Op_rule             : [in_rule = BEGIN] [source_file = brini.awk]
@@ -26230,7 +26245,7 @@ dgawk> @kbd{dump}
 @print{} [      :0x89fa3b0] Op_after_beginfile  : 
 @print{} [      :0x89fa388] Op_no_op            : 
 @print{} [      :0x89fa3c4] Op_after_endfile    : 
-dgawk>
+gawk>
 @end smallexample
 
 @cindex debugger commands, @code{h} (@code{help})
@@ -26239,7 +26254,7 @@ dgawk>
 @cindex @code{h} debugger command (alias for @code{help})
 @item @code{help}
 @itemx @code{h}
-Print a list of all of the @command{dgawk} commands with a short
+Print a list of all of the @command{gawk} debugger commands with a short
 summary of their usage.  @samp{help @var{command}} prints the information
 about the command @var{command}.
 
@@ -26286,7 +26301,7 @@ function @var{function}. This command may change the current source file.
 Exit the debugger.  Debugging is great fun, but sometimes we all have
 to tend to other obligations in life, and sometimes we find the bug,
 and are free to go on to the next one!  As we saw above, if you are
-running a program, @command{dgawk} warns you if you accidentally type
+running a program, the debugger warns you if you accidentally type
 @samp{q} or @samp{quit}, to make sure you really want to quit.
 
 @cindex debugger commands, @code{trace}
@@ -26305,7 +26320,7 @@ fairly self-explanatory, and using @code{stepi} and @code{nexti} while
 @node Readline Support
 @section Readline Support
 
-If @command{dgawk} is compiled with the @code{readline} library, you
+If @command{gawk} is compiled with the @code{readline} library, you
 can take advantage of that library's command completion and history expansion
 features. The following types of completion are available:
 
@@ -26337,28 +26352,28 @@ and
 
 @end table
 
-@node Dgawk Limitations
+@node Limitations
 @section Limitations and Future Plans
 
-We hope you find @command{dgawk} useful and enjoyable to work with,
+We hope you find the @command{gawk} debugger useful and enjoyable to work with,
 but as with any program, especially in its early releases, it still has
 some limitations.  A few which are worth being aware of are:
 
 @itemize @bullet{}
 @item
-At this point, @command{dgawk} does not give a detailed explanation of
+At this point, the debugger does not give a detailed explanation of
 what you did wrong when you type in something it doesn't like. Rather, it just
 responds @samp{syntax error}.  When you do figure out what your mistake was,
 though, you'll feel like a real guru.
 
 @item
-If you perused the dump of opcodes in @ref{Miscellaneous Dgawk Commands},
+If you perused the dump of opcodes in @ref{Miscellaneous Debugger Commands},
 (or if you are already familiar with @command{gawk} internals),
 you will realize that much of the internal manipulation of data
 in @command{gawk}, as in many interpreters, is done on a stack.
 @code{Op_push}, @code{Op_pop}, etc., are the ``bread and butter'' of
-most @command{gawk} code.  Unfortunately, as of now, @command{dgawk}
-does not allow you to examine the stack's contents.
+most @command{gawk} code.  Unfortunately, as of now, the @command{gawk}
+debugger does not allow you to examine the stack's contents.
 
 That is, the intermediate results of expression evaluation are on the
 stack, but cannot be printed.  Rather, only variables which are defined
@@ -26373,14 +26388,14 @@ programmer, you are expected to know what @code{/[^[:alnum:][:blank:]]/}
 means.
 
 @item
-@command{dgawk} is designed to be used by running a program (with all its
-parameters) on the command line, as described in @ref{dgawk invocation}.
+The @command{gawk} debugger is designed to be used by running a program (with all its
+parameters) on the command line, as described in @ref{Debugger Invocation}.
 There is no way (as of now) to attach or ``break in'' to a running program.
 This seems reasonable for a language which is used mainly for quickly
 executing, short programs.
 
 @item
-@command{dgawk} only accepts source supplied with the @option{-f} option.
+The @command{gawk} debugger only accepts source supplied with the @option{-f} option.
 @end itemize
 
 Look forward to a future release when these and other missing features may
@@ -27289,7 +27304,7 @@ environments.
 @cindex Haque, John
 John Haque
 reworked the @command{gawk} internals to use a byte-code engine,
-providing the @command{dgawk} debugger for @command{awk} programs.
+providing the @command{gawk} debugger for @command{awk} programs.
 
 @item
 @cindex Yawitz, Efraim
@@ -28559,7 +28574,7 @@ since approximately 2003.
 @item @command{pawk}
 Nelson H.F.@: Beebe at the University of Utah has modified
 Brian Kernighan's @command{awk} to provide timing and profiling information.
-It is different from @command{pgawk}
+It is different from @command{gawk} with the @option{--profile} option.
 (@pxref{Profiling}),
 in that it uses CPU-based profiling, not line-count
 profiling.  You may find it at either
@@ -29064,6 +29079,7 @@ When @option{--sandbox} is specified, extensions are disabled
 @menu
 * Internals::                   A brief look at some @command{gawk} internals.
 * Plugin License::              A note about licensing.
+* Loading Extensions::          How to load dynamic extensions.	             
 * Sample Library::              A example of new functions.
 @end menu
 
@@ -29374,6 +29390,56 @@ the symbol exists in the global scope.  Something like this is enough:
 int plugin_is_GPL_compatible;
 @end example
 
+@node Loading Extensions
+@appendixsubsec Loading a Dynamic Extension	
+@cindex loading extension
+@cindex @command{gawk}, functions, loading
+There are two ways to load a dynamically linked library. The first is to use the
+builtin @code{extension()}:
+
+@example
+extension(libname, init_func)
+@end example
+
+where @file{libname} is the library to load, and @samp{init_func} is the
+name of the initialization or bootstrap routine to run once loaded.
+
+The second method for dynamic loading of a library is to use the
+command line option @option{-l}:
+
+@example
+$ @kbd{gawk -l libname -f myprog}
+@end example
+
+This will work only if the initialization routine is named @code{dlload()}.
+
+If you use @code{extension()}, the library will be loaded
+at run time. This means that the functions are available only to the rest of
+your script. If you use the command line option @option{-l} instead,
+the library will be loaded before @command{gawk} starts compiling the
+actual program. The net effect is that you can use those functions
+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}
+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
+present in the name of the library.
+If the name of your library is @file{mylib.so}, you can simply type
+
+@example
+$ @kbd{gawk -l mylib -f myprog}
+@end example
+
+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.
+
 @node Sample Library
 @appendixsubsec Example: Directory and File Operation Built-ins
 @c STARTOFRANGE chdirg