diff options
Diffstat (limited to 'doc/gawk.texi')
| -rw-r--r-- | doc/gawk.texi | 1087 |
1 files changed, 771 insertions, 316 deletions
diff --git a/doc/gawk.texi b/doc/gawk.texi index e5f50413..108b3320 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -4,13 +4,13 @@ @settitle The GNU Awk User's Guide @c %**end of header (This is for running Texinfo on a region.) -@dircategory GNU Packages +@dircategory Text creation and manipulation @direntry -* Gawk: (gawk). A text scanning and processing language. +* Gawk: (gawk). A text scanning and processing language. @end direntry @dircategory Individual utilities @direntry -* awk: (gawk)Invoking gawk. Text scanning and processing. +* awk: (gawk)Invoking gawk. Text scanning and processing. @end direntry @c @set xref-automatic-section-title @@ -20,9 +20,9 @@ @c applies to and all the info about who's publishing this edition @c These apply across the board. -@set UPDATE-MONTH April, 2002 +@set UPDATE-MONTH February, 2003 @set VERSION 3.1 -@set PATCHLEVEL 1 +@set PATCHLEVEL 2 @set FSF @@ -54,6 +54,14 @@ @set SUBSECTION subsection @set DARKCORNER (d.c.) @end ifhtml +@ifxml +@set DOCUMENT book +@set CHAPTER chapter +@set APPENDIX appendix +@set SECTION section +@set SUBSECTION subsection +@set DARKCORNER (d.c.) +@end ifxml @c some special symbols @iftex @@ -87,6 +95,10 @@ Some comments on the layout for TeX. @syncodeindex fn cp @syncodeindex vr cp @end iftex +@ifxml +@syncodeindex fn cp +@syncodeindex vr cp +@end ifxml @c If "finalout" is commented out, the printed output will show @c black boxes that mark lines that are too long. Thus, it is @@ -98,7 +110,7 @@ Some comments on the layout for TeX. @end iftex @copying -Copyright @copyright{} 1989, 1991, 1992, 1993, 1996, 1997, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc. +Copyright @copyright{} 1989, 1991, 1992, 1993, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc. @sp 2 This is Edition @value{EDITION} of @cite{@value{TITLE}: @value{SUBTITLE}}, @@ -106,7 +118,7 @@ for the @value{VERSION}.@value{PATCHLEVEL} (or later) version of the GNU implementation of AWK. Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or +under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with the Invariant Sections being ``GNU General Public License'', the Front-Cover texts being (a) (see below), and with the Back-Cover Texts being (b) @@ -219,6 +231,7 @@ Cover art by Etienne Suvasa. @end iftex @ifnottex +@ifnotxml @node Top, Foreword, (dir), (dir) @top General Introduction @c Preface node should come right after the Top @@ -230,6 +243,7 @@ particular records in a file and perform operations upon them. @insertcopying +@end ifnotxml @end ifnottex @menu @@ -319,6 +333,7 @@ particular records in a file and perform operations upon them. * Case-sensitivity:: How to do case-insensitive matching. * Leftmost Longest:: How much text matches. * Computed Regexps:: Using Dynamic Regexps. +* Locales:: How the locale affects things. * Records:: Controlling how data is split into records. * Fields:: An introduction to fields. * Nonconstant Fields:: Nonconstant Field Numbers. @@ -1099,13 +1114,13 @@ This @value{DOCUMENT} is written using Texinfo, the GNU documentation formatting language. A single Texinfo source file is used to produce both the printed and online versions of the documentation. -@iftex +@ifnotinfo Because of this, the typographical conventions are slightly different than in other books you may have read. -@end iftex -@ifnottex +@end ifnotinfo +@ifinfo This @value{SECTION} briefly documents the typographical conventions used in Texinfo. -@end ifnottex +@end ifinfo Examples you would type at the command-line are preceded by the common shell primary and secondary prompts, @samp{$} and @samp{>}. @@ -1121,7 +1136,7 @@ $ echo hello on stderr 1>&2 @error{} hello on stderr @end example -@iftex +@ifnotinfo In the text, command names appear in @code{this font}, while code segments appear in the same font and quoted, @samp{like this}. Some things are emphasized @emph{like this}, and if a point needs to be made @@ -1129,7 +1144,7 @@ strongly, it is done @strong{like this}. The first occurrence of a new term is usually its @dfn{definition} and appears in the same font as the previous occurrence of ``definition'' in this sentence. @value{FN}s are indicated like this: @file{/path/to/ourfile}. -@end iftex +@end ifnotinfo Characters that you type at the keyboard look @kbd{like this}. In particular, there are special characters called ``control characters.'' These are @@ -1844,6 +1859,10 @@ $ advice @end example @noindent +(We assume you have the current directory in your shell's search +path variable (typically @code{$PATH}). If not, you may need +to type @samp{./advice} at the shell.) + Self-contained @command{awk} scripts are useful when you want to write a program that users can invoke without their having to know that the program is written in @command{awk}. @@ -2453,7 +2472,7 @@ are automatically initialized to zero.) After the last line of output from @command{ls} has been processed, the @code{END} rule executes and prints the value of @code{sum}. -In this example, the value of @code{sum} is 140963. +In this example, the value of @code{sum} is 80600. These more advanced @command{awk} techniques are covered in later sections (@pxref{Action Overview, ,Actions}). Before you can move on to more @@ -2699,6 +2718,7 @@ regular expressions work, we will present more complicated instances. * Case-sensitivity:: How to do case-insensitive matching. * Leftmost Longest:: How much text matches. * Computed Regexps:: Using Dynamic Regexps. +* Locales:: How the locale affects things. @end menu @node Regexp Usage, Escape Sequences, Regexp, Regexp @@ -3124,7 +3144,8 @@ arithmetic. They can be used to concatenate regular expressions containing the alternation operator, @samp{|}. For example, @samp{@@(samp|code)\@{[^@}]+\@}} matches both @samp{@@code@{foo@}} and @samp{@@samp@{bar@}}. -(These are Texinfo formatting control sequences.) +(These are Texinfo formatting control sequences. The @samp{+} is +explained further on in this list.) @cindex @code{*} (asterisk), @code{*} operator, as regexp operator @cindex asterisk (@code{*}), @code{*} operator, as regexp operator @@ -3556,7 +3577,9 @@ treated literally, even if they represent regexp metacharacters. @item @code{--re-interval} Allow interval expressions in regexps, even if @option{--traditional} -has been provided. +has been provided. (@option{--posix} automatically enables +interval expressions, so @option{--re-interval} is redundant +when @option{--posix} is is used.) @end table @c ENDOFRANGE gregexp @c ENDOFRANGE regexpg @@ -3698,7 +3721,7 @@ Understanding this principle is also important for regexp-based record and field splitting (@pxref{Records, ,How Input Is Split into Records}, and also @pxref{Field Separators, ,Specifying How Fields Are Separated}). -@node Computed Regexps, , Leftmost Longest, Regexp +@node Computed Regexps, Locales, Leftmost Longest, Regexp @section Using Dynamic Regexps @c STARTOFRANGE dregexp @@ -3814,6 +3837,46 @@ occur often in practice, but it's worth noting for future reference. @c ENDOFRANGE regexpd @c ENDOFRANGE regexp +@node Locales, , Computed Regexps, Regexp +@section Where You Are Makes A Difference + +Modern systems support the notion of @dfn{locales}: a way to tell +the system about the local character set and language. The current +locale setting can affect the way regexp matching works, often +in surprising ways. In particular, many locales do case-insensitive +matching, even when you may have specified characters of only +one particular case. + +The following example uses the @code{sub} function, which +does text replacement +(@pxref{String Functions, , String-Manipulation Functions}). +Here, the intent is to remove trailing uppercase characters: + +@example +$ echo something1234abc | gawk '@{ sub("[A-Z]*$", ""); print @}' +@print{} something1234 +@end example + +@noindent +This output is unexpected, since the @samp{abc} at the end of @samp{something1234abc} +should not normally match @samp{[A-Z]*}. This result is due to the +locale setting (and thus you may not see it on your system). +There are two fixes. The first is to use the POSIX character +class @samp{[[:upper:]]}, instead of @samp{[A-Z]}. +The second is to change the locale setting in the environment, +before running @command{gawk}, +by using the shell statements: + +@example +LANG=C LC_ALL=C +export LANG LC_ALL +@end example + +The setting @samp{C} forces @command{gawk} to behave in the traditional +Unix manner, where case distinctions do matter. +You may wish to put these statements into your shell startup file, +e.g., @file{$HOME/.profile}. + @node Reading Files, Printing, Regexp, Top @chapter Reading Input Files @@ -4057,6 +4120,14 @@ supplies its own terminating newline. @xref{Simple Sed, ,A Simple Stream Editor}, for a more useful example of @code{RS} as a regexp and @code{RT}. +If you set @code{RS} to a regular expression that allows optional +trailing text, such as @samp{RS = "abc(XYZ)?"} it is possible, due +to implementation constraints, that @command{gawk} may match the leading +part of the regular expression, but not the trailing part, particularly +if the input text that could match the trailing part is fairly long. +@command{gawk} attempts to avoid this problem, but currently, there's +no guarantee that this will never happen. + @cindex differences in @command{awk} and @command{gawk}, @code{RS}/@code{RT} variables The use of @code{RS} as a regular expression and the @code{RT} variable are @command{gawk} extensions; they are not available in @@ -4258,6 +4329,7 @@ evaluating @code{NF} and using its value as a field number. @node Changing Fields, Field Separators, Nonconstant Fields, Reading Files @section Changing the Contents of a Field +@c STARTOFRANGE ficon @cindex fields, changing contents of The contents of a field, as seen by @command{awk}, can be changed within an @command{awk} program; this changes what @command{awk} perceives as the @@ -4268,9 +4340,9 @@ Consider the following example and its output: @example $ awk '@{ nboxes = $3 ; $3 = $3 - 10 > print nboxes, $3 @}' inventory-shipped -@print{} 13 3 -@print{} 15 5 -@print{} 15 5 +@print{} 25 15 +@print{} 32 22 +@print{} 24 14 @dots{} @end example @@ -4284,7 +4356,7 @@ Then it prints the original and new values for field three. (Someone in the warehouse made a consistent mistake while inventorying the red boxes.) -For this to work, the text in field @code{$2} must make sense +For this to work, the text in field @code{$3} must make sense as a number; the string of characters must be converted to a number for the computer to do arithmetic on it. The number resulting from the subtraction is converted back to a string of characters that @@ -4337,11 +4409,11 @@ existing fields. @cindex field separators, See Also @code{OFS} This recomputation affects and is affected by @code{NF} (the number of fields; @pxref{Fields, ,Examining Fields}). -It is also affected by a feature that has not been discussed yet: -the @dfn{output field separator}, @code{OFS}, -used to separate the fields (@pxref{Output Separators}). For example, the value of @code{NF} is set to the number of the highest field you create. +The exact format of @code{$0} is also affected by a feature that has not been discussed yet: +the @dfn{output field separator}, @code{OFS}, +used to separate the fields (@pxref{Output Separators}). Note, however, that merely @emph{referencing} an out-of-range field does @emph{not} change the value of either @code{$0} or @code{NF}. @@ -4410,6 +4482,27 @@ $ echo a b c d e f | awk '@{ print "NF =", NF; @cindex portability, @code{NF} variable, decrementing @strong{Caution:} Some versions of @command{awk} don't rebuild @code{$0} when @code{NF} is decremented. Caveat emptor. + +Finally, there are times when it is convenient to force +@command{awk} to rebuild the entire record, using the current +value of the fields and @code{OFS}. To do this, use the +seemingly innocuous assignment: + +@example +$1 = $1 # force record to be reconstituted +print $0 # or whatever else with $0 +@end example + +@noindent +This forces @command{awk} rebuild the record. It does help +to add a comment, as we've shown here. + +There is a flip side to the relationship between @code{$0} and +the fields. Any assignment to @code{$0} causes the record to be +reparsed into fields using the @emph{current} value of @code{FS}. +This also applies to any built-in function that updates @code{$0}, +such as @code{sub} and @code{gsub} +(@pxref{String Functions, ,String-Manipulation Functions}). @c ENDOFRANGE ficon @node Field Separators, Constant Size, Changing Fields, Reading Files @@ -4759,10 +4852,17 @@ awk -F: '$2 == ""' /etc/passwd @node Field Splitting Summary, , Command Line Field Separator, Field Separators @subsection Field-Splitting Summary -The following -table -summarizes how fields are split, based on the -value of @code{FS} (@samp{==} means ``is equal to''): +It is important to remember that when you assign a string constant +as the value of @code{FS}, it undergoes normal @command{awk} string +processing. For example, with Unix @command{awk} and @command{gawk}, +the assignment @samp{FS = "\.."} assigns the character string @code{".."} +to @code{FS} (the backslash is stripped). This creates a regexp meaning +``fields are separated by occurrences of any two characters.'' +If instead you want fields to be separated by a literal period followed +by any single character, use @samp{FS = "\\.."}. + +The following table summarizes how fields are split, based on the value +of @code{FS} (@samp{==} means ``is equal to''): @table @code @item FS == " " @@ -4830,6 +4930,29 @@ prints something like: @example root:nSijPlPhZZwgE:0:0:Root:/: @end example + +@c fakenode --- for prepinfo +@subheading Advanced Notes: @code{FS} and @code{IGNORECASE} + +The @code{IGNORECASE} variable +(@pxref{User-modified, ,Built-in Variables That Control @command{awk}}) +affects field splitting @emph{only} when the value of @code{FS} is a regexp. +It has no effect when @code{FS} is a single character, even if +that character is a letter. Thus, in the following code: + +@example +FS = "c" +IGNORECASE = 1 +$0 = "aCa" +print $1 +@end example + +@noindent +The output is @samp{aCa}. If you really want to split fields on an +alphabetic character while ignoring case, use a regexp that will +do it for you. E.g., @samp{FS = "[c]"}. In this case, @code{IGNORECASE} +will take effect. + @c ENDOFRANGE fisepr @c ENDOFRANGE fisepg @@ -5029,8 +5152,13 @@ Now that the input is separated into records, the second step is to separate the fields in the record. One way to do this is to divide each of the lines into fields in the normal manner. This happens by default as the result of a special feature. When @code{RS} is set to the empty -string, the newline character @emph{always} acts as a field separator. -This is in addition to whatever field separations result from @code{FS}. +string, @emph{and} @code{FS} is a set to a single character, +the newline character @emph{always} acts as a field separator. +This is in addition to whatever field separations result from +@code{FS}.@footnote{When @code{FS} is the null string (@code{""}) +or a regexp, this special feature of @code{RS} does not apply. +It does apply to the default field separator of a single space: +@samp{FS = " "}.} The original motivation for this special exception was probably to provide useful behavior in the default case (i.e., @code{FS} is equal @@ -5039,11 +5167,16 @@ want the newline character to separate fields, because there is no way to prevent it. However, you can work around this by using the @code{split} function to break up the record manually (@pxref{String Functions, ,String Manipulation Functions}). +If you have a single character field separator, you can work around +the special feature in a different way, by making @code{FS} into a +regexp for that single character. For example, if the field +separator is a percent character, instead of +@samp{FS = "%"}, use @samp{FS = "[%]"}. Another way to separate fields is to put each field on a separate line: to do this, just set the -variable @code{FS} to the string @code{"\n"}. (This simple regular -expression matches a single newline.) +variable @code{FS} to the string @code{"\n"}. (This single +character seperator matches a single newline.) A practical example of a @value{DF} organized this way might be a mailing list, where each entry is separated by blank lines. Consider a mailing list in a file named @file{addresses}, which looks like this: @@ -5600,6 +5733,16 @@ have not yet started to process the command-line @value{DF}s. @value{DARKCORNER} (@xref{BEGIN/END, , The @code{BEGIN} and @code{END} Special Patterns}, also @pxref{Auto-set, ,Built-in Variables That Convey Information}.) + +@item +Using @code{FILENAME} with @code{getline} +(@samp{getline < FILENAME}) +is likely to be a source for +confusion. @command{awk} opens a separate input stream from the +current input file. However, by not using a variable, @code{$0} +and @code{NR} are still updated. If you're doing this, it's +probably by accident, and you should reconsider what it is you're +trying to accomplish. @end itemize @node Getline Summary, , Getline Notes, Getline @@ -6978,6 +7121,12 @@ is not closed and released until @code{close} is called or does not represent a file, pipe or coprocess that was opened with a redirection. +Note also that @samp{close(FILENAME)} has no +``magic'' effects on the implicit loop that reads through the +files named on the command line. It is, more likely, a close +of a file that was never opened, so @command{awk} silently +does nothing. + @c comma is part of tertiary @cindex @code{|} (vertical bar), @code{|&} operator (I/O), pipes, closing When using the @samp{|&} operator to communicate with a coprocess, @@ -7024,7 +7173,10 @@ In these cases, @command{gawk} sets the built-in variable In @command{gawk}, when closing a pipe or coprocess, -the return value is the exit status of the command. +the return value is the exit status of the command.@footnote{ +This is a full 16-bit value as returned by the @code{wait} +system call. See the system manual pages for information on +how to decode this value.} Otherwise, it is the return value from the system's @code{close} or @code{fclose} C functions when closing input or output files, respectively. @@ -7034,6 +7186,8 @@ it fails. The return value for closing a pipeline is particularly useful. It allows you to get the output from a command as well as its exit status. +@c 8/21/2002, FIXME: Maybe the code and this doc should be adjusted to +@c create values indicating death-by-signal? Sigh. @cindex pipes, closing @c comma does NOT start tertiary @@ -8916,8 +9070,6 @@ whereas @samp{$} has higher precedence. This table presents @command{awk}'s operators, in order of highest to lowest precedence: -@page - @c use @code in the items, looks better in TeX w/o all the quotes @table @code @item (@dots{}) @@ -9340,7 +9492,7 @@ This cannot be changed or worked around; range patterns do not combine with other patterns: @example -$ echo yes | gawk '(/1/,/2/) || /Yes/' +$ echo Yes | gawk '(/1/,/2/) || /Yes/' @error{} gawk: cmd. line:1: (/1/,/2/) || /Yes/ @error{} gawk: cmd. line:1: ^ parse error @error{} gawk: cmd. line:2: (/1/,/2/) || /Yes/ @@ -10325,7 +10477,7 @@ describing their areas of activity. The following is an alphabetical list of variables that you can change to control how @command{awk} does certain things. The variables that are -specific to @command{gawk} are marked with a pound sign (@samp{#}). +specific to @command{gawk} are marked with a pound sign@w{ (@samp{#}).} @table @code @cindex @code{BINMODE} variable @@ -10430,7 +10582,9 @@ matching with @samp{~} and @samp{!~}, as well as the @code{gensub}, @code{gsub}, @code{index}, @code{match}, @code{split}, and @code{sub} functions, record termination with @code{RS}, and field splitting with @code{FS}, all ignore case when doing their particular regexp operations. -However, the value of @code{IGNORECASE} does @emph{not} affect array subscripting. +However, the value of @code{IGNORECASE} does @emph{not} affect array subscripting +and it does not affect field splitting when using a single-character +field separator. @xref{Case-sensitivity, ,Case Sensitivity in Matching}. @cindex @command{gawk}, @code{IGNORECASE} variable in @@ -10447,6 +10601,8 @@ When this variable is true (nonzero or non-null), @command{gawk} behaves as if the @option{--lint} command-line option is in effect. (@pxref{Options, ,Command-Line Options}). With a value of @code{"fatal"}, lint warnings become fatal errors. +With a value of @code{"invalid"}, only warnings about things that are +actually invalid are issued. (This is not fully implemented yet.) Any other true value prints nonfatal warnings. Assigning a false value to @code{LINT} turns off the lint warnings. @@ -10551,7 +10707,7 @@ it is not special. The following is an alphabetical list of variables that @command{awk} sets automatically on certain occasions in order to provide information to your program. The variables that are specific to -@command{gawk} are marked with an asterisk (@samp{*}). +@command{gawk} are marked with a pound sign@w{ (@samp{#}).} @table @code @cindex @code{ARGC}/@code{ARGV} variables @@ -10682,6 +10838,18 @@ The number of fields in the current input record. @code{NF} is set each time a new record is read, when a new field is created or when @code{$0} changes (@pxref{Fields, ,Examining Fields}). +Unlike most of the variables described in this +@ifnotinfo +section, +@end ifnotinfo +@ifinfo +node, +@end ifinfo +assigning a value to @code{NF} has the potential to affect +@command{awk}'s internal workings. In particular, assignments +to @code{NF} can be used to create or remove fields from the +current record: @xref{Changing Fields, ,Changing the Contents of a Field}. + @cindex @code{NR} variable @item NR The number of input records @command{awk} has processed since @@ -11031,6 +11199,14 @@ conceptually, if the element values are 8, @code{"foo"}, 0 1 2 3 @r{Index} @end example @end ifinfo +@ifxml +@example ++---------+---------+--------+---------+ +| 8 | "foo" | "" | 30 | @r{Value} ++---------+---------+--------+---------+ + 0 1 2 3 @r{Index} +@end example +@end ifxml @noindent Only the values are stored; the indices are implicit from the order of @@ -11712,9 +11888,10 @@ In most @command{awk} implementations, sorting an array requires writing a @code{sort} function. While this can be educational for exploring different sorting algorithms, usually that's not the point of the program. -@command{gawk} provides the built-in @code{asort} function +@command{gawk} provides the built-in @code{asort} +and @code{asorti} functions (@pxref{String Functions, ,String Manipulation Functions}) -that sorts an array. For example: +for sorting arrays. For example: @example @var{populate the array} data @@ -11749,7 +11926,24 @@ In this case, @command{gawk} copies the @code{source} array into the However, the @code{source} array is not affected. Often, what's needed is to sort on the values of the @emph{indices} -instead of the values of the elements. To do this, use a helper array +instead of the values of the elements. +To do that, starting with @command{gawk} 3.1.2, use the +@code{asorti} function. The interface is identical to that of +@code{asort}, except that the index values are used for sorting, and +become the values of the result array: + +@example +@{ source[$0] = some_func($0) @} + +END @{ + n = asorti(source, dest) + for (i = 1; i <= n; i++) + @var{do something with} dest[i] +@} +@end example + +If your version of @command{gawk} is 3.1.0 or 3.1.1, you don't +have @code{asorti}. Instead, use a helper array to hold the sorted index values, and then access the original array's elements. It works in the following way: @@ -11779,10 +11973,14 @@ both arrays use the values. Similarly, when copying the indices from @code{data} to @code{ind}, there is only one copy of the actual index strings. +@c Document It And Call It A Feature. Sigh. @cindex arrays, sorting, @code{IGNORECASE} variable and @cindex @code{IGNORECASE} variable, array sorting and -As with array subscripts, the value of @code{IGNORECASE} -does not affect array sorting. +We said previously that comparisons are done using @command{gawk}'s +``usual comparison rules.'' Because @code{IGNORECASE} affects +string comparisons, the value of @code{IGNORECASE} also +affects sorting for both @code{asort} and @code{asorti}. +Caveat Emptor. @c ENDOFRANGE arrs @node Functions, Internationalization, Arrays, Top @@ -11894,7 +12092,7 @@ two arguments 11 and 10. The following list describes all of the built-in functions that work with numbers. -Optional parameters are enclosed in square brackets ([ ]): +Optional parameters are enclosed in square brackets@w{ ([ ]):} @table @code @item int(@var{x}) @@ -12021,9 +12219,9 @@ sequences of random numbers. The functions in this @value{SECTION} look at or change the text of one or more strings. -Optional parameters are enclosed in square brackets ([ ]). +Optional parameters are enclosed in square brackets@w{ ([ ]).} Those functions that are -specific to @command{gawk} are marked with a pound sign (@samp{#}): +specific to @command{gawk} are marked with a pound sign@w{ (@samp{#}):} @menu * Gory Details:: More than you want to know about @samp{\} and @@ -12037,7 +12235,9 @@ specific to @command{gawk} are marked with a pound sign (@samp{#}): @cindex @code{asort} function (@command{gawk}) @code{asort} is a @command{gawk}-specific extension, returning the number of elements in the array @var{source}. The contents of @var{source} are -sorted using @command{gawk}'s normal rules for comparing values, and the indices +sorted using @command{gawk}'s normal rules for comparing values +(in particular, @code{IGNORECASE} affects the sorting) +and the indices of the sorted values of @var{source} are replaced with sequential integers starting with one. If the optional array @var{dest} is specified, then @var{source} is duplicated into @var{dest}. @var{dest} is then @@ -12071,6 +12271,21 @@ The @code{asort} function is described in more detail in @code{asort} is a @command{gawk} extension; it is not available in compatibility mode (@pxref{Options, ,Command-Line Options}). +@item asorti(@var{source} @r{[}, @var{dest}@r{]}) # +@cindex @code{asorti} function (@command{gawk}) +@code{asorti} is a @command{gawk}-specific extension, returning the number of +elements in the array @var{source}. +It works similarly to @code{asort}, however, the @emph{indices} +are sorted, instead of the values. As array indices are always strings, +the comparison performed is always a string comparison. (Here too, +@code{IGNORECASE} affects the sorting.) + +The @code{asorti} function is described in more detail in +@ref{Array Sorting, ,Sorting Array Values and Indices with @command{gawk}}. +It was added in @command{gawk} 3.1.2. +@code{asorti} is a @command{gawk} extension; it is not available +in compatibility mode (@pxref{Options, ,Command-Line Options}). + @item index(@var{in}, @var{find}) @cindex @code{index} function @cindex searching @@ -12118,6 +12333,13 @@ longest, leftmost substring matched by the regular expression, at which that substring begins (one, if it starts at the beginning of @var{string}). If no match is found, it returns zero. +The @var{regexp} argument may be either a regexp constant +(@samp{/@dots{}/}) or a string constant (@var{"@dots{}"}). +In the latter case, the string is treated as a regexp to be matched. +@ref{Computed Regexps, ,Using Dynamic Regexps}, for a +discussion of the difference between the two forms, and the +implications for writing your program correctly. + The order of the first two arguments is backwards from most other string functions that work with regular expressions, such as @code{sub} and @code{gsub}. It might help to remember that @@ -12191,6 +12413,23 @@ $ echo foooobazbarrrrr | @print{} foooo barrrrr @end example +In addition, +beginning with @command{gawk} 3.1.2, +multidimensional subscripts are available providing +the start index and length of each matched subexpression: + +@example +$ echo foooobazbarrrrr | +> gawk '@{ match($0, /(fo+).+(bar*)/, arr) +> print arr[1], arr[2] +> print arr[1, "start"], arr[1, "length"] +> print arr[2, "start"], arr[2, "length"] +> @}' +@print{} foooo barrrrr +@print{} 1 5 +@print{} 9 7 +@end example + @cindex troubleshooting, @code{match} function The @var{array} argument to @code{match} is a @command{gawk} extension. In compatibility mode @@ -12237,17 +12476,30 @@ Also as with input field-splitting, if @var{fieldsep} is the null string, each individual character in the string is split into its own array element. (This is a @command{gawk}-specific extension.) +Note, however, that @code{RS} has no effect on the way @code{split} +works. Even though @samp{RS = ""} causes newline to also be an input +field separator, this does not affect how @code{split} splits strings. + @cindex dark corner, @code{split} function Modern implementations of @command{awk}, including @command{gawk}, allow the third argument to be a regexp constant (@code{/abc/}) as well as a string. @value{DARKCORNER} The POSIX standard allows this as well. +@ref{Computed Regexps, ,Using Dynamic Regexps}, for a +discussion of the difference between using a string constant or a regexp constant, +and the implications for writing your program correctly. Before splitting the string, @code{split} deletes any previously existing elements in the array @var{array}. -If @var{string} does not match @var{fieldsep} at all, @var{array} has -one element only. The value of that element is the original @var{string}. + +If @var{string} is null, the array has no elements. (So this is a portable +way to delete an entire array with one statement. +@xref{Delete, ,The @code{delete} Statement}.) + +If @var{string} does not match @var{fieldsep} at all (but is not null), +@var{array} has one element only. The value of that element is the original +@var{string}. @item sprintf(@var{format}, @var{expression1}, @dots{}) @cindex @code{sprintf} function @@ -12297,11 +12549,22 @@ Then the entire string is changed by replacing the matched text with @var{replacement}. The modified string becomes the new value of @var{target}. +The @var{regexp} argument may be either a regexp constant +(@samp{/@dots{}/}) or a string constant (@var{"@dots{}"}). +In the latter case, the string is treated as a regexp to be matched. +@ref{Computed Regexps, ,Using Dynamic Regexps}, for a +discussion of the difference between the two forms, and the +implications for writing your program correctly. + This function is peculiar because @var{target} is not simply used to compute a value, and not just any expression will do---it must be a variable, field, or array element so that @code{sub} can store a modified value there. If this argument is omitted, then the -default is to use and alter @code{$0}. +default is to use and alter @code{$0}.@footnote{Note that this means +that the record will first be regenerated using the value of @code{OFS} if +any fields have been changed, and that the fields will be updated +after the substituion, even if the operation is a ``no-op'' such +as @samp{sub(/^/, "")}.} For example: @example @@ -12477,7 +12740,11 @@ suffix is also returned if @var{length} is greater than the number of characters remaining in the string, counting from character @var{start}. -If @var{start} is less than one or greater than the number of characters +If @var{start} is less than one, @code{substr} treats it as +if it was one. (POSIX doesn't specify what to do in this case: +Unix @command{awk} acts this way, and therefore @command{gawk} +does too.) +If @var{start} is greater than the number of characters in the string, @code{substr} returns the null string. Similarly, if @var{length} is present but less than or equal to zero, the null string is returned. @@ -13846,7 +14113,6 @@ this program, using our function to format the results, prints: 21.2 @end example -@page This function deletes all the elements in an array: @example @@ -14612,7 +14878,7 @@ to standard output in the format of a GNU @code{gettext} Portable Object file. Also included in the output are any constant strings that appear as the first argument to @code{dcgettext} or as the first and second argument to @code{dcngettext}.@footnote{Starting with @code{gettext} -version 0.11.1, the @command{xgettext} utility that comes with GNU +version 0.11.5, the @command{xgettext} utility that comes with GNU @code{gettext} can handle @file{.awk} files.} @xref{I18N Example, ,A Simple Internationalization Example}, for the full list of steps to go through to create and test @@ -14941,7 +15207,7 @@ complete detail in @cite{GNU gettext tools}.) @end ifnotinfo As of this writing, the latest version of GNU @code{gettext} is -@uref{ftp://ftp.gnu.org/gnu/gettext/gettext-0.11.1.tar.gz, @value{PVERSION} 0.11.1}. +@uref{ftp://ftp.gnu.org/gnu/gettext/gettext-0.11.5.tar.gz, @value{PVERSION} 0.11.5}. If a translation of @command{gawk}'s messages exists, then @command{gawk} produces usage messages, warnings, @@ -15100,7 +15366,7 @@ done with temporary files: @example # write the data for processing -tempfile = ("/tmp/mydata." PROCINFO["pid"]) +tempfile = ("mydata." PROCINFO["pid"]) while (@var{not done with data}) print @var{data} | ("subprogram > " tempfile) close("subprogram > " tempfile) @@ -15113,7 +15379,10 @@ system("rm " tempfile) @end example @noindent -This works, but not elegantly. +This works, but not elegantly. Among other things, it requires that +the program be run in a directory that cannot be shared among users; +for example, @file{/tmp} will not do, as another user might happen +to be using a temporary file with the same name. @cindex coprocesses @cindex input/output, two-way @@ -15157,7 +15426,6 @@ standard error separately. @cindex deadlocks @cindex buffering, input/output @cindex @code{getline} command, deadlock and -</itemizedlist> @item I/O buffering may be a problem. @command{gawk} automatically flushes all output down the pipe to the child process. @@ -15215,6 +15483,26 @@ has been read, @command{gawk} terminates the coprocess and exits. As a side note, the assignment @samp{LC_ALL=C} in the @command{sort} command ensures traditional Unix (ASCII) sorting from @command{sort}. +Beginning with @command{gawk} 3.1.2, you may use Pseudo-ttys (ptys) for +two-way communication instead of pipes, if your system supports them. +This is done on a per-command basis, by setting a special element +in the @code{PROCINFO} array +(@pxref{Auto-set, ,Built-in Variables That Convey Information}), +like so: + +@example +command = "sort -nr" # command, saved in variable for convenience +PROCINFO[command, "pty"] = 1 # update PROCINFO +print @dots{} |& command # start two-way pipe +@dots{} +@end example + +@noindent +Using ptys avoids the buffer deadlock issues described earlier, at some +loss in performance. If your system does not have ptys, or if all the +system's ptys are in use, @command{gawk} automatically falls back to +using regular pipes. + @node TCP/IP Networking, Portal Files, Two-way I/O, Advanced Features @section Using @command{gawk} for Network Programming @cindex advanced features, @command{gawk}, network programming @@ -15894,6 +16182,8 @@ With an optional argument of @samp{fatal}, lint warnings become fatal errors. This may be drastic, but its use will certainly encourage the development of cleaner @command{awk} programs. +With an optional argument of @samp{invalid}, only warnings about things that are +actually invalid are issued. (This is not fully implemented yet.) @item -W lint-old @itemx --lint-old @@ -17444,12 +17734,12 @@ This code relies on the @code{ARGIND} variable which is specific to @command{gawk}. If you are not using @command{gawk}, you can use ideas presented in -@iftex +@ifnotinfo the previous @value{SECTION} -@end iftex -@ifnottex +@end ifnotinfo +@ifinfo @ref{Filetrans Function, ,Noting @value{DDF} Boundaries}, -@end ifnottex +@end ifinfo to either update @code{ARGIND} on your own or modify this code as appropriate. @@ -17990,12 +18280,26 @@ Following is @command{pwcat}, a C program that ``cats'' the password database: * Public Domain */ +#if HAVE_CONFIG_H +#include <config.h> +#endif + @c endfile @end ignore @c file eg/lib/pwcat.c #include <stdio.h> #include <pwd.h> +@c endfile +@ignore +@c file eg/lib/pwcat.c +#if defined (STDC_HEADERS) +#include <stdlib.h> +#endif + +@c endfile +@end ignore +@c file eg/lib/pwcat.c int main(argc, argv) int argc; @@ -18004,12 +18308,12 @@ char **argv; struct passwd *p; while ((p = getpwent()) != NULL) - printf("%s:%s:%d:%d:%s:%s:%s\n", - p->pw_name, p->pw_passwd, p->pw_uid, - p->pw_gid, p->pw_gecos, p->pw_dir, p->pw_shell); + printf("%s:%s:%ld:%ld:%s:%s:%s\n", + p->pw_name, p->pw_passwd, (long) p->pw_uid, + (long) p->pw_gid, p->pw_gecos, p->pw_dir, p->pw_shell); endpwent(); - exit(0); + return 0; @} @c endfile @end example @@ -18028,9 +18332,12 @@ The user's encrypted password. This may not be available on some systems. @item User-ID The user's numeric user ID number. +(On some systems it's a C @code{long}, and not an @code{int}. Thus +we cast it to @code{long} for all cases.) @item Group-ID The user's numeric group ID number. +(Similar comments about @code{long} vs.@: @code{int} apply here.) @item Full name The user's full name, and perhaps other information associated with the @@ -18328,9 +18635,13 @@ is as follows: #if HAVE_CONFIG_H #include <config.h> #endif + +#if defined (STDC_HEADERS) +#include <stdlib.h> +#endif -#ifndef HAVE_GETPGRENT -int main() { exit(0); } +#ifndef HAVE_GETGRENT +int main() { return 0; } #else @c endfile @end ignore @@ -18347,8 +18658,8 @@ char **argv; int i; while ((g = getgrent()) != NULL) @{ - printf("%s:%s:%d:", g->gr_name, g->gr_passwd, - g->gr_gid); + printf("%s:%s:%ld:", g->gr_name, g->gr_passwd, + (long) g->gr_gid); for (i = 0; g->gr_mem[i] != NULL; i++) @{ printf("%s", g->gr_mem[i]); @group @@ -18359,13 +18670,13 @@ char **argv; putchar('\n'); @} endgrent(); - exit(0); + return 0; @} @c endfile @end example @ignore @c file eg/lib/grcat.c -#endif /* HAVE_GETPGRENT */ +#endif /* HAVE_GETGRENT */ @c endfile @end ignore @@ -18383,6 +18694,8 @@ usually empty or set to @samp{*}. @item Group ID Number The numeric group ID number. This number is unique within the file. +(On some systems it's a C @code{long}, and not an @code{int}. Thus +we cast it to @code{long} for all cases.) @item Group Member List A comma-separated list of usernames. These users are members of the group. @@ -21378,8 +21691,11 @@ means it should accept all of @command{gawk}'s command-line arguments, including the ability to have multiple source files specified via @option{-f}, and the ability to mix command-line and library source files. -The program is written using the POSIX Shell (@command{sh}) command language. -It works as follows: +The program is written using the POSIX Shell (@command{sh}) command +language.@footnote{Fully explaining the @command{sh} language is beyond +the scope of this book. We provide some minimal explanations, but see +a good shell programming book if you wish to understand things in more +depth.} It works as follows: @enumerate @item @@ -21388,38 +21704,38 @@ Loop through the arguments, saving anything that doesn't represent @item For any arguments that do represent @command{awk} text, put the arguments into -a temporary file that will be expanded. There are two cases: +a shell variable that will be expanded. There are two cases: @enumerate a @item Literal text, provided with @option{--source} or @option{--source=}. This -text is just echoed directly. The @command{echo} program automatically -supplies a trailing newline. +text is just appended directly. @item -Source @value{FN}s, provided with @option{-f}. We use a neat trick and echo -@samp{@@include @var{filename}} into the temporary file. Since the file-inclusion +Source @value{FN}s, provided with @option{-f}. We use a neat trick and append +@samp{@@include @var{filename}} to the shell variable's contents. Since the file-inclusion program works the way @command{gawk} does, this gets the text of the file included into the program at the correct point. @end enumerate @item -Run an @command{awk} program (naturally) over the temporary file to expand +Run an @command{awk} program (naturally) over the shell variable's contents to expand @samp{@@include} statements. The expanded program is placed in a second -temporary file. +shell variable. @item Run the expanded program with @command{gawk} and any other original command-line arguments that the user supplied (such as the data @value{FN}s). @end enumerate -The initial part of the program turns on shell tracing if the first -argument is @samp{debug}. Otherwise, a shell @code{trap} statement -arranges to clean up any temporary files on program exit or upon an -interrupt. +This program uses shell variables extensively; for storing command line arguments, +the text of the @command{awk} program that will expand the user's program, for the +user's original program, and for the expanded program. Doing so removes some +potential problems that might arise were we to use temporary files instead, +at the cost of making the script somewhat more complicated. -@c 2e: For the temp file handling, go with Darrel's ig=${TMP:-/tmp}/igs.$$ -@c 2e: or something as similar as possible. +The initial part of the program turns on shell tracing if the first +argument is @samp{debug}. The next part loops through all the command-line arguments. There are several cases of interest: @@ -21440,13 +21756,17 @@ programming trick. Don't worry about it if you are not familiar with These are saved and passed on to @command{gawk}. @item -f@r{,} --file@r{,} --file=@r{,} -Wfile= -The @value{FN} is saved to the temporary file @file{/tmp/ig.s.$$} with an +The @value{FN} is appended to the shell variable @code{program} with an @samp{@@include} statement. -The @command{sed} utility is used to remove the leading option part of the +The @command{expr} utility is used to remove the leading option part of the argument (e.g., @samp{--file=}). +(Typical @command{sh} usage would be to use the @command{echo} and @command{sed} +utilities to do this work. Unfortunately, some versions of @command{echo} evaluate +escape sequences in their arguments, possibly mangling the program text. +Using @command{expr} avoids this problem.) @item --source@r{,} --source=@r{,} -Wsource= -The source text is echoed into @file{/tmp/ig.s.$$}. +The source text is appended to @code{program}. @item --version@r{,} -Wversion @command{igawk} prints its version number, runs @samp{gawk --version} @@ -21457,17 +21777,11 @@ If none of the @option{-f}, @option{--file}, @option{-Wfile}, @option{--source}, or @option{-Wsource} arguments are supplied, then the first nonoption argument should be the @command{awk} program. If there are no command-line arguments left, @command{igawk} prints an error message and exits. -Otherwise, the first argument is echoed into @file{/tmp/ig.s.$$}. +Otherwise, the first argument is appended to @code{program}. In any case, after the arguments have been processed, -@file{/tmp/ig.s.$$} contains the complete text of the original @command{awk} +@code{program} contains the complete text of the original @command{awk} program. -@cindex @command{sed} utility -@cindex stream editors -The @samp{$$} in @command{sh} represents the current process ID number. -It is often used in shell programs to generate unique temporary @value{FN}s. -This allows multiple users to run @command{igawk} without worrying -that the temporary @value{FN}s will clash. The program is as follows: @cindex @code{igawk.sh} program @@ -21489,49 +21803,56 @@ if [ "$1" = debug ] then set -x shift -else - # cleanup on exit, hangup, interrupt, quit, termination - trap 'rm -f /tmp/ig.[se].$$' 0 1 2 3 15 fi +# A literal newline, so that program text is formmatted correctly +n=' +' + +# Initialize variables to empty +program= +opts= + while [ $# -ne 0 ] # loop over arguments do case $1 in --) shift; break;; -W) shift - set -- -W"$@@" + # The $@{x?'message here'@} construct prints a + # diagnostic if $x is the null string + set -- -W"$@{@@?'missing operand'@}" continue;; - -[vF]) opts="$opts $1 '$2'" + -[vF]) opts="$opts $1 '$@{2?'missing operand'@}'" shift;; -[vF]*) opts="$opts '$1'" ;; - -f) echo @@include "$2" >> /tmp/ig.s.$$ + -f) program="$program$n@@include $@{2?'missing operand'@}" shift;; - -f*) f=`echo "$1" | sed 's/-f//'` - echo @@include "$f" >> /tmp/ig.s.$$ ;; + -f*) f=`expr "$1" : '-f\(.*\)'` + program="$program$n@@include $f";; - -?file=*) # -Wfile or --file - f=`echo "$1" | sed 's/-.file=//'` - echo @@include "$f" >> /tmp/ig.s.$$ ;; + -[W-]file=*) + f=`expr "$1" : '-.file=\(.*\)'` + program="$program$n@@include $f";; - -?file) # get arg, $2 - echo @@include "$2" >> /tmp/ig.s.$$ + -[W-]file) + program="$program$n@@include $@{2?'missing operand'@}" shift;; - -?source=*) # -Wsource or --source - t=`echo "$1" | sed 's/-.source=//'` - echo "$t" >> /tmp/ig.s.$$ ;; + -[W-]source=*) + t=`expr "$1" : '-.source=\(.*\)'` + program="$program$n$t";; - -?source) # get arg, $2 - echo "$2" >> /tmp/ig.s.$$ + -[W-]source) + program="$program$n$@{2?'missing operand'@}" shift;; - -?version) - echo igawk: version 1.0 1>&2 + -[W-]version) + echo igawk: version 2.0 1>&2 gawk --version exit 0 ;; @@ -21542,26 +21863,20 @@ do shift done -if [ ! -s /tmp/ig.s.$$ ] +if [ -z "$program" ] then -@group - if [ -z "$1" ] - then - echo igawk: no program! 1>&2 - exit 1 -@end group - else - echo "$1" > /tmp/ig.s.$$ - shift - fi + program=$@{1?'missing program'@} + shift fi -# at this point, /tmp/ig.s.$$ has the program +# At this point, `program' has the program. @c endfile @end example The @command{awk} program to process @samp{@@include} directives -reads through the program, one line at a time, using @code{getline} +is stored in the shell variable @code{expand_prog}. Doing this keeps +the shell script readable. The @command{awk} program +reads through the user's program, one line at a time, using @code{getline} (@pxref{Getline, ,Explicit Input with @code{getline}}). The input @value{FN}s and @samp{@@include} statements are managed using a stack. As each @samp{@@include} is encountered, the current @value{FN} is @@ -21595,8 +21910,7 @@ slower. @example @c file eg/prog/igawk.sh -gawk -- ' -# process @@include directives +expand_prog=' function pathto(file, i, t, junk) @{ @@ -21635,7 +21949,7 @@ BEGIN @{ @c endfile @end example -The stack is initialized with @code{ARGV[1]}, which will be @file{/tmp/ig.s.$$}. +The stack is initialized with @code{ARGV[1]}, which will be @file{/dev/stdin}. The main loop comes next. Input lines are read in succession. Lines that do not start with @samp{@@include} are printed verbatim. If the line does start with @samp{@@include}, the @value{FN} is in @code{$2}. @@ -21681,14 +21995,44 @@ the program is done: @} close(input[stackptr]) @} -@}' /tmp/ig.s.$$ > /tmp/ig.e.$$ +@}' # close quote ends `expand_prog' variable + +processed_program=`gawk -- "$expand_prog" /dev/stdin <<EOF +$program +EOF +` @c endfile @end example +The shell construct @samp{@var{command} << @var{marker}} is called a @dfn{here document}. +Everything in the shell script up to the @var{marker} is fed to @var{command} as input. +The shell processes the contents of the here document for variable and command substitution +(and possibly other things as well, depending upon the shell). + +The shell construct @samp{`@dots{}`} is called @dfn{command substitution}. +The output of the command between the two backquotes (grave accents) is substituted +into the command line. It is saved as a single string, even if the results +contain whitespace. + +The expanded program is saved in the variable @code{processed_program}. +It's done in these steps: + +@enumerate +@item +Run @command{gawk} with the @samp{@@include}-processing program (the +value of the @code{expand_prog} shell variable) on standard input. + +@item +Standard input is the contents of the user's program, from the shell variable @code{program}. +Its contents are fed to @command{gawk} via a here document. + +@item +The results of this processing are saved in the shell variable @code{processed_program} by using command substitution. +@end enumerate + The last step is to call @command{gawk} with the expanded program, along with the original -options and command-line arguments that the user supplied. @command{gawk}'s -exit status is passed back on to @command{igawk}'s calling program: +options and command-line arguments that the user supplied. @c this causes more problems than it solves, so leave it out. @ignore @@ -21707,14 +22051,15 @@ end of file indication. @example @c file eg/prog/igawk.sh -eval gawk -f /tmp/ig.e.$$ $opts -- "$@@" - -exit $? +eval gawk $opts -- '"$processed_program"' '"$@@"' @c endfile @end example -This version of @command{igawk} represents my third attempt at this program. -There are three key simplifications that make the program work better: +The @command{eval} command is a shell construct that reruns the shell's parsing +process. This keeps things properly quoted. + +This version of @command{igawk} represents my fourth attempt at this program. +There are four key simplifications that make the program work better: @itemize @bullet @item @@ -21734,6 +22079,13 @@ considerably. Using a @code{getline} loop in the @code{BEGIN} rule does it all in one place. It is not necessary to call out to a separate loop for processing nested @samp{@@include} statements. + +@item +Instead of saving the expanded program in a temporary file, putting it in a shell variable +avoids some potential security problems. +This has the disadvantage that the script relies upon more features +of the @command{sh} language, making it harder to follow for those who +aren't familiar with @command{sh}. @end itemize Also, this program illustrates that it is often worthwhile to combine @@ -22365,11 +22717,11 @@ making translations easier (@pxref{Printf Ordering, , Rearranging @code{printf} Arguments}). @item -The @code{asort} function for sorting arrays +The @code{asort} and @code{asorti} functions for sorting arrays (@pxref{Array Sorting, ,Sorting Array Values and Indices with @command{gawk}}). @item -The @code{bindtextdomain} and @code{dcgettext} functions +The @code{bindtextdomain}, @code{dcgettext} and @code{dcngettext} functions for internationalization (@pxref{Programmer i18n, ,Internationalizing @command{awk} Programs}). @@ -22449,6 +22801,11 @@ The Atari port became officially unsupported The source code now uses new-style function definitions, with @command{ansi2knr} to convert the code on systems with old compilers. +@item +The @option{--disable-lint} configuration option to disable lint checking +at compile time +(@pxref{Additional Configuration Options, , Additional Configuration Options}). + @end itemize @c XXX ADD MORE STUFF HERE @@ -23026,6 +23383,26 @@ This option should be used on systems that do @emph{not} use @value{PVERSION} 2 of the GNU C library. All known modern GNU/Linux systems use Glibc 2. Use this option on any other system. +@cindex @code{--disable-lint} configuration option +@cindex configuration option, @code{--disable-lint} +@item --disable-lint +This option disables all lint checking within @code{gawk}. The +@option{--lint} and @option{--lint-old} options +(@pxref{Options, , Command-Line Options}) +are accepted, but silently do nothing. +Similarly, setting the @code{LINT} variable +(@pxref{User-modified, , Built-in Variables That Control @command{awk}}) +has no effect on the running @command{awk} program. + +When used with GCC's automatic dead-code-elimination, this option +cuts almost 200K bytes off the size of the @command{gawk} +executable on GNU/Linux x86 systems. Results on other systems and +with other compilers are likely to vary. +Using this option may bring you some slight performance improvement. + +Using this option will cause some of the tests in the test suite +to fail. This option may be removed at a later date. + @cindex @code{--disable-nls} configuration option @cindex configuration option, @code{--disable-nls} @item --disable-nls @@ -23249,16 +23626,21 @@ or more detailed installation instructions. development tools from DJ Delorie (DJGPP; MS-DOS only) or Eberhard Mattes (EMX; MS-DOS, Win32 and OS/2). Microsoft Visual C/C++ can be used to build a Win32 version, and Microsoft C/C++ can be -used to build 16-bit versions for MS-DOS and OS/2. The file +used to build 16-bit versions for MS-DOS and OS/2. +@c FIXME: +(As of @command{gawk} 3.1.2, the MSC version doesn't work. However, +the maintainer is working on fixing it.) +The file @file{README_d/README.pc} in the @command{gawk} distribution contains additional notes, and @file{pc/Makefile} contains important information on compilation options. -To build @command{gawk} for MS-DOS, Win32, and OS/2 (16 bit; for 32 bit (EMX) -see below), copy the files in the @file{pc} directory (@emph{except} for -@file{ChangeLog}) to the directory with the rest of the @command{gawk} sources. -The @file{Makefile} contains a configuration section with comments and may need -to be edited in order to work with your @command{make} utility. +To build @command{gawk} for MS-DOS, Win32, and OS/2 (16 bit only; for 32 bit +(EMX) you can use the @command{configure} script and skip the following paragraphs; +for details see below), copy the files in the @file{pc} directory (@emph{except} +for @file{ChangeLog}) to the directory with the rest of the @command{gawk} +sources. The @file{Makefile} contains a configuration section with comments and +may need to be edited in order to work with your @command{make} utility. The @file{Makefile} contains a number of targets for building various MS-DOS, Win32, and OS/2 versions. A list of targets is printed if the @command{make} @@ -23276,69 +23658,79 @@ companion utilities or appropriate GNU utilities. However, some editing of replacement. Details can be found in @file{README_d/README.pc} and in the file @file{pc/Makefile.tst}. -To build @command{gawk} for OS/2 (32 bit, EMX), there are three possibilities: +The 32 bit EMX version of @command{gawk} works ``out of the box'' under OS/2. +In principle, it is possible to compile @command{gawk} the following way: -@enumerate 1 -@item -Using the @command{configure} script included in the official @command{gawk} distribution. -@command{configure} need not be recreated but a number of restrictions exist -when using this choice: +@example +$ ./configure +$ make +@end example -@itemize @bullet -@item -An external @code{gettext} library cannot be used. I.e. the @command{configure} option -@option{--without-included-gettext} does not work. Unfortunately, -the internal @code{gettext} library is seriuosly broken for OS/2. -Therefore you have to use @option{--disable-nls}. +This is not recommended, though. To get an OMF executable you should +use the following commands at your @command{sh} prompt: -@item -Executables must be linked statically (@code{a.out} format only). -@samp{make install} does not work. +@example +$ CPPFLAGS="-D__ST_MT_ERRNO__" +$ export CPPFLAGS +$ CFLAGS="-O2 -Zomf -Zmt" +$ export CFLAGS +$ LDFLAGS="-s -Zcrtdll -Zlinker /exepack:2 -Zlinker /pm:vio -Zstack 0x8000" +$ export LDFLAGS +$ RANLIB="echo" +$ export RANLIB +$ ./configure --prefix=c:/usr --without-included-gettext +$ make AR=emxomfar +@end example + +These are just suggestions. You may use any other set of (self-consistent) +environment variables and compiler flags. + +To get an FHS-compliant file hierarchy it is recommended to use the additional +@command{configure} options @option{--infodir=c:/usr/share/info}, @option{--mandir=c:/usr/share/man} +and @option{--libexecdir=c:/usr/lib}. + +The internal @code{gettext} library tends to be problematic. It is therefore recommended +to use either an external one (@option{--without-included-gettext}) or to disable +NLS entirely (@option{--disable-nls}). -These restrictions are due to restrictions in Autoconf 2.13 and cannot be -avoided. They will vanish as soon as @command{gawk} moves on to Autoconf 2.5x. -Now enter the following commands at your @command{sh} prompt: +If you use GCC 2.95 or newer it is recommended to use also: @example -$ CC="gcc"; export CC -$ CFLAGS="-O2"; export CFLAGS -$ AWK="awk"; export AWK -$ LD="ld"; export LD -$ LDFLAGS="-Zexe"; export LDFLAGS -$ RANLIB="ranlib"; export RANLIB -$ ac_cv_header_sys_socket_h="yes" -$ export ac_cv_header_sys_socket_h -$ ./configure --prefix=c:/usr --disable-nls -$ make +$ LIBS="-lgcc" +$ export LIBS @end example -@end itemize -@item -Using a special version of Autoconf 2.13 for OS/2 to recreate @command{configure}. -Not tested. In principle this should work but the same restrictions -apply as in 1, but the environment variables @env{CC}, @env{AWK}, -@env{LDFLAGS} and @env{RANLIB} are not necessary. +You can also get an @code{a.out} executable if you prefer: -@item -Using Autoconf 2.5x to recreate @command{configure} (2.52f or higher recommended). -Some patches must be applied to @file{Makefile.am} and @file{test/Makefile.am} -and @file{po/Makefile.in.in}. Currently not supported. -@end enumerate - -@strong{Note:} Even if the compiled @command{gawk.exe} executable contains a DOS header -(@code{a.out} format), it does @emph{not} work under DOS. To compile an executable -that runs under DOS, @env{CPPFLAGS} must be set to @code{"-DPIPES_SIMULATED"}. +@example +$ CPPFLAGS="-D__ST_MT_ERRNO__" +$ export CPPFLAGS +$ CFLAGS="-O2 -Zmt" +$ export CFLAGS +$ LDFLAGS="-s -Zstack 0x8000" +$ LIBS="-lgcc" +$ unset RANLIB +$ ./configure --prefix=c:/usr --without-included-gettext +$ make +@end example + +@strong{Note:} Even if the compiled @command{gawk.exe} (@code{a.out}) executable +contains a DOS header, it does @emph{not} work under DOS. To compile an executable +that runs under DOS, @code{"-DPIPES_SIMULATED"} must be added to @env{CPPFLAGS}. But then some nonstandard extensions of @command{gawk} (e.g., @samp{|&}) do not work! After compilation the internal tests can be performed. Enter @samp{make check CMP="diff -a"} at your command prompt. All tests but the @code{pid} test are expected to work properly. The @code{pid} -test might or might not work, no idea why. +test fails because child processes are not started by @code{fork()}. + +@samp{make install} works as expected. @strong{Note:} Most OS/2 ports of GNU @command{make} are not able to handle the Makefiles of this package. If you encounter any problems with @command{make} -try GNU @command{make} 3.79.1. You should find the latest version on -@uref{ftp://ftp.unixos2.org}. +try GNU Make 3.79.1 or later versions. You should find the latest +version on @uref{http://www.unixos2.org/sw/pub/binary/make/} or on +@uref{ftp://hobbes.nmsu.edu/pub/os2/}. @node PC Using, Cygwin, PC Compiling, PC Installation @@ -23508,6 +23900,7 @@ for any other environment for MS-DOS or MS-Windows. @appendixsubsec How to Compile and Install @command{gawk} on VMS @c based on material from Pat Rankin <rankin@eql.caltech.edu> +@c now rankin@pactechdata.com @cindex installation, vms This @value{SUBSECTION} describes how to compile and install @command{gawk} under VMS. @@ -23955,7 +24348,7 @@ Stephen Davies, @email{scldad@@sdc.com.au}. @cindex Rankin, Pat @item VMS -Pat Rankin, @email{rankin@@eql.caltech.edu}. +Pat Rankin, @email{rankin@@pactechdata.com}. @end table @end ignore @@ -23980,7 +24373,7 @@ Darrel Hankerson, @email{hankedr@@mail.auburn.edu}. @item Tandem @tab Stephen Davies, @email{scldad@@sdc.com.au}. @cindex Rankin, Pat -@item VMS @tab Pat Rankin, @email{rankin@@eql.caltech.edu}. +@item VMS @tab Pat Rankin, @email{rankin@@pactechdata.com}. @end multitable If your bug is also reproducible under Unix, please send a copy of your @@ -24117,12 +24510,22 @@ It also has a number of extensions. The @command{awk} translator is released under the GPL, and the library is under the LGPL. -@ignore -To get @command{awka}, go to its home page at -Go to @uref{http://awka.sourceforge.net}. -@end ignore To get @command{awka}, go to @uref{http://awka.sourceforge.net}. -You can reach Andrew Sumner at @email{andrew_sumner@@bigfoot.com}. +You can reach Andrew Sumner at @email{andrew@@zbcom.net}. + +@cindex Beebe, Nelson H.F. +@cindex @command{pawk} profiling Bell Labs @command{awk} +@item @command{pawk} +Nelson H.F.@: Beebe at the University of Utah has modified +the Bell Labs @command{awk} to provide timing and profiling information. +It is different from @command{pgawk} +(@pxref{Profiling, ,Profiling Your @command{awk} Programs}), +in that it uses CPU-based profiling, not line-count +profiling. You may find it at either +@uref{ftp://ftp.math.utah.edu/pub/pawk/pawk-20020210.tar.gz} +or +@uref{http://www.math.utah.edu/pub/pawk/pawk-20020210.tar.gz}. + @end table @c ENDOFRANGE gligawk @c ENDOFRANGE ingawk @@ -24234,7 +24637,10 @@ read it, please do so, preferably @emph{before} starting to modify @command{gawk the GNU Project's @command{ftp} site, at -@uref{ftp://ftp.gnu.org/gnu/GNUInfo/standards.text}. +@uref{ftp://ftp.gnu.org/gnu/GNUinfo/standards.text}. +An HTML version, suitable for reading with a WWW browser, is +available at +@uref{http://www.gnu.org/prep/standards_toc.html}. Texinfo, Info, and DVI versions are also available.) @cindex @command{gawk}, coding style in @@ -25275,11 +25681,6 @@ Following is a list of probable improvements that will make @command{gawk} perform better: @table @asis -@item An improved version of @code{dfa} -The @code{dfa} pattern matcher from GNU @command{grep} has some -problems. Either a new version or a fixed one will deal with some -important regexp matching issues. - @c NEXT ED: remove this item. awka and mawk do these respectively @item Compilation of @command{awk} programs @command{gawk} uses a Bison (YACC-like) @@ -25712,7 +26113,7 @@ There is a very nice paper on floating-point arithmetic by David Goldberg, ``What Every Computer Scientist Should Know About Floating-point Arithmetic,'' @cite{ACM Computing Surveys} @strong{23}, 1 (1991-03), -5-48.@footnote{@uref{http://www.validgh.com/goldberg/paper.ps}.} +5-48.@footnote{@uref{http://www.validlab.com/goldberg/paper.ps}.} This is worth reading if you are interested in the details, but it does require a background in computer science. @@ -25899,12 +26300,12 @@ Another name for an @command{awk} program. @item Bash The GNU version of the standard shell -@iftex +@ifnotinfo (the @b{B}ourne-@b{A}gain @b{SH}ell). -@end iftex -@ifnottex +@end ifnotinfo +@ifinfo (the Bourne-Again SHell). -@end ifnottex +@end ifinfo See also ``Bourne Shell.'' @item BBS @@ -26915,32 +27316,33 @@ consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Lesser General Public License instead of this License. -@node GNU Free Documentation License, Index, Copying, Top +@node GNU Free Documentation License @unnumbered GNU Free Documentation License -@center Version 1.1, March 2000 + @cindex FDL (Free Documentation License) @cindex Free Documentation License (FDL) @cindex GNU Free Documentation License +@center Version 1.2, November 2002 @display -Copyright (C) 2000 Free Software Foundation, Inc. -59 Temple Place, Suite 330, Boston, MA 02111-1307 USA +Copyright @copyright{} 2000,2001,2002 Free Software Foundation, Inc. +59 Temple Place, Suite 330, Boston, MA 02111-1307, USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. @end display -@sp 1 + @enumerate 0 @item PREAMBLE The purpose of this License is to make a manual, textbook, or other -written document ``free'' in the sense of freedom: to assure everyone -the effective freedom to copy and redistribute it, with or without -modifying it, either commercially or noncommercially. Secondarily, -this License preserves for the author and publisher a way to get -credit for their work, while not being considered responsible for -modifications made by others. +functional and useful document @dfn{free} in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. This License is a kind of ``copyleft'', which means that derivative works of the document must themselves be free in the same sense. It @@ -26955,60 +27357,72 @@ it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference. -@sp 1 @item APPLICABILITY AND DEFINITIONS -This License applies to any manual or other work that contains a -notice placed by the copyright holder saying it can be distributed -under the terms of this License. The ``Document'', below, refers to any -such manual or work. Any member of the public is a licensee, and is -addressed as ``you''. +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The ``Document'', below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as ``you''. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. A ``Modified Version'' of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language. -A ``Secondary Section'' is a named appendix or a front-matter section of -the Document that deals exclusively with the relationship of the -publishers or authors of the Document to the Document's overall subject -(or to related matters) and contains nothing that could fall directly -within that overall subject. (For example, if the Document is in part a -textbook of mathematics, a Secondary Section may not explain any -mathematics.) The relationship could be a matter of historical +A ``Secondary Section'' is a named appendix or a front-matter section +of the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall +subject (or to related matters) and contains nothing that could fall +directly within that overall subject. (Thus, if the Document is in +part a textbook of mathematics, a Secondary Section may not explain +any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them. The ``Invariant Sections'' are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice -that says that the Document is released under this License. +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. The ``Cover Texts'' are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that -the Document is released under this License. +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. A ``Transparent'' copy of the Document means a machine-readable copy, represented in a format whose specification is available to the -general public, whose contents can be viewed and edited directly and +general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file -format whose markup has been designed to thwart or discourage -subsequent modification by readers is not Transparent. A copy that is -not ``Transparent'' is called ``Opaque''. +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not ``Transparent'' is called ``Opaque''. Examples of suitable formats for Transparent copies include plain -ASCII without markup, Texinfo input format, LaTeX input format, SGML -or XML using a publicly available DTD, and standard-conforming simple -HTML designed for human modification. Opaque formats include -PostScript, PDF, proprietary formats that can be read and edited only -by proprietary word processors, SGML or XML for which the DTD and/or -processing tools are not generally available, and the -machine-generated HTML produced by some word processors for output -purposes only. +@sc{ascii} without markup, Texinfo input format, La@TeX{} input +format, @acronym{SGML} or @acronym{XML} using a publicly available +@acronym{DTD}, and standard-conforming simple @acronym{HTML}, +PostScript or @acronym{PDF} designed for human modification. Examples +of transparent image formats include @acronym{PNG}, @acronym{XCF} and +@acronym{JPG}. Opaque formats include proprietary formats that can be +read and edited only by proprietary word processors, @acronym{SGML} or +@acronym{XML} for which the @acronym{DTD} and/or processing tools are +not generally available, and the machine-generated @acronym{HTML}, +PostScript or @acronym{PDF} produced by some word processors for +output purposes only. The ``Title Page'' means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material @@ -27016,7 +27430,22 @@ this License requires to appear in the title page. For works in formats which do not have any title page as such, ``Title Page'' means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text. -@sp 1 + +A section ``Entitled XYZ'' means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as ``Acknowledgements'', +``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' +of such a section when you modify the Document means that it remains a +section ``Entitled XYZ'' according to this definition. + +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + @item VERBATIM COPYING @@ -27032,13 +27461,14 @@ number of copies you must also follow the conditions in section 3. You may also lend copies, under the same conditions stated above, and you may publicly display copies. -@sp 1 + @item COPYING IN QUANTITY -If you publish printed copies of the Document numbering more than 100, -and the Document's license notice requires Cover Texts, you must enclose -the copies in covers that carry, clearly and legibly, all these Cover +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present @@ -27056,21 +27486,20 @@ pages. If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy -a publicly-accessible computer-network location containing a complete -Transparent copy of the Document, free of added material, which the -general network-using public has access to download anonymously at no -charge using public-standard network protocols. If you use the latter -option, you must take reasonably prudent steps, when you begin -distribution of Opaque copies in quantity, to ensure that this -Transparent copy will remain thus accessible at the stated location -until at least one year after the last time you distribute an Opaque -copy (directly or through your agents or retailers) of that edition to -the public. +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document. -@sp 1 + @item MODIFICATIONS @@ -27093,7 +27522,8 @@ if the original publisher of that version gives permission. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the -Document (all of its principal authors, if it has less than five). +Document (all of its principal authors, if it has fewer than five), +unless they release you from this requirement. @item State on the Title page the name of the publisher of the @@ -27119,10 +27549,10 @@ and required Cover Texts given in the Document's license notice. Include an unaltered copy of this License. @item -Preserve the section entitled ``History'', and its title, and add to -it an item stating at least the title, year, new authors, and +Preserve the section Entitled ``History'', Preserve its Title, and add +to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If -there is no section entitled ``History'' in the Document, create one +there is no section Entitled ``History'' in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence. @@ -27137,10 +27567,10 @@ least four years before the Document itself, or if the original publisher of the version it refers to gives permission. @item -In any section entitled ``Acknowledgements'' or ``Dedications'', -preserve the section's title, and preserve in the section all the -substance and tone of each of the contributor acknowledgements -and/or dedications given therein. +For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve +the Title of the section, and preserve in the section all the +substance and tone of each of the contributor acknowledgements and/or +dedications given therein. @item Preserve all the Invariant Sections of the Document, @@ -27148,12 +27578,15 @@ unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles. @item -Delete any section entitled ``Endorsements''. Such a section +Delete any section Entitled ``Endorsements''. Such a section may not be included in the Modified Version. @item -Do not retitle any existing section as ``Endorsements'' -or to conflict in title with any Invariant Section. +Do not retitle any existing section to be Entitled ``Endorsements'' or +to conflict in title with any Invariant Section. + +@item +Preserve any Warranty Disclaimers. @end enumerate If the Modified Version includes new front-matter sections or @@ -27163,9 +27596,9 @@ of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles. -You may add a section entitled ``Endorsements'', provided it contains +You may add a section Entitled ``Endorsements'', provided it contains nothing but endorsements of your Modified Version by various -parties--for example, statements of peer review or that the text has +parties---for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard. @@ -27182,7 +27615,7 @@ permission from the previous publisher that added the old one. The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version. -@sp 1 + @item COMBINING DOCUMENTS @@ -27191,7 +27624,7 @@ License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its -license notice. +license notice, and that you preserve all their Warranty Disclaimers. The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single @@ -27202,12 +27635,12 @@ author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work. -In the combination, you must combine any sections entitled ``History'' -in the various original documents, forming one section entitled -``History''; likewise combine any sections entitled ``Acknowledgements'', -and any sections entitled ``Dedications''. You must delete all sections -entitled ``Endorsements.'' -@sp 1 +In the combination, you must combine any sections Entitled ``History'' +in the various original documents, forming one section Entitled +``History''; likewise combine any sections Entitled ``Acknowledgements'', +and any sections Entitled ``Dedications''. You must delete all +sections Entitled ``Endorsements.'' + @item COLLECTIONS OF DOCUMENTS @@ -27221,25 +27654,27 @@ You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document. -@sp 1 + @item AGGREGATION WITH INDEPENDENT WORKS A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or -distribution medium, does not as a whole count as a Modified Version -of the Document, provided no compilation copyright is claimed for the -compilation. Such a compilation is called an ``aggregate'', and this -License does not apply to the other self-contained works thus compiled -with the Document, on account of their being thus compiled, if they -are not themselves derivative works of the Document. +distribution medium, is called an ``aggregate'' if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these -copies of the Document, then if the Document is less than one quarter -of the entire aggregate, the Document's Cover Texts may be placed on -covers that surround only the Document within the aggregate. -Otherwise they must appear on covers around the whole aggregate. -@sp 1 +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. + @item TRANSLATION @@ -27249,11 +27684,18 @@ Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a -translation of this License provided that you also include the -original English version of this License. In case of a disagreement -between the translation and the original English version of this -License, the original English version will prevail. -@sp 1 +translation of this License, and all the license notices in the +Document, and any Warrany Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + +If a section in the Document is Entitled ``Acknowledgements'', +``Dedications'', or ``History'', the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. + @item TERMINATION @@ -27264,7 +27706,7 @@ automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. -@sp 1 + @item FUTURE REVISIONS OF THIS LICENSE @@ -27282,7 +27724,6 @@ of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. - @end enumerate @c fakenode --- for prepinfo @@ -27294,27 +27735,41 @@ license notices just after the title page: @smallexample @group - Copyright (C) @var{year} @var{your name}. Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.1 + under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; - with the Invariant Sections being @var{list their titles}, with the - Front-Cover Texts being @var{list}, and with the Back-Cover Texts being @var{list}. + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''. @end group @end smallexample -If you have no Invariant Sections, write ``with no Invariant Sections'' -instead of saying which ones are invariant. If you have no -Front-Cover Texts, write ``no Front-Cover Texts'' instead of -``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts. + +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the ``with...Texts.'' line with this: + +@smallexample +@group + with the Invariant Sections being @var{list their titles}, with + the Front-Cover Texts being @var{list}, and with the Back-Cover Texts + being @var{list}. +@end group +@end smallexample + +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software. +@c Local Variables: +@c ispell-local-pdict: "ispell-dict" +@c End: + + @node Index, , GNU Free Documentation License, Top @unnumbered Index @printindex cp |