[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[gawk-diffs] [SCM] gawk branch, extgawk, updated. 9cc3e7f1126d924a343f01
|
From: |
Arnold Robbins |
|
Subject: |
[gawk-diffs] [SCM] gawk branch, extgawk, updated. 9cc3e7f1126d924a343f01be6a92cf6aefe97bab |
|
Date: |
Fri, 10 Aug 2012 09:48:34 +0000 |
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "gawk".
The branch, extgawk has been updated
via 9cc3e7f1126d924a343f01be6a92cf6aefe97bab (commit)
via 35716c6aaa573dc15012fe1cba8d18b242367fd0 (commit)
from 94008850575fe9450b52aa83b77f9b08e5e55f6e (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
http://git.sv.gnu.org/cgit/gawk.git/commit/?id=9cc3e7f1126d924a343f01be6a92cf6aefe97bab
commit 9cc3e7f1126d924a343f01be6a92cf6aefe97bab
Author: Arnold D. Robbins <address@hidden>
Date: Fri Aug 10 12:48:15 2012 +0300
Discuss derived files in the git repo in the doc.
diff --git a/doc/ChangeLog b/doc/ChangeLog
index 32ef1a1..869ead2 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -2,6 +2,7 @@
* awkcard.in, gawk.1, gawk.texi: Updated. Mostly for new API stuff
but also some other things.
+ * gawk.texi (Derived Files): New node.
2012-08-01 Arnold D. Robbins <address@hidden>
diff --git a/doc/gawk.info b/doc/gawk.info
index 65bf903..bcbdb04 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -513,6 +513,8 @@ texts being (a) (see below), and with the Back-Cover Texts
being (b)
`gawk'.
* New Ports:: Porting `gawk' to a new operating
system.
+* Derived Files:: Why derived files are kept in the
+ `git' repository.
* Future Extensions:: New features that may be implemented one
day.
* Basic High Level:: The high level view.
@@ -21438,14 +21440,18 @@ the current version of `gawk'.
- The `AWKLIBPATH' environment variable for specifying a path
search for the `-l' command-line option (*note Options::).
- - The ability to use GNU-style long-named options that start
- with `--' and the `--bignum', `--characters-as-bytes',
- `--copyright', `--debug', `--dump-variables', `--exec',
- `--gen-pot', `--include', `--lint', `--lint-old', `--load',
+ - The `-b', `-c', `-C', `-d', `-D', `-e', `-E', `-g', `-h',
+ `-i', `-l', `-L', `-M', `-n', `-N', `-o', `-O', `-p', `-P',
+ `-r', `-S', `-t', and `-V' short options. Also, the ability
+ to use GNU-style long-named options that start with `--' and
+ the `--assign', `--bignum', `--characters-as-bytes',
+ `--copyright', `--debug', `--dump-variables', `--execle',
+ `--field-separator', `--file', `--gen-pot', `--help',
+ `--include', `--lint', `--lint-old', `--load',
`--non-decimal-data', `--optimize', `--posix',
`--pretty-print', `--profile', `--re-interval', `--sandbox',
- `--source', `--traditional', and `--use-lc-numeric' options
- (*note Options::).
+ `--source', `--traditional', `--use-lc-numeric', and
+ `--version' long options (*note Options::).
* Support for the following obsolete systems was removed from the
code and the documentation for `gawk' version 4.0:
@@ -22836,6 +22842,8 @@ as well as any considerations you should bear in mind.
`gawk'.
* New Ports:: Porting `gawk' to a new operating
system.
+* Derived Files:: Why derived files are kept in the
+ `git' repository.
File: gawk.info, Node: Accessing The Source, Next: Adding Code, Up:
Additions
@@ -23005,7 +23013,7 @@ isn't possible for me to do that with a minimum of
extra work, then I
probably will not.
-File: gawk.info, Node: New Ports, Prev: Adding Code, Up: Additions
+File: gawk.info, Node: New Ports, Next: Derived Files, Prev: Adding Code,
Up: Additions
C.2.3 Porting `gawk' to a New Operating System
----------------------------------------------
@@ -23087,6 +23095,149 @@ code that is already there.
style and brace layout that suits your taste.
+File: gawk.info, Node: Derived Files, Prev: New Ports, Up: Additions
+
+C.2.4 Why Generated Files Are Kept In `git'
+-------------------------------------------
+
+If you look at the `gawk' source in the `git' repository, you will
+notice that it includes files that are automatically generated by GNU
+infrastructure tools, such as `Makefile.in' from `automake' and even
+`configure' from `autoconf'.
+
+ This is different from many Free Software projects that do not store
+the derived files, because that keeps the repository less cluttered,
+and it is easier to see the substantive changes when comparing versions
+and trying to understand what changed between commits.
+
+ However, there are two reasons why the `gawk' maintainer likes to
+have everything in the repository.
+
+ First, because it is then easy to reproduce any given version
+completely, without relying upon the availability of (older, likely
+obsolete, and maybe even impossible to find) other tools.
+
+ As an extreme example, if you ever even think about trying to
+compile, oh, say, the V7 `awk', you will discover that not only do you
+have to bootstrap the V7 `yacc' to do so, but you also need the V7
+`lex'. And the latter is pretty much impossible to bring up on a
+modern GNU/Linux system.(1)
+
+ (Or, let's say `gawk' 1.2 required `bison' whatever-it-was in 1989
+and that there was no `awkgram.c' file in the repository. Is there a
+guarantee that we could find that `bison' version? Or that _it_ would
+build?)
+
+ If the repository has all the generated files, then it's easy to
+just check them out and build. (Or _easier_, depending upon how far
+back we go. `:-)')
+
+ And that brings us to the second (and stronger) reason why all the
+files really need to be in `git'. It boils down to who do you cater
+to--the `gawk' developer(s), or the user who just wants to check out a
+version and try it out?
+
+ The `gawk' maintainer wants it to be possible for any interested
+`awk' user in the world to just clone the repository, check out the
+branch of interest and build it. Without their having to have the
+correct version(s) of the autotools.(2) That is the point of the
+`bootstrap.sh' file. It touches the various other files in the right
+order such that
+
+ # The canonical incantation for building GNU software:
+ ./bootstrap.sh && ./configure && make
+
+will _just work_.
+
+ This is extremely important for the `master' and `gawk-X.Y-stable'
+branches.
+
+ Further, the `gawk' maintainer would argue that it's also important
+for the `gawk' developers. When he tried to check out the `xgawk'
+branch(3) to build it, he couldn't. (No `ltmain.sh' file, and he had no
+idea how to create it, and that was not the only problem.)
+
+ He felt _extremely_ frustrated. With respect to that branch, the
+maintainer is no different than Jane User who wants to try to build
+`gawk-4.0-stable' or `master' from the repository.
+
+ Thus, the maintainer thinks that it's not just important, but
+critical, that for any given branch, the above incantation _just works_.
+
+ What are some of the consequences and/or actions to take?
+
+ 1. We don't mind that there are differing files in the different
+ branches as a result of different versions of the autotools.
+
+ A. It's the maintainer's job to merge them and he will deal with
+ it.
+
+ B. He is really good at `git diff x y > /tmp/diff1 ; gvim
+ /tmp/diff1' to remove the diffs that aren't of interest in
+ order to review code. `:-)'
+
+ 2. It would certainly help if everyone used the same versions of the
+ GNU tools as he does, which in general are the latest released
+ versions of `automake', `autoconf', `bison', and `gettext'.
+
+ A. Installing from source is quite easy. It's how the maintainer
+ worked for years under Fedora. He had `/usr/local/bin' at
+ the front of hs `PATH' and just did:
+
+ wget http://ftp.gnu.org/gnu/PACKAGE/PACKAGE-X.Y.Z.tar.gz
+ tar -xpzvf PACKAGE-X.Y.Z.tar.gz
+ cd PACKAGE-X.Y.Z
+ ./configure && make && make check
+ make install # as root
+
+ B. These days the maintainer uses Ubuntu 10.11 which is medium
+ current, but he is already doing the above for `autoconf' and
+ `bison'.
+
+
+
+ Most of the above was originally written by the maintainer to other
+`gawk' developers. It raised the objection from one of the devlopers
+"... that anybody pulling down the source from `git' is not an end
+user."
+
+ However, this is not true. There are "power `awk' users" who can
+build `gawk' (using the magic incantation shown previously) but who
+can't program in C. Thus, the major branches should be kept buildable
+all the time.
+
+ It was then suggested that there be a `cron' job to create nightly
+tarballs of "the source." Here, the problem is that there are source
+trees, corresponding to the various branches! So, nightly tar balls
+aren't the answer, especially as the repository can go for weeks
+without significant change being introduced.
+
+ Fortunately, the `git' server can meet this need. For any given
+branch named BRANCHNAME, use:
+
+ wget
http://git.savannah.gnu.org/cgit/gawk.git/snapshot/gawk-BRANCHNAME.tar.gz
+
+to retrieve a snapshot of the given branch.
+
+ ---------- Footnotes ----------
+
+ (1) We tried. It was painful.
+
+ (2) There is one GNU program that is (in our opinion) severely
+difficult to bootstrap from the `git' repository. For example, on the
+author's old (but still working) PowerPC macintosh with Mac OS X 10.5,
+it was necessary to bootstrap a ton of software, starting with `git'
+itself, in order to try to work with the latest code. It's not
+pleasant, and especially on older systems, it's a big waste of time.
+
+ Starting with the latest tarball was no picnic either. The
+maintainers had dropped `.gz' and `.bz2' files and only distribute
+`.tar.xz' files. It was necessary to bootstrap `xz' first!
+
+ (3) A branch created by one of the other developers that did not
+include the generated files.
+
+
File: gawk.info, Node: Future Extensions, Prev: Additions, Up: Notes
C.3 Probable Future Extensions
@@ -28140,440 +28291,444 @@ Index
Tag Table:
Node: Top1352
-Node: Foreword31579
-Node: Preface35924
-Ref: Preface-Footnote-138977
-Ref: Preface-Footnote-239083
-Node: History39315
-Node: Names41706
-Ref: Names-Footnote-143183
-Node: This Manual43255
-Ref: This Manual-Footnote-148159
-Node: Conventions48259
-Node: Manual History50393
-Ref: Manual History-Footnote-153663
-Ref: Manual History-Footnote-253704
-Node: How To Contribute53778
-Node: Acknowledgments54922
-Node: Getting Started59418
-Node: Running gawk61797
-Node: One-shot62983
-Node: Read Terminal64208
-Ref: Read Terminal-Footnote-165858
-Ref: Read Terminal-Footnote-266134
-Node: Long66305
-Node: Executable Scripts67681
-Ref: Executable Scripts-Footnote-169550
-Ref: Executable Scripts-Footnote-269652
-Node: Comments70199
-Node: Quoting72666
-Node: DOS Quoting77289
-Node: Sample Data Files77964
-Node: Very Simple80996
-Node: Two Rules85595
-Node: More Complex87742
-Ref: More Complex-Footnote-190672
-Node: Statements/Lines90757
-Ref: Statements/Lines-Footnote-195219
-Node: Other Features95484
-Node: When96412
-Node: Invoking Gawk98559
-Node: Command Line100020
-Node: Options100803
-Ref: Options-Footnote-1116201
-Node: Other Arguments116226
-Node: Naming Standard Input118884
-Node: Environment Variables119978
-Node: AWKPATH Variable120536
-Ref: AWKPATH Variable-Footnote-1123294
-Node: AWKLIBPATH Variable123554
-Node: Other Environment Variables124151
-Node: Exit Status126646
-Node: Include Files127321
-Node: Loading Shared Libraries130890
-Node: Obsolete132115
-Node: Undocumented132812
-Node: Regexp133055
-Node: Regexp Usage134444
-Node: Escape Sequences136470
-Node: Regexp Operators142233
-Ref: Regexp Operators-Footnote-1149613
-Ref: Regexp Operators-Footnote-2149760
-Node: Bracket Expressions149858
-Ref: table-char-classes151748
-Node: GNU Regexp Operators154271
-Node: Case-sensitivity157994
-Ref: Case-sensitivity-Footnote-1160962
-Ref: Case-sensitivity-Footnote-2161197
-Node: Leftmost Longest161305
-Node: Computed Regexps162506
-Node: Reading Files165916
-Node: Records167919
-Ref: Records-Footnote-1176593
-Node: Fields176630
-Ref: Fields-Footnote-1179663
-Node: Nonconstant Fields179749
-Node: Changing Fields181951
-Node: Field Separators187932
-Node: Default Field Splitting190561
-Node: Regexp Field Splitting191678
-Node: Single Character Fields195020
-Node: Command Line Field Separator196079
-Node: Field Splitting Summary199520
-Ref: Field Splitting Summary-Footnote-1202712
-Node: Constant Size202813
-Node: Splitting By Content207397
-Ref: Splitting By Content-Footnote-1211123
-Node: Multiple Line211163
-Ref: Multiple Line-Footnote-1217010
-Node: Getline217189
-Node: Plain Getline219405
-Node: Getline/Variable221494
-Node: Getline/File222635
-Node: Getline/Variable/File223957
-Ref: Getline/Variable/File-Footnote-1225556
-Node: Getline/Pipe225643
-Node: Getline/Variable/Pipe228203
-Node: Getline/Coprocess229310
-Node: Getline/Variable/Coprocess230553
-Node: Getline Notes231267
-Node: Getline Summary233209
-Ref: table-getline-variants233617
-Node: Read Timeout234473
-Ref: Read Timeout-Footnote-1238218
-Node: Command line directories238275
-Node: Printing238905
-Node: Print240536
-Node: Print Examples241873
-Node: Output Separators244657
-Node: OFMT246417
-Node: Printf247775
-Node: Basic Printf248681
-Node: Control Letters250220
-Node: Format Modifiers254032
-Node: Printf Examples260041
-Node: Redirection262756
-Node: Special Files269740
-Node: Special FD270273
-Ref: Special FD-Footnote-1273898
-Node: Special Network273972
-Node: Special Caveats274822
-Node: Close Files And Pipes275618
-Ref: Close Files And Pipes-Footnote-1282641
-Ref: Close Files And Pipes-Footnote-2282789
-Node: Expressions282939
-Node: Values284071
-Node: Constants284747
-Node: Scalar Constants285427
-Ref: Scalar Constants-Footnote-1286286
-Node: Nondecimal-numbers286468
-Node: Regexp Constants289527
-Node: Using Constant Regexps290002
-Node: Variables293057
-Node: Using Variables293712
-Node: Assignment Options295436
-Node: Conversion297308
-Ref: table-locale-affects302684
-Ref: Conversion-Footnote-1303308
-Node: All Operators303417
-Node: Arithmetic Ops304047
-Node: Concatenation306552
-Ref: Concatenation-Footnote-1309345
-Node: Assignment Ops309465
-Ref: table-assign-ops314453
-Node: Increment Ops315861
-Node: Truth Values and Conditions319331
-Node: Truth Values320414
-Node: Typing and Comparison321463
-Node: Variable Typing322252
-Ref: Variable Typing-Footnote-1326149
-Node: Comparison Operators326271
-Ref: table-relational-ops326681
-Node: POSIX String Comparison330230
-Ref: POSIX String Comparison-Footnote-1331186
-Node: Boolean Ops331324
-Ref: Boolean Ops-Footnote-1335402
-Node: Conditional Exp335493
-Node: Function Calls337225
-Node: Precedence340819
-Node: Locales344488
-Node: Patterns and Actions345577
-Node: Pattern Overview346631
-Node: Regexp Patterns348300
-Node: Expression Patterns348843
-Node: Ranges352528
-Node: BEGIN/END355494
-Node: Using BEGIN/END356256
-Ref: Using BEGIN/END-Footnote-1358987
-Node: I/O And BEGIN/END359093
-Node: BEGINFILE/ENDFILE361375
-Node: Empty364279
-Node: Using Shell Variables364595
-Node: Action Overview366880
-Node: Statements369237
-Node: If Statement371091
-Node: While Statement372590
-Node: Do Statement374634
-Node: For Statement375790
-Node: Switch Statement378942
-Node: Break Statement381039
-Node: Continue Statement383029
-Node: Next Statement384822
-Node: Nextfile Statement387212
-Node: Exit Statement389757
-Node: Built-in Variables392173
-Node: User-modified393268
-Ref: User-modified-Footnote-1401623
-Node: Auto-set401685
-Ref: Auto-set-Footnote-1411593
-Node: ARGC and ARGV411798
-Node: Arrays415649
-Node: Array Basics417154
-Node: Array Intro417980
-Node: Reference to Elements422298
-Node: Assigning Elements424568
-Node: Array Example425059
-Node: Scanning an Array426791
-Node: Controlling Scanning429105
-Ref: Controlling Scanning-Footnote-1434038
-Node: Delete434354
-Ref: Delete-Footnote-1436789
-Node: Numeric Array Subscripts436846
-Node: Uninitialized Subscripts439029
-Node: Multi-dimensional440657
-Node: Multi-scanning443751
-Node: Arrays of Arrays445342
-Node: Functions449987
-Node: Built-in450809
-Node: Calling Built-in451887
-Node: Numeric Functions453875
-Ref: Numeric Functions-Footnote-1457707
-Ref: Numeric Functions-Footnote-2458064
-Ref: Numeric Functions-Footnote-3458112
-Node: String Functions458381
-Ref: String Functions-Footnote-1481878
-Ref: String Functions-Footnote-2482007
-Ref: String Functions-Footnote-3482255
-Node: Gory Details482342
-Ref: table-sub-escapes484021
-Ref: table-sub-posix-92485375
-Ref: table-sub-proposed486718
-Ref: table-posix-sub488068
-Ref: table-gensub-escapes489614
-Ref: Gory Details-Footnote-1490821
-Ref: Gory Details-Footnote-2490872
-Node: I/O Functions491023
-Ref: I/O Functions-Footnote-1497678
-Node: Time Functions497825
-Ref: Time Functions-Footnote-1508717
-Ref: Time Functions-Footnote-2508785
-Ref: Time Functions-Footnote-3508943
-Ref: Time Functions-Footnote-4509054
-Ref: Time Functions-Footnote-5509166
-Ref: Time Functions-Footnote-6509393
-Node: Bitwise Functions509659
-Ref: table-bitwise-ops510217
-Ref: Bitwise Functions-Footnote-1514438
-Node: Type Functions514622
-Node: I18N Functions515092
-Node: User-defined516719
-Node: Definition Syntax517523
-Ref: Definition Syntax-Footnote-1522433
-Node: Function Example522502
-Node: Function Caveats525096
-Node: Calling A Function525517
-Node: Variable Scope526632
-Node: Pass By Value/Reference528607
-Node: Return Statement532047
-Node: Dynamic Typing535028
-Node: Indirect Calls535763
-Node: Internationalization545448
-Node: I18N and L10N546887
-Node: Explaining gettext547573
-Ref: Explaining gettext-Footnote-1552639
-Ref: Explaining gettext-Footnote-2552823
-Node: Programmer i18n552988
-Node: Translator i18n557188
-Node: String Extraction557981
-Ref: String Extraction-Footnote-1558942
-Node: Printf Ordering559028
-Ref: Printf Ordering-Footnote-1561812
-Node: I18N Portability561876
-Ref: I18N Portability-Footnote-1564325
-Node: I18N Example564388
-Ref: I18N Example-Footnote-1567023
-Node: Gawk I18N567095
-Node: Arbitrary Precision Arithmetic567712
-Ref: Arbitrary Precision Arithmetic-Footnote-1570464
-Node: Floating-point Programming570612
-Node: Floating-point Representation575882
-Node: Floating-point Context576986
-Ref: table-ieee-formats577821
-Node: Rounding Mode579191
-Ref: table-rounding-modes579818
-Ref: Rounding Mode-Footnote-1582941
-Node: Arbitrary Precision Floats583122
-Ref: Arbitrary Precision Floats-Footnote-1585163
-Node: Setting Precision585474
-Node: Setting Rounding Mode588232
-Node: Floating-point Constants589149
-Node: Changing Precision590568
-Ref: Changing Precision-Footnote-1591968
-Node: Exact Arithmetic592141
-Node: Integer Programming595154
-Node: Arbitrary Precision Integers596934
-Ref: Arbitrary Precision Integers-Footnote-1599958
-Node: MPFR and GMP Libraries600104
-Node: Advanced Features600489
-Node: Nondecimal Data602012
-Node: Array Sorting603595
-Node: Controlling Array Traversal604292
-Node: Array Sorting Functions612529
-Ref: Array Sorting Functions-Footnote-1616203
-Ref: Array Sorting Functions-Footnote-2616296
-Node: Two-way I/O616490
-Ref: Two-way I/O-Footnote-1621922
-Node: TCP/IP Networking621992
-Node: Profiling624836
-Node: Library Functions632290
-Ref: Library Functions-Footnote-1635297
-Node: Library Names635468
-Ref: Library Names-Footnote-1638939
-Ref: Library Names-Footnote-2639159
-Node: General Functions639245
-Node: Strtonum Function640198
-Node: Assert Function643128
-Node: Round Function646454
-Node: Cliff Random Function647997
-Node: Ordinal Functions649013
-Ref: Ordinal Functions-Footnote-1652083
-Ref: Ordinal Functions-Footnote-2652335
-Node: Join Function652544
-Ref: Join Function-Footnote-1654315
-Node: Getlocaltime Function654515
-Node: Data File Management658230
-Node: Filetrans Function658862
-Node: Rewind Function663001
-Node: File Checking664388
-Node: Empty Files665482
-Node: Ignoring Assigns667712
-Node: Getopt Function669265
-Ref: Getopt Function-Footnote-1680569
-Node: Passwd Functions680772
-Ref: Passwd Functions-Footnote-1689747
-Node: Group Functions689835
-Node: Walking Arrays697919
-Node: Sample Programs699488
-Node: Running Examples700153
-Node: Clones700881
-Node: Cut Program702105
-Node: Egrep Program711950
-Ref: Egrep Program-Footnote-1719723
-Node: Id Program719833
-Node: Split Program723449
-Ref: Split Program-Footnote-1726968
-Node: Tee Program727096
-Node: Uniq Program729899
-Node: Wc Program737328
-Ref: Wc Program-Footnote-1741594
-Ref: Wc Program-Footnote-2741794
-Node: Miscellaneous Programs741886
-Node: Dupword Program743074
-Node: Alarm Program745105
-Node: Translate Program749854
-Ref: Translate Program-Footnote-1754241
-Ref: Translate Program-Footnote-2754469
-Node: Labels Program754603
-Ref: Labels Program-Footnote-1757974
-Node: Word Sorting758058
-Node: History Sorting761942
-Node: Extract Program763781
-Ref: Extract Program-Footnote-1771264
-Node: Simple Sed771392
-Node: Igawk Program774454
-Ref: Igawk Program-Footnote-1789611
-Ref: Igawk Program-Footnote-2789812
-Node: Anagram Program789950
-Node: Signature Program793018
-Node: Debugger794118
-Node: Debugging795072
-Node: Debugging Concepts795505
-Node: Debugging Terms797361
-Node: Awk Debugging799958
-Node: Sample Debugging Session800850
-Node: Debugger Invocation801370
-Node: Finding The Bug802699
-Node: List of Debugger Commands809187
-Node: Breakpoint Control810521
-Node: Debugger Execution Control814185
-Node: Viewing And Changing Data817545
-Node: Execution Stack820901
-Node: Debugger Info822368
-Node: Miscellaneous Debugger Commands826349
-Node: Readline Support831794
-Node: Limitations832625
-Node: Dynamic Extensions834877
-Node: Plugin License835773
-Node: Sample Library836387
-Node: Internal File Description837071
-Node: Internal File Ops840784
-Ref: Internal File Ops-Footnote-1845347
-Node: Using Internal File Ops845487
-Node: Language History847863
-Node: V7/SVR3.1849385
-Node: SVR4851706
-Node: POSIX853148
-Node: BTL854156
-Node: POSIX/GNU854890
-Node: Common Extensions860146
-Node: Ranges and Locales861253
-Ref: Ranges and Locales-Footnote-1865857
-Node: Contributors866078
-Node: Installation870374
-Node: Gawk Distribution871268
-Node: Getting871752
-Node: Extracting872578
-Node: Distribution contents874270
-Node: Unix Installation879492
-Node: Quick Installation880109
-Node: Additional Configuration Options882071
-Node: Configuration Philosophy883548
-Node: Non-Unix Installation885890
-Node: PC Installation886348
-Node: PC Binary Installation887647
-Node: PC Compiling889495
-Node: PC Testing892439
-Node: PC Using893615
-Node: Cygwin897800
-Node: MSYS898800
-Node: VMS Installation899314
-Node: VMS Compilation899917
-Ref: VMS Compilation-Footnote-1900924
-Node: VMS Installation Details900982
-Node: VMS Running902617
-Node: VMS Old Gawk904224
-Node: Bugs904698
-Node: Other Versions908550
-Node: Notes913865
-Node: Compatibility Mode914452
-Node: Additions915235
-Node: Accessing The Source916046
-Node: Adding Code917471
-Node: New Ports923479
-Node: Future Extensions927592
-Node: Basic Concepts929079
-Node: Basic High Level929836
-Ref: Basic High Level-Footnote-1933871
-Node: Basic Data Typing934056
-Node: Floating Point Issues938581
-Node: String Conversion Precision939664
-Ref: String Conversion Precision-Footnote-1941364
-Node: Unexpected Results941473
-Node: POSIX Floating Point Problems943299
-Ref: POSIX Floating Point Problems-Footnote-1947004
-Node: Glossary947042
-Node: Copying972018
-Node: GNU Free Documentation License1009575
-Node: Index1034712
+Node: Foreword31701
+Node: Preface36046
+Ref: Preface-Footnote-139099
+Ref: Preface-Footnote-239205
+Node: History39437
+Node: Names41828
+Ref: Names-Footnote-143305
+Node: This Manual43377
+Ref: This Manual-Footnote-148281
+Node: Conventions48381
+Node: Manual History50515
+Ref: Manual History-Footnote-153785
+Ref: Manual History-Footnote-253826
+Node: How To Contribute53900
+Node: Acknowledgments55044
+Node: Getting Started59540
+Node: Running gawk61919
+Node: One-shot63105
+Node: Read Terminal64330
+Ref: Read Terminal-Footnote-165980
+Ref: Read Terminal-Footnote-266256
+Node: Long66427
+Node: Executable Scripts67803
+Ref: Executable Scripts-Footnote-169672
+Ref: Executable Scripts-Footnote-269774
+Node: Comments70321
+Node: Quoting72788
+Node: DOS Quoting77411
+Node: Sample Data Files78086
+Node: Very Simple81118
+Node: Two Rules85717
+Node: More Complex87864
+Ref: More Complex-Footnote-190794
+Node: Statements/Lines90879
+Ref: Statements/Lines-Footnote-195341
+Node: Other Features95606
+Node: When96534
+Node: Invoking Gawk98681
+Node: Command Line100142
+Node: Options100925
+Ref: Options-Footnote-1116323
+Node: Other Arguments116348
+Node: Naming Standard Input119006
+Node: Environment Variables120100
+Node: AWKPATH Variable120658
+Ref: AWKPATH Variable-Footnote-1123416
+Node: AWKLIBPATH Variable123676
+Node: Other Environment Variables124273
+Node: Exit Status126768
+Node: Include Files127443
+Node: Loading Shared Libraries131012
+Node: Obsolete132237
+Node: Undocumented132934
+Node: Regexp133177
+Node: Regexp Usage134566
+Node: Escape Sequences136592
+Node: Regexp Operators142355
+Ref: Regexp Operators-Footnote-1149735
+Ref: Regexp Operators-Footnote-2149882
+Node: Bracket Expressions149980
+Ref: table-char-classes151870
+Node: GNU Regexp Operators154393
+Node: Case-sensitivity158116
+Ref: Case-sensitivity-Footnote-1161084
+Ref: Case-sensitivity-Footnote-2161319
+Node: Leftmost Longest161427
+Node: Computed Regexps162628
+Node: Reading Files166038
+Node: Records168041
+Ref: Records-Footnote-1176715
+Node: Fields176752
+Ref: Fields-Footnote-1179785
+Node: Nonconstant Fields179871
+Node: Changing Fields182073
+Node: Field Separators188054
+Node: Default Field Splitting190683
+Node: Regexp Field Splitting191800
+Node: Single Character Fields195142
+Node: Command Line Field Separator196201
+Node: Field Splitting Summary199642
+Ref: Field Splitting Summary-Footnote-1202834
+Node: Constant Size202935
+Node: Splitting By Content207519
+Ref: Splitting By Content-Footnote-1211245
+Node: Multiple Line211285
+Ref: Multiple Line-Footnote-1217132
+Node: Getline217311
+Node: Plain Getline219527
+Node: Getline/Variable221616
+Node: Getline/File222757
+Node: Getline/Variable/File224079
+Ref: Getline/Variable/File-Footnote-1225678
+Node: Getline/Pipe225765
+Node: Getline/Variable/Pipe228325
+Node: Getline/Coprocess229432
+Node: Getline/Variable/Coprocess230675
+Node: Getline Notes231389
+Node: Getline Summary233331
+Ref: table-getline-variants233739
+Node: Read Timeout234595
+Ref: Read Timeout-Footnote-1238340
+Node: Command line directories238397
+Node: Printing239027
+Node: Print240658
+Node: Print Examples241995
+Node: Output Separators244779
+Node: OFMT246539
+Node: Printf247897
+Node: Basic Printf248803
+Node: Control Letters250342
+Node: Format Modifiers254154
+Node: Printf Examples260163
+Node: Redirection262878
+Node: Special Files269862
+Node: Special FD270395
+Ref: Special FD-Footnote-1274020
+Node: Special Network274094
+Node: Special Caveats274944
+Node: Close Files And Pipes275740
+Ref: Close Files And Pipes-Footnote-1282763
+Ref: Close Files And Pipes-Footnote-2282911
+Node: Expressions283061
+Node: Values284193
+Node: Constants284869
+Node: Scalar Constants285549
+Ref: Scalar Constants-Footnote-1286408
+Node: Nondecimal-numbers286590
+Node: Regexp Constants289649
+Node: Using Constant Regexps290124
+Node: Variables293179
+Node: Using Variables293834
+Node: Assignment Options295558
+Node: Conversion297430
+Ref: table-locale-affects302806
+Ref: Conversion-Footnote-1303430
+Node: All Operators303539
+Node: Arithmetic Ops304169
+Node: Concatenation306674
+Ref: Concatenation-Footnote-1309467
+Node: Assignment Ops309587
+Ref: table-assign-ops314575
+Node: Increment Ops315983
+Node: Truth Values and Conditions319453
+Node: Truth Values320536
+Node: Typing and Comparison321585
+Node: Variable Typing322374
+Ref: Variable Typing-Footnote-1326271
+Node: Comparison Operators326393
+Ref: table-relational-ops326803
+Node: POSIX String Comparison330352
+Ref: POSIX String Comparison-Footnote-1331308
+Node: Boolean Ops331446
+Ref: Boolean Ops-Footnote-1335524
+Node: Conditional Exp335615
+Node: Function Calls337347
+Node: Precedence340941
+Node: Locales344610
+Node: Patterns and Actions345699
+Node: Pattern Overview346753
+Node: Regexp Patterns348422
+Node: Expression Patterns348965
+Node: Ranges352650
+Node: BEGIN/END355616
+Node: Using BEGIN/END356378
+Ref: Using BEGIN/END-Footnote-1359109
+Node: I/O And BEGIN/END359215
+Node: BEGINFILE/ENDFILE361497
+Node: Empty364401
+Node: Using Shell Variables364717
+Node: Action Overview367002
+Node: Statements369359
+Node: If Statement371213
+Node: While Statement372712
+Node: Do Statement374756
+Node: For Statement375912
+Node: Switch Statement379064
+Node: Break Statement381161
+Node: Continue Statement383151
+Node: Next Statement384944
+Node: Nextfile Statement387334
+Node: Exit Statement389879
+Node: Built-in Variables392295
+Node: User-modified393390
+Ref: User-modified-Footnote-1401745
+Node: Auto-set401807
+Ref: Auto-set-Footnote-1411715
+Node: ARGC and ARGV411920
+Node: Arrays415771
+Node: Array Basics417276
+Node: Array Intro418102
+Node: Reference to Elements422420
+Node: Assigning Elements424690
+Node: Array Example425181
+Node: Scanning an Array426913
+Node: Controlling Scanning429227
+Ref: Controlling Scanning-Footnote-1434160
+Node: Delete434476
+Ref: Delete-Footnote-1436911
+Node: Numeric Array Subscripts436968
+Node: Uninitialized Subscripts439151
+Node: Multi-dimensional440779
+Node: Multi-scanning443873
+Node: Arrays of Arrays445464
+Node: Functions450109
+Node: Built-in450931
+Node: Calling Built-in452009
+Node: Numeric Functions453997
+Ref: Numeric Functions-Footnote-1457829
+Ref: Numeric Functions-Footnote-2458186
+Ref: Numeric Functions-Footnote-3458234
+Node: String Functions458503
+Ref: String Functions-Footnote-1482000
+Ref: String Functions-Footnote-2482129
+Ref: String Functions-Footnote-3482377
+Node: Gory Details482464
+Ref: table-sub-escapes484143
+Ref: table-sub-posix-92485497
+Ref: table-sub-proposed486840
+Ref: table-posix-sub488190
+Ref: table-gensub-escapes489736
+Ref: Gory Details-Footnote-1490943
+Ref: Gory Details-Footnote-2490994
+Node: I/O Functions491145
+Ref: I/O Functions-Footnote-1497800
+Node: Time Functions497947
+Ref: Time Functions-Footnote-1508839
+Ref: Time Functions-Footnote-2508907
+Ref: Time Functions-Footnote-3509065
+Ref: Time Functions-Footnote-4509176
+Ref: Time Functions-Footnote-5509288
+Ref: Time Functions-Footnote-6509515
+Node: Bitwise Functions509781
+Ref: table-bitwise-ops510339
+Ref: Bitwise Functions-Footnote-1514560
+Node: Type Functions514744
+Node: I18N Functions515214
+Node: User-defined516841
+Node: Definition Syntax517645
+Ref: Definition Syntax-Footnote-1522555
+Node: Function Example522624
+Node: Function Caveats525218
+Node: Calling A Function525639
+Node: Variable Scope526754
+Node: Pass By Value/Reference528729
+Node: Return Statement532169
+Node: Dynamic Typing535150
+Node: Indirect Calls535885
+Node: Internationalization545570
+Node: I18N and L10N547009
+Node: Explaining gettext547695
+Ref: Explaining gettext-Footnote-1552761
+Ref: Explaining gettext-Footnote-2552945
+Node: Programmer i18n553110
+Node: Translator i18n557310
+Node: String Extraction558103
+Ref: String Extraction-Footnote-1559064
+Node: Printf Ordering559150
+Ref: Printf Ordering-Footnote-1561934
+Node: I18N Portability561998
+Ref: I18N Portability-Footnote-1564447
+Node: I18N Example564510
+Ref: I18N Example-Footnote-1567145
+Node: Gawk I18N567217
+Node: Arbitrary Precision Arithmetic567834
+Ref: Arbitrary Precision Arithmetic-Footnote-1570586
+Node: Floating-point Programming570734
+Node: Floating-point Representation576004
+Node: Floating-point Context577108
+Ref: table-ieee-formats577943
+Node: Rounding Mode579313
+Ref: table-rounding-modes579940
+Ref: Rounding Mode-Footnote-1583063
+Node: Arbitrary Precision Floats583244
+Ref: Arbitrary Precision Floats-Footnote-1585285
+Node: Setting Precision585596
+Node: Setting Rounding Mode588354
+Node: Floating-point Constants589271
+Node: Changing Precision590690
+Ref: Changing Precision-Footnote-1592090
+Node: Exact Arithmetic592263
+Node: Integer Programming595276
+Node: Arbitrary Precision Integers597056
+Ref: Arbitrary Precision Integers-Footnote-1600080
+Node: MPFR and GMP Libraries600226
+Node: Advanced Features600611
+Node: Nondecimal Data602134
+Node: Array Sorting603717
+Node: Controlling Array Traversal604414
+Node: Array Sorting Functions612651
+Ref: Array Sorting Functions-Footnote-1616325
+Ref: Array Sorting Functions-Footnote-2616418
+Node: Two-way I/O616612
+Ref: Two-way I/O-Footnote-1622044
+Node: TCP/IP Networking622114
+Node: Profiling624958
+Node: Library Functions632412
+Ref: Library Functions-Footnote-1635419
+Node: Library Names635590
+Ref: Library Names-Footnote-1639061
+Ref: Library Names-Footnote-2639281
+Node: General Functions639367
+Node: Strtonum Function640320
+Node: Assert Function643250
+Node: Round Function646576
+Node: Cliff Random Function648119
+Node: Ordinal Functions649135
+Ref: Ordinal Functions-Footnote-1652205
+Ref: Ordinal Functions-Footnote-2652457
+Node: Join Function652666
+Ref: Join Function-Footnote-1654437
+Node: Getlocaltime Function654637
+Node: Data File Management658352
+Node: Filetrans Function658984
+Node: Rewind Function663123
+Node: File Checking664510
+Node: Empty Files665604
+Node: Ignoring Assigns667834
+Node: Getopt Function669387
+Ref: Getopt Function-Footnote-1680691
+Node: Passwd Functions680894
+Ref: Passwd Functions-Footnote-1689869
+Node: Group Functions689957
+Node: Walking Arrays698041
+Node: Sample Programs699610
+Node: Running Examples700275
+Node: Clones701003
+Node: Cut Program702227
+Node: Egrep Program712072
+Ref: Egrep Program-Footnote-1719845
+Node: Id Program719955
+Node: Split Program723571
+Ref: Split Program-Footnote-1727090
+Node: Tee Program727218
+Node: Uniq Program730021
+Node: Wc Program737450
+Ref: Wc Program-Footnote-1741716
+Ref: Wc Program-Footnote-2741916
+Node: Miscellaneous Programs742008
+Node: Dupword Program743196
+Node: Alarm Program745227
+Node: Translate Program749976
+Ref: Translate Program-Footnote-1754363
+Ref: Translate Program-Footnote-2754591
+Node: Labels Program754725
+Ref: Labels Program-Footnote-1758096
+Node: Word Sorting758180
+Node: History Sorting762064
+Node: Extract Program763903
+Ref: Extract Program-Footnote-1771386
+Node: Simple Sed771514
+Node: Igawk Program774576
+Ref: Igawk Program-Footnote-1789733
+Ref: Igawk Program-Footnote-2789934
+Node: Anagram Program790072
+Node: Signature Program793140
+Node: Debugger794240
+Node: Debugging795194
+Node: Debugging Concepts795627
+Node: Debugging Terms797483
+Node: Awk Debugging800080
+Node: Sample Debugging Session800972
+Node: Debugger Invocation801492
+Node: Finding The Bug802821
+Node: List of Debugger Commands809309
+Node: Breakpoint Control810643
+Node: Debugger Execution Control814307
+Node: Viewing And Changing Data817667
+Node: Execution Stack821023
+Node: Debugger Info822490
+Node: Miscellaneous Debugger Commands826471
+Node: Readline Support831916
+Node: Limitations832747
+Node: Dynamic Extensions834999
+Node: Plugin License835895
+Node: Sample Library836509
+Node: Internal File Description837193
+Node: Internal File Ops840906
+Ref: Internal File Ops-Footnote-1845469
+Node: Using Internal File Ops845609
+Node: Language History847985
+Node: V7/SVR3.1849507
+Node: SVR4851828
+Node: POSIX853270
+Node: BTL854278
+Node: POSIX/GNU855012
+Node: Common Extensions860547
+Node: Ranges and Locales861654
+Ref: Ranges and Locales-Footnote-1866258
+Node: Contributors866479
+Node: Installation870775
+Node: Gawk Distribution871669
+Node: Getting872153
+Node: Extracting872979
+Node: Distribution contents874671
+Node: Unix Installation879893
+Node: Quick Installation880510
+Node: Additional Configuration Options882472
+Node: Configuration Philosophy883949
+Node: Non-Unix Installation886291
+Node: PC Installation886749
+Node: PC Binary Installation888048
+Node: PC Compiling889896
+Node: PC Testing892840
+Node: PC Using894016
+Node: Cygwin898201
+Node: MSYS899201
+Node: VMS Installation899715
+Node: VMS Compilation900318
+Ref: VMS Compilation-Footnote-1901325
+Node: VMS Installation Details901383
+Node: VMS Running903018
+Node: VMS Old Gawk904625
+Node: Bugs905099
+Node: Other Versions908951
+Node: Notes914266
+Node: Compatibility Mode914853
+Node: Additions915636
+Node: Accessing The Source916563
+Node: Adding Code917988
+Node: New Ports923996
+Node: Derived Files928131
+Ref: Derived Files-Footnote-1933435
+Ref: Derived Files-Footnote-2933469
+Ref: Derived Files-Footnote-3934069
+Node: Future Extensions934167
+Node: Basic Concepts935654
+Node: Basic High Level936411
+Ref: Basic High Level-Footnote-1940446
+Node: Basic Data Typing940631
+Node: Floating Point Issues945156
+Node: String Conversion Precision946239
+Ref: String Conversion Precision-Footnote-1947939
+Node: Unexpected Results948048
+Node: POSIX Floating Point Problems949874
+Ref: POSIX Floating Point Problems-Footnote-1953579
+Node: Glossary953617
+Node: Copying978593
+Node: GNU Free Documentation License1016150
+Node: Index1041287
End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index ceea9a9..4bab87e 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -712,6 +712,8 @@ particular records in a file and perform operations upon
them.
@command{gawk}.
* New Ports:: Porting @command{gawk} to a new operating
system.
+* Derived Files:: Why derived files are kept in the
+ @command{git} repository.
* Future Extensions:: New features that may be implemented one
day.
* Basic High Level:: The high level view.
@@ -28503,15 +28505,45 @@ the @option{-l} command-line option
(@pxref{Options}).
@item
-The ability to use GNU-style long-named options that start with @option{--}
+The
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
+and
address@hidden
+short options. Also, the
+ability to use GNU-style long-named options that start with @option{--}
and the
address@hidden,
@option{--bignum},
@option{--characters-as-bytes},
@option{--copyright},
@option{--debug},
@option{--dump-variables},
address@hidden,
address@hidden,
address@hidden,
address@hidden,
@option{--gen-pot},
address@hidden,
@option{--include},
@option{--lint},
@option{--lint-old},
@@ -28525,13 +28557,13 @@ and the
@option{--sandbox},
@option{--source},
@option{--traditional},
address@hidden,
and
address@hidden
-options
address@hidden
+long options
(@pxref{Options}).
@end itemize
-
@c new ports
@item
@@ -30311,6 +30343,8 @@ as well as any considerations you should bear in mind.
@command{gawk}.
* New Ports:: Porting @command{gawk} to a new operating
system.
+* Derived Files:: Why derived files are kept in the
+ @command{git} repository.
@end menu
@node Accessing The Source
@@ -30629,6 +30663,189 @@ operating systems' code that is already there.
In the code that you supply and maintain, feel free to use a
coding style and brace layout that suits your taste.
address@hidden Derived Files
address@hidden Why Generated Files Are Kept In @command{git}
+
address@hidden From emails written March 22, 2012, to the gawk developers list.
+
+If you look at the @command{gawk} source in the @command{git}
+repository, you will notice that it includes files that are automatically
+generated by GNU infrastructure tools, such as @file{Makefile.in} from
address@hidden and even @file{configure} from @command{autoconf}.
+
+This is different from many Free Software projects that do not store
+the derived files, because that keeps the repository less cluttered,
+and it is easier to see the substantive changes when comparing versions
+and trying to understand what changed between commits.
+
+However, there are two reasons why the @command{gawk} maintainer
+likes to have everything in the repository.
+
+First, because it is then easy to reproduce any given version completely,
+without relying upon the availability of (older, likely obsolete, and
+maybe even impossible to find) other tools.
+
+As an extreme example, if you ever even think about trying to compile,
+oh, say, the V7 @command{awk}, you will discover that not only do you
+have to bootstrap the V7 @command{yacc} to do so, but you also need the
+V7 @command{lex}. And the latter is pretty much impossible to bring up
+on a modern GNU/Linux address@hidden tried. It was painful.}
+
+(Or, let's say @command{gawk} 1.2 required @command{bison} whatever-it-was
+in 1989 and that there was no @file{awkgram.c} file in the repository. Is
+there a guarantee that we could find that @command{bison} version? Or that
address@hidden would build?)
+
+If the repository has all the generated files, then it's easy to just check
+them out and build. (Or @emph{easier}, depending upon how far back we go.
address@hidden:-)})
+
+And that brings us to the second (and stronger) reason why all the files
+really need to be in @command{git}. It boils down to who do you cater
+to---the @command{gawk} developer(s), or the user who just wants to check
+out a version and try it out?
+
+The @command{gawk} maintainer
+wants it to be possible for any interested @command{awk} user in the
+world to just clone the repository, check out the branch of interest and
+build it. Without their having to have the correct version(s) of the
address@hidden is one GNU program that is (in our opinion)
+severely difficult to bootstrap from the @command{git} repository. For
+example, on the author's old (but still working) PowerPC macintosh with
+Mac OS X 10.5, it was necessary to bootstrap a ton of software, starting
+with @command{git} itself, in order to try to work with the latest code.
+It's not pleasant, and especially on older systems, it's a big waste
+of time.
+
+Starting with the latest tarball was no picnic either. The maintainers
+had dropped @file{.gz} and @file{.bz2} files and only distribute
address@hidden files. It was necessary to bootstrap @command{xz} first!}
+That is the point of the @file{bootstrap.sh} file. It touches the
+various other files in the right order such that
+
address@hidden
+# The canonical incantation for building GNU software:
+./bootstrap.sh && ./configure && make
address@hidden example
+
address@hidden
+will @emph{just work}.
+
+This is extremely important for the @code{master} and
address@hidden@address@hidden branches.
+
+Further, the @command{gawk} maintainer would argue that it's also
+important for the @command{gawk} developers. When he tried to check out
+the @code{xgawk} address@hidden branch created by one of the other
+developers that did not include the generated files.} to build it, he
+couldn't. (No @file{ltmain.sh} file, and he had no idea how to create it,
+and that was not the only problem.)
+
+He felt @emph{extremely} frustrated. With respect to that branch,
+the maintainer is no different than Jane User who wants to try to build
address@hidden or @code{master} from the repository.
+
+Thus, the maintainer thinks that it's not just important, but critical,
+that for any given branch, the above incantation @emph{just works}.
+
address@hidden So - that's my reasoning and philosophy.
+
+What are some of the consequences and/or actions to take?
+
address@hidden 1
address@hidden
+We don't mind that there are differing files in the different branches
+as a result of different versions of the autotools.
+
address@hidden A
address@hidden
+It's the maintainer's job to merge them and he will deal with it.
+
address@hidden
+He is really good at @samp{git diff x y > /tmp/diff1 ; gvim /tmp/diff1} to
+remove the diffs that aren't of interest in order to review code. @code{:-)}
address@hidden enumerate
+
address@hidden
+It would certainly help if everyone used the same versions of the GNU tools
+as he does, which in general are the latest released versions of
address@hidden,
address@hidden,
address@hidden,
+and
address@hidden
+
address@hidden
+If it would help if I sent out an "I just upgraded to version x.y
+of tool Z" kind of message to this list, I can do that. Up until
+now it hasn't been a real issue since I'm the only one who's been
+dorking with the configuration machinery.
address@hidden ignore
+
address@hidden A
address@hidden
+Installing from source is quite easy. It's how the maintainer worked for years
+under Fedora.
+He had @file{/usr/local/bin} at the front of hs @env{PATH} and just did:
+
address@hidden
+wget http://ftp.gnu.org/gnu/@var{package}/@address@hidden@address@hidden
+tar -xpzvf @address@hidden@address@hidden
+cd @address@hidden@address@hidden
+./configure && make && make check
+make install # as root
address@hidden example
+
address@hidden
+These days the maintainer uses Ubuntu 10.11 which is medium current, but
+he is already doing the above for @command{autoconf} and @command{bison}.
+
address@hidden
+(C. Rant: Recent Linux versions with GNOME 3 really suck. What
+ are all those people thinking? Fedora 15 was such a bust it drove
+ me to Ubuntu, but Ubuntu 11.04 and 11.10 are totally unusable from
+ a UI perspective. Bleah.)
address@hidden ignore
address@hidden enumerate
+
address@hidden
address@hidden
+If someone still feels really strongly about all this, then perhaps they
+can have two branches, one for their development with just the clean
+changes, and one that is buildable (xgawk and xgawk-buildable, maybe).
+Or, as I suggested in another mail, make commits in pairs, the first with
+the "real" changes and the second with "everything else needed for
+ building".
address@hidden ignore
address@hidden enumerate
+
+Most of the above was originally written by the maintainer to other
address@hidden developers. It raised the objection from one of
+the devlopers address@hidden that anybody pulling down the source from
address@hidden is not an end user.''
+
+However, this is not true. There are ``power @command{awk} users''
+who can build @command{gawk} (using the magic incantation shown previously)
+but who can't program in C. Thus, the major branches should be
+kept buildable all the time.
+
+It was then suggested that there be a @command{cron} job to create
+nightly tarballs of ``the source.'' Here, the problem is that there
+are source trees, corresponding to the various branches! So,
+nightly tar balls aren't the answer, especially as the repository can go
+for weeks without significant change being introduced.
+
+Fortunately, the @command{git} server can meet this need. For any given
+branch named @var{branchname}, use:
+
address@hidden
+wget http://git.savannah.gnu.org/cgit/gawk.git/snapshot/address@hidden
address@hidden example
+
address@hidden
+to retrieve a snapshot of the given branch.
+
+
@node Future Extensions
@appendixsec Probable Future Extensions
@ignore
http://git.sv.gnu.org/cgit/gawk.git/commit/?id=35716c6aaa573dc15012fe1cba8d18b242367fd0
commit 35716c6aaa573dc15012fe1cba8d18b242367fd0
Author: Arnold D. Robbins <address@hidden>
Date: Fri Aug 10 11:53:37 2012 +0300
Doc updates. Mostly about the API.
diff --git a/ChangeLog b/ChangeLog
index ca35faf..8601188 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2012-08-10 Arnold D. Robbins <address@hidden>
+
+ * FUTURES, TODO.xgawk: Updates.
+
2012-08-08 Arnold D. Robbins <address@hidden>
* configure.ac: Add -DNDEBUG to remove asserts if not developing.
diff --git a/FUTURES b/FUTURES
index 62225b1..8e927aa 100644
--- a/FUTURES
+++ b/FUTURES
@@ -13,17 +13,17 @@ For 4.1
=======
DONE: Merge gawk/pgawk/dgawk into one executable
- Consider removing use of and/or need for the protos.h file.
-
- Consider moving var_value info into Node_var itself
- to reduce memory usage.
-
DONE: Merge xmlgawk -l feature
- Merge xmlgawk XML extensions
+ DONE: Merge xmlgawk XML extensions (via source forge project that
+ works with new API)
DONE: Integrate MPFR to provide high precision arithmetic.
+ DONE: Implement designed API for loadable modules
+
+ DONE: Redo the loadable modules interface from the awk level.
+
Continue code reviews / code cleanup
Consider making gawk output +nan for NaN values so that it
@@ -31,16 +31,16 @@ For 4.1
For 4.2
=======
- Implement designed API for loadable modules
- Redo the loadable modules interface from the awk level.
+ Consider removing use of and/or need for the protos.h file.
+
+ Consider moving var_value info into Node_var itself
+ to reduce memory usage.
Rework management of array index storage. (Partially DONE.)
DBM storage of awk arrays. Try to allow multiple dbm packages.
- ? Move the loadable modules interface to libtool.
-
? Add an optional base to strtonum, allowing 2-36.
? Optional third argument for index indicating where to start the
diff --git a/TODO.xgawk b/TODO.xgawk
index d11fad6..e091351 100644
--- a/TODO.xgawk
+++ b/TODO.xgawk
@@ -3,11 +3,6 @@ To-do list for xgawk enhancements:
- Attempting to load the same file with -f and -i (or @include) should
be a fatal error.
-- Review open hook implementation.
- * Mostly done.
- * Still to go: Rework iop_alloc, interaction with open hooks, and
- skipping command line directories.
-
Low priority:
- Enhance extension/fork.c waitpid to allow the caller to specify the options.
@@ -140,3 +135,9 @@ Done:
- MPFR. This is probably not useful now that MPFR support has been
integrated into gawk. Are there any users who need this extension?
+
+- Review open hook implementation.
+ * Mostly done.
+ * Still to go: Rework iop_alloc, interaction with open hooks, and
+ skipping command line directories.
+
diff --git a/doc/ChangeLog b/doc/ChangeLog
index 65907bc..32ef1a1 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,8 @@
+2012-08-10 Arnold D. Robbins <address@hidden>
+
+ * awkcard.in, gawk.1, gawk.texi: Updated. Mostly for new API stuff
+ but also some other things.
+
2012-08-01 Arnold D. Robbins <address@hidden>
* Makefile.am (install-data-hook): Install a dgawk.1 link to the
diff --git a/doc/awkcard.in b/doc/awkcard.in
index d0c1578..9615b58 100644
--- a/doc/awkcard.in
+++ b/doc/awkcard.in
@@ -271,6 +271,8 @@ for localization.
.TI "\*(FC\-h\*(FR, \*(FC\-\^\-help\*(FR
Print a short summary of the available
options on \*(FCstdout\*(FR, then exit zero.
+.TI "\*(FC\-i \*(FIfile\*(FR, \*(FC\-\^\-include \*(FIfile\*(FR
+Include library AWK code in \*(FIfile\*(FR.
.TI "\*(FC\-l \*(FIlib\*(FR, \*(FC\-\^\-load \*(FIlib\*(FR
Load dynamic extension \*(FIlib\fP.
.TI "\*(FC\-L \*(FR[\*(FC\*(FIvalue\*(FR],
\*(FC\-\^\-lint\*(FR[\*(FC=\*(FIvalue\*(FR]
@@ -300,13 +302,7 @@ Send profiling data to \*(FIfile\*(FR
The profile contains execution counts in the left margin
of each statement in the program.
.TI "\*(FC\-P\*(FR, \*(FC\-\^\-posix\*(FR
-Disable common and GNU extensions.
-.TI "\*(FC\-r\*(FR, \*(FC\-\^\-re\-interval\*(FR
-Enable \*(FIinterval expressions\*(FR.\*(CB
-... in regular
-... expression matching (see \fHRegular
-... Expressions\fP below). Useful if
-... \*(FC\-\^\-traditional\*(FR is specified
+Disable common and GNU extensions.\*(CB
.in -4n
.EB "\s+2\f(HBCOMMAND LINE ARGUMENTS (\*(GK\f(HB)\*(FR\s0"
@@ -318,6 +314,12 @@ Enable \*(FIinterval expressions\*(FR.\*(CB
.ES
.fi
.in +4n
+.TI "\*(FC\-r\*(FR, \*(FC\-\^\-re\-interval\*(FR
+Enable \*(FIinterval expressions\*(FR.
+... in regular
+... expression matching (see \fHRegular
+... Expressions\fP below). Useful if
+... \*(FC\-\^\-traditional\*(FR is specified
.TI "\*(FC\-S\*(FR, \*(FC\-\^\-sandbox\*(FR
Disable the \*(FCsystem()\*(FR function,
input redirection with \*(FCgetline\*(FR,
@@ -342,7 +344,7 @@ options are passed on to the AWK program in
\*(FCARGV\*(FR
for processing.\*(CB
.EB "\s+2\f(HBCOMMAND LINE ARGUMENTS (\*(GK\f(HB)\*(FR\s0"
-
+.sp .4
.\"
.\"
.\" --- Command Line Arguments (mawk)
@@ -454,7 +456,7 @@ The program text is read as if all the
\*(FIprog-file\*(FR(s)
\*(CBand command line
source texts\*(CD had been concatenated.
.sp
-\*(GK includes files named on \*(address@hidden(FR lines.
+\*(CB\*(GK includes files named on \*(address@hidden(FR lines.
Nested includes are allowed.\*(CD
.sp .5
AWK programs execute in the following order.
@@ -1141,7 +1143,10 @@ The default path is
If a file name given to the \*(FC\-f\fP option contains a ``/'' character,
no path search is performed.
.sp .5
-.PP
+The variable \*(FCAWKLIBPATH\fP
+specifies the search path for dynamic extensions to use
+with \*(address@hidden and the \*(FC\-l\fP option.
+.sp .5
For socket communication,
\*(FCGAWK_SOCK_RETRIES\fP
controls the number of retries, and
@@ -1151,6 +1156,10 @@ The interval is in milliseconds. On systems that do not
support
\*(FIusleep\fP(3),
the value is rounded up to an integral number of seconds.
.sp .5
+The value of \*(FCGAWK_READ_TIMEOUT\fP specifies the time, in milliseconds,
+for \*(GK to
+wait for input before returning with an error.
+.sp .5
If \*(FCPOSIXLY_CORRECT\fP exists
.\" in the environment,
then \*(GK
@@ -1845,16 +1854,15 @@ Return the bitwise XOR of the arguments.\*(CB
.fi
.in +.2i
.ti -.2i
-\*(CD\*(FCextension(\*(FIlib\*(FC, \*(FIfunc\*(FC)\*(FR
+\*(CD\*(address@hidden "\*(FIextension\*(FC"\*(FR
.br
-Dynamically load the shared library
-\*(FIlib\*(FR
-and call
-\*(FIfunc\*(FR
-in it to initialize the library.
+Dynamically load the named \*(FIextension\*(FR.
This adds new built-in functions to \*(GK.
-It returns the value returned by
-\*(FIfunc\*(FR.\*(CB
+.\" The extension should use the API defined by the
+.\" \*(FCgawkapi.h\*(FR header file, as documented in
+.\" the full manual.
+The extension is loaded during the parsing of the program.
+See the manual for details.\*(CB
.in -.2i
.EB "\s+2\f(HBDYNAMIC EXTENSIONS (\*(GK\f(HB)\*(FR\s0"
.BT
@@ -1955,7 +1963,7 @@ maintains it.\*(CX
.ES
.fi
\*(CDCopyright \(co 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005,
-2007, 2009, 2010, 2011 Free Software Foundation, Inc.
+2007, 2009, 2010, 2011, 2012 Free Software Foundation, Inc.
.sp .5
Permission is granted to make and distribute verbatim copies of this
reference card provided the copyright notice and this permission notice
diff --git a/doc/gawk.1 b/doc/gawk.1
index c0a0a41..494ab16 100644
--- a/doc/gawk.1
+++ b/doc/gawk.1
@@ -14,7 +14,7 @@
. if \w'\(rq' .ds rq "\(rq
. \}
.\}
-.TH GAWK 1 "Nov 10 2011" "Free Software Foundation" "Utility Commands"
+.TH GAWK 1 "Aug 09 2012" "Free Software Foundation" "Utility Commands"
.SH NAME
gawk \- pattern scanning and processing language
.SH SYNOPSIS
@@ -3181,24 +3181,11 @@ may be used in place of
.SH DYNAMICALLY LOADING NEW FUNCTIONS
You can dynamically add new built-in functions to the running
.I gawk
-interpreter.
+interpreter with the
+.B @load
+statement.
The full details are beyond the scope of this manual page;
-see \*(EP for the details.
-.PP
-.TP 8
-\fBextension(\fIobject\fB, \fIfunction\fB)\fR
-Dynamically link the shared object file named by
-.IR object ,
-and invoke
-.I function
-in that object, to perform initialization.
-These should both be provided as strings.
-Return the value returned by
-.IR function .
-.PP
-Using this feature at the C level is not pretty, but
-it is unlikely to go away. Additional mechanisms may
-be added at some point.
+see \*(EP.
.SH SIGNALS
The
.I gawk
@@ -3727,7 +3714,7 @@ status is 2. On non-POSIX systems, this value may be
mapped to
.SH VERSION INFORMATION
This man page documents
.IR gawk ,
-version 4.0.
+version 4.1.
.SH AUTHORS
The original version of \*(UX
.I awk
@@ -3805,6 +3792,7 @@ While the
developers occasionally read this newsgroup, posting bug reports there
is an unreliable way to report bugs. Instead, please use the electronic mail
addresses given above.
+Really.
.PP
If you're using a GNU/Linux or BSD-based system,
you may wish to submit a bug report to the vendor of your distribution.
@@ -3824,6 +3812,7 @@ are surprisingly difficult to diagnose in the completely
general case,
and the effort to do so really is not worth it.
.SH SEE ALSO
.IR egrep (1),
+.IR sed (1),
.IR getpid (2),
.IR getppid (2),
.IR getpgrp (2),
@@ -3839,7 +3828,7 @@ Alfred V. Aho, Brian W. Kernighan, Peter J. Weinberger,
Addison-Wesley, 1988. ISBN 0-201-07981-X.
.PP
\*(EP,
-Edition 4.0, shipped with the
+Edition 4.1, shipped with the
.I gawk
source.
The current version of this document is available online at
diff --git a/doc/gawk.info b/doc/gawk.info
index bcc773d..65bf903 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -97,12 +97,14 @@ texts being (a) (see below), and with the Back-Cover Texts
being (b)
* Sample Programs:: Many `awk' programs with complete
explanations.
* Debugger:: The `gawk' debugger.
+* Dynamic Extensions:: Adding new built-in functions to
+ `gawk'.
* Language History:: The evolution of the `awk'
language.
* Installation:: Installing `gawk' under various
operating systems.
-* Notes:: Notes about `gawk' extensions and
- possible future work.
+* Notes:: Notes about adding things to `gawk'
+ and possible future work.
* Basic Concepts:: A very quick introduction to programming
concepts.
* Glossary:: An explanation of some unfamiliar terms.
@@ -359,21 +361,22 @@ texts being (a) (see below), and with the Back-Cover
Texts being (b)
* I18N Portability:: `awk'-level portability issues.
* I18N Example:: A simple i18n example.
* Gawk I18N:: `gawk' is also internationalized.
-* Floating-point Programming:: Effective floating-point programming.
-* Floating-point Representation:: Binary floating-point representation.
-* Floating-point Context:: Floating-point context.
-* Rounding Mode:: Floating-point rounding mode.
-* Arbitrary Precision Floats:: Arbitrary precision floating-point
- arithmetic with `gawk'.
-* Setting Precision:: Setting the working precision.
-* Setting Rounding Mode:: Setting the rounding mode.
-* Floating-point Constants:: Representing floating-point constants.
-* Changing Precision:: Changing the precision of a number.
-* Exact Arithmetic:: Exact arithmetic with floating-point
numbers.
-* Integer Programming:: Effective integer programming.
-* Arbitrary Precision Integers:: Arbitrary precision integer
- arithmetic with `gawk'.
-* MPFR and GMP Libraries:: Information about the MPFR and GMP
libraries.
+* Floating-point Programming:: Effective Floating-point Programming.
+* Floating-point Representation:: Binary Floating-point Representation.
+* Floating-point Context:: Floating-point Context.
+* Rounding Mode:: Floating-point Rounding Mode.
+* Arbitrary Precision Floats:: Arbitrary Precision Floating-point
+ Arithmetic with `gawk'.
+* Setting Precision:: Setting the Working Precision.
+* Setting Rounding Mode:: Setting the Rounding Mode.
+* Floating-point Constants:: Representing Floating-point Constants.
+* Changing Precision:: Changing the Precision of a Number.
+* Exact Arithmetic:: Exact Arithmetic with Floating-point
+ Numbers.
+* Integer Programming:: Effective Integer Programming.
+* Arbitrary Precision Integers:: Arbitrary Precision Integer Arithmetic with
+ `gawk'.
+* MPFR and GMP Libraries ::
* Nondecimal Data:: Allowing nondecimal input data.
* Array Sorting:: Facilities for controlling array traversal
and sorting arrays.
@@ -438,14 +441,14 @@ texts being (a) (see below), and with the Back-Cover
Texts being (b)
* Anagram Program:: Finding anagrams from a dictionary.
* Signature Program:: People do amazing things with too much time
on their hands.
-* Debugging:: Introduction to `gawk' Debugger.
+* Debugging:: Introduction to `gawk' debugger.
* Debugging Concepts:: Debugging in General.
* Debugging Terms:: Additional Debugging Concepts.
* Awk Debugging:: Awk Debugging.
-* Sample Debugging Session:: Sample Debugging Session.
+* Sample Debugging Session:: Sample debugging session.
* Debugger Invocation:: How to Start the Debugger.
* Finding The Bug:: Finding the Bug.
-* List of Debugger Commands:: Main Commands.
+* List of Debugger Commands:: Main debugger commands.
* Breakpoint Control:: Control of Breakpoints.
* Debugger Execution Control:: Control of Execution.
* Viewing And Changing Data:: Viewing and Changing Data.
@@ -453,8 +456,13 @@ texts being (a) (see below), and with the Back-Cover Texts
being (b)
* Debugger Info:: Obtaining Information about the Program and
the Debugger State.
* Miscellaneous Debugger Commands:: Miscellaneous Commands.
-* Readline Support:: Readline Support.
-* Limitations:: Limitations and Future Plans.
+* Readline Support:: Readline support.
+* Limitations:: Limitations and future plans.
+* Plugin License:: A note about licensing.
+* Sample Library:: A example of new functions.
+* Internal File Description:: What the new functions will do.
+* Internal File Ops:: The code for internal file operations.
+* Using Internal File Ops:: How to use an external extension.
* V7/SVR3.1:: The major changes between V7 and System V
Release 3.1.
* SVR4:: Minor changes between System V Releases 3.1
@@ -505,16 +513,6 @@ texts being (a) (see below), and with the Back-Cover Texts
being (b)
`gawk'.
* New Ports:: Porting `gawk' to a new operating
system.
-* Dynamic Extensions:: Adding new built-in functions to
- `gawk'.
-* Internals:: A brief look at some `gawk'
- internals.
-* Plugin License:: A note about licensing.
-* Loading Extensions:: How to load dynamic extensions.
-* Sample Library:: A example of new functions.
-* Internal File Description:: What the new functions will do.
-* Internal File Ops:: The code for internal file operations.
-* Using Internal File Ops:: How to use an external extension.
* Future Extensions:: New features that may be implemented one
day.
* Basic High Level:: The high level view.
@@ -883,8 +881,8 @@ non-POSIX systems. It also describes how to report bugs in
`gawk' and
where to get other freely available `awk' implementations.
*note Notes::, describes how to disable `gawk''s extensions, as well
-as how to contribute new code to `gawk', how to write extension
-libraries, and some possible future directions for `gawk' development.
+as how to contribute new code to `gawk', and some possible future
+directions for `gawk' development.
*note Basic Concepts::, provides some very cursory background
material for those who are completely unfamiliar with computer
@@ -2594,8 +2592,8 @@ A number of environment variables influence how `gawk'
behaves.
* AWKPATH Variable:: Searching directories for `awk'
programs.
-* AWKLIBPATH Variable:: Searching directories for `awk'
- shared libraries.
+* AWKLIBPATH Variable:: Searching directories for `awk' shared
+ libraries.
* Other Environment Variables:: The environment variables.
@@ -3737,7 +3735,6 @@ have to be named on the `awk' command line (*note
Getline::).
* Getline:: Reading files under explicit program control
using the `getline' function.
* Read Timeout:: Reading input with a timeout.
-
* Command line directories:: What happens if you put a directory on the
command line.
@@ -8520,10 +8517,10 @@ would otherwise be difficult or impossible to perform:
entirely. Otherwise, `gawk' exits with the usual fatal error.
* If you have written extensions that modify the record handling (by
- inserting an "open hook"), you can invoke them at this point,
+ inserting an "input parser"), you can invoke them at this point,
before `gawk' has started processing the file. (This is a _very_
- advanced feature, currently used only by the XMLgawk project
- (http://xmlgawk.sourceforge.net).)
+ advanced feature, currently used only by the `gawkextlib' project
+ (http://gawkextlib.sourceforge.net).)
The `ENDFILE' rule is called when `gawk' has finished processing the
last record in an input file. For the last input file, it will be
@@ -13771,21 +13768,22 @@ numbers.
* Menu:
-* Floating-point Programming:: Effective Floating-point Programming.
-* Floating-point Representation:: Binary Floating-point Representation.
-* Floating-point Context:: Floating-point Context.
-* Rounding Mode:: Floating-point Rounding Mode.
-* Arbitrary Precision Floats:: Arbitrary Precision Floating-point
- Arithmetic with `gawk'.
-* Setting Precision:: Setting the Working Precision.
-* Setting Rounding Mode:: Setting the Rounding Mode.
-* Floating-point Constants:: Representing Floating-point Constants.
-* Changing Precision:: Changing the Precision of a Number.
-* Exact Arithmetic:: Exact Arithmetic with Floating-point
Numbers.
-* Integer Programming:: Effective Integer Programming.
-* Arbitrary Precision Integers:: Arbitrary Precision Integer
- Arithmetic with `gawk'.
-* MPFR and GMP Libraries:: Information About the MPFR and GMP
Libraries.
+* Floating-point Programming:: Effective Floating-point Programming.
+* Floating-point Representation:: Binary Floating-point Representation.
+* Floating-point Context:: Floating-point Context.
+* Rounding Mode:: Floating-point Rounding Mode.
+* Arbitrary Precision Floats:: Arbitrary Precision Floating-point
+ Arithmetic with `gawk'.
+* Setting Precision:: Setting the Working Precision.
+* Setting Rounding Mode:: Setting the Rounding Mode.
+* Floating-point Constants:: Representing Floating-point Constants.
+* Changing Precision:: Changing the Precision of a Number.
+* Exact Arithmetic:: Exact Arithmetic with Floating-point
+ Numbers.
+* Integer Programming:: Effective Integer Programming.
+* Arbitrary Precision Integers:: Arbitrary Precision Integer Arithmetic with
+ `gawk'.
+* MPFR and GMP Libraries ::
---------- Footnotes ----------
@@ -19689,7 +19687,7 @@ supplies the following copyright terms:
We leave it to you to determine what the program does.
-File: gawk.info, Node: Debugger, Next: Language History, Prev: Sample
Programs, Up: Top
+File: gawk.info, Node: Debugger, Next: Dynamic Extensions, Prev: Sample
Programs, Up: Top
15 Debugging `awk' Programs
***************************
@@ -20741,2618 +20739,2357 @@ features may be added, and of course feel free to
try to add them
yourself!
-File: gawk.info, Node: Language History, Next: Installation, Prev:
Debugger, Up: Top
+File: gawk.info, Node: Dynamic Extensions, Next: Language History, Prev:
Debugger, Up: Top
-Appendix A The Evolution of the `awk' Language
-**********************************************
+16 Writing Extensions for `gawk'
+********************************
-This Info file describes the GNU implementation of `awk', which follows
-the POSIX specification. Many long-time `awk' users learned `awk'
-programming with the original `awk' implementation in Version 7 Unix.
-(This implementation was the basis for `awk' in Berkeley Unix, through
-4.3-Reno. Subsequent versions of Berkeley Unix, and some systems
-derived from 4.4BSD-Lite, use various versions of `gawk' for their
-`awk'.) This major node briefly describes the evolution of the `awk'
-language, with cross-references to other parts of the Info file where
-you can find more information.
+This chapter is a placeholder, pending a rewrite for the new API. Some
+of the old bits remain, since they can be partially reused.
+
+ It is possible to add new built-in functions to `gawk' using
+dynamically loaded libraries. This facility is available on systems
+(such as GNU/Linux) that support the C `dlopen()' and `dlsym()'
+functions. This major node describes how to write and use dynamically
+loaded extensions for `gawk'. Experience with programming in C or C++
+is necessary when reading this minor node.
+
+ NOTE: When `--sandbox' is specified, extensions are disabled
+ (*note Options::.
* Menu:
-* V7/SVR3.1:: The major changes between V7 and System V
- Release 3.1.
-* SVR4:: Minor changes between System V Releases 3.1
- and 4.
-* POSIX:: New features from the POSIX standard.
-* BTL:: New features from Brian Kernighan's version of
- `awk'.
-* POSIX/GNU:: The extensions in `gawk' not in POSIX
- `awk'.
-* Common Extensions:: Common Extensions Summary.
-* Ranges and Locales:: How locales used to affect regexp ranges.
-* Contributors:: The major contributors to `gawk'.
+* Plugin License:: A note about licensing.
+* Sample Library:: A example of new functions.
-File: gawk.info, Node: V7/SVR3.1, Next: SVR4, Up: Language History
+File: gawk.info, Node: Plugin License, Next: Sample Library, Up: Dynamic
Extensions
-A.1 Major Changes Between V7 and SVR3.1
-=======================================
+16.1 Extension Licensing
+========================
-The `awk' language evolved considerably between the release of Version
-7 Unix (1978) and the new version that was first made generally
-available in System V Release 3.1 (1987). This minor node summarizes
-the changes, with cross-references to further details:
+Every dynamic extension should define the global symbol
+`plugin_is_GPL_compatible' to assert that it has been licensed under a
+GPL-compatible license. If this symbol does not exist, `gawk' will
+emit a fatal error and exit.
- * The requirement for `;' to separate rules on a line (*note
- Statements/Lines::).
+ The declared type of the symbol should be `int'. It does not need
+to be in any allocated section, though. The code merely asserts that
+the symbol exists in the global scope. Something like this is enough:
- * User-defined functions and the `return' statement (*note
- User-defined::).
+ int plugin_is_GPL_compatible;
- * The `delete' statement (*note Delete::).
+
+File: gawk.info, Node: Sample Library, Prev: Plugin License, Up: Dynamic
Extensions
- * The `do'-`while' statement (*note Do Statement::).
+16.2 Example: Directory and File Operation Built-ins
+====================================================
- * The built-in functions `atan2()', `cos()', `sin()', `rand()', and
- `srand()' (*note Numeric Functions::).
+Two useful functions that are not in `awk' are `chdir()' (so that an
+`awk' program can change its directory) and `stat()' (so that an `awk'
+program can gather information about a file). This minor node
+implements these functions for `gawk' in an external extension library.
- * The built-in functions `gsub()', `sub()', and `match()' (*note
- String Functions::).
+* Menu:
- * The built-in functions `close()' and `system()' (*note I/O
- Functions::).
+* Internal File Description:: What the new functions will do.
+* Internal File Ops:: The code for internal file operations.
+* Using Internal File Ops:: How to use an external extension.
- * The `ARGC', `ARGV', `FNR', `RLENGTH', `RSTART', and `SUBSEP'
- built-in variables (*note Built-in Variables::).
+
+File: gawk.info, Node: Internal File Description, Next: Internal File Ops,
Up: Sample Library
- * Assignable `$0' (*note Changing Fields::).
+16.2.1 Using `chdir()' and `stat()'
+-----------------------------------
- * The conditional expression using the ternary operator `?:' (*note
- Conditional Exp::).
+This minor node shows how to use the new functions at the `awk' level
+once they've been integrated into the running `gawk' interpreter.
+Using `chdir()' is very straightforward. It takes one argument, the new
+directory to change to:
- * The expression `INDEX-VARIABLE in ARRAY' outside of `for'
- statements (*note Reference to Elements::).
+ ...
+ newdir = "/home/arnold/funstuff"
+ ret = chdir(newdir)
+ if (ret < 0) {
+ printf("could not change to %s: %s\n",
+ newdir, ERRNO) > "/dev/stderr"
+ exit 1
+ }
+ ...
- * The exponentiation operator `^' (*note Arithmetic Ops::) and its
- assignment operator form `^=' (*note Assignment Ops::).
+ The return value is negative if the `chdir' failed, and `ERRNO'
+(*note Built-in Variables::) is set to a string indicating the error.
- * C-compatible operator precedence, which breaks some old `awk'
- programs (*note Precedence::).
+ Using `stat()' is a bit more complicated. The C `stat()' function
+fills in a structure that has a fair amount of information. The right
+way to model this in `awk' is to fill in an associative array with the
+appropriate information:
- * Regexps as the value of `FS' (*note Field Separators::) and as the
- third argument to the `split()' function (*note String
- Functions::), rather than using only the first character of `FS'.
+ file = "/home/arnold/.profile"
+ fdata[1] = "x" # force `fdata' to be an array
+ ret = stat(file, fdata)
+ if (ret < 0) {
+ printf("could not stat %s: %s\n",
+ file, ERRNO) > "/dev/stderr"
+ exit 1
+ }
+ printf("size of %s is %d bytes\n", file, fdata["size"])
- * Dynamic regexps as operands of the `~' and `!~' operators (*note
- Regexp Usage::).
+ The `stat()' function always clears the data array, even if the
+`stat()' fails. It fills in the following elements:
- * The escape sequences `\b', `\f', and `\r' (*note Escape
- Sequences::). (Some vendors have updated their old versions of
- `awk' to recognize `\b', `\f', and `\r', but this is not something
- you can rely on.)
+`"name"'
+ The name of the file that was `stat()''ed.
- * Redirection of input for the `getline' function (*note Getline::).
+`"dev"'
+`"ino"'
+ The file's device and inode numbers, respectively.
- * Multiple `BEGIN' and `END' rules (*note BEGIN/END::).
+`"mode"'
+ The file's mode, as a numeric value. This includes both the file's
+ type and its permissions.
- * Multidimensional arrays (*note Multi-dimensional::).
+`"nlink"'
+ The number of hard links (directory entries) the file has.
-
-File: gawk.info, Node: SVR4, Next: POSIX, Prev: V7/SVR3.1, Up: Language
History
+`"uid"'
+`"gid"'
+ The numeric user and group ID numbers of the file's owner.
-A.2 Changes Between SVR3.1 and SVR4
-===================================
+`"size"'
+ The size in bytes of the file.
-The System V Release 4 (1989) version of Unix `awk' added these features
-(some of which originated in `gawk'):
+`"blocks"'
+ The number of disk blocks the file actually occupies. This may not
+ be a function of the file's size if the file has holes.
- * The `ENVIRON' array (*note Built-in Variables::).
+`"atime"'
+`"mtime"'
+`"ctime"'
+ The file's last access, modification, and inode update times,
+ respectively. These are numeric timestamps, suitable for
+ formatting with `strftime()' (*note Built-in::).
- * Multiple `-f' options on the command line (*note Options::).
+`"pmode"'
+ The file's "printable mode." This is a string representation of
+ the file's type and permissions, such as what is produced by `ls
+ -l'--for example, `"drwxr-xr-x"'.
- * The `-v' option for assigning variables before program execution
- begins (*note Options::).
+`"type"'
+ A printable string representation of the file's type. The value
+ is one of the following:
- * The `--' option for terminating command-line options.
+ `"blockdev"'
+ `"chardev"'
+ The file is a block or character device ("special file").
- * The `\a', `\v', and `\x' escape sequences (*note Escape
- Sequences::).
+ `"directory"'
+ The file is a directory.
- * A defined return value for the `srand()' built-in function (*note
- Numeric Functions::).
+ `"fifo"'
+ The file is a named-pipe (also known as a FIFO).
- * The `toupper()' and `tolower()' built-in string functions for case
- translation (*note String Functions::).
+ `"file"'
+ The file is just a regular file.
- * A cleaner specification for the `%c' format-control letter in the
- `printf' function (*note Control Letters::).
+ `"socket"'
+ The file is an `AF_UNIX' ("Unix domain") socket in the
+ filesystem.
- * The ability to dynamically pass the field width and precision
- (`"%*.*d"') in the argument list of the `printf' function (*note
- Control Letters::).
+ `"symlink"'
+ The file is a symbolic link.
- * The use of regexp constants, such as `/foo/', as expressions, where
- they are equivalent to using the matching operator, as in `$0 ~
- /foo/' (*note Using Constant Regexps::).
+ Several additional elements may be present depending upon the
+operating system and the type of the file. You can test for them in
+your `awk' program by using the `in' operator (*note Reference to
+Elements::):
- * Processing of escape sequences inside command-line variable
- assignments (*note Assignment Options::).
+`"blksize"'
+ The preferred block size for I/O to the file. This field is not
+ present on all POSIX-like systems in the C `stat' structure.
-
-File: gawk.info, Node: POSIX, Next: BTL, Prev: SVR4, Up: Language History
+`"linkval"'
+ If the file is a symbolic link, this element is the name of the
+ file the link points to (i.e., the value of the link).
-A.3 Changes Between SVR4 and POSIX `awk'
-========================================
+`"rdev"'
+`"major"'
+`"minor"'
+ If the file is a block or character device file, then these values
+ represent the numeric device number and the major and minor
+ components of that number, respectively.
-The POSIX Command Language and Utilities standard for `awk' (1992)
-introduced the following changes into the language:
+
+File: gawk.info, Node: Internal File Ops, Next: Using Internal File Ops,
Prev: Internal File Description, Up: Sample Library
- * The use of `-W' for implementation-specific options (*note
- Options::).
+16.2.2 C Code for `chdir()' and `stat()'
+----------------------------------------
- * The use of `CONVFMT' for controlling the conversion of numbers to
- strings (*note Conversion::).
+Here is the C code for these extensions. They were written for
+GNU/Linux. The code needs some more work for complete portability to
+other POSIX-compliant systems:(1)
- * The concept of a numeric string and tighter comparison rules to go
- with it (*note Typing and Comparison::).
+ #include "awk.h"
- * The use of built-in variables as function parameter names is
- forbidden (*note Definition Syntax::.
+ #include <sys/sysmacros.h>
- * More complete documentation of many of the previously undocumented
- features of the language.
-
- *Note Common Extensions::, for a list of common extensions not
-permitted by the POSIX standard.
+ int plugin_is_GPL_compatible;
- The 2008 POSIX standard can be found online at
-`http://www.opengroup.org/onlinepubs/9699919799/'.
+ /* do_chdir --- provide dynamically loaded chdir() builtin for gawk */
-
-File: gawk.info, Node: BTL, Next: POSIX/GNU, Prev: POSIX, Up: Language
History
+ static NODE *
+ do_chdir(int nargs)
+ {
+ NODE *newdir;
+ int ret = -1;
-A.4 Extensions in Brian Kernighan's `awk'
-=========================================
+ if (do_lint && nargs != 1)
+ lintwarn("chdir: called with incorrect number of arguments");
-Brian Kernighan has made his version available via his home page (*note
-Other Versions::).
+ newdir = get_scalar_argument(0, FALSE);
- This minor node describes common extensions that originally appeared
-in his version of `awk'.
+ The file includes the `"awk.h"' header file for definitions for the
+`gawk' internals. It includes `<sys/sysmacros.h>' for access to the
+`major()' and `minor'() macros.
- * The `**' and `**=' operators (*note Arithmetic Ops:: and *note
- Assignment Ops::).
+ By convention, for an `awk' function `foo', the function that
+implements it is called `do_foo'. The function should take a `int'
+argument, usually called `nargs', that represents the number of defined
+arguments for the function. The `newdir' variable represents the new
+directory to change to, retrieved with `get_scalar_argument()'. Note
+that the first argument is numbered zero.
- * The use of `func' as an abbreviation for `function' (*note
- Definition Syntax::).
+ This code actually accomplishes the `chdir()'. It first forces the
+argument to be a string and passes the string value to the `chdir()'
+system call. If the `chdir()' fails, `ERRNO' is updated.
- * The `fflush()' built-in function for flushing buffered output
- (*note I/O Functions::).
+ (void) force_string(newdir);
+ ret = chdir(newdir->stptr);
+ if (ret < 0)
+ update_ERRNO_int(errno);
+ Finally, the function returns the return value to the `awk' level:
- *Note Common Extensions::, for a full list of the extensions
-available in his `awk'.
+ return make_number((AWKNUM) ret);
+ }
-
-File: gawk.info, Node: POSIX/GNU, Next: Common Extensions, Prev: BTL, Up:
Language History
+ The `stat()' built-in is more involved. First comes a function that
+turns a numeric mode into a printable representation (e.g., 644 becomes
+`-rw-r--r--'). This is omitted here for brevity:
-A.5 Extensions in `gawk' Not in POSIX `awk'
-===========================================
+ /* format_mode --- turn a stat mode field into something readable */
-The GNU implementation, `gawk', adds a large number of features. They
-can all be disabled with either the `--traditional' or `--posix' options
-(*note Options::).
+ static char *
+ format_mode(unsigned long fmode)
+ {
+ ...
+ }
- A number of features have come and gone over the years. This minor
-node summarizes the additional features over POSIX `awk' that are in
-the current version of `gawk'.
+ Next comes the `do_stat()' function. It starts with variable
+declarations and argument checking:
- * Additional built-in variables:
+ /* do_stat --- provide a stat() function for gawk */
- - The `ARGIND' `BINMODE', `ERRNO', `FIELDWIDTHS', `FPAT',
- `IGNORECASE', `LINT', `PROCINFO', `RT', and `TEXTDOMAIN'
- variables (*note Built-in Variables::).
+ static NODE *
+ do_stat(int nargs)
+ {
+ NODE *file, *array, *tmp;
+ struct stat sbuf;
+ int ret;
+ NODE **aptr;
+ char *pmode; /* printable mode */
+ char *type = "unknown";
- * Special files in I/O redirections:
+ if (do_lint && nargs > 2)
+ lintwarn("stat: called with too many arguments");
- - The `/dev/stdin', `/dev/stdout', `/dev/stderr' and
- `/dev/fd/N' special file names (*note Special Files::).
+ Then comes the actual work. First, the function gets the arguments.
+Then, it always clears the array. The code use `lstat()' (instead of
+`stat()') to get the file information, in case the file is a symbolic
+link. If there's an error, it sets `ERRNO' and returns:
- - The `/inet', `/inet4', and `/inet6' special files for TCP/IP
- networking using `|&' to specify which version of the IP
- protocol to use. (*note TCP/IP Networking::).
+ /* file is first arg, array to hold results is second */
+ file = get_scalar_argument(0, FALSE);
+ array = get_array_argument(1, FALSE);
- * Changes and/or additions to the language:
+ /* empty out the array */
+ assoc_clear(array);
- - The `\x' escape sequence (*note Escape Sequences::).
+ /* lstat the file, if error, set ERRNO and return */
+ (void) force_string(file);
+ ret = lstat(file->stptr, & sbuf);
+ if (ret < 0) {
+ update_ERRNO_int(errno);
+ return make_number((AWKNUM) ret);
+ }
- - Full support for both POSIX and GNU regexps (*note Regexp::).
+ Now comes the tedious part: filling in the array. Only a few of the
+calls are shown here, since they all follow the same pattern:
- - The ability for `FS' and for the third argument to `split()'
- to be null strings (*note Single Character Fields::).
+ /* fill in the array */
+ aptr = assoc_lookup(array, tmp = make_string("name", 4));
+ *aptr = dupnode(file);
+ unref(tmp);
- - The ability for `RS' to be a regexp (*note Records::).
+ aptr = assoc_lookup(array, tmp = make_string("mode", 4));
+ *aptr = make_number((AWKNUM) sbuf.st_mode);
+ unref(tmp);
- - The ability to use octal and hexadecimal constants in `awk'
- program source code (*note Nondecimal-numbers::).
+ aptr = assoc_lookup(array, tmp = make_string("pmode", 5));
+ pmode = format_mode(sbuf.st_mode);
+ *aptr = make_string(pmode, strlen(pmode));
+ unref(tmp);
- - The `|&' operator for two-way I/O to a coprocess (*note
- Two-way I/O::).
+ When done, return the `lstat()' return value:
- - Indirect function calls (*note Indirect Calls::).
- - Directories on the command line produce a warning and are
- skipped (*note Command line directories::).
+ return make_number((AWKNUM) ret);
+ }
- * New keywords:
+ Finally, it's necessary to provide the "glue" that loads the new
+function(s) into `gawk'. By convention, each library has a routine
+named `dl_load()' that does the job. The simplest way is to use the
+`dl_load_func' macro in `gawkapi.h'.
- - The `BEGINFILE' and `ENDFILE' special patterns. (*note
- BEGINFILE/ENDFILE::).
+ And that's it! As an exercise, consider adding functions to
+implement system calls such as `chown()', `chmod()', and `umask()'.
- - The ability to delete all of an array at once with `delete
- ARRAY' (*note Delete::).
+ ---------- Footnotes ----------
- - The `nextfile' statement (*note Nextfile Statement::).
+ (1) This version is edited slightly for presentation. See
+`extension/filefuncs.c' in the `gawk' distribution for the complete
+version.
- - The `switch' statement (*note Switch Statement::).
+
+File: gawk.info, Node: Using Internal File Ops, Prev: Internal File Ops,
Up: Sample Library
- * Changes to standard `awk' functions:
+16.2.3 Integrating the Extensions
+---------------------------------
- - The optional second argument to `close()' that allows closing
- one end of a two-way pipe to a coprocess (*note Two-way
- I/O::).
+Now that the code is written, it must be possible to add it at runtime
+to the running `gawk' interpreter. First, the code must be compiled.
+Assuming that the functions are in a file named `filefuncs.c', and IDIR
+is the location of the `gawk' include files, the following steps create
+a GNU/Linux shared library:
- - POSIX compliance for `gsub()' and `sub()'.
+ $ gcc -fPIC -shared -DHAVE_CONFIG_H -c -O -g -IIDIR filefuncs.c
+ $ ld -o filefuncs.so -shared filefuncs.o
- - The `length()' function accepts an array argument and returns
- the number of elements in the array (*note String
- Functions::).
+ Once the library exists, it is loaded by calling the `extension()'
+built-in function. This function takes two arguments: the name of the
+library to load and the name of a function to call when the library is
+first loaded. This function adds the new functions to `gawk'. It
+returns the value returned by the initialization function within the
+shared library:
- - The optional third argument to the `match()' function for
- capturing text-matching subexpressions within a regexp (*note
- String Functions::).
+ # file testff.awk
+ BEGIN {
+ extension("./filefuncs.so", "dl_load")
- - Positional specifiers in `printf' formats for making
- translations easier (*note Printf Ordering::).
+ chdir(".") # no-op
- - The `split()' function's additional optional fourth argument
- which is an array to hold the text of the field separators.
- (*note String Functions::).
+ data[1] = 1 # force `data' to be an array
+ print "Info for testff.awk"
+ ret = stat("testff.awk", data)
+ print "ret =", ret
+ for (i in data)
+ printf "data[\"%s\"] = %s\n", i, data[i]
+ print "testff.awk modified:",
+ strftime("%m %d %y %H:%M:%S", data["mtime"])
- * Additional functions only in `gawk':
+ print "\nInfo for JUNK"
+ ret = stat("JUNK", data)
+ print "ret =", ret
+ for (i in data)
+ printf "data[\"%s\"] = %s\n", i, data[i]
+ print "JUNK modified:", strftime("%m %d %y %H:%M:%S", data["mtime"])
+ }
- - The `and()', `compl()', `lshift()', `or()', `rshift()', and
- `xor()' functions for bit manipulation (*note Bitwise
- Functions::).
+ Here are the results of running the program:
- - The `asort()' and `asorti()' functions for sorting arrays
- (*note Array Sorting::).
+ $ gawk -f testff.awk
+ -| Info for testff.awk
+ -| ret = 0
+ -| data["size"] = 607
+ -| data["ino"] = 14945891
+ -| data["name"] = testff.awk
+ -| data["pmode"] = -rw-rw-r--
+ -| data["nlink"] = 1
+ -| data["atime"] = 1293993369
+ -| data["mtime"] = 1288520752
+ -| data["mode"] = 33204
+ -| data["blksize"] = 4096
+ -| data["dev"] = 2054
+ -| data["type"] = file
+ -| data["gid"] = 500
+ -| data["uid"] = 500
+ -| data["blocks"] = 8
+ -| data["ctime"] = 1290113572
+ -| testff.awk modified: 10 31 10 12:25:52
+ -|
+ -| Info for JUNK
+ -| ret = -1
+ -| JUNK modified: 01 01 70 02:00:00
- - The `bindtextdomain()', `dcgettext()' and `dcngettext()'
- functions for internationalization (*note Programmer i18n::).
+
+File: gawk.info, Node: Language History, Next: Installation, Prev: Dynamic
Extensions, Up: Top
- - The `extension()' built-in function and the ability to add
- new functions dynamically (*note Dynamic Extensions::).
+Appendix A The Evolution of the `awk' Language
+**********************************************
- - The `fflush()' function from Brian Kernighan's version of
- `awk' (*note I/O Functions::).
+This Info file describes the GNU implementation of `awk', which follows
+the POSIX specification. Many long-time `awk' users learned `awk'
+programming with the original `awk' implementation in Version 7 Unix.
+(This implementation was the basis for `awk' in Berkeley Unix, through
+4.3-Reno. Subsequent versions of Berkeley Unix, and some systems
+derived from 4.4BSD-Lite, use various versions of `gawk' for their
+`awk'.) This major node briefly describes the evolution of the `awk'
+language, with cross-references to other parts of the Info file where
+you can find more information.
- - The `gensub()', `patsplit()', and `strtonum()' functions for
- more powerful text manipulation (*note String Functions::).
+* Menu:
- - The `mktime()', `systime()', and `strftime()' functions for
- working with timestamps (*note Time Functions::).
+* V7/SVR3.1:: The major changes between V7 and System V
+ Release 3.1.
+* SVR4:: Minor changes between System V Releases 3.1
+ and 4.
+* POSIX:: New features from the POSIX standard.
+* BTL:: New features from Brian Kernighan's version of
+ `awk'.
+* POSIX/GNU:: The extensions in `gawk' not in POSIX
+ `awk'.
+* Common Extensions:: Common Extensions Summary.
+* Ranges and Locales:: How locales used to affect regexp ranges.
+* Contributors:: The major contributors to `gawk'.
- * Changes and/or additions in the command-line options:
+
+File: gawk.info, Node: V7/SVR3.1, Next: SVR4, Up: Language History
- - The `AWKPATH' environment variable for specifying a path
- search for the `-f' command-line option (*note Options::).
+A.1 Major Changes Between V7 and SVR3.1
+=======================================
- - The `AWKLIBPATH' environment variable for specifying a path
- search for the `-l' command-line option (*note Options::).
+The `awk' language evolved considerably between the release of Version
+7 Unix (1978) and the new version that was first made generally
+available in System V Release 3.1 (1987). This minor node summarizes
+the changes, with cross-references to further details:
- - The ability to use GNU-style long-named options that start
- with `--' and the `--characters-as-bytes', `--compat',
- `--dump-variables', `--exec', `--gen-pot', `--lint',
- `--lint-old', `--non-decimal-data', `--posix', `--profile',
- `--re-interval', `--sandbox', `--source', `--traditional', and
- `--use-lc-numeric' options (*note Options::).
+ * The requirement for `;' to separate rules on a line (*note
+ Statements/Lines::).
- * Support for the following obsolete systems was removed from the
- code and the documentation for `gawk' version 4.0:
+ * User-defined functions and the `return' statement (*note
+ User-defined::).
- - Amiga
+ * The `delete' statement (*note Delete::).
- - Atari
+ * The `do'-`while' statement (*note Do Statement::).
- - BeOS
+ * The built-in functions `atan2()', `cos()', `sin()', `rand()', and
+ `srand()' (*note Numeric Functions::).
- - Cray
+ * The built-in functions `gsub()', `sub()', and `match()' (*note
+ String Functions::).
- - MIPS RiscOS
+ * The built-in functions `close()' and `system()' (*note I/O
+ Functions::).
- - MS-DOS with the Microsoft Compiler
+ * The `ARGC', `ARGV', `FNR', `RLENGTH', `RSTART', and `SUBSEP'
+ built-in variables (*note Built-in Variables::).
- - MS-Windows with the Microsoft Compiler
+ * Assignable `$0' (*note Changing Fields::).
- - NeXT
+ * The conditional expression using the ternary operator `?:' (*note
+ Conditional Exp::).
- - SunOS 3.x, Sun 386 (Road Runner)
+ * The expression `INDEX-VARIABLE in ARRAY' outside of `for'
+ statements (*note Reference to Elements::).
- - Tandem (non-POSIX)
+ * The exponentiation operator `^' (*note Arithmetic Ops::) and its
+ assignment operator form `^=' (*note Assignment Ops::).
- - Prestandard VAX C compiler for VAX/VMS
+ * C-compatible operator precedence, which breaks some old `awk'
+ programs (*note Precedence::).
+ * Regexps as the value of `FS' (*note Field Separators::) and as the
+ third argument to the `split()' function (*note String
+ Functions::), rather than using only the first character of `FS'.
+ * Dynamic regexps as operands of the `~' and `!~' operators (*note
+ Regexp Usage::).
-
-File: gawk.info, Node: Common Extensions, Next: Ranges and Locales, Prev:
POSIX/GNU, Up: Language History
+ * The escape sequences `\b', `\f', and `\r' (*note Escape
+ Sequences::). (Some vendors have updated their old versions of
+ `awk' to recognize `\b', `\f', and `\r', but this is not something
+ you can rely on.)
-A.6 Common Extensions Summary
-=============================
+ * Redirection of input for the `getline' function (*note Getline::).
-This minor node summarizes the common extensions supported by `gawk',
-Brian Kernighan's `awk', and `mawk', the three most widely-used freely
-available versions of `awk' (*note Other Versions::).
+ * Multiple `BEGIN' and `END' rules (*note BEGIN/END::).
-Feature BWK Awk Mawk GNU Awk
---------------------------------------------------------
-`\x' Escape sequence X X X
-`RS' as regexp X X
-`FS' as null string X X X
-`/dev/stdin' special file X X
-`/dev/stdout' special file X X X
-`/dev/stderr' special file X X X
-`**' and `**=' operators X X
-`func' keyword X X
-`nextfile' statement X X X
-`delete' without subscript X X X
-`length()' of an array X X
-`fflush()' function X X X
-`BINMODE' variable X X
+ * Multidimensional arrays (*note Multi-dimensional::).
-File: gawk.info, Node: Ranges and Locales, Next: Contributors, Prev: Common
Extensions, Up: Language History
+File: gawk.info, Node: SVR4, Next: POSIX, Prev: V7/SVR3.1, Up: Language
History
-A.7 Regexp Ranges and Locales: A Long Sad Story
-===============================================
+A.2 Changes Between SVR3.1 and SVR4
+===================================
-This minor node describes the confusing history of ranges within
-regular expressions and their interactions with locales, and how this
-affected different versions of `gawk'.
+The System V Release 4 (1989) version of Unix `awk' added these features
+(some of which originated in `gawk'):
- The original Unix tools that worked with regular expressions defined
-character ranges (such as `[a-z]') to match any character between the
-first character in the range and the last character in the range,
-inclusive. Ordering was based on the numeric value of each character
-in the machine's native character set. Thus, on ASCII-based systems,
-`[a-z]' matched all the lowercase letters, and only the lowercase
-letters, since the numeric values for the letters from `a' through `z'
-were contiguous. (On an EBCDIC system, the range `[a-z]' includes
-additional, non-alphabetic characters as well.)
+ * The `ENVIRON' array (*note Built-in Variables::).
- Almost all introductory Unix literature explained range expressions
-as working in this fashion, and in particular, would teach that the
-"correct" way to match lowercase letters was with `[a-z]', and that
-`[A-Z]' was the "correct" way to match uppercase letters. And indeed,
-this was true.
+ * Multiple `-f' options on the command line (*note Options::).
- The 1993 POSIX standard introduced the idea of locales (*note
-Locales::). Since many locales include other letters besides the plain
-twenty-six letters of the American English alphabet, the POSIX standard
-added character classes (*note Bracket Expressions::) as a way to match
-different kinds of characters besides the traditional ones in the ASCII
-character set.
+ * The `-v' option for assigning variables before program execution
+ begins (*note Options::).
- However, the standard _changed_ the interpretation of range
-expressions. In the `"C"' and `"POSIX"' locales, a range expression
-like `[a-dx-z]' is still equivalent to `[abcdxyz]', as in ASCII. But
-outside those locales, the ordering was defined to be based on
-"collation order".
+ * The `--' option for terminating command-line options.
- In many locales, `A' and `a' are both less than `B'. In other
-words, these locales sort characters in dictionary order, and
-`[a-dx-z]' is typically not equivalent to `[abcdxyz]'; instead it might
-be equivalent to `[aBbCcdXxYyz]', for example.
+ * The `\a', `\v', and `\x' escape sequences (*note Escape
+ Sequences::).
- This point needs to be emphasized: Much literature teaches that you
-should use `[a-z]' to match a lowercase character. But on systems with
-non-ASCII locales, this also matched all of the uppercase characters
-except `Z'! This was a continuous cause of confusion, even well into
-the twenty-first century.
+ * A defined return value for the `srand()' built-in function (*note
+ Numeric Functions::).
- To demonstrate these issues, the following example uses the `sub()'
-function, which does text replacement (*note String Functions::). Here,
-the intent is to remove trailing uppercase characters:
+ * The `toupper()' and `tolower()' built-in string functions for case
+ translation (*note String Functions::).
- $ echo something1234abc | gawk-3.1.8 '{ sub("[A-Z]*$", ""); print }'
- -| something1234a
+ * A cleaner specification for the `%c' format-control letter in the
+ `printf' function (*note Control Letters::).
-This output is unexpected, since the `bc' at the end of
-`something1234abc' should not normally match `[A-Z]*'. This result is
-due to the locale setting (and thus you may not see it on your system).
+ * The ability to dynamically pass the field width and precision
+ (`"%*.*d"') in the argument list of the `printf' function (*note
+ Control Letters::).
- Similar considerations apply to other ranges. For example, `["-/]'
-is perfectly valid in ASCII, but is not valid in many Unicode locales,
-such as `en_US.UTF-8'.
+ * The use of regexp constants, such as `/foo/', as expressions, where
+ they are equivalent to using the matching operator, as in `$0 ~
+ /foo/' (*note Using Constant Regexps::).
- Early versions of `gawk' used regexp matching code that was not
-locale aware, so ranges had their traditional interpretation.
+ * Processing of escape sequences inside command-line variable
+ assignments (*note Assignment Options::).
- When `gawk' switched to using locale-aware regexp matchers, the
-problems began; especially as both GNU/Linux and commercial Unix
-vendors started implementing non-ASCII locales, _and making them the
-default_. Perhaps the most frequently asked question became something
-like "why does `[A-Z]' match lowercase letters?!?"
+
+File: gawk.info, Node: POSIX, Next: BTL, Prev: SVR4, Up: Language History
- This situation existed for close to 10 years, if not more, and the
-`gawk' maintainer grew weary of trying to explain that `gawk' was being
-nicely standards-compliant, and that the issue was in the user's
-locale. During the development of version 4.0, he modified `gawk' to
-always treat ranges in the original, pre-POSIX fashion, unless
-`--posix' was used (*note Options::).
+A.3 Changes Between SVR4 and POSIX `awk'
+========================================
- Fortunately, shortly before the final release of `gawk' 4.0, the
-maintainer learned that the 2008 standard had changed the definition of
-ranges, such that outside the `"C"' and `"POSIX"' locales, the meaning
-of range expressions was _undefined_.(1)
+The POSIX Command Language and Utilities standard for `awk' (1992)
+introduced the following changes into the language:
- By using this lovely technical term, the standard gives license to
-implementors to implement ranges in whatever way they choose. The
-`gawk' maintainer chose to apply the pre-POSIX meaning in all cases:
-the default regexp matching; with `--traditional', and with `--posix';
-in all cases, `gawk' remains POSIX compliant.
+ * The use of `-W' for implementation-specific options (*note
+ Options::).
- ---------- Footnotes ----------
+ * The use of `CONVFMT' for controlling the conversion of numbers to
+ strings (*note Conversion::).
- (1) See the standard
-(http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_03_05)
-and its rationale
-(http://pubs.opengroup.org/onlinepubs/9699919799/xrat/V4_xbd_chap09.html#tag_21_09_03_05).
+ * The concept of a numeric string and tighter comparison rules to go
+ with it (*note Typing and Comparison::).
-
-File: gawk.info, Node: Contributors, Prev: Ranges and Locales, Up: Language
History
+ * The use of built-in variables as function parameter names is
+ forbidden (*note Definition Syntax::.
-A.8 Major Contributors to `gawk'
-================================
+ * More complete documentation of many of the previously undocumented
+ features of the language.
- Always give credit where credit is due.
- Anonymous
+ *Note Common Extensions::, for a list of common extensions not
+permitted by the POSIX standard.
- This minor node names the major contributors to `gawk' and/or this
-Info file, in approximate chronological order:
+ The 2008 POSIX standard can be found online at
+`http://www.opengroup.org/onlinepubs/9699919799/'.
- * Dr. Alfred V. Aho, Dr. Peter J. Weinberger, and Dr. Brian W.
- Kernighan, all of Bell Laboratories, designed and implemented Unix
- `awk', from which `gawk' gets the majority of its feature set.
+
+File: gawk.info, Node: BTL, Next: POSIX/GNU, Prev: POSIX, Up: Language
History
- * Paul Rubin did the initial design and implementation in 1986, and
- wrote the first draft (around 40 pages) of this Info file.
+A.4 Extensions in Brian Kernighan's `awk'
+=========================================
- * Jay Fenlason finished the initial implementation.
+Brian Kernighan has made his version available via his home page (*note
+Other Versions::).
- * Diane Close revised the first draft of this Info file, bringing it
- to around 90 pages.
+ This minor node describes common extensions that originally appeared
+in his version of `awk'.
- * Richard Stallman helped finish the implementation and the initial
- draft of this Info file. He is also the founder of the FSF and
- the GNU project.
+ * The `**' and `**=' operators (*note Arithmetic Ops:: and *note
+ Assignment Ops::).
- * John Woods contributed parts of the code (mostly fixes) in the
- initial version of `gawk'.
+ * The use of `func' as an abbreviation for `function' (*note
+ Definition Syntax::).
- * In 1988, David Trueman took over primary maintenance of `gawk',
- making it compatible with "new" `awk', and greatly improving its
- performance.
-
- * Conrad Kwok, Scott Garfinkle, and Kent Williams did the initial
- ports to MS-DOS with various versions of MSC.
+ * The `fflush()' built-in function for flushing buffered output
+ (*note I/O Functions::).
- * Pat Rankin provided the VMS port and its documentation.
- * Hal Peterson provided help in porting `gawk' to Cray systems.
- (This is no longer supported.)
+ *Note Common Extensions::, for a full list of the extensions
+available in his `awk'.
- * Kai Uwe Rommel provided the initial port to OS/2 and its
- documentation.
+
+File: gawk.info, Node: POSIX/GNU, Next: Common Extensions, Prev: BTL, Up:
Language History
- * Michal Jaegermann provided the port to Atari systems and its
- documentation. (This port is no longer supported.) He continues
- to provide portability checking with DEC Alpha systems, and has
- done a lot of work to make sure `gawk' works on non-32-bit systems.
+A.5 Extensions in `gawk' Not in POSIX `awk'
+===========================================
- * Fred Fish provided the port to Amiga systems and its documentation.
- (With Fred's sad passing, this is no longer supported.)
+The GNU implementation, `gawk', adds a large number of features. They
+can all be disabled with either the `--traditional' or `--posix' options
+(*note Options::).
- * Scott Deifik currently maintains the MS-DOS port using DJGPP.
+ A number of features have come and gone over the years. This minor
+node summarizes the additional features over POSIX `awk' that are in
+the current version of `gawk'.
- * Eli Zaretskii currently maintains the MS-Windows port using MinGW.
+ * Additional built-in variables:
- * Juan Grigera provided a port to Windows32 systems. (This is no
- longer supported.)
+ - The `ARGIND' `BINMODE', `ERRNO', `FIELDWIDTHS', `FPAT',
+ `IGNORECASE', `LINT', `PROCINFO', `RT', and `TEXTDOMAIN'
+ variables (*note Built-in Variables::).
- * For many years, Dr. Darrel Hankerson acted as coordinator for the
- various ports to different PC platforms and created binary
- distributions for various PC operating systems. He was also
- instrumental in keeping the documentation up to date for the
- various PC platforms.
+ * Special files in I/O redirections:
- * Christos Zoulas provided the `extension()' built-in function for
- dynamically adding new modules.
+ - The `/dev/stdin', `/dev/stdout', `/dev/stderr' and
+ `/dev/fd/N' special file names (*note Special Files::).
- * Ju"rgen Kahrs contributed the initial version of the TCP/IP
- networking code and documentation, and motivated the inclusion of
- the `|&' operator.
+ - The `/inet', `/inet4', and `/inet6' special files for TCP/IP
+ networking using `|&' to specify which version of the IP
+ protocol to use. (*note TCP/IP Networking::).
- * Stephen Davies provided the initial port to Tandem systems and its
- documentation. (However, this is no longer supported.) He was
- also instrumental in the initial work to integrate the byte-code
- internals into the `gawk' code base.
+ * Changes and/or additions to the language:
- * Matthew Woehlke provided improvements for Tandem's POSIX-compliant
- systems.
+ - The `\x' escape sequence (*note Escape Sequences::).
- * Martin Brown provided the port to BeOS and its documentation.
- (This is no longer supported.)
+ - Full support for both POSIX and GNU regexps (*note Regexp::).
- * Arno Peters did the initial work to convert `gawk' to use GNU
- Automake and GNU `gettext'.
+ - The ability for `FS' and for the third argument to `split()'
+ to be null strings (*note Single Character Fields::).
- * Alan J. Broder provided the initial version of the `asort()'
- function as well as the code for the optional third argument to the
- `match()' function.
+ - The ability for `RS' to be a regexp (*note Records::).
- * Andreas Buening updated the `gawk' port for OS/2.
+ - The ability to use octal and hexadecimal constants in `awk'
+ program source code (*note Nondecimal-numbers::).
- * Isamu Hasegawa, of IBM in Japan, contributed support for multibyte
- characters.
+ - The `|&' operator for two-way I/O to a coprocess (*note
+ Two-way I/O::).
- * Michael Benzinger contributed the initial code for `switch'
- statements.
+ - Indirect function calls (*note Indirect Calls::).
- * Patrick T.J. McPhee contributed the code for dynamic loading in
- Windows32 environments. (This is no longer supported)
+ - Directories on the command line produce a warning and are
+ skipped (*note Command line directories::).
- * John Haque reworked the `gawk' internals to use a byte-code engine,
- providing the `gawk' debugger for `awk' programs.
+ * New keywords:
- * Efraim Yawitz contributed the original text for *note Debugger::.
+ - The `BEGINFILE' and `ENDFILE' special patterns. (*note
+ BEGINFILE/ENDFILE::).
- * Arnold Robbins has been working on `gawk' since 1988, at first
- helping David Trueman, and as the primary maintainer since around
- 1994.
+ - The ability to delete all of an array at once with `delete
+ ARRAY' (*note Delete::).
-
-File: gawk.info, Node: Installation, Next: Notes, Prev: Language History,
Up: Top
+ - The `nextfile' statement (*note Nextfile Statement::).
-Appendix B Installing `gawk'
-****************************
+ - The `switch' statement (*note Switch Statement::).
-This appendix provides instructions for installing `gawk' on the
-various platforms that are supported by the developers. The primary
-developer supports GNU/Linux (and Unix), whereas the other ports are
-contributed. *Note Bugs::, for the electronic mail addresses of the
-people who did the respective ports.
+ * Changes to standard `awk' functions:
-* Menu:
+ - The optional second argument to `close()' that allows closing
+ one end of a two-way pipe to a coprocess (*note Two-way
+ I/O::).
-* Gawk Distribution:: What is in the `gawk' distribution.
-* Unix Installation:: Installing `gawk' under various
- versions of Unix.
-* Non-Unix Installation:: Installation on Other Operating Systems.
-* Bugs:: Reporting Problems and Bugs.
-* Other Versions:: Other freely available `awk'
- implementations.
+ - POSIX compliance for `gsub()' and `sub()'.
-
-File: gawk.info, Node: Gawk Distribution, Next: Unix Installation, Up:
Installation
+ - The `length()' function accepts an array argument and returns
+ the number of elements in the array (*note String
+ Functions::).
-B.1 The `gawk' Distribution
-===========================
+ - The optional third argument to the `match()' function for
+ capturing text-matching subexpressions within a regexp (*note
+ String Functions::).
-This minor node describes how to get the `gawk' distribution, how to
-extract it, and then what is in the various files and subdirectories.
+ - Positional specifiers in `printf' formats for making
+ translations easier (*note Printf Ordering::).
-* Menu:
+ - The `split()' function's additional optional fourth argument
+ which is an array to hold the text of the field separators.
+ (*note String Functions::).
-* Getting:: How to get the distribution.
-* Extracting:: How to extract the distribution.
-* Distribution contents:: What is in the distribution.
+ * Additional functions only in `gawk':
-
-File: gawk.info, Node: Getting, Next: Extracting, Up: Gawk Distribution
+ - The `and()', `compl()', `lshift()', `or()', `rshift()', and
+ `xor()' functions for bit manipulation (*note Bitwise
+ Functions::).
-B.1.1 Getting the `gawk' Distribution
--------------------------------------
+ - The `asort()' and `asorti()' functions for sorting arrays
+ (*note Array Sorting::).
-There are three ways to get GNU software:
+ - The `bindtextdomain()', `dcgettext()' and `dcngettext()'
+ functions for internationalization (*note Programmer i18n::).
- * Copy it from someone else who already has it.
+ - The `fflush()' function from Brian Kernighan's version of
+ `awk' (*note I/O Functions::).
- * Retrieve `gawk' from the Internet host `ftp.gnu.org', in the
- directory `/gnu/gawk'. Both anonymous `ftp' and `http' access are
- supported. If you have the `wget' program, you can use a command
- like the following:
+ - The `gensub()', `patsplit()', and `strtonum()' functions for
+ more powerful text manipulation (*note String Functions::).
- wget http://ftp.gnu.org/gnu/gawk/gawk-4.0.1.tar.gz
+ - The `mktime()', `systime()', and `strftime()' functions for
+ working with timestamps (*note Time Functions::).
- The GNU software archive is mirrored around the world. The
-up-to-date list of mirror sites is available from the main FSF web site
-(http://www.gnu.org/order/ftp.html). Try to use one of the mirrors;
-they will be less busy, and you can usually find one closer to your
-site.
+ * Changes and/or additions in the command-line options:
-
-File: gawk.info, Node: Extracting, Next: Distribution contents, Prev:
Getting, Up: Gawk Distribution
+ - The `AWKPATH' environment variable for specifying a path
+ search for the `-f' command-line option (*note Options::).
-B.1.2 Extracting the Distribution
----------------------------------
+ - The `AWKLIBPATH' environment variable for specifying a path
+ search for the `-l' command-line option (*note Options::).
-`gawk' is distributed as several `tar' files compressed with different
-compression programs: `gzip', `bzip2', and `xz'. For simplicity, the
-rest of these instructions assume you are using the one compressed with
-the GNU Zip program, `gzip'.
+ - The ability to use GNU-style long-named options that start
+ with `--' and the `--bignum', `--characters-as-bytes',
+ `--copyright', `--debug', `--dump-variables', `--exec',
+ `--gen-pot', `--include', `--lint', `--lint-old', `--load',
+ `--non-decimal-data', `--optimize', `--posix',
+ `--pretty-print', `--profile', `--re-interval', `--sandbox',
+ `--source', `--traditional', and `--use-lc-numeric' options
+ (*note Options::).
- Once you have the distribution (for example, `gawk-4.0.1.tar.gz'),
-use `gzip' to expand the file and then use `tar' to extract it. You
-can use the following pipeline to produce the `gawk' distribution:
+ * Support for the following obsolete systems was removed from the
+ code and the documentation for `gawk' version 4.0:
- # Under System V, add 'o' to the tar options
- gzip -d -c gawk-4.0.1.tar.gz | tar -xvpf -
+ - Amiga
- On a system with GNU `tar', you can let `tar' do the decompression
-for you:
+ - Atari
- tar -xvpzf gawk-4.0.1.tar.gz
+ - BeOS
-Extracting the archive creates a directory named `gawk-4.0.1' in the
-current directory.
+ - Cray
- The distribution file name is of the form `gawk-V.R.P.tar.gz'. The
-V represents the major version of `gawk', the R represents the current
-release of version V, and the P represents a "patch level", meaning
-that minor bugs have been fixed in the release. The current patch
-level is 1, but when retrieving distributions, you should get the
-version with the highest version, release, and patch level. (Note,
-however, that patch levels greater than or equal to 70 denote "beta" or
-nonproduction software; you might not want to retrieve such a version
-unless you don't mind experimenting.) If you are not on a Unix or
-GNU/Linux system, you need to make other arrangements for getting and
-extracting the `gawk' distribution. You should consult a local expert.
+ - MIPS RiscOS
-
-File: gawk.info, Node: Distribution contents, Prev: Extracting, Up: Gawk
Distribution
+ - MS-DOS with the Microsoft Compiler
-B.1.3 Contents of the `gawk' Distribution
------------------------------------------
+ - MS-Windows with the Microsoft Compiler
-The `gawk' distribution has a number of C source files, documentation
-files, subdirectories, and files related to the configuration process
-(*note Unix Installation::), as well as several subdirectories related
-to different non-Unix operating systems:
+ - NeXT
-Various `.c', `.y', and `.h' files
- The actual `gawk' source code.
+ - SunOS 3.x, Sun 386 (Road Runner)
-`README'
-`README_d/README.*'
- Descriptive files: `README' for `gawk' under Unix and the rest for
- the various hardware and software combinations.
+ - Tandem (non-POSIX)
-`INSTALL'
- A file providing an overview of the configuration and installation
- process.
+ - Prestandard VAX C compiler for VAX/VMS
-`ChangeLog'
- A detailed list of source code changes as bugs are fixed or
- improvements made.
-`ChangeLog.0'
- An older list of source code changes.
-`NEWS'
- A list of changes to `gawk' since the last release or patch.
+
+File: gawk.info, Node: Common Extensions, Next: Ranges and Locales, Prev:
POSIX/GNU, Up: Language History
-`NEWS.0'
- An older list of changes to `gawk'.
+A.6 Common Extensions Summary
+=============================
-`COPYING'
- The GNU General Public License.
+This minor node summarizes the common extensions supported by `gawk',
+Brian Kernighan's `awk', and `mawk', the three most widely-used freely
+available versions of `awk' (*note Other Versions::).
-`FUTURES'
- A brief list of features and changes being contemplated for future
- releases, with some indication of the time frame for the feature,
- based on its difficulty.
-
-`LIMITATIONS'
- A list of those factors that limit `gawk''s performance. Most of
- these depend on the hardware or operating system software and are
- not limits in `gawk' itself.
-
-`POSIX.STD'
- A description of behaviors in the POSIX standard for `awk' which
- are left undefined, or where `gawk' may not comply fully, as well
- as a list of things that the POSIX standard should describe but
- does not.
-
-`doc/awkforai.txt'
- A short article describing why `gawk' is a good language for
- Artificial Intelligence (AI) programming.
-
-`doc/bc_notes'
- A brief description of `gawk''s "byte code" internals.
-
-`doc/README.card'
-`doc/ad.block'
-`doc/awkcard.in'
-`doc/cardfonts'
-`doc/colors'
-`doc/macros'
-`doc/no.colors'
-`doc/setter.outline'
- The `troff' source for a five-color `awk' reference card. A
- modern version of `troff' such as GNU `troff' (`groff') is needed
- to produce the color version. See the file `README.card' for
- instructions if you have an older `troff'.
-
-`doc/gawk.1'
- The `troff' source for a manual page describing `gawk'. This is
- distributed for the convenience of Unix users.
-
-`doc/gawk.texi'
- The Texinfo source file for this Info file. It should be
- processed with TeX (via `texi2dvi' or `texi2pdf') to produce a
- printed document, and with `makeinfo' to produce an Info or HTML
- file.
-
-`doc/gawk.info'
- The generated Info file for this Info file.
-
-`doc/gawkinet.texi'
- The Texinfo source file for *note (General Introduction)Top::
- gawkinet, TCP/IP Internetworking with `gawk'. It should be
- processed with TeX (via `texi2dvi' or `texi2pdf') to produce a
- printed document and with `makeinfo' to produce an Info or HTML
- file.
-
-`doc/gawkinet.info'
- The generated Info file for `TCP/IP Internetworking with `gawk''.
-
-`doc/igawk.1'
- The `troff' source for a manual page describing the `igawk'
- program presented in *note Igawk Program::.
-
-`doc/Makefile.in'
- The input file used during the configuration process to generate
- the actual `Makefile' for creating the documentation.
-
-`Makefile.am'
-`*/Makefile.am'
- Files used by the GNU `automake' software for generating the
- `Makefile.in' files used by `autoconf' and `configure'.
-
-`Makefile.in'
-`aclocal.m4'
-`configh.in'
-`configure.ac'
-`configure'
-`custom.h'
-`missing_d/*'
-`m4/*'
- These files and subdirectories are used when configuring `gawk'
- for various Unix systems. They are explained in *note Unix
- Installation::.
-
-`po/*'
- The `po' library contains message translations.
-
-`awklib/extract.awk'
-`awklib/Makefile.am'
-`awklib/Makefile.in'
-`awklib/eg/*'
- The `awklib' directory contains a copy of `extract.awk' (*note
- Extract Program::), which can be used to extract the sample
- programs from the Texinfo source file for this Info file. It also
- contains a `Makefile.in' file, which `configure' uses to generate
- a `Makefile'. `Makefile.am' is used by GNU Automake to create
- `Makefile.in'. The library functions from *note Library
- Functions::, and the `igawk' program from *note Igawk Program::,
- are included as ready-to-use files in the `gawk' distribution.
- They are installed as part of the installation process. The rest
- of the programs in this Info file are available in appropriate
- subdirectories of `awklib/eg'.
-
-`posix/*'
- Files needed for building `gawk' on POSIX-compliant systems.
-
-`pc/*'
- Files needed for building `gawk' under MS-Windows and OS/2 (*note
- PC Installation::, for details).
-
-`vms/*'
- Files needed for building `gawk' under VMS (*note VMS
- Installation::, for details).
-
-`test/*'
- A test suite for `gawk'. You can use `make check' from the
- top-level `gawk' directory to run your version of `gawk' against
- the test suite. If `gawk' successfully passes `make check', then
- you can be confident of a successful port.
+Feature BWK Awk Mawk GNU Awk
+--------------------------------------------------------
+`\x' Escape sequence X X X
+`RS' as regexp X X
+`FS' as null string X X X
+`/dev/stdin' special file X X
+`/dev/stdout' special file X X X
+`/dev/stderr' special file X X X
+`**' and `**=' operators X X
+`func' keyword X X
+`nextfile' statement X X X
+`delete' without subscript X X X
+`length()' of an array X X
+`fflush()' function X X X
+`BINMODE' variable X X
-File: gawk.info, Node: Unix Installation, Next: Non-Unix Installation,
Prev: Gawk Distribution, Up: Installation
+File: gawk.info, Node: Ranges and Locales, Next: Contributors, Prev: Common
Extensions, Up: Language History
-B.2 Compiling and Installing `gawk' on Unix-like Systems
-========================================================
+A.7 Regexp Ranges and Locales: A Long Sad Story
+===============================================
-Usually, you can compile and install `gawk' by typing only two
-commands. However, if you use an unusual system, you may need to
-configure `gawk' for your system yourself.
+This minor node describes the confusing history of ranges within
+regular expressions and their interactions with locales, and how this
+affected different versions of `gawk'.
-* Menu:
+ The original Unix tools that worked with regular expressions defined
+character ranges (such as `[a-z]') to match any character between the
+first character in the range and the last character in the range,
+inclusive. Ordering was based on the numeric value of each character
+in the machine's native character set. Thus, on ASCII-based systems,
+`[a-z]' matched all the lowercase letters, and only the lowercase
+letters, since the numeric values for the letters from `a' through `z'
+were contiguous. (On an EBCDIC system, the range `[a-z]' includes
+additional, non-alphabetic characters as well.)
-* Quick Installation:: Compiling `gawk' under Unix.
-* Additional Configuration Options:: Other compile-time options.
-* Configuration Philosophy:: How it's all supposed to work.
+ Almost all introductory Unix literature explained range expressions
+as working in this fashion, and in particular, would teach that the
+"correct" way to match lowercase letters was with `[a-z]', and that
+`[A-Z]' was the "correct" way to match uppercase letters. And indeed,
+this was true.
-
-File: gawk.info, Node: Quick Installation, Next: Additional Configuration
Options, Up: Unix Installation
+ The 1993 POSIX standard introduced the idea of locales (*note
+Locales::). Since many locales include other letters besides the plain
+twenty-six letters of the American English alphabet, the POSIX standard
+added character classes (*note Bracket Expressions::) as a way to match
+different kinds of characters besides the traditional ones in the ASCII
+character set.
-B.2.1 Compiling `gawk' for Unix-like Systems
---------------------------------------------
+ However, the standard _changed_ the interpretation of range
+expressions. In the `"C"' and `"POSIX"' locales, a range expression
+like `[a-dx-z]' is still equivalent to `[abcdxyz]', as in ASCII. But
+outside those locales, the ordering was defined to be based on
+"collation order".
-The normal installation steps should work on all modern commercial
-Unix-derived systems, GNU/Linux, BSD-based systems, and the Cygwin
-environment for MS-Windows.
+ In many locales, `A' and `a' are both less than `B'. In other
+words, these locales sort characters in dictionary order, and
+`[a-dx-z]' is typically not equivalent to `[abcdxyz]'; instead it might
+be equivalent to `[aBbCcdXxYyz]', for example.
- After you have extracted the `gawk' distribution, `cd' to
-`gawk-4.0.1'. Like most GNU software, `gawk' is configured
-automatically for your system by running the `configure' program. This
-program is a Bourne shell script that is generated automatically using
-GNU `autoconf'. (The `autoconf' software is described fully starting
-with *note (Autoconf)Top:: autoconf,Autoconf--Generating Automatic
-Configuration Scripts.)
+ This point needs to be emphasized: Much literature teaches that you
+should use `[a-z]' to match a lowercase character. But on systems with
+non-ASCII locales, this also matched all of the uppercase characters
+except `Z'! This was a continuous cause of confusion, even well into
+the twenty-first century.
- To configure `gawk', simply run `configure':
+ To demonstrate these issues, the following example uses the `sub()'
+function, which does text replacement (*note String Functions::). Here,
+the intent is to remove trailing uppercase characters:
- sh ./configure
+ $ echo something1234abc | gawk-3.1.8 '{ sub("[A-Z]*$", ""); print }'
+ -| something1234a
- This produces a `Makefile' and `config.h' tailored to your system.
-The `config.h' file describes various facts about your system. You
-might want to edit the `Makefile' to change the `CFLAGS' variable,
-which controls the command-line options that are passed to the C
-compiler (such as optimization levels or compiling for debugging).
+This output is unexpected, since the `bc' at the end of
+`something1234abc' should not normally match `[A-Z]*'. This result is
+due to the locale setting (and thus you may not see it on your system).
- Alternatively, you can add your own values for most `make' variables
-on the command line, such as `CC' and `CFLAGS', when running
-`configure':
+ Similar considerations apply to other ranges. For example, `["-/]'
+is perfectly valid in ASCII, but is not valid in many Unicode locales,
+such as `en_US.UTF-8'.
- CC=cc CFLAGS=-g sh ./configure
+ Early versions of `gawk' used regexp matching code that was not
+locale aware, so ranges had their traditional interpretation.
-See the file `INSTALL' in the `gawk' distribution for all the details.
+ When `gawk' switched to using locale-aware regexp matchers, the
+problems began; especially as both GNU/Linux and commercial Unix
+vendors started implementing non-ASCII locales, _and making them the
+default_. Perhaps the most frequently asked question became something
+like "why does `[A-Z]' match lowercase letters?!?"
- After you have run `configure' and possibly edited the `Makefile',
-type:
+ This situation existed for close to 10 years, if not more, and the
+`gawk' maintainer grew weary of trying to explain that `gawk' was being
+nicely standards-compliant, and that the issue was in the user's
+locale. During the development of version 4.0, he modified `gawk' to
+always treat ranges in the original, pre-POSIX fashion, unless
+`--posix' was used (*note Options::).
- make
+ Fortunately, shortly before the final release of `gawk' 4.0, the
+maintainer learned that the 2008 standard had changed the definition of
+ranges, such that outside the `"C"' and `"POSIX"' locales, the meaning
+of range expressions was _undefined_.(1)
-Shortly thereafter, you should have an executable version of `gawk'.
-That's all there is to it! To verify that `gawk' is working properly,
-run `make check'. All of the tests should succeed. If these steps do
-not work, or if any of the tests fail, check the files in the
-`README_d' directory to see if you've found a known problem. If the
-failure is not described there, please send in a bug report (*note
-Bugs::).
+ By using this lovely technical term, the standard gives license to
+implementors to implement ranges in whatever way they choose. The
+`gawk' maintainer chose to apply the pre-POSIX meaning in all cases:
+the default regexp matching; with `--traditional', and with `--posix';
+in all cases, `gawk' remains POSIX compliant.
-
-File: gawk.info, Node: Additional Configuration Options, Next: Configuration
Philosophy, Prev: Quick Installation, Up: Unix Installation
+ ---------- Footnotes ----------
-B.2.2 Additional Configuration Options
---------------------------------------
+ (1) See the standard
+(http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_03_05)
+and its rationale
+(http://pubs.opengroup.org/onlinepubs/9699919799/xrat/V4_xbd_chap09.html#tag_21_09_03_05).
-There are several additional options you may use on the `configure'
-command line when compiling `gawk' from scratch, including:
+
+File: gawk.info, Node: Contributors, Prev: Ranges and Locales, Up: Language
History
-`--disable-lint'
- Disable all lint checking within `gawk'. The `--lint' and
- `--lint-old' options (*note Options::) are accepted, but silently
- do nothing. Similarly, setting the `LINT' variable (*note
- User-modified::) has no effect on the running `awk' program.
+A.8 Major Contributors to `gawk'
+================================
- When used with GCC's automatic dead-code-elimination, this option
- cuts almost 200K bytes off the size of the `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.
+ Always give credit where credit is due.
+ Anonymous
- Using this option will cause some of the tests in the test suite
- to fail. This option may be removed at a later date.
+ This minor node names the major contributors to `gawk' and/or this
+Info file, in approximate chronological order:
-`--disable-nls'
- Disable all message-translation facilities. This is usually not
- desirable, but it may bring you some slight performance
- improvement.
+ * Dr. Alfred V. Aho, Dr. Peter J. Weinberger, and Dr. Brian W.
+ Kernighan, all of Bell Laboratories, designed and implemented Unix
+ `awk', from which `gawk' gets the majority of its feature set.
-`--with-whiny-user-strftime'
- Force use of the included version of the `strftime()' function for
- deficient systems.
+ * Paul Rubin did the initial design and implementation in 1986, and
+ wrote the first draft (around 40 pages) of this Info file.
- Use the command `./configure --help' to see the full list of options
-that `configure' supplies.
+ * Jay Fenlason finished the initial implementation.
-
-File: gawk.info, Node: Configuration Philosophy, Prev: Additional
Configuration Options, Up: Unix Installation
+ * Diane Close revised the first draft of this Info file, bringing it
+ to around 90 pages.
-B.2.3 The Configuration Process
--------------------------------
+ * Richard Stallman helped finish the implementation and the initial
+ draft of this Info file. He is also the founder of the FSF and
+ the GNU project.
-This minor node is of interest only if you know something about using
-the C language and Unix-like operating systems.
+ * John Woods contributed parts of the code (mostly fixes) in the
+ initial version of `gawk'.
- The source code for `gawk' generally attempts to adhere to formal
-standards wherever possible. This means that `gawk' uses library
-routines that are specified by the ISO C standard and by the POSIX
-operating system interface standard. The `gawk' source code requires
-using an ISO C compiler (the 1990 standard).
+ * In 1988, David Trueman took over primary maintenance of `gawk',
+ making it compatible with "new" `awk', and greatly improving its
+ performance.
- Many Unix systems do not support all of either the ISO or the POSIX
-standards. The `missing_d' subdirectory in the `gawk' distribution
-contains replacement versions of those functions that are most likely
-to be missing.
+ * Conrad Kwok, Scott Garfinkle, and Kent Williams did the initial
+ ports to MS-DOS with various versions of MSC.
- The `config.h' file that `configure' creates contains definitions
-that describe features of the particular operating system where you are
-attempting to compile `gawk'. The three things described by this file
-are: what header files are available, so that they can be correctly
-included, what (supposedly) standard functions are actually available
-in your C libraries, and various miscellaneous facts about your
-operating system. For example, there may not be an `st_blksize'
-element in the `stat' structure. In this case, `HAVE_ST_BLKSIZE' is
-undefined.
+ * Pat Rankin provided the VMS port and its documentation.
- It is possible for your C compiler to lie to `configure'. It may do
-so by not exiting with an error when a library function is not
-available. To get around this, edit the file `custom.h'. Use an
-`#ifdef' that is appropriate for your system, and either `#define' any
-constants that `configure' should have defined but didn't, or `#undef'
-any constants that `configure' defined and should not have. `custom.h'
-is automatically included by `config.h'.
+ * Hal Peterson provided help in porting `gawk' to Cray systems.
+ (This is no longer supported.)
- It is also possible that the `configure' program generated by
-`autoconf' will not work on your system in some other fashion. If you
-do have a problem, the file `configure.ac' is the input for `autoconf'.
-You may be able to change this file and generate a new version of
-`configure' that works on your system (*note Bugs::, for information on
-how to report problems in configuring `gawk'). The same mechanism may
-be used to send in updates to `configure.ac' and/or `custom.h'.
+ * Kai Uwe Rommel provided the initial port to OS/2 and its
+ documentation.
-
-File: gawk.info, Node: Non-Unix Installation, Next: Bugs, Prev: Unix
Installation, Up: Installation
+ * Michal Jaegermann provided the port to Atari systems and its
+ documentation. (This port is no longer supported.) He continues
+ to provide portability checking with DEC Alpha systems, and has
+ done a lot of work to make sure `gawk' works on non-32-bit systems.
-B.3 Installation on Other Operating Systems
-===========================================
+ * Fred Fish provided the port to Amiga systems and its documentation.
+ (With Fred's sad passing, this is no longer supported.)
-This minor node describes how to install `gawk' on various non-Unix
-systems.
+ * Scott Deifik currently maintains the MS-DOS port using DJGPP.
-* Menu:
+ * Eli Zaretskii currently maintains the MS-Windows port using MinGW.
-* PC Installation:: Installing and Compiling `gawk' on
- MS-DOS and OS/2.
-* VMS Installation:: Installing `gawk' on VMS.
+ * Juan Grigera provided a port to Windows32 systems. (This is no
+ longer supported.)
-
-File: gawk.info, Node: PC Installation, Next: VMS Installation, Up:
Non-Unix Installation
+ * For many years, Dr. Darrel Hankerson acted as coordinator for the
+ various ports to different PC platforms and created binary
+ distributions for various PC operating systems. He was also
+ instrumental in keeping the documentation up to date for the
+ various PC platforms.
-B.3.1 Installation on PC Operating Systems
-------------------------------------------
+ * Christos Zoulas provided the `extension()' built-in function for
+ dynamically adding new modules. (This was removed at `gawk' 4.1.)
-This minor node covers installation and usage of `gawk' on x86 machines
-running MS-DOS, any version of MS-Windows, or OS/2. In this minor
-node, the term "Windows32" refers to any of Microsoft
-Windows-95/98/ME/NT/2000/XP/Vista/7.
+ * Ju"rgen Kahrs contributed the initial version of the TCP/IP
+ networking code and documentation, and motivated the inclusion of
+ the `|&' operator.
- The limitations of MS-DOS (and MS-DOS shells under Windows32 or
-OS/2) has meant that various "DOS extenders" are often used with
-programs such as `gawk'. The varying capabilities of Microsoft Windows
-3.1 and Windows32 can add to the confusion. For an overview of the
-considerations, please refer to `README_d/README.pc' in the
-distribution.
+ * Stephen Davies provided the initial port to Tandem systems and its
+ documentation. (However, this is no longer supported.) He was
+ also instrumental in the initial work to integrate the byte-code
+ internals into the `gawk' code base.
-* Menu:
+ * Matthew Woehlke provided improvements for Tandem's POSIX-compliant
+ systems.
-* PC Binary Installation:: Installing a prepared distribution.
-* PC Compiling:: Compiling `gawk' for MS-DOS,
- Windows32, and OS/2.
-* PC Testing:: Testing `gawk' on PC systems.
-* PC Using:: Running `gawk' on MS-DOS, Windows32
- and OS/2.
-* Cygwin:: Building and running `gawk' for
- Cygwin.
-* MSYS:: Using `gawk' In The MSYS Environment.
+ * Martin Brown provided the port to BeOS and its documentation.
+ (This is no longer supported.)
-
-File: gawk.info, Node: PC Binary Installation, Next: PC Compiling, Up: PC
Installation
+ * Arno Peters did the initial work to convert `gawk' to use GNU
+ Automake and GNU `gettext'.
-B.3.1.1 Installing a Prepared Distribution for PC Systems
-.........................................................
+ * Alan J. Broder provided the initial version of the `asort()'
+ function as well as the code for the optional third argument to the
+ `match()' function.
-If you have received a binary distribution prepared by the MS-DOS
-maintainers, then `gawk' and the necessary support files appear under
-the `gnu' directory, with executables in `gnu/bin', libraries in
-`gnu/lib/awk', and manual pages under `gnu/man'. This is designed for
-easy installation to a `/gnu' directory on your drive--however, the
-files can be installed anywhere provided `AWKPATH' is set properly.
-Regardless of the installation directory, the first line of `igawk.cmd'
-and `igawk.bat' (in `gnu/bin') may need to be edited.
+ * Andreas Buening updated the `gawk' port for OS/2.
- The binary distribution contains a separate file describing the
-contents. In particular, it may include more than one version of the
-`gawk' executable.
+ * Isamu Hasegawa, of IBM in Japan, contributed support for multibyte
+ characters.
- OS/2 (32 bit, EMX) binary distributions are prepared for the `/usr'
-directory of your preferred drive. Set `UNIXROOT' to your installation
-drive (e.g., `e:') if you want to install `gawk' onto another drive
-than the hardcoded default `c:'. Executables appear in `/usr/bin',
-libraries under `/usr/share/awk', manual pages under `/usr/man',
-Texinfo documentation under `/usr/info', and NLS files under
-`/usr/share/locale'. Note that the files can be installed anywhere
-provided `AWKPATH' is set properly.
+ * Michael Benzinger contributed the initial code for `switch'
+ statements.
- If you already have a file `/usr/info/dir' from another package _do
-not overwrite it!_ Instead enter the following commands at your prompt
-(replace `x:' by your installation drive):
+ * Patrick T.J. McPhee contributed the code for dynamic loading in
+ Windows32 environments. (This is no longer supported)
- install-info --info-dir=x:/usr/info x:/usr/info/gawk.info
- install-info --info-dir=x:/usr/info x:/usr/info/gawkinet.info
+ * John Haque reworked the `gawk' internals to use a byte-code engine,
+ providing the `gawk' debugger for `awk' programs.
- The binary distribution may contain a separate file containing
-additional or more detailed installation instructions.
+ * Efraim Yawitz contributed the original text for *note Debugger::.
+
+ * Arnold Robbins has been working on `gawk' since 1988, at first
+ helping David Trueman, and as the primary maintainer since around
+ 1994.
-File: gawk.info, Node: PC Compiling, Next: PC Testing, Prev: PC Binary
Installation, Up: PC Installation
+File: gawk.info, Node: Installation, Next: Notes, Prev: Language History,
Up: Top
-B.3.1.2 Compiling `gawk' for PC Operating Systems
-.................................................
+Appendix B Installing `gawk'
+****************************
-`gawk' can be compiled for MS-DOS, Windows32, and OS/2 using the GNU
-development tools from DJ Delorie (DJGPP: MS-DOS only) or Eberhard
-Mattes (EMX: MS-DOS, Windows32 and OS/2). The file
-`README_d/README.pc' in the `gawk' distribution contains additional
-notes, and `pc/Makefile' contains important information on compilation
-options.
+This appendix provides instructions for installing `gawk' on the
+various platforms that are supported by the developers. The primary
+developer supports GNU/Linux (and Unix), whereas the other ports are
+contributed. *Note Bugs::, for the electronic mail addresses of the
+people who did the respective ports.
- To build `gawk' for MS-DOS and Windows32, copy the files in the `pc'
-directory (_except_ for `ChangeLog') to the directory with the rest of
-the `gawk' sources, then invoke `make' with the appropriate target name
-as an argument to build `gawk'. The `Makefile' copied from the `pc'
-directory contains a configuration section with comments and may need
-to be edited in order to work with your `make' utility.
+* Menu:
- The `Makefile' supports a number of targets for building various
-MS-DOS and Windows32 versions. A list of targets is printed if the
-`make' command is given without a target. As an example, to build
-`gawk' using the DJGPP tools, enter `make djgpp'. (The DJGPP tools
-needed for the build may be found at
-`ftp://ftp.delorie.com/pub/djgpp/current/v2gnu/'.) To build a native
-MS-Windows binary of `gawk', type `make mingw32'.
+* Gawk Distribution:: What is in the `gawk' distribution.
+* Unix Installation:: Installing `gawk' under various
+ versions of Unix.
+* Non-Unix Installation:: Installation on Other Operating Systems.
+* Bugs:: Reporting Problems and Bugs.
+* Other Versions:: Other freely available `awk'
+ implementations.
- The 32 bit EMX version of `gawk' works "out of the box" under OS/2.
-However, it is highly recommended to use GCC 2.95.3 for the compilation.
-In principle, it is possible to compile `gawk' the following way:
+
+File: gawk.info, Node: Gawk Distribution, Next: Unix Installation, Up:
Installation
- $ ./configure
- $ make
+B.1 The `gawk' Distribution
+===========================
- This is not recommended, though. To get an OMF executable you should
-use the following commands at your `sh' prompt:
+This minor node describes how to get the `gawk' distribution, how to
+extract it, and then what is in the various files and subdirectories.
- $ CFLAGS="-O2 -Zomf -Zmt"
- $ export CFLAGS
- $ LDFLAGS="-s -Zcrtdll -Zlinker /exepack:2 -Zlinker /pm:vio -Zstack
0x6000"
- $ export LDFLAGS
- $ RANLIB="echo"
- $ export RANLIB
- $ ./configure --prefix=c:/usr
- $ make AR=emxomfar
+* Menu:
- These are just suggestions for use with GCC 2.x. You may use any
-other set of (self-consistent) environment variables and compiler flags.
+* Getting:: How to get the distribution.
+* Extracting:: How to extract the distribution.
+* Distribution contents:: What is in the distribution.
- If you use GCC 2.95 it is recommended to use also:
+
+File: gawk.info, Node: Getting, Next: Extracting, Up: Gawk Distribution
- $ LIBS="-lgcc"
- $ export LIBS
+B.1.1 Getting the `gawk' Distribution
+-------------------------------------
- You can also get an `a.out' executable if you prefer:
+There are three ways to get GNU software:
- $ CFLAGS="-O2 -Zmt"
- $ export CFLAGS
- $ LDFLAGS="-s -Zstack 0x6000"
- $ LIBS="-lgcc"
- $ unset RANLIB
- $ ./configure --prefix=c:/usr
- $ make
+ * Copy it from someone else who already has it.
- NOTE: Compilation of `a.out' executables also works with GCC 3.2.
- Versions later than GCC 3.2 have not been tested successfully.
+ * Retrieve `gawk' from the Internet host `ftp.gnu.org', in the
+ directory `/gnu/gawk'. Both anonymous `ftp' and `http' access are
+ supported. If you have the `wget' program, you can use a command
+ like the following:
- `make install' works as expected with the EMX build.
+ wget http://ftp.gnu.org/gnu/gawk/gawk-4.0.1.tar.gz
- NOTE: Ancient OS/2 ports of GNU `make' are not able to handle the
- Makefiles of this package. If you encounter any problems with
- `make', try GNU Make 3.79.1 or later versions. You should find
- the latest version on `ftp://hobbes.nmsu.edu/pub/os2/'.
+ The GNU software archive is mirrored around the world. The
+up-to-date list of mirror sites is available from the main FSF web site
+(http://www.gnu.org/order/ftp.html). Try to use one of the mirrors;
+they will be less busy, and you can usually find one closer to your
+site.
-File: gawk.info, Node: PC Testing, Next: PC Using, Prev: PC Compiling, Up:
PC Installation
+File: gawk.info, Node: Extracting, Next: Distribution contents, Prev:
Getting, Up: Gawk Distribution
-B.3.1.3 Testing `gawk' on PC Operating Systems
-..............................................
+B.1.2 Extracting the Distribution
+---------------------------------
-Using `make' to run the standard tests and to install `gawk' requires
-additional Unix-like tools, including `sh', `sed', and `cp'. In order
-to run the tests, the `test/*.ok' files may need to be converted so
-that they have the usual MS-DOS-style end-of-line markers.
-Alternatively, run `make check CMP="diff -a"' to use GNU `diff' in text
-mode instead of `cmp' to compare the resulting files.
+`gawk' is distributed as several `tar' files compressed with different
+compression programs: `gzip', `bzip2', and `xz'. For simplicity, the
+rest of these instructions assume you are using the one compressed with
+the GNU Zip program, `gzip'.
- Most of the tests work properly with Stewartson's shell along with
-the companion utilities or appropriate GNU utilities. However, some
-editing of `test/Makefile' is required. It is recommended that you copy
-the file `pc/Makefile.tst' over the file `test/Makefile' as a
-replacement. Details can be found in `README_d/README.pc' and in the
-file `pc/Makefile.tst'.
+ Once you have the distribution (for example, `gawk-4.0.1.tar.gz'),
+use `gzip' to expand the file and then use `tar' to extract it. You
+can use the following pipeline to produce the `gawk' distribution:
- On OS/2 the `pid' test fails because `spawnl()' is used instead of
-`fork()'/`execl()' to start child processes. Also the `mbfw1' and
-`mbprintf1' tests fail because the needed multibyte functionality is
-not available.
+ # Under System V, add 'o' to the tar options
+ gzip -d -c gawk-4.0.1.tar.gz | tar -xvpf -
-
-File: gawk.info, Node: PC Using, Next: Cygwin, Prev: PC Testing, Up: PC
Installation
+ On a system with GNU `tar', you can let `tar' do the decompression
+for you:
-B.3.1.4 Using `gawk' on PC Operating Systems
-............................................
+ tar -xvpzf gawk-4.0.1.tar.gz
-With the exception of the Cygwin environment, the `|&' operator and
-TCP/IP networking (*note TCP/IP Networking::) are not supported for
-MS-DOS or MS-Windows. EMX (OS/2 only) does support at least the `|&'
-operator.
+Extracting the archive creates a directory named `gawk-4.0.1' in the
+current directory.
- The MS-DOS and MS-Windows versions of `gawk' search for program
-files as described in *note AWKPATH Variable::. However, semicolons
-(rather than colons) separate elements in the `AWKPATH' variable. If
-`AWKPATH' is not set or is empty, then the default search path for
-MS-Windows and MS-DOS versions is `".;c:/lib/awk;c:/gnu/lib/awk"'.
+ The distribution file name is of the form `gawk-V.R.P.tar.gz'. The
+V represents the major version of `gawk', the R represents the current
+release of version V, and the P represents a "patch level", meaning
+that minor bugs have been fixed in the release. The current patch
+level is 1, but when retrieving distributions, you should get the
+version with the highest version, release, and patch level. (Note,
+however, that patch levels greater than or equal to 70 denote "beta" or
+nonproduction software; you might not want to retrieve such a version
+unless you don't mind experimenting.) If you are not on a Unix or
+GNU/Linux system, you need to make other arrangements for getting and
+extracting the `gawk' distribution. You should consult a local expert.
- The search path for OS/2 (32 bit, EMX) is determined by the prefix
-directory (most likely `/usr' or `c:/usr') that has been specified as
-an option of the `configure' script like it is the case for the Unix
-versions. If `c:/usr' is the prefix directory then the default search
-path contains `.' and `c:/usr/share/awk'. Additionally, to support
-binary distributions of `gawk' for OS/2 systems whose drive `c:' might
-not support long file names or might not exist at all, there is a
-special environment variable. If `UNIXROOT' specifies a drive then
-this specific drive is also searched for program files. E.g., if
-`UNIXROOT' is set to `e:' the complete default search path is
-`".;c:/usr/share/awk;e:/usr/share/awk"'.
+
+File: gawk.info, Node: Distribution contents, Prev: Extracting, Up: Gawk
Distribution
- An `sh'-like shell (as opposed to `command.com' under MS-DOS or
-`cmd.exe' under MS-Windows or OS/2) may be useful for `awk' programming.
-The DJGPP collection of tools includes an MS-DOS port of Bash, and
-several shells are available for OS/2, including `ksh'.
+B.1.3 Contents of the `gawk' Distribution
+-----------------------------------------
- Under MS-Windows, OS/2 and MS-DOS, `gawk' (and many other text
-programs) silently translate end-of-line `"\r\n"' to `"\n"' on input
-and `"\n"' to `"\r\n"' on output. A special `BINMODE' variable
-(c.e.) allows control over these translations and is interpreted as
-follows:
+The `gawk' distribution has a number of C source files, documentation
+files, subdirectories, and files related to the configuration process
+(*note Unix Installation::), as well as several subdirectories related
+to different non-Unix operating systems:
- * If `BINMODE' is `"r"', or one, then binary mode is set on read
- (i.e., no translations on reads).
+Various `.c', `.y', and `.h' files
+ The actual `gawk' source code.
- * If `BINMODE' is `"w"', or two, then binary mode is set on write
- (i.e., no translations on writes).
+`README'
+`README_d/README.*'
+ Descriptive files: `README' for `gawk' under Unix and the rest for
+ the various hardware and software combinations.
- * If `BINMODE' is `"rw"' or `"wr"' or three, binary mode is set for
- both read and write.
+`INSTALL'
+ A file providing an overview of the configuration and installation
+ process.
- * `BINMODE=NON-NULL-STRING' is the same as `BINMODE=3' (i.e., no
- translations on reads or writes). However, `gawk' issues a warning
- message if the string is not one of `"rw"' or `"wr"'.
+`ChangeLog'
+ A detailed list of source code changes as bugs are fixed or
+ improvements made.
-The modes for standard input and standard output are set one time only
-(after the command line is read, but before processing any of the `awk'
-program). Setting `BINMODE' for standard input or standard output is
-accomplished by using an appropriate `-v BINMODE=N' option on the
-command line. `BINMODE' is set at the time a file or pipe is opened
-and cannot be changed mid-stream.
+`ChangeLog.0'
+ An older list of source code changes.
+
+`NEWS'
+ A list of changes to `gawk' since the last release or patch.
+
+`NEWS.0'
+ An older list of changes to `gawk'.
+
+`COPYING'
+ The GNU General Public License.
- The name `BINMODE' was chosen to match `mawk' (*note Other
-Versions::). `mawk' and `gawk' handle `BINMODE' similarly; however,
-`mawk' adds a `-W BINMODE=N' option and an environment variable that
-can set `BINMODE', `RS', and `ORS'. The files `binmode[1-3].awk'
-(under `gnu/lib/awk' in some of the prepared distributions) have been
-chosen to match `mawk''s `-W BINMODE=N' option. These can be changed
-or discarded; in particular, the setting of `RS' giving the fewest
-"surprises" is open to debate. `mawk' uses `RS = "\r\n"' if binary
-mode is set on read, which is appropriate for files with the
-MS-DOS-style end-of-line.
+`FUTURES'
+ A brief list of features and changes being contemplated for future
+ releases, with some indication of the time frame for the feature,
+ based on its difficulty.
- To illustrate, the following examples set binary mode on writes for
-standard output and other files, and set `ORS' as the "usual"
-MS-DOS-style end-of-line:
+`LIMITATIONS'
+ A list of those factors that limit `gawk''s performance. Most of
+ these depend on the hardware or operating system software and are
+ not limits in `gawk' itself.
- gawk -v BINMODE=2 -v ORS="\r\n" ...
+`POSIX.STD'
+ A description of behaviors in the POSIX standard for `awk' which
+ are left undefined, or where `gawk' may not comply fully, as well
+ as a list of things that the POSIX standard should describe but
+ does not.
-or:
+`doc/awkforai.txt'
+ A short article describing why `gawk' is a good language for
+ Artificial Intelligence (AI) programming.
- gawk -v BINMODE=w -f binmode2.awk ...
+`doc/bc_notes'
+ A brief description of `gawk''s "byte code" internals.
-These give the same result as the `-W BINMODE=2' option in `mawk'. The
-following changes the record separator to `"\r\n"' and sets binary mode
-on reads, but does not affect the mode on standard input:
+`doc/README.card'
+`doc/ad.block'
+`doc/awkcard.in'
+`doc/cardfonts'
+`doc/colors'
+`doc/macros'
+`doc/no.colors'
+`doc/setter.outline'
+ The `troff' source for a five-color `awk' reference card. A
+ modern version of `troff' such as GNU `troff' (`groff') is needed
+ to produce the color version. See the file `README.card' for
+ instructions if you have an older `troff'.
- gawk -v RS="\r\n" --source "BEGIN { BINMODE = 1 }" ...
+`doc/gawk.1'
+ The `troff' source for a manual page describing `gawk'. This is
+ distributed for the convenience of Unix users.
-or:
+`doc/gawk.texi'
+ The Texinfo source file for this Info file. It should be
+ processed with TeX (via `texi2dvi' or `texi2pdf') to produce a
+ printed document, and with `makeinfo' to produce an Info or HTML
+ file.
- gawk -f binmode1.awk ...
+`doc/gawk.info'
+ The generated Info file for this Info file.
-With proper quoting, in the first example the setting of `RS' can be
-moved into the `BEGIN' rule.
+`doc/gawkinet.texi'
+ The Texinfo source file for *note (General Introduction)Top::
+ gawkinet, TCP/IP Internetworking with `gawk'. It should be
+ processed with TeX (via `texi2dvi' or `texi2pdf') to produce a
+ printed document and with `makeinfo' to produce an Info or HTML
+ file.
-
-File: gawk.info, Node: Cygwin, Next: MSYS, Prev: PC Using, Up: PC
Installation
+`doc/gawkinet.info'
+ The generated Info file for `TCP/IP Internetworking with `gawk''.
-B.3.1.5 Using `gawk' In The Cygwin Environment
-..............................................
+`doc/igawk.1'
+ The `troff' source for a manual page describing the `igawk'
+ program presented in *note Igawk Program::.
-`gawk' can be built and used "out of the box" under MS-Windows if you
-are using the Cygwin environment (http://www.cygwin.com). This
-environment provides an excellent simulation of Unix, using the GNU
-tools, such as Bash, the GNU Compiler Collection (GCC), GNU Make, and
-other GNU programs. Compilation and installation for Cygwin is the
-same as for a Unix system:
+`doc/Makefile.in'
+ The input file used during the configuration process to generate
+ the actual `Makefile' for creating the documentation.
- tar -xvpzf gawk-4.0.1.tar.gz
- cd gawk-4.0.1
- ./configure
- make
+`Makefile.am'
+`*/Makefile.am'
+ Files used by the GNU `automake' software for generating the
+ `Makefile.in' files used by `autoconf' and `configure'.
- When compared to GNU/Linux on the same system, the `configure' step
-on Cygwin takes considerably longer. However, it does finish, and then
-the `make' proceeds as usual.
+`Makefile.in'
+`aclocal.m4'
+`configh.in'
+`configure.ac'
+`configure'
+`custom.h'
+`missing_d/*'
+`m4/*'
+ These files and subdirectories are used when configuring `gawk'
+ for various Unix systems. They are explained in *note Unix
+ Installation::.
- NOTE: The `|&' operator and TCP/IP networking (*note TCP/IP
- Networking::) are fully supported in the Cygwin environment. This
- is not true for any other environment on MS-Windows.
+`po/*'
+ The `po' library contains message translations.
-
-File: gawk.info, Node: MSYS, Prev: Cygwin, Up: PC Installation
+`awklib/extract.awk'
+`awklib/Makefile.am'
+`awklib/Makefile.in'
+`awklib/eg/*'
+ The `awklib' directory contains a copy of `extract.awk' (*note
+ Extract Program::), which can be used to extract the sample
+ programs from the Texinfo source file for this Info file. It also
+ contains a `Makefile.in' file, which `configure' uses to generate
+ a `Makefile'. `Makefile.am' is used by GNU Automake to create
+ `Makefile.in'. The library functions from *note Library
+ Functions::, and the `igawk' program from *note Igawk Program::,
+ are included as ready-to-use files in the `gawk' distribution.
+ They are installed as part of the installation process. The rest
+ of the programs in this Info file are available in appropriate
+ subdirectories of `awklib/eg'.
-B.3.1.6 Using `gawk' In The MSYS Environment
-............................................
+`posix/*'
+ Files needed for building `gawk' on POSIX-compliant systems.
-In the MSYS environment under MS-Windows, `gawk' automatically uses
-binary mode for reading and writing files. Thus there is no need to
-use the `BINMODE' variable.
+`pc/*'
+ Files needed for building `gawk' under MS-Windows and OS/2 (*note
+ PC Installation::, for details).
- This can cause problems with other Unix-like components that have
-been ported to MS-Windows that expect `gawk' to do automatic
-translation of `"\r\n"', since it won't. Caveat Emptor!
+`vms/*'
+ Files needed for building `gawk' under VMS (*note VMS
+ Installation::, for details).
+
+`test/*'
+ A test suite for `gawk'. You can use `make check' from the
+ top-level `gawk' directory to run your version of `gawk' against
+ the test suite. If `gawk' successfully passes `make check', then
+ you can be confident of a successful port.
-File: gawk.info, Node: VMS Installation, Prev: PC Installation, Up:
Non-Unix Installation
+File: gawk.info, Node: Unix Installation, Next: Non-Unix Installation,
Prev: Gawk Distribution, Up: Installation
-B.3.2 How to Compile and Install `gawk' on VMS
-----------------------------------------------
+B.2 Compiling and Installing `gawk' on Unix-like Systems
+========================================================
-This node describes how to compile and install `gawk' under VMS. The
-older designation "VMS" is used throughout to refer to OpenVMS.
+Usually, you can compile and install `gawk' by typing only two
+commands. However, if you use an unusual system, you may need to
+configure `gawk' for your system yourself.
* Menu:
-* VMS Compilation:: How to compile `gawk' under VMS.
-* VMS Installation Details:: How to install `gawk' under VMS.
-* VMS Running:: How to run `gawk' under VMS.
-* VMS Old Gawk:: An old version comes with some VMS systems.
+* Quick Installation:: Compiling `gawk' under Unix.
+* Additional Configuration Options:: Other compile-time options.
+* Configuration Philosophy:: How it's all supposed to work.
-File: gawk.info, Node: VMS Compilation, Next: VMS Installation Details, Up:
VMS Installation
+File: gawk.info, Node: Quick Installation, Next: Additional Configuration
Options, Up: Unix Installation
-B.3.2.1 Compiling `gawk' on VMS
-...............................
+B.2.1 Compiling `gawk' for Unix-like Systems
+--------------------------------------------
-To compile `gawk' under VMS, there is a `DCL' command procedure that
-issues all the necessary `CC' and `LINK' commands. There is also a
-`Makefile' for use with the `MMS' utility. From the source directory,
-use either:
+The normal installation steps should work on all modern commercial
+Unix-derived systems, GNU/Linux, BSD-based systems, and the Cygwin
+environment for MS-Windows.
- $ @[.VMS]VMSBUILD.COM
+ After you have extracted the `gawk' distribution, `cd' to
+`gawk-4.0.1'. Like most GNU software, `gawk' is configured
+automatically for your system by running the `configure' program. This
+program is a Bourne shell script that is generated automatically using
+GNU `autoconf'. (The `autoconf' software is described fully starting
+with *note (Autoconf)Top:: autoconf,Autoconf--Generating Automatic
+Configuration Scripts.)
-or:
+ To configure `gawk', simply run `configure':
- $ MMS/DESCRIPTION=[.VMS]DESCRIP.MMS GAWK
+ sh ./configure
- Older versions of `gawk' could be built with VAX C or GNU C on
-VAX/VMS, as well as with DEC C, but that is no longer supported. DEC C
-(also briefly known as "Compaq C" and now known as "HP C," but referred
-to here as "DEC C") is required. Both `VMSBUILD.COM' and `DESCRIP.MMS'
-contain some obsolete support for the older compilers but are set up to
-use DEC C by default.
+ This produces a `Makefile' and `config.h' tailored to your system.
+The `config.h' file describes various facts about your system. You
+might want to edit the `Makefile' to change the `CFLAGS' variable,
+which controls the command-line options that are passed to the C
+compiler (such as optimization levels or compiling for debugging).
- `gawk' has been tested under Alpha/VMS 7.3-1 using Compaq C V6.4,
-and on Alpha/VMS 7.3, Alpha/VMS 7.3-2, and IA64/VMS 8.3.(1)
+ Alternatively, you can add your own values for most `make' variables
+on the command line, such as `CC' and `CFLAGS', when running
+`configure':
- ---------- Footnotes ----------
+ CC=cc CFLAGS=-g sh ./configure
- (1) The IA64 architecture is also known as "Itanium."
+See the file `INSTALL' in the `gawk' distribution for all the details.
-
-File: gawk.info, Node: VMS Installation Details, Next: VMS Running, Prev:
VMS Compilation, Up: VMS Installation
+ After you have run `configure' and possibly edited the `Makefile',
+type:
-B.3.2.2 Installing `gawk' on VMS
-................................
+ make
-To install `gawk', all you need is a "foreign" command, which is a
-`DCL' symbol whose value begins with a dollar sign. For example:
+Shortly thereafter, you should have an executable version of `gawk'.
+That's all there is to it! To verify that `gawk' is working properly,
+run `make check'. All of the tests should succeed. If these steps do
+not work, or if any of the tests fail, check the files in the
+`README_d' directory to see if you've found a known problem. If the
+failure is not described there, please send in a bug report (*note
+Bugs::).
- $ GAWK :== $disk1:[gnubin]GAWK
+
+File: gawk.info, Node: Additional Configuration Options, Next: Configuration
Philosophy, Prev: Quick Installation, Up: Unix Installation
-Substitute the actual location of `gawk.exe' for `$disk1:[gnubin]'. The
-symbol should be placed in the `login.com' of any user who wants to run
-`gawk', so that it is defined every time the user logs on.
-Alternatively, the symbol may be placed in the system-wide
-`sylogin.com' procedure, which allows all users to run `gawk'.
+B.2.2 Additional Configuration Options
+--------------------------------------
- Optionally, the help entry can be loaded into a VMS help library:
+There are several additional options you may use on the `configure'
+command line when compiling `gawk' from scratch, including:
- $ LIBRARY/HELP SYS$HELP:HELPLIB [.VMS]GAWK.HLP
+`--disable-lint'
+ Disable all lint checking within `gawk'. The `--lint' and
+ `--lint-old' options (*note Options::) are accepted, but silently
+ do nothing. Similarly, setting the `LINT' variable (*note
+ User-modified::) has no effect on the running `awk' program.
+
+ When used with GCC's automatic dead-code-elimination, this option
+ cuts almost 200K bytes off the size of the `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.
-(You may want to substitute a site-specific help library rather than
-the standard VMS library `HELPLIB'.) After loading the help text, the
-command:
+ Using this option will cause some of the tests in the test suite
+ to fail. This option may be removed at a later date.
- $ HELP GAWK
+`--disable-nls'
+ Disable all message-translation facilities. This is usually not
+ desirable, but it may bring you some slight performance
+ improvement.
-provides information about both the `gawk' implementation and the `awk'
-programming language.
+`--with-whiny-user-strftime'
+ Force use of the included version of the `strftime()' function for
+ deficient systems.
- The logical name `AWK_LIBRARY' can designate a default location for
-`awk' program files. For the `-f' option, if the specified file name
-has no device or directory path information in it, `gawk' looks in the
-current directory first, then in the directory specified by the
-translation of `AWK_LIBRARY' if the file is not found. If, after
-searching in both directories, the file still is not found, `gawk'
-appends the suffix `.awk' to the filename and retries the file search.
-If `AWK_LIBRARY' has no definition, a default value of `SYS$LIBRARY:'
-is used for it.
+ Use the command `./configure --help' to see the full list of options
+that `configure' supplies.
-File: gawk.info, Node: VMS Running, Next: VMS Old Gawk, Prev: VMS
Installation Details, Up: VMS Installation
+File: gawk.info, Node: Configuration Philosophy, Prev: Additional
Configuration Options, Up: Unix Installation
-B.3.2.3 Running `gawk' on VMS
-.............................
+B.2.3 The Configuration Process
+-------------------------------
-Command-line parsing and quoting conventions are significantly different
-on VMS, so examples in this Info file or from other sources often need
-minor changes. They _are_ minor though, and all `awk' programs should
-run correctly.
+This minor node is of interest only if you know something about using
+the C language and Unix-like operating systems.
- Here are a couple of trivial tests:
+ The source code for `gawk' generally attempts to adhere to formal
+standards wherever possible. This means that `gawk' uses library
+routines that are specified by the ISO C standard and by the POSIX
+operating system interface standard. The `gawk' source code requires
+using an ISO C compiler (the 1990 standard).
- $ gawk -- "BEGIN {print ""Hello, World!""}"
- $ gawk -"W" version
- ! could also be -"W version" or "-W version"
+ Many Unix systems do not support all of either the ISO or the POSIX
+standards. The `missing_d' subdirectory in the `gawk' distribution
+contains replacement versions of those functions that are most likely
+to be missing.
-Note that uppercase and mixed-case text must be quoted.
+ The `config.h' file that `configure' creates contains definitions
+that describe features of the particular operating system where you are
+attempting to compile `gawk'. The three things described by this file
+are: what header files are available, so that they can be correctly
+included, what (supposedly) standard functions are actually available
+in your C libraries, and various miscellaneous facts about your
+operating system. For example, there may not be an `st_blksize'
+element in the `stat' structure. In this case, `HAVE_ST_BLKSIZE' is
+undefined.
- The VMS port of `gawk' includes a `DCL'-style interface in addition
-to the original shell-style interface (see the help entry for details).
-One side effect of dual command-line parsing is that if there is only a
-single parameter (as in the quoted string program above), the command
-becomes ambiguous. To work around this, the normally optional `--'
-flag is required to force Unix-style parsing rather than `DCL' parsing.
-If any other dash-type options (or multiple parameters such as data
-files to process) are present, there is no ambiguity and `--' can be
-omitted.
+ It is possible for your C compiler to lie to `configure'. It may do
+so by not exiting with an error when a library function is not
+available. To get around this, edit the file `custom.h'. Use an
+`#ifdef' that is appropriate for your system, and either `#define' any
+constants that `configure' should have defined but didn't, or `#undef'
+any constants that `configure' defined and should not have. `custom.h'
+is automatically included by `config.h'.
- The default search path, when looking for `awk' program files
-specified by the `-f' option, is `"SYS$DISK:[],AWK_LIBRARY:"'. The
-logical name `AWKPATH' can be used to override this default. The format
-of `AWKPATH' is a comma-separated list of directory specifications.
-When defining it, the value should be quoted so that it retains a single
-translation and not a multitranslation `RMS' searchlist.
+ It is also possible that the `configure' program generated by
+`autoconf' will not work on your system in some other fashion. If you
+do have a problem, the file `configure.ac' is the input for `autoconf'.
+You may be able to change this file and generate a new version of
+`configure' that works on your system (*note Bugs::, for information on
+how to report problems in configuring `gawk'). The same mechanism may
+be used to send in updates to `configure.ac' and/or `custom.h'.
-File: gawk.info, Node: VMS Old Gawk, Prev: VMS Running, Up: VMS Installation
+File: gawk.info, Node: Non-Unix Installation, Next: Bugs, Prev: Unix
Installation, Up: Installation
-B.3.2.4 Some VMS Systems Have An Old Version of `gawk'
-......................................................
+B.3 Installation on Other Operating Systems
+===========================================
-Some versions of VMS have an old version of `gawk'. To access it,
-define a symbol, as follows:
+This minor node describes how to install `gawk' on various non-Unix
+systems.
- $ gawk :== $sys$common:[syshlp.examples.tcpip.snmp]gawk.exe
+* Menu:
- This is apparently version 2.15.6, which is extremely old. We
-recommend compiling and using the current version.
+* PC Installation:: Installing and Compiling `gawk' on
+ MS-DOS and OS/2.
+* VMS Installation:: Installing `gawk' on VMS.
-File: gawk.info, Node: Bugs, Next: Other Versions, Prev: Non-Unix
Installation, Up: Installation
+File: gawk.info, Node: PC Installation, Next: VMS Installation, Up:
Non-Unix Installation
-B.4 Reporting Problems and Bugs
-===============================
+B.3.1 Installation on PC Operating Systems
+------------------------------------------
- There is nothing more dangerous than a bored archeologist.
- The Hitchhiker's Guide to the Galaxy
+This minor node covers installation and usage of `gawk' on x86 machines
+running MS-DOS, any version of MS-Windows, or OS/2. In this minor
+node, the term "Windows32" refers to any of Microsoft
+Windows-95/98/ME/NT/2000/XP/Vista/7.
- If you have problems with `gawk' or think that you have found a bug,
-please report it to the developers; we cannot promise to do anything
-but we might well want to fix it.
+ The limitations of MS-DOS (and MS-DOS shells under Windows32 or
+OS/2) has meant that various "DOS extenders" are often used with
+programs such as `gawk'. The varying capabilities of Microsoft Windows
+3.1 and Windows32 can add to the confusion. For an overview of the
+considerations, please refer to `README_d/README.pc' in the
+distribution.
- Before reporting a bug, make sure you have actually found a real bug.
-Carefully reread the documentation and see if it really says you can do
-what you're trying to do. If it's not clear whether you should be able
-to do something or not, report that too; it's a bug in the
-documentation!
+* Menu:
- Before reporting a bug or trying to fix it yourself, try to isolate
-it to the smallest possible `awk' program and input data file that
-reproduces the problem. Then send us the program and data file, some
-idea of what kind of Unix system you're using, the compiler you used to
-compile `gawk', and the exact results `gawk' gave you. Also say what
-you expected to occur; this helps us decide whether the problem is
-really in the documentation.
+* PC Binary Installation:: Installing a prepared distribution.
+* PC Compiling:: Compiling `gawk' for MS-DOS,
+ Windows32, and OS/2.
+* PC Testing:: Testing `gawk' on PC systems.
+* PC Using:: Running `gawk' on MS-DOS, Windows32
+ and OS/2.
+* Cygwin:: Building and running `gawk' for
+ Cygwin.
+* MSYS:: Using `gawk' In The MSYS Environment.
- Please include the version number of `gawk' you are using. You can
-get this information with the command `gawk --version'.
+
+File: gawk.info, Node: PC Binary Installation, Next: PC Compiling, Up: PC
Installation
- Once you have a precise problem, send email to <address@hidden>.
+B.3.1.1 Installing a Prepared Distribution for PC Systems
+.........................................................
- Using this address automatically sends a copy of your mail to me.
-If necessary, I can be reached directly at <address@hidden>. The
-bug reporting address is preferred since the email list is archived at
-the GNU Project. _All email should be in English, since that is my
-native language._
+If you have received a binary distribution prepared by the MS-DOS
+maintainers, then `gawk' and the necessary support files appear under
+the `gnu' directory, with executables in `gnu/bin', libraries in
+`gnu/lib/awk', and manual pages under `gnu/man'. This is designed for
+easy installation to a `/gnu' directory on your drive--however, the
+files can be installed anywhere provided `AWKPATH' is set properly.
+Regardless of the installation directory, the first line of `igawk.cmd'
+and `igawk.bat' (in `gnu/bin') may need to be edited.
- CAUTION: Do _not_ try to report bugs in `gawk' by posting to the
- Usenet/Internet newsgroup `comp.lang.awk'. While the `gawk'
- developers do occasionally read this newsgroup, there is no
- guarantee that we will see your posting. The steps described
- above are the official recognized ways for reporting bugs. Really.
+ The binary distribution contains a separate file describing the
+contents. In particular, it may include more than one version of the
+`gawk' executable.
- NOTE: Many distributions of GNU/Linux and the various BSD-based
- operating systems have their own bug reporting systems. If you
- report a bug using your distribution's bug reporting system,
- _please_ also send a copy to <address@hidden>.
+ OS/2 (32 bit, EMX) binary distributions are prepared for the `/usr'
+directory of your preferred drive. Set `UNIXROOT' to your installation
+drive (e.g., `e:') if you want to install `gawk' onto another drive
+than the hardcoded default `c:'. Executables appear in `/usr/bin',
+libraries under `/usr/share/awk', manual pages under `/usr/man',
+Texinfo documentation under `/usr/info', and NLS files under
+`/usr/share/locale'. Note that the files can be installed anywhere
+provided `AWKPATH' is set properly.
- This is for two reasons. First, while some distributions forward
- bug reports "upstream" to the GNU mailing list, many don't, so
- there is a good chance that the `gawk' maintainer won't even see
- the bug report! Second, mail to the GNU list is archived, and
- having everything at the GNU project keeps things self-contained
- and not dependant on other web sites.
+ If you already have a file `/usr/info/dir' from another package _do
+not overwrite it!_ Instead enter the following commands at your prompt
+(replace `x:' by your installation drive):
- Non-bug suggestions are always welcome as well. If you have
-questions about things that are unclear in the documentation or are
-just obscure features, ask me; I will try to help you out, although I
-may not have the time to fix the problem. You can send me electronic
-mail at the Internet address noted previously.
+ install-info --info-dir=x:/usr/info x:/usr/info/gawk.info
+ install-info --info-dir=x:/usr/info x:/usr/info/gawkinet.info
- If you find bugs in one of the non-Unix ports of `gawk', please send
-an electronic mail message to the person who maintains that port. They
-are named in the following list, as well as in the `README' file in the
-`gawk' distribution. Information in the `README' file should be
-considered authoritative if it conflicts with this Info file.
+ The binary distribution may contain a separate file containing
+additional or more detailed installation instructions.
- The people maintaining the non-Unix ports of `gawk' are as follows:
+
+File: gawk.info, Node: PC Compiling, Next: PC Testing, Prev: PC Binary
Installation, Up: PC Installation
-MS-DOS with DJGPP Scott Deifik, <address@hidden>.
-MS-Windows with MINGW Eli Zaretskii, <address@hidden>.
-OS/2 Andreas Buening, <address@hidden>.
-VMS Pat Rankin, <address@hidden>
-z/OS (OS/390) Dave Pitts, <address@hidden>.
+B.3.1.2 Compiling `gawk' for PC Operating Systems
+.................................................
- If your bug is also reproducible under Unix, please send a copy of
-your report to the <address@hidden> email list as well.
+`gawk' can be compiled for MS-DOS, Windows32, and OS/2 using the GNU
+development tools from DJ Delorie (DJGPP: MS-DOS only) or Eberhard
+Mattes (EMX: MS-DOS, Windows32 and OS/2). The file
+`README_d/README.pc' in the `gawk' distribution contains additional
+notes, and `pc/Makefile' contains important information on compilation
+options.
-
-File: gawk.info, Node: Other Versions, Prev: Bugs, Up: Installation
+ To build `gawk' for MS-DOS and Windows32, copy the files in the `pc'
+directory (_except_ for `ChangeLog') to the directory with the rest of
+the `gawk' sources, then invoke `make' with the appropriate target name
+as an argument to build `gawk'. The `Makefile' copied from the `pc'
+directory contains a configuration section with comments and may need
+to be edited in order to work with your `make' utility.
-B.5 Other Freely Available `awk' Implementations
-================================================
+ The `Makefile' supports a number of targets for building various
+MS-DOS and Windows32 versions. A list of targets is printed if the
+`make' command is given without a target. As an example, to build
+`gawk' using the DJGPP tools, enter `make djgpp'. (The DJGPP tools
+needed for the build may be found at
+`ftp://ftp.delorie.com/pub/djgpp/current/v2gnu/'.) To build a native
+MS-Windows binary of `gawk', type `make mingw32'.
+
+ The 32 bit EMX version of `gawk' works "out of the box" under OS/2.
+However, it is highly recommended to use GCC 2.95.3 for the compilation.
+In principle, it is possible to compile `gawk' the following way:
+
+ $ ./configure
+ $ make
- It's kind of fun to put comments like this in your awk code.
- `// Do C++ comments work? answer: yes! of course'
- Michael Brennan
+ This is not recommended, though. To get an OMF executable you should
+use the following commands at your `sh' prompt:
- There are a number of other freely available `awk' implementations.
-This minor node briefly describes where to get them:
+ $ CFLAGS="-O2 -Zomf -Zmt"
+ $ export CFLAGS
+ $ LDFLAGS="-s -Zcrtdll -Zlinker /exepack:2 -Zlinker /pm:vio -Zstack
0x6000"
+ $ export LDFLAGS
+ $ RANLIB="echo"
+ $ export RANLIB
+ $ ./configure --prefix=c:/usr
+ $ make AR=emxomfar
-Unix `awk'
- Brian Kernighan, one of the original designers of Unix `awk', has
- made his implementation of `awk' freely available. You can
- retrieve this version via the World Wide Web from his home page
- (http://www.cs.princeton.edu/~bwk). It is available in several
- archive formats:
+ These are just suggestions for use with GCC 2.x. You may use any
+other set of (self-consistent) environment variables and compiler flags.
- Shell archive
- `http://www.cs.princeton.edu/~bwk/btl.mirror/awk.shar'
+ If you use GCC 2.95 it is recommended to use also:
- Compressed `tar' file
- `http://www.cs.princeton.edu/~bwk/btl.mirror/awk.tar.gz'
+ $ LIBS="-lgcc"
+ $ export LIBS
- Zip file
- `http://www.cs.princeton.edu/~bwk/btl.mirror/awk.zip'
+ You can also get an `a.out' executable if you prefer:
- This version requires an ISO C (1990 standard) compiler; the C
- compiler from GCC (the GNU Compiler Collection) works quite nicely.
+ $ CFLAGS="-O2 -Zmt"
+ $ export CFLAGS
+ $ LDFLAGS="-s -Zstack 0x6000"
+ $ LIBS="-lgcc"
+ $ unset RANLIB
+ $ ./configure --prefix=c:/usr
+ $ make
- *Note Common Extensions::, for a list of extensions in this `awk'
- that are not in POSIX `awk'.
+ NOTE: Compilation of `a.out' executables also works with GCC 3.2.
+ Versions later than GCC 3.2 have not been tested successfully.
-`mawk'
- Michael Brennan wrote an independent implementation of `awk',
- called `mawk'. It is available under the GPL (*note Copying::),
- just as `gawk' is.
+ `make install' works as expected with the EMX build.
- The original distribution site for the `mawk' source code no
- longer has it. A copy is available at
- `http://www.skeeve.com/gawk/mawk1.3.3.tar.gz'.
+ NOTE: Ancient OS/2 ports of GNU `make' are not able to handle the
+ Makefiles of this package. If you encounter any problems with
+ `make', try GNU Make 3.79.1 or later versions. You should find
+ the latest version on `ftp://hobbes.nmsu.edu/pub/os2/'.
- In 2009, Thomas Dickey took on `mawk' maintenance. Basic
- information is available on the project's web page
- (http://www.invisible-island.net/mawk/mawk.html). The download
- URL is `http://invisible-island.net/datafiles/release/mawk.tar.gz'.
+
+File: gawk.info, Node: PC Testing, Next: PC Using, Prev: PC Compiling, Up:
PC Installation
- Once you have it, `gunzip' may be used to decompress this file.
- Installation is similar to `gawk''s (*note Unix Installation::).
+B.3.1.3 Testing `gawk' on PC Operating Systems
+..............................................
- *Note Common Extensions::, for a list of extensions in `mawk' that
- are not in POSIX `awk'.
+Using `make' to run the standard tests and to install `gawk' requires
+additional Unix-like tools, including `sh', `sed', and `cp'. In order
+to run the tests, the `test/*.ok' files may need to be converted so
+that they have the usual MS-DOS-style end-of-line markers.
+Alternatively, run `make check CMP="diff -a"' to use GNU `diff' in text
+mode instead of `cmp' to compare the resulting files.
-`awka'
- Written by Andrew Sumner, `awka' translates `awk' programs into C,
- compiles them, and links them with a library of functions that
- provides the core `awk' functionality. It also has a number of
- extensions.
+ Most of the tests work properly with Stewartson's shell along with
+the companion utilities or appropriate GNU utilities. However, some
+editing of `test/Makefile' is required. It is recommended that you copy
+the file `pc/Makefile.tst' over the file `test/Makefile' as a
+replacement. Details can be found in `README_d/README.pc' and in the
+file `pc/Makefile.tst'.
- The `awk' translator is released under the GPL, and the library is
- under the LGPL.
+ On OS/2 the `pid' test fails because `spawnl()' is used instead of
+`fork()'/`execl()' to start child processes. Also the `mbfw1' and
+`mbprintf1' tests fail because the needed multibyte functionality is
+not available.
- To get `awka', go to `http://sourceforge.net/projects/awka'.
+
+File: gawk.info, Node: PC Using, Next: Cygwin, Prev: PC Testing, Up: PC
Installation
- The project seems to be frozen; no new code changes have been made
- since approximately 2003.
+B.3.1.4 Using `gawk' on PC Operating Systems
+............................................
-`pawk'
- Nelson H.F. Beebe at the University of Utah has modified Brian
- Kernighan's `awk' to provide timing and profiling information. It
- is different from `gawk' with the `--profile' option. (*note
- Profiling::), in that it uses CPU-based profiling, not line-count
- profiling. You may find it at either
- `ftp://ftp.math.utah.edu/pub/pawk/pawk-20030606.tar.gz' or
- `http://www.math.utah.edu/pub/pawk/pawk-20030606.tar.gz'.
+With the exception of the Cygwin environment, the `|&' operator and
+TCP/IP networking (*note TCP/IP Networking::) are not supported for
+MS-DOS or MS-Windows. EMX (OS/2 only) does support at least the `|&'
+operator.
-Busybox Awk
- Busybox is a GPL-licensed program providing small versions of many
- applications within a single executable. It is aimed at embedded
- systems. It includes a full implementation of POSIX `awk'. When
- building it, be careful not to do `make install' as it will
- overwrite copies of other applications in your `/usr/local/bin'.
- For more information, see the project's home page
- (http://busybox.net).
+ The MS-DOS and MS-Windows versions of `gawk' search for program
+files as described in *note AWKPATH Variable::. However, semicolons
+(rather than colons) separate elements in the `AWKPATH' variable. If
+`AWKPATH' is not set or is empty, then the default search path for
+MS-Windows and MS-DOS versions is `".;c:/lib/awk;c:/gnu/lib/awk"'.
-The OpenSolaris POSIX `awk'
- The version of `awk' in `/usr/xpg4/bin' on Solaris is more-or-less
- POSIX-compliant. It is based on the `awk' from Mortice Kern
- Systems for PCs. The source code can be downloaded from the
- OpenSolaris web site (http://www.opensolaris.org). This author
- was able to make it compile and work under GNU/Linux with 1-2
- hours of work. Making it more generally portable (using GNU
- Autoconf and/or Automake) would take more work, and this has not
- been done, at least to our knowledge.
+ The search path for OS/2 (32 bit, EMX) is determined by the prefix
+directory (most likely `/usr' or `c:/usr') that has been specified as
+an option of the `configure' script like it is the case for the Unix
+versions. If `c:/usr' is the prefix directory then the default search
+path contains `.' and `c:/usr/share/awk'. Additionally, to support
+binary distributions of `gawk' for OS/2 systems whose drive `c:' might
+not support long file names or might not exist at all, there is a
+special environment variable. If `UNIXROOT' specifies a drive then
+this specific drive is also searched for program files. E.g., if
+`UNIXROOT' is set to `e:' the complete default search path is
+`".;c:/usr/share/awk;e:/usr/share/awk"'.
-`jawk'
- This is an interpreter for `awk' written in Java. It claims to be
- a full interpreter, although because it uses Java facilities for
- I/O and for regexp matching, the language it supports is different
- from POSIX `awk'. More information is available on the project's
- home page (http://jawk.sourceforge.net).
+ An `sh'-like shell (as opposed to `command.com' under MS-DOS or
+`cmd.exe' under MS-Windows or OS/2) may be useful for `awk' programming.
+The DJGPP collection of tools includes an MS-DOS port of Bash, and
+several shells are available for OS/2, including `ksh'.
-Libmawk
- This is an embeddable `awk' interpreter derived from `mawk'. For
- more information see `http://repo.hu/projects/libmawk/'.
+ Under MS-Windows, OS/2 and MS-DOS, `gawk' (and many other text
+programs) silently translate end-of-line `"\r\n"' to `"\n"' on input
+and `"\n"' to `"\r\n"' on output. A special `BINMODE' variable
+(c.e.) allows control over these translations and is interpreted as
+follows:
-QSE Awk
- This is an embeddable `awk' interpreter. For more information see
- `http://code.google.com/p/qse/' and `http://awk.info/?tools/qse'.
+ * If `BINMODE' is `"r"', or one, then binary mode is set on read
+ (i.e., no translations on reads).
-`QTawk'
- This is an independent implementation of `awk' distributed under
- the GPL. It has a large number of extensions over standard `awk'
- and may not be 100% syntactically compatible with it. See
- `http://www.quiktrim.org/QTawk.html' for more information,
- including the manual and a download link.
+ * If `BINMODE' is `"w"', or two, then binary mode is set on write
+ (i.e., no translations on writes).
-`xgawk'
- XML `gawk'. This is a fork of the `gawk' 3.1.6 source base to
- support processing XML files. It has a number of interesting
- extensions which should one day be integrated into the main `gawk'
- code base. For more information, see the XMLgawk project web site
- (http://xmlgawk.sourceforge.net).
+ * If `BINMODE' is `"rw"' or `"wr"' or three, binary mode is set for
+ both read and write.
+ * `BINMODE=NON-NULL-STRING' is the same as `BINMODE=3' (i.e., no
+ translations on reads or writes). However, `gawk' issues a warning
+ message if the string is not one of `"rw"' or `"wr"'.
-
-File: gawk.info, Node: Notes, Next: Basic Concepts, Prev: Installation,
Up: Top
+The modes for standard input and standard output are set one time only
+(after the command line is read, but before processing any of the `awk'
+program). Setting `BINMODE' for standard input or standard output is
+accomplished by using an appropriate `-v BINMODE=N' option on the
+command line. `BINMODE' is set at the time a file or pipe is opened
+and cannot be changed mid-stream.
-Appendix C Implementation Notes
-*******************************
+ The name `BINMODE' was chosen to match `mawk' (*note Other
+Versions::). `mawk' and `gawk' handle `BINMODE' similarly; however,
+`mawk' adds a `-W BINMODE=N' option and an environment variable that
+can set `BINMODE', `RS', and `ORS'. The files `binmode[1-3].awk'
+(under `gnu/lib/awk' in some of the prepared distributions) have been
+chosen to match `mawk''s `-W BINMODE=N' option. These can be changed
+or discarded; in particular, the setting of `RS' giving the fewest
+"surprises" is open to debate. `mawk' uses `RS = "\r\n"' if binary
+mode is set on read, which is appropriate for files with the
+MS-DOS-style end-of-line.
-This appendix contains information mainly of interest to implementers
-and maintainers of `gawk'. Everything in it applies specifically to
-`gawk' and not to other implementations.
+ To illustrate, the following examples set binary mode on writes for
+standard output and other files, and set `ORS' as the "usual"
+MS-DOS-style end-of-line:
-* Menu:
+ gawk -v BINMODE=2 -v ORS="\r\n" ...
-* Compatibility Mode:: How to disable certain `gawk'
- extensions.
-* Additions:: Making Additions To `gawk'.
-* Dynamic Extensions:: Adding new built-in functions to
- `gawk'.
-* Future Extensions:: New features that may be implemented one day.
+or:
-
-File: gawk.info, Node: Compatibility Mode, Next: Additions, Up: Notes
+ gawk -v BINMODE=w -f binmode2.awk ...
-C.1 Downward Compatibility and Debugging
-========================================
+These give the same result as the `-W BINMODE=2' option in `mawk'. The
+following changes the record separator to `"\r\n"' and sets binary mode
+on reads, but does not affect the mode on standard input:
-*Note POSIX/GNU::, for a summary of the GNU extensions to the `awk'
-language and program. All of these features can be turned off by
-invoking `gawk' with the `--traditional' option or with the `--posix'
-option.
+ gawk -v RS="\r\n" --source "BEGIN { BINMODE = 1 }" ...
- If `gawk' is compiled for debugging with `-DDEBUG', then there is
-one more option available on the command line:
+or:
-`-Y'
-`--parsedebug'
- Prints out the parse stack information as the program is being
- parsed.
+ gawk -f binmode1.awk ...
- This option is intended only for serious `gawk' developers and not
-for the casual user. It probably has not even been compiled into your
-version of `gawk', since it slows down execution.
+With proper quoting, in the first example the setting of `RS' can be
+moved into the `BEGIN' rule.
-File: gawk.info, Node: Additions, Next: Dynamic Extensions, Prev:
Compatibility Mode, Up: Notes
+File: gawk.info, Node: Cygwin, Next: MSYS, Prev: PC Using, Up: PC
Installation
+
+B.3.1.5 Using `gawk' In The Cygwin Environment
+..............................................
+
+`gawk' can be built and used "out of the box" under MS-Windows if you
+are using the Cygwin environment (http://www.cygwin.com). This
+environment provides an excellent simulation of Unix, using the GNU
+tools, such as Bash, the GNU Compiler Collection (GCC), GNU Make, and
+other GNU programs. Compilation and installation for Cygwin is the
+same as for a Unix system:
-C.2 Making Additions to `gawk'
-==============================
+ tar -xvpzf gawk-4.0.1.tar.gz
+ cd gawk-4.0.1
+ ./configure
+ make
-If you find that you want to enhance `gawk' in a significant fashion,
-you are perfectly free to do so. That is the point of having free
-software; the source code is available and you are free to change it as
-you want (*note Copying::).
+ When compared to GNU/Linux on the same system, the `configure' step
+on Cygwin takes considerably longer. However, it does finish, and then
+the `make' proceeds as usual.
- This minor node discusses the ways you might want to change `gawk'
-as well as any considerations you should bear in mind.
+ NOTE: The `|&' operator and TCP/IP networking (*note TCP/IP
+ Networking::) are fully supported in the Cygwin environment. This
+ is not true for any other environment on MS-Windows.
-* Menu:
+
+File: gawk.info, Node: MSYS, Prev: Cygwin, Up: PC Installation
-* Accessing The Source:: Accessing the Git repository.
-* Adding Code:: Adding code to the main body of
- `gawk'.
-* New Ports:: Porting `gawk' to a new operating
- system.
+B.3.1.6 Using `gawk' In The MSYS Environment
+............................................
-
-File: gawk.info, Node: Accessing The Source, Next: Adding Code, Up:
Additions
+In the MSYS environment under MS-Windows, `gawk' automatically uses
+binary mode for reading and writing files. Thus there is no need to
+use the `BINMODE' variable.
-C.2.1 Accessing The `gawk' Git Repository
------------------------------------------
+ This can cause problems with other Unix-like components that have
+been ported to MS-Windows that expect `gawk' to do automatic
+translation of `"\r\n"', since it won't. Caveat Emptor!
-As `gawk' is Free Software, the source code is always available. *note
-Gawk Distribution::, describes how to get and build the formal,
-released versions of `gawk'.
+
+File: gawk.info, Node: VMS Installation, Prev: PC Installation, Up:
Non-Unix Installation
- However, if you want to modify `gawk' and contribute back your
-changes, you will probably wish to work with the development version.
-To do so, you will need to access the `gawk' source code repository.
-The code is maintained using the Git distributed version control system
-(http://git-scm.com/). You will need to install it if your system
-doesn't have it. Once you have done so, use the command:
+B.3.2 How to Compile and Install `gawk' on VMS
+----------------------------------------------
- git clone git://git.savannah.gnu.org/gawk.git
+This node describes how to compile and install `gawk' under VMS. The
+older designation "VMS" is used throughout to refer to OpenVMS.
-This will clone the `gawk' repository. If you are behind a firewall
-that will not allow you to use the Git native protocol, you can still
-access the repository using:
+* Menu:
- git clone http://git.savannah.gnu.org/r/gawk.git
+* VMS Compilation:: How to compile `gawk' under VMS.
+* VMS Installation Details:: How to install `gawk' under VMS.
+* VMS Running:: How to run `gawk' under VMS.
+* VMS Old Gawk:: An old version comes with some VMS systems.
- Once you have made changes, you can use `git diff' to produce a
-patch, and send that to the `gawk' maintainer; see *note Bugs:: for how
-to do that.
+
+File: gawk.info, Node: VMS Compilation, Next: VMS Installation Details, Up:
VMS Installation
- Finally, if you cannot install Git (e.g., if it hasn't been ported
-yet to your operating system), you can use the Git-CVS gateway to check
-out a copy using CVS, as follows:
+B.3.2.1 Compiling `gawk' on VMS
+...............................
- cvs -d:pserver:address@hidden:/gawk.git co -d gawk master
+To compile `gawk' under VMS, there is a `DCL' command procedure that
+issues all the necessary `CC' and `LINK' commands. There is also a
+`Makefile' for use with the `MMS' utility. From the source directory,
+use either:
-
-File: gawk.info, Node: Adding Code, Next: New Ports, Prev: Accessing The
Source, Up: Additions
+ $ @[.VMS]VMSBUILD.COM
-C.2.2 Adding New Features
--------------------------
+or:
-You are free to add any new features you like to `gawk'. However, if
-you want your changes to be incorporated into the `gawk' distribution,
-there are several steps that you need to take in order to make it
-possible to include your changes:
+ $ MMS/DESCRIPTION=[.VMS]DESCRIP.MMS GAWK
- 1. Before building the new feature into `gawk' itself, consider
- writing it as an extension module (*note Dynamic Extensions::).
- If that's not possible, continue with the rest of the steps in
- this list.
+ Older versions of `gawk' could be built with VAX C or GNU C on
+VAX/VMS, as well as with DEC C, but that is no longer supported. DEC C
+(also briefly known as "Compaq C" and now known as "HP C," but referred
+to here as "DEC C") is required. Both `VMSBUILD.COM' and `DESCRIP.MMS'
+contain some obsolete support for the older compilers but are set up to
+use DEC C by default.
- 2. Be prepared to sign the appropriate paperwork. In order for the
- FSF to distribute your changes, you must either place those
- changes in the public domain and submit a signed statement to that
- effect, or assign the copyright in your changes to the FSF. Both
- of these actions are easy to do and _many_ people have done so
- already. If you have questions, please contact me (*note Bugs::),
- or <address@hidden>.
+ `gawk' has been tested under Alpha/VMS 7.3-1 using Compaq C V6.4,
+and on Alpha/VMS 7.3, Alpha/VMS 7.3-2, and IA64/VMS 8.3.(1)
- 3. Get the latest version. It is much easier for me to integrate
- changes if they are relative to the most recent distributed
- version of `gawk'. If your version of `gawk' is very old, I may
- not be able to integrate them at all. (*Note Getting::, for
- information on getting the latest version of `gawk'.)
+ ---------- Footnotes ----------
- 4. See *note (Version)Top:: standards, GNU Coding Standards. This
- document describes how GNU software should be written. If you
- haven't read it, please do so, preferably _before_ starting to
- modify `gawk'. (The `GNU Coding Standards' are available from the
- GNU Project's web site
- (http://www.gnu.org/prep/standards_toc.html). Texinfo, Info, and
- DVI versions are also available.)
+ (1) The IA64 architecture is also known as "Itanium."
- 5. Use the `gawk' coding style. The C code for `gawk' follows the
- instructions in the `GNU Coding Standards', with minor exceptions.
- The code is formatted using the traditional "K&R" style,
- particularly as regards to the placement of braces and the use of
- TABs. In brief, the coding rules for `gawk' are as follows:
+
+File: gawk.info, Node: VMS Installation Details, Next: VMS Running, Prev:
VMS Compilation, Up: VMS Installation
- * Use ANSI/ISO style (prototype) function headers when defining
- functions.
+B.3.2.2 Installing `gawk' on VMS
+................................
- * Put the name of the function at the beginning of its own line.
+To install `gawk', all you need is a "foreign" command, which is a
+`DCL' symbol whose value begins with a dollar sign. For example:
- * Put the return type of the function, even if it is `int', on
- the line above the line with the name and arguments of the
- function.
+ $ GAWK :== $disk1:[gnubin]GAWK
- * Put spaces around parentheses used in control structures
- (`if', `while', `for', `do', `switch', and `return').
+Substitute the actual location of `gawk.exe' for `$disk1:[gnubin]'. The
+symbol should be placed in the `login.com' of any user who wants to run
+`gawk', so that it is defined every time the user logs on.
+Alternatively, the symbol may be placed in the system-wide
+`sylogin.com' procedure, which allows all users to run `gawk'.
- * Do not put spaces in front of parentheses used in function
- calls.
+ Optionally, the help entry can be loaded into a VMS help library:
- * Put spaces around all C operators and after commas in
- function calls.
+ $ LIBRARY/HELP SYS$HELP:HELPLIB [.VMS]GAWK.HLP
- * Do not use the comma operator to produce multiple side
- effects, except in `for' loop initialization and increment
- parts, and in macro bodies.
+(You may want to substitute a site-specific help library rather than
+the standard VMS library `HELPLIB'.) After loading the help text, the
+command:
- * Use real TABs for indenting, not spaces.
+ $ HELP GAWK
- * Use the "K&R" brace layout style.
+provides information about both the `gawk' implementation and the `awk'
+programming language.
- * Use comparisons against `NULL' and `'\0'' in the conditions of
- `if', `while', and `for' statements, as well as in the `case's
- of `switch' statements, instead of just the plain pointer or
- character value.
+ The logical name `AWK_LIBRARY' can designate a default location for
+`awk' program files. For the `-f' option, if the specified file name
+has no device or directory path information in it, `gawk' looks in the
+current directory first, then in the directory specified by the
+translation of `AWK_LIBRARY' if the file is not found. If, after
+searching in both directories, the file still is not found, `gawk'
+appends the suffix `.awk' to the filename and retries the file search.
+If `AWK_LIBRARY' has no definition, a default value of `SYS$LIBRARY:'
+is used for it.
- * Use the `TRUE', `FALSE' and `NULL' symbolic constants and the
- character constant `'\0'' where appropriate, instead of `1'
- and `0'.
+
+File: gawk.info, Node: VMS Running, Next: VMS Old Gawk, Prev: VMS
Installation Details, Up: VMS Installation
- * Provide one-line descriptive comments for each function.
+B.3.2.3 Running `gawk' on VMS
+.............................
- * Do not use the `alloca()' function for allocating memory off
- the stack. Its use causes more portability trouble than is
- worth the minor benefit of not having to free the storage.
- Instead, use `malloc()' and `free()'.
+Command-line parsing and quoting conventions are significantly different
+on VMS, so examples in this Info file or from other sources often need
+minor changes. They _are_ minor though, and all `awk' programs should
+run correctly.
- * Do not use comparisons of the form `! strcmp(a, b)' or
- similar. As Henry Spencer once said, "`strcmp()' is not a
- boolean!" Instead, use `strcmp(a, b) == 0'.
+ Here are a couple of trivial tests:
- * If adding new bit flag values, use explicit hexadecimal
- constants (`0x001', `0x002', `0x004', and son on) instead of
- shifting one left by successive amounts (`(1<<0)', `(1<<1)',
- and so on).
+ $ gawk -- "BEGIN {print ""Hello, World!""}"
+ $ gawk -"W" version
+ ! could also be -"W version" or "-W version"
- NOTE: If I have to reformat your code to follow the coding
- style used in `gawk', I may not bother to integrate your
- changes at all.
+Note that uppercase and mixed-case text must be quoted.
- 6. Update the documentation. Along with your new code, please supply
- new sections and/or chapters for this Info file. If at all
- possible, please use real Texinfo, instead of just supplying
- unformatted ASCII text (although even that is better than no
- documentation at all). Conventions to be followed in `GAWK:
- Effective AWK Programming' are provided after the address@hidden' at the
- end of the Texinfo source file. If possible, please update the
- `man' page as well.
+ The VMS port of `gawk' includes a `DCL'-style interface in addition
+to the original shell-style interface (see the help entry for details).
+One side effect of dual command-line parsing is that if there is only a
+single parameter (as in the quoted string program above), the command
+becomes ambiguous. To work around this, the normally optional `--'
+flag is required to force Unix-style parsing rather than `DCL' parsing.
+If any other dash-type options (or multiple parameters such as data
+files to process) are present, there is no ambiguity and `--' can be
+omitted.
- You will also have to sign paperwork for your documentation
- changes.
+ The default search path, when looking for `awk' program files
+specified by the `-f' option, is `"SYS$DISK:[],AWK_LIBRARY:"'. The
+logical name `AWKPATH' can be used to override this default. The format
+of `AWKPATH' is a comma-separated list of directory specifications.
+When defining it, the value should be quoted so that it retains a single
+translation and not a multitranslation `RMS' searchlist.
- 7. Submit changes as unified diffs. Use `diff -u -r -N' to compare
- the original `gawk' source tree with your version. I recommend
- using the GNU version of `diff'. Send the output produced by
- either run of `diff' to me when you submit your changes. (*Note
- Bugs::, for the electronic mail information.)
+
+File: gawk.info, Node: VMS Old Gawk, Prev: VMS Running, Up: VMS Installation
- Using this format makes it easy for me to apply your changes to the
- master version of the `gawk' source code (using `patch'). If I
- have to apply the changes manually, using a text editor, I may not
- do so, particularly if there are lots of changes.
+B.3.2.4 Some VMS Systems Have An Old Version of `gawk'
+......................................................
- 8. Include an entry for the `ChangeLog' file with your submission.
- This helps further minimize the amount of work I have to do,
- making it easier for me to accept patches.
+Some versions of VMS have an old version of `gawk'. To access it,
+define a symbol, as follows:
- Although this sounds like a lot of work, please remember that while
-you may write the new code, I have to maintain it and support it. If it
-isn't possible for me to do that with a minimum of extra work, then I
-probably will not.
+ $ gawk :== $sys$common:[syshlp.examples.tcpip.snmp]gawk.exe
+
+ This is apparently version 2.15.6, which is extremely old. We
+recommend compiling and using the current version.
-File: gawk.info, Node: New Ports, Prev: Adding Code, Up: Additions
+File: gawk.info, Node: Bugs, Next: Other Versions, Prev: Non-Unix
Installation, Up: Installation
-C.2.3 Porting `gawk' to a New Operating System
-----------------------------------------------
+B.4 Reporting Problems and Bugs
+===============================
-If you want to port `gawk' to a new operating system, there are several
-steps:
+ There is nothing more dangerous than a bored archeologist.
+ The Hitchhiker's Guide to the Galaxy
- 1. Follow the guidelines in *note Adding Code::, concerning coding
- style, submission of diffs, and so on.
+ If you have problems with `gawk' or think that you have found a bug,
+please report it to the developers; we cannot promise to do anything
+but we might well want to fix it.
- 2. Be prepared to sign the appropriate paperwork. In order for the
- FSF to distribute your code, you must either place your code in
- the public domain and submit a signed statement to that effect, or
- assign the copyright in your code to the FSF. Both of these
- actions are easy to do and _many_ people have done so already. If
- you have questions, please contact me, or <address@hidden>.
+ Before reporting a bug, make sure you have actually found a real bug.
+Carefully reread the documentation and see if it really says you can do
+what you're trying to do. If it's not clear whether you should be able
+to do something or not, report that too; it's a bug in the
+documentation!
- 3. When doing a port, bear in mind that your code must coexist
- peacefully with the rest of `gawk' and the other ports. Avoid
- gratuitous changes to the system-independent parts of the code. If
- at all possible, avoid sprinkling `#ifdef's just for your port
- throughout the code.
+ Before reporting a bug or trying to fix it yourself, try to isolate
+it to the smallest possible `awk' program and input data file that
+reproduces the problem. Then send us the program and data file, some
+idea of what kind of Unix system you're using, the compiler you used to
+compile `gawk', and the exact results `gawk' gave you. Also say what
+you expected to occur; this helps us decide whether the problem is
+really in the documentation.
- If the changes needed for a particular system affect too much of
- the code, I probably will not accept them. In such a case, you
- can, of course, distribute your changes on your own, as long as
- you comply with the GPL (*note Copying::).
+ Please include the version number of `gawk' you are using. You can
+get this information with the command `gawk --version'.
- 4. A number of the files that come with `gawk' are maintained by other
- people. Thus, you should not change them unless it is for a very
- good reason; i.e., changes are not out of the question, but
- changes to these files are scrutinized extra carefully. The files
- are `dfa.c', `dfa.h', `getopt1.c', `getopt.c', `getopt.h',
- `install-sh', `mkinstalldirs', `regcomp.c', `regex.c',
- `regexec.c', `regexex.c', `regex.h', `regex_internal.c', and
- `regex_internal.h'.
+ Once you have a precise problem, send email to <address@hidden>.
- 5. Be willing to continue to maintain the port. Non-Unix operating
- systems are supported by volunteers who maintain the code needed
- to compile and run `gawk' on their systems. If noone volunteers to
- maintain a port, it becomes unsupported and it may be necessary to
- remove it from the distribution.
+ Using this address automatically sends a copy of your mail to me.
+If necessary, I can be reached directly at <address@hidden>. The
+bug reporting address is preferred since the email list is archived at
+the GNU Project. _All email should be in English, since that is my
+native language._
- 6. Supply an appropriate `gawkmisc.???' file. Each port has its own
- `gawkmisc.???' that implements certain operating system specific
- functions. This is cleaner than a plethora of `#ifdef's scattered
- throughout the code. The `gawkmisc.c' in the main source
- directory includes the appropriate `gawkmisc.???' file from each
- subdirectory. Be sure to update it as well.
+ CAUTION: Do _not_ try to report bugs in `gawk' by posting to the
+ Usenet/Internet newsgroup `comp.lang.awk'. While the `gawk'
+ developers do occasionally read this newsgroup, there is no
+ guarantee that we will see your posting. The steps described
+ above are the official recognized ways for reporting bugs. Really.
- Each port's `gawkmisc.???' file has a suffix reminiscent of the
- machine or operating system for the port--for example,
- `pc/gawkmisc.pc' and `vms/gawkmisc.vms'. The use of separate
- suffixes, instead of plain `gawkmisc.c', makes it possible to move
- files from a port's subdirectory into the main subdirectory,
- without accidentally destroying the real `gawkmisc.c' file.
- (Currently, this is only an issue for the PC operating system
- ports.)
+ NOTE: Many distributions of GNU/Linux and the various BSD-based
+ operating systems have their own bug reporting systems. If you
+ report a bug using your distribution's bug reporting system,
+ _please_ also send a copy to <address@hidden>.
- 7. Supply a `Makefile' as well as any other C source and header files
- that are necessary for your operating system. All your code
- should be in a separate subdirectory, with a name that is the same
- as, or reminiscent of, either your operating system or the
- computer system. If possible, try to structure things so that it
- is not necessary to move files out of the subdirectory into the
- main source directory. If that is not possible, then be sure to
- avoid using names for your files that duplicate the names of files
- in the main source directory.
+ This is for two reasons. First, while some distributions forward
+ bug reports "upstream" to the GNU mailing list, many don't, so
+ there is a good chance that the `gawk' maintainer won't even see
+ the bug report! Second, mail to the GNU list is archived, and
+ having everything at the GNU project keeps things self-contained
+ and not dependant on other web sites.
- 8. Update the documentation. Please write a section (or sections)
- for this Info file describing the installation and compilation
- steps needed to compile and/or install `gawk' for your system.
+ Non-bug suggestions are always welcome as well. If you have
+questions about things that are unclear in the documentation or are
+just obscure features, ask me; I will try to help you out, although I
+may not have the time to fix the problem. You can send me electronic
+mail at the Internet address noted previously.
- Following these steps makes it much easier to integrate your changes
-into `gawk' and have them coexist happily with other operating systems'
-code that is already there.
+ If you find bugs in one of the non-Unix ports of `gawk', please send
+an electronic mail message to the person who maintains that port. They
+are named in the following list, as well as in the `README' file in the
+`gawk' distribution. Information in the `README' file should be
+considered authoritative if it conflicts with this Info file.
- In the code that you supply and maintain, feel free to use a coding
-style and brace layout that suits your taste.
+ The people maintaining the non-Unix ports of `gawk' are as follows:
-
-File: gawk.info, Node: Dynamic Extensions, Next: Future Extensions, Prev:
Additions, Up: Notes
+MS-DOS with DJGPP Scott Deifik, <address@hidden>.
+MS-Windows with MINGW Eli Zaretskii, <address@hidden>.
+OS/2 Andreas Buening, <address@hidden>.
+VMS Pat Rankin, <address@hidden>
+z/OS (OS/390) Dave Pitts, <address@hidden>.
-C.3 Adding New Built-in Functions to `gawk'
-===========================================
+ If your bug is also reproducible under Unix, please send a copy of
+your report to the <address@hidden> email list as well.
- Danger Will Robinson! Danger!!
- Warning! Warning!
- The Robot
+
+File: gawk.info, Node: Other Versions, Prev: Bugs, Up: Installation
- It is possible to add new built-in functions to `gawk' using
-dynamically loaded libraries. This facility is available on systems
-(such as GNU/Linux) that support the C `dlopen()' and `dlsym()'
-functions. This minor node describes how to write and use dynamically
-loaded extensions for `gawk'. Experience with programming in C or C++
-is necessary when reading this minor node.
+B.5 Other Freely Available `awk' Implementations
+================================================
- CAUTION: The facilities described in this minor node are very much
- subject to change in a future `gawk' release. Be aware that you
- may have to re-do everything, at some future time.
+ It's kind of fun to put comments like this in your awk code.
+ `// Do C++ comments work? answer: yes! of course'
+ Michael Brennan
- If you have written your own dynamic extensions, be sure to
- recompile them for each new `gawk' release. There is no guarantee
- of binary compatibility between different releases, nor will there
- ever be such a guarantee.
+ There are a number of other freely available `awk' implementations.
+This minor node briefly describes where to get them:
- NOTE: When `--sandbox' is specified, extensions are disabled
- (*note Options::.
+Unix `awk'
+ Brian Kernighan, one of the original designers of Unix `awk', has
+ made his implementation of `awk' freely available. You can
+ retrieve this version via the World Wide Web from his home page
+ (http://www.cs.princeton.edu/~bwk). It is available in several
+ archive formats:
-* Menu:
+ Shell archive
+ `http://www.cs.princeton.edu/~bwk/btl.mirror/awk.shar'
-* Internals:: A brief look at some `gawk' internals.
-* Plugin License:: A note about licensing.
-* Loading Extensions:: How to load dynamic extensions.
-* Sample Library:: A example of new functions.
+ Compressed `tar' file
+ `http://www.cs.princeton.edu/~bwk/btl.mirror/awk.tar.gz'
-
-File: gawk.info, Node: Internals, Next: Plugin License, Up: Dynamic
Extensions
+ Zip file
+ `http://www.cs.princeton.edu/~bwk/btl.mirror/awk.zip'
-C.3.1 A Minimal Introduction to `gawk' Internals
-------------------------------------------------
+ This version requires an ISO C (1990 standard) compiler; the C
+ compiler from GCC (the GNU Compiler Collection) works quite nicely.
-The truth is that `gawk' was not designed for simple extensibility.
-The facilities for adding functions using shared libraries work, but
-are something of a "bag on the side." Thus, this tour is brief and
-simplistic; would-be `gawk' hackers are encouraged to spend some time
-reading the source code before trying to write extensions based on the
-material presented here. Of particular note are the files `awk.h',
-`builtin.c', and `eval.c'. Reading `awkgram.y' in order to see how the
-parse tree is built would also be of use.
-
- With the disclaimers out of the way, the following types, structure
-members, functions, and macros are declared in `awk.h' and are of use
-when writing extensions. The next minor node shows how they are used:
-
-`AWKNUM'
- An `AWKNUM' is the internal type of `awk' floating-point numbers.
- Typically, it is a C `double'.
-
-`NODE'
- Just about everything is done using objects of type `NODE'. These
- contain both strings and numbers, as well as variables and arrays.
-
-`AWKNUM force_number(NODE *n)'
- This macro forces a value to be numeric. It returns the actual
- numeric value contained in the node. It may end up calling an
- internal `gawk' function.
-
-`void force_string(NODE *n)'
- This macro guarantees that a `NODE''s string value is current. It
- may end up calling an internal `gawk' function. It also
- guarantees that the string is zero-terminated.
-
-`void force_wstring(NODE *n)'
- Similarly, this macro guarantees that a `NODE''s wide-string value
- is current. It may end up calling an internal `gawk' function.
- It also guarantees that the wide string is zero-terminated.
-
-`nargs'
- Inside an extension function, this is the actual number of
- parameters passed to the current function.
-
-`n->stptr'
-`n->stlen'
- The data and length of a `NODE''s string value, respectively. The
- string is _not_ guaranteed to be zero-terminated. If you need to
- pass the string value to a C library function, save the value in
- `n->stptr[n->stlen]', assign `'\0'' to it, call the routine, and
- then restore the value.
-
-`n->wstptr'
-`n->wstlen'
- The data and length of a `NODE''s wide-string value, respectively.
- Use `force_wstring()' to make sure these values are current.
-
-`n->type'
- The type of the `NODE'. This is a C `enum'. Values should be one
- of `Node_var', `Node_var_new', or `Node_var_array' for function
- parameters.
-
-`n->vname'
- The "variable name" of a node. This is not of much use inside
- externally written extensions.
-
-`void assoc_clear(NODE *n)'
- Clears the associative array pointed to by `n'. Make sure that
- `n->type == Node_var_array' first.
-
-`NODE **assoc_lookup(NODE *symbol, NODE *subs)'
- Finds, and installs if necessary, array elements. `symbol' is the
- array, `subs' is the subscript. This is usually a value created
- with `make_string()' (see below).
-
-`NODE *make_string(char *s, size_t len)'
- Take a C string and turn it into a pointer to a `NODE' that can be
- stored appropriately. This is permanent storage; understanding of
- `gawk' memory management is helpful.
-
-`NODE *make_number(AWKNUM val)'
- Take an `AWKNUM' and turn it into a pointer to a `NODE' that can
- be stored appropriately. This is permanent storage; understanding
- of `gawk' memory management is helpful.
-
-`NODE *dupnode(NODE *n)'
- Duplicate a node. In most cases, this increments an internal
- reference count instead of actually duplicating the entire `NODE';
- understanding of `gawk' memory management is helpful.
-
-`void unref(NODE *n)'
- This macro releases the memory associated with a `NODE' allocated
- with `make_string()' or `make_number()'. Understanding of `gawk'
- memory management is helpful.
-
-`void make_builtin(const char *name, NODE *(*func)(NODE *), int count)'
- Register a C function pointed to by `func' as new built-in
- function `name'. `name' is a regular C string. `count' is the
- maximum number of arguments that the function takes. The function
- should be written in the following manner:
-
- /* do_xxx --- do xxx function for gawk */
-
- NODE *
- do_xxx(int nargs)
- {
- ...
- }
+ *Note Common Extensions::, for a list of extensions in this `awk'
+ that are not in POSIX `awk'.
-`NODE *get_argument(int i)'
- This function is called from within a C extension function to get
- the `i'-th argument from the function call. The first argument is
- argument zero.
-
-`NODE *get_actual_argument(int i,'
-` int optional, int wantarray);'
- This function retrieves a particular argument `i'. `wantarray' is
- `TRUE' if the argument should be an array, `FALSE' otherwise. If
- `optional' is `TRUE', the argument need not have been supplied.
- If it wasn't, the return value is `NULL'. It is a fatal error if
- `optional' is `TRUE' but the argument was not provided.
-
-`get_scalar_argument(i, opt)'
- This is a convenience macro that calls `get_actual_argument()'.
-
-`get_array_argument(i, opt)'
- This is a convenience macro that calls `get_actual_argument()'.
-
-`void update_ERRNO_int(int errno_saved)'
- This function is called from within a C extension function to set
- the value of `gawk''s `ERRNO' variable, based on the error value
- provided as the argument. It is provided as a convenience.
-
-`void update_ERRNO_string(const char *string, enum errno_translate)'
- This function is called from within a C extension function to set
- the value of `gawk''s `ERRNO' variable to a given string. The
- second argument determines whether the string is translated before
- being installed into `ERRNO'. It is provided as a convenience.
-
-`void unset_ERRNO(void)'
- This function is called from within a C extension function to set
- the value of `gawk''s `ERRNO' variable to a null string. It is
- provided as a convenience.
-
-`void register_deferred_variable(const char *name, NODE *(*load_func)(void))'
- This function is called to register a function to be called when a
- reference to an undefined variable with the given name is
- encountered. The callback function will never be called if the
- variable exists already, so, unless the calling code is running at
- program startup, it should first check whether a variable of the
- given name already exists. The argument function must return a
- pointer to a `NODE' containing the newly created variable. This
- function is used to implement the builtin `ENVIRON' and `PROCINFO'
- arrays, so you can refer to them for examples.
-
-`void register_open_hook(void *(*open_func)(IOBUF *))'
- This function is called to register a function to be called
- whenever a new data file is opened, leading to the creation of an
- `IOBUF' structure in `iop_alloc()'. After creating the new
- `IOBUF', `iop_alloc()' will call (in reverse order of
- registration, so the last function registered is called first)
- each open hook until one returns non-`NULL'. If any hook returns
- a non-`NULL' value, that value is assigned to the `IOBUF''s
- `opaque' field (which will presumably point to a structure
- containing additional state associated with the input processing),
- and no further open hooks are called.
-
- The function called will most likely want to set the `IOBUF''s
- `get_record' method to indicate that future input records should
- be retrieved by calling that method instead of using the standard
- `gawk' input processing.
-
- And the function will also probably want to set the `IOBUF''s
- `close_func' method to be called when the file is closed to clean
- up any state associated with the input.
-
- Finally, hook functions should be prepared to receive an `IOBUF'
- structure where the `fd' field is set to `INVALID_HANDLE', meaning
- that `gawk' was not able to open the file itself. In this case,
- the hook function must be able to successfully open the file and
- place a valid file descriptor there.
-
- Currently, for example, the hook function facility is used to
- implement the XML parser shared library extension. For more info,
- please look in `awk.h' and in `io.c'.
-
- An argument that is supposed to be an array needs to be handled with
-some extra code, in case the array being passed in is actually from a
-function parameter.
-
- The following boilerplate code shows how to do this:
-
- NODE *the_arg;
-
- /* assume need 3rd arg, 0-based */
- the_arg = get_array_argument(2, FALSE);
-
- Again, you should spend time studying the `gawk' internals; don't
-just blindly copy this code.
-
-
-File: gawk.info, Node: Plugin License, Next: Loading Extensions, Prev:
Internals, Up: Dynamic Extensions
-
-C.3.2 Extension Licensing
--------------------------
+`mawk'
+ Michael Brennan wrote an independent implementation of `awk',
+ called `mawk'. It is available under the GPL (*note Copying::),
+ just as `gawk' is.
-Every dynamic extension should define the global symbol
-`plugin_is_GPL_compatible' to assert that it has been licensed under a
-GPL-compatible license. If this symbol does not exist, `gawk' will
-emit a fatal error and exit.
+ The original distribution site for the `mawk' source code no
+ longer has it. A copy is available at
+ `http://www.skeeve.com/gawk/mawk1.3.3.tar.gz'.
- The declared type of the symbol should be `int'. It does not need
-to be in any allocated section, though. The code merely asserts that
-the symbol exists in the global scope. Something like this is enough:
+ In 2009, Thomas Dickey took on `mawk' maintenance. Basic
+ information is available on the project's web page
+ (http://www.invisible-island.net/mawk/mawk.html). The download
+ URL is `http://invisible-island.net/datafiles/release/mawk.tar.gz'.
- int plugin_is_GPL_compatible;
+ Once you have it, `gunzip' may be used to decompress this file.
+ Installation is similar to `gawk''s (*note Unix Installation::).
-
-File: gawk.info, Node: Loading Extensions, Next: Sample Library, Prev:
Plugin License, Up: Dynamic Extensions
+ *Note Common Extensions::, for a list of extensions in `mawk' that
+ are not in POSIX `awk'.
-C.3.3 Loading a Dynamic Extension
----------------------------------
+`awka'
+ Written by Andrew Sumner, `awka' translates `awk' programs into C,
+ compiles them, and links them with a library of functions that
+ provides the core `awk' functionality. It also has a number of
+ extensions.
+
+ The `awk' translator is released under the GPL, and the library is
+ under the LGPL.
-There are two ways to load a dynamically linked library. The first is
-to use the builtin `extension()':
+ To get `awka', go to `http://sourceforge.net/projects/awka'.
- extension(libname, init_func)
+ The project seems to be frozen; no new code changes have been made
+ since approximately 2003.
- where `libname' is the library to load, and `init_func' is the name
-of the initialization or bootstrap routine to run once loaded.
+`pawk'
+ Nelson H.F. Beebe at the University of Utah has modified Brian
+ Kernighan's `awk' to provide timing and profiling information. It
+ is different from `gawk' with the `--profile' option. (*note
+ Profiling::), in that it uses CPU-based profiling, not line-count
+ profiling. You may find it at either
+ `ftp://ftp.math.utah.edu/pub/pawk/pawk-20030606.tar.gz' or
+ `http://www.math.utah.edu/pub/pawk/pawk-20030606.tar.gz'.
- The second method for dynamic loading of a library is to use the
-command line option `-l':
+Busybox Awk
+ Busybox is a GPL-licensed program providing small versions of many
+ applications within a single executable. It is aimed at embedded
+ systems. It includes a full implementation of POSIX `awk'. When
+ building it, be careful not to do `make install' as it will
+ overwrite copies of other applications in your `/usr/local/bin'.
+ For more information, see the project's home page
+ (http://busybox.net).
- $ gawk -l libname -f myprog
+The OpenSolaris POSIX `awk'
+ The version of `awk' in `/usr/xpg4/bin' on Solaris is more-or-less
+ POSIX-compliant. It is based on the `awk' from Mortice Kern
+ Systems for PCs. The source code can be downloaded from the
+ OpenSolaris web site (http://www.opensolaris.org). This author
+ was able to make it compile and work under GNU/Linux with 1-2
+ hours of work. Making it more generally portable (using GNU
+ Autoconf and/or Automake) would take more work, and this has not
+ been done, at least to our knowledge.
- This will work only if the initialization routine is named
-`dl_load()'.
+`jawk'
+ This is an interpreter for `awk' written in Java. It claims to be
+ a full interpreter, although because it uses Java facilities for
+ I/O and for regexp matching, the language it supports is different
+ from POSIX `awk'. More information is available on the project's
+ home page (http://jawk.sourceforge.net).
- If you use `extension()', the library will be loaded at run time.
-This means that the functions are available only to the rest of your
-script. If you use the command line option `-l' instead, the library
-will be loaded before `gawk' starts compiling the actual program. The
-net effect is that you can use those functions anywhere in the program.
+Libmawk
+ This is an embeddable `awk' interpreter derived from `mawk'. For
+ more information see `http://repo.hu/projects/libmawk/'.
- `gawk' has a list of directories where it searches for libraries.
-By default, the list includes directories that depend upon how gawk was
-built and installed (*note AWKLIBPATH Variable::). If you want `gawk'
-to look for libraries in your private directory, you have to tell it.
-The way to do it is to set the `AWKLIBPATH' environment variable (*note
-AWKLIBPATH Variable::). `gawk' supplies the default shared library
-platform suffix if it is not present in the name of the library. If
-the name of your library is `mylib.so', you can simply type
+QSE Awk
+ This is an embeddable `awk' interpreter. For more information see
+ `http://code.google.com/p/qse/' and `http://awk.info/?tools/qse'.
- $ gawk -l mylib -f myprog
+`QTawk'
+ This is an independent implementation of `awk' distributed under
+ the GPL. It has a large number of extensions over standard `awk'
+ and may not be 100% syntactically compatible with it. See
+ `http://www.quiktrim.org/QTawk.html' for more information,
+ including the manual and a download link.
- and `gawk' will do everything necessary to load in your library, and
-then call your `dl_load()' routine.
+`xgawk'
+ XML `gawk'. This is a fork of the `gawk' 3.1.6 source base to
+ support processing XML files. It has a number of interesting
+ extensions which should one day be integrated into the main `gawk'
+ code base. For more information, see the XMLgawk project web site
+ (http://xmlgawk.sourceforge.net).
- You can always specify the library using an absolute pathname, in
-which case `gawk' will not use `AWKLIBPATH' to search for it.
-File: gawk.info, Node: Sample Library, Prev: Loading Extensions, Up:
Dynamic Extensions
+File: gawk.info, Node: Notes, Next: Basic Concepts, Prev: Installation,
Up: Top
-C.3.4 Example: Directory and File Operation Built-ins
------------------------------------------------------
+Appendix C Implementation Notes
+*******************************
-Two useful functions that are not in `awk' are `chdir()' (so that an
-`awk' program can change its directory) and `stat()' (so that an `awk'
-program can gather information about a file). This minor node
-implements these functions for `gawk' in an external extension library.
+This appendix contains information mainly of interest to implementers
+and maintainers of `gawk'. Everything in it applies specifically to
+`gawk' and not to other implementations.
* Menu:
-* Internal File Description:: What the new functions will do.
-* Internal File Ops:: The code for internal file operations.
-* Using Internal File Ops:: How to use an external extension.
+* Compatibility Mode:: How to disable certain `gawk'
+ extensions.
+* Additions:: Making Additions To `gawk'.
+* Future Extensions:: New features that may be implemented one day.
-File: gawk.info, Node: Internal File Description, Next: Internal File Ops,
Up: Sample Library
-
-C.3.4.1 Using `chdir()' and `stat()'
-....................................
-
-This minor node shows how to use the new functions at the `awk' level
-once they've been integrated into the running `gawk' interpreter.
-Using `chdir()' is very straightforward. It takes one argument, the new
-directory to change to:
-
- ...
- newdir = "/home/arnold/funstuff"
- ret = chdir(newdir)
- if (ret < 0) {
- printf("could not change to %s: %s\n",
- newdir, ERRNO) > "/dev/stderr"
- exit 1
- }
- ...
-
- The return value is negative if the `chdir' failed, and `ERRNO'
-(*note Built-in Variables::) is set to a string indicating the error.
-
- Using `stat()' is a bit more complicated. The C `stat()' function
-fills in a structure that has a fair amount of information. The right
-way to model this in `awk' is to fill in an associative array with the
-appropriate information:
-
- file = "/home/arnold/.profile"
- fdata[1] = "x" # force `fdata' to be an array
- ret = stat(file, fdata)
- if (ret < 0) {
- printf("could not stat %s: %s\n",
- file, ERRNO) > "/dev/stderr"
- exit 1
- }
- printf("size of %s is %d bytes\n", file, fdata["size"])
+File: gawk.info, Node: Compatibility Mode, Next: Additions, Up: Notes
- The `stat()' function always clears the data array, even if the
-`stat()' fails. It fills in the following elements:
+C.1 Downward Compatibility and Debugging
+========================================
-`"name"'
- The name of the file that was `stat()''ed.
+*Note POSIX/GNU::, for a summary of the GNU extensions to the `awk'
+language and program. All of these features can be turned off by
+invoking `gawk' with the `--traditional' option or with the `--posix'
+option.
-`"dev"'
-`"ino"'
- The file's device and inode numbers, respectively.
+ If `gawk' is compiled for debugging with `-DDEBUG', then there is
+one more option available on the command line:
-`"mode"'
- The file's mode, as a numeric value. This includes both the file's
- type and its permissions.
+`-Y'
+`--parsedebug'
+ Prints out the parse stack information as the program is being
+ parsed.
-`"nlink"'
- The number of hard links (directory entries) the file has.
+ This option is intended only for serious `gawk' developers and not
+for the casual user. It probably has not even been compiled into your
+version of `gawk', since it slows down execution.
-`"uid"'
-`"gid"'
- The numeric user and group ID numbers of the file's owner.
+
+File: gawk.info, Node: Additions, Next: Future Extensions, Prev:
Compatibility Mode, Up: Notes
-`"size"'
- The size in bytes of the file.
+C.2 Making Additions to `gawk'
+==============================
-`"blocks"'
- The number of disk blocks the file actually occupies. This may not
- be a function of the file's size if the file has holes.
+If you find that you want to enhance `gawk' in a significant fashion,
+you are perfectly free to do so. That is the point of having free
+software; the source code is available and you are free to change it as
+you want (*note Copying::).
-`"atime"'
-`"mtime"'
-`"ctime"'
- The file's last access, modification, and inode update times,
- respectively. These are numeric timestamps, suitable for
- formatting with `strftime()' (*note Built-in::).
+ This minor node discusses the ways you might want to change `gawk'
+as well as any considerations you should bear in mind.
-`"pmode"'
- The file's "printable mode." This is a string representation of
- the file's type and permissions, such as what is produced by `ls
- -l'--for example, `"drwxr-xr-x"'.
+* Menu:
-`"type"'
- A printable string representation of the file's type. The value
- is one of the following:
+* Accessing The Source:: Accessing the Git repository.
+* Adding Code:: Adding code to the main body of
+ `gawk'.
+* New Ports:: Porting `gawk' to a new operating
+ system.
- `"blockdev"'
- `"chardev"'
- The file is a block or character device ("special file").
+
+File: gawk.info, Node: Accessing The Source, Next: Adding Code, Up:
Additions
- `"directory"'
- The file is a directory.
+C.2.1 Accessing The `gawk' Git Repository
+-----------------------------------------
- `"fifo"'
- The file is a named-pipe (also known as a FIFO).
+As `gawk' is Free Software, the source code is always available. *note
+Gawk Distribution::, describes how to get and build the formal,
+released versions of `gawk'.
- `"file"'
- The file is just a regular file.
+ However, if you want to modify `gawk' and contribute back your
+changes, you will probably wish to work with the development version.
+To do so, you will need to access the `gawk' source code repository.
+The code is maintained using the Git distributed version control system
+(http://git-scm.com/). You will need to install it if your system
+doesn't have it. Once you have done so, use the command:
- `"socket"'
- The file is an `AF_UNIX' ("Unix domain") socket in the
- filesystem.
+ git clone git://git.savannah.gnu.org/gawk.git
- `"symlink"'
- The file is a symbolic link.
+This will clone the `gawk' repository. If you are behind a firewall
+that will not allow you to use the Git native protocol, you can still
+access the repository using:
- Several additional elements may be present depending upon the
-operating system and the type of the file. You can test for them in
-your `awk' program by using the `in' operator (*note Reference to
-Elements::):
+ git clone http://git.savannah.gnu.org/r/gawk.git
-`"blksize"'
- The preferred block size for I/O to the file. This field is not
- present on all POSIX-like systems in the C `stat' structure.
+ Once you have made changes, you can use `git diff' to produce a
+patch, and send that to the `gawk' maintainer; see *note Bugs:: for how
+to do that.
-`"linkval"'
- If the file is a symbolic link, this element is the name of the
- file the link points to (i.e., the value of the link).
+ Finally, if you cannot install Git (e.g., if it hasn't been ported
+yet to your operating system), you can use the Git-CVS gateway to check
+out a copy using CVS, as follows:
-`"rdev"'
-`"major"'
-`"minor"'
- If the file is a block or character device file, then these values
- represent the numeric device number and the major and minor
- components of that number, respectively.
+ cvs -d:pserver:address@hidden:/gawk.git co -d gawk master
-File: gawk.info, Node: Internal File Ops, Next: Using Internal File Ops,
Prev: Internal File Description, Up: Sample Library
-
-C.3.4.2 C Code for `chdir()' and `stat()'
-.........................................
-
-Here is the C code for these extensions. They were written for
-GNU/Linux. The code needs some more work for complete portability to
-other POSIX-compliant systems:(1)
-
- #include "awk.h"
-
- #include <sys/sysmacros.h>
+File: gawk.info, Node: Adding Code, Next: New Ports, Prev: Accessing The
Source, Up: Additions
- int plugin_is_GPL_compatible;
+C.2.2 Adding New Features
+-------------------------
- /* do_chdir --- provide dynamically loaded chdir() builtin for gawk */
+You are free to add any new features you like to `gawk'. However, if
+you want your changes to be incorporated into the `gawk' distribution,
+there are several steps that you need to take in order to make it
+possible to include your changes:
- static NODE *
- do_chdir(int nargs)
- {
- NODE *newdir;
- int ret = -1;
+ 1. Before building the new feature into `gawk' itself, consider
+ writing it as an extension module (*note Dynamic Extensions::).
+ If that's not possible, continue with the rest of the steps in
+ this list.
- if (do_lint && nargs != 1)
- lintwarn("chdir: called with incorrect number of arguments");
+ 2. Be prepared to sign the appropriate paperwork. In order for the
+ FSF to distribute your changes, you must either place those
+ changes in the public domain and submit a signed statement to that
+ effect, or assign the copyright in your changes to the FSF. Both
+ of these actions are easy to do and _many_ people have done so
+ already. If you have questions, please contact me (*note Bugs::),
+ or <address@hidden>.
- newdir = get_scalar_argument(0, FALSE);
+ 3. Get the latest version. It is much easier for me to integrate
+ changes if they are relative to the most recent distributed
+ version of `gawk'. If your version of `gawk' is very old, I may
+ not be able to integrate them at all. (*Note Getting::, for
+ information on getting the latest version of `gawk'.)
- The file includes the `"awk.h"' header file for definitions for the
-`gawk' internals. It includes `<sys/sysmacros.h>' for access to the
-`major()' and `minor'() macros.
+ 4. See *note (Version)Top:: standards, GNU Coding Standards. This
+ document describes how GNU software should be written. If you
+ haven't read it, please do so, preferably _before_ starting to
+ modify `gawk'. (The `GNU Coding Standards' are available from the
+ GNU Project's web site
+ (http://www.gnu.org/prep/standards_toc.html). Texinfo, Info, and
+ DVI versions are also available.)
- By convention, for an `awk' function `foo', the function that
-implements it is called `do_foo'. The function should take a `int'
-argument, usually called `nargs', that represents the number of defined
-arguments for the function. The `newdir' variable represents the new
-directory to change to, retrieved with `get_scalar_argument()'. Note
-that the first argument is numbered zero.
+ 5. Use the `gawk' coding style. The C code for `gawk' follows the
+ instructions in the `GNU Coding Standards', with minor exceptions.
+ The code is formatted using the traditional "K&R" style,
+ particularly as regards to the placement of braces and the use of
+ TABs. In brief, the coding rules for `gawk' are as follows:
- This code actually accomplishes the `chdir()'. It first forces the
-argument to be a string and passes the string value to the `chdir()'
-system call. If the `chdir()' fails, `ERRNO' is updated.
+ * Use ANSI/ISO style (prototype) function headers when defining
+ functions.
- (void) force_string(newdir);
- ret = chdir(newdir->stptr);
- if (ret < 0)
- update_ERRNO_int(errno);
+ * Put the name of the function at the beginning of its own line.
- Finally, the function returns the return value to the `awk' level:
+ * Put the return type of the function, even if it is `int', on
+ the line above the line with the name and arguments of the
+ function.
- return make_number((AWKNUM) ret);
- }
+ * Put spaces around parentheses used in control structures
+ (`if', `while', `for', `do', `switch', and `return').
- The `stat()' built-in is more involved. First comes a function that
-turns a numeric mode into a printable representation (e.g., 644 becomes
-`-rw-r--r--'). This is omitted here for brevity:
+ * Do not put spaces in front of parentheses used in function
+ calls.
- /* format_mode --- turn a stat mode field into something readable */
+ * Put spaces around all C operators and after commas in
+ function calls.
- static char *
- format_mode(unsigned long fmode)
- {
- ...
- }
+ * Do not use the comma operator to produce multiple side
+ effects, except in `for' loop initialization and increment
+ parts, and in macro bodies.
- Next comes the `do_stat()' function. It starts with variable
-declarations and argument checking:
+ * Use real TABs for indenting, not spaces.
- /* do_stat --- provide a stat() function for gawk */
+ * Use the "K&R" brace layout style.
- static NODE *
- do_stat(int nargs)
- {
- NODE *file, *array, *tmp;
- struct stat sbuf;
- int ret;
- NODE **aptr;
- char *pmode; /* printable mode */
- char *type = "unknown";
+ * Use comparisons against `NULL' and `'\0'' in the conditions of
+ `if', `while', and `for' statements, as well as in the `case's
+ of `switch' statements, instead of just the plain pointer or
+ character value.
- if (do_lint && nargs > 2)
- lintwarn("stat: called with too many arguments");
+ * Use the `TRUE', `FALSE' and `NULL' symbolic constants and the
+ character constant `'\0'' where appropriate, instead of `1'
+ and `0'.
- Then comes the actual work. First, the function gets the arguments.
-Then, it always clears the array. The code use `lstat()' (instead of
-`stat()') to get the file information, in case the file is a symbolic
-link. If there's an error, it sets `ERRNO' and returns:
+ * Provide one-line descriptive comments for each function.
- /* file is first arg, array to hold results is second */
- file = get_scalar_argument(0, FALSE);
- array = get_array_argument(1, FALSE);
+ * Do not use the `alloca()' function for allocating memory off
+ the stack. Its use causes more portability trouble than is
+ worth the minor benefit of not having to free the storage.
+ Instead, use `malloc()' and `free()'.
- /* empty out the array */
- assoc_clear(array);
+ * Do not use comparisons of the form `! strcmp(a, b)' or
+ similar. As Henry Spencer once said, "`strcmp()' is not a
+ boolean!" Instead, use `strcmp(a, b) == 0'.
- /* lstat the file, if error, set ERRNO and return */
- (void) force_string(file);
- ret = lstat(file->stptr, & sbuf);
- if (ret < 0) {
- update_ERRNO_int(errno);
- return make_number((AWKNUM) ret);
- }
+ * If adding new bit flag values, use explicit hexadecimal
+ constants (`0x001', `0x002', `0x004', and son on) instead of
+ shifting one left by successive amounts (`(1<<0)', `(1<<1)',
+ and so on).
- Now comes the tedious part: filling in the array. Only a few of the
-calls are shown here, since they all follow the same pattern:
+ NOTE: If I have to reformat your code to follow the coding
+ style used in `gawk', I may not bother to integrate your
+ changes at all.
- /* fill in the array */
- aptr = assoc_lookup(array, tmp = make_string("name", 4));
- *aptr = dupnode(file);
- unref(tmp);
+ 6. Update the documentation. Along with your new code, please supply
+ new sections and/or chapters for this Info file. If at all
+ possible, please use real Texinfo, instead of just supplying
+ unformatted ASCII text (although even that is better than no
+ documentation at all). Conventions to be followed in `GAWK:
+ Effective AWK Programming' are provided after the address@hidden' at the
+ end of the Texinfo source file. If possible, please update the
+ `man' page as well.
- aptr = assoc_lookup(array, tmp = make_string("mode", 4));
- *aptr = make_number((AWKNUM) sbuf.st_mode);
- unref(tmp);
+ You will also have to sign paperwork for your documentation
+ changes.
- aptr = assoc_lookup(array, tmp = make_string("pmode", 5));
- pmode = format_mode(sbuf.st_mode);
- *aptr = make_string(pmode, strlen(pmode));
- unref(tmp);
+ 7. Submit changes as unified diffs. Use `diff -u -r -N' to compare
+ the original `gawk' source tree with your version. I recommend
+ using the GNU version of `diff', or best of all, `git diff' or
+ `git format-patch'. Send the output produced by `diff' to me when
+ you submit your changes. (*Note Bugs::, for the electronic mail
+ information.)
- When done, return the `lstat()' return value:
+ Using this format makes it easy for me to apply your changes to the
+ master version of the `gawk' source code (using `patch'). If I
+ have to apply the changes manually, using a text editor, I may not
+ do so, particularly if there are lots of changes.
+ 8. Include an entry for the `ChangeLog' file with your submission.
+ This helps further minimize the amount of work I have to do,
+ making it easier for me to accept patches.
- return make_number((AWKNUM) ret);
- }
+ Although this sounds like a lot of work, please remember that while
+you may write the new code, I have to maintain it and support it. If it
+isn't possible for me to do that with a minimum of extra work, then I
+probably will not.
- Finally, it's necessary to provide the "glue" that loads the new
-function(s) into `gawk'. By convention, each library has a routine
-named `dl_load()' that does the job. The simplest way is to use the
-`dl_load_func' macro in `gawkapi.h'.
+
+File: gawk.info, Node: New Ports, Prev: Adding Code, Up: Additions
- And that's it! As an exercise, consider adding functions to
-implement system calls such as `chown()', `chmod()', and `umask()'.
+C.2.3 Porting `gawk' to a New Operating System
+----------------------------------------------
- ---------- Footnotes ----------
+If you want to port `gawk' to a new operating system, there are several
+steps:
- (1) This version is edited slightly for presentation. See
-`extension/filefuncs.c' in the `gawk' distribution for the complete
-version.
+ 1. Follow the guidelines in *note Adding Code::, concerning coding
+ style, submission of diffs, and so on.
-
-File: gawk.info, Node: Using Internal File Ops, Prev: Internal File Ops,
Up: Sample Library
+ 2. Be prepared to sign the appropriate paperwork. In order for the
+ FSF to distribute your code, you must either place your code in
+ the public domain and submit a signed statement to that effect, or
+ assign the copyright in your code to the FSF. Both of these
+ actions are easy to do and _many_ people have done so already. If
+ you have questions, please contact me, or <address@hidden>.
-C.3.4.3 Integrating the Extensions
-..................................
+ 3. When doing a port, bear in mind that your code must coexist
+ peacefully with the rest of `gawk' and the other ports. Avoid
+ gratuitous changes to the system-independent parts of the code. If
+ at all possible, avoid sprinkling `#ifdef's just for your port
+ throughout the code.
-Now that the code is written, it must be possible to add it at runtime
-to the running `gawk' interpreter. First, the code must be compiled.
-Assuming that the functions are in a file named `filefuncs.c', and IDIR
-is the location of the `gawk' include files, the following steps create
-a GNU/Linux shared library:
+ If the changes needed for a particular system affect too much of
+ the code, I probably will not accept them. In such a case, you
+ can, of course, distribute your changes on your own, as long as
+ you comply with the GPL (*note Copying::).
- $ gcc -fPIC -shared -DHAVE_CONFIG_H -c -O -g -IIDIR filefuncs.c
- $ ld -o filefuncs.so -shared filefuncs.o
+ 4. A number of the files that come with `gawk' are maintained by other
+ people. Thus, you should not change them unless it is for a very
+ good reason; i.e., changes are not out of the question, but
+ changes to these files are scrutinized extra carefully. The files
+ are `dfa.c', `dfa.h', `getopt1.c', `getopt.c', `getopt.h',
+ `install-sh', `mkinstalldirs', `regcomp.c', `regex.c',
+ `regexec.c', `regexex.c', `regex.h', `regex_internal.c', and
+ `regex_internal.h'.
- Once the library exists, it is loaded by calling the `extension()'
-built-in function. This function takes two arguments: the name of the
-library to load and the name of a function to call when the library is
-first loaded. This function adds the new functions to `gawk'. It
-returns the value returned by the initialization function within the
-shared library:
+ 5. Be willing to continue to maintain the port. Non-Unix operating
+ systems are supported by volunteers who maintain the code needed
+ to compile and run `gawk' on their systems. If noone volunteers to
+ maintain a port, it becomes unsupported and it may be necessary to
+ remove it from the distribution.
- # file testff.awk
- BEGIN {
- extension("./filefuncs.so", "dl_load")
+ 6. Supply an appropriate `gawkmisc.???' file. Each port has its own
+ `gawkmisc.???' that implements certain operating system specific
+ functions. This is cleaner than a plethora of `#ifdef's scattered
+ throughout the code. The `gawkmisc.c' in the main source
+ directory includes the appropriate `gawkmisc.???' file from each
+ subdirectory. Be sure to update it as well.
- chdir(".") # no-op
+ Each port's `gawkmisc.???' file has a suffix reminiscent of the
+ machine or operating system for the port--for example,
+ `pc/gawkmisc.pc' and `vms/gawkmisc.vms'. The use of separate
+ suffixes, instead of plain `gawkmisc.c', makes it possible to move
+ files from a port's subdirectory into the main subdirectory,
+ without accidentally destroying the real `gawkmisc.c' file.
+ (Currently, this is only an issue for the PC operating system
+ ports.)
- data[1] = 1 # force `data' to be an array
- print "Info for testff.awk"
- ret = stat("testff.awk", data)
- print "ret =", ret
- for (i in data)
- printf "data[\"%s\"] = %s\n", i, data[i]
- print "testff.awk modified:",
- strftime("%m %d %y %H:%M:%S", data["mtime"])
+ 7. Supply a `Makefile' as well as any other C source and header files
+ that are necessary for your operating system. All your code
+ should be in a separate subdirectory, with a name that is the same
+ as, or reminiscent of, either your operating system or the
+ computer system. If possible, try to structure things so that it
+ is not necessary to move files out of the subdirectory into the
+ main source directory. If that is not possible, then be sure to
+ avoid using names for your files that duplicate the names of files
+ in the main source directory.
- print "\nInfo for JUNK"
- ret = stat("JUNK", data)
- print "ret =", ret
- for (i in data)
- printf "data[\"%s\"] = %s\n", i, data[i]
- print "JUNK modified:", strftime("%m %d %y %H:%M:%S", data["mtime"])
- }
+ 8. Update the documentation. Please write a section (or sections)
+ for this Info file describing the installation and compilation
+ steps needed to compile and/or install `gawk' for your system.
- Here are the results of running the program:
+ Following these steps makes it much easier to integrate your changes
+into `gawk' and have them coexist happily with other operating systems'
+code that is already there.
- $ gawk -f testff.awk
- -| Info for testff.awk
- -| ret = 0
- -| data["size"] = 607
- -| data["ino"] = 14945891
- -| data["name"] = testff.awk
- -| data["pmode"] = -rw-rw-r--
- -| data["nlink"] = 1
- -| data["atime"] = 1293993369
- -| data["mtime"] = 1288520752
- -| data["mode"] = 33204
- -| data["blksize"] = 4096
- -| data["dev"] = 2054
- -| data["type"] = file
- -| data["gid"] = 500
- -| data["uid"] = 500
- -| data["blocks"] = 8
- -| data["ctime"] = 1290113572
- -| testff.awk modified: 10 31 10 12:25:52
- -|
- -| Info for JUNK
- -| ret = -1
- -| JUNK modified: 01 01 70 02:00:00
+ In the code that you supply and maintain, feel free to use a coding
+style and brace layout that suits your taste.
-File: gawk.info, Node: Future Extensions, Prev: Dynamic Extensions, Up:
Notes
+File: gawk.info, Node: Future Extensions, Prev: Additions, Up: Notes
-C.4 Probable Future Extensions
+C.3 Probable Future Extensions
==============================
AWK is a language similar to PERL, only considerably more elegant.
@@ -23369,12 +23106,9 @@ well.
Following is a list of probable future changes visible at the `awk'
language level:
-Loadable module interface
- It is not clear that the `awk'-level interface to the modules
- facility is as good as it should be. The interface needs to be
- redesigned, particularly taking namespace issues into account, as
- well as possibly including issues such as library search path order
- and versioning.
+Databases
+ It may be possible to map a GDBM/NDBM/SDBM file into an `awk'
+ array.
`RECLEN' variable for fixed-length records
Along with `FIELDWIDTHS', this would speed up the processing of
@@ -23382,30 +23116,12 @@ Loadable module interface
`"RECLEN"', depending upon which kind of record processing is in
effect.
-Databases
- It may be possible to map a GDBM/NDBM/SDBM file into an `awk'
- array.
-
More `lint' warnings
There are more things that could be checked for portability.
Following is a list of probable improvements that will make `gawk''s
source code easier to work with:
-Loadable module mechanics
- The current extension mechanism works (*note Dynamic Extensions::),
- but is rather primitive. It requires a fair amount of manual work
- to create and integrate a loadable module. Nor is the current
- mechanism as portable as might be desired. The GNU `libtool'
- package provides a number of features that would make using
- loadable modules much easier. `gawk' should be changed to use
- `libtool'.
-
-Loadable module internals
- The API to its internals that `gawk' "exports" should be revised.
- Too many things are needlessly exposed. A new API should be
- designed and implemented to make module writing easier.
-
Better array subscript management
`gawk''s management of array subscript storage could use revamping,
so that using the same value to index multiple arrays only stores
@@ -25955,7 +25671,7 @@ Index
* Ada programming language: Glossary. (line 20)
* adding, features to gawk: Adding Code. (line 6)
* adding, fields: Changing Fields. (line 53)
-* adding, functions to gawk: Dynamic Extensions. (line 10)
+* adding, functions to gawk: Dynamic Extensions. (line 9)
* advanced features, buffering: I/O Functions. (line 98)
* advanced features, close() function: Close Files And Pipes.
(line 131)
@@ -26014,18 +25730,15 @@ Index
* arguments, command-line, invoking awk: Command Line. (line 6)
* arguments, in function calls: Function Calls. (line 16)
* arguments, processing: Getopt Function. (line 6)
-* arguments, retrieving: Internals. (line 111)
* arithmetic operators: Arithmetic Ops. (line 6)
* arrays: Arrays. (line 6)
* arrays, as parameters to functions: Pass By Value/Reference.
(line 47)
* arrays, associative: Array Intro. (line 50)
-* arrays, associative, clearing: Internals. (line 68)
* arrays, associative, library functions and: Library Names. (line 57)
* arrays, deleting entire contents: Delete. (line 39)
* arrays, elements, assigning: Assigning Elements. (line 6)
* arrays, elements, deleting: Delete. (line 6)
-* arrays, elements, installing: Internals. (line 72)
* arrays, elements, order of: Scanning an Array. (line 48)
* arrays, elements, referencing: Reference to Elements.
(line 6)
@@ -26064,8 +25777,6 @@ Index
* assignment operators, evaluation order: Assignment Ops. (line 111)
* assignment operators, lvalues/rvalues: Assignment Ops. (line 32)
* assignments as filenames: Ignoring Assigns. (line 6)
-* assoc_clear() internal function: Internals. (line 68)
-* assoc_lookup() internal function: Internals. (line 72)
* associative arrays: Array Intro. (line 50)
* asterisk (*), * operator, as multiplication operator: Precedence.
(line 55)
@@ -26134,10 +25845,8 @@ Index
* awk, versions of, See Also Brian Kernighan's awk <1>: Other Versions.
(line 13)
* awk, versions of, See Also Brian Kernighan's awk: BTL. (line 6)
-* awk.h file (internal): Internals. (line 15)
* awka compiler for awk: Other Versions. (line 55)
* AWKLIBPATH environment variable: AWKLIBPATH Variable. (line 6)
-* AWKNUM internal type: Internals. (line 19)
* AWKPATH environment variable <1>: PC Using. (line 11)
* AWKPATH environment variable: AWKPATH Variable. (line 6)
* awkprof.out file: Profiling. (line 6)
@@ -26339,7 +26048,6 @@ Index
* close() function, two-way pipes and: Two-way I/O. (line 77)
* Close, Diane <1>: Contributors. (line 21)
* Close, Diane: Manual History. (line 41)
-* close_func() input method: Internals. (line 157)
* collating elements: Bracket Expressions. (line 69)
* collating symbols: Bracket Expressions. (line 76)
* Colombo, Antonio: Acknowledgments. (line 60)
@@ -26719,7 +26427,6 @@ Index
* DuBois, John: Acknowledgments. (line 60)
* dump debugger command: Miscellaneous Debugger Commands.
(line 9)
-* dupnode() internal function: Internals. (line 87)
* dupword.awk program: Dupword Program. (line 31)
* e debugger command (alias for enable): Breakpoint Control. (line 73)
* EBCDIC: Ordinal Functions. (line 45)
@@ -26760,7 +26467,6 @@ Index
* endgrent() user-defined function: Group Functions. (line 218)
* endpwent() function (C library): Passwd Functions. (line 210)
* endpwent() user-defined function: Passwd Functions. (line 213)
-* ENVIRON array <1>: Internals. (line 146)
* ENVIRON array: Auto-set. (line 60)
* environment variables: Auto-set. (line 60)
* epoch, definition of: Glossary. (line 239)
@@ -26769,11 +26475,10 @@ Index
* equals sign (=), == operator: Comparison Operators.
(line 11)
* EREs (Extended Regular Expressions): Bracket Expressions. (line 24)
-* ERRNO variable <1>: Internals. (line 130)
-* ERRNO variable <2>: TCP/IP Networking. (line 54)
-* ERRNO variable <3>: Auto-set. (line 73)
-* ERRNO variable <4>: BEGINFILE/ENDFILE. (line 26)
-* ERRNO variable <5>: Close Files And Pipes.
+* ERRNO variable <1>: TCP/IP Networking. (line 54)
+* ERRNO variable <2>: Auto-set. (line 73)
+* ERRNO variable <3>: BEGINFILE/ENDFILE. (line 26)
+* ERRNO variable <4>: Close Files And Pipes.
(line 139)
* ERRNO variable: Getline. (line 19)
* error handling: Special FD. (line 16)
@@ -26818,7 +26523,6 @@ Index
(line 9)
* expressions, selecting: Conditional Exp. (line 6)
* Extended Regular Expressions (EREs): Bracket Expressions. (line 24)
-* eXtensible Markup Language (XML): Internals. (line 157)
* extension() function (gawk): Using Internal File Ops.
(line 15)
* extensions, Brian Kernighan's awk <1>: Other Versions. (line 13)
@@ -26958,15 +26662,11 @@ Index
(line 6)
* floating-point, numbers <1>: Unexpected Results. (line 6)
* floating-point, numbers: Basic Data Typing. (line 21)
-* floating-point, numbers, AWKNUM internal type: Internals. (line 19)
* FNR variable <1>: Auto-set. (line 103)
* FNR variable: Records. (line 6)
* FNR variable, changing: Auto-set. (line 225)
* for statement: For Statement. (line 6)
* for statement, in arrays: Scanning an Array. (line 20)
-* force_number() internal function: Internals. (line 27)
-* force_string() internal function: Internals. (line 32)
-* force_wstring() internal function: Internals. (line 37)
* format specifiers, mixing regular with positional specifiers: Printf
Ordering.
(line 57)
* format specifiers, printf statement: Control Letters. (line 6)
@@ -27014,7 +26714,7 @@ Index
(line 47)
* functions, built-in <1>: Functions. (line 6)
* functions, built-in: Function Calls. (line 10)
-* functions, built-in, adding to gawk: Dynamic Extensions. (line 10)
+* functions, built-in, adding to gawk: Dynamic Extensions. (line 9)
* functions, built-in, evaluation order: Calling Built-in. (line 30)
* functions, defining: Definition Syntax. (line 6)
* functions, library: Library Functions. (line 6)
@@ -27042,7 +26742,6 @@ Index
* functions, names of <1>: Definition Syntax. (line 20)
* functions, names of: Arrays. (line 18)
* functions, recursive: Definition Syntax. (line 73)
-* functions, return values, setting: Internals. (line 130)
* functions, string-translation: I18N Functions. (line 6)
* functions, undefined: Pass By Value/Reference.
(line 71)
@@ -27096,8 +26795,7 @@ Index
* gawk, FPAT variable in: Splitting By Content.
(line 26)
* gawk, function arguments and: Calling Built-in. (line 16)
-* gawk, functions, adding: Dynamic Extensions. (line 10)
-* gawk, functions, loading: Loading Extensions. (line 6)
+* gawk, functions, adding: Dynamic Extensions. (line 9)
* gawk, hexadecimal numbers and: Nondecimal-numbers. (line 42)
* gawk, IGNORECASE variable in <1>: Array Sorting Functions.
(line 81)
@@ -27112,7 +26810,6 @@ Index
* gawk, implementation issues, limits: Getline Notes. (line 14)
* gawk, implementation issues, pipes: Redirection. (line 135)
* gawk, installing: Installation. (line 6)
-* gawk, internals: Internals. (line 6)
* gawk, internationalization and, See internationalization:
Internationalization.
(line 13)
* gawk, interpreter, adding code to: Using Internal File Ops.
@@ -27158,11 +26855,6 @@ Index
* gensub() function (gawk): Using Constant Regexps.
(line 43)
* gensub() function (gawk), escape processing: Gory Details. (line 6)
-* get_actual_argument() internal function: Internals. (line 116)
-* get_argument() internal function: Internals. (line 111)
-* get_array_argument() internal macro: Internals. (line 127)
-* get_record() input method: Internals. (line 157)
-* get_scalar_argument() internal macro: Internals. (line 124)
* getaddrinfo() function (C library): TCP/IP Networking. (line 38)
* getgrent() function (C library): Group Functions. (line 6)
* getgrent() user-defined function: Group Functions. (line 6)
@@ -27323,37 +27015,6 @@ Index
* integers: Basic Data Typing. (line 21)
* integers, unsigned: Basic Data Typing. (line 30)
* interacting with other programs: I/O Functions. (line 63)
-* internal constant, INVALID_HANDLE: Internals. (line 157)
-* internal function, assoc_clear(): Internals. (line 68)
-* internal function, assoc_lookup(): Internals. (line 72)
-* internal function, dupnode(): Internals. (line 87)
-* internal function, force_number(): Internals. (line 27)
-* internal function, force_string(): Internals. (line 32)
-* internal function, force_wstring(): Internals. (line 37)
-* internal function, get_actual_argument(): Internals. (line 116)
-* internal function, get_argument(): Internals. (line 111)
-* internal function, iop_alloc(): Internals. (line 157)
-* internal function, make_builtin(): Internals. (line 97)
-* internal function, make_number(): Internals. (line 82)
-* internal function, make_string(): Internals. (line 77)
-* internal function, register_deferred_variable(): Internals. (line 146)
-* internal function, register_open_hook(): Internals. (line 157)
-* internal function, unref(): Internals. (line 92)
-* internal function, unset_ERRNO(): Internals. (line 141)
-* internal function, update_ERRNO_int(): Internals. (line 130)
-* internal function, update_ERRNO_string(): Internals. (line 135)
-* internal macro, get_array_argument(): Internals. (line 127)
-* internal macro, get_scalar_argument(): Internals. (line 124)
-* internal structure, IOBUF: Internals. (line 157)
-* internal type, AWKNUM: Internals. (line 19)
-* internal type, NODE: Internals. (line 23)
-* internal variable, nargs: Internals. (line 42)
-* internal variable, stlen: Internals. (line 46)
-* internal variable, stptr: Internals. (line 46)
-* internal variable, type: Internals. (line 59)
-* internal variable, vname: Internals. (line 64)
-* internal variable, wstlen: Internals. (line 54)
-* internal variable, wstptr: Internals. (line 54)
* internationalization <1>: I18N and L10N. (line 6)
* internationalization: I18N Functions. (line 6)
* internationalization, localization <1>: Internationalization.
@@ -27373,10 +27034,7 @@ Index
* interpreted programs <1>: Glossary. (line 361)
* interpreted programs: Basic High Level. (line 14)
* interval expressions: Regexp Operators. (line 116)
-* INVALID_HANDLE internal constant: Internals. (line 157)
* inventory-shipped file: Sample Data Files. (line 32)
-* IOBUF internal structure: Internals. (line 157)
-* iop_alloc() internal function: Internals. (line 157)
* isarray() function (gawk): Type Functions. (line 11)
* ISO: Glossary. (line 372)
* ISO 8859-1: Glossary. (line 141)
@@ -27482,7 +27140,6 @@ Index
* Linux: Manual History. (line 28)
* list debugger command: Miscellaneous Debugger Commands.
(line 74)
-* loading extension: Loading Extensions. (line 6)
* loading, library: Options. (line 173)
* local variables: Variable Scope. (line 6)
* locale categories: Explaining gettext. (line 80)
@@ -27502,15 +27159,11 @@ Index
* loops, count for header: Profiling. (line 123)
* loops, exiting: Break Statement. (line 6)
* loops, See Also while statement: While Statement. (line 6)
-* Lost In Space: Dynamic Extensions. (line 6)
* ls utility: More Complex. (line 15)
* lshift() function (gawk): Bitwise Functions. (line 46)
* lvalues/rvalues: Assignment Ops. (line 32)
* mailing labels, printing: Labels Program. (line 6)
* mailing list, GNITS: Acknowledgments. (line 52)
-* make_builtin() internal function: Internals. (line 97)
-* make_number() internal function: Internals. (line 82)
-* make_string() internal function: Internals. (line 77)
* mark parity: Ordinal Functions. (line 45)
* marked string extraction (internationalization): String Extraction.
(line 6)
@@ -27525,7 +27178,6 @@ Index
* matching, null strings: Gory Details. (line 164)
* mawk program: Other Versions. (line 35)
* McPhee, Patrick: Contributors. (line 100)
-* memory, releasing: Internals. (line 92)
* message object files: Explaining gettext. (line 41)
* message object files, converting from portable object files: I18N Example.
(line 62)
@@ -27551,7 +27203,6 @@ Index
* namespace issues <1>: Library Names. (line 6)
* namespace issues: Arrays. (line 18)
* namespace issues, functions: Definition Syntax. (line 20)
-* nargs internal variable: Internals. (line 42)
* nawk utility: Names. (line 17)
* negative zero: Unexpected Results. (line 28)
* NetBSD: Glossary. (line 611)
@@ -27592,8 +27243,6 @@ Index
* ni debugger command (alias for nexti): Debugger Execution Control.
(line 49)
* noassign.awk program: Ignoring Assigns. (line 15)
-* NODE internal type: Internals. (line 23)
-* nodes, duplicating: Internals. (line 87)
* not Boolean-logic operator: Boolean Ops. (line 6)
* NR variable <1>: Auto-set. (line 119)
* NR variable: Records. (line 6)
@@ -27614,7 +27263,6 @@ Index
* number sign (#), #! (executable scripts), portability issues with:
Executable Scripts.
(line 6)
* number sign (#), commenting: Comments. (line 6)
-* numbers: Internals. (line 82)
* numbers, as array subscripts: Numeric Array Subscripts.
(line 6)
* numbers, as values of characters: Ordinal Functions. (line 6)
@@ -27624,16 +27272,13 @@ Index
* numbers, converting: Conversion. (line 6)
* numbers, converting, to strings: User-modified. (line 28)
* numbers, floating-point: Basic Data Typing. (line 21)
-* numbers, floating-point, AWKNUM internal type: Internals. (line 19)
* numbers, hexadecimal: Nondecimal-numbers. (line 6)
-* numbers, NODE internal type: Internals. (line 23)
* numbers, octal: Nondecimal-numbers. (line 6)
* numbers, random: Numeric Functions. (line 64)
* numbers, rounding: Round Function. (line 6)
* numeric, constants: Scalar Constants. (line 6)
* numeric, output format: OFMT. (line 6)
* numeric, strings: Variable Typing. (line 6)
-* numeric, values: Internals. (line 27)
* o debugger command (alias for option): Debugger Info. (line 57)
* oawk utility: Names. (line 17)
* obsolete features: Obsolete. (line 6)
@@ -27717,7 +27362,6 @@ Index
(line 36)
* P1003.1 POSIX standard: Glossary. (line 454)
* P1003.2 POSIX standard: Glossary. (line 454)
-* parameters, number of: Internals. (line 42)
* parentheses () <1>: Profiling. (line 138)
* parentheses (): Regexp Operators. (line 79)
* password file: Passwd Functions. (line 16)
@@ -27880,13 +27524,12 @@ Index
* private variables: Library Names. (line 11)
* processes, two-way communications with: Two-way I/O. (line 23)
* processing data: Basic High Level. (line 6)
-* PROCINFO array <1>: Internals. (line 146)
-* PROCINFO array <2>: Id Program. (line 15)
-* PROCINFO array <3>: Group Functions. (line 6)
-* PROCINFO array <4>: Passwd Functions. (line 6)
-* PROCINFO array <5>: Two-way I/O. (line 116)
-* PROCINFO array <6>: Time Functions. (line 46)
-* PROCINFO array <7>: Auto-set. (line 124)
+* PROCINFO array <1>: Id Program. (line 15)
+* PROCINFO array <2>: Group Functions. (line 6)
+* PROCINFO array <3>: Passwd Functions. (line 6)
+* PROCINFO array <4>: Two-way I/O. (line 116)
+* PROCINFO array <5>: Time Functions. (line 46)
+* PROCINFO array <6>: Auto-set. (line 124)
* PROCINFO array: Obsolete. (line 11)
* profiling awk programs: Profiling. (line 6)
* profiling awk programs, dynamically: Profiling. (line 171)
@@ -27976,8 +27619,6 @@ Index
* regexp constants, slashes vs. quotes: Computed Regexps. (line 28)
* regexp constants, vs. string constants: Computed Regexps. (line 38)
* regexp, See regular expressions: Regexp. (line 6)
-* register_deferred_variable() internal function: Internals. (line 146)
-* register_open_hook() internal function: Internals. (line 157)
* regular expressions: Regexp. (line 6)
* regular expressions as field separators: Field Separators. (line 50)
* regular expressions, anchors in: Regexp Operators. (line 22)
@@ -28046,8 +27687,6 @@ Index
* Robbins, Miriam <1>: Passwd Functions. (line 90)
* Robbins, Miriam <2>: Getline/Pipe. (line 36)
* Robbins, Miriam: Acknowledgments. (line 83)
-* Robinson, Will: Dynamic Extensions. (line 6)
-* robot, the: Dynamic Extensions. (line 6)
* Rommel, Kai Uwe: Contributors. (line 43)
* round() user-defined function: Round Function. (line 16)
* rounding mode, floating-point: Rounding Mode. (line 6)
@@ -28209,8 +27848,6 @@ Index
(line 68)
* stepi debugger command: Debugger Execution Control.
(line 76)
-* stlen internal variable: Internals. (line 46)
-* stptr internal variable: Internals. (line 46)
* stream editors <1>: Simple Sed. (line 6)
* stream editors: Field Splitting Summary.
(line 47)
@@ -28221,7 +27858,6 @@ Index
(line 6)
* string operators: Concatenation. (line 9)
* string-matching operators: Regexp Usage. (line 19)
-* strings: Internals. (line 77)
* strings, converting <1>: Bitwise Functions. (line 109)
* strings, converting: Conversion. (line 6)
* strings, converting, numbers to: User-modified. (line 28)
@@ -28230,7 +27866,6 @@ Index
* strings, for localization: Programmer i18n. (line 14)
* strings, length of: Scalar Constants. (line 20)
* strings, merging arrays into: Join Function. (line 6)
-* strings, NODE internal type: Internals. (line 23)
* strings, null: Regexp Field Splitting.
(line 43)
* strings, numeric: Variable Typing. (line 6)
@@ -28352,7 +27987,6 @@ Index
* trunc-mod operation: Arithmetic Ops. (line 66)
* truth values: Truth Values. (line 6)
* type conversion: Conversion. (line 21)
-* type internal variable: Internals. (line 59)
* u debugger command (alias for until): Debugger Execution Control.
(line 83)
* undefined functions: Pass By Value/Reference.
@@ -28378,16 +28012,12 @@ Index
(line 72)
* Unix, awk scripts and: Executable Scripts. (line 6)
* UNIXROOT variable, on OS/2 systems: PC Using. (line 17)
-* unref() internal function: Internals. (line 92)
-* unset_ERRNO() internal function: Internals. (line 141)
* unsigned integers: Basic Data Typing. (line 30)
* until debugger command: Debugger Execution Control.
(line 83)
* unwatch debugger command: Viewing And Changing Data.
(line 84)
* up debugger command: Execution Stack. (line 33)
-* update_ERRNO_int() internal function: Internals. (line 130)
-* update_ERRNO_string() internal function: Internals. (line 135)
* user database, reading: Passwd Functions. (line 6)
* user-defined, functions: User-defined. (line 6)
* user-defined, functions, counts: Profiling. (line 129)
@@ -28438,7 +28068,6 @@ Index
* vertical bar (|), || operator <1>: Precedence. (line 89)
* vertical bar (|), || operator: Boolean Ops. (line 57)
* Vinschen, Corinna: Acknowledgments. (line 60)
-* vname internal variable: Internals. (line 64)
* w debugger command (alias for watch): Viewing And Changing Data.
(line 67)
* w utility: Constant Size. (line 22)
@@ -28472,11 +28101,8 @@ Index
* words, counting: Wc Program. (line 6)
* words, duplicate, searching for: Dupword Program. (line 6)
* words, usage counts, generating: Word Sorting. (line 6)
-* wstlen internal variable: Internals. (line 54)
-* wstptr internal variable: Internals. (line 54)
* xgawk: Other Versions. (line 120)
* xgettext utility: String Extraction. (line 13)
-* XML (eXtensible Markup Language): Internals. (line 157)
* XOR bitwise operation: Bitwise Functions. (line 6)
* xor() function (gawk): Bitwise Functions. (line 55)
* Yawitz, Efraim: Contributors. (line 106)
@@ -28514,442 +28140,440 @@ Index
Tag Table:
Node: Top1352
-Node: Foreword31758
-Node: Preface36103
-Ref: Preface-Footnote-139156
-Ref: Preface-Footnote-239262
-Node: History39494
-Node: Names41885
-Ref: Names-Footnote-143362
-Node: This Manual43434
-Ref: This Manual-Footnote-148372
-Node: Conventions48472
-Node: Manual History50606
-Ref: Manual History-Footnote-153876
-Ref: Manual History-Footnote-253917
-Node: How To Contribute53991
-Node: Acknowledgments55135
-Node: Getting Started59631
-Node: Running gawk62010
-Node: One-shot63196
-Node: Read Terminal64421
-Ref: Read Terminal-Footnote-166071
-Ref: Read Terminal-Footnote-266347
-Node: Long66518
-Node: Executable Scripts67894
-Ref: Executable Scripts-Footnote-169763
-Ref: Executable Scripts-Footnote-269865
-Node: Comments70412
-Node: Quoting72879
-Node: DOS Quoting77502
-Node: Sample Data Files78177
-Node: Very Simple81209
-Node: Two Rules85808
-Node: More Complex87955
-Ref: More Complex-Footnote-190885
-Node: Statements/Lines90970
-Ref: Statements/Lines-Footnote-195432
-Node: Other Features95697
-Node: When96625
-Node: Invoking Gawk98772
-Node: Command Line100233
-Node: Options101016
-Ref: Options-Footnote-1116414
-Node: Other Arguments116439
-Node: Naming Standard Input119097
-Node: Environment Variables120191
-Node: AWKPATH Variable120749
-Ref: AWKPATH Variable-Footnote-1123507
-Node: AWKLIBPATH Variable123767
-Node: Other Environment Variables124364
-Node: Exit Status126859
-Node: Include Files127534
-Node: Loading Shared Libraries131103
-Node: Obsolete132328
-Node: Undocumented133025
-Node: Regexp133268
-Node: Regexp Usage134657
-Node: Escape Sequences136683
-Node: Regexp Operators142446
-Ref: Regexp Operators-Footnote-1149826
-Ref: Regexp Operators-Footnote-2149973
-Node: Bracket Expressions150071
-Ref: table-char-classes151961
-Node: GNU Regexp Operators154484
-Node: Case-sensitivity158207
-Ref: Case-sensitivity-Footnote-1161175
-Ref: Case-sensitivity-Footnote-2161410
-Node: Leftmost Longest161518
-Node: Computed Regexps162719
-Node: Reading Files166129
-Node: Records168133
-Ref: Records-Footnote-1176807
-Node: Fields176844
-Ref: Fields-Footnote-1179877
-Node: Nonconstant Fields179963
-Node: Changing Fields182165
-Node: Field Separators188146
-Node: Default Field Splitting190775
-Node: Regexp Field Splitting191892
-Node: Single Character Fields195234
-Node: Command Line Field Separator196293
-Node: Field Splitting Summary199734
-Ref: Field Splitting Summary-Footnote-1202926
-Node: Constant Size203027
-Node: Splitting By Content207611
-Ref: Splitting By Content-Footnote-1211337
-Node: Multiple Line211377
-Ref: Multiple Line-Footnote-1217224
-Node: Getline217403
-Node: Plain Getline219619
-Node: Getline/Variable221708
-Node: Getline/File222849
-Node: Getline/Variable/File224171
-Ref: Getline/Variable/File-Footnote-1225770
-Node: Getline/Pipe225857
-Node: Getline/Variable/Pipe228417
-Node: Getline/Coprocess229524
-Node: Getline/Variable/Coprocess230767
-Node: Getline Notes231481
-Node: Getline Summary233423
-Ref: table-getline-variants233831
-Node: Read Timeout234687
-Ref: Read Timeout-Footnote-1238432
-Node: Command line directories238489
-Node: Printing239119
-Node: Print240750
-Node: Print Examples242087
-Node: Output Separators244871
-Node: OFMT246631
-Node: Printf247989
-Node: Basic Printf248895
-Node: Control Letters250434
-Node: Format Modifiers254246
-Node: Printf Examples260255
-Node: Redirection262970
-Node: Special Files269954
-Node: Special FD270487
-Ref: Special FD-Footnote-1274112
-Node: Special Network274186
-Node: Special Caveats275036
-Node: Close Files And Pipes275832
-Ref: Close Files And Pipes-Footnote-1282855
-Ref: Close Files And Pipes-Footnote-2283003
-Node: Expressions283153
-Node: Values284285
-Node: Constants284961
-Node: Scalar Constants285641
-Ref: Scalar Constants-Footnote-1286500
-Node: Nondecimal-numbers286682
-Node: Regexp Constants289741
-Node: Using Constant Regexps290216
-Node: Variables293271
-Node: Using Variables293926
-Node: Assignment Options295650
-Node: Conversion297522
-Ref: table-locale-affects302898
-Ref: Conversion-Footnote-1303522
-Node: All Operators303631
-Node: Arithmetic Ops304261
-Node: Concatenation306766
-Ref: Concatenation-Footnote-1309559
-Node: Assignment Ops309679
-Ref: table-assign-ops314667
-Node: Increment Ops316075
-Node: Truth Values and Conditions319545
-Node: Truth Values320628
-Node: Typing and Comparison321677
-Node: Variable Typing322466
-Ref: Variable Typing-Footnote-1326363
-Node: Comparison Operators326485
-Ref: table-relational-ops326895
-Node: POSIX String Comparison330444
-Ref: POSIX String Comparison-Footnote-1331400
-Node: Boolean Ops331538
-Ref: Boolean Ops-Footnote-1335616
-Node: Conditional Exp335707
-Node: Function Calls337439
-Node: Precedence341033
-Node: Locales344702
-Node: Patterns and Actions345791
-Node: Pattern Overview346845
-Node: Regexp Patterns348514
-Node: Expression Patterns349057
-Node: Ranges352742
-Node: BEGIN/END355708
-Node: Using BEGIN/END356470
-Ref: Using BEGIN/END-Footnote-1359201
-Node: I/O And BEGIN/END359307
-Node: BEGINFILE/ENDFILE361589
-Node: Empty364482
-Node: Using Shell Variables364798
-Node: Action Overview367083
-Node: Statements369440
-Node: If Statement371294
-Node: While Statement372793
-Node: Do Statement374837
-Node: For Statement375993
-Node: Switch Statement379145
-Node: Break Statement381242
-Node: Continue Statement383232
-Node: Next Statement385025
-Node: Nextfile Statement387415
-Node: Exit Statement389960
-Node: Built-in Variables392376
-Node: User-modified393471
-Ref: User-modified-Footnote-1401826
-Node: Auto-set401888
-Ref: Auto-set-Footnote-1411796
-Node: ARGC and ARGV412001
-Node: Arrays415852
-Node: Array Basics417357
-Node: Array Intro418183
-Node: Reference to Elements422501
-Node: Assigning Elements424771
-Node: Array Example425262
-Node: Scanning an Array426994
-Node: Controlling Scanning429308
-Ref: Controlling Scanning-Footnote-1434241
-Node: Delete434557
-Ref: Delete-Footnote-1436992
-Node: Numeric Array Subscripts437049
-Node: Uninitialized Subscripts439232
-Node: Multi-dimensional440860
-Node: Multi-scanning443954
-Node: Arrays of Arrays445545
-Node: Functions450190
-Node: Built-in451012
-Node: Calling Built-in452090
-Node: Numeric Functions454078
-Ref: Numeric Functions-Footnote-1457910
-Ref: Numeric Functions-Footnote-2458267
-Ref: Numeric Functions-Footnote-3458315
-Node: String Functions458584
-Ref: String Functions-Footnote-1482081
-Ref: String Functions-Footnote-2482210
-Ref: String Functions-Footnote-3482458
-Node: Gory Details482545
-Ref: table-sub-escapes484224
-Ref: table-sub-posix-92485578
-Ref: table-sub-proposed486921
-Ref: table-posix-sub488271
-Ref: table-gensub-escapes489817
-Ref: Gory Details-Footnote-1491024
-Ref: Gory Details-Footnote-2491075
-Node: I/O Functions491226
-Ref: I/O Functions-Footnote-1497881
-Node: Time Functions498028
-Ref: Time Functions-Footnote-1508920
-Ref: Time Functions-Footnote-2508988
-Ref: Time Functions-Footnote-3509146
-Ref: Time Functions-Footnote-4509257
-Ref: Time Functions-Footnote-5509369
-Ref: Time Functions-Footnote-6509596
-Node: Bitwise Functions509862
-Ref: table-bitwise-ops510420
-Ref: Bitwise Functions-Footnote-1514641
-Node: Type Functions514825
-Node: I18N Functions515295
-Node: User-defined516922
-Node: Definition Syntax517726
-Ref: Definition Syntax-Footnote-1522636
-Node: Function Example522705
-Node: Function Caveats525299
-Node: Calling A Function525720
-Node: Variable Scope526835
-Node: Pass By Value/Reference528810
-Node: Return Statement532250
-Node: Dynamic Typing535231
-Node: Indirect Calls535966
-Node: Internationalization545651
-Node: I18N and L10N547090
-Node: Explaining gettext547776
-Ref: Explaining gettext-Footnote-1552842
-Ref: Explaining gettext-Footnote-2553026
-Node: Programmer i18n553191
-Node: Translator i18n557391
-Node: String Extraction558184
-Ref: String Extraction-Footnote-1559145
-Node: Printf Ordering559231
-Ref: Printf Ordering-Footnote-1562015
-Node: I18N Portability562079
-Ref: I18N Portability-Footnote-1564528
-Node: I18N Example564591
-Ref: I18N Example-Footnote-1567226
-Node: Gawk I18N567298
-Node: Arbitrary Precision Arithmetic567915
-Ref: Arbitrary Precision Arithmetic-Footnote-1570790
-Node: Floating-point Programming570938
-Node: Floating-point Representation576208
-Node: Floating-point Context577312
-Ref: table-ieee-formats578147
-Node: Rounding Mode579517
-Ref: table-rounding-modes580144
-Ref: Rounding Mode-Footnote-1583267
-Node: Arbitrary Precision Floats583448
-Ref: Arbitrary Precision Floats-Footnote-1585489
-Node: Setting Precision585800
-Node: Setting Rounding Mode588558
-Node: Floating-point Constants589475
-Node: Changing Precision590894
-Ref: Changing Precision-Footnote-1592294
-Node: Exact Arithmetic592467
-Node: Integer Programming595480
-Node: Arbitrary Precision Integers597260
-Ref: Arbitrary Precision Integers-Footnote-1600284
-Node: MPFR and GMP Libraries600430
-Node: Advanced Features600815
-Node: Nondecimal Data602338
-Node: Array Sorting603921
-Node: Controlling Array Traversal604618
-Node: Array Sorting Functions612855
-Ref: Array Sorting Functions-Footnote-1616529
-Ref: Array Sorting Functions-Footnote-2616622
-Node: Two-way I/O616816
-Ref: Two-way I/O-Footnote-1622248
-Node: TCP/IP Networking622318
-Node: Profiling625162
-Node: Library Functions632616
-Ref: Library Functions-Footnote-1635623
-Node: Library Names635794
-Ref: Library Names-Footnote-1639265
-Ref: Library Names-Footnote-2639485
-Node: General Functions639571
-Node: Strtonum Function640524
-Node: Assert Function643454
-Node: Round Function646780
-Node: Cliff Random Function648323
-Node: Ordinal Functions649339
-Ref: Ordinal Functions-Footnote-1652409
-Ref: Ordinal Functions-Footnote-2652661
-Node: Join Function652870
-Ref: Join Function-Footnote-1654641
-Node: Getlocaltime Function654841
-Node: Data File Management658556
-Node: Filetrans Function659188
-Node: Rewind Function663327
-Node: File Checking664714
-Node: Empty Files665808
-Node: Ignoring Assigns668038
-Node: Getopt Function669591
-Ref: Getopt Function-Footnote-1680895
-Node: Passwd Functions681098
-Ref: Passwd Functions-Footnote-1690073
-Node: Group Functions690161
-Node: Walking Arrays698245
-Node: Sample Programs699814
-Node: Running Examples700479
-Node: Clones701207
-Node: Cut Program702431
-Node: Egrep Program712276
-Ref: Egrep Program-Footnote-1720049
-Node: Id Program720159
-Node: Split Program723775
-Ref: Split Program-Footnote-1727294
-Node: Tee Program727422
-Node: Uniq Program730225
-Node: Wc Program737654
-Ref: Wc Program-Footnote-1741920
-Ref: Wc Program-Footnote-2742120
-Node: Miscellaneous Programs742212
-Node: Dupword Program743400
-Node: Alarm Program745431
-Node: Translate Program750180
-Ref: Translate Program-Footnote-1754567
-Ref: Translate Program-Footnote-2754795
-Node: Labels Program754929
-Ref: Labels Program-Footnote-1758300
-Node: Word Sorting758384
-Node: History Sorting762268
-Node: Extract Program764107
-Ref: Extract Program-Footnote-1771590
-Node: Simple Sed771718
-Node: Igawk Program774780
-Ref: Igawk Program-Footnote-1789937
-Ref: Igawk Program-Footnote-2790138
-Node: Anagram Program790276
-Node: Signature Program793344
-Node: Debugger794444
-Node: Debugging795396
-Node: Debugging Concepts795829
-Node: Debugging Terms797685
-Node: Awk Debugging800282
-Node: Sample Debugging Session801174
-Node: Debugger Invocation801694
-Node: Finding The Bug803023
-Node: List of Debugger Commands809511
-Node: Breakpoint Control810845
-Node: Debugger Execution Control814509
-Node: Viewing And Changing Data817869
-Node: Execution Stack821225
-Node: Debugger Info822692
-Node: Miscellaneous Debugger Commands826673
-Node: Readline Support832118
-Node: Limitations832949
-Node: Language History835201
-Node: V7/SVR3.1836713
-Node: SVR4839034
-Node: POSIX840476
-Node: BTL841484
-Node: POSIX/GNU842218
-Node: Common Extensions847509
-Node: Ranges and Locales848616
-Ref: Ranges and Locales-Footnote-1853220
-Node: Contributors853441
-Node: Installation857702
-Node: Gawk Distribution858596
-Node: Getting859080
-Node: Extracting859906
-Node: Distribution contents861598
-Node: Unix Installation866820
-Node: Quick Installation867437
-Node: Additional Configuration Options869399
-Node: Configuration Philosophy870876
-Node: Non-Unix Installation873218
-Node: PC Installation873676
-Node: PC Binary Installation874975
-Node: PC Compiling876823
-Node: PC Testing879767
-Node: PC Using880943
-Node: Cygwin885128
-Node: MSYS886128
-Node: VMS Installation886642
-Node: VMS Compilation887245
-Ref: VMS Compilation-Footnote-1888252
-Node: VMS Installation Details888310
-Node: VMS Running889945
-Node: VMS Old Gawk891552
-Node: Bugs892026
-Node: Other Versions895878
-Node: Notes901193
-Node: Compatibility Mode901885
-Node: Additions902668
-Node: Accessing The Source903480
-Node: Adding Code904905
-Node: New Ports910872
-Node: Dynamic Extensions914985
-Node: Internals916425
-Node: Plugin License925247
-Node: Loading Extensions925885
-Node: Sample Library927726
-Node: Internal File Description928416
-Node: Internal File Ops932131
-Ref: Internal File Ops-Footnote-1936696
-Node: Using Internal File Ops936836
-Node: Future Extensions939214
-Node: Basic Concepts941718
-Node: Basic High Level942475
-Ref: Basic High Level-Footnote-1946510
-Node: Basic Data Typing946695
-Node: Floating Point Issues951220
-Node: String Conversion Precision952303
-Ref: String Conversion Precision-Footnote-1954003
-Node: Unexpected Results954112
-Node: POSIX Floating Point Problems955938
-Ref: POSIX Floating Point Problems-Footnote-1959643
-Node: Glossary959681
-Node: Copying984657
-Node: GNU Free Documentation License1022214
-Node: Index1047351
+Node: Foreword31579
+Node: Preface35924
+Ref: Preface-Footnote-138977
+Ref: Preface-Footnote-239083
+Node: History39315
+Node: Names41706
+Ref: Names-Footnote-143183
+Node: This Manual43255
+Ref: This Manual-Footnote-148159
+Node: Conventions48259
+Node: Manual History50393
+Ref: Manual History-Footnote-153663
+Ref: Manual History-Footnote-253704
+Node: How To Contribute53778
+Node: Acknowledgments54922
+Node: Getting Started59418
+Node: Running gawk61797
+Node: One-shot62983
+Node: Read Terminal64208
+Ref: Read Terminal-Footnote-165858
+Ref: Read Terminal-Footnote-266134
+Node: Long66305
+Node: Executable Scripts67681
+Ref: Executable Scripts-Footnote-169550
+Ref: Executable Scripts-Footnote-269652
+Node: Comments70199
+Node: Quoting72666
+Node: DOS Quoting77289
+Node: Sample Data Files77964
+Node: Very Simple80996
+Node: Two Rules85595
+Node: More Complex87742
+Ref: More Complex-Footnote-190672
+Node: Statements/Lines90757
+Ref: Statements/Lines-Footnote-195219
+Node: Other Features95484
+Node: When96412
+Node: Invoking Gawk98559
+Node: Command Line100020
+Node: Options100803
+Ref: Options-Footnote-1116201
+Node: Other Arguments116226
+Node: Naming Standard Input118884
+Node: Environment Variables119978
+Node: AWKPATH Variable120536
+Ref: AWKPATH Variable-Footnote-1123294
+Node: AWKLIBPATH Variable123554
+Node: Other Environment Variables124151
+Node: Exit Status126646
+Node: Include Files127321
+Node: Loading Shared Libraries130890
+Node: Obsolete132115
+Node: Undocumented132812
+Node: Regexp133055
+Node: Regexp Usage134444
+Node: Escape Sequences136470
+Node: Regexp Operators142233
+Ref: Regexp Operators-Footnote-1149613
+Ref: Regexp Operators-Footnote-2149760
+Node: Bracket Expressions149858
+Ref: table-char-classes151748
+Node: GNU Regexp Operators154271
+Node: Case-sensitivity157994
+Ref: Case-sensitivity-Footnote-1160962
+Ref: Case-sensitivity-Footnote-2161197
+Node: Leftmost Longest161305
+Node: Computed Regexps162506
+Node: Reading Files165916
+Node: Records167919
+Ref: Records-Footnote-1176593
+Node: Fields176630
+Ref: Fields-Footnote-1179663
+Node: Nonconstant Fields179749
+Node: Changing Fields181951
+Node: Field Separators187932
+Node: Default Field Splitting190561
+Node: Regexp Field Splitting191678
+Node: Single Character Fields195020
+Node: Command Line Field Separator196079
+Node: Field Splitting Summary199520
+Ref: Field Splitting Summary-Footnote-1202712
+Node: Constant Size202813
+Node: Splitting By Content207397
+Ref: Splitting By Content-Footnote-1211123
+Node: Multiple Line211163
+Ref: Multiple Line-Footnote-1217010
+Node: Getline217189
+Node: Plain Getline219405
+Node: Getline/Variable221494
+Node: Getline/File222635
+Node: Getline/Variable/File223957
+Ref: Getline/Variable/File-Footnote-1225556
+Node: Getline/Pipe225643
+Node: Getline/Variable/Pipe228203
+Node: Getline/Coprocess229310
+Node: Getline/Variable/Coprocess230553
+Node: Getline Notes231267
+Node: Getline Summary233209
+Ref: table-getline-variants233617
+Node: Read Timeout234473
+Ref: Read Timeout-Footnote-1238218
+Node: Command line directories238275
+Node: Printing238905
+Node: Print240536
+Node: Print Examples241873
+Node: Output Separators244657
+Node: OFMT246417
+Node: Printf247775
+Node: Basic Printf248681
+Node: Control Letters250220
+Node: Format Modifiers254032
+Node: Printf Examples260041
+Node: Redirection262756
+Node: Special Files269740
+Node: Special FD270273
+Ref: Special FD-Footnote-1273898
+Node: Special Network273972
+Node: Special Caveats274822
+Node: Close Files And Pipes275618
+Ref: Close Files And Pipes-Footnote-1282641
+Ref: Close Files And Pipes-Footnote-2282789
+Node: Expressions282939
+Node: Values284071
+Node: Constants284747
+Node: Scalar Constants285427
+Ref: Scalar Constants-Footnote-1286286
+Node: Nondecimal-numbers286468
+Node: Regexp Constants289527
+Node: Using Constant Regexps290002
+Node: Variables293057
+Node: Using Variables293712
+Node: Assignment Options295436
+Node: Conversion297308
+Ref: table-locale-affects302684
+Ref: Conversion-Footnote-1303308
+Node: All Operators303417
+Node: Arithmetic Ops304047
+Node: Concatenation306552
+Ref: Concatenation-Footnote-1309345
+Node: Assignment Ops309465
+Ref: table-assign-ops314453
+Node: Increment Ops315861
+Node: Truth Values and Conditions319331
+Node: Truth Values320414
+Node: Typing and Comparison321463
+Node: Variable Typing322252
+Ref: Variable Typing-Footnote-1326149
+Node: Comparison Operators326271
+Ref: table-relational-ops326681
+Node: POSIX String Comparison330230
+Ref: POSIX String Comparison-Footnote-1331186
+Node: Boolean Ops331324
+Ref: Boolean Ops-Footnote-1335402
+Node: Conditional Exp335493
+Node: Function Calls337225
+Node: Precedence340819
+Node: Locales344488
+Node: Patterns and Actions345577
+Node: Pattern Overview346631
+Node: Regexp Patterns348300
+Node: Expression Patterns348843
+Node: Ranges352528
+Node: BEGIN/END355494
+Node: Using BEGIN/END356256
+Ref: Using BEGIN/END-Footnote-1358987
+Node: I/O And BEGIN/END359093
+Node: BEGINFILE/ENDFILE361375
+Node: Empty364279
+Node: Using Shell Variables364595
+Node: Action Overview366880
+Node: Statements369237
+Node: If Statement371091
+Node: While Statement372590
+Node: Do Statement374634
+Node: For Statement375790
+Node: Switch Statement378942
+Node: Break Statement381039
+Node: Continue Statement383029
+Node: Next Statement384822
+Node: Nextfile Statement387212
+Node: Exit Statement389757
+Node: Built-in Variables392173
+Node: User-modified393268
+Ref: User-modified-Footnote-1401623
+Node: Auto-set401685
+Ref: Auto-set-Footnote-1411593
+Node: ARGC and ARGV411798
+Node: Arrays415649
+Node: Array Basics417154
+Node: Array Intro417980
+Node: Reference to Elements422298
+Node: Assigning Elements424568
+Node: Array Example425059
+Node: Scanning an Array426791
+Node: Controlling Scanning429105
+Ref: Controlling Scanning-Footnote-1434038
+Node: Delete434354
+Ref: Delete-Footnote-1436789
+Node: Numeric Array Subscripts436846
+Node: Uninitialized Subscripts439029
+Node: Multi-dimensional440657
+Node: Multi-scanning443751
+Node: Arrays of Arrays445342
+Node: Functions449987
+Node: Built-in450809
+Node: Calling Built-in451887
+Node: Numeric Functions453875
+Ref: Numeric Functions-Footnote-1457707
+Ref: Numeric Functions-Footnote-2458064
+Ref: Numeric Functions-Footnote-3458112
+Node: String Functions458381
+Ref: String Functions-Footnote-1481878
+Ref: String Functions-Footnote-2482007
+Ref: String Functions-Footnote-3482255
+Node: Gory Details482342
+Ref: table-sub-escapes484021
+Ref: table-sub-posix-92485375
+Ref: table-sub-proposed486718
+Ref: table-posix-sub488068
+Ref: table-gensub-escapes489614
+Ref: Gory Details-Footnote-1490821
+Ref: Gory Details-Footnote-2490872
+Node: I/O Functions491023
+Ref: I/O Functions-Footnote-1497678
+Node: Time Functions497825
+Ref: Time Functions-Footnote-1508717
+Ref: Time Functions-Footnote-2508785
+Ref: Time Functions-Footnote-3508943
+Ref: Time Functions-Footnote-4509054
+Ref: Time Functions-Footnote-5509166
+Ref: Time Functions-Footnote-6509393
+Node: Bitwise Functions509659
+Ref: table-bitwise-ops510217
+Ref: Bitwise Functions-Footnote-1514438
+Node: Type Functions514622
+Node: I18N Functions515092
+Node: User-defined516719
+Node: Definition Syntax517523
+Ref: Definition Syntax-Footnote-1522433
+Node: Function Example522502
+Node: Function Caveats525096
+Node: Calling A Function525517
+Node: Variable Scope526632
+Node: Pass By Value/Reference528607
+Node: Return Statement532047
+Node: Dynamic Typing535028
+Node: Indirect Calls535763
+Node: Internationalization545448
+Node: I18N and L10N546887
+Node: Explaining gettext547573
+Ref: Explaining gettext-Footnote-1552639
+Ref: Explaining gettext-Footnote-2552823
+Node: Programmer i18n552988
+Node: Translator i18n557188
+Node: String Extraction557981
+Ref: String Extraction-Footnote-1558942
+Node: Printf Ordering559028
+Ref: Printf Ordering-Footnote-1561812
+Node: I18N Portability561876
+Ref: I18N Portability-Footnote-1564325
+Node: I18N Example564388
+Ref: I18N Example-Footnote-1567023
+Node: Gawk I18N567095
+Node: Arbitrary Precision Arithmetic567712
+Ref: Arbitrary Precision Arithmetic-Footnote-1570464
+Node: Floating-point Programming570612
+Node: Floating-point Representation575882
+Node: Floating-point Context576986
+Ref: table-ieee-formats577821
+Node: Rounding Mode579191
+Ref: table-rounding-modes579818
+Ref: Rounding Mode-Footnote-1582941
+Node: Arbitrary Precision Floats583122
+Ref: Arbitrary Precision Floats-Footnote-1585163
+Node: Setting Precision585474
+Node: Setting Rounding Mode588232
+Node: Floating-point Constants589149
+Node: Changing Precision590568
+Ref: Changing Precision-Footnote-1591968
+Node: Exact Arithmetic592141
+Node: Integer Programming595154
+Node: Arbitrary Precision Integers596934
+Ref: Arbitrary Precision Integers-Footnote-1599958
+Node: MPFR and GMP Libraries600104
+Node: Advanced Features600489
+Node: Nondecimal Data602012
+Node: Array Sorting603595
+Node: Controlling Array Traversal604292
+Node: Array Sorting Functions612529
+Ref: Array Sorting Functions-Footnote-1616203
+Ref: Array Sorting Functions-Footnote-2616296
+Node: Two-way I/O616490
+Ref: Two-way I/O-Footnote-1621922
+Node: TCP/IP Networking621992
+Node: Profiling624836
+Node: Library Functions632290
+Ref: Library Functions-Footnote-1635297
+Node: Library Names635468
+Ref: Library Names-Footnote-1638939
+Ref: Library Names-Footnote-2639159
+Node: General Functions639245
+Node: Strtonum Function640198
+Node: Assert Function643128
+Node: Round Function646454
+Node: Cliff Random Function647997
+Node: Ordinal Functions649013
+Ref: Ordinal Functions-Footnote-1652083
+Ref: Ordinal Functions-Footnote-2652335
+Node: Join Function652544
+Ref: Join Function-Footnote-1654315
+Node: Getlocaltime Function654515
+Node: Data File Management658230
+Node: Filetrans Function658862
+Node: Rewind Function663001
+Node: File Checking664388
+Node: Empty Files665482
+Node: Ignoring Assigns667712
+Node: Getopt Function669265
+Ref: Getopt Function-Footnote-1680569
+Node: Passwd Functions680772
+Ref: Passwd Functions-Footnote-1689747
+Node: Group Functions689835
+Node: Walking Arrays697919
+Node: Sample Programs699488
+Node: Running Examples700153
+Node: Clones700881
+Node: Cut Program702105
+Node: Egrep Program711950
+Ref: Egrep Program-Footnote-1719723
+Node: Id Program719833
+Node: Split Program723449
+Ref: Split Program-Footnote-1726968
+Node: Tee Program727096
+Node: Uniq Program729899
+Node: Wc Program737328
+Ref: Wc Program-Footnote-1741594
+Ref: Wc Program-Footnote-2741794
+Node: Miscellaneous Programs741886
+Node: Dupword Program743074
+Node: Alarm Program745105
+Node: Translate Program749854
+Ref: Translate Program-Footnote-1754241
+Ref: Translate Program-Footnote-2754469
+Node: Labels Program754603
+Ref: Labels Program-Footnote-1757974
+Node: Word Sorting758058
+Node: History Sorting761942
+Node: Extract Program763781
+Ref: Extract Program-Footnote-1771264
+Node: Simple Sed771392
+Node: Igawk Program774454
+Ref: Igawk Program-Footnote-1789611
+Ref: Igawk Program-Footnote-2789812
+Node: Anagram Program789950
+Node: Signature Program793018
+Node: Debugger794118
+Node: Debugging795072
+Node: Debugging Concepts795505
+Node: Debugging Terms797361
+Node: Awk Debugging799958
+Node: Sample Debugging Session800850
+Node: Debugger Invocation801370
+Node: Finding The Bug802699
+Node: List of Debugger Commands809187
+Node: Breakpoint Control810521
+Node: Debugger Execution Control814185
+Node: Viewing And Changing Data817545
+Node: Execution Stack820901
+Node: Debugger Info822368
+Node: Miscellaneous Debugger Commands826349
+Node: Readline Support831794
+Node: Limitations832625
+Node: Dynamic Extensions834877
+Node: Plugin License835773
+Node: Sample Library836387
+Node: Internal File Description837071
+Node: Internal File Ops840784
+Ref: Internal File Ops-Footnote-1845347
+Node: Using Internal File Ops845487
+Node: Language History847863
+Node: V7/SVR3.1849385
+Node: SVR4851706
+Node: POSIX853148
+Node: BTL854156
+Node: POSIX/GNU854890
+Node: Common Extensions860146
+Node: Ranges and Locales861253
+Ref: Ranges and Locales-Footnote-1865857
+Node: Contributors866078
+Node: Installation870374
+Node: Gawk Distribution871268
+Node: Getting871752
+Node: Extracting872578
+Node: Distribution contents874270
+Node: Unix Installation879492
+Node: Quick Installation880109
+Node: Additional Configuration Options882071
+Node: Configuration Philosophy883548
+Node: Non-Unix Installation885890
+Node: PC Installation886348
+Node: PC Binary Installation887647
+Node: PC Compiling889495
+Node: PC Testing892439
+Node: PC Using893615
+Node: Cygwin897800
+Node: MSYS898800
+Node: VMS Installation899314
+Node: VMS Compilation899917
+Ref: VMS Compilation-Footnote-1900924
+Node: VMS Installation Details900982
+Node: VMS Running902617
+Node: VMS Old Gawk904224
+Node: Bugs904698
+Node: Other Versions908550
+Node: Notes913865
+Node: Compatibility Mode914452
+Node: Additions915235
+Node: Accessing The Source916046
+Node: Adding Code917471
+Node: New Ports923479
+Node: Future Extensions927592
+Node: Basic Concepts929079
+Node: Basic High Level929836
+Ref: Basic High Level-Footnote-1933871
+Node: Basic Data Typing934056
+Node: Floating Point Issues938581
+Node: String Conversion Precision939664
+Ref: String Conversion Precision-Footnote-1941364
+Node: Unexpected Results941473
+Node: POSIX Floating Point Problems943299
+Ref: POSIX Floating Point Problems-Footnote-1947004
+Node: Glossary947042
+Node: Copying972018
+Node: GNU Free Documentation License1009575
+Node: Index1034712
End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index 12b7755..ceea9a9 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -295,12 +295,14 @@ particular records in a file and perform operations upon
them.
* Sample Programs:: Many @command{awk} programs with complete
explanations.
* Debugger:: The @code{gawk} debugger.
+* Dynamic Extensions:: Adding new built-in functions to
+ @command{gawk}.
* Language History:: The evolution of the @command{awk}
language.
* Installation:: Installing @command{gawk} under various
operating systems.
-* Notes:: Notes about @command{gawk} extensions and
- possible future work.
+* Notes:: Notes about adding things to @command{gawk}
+ and possible future work.
* Basic Concepts:: A very quick introduction to programming
concepts.
* Glossary:: An explanation of some unfamiliar terms.
@@ -558,21 +560,22 @@ particular records in a file and perform operations upon
them.
* I18N Portability:: @command{awk}-level portability issues.
* I18N Example:: A simple i18n example.
* Gawk I18N:: @command{gawk} is also internationalized.
-* Floating-point Programming:: Effective floating-point programming.
-* Floating-point Representation:: Binary floating-point representation.
-* Floating-point Context:: Floating-point context.
-* Rounding Mode:: Floating-point rounding mode.
-* Arbitrary Precision Floats:: Arbitrary precision floating-point
- arithmetic with @command{gawk}.
-* Setting Precision:: Setting the working precision.
-* Setting Rounding Mode:: Setting the rounding mode.
-* Floating-point Constants:: Representing floating-point constants.
-* Changing Precision:: Changing the precision of a number.
-* Exact Arithmetic:: Exact arithmetic with floating-point
numbers.
-* Integer Programming:: Effective integer programming.
-* Arbitrary Precision Integers:: Arbitrary precision integer
- arithmetic with @command{gawk}.
-* MPFR and GMP Libraries:: Information about the MPFR and GMP
libraries.
+* Floating-point Programming:: Effective Floating-point Programming.
+* Floating-point Representation:: Binary Floating-point Representation.
+* Floating-point Context:: Floating-point Context.
+* Rounding Mode:: Floating-point Rounding Mode.
+* Arbitrary Precision Floats:: Arbitrary Precision Floating-point
+ Arithmetic with @command{gawk}.
+* Setting Precision:: Setting the Working Precision.
+* Setting Rounding Mode:: Setting the Rounding Mode.
+* Floating-point Constants:: Representing Floating-point Constants.
+* Changing Precision:: Changing the Precision of a Number.
+* Exact Arithmetic:: Exact Arithmetic with Floating-point
+ Numbers.
+* Integer Programming:: Effective Integer Programming.
+* Arbitrary Precision Integers:: Arbitrary Precision Integer Arithmetic with
+ @command{gawk}.
+* MPFR and GMP Libraries ::
* Nondecimal Data:: Allowing nondecimal input data.
* Array Sorting:: Facilities for controlling array traversal
and sorting arrays.
@@ -637,14 +640,14 @@ particular records in a file and perform operations upon
them.
* Anagram Program:: Finding anagrams from a dictionary.
* Signature Program:: People do amazing things with too much time
on their hands.
-* Debugging:: Introduction to @command{gawk} Debugger.
+* Debugging:: Introduction to @command{gawk} debugger.
* Debugging Concepts:: Debugging in General.
* Debugging Terms:: Additional Debugging Concepts.
* Awk Debugging:: Awk Debugging.
-* Sample Debugging Session:: Sample Debugging Session.
+* Sample Debugging Session:: Sample debugging session.
* Debugger Invocation:: How to Start the Debugger.
* Finding The Bug:: Finding the Bug.
-* List of Debugger Commands:: Main Commands.
+* List of Debugger Commands:: Main debugger commands.
* Breakpoint Control:: Control of Breakpoints.
* Debugger Execution Control:: Control of Execution.
* Viewing And Changing Data:: Viewing and Changing Data.
@@ -652,8 +655,13 @@ particular records in a file and perform operations upon
them.
* Debugger Info:: Obtaining Information about the Program and
the Debugger State.
* Miscellaneous Debugger Commands:: Miscellaneous Commands.
-* Readline Support:: Readline Support.
-* Limitations:: Limitations and Future Plans.
+* Readline Support:: Readline support.
+* Limitations:: Limitations and future plans.
+* Plugin License:: A note about licensing.
+* Sample Library:: A example of new functions.
+* Internal File Description:: What the new functions will do.
+* Internal File Ops:: The code for internal file operations.
+* Using Internal File Ops:: How to use an external extension.
* V7/SVR3.1:: The major changes between V7 and System V
Release 3.1.
* SVR4:: Minor changes between System V Releases 3.1
@@ -704,16 +712,6 @@ particular records in a file and perform operations upon
them.
@command{gawk}.
* New Ports:: Porting @command{gawk} to a new operating
system.
-* Dynamic Extensions:: Adding new built-in functions to
- @command{gawk}.
-* Internals:: A brief look at some @command{gawk}
- internals.
-* Plugin License:: A note about licensing.
-* Loading Extensions:: How to load dynamic extensions.
-* Sample Library:: A example of new functions.
-* Internal File Description:: What the new functions will do.
-* Internal File Ops:: The code for internal file operations.
-* Using Internal File Ops:: How to use an external extension.
* Future Extensions:: New features that may be implemented one
day.
* Basic High Level:: The high level view.
@@ -1206,8 +1204,7 @@ available @command{awk} implementations.
@ref{Notes},
describes how to disable @command{gawk}'s extensions, as
well as how to contribute new code to @command{gawk},
-how to write extension libraries, and some possible
-future directions for @command{gawk} development.
+and some possible future directions for @command{gawk} development.
@ref{Basic Concepts},
provides some very cursory background material for those who
@@ -3616,8 +3613,8 @@ behaves.
@menu
* AWKPATH Variable:: Searching directories for @command{awk}
programs.
-* AWKLIBPATH Variable:: Searching directories for @command{awk}
- shared libraries.
+* AWKLIBPATH Variable:: Searching directories for @command{awk} shared
+ libraries.
* Other Environment Variables:: The environment variables.
@end menu
@@ -5263,7 +5260,6 @@ used with it do not have to be named on the @command{awk}
command line
* Getline:: Reading files under explicit program control
using the @code{getline} function.
* Read Timeout:: Reading input with a timeout.
-
* Command line directories:: What happens if you put a directory on the
command line.
@end menu
@@ -11565,9 +11561,9 @@ fatal error.
@item
If you have written extensions that modify the record handling (by inserting
-an ``open hook''), you can invoke them at this point, before @command{gawk}
+an ``input parser''), you can invoke them at this point, before @command{gawk}
has started processing the file. (This is a @emph{very} advanced feature,
-currently used only by the @uref{http://xmlgawk.sourceforge.net, XMLgawk
project}.)
+currently used only by the @uref{http://gawkextlib.sourceforge.net,
@code{gawkextlib} project}.)
@end itemize
The @code{ENDFILE} rule is called when @command{gawk} has finished processing
@@ -18508,21 +18504,22 @@ in general, and the limitations of doing arithmetic
with ordinary
@command{gawk} numbers.
@menu
-* Floating-point Programming:: Effective Floating-point Programming.
-* Floating-point Representation:: Binary Floating-point Representation.
-* Floating-point Context:: Floating-point Context.
-* Rounding Mode:: Floating-point Rounding Mode.
-* Arbitrary Precision Floats:: Arbitrary Precision Floating-point
- Arithmetic with @command{gawk}.
-* Setting Precision:: Setting the Working Precision.
-* Setting Rounding Mode:: Setting the Rounding Mode.
-* Floating-point Constants:: Representing Floating-point Constants.
-* Changing Precision:: Changing the Precision of a Number.
-* Exact Arithmetic:: Exact Arithmetic with Floating-point
Numbers.
-* Integer Programming:: Effective Integer Programming.
-* Arbitrary Precision Integers:: Arbitrary Precision Integer
- Arithmetic with @command{gawk}.
-* MPFR and GMP Libraries:: Information About the MPFR and GMP
Libraries.
+* Floating-point Programming:: Effective Floating-point Programming.
+* Floating-point Representation:: Binary Floating-point Representation.
+* Floating-point Context:: Floating-point Context.
+* Rounding Mode:: Floating-point Rounding Mode.
+* Arbitrary Precision Floats:: Arbitrary Precision Floating-point
+ Arithmetic with @command{gawk}.
+* Setting Precision:: Setting the Working Precision.
+* Setting Rounding Mode:: Setting the Rounding Mode.
+* Floating-point Constants:: Representing Floating-point Constants.
+* Changing Precision:: Changing the Precision of a Number.
+* Exact Arithmetic:: Exact Arithmetic with Floating-point
+ Numbers.
+* Integer Programming:: Effective Integer Programming.
+* Arbitrary Precision Integers:: Arbitrary Precision Integer Arithmetic with
+ @command{gawk}.
+* MPFR and GMP Libraries ::
@end menu
@node Floating-point Programming
@@ -27530,3473 +27527,3107 @@ The @command{gawk} debugger only accepts source
supplied with the @option{-f} op
Look forward to a future release when these and other missing features may
be added, and of course feel free to try to add them yourself!
address@hidden
address@hidden Try this
address@hidden
address@hidden
address@hidden off
address@hidden III@ @ @ Appendixes
-Part III provides the appendixes, the Glossary, and two licenses that cover
-the @command{gawk} source code and this @value{DOCUMENT}, respectively.
-It contains the following appendixes:
address@hidden Dynamic Extensions
address@hidden Writing Extensions for @command{gawk}
address@hidden @bullet
address@hidden
address@hidden History}.
+This chapter is a placeholder, pending a rewrite for the new API.
+Some of the old bits remain, since they can be partially reused.
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden STARTOFRANGE gladfgaw
address@hidden @command{gawk}, functions, adding
address@hidden STARTOFRANGE adfugaw
address@hidden adding, functions to @command{gawk}
address@hidden STARTOFRANGE fubadgaw
address@hidden functions, built-in, adding to @command{gawk}
+It is possible to add new built-in
+functions to @command{gawk} using dynamically loaded libraries. This
+facility is available on systems (such as GNU/Linux) that support
+the C @code{dlopen()} and @code{dlsym()} functions.
+This @value{CHAPTER} describes how to write and use dynamically
+loaded extensions for @command{gawk}.
+Experience with programming in
+C or C++ is necessary when reading this @value{SECTION}.
address@hidden
address@hidden Concepts}.
address@hidden NOTE
+When @option{--sandbox} is specified, extensions are disabled
+(@pxref{Options}.
address@hidden quotation
address@hidden
address@hidden
address@hidden
+* Plugin License:: A note about licensing.
+* Sample Library:: A example of new functions.
address@hidden menu
address@hidden
address@hidden
address@hidden Plugin License
address@hidden Extension Licensing
address@hidden
address@hidden Free Documentation License}.
address@hidden itemize
+Every dynamic extension should define the global symbol
address@hidden to assert that it has been licensed under
+a GPL-compatible license. If this symbol does not exist, @command{gawk}
+will emit a fatal error and exit.
address@hidden
address@hidden @thispage@ @ @ @address@hidden @| @|
address@hidden @| @| @address@hidden@ @ @ @thispage
address@hidden iftex
address@hidden ignore
+The declared type of the symbol should be @code{int}. It does not need
+to be in any allocated section, though. The code merely asserts that
+the symbol exists in the global scope. Something like this is enough:
address@hidden Language History
address@hidden The Evolution of the @command{awk} Language
address@hidden
+int plugin_is_GPL_compatible;
address@hidden example
-This @value{DOCUMENT} describes the GNU implementation of @command{awk}, which
follows
-the POSIX specification.
-Many long-time @command{awk} users learned @command{awk} programming
-with the original @command{awk} implementation in Version 7 Unix.
-(This implementation was the basis for @command{awk} in Berkeley Unix,
-through 4.3-Reno. Subsequent versions of Berkeley Unix, and some systems
-derived from 4.4BSD-Lite, use various versions of @command{gawk}
-for their @command{awk}.)
-This @value{CHAPTER} briefly describes the
-evolution of the @command{awk} language, with cross-references to other parts
-of the @value{DOCUMENT} where you can find more information.
address@hidden Sample Library
address@hidden Example: Directory and File Operation Built-ins
address@hidden STARTOFRANGE chdirg
address@hidden @code{chdir()} address@hidden implementing in @command{gawk}
address@hidden STARTOFRANGE statg
address@hidden @code{stat()} address@hidden implementing in @command{gawk}
address@hidden STARTOFRANGE filre
address@hidden files, information address@hidden retrieving
address@hidden STARTOFRANGE dirch
address@hidden directories, changing
+
+Two useful functions that are not in @command{awk} are @code{chdir()}
+(so that an @command{awk} program can change its directory) and
address@hidden()} (so that an @command{awk} program can gather information about
+a file).
+This @value{SECTION} implements these functions for @command{gawk} in an
+external extension library.
@menu
-* V7/SVR3.1:: The major changes between V7 and System V
- Release 3.1.
-* SVR4:: Minor changes between System V Releases 3.1
- and 4.
-* POSIX:: New features from the POSIX standard.
-* BTL:: New features from Brian Kernighan's version of
- @command{awk}.
-* POSIX/GNU:: The extensions in @command{gawk} not in POSIX
- @command{awk}.
-* Common Extensions:: Common Extensions Summary.
-* Ranges and Locales:: How locales used to affect regexp ranges.
-* Contributors:: The major contributors to @command{gawk}.
+* Internal File Description:: What the new functions will do.
+* Internal File Ops:: The code for internal file operations.
+* Using Internal File Ops:: How to use an external extension.
@end menu
address@hidden V7/SVR3.1
address@hidden Major Changes Between V7 and SVR3.1
address@hidden STARTOFRANGE gawkv
address@hidden @command{awk}, versions of
address@hidden STARTOFRANGE gawkv1
address@hidden @command{awk}, versions of, changes between V7 and SVR3.1
address@hidden Internal File Description
address@hidden Using @code{chdir()} and @code{stat()}
-The @command{awk} language evolved considerably between the release of
-Version 7 Unix (1978) and the new version that was first made generally
available in
-System V Release 3.1 (1987). This @value{SECTION} summarizes the changes, with
-cross-references to further details:
+This @value{SECTION} shows how to use the new functions at the @command{awk}
+level once they've been integrated into the running @command{gawk}
+interpreter.
+Using @code{chdir()} is very straightforward. It takes one argument,
+the new directory to change to:
address@hidden @bullet
address@hidden
-The requirement for @samp{;} to separate rules on a line
-(@pxref{Statements/Lines}).
address@hidden
address@hidden
+newdir = "/home/arnold/funstuff"
+ret = chdir(newdir)
+if (ret < 0) @{
+ printf("could not change to %s: %s\n",
+ newdir, ERRNO) > "/dev/stderr"
+ exit 1
address@hidden
address@hidden
address@hidden example
address@hidden
-User-defined functions and the @code{return} statement
-(@pxref{User-defined}).
+The return value is negative if the @code{chdir} failed,
+and @code{ERRNO}
+(@pxref{Built-in Variables})
+is set to a string indicating the error.
address@hidden
-The @code{delete} statement (@pxref{Delete}).
+Using @code{stat()} is a bit more complicated.
+The C @code{stat()} function fills in a structure that has a fair
+amount of information.
+The right way to model this in @command{awk} is to fill in an associative
+array with the appropriate information:
address@hidden
-The @address@hidden statement
-(@pxref{Do Statement}).
address@hidden broke printf for page breaking
address@hidden
+file = "/home/arnold/.profile"
+fdata[1] = "x" # force `fdata' to be an array
+ret = stat(file, fdata)
+if (ret < 0) @{
+ printf("could not stat %s: %s\n",
+ file, ERRNO) > "/dev/stderr"
+ exit 1
address@hidden
+printf("size of %s is %d bytes\n", file, fdata["size"])
address@hidden example
address@hidden
-The built-in functions @code{atan2()}, @code{cos()}, @code{sin()},
@code{rand()}, and
address@hidden()} (@pxref{Numeric Functions}).
+The @code{stat()} function always clears the data array, even if
+the @code{stat()} fails. It fills in the following elements:
address@hidden
-The built-in functions @code{gsub()}, @code{sub()}, and @code{match()}
-(@pxref{String Functions}).
address@hidden @code
address@hidden "name"
+The name of the file that was @code{stat()}'ed.
address@hidden
-The built-in functions @code{close()} and @code{system()}
-(@pxref{I/O Functions}).
address@hidden "dev"
address@hidden "ino"
+The file's device and inode numbers, respectively.
address@hidden
-The @code{ARGC}, @code{ARGV}, @code{FNR}, @code{RLENGTH}, @code{RSTART},
-and @code{SUBSEP} built-in variables (@pxref{Built-in Variables}).
address@hidden "mode"
+The file's mode, as a numeric value. This includes both the file's
+type and its permissions.
address@hidden
-Assignable @code{$0} (@pxref{Changing Fields}).
address@hidden "nlink"
+The number of hard links (directory entries) the file has.
address@hidden
-The conditional expression using the ternary operator @samp{?:}
-(@pxref{Conditional Exp}).
address@hidden "uid"
address@hidden "gid"
+The numeric user and group ID numbers of the file's owner.
address@hidden
-The expression @address@hidden in @var{array}} outside of @code{for}
-statements (@pxref{Reference to Elements}).
address@hidden "size"
+The size in bytes of the file.
address@hidden
-The exponentiation operator @samp{^}
-(@pxref{Arithmetic Ops}) and its assignment operator
-form @samp{^=} (@pxref{Assignment Ops}).
address@hidden "blocks"
+The number of disk blocks the file actually occupies. This may not
+be a function of the file's size if the file has holes.
address@hidden
-C-compatible operator precedence, which breaks some old @command{awk}
-programs (@pxref{Precedence}).
address@hidden "atime"
address@hidden "mtime"
address@hidden "ctime"
+The file's last access, modification, and inode update times,
+respectively. These are numeric timestamps, suitable for formatting
+with @code{strftime()}
+(@pxref{Built-in}).
address@hidden
-Regexps as the value of @code{FS}
-(@pxref{Field Separators}) and as the
-third argument to the @code{split()} function
-(@pxref{String Functions}), rather than using only the first character
-of @code{FS}.
address@hidden "pmode"
+The file's ``printable mode.'' This is a string representation of
+the file's type and permissions, such as what is produced by
address@hidden -l}---for example, @code{"drwxr-xr-x"}.
address@hidden
-Dynamic regexps as operands of the @samp{~} and @samp{!~} operators
-(@pxref{Regexp Usage}).
address@hidden "type"
+A printable string representation of the file's type. The value
+is one of the following:
address@hidden
-The escape sequences @samp{\b}, @samp{\f}, and @samp{\r}
-(@pxref{Escape Sequences}).
-(Some vendors have updated their old versions of @command{awk} to
-recognize @samp{\b}, @samp{\f}, and @samp{\r}, but this is not
-something you can rely on.)
-
address@hidden
-Redirection of input for the @code{getline} function
-(@pxref{Getline}).
-
address@hidden
-Multiple @code{BEGIN} and @code{END} rules
-(@pxref{BEGIN/END}).
-
address@hidden
-Multidimensional arrays
-(@pxref{Multi-dimensional}).
address@hidden itemize
address@hidden ENDOFRANGE gawkv1
address@hidden @code
address@hidden "blockdev"
address@hidden "chardev"
+The file is a block or character device (``special file'').
address@hidden SVR4
address@hidden Changes Between SVR3.1 and SVR4
address@hidden
address@hidden "door"
+The file is a Solaris ``door'' (special file used for
+interprocess communications).
address@hidden ignore
address@hidden @command{awk}, versions of, changes between SVR3.1 and SVR4
-The System V Release 4 (1989) version of Unix @command{awk} added these
features
-(some of which originated in @command{gawk}):
address@hidden "directory"
+The file is a directory.
address@hidden @bullet
address@hidden
-The @code{ENVIRON} array (@pxref{Built-in Variables}).
address@hidden gawk and MKS awk
address@hidden "fifo"
+The file is a named-pipe (also known as a FIFO).
address@hidden
-Multiple @option{-f} options on the command line
-(@pxref{Options}).
address@hidden MKS awk
address@hidden "file"
+The file is just a regular file.
address@hidden
-The @option{-v} option for assigning variables before program execution begins
-(@pxref{Options}).
address@hidden GNU, Bell Laboratories & MKS together
address@hidden "socket"
+The file is an @code{AF_UNIX} (``Unix domain'') socket in the
+filesystem.
address@hidden
-The @option{--} option for terminating command-line options.
address@hidden "symlink"
+The file is a symbolic link.
address@hidden table
address@hidden table
address@hidden
-The @samp{\a}, @samp{\v}, and @samp{\x} escape sequences
-(@pxref{Escape Sequences}).
address@hidden GNU, for ANSI C compat
+Several additional elements may be present depending upon the operating
+system and the type of the file. You can test for them in your @command{awk}
+program by using the @code{in} operator
+(@pxref{Reference to Elements}):
address@hidden
-A defined return value for the @code{srand()} built-in function
-(@pxref{Numeric Functions}).
address@hidden @code
address@hidden "blksize"
+The preferred block size for I/O to the file. This field is not
+present on all POSIX-like systems in the C @code{stat} structure.
address@hidden
-The @code{toupper()} and @code{tolower()} built-in string functions
-for case translation
-(@pxref{String Functions}).
address@hidden "linkval"
+If the file is a symbolic link, this element is the name of the
+file the link points to (i.e., the value of the link).
address@hidden
-A cleaner specification for the @samp{%c} format-control letter in the
address@hidden function
-(@pxref{Control Letters}).
address@hidden "rdev"
address@hidden "major"
address@hidden "minor"
+If the file is a block or character device file, then these values
+represent the numeric device number and the major and minor components
+of that number, respectively.
address@hidden table
address@hidden
-The ability to dynamically pass the field width and precision (@code{"%*.*d"})
-in the argument list of the @code{printf} function
-(@pxref{Control Letters}).
address@hidden Internal File Ops
address@hidden C Code for @code{chdir()} and @code{stat()}
address@hidden
-The use of regexp constants, such as @code{/foo/}, as expressions, where
-they are equivalent to using the matching operator, as in @samp{$0 ~ /foo/}
-(@pxref{Using Constant Regexps}).
+Here is the C code for these extensions. They were written for
+GNU/Linux. The code needs some more work for complete portability
+to other POSIX-compliant systems:@footnote{This version is edited
+slightly for presentation. See
address@hidden/filefuncs.c} in the @command{gawk} distribution
+for the complete version.}
address@hidden
-Processing of escape sequences inside command-line variable assignments
-(@pxref{Assignment Options}).
address@hidden itemize
address@hidden break line for page breaking
address@hidden
+#include "awk.h"
address@hidden POSIX
address@hidden Changes Between SVR4 and POSIX @command{awk}
address@hidden @command{awk}, versions of, changes between SVR4 and POSIX
@command{awk}
address@hidden POSIX @command{awk}, changes in @command{awk} versions
+#include <sys/sysmacros.h>
-The POSIX Command Language and Utilities standard for @command{awk} (1992)
-introduced the following changes into the language:
+int plugin_is_GPL_compatible;
address@hidden @bullet
address@hidden
-The use of @option{-W} for implementation-specific options
-(@pxref{Options}).
+/* do_chdir --- provide dynamically loaded chdir() builtin for gawk */
address@hidden
-The use of @code{CONVFMT} for controlling the conversion of numbers
-to strings (@pxref{Conversion}).
+static NODE *
+do_chdir(int nargs)
address@hidden
+ NODE *newdir;
+ int ret = -1;
address@hidden
-The concept of a numeric string and tighter comparison rules to go
-with it (@pxref{Typing and Comparison}).
+ if (do_lint && nargs != 1)
+ lintwarn("chdir: called with incorrect number of arguments");
address@hidden
-The use of built-in variables as function parameter names is forbidden
-(@pxref{Definition Syntax}.
+ newdir = get_scalar_argument(0, FALSE);
address@hidden example
address@hidden
-More complete documentation of many of the previously undocumented
-features of the language.
address@hidden itemize
+The file includes the @code{"awk.h"} header file for definitions
+for the @command{gawk} internals. It includes @code{<sys/sysmacros.h>}
+for access to the @code{major()} and @code{minor}() macros.
address@hidden Extensions}, for a list of common extensions
-not permitted by the POSIX standard.
address@hidden programming conventions, @command{gawk} internals
+By convention, for an @command{awk} function @code{foo}, the function that
+implements it is called @samp{do_foo}. The function should take
+a @samp{int} argument, usually called @code{nargs}, that
+represents the number of defined arguments for the function. The @code{newdir}
+variable represents the new directory to change to, retrieved
+with @code{get_scalar_argument()}. Note that the first argument is
+numbered zero.
-The 2008 POSIX standard can be found online at
address@hidden://www.opengroup.org/onlinepubs/9699919799/}.
+This code actually accomplishes the @code{chdir()}. It first forces
+the argument to be a string and passes the string value to the
address@hidden()} system call. If the @code{chdir()} fails, @code{ERRNO}
+is updated.
address@hidden ENDOFRANGE gawkv
address@hidden
+ (void) force_string(newdir);
+ ret = chdir(newdir->stptr);
+ if (ret < 0)
+ update_ERRNO_int(errno);
address@hidden example
address@hidden BTL
address@hidden Extensions in Brian Kernighan's @command{awk}
+Finally, the function returns the return value to the @command{awk} level:
address@hidden @command{awk}, versions of, See Also Brian Kernighan's
@command{awk}
address@hidden extensions, Brian Kernighan's @command{awk}
address@hidden Brian Kernighan's @command{awk}, extensions
address@hidden Kernighan, Brian
-Brian Kernighan
-has made his version available via his home page
-(@pxref{Other Versions}).
address@hidden
+ return make_number((AWKNUM) ret);
address@hidden
address@hidden example
-This @value{SECTION} describes common extensions that
-originally appeared in his version of @command{awk}.
+The @code{stat()} built-in is more involved. First comes a function
+that turns a numeric mode into a printable representation
+(e.g., 644 becomes @samp{-rw-r--r--}). This is omitted here for brevity:
address@hidden @bullet
address@hidden
-The @samp{**} and @samp{**=} operators
-(@pxref{Arithmetic Ops}
-and
address@hidden Ops}).
address@hidden break line for page breaking
address@hidden
+/* format_mode --- turn a stat mode field into something readable */
address@hidden
-The use of @code{func} as an abbreviation for @code{function}
-(@pxref{Definition Syntax}).
+static char *
+format_mode(unsigned long fmode)
address@hidden
+ @dots{}
address@hidden
address@hidden example
address@hidden
-The @code{fflush()} built-in function for flushing buffered output
-(@pxref{I/O Functions}).
+Next comes the @code{do_stat()} function. It starts with
+variable declarations and argument checking:
@ignore
address@hidden
-The @code{SYMTAB} array, that allows access to @command{awk}'s internal symbol
-table. This feature is not documented, largely because
-it is somewhat shakily implemented. For instance, you cannot access arrays
-or array elements through it.
+Changed message for page breaking. Used to be:
+ "stat: called with incorrect number of arguments (%d), should be 2",
@end ignore
address@hidden itemize
-
address@hidden Extensions}, for a full list of the extensions
-available in his @command{awk}.
address@hidden
+/* do_stat --- provide a stat() function for gawk */
address@hidden POSIX/GNU
address@hidden Extensions in @command{gawk} Not in POSIX @command{awk}
+static NODE *
+do_stat(int nargs)
address@hidden
+ NODE *file, *array, *tmp;
+ struct stat sbuf;
+ int ret;
+ NODE **aptr;
+ char *pmode; /* printable mode */
+ char *type = "unknown";
address@hidden STARTOFRANGE fripls
address@hidden compatibility mode (@command{gawk}), extensions
address@hidden STARTOFRANGE exgnot
address@hidden extensions, in @command{gawk}, not in POSIX @command{awk}
address@hidden STARTOFRANGE posnot
address@hidden POSIX, @command{gawk} extensions not included in
-The GNU implementation, @command{gawk}, adds a large number of features.
-They can all be disabled with either the @option{--traditional} or
address@hidden options
-(@pxref{Options}).
+ if (do_lint && nargs > 2)
+ lintwarn("stat: called with too many arguments");
address@hidden example
-A number of features have come and gone over the years. This @value{SECTION}
-summarizes the additional features over POSIX @command{awk} that are
-in the current version of @command{gawk}.
+Then comes the actual work. First, the function gets the arguments.
+Then, it always clears the array.
+The code use @code{lstat()} (instead of @code{stat()})
+to get the file information,
+in case the file is a symbolic link.
+If there's an error, it sets @code{ERRNO} and returns:
address@hidden @bullet
address@hidden comment made multiline for page breaking
address@hidden
+ /* file is first arg, array to hold results is second */
+ file = get_scalar_argument(0, FALSE);
+ array = get_array_argument(1, FALSE);
address@hidden
-Additional built-in variables:
+ /* empty out the array */
+ assoc_clear(array);
address@hidden @minus
address@hidden
-The
address@hidden
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
-and
address@hidden
-variables
-(@pxref{Built-in Variables}).
address@hidden itemize
+ /* lstat the file, if error, set ERRNO and return */
+ (void) force_string(file);
+ ret = lstat(file->stptr, & sbuf);
+ if (ret < 0) @{
+ update_ERRNO_int(errno);
+ return make_number((AWKNUM) ret);
+ @}
address@hidden example
address@hidden
-Special files in I/O redirections:
+Now comes the tedious part: filling in the array. Only a few of the
+calls are shown here, since they all follow the same pattern:
address@hidden @minus{}
address@hidden
-The @file{/dev/stdin}, @file{/dev/stdout}, @file{/dev/stderr} and
address@hidden/dev/fd/@var{N}} special @value{FN}s
-(@pxref{Special Files}).
address@hidden
+ /* fill in the array */
+ aptr = assoc_lookup(array, tmp = make_string("name", 4));
+ *aptr = dupnode(file);
+ unref(tmp);
address@hidden
-The @file{/inet}, @file{/inet4}, and @samp{/inet6} special files for
-TCP/IP networking using @samp{|&} to specify which version of the
-IP protocol to use.
-(@pxref{TCP/IP Networking}).
address@hidden itemize
+ aptr = assoc_lookup(array, tmp = make_string("mode", 4));
+ *aptr = make_number((AWKNUM) sbuf.st_mode);
+ unref(tmp);
address@hidden
-Changes and/or additions to the language:
+ aptr = assoc_lookup(array, tmp = make_string("pmode", 5));
+ pmode = format_mode(sbuf.st_mode);
+ *aptr = make_string(pmode, strlen(pmode));
+ unref(tmp);
address@hidden example
address@hidden @minus{}
address@hidden
-The @samp{\x} escape sequence
-(@pxref{Escape Sequences}).
+When done, return the @code{lstat()} return value:
address@hidden
-Full support for both POSIX and GNU regexps
-(@pxref{Regexp}).
address@hidden
address@hidden
-The ability for @code{FS} and for the third
-argument to @code{split()} to be null strings
-(@pxref{Single Character Fields}).
+ return make_number((AWKNUM) ret);
address@hidden
address@hidden example
address@hidden
-The ability for @code{RS} to be a regexp
-(@pxref{Records}).
address@hidden programming conventions, @command{gawk} internals
+Finally, it's necessary to provide the ``glue'' that loads the
+new function(s) into @command{gawk}. By convention, each library has
+a routine named @code{dl_load()} that does the job. The simplest way
+is to use the @code{dl_load_func} macro in @code{gawkapi.h}.
address@hidden
-The ability to use octal and hexadecimal constants in @command{awk}
-program source code
-(@pxref{Nondecimal-numbers}).
+And that's it! As an exercise, consider adding functions to
+implement system calls such as @code{chown()}, @code{chmod()},
+and @code{umask()}.
address@hidden
-The @samp{|&} operator for two-way I/O to a coprocess
-(@pxref{Two-way I/O}).
address@hidden Using Internal File Ops
address@hidden Integrating the Extensions
address@hidden
-Indirect function calls
-(@pxref{Indirect Calls}).
address@hidden @command{gawk}, address@hidden adding code to
+Now that the code is written, it must be possible to add it at
+runtime to the running @command{gawk} interpreter. First, the
+code must be compiled. Assuming that the functions are in
+a file named @file{filefuncs.c}, and @var{idir} is the location
+of the @command{gawk} include files,
+the following steps create
+a GNU/Linux shared library:
address@hidden
-Directories on the command line produce a warning and are skipped
-(@pxref{Command line directories}).
address@hidden itemize
address@hidden
+$ @kbd{gcc -fPIC -shared -DHAVE_CONFIG_H -c -O -g address@hidden filefuncs.c}
+$ @kbd{ld -o filefuncs.so -shared filefuncs.o}
address@hidden example
address@hidden
-New keywords:
address@hidden @code{extension()} function (@command{gawk})
+Once the library exists, it is loaded by calling the @code{extension()}
+built-in function.
+This function takes two arguments: the name of the
+library to load and the name of a function to call when the library
+is first loaded. This function adds the new functions to @command{gawk}.
+It returns the value returned by the initialization function
+within the shared library:
address@hidden @minus{}
address@hidden
-The @code{BEGINFILE} and @code{ENDFILE} special patterns.
-(@pxref{BEGINFILE/ENDFILE}).
address@hidden
+# file testff.awk
+BEGIN @{
+ extension("./filefuncs.so", "dl_load")
address@hidden
-The ability to delete all of an array at once with @samp{delete @var{array}}
-(@pxref{Delete}).
+ chdir(".") # no-op
address@hidden
-The @code{nextfile} statement
-(@pxref{Nextfile Statement}).
+ data[1] = 1 # force `data' to be an array
+ print "Info for testff.awk"
+ ret = stat("testff.awk", data)
+ print "ret =", ret
+ for (i in data)
+ printf "data[\"%s\"] = %s\n", i, data[i]
+ print "testff.awk modified:",
+ strftime("%m %d %y %H:%M:%S", data["mtime"])
address@hidden
-The @code{switch} statement
-(@pxref{Switch Statement}).
address@hidden itemize
+ print "\nInfo for JUNK"
+ ret = stat("JUNK", data)
+ print "ret =", ret
+ for (i in data)
+ printf "data[\"%s\"] = %s\n", i, data[i]
+ print "JUNK modified:", strftime("%m %d %y %H:%M:%S", data["mtime"])
address@hidden
address@hidden example
address@hidden
-Changes to standard @command{awk} functions:
+Here are the results of running the program:
address@hidden @minus
address@hidden
-The optional second argument to @code{close()} that allows closing one end
-of a two-way pipe to a coprocess
-(@pxref{Two-way I/O}).
address@hidden
+$ @kbd{gawk -f testff.awk}
address@hidden Info for testff.awk
address@hidden ret = 0
address@hidden data["size"] = 607
address@hidden data["ino"] = 14945891
address@hidden data["name"] = testff.awk
address@hidden data["pmode"] = -rw-rw-r--
address@hidden data["nlink"] = 1
address@hidden data["atime"] = 1293993369
address@hidden data["mtime"] = 1288520752
address@hidden data["mode"] = 33204
address@hidden data["blksize"] = 4096
address@hidden data["dev"] = 2054
address@hidden data["type"] = file
address@hidden data["gid"] = 500
address@hidden data["uid"] = 500
address@hidden data["blocks"] = 8
address@hidden data["ctime"] = 1290113572
address@hidden testff.awk modified: 10 31 10 12:25:52
address@hidden
address@hidden Info for JUNK
address@hidden ret = -1
address@hidden JUNK modified: 01 01 70 02:00:00
address@hidden example
address@hidden ENDOFRANGE filre
address@hidden ENDOFRANGE dirch
address@hidden ENDOFRANGE statg
address@hidden ENDOFRANGE chdirg
address@hidden ENDOFRANGE gladfgaw
address@hidden ENDOFRANGE adfugaw
address@hidden ENDOFRANGE fubadgaw
address@hidden
-POSIX compliance for @code{gsub()} and @code{sub()}.
address@hidden
address@hidden Try this
address@hidden
address@hidden
address@hidden off
address@hidden III@ @ @ Appendixes
+Part III provides the appendixes, the Glossary, and two licenses that cover
+the @command{gawk} source code and this @value{DOCUMENT}, respectively.
+It contains the following appendixes:
address@hidden @bullet
@item
-The @code{length()} function accepts an array argument
-and returns the number of elements in the array
-(@pxref{String Functions}).
address@hidden History}.
@item
-The optional third argument to the @code{match()} function
-for capturing text-matching subexpressions within a regexp
-(@pxref{String Functions}).
address@hidden
@item
-Positional specifiers in @code{printf} formats for
-making translations easier
-(@pxref{Printf Ordering}).
address@hidden
@item
-The @code{split()} function's additional optional fourth
-argument which is an array to hold the text of the field separators.
-(@pxref{String Functions}).
address@hidden itemize
address@hidden Concepts}.
@item
-Additional functions only in @command{gawk}:
address@hidden
address@hidden @minus
@item
-The
address@hidden()},
address@hidden()},
address@hidden()},
address@hidden()},
address@hidden()},
-and
address@hidden()}
-functions for bit manipulation
-(@pxref{Bitwise Functions}).
address@hidden In 4.1, and(), or() and xor() grew the ability to take > 2
arguments
address@hidden
@item
-The @code{asort()} and @code{asorti()} functions for sorting arrays
-(@pxref{Array Sorting}).
address@hidden Free Documentation License}.
address@hidden itemize
+
address@hidden
address@hidden @thispage@ @ @ @address@hidden @| @|
address@hidden @| @| @address@hidden@ @ @ @thispage
address@hidden iftex
address@hidden ignore
+
address@hidden Language History
address@hidden The Evolution of the @command{awk} Language
+
+This @value{DOCUMENT} describes the GNU implementation of @command{awk}, which
follows
+the POSIX specification.
+Many long-time @command{awk} users learned @command{awk} programming
+with the original @command{awk} implementation in Version 7 Unix.
+(This implementation was the basis for @command{awk} in Berkeley Unix,
+through 4.3-Reno. Subsequent versions of Berkeley Unix, and some systems
+derived from 4.4BSD-Lite, use various versions of @command{gawk}
+for their @command{awk}.)
+This @value{CHAPTER} briefly describes the
+evolution of the @command{awk} language, with cross-references to other parts
+of the @value{DOCUMENT} where you can find more information.
+
address@hidden
+* V7/SVR3.1:: The major changes between V7 and System V
+ Release 3.1.
+* SVR4:: Minor changes between System V Releases 3.1
+ and 4.
+* POSIX:: New features from the POSIX standard.
+* BTL:: New features from Brian Kernighan's version of
+ @command{awk}.
+* POSIX/GNU:: The extensions in @command{gawk} not in POSIX
+ @command{awk}.
+* Common Extensions:: Common Extensions Summary.
+* Ranges and Locales:: How locales used to affect regexp ranges.
+* Contributors:: The major contributors to @command{gawk}.
address@hidden menu
+
address@hidden V7/SVR3.1
address@hidden Major Changes Between V7 and SVR3.1
address@hidden STARTOFRANGE gawkv
address@hidden @command{awk}, versions of
address@hidden STARTOFRANGE gawkv1
address@hidden @command{awk}, versions of, changes between V7 and SVR3.1
+
+The @command{awk} language evolved considerably between the release of
+Version 7 Unix (1978) and the new version that was first made generally
available in
+System V Release 3.1 (1987). This @value{SECTION} summarizes the changes, with
+cross-references to further details:
address@hidden @bullet
@item
-The @code{bindtextdomain()}, @code{dcgettext()} and @code{dcngettext()}
-functions for internationalization
-(@pxref{Programmer i18n}).
+The requirement for @samp{;} to separate rules on a line
+(@pxref{Statements/Lines}).
@item
-The @code{extension()} built-in function and the ability to add
-new functions dynamically
-(@pxref{Dynamic Extensions}).
+User-defined functions and the @code{return} statement
+(@pxref{User-defined}).
@item
-The @code{fflush()} function from Brian Kernighan's
-version of @command{awk}
-(@pxref{I/O Functions}).
+The @code{delete} statement (@pxref{Delete}).
@item
-The @code{gensub()}, @code{patsplit()}, and @code{strtonum()} functions
-for more powerful text manipulation
+The @address@hidden statement
+(@pxref{Do Statement}).
+
address@hidden
+The built-in functions @code{atan2()}, @code{cos()}, @code{sin()},
@code{rand()}, and
address@hidden()} (@pxref{Numeric Functions}).
+
address@hidden
+The built-in functions @code{gsub()}, @code{sub()}, and @code{match()}
(@pxref{String Functions}).
@item
-The @code{mktime()}, @code{systime()}, and @code{strftime()}
-functions for working with timestamps
-(@pxref{Time Functions}).
address@hidden itemize
+The built-in functions @code{close()} and @code{system()}
+(@pxref{I/O Functions}).
address@hidden
+The @code{ARGC}, @code{ARGV}, @code{FNR}, @code{RLENGTH}, @code{RSTART},
+and @code{SUBSEP} built-in variables (@pxref{Built-in Variables}).
@item
-Changes and/or additions in the command-line options:
+Assignable @code{$0} (@pxref{Changing Fields}).
address@hidden @minus
@item
-The @env{AWKPATH} environment variable for specifying a path search for
-the @option{-f} command-line option
-(@pxref{Options}).
+The conditional expression using the ternary operator @samp{?:}
+(@pxref{Conditional Exp}).
@item
-The @env{AWKLIBPATH} environment variable for specifying a path search for
-the @option{-l} command-line option
-(@pxref{Options}).
+The expression @address@hidden in @var{array}} outside of @code{for}
+statements (@pxref{Reference to Elements}).
@item
-The ability to use GNU-style long-named options that start with @option{--}
-and the
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
-and
address@hidden
-options
-(@pxref{Options}).
address@hidden itemize
+The exponentiation operator @samp{^}
+(@pxref{Arithmetic Ops}) and its assignment operator
+form @samp{^=} (@pxref{Assignment Ops}).
address@hidden
+C-compatible operator precedence, which breaks some old @command{awk}
+programs (@pxref{Precedence}).
address@hidden new ports
address@hidden
+Regexps as the value of @code{FS}
+(@pxref{Field Separators}) and as the
+third argument to the @code{split()} function
+(@pxref{String Functions}), rather than using only the first character
+of @code{FS}.
@item
-Support for the following obsolete systems was removed from the code
-and the documentation for @command{gawk} @value{PVERSION} 4.0:
+Dynamic regexps as operands of the @samp{~} and @samp{!~} operators
+(@pxref{Regexp Usage}).
address@hidden nested table
address@hidden @minus
@item
-Amiga
+The escape sequences @samp{\b}, @samp{\f}, and @samp{\r}
+(@pxref{Escape Sequences}).
+(Some vendors have updated their old versions of @command{awk} to
+recognize @samp{\b}, @samp{\f}, and @samp{\r}, but this is not
+something you can rely on.)
@item
-Atari
+Redirection of input for the @code{getline} function
+(@pxref{Getline}).
@item
-BeOS
+Multiple @code{BEGIN} and @code{END} rules
+(@pxref{BEGIN/END}).
@item
-Cray
+Multidimensional arrays
+(@pxref{Multi-dimensional}).
address@hidden itemize
address@hidden ENDOFRANGE gawkv1
+
address@hidden SVR4
address@hidden Changes Between SVR3.1 and SVR4
+
address@hidden @command{awk}, versions of, changes between SVR3.1 and SVR4
+The System V Release 4 (1989) version of Unix @command{awk} added these
features
+(some of which originated in @command{gawk}):
address@hidden @bullet
@item
-MIPS RiscOS
+The @code{ENVIRON} array (@pxref{Built-in Variables}).
address@hidden gawk and MKS awk
@item
-MS-DOS with the Microsoft Compiler
+Multiple @option{-f} options on the command line
+(@pxref{Options}).
address@hidden MKS awk
@item
-MS-Windows with the Microsoft Compiler
+The @option{-v} option for assigning variables before program execution begins
+(@pxref{Options}).
address@hidden GNU, Bell Laboratories & MKS together
@item
-NeXT
+The @option{--} option for terminating command-line options.
@item
-SunOS 3.x, Sun 386 (Road Runner)
+The @samp{\a}, @samp{\v}, and @samp{\x} escape sequences
+(@pxref{Escape Sequences}).
address@hidden GNU, for ANSI C compat
@item
-Tandem (non-POSIX)
+A defined return value for the @code{srand()} built-in function
+(@pxref{Numeric Functions}).
@item
-Prestandard VAX C compiler for VAX/VMS
+The @code{toupper()} and @code{tolower()} built-in string functions
+for case translation
+(@pxref{String Functions}).
address@hidden itemize
address@hidden
+A cleaner specification for the @samp{%c} format-control letter in the
address@hidden function
+(@pxref{Control Letters}).
address@hidden itemize
address@hidden
+The ability to dynamically pass the field width and precision (@code{"%*.*d"})
+in the argument list of the @code{printf} function
+(@pxref{Control Letters}).
address@hidden XXX ADD MORE STUFF HERE
address@hidden
+The use of regexp constants, such as @code{/foo/}, as expressions, where
+they are equivalent to using the matching operator, as in @samp{$0 ~ /foo/}
+(@pxref{Using Constant Regexps}).
address@hidden ENDOFRANGE fripls
address@hidden ENDOFRANGE exgnot
address@hidden ENDOFRANGE posnot
address@hidden
+Processing of escape sequences inside command-line variable assignments
+(@pxref{Assignment Options}).
address@hidden itemize
address@hidden Common Extensions
address@hidden Common Extensions Summary
address@hidden POSIX
address@hidden Changes Between SVR4 and POSIX @command{awk}
address@hidden @command{awk}, versions of, changes between SVR4 and POSIX
@command{awk}
address@hidden POSIX @command{awk}, changes in @command{awk} versions
-This @value{SECTION} summarizes the common extensions supported
-by @command{gawk}, Brian Kernighan's @command{awk}, and @command{mawk},
-the three most widely-used freely available versions of @command{awk}
-(@pxref{Other Versions}).
+The POSIX Command Language and Utilities standard for @command{awk} (1992)
+introduced the following changes into the language:
address@hidden address@hidden/dev/stderr} special file} {BWK Awk} {Mawk} {GNU
Awk}
address@hidden Feature @tab BWK Awk @tab Mawk @tab GNU Awk
address@hidden @samp{\x} Escape sequence @tab X @tab X @tab X
address@hidden @code{RS} as regexp @tab @tab X @tab X
address@hidden @code{FS} as null string @tab X @tab X @tab X
address@hidden @file{/dev/stdin} special file @tab X @tab @tab X
address@hidden @file{/dev/stdout} special file @tab X @tab X @tab X
address@hidden @file{/dev/stderr} special file @tab X @tab X @tab X
address@hidden @code{**} and @code{**=} operators @tab X @tab @tab X
address@hidden @code{func} keyword @tab X @tab @tab X
address@hidden @code{nextfile} statement @tab X @tab X @tab X
address@hidden @code{delete} without subscript @tab X @tab X @tab X
address@hidden @code{length()} of an array @tab X @tab @tab X
address@hidden @code{fflush()} function @tab X @tab X @tab X
address@hidden @code{BINMODE} variable @tab @tab X @tab X
address@hidden multitable
address@hidden @bullet
address@hidden
+The use of @option{-W} for implementation-specific options
+(@pxref{Options}).
address@hidden Ranges and Locales
address@hidden Regexp Ranges and Locales: A Long Sad Story
address@hidden
+The use of @code{CONVFMT} for controlling the conversion of numbers
+to strings (@pxref{Conversion}).
-This @value{SECTION} describes the confusing history of ranges within
-regular expressions and their interactions with locales, and how this
-affected different versions of @command{gawk}.
address@hidden
+The concept of a numeric string and tighter comparison rules to go
+with it (@pxref{Typing and Comparison}).
-The original Unix tools that worked with regular expressions defined
-character ranges (such as @samp{[a-z]}) to match any character between
-the first character in the range and the last character in the range,
-inclusive. Ordering was based on the numeric value of each character
-in the machine's native character set. Thus, on ASCII-based systems,
address@hidden matched all the lowercase letters, and only the lowercase
-letters, since the numeric values for the letters from @samp{a} through
address@hidden were contiguous. (On an EBCDIC system, the range @samp{[a-z]}
-includes additional, non-alphabetic characters as well.)
-
-Almost all introductory Unix literature explained range expressions
-as working in this fashion, and in particular, would teach that the
-``correct'' way to match lowercase letters was with @samp{[a-z]}, and
-that @samp{[A-Z]} was the ``correct'' way to match uppercase letters.
-And indeed, this was true.
address@hidden
+The use of built-in variables as function parameter names is forbidden
+(@pxref{Definition Syntax}.
-The 1993 POSIX standard introduced the idea of locales (@pxref{Locales}).
-Since many locales include other letters besides the plain twenty-six
-letters of the American English alphabet, the POSIX standard added
-character classes (@pxref{Bracket Expressions}) as a way to match
-different kinds of characters besides the traditional ones in the ASCII
-character set.
address@hidden
+More complete documentation of many of the previously undocumented
+features of the language.
address@hidden itemize
-However, the standard @emph{changed} the interpretation of range expressions.
-In the @code{"C"} and @code{"POSIX"} locales, a range expression like
address@hidden is still equivalent to @samp{[abcdxyz]}, as in ASCII.
-But outside those locales, the ordering was defined to be based on
address@hidden order}.
address@hidden Extensions}, for a list of common extensions
+not permitted by the POSIX standard.
-In many locales, @samp{A} and @samp{a} are both less than @samp{B}.
-In other words, these locales sort characters in dictionary order,
-and @samp{[a-dx-z]} is typically not equivalent to @samp{[abcdxyz]};
-instead it might be equivalent to @samp{[aBbCcdXxYyz]}, for example.
+The 2008 POSIX standard can be found online at
address@hidden://www.opengroup.org/onlinepubs/9699919799/}.
-This point needs to be emphasized: Much literature teaches that you should
-use @samp{[a-z]} to match a lowercase character. But on systems with
-non-ASCII locales, this also matched all of the uppercase characters
-except @samp{Z}! This was a continuous cause of confusion, even well
-into the twenty-first century.
address@hidden ENDOFRANGE gawkv
-To demonstrate these issues, the following example uses the @code{sub()}
-function, which does text replacement (@pxref{String Functions}). Here,
-the intent is to remove trailing uppercase characters:
address@hidden BTL
address@hidden Extensions in Brian Kernighan's @command{awk}
address@hidden
-$ @kbd{echo something1234abc | gawk-3.1.8 '@{ sub("[A-Z]*$", ""); print @}'}
address@hidden something1234a
address@hidden example
address@hidden @command{awk}, versions of, See Also Brian Kernighan's
@command{awk}
address@hidden extensions, Brian Kernighan's @command{awk}
address@hidden Brian Kernighan's @command{awk}, extensions
address@hidden Kernighan, Brian
+Brian Kernighan
+has made his version available via his home page
+(@pxref{Other Versions}).
address@hidden
-This output is unexpected, since the @samp{bc} at the end of
address@hidden 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).
+This @value{SECTION} describes common extensions that
+originally appeared in his version of @command{awk}.
-Similar considerations apply to other ranges. For example, @samp{["-/]}
-is perfectly valid in ASCII, but is not valid in many Unicode locales,
-such as @samp{en_US.UTF-8}.
address@hidden @bullet
address@hidden
+The @samp{**} and @samp{**=} operators
+(@pxref{Arithmetic Ops}
+and
address@hidden Ops}).
-Early versions of @command{gawk} used regexp matching code that was not
-locale aware, so ranges had their traditional interpretation.
address@hidden
+The use of @code{func} as an abbreviation for @code{function}
+(@pxref{Definition Syntax}).
-When @command{gawk} switched to using locale-aware regexp matchers,
-the problems began; especially as both GNU/Linux and commercial Unix
-vendors started implementing non-ASCII locales, @emph{and making them
-the default}. Perhaps the most frequently asked question became something
-like ``why does @code{[A-Z]} match lowercase letters?!?''
address@hidden
+The @code{fflush()} built-in function for flushing buffered output
+(@pxref{I/O Functions}).
-This situation existed for close to 10 years, if not more, and
-the @command{gawk} maintainer grew weary of trying to explain that
address@hidden was being nicely standards-compliant, and that the issue
-was in the user's locale. During the development of version 4.0,
-he modified @command{gawk} to always treat ranges in the original,
-pre-POSIX fashion, unless @option{--posix} was used (@pxref{Options}).
address@hidden
address@hidden
+The @code{SYMTAB} array, that allows access to @command{awk}'s internal symbol
+table. This feature is not documented, largely because
+it is somewhat shakily implemented. For instance, you cannot access arrays
+or array elements through it.
address@hidden ignore
address@hidden itemize
-Fortunately, shortly before the final release of @command{gawk} 4.0,
-the maintainer learned that the 2008 standard had changed the
-definition of ranges, such that outside the @code{"C"} and @code{"POSIX"}
-locales, the meaning of range expressions was
address@hidden@footnote{See
address@hidden://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_03_05,
the standard}
-and
address@hidden://pubs.opengroup.org/onlinepubs/9699919799/xrat/V4_xbd_chap09.html#tag_21_09_03_05,
its rationale}.}
address@hidden Extensions}, for a full list of the extensions
+available in his @command{awk}.
-By using this lovely technical term, the standard gives license
-to implementors to implement ranges in whatever way they choose.
-The @command{gawk} maintainer chose to apply the pre-POSIX meaning in all
-cases: the default regexp matching; with @option{--traditional}, and with
address@hidden; in all cases, @command{gawk} remains POSIX compliant.
address@hidden POSIX/GNU
address@hidden Extensions in @command{gawk} Not in POSIX @command{awk}
address@hidden Contributors
address@hidden Major Contributors to @command{gawk}
address@hidden @command{gawk}, list of contributors to
address@hidden
address@hidden give credit where credit is address@hidden
-Anonymous
address@hidden quotation
address@hidden STARTOFRANGE fripls
address@hidden compatibility mode (@command{gawk}), extensions
address@hidden STARTOFRANGE exgnot
address@hidden extensions, in @command{gawk}, not in POSIX @command{awk}
address@hidden STARTOFRANGE posnot
address@hidden POSIX, @command{gawk} extensions not included in
+The GNU implementation, @command{gawk}, adds a large number of features.
+They can all be disabled with either the @option{--traditional} or
address@hidden options
+(@pxref{Options}).
-This @value{SECTION} names the major contributors to @command{gawk}
-and/or this @value{DOCUMENT}, in approximate chronological order:
+A number of features have come and gone over the years. This @value{SECTION}
+summarizes the additional features over POSIX @command{awk} that are
+in the current version of @command{gawk}.
@itemize @bullet
+
@item
address@hidden Aho, Alfred
address@hidden Weinberger, Peter
address@hidden Kernighan, Brian
-Dr.@: Alfred V.@: Aho,
-Dr.@: Peter J.@: Weinberger, and
-Dr.@: Brian W.@: Kernighan, all of Bell Laboratories,
-designed and implemented Unix @command{awk},
-from which @command{gawk} gets the majority of its feature set.
+Additional built-in variables:
address@hidden @minus
@item
address@hidden Rubin, Paul
-Paul Rubin
-did the initial design and implementation in 1986, and wrote
-the first draft (around 40 pages) of this @value{DOCUMENT}.
+The
address@hidden
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
+and
address@hidden
+variables
+(@pxref{Built-in Variables}).
address@hidden itemize
@item
address@hidden Fenlason, Jay
-Jay Fenlason
-finished the initial implementation.
+Special files in I/O redirections:
address@hidden @minus{}
@item
address@hidden Close, Diane
-Diane Close
-revised the first draft of this @value{DOCUMENT}, bringing it
-to around 90 pages.
+The @file{/dev/stdin}, @file{/dev/stdout}, @file{/dev/stderr} and
address@hidden/dev/fd/@var{N}} special @value{FN}s
+(@pxref{Special Files}).
@item
address@hidden Stallman, Richard
-Richard Stallman
-helped finish the implementation and the initial draft of this
address@hidden
-He is also the founder of the FSF and the GNU project.
+The @file{/inet}, @file{/inet4}, and @samp{/inet6} special files for
+TCP/IP networking using @samp{|&} to specify which version of the
+IP protocol to use.
+(@pxref{TCP/IP Networking}).
address@hidden itemize
@item
address@hidden Woods, John
-John Woods
-contributed parts of the code (mostly fixes) in
-the initial version of @command{gawk}.
+Changes and/or additions to the language:
address@hidden @minus{}
@item
address@hidden Trueman, David
-In 1988,
-David Trueman
-took over primary maintenance of @command{gawk},
-making it compatible with ``new'' @command{awk}, and
-greatly improving its performance.
+The @samp{\x} escape sequence
+(@pxref{Escape Sequences}).
@item
address@hidden Kwok, Conrad
address@hidden Garfinkle, Scott
address@hidden Williams, Kent
-Conrad Kwok,
-Scott Garfinkle,
-and
-Kent Williams
-did the initial ports to MS-DOS with various versions of MSC.
+Full support for both POSIX and GNU regexps
+(@pxref{Regexp}).
@item
address@hidden Rankin, Pat
-Pat Rankin
-provided the VMS port and its documentation.
+The ability for @code{FS} and for the third
+argument to @code{split()} to be null strings
+(@pxref{Single Character Fields}).
@item
address@hidden Peterson, Hal
-Hal Peterson
-provided help in porting @command{gawk} to Cray systems.
-(This is no longer supported.)
+The ability for @code{RS} to be a regexp
+(@pxref{Records}).
@item
address@hidden Rommel, Kai Uwe
-Kai Uwe Rommel
-provided the initial port to OS/2 and its documentation.
+The ability to use octal and hexadecimal constants in @command{awk}
+program source code
+(@pxref{Nondecimal-numbers}).
@item
address@hidden Jaegermann, Michal
-Michal Jaegermann
-provided the port to Atari systems and its documentation.
-(This port is no longer supported.)
-He continues to provide portability checking with DEC Alpha
-systems, and has done a lot of work to make sure @command{gawk}
-works on non-32-bit systems.
+The @samp{|&} operator for two-way I/O to a coprocess
+(@pxref{Two-way I/O}).
@item
address@hidden Fish, Fred
-Fred Fish
-provided the port to Amiga systems and its documentation.
-(With Fred's sad passing, this is no longer supported.)
+Indirect function calls
+(@pxref{Indirect Calls}).
@item
address@hidden Deifik, Scott
-Scott Deifik
-currently maintains the MS-DOS port using DJGPP.
+Directories on the command line produce a warning and are skipped
+(@pxref{Command line directories}).
address@hidden itemize
@item
address@hidden Zaretskii, Eli
-Eli Zaretskii
-currently maintains the MS-Windows port using MinGW.
+New keywords:
address@hidden @minus{}
address@hidden
+The @code{BEGINFILE} and @code{ENDFILE} special patterns.
+(@pxref{BEGINFILE/ENDFILE}).
@item
address@hidden Grigera, Juan
-Juan Grigera
-provided a port to Windows32 systems.
-(This is no longer supported.)
+The ability to delete all of an array at once with @samp{delete @var{array}}
+(@pxref{Delete}).
@item
address@hidden Hankerson, Darrel
-For many years,
-Dr.@: Darrel Hankerson
-acted as coordinator for the various ports to different PC platforms
-and created binary distributions for various PC operating systems.
-He was also instrumental in keeping the documentation up to date for
-the various PC platforms.
+The @code{nextfile} statement
+(@pxref{Nextfile Statement}).
@item
address@hidden Zoulas, Christos
-Christos Zoulas
-provided the @code{extension()}
-built-in function for dynamically adding new modules.
+The @code{switch} statement
+(@pxref{Switch Statement}).
address@hidden itemize
@item
address@hidden Kahrs, J@"urgen
-J@"urgen Kahrs
-contributed the initial version of the TCP/IP networking
-code and documentation, and motivated the inclusion of the @samp{|&} operator.
+Changes to standard @command{awk} functions:
address@hidden @minus
@item
address@hidden Davies, Stephen
-Stephen Davies
-provided the initial port to Tandem systems and its documentation.
-(However, this is no longer supported.)
-He was also instrumental in the initial work to integrate the
-byte-code internals into the @command{gawk} code base.
+The optional second argument to @code{close()} that allows closing one end
+of a two-way pipe to a coprocess
+(@pxref{Two-way I/O}).
@item
address@hidden Woehlke, Matthew
-Matthew Woehlke
-provided improvements for Tandem's POSIX-compliant systems.
+POSIX compliance for @code{gsub()} and @code{sub()}.
@item
address@hidden Brown, Martin
-Martin Brown
-provided the port to BeOS and its documentation.
-(This is no longer supported.)
+The @code{length()} function accepts an array argument
+and returns the number of elements in the array
+(@pxref{String Functions}).
@item
address@hidden Peters, Arno
-Arno Peters
-did the initial work to convert @command{gawk} to use
-GNU Automake and GNU @code{gettext}.
+The optional third argument to the @code{match()} function
+for capturing text-matching subexpressions within a regexp
+(@pxref{String Functions}).
@item
address@hidden Broder, Alan J.@:
-Alan J.@: Broder
-provided the initial version of the @code{asort()} function
-as well as the code for the optional third argument to the
address@hidden()} function.
+Positional specifiers in @code{printf} formats for
+making translations easier
+(@pxref{Printf Ordering}).
@item
address@hidden Buening, Andreas
-Andreas Buening
-updated the @command{gawk} port for OS/2.
+The @code{split()} function's additional optional fourth
+argument which is an array to hold the text of the field separators.
+(@pxref{String Functions}).
address@hidden itemize
@item
address@hidden Hasegawa, Isamu
-Isamu Hasegawa,
-of IBM in Japan, contributed support for multibyte characters.
+Additional functions only in @command{gawk}:
address@hidden @minus
@item
address@hidden Benzinger, Michael
-Michael Benzinger contributed the initial code for @code{switch} statements.
+The
address@hidden()},
address@hidden()},
address@hidden()},
address@hidden()},
address@hidden()},
+and
address@hidden()}
+functions for bit manipulation
+(@pxref{Bitwise Functions}).
address@hidden In 4.1, and(), or() and xor() grew the ability to take > 2
arguments
@item
address@hidden McPhee, Patrick
-Patrick T.J.@: McPhee contributed the code for dynamic loading in Windows32
-environments.
-(This is no longer supported)
+The @code{asort()} and @code{asorti()} functions for sorting arrays
+(@pxref{Array Sorting}).
@item
address@hidden Haque, John
-John Haque
-reworked the @command{gawk} internals to use a byte-code engine,
-providing the @command{gawk} debugger for @command{awk} programs.
+The @code{bindtextdomain()}, @code{dcgettext()} and @code{dcngettext()}
+functions for internationalization
+(@pxref{Programmer i18n}).
@item
address@hidden Yawitz, Efraim
-Efraim Yawitz contributed the original text for @ref{Debugger}.
+The @code{fflush()} function from Brian Kernighan's
+version of @command{awk}
+(@pxref{I/O Functions}).
@item
address@hidden Robbins, Arnold
-Arnold Robbins
-has been working on @command{gawk} since 1988, at first
-helping David Trueman, and as the primary maintainer since around 1994.
+The @code{gensub()}, @code{patsplit()}, and @code{strtonum()} functions
+for more powerful text manipulation
+(@pxref{String Functions}).
+
address@hidden
+The @code{mktime()}, @code{systime()}, and @code{strftime()}
+functions for working with timestamps
+(@pxref{Time Functions}).
@end itemize
address@hidden Installation
address@hidden Installing @command{gawk}
address@hidden last two commas are part of see also
address@hidden operating systems, See Also GNU/Linux, PC operating systems, Unix
address@hidden STARTOFRANGE gligawk
address@hidden @command{gawk}, installing
address@hidden STARTOFRANGE ingawk
address@hidden installing @command{gawk}
-This appendix provides instructions for installing @command{gawk} on the
-various platforms that are supported by the developers. The primary
-developer supports GNU/Linux (and Unix), whereas the other ports are
-contributed.
address@hidden,
-for the electronic mail addresses of the people who did
-the respective ports.
address@hidden
+Changes and/or additions in the command-line options:
address@hidden
-* Gawk Distribution:: What is in the @command{gawk} distribution.
-* Unix Installation:: Installing @command{gawk} under various
- versions of Unix.
-* Non-Unix Installation:: Installation on Other Operating Systems.
-* Bugs:: Reporting Problems and Bugs.
-* Other Versions:: Other freely available @command{awk}
- implementations.
address@hidden menu
address@hidden @minus
address@hidden
+The @env{AWKPATH} environment variable for specifying a path search for
+the @option{-f} command-line option
+(@pxref{Options}).
address@hidden Gawk Distribution
address@hidden The @command{gawk} Distribution
address@hidden source code, @command{gawk}
address@hidden
+The @env{AWKLIBPATH} environment variable for specifying a path search for
+the @option{-l} command-line option
+(@pxref{Options}).
-This @value{SECTION} describes how to get the @command{gawk}
-distribution, how to extract it, and then what is in the various files and
-subdirectories.
address@hidden
+The ability to use GNU-style long-named options that start with @option{--}
+and the
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
+and
address@hidden
+options
+(@pxref{Options}).
address@hidden itemize
address@hidden
-* Getting:: How to get the distribution.
-* Extracting:: How to extract the distribution.
-* Distribution contents:: What is in the distribution.
address@hidden menu
address@hidden Getting
address@hidden Getting the @command{gawk} Distribution
address@hidden @command{gawk}, source address@hidden obtaining
-There are three ways to get GNU software:
address@hidden new ports
address@hidden @bullet
@item
-Copy it from someone else who already has it.
+Support for the following obsolete systems was removed from the code
+and the documentation for @command{gawk} @value{PVERSION} 4.0:
address@hidden FSF (Free Software Foundation)
address@hidden Free Software Foundation (FSF)
address@hidden nested table
address@hidden @minus
@item
-Retrieve @command{gawk}
-from the Internet host
address@hidden, in the directory @file{/gnu/gawk}.
-Both anonymous @command{ftp} and @code{http} access are supported.
-If you have the @command{wget} program, you can use a command like
-the following:
+Amiga
address@hidden
-wget http://ftp.gnu.org/gnu/gawk/address@hidden@value{PATCHLEVEL}.tar.gz
address@hidden example
address@hidden itemize
address@hidden
+Atari
-The GNU software archive is mirrored around the world.
-The up-to-date list of mirror sites is available from
address@hidden://www.gnu.org/order/ftp.html, the main FSF web site}.
-Try to use one of the mirrors; they
-will be less busy, and you can usually find one closer to your site.
address@hidden
+BeOS
address@hidden Extracting
address@hidden Extracting the Distribution
address@hidden is distributed as several @code{tar} files compressed with
-different compression programs: @command{gzip}, @command{bzip2},
-and @command{xz}. For simplicity, the rest of these instructions assume
-you are using the one compressed with the GNU Zip program, @code{gzip}.
address@hidden
+Cray
-Once you have the distribution (for example,
address@hidden@address@hidden),
-use @code{gzip} to expand the
-file and then use @code{tar} to extract it. You can use the following
-pipeline to produce the @command{gawk} distribution:
address@hidden
+MIPS RiscOS
address@hidden
-# Under System V, add 'o' to the tar options
-gzip -d -c address@hidden@value{PATCHLEVEL}.tar.gz | tar -xvpf -
address@hidden example
address@hidden
+MS-DOS with the Microsoft Compiler
-On a system with GNU @command{tar}, you can let @command{tar}
-do the decompression for you:
address@hidden
+MS-Windows with the Microsoft Compiler
address@hidden
-tar -xvpzf address@hidden@value{PATCHLEVEL}.tar.gz
address@hidden example
address@hidden
+NeXT
address@hidden
-Extracting the archive
-creates a directory named @address@hidden@value{PATCHLEVEL}}
-in the current directory.
address@hidden
+SunOS 3.x, Sun 386 (Road Runner)
-The distribution @value{FN} is of the form
address@hidden@address@hidden@var{P}.tar.gz}.
-The @var{V} represents the major version of @command{gawk},
-the @var{R} represents the current release of version @var{V}, and
-the @var{P} represents a @dfn{patch level}, meaning that minor bugs have
-been fixed in the release. The current patch level is @value{PATCHLEVEL},
-but when retrieving distributions, you should get the version with the highest
-version, release, and patch level. (Note, however, that patch levels greater
than
-or equal to 70 denote ``beta'' or nonproduction software; you might not want
-to retrieve such a version unless you don't mind experimenting.)
-If you are not on a Unix or GNU/Linux system, you need to make other
arrangements
-for getting and extracting the @command{gawk} distribution. You should consult
-a local expert.
address@hidden
+Tandem (non-POSIX)
address@hidden Distribution contents
address@hidden Contents of the @command{gawk} Distribution
address@hidden STARTOFRANGE gawdis
address@hidden @command{gawk}, distribution
address@hidden
+Prestandard VAX C compiler for VAX/VMS
-The @command{gawk} distribution has a number of C source files,
-documentation files,
-subdirectories, and files related to the configuration process
-(@pxref{Unix Installation}),
-as well as several subdirectories related to different non-Unix
-operating systems:
address@hidden itemize
address@hidden @asis
address@hidden Various @samp{.c}, @samp{.y}, and @samp{.h} files
-The actual @command{gawk} source code.
address@hidden table
address@hidden itemize
address@hidden @file
address@hidden README
address@hidden README_d/README.*
-Descriptive files: @file{README} for @command{gawk} under Unix and the
-rest for the various hardware and software combinations.
address@hidden XXX ADD MORE STUFF HERE
address@hidden INSTALL
-A file providing an overview of the configuration and installation process.
address@hidden ENDOFRANGE fripls
address@hidden ENDOFRANGE exgnot
address@hidden ENDOFRANGE posnot
address@hidden ChangeLog
-A detailed list of source code changes as bugs are fixed or improvements made.
address@hidden Common Extensions
address@hidden Common Extensions Summary
address@hidden ChangeLog.0
-An older list of source code changes.
+This @value{SECTION} summarizes the common extensions supported
+by @command{gawk}, Brian Kernighan's @command{awk}, and @command{mawk},
+the three most widely-used freely available versions of @command{awk}
+(@pxref{Other Versions}).
address@hidden NEWS
-A list of changes to @command{gawk} since the last release or patch.
address@hidden address@hidden/dev/stderr} special file} {BWK Awk} {Mawk} {GNU
Awk}
address@hidden Feature @tab BWK Awk @tab Mawk @tab GNU Awk
address@hidden @samp{\x} Escape sequence @tab X @tab X @tab X
address@hidden @code{RS} as regexp @tab @tab X @tab X
address@hidden @code{FS} as null string @tab X @tab X @tab X
address@hidden @file{/dev/stdin} special file @tab X @tab @tab X
address@hidden @file{/dev/stdout} special file @tab X @tab X @tab X
address@hidden @file{/dev/stderr} special file @tab X @tab X @tab X
address@hidden @code{**} and @code{**=} operators @tab X @tab @tab X
address@hidden @code{func} keyword @tab X @tab @tab X
address@hidden @code{nextfile} statement @tab X @tab X @tab X
address@hidden @code{delete} without subscript @tab X @tab X @tab X
address@hidden @code{length()} of an array @tab X @tab @tab X
address@hidden @code{fflush()} function @tab X @tab X @tab X
address@hidden @code{BINMODE} variable @tab @tab X @tab X
address@hidden multitable
address@hidden NEWS.0
-An older list of changes to @command{gawk}.
address@hidden Ranges and Locales
address@hidden Regexp Ranges and Locales: A Long Sad Story
address@hidden COPYING
-The GNU General Public License.
+This @value{SECTION} describes the confusing history of ranges within
+regular expressions and their interactions with locales, and how this
+affected different versions of @command{gawk}.
address@hidden FUTURES
-A brief list of features and changes being contemplated for future
-releases, with some indication of the time frame for the feature, based
-on its difficulty.
+The original Unix tools that worked with regular expressions defined
+character ranges (such as @samp{[a-z]}) to match any character between
+the first character in the range and the last character in the range,
+inclusive. Ordering was based on the numeric value of each character
+in the machine's native character set. Thus, on ASCII-based systems,
address@hidden matched all the lowercase letters, and only the lowercase
+letters, since the numeric values for the letters from @samp{a} through
address@hidden were contiguous. (On an EBCDIC system, the range @samp{[a-z]}
+includes additional, non-alphabetic characters as well.)
address@hidden LIMITATIONS
-A list of those factors that limit @command{gawk}'s performance.
-Most of these depend on the hardware or operating system software and
-are not limits in @command{gawk} itself.
+Almost all introductory Unix literature explained range expressions
+as working in this fashion, and in particular, would teach that the
+``correct'' way to match lowercase letters was with @samp{[a-z]}, and
+that @samp{[A-Z]} was the ``correct'' way to match uppercase letters.
+And indeed, this was true.
address@hidden POSIX.STD
-A description of behaviors in the POSIX standard for @command{awk} which
-are left undefined, or where @command{gawk} may not comply fully, as well
-as a list of things that the POSIX standard should describe but does not.
+The 1993 POSIX standard introduced the idea of locales (@pxref{Locales}).
+Since many locales include other letters besides the plain twenty-six
+letters of the American English alphabet, the POSIX standard added
+character classes (@pxref{Bracket Expressions}) as a way to match
+different kinds of characters besides the traditional ones in the ASCII
+character set.
address@hidden artificial address@hidden @command{gawk} and
address@hidden doc/awkforai.txt
-A short article describing why @command{gawk} is a good language for
-Artificial Intelligence (AI) programming.
+However, the standard @emph{changed} the interpretation of range expressions.
+In the @code{"C"} and @code{"POSIX"} locales, a range expression like
address@hidden is still equivalent to @samp{[abcdxyz]}, as in ASCII.
+But outside those locales, the ordering was defined to be based on
address@hidden order}.
address@hidden doc/bc_notes
-A brief description of @command{gawk}'s ``byte code'' internals.
+In many locales, @samp{A} and @samp{a} are both less than @samp{B}.
+In other words, these locales sort characters in dictionary order,
+and @samp{[a-dx-z]} is typically not equivalent to @samp{[abcdxyz]};
+instead it might be equivalent to @samp{[aBbCcdXxYyz]}, for example.
address@hidden doc/README.card
address@hidden doc/ad.block
address@hidden doc/awkcard.in
address@hidden doc/cardfonts
address@hidden doc/colors
address@hidden doc/macros
address@hidden doc/no.colors
address@hidden doc/setter.outline
-The @command{troff} source for a five-color @command{awk} reference card.
-A modern version of @command{troff} such as GNU @command{troff}
(@command{groff}) is
-needed to produce the color version. See the file @file{README.card}
-for instructions if you have an older @command{troff}.
+This point needs to be emphasized: Much literature teaches that you should
+use @samp{[a-z]} to match a lowercase character. But on systems with
+non-ASCII locales, this also matched all of the uppercase characters
+except @samp{Z}! This was a continuous cause of confusion, even well
+into the twenty-first century.
address@hidden doc/gawk.1
-The @command{troff} source for a manual page describing @command{gawk}.
-This is distributed for the convenience of Unix users.
+To demonstrate these issues, the following example uses the @code{sub()}
+function, which does text replacement (@pxref{String Functions}). Here,
+the intent is to remove trailing uppercase characters:
address@hidden Texinfo
address@hidden doc/gawk.texi
-The Texinfo source file for this @value{DOCUMENT}.
-It should be processed with @TeX{}
-(via @command{texi2dvi} or @command{texi2pdf})
-to produce a printed document, and
-with @command{makeinfo} to produce an Info or HTML file.
address@hidden
+$ @kbd{echo something1234abc | gawk-3.1.8 '@{ sub("[A-Z]*$", ""); print @}'}
address@hidden something1234a
address@hidden example
address@hidden doc/gawk.info
-The generated Info file for this @value{DOCUMENT}.
address@hidden
+This output is unexpected, since the @samp{bc} at the end of
address@hidden 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).
address@hidden doc/gawkinet.texi
-The Texinfo source file for
address@hidden
address@hidden, , General Introduction, gawkinet, TCP/IP Internetworking with
@command{gawk}}.
address@hidden ifinfo
address@hidden
address@hidden/IP Internetworking with @command{gawk}}.
address@hidden ifnotinfo
-It should be processed with @TeX{}
-(via @command{texi2dvi} or @command{texi2pdf})
-to produce a printed document and
-with @command{makeinfo} to produce an Info or HTML file.
+Similar considerations apply to other ranges. For example, @samp{["-/]}
+is perfectly valid in ASCII, but is not valid in many Unicode locales,
+such as @samp{en_US.UTF-8}.
address@hidden doc/gawkinet.info
-The generated Info file for
address@hidden/IP Internetworking with @command{gawk}}.
+Early versions of @command{gawk} used regexp matching code that was not
+locale aware, so ranges had their traditional interpretation.
address@hidden doc/igawk.1
-The @command{troff} source for a manual page describing the @command{igawk}
-program presented in
address@hidden Program}.
+When @command{gawk} switched to using locale-aware regexp matchers,
+the problems began; especially as both GNU/Linux and commercial Unix
+vendors started implementing non-ASCII locales, @emph{and making them
+the default}. Perhaps the most frequently asked question became something
+like ``why does @code{[A-Z]} match lowercase letters?!?''
address@hidden doc/Makefile.in
-The input file used during the configuration process to generate the
-actual @file{Makefile} for creating the documentation.
+This situation existed for close to 10 years, if not more, and
+the @command{gawk} maintainer grew weary of trying to explain that
address@hidden was being nicely standards-compliant, and that the issue
+was in the user's locale. During the development of version 4.0,
+he modified @command{gawk} to always treat ranges in the original,
+pre-POSIX fashion, unless @option{--posix} was used (@pxref{Options}).
address@hidden Makefile.am
address@hidden */Makefile.am
-Files used by the GNU @command{automake} software for generating
-the @file{Makefile.in} files used by @command{autoconf} and
address@hidden
+Fortunately, shortly before the final release of @command{gawk} 4.0,
+the maintainer learned that the 2008 standard had changed the
+definition of ranges, such that outside the @code{"C"} and @code{"POSIX"}
+locales, the meaning of range expressions was
address@hidden@footnote{See
address@hidden://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_03_05,
the standard}
+and
address@hidden://pubs.opengroup.org/onlinepubs/9699919799/xrat/V4_xbd_chap09.html#tag_21_09_03_05,
its rationale}.}
address@hidden Makefile.in
address@hidden aclocal.m4
address@hidden configh.in
address@hidden configure.ac
address@hidden configure
address@hidden custom.h
address@hidden missing_d/*
address@hidden m4/*
-These files and subdirectories are used when configuring @command{gawk}
-for various Unix systems. They are explained in
address@hidden Installation}.
+By using this lovely technical term, the standard gives license
+to implementors to implement ranges in whatever way they choose.
+The @command{gawk} maintainer chose to apply the pre-POSIX meaning in all
+cases: the default regexp matching; with @option{--traditional}, and with
address@hidden; in all cases, @command{gawk} remains POSIX compliant.
address@hidden po/*
-The @file{po} library contains message translations.
address@hidden Contributors
address@hidden Major Contributors to @command{gawk}
address@hidden @command{gawk}, list of contributors to
address@hidden
address@hidden give credit where credit is address@hidden
+Anonymous
address@hidden quotation
address@hidden awklib/extract.awk
address@hidden awklib/Makefile.am
address@hidden awklib/Makefile.in
address@hidden awklib/eg/*
-The @file{awklib} directory contains a copy of @file{extract.awk}
-(@pxref{Extract Program}),
-which can be used to extract the sample programs from the Texinfo
-source file for this @value{DOCUMENT}. It also contains a @file{Makefile.in}
file, which
address@hidden uses to generate a @file{Makefile}.
address@hidden is used by GNU Automake to create @file{Makefile.in}.
-The library functions from
address@hidden Functions},
-and the @command{igawk} program from
address@hidden Program},
-are included as ready-to-use files in the @command{gawk} distribution.
-They are installed as part of the installation process.
-The rest of the programs in this @value{DOCUMENT} are available in appropriate
-subdirectories of @file{awklib/eg}.
+This @value{SECTION} names the major contributors to @command{gawk}
+and/or this @value{DOCUMENT}, in approximate chronological order:
address@hidden posix/*
-Files needed for building @command{gawk} on POSIX-compliant systems.
address@hidden @bullet
address@hidden
address@hidden Aho, Alfred
address@hidden Weinberger, Peter
address@hidden Kernighan, Brian
+Dr.@: Alfred V.@: Aho,
+Dr.@: Peter J.@: Weinberger, and
+Dr.@: Brian W.@: Kernighan, all of Bell Laboratories,
+designed and implemented Unix @command{awk},
+from which @command{gawk} gets the majority of its feature set.
address@hidden pc/*
-Files needed for building @command{gawk} under MS-Windows and OS/2
-(@pxref{PC Installation}, for details).
address@hidden
address@hidden Rubin, Paul
+Paul Rubin
+did the initial design and implementation in 1986, and wrote
+the first draft (around 40 pages) of this @value{DOCUMENT}.
address@hidden vms/*
-Files needed for building @command{gawk} under VMS
-(@pxref{VMS Installation}, for details).
address@hidden
address@hidden Fenlason, Jay
+Jay Fenlason
+finished the initial implementation.
address@hidden test/*
-A test suite for
address@hidden You can use @samp{make check} from the top-level @command{gawk}
-directory to run your version of @command{gawk} against the test suite.
-If @command{gawk} successfully passes @samp{make check}, then you can
-be confident of a successful port.
address@hidden table
address@hidden ENDOFRANGE gawdis
address@hidden
address@hidden Close, Diane
+Diane Close
+revised the first draft of this @value{DOCUMENT}, bringing it
+to around 90 pages.
address@hidden Unix Installation
address@hidden Compiling and Installing @command{gawk} on Unix-like Systems
address@hidden
address@hidden Stallman, Richard
+Richard Stallman
+helped finish the implementation and the initial draft of this
address@hidden
+He is also the founder of the FSF and the GNU project.
-Usually, you can compile and install @command{gawk} by typing only two
-commands. However, if you use an unusual system, you may need
-to configure @command{gawk} for your system yourself.
address@hidden
address@hidden Woods, John
+John Woods
+contributed parts of the code (mostly fixes) in
+the initial version of @command{gawk}.
address@hidden
-* Quick Installation:: Compiling @command{gawk} under Unix.
-* Additional Configuration Options:: Other compile-time options.
-* Configuration Philosophy:: How it's all supposed to work.
address@hidden menu
address@hidden
address@hidden Trueman, David
+In 1988,
+David Trueman
+took over primary maintenance of @command{gawk},
+making it compatible with ``new'' @command{awk}, and
+greatly improving its performance.
address@hidden Quick Installation
address@hidden Compiling @command{gawk} for Unix-like Systems
address@hidden
address@hidden Kwok, Conrad
address@hidden Garfinkle, Scott
address@hidden Williams, Kent
+Conrad Kwok,
+Scott Garfinkle,
+and
+Kent Williams
+did the initial ports to MS-DOS with various versions of MSC.
-The normal installation steps should work on all modern commercial
-Unix-derived systems, GNU/Linux, BSD-based systems, and the Cygwin
-environment for MS-Windows.
address@hidden
address@hidden Rankin, Pat
+Pat Rankin
+provided the VMS port and its documentation.
-After you have extracted the @command{gawk} distribution, @command{cd}
-to @address@hidden@value{PATCHLEVEL}}. Like most GNU software,
address@hidden is configured
-automatically for your system by running the @command{configure} program.
-This program is a Bourne shell script that is generated automatically using
-GNU @command{autoconf}.
address@hidden
-(The @command{autoconf} software is
-described fully in
address@hidden Automatic Configuration Scripts},
-which can be found online at
address@hidden://www.gnu.org/software/autoconf/manual/index.html,
-the Free Software Foundation's web site}.)
address@hidden ifnotinfo
address@hidden
-(The @command{autoconf} software is described fully starting with
address@hidden, , Autoconf, autoconf,Autoconf---Generating Automatic
Configuration Scripts}.)
address@hidden ifinfo
address@hidden
address@hidden Peterson, Hal
+Hal Peterson
+provided help in porting @command{gawk} to Cray systems.
+(This is no longer supported.)
-To configure @command{gawk}, simply run @command{configure}:
address@hidden
address@hidden Rommel, Kai Uwe
+Kai Uwe Rommel
+provided the initial port to OS/2 and its documentation.
address@hidden
-sh ./configure
address@hidden example
address@hidden
address@hidden Jaegermann, Michal
+Michal Jaegermann
+provided the port to Atari systems and its documentation.
+(This port is no longer supported.)
+He continues to provide portability checking with DEC Alpha
+systems, and has done a lot of work to make sure @command{gawk}
+works on non-32-bit systems.
-This produces a @file{Makefile} and @file{config.h} tailored to your system.
-The @file{config.h} file describes various facts about your system.
-You might want to edit the @file{Makefile} to
-change the @code{CFLAGS} variable, which controls
-the command-line options that are passed to the C compiler (such as
-optimization levels or compiling for debugging).
address@hidden
address@hidden Fish, Fred
+Fred Fish
+provided the port to Amiga systems and its documentation.
+(With Fred's sad passing, this is no longer supported.)
-Alternatively, you can add your own values for most @command{make}
-variables on the command line, such as @code{CC} and @code{CFLAGS}, when
-running @command{configure}:
address@hidden
address@hidden Deifik, Scott
+Scott Deifik
+currently maintains the MS-DOS port using DJGPP.
address@hidden
-CC=cc CFLAGS=-g sh ./configure
address@hidden example
address@hidden
address@hidden Zaretskii, Eli
+Eli Zaretskii
+currently maintains the MS-Windows port using MinGW.
address@hidden
-See the file @file{INSTALL} in the @command{gawk} distribution for
-all the details.
-After you have run @command{configure} and possibly edited the @file{Makefile},
-type:
address@hidden
address@hidden Grigera, Juan
+Juan Grigera
+provided a port to Windows32 systems.
+(This is no longer supported.)
address@hidden
-make
address@hidden example
address@hidden
address@hidden Hankerson, Darrel
+For many years,
+Dr.@: Darrel Hankerson
+acted as coordinator for the various ports to different PC platforms
+and created binary distributions for various PC operating systems.
+He was also instrumental in keeping the documentation up to date for
+the various PC platforms.
address@hidden
-Shortly thereafter, you should have an executable version of @command{gawk}.
-That's all there is to it!
-To verify that @command{gawk} is working properly,
-run @samp{make check}. All of the tests should succeed.
-If these steps do not work, or if any of the tests fail,
-check the files in the @file{README_d} directory to see if you've
-found a known problem. If the failure is not described there,
-please send in a bug report (@pxref{Bugs}).
address@hidden
address@hidden Zoulas, Christos
+Christos Zoulas
+provided the @code{extension()}
+built-in function for dynamically adding new modules.
+(This was removed at @command{gawk} 4.1.)
address@hidden Additional Configuration Options
address@hidden Additional Configuration Options
address@hidden @command{gawk}, configuring, options
address@hidden configuration address@hidden @command{gawk}
address@hidden
address@hidden Kahrs, J@"urgen
+J@"urgen Kahrs
+contributed the initial version of the TCP/IP networking
+code and documentation, and motivated the inclusion of the @samp{|&} operator.
-There are several additional options you may use on the @command{configure}
-command line when compiling @command{gawk} from scratch, including:
address@hidden
address@hidden Davies, Stephen
+Stephen Davies
+provided the initial port to Tandem systems and its documentation.
+(However, this is no longer supported.)
+He was also instrumental in the initial work to integrate the
+byte-code internals into the @command{gawk} code base.
address@hidden @code
address@hidden
address@hidden Woehlke, Matthew
+Matthew Woehlke
+provided improvements for Tandem's POSIX-compliant systems.
address@hidden @code{--disable-lint} configuration option
address@hidden configuration option, @code{--disable-lint}
address@hidden --disable-lint
-Disable all lint checking within @code{gawk}. The
address@hidden and @option{--lint-old} options
-(@pxref{Options})
-are accepted, but silently do nothing.
-Similarly, setting the @code{LINT} variable
-(@pxref{User-modified})
-has no effect on the running @command{awk} program.
address@hidden
address@hidden Brown, Martin
+Martin Brown
+provided the port to BeOS and its documentation.
+(This is no longer supported.)
-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.
address@hidden
address@hidden Peters, Arno
+Arno Peters
+did the initial work to convert @command{gawk} to use
+GNU Automake and GNU @code{gettext}.
-Using this option will cause some of the tests in the test suite
-to fail. This option may be removed at a later date.
address@hidden
address@hidden Broder, Alan J.@:
+Alan J.@: Broder
+provided the initial version of the @code{asort()} function
+as well as the code for the optional third argument to the
address@hidden()} function.
address@hidden @code{--disable-nls} configuration option
address@hidden configuration option, @code{--disable-nls}
address@hidden --disable-nls
-Disable all message-translation facilities.
-This is usually not desirable, but it may bring you some slight performance
-improvement.
-
address@hidden @code{--with-whiny-user-strftime} configuration option
address@hidden configuration option, @code{--with-whiny-user-strftime}
address@hidden --with-whiny-user-strftime
-Force use of the included version of the @code{strftime()}
-function for deficient systems.
address@hidden table
-
-Use the command @samp{./configure --help} to see the full list of
-options that @command{configure} supplies.
-
address@hidden Configuration Philosophy
address@hidden The Configuration Process
address@hidden
address@hidden Buening, Andreas
+Andreas Buening
+updated the @command{gawk} port for OS/2.
address@hidden @command{gawk}, configuring
-This @value{SECTION} is of interest only if you know something about using the
-C language and Unix-like operating systems.
address@hidden
address@hidden Hasegawa, Isamu
+Isamu Hasegawa,
+of IBM in Japan, contributed support for multibyte characters.
-The source code for @command{gawk} generally attempts to adhere to formal
-standards wherever possible. This means that @command{gawk} uses library
-routines that are specified by the ISO C standard and by the POSIX
-operating system interface standard.
-The @command{gawk} source code requires using an ISO C compiler (the 1990
-standard).
address@hidden
address@hidden Benzinger, Michael
+Michael Benzinger contributed the initial code for @code{switch} statements.
-Many Unix systems do not support all of either the ISO or the
-POSIX standards. The @file{missing_d} subdirectory in the @command{gawk}
-distribution contains replacement versions of those functions that are
-most likely to be missing.
address@hidden
address@hidden McPhee, Patrick
+Patrick T.J.@: McPhee contributed the code for dynamic loading in Windows32
+environments.
+(This is no longer supported)
-The @file{config.h} file that @command{configure} creates contains
-definitions that describe features of the particular operating system
-where you are attempting to compile @command{gawk}. The three things
-described by this file are: what header files are available, so that
-they can be correctly included, what (supposedly) standard functions
-are actually available in your C libraries, and various miscellaneous
-facts about your operating system. For example, there may not be an
address@hidden element in the @code{stat} structure. In this case,
address@hidden is undefined.
address@hidden
address@hidden Haque, John
+John Haque
+reworked the @command{gawk} internals to use a byte-code engine,
+providing the @command{gawk} debugger for @command{awk} programs.
address@hidden @code{custom.h} file
-It is possible for your C compiler to lie to @command{configure}. It may
-do so by not exiting with an error when a library function is not
-available. To get around this, edit the file @file{custom.h}.
-Use an @samp{#ifdef} that is appropriate for your system, and either
address@hidden any constants that @command{configure} should have defined but
-didn't, or @code{#undef} any constants that @command{configure} defined and
-should not have. @file{custom.h} is automatically included by
address@hidden
address@hidden
address@hidden Yawitz, Efraim
+Efraim Yawitz contributed the original text for @ref{Debugger}.
-It is also possible that the @command{configure} program generated by
address@hidden will not work on your system in some other fashion.
-If you do have a problem, the file @file{configure.ac} is the input for
address@hidden You may be able to change this file and generate a
-new version of @command{configure} that works on your system
-(@pxref{Bugs},
-for information on how to report problems in configuring @command{gawk}).
-The same mechanism may be used to send in updates to @file{configure.ac}
-and/or @file{custom.h}.
address@hidden
address@hidden Robbins, Arnold
+Arnold Robbins
+has been working on @command{gawk} since 1988, at first
+helping David Trueman, and as the primary maintainer since around 1994.
address@hidden itemize
address@hidden Non-Unix Installation
address@hidden Installation on Other Operating Systems
address@hidden Installation
address@hidden Installing @command{gawk}
-This @value{SECTION} describes how to install @command{gawk} on
-various non-Unix systems.
address@hidden last two commas are part of see also
address@hidden operating systems, See Also GNU/Linux, PC operating systems, Unix
address@hidden STARTOFRANGE gligawk
address@hidden @command{gawk}, installing
address@hidden STARTOFRANGE ingawk
address@hidden installing @command{gawk}
+This appendix provides instructions for installing @command{gawk} on the
+various platforms that are supported by the developers. The primary
+developer supports GNU/Linux (and Unix), whereas the other ports are
+contributed.
address@hidden,
+for the electronic mail addresses of the people who did
+the respective ports.
@menu
-* PC Installation:: Installing and Compiling @command{gawk} on
- MS-DOS and OS/2.
-* VMS Installation:: Installing @command{gawk} on VMS.
+* Gawk Distribution:: What is in the @command{gawk} distribution.
+* Unix Installation:: Installing @command{gawk} under various
+ versions of Unix.
+* Non-Unix Installation:: Installation on Other Operating Systems.
+* Bugs:: Reporting Problems and Bugs.
+* Other Versions:: Other freely available @command{awk}
+ implementations.
@end menu
address@hidden Rewritten by Scott Deifik <address@hidden>
address@hidden and Darrel Hankerson <address@hidden>
-
address@hidden PC Installation
address@hidden Installation on PC Operating Systems
-
address@hidden PC operating address@hidden @command{gawk} on, installing
address@hidden operating systems, address@hidden @command{gawk} on, installing
-This @value{SECTION} covers installation and usage of @command{gawk} on x86
machines
-running MS-DOS, any version of MS-Windows, or OS/2.
-In this @value{SECTION}, the term ``Windows32''
-refers to any of Microsoft Windows-95/98/ME/NT/2000/XP/Vista/7.
address@hidden Gawk Distribution
address@hidden The @command{gawk} Distribution
address@hidden source code, @command{gawk}
-The limitations of MS-DOS (and MS-DOS shells under Windows32 or OS/2) has meant
-that various ``DOS extenders'' are often used with programs such as
address@hidden The varying capabilities of Microsoft Windows 3.1
-and Windows32 can add to the confusion. For an overview of the
-considerations, please refer to @file{README_d/README.pc} in the
-distribution.
+This @value{SECTION} describes how to get the @command{gawk}
+distribution, how to extract it, and then what is in the various files and
+subdirectories.
@menu
-* PC Binary Installation:: Installing a prepared distribution.
-* PC Compiling:: Compiling @command{gawk} for MS-DOS,
- Windows32, and OS/2.
-* PC Testing:: Testing @command{gawk} on PC systems.
-* PC Using:: Running @command{gawk} on MS-DOS, Windows32
- and OS/2.
-* Cygwin:: Building and running @command{gawk} for
- Cygwin.
-* MSYS:: Using @command{gawk} In The MSYS Environment.
+* Getting:: How to get the distribution.
+* Extracting:: How to extract the distribution.
+* Distribution contents:: What is in the distribution.
@end menu
address@hidden PC Binary Installation
address@hidden Installing a Prepared Distribution for PC Systems
-
-If you have received a binary distribution prepared by the MS-DOS
-maintainers, then @command{gawk} and the necessary support files appear
-under the @file{gnu} directory, with executables in @file{gnu/bin},
-libraries in @file{gnu/lib/awk}, and manual pages under @file{gnu/man}.
-This is designed for easy installation to a @file{/gnu} directory on your
-drive---however, the files can be installed anywhere provided @env{AWKPATH} is
-set properly. Regardless of the installation directory, the first line of
address@hidden and @file{igawk.bat} (in @file{gnu/bin}) may need to be
-edited.
-
-The binary distribution contains a separate file describing the
-contents. In particular, it may include more than one version of the
address@hidden executable.
address@hidden Getting
address@hidden Getting the @command{gawk} Distribution
address@hidden @command{gawk}, source address@hidden obtaining
+There are three ways to get GNU software:
-OS/2 (32 bit, EMX) binary distributions are prepared for the @file{/usr}
-directory of your preferred drive. Set @env{UNIXROOT} to your installation
-drive (e.g., @samp{e:}) if you want to install @command{gawk} onto another
drive
-than the hardcoded default @samp{c:}. Executables appear in @file{/usr/bin},
-libraries under @file{/usr/share/awk}, manual pages under @file{/usr/man},
-Texinfo documentation under @file{/usr/info}, and NLS files
-under @file{/usr/share/locale}.
-Note that the files can be installed anywhere provided @env{AWKPATH} is
-set properly.
address@hidden @bullet
address@hidden
+Copy it from someone else who already has it.
-If you already have a file @file{/usr/info/dir} from another package
address@hidden not overwrite it!} Instead enter the following commands at your
prompt
-(replace @samp{x:} by your installation drive):
address@hidden FSF (Free Software Foundation)
address@hidden Free Software Foundation (FSF)
address@hidden
+Retrieve @command{gawk}
+from the Internet host
address@hidden, in the directory @file{/gnu/gawk}.
+Both anonymous @command{ftp} and @code{http} access are supported.
+If you have the @command{wget} program, you can use a command like
+the following:
@example
-install-info --info-dir=x:/usr/info x:/usr/info/gawk.info
-install-info --info-dir=x:/usr/info x:/usr/info/gawkinet.info
+wget http://ftp.gnu.org/gnu/gawk/address@hidden@value{PATCHLEVEL}.tar.gz
@end example
address@hidden itemize
-The binary distribution may contain a separate file containing additional
-or more detailed installation instructions.
-
address@hidden PC Compiling
address@hidden Compiling @command{gawk} for PC Operating Systems
+The GNU software archive is mirrored around the world.
+The up-to-date list of mirror sites is available from
address@hidden://www.gnu.org/order/ftp.html, the main FSF web site}.
+Try to use one of the mirrors; they
+will be less busy, and you can usually find one closer to your site.
address@hidden can be compiled for MS-DOS, Windows32, and OS/2 using the GNU
-development tools from DJ Delorie (DJGPP: MS-DOS only) or Eberhard
-Mattes (EMX: MS-DOS, Windows32 and OS/2). The file
address@hidden/README.pc} in the @command{gawk} distribution contains
-additional notes, and @file{pc/Makefile} contains important information on
-compilation options.
address@hidden Extracting
address@hidden Extracting the Distribution
address@hidden is distributed as several @code{tar} files compressed with
+different compression programs: @command{gzip}, @command{bzip2},
+and @command{xz}. For simplicity, the rest of these instructions assume
+you are using the one compressed with the GNU Zip program, @code{gzip}.
address@hidden compiling @command{gawk} for MS-DOS and MS-Windows
-To build @command{gawk} for MS-DOS and Windows32, copy the files in
-the @file{pc} directory (@emph{except} for @file{ChangeLog}) to the
-directory with the rest of the @command{gawk} sources, then invoke
address@hidden with the appropriate target name as an argument to
-build @command{gawk}. The @file{Makefile} copied from the @file{pc}
-directory contains a configuration section with comments and may need
-to be edited in order to work with your @command{make} utility.
+Once you have the distribution (for example,
address@hidden@address@hidden),
+use @code{gzip} to expand the
+file and then use @code{tar} to extract it. You can use the following
+pipeline to produce the @command{gawk} distribution:
-The @file{Makefile} supports a number of targets for building various
-MS-DOS and Windows32 versions. A list of targets is printed if the
address@hidden command is given without a target. As an example, to
-build @command{gawk} using the DJGPP tools, enter @samp{make djgpp}.
-(The DJGPP tools needed for the build may be found at
address@hidden://ftp.delorie.com/pub/djgpp/current/v2gnu/}.) To build a
-native MS-Windows binary of @command{gawk}, type @samp{make mingw32}.
address@hidden
+# Under System V, add 'o' to the tar options
+gzip -d -c address@hidden@value{PATCHLEVEL}.tar.gz | tar -xvpf -
address@hidden example
address@hidden compiling @command{gawk} with EMX for OS/2
-The 32 bit EMX version of @command{gawk} works ``out of the box'' under OS/2.
-However, it is highly recommended to use GCC 2.95.3 for the compilation.
-In principle, it is possible to compile @command{gawk} the following way:
+On a system with GNU @command{tar}, you can let @command{tar}
+do the decompression for you:
@example
-$ @kbd{./configure}
-$ @kbd{make}
+tar -xvpzf address@hidden@value{PATCHLEVEL}.tar.gz
@end example
-This is not recommended, though. To get an OMF executable you should
-use the following commands at your @command{sh} prompt:
-
address@hidden
-$ @kbd{CFLAGS="-O2 -Zomf -Zmt"}
-$ @kbd{export CFLAGS}
-$ @kbd{LDFLAGS="-s -Zcrtdll -Zlinker /exepack:2 -Zlinker /pm:vio -Zstack
0x6000"}
-$ @kbd{export LDFLAGS}
-$ @kbd{RANLIB="echo"}
-$ @kbd{export RANLIB}
-$ @kbd{./configure --prefix=c:/usr}
-$ @kbd{make AR=emxomfar}
address@hidden example
address@hidden
+Extracting the archive
+creates a directory named @address@hidden@value{PATCHLEVEL}}
+in the current directory.
-These are just suggestions for use with GCC 2.x. You may use any other set of
-(self-consistent) environment variables and compiler flags.
+The distribution @value{FN} is of the form
address@hidden@address@hidden@var{P}.tar.gz}.
+The @var{V} represents the major version of @command{gawk},
+the @var{R} represents the current release of version @var{V}, and
+the @var{P} represents a @dfn{patch level}, meaning that minor bugs have
+been fixed in the release. The current patch level is @value{PATCHLEVEL},
+but when retrieving distributions, you should get the version with the highest
+version, release, and patch level. (Note, however, that patch levels greater
than
+or equal to 70 denote ``beta'' or nonproduction software; you might not want
+to retrieve such a version unless you don't mind experimenting.)
+If you are not on a Unix or GNU/Linux system, you need to make other
arrangements
+for getting and extracting the @command{gawk} distribution. You should consult
+a local expert.
address@hidden
-To get an FHS-compliant file hierarchy it is recommended to use the additional
address@hidden options @option{--infodir=c:/usr/share/info},
@option{--mandir=c:/usr/share/man}
-and @option{--libexecdir=c:/usr/lib}.
address@hidden ignore
address@hidden Distribution contents
address@hidden Contents of the @command{gawk} Distribution
address@hidden STARTOFRANGE gawdis
address@hidden @command{gawk}, distribution
address@hidden
-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}).
address@hidden ignore
+The @command{gawk} distribution has a number of C source files,
+documentation files,
+subdirectories, and files related to the configuration process
+(@pxref{Unix Installation}),
+as well as several subdirectories related to different non-Unix
+operating systems:
-If you use GCC 2.95 it is recommended to use also:
address@hidden @asis
address@hidden Various @samp{.c}, @samp{.y}, and @samp{.h} files
+The actual @command{gawk} source code.
address@hidden table
address@hidden
-$ @kbd{LIBS="-lgcc"}
-$ @kbd{export LIBS}
address@hidden example
address@hidden @file
address@hidden README
address@hidden README_d/README.*
+Descriptive files: @file{README} for @command{gawk} under Unix and the
+rest for the various hardware and software combinations.
-You can also get an @code{a.out} executable if you prefer:
address@hidden INSTALL
+A file providing an overview of the configuration and installation process.
address@hidden
-$ @kbd{CFLAGS="-O2 -Zmt"}
-$ @kbd{export CFLAGS}
-$ @kbd{LDFLAGS="-s -Zstack 0x6000"}
-$ @kbd{LIBS="-lgcc"}
-$ @kbd{unset RANLIB}
address@hidden $ ./configure --prefix=c:/usr --without-included-gettext
-$ @kbd{./configure --prefix=c:/usr}
-$ @kbd{make}
address@hidden example
address@hidden ChangeLog
+A detailed list of source code changes as bugs are fixed or improvements made.
address@hidden NOTE
-Compilation of @code{a.out} executables also works with GCC 3.2.
-Versions later than GCC 3.2 have not been tested successfully.
address@hidden quotation
address@hidden ChangeLog.0
+An older list of source code changes.
address@hidden install} works as expected with the EMX build.
address@hidden NEWS
+A list of changes to @command{gawk} since the last release or patch.
address@hidden NOTE
-Ancient OS/2 ports of GNU @command{make} are not able to handle
-the Makefiles of this package. If you encounter any problems with
address@hidden, try GNU Make 3.79.1 or later versions. You should
-find the latest version on
address@hidden://hobbes.nmsu.edu/pub/os2/}.
address@hidden quotation
address@hidden NEWS.0
+An older list of changes to @command{gawk}.
address@hidden PC Testing
address@hidden Testing @command{gawk} on PC Operating Systems
address@hidden COPYING
+The GNU General Public License.
-Using @command{make} to run the standard tests and to install @command{gawk}
-requires additional Unix-like tools, including @command{sh}, @command{sed}, and
address@hidden In order to run the tests, the @file{test/*.ok} files may need to
-be converted so that they have the usual MS-DOS-style end-of-line markers.
-Alternatively, run @command{make check CMP="diff -a"} to use GNU @command{diff}
-in text mode instead of @command{cmp} to compare the resulting files.
address@hidden FUTURES
+A brief list of features and changes being contemplated for future
+releases, with some indication of the time frame for the feature, based
+on its difficulty.
-Most
-of the tests work properly with Stewartson's shell along with the
-companion utilities or appropriate GNU utilities. However, some editing of
address@hidden/Makefile} is required. It is recommended that you copy the file
address@hidden/Makefile.tst} over the file @file{test/Makefile} as a
-replacement. Details can be found in @file{README_d/README.pc}
-and in the file @file{pc/Makefile.tst}.
address@hidden LIMITATIONS
+A list of those factors that limit @command{gawk}'s performance.
+Most of these depend on the hardware or operating system software and
+are not limits in @command{gawk} itself.
-On OS/2 the @code{pid} test fails because @code{spawnl()} is used instead of
address@hidden()}/@code{execl()} to start child processes.
-Also the @code{mbfw1} and @code{mbprintf1} tests fail because the needed
-multibyte functionality is not available.
address@hidden POSIX.STD
+A description of behaviors in the POSIX standard for @command{awk} which
+are left undefined, or where @command{gawk} may not comply fully, as well
+as a list of things that the POSIX standard should describe but does not.
address@hidden artificial address@hidden @command{gawk} and
address@hidden doc/awkforai.txt
+A short article describing why @command{gawk} is a good language for
+Artificial Intelligence (AI) programming.
address@hidden PC Using
address@hidden Using @command{gawk} on PC Operating Systems
address@hidden STARTOFRANGE opgawx
address@hidden operating systems, PC, @command{gawk} on
address@hidden STARTOFRANGE pcgawon
address@hidden PC operating systems, @command{gawk} on
address@hidden doc/bc_notes
+A brief description of @command{gawk}'s ``byte code'' internals.
-With the exception of the Cygwin environment,
-the @samp{|&} operator and TCP/IP networking
-(@pxref{TCP/IP Networking})
-are not supported for MS-DOS or MS-Windows. EMX (OS/2 only) does support
-at least the @samp{|&} operator.
address@hidden doc/README.card
address@hidden doc/ad.block
address@hidden doc/awkcard.in
address@hidden doc/cardfonts
address@hidden doc/colors
address@hidden doc/macros
address@hidden doc/no.colors
address@hidden doc/setter.outline
+The @command{troff} source for a five-color @command{awk} reference card.
+A modern version of @command{troff} such as GNU @command{troff}
(@command{groff}) is
+needed to produce the color version. See the file @file{README.card}
+for instructions if you have an older @command{troff}.
address@hidden search paths
address@hidden search paths, for source files
address@hidden @command{gawk}, OS/2 version of
address@hidden @command{gawk}, MS-DOS version of
address@hidden @command{gawk}, MS-Windows version of
address@hidden @code{;} (semicolon), @code{AWKPATH} variable and
address@hidden semicolon (@code{;}), @code{AWKPATH} variable and
address@hidden @code{AWKPATH} environment variable
-The MS-DOS and MS-Windows versions of @command{gawk} search for
-program files as described in @ref{AWKPATH Variable}. However,
-semicolons (rather than colons) separate elements in the @env{AWKPATH}
-variable. If @env{AWKPATH} is not set or is empty, then the default
-search path for MS-Windows and MS-DOS versions is
address@hidden@w{".;c:/lib/awk;c:/gnu/lib/awk"}}.
address@hidden doc/gawk.1
+The @command{troff} source for a manual page describing @command{gawk}.
+This is distributed for the convenience of Unix users.
address@hidden @code{UNIXROOT} variable, on OS/2 systems
-The search path for OS/2 (32 bit, EMX) is determined by the prefix directory
-(most likely @file{/usr} or @file{c:/usr}) that has been specified as an
option of
-the @command{configure} script like it is the case for the Unix versions.
-If @file{c:/usr} is the prefix directory then the default search path contains
@file{.}
-and @file{c:/usr/share/awk}.
-Additionally, to support binary distributions of @command{gawk} for OS/2
-systems whose drive @samp{c:} might not support long file names or might not
exist
-at all, there is a special environment variable. If @env{UNIXROOT} specifies
-a drive then this specific drive is also searched for program files.
-E.g., if @env{UNIXROOT} is set to @file{e:} the complete default search path is
address@hidden@w{".;c:/usr/share/awk;e:/usr/share/awk"}}.
address@hidden Texinfo
address@hidden doc/gawk.texi
+The Texinfo source file for this @value{DOCUMENT}.
+It should be processed with @TeX{}
+(via @command{texi2dvi} or @command{texi2pdf})
+to produce a printed document, and
+with @command{makeinfo} to produce an Info or HTML file.
-An @command{sh}-like shell (as opposed to @command{command.com} under MS-DOS
-or @command{cmd.exe} under MS-Windows or OS/2) may be useful for @command{awk}
programming.
-The DJGPP collection of tools includes an MS-DOS port of Bash,
-and several shells are available for OS/2, including @command{ksh}.
address@hidden doc/gawk.info
+The generated Info file for this @value{DOCUMENT}.
address@hidden common extensions, @code{BINMODE} variable
address@hidden extensions, address@hidden @code{BINMODE} variable
address@hidden differences in @command{awk} and @command{gawk}, @code{BINMODE}
variable
address@hidden @code{BINMODE} variable
-Under MS-Windows, OS/2 and MS-DOS, @command{gawk} (and many other text
programs) silently
-translate end-of-line @code{"\r\n"} to @code{"\n"} on input and @code{"\n"}
-to @code{"\r\n"} on output. A special @code{BINMODE} variable
@value{COMMONEXT}
-allows control over these translations and is interpreted as follows:
address@hidden doc/gawkinet.texi
+The Texinfo source file for
address@hidden
address@hidden, , General Introduction, gawkinet, TCP/IP Internetworking with
@command{gawk}}.
address@hidden ifinfo
address@hidden
address@hidden/IP Internetworking with @command{gawk}}.
address@hidden ifnotinfo
+It should be processed with @TeX{}
+(via @command{texi2dvi} or @command{texi2pdf})
+to produce a printed document and
+with @command{makeinfo} to produce an Info or HTML file.
address@hidden @bullet
address@hidden
-If @code{BINMODE} is @code{"r"}, or one,
-then
-binary mode is set on read (i.e., no translations on reads).
address@hidden doc/gawkinet.info
+The generated Info file for
address@hidden/IP Internetworking with @command{gawk}}.
address@hidden
-If @code{BINMODE} is @code{"w"}, or two,
-then
-binary mode is set on write (i.e., no translations on writes).
address@hidden doc/igawk.1
+The @command{troff} source for a manual page describing the @command{igawk}
+program presented in
address@hidden Program}.
address@hidden
-If @code{BINMODE} is @code{"rw"} or @code{"wr"} or three,
-binary mode is set for both read and write.
address@hidden doc/Makefile.in
+The input file used during the configuration process to generate the
+actual @file{Makefile} for creating the documentation.
address@hidden
address@hidden@var{non-null-string}} is
-the same as @samp{BINMODE=3} (i.e., no translations on
-reads or writes). However, @command{gawk} issues a warning
-message if the string is not one of @code{"rw"} or @code{"wr"}.
address@hidden itemize
address@hidden Makefile.am
address@hidden */Makefile.am
+Files used by the GNU @command{automake} software for generating
+the @file{Makefile.in} files used by @command{autoconf} and
address@hidden
address@hidden
-The modes for standard input and standard output are set one time
-only (after the
-command line is read, but before processing any of the @command{awk} program).
-Setting @code{BINMODE} for standard input or
-standard output is accomplished by using an
-appropriate @samp{-v address@hidden option on the command line.
address@hidden is set at the time a file or pipe is opened and cannot be
-changed mid-stream.
-
-The name @code{BINMODE} was chosen to match @command{mawk}
-(@pxref{Other Versions}).
address@hidden and @command{gawk} handle @code{BINMODE} similarly; however,
address@hidden adds a @samp{-W address@hidden option and an environment
-variable that can set @code{BINMODE}, @code{RS}, and @code{ORS}. The
-files @file{binmode[1-3].awk} (under @file{gnu/lib/awk} in some of the
-prepared distributions) have been chosen to match @command{mawk}'s @samp{-W
address@hidden option. These can be changed or discarded; in particular,
-the setting of @code{RS} giving the fewest ``surprises'' is open to debate.
address@hidden uses @samp{RS = "\r\n"} if binary mode is set on read, which is
-appropriate for files with the MS-DOS-style end-of-line.
-
-To illustrate, the following examples set binary mode on writes for standard
-output and other files, and set @code{ORS} as the ``usual'' MS-DOS-style
-end-of-line:
-
address@hidden
-gawk -v BINMODE=2 -v ORS="\r\n" @dots{}
address@hidden example
-
address@hidden
-or:
-
address@hidden
-gawk -v BINMODE=w -f binmode2.awk @dots{}
address@hidden example
-
address@hidden
-These give the same result as the @samp{-W BINMODE=2} option in
address@hidden
-The following changes the record separator to @code{"\r\n"} and sets binary
-mode on reads, but does not affect the mode on standard input:
-
address@hidden
-gawk -v RS="\r\n" --source "BEGIN @{ BINMODE = 1 @}" @dots{}
address@hidden example
-
address@hidden
-or:
-
address@hidden
-gawk -f binmode1.awk @dots{}
address@hidden example
-
address@hidden
-With proper quoting, in the first example the setting of @code{RS} can be
-moved into the @code{BEGIN} rule.
-
address@hidden Cygwin
address@hidden Using @command{gawk} In The Cygwin Environment
address@hidden compiling @command{gawk} for Cygwin
-
address@hidden can be built and used ``out of the box'' under MS-Windows
-if you are using the @uref{http://www.cygwin.com, Cygwin environment}.
-This environment provides an excellent simulation of Unix, using the
-GNU tools, such as Bash, the GNU Compiler Collection (GCC), GNU Make,
-and other GNU programs. Compilation and installation for Cygwin is the
-same as for a Unix system:
-
address@hidden
-tar -xvpzf address@hidden@value{PATCHLEVEL}.tar.gz
-cd address@hidden@value{PATCHLEVEL}
-./configure
-make
address@hidden example
address@hidden Makefile.in
address@hidden aclocal.m4
address@hidden configh.in
address@hidden configure.ac
address@hidden configure
address@hidden custom.h
address@hidden missing_d/*
address@hidden m4/*
+These files and subdirectories are used when configuring @command{gawk}
+for various Unix systems. They are explained in
address@hidden Installation}.
-When compared to GNU/Linux on the same system, the @samp{configure}
-step on Cygwin takes considerably longer. However, it does finish,
-and then the @samp{make} proceeds as usual.
address@hidden po/*
+The @file{po} library contains message translations.
address@hidden NOTE
-The @samp{|&} operator and TCP/IP networking
-(@pxref{TCP/IP Networking})
-are fully supported in the Cygwin environment. This is not true
-for any other environment on MS-Windows.
address@hidden quotation
address@hidden awklib/extract.awk
address@hidden awklib/Makefile.am
address@hidden awklib/Makefile.in
address@hidden awklib/eg/*
+The @file{awklib} directory contains a copy of @file{extract.awk}
+(@pxref{Extract Program}),
+which can be used to extract the sample programs from the Texinfo
+source file for this @value{DOCUMENT}. It also contains a @file{Makefile.in}
file, which
address@hidden uses to generate a @file{Makefile}.
address@hidden is used by GNU Automake to create @file{Makefile.in}.
+The library functions from
address@hidden Functions},
+and the @command{igawk} program from
address@hidden Program},
+are included as ready-to-use files in the @command{gawk} distribution.
+They are installed as part of the installation process.
+The rest of the programs in this @value{DOCUMENT} are available in appropriate
+subdirectories of @file{awklib/eg}.
address@hidden MSYS
address@hidden Using @command{gawk} In The MSYS Environment
address@hidden posix/*
+Files needed for building @command{gawk} on POSIX-compliant systems.
-In the MSYS environment under MS-Windows, @command{gawk} automatically
-uses binary mode for reading and writing files. Thus there is no
-need to use the @code{BINMODE} variable.
address@hidden pc/*
+Files needed for building @command{gawk} under MS-Windows and OS/2
+(@pxref{PC Installation}, for details).
-This can cause problems with other Unix-like components that have
-been ported to MS-Windows that expect @command{gawk} to do automatic
-translation of @code{"\r\n"}, since it won't. Caveat Emptor!
address@hidden vms/*
+Files needed for building @command{gawk} under VMS
+(@pxref{VMS Installation}, for details).
address@hidden VMS Installation
address@hidden How to Compile and Install @command{gawk} on VMS
address@hidden test/*
+A test suite for
address@hidden You can use @samp{make check} from the top-level @command{gawk}
+directory to run your version of @command{gawk} against the test suite.
+If @command{gawk} successfully passes @samp{make check}, then you can
+be confident of a successful port.
address@hidden table
address@hidden ENDOFRANGE gawdis
address@hidden based on material from Pat Rankin <address@hidden>
address@hidden now address@hidden
address@hidden now address@hidden
address@hidden Unix Installation
address@hidden Compiling and Installing @command{gawk} on Unix-like Systems
address@hidden @command{gawk}, VMS version of
address@hidden installation, VMS
-This @value{SUBSECTION} describes how to compile and install @command{gawk}
under VMS.
-The older designation ``VMS'' is used throughout to refer to OpenVMS.
+Usually, you can compile and install @command{gawk} by typing only two
+commands. However, if you use an unusual system, you may need
+to configure @command{gawk} for your system yourself.
@menu
-* VMS Compilation:: How to compile @command{gawk} under VMS.
-* VMS Installation Details:: How to install @command{gawk} under VMS.
-* VMS Running:: How to run @command{gawk} under VMS.
-* VMS Old Gawk:: An old version comes with some VMS systems.
+* Quick Installation:: Compiling @command{gawk} under Unix.
+* Additional Configuration Options:: Other compile-time options.
+* Configuration Philosophy:: How it's all supposed to work.
@end menu
address@hidden VMS Compilation
address@hidden Compiling @command{gawk} on VMS
address@hidden compiling @command{gawk} for VMS
address@hidden Quick Installation
address@hidden Compiling @command{gawk} for Unix-like Systems
-To compile @command{gawk} under VMS, there is a @code{DCL} command procedure
that
-issues all the necessary @code{CC} and @code{LINK} commands. There is
-also a @file{Makefile} for use with the @code{MMS} utility. From the source
-directory, use either:
+The normal installation steps should work on all modern commercial
+Unix-derived systems, GNU/Linux, BSD-based systems, and the Cygwin
+environment for MS-Windows.
address@hidden
-$ @kbd{@@[.VMS]VMSBUILD.COM}
address@hidden example
+After you have extracted the @command{gawk} distribution, @command{cd}
+to @address@hidden@value{PATCHLEVEL}}. Like most GNU software,
address@hidden is configured
+automatically for your system by running the @command{configure} program.
+This program is a Bourne shell script that is generated automatically using
+GNU @command{autoconf}.
address@hidden
+(The @command{autoconf} software is
+described fully in
address@hidden Automatic Configuration Scripts},
+which can be found online at
address@hidden://www.gnu.org/software/autoconf/manual/index.html,
+the Free Software Foundation's web site}.)
address@hidden ifnotinfo
address@hidden
+(The @command{autoconf} software is described fully starting with
address@hidden, , Autoconf, autoconf,Autoconf---Generating Automatic
Configuration Scripts}.)
address@hidden ifinfo
address@hidden
-or:
+To configure @command{gawk}, simply run @command{configure}:
@example
-$ @kbd{MMS/DESCRIPTION=[.VMS]DESCRIP.MMS GAWK}
+sh ./configure
@end example
-Older versions of @command{gawk} could be built with VAX C or
-GNU C on VAX/VMS, as well as with DEC C, but that is no longer
-supported. DEC C (also briefly known as ``Compaq C'' and now known
-as ``HP C,'' but referred to here as ``DEC C'') is required. Both
address@hidden and @code{DESCRIP.MMS} contain some obsolete support
-for the older compilers but are set up to use DEC C by default.
-
address@hidden has been tested under Alpha/VMS 7.3-1 using Compaq C V6.4,
-and on Alpha/VMS 7.3, Alpha/VMS 7.3-2, and IA64/VMS address@hidden IA64
-architecture is also known as ``Itanium.''}
-
address@hidden VMS Installation Details
address@hidden Installing @command{gawk} on VMS
+This produces a @file{Makefile} and @file{config.h} tailored to your system.
+The @file{config.h} file describes various facts about your system.
+You might want to edit the @file{Makefile} to
+change the @code{CFLAGS} variable, which controls
+the command-line options that are passed to the C compiler (such as
+optimization levels or compiling for debugging).
-To install @command{gawk}, all you need is a ``foreign'' command, which is
-a @code{DCL} symbol whose value begins with a dollar sign. For example:
+Alternatively, you can add your own values for most @command{make}
+variables on the command line, such as @code{CC} and @code{CFLAGS}, when
+running @command{configure}:
@example
-$ @kbd{GAWK :== $disk1:[gnubin]GAWK}
+CC=cc CFLAGS=-g sh ./configure
@end example
@noindent
-Substitute the actual location of @command{gawk.exe} for
address@hidden:[gnubin]}. The symbol should be placed in the
address@hidden of any user who wants to run @command{gawk},
-so that it is defined every time the user logs on.
-Alternatively, the symbol may be placed in the system-wide
address@hidden procedure, which allows all users
-to run @command{gawk}.
+See the file @file{INSTALL} in the @command{gawk} distribution for
+all the details.
-Optionally, the help entry can be loaded into a VMS help library:
+After you have run @command{configure} and possibly edited the @file{Makefile},
+type:
@example
-$ @kbd{LIBRARY/HELP SYS$HELP:HELPLIB [.VMS]GAWK.HLP}
+make
@end example
@noindent
-(You may want to substitute a site-specific help library rather than
-the standard VMS library @samp{HELPLIB}.) After loading the help text,
-the command:
+Shortly thereafter, you should have an executable version of @command{gawk}.
+That's all there is to it!
+To verify that @command{gawk} is working properly,
+run @samp{make check}. All of the tests should succeed.
+If these steps do not work, or if any of the tests fail,
+check the files in the @file{README_d} directory to see if you've
+found a known problem. If the failure is not described there,
+please send in a bug report (@pxref{Bugs}).
address@hidden
-$ @kbd{HELP GAWK}
address@hidden example
address@hidden Additional Configuration Options
address@hidden Additional Configuration Options
address@hidden @command{gawk}, configuring, options
address@hidden configuration address@hidden @command{gawk}
address@hidden
-provides information about both the @command{gawk} implementation and the
address@hidden programming language.
+There are several additional options you may use on the @command{configure}
+command line when compiling @command{gawk} from scratch, including:
-The logical name @samp{AWK_LIBRARY} can designate a default location
-for @command{awk} program files. For the @option{-f} option, if the specified
address@hidden has no device or directory path information in it, @command{gawk}
-looks in the current directory first, then in the directory specified
-by the translation of @samp{AWK_LIBRARY} if the file is not found.
-If, after searching in both directories, the file still is not found,
address@hidden appends the suffix @samp{.awk} to the filename and retries
-the file search. If @samp{AWK_LIBRARY} has no definition, a default value
-of @samp{SYS$LIBRARY:} is used for it.
address@hidden @code
address@hidden VMS Running
address@hidden Running @command{gawk} on VMS
address@hidden @code{--disable-lint} configuration option
address@hidden configuration option, @code{--disable-lint}
address@hidden --disable-lint
+Disable all lint checking within @code{gawk}. The
address@hidden and @option{--lint-old} options
+(@pxref{Options})
+are accepted, but silently do nothing.
+Similarly, setting the @code{LINT} variable
+(@pxref{User-modified})
+has no effect on the running @command{awk} program.
-Command-line parsing and quoting conventions are significantly different
-on VMS, so examples in this @value{DOCUMENT} or from other sources often need
minor
-changes. They @emph{are} minor though, and all @command{awk} programs
-should run correctly.
+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.
-Here are a couple of trivial tests:
+Using this option will cause some of the tests in the test suite
+to fail. This option may be removed at a later date.
address@hidden
-$ @kbd{gawk -- "BEGIN @{print ""Hello, World!""@}"}
-$ @kbd{gawk -"W" version}
-! could also be -"W version" or "-W version"
address@hidden example
address@hidden @code{--disable-nls} configuration option
address@hidden configuration option, @code{--disable-nls}
address@hidden --disable-nls
+Disable all message-translation facilities.
+This is usually not desirable, but it may bring you some slight performance
+improvement.
address@hidden
-Note that uppercase and mixed-case text must be quoted.
address@hidden @code{--with-whiny-user-strftime} configuration option
address@hidden configuration option, @code{--with-whiny-user-strftime}
address@hidden --with-whiny-user-strftime
+Force use of the included version of the @code{strftime()}
+function for deficient systems.
address@hidden table
-The VMS port of @command{gawk} includes a @code{DCL}-style interface in
addition
-to the original shell-style interface (see the help entry for details).
-One side effect of dual command-line parsing is that if there is only a
-single parameter (as in the quoted string program above), the command
-becomes ambiguous. To work around this, the normally optional @option{--}
-flag is required to force Unix-style parsing rather than @code{DCL} parsing.
If any
-other dash-type options (or multiple parameters such as @value{DF}s to
-process) are present, there is no ambiguity and @option{--} can be omitted.
+Use the command @samp{./configure --help} to see the full list of
+options that @command{configure} supplies.
address@hidden @cindex directory search
address@hidden @cindex path, search
address@hidden search paths
address@hidden search paths, for source files
-The default search path, when looking for @command{awk} program files specified
-by the @option{-f} option, is @code{"SYS$DISK:[],AWK_LIBRARY:"}. The logical
-name @env{AWKPATH} can be used to override this default. The format
-of @env{AWKPATH} is a comma-separated list of directory specifications.
-When defining it, the value should be quoted so that it retains a single
-translation and not a multitranslation @code{RMS} searchlist.
address@hidden Configuration Philosophy
address@hidden The Configuration Process
address@hidden
address@hidden The VMS POSIX product, also known as POSIX for OpenVMS, is long
defunct
address@hidden and building gawk for it has not been tested in many years, but
these
address@hidden old instructions might still work if anyone is still using it.
address@hidden @command{gawk}, configuring
+This @value{SECTION} is of interest only if you know something about using the
+C language and Unix-like operating systems.
address@hidden VMS POSIX
address@hidden Building and Using @command{gawk} on VMS POSIX
+The source code for @command{gawk} generally attempts to adhere to formal
+standards wherever possible. This means that @command{gawk} uses library
+routines that are specified by the ISO C standard and by the POSIX
+operating system interface standard.
+The @command{gawk} source code requires using an ISO C compiler (the 1990
+standard).
-Ignore the instructions above, although @file{vms/gawk.hlp} should still
-be made available in a help library. The source tree should be unpacked
-into a container file subsystem rather than into the ordinary VMS filesystem.
-Make sure that the two scripts, @file{configure} and
address@hidden/posix-cc.sh}, are executable; use @samp{chmod +x} on them if
-necessary. Then execute the following two commands:
+Many Unix systems do not support all of either the ISO or the
+POSIX standards. The @file{missing_d} subdirectory in the @command{gawk}
+distribution contains replacement versions of those functions that are
+most likely to be missing.
address@hidden
-psx> @kbd{CC=vms/posix-cc.sh configure}
-psx> @kbd{make CC=c89 gawk}
address@hidden example
+The @file{config.h} file that @command{configure} creates contains
+definitions that describe features of the particular operating system
+where you are attempting to compile @command{gawk}. The three things
+described by this file are: what header files are available, so that
+they can be correctly included, what (supposedly) standard functions
+are actually available in your C libraries, and various miscellaneous
+facts about your operating system. For example, there may not be an
address@hidden element in the @code{stat} structure. In this case,
address@hidden is undefined.
address@hidden
-The first command constructs files @file{config.h} and @file{Makefile} out
-of templates, using a script to make the C compiler fit @command{configure}'s
-expectations. The second command compiles and links @command{gawk} using
-the C compiler directly; ignore any warnings from @command{make} about being
-unable to redefine @code{CC}. @command{configure} takes a very long
-time to execute, but at least it provides incremental feedback as it runs.
address@hidden @code{custom.h} file
+It is possible for your C compiler to lie to @command{configure}. It may
+do so by not exiting with an error when a library function is not
+available. To get around this, edit the file @file{custom.h}.
+Use an @samp{#ifdef} that is appropriate for your system, and either
address@hidden any constants that @command{configure} should have defined but
+didn't, or @code{#undef} any constants that @command{configure} defined and
+should not have. @file{custom.h} is automatically included by
address@hidden
-This has been tested with VAX/VMS V6.2, VMS POSIX V2.0, and DEC C V5.2.
+It is also possible that the @command{configure} program generated by
address@hidden will not work on your system in some other fashion.
+If you do have a problem, the file @file{configure.ac} is the input for
address@hidden You may be able to change this file and generate a
+new version of @command{configure} that works on your system
+(@pxref{Bugs},
+for information on how to report problems in configuring @command{gawk}).
+The same mechanism may be used to send in updates to @file{configure.ac}
+and/or @file{custom.h}.
-Once built, @command{gawk} works like any other shell utility. Unlike
-the normal VMS port of @command{gawk}, no special command-line manipulation is
-needed in the VMS POSIX environment.
address@hidden ignore
address@hidden Non-Unix Installation
address@hidden Installation on Other Operating Systems
address@hidden VMS Old Gawk
address@hidden Some VMS Systems Have An Old Version of @command{gawk}
+This @value{SECTION} describes how to install @command{gawk} on
+various non-Unix systems.
address@hidden Thanks to "gerard labadie" <address@hidden>
address@hidden
+* PC Installation:: Installing and Compiling @command{gawk} on
+ MS-DOS and OS/2.
+* VMS Installation:: Installing @command{gawk} on VMS.
address@hidden menu
-Some versions of VMS have an old version of @command{gawk}. To access it,
-define a symbol, as follows:
address@hidden Rewritten by Scott Deifik <address@hidden>
address@hidden and Darrel Hankerson <address@hidden>
address@hidden
-$ @kbd{gawk :== $sys$common:[syshlp.examples.tcpip.snmp]gawk.exe}
address@hidden example
address@hidden PC Installation
address@hidden Installation on PC Operating Systems
-This is apparently @value{PVERSION} 2.15.6, which is extremely old. We
-recommend compiling and using the current version.
address@hidden PC operating address@hidden @command{gawk} on, installing
address@hidden operating systems, address@hidden @command{gawk} on, installing
+This @value{SECTION} covers installation and usage of @command{gawk} on x86
machines
+running MS-DOS, any version of MS-Windows, or OS/2.
+In this @value{SECTION}, the term ``Windows32''
+refers to any of Microsoft Windows-95/98/ME/NT/2000/XP/Vista/7.
address@hidden ENDOFRANGE opgawx
address@hidden ENDOFRANGE pcgawon
+The limitations of MS-DOS (and MS-DOS shells under Windows32 or OS/2) has meant
+that various ``DOS extenders'' are often used with programs such as
address@hidden The varying capabilities of Microsoft Windows 3.1
+and Windows32 can add to the confusion. For an overview of the
+considerations, please refer to @file{README_d/README.pc} in the
+distribution.
address@hidden Bugs
address@hidden Reporting Problems and Bugs
address@hidden archeologists
address@hidden
address@hidden is nothing more dangerous than a bored address@hidden
-The Hitchhiker's Guide to the Galaxy
address@hidden quotation
address@hidden the radio show, not the book. :-)
address@hidden
+* PC Binary Installation:: Installing a prepared distribution.
+* PC Compiling:: Compiling @command{gawk} for MS-DOS,
+ Windows32, and OS/2.
+* PC Testing:: Testing @command{gawk} on PC systems.
+* PC Using:: Running @command{gawk} on MS-DOS, Windows32
+ and OS/2.
+* Cygwin:: Building and running @command{gawk} for
+ Cygwin.
+* MSYS:: Using @command{gawk} In The MSYS Environment.
address@hidden menu
address@hidden STARTOFRANGE dbugg
address@hidden debugging @command{gawk}, bug reports
address@hidden STARTOFRANGE tblgawb
address@hidden troubleshooting, @command{gawk}, bug reports
-If you have problems with @command{gawk} or think that you have found a bug,
-please report it to the developers; we cannot promise to do anything
-but we might well want to fix it.
address@hidden PC Binary Installation
address@hidden Installing a Prepared Distribution for PC Systems
-Before reporting a bug, make sure you have actually found a real bug.
-Carefully reread the documentation and see if it really says you can do
-what you're trying to do. If it's not clear whether you should be able
-to do something or not, report that too; it's a bug in the documentation!
+If you have received a binary distribution prepared by the MS-DOS
+maintainers, then @command{gawk} and the necessary support files appear
+under the @file{gnu} directory, with executables in @file{gnu/bin},
+libraries in @file{gnu/lib/awk}, and manual pages under @file{gnu/man}.
+This is designed for easy installation to a @file{/gnu} directory on your
+drive---however, the files can be installed anywhere provided @env{AWKPATH} is
+set properly. Regardless of the installation directory, the first line of
address@hidden and @file{igawk.bat} (in @file{gnu/bin}) may need to be
+edited.
-Before reporting a bug or trying to fix it yourself, try to isolate it
-to the smallest possible @command{awk} program and input @value{DF} that
-reproduces the problem. Then send us the program and @value{DF},
-some idea of what kind of Unix system you're using,
-the compiler you used to compile @command{gawk}, and the exact results
address@hidden gave you. Also say what you expected to occur; this helps
-us decide whether the problem is really in the documentation.
+The binary distribution contains a separate file describing the
+contents. In particular, it may include more than one version of the
address@hidden executable.
-Please include the version number of @command{gawk} you are using.
-You can get this information with the command @samp{gawk --version}.
+OS/2 (32 bit, EMX) binary distributions are prepared for the @file{/usr}
+directory of your preferred drive. Set @env{UNIXROOT} to your installation
+drive (e.g., @samp{e:}) if you want to install @command{gawk} onto another
drive
+than the hardcoded default @samp{c:}. Executables appear in @file{/usr/bin},
+libraries under @file{/usr/share/awk}, manual pages under @file{/usr/man},
+Texinfo documentation under @file{/usr/info}, and NLS files
+under @file{/usr/share/locale}.
+Note that the files can be installed anywhere provided @env{AWKPATH} is
+set properly.
address@hidden @code{bug-gawk@@gnu.org} bug reporting address
address@hidden email address for bug reports, @code{bug-gawk@@gnu.org}
address@hidden bug reports, email address, @code{bug-gawk@@gnu.org}
-Once you have a precise problem, send email to
address@hidden@@gnu.org,bug-gawk at gnu dot org}.
+If you already have a file @file{/usr/info/dir} from another package
address@hidden not overwrite it!} Instead enter the following commands at your
prompt
+(replace @samp{x:} by your installation drive):
address@hidden Robbins, Arnold
-Using this address automatically sends a copy of your
-mail to me. If necessary, I can be reached directly at
address@hidden@@skeeve.com,arnold at skeeve dot com}.
-The bug reporting address is preferred since the
-email list is archived at the GNU Project.
address@hidden email should be in English, since that is my native language.}
-
address@hidden @code{comp.lang.awk} newsgroup
address@hidden CAUTION
-Do @emph{not} try to report bugs in @command{gawk} by
-posting to the Usenet/Internet newsgroup @code{comp.lang.awk}.
-While the @command{gawk} developers do occasionally read this newsgroup,
-there is no guarantee that we will see your posting. The steps described
-above are the official recognized ways for reporting bugs.
-Really.
address@hidden quotation
-
address@hidden NOTE
-Many distributions of GNU/Linux and the various BSD-based operating systems
-have their own bug reporting systems. If you report a bug using your
distribution's
-bug reporting system, @emph{please} also send a copy to
address@hidden@@gnu.org,bug-gawk at gnu dot org}.
address@hidden
+install-info --info-dir=x:/usr/info x:/usr/info/gawk.info
+install-info --info-dir=x:/usr/info x:/usr/info/gawkinet.info
address@hidden example
-This is for two reasons. First, while some distributions forward
-bug reports ``upstream'' to the GNU mailing list, many don't, so there is a
good
-chance that the @command{gawk} maintainer won't even see the bug report!
Second,
-mail to the GNU list is archived, and having everything at the GNU project
-keeps things self-contained and not dependant on other web sites.
address@hidden quotation
+The binary distribution may contain a separate file containing additional
+or more detailed installation instructions.
-Non-bug suggestions are always welcome as well. If you have questions
-about things that are unclear in the documentation or are just obscure
-features, ask me; I will try to help you out, although I
-may not have the time to fix the problem. You can send me electronic
-mail at the Internet address noted previously.
address@hidden PC Compiling
address@hidden Compiling @command{gawk} for PC Operating Systems
-If you find bugs in one of the non-Unix ports of @command{gawk}, please send
-an electronic mail message to the person who maintains that port. They
-are named in the following list, as well as in the @file{README} file in the
@command{gawk}
-distribution. Information in the @file{README} file should be considered
-authoritative if it conflicts with this @value{DOCUMENT}.
address@hidden can be compiled for MS-DOS, Windows32, and OS/2 using the GNU
+development tools from DJ Delorie (DJGPP: MS-DOS only) or Eberhard
+Mattes (EMX: MS-DOS, Windows32 and OS/2). The file
address@hidden/README.pc} in the @command{gawk} distribution contains
+additional notes, and @file{pc/Makefile} contains important information on
+compilation options.
-The people maintaining the non-Unix ports of @command{gawk} are
-as follows:
address@hidden compiling @command{gawk} for MS-DOS and MS-Windows
+To build @command{gawk} for MS-DOS and Windows32, copy the files in
+the @file{pc} directory (@emph{except} for @file{ChangeLog}) to the
+directory with the rest of the @command{gawk} sources, then invoke
address@hidden with the appropriate target name as an argument to
+build @command{gawk}. The @file{Makefile} copied from the @file{pc}
+directory contains a configuration section with comments and may need
+to be edited in order to work with your @command{make} utility.
address@hidden {MS-Windows with MINGW}
{123456789012345678901234567890123456789001234567890}
address@hidden Deifik, Scott
address@hidden MS-DOS with DJGPP @tab Scott Deifik,
@EMAIL{scottd.mail@@sbcglobal.net,scottd dot mail at sbcglobal dot net}.
+The @file{Makefile} supports a number of targets for building various
+MS-DOS and Windows32 versions. A list of targets is printed if the
address@hidden command is given without a target. As an example, to
+build @command{gawk} using the DJGPP tools, enter @samp{make djgpp}.
+(The DJGPP tools needed for the build may be found at
address@hidden://ftp.delorie.com/pub/djgpp/current/v2gnu/}.) To build a
+native MS-Windows binary of @command{gawk}, type @samp{make mingw32}.
address@hidden Zaretskii, Eli
address@hidden MS-Windows with MINGW @tab Eli Zaretskii,
@EMAIL{eliz@@gnu.org,eliz at gnu dot org}.
address@hidden compiling @command{gawk} with EMX for OS/2
+The 32 bit EMX version of @command{gawk} works ``out of the box'' under OS/2.
+However, it is highly recommended to use GCC 2.95.3 for the compilation.
+In principle, it is possible to compile @command{gawk} the following way:
address@hidden Buening, Andreas
address@hidden OS/2 @tab Andreas Buening,
@EMAIL{andreas.buening@@nexgo.de,andreas dot buening at nexgo dot de}.
address@hidden
+$ @kbd{./configure}
+$ @kbd{make}
address@hidden example
address@hidden Rankin, Pat
address@hidden VMS @tab Pat Rankin, @EMAIL{r.pat.rankin@@gmail.com,r.pat.rankin
at gmail.com}
+This is not recommended, though. To get an OMF executable you should
+use the following commands at your @command{sh} prompt:
address@hidden Pitts, Dave
address@hidden z/OS (OS/390) @tab Dave Pitts, @EMAIL{dpitts@@cozx.com,dpitts at
cozx dot com}.
address@hidden multitable
address@hidden
+$ @kbd{CFLAGS="-O2 -Zomf -Zmt"}
+$ @kbd{export CFLAGS}
+$ @kbd{LDFLAGS="-s -Zcrtdll -Zlinker /exepack:2 -Zlinker /pm:vio -Zstack
0x6000"}
+$ @kbd{export LDFLAGS}
+$ @kbd{RANLIB="echo"}
+$ @kbd{export RANLIB}
+$ @kbd{./configure --prefix=c:/usr}
+$ @kbd{make AR=emxomfar}
address@hidden example
-If your bug is also reproducible under Unix, please send a copy of your
-report to the @EMAIL{bug-gawk@@gnu.org,bug-gawk at gnu dot org} email list as
well.
address@hidden ENDOFRANGE dbugg
address@hidden ENDOFRANGE tblgawb
+These are just suggestions for use with GCC 2.x. You may use any other set of
+(self-consistent) environment variables and compiler flags.
address@hidden Other Versions
address@hidden Other Freely Available @command{awk} Implementations
address@hidden STARTOFRANGE awkim
address@hidden @command{awk}, implementations
@ignore
-From: emory!amc.com!brennan (Michael Brennan)
-Subject: C++ comments in awk programs
-To: address@hidden (Arnold Robbins)
-Date: Wed, 4 Sep 1996 08:11:48 -0700 (PDT)
-
+To get an FHS-compliant file hierarchy it is recommended to use the additional
address@hidden options @option{--infodir=c:/usr/share/info},
@option{--mandir=c:/usr/share/man}
+and @option{--libexecdir=c:/usr/lib}.
@end ignore
address@hidden Brennan, Michael
address@hidden
address@hidden's kind of fun to put comments like this in your awk
address@hidden
-@ @ @ @ @ @ @code{// Do C++ comments work? answer: yes! of address@hidden
-Michael Brennan
address@hidden quotation
-
-There are a number of other freely available @command{awk} implementations.
-This @value{SECTION} briefly describes where to get them:
-
address@hidden @asis
address@hidden Kernighan, Brian
address@hidden source code, Brian Kernighan's @command{awk}
address@hidden @command{awk}, versions of, See Also Brian Kernighan's
@command{awk}
address@hidden extensions, Brian Kernighan's @command{awk}
address@hidden Brian Kernighan's @command{awk}, extensions
address@hidden Unix @command{awk}
-Brian Kernighan, one of the original designers of Unix @command{awk},
-has made his implementation of
address@hidden freely available.
-You can retrieve this version via the World Wide Web from
address@hidden://www.cs.princeton.edu/~bwk, his home page}.
-It is available in several archive formats:
-
address@hidden @asis
address@hidden Shell archive
address@hidden://www.cs.princeton.edu/~bwk/btl.mirror/awk.shar}
-
address@hidden Compressed @command{tar} file
address@hidden://www.cs.princeton.edu/~bwk/btl.mirror/awk.tar.gz}
-
address@hidden Zip file
address@hidden://www.cs.princeton.edu/~bwk/btl.mirror/awk.zip}
address@hidden table
-
-This version requires an ISO C (1990 standard) compiler;
-the C compiler from
-GCC (the GNU Compiler Collection)
-works quite nicely.
-
address@hidden Extensions},
-for a list of extensions in this @command{awk} that are not in POSIX
@command{awk}.
-
address@hidden Brennan, Michael
address@hidden @command{mawk} program
address@hidden source code, @command{mawk}
address@hidden @command{mawk}
-Michael Brennan wrote an independent implementation of @command{awk},
-called @command{mawk}. It is available under the GPL
-(@pxref{Copying}),
-just as @command{gawk} is.
-
-The original distribution site for the @command{mawk} source code
-no longer has it. A copy is available at
address@hidden://www.skeeve.com/gawk/mawk1.3.3.tar.gz}.
-
-In 2009, Thomas Dickey took on @command{mawk} maintenance.
-Basic information is available on
address@hidden://www.invisible-island.net/mawk/mawk.html, the project's web
page}.
-The download URL is
address@hidden://invisible-island.net/datafiles/release/mawk.tar.gz}.
-
-Once you have it,
address@hidden may be used to decompress this file. Installation
-is similar to @command{gawk}'s
-(@pxref{Unix Installation}).
address@hidden Extensions},
-for a list of extensions in @command{mawk} that are not in POSIX @command{awk}.
address@hidden
+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}).
address@hidden ignore
address@hidden Sumner, Andrew
address@hidden @command{awka} compiler for @command{awk}
address@hidden source code, @command{awka}
address@hidden @command{awka}
-Written by Andrew Sumner,
address@hidden translates @command{awk} programs into C, compiles them,
-and links them with a library of functions that provides the core
address@hidden functionality.
-It also has a number of extensions.
+If you use GCC 2.95 it is recommended to use also:
-The @command{awk} translator is released under the GPL, and the library
-is under the LGPL.
address@hidden
+$ @kbd{LIBS="-lgcc"}
+$ @kbd{export LIBS}
address@hidden example
-To get @command{awka}, go to @url{http://sourceforge.net/projects/awka}.
address@hidden You can reach Andrew Sumner at @email{andrew@@zbcom.net}.
address@hidden andrewsumner@@yahoo.net
+You can also get an @code{a.out} executable if you prefer:
-The project seems to be frozen; no new code changes have been made
-since approximately 2003.
address@hidden
+$ @kbd{CFLAGS="-O2 -Zmt"}
+$ @kbd{export CFLAGS}
+$ @kbd{LDFLAGS="-s -Zstack 0x6000"}
+$ @kbd{LIBS="-lgcc"}
+$ @kbd{unset RANLIB}
address@hidden $ ./configure --prefix=c:/usr --without-included-gettext
+$ @kbd{./configure --prefix=c:/usr}
+$ @kbd{make}
address@hidden example
address@hidden Beebe, Nelson
address@hidden @command{pawk} (profiling version of Brian Kernighan's
@command{awk})
address@hidden source code, @command{pawk}
address@hidden @command{pawk}
-Nelson H.F.@: Beebe at the University of Utah has modified
-Brian Kernighan's @command{awk} to provide timing and profiling information.
-It is different from @command{gawk} with the @option{--profile} option.
-(@pxref{Profiling}),
-in that it uses CPU-based profiling, not line-count
-profiling. You may find it at either
address@hidden://ftp.math.utah.edu/pub/pawk/pawk-20030606.tar.gz}
-or
address@hidden://www.math.utah.edu/pub/pawk/pawk-20030606.tar.gz}.
address@hidden NOTE
+Compilation of @code{a.out} executables also works with GCC 3.2.
+Versions later than GCC 3.2 have not been tested successfully.
address@hidden quotation
address@hidden Busybox Awk
address@hidden Busybox Awk
address@hidden source code, Busybox Awk
-Busybox is a GPL-licensed program providing small versions of many
-applications within a single executable. It is aimed at embedded systems.
-It includes a full implementation of POSIX @command{awk}. When building
-it, be careful not to do @samp{make install} as it will overwrite
-copies of other applications in your @file{/usr/local/bin}. For more
-information, see the @uref{http://busybox.net, project's home page}.
address@hidden install} works as expected with the EMX build.
address@hidden OpenSolaris
address@hidden Solaris, POSIX-compliant @command{awk}
address@hidden source code, Solaris @command{awk}
address@hidden The OpenSolaris POSIX @command{awk}
-The version of @command{awk} in @file{/usr/xpg4/bin} on Solaris is
-more-or-less
-POSIX-compliant. It is based on the @command{awk} from Mortice Kern
-Systems for PCs. The source code can be downloaded from
-the @uref{http://www.opensolaris.org, OpenSolaris web site}.
-This author was able to make it compile and work under GNU/Linux
-with 1--2 hours of work. Making it more generally portable (using
-GNU Autoconf and/or Automake) would take more work, and this
-has not been done, at least to our knowledge.
address@hidden NOTE
+Ancient OS/2 ports of GNU @command{make} are not able to handle
+the Makefiles of this package. If you encounter any problems with
address@hidden, try GNU Make 3.79.1 or later versions. You should
+find the latest version on
address@hidden://hobbes.nmsu.edu/pub/os2/}.
address@hidden quotation
address@hidden @command{jawk}
address@hidden Java implementation of @command{awk}
address@hidden source code, @command{jawk}
address@hidden @command{jawk}
-This is an interpreter for @command{awk} written in Java. It claims
-to be a full interpreter, although because it uses Java facilities
-for I/O and for regexp matching, the language it supports is different
-from POSIX @command{awk}. More information is available on the
address@hidden://jawk.sourceforge.net, project's home page}.
address@hidden PC Testing
address@hidden Testing @command{gawk} on PC Operating Systems
address@hidden Libmawk
address@hidden libmawk
address@hidden source code, libmawk
-This is an embeddable @command{awk} interpreter derived from
address@hidden For more information see
address@hidden://repo.hu/projects/libmawk/}.
+Using @command{make} to run the standard tests and to install @command{gawk}
+requires additional Unix-like tools, including @command{sh}, @command{sed}, and
address@hidden In order to run the tests, the @file{test/*.ok} files may need to
+be converted so that they have the usual MS-DOS-style end-of-line markers.
+Alternatively, run @command{make check CMP="diff -a"} to use GNU @command{diff}
+in text mode instead of @command{cmp} to compare the resulting files.
address@hidden @w{QSE Awk}
address@hidden QSE Awk
address@hidden source code, QSE Awk
-This is an embeddable @command{awk} interpreter. For more information
-see @uref{http://code.google.com/p/qse/} and @uref{http://awk.info/?tools/qse}.
+Most
+of the tests work properly with Stewartson's shell along with the
+companion utilities or appropriate GNU utilities. However, some editing of
address@hidden/Makefile} is required. It is recommended that you copy the file
address@hidden/Makefile.tst} over the file @file{test/Makefile} as a
+replacement. Details can be found in @file{README_d/README.pc}
+and in the file @file{pc/Makefile.tst}.
address@hidden @command{QTawk}
address@hidden QuikTrim Awk
address@hidden source code, QuikTrim Awk
-This is an independent implementation of @command{awk} distributed
-under the GPL. It has a large number of extensions over standard
address@hidden and may not be 100% syntactically compatible with it.
-See @uref{http://www.quiktrim.org/QTawk.html} for more information,
-including the manual and a download link.
+On OS/2 the @code{pid} test fails because @code{spawnl()} is used instead of
address@hidden()}/@code{execl()} to start child processes.
+Also the @code{mbfw1} and @code{mbprintf1} tests fail because the needed
+multibyte functionality is not available.
address@hidden @command{xgawk}
address@hidden @command{xgawk}
address@hidden source code, @command{xgawk}
-XML @command{gawk}.
-This is a fork of the @command{gawk} 3.1.6 source base
-to support processing XML files. It has a number of
-interesting extensions which should one day be integrated
-into the main @command{gawk} code base.
-For more information, see
address@hidden://xmlgawk.sourceforge.net, the XMLgawk project web site}.
address@hidden table
address@hidden ENDOFRANGE gligawk
address@hidden ENDOFRANGE ingawk
address@hidden ENDOFRANGE awkim
address@hidden PC Using
address@hidden Using @command{gawk} on PC Operating Systems
address@hidden STARTOFRANGE opgawx
address@hidden operating systems, PC, @command{gawk} on
address@hidden STARTOFRANGE pcgawon
address@hidden PC operating systems, @command{gawk} on
address@hidden Notes
address@hidden Implementation Notes
address@hidden STARTOFRANGE gawii
address@hidden @command{gawk}, implementation issues
address@hidden STARTOFRANGE impis
address@hidden implementation issues, @command{gawk}
+With the exception of the Cygwin environment,
+the @samp{|&} operator and TCP/IP networking
+(@pxref{TCP/IP Networking})
+are not supported for MS-DOS or MS-Windows. EMX (OS/2 only) does support
+at least the @samp{|&} operator.
-This appendix contains information mainly of interest to implementers and
-maintainers of @command{gawk}. Everything in it applies specifically to
address@hidden and not to other implementations.
address@hidden search paths
address@hidden search paths, for source files
address@hidden @command{gawk}, OS/2 version of
address@hidden @command{gawk}, MS-DOS version of
address@hidden @command{gawk}, MS-Windows version of
address@hidden @code{;} (semicolon), @code{AWKPATH} variable and
address@hidden semicolon (@code{;}), @code{AWKPATH} variable and
address@hidden @code{AWKPATH} environment variable
+The MS-DOS and MS-Windows versions of @command{gawk} search for
+program files as described in @ref{AWKPATH Variable}. However,
+semicolons (rather than colons) separate elements in the @env{AWKPATH}
+variable. If @env{AWKPATH} is not set or is empty, then the default
+search path for MS-Windows and MS-DOS versions is
address@hidden@w{".;c:/lib/awk;c:/gnu/lib/awk"}}.
address@hidden
-* Compatibility Mode:: How to disable certain @command{gawk}
- extensions.
-* Additions:: Making Additions To @command{gawk}.
-* Dynamic Extensions:: Adding new built-in functions to
- @command{gawk}.
-* Future Extensions:: New features that may be implemented one day.
address@hidden menu
address@hidden @code{UNIXROOT} variable, on OS/2 systems
+The search path for OS/2 (32 bit, EMX) is determined by the prefix directory
+(most likely @file{/usr} or @file{c:/usr}) that has been specified as an
option of
+the @command{configure} script like it is the case for the Unix versions.
+If @file{c:/usr} is the prefix directory then the default search path contains
@file{.}
+and @file{c:/usr/share/awk}.
+Additionally, to support binary distributions of @command{gawk} for OS/2
+systems whose drive @samp{c:} might not support long file names or might not
exist
+at all, there is a special environment variable. If @env{UNIXROOT} specifies
+a drive then this specific drive is also searched for program files.
+E.g., if @env{UNIXROOT} is set to @file{e:} the complete default search path is
address@hidden@w{".;c:/usr/share/awk;e:/usr/share/awk"}}.
address@hidden Compatibility Mode
address@hidden Downward Compatibility and Debugging
address@hidden @command{gawk}, implementation issues, downward compatibility
address@hidden @command{gawk}, implementation issues, debugging
address@hidden troubleshooting, @command{gawk}
address@hidden implementation address@hidden @command{gawk}, debugging
+An @command{sh}-like shell (as opposed to @command{command.com} under MS-DOS
+or @command{cmd.exe} under MS-Windows or OS/2) may be useful for @command{awk}
programming.
+The DJGPP collection of tools includes an MS-DOS port of Bash,
+and several shells are available for OS/2, including @command{ksh}.
address@hidden/GNU},
-for a summary of the GNU extensions to the @command{awk} language and program.
-All of these features can be turned off by invoking @command{gawk} with the
address@hidden option or with the @option{--posix} option.
address@hidden common extensions, @code{BINMODE} variable
address@hidden extensions, address@hidden @code{BINMODE} variable
address@hidden differences in @command{awk} and @command{gawk}, @code{BINMODE}
variable
address@hidden @code{BINMODE} variable
+Under MS-Windows, OS/2 and MS-DOS, @command{gawk} (and many other text
programs) silently
+translate end-of-line @code{"\r\n"} to @code{"\n"} on input and @code{"\n"}
+to @code{"\r\n"} on output. A special @code{BINMODE} variable
@value{COMMONEXT}
+allows control over these translations and is interpreted as follows:
-If @command{gawk} is compiled for debugging with @samp{-DDEBUG}, then there
-is one more option available on the command line:
address@hidden @bullet
address@hidden
+If @code{BINMODE} is @code{"r"}, or one,
+then
+binary mode is set on read (i.e., no translations on reads).
address@hidden @code
address@hidden -Y
address@hidden --parsedebug
-Prints out the parse stack information as the program is being parsed.
address@hidden table
address@hidden
+If @code{BINMODE} is @code{"w"}, or two,
+then
+binary mode is set on write (i.e., no translations on writes).
-This option is intended only for serious @command{gawk} developers
-and not for the casual user. It probably has not even been compiled into
-your version of @command{gawk}, since it slows down execution.
address@hidden
+If @code{BINMODE} is @code{"rw"} or @code{"wr"} or three,
+binary mode is set for both read and write.
address@hidden Additions
address@hidden Making Additions to @command{gawk}
address@hidden
address@hidden@var{non-null-string}} is
+the same as @samp{BINMODE=3} (i.e., no translations on
+reads or writes). However, @command{gawk} issues a warning
+message if the string is not one of @code{"rw"} or @code{"wr"}.
address@hidden itemize
-If you find that you want to enhance @command{gawk} in a significant
-fashion, you are perfectly free to do so. That is the point of having
-free software; the source code is available and you are free to change
-it as you want (@pxref{Copying}).
address@hidden
+The modes for standard input and standard output are set one time
+only (after the
+command line is read, but before processing any of the @command{awk} program).
+Setting @code{BINMODE} for standard input or
+standard output is accomplished by using an
+appropriate @samp{-v address@hidden option on the command line.
address@hidden is set at the time a file or pipe is opened and cannot be
+changed mid-stream.
-This @value{SECTION} discusses the ways you might want to change @command{gawk}
-as well as any considerations you should bear in mind.
+The name @code{BINMODE} was chosen to match @command{mawk}
+(@pxref{Other Versions}).
address@hidden and @command{gawk} handle @code{BINMODE} similarly; however,
address@hidden adds a @samp{-W address@hidden option and an environment
+variable that can set @code{BINMODE}, @code{RS}, and @code{ORS}. The
+files @file{binmode[1-3].awk} (under @file{gnu/lib/awk} in some of the
+prepared distributions) have been chosen to match @command{mawk}'s @samp{-W
address@hidden option. These can be changed or discarded; in particular,
+the setting of @code{RS} giving the fewest ``surprises'' is open to debate.
address@hidden uses @samp{RS = "\r\n"} if binary mode is set on read, which is
+appropriate for files with the MS-DOS-style end-of-line.
address@hidden
-* Accessing The Source:: Accessing the Git repository.
-* Adding Code:: Adding code to the main body of
- @command{gawk}.
-* New Ports:: Porting @command{gawk} to a new operating
- system.
address@hidden menu
+To illustrate, the following examples set binary mode on writes for standard
+output and other files, and set @code{ORS} as the ``usual'' MS-DOS-style
+end-of-line:
address@hidden Accessing The Source
address@hidden Accessing The @command{gawk} Git Repository
address@hidden
+gawk -v BINMODE=2 -v ORS="\r\n" @dots{}
address@hidden example
-As @command{gawk} is Free Software, the source code is always available.
address@hidden Distribution}, describes how to get and build the formal,
-released versions of @command{gawk}.
address@hidden
+or:
-However, if you want to modify @command{gawk} and contribute back your
-changes, you will probably wish to work with the development version.
-To do so, you will need to access the @command{gawk} source code
-repository. The code is maintained using the
address@hidden://git-scm.com/, Git distributed version control system}.
-You will need to install it if your system doesn't have it.
-Once you have done so, use the command:
address@hidden
+gawk -v BINMODE=w -f binmode2.awk @dots{}
address@hidden example
+
address@hidden
+These give the same result as the @samp{-W BINMODE=2} option in
address@hidden
+The following changes the record separator to @code{"\r\n"} and sets binary
+mode on reads, but does not affect the mode on standard input:
@example
-git clone git://git.savannah.gnu.org/gawk.git
+gawk -v RS="\r\n" --source "BEGIN @{ BINMODE = 1 @}" @dots{}
@end example
@noindent
-This will clone the @command{gawk} repository. If you are behind a
-firewall that will not allow you to use the Git native protocol, you
-can still access the repository using:
+or:
@example
-git clone http://git.savannah.gnu.org/r/gawk.git
+gawk -f binmode1.awk @dots{}
@end example
-Once you have made changes, you can use @samp{git diff} to produce a
-patch, and send that to the @command{gawk} maintainer; see @ref{Bugs}
-for how to do that.
address@hidden
+With proper quoting, in the first example the setting of @code{RS} can be
+moved into the @code{BEGIN} rule.
-Finally, if you cannot install Git (e.g., if it hasn't been ported
-yet to your operating system), you can use the Git--CVS gateway
-to check out a copy using CVS, as follows:
address@hidden Cygwin
address@hidden Using @command{gawk} In The Cygwin Environment
address@hidden compiling @command{gawk} for Cygwin
+
address@hidden can be built and used ``out of the box'' under MS-Windows
+if you are using the @uref{http://www.cygwin.com, Cygwin environment}.
+This environment provides an excellent simulation of Unix, using the
+GNU tools, such as Bash, the GNU Compiler Collection (GCC), GNU Make,
+and other GNU programs. Compilation and installation for Cygwin is the
+same as for a Unix system:
@example
-cvs -d:pserver:anonymous@@pserver.git.sv.gnu.org:/gawk.git co -d gawk master
+tar -xvpzf address@hidden@value{PATCHLEVEL}.tar.gz
+cd address@hidden@value{PATCHLEVEL}
+./configure
+make
@end example
address@hidden Adding Code
address@hidden Adding New Features
+When compared to GNU/Linux on the same system, the @samp{configure}
+step on Cygwin takes considerably longer. However, it does finish,
+and then the @samp{make} proceeds as usual.
address@hidden STARTOFRANGE adfgaw
address@hidden adding, features to @command{gawk}
address@hidden STARTOFRANGE fadgaw
address@hidden features, adding to @command{gawk}
address@hidden STARTOFRANGE gawadf
address@hidden @command{gawk}, features, adding
-You are free to add any new features you like to @command{gawk}.
-However, if you want your changes to be incorporated into the @command{gawk}
-distribution, there are several steps that you need to take in order to
-make it possible to include your changes:
address@hidden NOTE
+The @samp{|&} operator and TCP/IP networking
+(@pxref{TCP/IP Networking})
+are fully supported in the Cygwin environment. This is not true
+for any other environment on MS-Windows.
address@hidden quotation
address@hidden 1
address@hidden
-Before building the new feature into @command{gawk} itself,
-consider writing it as an extension module
-(@pxref{Dynamic Extensions}).
-If that's not possible, continue with the rest of the steps in this list.
address@hidden MSYS
address@hidden Using @command{gawk} In The MSYS Environment
address@hidden
-Be prepared to sign the appropriate paperwork.
-In order for the FSF to distribute your changes, you must either place
-those changes in the public domain and submit a signed statement to that
-effect, or assign the copyright in your changes to the FSF.
-Both of these actions are easy to do and @emph{many} people have done so
-already. If you have questions, please contact me
-(@pxref{Bugs}),
-or @EMAIL{assign@@gnu.org,assign at gnu dot org}.
+In the MSYS environment under MS-Windows, @command{gawk} automatically
+uses binary mode for reading and writing files. Thus there is no
+need to use the @code{BINMODE} variable.
address@hidden
-Get the latest version.
-It is much easier for me to integrate changes if they are relative to
-the most recent distributed version of @command{gawk}. If your version of
address@hidden is very old, I may not be able to integrate them at all.
-(@xref{Getting},
-for information on getting the latest version of @command{gawk}.)
+This can cause problems with other Unix-like components that have
+been ported to MS-Windows that expect @command{gawk} to do automatic
+translation of @code{"\r\n"}, since it won't. Caveat Emptor!
address@hidden
address@hidden
-Follow the @cite{GNU Coding Standards}.
address@hidden ifnotinfo
address@hidden
-See @inforef{Top, , Version, standards, GNU Coding Standards}.
address@hidden ifinfo
-This document describes how GNU software should be written. If you haven't
-read it, please do so, preferably @emph{before} starting to modify
@command{gawk}.
-(The @cite{GNU Coding Standards} are available from
-the GNU Project's
address@hidden://www.gnu.org/prep/standards_toc.html, web site}.
-Texinfo, Info, and DVI versions are also available.)
address@hidden VMS Installation
address@hidden How to Compile and Install @command{gawk} on VMS
+
address@hidden based on material from Pat Rankin <address@hidden>
address@hidden now address@hidden
address@hidden now address@hidden
+
address@hidden @command{gawk}, VMS version of
address@hidden installation, VMS
+This @value{SUBSECTION} describes how to compile and install @command{gawk}
under VMS.
+The older designation ``VMS'' is used throughout to refer to OpenVMS.
address@hidden @command{gawk}, coding style in
address@hidden
-Use the @command{gawk} coding style.
-The C code for @command{gawk} follows the instructions in the
address@hidden Coding Standards}, with minor exceptions. The code is formatted
-using the traditional ``K&R'' style, particularly as regards to the placement
-of braces and the use of TABs. In brief, the coding rules for @command{gawk}
-are as follows:
address@hidden
+* VMS Compilation:: How to compile @command{gawk} under VMS.
+* VMS Installation Details:: How to install @command{gawk} under VMS.
+* VMS Running:: How to run @command{gawk} under VMS.
+* VMS Old Gawk:: An old version comes with some VMS systems.
address@hidden menu
address@hidden @bullet
address@hidden
-Use ANSI/ISO style (prototype) function headers when defining functions.
address@hidden VMS Compilation
address@hidden Compiling @command{gawk} on VMS
address@hidden compiling @command{gawk} for VMS
address@hidden
-Put the name of the function at the beginning of its own line.
+To compile @command{gawk} under VMS, there is a @code{DCL} command procedure
that
+issues all the necessary @code{CC} and @code{LINK} commands. There is
+also a @file{Makefile} for use with the @code{MMS} utility. From the source
+directory, use either:
address@hidden
-Put the return type of the function, even if it is @code{int}, on the
-line above the line with the name and arguments of the function.
address@hidden
+$ @kbd{@@[.VMS]VMSBUILD.COM}
address@hidden example
address@hidden
-Put spaces around parentheses used in control structures
-(@code{if}, @code{while}, @code{for}, @code{do}, @code{switch},
-and @code{return}).
address@hidden
+or:
address@hidden
-Do not put spaces in front of parentheses used in function calls.
address@hidden
+$ @kbd{MMS/DESCRIPTION=[.VMS]DESCRIP.MMS GAWK}
address@hidden example
address@hidden
-Put spaces around all C operators and after commas in function calls.
+Older versions of @command{gawk} could be built with VAX C or
+GNU C on VAX/VMS, as well as with DEC C, but that is no longer
+supported. DEC C (also briefly known as ``Compaq C'' and now known
+as ``HP C,'' but referred to here as ``DEC C'') is required. Both
address@hidden and @code{DESCRIP.MMS} contain some obsolete support
+for the older compilers but are set up to use DEC C by default.
address@hidden
-Do not use the comma operator to produce multiple side effects, except
-in @code{for} loop initialization and increment parts, and in macro bodies.
address@hidden has been tested under Alpha/VMS 7.3-1 using Compaq C V6.4,
+and on Alpha/VMS 7.3, Alpha/VMS 7.3-2, and IA64/VMS address@hidden IA64
+architecture is also known as ``Itanium.''}
address@hidden
-Use real TABs for indenting, not spaces.
address@hidden VMS Installation Details
address@hidden Installing @command{gawk} on VMS
address@hidden
-Use the ``K&R'' brace layout style.
+To install @command{gawk}, all you need is a ``foreign'' command, which is
+a @code{DCL} symbol whose value begins with a dollar sign. For example:
address@hidden
-Use comparisons against @code{NULL} and @code{'\0'} in the conditions of
address@hidden, @code{while}, and @code{for} statements, as well as in the
@code{case}s
-of @code{switch} statements, instead of just the
-plain pointer or character value.
address@hidden
+$ @kbd{GAWK :== $disk1:[gnubin]GAWK}
address@hidden example
address@hidden
-Use the @code{TRUE}, @code{FALSE} and @code{NULL} symbolic constants
-and the character constant @code{'\0'} where appropriate, instead of @code{1}
-and @code{0}.
address@hidden
+Substitute the actual location of @command{gawk.exe} for
address@hidden:[gnubin]}. The symbol should be placed in the
address@hidden of any user who wants to run @command{gawk},
+so that it is defined every time the user logs on.
+Alternatively, the symbol may be placed in the system-wide
address@hidden procedure, which allows all users
+to run @command{gawk}.
address@hidden
-Provide one-line descriptive comments for each function.
+Optionally, the help entry can be loaded into a VMS help library:
address@hidden
-Do not use the @code{alloca()} function for allocating memory off the
-stack. Its use causes more portability trouble than is worth the minor
-benefit of not having to free the storage. Instead, use @code{malloc()}
-and @code{free()}.
address@hidden
+$ @kbd{LIBRARY/HELP SYS$HELP:HELPLIB [.VMS]GAWK.HLP}
address@hidden example
address@hidden
-Do not use comparisons of the form @samp{! strcmp(a, b)} or similar.
-As Henry Spencer once said, address@hidden()} is not a boolean!''
-Instead, use @samp{strcmp(a, b) == 0}.
address@hidden
+(You may want to substitute a site-specific help library rather than
+the standard VMS library @samp{HELPLIB}.) After loading the help text,
+the command:
address@hidden
-If adding new bit flag values, use explicit hexadecimal constants
-(@code{0x001}, @code{0x002}, @code{0x004}, and son on) instead of
-shifting one left by successive amounts (@samp{(1<<0)}, @samp{(1<<1)},
-and so on).
address@hidden itemize
address@hidden
+$ @kbd{HELP GAWK}
address@hidden example
address@hidden NOTE
-If I have to reformat your code to follow the coding style used in
address@hidden, I may not bother to integrate your changes at all.
address@hidden quotation
address@hidden
+provides information about both the @command{gawk} implementation and the
address@hidden programming language.
address@hidden Texinfo
address@hidden
-Update the documentation.
-Along with your new code, please supply new sections and/or chapters
-for this @value{DOCUMENT}. If at all possible, please use real
-Texinfo, instead of just supplying unformatted ASCII text (although
-even that is better than no documentation at all).
-Conventions to be followed in @address@hidden are provided
-after the @samp{@@bye} at the end of the Texinfo source file.
-If possible, please update the @command{man} page as well.
+The logical name @samp{AWK_LIBRARY} can designate a default location
+for @command{awk} program files. For the @option{-f} option, if the specified
address@hidden has no device or directory path information in it, @command{gawk}
+looks in the current directory first, then in the directory specified
+by the translation of @samp{AWK_LIBRARY} if the file is not found.
+If, after searching in both directories, the file still is not found,
address@hidden appends the suffix @samp{.awk} to the filename and retries
+the file search. If @samp{AWK_LIBRARY} has no definition, a default value
+of @samp{SYS$LIBRARY:} is used for it.
-You will also have to sign paperwork for your documentation changes.
address@hidden VMS Running
address@hidden Running @command{gawk} on VMS
address@hidden
-Submit changes as unified diffs.
-Use @samp{diff -u -r -N} to compare
-the original @command{gawk} source tree with your version.
-I recommend using the GNU version of @command{diff}.
-Send the output produced by either run of @command{diff} to me when you
-submit your changes.
-(@xref{Bugs}, for the electronic mail
-information.)
+Command-line parsing and quoting conventions are significantly different
+on VMS, so examples in this @value{DOCUMENT} or from other sources often need
minor
+changes. They @emph{are} minor though, and all @command{awk} programs
+should run correctly.
-Using this format makes it easy for me to apply your changes to the
-master version of the @command{gawk} source code (using @code{patch}).
-If I have to apply the changes manually, using a text editor, I may
-not do so, particularly if there are lots of changes.
+Here are a couple of trivial tests:
address@hidden
-Include an entry for the @file{ChangeLog} file with your submission.
-This helps further minimize the amount of work I have to do,
-making it easier for me to accept patches.
address@hidden enumerate
address@hidden
+$ @kbd{gawk -- "BEGIN @{print ""Hello, World!""@}"}
+$ @kbd{gawk -"W" version}
+! could also be -"W version" or "-W version"
address@hidden example
-Although this sounds like a lot of work, please remember that while you
-may write the new code, I have to maintain it and support it. If it
-isn't possible for me to do that with a minimum of extra work, then I
-probably will not.
address@hidden ENDOFRANGE adfgaw
address@hidden ENDOFRANGE gawadf
address@hidden ENDOFRANGE fadgaw
address@hidden
+Note that uppercase and mixed-case text must be quoted.
address@hidden New Ports
address@hidden Porting @command{gawk} to a New Operating System
address@hidden portability, @command{gawk}
address@hidden operating systems, porting @command{gawk} to
+The VMS port of @command{gawk} includes a @code{DCL}-style interface in
addition
+to the original shell-style interface (see the help entry for details).
+One side effect of dual command-line parsing is that if there is only a
+single parameter (as in the quoted string program above), the command
+becomes ambiguous. To work around this, the normally optional @option{--}
+flag is required to force Unix-style parsing rather than @code{DCL} parsing.
If any
+other dash-type options (or multiple parameters such as @value{DF}s to
+process) are present, there is no ambiguity and @option{--} can be omitted.
address@hidden porting @command{gawk}
-If you want to port @command{gawk} to a new operating system, there are
-several steps:
address@hidden @cindex directory search
address@hidden @cindex path, search
address@hidden search paths
address@hidden search paths, for source files
+The default search path, when looking for @command{awk} program files specified
+by the @option{-f} option, is @code{"SYS$DISK:[],AWK_LIBRARY:"}. The logical
+name @env{AWKPATH} can be used to override this default. The format
+of @env{AWKPATH} is a comma-separated list of directory specifications.
+When defining it, the value should be quoted so that it retains a single
+translation and not a multitranslation @code{RMS} searchlist.
address@hidden 1
address@hidden
-Follow the guidelines in
address@hidden
address@hidden Code},
address@hidden ifinfo
address@hidden
-the previous @value{SECTION}
address@hidden ifnotinfo
-concerning coding style, submission of diffs, and so on.
address@hidden
address@hidden The VMS POSIX product, also known as POSIX for OpenVMS, is long
defunct
address@hidden and building gawk for it has not been tested in many years, but
these
address@hidden old instructions might still work if anyone is still using it.
address@hidden
-Be prepared to sign the appropriate paperwork.
-In order for the FSF to distribute your code, you must either place
-your code in the public domain and submit a signed statement to that
-effect, or assign the copyright in your code to the FSF.
address@hidden
-Both of these actions are easy to do and @emph{many} people have done so
-already. If you have questions, please contact me, or
address@hidden@@gnu.org}.
address@hidden ifinfo
address@hidden VMS POSIX
address@hidden Building and Using @command{gawk} on VMS POSIX
address@hidden
-When doing a port, bear in mind that your code must coexist peacefully
-with the rest of @command{gawk} and the other ports. Avoid gratuitous
-changes to the system-independent parts of the code. If at all possible,
-avoid sprinkling @samp{#ifdef}s just for your port throughout the
-code.
+Ignore the instructions above, although @file{vms/gawk.hlp} should still
+be made available in a help library. The source tree should be unpacked
+into a container file subsystem rather than into the ordinary VMS filesystem.
+Make sure that the two scripts, @file{configure} and
address@hidden/posix-cc.sh}, are executable; use @samp{chmod +x} on them if
+necessary. Then execute the following two commands:
-If the changes needed for a particular system affect too much of the
-code, I probably will not accept them. In such a case, you can, of course,
-distribute your changes on your own, as long as you comply
-with the GPL
-(@pxref{Copying}).
address@hidden
+psx> @kbd{CC=vms/posix-cc.sh configure}
+psx> @kbd{make CC=c89 gawk}
address@hidden example
+
address@hidden
+The first command constructs files @file{config.h} and @file{Makefile} out
+of templates, using a script to make the C compiler fit @command{configure}'s
+expectations. The second command compiles and links @command{gawk} using
+the C compiler directly; ignore any warnings from @command{make} about being
+unable to redefine @code{CC}. @command{configure} takes a very long
+time to execute, but at least it provides incremental feedback as it runs.
address@hidden
-A number of the files that come with @command{gawk} are maintained by other
-people. Thus, you should not change them
-unless it is for a very good reason; i.e., changes are not out of the
-question, but changes to these files are scrutinized extra carefully.
-The files are @file{dfa.c}, @file{dfa.h}, @file{getopt1.c}, @file{getopt.c},
address@hidden, @file{install-sh}, @file{mkinstalldirs}, @file{regcomp.c},
address@hidden, @file{regexec.c}, @file{regexex.c}, @file{regex.h},
address@hidden, and @file{regex_internal.h}.
+This has been tested with VAX/VMS V6.2, VMS POSIX V2.0, and DEC C V5.2.
address@hidden
-Be willing to continue to maintain the port.
-Non-Unix operating systems are supported by volunteers who maintain
-the code needed to compile and run @command{gawk} on their systems. If noone
-volunteers to maintain a port, it becomes unsupported and it may
-be necessary to remove it from the distribution.
+Once built, @command{gawk} works like any other shell utility. Unlike
+the normal VMS port of @command{gawk}, no special command-line manipulation is
+needed in the VMS POSIX environment.
address@hidden ignore
address@hidden
-Supply an appropriate @file{gawkmisc.???} file.
-Each port has its own @file{gawkmisc.???} that implements certain
-operating system specific functions. This is cleaner than a plethora of
address@hidden scattered throughout the code. The @file{gawkmisc.c} in
-the main source directory includes the appropriate
address@hidden file from each subdirectory.
-Be sure to update it as well.
address@hidden VMS Old Gawk
address@hidden Some VMS Systems Have An Old Version of @command{gawk}
-Each port's @file{gawkmisc.???} file has a suffix reminiscent of the machine
-or operating system for the port---for example, @file{pc/gawkmisc.pc} and
address@hidden/gawkmisc.vms}. The use of separate suffixes, instead of plain
address@hidden, makes it possible to move files from a port's subdirectory
-into the main subdirectory, without accidentally destroying the real
address@hidden file. (Currently, this is only an issue for the
-PC operating system ports.)
address@hidden Thanks to "gerard labadie" <address@hidden>
address@hidden
-Supply a @file{Makefile} as well as any other C source and header files that
are
-necessary for your operating system. All your code should be in a
-separate subdirectory, with a name that is the same as, or reminiscent
-of, either your operating system or the computer system. If possible,
-try to structure things so that it is not necessary to move files out
-of the subdirectory into the main source directory. If that is not
-possible, then be sure to avoid using names for your files that
-duplicate the names of files in the main source directory.
+Some versions of VMS have an old version of @command{gawk}. To access it,
+define a symbol, as follows:
address@hidden
-Update the documentation.
-Please write a section (or sections) for this @value{DOCUMENT} describing the
-installation and compilation steps needed to compile and/or install
address@hidden for your system.
address@hidden enumerate
address@hidden
+$ @kbd{gawk :== $sys$common:[syshlp.examples.tcpip.snmp]gawk.exe}
address@hidden example
-Following these steps makes it much easier to integrate your changes
-into @command{gawk} and have them coexist happily with other
-operating systems' code that is already there.
+This is apparently @value{PVERSION} 2.15.6, which is extremely old. We
+recommend compiling and using the current version.
-In the code that you supply and maintain, feel free to use a
-coding style and brace layout that suits your taste.
address@hidden ENDOFRANGE opgawx
address@hidden ENDOFRANGE pcgawon
address@hidden Dynamic Extensions
address@hidden Adding New Built-in Functions to @command{gawk}
address@hidden Robinson, Will
address@hidden robot, the
address@hidden Lost In Space
address@hidden Bugs
address@hidden Reporting Problems and Bugs
address@hidden archeologists
@quotation
address@hidden Will Robinson! address@hidden
-Warning! address@hidden
-The Robot
address@hidden is nothing more dangerous than a bored address@hidden
+The Hitchhiker's Guide to the Galaxy
@end quotation
address@hidden the radio show, not the book. :-)
address@hidden STARTOFRANGE gladfgaw
address@hidden @command{gawk}, functions, adding
address@hidden STARTOFRANGE adfugaw
address@hidden adding, functions to @command{gawk}
address@hidden STARTOFRANGE fubadgaw
address@hidden functions, built-in, adding to @command{gawk}
-It is possible to add new built-in
-functions to @command{gawk} using dynamically loaded libraries. This
-facility is available on systems (such as GNU/Linux) that support
-the C @code{dlopen()} and @code{dlsym()} functions.
-This @value{SECTION} describes how to write and use dynamically
-loaded extensions for @command{gawk}.
-Experience with programming in
-C or C++ is necessary when reading this @value{SECTION}.
address@hidden STARTOFRANGE dbugg
address@hidden debugging @command{gawk}, bug reports
address@hidden STARTOFRANGE tblgawb
address@hidden troubleshooting, @command{gawk}, bug reports
+If you have problems with @command{gawk} or think that you have found a bug,
+please report it to the developers; we cannot promise to do anything
+but we might well want to fix it.
address@hidden CAUTION
-The facilities described in this @value{SECTION}
-are very much subject to change in a future @command{gawk} release.
-Be aware that you may have to re-do everything,
-at some future time.
-
-If you have written your own dynamic extensions,
-be sure to recompile them for each new @command{gawk} release.
-There is no guarantee of binary compatibility between different
-releases, nor will there ever be such a guarantee.
address@hidden quotation
+Before reporting a bug, make sure you have actually found a real bug.
+Carefully reread the documentation and see if it really says you can do
+what you're trying to do. If it's not clear whether you should be able
+to do something or not, report that too; it's a bug in the documentation!
address@hidden NOTE
-When @option{--sandbox} is specified, extensions are disabled
-(@pxref{Options}.
address@hidden quotation
+Before reporting a bug or trying to fix it yourself, try to isolate it
+to the smallest possible @command{awk} program and input @value{DF} that
+reproduces the problem. Then send us the program and @value{DF},
+some idea of what kind of Unix system you're using,
+the compiler you used to compile @command{gawk}, and the exact results
address@hidden gave you. Also say what you expected to occur; this helps
+us decide whether the problem is really in the documentation.
address@hidden
-* Internals:: A brief look at some @command{gawk} internals.
-* Plugin License:: A note about licensing.
-* Loading Extensions:: How to load dynamic extensions.
-* Sample Library:: A example of new functions.
address@hidden menu
+Please include the version number of @command{gawk} you are using.
+You can get this information with the command @samp{gawk --version}.
address@hidden Internals
address@hidden A Minimal Introduction to @command{gawk} Internals
address@hidden STARTOFRANGE gawint
address@hidden @command{gawk}, internals
-
-The truth is that @command{gawk} was not designed for simple extensibility.
-The facilities for adding functions using shared libraries work, but
-are something of a ``bag on the side.'' Thus, this tour is
-brief and simplistic; would-be @command{gawk} hackers are encouraged to
-spend some time reading the source code before trying to write
-extensions based on the material presented here. Of particular note
-are the files @file{awk.h}, @file{builtin.c}, and @file{eval.c}.
-Reading @file{awkgram.y} in order to see how the parse tree is built
-would also be of use.
-
address@hidden @code{awk.h} file (internal)
-With the disclaimers out of the way, the following types, structure
-members, functions, and macros are declared in @file{awk.h} and are of
-use when writing extensions. The next @value{SECTION}
-shows how they are used:
address@hidden @code{bug-gawk@@gnu.org} bug reporting address
address@hidden email address for bug reports, @code{bug-gawk@@gnu.org}
address@hidden bug reports, email address, @code{bug-gawk@@gnu.org}
+Once you have a precise problem, send email to
address@hidden@@gnu.org,bug-gawk at gnu dot org}.
address@hidden @code
address@hidden floating-point, numbers, @code{AWKNUM} internal type
address@hidden numbers, floating-point, @code{AWKNUM} internal type
address@hidden @code{AWKNUM} internal type
address@hidden internal type, @code{AWKNUM}
address@hidden AWKNUM
-An @code{AWKNUM} is the internal type of @command{awk}
-floating-point numbers. Typically, it is a C @code{double}.
-
address@hidden @code{NODE} internal type
address@hidden internal type, @code{NODE}
address@hidden strings, @code{NODE} internal type
address@hidden numbers, @code{NODE} internal type
address@hidden NODE
-Just about everything is done using objects of type @code{NODE}.
-These contain both strings and numbers, as well as variables and arrays.
-
address@hidden @code{force_number()} internal function
address@hidden internal function, @code{force_number()}
address@hidden numeric, values
address@hidden AWKNUM force_number(NODE *n)
-This macro forces a value to be numeric. It returns the actual
-numeric value contained in the node.
-It may end up calling an internal @command{gawk} function.
-
address@hidden @code{force_string()} internal function
address@hidden internal function, @code{force_string()}
address@hidden void force_string(NODE *n)
-This macro guarantees that a @code{NODE}'s string value is current.
-It may end up calling an internal @command{gawk} function.
-It also guarantees that the string is zero-terminated.
-
address@hidden @code{force_wstring()} internal function
address@hidden internal function, @code{force_wstring()}
address@hidden void force_wstring(NODE *n)
-Similarly, this
-macro guarantees that a @code{NODE}'s wide-string value is current.
-It may end up calling an internal @command{gawk} function.
-It also guarantees that the wide string is zero-terminated.
-
address@hidden address@hidden number of
address@hidden @code{nargs} internal variable
address@hidden internal variable, @code{nargs}
address@hidden nargs
-Inside an extension function, this is the actual number of
-parameters passed to the current function.
-
address@hidden @code{stptr} internal variable
address@hidden internal variable, @code{stptr}
address@hidden @code{stlen} internal variable
address@hidden internal variable, @code{stlen}
address@hidden n->stptr
address@hidden n->stlen
-The data and length of a @code{NODE}'s string value, respectively.
-The string is @emph{not} guaranteed to be zero-terminated.
-If you need to pass the string value to a C library function, save
-the value in @code{n->stptr[n->stlen]}, assign @code{'\0'} to it,
-call the routine, and then restore the value.
-
address@hidden @code{wstptr} internal variable
address@hidden internal variable, @code{wstptr}
address@hidden @code{wstlen} internal variable
address@hidden internal variable, @code{wstlen}
address@hidden n->wstptr
address@hidden n->wstlen
-The data and length of a @code{NODE}'s wide-string value, respectively.
-Use @code{force_wstring()} to make sure these values are current.
-
address@hidden @code{type} internal variable
address@hidden internal variable, @code{type}
address@hidden n->type
-The type of the @code{NODE}. This is a C @code{enum}. Values should
-be one of @code{Node_var}, @code{Node_var_new}, or @code{Node_var_array}
-for function parameters.
-
address@hidden @code{vname} internal variable
address@hidden internal variable, @code{vname}
address@hidden n->vname
-The ``variable name'' of a node. This is not of much use inside
-externally written extensions.
-
address@hidden arrays, associative, clearing
address@hidden @code{assoc_clear()} internal function
address@hidden internal function, @code{assoc_clear()}
address@hidden void assoc_clear(NODE *n)
-Clears the associative array pointed to by @code{n}.
-Make sure that @samp{n->type == Node_var_array} first.
-
address@hidden arrays, elements, installing
address@hidden @code{assoc_lookup()} internal function
address@hidden internal function, @code{assoc_lookup()}
address@hidden NODE **assoc_lookup(NODE *symbol, NODE *subs)
-Finds, and installs if necessary, array elements.
address@hidden is the array, @code{subs} is the subscript.
-This is usually a value created with @code{make_string()} (see below).
-
address@hidden strings
address@hidden @code{make_string()} internal function
address@hidden internal function, @code{make_string()}
address@hidden NODE *make_string(char *s, size_t len)
-Take a C string and turn it into a pointer to a @code{NODE} that
-can be stored appropriately. This is permanent storage; understanding
-of @command{gawk} memory management is helpful.
-
address@hidden numbers
address@hidden @code{make_number()} internal function
address@hidden internal function, @code{make_number()}
address@hidden NODE *make_number(AWKNUM val)
-Take an @code{AWKNUM} and turn it into a pointer to a @code{NODE} that
-can be stored appropriately. This is permanent storage; understanding
-of @command{gawk} memory management is helpful.
-
-
address@hidden address@hidden duplicating
address@hidden @code{dupnode()} internal function
address@hidden internal function, @code{dupnode()}
address@hidden NODE *dupnode(NODE *n)
-Duplicate a node. In most cases, this increments an internal
-reference count instead of actually duplicating the entire @code{NODE};
-understanding of @command{gawk} memory management is helpful.
-
address@hidden memory, releasing
address@hidden @code{unref()} internal function
address@hidden internal function, @code{unref()}
address@hidden void unref(NODE *n)
-This macro releases the memory associated with a @code{NODE}
-allocated with @code{make_string()} or @code{make_number()}.
-Understanding of @command{gawk} memory management is helpful.
-
address@hidden @code{make_builtin()} internal function
address@hidden internal function, @code{make_builtin()}
address@hidden void make_builtin(const char *name, NODE *(*func)(NODE *), int
count)
-Register a C function pointed to by @code{func} as new built-in
-function @code{name}. @code{name} is a regular C string. @code{count}
-is the maximum number of arguments that the function takes.
-The function should be written in the following manner:
-
address@hidden
-/* do_xxx --- do xxx function for gawk */
-
-NODE *
-do_xxx(int nargs)
address@hidden
- @dots{}
address@hidden
address@hidden example
address@hidden Robbins, Arnold
+Using this address automatically sends a copy of your
+mail to me. If necessary, I can be reached directly at
address@hidden@@skeeve.com,arnold at skeeve dot com}.
+The bug reporting address is preferred since the
+email list is archived at the GNU Project.
address@hidden email should be in English, since that is my native language.}
address@hidden arguments, retrieving
address@hidden @code{get_argument()} internal function
address@hidden internal function, @code{get_argument()}
address@hidden NODE *get_argument(int i)
-This function is called from within a C extension function to get
-the @code{i}-th argument from the function call.
-The first argument is argument zero.
-
address@hidden @code{get_actual_argument()} internal function
address@hidden internal function, @code{get_actual_argument()}
address@hidden NODE *get_actual_argument(int i,
address@hidden @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ int@
optional,@ int@ wantarray);
-This function retrieves a particular argument @code{i}. @code{wantarray} is
@code{TRUE}
-if the argument should be an array, @code{FALSE} otherwise. If @code{optional}
is
address@hidden, the argument need not have been supplied. If it wasn't, the
return
-value is @code{NULL}. It is a fatal error if @code{optional} is @code{TRUE}
but
-the argument was not provided.
-
address@hidden @code{get_scalar_argument()} internal macro
address@hidden internal macro, @code{get_scalar_argument()}
address@hidden get_scalar_argument(i, opt)
-This is a convenience macro that calls @code{get_actual_argument()}.
-
address@hidden @code{get_array_argument()} internal macro
address@hidden internal macro, @code{get_array_argument()}
address@hidden get_array_argument(i, opt)
-This is a convenience macro that calls @code{get_actual_argument()}.
-
address@hidden functions, return address@hidden setting
address@hidden @code{comp.lang.awk} newsgroup
address@hidden CAUTION
+Do @emph{not} try to report bugs in @command{gawk} by
+posting to the Usenet/Internet newsgroup @code{comp.lang.awk}.
+While the @command{gawk} developers do occasionally read this newsgroup,
+there is no guarantee that we will see your posting. The steps described
+above are the official recognized ways for reporting bugs.
+Really.
address@hidden quotation
address@hidden @code{ERRNO} variable
address@hidden @code{update_ERRNO_int()} internal function
address@hidden internal function, @code{update_ERRNO_int()}
address@hidden void update_ERRNO_int(int errno_saved)
-This function is called from within a C extension function to set
-the value of @command{gawk}'s @code{ERRNO} variable, based on the error
-value provided as the argument.
-It is provided as a convenience.
address@hidden NOTE
+Many distributions of GNU/Linux and the various BSD-based operating systems
+have their own bug reporting systems. If you report a bug using your
distribution's
+bug reporting system, @emph{please} also send a copy to
address@hidden@@gnu.org,bug-gawk at gnu dot org}.
address@hidden @code{ERRNO} variable
address@hidden @code{update_ERRNO_string()} internal function
address@hidden internal function, @code{update_ERRNO_string()}
address@hidden void update_ERRNO_string(const char *string, enum
errno_translate)
-This function is called from within a C extension function to set
-the value of @command{gawk}'s @code{ERRNO} variable to a given string.
-The second argument determines whether the string is translated before being
-installed into @code{ERRNO}. It is provided as a convenience.
+This is for two reasons. First, while some distributions forward
+bug reports ``upstream'' to the GNU mailing list, many don't, so there is a
good
+chance that the @command{gawk} maintainer won't even see the bug report!
Second,
+mail to the GNU list is archived, and having everything at the GNU project
+keeps things self-contained and not dependant on other web sites.
address@hidden quotation
address@hidden @code{ERRNO} variable
address@hidden @code{unset_ERRNO()} internal function
address@hidden internal function, @code{unset_ERRNO()}
address@hidden void unset_ERRNO(void)
-This function is called from within a C extension function to set
-the value of @command{gawk}'s @code{ERRNO} variable to a null string.
-It is provided as a convenience.
+Non-bug suggestions are always welcome as well. If you have questions
+about things that are unclear in the documentation or are just obscure
+features, ask me; I will try to help you out, although I
+may not have the time to fix the problem. You can send me electronic
+mail at the Internet address noted previously.
address@hidden @code{ENVIRON} array
address@hidden @code{PROCINFO} array
address@hidden @code{register_deferred_variable()} internal function
address@hidden internal function, @code{register_deferred_variable()}
address@hidden void register_deferred_variable(const char *name, NODE
*(*load_func)(void))
-This function is called to register a function to be called when a
-reference to an undefined variable with the given name is encountered.
-The callback function will never be called if the variable exists already,
-so, unless the calling code is running at program startup, it should first
-check whether a variable of the given name already exists.
-The argument function must return a pointer to a @code{NODE} containing the
-newly created variable. This function is used to implement the builtin
address@hidden and @code{PROCINFO} arrays, so you can refer to them
-for examples.
-
address@hidden @code{IOBUF} internal structure
address@hidden internal structure, @code{IOBUF}
address@hidden @code{iop_alloc()} internal function
address@hidden internal function, @code{iop_alloc()}
address@hidden @code{get_record()} input method
address@hidden @code{close_func}() input method
address@hidden @code{INVALID_HANDLE} internal constant
address@hidden internal constant, @code{INVALID_HANDLE}
address@hidden XML (eXtensible Markup Language)
address@hidden eXtensible Markup Language (XML)
address@hidden @code{register_open_hook()} internal function
address@hidden internal function, @code{register_open_hook()}
address@hidden void register_open_hook(void *(*open_func)(IOBUF *))
-This function is called to register a function to be called whenever
-a new data file is opened, leading to the creation of an @code{IOBUF}
-structure in @code{iop_alloc()}. After creating the new @code{IOBUF},
address@hidden()} will call (in reverse order of registration, so the last
-function registered is called first) each open hook until one returns
address@hidden If any hook returns a address@hidden value, that value is
assigned
-to the @code{IOBUF}'s @code{opaque} field (which will presumably point
-to a structure containing additional state associated with the input
-processing), and no further open hooks are called.
-
-The function called will most likely want to set the @code{IOBUF}'s
address@hidden method to indicate that future input records should
-be retrieved by calling that method instead of using the standard
address@hidden input processing.
-
-And the function will also probably want to set the @code{IOBUF}'s
address@hidden method to be called when the file is closed to clean
-up any state associated with the input.
-
-Finally, hook functions should be prepared to receive an @code{IOBUF}
-structure where the @code{fd} field is set to @code{INVALID_HANDLE},
-meaning that @command{gawk} was not able to open the file itself. In
-this case, the hook function must be able to successfully open the file
-and place a valid file descriptor there.
-
-Currently, for example, the hook function facility is used to implement
-the XML parser shared library extension. For more info, please look in
address@hidden and in @file{io.c}.
address@hidden table
+If you find bugs in one of the non-Unix ports of @command{gawk}, please send
+an electronic mail message to the person who maintains that port. They
+are named in the following list, as well as in the @file{README} file in the
@command{gawk}
+distribution. Information in the @file{README} file should be considered
+authoritative if it conflicts with this @value{DOCUMENT}.
-An argument that is supposed to be an array needs to be handled with
-some extra code, in case the array being passed in is actually
-from a function parameter.
+The people maintaining the non-Unix ports of @command{gawk} are
+as follows:
-The following boilerplate code shows how to do this:
address@hidden {MS-Windows with MINGW}
{123456789012345678901234567890123456789001234567890}
address@hidden Deifik, Scott
address@hidden MS-DOS with DJGPP @tab Scott Deifik,
@EMAIL{scottd.mail@@sbcglobal.net,scottd dot mail at sbcglobal dot net}.
address@hidden
-NODE *the_arg;
address@hidden Zaretskii, Eli
address@hidden MS-Windows with MINGW @tab Eli Zaretskii,
@EMAIL{eliz@@gnu.org,eliz at gnu dot org}.
-/* assume need 3rd arg, 0-based */
-the_arg = get_array_argument(2, FALSE);
address@hidden example
address@hidden Buening, Andreas
address@hidden OS/2 @tab Andreas Buening,
@EMAIL{andreas.buening@@nexgo.de,andreas dot buening at nexgo dot de}.
-Again, you should spend time studying the @command{gawk} internals;
-don't just blindly copy this code.
address@hidden ENDOFRANGE gawint
address@hidden Rankin, Pat
address@hidden VMS @tab Pat Rankin, @EMAIL{r.pat.rankin@@gmail.com,r.pat.rankin
at gmail.com}
address@hidden Plugin License
address@hidden Extension Licensing
address@hidden Pitts, Dave
address@hidden z/OS (OS/390) @tab Dave Pitts, @EMAIL{dpitts@@cozx.com,dpitts at
cozx dot com}.
address@hidden multitable
-Every dynamic extension should define the global symbol
address@hidden to assert that it has been licensed under
-a GPL-compatible license. If this symbol does not exist, @command{gawk}
-will emit a fatal error and exit.
+If your bug is also reproducible under Unix, please send a copy of your
+report to the @EMAIL{bug-gawk@@gnu.org,bug-gawk at gnu dot org} email list as
well.
address@hidden ENDOFRANGE dbugg
address@hidden ENDOFRANGE tblgawb
-The declared type of the symbol should be @code{int}. It does not need
-to be in any allocated section, though. The code merely asserts that
-the symbol exists in the global scope. Something like this is enough:
address@hidden Other Versions
address@hidden Other Freely Available @command{awk} Implementations
address@hidden STARTOFRANGE awkim
address@hidden @command{awk}, implementations
address@hidden
+From: emory!amc.com!brennan (Michael Brennan)
+Subject: C++ comments in awk programs
+To: address@hidden (Arnold Robbins)
+Date: Wed, 4 Sep 1996 08:11:48 -0700 (PDT)
address@hidden
-int plugin_is_GPL_compatible;
address@hidden example
address@hidden ignore
address@hidden Brennan, Michael
address@hidden
address@hidden's kind of fun to put comments like this in your awk
address@hidden
+@ @ @ @ @ @ @code{// Do C++ comments work? answer: yes! of address@hidden
+Michael Brennan
address@hidden quotation
address@hidden Loading Extensions
address@hidden Loading a Dynamic Extension
address@hidden loading extension
address@hidden @command{gawk}, functions, loading
-There are two ways to load a dynamically linked library. The first is to use
the
-builtin @code{extension()}:
+There are a number of other freely available @command{awk} implementations.
+This @value{SECTION} briefly describes where to get them:
address@hidden
-extension(libname, init_func)
address@hidden example
address@hidden @asis
address@hidden Kernighan, Brian
address@hidden source code, Brian Kernighan's @command{awk}
address@hidden @command{awk}, versions of, See Also Brian Kernighan's
@command{awk}
address@hidden extensions, Brian Kernighan's @command{awk}
address@hidden Brian Kernighan's @command{awk}, extensions
address@hidden Unix @command{awk}
+Brian Kernighan, one of the original designers of Unix @command{awk},
+has made his implementation of
address@hidden freely available.
+You can retrieve this version via the World Wide Web from
address@hidden://www.cs.princeton.edu/~bwk, his home page}.
+It is available in several archive formats:
-where @file{libname} is the library to load, and @samp{init_func} is the
-name of the initialization or bootstrap routine to run once loaded.
address@hidden @asis
address@hidden Shell archive
address@hidden://www.cs.princeton.edu/~bwk/btl.mirror/awk.shar}
-The second method for dynamic loading of a library is to use the
-command line option @option{-l}:
address@hidden Compressed @command{tar} file
address@hidden://www.cs.princeton.edu/~bwk/btl.mirror/awk.tar.gz}
address@hidden
-$ @kbd{gawk -l libname -f myprog}
address@hidden example
address@hidden Zip file
address@hidden://www.cs.princeton.edu/~bwk/btl.mirror/awk.zip}
address@hidden table
-This will work only if the initialization routine is named @code{dl_load()}.
+This version requires an ISO C (1990 standard) compiler;
+the C compiler from
+GCC (the GNU Compiler Collection)
+works quite nicely.
-If you use @code{extension()}, the library will be loaded
-at run time. This means that the functions are available only to the rest of
-your script. If you use the command line option @option{-l} instead,
-the library will be loaded before @command{gawk} starts compiling the
-actual program. The net effect is that you can use those functions
-anywhere in the program.
address@hidden Extensions},
+for a list of extensions in this @command{awk} that are not in POSIX
@command{awk}.
address@hidden has a list of directories where it searches for libraries.
-By default, the list includes directories that depend upon how gawk was built
-and installed (@pxref{AWKLIBPATH Variable}). If you want @command{gawk}
-to look for libraries in your private directory, you have to tell it.
-The way to do it is to set the @env{AWKLIBPATH} environment variable
-(@pxref{AWKLIBPATH Variable}).
address@hidden supplies the default shared library platform suffix if it is not
-present in the name of the library.
-If the name of your library is @file{mylib.so}, you can simply type
address@hidden Brennan, Michael
address@hidden @command{mawk} program
address@hidden source code, @command{mawk}
address@hidden @command{mawk}
+Michael Brennan wrote an independent implementation of @command{awk},
+called @command{mawk}. It is available under the GPL
+(@pxref{Copying}),
+just as @command{gawk} is.
address@hidden
-$ @kbd{gawk -l mylib -f myprog}
address@hidden example
+The original distribution site for the @command{mawk} source code
+no longer has it. A copy is available at
address@hidden://www.skeeve.com/gawk/mawk1.3.3.tar.gz}.
-and @command{gawk} will do everything necessary to load in your library,
-and then call your @code{dl_load()} routine.
+In 2009, Thomas Dickey took on @command{mawk} maintenance.
+Basic information is available on
address@hidden://www.invisible-island.net/mawk/mawk.html, the project's web
page}.
+The download URL is
address@hidden://invisible-island.net/datafiles/release/mawk.tar.gz}.
-You can always specify the library using an absolute pathname, in which
-case @command{gawk} will not use @env{AWKLIBPATH} to search for it.
+Once you have it,
address@hidden may be used to decompress this file. Installation
+is similar to @command{gawk}'s
+(@pxref{Unix Installation}).
address@hidden Sample Library
address@hidden Example: Directory and File Operation Built-ins
address@hidden STARTOFRANGE chdirg
address@hidden @code{chdir()} address@hidden implementing in @command{gawk}
address@hidden STARTOFRANGE statg
address@hidden @code{stat()} address@hidden implementing in @command{gawk}
address@hidden STARTOFRANGE filre
address@hidden files, information address@hidden retrieving
address@hidden STARTOFRANGE dirch
address@hidden directories, changing
address@hidden Extensions},
+for a list of extensions in @command{mawk} that are not in POSIX @command{awk}.
-Two useful functions that are not in @command{awk} are @code{chdir()}
-(so that an @command{awk} program can change its directory) and
address@hidden()} (so that an @command{awk} program can gather information about
-a file).
-This @value{SECTION} implements these functions for @command{gawk} in an
-external extension library.
address@hidden Sumner, Andrew
address@hidden @command{awka} compiler for @command{awk}
address@hidden source code, @command{awka}
address@hidden @command{awka}
+Written by Andrew Sumner,
address@hidden translates @command{awk} programs into C, compiles them,
+and links them with a library of functions that provides the core
address@hidden functionality.
+It also has a number of extensions.
address@hidden
-* Internal File Description:: What the new functions will do.
-* Internal File Ops:: The code for internal file operations.
-* Using Internal File Ops:: How to use an external extension.
address@hidden menu
+The @command{awk} translator is released under the GPL, and the library
+is under the LGPL.
address@hidden Internal File Description
address@hidden Using @code{chdir()} and @code{stat()}
+To get @command{awka}, go to @url{http://sourceforge.net/projects/awka}.
address@hidden You can reach Andrew Sumner at @email{andrew@@zbcom.net}.
address@hidden andrewsumner@@yahoo.net
-This @value{SECTION} shows how to use the new functions at the @command{awk}
-level once they've been integrated into the running @command{gawk}
-interpreter.
-Using @code{chdir()} is very straightforward. It takes one argument,
-the new directory to change to:
+The project seems to be frozen; no new code changes have been made
+since approximately 2003.
address@hidden
address@hidden
-newdir = "/home/arnold/funstuff"
-ret = chdir(newdir)
-if (ret < 0) @{
- printf("could not change to %s: %s\n",
- newdir, ERRNO) > "/dev/stderr"
- exit 1
address@hidden
address@hidden
address@hidden example
address@hidden Beebe, Nelson
address@hidden @command{pawk} (profiling version of Brian Kernighan's
@command{awk})
address@hidden source code, @command{pawk}
address@hidden @command{pawk}
+Nelson H.F.@: Beebe at the University of Utah has modified
+Brian Kernighan's @command{awk} to provide timing and profiling information.
+It is different from @command{gawk} with the @option{--profile} option.
+(@pxref{Profiling}),
+in that it uses CPU-based profiling, not line-count
+profiling. You may find it at either
address@hidden://ftp.math.utah.edu/pub/pawk/pawk-20030606.tar.gz}
+or
address@hidden://www.math.utah.edu/pub/pawk/pawk-20030606.tar.gz}.
-The return value is negative if the @code{chdir} failed,
-and @code{ERRNO}
-(@pxref{Built-in Variables})
-is set to a string indicating the error.
address@hidden Busybox Awk
address@hidden Busybox Awk
address@hidden source code, Busybox Awk
+Busybox is a GPL-licensed program providing small versions of many
+applications within a single executable. It is aimed at embedded systems.
+It includes a full implementation of POSIX @command{awk}. When building
+it, be careful not to do @samp{make install} as it will overwrite
+copies of other applications in your @file{/usr/local/bin}. For more
+information, see the @uref{http://busybox.net, project's home page}.
-Using @code{stat()} is a bit more complicated.
-The C @code{stat()} function fills in a structure that has a fair
-amount of information.
-The right way to model this in @command{awk} is to fill in an associative
-array with the appropriate information:
address@hidden OpenSolaris
address@hidden Solaris, POSIX-compliant @command{awk}
address@hidden source code, Solaris @command{awk}
address@hidden The OpenSolaris POSIX @command{awk}
+The version of @command{awk} in @file{/usr/xpg4/bin} on Solaris is
+more-or-less
+POSIX-compliant. It is based on the @command{awk} from Mortice Kern
+Systems for PCs. The source code can be downloaded from
+the @uref{http://www.opensolaris.org, OpenSolaris web site}.
+This author was able to make it compile and work under GNU/Linux
+with 1--2 hours of work. Making it more generally portable (using
+GNU Autoconf and/or Automake) would take more work, and this
+has not been done, at least to our knowledge.
address@hidden broke printf for page breaking
address@hidden
-file = "/home/arnold/.profile"
-fdata[1] = "x" # force `fdata' to be an array
-ret = stat(file, fdata)
-if (ret < 0) @{
- printf("could not stat %s: %s\n",
- file, ERRNO) > "/dev/stderr"
- exit 1
address@hidden
-printf("size of %s is %d bytes\n", file, fdata["size"])
address@hidden example
address@hidden @command{jawk}
address@hidden Java implementation of @command{awk}
address@hidden source code, @command{jawk}
address@hidden @command{jawk}
+This is an interpreter for @command{awk} written in Java. It claims
+to be a full interpreter, although because it uses Java facilities
+for I/O and for regexp matching, the language it supports is different
+from POSIX @command{awk}. More information is available on the
address@hidden://jawk.sourceforge.net, project's home page}.
-The @code{stat()} function always clears the data array, even if
-the @code{stat()} fails. It fills in the following elements:
address@hidden Libmawk
address@hidden libmawk
address@hidden source code, libmawk
+This is an embeddable @command{awk} interpreter derived from
address@hidden For more information see
address@hidden://repo.hu/projects/libmawk/}.
address@hidden @code
address@hidden "name"
-The name of the file that was @code{stat()}'ed.
address@hidden @w{QSE Awk}
address@hidden QSE Awk
address@hidden source code, QSE Awk
+This is an embeddable @command{awk} interpreter. For more information
+see @uref{http://code.google.com/p/qse/} and @uref{http://awk.info/?tools/qse}.
address@hidden "dev"
address@hidden "ino"
-The file's device and inode numbers, respectively.
address@hidden @command{QTawk}
address@hidden QuikTrim Awk
address@hidden source code, QuikTrim Awk
+This is an independent implementation of @command{awk} distributed
+under the GPL. It has a large number of extensions over standard
address@hidden and may not be 100% syntactically compatible with it.
+See @uref{http://www.quiktrim.org/QTawk.html} for more information,
+including the manual and a download link.
address@hidden "mode"
-The file's mode, as a numeric value. This includes both the file's
-type and its permissions.
address@hidden @command{xgawk}
address@hidden @command{xgawk}
address@hidden source code, @command{xgawk}
+XML @command{gawk}.
+This is a fork of the @command{gawk} 3.1.6 source base
+to support processing XML files. It has a number of
+interesting extensions which should one day be integrated
+into the main @command{gawk} code base.
+For more information, see
address@hidden://xmlgawk.sourceforge.net, the XMLgawk project web site}.
address@hidden "nlink"
-The number of hard links (directory entries) the file has.
address@hidden table
address@hidden ENDOFRANGE gligawk
address@hidden ENDOFRANGE ingawk
address@hidden ENDOFRANGE awkim
address@hidden "uid"
address@hidden "gid"
-The numeric user and group ID numbers of the file's owner.
address@hidden Notes
address@hidden Implementation Notes
address@hidden STARTOFRANGE gawii
address@hidden @command{gawk}, implementation issues
address@hidden STARTOFRANGE impis
address@hidden implementation issues, @command{gawk}
address@hidden "size"
-The size in bytes of the file.
+This appendix contains information mainly of interest to implementers and
+maintainers of @command{gawk}. Everything in it applies specifically to
address@hidden and not to other implementations.
address@hidden "blocks"
-The number of disk blocks the file actually occupies. This may not
-be a function of the file's size if the file has holes.
address@hidden
+* Compatibility Mode:: How to disable certain @command{gawk}
+ extensions.
+* Additions:: Making Additions To @command{gawk}.
+* Future Extensions:: New features that may be implemented one day.
address@hidden menu
address@hidden "atime"
address@hidden "mtime"
address@hidden "ctime"
-The file's last access, modification, and inode update times,
-respectively. These are numeric timestamps, suitable for formatting
-with @code{strftime()}
-(@pxref{Built-in}).
address@hidden Compatibility Mode
address@hidden Downward Compatibility and Debugging
address@hidden @command{gawk}, implementation issues, downward compatibility
address@hidden @command{gawk}, implementation issues, debugging
address@hidden troubleshooting, @command{gawk}
address@hidden implementation address@hidden @command{gawk}, debugging
address@hidden "pmode"
-The file's ``printable mode.'' This is a string representation of
-the file's type and permissions, such as what is produced by
address@hidden -l}---for example, @code{"drwxr-xr-x"}.
address@hidden/GNU},
+for a summary of the GNU extensions to the @command{awk} language and program.
+All of these features can be turned off by invoking @command{gawk} with the
address@hidden option or with the @option{--posix} option.
address@hidden "type"
-A printable string representation of the file's type. The value
-is one of the following:
+If @command{gawk} is compiled for debugging with @samp{-DDEBUG}, then there
+is one more option available on the command line:
@table @code
address@hidden "blockdev"
address@hidden "chardev"
-The file is a block or character device (``special file'').
address@hidden -Y
address@hidden --parsedebug
+Prints out the parse stack information as the program is being parsed.
address@hidden table
address@hidden
address@hidden "door"
-The file is a Solaris ``door'' (special file used for
-interprocess communications).
address@hidden ignore
+This option is intended only for serious @command{gawk} developers
+and not for the casual user. It probably has not even been compiled into
+your version of @command{gawk}, since it slows down execution.
address@hidden "directory"
-The file is a directory.
address@hidden Additions
address@hidden Making Additions to @command{gawk}
+
+If you find that you want to enhance @command{gawk} in a significant
+fashion, you are perfectly free to do so. That is the point of having
+free software; the source code is available and you are free to change
+it as you want (@pxref{Copying}).
address@hidden "fifo"
-The file is a named-pipe (also known as a FIFO).
+This @value{SECTION} discusses the ways you might want to change @command{gawk}
+as well as any considerations you should bear in mind.
address@hidden "file"
-The file is just a regular file.
address@hidden
+* Accessing The Source:: Accessing the Git repository.
+* Adding Code:: Adding code to the main body of
+ @command{gawk}.
+* New Ports:: Porting @command{gawk} to a new operating
+ system.
address@hidden menu
address@hidden "socket"
-The file is an @code{AF_UNIX} (``Unix domain'') socket in the
-filesystem.
address@hidden Accessing The Source
address@hidden Accessing The @command{gawk} Git Repository
address@hidden "symlink"
-The file is a symbolic link.
address@hidden table
address@hidden table
+As @command{gawk} is Free Software, the source code is always available.
address@hidden Distribution}, describes how to get and build the formal,
+released versions of @command{gawk}.
-Several additional elements may be present depending upon the operating
-system and the type of the file. You can test for them in your @command{awk}
-program by using the @code{in} operator
-(@pxref{Reference to Elements}):
+However, if you want to modify @command{gawk} and contribute back your
+changes, you will probably wish to work with the development version.
+To do so, you will need to access the @command{gawk} source code
+repository. The code is maintained using the
address@hidden://git-scm.com/, Git distributed version control system}.
+You will need to install it if your system doesn't have it.
+Once you have done so, use the command:
address@hidden @code
address@hidden "blksize"
-The preferred block size for I/O to the file. This field is not
-present on all POSIX-like systems in the C @code{stat} structure.
address@hidden
+git clone git://git.savannah.gnu.org/gawk.git
address@hidden example
address@hidden "linkval"
-If the file is a symbolic link, this element is the name of the
-file the link points to (i.e., the value of the link).
address@hidden
+This will clone the @command{gawk} repository. If you are behind a
+firewall that will not allow you to use the Git native protocol, you
+can still access the repository using:
address@hidden "rdev"
address@hidden "major"
address@hidden "minor"
-If the file is a block or character device file, then these values
-represent the numeric device number and the major and minor components
-of that number, respectively.
address@hidden table
address@hidden
+git clone http://git.savannah.gnu.org/r/gawk.git
address@hidden example
address@hidden Internal File Ops
address@hidden C Code for @code{chdir()} and @code{stat()}
+Once you have made changes, you can use @samp{git diff} to produce a
+patch, and send that to the @command{gawk} maintainer; see @ref{Bugs}
+for how to do that.
-Here is the C code for these extensions. They were written for
-GNU/Linux. The code needs some more work for complete portability
-to other POSIX-compliant systems:@footnote{This version is edited
-slightly for presentation. See
address@hidden/filefuncs.c} in the @command{gawk} distribution
-for the complete version.}
+Finally, if you cannot install Git (e.g., if it hasn't been ported
+yet to your operating system), you can use the Git--CVS gateway
+to check out a copy using CVS, as follows:
address@hidden break line for page breaking
@example
-#include "awk.h"
+cvs -d:pserver:anonymous@@pserver.git.sv.gnu.org:/gawk.git co -d gawk master
address@hidden example
-#include <sys/sysmacros.h>
address@hidden Adding Code
address@hidden Adding New Features
-int plugin_is_GPL_compatible;
address@hidden STARTOFRANGE adfgaw
address@hidden adding, features to @command{gawk}
address@hidden STARTOFRANGE fadgaw
address@hidden features, adding to @command{gawk}
address@hidden STARTOFRANGE gawadf
address@hidden @command{gawk}, features, adding
+You are free to add any new features you like to @command{gawk}.
+However, if you want your changes to be incorporated into the @command{gawk}
+distribution, there are several steps that you need to take in order to
+make it possible to include your changes:
-/* do_chdir --- provide dynamically loaded chdir() builtin for gawk */
address@hidden 1
address@hidden
+Before building the new feature into @command{gawk} itself,
+consider writing it as an extension module
+(@pxref{Dynamic Extensions}).
+If that's not possible, continue with the rest of the steps in this list.
-static NODE *
-do_chdir(int nargs)
address@hidden
- NODE *newdir;
- int ret = -1;
address@hidden
+Be prepared to sign the appropriate paperwork.
+In order for the FSF to distribute your changes, you must either place
+those changes in the public domain and submit a signed statement to that
+effect, or assign the copyright in your changes to the FSF.
+Both of these actions are easy to do and @emph{many} people have done so
+already. If you have questions, please contact me
+(@pxref{Bugs}),
+or @EMAIL{assign@@gnu.org,assign at gnu dot org}.
- if (do_lint && nargs != 1)
- lintwarn("chdir: called with incorrect number of arguments");
address@hidden
+Get the latest version.
+It is much easier for me to integrate changes if they are relative to
+the most recent distributed version of @command{gawk}. If your version of
address@hidden is very old, I may not be able to integrate them at all.
+(@xref{Getting},
+for information on getting the latest version of @command{gawk}.)
- newdir = get_scalar_argument(0, FALSE);
address@hidden example
address@hidden
address@hidden
+Follow the @cite{GNU Coding Standards}.
address@hidden ifnotinfo
address@hidden
+See @inforef{Top, , Version, standards, GNU Coding Standards}.
address@hidden ifinfo
+This document describes how GNU software should be written. If you haven't
+read it, please do so, preferably @emph{before} starting to modify
@command{gawk}.
+(The @cite{GNU Coding Standards} are available from
+the GNU Project's
address@hidden://www.gnu.org/prep/standards_toc.html, web site}.
+Texinfo, Info, and DVI versions are also available.)
-The file includes the @code{"awk.h"} header file for definitions
-for the @command{gawk} internals. It includes @code{<sys/sysmacros.h>}
-for access to the @code{major()} and @code{minor}() macros.
address@hidden @command{gawk}, coding style in
address@hidden
+Use the @command{gawk} coding style.
+The C code for @command{gawk} follows the instructions in the
address@hidden Coding Standards}, with minor exceptions. The code is formatted
+using the traditional ``K&R'' style, particularly as regards to the placement
+of braces and the use of TABs. In brief, the coding rules for @command{gawk}
+are as follows:
address@hidden programming conventions, @command{gawk} internals
-By convention, for an @command{awk} function @code{foo}, the function that
-implements it is called @samp{do_foo}. The function should take
-a @samp{int} argument, usually called @code{nargs}, that
-represents the number of defined arguments for the function. The @code{newdir}
-variable represents the new directory to change to, retrieved
-with @code{get_scalar_argument()}. Note that the first argument is
-numbered zero.
address@hidden @bullet
address@hidden
+Use ANSI/ISO style (prototype) function headers when defining functions.
-This code actually accomplishes the @code{chdir()}. It first forces
-the argument to be a string and passes the string value to the
address@hidden()} system call. If the @code{chdir()} fails, @code{ERRNO}
-is updated.
address@hidden
+Put the name of the function at the beginning of its own line.
address@hidden
- (void) force_string(newdir);
- ret = chdir(newdir->stptr);
- if (ret < 0)
- update_ERRNO_int(errno);
address@hidden example
address@hidden
+Put the return type of the function, even if it is @code{int}, on the
+line above the line with the name and arguments of the function.
-Finally, the function returns the return value to the @command{awk} level:
address@hidden
+Put spaces around parentheses used in control structures
+(@code{if}, @code{while}, @code{for}, @code{do}, @code{switch},
+and @code{return}).
address@hidden
- return make_number((AWKNUM) ret);
address@hidden
address@hidden example
address@hidden
+Do not put spaces in front of parentheses used in function calls.
-The @code{stat()} built-in is more involved. First comes a function
-that turns a numeric mode into a printable representation
-(e.g., 644 becomes @samp{-rw-r--r--}). This is omitted here for brevity:
address@hidden
+Put spaces around all C operators and after commas in function calls.
address@hidden break line for page breaking
address@hidden
-/* format_mode --- turn a stat mode field into something readable */
address@hidden
+Do not use the comma operator to produce multiple side effects, except
+in @code{for} loop initialization and increment parts, and in macro bodies.
-static char *
-format_mode(unsigned long fmode)
address@hidden
- @dots{}
address@hidden
address@hidden example
address@hidden
+Use real TABs for indenting, not spaces.
-Next comes the @code{do_stat()} function. It starts with
-variable declarations and argument checking:
address@hidden
+Use the ``K&R'' brace layout style.
address@hidden
-Changed message for page breaking. Used to be:
- "stat: called with incorrect number of arguments (%d), should be 2",
address@hidden ignore
address@hidden
-/* do_stat --- provide a stat() function for gawk */
address@hidden
+Use comparisons against @code{NULL} and @code{'\0'} in the conditions of
address@hidden, @code{while}, and @code{for} statements, as well as in the
@code{case}s
+of @code{switch} statements, instead of just the
+plain pointer or character value.
-static NODE *
-do_stat(int nargs)
address@hidden
- NODE *file, *array, *tmp;
- struct stat sbuf;
- int ret;
- NODE **aptr;
- char *pmode; /* printable mode */
- char *type = "unknown";
address@hidden
+Use the @code{TRUE}, @code{FALSE} and @code{NULL} symbolic constants
+and the character constant @code{'\0'} where appropriate, instead of @code{1}
+and @code{0}.
- if (do_lint && nargs > 2)
- lintwarn("stat: called with too many arguments");
address@hidden example
address@hidden
+Provide one-line descriptive comments for each function.
-Then comes the actual work. First, the function gets the arguments.
-Then, it always clears the array.
-The code use @code{lstat()} (instead of @code{stat()})
-to get the file information,
-in case the file is a symbolic link.
-If there's an error, it sets @code{ERRNO} and returns:
address@hidden
+Do not use the @code{alloca()} function for allocating memory off the
+stack. Its use causes more portability trouble than is worth the minor
+benefit of not having to free the storage. Instead, use @code{malloc()}
+and @code{free()}.
+
address@hidden
+Do not use comparisons of the form @samp{! strcmp(a, b)} or similar.
+As Henry Spencer once said, address@hidden()} is not a boolean!''
+Instead, use @samp{strcmp(a, b) == 0}.
address@hidden comment made multiline for page breaking
address@hidden
- /* file is first arg, array to hold results is second */
- file = get_scalar_argument(0, FALSE);
- array = get_array_argument(1, FALSE);
address@hidden
+If adding new bit flag values, use explicit hexadecimal constants
+(@code{0x001}, @code{0x002}, @code{0x004}, and son on) instead of
+shifting one left by successive amounts (@samp{(1<<0)}, @samp{(1<<1)},
+and so on).
address@hidden itemize
- /* empty out the array */
- assoc_clear(array);
address@hidden NOTE
+If I have to reformat your code to follow the coding style used in
address@hidden, I may not bother to integrate your changes at all.
address@hidden quotation
- /* lstat the file, if error, set ERRNO and return */
- (void) force_string(file);
- ret = lstat(file->stptr, & sbuf);
- if (ret < 0) @{
- update_ERRNO_int(errno);
- return make_number((AWKNUM) ret);
- @}
address@hidden example
address@hidden Texinfo
address@hidden
+Update the documentation.
+Along with your new code, please supply new sections and/or chapters
+for this @value{DOCUMENT}. If at all possible, please use real
+Texinfo, instead of just supplying unformatted ASCII text (although
+even that is better than no documentation at all).
+Conventions to be followed in @address@hidden are provided
+after the @samp{@@bye} at the end of the Texinfo source file.
+If possible, please update the @command{man} page as well.
-Now comes the tedious part: filling in the array. Only a few of the
-calls are shown here, since they all follow the same pattern:
+You will also have to sign paperwork for your documentation changes.
address@hidden
- /* fill in the array */
- aptr = assoc_lookup(array, tmp = make_string("name", 4));
- *aptr = dupnode(file);
- unref(tmp);
address@hidden
+Submit changes as unified diffs.
+Use @samp{diff -u -r -N} to compare
+the original @command{gawk} source tree with your version.
+I recommend using the GNU version of @command{diff}, or best of all,
address@hidden diff} or @samp{git format-patch}.
+Send the output produced by @command{diff} to me when you
+submit your changes.
+(@xref{Bugs}, for the electronic mail
+information.)
- aptr = assoc_lookup(array, tmp = make_string("mode", 4));
- *aptr = make_number((AWKNUM) sbuf.st_mode);
- unref(tmp);
+Using this format makes it easy for me to apply your changes to the
+master version of the @command{gawk} source code (using @code{patch}).
+If I have to apply the changes manually, using a text editor, I may
+not do so, particularly if there are lots of changes.
- aptr = assoc_lookup(array, tmp = make_string("pmode", 5));
- pmode = format_mode(sbuf.st_mode);
- *aptr = make_string(pmode, strlen(pmode));
- unref(tmp);
address@hidden example
address@hidden
+Include an entry for the @file{ChangeLog} file with your submission.
+This helps further minimize the amount of work I have to do,
+making it easier for me to accept patches.
address@hidden enumerate
-When done, return the @code{lstat()} return value:
+Although this sounds like a lot of work, please remember that while you
+may write the new code, I have to maintain it and support it. If it
+isn't possible for me to do that with a minimum of extra work, then I
+probably will not.
address@hidden ENDOFRANGE adfgaw
address@hidden ENDOFRANGE gawadf
address@hidden ENDOFRANGE fadgaw
address@hidden
address@hidden New Ports
address@hidden Porting @command{gawk} to a New Operating System
address@hidden portability, @command{gawk}
address@hidden operating systems, porting @command{gawk} to
- return make_number((AWKNUM) ret);
address@hidden
address@hidden example
address@hidden porting @command{gawk}
+If you want to port @command{gawk} to a new operating system, there are
+several steps:
address@hidden programming conventions, @command{gawk} internals
-Finally, it's necessary to provide the ``glue'' that loads the
-new function(s) into @command{gawk}. By convention, each library has
-a routine named @code{dl_load()} that does the job. The simplest way
-is to use the @code{dl_load_func} macro in @code{gawkapi.h}.
address@hidden 1
address@hidden
+Follow the guidelines in
address@hidden
address@hidden Code},
address@hidden ifinfo
address@hidden
+the previous @value{SECTION}
address@hidden ifnotinfo
+concerning coding style, submission of diffs, and so on.
-And that's it! As an exercise, consider adding functions to
-implement system calls such as @code{chown()}, @code{chmod()},
-and @code{umask()}.
address@hidden
+Be prepared to sign the appropriate paperwork.
+In order for the FSF to distribute your code, you must either place
+your code in the public domain and submit a signed statement to that
+effect, or assign the copyright in your code to the FSF.
address@hidden
+Both of these actions are easy to do and @emph{many} people have done so
+already. If you have questions, please contact me, or
address@hidden@@gnu.org}.
address@hidden ifinfo
address@hidden Using Internal File Ops
address@hidden Integrating the Extensions
address@hidden
+When doing a port, bear in mind that your code must coexist peacefully
+with the rest of @command{gawk} and the other ports. Avoid gratuitous
+changes to the system-independent parts of the code. If at all possible,
+avoid sprinkling @samp{#ifdef}s just for your port throughout the
+code.
address@hidden @command{gawk}, address@hidden adding code to
-Now that the code is written, it must be possible to add it at
-runtime to the running @command{gawk} interpreter. First, the
-code must be compiled. Assuming that the functions are in
-a file named @file{filefuncs.c}, and @var{idir} is the location
-of the @command{gawk} include files,
-the following steps create
-a GNU/Linux shared library:
+If the changes needed for a particular system affect too much of the
+code, I probably will not accept them. In such a case, you can, of course,
+distribute your changes on your own, as long as you comply
+with the GPL
+(@pxref{Copying}).
address@hidden
-$ @kbd{gcc -fPIC -shared -DHAVE_CONFIG_H -c -O -g address@hidden filefuncs.c}
-$ @kbd{ld -o filefuncs.so -shared filefuncs.o}
address@hidden example
address@hidden
+A number of the files that come with @command{gawk} are maintained by other
+people. Thus, you should not change them
+unless it is for a very good reason; i.e., changes are not out of the
+question, but changes to these files are scrutinized extra carefully.
+The files are @file{dfa.c}, @file{dfa.h}, @file{getopt1.c}, @file{getopt.c},
address@hidden, @file{install-sh}, @file{mkinstalldirs}, @file{regcomp.c},
address@hidden, @file{regexec.c}, @file{regexex.c}, @file{regex.h},
address@hidden, and @file{regex_internal.h}.
address@hidden @code{extension()} function (@command{gawk})
-Once the library exists, it is loaded by calling the @code{extension()}
-built-in function.
-This function takes two arguments: the name of the
-library to load and the name of a function to call when the library
-is first loaded. This function adds the new functions to @command{gawk}.
-It returns the value returned by the initialization function
-within the shared library:
address@hidden
+Be willing to continue to maintain the port.
+Non-Unix operating systems are supported by volunteers who maintain
+the code needed to compile and run @command{gawk} on their systems. If noone
+volunteers to maintain a port, it becomes unsupported and it may
+be necessary to remove it from the distribution.
address@hidden
-# file testff.awk
-BEGIN @{
- extension("./filefuncs.so", "dl_load")
address@hidden
+Supply an appropriate @file{gawkmisc.???} file.
+Each port has its own @file{gawkmisc.???} that implements certain
+operating system specific functions. This is cleaner than a plethora of
address@hidden scattered throughout the code. The @file{gawkmisc.c} in
+the main source directory includes the appropriate
address@hidden file from each subdirectory.
+Be sure to update it as well.
- chdir(".") # no-op
+Each port's @file{gawkmisc.???} file has a suffix reminiscent of the machine
+or operating system for the port---for example, @file{pc/gawkmisc.pc} and
address@hidden/gawkmisc.vms}. The use of separate suffixes, instead of plain
address@hidden, makes it possible to move files from a port's subdirectory
+into the main subdirectory, without accidentally destroying the real
address@hidden file. (Currently, this is only an issue for the
+PC operating system ports.)
- data[1] = 1 # force `data' to be an array
- print "Info for testff.awk"
- ret = stat("testff.awk", data)
- print "ret =", ret
- for (i in data)
- printf "data[\"%s\"] = %s\n", i, data[i]
- print "testff.awk modified:",
- strftime("%m %d %y %H:%M:%S", data["mtime"])
address@hidden
+Supply a @file{Makefile} as well as any other C source and header files that
are
+necessary for your operating system. All your code should be in a
+separate subdirectory, with a name that is the same as, or reminiscent
+of, either your operating system or the computer system. If possible,
+try to structure things so that it is not necessary to move files out
+of the subdirectory into the main source directory. If that is not
+possible, then be sure to avoid using names for your files that
+duplicate the names of files in the main source directory.
- print "\nInfo for JUNK"
- ret = stat("JUNK", data)
- print "ret =", ret
- for (i in data)
- printf "data[\"%s\"] = %s\n", i, data[i]
- print "JUNK modified:", strftime("%m %d %y %H:%M:%S", data["mtime"])
address@hidden
address@hidden example
address@hidden
+Update the documentation.
+Please write a section (or sections) for this @value{DOCUMENT} describing the
+installation and compilation steps needed to compile and/or install
address@hidden for your system.
address@hidden enumerate
-Here are the results of running the program:
+Following these steps makes it much easier to integrate your changes
+into @command{gawk} and have them coexist happily with other
+operating systems' code that is already there.
address@hidden
-$ @kbd{gawk -f testff.awk}
address@hidden Info for testff.awk
address@hidden ret = 0
address@hidden data["size"] = 607
address@hidden data["ino"] = 14945891
address@hidden data["name"] = testff.awk
address@hidden data["pmode"] = -rw-rw-r--
address@hidden data["nlink"] = 1
address@hidden data["atime"] = 1293993369
address@hidden data["mtime"] = 1288520752
address@hidden data["mode"] = 33204
address@hidden data["blksize"] = 4096
address@hidden data["dev"] = 2054
address@hidden data["type"] = file
address@hidden data["gid"] = 500
address@hidden data["uid"] = 500
address@hidden data["blocks"] = 8
address@hidden data["ctime"] = 1290113572
address@hidden testff.awk modified: 10 31 10 12:25:52
address@hidden
address@hidden Info for JUNK
address@hidden ret = -1
address@hidden JUNK modified: 01 01 70 02:00:00
address@hidden example
address@hidden ENDOFRANGE filre
address@hidden ENDOFRANGE dirch
address@hidden ENDOFRANGE statg
address@hidden ENDOFRANGE chdirg
address@hidden ENDOFRANGE gladfgaw
address@hidden ENDOFRANGE adfugaw
address@hidden ENDOFRANGE fubadgaw
+In the code that you supply and maintain, feel free to use a
+coding style and brace layout that suits your taste.
@node Future Extensions
@appendixsec Probable Future Extensions
@@ -31055,12 +30686,8 @@ Following is a list of probable future changes visible
at the
@c these are ordered by likelihood
@table @asis
address@hidden Loadable module interface
-It is not clear that the @command{awk}-level interface to the
-modules facility is as good as it should be. The interface needs to be
-redesigned, particularly taking namespace issues into account, as
-well as possibly including issues such as library search path order
-and versioning.
address@hidden Databases
+It may be possible to map a GDBM/NDBM/SDBM file into an @command{awk} array.
@item @code{RECLEN} variable for fixed-length records
Along with @code{FIELDWIDTHS}, this would speed up the processing of
@@ -31068,9 +30695,6 @@ fixed-length records.
@code{PROCINFO["RS"]} would be @code{"RS"} or @code{"RECLEN"},
depending upon which kind of record processing is in effect.
address@hidden Databases
-It may be possible to map a GDBM/NDBM/SDBM file into an @command{awk} array.
-
@item More @code{lint} warnings
There are more things that could be checked for portability.
@end table
@@ -31079,21 +30703,6 @@ Following is a list of probable improvements that will
make @command{gawk}'s
source code easier to work with:
@table @asis
address@hidden Loadable module mechanics
-The current extension mechanism works
-(@pxref{Dynamic Extensions}),
-but is rather primitive. It requires a fair amount of manual work
-to create and integrate a loadable module.
-Nor is the current mechanism as portable as might be desired.
-The GNU @command{libtool} package provides a number of features that
-would make using loadable modules much easier.
address@hidden should be changed to use @command{libtool}.
-
address@hidden Loadable module internals
-The API to its internals that @command{gawk} ``exports'' should be revised.
-Too many things are needlessly exposed. A new API should be designed
-and implemented to make module writing easier.
-
@item Better array subscript management
@command{gawk}'s management of array subscript storage could use revamping,
so that using the same value to index multiple arrays only
-----------------------------------------------------------------------
Summary of changes:
ChangeLog | 4 +
FUTURES | 20 +-
TODO.xgawk | 11 +-
doc/ChangeLog | 6 +
doc/awkcard.in | 46 +-
doc/gawk.1 | 29 +-
doc/gawk.info | 2635 ++++++++++++--------------
doc/gawk.texi | 5632 +++++++++++++++++++++++++++-----------------------------
8 files changed, 3998 insertions(+), 4385 deletions(-)
hooks/post-receive
--
gawk
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [gawk-diffs] [SCM] gawk branch, extgawk, updated. 9cc3e7f1126d924a343f01be6a92cf6aefe97bab,
Arnold Robbins <=