diff options
Diffstat (limited to 'doc/gawk.texi')
| -rw-r--r-- | doc/gawk.texi | 346 |
1 files changed, 319 insertions, 27 deletions
diff --git a/doc/gawk.texi b/doc/gawk.texi index 22230d10..b6af32e5 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -116,11 +116,19 @@ @end ifnottex @ifnottex +@ifnotdocbook @macro ii{text} @i{\text\} @end macro +@end ifnotdocbook @end ifnottex +@ifdocbook +@macro ii{text} +@inlineraw{docbook,<lineannotation>\text\</lineannotation>} +@end macro +@end ifdocbook + @c For HTML, spell out email addresses, to avoid problems with @c address harvesters for spammers. @ifhtml @@ -176,6 +184,10 @@ Some comments on the layout for TeX. @syncodeindex fn cp @syncodeindex vr cp @end ifxml +@ifdocbook +@synindex fn cp +@synindex vr cp +@end ifdocbook @c If "finalout" is commented out, the printed output will show @c black boxes that mark lines that are too long. Thus, it is @@ -187,10 +199,26 @@ Some comments on the layout for TeX. @end iftex @copying -Copyright @copyright{} 1989, 1991, 1992, 1993, 1996, 1997, 1998, 1999, -2000, 2001, 2002, 2003, 2004, 2005, 2007, 2009, 2010, 2011, 2012, 2013, -2014 +@docbook +<para>Published by:</para> + +<literallayout class="normal">Free Software Foundation +51 Franklin Street, Fifth Floor +Boston, MA 02110-1301 USA +Phone: +1-617-542-5942 +Fax: +1-617-542-2652 +Email: <email>gnu@@gnu.org</email> +URL: <ulink url="http://www.gnu.org">http://www.gnu.org/</ulink></literallayout> + +<literallayout class="normal">Copyright © 1989, 1991, 1992, 1993, 1996–2005, 2007, 2009–2014 +Free Software Foundation, Inc. +All Rights Reserved.</literallayout> +@end docbook + +@ifnotdocbook +Copyright @copyright{} 1989, 1991, 1992, 1993, 1996--2005, 2007, 2009--2014 @* Free Software Foundation, Inc. +@end ifnotdocbook @sp 2 This is Edition @value{EDITION} of @cite{@value{TITLE}: @value{SUBTITLE}}, @@ -238,6 +266,7 @@ supports it in developing GNU and promoting software freedom.'' @subtitle @value{UPDATE-MONTH} @author Arnold D. Robbins +@ifnotdocbook @c Include the Distribution inside the titlepage environment so @c that headings are turned off. Headings on and off do not work. @@ -262,6 +291,7 @@ URL: @uref{http://www.gnu.org/} @* ISBN 1-882114-28-0 @* @sp 2 @insertcopying +@end ifnotdocbook @end titlepage @c Thanks to Bob Chassell for directions on doing dedications. @@ -286,6 +316,18 @@ ISBN 1-882114-28-0 @* @headings on @end iftex +@docbook +<dedication> +<simplelist> +<member>To Miriam, for making me complete.</member> +<member>To Chana, for the joy you bring us.</member> +<member>To Rivka, for the exponential increase.</member> +<member>To Nachum, for the added dimension.</member> +<member>To Malka, for the new beginning.</member> +</simplelist> +</dedication> +@end docbook + @iftex @headings off @evenheading @thispage@ @ @ @strong{@value{TITLE}} @| @| @@ -294,6 +336,7 @@ ISBN 1-882114-28-0 @* @ifnottex @ifnotxml +@ifnotdocbook @node Top @top General Introduction @c Preface node should come right after the Top @@ -305,6 +348,7 @@ particular records in a file and perform operations upon them. @insertcopying +@end ifnotdocbook @end ifnotxml @end ifnottex @@ -1001,21 +1045,37 @@ and the AWK prototype becomes the product. The new @command{pgawk} (profiling @command{gawk}), produces program execution counts. I recently experimented with an algorithm that for -@math{n} lines of input, exhibited +@ifnotdocbook +@math{n} +@end ifnotdocbook +@ifdocbook +@i{n} +@end ifdocbook +lines of input, exhibited @tex $\sim\! Cn^2$ @end tex @ifnottex +@ifnotdocbook ~ C n^2 +@end ifnotdocbook @end ifnottex +@docbook +<emphasis>∼ Cn<superscript>2</superscript></emphasis>  +@end docbook performance, while theory predicted @tex $\sim\! Cn\log n$ @end tex @ifnottex +@ifnotdocbook ~ C n log n +@end ifnotdocbook @end ifnottex +@docbook +<emphasis>∼ Cn log n</emphasis>  +@end docbook behavior. A few minutes poring over the @file{awkprof.out} profile pinpointed the problem to a single line of code. @command{pgawk} is a welcome addition to @@ -3176,10 +3236,19 @@ There are two ways to run @command{awk}---with an explicit program or with one or more program files. Here are templates for both of them; items enclosed in [@dots{}] in these templates are optional: +@ifnotdocbook @example awk @r{[@var{options}]} -f progfile @r{[@code{--}]} @var{file} @dots{} awk @r{[@var{options}]} @r{[@code{--}]} '@var{program}' @var{file} @dots{} @end example +@end ifnotdocbook + +@c FIXME - find a better way to mark this up in docbook +@docbook +<screen>awk [<replaceable>options</replaceable>] -f progfile [<literal>--</literal>] <replaceable>file</replaceable> … +awk [<replaceable>options</replaceable>] [<literal>--</literal>] '<replaceable>program</replaceable>' <replaceable>file</replaceable> … +</screen> +@end docbook @cindex GNU long options @cindex long options @@ -17225,7 +17294,18 @@ it is the number of seconds since 1970-01-01 00:00:00 UTC, not counting leap seconds.@footnote{@xref{Glossary}, especially the entries ``Epoch'' and ``UTC.''} All known POSIX-compliant systems support timestamps from 0 through -@math{2^{31} - 1}, which is sufficient to represent times through +@iftex +@math{2^{31} - 1}, +@end iftex +@ifnottex +@ifnotdocbook +2^31 - 1, +@end ifnotdocbook +@end ifnottex +@docbook +2<superscript>31</superscript> − 1,  +@end docbook +which is sufficient to represent times through 2038-01-19 03:14:07 UTC. Many systems support a wider range of timestamps, including negative timestamps that represent times before the epoch. @@ -27574,15 +27654,16 @@ Without any argument, set a breakpoint at the next instruction to be executed in the selected stack frame. Arguments can be one of the following: +@c @asis for docbook @c nested table -@table @var -@item n +@table @asis +@item @var{n} Set a breakpoint at line number @var{n} in the current source file. -@item filename@code{:}n +@item @var{filename}@code{:}@var{n} Set a breakpoint at line number @var{n} in source file @var{filename}. -@item function +@item @var{function} Set a breakpoint at entry to (the first instruction of) function @var{function}. @end table @@ -27607,14 +27688,14 @@ a breakpoint, this deletes that breakpoint so that the program does not stop at that location again. Arguments can be one of the following: @c nested table -@table @var -@item n +@table @asis +@item @var{n} Delete breakpoint(s) set at line number @var{n} in the current source file. -@item filename@code{:}n +@item @var{filename}@code{:}@var{n} Delete breakpoint(s) set at line number @var{n} in source file @var{filename}. -@item function +@item @var{function} Delete breakpoint(s) set at entry to function @var{function}. @end table @@ -28216,8 +28297,8 @@ about the command @var{command}. @cindex debugger commands, @code{list} @cindex @code{list} debugger command @cindex @code{l} debugger command (alias for @code{list}) -@item @code{list} [@code{-} | @code{+} | @var{n} | @var{filename@code{:}n} | @var{n}--@var{m} | @var{function}] -@itemx @code{l} [@code{-} | @code{+} | @var{n} | @var{filename@code{:}n} | @var{n}--@var{m} | @var{function}] +@item @code{list} [@code{-} | @code{+} | @var{n} | @var{filename}@code{:}@var{n} | @var{n}--@var{m} | @var{function}] +@itemx @code{l} [@code{-} | @code{+} | @var{n} | @var{filename}@code{:}@var{n} | @var{n}--@var{m} | @var{function}] Print the specified lines (default 15) from the current source file or the file named @var{filename}. The possible arguments to @code{list} are as follows: @@ -28237,7 +28318,7 @@ Print lines centered around line number @var{n}. @item @var{n}--@var{m} Print lines from @var{n} to @var{m}. -@item @var{filename@code{:}n} +@item @var{filename}@code{:}@var{n} Print lines centered around line number @var{n} in source file @var{filename}. This command may change the current source file. @@ -28707,23 +28788,38 @@ then the answer is @math{2^{53}}. @end iftex @ifnottex +@ifnotdocbook 2^53. +@end ifnotdocbook @end ifnottex +@docbook +2<superscript>53</superscript>.  +@end docbook The next representable number is the even number @iftex @math{2^{53} + 2}, @end iftex @ifnottex +@ifnotdocbook 2^53 + 2, +@end ifnotdocbook @end ifnottex +@docbook +2<superscript>53</superscript> + 2, +@end docbook meaning it is unlikely that you will be able to make @command{gawk} print @iftex @math{2^{53} + 1} @end iftex @ifnottex +@ifnotdocbook 2^53 + 1 +@end ifnotdocbook @end ifnottex +@docbook +2<superscript>53</superscript> + 1  +@end docbook in integer format. The range of integers exactly representable by a 64-bit double is @@ -28731,8 +28827,13 @@ is @math{[-2^{53}, 2^{53}]}. @end iftex @ifnottex +@ifnotdocbook [@minus{}2^53, 2^53]. +@end ifnotdocbook @end ifnottex +@docbook +[−2<superscript>53</superscript>, 2<superscript>53</superscript>].  +@end docbook If you ever see an integer outside this range in @command{awk} using 64-bit doubles, you have reason to be very suspicious about the accuracy of the output. Here is a simple program with erroneous output: @@ -28956,8 +29057,13 @@ number is then @math{s @cdot 2^e}. @end iftex @ifnottex +@ifnotdocbook @var{s * 2^e}. +@end ifnotdocbook @end ifnottex +@docbook +<emphasis>s ċ 2<superscript>e</superscript></emphasis>.  +@end docbook The first bit of a non-zero binary significand is always one, so the significand in an IEEE-754 format only includes the fractional part, leaving the leading one implicit. @@ -29200,8 +29306,13 @@ numbers are not implemented.} (@math{emax = 2^{30} - 1, emin = -emax}) @end iftex @ifnottex +@ifnotdocbook (@var{emax} = 2^30 @minus{} 1, @var{emin} = @minus{}@var{emax}) +@end ifnotdocbook @end ifnottex +@docbook +(<emphasis>emax</emphasis> = 2<superscript>30</superscript> − 1, <emphasis>emin</emphasis> = −<emphasis>emax</emphasis>)  +@end docbook for all floating-point contexts. There is no explicit mechanism to adjust the exponent range. MPFR does not implement subnormal numbers by default, @@ -29273,8 +29384,15 @@ formula: @math{prec = 3.322 @cdot dps} @end iftex @ifnottex +@ifnotdocbook @var{prec} = 3.322 * @var{dps} +@end ifnotdocbook @end ifnottex +@docbook +<para> +<emphasis>prec</emphasis> = 3.322 ċ <emphasis>dps</emphasis> +</para> +@end docbook @noindent Here, @var{prec} denotes the binary precision @@ -29674,8 +29792,14 @@ Communication between @command{gawk} and an extension is two-way. First, when an extension is loaded, it is passed a pointer to a @code{struct} whose fields are function pointers. +@ifnotdocbook This is shown in @ref{load-extension}. +@end ifnotdocbook +@ifdocbook +This is shown in @inlineraw{docbook, <xref linkend="load-extension"/>}. +@end ifdocbook +@ifnotdocbook @float Figure,load-extension @caption{Loading The Extension} @c FIXME: One day, it should not be necessary to have two cases, @@ -29688,13 +29812,27 @@ This is shown in @ref{load-extension}. @center @image{api-figure1, , , Loading the extension} @end ifnotinfo @end float +@end ifnotdocbook + +@docbook +<figure id="load-extension"> +<title>Loading the extension</title> +<graphic fileref="api-figure1.eps"/> +</figure> +@end docbook The extension can call functions inside @command{gawk} through these function pointers, at runtime, without needing (link-time) access to @command{gawk}'s symbols. One of these function pointers is to a function for ``registering'' new built-in functions. +@ifnotdocbook This is shown in @ref{load-new-function}. +@end ifnotdocbook +@ifdocbook +This is shown in @inlineraw{docboook, <xref linkend="load-new-function"/>}. +@end ifdocbook +@ifnotdocbook @float Figure,load-new-function @caption{Loading The New Function} @ifinfo @@ -29704,14 +29842,28 @@ This is shown in @ref{load-new-function}. @center @image{api-figure2, , , Loading the new function} @end ifnotinfo @end float +@end ifnotdocbook + +@docbook +<figure id="load-new-function"> +<title>Loading the new function</title> +<graphic fileref="api-figure2.eps"/> +</figure> +@end docbook In the other direction, the extension registers its new functions with @command{gawk} by passing function pointers to the functions that provide the new feature (@code{do_chdir()}, for example). @command{gawk} associates the function pointer with a name and can then call it, using a defined calling convention. +@ifnotdocbook This is shown in @ref{call-new-function}. +@end ifnotdocbook +@ifdocbook +This is shown in @inlineraw{docbook, <xref linkend="call-new-function"/>}. +@end ifdocbook +@ifnotdocbook @float Figure,call-new-function @caption{Calling The New Function} @ifinfo @@ -29721,6 +29873,14 @@ This is shown in @ref{call-new-function}. @center @image{api-figure3, , , Calling the new function} @end ifnotinfo @end float +@end ifnotdocbook + +@docbook +<figure id="call-new-function"> +<title>Calling The New Function</title> +<graphic fileref="api-figure3.eps"/> +</figure> +@end docbook The @code{do_@var{xxx}()} function, in turn, then uses the function pointers in the API @code{struct} to do its work, such as updating @@ -30094,7 +30254,94 @@ print an error message, or reissue the request for the actual value type, as appropriate. This behavior is summarized in @ref{table-value-types-returned}. +@c FIXME: Try to do this with spans... +@ifdocbook +@anchor{table-value-types-returned} +@end ifdocbook +@docbook +<informaltable> +<tgroup cols="2"> + <colspec colwidth="50*"/><colspec colwidth="50*"/> + <thead> + <row><entry></entry><entry><para>Type of Actual Value:</para></entry></row> + </thead> + <tbody> + <row><entry></entry><entry></entry></row> + </tbody> +</tgroup> +<tgroup cols="6"> + <colspec colwidth="16.6*"/> + <colspec colwidth="16.6*"/> + <colspec colwidth="19.8*"/> + <colspec colwidth="15*"/> + <colspec colwidth="15*"/> + <colspec colwidth="16.6*"/> + <thead> + <row> + <entry></entry> + <entry></entry> + <entry><para>String</para></entry> + <entry><para>Number</para></entry> + <entry><para>Array</para></entry> + <entry><para>Undefined</para></entry> + </row> + </thead> + <tbody> + <row> + <entry></entry> + <entry><para><emphasis role="bold">String</emphasis></para></entry> + <entry><para>String</para></entry> + <entry><para>String</para></entry> + <entry><para>false</para></entry> + <entry><para>false</para></entry> + </row> + <row> + <entry></entry> + <entry><para><emphasis role="bold">Number</emphasis></para></entry> + <entry><para>Number if can be converted, else false</para></entry> + <entry><para>Number</para></entry> + <entry><para>false</para></entry> + <entry><para>false</para></entry> + </row> + <row> + <entry><para><emphasis role="bold">Type</emphasis></para></entry> + <entry><para><emphasis role="bold">Array</emphasis></para></entry> + <entry><para>false</para></entry> + <entry><para>false</para></entry> + <entry><para>Array</para></entry> + <entry><para>false</para></entry> + </row> + <row> + <entry><para><emphasis role="bold">Requested:</emphasis></para></entry> + <entry><para><emphasis role="bold">Scalar</emphasis></para></entry> + <entry><para>Scalar</para></entry> + <entry><para>Scalar</para></entry> + <entry><para>false</para></entry> + <entry><para>false</para></entry> + </row> + <row> + <entry></entry> + <entry><para><emphasis role="bold">Undefined</emphasis></para></entry> + <entry><para>String</para></entry> + <entry><para>Number</para></entry> + <entry><para>Array</para></entry> + <entry><para>Undefined</para></entry> + </row> + <row> + <entry></entry> + <entry><para><emphasis role="bold">Value Cookie</emphasis></para></entry> + <entry><para>false</para></entry> + <entry><para>false</para></entry> + <entry><para>false</para> + </entry><entry><para>false</para></entry> + </row> + </tbody> +</tgroup> +</informaltable> +@end docbook + @ifnotplaintext +@ifnotdocbook @float Table,table-value-types-returned @caption{Value Types Returned} @multitable @columnfractions .50 .50 @@ -30110,6 +30357,7 @@ value type, as appropriate. This behavior is summarized in @item @tab @b{Value Cookie} @tab false @tab false @tab false @tab false @end multitable @end float +@end ifnotdocbook @end ifnotplaintext @ifplaintext @float Table,table-value-types-returned @@ -36266,22 +36514,23 @@ authoritative if it conflicts with this @value{DOCUMENT}. The people maintaining the non-Unix ports of @command{gawk} are as follows: -@multitable {MS-Windows with MINGW} {123456789012345678901234567890123456789001234567890} +@c put the index entries outside the table, for docbook @cindex Deifik, Scott +@cindex Zaretskii, Eli +@cindex Buening, Andreas +@cindex Rankin, Pat +@cindex Malmberg, John +@cindex Pitts, Dave +@multitable {MS-Windows with MINGW} {123456789012345678901234567890123456789001234567890} @item MS-DOS with DJGPP @tab Scott Deifik, @EMAIL{scottd.mail@@sbcglobal.net,scottd dot mail at sbcglobal dot net}. -@cindex Zaretskii, Eli @item MS-Windows with MINGW @tab Eli Zaretskii, @EMAIL{eliz@@gnu.org,eliz at gnu dot org}. -@cindex Buening, Andreas @item OS/2 @tab Andreas Buening, @EMAIL{andreas.buening@@nexgo.de,andreas dot buening at nexgo dot de}. -@cindex Rankin, Pat -@cindex Malmberg, John @item VMS @tab Pat Rankin, @EMAIL{r.pat.rankin@@gmail.com,r.pat.rankin at gmail.com}, and John Malmberg, @EMAIL{wb8tyw@@qsl.net,wb8tyw at qsl.net}. -@cindex Pitts, Dave @item z/OS (OS/390) @tab Dave Pitts, @EMAIL{dpitts@@cozx.com,dpitts at cozx dot com}. @end multitable @@ -37432,8 +37681,15 @@ other introductory texts that you should refer to instead.) @cindex processing data At the most basic level, the job of a program is to process -some input data and produce results. See @ref{figure-general-flow}. +some input data and produce results. +@ifnotdocbook +See @ref{figure-general-flow}. +@end ifnotdocbook +@ifdocbook +See @inlineraw{docbook, <xref linkend="figure-general-flow"/>}. +@end ifdocbook +@ifnotdocbook @float Figure,figure-general-flow @caption{General Program Flow} @ifinfo @@ -37443,6 +37699,14 @@ some input data and produce results. See @ref{figure-general-flow}. @center @image{general-program, , , General program flow} @end ifnotinfo @end float +@end ifnotdocbook + +@docbook +<figure id="figure-general-flow"> +<title>General Program Flow</title> +<graphic fileref="general-program.eps"/> +</figure> +@end docbook @cindex compiled programs @cindex interpreted programs @@ -37458,9 +37722,15 @@ instructions in your program to process the data. @cindex programming, basic steps When you write a program, it usually consists -of the following, very basic set of steps, as shown -in @ref{figure-process-flow}: +of the following, very basic set of steps, +@ifnotdocbook +as shown in @ref{figure-process-flow}: +@end ifnotdocbook +@ifdocbook +as shown in @inlineraw{docbook <xref linkend="figure-process-flow"/>}: +@end ifdocbook +@ifnotdocbook @float Figure,figure-process-flow @caption{Basic Program Steps} @ifinfo @@ -37470,6 +37740,14 @@ in @ref{figure-process-flow}: @center @image{process-flow, , , Basic Program Stages} @end ifnotinfo @end float +@end ifnotdocbook + +@docbook +<figure id="figure-process-flow"> +<title>Basic Program Stages</title> +<graphic fileref="process-flow.eps"/> +</figure> +@end docbook @table @asis @item Initialization @@ -37946,7 +38224,7 @@ ordinary expression. It could be a string constant, such as (@xref{Computed Regexps}.) @item Environment -A collection of strings, of the form @var{name@code{=}val}, that each +A collection of strings, of the form @var{name}@code{=}@code{val}, that each program has available to it. Users generally place values into the environment in order to provide information to various programs. Typical examples are the environment variables @env{HOME} and @env{PATH}. @@ -38402,7 +38680,12 @@ record or a string. @c The GNU General Public License. @node Copying @unnumbered GNU General Public License +@ifnotdocbook @center Version 3, 29 June 2007 +@end ifnotdocbook +@docbook +<subtitle>Version 3, 29 June 2007</subtitle> +@end docbook @c This file is intended to be included within another document, @c hence no sectioning command or @node. @@ -39127,10 +39410,17 @@ first, please read @url{http://www.gnu.org/philosophy/why-not-lgpl.html}. @c The GNU Free Documentation License. @node GNU Free Documentation License @unnumbered GNU Free Documentation License +@ifnotdocbook +@center Version 1.3, 3 November 2008 +@end ifnotdocbook + +@docbook +<subtitle>Version 1.3, 3 November 2008</subtitle> +@end docbook + @cindex FDL (Free Documentation License) @cindex Free Documentation License (FDL) @cindex GNU Free Documentation License -@center Version 1.3, 3 November 2008 @c This file is intended to be included within another document, @c hence no sectioning command or @node. @@ -39635,8 +39925,10 @@ to permit their use in free software. @c ispell-local-pdict: "ispell-dict" @c End: +@ifnotdocbook @node Index @unnumbered Index +@end ifnotdocbook @printindex cp @bye |