This is Info file gawk.info, produced by Makeinfo version 1.67 from the input file /ade-src/fsf/gawk/doc/gawk.texi. INFO-DIR-SECTION Programming Languages START-INFO-DIR-ENTRY * Gawk: (gawk.info). A Text Scanning and Processing Language. END-INFO-DIR-ENTRY This file documents `awk', a program that you can use to select particular records in a file and perform operations upon them. This is Edition 1.0.2 of `The GNU Awk User's Guide', for the 3.0.2 version of the GNU implementation of AWK. Copyright (C) 1989, 1991, 92, 93, 96 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation.  File: gawk.info, Node: Built-in Functions Summary, Next: Time Functions Summary, Prev: Special File Summary, Up: Actions Summary Built-in Functions ------------------ `awk' provides a number of built-in functions for performing numeric operations, string related operations, and I/O related operations. The built-in arithmetic functions are: `atan2(Y, X)' the arctangent of Y/X in radians. `cos(EXPR)' the cosine of EXPR, which is in radians. `exp(EXPR)' the exponential function (`e ^ EXPR'). `int(EXPR)' truncates to integer. `log(EXPR)' the natural logarithm of `expr'. `rand()' a random number between zero and one. `sin(EXPR)' the sine of EXPR, which is in radians. `sqrt(EXPR)' the square root function. `srand([EXPR])' use EXPR as a new seed for the random number generator. If no EXPR is provided, the time of day is used. The return value is the previous seed for the random number generator. `awk' has the following built-in string functions: `gensub(REGEX, SUBST, HOW [, TARGET])' If HOW is a string beginning with `g' or `G', then replace each match of REGEX in TARGET with SUBST. Otherwise, replace the HOW'th occurrence. If TARGET is not supplied, use `$0'. The return value is the changed string; the original TARGET is not modified. Within SUBST, `\N', where N is a digit from one to nine, can be used to indicate the text that matched the N'th parenthesized subexpression. This function is `gawk'-specific. `gsub(REGEX, SUBST [, TARGET])' for each substring matching the regular expression REGEX in the string TARGET, substitute the string SUBST, and return the number of substitutions. If TARGET is not supplied, use `$0'. `index(STR, SEARCH)' returns the index of the string SEARCH in the string STR, or zero if SEARCH is not present. `length([STR])' returns the length of the string STR. The length of `$0' is returned if no argument is supplied. `match(STR, REGEX)' returns the position in STR where the regular expression REGEX occurs, or zero if REGEX is not present, and sets the values of `RSTART' and `RLENGTH'. `split(STR, ARR [, REGEX])' splits the string STR into the array ARR on the regular expression REGEX, and returns the number of elements. If REGEX is omitted, `FS' is used instead. REGEX can be the null string, causing each character to be placed into its own array element. The array ARR is cleared first. `sprintf(FMT, EXPR-LIST)' prints EXPR-LIST according to FMT, and returns the resulting string. `sub(REGEX, SUBST [, TARGET])' just like `gsub', but only the first matching substring is replaced. `substr(STR, INDEX [, LEN])' returns the LEN-character substring of STR starting at INDEX. If LEN is omitted, the rest of STR is used. `tolower(STR)' returns a copy of the string STR, with all the upper-case characters in STR translated to their corresponding lower-case counterparts. Non-alphabetic characters are left unchanged. `toupper(STR)' returns a copy of the string STR, with all the lower-case characters in STR translated to their corresponding upper-case counterparts. Non-alphabetic characters are left unchanged. The I/O related functions are: `close(EXPR)' Close the open file or pipe denoted by EXPR. `fflush([EXPR])' Flush any buffered output for the output file or pipe denoted by EXPR. If EXPR is omitted, standard output is flushed. If EXPR is the null string (`""'), all output buffers are flushed. `system(CMD-LINE)' Execute the command CMD-LINE, and return the exit status. If your operating system does not support `system', calling it will generate a fatal error. `system("")' can be used to force `awk' to flush any pending output. This is more portable, but less obvious, than calling `fflush'.  File: gawk.info, Node: Time Functions Summary, Next: String Constants Summary, Prev: Built-in Functions Summary, Up: Actions Summary Time Functions -------------- The following two functions are available for getting the current time of day, and for formatting time stamps. They are specific to `gawk'. `systime()' returns the current time of day as the number of seconds since a particular epoch (Midnight, January 1, 1970 UTC, on POSIX systems). `strftime([FORMAT[, TIMESTAMP]])' formats TIMESTAMP according to the specification in FORMAT. The current time of day is used if no TIMESTAMP is supplied. A default format equivalent to the output of the `date' utility is used if no FORMAT is supplied. *Note Functions for Dealing with Time Stamps: Time Functions, for the details on the conversion specifiers that `strftime' accepts.  File: gawk.info, Node: String Constants Summary, Prev: Time Functions Summary, Up: Actions Summary String Constants ---------------- String constants in `awk' are sequences of characters enclosed in double quotes (`"'). Within strings, certain "escape sequences" are recognized, as in C. These are: `\\' A literal backslash. `\a' The "alert" character; usually the ASCII BEL character. `\b' Backspace. `\f' Formfeed. `\n' Newline. `\r' Carriage return. `\t' Horizontal tab. `\v' Vertical tab. `\xHEX DIGITS' The character represented by the string of hexadecimal digits following the `\x'. As in ANSI C, all following hexadecimal digits are considered part of the escape sequence. E.g., `"\x1B"' is a string containing the ASCII ESC (escape) character. (The `\x' escape sequence is not in POSIX `awk'.) `\DDD' The character represented by the one, two, or three digit sequence of octal digits. Thus, `"\033"' is also a string containing the ASCII ESC (escape) character. `\C' The literal character C, if C is not one of the above. The escape sequences may also be used inside constant regular expressions (e.g., the regexp `/[ \t\f\n\r\v]/' matches whitespace characters). *Note Escape Sequences::.  File: gawk.info, Node: Functions Summary, Next: Historical Features, Prev: Actions Summary, Up: Gawk Summary User-defined Functions ====================== Functions in `awk' are defined as follows: function NAME(PARAMETER LIST) { STATEMENTS } Actual parameters supplied in the function call are used to instantiate the formal parameters declared in the function. Arrays are passed by reference, other variables are passed by value. If there are fewer arguments passed than there are names in PARAMETER-LIST, the extra names are given the null string as their value. Extra names have the effect of local variables. The open-parenthesis in a function call of a user-defined function must immediately follow the function name, without any intervening white space. This is to avoid a syntactic ambiguity with the concatenation operator. The word `func' may be used in place of `function' (but not in POSIX `awk'). Use the `return' statement to return a value from a function. *Note User-defined Functions: User-defined.  File: gawk.info, Node: Historical Features, Prev: Functions Summary, Up: Gawk Summary Historical Features =================== There are two features of historical `awk' implementations that `gawk' supports. First, it is possible to call the `length' built-in function not only with no arguments, but even without parentheses! a = length is the same as either of a = length() a = length($0) For example: $ echo abcdef | awk '{ print length }' -| 6 This feature is marked as "deprecated" in the POSIX standard, and `gawk' will issue a warning about its use if `--lint' is specified on the command line. (The ability to use `length' this way was actually an accident of the original Unix `awk' implementation. If any built-in function used `$0' as its default argument, it was possible to call that function without the parentheses. In particular, it was common practice to use the `length' function in this fashion, and this usage was documented in the `awk' manual page.) The other historical feature is the use of either the `break' statement, or the `continue' statement outside the body of a `while', `for', or `do' loop. Traditional `awk' implementations have treated such usage as equivalent to the `next' statement. More recent versions of Unix `awk' do not allow it. `gawk' supports this usage if `--traditional' has been specified. *Note Command Line Options: Options, for more information about the `--posix' and `--lint' options.  File: gawk.info, Node: Installation, Next: Notes, Prev: Gawk Summary, Up: Top Installing `gawk' ***************** This appendix provides instructions for installing `gawk' on the various platforms that are supported by the developers. The primary developers support Unix (and one day, GNU), while the other ports were contributed. The file `ACKNOWLEDGMENT' in the `gawk' distribution lists the electronic mail addresses of the people who did the respective ports, and they are also provided in *Note Reporting Problems and Bugs: Bugs.. * Menu: * Gawk Distribution:: What is in the `gawk' distribution. * Unix Installation:: Installing `gawk' under various versions of Unix. * VMS Installation:: Installing `gawk' on VMS. * PC Installation:: Installing and Compiling `gawk' on MS-DOS and OS/2 * Atari Installation:: Installing `gawk' on the Atari ST. * Amiga Installation:: Installing `gawk' on an Amiga. * Bugs:: Reporting Problems and Bugs. * Other Versions:: Other freely available `awk' implementations.  File: gawk.info, Node: Gawk Distribution, Next: Unix Installation, Prev: Installation, Up: Installation The `gawk' Distribution ======================= This section first describes how to get the `gawk' distribution, how to extract it, and then what is in the various files and subdirectories. * Menu: * Getting:: How to get the distribution. * Extracting:: How to extract the distribution. * Distribution contents:: What is in the distribution.  File: gawk.info, Node: Getting, Next: Extracting, Prev: Gawk Distribution, Up: Gawk Distribution Getting the `gawk' Distribution ------------------------------- There are three ways you can get GNU software. 1. You can copy it from someone else who already has it. 2. You can order `gawk' directly from the Free Software Foundation. Software distributions are available for Unix, MS-DOS, and VMS, on tape and CD-ROM. The address is: Free Software Foundation 59 Temple Place--Suite 330 Boston, MA 02111-1307 USA Phone: +1-617-542-5942 Fax (including Japan): +1-617-542-2652 E-mail: `gnu@prep.ai.mit.edu' Ordering from the FSF directly contributes to the support of the foundation and to the production of more free software. 3. You can get `gawk' by using anonymous `ftp' to the Internet host `ftp.gnu.ai.mit.edu', in the directory `/pub/gnu'. Here is a list of alternate `ftp' sites from which you can obtain GNU software. When a site is listed as "SITE`:'DIRECTORY" the DIRECTORY indicates the directory where GNU software is kept. You should use a site that is geographically close to you. Asia: `cair-archive.kaist.ac.kr:/pub/gnu' `ftp.cs.titech.ac.jp' `ftp.nectec.or.th:/pub/mirrors/gnu' `utsun.s.u-tokyo.ac.jp:/ftpsync/prep' Australia: `archie.au:/gnu' (`archie.oz' or `archie.oz.au' for ACSnet) Africa: `ftp.sun.ac.za:/pub/gnu' Middle East: `ftp.technion.ac.il:/pub/unsupported/gnu' Europe: `archive.eu.net' `ftp.denet.dk' `ftp.eunet.ch' `ftp.funet.fi:/pub/gnu' `ftp.ieunet.ie:pub/gnu' `ftp.informatik.rwth-aachen.de:/pub/gnu' `ftp.informatik.tu-muenchen.de' `ftp.luth.se:/pub/unix/gnu' `ftp.mcc.ac.uk' `ftp.stacken.kth.se' `ftp.sunet.se:/pub/gnu' `ftp.univ-lyon1.fr:pub/gnu' `ftp.win.tue.nl:/pub/gnu' `irisa.irisa.fr:/pub/gnu' `isy.liu.se' `nic.switch.ch:/mirror/gnu' `src.doc.ic.ac.uk:/gnu' `unix.hensa.ac.uk:/pub/uunet/systems/gnu' South America: `ftp.inf.utfsm.cl:/pub/gnu' `ftp.unicamp.br:/pub/gnu' Western Canada: `ftp.cs.ubc.ca:/mirror2/gnu' USA: `col.hp.com:/mirrors/gnu' `f.ms.uky.edu:/pub3/gnu' `ftp.cc.gatech.edu:/pub/gnu' `ftp.cs.columbia.edu:/archives/gnu/prep' `ftp.digex.net:/pub/gnu' `ftp.hawaii.edu:/mirrors/gnu' `ftp.kpc.com:/pub/mirror/gnu' USA (continued): `ftp.uu.net:/systems/gnu' `gatekeeper.dec.com:/pub/GNU' `jaguar.utah.edu:/gnustuff' `labrea.stanford.edu' `mrcnext.cso.uiuc.edu:/pub/gnu' `vixen.cso.uiuc.edu:/gnu' `wuarchive.wustl.edu:/systems/gnu'  File: gawk.info, Node: Extracting, Next: Distribution contents, Prev: Getting, Up: Gawk Distribution Extracting the Distribution --------------------------- `gawk' is distributed as a `tar' file compressed with the GNU Zip program, `gzip'. Once you have the distribution (for example, `gawk-3.0.2.tar.gz'), first use `gzip' to expand the file, and then use `tar' to extract it. You can use the following pipeline to produce the `gawk' distribution: # Under System V, add 'o' to the tar flags gzip -d -c gawk-3.0.2.tar.gz | tar -xvpf - This will create a directory named `gawk-3.0.2' in the current directory. The distribution file name is of the form `gawk-V.R.N.tar.gz'. The V represents the major version of `gawk', the R represents the current release of version V, and the N represents a "patch level", meaning that minor bugs have been fixed in the release. The current patch level is 0, but when retrieving distributions, you should get the version with the highest version, release, and patch level. (Note that release levels greater than or equal to 90 denote "beta," or non-production software; you may not wish to retrieve such a version unless you don't mind experimenting.) If you are not on a Unix system, you will need to make other arrangements for getting and extracting the `gawk' distribution. You should consult a local expert.  File: gawk.info, Node: Distribution contents, Prev: Extracting, Up: Gawk Distribution Contents of the `gawk' Distribution ----------------------------------- The `gawk' distribution has a number of C source files, documentation files, subdirectories and files related to the configuration process (*note Compiling and Installing `gawk' on Unix: Unix Installation.), and several subdirectories related to different, non-Unix, operating systems. various `.c', `.y', and `.h' files These files are the actual `gawk' source code. `README' `README_d/README.*' Descriptive files: `README' for `gawk' under Unix, and the rest for the various hardware and software combinations. `INSTALL' A file providing an overview of the configuration and installation process. `PORTS' A list of systems to which `gawk' has been ported, and which have successfully run the test suite. `ACKNOWLEDGMENT' A list of the people who contributed major parts of the code or documentation. `ChangeLog' A detailed list of source code changes as bugs are fixed or improvements made. `NEWS' A list of changes to `gawk' since the last release or patch. `COPYING' The GNU General Public License. `FUTURES' A brief list of features and/or 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 one area where the POSIX standard for `awk' is incorrect, and how `gawk' handles the problem. `PROBLEMS' A file describing known problems with the current release. `doc/awkforai.txt' A short article describing why `gawk' is a good language for AI (Artificial Intelligence) programming. `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 to produce a printed document, and with `makeinfo' to produce an Info file. `doc/gawk.info' The generated Info file for this Info file. `doc/igawk.1' The `troff' source for a manual page describing the `igawk' program presented in *Note An Easy Way to Use Library Functions: Igawk Program.. `doc/Makefile.in' The input file used during the configuration process to generate the actual `Makefile' for creating the documentation. `Makefile.in' `acconfig.h' `aclocal.m4' `configh.in' `configure.in' `configure' `custom.h' `missing/*' These files and subdirectory are used when configuring `gawk' for various Unix systems. They are explained in detail in *Note Compiling and Installing `gawk' on Unix: Unix Installation.. `awklib/extract.awk' `awklib/Makefile.in' The `awklib' directory contains a copy of `extract.awk' (*note Extracting Programs from Texinfo Source Files: Extract Program.), which can be used to extract the sample programs from the Texinfo source file for this Info file, and a `Makefile.in' file, which `configure' uses to generate a `Makefile'. As part of the process of building `gawk', the library functions from *Note A Library of `awk' Functions: Library Functions., and the `igawk' program from *Note An Easy Way to Use Library Functions: Igawk Program., are extracted into ready to use files. They are installed as part of the installation process. `amiga/*' Files needed for building `gawk' on an Amiga. *Note Installing `gawk' on an Amiga: Amiga Installation, for details. `atari/*' Files needed for building `gawk' on an Atari ST. *Note Installing `gawk' on the Atari ST: Atari Installation, for details. `pc/*' Files needed for building `gawk' under MS-DOS and OS/2. *Note MS-DOS and OS/2 Installation and Compilation: PC Installation, for details. `vms/*' Files needed for building `gawk' under VMS. *Note How to Compile and Install `gawk' on VMS: 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: Unix Installation, Next: VMS Installation, Prev: Gawk Distribution, Up: Installation Compiling and Installing `gawk' on Unix ======================================= Usually, you can compile and install `gawk' by typing only two commands. However, if you do use an unusual system, you may need to configure `gawk' for your system yourself. * Menu: * Quick Installation:: Compiling `gawk' under Unix. * Configuration Philosophy:: How it's all supposed to work.  File: gawk.info, Node: Quick Installation, Next: Configuration Philosophy, Prev: Unix Installation, Up: Unix Installation Compiling `gawk' for Unix ------------------------- After you have extracted the `gawk' distribution, `cd' to `gawk-3.0.2'. Like most GNU software, `gawk' is configured automatically for your Unix system by running the `configure' program. This program is a Bourne shell script that was generated automatically using GNU `autoconf'. (The `autoconf' software is described fully starting with *Note Introduction: (autoconf)Top..) To configure `gawk', simply run `configure': sh ./configure This produces a `Makefile' and `config.h' tailored to your system. The `config.h' file describes various facts about your system. You may wish 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). Alternatively, you can add your own values for most `make' variables, such as `CC' and `CFLAGS', on the command line when running `configure': CC=cc CFLAGS=-g sh ./configure See the file `INSTALL' in the `gawk' distribution for all the details. After you have run `configure', and possibly edited the `Makefile', type: make and shortly thereafter, you should have an executable version of `gawk'. That's all there is to it! (If these steps do not work, please send in a bug report; *note Reporting Problems and Bugs: Bugs..)  File: gawk.info, Node: Configuration Philosophy, Prev: Quick Installation, Up: Unix Installation The Configuration Process ------------------------- (This section is of interest only if you know something about using the C language and the Unix operating system.) 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 ANSI C standard and by the POSIX operating system interface standard. When using an ANSI C compiler, function prototypes are used to help improve the compile-time checking. Many Unix systems do not support all of either the ANSI or the POSIX standards. The `missing' subdirectory in the `gawk' distribution contains replacement versions of those subroutines that are most likely to be missing. The `config.h' file that is created by the `configure' program 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 other miscellaneous facts about your variant of Unix. For example, there may not be an `st_blksize' element in the `stat' structure. In this case `HAVE_ST_BLKSIZE' would be undefined. 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, you can 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'. 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.in' is the input for `autoconf'. You may be able to change this file, and generate a new version of `configure' that will work on your system. *Note Reporting Problems and Bugs: Bugs, for information on how to report problems in configuring `gawk'. The same mechanism may be used to send in updates to `configure.in' and/or `custom.h'.  File: gawk.info, Node: VMS Installation, Next: PC Installation, Prev: Unix Installation, Up: Installation How to Compile and Install `gawk' on VMS ======================================== This section describes how to compile and install `gawk' under VMS. * 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 POSIX:: Alternate instructions for VMS POSIX.  File: gawk.info, Node: VMS Compilation, Next: VMS Installation Details, Prev: VMS Installation, Up: VMS Installation Compiling `gawk' on VMS ----------------------- To compile `gawk' under VMS, there is a `DCL' command procedure that will issue all the necessary `CC' and `LINK' commands, and there is also a `Makefile' for use with the `MMS' utility. From the source directory, use either $ @[.VMS]VMSBUILD.COM or $ MMS/DESCRIPTION=[.VMS]DESCRIP.MMS GAWK Depending upon which C compiler you are using, follow one of the sets of instructions in this table: VAX C V3.x Use either `vmsbuild.com' or `descrip.mms' as is. These use `CC/OPTIMIZE=NOLINE', which is essential for Version 3.0. VAX C V2.x You must have Version 2.3 or 2.4; older ones won't work. Edit either `vmsbuild.com' or `descrip.mms' according to the comments in them. For `vmsbuild.com', this just entails removing two `!' delimiters. Also edit `config.h' (which is a copy of file `[.config]vms-conf.h') and comment out or delete the two lines `#define __STDC__ 0' and `#define VAXC_BUILTINS' near the end. GNU C Edit `vmsbuild.com' or `descrip.mms'; the changes are different from those for VAX C V2.x, but equally straightforward. No changes to `config.h' should be needed. DEC C Edit `vmsbuild.com' or `descrip.mms' according to their comments. No changes to `config.h' should be needed. `gawk' has been tested under VAX/VMS 5.5-1 using VAX C V3.2, GNU C 1.40 and 2.3. It should work without modifications for VMS V4.6 and up.  File: gawk.info, Node: VMS Installation Details, Next: VMS Running, Prev: VMS Compilation, Up: VMS Installation Installing `gawk' on VMS ------------------------ To install `gawk', all you need is a "foreign" command, which is a `DCL' symbol whose value begins with a dollar sign. For example: $ GAWK :== $disk1:[gnubin]GAWK (Substitute the actual location of `gawk.exe' for `$disk1:[gnubin]'.) The symbol should be placed in the `login.com' of any user who wishes to run `gawk', so that it will be defined every time the user logs on. Alternatively, the symbol may be placed in the system-wide `sylogin.com' procedure, which will allow all users to run `gawk'. Optionally, the help entry can be loaded into a VMS help library: $ LIBRARY/HELP SYS$HELP:HELPLIB [.VMS]GAWK.HLP (You may want to substitute a site-specific help library rather than the standard VMS library `HELPLIB'.) After loading the help text, $ HELP GAWK will provide information about both the `gawk' implementation and the `awk' programming language. The logical name `AWK_LIBRARY' can designate a default location for `awk' program files. For the `-f' option, if the specified filename has no device or directory path information in it, `gawk' will look in the current directory first, then in the directory specified by the translation of `AWK_LIBRARY' if the file was not found. If after searching in both directories, the file still is not found, then `gawk' appends the suffix `.awk' to the filename and the file search will be re-tried. If `AWK_LIBRARY' is not defined, that portion of the file search will fail benignly.  File: gawk.info, Node: VMS Running, Next: VMS POSIX, Prev: VMS Installation Details, Up: VMS Installation Running `gawk' on VMS --------------------- 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. Here are a couple of trivial tests: $ gawk -- "BEGIN {print ""Hello, World!""}" $ gawk -"W" version ! could also be -"W version" or "-W version" Note that upper-case and mixed-case text must be quoted. 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 rather than `DCL' parsing. If any other dash-type options (or multiple parameters such as data files to be processed) are present, there is no ambiguity and `--' can be omitted. 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 multi-translation `RMS' searchlist.  File: gawk.info, Node: VMS POSIX, Prev: VMS Running, Up: VMS Installation Building and Using `gawk' on VMS POSIX -------------------------------------- Ignore the instructions above, although `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 file system. Make sure that the two scripts, `configure' and `vms/posix-cc.sh', are executable; use `chmod +x' on them if necessary. Then execute the following two commands: psx> CC=vms/posix-cc.sh configure psx> make CC=c89 gawk The first command will construct files `config.h' and `Makefile' out of templates, using a script to make the C compiler fit `configure''s expectations. The second command will compile and link `gawk' using the C compiler directly; ignore any warnings from `make' about being unable to redefine `CC'. `configure' will take a very long time to execute, but at least it provides incremental feedback as it runs. This has been tested with VAX/VMS V6.2, VMS POSIX V2.0, and DEC C V5.2. Once built, `gawk' will work like any other shell utility. Unlike the normal VMS port of `gawk', no special command line manipulation is needed in the VMS POSIX environment.  File: gawk.info, Node: PC Installation, Next: Atari Installation, Prev: VMS Installation, Up: Installation MS-DOS and OS/2 Installation and Compilation ============================================ If you have received a binary distribution prepared by the DOS maintainers, then `gawk' and the necessary support files will 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, but 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. The binary distribution will contain a separate file describing the contents. In particular, it may include more than one version of the `gawk' executable. OS/2 binary distributions may have a different arrangement, but installation is similar. The OS/2 and MS-DOS versions of `gawk' search for program files as described in *Note The `AWKPATH' Environment Variable: 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 is `".;c:/lib/awk;c:/gnu/lib/awk"'. An `sh'-like shell (as opposed to `command.com' under MS-DOS or `cmd.exe' under OS/2) may be useful for `awk' programming. Ian Stewartson has written an excellent shell for MS-DOS and OS/2, and a `ksh' clone and GNU Bash are available for OS/2. The file `README_d/README.pc' in the `gawk' distribution contains information on these shells. Users of Stewartson's shell on DOS should examine its documentation on handling of command-lines. In particular, the setting for `gawk' in the shell configuration may need to be changed, and the `ignoretype' option may also be of interest. `gawk' can be compiled for MS-DOS and OS/2 using the GNU development tools from DJ Delorie (DJGPP, MS-DOS-only) or Eberhard Mattes (EMX, MS-DOS and OS/2). Microsoft C can be used to build 16-bit versions for MS-DOS and OS/2. The file `README_d/README.pc' in the `gawk' distribution contains additional notes, and `pc/Makefile' contains important notes on compilation options. To build `gawk', copy the files in the `pc' directory (*except* for `ChangeLog') to the directory with the rest of the `gawk' sources. The `Makefile' contains a configuration section with comments, and may need to be edited in order to work with your `make' utility. The `Makefile' contains a number of targets for building various MS-DOS and OS/2 versions. A list of targets will be printed if the `make' command is given without a target. As an example, to build `gawk' using the DJGPP tools, enter `make djgpp'. 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 DOS-style end-of-line markers. Most of the tests will 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 the file `pc/Makefile.tst' be copied to `test/Makefile' as a replacement. Details can be found in `README_d/README.pc'.  File: gawk.info, Node: Atari Installation, Next: Amiga Installation, Prev: PC Installation, Up: Installation Installing `gawk' on the Atari ST ================================= There are no substantial differences when installing `gawk' on various Atari models. Compiled `gawk' executables do not require a large amount of memory with most `awk' programs and should run on all Motorola processor based models (called further ST, even if that is not exactly right). In order to use `gawk', you need to have a shell, either text or graphics, that does not map all the characters of a command line to upper-case. Maintaining case distinction in option flags is very important (*note Command Line Options: Options.). These days this is the default, and it may only be a problem for some very old machines. If your system does not preserve the case of option flags, you will need to upgrade your tools. Support for I/O redirection is necessary to make it easy to import `awk' programs from other environments. Pipes are nice to have, but not vital. * Menu: * Atari Compiling:: Compiling `gawk' on Atari * Atari Using:: Running `gawk' on Atari  File: gawk.info, Node: Atari Compiling, Next: Atari Using, Prev: Atari Installation, Up: Atari Installation Compiling `gawk' on the Atari ST -------------------------------- A proper compilation of `gawk' sources when `sizeof(int)' differs from `sizeof(void *)' requires an ANSI C compiler. An initial port was done with `gcc'. You may actually prefer executables where `int's are four bytes wide, but the other variant works as well. You may need quite a bit of memory when trying to recompile the `gawk' sources, as some source files (`regex.c' in particular) are quite big. If you run out of memory compiling such a file, try reducing the optimization level for this particular file; this may help. With a reasonable shell (Bash will do), and in particular if you run Linux, MiNT or a similar operating system, you have a pretty good chance that the `configure' utility will succeed. Otherwise sample versions of `config.h' and `Makefile.st' are given in the `atari' subdirectory and can be edited and copied to the corresponding files in the main source directory. Even if `configure' produced something, it might be advisable to compare its results with the sample versions and possibly make adjustments. Some `gawk' source code fragments depend on a preprocessor define `atarist'. This basically assumes the TOS environment with `gcc'. Modify these sections as appropriate if they are not right for your environment. Also see the remarks about `AWKPATH' and `envsep' in *Note Running `gawk' on the Atari ST: Atari Using.. As shipped, the sample `config.h' claims that the `system' function is missing from the libraries, which is not true, and an alternative implementation of this function is provided in `atari/system.c'. Depending upon your particular combination of shell and operating system, you may wish to change the file to indicate that `system' is available.  File: gawk.info, Node: Atari Using, Prev: Atari Compiling, Up: Atari Installation Running `gawk' on the Atari ST ------------------------------ An executable version of `gawk' should be placed, as usual, anywhere in your `PATH' where your shell can find it. While executing, `gawk' creates a number of temporary files. When using `gcc' libraries for TOS, `gawk' looks for either of the environment variables `TEMP' or `TMPDIR', in that order. If either one is found, its value is assumed to be a directory for temporary files. This directory must exist, and if you can spare the memory, it is a good idea to put it on a RAM drive. If neither `TEMP' nor `TMPDIR' are found, then `gawk' uses the current directory for its temporary files. The ST version of `gawk' searches for its program files as described in *Note The `AWKPATH' Environment Variable: AWKPATH Variable.. The default value for the `AWKPATH' variable is taken from `DEFPATH' defined in `Makefile'. The sample `gcc'/TOS `Makefile' for the ST in the distribution sets `DEFPATH' to `".,c:\lib\awk,c:\gnu\lib\awk"'. The search path can be modified by explicitly setting `AWKPATH' to whatever you wish. Note that colons cannot be used on the ST to separate elements in the `AWKPATH' variable, since they have another, reserved, meaning. Instead, you must use a comma to separate elements in the path. When recompiling, the separating character can be modified by initializing the `envsep' variable in `atari/gawkmisc.atr' to another value. Although `awk' allows great flexibility in doing I/O redirections from within a program, this facility should be used with care on the ST running under TOS. In some circumstances the OS routines for file handle pool processing lose track of certain events, causing the computer to crash, and requiring a reboot. Often a warm reboot is sufficient. Fortunately, this happens infrequently, and in rather esoteric situations. In particular, avoid having one part of an `awk' program using `print' statements explicitly redirected to `"/dev/stdout"', while other `print' statements use the default standard output, and a calling shell has redirected standard output to a file. When `gawk' is compiled with the ST version of `gcc' and its usual libraries, it will accept both `/' and `\' as path separators. While this is convenient, it should be remembered that this removes one, technically valid, character (`/') from your file names, and that it may create problems for external programs, called via the `system' function, which may not support this convention. Whenever it is possible that a file created by `gawk' will be used by some other program, use only backslashes. Also remember that in `awk', backslashes in strings have to be doubled in order to get literal backslashes (*note Escape Sequences::.).  File: gawk.info, Node: Amiga Installation, Next: Bugs, Prev: Atari Installation, Up: Installation Installing `gawk' on an Amiga ============================= You can install `gawk' on an Amiga system using a Unix emulation environment available via anonymous `ftp' from `ftp.ninemoons.com' in the directory `pub/ade/current'. This includes a shell based on `pdksh'. The primary component of this environment is a Unix emulation library, `ixemul.lib'. A more complete distribution for the Amiga is available on the Geek Gadgets CD-ROM from: CRONUS 1840 E. Warner Road #105-265 Tempe, AZ 85284 USA US Toll Free: (800) 804-0833 Phone: +1-602-491-0442 FAX: +1-602-491-0048 Email: `info@ninemoons.com' WWW: `http://www.ninemoons.com' Anonymous `ftp' site: `ftp.ninemoons.com' Once you have the distribution, you can configure `gawk' simply by running `configure': configure -v m68k-amigaos Then run `make', and you should be all set! (If these steps do not work, please send in a bug report; *note Reporting Problems and Bugs: Bugs..)  File: gawk.info, Node: Bugs, Next: Other Versions, Prev: Amiga Installation, Up: Installation Reporting Problems and Bugs =========================== 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. 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! 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, and the exact results `gawk' gave you. Also say what you expected to occur; this will help us decide whether the problem was really in the documentation. Once you have a precise problem, there are two e-mail addresses you can send mail to. Internet: `bug-gnu-utils@prep.ai.mit.edu' UUCP: `uunet!prep.ai.mit.edu!bug-gnu-utils' Please include the version number of `gawk' you are using. You can get this information with the command `gawk --version'. You should send a carbon copy of your mail to Arnold Robbins, who can be reached at `arnold@gnu.ai.mit.edu'. *Important!* 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. 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 Arnold Robbins; he will try to help you out, although he may not have the time to fix the problem. You can send him electronic mail at the Internet address above. 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 listed below, and also 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 people maintaining the non-Unix ports of `gawk' are: MS-DOS Scott Deifik, `scottd@amgen.com', and Darrel Hankerson, `hankedr@mail.auburn.edu'. OS/2 Kai Uwe Rommel, `rommel@ars.de'. VMS Pat Rankin, `rankin@eql.caltech.edu'. Atari ST Michal Jaegermann, `michal@gortel.phys.ualberta.ca'. Amiga Fred Fish, `fnf@ninemoons.com'. If your bug is also reproducible under Unix, please send copies of your report to the general GNU bug list, as well as to Arnold Robbins, at the addresses listed above.  File: gawk.info, Node: Other Versions, Prev: Bugs, Up: Installation Other Freely Available `awk' Implementations ============================================ It's kind of fun to put comments like this in your awk code. `// Do C++ comments work? answer: yes! of course' Michael Brennan There are two other freely available `awk' implementations. This section briefly describes where to get them. Unix `awk' Brian Kernighan has been able to make his implementation of `awk' freely available. You can get it via anonymous `ftp' to the host `netlib.att.com'. Change directory to `/netlib/research'. Use "binary" or "image" mode, and retrieve `awk.bundle.Z'. This is a shell archive that has been compressed with the `compress' utility. It can be uncompressed with either `uncompress' or the GNU `gunzip' utility. This version requires an ANSI C compiler; GCC (the GNU C compiler) works quite nicely. `mawk' Michael Brennan has written an independent implementation of `awk', called `mawk'. It is available under the GPL (*note GNU GENERAL PUBLIC LICENSE: Copying.), just as `gawk' is. You can get it via anonymous `ftp' to the host `ftp.whidbey.net'. Change directory to `/pub/brennan'. Use "binary" or "image" mode, and retrieve `mawk1.3.3.tar.gz' (or the latest version that is there). `gunzip' may be used to decompress this file. Installation is similar to `gawk''s (*note Compiling and Installing `gawk' on Unix: Unix Installation.).  File: gawk.info, Node: Notes, Next: Glossary, Prev: Installation, Up: Top Implementation Notes ******************** This appendix contains information mainly of interest to implementors and maintainers of `gawk'. Everything in it applies specifically to `gawk', and not to other implementations. * Menu: * Compatibility Mode:: How to disable certain `gawk' extensions. * Additions:: Making Additions To `gawk'. * Future Extensions:: New features that may be implemented one day. * Improvements:: Suggestions for improvements by volunteers.  File: gawk.info, Node: Compatibility Mode, Next: Additions, Prev: Notes, Up: Notes Downward Compatibility and Debugging ==================================== *Note Extensions in `gawk' Not in POSIX `awk': 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. If `gawk' is compiled for debugging with `-DDEBUG', then there is one more option available on the command line: `-W parsedebug' `--parsedebug' Print out the parse stack information as the program is being parsed. 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.  File: gawk.info, Node: Additions, Next: Future Extensions, Prev: Compatibility Mode, Up: Notes Making Additions to `gawk' ========================== If you should find that you wish 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 wish (*note GNU GENERAL PUBLIC LICENSE: Copying.). This section discusses the ways you might wish to change `gawk', and any considerations you should bear in mind. * Menu: * Adding Code:: Adding code to the main body of `gawk'. * New Ports:: Porting `gawk' to a new operating system.