aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/ChangeLog52
-rw-r--r--doc/Makefile.am7
-rw-r--r--doc/Makefile.in374
-rw-r--r--doc/awkcard.in206
-rw-r--r--doc/gawk.150
-rw-r--r--doc/gawk.info5214
-rw-r--r--doc/gawk.texi4774
-rw-r--r--doc/gawkinet.info522
-rw-r--r--doc/gawkinet.texi376
-rw-r--r--doc/texinfo.tex734
-rw-r--r--doc/uf002331.eps1155
-rw-r--r--doc/uf002331.jpgbin36796 -> 0 bytes
12 files changed, 7355 insertions, 6109 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog
index 79dac766..6223634f 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,55 @@
+Wed May 1 16:41:32 2002 Arnold D. Robbins <arnold@skeeve.com>
+
+ * Release 3.1.1: Release tar file made.
+
+Tue Apr 16 13:26:13 2002 Arnold D. Robbins <arnold@skeeve.com>
+
+ * gawk.texi: FINALLY. All O'Reilly production and
+ indexing changes integrated. Index reviewed and
+ cleaned up.
+ * gawkinet.texi: Ditto.
+ * awkcard.in: Redid page breaking.
+ * Makefile.am (clean): Add `awkcard.tr' to list of files
+ that are removed.
+ (distclean): Depend on clean to REALLY GET `awkcard.tr'.
+ Sheesh.
+
+Mon Apr 15 14:43:51 2002 Arnold D. Robbins <arnold@skeeve.com>
+
+ * texinfo.tex: Updated to version from Texinfo 4.2.
+ * gawk.texi: Modified to use new @copying command.
+ * gawkinet.texi: Ditto.
+
+Wed Mar 20 17:07:50 2002 Arnold D. Robbins <arnold@skeeve.com>
+
+ * texinfo.tex: Updated to version from Texinfo 4.1.
+
+2002-02-10 Paul Eggert <eggert@twinsun.com>
+
+ * gawk.texi (Word Sorting): Don't use sort +1, as POSIX 1003.1-2001
+ no longer allows it. Use sort -k instead.
+
+2002-01-27 Bruno Haible <bruno@clisp.org>
+
+ * gawk.texi: Document the dcngettext function.
+ * awkcard.in: Likewise.
+ * gawk.1: Likewise.
+
+Mon Jan 28 18:41:02 2002 Arnold D. Robbins <arnold@skeeve.com>
+
+ * gawkinet.texi, Makefile.am: Removed User Friendly cartoon.
+ Sigh.
+
+Wed Dec 19 16:00:39 2001 Eli Zaretskii <eliz@is.elta.co.il>
+
+ * gawk.texi (Profiling): Describe the signals used for profile
+ dumping in the DJGPP version.
+
+Mon Sep 3 18:30:13 2001 Arnold D. Robbins <arnold@skeeve.com>
+
+ * gawk.texi (Top): Put in @ifnottex so that makeinfo
+ --html is now happy.
+
Sun Jun 3 13:04:44 2001 Arnold D. Robbins <arnold@skeeve.com>
* Release 3.1.0: Release tar file made. And there was
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 3a9e4b44..93092a15 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,7 +1,7 @@
#
# doc/Makefile.am --- automake input file for gawk
#
-# Copyright (C) 2000, 2001 the Free Software Foundation, Inc.
+# Copyright (C) 2000, 2001, 2002 the Free Software Foundation, Inc.
#
# This file is part of GAWK, the GNU implementation of the
# AWK Programming Language.
@@ -30,7 +30,7 @@ man_MANS = gawk.1 igawk.1
EXTRA_DIST = ChangeLog README.card ad.block setter.outline \
awkcard.in awkforai.txt texinfo.tex cardfonts \
macros colors no.colors $(man_MANS) \
- uf002331.eps uf002331.jpg lflashlight.eps rflashlight.eps \
+ lflashlight.eps rflashlight.eps \
statist.jpg statist.eps
MAKEINFO = @MAKEINFO@ --no-split
@@ -76,5 +76,6 @@ awkcard.nc: $(CARDFILES)
$(TROFF) $(CARDSRC_N) | $(SEDME) | cat $(srcdir)/setter.outline - > awkcard.ps && touch awkcard.nc
clean:
- rm -f *.ps *~ awkcard.nc
+ rm -f *.ps *~ awkcard.nc awkcard.tr
+distclean: clean
diff --git a/doc/Makefile.in b/doc/Makefile.in
index 555450d2..8c38c91c 100644
--- a/doc/Makefile.in
+++ b/doc/Makefile.in
@@ -1,6 +1,6 @@
-# Makefile.in generated automatically by automake 1.4a from Makefile.am
+# Makefile.in generated automatically by automake 1.5 from Makefile.am.
-# Copyright 1994, 1995, 1996, 1997, 1998, 1999, 2000
+# Copyright 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001
# Free Software Foundation, Inc.
# This Makefile.in is free software; the Free Software Foundation
# gives unlimited permission to copy and/or distribute it,
@@ -11,6 +11,31 @@
# even the implied warranty of MERCHANTABILITY or FITNESS FOR A
# PARTICULAR PURPOSE.
+@SET_MAKE@
+
+#
+# doc/Makefile.am --- automake input file for gawk
+#
+# Copyright (C) 2000, 2001, 2002 the Free Software Foundation, Inc.
+#
+# This file is part of GAWK, the GNU implementation of the
+# AWK Programming Language.
+#
+# GAWK is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# GAWK is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
+#
+
SHELL = @SHELL@
srcdir = @srcdir@
@@ -31,11 +56,9 @@ infodir = @infodir@
mandir = @mandir@
includedir = @includedir@
oldincludedir = /usr/include
-
pkgdatadir = $(datadir)/@PACKAGE@
pkglibdir = $(libdir)/@PACKAGE@
pkgincludedir = $(includedir)/@PACKAGE@
-
top_builddir = ..
ACLOCAL = @ACLOCAL@
@@ -47,44 +70,47 @@ INSTALL = @INSTALL@
INSTALL_PROGRAM = @INSTALL_PROGRAM@
INSTALL_DATA = @INSTALL_DATA@
INSTALL_SCRIPT = @INSTALL_SCRIPT@
-INSTALL_STRIP_FLAG =
+INSTALL_HEADER = $(INSTALL_DATA)
transform = @program_transform_name@
-
NORMAL_INSTALL = :
PRE_INSTALL = :
POST_INSTALL = :
NORMAL_UNINSTALL = :
PRE_UNINSTALL = :
POST_UNINSTALL = :
-
-@SET_MAKE@
-AMDEP = @AMDEP@
+host_alias = @host_alias@
+host_triplet = @host@
AMTAR = @AMTAR@
AWK = @AWK@
-CATALOGS = @CATALOGS@
+BUILD_INCLUDED_LIBINTL = @BUILD_INCLUDED_LIBINTL@
CATOBJEXT = @CATOBJEXT@
CC = @CC@
CFLAGS = @CFLAGS@
CPP = @CPP@
-CXX = @CXX@
-CXXCPP = @CXXCPP@
DATADIRNAME = @DATADIRNAME@
DEPDIR = @DEPDIR@
+EXEEXT = @EXEEXT@
GENCAT = @GENCAT@
-GMOFILES = @GMOFILES@
+GLIBC21 = @GLIBC21@
GMSGFMT = @GMSGFMT@
-GT_NO = @GT_NO@
-GT_YES = @GT_YES@
-INCLUDE_LOCALE_H = @INCLUDE_LOCALE_H@
+HAVE_LIB = @HAVE_LIB@
+INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@
INSTOBJEXT = @INSTOBJEXT@
-INTLDEPS = @INTLDEPS@
+INTLBISON = @INTLBISON@
INTLLIBS = @INTLLIBS@
INTLOBJS = @INTLOBJS@
+INTL_LIBTOOL_SUFFIX_PREFIX = @INTL_LIBTOOL_SUFFIX_PREFIX@
+LIB = @LIB@
+LIBICONV = @LIBICONV@
+LIBINTL = @LIBINTL@
LN_S = @LN_S@
+LTLIB = @LTLIB@
+LTLIBICONV = @LTLIBICONV@
+LTLIBINTL = @LTLIBINTL@
MKINSTALLDIRS = @MKINSTALLDIRS@
-MSGFMT = @MSGFMT@
+OBJEXT = @OBJEXT@
PACKAGE = @PACKAGE@
-POFILES = @POFILES@
+PATH_SEPARATOR = @PATH_SEPARATOR@
POSUB = @POSUB@
RANLIB = @RANLIB@
SOCKET_LIBS = @SOCKET_LIBS@
@@ -93,32 +119,9 @@ USE_INCLUDED_LIBINTL = @USE_INCLUDED_LIBINTL@
USE_NLS = @USE_NLS@
VERSION = @VERSION@
YACC = @YACC@
+am__include = @am__include@
+am__quote = @am__quote@
install_sh = @install_sh@
-l = @l@
-
-#
-# doc/Makefile.am --- automake input file for gawk
-#
-# Copyright (C) 2000, 2001 the Free Software Foundation, Inc.
-#
-# This file is part of GAWK, the GNU implementation of the
-# AWK Programming Language.
-#
-# GAWK is free software; you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation; either version 2 of the License, or
-# (at your option) any later version.
-#
-# GAWK is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with this program; if not, write to the Free Software
-# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
-#
-
info_TEXINFOS = gawk.texi gawkinet.texi
@@ -127,7 +130,7 @@ man_MANS = gawk.1 igawk.1
EXTRA_DIST = ChangeLog README.card ad.block setter.outline \
awkcard.in awkforai.txt texinfo.tex cardfonts \
macros colors no.colors $(man_MANS) \
- uf002331.eps uf002331.jpg lflashlight.eps rflashlight.eps \
+ lflashlight.eps rflashlight.eps \
statist.jpg statist.eps
@@ -146,113 +149,59 @@ CARDFILES = $(CARDSRC) ad.block awkcard.in setter.outline
AWKCARD = awkcard.ps
subdir = doc
mkinstalldirs = $(SHELL) $(top_srcdir)/mkinstalldirs
-CONFIG_HEADER = ../config.h
-CONFIG_CLEAN_FILES =
-DIST_SOURCES =
-TEXI2DVI = texi2dvi
+CONFIG_HEADER = $(top_builddir)/config.h
+CONFIG_CLEAN_FILES =
+DIST_SOURCES =
INFO_DEPS = gawk.info gawkinet.info
DVIS = gawk.dvi gawkinet.dvi
TEXINFOS = gawk.texi gawkinet.texi
-man1dir = $(mandir)/man1
-MANS = $(man_MANS)
NROFF = nroff
-DIST_COMMON = ChangeLog Makefile.am Makefile.in texinfo.tex
-
-
-DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
+MANS = $(man_MANS)
+DIST_COMMON = ChangeLog Makefile.am Makefile.in texinfo.tex
+all: all-am
-GZIP_ENV = --best
-all: all-redirect
.SUFFIXES:
-.SUFFIXES: .dvi .info .ps .texi .texinfo .txi
-$(srcdir)/Makefile.in: Makefile.am $(top_srcdir)/configure.in $(ACLOCAL_M4)
- cd $(top_srcdir) && $(AUTOMAKE) --gnu doc/Makefile
-
-Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status
- cd $(top_builddir) \
- && CONFIG_FILES=$(subdir)/$@ CONFIG_HEADERS= $(SHELL) ./config.status
-
+.SUFFIXES: .dvi .info .ps .texi
+$(srcdir)/Makefile.in: Makefile.am $(top_srcdir)/configure.in $(ACLOCAL_M4)
+ cd $(top_srcdir) && \
+ $(AUTOMAKE) --gnu doc/Makefile
+Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status
+ cd $(top_builddir) && \
+ CONFIG_HEADERS= CONFIG_LINKS= \
+ CONFIG_FILES=$(subdir)/$@ $(SHELL) ./config.status
gawk.info: gawk.texi
gawk.dvi: gawk.texi
-
gawkinet.info: gawkinet.texi
gawkinet.dvi: gawkinet.texi
-
-DVIPS = dvips
-
.texi.info:
@cd $(srcdir) && rm -f $@ $@-[0-9] $@-[0-9][0-9]
cd $(srcdir) \
- && $(MAKEINFO) `echo $< | sed 's,.*/,,'`
+ && $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) \
+ `echo $< | sed 's,.*/,,'`
.texi.dvi:
TEXINPUTS=$(srcdir):$$TEXINPUTS \
- MAKEINFO='$(MAKEINFO) -I $(srcdir)' $(TEXI2DVI) $<
+ MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \
+ $(TEXI2DVI) $<
.texi:
@cd $(srcdir) && rm -f $@ $@-[0-9] $@-[0-9][0-9]
cd $(srcdir) \
- && $(MAKEINFO) `echo $< | sed 's,.*/,,'`
-
-.texinfo.info:
- @cd $(srcdir) && rm -f $@ $@-[0-9] $@-[0-9][0-9]
- cd $(srcdir) \
- && $(MAKEINFO) `echo $< | sed 's,.*/,,'`
-
-.texinfo:
- @cd $(srcdir) && rm -f $@ $@-[0-9] $@-[0-9][0-9]
- cd $(srcdir) \
- && $(MAKEINFO) `echo $< | sed 's,.*/,,'`
-
-.texinfo.dvi:
- TEXINPUTS=$(srcdir):$$TEXINPUTS \
- MAKEINFO='$(MAKEINFO) -I $(srcdir)' $(TEXI2DVI) $<
-
-.txi.info:
- @cd $(srcdir) && rm -f $@ $@-[0-9] $@-[0-9][0-9]
- cd $(srcdir) \
- && $(MAKEINFO) `echo $< | sed 's,.*/,,'`
-
-.txi.dvi:
- TEXINPUTS=$(srcdir):$$TEXINPUTS \
- MAKEINFO='$(MAKEINFO) -I $(srcdir)' $(TEXI2DVI) $<
-
-.txi:
- @cd $(srcdir) && rm -f $@ $@-[0-9] $@-[0-9][0-9]
- cd $(srcdir) \
- && $(MAKEINFO) `echo $< | sed 's,.*/,,'`
+ && $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) \
+ `echo $< | sed 's,.*/,,'`
+TEXI2DVI = texi2dvi
+DVIPS = dvips
.dvi.ps:
$(DVIPS) $< -o $@
-install-info-am: $(INFO_DEPS)
- @$(NORMAL_INSTALL)
- $(mkinstalldirs) $(DESTDIR)$(infodir)
- @list='$(INFO_DEPS)'; \
- for file in $$list; do \
- d=$(srcdir); \
- for ifile in `CDPATH=: && cd $$d && echo $$file $$file-[0-9] $$file-[0-9][0-9]`; do \
- if test -f $$d/$$ifile; then \
- echo " $(INSTALL_DATA) $$d/$$ifile $(DESTDIR)$(infodir)/$$ifile"; \
- $(INSTALL_DATA) $$d/$$ifile $(DESTDIR)$(infodir)/$$ifile; \
- else : ; fi; \
- done; \
- done
- @$(POST_INSTALL)
- @if $(SHELL) -c 'install-info --version | sed 1q | fgrep -s -v -i debian' >/dev/null 2>&1; then \
- list='$(INFO_DEPS)'; \
- for file in $$list; do \
- echo " install-info --info-dir=$(DESTDIR)$(infodir) $(DESTDIR)$(infodir)/$$file";\
- install-info --info-dir=$(DESTDIR)$(infodir) $(DESTDIR)$(infodir)/$$file || :;\
- done; \
- else : ; fi
-
-uninstall-info:
+uninstall-info-am:
$(PRE_UNINSTALL)
- @if $(SHELL) -c 'install-info --version | sed 1q | fgrep -s -v -i debian' >/dev/null 2>&1; then \
+ @if (install-info --version && \
+ install-info --version | fgrep -i -v debian) >/dev/null 2>&1; then \
list='$(INFO_DEPS)'; \
for file in $$list; do \
echo " install-info --info-dir=$(DESTDIR)$(infodir) --remove $(DESTDIR)$(infodir)/$$file"; \
@@ -279,32 +228,28 @@ dist-info: $(INFO_DEPS)
done
mostlyclean-aminfo:
- -rm -f gawk.aux gawk.cp gawk.cps gawk.dvi gawk.fn gawk.fns gawk.pgs \
- gawk.ky gawk.kys gawk.ps gawk.log gawk.pg gawk.toc gawk.tp \
- gawk.tps gawk.vr gawk.vrs gawk.op gawk.tr gawk.cv gawk.cn \
- gawk.cm gawk.ov gawkinet.aux gawkinet.cp gawkinet.cps \
- gawkinet.dvi gawkinet.fn gawkinet.fns gawkinet.pgs \
- gawkinet.ky gawkinet.kys gawkinet.ps gawkinet.log gawkinet.pg \
- gawkinet.toc gawkinet.tp gawkinet.tps gawkinet.vr \
- gawkinet.vrs gawkinet.op gawkinet.tr gawkinet.cv gawkinet.cn \
- gawkinet.cm gawkinet.ov
-
-clean-aminfo:
-
-distclean-aminfo:
+ -rm -f gawk.aux gawk.cp gawk.cps gawk.dvi gawk.fn gawk.ky gawk.log gawk.pg \
+ gawk.ps gawk.toc gawk.tp gawk.vr gawkinet.aux gawkinet.cp \
+ gawkinet.cps gawkinet.dvi gawkinet.fn gawkinet.ky \
+ gawkinet.log gawkinet.pg gawkinet.ps gawkinet.toc gawkinet.tp \
+ gawkinet.vr
maintainer-clean-aminfo:
- cd $(srcdir) && for i in $(INFO_DEPS); do \
+ cd $(srcdir) && \
+ for i in $(INFO_DEPS); do \
rm -f $$i; \
if test "`echo $$i-[0-9]*`" != "$$i-[0-9]*"; then \
rm -f $$i-[0-9]*; \
fi; \
done
-install-man1:
+man1dir = $(mandir)/man1
+install-man1: $(man1_MANS) $(man_MANS)
+ @$(NORMAL_INSTALL)
$(mkinstalldirs) $(DESTDIR)$(man1dir)
- @list='$(man1_MANS)'; \
- l2='$(man_MANS)'; for i in $$l2; do \
+ @list='$(man1_MANS) $(dist_man1_MANS) $(nodist_man1_MANS)'; \
+ l2='$(man_MANS) $(dist_man_MANS) $(nodist_man_MANS)'; \
+ for i in $$l2; do \
case "$$i" in \
*.1*) list="$$list $$i" ;; \
esac; \
@@ -319,10 +264,11 @@ install-man1:
echo " $(INSTALL_DATA) $$file $(DESTDIR)$(man1dir)/$$inst"; \
$(INSTALL_DATA) $$file $(DESTDIR)$(man1dir)/$$inst; \
done
-
uninstall-man1:
- @list='$(man1_MANS)'; \
- l2='$(man_MANS)'; for i in $$l2; do \
+ @$(NORMAL_UNINSTALL)
+ @list='$(man1_MANS) $(dist_man1_MANS) $(nodist_man1_MANS)'; \
+ l2='$(man_MANS) $(dist_man_MANS) $(nodist_man_MANS)'; \
+ for i in $$l2; do \
case "$$i" in \
*.1*) list="$$list $$i" ;; \
esac; \
@@ -335,21 +281,22 @@ uninstall-man1:
echo " rm -f $(DESTDIR)$(man1dir)/$$inst"; \
rm -f $(DESTDIR)$(man1dir)/$$inst; \
done
-install-man: $(MANS)
- @$(NORMAL_INSTALL)
- $(MAKE) $(AM_MAKEFLAGS) install-man1
-uninstall-man:
- @$(NORMAL_UNINSTALL)
- $(MAKE) $(AM_MAKEFLAGS) uninstall-man1
tags: TAGS
TAGS:
-distdir = $(top_builddir)/$(PACKAGE)-$(VERSION)/$(subdir)
+DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
+
+top_distdir = ..
+distdir = $(top_distdir)/$(PACKAGE)-$(VERSION)
distdir: $(DISTFILES)
@for file in $(DISTFILES); do \
- d=$(srcdir); \
+ if test -f $$file; then d=.; else d=$(srcdir); fi; \
+ dir=`echo "$$file" | sed -e 's,/[^/]*$$,,'`; \
+ if test "$$dir" != "$$file" && test "$$dir" != "."; then \
+ $(mkinstalldirs) "$(distdir)/$$dir"; \
+ fi; \
if test -d $$d/$$file; then \
cp -pR $$d/$$file $(distdir) \
|| exit 1; \
@@ -359,71 +306,109 @@ distdir: $(DISTFILES)
|| exit 1; \
fi; \
done
- $(MAKE) $(AM_MAKEFLAGS) top_distdir="$(top_distdir)" distdir="$(distdir)" dist-info
-info-am: $(INFO_DEPS)
-info: info-am
-dvi-am: $(DVIS)
-dvi: dvi-am
+ $(MAKE) $(AM_MAKEFLAGS) \
+ top_distdir="${top_distdir}" distdir="$(distdir)" \
+ dist-info
check-am: all-am
check: check-am
-installcheck-am:
-installcheck: installcheck-am
-install-exec-am:
-install-exec: install-exec-am
+all-am: Makefile $(INFO_DEPS) $(MANS)
-install-data-am: install-info-am install-man
-install-data: install-data-am
+installdirs:
+ $(mkinstalldirs) $(DESTDIR)$(infodir) $(DESTDIR)$(man1dir)
-install-am: all-am
- @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am
install: install-am
-uninstall-am: uninstall-info uninstall-man
+install-exec: install-exec-am
+install-data: install-data-am
uninstall: uninstall-am
-all-am: Makefile $(INFO_DEPS) $(MANS)
-all-redirect: all-am
-install-strip:
- $(MAKE) $(AM_MAKEFLAGS) INSTALL_STRIP_FLAG=-s install
-installdirs:
- $(mkinstalldirs) $(DESTDIR)$(infodir) $(DESTDIR)$(mandir)/man1
+install-am: all-am
+ @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am
+installcheck: installcheck-am
+install-strip:
+ $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
+ `test -z '$(STRIP)' || \
+ echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install
mostlyclean-generic:
clean-generic:
distclean-generic:
- -rm -f Makefile $(CONFIG_CLEAN_FILES)
- -rm -f config.cache config.log stamp-h stamp-h[0-9]*
+ -rm -f Makefile $(CONFIG_CLEAN_FILES) stamp-h stamp-h[0-9]*
maintainer-clean-generic:
- -rm -f Makefile.in
-mostlyclean-am: mostlyclean-aminfo mostlyclean-generic
+ @echo "This command is intended for maintainers to use"
+ @echo "it deletes files that may require special tools to rebuild."
+clean: clean-am
-mostlyclean: mostlyclean-am
+clean-am: clean-generic mostlyclean-am
-clean-am: clean-aminfo clean-generic mostlyclean-am
+distclean: distclean-am
-clean: clean-am
+distclean-am: clean-am distclean-generic
+
+dvi: dvi-am
-distclean-am: distclean-aminfo distclean-generic clean-am
+dvi-am: $(DVIS)
-distclean: distclean-am
+info: info-am
-maintainer-clean-am: maintainer-clean-aminfo maintainer-clean-generic \
- distclean-am
- @echo "This command is intended for maintainers to use;"
- @echo "it deletes files that may require special tools to rebuild."
+info-am: $(INFO_DEPS)
+
+install-data-am: install-info-am install-man
+
+install-exec-am:
+
+install-info: install-info-am
+
+install-info-am: $(INFO_DEPS)
+ @$(NORMAL_INSTALL)
+ $(mkinstalldirs) $(DESTDIR)$(infodir)
+ @list='$(INFO_DEPS)'; \
+ for file in $$list; do \
+ d=$(srcdir); \
+ for ifile in `CDPATH=: && cd $$d && echo $$file $$file-[0-9] $$file-[0-9][0-9]`; do \
+ if test -f $$d/$$ifile; then \
+ echo " $(INSTALL_DATA) $$d/$$ifile $(DESTDIR)$(infodir)/$$ifile"; \
+ $(INSTALL_DATA) $$d/$$ifile $(DESTDIR)$(infodir)/$$ifile; \
+ else : ; fi; \
+ done; \
+ done
+ @$(POST_INSTALL)
+ @if (install-info --version && \
+ install-info --version | fgrep -i -v debian) >/dev/null 2>&1; then \
+ list='$(INFO_DEPS)'; \
+ for file in $$list; do \
+ echo " install-info --info-dir=$(DESTDIR)$(infodir) $(DESTDIR)$(infodir)/$$file";\
+ install-info --info-dir=$(DESTDIR)$(infodir) $(DESTDIR)$(infodir)/$$file || :;\
+ done; \
+ else : ; fi
+install-man: install-man1
+
+installcheck-am:
maintainer-clean: maintainer-clean-am
-.PHONY: install-info-am uninstall-info mostlyclean-aminfo \
-distclean-aminfo clean-aminfo maintainer-clean-aminfo install-man1 \
-uninstall-man1 install-man uninstall-man tags distdir info-am info \
-dvi-am dvi check check-am installcheck-am installcheck install-exec-am \
-install-exec install-data-am install-data install-am install \
-uninstall-am uninstall all-redirect all-am all install-strip \
-installdirs mostlyclean-generic distclean-generic clean-generic \
-maintainer-clean-generic clean mostlyclean distclean maintainer-clean
+maintainer-clean-am: distclean-am maintainer-clean-aminfo \
+ maintainer-clean-generic
+
+mostlyclean: mostlyclean-am
+
+mostlyclean-am: mostlyclean-aminfo mostlyclean-generic
+
+uninstall-am: uninstall-info-am uninstall-man
+
+uninstall-man: uninstall-man1
+
+.PHONY: all all-am check check-am clean clean-generic dist-info \
+ distclean distclean-generic distdir dvi dvi-am info info-am \
+ install install-am install-data install-data-am install-exec \
+ install-exec-am install-info install-info-am install-man \
+ install-man1 install-strip installcheck installcheck-am \
+ installdirs maintainer-clean maintainer-clean-aminfo \
+ maintainer-clean-generic mostlyclean mostlyclean-aminfo \
+ mostlyclean-generic uninstall uninstall-am uninstall-info-am \
+ uninstall-man uninstall-man1
# Uncomment the following definition of AWKCARD if your troff can produce
@@ -456,8 +441,9 @@ awkcard.nc: $(CARDFILES)
$(TROFF) $(CARDSRC_N) | $(SEDME) | cat $(srcdir)/setter.outline - > awkcard.ps && touch awkcard.nc
clean:
- rm -f *.ps *~ awkcard.nc
+ rm -f *.ps *~ awkcard.nc awkcard.tr
+distclean: clean
# Tell versions [3.59,3.63) of GNU make to not export all variables.
# Otherwise a system limit (for SysV at least) may be exceeded.
.NOEXPORT:
diff --git a/doc/awkcard.in b/doc/awkcard.in
index 43f73fb8..be6a7caa 100644
--- a/doc/awkcard.in
+++ b/doc/awkcard.in
@@ -1,6 +1,6 @@
.\" AWK Reference Card --- Arnold Robbins, arnold@gnu.org
.\"
-.\" Copyright (C) 1996-2001 Free Software Foundation, Inc.
+.\" Copyright (C) 1996, 1997, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
.\"
.\" Permission is granted to make and distribute verbatim copies of
.\" this reference card provided the copyright notice and this permission
@@ -57,15 +57,15 @@ Command Line Arguments (\*(MK) 4
Conversions And Comparisons 9
Copying Permissions 18
Definitions 2
-Dynamic Extensions (\*(GK) 18
-Environment Variables (\*(GK) 18
+Dynamic Extensions (\*(GK) 14
+Environment Variables (\*(GK) 16
Escape Sequences 8
Expressions 11
Fields 6
FTP/HTTP Information 18
-Historical Features (\*(GK) 18
+Historical Features (\*(GK) 16
Input Control 12
-Internationalization (\*(GK) 16
+Internationalization (\*(GK) 18
Lines And Statements 5
Localization (\*(GK) 17
Numeric Functions 14
@@ -97,9 +97,8 @@ Brian Kernighan and Michael Brennan who reviewed it.
\*(CD
.SL
.nf
-\*(FR\(co Copyright 1996-2001, Free Software Foundation
-59 Temple Place \(em Suite 330
-Boston, MA 02111-1307 USA
+\*(FRCopyright \(co 1996, 1997, 1998, 1999, 2000, 2001, 2002
+Free Software Foundation, Inc.
.nf
.BT
@@ -111,7 +110,7 @@ Boston, MA 02111-1307 USA
.ES
\*(CDThis card describes POSIX AWK, as well as the three
freely available \*(AK implementations
-(see \fHFTP Information\fP below).
+(see \fHFTP/HTTP Information\fP below).
\*(CLCommon extensions (in two or more versions) are printed in light blue.
\*(CBFeatures specific to just one version\(emusually GNU AWK (\*(GK)\(emare
printed in dark blue.
@@ -1422,7 +1421,7 @@ T}
\*(CRThese filenames are now obsolete.
Use the \*(FCPROCINFO\fP array to obtain the information they provide.\*(CL
.EB "\s+2\f(HBSPECIAL FILENAMES\*(FR\s0"
-
+.sp .5
.\" --- Builtin Numeric Functions
.ES
.fi
@@ -1445,6 +1444,24 @@ generator.\*(CX
T}
.TE
.EB "\s+2\f(HBNUMERIC FUNCTIONS\*(FR\s0"
+.sp .5
+.\" --- Extensions
+.ES
+.fi
+.in +.2i
+.ti -.2i
+\*(CD\*(FCextension(\*(FIlib\*(FC, \*(FIfunc\*(FC)\*(FR
+.br
+dynamically load the shared library
+\*(FIlib\*(FR
+and call
+\*(FIfunc\*(FR
+in it to initialize the library.
+This adds new built-in functions to \*(GK.
+It returns the value returned by
+\*(FIfunc\*(FR.\*(CB
+.in -.2i
+.EB "\s+2\f(HBDYNAMIC EXTENSIONS (\*(GK\f(HB)\*(FR\s0"
.BT
@@ -1647,40 +1664,43 @@ teturns the bitwise XOR of the values provided by
.in -.2i
.EB "\s+2\f(HBBIT MANIPULATION FUNCTIONS (\*(GK\f(HB)\*(FR\s0"
-.\" --- Builtin Internationalizatin Functions
+.\" --- Environment Variables
.ES
.fi
-\*(CD\*(GK
-provides the following functions for runtime message translation.
-.in +.2i
-.sp .5
-.ti -.2i
-\*(FCbindtextdomain(\*(FIdirectory \*(FR[\*(FC, \*(FIdomain\*(FR]\*(FC)\*(FR
-.br
-specifies the directory where \*(GK looks for the \*(FC\&.mo\*(FR
-files, in case they
-will not or cannot be placed in the ``standard'' locations
-(e.g., during testing.)
-It returns the directory where \*(FIdomain\*(FR is ``bound.''
+\*(CDThe environment variable \*(FCAWKPATH\fP specifies a search path to use
+when finding source files named with the \*(FC\-f\fP
+option.
+The default path is
+\*(FC".:/usr/local/share/awk"\*(FR.
+.\" if this variable does not exist.
+.\" (The actual directory may vary,
+.\" depending upon how \*(GK was built and installed.)
+If a file name given to the \*(FC\-f\fP option contains a ``/'' character,
+no path search is performed.
.sp .5
-The default \*(FIdomain\*(FR is the value of \*(FCTEXTDOMAIN\*(FR.
-When \*(FIdirectory\*(FR is the null string (\*(FC"\^"\*(FR),
-\*(FCbindtextdomain()\*(FR returns the current binding for the
-given \*(FIdomain\*(FR.
-.ti -.2i
-\*(FCdcgettext(\*(FIstring \*(FR[\*(FC, \*(FIdomain \*(FR[\*(FC, \*(FIcategory\*(FR]]\*(FC)\*(FR
-.br
-returns the translation of \*(FIstring\*(FR in text domain
-\*(FIdomain\*(FR for locale category \*(FIcategory\*(FR.
-The default value for \*(FIdomain\*(FR is the current value of \*(FCTEXTDOMAIN\*(FR.
-The default value for \*(FIcategory\*(FR is \*(FC"LC_MESSAGES"\*(FR.
+If \*(FCPOSIXLY_CORRECT\fP exists
+.\" in the environment,
+then \*(GK
+behaves exactly as if the \*(FC\-\^\-posix\fP option had been given.\*(CB
+.EB "\s+2\f(HBENVIRONMENT VARIABLES (\*(GK\f(HB)\*(FR\s0"
+
+.\" --- Historical Features
+.ES
+.fi
+\*(CD1. It is possible to call the \*(FClength()\fP
+built-in function not only with no argument, but even without parentheses.
+This feature is marked as ``deprecated'' in the POSIX standard, and \*(GK
+issues a warning about its use if \*(FC\-\^\-lint\fP
+is specified on the command line.
.sp .5
-If you supply a value for \*(FIcategory\*(FR, it must be a string equal to
-one of the known locale categories.
-You must also supply a text domain. Use \*(FCTEXTDOMAIN\*(FR
-to use the current domain.\*(CB
-.in -.2i
-.EB "\s+2\f(HBINTERNATIONALIZATION (\*(GK\f(HB)\*(FR\s0"
+2. The \*(FCcontinue\fP
+and \*(FCbreak\fP statements may be used outside the body of a
+\*(FCwhile\*(FR, \*(FCfor\*(FR, or \*(FCdo\fP loop.
+Historical AWK implementations have treated such usage as
+equivalent to the \*(FCnext\fP statement.
+\*(GK supports this usage if \*(FC\-\^\-traditional\fP
+is specified.\*(CB
+.EB "\s+2\f(HBHISTORICAL FEATURES (\*(GK\f(HB)\*(FR\s0"
.BT
@@ -1756,9 +1776,12 @@ which probably won't work.
.sp .5
2. Mark all strings that should be translated with leading underscores.
.sp .5
-3. Use the \*(FCdcgettext()\*(FR
-and/or \*(FCbindtextdomain()\*(FR
-functions in your program, as necessary or appropriate.
+3. Use the
+\*(FCbindtextdomain()\*(FR,
+\*(FCdcgettext()\*(FR,
+and/or
+\*(FCdcngettext()\*(FR
+functions in your program, as appropriate.
.sp .5
4. Run
.sp .5
@@ -1777,68 +1800,60 @@ The internationalization features are described in full detail in \*(AM.\*(CB
.BT
-.\" --- Extensions
+.\" --- Builtin Internationalization Functions
.ES
.fi
+\*(CD\*(GK
+provides the following functions for runtime message translation.
.in +.2i
+.sp .5
.ti -.2i
-\*(CD\*(FCextension(\*(FIlib\*(FC, \*(FIfunc\*(FC)\*(FR
+\*(FCbindtextdomain(\*(FIdirectory \*(FR[\*(FC, \*(FIdomain\*(FR]\*(FC)\*(FR
.br
-dynamically load the shared library
-\*(FIlib\*(FR
-and call
-\*(FIfunc\*(FR
-in it to initialize the library.
-This adds new built-in functions to \*(GK.
-It returns the value returned by
-\*(FIfunc\*(FR.\*(CB
-.in -.2i
-.EB "\s+2\f(HBDYNAMIC EXTENSIONS (\*(GK\f(HB)\*(FR\s0"
-
-.\" --- Environment Variables
-.ES
-.fi
-\*(CDThe environment variable \*(FCAWKPATH\fP specifies a search path to use
-when finding source files named with the \*(FC\-f\fP
-option.
-The default path is
-\*(FC".:/usr/local/share/awk"\*(FR,
-if this variable does not exist.
-(The actual directory may vary,
-depending upon how \*(GK was built and installed.)
-If a file name given to the \*(FC\-f\fP option contains a ``/'' character,
-no path search is performed.
+specifies the directory where \*(GK looks for the \*(FC\&.mo\*(FR
+files, in case they
+will not or cannot be placed in the ``standard'' locations
+(e.g., during testing.)
+It returns the directory where \*(FIdomain\*(FR is ``bound.''
.sp .5
-If \*(FCPOSIXLY_CORRECT\fP exists in the environment, then \*(GK
-behaves exactly as if \*(FC\-\^\-posix\fP had been specified on the
-command line.\*(CB
-.EB "\s+2\f(HBENVIRONMENT VARIABLES (\*(GK\f(HB)\*(FR\s0"
-
-.\" --- Historical Features
-.ES
-.fi
-\*(CD\*(GK supports two features of historical AWK implementations.
-First, it is possible to call the \*(FClength()\fP
-built-in function not only with no argument, but even without parentheses.
-This feature is marked as ``deprecated'' in the POSIX standard, and \*(GK
-issues a warning about its use if \*(FC\-\^\-lint\fP
-is specified on the command line.
+The default \*(FIdomain\*(FR is the value of \*(FCTEXTDOMAIN\*(FR.
+When \*(FIdirectory\*(FR is the null string (\*(FC"\^"\*(FR),
+\*(FCbindtextdomain()\*(FR returns the current binding for the
+given \*(FIdomain\*(FR.
+.ti -.2i
+\*(FCdcgettext(\*(FIstring \*(FR[\*(FC, \*(FIdomain \*(FR[\*(FC, \*(FIcategory\*(FR]]\*(FC)\*(FR
+.br
+returns the translation of \*(FIstring\*(FR in text domain
+\*(FIdomain\*(FR for locale category \*(FIcategory\*(FR.
+The default value for \*(FIdomain\*(FR is the current value of \*(FCTEXTDOMAIN\*(FR.
+The default value for \*(FIcategory\*(FR is \*(FC"LC_MESSAGES"\*(FR.
.sp .5
-The other feature is the use of \*(FCcontinue\fP
-or \*(FCbreak\fP statements outside the body of a
-\*(FCwhile\*(FR, \*(FCfor\*(FR, or \*(FCdo\fP loop.
-Historical AWK implementations have treated such usage as
-equivalent to the \*(FCnext\fP statement.
-\*(GK supports this usage if \*(FC\-\^\-traditional\fP
-is specified.\*(CB
-.EB "\s+2\f(HBHISTORICAL FEATURES (\*(GK\f(HB)\*(FR\s0"
+If you supply a value for \*(FIcategory\*(FR, it must be a string equal to
+one of the known locale categories.
+You must also supply a text domain. Use \*(FCTEXTDOMAIN\*(FR
+to use the current domain.
+.ti -.2i
+\*(FCdcngettext(\*(FIstring1 \*(FR, \*(FIstring2 \*(FR, \*(FInumber \*(FR[\*(FC, \*(FIdomain \*(FR[\*(FC, \*(FIcategory\*(FR]]\*(FC)\*(FR
+.br
+returns the plural form used for \*(FInumber\*(FR of the translation of
+\*(FIstring1\*(FR and \*(FIstring2\*(FR in text domain
+\*(FIdomain\*(FR for locale category \*(FIcategory\*(FR.
+The default value for \*(FIdomain\*(FR is the current value of \*(FCTEXTDOMAIN\*(FR.
+The default value for \*(FIcategory\*(FR is \*(FC"LC_MESSAGES"\*(FR.
+.sp .5
+If you supply a value for \*(FIcategory\*(FR, it must be a string equal to
+one of the known locale categories.
+You must also supply a text domain. Use \*(FCTEXTDOMAIN\*(FR
+to use the current domain.\*(CB
+.in -.2i
+.EB "\s+2\f(HBINTERNATIONALIZATION (\*(GK\f(HB)\*(FR\s0"
-.\" --- FTP Information
+.\" --- FTP/HTTP Information
.ES
.nf
-\*(CDHost: \*(FCgnudist.gnu.org\*(FR
-File: \*(FC/gnu/gawk/gawk-3.1.0.tar.gz\fP
+\*(CDHost: \*(FCftp.gnu.org\*(FR
+File: \*(FC/gnu/gawk/gawk-3.1.1.tar.gz\fP
.in +.2i
.fi
GNU \*(AK (\*(GK). There may be a later version.
@@ -1861,10 +1876,11 @@ Michael Brennan's \*(MK. There may be a newer version.\*(CX
.in -.2i
.EB "\s+2\f(HBFTP/HTTP INFORMATION\*(FR\s0"
+
.\" --- Copying Permissions
.ES
.fi
-\*(CDCopyright \(co 1996-2001 Free Software Foundation, Inc.
+\*(CDCopyright \(co 1996, 1997, 1998, 1999, 2000, 2001, 2002 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 3e3c62b3..5f73a68e 100644
--- a/doc/gawk.1
+++ b/doc/gawk.1
@@ -14,7 +14,7 @@
. if \w'\(rq' .ds rq "\(rq
. \}
.\}
-.TH GAWK 1 "May 29 2001" "Free Software Foundation" "Utility Commands"
+.TH GAWK 1 "Apr 16 2002" "Free Software Foundation" "Utility Commands"
.SH NAME
gawk \- pattern scanning and processing language
.SH SYNOPSIS
@@ -923,6 +923,7 @@ specified by
The index of the first character matched by
.BR match() ;
0 if no match.
+(This implies that character indices start at one.)
.TP
.B RLENGTH
The length of the string matched by
@@ -1494,16 +1495,14 @@ and
For example, the name
.B e
might be used to represent all of
-\*(lqe,\*(rq \*(lqe\h'-\w:e:u'\`,\*(rq and \*(lqe\h'-\w:e:u'\`.\*(rq
+\*(lqe,\*(rq \*(lqe\h'-\w:e:u'\',\*(rq and \*(lqe\h'-\w:e:u'\`.\*(rq
In this case,
.B [[=e=]]
is a regular expression
that matches any of
.BR e ,
-....BR "e\'" ,
.BR "e\h'-\w:e:u'\'" ,
or
-....BR "e\`" .
.BR "e\h'-\w:e:u'\`" .
.PP
These features are very valuable in non-English speaking locales.
@@ -1677,7 +1676,7 @@ as follows:
\fBdelete \fIarray\^\fB[\^\fIindex\^\fB]\fR
\fBdelete \fIarray\^\fR
\fBexit\fR [ \fIexpression\fR ]
-\fB{ \fIstatements \fB}
+\fB{ \fIstatements \fB}\fR
.fi
.RE
.SS "I/O Statements"
@@ -2322,6 +2321,7 @@ in the string
or 0 if
.I t
is not present.
+(This implies that character indices start at one.)
.TP
\fBlength(\fR[\fIs\fR]\fB)
Returns the length of the string
@@ -2629,6 +2629,35 @@ in \*(EP.
You must also supply a text domain. Use
.B TEXTDOMAIN
if you want to use the current domain.
+.TP
+\fBdcngettext(\fIstring1 \fR, \fIstring2 \fR, \fInumber \fR[\fB, \fIdomain \fR[\fB, \fIcategory\fR]]\fB)\fR
+Returns the plural form used for
+.I number
+of the translation of
+.I string1
+and
+.I string2
+in
+text domain
+.I domain
+for locale category
+.IR category .
+The default value for
+.I domain
+is the current value of
+.BR TEXTDOMAIN .
+The default value for
+.I category
+is \fB"LC_MESSAGES"\fR.
+.sp .5
+If you supply a value for
+.IR category ,
+it must be a string equal to
+one of the known locale categories described
+in \*(EP.
+You must also supply a text domain. Use
+.B TEXTDOMAIN
+if you want to use the current domain.
.SH USER-DEFINED FUNCTIONS
Functions in \*(AK are defined as follows:
.PP
@@ -3224,14 +3253,6 @@ Syntactically invalid single character programs tend to overflow
the parse stack, generating a rather unhelpful message. Such programs
are surprisingly difficult to diagnose in the completely general case,
and the effort to do so really is not worth it.
-.ig
-.PP
-.I Gawk
-suffers from ``feeping creaturism.''
-It's too bad
-.I perl
-is so inelegant.
-..
.SH AUTHORS
The original version of \*(UX
.I awk
@@ -3299,7 +3320,8 @@ Brian Kernighan of Bell Laboratories
provided valuable assistance during testing and debugging.
We thank him.
.SH COPYING PERMISSIONS
-Copyright \(co 1989, 1991\-2001 Free Software Foundation, Inc.
+Copyright \(co 1989, 1991, 1992, 1993, 1994, 1995, 1996,
+1997, 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
.PP
Permission is granted to make and distribute verbatim copies of
this manual page provided the copyright notice and this permission
diff --git a/doc/gawk.info b/doc/gawk.info
index 075d4947..316b56c5 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -1,4 +1,4 @@
-This is gawk.info, produced by makeinfo version 4.0 from gawk.texi.
+This is gawk.info, produced by makeinfo version 4.2 from gawk.texi.
INFO-DIR-SECTION GNU Packages
START-INFO-DIR-ENTRY
@@ -9,15 +9,13 @@ START-INFO-DIR-ENTRY
* awk: (gawk)Invoking gawk. Text scanning and processing.
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.
+Copyright (C) 1989, 1991, 1992, 1993, 1996, 1997, 1998, 1999, 2000,
+2001, 2002 Free Software Foundation, Inc.
- This is Edition 3 of `GAWK: Effective AWK Programming: A User's
-Guide for GNU Awk', for the 3.1.0 version of the GNU implementation of
-AWK.
- Copyright (C) 1989, 1991, 1992, 1993, 1996-2001 Free Software
-Foundation, Inc.
+ This is Edition 3 of `GAWK: Effective AWK Programming: A User's
+Guide for GNU Awk', for the 3.1.1 (or later) version of the GNU
+implementation of AWK.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
@@ -32,7 +30,7 @@ texts being (a) (see below), and with the Back-Cover Texts being (b)
b. "You have freedom to copy and modify this GNU Manual, like GNU
software. Copies published by the Free Software Foundation raise
funds for GNU development."
-
+

File: gawk.info, Node: Top, Next: Foreword, Prev: (dir), Up: (dir)
@@ -42,10 +40,28 @@ General Introduction
This file documents `awk', a program that you can use to select
particular records in a file and perform operations upon them.
+Copyright (C) 1989, 1991, 1992, 1993, 1996, 1997, 1998, 1999, 2000,
+2001, 2002 Free Software Foundation, Inc.
+
+
This is Edition 3 of `GAWK: Effective AWK Programming: A User's
-Guide for GNU Awk', for the 3.1.0 version of the GNU implementation of
-AWK.
+Guide for GNU Awk', for the 3.1.1 (or later) version of the GNU
+implementation of AWK.
+ Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being "GNU General Public License", the Front-Cover
+texts being (a) (see below), and with the Back-Cover Texts being (b)
+(see below). A copy of the license is included in the section entitled
+"GNU Free Documentation License".
+
+ a. "A GNU Manual"
+
+ b. "You have freedom to copy and modify this GNU Manual, like GNU
+ software. Copies published by the Free Software Foundation raise
+ funds for GNU development."
+
* Menu:
* Foreword:: Some nice words about this
@@ -102,7 +118,7 @@ AWK.
* Acknowledgments:: Acknowledgments.
* Running gawk:: How to run `gawk' programs;
includes command-line syntax.
-* One-shot:: Running a short throw-away `awk'
+* One-shot:: Running a short throwaway `awk'
program.
* Read Terminal:: Using no input files (input from terminal
instead).
@@ -126,7 +142,7 @@ AWK.
* When:: When to use `gawk' and when to use
other things.
* Regexp Usage:: How to Use Regular Expressions.
-* Escape Sequences:: How to write non-printing characters.
+* Escape Sequences:: How to write nonprinting characters.
* Regexp Operators:: Regular Expression Operators.
* Character Lists:: What can go between `[...]'.
* GNU Regexp Operators:: Operators specific to GNU software.
@@ -135,7 +151,7 @@ AWK.
* Computed Regexps:: Using Dynamic Regexps.
* Records:: Controlling how data is split into records.
* Fields:: An introduction to fields.
-* Non-Constant Fields:: Non-constant Field Numbers.
+* Nonconstant Fields:: Nonconstant Field Numbers.
* Changing Fields:: Changing the Contents of a Field.
* Field Separators:: The field separator and how to change it.
* Regexp Field Splitting:: Using regexps as the field separator.
@@ -183,7 +199,7 @@ AWK.
* Close Files And Pipes:: Closing Input and Output Files and Pipes.
* Constants:: String, numeric and regexp constants.
* Scalar Constants:: Numeric and string constants.
-* Non-decimal-numbers:: What are octal and hex numbers.
+* Nondecimal-numbers:: What are octal and hex numbers.
* Regexp Constants:: Regular Expression constants.
* Using Constant Regexps:: When and how to use a regexp constant.
* Variables:: Variables give names to values for later
@@ -296,7 +312,7 @@ AWK.
* I18N Portability:: `awk'-level portability issues.
* I18N Example:: A simple i18n example.
* Gawk I18N:: `gawk' is also internationalized.
-* Non-decimal Data:: Allowing non-decimal input data.
+* Nondecimal Data:: Allowing nondecimal input data.
* Two-way I/O:: Two-way communications with another
process.
* TCP/IP Networking:: Using `gawk' for network
@@ -388,6 +404,8 @@ AWK.
and OS/2.
* PC Using:: Running `gawk' on MS-DOS, Win32 and
OS/2.
+* Cygwin:: Building and running `gawk' for
+ Cygwin.
* VMS Installation:: Installing `gawk' on VMS.
* VMS Compilation:: How to compile `gawk' under VMS.
* VMS Installation Details:: How to install `gawk' under VMS.
@@ -425,16 +443,12 @@ AWK.
To Miriam, for making me complete.
-
To Chana, for the joy you bring us.
-
To Rivka, for the exponential increase.
-
To Nachum, for the added dimension.
-
To Malka, for the new beginning.

@@ -533,7 +547,7 @@ Preface
You might want to extract certain lines and discard the rest. Or you
may need to make changes wherever certain patterns appear, but leave
the rest of the file alone. Writing single-use programs for these
-tasks in languages such as C, C++ or Pascal is time-consuming and
+tasks in languages such as C, C++, or Pascal is time-consuming and
inconvenient. Such jobs are often easier with `awk'. The `awk'
utility interprets a special-purpose programming language that makes it
easy to handle simple data-reformatting jobs.
@@ -556,7 +570,7 @@ This means that all properly written `awk' programs should work with
* Produce indexes and perform other document preparation tasks
* Experiment with algorithms that you can adapt later to other
- computer languages.
+ computer languages
In addition, `gawk' provides facilities that make it easy to:
@@ -564,21 +578,21 @@ This means that all properly written `awk' programs should work with
* Sort data
- * Perform simple network communications.
+ * Perform simple network communications
This Info file teaches you about the `awk' language and how you can
use it effectively. You should already be familiar with basic system
commands, such as `cat' and `ls',(1) as well as basic shell facilities,
-such as Input/Output (I/O) redirection and pipes.
+such as input/output (I/O) redirection and pipes.
Implementations of the `awk' language are available for many
different computing environments. This Info file, while describing the
`awk' language in general, also describes the particular implementation
of `awk' called `gawk' (which stands for "GNU awk"). `gawk' runs on a
-broad range of Unix systems, ranging from 80386 PC-based computers, up
+broad range of Unix systems, ranging from 80386 PC-based computers up
through large-scale systems, such as Crays. `gawk' has also been ported
-to Mac OS X, MS-DOS, Microsoft Windows (all versions) and OS/2 PC's,
-Atari and Amiga micro-computers, BeOS, Tandem D20, and VMS.
+to Mac OS X, MS-DOS, Microsoft Windows (all versions) and OS/2 PCs,
+Atari and Amiga microcomputers, BeOS, Tandem D20, and VMS.
* Menu:
@@ -596,7 +610,7 @@ Atari and Amiga micro-computers, BeOS, Tandem D20, and VMS.
---------- Footnotes ----------
(1) These commands are available on POSIX-compliant systems, as well
-as on traditional Unix based systems. If you are using some other
+as on traditional Unix-based systems. If you are using some other
operating system, you still need to be familiar with the ideas of I/O
redirection and pipes.
@@ -607,7 +621,6 @@ History of `awk' and `gawk'
===========================
Recipe For A Programming Language
-
1 part `egrep' 1 part `snobol'
2 parts `ed' 3 parts C
@@ -662,9 +675,9 @@ The language described in this Info file is often referred to as "new
Because of this, many systems have multiple versions of `awk'. Some
systems have an `awk' utility that implements the original version of
the `awk' language and a `nawk' utility for the new version. Others
-have an `oawk' for the "old `awk'" language and plain `awk' for the new
-one. Still others only have one version, which is usually the new
-one.(1)
+have an `oawk' version for the "old `awk'" language and plain `awk' for
+the new one. Still others only have one version, which is usually the
+new one.(1)
All in all, this makes it difficult for you to know which version of
`awk' you should run when writing your programs. The best advice I can
@@ -689,15 +702,11 @@ File: gawk.info, Node: This Manual, Next: Conventions, Prev: Names, Up: Pref
Using This Book
===============
- Documentation is like sex: when it is good, it is very, very good;
- and when it is bad, it is better than nothing.
- Dick Brandon
-
The term `awk' refers to a particular program as well as to the
language you use to tell this program what to do. When we need to be
-careful, we call the program "the `awk' utility" and the language "the
-`awk' language." This Info file explains both the `awk' language and
-how to run the `awk' utility. The term "`awk' program" refers to a
+careful, we call the language "the `awk' language," and the program
+"the `awk' utility." This Info file explains both the `awk' language
+and how to run the `awk' utility. The term "`awk' program" refers to a
program written by you in the `awk' programming language.
Primarily, this Info file explains the features of `awk', as defined
@@ -710,7 +719,8 @@ noted.
There are subsections labelled as *Advanced Notes* scattered
throughout the Info file. They add a more complete explanation of
points that are relevant, but not likely to be of interest on first
-reading. All appear in the index, under the heading "advanced notes."
+reading. All appear in the index, under the heading "advanced
+features."
Most of the time, the examples use complete `awk' programs. In some
of the more advanced sections, only the part of the `awk' program that
@@ -750,7 +760,7 @@ structure: associative arrays. Deleting array elements and whole
arrays is also described, as well as sorting arrays in `gawk'.
*Note Functions::, describes the built-in functions `awk' and `gawk'
-provide for you, as well as how to define your own functions.
+provide, as well as how to define your own functions.
*Note Internationalization with `gawk': Internationalization,
describes special features in `gawk' for translating program messages
@@ -767,13 +777,11 @@ program source files.
*Note A Library of `awk' Functions: Library Functions, and *Note
Practical `awk' Programs: Sample Programs, provide many sample `awk'
-programs. Reading them allows you to see `awk' being used for solving
-real problems.
+programs. Reading them allows you to see `awk' solving real problems.
*Note The Evolution of the `awk' Language: Language History,
-describes how the `awk' language has evolved since it was first
-released to present. It also describes how `gawk' has acquired
-features over time.
+describes how the `awk' language has evolved since first release to
+present. It also describes how `gawk' has acquired features over time.
*Note Installing `gawk': Installation, describes how to get `gawk',
how to compile it under Unix, and how to compile and use it on different
@@ -788,20 +796,20 @@ write extension libraries, and some possible future directions for
*Note Basic Programming Concepts: Basic Concepts, provides some very
cursory background material for those who are completely unfamiliar
with computer programming. Also centralized there is a discussion of
-some of the issues involved in using floating-point numbers.
+some of the issues surrounding floating-point numbers.
The *Note Glossary::, defines most, if not all, the significant
terms used throughout the book. If you find terms that you aren't
-familiar with, try looking them up.
+familiar with, try looking them up here.
*Note GNU General Public License: Copying, and *Note GNU Free
Documentation License::, present the licenses that cover the `gawk'
-source code, and this Info file, respectively.
+source code and this Info file, respectively.
---------- Footnotes ----------
- (1) All such differences appear in the index under the heading
-"differences between `gawk' and `awk'."
+ (1) All such differences appear in the index under the entry
+"differences in `awk' and `gawk'."

File: gawk.info, Node: Conventions, Next: Manual History, Prev: This Manual, Up: Preface
@@ -855,10 +863,7 @@ File: gawk.info, Node: Manual History, Next: How To Contribute, Prev: Convent
The GNU Project and This Book
=============================
- Software is like sex: it's better when it's free.
- Linus Torvalds
-
- The Free Software Foundation (FSF) is a non-profit organization
+ The Free Software Foundation (FSF) is a nonprofit organization
dedicated to the production and distribution of freely distributable
software. It was founded by Richard M. Stallman, the author of the
original Emacs editor. GNU Emacs is the most widely used version of
@@ -960,12 +965,12 @@ acknowledgments:
I would like to acknowledge Richard M. Stallman, for his vision of a
better world and for his courage in founding the FSF and starting the
-GNU project.
+GNU Project.
The following people (in alphabetical order) provided helpful
comments on various versions of this book, up to and including this
edition. Rick Adams, Nelson H.F. Beebe, Karl Berry, Dr. Michael
-Brennan, Rich Burridge, Claire Coutier, Diane Close, Scott Deifik,
+Brennan, Rich Burridge, Claire Cloutier, Diane Close, Scott Deifik,
Christopher ("Topher") Eliot, Jeffrey Friedl, Dr. Darrel Hankerson,
Michal Jaegermann, Dr. Richard J. LeBlanc, Michael Lijewski, Pat Rankin,
Miriam Robbins, Mary Sheehan, and Chuck Toporek.
@@ -993,12 +998,12 @@ a significant pleasure.
Ulrich Drepper, provided invaluable help and feedback for the design of
the internationalization features.
- Nelson Beebe, Martin Brown, Scott Deifik, Darrel Hankerson, Michal
-Jaegermann, Ju"rgen Kahrs, Pat Rankin, Kai Uwe Rommel, and Eli Zaretskii
-(in alphabetical order) are long-time members of the `gawk' "crack
-portability team." Without their hard work and help, `gawk' would not
-be nearly the fine program it is today. It has been and continues to
-be a pleasure working with this team of fine people.
+ Nelson Beebe, Martin Brown, Andreas Buening, Scott Deifik, Darrel
+Hankerson, Isamu Hasegawa, Michal Jaegermann, Ju"rgen Kahrs, Pat Rankin,
+Kai Uwe Rommel, and Eli Zaretskii (in alphabetical order) make up the
+`gawk' "crack portability team." Without their hard work and help,
+`gawk' would not be nearly the fine program it is today. It has been
+and continues to be a pleasure working with this team of fine people.
David and I would like to thank Brian Kernighan of Bell Laboratories
for invaluable assistance during the testing and debugging of `gawk',
@@ -1011,15 +1016,14 @@ Associates contributed significant editorial help for this Info file
for the 3.1 release of `gawk'.
I must thank my wonderful wife, Miriam, for her patience through the
-many versions of this project, for her proof-reading, and for sharing
-me with the computer. I would like to thank my parents for their love,
+many versions of this project, for her proofreading, and for sharing me
+with the computer. I would like to thank my parents for their love,
and for the grace with which they raised and educated me. Finally, I
also must acknowledge my gratitude to G-d, for the many opportunities
He has sent my way, as well as for the gifts He has given me with which
to take advantage of those opportunities.
-
Arnold Robbins
Nof Ayalon
ISRAEL
@@ -1044,7 +1048,7 @@ find it. Most other languages are "procedural"; you have to describe,
in great detail, every step the program is to take. When working with
procedural languages, it is usually much harder to clearly describe the
data your program will process. For this reason, `awk' programs are
-often refreshingly easy to write and read.
+often refreshingly easy to read and write.
When you run `awk', you specify an `awk' "program" that tells `awk'
what to do. The program consists of a series of "rules". (It may also
@@ -1100,7 +1104,7 @@ variations of each.
* Menu:
-* One-shot:: Running a short throw-away `awk'
+* One-shot:: Running a short throwaway `awk'
program.
* Read Terminal:: Using no input files (input from terminal
instead).
@@ -1114,8 +1118,8 @@ variations of each.

File: gawk.info, Node: One-shot, Next: Read Terminal, Prev: Running gawk, Up: Running gawk
-One-Shot Throw-Away `awk' Programs
-----------------------------------
+One-Shot Throwaway `awk' Programs
+---------------------------------
Once you are familiar with `awk', you will often type in simple
programs the moment you want to use them. Then you can write the
@@ -1160,8 +1164,8 @@ MS-DOS, it is `Ctrl-z'.)
As an example, the following program prints a friendly piece of
advice (from Douglas Adams's `The Hitchhiker's Guide to the Galaxy'),
-to keep you from worrying about the complexities of computer
-programming. (`BEGIN' is a feature we haven't discussed yet.):
+to keep you from worrying about the complexities of computer programming
+(`BEGIN' is a feature we haven't discussed yet):
$ awk "BEGIN { print \"Don't Panic!\" }"
-| Don't Panic!
@@ -1172,8 +1176,8 @@ rules--in particular because it mixes both single quotes and double
quotes.(1)
This next simple `awk' program emulates the `cat' utility; it copies
-whatever you type at the keyboard to its standard output. (Why this
-works is explained shortly.)
+whatever you type on the keyboard to its standard output (why this
+works is explained shortly).
$ awk '{ print }'
Now is the time for all good men
@@ -1287,8 +1291,8 @@ interpreter to run and an optional initial command-line argument to
pass to that interpreter. The operating system then runs the
interpreter with the given argument and the full argument list of the
executed program. The first argument in the list is the full file name
-of the `awk' program. The rest of the argument list is either options
-to `awk', or data files, or both.
+of the `awk' program. The rest of the argument list contains either
+options to `awk', or data files, or both.

File: gawk.info, Node: Comments, Next: Quoting, Prev: Executable Scripts, Up: Running gawk
@@ -1312,12 +1316,12 @@ put the following into `advice':
# keep novice users from being afraid of the computer.
BEGIN { print "Don't Panic!" }
- You can put comment lines into keyboard-composed throw-away `awk'
+ You can put comment lines into keyboard-composed throwaway `awk'
programs, but this usually isn't very useful; the purpose of a comment
is to help you or another person understand the program when reading it
at a later time.
- *Caution:* As mentioned in *Note One-Shot Throw-Away `awk' Programs:
+ *Caution:* As mentioned in *Note One-Shot Throwaway `awk' Programs:
One-shot, you can enclose small to medium programs in single quotes, in
order to keep your shell scripts self-contained. When doing so,
_don't_ put an apostrophe (i.e., a single quote) into a comment (or
@@ -1331,7 +1335,7 @@ example, look at the following:
>
The shell sees that the first two quotes match, and that a new
-quoted object begins at the end of the command-line. It therefore
+quoted object begins at the end of the command line. It therefore
prompts with the secondary prompt, waiting for more input. With Unix
`awk', closing the quoted string produces this result:
@@ -1347,7 +1351,7 @@ node describes the shell's quoting rules.

File: gawk.info, Node: Quoting, Prev: Comments, Up: Running gawk
-Shell Quoting Issues
+Shell-Quoting Issues
--------------------
For short to medium length `awk' programs, it is most convenient to
@@ -1375,8 +1379,8 @@ Bourne-Again Shell). If you use `csh', you're on your own.
quotes. The shell does no interpretation of the quoted text,
passing it on verbatim to the command. It is _impossible_ to
embed a single quote inside single-quoted text. Refer back to
- *Note Comments in `awk' Programs: Comments, for an example showing
- what happens if you try.
+ *Note Comments in `awk' Programs: Comments, for an example of what
+ happens if you try.
* Double quotes protect most things between the opening and closing
quotes. The shell does at least variable and command substitution
@@ -1385,7 +1389,7 @@ Bourne-Again Shell). If you use `csh', you're on your own.
Since certain characters within double-quoted text are processed
by the shell, they must be "escaped" within the text. Of note are
- the characters `$', ``', `\' and `"', all of which must be
+ the characters `$', ``', `\', and `"', all of which must be
preceded by a backslash within double-quoted text if they are to
be passed on literally to the program. (The leading backslash is
stripped first.) Thus, the example seen in *Note Running `awk'
@@ -1448,18 +1452,18 @@ Data Files for the Examples
===========================
Many of the examples in this Info file take their input from two
-sample data files. The first, called `BBS-list', represents a list of
+sample data files. The first, `BBS-list', represents a list of
computer bulletin board systems together with information about those
systems. The second data file, called `inventory-shipped', contains
information about monthly shipments. In both files, each line is
considered to be one "record".
- In the file `BBS-list', each record contains the name of a computer
-bulletin board, its phone number, the board's baud rate(s), and a code
-for the number of hours it is operational. An `A' in the last column
-means the board operates 24 hours a day. A `B' in the last column
-means the board only operates on evening and weekend hours. A `C'
-means the board operates only on weekends:
+ In the data file `BBS-list', each record contains the name of a
+computer bulletin board, its phone number, the board's baud rate(s),
+and a code for the number of hours it is operational. An `A' in the
+last column means the board operates 24 hours a day. A `B' in the last
+column means the board only operates on evening and weekend hours. A
+`C' means the board operates only on weekends:
aardvark 555-5553 1200/300 B
alpo-net 555-3412 2400/1200/300 A
@@ -1473,12 +1477,12 @@ means the board operates only on weekends:
sdace 555-3430 2400/1200/300 A
sabafoo 555-2127 1200/300 C
- The second data file, called `inventory-shipped', represents
-information about shipments during the year. Each record contains the
-month, the number of green crates shipped, the number of red boxes
-shipped, the number of orange bags shipped, and the number of blue
-packages shipped, respectively. There are 16 entries, covering the 12
-months of last year and the first four months of the current year.
+ The data file `inventory-shipped' represents information about
+shipments during the year. Each record contains the month, the number
+of green crates shipped, the number of red boxes shipped, the number of
+orange bags shipped, and the number of blue packages shipped,
+respectively. There are 16 entries, covering the 12 months of last year
+and the first four months of the current year.
Jan 13 25 15 115
Feb 15 32 24 226
@@ -1519,10 +1523,10 @@ Some Simple Examples
====================
The following command runs a simple `awk' program that searches the
-input file `BBS-list' for the character string `foo'. (A string of
-characters is usually called a "string". The term "string" is based on
-similar usage in English, such as "a string of pearls," or, "a string
-of cars in a train."):
+input file `BBS-list' for the character string `foo' (a grouping of
+characters is usually called a "string"; the term "string" is based on
+similar usage in English, such as "a string of pearls," or "a string of
+cars in a train"):
awk '/foo/ { print $0 }' BBS-list
@@ -1552,10 +1556,10 @@ for _every_ input line. If the action is omitted, the default action
is to print all lines that match the pattern.
Thus, we could leave out the action (the `print' statement and the
-curly braces) in the above example and the result would be the same: all
-lines matching the pattern `foo' are printed. By comparison, omitting
-the `print' statement but retaining the curly braces makes an empty
-action that does nothing (i.e., no lines are printed).
+curly braces) in the previous example and the result would be the same:
+all lines matching the pattern `foo' are printed. By comparison,
+omitting the `print' statement but retaining the curly braces makes an
+empty action that does nothing (i.e., no lines are printed).
Many practical `awk' programs are just a line or two. Following is a
collection of useful, short programs to get you started. Some of these
@@ -1617,7 +1621,7 @@ different ways to do the same things shown here:
awk -F: '{ print $1 }' /etc/passwd | sort
- * Count lines in a file:
+ * Count the lines in a file:
awk 'END { print NR }' data
@@ -1625,8 +1629,8 @@ different ways to do the same things shown here:
awk 'NR % 2 == 0' data
- If you use the expression `NR % 2 == 1' instead, it would print
- the odd-numbered lines.
+ If you use the expression `NR % 2 == 1' instead, the program would
+ print the odd-numbered lines.

File: gawk.info, Node: Two Rules, Next: More Complex, Prev: Very Simple, Up: Getting Started
@@ -1643,9 +1647,9 @@ run.
After processing all the rules that match the line (and perhaps
there are none), `awk' reads the next line. (However, *note The `next'
Statement: Next Statement., and also *note Using `gawk''s `nextfile'
-Statement: Nextfile Statement.). This continues until the end of the
-file is reached. For example, the following `awk' program contains two
-rules:
+Statement: Nextfile Statement.). This continues until the program
+reaches the end of the file. For example, the following `awk' program
+contains two rules:
/12/ { print $0 }
/21/ { print $0 }
@@ -1660,7 +1664,7 @@ the string `21'. If a line contains both strings, it is printed twice,
once by each rule.
This is what happens if we run this program on our two sample data
-files, `BBS-list' and `inventory-shipped', as shown here:
+files, `BBS-list' and `inventory-shipped':
$ awk '/12/ { print $0 }
> /21/ { print $0 }' BBS-list inventory-shipped
@@ -1715,7 +1719,7 @@ The first field contains read-write permissions, the second field
contains the number of links to the file, and the third field
identifies the owner of the file. The fourth field identifies the group
of the file. The fifth field contains the size of the file in bytes.
-The sixth, seventh and eighth fields contain the month, day, and time,
+The sixth, seventh, and eighth fields contain the month, day, and time,
respectively, that the file was last modified. Finally, the ninth field
contains the name of the file.(2)
@@ -1736,14 +1740,14 @@ the value of `sum' is 140963.
(*note Actions: Action Overview.). Before you can move on to more
advanced `awk' programming, you have to know how `awk' interprets your
input and displays your output. By manipulating fields and using
-`print' statements, you can produce some very useful and impressive
-looking reports.
+`print' statements, you can produce some very useful and
+impressive-looking reports.
---------- Footnotes ----------
(1) In the C shell (`csh'), you need to type a semicolon and then a
backslash at the end of the first line; see *Note `awk' Statements
-Versus Lines: Statements/Lines, for an explanation as to why. In a
+Versus Lines: Statements/Lines, for an explanation. In a
POSIX-compliant shell, such as the Bourne shell or `bash', you can type
the example as shown. If the command `echo $path' produces an empty
output line, you are most likely using a POSIX-compliant shell.
@@ -1797,13 +1801,13 @@ constant using backslash continuation. Thus, for maximum portability
of your `awk' programs, it is best not to split your lines in the
middle of a regular expression or a string.
- *Caution:* _Backslash continuation does not work as described above
-with the C shell._ It works for `awk' programs in files and for
-one-shot programs, _provided_ you are using a POSIX-compliant shell,
-such as the Unix Bourne shell or `bash'. But the C shell behaves
-differently! There, you must use two backslashes in a row, followed by
-a newline. Note also that when using the C shell, _every_ newline in
-your awk program must be escaped with a backslash. To illustrate:
+ *Caution:* _Backslash continuation does not work as described with
+the C shell._ It works for `awk' programs in files and for one-shot
+programs, _provided_ you are using a POSIX-compliant shell, such as the
+Unix Bourne shell or `bash'. But the C shell behaves differently!
+There, you must use two backslashes in a row, followed by a newline.
+Note also that when using the C shell, _every_ newline in your awk
+program must be escaped with a backslash. To illustrate:
% awk 'BEGIN { \
? print \\
@@ -1826,7 +1830,7 @@ POSIX-compliant shell:
`awk' is a line-oriented language. Each rule's action has to begin
on the same line as the pattern. To have the pattern and action on
separate lines, you _must_ use backslash continuation; there is no
-other way.
+other option.
Another thing to keep in mind is that backslash continuation and
comments do not mix. As soon as `awk' sees the `#' that starts a
@@ -1876,7 +1880,7 @@ There are other variables your program can set as well to control how
`awk' processes your data.
In addition, `awk' provides a number of built-in functions for doing
-common computational and string related operations. `gawk' provides
+common computational and string-related operations. `gawk' provides
built-in functions for working with timestamps, performing bit
manipulation, and for runtime string translation.
@@ -1908,7 +1912,7 @@ edit-compile-test-debug cycle of software development.
Complex programs have been written in `awk', including a complete
retargetable assembler for eight-bit microprocessors (*note Glossary::,
-for more information), and a microcode assembler for a special purpose
+for more information), and a microcode assembler for a special-purpose
Prolog computer. However, `awk''s capabilities are strained by tasks of
such complexity.
@@ -1945,7 +1949,7 @@ you specify more complicated classes of strings.
* Menu:
* Regexp Usage:: How to Use Regular Expressions.
-* Escape Sequences:: How to write non-printing characters.
+* Escape Sequences:: How to write nonprinting characters.
* Regexp Operators:: Regular Expression Operators.
* Character Lists:: What can go between `[...]'.
* GNU Regexp Operators:: Operators specific to GNU software.
@@ -1972,13 +1976,13 @@ it:
-| 555-6480
-| 555-2127
- Regular expressions can also be used in matching expressions. These
-expressions allow you to specify the string to match against; it need
-not be the entire current input record. The two operators `~' and `!~'
-perform regular expression comparisons. Expressions using these
-operators can be used as patterns, or in `if', `while', `for', and `do'
-statements. (*Note Control Statements in Actions: Statements.) For
-example:
+ `~' (tilde), `~' operator Regular expressions can also be used in
+matching expressions. These expressions allow you to specify the
+string to match against; it need not be the entire current input
+record. The two operators `~' and `!~' perform regular expression
+comparisons. Expressions using these operators can be used as
+patterns, or in `if', `while', `for', and `do' statements. (*Note
+Control Statements in Actions: Statements.) For example:
EXP ~ /REGEXP/
@@ -2025,9 +2029,9 @@ Escape Sequences
(`"foo"') or regexp constants (`/foo/'). Instead, they should be
represented with "escape sequences", which are character sequences
beginning with a backslash (`\'). One use of an escape sequence is to
-include a double quote character in a string constant. Because a plain
+include a double-quote character in a string constant. Because a plain
double quote ends the string, you must use `\"' to represent an actual
-double quote character as a part of the string. For example:
+double-quote character as a part of the string. For example:
$ awk 'BEGIN { print "He said \"hi!\" to her." }'
-| He said "hi!" to her.
@@ -2037,10 +2041,10 @@ included normally; you must write `\\' to put one backslash in the
string or regexp. Thus, the string whose contents are the two
characters `"' and `\' must be written `"\"\\"'.
- Another use of backslash is to represent unprintable characters such
-as tab or newline. While there is nothing to stop you from entering
-most unprintable characters directly in a string constant or regexp
-constant, they may look ugly.
+ Backslash also represents unprintable characters such as TAB or
+newline. While there is nothing to stop you from entering most
+unprintable characters directly in a string constant or regexp constant,
+they may look ugly.
The following table lists all the escape sequences used in `awk' and
what they represent. Unless noted otherwise, all these escape sequences
@@ -2066,7 +2070,7 @@ apply to both string constants and regexp constants:
Carriage return, `Ctrl-m', ASCII code 13 (CR).
`\t'
- Horizontal tab, `Ctrl-i', ASCII code 9 (HT).
+ Horizontal TAB, `Ctrl-i', ASCII code 9 (HT).
`\v'
Vertical tab, `Ctrl-k', ASCII code 11 (VT).
@@ -2078,11 +2082,11 @@ apply to both string constants and regexp constants:
`\xHH...'
The hexadecimal value HH, where HH stands for a sequence of
- hexadecimal digits (`0' through `9', and either `A' through `F' or
- `a' through `f'). Like the same construct in ISO C, the escape
- sequence continues until the first non-hexadecimal digit is seen.
- However, using more than two hexadecimal digits produces undefined
- results. (The `\x' escape sequence is not allowed in POSIX `awk'.)
+ hexadecimal digits (`0'-`9', and either `A'-`F' or `a'-`f'). Like
+ the same construct in ISO C, the escape sequence continues until
+ the first nonhexadecimal digit is seen. However, using more than
+ two hexadecimal digits produces undefined results. (The `\x'
+ escape sequence is not allowed in POSIX `awk'.)
`\/'
A literal slash (necessary for regexp constants only). This
@@ -2104,13 +2108,13 @@ with a backslash have special meaning in regexps. *Note
`gawk'-Specific Regexp Operators: GNU Regexp Operators.
In a regexp, a backslash before any character that is not in the
-above table and not listed in *Note `gawk'-Specific Regexp Operators:
+previous list and not listed in *Note `gawk'-Specific Regexp Operators:
GNU Regexp Operators, means that the next character should be taken
literally, even if it would normally be a regexp operator. For
example, `/a\+b/' matches the three characters `a+b'.
For complete portability, do not use a backslash before any
-character not shown in the table above.
+character not shown in the previous list.
To summarize:
@@ -2130,29 +2134,28 @@ Advanced Notes: Backslash Before Regular Characters
---------------------------------------------------
If you place a backslash in a string constant before something that
-is not one of the characters listed above, POSIX `awk' purposely leaves
-what happens as undefined. There are two choices:
+is not one of the characters previously listed, POSIX `awk' purposely
+leaves what happens as undefined. There are two choices:
Strip the backslash out
This is what Unix `awk' and `gawk' both do. For example, `"a\qc"'
- is the same as `"aqc"'. (Because this is such an easy bug to both
+ is the same as `"aqc"'. (Because this is such an easy bug both to
introduce and to miss, `gawk' warns you about it.) Consider `FS =
"[ \t]+\|[ \t]+"' to use vertical bars surrounded by whitespace as
- the field separator. There should be two backslashes in the
- string, `FS = "[ \t]+\\|[ \t]+"'.)
+ the field separator. There should be two backslashes in the string
+ `FS = "[ \t]+\\|[ \t]+"'.)
Leave the backslash alone
Some other `awk' implementations do this. In such
- implementations, `"a\qc"' is the same as if you had typed
- `"a\\qc"'.
+ implementations, typing `"a\qc"' is the same as typing `"a\\qc"'.
Advanced Notes: Escape Sequences for Metacharacters
---------------------------------------------------
Suppose you use an octal or hexadecimal escape to represent a regexp
-metacharacter (*note Regular Expression Operators: Regexp Operators.).
-Does `awk' treat the character as a literal character or as a regexp
-operator?
+metacharacter. (See *Note Regular Expression Operators: Regexp
+Operators.) Does `awk' treat the character as a literal character or
+as a regexp operator?
Historically, such characters were taken literally. (d.c.)
However, the POSIX standard indicates that they should be treated as
@@ -2172,9 +2175,9 @@ Regular Expression Operators
power and versatility of regular expressions.
The escape sequences described in *Note Escape Sequences::, are
-valid inside a regexp. They are introduced by a `\', and are
-recognized and converted into the corresponding real characters as the
-very first step in processing regexps.
+valid inside a regexp. They are introduced by a `\' and are recognized
+and converted into corresponding real characters as the very first step
+in processing regexps.
Here is a list of metacharacters. All characters that are not escape
sequences and that are not listed in the table stand for themselves:
@@ -2185,10 +2188,10 @@ sequences and that are not listed in the table stand for themselves:
`^'
This matches the beginning of a string. For example, `^@chapter'
- matches `@chapter' at the beginning of a string, and can be used
- to identify chapter beginnings in Texinfo source files. The `^'
- is known as an "anchor", because it anchors the pattern to match
- only at the beginning of the string.
+ matches `@chapter' at the beginning of a string and can be used to
+ identify chapter beginnings in Texinfo source files. The `^' is
+ known as an "anchor", because it anchors the pattern to match only
+ at the beginning of the string.
It is important to realize that `^' does not match the beginning of
a line embedded in a string. The condition is not true in the
@@ -2197,10 +2200,10 @@ sequences and that are not listed in the table stand for themselves:
if ("line1\nLINE 2" ~ /^L/) ...
`$'
- This is similar to `^' but it matches only at the end of a string.
+ This is similar to `^', but it matches only at the end of a string.
For example, `p$' matches a record that ends with a `p'. The `$'
is an anchor and does not match the end of a line embedded in a
- string. The condition is not true in the following example:
+ string. The condition in the following example is not true:
if ("line1\nLINE 2" ~ /1$/) ...
@@ -2208,8 +2211,8 @@ sequences and that are not listed in the table stand for themselves:
This matches any single character, _including_ the newline
character. For example, `.P' matches any single character
followed by a `P' in a string. Using concatenation, we can make a
- regular expression such as `U.A', that matches any three-character
- sequence that begins with `U' and ends with `A'.
+ regular expression such as `U.A', which matches any
+ three-character sequence that begins with `U' and ends with `A'.
In strict POSIX mode (*note Command-Line Options: Options.), `.'
does not match the NUL character, which is a character with all
@@ -2219,7 +2222,7 @@ sequences and that are not listed in the table stand for themselves:
`[...]'
This is called a "character list".(1) It matches any _one_ of the
characters that are enclosed in the square brackets. For example,
- `[MVX]' matches any one of the characters `M', `V', or `X', in a
+ `[MVX]' matches any one of the characters `M', `V', or `X' in a
string. A full discussion of what can be inside the square
brackets of a character list is given in *Note Using Character
Lists: Character Lists.
@@ -2228,7 +2231,7 @@ sequences and that are not listed in the table stand for themselves:
This is a "complemented character list". The first character after
the `[' _must_ be a `^'. It matches any characters _except_ those
in the square brackets. For example, `[^awk]' matches any
- character that is not an `a', a `w', or a `k'.
+ character that is not an `a', `w', or `k'.
`|'
This is the "alternation operator" and it is used to specify
@@ -2241,8 +2244,8 @@ sequences and that are not listed in the table stand for themselves:
side.
`(...)'
- Parentheses are used for grouping in regular expressions, similar
- to arithmetic. They can be used to concatenate regular expressions
+ Parentheses are used for grouping in regular expressions, as in
+ arithmetic. They can be used to concatenate regular expressions
containing the alternation operator, `|'. For example,
`@(samp|code)\{[^}]+\}' matches both `@code{foo}' and `@samp{bar}'.
(These are Texinfo formatting control sequences.)
@@ -2263,18 +2266,18 @@ sequences and that are not listed in the table stand for themselves:
preceding them with backslashes.
`+'
- This symbol is similar to `*' except that the preceding expression
- must be matched at least once. This means that `wh+y' would match
- `why' and `whhy', but not `wy', whereas `wh*y' would match all
- three of these strings. The following is a simpler way of writing
- the last `*' example:
+ This symbol is similar to `*', except that the preceding
+ expression must be matched at least once. This means that `wh+y'
+ would match `why' and `whhy', but not `wy', whereas `wh*y' would
+ match all three of these strings. The following is a simpler way
+ of writing the last `*' example:
awk '/\(c[ad]+r x\)/ { print }' sample
`?'
- This symbol is similar to `*' except that the preceding expression
- can be matched either once or not at all. For example, `fe?d'
- matches `fed' and `fd', but nothing else.
+ This symbol is similar to `*', except that the preceding
+ expression can be matched either once or not at all. For example,
+ `fe?d' matches `fed' and `fd', but nothing else.
`{N}'
`{N,}'
@@ -2327,7 +2330,8 @@ available in regular expressions.
---------- Footnotes ----------
(1) In other literature, you may see a character list referred to as
-either a "character set", a "character class" or a "bracket expression".
+either a "character set", a "character class", or a "bracket
+expression".
(2) Use two backslashes if you're using a string constant with a
regexp operator or function.
@@ -2372,11 +2376,11 @@ differs between the United States and France.
A character class is only valid in a regexp _inside_ the brackets of
a character list. Character classes consist of `[:', a keyword
denoting the class, and `:]'. Here are the character classes defined
-by the POSIX standard:
+by the POSIX standard.
`[:alnum:]' Alphanumeric characters.
`[:alpha:]' Alphabetic characters.
-`[:blank:]' Space and tab characters.
+`[:blank:]' Space and TAB characters.
`[:cntrl:]' Control characters.
`[:digit:]' Numeric characters.
`[:graph:]' Characters that are both printable and visible. (A space is
@@ -2386,7 +2390,7 @@ by the POSIX standard:
characters).
`[:punct:]' Punctuation characters (characters that are not letters,
digits, control characters, or space characters).
-`[:space:]' Space characters (such as space, tab, and formfeed, to name a
+`[:space:]' Space characters (such as space, TAB, and formfeed, to name a
few).
`[:upper:]' Uppercase alphabetic characters.
`[:xdigit:]' Characters that are hexadecimal digits.
@@ -2404,26 +2408,24 @@ These apply to non-ASCII character sets, which can have single symbols
(called "collating elements") that are represented with more than one
character. They can also have several characters that are equivalent for
"collating", or sorting, purposes. (For example, in French, a plain "e"
-and a grave-accented "e`" are equivalent.)
+and a grave-accented "e`" are equivalent.) These sequences are:
-Collating Symbols
- A "collating symbol" is a multicharacter collating element
- enclosed between `[.' and `.]'. For example, if `ch' is a
- collating element, then `[[.ch.]]' is a regexp that matches this
- collating element, whereas `[ch]' is a regexp that matches either
- `c' or `h'.
+Collating symbols
+ Multicharacter collating elements enclosed between `[.' and `.]'.
+ For example, if `ch' is a collating element, then `[[.ch.]]' is a
+ regexp that matches this collating element, whereas `[ch]' is a
+ regexp that matches either `c' or `h'.
-Equivalence Classes
- An "equivalence class" is a locale-specific name for a list of
- characters that are equal. The name is enclosed between `[=' and
- `=]'. For example, the name `e' might be used to represent all of
- "e," "e`," and "e'." In this case, `[[=e=]]' is a regexp that
- matches any of `e', `e'', or `e`'.
+Equivalence classes
+ Locale-specific names for a list of characters that are equal. The
+ name is enclosed between `[=' and `=]'. For example, the name `e'
+ might be used to represent all of "e," "e`," and "e'." In this
+ case, `[[=e=]]' is a regexp that matches any of `e', `e'', or `e`'.
- These features are very valuable in non-English speaking locales.
+ These features are very valuable in non-English-speaking locales.
*Caution:* The library functions that `gawk' uses for regular
-expression matching currently only recognize POSIX character classes;
+expression matching currently recognize only POSIX character classes;
they do not recognize collating symbols or equivalence classes.

@@ -2441,12 +2443,12 @@ letters, digits, or underscores (`_'):
`\w'
Matches any word-constituent character--that is, it matches any
- letter, digit, or underscore. Think of it as short-hand for
+ letter, digit, or underscore. Think of it as shorthand for
`[[:alnum:]_]'.
`\W'
Matches any character that is not word-constituent. Think of it
- as short-hand for `[^[:alnum:]_]'.
+ as shorthand for `[^[:alnum:]_]'.
`\<'
Matches the empty string at the beginning of a word. For example,
@@ -2469,7 +2471,7 @@ letters, digits, or underscores (`_'):
There are two other operators that work on buffers. In Emacs, a
"buffer" is, naturally, an Emacs buffer. For other programs, `gawk''s
regexp library routines consider the entire string to match as the
-buffer.
+buffer. The operators are:
`\`'
Matches the empty string at the beginning of a buffer (string).
@@ -2505,7 +2507,7 @@ No options
`--traditional'
Traditional Unix `awk' regexps are matched. The GNU operators are
not special, interval expressions are not available, nor are the
- POSIX character classes (`[[:alnum:]]' and so on). Characters
+ POSIX character classes (`[[:alnum:]]', etc.). Characters
described by octal and hexadecimal escape sequences are treated
literally, even if they represent regexp metacharacters.
@@ -2526,8 +2528,8 @@ lowercase `w' and not an uppercase `W'.
The simplest way to do a case-independent match is to use a character
list--for example, `[Ww]'. However, this can be cumbersome if you need
-to use it often and it can make the regular expressions harder to read.
-There are two alternatives that you might prefer.
+to use it often, and it can make the regular expressions harder to
+read. There are two alternatives that you might prefer.
One way to perform a case-insensitive match at a particular point in
the program is to convert the data to a single case, using the
@@ -2543,9 +2545,10 @@ works in any POSIX-compliant `awk'.
Another method, specific to `gawk', is to set the variable
`IGNORECASE' to a nonzero value (*note Built-in Variables::). When
`IGNORECASE' is not zero, _all_ regexp and string operations ignore
-case. Changing the value of `IGNORECASE' dynamically controls the case
-sensitivity of the program as it runs. Case is significant by default
-because `IGNORECASE' (like most variables) is initialized to zero:
+case. Changing the value of `IGNORECASE' dynamically controls the
+case-sensitivity of the program as it runs. Case is significant by
+default because `IGNORECASE' (like most variables) is initialized to
+zero:
x = "aB"
if (x ~ /ab/) ... # this test will fail
@@ -2574,7 +2577,7 @@ comparison operations are also affected by `IGNORECASE'.
Beginning with `gawk' 3.0, the equivalences between upper- and
lowercase characters are based on the ISO-8859-1 (ISO Latin-1)
character set. This character set is a superset of the traditional 128
-ASCII characters, that also provides a number of characters suitable
+ASCII characters, which also provides a number of characters suitable
for use with European languages.
The value of `IGNORECASE' has no effect if `gawk' is in
@@ -2645,7 +2648,7 @@ going to use a string constant, you have to understand that the string
is, in essence, scanned _twice_: the first time when `awk' reads your
program, and the second time when it goes to match the string on the
lefthand side of the operator with the pattern on the right. This is
-true of any string valued expression (such as `digits_regexp' shown
+true of any string-valued expression (such as `digits_regexp', shown
previously), not just string constants.
What difference does it make if the string is scanned twice? The
@@ -2668,7 +2671,7 @@ constants," for several reasons:
kinds of constants is a common source of errors.
* It is more efficient to use regexp constants. `awk' can note that
- you have supplied a regexp, and store it internally in a form that
+ you have supplied a regexp and store it internally in a form that
makes pattern matching more efficient. When using a string
constant, `awk' must first convert the string into this internal
form and then perform the pattern matching.
@@ -2706,8 +2709,8 @@ Reading Input Files
*******************
In the typical `awk' program, all input is read either from the
-standard input (by default, this is the keyboard but often it is a pipe
-from another command), or from files whose names you specify on the
+standard input (by default, this is the keyboard, but often it is a
+pipe from another command) or from files whose names you specify on the
`awk' command line. If you specify input files, `awk' reads them in
order, processing all the data from one before going on to the next.
The name of the current input file can be found in the built-in variable
@@ -2729,7 +2732,7 @@ have to be named on the `awk' command line (*note Explicit Input with
* Records:: Controlling how data is split into records.
* Fields:: An introduction to fields.
-* Non-Constant Fields:: Non-constant Field Numbers.
+* Nonconstant Fields:: Nonconstant Field Numbers.
* Changing Fields:: Changing the Contents of a Field.
* Field Separators:: The field separator and how to change it.
* Constant Size:: Reading constant width data.
@@ -2775,9 +2778,8 @@ a string whose first character is a slash; as a result, records are
separated by slashes. Then the input file is read, and the second rule
in the `awk' program (the action with no pattern) prints each record.
Because each `print' statement adds a newline at the end of its output,
-the effect of this `awk' program is to copy the input with each slash
-changed to a newline. Here are the results of running the program on
-`BBS-list':
+this `awk' program copies the input with each slash changed to a
+newline. Here are the results of running the program on `BBS-list':
$ awk 'BEGIN { RS = "/" }
> { print $0 }' BBS-list
@@ -2860,7 +2862,7 @@ general, each record ends at the next string that matches the regular
expression; the next record starts at the end of the matching string.
This general rule is actually at work in the usual case, where `RS'
contains just a newline: a record ends at the beginning of the next
-matching string (the next newline in the input) and the following
+matching string (the next newline in the input), and the following
record starts just after the end of this string (at the first character
of the following line). The newline, because it matches `RS', is not
part of either record.
@@ -2926,13 +2928,13 @@ the end of the previous ones.
(1) At least that we know about.

-File: gawk.info, Node: Fields, Next: Non-Constant Fields, Prev: Records, Up: Reading Files
+File: gawk.info, Node: Fields, Next: Nonconstant Fields, Prev: Records, Up: Reading Files
Examining Fields
================
When `awk' reads an input record, the record is automatically
-separated or "parsed" by the interpreter into chunks called "fields".
+"parsed" or separated by the interpreter into chunks called "fields".
By default, fields are separated by "whitespace", like words in a line.
Whitespace in `awk' means any string of one or more spaces, tabs, or
newlines;(1) other characters, such as formfeed, vertical tab, etc.
@@ -2948,8 +2950,8 @@ simple `awk' programs so powerful.
followed by the number of the field you want. Thus, `$1' refers to the
first field, `$2' to the second, and so on. (Unlike the Unix shells,
the field numbers are not limited to single digits. `$127' is the one
-hundred and twenty-seventh field in the record.) For example, suppose
-the following is a line of input:
+hundred twenty-seventh field in the record.) For example, suppose the
+following is a line of input:
This seems like a pretty nice example.
@@ -2966,9 +2968,9 @@ as `$7', which is `example.'. If you try to reference a field beyond
the last one (such as `$8' when the record has only seven fields), you
get the empty string. (If used in a numeric operation, you get zero.)
- The use of `$0', which looks like a reference to the "zeroth" field,
-is a special case: it represents the whole input record when you are
-not interested in specific fields. Here are some more examples:
+ The use of `$0', which looks like a reference to the "zero-th"
+field, is a special case: it represents the whole input record when you
+are not interested in specific fields. Here are some more examples:
$ awk '$1 ~ /foo/ { print $0 }' BBS-list
-| fooey 555-1234 2400/1200/300 B
@@ -2998,10 +3000,10 @@ input record:
separating fields.

-File: gawk.info, Node: Non-Constant Fields, Next: Changing Fields, Prev: Fields, Up: Reading Files
+File: gawk.info, Node: Nonconstant Fields, Next: Changing Fields, Prev: Fields, Up: Reading Files
-Non-Constant Field Numbers
-==========================
+Nonconstant Field Numbers
+=========================
The number of a field does not need to be a constant. Any
expression in the `awk' language can be used after a `$' to refer to a
@@ -3044,7 +3046,7 @@ feature--it is the direct consequence of evaluating `NF' and using its
value as a field number.

-File: gawk.info, Node: Changing Fields, Next: Field Separators, Prev: Non-Constant Fields, Up: Reading Files
+File: gawk.info, Node: Changing Fields, Next: Field Separators, Prev: Nonconstant Fields, Up: Reading Files
Changing the Contents of a Field
================================
@@ -3052,7 +3054,7 @@ Changing the Contents of a Field
The contents of a field, as seen by `awk', can be changed within an
`awk' program; this changes what `awk' perceives as the current input
record. (The actual input is untouched; `awk' _never_ modifies the
-input file.) Consider this example and its output:
+input file.) Consider the following example and its output:
$ awk '{ nboxes = $3 ; $3 = $3 - 10
> print nboxes, $3 }' inventory-shipped
@@ -3259,8 +3261,8 @@ example, the assignment:
FS = ", \t"
makes every area of an input line that consists of a comma followed by a
-space and a tab into a field separator. (`\t' is an "escape sequence"
-that stands for a tab; *note Escape Sequences::, for the complete list
+space and a TAB into a field separator. (`\t' is an "escape sequence"
+that stands for a TAB; *note Escape Sequences::, for the complete list
of similar escape sequences.)
For a less trivial example of a regular expression, try using single
@@ -3341,12 +3343,12 @@ For example:
awk -F, 'PROGRAM' INPUT-FILES
-sets `FS' to the `,' character. Notice that the option uses a capital
-`F' instead of a lowercase `-f', which specifies a file containing an
-`awk' program. Case is significant in command-line options: the `-F'
-and `-f' options have nothing to do with each other. You can use both
-options at the same time to set the `FS' variable _and_ get an `awk'
-program from a file.
+sets `FS' to the `,' character. Notice that the option uses an
+uppercase `F' instead of a lowercase `f'. The latter option (`-f')
+specifies a file containing an `awk' program. Case is significant in
+command-line options: the `-F' and `-f' options have nothing to do with
+each other. You can use both options at the same time to set the `FS'
+variable _and_ get an `awk' program from a file.
The value used for the argument to `-F' is processed in exactly the
same way as assignments to the built-in variable `FS'. Any special
@@ -3364,7 +3366,7 @@ separator.
As a special case, in compatibility mode (*note Command-Line
Options: Options.), if the argument to `-F' is `t', then `FS' is set to
-the tab character. If you type `-F\t' at the shell, without any
+the TAB character. If you type `-F\t' at the shell, without any
quotes, the `\' gets deleted, so `awk' figures that you really want
your fields to be separated with tabs and not `t's. Use `-v FS="t"' or
`-F"[t]"' on the command line if you really do want to separate your
@@ -3421,11 +3423,11 @@ the entries for users who have no password:

File: gawk.info, Node: Field Splitting Summary, Prev: Command Line Field Separator, Up: Field Separators
-Field Splitting Summary
+Field-Splitting Summary
-----------------------
The following table summarizes how fields are split, based on the
-value of `FS'. (`==' means "is equal to.")
+value of `FS' (`==' means "is equal to"):
`FS == " "'
Fields are separated by runs of whitespace. Leading and trailing
@@ -3525,7 +3527,7 @@ use of `FIELDWIDTHS':
The following program takes the above input, converts the idle time
to number of seconds, and prints out the first two fields and the
-calculated idle time.
+calculated idle time:
*Note:* This program uses a number of `awk' features that haven't
been introduced yet.
@@ -3567,8 +3569,8 @@ An `awk' program for processing such data could use the `FIELDWIDTHS'
feature to simplify reading the data. (Of course, getting `gawk' to
run on a system with card readers is another story!)
- Assigning a value to `FS' causes `gawk' to return to using `FS' for
-field splitting. Use `FS = FS' to make this happen, without having to
+ Assigning a value to `FS' causes `gawk' to use `FS' for field
+splitting again. Use `FS = FS' to make this happen, without having to
know the current value of `FS'. In order to tell which kind of field
splitting is in effect, use `PROCINFO["FS"]' (*note Built-in Variables
That Convey Information: Auto-set.). The value is `"FS"' if regular
@@ -3606,7 +3608,7 @@ well be used, as long as it won't be part of the data in a record.
special dispensation, an empty string as the value of `RS' indicates
that records are separated by one or more blank lines. When `RS' is set
to the empty string, each record always ends at the first blank line
-encountered. The next record doesn't start until the first non-blank
+encountered. The next record doesn't start until the first nonblank
line that follows. No matter how many blank lines appear in a row, they
all act as one record separator. (Blank lines must be completely
empty; lines that contain only whitespace do not count.)
@@ -3616,7 +3618,7 @@ empty; lines that contain only whitespace do not count.)
record and one or more blank lines after the record. In addition, a
regular expression always matches the longest possible sequence when
there is a choice (*note How Much Text Matches?: Leftmost Longest.).
-So the next record doesn't start until the first non-blank line that
+So the next record doesn't start until the first nonblank line that
follows--no matter how many blank lines appear in a row, they are
considered one record separator.
@@ -3646,7 +3648,7 @@ line: to do this, just set the variable `FS' to the string `"\n"'.
(This simple regular expression matches a single newline.) A practical
example of a data file organized this way might be a mailing list,
where each entry is separated by blank lines. Consider a mailing list
-in a file named `addresses', that looks like this:
+in a file named `addresses', which looks like this:
Jane Doe
123 Main Street
@@ -3708,7 +3710,7 @@ equal to.")
`RS == REGEXP'
Records are separated by occurrences of characters that match
REGEXP. Leading and trailing matches of REGEXP delimit empty
- records. (This is a `gawk' extension, it is not specified by the
+ records. (This is a `gawk' extension; it is not specified by the
POSIX standard.)
In all cases, `gawk' sets `RT' to the input text that matched the
@@ -3734,8 +3736,8 @@ have reviewed the rest of this Info file and have a good knowledge of
how `awk' works.
The `getline' command returns one if it finds a record and zero if
-the end of the file is encountered. If there is some error in getting
-a record, such as a file that cannot be opened, then `getline' returns
+it encounters the end of the file. If there is some error in getting a
+record, such as a file that cannot be opened, then `getline' returns
-1. In this case, `gawk' sets the variable `ERRNO' to a string
describing the error that occurred.
@@ -3768,7 +3770,7 @@ Using `getline' with No Arguments
from the current input file. All it does in this case is read the next
input record and split it up into fields. This is useful if you've
finished processing the current record, but want to do some special
-processing _right now_ on the next record. Here's an example:
+processing on the next record _right now_. For example:
{
if ((t = index($0, "/*")) != 0) {
@@ -3821,8 +3823,7 @@ suppose the next line is a comment or a special string, and you want to
read it without triggering any rules. This form of `getline' allows
you to read that line and store it in a variable so that the main
read-a-line-and-check-each-rule loop of `awk' never sees it. The
-following example swaps every two lines of input. The program is as
-follows:
+following example swaps every two lines of input:
{
if ((getline tmp) > 0) {
@@ -3912,8 +3913,8 @@ file FILENAME:
}
Note here how the name of the extra input file is not built into the
-program; it is taken directly from the data, from the second field on
-the `@include' line.
+program; it is taken directly from the data, specifically from the
+second field on the `@include' line.
The `close' function is called to ensure that if two identical
`@include' lines appear in the input, the entire specified file is
@@ -3971,13 +3972,13 @@ the program might produce:
bill ttyp1 Jul 13 14:23 (murphy:0)
bletch
-Notice that this program ran the command `who' and printed the result.
-(If you try this program yourself, you will of course get different
-results, depending upon who is logged in on your system.)
+Notice that this program ran the command `who' and printed the previous
+result. (If you try this program yourself, you will of course get
+different results, depending upon who is logged in on your system.)
This variation of `getline' splits the record into fields, sets the
-value of `NF' and recomputes the value of `$0'. The values of `NR' and
-`FNR' are not changed.
+value of `NF', and recomputes the value of `$0'. The values of `NR'
+and `FNR' are not changed.
According to POSIX, `EXPRESSION | getline' is ambiguous if
EXPRESSION contains unparenthesized operators other than `$'--for
@@ -4031,7 +4032,7 @@ your `awk' program.
processing and then read the results back. `gawk' allows you start a
"coprocess", with which two-way communications are possible. This is
done with the `|&' operator. Typically, you write data to the
-coprocess first, and then read results back, as shown in the following:
+coprocess first and then read results back, as shown in the following:
print "SOME QUERY" |& "db_server"
"db_server" |& getline
@@ -4040,8 +4041,8 @@ which sends a query to `db_server' and then reads the results.
The values of `NR' and `FNR' are not changed, because the main input
stream is not used. However, the record is split into fields in the
-normal manner, thus changing the values of `$0', the other fields, and
-of `NF'.
+normal manner, thus changing the values of `$0', of the other fields,
+and of `NF'.
Coprocesses are an advanced feature. They are discussed here only
because this is the minor node on `getline'. *Note Two-Way
@@ -4070,7 +4071,7 @@ discussed in more detail.

File: gawk.info, Node: Getline Notes, Next: Getline Summary, Prev: Getline/Variable/Coprocess, Up: Getline
-Points About `getline' to Remember
+Points to Remember About `getline'
----------------------------------
Here are some miscellaneous points about `getline' that you should
@@ -4105,15 +4106,15 @@ Summary of `getline' Variants
The following table summarizes the eight variants of `getline',
listing which built-in variables are set by each one.
-`getline' Sets `$0', `NF', `FNR' and `NR'
-`getline' VAR Sets VAR, `FNR' and `NR'
+`getline' Sets `$0', `NF', `FNR', and `NR'
+`getline' VAR Sets VAR, `FNR', and `NR'
`getline <' FILE Sets `$0' and `NF'
`getline VAR < FILE' Sets VAR
COMMAND `| getline' Sets `$0' and `NF'
COMMAND `| getline' VAR Sets VAR
-COMMAND `|& getline' Sets `$0' and `NF' (this is a `gawk'
- extension)
-COMMAND `|& getline' VAR Sets VAR (this is a `gawk' extension)
+COMMAND `|& getline' Sets `$0' and `NF'. This is a `gawk'
+ extension
+COMMAND `|& getline' VAR Sets VAR. This is a `gawk' extension

File: gawk.info, Node: Printing, Next: Expressions, Prev: Reading Files, Up: Top
@@ -4121,16 +4122,16 @@ File: gawk.info, Node: Printing, Next: Expressions, Prev: Reading Files, Up:
Printing Output
***************
- One of the most common programming actions is to "print" or output,
+ One of the most common programming actions is to "print", or output,
some or all of the input. Use the `print' statement for simple output,
and the `printf' statement for fancier formatting. The `print'
statement is not limited when computing _which_ values to print.
However, with two exceptions, you cannot specify _how_ to print
them--how many columns, whether to use exponential notation or not, and
so on. (For the exceptions, *note Output Separators::, and *Note
-Controlling Numeric Output with `print': OFMT.) For that, you need the
-`printf' statement (*note Using `printf' Statements for Fancier
-Printing: Printf.).
+Controlling Numeric Output with `print': OFMT.) For printing with
+specifications, you need the `printf' statement (*note Using `printf'
+Statements for Fancier Printing: Printf.).
Besides basic and formatted printing, this major node also covers
I/O redirections to files and pipes, introduces the special file names
@@ -4177,9 +4178,9 @@ Numeric values are converted to strings and then printed.
$0': it prints the entire current record. To print a blank line, use
`print ""', where `""' is the empty string. To print a fixed piece of
text, use a string constant, such as `"Don't Panic"', as one item. If
-you forget to use the double quote characters, your text is taken as an
-`awk' expression and you will probably get an error. Keep in mind that
-a space is printed between any two items.
+you forget to use the double-quote characters, your text is taken as an
+`awk' expression, and you will probably get an error. Keep in mind
+that a space is printed between any two items.

File: gawk.info, Node: Print Examples, Next: Output Separators, Prev: Print, Up: Printing
@@ -4371,8 +4372,9 @@ Introduction to the `printf' Statement
The entire list of arguments may optionally be enclosed in parentheses.
The parentheses are necessary if any of the item expressions use the
-`>' relational operator; otherwise it can be confused with a redirection
-(*note Redirecting Output of `print' and `printf': Redirection.).
+`>' relational operator; otherwise, it can be confused with a
+redirection (*note Redirecting Output of `print' and `printf':
+Redirection.).
The difference between `printf' and `print' is the FORMAT argument.
This is an expression whose value is taken as a string; it specifies
@@ -4464,7 +4466,7 @@ width. Here is a list of the format-control letters:
`A' through `F' instead of `a' through `f'.
`%%'
- This isn't a format-control letter but it does have meaning--the
+ This isn't a format-control letter, but it does have meaning--the
sequence `%%' outputs one `%'; it does not consume an argument and
it ignores any modifiers.
@@ -4492,7 +4494,7 @@ which they may appear:
order given in the format string. With a positional specifier,
the format specification is applied to a specific argument,
instead of what would be the next argument in the list.
- Positional specifiers begin counting with one:
+ Positional specifiers begin counting with one. Thus:
printf "%s %s\n", "don't", "panic"
printf "%2$s %1$s\n", "panic", "don't"
@@ -4506,7 +4508,7 @@ which they may appear:
For now, we will not use them.
`-'
- The minus sign, used before the width modifier (see further on in
+ The minus sign, used before the width modifier (see later on in
this table), says to left-justify the argument within its
specified width. Normally, the argument is printed
right-justified in the specified width. Thus:
@@ -4520,7 +4522,7 @@ which they may appear:
negative values with a minus sign.
`+'
- The plus sign, used before the width modifier (see further on in
+ The plus sign, used before the width modifier (see later on in
this table), says to always supply a sign for numeric conversions,
even if the data to format is positive. The `+' overrides the
space modifier.
@@ -4773,14 +4775,14 @@ work identically for `printf':
close(report)
The message is built using string concatenation and saved in the
- variable `m'. It is then sent down the pipeline to the `mail'
+ variable `m'. It's then sent down the pipeline to the `mail'
program. (The parentheses group the items to concatenate--see
*Note String Concatenation: Concatenation.)
The `close' function is called here because it's a good idea to
close the pipe as soon as all the intended output has been sent to
it. *Note Closing Input and Output Redirections: Close Files And
- Pipes, for more information on this.
+ Pipes, for more information.
This example also illustrates the use of a variable to represent a
FILE or COMMAND--it is not necessary to always use a string
@@ -4792,15 +4794,15 @@ work identically for `printf':
This type of redirection prints the items to the input of COMMAND.
The difference between this and the single-`|' redirection is that
the output from COMMAND can be read with `getline'. Thus COMMAND
- is a "coprocess", that works together with, but subsidiary to, the
- `awk' program.
+ is a "coprocess", which works together with, but subsidiary to,
+ the `awk' program.
This feature is a `gawk' extension, and is not available in POSIX
`awk'. *Note Two-Way Communications with Another Process: Two-way
I/O, for a more complete discussion.
Redirecting output using `>', `>>', `|', or `|&' asks the system to
-open a file, pipe, or coprocess, only if the particular FILE or COMMAND
+open a file, pipe, or coprocess only if the particular FILE or COMMAND
you specify has not already been written to by your program or if it
has been closed since it was last written to.
@@ -4827,7 +4829,7 @@ Advanced Notes: Piping into `sh'
--------------------------------
A particularly powerful way to use redirection is to build command
-lines, and pipe them into the shell, `sh'. For example, suppose you
+lines and pipe them into the shell, `sh'. For example, suppose you
have a list of files brought over from a system where all the file names
are stored in uppercase, and you wish to rename them to have names in
all lowercase. The following program is both simple and efficient:
@@ -4871,7 +4873,7 @@ the "standard input", "standard output", and "standard error output".
These streams are, by default, connected to your terminal, but they are
often redirected with the shell, via the `<', `<<', `>', `>>', `>&',
and `|' operators. Standard error is typically used for writing error
-messages; the reason there are two separate streams, standard output,
+messages; the reason there are two separate streams, standard output
and standard error, is so that they can be redirected separately.
In other implementations of `awk', the only way to write an error
@@ -4897,8 +4899,8 @@ opening `/dev/tty' fails.
streams, as well as any other inherited open files. If the file name
matches one of these special names when `gawk' redirects input or
output, then it directly uses the stream that the file name stands for.
-(These special file names work for all operating systems that `gawk'
-has been ported to, not just those that are POSIX-compliant.):
+These special file names work for all operating systems that `gawk' has
+been ported to, not just those that are POSIX-compliant:
`/dev/stdin'
The standard input (file descriptor 0).
@@ -4994,7 +4996,7 @@ Special Files for Network Communications
----------------------------------------
Starting with version 3.1 of `gawk', `awk' programs can open a
-two-way TCP/IP connection, acting as either a client or server. This
+two-way TCP/IP connection, acting as either a client or a server. This
is done using a special file name of the form:
`/inet/PROTOCOL/LOCAL-PORT/REMOTE-HOST/REMOTE-PORT'
@@ -5015,7 +5017,7 @@ Special File Name Caveats
-------------------------
Here is a list of things to bear in mind when using the special file
-names that `gawk' provides.
+names that `gawk' provides:
* Recognition of these special file names is disabled if `gawk' is in
compatibility mode (*note Command-Line Options: Options.).
@@ -5036,12 +5038,12 @@ names that `gawk' provides.
---------- Footnotes ----------
- (1) Older versions of `gawk' would only interpret these names
-internally if the system did not actually have a a `/dev/fd' directory
-or any of the other above listed special files. Usually this didn't
-make a difference, but sometimes it did; thus, it was decided to make
-`gawk''s behavior consistent on all systems and to have it always
-interpret the special file names itself.
+ (1) Older versions of `gawk' would interpret these names internally
+only if the system did not actually have a `/dev/fd' directory or any
+of the other special files listed earlier. Usually this didn't make a
+difference, but sometimes it did; thus, it was decided to make `gawk''s
+behavior consistent on all systems and to have it always interpret the
+special file names itself.

File: gawk.info, Node: Close Files And Pipes, Prev: Special Files, Up: Printing
@@ -5273,11 +5275,11 @@ forms, but are stored identically internally.
* Menu:
* Scalar Constants:: Numeric and string constants.
-* Non-decimal-numbers:: What are octal and hex numbers.
+* Nondecimal-numbers:: What are octal and hex numbers.
* Regexp Constants:: Regular Expression constants.

-File: gawk.info, Node: Scalar Constants, Next: Non-decimal-numbers, Prev: Constants, Up: Constants
+File: gawk.info, Node: Scalar Constants, Next: Nondecimal-numbers, Prev: Constants, Up: Constants
Numeric and String Constants
----------------------------
@@ -5292,7 +5294,7 @@ the same value:
1050e-1
A string constant consists of a sequence of characters enclosed in
-double quote marks. For example:
+double-quotation marks. For example:
"parrot"
@@ -5309,7 +5311,7 @@ uses double-precision floating-point numbers. On most modern systems,
these are in IEEE 754 standard format.

-File: gawk.info, Node: Non-decimal-numbers, Next: Regexp Constants, Prev: Scalar Constants, Up: Constants
+File: gawk.info, Node: Nondecimal-numbers, Next: Regexp Constants, Prev: Scalar Constants, Up: Constants
Octal and Hexadecimal Numbers
-----------------------------
@@ -5317,14 +5319,14 @@ Octal and Hexadecimal Numbers
In `awk', all numbers are in decimal; i.e., base 10. Many other
programming languages allow you to specify numbers in other bases, often
octal (base 8) and hexadecimal (base 16). In octal, the numbers go 0,
-1, 2, 3, 4, 5, 6, 7, 10, 11, 12, etc.. Just as `11' in decimal is 1
-times 10 plus 1, so `11' in octal is 1 times 8, plus 1. This equals
-nine in decimal. In hexadecimal, there are 16 digits. Since the
-everyday decimal number system only has ten digits (`0'--`9'), the
-letters `a' through `f' are used to represent the rest. (Case in the
-letters is usually irrelevant; hexadecimal `a' and `A' have the same
-value.) Thus, `11' in hexadecimal is 1 times 16 plus 1, which equals
-17 in decimal.
+1, 2, 3, 4, 5, 6, 7, 10, 11, 12, etc. Just as `11', in decimal, is 1
+times 10 plus 1, so `11', in octal, is 1 times 8, plus 1. This equals 9
+in decimal. In hexadecimal, there are 16 digits. Since the everyday
+decimal number system only has ten digits (`0'-`9'), the letters `a'
+through `f' are used to represent the rest. (Case in the letters is
+usually irrelevant; hexadecimal `a' and `A' have the same value.)
+Thus, `11', in hexadecimal, is 1 times 16 plus 1, which equals 17 in
+decimal.
Just by looking at plain `11', you can't tell what base it's in.
So, in C, C++, and other languages derived from C, there is a special
@@ -5332,7 +5334,7 @@ notation to help signify the base. Octal numbers start with a leading
`0', and hexadecimal numbers start with a leading `0x' or `0X':
`11'
- Decimal 11.
+ Decimal value 11.
`011'
Octal 11, decimal value 9.
@@ -5354,7 +5356,7 @@ of various sorts.
program text. However, such numbers in the input data are not treated
differently; doing so by default would break old programs. (If you
really need to do this, use the `--non-decimal-data' command-line
-option, *note Allowing Non-Decimal Input Data: Non-decimal Data..) If
+option; *note Allowing Nondecimal Input Data: Nondecimal Data..) If
you have octal or hexadecimal data, you can use the `strtonum' function
(*note String Manipulation Functions: String Functions.) to convert
the data into a number. Most of the time, you will want to use octal
@@ -5363,7 +5365,7 @@ manipulation functions; see *Note Using `gawk''s Bit Manipulation
Functions: Bitwise Functions, for more information.
Unlike some early C implementations, `8' and `9' are not valid in
-octal constants; e.g., `gawk' treats `018' as decimal 18.
+octal constants; e.g., `gawk' treats `018' as decimal 18:
$ gawk 'BEGIN { print "021 is", 021 ; print 018 }'
-| 021 is 17
@@ -5385,7 +5387,7 @@ for conversion of numbers to strings:
-| 0x11 is <17>

-File: gawk.info, Node: Regexp Constants, Prev: Non-decimal-numbers, Up: Constants
+File: gawk.info, Node: Regexp Constants, Prev: Nondecimal-numbers, Up: Constants
Regular Expression Constants
----------------------------
@@ -5406,7 +5408,7 @@ Using Regular Expression Constants
regexp constant merely stands for the regexp that is to be matched.
However, regexp constants (such as `/foo/') may be used like simple
expressions. When a regexp constant appears by itself, it has the same
-meaning as if it appeared in a pattern, i.e.; `($0 ~ /foo/)' (d.c.)
+meaning as if it appeared in a pattern, i.e., `($0 ~ /foo/)' (d.c.)
*Note Expressions as Patterns: Expression Patterns. This means that
the following two code segments:
@@ -5447,7 +5449,7 @@ of the `match' function (*note String Manipulation Functions: String
Functions.). Modern implementations of `awk', including `gawk', allow
the third argument of `split' to be a regexp constant, but some older
implementations do not. (d.c.) This can lead to confusion when
-attempting to use regexp constants as arguments to user defined
+attempting to use regexp constants as arguments to user-defined
functions (*note User-Defined Functions: User-defined.). For example:
function mysub(pat, repl, str, global)
@@ -5569,9 +5571,9 @@ second field is printed in lines from `BBS-list':
...
Command-line arguments are made available for explicit examination by
-the `awk' program in an array named `ARGV' (*note Using `ARGC' and
-`ARGV': ARGC and ARGV.). `awk' processes the values of command-line
-assignments for escape sequences (d.c.) (*note Escape Sequences::).
+the `awk' program in the `ARGV' array (*note Using `ARGC' and `ARGV':
+ARGC and ARGV.). `awk' processes the values of command-line
+assignments for escape sequences (*note Escape Sequences::). (d.c.)

File: gawk.info, Node: Conversion, Next: Arithmetic Ops, Prev: Variables, Up: Expressions
@@ -5592,7 +5594,7 @@ are converted to strings. Consider the following:
This prints the (numeric) value 27. The numeric values of the
variables `two' and `three' are converted to strings and concatenated
together. The resulting string is converted back to the number 23, to
-which four is then added.
+which 4 is then added.
If, for some reason, you need to force a number to be converted to a
string, concatenate the empty string, `""', with that number. To force
@@ -5724,7 +5726,7 @@ that `X % Y' is negative if X is negative. Thus:
-17 % 8 = -1
In other `awk' implementations, the signedness of the remainder may
-be machine dependent.
+be machine-dependent.
*Note:* The POSIX standard only specifies the use of `^' for
exponentiation. For maximum portability, do not use the `**' operator.
@@ -5849,7 +5851,7 @@ Arrays.). These are all called "lvalues", which means they can appear
on the lefthand side of an assignment operator. The righthand operand
may be any expression; it produces the new value that the assignment
stores in the specified variable, field, or array element. (Such values
-are called "rvalues").
+are called "rvalues".)
It is important to note that variables do _not_ have permanent types.
A variable's type is simply the type of whatever value it happens to
@@ -5872,8 +5874,7 @@ zero. After executing the following code, the value of `foo' is five:
*Note:* Using a variable as a number and then later as a string can be
confusing and is poor programming style. The previous two examples
-illustrate how `awk' works, _not_ how you should write your own
-programs!
+illustrate how `awk' works, _not_ how you should write your programs!
An assignment is an expression, so it has a value--the same value
that is assigned. Thus, `z = 1' is an expression with the value one.
@@ -5969,7 +5970,7 @@ A workaround is:
awk '/[=]=/' /dev/null
- `gawk' does not have this problem, nor do the other freely-available
+ `gawk' does not have this problem, nor do the other freely available
versions described in *Note Other Freely Available `awk'
Implementations: Other Versions.
@@ -5981,8 +5982,8 @@ Increment and Decrement Operators
"Increment" and "decrement operators" increase or decrease the value
of a variable by one. An assignment operator can do the same thing, so
-the increment operators add no power to the `awk' language; however they
-are convenient abbreviations for very common operations.
+the increment operators add no power to the `awk' language; however,
+they are convenient abbreviations for very common operations.
The operator used for adding one is written `++'. It can be used to
increment a variable either before or after taking its value. To
@@ -6070,7 +6071,7 @@ concepts of "true" and "false." Such languages usually use the special
constants `true' and `false', or perhaps their uppercase equivalents.
However, `awk' is different. It borrows a very simple concept of true
and false from C. In `awk', any nonzero numeric value _or_ any
-non-empty string value is true. Any other value (zero or the null
+nonempty string value is true. Any other value (zero or the null
string `""') is false. The following program prints `A strange truth
value' three times:
@@ -6300,7 +6301,7 @@ also referred to as "logical expressions". The terms are equivalent.
Boolean expressions can be used wherever comparison and matching
expressions can be used. They can be used in `if', `while', `do', and
`for' statements (*note Control Statements in Actions: Statements.).
-They have numeric values (one if true, zero if false), that come into
+They have numeric values (one if true, zero if false) that come into
play if the result of the Boolean expression is stored in a variable or
used in arithmetic.
@@ -6456,7 +6457,8 @@ concatenation of a variable with an expression inside parentheses.
but it is best not to get into the habit of using space to avoid
mistakes with user-defined functions. Each function expects a
particular number of arguments. For example, the `sqrt' function must
-be called with a single argument: the number to take the square root of:
+be called with a single argument, the number of which to take the
+square root:
sqrt(ARGUMENT)
@@ -6516,7 +6518,7 @@ interpret them: innermost first. Thus, `$++i' means `$(++i)' and
operand, then the precedence of the unary operators can matter. `$x^2'
means `($x)^2', but `-x^2' means `-(x^2)', because `-' has lower
precedence than `^', whereas `$' has higher precedence. This table
-presents `awk''s operators, in order of highest precedence to lowest:
+presents `awk''s operators, in order of highest to lowest precedence:
`(...)'
Grouping.
@@ -6556,12 +6558,12 @@ presents `awk''s operators, in order of highest precedence to lowest:
redirection does not produce an expression that could be the
operand of another operator. As a result, it does not make sense
to use a redirection operator near another operator of lower
- precedence without parentheses. Such combinations (for example
+ precedence without parentheses. Such combinations (for example,
`print foo > a ? b : c'), result in syntax errors. The correct
way to write this statement is `print foo > (a ? b : c)'.
`~ !~'
- Matching, non-matching.
+ Matching, nonmatching.
`in'
Array membership.
@@ -6577,7 +6579,7 @@ presents `awk''s operators, in order of highest precedence to lowest:
`= += -= *='
`/= %= ^= **='
- Assignment. These operators group right-to-left.
+ Assignment. These operators group right to left.
*Note:* The `|&', `**', and `**=' operators are not specified by
POSIX. For maximum portability, do not use them.
@@ -6623,7 +6625,7 @@ Pattern Elements
Patterns in `awk' control the execution of rules--a rule is executed
when its pattern matches the current input record. The following is a
-summary of the types of patterns in `awk':
+summary of the types of `awk' patterns:
`/REGULAR EXPRESSION/'
A regular expression. It matches when the text of the input record
@@ -6675,13 +6677,13 @@ matches if the expression's value is nonzero (if a number) or non-null
(if a string). The expression is reevaluated each time the rule is
tested against a new input record. If the expression uses fields such
as `$1', the value depends directly on the new input record's text;
-otherwise it depends on only what has happened so far in the execution
+otherwise, it depends on only what has happened so far in the execution
of the `awk' program.
Comparison expressions, using the comparison operators described in
*Note Variable Typing and Comparison Expressions: Typing and Comparison,
-are a very common kind of pattern. Regexp matching and non-matching
-are also very common expressions. The left operand of the `~' and `!~'
+are a very common kind of pattern. Regexp matching and nonmatching are
+also very common expressions. The left operand of the `~' and `!~'
operators is a string. The right operand is either a constant regular
expression enclosed in slashes (`/REGEXP/'), or any expression whose
string value is used as a dynamic regular expression (*note Using
@@ -6777,7 +6779,7 @@ distinguish them from the records you are interested in.
It is possible for a pattern to be turned on and off by the same
record. If the record satisfies both conditions, then the action is
executed for just that record. For example, suppose there is text
-between two identical markers (say the `%' symbol), each on its own
+between two identical markers (e.g., the `%' symbol), each on its own
line, that should be ignored. A first attempt would be to combine a
range pattern that describes the delimited text with the `next'
statement (not discussed yet, *note The `next' Statement: Next
@@ -6798,7 +6800,7 @@ a flag:
In a range pattern, the comma (`,') has the lowest precedence of all
the operators (i.e., it is evaluated last). Thus, the following
-program attempts to combine a range pattern with another simpler test:
+program attempts to combine a range pattern with another, simpler test:
echo Yes | awk '/1/,/2/ || /Yes/'
@@ -6873,14 +6875,14 @@ and readability.
functions, because each library file can have its own `BEGIN' and/or
`END' rule to do its own initialization and/or cleanup. The order in
which library functions are named on the command line controls the
-order in which their `BEGIN' and `END' rules are executed. Therefore
+order in which their `BEGIN' and `END' rules are executed. Therefore,
you have to be careful when writing such rules in library files so that
the order in which they are executed doesn't matter. *Note
Command-Line Options: Options, for more information on using library
functions. *Note A Library of `awk' Functions: Library Functions, for
a number of useful library functions.
- If an `awk' program only has a `BEGIN' rule and no other rules, then
+ If an `awk' program has only a `BEGIN' rule and no other rules, then
the program exits after the `BEGIN' rule is run.(1) However, if an
`END' rule exists, then the input is read, even if there are no other
rules in the program. This is necessary in case the `END' rule checks
@@ -6889,7 +6891,7 @@ the `FNR' and `NR' variables.
---------- Footnotes ----------
(1) The original version of `awk' used to keep reading and ignoring
-input until end of file was seen.
+input until the end of the file was seen.

File: gawk.info, Node: I/O And BEGIN/END, Prev: Using BEGIN/END, Up: BEGIN/END
@@ -6905,7 +6907,7 @@ fields, when executing `BEGIN' rules. References to `$0' and the fields
yield a null string or zero, depending upon the context. One way to
give `$0' a real value is to execute a `getline' command without a
variable (*note Explicit Input with `getline': Getline.). Another way
-is to simply assign a value to `$0'.
+is simply to assign a value to `$0'.
The second point is similar to the first but from the other
direction. Traditionally, due largely to implementation issues, `$0'
@@ -6940,7 +6942,7 @@ File: gawk.info, Node: Empty, Prev: BEGIN/END, Up: Pattern Overview
The Empty Pattern
-----------------
- An empty (i.e., non-existent) pattern is considered to match _every_
+ An empty (i.e., nonexistent) pattern is considered to match _every_
input record. For example, the program:
awk '{ print $1 }' BBS-list
@@ -7020,10 +7022,10 @@ looks like this:
...
An action consists of one or more `awk' "statements", enclosed in
-curly braces (`{' and `}'). Each statement specifies one thing to do.
-The statements are separated by newlines or semicolons. The curly
-braces around an action must be used even if the action contains only
-one statement, or if it contains no statements at all. However, if you
+curly braces (`{...}'). Each statement specifies one thing to do. The
+statements are separated by newlines or semicolons. The curly braces
+around an action must be used even if the action contains only one
+statement, or if it contains no statements at all. However, if you
omit the action entirely, omit the curly braces as well. An omitted
action is equivalent to `{ print $0 }':
@@ -7032,32 +7034,35 @@ action is equivalent to `{ print $0 }':
The following types of statements are supported in `awk':
- * Expressions, which can call functions or assign values to variables
- (*note Expressions::). Executing this kind of statement simply
- computes the value of the expression. This is useful when the
- expression has side effects (*note Assignment Expressions:
- Assignment Ops.).
-
- * Control statements, which specify the control flow of `awk'
- programs. The `awk' language gives you C-like constructs (`if',
- `for', `while', and `do') as well as a few special ones (*note
- Control Statements in Actions: Statements.).
-
- * Compound statements, which consist of one or more statements
- enclosed in curly braces. A compound statement is used in order
- to put several statements together in the body of an `if',
- `while', `do', or `for' statement.
-
- * Input statements using the `getline' command (*note Explicit Input
- with `getline': Getline.), the `next' statement (*note The `next'
- Statement: Next Statement.), and the `nextfile' statement (*note
- Using `gawk''s `nextfile' Statement: Nextfile Statement.).
+Expressions
+ Call functions or assign values to variables (*note
+ Expressions::). Executing this kind of statement simply computes
+ the value of the expression. This is useful when the expression
+ has side effects (*note Assignment Expressions: Assignment Ops.).
+
+Control statements
+ Specify the control flow of `awk' programs. The `awk' language
+ gives you C-like constructs (`if', `for', `while', and `do') as
+ well as a few special ones (*note Control Statements in Actions:
+ Statements.).
+
+Compound statements
+ Consist of one or more statements enclosed in curly braces. A
+ compound statement is used in order to put several statements
+ together in the body of an `if', `while', `do', or `for' statement.
+
+Input statements
+ Use the `getline' command (*note Explicit Input with `getline':
+ Getline.). Also supplied in `awk' are the `next' statement (*note
+ The `next' Statement: Next Statement.), and the `nextfile'
+ statement (*note Using `gawk''s `nextfile' Statement: Nextfile
+ Statement.).
- * Output statements, such as `print' and `printf'. *Note Printing
- Output: Printing.
+Output statements
+ Such as `print' and `printf'. *Note Printing Output: Printing.
- * Deletion statements for deleting array elements. *Note The
- `delete' Statement: Delete.
+Deletion statements
+ For deleting array elements. *Note The `delete' Statement: Delete.

File: gawk.info, Node: Statements, Next: Built-in Variables, Prev: Action Overview, Up: Patterns and Actions
@@ -7108,7 +7113,7 @@ The CONDITION is an expression that controls what the rest of the
statement does. If the CONDITION is true, THEN-BODY is executed;
otherwise, ELSE-BODY is executed. The `else' part of the statement is
optional. The condition is considered false if its value is zero or
-the null string; otherwise the condition is true. Refer to the
+the null string; otherwise, the condition is true. Refer to the
following:
if (x % 2 == 0)
@@ -7118,7 +7123,7 @@ following:
In this example, if the expression `x % 2 == 0' is true (that is, if
the value of `x' is evenly divisible by two), then the first `print'
-statement is executed; otherwise the second `print' statement is
+statement is executed; otherwise, the second `print' statement is
executed. If the `else' keyword appears on the same line as THEN-BODY
and THEN-BODY is not a compound statement (i.e., not surrounded by
curly braces), then a semicolon must separate THEN-BODY from the `else'.
@@ -7210,7 +7215,7 @@ false to begin with. The following is an example of a `do' statement:
} while (i <= 10)
}
-This program prints each input record ten times. However, it isn't a
+This program prints each input record 10 times. However, it isn't a
very realistic example, since in this case an ordinary `while' would do
just as well. This situation reflects actual experience; only
occasionally is there a real use for a `do' statement.
@@ -7381,10 +7386,10 @@ illustrates this fact:
print ""
}
-This program prints all the numbers from 0 to 20--except for five, for
+This program prints all the numbers from 0 to 20--except for 5, for
which the `printf' is skipped. Because the increment `x++' is not
-skipped, `x' does not remain stuck at five. Contrast the `for' loop
-from the previous example with the following `while' loop:
+skipped, `x' does not remain stuck at 5. Contrast the `for' loop from
+the previous example with the following `while' loop:
BEGIN {
x = 0
@@ -7397,7 +7402,7 @@ from the previous example with the following `while' loop:
print ""
}
-This program loops forever once `x' reaches five.
+This program loops forever once `x' reaches 5.
The `continue' statement has no meaning when used outside the body of
a loop. Historical versions of `awk' treated a `continue' statement
@@ -7446,8 +7451,8 @@ beginning, in the following manner:
Because of the `next' statement, the program's subsequent rules won't
see the bad record. The error message is redirected to the standard
-error output stream, as error messages should be. *Note Special File
-Names in `gawk': Special Files.
+error output stream, as error messages should be. For more detail see
+*Note Special File Names in `gawk': Special Files.
According to the POSIX standard, the behavior is undefined if the
`next' statement is used in a `BEGIN' or `END' rule. `gawk' treats it
@@ -7571,14 +7576,14 @@ File: gawk.info, Node: Built-in Variables, Prev: Statements, Up: Patterns and
Built-in Variables
==================
- Most `awk' variables are available for you to use for your own
-purposes; they never change unless your program assigns values to them,
-and they never affect anything unless your program examines them.
-However, a few variables in `awk' have special built-in meanings.
-`awk' examines some of these automatically, so that they enable you to
-tell `awk' how to do certain things. Others are set automatically by
-`awk', so that they carry information from the internal workings of
-`awk' to your program.
+ Most `awk' variables are available to use for your own purposes;
+they never change unless your program assigns values to them, and they
+never affect anything unless your program examines them. However, a
+few variables in `awk' have special built-in meanings. `awk' examines
+some of these automatically, so that they enable you to tell `awk' how
+to do certain things. Others are set automatically by `awk', so that
+they carry information from the internal workings of `awk' to your
+program.
This minor node documents all the built-in variables of `gawk', most
of which are also documented in the chapters describing their areas of
@@ -7603,8 +7608,8 @@ change to control how `awk' does certain things. The variables that are
specific to `gawk' are marked with a pound sign (`#').
`BINMODE #'
- On non-POSIX systems, this variable specifies use of "binary" mode
- for all I/O. Numeric values of one, two, or three, specify that
+ On non-POSIX systems, this variable specifies use of binary mode
+ for all I/O. Numeric values of one, two, or three specify that
input files, output files, or all files, respectively, should use
binary I/O. Alternatively, string values of `"r"' or `"w"'
specify that input files and output files, respectively, should
@@ -7667,7 +7672,7 @@ specific to `gawk' are marked with a pound sign (`#').
`IGNORECASE #'
If `IGNORECASE' is nonzero or non-null, then all string comparisons
- and all regular expression matching are case-independent. Thus,
+ and all regular expression matching are case independent. Thus,
regexp matching with `~' and `!~', as well as the `gensub',
`gsub', `index', `match', `split', and `sub' functions, record
termination with `RS', and field splitting with `FS', all ignore
@@ -7684,7 +7689,7 @@ specific to `gawk' are marked with a pound sign (`#').
as if the `--lint' command-line option is in effect. (*note
Command-Line Options: Options.). With a value of `"fatal"', lint
warnings become fatal errors. Any other true value prints
- non-fatal warnings. Assigning a false value to `LINT' turns off
+ nonfatal warnings. Assigning a false value to `LINT' turns off
the lint warnings.
This variable is a `gawk' extension. It is not special in other
@@ -7740,7 +7745,7 @@ specific to `gawk' are marked with a pound sign (`#').
This variable is used for internationalization of programs at the
`awk' level. It sets the default text domain for specially marked
string constants in the source text, as well as for the
- `dcgettext' and `bindtextdomain' functions (*note
+ `dcgettext', `dcngettext' and `bindtextdomain' functions (*note
Internationalization with `gawk': Internationalization.). The
default value of `TEXTDOMAIN' is `"messages"'.
@@ -7779,7 +7784,7 @@ with an asterisk (`*').
-| BBS-list
`ARGV[0]' contains `"awk"', `ARGV[1]' contains
- `"inventory-shipped"' and `ARGV[2]' contains `"BBS-list"'. The
+ `"inventory-shipped"', and `ARGV[2]' contains `"BBS-list"'. The
value of `ARGC' is three, one more than the index of the last
element in `ARGV', because the elements are numbered from zero.
@@ -7794,9 +7799,9 @@ with an asterisk (`*').
variables.
`ARGIND #'
- This is the index in `ARGV' of the current file being processed.
- Every time `gawk' opens a new data file for processing, it sets
- `ARGIND' to the index in `ARGV' of the file name. When `gawk' is
+ The index in `ARGV' of the current file being processed. Every
+ time `gawk' opens a new data file for processing, it sets `ARGIND'
+ to the index in `ARGV' of the file name. When `gawk' is
processing the input files, `FILENAME == ARGV[ARGIND]' is always
true.
@@ -7836,29 +7841,29 @@ with an asterisk (`*').
Command-Line Options: Options.), it is not special.
`FILENAME'
- This is the name of the file that `awk' is currently reading.
- When no data files are listed on the command line, `awk' reads
- from the standard input and `FILENAME' is set to `"-"'.
- `FILENAME' is changed each time a new file is read (*note Reading
- Input Files: Reading Files.). Inside a `BEGIN' rule, the value of
- `FILENAME' is `""', since there are no input files being processed
- yet.(1) (d.c.) Note though, that using `getline' (*note Explicit
- Input with `getline': Getline.) inside a `BEGIN' rule can give
+ The name of the file that `awk' is currently reading. When no
+ data files are listed on the command line, `awk' reads from the
+ standard input and `FILENAME' is set to `"-"'. `FILENAME' is
+ changed each time a new file is read (*note Reading Input Files:
+ Reading Files.). Inside a `BEGIN' rule, the value of `FILENAME' is
+ `""', since there are no input files being processed yet.(1)
+ (d.c.) Note, though, that using `getline' (*note Explicit Input
+ with `getline': Getline.) inside a `BEGIN' rule can give
`FILENAME' a value.
`FNR'
- This is the current record number in the current file. `FNR' is
+ The current record number in the current file. `FNR' is
incremented each time a new record is read (*note Explicit Input
with `getline': Getline.). It is reinitialized to zero each time
a new input file is started.
`NF'
- This is the number of fields in the current input record. `NF' is
- set each time a new record is read, when a new field is created or
+ The number of fields in the current input record. `NF' is set
+ each time a new record is read, when a new field is created or
when `$0' changes (*note Examining Fields: Fields.).
`NR'
- This is the number of input records `awk' has processed since the
+ The number of input records `awk' has processed since the
beginning of the program's execution (*note How Input Is Split
into Records: Records.). `NR' is incremented each time a new
record is read.
@@ -7905,17 +7910,17 @@ with an asterisk (`*').
Options.), it is not special.
`RLENGTH'
- This is the length of the substring matched by the `match' function
- (*note String Manipulation Functions: String Functions.).
- `RLENGTH' is set by invoking the `match' function. Its value is
- the length of the matched string, or -1 if no match is found.
+ The length of the substring matched by the `match' function (*note
+ String Manipulation Functions: String Functions.). `RLENGTH' is
+ set by invoking the `match' function. Its value is the length of
+ the matched string, or -1 if no match is found.
`RSTART'
- This is the start-index in characters of the substring that is
- matched by the `match' function (*note String Manipulation
- Functions: String Functions.). `RSTART' is set by invoking the
- `match' function. Its value is the position of the string where
- the matched substring starts, or zero if no match was found.
+ The start-index in characters of the substring that is matched by
+ the `match' function (*note String Manipulation Functions: String
+ Functions.). `RSTART' is set by invoking the `match' function.
+ Its value is the position of the string where the matched
+ substring starts, or zero if no match was found.
`RT #'
This is set each time a record is read. It contains the input text
@@ -8138,12 +8143,12 @@ example, conceptually, if the element values are 8, `"foo"', `""', and
0 1 2 3 Index
Only the values are stored; the indices are implicit from the order of
-the values. 8 is the value at index zero, because 8 appears in the
+the values. Here, 8 is the value at index zero, because 8 appears in the
position with zero elements before it.
Arrays in `awk' are different--they are "associative". This means
-that each array is a collection of pairs: an index, and its
-corresponding array element value:
+that each array is a collection of pairs: an index and its corresponding
+array element value:
Element 3 Value 30
Element 1 Value "foo"
@@ -8169,7 +8174,7 @@ It has elements 0-3 and 10, but doesn't have elements 4, 5, 6, 7, 8, or
Another consequence of associative arrays is that the indices don't
have to be positive integers. Any number, or even a string, can be an
index. For example, the following is an array that translates words
-from English into French:
+from English to French:
Element "dog" Value "chien"
Element "cat" Value "chat"
@@ -8224,10 +8229,10 @@ index, use the following expression:
INDEX in ARRAY
-This expression tests whether or not the particular index exists,
-without the side effect of creating that element if it is not present.
-The expression has the value one (true) if `ARRAY[INDEX]' exists and
-zero (false) if it does not exist. For example, this statement tests
+This expression tests whether the particular index exists, without the
+side effect of creating that element if it is not present. The
+expression has the value one (true) if `ARRAY[INDEX]' exists and zero
+(false) if it does not exist. For example, this statement tests
whether the array `frequencies' contains the index `2':
if (2 in frequencies)
@@ -8293,7 +8298,7 @@ following input:
1 Who is number one?
3 I three you.
-its output is:
+Its output is:
1 Who is number one?
2 Who are you? The new number two!
@@ -8363,9 +8368,9 @@ example of this type.
statement is determined by the internal arrangement of the array
elements within `awk' and cannot be controlled or changed. This can
lead to problems if new elements are added to ARRAY by statements in
-the loop body; it is not predictable whether or not the `for' loop will
-reach them. Similarly, changing VAR inside the loop may produce
-strange results. It is best to avoid such things.
+the loop body; it is not predictable whether the `for' loop will reach
+them. Similarly, changing VAR inside the loop may produce strange
+results. It is best to avoid such things.

File: gawk.info, Node: Delete, Next: Numeric Array Subscripts, Prev: Scanning an Array, Up: Arrays
@@ -8419,7 +8424,7 @@ compatibility mode (*note Command-Line Options: Options.).
more efficient than the equivalent loop that deletes each element one
at a time.
- The following statement provides a portable but non-obvious way to
+ The following statement provides a portable but nonobvious way to
clear out an array:(1)
split("", array)
@@ -8480,8 +8485,8 @@ to be. So the usual case of the following works:
The "integer values always convert to strings as integers" rule has
an additional consequence for array indexing. Octal and hexadecimal
-constants (*note Octal and Hexadecimal Numbers: Non-decimal-numbers.)
-are converted internally into numbers and their original form is
+constants (*note Octal and Hexadecimal Numbers: Nondecimal-numbers.)
+are converted internally into numbers, and their original form is
forgotten. This means, for example, that `array[17]', `array[021]', and
`array[0x11]' all refer to the same element!
@@ -8569,7 +8574,7 @@ it was stored with a single index or a sequence of indices. The two
expressions `foo[5,12]' and `foo[5 SUBSEP 12]' are always equivalent.
The default value of `SUBSEP' is the string `"\034"', which contains
-a non-printing character that is unlikely to appear in an `awk' program
+a nonprinting character that is unlikely to appear in an `awk' program
or in most input data. The usefulness of choosing an unlikely
character comes from the fact that index values that contain a string
matching `SUBSEP' can lead to combined strings that are ambiguous.
@@ -8578,7 +8583,7 @@ Suppose that `SUBSEP' is `"@"'; then `foo["a@b", "c"]' and
stored as `foo["a@b@c"]'.
To test whether a particular index sequence exists in a
-"multidimensional" array, use the same operator (`in') that is used for
+multidimensional array, use the same operator (`in') that is used for
single dimensional arrays. Write the whole sequence of indices in
parentheses, separated by commas, as the left operand:
@@ -8586,7 +8591,7 @@ parentheses, separated by commas, as the left operand:
The following example treats its input as a two-dimensional array of
fields; it rotates this array 90 degrees clockwise and prints the
-result. It assumes that all lines have the same number of elements.
+result. It assumes that all lines have the same number of elements:
{
if (max_nf < NF)
@@ -8627,7 +8632,7 @@ Scanning Multidimensional Arrays
================================
There is no special `for' statement for scanning a
-"multidimensional" array. There cannot be one, because in truth there
+"multidimensional" array. There cannot be one, because, in truth, there
are no multidimensional arrays or elements--there is only a
multidimensional _way of accessing_ an array.
@@ -8740,7 +8745,7 @@ Functions
This major node describes `awk''s built-in functions, which fall
into three categories: numeric, string, and I/O. `gawk' provides
additional groups of functions to work with values that represent time,
-do bit manipulation, and to internationalize and localize programs.
+do bit manipulation, and internationalize and localize programs.
Besides the built-in functions, `awk' has provisions for writing new
functions that the rest of a program can use. The second half of this
@@ -8782,7 +8787,7 @@ Calling Built-in Functions
To call one of `awk''s built-in functions, write the name of the
function followed by arguments in parentheses. For example, `atan2(y +
-z, 1)' is a call to the function `atan2', and has two arguments.
+z, 1)' is a call to the function `atan2' and has two arguments.
Whitespace is ignored between the built-in function name and the
open parenthesis, and it is good practice to avoid using whitespace
@@ -8814,9 +8819,9 @@ are evaluated from left to right or from right to left. For example:
j = atan2(i++, i *= 2)
If the order of evaluation is left to right, then `i' first becomes
-six, and then 12, and `atan2' is called with the two arguments 6 and
-12. But if the order of evaluation is right to left, `i' first becomes
-10, then 11, and `atan2' is called with the two arguments 11 and 10.
+6, and then 12, and `atan2' is called with the two arguments 6 and 12.
+But if the order of evaluation is right to left, `i' first becomes 10,
+then 11, and `atan2' is called with the two arguments 11 and 10.

File: gawk.info, Node: Numeric Functions, Next: String Functions, Prev: Calling Built-in, Up: Built-in
@@ -8826,18 +8831,18 @@ Numeric Functions
The following list describes all of the built-in functions that work
with numbers. Optional parameters are enclosed in square brackets ([
-and ]):
+]):
`int(X)'
This returns the nearest integer to X, located between X and zero
and truncated toward zero.
- For example, `int(3)' is three, `int(3.9)' is three, `int(-3.9)'
- is -3, and `int(-3)' is -3 as well.
+ For example, `int(3)' is 3, `int(3.9)' is 3, `int(-3.9)' is -3,
+ and `int(-3)' is -3 as well.
`sqrt(X)'
This returns the positive square root of X. `gawk' reports an
- error if X is negative. Thus, `sqrt(4)' is two.
+ error if X is negative. Thus, `sqrt(4)' is 2.
`exp(X)'
This returns the exponential of X (`e ^ X') or reports an error if
@@ -8876,7 +8881,7 @@ and ]):
The following example uses a similar function to produce random
integers between one and N. This program prints a new random
- number for each input record.
+ number for each input record:
# Function to roll a simulated die.
function roll(n) { return 1 + int(rand() * n) }
@@ -8905,7 +8910,7 @@ and ]):
numbers.(2) Thus, if the seed is set to the same value a second
time, the same sequence of random numbers is produced again.
- Different `awk' implementations use different random number
+ Different `awk' implementations use different random-number
generators internally. Don't expect the same `awk' program to
produce the same series of random numbers when executed by
different versions of `awk'.
@@ -8926,21 +8931,21 @@ implementation use the C `rand' to implement the `awk' version of
`rand'. In fact, `gawk' uses the BSD `random' function, which is
considerably better than `rand', to produce random numbers.
- (2) Computer generated random numbers really are not truly random.
-They are technically known as "pseudo-random." This means that while
+ (2) Computer-generated random numbers really are not truly random.
+They are technically known as "pseudorandom." This means that while
the numbers in a sequence appear to be random, you can in fact generate
the same sequence of random numbers over and over again.

File: gawk.info, Node: String Functions, Next: I/O Functions, Prev: Numeric Functions, Up: Built-in
-String Manipulation Functions
+String-Manipulation Functions
-----------------------------
The functions in this minor node look at or change the text of one
or more strings. Optional parameters are enclosed in square brackets
-([ and ]). Those functions that are specific to `gawk' are marked with
-a pound sign (`#'):
+([ ]). Those functions that are specific to `gawk' are marked with a
+pound sign (`#'):
* Menu:
@@ -9006,9 +9011,9 @@ a pound sign (`#'):
programs to be maximally portable, always supply the parentheses.
`match(STRING, REGEXP [, ARRAY])'
- The `match' function searches STRING for the longest leftmost
+ The `match' function searches STRING for the longest, leftmost
substring matched by the regular expression, REGEXP. It returns
- the character position, or "index", where that substring begins
+ the character position, or "index", at which that substring begins
(one, if it starts at the beginning of STRING). If no match is
found, it returns zero.
@@ -9053,14 +9058,14 @@ a pound sign (`#'):
Match of ru+n found at 12 in My program runs
Match of Melvin found at 1 in Melvin was here.
- If ARRAY is present, it is cleared, and then the 0'th element of
+ If ARRAY is present, it is cleared, and then the 0th element of
ARRAY is set to the entire portion of STRING matched by REGEXP.
If REGEXP contains parentheses, the integer-indexed elements of
ARRAY are set to contain the portion of STRING matching the
- corresponding parenthesized sub-expression. For example:
+ corresponding parenthesized subexpression. For example:
$ echo foooobazbarrrrr |
- > gawk '{ match($0, /(fo+).+(ba*r)/, arr)
+ > gawk '{ match($0, /(fo+).+(bar*)/, arr)
> print arr[1], arr[2] }'
-| foooo barrrrr
@@ -9069,15 +9074,14 @@ a pound sign (`#'):
third argument is a fatal error.
`split(STRING, ARRAY [, FIELDSEP])'
- This function divides STRING into pieces separated by FIELDSEP,
- and stores the pieces in ARRAY. The first piece is stored in
+ This function divides STRING into pieces separated by FIELDSEP and
+ stores the pieces in ARRAY. The first piece is stored in
`ARRAY[1]', the second piece in `ARRAY[2]', and so forth. The
string value of the third argument, FIELDSEP, is a regexp
describing where to split STRING (much as `FS' can be a regexp
- describing where to split input records). If the FIELDSEP is
- omitted, the value of `FS' is used. `split' returns the number of
- elements created. If STRING does not match FIELDSEP, ARRAY is
- empty and `split' returns zero.
+ describing where to split input records). If FIELDSEP is omitted,
+ the value of `FS' is used. `split' returns the number of elements
+ created.
The `split' function splits strings into pieces in a manner
similar to the way input lines are split into fields. For example:
@@ -9094,7 +9098,7 @@ a pound sign (`#'):
The value returned by this call to `split' is three.
As with input field-splitting, when the value of FIELDSEP is
- `" "', leading and trailing whitespace is ignored and the elements
+ `" "', leading and trailing whitespace is ignored, and the elements
are separated by runs of whitespace. Also as with input
field-splitting, if FIELDSEP is the null string, each individual
character in the string is split into its own array element.
@@ -9137,7 +9141,7 @@ a pound sign (`#'):
`sub(REGEXP, REPLACEMENT [, TARGET])'
The `sub' function alters the value of TARGET. It searches this
- value, which is treated as a string, for the leftmost longest
+ value, which is treated as a string, for the leftmost, longest
substring matched by the regular expression REGEXP. Then the
entire string is changed by replacing the matched text with
REPLACEMENT. The modified string becomes the new value of TARGET.
@@ -9174,7 +9178,7 @@ a pound sign (`#'):
> }'
-| dCaaCbaaa
- This shows how `&' can represent a non-constant string and also
+ This shows how `&' can represent a nonconstant string and also
illustrates the "leftmost, longest" rule in regexp matching (*note
How Much Text Matches?: Leftmost Longest.).
@@ -9182,7 +9186,7 @@ a pound sign (`#'):
putting a backslash before it in the string. As usual, to insert
one backslash in the string, you must write two backslashes.
Therefore, write `\\&' in a string constant to include a literal
- `&' in the replacement. For example, following is shown how to
+ `&' in the replacement. For example, the following shows how to
replace the first `|' on each line with an `&':
{ sub(/\|/, "\\&"); print }
@@ -9198,7 +9202,7 @@ a pound sign (`#'):
sub(/USA/, "United States", "the USA and Canada")
For historical compatibility, `gawk' accepts erroneous code, such
- as in the previous example. However, using any other non-changeable
+ as in the previous example. However, using any other nonchangeable
object as the third parameter causes a fatal error and your program
will not run.
@@ -9208,7 +9212,7 @@ a pound sign (`#'):
`gsub(REGEXP, REPLACEMENT [, TARGET])'
This is similar to the `sub' function, except `gsub' replaces
- _all_ of the longest, leftmost, _non-overlapping_ matching
+ _all_ of the longest, leftmost, _nonoverlapping_ matching
substrings it can find. The `g' in `gsub' stands for "global,"
which means replace everywhere. For example:
@@ -9248,10 +9252,8 @@ a pound sign (`#'):
-| def abc
As with `sub', you must type two backslashes in order to get one
- into the string.
-
- In the replacement text, the sequence `\0' represents the entire
- matched text, as does the character `&'.
+ into the string. In the replacement text, the sequence `\0'
+ represents the entire matched text, as does the character `&'.
The following example shows how you can use the third argument to
control which match of the regexp should be changed:
@@ -9285,7 +9287,12 @@ a pound sign (`#'):
STRING that begins at character number START. For example,
`substr("washington", 5)' returns `"ington"'. The whole suffix is
also returned if LENGTH is greater than the number of characters
- remaining in the string, counting from character number START.
+ remaining in the string, counting from character START.
+
+ If START is less than one or greater than the number of characters
+ in the string, `substr' returns the null string. Similarly, if
+ LENGTH is present but less than or equal to zero, the null string
+ is returned.
The string returned by `substr' _cannot_ be assigned. Thus, it is
a mistake to attempt to change a portion of a string, as shown in
@@ -9313,23 +9320,23 @@ a pound sign (`#'):
`tolower(STRING)'
This returns a copy of STRING, with each uppercase character in
the string replaced with its corresponding lowercase character.
- Non-alphabetic characters are left unchanged. For example,
+ Nonalphabetic characters are left unchanged. For example,
`tolower("MiXeD cAsE 123")' returns `"mixed case 123"'.
`toupper(STRING)'
This returns a copy of STRING, with each lowercase character in
the string replaced with its corresponding uppercase character.
- Non-alphabetic characters are left unchanged. For example,
+ Nonalphabetic characters are left unchanged. For example,
`toupper("MiXeD cAsE 123")' returns `"MIXED CASE 123"'.
---------- Footnotes ----------
(1) Unless you use the `--non-decimal-data' option, which isn't
-recommended. *Note Allowing Non-Decimal Input Data: Non-decimal Data,
+recommended. *Note Allowing Nondecimal Input Data: Nondecimal Data,
for more information.
- (2) This is different from C and C++, where the first character is
-number zero.
+ (2) This is different from C and C++, in which the first character
+is number zero.

File: gawk.info, Node: Gory Details, Prev: String Functions, Up: String Functions
@@ -9376,7 +9383,7 @@ illustrate with a table:
This table shows both the lexical-level processing, where an odd number
of backslashes becomes an even number at the runtime level, as well as
the runtime processing done by `sub'. (For the sake of simplicity, the
-rest of the tables below only show the case of even numbers of
+rest of the following tables only show the case of even numbers of
backslashes entered at the lexical level.)
The problem with the historical approach is that there is no way to
@@ -9435,8 +9442,8 @@ specifies; this Info file will be updated as well.(2)
level, whenever `gawk' sees a `\', if the following character is a
digit, then the text that matched the corresponding parenthesized
subexpression is placed in the generated output. Otherwise, no matter
-what the character after the `\' is, it appears in the generated text
-and the `\' does not:
+what character follows the `\', it appears in the generated text and
+the `\' does not:
You type `gensub' sees `gensub' generates
-------- ------------- ------------------
@@ -9477,8 +9484,8 @@ File: gawk.info, Node: I/O Functions, Next: Time Functions, Prev: String Func
Input/Output Functions
----------------------
- The following functions relate to Input/Output (I/O). Optional
-parameters are enclosed in square brackets ([ and ]):
+ The following functions relate to input/output (I/O). Optional
+parameters are enclosed in square brackets ([ ]):
`close(FILENAME [, HOW])'
Close the file FILENAME for input or output. Alternatively, the
@@ -9488,7 +9495,7 @@ parameters are enclosed in square brackets ([ and ]):
Redirections: Close Files And Pipes, for more information.
When closing a coprocess, it is occasionally useful to first close
- one end of the two-way pipe, and then to close the other. This is
+ one end of the two-way pipe and then to close the other. This is
done by providing a second argument to `close'. This second
argument should be one of the two string values `"to"' or `"from"',
indicating which end of the pipe to close. Case in the string does
@@ -9502,7 +9509,7 @@ parameters are enclosed in square brackets ([ and ]):
redirecting output to a pipe or coprocess.
Many utility programs "buffer" their output; i.e., they save
- information to write to a disk file or terminal in memory, until
+ information to write to a disk file or terminal in memory until
there is enough for it to be worthwhile to send the data to the
output device. This is often more efficient than writing every
little bit of information as soon as it is ready. However,
@@ -9524,22 +9531,21 @@ parameters are enclosed in square brackets ([ and ]):
output files and pipes are flushed.
`fflush' returns zero if the buffer is successfully flushed;
- otherwise it returns -1. In the case where all buffers are
+ otherwise, it returns -1. In the case where all buffers are
flushed, the return value is zero only if all buffers were flushed
successfully. Otherwise, it is -1, and `gawk' warns about the
- FILENAME that had the problem.
+ problem FILENAME.
`gawk' also issues a warning message if you attempt to flush a
file or pipe that was opened for reading (such as with `getline'),
or if FILENAME is not an open file, pipe, or coprocess. In such a
- case, `fflush' returns -1 as well.
+ case, `fflush' returns -1, as well.
`system(COMMAND)'
- The `system' function allows the user to execute operating system
- commands and then return to the `awk' program. The `system'
- function executes the command given by the string COMMAND. It
- returns the status returned by the command that was executed as
- its value.
+ Executes operating-system commands and then returns to the `awk'
+ program. The `system' function executes the command given by the
+ string COMMAND. It returns the status returned by the command
+ that was executed as its value.
For example, if the following fragment of code is put in your `awk'
program:
@@ -9565,15 +9571,15 @@ parameters are enclosed in square brackets ([ and ]):
an editor. Some operating systems cannot implement the `system'
function. `system' causes a fatal error if it is not supported.
-Advanced Notes: Interactive Versus Non-Interactive Buffering
-------------------------------------------------------------
+Advanced Notes: Interactive Versus Noninteractive Buffering
+-----------------------------------------------------------
As a side point, buffering issues can be even more confusing,
-depending upon whether your program is "interactive"; i.e.,
+depending upon whether your program is "interactive", i.e.,
communicating with a user sitting at a keyboard.(1)
Interactive programs generally "line buffer" their output; i.e., they
-write out every line. Non-interactive programs wait until they have a
+write out every line. Noninteractive programs wait until they have a
full buffer, which may be many lines of output. Here is an example of
the difference:
@@ -9638,8 +9644,8 @@ and not:
first print
second print
- If `awk' did not flush its buffers before calling `system', the
-latter (undesirable) output is what you see.
+ If `awk' did not flush its buffers before calling `system', you
+would see the latter (undesirable) output.
---------- Footnotes ----------
@@ -9652,22 +9658,22 @@ File: gawk.info, Node: Time Functions, Next: Bitwise Functions, Prev: I/O Fun
Using `gawk''s Timestamp Functions
----------------------------------
- A common use for `awk' programs is the processing of log files
-containing timestamp information, indicating when a particular log
-record was written. Many programs log their timestamp in the form
-returned by the `time' system call, which is the number of seconds
-since a particular epoch. On POSIX-compliant systems, it is the number
-of seconds since 1970-01-01 00:00:00 UTC, not counting leap seconds.(1)
-All known POSIX-compliant systems support timestamps from 0 through
-2^31 - 1, which is sufficient to represent times through 2038-01-19
-03:14:07 UTC. Many systems support a wider range of timestamps,
-including negative timestamps that represent times before the epoch.
+ `awk' programs are commonly used to process log files containing
+timestamp information, indicating when a particular log record was
+written. Many programs log their timestamp in the form returned by the
+`time' system call, which is the number of seconds since a particular
+epoch. On POSIX-compliant systems, it is the number of seconds since
+1970-01-01 00:00:00 UTC, not counting leap seconds.(1) All known
+POSIX-compliant systems support timestamps from 0 through 2^31 - 1,
+which is sufficient to represent times through 2038-01-19 03:14:07 UTC.
+Many systems support a wider range of timestamps, including negative
+timestamps that represent times before the epoch.
In order to make it easier to process such log files and to produce
useful reports, `gawk' provides the following functions for working
with timestamps. They are `gawk' extensions; they are not specified in
the POSIX standard, nor are they in any other known version of `awk'.(2)
-Optional parameters are enclosed in square brackets ([ and ]):
+Optional parameters are enclosed in square brackets ([ ]):
`systime()'
This function returns the current time as the number of seconds
@@ -9683,13 +9689,13 @@ Optional parameters are enclosed in square brackets ([ and ]):
seven numbers representing, respectively, the full year including
century, the month from 1 to 12, the day of the month from 1 to
31, the hour of the day from 0 to 23, the minute from 0 to 59, the
- second from 0 to 60,(3) and an optional daylight savings flag.
+ second from 0 to 60,(3) and an optional daylight-savings flag.
The values of these numbers need not be within the ranges
specified; for example, an hour of -1 means 1 hour before midnight.
The origin-zero Gregorian calendar is assumed, with year 0
preceding year 1 and year -1 preceding year 0. The time is
- assumed to be in the local timezone. If the daylight savings flag
+ assumed to be in the local timezone. If the daylight-savings flag
is positive, the time is assumed to be daylight savings time; if
zero, the time is assumed to be standard time; and if negative
(the default), `mktime' attempts to determine whether daylight
@@ -9724,7 +9730,7 @@ file.
The `strftime' function allows you to easily turn a timestamp into
human-readable information. It is similar in nature to the `sprintf'
function (*note String Manipulation Functions: String Functions.), in
-that it copies non-format specification characters verbatim to the
+that it copies nonformat specification characters verbatim to the
returned string, while substituting date and time values for format
specifications in the FORMAT string.
@@ -9766,9 +9772,9 @@ the following date format specifications:
`%g'
The year modulo 100 of the ISO week number, as a decimal number
- (00-99). For example, January 1, 1993, is in week 53 of 1992.
+ (00-99). For example, January 1, 1993 is in week 53 of 1992.
Thus, the year of its ISO week number is 1992, even though its
- year is 1993. Similarly, December 31, 1973, is in week 1 of 1974.
+ year is 1993. Similarly, December 31, 1973 is in week 1 of 1974.
Thus, the year of its ISO week number is 1974, even though its
year is 1973.
@@ -9811,7 +9817,7 @@ the following date format specifications:
The second as a decimal number (00-60).
`%t'
- A tab character.
+ A TAB character.
`%T'
Equivalent to specifying `%H:%M:%S'.
@@ -9828,7 +9834,7 @@ the following date format specifications:
week one) as a decimal number (01-53). The method for determining
the week number is as specified by ISO 8601. (To wit: if the week
containing January 1 has four or more days in the new year, then
- it is week one, otherwise it is week 53 of the previous year and
+ it is week one; otherwise it is week 53 of the previous year and
the next week is week one.)
`%w'
@@ -9862,9 +9868,9 @@ the following date format specifications:
`%Ec %EC %Ex %EX %Ey %EY %Od %Oe %OH'
`%OI %Om %OM %OS %Ou %OU %OV %Ow %OW %Oy'
- These are "alternate representations" for the specifications that
- use only the second letter (`%c', `%C', and so on).(5) (These
- facilitate compliance with the POSIX `date' utility.)
+ "Alternate representations" for the specifications that use only
+ the second letter (`%c', `%C', and so on).(5) (These facilitate
+ compliance with the POSIX `date' utility.)
`%%'
A literal `%'.
@@ -9888,11 +9894,11 @@ compile `gawk' (*note Installing `gawk': Installation.), then the
following additional format specifications are available:
`%k'
- The hour (24-hour clock) as a decimal number (0-23). Single digit
+ The hour (24-hour clock) as a decimal number (0-23). Single-digit
numbers are padded with a space.
`%l'
- The hour (12-hour clock) as a decimal number (1-12). Single digit
+ The hour (12-hour clock) as a decimal number (1-12). Single-digit
numbers are padded with a space.
`%N'
@@ -9913,7 +9919,7 @@ normal representations are used.
This example is an `awk' implementation of the POSIX `date' utility.
Normally, the `date' utility prints the current date and time of day
in a well-known format. However, if you provide an argument to it that
-begins with a `+', `date' copies non-format specifier characters to the
+begins with a `+', `date' copies nonformat specifier characters to the
standard output and interprets the current time according to the format
specifiers in the string. For example:
@@ -9951,10 +9957,10 @@ if the time zone is set to UTC:
---------- Footnotes ----------
- (1) *Note Glossary::, especially the entries for "Epoch" and "UTC."
+ (1) *Note Glossary::, especially the entries "Epoch" and "UTC."
(2) The GNU `date' utility can also do many of the things described
-here. It's use may be preferable for simple time-related operations in
+here. Its use may be preferable for simple time-related operations in
shell scripts.
(3) Occasionally there are minutes in a year with a leap second,
@@ -9971,13 +9977,13 @@ Internationalization with `gawk': Internationalization.
(6) This is because ISO C leaves the behavior of the C version of
`strftime' undefined and `gawk' uses the system's version of `strftime'
if it's there. Typically, the conversion specifier either does not
-appear in the returned string or it appears literally.
+appear in the returned string or appears literally.

File: gawk.info, Node: Bitwise Functions, Next: I18N Functions, Prev: Time Functions, Up: Built-in
-Using `gawk''s Bit Manipulation Functions
------------------------------------------
+Bit-Manipulation Functions of `gawk'
+------------------------------------
I can explain it for you, but I can't understand it for you.
Anonymous
@@ -10010,15 +10016,15 @@ again with `10111001' and shift it left by three bits, you end up with
`11001000'. `gawk' provides built-in functions that implement the
bitwise operations just described. They are:
-`and(V1, V2)' Return the bitwise AND of the values provided by V1
+`and(V1, V2)' Returns the bitwise AND of the values provided by V1
and V2.
-`or(V1, V2)' Return the bitwise OR of the values provided by V1 and
- V2.
-`xor(V1, V2)' Return the bitwise XOR of the values provided by V1
+`or(V1, V2)' Returns the bitwise OR of the values provided by V1
and V2.
-`compl(VAL)' Return the bitwise complement of VAL.
-`lshift(VAL, COUNT)' Return the value of VAL, shifted left by COUNT bits.
-`rshift(VAL, COUNT)' Return the value of VAL, shifted right by COUNT bits.
+`xor(V1, V2)' Returns the bitwise XOR of the values provided by V1
+ and V2.
+`compl(VAL)' Returns the bitwise complement of VAL.
+`lshift(VAL, COUNT)' Returns the value of VAL, shifted left by COUNT bits.
+`rshift(VAL, COUNT)' Returns the value of VAL, shifted right by COUNT bits.
For all of these functions, first the double-precision
floating-point value is converted to a C `unsigned long', then the
@@ -10071,18 +10077,18 @@ This program produces the following output when run:
The `bits2str' function turns a binary number into a string. The
number `1' represents a binary value where the rightmost bit is set to
1. Using this mask, the function repeatedly checks the rightmost bit.
-AND-ing the mask with the value indicates whether the rightmost bit is
-1 or not. If so, a `"1"' is concatenated onto the front of the string.
+ANDing the mask with the value indicates whether the rightmost bit is 1
+or not. If so, a `"1"' is concatenated onto the front of the string.
Otherwise, a `"0"' is added. The value is then shifted right by one
bit and the loop continues until there are no more 1 bits.
If the initial value is zero it returns a simple `"0"'. Otherwise,
at the end, it pads the value with zeros to represent multiples of
-eight-bit quantities. This is typical in modern computers.
+8-bit quantities. This is typical in modern computers.
The main code in the `BEGIN' rule shows the difference between the
decimal and octal values for the same numbers (*note Octal and
-Hexadecimal Numbers: Non-decimal-numbers.), and then demonstrates the
+Hexadecimal Numbers: Nondecimal-numbers.), and then demonstrates the
results of the `compl', `lshift', and `rshift' functions.
---------- Footnotes ----------
@@ -10094,14 +10100,14 @@ have the left side fill with 1's. Caveat emptor.

File: gawk.info, Node: I18N Functions, Prev: Bitwise Functions, Up: Built-in
-Using `gawk''s String Translation Functions
+Using `gawk''s String-Translation Functions
-------------------------------------------
`gawk' provides facilities for internationalizing `awk' programs.
These include the functions described in the following list. The
-description here is purposely brief. *Note Internationalization with
+descriptions here are purposely brief. *Note Internationalization with
`gawk': Internationalization, for the full story. Optional parameters
-are enclosed in square brackets ([ and ]):
+are enclosed in square brackets ([ ]):
`dcgettext(STRING [, DOMAIN [, CATEGORY]])'
This function returns the translation of STRING in text domain
@@ -10109,11 +10115,19 @@ are enclosed in square brackets ([ and ]):
is the current value of `TEXTDOMAIN'. The default value for
CATEGORY is `"LC_MESSAGES"'.
+`dcngettext(STRING1, STRING2, NUMBER [, DOMAIN [, CATEGORY]])'
+ This function returns the plural form used for NUMBER of the
+ translation of STRING1 and STRING2 in text domain DOMAIN for
+ locale category CATEGORY. STRING1 is the English singular variant
+ of a message, and STRING2 the English plural variant of the same
+ message. The default value for DOMAIN is the current value of
+ `TEXTDOMAIN'. The default value for CATEGORY is `"LC_MESSAGES"'.
+
`bindtextdomain(DIRECTORY [, DOMAIN])'
- This function allows you to specify the directory where `gawk'
+ This function allows you to specify the directory in which `gawk'
will look for message translation files, in case they will not or
cannot be placed in the "standard" locations (e.g., during
- testing). It returns the directory where DOMAIN is "bound."
+ testing). It returns the directory in which DOMAIN is "bound."
The default DOMAIN is the value of `TEXTDOMAIN'. If DIRECTORY is
the null string (`""'), then `bindtextdomain' returns the current
@@ -10127,7 +10141,7 @@ User-Defined Functions
Complicated `awk' programs can often be simplified by defining your
own functions. User-defined functions can be called just like built-in
-ones (*note Function Calls::), but it is up to you to define them;
+ones (*note Function Calls::), but it is up to you to define them,
i.e., to tell `awk' what they should do.
* Menu:
@@ -10161,7 +10175,7 @@ starting to execute any of it.
NAME is the name of the function to define. A valid function name is
like a valid variable name: a sequence of letters, digits, and
-underscores, that doesn't start with a digit. Within a single `awk'
+underscores that doesn't start with a digit. Within a single `awk'
program, any particular name can only be used as a variable, array, or
function.
@@ -10196,7 +10210,7 @@ arguments and the local variables, in order to document how your
function is supposed to be used.
During execution of the function body, the arguments and local
-variable values hide or "shadow" any variables of the same names used
+variable values hide, or "shadow", any variables of the same names used
in the rest of the program. The shadowed variables are not accessible
in the function definition, because there is no way to name them while
their names have been taken away for the local variables. All other
@@ -10276,13 +10290,13 @@ The `delete' Statement: Delete.). Instead of having to repeat this
loop everywhere that you need to clear out an array, your program can
just call `delarray'. (This guarantees portability. The use of
`delete ARRAY' to delete the contents of an entire array is a
-non-standard extension.)
+nonstandard extension.)
The following is an example of a recursive function. It takes a
string as an input parameter and returns the string in backwards order.
Recursive functions must always have a test that stops the recursion.
In this case, the recursion terminates when the starting position is
-zero; i.e., when there are no more characters left in the string.
+zero, i.e., when there are no more characters left in the string.
function rev(str, start)
{
@@ -10364,7 +10378,7 @@ does this:
print str
}
-to change its first argument variable `str', it _does not_ change the
+to change its first argument variable `str', it does _not_ change the
value of `foo' in the caller. The role of `foo' in calling `myfunc'
ended when its value (`"bar"') was computed. If `str' also exists
outside of `myfunc', the function body cannot alter this outer value,
@@ -10392,8 +10406,8 @@ dangerous if you do not watch what you are doing. For example:
a[1], a[2], a[3]
}
-This program prints `a[1] = 1, a[2] = two, a[3] = 3', because
-`changeit' stores `"two"' in the second element of `a'.
+prints `a[1] = 1, a[2] = two, a[3] = 3', because `changeit' stores
+`"two"' in the second element of `a'.
Some `awk' implementations allow you to call a function that has not
been defined. They only report a problem at runtime when the program
@@ -10409,7 +10423,7 @@ actually tries to call the function. For example:
# note that `foo' is not defined
Because the `if' statement will never be true, it is not really a
-problem that `foo' has not been defined. Usually though, it is a
+problem that `foo' has not been defined. Usually, though, it is a
problem if a program calls an undefined function.
If `--lint' is specified (*note Command-Line Options: Options.),
@@ -10460,11 +10474,11 @@ a value for the largest number among the elements of an array:
You call `maxelt' with one argument, which is an array name. The local
variables `i' and `ret' are not intended to be arguments; while there
-is nothing to stop you from passing two or three arguments to `maxelt',
+is nothing to stop you from passing more than one argument to `maxelt',
the results would be strange. The extra space before `i' in the
function parameter list indicates that `i' and `ret' are not supposed
-to be arguments. This is a convention that you should follow when you
-define functions.
+to be arguments. You should follow this convention when defining
+functions.
The following program uses the `maxelt' function. It loads an
array, calls `maxelt', and then reports the maximum number in that
@@ -10503,8 +10517,8 @@ the array.

File: gawk.info, Node: Dynamic Typing, Prev: Return Statement, Up: User-defined
-Functions and Their Effect on Variable Typing
----------------------------------------------
+Functions and Their Effects on Variable Typing
+----------------------------------------------
`awk' is a very fluid language. It is possible that `awk' can't
tell if an identifier represents a regular variable or an array until
@@ -10532,7 +10546,7 @@ File: gawk.info, Node: Internationalization, Next: Advanced Features, Prev: F
Internationalization with `gawk'
********************************
- Once upon a time, computer makers wrote software that only worked in
+ Once upon a time, computer makers wrote software that worked only in
English. Eventually, hardware and software vendors noticed that if
their systems worked in the native languages of non-English-speaking
countries, they were able to sell more systems. As a result,
@@ -10565,7 +10579,7 @@ Internationalization and Localization
"Internationalization" means writing (or modifying) a program once,
in such a way that it can use multiple languages without requiring
-further source code changes. "Localization" means providing the data
+further source-code changes. "Localization" means providing the data
necessary for an internationalized program to work in a particular
language. Most typically, these terms refer to features such as the
language used for printing error messages, the language used to read
@@ -10583,7 +10597,7 @@ by a program, either directly or via formatting with `printf' or
`sprintf'.(1)
When using GNU `gettext', each application has its own "text
-domain". This is a unique name such as `kpilot' or `gawk', that
+domain". This is a unique name, such as `kpilot' or `gawk', that
identifies the application. A complete application may have multiple
components--programs written in C or C++, as well as scripts written in
`sh' or `awk'. All of the components use the same text domain.
@@ -10603,7 +10617,7 @@ in this order:
to the `gettext' library, by calling the `textdomain' function.
3. Messages from the application are extracted from the source code
- and collected into a Portable Object file (`guide.po'), which
+ and collected into a portable object file (`guide.po'), which
lists the strings and their translations. The translations are
initially empty. The original (usually English) messages serve as
the key for lookup of the translations.
@@ -10662,11 +10676,11 @@ defined locale categories that `gettext' knows about are:
a different category.)
`LC_COLLATE'
- Text collation information; i.e., how different characters and/or
+ Text-collation information; i.e., how different characters and/or
groups of characters sort in a given language.
`LC_CTYPE'
- Character type information (alphabetic, digit, upper- or
+ Character-type information (alphabetic, digit, upper- or
lowercase, and so on). This information is accessed via the POSIX
character classes in regular expressions, such as `/[[:alnum:]]/'
(*note Regular Expression Operators: Regexp Operators.).
@@ -10684,7 +10698,7 @@ defined locale categories that `gettext' knows about are:
local language, and possibly other information as well.
`LC_TIME'
- Time and date related information, such as 12- or 24-hour clock,
+ Time- and date-related information, such as 12- or 24-hour clock,
month printed before or after day in a date, local month
abbreviations, and so on.
@@ -10700,7 +10714,7 @@ operating systems. Sorry.
(2) Americans use a comma every three decimal places and a period
for the decimal point, while many Europeans do exactly the opposite:
-`1,234.56' vs. `1.234,56'.
+`1,234.56' versus `1.234,56'.

File: gawk.info, Node: Programmer i18n, Next: Translator i18n, Prev: Explaining gettext, Up: Internationalization
@@ -10737,11 +10751,21 @@ internationalization:
C version. The `awk' version's order was chosen to be simple and
to allow for reasonable `awk'-style default arguments.
+`dcngettext(STRING1, STRING2, NUMBER [, DOMAIN [, CATEGORY]])'
+ This built-in function returns the plural form used for NUMBER of
+ the translation of STRING1 and STRING2 in text domain DOMAIN for
+ locale category CATEGORY. STRING1 is the English singular variant
+ of a message, and STRING2 the English plural variant of the same
+ message. The default value for DOMAIN is the current value of
+ `TEXTDOMAIN'. The default value for CATEGORY is `"LC_MESSAGES"'.
+
+ The same remarks as for the `dcgettext' function apply.
+
`bindtextdomain(DIRECTORY [, DOMAIN])'
- This built-in function allows you to specify the directory where
+ This built-in function allows you to specify the directory in which
`gettext' looks for `.mo' files, in case they will not or cannot
be placed in the standard locations (e.g., during testing). It
- returns the directory where DOMAIN is "bound."
+ returns the directory in which DOMAIN is "bound."
The default DOMAIN is the value of `TEXTDOMAIN'. If DIRECTORY is
the null string (`""'), then `bindtextdomain' returns the current
@@ -10769,7 +10793,7 @@ outlined in *Note GNU `gettext': Explaining gettext, like so:
printf(_"Number of users is %d\n", nusers)
3. If you are creating strings dynamically, you can still translate
- them, using the `dcgettext' built-in function.
+ them, using the `dcgettext' built-in function:
message = nusers " users logged in"
message = dcgettext(message, "adminprog")
@@ -10796,8 +10820,8 @@ outlined in *Note GNU `gettext': Explaining gettext, like so:
*Note A Simple Internationalization Example: I18N Example, for an
-example program showing the steps necessary to create and use
-translations from `awk'.
+example program showing the steps to create and use translations from
+`awk'.

File: gawk.info, Node: Translator i18n, Next: I18N Example, Prev: Programmer i18n, Up: Internationalization
@@ -10837,15 +10861,15 @@ to create the initial `.po' file:
Instead, it parses it as usual and prints all marked strings to
standard output in the format of a GNU `gettext' Portable Object file.
Also included in the output are any constant strings that appear as the
-first argument to `dcgettext'.(1) *Note A Simple Internationalization
-Example: I18N Example, for the full list of steps to go through to
-create and test translations for `guide'.
+first argument to `dcgettext' or as the first and second argument to
+`dcngettext'.(1) *Note A Simple Internationalization Example: I18N
+Example, for the full list of steps to go through to create and test
+translations for `guide'.
---------- Footnotes ----------
- (1) Eventually, the `xgettext' utility that comes with GNU `gettext'
-will be taught to automatically run `gawk --gen-po' for `.awk' files,
-freeing the translator from having to do it manually.
+ (1) Starting with `gettext' version 0.11.1, the `xgettext' utility
+that comes with GNU `gettext' can handle `.awk' files.

File: gawk.info, Node: Printf Ordering, Next: I18N Portability, Prev: String Extraction, Up: Translator i18n
@@ -10879,7 +10903,7 @@ For example:
indicates which argument to use, and a `$'. Counts are one-based, and
the format string itself is _not_ included. Thus, in the following
example, `string' is the first argument and `length(string)' is the
-second.
+second:
$ gawk 'BEGIN {
> string = "Dont Panic"
@@ -10903,7 +10927,7 @@ precision capability:
*Note:* When using `*' with a positional specifier, the `*' comes
first, then the integer position, and then the `$'. This is somewhat
-counter-intutive.
+counterintutive.
`gawk' does not allow you to mix regular format specifiers and those
with positional specifiers in the same string:
@@ -10942,7 +10966,7 @@ use them to other versions of `awk'. Consider this program:
}
As written, it won't work on other versions of `awk'. However, it is
-actually almost portable, requiring very little change.
+actually almost portable, requiring very little change:
* Assignments to `TEXTDOMAIN' won't have any effect, since
`TEXTDOMAIN' is not special in other `awk' implementations.
@@ -10952,9 +10976,9 @@ actually almost portable, requiring very little change.
it.(1) Typically, the variable `_' has the null string (`""') as
its value, leaving the original string constant as the result.
- * By defining "dummy" functions to replace `dcgettext' and
- `bindtextdomain', the `awk' program can be made to run, but all
- the messages are output in the original language. For example:
+ * By defining "dummy" functions to replace `dcgettext', `dcngettext'
+ and `bindtextdomain', the `awk' program can be made to run, but
+ all the messages are output in the original language. For example:
function bindtextdomain(dir, domain)
{
@@ -10965,6 +10989,11 @@ actually almost portable, requiring very little change.
{
return string
}
+
+ function dcngettext(string1, string2, number, domain, category)
+ {
+ return (number == 1 ? string1 : string2)
+ }
* The use of positional specifications in `printf' or `sprintf' is
_not_ portable. To support `gettext' at the C level, many
@@ -11060,9 +11089,10 @@ proper directory so that `gawk' can find it:
-| Like, the scoop is 42
-| Pardon me, Zaphod who?
- If the two replacement functions for `dcgettext' and `bindtextdomain'
-(*note `awk' Portability Issues: I18N Portability.) are in a file
-named `libintl.awk', then we can run `guide.awk' unchanged as follows:
+ If the three replacement functions for `dcgettext', `dcngettext' and
+`bindtextdomain' (*note `awk' Portability Issues: I18N Portability.)
+are in a file named `libintl.awk', then we can run `guide.awk'
+unchanged as follows:
$ gawk --posix -f guide.awk -f libintl.awk
-| Don't Panic
@@ -11082,8 +11112,8 @@ File: gawk.info, Node: Gawk I18N, Prev: I18N Example, Up: Internationalizatio
As of version 3.1, `gawk' itself has been internationalized using
the GNU `gettext' package. (GNU `gettext' is described in complete
detail in *Note Top::.) As of this writing, the latest version of GNU
-`gettext' is version 0.10.37
-(ftp://gnudist.gnu.org/gnu/gettext/gettext-0.10.37.tar.gz).
+`gettext' is version 0.11.1
+(ftp://ftp.gnu.org/gnu/gettext/gettext-0.11.1.tar.gz).
If a translation of `gawk''s messages exists, then `gawk' produces
usage messages, warnings, and fatal errors in the local language.
@@ -11105,7 +11135,7 @@ Advanced Features of `gawk'
This major node discusses advanced features in `gawk'. It's a bit
of a "grab bag" of items that are otherwise unrelated to each other.
-First, a command-line option allows `gawk' to recognize non-decimal
+First, a command-line option allows `gawk' to recognize nondecimal
numbers in input data, not just in `awk' programs. Next, two-way I/O,
discussed briefly in earlier parts of this Info file, is described in
full detail, along with the basics of TCP/IP networking and BSD portal
@@ -11119,20 +11149,20 @@ description is relegated to an appendix.
* Menu:
-* Non-decimal Data:: Allowing non-decimal input data.
+* Nondecimal Data:: Allowing nondecimal input data.
* Two-way I/O:: Two-way communications with another process.
* TCP/IP Networking:: Using `gawk' for network programming.
* Portal Files:: Using `gawk' with BSD portals.
* Profiling:: Profiling your `awk' programs.

-File: gawk.info, Node: Non-decimal Data, Next: Two-way I/O, Prev: Advanced Features, Up: Advanced Features
+File: gawk.info, Node: Nondecimal Data, Next: Two-way I/O, Prev: Advanced Features, Up: Advanced Features
-Allowing Non-Decimal Input Data
-===============================
+Allowing Nondecimal Input Data
+==============================
If you run `gawk' with the `--non-decimal-data' option, you can have
-non-decimal constants in your input data:
+nondecimal constants in your input data:
$ echo 0123 123 0x123 |
> gawk --non-decimal-data '{ printf "%d, %d, %d\n",
@@ -11163,12 +11193,12 @@ request it.
*Caution:* _Use of this option is not recommended._ It can break old
programs very badly. Instead, use the `strtonum' function to convert
-your data (*note Octal and Hexadecimal Numbers: Non-decimal-numbers.).
+your data (*note Octal and Hexadecimal Numbers: Nondecimal-numbers.).
This makes your programs easier to write and easier to read, and leads
to less surprising results.

-File: gawk.info, Node: Two-way I/O, Next: TCP/IP Networking, Prev: Non-decimal Data, Up: Advanced Features
+File: gawk.info, Node: Two-way I/O, Next: TCP/IP Networking, Prev: Nondecimal Data, Up: Advanced Features
Two-Way Communications with Another Process
===========================================
@@ -11212,7 +11242,7 @@ This works, but not elegantly.
_two-way_ pipe to another process. The second process is termed a
"coprocess", since it runs in parallel with `gawk'. The two-way
connection is created using the new `|&' operator (borrowed from the
-Korn Shell, `ksh'):(1)
+Korn shell, `ksh'):(1)
do {
print DATA |& "subprogram"
@@ -11235,6 +11265,8 @@ or pipeline of programs, that can be started by the shell.
standard error goes. It is not possible to read the child's
standard error separately.
+ </itemizedlist>
+
* I/O buffering may be a problem. `gawk' automatically flushes all
output down the pipe to the child process. However, if the
coprocess does not flush its output, `gawk' may hang when doing a
@@ -11309,8 +11341,8 @@ networking is by recognizing special file names that begin with
`/inet/'.
The full syntax of the special file name is
-`/inet/PROTOCOL/LOCAL-PORT/REMOTE-HOST/REMOTE-PORT'. The meaning of
-the components are:
+`/inet/PROTOCOL/LOCAL-PORT/REMOTE-HOST/REMOTE-PORT'. The components
+are:
PROTOCOL
The protocol to use over IP. This must be either `tcp', `udp', or
@@ -11325,7 +11357,7 @@ LOCAL-PORT
when you want the system to pick a port. This is what you should do
when writing a TCP or UDP client. You may also use a well-known
service name, such as `smtp' or `http', in which case `gawk'
- attempts to determine the pre-defined port number using the C
+ attempts to determine the predefined port number using the C
`getservbyname' function.
REMOTE-HOST
@@ -11382,8 +11414,8 @@ version of `gawk', called `pgawk' ("profiling `gawk'").
`pgawk' is identical in every way to `gawk', except that when it has
finished running, it creates a profile of your program in a file named
-`awkprof.out'. Because it is profiling, it also executes up to 45
-percent slower than `gawk' normally does.
+`awkprof.out'. Because it is profiling, it also executes up to 45%
+slower than `gawk' normally does.
As shown in the following example, the `--profile' option can be
used to change the name of the file where `pgawk' will write the
@@ -11436,8 +11468,8 @@ First, the `awk' program:
junk
Here is the `awkprof.out' that results from running `pgawk' on this
-program and data. (This example also illustrates that `awk'
-programmers sometimes have to work late.):
+program and data (this example also illustrates that `awk' programmers
+sometimes have to work late):
# gawk profile, created Sun Aug 13 00:00:15 2000
@@ -11479,8 +11511,8 @@ programmers sometimes have to work late.):
6 print "I gotta be me!"
}
- The previous example illustrates many of the basic rules for
-profiling output. The rules are as follows:
+ This example illustrates many of the basic rules for profiling
+output. The rules are as follows:
* The program is printed in the order `BEGIN' rule, pattern/action
rules, `END' rule and functions, listed alphabetically. Multiple
@@ -11510,7 +11542,7 @@ profiling output. The rules are as follows:
counts next to the statements in the body show how many times
those statements were executed.
- * The layout uses "K&R" style using tabs. Braces are used
+ * The layout uses "K&R" style with tabs. Braces are used
everywhere, even when the body of an `if', `else', or loop is only
a single statement.
@@ -11536,7 +11568,7 @@ profiling output. The rules are as follows:
you typed when you wrote it. This is because `pgawk' creates the
profiled version by "pretty printing" its internal representation of
the program. The advantage to this is that `pgawk' can produce a
-standard representation. The disadvantage is that all source code
+standard representation. The disadvantage is that all source-code
comments are lost, as are the distinctions among multiple `BEGIN' and
`END' rules. Also, things such as:
@@ -11558,7 +11590,7 @@ executed. To use this feature, run `pgawk' in the background:
$ pgawk -f myprog &
[1] 13992
-The shell prints a job number and process ID number, in this case,
+The shell prints a job number and process ID number; in this case,
13992. Use the `kill' command to send the `USR1' signal to `pgawk':
$ kill -USR1 13992
@@ -11581,7 +11613,15 @@ Each time, the profile and function call trace are appended to the
output profile file.
If you use the `HUP' signal instead of the `USR1' signal, `pgawk'
-produces the profile and the function call trace, and then exits.
+produces the profile and the function call trace and then exits.
+
+ When `pgawk' runs on MS-DOS or MS-Windows, it uses the `INT' and
+`QUIT' signals for producing the profile and, in the case of the `INT'
+signal, `pgawk' exits. This is because these systems don't support the
+`kill' command, so the only signals you can deliver to a program are
+those generated by the keyboard. The `INT' signal is generated by the
+`Ctrl-<C>' or `Ctrl-<BREAK>' key, while the `QUIT' signal is generated
+by the `Ctrl-<\>' key.

File: gawk.info, Node: Invoking Gawk, Next: Library Functions, Prev: Advanced Features, Up: Top
@@ -11631,9 +11671,9 @@ supports GNU long options.
awk '' datafile1 datafile2
-Doing so makes little sense though; `awk' exits silently when given an
-empty program. (d.c.) If `--lint' has been specified on the
-command-line, `gawk' issues a warning that the program is empty.
+Doing so makes little sense, though; `awk' exits silently when given an
+empty program. (d.c.) If `--lint' has been specified on the command
+line, `gawk' issues a warning that the program is empty.

File: gawk.info, Node: Options, Next: Other Arguments, Prev: Command Line, Up: Invoking Gawk
@@ -11682,7 +11722,7 @@ options and their meanings are as follows:
`-mf N'
`-mr N'
- Set various memory limits to the value N. The `f' flag sets the
+ Sets various memory limits to the value N. The `f' flag sets the
maximum number of fields and the `r' flag sets the maximum record
size. These two flags and the `-m' option are from the Bell
Laboratories research version of Unix `awk'. They are provided
@@ -11736,21 +11776,21 @@ The following list describes `gawk'-specific options:
`-W dump-variables[=FILE]'
`--dump-variables[=FILE]'
- Print a sorted list of global variables, their types, and final
+ Prints a sorted list of global variables, their types, and final
values to FILE. If no FILE is provided, `gawk' prints this list
- to a file named `awkvars.out' in the current directory.
+ to the file named `awkvars.out' in the current directory.
- Having a list of all the global variables is a good way to look for
+ Having a list of all global variables is a good way to look for
typographical errors in your programs. You would also use this
option if you have a large program with a lot of functions, and
you want to be sure that your functions don't inadvertently use
global variables that you meant to be local. (This is a
particularly easy mistake to make with simple variable names like
- `i', `j', and so on.)
+ `i', `j', etc.)
`-W gen-po'
`--gen-po'
- Analyze the source program and generate a GNU `gettext' Portable
+ Analyzes the source program and generates a GNU `gettext' Portable
Object file on standard output for all string constants that have
been marked for translation. *Note Internationalization with
`gawk': Internationalization, for information about this option.
@@ -11759,28 +11799,28 @@ The following list describes `gawk'-specific options:
`-W usage'
`--help'
`--usage'
- Print a "usage" message summarizing the short and long style
+ Prints a "usage" message summarizing the short and long style
options that `gawk' accepts and then exit.
`-W lint[=fatal]'
`--lint[=fatal]'
- Warn about constructs that are dubious or non-portable to other
+ Warns about constructs that are dubious or nonportable to other
`awk' implementations. Some warnings are issued when `gawk' first
reads your program. Others are issued at runtime, as your program
executes. With an optional argument of `fatal', lint warnings
- become fatal errors. This may be drastic but its use will
+ become fatal errors. This may be drastic, but its use will
certainly encourage the development of cleaner `awk' programs.
`-W lint-old'
`--lint-old'
- Warn about constructs that are not available in the original
+ Warns about constructs that are not available in the original
version of `awk' from Version 7 Unix (*note Major Changes Between
V7 and SVR3.1: V7/SVR3.1.).
`-W non-decimal-data'
`--non-decimal-data'
Enable automatic interpretation of octal and hexadecimal values in
- input data (*note Allowing Non-Decimal Input Data: Non-decimal
+ input data (*note Allowing Nondecimal Input Data: Nondecimal
Data.).
*Caution:* This option can severely break old programs. Use with
@@ -11788,9 +11828,9 @@ The following list describes `gawk'-specific options:
`-W posix'
`--posix'
- Operate in strict POSIX mode. This disables all `gawk' extensions
- (just like `--traditional') and adds the following additional
- restrictions:
+ Operates in strict POSIX mode. This disables all `gawk'
+ extensions (just like `--traditional') and adds the following
+ additional restrictions:
* `\x' escape sequences are not recognized (*note Escape
Sequences::).
@@ -11811,15 +11851,15 @@ The following list describes `gawk'-specific options:
also *note Assignment Expressions: Assignment Ops.).
* Specifying `-Ft' on the command-line does not set the value
- of `FS' to be a single tab character (*note Specifying How
+ of `FS' to be a single TAB character (*note Specifying How
Fields Are Separated: Field Separators.).
* The `fflush' built-in function is not supported (*note
Input/Output Functions: I/O Functions.).
- If you supply both `--traditional' and `--posix' on the
- command-line, `--posix' takes precedence. `gawk' also issues a
- warning if both options are supplied.
+ If you supply both `--traditional' and `--posix' on the command
+ line, `--posix' takes precedence. `gawk' also issues a warning if
+ both options are supplied.
`-W profile[=FILE]'
`--profile[=FILE]'
@@ -11835,23 +11875,22 @@ The following list describes `gawk'-specific options:
`-W re-interval'
`--re-interval'
- Allow interval expressions (*note Regular Expression Operators:
+ Allows interval expressions (*note Regular Expression Operators:
Regexp Operators.) in regexps. Because interval expressions were
traditionally not available in `awk', `gawk' does not provide them
by default. This prevents old `awk' programs from breaking.
`-W source PROGRAM-TEXT'
`--source PROGRAM-TEXT'
- Program source code is taken from the PROGRAM-TEXT. This option
- allows you to mix source code in files with source code that you
- enter on the command-line. This is particularly useful when you
- have library functions that you want to use from your command-line
- programs (*note The `AWKPATH' Environment Variable: AWKPATH
- Variable.).
+ Allows you to mix source code in files with source code that you
+ enter on the command line. Program source code is taken from the
+ PROGRAM-TEXT. This is particularly useful when you have library
+ functions that you want to use from your command-line programs
+ (*note The `AWKPATH' Environment Variable: AWKPATH Variable.).
`-W version'
`--version'
- Print version information for this particular copy of `gawk'.
+ Prints version information for this particular copy of `gawk'.
This allows you to determine if your copy of `gawk' is up to date
with respect to whatever the Free Software Foundation is currently
distributing. It is also useful for bug reports (*note Reporting
@@ -11861,11 +11900,11 @@ The following list describes `gawk'-specific options:
flagged as invalid with a warning message but are otherwise ignored.
In compatibility mode, as a special case, if the value of FS supplied
-to the `-F' option is `t', then `FS' is set to the tab character
-(`"\t"'). This is only true for `--traditional' and not for `--posix'
+to the `-F' option is `t', then `FS' is set to the TAB character
+(`"\t"'). This is true only for `--traditional' and not for `--posix'
(*note Specifying How Fields Are Separated: Field Separators.).
- The `-f' option may be used more than once on the command-line. If
+ The `-f' option may be used more than once on the command line. If
it is, `awk' reads its program source from all of the named files, as
if they had been concatenated together into one big file. This is
useful for creating libraries of `awk' functions. These functions can
@@ -11896,7 +11935,7 @@ source code.
behaves in strict POSIX mode, exactly as if you had supplied the
`--posix' command-line option. Many GNU programs look for this
environment variable to turn on strict POSIX mode. If `--lint' is
-supplied on the command-line and `gawk' turns on POSIX mode because of
+supplied on the command line and `gawk' turns on POSIX mode because of
`POSIXLY_CORRECT', then it issues a warning message indicating that
POSIX mode is in effect. You would typically set this variable in your
shell's startup file. For a Bourne-compatible shell (such as `bash'),
@@ -11905,7 +11944,7 @@ you would add these lines to the `.profile' file in your home directory:
POSIXLY_CORRECT=true
export POSIXLY_CORRECT
- For a `csh' compatible shell,(1) you would add this line to the
+ For a `csh'-compatible shell,(1) you would add this line to the
`.login' file in your home directory:
setenv POSIXLY_CORRECT true
@@ -11924,7 +11963,7 @@ File: gawk.info, Node: Other Arguments, Next: AWKPATH Variable, Prev: Options
Other Command-Line Arguments
============================
- Any additional arguments on the command-line are normally treated as
+ Any additional arguments on the command line are normally treated as
input files to be processed in the order specified. However, an
argument that has the form `VAR=VALUE', assigns the value VALUE to the
variable VAR--it does not specify a file at all. (This was discussed
@@ -11951,7 +11990,7 @@ rule (*note The `BEGIN' and `END' Special Patterns: BEGIN/END.),
because such rules are run before `awk' begins scanning the argument
list.
- The variable values given on the command-line are processed for
+ The variable values given on the command line are processed for
escape sequences (*note Escape Sequences::). (d.c.)
In some earlier implementations of `awk', when a variable assignment
@@ -11993,19 +12032,19 @@ by one, looking for a file with the specified name.
The search path is a string consisting of directory names separated
by colons. `gawk' gets its search path from the `AWKPATH' environment
variable. If that variable does not exist, `gawk' uses a default path,
-which is `.:/usr/local/share/awk'.(1) (Programs written for use by
-system administrators should use an `AWKPATH' variable that does not
-include the current directory, `.'.)
+`.:/usr/local/share/awk'.(1) (Programs written for use by system
+administrators should use an `AWKPATH' variable that does not include
+the current directory, `.'.)
The search path feature is particularly useful for building libraries
of useful `awk' functions. The library files can be placed in a
standard directory in the default path and then specified on the
-command-line with a short file name. Otherwise, the full file name
+command line with a short file name. Otherwise, the full file name
would have to be typed for each file.
By using both the `--source' and `-f' options, your command-line
-`awk' programs can use facilities in `awk' library files. *Note A
-Library of `awk' Functions: Library Functions. Path searching is not
+`awk' programs can use facilities in `awk' library files (*note A
+Library of `awk' Functions: Library Functions.). Path searching is not
done if `gawk' is in compatibility mode. This is true for both
`--traditional' and `--posix'. *Note Command-Line Options: Options.
@@ -12034,7 +12073,7 @@ found, and `gawk' no longer needs to use `AWKPATH'.
(1) Your version of `gawk' may use a different directory; it will
depend upon how `gawk' was built and installed. The actual directory is
the value of `$(datadir)' generated when `gawk' was configured. You
-probably don't need to worry about this though.
+probably don't need to worry about this, though.

File: gawk.info, Node: Obsolete, Next: Undocumented, Prev: AWKPATH Variable, Up: Invoking Gawk
@@ -12050,7 +12089,7 @@ they will _not_ be in the next release).
For version 3.1 of `gawk', there are no deprecated command-line
options from the previous version of `gawk'. The use of `next file'
(two words) for `nextfile' was deprecated in `gawk' 3.0 but still
-worked. Starting with version 3.1, the two word usage is no longer
+worked. Starting with version 3.1, the two-word usage is no longer
accepted.
The process-related special files described in *Note Special Files
@@ -12079,13 +12118,13 @@ Known Bugs in `gawk'
* The `-F' option for changing the value of `FS' (*note Command-Line
Options: Options.) is not necessary given the command-line
- variable assignment feature; it remains only for backwards
+ variable assignment feature; it remains only for backward
compatibility.
- * Syntactically invalid single character programs tend to overflow
+ * Syntactically invalid single-character programs tend to overflow
the parse stack, generating a rather unhelpful message. Such
programs are surprisingly difficult to diagnose in the completely
- general case and the effort to do so really is not worth it.
+ general case, and the effort to do so really is not worth it.

File: gawk.info, Node: Library Functions, Next: Sample Programs, Prev: Invoking Gawk, Up: Top
@@ -12115,19 +12154,19 @@ these example library functions and programs from the Texinfo source
for this Info file. (This has already been done as part of the `gawk'
distribution.)
- If you have written one or more useful, general purpose `awk'
+ If you have written one or more useful, general-purpose `awk'
functions and would like to contribute them to the author's collection
of `awk' programs, see *Note How to Contribute: How To Contribute, for
more information.
The programs in this major node and in *Note Practical `awk'
Programs: Sample Programs, freely use features that are `gawk'-specific.
-It is straightforward to rewrite these programs for different
-implementations of `awk'.
+Rewriting these programs for different implementations of awk is pretty
+straightforward.
Diagnostic error messages are sent to `/dev/stderr'. Use `| "cat
-1>&2"' instead of `> "/dev/stderr"', if your system does not have a
-`/dev/stderr' or if you cannot use `gawk'.
+1>&2"' instead of `> "/dev/stderr"' if your system does not have a
+`/dev/stderr', or if you cannot use `gawk'.
A number of programs use `nextfile' (*note Using `gawk''s `nextfile'
Statement: Nextfile Statement.) to skip any remaining input in the
@@ -12143,7 +12182,7 @@ following rule to the beginning of the program:
{ $0 = tolower($0) }
Also, verify that all regexp and string constants used in comparisons
-only use lowercase letters.
+use only lowercase letters.
* Menu:
@@ -12238,7 +12277,7 @@ merely recommend that you do so.
(1) While all the library routines could have been rewritten to use
this convention, this was not done, in order to show how my own `awk'
-programming style has evolved, and to provide some basis for this
+programming style has evolved and to provide some basis for this
discussion.
(2) `gawk''s `--dump-variables' command-line option is useful for
@@ -12273,7 +12312,7 @@ File: gawk.info, Node: Nextfile Function, Next: Assert Function, Prev: Genera
Implementing `nextfile' as a Function
-------------------------------------
- The `nextfile' statement presented in *Note Using `gawk''s
+ The `nextfile' statement, presented in *Note Using `gawk''s
`nextfile' Statement: Nextfile Statement, is a `gawk'-specific
extension--it is not available in most other implementations of `awk'.
This minor node shows two versions of a `nextfile' function that you
@@ -12301,7 +12340,7 @@ Variables: Library Names.)
all the records from the current data file. The end of the file is
eventually reached and a new data file is opened, changing the value of
`FILENAME'. Once this happens, the comparison of `_abandon_' to
-`FILENAME' fails and execution continues with the first rule of the
+`FILENAME' fails, and execution continues with the first rule of the
"real" program.
The `nextfile' function itself simply sets the value of `_abandon_'
@@ -12310,9 +12349,9 @@ and then executes a `next' statement to start the loop.
This initial version has a subtle problem. If the same data file is
listed _twice_ on the commandline, one right after the other or even
with just a variable assignment between them, this code skips right
-through the file, a second time, even though it should stop when it
-gets to the end of the first occurrence. A second version of
-`nextfile' that remedies this problem is shown here:
+through the file a second time, even though it should stop when it gets
+to the end of the first occurrence. A second version of `nextfile'
+that remedies this problem is shown here:
# nextfile --- skip remaining records in current file
# correctly handle successive occurrences of the same file
@@ -12411,7 +12450,7 @@ false, it prints a message to standard error, using the `string'
parameter to describe the failed condition. It then sets the variable
`_assert_exit' to one and executes the `exit' statement. The `exit'
statement jumps to the `END' rule. If the `END' rules finds
-`_assert_exit' to be true, it then exits immediately.
+`_assert_exit' to be true, it exits immediately.
The purpose of the test in the `END' rule is to keep any other `END'
rules from running. When an assertion fails, the program should exit
@@ -12459,7 +12498,7 @@ This means that if you are using a format that does rounding (e.g.,
function does traditional rounding; it might be useful if your awk's
`printf' does unbiased rounding:
- # round --- do normal rounding
+ # round.awk --- do normal rounding
function round(x, ival, aval, fraction)
{
ival = int(x) # integer part, int() truncates
@@ -12564,16 +12603,15 @@ no real reason to build them into the `awk' interpreter:
}
Some explanation of the numbers used by `chr' is worthwhile. The
-most prominent character set in use today is ASCII. Although an
-eight-bit byte can hold 256 distinct values (from 0 to 255), ASCII only
-defines characters that use the values from 0 to 127.(1) In the now
-distant past, at least one minicomputer manufacturer used ASCII, but
-with mark parity, meaning that the leftmost bit in the byte is always
-1. This means that on those systems, characters have numeric values
-from 128 to 255. Finally, large mainframe systems use the EBCDIC
-character set, which uses all 256 values. While there are other
-character sets in use on some older systems, they are not really worth
-worrying about:
+most prominent character set in use today is ASCII. Although an 8-bit
+byte can hold 256 distinct values (from 0 to 255), ASCII only defines
+characters that use the values from 0 to 127.(1) In the now distant
+past, at least one minicomputer manufacturer used ASCII, but with mark
+parity, meaning that the leftmost bit in the byte is always 1. This
+means that on those systems, characters have numeric values from 128 to
+255. Finally, large mainframe systems use the EBCDIC character set,
+which uses all 256 values. While there are other character sets in use
+on some older systems, they are not really worth worrying about:
function ord(str, c)
{
@@ -12645,7 +12683,7 @@ Functions.):
}
An optional additional argument is the separator to use when joining
-the strings back together. If the caller supplies a non-empty value,
+the strings back together. If the caller supplies a nonempty value,
`join' uses it; if it is not supplied, it has a null value. In this
case, `join' uses a single blank as a default separator for the
strings. If the value is equal to `SUBSEP', then `join' joins the
@@ -12750,7 +12788,7 @@ Data File Management
====================
This minor node presents functions that are useful for managing
-command-line datafiles.
+command-line data files.
* Menu:
@@ -12765,7 +12803,7 @@ File: gawk.info, Node: Filetrans Function, Next: Rewind Function, Prev: Data
Noting Data File Boundaries
---------------------------
- The `BEGIN' and `END' rules are each executed exactly once, at the
+ The `BEGIN' and `END' rules are each executed exactly once at the
beginning and end of your `awk' program, respectively (*note The
`BEGIN' and `END' Special Patterns: BEGIN/END.). We (the `gawk'
authors) once had a user who mistakenly thought that the `BEGIN' rule
@@ -12985,7 +13023,7 @@ When it returns -1, there are no options left on the command line.
When using `getopt', options that do not take arguments can be
grouped together. Furthermore, options that take arguments require
that the argument is present. The argument can immediately follow the
-option letter or it can be a separate command-line argument.
+option letter, or it can be a separate command-line argument.
Given a hypothetical program that takes three command-line options,
`-a', `-b', and `-c', where `-b' requires an argument, all of the
@@ -13006,7 +13044,7 @@ use:
`optind'
The index in the argument value array (`argv') where the first
- non-option command-line argument can be found.
+ nonoption command-line argument can be found.
`optarg'
The string value of the argument to an option.
@@ -13066,7 +13104,7 @@ characters (*note String Manipulation Functions: String Functions.).(1)
# getopt.awk --- do C library getopt(3) function in awk
# External variables:
- # Optind -- index in ARGV of first non-option argument
+ # Optind -- index in ARGV of first nonoption argument
# Optarg -- string value of argument to current option
# Opterr -- if nonzero, print our own diagnostic
# Optopt -- current option letter
@@ -13112,7 +13150,7 @@ because it is a global variable.
perhaps a bit of overkill; it checks for a `-' followed by anything
that is not whitespace and not a colon. If the current command-line
argument does not match this pattern, it is not an option, and it ends
-option processing.
+option processing:
if (_opti == 0)
_opti = 2
@@ -13171,7 +13209,7 @@ invalid option letter actually is. Continuing on:
a colon in the `options' string. If there are remaining characters in
the current command-line argument (`argv[Optind]'), then the rest of
that string is assigned to `Optarg'. Otherwise, the next command-line
-argument is used (`-xFOO' vs. `-x FOO'). In either case, `_opti' is
+argument is used (`-xFOO' versus `-x FOO'). In either case, `_opti' is
reset to zero, because there are no more characters left to examine in
the current command-line argument. Continuing:
@@ -13249,14 +13287,14 @@ Reading the User Database
=========================
The `PROCINFO' array (*note Built-in Variables::) provides access to
-the current user's real and effective user and group id numbers, and if
+the current user's real and effective user and group ID numbers, and if
available, the user's supplementary group set. However, because these
are numbers, they do not provide very useful information to the average
user. There needs to be some way to find the user information
-associated with the user and group numbers. This minor node presents a
-suite of functions for retrieving information from the user database.
-*Note Reading the Group Database: Group Functions, for a similar suite
-that retrieves information from the group database.
+associated with the user and group ID numbers. This minor node
+presents a suite of functions for retrieving information from the user
+database. *Note Reading the Group Database: Group Functions, for a
+similar suite that retrieves information from the group database.
The POSIX standard does not define the file where user information is
kept. Instead, it provides the `<pwd.h>' header file and several C
@@ -13274,7 +13312,7 @@ pointer to a `struct passwd'. Each time it is called, it returns the
next entry in the database. When there are no more entries, it returns
`NULL', the null pointer. When this happens, the C program should call
`endpwent' to close the database. Following is `pwcat', a C program
-that "cats" the password database.
+that "cats" the password database:
/*
* pwcat.c
@@ -13307,8 +13345,8 @@ of colon-separated fields. The fields are:
Login name The user's login name.
Encrypted password The user's encrypted password. This may not be
available on some systems.
-User-ID The user's numeric user-id number.
-Group-ID The user's numeric group-id number.
+User-ID The user's numeric user ID number.
+Group-ID The user's numeric group ID number.
Full name The user's full name, and perhaps other
information associated with the user.
Home directory The user's login (or "home") directory
@@ -13374,7 +13412,7 @@ you might want it to be in a different directory on your system.
The function `_pw_init' keeps three copies of the user information
in three associative arrays. The arrays are indexed by username
-(`_pw_byname'), by user-id number (`_pw_byuid'), and by order of
+(`_pw_byname'), by user ID number (`_pw_byuid'), and by order of
occurrence (`_pw_bycount'). The variable `_pw_inited' is used for
efficiency; `_pw_init' needs only to be called once.
@@ -13400,7 +13438,7 @@ explained shortly.
The `getpwnam' function takes a username as a string argument. If
that user is in the database, it returns the appropriate line.
-Otherwise it returns the null string:
+Otherwise, it returns the null string:
function getpwnam(name)
{
@@ -13410,9 +13448,9 @@ Otherwise it returns the null string:
return ""
}
- Similarly, the `getpwuid' function takes a user-id number argument.
+ Similarly, the `getpwuid' function takes a user ID number argument.
If that user number is in the database, it returns the appropriate
-line. Otherwise it returns the null string:
+line. Otherwise, it returns the null string:
function getpwuid(uid)
{
@@ -13442,15 +13480,16 @@ subsequent calls to `getpwent' start over again:
_pw_count = 0
}
- A conscious design decision in this suite is that each subroutine
-calls `_pw_init' to initialize the database arrays. The overhead of
-running a separate process to generate the user database, and the I/O
-to scan it, are only incurred if the user's main program actually calls
-one of these functions. If this library file is loaded along with a
-user's program, but none of the routines are ever called, then there is
-no extra runtime overhead. (The alternative is move the body of
-`_pw_init' into a `BEGIN' rule, which always runs `pwcat'. This
-simplifies the code but runs an extra process that may never be needed.)
+ A conscious design decision in this suite was made that each
+subroutine calls `_pw_init' to initialize the database arrays. The
+overhead of running a separate process to generate the user database,
+and the I/O to scan it, are only incurred if the user's main program
+actually calls one of these functions. If this library file is loaded
+along with a user's program, but none of the routines are ever called,
+then there is no extra runtime overhead. (The alternative is move the
+body of `_pw_init' into a `BEGIN' rule, which always runs `pwcat'.
+This simplifies the code but runs an extra process that may never be
+needed.)
In turn, calling `_pw_init' is not too expensive, because the
`_pw_inited' variable keeps the program from reading the data more than
@@ -13522,14 +13561,14 @@ Group name The group's name.
Group password The group's encrypted password. In practice,
this field is never used; it is usually empty
or set to `*'.
-Group-ID The group's numeric group-id number; this
+Group-ID The group's numeric group ID number; this
number should be unique within the file.
Group member list A comma-separated list of usernames. These
users are members of the group. Modern Unix
systems allow users to be members of several
groups simultaneously. If your system does,
then there are elements `"group1"' through
- `"groupN"' in `PROCINFO' for those group-id
+ `"groupN"' in `PROCINFO' for those group ID
numbers. (Note that `PROCINFO' is a `gawk'
extension; *note Built-in Variables::.)
@@ -13612,10 +13651,10 @@ more than once. The `_gr_init' function first saves `FS',
correct values for scanning the group information.
The group information is stored is several associative arrays. The
-arrays are indexed by group name (`_gr_byname'), by group-id number
+arrays are indexed by group name (`_gr_byname'), by group ID number
(`_gr_bygid'), and by position in the database (`_gr_bycount'). There
is an additional array indexed by username (`_gr_groupsbyuser'), which
-is a space-separated list of groups that each user belongs to.
+is a space-separated list of groups to which each user belongs.
Unlike the user database, it is possible to have multiple records in
the database for the same group. This is common when a group has a
@@ -13625,7 +13664,7 @@ following:
tvpeople:*:101:johnny,jay,arsenio
tvpeople:*:101:david,conan,tom,joan
- For this reason, `_gr_init' looks to see if a group name or group-id
+ For this reason, `_gr_init' looks to see if a group name or group ID
number is already seen. If it is, then the usernames are simply
concatenated onto the previous list of users. (There is actually a
subtle problem with the code just presented. Suppose that the first
@@ -13648,8 +13687,8 @@ null string:
return ""
}
- The `getgrgid' function is similar, it takes a numeric group-id and
-looks up the information associated with that group-id:
+ The `getgrgid' function is similar, it takes a numeric group ID and
+looks up the information associated with that group ID:
function getgrgid(gid)
{
@@ -13783,7 +13822,7 @@ Cutting out Fields and Columns
The `cut' utility selects, or "cuts," characters or fields from its
standard input and sends them to its standard output. Fields are
separated by tabs by default, but you may supply a command-line option
-to change the field "delimiter" (i.e., the field separator character).
+to change the field "delimiter" (i.e., the field-separator character).
`cut''s definition of fields is less general than `awk''s.
A common use of `cut' might be to pull out just the login name of
@@ -13804,7 +13843,7 @@ pipeline generates a sorted, unique list of the logged-on users:
Use LIST as the list of fields to cut out.
`-d DELIM'
- Use DELIM as the field separator character instead of the tab
+ Use DELIM as the field-separator character instead of the tab
character.
`-s'
@@ -13842,13 +13881,13 @@ The variables `e1' and `e2' are used so that the function fits nicely
on the screen.
Next comes a `BEGIN' rule that parses the command-line options. It
-sets `FS' to a single tab character, because that is `cut''s default
+sets `FS' to a single TAB character, because that is `cut''s default
field separator. The output field separator is also set to be the same
as the input field separator. Then `getopt' is used to step through
-the command-line options. One or the other of the variables
-`by_fields' or `by_chars' is set to true, to indicate that processing
-should be done by fields or by characters, respectively. When cutting
-by characters, the output field separator is set to the null string.
+the command-line options. Exactly one of the variables `by_fields' or
+`by_chars' is set to true, to indicate that processing should be done
+by fields or by characters, respectively. When cutting by characters,
+the output field separator is set to the null string:
BEGIN \
{
@@ -13912,7 +13951,7 @@ fields or characters:
set_charlist()
}
- `set_fieldlist' is used to split the field list apart at the commas,
+ `set_fieldlist' is used to split the field list apart at the commas
and into an array. Then, for each element of the array, it looks to
see if it is actually a range, and if so, splits it apart. The range is
verified to make sure the first number is smaller than the second.
@@ -13942,7 +13981,7 @@ The program lets `awk' handle the job of doing the field splitting:
The `set_charlist' function is more complicated than `set_fieldlist'.
The idea here is to use `gawk''s `FIELDWIDTHS' variable (*note Reading
-Fixed-Width Data: Constant Size.), which describes constant width
+Fixed-Width Data: Constant Size.), which describes constant-width
input. When using a character list, that is exactly what we have.
Setting up `FIELDWIDTHS' is more complicated than simply listing the
@@ -14116,7 +14155,7 @@ that processes the command-line arguments with `getopt'. The `-i'
}
Next comes the code that handles the `egrep'-specific behavior. If no
-pattern is supplied with `-e', the first non-option on the command line
+pattern is supplied with `-e', the first nonoption on the command line
is used. The `awk' command-line arguments up to `ARGV[Optind]' are
cleared, so that `awk' won't try to process them as files. If no files
are specified, the standard input is used, and if multiple files are
@@ -14155,9 +14194,9 @@ since it is not necessary with `gawk':
The `beginfile' function is called by the rule in `ftrans.awk' when
each new file is processed. In this case, it is very simple; all it
does is initialize a variable `fcount' to zero. `fcount' tracks how
-many lines in the current file matched the pattern. (Naming the
+many lines in the current file matched the pattern (naming the
parameter `junk' shows we know that `beginfile' is called with a
-parameter, but that we're not interested in its value.):
+parameter, but that we're not interested in its value):
function beginfile(junk)
{
@@ -14170,8 +14209,8 @@ lines that matched. `no_print' is true only if the exit status is
desired. `count_only' is true if line counts are desired. `egrep'
therefore only prints line counts if printing and counting are enabled.
The output format must be adjusted depending upon the number of files to
-process. Finally, `fcount' is added to `total', so that we know how
-many lines altogether matched the pattern:
+process. Finally, `fcount' is added to `total', so that we know the
+total number of lines that matched the pattern:
function endfile(file)
{
@@ -14227,7 +14266,7 @@ line is printed, with a leading file name and colon if necessary:
}
The `END' rule takes care of producing the correct exit status. If
-there are no matches, the exit status is one, otherwise it is zero:
+there are no matches, the exit status is one; otherwise it is zero:
END \
{
@@ -14268,9 +14307,9 @@ File: gawk.info, Node: Id Program, Next: Split Program, Prev: Egrep Program,
Printing out User Information
-----------------------------
- The `id' utility lists a user's real and effective user-id numbers,
-real and effective group-id numbers, and the user's group set, if any.
-`id' only prints the effective user-id and group-id if they are
+ The `id' utility lists a user's real and effective user ID numbers,
+real and effective group ID numbers, and the user's group set, if any.
+`id' only prints the effective user ID and group ID if they are
different from the real ones. If possible, `id' also supplies the
corresponding user and group names. The output might look like this:
@@ -14289,9 +14328,9 @@ the Group Database: Group Functions.):
The program is fairly straightforward. All the work is done in the
`BEGIN' rule. The user and group ID numbers are obtained from
`PROCINFO'. The code is repetitive. The entry in the user database
-for the real user-id number is split into parts at the `:'. The name is
-the first field. Similar code is used for the effective user-id number
-and the group numbers.
+for the real user ID number is split into parts at the `:'. The name is
+the first field. Similar code is used for the effective user ID number
+and the group numbers:
# id.awk --- implement id in awk
#
@@ -14358,9 +14397,8 @@ and the group numbers.
The test in the `for' loop is worth noting. Any supplementary
groups in the `PROCINFO' array have the indices `"group1"' through
-`"groupN"' for some N; i.e., the total number of supplementary groups.
-The problem is, we don't know in advance how many of these groups there
-are.
+`"groupN"' for some N, i.e., the total number of supplementary groups.
+However, we don't know in advance how many of these groups there are.
This loop works by starting at one, concatenating the value with
`"group"', and then using `in' to see if that value is in the array.
@@ -14378,7 +14416,7 @@ Splitting a Large File into Pieces
----------------------------------
The `split' program splits large text files into smaller pieces.
-The usage is as follows:
+Usage is as follows:
split [-COUNT] file [ PREFIX ]
@@ -14396,8 +14434,8 @@ Numbers: Ordinal Functions.
The program first sets its defaults, and then tests to make sure
there are not too many arguments. It then looks at each argument in
-turn. The first argument could be a minus followed by a number. If it
-is, this happens to look like a negative number, so it is made
+turn. The first argument could be a minus sign followed by a number.
+If it is, this happens to look like a negative number, so it is made
positive, and that is the count of lines. The data file name is
skipped over and the final argument is used as the prefix for the
output file names:
@@ -14470,10 +14508,10 @@ The `usage' function simply prints an error message and exits:
The variable `e' is used so that the function fits nicely on the screen.
- This program is a bit sloppy; it relies on `awk' to close the last
-file for it automatically, instead of doing it in an `END' rule. It
-also assumes that letters are contiguous in the character set, which
-isn't true for EBCDIC systems.
+ This program is a bit sloppy; it relies on `awk' to automatically
+close the last file instead of doing it in an `END' rule. It also
+assumes that letters are contiguous in the character set, which isn't
+true for EBCDIC systems.

File: gawk.info, Node: Tee Program, Next: Uniq Program, Prev: Split Program, Up: Clones
@@ -14562,8 +14600,8 @@ N input records and M output files, the first method only executes N

File: gawk.info, Node: Uniq Program, Next: Wc Program, Prev: Tee Program, Up: Clones
-Printing Non-Duplicated Lines of Text
--------------------------------------
+Printing Nonduplicated Lines of Text
+------------------------------------
The `uniq' utility reads sorted lines of data on its standard input,
and by default removes duplicate lines. In other words, it only prints
@@ -14572,21 +14610,21 @@ usage is as follows:
uniq [-udc [-N]] [+N] [ INPUT FILE [ OUTPUT FILE ]]
- The option meanings are:
+ The options for `uniq' are:
`-d'
- Only print repeated lines.
+ Pnly print only repeated lines.
`-u'
- Only print non-repeated lines.
+ Print only nonrepeated lines.
`-c'
Count lines. This option overrides `-d' and `-u'. Both repeated
- and non-repeated lines are counted.
+ and nonrepeated lines are counted.
`-N'
Skip N fields before comparing lines. The definition of fields is
- similar to `awk''s default: non-whitespace characters separated by
+ similar to `awk''s default: nonwhitespace characters separated by
runs of spaces and/or tabs.
`+N'
@@ -14616,11 +14654,12 @@ as the option letter `2' with an argument of `5'. If indeed two or more
digits are supplied (`Optarg' looks like a number), `Optarg' is
concatenated with the option digit and then the result is added to zero
to make it into a number. If there is only one digit in the option,
-then `Optarg' is not needed. `Optind' must be decremented so that
-`getopt' processes it next time. This code is admittedly a bit tricky.
+then `Optarg' is not needed. In this case, `Optind' must be decremented
+so that `getopt' processes it next time. This code is admittedly a bit
+tricky.
If no options are supplied, then the default is taken, to print both
-repeated and non-repeated lines. The output file, if provided, is
+repeated and nonrepeated lines. The output file, if provided, is
assigned to `outputfile'. Early on, `outputfile' is initialized to the
standard output, `/dev/stdout':
@@ -14726,13 +14765,13 @@ to.
The second rule does the work. The variable `equal' is one or zero,
depending upon the results of `are_equal''s comparison. If `uniq' is
counting repeated lines, and the lines are equal, then it increments
-the `count' variable. Otherwise it prints the line and resets `count',
+the `count' variable. Otherwise, it prints the line and resets `count',
since the two lines are not equal.
If `uniq' is not counting, and if the lines are equal, `count' is
incremented. Nothing is printed, since the point is to remove
duplicates. Otherwise, if `uniq' is counting repeated lines and more
-than one line is seen, or if `uniq' is counting non-repeated lines and
+than one line is seen, or if `uniq' is counting nonrepeated lines and
only one line is seen, then the line is printed, and `count' is reset.
Finally, similar logic is used in the `END' rule to print the final
@@ -14793,16 +14832,16 @@ counts for all the files. The options and their meanings are shown in
the following list:
`-l'
- Only count lines.
+ Count only lines.
`-w'
- Only count words. A "word" is a contiguous sequence of
- non-whitespace characters, separated by spaces and/or tabs.
- Happily, this is the normal way `awk' separates fields in its
+ Count only words. A "word" is a contiguous sequence of
+ nonwhitespace characters, separated by spaces and/or tabs.
+ Luckily, this is the normal way `awk' separates fields in its
input data.
`-c'
- Only count characters.
+ Count only characters.
Implementing `wc' in `awk' is particularly elegant, since `awk' does
a lot of the work for us; it splits lines into words (i.e., fields) and
@@ -14810,7 +14849,7 @@ counts them, it counts lines (i.e., records), and it can easily tell us
how long a line is.
This uses the `getopt' library function (*note Processing
-Command-Line Options: Getopt Function.) and the file transition
+Command-Line Options: Getopt Function.) and the file-transition
functions (*note Noting Data File Boundaries: Filetrans Function.).
This version has one notable difference from traditional versions of
@@ -14865,7 +14904,7 @@ lines, words, and characters to zero, and saves the current file name in
}
The `endfile' function adds the current file's numbers to the running
-totals of lines, words, and characters. It then prints out those
+totals of lines, words, and characters.(1) It then prints out those
numbers for the file that was just read. It relies on `beginfile' to
reset the numbers for the following data file:
@@ -14889,7 +14928,7 @@ is needed because the newline character separating records (the value
of `RS') is not part of the record itself, and thus not included in its
length. Next, `lines' is incremented for each line read, and `words'
is incremented by the value of `NF', which is the number of "words" on
-this line:(1)
+this line:
# do per line
{
@@ -14898,7 +14937,7 @@ this line:(1)
words += NF
}
- Finally, the `END' rule simply prints the totals for all the files.
+ Finally, the `END' rule simply prints the totals for all the files:
END {
if (print_total) {
@@ -14914,9 +14953,9 @@ this line:(1)
---------- Footnotes ----------
- (1) `wc' can't just use the value of `FNR' in `endfile'. If you
+ (1) `wc' can't just use the value of `FNR' in `endfile'. If you
examine the code in *Note Noting Data File Boundaries: Filetrans
-Function, you will see that `FNR' has already been reset by the time
+Function you will see that `FNR' has already been reset by the time
`endfile' is called.

@@ -14951,9 +14990,9 @@ Finding Duplicated Words in a Document
A common error when writing large amounts of prose is to accidentally
duplicate words. Typically you will see this in text as something like
-"the the program does the following ...." When the text is online,
-often the duplicated words occur at the end of one line and the
-beginning of another, making them very difficult to spot.
+"the the program does the following..." When the text is online, often
+the duplicated words occur at the end of one line and the beginning of
+another, making them very difficult to spot.
This program, `dupword.awk', scans through a file one line at a time
and looks for adjacent occurrences of the same word. It also saves the
@@ -14962,13 +15001,13 @@ first word on the next line.
The first two statements make sure that the line is all lowercase,
so that, for example, "The" and "the" compare equal to each other. The
-next statement replaces non-alphanumeric and non-whitespace characters
+next statement replaces nonalphanumeric and nonwhitespace characters
with spaces, so that punctuation does not affect the comparison either.
The characters are replaced with spaces so that formatting controls
don't create nonsense words (e.g., the Texinfo `@code{NF}' becomes
-`codeNF' if punctuation is simply deleted). The record is then
-re-split into fields, yielding just the actual words on the line, and
-insuring that there are no empty fields.
+`codeNF' if punctuation is simply deleted). The record is then resplit
+into fields, yielding just the actual words on the line, and ensuring
+that there are no empty fields.
If there are no fields left after removing all the punctuation, the
current record is skipped. Otherwise, the program loops through each
@@ -15013,10 +15052,10 @@ the Time of Day: Gettimeofday Function.
checking and setting of defaults: the delay, the count, and the message
to print. If the user supplied a message without the ASCII BEL
character (known as the "alert" character, `"\a"'), then it is added to
-the message. (On many systems, printing the ASCII BEL generates some
-sort of audible alert. Thus when the alarm goes off, the system calls
-attention to itself in case the user is not looking at their computer
-or terminal.):
+the message. (On many systems, printing the ASCII BEL generates an
+audible alert. Thus when the alarm goes off, the system calls attention
+to itself in case the user is not looking at the computer or terminal.)
+Here is the program:
# alarm.awk --- set an alarm
#
@@ -15147,18 +15186,17 @@ most of the job.
standard `awk': dealing with individual characters is very painful,
requiring repeated use of the `substr', `index', and `gsub' built-in
functions (*note String Manipulation Functions: String Functions.).(2)
-
- There are two functions. The first, `stranslate', takes three
+There are two functions. The first, `stranslate', takes three
arguments:
`from'
- A list of characters to translate from.
+ A list of characters from which to translate.
`to'
- A list of characters to translate to.
+ A list of characters to which to translate.
`target'
- The string to do the translation on.
+ The string on which to do the translation.
Associative arrays make the translation part fairly easy. `t_ar'
holds the "to" characters, indexed by the "from" characters. Then a
@@ -15251,9 +15289,9 @@ Printing Mailing Labels
Here is a "real world"(1) program. This script reads lists of names
and addresses and generates mailing labels. Each page of labels has 20
-labels on it, two across and ten down. The addresses are guaranteed to
-be no more than five lines of data. Each address is separated from the
-next by a blank line.
+labels on it, 2 across and 10 down. The addresses are guaranteed to be
+no more than 5 lines of data. Each address is separated from the next
+by a blank line.
The basic idea is to read 20 labels worth of data. Each line of
each label is stored in the `line' array. The single rule takes care
@@ -15272,7 +15310,7 @@ print horizontally; `line[1]' next to `line[6]', `line[2]' next to
outer loop, controlled by `i', steps through every 10 lines of data;
this is each row of labels. The inner loop, controlled by `j', goes
through the lines within the row. As `j' goes from 0 to 4, `i+j' is
-the `j''th line in the row, and `i+j+5' is the entry next to it. The
+the `j'-th line in the row, and `i+j+5' is the entry next to it. The
output ends up looking something like this:
line 1 line 6
@@ -15285,7 +15323,7 @@ output ends up looking something like this:
As a final note, an extra blank line is printed at lines 21 and 61,
to keep the output lined up on the labels. This is dependent on the
particular brand of labels in use when the program was written. You
-will also note that there are two blank lines at the top and two blank
+will also note that there are 2 blank lines at the top and 2 blank
lines at the bottom.
The `END' rule arranges to flush the final page of labels; there may
@@ -15351,7 +15389,7 @@ something done."

File: gawk.info, Node: Word Sorting, Next: History Sorting, Prev: Labels Program, Up: Miscellaneous Programs
-Generating Word Usage Counts
+Generating Word-Usage Counts
----------------------------
The following `awk' program prints the number of occurrences of each
@@ -15426,7 +15464,7 @@ Finally, we use the system `sort' utility to process the output of the
Assuming we have saved this program in a file named `wordfreq.awk',
and that the data is in `file1', the following pipeline:
- awk -f wordfreq.awk file1 | sort +1 -nr
+ awk -f wordfreq.awk file1 | sort -k 2nr
produces a table of the words appearing in `file1' in order of
decreasing frequency. The `awk' program suitably massages the data and
@@ -15443,7 +15481,7 @@ descending (reverse) order.
the `END' action to:
END {
- sort = "sort +1 -nr"
+ sort = "sort -k 2nr"
for (word in freq)
printf "%s\t%d\n", word, freq[word] | sort
close(sort)
@@ -15460,8 +15498,8 @@ File: gawk.info, Node: History Sorting, Next: Extract Program, Prev: Word Sor
Removing Duplicates from Unsorted Text
--------------------------------------
- The `uniq' program (*note Printing Non-Duplicated Lines of Text:
-Uniq Program.), removes duplicate lines from _sorted_ data.
+ The `uniq' program (*note Printing Nonduplicated Lines of Text: Uniq
+Program.), removes duplicate lines from _sorted_ data.
Suppose, however, you need to remove duplicate lines from a data
file but that you want to preserve the order the lines are in. A good
@@ -15525,14 +15563,14 @@ input files:
(`\') is in C or `awk'. Literal `@' symbols are represented in
Texinfo source files as `@@'.
- * Comments start with either `@c' or `@comment'. The file
- extraction program works by using special comments that start at
- the beginning of a line.
+ * Comments start with either `@c' or `@comment'. The
+ file-extraction program works by using special comments that start
+ at the beginning of a line.
* Lines containing `@group' and `@end group' commands bracket
example text that should not be split across a page boundary.
(Unfortunately, TeX isn't always smart enough to do things exactly
- right and we have to give it some help.)
+ right, and we have to give it some help.)
The following program, `extract.awk', reads through a Texinfo source
file and does two things, based on the special comments. Upon seeing
@@ -15700,18 +15738,18 @@ File: gawk.info, Node: Simple Sed, Next: Igawk Program, Prev: Extract Program
A Simple Stream Editor
----------------------
- The `sed' utility is a "stream editor," a program that reads a
-stream of data, makes changes to it, and passes it on. It is often
-used to make global changes to a large file or to a stream of data
-generated by a pipeline of commands. While `sed' is a complicated
-program in its own right, its most common use is to perform global
-substitutions in the middle of a pipeline:
+ The `sed' utility is a stream editor, a program that reads a stream
+of data, makes changes to it, and passes it on. It is often used to
+make global changes to a large file or to a stream of data generated by
+a pipeline of commands. While `sed' is a complicated program in its
+own right, its most common use is to perform global substitutions in
+the middle of a pipeline:
command1 < orig.data | sed 's/old/new/g' | command2 > result
Here, `s/old/new/g' tells `sed' to look for the regexp `old' on each
-input line and globally replace it with the text `new', (i.e., all the
-occurrences on a line). This is similar to `awk''s `gsub' function
+input line and globally replace it with the text `new', i.e., all the
+occurrences on a line. This is similar to `awk''s `gsub' function
(*note String Manipulation Functions: String Functions.).
The following program, `awksed.awk', accepts at least two
@@ -15816,7 +15854,7 @@ ability to have multiple source files specified via `-f', and the
ability to mix command-line and library source files.
The program is written using the POSIX Shell (`sh') command language.
-The way the program works is as follows:
+It works as follows:
1. Loop through the arguments, saving anything that doesn't represent
`awk' source code for later, when the expanded program is run.
@@ -15828,9 +15866,9 @@ The way the program works is as follows:
text is just echoed directly. The `echo' program
automatically supplies a trailing newline.
- b. Source file names provided with `-f'. We use a neat trick
+ b. Source file names, provided with `-f'. We use a neat trick
and echo `@include FILENAME' into the temporary file. Since
- the file inclusion program works the way `gawk' does, this
+ the file-inclusion program works the way `gawk' does, this
gets the text of the file included into the program at the
correct point.
@@ -15876,12 +15914,12 @@ are several cases of interest:
the `gawk' version information, and then exits.
If none of the `-f', `--file', `-Wfile', `--source', or `-Wsource'
-arguments are supplied, then the first non-option argument should be
-the `awk' program. If there are no command-line arguments left,
-`igawk' prints an error message and exits. Otherwise, the first
-argument is echoed into `/tmp/ig.s.$$'. In any case, after the
-arguments have been processed, `/tmp/ig.s.$$' contains the complete
-text of the original `awk' program.
+arguments are supplied, then the first nonoption argument should be the
+`awk' program. If there are no command-line arguments left, `igawk'
+prints an error message and exits. Otherwise, the first argument is
+echoed into `/tmp/ig.s.$$'. In any case, after the arguments have been
+processed, `/tmp/ig.s.$$' contains the complete text of the original
+`awk' program.
The `$$' in `sh' represents the current process ID number. It is
often used in shell programs to generate unique temporary file names.
@@ -16073,10 +16111,9 @@ There are three key simplifications that make the program work better:
the initial collected `awk' program much simpler; all the
`@include' processing can be done once.
- * The `pathto' function doesn't try to save the line read with
- `getline' when testing for the file's accessibility. Trying to
- save this line for use with the main program complicates things
- considerably.
+ * Not trying to save the line read with `getline' in the `pathto'
+ function when testing for the file's accessibility for use with
+ the main program simplifies things considerably.
* Using a `getline' loop in the `BEGIN' rule does it all in one
place. It is not necessary to call out to a separate loop for
@@ -16131,7 +16168,7 @@ Unix. (This implementation was the basis for `awk' in Berkeley Unix,
through 4.3-Reno. Subsequent versions of Berkeley Unix, and 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
+language, with cross-references to other parts of the Info file where
you can find more information.
* Menu:
@@ -16301,7 +16338,7 @@ standard:
Assignment Expressions: Assignment Ops).
* Specifying `-Ft' on the command line does not set the value of
- `FS' to be a single tab character (*note Specifying How Fields Are
+ `FS' to be a single TAB character (*note Specifying How Fields Are
Separated: Field Separators.).
* The `fflush' built-in function is not supported (*note
@@ -16317,7 +16354,7 @@ Extensions in the Bell Laboratories `awk'
made his version available via his home page (*note Other Freely
Available `awk' Implementations: Other Versions.). This minor node
describes extensions in his version of `awk' that are not in POSIX
-`awk'.
+`awk':
* The `-mf N' and `-mr N' command-line options to set the maximum
number of fields and the maximum record size, respectively (*note
@@ -16407,8 +16444,7 @@ options (*note Command-Line Options: Options.).
through `ARGV' (*note Built-in Variables::).
* The `ERRNO' variable, which contains the system error message when
- `getline' returns -1 or when `close' fails (*note Built-in
- Variables::).
+ `getline' returns -1 or `close' fails (*note Built-in Variables::).
* The `/dev/pid', `/dev/ppid', `/dev/pgrpid', and `/dev/user' file
name interpretation (*note Special File Names in `gawk': Special
@@ -16420,7 +16456,7 @@ options (*note Command-Line Options: Options.).
* The ability to use GNU-style long-named options that start with
`--' (*note Command-Line Options: Options.).
- * The `--source' option for mixing command-line and library file
+ * The `--source' option for mixing command-line and library-file
source code (*note Command-Line Options: Options.).
Version 3.0 of `gawk' introduced the following features:
@@ -16492,7 +16528,7 @@ options (*note Command-Line Options: Options.).
* The ability to use octal and hexadecimal constants in `awk'
program source code (*note Octal and Hexadecimal Numbers:
- Non-decimal-numbers.).
+ Nondecimal-numbers.).
* The `|&' operator for two-way I/O to a coprocess (*note Two-Way
Communications with Another Process: Two-way I/O.).
@@ -16540,7 +16576,7 @@ options (*note Command-Line Options: Options.).
Extracting Marked Strings: String Extraction.).
* The `--non-decimal-data' option to allow non-decimal input data
- (*note Allowing Non-Decimal Input Data: Non-decimal Data.).
+ (*note Allowing Nondecimal Input Data: Nondecimal Data.).
* The `--profile' option and `pgawk', the profiling version of
`gawk', for producing execution profiles of `awk' programs (*note
@@ -16610,7 +16646,8 @@ Info file, in approximate chronological order:
* Hal Peterson provided help in porting `gawk' to Cray systems.
- * Kai Uwe Rommel provided the port to OS/2 and its documentation.
+ * Kai Uwe Rommel provided the initial port to OS/2 and its
+ documentation.
* Michal Jaegermann provided the port to Atari systems and its
documentation. He continues to provide portability checking with
@@ -16647,6 +16684,11 @@ Info file, in approximate chronological order:
as well as the code for the new optional third argument to the
`match' function.
+ * Andreas Buening updated the `gawk' port for OS/2.
+
+ Isamu Hasegawa, of IBM in Japan, contributed support for multibyte
+ characters.
+
* Arnold Robbins has been working on `gawk' since 1988, at first
helping David Trueman, and as the primary maintainer since around
1994.
@@ -16700,8 +16742,8 @@ Getting the `gawk' Distribution
* Copy it from someone else who already has it.
* Order `gawk' directly from the Free Software Foundation. Software
- distributions are available for Unix, MS-DOS, and VMS, on tape and
- CD-ROM. Their address is:
+ distributions are available for Gnu/Linux, Unix, and MS-Windows,
+ in several CD packages. Their address is:
Free Software Foundation
59 Temple Place, Suite 330
@@ -16709,13 +16751,13 @@ Getting the `gawk' Distribution
Phone: +1-617-542-5942
Fax (including Japan): +1-617-542-2652
Email: <gnu@gnu.org>
- URL: `http://www.gnu.org/'
+ URL: `http://www.gnu.org'
Ordering from the FSF directly contributes to the support of the
foundation and to the production of more free software.
* Retrieve `gawk' by using anonymous `ftp' to the Internet host
- `gnudist.gnu.org', in the directory `/gnu/gawk'.
+ `ftp.gnu.org', in the directory `/gnu/gawk'.
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
@@ -16732,23 +16774,23 @@ 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.1.0.tar.gz'),
+ Once you have the distribution (for example, `gawk-3.1.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:
# Under System V, add 'o' to the tar options
- gzip -d -c gawk-3.1.0.tar.gz | tar -xvpf -
+ gzip -d -c gawk-3.1.1.tar.gz | tar -xvpf -
-This creates a directory named `gawk-3.1.0' in the current directory.
+This creates a directory named `gawk-3.1.1' in the current directory.
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 0, but when retrieving distributions, you should get the
+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 80 denote "beta" or
-non-production software; you might not want to retrieve such a version
+nonproduction software; you might not want to retrieve such a version
unless you don't mind experimenting.) If you are not on a Unix system,
you need to make other arrangements for getting and extracting the
`gawk' distribution. You should consult a local expert.
@@ -16765,8 +16807,8 @@ configuration process (*note Compiling and Installing `gawk' on Unix:
Unix Installation.), as well as several subdirectories related to
different non-Unix operating systems:
-Various `.c', `.y', and `.h' files:
- These files are the actual `gawk' source code.
+Various `.c', `.y', and `.h' files
+ The actual `gawk' source code.
`README'
`README_d/README.*'
@@ -16794,11 +16836,11 @@ Various `.c', `.y', and `.h' files:
`LIMITATIONS'
A list of those factors that limit `gawk''s performance. Most of
- these depend on the hardware or operating system software, and are
+ 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
+ A description of one area in which the POSIX standard for `awk' is
incorrect as well as how `gawk' handles the problem.
`doc/awkforai.txt'
@@ -16939,7 +16981,7 @@ Compiling `gawk' for Unix
-------------------------
After you have extracted the `gawk' distribution, `cd' to
-`gawk-3.1.0'. Like most GNU software, `gawk' is configured
+`gawk-3.1.1'. 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 is generated automatically
using GNU `autoconf'. (The `autoconf' software is described fully
@@ -16983,12 +17025,12 @@ Additional Configuration Options
--------------------------------
There are several additional options you may use on the `configure'
-command line when compiling `gawk' from scratch.
+command line when compiling `gawk' from scratch, including:
`--enable-portals'
- This option causes `gawk' to treat pathnames that begin with `/p'
- as BSD portal files when doing two-way I/O with the `|&' operator
- (*note Using `gawk' with BSD Portals: Portal Files.).
+ Treat pathnames that begin with `/p' as BSD portal files when
+ doing two-way I/O with the `|&' operator (*note Using `gawk' with
+ BSD Portals: Portal Files.).
`--with-included-gettext'
Use the version of the `gettext' library that comes with `gawk'.
@@ -16997,7 +17039,7 @@ command line when compiling `gawk' from scratch.
systems use Glibc 2. Use this option on any other system.
`--disable-nls'
- Disable all message translation facilities. This is usually not
+ Disable all message-translation facilities. This is usually not
desirable, but it may bring you some slight performance
improvement. You should also use this option if
`--with-included-gettext' doesn't work on your system.
@@ -17154,6 +17196,8 @@ please refer to `README_d/README.pc' in the distribution.
and OS/2.
* PC Using:: Running `gawk' on MS-DOS, Win32 and
OS/2.
+* Cygwin:: Building and running `gawk' for
+ Cygwin.

File: gawk.info, Node: PC Binary Installation, Next: PC Compiling, Prev: PC Installation, Up: PC Installation
@@ -17172,8 +17216,26 @@ and `igawk.bat' (in `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
-`gawk' executable. OS/2 binary distributions may have a different
-arrangement, but installation is similar.
+`gawk' executable.
+
+ 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'. 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):
+
+ install-info --info-dir=x:/usr/info x:/usr/info/gawk.info
+ install-info --info-dir=x:/usr/info x:/usr/info/gawkinet.info
+
+ However, the files can be installed anywhere provided `AWKPATH' is
+set properly.
+
+ The binary distribution may contain a separate file containing
+additional or more detailed installation instructions.

File: gawk.info, Node: PC Compiling, Next: PC Using, Prev: PC Binary Installation, Up: PC Installation
@@ -17189,8 +17251,9 @@ used to build a Win32 version, and Microsoft C/C++ can be used to build
the `gawk' distribution contains additional notes, and `pc/Makefile'
contains important information 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
+ To build `gawk' for MS-DOS, Win32, and OS/2 (16 bit; for 32 bit (EMX)
+see below), 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.
@@ -17210,17 +17273,93 @@ 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'.
-
-File: gawk.info, Node: PC Using, Prev: PC Compiling, Up: PC Installation
+ To build `gawk' for OS/2 (32 bit, EMX), there are three
+possibilities:
+
+ 1. Using the `configure' script included in the official `gawk'
+ distribution. `configure' need not be recreated but a number of
+ restrictions exist when using this choice:
+
+ * An external `gettext' library cannot be used. I.e. the
+ `configure' option `--without-included-gettext' does not
+ work. Unfortunately, the internal `gettext' library is
+ seriuosly broken for OS/2. Therefore you have to use
+ `--disable-nls'.
+
+ * Executables must be linked statically (`a.out' format only).
+ `make install' does not work.
+
+ These restrictions are due to restrictions in Autoconf 2.13
+ and cannot be avoided. They will vanish as soon as `gawk'
+ moves on to Autoconf 2.5x. Now enter the following commands
+ at your `sh' prompt:
+
+ $ CC="gcc"; export CC
+ $ CFLAGS="-O2"; export CFLAGS
+ $ AWK="awk"; export AWK
+ $ LD="ld"; export LD
+ $ LDFLAGS="-Zexe"; export LDFLAGS
+ $ RANLIB="ranlib"; export RANLIB
+ $ ac_cv_header_sys_socket_h="yes"
+ $ export ac_cv_header_sys_socket_h
+ $ ./configure --prefix=c:/usr --disable-nls
+ $ make
+
+ 2. Using a special version of Autoconf 2.13 for OS/2 to recreate
+ `configure'. Not tested. In principle this should work but the
+ same restrictions apply as in 1, but the environment variables
+ `CC', `AWK', `LDFLAGS' and `RANLIB' are not necessary.
+
+ 3. Using Autoconf 2.5x to recreate `configure' (2.52f or higher
+ recommended). Some patches must be applied to `Makefile.am' and
+ `test/Makefile.am' and `po/Makefile.in.in'. Currently not
+ supported.
+
+ *Note:* Even if the compiled `gawk.exe' executable contains a DOS
+header (`a.out' format), it does _not_ work under DOS. To compile an
+executable that runs under DOS, `CPPFLAGS' must be set to
+`"-DPIPES_SIMULATED"'. But then some nonstandard extensions of `gawk'
+(e.g., `|&') do not work!
+
+ After compilation the internal tests can be performed. Enter `make
+check CMP="diff -a"' at your command prompt. All tests but the `pid'
+test are expected to work properly. The `pid' test might or might not
+work, no idea why.
+
+ *Note:* Most 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. You should find the latest version on
+`ftp://ftp.unixos2.org'.
+
+
+File: gawk.info, Node: PC Using, Next: Cygwin, Prev: PC Compiling, Up: PC Installation
Using `gawk' on PC Operating Systems
....................................
+ With the exception of the Cygwin environment, the `|&' operator and
+TCP/IP networking (*note Using `gawk' for Network Programming: TCP/IP
+Networking.) are not supported for MS-DOS or MS-Windows. EMX (OS/2
+only) does support at least the `|&' operator.
+
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"'.
+default search path for OS/2 (16 bit) and MS-DOS versions is
+`".;c:/lib/awk;c:/gnu/lib/awk"'.
+
+ 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"'.
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
@@ -17236,7 +17375,7 @@ for `gawk' in the shell configuration may need to be changed and the
Under OS/2 and 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 allows control over
-these translations and is interpreted as follows.
+these translations and is interpreted as follows:
* If `BINMODE' is `"r"', or `(BINMODE & 1)' is nonzero, then binary
mode is set on read (i.e., no translations on reads).
@@ -17269,7 +17408,7 @@ 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 DOS-style end-of-line.
- To Illustrate, the following examples set binary mode on writes for
+ To illustrate, the following examples set binary mode on writes for
standard output and other files, and set `ORS' as the "usual" DOS-style
end-of-line:
@@ -17293,6 +17432,36 @@ With proper quoting, in the first example the setting of `RS' can be
moved into the `BEGIN' rule.

+File: gawk.info, Node: Cygwin, Prev: PC Using, Up: PC Installation
+
+Using `gawk' In The Cygwin Environment
+......................................
+
+ `gawk' can be used "out of the box" under Windows if you are using
+the Cygwin environment.(1) 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 tools. Compilation
+and installation for Cygwin is the same as for a Unix system:
+
+ tar -xvpzf gawk-3.1.1.tar.gz
+ cd gawk-3.1.1
+ ./configure
+ make
+
+ 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.
+
+ *Note:* The `|&' operator and TCP/IP networking (*note Using `gawk'
+for Network Programming: TCP/IP Networking.) are fully supported in
+the Cygwin environment. This is not true for any other environment for
+MS-DOS or MS-Windows.
+
+ ---------- Footnotes ----------
+
+ (1) `http://www.cygwin.com'
+
+
File: gawk.info, Node: VMS Installation, Prev: PC Installation, Up: Non-Unix Installation
How to Compile and Install `gawk' on VMS
@@ -17692,7 +17861,8 @@ BeOS Martin Brown, <mc@whoever.com>.
MS-DOS Scott Deifik, <scottd@amgen.com> and Darrel
Hankerson, <hankedr@mail.auburn.edu>.
MS-Windows Juan Grigera, <juan@biophnet.unlp.edu.ar>.
-OS/2 Kai Uwe Rommel, <rommel@ars.de>.
+OS/2 The Unix for OS/2 team,
+ <gawk-maintainer@unixos2.org>.
Tandem Stephen Davies, <scldad@sdc.com.au>.
VMS Pat Rankin, <rankin@eql.caltech.edu>.
@@ -17830,7 +18000,7 @@ one more option available on the command line:
`-W parsedebug'
`--parsedebug'
- Print out the parse stack information as the program is being
+ Prints out the parse stack information as the program is being
parsed.
This option is intended only for serious `gawk' developers and not
@@ -17886,8 +18056,8 @@ make it possible for me to include your changes:
haven't read it, please do so, preferably _before_ starting to
modify `gawk'. (The `GNU Coding Standards' are available from the
GNU Project's `ftp' site, at
- `ftp://gnudist.gnu.org/gnu/GNUInfo/standards.text'. Texinfo,
- Info, and DVI versions are also available.)
+ `ftp://ftp.gnu.org/gnu/GNUInfo/standards.text'. Texinfo, Info,
+ and DVI versions are also available.)
4. Use the `gawk' coding style. The C code for `gawk' follows the
instructions in the `GNU Coding Standards', with minor exceptions.
@@ -17996,12 +18166,12 @@ Porting `gawk' to a New Operating System
----------------------------------------
If you want to port `gawk' to a new operating system, there are
-several steps to follow:
+several steps:
1. Follow the guidelines in *Note Adding New Features: Adding Code,
concerning coding style, submission of diffs, and so on.
- 2. When doing a port, bear in mind that your code must co-exist
+ 2. 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
@@ -18065,8 +18235,8 @@ several steps to follow:
you have questions, please contact me, or <gnu@gnu.org>.
Following these steps makes it much easier to integrate your changes
-into `gawk' and have them co-exist happily with other operating
-systems' code that is already there.
+into `gawk' and have them coexist happily with other 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.
@@ -18211,7 +18381,7 @@ when writing extensions. The next minor node shows how they are used:
`NODE *get_argument(NODE *tree, 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
+ the `i'-th argument from the function call. The first argument is
argument zero.
`void set_value(NODE *tree)'
@@ -18227,7 +18397,7 @@ when writing extensions. The next minor node shows how they are used:
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 "boiler plate" code shows how to do
+function parameter. The following boilerplate code shows how to do
this:
NODE *the_arg;
@@ -18650,14 +18820,14 @@ well.
Following is a list of probable future changes visible at the `awk'
language level:
-Loadable Module Interface
+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.
-`RECLEN' variable for fixed length records
+`RECLEN' variable for fixed-length records
Along with `FIELDWIDTHS', this would speed up the processing of
fixed-length records. `PROCINFO["RS"]' would be `"RS"' or
`"RECLEN"', depending upon which kind of record processing is in
@@ -18672,7 +18842,7 @@ Databases
It may be possible to map a GDBM/NDBM/SDBM file into an `awk'
array.
-Large Character Sets
+Large character sets
It would be nice if `gawk' could handle UTF-8 and other character
sets that are larger than eight bits.
@@ -18682,7 +18852,7 @@ More `lint' warnings
Following is a list of probable improvements that will make `gawk''s
source code easier to work with:
-Loadable Module Mechanics
+Loadable module mechanics
The current extension mechanism works (*note Adding New Built-in
Functions to `gawk': Dynamic Extensions.), but is rather
primitive. It requires a fair amount of manual work to create and
@@ -18691,24 +18861,24 @@ Loadable Module Mechanics
a number of features that would make using loadable modules much
easier. `gawk' should be changed to use `libtool'.
-Loadable Module Internals
+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
+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
one copy of the index value.
-Integrating the DBUG Library
+Integrating the DBUG library
Integrating Fred Fish's DBUG library would be helpful during
development, but it's a lot of work to do.
Following is a list of probable improvements that will make `gawk'
perform better:
-An Improved Version of `dfa'
+An improved version of `dfa'
The `dfa' pattern matcher from GNU `grep' has some problems.
Either a new version or a fixed one will deal with some important
regexp matching issues.
@@ -18823,7 +18993,7 @@ Clean Up
After the cake comes out of the oven, you still have to wrap it in
plastic wrap to keep anyone from tasting it, as well as wash the
- mixing bowls and other utensils.
+ mixing bowls and utensils.
An "algorithm" is a detailed set of instructions necessary to
accomplish a task, or process data. It is much the same as a recipe
@@ -18839,7 +19009,7 @@ record.
The act of reading data is termed "input", and that of generating
results, not too surprisingly, is termed "output". They are often
-referred to together as "Input/Output," and even more often, as "I/O"
+referred to together as "input/output," and even more often, as "I/O"
for short. (You will also see "input" and "output" used as verbs.)
`awk' manages the reading of data for you, as well as the breaking
@@ -18864,7 +19034,7 @@ Data Values in a Computer
In a program, you keep track of information and values in things
called "variables". A variable is just a name for a given value, such
as `first_name', `last_name', `address', and so on. `awk' has several
-pre-defined variables, and it has special names to refer to the current
+predefined variables, and it has special names to refer to the current
input record and the fields of the record. You may also group multiple
associated values under one name, as an array.
@@ -18876,7 +19046,7 @@ characters that comprise them. Individual variables, as well as
numeric and string variables, are referred to as "scalar" values.
Groups of values, such as arrays, are not scalars.
- Within computers, there are two kinds of numeric values: "integers",
+ Within computers, there are two kinds of numeric values: "integers"
and "floating-point". In school, integer values were referred to as
"whole" numbers--that is, numbers without any fractional part, such as
1, 42, or -17. The advantage to integer numbers is that they represent
@@ -18920,7 +19090,7 @@ binary, each column represents two times the value in the column to its
right. Each column may contain either a 0 or a 1. Thus, binary 1010
represents 1 times 8, plus 0 times 4, plus 1 times 2, plus 0 times 1,
or decimal 10. Octal and hexadecimal are discussed more in *Note Octal
-and Hexadecimal Numbers: Non-decimal-numbers.
+and Hexadecimal Numbers: Nondecimal-numbers.
Programs are written in programming languages. Hundreds, if not
thousands, of programming languages exist. One of the most popular is
@@ -18932,7 +19102,7 @@ to as "K&R" C, after the initials of Brian Kernighan and Dennis Ritchie,
the authors of the first book on C. (Dennis Ritchie created the
language, and Brian Kernighan was one of the creators of `awk'.)
- In the mid-1980's, an effort began to produce an international
+ In the mid-1980s, an effort began to produce an international
standard for C. This work culminated in 1989, with the production of
the ANSI standard for C. This standard became an ISO standard in 1990.
Where it makes sense, POSIX `awk' is compatible with 1990 ISO C.
@@ -18947,16 +19117,16 @@ Floating-Point Number Caveats
=============================
As mentioned earlier, floating-point numbers represent what are
-called "real" numbers; i.e., those that have a fractional part. `awk'
+called "real" numbers, i.e., those that have a fractional part. `awk'
uses double-precision floating-point numbers to represent all numeric
values. This minor node describes some of the issues involved in using
floating-point numbers.
There is a very nice paper on floating-point arithmetic by David
-Goldberg, `What Every Computer Scientist Should Know About
-Floating-point Arithmetic', `ACM Computing Surveys' *23*, 1 (1991-03),
+Goldberg, "What Every Computer Scientist Should Know About
+Floating-point Arithmetic," `ACM Computing Surveys' *23*, 1 (1991-03),
5-48.(1) This is worth reading if you are interested in the details,
-but it does require a background in Computer Science.
+but it does require a background in computer science.
Internally, `awk' keeps both the numeric value (double-precision
floating-point) and the string value for a variable. Separately, `awk'
@@ -19043,7 +19213,7 @@ noted and can affect comparisons.
---------- Footnotes ----------
- (1) `http://www.validgh.com/goldberg/paper.ps'
+ (1) `http://www.validgh.com/goldberg/paper.ps'.
(2) Pathological cases can require up to 752 digits (!), but we
doubt that you need to worry about this.
@@ -19292,7 +19462,7 @@ Epoch
See also "GMT" and "UTC."
Escape Sequences
- A special sequence of characters used for describing non-printing
+ A special sequence of characters used for describing nonprinting
characters, such as `\n' for newline or `\033' for the ASCII ESC
(Escape) character. (*Note Escape Sequences::.)
@@ -19310,7 +19480,7 @@ Field
Flag
A variable whose truth value indicates the existence or
- non-existence of some condition.
+ nonexistence of some condition.
Floating-Point Number
Often referred to in mathematical terms as a "rational" or real
@@ -19339,7 +19509,7 @@ FSF
See "Free Software Foundation."
Free Software Foundation
- A non-profit organization dedicated to the production and
+ A nonprofit organization dedicated to the production and
distribution of freely distributable software. It was founded by
Richard M. Stallman, the author of the original Emacs editor. GNU
Emacs is the most widely used version of Emacs today.
@@ -19652,7 +19822,7 @@ UTC
and "GMT."
Whitespace
- A sequence of space, tab, or newline characters occurring inside
+ A sequence of space, TAB, or newline characters occurring inside
an input record or a string.

@@ -19662,7 +19832,6 @@ GNU General Public License
**************************
Version 2, June 1991
-
Copyright (C) 1989, 1991 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA 02111, USA
@@ -19721,7 +19890,6 @@ patent must be licensed for everyone's free use or not licensed at all.
modification follow.
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
-
0. This License applies to any program or other work which contains a
notice placed by the copyright holder saying it may be distributed
under the terms of this General Public License. The "Program",
@@ -20034,7 +20202,6 @@ GNU Free Documentation License
of this license document, but changing it is not allowed.
-
0. PREAMBLE
The purpose of this License is to make a manual, textbook, or other
@@ -20121,7 +20288,6 @@ GNU Free Documentation License
Page" means the text near the most prominent appearance of the
work's title, preceding the beginning of the body of the text.
-
2. VERBATIM COPYING
You may copy and distribute the Document in any medium, either
@@ -20138,7 +20304,6 @@ GNU Free Documentation License
You may also lend copies, under the same conditions stated above,
and you may publicly display copies.
-
3. COPYING IN QUANTITY
If you publish printed copies of the Document numbering more than
@@ -20179,7 +20344,6 @@ GNU Free Documentation License
copies, to give them a chance to provide you with an updated
version of the Document.
-
4. MODIFICATIONS
You may copy and distribute a Modified Version of the Document
@@ -20285,7 +20449,6 @@ GNU Free Documentation License
License give permission to use their names for publicity for or to
assert or imply endorsement of any Modified Version.
-
5. COMBINING DOCUMENTS
You may combine the Document with other documents released under
@@ -20311,7 +20474,6 @@ GNU Free Documentation License
"Acknowledgements", and any sections entitled "Dedications". You
must delete all sections entitled "Endorsements."
-
6. COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other
@@ -20327,7 +20489,6 @@ GNU Free Documentation License
this License in all other respects regarding verbatim copying of
that document.
-
7. AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other
@@ -20347,7 +20508,6 @@ GNU Free Documentation License
aggregate. Otherwise they must appear on covers around the whole
aggregate.
-
8. TRANSLATION
Translation is considered a kind of modification, so you may
@@ -20361,7 +20521,6 @@ GNU Free Documentation License
disagreement between the translation and the original English
version of this License, the original English version will prevail.
-
9. TERMINATION
You may not copy, modify, sublicense, or distribute the Document
@@ -20372,7 +20531,6 @@ GNU Free Documentation License
from you under this License will not have their licenses
terminated so long as such parties remain in full compliance.
-
10. FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions of
@@ -20426,46 +20584,76 @@ Index
* Menu:
+* ! (exclamation point), ! operator: Boolean Ops.
+* ! (exclamation point), ! operator <1>: Egrep Program.
+* ! (exclamation point), ! operator: Precedence.
+* ! (exclamation point), != operator <1>: Precedence.
+* ! (exclamation point), != operator: Typing and Comparison.
+* ! (exclamation point), !~ operator <1>: Expression Patterns.
+* ! (exclamation point), !~ operator <2>: Precedence.
+* ! (exclamation point), !~ operator <3>: Typing and Comparison.
+* ! (exclamation point), !~ operator <4>: Regexp Constants.
+* ! (exclamation point), !~ operator <5>: Computed Regexps.
+* ! (exclamation point), !~ operator <6>: Case-sensitivity.
+* ! (exclamation point), !~ operator: Regexp Usage.
* ! operator <1>: Egrep Program.
-* ! operator <2>: Ranges.
-* ! operator <3>: Precedence.
-* ! operator: Boolean Ops.
-* != operator <1>: Precedence.
-* != operator: Typing and Comparison.
-* !~ operator <1>: Precedence.
-* !~ operator <2>: Typing and Comparison.
-* !~ operator <3>: Regexp Constants.
-* !~ operator <4>: Computed Regexps.
-* !~ operator <5>: Case-sensitivity.
-* !~ operator: Regexp Usage.
-* # (comment): Comments.
-* #! (executable scripts): Executable Scripts.
-* $ field operator <1>: Precedence.
+* ! operator: Ranges.
+* " (double quote) <1>: Quoting.
+* " (double quote): Read Terminal.
+* " (double quote), regexp constants: Computed Regexps.
+* # (number sign), #! (executable scripts): Executable Scripts.
+* # (number sign), #! (executable scripts), portability issues with: Executable Scripts.
+* # (number sign), commenting: Comments.
+* $ (dollar sign): Regexp Operators.
+* $ (dollar sign), $ field operator <1>: Precedence.
+* $ (dollar sign), $ field operator: Fields.
+* $ (dollar sign), incrementing fields and arrays: Increment Ops.
* $ field operator: Fields.
-* % operator: Precedence.
-* %= operator <1>: Precedence.
-* %= operator: Assignment Ops.
-* && operator <1>: Precedence.
-* && operator: Boolean Ops.
-* * operator: Precedence.
-* ** operator: Precedence.
-* **= operator <1>: Precedence.
-* **= operator: Assignment Ops.
-* *= operator <1>: Precedence.
-* *= operator: Assignment Ops.
-* + operator: Precedence.
-* ++ operator <1>: Precedence.
-* ++ operator: Increment Ops.
-* += operator <1>: Precedence.
-* += operator: Assignment Ops.
-* - operator: Precedence.
-* -- operator <1>: Precedence.
-* -- operator: Increment Ops.
+* % (percent sign), % operator: Precedence.
+* % (percent sign), %= operator <1>: Precedence.
+* % (percent sign), %= operator: Assignment Ops.
+* & (ampersand), && operator <1>: Precedence.
+* & (ampersand), && operator: Boolean Ops.
+* & (ampersand), gsub/gensub/sub functions and: Gory Details.
+* ' (single quote) <1>: Quoting.
+* ' (single quote) <2>: Long.
+* ' (single quote): One-shot.
+* ' (single quote), vs. apostrophe: Comments.
+* ' (single quote), with double quotes: Quoting.
+* () (parentheses): Regexp Operators.
+* () (parentheses), pgawk program: Profiling.
+* * (asterisk), * operator, as multiplication operator: Precedence.
+* * (asterisk), * operator, as regexp operator: Regexp Operators.
+* * (asterisk), * operator, null strings, matching: Gory Details.
+* * (asterisk), ** operator <1>: Options.
+* * (asterisk), ** operator <2>: Precedence.
+* * (asterisk), ** operator: Arithmetic Ops.
+* * (asterisk), **= operator <1>: Options.
+* * (asterisk), **= operator <2>: Precedence.
+* * (asterisk), **= operator: Assignment Ops.
+* * (asterisk), *= operator <1>: Precedence.
+* * (asterisk), *= operator: Assignment Ops.
+* + (plus sign): Regexp Operators.
+* + (plus sign), + operator: Precedence.
+* + (plus sign), ++ operator <1>: Precedence.
+* + (plus sign), ++ operator: Increment Ops.
+* + (plus sign), += operator <1>: Precedence.
+* + (plus sign), += operator: Assignment Ops.
+* + (plus sign), decrement/increment operators: Increment Ops.
+* , (comma), in range patterns: Ranges.
+* - (hyphen), - operator: Precedence.
+* - (hyphen), -- (decrement/increment) operator: Precedence.
+* - (hyphen), -- operator: Increment Ops.
+* - (hyphen), -= operator <1>: Precedence.
+* - (hyphen), -= operator: Assignment Ops.
+* - (hyphen), filenames beginning with: Options.
+* - (hyphen), in character lists: Character Lists.
* --assign option: Options.
* --compat option: Options.
* --copyleft option: Options.
* --copyright option: Options.
* --disable-nls configuration option: Additional Configuration Options.
+* --dump-variables option <1>: Library Names.
* --dump-variables option: Options.
* --enable-portals configuration option <1>: Additional Configuration Options.
* --enable-portals configuration option: Portal Files.
@@ -20474,234 +20662,369 @@ Index
* --gen-po option <1>: Options.
* --gen-po option: String Extraction.
* --help option: Options.
-* --lint option: Options.
+* --lint option <1>: Options.
+* --lint option: Command Line.
* --lint-old option: Options.
* --non-decimal-data option <1>: Options.
-* --non-decimal-data option: Non-decimal Data.
+* --non-decimal-data option: Nondecimal Data.
+* --non-decimal-data option, strtonum function and: Nondecimal Data.
* --posix option: Options.
-* --profile option: Options.
+* --posix option, --traditional option and: Options.
+* --profile option <1>: Options.
+* --profile option: Profiling.
* --re-interval option: Options.
* --source option: Options.
* --traditional option: Options.
+* --traditional option, --posix option and: Options.
* --usage option: Options.
* --version option: Options.
* --with-included-gettext configuration option <1>: Additional Configuration Options.
* --with-included-gettext configuration option: Gawk I18N.
-* -= operator <1>: Precedence.
-* -= operator: Assignment Ops.
+* --with-included-gettext configuration option, configuring gawk with: Additional Configuration Options.
* -f option: Options.
* -F option <1>: Options.
* -F option: Command Line Field Separator.
* -f option: Long.
-* -mf option: Options.
-* -mr option: Options.
+* -F option, -Ft sets FS to TAB: Options.
+* -f option, on command line: Options.
+* -F option, troubleshooting: Known Bugs.
+* -mf/-mr options: Options.
* -v option: Options.
+* -v option, variables, assigning: Assignment Options.
* -W option: Options.
-* / operator: Precedence.
-* /= operator <1>: Precedence.
-* /= operator: Assignment Ops.
+* . (period): Regexp Operators.
+* .mo files: Explaining gettext.
+* .mo files, converting from .po: I18N Example.
+* .mo files, specifying directory of <1>: Programmer i18n.
+* .mo files, specifying directory of: Explaining gettext.
+* .po files <1>: Translator i18n.
+* .po files: Explaining gettext.
+* .po files, converting to .mo: I18N Example.
+* / (forward slash): Regexp.
+* / (forward slash), / operator: Precedence.
+* / (forward slash), /= operator <1>: Precedence.
+* / (forward slash), /= operator: Assignment Ops.
+* / (forward slash), /= operator, vs. /=.../ regexp constant: Assignment Ops.
+* / (forward slash), patterns and: Expression Patterns.
* /= operator vs. /=.../ regexp constant: Assignment Ops.
-* /dev/fd special files: Special FD.
-* /dev/pgrpid special file: Special Process.
-* /dev/pid special file: Special Process.
-* /dev/ppid special file: Special Process.
-* /dev/stderr special file: Special FD.
-* /dev/stdin special file: Special FD.
-* /dev/stdout special file: Special FD.
-* /dev/user special file: Special Process.
-* /inet special files: TCP/IP Networking.
-* /p special files: Portal Files.
-* < I/O operator: Getline/File.
-* < operator <1>: Precedence.
-* < operator: Typing and Comparison.
-* <= operator <1>: Precedence.
-* <= operator: Typing and Comparison.
-* = operator: Assignment Ops.
-* == operator <1>: Precedence.
-* == operator: Typing and Comparison.
-* > I/O operator: Redirection.
-* > operator <1>: Precedence.
-* > operator: Typing and Comparison.
-* >= operator <1>: Precedence.
-* >= operator: Typing and Comparison.
-* >> I/O operator <1>: Precedence.
-* >> I/O operator: Redirection.
-* ?: operator: Precedence.
-* \" escape sequence: Escape Sequences.
-* \' regexp operator: GNU Regexp Operators.
-* \/ escape sequence: Escape Sequences.
-* \< regexp operator: GNU Regexp Operators.
-* \> regexp operator: GNU Regexp Operators.
-* \` regexp operator: GNU Regexp Operators.
-* \a escape sequence: Escape Sequences.
-* \b escape sequence: Escape Sequences.
-* \B regexp operator: GNU Regexp Operators.
-* \f escape sequence: Escape Sequences.
-* \n escape sequence: Escape Sequences.
-* \NNN escape sequence (octal): Escape Sequences.
-* \r escape sequence: Escape Sequences.
-* \t escape sequence: Escape Sequences.
-* \v escape sequence: Escape Sequences.
-* \W regexp operator: GNU Regexp Operators.
-* \w regexp operator: GNU Regexp Operators.
-* \x escape sequence: Escape Sequences.
-* \y regexp operator: GNU Regexp Operators.
-* ^ operator: Precedence.
-* ^= operator <1>: Precedence.
-* ^= operator: Assignment Ops.
-* _ C macro (gettext): Explaining gettext.
+* /dev/... special files (gawk): Special FD.
+* /inet/ files (gawk): TCP/IP Networking.
+* /p files (gawk): Portal Files.
+* ; (semicolon): Statements/Lines.
+* ; (semicolon), AWKPATH variable and: PC Using.
+* ; (semicolon), separating statements in actions <1>: Statements.
+* ; (semicolon), separating statements in actions: Action Overview.
+* < (left angle bracket), < operator <1>: Precedence.
+* < (left angle bracket), < operator: Typing and Comparison.
+* < (left angle bracket), < operator (I/O): Getline/File.
+* < (left angle bracket), <= operator <1>: Precedence.
+* < (left angle bracket), <= operator: Typing and Comparison.
+* = (equals sign), = operator: Assignment Ops.
+* = (equals sign), == operator <1>: Precedence.
+* = (equals sign), == operator: Typing and Comparison.
+* > (right angle bracket), > operator <1>: Precedence.
+* > (right angle bracket), > operator: Typing and Comparison.
+* > (right angle bracket), > operator (I/O): Redirection.
+* > (right angle bracket), >= operator <1>: Precedence.
+* > (right angle bracket), >= operator: Typing and Comparison.
+* > (right angle bracket), >> operator (I/O) <1>: Precedence.
+* > (right angle bracket), >> operator (I/O): Redirection.
+* ? (question mark) <1>: GNU Regexp Operators.
+* ? (question mark): Regexp Operators.
+* ? (question mark), ?: operator: Precedence.
+* [] (square brackets): Regexp Operators.
+* \ (backslash) <1>: Regexp Operators.
+* \ (backslash) <2>: Quoting.
+* \ (backslash) <3>: Comments.
+* \ (backslash): Read Terminal.
+* \ (backslash), \" escape sequence: Escape Sequences.
+* \ (backslash), \' operator (gawk): GNU Regexp Operators.
+* \ (backslash), \/ escape sequence: Escape Sequences.
+* \ (backslash), \< operator (gawk): GNU Regexp Operators.
+* \ (backslash), \> operator (gawk): GNU Regexp Operators.
+* \ (backslash), \` operator (gawk): GNU Regexp Operators.
+* \ (backslash), \a escape sequence: Escape Sequences.
+* \ (backslash), \b escape sequence: Escape Sequences.
+* \ (backslash), \B operator (gawk): GNU Regexp Operators.
+* \ (backslash), \f escape sequence: Escape Sequences.
+* \ (backslash), \n escape sequence: Escape Sequences.
+* \ (backslash), \NNN escape sequence: Escape Sequences.
+* \ (backslash), \r escape sequence: Escape Sequences.
+* \ (backslash), \t escape sequence: Escape Sequences.
+* \ (backslash), \v escape sequence: Escape Sequences.
+* \ (backslash), \W operator (gawk): GNU Regexp Operators.
+* \ (backslash), \w operator (gawk): GNU Regexp Operators.
+* \ (backslash), \x escape sequence: Escape Sequences.
+* \ (backslash), \y operator (gawk): GNU Regexp Operators.
+* \ (backslash), as field separators: Command Line Field Separator.
+* \ (backslash), continuing lines and <1>: Egrep Program.
+* \ (backslash), continuing lines and: Statements/Lines.
+* \ (backslash), continuing lines and, comments and: Statements/Lines.
+* \ (backslash), continuing lines and, in csh <1>: Statements/Lines.
+* \ (backslash), continuing lines and, in csh: More Complex.
+* \ (backslash), gsub/gensub/sub functions and: Gory Details.
+* \ (backslash), in character lists: Character Lists.
+* \ (backslash), in escape sequences: Escape Sequences.
+* \ (backslash), in escape sequences, POSIX and: Escape Sequences.
+* \ (backslash), regexp constants: Computed Regexps.
+* ^ (caret) <1>: GNU Regexp Operators.
+* ^ (caret): Regexp Operators.
+* ^ (caret), ^ operator <1>: Options.
+* ^ (caret), ^ operator: Precedence.
+* ^ (caret), ^= operator <1>: Options.
+* ^ (caret), ^= operator <2>: Precedence.
+* ^ (caret), ^= operator: Assignment Ops.
+* ^ (caret), in character lists: Character Lists.
+* _ (underscore), _ C macro: Explaining gettext.
+* _ (underscore), in names of private variables: Library Names.
+* _ (underscore), translatable string: Programmer i18n.
* _gr_init user-defined function: Group Functions.
* _pw_init user-defined function: Passwd Functions.
* accessing fields: Fields.
* account information <1>: Group Functions.
* account information: Passwd Functions.
-* acronym: History.
-* action, curly braces: Action Overview.
-* action, default: Very Simple.
-* action, definition of: Action Overview.
-* action, empty: Very Simple.
-* action, separating statements: Action Overview.
-* adding new features: Adding Code.
-* addition: Arithmetic Ops.
-* advanced features: Advanced Features.
-* advanced notes <1>: I/O Functions.
-* advanced notes <2>: Gory Details.
-* advanced notes <3>: Auto-set.
-* advanced notes <4>: Increment Ops.
-* advanced notes <5>: Assignment Ops.
-* advanced notes <6>: Non-decimal-numbers.
-* advanced notes <7>: Close Files And Pipes.
-* advanced notes <8>: Redirection.
-* advanced notes <9>: Records.
-* advanced notes <10>: Computed Regexps.
-* advanced notes <11>: Escape Sequences.
-* advanced notes: Executable Scripts.
+* actions: Action Overview.
+* actions, control statements in: Statements.
+* actions, default: Very Simple.
+* actions, empty: Very Simple.
+* adding, features to gawk: Adding Code.
+* adding, fields: Changing Fields.
+* adding, functions to gawk: Dynamic Extensions.
+* advanced features, buffering: I/O Functions.
+* advanced features, close function: Close Files And Pipes.
+* advanced features, constants, values of: Nondecimal-numbers.
+* advanced features, data files as single record: Records.
+* advanced features, fixed-width data: Constant Size.
+* advanced features, FNR/NR variables: Auto-set.
+* advanced features, gawk: Advanced Features.
+* advanced features, gawk, BSD portals: Portal Files.
+* advanced features, gawk, network programming: TCP/IP Networking.
+* advanced features, gawk, nondecimal input data: Nondecimal Data.
+* advanced features, gawk, processes, communicating with: Two-way I/O.
+* advanced features, network connections, See Also networks, connections: Advanced Features.
+* advanced features, null strings, matching: Gory Details.
+* advanced features, operators, precedence: Increment Ops.
+* advanced features, piping into sh: Redirection.
+* advanced features, regexp constants: Assignment Ops.
* Aho, Alfred <1>: Contributors.
* Aho, Alfred: History.
-* AI programming, using gawk: Distribution contents.
+* alarm clock example program: Alarm Program.
* alarm.awk program: Alarm Program.
-* algorithm, definition of: Basic High Level.
+* algorithms: Basic High Level.
+* Alpha (DEC): Manual History.
* amazing awk assembler (aaa): Glossary.
* amazingly workable formatter (awf): Glossary.
* ambiguity, syntactic: /= operator vs. /=.../ regexp constant: Assignment Ops.
* amiga: Amiga Installation.
-* anchors in regexps: Regexp Operators.
+* ampersand (&), && operator: Boolean Ops.
+* ampersand (&), &&operator: Precedence.
+* ampersand (&), gsub/gensub/sub functions and: Gory Details.
* AND bitwise operation: Bitwise Functions.
-* and built-in function: Bitwise Functions.
-* AND logical operator: Boolean Ops.
-* anonymous ftp: Getting.
+* and Boolean-logic operator: Boolean Ops.
+* and function (gawk): Bitwise Functions.
* ANSI: Glossary.
-* applications of awk <1>: When.
-* applications of awk: Preface.
* archeologists: Bugs.
-* ARGC variable: Auto-set.
-* ARGIND variable <1>: Other Arguments.
+* ARGC/ARGV variables <1>: ARGC and ARGV.
+* ARGC/ARGV variables: Auto-set.
+* ARGC/ARGV variables, command-line arguments: Other Arguments.
+* ARGC/ARGV variables, portability and: Executable Scripts.
* ARGIND variable: Auto-set.
-* argument processing: Getopt Function.
-* arguments in function call: Function Calls.
-* arguments, command-line: Command Line.
-* ARGV variable <1>: Other Arguments.
-* ARGV variable: Auto-set.
+* ARGIND variable, command-line arguments: Other Arguments.
+* arguments, command-line <1>: Other Arguments.
+* arguments, command-line <2>: ARGC and ARGV.
+* arguments, command-line: Auto-set.
+* arguments, command-line, invoking awk: Command Line.
+* arguments, in function calls: Function Calls.
+* arguments, processing: Getopt Function.
+* arguments, retrieving: Internals.
* arithmetic operators: Arithmetic Ops.
-* array assignment: Assigning Elements.
-* array reference: Reference to Elements.
-* arrays: Array Intro.
+* arrays: Arrays.
+* arrays, as parameters to functions: Function Caveats.
* arrays, associative: Array Intro.
-* arrays, definition of: Array Intro.
-* arrays, deleting an element: Delete.
+* arrays, associative, clearing: Internals.
+* arrays, associative, library functions and: Library Names.
* arrays, deleting entire contents: Delete.
-* arrays, multidimensional subscripts: Multi-dimensional.
-* arrays, presence of elements: Reference to Elements.
+* arrays, elements, assigning: Assigning Elements.
+* arrays, elements, deleting: Delete.
+* arrays, elements, installing: Internals.
+* arrays, elements, order of: Scanning an Array.
+* arrays, elements, referencing: Reference to Elements.
+* arrays, elements, retrieving number of: String Functions.
+* arrays, for statement and: Scanning an Array.
+* arrays, IGNORECASE variable and: Array Intro.
+* arrays, indexing: Array Intro.
+* arrays, merging into strings: Join Function.
+* arrays, multidimensional: Multi-dimensional.
+* arrays, multidimensional, scanning: Multi-scanning.
+* arrays, names of: Arrays.
+* arrays, scanning: Scanning an Array.
* arrays, sorting: Array Sorting.
-* arrays, sorting and IGNORECASE: Array Sorting.
+* arrays, sorting, IGNORECASE variable and: Array Sorting.
* arrays, sparse: Array Intro.
-* arrays, special for statement: Scanning an Array.
-* arrays, subscripts, and IGNORECASE: Array Intro.
-* arrays, subscripts, uninitialized variables: Uninitialized Subscripts.
-* arrays, the in operator: Reference to Elements.
-* artificial intelligence, using gawk: Distribution contents.
+* arrays, subscripts: Numeric Array Subscripts.
+* arrays, subscripts, uninitialized variables as: Uninitialized Subscripts.
+* artificial intelligence, gawk and: Distribution contents.
* ASCII: Ordinal Functions.
-* asort built-in function <1>: String Functions.
-* asort built-in function: Array Sorting.
-* assert C library function: Assert Function.
+* asort function (gawk) <1>: String Functions.
+* asort function (gawk): Array Sorting.
+* asort function (gawk), arrays, sorting: Array Sorting.
+* assert function (C library): Assert Function.
* assert user-defined function: Assert Function.
* assertions: Assert Function.
* assignment operators: Assignment Ops.
-* assignment to fields: Changing Fields.
+* assignment operators, evaluation order: Assignment Ops.
+* assignment operators, lvalues/rvalues: Assignment Ops.
+* assignments as filenames: Ignoring Assigns.
* assoc_clear internal function: Internals.
* assoc_lookup internal function: Internals.
* associative arrays: Array Intro.
-* atan2 built-in function: Numeric Functions.
+* asterisk (*), * operator, as multiplication operator: Precedence.
+* asterisk (*), * operator, as regexp operator: Regexp Operators.
+* asterisk (*), * operator, null strings, matching: Gory Details.
+* asterisk (*), ** operator <1>: Options.
+* asterisk (*), ** operator <2>: Precedence.
+* asterisk (*), ** operator: Arithmetic Ops.
+* asterisk (*), **= operator <1>: Options.
+* asterisk (*), **= operator <2>: Precedence.
+* asterisk (*), **= operator: Assignment Ops.
+* asterisk (*), *= operator <1>: Precedence.
+* asterisk (*), *= operator: Assignment Ops.
+* atan2 function: Numeric Functions.
* atari: Atari Installation.
-* automatic initialization: More Complex.
-* automatic warnings <1>: Options.
-* automatic warnings <2>: I/O Functions.
-* automatic warnings <3>: String Functions.
-* automatic warnings <4>: Using Constant Regexps.
-* automatic warnings <5>: Special Caveats.
-* automatic warnings <6>: Special Process.
-* automatic warnings: Escape Sequences.
* awf (amazingly workable formatter) program: Glossary.
-* awk language, POSIX version <1>: Definition Syntax.
-* awk language, POSIX version <2>: Gory Details.
-* awk language, POSIX version <3>: String Functions.
-* awk language, POSIX version <4>: User-modified.
-* awk language, POSIX version <5>: Next Statement.
-* awk language, POSIX version <6>: Continue Statement.
-* awk language, POSIX version <7>: Break Statement.
-* awk language, POSIX version <8>: Precedence.
-* awk language, POSIX version <9>: Assignment Ops.
-* awk language, POSIX version <10>: Arithmetic Ops.
-* awk language, POSIX version <11>: Conversion.
-* awk language, POSIX version <12>: Format Modifiers.
-* awk language, POSIX version <13>: OFMT.
-* awk language, POSIX version <14>: Field Splitting Summary.
-* awk language, POSIX version <15>: Character Lists.
-* awk language, POSIX version <16>: Regexp Operators.
-* awk language, POSIX version: Escape Sequences.
-* awk language, V.4 version <1>: SVR4.
-* awk language, V.4 version: Escape Sequences.
-* awka compiler for awk programs: Other Versions.
-* awka, source code: Other Versions.
+* awk language, POSIX version: Assignment Ops.
+* awk programs <1>: Two Rules.
+* awk programs <2>: Executable Scripts.
+* awk programs: Getting Started.
+* awk programs, complex: When.
+* awk programs, documenting <1>: Library Names.
+* awk programs, documenting: Comments.
+* awk programs, examples of: Sample Programs.
+* awk programs, execution of: Next Statement.
+* awk programs, internationalizing <1>: Programmer i18n.
+* awk programs, internationalizing: I18N Functions.
+* awk programs, lengthy: Long.
+* awk programs, lengthy, assertions: Assert Function.
+* awk programs, location of: Options.
+* awk programs, one-line examples: Very Simple.
+* awk programs, profiling: Profiling.
+* awk programs, profiling, enabling: Options.
+* awk programs, running <1>: Long.
+* awk programs, running: Running gawk.
+* awk programs, running, from shell scripts: One-shot.
+* awk programs, running, without input files: Read Terminal.
+* awk programs, shell variables in: Using Shell Variables.
+* awk, function of: Getting Started.
+* awk, gawk and <1>: This Manual.
+* awk, gawk and: Preface.
+* awk, history of: History.
+* awk, implementation issues, pipes: Redirection.
+* awk, implementations: Other Versions.
+* awk, implementations, limits: Getline Notes.
+* awk, invoking: Command Line.
+* awk, new vs. old: Names.
+* awk, new vs. old, OFMT variable: Conversion.
+* awk, POSIX and: Preface.
+* awk, POSIX and, See Also POSIX awk: Preface.
+* awk, regexp constants and: Typing and Comparison.
+* awk, See Also gawk: Preface.
+* awk, terms describing: This Manual.
+* awk, uses for <1>: When.
+* awk, uses for <2>: Getting Started.
+* awk, uses for: Preface.
+* awk, versions of <1>: V7/SVR3.1.
+* awk, versions of: Names.
+* awk, versions of, changes between SVR3.1 and SVR4: SVR4.
+* awk, versions of, changes between SVR4 and POSIX awk: POSIX.
+* awk, versions of, changes between V7 and SVR3.1: V7/SVR3.1.
+* awk, versions of, See Also Bell Laboratories awk: BTL.
+* awk.h file (internal): Internals.
+* awka compiler for awk: Other Versions.
* AWKNUM internal type: Internals.
+* AWKPATH environment variable <1>: PC Using.
* AWKPATH environment variable: AWKPATH Variable.
-* awkprof.out profiling output file: Profiling.
+* awkprof.out file: Profiling.
* awksed.awk program: Simple Sed.
-* awkvars.out global variable list output file: Options.
-* backslash continuation <1>: Egrep Program.
-* backslash continuation: Statements/Lines.
-* backslash continuation, and comments: Statements/Lines.
-* backslash continuation, in csh <1>: Statements/Lines.
-* backslash continuation, in csh: More Complex.
-* basic function of awk: Getting Started.
-* basic programming concepts: Basic Concepts.
+* awkvars.out file: Options.
+* backslash (\) <1>: Regexp Operators.
+* backslash (\) <2>: Quoting.
+* backslash (\) <3>: Comments.
+* backslash (\): Read Terminal.
+* backslash (\), \" escape sequence: Escape Sequences.
+* backslash (\), \' operator (gawk): GNU Regexp Operators.
+* backslash (\), \/ escape sequence: Escape Sequences.
+* backslash (\), \< operator (gawk): GNU Regexp Operators.
+* backslash (\), \> operator (gawk): GNU Regexp Operators.
+* backslash (\), \` operator (gawk): GNU Regexp Operators.
+* backslash (\), \a escape sequence: Escape Sequences.
+* backslash (\), \b escape sequence: Escape Sequences.
+* backslash (\), \B operator (gawk): GNU Regexp Operators.
+* backslash (\), \f escape sequence: Escape Sequences.
+* backslash (\), \n escape sequence: Escape Sequences.
+* backslash (\), \NNN escape sequence: Escape Sequences.
+* backslash (\), \r escape sequence: Escape Sequences.
+* backslash (\), \t escape sequence: Escape Sequences.
+* backslash (\), \v escape sequence: Escape Sequences.
+* backslash (\), \W operator (gawk): GNU Regexp Operators.
+* backslash (\), \w operator (gawk): GNU Regexp Operators.
+* backslash (\), \x escape sequence: Escape Sequences.
+* backslash (\), \y operator (gawk): GNU Regexp Operators.
+* backslash (\), as field separators: Command Line Field Separator.
+* backslash (\), continuing lines and <1>: Egrep Program.
+* backslash (\), continuing lines and: Statements/Lines.
+* backslash (\), continuing lines and, comments and: Statements/Lines.
+* backslash (\), continuing lines and, in csh <1>: Statements/Lines.
+* backslash (\), continuing lines and, in csh: More Complex.
+* backslash (\), gsub/gensub/sub functions and: Gory Details.
+* backslash (\), in character lists: Character Lists.
+* backslash (\), in escape sequences: Escape Sequences.
+* backslash (\), in escape sequences, POSIX and: Escape Sequences.
+* backslash (\), regexp constants: Computed Regexps.
* BBS-list file: Sample Data Files.
* Beebe, Nelson: Acknowledgments.
-* BEGIN special pattern: BEGIN/END.
+* BEGIN pattern <1>: BEGIN/END.
+* BEGIN pattern <2>: Field Separators.
+* BEGIN pattern: Records.
+* BEGIN pattern, assert user-defined function and: Assert Function.
+* BEGIN pattern, Boolean patterns and: Expression Patterns.
+* BEGIN pattern, exit statement and: Exit Statement.
+* BEGIN pattern, getline and: Getline Notes.
+* BEGIN pattern, headings, adding: Print Examples.
+* BEGIN pattern, next/nextfile statements and <1>: Next Statement.
+* BEGIN pattern, next/nextfile statements and: I/O And BEGIN/END.
+* BEGIN pattern, OFS/ORS variables, assigning values to: Output Separators.
+* BEGIN pattern, operators and: Using BEGIN/END.
+* BEGIN pattern, pgawk program: Profiling.
+* BEGIN pattern, print statement and: I/O And BEGIN/END.
+* BEGIN pattern, pwcat program: Passwd Functions.
+* BEGIN pattern, running awk programs and: Cut Program.
+* BEGIN pattern, TEXTDOMAIN variable and: Programmer i18n.
* beginfile user-defined function: Filetrans Function.
+* Bell Laboratories awk extensions: BTL.
* BeOS: BeOS Installation.
* Berry, Karl: Acknowledgments.
-* binary I/O: User-modified.
-* bindtextdomain built-in function <1>: Programmer i18n.
-* bindtextdomain built-in function: I18N Functions.
-* bindtextdomain C library function: Explaining gettext.
-* bindtextdomain user-defined function: I18N Portability.
+* binary input/output: User-modified.
+* bindtextdomain function (C library): Explaining gettext.
+* bindtextdomain function (gawk) <1>: Programmer i18n.
+* bindtextdomain function (gawk): I18N Functions.
+* bindtextdomain function (gawk), portability and: I18N Portability.
* BINMODE variable <1>: PC Using.
* BINMODE variable: User-modified.
* bits2str user-defined function: Bitwise Functions.
-* bitwise complement: Bitwise Functions.
-* bitwise operations: Bitwise Functions.
-* bitwise shift: Bitwise Functions.
-* blocks, BEGIN and END <1>: Profiling.
-* blocks, BEGIN and END: BEGIN/END.
-* body of a loop: While Statement.
-* book, using this: This Manual.
-* boolean expressions: Boolean Ops.
-* boolean operators: Boolean Ops.
-* bracket expression: Regexp Operators.
-* Brandon, Dick: This Manual.
+* bitwise, complement: Bitwise Functions.
+* bitwise, operations: Bitwise Functions.
+* bitwise, shift: Bitwise Functions.
+* body, in actions: Statements.
+* body, in loops: While Statement.
+* Boolean expressions: Boolean Ops.
+* Boolean expressions, as patterns: Expression Patterns.
+* Boolean operators, See Boolean expressions: Boolean Ops.
+* Bourne shell, quoting rules for: Quoting.
+* braces ({}), actions and: Action Overview.
+* braces ({}), pgawk program: Profiling.
+* braces ({}), statements, grouping: Statements.
+* bracket expressions, See character lists: Regexp Operators.
* break statement: Break Statement.
-* break, outside of loops: Break Statement.
* Brennan, Michael <1>: Other Versions.
* Brennan, Michael <2>: Simple Sed.
* Brennan, Michael <3>: Two-way I/O.
@@ -20710,540 +21033,721 @@ Index
* Brown, Martin <1>: Bugs.
* Brown, Martin <2>: Contributors.
* Brown, Martin: Acknowledgments.
-* BSD portal files: Portal Files.
-* BSD-based operating systems <1>: Glossary.
-* BSD-based operating systems <2>: Portal Files.
-* BSD-based operating systems: Manual History.
-* buffer matching operators: GNU Regexp Operators.
-* buffering output: I/O Functions.
-* buffering, interactive vs. non-interactive: I/O Functions.
-* buffering, non-interactive vs. interactive: I/O Functions.
+* BSD portals: Portal Files.
+* BSD-based operating systems: Glossary.
+* Buening, Andreas <1>: Contributors.
+* Buening, Andreas: Acknowledgments.
+* buffering, input/output <1>: Two-way I/O.
+* buffering, input/output: I/O Functions.
+* buffering, interactive vs. noninteractive: I/O Functions.
* buffers, flushing: I/O Functions.
-* bug reports: Bugs.
+* buffers, operators for: GNU Regexp Operators.
* bug reports, email address, bug-gawk@gnu.org: Bugs.
* bug-gawk@gnu.org bug reporting address: Bugs.
-* bugs, known in gawk: Known Bugs.
-* built-in functions: Built-in.
+* built-in functions: Functions.
+* built-in functions, evaluation order: Calling Built-in.
* built-in variables: Built-in Variables.
-* built-in variables, convey information: Auto-set.
-* built-in variables, user modifiable: User-modified.
+* built-in variables, -v option, setting with: Options.
+* built-in variables, conveying information: Auto-set.
+* built-in variables, user-modifiable: User-modified.
* call by reference: Function Caveats.
* call by value: Function Caveats.
-* calling a function <1>: Function Caveats.
-* calling a function: Function Calls.
-* case conversion: String Functions.
-* case sensitivity: Case-sensitivity.
-* changing contents of a field: Changing Fields.
-* changing the record separator: Records.
-* character class <1>: Character Lists.
-* character class: Regexp Operators.
+* caret (^) <1>: GNU Regexp Operators.
+* caret (^): Regexp Operators.
+* caret (^), ^ operator <1>: Options.
+* caret (^), ^ operator: Precedence.
+* caret (^), ^= operator <1>: Options.
+* caret (^), ^= operator <2>: Precedence.
+* caret (^), ^= operator: Assignment Ops.
+* caret (^), in character lists: Character Lists.
+* case sensitivity, array indices and: Array Intro.
+* case sensitivity, converting case: String Functions.
+* case sensitivity, example programs: Library Functions.
+* case sensitivity, gawk: Case-sensitivity.
+* case sensitivity, regexps and <1>: User-modified.
+* case sensitivity, regexps and: Case-sensitivity.
+* case sensitivity, string comparisons and: User-modified.
* character encodings: Ordinal Functions.
-* character list: Regexp Operators.
-* character list, complemented: Regexp Operators.
-* character set (regexp component): Regexp Operators.
-* character sets (machine character encodings) <1>: Glossary.
-* character sets (machine character encodings): Ordinal Functions.
+* character lists <1>: Character Lists.
+* character lists: Regexp Operators.
+* character lists, character classes: Character Lists.
+* character lists, collating elements: Character Lists.
+* character lists, collating symbols: Character Lists.
+* character lists, complemented: Regexp Operators.
+* character lists, equivalence classes: Character Lists.
+* character lists, non-ASCII: Character Lists.
+* character lists, range expressions: Character Lists.
+* character sets: Ordinal Functions.
+* character sets (machine character encodings): Glossary.
+* character sets, See Also character lists: Regexp Operators.
+* characters, counting: Wc Program.
+* characters, transliterating: Translate Program.
+* characters, values of as numbers: Ordinal Functions.
* Chassell, Robert J.: Acknowledgments.
+* chdir function, implementing in gawk: Sample Library.
* chem utility: Glossary.
* chr user-defined function: Ordinal Functions.
* Cliff random numbers: Cliff Random Function.
* cliff_rand user-defined function: Cliff Random Function.
-* close built-in function <1>: I/O Functions.
-* close built-in function: Close Files And Pipes.
+* close function <1>: I/O Functions.
+* close function <2>: Close Files And Pipes.
+* close function <3>: Getline/Pipe.
+* close function: Getline/Variable/File.
+* close function, return values: Close Files And Pipes.
+* close function, two-way pipes and: Two-way I/O.
* Close, Diane <1>: Contributors.
* Close, Diane: Manual History.
-* close, return value: Close Files And Pipes.
-* closing coprocesses: Close Files And Pipes.
-* closing input files and pipes: Close Files And Pipes.
-* closing output files and pipes: Close Files And Pipes.
-* coding style used in gawk: Adding Code.
* collating elements: Character Lists.
* collating symbols: Character Lists.
-* comma operator, not supported: For Statement.
-* command line: Command Line.
-* command line, setting FS on: Command Line Field Separator.
-* command-line formats: Running gawk.
-* command-line option, --assign: Options.
-* command-line option, --compat: Options.
-* command-line option, --copyleft: Options.
-* command-line option, --copyright: Options.
-* command-line option, --dump-variables: Options.
-* command-line option, --field-separator: Options.
-* command-line option, --file: Options.
-* command-line option, --gen-po <1>: Options.
-* command-line option, --gen-po: String Extraction.
-* command-line option, --help: Options.
-* command-line option, --lint: Options.
-* command-line option, --lint-old: Options.
-* command-line option, --non-decimal-data <1>: Options.
-* command-line option, --non-decimal-data: Non-decimal Data.
-* command-line option, --posix: Options.
-* command-line option, --profile: Options.
-* command-line option, --re-interval: Options.
-* command-line option, --source: Options.
-* command-line option, --traditional: Options.
-* command-line option, --usage: Options.
-* command-line option, --version: Options.
-* command-line option, -f: Options.
-* command-line option, -F <1>: Options.
-* command-line option, -F: Command Line Field Separator.
-* command-line option, -f: Long.
-* command-line option, -mf: Options.
-* command-line option, -mr: Options.
-* command-line option, -v: Options.
-* command-line option, -W: Options.
-* comments: Comments.
-* comments and backslash continuation: Statements/Lines.
-* common mistakes <1>: Options.
-* common mistakes <2>: String Functions.
-* common mistakes <3>: Typing and Comparison.
-* common mistakes <4>: Concatenation.
-* common mistakes <5>: Arithmetic Ops.
-* common mistakes <6>: Special FD.
-* common mistakes <7>: Redirection.
-* common mistakes <8>: Print Examples.
-* common mistakes <9>: Field Separators.
-* common mistakes <10>: Computed Regexps.
-* common mistakes: Escape Sequences.
-* comp.lang.awk Usenet news group: Bugs.
+* columns, aligning: Print Examples.
+* columns, cutting: Cut Program.
+* comma (,), in range patterns: Ranges.
+* command line, arguments <1>: Other Arguments.
+* command line, arguments <2>: ARGC and ARGV.
+* command line, arguments: Auto-set.
+* command line, formats: Running gawk.
+* command line, FS on, setting: Command Line Field Separator.
+* command line, invoking awk from: Command Line.
+* command line, options <1>: Options.
+* command line, options <2>: Command Line Field Separator.
+* command line, options: Long.
+* command line, options, end of: Options.
+* command line, variables, assigning on: Assignment Options.
+* command-line options, processing: Getopt Function.
+* command-line options, string extraction: String Extraction.
+* commenting: Comments.
+* commenting, backslash continuation and: Statements/Lines.
+* comp.lang.awk newsgroup: Bugs.
* comparison expressions: Typing and Comparison.
-* comparisons, string vs. regexp: Typing and Comparison.
-* compatibility mode <1>: POSIX/GNU.
-* compatibility mode: Options.
+* comparison expressions, as patterns: Expression Patterns.
+* comparison expressions, string vs. regexp: Typing and Comparison.
+* compatibility mode (gawk), extensions: POSIX/GNU.
+* compatibility mode (gawk), file names: Special Caveats.
+* compatibility mode (gawk), hexadecimal numbers: Nondecimal-numbers.
+* compatibility mode (gawk), octal numbers: Nondecimal-numbers.
+* compatibility mode (gawk), specifying: Options.
* compiled programs <1>: Glossary.
* compiled programs: Basic High Level.
-* compl built-in function: Bitwise Functions.
+* compl function (gawk): Bitwise Functions.
* complement, bitwise: Bitwise Functions.
-* complemented character list: Regexp Operators.
-* compound statement: Statements.
-* computed regular expressions: Computed Regexps.
-* concatenation: Concatenation.
-* concatenation evaluation order: Concatenation.
-* conditional expression: Conditional Exp.
+* compound statements, control statements and: Statements.
+* concatenating: Concatenation.
+* conditional expressions: Conditional Exp.
* configuration option, --disable-nls: Additional Configuration Options.
-* configuration option, --enable-portals <1>: Additional Configuration Options.
-* configuration option, --enable-portals: Portal Files.
+* configuration option, --enable-portals: Additional Configuration Options.
* configuration option, --with-included-gettext <1>: Additional Configuration Options.
* configuration option, --with-included-gettext: Gawk I18N.
-* configuring gawk: Configuration Philosophy.
+* configuration options, gawk: Additional Configuration Options.
+* constants, nondecimal: Nondecimal Data.
* constants, types of: Constants.
-* continuation of lines: Statements/Lines.
* continue statement: Continue Statement.
-* continue, outside of loops: Continue Statement.
-* contributors to gawk: Contributors.
-* control statement: Statements.
-* conventions, programming <1>: Internal File Ops.
-* conventions, programming <2>: Nextfile Function.
-* conventions, programming <3>: Library Names.
-* conventions, programming <4>: Non-decimal Data.
-* conventions, programming <5>: Return Statement.
-* conventions, programming <6>: Definition Syntax.
-* conventions, programming <7>: Calling Built-in.
-* conventions, programming <8>: Auto-set.
-* conventions, programming: Exit Statement.
-* conversion of case: String Functions.
-* conversion of strings and numbers: Conversion.
-* conversions, during subscripting: Numeric Array Subscripts.
-* converting dates to timestamps: Time Functions.
-* CONVFMT variable <1>: Numeric Array Subscripts.
-* CONVFMT variable <2>: User-modified.
+* control statements: Statements.
+* converting, case: String Functions.
+* converting, dates to timestamps: Time Functions.
+* converting, during subscripting: Numeric Array Subscripts.
+* converting, numbers: Conversion.
+* converting, numbers, to strings: Bitwise Functions.
+* converting, strings to numbers: Conversion.
+* CONVFMT variable <1>: User-modified.
* CONVFMT variable: Conversion.
-* coprocess <1>: Two-way I/O.
-* coprocess <2>: Close Files And Pipes.
-* coprocess <3>: Redirection.
-* coprocess: Getline/Coprocess.
-* cos built-in function: Numeric Functions.
-* csh utility <1>: Options.
-* csh utility <2>: Two-way I/O.
-* csh utility <3>: Statements/Lines.
-* csh utility <4>: More Complex.
-* csh utility: Quoting.
-* csh, backslash continuation <1>: Statements/Lines.
-* csh, backslash continuation: More Complex.
-* curly braces: Action Overview.
-* custom.h configuration file: Configuration Philosophy.
+* CONVFMT variable, array subscripts and: Numeric Array Subscripts.
+* coprocesses <1>: Two-way I/O.
+* coprocesses: Redirection.
+* coprocesses, closing: Close Files And Pipes.
+* coprocesses, getline from: Getline/Coprocess.
+* cos function: Numeric Functions.
+* counting: Wc Program.
+* csh utility: Statements/Lines.
+* csh utility, backslash continuation and: More Complex.
+* csh utility, POSIXLY_CORRECT environment variable: Options.
+* csh utility, |& operator, comparison with: Two-way I/O.
+* ctime user-defined function: Function Example.
+* currency symbols, localization: Explaining gettext.
+* custom.h file: Configuration Philosophy.
* cut utility: Cut Program.
* cut.awk program: Cut Program.
-* d.c., see "dark corner": Conventions.
+* d.c., See dark corner: Conventions.
* dark corner <1>: Glossary.
-* dark corner <2>: Other Arguments.
-* dark corner <3>: Command Line.
-* dark corner <4>: String Functions.
-* dark corner <5>: Uninitialized Subscripts.
-* dark corner <6>: Auto-set.
-* dark corner <7>: Exit Statement.
-* dark corner <8>: Continue Statement.
-* dark corner <9>: Break Statement.
-* dark corner <10>: Truth Values.
-* dark corner <11>: Assignment Ops.
-* dark corner <12>: Conversion.
-* dark corner <13>: Assignment Options.
-* dark corner <14>: Using Constant Regexps.
-* dark corner <15>: Close Files And Pipes.
-* dark corner <16>: Format Modifiers.
-* dark corner <17>: Control Letters.
-* dark corner <18>: OFMT.
-* dark corner <19>: Getline Notes.
-* dark corner <20>: Multiple Line.
-* dark corner <21>: Field Splitting Summary.
-* dark corner <22>: Single Character Fields.
-* dark corner <23>: Changing Fields.
-* dark corner <24>: Records.
-* dark corner <25>: Escape Sequences.
+* dark corner <2>: Truth Values.
+* dark corner <3>: Assignment Ops.
+* dark corner <4>: Format Modifiers.
* dark corner: Conventions.
-* data files, non-readable, skipping: File Checking.
-* data files, readable, checking: File Checking.
-* data-driven languages <1>: Basic High Level.
-* data-driven languages: Getting Started.
+* dark corner, array subscripts: Uninitialized Subscripts.
+* dark corner, break statement: Break Statement.
+* dark corner, close function: Close Files And Pipes.
+* dark corner, command-line arguments: Assignment Options.
+* dark corner, continue statement: Continue Statement.
+* dark corner, CONVFMT variable: Conversion.
+* dark corner, escape sequences: Other Arguments.
+* dark corner, escape sequences, for metacharacters: Escape Sequences.
+* dark corner, exit statement: Exit Statement.
+* dark corner, field separators: Field Splitting Summary.
+* dark corner, FILENAME variable <1>: Auto-set.
+* dark corner, FILENAME variable: Getline Notes.
+* dark corner, FNR/NR variables: Auto-set.
+* dark corner, format-control characters: Control Letters.
+* dark corner, FS as null string: Single Character Fields.
+* dark corner, input files: Records.
+* dark corner, invoking awk: Command Line.
+* dark corner, multiline records: Multiple Line.
+* dark corner, NF variable, decrementing: Changing Fields.
+* dark corner, OFMT variable: OFMT.
+* dark corner, regexp constants: Using Constant Regexps.
+* dark corner, regexp constants, /= operator and: Assignment Ops.
+* dark corner, regexp constants, as arguments to user-defined functions: Using Constant Regexps.
+* dark corner, split function: String Functions.
+* dark corner, strings, storing: Records.
+* data, fixed-width: Constant Size.
+* data-driven languages: Basic High Level.
+* database, group, reading: Group Functions.
+* database, users, reading: Passwd Functions.
+* date utility, GNU: Time Functions.
+* date utility, POSIX: Time Functions.
* dates, converting to timestamps: Time Functions.
+* dates, information related to, localization: Explaining gettext.
* Davies, Stephen <1>: Bugs.
* Davies, Stephen: Contributors.
-* dcgettext built-in function <1>: Programmer i18n.
-* dcgettext built-in function: I18N Functions.
-* dcgettext user-defined function: I18N Portability.
-* deadlock: Two-way I/O.
+* dcgettext function (gawk) <1>: Programmer i18n.
+* dcgettext function (gawk): I18N Functions.
+* dcgettext function (gawk), portability and: I18N Portability.
+* dcngettext function (gawk) <1>: Programmer i18n.
+* dcngettext function (gawk): I18N Functions.
+* dcngettext function (gawk), portability and: I18N Portability.
+* deadlocks: Two-way I/O.
+* debugging gawk: Known Bugs.
+* debugging gawk, bug reports: Bugs.
* decrement operators: Increment Ops.
-* default action: Very Simple.
-* default pattern: Very Simple.
-* defining functions: Definition Syntax.
* Deifik, Scott <1>: Bugs.
* Deifik, Scott <2>: Contributors.
* Deifik, Scott: Acknowledgments.
* delete statement: Delete.
-* deleting elements of arrays: Delete.
+* deleting elements in arrays: Delete.
* deleting entire arrays: Delete.
-* deprecated features: Obsolete.
-* deprecated options: Obsolete.
-* differences between gawk and awk <1>: AWKPATH Variable.
-* differences between gawk and awk <2>: String Functions.
-* differences between gawk and awk <3>: Calling Built-in.
-* differences between gawk and awk <4>: Delete.
-* differences between gawk and awk <5>: ARGC and ARGV.
-* differences between gawk and awk <6>: User-modified.
-* differences between gawk and awk <7>: Nextfile Statement.
-* differences between gawk and awk <8>: I/O And BEGIN/END.
-* differences between gawk and awk <9>: Conditional Exp.
-* differences between gawk and awk <10>: Arithmetic Ops.
-* differences between gawk and awk <11>: Using Constant Regexps.
-* differences between gawk and awk <12>: Scalar Constants.
-* differences between gawk and awk <13>: Close Files And Pipes.
-* differences between gawk and awk <14>: Special FD.
-* differences between gawk and awk <15>: Redirection.
-* differences between gawk and awk <16>: Format Modifiers.
-* differences between gawk and awk <17>: Getline Notes.
-* differences between gawk and awk <18>: Getline/Coprocess.
-* differences between gawk and awk <19>: Getline.
-* differences between gawk and awk <20>: Single Character Fields.
-* differences between gawk and awk <21>: Records.
-* differences between gawk and awk: Case-sensitivity.
-* directory search <1>: VMS Running.
-* directory search <2>: PC Using.
-* directory search <3>: Igawk Program.
-* directory search: AWKPATH Variable.
+* differences in awk and gawk, ARGC/ARGV variables: ARGC and ARGV.
+* differences in awk and gawk, ARGIND variable: Auto-set.
+* differences in awk and gawk, array elements, deleting: Delete.
+* differences in awk and gawk, AWKPATH environment variable: AWKPATH Variable.
+* differences in awk and gawk, BEGIN/END patterns: I/O And BEGIN/END.
+* differences in awk and gawk, BINMODE variable <1>: PC Using.
+* differences in awk and gawk, BINMODE variable: User-modified.
+* differences in awk and gawk, close function: Close Files And Pipes.
+* differences in awk and gawk, ERRNO variable: Auto-set.
+* differences in awk and gawk, error messages: Special FD.
+* differences in awk and gawk, FIELDWIDTHS variable: User-modified.
+* differences in awk and gawk, function arguments (gawk): Calling Built-in.
+* differences in awk and gawk, getline command: Getline.
+* differences in awk and gawk, IGNORECASE variable: User-modified.
+* differences in awk and gawk, implementation limitations <1>: Redirection.
+* differences in awk and gawk, implementation limitations: Getline Notes.
+* differences in awk and gawk, input/output operators <1>: Redirection.
+* differences in awk and gawk, input/output operators: Getline/Coprocess.
+* differences in awk and gawk, line continuations: Conditional Exp.
+* differences in awk and gawk, LINT variable: User-modified.
+* differences in awk and gawk, match function: String Functions.
+* differences in awk and gawk, next/nextfile statements: Nextfile Statement.
+* differences in awk and gawk, print/printf statements: Format Modifiers.
+* differences in awk and gawk, PROCINFO array: Auto-set.
+* differences in awk and gawk, record separators: Records.
+* differences in awk and gawk, regexp constants: Using Constant Regexps.
+* differences in awk and gawk, regular expressions: Case-sensitivity.
+* differences in awk and gawk, RS/RT variables: Records.
+* differences in awk and gawk, RT variable: Auto-set.
+* differences in awk and gawk, single-character fields: Single Character Fields.
+* differences in awk and gawk, split function: String Functions.
+* differences in awk and gawk, strings: Scalar Constants.
+* differences in awk and gawk, strings, storing: Records.
+* differences in awk and gawk, strtonum function (gawk): String Functions.
+* differences in awk and gawk, TEXTDOMAIN variable: User-modified.
+* differences in awk and gawk, trunc-mod operation: Arithmetic Ops.
+* directories, changing: Sample Library.
+* directories, searching <1>: Igawk Program.
+* directories, searching: AWKPATH Variable.
* division: Arithmetic Ops.
-* do-while statement: Do Statement.
+* do-while statement <1>: Do Statement.
+* do-while statement: Regexp Usage.
+* documentation, of awk programs: Library Names.
* documentation, online: Manual History.
-* documenting awk programs <1>: Library Names.
-* documenting awk programs: Comments.
-* double-precision floating-point, definition of: Basic Data Typing.
+* documents, searching: Dupword Program.
+* dollar sign ($): Regexp Operators.
+* dollar sign ($), $ field operator <1>: Precedence.
+* dollar sign ($), $ field operator: Fields.
+* dollar sign ($), incrementing fields and arrays: Increment Ops.
+* double quote (") <1>: Quoting.
+* double quote ("): Read Terminal.
+* double quote ("), regexp constants: Computed Regexps.
+* double-precision floating-point: Basic Data Typing.
* Drepper, Ulrich: Acknowledgments.
* dupnode internal function: Internals.
* dupword.awk program: Dupword Program.
-* dynamic profiling: Profiling.
-* dynamic regular expressions: Computed Regexps.
-* dynamic regular expressions with embedded newlines: Computed Regexps.
* EBCDIC: Ordinal Functions.
* egrep utility <1>: Egrep Program.
* egrep utility: Character Lists.
* egrep.awk program: Egrep Program.
-* element assignment: Assigning Elements.
-* element of array: Reference to Elements.
-* emaill address for bug reports, bug-gawk@gnu.org: Bugs.
-* embedded newlines, in dynamic regexps: Computed Regexps.
+* elements in arrays: Reference to Elements.
+* elements in arrays, assigning: Assigning Elements.
+* elements in arrays, deleting: Delete.
+* elements in arrays, order of: Scanning an Array.
+* elements in arrays, scanning: Scanning an Array.
+* email address for bug reports, bug-gawk@gnu.org: Bugs.
* EMISTERED: TCP/IP Networking.
-* empty action: Very Simple.
* empty pattern: Empty.
-* empty program: Command Line.
-* empty string <1>: Truth Values.
-* empty string <2>: Conversion.
-* empty string <3>: Regexp Field Splitting.
-* empty string: Records.
-* empty string, definition of: Basic Data Typing.
-* END special pattern: BEGIN/END.
+* empty strings, See null strings: Regexp Field Splitting.
+* END pattern: BEGIN/END.
+* END pattern, assert user-defined function and: Assert Function.
+* END pattern, backslash continuation and: Egrep Program.
+* END pattern, Boolean patterns and: Expression Patterns.
+* END pattern, exit statement and: Exit Statement.
+* END pattern, next/nextfile statements and <1>: Next Statement.
+* END pattern, next/nextfile statements and: I/O And BEGIN/END.
+* END pattern, operators and: Using BEGIN/END.
+* END pattern, pgawk program: Profiling.
+* END pattern, print statement and: I/O And BEGIN/END.
* endfile user-defined function: Filetrans Function.
+* endgrent function (C library): Group Functions.
* endgrent user-defined function: Group Functions.
+* endpwent function (C library): Passwd Functions.
* endpwent user-defined function: Passwd Functions.
* ENVIRON variable: Auto-set.
-* environment variable, AWKPATH: AWKPATH Variable.
-* environment variable, POSIXLY_CORRECT: Options.
+* environment variables: Auto-set.
* epoch, definition of: Glossary.
-* equivalence classes: Character Lists.
-* ERRNO variable <1>: Auto-set.
+* equals sign (=), = operator: Assignment Ops.
+* equals sign (=), == operator <1>: Precedence.
+* equals sign (=), == operator: Typing and Comparison.
+* EREs (Extended Regular Expressions): Character Lists.
+* ERRNO variable <1>: Internals.
+* ERRNO variable <2>: Auto-set.
* ERRNO variable: Getline.
-* errors, common <1>: Options.
-* errors, common <2>: String Functions.
-* errors, common <3>: Typing and Comparison.
-* errors, common <4>: Concatenation.
-* errors, common <5>: Arithmetic Ops.
-* errors, common <6>: Special FD.
-* errors, common <7>: Redirection.
-* errors, common <8>: Print Examples.
-* errors, common <9>: Field Separators.
-* errors, common <10>: Computed Regexps.
-* errors, common: Escape Sequences.
-* escape processing, sub et. al.: Gory Details.
-* escape sequence notation: Escape Sequences.
-* evaluation, order of <1>: Calling Built-in.
-* evaluation, order of <2>: Increment Ops.
-* evaluation, order of: Concatenation.
+* error handling: Special FD.
+* error handling, ERRNO variable and: Auto-set.
+* error output: Special FD.
+* escape processing, gsub/gensub/sub functions: Gory Details.
+* escape sequences: Escape Sequences.
+* escape sequences, unrecognized: Options.
+* evaluation order: Increment Ops.
+* evaluation order, concatenation: Concatenation.
+* evaluation order, functions: Calling Built-in.
* examining fields: Fields.
-* executable scripts: Executable Scripts.
+* exclamation point (!), ! operator <1>: Egrep Program.
+* exclamation point (!), ! operator <2>: Precedence.
+* exclamation point (!), ! operator: Boolean Ops.
+* exclamation point (!), != operator <1>: Precedence.
+* exclamation point (!), != operator: Typing and Comparison.
+* exclamation point (!), !~ operator <1>: Expression Patterns.
+* exclamation point (!), !~ operator <2>: Precedence.
+* exclamation point (!), !~ operator <3>: Typing and Comparison.
+* exclamation point (!), !~ operator <4>: Regexp Constants.
+* exclamation point (!), !~ operator <5>: Computed Regexps.
+* exclamation point (!), !~ operator <6>: Case-sensitivity.
+* exclamation point (!), !~ operator: Regexp Usage.
* exit statement: Exit Statement.
-* exp built-in function: Numeric Functions.
+* exp function: Numeric Functions.
* expand utility: Very Simple.
-* explicit input: Getline.
-* exponentiation: Arithmetic Ops.
-* expression: Expressions.
-* expression, assignment: Assignment Ops.
-* expression, boolean: Boolean Ops.
-* expression, comparison: Typing and Comparison.
-* expression, conditional: Conditional Exp.
-* expression, matching: Typing and Comparison.
-* extension built-in function: Using Internal File Ops.
+* expressions: Expressions.
+* expressions, as patterns: Expression Patterns.
+* expressions, assignment: Assignment Ops.
+* expressions, Boolean: Boolean Ops.
+* expressions, comparison: Typing and Comparison.
+* expressions, conditional: Conditional Exp.
+* expressions, matching, See comparison expressions: Typing and Comparison.
+* expressions, selecting: Conditional Exp.
+* Extended Regular Expressions (EREs): Character Lists.
+* extension function (gawk): Using Internal File Ops.
* extensions, Bell Laboratories awk: BTL.
+* extensions, in gawk, not in POSIX awk: POSIX/GNU.
* extensions, mawk: Other Versions.
* extract.awk program: Extract Program.
* extraction, of marked strings (internationalization): String Extraction.
-* fatal errors <1>: File Checking.
-* fatal errors <2>: Options.
-* fatal errors <3>: I/O Functions.
-* fatal errors <4>: String Functions.
-* fatal errors <5>: Calling Built-in.
-* fatal errors <6>: Format Modifiers.
-* fatal errors: Constant Size.
-* FDL: GNU Free Documentation License.
+* false, logical: Truth Values.
+* FDL (Free Documentation License): GNU Free Documentation License.
* features, adding to gawk: Adding Code.
-* features, advanced: Advanced Features.
+* features, advanced, See advanced features: Obsolete.
+* features, deprecated: Obsolete.
* features, undocumented: Undocumented.
* Fenlason, Jay <1>: Contributors.
* Fenlason, Jay: History.
-* fflush built-in function: I/O Functions.
+* fflush function: I/O Functions.
+* fflush function, unsupported: Options.
+* field numbers: Nonconstant Fields.
* field operator $: Fields.
-* field separator, choice of: Field Separators.
-* field separator, FS: Field Separators.
-* field separator, on command line: Command Line Field Separator.
-* fields: Fields.
+* field operators, dollar sign as: Fields.
+* field separators <1>: User-modified.
+* field separators: Field Separators.
+* field separators, choice of: Field Separators.
+* field separators, FIELDWIDTHS variable and: User-modified.
+* field separators, in multiline records: Multiple Line.
+* field separators, on command line: Command Line Field Separator.
+* field separators, POSIX and <1>: Field Splitting Summary.
+* field separators, POSIX and: Fields.
+* field separators, regular expressions as <1>: Regexp Field Splitting.
+* field separators, regular expressions as: Field Separators.
+* field separators, See Also OFS: Changing Fields.
+* field separators, spaces as: Cut Program.
+* fields <1>: Basic High Level.
+* fields <2>: Fields.
+* fields: Reading Files.
+* fields, adding: Changing Fields.
* fields, changing contents of: Changing Fields.
-* fields, definition of: Basic High Level.
+* fields, cutting: Cut Program.
+* fields, examining: Fields.
+* fields, number of: Fields.
+* fields, numbers: Nonconstant Fields.
+* fields, printing: Print Examples.
* fields, separating: Field Separators.
-* FIELDWIDTHS variable: User-modified.
+* fields, single-character: Single Character Fields.
+* FIELDWIDTHS variable <1>: User-modified.
+* FIELDWIDTHS variable: Constant Size.
* file descriptors: Special FD.
-* file, awk program: Long.
+* file names, distinguishing: Auto-set.
+* file names, in compatibility mode: Special Caveats.
+* file names, standard streams in gawk: Special FD.
* FILENAME variable <1>: Auto-set.
-* FILENAME variable <2>: Getline Notes.
* FILENAME variable: Reading Files.
-* FILENAME, being set by getline: Getline Notes.
+* FILENAME variable, getline, setting with: Getline Notes.
+* filenames, assignments as: Ignoring Assigns.
+* files, .mo: Explaining gettext.
+* files, .mo, converting from .po: I18N Example.
+* files, .mo, specifying directory of <1>: Programmer i18n.
+* files, .mo, specifying directory of: Explaining gettext.
+* files, .po <1>: Translator i18n.
+* files, .po: Explaining gettext.
+* files, .po, converting to .mo: I18N Example.
+* files, /dev/... special files: Special FD.
+* files, /inet/ (gawk): TCP/IP Networking.
+* files, /p (gawk): Portal Files.
+* files, as single records: Records.
+* files, awk programs in: Long.
+* files, awkprof.out: Profiling.
+* files, awkvars.out: Options.
+* files, closing: I/O Functions.
+* files, descriptors, See file descriptors: Special FD.
+* files, for process information: Special Process.
+* files, group: Group Functions.
+* files, information about, retrieving: Sample Library.
+* files, initialization and cleanup: Filetrans Function.
+* files, input, See input files: Read Terminal.
+* files, log, timestamps in: Time Functions.
+* files, managing: Data File Management.
+* files, managing, data file boundaries: Filetrans Function.
+* files, message object: Explaining gettext.
+* files, message object, converting from portable object files: I18N Example.
+* files, message object, specifying directory of <1>: Programmer i18n.
+* files, message object, specifying directory of: Explaining gettext.
+* files, multiple passes over: Other Arguments.
+* files, multiple, duplicating output into: Tee Program.
+* files, output, See output files: Close Files And Pipes.
+* files, password: Passwd Functions.
+* files, portable object <1>: Translator i18n.
+* files, portable object: Explaining gettext.
+* files, portable object, converting to message object files: I18N Example.
+* files, portable object, generating: Options.
+* files, portal: Portal Files.
+* files, processing, ARGIND variable and: Auto-set.
+* files, reading: Rewind Function.
+* files, reading, multiline records: Multiple Line.
+* files, searching for regular expressions: Egrep Program.
+* files, skipping: File Checking.
+* files, source, search path for: Igawk Program.
+* files, splitting: Split Program.
+* files, Texinfo, extracting programs from: Extract Program.
* Fish, Fred <1>: Bugs.
* Fish, Fred: Contributors.
+* fixed-width data: Constant Size.
* flag variables <1>: Tee Program.
-* flag variables <2>: Ranges.
* flag variables: Boolean Ops.
-* floating-point, definition of: Basic Data Typing.
-* floating-point, positive and negative values for zero: Floating Point Issues.
-* floating-point, precision issues: Floating Point Issues.
-* flushing buffers: I/O Functions.
+* floating-point: Floating Point Issues.
+* floating-point, numbers: Basic Data Typing.
+* floating-point, numbers, AWKNUM internal type: Internals.
* FNR variable <1>: Auto-set.
* FNR variable: Records.
-* for (x in ...) statement: Scanning an Array.
+* FNR variable, changing: Auto-set.
* for statement: For Statement.
+* for statement, in arrays: Scanning an Array.
* force_number internal function: Internals.
* force_string internal function: Internals.
-* format specifier, printf: Control Letters.
-* format specifier, strftime: Time Functions.
-* format specifiers, mixing regular with positional specifiers (printf): Printf Ordering.
-* format string: Basic Printf.
-* format, numeric output: OFMT.
-* formatted output: Printf.
-* formatted timestamps: Gettimeofday Function.
-* Free Documentation License: GNU Free Documentation License.
-* Free Software Foundation <1>: Glossary.
-* Free Software Foundation <2>: Getting.
-* Free Software Foundation: Manual History.
+* format specifiers, mixing regular with positional specifiers: Printf Ordering.
+* format specifiers, printf statement: Control Letters.
+* format specifiers, strftime function (gawk): Time Functions.
+* format strings: Basic Printf.
+* formats, numeric output: OFMT.
+* formatting output: Printf.
+* forward slash (/): Regexp.
+* forward slash (/), / operator: Precedence.
+* forward slash (/), /= operator <1>: Precedence.
+* forward slash (/), /= operator: Assignment Ops.
+* forward slash (/), /= operator, vs. /=.../ regexp constant: Assignment Ops.
+* forward slash (/), patterns and: Expression Patterns.
+* Free Documentation License (FDL): GNU Free Documentation License.
+* Free Software Foundation (FSF) <1>: Glossary.
+* Free Software Foundation (FSF) <2>: Getting.
+* Free Software Foundation (FSF): Manual History.
* free_temp internal macro: Internals.
-* FreeBSD <1>: Glossary.
-* FreeBSD: Manual History.
+* FreeBSD: Glossary.
* FS variable <1>: User-modified.
* FS variable: Field Separators.
-* FSF <1>: Glossary.
-* FSF <2>: Getting.
-* FSF: Manual History.
-* ftp, anonymous: Getting.
-* function call <1>: Function Caveats.
-* function call: Function Calls.
-* function definition: Definition Syntax.
-* function, recursive: Definition Syntax.
-* function, user-defined: User-defined.
+* FS variable, --field-separator option and: Options.
+* FS variable, as null string: Single Character Fields.
+* FS variable, as TAB character: Options.
+* FS variable, changing value of <1>: Known Bugs.
+* FS variable, changing value of: Field Separators.
+* FS variable, running awk programs and: Cut Program.
+* FS variable, setting from command line: Command Line Field Separator.
+* FSF (Free Software Foundation) <1>: Glossary.
+* FSF (Free Software Foundation) <2>: Getting.
+* FSF (Free Software Foundation): Manual History.
+* function calls: Function Calls.
+* functions, arrays as parameters to: Function Caveats.
+* functions, built-in <1>: Functions.
+* functions, built-in: Function Calls.
+* functions, built-in, adding to gawk: Dynamic Extensions.
+* functions, built-in, evaluation order: Calling Built-in.
+* functions, defining: Definition Syntax.
+* functions, library: Library Functions.
+* functions, library, assertions: Assert Function.
+* functions, library, associative arrays and: Library Names.
+* functions, library, C library: Getopt Function.
+* functions, library, character values as numbers: Ordinal Functions.
+* functions, library, Cliff random numbers: Cliff Random Function.
+* functions, library, command-line options: Getopt Function.
+* functions, library, example program for using: Igawk Program.
+* functions, library, group database, reading: Group Functions.
+* functions, library, managing data files: Data File Management.
+* functions, library, managing time: Gettimeofday Function.
+* functions, library, merging arrays into strings: Join Function.
+* functions, library, nextfile statement: Nextfile Function.
+* functions, library, rounding numbers: Round Function.
+* functions, library, user database, reading: Passwd Functions.
+* functions, names of <1>: Definition Syntax.
+* functions, names of: Arrays.
+* functions, recursive: Definition Syntax.
+* functions, return values, setting: Internals.
+* functions, string-translation: I18N Functions.
* functions, undefined: Function Caveats.
+* functions, user-defined: User-defined.
+* functions, user-defined, calling: Function Caveats.
+* functions, user-defined, counts: Profiling.
+* functions, user-defined, library of: Library Functions.
+* functions, user-defined, next/nextfile statements and <1>: Nextfile Statement.
+* functions, user-defined, next/nextfile statements and: Next Statement.
* G-d: Acknowledgments.
* Garfinkle, Scott: Contributors.
-* gawk, coding style: Adding Code.
-* gawk, source code: Getting.
-* General Public License <1>: Glossary.
-* General Public License <2>: New Ports.
-* General Public License <3>: Other Versions.
-* General Public License: Manual History.
-* gensub built-in function: String Functions.
-* gensub, escape processing: Gory Details.
+* gawk, awk and <1>: This Manual.
+* gawk, awk and: Preface.
+* gawk, bitwise operations in: Bitwise Functions.
+* gawk, break statement in: Break Statement.
+* gawk, built-in variables and: Built-in Variables.
+* gawk, character classes and: Character Lists.
+* gawk, coding style in: Adding Code.
+* gawk, command-line options: GNU Regexp Operators.
+* gawk, comparison operators and: Typing and Comparison.
+* gawk, configuring: Configuration Philosophy.
+* gawk, configuring, options: Additional Configuration Options.
+* gawk, continue statement in: Continue Statement.
+* gawk, debugging: Known Bugs.
+* gawk, distribution: Distribution contents.
+* gawk, escape sequences: Escape Sequences.
+* gawk, extensions, disabling: Options.
+* gawk, features, adding: Adding Code.
+* gawk, features, advanced: Advanced Features.
+* gawk, fflush function in: I/O Functions.
+* gawk, field separators and: User-modified.
+* gawk, FIELDWIDTHS variable in: User-modified.
+* gawk, file names in: Special Files.
+* gawk, format-control characters: Control Letters.
+* gawk, function arguments and: Calling Built-in.
+* gawk, functions, adding: Dynamic Extensions.
+* gawk, hexadecimal numbers and: Nondecimal-numbers.
+* gawk, IGNORECASE variable in: User-modified.
+* gawk, implementation issues: Notes.
+* gawk, implementation issues, debugging: Compatibility Mode.
+* gawk, implementation issues, downward compatibility: Compatibility Mode.
+* gawk, implementation issues, limits: Getline Notes.
+* gawk, implementation issues, pipes: Redirection.
+* gawk, installing: Installation.
+* gawk, internals: Internals.
+* gawk, internationalization and, See internationalization: Internationalization.
+* gawk, interpreter, adding code to <1>: Future Extensions.
+* gawk, interpreter, adding code to: Using Internal File Ops.
+* gawk, interval expressions and: Regexp Operators.
+* gawk, line continuation in: Conditional Exp.
+* gawk, LINT variable in: User-modified.
+* gawk, list of contributors to: Contributors.
+* gawk, MS-DOS version of: PC Using.
+* gawk, newlines in: Statements/Lines.
+* gawk, next file statement in: Nextfile Statement.
+* gawk, nextfile statement in <1>: Nextfile Function.
+* gawk, nextfile statement in: Nextfile Statement.
+* gawk, octal numbers and: Nondecimal-numbers.
+* gawk, OS/2 version of: PC Using.
+* gawk, regexp constants and: Using Constant Regexps.
+* gawk, regular expressions, case sensitivity: Case-sensitivity.
+* gawk, regular expressions, operators: GNU Regexp Operators.
+* gawk, regular expressions, precedence: Regexp Operators.
+* gawk, See Also awk: Preface.
+* gawk, source code, obtaining: Getting.
+* gawk, splitting fields and: Constant Size.
+* gawk, string-translation functions: I18N Functions.
+* gawk, timestamps: Time Functions.
+* gawk, uses for: Preface.
+* gawk, versions of, information about, printing: Options.
+* gawk, word-boundary operator: GNU Regexp Operators.
+* General Public License (GPL): Glossary.
+* General Public License, See GPL: Manual History.
+* gensub function (gawk) <1>: String Functions.
+* gensub function (gawk): Using Constant Regexps.
+* gensub function (gawk), escape processing: Gory Details.
* get_argument internal function: Internals.
-* getgrent C library function: Group Functions.
+* getgrent function (C library): Group Functions.
* getgrent user-defined function: Group Functions.
+* getgrgid function (C library): Group Functions.
* getgrgid user-defined function: Group Functions.
+* getgrnam function (C library): Group Functions.
* getgrnam user-defined function: Group Functions.
-* getgruser user-defined function: Group Functions.
-* getline built-in function: Getline.
-* getline, return values: Getline.
-* getline, setting FILENAME: Getline Notes.
-* getopt C library function: Getopt Function.
+* getgruser function (C library): Group Functions.
+* getgruser function, user-defined: Group Functions.
+* getline command: Reading Files.
+* getline command, _gr_init user-defined function: Group Functions.
+* getline command, _pw_init function: Passwd Functions.
+* getline command, coprocesses, using from <1>: Close Files And Pipes.
+* getline command, coprocesses, using from: Getline/Coprocess.
+* getline command, deadlock and: Two-way I/O.
+* getline command, explicit input with: Getline.
+* getline command, FILENAME variable and: Getline Notes.
+* getline command, return values: Getline.
+* getline command, variants: Getline Summary.
+* getopt function (C library): Getopt Function.
* getopt user-defined function: Getopt Function.
-* getpwent C library function: Passwd Functions.
+* getpwent function (C library): Passwd Functions.
* getpwent user-defined function: Passwd Functions.
+* getpwnam function (C library): Passwd Functions.
* getpwnam user-defined function: Passwd Functions.
+* getpwuid function (C library): Passwd Functions.
* getpwuid user-defined function: Passwd Functions.
-* getservbyname C library function: TCP/IP Networking.
-* gettext C library function: Explaining gettext.
-* gettext, how it works: Explaining gettext.
+* getservbyname function (C library): TCP/IP Networking.
+* gettext function (C library): Explaining gettext.
+* gettext library: Explaining gettext.
+* gettext library, locale categories: Explaining gettext.
* gettimeofday user-defined function: Gettimeofday Function.
-* getting gawk: Getting.
* GNITS mailing list: Acknowledgments.
+* GNU awk, See gawk: Preface.
* GNU Free Documentation License: GNU Free Documentation License.
-* GNU General Public License <1>: Glossary.
-* GNU General Public License <2>: New Ports.
-* GNU General Public License <3>: Other Versions.
-* GNU General Public License: Manual History.
-* GNU Lesser General Public License <1>: Glossary.
-* GNU Lesser General Public License: Other Versions.
+* GNU General Public License: Glossary.
+* GNU Lesser General Public License: Glossary.
+* GNU long options <1>: Options.
+* GNU long options: Command Line.
+* GNU long options, printing list of: Options.
* GNU Project <1>: Glossary.
* GNU Project: Manual History.
* GNU/Linux <1>: Glossary.
-* GNU/Linux <2>: Using Internal File Ops.
-* GNU/Linux <3>: Internal File Ops.
-* GNU/Linux <4>: Dynamic Extensions.
-* GNU/Linux <5>: Atari Compiling.
-* GNU/Linux <6>: Additional Configuration Options.
-* GNU/Linux <7>: Installation.
-* GNU/Linux <8>: I18N Example.
+* GNU/Linux <2>: Atari Compiling.
+* GNU/Linux <3>: Additional Configuration Options.
+* GNU/Linux <4>: I18N Example.
* GNU/Linux: Manual History.
-* GPL <1>: Glossary.
-* GPL <2>: New Ports.
-* GPL <3>: Other Versions.
-* GPL: Manual History.
+* GPL (General Public License) <1>: Glossary.
+* GPL (General Public License): Manual History.
+* GPL (General Public License), printing: Options.
* grcat program: Group Functions.
* Grigera, Juan <1>: Bugs.
* Grigera, Juan: Contributors.
+* group database, reading: Group Functions.
* group file: Group Functions.
-* group information: Group Functions.
-* gsub built-in function: String Functions.
-* gsub, escape processing: Gory Details.
-* gsub, third argument of: String Functions.
+* groups, information about: Group Functions.
+* gsub function <1>: String Functions.
+* gsub function: Using Constant Regexps.
+* gsub function, arguments of: String Functions.
+* gsub function, escape processing: Gory Details.
* Hankerson, Darrel <1>: Bugs.
* Hankerson, Darrel <2>: Contributors.
* Hankerson, Darrel: Acknowledgments.
* Hartholz, Elaine: Acknowledgments.
* Hartholz, Marshall: Acknowledgments.
-* hexadecimal numbers: Non-decimal-numbers.
-* historical features <1>: String Functions.
-* historical features <2>: Continue Statement.
-* historical features <3>: Break Statement.
-* historical features: Command Line Field Separator.
-* history of awk: History.
+* Hasegawa, Isamu <1>: Contributors.
+* Hasegawa, Isamu: Acknowledgments.
+* hexadecimal numbers: Nondecimal-numbers.
+* hexadecimal, values, enabling interpretation of: Options.
* histsort.awk program: History Sorting.
-* how awk works: Two Rules.
* Hughes, Phil: Acknowledgments.
* HUP signal: Profiling.
-* I/O, binary: User-modified.
-* I/O, from BEGIN and END: I/O And BEGIN/END.
-* I/O, two-way: Two-way I/O.
+* hyphen (-), - operator: Precedence.
+* hyphen (-), -- (decrement/increment) operators: Precedence.
+* hyphen (-), -- operator: Increment Ops.
+* hyphen (-), -= operator <1>: Precedence.
+* hyphen (-), -= operator: Assignment Ops.
+* hyphen (-), filenames beginning with: Options.
+* hyphen (-), in character lists: Character Lists.
* id utility: Id Program.
* id.awk program: Id Program.
-* if-else statement: If Statement.
+* if statement <1>: If Statement.
+* if statement: Regexp Usage.
+* if statement, actions, changing: Ranges.
* igawk.sh program: Igawk Program.
-* IGNORECASE variable <1>: Array Sorting.
-* IGNORECASE variable <2>: Array Intro.
-* IGNORECASE variable <3>: User-modified.
+* IGNORECASE variable <1>: User-modified.
* IGNORECASE variable: Case-sensitivity.
-* IGNORECASE, and array sorting: Array Sorting.
-* IGNORECASE, and array subscripts: Array Intro.
-* ignoring case: Case-sensitivity.
-* implementation limits <1>: Redirection.
-* implementation limits: Getline Notes.
+* IGNORECASE variable, array sorting and: Array Sorting.
+* IGNORECASE variable, array subscripts and: Array Intro.
+* IGNORECASE variable, in example programs: Library Functions.
+* implementation issues, gawk: Notes.
+* implementation issues, gawk, debugging: Compatibility Mode.
+* implementation issues, gawk, limits <1>: Redirection.
+* implementation issues, gawk, limits: Getline Notes.
* in operator <1>: Id Program.
-* in operator <2>: Scanning an Array.
-* in operator <3>: For Statement.
-* in operator <4>: Precedence.
+* in operator <2>: For Statement.
+* in operator <3>: Precedence.
* in operator: Typing and Comparison.
+* in operator, arrays and <1>: Scanning an Array.
+* in operator, arrays and: Reference to Elements.
* increment operators: Increment Ops.
-* index built-in function: String Functions.
+* index function: String Functions.
+* indexing arrays: Array Intro.
* initialization, automatic: More Complex.
-* input: Reading Files.
-* input file, sample: Sample Data Files.
+* input files: Reading Files.
+* input files, closing: Close Files And Pipes.
+* input files, counting elements in: Wc Program.
+* input files, examples: Sample Data Files.
+* input files, reading: Reading Files.
+* input files, running awk without: Read Terminal.
* input files, skipping: Nextfile Function.
+* input files, variable assignments and: Other Arguments.
* input pipeline: Getline/Pipe.
* input redirection: Getline/File.
+* input, data, nondecimal: Nondecimal Data.
* input, explicit: Getline.
-* input, getline command: Getline.
-* input, multiple line records: Multiple Line.
+* input, files, See input files: Multiple Line.
+* input, multiline records: Multiple Line.
+* input, splitting into records: Records.
+* input, standard <1>: Special FD.
* input, standard: Read Terminal.
+* input/output, binary: User-modified.
+* input/output, from BEGIN and END: I/O And BEGIN/END.
+* input/output, two-way: Two-way I/O.
* insomnia, cure for: Alarm Program.
* installation, amiga: Amiga Installation.
* installation, atari: Atari Installation.
* installation, beos: BeOS Installation.
-* installation, pc operating systems: PC Installation.
* installation, tandem: Tandem Installation.
-* installation, unix: Quick Installation.
* installation, vms: VMS Installation.
-* int built-in function: Numeric Functions.
-* integer, definition of: Basic Data Typing.
-* integer, unsigned: Basic Data Typing.
-* interaction, awk and other programs: I/O Functions.
-* interactive buffering vs. non-interactive: I/O Functions.
-* internal function, assoc_clear: Internals.
-* internal function, assoc_lookup: Internals.
-* internal function, dupnode: Internals.
-* internal function, force_number: Internals.
-* internal function, force_string: Internals.
-* internal function, get_argument: Internals.
-* internal function, make_builtin: Internals.
-* internal function, make_number: Internals.
-* internal function, make_string: Internals.
-* internal function, set_value: Internals.
-* internal function, tmp_number: Internals.
-* internal function, tmp_string: Internals.
-* internal function, update_ERRNO: Internals.
-* internal macro, free_temp: Internals.
-* internal type, AWKNUM: Internals.
-* internal type, NODE: Internals.
-* internal variable, param_cnt: Internals.
-* internal variable, stlen: Internals.
-* internal variable, stptr: Internals.
-* internal variable, type: Internals.
-* internal variable, vname: Internals.
+* installing gawk: Installation.
+* int function: Numeric Functions.
+* INT signal (MS-DOS): Profiling.
+* integers: Basic Data Typing.
+* integers, unsigned: Basic Data Typing.
+* interacting with other programs: I/O Functions.
* internationalization <1>: I18N and L10N.
-* internationalization: User-modified.
-* internationalization features in gawk: Internationalization.
-* internationalization of awk programs, portability issues: I18N Portability.
-* internationalization, marked strings: Programmer i18n.
+* internationalization: I18N Functions.
+* internationalization, localization <1>: Internationalization.
+* internationalization, localization: User-modified.
+* internationalization, localization, character classes: Character Lists.
+* internationalization, localization, gawk and: Internationalization.
+* internationalization, localization, locale categories: Explaining gettext.
+* internationalization, localization, marked strings: Programmer i18n.
+* internationalization, localization, portability and: I18N Portability.
* internationalizing a program: Explaining gettext.
* interpreted programs <1>: Glossary.
* interpreted programs: Basic High Level.
* interval expressions: Regexp Operators.
* inventory-shipped file: Sample Data Files.
-* invocation of gawk: Command Line.
* ISO: Glossary.
-* ISO 8601: Time Functions.
-* ISO 8859-1 <1>: Glossary.
-* ISO 8859-1: Case-sensitivity.
-* ISO Latin-1 <1>: Glossary.
-* ISO Latin-1: Case-sensitivity.
+* ISO 8859-1: Glossary.
+* ISO Latin-1: Glossary.
* Jacobs, Andrew: Passwd Functions.
* Jaegermann, Michal <1>: Contributors.
* Jaegermann, Michal: Acknowledgments.
@@ -21260,371 +21764,505 @@ Index
* Kernighan, Brian <6>: Acknowledgments.
* Kernighan, Brian <7>: Conventions.
* Kernighan, Brian: History.
-* kill command: Profiling.
+* kill command, dynamic profiling: Profiling.
* Knights, jedi: Undocumented.
-* known bugs: Known Bugs.
* Kwok, Conrad: Contributors.
* labels.awk program: Labels Program.
-* language, awk: This Manual.
-* language, data-driven <1>: Basic High Level.
-* language, data-driven: Getting Started.
-* language, procedural: Getting Started.
+* languages, data-driven: Basic High Level.
* LC_ALL locale category: Explaining gettext.
* LC_COLLATE locale category: Explaining gettext.
* LC_CTYPE locale category: Explaining gettext.
* LC_MESSAGES locale category: Explaining gettext.
+* LC_MESSAGES locale category, bindtextdomain function (gawk): Programmer i18n.
* LC_MONETARY locale category: Explaining gettext.
* LC_NUMERIC locale category: Explaining gettext.
* LC_RESPONSE locale category: Explaining gettext.
* LC_TIME locale category: Explaining gettext.
+* left angle bracket (<), < operator <1>: Precedence.
+* left angle bracket (<), < operator: Typing and Comparison.
+* left angle bracket (<), < operator (I/O): Getline/File.
+* left angle bracket (<), <= operator <1>: Precedence.
+* left angle bracket (<), <= operator: Typing and Comparison.
* left shift, bitwise: Bitwise Functions.
-* leftmost longest match <1>: Multiple Line.
-* leftmost longest match: Leftmost Longest.
-* length built-in function: String Functions.
-* Lesser General Public License <1>: Glossary.
-* Lesser General Public License: Other Versions.
-* LGPL <1>: Glossary.
-* LGPL: Other Versions.
-* limitations <1>: Redirection.
-* limitations: Getline Notes.
-* line break: Statements/Lines.
-* line continuation <1>: Conditional Exp.
-* line continuation <2>: Boolean Ops.
-* line continuation <3>: Print Examples.
-* line continuation: Statements/Lines.
-* lint checks <1>: Options.
-* lint checks <2>: Command Line.
-* lint checks <3>: Function Caveats.
-* lint checks <4>: Uninitialized Subscripts.
-* lint checks <5>: Delete.
-* lint checks <6>: User-modified.
-* lint checks: Format Modifiers.
+* leftmost longest match: Multiple Line.
+* length function: String Functions.
+* Lesser General Public License (LGPL): Glossary.
+* LGPL (Lesser General Public License): Glossary.
+* libraries of awk functions: Library Functions.
+* libraries of awk functions, assertions: Assert Function.
+* libraries of awk functions, associative arrays and: Library Names.
+* libraries of awk functions, character values as numbers: Ordinal Functions.
+* libraries of awk functions, command-line options: Getopt Function.
+* libraries of awk functions, example program for using: Igawk Program.
+* libraries of awk functions, group database, reading: Group Functions.
+* libraries of awk functions, managing, data files: Data File Management.
+* libraries of awk functions, managing, time: Gettimeofday Function.
+* libraries of awk functions, merging arrays into strings: Join Function.
+* libraries of awk functions, nextfile statement: Nextfile Function.
+* libraries of awk functions, rounding numbers: Round Function.
+* libraries of awk functions, user database, reading: Passwd Functions.
+* line breaks: Statements/Lines.
+* line continuations: Boolean Ops.
+* line continuations, gawk: Conditional Exp.
+* line continuations, in print statement: Print Examples.
+* line continuations, with C shell: More Complex.
+* lines, blank, printing: Print.
+* lines, counting: Wc Program.
+* lines, duplicate, removing: History Sorting.
+* lines, matching ranges of: Ranges.
+* lines, skipping between markers: Ranges.
+* lint checking: User-modified.
+* lint checking, array elements: Delete.
+* lint checking, array subscripts: Uninitialized Subscripts.
+* lint checking, empty programs: Command Line.
+* lint checking, issuing warnings: Options.
+* lint checking, POSIXLY_CORRECT environment variable: Options.
+* lint checking, undefined functions: Function Caveats.
* LINT variable: User-modified.
* Linux <1>: Glossary.
-* Linux <2>: Using Internal File Ops.
-* Linux <3>: Internal File Ops.
-* Linux <4>: Dynamic Extensions.
-* Linux <5>: Atari Compiling.
-* Linux <6>: Additional Configuration Options.
-* Linux <7>: Installation.
-* Linux <8>: I18N Example.
+* Linux <2>: Atari Compiling.
+* Linux <3>: Additional Configuration Options.
+* Linux <4>: I18N Example.
* Linux: Manual History.
* locale categories: Explaining gettext.
-* locale, definition of: Time Functions.
* localization: I18N and L10N.
-* log built-in function: Numeric Functions.
-* logical false: Truth Values.
-* logical operators: Boolean Ops.
-* logical true: Truth Values.
+* localization, See internationalization, localization: I18N and L10N.
+* log files, timestamps in: Time Functions.
+* log function: Numeric Functions.
+* logical false/true: Truth Values.
+* logical operators, See Boolean expressions: Boolean Ops.
* login information: Passwd Functions.
* long options: Command Line.
-* loop: While Statement.
+* loops: While Statement.
+* loops, continue statements and: For Statement.
+* loops, count for header: Profiling.
* loops, exiting: Break Statement.
+* loops, See Also while statement: While Statement.
* Lost In Space: Dynamic Extensions.
* ls utility: More Complex.
-* lshift built-in function: Bitwise Functions.
-* lvalue: Assignment Ops.
+* lshift function (gawk): Bitwise Functions.
+* lvalues/rvalues: Assignment Ops.
+* mailing labels, printing: Labels Program.
+* mailing list, GNITS: Acknowledgments.
* make_builtin internal function: Internals.
* make_number internal function: Internals.
* make_string internal function: Internals.
* mark parity: Ordinal Functions.
* marked string extraction (internationalization): String Extraction.
-* marked strings for internationalization: Programmer i18n.
+* marked strings, extracting: String Extraction.
* Marx, Groucho: Increment Ops.
-* match built-in function: String Functions.
-* matching ranges of lines: Ranges.
-* matching, leftmost longest <1>: Multiple Line.
-* matching, leftmost longest: Leftmost Longest.
-* matching, the null string: Gory Details.
-* mawk, source code: Other Versions.
-* merging strings: Join Function.
-* message object files (gettext): Explaining gettext.
-* metacharacters: Regexp Operators.
-* mistakes, common <1>: Options.
-* mistakes, common <2>: String Functions.
-* mistakes, common <3>: Typing and Comparison.
-* mistakes, common <4>: Concatenation.
-* mistakes, common <5>: Arithmetic Ops.
-* mistakes, common <6>: Special FD.
-* mistakes, common <7>: Redirection.
-* mistakes, common <8>: Print Examples.
-* mistakes, common <9>: Field Separators.
-* mistakes, common <10>: Computed Regexps.
-* mistakes, common: Escape Sequences.
-* mktime built-in function: Time Functions.
-* modifiers (in format specifiers): Format Modifiers.
+* match function: String Functions.
+* match function, RSTART/RLENGTH variables: String Functions.
+* matching, expressions, See comparison expressions: Typing and Comparison.
+* matching, leftmost longest: Multiple Line.
+* matching, null strings: Gory Details.
+* mawk program: Other Versions.
+* memory, releasing: Internals.
+* memory, setting limits: Options.
+* message object files: Explaining gettext.
+* message object files, converting from portable object files: I18N Example.
+* message object files, specifying directory of <1>: Programmer i18n.
+* message object files, specifying directory of: Explaining gettext.
+* metacharacters, escape sequences for: Escape Sequences.
+* mktime function (gawk): Time Functions.
+* modifiers, in format specifiers: Format Modifiers.
+* monetary information, localization: Explaining gettext.
* msgfmt utility: I18N Example.
-* multidimensional subscripts: Multi-dimensional.
-* multiple line records: Multiple Line.
-* multiple passes over data: Other Arguments.
-* multiple statements on one line: Statements/Lines.
-* multiplication: Arithmetic Ops.
-* mv utility: Redirection.
-* names, use of <1>: Library Names.
-* names, use of <2>: Definition Syntax.
-* names, use of: Arrays.
-* namespace issues in awk <1>: Library Names.
-* namespace issues in awk <2>: Definition Syntax.
-* namespace issues in awk: Arrays.
+* names, arrays/variables <1>: Library Names.
+* names, arrays/variables: Arrays.
+* names, functions <1>: Library Names.
+* names, functions: Definition Syntax.
+* namespace issues <1>: Library Names.
+* namespace issues: Arrays.
+* namespace issues, functions: Definition Syntax.
+* nawk utility: Names.
* negative zero: Floating Point Issues.
-* NetBSD <1>: Glossary.
-* NetBSD: Manual History.
-* networking, TCP/IP: TCP/IP Networking.
-* new awk: History.
-* new awk vs. old awk: Names.
-* newline: Statements/Lines.
-* newlines, embedded in dynamic regexps: Computed Regexps.
-* next file statement <1>: POSIX/GNU.
-* next file statement: Nextfile Statement.
-* next statement: Next Statement.
-* next, inside a user-defined function: Next Statement.
+* NetBSD: Glossary.
+* networks, programming: TCP/IP Networking.
+* networks, support for: Special Network.
+* newlines <1>: Options.
+* newlines <2>: Boolean Ops.
+* newlines: Statements/Lines.
+* newlines, as field separators: Field Separators.
+* newlines, as record separators: Records.
+* newlines, in dynamic regexps: Computed Regexps.
+* newlines, in regexp constants: Computed Regexps.
+* newlines, printing: Print Examples.
+* newlines, separating statements in actions <1>: Statements.
+* newlines, separating statements in actions: Action Overview.
+* next file statement: POSIX/GNU.
+* next file statement, deprecated: Obsolete.
+* next file statement, in gawk: Nextfile Statement.
+* next statement <1>: Next Statement.
+* next statement: Boolean Ops.
+* next statement, BEGIN/END patterns and: I/O And BEGIN/END.
+* next statement, user-defined functions and: Next Statement.
* nextfile statement: Nextfile Statement.
+* nextfile statement, BEGIN/END patterns and: I/O And BEGIN/END.
+* nextfile statement, implementing: Nextfile Function.
+* nextfile statement, in gawk: Nextfile Statement.
+* nextfile statement, next file statement and: Obsolete.
+* nextfile statement, user-defined functions and: Nextfile Statement.
* nextfile user-defined function: Nextfile Function.
-* nextfile, inside a user-defined function: Nextfile Statement.
* NF variable <1>: Auto-set.
* NF variable: Fields.
+* NF variable, decrementing: Changing Fields.
* noassign.awk program: Ignoring Assigns.
* NODE internal type: Internals.
-* non-interactive buffering vs. interactive: I/O Functions.
-* non-readable data files, skipping: File Checking.
-* NOT logical operator: Boolean Ops.
+* nodes, duplicating: Internals.
+* not Boolean-logic operator: Boolean Ops.
* NR variable <1>: Auto-set.
* NR variable: Records.
-* null string <1>: Truth Values.
-* null string <2>: Conversion.
-* null string: Regexp Field Splitting.
-* null string, as array subscript: Uninitialized Subscripts.
-* null string, definition of: Basic Data Typing.
-* number of fields, NF: Fields.
-* number of records, NR, FNR: Records.
-* numbers, hexadecimal: Non-decimal-numbers.
-* numbers, octal: Non-decimal-numbers.
-* numbers, used as subscripts: Numeric Array Subscripts.
-* numeric character values: Ordinal Functions.
-* numeric constant: Scalar Constants.
-* numeric output format: OFMT.
-* numeric string: Typing and Comparison.
-* numeric value: Scalar Constants.
+* NR variable, changing: Auto-set.
+* null strings <1>: Basic Data Typing.
+* null strings <2>: Truth Values.
+* null strings <3>: Regexp Field Splitting.
+* null strings: Records.
+* null strings, array elements and: Delete.
+* null strings, as array subscripts: Uninitialized Subscripts.
+* null strings, converting numbers to strings: Conversion.
+* null strings, matching: Gory Details.
+* null strings, quoting and: Quoting.
+* number sign (#), #! (executable scripts): Executable Scripts.
+* number sign (#), #! (executable scripts), portability issues with: Executable Scripts.
+* number sign (#), commenting: Comments.
+* numbers: Internals.
+* numbers, as array subscripts: Numeric Array Subscripts.
+* numbers, as values of characters: Ordinal Functions.
+* numbers, Cliff random: Cliff Random Function.
+* numbers, converting: Conversion.
+* numbers, converting, to strings <1>: Bitwise Functions.
+* numbers, converting, to strings: User-modified.
+* numbers, floating-point: Basic Data Typing.
+* numbers, floating-point, AWKNUM internal type: Internals.
+* numbers, hexadecimal: Nondecimal-numbers.
+* numbers, NODE internal type: Internals.
+* numbers, octal: Nondecimal-numbers.
+* numbers, random: Numeric Functions.
+* numbers, rounding: Round Function.
+* numeric, constants: Scalar Constants.
+* numeric, output format: OFMT.
+* numeric, strings: Typing and Comparison.
+* numeric, values: Internals.
+* oawk utility: Names.
* obsolete features: Obsolete.
-* obsolete options: Obsolete.
-* octal numbers: Non-decimal-numbers.
+* octal numbers: Nondecimal-numbers.
+* octal values, enabling interpretation of: Options.
* OFMT variable <1>: User-modified.
* OFMT variable <2>: Conversion.
* OFMT variable: OFMT.
+* OFMT variable, POSIX awk and: OFMT.
* OFS variable <1>: User-modified.
-* OFS variable: Output Separators.
-* old awk: History.
-* old awk vs. new awk: Names.
-* one-liners: Very Simple.
-* online documentation: Manual History.
-* OpenBSD <1>: Glossary.
-* OpenBSD: Manual History.
-* operator precedence <1>: Precedence.
-* operator precedence: Increment Ops.
+* OFS variable <2>: Output Separators.
+* OFS variable: Changing Fields.
+* OpenBSD: Glossary.
+* operating systems, BSD-based <1>: Portal Files.
+* operating systems, BSD-based: Manual History.
+* operating systems, PC, gawk on: PC Using.
+* operating systems, PC, gawk on, installing: PC Installation.
+* operating systems, porting gawk to: New Ports.
+* operating systems, See Also GNU/Linux, PC operating systems, Unix: Installation.
+* operations, bitwise: Bitwise Functions.
* operators, arithmetic: Arithmetic Ops.
* operators, assignment: Assignment Ops.
-* operators, boolean: Boolean Ops.
-* operators, decrement: Increment Ops.
-* operators, increment: Increment Ops.
-* operators, logical: Boolean Ops.
-* operators, regexp matching: Regexp Usage.
-* operators, relational: Typing and Comparison.
+* operators, assignment, evaluation order: Assignment Ops.
+* operators, Boolean, See Boolean expressions: Boolean Ops.
+* operators, decrement/increment: Increment Ops.
+* operators, GNU-specific: GNU Regexp Operators.
+* operators, input/output <1>: Precedence.
+* operators, input/output <2>: Redirection.
+* operators, input/output <3>: Getline/Coprocess.
+* operators, input/output <4>: Getline/Pipe.
+* operators, input/output: Getline/File.
+* operators, logical, See Boolean expressions: Boolean Ops.
+* operators, precedence <1>: Precedence.
+* operators, precedence: Increment Ops.
+* operators, relational, See operators, comparison: Typing and Comparison.
* operators, short-circuit: Boolean Ops.
* operators, string: Concatenation.
* operators, string-matching: Regexp Usage.
-* options, command-line: Command Line.
+* operators, string-matching, for buffers: GNU Regexp Operators.
+* operators, word-boundary (gawk): GNU Regexp Operators.
+* options, command-line <1>: Options.
+* options, command-line <2>: Command Line Field Separator.
+* options, command-line: Long.
+* options, command-line, end of: Options.
+* options, command-line, invoking awk: Command Line.
+* options, command-line, processing: Getopt Function.
+* options, deprecated: Obsolete.
+* options, long <1>: Options.
* options, long: Command Line.
+* options, printing list of: Options.
* OR bitwise operation: Bitwise Functions.
-* or built-in function: Bitwise Functions.
-* OR logical operator: Boolean Ops.
+* or Boolean-logic operator: Boolean Ops.
+* or function (gawk): Bitwise Functions.
* ord user-defined function: Ordinal Functions.
-* order of evaluation: Calling Built-in.
* order of evaluation, concatenation: Concatenation.
* ORS variable <1>: User-modified.
* ORS variable: Output Separators.
-* other awk implementations: Other Versions.
-* output: Printing.
-* output field separator, OFS: Output Separators.
-* output format specifier, OFMT: OFMT.
-* output record separator, ORS: Output Separators.
+* output field separator, See OFS variable: Changing Fields.
+* output record separator, See ORS variable: Output Separators.
* output redirection: Redirection.
* output, buffering: I/O Functions.
+* output, duplicating into files: Tee Program.
+* output, files, closing: Close Files And Pipes.
+* output, format specifier, OFMT: OFMT.
* output, formatted: Printf.
-* output, piping: Redirection.
+* output, pipes: Redirection.
+* output, printing, See printing: Printing.
+* output, records: Output Separators.
+* output, standard: Special FD.
* P1003.2 POSIX standard: Glossary.
* param_cnt internal variable: Internals.
-* passes, multiple: Other Arguments.
+* parameters, number of: Internals.
+* parentheses (): Regexp Operators.
+* parentheses (), pgawk program: Profiling.
* password file: Passwd Functions.
-* path, search <1>: VMS Running.
-* path, search <2>: PC Using.
-* path, search <3>: Igawk Program.
-* path, search: AWKPATH Variable.
-* pattern, BEGIN: BEGIN/END.
-* pattern, default: Very Simple.
-* pattern, definition of: Patterns and Actions.
-* pattern, empty: Empty.
-* pattern, END: BEGIN/END.
-* pattern, range: Ranges.
-* pattern, regular expressions: Regexp.
+* patterns: Patterns and Actions.
+* patterns, comparison expressions as: Expression Patterns.
+* patterns, counts: Profiling.
+* patterns, default: Very Simple.
+* patterns, empty: Empty.
+* patterns, expressions as: Regexp Patterns.
+* patterns, ranges in: Ranges.
+* patterns, regexp constants as: Expression Patterns.
* patterns, types of: Pattern Overview.
-* per file initialization and cleanup: Filetrans Function.
+* PC operating systems, gawk on: PC Using.
+* PC operating systems, gawk on, installing: PC Installation.
+* percent sign (%), % operator: Precedence.
+* percent sign (%), %= operator <1>: Precedence.
+* percent sign (%), %= operator: Assignment Ops.
+* period (.): Regexp Operators.
* PERL: Future Extensions.
* Peters, Arno: Contributors.
* Peterson, Hal: Contributors.
* pgawk program: Profiling.
-* pipeline, input: Getline/Pipe.
-* pipes for output: Redirection.
-* piping commands into the shell: Redirection.
-* portability issues <1>: Library Functions.
-* portability issues <2>: I18N Portability.
-* portability issues <3>: Function Caveats.
-* portability issues <4>: Definition Syntax.
-* portability issues <5>: I/O Functions.
-* portability issues <6>: String Functions.
-* portability issues <7>: Delete.
-* portability issues <8>: Precedence.
-* portability issues <9>: Increment Ops.
-* portability issues <10>: Assignment Ops.
-* portability issues <11>: Arithmetic Ops.
-* portability issues <12>: Close Files And Pipes.
-* portability issues <13>: Changing Fields.
-* portability issues <14>: Records.
-* portability issues <15>: Escape Sequences.
-* portability issues <16>: Statements/Lines.
-* portability issues: Executable Scripts.
-* portability issues, internationalization of awk programs: I18N Portability.
-* portable object files (gettext): Explaining gettext.
+* pgawk program, awkprof.out file: Profiling.
+* pgawk program, dynamic profiling: Profiling.
+* pipes, closing: Close Files And Pipes.
+* pipes, input: Getline/Pipe.
+* pipes, output: Redirection.
+* plus sign (+): Regexp Operators.
+* plus sign (+), + operator: Precedence.
+* plus sign (+), ++ operator <1>: Precedence.
+* plus sign (+), ++ operator: Increment Ops.
+* plus sign (+), += operator <1>: Precedence.
+* plus sign (+), += operator: Assignment Ops.
+* plus sign (+), decrement/increment operators: Increment Ops.
+* portability: Escape Sequences.
+* portability, #! (executable scripts): Executable Scripts.
+* portability, ** operator and: Arithmetic Ops.
+* portability, **= operator and: Assignment Ops.
+* portability, ARGV variable: Executable Scripts.
+* portability, backslash continuation and: Statements/Lines.
+* portability, backslash in escape sequences: Escape Sequences.
+* portability, close function and: Close Files And Pipes.
+* portability, data files as single record: Records.
+* portability, deleting array elements: Delete.
+* portability, example programs: Library Functions.
+* portability, fflush function and: I/O Functions.
+* portability, functions, defining: Definition Syntax.
+* portability, gawk: New Ports.
+* portability, gettext library and: Explaining gettext.
+* portability, internationalization and: I18N Portability.
+* portability, length function: String Functions.
+* portability, new awk vs. old awk: Conversion.
+* portability, next statement in user-defined functions: Function Caveats.
+* portability, NF variable, decrementing: Changing Fields.
+* portability, operators: Increment Ops.
+* portability, operators, not in POSIX awk: Precedence.
+* portability, POSIXLY_CORRECT environment variable: Options.
+* portability, substr function: String Functions.
+* portable object files <1>: Translator i18n.
+* portable object files: Explaining gettext.
+* portable object files, converting to message object files: I18N Example.
+* portable object files, generating: Options.
* portal files: Portal Files.
* porting gawk: New Ports.
-* positional specifier, printf <1>: Printf Ordering.
-* positional specifier, printf: Format Modifiers.
-* positional specifiers, mixing with regular formats (printf): Printf Ordering.
+* positional specifiers, printf statement <1>: Printf Ordering.
+* positional specifiers, printf statement: Format Modifiers.
+* positional specifiers, printf statement, mixing with regular formats: Printf Ordering.
* positive zero: Floating Point Issues.
-* POSIX awk <1>: Definition Syntax.
-* POSIX awk <2>: Gory Details.
-* POSIX awk <3>: String Functions.
-* POSIX awk <4>: User-modified.
-* POSIX awk <5>: Next Statement.
-* POSIX awk <6>: Continue Statement.
-* POSIX awk <7>: Break Statement.
-* POSIX awk <8>: Precedence.
-* POSIX awk <9>: Assignment Ops.
-* POSIX awk <10>: Arithmetic Ops.
-* POSIX awk <11>: Conversion.
-* POSIX awk <12>: Format Modifiers.
-* POSIX awk <13>: OFMT.
-* POSIX awk <14>: Field Splitting Summary.
-* POSIX awk <15>: Character Lists.
-* POSIX awk <16>: Regexp Operators.
-* POSIX awk: Escape Sequences.
+* POSIX awk <1>: Assignment Ops.
+* POSIX awk: This Manual.
+* POSIX awk, **= operator and: Assignment Ops.
+* POSIX awk, < operator and: Getline/File.
+* POSIX awk, arithmetic operators and: Arithmetic Ops.
+* POSIX awk, backslashes in string constants: Escape Sequences.
+* POSIX awk, BEGIN/END patterns: I/O And BEGIN/END.
+* POSIX awk, break statement and: Break Statement.
+* POSIX awk, changes in awk versions: POSIX.
+* POSIX awk, character lists and: Character Lists.
+* POSIX awk, character lists and, character classes: Character Lists.
+* POSIX awk, continue statement and: Continue Statement.
+* POSIX awk, CONVFMT variable and: User-modified.
+* POSIX awk, date utility and: Time Functions.
+* POSIX awk, field separators and <1>: Field Splitting Summary.
+* POSIX awk, field separators and: Fields.
+* POSIX awk, FS variable and: User-modified.
+* POSIX awk, function keyword in: Definition Syntax.
+* POSIX awk, functions and, gsub/sub: Gory Details.
+* POSIX awk, functions and, length: String Functions.
+* POSIX awk, GNU long options and: Options.
+* POSIX awk, interval expressions in: Regexp Operators.
+* POSIX awk, next/nextfile statements and: Next Statement.
+* POSIX awk, numeric strings and: Typing and Comparison.
+* POSIX awk, OFMT variable and <1>: Conversion.
+* POSIX awk, OFMT variable and: OFMT.
+* POSIX awk, period (.), using: Regexp Operators.
+* POSIX awk, pipes, closing: Close Files And Pipes.
+* POSIX awk, printf format strings and: Format Modifiers.
+* POSIX awk, regular expressions and: Regexp Operators.
+* POSIX awk, timestamps and: Time Functions.
+* POSIX awk, | I/O operator and: Getline/Pipe.
* POSIX mode: Options.
+* POSIX, awk and: Preface.
+* POSIX, gawk extensions not included in: POSIX/GNU.
+* POSIX, programs, implementing in awk: Clones.
* POSIXLY_CORRECT environment variable: Options.
* precedence <1>: Precedence.
* precedence: Increment Ops.
* precedence, regexp operators: Regexp Operators.
-* print statement: Print.
-* printf statement: Printf.
+* print statement: Printing.
+* print statement, BEGIN/END patterns and: I/O And BEGIN/END.
+* print statement, commas, omitting: Print Examples.
+* print statement, I/O operators in: Precedence.
+* print statement, line continuations and: Print Examples.
+* print statement, OFMT variable and: User-modified.
+* print statement, See Also redirection, of output: Redirection.
+* print statement, sprintf function and: Round Function.
+* printf statement <1>: Printf.
+* printf statement: Printing.
+* printf statement, columns, aligning: Print Examples.
+* printf statement, format-control characters: Control Letters.
+* printf statement, I/O operators in: Precedence.
+* printf statement, modifiers: Format Modifiers.
+* printf statement, positional specifiers <1>: Printf Ordering.
+* printf statement, positional specifiers: Format Modifiers.
+* printf statement, positional specifiers, mixing with regular formats: Printf Ordering.
+* printf statement, See Also redirection, of output: Redirection.
+* printf statement, sprintf function and: Round Function.
* printf statement, syntax of: Basic Printf.
-* printf, format-control characters: Control Letters.
-* printf, mixing positional specifiers with regular formats: Printf Ordering.
-* printf, modifiers: Format Modifiers.
-* printf, positional specifier <1>: Printf Ordering.
-* printf, positional specifier: Format Modifiers.
* printing: Printing.
-* problem reports: Bugs.
-* procedural languages: Getting Started.
-* process information: Special Process.
-* processing arguments: Getopt Function.
+* printing, list of options: Options.
+* printing, mailing labels: Labels Program.
+* printing, unduplicated lines of text: Uniq Program.
+* printing, user information: Id Program.
+* private variables: Library Names.
+* process information, files for: Special Process.
+* processes, two-way communications with: Two-way I/O.
* processing data: Basic High Level.
-* PROCINFO variable: Auto-set.
+* PROCINFO array <1>: Group Functions.
+* PROCINFO array <2>: Passwd Functions.
+* PROCINFO array <3>: Auto-set.
+* PROCINFO array: Special Caveats.
* profiling awk programs: Profiling.
-* profiling output file (awkprof.out): Profiling.
-* profiling, dynamic: Profiling.
-* program file: Long.
-* program, awk: This Manual.
+* profiling awk programs, dynamically: Profiling.
+* profiling gawk, See pgawk program: Profiling.
* program, definition of: Getting Started.
-* program, self-contained: Executable Scripts.
-* programming concepts, basic: Basic Concepts.
-* programming conventions <1>: Internal File Ops.
-* programming conventions <2>: Nextfile Function.
-* programming conventions <3>: Library Names.
-* programming conventions <4>: Non-decimal Data.
-* programming conventions <5>: Return Statement.
-* programming conventions <6>: Definition Syntax.
-* programming conventions <7>: Calling Built-in.
-* programming conventions <8>: Auto-set.
-* programming conventions: Exit Statement.
+* programmers, attractiveness of: Two-way I/O.
+* programming conventions, --non-decimal-data option: Nondecimal Data.
+* programming conventions, ARGC/ARGV variables: Auto-set.
+* programming conventions, exit statement: Exit Statement.
+* programming conventions, function parameters: Return Statement.
+* programming conventions, functions, calling: Calling Built-in.
+* programming conventions, functions, writing: Definition Syntax.
+* programming conventions, gawk internals: Internal File Ops.
+* programming conventions, nextfile statement: Nextfile Function.
+* programming conventions, private variable names: Library Names.
* programming language, recipe for: History.
+* programming languages, data-driven vs. procedural: Getting Started.
* programming, basic steps: Basic High Level.
-* programs, compiled: Basic High Level.
-* programs, documenting <1>: Library Names.
-* programs, documenting: Comments.
-* programs, interpreted: Basic High Level.
+* programming, concepts: Basic Concepts.
* pwcat program: Passwd Functions.
-* quotient: Arithmetic Ops.
-* quoting rules, shell: Quoting.
-* quoting, shell <1>: Comments.
-* quoting, shell <2>: Long.
-* quoting, shell: Read Terminal.
+* question mark (?) <1>: GNU Regexp Operators.
+* question mark (?): Regexp Operators.
+* question mark (?), ?: operator: Precedence.
+* QUIT signal (MS-DOS): Profiling.
+* quoting <1>: Comments.
+* quoting <2>: Long.
+* quoting: Read Terminal.
+* quoting, rules for: Quoting.
+* quoting, tricks for: Quoting.
* Rakitzis, Byron: History Sorting.
-* rand built-in function: Numeric Functions.
+* rand function: Numeric Functions.
* random numbers, Cliff: Cliff Random Function.
+* random numbers, rand/srand functions: Numeric Functions.
* random numbers, seed of: Numeric Functions.
-* range pattern: Ranges.
+* range expressions: Character Lists.
+* range patterns: Ranges.
* Rankin, Pat <1>: Bugs.
* Rankin, Pat <2>: Contributors.
* Rankin, Pat <3>: Assignment Ops.
* Rankin, Pat: Acknowledgments.
+* raw sockets: TCP/IP Networking.
* readable data files, checking: File Checking.
* readable.awk program: File Checking.
-* reading files: Reading Files.
-* reading files, getline command: Getline.
-* reading files, multiple line records: Multiple Line.
* recipe for a programming language: History.
-* record separator, RS: Records.
-* record terminator, RT: Records.
-* record, definition of <1>: Basic High Level.
-* record, definition of: Records.
-* records, multiple line: Multiple Line.
-* recursive function: Definition Syntax.
+* record separators <1>: User-modified.
+* record separators: Records.
+* record separators, changing: Records.
+* record separators, regular expressions as: Records.
+* record separators, with multiline records: Multiple Line.
+* records <1>: Basic High Level.
+* records: Reading Files.
+* records, multiline: Multiple Line.
+* records, printing: Print.
+* records, splitting input into: Records.
+* records, terminating: Records.
+* records, treating files as: Records.
+* recursive functions: Definition Syntax.
* redirection of input: Getline/File.
* redirection of output: Redirection.
-* reference counting: Array Sorting.
-* reference to array: Reference to Elements.
-* regexp: Regexp.
-* regexp as expression: Typing and Comparison.
-* regexp comparison vs. string comparison: Typing and Comparison.
-* regexp constant: Regexp Usage.
-* regexp constants, difference between slashes and quotes: Computed Regexps.
-* regexp operators <1>: Typing and Comparison.
-* regexp operators <2>: Regexp Operators.
-* regexp operators: Regexp Usage.
-* regexp operators, GNU specific: GNU Regexp Operators.
-* regexp operators, precedence of: Regexp Operators.
-* regexp, anchors: Regexp Operators.
-* regexp, dynamic: Computed Regexps.
-* regexp, dynamic, with embedded newlines: Computed Regexps.
-* regexp, effect of command-line options: GNU Regexp Operators.
-* regular expression: Regexp.
-* regular expression metacharacters: Regexp Operators.
+* reference counting, sorting arrays: Array Sorting.
+* regexp constants <1>: Typing and Comparison.
+* regexp constants <2>: Regexp Constants.
+* regexp constants: Regexp Usage.
+* regexp constants, /=.../, /= operator and: Assignment Ops.
+* regexp constants, as patterns: Expression Patterns.
+* regexp constants, in gawk: Using Constant Regexps.
+* regexp constants, slashes vs. quotes: Computed Regexps.
+* regexp constants, vs. string constants: Computed Regexps.
+* regexp, See regular expressions: Regexp.
+* regular expressions: Regexp.
* regular expressions as field separators: Field Separators.
-* regular expressions as patterns: Regexp.
-* regular expressions as record separators: Records.
+* regular expressions, anchors in: Regexp Operators.
+* regular expressions, as field separators: Regexp Field Splitting.
+* regular expressions, as patterns <1>: Regexp Patterns.
+* regular expressions, as patterns: Regexp Usage.
+* regular expressions, as record separators: Records.
+* regular expressions, case sensitivity <1>: User-modified.
+* regular expressions, case sensitivity: Case-sensitivity.
* regular expressions, computed: Computed Regexps.
-* relational operators: Typing and Comparison.
-* remainder: Arithmetic Ops.
-* removing elements of arrays: Delete.
-* reporting bugs: Bugs.
-* reporting problems: Bugs.
-* return statement: Return Statement.
-* return value from close: Close Files And Pipes.
+* regular expressions, constants, See regexp constants: Regexp Usage.
+* regular expressions, dynamic: Computed Regexps.
+* regular expressions, dynamic, with embedded newlines: Computed Regexps.
+* regular expressions, gawk, command-line options: GNU Regexp Operators.
+* regular expressions, interval expressions and: Options.
+* regular expressions, leftmost longest match: Leftmost Longest.
+* regular expressions, operators <1>: Regexp Operators.
+* regular expressions, operators: Regexp Usage.
+* regular expressions, operators, for buffers: GNU Regexp Operators.
+* regular expressions, operators, for words: GNU Regexp Operators.
+* regular expressions, operators, gawk: GNU Regexp Operators.
+* regular expressions, operators, precedence of: Regexp Operators.
+* regular expressions, searching for: Egrep Program.
+* relational operators, See comparison operators: Typing and Comparison.
+* return statement, user-defined functions: Return Statement.
+* return values, close function: Close Files And Pipes.
+* rev user-defined function: Function Example.
* rewind user-defined function: Rewind Function.
-* RFC 1036: Time Functions.
-* RFC 822: Time Functions.
+* right angle bracket (>), > operator <1>: Precedence.
+* right angle bracket (>), > operator: Typing and Comparison.
+* right angle bracket (>), > operator (I/O): Redirection.
+* right angle bracket (>), >= operator <1>: Precedence.
+* right angle bracket (>), >= operator: Typing and Comparison.
+* right angle bracket (>), >> operator (I/O) <1>: Precedence.
+* right angle bracket (>), >> operator (I/O): Redirection.
* right shift, bitwise: Bitwise Functions.
* Ritchie, Dennis: Basic Data Typing.
-* RLENGTH variable <1>: String Functions.
* RLENGTH variable: Auto-set.
+* RLENGTH variable, match function and: String Functions.
* Robbins, Arnold <1>: Future Extensions.
* Robbins, Arnold <2>: Bugs.
* Robbins, Arnold <3>: Contributors.
@@ -21640,573 +22278,683 @@ Index
* Robbins, Miriam: Acknowledgments.
* Robinson, Will: Dynamic Extensions.
* robot, the: Dynamic Extensions.
-* Rommel, Kai Uwe <1>: Bugs.
-* Rommel, Kai Uwe <2>: Contributors.
+* Rommel, Kai Uwe <1>: Contributors.
* Rommel, Kai Uwe: Acknowledgments.
* round user-defined function: Round Function.
* rounding: Round Function.
+* rounding numbers: Round Function.
* RS variable <1>: User-modified.
* RS variable: Records.
-* rshift built-in function: Bitwise Functions.
-* RSTART variable <1>: String Functions.
+* RS variable, multiline records and: Multiple Line.
+* rshift function (gawk): Bitwise Functions.
* RSTART variable: Auto-set.
+* RSTART variable, match function and: String Functions.
* RT variable <1>: Auto-set.
* RT variable <2>: Multiple Line.
* RT variable: Records.
* Rubin, Paul <1>: Contributors.
* Rubin, Paul: History.
* rule, definition of: Getting Started.
-* running awk programs: Running gawk.
-* running long programs: Long.
-* rvalue: Assignment Ops.
-* sample input files: Sample Data Files.
-* scalar, definition of: Basic Data Typing.
-* scanning an array: Scanning an Array.
+* rvalues/lvalues: Assignment Ops.
+* scalar values: Basic Data Typing.
* Schreiber, Bert: Acknowledgments.
* Schreiber, Rita: Acknowledgments.
-* script, definition of: Getting Started.
-* scripts, executable: Executable Scripts.
-* search path <1>: VMS Running.
-* search path <2>: PC Using.
-* search path <3>: Igawk Program.
-* search path: AWKPATH Variable.
-* search path, for source files <1>: VMS Running.
-* search path, for source files <2>: PC Using.
-* search path, for source files <3>: Igawk Program.
-* search path, for source files: AWKPATH Variable.
+* search paths <1>: VMS Running.
+* search paths: PC Using.
+* search paths, for source files <1>: VMS Running.
+* search paths, for source files <2>: Igawk Program.
+* search paths, for source files: AWKPATH Variable.
+* searching: String Functions.
+* searching, files for regular expressions: Egrep Program.
+* searching, for words: Dupword Program.
* sed utility <1>: Glossary.
* sed utility <2>: Igawk Program.
* sed utility <3>: Simple Sed.
* sed utility: Field Splitting Summary.
-* seed for random numbers: Numeric Functions.
-* self-contained programs: Executable Scripts.
+* semicolon (;): Statements/Lines.
+* semicolon (;), AWKPATH variable and: PC Using.
+* semicolon (;), separating statements in actions <1>: Statements.
+* semicolon (;), separating statements in actions: Action Overview.
+* separators, field: User-modified.
+* separators, field, FIELDWIDTHS variable and: User-modified.
+* separators, field, POSIX and: Fields.
+* separators, for records: Records.
+* separators, for records, regular expressions as: Records.
+* separators, for statements in actions: Action Overview.
+* separators, record: User-modified.
+* separators, subscript: User-modified.
* set_value internal function: Internals.
-* sex, comparisons with <1>: Manual History.
-* sex, comparisons with: This Manual.
-* sex, programmer attractiveness: Two-way I/O.
-* shell and awk interaction: Using Shell Variables.
-* shell quoting <1>: Comments.
-* shell quoting <2>: Long.
-* shell quoting: Read Terminal.
-* shell quoting rules: Quoting.
-* shell quoting, tricks: Quoting.
-* shell varibles, using in awk programs: Using Shell Variables.
-* shell, piping commands into: Redirection.
+* shells, piping commands into: Redirection.
+* shells, quoting: Using Shell Variables.
+* shells, quoting, rules for: Quoting.
+* shells, scripts: One-shot.
+* shells, variables: Using Shell Variables.
* shift, bitwise: Bitwise Functions.
* short-circuit operators: Boolean Ops.
-* side effects <1>: Array Sorting.
-* side effects <2>: Reference to Elements.
-* side effects <3>: Action Overview.
-* side effects <4>: Function Calls.
-* side effects <5>: Conditional Exp.
-* side effects <6>: Boolean Ops.
-* side effects <7>: Increment Ops.
-* side effects <8>: Assignment Ops.
-* side effects <9>: Concatenation.
-* side effects: Getline Notes.
-* SIGHUP signal: Profiling.
-* signals, SIGHUP: Profiling.
-* signals, SIGUSR1: Profiling.
-* SIGUSR1 signal: Profiling.
-* simple stream editor: Simple Sed.
-* sin built-in function: Numeric Functions.
-* single quotes, why needed: One-shot.
+* side effects <1>: Increment Ops.
+* side effects: Concatenation.
+* side effects, array indexing: Reference to Elements.
+* side effects, asort function: Array Sorting.
+* side effects, assignment expressions: Assignment Ops.
+* side effects, Boolean operators: Boolean Ops.
+* side effects, conditional expressions: Conditional Exp.
+* side effects, decrement/increment operators: Increment Ops.
+* side effects, FILENAME variable: Getline Notes.
+* side effects, function calls: Function Calls.
+* side effects, statements: Action Overview.
+* signals, HUP/SIGHUP: Profiling.
+* signals, INT/SIGINT (MS-DOS): Profiling.
+* signals, QUIT/SIGQUIT (MS-DOS): Profiling.
+* signals, USR1/SIGUSR1: Profiling.
+* sin function: Numeric Functions.
+* single quote (') <1>: Quoting.
+* single quote (') <2>: Long.
+* single quote ('): One-shot.
+* single quote ('), vs. apostrophe: Comments.
+* single quote ('), with double quotes: Quoting.
* single-character fields: Single Character Fields.
-* single-precision floating-point, definition of: Basic Data Typing.
-* skipping input files: Nextfile Function.
-* skipping lines between markers: Ranges.
+* single-precision floating-point: Basic Data Typing.
* Skywalker, Luke: Undocumented.
* sleep utility: Alarm Program.
+* sockets: TCP/IP Networking.
+* sort function, arrays, sorting: Array Sorting.
* sort utility: Word Sorting.
+* sort utility, coprocesses and: Two-way I/O.
+* sorting characters in different languages: Explaining gettext.
* source code, awka: Other Versions.
-* source code, gawk: Getting.
+* source code, Bell Laboratories awk: Other Versions.
+* source code, gawk: Gawk Distribution.
* source code, mawk: Other Versions.
-* source code, Unix awk: Other Versions.
+* source code, mixing: Options.
+* source files, search path for: Igawk Program.
* sparse arrays: Array Intro.
* Spencer, Henry: Glossary.
-* split built-in function: String Functions.
+* split function: String Functions.
+* split function, array elements, deleting: Delete.
* split utility: Split Program.
* split.awk program: Split Program.
-* sprintf built-in function: String Functions.
-* sqrt built-in function: Numeric Functions.
-* srand built-in function: Numeric Functions.
+* sprintf function <1>: String Functions.
+* sprintf function: OFMT.
+* sprintf function, OFMT variable and: User-modified.
+* sprintf function, print/printf statements and: Round Function.
+* sqrt function: Numeric Functions.
+* square brackets ([]): Regexp Operators.
+* srand function: Numeric Functions.
* Stallman, Richard <1>: Glossary.
* Stallman, Richard <2>: Contributors.
* Stallman, Richard <3>: Acknowledgments.
* Stallman, Richard: Manual History.
-* standard error output: Special FD.
* standard input <1>: Special FD.
-* standard input <2>: Reading Files.
* standard input: Read Terminal.
* standard output: Special FD.
-* statement, compound: Statements.
+* stat function, implementing in gawk: Sample Library.
+* statements, compound, control statements and: Statements.
+* statements, control, in actions: Statements.
+* statements, multiple: Statements/Lines.
* stlen internal variable: Internals.
* stptr internal variable: Internals.
-* stream editor <1>: Igawk Program.
-* stream editor <2>: Simple Sed.
-* stream editor: Field Splitting Summary.
-* stream editor, simple: Simple Sed.
-* strftime built-in function: Time Functions.
-* string comparison vs. regexp comparison: Typing and Comparison.
+* stream editors <1>: Igawk Program.
+* stream editors <2>: Simple Sed.
+* stream editors: Field Splitting Summary.
+* strftime function (gawk): Time Functions.
* string constants: Scalar Constants.
+* string constants, vs. regexp constants: Computed Regexps.
* string extraction (internationalization): String Extraction.
* string operators: Concatenation.
* string-matching operators: Regexp Usage.
-* strtonum built-in function: String Functions.
-* sub built-in function: String Functions.
-* sub, escape processing: Gory Details.
-* sub, third argument of: String Functions.
-* subscripts in arrays: Multi-dimensional.
-* SUBSEP variable <1>: Multi-dimensional.
+* strings: Internals.
+* strings, converting: Conversion.
+* strings, converting, numbers to <1>: Bitwise Functions.
+* strings, converting, numbers to: User-modified.
+* strings, empty, See null strings: Records.
+* strings, extracting: String Extraction.
+* strings, for localization: Programmer i18n.
+* strings, length of: Scalar Constants.
+* strings, merging arrays into: Join Function.
+* strings, NODE internal type: Internals.
+* strings, null: Regexp Field Splitting.
+* strings, numeric: Typing and Comparison.
+* strings, splitting: String Functions.
+* strtonum function (gawk): String Functions.
+* strtonum function (gawk), --non-decimal-data option and: Nondecimal Data.
+* sub function <1>: String Functions.
+* sub function: Using Constant Regexps.
+* sub function, arguments of: String Functions.
+* sub function, escape processing: Gory Details.
+* subscript separators: User-modified.
+* subscripts in arrays, multidimensional: Multi-dimensional.
+* subscripts in arrays, multidimensional, scanning: Multi-scanning.
+* subscripts in arrays, numbers as: Numeric Array Subscripts.
+* subscripts in arrays, uninitialized variables as: Uninitialized Subscripts.
* SUBSEP variable: User-modified.
-* substr built-in function: String Functions.
-* subtraction: Arithmetic Ops.
+* SUBSEP variable, multidimensional arrays: Multi-dimensional.
+* substr function: String Functions.
* Sumner, Andrew: Other Versions.
* syntactic ambiguity: /= operator vs. /=.../ regexp constant: Assignment Ops.
-* system built-in function: I/O Functions.
-* systime built-in function: Time Functions.
+* system function: I/O Functions.
+* systime function (gawk): Time Functions.
* tandem: Tandem Installation.
* Tcl: Library Names.
-* TCP/IP networking <1>: Portal Files.
-* TCP/IP networking: TCP/IP Networking.
+* TCP/IP: TCP/IP Networking.
+* TCP/IP, support for: Special Network.
* tee utility: Tee Program.
* tee.awk program: Tee Program.
-* terminator, record: Records.
+* terminating records: Records.
* testbits.awk program: Bitwise Functions.
* Texinfo <1>: Adding Code.
* Texinfo <2>: Distribution contents.
* Texinfo <3>: Extract Program.
* Texinfo <4>: Dupword Program.
* Texinfo <5>: Library Functions.
-* Texinfo <6>: Regexp Operators.
-* Texinfo <7>: Sample Data Files.
-* Texinfo <8>: Acknowledgments.
+* Texinfo <6>: Sample Data Files.
* Texinfo: Conventions.
-* textdomain C library function: Explaining gettext.
+* Texinfo, chapter beginnings in files: Regexp Operators.
+* Texinfo, extracting programs from source files: Extract Program.
+* text, printing: Print.
+* text, printing, unduplicated lines of: Uniq Program.
+* textdomain function (C library): Explaining gettext.
* TEXTDOMAIN variable <1>: Programmer i18n.
* TEXTDOMAIN variable: User-modified.
-* time of day: Time Functions.
+* TEXTDOMAIN variable, BEGIN pattern and: Programmer i18n.
+* TEXTDOMAIN variable, portability and: I18N Portability.
+* tilde (~), ~ operator <1>: Expression Patterns.
+* tilde (~), ~ operator <2>: Precedence.
+* tilde (~), ~ operator <3>: Typing and Comparison.
+* tilde (~), ~ operator <4>: Regexp Constants.
+* tilde (~), ~ operator <5>: Computed Regexps.
+* tilde (~), ~ operator <6>: Case-sensitivity.
+* tilde (~), ~ operator: Regexp Usage.
+* time, alarm clock example program: Alarm Program.
+* time, localization and: Explaining gettext.
+* time, managing: Gettimeofday Function.
+* time, retrieving: Time Functions.
* timestamps: Time Functions.
-* timestamps, converting from dates: Time Functions.
+* timestamps, converting dates to: Time Functions.
* timestamps, formatted: Gettimeofday Function.
* tmp_number internal function: Internals.
* tmp_string internal function: Internals.
-* tolower built-in function: String Functions.
-* Torvalds, Linus: Manual History.
-* toupper built-in function: String Functions.
+* tolower function: String Functions.
+* toupper function: String Functions.
* tr utility: Translate Program.
* translate.awk program: Translate Program.
+* troubleshooting, --non-decimal-data option: Options.
+* troubleshooting, -F option: Known Bugs.
+* troubleshooting, == operator: Typing and Comparison.
+* troubleshooting, awk uses FS not IFS: Field Separators.
+* troubleshooting, backslash before nonspecial character: Escape Sequences.
+* troubleshooting, division: Arithmetic Ops.
+* troubleshooting, fatal errors, field widths, specifying: Constant Size.
+* troubleshooting, fatal errors, printf format strings: Format Modifiers.
+* troubleshooting, fflush function: I/O Functions.
+* troubleshooting, function call syntax: Function Calls.
+* troubleshooting, gawk <1>: Compatibility Mode.
+* troubleshooting, gawk: Known Bugs.
+* troubleshooting, gawk, bug reports: Bugs.
+* troubleshooting, gawk, fatal errors, function arguments: Calling Built-in.
+* troubleshooting, getline function: File Checking.
+* troubleshooting, gsub/sub functions: String Functions.
+* troubleshooting, match function: String Functions.
+* troubleshooting, print statement, omitting commas: Print Examples.
+* troubleshooting, printing: Redirection.
+* troubleshooting, quotes with file names: Special FD.
+* troubleshooting, readable data files: File Checking.
+* troubleshooting, regexp constants vs. string constants: Computed Regexps.
+* troubleshooting, string concatenation: Concatenation.
+* troubleshooting, substr function: String Functions.
+* troubleshooting, system function: I/O Functions.
+* troubleshooting, typographical errors, global variables: Options.
+* true, logical: Truth Values.
* Trueman, David <1>: Contributors.
* Trueman, David <2>: Acknowledgments.
* Trueman, David: History.
+* trunc-mod operation: Arithmetic Ops.
* truth values: Truth Values.
-* two-way I/O: Two-way I/O.
* type conversion: Conversion.
* type internal variable: Internals.
-* types of variables <1>: Typing and Comparison.
-* types of variables: Assignment Ops.
* undefined functions: Function Caveats.
+* underscore (_), _ C macro: Explaining gettext.
+* underscore (_), in names of private variables: Library Names.
+* underscore (_), translatable string: Programmer i18n.
* undocumented features: Undocumented.
* uninitialized variables, as array subscripts: Uninitialized Subscripts.
* uniq utility: Uniq Program.
* uniq.awk program: Uniq Program.
* Unix: Glossary.
-* Unix awk, source code: Other Versions.
+* Unix awk, backslashes in escape sequences: Escape Sequences.
+* Unix awk, close function and: Close Files And Pipes.
+* Unix awk, password files, field separators and: Command Line Field Separator.
+* Unix, awk scripts and: Executable Scripts.
* unsigned integers: Basic Data Typing.
* update_ERRNO internal function: Internals.
-* use of comments: Comments.
-* user information: Passwd Functions.
-* user-defined functions: User-defined.
-* user-defined variables: Using Variables.
-* uses of awk <1>: When.
-* uses of awk: Preface.
-* uses of gawk: Preface.
-* using shell variables in awk programs: Using Shell Variables.
-* using this book: This Manual.
+* user database, reading: Passwd Functions.
+* user-defined, functions: User-defined.
+* user-defined, functions, counts: Profiling.
+* user-defined, variables: Variables.
+* user-modifiable variables: User-modified.
+* users, information about, printing: Id Program.
+* users, information about, retrieving: Passwd Functions.
* USR1 signal: Profiling.
-* values of characters as numbers: Ordinal Functions.
* values, numeric: Basic Data Typing.
* values, string: Basic Data Typing.
-* variable shadowing: Definition Syntax.
* variable typing: Typing and Comparison.
-* variable, definition of: Basic Data Typing.
-* variables, user-defined: Using Variables.
+* variables <1>: Basic Data Typing.
+* variables: Other Features.
+* variables, assigning on command line: Assignment Options.
+* variables, built-in <1>: Built-in Variables.
+* variables, built-in: Using Variables.
+* variables, built-in, -v option, setting with: Options.
+* variables, built-in, conveying information: Auto-set.
+* variables, flag: Boolean Ops.
+* variables, getline command into, using <1>: Getline/Variable/Coprocess.
+* variables, getline command into, using <2>: Getline/Variable/Pipe.
+* variables, getline command into, using <3>: Getline/Variable/File.
+* variables, getline command into, using: Getline/Variable.
+* variables, global, for library functions: Library Names.
+* variables, global, printing list of: Options.
+* variables, initializing: Using Variables.
+* variables, names of: Arrays.
+* variables, private: Library Names.
+* variables, setting: Options.
+* variables, shadowing: Definition Syntax.
+* variables, types of: Assignment Ops.
+* variables, types of, comparison expressions and: Typing and Comparison.
+* variables, uninitialized, as array subscripts: Uninitialized Subscripts.
+* variables, user-defined: Variables.
+* vertical bar (|): Regexp Operators.
+* vertical bar (|), | operator (I/O) <1>: Precedence.
+* vertical bar (|), | operator (I/O): Getline/Pipe.
+* vertical bar (|), |& I/O operator (I/O): Two-way I/O.
+* vertical bar (|), |& operator (I/O) <1>: Precedence.
+* vertical bar (|), |& operator (I/O): Getline/Coprocess.
+* vertical bar (|), |& operator (I/O), two-way communications: Portal Files.
+* vertical bar (|), || operator <1>: Precedence.
+* vertical bar (|), || operator: Boolean Ops.
* vname internal variable: Internals.
* w utility: Constant Size.
* Wall, Larry: Future Extensions.
-* warnings, automatic <1>: Options.
-* warnings, automatic <2>: I/O Functions.
-* warnings, automatic <3>: String Functions.
-* warnings, automatic <4>: Using Constant Regexps.
-* warnings, automatic <5>: Special Caveats.
-* warnings, automatic <6>: Special Process.
-* warnings, automatic: Escape Sequences.
+* warnings, issuing: Options.
* wc utility: Wc Program.
* wc.awk program: Wc Program.
* Weinberger, Peter <1>: Contributors.
* Weinberger, Peter: History.
-* while statement: While Statement.
+* while statement <1>: While Statement.
+* while statement: Regexp Usage.
+* whitespace, as field separators: Field Separators.
+* whitespace, functions, calling: Calling Built-in.
+* whitespace, newlines as: Options.
* Williams, Kent: Contributors.
* Woods, John: Contributors.
* word boundaries, matching: GNU Regexp Operators.
* word, regexp definition of: GNU Regexp Operators.
+* word-boundary operator (gawk): GNU Regexp Operators.
* wordfreq.awk program: Word Sorting.
+* words, counting: Wc Program.
+* words, duplicate, searching for: Dupword Program.
+* words, usage counts, generating: Word Sorting.
* xgettext utility: String Extraction.
* XOR bitwise operation: Bitwise Functions.
-* xor built-in function: Bitwise Functions.
+* xor function (gawk): Bitwise Functions.
* Zaretskii, Eli: Acknowledgments.
* zero, negative vs. positive: Floating Point Issues.
* Zoulas, Christos: Contributors.
-* | I/O operator <1>: Precedence.
-* | I/O operator <2>: Redirection.
-* | I/O operator: Getline/Pipe.
-* |& I/O operator <1>: Two-way I/O.
-* |& I/O operator <2>: Precedence.
-* |& I/O operator <3>: Redirection.
-* |& I/O operator: Getline/Coprocess.
-* || operator <1>: Precedence.
-* || operator: Boolean Ops.
-* ~ operator <1>: Precedence.
-* ~ operator <2>: Typing and Comparison.
-* ~ operator <3>: Regexp Constants.
-* ~ operator <4>: Computed Regexps.
-* ~ operator <5>: Case-sensitivity.
-* ~ operator: Regexp Usage.
+* {} (braces), actions and: Action Overview.
+* {} (braces), pgawk program: Profiling.
+* {} (braces), statements, grouping: Statements.
+* | (vertical bar): Regexp Operators.
+* | (vertical bar), | operator (I/O) <1>: Precedence.
+* | (vertical bar), | operator (I/O) <2>: Redirection.
+* | (vertical bar), | operator (I/O): Getline/Pipe.
+* | (vertical bar), |& operator (I/O) <1>: Two-way I/O.
+* | (vertical bar), |& operator (I/O) <2>: Precedence.
+* | (vertical bar), |& operator (I/O) <3>: Redirection.
+* | (vertical bar), |& operator (I/O): Getline/Coprocess.
+* | (vertical bar), |& operator (I/O), pipes, closing: Close Files And Pipes.
+* | (vertical bar), |& operator (I/O), two-way communications: Portal Files.
+* | (vertical bar), || operator <1>: Precedence.
+* | (vertical bar), || operator: Boolean Ops.
+* ~ (tilde), ~ operator <1>: Expression Patterns.
+* ~ (tilde), ~ operator <2>: Precedence.
+* ~ (tilde), ~ operator <3>: Typing and Comparison.
+* ~ (tilde), ~ operator <4>: Regexp Constants.
+* ~ (tilde), ~ operator <5>: Computed Regexps.
+* ~ (tilde), ~ operator: Case-sensitivity.

Tag Table:
-Node: Top1365
-Node: Foreword25650
-Node: Preface29974
-Ref: Preface-Footnote-132860
-Node: History33092
-Node: Names35352
-Ref: Names-Footnote-136853
-Node: This Manual36925
-Ref: This Manual-Footnote-142290
-Node: Conventions42397
-Node: Manual History44274
-Ref: Manual History-Footnote-148037
-Ref: Manual History-Footnote-248078
-Node: How To Contribute48152
-Node: Acknowledgments48750
-Node: Getting Started52540
-Node: Running gawk54933
-Node: One-shot56139
-Node: Read Terminal57398
-Ref: Read Terminal-Footnote-159051
-Node: Long59222
-Node: Executable Scripts60623
-Ref: Executable Scripts-Footnote-162359
-Ref: Executable Scripts-Footnote-262510
-Node: Comments62955
-Node: Quoting65349
-Node: Sample Data Files69331
-Node: Very Simple72427
-Node: Two Rules77034
-Node: More Complex79239
-Ref: More Complex-Footnote-182161
-Ref: More Complex-Footnote-282647
-Node: Statements/Lines82730
-Ref: Statements/Lines-Footnote-187094
-Node: Other Features87403
-Node: When88268
-Node: Regexp90257
-Node: Regexp Usage91648
-Node: Escape Sequences93713
-Node: Regexp Operators99658
-Ref: Regexp Operators-Footnote-1106811
-Ref: Regexp Operators-Footnote-2106957
-Node: Character Lists107055
-Node: GNU Regexp Operators111565
-Node: Case-sensitivity115046
-Ref: Case-sensitivity-Footnote-1118168
-Node: Leftmost Longest118403
-Node: Computed Regexps119717
-Node: Reading Files123108
-Node: Records124895
-Ref: Records-Footnote-1132790
-Node: Fields132827
-Ref: Fields-Footnote-1135886
-Node: Non-Constant Fields135972
-Node: Changing Fields138227
-Node: Field Separators142929
-Node: Regexp Field Splitting146473
-Node: Single Character Fields148974
-Node: Command Line Field Separator150037
-Node: Field Splitting Summary153467
-Ref: Field Splitting Summary-Footnote-1155571
-Node: Constant Size155672
-Node: Multiple Line160252
-Node: Getline165684
-Node: Plain Getline167748
-Node: Getline/Variable169804
-Node: Getline/File170964
-Node: Getline/Variable/File172389
-Node: Getline/Pipe173999
-Node: Getline/Variable/Pipe176195
-Node: Getline/Coprocess177411
-Node: Getline/Variable/Coprocess178683
-Node: Getline Notes179431
-Node: Getline Summary180780
-Node: Printing181485
-Node: Print183174
-Node: Print Examples184554
-Node: Output Separators187451
-Node: OFMT189267
-Node: Printf190669
-Node: Basic Printf191583
-Node: Control Letters193166
-Node: Format Modifiers195752
-Node: Printf Examples200802
-Node: Redirection203572
-Node: Special Files210306
-Node: Special FD210935
-Node: Special Process213978
-Node: Special Network216264
-Node: Special Caveats217177
-Ref: Special Caveats-Footnote-1218387
-Node: Close Files And Pipes218770
-Ref: Close Files And Pipes-Footnote-1225952
-Node: Expressions226100
-Node: Constants228288
-Node: Scalar Constants228984
-Ref: Scalar Constants-Footnote-1229845
-Node: Non-decimal-numbers230027
-Node: Regexp Constants233200
-Node: Using Constant Regexps233665
-Node: Variables236825
-Node: Using Variables237476
-Node: Assignment Options239017
-Node: Conversion240962
-Ref: Conversion-Footnote-1244196
-Node: Arithmetic Ops244305
-Node: Concatenation246802
-Node: Assignment Ops249497
-Node: Increment Ops255817
-Node: Truth Values259304
-Node: Typing and Comparison260350
-Ref: Typing and Comparison-Footnote-1266904
-Node: Boolean Ops267049
-Node: Conditional Exp271158
-Node: Function Calls272954
-Node: Precedence275921
-Node: Patterns and Actions279365
-Node: Pattern Overview280418
-Node: Regexp Patterns282034
-Node: Expression Patterns282593
-Node: Ranges286199
-Node: BEGIN/END289297
-Node: Using BEGIN/END290037
-Ref: Using BEGIN/END-Footnote-1292821
-Node: I/O And BEGIN/END292927
-Node: Empty295266
-Node: Using Shell Variables295566
-Node: Action Overview297926
-Node: Statements300510
-Node: If Statement302216
-Node: While Statement303723
-Node: Do Statement305746
-Node: For Statement306887
-Node: Break Statement310075
-Node: Continue Statement312179
-Node: Next Statement314127
-Node: Nextfile Statement316496
-Node: Exit Statement319250
-Node: Built-in Variables321359
-Node: User-modified322455
-Ref: User-modified-Footnote-1330031
-Node: Auto-set330093
-Ref: Auto-set-Footnote-1338167
-Node: ARGC and ARGV338372
-Node: Arrays342234
-Node: Array Intro344164
-Node: Reference to Elements348432
-Node: Assigning Elements350323
-Node: Array Example350785
-Node: Scanning an Array352508
-Node: Delete354839
-Ref: Delete-Footnote-1357290
-Node: Numeric Array Subscripts357347
-Node: Uninitialized Subscripts359626
-Node: Multi-dimensional361248
-Node: Multi-scanning364298
-Node: Array Sorting365968
-Node: Functions368782
-Node: Built-in369519
-Node: Calling Built-in370502
-Node: Numeric Functions372481
-Ref: Numeric Functions-Footnote-1376235
-Ref: Numeric Functions-Footnote-2376561
-Node: String Functions376831
-Ref: String Functions-Footnote-1393299
-Ref: String Functions-Footnote-2393460
-Node: Gory Details393544
-Ref: Gory Details-Footnote-1400132
-Ref: Gory Details-Footnote-2400183
-Node: I/O Functions400390
-Ref: I/O Functions-Footnote-1407133
-Node: Time Functions407224
-Ref: Time Functions-Footnote-1418026
-Ref: Time Functions-Footnote-2418098
-Ref: Time Functions-Footnote-3418257
-Ref: Time Functions-Footnote-4418368
-Ref: Time Functions-Footnote-5418493
-Ref: Time Functions-Footnote-6418752
-Node: Bitwise Functions419017
-Ref: Bitwise Functions-Footnote-1423725
-Node: I18N Functions423909
-Node: User-defined425173
-Node: Definition Syntax425949
-Node: Function Example430340
-Node: Function Caveats432982
-Node: Return Statement436894
-Node: Dynamic Typing439564
-Node: Internationalization440300
-Node: I18N and L10N441718
-Node: Explaining gettext442427
-Ref: Explaining gettext-Footnote-1447361
-Ref: Explaining gettext-Footnote-2447600
-Node: Programmer i18n447766
-Node: Translator i18n451569
-Node: String Extraction452354
-Ref: String Extraction-Footnote-1453304
-Node: Printf Ordering453501
-Ref: Printf Ordering-Footnote-1456293
-Node: I18N Portability456357
-Ref: I18N Portability-Footnote-1458617
-Node: I18N Example458680
-Ref: I18N Example-Footnote-1461302
-Node: Gawk I18N461374
-Node: Advanced Features462202
-Node: Non-decimal Data463636
-Node: Two-way I/O465248
-Ref: Two-way I/O-Footnote-1469889
-Node: TCP/IP Networking469966
-Node: Portal Files472445
-Node: Profiling473108
-Node: Invoking Gawk480308
-Node: Command Line481485
-Node: Options482284
-Ref: Options-Footnote-1494190
-Node: Other Arguments494215
-Node: AWKPATH Variable496967
-Ref: AWKPATH Variable-Footnote-1499758
-Node: Obsolete500017
-Node: Undocumented501098
-Node: Known Bugs501350
-Node: Library Functions501969
-Ref: Library Functions-Footnote-1505152
-Node: Library Names505323
-Ref: Library Names-Footnote-1508932
-Ref: Library Names-Footnote-2509152
-Node: General Functions509238
-Node: Nextfile Function510174
-Node: Assert Function514638
-Node: Round Function517974
-Node: Cliff Random Function519529
-Ref: Cliff Random Function-Footnote-1520512
-Node: Ordinal Functions520583
-Ref: Ordinal Functions-Footnote-1523661
-Node: Join Function523877
-Ref: Join Function-Footnote-1525682
-Node: Gettimeofday Function525882
-Node: Data File Management529660
-Node: Filetrans Function530220
-Node: Rewind Function533772
-Node: File Checking535396
-Node: Ignoring Assigns536442
-Node: Getopt Function538026
-Ref: Getopt Function-Footnote-1549173
-Node: Passwd Functions549374
-Ref: Passwd Functions-Footnote-1558085
-Node: Group Functions558173
-Node: Sample Programs566271
-Node: Running Examples567001
-Node: Clones567772
-Node: Cut Program568897
-Node: Egrep Program578768
-Ref: Egrep Program-Footnote-1586632
-Node: Id Program586742
-Node: Split Program590434
-Node: Tee Program593950
-Node: Uniq Program596621
-Node: Wc Program604115
-Ref: Wc Program-Footnote-1608430
-Node: Miscellaneous Programs608654
-Node: Dupword Program609643
-Node: Alarm Program611699
-Node: Translate Program616315
-Ref: Translate Program-Footnote-1620617
-Ref: Translate Program-Footnote-2620854
-Node: Labels Program620988
-Ref: Labels Program-Footnote-1624355
-Node: Word Sorting624439
-Node: History Sorting628742
-Node: Extract Program630612
-Node: Simple Sed638193
-Node: Igawk Program641394
-Ref: Igawk Program-Footnote-1654472
-Node: Language History654610
-Node: V7/SVR3.1655977
-Node: SVR4658572
-Node: POSIX660219
-Node: BTL662007
-Node: POSIX/GNU663824
-Node: Contributors672461
-Node: Installation675554
-Node: Gawk Distribution676533
-Node: Getting677033
-Node: Extracting678270
-Node: Distribution contents679650
-Node: Unix Installation685262
-Node: Quick Installation685848
-Node: Additional Configuration Options687595
-Node: Configuration Philosophy688708
-Node: Non-Unix Installation691091
-Node: Amiga Installation691673
-Node: BeOS Installation692818
-Node: PC Installation693990
-Node: PC Binary Installation695019
-Node: PC Compiling696017
-Node: PC Using697840
-Node: VMS Installation701526
-Node: VMS Compilation702045
-Node: VMS Installation Details703634
-Node: VMS Running705251
-Node: VMS POSIX706835
-Node: Unsupported708099
-Node: Atari Installation708497
-Node: Atari Compiling709818
-Node: Atari Using711747
-Node: Tandem Installation714611
-Node: Bugs716417
-Node: Other Versions719667
-Ref: Other Versions-Footnote-1723253
-Node: Notes723295
-Node: Compatibility Mode723968
-Node: Additions724809
-Node: Adding Code725581
-Node: New Ports731627
-Node: Dynamic Extensions735742
-Node: Internals736758
-Node: Sample Library743097
-Node: Internal File Description743747
-Node: Internal File Ops747499
-Ref: Internal File Ops-Footnote-1752915
-Node: Using Internal File Ops753063
-Node: Future Extensions755084
-Node: Basic Concepts759427
-Node: Basic High Level760165
-Ref: Basic High Level-Footnote-1764332
-Node: Basic Data Typing764526
-Node: Floating Point Issues769020
-Ref: Floating Point Issues-Footnote-1772943
-Ref: Floating Point Issues-Footnote-2772994
-Node: Glossary773103
-Node: Copying797415
-Node: GNU Free Documentation License816614
-Node: Index836506
+Node: Top353
+Node: Foreword26454
+Node: Preface30778
+Ref: Preface-Footnote-133660
+Node: History33892
+Node: Names36151
+Ref: Names-Footnote-137660
+Node: This Manual37732
+Ref: This Manual-Footnote-142925
+Node: Conventions43025
+Node: Manual History44902
+Ref: Manual History-Footnote-148588
+Ref: Manual History-Footnote-248629
+Node: How To Contribute48703
+Node: Acknowledgments49301
+Node: Getting Started53106
+Node: Running gawk55499
+Node: One-shot56704
+Node: Read Terminal57961
+Ref: Read Terminal-Footnote-159610
+Node: Long59781
+Node: Executable Scripts61182
+Ref: Executable Scripts-Footnote-162918
+Ref: Executable Scripts-Footnote-263069
+Node: Comments63520
+Node: Quoting65912
+Node: Sample Data Files69890
+Node: Very Simple72968
+Node: Two Rules77588
+Node: More Complex79787
+Ref: More Complex-Footnote-182710
+Ref: More Complex-Footnote-283186
+Node: Statements/Lines83269
+Ref: Statements/Lines-Footnote-187628
+Node: Other Features87937
+Node: When88802
+Node: Regexp90791
+Node: Regexp Usage92181
+Node: Escape Sequences94272
+Node: Regexp Operators100184
+Ref: Regexp Operators-Footnote-1107325
+Ref: Regexp Operators-Footnote-2107472
+Node: Character Lists107570
+Node: GNU Regexp Operators112039
+Node: Case-sensitivity115534
+Ref: Case-sensitivity-Footnote-1118659
+Node: Leftmost Longest118894
+Node: Computed Regexps120208
+Node: Reading Files123599
+Node: Records125385
+Ref: Records-Footnote-1133263
+Node: Fields133300
+Ref: Fields-Footnote-1136355
+Node: Nonconstant Fields136441
+Node: Changing Fields138693
+Node: Field Separators143403
+Node: Regexp Field Splitting146947
+Node: Single Character Fields149448
+Node: Command Line Field Separator150511
+Node: Field Splitting Summary153962
+Ref: Field Splitting Summary-Footnote-1156065
+Node: Constant Size156166
+Node: Multiple Line160740
+Node: Getline166171
+Node: Plain Getline168234
+Node: Getline/Variable170284
+Node: Getline/File171416
+Node: Getline/Variable/File172841
+Node: Getline/Pipe174464
+Node: Getline/Variable/Pipe176671
+Node: Getline/Coprocess177887
+Node: Getline/Variable/Coprocess179161
+Node: Getline Notes179909
+Node: Getline Summary181258
+Node: Printing181965
+Node: Print183679
+Node: Print Examples185060
+Node: Output Separators187957
+Node: OFMT189773
+Node: Printf191175
+Node: Basic Printf192089
+Node: Control Letters193673
+Node: Format Modifiers196260
+Node: Printf Examples201312
+Node: Redirection204082
+Node: Special Files210806
+Node: Special FD211435
+Node: Special Process214474
+Node: Special Network216760
+Node: Special Caveats217675
+Ref: Special Caveats-Footnote-1218885
+Node: Close Files And Pipes219268
+Ref: Close Files And Pipes-Footnote-1226450
+Node: Expressions226598
+Node: Constants228786
+Node: Scalar Constants229482
+Ref: Scalar Constants-Footnote-1230346
+Node: Nondecimal-numbers230528
+Node: Regexp Constants233704
+Node: Using Constant Regexps234168
+Node: Variables237328
+Node: Using Variables237979
+Node: Assignment Options239520
+Node: Conversion241460
+Ref: Conversion-Footnote-1244691
+Node: Arithmetic Ops244800
+Node: Concatenation247297
+Node: Assignment Ops249992
+Node: Increment Ops256308
+Node: Truth Values259796
+Node: Typing and Comparison260841
+Ref: Typing and Comparison-Footnote-1267395
+Node: Boolean Ops267540
+Node: Conditional Exp271648
+Node: Function Calls273444
+Node: Precedence276417
+Node: Patterns and Actions279861
+Node: Pattern Overview280914
+Node: Regexp Patterns282527
+Node: Expression Patterns283086
+Node: Ranges286692
+Node: BEGIN/END289793
+Node: Using BEGIN/END290533
+Ref: Using BEGIN/END-Footnote-1293318
+Node: I/O And BEGIN/END293432
+Node: Empty295771
+Node: Using Shell Variables296070
+Node: Action Overview298430
+Node: Statements300996
+Node: If Statement302702
+Node: While Statement304211
+Node: Do Statement306234
+Node: For Statement307374
+Node: Break Statement310562
+Node: Continue Statement312666
+Node: Next Statement314605
+Node: Nextfile Statement316994
+Node: Exit Statement319748
+Node: Built-in Variables321857
+Node: User-modified322947
+Ref: User-modified-Footnote-1330533
+Node: Auto-set330595
+Ref: Auto-set-Footnote-1338618
+Node: ARGC and ARGV338823
+Node: Arrays342685
+Node: Array Intro344615
+Node: Reference to Elements348885
+Node: Assigning Elements350770
+Node: Array Example351232
+Node: Scanning an Array352955
+Node: Delete355279
+Ref: Delete-Footnote-1357729
+Node: Numeric Array Subscripts357786
+Node: Uninitialized Subscripts360065
+Node: Multi-dimensional361687
+Node: Multi-scanning364734
+Node: Array Sorting366406
+Node: Functions369220
+Node: Built-in369954
+Node: Calling Built-in370937
+Node: Numeric Functions372912
+Ref: Numeric Functions-Footnote-1376652
+Ref: Numeric Functions-Footnote-2376978
+Node: String Functions377247
+Ref: String Functions-Footnote-1393843
+Ref: String Functions-Footnote-2394002
+Node: Gory Details394089
+Ref: Gory Details-Footnote-1400676
+Ref: Gory Details-Footnote-2400727
+Node: I/O Functions400934
+Ref: I/O Functions-Footnote-1407611
+Node: Time Functions407702
+Ref: Time Functions-Footnote-1418476
+Ref: Time Functions-Footnote-2418544
+Ref: Time Functions-Footnote-3418702
+Ref: Time Functions-Footnote-4418813
+Ref: Time Functions-Footnote-5418938
+Ref: Time Functions-Footnote-6419197
+Node: Bitwise Functions419459
+Ref: Bitwise Functions-Footnote-1424157
+Node: I18N Functions424341
+Node: User-defined426085
+Node: Definition Syntax426861
+Node: Function Example431253
+Node: Function Caveats433894
+Node: Return Statement437794
+Node: Dynamic Typing440452
+Node: Internationalization441190
+Node: I18N and L10N442608
+Node: Explaining gettext443317
+Ref: Explaining gettext-Footnote-1448253
+Ref: Explaining gettext-Footnote-2448492
+Node: Programmer i18n448661
+Node: Translator i18n453007
+Node: String Extraction453792
+Ref: String Extraction-Footnote-1454794
+Node: Printf Ordering454920
+Ref: Printf Ordering-Footnote-1457711
+Node: I18N Portability457775
+Ref: I18N Portability-Footnote-1460213
+Node: I18N Example460276
+Ref: I18N Example-Footnote-1462913
+Node: Gawk I18N462985
+Node: Advanced Features463807
+Node: Nondecimal Data465239
+Node: Two-way I/O466846
+Ref: Two-way I/O-Footnote-1471508
+Node: TCP/IP Networking471585
+Node: Portal Files474048
+Node: Profiling474711
+Node: Invoking Gawk482337
+Node: Command Line483514
+Node: Options484314
+Ref: Options-Footnote-1496204
+Node: Other Arguments496229
+Node: AWKPATH Variable498981
+Ref: AWKPATH Variable-Footnote-1501764
+Node: Obsolete502024
+Node: Undocumented503105
+Node: Known Bugs503357
+Node: Library Functions503976
+Ref: Library Functions-Footnote-1507160
+Node: Library Names507331
+Ref: Library Names-Footnote-1510940
+Ref: Library Names-Footnote-2511159
+Node: General Functions511245
+Node: Nextfile Function512181
+Node: Assert Function516646
+Node: Round Function519977
+Node: Cliff Random Function521536
+Ref: Cliff Random Function-Footnote-1522519
+Node: Ordinal Functions522590
+Ref: Ordinal Functions-Footnote-1525664
+Node: Join Function525880
+Ref: Join Function-Footnote-1527684
+Node: Gettimeofday Function527884
+Node: Data File Management531662
+Node: Filetrans Function532223
+Node: Rewind Function535774
+Node: File Checking537398
+Node: Ignoring Assigns538444
+Node: Getopt Function540028
+Ref: Getopt Function-Footnote-1551177
+Node: Passwd Functions551378
+Ref: Passwd Functions-Footnote-1560100
+Node: Group Functions560188
+Node: Sample Programs568287
+Node: Running Examples569017
+Node: Clones569788
+Node: Cut Program570913
+Node: Egrep Program580778
+Ref: Egrep Program-Footnote-1588643
+Node: Id Program588753
+Node: Split Program592438
+Node: Tee Program595947
+Node: Uniq Program598618
+Node: Wc Program606128
+Ref: Wc Program-Footnote-1610442
+Node: Miscellaneous Programs610664
+Node: Dupword Program611653
+Node: Alarm Program613704
+Node: Translate Program618328
+Ref: Translate Program-Footnote-1622644
+Ref: Translate Program-Footnote-2622881
+Node: Labels Program623015
+Ref: Labels Program-Footnote-1626372
+Node: Word Sorting626456
+Node: History Sorting630759
+Node: Extract Program632628
+Node: Simple Sed640210
+Node: Igawk Program643407
+Ref: Igawk Program-Footnote-1656434
+Node: Language History656572
+Node: V7/SVR3.1657939
+Node: SVR4660534
+Node: POSIX662181
+Node: BTL663969
+Node: POSIX/GNU665786
+Node: Contributors674410
+Node: Installation677662
+Node: Gawk Distribution678641
+Node: Getting679141
+Node: Extracting680387
+Node: Distribution contents681766
+Node: Unix Installation687363
+Node: Quick Installation687949
+Node: Additional Configuration Options689696
+Node: Configuration Philosophy690791
+Node: Non-Unix Installation693174
+Node: Amiga Installation693756
+Node: BeOS Installation694901
+Node: PC Installation696073
+Node: PC Binary Installation697206
+Node: PC Compiling699060
+Node: PC Using703514
+Node: Cygwin708232
+Ref: Cygwin-Footnote-1709245
+Node: VMS Installation709277
+Node: VMS Compilation709796
+Node: VMS Installation Details711385
+Node: VMS Running713002
+Node: VMS POSIX714586
+Node: Unsupported715850
+Node: Atari Installation716248
+Node: Atari Compiling717569
+Node: Atari Using719498
+Node: Tandem Installation722362
+Node: Bugs724168
+Node: Other Versions727453
+Ref: Other Versions-Footnote-1731039
+Node: Notes731081
+Node: Compatibility Mode731754
+Node: Additions732596
+Node: Adding Code733368
+Node: New Ports739410
+Node: Dynamic Extensions743513
+Node: Internals744529
+Node: Sample Library750865
+Node: Internal File Description751515
+Node: Internal File Ops755267
+Ref: Internal File Ops-Footnote-1760683
+Node: Using Internal File Ops760831
+Node: Future Extensions762852
+Node: Basic Concepts767195
+Node: Basic High Level767933
+Ref: Basic High Level-Footnote-1772094
+Node: Basic Data Typing772288
+Node: Floating Point Issues776778
+Ref: Floating Point Issues-Footnote-1780701
+Ref: Floating Point Issues-Footnote-2780753
+Node: Glossary780862
+Node: Copying805171
+Node: GNU Free Documentation License824368
+Node: Index844250

End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index 808ef6e8..e5f50413 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -20,9 +20,9 @@
@c applies to and all the info about who's publishing this edition
@c These apply across the board.
-@set UPDATE-MONTH March, 2001
+@set UPDATE-MONTH April, 2002
@set VERSION 3.1
-@set PATCHLEVEL 0
+@set PATCHLEVEL 1
@set FSF
@@ -68,6 +68,7 @@
@set DF data file
@set DDF Data File
@set PVERSION version
+@set CTL Ctrl
@ignore
Some comments on the layout for TeX.
@@ -96,19 +97,13 @@ Some comments on the layout for TeX.
@finalout
@end iftex
-@c Comment out the "smallbook" for technical review. Saves
-@c considerable paper. Remember to turn it back on *before*
-@c starting the page-breaking work.
-@smallbook
-
-@ifinfo
-This file documents @command{awk}, a program that you can use to select
-particular records in a file and perform operations upon them.
+@copying
+Copyright @copyright{} 1989, 1991, 1992, 1993, 1996, 1997, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
+@sp 2
This is Edition @value{EDITION} of @cite{@value{TITLE}: @value{SUBTITLE}},
-for the @value{VERSION}.@value{PATCHLEVEL} version of the GNU implementation of AWK.
-
-Copyright (C) 1989, 1991, 1992, 1993, 1996-2001 Free Software Foundation, Inc.
+for the @value{VERSION}.@value{PATCHLEVEL} (or later) version of the GNU
+implementation of AWK.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
@@ -127,11 +122,21 @@ texts being (a) (see below), and with the Back-Cover Texts being (b)
software. Copies published by the Free Software Foundation raise
funds for GNU development.''
@end enumerate
-@end ifinfo
+@end copying
+
+@c Comment out the "smallbook" for technical review. Saves
+@c considerable paper. Remember to turn it back on *before*
+@c starting the page-breaking work.
+
+@c 4/2002: Karl Berry recommends commenting out this and the
+@c `@setchapternewpage odd', and letting users use `texi2dvi -t'
+@c if they want to waste paper.
+@c @smallbook
+
@c Uncomment this for the release. Leaving it off saves paper
@c during editing and review.
-@setchapternewpage odd
+@c @setchapternewpage odd
@titlepage
@title @value{TITLE}
@@ -166,14 +171,6 @@ Corporation. @*
Registered Trademark of Paramount Pictures Corporation. @*
@c sorry, i couldn't resist
@sp 3
-Copyright @copyright{} 1989, 1991, 1992, 1993, 1996-2001 Free Software Foundation, Inc.
-@sp 2
-
-This is Edition @value{EDITION} of @cite{@value{TITLE}: @value{SUBTITLE}},
-for the @value{VERSION}.@value{PATCHLEVEL} (or later) version of the GNU
-implementation of AWK.
-
-@sp 2
Published by:
@sp 1
@@ -187,24 +184,8 @@ URL: @uref{http://www.gnu.org/} @*
@c This one is correct for gawk 3.1.0 from the FSF
ISBN 1-882114-28-0 @*
-
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with the
-Invariant Sections being ``GNU General Public License'', the Front-Cover
-texts being (a) (see below), and with the Back-Cover Texts being (b)
-(see below). A copy of the license is included in the section entitled
-``GNU Free Documentation License''.
-
-@enumerate a
-@item
-``A GNU Manual''
-
-@item
-``You have freedom to copy and modify this GNU Manual, like GNU
-software. Copies published by the Free Software Foundation raise
-funds for GNU development.''
-@end enumerate
+@sp 2
+@insertcopying
@sp 2
Cover art by Etienne Suvasa.
@end titlepage
@@ -237,7 +218,7 @@ Cover art by Etienne Suvasa.
@oddheading @| @| @strong{@thischapter}@ @ @ @thispage
@end iftex
-@ifinfo
+@ifnottex
@node Top, Foreword, (dir), (dir)
@top General Introduction
@c Preface node should come right after the Top
@@ -247,11 +228,9 @@ Cover art by Etienne Suvasa.
This file documents @command{awk}, a program that you can use to select
particular records in a file and perform operations upon them.
-This is Edition @value{EDITION} of @cite{@value{TITLE}: @value{SUBTITLE}},
-for the @value{VERSION}.@value{PATCHLEVEL} version of the GNU implementation
-of AWK.
+@insertcopying
-@end ifinfo
+@end ifnottex
@menu
* Foreword:: Some nice words about this
@@ -309,7 +288,7 @@ of AWK.
* Acknowledgments:: Acknowledgments.
* Running gawk:: How to run @command{gawk} programs;
includes command-line syntax.
-* One-shot:: Running a short throw-away @command{awk}
+* One-shot:: Running a short throwaway @command{awk}
program.
* Read Terminal:: Using no input files (input from terminal
instead).
@@ -333,7 +312,7 @@ of AWK.
* When:: When to use @command{gawk} and when to use
other things.
* Regexp Usage:: How to Use Regular Expressions.
-* Escape Sequences:: How to write non-printing characters.
+* Escape Sequences:: How to write nonprinting characters.
* Regexp Operators:: Regular Expression Operators.
* Character Lists:: What can go between @samp{[...]}.
* GNU Regexp Operators:: Operators specific to GNU software.
@@ -342,7 +321,7 @@ of AWK.
* Computed Regexps:: Using Dynamic Regexps.
* Records:: Controlling how data is split into records.
* Fields:: An introduction to fields.
-* Non-Constant Fields:: Non-constant Field Numbers.
+* Nonconstant Fields:: Nonconstant Field Numbers.
* Changing Fields:: Changing the Contents of a Field.
* Field Separators:: The field separator and how to change it.
* Regexp Field Splitting:: Using regexps as the field separator.
@@ -390,7 +369,7 @@ of AWK.
* Close Files And Pipes:: Closing Input and Output Files and Pipes.
* Constants:: String, numeric and regexp constants.
* Scalar Constants:: Numeric and string constants.
-* Non-decimal-numbers:: What are octal and hex numbers.
+* Nondecimal-numbers:: What are octal and hex numbers.
* Regexp Constants:: Regular Expression constants.
* Using Constant Regexps:: When and how to use a regexp constant.
* Variables:: Variables give names to values for later
@@ -503,7 +482,7 @@ of AWK.
* I18N Portability:: @command{awk}-level portability issues.
* I18N Example:: A simple i18n example.
* Gawk I18N:: @command{gawk} is also internationalized.
-* Non-decimal Data:: Allowing non-decimal input data.
+* Nondecimal Data:: Allowing nondecimal input data.
* Two-way I/O:: Two-way communications with another
process.
* TCP/IP Networking:: Using @command{gawk} for network
@@ -595,6 +574,8 @@ of AWK.
and OS/2.
* PC Using:: Running @command{gawk} on MS-DOS, Win32 and
OS/2.
+* Cygwin:: Building and running @command{gawk} for
+ Cygwin.
* VMS Installation:: Installing @command{gawk} on VMS.
* VMS Compilation:: How to compile @command{gawk} under VMS.
* VMS Installation Details:: How to install @command{gawk} under VMS.
@@ -774,7 +755,7 @@ when working with text files.
You might want to extract certain lines and discard the rest.
Or you may need to make changes wherever certain patterns appear,
but leave the rest of the file alone.
-Writing single-use programs for these tasks in languages such as C, C++ or Pascal
+Writing single-use programs for these tasks in languages such as C, C++, or Pascal
is time-consuming and inconvenient.
Such jobs are often easier with @command{awk}.
The @command{awk} utility interprets a special-purpose programming language
@@ -788,8 +769,12 @@ properly written @command{awk} programs should work with @command{gawk}.
Thus, we usually don't distinguish between @command{gawk} and other
@command{awk} implementations.
-@cindex uses of @command{awk}
-@cindex applications of @command{awk}
+@cindex @command{awk}, POSIX and, See Also POSIX @command{awk}
+@cindex @command{awk}, POSIX and
+@cindex POSIX, @command{awk} and
+@cindex @command{gawk}, @command{awk} and
+@cindex @command{awk}, @command{gawk} and
+@cindex @command{awk}, uses for
Using @command{awk} allows you to:
@itemize @bullet
@@ -807,10 +792,12 @@ Produce indexes and perform other document preparation tasks
@item
Experiment with algorithms that you can adapt later to other computer
-languages.
+languages
@end itemize
-@cindex uses of @command{gawk}
+@cindex @command{awk}, See Also @command{gawk}
+@cindex @command{gawk}, See Also @command{awk}
+@cindex @command{gawk}, uses for
In addition,
@command{gawk}
provides facilities that make it easy to:
@@ -823,26 +810,27 @@ Extract bits and pieces of data for processing
Sort data
@item
-Perform simple network communications.
+Perform simple network communications
@end itemize
This @value{DOCUMENT} teaches you about the @command{awk} language and
how you can use it effectively. You should already be familiar with basic
system commands, such as @command{cat} and @command{ls},@footnote{These commands
-are available on POSIX-compliant systems, as well as on traditional Unix
-based systems. If you are using some other operating system, you still need to
+are available on POSIX-compliant systems, as well as on traditional
+Unix-based systems. If you are using some other operating system, you still need to
be familiar with the ideas of I/O redirection and pipes.} as well as basic shell
-facilities, such as Input/Output (I/O) redirection and pipes.
+facilities, such as input/output (I/O) redirection and pipes.
+@cindex GNU @command{awk}, See @command{gawk}
Implementations of the @command{awk} language are available for many
different computing environments. This @value{DOCUMENT}, while describing
the @command{awk} language in general, also describes the particular
implementation of @command{awk} called @command{gawk} (which stands for
``GNU awk''). @command{gawk} runs on a broad range of Unix systems,
-ranging from 80386 PC-based computers, up through large-scale systems,
+ranging from 80386 PC-based computers up through large-scale systems,
such as Crays. @command{gawk} has also been ported to Mac OS X,
-MS-DOS, Microsoft Windows (all versions) and OS/2 PC's, Atari and Amiga
-micro-computers, BeOS, Tandem D20, and VMS.
+MS-DOS, Microsoft Windows (all versions) and OS/2 PCs, Atari and Amiga
+microcomputers, BeOS, Tandem D20, and VMS.
@menu
* History:: The history of @command{gawk} and
@@ -876,13 +864,10 @@ After eight years, add another part @code{egrep} and two
more parts C. Document very well and release.
@end quotation
-@cindex acronym
-@cindex history of @command{awk}
@cindex Aho, Alfred
@cindex Weinberger, Peter
@cindex Kernighan, Brian
-@cindex old @command{awk}
-@cindex new @command{awk}
+@cindex @command{awk}, history of
The name @command{awk} comes from the initials of its designers: Alfred V.@:
Aho, Peter J.@: Weinberger and Brian W.@: Kernighan. The original version of
@command{awk} was written in 1977 at AT&T Bell Laboratories.
@@ -925,24 +910,26 @@ for a complete list of those who made important contributions to @command{gawk}.
@node Names, This Manual, History, Preface
@section A Rose by Any Other Name
-@cindex old @command{awk} vs. new @command{awk}
-@cindex new @command{awk} vs. old @command{awk}
+@cindex @command{awk}, new vs. old
The @command{awk} language has evolved over the years. Full details are
provided in @ref{Language History, ,The Evolution of the @command{awk} Language}.
The language described in this @value{DOCUMENT}
is often referred to as ``new @command{awk}'' (@command{nawk}).
+@cindex @command{awk}, versions of
Because of this, many systems have multiple
versions of @command{awk}.
Some systems have an @command{awk} utility that implements the
original version of the @command{awk} language and a @command{nawk} utility
for the new
version.
-Others have an @command{oawk} for the ``old @command{awk}''
+Others have an @command{oawk} version for the ``old @command{awk}''
language and plain @command{awk} for the new one. Still others only
have one version, which is usually the new one.@footnote{Often, these systems
use @command{gawk} for their @command{awk} implementation!}
+@cindex @command{nawk} utility
+@cindex @command{oawk} utility
All in all, this makes it difficult for you to know which version of
@command{awk} you should run when writing your programs. The best advice
I can give here is to check your local documentation. Look for @command{awk},
@@ -959,44 +946,34 @@ specific to the GNU implementation, we use the term @command{gawk}.
@node This Manual, Conventions, Names, Preface
@section Using This Book
-@cindex book, using this
-@cindex using this book
-@cindex language, @command{awk}
-@cindex program, @command{awk}
-@ignore
-@cindex @command{awk} language
-@cindex @command{awk} program
-@end ignore
-@cindex Brandon, Dick
-@cindex sex, comparisons with
-@quotation
-@i{Documentation is like sex: when it is good, it is very, very good; and
-when it is bad, it is better than nothing.}@*
-Dick Brandon
-@end quotation
+@cindex @command{awk}, terms describing
The term @command{awk} refers to a particular program as well as to the language you
use to tell this program what to do. When we need to be careful, we call
-the program ``the @command{awk} utility'' and the language ``the @command{awk}
-language.''
+the language ``the @command{awk} language,''
+and the program ``the @command{awk} utility.''
This @value{DOCUMENT} explains
both the @command{awk} language and how to run the @command{awk} utility.
The term @dfn{@command{awk} program} refers to a program written by you in
the @command{awk} programming language.
+@cindex @command{gawk}, @command{awk} and
+@cindex @command{awk}, @command{gawk} and
+@cindex POSIX @command{awk}
Primarily, this @value{DOCUMENT} explains the features of @command{awk},
as defined in the POSIX standard. It does so in the context of the
@command{gawk} implementation. While doing so, it also
attempts to describe important differences between @command{gawk}
and other @command{awk} implementations.@footnote{All such differences
-appear in the index under the heading ``differences between @command{gawk} and
-@command{awk}.''} Finally, any @command{gawk} features that are not in
+appear in the index under the
+entry ``differences in @command{awk} and @command{gawk}.''}
+Finally, any @command{gawk} features that are not in
the POSIX standard for @command{awk} are noted.
@ifnotinfo
This @value{DOCUMENT} has the difficult task of being both a tutorial and a reference.
If you are a novice, feel free to skip over details that seem too complex.
-You should also ignore the many cross references; they are for the
+You should also ignore the many cross-references; they are for the
expert user and for the online Info version of the document.
@end ifnotinfo
@@ -1006,7 +983,7 @@ as @strong{Advanced Notes}
scattered throughout the @value{DOCUMENT}.
They add a more complete explanation of points that are relevant, but not likely
to be of interest on first reading.
-All appear in the index, under the heading ``advanced notes.''
+All appear in the index, under the heading ``advanced features.''
Most of the time, the examples use complete @command{awk} programs.
In some of the more advanced sections, only the part of the @command{awk}
@@ -1054,7 +1031,7 @@ sorting arrays in @command{gawk}.
@ref{Functions},
describes the built-in functions @command{awk} and
-@command{gawk} provide for you, as well as how to define
+@command{gawk} provide, as well as how to define
your own functions.
@ref{Internationalization, ,Internationalization with @command{gawk}},
@@ -1076,12 +1053,12 @@ program source files.
@ref{Library Functions, ,A Library of @command{awk} Functions}, and
@ref{Sample Programs, ,Practical @command{awk} Programs},
provide many sample @command{awk} programs.
-Reading them allows you to see @command{awk} being used
-for solving real problems.
+Reading them allows you to see @command{awk}
+solving real problems.
@ref{Language History, ,The Evolution of the @command{awk} Language},
-describes how the @command{awk} language has evolved since it was
-first released to present. It also describes how @command{gawk}
+describes how the @command{awk} language has evolved since
+first release to present. It also describes how @command{gawk}
has acquired features over time.
@ref{Installation, ,Installing @command{gawk}},
@@ -1101,17 +1078,17 @@ future directions for @command{gawk} development.
provides some very cursory background material for those who
are completely unfamiliar with computer programming.
Also centralized there is a discussion of some of the issues
-involved in using floating-point numbers.
+surrounding floating-point numbers.
The
@ref{Glossary},
defines most, if not all, the significant terms used
throughout the book.
-If you find terms that you aren't familiar with, try looking them up.
+If you find terms that you aren't familiar with, try looking them up here.
@ref{Copying, ,GNU General Public License}, and
@ref{GNU Free Documentation License},
-present the licenses that cover the @command{gawk} source code,
+present the licenses that cover the @command{gawk} source code
and this @value{DOCUMENT}, respectively.
@node Conventions, Manual History, This Manual, Preface
@@ -1157,7 +1134,7 @@ font as the previous occurrence of ``definition'' in this sentence.
Characters that you type at the keyboard look @kbd{like this}. In particular,
there are special characters called ``control characters.'' These are
characters that you type by holding down both the @kbd{CONTROL} key and
-another key, at the same time. For example, a @kbd{Ctrl-d} is typed
+another key, at the same time. For example, a @kbd{@value{CTL}-d} is typed
by first pressing and holding the @kbd{CONTROL} key, next
pressing the @kbd{d} key and finally releasing both keys.
@@ -1170,7 +1147,7 @@ you illuminate, there's always a smaller but darker one.}@*
Brian Kernighan
@end quotation
-@cindex d.c., see ``dark corner''
+@cindex d.c., See dark corner
@cindex dark corner
Until the POSIX standard (and @cite{The Gawk Manual}),
many features of @command{awk} were either poorly documented or not
@@ -1191,26 +1168,18 @@ is, by definition, something that is incomplete.
@node Manual History, How To Contribute, Conventions, Preface
@unnumberedsec The GNU Project and This Book
-@cindex Torvalds, Linus
-@cindex sex, comparisons with
-@quotation
-@i{Software is like sex: it's better when it's free.}@*
-Linus Torvalds
-@end quotation
-@cindex FSF
-@cindex Free Software Foundation
+@cindex FSF (Free Software Foundation)
+@cindex Free Software Foundation (FSF)
@cindex Stallman, Richard
-The Free Software Foundation (FSF) is a non-profit organization dedicated
+The Free Software Foundation (FSF) is a nonprofit organization dedicated
to the production and distribution of freely distributable software.
It was founded by Richard M.@: Stallman, the author of the original
Emacs editor. GNU Emacs is the most widely used version of Emacs today.
@cindex GNU Project
-@cindex GPL
-@cindex General Public License
-@cindex GNU General Public License
-@cindex online documentation
+@cindex GPL (General Public License)
+@cindex General Public License, See GPL
@cindex documentation, online
The GNU@footnote{GNU stands for ``GNU's not Unix.''}
Project is an ongoing effort on the part of the Free Software
@@ -1240,10 +1209,8 @@ stage of development.
@cindex Linux
@cindex GNU/Linux
-@cindex BSD-based operating systems
-@cindex NetBSD
-@cindex FreeBSD
-@cindex OpenBSD
+@cindex operating systems, BSD-based
+@cindex Alpha (DEC)
Until the GNU operating system is more fully developed, you should
consider using GNU/Linux, a freely distributable, Unix-like operating
system for Intel 80386, DEC Alpha, Sun SPARC, IBM S/390, and other
@@ -1260,12 +1227,12 @@ bundled on CD-ROMs with books about Linux.
of @command{gawk} for their versions of @command{awk}.)
@ifnotinfo
-The @value{DOCUMENT} you are reading now is actually free---at least, the
-information in it is free to anyone. The machine readable
+The @value{DOCUMENT} you are reading is actually free---at least, the
+information in it is free to anyone. The machine-readable
source code for the @value{DOCUMENT} comes with @command{gawk}; anyone
may take this @value{DOCUMENT} to a copying machine and make as many
-copies of it as they like. (Take a moment to check the Free Documentation
-License; see @ref{GNU Free Documentation License}.)
+copies as they like. (Take a moment to check the Free Documentation
+License in @ref{GNU Free Documentation License}.)
Although you could just print it out yourself, bound books are much
easier to read and use. Furthermore,
@@ -1384,7 +1351,7 @@ would otherwise have escaped us.
@cindex Stallman, Richard
I would like to acknowledge Richard M.@: Stallman, for his vision of a
better world and for his courage in founding the FSF and starting the
-GNU project.
+GNU Project.
The following people (in alphabetical order)
provided helpful comments on various
@@ -1394,7 +1361,7 @@ Nelson H.F. Beebe,
Karl Berry,
Dr.@: Michael Brennan,
Rich Burridge,
-Claire Coutier,
+Claire Cloutier,
Diane Close,
Scott Deifik,
Christopher (``Topher'') Eliot,
@@ -1411,7 +1378,7 @@ Chuck Toporek.
@cindex Berry, Karl
@cindex Chassell, Robert J.@:
-@cindex Texinfo
+@c @cindex Texinfo
Robert J.@: Chassell provided much valuable advice on
the use of Texinfo.
He also deserves special thanks for
@@ -1442,14 +1409,17 @@ working with him on this project was a significant pleasure.
@cindex Drepper, Ulrich
@cindex GNITS mailing list
+@cindex mailing list, GNITS
The intrepid members of the GNITS mailing list, and most notably Ulrich
Drepper, provided invaluable help and feedback for the design of the
internationalization features.
@cindex Beebe, Nelson
@cindex Brown, Martin
+@cindex Buening, Andreas
@cindex Deifik, Scott
@cindex Hankerson, Darrel
+@cindex Hasegawa, Isamu
@cindex Jaegermann, Michal
@cindex Kahrs, J@"urgen
@cindex Rankin, Pat
@@ -1457,15 +1427,17 @@ internationalization features.
@cindex Zaretskii, Eli
Nelson Beebe,
Martin Brown,
+Andreas Buening,
Scott Deifik,
Darrel Hankerson,
+Isamu Hasegawa,
Michal Jaegermann,
J@"urgen Kahrs,
Pat Rankin,
Kai Uwe Rommel,
and Eli Zaretskii
(in alphabetical order)
-are long-time members of the
+make up the
@command{gawk} ``crack portability team.'' Without their hard work and
help, @command{gawk} would not be nearly the fine program it is today. It
has been and continues to be a pleasure working with this team of fine
@@ -1487,7 +1459,7 @@ significant editorial help for this @value{DOCUMENT} for the
@cindex Robbins, Harry
@cindex G-d
I must thank my wonderful wife, Miriam, for her patience through
-the many versions of this project, for her proof-reading,
+the many versions of this project, for her proofreading,
and for sharing me with the computer.
I would like to thank my parents for their love, and for the grace with
which they raised and educated me.
@@ -1554,10 +1526,11 @@ and @command{gawk}. It contains the following chapters:
@node Getting Started, Regexp, Preface, Top
@chapter Getting Started with @command{awk}
-@cindex script, definition of
-@cindex rule, definition of
-@cindex program, definition of
-@cindex basic function of @command{awk}
+@c @cindex script, definition of
+@c @cindex rule, definition of
+@c @cindex program, definition of
+@c @cindex basic function of @command{awk}
+@cindex @command{awk}, function of
The basic function of @command{awk} is to search files for lines (or other
units of text) that contain certain patterns. When a line matches one
@@ -1565,10 +1538,10 @@ of the patterns, @command{awk} performs specified actions on that line.
@command{awk} keeps processing input lines in this way until it reaches
the end of the input files.
-@cindex data-driven languages
-@cindex procedural languages
-@cindex language, data-driven
-@cindex language, procedural
+@cindex @command{awk}, uses for
+@c comma here is NOT for secondary
+@cindex programming languages, data-driven vs. procedural
+@cindex @command{awk} programs
Programs in @command{awk} are different from programs in most other languages,
because @command{awk} programs are @dfn{data-driven}; that is, you describe
the data you want to work with and then what to do when you find it.
@@ -1577,7 +1550,7 @@ detail, every step the program is to take. When working with procedural
languages, it is usually much
harder to clearly describe the data your program will process.
For this reason, @command{awk} programs are often refreshingly easy to
-write and read.
+read and write.
@cindex program, definition of
@cindex rule, definition of
@@ -1619,8 +1592,7 @@ program looks like this:
@node Running gawk, Sample Data Files, Getting Started, Getting Started
@section How to Run @command{awk} Programs
-@cindex command-line formats
-@cindex running @command{awk} programs
+@cindex @command{awk} programs, running
There are several ways to run an @command{awk} program. If the program is
short, it is easiest to include it in the command that runs @command{awk},
like this:
@@ -1629,6 +1601,7 @@ like this:
awk '@var{program}' @var{input-file1} @var{input-file2} @dots{}
@end example
+@cindex command line, formats
When the program is long, it is usually more convenient to put it in a file
and run it with a command like this:
@@ -1640,7 +1613,7 @@ This @value{SECTION} discusses both mechanisms, along with several
variations of each.
@menu
-* One-shot:: Running a short throw-away @command{awk}
+* One-shot:: Running a short throwaway @command{awk}
program.
* Read Terminal:: Using no input files (input from terminal
instead).
@@ -1653,7 +1626,7 @@ variations of each.
@end menu
@node One-shot, Read Terminal, Running gawk, Running gawk
-@subsection One-Shot Throw-Away @command{awk} Programs
+@subsection One-Shot Throwaway @command{awk} Programs
Once you are familiar with @command{awk}, you will often type in simple
programs the moment you want to use them. Then you can write the
@@ -1667,7 +1640,8 @@ awk '@var{program}' @var{input-file1} @var{input-file2} @dots{}
where @var{program} consists of a series of @var{patterns} and
@var{actions}, as described earlier.
-@cindex single quotes, why needed
+@cindex single quote (@code{'})
+@cindex @code{'} (single quote)
This command format instructs the @dfn{shell}, or command interpreter,
to start @command{awk} and use the @var{program} to process records in the
input file(s). There are single quotes around @var{program} so
@@ -1676,6 +1650,8 @@ characters. The quotes also cause the shell to treat all of @var{program} as
a single argument for @command{awk}, and allow @var{program} to be more
than one line long.
+@cindex shells, scripts
+@cindex @command{awk} programs, running, from shell scripts
This format is also useful for running short or medium-sized @command{awk}
programs from shell scripts, because it avoids the need for a separate
file for the @command{awk} program. A self-contained shell script is more
@@ -1710,6 +1686,7 @@ egrep foo @var{files} @dots{}
@cindex standard input
@cindex input, standard
+@cindex input files, running @command{awk} without
You can also run @command{awk} without any input files. If you type the
following command line:
@@ -1720,22 +1697,28 @@ awk '@var{program}'
@noindent
@command{awk} applies the @var{program} to the @dfn{standard input},
which usually means whatever you type on the terminal. This continues
-until you indicate end-of-file by typing @kbd{Ctrl-d}.
+until you indicate end-of-file by typing @kbd{@value{CTL}-d}.
(On other operating systems, the end-of-file character may be different.
-For example, on OS/2 and MS-DOS, it is @kbd{Ctrl-z}.)
+For example, on OS/2 and MS-DOS, it is @kbd{@value{CTL}-z}.)
+@cindex files, input, See input files
+@cindex input files, running @command{awk} without
+@cindex @command{awk} programs, running, without input files
As an example, the following program prints a friendly piece of advice
(from Douglas Adams's @cite{The Hitchhiker's Guide to the Galaxy}),
-to keep you from worrying about the complexities of computer programming.
-(@code{BEGIN} is a feature we haven't discussed yet.):
+to keep you from worrying about the complexities of computer programming
+(@code{BEGIN} is a feature we haven't discussed yet):
@example
$ awk "BEGIN @{ print \"Don't Panic!\" @}"
@print{} Don't Panic!
@end example
-@cindex quoting, shell
-@cindex shell quoting
+@cindex quoting
+@cindex double quote (@code{"})
+@cindex @code{"} (double quote)
+@cindex @code{\} (backslash)
+@cindex backslash (@code{\})
This program does not read any input. The @samp{\} before each of the
inner double quotes is necessary because of the shell's quoting
rules---in particular because it mixes both single quotes and
@@ -1744,8 +1727,8 @@ quotes around the program text, double quotes are needed here in order to
put the single quote into the message.}
This next simple @command{awk} program
-emulates the @command{cat} utility; it copies whatever you type at the
-keyboard to its standard output. (Why this works is explained shortly.)
+emulates the @command{cat} utility; it copies whatever you type on the
+keyboard to its standard output (why this works is explained shortly).
@example
$ awk '@{ print @}'
@@ -1757,17 +1740,15 @@ Four score and seven years ago, ...
@print{} Four score and seven years ago, ...
What, me worry?
@print{} What, me worry?
-@kbd{Ctrl-d}
+@kbd{@value{CTL}-d}
@end example
@node Long, Executable Scripts, Read Terminal, Running gawk
@subsection Running Long Programs
-@cindex running long programs
-@cindex @code{-f} option
-@cindex command-line option, @code{-f}
-@cindex program file
-@cindex file, @command{awk} program
+@cindex @command{awk} programs, running
+@cindex @command{awk} programs, lengthy
+@cindex files, @command{awk} programs in
Sometimes your @command{awk} programs can be very long. In this case, it is
more convenient to put the program into a separate file. In order to tell
@command{awk} to use that file for its program, you type:
@@ -1776,6 +1757,9 @@ more convenient to put the program into a separate file. In order to tell
awk -f @var{source-file} @var{input-file1} @var{input-file2} @dots{}
@end example
+@cindex @code{-f} option
+@cindex command line, options
+@cindex options, command-line
The @option{-f} instructs the @command{awk} utility to get the @command{awk} program
from the file @var{source-file}. Any @value{FN} can be used for
@var{source-file}. For example, you could put the program:
@@ -1798,8 +1782,7 @@ does the same thing as this one:
awk "BEGIN @{ print \"Don't Panic!\" @}"
@end example
-@cindex quoting, shell
-@cindex shell quoting
+@cindex quoting
@noindent
This was explained earlier
(@pxref{Read Terminal, ,Running @command{awk} Without Input Files}).
@@ -1809,6 +1792,10 @@ special characters. Notice that in @file{advice}, the @command{awk}
program did not have single quotes around it. The quotes are only needed
for programs that are provided on the @command{awk} command line.
+@c STARTOFRANGE sq1x
+@cindex single quote (@code{'})
+@c STARTOFRANGE qs2x
+@cindex @code{'} (single quote)
If you want to identify your @command{awk} program files clearly as such,
you can add the extension @file{.awk} to the @value{FN}. This doesn't
affect the execution of the @command{awk} program but it does make
@@ -1816,11 +1803,12 @@ affect the execution of the @command{awk} program but it does make
@node Executable Scripts, Comments, Long, Running gawk
@subsection Executable @command{awk} Programs
-@cindex executable scripts
-@cindex scripts, executable
-@cindex self-contained programs
-@cindex program, self-contained
-@cindex @code{#!} (executable scripts)
+@cindex @command{awk} programs
+@cindex @code{#} (number sign), @code{#!} (executable scripts)
+@cindex number sign (@code{#}), @code{#!} (executable scripts)
+@cindex Unix, @command{awk} scripts and
+@cindex @code{#} (number sign), @code{#!} (executable scripts), portability issues with
+@cindex number sign (@code{#}), @code{#!} (executable scripts), portability issues with
Once you have learned @command{awk}, you may want to write self-contained
@command{awk} scripts, using the @samp{#!} script mechanism. You can do
@@ -1845,7 +1833,7 @@ to run and an optional initial command-line argument to pass to that
interpreter. The operating system then runs the interpreter with the given
argument and the full argument list of the executed program. The first argument
in the list is the full @value{FN} of the @command{awk} program. The rest of the
-argument list is either options to @command{awk}, or @value{DF}s,
+argument list contains either options to @command{awk}, or @value{DF}s,
or both.} as if you had
typed @samp{awk -f advice}:
@@ -1862,7 +1850,7 @@ written in @command{awk}.
@c fakenode --- for prepinfo
@subheading Advanced Notes: Portability Issues with @samp{#!}
-@cindex advanced notes
+@cindex portability, @code{#!} (executable scripts)
Some systems limit the length of the interpreter name to 32 characters.
Often, this can be dealt with by using a symbolic link.
@@ -1873,7 +1861,8 @@ treats the rest of the line as a single argument and passes it to @command{awk}.
Doing this leads to confusing behavior---most likely a usage diagnostic
of some sort from @command{awk}.
-@cindex portability issues
+@cindex @code{ARGC}/@code{ARGV} variables, portability and
+@cindex portability, @code{ARGV} variable
Finally,
the value of @code{ARGV[0]}
(@pxref{Built-in Variables})
@@ -1885,11 +1874,10 @@ to provide your script name.
@node Comments, Quoting, Executable Scripts, Running gawk
@subsection Comments in @command{awk} Programs
-@cindex @code{#} (comment)
-@cindex comments
-@cindex use of comments
-@cindex documenting @command{awk} programs
-@cindex programs, documenting
+@cindex @code{#} (number sign), commenting
+@cindex number sign (@code{#}), commenting
+@cindex commenting
+@cindex @command{awk} programs, documenting
A @dfn{comment} is some text that is included in a program for the sake
of human readers; it is not really an executable part of the program. Comments
@@ -1909,15 +1897,16 @@ For example, we could have put the following into @file{advice}:
BEGIN @{ print "Don't Panic!" @}
@end example
-You can put comment lines into keyboard-composed throw-away @command{awk}
+You can put comment lines into keyboard-composed throwaway @command{awk}
programs, but this usually isn't very useful; the purpose of a
comment is to help you or another person understand the program
when reading it at a later time.
-@cindex quoting, shell
-@cindex shell quoting
+@cindex quoting
+@cindex single quote (@code{'}), vs. apostrophe
+@cindex @code{'} (single quote), vs. apostrophe
@strong{Caution:} As mentioned in
-@ref{One-shot, ,One-Shot Throw-Away @command{awk} Programs},
+@ref{One-shot, ,One-Shot Throwaway @command{awk} Programs},
you can enclose small to medium programs in single quotes, in order to keep
your shell scripts self-contained. When doing so, @emph{don't} put
an apostrophe (i.e., a single quote) into a comment (or anywhere else
@@ -1933,7 +1922,7 @@ $ awk '@{ print "hello" @} # let's be cute'
@end example
The shell sees that the first two quotes match, and that
-a new quoted object begins at the end of the command-line.
+a new quoted object begins at the end of the command line.
It therefore prompts with the secondary prompt, waiting for more input.
With Unix @command{awk}, closing the quoted string produces this result:
@@ -1944,16 +1933,15 @@ $ awk '@{ print "hello" @} # let's be cute'
@error{} source line number 1
@end example
+@cindex @code{\} (backslash)
+@cindex backslash (@code{\})
Putting a backslash before the single quote in @samp{let's} wouldn't help,
since backslashes are not special inside single quotes.
The next @value{SUBSECTION} describes the shell's quoting rules.
@node Quoting, , Comments, Running gawk
-@subsection Shell Quoting Issues
-@c the indexing here is purposely different, until we
-@c get a way to mark the defining instance for an index entry
-@cindex quoting rules, shell
-@cindex shell quoting rules
+@subsection Shell-Quoting Issues
+@cindex quoting, rules for
For short to medium length @command{awk} programs, it is most convenient
to enter the program on the @command{awk} command line.
@@ -1965,7 +1953,8 @@ the shell prompt, or writing it as part of a larger shell script:
awk '@var{program text}' @var{input-file1} @var{input-file2} @dots{}
@end example
-@cindex @command{csh} utility
+@cindex shells, quoting, rules for
+@cindex Bourne shell, quoting rules for
Once you are working with the shell, it is helpful to have a basic
knowledge of shell quoting rules. The following rules apply only to
POSIX-compliant, Bourne-style shells (such as @command{bash}, the GNU Bourne-Again
@@ -1983,22 +1972,28 @@ that character. The shell removes the backslash and passes the quoted
character on to the command.
@item
+@cindex @code{\} (backslash)
+@cindex backslash (@code{\})
+@cindex single quote (@code{'})
+@cindex @code{'} (single quote)
Single quotes protect everything between the opening and closing quotes.
The shell does no interpretation of the quoted text, passing it on verbatim
to the command.
It is @emph{impossible} to embed a single quote inside single-quoted text.
Refer back to
@ref{Comments, ,Comments in @command{awk} Programs},
-for an example showing what happens if you try.
+for an example of what happens if you try.
@item
+@cindex double quote (@code{"})
+@cindex @code{"} (double quote)
Double quotes protect most things between the opening and closing quotes.
The shell does at least variable and command substitution on the quoted text.
Different shells may do additional kinds of processing on double-quoted text.
Since certain characters within double-quoted text are processed by the shell,
they must be @dfn{escaped} within the text. Of note are the characters
-@samp{$}, @samp{`}, @samp{\} and @samp{"}, all of which must be preceded by
+@samp{$}, @samp{`}, @samp{\}, and @samp{"}, all of which must be preceded by
a backslash within double-quoted text if they are to be passed on literally
to the program. (The leading backslash is stripped first.)
Thus, the example seen
@@ -2013,6 +2008,8 @@ $ awk "BEGIN @{ print \"Don't Panic!\" @}"
@print{} Don't Panic!
@end example
+@cindex single quote (@code{'}), with double quotes
+@cindex @code{'} (single quote), with double quotes
Note that the single quote is not special within double quotes.
@item
@@ -2026,6 +2023,7 @@ awk -F "" '@var{program}' @var{files} # correct
@end example
@noindent
+@cindex null strings, quoting and
Don't use this:
@example
@@ -2038,7 +2036,7 @@ as the value of @code{FS}, and the first @value{FN} as the text of the program!
This results in syntax errors at best, and confusing behavior at worst.
@end itemize
-@cindex shell quoting, tricks
+@cindex quoting, tricks for
Mixing single and double quotes is difficult. You have to resort
to shell quoting tricks, like this:
@@ -2070,6 +2068,8 @@ $ awk "BEGIN @{ print \"Here is a single quote <'>\" @}"
@end example
@noindent
+@c ENDOFRANGE sq1x
+@c ENDOFRANGE qs2x
This option is also painful, because double quotes, backslashes, and dollar signs
are very common in @command{awk} programs.
@@ -2081,17 +2081,16 @@ the shell won't be part of the picture, and you can say what you mean.
@section @value{DDF}s for the Examples
@c For gawk >= 3.2, update these data files. No-one has such slow modems!
-@cindex input file, sample
-@cindex sample input files
-@cindex @file{BBS-list} file
+@cindex input files, examples
+@cindex @code{BBS-list} file
Many of the examples in this @value{DOCUMENT} take their input from two sample
-@value{DF}s. The first, called @file{BBS-list}, represents a list of
+@value{DF}s. The first, @file{BBS-list}, represents a list of
computer bulletin board systems together with information about those systems.
The second @value{DF}, called @file{inventory-shipped}, contains
information about monthly shipments. In both files,
each line is considered to be one @dfn{record}.
-In the file @file{BBS-list}, each record contains the name of a computer
+In the @value{DF} @file{BBS-list}, each record contains the name of a computer
bulletin board, its phone number, the board's baud rate(s), and a code for
the number of hours it is operational. An @samp{A} in the last column
means the board operates 24 hours a day. A @samp{B} in the last
@@ -2120,8 +2119,8 @@ sabafoo 555-2127 1200/300 C
@c endfile
@end example
-@cindex @file{inventory-shipped} file
-The second @value{DF}, called @file{inventory-shipped}, represents
+@cindex @code{inventory-shipped} file
+The @value{DF} @file{inventory-shipped} represents
information about shipments during the year.
Each record contains the month, the number
of green crates shipped, the number of red boxes shipped, the number of
@@ -2173,10 +2172,10 @@ for an @command{awk} program that extracts these @value{DF}s from
@section Some Simple Examples
The following command runs a simple @command{awk} program that searches the
-input file @file{BBS-list} for the character string @samp{foo}. (A
-string of characters is usually called a @dfn{string}.
-The term @dfn{string} is based on similar usage in English, such
-as ``a string of pearls,'' or, ``a string of cars in a train.''):
+input file @file{BBS-list} for the character string @samp{foo} (a
+grouping of characters is usually called a @dfn{string};
+the term @dfn{string} is based on similar usage in English, such
+as ``a string of pearls,'' or ``a string of cars in a train''):
@example
awk '/foo/ @{ print $0 @}' BBS-list
@@ -2208,24 +2207,21 @@ $ awk '/foo/ @{ print $0 @}' BBS-list
@print{} sabafoo 555-2127 1200/300 C
@end example
-@cindex action, default
-@cindex pattern, default
-@cindex default action
-@cindex default pattern
+@cindex actions, default
+@cindex patterns, default
In an @command{awk} rule, either the pattern or the action can be omitted,
but not both. If the pattern is omitted, then the action is performed
for @emph{every} input line. If the action is omitted, the default
action is to print all lines that match the pattern.
-@cindex empty action
-@cindex action, empty
+@cindex actions, empty
Thus, we could leave out the action (the @code{print} statement and the curly
-braces) in the above example and the result would be the same: all
+braces) in the previous example and the result would be the same: all
lines matching the pattern @samp{foo} are printed. By comparison,
omitting the @code{print} statement but retaining the curly braces makes an
empty action that does nothing (i.e., no lines are printed).
-@cindex one-liners
+@cindex @command{awk} programs, one-line examples
Many practical @command{awk} programs are just a line or two. Following is a
collection of useful, short programs to get you started. Some of these
programs contain constructs that haven't been covered yet. (The description
@@ -2314,7 +2310,7 @@ awk -F: '@{ print $1 @}' /etc/passwd | sort
@end example
@item
-Count lines in a file:
+Count the lines in a file:
@example
awk 'END @{ print NR @}' data
@@ -2328,12 +2324,12 @@ awk 'NR % 2 == 0' data
@end example
If you use the expression @samp{NR % 2 == 1} instead,
-it would print the odd-numbered lines.
+the program would print the odd-numbered lines.
@end itemize
@node Two Rules, More Complex, Very Simple, Getting Started
@section An Example with Two Rules
-@cindex how @command{awk} works
+@cindex @command{awk} programs
The @command{awk} utility reads the input files one line at a
time. For each line, @command{awk} tries the patterns of each of the rules.
@@ -2345,7 +2341,7 @@ After processing all the rules that match the line (and perhaps there are none),
@command{awk} reads the next line. (However,
@pxref{Next Statement, ,The @code{next} Statement},
and also @pxref{Nextfile Statement, ,Using @command{gawk}'s @code{nextfile} Statement}).
-This continues until the end of the file is reached.
+This continues until the program reaches the end of the file.
For example, the following @command{awk} program contains two rules:
@example
@@ -2364,7 +2360,7 @@ This program prints every line that contains the string
strings, it is printed twice, once by each rule.
This is what happens if we run this program on our two sample @value{DF}s,
-@file{BBS-list} and @file{inventory-shipped}, as shown here:
+@file{BBS-list} and @file{inventory-shipped}:
@example
$ awk '/12/ @{ print $0 @}
@@ -2403,16 +2399,16 @@ ls -l | awk '$6 == "Nov" @{ sum += $5 @}
END @{ print sum @}'
@end example
-@cindex @command{csh} utility
-@cindex @command{csh}, backslash continuation
-@cindex backslash continuation, in @command{csh}
+@cindex @command{csh} utility, backslash continuation and
@cindex @command{ls} utility
+@cindex backslash (@code{\}), continuing lines and, in @command{csh}
+@cindex @code{\} (backslash), continuing lines and, in @command{csh}
This command prints the total number of bytes in all the files in the
current directory that were last modified in November (of any year).
@footnote{In the C shell (@command{csh}), you need to type
a semicolon and then a backslash at the end of the first line; see
@ref{Statements/Lines, ,@command{awk} Statements Versus Lines}, for an
-explanation as to why. In a POSIX-compliant shell, such as the Bourne
+explanation. In a POSIX-compliant shell, such as the Bourne
shell or @command{bash}, you can type the example as shown. If the command
@samp{echo $path} produces an empty output line, you are most likely
using a POSIX-compliant shell. Otherwise, you are probably using the
@@ -2433,16 +2429,17 @@ the file was last modified. Its output looks like this:
@end example
@noindent
+@cindex line continuations, with C shell
The first field contains read-write permissions, the second field contains
the number of links to the file, and the third field identifies the owner of
the file. The fourth field identifies the group of the file.
The fifth field contains the size of the file in bytes. The
-sixth, seventh and eighth fields contain the month, day, and time,
+sixth, seventh, and eighth fields contain the month, day, and time,
respectively, that the file was last modified. Finally, the ninth field
contains the name of the file.@footnote{On some
very old systems, you may need to use @samp{ls -lg} to get this output.}
-@cindex automatic initialization
+@c @cindex automatic initialization
@cindex initialization, automatic
The @samp{$6 == "Nov"} in our @command{awk} program is an expression that
tests whether the sixth field of the output from @w{@samp{ls -l}}
@@ -2462,13 +2459,13 @@ These more advanced @command{awk} techniques are covered in later sections
(@pxref{Action Overview, ,Actions}). Before you can move on to more
advanced @command{awk} programming, you have to know how @command{awk} interprets
your input and displays your output. By manipulating fields and using
-@code{print} statements, you can produce some very useful and impressive
-looking reports.
+@code{print} statements, you can produce some very useful and
+impressive-looking reports.
@node Statements/Lines, Other Features, More Complex, Getting Started
@section @command{awk} Statements Versus Lines
-@cindex line break
-@cindex newline
+@cindex line breaks
+@cindex newlines
Most often, each line in an @command{awk} program is a separate statement or
separate rule, like this:
@@ -2478,6 +2475,7 @@ awk '/12/ @{ print $0 @}
/21/ @{ print $0 @}' BBS-list inventory-shipped
@end example
+@cindex @command{gawk}, newlines in
However, @command{gawk} ignores newlines after any of the following
symbols and keywords:
@@ -2494,9 +2492,8 @@ Splitting lines after @samp{?} and @samp{:} is a minor @command{gawk}
extension; if @option{--posix} is specified
(@pxref{Options, , Command-Line Options}), then this extension is disabled.}
-@cindex backslash continuation
-@cindex continuation of lines
-@cindex line continuation
+@cindex @code{\} (backslash), continuing lines and
+@cindex backslash (@code{\}), continuing lines and
If you would like to split a single statement into two lines at a point
where a newline would terminate it, you can @dfn{continue} it by ending the
first line with a backslash character (@samp{\}). The backslash must be
@@ -2510,7 +2507,7 @@ awk '/This regular expression is too long, so continue it\
@end example
@noindent
-@cindex portability issues
+@cindex portability, backslash continuation and
We have generally not used backslash continuation in the sample programs
in this @value{DOCUMENT}. In @command{gawk}, there is no limit on the
length of a line, so backslash continuation is never strictly necessary;
@@ -2528,10 +2525,10 @@ lines in the middle of a regular expression or a string.
@c solaris 2.7 nawk does not. Solaris /usr/xpg4/bin/awk does though! sigh.
@cindex @command{csh} utility
-@cindex @command{csh}, backslash continuation
-@cindex backslash continuation, in @command{csh}
+@cindex backslash (@code{\}), continuing lines and, in @command{csh}
+@cindex @code{\} (backslash), continuing lines and, in @command{csh}
@strong{Caution:} @emph{Backslash continuation does not work as described
-above with the C shell.} It works for @command{awk} programs in files and
+with the C shell.} It works for @command{awk} programs in files and
for one-shot programs, @emph{provided} you are using a POSIX-compliant
shell, such as the Unix Bourne shell or @command{bash}. But the C shell behaves
differently! There, you must use two backslashes in a row, followed by
@@ -2563,10 +2560,11 @@ $ awk 'BEGIN @{
@command{awk} is a line-oriented language. Each rule's action has to
begin on the same line as the pattern. To have the pattern and action
on separate lines, you @emph{must} use backslash continuation; there
-is no other way.
+is no other option.
-@cindex backslash continuation, and comments
-@cindex comments and backslash continuation
+@cindex backslash (@code{\}), continuing lines and, comments and
+@cindex @code{\} (backslash), continuing lines and, comments and
+@cindex commenting, backslash continuation and
Another thing to keep in mind is that backslash continuation and
comments do not mix. As soon as @command{awk} sees the @samp{#} that
starts a comment, it ignores @emph{everything} on the rest of the
@@ -2586,7 +2584,9 @@ next line. However, the backslash-newline combination is never even
noticed because it is ``hidden'' inside the comment. Thus, the
@code{BEGIN} is noted as a syntax error.
-@cindex multiple statements on one line
+@cindex statements, multiple
+@cindex @code{;} (semicolon)
+@cindex semicolon (@code{;})
When @command{awk} statements within one rule are short, you might want to put
more than one of them on a line. This is accomplished by separating the statements
with a semicolon (@samp{;}).
@@ -2607,13 +2607,14 @@ within an action.
@node Other Features, When, Statements/Lines, Getting Started
@section Other Features of @command{awk}
+@cindex variables
The @command{awk} language provides a number of predefined, or
@dfn{built-in}, variables that your programs can use to get information
from @command{awk}. There are other variables your program can set
as well to control how @command{awk} processes your data.
In addition, @command{awk} provides a number of built-in functions for doing
-common computational and string related operations.
+common computational and string-related operations.
@command{gawk} provides built-in functions for working with timestamps,
performing bit manipulation, and for runtime string translation.
@@ -2625,8 +2626,7 @@ systematically in @ref{Built-in Variables}, and
@node When, , Other Features, Getting Started
@section When to Use @command{awk}
-@cindex uses of @command{awk}
-@cindex applications of @command{awk}
+@cindex @command{awk}, uses for
Now that you've seen some of what @command{awk} can do,
you might wonder how @command{awk} could be useful for you. By using
utility programs, advanced patterns, field separators, arithmetic
@@ -2645,10 +2645,11 @@ edit-compile-test-debug cycle of software development.
Complex programs have been written in @command{awk}, including a complete
retargetable assembler for eight-bit microprocessors (@pxref{Glossary}, for
-more information), and a microcode assembler for a special purpose Prolog
+more information), and a microcode assembler for a special-purpose Prolog
computer. However, @command{awk}'s capabilities are strained by tasks of
such complexity.
+@cindex @command{awk} programs, complex
If you find yourself writing @command{awk} scripts of more than, say, a few
hundred lines, you might consider using a different programming
language. Emacs Lisp is a good choice if you need sophisticated string
@@ -2662,16 +2663,17 @@ easier to maintain and usually run more efficiently.
@node Regexp, Reading Files, Getting Started, Top
@chapter Regular Expressions
-@cindex pattern, regular expressions
-@cindex regexp
-@cindex regular expression
-@cindex regular expressions as patterns
+@cindex regexp, See regular expressions
+@c STARTOFRANGE regexp
+@cindex regular expressions
A @dfn{regular expression}, or @dfn{regexp}, is a way of describing a
set of strings.
Because regular expressions are such a fundamental part of @command{awk}
programming, their format and use deserve a separate @value{CHAPTER}.
+@cindex forward slash (@code{/})
+@cindex @code{/} (forward slash)
A regular expression enclosed in slashes (@samp{/})
is an @command{awk} pattern that matches every input record whose text
belongs to that set.
@@ -2690,7 +2692,7 @@ regular expressions work, we will present more complicated instances.
@menu
* Regexp Usage:: How to Use Regular Expressions.
-* Escape Sequences:: How to write non-printing characters.
+* Escape Sequences:: How to write nonprinting characters.
* Regexp Operators:: Regular Expression Operators.
* Character Lists:: What can go between @samp{[...]}.
* GNU Regexp Operators:: Operators specific to GNU software.
@@ -2702,6 +2704,7 @@ regular expressions work, we will present more complicated instances.
@node Regexp Usage, Escape Sequences, Regexp, Regexp
@section How to Use Regular Expressions
+@cindex regular expressions, as patterns
A regular expression can be used as a pattern by enclosing it in
slashes. Then the regular expression is tested against the
entire text of each record. (Normally, it only needs
@@ -2717,12 +2720,21 @@ $ awk '/foo/ @{ print $2 @}' BBS-list
@print{} 555-2127
@end example
-@cindex regexp operators
-@cindex string-matching operators
+@cindex regular expressions, operators
@cindex operators, string-matching
-@cindex operators, regexp matching
-@cindex @code{~} operator
-@cindex @code{!~} operator
+@c @cindex operators, @code{~}
+@cindex string-matching operators
+@code{~} (tilde), @code{~} operator
+@cindex tilde (@code{~}), @code{~} operator
+@cindex @code{!} (exclamation point), @code{!~} operator
+@cindex exclamation point (@code{!}), @code{!~} operator
+@c @cindex operators, @code{!~}
+@cindex @code{if} statement
+@cindex @code{while} statement
+@cindex @code{do}-@code{while} statement
+@c @cindex statements, @code{if}
+@c @cindex statements, @code{while}
+@c @cindex statements, @code{do}
Regular expressions can also be used in matching expressions. These
expressions allow you to specify the string to match against; it need
not be the entire current input record. The two operators @samp{~}
@@ -2777,7 +2789,8 @@ $ awk '$1 !~ /J/' inventory-shipped
@dots{}
@end example
-@cindex regexp constant
+@cindex regexp constants
+@cindex regular expressions, constants, See regexp constants
When a regexp is enclosed in slashes, such as @code{/foo/}, we call it
a @dfn{regexp constant}, much like @code{5.27} is a numeric constant and
@code{"foo"} is a string constant.
@@ -2785,14 +2798,16 @@ a @dfn{regexp constant}, much like @code{5.27} is a numeric constant and
@node Escape Sequences, Regexp Operators, Regexp Usage, Regexp
@section Escape Sequences
-@cindex escape sequence notation
+@cindex escape sequences
+@cindex backslash (@code{\}), in escape sequences
+@cindex @code{\} (backslash), in escape sequences
Some characters cannot be included literally in string constants
(@code{"foo"}) or regexp constants (@code{/foo/}).
Instead, they should be represented with @dfn{escape sequences},
which are character sequences beginning with a backslash (@samp{\}).
-One use of an escape sequence is to include a double quote character in
+One use of an escape sequence is to include a double-quote character in
a string constant. Because a plain double quote ends the string, you
-must use @samp{\"} to represent an actual double quote character as a
+must use @samp{\"} to represent an actual double-quote character as a
part of the string. For example:
@example
@@ -2805,8 +2820,8 @@ included normally; you must write @samp{\\} to put one backslash in the
string or regexp. Thus, the string whose contents are the two characters
@samp{"} and @samp{\} must be written @code{"\"\\"}.
-Another use of backslash is to represent unprintable characters
-such as tab or newline. While there is nothing to stop you from entering most
+Backslash also represents unprintable characters
+such as TAB or newline. While there is nothing to stop you from entering most
unprintable characters directly in a string constant or regexp constant,
they may look ugly.
@@ -2819,57 +2834,66 @@ sequences apply to both string constants and regexp constants:
@item \\
A literal backslash, @samp{\}.
-@cindex @command{awk} language, V.4 version
-@cindex @code{\a} escape sequence
+@c @cindex @command{awk} language, V.4 version
+@cindex @code{\} (backslash), @code{\a} escape sequence
+@cindex backslash (@code{\}), @code{\a} escape sequence
@item \a
-The ``alert'' character, @kbd{Ctrl-g}, ASCII code 7 (BEL).
+The ``alert'' character, @kbd{@value{CTL}-g}, ASCII code 7 (BEL).
(This usually makes some sort of audible noise.)
-@cindex @code{\b} escape sequence
+@cindex @code{\} (backslash), @code{\b} escape sequence
+@cindex backslash (@code{\}), @code{\b} escape sequence
@item \b
-Backspace, @kbd{Ctrl-h}, ASCII code 8 (BS).
+Backspace, @kbd{@value{CTL}-h}, ASCII code 8 (BS).
-@cindex @code{\f} escape sequence
+@cindex @code{\} (backslash), @code{\f} escape sequence
+@cindex backslash (@code{\}), @code{\f} escape sequence
@item \f
-Formfeed, @kbd{Ctrl-l}, ASCII code 12 (FF).
+Formfeed, @kbd{@value{CTL}-l}, ASCII code 12 (FF).
-@cindex @code{\n} escape sequence
+@cindex @code{\} (backslash), @code{\n} escape sequence
+@cindex backslash (@code{\}), @code{\n} escape sequence
@item \n
-Newline, @kbd{Ctrl-j}, ASCII code 10 (LF).
+Newline, @kbd{@value{CTL}-j}, ASCII code 10 (LF).
-@cindex @code{\r} escape sequence
+@cindex @code{\} (backslash), @code{\r} escape sequence
+@cindex backslash (@code{\}), @code{\r} escape sequence
@item \r
-Carriage return, @kbd{Ctrl-m}, ASCII code 13 (CR).
+Carriage return, @kbd{@value{CTL}-m}, ASCII code 13 (CR).
-@cindex @code{\t} escape sequence
+@cindex @code{\} (backslash), @code{\t} escape sequence
+@cindex backslash (@code{\}), @code{\t} escape sequence
@item \t
-Horizontal tab, @kbd{Ctrl-i}, ASCII code 9 (HT).
+Horizontal TAB, @kbd{@value{CTL}-i}, ASCII code 9 (HT).
-@cindex @command{awk} language, V.4 version
-@cindex @code{\v} escape sequence
+@c @cindex @command{awk} language, V.4 version
+@cindex @code{\} (backslash), @code{\v} escape sequence
+@cindex backslash (@code{\}), @code{\v} escape sequence
@item \v
-Vertical tab, @kbd{Ctrl-k}, ASCII code 11 (VT).
+Vertical tab, @kbd{@value{CTL}-k}, ASCII code 11 (VT).
-@cindex @code{\}@var{nnn} escape sequence (octal)
+@cindex @code{\} (backslash), @code{\}@var{nnn} escape sequence
+@cindex backslash (@code{\}), @code{\}@var{nnn} escape sequence
@item \@var{nnn}
The octal value @var{nnn}, where @var{nnn} stands for 1 to 3 digits
between @samp{0} and @samp{7}. For example, the code for the ASCII ESC
(escape) character is @samp{\033}.
-@cindex @code{\x} escape sequence
-@cindex @command{awk} language, V.4 version
-@cindex @command{awk} language, POSIX version
-@cindex POSIX @command{awk}
+@c @cindex @command{awk} language, V.4 version
+@c @cindex @command{awk} language, POSIX version
+@cindex @code{\} (backslash), @code{\x} escape sequence
+@cindex backslash (@code{\}), @code{\x} escape sequence
@item \x@var{hh}@dots{}
The hexadecimal value @var{hh}, where @var{hh} stands for a sequence
-of hexadecimal digits (@samp{0} through @samp{9}, and either @samp{A}
-through @samp{F} or @samp{a} through @samp{f}). Like the same construct
-in ISO C, the escape sequence continues until the first non-hexadecimal
+of hexadecimal digits (@samp{0}--@samp{9}, and either @samp{A}--@samp{F}
+or @samp{a}--@samp{f}). Like the same construct
+in ISO C, the escape sequence continues until the first nonhexadecimal
digit is seen. However, using more than two hexadecimal digits produces
undefined results. (The @samp{\x} escape sequence is not allowed in
POSIX @command{awk}.)
-@cindex @code{\/} escape sequence
+@cindex @code{\} (backslash), @code{\/} escape sequence
+@cindex backslash (@code{\}), @code{\/} escape sequence
@item \/
A literal slash (necessary for regexp constants only).
This expression is used when you want to write a regexp
@@ -2877,7 +2901,8 @@ constant that contains a slash. Because the regexp is delimited by
slashes, you need to escape the slash that is part of the pattern,
in order to tell @command{awk} to keep processing the rest of the regexp.
-@cindex @code{\"} escape sequence
+@cindex @code{\} (backslash), @code{\"} escape sequence
+@cindex backslash (@code{\}), @code{\"} escape sequence
@item \"
A literal double quote (necessary for string constants only).
This expression is used when you want to write a string
@@ -2890,16 +2915,18 @@ In @command{gawk}, a number of additional two-character sequences that begin
with a backslash have special meaning in regexps.
@xref{GNU Regexp Operators, ,@command{gawk}-Specific Regexp Operators}.
-In a regexp, a backslash before any character that is not in the above table
+In a regexp, a backslash before any character that is not in the previous list
and not listed in
@ref{GNU Regexp Operators, ,@command{gawk}-Specific Regexp Operators},
means that the next character should be taken literally, even if it would
normally be a regexp operator. For example, @code{/a\+b/} matches the three
characters @samp{a+b}.
-@cindex portability issues
+@cindex backslash (@code{\}), in escape sequences
+@cindex @code{\} (backslash), in escape sequences
+@cindex portability
For complete portability, do not use a backslash before any character not
-shown in the table above.
+shown in the previous list.
To summarize:
@@ -2922,45 +2949,48 @@ literally.
@c fakenode --- for prepinfo
@subheading Advanced Notes: Backslash Before Regular Characters
-@cindex advanced notes
+@cindex portability, backslash in escape sequences
+@cindex POSIX @command{awk}, backslashes in string constants
+@cindex backslash (@code{\}), in escape sequences, POSIX and
+@cindex @code{\} (backslash), in escape sequences, POSIX and
-@cindex common mistakes
-@cindex mistakes, common
-@cindex errors, common
+@cindex troubleshooting, backslash before nonspecial character
If you place a backslash in a string constant before something that is
-not one of the characters listed above, POSIX @command{awk} purposely
+not one of the characters previously listed, POSIX @command{awk} purposely
leaves what happens as undefined. There are two choices:
-@cindex automatic warnings
-@cindex warnings, automatic
+@c @cindex automatic warnings
+@c @cindex warnings, automatic
@table @asis
@item Strip the backslash out
This is what Unix @command{awk} and @command{gawk} both do.
For example, @code{"a\qc"} is the same as @code{"aqc"}.
-(Because this is such an easy bug to both introduce and to miss,
+(Because this is such an easy bug both to introduce and to miss,
@command{gawk} warns you about it.)
Consider @samp{FS = @w{"[ \t]+\|[ \t]+"}} to use vertical bars
surrounded by whitespace as the field separator. There should be
-two backslashes in the string, @samp{FS = @w{"[ \t]+\\|[ \t]+"}}.)
+two backslashes in the string @samp{FS = @w{"[ \t]+\\|[ \t]+"}}.)
@c I did this! This is why I added the warning.
+@cindex @command{gawk}, escape sequences
+@cindex Unix @command{awk}, backslashes in escape sequences
@item Leave the backslash alone
Some other @command{awk} implementations do this.
-In such implementations, @code{"a\qc"} is the same as if you had typed
+In such implementations, typing @code{"a\qc"} is the same as typing
@code{"a\\qc"}.
@end table
@c fakenode --- for prepinfo
@subheading Advanced Notes: Escape Sequences for Metacharacters
-@cindex advanced notes
+@cindex metacharacters, escape sequences for
Suppose you use an octal or hexadecimal
-escape to represent a regexp metacharacter
-(@pxref{Regexp Operators, , Regular Expression Operators}).
+escape to represent a regexp metacharacter.
+(See @ref{Regexp Operators, , Regular Expression Operators}.)
Does @command{awk} treat the character as a literal character or as a regexp
operator?
-@cindex dark corner
+@cindex dark corner, escape sequences, for metacharacters
Historically, such characters were taken literally.
@value{DARKCORNER}
However, the POSIX standard indicates that they should be treated
@@ -2972,9 +3002,8 @@ escape sequences literally when used in regexp constants. Thus,
@node Regexp Operators, Character Lists, Escape Sequences, Regexp
@section Regular Expression Operators
-@cindex metacharacters
-@cindex regular expression metacharacters
-@cindex regexp operators
+@c STARTOFRANGE regexpo
+@cindex regular expressions, operators
You can combine regular expressions with special characters,
called @dfn{regular expression operators} or @dfn{metacharacters}, to
@@ -2985,25 +3014,28 @@ The escape sequences described
earlier
@end ifnotinfo
in @ref{Escape Sequences},
-are valid inside a regexp. They are introduced by a @samp{\}, and
-are recognized and converted into the corresponding real characters as
+are valid inside a regexp. They are introduced by a @samp{\} and
+are recognized and converted into corresponding real characters as
the very first step in processing regexps.
Here is a list of metacharacters. All characters that are not escape
sequences and that are not listed in the table stand for themselves:
@table @code
+@cindex backslash (@code{\})
+@cindex @code{\} (backslash)
@item \
This is used to suppress the special meaning of a character when
matching. For example, @samp{\$}
matches the character @samp{$}.
-@cindex anchors in regexps
-@cindex regexp, anchors
-@cindex Texinfo
+@cindex regular expressions, anchors in
+@cindex Texinfo, chapter beginnings in files
+@cindex @code{^} (caret)
+@cindex caret (@code{^})
@item ^
This matches the beginning of a string. For example, @samp{^@@chapter}
-matches @samp{@@chapter} at the beginning of a string, and can be used
+matches @samp{@@chapter} at the beginning of a string and can be used
to identify chapter beginnings in Texinfo source files.
The @samp{^} is known as an @dfn{anchor}, because it anchors the pattern to
match only at the beginning of the string.
@@ -3016,57 +3048,63 @@ The condition is not true in the following example:
if ("line1\nLINE 2" ~ /^L/) @dots{}
@end example
+@cindex @code{$} (dollar sign)
+@cindex dollar sign (@code{$})
@item $
-This is similar to @samp{^} but it matches only at the end of a string.
+This is similar to @samp{^}, but it matches only at the end of a string.
For example, @samp{p$}
matches a record that ends with a @samp{p}. The @samp{$} is an anchor
and does not match the end of a line embedded in a string.
-The condition is not true in the following example:
+The condition in the following example is not true:
@example
if ("line1\nLINE 2" ~ /1$/) @dots{}
@end example
+@cindex @code{.} (period)
+@cindex period (@code{.})
@item .
This matches any single character,
@emph{including} the newline character. For example, @samp{.P}
matches any single character followed by a @samp{P} in a string. Using
-concatenation, we can make a regular expression such as @samp{U.A}, that
+concatenation, we can make a regular expression such as @samp{U.A}, which
matches any three-character sequence that begins with @samp{U} and ends
with @samp{A}.
-@cindex @command{awk} language, POSIX version
-@cindex POSIX @command{awk}
+@c comma before using does NOT do tertiary
+@cindex POSIX @command{awk}, period (@code{.}), using
In strict POSIX mode (@pxref{Options, ,Command-Line Options}),
@samp{.} does not match the @sc{nul}
character, which is a character with all bits equal to zero.
Otherwise, @sc{nul} is just another character. Other versions of @command{awk}
may not be able to match the @sc{nul} character.
-@cindex character list
-@cindex character set (regexp component)
-@cindex character class
-@cindex bracket expression
+@cindex @code{[]} (square brackets)
+@cindex square brackets (@code{[]})
+@cindex character lists
+@cindex character sets, See Also character lists
+@cindex bracket expressions, See character lists
@item [@dots{}]
This is called a @dfn{character list}.@footnote{In other literature,
you may see a character list referred to as either a
-@dfn{character set}, a @dfn{character class} or a @dfn{bracket expression}.}
+@dfn{character set}, a @dfn{character class}, or a @dfn{bracket expression}.}
It matches any @emph{one} of the characters that are enclosed in
the square brackets. For example, @samp{[MVX]} matches any one of
-the characters @samp{M}, @samp{V}, or @samp{X}, in a string. A full
+the characters @samp{M}, @samp{V}, or @samp{X} in a string. A full
discussion of what can be inside the square brackets of a character list
is given in
@ref{Character Lists, ,Using Character Lists}.
-@cindex complemented character list
-@cindex character list, complemented
+@cindex character lists, complemented
@item [^ @dots{}]
This is a @dfn{complemented character list}. The first character after
the @samp{[} @emph{must} be a @samp{^}. It matches any characters
@emph{except} those in the square brackets. For example, @samp{[^awk]}
-matches any character that is not an @samp{a}, a @samp{w},
-or a @samp{k}.
+matches any character that is not an @samp{a}, @samp{w},
+or @samp{k}.
+@cindex @code{|} (vertical bar)
+@cindex vertical bar (@code{|})
@item |
This is the @dfn{alternation operator} and it is used to specify
alternatives.
@@ -3078,15 +3116,18 @@ means it matches any string that starts with @samp{P} or contains a digit.
The alternation applies to the largest possible regexps on either side.
-@cindex Texinfo
+@cindex @code{()} (parentheses)
+@cindex parentheses @code{()}
@item (@dots{})
-Parentheses are used for grouping in regular expressions, similar to
+Parentheses are used for grouping in regular expressions, as in
arithmetic. They can be used to concatenate regular expressions
containing the alternation operator, @samp{|}. For example,
@samp{@@(samp|code)\@{[^@}]+\@}} matches both @samp{@@code@{foo@}} and
@samp{@@samp@{bar@}}.
(These are Texinfo formatting control sequences.)
+@cindex @code{*} (asterisk), @code{*} operator, as regexp operator
+@cindex asterisk (@code{*}), @code{*} operator, as regexp operator
@item *
This symbol means that the preceding regular expression should be
repeated as many times as necessary to find a match. For example, @samp{ph*}
@@ -3103,8 +3144,10 @@ prints every record in @file{sample} containing a string of the form
Notice the escaping of the parentheses by preceding them
with backslashes.
+@cindex @code{+} (plus sign)
+@cindex plus sign (@code{+})
@item +
-This symbol is similar to @samp{*} except that the preceding expression must be
+This symbol is similar to @samp{*}, except that the preceding expression must be
matched at least once. This means that @samp{wh+y}
would match @samp{why} and @samp{whhy}, but not @samp{wy}, whereas
@samp{wh*y} would match all three of these strings.
@@ -3115,13 +3158,13 @@ way of writing the last @samp{*} example:
awk '/\(c[ad]+r x\)/ @{ print @}' sample
@end example
+@cindex @code{?} (question mark)
+@cindex question mark (@code{?})
@item ?
-This symbol is similar to @samp{*} except that the preceding expression can be
+This symbol is similar to @samp{*}, except that the preceding expression can be
matched either once or not at all. For example, @samp{fe?d}
matches @samp{fed} and @samp{fd}, but nothing else.
-@cindex @command{awk} language, POSIX version
-@cindex POSIX @command{awk}
@cindex interval expressions
@item @{@var{n}@}
@itemx @{@var{n},@}
@@ -3145,10 +3188,12 @@ Matches @samp{whhhy}, @samp{whhhhy}, or @samp{whhhhhy}, only.
Matches @samp{whhy} or @samp{whhhy}, and so on.
@end table
+@cindex POSIX @command{awk}, interval expressions in
Interval expressions were not traditionally available in @command{awk}.
They were added as part of the POSIX standard to make @command{awk}
and @command{egrep} consistent with each other.
+@cindex @command{gawk}, interval expressions and
However, because old programs may use @samp{@{} and @samp{@}} in regexp
constants, by default @command{gawk} does @emph{not} match interval expressions
in regexps. If either @option{--posix} or @option{--re-interval} are specified
@@ -3163,13 +3208,15 @@ using a string constant with a regexp operator or function.}
@end table
@cindex precedence, regexp operators
-@cindex regexp operators, precedence of
+@cindex regular expressions, operators, precedence of
In regular expressions, the @samp{*}, @samp{+}, and @samp{?} operators,
as well as the braces @samp{@{} and @samp{@}},
have
the highest precedence, followed by concatenation, and finally by @samp{|}.
As in arithmetic, parentheses can change how operators are grouped.
+@cindex POSIX @command{awk}, regular expressions and
+@cindex @command{gawk}, regular expressions, precedence
In POSIX @command{awk} and @command{gawk}, the @samp{*}, @samp{+}, and @samp{?} operators
stand for themselves when there is nothing in the regexp that precedes them.
For example, @samp{/+/} matches a literal plus sign. However, many other versions of
@@ -3179,9 +3226,14 @@ If @command{gawk} is in compatibility mode
(@pxref{Options, ,Command-Line Options}),
POSIX character classes and interval expressions are not available in
regular expressions.
+@c ENDOFRANGE regexpo
@node Character Lists, GNU Regexp Operators, Regexp Operators, Regexp
@section Using Character Lists
+@c STARTOFRANGE charlist
+@cindex character lists
+@cindex character lists, range expressions
+@cindex range expressions
Within a character list, a @dfn{range expression} consists of two
characters separated by a hyphen. It matches any single character that
@@ -3195,6 +3247,12 @@ the traditional interpretation of bracket expressions, you can use the C
locale by setting the @env{LC_ALL} environment variable to the value
@samp{C}.
+@cindex @code{\} (backslash), in character lists
+@cindex backslash (@code{\}), in character lists
+@cindex @code{^} (caret), in character lists
+@cindex caret (@code{^}), in character lists
+@cindex @code{-} (hyphen), in character lists
+@cindex hyphen (@code{-}), in character lists
To include one of the characters @samp{\}, @samp{]}, @samp{-}, or @samp{^} in a
character list, put a @samp{\} in front of it. For example:
@@ -3205,6 +3263,9 @@ character list, put a @samp{\} in front of it. For example:
@noindent
matches either @samp{d} or @samp{]}.
+@cindex POSIX @command{awk}, character lists and
+@cindex Extended Regular Expressions (EREs)
+@cindex EREs (Extended Regular Expressions)
@cindex @command{egrep} utility
This treatment of @samp{\} in character lists
is compatible with other @command{awk}
@@ -3214,9 +3275,8 @@ of the POSIX specification for Extended Regular Expressions (EREs).
POSIX EREs are based on the regular expressions accepted by the
traditional @command{egrep} utility.
-@cindex character class
-@cindex @command{awk} language, POSIX version
-@cindex POSIX @command{awk}
+@cindex character lists, character classes
+@cindex POSIX @command{awk}, character lists and, character classes
@dfn{Character classes} are a new feature introduced in the POSIX standard.
A character class is a special notation for describing
lists of characters that have a specific attribute, but the
@@ -3227,7 +3287,7 @@ is an alphabetic character differs between the United States and France.
A character class is only valid in a regexp @emph{inside} the
brackets of a character list. Character classes consist of @samp{[:},
a keyword denoting the class, and @samp{:]}. Here are the character
-classes defined by the POSIX standard:
+classes defined by the POSIX standard.
@c the regular table is commented out while trying out the multitable.
@c leave it here in case we need to go back, but make sure the text
@@ -3242,7 +3302,7 @@ Alphanumeric characters.
Alphabetic characters.
@item [:blank:]
-Space and tab characters.
+Space and TAB characters.
@item [:cntrl:]
Control characters.
@@ -3265,7 +3325,7 @@ Punctuation characters (characters that are not letters, digits,
control characters, or space characters).
@item [:space:]
-Space characters (such as space, tab, and formfeed, to name a few).
+Space characters (such as space, TAB, and formfeed, to name a few).
@item [:upper:]
Uppercase alphabetic characters.
@@ -3278,7 +3338,7 @@ Characters that are hexadecimal digits.
@multitable {@code{[:xdigit:]}} {Characters that are both printable and visible. (A space is}
@item @code{[:alnum:]} @tab Alphanumeric characters.
@item @code{[:alpha:]} @tab Alphabetic characters.
-@item @code{[:blank:]} @tab Space and tab characters.
+@item @code{[:blank:]} @tab Space and TAB characters.
@item @code{[:cntrl:]} @tab Control characters.
@item @code{[:digit:]} @tab Numeric characters.
@item @code{[:graph:]} @tab Characters that are both printable and visible.
@@ -3287,7 +3347,7 @@ Characters that are hexadecimal digits.
@item @code{[:print:]} @tab Printable characters (characters that are not control characters).
@item @code{[:punct:]} @tab Punctuation characters (characters that are not letters, digits,
control characters, or space characters).
-@item @code{[:space:]} @tab Space characters (such as space, tab, and formfeed, to name a few).
+@item @code{[:space:]} @tab Space characters (such as space, TAB, and formfeed, to name a few).
@item @code{[:upper:]} @tab Uppercase alphabetic characters.
@item @code{[:xdigit:]} @tab Characters that are hexadecimal digits.
@end multitable
@@ -3301,6 +3361,8 @@ With the POSIX character classes, you can write
@code{/[[:alnum:]]/} to match the alphabetic
and numeric characters in your character set.
+@cindex character lists, collating elements
+@cindex character lists, non-ASCII
@cindex collating elements
Two additional special sequences can appear in character lists.
These apply to non-ASCII character sets, which can have single symbols
@@ -3308,18 +3370,20 @@ These apply to non-ASCII character sets, which can have single symbols
character. They can also have several characters that are equivalent for
@dfn{collating}, or sorting, purposes. (For example, in French, a plain ``e''
and a grave-accented ``@`e'' are equivalent.)
+These sequences are:
@table @asis
+@cindex character lists, collating symbols
@cindex collating symbols
-@item Collating Symbols
-A @dfn{collating symbol} is a multicharacter collating element enclosed between
+@item Collating symbols
+Multicharacter collating elements enclosed between
@samp{[.} and @samp{.]}. For example, if @samp{ch} is a collating element,
then @code{[[.ch.]]} is a regexp that matches this collating element, whereas
@code{[ch]} is a regexp that matches either @samp{c} or @samp{h}.
-@cindex equivalence classes
-@item Equivalence Classes
-An @dfn{equivalence class} is a locale-specific name for a list of
+@cindex character lists, equivalence classes
+@item Equivalence classes
+Locale-specific names for a list of
characters that are equal. The name is enclosed between
@samp{[=} and @samp{=]}.
For example, the name @samp{e} might be used to represent all of
@@ -3327,19 +3391,28 @@ For example, the name @samp{e} might be used to represent all of
that matches any of @samp{e}, @samp{@'e}, or @samp{@`e}.
@end table
-These features are very valuable in non-English speaking locales.
+These features are very valuable in non-English-speaking locales.
+@cindex internationalization, localization, character classes
+@cindex @command{gawk}, character classes and
+@cindex POSIX @command{awk}, character lists and, character classes
@strong{Caution:} The library functions that @command{gawk} uses for regular
-expression matching currently only recognize POSIX character classes;
+expression matching currently recognize only POSIX character classes;
they do not recognize collating symbols or equivalence classes.
@c maybe one day ...
+@c ENDOFRANGE charlist
@node GNU Regexp Operators, Case-sensitivity, Character Lists, Regexp
@section @command{gawk}-Specific Regexp Operators
@c This section adapted (long ago) from the regex-0.12 manual
-@cindex regexp operators, GNU specific
+@c STARTOFRANGE regexpg
+@cindex regular expressions, operators, @command{gawk}
+@c STARTOFRANGE gregexp
+@cindex @command{gawk}, regular expressions, operators
+@cindex operators, GNU-specific
+@cindex regular expressions, operators, for words
@cindex word, regexp definition of
GNU software that deals with regular expressions provides a number of
additional regexp operators. These operators are described in this
@@ -3350,37 +3423,50 @@ For our purposes, a @dfn{word} is a sequence of one or more letters, digits,
or underscores (@samp{_}):
@table @code
-@cindex @code{\w} regexp operator
+@c @cindex operators, @code{\w} (@command{gawk})
+@cindex backslash (@code{\}), @code{\w} operator (@command{gawk})
+@cindex @code{\} (backslash), @code{\w} operator (@command{gawk})
@item \w
Matches any word-constituent character---that is, it matches any
-letter, digit, or underscore. Think of it as short-hand for
+letter, digit, or underscore. Think of it as shorthand for
@w{@code{[[:alnum:]_]}}.
-@cindex @code{\W} regexp operator
+@c @cindex operators, @code{\W} (@command{gawk})
+@cindex backslash (@code{\}), @code{\W} operator (@command{gawk})
+@cindex @code{\} (backslash), @code{\W} operator (@command{gawk})
@item \W
Matches any character that is not word-constituent.
-Think of it as short-hand for
+Think of it as shorthand for
@w{@code{[^[:alnum:]_]}}.
-@cindex @code{\<} regexp operator
+@c @cindex operators, @code{\<} (@command{gawk})
+@cindex backslash (@code{\}), @code{\<} operator (@command{gawk})
+@cindex @code{\} (backslash), @code{\<} operator (@command{gawk})
@item \<
Matches the empty string at the beginning of a word.
For example, @code{/\<away/} matches @samp{away} but not
@samp{stowaway}.
-@cindex @code{\>} regexp operator
+@c @cindex operators, @code{\>} (@command{gawk})
+@cindex backslash (@code{\}), @code{\>} operator (@command{gawk})
+@cindex @code{\} (backslash), @code{\>} operator (@command{gawk})
@item \>
Matches the empty string at the end of a word.
For example, @code{/stow\>/} matches @samp{stow} but not @samp{stowaway}.
-@cindex @code{\y} regexp operator
+@c @cindex operators, @code{\y} (@command{gawk})
+@cindex backslash (@code{\}), @code{\y} operator (@command{gawk})
+@cindex @code{\} (backslash), @code{\y} operator (@command{gawk})
+@c comma before using does NOT do secondary
@cindex word boundaries, matching
@item \y
Matches the empty string at either the beginning or the
end of a word (i.e., the word boundar@strong{y}). For example, @samp{\yballs?\y}
matches either @samp{ball} or @samp{balls}, as a separate word.
-@cindex @code{\B} regexp operator
+@c @cindex operators, @code{\B} (@command{gawk})
+@cindex backslash (@code{\}), @code{\B} operator (@command{gawk})
+@cindex @code{\} (backslash), @code{\B} operator (@command{gawk})
@item \B
Matches the empty string that occurs between two
word-constituent characters. For example,
@@ -3388,29 +3474,43 @@ word-constituent characters. For example,
@samp{\B} is essentially the opposite of @samp{\y}.
@end table
-@cindex buffer matching operators
+@cindex buffers, operators for
+@cindex regular expressions, operators, for buffers
+@cindex operators, string-matching, for buffers
There are two other operators that work on buffers. In Emacs, a
@dfn{buffer} is, naturally, an Emacs buffer. For other programs,
@command{gawk}'s regexp library routines consider the entire
string to match as the buffer.
+The operators are:
@table @code
@item \`
-@cindex @code{\`} regexp operator
+@c @cindex operators, @code{\`} (@command{gawk})
+@cindex backslash (@code{\}), @code{\`} operator (@command{gawk})
+@cindex @code{\} (backslash), @code{\`} operator (@command{gawk})
Matches the empty string at the
beginning of a buffer (string).
-@cindex @code{\'} regexp operator
+@c @cindex operators, @code{\'} (@command{gawk})
+@cindex backslash (@code{\}), @code{\'} operator (@command{gawk})
+@cindex @code{\} (backslash), @code{\'} operator (@command{gawk})
@item \'
Matches the empty string at the
end of a buffer (string).
@end table
+@cindex @code{^} (caret)
+@cindex caret (@code{^})
+@cindex @code{?} (question mark)
+@cindex question mark (@code{?})
Because @samp{^} and @samp{$} always work in terms of the beginning
and end of strings, these operators don't add any new capabilities
for @command{awk}. They are provided for compatibility with other
GNU software.
+@cindex @command{gawk}, word-boundary operator
+@cindex word-boundary operator (@command{gawk})
+@cindex operators, word-boundary (@command{gawk})
In other GNU software, the word-boundary operator is @samp{\b}. However,
that conflicts with the @command{awk} language's definition of @samp{\b}
as backspace, so @command{gawk} uses a different letter.
@@ -3422,7 +3522,8 @@ lesser of two evils.
@c NOTE!!! Keep this in sync with the same table in the summary appendix!
@c
@c Should really do this with file inclusion.
-@cindex regexp, effect of command-line options
+@cindex regular expressions, @command{gawk}, command-line options
+@cindex @command{gawk}, command-line options
The various command-line options
(@pxref{Options, ,Command-Line Options})
control how @command{gawk} interprets characters in regexps:
@@ -3449,7 +3550,7 @@ are allowed.
@item @code{--traditional}
Traditional Unix @command{awk} regexps are matched. The GNU operators
are not special, interval expressions are not available, nor
-are the POSIX character classes (@code{[[:alnum:]]} and so on).
+are the POSIX character classes (@code{[[:alnum:]]}, etc.).
Characters described by octal and hexadecimal escape sequences are
treated literally, even if they represent regexp metacharacters.
@@ -3457,12 +3558,16 @@ treated literally, even if they represent regexp metacharacters.
Allow interval expressions in regexps, even if @option{--traditional}
has been provided.
@end table
+@c ENDOFRANGE gregexp
+@c ENDOFRANGE regexpg
@node Case-sensitivity, Leftmost Longest, GNU Regexp Operators, Regexp
@section Case Sensitivity in Matching
-@cindex case sensitivity
-@cindex ignoring case
+@c STARTOFRANGE regexpcs
+@cindex regular expressions, case sensitivity
+@c STARTOFRANGE csregexp
+@cindex case sensitivity, regexps and
Case is normally significant in regular expressions, both when matching
ordinary characters (i.e., not metacharacters) and inside character
sets. Thus, a @samp{w} in a regular expression matches only a lowercase
@@ -3470,7 +3575,7 @@ sets. Thus, a @samp{w} in a regular expression matches only a lowercase
The simplest way to do a case-independent match is to use a character
list---for example, @samp{[Ww]}. However, this can be cumbersome if
-you need to use it often and it can make the regular expressions harder
+you need to use it often, and it can make the regular expressions harder
to read. There are two alternatives that you might prefer.
One way to perform a case-insensitive match at a particular point in the
@@ -3488,15 +3593,20 @@ tolower($1) ~ /foo/ @{ @dots{} @}
converts the first field to lowercase before matching against it.
This works in any POSIX-compliant @command{awk}.
-@cindex differences between @command{gawk} and @command{awk}
-@cindex @code{~} operator
-@cindex @code{!~} operator
+@cindex @command{gawk}, regular expressions, case sensitivity
+@cindex case sensitivity, @command{gawk}
+@cindex differences in @command{awk} and @command{gawk}, regular expressions
+@cindex @code{~} (tilde), @code{~} operator
+@cindex tilde (@code{~}), @code{~} operator
+@cindex @code{!} (exclamation point), @code{!~} operator
+@cindex exclamation point (@code{!}), @code{!~} operator
@cindex @code{IGNORECASE} variable
+@c @cindex variables, @code{IGNORECASE}
Another method, specific to @command{gawk}, is to set the variable
@code{IGNORECASE} to a nonzero value (@pxref{Built-in Variables}).
When @code{IGNORECASE} is not zero, @emph{all} regexp and string
operations ignore case. Changing the value of
-@code{IGNORECASE} dynamically controls the case sensitivity of the
+@code{IGNORECASE} dynamically controls the case-sensitivity of the
program as it runs. Case is significant by default because
@code{IGNORECASE} (like most variables) is initialized to zero:
@@ -3534,24 +3644,26 @@ with @samp{==}, @samp{!=}, and so on.
Beginning with @value{PVERSION} 3.0, both regexp and string comparison
operations are also affected by @code{IGNORECASE}.
-@cindex ISO 8859-1
-@cindex ISO Latin-1
+@c @cindex ISO 8859-1
+@c @cindex ISO Latin-1
Beginning with @command{gawk} 3.0,
the equivalences between upper-
and lowercase characters are based on the ISO-8859-1 (ISO Latin-1)
character set. This character set is a superset of the traditional 128
-ASCII characters, that also provides a number of characters suitable
+ASCII characters, which also provides a number of characters suitable
for use with European languages.
The value of @code{IGNORECASE} has no effect if @command{gawk} is in
compatibility mode (@pxref{Options, ,Command-Line Options}).
Case is always significant in compatibility mode.
+@c ENDOFRANGE csregexp
+@c ENDOFRANGE regexpcs
@node Leftmost Longest, Computed Regexps, Case-sensitivity, Regexp
@section How Much Text Matches?
-@cindex leftmost longest match
-@cindex matching, leftmost longest
+@cindex regular expressions, leftmost longest match
+@c @cindex matching, leftmost longest
Consider the following:
@example
@@ -3589,12 +3701,16 @@ and also @pxref{Field Separators, ,Specifying How Fields Are Separated}).
@node Computed Regexps, , Leftmost Longest, Regexp
@section Using Dynamic Regexps
-@cindex computed regular expressions
+@c STARTOFRANGE dregexp
@cindex regular expressions, computed
-@cindex dynamic regular expressions
-@cindex regexp, dynamic
-@cindex @code{~} operator
-@cindex @code{!~} operator
+@c STARTOFRANGE regexpd
+@cindex regular expressions, dynamic
+@cindex @code{~} (tilde), @code{~} operator
+@cindex tilde (@code{~}), @code{~} operator
+@cindex @code{!} (exclamation point), @code{!~} operator
+@cindex exclamation point (@code{!}), @code{!~} operator
+@c @cindex operators, @code{~}
+@c @cindex operators, @code{!~}
The righthand side of a @samp{~} or @samp{!~} operator need not be a
regexp constant (i.e., a string of characters between slashes). It may
be any expression. The expression is evaluated and converted to a string
@@ -3620,10 +3736,14 @@ If you are going to use a string constant, you have to understand that
the string is, in essence, scanned @emph{twice}: the first time when
@command{awk} reads your program, and the second time when it goes to
match the string on the lefthand side of the operator with the pattern
-on the right. This is true of any string valued expression (such as
-@code{digits_regexp} shown previously), not just string constants.
-
-@cindex regexp constants, difference between slashes and quotes
+on the right. This is true of any string-valued expression (such as
+@code{digits_regexp}, shown previously), not just string constants.
+
+@cindex regexp constants, slashes vs. quotes
+@cindex @code{\} (backslash), regexp constants
+@cindex backslash (@code{\}), regexp constants
+@cindex @code{"} (double quote), regexp constants
+@cindex double quote (@code{"}), regexp constants
What difference does it make if the string is
scanned twice? The answer has to do with escape sequences, and particularly
with backslashes. To get a backslash into a regular expression inside a
@@ -3635,9 +3755,9 @@ you have to type @code{"\\*"}. The first backslash escapes the
second one so that the string actually contains the
two characters @samp{\} and @samp{*}.
-@cindex common mistakes
-@cindex mistakes, common
-@cindex errors, common
+@cindex troubleshooting, regexp constants vs. string constants
+@cindex regexp constants, vs. string constants
+@cindex string constants, vs. regexp constants
Given that you can use both regexp and string constants to describe
regular expressions, which should you use? The answer is ``regexp
constants,'' for several reasons:
@@ -3651,7 +3771,7 @@ kinds of constants is a common source of errors.
@item
It is more efficient to use regexp constants. @command{awk} can note
-that you have supplied a regexp, and store it internally in a form that
+that you have supplied a regexp and store it internally in a form that
makes pattern matching more efficient. When using a string constant,
@command{awk} must first convert the string into this internal form and
then perform the pattern matching.
@@ -3663,11 +3783,8 @@ intend a regexp match.
@c fakenode --- for prepinfo
@subheading Advanced Notes: Using @code{\n} in Character Lists of Dynamic Regexps
-@cindex advanced notes
-@cindex dynamic regular expressions with embedded newlines
-@cindex regexp, dynamic, with embedded newlines
-@cindex newlines, embedded in dynamic regexps
-@cindex embedded newlines, in dynamic regexps
+@cindex regular expressions, dynamic, with embedded newlines
+@cindex newlines, in dynamic regexps
Some commercial versions of @command{awk} do not allow the newline
character to be used inside a character list for a dynamic regexp:
@@ -3681,40 +3798,47 @@ $ awk '$0 ~ "[ \t\n]"'
@error{} >>> <<<
@end example
+@cindex newlines, in regexp constants
But a newline in a regexp constant works with no problem:
@example
$ awk '$0 ~ /[ \t\n]/'
here is a sample line
@print{} here is a sample line
-@kbd{Ctrl-d}
+@kbd{@value{CTL}-d}
@end example
@command{gawk} does not have this problem, and it isn't likely to
occur often in practice, but it's worth noting for future reference.
+@c ENDOFRANGE dregexp
+@c ENDOFRANGE regexpd
+@c ENDOFRANGE regexp
@node Reading Files, Printing, Regexp, Top
@chapter Reading Input Files
-@cindex reading files
-@cindex input
-@cindex standard input
+@c STARTOFRANGE infir
+@cindex input files, reading
+@cindex input files
@cindex @code{FILENAME} variable
In the typical @command{awk} program, all input is read either from the
-standard input (by default, this is the keyboard but often it is a pipe from another
-command), or from files whose names you specify on the @command{awk}
+standard input (by default, this is the keyboard, but often it is a pipe from another
+command) or from files whose names you specify on the @command{awk}
command line. If you specify input files, @command{awk} reads them
in order, processing all the data from one before going on to the next.
The name of the current input file can be found in the built-in variable
@code{FILENAME}
(@pxref{Built-in Variables}).
+@cindex records
+@cindex fields
The input is read in units called @dfn{records}, and is processed by the
rules of your program one record at a time.
By default, each record is one line. Each
record is automatically split into chunks called @dfn{fields}.
This makes it more convenient for programs to work on the parts of a record.
+@cindex @code{getline} command
On rare occasions, you may need to use the @code{getline} command.
The @code{getline} command is valuable, both because it
can do explicit input from any number of files, and because the files
@@ -3724,7 +3848,7 @@ used with it do not have to be named on the @command{awk} command line
@menu
* Records:: Controlling how data is split into records.
* Fields:: An introduction to fields.
-* Non-Constant Fields:: Non-constant Field Numbers.
+* Nonconstant Fields:: Nonconstant Field Numbers.
* Changing Fields:: Changing the Contents of a Field.
* Field Separators:: The field separator and how to change it.
* Constant Size:: Reading constant width data.
@@ -3736,7 +3860,10 @@ used with it do not have to be named on the @command{awk} command line
@node Records, Fields, Reading Files, Reading Files
@section How Input Is Split into Records
-@cindex number of records, @code{NR}, @code{FNR}
+@c STARTOFRANGE inspl
+@cindex input, splitting into records
+@c STARTOFRANGE recspl
+@cindex records, splitting input into
@cindex @code{NR} variable
@cindex @code{FNR} variable
The @command{awk} utility divides the input for your @command{awk}
@@ -3750,16 +3877,16 @@ file is started. Another built-in variable, @code{NR}, is the total
number of input records read so far from all @value{DF}s. It starts at zero,
but is never automatically reset to zero.
-@cindex record separator, @code{RS}
-@cindex changing the record separator
-@cindex record, definition of
-@cindex @code{RS} variable
+@cindex separators, for records
+@cindex record separators
Records are separated by a character called the @dfn{record separator}.
By default, the record separator is the newline character.
This is why records are, by default, single lines.
A different character can be used for the record separator by
assigning the character to the built-in variable @code{RS}.
+@cindex newlines, as record separators
+@cindex @code{RS} variable
Like any other variable,
the value of @code{RS} can be changed in the @command{awk} program
with the assignment operator, @samp{=}
@@ -3772,6 +3899,7 @@ To do this, use the special @code{BEGIN} pattern
(@pxref{BEGIN/END, ,The @code{BEGIN} and @code{END} Special Patterns}).
For example:
+@cindex @code{BEGIN} pattern
@example
awk 'BEGIN @{ RS = "/" @}
@{ print $0 @}' BBS-list
@@ -3783,7 +3911,7 @@ This is a string whose first character is a slash; as a result, records
are separated by slashes. Then the input file is read, and the second
rule in the @command{awk} program (the action with no pattern) prints each
record. Because each @code{print} statement adds a newline at the end of
-its output, the effect of this @command{awk} program is to copy the input
+its output, this @command{awk} program copies the input
with each slash changed to a newline. Here are the results of running
the program on @file{BBS-list}:
@@ -3836,6 +3964,8 @@ for the @samp{core} BBS; the newline separating them in the output
is the original newline in the @value{DF}, not the one added by
@command{awk} when it printed the record!
+@cindex record separators, changing
+@cindex separators, for records
Another way to change the record separator is on the command line,
using the variable-assignment feature
(@pxref{Other Arguments, ,Other Command-Line Arguments}):
@@ -3859,12 +3989,13 @@ $ echo | awk 'BEGIN @{ RS = "a" @} ; @{ print NF @}'
There is one field, consisting of a newline. The value of the built-in
variable @code{NF} is the number of fields in the current record.
-@cindex dark corner
+@cindex dark corner, input files
Reaching the end of an input file terminates the current input record,
even if the last character in the file is not the character in @code{RS}.
@value{DARKCORNER}
-@cindex empty string
+@cindex null strings
+@cindex strings, empty, See null strings
The empty string @code{""} (a string without any characters)
has a special meaning
as the value of @code{RS}. It means that records are separated
@@ -3877,10 +4008,12 @@ currently being processed, as well as records already processed, are not
affected.
@cindex @code{RT} variable
-@cindex record terminator, @code{RT}
-@cindex terminator, record
-@cindex differences between @command{gawk} and @command{awk}
-@cindex regular expressions as record separators
+@cindex records, terminating
+@cindex terminating records
+@cindex differences in @command{awk} and @command{gawk}, record separators
+@cindex regular expressions, as record separators
+@cindex record separators, regular expressions as
+@cindex separators, for records, regular expressions as
After the end of the record has been determined, @command{gawk}
sets the variable @code{RT} to the text in the input that matched
@code{RS}.
@@ -3893,7 +4026,7 @@ ends at the next string that matches the regular expression; the next
record starts at the end of the matching string. This general rule is
actually at work in the usual case, where @code{RS} contains just a
newline: a record ends at the beginning of the next matching string (the
-next newline in the input) and the following record starts just after
+next newline in the input), and the following record starts just after
the end of this string (at the first character of the following line).
The newline, because it matches @code{RS}, is not part of either record.
@@ -3924,7 +4057,7 @@ supplies its own terminating newline.
@xref{Simple Sed, ,A Simple Stream Editor}, for a more useful example
of @code{RS} as a regexp and @code{RT}.
-@cindex differences between @command{gawk} and @command{awk}
+@cindex differences in @command{awk} and @command{gawk}, @code{RS}/@code{RT} variables
The use of @code{RS} as a regular expression and the @code{RT}
variable are @command{gawk} extensions; they are not available in
compatibility mode
@@ -3934,9 +4067,9 @@ In compatibility mode, only the first character of the value of
@c fakenode --- for prepinfo
@subheading Advanced Notes: @code{RS = "\0"} Is Not Portable
-@cindex advanced notes
-@cindex portability issues
+@cindex advanced features, @value{DF}s as single record
+@cindex portability, @value{DF}s as single record
There are times when you might want to treat an entire @value{DF} as a
single record. The only way to make this happen is to give @code{RS}
a value that you know doesn't occur in the input file. This is hard
@@ -3952,31 +4085,40 @@ value to use for @code{RS} in this case:
BEGIN @{ RS = "\0" @} # whole file becomes one record?
@end example
-@cindex differences between @command{gawk} and @command{awk}
+@cindex differences in @command{awk} and @command{gawk}, strings, storing
@command{gawk} in fact accepts this, and uses the @sc{nul}
character for the record separator.
However, this usage is @emph{not} portable
to other @command{awk} implementations.
-@cindex dark corner
+@cindex dark corner, strings, storing
All other @command{awk} implementations@footnote{At least that we know
about.} store strings internally as C-style strings. C strings use the
@sc{nul} character as the string terminator. In effect, this means that
@samp{RS = "\0"} is the same as @samp{RS = ""}.
@value{DARKCORNER}
+@cindex records, treating files as
+@cindex files, as single records
The best way to treat a whole file as a single record is to
simply read the file in, one record at a time, concatenating each
record onto the end of the previous ones.
+@c ENDOFRANGE inspl
+@c ENDOFRANGE recspl
-@node Fields, Non-Constant Fields, Records, Reading Files
+@node Fields, Nonconstant Fields, Records, Reading Files
@section Examining Fields
@cindex examining fields
@cindex fields
@cindex accessing fields
+@c STARTOFRANGE fiex
+@cindex fields, examining
+@cindex POSIX @command{awk}, field separators and
+@cindex field separators, POSIX and
+@cindex separators, field, POSIX and
When @command{awk} reads an input record, the record is
-automatically separated or @dfn{parsed} by the interpreter into chunks
+automatically @dfn{parsed} or separated by the interpreter into chunks
called @dfn{fields}. By default, fields are separated by @dfn{whitespace},
like words in a line.
Whitespace in @command{awk} means any string of one or more spaces,
@@ -3993,12 +4135,16 @@ simple @command{awk} programs so powerful.
@cindex @code{$} field operator
@cindex field operator @code{$}
+@cindex @code{$} (dollar sign), @code{$} field operator
+@cindex dollar sign (@code{$}), @code{$} field operator
+@c The comma here does NOT mark a secondary term:
+@cindex field operators, dollar sign as
A dollar-sign (@samp{$}) is used
to refer to a field in an @command{awk} program,
followed by the number of the field you want. Thus, @code{$1}
refers to the first field, @code{$2} to the second, and so on.
(Unlike the Unix shells, the field numbers are not limited to single digits.
-@code{$127} is the one hundred and twenty-seventh field in the record.)
+@code{$127} is the one hundred twenty-seventh field in the record.)
For example, suppose the following is a line of input:
@example
@@ -4013,7 +4159,7 @@ Here the first field, or @code{$1}, is @samp{This}, the second field, or
field.
@cindex @code{NF} variable
-@cindex number of fields, @code{NF}
+@cindex fields, number of
@code{NF} is a built-in variable whose value is the number of fields
in the current record. @command{awk} automatically updates the value
of @code{NF} each time it reads a record. No matter how many fields
@@ -4023,7 +4169,7 @@ If you try to reference a field beyond the last
one (such as @code{$8} when the record has only seven fields), you get
the empty string. (If used in a numeric operation, you get zero.)
-The use of @code{$0}, which looks like a reference to the ``zeroth'' field, is
+The use of @code{$0}, which looks like a reference to the ``zero-th'' field, is
a special case: it represents the whole input record
when you are not interested in specific fields.
Here are some more examples:
@@ -4055,9 +4201,12 @@ $ awk '/foo/ @{ print $1, $NF @}' BBS-list
@print{} macfoo A
@print{} sabafoo C
@end example
+@c ENDOFRANGE fiex
-@node Non-Constant Fields, Changing Fields, Fields, Reading Files
-@section Non-Constant Field Numbers
+@node Nonconstant Fields, Changing Fields, Fields, Reading Files
+@section Nonconstant Field Numbers
+@cindex fields, numbers
+@cindex field numbers
The number of a field does not need to be a constant. Any expression in
the @command{awk} language can be used after a @samp{$} to refer to a
@@ -4106,17 +4255,15 @@ variable @code{NF} (also @pxref{Built-in Variables}). The expression
@code{$NF} is not a special feature---it is the direct consequence of
evaluating @code{NF} and using its value as a field number.
-@node Changing Fields, Field Separators, Non-Constant Fields, Reading Files
+@node Changing Fields, Field Separators, Nonconstant Fields, Reading Files
@section Changing the Contents of a Field
@cindex fields, changing contents of
-@cindex changing contents of a field
-@cindex assignment to fields
The contents of a field, as seen by @command{awk}, can be changed within an
@command{awk} program; this changes what @command{awk} perceives as the
current input record. (The actual input is untouched; @command{awk} @emph{never}
modifies the input file.)
-Consider this example and its output:
+Consider the following example and its output:
@example
$ awk '@{ nboxes = $3 ; $3 = $3 - 10
@@ -4171,6 +4318,8 @@ $ awk '@{ $6 = ($5 + $4 + $3 + $2)
@dots{}
@end example
+@cindex adding, fields
+@cindex fields, adding
@noindent
We've just created @code{$6}, whose value is the sum of fields
@code{$2}, @code{$3}, @code{$4}, and @code{$5}. The @samp{+} sign
@@ -4183,6 +4332,9 @@ after adding a field, the record printed includes the new field, with
the appropriate number of field separators between it and the previously
existing fields.
+@cindex @code{OFS} variable
+@cindex output field separator, See @code{OFS} variable
+@cindex field separators, See Also @code{OFS}
This recomputation affects and is affected by
@code{NF} (the number of fields; @pxref{Fields, ,Examining Fields}).
It is also affected by a feature that has not been discussed yet:
@@ -4240,7 +4392,8 @@ The intervening field, @code{$5}, is created with an empty value
and @code{NF} is updated with the value six.
@c FIXME: Verify that this is in POSIX
-@cindex dark corner
+@cindex dark corner, @code{NF} variable, decrementing
+@cindex @code{NF} variable, decrementing
Decrementing @code{NF} throws away the values of the fields
after the new value of @code{NF} and recomputes @code{$0}.
@value{DARKCORNER}
@@ -4253,9 +4406,11 @@ $ echo a b c d e f | awk '@{ print "NF =", NF;
@print{} a b c
@end example
-@cindex portability issues
+@c the comma before decrementing does NOT represent a tertiary entry
+@cindex portability, @code{NF} variable, decrementing
@strong{Caution:} Some versions of @command{awk} don't
rebuild @code{$0} when @code{NF} is decremented. Caveat emptor.
+@c ENDOFRANGE ficon
@node Field Separators, Constant Size, Changing Fields, Reading Files
@section Specifying How Fields Are Separated
@@ -4269,7 +4424,10 @@ rebuild @code{$0} when @code{NF} is decremented. Caveat emptor.
@cindex @code{FS} variable
@cindex fields, separating
-@cindex field separator, @code{FS}
+@c STARTOFRANGE fisepr
+@cindex field separators
+@c STARTOFRANGE fisepg
+@cindex fields, separating
The @dfn{field separator}, which is either a single character or a regular
expression, controls the way @command{awk} splits an input record into fields.
@command{awk} scans the input record for character sequences that
@@ -4288,14 +4446,13 @@ is split into three fields: @samp{m}, @samp{@bullet{}g}, and
@samp{@bullet{}gai@bullet{}pan}.
Note the leading spaces in the values of the second and third fields.
-@cindex common mistakes
-@cindex mistakes, common
-@cindex errors, common
+@cindex troubleshooting, @command{awk} uses @code{FS} not @code{IFS}
The field separator is represented by the built-in variable @code{FS}.
Shell programmers take note: @command{awk} does @emph{not} use the
name @code{IFS} that is used by the POSIX-compliant shells (such as
the Unix Bourne shell, @command{sh}, or @command{bash}).
+@cindex @code{FS} variable, changing value of
The value of @code{FS} can be changed in the @command{awk} program with the
assignment operator, @samp{=} (@pxref{Assignment Ops, ,Assignment Expressions}).
Often the right time to do this is at the beginning of execution
@@ -4310,6 +4467,7 @@ For example, here we set the value of @code{FS} to the string
awk 'BEGIN @{ FS = "," @} ; @{ print $2 @}'
@end example
+@cindex @code{BEGIN} pattern
@noindent
Given the input line:
@@ -4321,8 +4479,9 @@ John Q. Smith, 29 Oak St., Walamazoo, MI 42139
this @command{awk} program extracts and prints the string
@samp{@bullet{}29@bullet{}Oak@bullet{}St.}.
-@cindex field separator, choice of
+@cindex field separators, choice of
@cindex regular expressions as field separators
+@cindex field separators, regular expressions as
Sometimes the input data contains separator characters that don't
separate fields the way you thought they would. For instance, the
person's name in the example we just used might have a title or
@@ -4341,6 +4500,8 @@ separator characters carefully to prevent such problems.
(If the data is not in a form that is easy to process, perhaps you
can massage it first with a separate @command{awk} program.)
+@cindex newlines, as field separators
+@cindex whitespace, as field separators
Fields are normally separated by whitespace sequences
(spaces, tabs, and newlines), not by single spaces. Two spaces in a row do not
delimit an empty field. The default value of the field separator @code{FS}
@@ -4361,6 +4522,10 @@ rules.
@node Regexp Field Splitting, Single Character Fields, Field Separators, Field Separators
@subsection Using Regular Expressions to Separate Fields
+@c STARTOFRANGE regexpfs
+@cindex regular expressions, as field separators
+@c STARTOFRANGE fsregexp
+@cindex field separators, regular expressions as
The previous @value{SUBSECTION}
discussed the use of single characters or simple strings as the
value of @code{FS}.
@@ -4374,10 +4539,10 @@ FS = ", \t"
@noindent
makes every area of an input line that consists of a comma followed by a
-space and a tab into a field separator.
+space and a TAB into a field separator.
@ifinfo
(@samp{\t}
-is an @dfn{escape sequence} that stands for a tab;
+is an @dfn{escape sequence} that stands for a TAB;
@pxref{Escape Sequences},
for the complete list of similar escape sequences.)
@end ifinfo
@@ -4414,8 +4579,9 @@ $ echo ' a b c d ' | awk 'BEGIN @{ FS = "[ \t\n]+" @}
@end example
@noindent
-@cindex null string
-@cindex empty string
+@cindex null strings
+@cindex strings, null
+@cindex empty strings, See null strings
In this case, the first field is @dfn{null} or empty.
The stripping of leading and trailing whitespace also comes into
@@ -4434,12 +4600,15 @@ with leading whitespace intact. The assignment to @code{$2} rebuilds
separated by the value of @code{OFS}. Because the leading whitespace
was ignored when finding @code{$1}, it is not part of the new @code{$0}.
Finally, the last @code{print} statement prints the new @code{$0}.
+@c ENDOFRANGE regexpfs
+@c ENDOFRANGE fsregexp
@node Single Character Fields, Command Line Field Separator, Regexp Field Splitting, Field Separators
@subsection Making Each Character a Separate Field
-@cindex differences between @command{gawk} and @command{awk}
+@cindex differences in @command{awk} and @command{gawk}, single-character fields
@cindex single-character fields
+@cindex fields, single-character
There are times when you may want to examine each character
of a record separately. This can be done in @command{gawk} by
simply assigning the null string (@code{""}) to @code{FS}. In this case,
@@ -4457,7 +4626,8 @@ $ echo a b | gawk 'BEGIN @{ FS = "" @}
@print{} Field 3 is b
@end example
-@cindex dark corner
+@cindex dark corner, @code{FS} as null string
+@cindex FS variable, as null string
Traditionally, the behavior of @code{FS} equal to @code{""} was not defined.
In this case, most versions of Unix @command{awk} simply treat the entire record
as only having one field.
@@ -4470,9 +4640,12 @@ behaves this way.
@node Command Line Field Separator, Field Splitting Summary, Single Character Fields, Field Separators
@subsection Setting @code{FS} from the Command Line
@cindex @code{-F} option
-@cindex command-line option, @code{-F}
-@cindex field separator, on command line
-@cindex command line, setting @code{FS} on
+@cindex options, command-line
+@cindex command line, options
+@cindex field separators, on command line
+@c The comma before "setting" does NOT represent a tertiary
+@cindex command line, @code{FS} on, setting
+@cindex @code{FS} variable, setting from command line
@code{FS} can be set on the command line. Use the @option{-F} option to
do so. For example:
@@ -4483,7 +4656,8 @@ awk -F, '@var{program}' @var{input-files}
@noindent
sets @code{FS} to the @samp{,} character. Notice that the option uses
-a capital @samp{F} instead of a lowercase @option{-f}, which specifies a file
+an uppercase @samp{F} instead of a lowercase @samp{f}. The latter
+option (@option{-f}) specifies a file
containing an @command{awk} program. Case is significant in command-line
options:
the @option{-F} and @option{-f} options have nothing to do with each other.
@@ -4502,16 +4676,18 @@ awk -F\\\\ '@dots{}' files @dots{}
@end example
@noindent
+@cindex @code{\} (backslash), as field separators
+@cindex backslash (@code{\}), as field separators
Because @samp{\} is used for quoting in the shell, @command{awk} sees
@samp{-F\\}. Then @command{awk} processes the @samp{\\} for escape
characters (@pxref{Escape Sequences}), finally yielding
a single @samp{\} to use for the field separator.
-@cindex historical features
+@c @cindex historical features
As a special case, in compatibility mode
(@pxref{Options, ,Command-Line Options}),
if the argument to @option{-F} is @samp{t}, then @code{FS} is set to
-the tab character. If you type @samp{-F\t} at the
+the TAB character. If you type @samp{-F\t} at the
shell, without any quotes, the @samp{\} gets deleted, so @command{awk}
figures that you really want your fields to be separated with tabs and
not @samp{t}s. Use @samp{-v FS="t"} or @samp{-F"[t]"} on the command line
@@ -4558,6 +4734,8 @@ separator, instead of the @samp{-} in the phone number that was
originally intended. This demonstrates why you have to be careful in
choosing your field and record separators.
+@c The comma after "password files" does NOT start a tertiary
+@cindex Unix @command{awk}, password files, field separators and
Perhaps the most common use of a single character as the field
separator occurs when processing the Unix system password file.
On many Unix systems, each user has a separate entry in the system password
@@ -4579,12 +4757,12 @@ awk -F: '$2 == ""' /etc/passwd
@end example
@node Field Splitting Summary, , Command Line Field Separator, Field Separators
-@subsection Field Splitting Summary
+@subsection Field-Splitting Summary
The following
table
summarizes how fields are split, based on the
-value of @code{FS}. (@samp{==} means ``is equal to.'')
+value of @code{FS} (@samp{==} means ``is equal to''):
@table @code
@item FS == " "
@@ -4611,17 +4789,17 @@ POSIX standard.)
@c fakenode --- for prepinfo
@subheading Advanced Notes: Changing @code{FS} Does Not Affect the Fields
-@cindex @command{awk} language, POSIX version
-@cindex POSIX @command{awk}
+@cindex POSIX @command{awk}, field separators and
+@cindex field separators, POSIX and
According to the POSIX standard, @command{awk} is supposed to behave
as if each record is split into fields at the time it is read.
In particular, this means that if you change the value of @code{FS}
after a record is read, the value of the fields (i.e., how they were split)
should reflect the old value of @code{FS}, not the new one.
-@cindex dark corner
+@cindex dark corner, field separators
@cindex @command{sed} utility
-@cindex stream editor
+@cindex stream editors
However, many implementations of @command{awk} do not work this way. Instead,
they defer splitting the fields until a field is actually
referenced. The fields are split
@@ -4652,6 +4830,8 @@ prints something like:
@example
root:nSijPlPhZZwgE:0:0:Root:/:
@end example
+@c ENDOFRANGE fisepr
+@c ENDOFRANGE fisepg
@node Constant Size, Multiple Line, Field Separators, Reading Files
@section Reading Fixed-Width Data
@@ -4668,6 +4848,9 @@ If you are a novice @command{awk} user, you might want to skip it on
the first reading.)
@end ifinfo
+@cindex data, fixed-width
+@cindex fixed-width data
+@cindex advanced features, fixed-width data
@command{gawk} @value{PVERSION} 2.13 introduced a facility for dealing with
fixed-width fields with no distinctive field separator. For example,
data of this nature arises in the input for old Fortran programs where
@@ -4682,8 +4865,10 @@ can use a series of @code{substr} calls on @code{$0}
(@pxref{String Functions, ,String Manipulation Functions}),
this is awkward and inefficient for a large number of fields.
-@cindex fatal errors
+@c comma before specifying is part of tertiary
+@cindex troubleshooting, fatal errors, field widths, specifying
@cindex @command{w} utility
+@cindex @code{FIELDWIDTHS} variable
The splitting of an input record into fixed-width fields is specified by
assigning a string containing space-separated numbers to the built-in
variable @code{FIELDWIDTHS}. Each number specifies the width of the field,
@@ -4711,7 +4896,7 @@ dave ttyq4 26Jun9115days 46 46 wnewmail
The following program takes the above input, converts the idle time to
number of seconds, and prints out the first two fields and the calculated
-idle time.
+idle time:
@strong{Note:}
This program uses a number of @command{awk} features that
@@ -4762,8 +4947,9 @@ a system with card readers is another story!)
Exercise: Write a ballot card reading program
@end ignore
-Assigning a value to @code{FS} causes @command{gawk} to return to using
-@code{FS} for field splitting. Use @samp{FS = FS} to make this happen,
+@cindex @command{gawk}, splitting fields and
+Assigning a value to @code{FS} causes @command{gawk} to use
+@code{FS} for field splitting again. Use @samp{FS = FS} to make this happen,
without having to know the current value of @code{FS}.
In order to tell which kind of field splitting is in effect,
use @code{PROCINFO["FS"]}
@@ -4787,14 +4973,18 @@ for an example of such a function).
@node Multiple Line, Getline, Constant Size, Reading Files
@section Multiple-Line Records
-@cindex multiple line records
-@cindex input, multiple line records
-@cindex reading files, multiple line records
-@cindex records, multiple line
+@c STARTOFRANGE recm
+@cindex records, multiline
+@c STARTOFRANGE imr
+@cindex input, multiline records
+@c STARTOFRANGE frm
+@cindex files, reading, multiline records
+@cindex input, files, See input files
In some databases, a single line cannot conveniently hold all the
information in one entry. In such cases, you can use multiline
records. The first step in doing this is to choose your data format.
+@cindex record separators, with multiline records
One technique is to use an unusual character or string to separate
records. For example, you could use the formfeed character (written
@samp{\f} in @command{awk}, as in C) to separate them, making each record
@@ -4803,11 +4993,12 @@ a page of the file. To do this, just set the variable @code{RS} to
other character could equally well be used, as long as it won't be part
of the data in a record.
+@cindex @code{RS} variable, multiline records and
Another technique is to have blank lines separate records. By a special
dispensation, an empty string as the value of @code{RS} indicates that
records are separated by one or more blank lines. When @code{RS} is set
to the empty string, each record always ends at the first blank line
-encountered. The next record doesn't start until the first non-blank
+encountered. The next record doesn't start until the first nonblank
line that follows. No matter how many blank lines appear in a row, they
all act as one record separator.
(Blank lines must be completely empty; lines that contain only
@@ -4822,10 +5013,10 @@ In addition, a regular expression always matches the longest possible
sequence when there is a choice
(@pxref{Leftmost Longest, ,How Much Text Matches?}).
So the next record doesn't start until
-the first non-blank line that follows---no matter how many blank lines
+the first nonblank line that follows---no matter how many blank lines
appear in a row, they are considered one record separator.
-@cindex dark corner
+@cindex dark corner, multiline records
There is an important difference between @samp{RS = ""} and
@samp{RS = "\n\n+"}. In the first case, leading newlines in the input
@value{DF} are ignored, and if a file ends without extra blank lines
@@ -4833,6 +5024,7 @@ after the last record, the final newline is removed from the record.
In the second case, this special processing is not done.
@value{DARKCORNER}
+@cindex field separators, in multiline records
Now that the input is separated into records, the second step is to
separate the fields in the record. One way to do this is to divide each
of the lines into fields in the normal manner. This happens by default
@@ -4854,7 +5046,7 @@ variable @code{FS} to the string @code{"\n"}. (This simple regular
expression matches a single newline.)
A practical example of a @value{DF} organized this way might be a mailing
list, where each entry is separated by blank lines. Consider a mailing
-list in a file named @file{addresses}, that looks like this:
+list in a file named @file{addresses}, which looks like this:
@example
Jane Doe
@@ -4932,22 +5124,23 @@ always serves as a field separator, in addition to whatever value
@item RS == @var{regexp}
Records are separated by occurrences of characters that match @var{regexp}.
Leading and trailing matches of @var{regexp} delimit empty records.
-(This is a @command{gawk} extension, it is not specified by the
+(This is a @command{gawk} extension; it is not specified by the
POSIX standard.)
@end table
@cindex @code{RT} variable
In all cases, @command{gawk} sets @code{RT} to the input text that matched the
value specified by @code{RS}.
+@c ENDOFRANGE recm
+@c ENDOFRANGE imr
+@c ENDOFRANGE frm
@node Getline, , Multiple Line, Reading Files
@section Explicit Input with @code{getline}
-@cindex @code{getline} built-in function
+@c STARTOFRANGE getl
+@cindex @code{getline} command, explicit input with
@cindex input, explicit
-@cindex explicit input
-@cindex input, @code{getline} command
-@cindex reading files, @code{getline} command
So far we have been getting our input data from @command{awk}'s main
input stream---either the standard input (usually your terminal, sometimes
the output from another program) or from the
@@ -4963,10 +5156,10 @@ and study the @code{getline} command @emph{after} you have reviewed the
rest of this @value{DOCUMENT} and have a good knowledge of how @command{awk} works.
@cindex @code{ERRNO} variable
-@cindex differences between @command{gawk} and @command{awk}
-@cindex @code{getline}, return values
+@cindex differences in @command{awk} and @command{gawk}, @code{getline} command
+@cindex @code{getline} command, return values
The @code{getline} command returns one if it finds a record and zero if
-the end of the file is encountered. If there is some error in getting
+it encounters the end of the file. If there is some error in getting
a record, such as a file that cannot be opened, then @code{getline}
returns @minus{}1. In this case, @command{gawk} sets the variable
@code{ERRNO} to a string describing the error that occurred.
@@ -4997,8 +5190,7 @@ The @code{getline} command can be used without arguments to read input
from the current input file. All it does in this case is read the next
input record and split it up into fields. This is useful if you've
finished processing the current record, but want to do some special
-processing @emph{right now} on the next record. Here's an
-example:
+processing on the next record @emph{right now}. For example:
@example
@{
@@ -5049,6 +5241,8 @@ rule in the program. @xref{Next Statement, ,The @code{next} Statement}.
@node Getline/Variable, Getline/File, Plain Getline, Getline
@subsection Using @code{getline} into a Variable
+@c comma before using is NOT for tertiary
+@cindex variables, @code{getline} command into, using
You can use @samp{getline @var{var}} to read the next record from
@command{awk}'s input into the variable @var{var}. No other processing is
@@ -5058,8 +5252,7 @@ and you want to read it without triggering
any rules. This form of @code{getline} allows you to read that line
and store it in a variable so that the main
read-a-line-and-check-each-rule loop of @command{awk} never sees it.
-The following example swaps every two lines of input.
-The program is as follows:
+The following example swaps every two lines of input:
@example
@{
@@ -5101,7 +5294,9 @@ the value of @code{NF} do not change.
@cindex input redirection
@cindex redirection of input
-@cindex @code{<} I/O operator
+@cindex @code{<} (left angle bracket), @code{<} operator (I/O)
+@cindex left angle bracket (@code{<}), @code{<} operator (I/O)
+@cindex operators, input/output
Use @samp{getline < @var{file}} to read the next record from @var{file}.
Here @var{file} is a string-valued expression that
specifies the @value{FN}. @samp{< @var{file}} is called a @dfn{redirection}
@@ -5126,6 +5321,7 @@ Because the main input stream is not used, the values of @code{NR} and
the normal manner, so the values of @code{$0} and the other fields are
changed, resulting in a new value of @code{NF}.
+@cindex POSIX @command{awk}, @code{<} operator and
@c Thanks to Paul Eggert for initial wording here
According to POSIX, @samp{getline < @var{expression}} is ambiguous if
@var{expression} contains unparenthesized operators other than
@@ -5138,6 +5334,8 @@ rely on this. Parentheses make it easier to read.)
@node Getline/Variable/File, Getline/Pipe, Getline/File, Getline
@subsection Using @code{getline} into a Variable from a File
+@c comma before using is NOT for tertiary
+@cindex variables, @code{getline} command into, using
Use @samp{getline @var{var} < @var{file}} to read input
from the file
@@ -5164,9 +5362,10 @@ Such a record is replaced by the contents of the file
@end example
Note here how the name of the extra input file is not built into
-the program; it is taken directly from the data, from the second field on
+the program; it is taken directly from the data, specifically from the second field on
the @samp{@@include} line.
+@cindex @code{close} function
The @code{close} function is called to ensure that if two identical
@samp{@@include} lines appear in the input, the entire specified file is
included twice.
@@ -5182,9 +5381,11 @@ that does handle nested @samp{@@include} statements.
@node Getline/Pipe, Getline/Variable/Pipe, Getline/Variable/File, Getline
@subsection Using @code{getline} from a Pipe
-@cindex @code{|} I/O operator
+@cindex @code{|} (vertical bar), @code{|} operator (I/O)
+@cindex vertical bar (@code{|}), @code{|} operator (I/O)
@cindex input pipeline
-@cindex pipeline, input
+@cindex pipes, input
+@cindex operators, input/output
The output of a command can also be piped into @code{getline}, using
@samp{@var{command} | getline}. In
this case, the string @var{command} is run as a shell command and its output
@@ -5207,6 +5408,7 @@ produced by running the rest of the line as a shell command:
@end example
@noindent
+@cindex @code{close} function
The @code{close} function is called to ensure that if two identical
@samp{@@execute} lines appear in the input, the command is run for
each one.
@@ -5242,14 +5444,15 @@ bletch
@end example
@noindent
-Notice that this program ran the command @command{who} and printed the result.
+Notice that this program ran the command @command{who} and printed the previous result.
(If you try this program yourself, you will of course get different results,
depending upon who is logged in on your system.)
This variation of @code{getline} splits the record into fields, sets the
-value of @code{NF} and recomputes the value of @code{$0}. The values of
+value of @code{NF}, and recomputes the value of @code{$0}. The values of
@code{NR} and @code{FNR} are not changed.
+@cindex POSIX @command{awk}, @code{|} I/O operator and
@c Thanks to Paul Eggert for initial wording here
According to POSIX, @samp{@var{expression} | getline} is ambiguous if
@var{expression} contains unparenthesized operators other than
@@ -5264,6 +5467,8 @@ rely on this. Parentheses make it easier to read, anyway.)
@node Getline/Variable/Pipe, Getline/Coprocess, Getline/Pipe, Getline
@subsection Using @code{getline} into a Variable from a Pipe
+@c comma before using is NOT for tertiary
+@cindex variables, @code{getline} command into, using
When you use @samp{@var{command} | getline @var{var}}, the
output of @var{command} is sent through a pipe to
@@ -5297,9 +5502,13 @@ rely on this. Parentheses make it easier to read, anyway.)
@node Getline/Coprocess, Getline/Variable/Coprocess, Getline/Variable/Pipe, Getline
@subsection Using @code{getline} from a Coprocess
-@cindex coprocess
-@cindex @code{|&} I/O operator
-@cindex differences between @command{gawk} and @command{awk}
+@cindex coprocesses, @code{getline} from
+@c comma before using is NOT for tertiary
+@cindex @code{getline} command, coprocesses, using from
+@cindex @code{|} (vertical bar), @code{|&} operator (I/O)
+@cindex vertical bar (@code{|}), @code{|&} operator (I/O)
+@cindex operators, input/output
+@cindex differences in @command{awk} and @command{gawk}, input/output operators
Input into @code{getline} from a pipe is a one-way operation.
The command that is started with @samp{@var{command} | getline} only
@@ -5310,7 +5519,7 @@ for processing and then read the results back.
@command{gawk} allows you start a @dfn{coprocess}, with which two-way
communications are possible. This is done with the @samp{|&}
operator.
-Typically, you write data to the coprocess first, and then
+Typically, you write data to the coprocess first and then
read results back, as shown in the following:
@example
@@ -5325,7 +5534,7 @@ The values of @code{NR} and
@code{FNR} are not changed,
because the main input stream is not used.
However, the record is split into fields in
-the normal manner, thus changing the values of @code{$0}, the other fields,
+the normal manner, thus changing the values of @code{$0}, of the other fields,
and of @code{NF}.
Coprocesses are an advanced feature. They are discussed here only because
@@ -5335,6 +5544,8 @@ where coprocesses are discussed in more detail.
@node Getline/Variable/Coprocess, Getline Notes, Getline/Coprocess, Getline
@subsection Using @code{getline} into a Variable from a Coprocess
+@c comma before using is NOT for tertiary
+@cindex variables, @code{getline} command into, using
When you use @samp{@var{command} |& getline @var{var}}, the output from
the coprocess @var{command} is sent through a two-way pipe to @code{getline}
@@ -5352,7 +5563,7 @@ where coprocesses are discussed in more detail.
@end ifinfo
@node Getline Notes, Getline Summary, Getline/Variable/Coprocess, Getline
-@subsection Points About @code{getline} to Remember
+@subsection Points to Remember About @code{getline}
Here are some miscellaneous points about @code{getline} that
you should bear in mind:
@@ -5363,20 +5574,22 @@ When @code{getline} changes the value of @code{$0} and @code{NF},
program and start testing the new record against every pattern.
However, the new record is tested against any subsequent rules.
-@cindex differences between @command{gawk} and @command{awk}
-@cindex limitations
-@cindex implementation limits
+@cindex differences in @command{awk} and @command{gawk}, implementation limitations
+@cindex implementation issues, @command{gawk}, limits
+@cindex @command{awk}, implementations, limits
+@cindex @command{gawk}, implementation issues, limits
@item
Many @command{awk} implementations limit the number of pipelines that an @command{awk}
program may have open to just one. In @command{gawk}, there is no such limit.
You can open as many pipelines (and coprocesses) as the underlying operating
system permits.
-@cindex side effects
-@cindex @code{FILENAME} variable
-@cindex dark corner
-@cindex @code{getline}, setting @code{FILENAME}
-@cindex @code{FILENAME}, being set by @code{getline}
+@cindex side effects, @code{FILENAME} variable
+@c The comma before "setting with" does NOT represent a tertiary
+@cindex @code{FILENAME} variable, @code{getline}, setting with
+@cindex dark corner, @code{FILENAME} variable
+@cindex @code{getline} command, @code{FILENAME} variable and
+@cindex @code{BEGIN} pattern, @code{getline} and
@item
An interesting side effect occurs if you use @code{getline} without a
redirection inside a @code{BEGIN} rule. Because an unredirected @code{getline}
@@ -5391,14 +5604,15 @@ also @pxref{Auto-set, ,Built-in Variables That Convey Information}.)
@node Getline Summary, , Getline Notes, Getline
@subsection Summary of @code{getline} Variants
+@cindex @code{getline} command, variants
The following table summarizes the eight variants of @code{getline},
listing which built-in variables are set by each one.
@multitable {@var{command} @code{|& getline} @var{var}} {1234567890123456789012345678901234567890}
-@item @code{getline} @tab Sets @code{$0}, @code{NF}, @code{FNR} and @code{NR}
+@item @code{getline} @tab Sets @code{$0}, @code{NF}, @code{FNR}, and @code{NR}
-@item @code{getline} @var{var} @tab Sets @var{var}, @code{FNR} and @code{NR}
+@item @code{getline} @var{var} @tab Sets @var{var}, @code{FNR}, and @code{NR}
@item @code{getline <} @var{file} @tab Sets @code{$0} and @code{NF}
@@ -5408,19 +5622,23 @@ listing which built-in variables are set by each one.
@item @var{command} @code{| getline} @var{var} @tab Sets @var{var}
-@item @var{command} @code{|& getline} @tab Sets @code{$0} and @code{NF}
-(this is a @command{gawk} extension)
+@item @var{command} @code{|& getline} @tab Sets @code{$0} and @code{NF}.
+This is a @command{gawk} extension
-@item @var{command} @code{|& getline} @var{var} @tab Sets @var{var}
-(this is a @command{gawk} extension)
+@item @var{command} @code{|& getline} @var{var} @tab Sets @var{var}.
+This is a @command{gawk} extension
@end multitable
+@c ENDOFRANGE getl
+@c ENDOFRANGE inex
+@c ENDOFRANGE infir
@node Printing, Expressions, Reading Files, Top
@chapter Printing Output
+@c STARTOFRANGE prnt
@cindex printing
-@cindex output
-One of the most common programming actions is to @dfn{print} or output,
+@cindex output, printing, See printing
+One of the most common programming actions is to @dfn{print}, or output,
some or all of the input. Use the @code{print} statement
for simple output, and the @code{printf} statement
for fancier formatting.
@@ -5430,9 +5648,12 @@ you cannot specify @emph{how} to print them---how many
columns, whether to use exponential notation or not, and so on.
(For the exceptions, @pxref{Output Separators}, and
@ref{OFMT, ,Controlling Numeric Output with @code{print}}.)
-For that, you need the @code{printf} statement
+For printing with specifications, you need the @code{printf} statement
(@pxref{Printf, ,Using @code{printf} Statements for Fancier Printing}).
+@c STARTOFRANGE prnts
+@cindex @code{print} statement
+@cindex @code{printf} statement
Besides basic and formatted printing, this @value{CHAPTER}
also covers I/O redirections to files and pipes, introduces
the special @value{FN}s that @command{gawk} processes internally,
@@ -5454,7 +5675,6 @@ and discusses the @code{close} built-in function.
@node Print, Print Examples, Printing, Printing
@section The @code{print} Statement
-@cindex @code{print} statement
The @code{print} statement is used to produce output with simple, standardized
formatting. Specify only the strings or numbers to print, in a
@@ -5475,13 +5695,16 @@ The items to print can be constant strings or numbers, fields of the
current record (such as @code{$1}), variables, or any @command{awk}
expression. Numeric values are converted to strings and then printed.
+@cindex records, printing
+@cindex lines, blank, printing
+@cindex text, printing
The simple statement @samp{print} with no items is equivalent to
@samp{print $0}: it prints the entire current record. To print a blank
line, use @samp{print ""}, where @code{""} is the empty string.
To print a fixed piece of text, use a string constant, such as
@w{@code{"Don't Panic"}}, as one item. If you forget to use the
-double quote characters, your text is taken as an @command{awk}
-expression and you will probably get an error. Keep in mind that a
+double-quote characters, your text is taken as an @command{awk}
+expression, and you will probably get an error. Keep in mind that a
space is printed between any two items.
@node Print Examples, Output Separators, Print, Printing
@@ -5492,6 +5715,7 @@ isn't limited to only one line. If an item value is a string that contains a
newline, the newline is output along with the rest of the string. A
single @code{print} statement can make any number of lines this way.
+@cindex newlines, printing
The following is an example of printing a string that contains embedded newlines
(the @samp{\n} is an escape sequence, used to represent the newline
character; @pxref{Escape Sequences}):
@@ -5503,6 +5727,7 @@ $ awk 'BEGIN @{ print "line one\nline two\nline three" @}'
@print{} line three
@end example
+@cindex fields, printing
The next example, which is run on the @file{inventory-shipped} file,
prints the first two fields of each input record, with a space between
them:
@@ -5515,9 +5740,9 @@ $ awk '@{ print $1, $2 @}' inventory-shipped
@dots{}
@end example
-@cindex common mistakes
-@cindex mistakes, common
-@cindex errors, common
+@cindex @code{print} statement, commas, omitting
+@c comma does NOT start tertiary
+@cindex troubleshooting, @code{print} statement, omitting commas
A common mistake in using the @code{print} statement is to omit the comma
between two items. This often has the effect of making the items run
together in the output, with no space. The reason for this is that
@@ -5532,6 +5757,8 @@ $ awk '@{ print $1 $2 @}' inventory-shipped
@dots{}
@end example
+@c comma does NOT start tertiary
+@cindex @code{BEGIN} pattern, headings, adding
To someone unfamiliar with the @file{inventory-shipped} file, neither
example's output makes much sense. A heading line at the beginning
would make it clearer. Let's add some headings to our table of months
@@ -5571,6 +5798,9 @@ awk 'BEGIN @{ print "Month Crates"
@end group
@end example
+@c comma does NOT start tertiary
+@cindex @code{printf} statement, columns, aligning
+@cindex columns, aligning
Lining up columns this way can get pretty
complicated when there are many columns to fix. Counting spaces for two
or three columns is simple, but any more than this can take up
@@ -5578,18 +5808,17 @@ a lot of time. This is why the @code{printf} statement was
created (@pxref{Printf, ,Using @code{printf} Statements for Fancier Printing});
one of its specialties is lining up columns of data.
-@cindex line continuation
+@cindex line continuations, in @code{print} statement
+@cindex @code{print} statement, line continuations and
@strong{Note:} You can continue either a @code{print} or
@code{printf} statement simply by putting a newline after any comma
(@pxref{Statements/Lines, ,@command{awk} Statements Versus Lines}).
+@c ENDOFRANGE prnts
@node Output Separators, OFMT, Print Examples, Printing
@section Output Separators
-@cindex output field separator, @code{OFS}
-@cindex output record separator, @code{ORS}
@cindex @code{OFS} variable
-@cindex @code{ORS} variable
As mentioned previously, a @code{print} statement contains a list
of items separated by commas. In the output, the items are normally
separated by single spaces. However, this doesn't need to be the case;
@@ -5605,6 +5834,10 @@ record, and then outputs a string called the @dfn{output record separator}
value of @code{ORS} is the string @code{"\n"}; i.e., a newline
character. Thus, each @code{print} statement normally makes a separate line.
+@cindex output, records
+@cindex output record separator, See @code{ORS} variable
+@cindex @code{ORS} variable
+@cindex @code{BEGIN} pattern, @code{OFS}/@code{ORS} variables, assigning values to
In order to change how output fields and records are separated, assign
new values to the variables @code{OFS} and @code{ORS}. The usual
place to do this is in the @code{BEGIN} rule
@@ -5644,10 +5877,9 @@ is run together on a single line.
@node OFMT, Printf, Output Separators, Printing
@section Controlling Numeric Output with @code{print}
-@cindex @code{OFMT} variable
-@cindex numeric output format
-@cindex format, numeric output
-@cindex output format specifier, @code{OFMT}
+@cindex numeric, output format
+@c the comma does NOT start a secondary
+@cindex formats, numeric output
When the @code{print} statement is used to print numeric values,
@command{awk} internally converts the number to a string of characters
and prints that string. @command{awk} uses the @code{sprintf} function
@@ -5660,6 +5892,10 @@ numbers can be formatted. The different format specifications are discussed
more fully in
@ref{Control Letters, , Format-Control Letters}.
+@cindex @code{sprintf} function
+@cindex @code{OFMT} variable
+@c the comma before OFMT does NOT start a tertiary
+@cindex output, format specifier, @code{OFMT}
The built-in variable @code{OFMT} contains the default format specification
that @code{print} uses with @code{sprintf} when it wants to convert a
number to a string for printing.
@@ -5676,19 +5912,20 @@ $ awk 'BEGIN @{
@end example
@noindent
-@cindex dark corner
-@cindex @command{awk} language, POSIX version
-@cindex POSIX @command{awk}
+@cindex dark corner, @code{OFMT} variable
+@cindex POSIX @command{awk}, @code{OFMT} variable and
+@cindex @code{OFMT} variable, POSIX @command{awk} and
According to the POSIX standard, @command{awk}'s behavior is undefined
if @code{OFMT} contains anything but a floating-point conversion specification.
@value{DARKCORNER}
@node Printf, Redirection, OFMT, Printing
@section Using @code{printf} Statements for Fancier Printing
-@cindex formatted output
-@cindex output, formatted
-@cindex @code{printf} statement
+@c STARTOFRANGE printfs
+@cindex @code{printf} statement
+@cindex output, formatted
+@cindex formatting output
For more precise control over the output format than what is
normally provided by @code{print}, use @code{printf}.
@code{printf} can be used to
@@ -5719,10 +5956,10 @@ printf @var{format}, @var{item1}, @var{item2}, @dots{}
@noindent
The entire list of arguments may optionally be enclosed in parentheses. The
parentheses are necessary if any of the item expressions use the @samp{>}
-relational operator; otherwise it can be confused with a redirection
+relational operator; otherwise, it can be confused with a redirection
(@pxref{Redirection, ,Redirecting Output of @code{print} and @code{printf}}).
-@cindex format string
+@cindex format strings
The difference between @code{printf} and @code{print} is the @var{format}
argument. This is an expression whose value is taken as a string; it
specifies how to output each of the other arguments. It is called the
@@ -5755,8 +5992,8 @@ the message is printed.
@node Control Letters, Format Modifiers, Basic Printf, Printf
@subsection Format-Control Letters
-@cindex @code{printf}, format-control characters
-@cindex format specifier, @code{printf}
+@cindex @code{printf} statement, format-control characters
+@cindex format specifiers, @code{printf} statement
A format specifier starts with the character @samp{%} and ends with
a @dfn{format-control letter}---it tells the @code{printf} statement
@@ -5826,12 +6063,13 @@ These print an unsigned hexadecimal integer;
instead of @samp{a} through @samp{f}.
@item %%
-This isn't a format-control letter but it does have meaning---the
+This isn't a format-control letter, but it does have meaning---the
sequence @samp{%%} outputs one @samp{%}; it does not consume an
argument and it ignores any modifiers.
@end table
-@cindex dark corner
+@cindex dark corner, format-control characters
+@cindex @command{gawk}, format-control characters
@strong{Note:}
When using the integer format-control letters for values that are outside
the range of a C @code{long} integer, @command{gawk} switches to the
@@ -5842,8 +6080,10 @@ invalid values or do something else entirely.
@node Format Modifiers, Printf Examples, Control Letters, Printf
@subsection Modifiers for @code{printf} Formats
-@cindex @code{printf}, modifiers
-@cindex modifiers (in format specifiers)
+@c STARTOFRANGE pfm
+@cindex @code{printf} statement, modifiers
+@c the comma here does NOT start a secondary
+@cindex modifiers, in format specifiers
A format specification can also include @dfn{modifiers} that can control
how much of the item's value is printed, as well as how much space it gets.
The modifiers come between the @samp{%} and the format-control letter.
@@ -5853,16 +6093,17 @@ spaces in the output. Here are the possible modifiers, in the order in
which they may appear:
@table @code
-@cindex differences between @command{gawk} and @command{awk}
-@cindex @code{printf}, positional specifier
-@cindex positional specifier, @code{printf}
+@cindex differences in @command{awk} and @command{gawk}, @code{print}/@code{printf} statements
+@cindex @code{printf} statement, positional specifiers
+@c the command does NOT start a secondary
+@cindex positional specifiers, @code{printf} statement
@item @var{N}$
An integer constant followed by a @samp{$} is a @dfn{positional specifier}.
Normally, format specifications are applied to arguments in the order
given in the format string. With a positional specifier, the format
specification is applied to a specific argument, instead of what
would be the next argument in the list. Positional specifiers begin
-counting with one:
+counting with one. Thus:
@example
printf "%s %s\n", "don't", "panic"
@@ -5880,7 +6121,7 @@ which describes how and why to use positional specifiers.
For now, we will not use them.
@item -
-The minus sign, used before the width modifier (see further on in
+The minus sign, used before the width modifier (see later on in
this table),
says to left-justify
the argument within its specified width. Normally, the argument
@@ -5898,7 +6139,7 @@ For numeric conversions, prefix positive values with a space and
negative values with a minus sign.
@item +
-The plus sign, used before the width modifier (see further on in
+The plus sign, used before the width modifier (see later on in
this table),
says to always supply a sign for numeric conversions, even if the data
to format is positive. The @samp{+} overrides the space modifier.
@@ -6013,10 +6254,9 @@ printf "%" w "." p "s\n", s
@noindent
This is not particularly easy to read but it does work.
-@cindex fatal errors
-@cindex @command{awk} language, POSIX version
-@cindex POSIX @command{awk}
-@cindex lint checks
+@c @cindex lint checks
+@cindex troubleshooting, fatal errors, @code{printf} format strings
+@cindex POSIX @command{awk}, @code{printf} format strings and
C programmers may be used to supplying additional
@samp{l}, @samp{L}, and @samp{h}
modifiers in @code{printf} format strings. These are not valid in @command{awk}.
@@ -6025,6 +6265,7 @@ If @option{--lint} is provided on the command line
(@pxref{Options, ,Command-Line Options}),
@command{gawk} warns about their use. If @option{--posix} is supplied,
their use is a fatal error.
+@c ENDOFRANGE pfm
@node Printf Examples, , Format Modifiers, Printf
@subsection Examples Using @code{printf}
@@ -6111,6 +6352,7 @@ At this point, it would be a worthwhile exercise to use the
@file{inventory-shipped} example that was covered earlier in the @value{SECTION}
on the @code{print} statement
(@pxref{Print, ,The @code{print} Statement}).
+@c ENDOFRANGE printfs
@node Redirection, Special Files, Printf, Printing
@section Redirecting Output of @code{print} and @code{printf}
@@ -6127,13 +6369,18 @@ A redirection appears after the @code{print} or @code{printf} statement.
Redirections in @command{awk} are written just like redirections in shell
commands, except that they are written inside the @command{awk} program.
+@c the commas here are part of the see also
+@cindex @code{print} statement, See Also redirection, of output
+@cindex @code{printf} statement, See Also redirection, of output
There are four forms of output redirection: output to a file, output
appended to a file, output through a pipe to another command, and output
to a coprocess. They are all shown for the @code{print} statement,
but they work identically for @code{printf}:
@table @code
-@cindex @code{>} I/O operator
+@cindex @code{>} (right angle bracket), @code{>} operator (I/O)
+@cindex right angle bracket (@code{>}), @code{>} operator (I/O)
+@cindex operators, input/output
@item print @var{items} > @var{output-file}
This type of redirection prints the items into the output file named
@var{output-file}. The @value{FN} @var{output-file} can be any
@@ -6165,7 +6412,8 @@ $ cat name-list
@noindent
Each output file contains one name or number per line.
-@cindex @code{>>} I/O operator
+@cindex @code{>} (right angle bracket), @code{>>} operator (I/O)
+@cindex right angle bracket (@code{>}), @code{>>} operator (I/O)
@item print @var{items} >> @var{output-file}
This type of redirection prints the items into the pre-existing output file
named @var{output-file}. The difference between this and the
@@ -6174,9 +6422,9 @@ single-@samp{>} redirection is that the old contents (if any) of
appended to the file.
If @var{output-file} does not exist, then it is created.
-@cindex @code{|} I/O operator
-@cindex pipes for output
-@cindex output, piping
+@cindex @code{|} (vertical bar), @code{|} operator (I/O)
+@cindex pipes, output
+@cindex output, pipes
@item print @var{items} | @var{command}
It is also possible to send output to another program through a pipe
instead of into a file. This type of redirection opens a pipe to
@@ -6218,14 +6466,14 @@ close(report)
@end example
The message is built using string concatenation and saved in the variable
-@code{m}. It is then sent down the pipeline to the @command{mail} program.
+@code{m}. It's then sent down the pipeline to the @command{mail} program.
(The parentheses group the items to concatenate---see
@ref{Concatenation, ,String Concatenation}.)
The @code{close} function is called here because it's a good idea to close
the pipe as soon as all the intended output has been sent to it.
@xref{Close Files And Pipes, ,Closing Input and Output Redirections},
-for more information on this.
+for more information.
This example also illustrates the use of a variable to represent
a @var{file} or @var{command}---it is not necessary to always
@@ -6233,15 +6481,16 @@ use a string constant. Using a variable is generally a good idea,
because @command{awk} requires that the string value be spelled identically
every time.
-@cindex coprocess
-@cindex @code{|&} I/O operator
-@cindex differences between @command{gawk} and @command{awk}
+@cindex coprocesses
+@cindex @code{|} (vertical bar), @code{|&} operator (I/O)
+@cindex operators, input/output
+@cindex differences in @command{awk} and @command{gawk}, input/output operators
@item print @var{items} |& @var{command}
This type of redirection prints the items to the input of @var{command}.
The difference between this and the
single-@samp{|} redirection is that the output from @var{command}
can be read with @code{getline}.
-Thus @var{command} is a @dfn{coprocess}, that works together with,
+Thus @var{command} is a @dfn{coprocess}, which works together with,
but subsidiary to, the @command{awk} program.
This feature is a @command{gawk} extension, and is not available in
@@ -6251,13 +6500,11 @@ for a more complete discussion.
@end table
Redirecting output using @samp{>}, @samp{>>}, @samp{|}, or @samp{|&}
-asks the system to open a file, pipe, or coprocess, only if the particular
+asks the system to open a file, pipe, or coprocess only if the particular
@var{file} or @var{command} you specify has not already been written
to by your program or if it has been closed since it was last written to.
-@cindex common mistakes
-@cindex mistakes, common
-@cindex errors, common
+@cindex troubleshooting, printing
It is a common error to use @samp{>} redirection for the first @code{print}
to a file, and then to use @samp{>>} for subsequent output:
@@ -6275,9 +6522,11 @@ This is indeed how redirections must be used from the shell. But in
use @samp{>} for all the @code{print} statements, since the output file
is only opened once.
-@cindex differences between @command{gawk} and @command{awk}
-@cindex limitations
-@cindex implementation limits
+@cindex differences in @command{awk} and @command{gawk}, implementation limitations
+@c the comma here does NOT start a secondary
+@cindex implementation issues, @command{gawk}, limits
+@cindex @command{awk}, implementation issues, pipes
+@cindex @command{gawk}, implementation issues, pipes
@ifnotinfo
As mentioned earlier
(@pxref{Getline Notes, ,Points About @code{getline} to Remember}),
@@ -6293,17 +6542,16 @@ open as many pipelines as the underlying operating system permits.
@c fakenode --- for prepinfo
@subheading Advanced Notes: Piping into @command{sh}
-@cindex advanced notes
-@cindex shell, piping commands into
-@cindex piping commands into the shell
+@cindex advanced features, piping into @command{sh}
+@cindex shells, piping commands into
-A particularly powerful way to use redirection is to build command lines,
+A particularly powerful way to use redirection is to build command lines
and pipe them into the shell, @command{sh}. For example, suppose you
have a list of files brought over from a system where all the @value{FN}s
are stored in uppercase, and you wish to rename them to have names in
all lowercase. The following program is both simple and efficient:
-@cindex @command{mv} utility
+@c @cindex @command{mv} utility
@example
@{ printf("mv %s %s\n", $0, tolower($0)) | "sh" @}
@@ -6316,9 +6564,13 @@ uppercase characters converted to lowercase
The program builds up a list of command lines,
using the @command{mv} utility to rename the files.
It then sends the list to the shell for execution.
+@c ENDOFRANGE outre
+@c ENDOFRANGE reout
@node Special Files, Close Files And Pipes, Redirection, Printing
@section Special @value{FFN}s in @command{gawk}
+@c STARTOFRANGE gfn
+@cindex @command{gawk}, @value{FN}s in
@command{gawk} provides a number of special @value{FN}s that it interprets
internally. These @value{FN}s provide access to standard file descriptors,
@@ -6334,9 +6586,12 @@ process-related information, and TCP/IP networking.
@node Special FD, Special Process, Special Files, Special Files
@subsection Special Files for Standard Descriptors
@cindex standard input
+@cindex input, standard
@cindex standard output
-@cindex standard error output
+@cindex output, standard
+@cindex error output
@cindex file descriptors
+@cindex files, descriptors, See file descriptors
Running programs conventionally have three input and output streams
already available to them for reading and writing. These are known as
@@ -6345,10 +6600,11 @@ output}. These streams are, by default, connected to your terminal, but
they are often redirected with the shell, via the @samp{<}, @samp{<<},
@samp{>}, @samp{>>}, @samp{>&}, and @samp{|} operators. Standard error
is typically used for writing error messages; the reason there are two separate
-streams, standard output, and standard error, is so that they can be
+streams, standard output and standard error, is so that they can be
redirected separately.
-@cindex differences between @command{gawk} and @command{awk}
+@cindex differences in @command{awk} and @command{gawk}, error messages
+@cindex error handling
In other implementations of @command{awk}, the only way to write an error
message to standard error in an @command{awk} program is as follows:
@@ -6379,13 +6635,16 @@ Then opening @file{/dev/tty} fails.
streams, as well as any other inherited open files. If the @value{FN} matches
one of these special names when @command{gawk} redirects input or output,
then it directly uses the stream that the @value{FN} stands for.
-(These special @value{FN}s work for all operating systems that @command{gawk}
-has been ported to, not just those that are POSIX-compliant.):
-
-@cindex @file{/dev/stdin} special file
-@cindex @file{/dev/stdout} special file
-@cindex @file{/dev/stderr} special file
-@cindex @file{/dev/fd} special files
+These special @value{FN}s work for all operating systems that @command{gawk}
+has been ported to, not just those that are POSIX-compliant:
+
+@cindex @value{FN}s, standard streams in @command{gawk}
+@cindex @code{/dev/@dots{}} special files (@command{gawk})
+@cindex files, @code{/dev/@dots{}} special files
+@c @cindex @code{/dev/stdin} special file
+@c @cindex @code{/dev/stdout} special file
+@c @cindex @code{/dev/stderr} special file
+@c @cindex @code{/dev/fd} special files
@table @file
@item /dev/stdin
The standard input (file descriptor 0).
@@ -6413,9 +6672,7 @@ is to use @file{/dev/stderr}, like this:
print "Serious error detected!" > "/dev/stderr"
@end example
-@cindex common mistakes
-@cindex mistakes, common
-@cindex errors, common
+@cindex troubleshooting, quotes with @value{FN}s
Note the use of quotes around the @value{FN}.
Like any other redirection, the value must be a string.
It is a common error to omit the quotes, which leads
@@ -6425,6 +6682,8 @@ to confusing results.
@node Special Process, Special Network, Special FD, Special Files
@subsection Special Files for Process-Related Information
+@cindex files, for process information
+@cindex process information, files for
@command{gawk} also provides special @value{FN}s that give access to information
about the running @command{gawk} process. Each of these ``files'' provides
a single record of information. To read them more than once, they must
@@ -6432,11 +6691,10 @@ first be closed with the @code{close} function
(@pxref{Close Files And Pipes, ,Closing Input and Output Redirections}).
The @value{FN}s are:
-@cindex process information
-@cindex @file{/dev/pid} special file
-@cindex @file{/dev/pgrpid} special file
-@cindex @file{/dev/ppid} special file
-@cindex @file{/dev/user} special file
+@c @cindex @code{/dev/pid} special file
+@c @cindex @code{/dev/pgrpid} special file
+@c @cindex @code{/dev/ppid} special file
+@c @cindex @code{/dev/user} special file
@table @file
@item /dev/pid
Reading this file returns the process ID of the current process,
@@ -6482,8 +6740,8 @@ These special @value{FN}s may be used on the command line as @value{DF}s,
as well as for I/O redirections within an @command{awk} program.
They may not be used as source files with the @option{-f} option.
-@cindex automatic warnings
-@cindex warnings, automatic
+@c @cindex automatic warnings
+@c @cindex warnings, automatic
@strong{Note:}
The special files that provide process-related information are now considered
obsolete and will disappear entirely
@@ -6495,10 +6753,12 @@ To obtain process-related information, use the @code{PROCINFO} array.
@node Special Network, Special Caveats, Special Process, Special Files
@subsection Special Files for Network Communications
+@cindex networks, support for
+@cindex TCP/IP, support for
Starting with @value{PVERSION} 3.1 of @command{gawk}, @command{awk} programs
can open a two-way
-TCP/IP connection, acting as either a client or server.
+TCP/IP connection, acting as either a client or a server.
This is done using a special @value{FN} of the form:
@example
@@ -6519,15 +6779,18 @@ Full discussion is delayed until
@subsection Special @value{FFN} Caveats
Here is a list of things to bear in mind when using the
-special @value{FN}s that @command{gawk} provides.
+special @value{FN}s that @command{gawk} provides:
@itemize @bullet
+@cindex compatibility mode (@command{gawk}), @value{FN}s
+@cindex @value{FN}s, in compatibility mode
@item
Recognition of these special @value{FN}s is disabled if @command{gawk} is in
compatibility mode (@pxref{Options, ,Command-Line Options}).
-@cindex automatic warnings
-@cindex warnings, automatic
+@c @cindex automatic warnings
+@c @cindex warnings, automatic
+@cindex @code{PROCINFO} array
@item
@ifnottex
The
@@ -6548,9 +6811,9 @@ To obtain process-related information, use the @code{PROCINFO} array.
@item
Starting with @value{PVERSION} 3.1, @command{gawk} @emph{always}
interprets these special @value{FN}s.@footnote{Older versions of
-@command{gawk} would only interpret these names internally if the system
-did not actually have a a @file{/dev/fd} directory or any of the other
-above listed special files. Usually this didn't make a difference,
+@command{gawk} would interpret these names internally only if the system
+did not actually have a @file{/dev/fd} directory or any of the other
+special files listed earlier. Usually this didn't make a difference,
but sometimes it did; thus, it was decided to make @command{gawk}'s
behavior consistent on all systems and to have it always interpret
the special @value{FN}s itself.}
@@ -6561,14 +6824,22 @@ the time this does not matter; however, it is important to @emph{not}
close any of the files related to file descriptors 0, 1, and 2.
Doing so results in unpredictable behavior.
@end itemize
+@c ENDOFRANGE gfn
@node Close Files And Pipes, , Special Files, Printing
@section Closing Input and Output Redirections
-@cindex closing input files and pipes
-@cindex closing output files and pipes
-@cindex closing coprocesses
-@cindex coprocess
-@cindex @code{close} built-in function
+@cindex files, output, See output files
+@c STARTOFRANGE ifc
+@cindex input files, closing
+@c comma before closing is NOT start of tertiary
+@c STARTOFRANGE ofc
+@cindex output, files, closing
+@c STARTOFRANGE pc
+@cindex pipes, closing
+@c STARTOFRANGE cc
+@cindex coprocesses, closing
+@c comma before using is NOT start of tertiary
+@cindex @code{getline} command, coprocesses, using from
If the same @value{FN} or the same shell command is used with @code{getline}
more than once during the execution of an @command{awk} program
@@ -6583,6 +6854,7 @@ command associated with it is remembered by @command{awk}, and subsequent
writes to the same file or command are appended to the previous writes.
The file or pipe stays open until @command{awk} exits.
+@cindex @code{close} function
This implies that special steps are necessary in order to read the same
file again from the beginning, or to rerun a shell command (rather than
reading more output from the same command). The @code{close} function
@@ -6665,8 +6937,8 @@ program closes the pipe after each line of output, then each line makes
a separate message.
@end itemize
-@cindex differences between @command{gawk} and @command{awk}
-@cindex portability issues
+@cindex differences in @command{awk} and @command{gawk}, @code{close} function
+@cindex portability, @code{close} function and
If you use more files than the system allows you to have open,
@command{gawk} attempts to multiplex the available open files among
your @value{DF}s. @command{gawk}'s ability to do this depends upon the
@@ -6706,6 +6978,8 @@ is not closed and released until @code{close} is called or
does not represent a file, pipe or coprocess that was opened with
a redirection.
+@c comma is part of tertiary
+@cindex @code{|} (vertical bar), @code{|&} operator (I/O), pipes, closing
When using the @samp{|&} operator to communicate with a coprocess,
it is occasionally useful to be able to close one end of the two-way
pipe without closing the other.
@@ -6722,11 +6996,13 @@ which discusses it in more detail and gives an example.
@c fakenode --- for prepinfo
@subheading Advanced Notes: Using @code{close}'s Return Value
-@cindex advanced notes
-@cindex dark corner
-@cindex differences between @command{gawk} and @command{awk}
-@cindex @code{close}, return value
-@cindex return value from @code{close}
+@cindex advanced features, @code{close} function
+@cindex dark corner, @code{close} function
+@cindex @code{close} function, return values
+@c comma does NOT start secondary
+@cindex return values, @code{close} function
+@cindex differences in @command{awk} and @command{gawk}, @code{close} function
+@cindex Unix @command{awk}, @code{close} function and
In many versions of Unix @command{awk}, the @code{close} function
is actually a statement. It is a syntax error to try and use the return
@@ -6759,6 +7035,9 @@ The return value for closing a pipeline is particularly useful.
It allows you to get the output from a command as well as its
exit status.
+@cindex pipes, closing
+@c comma does NOT start tertiary
+@cindex POSIX @command{awk}, pipes, closing
For POSIX-compliant systems,
if the exit status is a number above 128, then the program
was terminated by a signal. Subtract 128 to get the signal number:
@@ -6776,10 +7055,16 @@ piping into @code{getline}. For commands piped into
from @code{print} or @code{printf}, the
return value from @code{close} is that of the library's
@code{pclose} function.
+@c ENDOFRANGE ifc
+@c ENDOFRANGE ofc
+@c ENDOFRANGE pc
+@c ENDOFRANGE cc
+@c ENDOFRANGE prnt
@node Expressions, Patterns and Actions, Printing, Top
@chapter Expressions
-@cindex expression
+@c STARTOFRANGE exps
+@cindex expressions
Expressions are the basic building blocks of @command{awk} patterns
and actions. An expression evaluates to a value that you can print, test,
@@ -6832,15 +7117,14 @@ have different forms, but are stored identically internally.
@menu
* Scalar Constants:: Numeric and string constants.
-* Non-decimal-numbers:: What are octal and hex numbers.
+* Nondecimal-numbers:: What are octal and hex numbers.
* Regexp Constants:: Regular Expression constants.
@end menu
-@node Scalar Constants, Non-decimal-numbers, Constants, Constants
+@node Scalar Constants, Nondecimal-numbers, Constants, Constants
@subsection Numeric and String Constants
-@cindex numeric constant
-@cindex numeric value
+@cindex numeric, constants
A @dfn{numeric constant} stands for a number. This number can be an
integer, a decimal fraction, or a number in scientific (exponential)
notation.@footnote{The internal representation of all numbers,
@@ -6858,21 +7142,22 @@ have the same value:
@cindex string constants
A string constant consists of a sequence of characters enclosed in
-double quote marks. For example:
+double-quotation marks. For example:
@example
"parrot"
@end example
@noindent
-@cindex differences between @command{gawk} and @command{awk}
+@cindex differences in @command{awk} and @command{gawk}, strings
+@cindex strings, length of
represents the string whose contents are @samp{parrot}. Strings in
@command{gawk} can be of any length, and they can contain any of the possible
eight-bit ASCII characters including ASCII @sc{nul} (character code zero).
Other @command{awk}
implementations may have difficulty with some character codes.
-@node Non-decimal-numbers, Regexp Constants, Scalar Constants, Constants
+@node Nondecimal-numbers, Regexp Constants, Scalar Constants, Constants
@subsection Octal and Hexadecimal Numbers
@cindex octal numbers
@cindex hexadecimal numbers
@@ -6882,16 +7167,16 @@ implementations may have difficulty with some character codes.
In @command{awk}, all numbers are in decimal; i.e., base 10. Many other
programming languages allow you to specify numbers in other bases, often
octal (base 8) and hexadecimal (base 16).
-In octal, the numbers go 0, 1, 2, 3, 4, 5, 6, 7, 10, 11, 12, etc..
-Just as @samp{11} in decimal is 1 times 10 plus 1, so
-@samp{11} in octal is 1 times 8, plus 1. This equals nine in decimal.
+In octal, the numbers go 0, 1, 2, 3, 4, 5, 6, 7, 10, 11, 12, etc.
+Just as @samp{11}, in decimal, is 1 times 10 plus 1, so
+@samp{11}, in octal, is 1 times 8, plus 1. This equals 9 in decimal.
In hexadecimal, there are 16 digits. Since the everyday decimal
-number system only has ten digits (@samp{0}---@samp{9}), the letters
+number system only has ten digits (@samp{0}--@samp{9}), the letters
@samp{a} through @samp{f} are used to represent the rest.
(Case in the letters is usually irrelevant; hexadecimal @samp{a} and @samp{A}
have the same value.)
-Thus, @samp{11} in
-hexadecimal is 1 times 16 plus 1, which equals 17 in decimal.
+Thus, @samp{11}, in
+hexadecimal, is 1 times 16 plus 1, which equals 17 in decimal.
Just by looking at plain @samp{11}, you can't tell what base it's in.
So, in C, C++, and other languages derived from C,
@@ -6902,7 +7187,7 @@ and hexadecimal numbers start with a leading @samp{0x} or @samp{0X}:
@table @code
@item 11
-Decimal 11.
+Decimal value 11.
@item 011
Octal 11, decimal value 9.
@@ -6922,13 +7207,15 @@ Being able to use octal and hexadecimal constants in your programs is most
useful when working with data that cannot be represented conveniently as
characters or as regular numbers, such as binary data of various sorts.
+@cindex @command{gawk}, octal numbers and
+@cindex @command{gawk}, hexadecimal numbers and
@command{gawk} allows the use of octal and hexadecimal
constants in your program text. However, such numbers in the input data
are not treated differently; doing so by default would break old
programs.
(If you really need to do this, use the @option{--non-decimal-data}
-command-line option,
-@pxref{Non-decimal Data, ,Allowing Non-Decimal Input Data}.)
+command-line option;
+@pxref{Nondecimal Data, ,Allowing Nondecimal Input Data}.)
If you have octal or hexadecimal data,
you can use the @code{strtonum} function
(@pxref{String Functions, ,String Manipulation Functions})
@@ -6939,7 +7226,7 @@ see @ref{Bitwise Functions, ,Using @command{gawk}'s Bit Manipulation Functions},
for more information.
Unlike some early C implementations, @samp{8} and @samp{9} are not valid
-in octal constants; e.g., @command{gawk} treats @samp{018} as decimal 18.
+in octal constants; e.g., @command{gawk} treats @samp{018} as decimal 18:
@example
$ gawk 'BEGIN @{ print "021 is", 021 ; print 018 @}'
@@ -6947,6 +7234,8 @@ $ gawk 'BEGIN @{ print "021 is", 021 ; print 018 @}'
@print{} 18
@end example
+@cindex compatibility mode (@command{gawk}), octal numbers
+@cindex compatibility mode (@command{gawk}), hexadecimal numbers
Octal and hexadecimal source code constants are a @command{gawk} extension.
If @command{gawk} is in compatibility mode
(@pxref{Options, ,Command-Line Options}),
@@ -6954,7 +7243,8 @@ they are not available.
@c fakenode --- for prepinfo
@subheading Advanced Notes: A Constant's Base Does Not Affect Its Value
-@cindex advanced notes
+@c comma before values does NOT start tertiary
+@cindex advanced features, constants, values of
Once a numeric constant has
been converted internally into a number,
@@ -6968,28 +7258,33 @@ $ gawk 'BEGIN @{ printf "0x11 is <%s>\n", 0x11 @}'
@print{} 0x11 is <17>
@end example
-@node Regexp Constants, , Non-decimal-numbers, Constants
+@node Regexp Constants, , Nondecimal-numbers, Constants
@subsection Regular Expression Constants
-@cindex @code{~} operator
-@cindex @code{!~} operator
+@c STARTOFRANGE rec
+@cindex regexp constants
+@cindex @code{~} (tilde), @code{~} operator
+@cindex tilde (@code{~}), @code{~} operator
+@cindex @code{!} (exclamation point), @code{!~} operator
+@cindex exclamation point (@code{!}), @code{!~} operator
A regexp constant is a regular expression description enclosed in
slashes, such as @code{@w{/^beginning and end$/}}. Most regexps used in
@command{awk} programs are constant, but the @samp{~} and @samp{!~}
matching operators can also match computed or ``dynamic'' regexps
(which are just ordinary strings or variables that contain a regexp).
+@c ENDOFRANGE cnst
@node Using Constant Regexps, Variables, Constants, Expressions
@section Using Regular Expression Constants
-@cindex dark corner
+@cindex dark corner, regexp constants
When used on the righthand side of the @samp{~} or @samp{!~}
operators, a regexp constant merely stands for the regexp that is to be
matched.
However, regexp constants (such as @code{/foo/}) may be used like simple expressions.
When a
regexp constant appears by itself, it has the same meaning as if it appeared
-in a pattern, i.e.; @samp{($0 ~ /foo/)}
+in a pattern, i.e., @samp{($0 ~ /foo/)}
@value{DARKCORNER}
@xref{Expression Patterns, ,Expressions as Patterns}.
This means that the following two code segments:
@@ -7018,8 +7313,10 @@ intended:
if (/foo/ ~ $1) print "found foo"
@end example
-@cindex automatic warnings
-@cindex warnings, automatic
+@c @cindex automatic warnings
+@c @cindex warnings, automatic
+@cindex @command{gawk}, regexp constants and
+@cindex regexp constants, in @command{gawk}
@noindent
This code is ``obviously'' testing @code{$1} for a match against the regexp
@code{/foo/}. But in fact, the expression @samp{/foo/ ~ $1} actually means
@@ -7042,8 +7339,11 @@ upon the contents of the current input record.
This feature of the language has never been well documented until the
POSIX specification.
-@cindex differences between @command{gawk} and @command{awk}
-@cindex dark corner
+@cindex differences in @command{awk} and @command{gawk}, regexp constants
+@cindex dark corner, regexp constants, as arguments to user-defined functions
+@cindex @code{gensub} function (@command{gawk})
+@cindex @code{sub} function
+@cindex @code{gsub} function
Constant regular expressions are also used as the first argument for
the @code{gensub}, @code{sub}, and @code{gsub} functions, and as the
second argument of the @code{match} function
@@ -7053,7 +7353,7 @@ the third argument of @code{split} to be a regexp constant, but some
older implementations do not.
@value{DARKCORNER}
This can lead to confusion when attempting to use regexp constants
-as arguments to user defined functions
+as arguments to user-defined functions
(@pxref{User-defined, ,User-Defined Functions}).
For example:
@@ -7075,8 +7375,8 @@ function mysub(pat, repl, str, global)
@}
@end example
-@cindex automatic warnings
-@cindex warnings, automatic
+@c @cindex automatic warnings
+@c @cindex warnings, automatic
In this example, the programmer wants to pass a regexp constant to the
user-defined function @code{mysub}, which in turn passes it on to
either @code{sub} or @code{gsub}. However, what really happens is that
@@ -7085,10 +7385,13 @@ or not @code{$0} matches @code{/hi/}.
@command{gawk} issues a warning when it sees a regexp constant used as
a parameter to a user-defined function, since passing a truth value in
this way is probably not what was intended.
+@c ENDOFRANGE rec
@node Variables, Conversion, Using Constant Regexps, Expressions
@section Variables
+@cindex variables, user-defined
+@cindex user-defined, variables
Variables are ways of storing values at one point in your program for
use later in another part of your program. They can be manipulated
entirely within the program text, and they can also be assigned values
@@ -7104,8 +7407,6 @@ on the @command{awk} command line.
@node Using Variables, Assignment Options, Variables, Variables
@subsection Using Variables in a Program
-@cindex variables, user-defined
-@cindex user-defined variables
Variables let you give names to values and refer to them later. Variables
have already been used in many of the examples. The name of a variable
must be a sequence of letters, digits, or underscores, and it may not begin
@@ -7119,6 +7420,8 @@ variable's current value. Variables are given new values with
@xref{Assignment Ops, ,Assignment Expressions}.
@c NEXT ED: Can also be changed by sub, gsub, split
+@cindex variables, built-in
+@cindex variables, initializing
A few variables have special built-in meanings, such as @code{FS} (the
field separator), and @code{NF} (the number of fields in the current input
record). @xref{Built-in Variables}, for a list of the built-in variables.
@@ -7135,6 +7438,9 @@ which is what you would do in C and in most other traditional languages.
@node Assignment Options, , Using Variables, Variables
@subsection Assigning Variables on the Command Line
+@cindex variables, assigning on command line
+@c comma before assigning does NOT start tertiary
+@cindex command line, variables, assigning on
Any @command{awk} variable can be set by including a @dfn{variable assignment}
among the arguments on the command line when @command{awk} is invoked
@@ -7145,6 +7451,8 @@ Such an assignment has the following form:
@var{variable}=@var{text}
@end example
+@c comma before assigning does NOT start tertiary
+@cindex @code{-v} option, variables, assigning
@noindent
With it, a variable is set either at the beginning of the
@command{awk} run or in between input files.
@@ -7187,19 +7495,22 @@ $ awk '@{ print $n @}' n=4 inventory-shipped n=2 BBS-list
@dots{}
@end example
-@cindex dark corner
+@cindex dark corner, command-line arguments
Command-line arguments are made available for explicit examination by
-the @command{awk} program in an array named @code{ARGV}
+the @command{awk} program in the @code{ARGV} array
(@pxref{ARGC and ARGV, ,Using @code{ARGC} and @code{ARGV}}).
@command{awk} processes the values of command-line assignments for escape
sequences
-@value{DARKCORNER}
(@pxref{Escape Sequences}).
+@value{DARKCORNER}
@node Conversion, Arithmetic Ops, Variables, Expressions
@section Conversion of Strings and Numbers
-@cindex conversion of strings and numbers
+@cindex converting, strings to numbers
+@cindex strings, converting
+@cindex numbers, converting
+@cindex converting, numbers
Strings are converted to numbers and numbers are converted to strings, if the context
of the @command{awk} program demands it. For example, if the value of
either @code{foo} or @code{bar} in the expression @samp{foo + bar}
@@ -7216,10 +7527,9 @@ print (two three) + 4
This prints the (numeric) value 27. The numeric values of
the variables @code{two} and @code{three} are converted to strings and
concatenated together. The resulting string is converted back to the
-number 23, to which four is then added.
+number 23, to which 4 is then added.
-@cindex null string
-@cindex empty string
+@cindex null strings, converting numbers to strings
@cindex type conversion
If, for some reason, you need to force a number to be converted to a
string, concatenate the empty string, @code{""}, with that number.
@@ -7247,7 +7557,7 @@ value exactly,
most of the time.@footnote{Pathological cases can require up to
752 digits (!), but we doubt that you need to worry about this.}
-@cindex dark corner
+@cindex dark corner, @code{CONVFMT} variable
Strange results can occur if you set @code{CONVFMT} to a string that doesn't
tell @code{sprintf} how to format floating-point numbers in a useful way.
For example, if you forget the @samp{%} in the format, @command{awk} converts
@@ -7266,9 +7576,10 @@ b = a ""
@code{b} has the value @code{"12"}, not @code{"12.00"}.
@value{DARKCORNER}
-@cindex @command{awk} language, POSIX version
-@cindex POSIX @command{awk}
+@cindex POSIX @command{awk}, @code{OFMT} variable and
@cindex @code{OFMT} variable
+@cindex portability, new @command{awk} vs. old @command{awk}
+@cindex @command{awk}, new vs. old, @code{OFMT} variable
Prior to the POSIX standard, @command{awk} used the value
of @code{OFMT} for converting numbers to strings. @code{OFMT}
specifies the output format to use when printing numbers with @code{print}.
@@ -7287,13 +7598,13 @@ for more information on the @code{print} statement.
@section Arithmetic Operators
@cindex arithmetic operators
@cindex operators, arithmetic
-@cindex addition
-@cindex subtraction
-@cindex multiplication
-@cindex division
-@cindex remainder
-@cindex quotient
-@cindex exponentiation
+@c @cindex addition
+@c @cindex subtraction
+@c @cindex multiplication
+@c @cindex division
+@c @cindex remainder
+@c @cindex quotient
+@c @cindex exponentiation
The @command{awk} language uses the common arithmetic operators when
evaluating expressions. All of these arithmetic operators follow normal
@@ -7331,8 +7642,7 @@ Negation.
@item + @var{x}
Unary plus; the expression is converted to a number.
-@cindex @command{awk} language, POSIX version
-@cindex POSIX @command{awk}
+@cindex POSIX @command{awk}, arithmetic operators and
@item @var{x} ^ @var{y}
@itemx @var{x} ** @var{y}
Exponentiation; @var{x} raised to the @var{y} power. @samp{2 ^ 3} has
@@ -7342,9 +7652,8 @@ the value eight; the character sequence @samp{**} is equivalent to
@item @var{x} * @var{y}
Multiplication.
-@cindex common mistakes
-@cindex mistakes, common
-@cindex errors, common
+@cindex troubleshooting, division
+@cindex division
@item @var{x} / @var{y}
Division; because all numbers in @command{awk} are floating-point
numbers, the result is @emph{not} rounded to an integer---@samp{3 / 4} has
@@ -7368,7 +7677,8 @@ Unary plus and minus have the same precedence,
the multiplication operators all have the same precedence, and
addition and subtraction have the same precedence.
-@cindex differences between @command{gawk} and @command{awk}
+@cindex differences in @command{awk} and @command{gawk}, trunc-mod operation
+@cindex trunc-mod operation
When computing the remainder of @code{@var{x} % @var{y}},
the quotient is rounded toward zero to an integer and
multiplied by @var{y}. This result is subtracted from @var{x};
@@ -7387,10 +7697,12 @@ One possibly undesirable effect of this definition of remainder is that
@end example
In other @command{awk} implementations, the signedness of the remainder
-may be machine dependent.
+may be machine-dependent.
@c !!! what does posix say?
-@cindex portability issues
+@cindex portability, @code{**} operator and
+@cindex @code{*} (asterisk), @code{**} operator
+@cindex asterisk (@code{*}), @code{**} operator
@strong{Note:}
The POSIX standard only specifies the use of @samp{^}
for exponentiation.
@@ -7406,7 +7718,7 @@ Brian Kernighan
@cindex string operators
@cindex operators, string
-@cindex concatenation
+@cindex concatenating
There is only one string operation: concatenation. It does not have a
specific operator to represent it. Instead, concatenation is performed by
writing expressions next to one another, with no operator. For example:
@@ -7428,9 +7740,7 @@ $ awk '@{ print "Field number one:" $1 @}' BBS-list
@dots{}
@end example
-@cindex common mistakes
-@cindex mistakes, common
-@cindex errors, common
+@cindex troubleshooting, string concatenation
Because string concatenation does not have an explicit operator, it is
often necessary to insure that it happens at the right time by using
parentheses to enclose the items to concatenate. For example, the
@@ -7451,8 +7761,7 @@ print "something meaningful" > (file name)
@end example
@cindex order of evaluation, concatenation
-@cindex concatenation evaluation order
-@cindex evaluation, order of
+@cindex evaluation order, concatenation
@cindex side effects
Parentheses should be used around concatenation in all but the
most common contexts, such as on the righthand side of @samp{=}.
@@ -7531,11 +7840,14 @@ you're never quite sure what you'll get.
@node Assignment Ops, Increment Ops, Concatenation, Expressions
@section Assignment Expressions
+@c STARTOFRANGE asop
@cindex assignment operators
+@c STARTOFRANGE opas
@cindex operators, assignment
-@cindex expression, assignment
-
-@cindex @code{=} operator
+@c STARTOFRANGE exas
+@cindex expressions, assignment
+@cindex @code{=} (equals sign), @code{=} operator
+@cindex equals sign (@code{=}), @code{=} operator
An @dfn{assignment} is an expression that stores a (usually different)
value into a variable. For example, let's assign the value one to the variable
@code{z}:
@@ -7558,7 +7870,7 @@ message = "this " thing " is " predicate
@end example
@noindent
-@cindex side effects
+@cindex side effects, assignment expressions
This also illustrates string concatenation.
The @samp{=} sign is called an @dfn{assignment operator}. It is the
simplest assignment operator because the value of the righthand
@@ -7570,8 +7882,10 @@ produce a value, but even if you ignore it, the assignment still
makes itself felt through the alteration of the variable. We call this
a @dfn{side effect}.
-@cindex lvalue
-@cindex rvalue
+@cindex lvalues/rvalues
+@cindex rvalues/lvalues
+@cindex assignment operators, lvalues/rvalues
+@cindex operators, assignment
The lefthand operand of an assignment need not be a variable
(@pxref{Variables}); it can also be a field
(@pxref{Changing Fields, ,Changing the Contents of a Field}) or
@@ -7580,9 +7894,9 @@ These are all called @dfn{lvalues},
which means they can appear on the lefthand side of an assignment operator.
The righthand operand may be any expression; it produces the new value
that the assignment stores in the specified variable, field, or array
-element. (Such values are called @dfn{rvalues}).
+element. (Such values are called @dfn{rvalues}.)
-@cindex types of variables
+@cindex variables, types of
It is important to note that variables do @emph{not} have permanent types.
A variable's type is simply the type of whatever value it happens
to hold at the moment. In the following program fragment, the variable
@@ -7611,7 +7925,7 @@ foo = foo + 5
@strong{Note:} Using a variable as a number and then later as a string
can be confusing and is poor programming style. The previous two examples
illustrate how @command{awk} works, @emph{not} how you should write your
-own programs!
+programs!
An assignment is an expression, so it has a value---the same value that
is assigned. Thus, @samp{z = 1} is an expression with the value one.
@@ -7635,6 +7949,8 @@ and then test whether @code{x} equals one. But this style tends to make
programs hard to read; such nesting of assignments should be avoided,
except perhaps in a one-shot program.
+@cindex @code{+} (plus sign), @code{+=} operator
+@cindex plus sign (@code{+}), @code{+=} operator
Aside from @samp{=}, there are several other assignment operators that
do arithmetic with the old value of the variable. For example, the
operator @samp{+=} computes a new value by adding the righthand value
@@ -7673,6 +7989,8 @@ BEGIN @{
@}
@end example
+@cindex operators, assignment, evaluation order
+@cindex assignment operators, evaluation order
@noindent
The indices of @code{bar} are practically guaranteed to be different, because
@code{rand} returns different values each time it is called.
@@ -7723,13 +8041,18 @@ Raises @var{lvalue} to the power @var{power}.
@end table
@end ignore
-@cindex @code{+=} operator
-@cindex @code{-=} operator
-@cindex @code{*=} operator
-@cindex @code{/=} operator
-@cindex @code{%=} operator
-@cindex @code{^=} operator
-@cindex @code{**=} operator
+@cindex @code{-} (hyphen), @code{-=} operator
+@cindex hyphen (@code{-}), @code{-=} operator
+@cindex @code{*} (asterisk), @code{*=} operator
+@cindex asterisk (@code{*}), @code{*=} operator
+@cindex @code{/} (forward slash), @code{/=} operator
+@cindex forward slash (@code{/}), @code{/=} operator
+@cindex @code{%} (percent sign), @code{%=} operator
+@cindex percent sign (@code{%}), @code{%=} operator
+@cindex @code{^} (caret), @code{^=} operator
+@cindex caret (@code{^}), @code{^=} operator
+@cindex @code{*} (asterisk), @code{**=} operator
+@cindex asterisk (@code{*}), @code{**=} operator
@multitable {@var{lvalue} *= @var{coefficient}} {Subtracts @var{decrement} from the value of @var{lvalue}.}
@item @var{lvalue} @code{+=} @var{increment} @tab Adds @var{increment} to the value of @var{lvalue}.
@@ -7747,14 +8070,19 @@ Raises @var{lvalue} to the power @var{power}.
@item @var{lvalue} @code{**=} @var{power} @tab Raises @var{lvalue} to the power @var{power}.
@end multitable
-@cindex portability issues
+@cindex POSIX @command{awk}, @code{**=} operator and
+@cindex portability, @code{**=} operator and
@strong{Note:}
Only the @samp{^=} operator is specified by POSIX.
For maximum portability, do not use the @samp{**=} operator.
@c fakenode --- for prepinfo
@subheading Advanced Notes: Syntactic Ambiguities Between @samp{/=} and Regular Expressions
-@cindex advanced notes
+@cindex advanced features, regexp constants
+@cindex dark corner, regexp constants, @code{/=} operator and
+@cindex @code{/} (forward slash), @code{/=} operator, vs. @code{/=@dots{}/} regexp constant
+@cindex forward slash (@code{/}), @code{/=} operator, vs. @code{/=@dots{}/} regexp constant
+@cindex regexp constants, @code{/=@dots{}/}, @code{/=} operator and
@c derived from email from "Nelson H. F. Beebe" <beebe@math.utah.edu>
@c Date: Mon, 1 Sep 1997 13:38:35 -0600 (MDT)
@@ -7786,20 +8114,28 @@ awk '/[=]=/' /dev/null
@command{gawk} does not have this problem,
nor do the other
-freely-available versions described in
+freely available versions described in
@ref{Other Versions, , Other Freely Available @command{awk} Implementations}.
+@c ENDOFRANGE exas
+@c ENDOFRANGE opas
+@c ENDOFRANGE asop
@node Increment Ops, Truth Values, Assignment Ops, Expressions
@section Increment and Decrement Operators
+@c STARTOFRANGE inop
@cindex increment operators
-@cindex operators, increment
+@c STARTOFRANGE opde
+@cindex operators, decrement/increment
@dfn{Increment} and @dfn{decrement operators} increase or decrease the value of
a variable by one. An assignment operator can do the same thing, so
-the increment operators add no power to the @command{awk} language; however they
+the increment operators add no power to the @command{awk} language; however, they
are convenient abbreviations for very common operations.
@cindex side effects
+@cindex @code{+} (plus sign), decrement/increment operators
+@cindex plus sign (@code{+}), decrement/increment operators
+@cindex side effects, decrement/increment operators
The operator used for adding one is written @samp{++}. It can be used to increment
a variable either before or after taking its value.
To pre-increment a variable @code{v}, write @samp{++v}. This adds
@@ -7820,20 +8156,22 @@ The post-increment @samp{foo++} is nearly the same as writing @samp{(foo
not necessarily equal @code{foo}. But the difference is minute as
long as you stick to numbers that are fairly small (less than 10e12).
+@cindex @code{$} (dollar sign), incrementing fields and arrays
+@cindex dollar sign (@code{$}), incrementing fields and arrays
Fields and array elements are incremented
just like variables. (Use @samp{$(i++)} when you want to do a field reference
and a variable increment at the same time. The parentheses are necessary
because of the precedence of the field reference operator @samp{$}.)
@cindex decrement operators
-@cindex operators, decrement
The decrement operator @samp{--} works just like @samp{++}, except that
it subtracts one instead of adding it. As with @samp{++}, it can be used before
the lvalue to pre-decrement or after it to post-decrement.
Following is a summary of increment and decrement expressions:
@table @code
-@cindex @code{++} operator
+@cindex @code{+} (plus sign), @code{++} operator
+@cindex plus sign (@code{+}), @code{++} operator
@item ++@var{lvalue}
This expression increments @var{lvalue}, and the new value becomes the
value of the expression.
@@ -7842,7 +8180,8 @@ value of the expression.
This expression increments @var{lvalue}, but
the value of the expression is the @emph{old} value of @var{lvalue}.
-@cindex @code{--} operator
+@cindex @code{-} (hyphen), @code{--} operator
+@cindex hyphen (@code{-}), @code{--} operator
@item --@var{lvalue}
This expression is
like @samp{++@var{lvalue}}, but instead of adding, it subtracts. It
@@ -7857,11 +8196,12 @@ value of @var{lvalue}.
@c fakenode --- for prepinfo
@subheading Advanced Notes: Operator Evaluation Order
-@cindex advanced notes
+@c comma before precedence does NOT start tertiary
+@cindex advanced features, operators, precedence
@cindex precedence
-@cindex operator precedence
-@cindex portability issues
-@cindex evaluation, order of
+@cindex operators, precedence
+@cindex portability, operators
+@cindex evaluation order
@cindex Marx, Groucho
@quotation
@i{Doctor, doctor! It hurts when I do this!@*
@@ -7899,15 +8239,18 @@ not anything that you can rely upon for portability.
You should avoid such things in your own programs.
@c You'll sleep better at night and be able to look at yourself
@c in the mirror in the morning.
+@c ENDOFRANGE inop
+@c ENDOFRANGE opde
+@c ENDOFRANGE deop
@node Truth Values, Typing and Comparison, Increment Ops, Expressions
@section True and False in @command{awk}
@cindex truth values
-@cindex logical true
-@cindex logical false
+@cindex logical false/true
+@cindex false, logical
+@cindex true, logical
-@cindex null string
-@cindex empty string
+@cindex null strings
Many programming languages have a special representation for the concepts
of ``true'' and ``false.'' Such languages usually use the special
constants @code{true} and @code{false}, or perhaps their uppercase
@@ -7915,7 +8258,7 @@ equivalents.
However, @command{awk} is different.
It borrows a very simple concept of true and
false from C. In @command{awk}, any nonzero numeric value @emph{or} any
-non-empty string value is true. Any other value (zero or the null
+nonempty string value is true. Any other value (zero or the null
string @code{""}) is false. The following program prints @samp{A strange
truth value} three times:
@@ -7937,24 +8280,31 @@ the string constant @code{"0"} is actually true, because it is non-null.
@node Typing and Comparison, Boolean Ops, Truth Values, Expressions
@section Variable Typing and Comparison Expressions
-@cindex comparison expressions
-@cindex expression, comparison
-@cindex expression, matching
-@cindex relational operators
-@cindex operators, relational
-@cindex regexp operators
-@cindex variable typing
-@cindex types of variables
@quotation
@i{The Guide is definitive. Reality is frequently inaccurate.}@*
The Hitchhiker's Guide to the Galaxy
@end quotation
+@c STARTOFRANGE comex
+@cindex comparison expressions
+@c STARTOFRANGE excom
+@cindex expressions, comparison
+@cindex expressions, matching, See comparison expressions
+@cindex matching, expressions, See comparison expressions
+@cindex relational operators, See comparison operators
+@c comma is part of See
+@cindex operators, relational, See operators, comparison
+@c STARTOFRANGE varting
+@cindex variable typing
+@c STARTOFRANGE vartypc
+@cindex variables, types of, comparison expressions and
Unlike other programming languages, @command{awk} variables do not have a
fixed type. Instead, they can be either a number or a string, depending
upon the value that is assigned to them.
-@cindex numeric string
+@cindex numeric, strings
+@cindex strings, numeric
+@cindex POSIX @command{awk}, numeric strings and
The 1992 POSIX standard introduced
the concept of a @dfn{numeric string}, which is simply a string that looks
like a number---for example, @code{@w{" +2"}}. This concept is used
@@ -8082,16 +8432,22 @@ relationships such as equality. They are written using @dfn{relational
operators}, which are a superset of those in C. Here is a table of
them:
-@cindex relational operators
-@cindex operators, relational
-@cindex @code{<} operator
-@cindex @code{<=} operator
-@cindex @code{>} operator
-@cindex @code{>=} operator
-@cindex @code{==} operator
-@cindex @code{!=} operator
-@cindex @code{~} operator
-@cindex @code{!~} operator
+@cindex @code{<} (left angle bracket), @code{<} operator
+@cindex left angle bracket (@code{<}), @code{<} operator
+@cindex @code{<} (left angle bracket), @code{<=} operator
+@cindex left angle bracket (@code{<}), @code{<=} operator
+@cindex @code{>} (right angle bracket), @code{>=} operator
+@cindex right angle bracket (@code{>}), @code{>=} operator
+@cindex @code{>} (right angle bracket), @code{>} operator
+@cindex right angle bracket (@code{>}), @code{>} operator
+@cindex @code{=} (equals sign), @code{==} operator
+@cindex equals sign (@code{=}), @code{==} operator
+@cindex @code{!} (exclamation point), @code{!=} operator
+@cindex exclamation point (@code{!}), @code{!=} operator
+@cindex @code{~} (tilde), @code{~} operator
+@cindex tilde (@code{~}), @code{~} operator
+@cindex @code{!} (exclamation point), @code{!~} operator
+@cindex exclamation point (@code{!}), @code{!~} operator
@cindex @code{in} operator
@table @code
@item @var{x} < @var{y}
@@ -8133,9 +8489,7 @@ and so on. Thus, @code{"10"} is less than @code{"9"}. If there are two
strings where one is a prefix of the other, the shorter string is less than
the longer one. Thus, @code{"abc"} is less than @code{"abcd"}.
-@cindex common mistakes
-@cindex mistakes, common
-@cindex errors, common
+@cindex troubleshooting, @code{==} operator
It is very easy to accidentally mistype the @samp{==} operator and
leave off one of the @samp{=} characters. The result is still valid @command{awk}
code, but the program does not do what is intended:
@@ -8153,6 +8507,7 @@ part of the test always succeeds. Because the operators are
so similar, this kind of error is very difficult to spot when
scanning the source code.
+@cindex @command{gawk}, comparison operators and
The following table of expressions illustrates the kind of comparison
@command{gawk} performs, as well as what the result of the comparison is:
@@ -8185,9 +8540,9 @@ $ echo 1e2 3 | awk '@{ print ($1 < $2) ? "true" : "false" @}'
@print{} false
@end example
-@cindex comparisons, string vs. regexp
-@cindex string comparison vs. regexp comparison
-@cindex regexp comparison vs. string comparison
+@cindex comparison expressions, string vs. regexp
+@c @cindex string comparison vs. regexp comparison
+@c @cindex regexp comparison vs. string comparison
@noindent
the result is @samp{false} because both @code{$1} and @code{$2}
are user input. They are numeric strings---therefore both have
@@ -8214,13 +8569,18 @@ x ~ /foo/
has the value one if @code{x} contains @samp{foo}, such as
@code{"Oh, what a fool am I!"}.
+@cindex @code{~} (tilde), @code{~} operator
+@cindex tilde (@code{~}), @code{~} operator
+@cindex @code{!} (exclamation point), @code{!~} operator
+@cindex exclamation point (@code{!}), @code{!~} operator
The righthand operand of the @samp{~} and @samp{!~} operators may be
either a regexp constant (@code{/@dots{}/}) or an ordinary
expression. In the latter case, the value of the expression as a string is used as a
dynamic regexp (@pxref{Regexp Usage, ,How to Use Regular Expressions}; also
@pxref{Computed Regexps, ,Using Dynamic Regexps}).
-@cindex regexp as expression
+@cindex @command{awk}, regexp constants and
+@cindex regexp constants
In modern implementations of @command{awk}, a constant regular
expression in slashes by itself is also an expression. The regexp
@code{/@var{regexp}/} is an abbreviation for the following comparison expression:
@@ -8234,23 +8594,24 @@ One special place where @code{/foo/} is @emph{not} an abbreviation for
@samp{!~}.
@xref{Using Constant Regexps, ,Using Regular Expression Constants},
where this is discussed in more detail.
+@c ENDOFRANGE comex
+@c ENDOFRANGE excom
+@c ENDOFRANGE vartypc
+@c ENDOFRANGE varting
@node Boolean Ops, Conditional Exp, Typing and Comparison, Expressions
@section Boolean Expressions
-@cindex expression, boolean
-@cindex boolean expressions
-@cindex operators, boolean
-@cindex boolean operators
-@cindex logical operators
-@cindex operators, logical
-@cindex short-circuit operators
-@cindex operators, short-circuit
-@cindex AND logical operator
-@cindex OR logical operator
-@cindex NOT logical operator
-@cindex @code{&&} operator
-@cindex @code{||} operator
-@cindex @code{!} operator
+@cindex and Boolean-logic operator
+@cindex or Boolean-logic operator
+@cindex not Boolean-logic operator
+@c STARTOFRANGE exbo
+@cindex expressions, Boolean
+@c STARTOFRANGE boex
+@cindex Boolean expressions
+@cindex operators, Boolean, See Boolean expressions
+@cindex Boolean operators, See Boolean expressions
+@cindex logical operators, See Boolean expressions
+@cindex operators, logical, See Boolean expressions
A @dfn{Boolean expression} is a combination of comparison expressions or
matching expressions, using the Boolean operators ``or''
@@ -8264,7 +8625,7 @@ Boolean expressions can be used wherever comparison and matching
expressions can be used. They can be used in @code{if}, @code{while},
@code{do}, and @code{for} statements
(@pxref{Statements, ,Control Statements in Actions}).
-They have numeric values (one if true, zero if false), that come into play
+They have numeric values (one if true, zero if false) that come into play
if the result of the Boolean expression is stored in a variable or
used in arithmetic.
@@ -8282,7 +8643,7 @@ both @samp{2400} and @samp{foo}:
if ($0 ~ /2400/ && $0 ~ /foo/) print
@end example
-@cindex side effects
+@cindex side effects, Boolean operators
The subexpression @var{boolean2} is evaluated only if @var{boolean1}
is true. This can make a difference when @var{boolean2} contains
expressions that have side effects. In the case of @samp{$0 ~ /foo/ &&
@@ -8318,17 +8679,27 @@ BEGIN @{ if (! ("HOME" in ENVIRON))
@ref{Reference to Elements, ,Referring to an Array Element}.)
@end table
+@cindex short-circuit operators
+@cindex operators, short-circuit
+@cindex @code{&} (ampersand), @code{&&} operator
+@cindex ampersand (@code{&}), @code{&&} operator
+@cindex @code{|} (vertical bar), @code{||} operator
+@cindex vertical bar (@code{|}), @code{||} operator
The @samp{&&} and @samp{||} operators are called @dfn{short-circuit}
operators because of the way they work. Evaluation of the full expression
is ``short-circuited'' if the result can be determined part way through
its evaluation.
-@cindex line continuation
+@cindex line continuations
Statements that use @samp{&&} or @samp{||} can be continued simply
by putting a newline after them. But you cannot put a newline in front
of either of these operators without using backslash continuation
(@pxref{Statements/Lines, ,@command{awk} Statements Versus Lines}).
+@cindex @code{!} (exclamation point), @code{!} operator
+@cindex exclamation point (@code{!}), @code{!} operator
+@cindex newlines
+@cindex variables, flag
@cindex flag variables
The actual value of an expression using the @samp{!} operator is
either one or zero, depending upon the truth value of the expression it
@@ -8357,17 +8728,21 @@ bogus input data, but the point is to illustrate the use of `!',
so we'll leave well enough alone.
@end ignore
+@cindex @code{next} statement
@strong{Note:} The @code{next} statement is discussed in
@ref{Next Statement, ,The @code{next} Statement}.
@code{next} tells @command{awk} to skip the rest of the rules, get the
next record, and start processing the rules over again at the top.
The reason it's there is to avoid printing the bracketing
@samp{START} and @samp{END} lines.
+@c ENDOFRANGE exbo
+@c ENDOFRANGE boex
@node Conditional Exp, Function Calls, Boolean Ops, Expressions
@section Conditional Expressions
-@cindex conditional expression
-@cindex expression, conditional
+@cindex conditional expressions
+@cindex expressions, conditional
+@cindex expressions, selecting
A @dfn{conditional expression} is a special kind of expression that has
three operands. It allows you to use one expression's value to select
@@ -8391,7 +8766,7 @@ For example, the following expression produces the absolute value of @code{x}:
x >= 0 ? x : -x
@end example
-@cindex side effects
+@cindex side effects, conditional expressions
Each time the conditional expression is computed, only one of
@var{if-true-exp} and @var{if-false-exp} is used; the other is ignored.
This is important when the expressions have side effects. For example,
@@ -8409,8 +8784,9 @@ and the other is not.
@xref{Arrays, ,Arrays in @command{awk}},
for more information about arrays.
-@cindex differences between @command{gawk} and @command{awk}
-@cindex line continuation
+@cindex differences in @command{awk} and @command{gawk}, line continuations
+@cindex line continuations, @command{gawk}
+@cindex @command{gawk}, line continuation in
As a minor @command{gawk} extension,
a statement that uses @samp{?:} can be continued simply
by putting a newline after either character.
@@ -8422,14 +8798,14 @@ If @option{--posix} is specified
@node Function Calls, Precedence, Conditional Exp, Expressions
@section Function Calls
-@cindex function call
-@cindex calling a function
+@cindex function calls
A @dfn{function} is a name for a particular calculation.
This enables you to
ask for it by name at any point in the program. For
example, the function @code{sqrt} computes the square root of a number.
+@cindex functions, built-in
A fixed set of functions are @dfn{built-in}, which means they are
available in every @command{awk} program. The @code{sqrt} function is one
of these. @xref{Built-in, ,Built-in Functions}, for a list of built-in
@@ -8438,7 +8814,7 @@ functions for use in your program.
@xref{User-defined, ,User-Defined Functions},
for instructions on how to do this.
-@cindex arguments in function call
+@cindex arguments, in function calls
The way to use a function is with a @dfn{function call} expression,
which consists of the function name followed immediately by a list of
@dfn{arguments} in parentheses. The arguments are expressions that
@@ -8453,6 +8829,7 @@ atan2(y, x) @i{two arguments}
rand() @i{no arguments}
@end example
+@cindex troubleshooting, function call syntax
@strong{Caution:}
Do not put any space between the function name and the open-parenthesis!
A user-defined function name looks just like the name of a
@@ -8463,7 +8840,7 @@ With built-in functions, space before the parenthesis is harmless, but
it is best not to get into the habit of using space to avoid mistakes
with user-defined functions. Each function expects a particular number
of arguments. For example, the @code{sqrt} function must be called with
-a single argument: the number to take the square root of:
+a single argument, the number of which to take the square root:
@example
sqrt(@var{argument})
@@ -8478,7 +8855,7 @@ are omitted in calls to user-defined functions, then those arguments are
treated as local variables and initialized to the empty string
(@pxref{User-defined, ,User-Defined Functions}).
-@cindex side effects
+@cindex side effects, function calls
Like every other expression, the function call has a value, which is
computed by the function based on the arguments you give it. In this
example, the value of @samp{sqrt(@var{argument})} is the square root of
@@ -8495,13 +8872,15 @@ $ awk '@{ print "The square root of", $1, "is", sqrt($1) @}'
@print{} The square root of 3 is 1.73205
5
@print{} The square root of 5 is 2.23607
-@kbd{Ctrl-d}
+@kbd{@value{CTL}-d}
@end example
@node Precedence, , Function Calls, Expressions
@section Operator Precedence (How Operators Nest)
+@c STARTOFRANGE prec
@cindex precedence
-@cindex operator precedence
+@c STARTOFRANGE oppr
+@cindex operators, precedence
@dfn{Operator precedence} determines how operators are grouped when
different operators appear close by in one expression. For example,
@@ -8535,63 +8914,56 @@ the operand, then the precedence of the unary operators can matter.
@samp{-(x^2)}, because @samp{-} has lower precedence than @samp{^},
whereas @samp{$} has higher precedence.
This table presents @command{awk}'s operators, in order of highest
-precedence to lowest:
+to lowest precedence:
@page
-@cindex @code{$} field operator
-@cindex @code{+} operator
-@cindex @code{-} operator
-@cindex @code{!} operator
-@cindex @code{*} operator
-@cindex @code{/} operator
-@cindex @code{%} operator
-@cindex @code{^} operator
-@cindex @code{**} operator
-@cindex @code{++} operator
-@cindex @code{--} operator
-@cindex @code{<} operator
-@cindex @code{<=} operator
-@cindex @code{==} operator
-@cindex @code{!=} operator
-@cindex @code{>} operator
-@cindex @code{>=} operator
-@cindex @code{>>} I/O operator
-@cindex @code{|} I/O operator
-@cindex @code{|&} I/O operator
-@cindex @code{~} operator
-@cindex @code{!~} operator
-@cindex @code{in} operator
-@cindex @code{&&} operator
-@cindex @code{||} operator
-@cindex @code{?:} operator
-@cindex @code{+=} operator
-@cindex @code{-=} operator
-@cindex @code{*=} operator
-@cindex @code{/=} operator
-@cindex @code{%=} operator
-@cindex @code{^=} operator
-@cindex @code{**=} operator
@c use @code in the items, looks better in TeX w/o all the quotes
@table @code
@item (@dots{})
Grouping.
+@cindex @code{$} (dollar sign), @code{$} field operator
+@cindex dollar sign (@code{$}), @code{$} field operator
@item $
Field.
+@cindex @code{+} (plus sign), @code{++} operator
+@cindex plus sign (@code{+}), @code{++} operator
+@cindex @code{-} (hyphen), @code{--} (decrement/increment) operator
+@cindex hyphen (@code{-}), @code{--} (decrement/increment) operators
@item ++ --
Increment, decrement.
+@cindex @code{^} (caret), @code{^} operator
+@cindex caret (@code{^}), @code{^} operator
+@cindex @code{*} (asterisk), @code{**} operator
+@cindex asterisk (@code{*}), @code{**} operator
@item ^ **
Exponentiation. These operators group right-to-left.
+@cindex @code{+} (plus sign), @code{+} operator
+@cindex plus sign (@code{+}), @code{+} operator
+@cindex @code{-} (hyphen), @code{-} operator
+@cindex hyphen (@code{-}), @code{-} operator
+@cindex @code{!} (exclamation point), @code{!} operator
+@cindex exclamation point (@code{!}), @code{!} operator
@item + - !
Unary plus, minus, logical ``not.''
+@cindex @code{*} (asterisk), @code{*} operator, as multiplication operator
+@cindex asterisk (@code{*}), @code{*} operator, as multiplication operator
+@cindex @code{/} (forward slash), @code{/} operator
+@cindex forward slash (@code{/}), @code{/} operator
+@cindex @code{%} (percent sign), @code{%} operator
+@cindex percent sign (@code{%}), @code{%} operator
@item * / %
Multiplication, division, modulus.
+@cindex @code{+} (plus sign), @code{+} operator
+@cindex plus sign (@code{+}), @code{+} operator
+@cindex @code{-} (hyphen), @code{-} operator
+@cindex hyphen (@code{-}), @code{-} operator
@item + -
Addition, subtraction.
@@ -8600,6 +8972,27 @@ No special symbol is used to indicate concatenation.
The operands are simply written side by side
(@pxref{Concatenation, ,String Concatenation}).
+@cindex @code{<} (left angle bracket), @code{<} operator
+@cindex left angle bracket (@code{<}), @code{<} operator
+@cindex @code{<} (left angle bracket), @code{<=} operator
+@cindex left angle bracket (@code{<}), @code{<=} operator
+@cindex @code{>} (right angle bracket), @code{>=} operator
+@cindex right angle bracket (@code{>}), @code{>=} operator
+@cindex @code{>} (right angle bracket), @code{>} operator
+@cindex right angle bracket (@code{>}), @code{>} operator
+@cindex @code{=} (equals sign), @code{==} operator
+@cindex equals sign (@code{=}), @code{==} operator
+@cindex @code{!} (exclamation point), @code{!=} operator
+@cindex exclamation point (@code{!}), @code{!=} operator
+@cindex @code{>} (right angle bracket), @code{>>} operator (I/O)
+@cindex right angle bracket (@code{>}), @code{>>} operator (I/O)
+@cindex operators, input/output
+@cindex @code{|} (vertical bar), @code{|} operator (I/O)
+@cindex vertical bar (@code{|}), @code{|} operator (I/O)
+@cindex operators, input/output
+@cindex @code{|} (vertical bar), @code{|&} operator (I/O)
+@cindex vertical bar (@code{|}), @code{|&} operator (I/O)
+@cindex operators, input/output
@item < <= == !=
@itemx > >= >> | |&
Relational and redirection.
@@ -8607,45 +9000,74 @@ The relational operators and the redirections have the same precedence
level. Characters such as @samp{>} serve both as relationals and as
redirections; the context distinguishes between the two meanings.
+@cindex @code{print} statement, I/O operators in
+@cindex @code{printf} statement, I/O operators in
Note that the I/O redirection operators in @code{print} and @code{printf}
statements belong to the statement level, not to expressions. The
redirection does not produce an expression that could be the operand of
another operator. As a result, it does not make sense to use a
redirection operator near another operator of lower precedence without
-parentheses. Such combinations (for example @samp{print foo > a ? b : c}),
+parentheses. Such combinations (for example, @samp{print foo > a ? b : c}),
result in syntax errors.
The correct way to write this statement is @samp{print foo > (a ? b : c)}.
+@cindex @code{~} (tilde), @code{~} operator
+@cindex tilde (@code{~}), @code{~} operator
+@cindex @code{!} (exclamation point), @code{!~} operator
+@cindex exclamation point (@code{!}), @code{!~} operator
@item ~ !~
-Matching, non-matching.
+Matching, nonmatching.
+@cindex @code{in} operator
@item in
Array membership.
+@cindex @code{&} (ampersand), @code{&&} operator
+@cindex ampersand (@code{&}), @code{&&}operator
@item &&
Logical ``and''.
+@cindex @code{|} (vertical bar), @code{||} operator
+@cindex vertical bar (@code{|}), @code{||} operator
@item ||
Logical ``or''.
+@cindex @code{?} (question mark), @code{?:} operator
+@cindex question mark (@code{?}), @code{?:} operator
@item ?:
Conditional. This operator groups right-to-left.
+@cindex @code{+} (plus sign), @code{+=} operator
+@cindex plus sign (@code{+}), @code{+=} operator
+@cindex @code{-} (hyphen), @code{-=} operator
+@cindex hyphen (@code{-}), @code{-=} operator
+@cindex @code{*} (asterisk), @code{*=} operator
+@cindex asterisk (@code{*}), @code{*=} operator
+@cindex @code{*} (asterisk), @code{**=} operator
+@cindex asterisk (@code{*}), @code{**=} operator
+@cindex @code{/} (forward slash), @code{/=} operator
+@cindex forward slash (@code{/}), @code{/=} operator
+@cindex @code{%} (percent sign), @code{%=} operator
+@cindex percent sign (@code{%}), @code{%=} operator
+@cindex @code{^} (caret), @code{^=} operator
+@cindex caret (@code{^}), @code{^=} operator
@item = += -= *=
@itemx /= %= ^= **=
-Assignment. These operators group right-to-left.
+Assignment. These operators group right to left.
@end table
-@cindex portability issues
-@cindex @command{awk} language, POSIX version
-@cindex POSIX @command{awk}
+@cindex portability, operators, not in POSIX @command{awk}
@strong{Note:}
The @samp{|&}, @samp{**}, and @samp{**=} operators are not specified by POSIX.
For maximum portability, do not use them.
+@c ENDOFRANGE prec
+@c ENDOFRANGE oppr
+@c ENDOFRANGE exps
@node Patterns and Actions, Arrays, Expressions, Top
@chapter Patterns, Actions, and Variables
-@cindex pattern, definition of
+@c STARTOFRANGE pat
+@cindex patterns
As you have already seen, each @command{awk} statement consists of
a pattern with an associated action. This @value{CHAPTER} describes how
@@ -8682,7 +9104,7 @@ building something useful.
@cindex patterns, types of
Patterns in @command{awk} control the execution of rules---a rule is
executed when its pattern matches the current input record.
-The following is a summary of the types of patterns in @command{awk}:
+The following is a summary of the types of @command{awk} patterns:
@table @code
@item /@var{regular expression}/
@@ -8714,6 +9136,8 @@ The empty pattern matches every input record.
@node Regexp Patterns, Expression Patterns, Pattern Overview, Pattern Overview
@subsection Regular Expressions as Patterns
+@cindex patterns, expressions as
+@cindex regular expressions, as patterns
Regular expressions are one of the first kinds of patterns presented
in this book.
@@ -8729,20 +9153,23 @@ END @{ print buzzwords, "buzzwords seen" @}
@node Expression Patterns, Ranges, Regexp Patterns, Pattern Overview
@subsection Expressions as Patterns
+@cindex expressions, as patterns
Any @command{awk} expression is valid as an @command{awk} pattern.
The pattern matches if the expression's value is nonzero (if a
number) or non-null (if a string).
The expression is reevaluated each time the rule is tested against a new
input record. If the expression uses fields such as @code{$1}, the
-value depends directly on the new input record's text; otherwise it
+value depends directly on the new input record's text; otherwise, it
depends on only what has happened so far in the execution of the
@command{awk} program.
+@cindex comparison expressions, as patterns
+@cindex patterns, comparison expressions as
Comparison expressions, using the comparison operators described in
@ref{Typing and Comparison, ,Variable Typing and Comparison Expressions},
-are a very common kind of pattern.
-Regexp matching and non-matching are also very common expressions.
+are a very common kind of pattern.
+Regexp matching and nonmatching are also very common expressions.
The left operand of the @samp{~} and @samp{!~} operators is a string.
The right operand is either a constant regular expression enclosed in
slashes (@code{/@var{regexp}/}), or any expression whose string value
@@ -8751,6 +9178,12 @@ is used as a dynamic regular expression
The following example prints the second field of each input record
whose first field is precisely @samp{foo}:
+@cindex @code{/} (forward slash), patterns and
+@cindex forward slash (@code{/}), patterns and
+@cindex @code{~} (tilde), @code{~} operator
+@cindex tilde (@code{~}), @code{~} operator
+@cindex @code{!} (exclamation point), @code{!~} operator
+@cindex exclamation point (@code{!}), @code{!~} operator
@example
$ awk '$1 == "foo" @{ print $2 @}' BBS-list
@end example
@@ -8768,11 +9201,14 @@ $ awk '$1 ~ /foo/ @{ print $2 @}' BBS-list
@print{} 555-2127
@end example
+@cindex regexp constants, as patterns
+@cindex patterns, regexp constants as
A regexp constant as a pattern is also a special case of an expression
pattern. The expression @code{/foo/} has the value one if @samp{foo}
appears in the current input record. Thus, as a pattern, @code{/foo/}
matches any record containing @samp{foo}.
+@cindex Boolean expressions, as patterns
Boolean expressions are also commonly used as patterns.
Whether the pattern
matches an input record depends on whether its subexpressions match.
@@ -8813,6 +9249,8 @@ $ awk '! /foo/' BBS-list
@print{} sdace 555-3430 2400/1200/300 A
@end example
+@cindex @code{BEGIN} pattern, Boolean patterns and
+@cindex @code{END} pattern, Boolean patterns and
The subexpressions of a Boolean operator in a pattern can be constant regular
expressions, comparisons, or any other @command{awk} expressions. Range
patterns are not expressions, so they cannot appear inside Boolean
@@ -8823,9 +9261,11 @@ appear inside Boolean patterns.
@node Ranges, BEGIN/END, Expression Patterns, Pattern Overview
@subsection Specifying Record Ranges with Patterns
-@cindex range pattern
-@cindex pattern, range
-@cindex matching ranges of lines
+@cindex range patterns
+@cindex patterns, ranges in
+@cindex lines, matching ranges of
+@cindex @code{,} (comma), in range patterns
+@cindex comma (@code{,}), in range patterns
A @dfn{range pattern} is made of two patterns separated by a comma, in
the form @samp{@var{begpat}, @var{endpat}}. It is used to match ranges of
consecutive input records. The first pattern, @var{begpat}, controls
@@ -8848,6 +9288,8 @@ input record; when this succeeds, the range pattern is turned off again
for the following record. Then the range pattern goes back to checking
@var{begpat} against each record.
+@c last comma does NOT start a tertiary
+@cindex @code{if} statement, actions, changing
The record that turns on the range pattern and the one that turns it
off both match the range pattern. If you don't want to operate on
these records, you can write @code{if} statements in the rule's action
@@ -8856,7 +9298,7 @@ to distinguish them from the records you are interested in.
It is possible for a pattern to be turned on and off by the same
record. If the record satisfies both conditions, then the action is
executed for just that record.
-For example, suppose there is text between two identical markers (say
+For example, suppose there is text between two identical markers (e.g.,
the @samp{%} symbol), each on its own line, that should be ignored.
A first attempt would be to
combine a range pattern that describes the delimited text with the
@@ -8872,8 +9314,8 @@ looks like this:
@end example
@noindent
-@cindex skipping lines between markers
-@cindex flag variables
+@cindex lines, skipping between markers
+@c @cindex flag variables
This program fails because the range pattern is both turned on and turned off
by the first line, which just has a @samp{%} on it. To accomplish this task,
write the program in the following manner, using a flag:
@@ -8886,7 +9328,7 @@ skip == 1 @{ next @} # skip lines with `skip' set
In a range pattern, the comma (@samp{,}) has the lowest precedence of
all the operators (i.e., it is evaluated last). Thus, the following
-program attempts to combine a range pattern with another simpler test:
+program attempts to combine a range pattern with another, simpler test:
@example
echo Yes | awk '/1/,/2/ || /Yes/'
@@ -8908,11 +9350,10 @@ $ echo yes | gawk '(/1/,/2/) || /Yes/'
@node BEGIN/END, Empty, Ranges, Pattern Overview
@subsection The @code{BEGIN} and @code{END} Special Patterns
-@cindex @code{BEGIN} special pattern
-@cindex pattern, @code{BEGIN}
-@cindex @code{END} special pattern
-@cindex pattern, @code{END}
-@cindex blocks, @code{BEGIN} and @code{END}
+@c STARTOFRANGE beg
+@cindex @code{BEGIN} pattern
+@c STARTOFRANGE end
+@cindex @code{END} pattern
All the patterns described so far are for matching input records.
The @code{BEGIN} and @code{END} special patterns are different.
They supply startup and cleanup actions for @command{awk} programs.
@@ -8943,6 +9384,8 @@ $ awk '
@print{} "foo" appears 4 times.
@end example
+@cindex @code{BEGIN} pattern, operators and
+@cindex @code{END} pattern, operators and
This program finds the number of records in the input file @file{BBS-list}
that contain the string @samp{foo}. The @code{BEGIN} rule prints a title
for the report. There is no need to use the @code{BEGIN} rule to
@@ -8972,17 +9415,17 @@ library functions, because each library file can have its own @code{BEGIN} and/o
@code{END} rule to do its own initialization and/or cleanup.
The order in which library functions are named on the command line
controls the order in which their @code{BEGIN} and @code{END} rules are
-executed. Therefore you have to be careful when writing such rules in
+executed. Therefore, you have to be careful when writing such rules in
library files so that the order in which they are executed doesn't matter.
@xref{Options, ,Command-Line Options}, for more information on
using library functions.
@xref{Library Functions, ,A Library of @command{awk} Functions},
for a number of useful library functions.
-If an @command{awk} program only has a @code{BEGIN} rule and no
+If an @command{awk} program has only a @code{BEGIN} rule and no
other rules, then the program exits after the @code{BEGIN} rule is
run.@footnote{The original version of @command{awk} used to keep
-reading and ignoring input until end of file was seen.} However, if an
+reading and ignoring input until the end of the file was seen.} However, if an
@code{END} rule exists, then the input is read, even if there are
no other rules in the program. This is necessary in case the @code{END}
rule checks the @code{FNR} and @code{NR} variables.
@@ -8990,7 +9433,7 @@ rule checks the @code{FNR} and @code{NR} variables.
@node I/O And BEGIN/END, , Using BEGIN/END, BEGIN/END
@subsubsection Input/Output from @code{BEGIN} and @code{END} Rules
-@cindex I/O, from @code{BEGIN} and @code{END}
+@cindex input/output, from @code{BEGIN} and @code{END}
There are several (sometimes subtle) points to remember when doing I/O
from a @code{BEGIN} or @code{END} rule.
The first has to do with the value of @code{$0} in a @code{BEGIN}
@@ -9000,9 +9443,13 @@ executing @code{BEGIN} rules. References to @code{$0} and the fields
yield a null string or zero, depending upon the context. One way
to give @code{$0} a real value is to execute a @code{getline} command
without a variable (@pxref{Getline, ,Explicit Input with @code{getline}}).
-Another way is to simply assign a value to @code{$0}.
+Another way is simply to assign a value to @code{$0}.
-@cindex differences between @command{gawk} and @command{awk}
+@cindex differences in @command{awk} and @command{gawk}, @code{BEGIN}/@code{END} patterns
+@cindex POSIX @command{awk}, @code{BEGIN}/@code{END} patterns
+@cindex @code{print} statement, @code{BEGIN}/@code{END} patterns and
+@cindex @code{BEGIN} pattern, @code{print} statement and
+@cindex @code{END} pattern, @code{print} statement and
The second point is similar to the first but from the other direction.
Traditionally, due largely to implementation issues, @code{$0} and
@code{NF} were @emph{undefined} inside an @code{END} rule.
@@ -9024,19 +9471,25 @@ this in @code{BEGIN} rules, it is a very bad idea in @code{END} rules,
at least in @command{gawk}. It is also poor style, since if an empty
line is needed in the output, the program should print one explicitly.
+@cindex @code{next} statement, @code{BEGIN}/@code{END} patterns and
+@cindex @code{nextfile} statement, @code{BEGIN}/@code{END} patterns and
+@cindex @code{BEGIN} pattern, @code{next}/@code{nextfile} statements and
+@cindex @code{END} pattern, @code{next}/@code{nextfile} statements and
Finally, the @code{next} and @code{nextfile} statements are not allowed
in a @code{BEGIN} rule, because the implicit
read-a-record-and-match-against-the-rules loop has not started yet. Similarly, those statements
are not valid in an @code{END} rule, since all the input has been read.
(@xref{Next Statement, ,The @code{next} Statement}, and see
@ref{Nextfile Statement, ,Using @command{gawk}'s @code{nextfile} Statement}.)
+@c ENDOFRANGE beg
+@c ENDOFRANGE end
@node Empty, , BEGIN/END, Pattern Overview
@subsection The Empty Pattern
@cindex empty pattern
-@cindex pattern, empty
-An empty (i.e., non-existent) pattern is considered to match @emph{every}
+@cindex patterns, empty
+An empty (i.e., nonexistent) pattern is considered to match @emph{every}
input record. For example, the program:
@example
@@ -9045,12 +9498,13 @@ awk '@{ print $1 @}' BBS-list
@noindent
prints the first field of every record.
+@c ENDOFRANGE pat
@node Using Shell Variables, Action Overview, Pattern Overview, Patterns and Actions
@section Using Shell Variables in Programs
-@cindex shell varibles, using in @command{awk} programs
-@cindex using shell variables in @command{awk} programs
-@cindex shell and @command{awk} interaction
+@cindex shells, variables
+@cindex @command{awk} programs, shell variables in
+@c @cindex shell and @command{awk} interaction
@command{awk} programs are often used as components in larger
programs written in shell.
@@ -9059,6 +9513,7 @@ hold a pattern that the @command{awk} program searches for.
There are two ways to get the value of the shell variable
into the body of the @command{awk} program.
+@cindex shells, quoting
The most common method is to use shell quoting to substitute
the variable's value into the program inside the script.
For example, in the following program:
@@ -9110,10 +9565,11 @@ use---without requiring the quoting tricks at every point in the program.
@node Action Overview, Statements, Using Shell Variables, Patterns and Actions
@section Actions
-@cindex action, definition of
-@cindex curly braces
-@cindex action, curly braces
-@cindex action, separating statements
+@c @cindex action, definition of
+@c @cindex curly braces
+@c @cindex action, curly braces
+@c @cindex action, separating statements
+@cindex actions
An @command{awk} program or script consists of a series of
rules and function definitions interspersed. (Functions are
@@ -9131,8 +9587,14 @@ function @var{name}(@var{args}) @{ @dots{} @}
@dots{}
@end example
+@cindex @code{@{@}} (braces), actions and
+@cindex braces (@code{@{@}}), actions and
+@cindex separators, for statements in actions
+@cindex newlines, separating statements in actions
+@cindex @code{;} (semicolon), separating statements in actions
+@cindex semicolon (@code{;}), separating statements in actions
An action consists of one or more @command{awk} @dfn{statements}, enclosed
-in curly braces (@samp{@{} and @samp{@}}). Each statement specifies one
+in curly braces (@samp{@{@dots{}@}}). Each statement specifies one
thing to do. The statements are separated by newlines or semicolons.
The curly braces around an action must be used even if the action
contains only one statement, or if it contains no statements at
@@ -9146,53 +9608,67 @@ well. An omitted action is equivalent to @samp{@{ print $0 @}}:
The following types of statements are supported in @command{awk}:
-@itemize @bullet
-@cindex side effects
-@item
-Expressions, which can call functions or assign values to variables
+@table @asis
+@cindex side effects, statements
+@item Expressions
+Call functions or assign values to variables
(@pxref{Expressions}). Executing
this kind of statement simply computes the value of the expression.
This is useful when the expression has side effects
(@pxref{Assignment Ops, ,Assignment Expressions}).
-@item
-Control statements, which specify the control flow of @command{awk}
+@item Control statements
+Specify the control flow of @command{awk}
programs. The @command{awk} language gives you C-like constructs
(@code{if}, @code{for}, @code{while}, and @code{do}) as well as a few
special ones (@pxref{Statements, ,Control Statements in Actions}).
-@item
-Compound statements, which consist of one or more statements enclosed in
+@item Compound statements
+Consist of one or more statements enclosed in
curly braces. A compound statement is used in order to put several
statements together in the body of an @code{if}, @code{while}, @code{do},
or @code{for} statement.
-@item
-Input statements using the @code{getline} command
-(@pxref{Getline, ,Explicit Input with @code{getline}}), the @code{next}
+@item Input statements
+Use the @code{getline} command
+(@pxref{Getline, ,Explicit Input with @code{getline}}).
+Also supplied in @command{awk} are the @code{next}
statement (@pxref{Next Statement, ,The @code{next} Statement}),
and the @code{nextfile} statement
(@pxref{Nextfile Statement, ,Using @command{gawk}'s @code{nextfile} Statement}).
-@item
-Output statements, such as @code{print} and @code{printf}.
+@item Output statements
+Such as @code{print} and @code{printf}.
@xref{Printing, ,Printing Output}.
-@item
-Deletion statements for deleting array elements.
+@item Deletion statements
+For deleting array elements.
@xref{Delete, ,The @code{delete} Statement}.
-@end itemize
+@end table
@node Statements, Built-in Variables, Action Overview, Patterns and Actions
@section Control Statements in Actions
-@cindex control statement
+@c STARTOFRANGE csta
+@cindex control statements
+@c STARTOFRANGE acs
+@cindex statements, control, in actions
+@c STARTOFRANGE accs
+@cindex actions, control statements in
@dfn{Control statements}, such as @code{if}, @code{while}, and so on,
control the flow of execution in @command{awk} programs. Most of the
control statements in @command{awk} are patterned on similar statements in C.
-@cindex compound statement
-@cindex statement, compound
+@c the comma here does NOT start a secondary
+@cindex compound statements, control statements and
+@c the second comma here does NOT start a tertiary
+@cindex statements, compound, control statements and
+@cindex body, in actions
+@cindex @code{@{@}} (braces), statements, grouping
+@cindex braces (@code{@{@}}), statements, grouping
+@cindex newlines, separating statements in actions
+@cindex @code{;} (semicolon), separating statements in actions
+@cindex semicolon (@code{;}), separating statements in actions
All the control statements start with special keywords, such as @code{if}
and @code{while}, to distinguish them from simple expressions.
Many control statements contain other statements. For example, the
@@ -9221,7 +9697,7 @@ newlines or semicolons.
@node If Statement, While Statement, Statements, Statements
@subsection The @code{if}-@code{else} Statement
-@cindex @code{if}-@code{else} statement
+@cindex @code{if} statement
The @code{if}-@code{else} statement is @command{awk}'s decision-making
statement. It looks like this:
@@ -9235,7 +9711,7 @@ statement does. If the @var{condition} is true, @var{then-body} is
executed; otherwise, @var{else-body} is executed.
The @code{else} part of the statement is
optional. The condition is considered false if its value is zero or
-the null string; otherwise the condition is true.
+the null string; otherwise, the condition is true.
Refer to the following:
@example
@@ -9247,7 +9723,7 @@ else
In this example, if the expression @samp{x % 2 == 0} is true (that is,
if the value of @code{x} is evenly divisible by two), then the first
-@code{print} statement is executed; otherwise the second @code{print}
+@code{print} statement is executed; otherwise, the second @code{print}
statement is executed.
If the @code{else} keyword appears on the same line as @var{then-body} and
@var{then-body} is not a compound statement (i.e., not surrounded by
@@ -9269,8 +9745,8 @@ the first thing on its line.
@node While Statement, Do Statement, If Statement, Statements
@subsection The @code{while} Statement
@cindex @code{while} statement
-@cindex loop
-@cindex body of a loop
+@cindex loops
+@cindex loops, See Also @code{while} statement
In programming, a @dfn{loop} is a part of a program that can
be executed two or more times in succession.
@@ -9283,6 +9759,7 @@ while (@var{condition})
@var{body}
@end example
+@cindex body, in loops
@noindent
@var{body} is a statement called the @dfn{body} of the loop,
and @var{condition} is an expression that controls how long the loop
@@ -9364,7 +9841,7 @@ The following is an example of a @code{do} statement:
@end example
@noindent
-This program prints each input record ten times. However, it isn't a very
+This program prints each input record 10 times. However, it isn't a very
realistic example, since in this case an ordinary @code{while} would do
just as well. This situation reflects actual experience; only
occasionally is there a real use for a @code{do} statement.
@@ -9411,7 +9888,7 @@ such as @samp{x = y = 0}. This makes sense only if all the initial values
are equal. (But it is possible to initialize additional variables by writing
their assignments as separate statements preceding the @code{for} loop.)
-@cindex comma operator, not supported
+@c @cindex comma operator, not supported
The same is true of the @var{increment} part. Incrementing additional
variables requires separate statements at the end of the loop.
The C compound expression, using C's comma operator, is useful in
@@ -9444,6 +9921,7 @@ while (@var{condition}) @{
@}
@end example
+@cindex loops, @code{continue} statements and
@noindent
The only exception is when the @code{continue} statement
(@pxref{Continue Statement, ,The @code{continue} Statement}) is used
@@ -9524,11 +10002,12 @@ an @code{if}:
@}
@end example
-@cindex @code{break}, outside of loops
-@cindex historical features
-@cindex @command{awk} language, POSIX version
-@cindex POSIX @command{awk}
-@cindex dark corner
+@c @cindex @code{break}, outside of loops
+@c @cindex historical features
+@c @cindex @command{awk} language, POSIX version
+@cindex POSIX @command{awk}, @code{break} statement and
+@cindex dark corner, @code{break} statement
+@cindex @command{gawk}, @code{break} statement in
The @code{break} statement has no meaning when
used outside the body of a loop. However, although it was never documented,
historical implementations of @command{awk} treated the @code{break}
@@ -9571,9 +10050,9 @@ BEGIN @{
@end example
@noindent
-This program prints all the numbers from 0 to 20---except for five, for
+This program prints all the numbers from 0 to 20---except for 5, for
which the @code{printf} is skipped. Because the increment @samp{x++}
-is not skipped, @code{x} does not remain stuck at five. Contrast the
+is not skipped, @code{x} does not remain stuck at 5. Contrast the
@code{for} loop from the previous example with the following @code{while} loop:
@example
@@ -9590,13 +10069,14 @@ BEGIN @{
@end example
@noindent
-This program loops forever once @code{x} reaches five.
-
-@cindex @code{continue}, outside of loops
-@cindex historical features
-@cindex @command{awk} language, POSIX version
-@cindex POSIX @command{awk}
-@cindex dark corner
+This program loops forever once @code{x} reaches 5.
+
+@c @cindex @code{continue}, outside of loops
+@c @cindex historical features
+@c @cindex @command{awk} language, POSIX version
+@cindex POSIX @command{awk}, @code{continue} statement and
+@cindex dark corner, @code{continue} statement
+@cindex @command{gawk}, @code{continue} statement in
The @code{continue} statement has no meaning when used outside the body of
a loop. Historical versions of @command{awk} treated a @code{continue}
statement outside a loop the same way they treated a @code{break}
@@ -9625,6 +10105,7 @@ Contrast this with the effect of the @code{getline} function
flow of control in any way (i.e., the rest of the current action executes
with a new input record).
+@cindex @command{awk} programs, execution of
At the highest level, @command{awk} program execution is a loop that reads
an input record and then tests each rule's pattern against it. If you
think of this loop as a @code{for} statement whose body contains the
@@ -9650,11 +10131,16 @@ Because of the @code{next} statement,
the program's subsequent rules won't see the bad record. The error
message is redirected to the standard error output stream, as error
messages should be.
-@xref{Special Files, ,Special @value{FFN}s in @command{gawk}}.
-
-@cindex @command{awk} language, POSIX version
-@cindex POSIX @command{awk}
-@cindex @code{next}, inside a user-defined function
+For more detail see
+@ref{Special Files, ,Special @value{FFN}s in @command{gawk}}.
+
+@c @cindex @command{awk} language, POSIX version
+@c @cindex @code{next}, inside a user-defined function
+@cindex @code{BEGIN} pattern, @code{next}/@code{nextfile} statements and
+@cindex @code{END} pattern, @code{next}/@code{nextfile} statements and
+@cindex POSIX @command{awk}, @code{next}/@code{nextfile} statements and
+@cindex @code{next} statement, user-defined functions and
+@cindex functions, user-defined, @code{next}/@code{nextfile} statements and
According to the POSIX standard, the behavior is undefined if
the @code{next} statement is used in a @code{BEGIN} or @code{END} rule.
@command{gawk} treats it as a syntax error.
@@ -9672,7 +10158,7 @@ then the code in any @code{END} rules is executed.
@node Nextfile Statement, Exit Statement, Next Statement, Statements
@subsection Using @command{gawk}'s @code{nextfile} Statement
@cindex @code{nextfile} statement
-@cindex differences between @command{gawk} and @command{awk}
+@cindex differences in @command{awk} and @command{gawk}, @code{next}/@code{nextfile} statements
@command{gawk} provides the @code{nextfile} statement,
which is similar to the @code{next} statement.
@@ -9713,7 +10199,8 @@ If it's necessary to use an @command{awk} version that doesn't support
for a user-defined function that simulates the @code{nextfile}
statement.
-@cindex @code{nextfile}, inside a user-defined function
+@cindex functions, user-defined, @code{next}/@code{nextfile} statements and
+@cindex @code{nextfile} statement, user-defined functions and
The current version of the Bell Laboratories @command{awk}
(@pxref{Other Versions, ,Other Freely Available @command{awk} Implementations})
also supports @code{nextfile}. However, it doesn't allow the @code{nextfile}
@@ -9723,7 +10210,10 @@ statement inside function bodies
function body reads the next record and starts processing it with the
first rule in the program, just as any other @code{nextfile} statement.
-@cindex @code{next file} statement
+@cindex @code{next file} statement, in @command{gawk}
+@cindex @command{gawk}, @code{next file} statement in
+@cindex @code{nextfile} statement, in @command{gawk}
+@cindex @command{gawk}, @code{nextfile} statement in
@strong{Caution:} Versions of @command{gawk} prior to 3.0 used two
words (@samp{next file}) for the @code{nextfile} statement.
In @value{PVERSION} 3.0, this was changed
@@ -9744,6 +10234,8 @@ is ignored. The @code{exit} statement is written as follows:
exit @r{[}@var{return code}@r{]}
@end example
+@cindex @code{BEGIN} pattern, @code{exit} statement and
+@cindex @code{END} pattern, @code{exit} statement and
When an @code{exit} statement is executed from a @code{BEGIN} rule, the
program stops processing everything immediately. No input records are
read. However, if an @code{END} rule is present,
@@ -9765,7 +10257,7 @@ the @code{END} rule.
@xref{Assert Function, ,Assertions},
for an example that does this.
-@cindex dark corner
+@cindex dark corner, @code{exit} statement
If an argument is supplied to @code{exit}, its value is used as the exit
status code for the @command{awk} process. If no argument is supplied,
@code{exit} returns status zero (success). In the case where an argument
@@ -9774,8 +10266,7 @@ called a second time from an @code{END} rule with no argument,
@command{awk} uses the previously supplied exit value.
@value{DARKCORNER}
-@cindex conventions, programming
-@cindex programming conventions
+@cindex programming conventions, @code{exit} statement
For example, suppose an error condition occurs that is difficult or
impossible to handle. Conventionally, programs report this by
exiting with a nonzero status. An @command{awk} program can do this
@@ -9792,12 +10283,18 @@ BEGIN @{
close("date")
@}
@end example
+@c ENDOFRANGE csta
+@c ENDOFRANGE acs
+@c ENDOFRANGE accs
@node Built-in Variables, , Statements, Patterns and Actions
@section Built-in Variables
+@c STARTOFRANGE bvar
@cindex built-in variables
+@c STARTOFRANGE varb
+@cindex variables, built-in
-Most @command{awk} variables are available for you to use for your own
+Most @command{awk} variables are available to use for your own
purposes; they never change unless your program assigns values to
them, and they never affect anything unless your program examines them.
However, a few variables in @command{awk} have special built-in meanings.
@@ -9806,6 +10303,7 @@ to tell @command{awk} how to do certain things. Others are set
automatically by @command{awk}, so that they carry information from the
internal workings of @command{awk} to your program.
+@cindex @command{gawk}, built-in variables and
This @value{SECTION} documents all the built-in variables of
@command{gawk}, most of which are also documented in the chapters
describing their areas of activity.
@@ -9820,7 +10318,10 @@ describing their areas of activity.
@node User-modified, Auto-set, Built-in Variables, Built-in Variables
@subsection Built-in Variables That Control @command{awk}
-@cindex built-in variables, user modifiable
+@c STARTOFRANGE bvaru
+@cindex built-in variables, user-modifiable
+@c STARTOFRANGE nmbv
+@cindex user-modifiable variables
The following is an alphabetical list of variables that you can change to
control how @command{awk} does certain things. The variables that are
@@ -9828,12 +10329,11 @@ specific to @command{gawk} are marked with a pound sign (@samp{#}).
@table @code
@cindex @code{BINMODE} variable
-@cindex binary I/O
-@cindex I/O, binary
-@cindex differences between @command{gawk} and @command{awk}
+@cindex binary input/output
+@cindex input/output, binary
@item BINMODE #
-On non-POSIX systems, this variable specifies use of ``binary'' mode for all I/O.
-Numeric values of one, two, or three, specify that input files, output files, or
+On non-POSIX systems, this variable specifies use of binary mode for all I/O.
+Numeric values of one, two, or three specify that input files, output files, or
all files, respectively, should use binary I/O.
Alternatively,
string values of @code{"r"} or @code{"w"} specify that input files and
@@ -9845,6 +10345,7 @@ generates a warning message.
@code{BINMODE} is described in more detail in
@ref{PC Using, ,Using @command{gawk} on PC Operating Systems}.
+@cindex differences in @command{awk} and @command{gawk}, @code{BINMODE} variable
This variable is a @command{gawk} extension.
In other @command{awk} implementations
(except @command{mawk},
@@ -9854,8 +10355,9 @@ or if @command{gawk} is in compatibility mode
it is not special.
@cindex @code{CONVFMT} variable
-@cindex @command{awk} language, POSIX version
-@cindex POSIX @command{awk}
+@cindex POSIX @command{awk}, @code{CONVFMT} variable and
+@cindex numbers, converting, to strings
+@cindex strings, converting, numbers to
@item CONVFMT
This string controls conversion of numbers to
strings (@pxref{Conversion, ,Conversion of Strings and Numbers}).
@@ -9866,6 +10368,9 @@ Its default value is @code{"%.6g"}.
@code{CONVFMT} was introduced by the POSIX standard.
@cindex @code{FIELDWIDTHS} variable
+@cindex differences in @command{awk} and @command{gawk}, @code{FIELDWIDTHS} variable
+@cindex field separators, @code{FIELDWIDTHS} variable and
+@cindex separators, field, @code{FIELDWIDTHS} variable and
@item FIELDWIDTHS #
This is a space-separated list of columns that tells @command{gawk}
how to split input with fixed columnar boundaries.
@@ -9873,12 +10378,15 @@ Assigning a value to @code{FIELDWIDTHS}
overrides the use of @code{FS} for field splitting.
@xref{Constant Size, ,Reading Fixed-Width Data}, for more information.
+@cindex @command{gawk}, @code{FIELDWIDTHS} variable in
If @command{gawk} is in compatibility mode
(@pxref{Options, ,Command-Line Options}), then @code{FIELDWIDTHS}
has no special meaning, and field-splitting operations occur based
exclusively on the value of @code{FS}.
@cindex @code{FS} variable
+@cindex separators, field
+@cindex field separators
@item FS
This is the input field separator
(@pxref{Field Separators, ,Specifying How Fields Are Separated}).
@@ -9890,6 +10398,7 @@ character in the record becomes a separate field.
specify the behavior when @code{FS} is the null string.)
@c NEXT ED: Mark as common extension
+@cindex POSIX @command{awk}, @code{FS} variable and
The default value is @w{@code{" "}}, a string consisting of a single
space. As a special exception, this value means that any
sequence of spaces, tabs, and/or newlines is a single separator.@footnote{In
@@ -9903,15 +10412,20 @@ You can set the value of @code{FS} on the command line using the
awk -F, '@var{program}' @var{input-files}
@end example
+@cindex @command{gawk}, field separators and
If @command{gawk} is using @code{FIELDWIDTHS} for field splitting,
assigning a value to @code{FS} causes @command{gawk} to return to
the normal, @code{FS}-based field splitting. An easy way to do this
is to simply say @samp{FS = FS}, perhaps with an explanatory comment.
@cindex @code{IGNORECASE} variable
+@cindex differences in @command{awk} and @command{gawk}, @code{IGNORECASE} variable
+@cindex case sensitivity, string comparisons and
+@cindex case sensitivity, regexps and
+@cindex regular expressions, case sensitivity
@item IGNORECASE #
If @code{IGNORECASE} is nonzero or non-null, then all string comparisons
-and all regular expression matching are case-independent. Thus, regexp
+and all regular expression matching are case independent. Thus, regexp
matching with @samp{~} and @samp{!~}, as well as the @code{gensub},
@code{gsub}, @code{index}, @code{match}, @code{split}, and @code{sub}
functions, record termination with @code{RS}, and field splitting with
@@ -9919,22 +10433,24 @@ functions, record termination with @code{RS}, and field splitting with
However, the value of @code{IGNORECASE} does @emph{not} affect array subscripting.
@xref{Case-sensitivity, ,Case Sensitivity in Matching}.
+@cindex @command{gawk}, @code{IGNORECASE} variable in
If @command{gawk} is in compatibility mode
(@pxref{Options, ,Command-Line Options}),
then @code{IGNORECASE} has no special meaning. Thus, string
and regexp operations are always case-sensitive.
@cindex @code{LINT} variable
-@cindex differences between @command{gawk} and @command{awk}
-@cindex lint checks
+@cindex differences in @command{awk} and @command{gawk}, @code{LINT} variable
+@cindex lint checking
@item LINT #
When this variable is true (nonzero or non-null), @command{gawk}
behaves as if the @option{--lint} command-line option is in effect.
(@pxref{Options, ,Command-Line Options}).
With a value of @code{"fatal"}, lint warnings become fatal errors.
-Any other true value prints non-fatal warnings.
+Any other true value prints nonfatal warnings.
Assigning a false value to @code{LINT} turns off the lint warnings.
+@cindex @command{gawk}, @code{LINT} variable in
This variable is a @command{gawk} extension. It is not special
in other @command{awk} implementations. Unlike the other special variables,
changing @code{LINT} does affect the production of lint warnings,
@@ -9945,6 +10461,8 @@ of lint warnings during program execution is independent of the flavor
of @command{awk} being executed.
@cindex @code{OFMT} variable
+@cindex numbers, converting, to strings
+@cindex strings, converting, numbers to
@item OFMT
This string controls conversion of numbers to
strings (@pxref{Conversion, ,Conversion of Strings and Numbers}) for
@@ -9955,7 +10473,11 @@ Its default value is @code{"%.6g"}. Earlier versions of @command{awk}
also used @code{OFMT} to specify the format for converting numbers to
strings in general expressions; this is now done by @code{CONVFMT}.
+@cindex @code{sprintf} function, @code{OFMT} variable and
+@cindex @code{print} statement, @code{OFMT} variable and
@cindex @code{OFS} variable
+@cindex separators, field
+@cindex field separators
@item OFS
This is the output field separator (@pxref{Output Separators}). It is
output between the fields printed by a @code{print} statement. Its
@@ -9968,6 +10490,8 @@ This is the output record separator. It is output at the end of every
character. (@xref{Output Separators}.)
@cindex @code{RS} variable
+@cindex separators, record
+@cindex record separators
@item RS
This is @command{awk}'s input record separator. Its default value is a string
containing a single newline character, which means that an input record
@@ -9986,6 +10510,8 @@ or if @command{gawk} is in compatibility mode
just the first character of @code{RS}'s value is used.
@cindex @code{SUBSEP} variable
+@cindex separators, subscript
+@cindex subscript separators
@item SUBSEP
This is the subscript separator. It has the default value of
@code{"\034"} and is used to separate the parts of the indices of a
@@ -9994,12 +10520,13 @@ really accesses @code{foo["A\034B"]}
(@pxref{Multi-dimensional, ,Multidimensional Arrays}).
@cindex @code{TEXTDOMAIN} variable
-@cindex internationalization
+@cindex differences in @command{awk} and @command{gawk}, @code{TEXTDOMAIN} variable
+@cindex internationalization, localization
@item TEXTDOMAIN #
This variable is used for internationalization of programs at the
@command{awk} level. It sets the default text domain for specially
marked string constants in the source text, as well as for the
-@code{dcgettext} and @code{bindtextdomain} functions
+@code{dcgettext}, @code{dcngettext} and @code{bindtextdomain} functions
(@pxref{Internationalization, ,Internationalization with @command{gawk}}).
The default value of @code{TEXTDOMAIN} is @code{"messages"}.
@@ -10009,19 +10536,27 @@ or if @command{gawk} is in compatibility mode
(@pxref{Options, ,Command-Line Options}),
it is not special.
@end table
+@c ENDOFRANGE bvar
+@c ENDOFRANGE varb
+@c ENDOFRANGE bvaru
+@c ENDOFRANGE nmbv
@node Auto-set, ARGC and ARGV, User-modified, Built-in Variables
@subsection Built-in Variables That Convey Information
-@cindex built-in variables, convey information
+@c STARTOFRANGE bvconi
+@cindex built-in variables, conveying information
+@c STARTOFRANGE vbconi
+@cindex variables, built-in, conveying information
The following is an alphabetical list of variables that @command{awk}
sets automatically on certain occasions in order to provide
information to your program. The variables that are specific to
@command{gawk} are marked with an asterisk (@samp{*}).
@table @code
-@cindex @code{ARGC} variable
-@cindex @code{ARGV} variable
+@cindex @code{ARGC}/@code{ARGV} variables
+@cindex arguments, command-line
+@cindex command line, arguments
@item ARGC@r{,} ARGV
The command-line arguments available to @command{awk} programs are stored in
an array called @code{ARGV}. @code{ARGC} is the number of command-line
@@ -10042,13 +10577,12 @@ $ awk 'BEGIN @{
@noindent
@code{ARGV[0]} contains @code{"awk"}, @code{ARGV[1]}
-contains @code{"inventory-shipped"} and @code{ARGV[2]} contains
+contains @code{"inventory-shipped"}, and @code{ARGV[2]} contains
@code{"BBS-list"}. The value of @code{ARGC} is three, one more than the
index of the last element in @code{ARGV}, because the elements are numbered
from zero.
-@cindex conventions, programming
-@cindex programming conventions
+@cindex programming conventions, @code{ARGC}/@code{ARGV} variables
The names @code{ARGC} and @code{ARGV}, as well as the convention of indexing
the array from 0 to @code{ARGC} @minus{} 1, are derived from the C language's
method of accessing command-line arguments.
@@ -10060,17 +10594,21 @@ Also, you should note that the program text is @emph{not} included in
about how @command{awk} uses these variables.
@cindex @code{ARGIND} variable
+@cindex differences in @command{awk} and @command{gawk}, @code{ARGIND} variable
@item ARGIND #
-This is the index in @code{ARGV} of the current file being processed.
+The index in @code{ARGV} of the current file being processed.
Every time @command{gawk} opens a new @value{DF} for processing, it sets
@code{ARGIND} to the index in @code{ARGV} of the @value{FN}.
When @command{gawk} is processing the input files,
@samp{FILENAME == ARGV[ARGIND]} is always true.
+@c comma before ARGIND does NOT mark a tertiary
+@cindex files, processing, @code{ARGIND} variable and
This variable is useful in file processing; it allows you to tell how far
along you are in the list of @value{DF}s as well as to distinguish between
successive instances of the same @value{FN} on the command line.
+@cindex @value{FN}s, distinguishing
While you can change the value of @code{ARGIND} within your @command{awk}
program, @command{gawk} automatically sets it to a new value when the
next file is opened.
@@ -10082,6 +10620,7 @@ or if @command{gawk} is in compatibility mode
it is not special.
@cindex @code{ENVIRON} variable
+@cindex environment variables
@item ENVIRON
An associative array that contains the values of the environment. The array
indices are the environment variable names; the elements are the values of
@@ -10097,6 +10636,8 @@ On such systems, the @code{ENVIRON} array is empty (except for
@pxref{AWKPATH Variable, ,The @env{AWKPATH} Environment Variable}).
@cindex @code{ERRNO} variable
+@cindex differences in @command{awk} and @command{gawk}, @code{ERRNO} variable
+@cindex error handling, @code{ERRNO} variable and
@item ERRNO #
If a system error occurs during a redirection for @code{getline},
during a read for @code{getline}, or during a @code{close} operation,
@@ -10108,10 +10649,10 @@ or if @command{gawk} is in compatibility mode
(@pxref{Options, ,Command-Line Options}),
it is not special.
-@cindex dark corner
@cindex @code{FILENAME} variable
+@cindex dark corner, @code{FILENAME} variable
@item FILENAME
-This is the name of the file that @command{awk} is currently reading.
+The name of the file that @command{awk} is currently reading.
When no @value{DF}s are listed on the command line, @command{awk} reads
from the standard input and @code{FILENAME} is set to @code{"-"}.
@code{FILENAME} is changed each time a new file is read
@@ -10123,32 +10664,33 @@ yet.@footnote{Some early implementations of Unix @command{awk} initialized
processed. This behavior was incorrect and should not be relied
upon in your programs.}
@value{DARKCORNER}
-Note though, that using @code{getline}
+Note, though, that using @code{getline}
(@pxref{Getline, ,Explicit Input with @code{getline}})
inside a @code{BEGIN} rule can give
@code{FILENAME} a value.
@cindex @code{FNR} variable
@item FNR
-This is the current record number in the current file. @code{FNR} is
+The current record number in the current file. @code{FNR} is
incremented each time a new record is read
(@pxref{Getline, ,Explicit Input with @code{getline}}). It is reinitialized
to zero each time a new input file is started.
@cindex @code{NF} variable
@item NF
-This is the number of fields in the current input record.
+The number of fields in the current input record.
@code{NF} is set each time a new record is read, when a new field is
created or when @code{$0} changes (@pxref{Fields, ,Examining Fields}).
@cindex @code{NR} variable
@item NR
-This is the number of input records @command{awk} has processed since
+The number of input records @command{awk} has processed since
the beginning of the program's execution
(@pxref{Records, ,How Input Is Split into Records}).
@code{NR} is incremented each time a new record is read.
-@cindex @code{PROCINFO} variable
+@cindex @code{PROCINFO} array
+@cindex differences in @command{awk} and @command{gawk}, @code{PROCINFO} array
@item PROCINFO #
The elements of this array provide access to information about the
running @command{awk} program.
@@ -10197,7 +10739,7 @@ it is not special.
@cindex @code{RLENGTH} variable
@item RLENGTH
-This is the length of the substring matched by the
+The length of the substring matched by the
@code{match} function
(@pxref{String Functions, ,String Manipulation Functions}).
@code{RLENGTH} is set by invoking the @code{match} function. Its value
@@ -10205,7 +10747,7 @@ is the length of the matched string, or @minus{}1 if no match is found.
@cindex @code{RSTART} variable
@item RSTART
-This is the start-index in characters of the substring that is matched by the
+The start-index in characters of the substring that is matched by the
@code{match} function
(@pxref{String Functions, ,String Manipulation Functions}).
@code{RSTART} is set by invoking the @code{match} function. Its value
@@ -10213,6 +10755,7 @@ is the position of the string where the matched substring starts, or zero
if no match was found.
@cindex @code{RT} variable
+@cindex differences in @command{awk} and @command{gawk}, @code{RT} variable
@item RT #
This is set each time a record is read. It contains the input text
that matched the text denoted by @code{RS}, the record separator.
@@ -10223,11 +10766,15 @@ or if @command{gawk} is in compatibility mode
(@pxref{Options, ,Command-Line Options}),
it is not special.
@end table
+@c ENDOFRANGE bvconi
+@c ENDOFRANGE vbconi
@c fakenode --- for prepinfo
@subheading Advanced Notes: Changing @code{NR} and @code{FNR}
-@cindex advanced notes
-@cindex dark corner
+@cindex @code{NR} variable, changing
+@cindex @code{FNR} variable, changing
+@cindex advanced features, @code{FNR}/@code{NR} variables
+@cindex dark corner, @code{FNR}/@code{NR} variables
@command{awk} increments @code{NR} and @code{FNR}
each time it reads a record, instead of setting them to the absolute
value of the number of records read. This means that a program can
@@ -10257,6 +10804,9 @@ changed.
@node ARGC and ARGV, , Auto-set, Built-in Variables
@subsection Using @code{ARGC} and @code{ARGV}
+@cindex @code{ARGC}/@code{ARGV} variables
+@cindex arguments, command-line
+@cindex command line, arguments
@ref{Auto-set, ,Built-in Variables That Convey Information},
presented the following program describing the information contained in @code{ARGC}
@@ -10355,7 +10905,7 @@ the @command{awk} program's options, in the following manner:
awk -f myprog -- -v -d file1 file2 @dots{}
@end example
-@cindex differences between @command{gawk} and @command{awk}
+@cindex differences in @command{awk} and @command{gawk}, @code{ARGC}/@code{ARGV} variables
This is not necessary in @command{gawk}. Unless @option{--posix} has
been specified, @command{gawk} silently puts any unrecognized options
into @code{ARGV} for the @command{awk} program to deal with. As soon
@@ -10374,6 +10924,8 @@ are passed on to the @command{awk} program.
@node Arrays, Functions, Patterns and Actions, Top
@chapter Arrays in @command{awk}
+@c STARTOFRANGE arrs
+@cindex arrays
An @dfn{array} is a table of values called @dfn{elements}. The
elements of an array are distinguished by their indices. @dfn{Indices}
@@ -10387,8 +10939,11 @@ arrays, as well as some of the less obvious points about array usage.
The @value{CHAPTER} finishes with a discussion of @command{gawk}'s facility
for sorting an array based on its indices.
-@cindex names, use of
-@cindex namespace issues in @command{awk}
+@cindex variables, names of
+@cindex functions, names of
+@cindex arrays, names of
+@cindex names, arrays/variables
+@cindex namespace issues
@command{awk} maintains a single set
of names that may be used for naming variables, arrays, and functions
(@pxref{User-defined, ,User-Defined Functions}).
@@ -10417,7 +10972,6 @@ same @command{awk} program.
@node Array Intro, Reference to Elements, Arrays, Arrays
@section Introduction to Arrays
-@cindex arrays
The @command{awk} language provides one-dimensional arrays
for storing groups of related strings or numbers.
Every @command{awk} array must have a name. Array names have the same
@@ -10480,14 +11034,17 @@ conceptually, if the element values are 8, @code{"foo"},
@noindent
Only the values are stored; the indices are implicit from the order of
-the values. 8 is the value at index zero, because 8 appears in the
+the values. Here, 8 is the value at index zero, because 8 appears in the
position with zero elements before it.
-@cindex arrays, definition of
+@c STARTOFRANGE arrin
+@cindex arrays, indexing
+@c STARTOFRANGE inarr
+@cindex indexing arrays
@cindex associative arrays
@cindex arrays, associative
Arrays in @command{awk} are different---they are @dfn{associative}. This means
-that each array is a collection of pairs: an index, and its corresponding
+that each array is a collection of pairs: an index and its corresponding
array element value:
@example
@@ -10521,7 +11078,7 @@ It has elements 0--3 and 10, but doesn't have elements 4, 5, 6, 7, 8, or 9.
Another consequence of associative arrays is that the indices don't
have to be positive integers. Any number, or even a string, can be
an index. For example, the following is an array that translates words from
-English into French:
+English to French:
@example
@r{Element} "dog" @r{Value} "chien"
@@ -10540,9 +11097,9 @@ in more detail in
Here, the number @code{1} isn't double-quoted, since @command{awk}
automatically converts it to a string.
-@cindex arrays, subscripts, and @code{IGNORECASE}
-@cindex @code{IGNORECASE}, and array subscripts
-@cindex @code{IGNORECASE} variable
+@cindex case sensitivity, array indices and
+@cindex arrays, @code{IGNORECASE} variable and
+@cindex @code{IGNORECASE} variable, array subscripts and
The value of @code{IGNORECASE} has no effect upon array subscripting.
The identical string value used to store an array element must be used
to retrieve it.
@@ -10553,12 +11110,13 @@ that array's indices are consecutive integers starting at one.
@command{awk}'s arrays are efficient---the time to access an element
is independent of the number of elements in the array.
+@c ENDOFRANGE arrin
+@c ENDOFRANGE inarr
@node Reference to Elements, Assigning Elements, Array Intro, Arrays
@section Referring to an Array Element
-@cindex array reference
-@cindex element of array
-@cindex reference to array
+@cindex arrays, elements, referencing
+@cindex elements in arrays
The principal way to use an array is to refer to one of its elements.
An array reference is an expression as follows:
@@ -10583,8 +11141,8 @@ automatically creates that array element, with the null string as its value.
(In some cases, this is unfortunate, because it might waste memory inside
@command{awk}.)
-@cindex arrays, presence of elements
-@cindex arrays, the @code{in} operator
+@c @cindex arrays, @code{in} operator and
+@cindex @code{in} operator, arrays and
To determine whether an element exists in an array at a certain index, use
the following expression:
@@ -10592,9 +11150,9 @@ the following expression:
@var{index} in @var{array}
@end example
-@cindex side effects
+@cindex side effects, array indexing
@noindent
-This expression tests whether or not the particular index exists,
+This expression tests whether the particular index exists,
without the side effect of creating that element if it is not present.
The expression has the value one (true) if @code{@var{array}[@var{index}]}
exists and zero (false) if it does not exist.
@@ -10619,8 +11177,8 @@ if (frequencies[2] != "")
@node Assigning Elements, Array Example, Reference to Elements, Arrays
@section Assigning Array Elements
-@cindex array assignment
-@cindex element assignment
+@cindex arrays, elements, assigning
+@cindex elements in arrays, assigning
Array elements can be assigned values just like
@command{awk} variables:
@@ -10680,7 +11238,7 @@ When this program is run with the following input:
@end example
@noindent
-its output is:
+Its output is:
@example
1 Who is number one?
@@ -10705,10 +11263,8 @@ END @{
@node Scanning an Array, Delete, Array Example, Arrays
@section Scanning All Elements of an Array
-@cindex @code{for (x in @dots{})} statement
-@cindex arrays, special @code{for} statement
-@cindex scanning an array
-@cindex @code{in} operator
+@cindex elements in arrays, scanning
+@cindex arrays, scanning
In programs that use arrays, it is often necessary to use a loop that
executes once for each element of an array. In other languages, where
@@ -10725,9 +11281,12 @@ for (@var{var} in @var{array})
@end example
@noindent
+@cindex @code{in} operator, arrays and
This loop executes @var{body} once for each index in @var{array} that the
program has previously used, with the variable @var{var} set to that index.
+@cindex arrays, @code{for} statement and
+@cindex @code{for} statement, in arrays
The following program uses this form of the @code{for} statement. The
first rule scans the input records and notes which words appear (at
least once) in the input, by storing a one into the array @code{used} with
@@ -10760,20 +11319,22 @@ END @{
@xref{Word Sorting, ,Generating Word Usage Counts},
for a more detailed example of this type.
+@cindex arrays, elements, order of
+@cindex elements in arrays, order of
The order in which elements of the array are accessed by this statement
is determined by the internal arrangement of the array elements within
@command{awk} and cannot be controlled or changed. This can lead to
problems if new elements are added to @var{array} by statements in
-the loop body; it is not predictable whether or not the @code{for} loop will
+the loop body; it is not predictable whether the @code{for} loop will
reach them. Similarly, changing @var{var} inside the loop may produce
strange results. It is best to avoid such things.
@node Delete, Numeric Array Subscripts, Scanning an Array, Arrays
@section The @code{delete} Statement
@cindex @code{delete} statement
-@cindex deleting elements of arrays
-@cindex removing elements of arrays
-@cindex arrays, deleting an element
+@cindex deleting elements in arrays
+@cindex arrays, elements, deleting
+@cindex elements in arrays, deleting
To remove an individual element of an array, use the @code{delete}
statement:
@@ -10804,6 +11365,7 @@ if (4 in foo)
print "This will never be printed"
@end example
+@cindex null strings, array elements and
It is important to note that deleting an element is @emph{not} the
same as assigning it a null value (the empty string, @code{""}).
For example:
@@ -10814,7 +11376,7 @@ if (4 in foo)
print "This is printed, even though foo[4] is empty"
@end example
-@cindex lint checks
+@cindex lint checking, array elements
It is not an error to delete an element that does not exist.
If @option{--lint} is provided on the command line
(@pxref{Options, ,Command-Line Options}),
@@ -10823,7 +11385,7 @@ is not in the array is deleted.
@cindex arrays, deleting entire contents
@cindex deleting entire arrays
-@cindex differences between @command{gawk} and @command{awk}
+@cindex differences in @command{awk} and @command{gawk}, array elements, deleting
All the elements of an array may be deleted with a single statement
by leaving off the subscript in the @code{delete} statement,
as follows:
@@ -10839,15 +11401,17 @@ Using this version of the @code{delete} statement is about three times
more efficient than the equivalent loop that deletes each element one
at a time.
-@cindex portability issues
+@cindex portability, deleting array elements
@cindex Brennan, Michael
-The following statement provides a portable but non-obvious way to clear
+The following statement provides a portable but nonobvious way to clear
out an array:@footnote{Thanks to Michael Brennan for pointing this out.}
@example
split("", array)
@end example
+@c comma before deleting does NOT start a tertiary
+@cindex @code{split} function, array elements, deleting
The @code{split} function
(@pxref{String Functions, ,String Manipulation Functions})
clears out the target array first. This call asks it to split
@@ -10865,9 +11429,10 @@ a[1] = 3; delete a; a = 3
@node Numeric Array Subscripts, Uninitialized Subscripts, Delete, Arrays
@section Using Numbers to Subscript Arrays
-@cindex conversions, during subscripting
-@cindex numbers, used as subscripts
-@cindex @code{CONVFMT} variable
+@cindex numbers, as array subscripts
+@cindex arrays, subscripts
+@cindex subscripts in arrays, numbers as
+@cindex @code{CONVFMT} variable, array subscripts and
An important aspect about arrays to remember is that @emph{array subscripts
are always strings}. When a numeric value is used as a subscript,
it is converted to a string value before being used for subscripting
@@ -10897,6 +11462,7 @@ string value from @code{xyz}---this time @code{"12.15"}---because the value of
@code{CONVFMT} only allows two significant digits. This test fails,
since @code{"12.15"} is a different string from @code{"12.153"}.
+@cindex converting, during subscripting
According to the rules for conversions
(@pxref{Conversion, ,Conversion of Strings and Numbers}), integer
values are always converted to strings as integers, no matter what the
@@ -10911,8 +11477,8 @@ for (i = 1; i <= maxsub; i++)
The ``integer values always convert to strings as integers'' rule
has an additional consequence for array indexing.
Octal and hexadecimal constants
-(@pxref{Non-decimal-numbers, ,Octal and Hexadecimal Numbers})
-are converted internally into numbers and their original form
+(@pxref{Nondecimal-numbers, ,Octal and Hexadecimal Numbers})
+are converted internally into numbers, and their original form
is forgotten.
This means, for example, that
@code{array[17]},
@@ -10929,8 +11495,11 @@ effect on your programs.
@node Uninitialized Subscripts, Multi-dimensional, Numeric Array Subscripts, Arrays
@section Using Uninitialized Variables as Subscripts
+@c last comma does NOT start a tertiary
+@cindex variables, uninitialized, as array subscripts
@cindex uninitialized variables, as array subscripts
-@cindex arrays, subscripts, uninitialized variables
+@cindex subscripts in arrays, uninitialized variables as
+@cindex arrays, subscripts, uninitialized variables as
Suppose it's necessary to write a program
to print the input data in reverse order.
A reasonable attempt to do so (with some test
@@ -10973,9 +11542,9 @@ Here, the @samp{++} forces @code{lines} to be numeric, thus making
the ``old value'' numeric zero. This is then converted to @code{"0"}
as the array subscript.
-@cindex null string, as array subscript
-@cindex dark corner
-@cindex lint checks
+@cindex null strings, as array subscripts
+@cindex dark corner, array subscripts
+@cindex lint checking, array subscripts
Even though it is somewhat unusual, the null string
(@code{""}) is a valid array subscript.
@value{DARKCORNER}
@@ -10986,9 +11555,8 @@ on the command line (@pxref{Options, ,Command-Line Options}).
@node Multi-dimensional, Multi-scanning, Uninitialized Subscripts, Arrays
@section Multidimensional Arrays
-@cindex subscripts in arrays
-@cindex arrays, multidimensional subscripts
-@cindex multidimensional subscripts
+@cindex subscripts in arrays, multidimensional
+@cindex arrays, multidimensional
A multidimensional array is an array in which an element is identified
by a sequence of indices instead of a single index. For example, a
two-dimensional array requires two indices. The usual way (in most
@@ -10996,7 +11564,7 @@ languages, including @command{awk}) to refer to an element of a
two-dimensional array named @code{grid} is with
@code{grid[@var{x},@var{y}]}.
-@cindex @code{SUBSEP} variable
+@cindex @code{SUBSEP} variable, multidimensional arrays
Multidimensional arrays are supported in @command{awk} through
concatenation of indices into one string.
@command{awk} converts the indices into strings
@@ -11019,7 +11587,7 @@ expressions @samp{foo[5,12]} and @w{@samp{foo[5 SUBSEP 12]}} are always
equivalent.
The default value of @code{SUBSEP} is the string @code{"\034"},
-which contains a non-printing character that is unlikely to appear in an
+which contains a nonprinting character that is unlikely to appear in an
@command{awk} program or in most input data.
The usefulness of choosing an unlikely character comes from the fact
that index values that contain a string matching @code{SUBSEP} can lead to
@@ -11029,7 +11597,7 @@ combined strings that are ambiguous. Suppose that @code{SUBSEP} is
stored as @samp{foo["a@@b@@c"]}.
To test whether a particular index sequence exists in a
-``multidimensional'' array, use the same operator (@samp{in}) that is
+multidimensional array, use the same operator (@samp{in}) that is
used for single dimensional arrays. Write the whole sequence of indices
in parentheses, separated by commas, as the left operand:
@@ -11040,7 +11608,7 @@ in parentheses, separated by commas, as the left operand:
The following example treats its input as a two-dimensional array of
fields; it rotates this array 90 degrees clockwise and prints the
result. It assumes that all lines have the same number of
-elements.
+elements:
@example
@{
@@ -11086,10 +11654,12 @@ the program produces the following output:
@section Scanning Multidimensional Arrays
There is no special @code{for} statement for scanning a
-``multidimensional'' array. There cannot be one, because in truth there
+``multidimensional'' array. There cannot be one, because, in truth, there
are no multidimensional arrays or elements---there is only a
multidimensional @emph{way of accessing} an array.
+@cindex subscripts in arrays, multidimensional, scanning
+@cindex arrays, multidimensional, scanning
However, if your program has an array that is always accessed as
multidimensional, you can get the effect of scanning it by combining
the scanning @code{for} statement
@@ -11132,7 +11702,10 @@ separate indices is recovered.
@section Sorting Array Values and Indices with @command{gawk}
@cindex arrays, sorting
-@cindex @code{asort} built-in function
+@cindex @code{asort} function (@command{gawk})
+@c last comma does NOT start a tertiary
+@cindex @code{asort} function (@command{gawk}), arrays, sorting
+@cindex sort function, arrays, sorting
The order in which an array is scanned with a @samp{for (i in array)}
loop is essentially arbitrary.
In most @command{awk} implementations, sorting an array requires
@@ -11158,7 +11731,7 @@ The comparison of array elements is done
using @command{gawk}'s usual comparison rules
(@pxref{Typing and Comparison, ,Variable Typing and Comparison Expressions}).
-@cindex side effects
+@cindex side effects, @code{asort} function
An important side effect of calling @code{asort} is that
@emph{the array's original indices are irrevocably lost}.
As this isn't always desirable, @code{asort} accepts a
@@ -11197,7 +11770,7 @@ Sorting the array by replacing the indices provides maximal flexibility.
To traverse the elements in decreasing order, use a loop that goes from
@var{n} down to 1, either over the elements or over the indices.
-@cindex reference counting
+@cindex reference counting, sorting arrays
Copying array indices and elements isn't expensive in terms of memory.
Internally, @command{gawk} maintains @dfn{reference counts} to data.
For example, when @code{asort} copies the first array to the second one,
@@ -11206,20 +11779,24 @@ both arrays use the values. Similarly, when copying the indices from
@code{data} to @code{ind}, there is only one copy of the actual index
strings.
-@cindex arrays, sorting and @code{IGNORECASE}
-@cindex @code{IGNORECASE}, and array sorting
-@cindex @code{IGNORECASE} variable
+@cindex arrays, sorting, @code{IGNORECASE} variable and
+@cindex @code{IGNORECASE} variable, array sorting and
As with array subscripts, the value of @code{IGNORECASE}
does not affect array sorting.
+@c ENDOFRANGE arrs
@node Functions, Internationalization, Arrays, Top
@chapter Functions
+@c STARTOFRANGE funcbi
+@cindex functions, built-in
+@c STARTOFRANGE bifunc
+@cindex built-in functions
This @value{CHAPTER} describes @command{awk}'s built-in functions,
which fall into three categories: numeric, string, and I/O.
@command{gawk} provides additional groups of functions
to work with values that represent time, do
-bit manipulation, and to internationalize and localize programs.
+bit manipulation, and internationalize and localize programs.
Besides the built-in functions, @command{awk} has provisions for
writing new functions that the rest of a program can use.
@@ -11235,7 +11812,6 @@ The second half of this @value{CHAPTER} describes these
@section Built-in Functions
@c 2e: USE TEXINFO-2 FUNCTION DEFINITION STUFF!!!!!!!!!!!!!
-@cindex built-in functions
@dfn{Built-in} functions are always available for
your @command{awk} program to call. This @value{SECTION} defines all
the built-in
@@ -11260,18 +11836,21 @@ but are summarized here for your convenience.
To call one of @command{awk}'s built-in functions, write the name of
the function followed
by arguments in parentheses. For example, @samp{atan2(y + z, 1)}
-is a call to the function @code{atan2}, and has two arguments.
+is a call to the function @code{atan2} and has two arguments.
-@cindex conventions, programming
-@cindex programming conventions
+@cindex programming conventions, functions, calling
+@c last comma does NOT start a tertiary
+@cindex whitespace, functions, calling
Whitespace is ignored between the built-in function name and the
open parenthesis, and it is good practice to avoid using whitespace
there. User-defined functions do not permit whitespace in this way, and
it is easier to avoid mistakes by following a simple
convention that always works---no whitespace after a function name.
-@cindex fatal errors
-@cindex differences between @command{gawk} and @command{awk}
+@c last comma is part of tertiary
+@cindex troubleshooting, @command{gawk}, fatal errors, function arguments
+@cindex @command{gawk}, function arguments and
+@cindex differences in @command{awk} and @command{gawk}, function arguments (@command{gawk})
Each built-in function accepts a certain number of arguments.
In some cases, arguments can be omitted. The defaults for omitted
arguments vary from function to function and are described under the
@@ -11288,8 +11867,9 @@ i = 4
j = sqrt(i++)
@end example
-@cindex evaluation, order of
-@cindex order of evaluation
+@cindex evaluation order, functions
+@cindex functions, built-in, evaluation order
+@cindex built-in functions, evaluation order
@noindent
the variable @code{i} is incremented to the value five before @code{sqrt}
is called with a value of four for its actual parameter.
@@ -11304,7 +11884,7 @@ j = atan2(i++, i *= 2)
@end example
If the order of evaluation is left to right, then @code{i} first becomes
-six, and then 12, and @code{atan2} is called with the two arguments 6
+6, and then 12, and @code{atan2} is called with the two arguments 6
and 12. But if the order of evaluation is right to left, @code{i}
first becomes 10, then 11, and @code{atan2} is called with the
two arguments 11 and 10.
@@ -11314,48 +11894,49 @@ two arguments 11 and 10.
The following list describes all of
the built-in functions that work with numbers.
-Optional parameters are enclosed in square brackets ([ and ]):
+Optional parameters are enclosed in square brackets ([ ]):
@table @code
@item int(@var{x})
-@cindex @code{int} built-in function
+@cindex @code{int} function
This returns the nearest integer to @var{x}, located between @var{x} and zero and
truncated toward zero.
-For example, @code{int(3)} is three, @code{int(3.9)} is three, @code{int(-3.9)}
+For example, @code{int(3)} is 3, @code{int(3.9)} is 3, @code{int(-3.9)}
is @minus{}3, and @code{int(-3)} is @minus{}3 as well.
@item sqrt(@var{x})
-@cindex @code{sqrt} built-in function
+@cindex @code{sqrt} function
This returns the positive square root of @var{x}.
@command{gawk} reports an error
-if @var{x} is negative. Thus, @code{sqrt(4)} is two.
+if @var{x} is negative. Thus, @code{sqrt(4)} is 2.
@item exp(@var{x})
-@cindex @code{exp} built-in function
+@cindex @code{exp} function
This returns the exponential of @var{x} (@code{e ^ @var{x}}) or reports
an error if @var{x} is out of range. The range of values @var{x} can have
depends on your machine's floating-point representation.
@item log(@var{x})
-@cindex @code{log} built-in function
+@cindex @code{log} function
This returns the natural logarithm of @var{x}, if @var{x} is positive;
otherwise, it reports an error.
@item sin(@var{x})
-@cindex @code{sin} built-in function
+@cindex @code{sin} function
This returns the sine of @var{x}, with @var{x} in radians.
@item cos(@var{x})
-@cindex @code{cos} built-in function
+@cindex @code{cos} function
This returns the cosine of @var{x}, with @var{x} in radians.
@item atan2(@var{y}, @var{x})
-@cindex @code{atan2} built-in function
+@cindex @code{atan2} function
This returns the arctangent of @code{@var{y} / @var{x}} in radians.
@item rand()
-@cindex @code{rand} built-in function
+@cindex @code{rand} function
+@cindex random numbers, @code{rand}/@code{srand} functions
This returns a random number. The values of @code{rand} are
uniformly distributed between zero and one.
The value is never zero and never one.@footnote{The C version of @code{rand}
@@ -11381,7 +11962,7 @@ an integer between zero and @code{n} @minus{} 1, inclusive.
The following example uses a similar function to produce random integers
between one and @var{n}. This program prints a new random number for
-each input record.
+each input record:
@example
# Function to roll a simulated die.
@@ -11395,7 +11976,7 @@ function roll(n) @{ return 1 + int(rand() * n) @}
@}
@end example
-@cindex seed for random numbers
+@cindex numbers, random
@cindex random numbers, seed of
@c MAWK uses a different seed each time.
@strong{Caution:} In most @command{awk} implementations, including @command{gawk},
@@ -11409,19 +11990,19 @@ the seed to a value that is different in each run. To do this,
use @code{srand}.
@item srand(@r{[}@var{x}@r{]})
-@cindex @code{srand} built-in function
+@cindex @code{srand} function
The function @code{srand} sets the starting point, or seed,
for generating random numbers to the value @var{x}.
Each seed value leads to a particular sequence of random
-numbers.@footnote{Computer generated random numbers really are not truly
-random. They are technically known as ``pseudo-random.'' This means
+numbers.@footnote{Computer-generated random numbers really are not truly
+random. They are technically known as ``pseudorandom.'' This means
that while the numbers in a sequence appear to be random, you can in
fact generate the same sequence of random numbers over and over again.}
Thus, if the seed is set to the same value a second time,
the same sequence of random numbers is produced again.
-Different @command{awk} implementations use different random number
+Different @command{awk} implementations use different random-number
generators internally. Don't expect the same @command{awk} program
to produce the same series of random numbers when executed by
different versions of @command{awk}.
@@ -11436,11 +12017,11 @@ sequences of random numbers.
@end table
@node String Functions, I/O Functions, Numeric Functions, Built-in
-@subsection String Manipulation Functions
+@subsection String-Manipulation Functions
The functions in this @value{SECTION} look at or change the text of one or more
strings.
-Optional parameters are enclosed in square brackets ([ and ]).
+Optional parameters are enclosed in square brackets ([ ]).
Those functions that are
specific to @command{gawk} are marked with a pound sign (@samp{#}):
@@ -11452,7 +12033,8 @@ specific to @command{gawk} are marked with a pound sign (@samp{#}):
@table @code
@item asort(@var{source} @r{[}, @var{dest}@r{]}) #
-@cindex @code{asort} built-in function
+@cindex arrays, elements, retrieving number of
+@cindex @code{asort} function (@command{gawk})
@code{asort} is a @command{gawk}-specific extension, returning the number of
elements in the array @var{source}. The contents of @var{source} are
sorted using @command{gawk}'s normal rules for comparing values, and the indices
@@ -11484,14 +12066,14 @@ a[2] = "de"
a[3] = "sac"
@end example
-@cindex differences between @command{gawk} and @command{awk}
The @code{asort} function is described in more detail in
@ref{Array Sorting, ,Sorting Array Values and Indices with @command{gawk}}.
@code{asort} is a @command{gawk} extension; it is not available
in compatibility mode (@pxref{Options, ,Command-Line Options}).
@item index(@var{in}, @var{find})
-@cindex @code{index} built-in function
+@cindex @code{index} function
+@cindex searching
This searches the string @var{in} for the first occurrence of the string
@var{find}, and returns the position in characters where that occurrence
begins in the string @var{in}. Consider the following example:
@@ -11506,7 +12088,7 @@ If @var{find} is not found, @code{index} returns zero.
(Remember that string indices in @command{awk} start at one.)
@item length(@r{[}@var{string}@r{]})
-@cindex @code{length} built-in function
+@cindex @code{length} function
This returns the number of characters in @var{string}. If
@var{string} is a number, the length of the digit string representing
that number is returned. For example, @code{length("abcde")} is 5. By
@@ -11516,10 +12098,9 @@ three characters.
If no argument is supplied, @code{length} returns the length of @code{$0}.
-@cindex historical features
-@cindex portability issues
-@cindex @command{awk} language, POSIX version
-@cindex POSIX @command{awk}
+@c @cindex historical features
+@cindex portability, @code{length} function
+@cindex POSIX @command{awk}, functions and, @code{length}
@strong{Note:}
In older versions of @command{awk}, the @code{length} function could
be called
@@ -11530,11 +12111,11 @@ version of the standard. Therefore, for programs to be maximally portable,
always supply the parentheses.
@item match(@var{string}, @var{regexp} @r{[}, @var{array}@r{]})
-@cindex @code{match} built-in function
+@cindex @code{match} function
The @code{match} function searches @var{string} for the
-longest leftmost substring matched by the regular expression,
+longest, leftmost substring matched by the regular expression,
@var{regexp}. It returns the character position, or @dfn{index},
-where that substring begins (one, if it starts at the beginning of
+at which that substring begins (one, if it starts at the beginning of
@var{string}). If no match is found, it returns zero.
The order of the first two arguments is backwards from most other string
@@ -11543,8 +12124,9 @@ functions that work with regular expressions, such as
for @code{match}, the order is the same as for the @samp{~} operator:
@samp{@var{string} ~ @var{regexp}}.
-@cindex @code{RSTART} variable
-@cindex @code{RLENGTH} variable
+@cindex @code{RSTART} variable, @code{match} function and
+@cindex @code{RLENGTH} variable, @code{match} function and
+@cindex @code{match} function, @code{RSTART}/@code{RLENGTH} variables
The @code{match} function sets the built-in variable @code{RSTART} to
the index. It also sets the built-in variable @code{RLENGTH} to the
length in characters of the matched substring. If no match is found,
@@ -11593,40 +12175,38 @@ Match of ru+n found at 12 in My program runs
Match of Melvin found at 1 in Melvin was here.
@end example
-@cindex differences between @command{gawk} and @command{awk}
-If @var{array} is present, it is cleared, and then the 0'th element
+@cindex differences in @command{awk} and @command{gawk}, @code{match} function
+If @var{array} is present, it is cleared, and then the 0th element
of @var{array} is set to the entire portion of @var{string}
matched by @var{regexp}. If @var{regexp} contains parentheses,
the integer-indexed elements of @var{array} are set to contain the
portion of @var{string} matching the corresponding parenthesized
-sub-expression.
+subexpression.
For example:
@example
$ echo foooobazbarrrrr |
-> gawk '@{ match($0, /(fo+).+(ba*r)/, arr)
+> gawk '@{ match($0, /(fo+).+(bar*)/, arr)
> print arr[1], arr[2] @}'
@print{} foooo barrrrr
@end example
-@cindex fatal errors
+@cindex troubleshooting, @code{match} function
The @var{array} argument to @code{match} is a
@command{gawk} extension. In compatibility mode
(@pxref{Options, ,Command-Line Options}),
using a third argument is a fatal error.
@item split(@var{string}, @var{array} @r{[}, @var{fieldsep}@r{]})
-@cindex @code{split} built-in function
-This function divides @var{string} into pieces separated by @var{fieldsep},
+@cindex @code{split} function
+This function divides @var{string} into pieces separated by @var{fieldsep}
and stores the pieces in @var{array}. The first piece is stored in
@code{@var{array}[1]}, the second piece in @code{@var{array}[2]}, and so
forth. The string value of the third argument, @var{fieldsep}, is
a regexp describing where to split @var{string} (much as @code{FS} can
be a regexp describing where to split input records). If
-the @var{fieldsep} is omitted, the value of @code{FS} is used.
+@var{fieldsep} is omitted, the value of @code{FS} is used.
@code{split} returns the number of elements created.
-If @var{string} does not match @var{fieldsep}, @var{array} is empty
-and @code{split} returns zero.
The @code{split} function splits strings into pieces in a
manner similar to the way input lines are split into fields. For example:
@@ -11636,6 +12216,7 @@ split("cul-de-sac", a, "-")
@end example
@noindent
+@cindex strings, splitting
splits the string @samp{cul-de-sac} into three fields using @samp{-} as the
separator. It sets the contents of the array @code{a} as follows:
@@ -11648,15 +12229,15 @@ a[3] = "sac"
@noindent
The value returned by this call to @code{split} is three.
-@cindex differences between @command{gawk} and @command{awk}
+@cindex differences in @command{awk} and @command{gawk}, @code{split} function
As with input field-splitting, when the value of @var{fieldsep} is
-@w{@code{" "}}, leading and trailing whitespace is ignored and the elements
+@w{@code{" "}}, leading and trailing whitespace is ignored, and the elements
are separated by runs of whitespace.
Also as with input field-splitting, if @var{fieldsep} is the null string, each
individual character in the string is split into its own array element.
(This is a @command{gawk}-specific extension.)
-@cindex dark corner
+@cindex dark corner, @code{split} function
Modern implementations of @command{awk}, including @command{gawk}, allow
the third argument to be a regexp constant (@code{/abc/}) as well as a
string.
@@ -11669,7 +12250,7 @@ If @var{string} does not match @var{fieldsep} at all, @var{array} has
one element only. The value of that element is the original @var{string}.
@item sprintf(@var{format}, @var{expression1}, @dots{})
-@cindex @code{sprintf} built-in function
+@cindex @code{sprintf} function
This returns (without printing) the string that @code{printf} would
have printed out with the same arguments
(@pxref{Printf, ,Using @code{printf} Statements for Fancier Printing}).
@@ -11682,7 +12263,8 @@ pival = sprintf("pi = %.2f (approx.)", 22/7)
@noindent
assigns the string @w{@code{"pi = 3.14 (approx.)"}} to the variable @code{pival}.
-@cindex @code{strtonum} built-in function
+@cindex differences in @command{awk} and @command{gawk}, @code{strtonum} function (@command{gawk})
+@cindex @code{strtonum} function (@command{gawk})
@item strtonum(@var{str}) #
Examines @var{str} and returns its numeric value. If @var{str}
begins with a leading @samp{0}, @code{strtonum} assumes that @var{str}
@@ -11700,17 +12282,17 @@ Using the @code{strtonum} function is @emph{not} the same as adding zero
to a string value; the automatic coercion of strings to numbers
works only for decimal data, not for octal or hexadecimal.@footnote{Unless
you use the @option{--non-decimal-data} option, which isn't recommended.
-@xref{Non-decimal Data, ,Allowing Non-Decimal Input Data}, for more information.}
+@xref{Nondecimal Data, ,Allowing Nondecimal Input Data}, for more information.}
-@cindex differences between @command{gawk} and @command{awk}
+@cindex differences in @command{awk} and @command{gawk}, @code{strtonum} function (@command{gawk})
@code{strtonum} is a @command{gawk} extension; it is not available
in compatibility mode (@pxref{Options, ,Command-Line Options}).
@item sub(@var{regexp}, @var{replacement} @r{[}, @var{target}@r{]})
-@cindex @code{sub} built-in function
+@cindex @code{sub} function
The @code{sub} function alters the value of @var{target}.
It searches this value, which is treated as a string, for the
-leftmost longest substring matched by the regular expression @var{regexp}.
+leftmost, longest substring matched by the regular expression @var{regexp}.
Then the entire string is
changed by replacing the matched text with @var{replacement}.
The modified string becomes the new value of @var{target}.
@@ -11758,7 +12340,7 @@ $ awk 'BEGIN @{
@end example
@noindent
-This shows how @samp{&} can represent a non-constant string and also
+This shows how @samp{&} can represent a nonconstant string and also
illustrates the ``leftmost, longest'' rule in regexp matching
(@pxref{Leftmost Longest, ,How Much Text Matches?}).
@@ -11766,15 +12348,15 @@ The effect of this special character (@samp{&}) can be turned off by putting a
backslash before it in the string. As usual, to insert one backslash in
the string, you must write two backslashes. Therefore, write @samp{\\&}
in a string constant to include a literal @samp{&} in the replacement.
-For example, following is shown how to replace the first @samp{|} on each line with
+For example, the following shows how to replace the first @samp{|} on each line with
an @samp{&}:
@example
@{ sub(/\|/, "\\&"); print @}
@end example
-@cindex @code{sub}, third argument of
-@cindex @code{gsub}, third argument of
+@cindex @code{sub} function, arguments of
+@cindex @code{gsub} function, arguments of
As mentioned, the third argument to @code{sub} must
be a variable, field or array reference.
Some versions of @command{awk} allow the third argument to
@@ -11789,9 +12371,9 @@ sub(/USA/, "United States", "the USA and Canada")
@end example
@noindent
-@cindex fatal errors
+@cindex troubleshooting, @code{gsub}/@code{sub} functions
For historical compatibility, @command{gawk} accepts erroneous code,
-such as in the previous example. However, using any other non-changeable
+such as in the previous example. However, using any other nonchangeable
object as the third parameter causes a fatal error and your program
will not run.
@@ -11799,9 +12381,9 @@ Finally, if the @var{regexp} is not a regexp constant, it is converted into a
string, and then the value of that string is treated as the regexp to match.
@item gsub(@var{regexp}, @var{replacement} @r{[}, @var{target}@r{]})
-@cindex @code{gsub} built-in function
+@cindex @code{gsub} function
This is similar to the @code{sub} function, except @code{gsub} replaces
-@emph{all} of the longest, leftmost, @emph{non-overlapping} matching
+@emph{all} of the longest, leftmost, @emph{nonoverlapping} matching
substrings it can find. The @samp{g} in @code{gsub} stands for
``global,'' which means replace everywhere. For example:
@@ -11820,7 +12402,7 @@ As in @code{sub}, the characters @samp{&} and @samp{\} are special,
and the third argument must be assignable.
@item gensub(@var{regexp}, @var{replacement}, @var{how} @r{[}, @var{target}@r{]}) #
-@cindex @code{gensub} built-in function
+@cindex @code{gensub} function (@command{gawk})
@code{gensub} is a general substitution function. Like @code{sub} and
@code{gsub}, it searches the target string @var{target} for matches of
the regular expression @var{regexp}. Unlike @code{sub} and @code{gsub},
@@ -11851,7 +12433,6 @@ $ gawk '
@noindent
As with @code{sub}, you must type two backslashes in order
to get one into the string.
-
In the replacement text, the sequence @samp{\0} represents the entire
matched text, as does the character @samp{&}.
@@ -11868,8 +12449,8 @@ In this case, @code{$0} is used as the default target string.
@code{gensub} returns the new string as its result, which is
passed directly to @code{print} for printing.
-@cindex automatic warnings
-@cindex warnings, automatic
+@c @cindex automatic warnings
+@c @cindex warnings, automatic
If the @var{how} argument is a string that does not begin with @samp{g} or
@samp{G}, or if it is a number that is less than or equal to zero, only one
substitution is performed. If @var{how} is zero, @command{gawk} issues
@@ -11878,16 +12459,15 @@ a warning message.
If @var{regexp} does not match @var{target}, @code{gensub}'s return value
is the original unchanged value of @var{target}.
-@cindex differences between @command{gawk} and @command{awk}
@code{gensub} is a @command{gawk} extension; it is not available
in compatibility mode (@pxref{Options, ,Command-Line Options}).
@item substr(@var{string}, @var{start} @r{[}, @var{length}@r{]})
-@cindex @code{substr} built-in function
+@cindex @code{substr} function
This returns a @var{length}-character-long substring of @var{string},
starting at character number @var{start}. The first character of a
string is character number one.@footnote{This is different from
-C and C++, where the first character is number zero.}
+C and C++, in which the first character is number zero.}
For example, @code{substr("washington", 5, 3)} returns @code{"ing"}.
If @var{length} is not present, this function returns the whole suffix of
@@ -11895,11 +12475,14 @@ If @var{length} is not present, this function returns the whole suffix of
@code{substr("washington", 5)} returns @code{"ington"}. The whole
suffix is also returned
if @var{length} is greater than the number of characters remaining
-in the string, counting from character number @var{start}.
+in the string, counting from character @var{start}.
-@cindex common mistakes
-@cindex mistakes, common
-@cindex errors, common
+If @var{start} is less than one or greater than the number of characters
+in the string, @code{substr} returns the null string.
+Similarly, if @var{length} is present but less than or equal to zero,
+the null string is returned.
+
+@cindex troubleshooting, @code{substr} function
The string returned by @code{substr} @emph{cannot} be
assigned. Thus, it is a mistake to attempt to change a portion of
a string, as shown in the following example:
@@ -11918,7 +12501,7 @@ of @code{sub} or @code{gsub}:
gsub(/xyz/, "pdq", substr($0, 5, 20)) # WRONG
@end example
-@cindex portability issues
+@cindex portability, @code{substr} function
(Some commercial versions of @command{awk} do in fact let you use
@code{substr} this way, but doing so is not portable.)
@@ -11931,30 +12514,34 @@ string = "abcdef"
string = substr(string, 1, 2) "CDE" substr(string, 6)
@end example
-@cindex case conversion
-@cindex conversion of case
+@cindex case sensitivity, converting case
+@cindex converting, case
@item tolower(@var{string})
-@cindex @code{tolower} built-in function
+@cindex @code{tolower} function
This returns a copy of @var{string}, with each uppercase character
in the string replaced with its corresponding lowercase character.
-Non-alphabetic characters are left unchanged. For example,
+Nonalphabetic characters are left unchanged. For example,
@code{tolower("MiXeD cAsE 123")} returns @code{"mixed case 123"}.
@item toupper(@var{string})
-@cindex @code{toupper} built-in function
+@cindex @code{toupper} function
This returns a copy of @var{string}, with each lowercase character
in the string replaced with its corresponding uppercase character.
-Non-alphabetic characters are left unchanged. For example,
+Nonalphabetic characters are left unchanged. For example,
@code{toupper("MiXeD cAsE 123")} returns @code{"MIXED CASE 123"}.
@end table
@node Gory Details, , String Functions, String Functions
@subsubsection More About @samp{\} and @samp{&} with @code{sub}, @code{gsub}, and @code{gensub}
-@cindex escape processing, @code{sub} et. al.
-@cindex @code{sub}, escape processing
-@cindex @code{gsub}, escape processing
-@cindex @code{gensub}, escape processing
+@cindex escape processing, @code{gsub}/@code{gensub}/@code{sub} functions
+@cindex @code{sub} function, escape processing
+@cindex @code{gsub} function, escape processing
+@cindex @code{gensub} function (@command{gawk}), escape processing
+@cindex @code{\} (backslash), @code{gsub}/@code{gensub}/@code{sub} functions and
+@cindex backslash (@code{\}), @code{gsub}/@code{gensub}/@code{sub} functions and
+@cindex @code{&} (ampersand), @code{gsub}/@code{gensub}/@code{sub} functions and
+@cindex ampersand (@code{&}), @code{gsub}/@code{gensub}/@code{sub} functions and
When using @code{sub}, @code{gsub}, or @code{gensub}, and trying to get literal
backslashes and ampersands into the replacement text, you need to remember
that there are several levels of @dfn{escape processing} going on.
@@ -12021,14 +12608,14 @@ through unchanged. To illustrate with a table:
This table shows both the lexical-level processing, where
an odd number of backslashes becomes an even number at the runtime level,
as well as the runtime processing done by @code{sub}.
-(For the sake of simplicity, the rest of the tables below only show the
+(For the sake of simplicity, the rest of the following tables only show the
case of even numbers of backslashes entered at the lexical level.)
The problem with the historical approach is that there is no way to get
a literal @samp{\} followed by the matched text.
-@cindex @command{awk} language, POSIX version
-@cindex POSIX @command{awk}
+@c @cindex @command{awk} language, POSIX version
+@cindex POSIX @command{awk}, functions and, @code{gsub}/@code{sub}
The 1992 POSIX standard attempted to fix this problem. The standard
says that @code{sub} and @code{gsub} look for either a @samp{\} or an @samp{&}
after the @samp{\}. If either one follows a @samp{\}, that character is
@@ -12136,7 +12723,7 @@ The rules for @code{gensub} are considerably simpler. At the runtime
level, whenever @command{gawk} sees a @samp{\}, if the following character
is a digit, then the text that matched the corresponding parenthesized
subexpression is placed in the generated output. Otherwise,
-no matter what the character after the @samp{\} is, it
+no matter what character follows the @samp{\}, it
appears in the generated text and the @samp{\} does not:
@tex
@@ -12177,8 +12764,13 @@ to do substitutions.
@c fakenode --- for prepinfo
@subheading Advanced Notes: Matching the Null String
-@cindex advanced notes
-@cindex matching, the null string
+@c last comma does NOT start tertiary
+@cindex advanced features, null strings, matching
+@cindex matching, null strings
+@cindex null strings, matching
+@c last comma in next two is part of tertiary
+@cindex @code{*} (asterisk), @code{*} operator, null strings, matching
+@cindex asterisk (@code{*}), @code{*} operator, null strings, matching
In @command{awk}, the @samp{*} operator can match the null string.
This is particularly important for the @code{sub}, @code{gsub},
@@ -12195,12 +12787,13 @@ Although this makes a certain amount of sense, it can be surprising.
@node I/O Functions, Time Functions, String Functions, Built-in
@subsection Input/Output Functions
-The following functions relate to Input/Output (I/O).
-Optional parameters are enclosed in square brackets ([ and ]):
+The following functions relate to input/output (I/O).
+Optional parameters are enclosed in square brackets ([ ]):
@table @code
@item close(@var{filename} @r{[}, @var{how}@r{]})
-@cindex @code{close} built-in function
+@cindex @code{close} function
+@cindex files, closing
Close the file @var{filename} for input or output. Alternatively, the
argument may be a shell command that was used for creating a coprocess, or
for redirecting to or from a pipe; then the coprocess or pipe is closed.
@@ -12208,7 +12801,7 @@ for redirecting to or from a pipe; then the coprocess or pipe is closed.
for more information.
When closing a coprocess, it is occasionally useful to first close
-one end of the two-way pipe, and then to close the other. This is done
+one end of the two-way pipe and then to close the other. This is done
by providing a second argument to @code{close}. This second argument
should be one of the two string values @code{"to"} or @code{"from"},
indicating which end of the pipe to close. Case in the string does
@@ -12217,18 +12810,16 @@ not matter.
which discusses this feature in more detail and gives an example.
@item fflush(@r{[}@var{filename}@r{]})
-@cindex @code{fflush} built-in function
-@cindex portability issues
-@cindex flushing buffers
-@cindex buffers, flushing
-@cindex buffering output
-@cindex output, buffering
+@cindex @code{fflush} function
Flush any buffered output associated with @var{filename}, which is either a
file opened for writing or a shell command for redirecting output to
a pipe or coprocess.
+@cindex portability, @code{fflush} function and
+@cindex buffers, flushing
+@cindex output, buffering
Many utility programs @dfn{buffer} their output; i.e., they save information
-to write to a disk file or terminal in memory, until there is enough
+to write to a disk file or terminal in memory until there is enough
for it to be worthwhile to send the data to the output device.
This is often more efficient than writing
every little bit of information as soon as it is ready. However, sometimes
@@ -12243,30 +12834,32 @@ version of @command{awk} in 1994; it is not part of the POSIX standard and is
not available if @option{--posix} has been specified on the
command line (@pxref{Options, ,Command-Line Options}).
+@cindex @command{gawk}, @code{fflush} function in
@command{gawk} extends the @code{fflush} function in two ways. The first
is to allow no argument at all. In this case, the buffer for the
standard output is flushed. The second is to allow the null string
(@w{@code{""}}) as the argument. In this case, the buffers for
@emph{all} open output files and pipes are flushed.
-@cindex automatic warnings
-@cindex warnings, automatic
+@c @cindex automatic warnings
+@c @cindex warnings, automatic
+@cindex troubleshooting, @code{fflush} function
@code{fflush} returns zero if the buffer is successfully flushed;
-otherwise it returns @minus{}1.
+otherwise, it returns @minus{}1.
In the case where all buffers are flushed, the return value is zero
only if all buffers were flushed successfully. Otherwise, it is
-@minus{}1, and @command{gawk} warns about the @var{filename} that had the problem.
+@minus{}1, and @command{gawk} warns about the problem @var{filename}.
@command{gawk} also issues a warning message if you attempt to flush
a file or pipe that was opened for reading (such as with @code{getline}),
or if @var{filename} is not an open file, pipe, or coprocess.
-In such a case, @code{fflush} returns @minus{}1 as well.
+In such a case, @code{fflush} returns @minus{}1, as well.
@item system(@var{command})
-@cindex @code{system} built-in function
-@cindex interaction, @command{awk} and other programs
-The @code{system} function allows the user to execute operating system
-commands and then return to the @command{awk} program. The @code{system}
+@cindex @code{system} function
+@cindex interacting with other programs
+Executes operating-system
+commands and then returns to the @command{awk} program. The @code{system}
function executes the command given by the string @var{command}.
It returns the status returned by the command that was executed as
its value.
@@ -12295,7 +12888,7 @@ close("/bin/sh")
@end example
@noindent
-@cindex fatal errors
+@cindex troubleshooting, @code{system} function
However, if your @command{awk}
program is interactive, @code{system} is useful for cranking up large
self-contained programs, such as a shell or an editor.
@@ -12304,15 +12897,12 @@ Some operating systems cannot implement the @code{system} function.
@end table
@c fakenode --- for prepinfo
-@subheading Advanced Notes: Interactive Versus Non-Interactive Buffering
-@cindex advanced notes
-@cindex buffering, interactive vs. non-interactive
-@cindex buffering, non-interactive vs. interactive
-@cindex interactive buffering vs. non-interactive
-@cindex non-interactive buffering vs. interactive
+@subheading Advanced Notes: Interactive Versus Noninteractive Buffering
+@cindex advanced features, buffering
+@cindex buffering, interactive vs. noninteractive
As a side point, buffering issues can be even more confusing, depending
-upon whether your program is @dfn{interactive}; i.e., communicating
+upon whether your program is @dfn{interactive}, i.e., communicating
with a user sitting at a keyboard.@footnote{A program is interactive
if the standard output is connected
to a terminal device.}
@@ -12320,7 +12910,7 @@ to a terminal device.}
@c Thanks to Walter.Mecky@dresdnerbank.de for this example, and for
@c motivating me to write this section.
Interactive programs generally @dfn{line buffer} their output; i.e., they
-write out every line. Non-interactive programs wait until they have
+write out every line. Noninteractive programs wait until they have
a full buffer, which may be many lines of output.
Here is an example of the difference:
@@ -12330,7 +12920,7 @@ $ awk '@{ print $1 + $2 @}'
@print{} 2
2 3
@print{} 5
-@kbd{Ctrl-d}
+@kbd{@value{CTL}-d}
@end example
@noindent
@@ -12341,21 +12931,20 @@ with this example:
$ awk '@{ print $1 + $2 @}' | cat
1 1
2 3
-@kbd{Ctrl-d}
+@kbd{@value{CTL}-d}
@print{} 2
@print{} 5
@end example
@noindent
-Here, no output is printed until after the @kbd{Ctrl-d} is typed, because
+Here, no output is printed until after the @kbd{@value{CTL}-d} is typed, because
it is all buffered and sent down the pipe to @command{cat} in one shot.
@c fakenode --- for prepinfo
@subheading Advanced Notes: Controlling Output Buffering with @code{system}
-@cindex advanced notes
-@cindex flushing buffers
+@cindex advanced features, buffering
@cindex buffers, flushing
-@cindex buffering output
+@cindex buffering, input/output
@cindex output, buffering
The @code{fflush} function provides explicit control over output buffering for
@@ -12406,40 +12995,51 @@ first print
second print
@end example
-If @command{awk} did not flush its buffers before calling @code{system}, the
-latter (undesirable) output is what you see.
+If @command{awk} did not flush its buffers before calling @code{system},
+you would see the latter (undesirable) output.
@node Time Functions, Bitwise Functions, I/O Functions, Built-in
@subsection Using @command{gawk}'s Timestamp Functions
+@c STARTOFRANGE tst
@cindex timestamps
-@cindex time of day
-A common use for @command{awk} programs is the processing of log files
+@c STARTOFRANGE logftst
+@cindex log files, timestamps in
+@c last comma does NOT start tertiary
+@c STARTOFRANGE filogtst
+@cindex files, log, timestamps in
+@c STARTOFRANGE gawtst
+@cindex @command{gawk}, timestamps
+@cindex POSIX @command{awk}, timestamps and
+@code{awk} programs are commonly used to process log files
containing timestamp information, indicating when a
particular log record was written. Many programs log their timestamp
in the form returned by the @code{time} system call, which is the
number of seconds since a particular epoch. On POSIX-compliant systems,
it is the number of seconds since
1970-01-01 00:00:00 UTC, not counting leap seconds.@footnote{@xref{Glossary},
-especially the entries for ``Epoch'' and ``UTC.''}
+especially the entries ``Epoch'' and ``UTC.''}
All known POSIX-compliant systems support timestamps from 0 through
@math{2^31 - 1}, which is sufficient to represent times through
2038-01-19 03:14:07 UTC. Many systems support a wider range of timestamps,
including negative timestamps that represent times before the
epoch.
+@cindex @command{date} utility, GNU
+@cindex time, retrieving
In order to make it easier to process such log files and to produce
useful reports, @command{gawk} provides the following functions for
working with timestamps. They are @command{gawk} extensions; they are
not specified in the POSIX standard, nor are they in any other known
version of @command{awk}.@footnote{The GNU @command{date} utility can
-also do many of the things described here. It's use may be preferable
+also do many of the things described here. Its use may be preferable
for simple time-related operations in shell scripts.}
-Optional parameters are enclosed in square brackets ([ and ]):
+Optional parameters are enclosed in square brackets ([ ]):
@table @code
@item systime()
-@cindex @code{systime} built-in function
+@cindex @code{systime} function (@command{gawk})
+@cindex timestamps
This function returns the current time as the number of seconds since
the system epoch. On POSIX systems, this is the number of seconds
since 1970-01-01 00:00:00 UTC, not counting leap seconds.
@@ -12447,7 +13047,7 @@ It may be a different number on
other systems.
@item mktime(@var{datespec})
-@cindex @code{mktime} built-in function
+@cindex @code{mktime} function (@command{gawk})
This function turns @var{datespec} into a timestamp in the same form
as is returned by @code{systime}. It is similar to the function of the
same name in ISO C. The argument, @var{datespec}, is a string of the form
@@ -12458,14 +13058,14 @@ from 1 to 31, the hour of the day from 0 to 23, the minute from 0 to
59, the second from 0 to 60,@footnote{Occasionally there are
minutes in a year with a leap second, which is why the
seconds can go up to 60.}
-and an optional daylight savings flag.
+and an optional daylight-savings flag.
The values of these numbers need not be within the ranges specified;
for example, an hour of @minus{}1 means 1 hour before midnight.
The origin-zero Gregorian calendar is assumed, with year 0 preceding
year 1 and year @minus{}1 preceding year 0.
The time is assumed to be in the local timezone.
-If the daylight savings flag is positive, the time is assumed to be
+If the daylight-savings flag is positive, the time is assumed to be
daylight savings time; if zero, the time is assumed to be standard
time; and if negative (the default), @code{mktime} attempts to determine
whether daylight savings time is in effect for the specified time.
@@ -12474,7 +13074,8 @@ If @var{datespec} does not contain enough elements or if the resulting time
is out of range, @code{mktime} returns @minus{}1.
@item strftime(@r{[}@var{format} @r{[}, @var{timestamp}@r{]]})
-@cindex @code{strftime} built-in function
+@c STARTOFRANGE strf
+@cindex @code{strftime} function (@command{gawk})
This function returns a string. It is similar to the function of the
same name in ISO C. The time specified by @var{timestamp} is used to
produce a string, based on the contents of the @var{format} string.
@@ -12492,9 +13093,9 @@ log file with the current time of day. In particular, it is easy to
determine how long ago a particular record was logged. It also allows
you to produce log records using the ``seconds since the epoch'' format.
-@cindex converting dates to timestamps
+@cindex converting, dates to timestamps
@cindex dates, converting to timestamps
-@cindex timestamps, converting from dates
+@cindex timestamps, converting dates to
The @code{mktime} function allows you to convert a textual representation
of a date and time into a timestamp. This makes it easy to do before/after
comparisons of dates and times, particularly when dealing with date and
@@ -12504,16 +13105,16 @@ The @code{strftime} function allows you to easily turn a timestamp
into human-readable information. It is similar in nature to the @code{sprintf}
function
(@pxref{String Functions, ,String Manipulation Functions}),
-in that it copies non-format specification characters verbatim to the
+in that it copies nonformat specification characters verbatim to the
returned string, while substituting date and time values for format
specifications in the @var{format} string.
+@cindex format specifiers, @code{strftime} function (@command{gawk})
@code{strftime} is guaranteed by the 1999 ISO C standard@footnote{As this
is a recent standard, not every system's @code{strftime} necessarily
supports all of the conversions listed here.}
to support the following date format specifications:
-@cindex format specifier, @code{strftime}
@table @code
@item %a
The locale's abbreviated weekday name.
@@ -12550,9 +13151,9 @@ This is the ISO 8601 date format.
@item %g
The year modulo 100 of the ISO week number, as a decimal number (00--99).
-For example, January 1, 1993, is in week 53 of 1992. Thus, the year
+For example, January 1, 1993 is in week 53 of 1992. Thus, the year
of its ISO week number is 1992, even though its year is 1993.
-Similarly, December 31, 1973, is in week 1 of 1974. Thus, the year
+Similarly, December 31, 1973 is in week 1 of 1974. Thus, the year
of its ISO week number is 1974, even though its year is 1973.
@item %G
@@ -12594,7 +13195,7 @@ Equivalent to specifying @samp{%H:%M}.
The second as a decimal number (00--60).
@item %t
-A tab character.
+A TAB character.
@item %T
Equivalent to specifying @samp{%H:%M:%S}.
@@ -12606,13 +13207,13 @@ The weekday as a decimal number (1--7). Monday is day one.
The week number of the year (the first Sunday as the first day of week one)
as a decimal number (00--53).
-@cindex ISO 8601
+@c @cindex ISO 8601
@item %V
The week number of the year (the first Monday as the first
day of week one) as a decimal number (01--53).
The method for determining the week number is as specified by ISO 8601.
(To wit: if the week containing January 1 has four or more days in the
-new year, then it is week one, otherwise it is week 53 of the previous year
+new year, then it is week one; otherwise it is week 53 of the previous year
and the next week is week one.)
@item %w
@@ -12636,8 +13237,8 @@ The year modulo 100 as a decimal number (00--99).
@item %Y
The full year as a decimal number (e.g., 1995).
-@cindex RFC 822
-@cindex RFC 1036
+@c @cindex RFC 822
+@c @cindex RFC 1036
@item %z
The timezone offset in a +HHMM format (e.g., the format necessary to
produce RFC 822/RFC 1036 date headers).
@@ -12648,7 +13249,7 @@ no time zone is determinable.
@item %Ec %EC %Ex %EX %Ey %EY %Od %Oe %OH
@itemx %OI %Om %OM %OS %Ou %OU %OV %Ow %OW %Oy
-These are ``alternate representations'' for the specifications
+``Alternate representations'' for the specifications
that use only the second letter (@samp{%c}, @samp{%C},
and so on).@footnote{If you don't understand any of this, don't worry about
it; these facilities are meant to make it easier to ``internationalize''
@@ -12666,9 +13267,9 @@ undefined.@footnote{This is because ISO C leaves the
behavior of the C version of @code{strftime} undefined and @command{gawk}
uses the system's version of @code{strftime} if it's there.
Typically, the conversion specifier either does not appear in the
-returned string or it appears literally.}
+returned string or appears literally.}
-@cindex locale, definition of
+@c @cindex locale, definition of
Informally, a @dfn{locale} is the geographic place in which a program
is meant to run. For example, a common way to abbreviate the date
September 4, 1991 in the United States is ``9/4/91.''
@@ -12689,11 +13290,11 @@ then the following additional format specifications are available:
@table @code
@item %k
The hour (24-hour clock) as a decimal number (0--23).
-Single digit numbers are padded with a space.
+Single-digit numbers are padded with a space.
@item %l
The hour (12-hour clock) as a decimal number (1--12).
-Single digit numbers are padded with a space.
+Single-digit numbers are padded with a space.
@item %N
The ``Emperor/Era'' name.
@@ -12709,15 +13310,18 @@ The time as a decimal timestamp in seconds since the epoch.
@item %v
The date in VMS format (e.g., @samp{20-JUN-1991}).
@end table
+@c ENDOFRANGE strf
Additionally, the alternate representations are recognized but their
normal representations are used.
+@cindex @code{date} utility, POSIX
+@cindex POSIX @command{awk}, @code{date} utility and
This example is an @command{awk} implementation of the POSIX
@command{date} utility. Normally, the @command{date} utility prints the
current date and time of day in a well-known format. However, if you
provide an argument to it that begins with a @samp{+}, @command{date}
-copies non-format specifier characters to the standard output and
+copies nonformat specifier characters to the standard output and
interprets the current time according to the format specifiers in
the string. For example:
@@ -12758,18 +13362,28 @@ gawk 'BEGIN @{
exit exitval
@}' "$@@"
@end example
+@c ENDOFRANGE tst
+@c ENDOFRANGE logftst
+@c ENDOFRANGE filogtst
+@c ENDOFRANGE gawtst
@node Bitwise Functions, I18N Functions, Time Functions, Built-in
-@subsection Using @command{gawk}'s Bit Manipulation Functions
-@cindex bitwise operations
+@subsection Bit-Manipulation Functions of @command{gawk}
+@c STARTOFRANGE bit
+@cindex bitwise, operations
+@c STARTOFRANGE and
+@cindex AND bitwise operation
+@c STARTOFRANGE oro
+@cindex OR bitwise operation
+@c STARTOFRANGE xor
+@cindex XOR bitwise operation
+@c STARTOFRANGE opbit
+@cindex operations, bitwise
@quotation
@i{I can explain it for you, but I can't understand it for you.}@*
Anonymous
@end quotation
-@cindex AND bitwise operation
-@cindex OR bitwise operation
-@cindex XOR bitwise operation
Many languages provide the ability to perform @dfn{bitwise} operations
on two integer numbers. In other words, the operation is performed on
each successive pair of bits in the operands.
@@ -12816,7 +13430,7 @@ Operands | 0 | 1 | 0 | 1 | 0 | 1
}}}
@end tex
-@cindex bitwise complement
+@cindex bitwise, complement
@cindex complement, bitwise
As you can see, the result of an AND operation is 1 only when @emph{both}
bits are 1.
@@ -12827,7 +13441,7 @@ The next operation is the @dfn{complement}; the complement of 1 is 0 and
the complement of 0 is 1. Thus, this operation ``flips'' all the bits
of a given value.
-@cindex bitwise shift
+@cindex bitwise, shift
@cindex left shift, bitwise
@cindex right shift, bitwise
@cindex shift, bitwise
@@ -12846,56 +13460,57 @@ bitwise operations just described. They are:
@ignore
@table @code
-@cindex @code{and} built-in function
+@cindex @code{and} function (@command{gawk})
@item and(@var{v1}, @var{v2})
Return the bitwise AND of the values provided by @var{v1} and @var{v2}.
-@cindex @code{or} built-in function
+@cindex @code{or} function (@command{gawk})
@item or(@var{v1}, @var{v2})
Return the bitwise OR of the values provided by @var{v1} and @var{v2}.
-@cindex @code{xor} built-in function
+@cindex @code{xor} function (@command{gawk})
@item xor(@var{v1}, @var{v2})
Return the bitwise XOR of the values provided by @var{v1} and @var{v2}.
-@cindex @code{compl} built-in function
+@cindex @code{compl} function (@command{gawk})
@item compl(@var{val})
Return the bitwise complement of @var{val}.
-@cindex @code{lshift} built-in function
+@cindex @code{lshift} function (@command{gawk})
@item lshift(@var{val}, @var{count})
Return the value of @var{val}, shifted left by @var{count} bits.
-@cindex @code{rshift} built-in function
+@cindex @code{rshift} function (@command{gawk})
@item rshift(@var{val}, @var{count})
Return the value of @var{val}, shifted right by @var{count} bits.
@end table
@end ignore
+@cindex @command{gawk}, bitwise operations in
@multitable {@code{rshift(@var{val}, @var{count})}} {Return the value of @var{val}, shifted right by @var{count} bits.}
-@cindex @code{and} built-in function
+@cindex @code{and} function (@command{gawk})
@item @code{and(@var{v1}, @var{v2})}
-@tab Return the bitwise AND of the values provided by @var{v1} and @var{v2}.
+@tab Returns the bitwise AND of the values provided by @var{v1} and @var{v2}.
-@cindex @code{or} built-in function
+@cindex @code{or} function (@command{gawk})
@item @code{or(@var{v1}, @var{v2})}
-@tab Return the bitwise OR of the values provided by @var{v1} and @var{v2}.
+@tab Returns the bitwise OR of the values provided by @var{v1} and @var{v2}.
-@cindex @code{xor} built-in function
+@cindex @code{xor} function (@command{gawk})
@item @code{xor(@var{v1}, @var{v2})}
-@tab Return the bitwise XOR of the values provided by @var{v1} and @var{v2}.
+@tab Returns the bitwise XOR of the values provided by @var{v1} and @var{v2}.
-@cindex @code{compl} built-in function
+@cindex @code{compl} function (@command{gawk})
@item @code{compl(@var{val})}
-@tab Return the bitwise complement of @var{val}.
+@tab Returns the bitwise complement of @var{val}.
-@cindex @code{lshift} built-in function
+@cindex @code{lshift} function (@command{gawk})
@item @code{lshift(@var{val}, @var{count})}
-@tab Return the value of @var{val}, shifted left by @var{count} bits.
+@tab Returns the value of @var{val}, shifted left by @var{count} bits.
-@cindex @code{rshift} built-in function
+@cindex @code{rshift} function (@command{gawk})
@item @code{rshift(@var{val}, @var{count})}
-@tab Return the value of @var{val}, shifted right by @var{count} bits.
+@tab Returns the value of @var{val}, shifted right by @var{count} bits.
@end multitable
For all of these functions, first the double-precision floating-point value is
@@ -12980,11 +13595,14 @@ $ gawk -f testbits.awk
@print{} rshift(0x99, 2) = 0x26 = 00100110
@end smallexample
+@cindex numbers, converting, to strings
+@cindex strings, converting, numbers to
+@cindex converting, numbers, to strings
The @code{bits2str} function turns a binary number into a string.
The number @code{1} represents a binary value where the rightmost bit
is set to 1. Using this mask,
the function repeatedly checks the rightmost bit.
-AND-ing the mask with the value indicates whether the
+ANDing the mask with the value indicates whether the
rightmost bit is 1 or not. If so, a @code{"1"} is concatenated onto the front
of the string.
Otherwise, a @code{"0"} is added.
@@ -12993,55 +13611,78 @@ until there are no more 1 bits.
If the initial value is zero it returns a simple @code{"0"}.
Otherwise, at the end, it pads the value with zeros to represent multiples
-of eight-bit quantities. This is typical in modern computers.
+of 8-bit quantities. This is typical in modern computers.
The main code in the @code{BEGIN} rule shows the difference between the
decimal and octal values for the same numbers
-(@pxref{Non-decimal-numbers, ,Octal and Hexadecimal Numbers}),
+(@pxref{Nondecimal-numbers, ,Octal and Hexadecimal Numbers}),
and then demonstrates the
results of the @code{compl}, @code{lshift}, and @code{rshift} functions.
+@c ENDOFRANGE bit
+@c ENDOFRANGE and
+@c ENDOFRANGE oro
+@c ENDOFRANGE xor
+@c ENDOFRANGE opbit
@node I18N Functions, , Bitwise Functions, Built-in
-@subsection Using @command{gawk}'s String Translation Functions
+@subsection Using @command{gawk}'s String-Translation Functions
+@cindex @command{gawk}, string-translation functions
+@cindex functions, string-translation
+@cindex internationalization
+@cindex @command{awk} programs, internationalizing
@command{gawk} provides facilities for internationalizing @command{awk} programs.
These include the functions described in the following list.
-The description here is purposely brief.
+The descriptions here are purposely brief.
@xref{Internationalization, ,Internationalization with @command{gawk}},
for the full story.
-Optional parameters are enclosed in square brackets ([ and ]):
+Optional parameters are enclosed in square brackets ([ ]):
@table @code
-@cindex @code{dcgettext} built-in function
+@cindex @code{dcgettext} function (@command{gawk})
@item dcgettext(@var{string} @r{[}, @var{domain} @r{[}, @var{category}@r{]]})
This function returns the translation of @var{string} in
text domain @var{domain} for locale category @var{category}.
The default value for @var{domain} is the current value of @code{TEXTDOMAIN}.
The default value for @var{category} is @code{"LC_MESSAGES"}.
-@cindex @code{bindtextdomain} built-in function
+@cindex @code{dcngettext} function (@command{gawk})
+@item dcngettext(@var{string1}, @var{string2}, @var{number} @r{[}, @var{domain} @r{[}, @var{category}@r{]]})
+This function returns the plural form used for @var{number} of the
+translation of @var{string1} and @var{string2} in text domain
+@var{domain} for locale category @var{category}. @var{string1} is the
+English singular variant of a message, and @var{string2} the English plural
+variant of the same message.
+The default value for @var{domain} is the current value of @code{TEXTDOMAIN}.
+The default value for @var{category} is @code{"LC_MESSAGES"}.
+
+@cindex @code{bindtextdomain} function (@command{gawk})
@item bindtextdomain(@var{directory} @r{[}, @var{domain}@r{]})
-This function allows you to specify the directory where
+This function allows you to specify the directory in which
@command{gawk} will look for message translation files, in case they
will not or cannot be placed in the ``standard'' locations
(e.g., during testing).
-It returns the directory where @var{domain} is ``bound.''
+It returns the directory in which @var{domain} is ``bound.''
The default @var{domain} is the value of @code{TEXTDOMAIN}.
If @var{directory} is the null string (@code{""}), then
@code{bindtextdomain} returns the current binding for the
given @var{domain}.
@end table
+@c ENDOFRANGE funcbi
+@c ENDOFRANGE bifunc
@node User-defined, , Built-in, Functions
@section User-Defined Functions
-@cindex user-defined functions
-@cindex function, user-defined
+@c STARTOFRANGE udfunc
+@cindex user-defined, functions
+@c STARTOFRANGE funcud
+@cindex functions, user-defined
Complicated @command{awk} programs can often be simplified by defining
your own functions. User-defined functions can be called just like
built-in ones (@pxref{Function Calls}), but it is up to you to define
-them; i.e., to tell @command{awk} what they should do.
+them, i.e., to tell @command{awk} what they should do.
@menu
* Definition Syntax:: How to write definitions and what they mean.
@@ -13054,9 +13695,9 @@ them; i.e., to tell @command{awk} what they should do.
@node Definition Syntax, Function Example, User-defined, User-defined
@subsection Function Definition Syntax
-@cindex defining functions
-@cindex function definition
+@c STARTOFRANGE fdef
+@cindex functions, defining
Definitions of functions can appear anywhere between the rules of an
@command{awk} program. Thus, the general form of an @command{awk} program is
extended to include sequences of rules @emph{and} user-defined function
@@ -13075,12 +13716,13 @@ function @var{name}(@var{parameter-list})
@}
@end example
-@cindex names, use of
-@cindex namespace issues in @command{awk}
+@cindex names, functions
+@cindex functions, names of
+@cindex namespace issues, functions
@noindent
@var{name} is the name of the function to define. A valid function
name is like a valid variable name: a sequence of letters, digits, and
-underscores, that doesn't start with a digit.
+underscores that doesn't start with a digit.
Within a single @command{awk} program, any particular name can only be
used as a variable, array, or function.
@@ -13110,16 +13752,15 @@ arguments on some occasions and local variables on others. Another
way to think of this is that omitted arguments default to the
null string.
-@cindex conventions, programming
-@cindex programming conventions
+@cindex programming conventions, functions, writing
Usually when you write a function, you know how many names you intend to
use for arguments and how many you intend to use as local variables. It is
conventional to place some extra space between the arguments and
the local variables, in order to document how your function is supposed to be used.
-@cindex variable shadowing
+@cindex variables, shadowing
During execution of the function body, the arguments and local variable
-values hide or @dfn{shadow} any variables of the same names used in the
+values hide, or @dfn{shadow}, any variables of the same names used in the
rest of the program. The shadowed variables are not accessible in the
function definition, because there is no way to name them while their
names have been taken away for the local variables. All other variables
@@ -13130,15 +13771,16 @@ The arguments and local variables last only as long as the function body
is executing. Once the body finishes, you can once again access the
variables that were shadowed while the function was running.
-@cindex recursive function
-@cindex function, recursive
+@cindex recursive functions
+@cindex functions, recursive
The function body can contain expressions that call functions. They
can even call this function, either directly or by way of another
function. When this happens, we say the function is @dfn{recursive}.
The act of a function calling itself is called @dfn{recursion}.
-@cindex @command{awk} language, POSIX version
-@cindex POSIX @command{awk}
+@c @cindex @command{awk} language, POSIX version
+@c @cindex POSIX @command{awk}
+@cindex POSIX @command{awk}, @code{function} keyword in
In many @command{awk} implementations, including @command{gawk},
the keyword @code{function} may be
abbreviated @code{func}. However, POSIX only specifies the use of
@@ -13160,7 +13802,8 @@ syntactically valid, because functions may be used before they are defined
in @command{awk} programs.)
@c NEXT ED: This won't actually run, since foo() is undefined ...
-@cindex portability issues
+@c last comma does NOT start tertiary
+@cindex portability, functions, defining
To ensure that your @command{awk} programs are portable, always use the
keyword @code{function} when defining a function.
@@ -13221,14 +13864,15 @@ Instead of having
to repeat this loop everywhere that you need to clear out
an array, your program can just call @code{delarray}.
(This guarantees portability. The use of @samp{delete @var{array}} to delete
-the contents of an entire array is a non-standard extension.)
+the contents of an entire array is a nonstandard extension.)
The following is an example of a recursive function. It takes a string
as an input parameter and returns the string in backwards order.
Recursive functions must always have a test that stops the recursion.
In this case, the recursion terminates when the starting position
-is zero; i.e., when there are no more characters left in the string.
+is zero, i.e., when there are no more characters left in the string.
+@cindex @code{rev} user-defined function
@example
function rev(str, start)
@{
@@ -13254,6 +13898,7 @@ The following example uses the built-in @code{strftime} function
(@pxref{Time Functions, ,Using @command{gawk}'s Timestamp Functions})
to create an @command{awk} version of @code{ctime}:
+@cindex @code{ctime} user-defined function
@c FIXME: One day, change %d to %e, when C 99 is common.
@example
@c file eg/lib/ctime.awk
@@ -13270,12 +13915,13 @@ function ctime(ts, format)
@}
@c endfile
@end example
+@c ENDOFRANGE fdef
@node Function Caveats, Return Statement, Function Example, User-defined
@subsection Calling User-Defined Functions
-@cindex calling a function
-@cindex function call
+@c STARTOFRANGE fudc
+@cindex functions, user-defined, calling
@dfn{Calling a function} means causing the function to run and do its job.
A function call is an expression and its value is the value returned by
the function.
@@ -13328,7 +13974,7 @@ function myfunc(str)
@end example
@noindent
-to change its first argument variable @code{str}, it @emph{does not}
+to change its first argument variable @code{str}, it does @emph{not}
change the value of @code{foo} in the caller. The role of @code{foo} in
calling @code{myfunc} ended when its value (@code{"bar"}) was computed.
If @code{str} also exists outside of @code{myfunc}, the function body
@@ -13336,6 +13982,8 @@ cannot alter this outer value, because it is shadowed during the
execution of @code{myfunc} and cannot be seen or changed from there.
@cindex call by reference
+@cindex arrays, as parameters to functions
+@cindex functions, arrays as parameters to
However, when arrays are the parameters to functions, they are @emph{not}
copied. Instead, the array itself is made available for direct manipulation
by the function. This is usually called @dfn{call by reference}.
@@ -13361,7 +14009,7 @@ BEGIN @{
@end example
@noindent
-This program prints @samp{a[1] = 1, a[2] = two, a[3] = 3}, because
+prints @samp{a[1] = 1, a[2] = two, a[3] = 3}, because
@code{changeit} stores @code{"two"} in the second element of @code{a}.
@cindex undefined functions
@@ -13383,24 +14031,26 @@ function bar() @{ @dots{} @}
@noindent
Because the @samp{if} statement will never be true, it is not really a
-problem that @code{foo} has not been defined. Usually though, it is a
+problem that @code{foo} has not been defined. Usually, though, it is a
problem if a program calls an undefined function.
-@cindex lint checks
+@cindex lint checking, undefined functions
If @option{--lint} is specified
(@pxref{Options, ,Command-Line Options}),
@command{gawk} reports calls to undefined functions.
-@cindex portability issues
+@cindex portability, @code{next} statement in user-defined functions
Some @command{awk} implementations generate a runtime
error if you use the @code{next} statement
(@pxref{Next Statement, , The @code{next} Statement})
inside a user-defined function.
@command{gawk} does not have this limitation.
+@c ENDOFRANGE fudc
@node Return Statement, Dynamic Typing, Function Caveats, User-defined
@subsection The @code{return} Statement
-@cindex @code{return} statement
+@c comma does NOT start a secondary
+@cindex @code{return} statement, user-defined functions
The body of a user-defined function can contain a @code{return} statement.
This statement returns control to the calling part of the @command{awk} program. It
@@ -13439,16 +14089,15 @@ function maxelt(vec, i, ret)
@}
@end example
-@cindex conventions, programming
-@cindex programming conventions
+@cindex programming conventions, function parameters
@noindent
You call @code{maxelt} with one argument, which is an array name. The local
variables @code{i} and @code{ret} are not intended to be arguments;
-while there is nothing to stop you from passing two or three arguments
+while there is nothing to stop you from passing more than one argument
to @code{maxelt}, the results would be strange. The extra space before
@code{i} in the function parameter list indicates that @code{i} and
-@code{ret} are not supposed to be arguments. This is a convention that
-you should follow when you define functions.
+@code{ret} are not supposed to be arguments.
+You should follow this convention when defining functions.
The following program uses the @code{maxelt} function. It loads an
array, calls @code{maxelt}, and then reports the maximum number in that
@@ -13490,7 +14139,7 @@ the program reports (predictably) that @code{99385} is the largest number
in the array.
@node Dynamic Typing, , Return Statement, User-defined
-@subsection Functions and Their Effect on Variable Typing
+@subsection Functions and Their Effects on Variable Typing
@command{awk} is a very fluid language.
It is possible that @command{awk} can't tell if an identifier
@@ -13514,19 +14163,24 @@ BEGIN @{
Usually, such things aren't a big issue, but it's worth
being aware of them.
+@c ENDOFRANGE udfunc
+@c ENDOFRANGE funcud
@node Internationalization, Advanced Features, Functions, Top
@chapter Internationalization with @command{gawk}
Once upon a time, computer makers
-wrote software that only worked in English.
+wrote software that worked only in English.
Eventually, hardware and software vendors noticed that if their
systems worked in the native languages of non-English-speaking
countries, they were able to sell more systems.
As a result, internationalization and localization
of programs and software systems became a common practice.
-@cindex internationalization features in @command{gawk}
+@c STARTOFRANGE inloc
+@cindex internationalization, localization
+@cindex @command{gawk}, internationalization and, See internationalization
+@cindex internationalization, localization, @command{gawk} and
Until recently, the ability to provide internationalization
was largely restricted to programs written in C and C++.
This @value{CHAPTER} describes the underlying library @command{gawk}
@@ -13551,10 +14205,12 @@ a requirement.
@section Internationalization and Localization
@cindex internationalization
+@c comma is part of see
+@cindex localization, See internationalization, localization
@cindex localization
@dfn{Internationalization} means writing (or modifying) a program once,
in such a way that it can use multiple languages without requiring
-further source code changes.
+further source-code changes.
@dfn{Localization} means providing the data necessary for an
internationalized program to work in a particular language.
Most typically, these terms refer to features such as the language
@@ -13565,8 +14221,9 @@ monetary values are printed and read.
@node Explaining gettext, Programmer i18n, I18N and L10N, Internationalization
@section GNU @code{gettext}
-@cindex @code{gettext}, how it works
@cindex internationalizing a program
+@c STARTOFRANGE gettex
+@cindex @code{gettext} library
The facilities in GNU @code{gettext} focus on messages; strings printed
by a program, either directly or via formatting with @code{printf} or
@code{sprintf}.@footnote{For some operating systems, the @command{gawk}
@@ -13574,8 +14231,9 @@ port doesn't support GNU @code{gettext}. This applies most notably to
the PC operating systems. As such, these features are not available
if you are using one of those operating systems. Sorry.}
+@cindex portability, @code{gettext} library and
When using GNU @code{gettext}, each application has its own
-@dfn{text domain}. This is a unique name such as @samp{kpilot} or @samp{gawk},
+@dfn{text domain}. This is a unique name, such as @samp{kpilot} or @samp{gawk},
that identifies the application.
A complete application may have multiple components---programs written
in C or C++, as well as scripts written in @command{sh} or @command{awk}.
@@ -13595,7 +14253,7 @@ A table with strings of option names is not (e.g., @command{gawk}'s
@option{--profile} option should remain the same, no matter what the local
language).
-@cindex @code{textdomain} C library function
+@cindex @code{textdomain} function (C library)
@item
The programmer indicates the application's text domain
(@code{"guide"}) to the @code{gettext} library,
@@ -13603,18 +14261,24 @@ by calling the @code{textdomain} function.
@item
Messages from the application are extracted from the source code and
-collected into a Portable Object file (@file{guide.po}),
+collected into a portable object file (@file{guide.po}),
which lists the strings and their translations.
The translations are initially empty.
The original (usually English) messages serve as the key for
lookup of the translations.
-@cindex portable object files (@code{gettext})
+@cindex @code{.po} files
+@cindex files, @code{.po}
+@cindex portable object files
+@cindex files, portable object
@item
For each language with a translator, @file{guide.po}
is copied and translations are created and shipped with the application.
-@cindex message object files (@code{gettext})
+@cindex @code{.mo} files
+@cindex files, @code{.mo}
+@cindex message object files
+@cindex files, message object
@item
Each language's @file{.po} file is converted into a binary
message object (@file{.mo}) file.
@@ -13626,12 +14290,16 @@ at runtime.
When @command{guide} is built and installed, the binary translation files
are installed in a standard place.
-@cindex @code{bindtextdomain} C library function
+@cindex @code{bindtextdomain} function (C library)
@item
For testing and development, it is possible to tell @code{gettext}
to use @file{.mo} files in a different directory than the standard
one by using the @code{bindtextdomain} function.
+@cindex @code{.mo} files, specifying directory of
+@cindex files, @code{.mo}, specifying directory of
+@cindex message object files, specifying directory of
+@cindex files, message object, specifying directory of
@item
At runtime, @command{guide} looks up each string via a call
to @code{gettext}. The returned string is the translated string
@@ -13644,7 +14312,7 @@ having to switch the application's default text domain back
and forth.
@end enumerate
-@cindex @code{gettext} C library function
+@cindex @code{gettext} function (C library)
In C (or C++), the string marking and dynamic translation lookup
are accomplished by wrapping each string in a call to @code{gettext}:
@@ -13655,7 +14323,8 @@ printf(gettext("Don't Panic!\n"));
The tools that extract messages from source code pull out all
strings enclosed in calls to @code{gettext}.
-@cindex @code{_} C macro (@code{gettext})
+@cindex @code{_} (underscore), @code{_} C macro
+@cindex underscore (@code{_}), @code{_} C macro
The GNU @code{gettext} developers, recognizing that typing
@samp{gettext} over and over again is both painful and ugly to look
at, use the macro @samp{_} (an underscore) to make things easier:
@@ -13668,6 +14337,8 @@ at, use the macro @samp{_} (an underscore) to make things easier:
printf(_("Don't Panic!\n"));
@end example
+@cindex internationalization, localization, locale categories
+@cindex @code{gettext} library, locale categories
@cindex locale categories
@noindent
This reduces the typing overhead to just three extra characters per string
@@ -13683,20 +14354,23 @@ Text messages. This is the default category for @code{gettext}
operations, but it is possible to supply a different one explicitly,
if necessary. (It is almost never necessary to supply a different category.)
+@cindex sorting characters in different languages
@cindex @code{LC_COLLATE} locale category
@item LC_COLLATE
-Text collation information; i.e., how different characters
+Text-collation information; i.e., how different characters
and/or groups of characters sort in a given language.
@cindex @code{LC_CTYPE} locale category
@item LC_CTYPE
-Character type information (alphabetic, digit, upper- or lowercase, and
+Character-type information (alphabetic, digit, upper- or lowercase, and
so on).
This information is accessed via the
POSIX character classes in regular expressions,
such as @code{/[[:alnum:]]/}
(@pxref{Regexp Operators, ,Regular Expression Operators}).
+@cindex monetary information, localization
+@cindex currency symbols, localization
@cindex @code{LC_MONETARY} locale category
@item LC_MONETARY
Monetary information, such as the currency symbol, and whether the
@@ -13708,25 +14382,31 @@ Numeric information, such as which characters to use for the decimal
point and the thousands separator.@footnote{Americans
use a comma every three decimal places and a period for the decimal
point, while many Europeans do exactly the opposite:
-@code{1,234.56} vs.@: @code{1.234,56}.}
+@code{1,234.56} versus @code{1.234,56}.}
@cindex @code{LC_RESPONSE} locale category
@item LC_RESPONSE
Response information, such as how ``yes'' and ``no'' appear in the
local language, and possibly other information as well.
+@cindex time, localization and
+@c last comma does NOT start a tertiary
+@cindex dates, information related to, localization
@cindex @code{LC_TIME} locale category
@item LC_TIME
-Time and date related information, such as 12- or 24-hour clock, month printed
+Time- and date-related information, such as 12- or 24-hour clock, month printed
before or after day in a date, local month abbreviations, and so on.
@cindex @code{LC_ALL} locale category
@item LC_ALL
All of the above. (Not too useful in the context of @code{gettext}.)
@end table
+@c ENDOFRANGE gettex
@node Programmer i18n, Translator i18n, Explaining gettext, Internationalization
@section Internationalizing @command{awk} Programs
+@c STARTOFRANGE inap
+@cindex @command{awk} programs, internationalizing
@command{gawk} provides the following variables and functions for
internationalization:
@@ -13738,14 +14418,14 @@ This variable indicates the application's text domain.
For compatibility with GNU @code{gettext}, the default
value is @code{"messages"}.
-@cindex internationalization, marked strings
-@cindex marked strings for internationalization
+@cindex internationalization, localization, marked strings
+@cindex strings, for localization
@item _"your message here"
String constants marked with a leading underscore
are candidates for translation at runtime.
String constants without a leading underscore are not translated.
-@cindex @code{dcgettext} built-in function
+@cindex @code{dcgettext} function (@command{gawk})
@item dcgettext(@var{string} @r{[}, @var{domain} @r{[}, @var{category}@r{]]})
This built-in function returns the translation of @var{string} in
text domain @var{domain} for locale category @var{category}.
@@ -13769,13 +14449,29 @@ the C version. The @command{awk} version's order was
chosen to be simple and to allow for reasonable @command{awk}-style
default arguments.
-@cindex @code{bindtextdomain} built-in function
+@cindex @code{dcngettext} function (@command{gawk})
+@item dcngettext(@var{string1}, @var{string2}, @var{number} @r{[}, @var{domain} @r{[}, @var{category}@r{]]})
+This built-in function returns the plural form used for @var{number} of the
+translation of @var{string1} and @var{string2} in text domain
+@var{domain} for locale category @var{category}. @var{string1} is the
+English singular variant of a message, and @var{string2} the English plural
+variant of the same message.
+The default value for @var{domain} is the current value of @code{TEXTDOMAIN}.
+The default value for @var{category} is @code{"LC_MESSAGES"}.
+
+The same remarks as for the @code{dcgettext} function apply.
+
+@cindex @code{.mo} files, specifying directory of
+@cindex files, @code{.mo}, specifying directory of
+@cindex message object files, specifying directory of
+@cindex files, message object, specifying directory of
+@cindex @code{bindtextdomain} function (@command{gawk})
@item bindtextdomain(@var{directory} @r{[}, @var{domain}@r{]})
-This built-in function allows you to specify the directory where
+This built-in function allows you to specify the directory in which
@code{gettext} looks for @file{.mo} files, in case they
will not or cannot be placed in the standard locations
(e.g., during testing).
-It returns the directory where @var{domain} is ``bound.''
+It returns the directory in which @var{domain} is ``bound.''
The default @var{domain} is the value of @code{TEXTDOMAIN}.
If @var{directory} is the null string (@code{""}), then
@@ -13794,6 +14490,8 @@ the previous @value{SECTION},
like so:
@enumerate
+@cindex @code{BEGIN} pattern, @code{TEXTDOMAIN} variable and
+@cindex @code{TEXTDOMAIN} variable, @code{BEGIN} pattern and
@item
Set the variable @code{TEXTDOMAIN} to the text domain of
your program. This is best done in a @code{BEGIN} rule
@@ -13808,6 +14506,8 @@ BEGIN @{
@}
@end example
+@cindex @code{_} (underscore), translatable string
+@cindex underscore (@code{_}), translatable string
@item
Mark all translatable strings with a leading underscore (@samp{_})
character. It @emph{must} be adjacent to the opening
@@ -13822,7 +14522,7 @@ printf(_"Number of users is %d\n", nusers)
@item
If you are creating strings dynamically, you can
still translate them, using the @code{dcgettext}
-built-in function.
+built-in function:
@example
message = nusers " users logged in"
@@ -13834,6 +14534,7 @@ Here, the call to @code{dcgettext} supplies a different
text domain (@code{"adminprog"}) in which to find the
message, but it uses the default @code{"LC_MESSAGES"} category.
+@cindex @code{LC_MESSAGES} locale category, @code{bindtextdomain} function (@command{gawk})
@item
During development, you might want to put the @file{.mo}
file in a private directory for testing. This is done
@@ -13855,12 +14556,16 @@ BEGIN @{
@end enumerate
@xref{I18N Example, ,A Simple Internationalization Example},
-for an example program showing the steps necessary to create
+for an example program showing the steps to create
and use translations from @command{awk}.
@node Translator i18n, I18N Example, Programmer i18n, Internationalization
@section Translating @command{awk} Programs
+@cindex @code{.po} files
+@cindex files, @code{.po}
+@cindex portable object files
+@cindex files, portable object
Once a program's translatable strings have been marked, they must
be extracted to create the initial @file{.po} file.
As part of translation, it is often helpful to rearrange the order
@@ -13880,12 +14585,16 @@ is covered.
@node String Extraction, Printf Ordering, Translator i18n, Translator i18n
@subsection Extracting Marked Strings
+@cindex strings, extracting
+@c comma does NOT start secondary
+@cindex marked strings, extracting
+@cindex @code{--gen-po} option
+@cindex command-line options, string extraction
@cindex string extraction (internationalization)
@cindex marked string extraction (internationalization)
@cindex extraction, of marked strings (internationalization)
@cindex @code{--gen-po} option
-@cindex command-line option, @code{--gen-po}
Once your @command{awk} program is working, and all the strings have
been marked and you've set (and perhaps bound) the text domain,
it is time to produce translations.
@@ -13901,10 +14610,10 @@ When run with @option{--gen-po}, @command{gawk} does not execute your
program. Instead, it parses it as usual and prints all marked strings
to standard output in the format of a GNU @code{gettext} Portable Object
file. Also included in the output are any constant strings that
-appear as the first argument to @code{dcgettext}.@footnote{Eventually,
-the @command{xgettext} utility that comes with GNU @code{gettext} will be
-taught to automatically run @samp{gawk --gen-po} for @file{.awk} files,
-freeing the translator from having to do it manually.}
+appear as the first argument to @code{dcgettext} or as the first and
+second argument to @code{dcngettext}.@footnote{Starting with @code{gettext}
+version 0.11.1, the @command{xgettext} utility that comes with GNU
+@code{gettext} can handle @file{.awk} files.}
@xref{I18N Example, ,A Simple Internationalization Example},
for the full list of steps to go through to create and test
translations for @command{guide}.
@@ -13912,8 +14621,9 @@ translations for @command{guide}.
@node Printf Ordering, I18N Portability, String Extraction, Translator i18n
@subsection Rearranging @code{printf} Arguments
-@cindex @code{printf}, positional specifier
-@cindex positional specifier, @code{printf}
+@cindex @code{printf} statement, positional specifiers
+@c comma does NOT start secondary
+@cindex positional specifiers, @code{printf} statement
Format strings for @code{printf} and @code{sprintf}
(@pxref{Printf, ,Using @code{printf} Statements for Fancier Printing})
present a special problem for translation.
@@ -13949,7 +14659,7 @@ For example:
Here, the positional specifier consists of an integer count, which indicates which
argument to use, and a @samp{$}. Counts are one-based, and the
format string itself is @emph{not} included. Thus, in the following
-example, @samp{string} is the first argument and @samp{length(string)} is the second.
+example, @samp{string} is the first argument and @samp{length(string)} is the second:
@example
$ gawk 'BEGIN @{
@@ -13978,11 +14688,12 @@ $ gawk 'BEGIN @{
@noindent
@strong{Note:} When using @samp{*} with a positional specifier, the @samp{*}
comes first, then the integer position, and then the @samp{$}.
-This is somewhat counter-intutive.
+This is somewhat counterintutive.
-@cindex @code{printf}, mixing positional specifiers with regular formats
-@cindex positional specifiers, mixing with regular formats (@code{printf})
-@cindex format specifiers, mixing regular with positional specifiers (@code{printf})
+@cindex @code{printf} statement, positional specifiers, mixing with regular formats
+@c first comma does is part of primary
+@cindex positional specifiers, @code{printf} statement, mixing with regular formats
+@cindex format specifiers, mixing regular with positional specifiers
@command{gawk} does not allow you to mix regular format specifiers
and those with positional specifiers in the same string:
@@ -14004,9 +14715,8 @@ is first written.
@node I18N Portability, , Printf Ordering, Translator i18n
@subsection @command{awk} Portability Issues
-@cindex portability issues
-@cindex portability issues, internationalization of @command{awk} programs
-@cindex internationalization of @command{awk} programs, portability issues
+@cindex portability, internationalization and
+@cindex internationalization, localization, portability and
@command{gawk}'s internationalization features were purposely chosen to
have as little impact as possible on the portability of @command{awk}
programs that use them to other versions of @command{awk}.
@@ -14024,9 +14734,10 @@ BEGIN @{
@noindent
As written, it won't work on other versions of @command{awk}.
However, it is actually almost portable, requiring very little
-change.
+change:
@itemize @bullet
+@cindex @code{TEXTDOMAIN} variable, portability and
@item
Assignments to @code{TEXTDOMAIN} won't have any effect,
since @code{TEXTDOMAIN} is not special in other @command{awk} implementations.
@@ -14040,13 +14751,14 @@ the null string (@code{""}) as its value, leaving the original string constant a
the result.
@item
-By defining ``dummy'' functions to replace @code{dcgettext}
+By defining ``dummy'' functions to replace @code{dcgettext}, @code{dcngettext}
and @code{bindtextdomain}, the @command{awk} program can be made to run, but
all the messages are output in the original language.
For example:
-@cindex @code{bindtextdomain} user-defined function
-@cindex @code{dcgettext} user-defined function
+@cindex @code{bindtextdomain} function (@command{gawk}), portability and
+@cindex @code{dcgettext} function (@command{gawk}), portability and
+@cindex @code{dcngettext} function (@command{gawk}), portability and
@example
@c file eg/lib/libintl.awk
function bindtextdomain(dir, domain)
@@ -14058,6 +14770,11 @@ function dcgettext(string, domain, category)
@{
return string
@}
+
+function dcngettext(string1, string2, number, domain, category)
+@{
+ return (number == 1 ? string1 : string2)
+@}
@c endfile
@end example
@@ -14075,6 +14792,7 @@ However, since the positional specifications are primarily for use in
@emph{translated} format strings, and since non-GNU @command{awk}s never
retrieve the translated string, this should not be a problem in practice.
@end itemize
+@c ENDOFRANGE inap
@node I18N Example, Gawk I18N, Translator i18n, Internationalization
@section A Simple Internationalization Example
@@ -14165,6 +14883,14 @@ layout:
$ mkdir en_US en_US/LC_MESSAGES
@end example
+@cindex @code{.po} files, converting to @code{.mo}
+@cindex files, @code{.po}, converting to @code{.mo}
+@cindex @code{.mo} files, converting from @code{.po}
+@cindex files, @code{.mo}, converting from @code{.po}
+@cindex portable object files, converting to message object files
+@cindex files, portable object, converting to message object files
+@cindex message object files, converting from portable object files
+@cindex files, message object, converting from portable object files
@cindex @command{msgfmt} utility
The @command{msgfmt} utility does the conversion from human-readable
@file{.po} file to machine-readable @file{.mo} file.
@@ -14186,7 +14912,7 @@ $ gawk -f guide.awk
@print{} Pardon me, Zaphod who?
@end example
-If the two replacement functions for @code{dcgettext}
+If the three replacement functions for @code{dcgettext}, @code{dcngettext}
and @code{bindtextdomain}
(@pxref{I18N Portability, ,@command{awk} Portability Issues})
are in a file named @file{libintl.awk},
@@ -14215,7 +14941,7 @@ complete detail in
@cite{GNU gettext tools}.)
@end ifnotinfo
As of this writing, the latest version of GNU @code{gettext} is
-@uref{ftp://gnudist.gnu.org/gnu/gettext/gettext-0.10.37.tar.gz, @value{PVERSION} 0.10.37}.
+@uref{ftp://ftp.gnu.org/gnu/gettext/gettext-0.11.1.tar.gz, @value{PVERSION} 0.11.1}.
If a translation of @command{gawk}'s messages exists,
then @command{gawk} produces usage messages, warnings,
@@ -14228,11 +14954,15 @@ configure @command{gawk} with the @option{--with-included-gettext} option
before compiling and installing it.
@xref{Additional Configuration Options},
for more information.
+@c ENDOFRANGE inloc
@node Advanced Features, Invoking Gawk, Internationalization, Top
@chapter Advanced Features of @command{gawk}
-@cindex advanced features
-@cindex features, advanced
+@cindex advanced features, network connections, See Also networks, connections
+@c STARTOFRANGE gawadv
+@cindex @command{gawk}, features, advanced
+@c STARTOFRANGE advgaw
+@cindex advanced features, @command{gawk}
@ignore
Contributed by: Peter Langston <pud!psl@bellcore.bellcore.com>
@@ -14251,7 +14981,7 @@ This @value{CHAPTER} discusses advanced features in @command{gawk}.
It's a bit of a ``grab bag'' of items that are otherwise unrelated
to each other.
First, a command-line option allows @command{gawk} to recognize
-non-decimal numbers in input data, not just in @command{awk}
+nondecimal numbers in input data, not just in @command{awk}
programs. Next, two-way I/O, discussed briefly in earlier parts of this
@value{DOCUMENT}, is described in full detail, along with the basics
of TCP/IP networking and BSD portal files. Finally, @command{gawk}
@@ -14264,20 +14994,23 @@ discusses the ability to dynamically add new built-in functions to
its description is relegated to an appendix.
@menu
-* Non-decimal Data:: Allowing non-decimal input data.
+* Nondecimal Data:: Allowing nondecimal input data.
* Two-way I/O:: Two-way communications with another process.
* TCP/IP Networking:: Using @command{gawk} for network programming.
* Portal Files:: Using @command{gawk} with BSD portals.
* Profiling:: Profiling your @command{awk} programs.
@end menu
-@node Non-decimal Data, Two-way I/O, Advanced Features, Advanced Features
-@section Allowing Non-Decimal Input Data
+@node Nondecimal Data, Two-way I/O, Advanced Features, Advanced Features
+@section Allowing Nondecimal Input Data
@cindex @code{--non-decimal-data} option
-@cindex command-line option, @code{--non-decimal-data}
+@cindex advanced features, @command{gawk}, nondecimal input data
+@c last comma does NOT start tertiary
+@cindex input, data, nondecimal
+@cindex constants, nondecimal
If you run @command{gawk} with the @option{--non-decimal-data} option,
-you can have non-decimal constants in your input data:
+you can have nondecimal constants in your input data:
@c line break here for small book format
@example
@@ -14314,20 +15047,21 @@ Because it is common to have decimal data with leading zeros, and because
using it could lead to surprising results, the default is to leave this
facility disabled. If you want it, you must explicitly request it.
-@cindex conventions, programming
-@cindex programming conventions
+@cindex programming conventions, @code{--non-decimal-data} option
+@cindex @code{--non-decimal-data} option, @code{strtonum} function and
+@cindex @code{strtonum} function (@command{gawk}), @code{--non-decimal-data} option and
@strong{Caution:}
@emph{Use of this option is not recommended.}
It can break old programs very badly.
Instead, use the @code{strtonum} function to convert your data
-(@pxref{Non-decimal-numbers, ,Octal and Hexadecimal Numbers}).
+(@pxref{Nondecimal-numbers, ,Octal and Hexadecimal Numbers}).
This makes your programs easier to write and easier to read, and
leads to less surprising results.
-@node Two-way I/O, TCP/IP Networking, Non-decimal Data, Advanced Features
+@node Two-way I/O, TCP/IP Networking, Nondecimal Data, Advanced Features
@section Two-Way Communications with Another Process
@cindex Brennan, Michael
-@cindex sex, programmer attractiveness
+@cindex programmers, attractiveness of
@smallexample
@c Path: cssun.mathcs.emory.edu!gatech!newsxfer3.itd.umich.edu!news-peer.sprintlink.net!news-sea-19.sprintlink.net!news-in-west.sprintlink.net!news.sprintlink.net!Sprint!204.94.52.5!news.whidbey.com!brennan
From: brennan@@whidbey.com (Mike Brennan)
@@ -14356,6 +15090,9 @@ Mike Brennan
@c brennan@@whidbey.com
@end smallexample
+@c final comma is part of tertiary
+@cindex advanced features, @command{gawk}, processes, communicating with
+@cindex processes, two-way communications with
It is often useful to be able to
send data to a separate program for
processing and then read the result. This can always be
@@ -14378,16 +15115,16 @@ system("rm " tempfile)
@noindent
This works, but not elegantly.
-@cindex coprocess
-@cindex two-way I/O
-@cindex I/O, two-way
-@cindex @code{|&} I/O operator
-@cindex @command{csh} utility
+@cindex coprocesses
+@cindex input/output, two-way
+@cindex @code{|} (vertical bar), @code{|&} operator (I/O)
+@cindex vertical bar (@code{|}), @code{|&} I/O operator (I/O)
+@cindex @command{csh} utility, @code{|&} operator, comparison with
Starting with @value{PVERSION} 3.1 of @command{gawk}, it is possible to
open a @emph{two-way} pipe to another process. The second process is
termed a @dfn{coprocess}, since it runs in parallel with @command{gawk}.
The two-way connection is created using the new @samp{|&} operator
-(borrowed from the Korn Shell, @command{ksh}):@footnote{This is very
+(borrowed from the Korn shell, @command{ksh}):@footnote{This is very
different from the same operator in the C shell, @command{csh}.}
@example
@@ -14417,7 +15154,10 @@ standard error goes to the same place that the parent @command{gawk}'s
standard error goes. It is not possible to read the child's
standard error separately.
-@cindex deadlock
+@cindex deadlocks
+@cindex buffering, input/output
+@cindex @code{getline} command, deadlock and
+</itemizedlist>
@item
I/O buffering may be a problem. @command{gawk} automatically
flushes all output down the pipe to the child process.
@@ -14428,6 +15168,7 @@ known as @dfn{deadlock}, where each process is waiting for the
other one to do something.
@end itemize
+@cindex @code{close} function, two-way pipes and
It is possible to close just one end of the two-way pipe to
a coprocess, by supplying a second argument to the @code{close}
function of either @code{"to"} or @code{"from"}
@@ -14436,6 +15177,7 @@ These strings tell @command{gawk} to close the end of the pipe
that sends data to the process or the end that reads from it,
respectively.
+@cindex @command{sort} utility, coprocesses and
This is particularly necessary in order to use
the system @command{sort} utility as part of a coprocess;
@command{sort} must read @emph{all} of its input
@@ -14475,9 +15217,12 @@ command ensures traditional Unix (ASCII) sorting from @command{sort}.
@node TCP/IP Networking, Portal Files, Two-way I/O, Advanced Features
@section Using @command{gawk} for Network Programming
-@cindex networking, TCP/IP
-@cindex TCP/IP networking
-@cindex @file{/inet} special files
+@cindex advanced features, @command{gawk}, network programming
+@cindex networks, programming
+@c STARTOFRANGE tcpip
+@cindex TCP/IP
+@cindex @code{/inet/} files (@command{gawk})
+@cindex files, @code{/inet/} (@command{gawk})
@cindex @code{EMISTERED}
@quotation
@code{EMISTERED}: @i{A host is a host from coast to coast,@*
@@ -14499,7 +15244,7 @@ by recognizing special @value{FN}s that begin with @samp{/inet/}.
The full syntax of the special @value{FN} is
@file{/inet/@var{protocol}/@var{local-port}/@var{remote-host}/@var{remote-port}}.
-The meaning of the components are:
+The components are:
@table @var
@item protocol
@@ -14507,17 +15252,19 @@ The protocol to use over IP. This must be either @samp{tcp},
@samp{udp}, or @samp{raw}, for a TCP, UDP, or raw IP connection,
respectively. The use of TCP is recommended for most applications.
+@cindex raw sockets
+@cindex sockets
@strong{Caution:} The use of raw sockets is not currently supported
in @value{PVERSION} 3.1 of @command{gawk}.
@item local-port
-@cindex @code{getservbyname} C library function
+@cindex @code{getservbyname} function (C library)
The local TCP or UDP port number to use. Use a port number of @samp{0}
when you want the system to pick a port. This is what you should do
when writing a TCP or UDP client.
You may also use a well-known service name, such as @samp{smtp}
or @samp{http}, in which case @command{gawk} attempts to determine
-the pre-defined port number using the C @code{getservbyname} function.
+the predefined port number using the C @code{getservbyname} function.
@item remote-host
The IP address or fully-qualified domain name of the Internet
@@ -14558,13 +15305,14 @@ extensive examples.
@node Portal Files, Profiling, TCP/IP Networking, Advanced Features
@section Using @command{gawk} with BSD Portals
+@cindex advanced features, @command{gawk}, BSD portals
@cindex portal files
-@cindex BSD portal files
-@cindex TCP/IP networking
-@cindex @file{/p} special files
+@cindex files, portal
+@cindex BSD portals
+@cindex @code{/p} files (@command{gawk})
+@cindex files, @code{/p} (@command{gawk})
@cindex @code{--enable-portals} configuration option
-@cindex configuration option, @code{--enable-portals}
-@cindex BSD-based operating systems
+@cindex operating systems, BSD-based
Similar to the @file{/inet} special files, if @command{gawk}
is configured with the @option{--enable-portals} option
@@ -14572,29 +15320,39 @@ is configured with the @option{--enable-portals} option
then @command{gawk} treats
files whose pathnames begin with @code{/p} as 4.4 BSD-style portals.
+@cindex @code{|} (vertical bar), @code{|&} operator (I/O), two-way communications
+@cindex vertical bar (@code{|}), @code{|&} operator (I/O), two-way communications
When used with the @samp{|&} operator, @command{gawk} opens the file
for two-way communications. The operating system's portal mechanism
then manages creating the process associated with the portal and
the corresponding communications with the portal's process.
+@c ENDOFRANGE tcpip
@node Profiling, , Portal Files, Advanced Features
@section Profiling Your @command{awk} Programs
+@c STARTOFRANGE awkp
+@cindex @command{awk} programs, profiling
+@c STARTOFRANGE proawk
@cindex profiling @command{awk} programs
+@c STARTOFRANGE pgawk
@cindex @command{pgawk} program
+@cindex profiling @command{gawk}, See @command{pgawk} program
Beginning with @value{PVERSION} 3.1 of @command{gawk}, you may produce execution
traces of your @command{awk} programs.
This is done with a specially compiled version of @command{gawk},
called @command{pgawk} (``profiling @command{gawk}'').
-@cindex @file{awkprof.out} profiling output file
-@cindex profiling output file (@file{awkprof.out})
+@cindex @code{awkprof.out} file
+@cindex files, @code{awkprof.out}
+@cindex @command{pgawk} program, @code{awkprof.out} file
@command{pgawk} is identical in every way to @command{gawk}, except that when
it has finished running, it creates a profile of your program in a file
named @file{awkprof.out}.
-Because it is profiling, it also executes up to 45 percent slower than
+Because it is profiling, it also executes up to 45% slower than
@command{gawk} normally does.
+@cindex @code{--profile} option
As shown in the following example,
the @option{--profile} option can be used to change the name of the file
where @command{pgawk} will write the profile:
@@ -14653,10 +15411,11 @@ junk
@end example
Here is the @file{awkprof.out} that results from running @command{pgawk}
-on this program and data. (This example also illustrates that @command{awk}
-programmers sometimes have to work late.):
+on this program and data (this example also illustrates that @command{awk}
+programmers sometimes have to work late):
-@cindex blocks, @code{BEGIN} and @code{END}
+@cindex @code{BEGIN} pattern, @command{pgawk} program
+@cindex @code{END} pattern, @command{pgawk} program
@example
# gawk profile, created Sun Aug 13 00:00:15 2000
@@ -14699,7 +15458,7 @@ programmers sometimes have to work late.):
@}
@end example
-The previous example illustrates many of the basic rules for profiling output.
+This example illustrates many of the basic rules for profiling output.
The rules are as follows:
@itemize @bullet
@@ -14709,6 +15468,7 @@ pattern/action rules, @code{END} rule and functions, listed
alphabetically.
Multiple @code{BEGIN} and @code{END} rules are merged together.
+@cindex patterns, counts
@item
Pattern-action rules have two counts.
The first count, to the left of the rule, shows how many times
@@ -14728,6 +15488,7 @@ is a count showing how many times the condition was true.
The count for the @code{else}
indicates how many times the test failed.
+@cindex loops, count for header
@item
The count for a loop header (such as @code{for}
or @code{while}) shows how many times the loop test was executed.
@@ -14735,17 +15496,23 @@ or @code{while}) shows how many times the loop test was executed.
statement in a rule to determine how many times the rule was executed.
If the first statement is a loop, the count is misleading.)
+@cindex functions, user-defined, counts
+@cindex user-defined, functions, counts
@item
For user-defined functions, the count next to the @code{function}
keyword indicates how many times the function was called.
The counts next to the statements in the body show how many times
those statements were executed.
+@cindex @code{@{@}} (braces), @command{pgawk} program
+@cindex braces (@code{@{@}}), @command{pgawk} program
@item
-The layout uses ``K&R'' style using tabs.
+The layout uses ``K&R'' style with tabs.
Braces are used everywhere, even when
the body of an @code{if}, @code{else}, or loop is only a single statement.
+@cindex @code{()} (parentheses), @command{pgawk} program
+@cindex parentheses @code{()}, @command{pgawk} program
@item
Parentheses are used only where needed, as indicated by the structure
of the program and the precedence rules.
@@ -14776,7 +15543,7 @@ The profiled version of your program may not look exactly like what you
typed when you wrote it. This is because @command{pgawk} creates the
profiled version by ``pretty printing'' its internal representation of
the program. The advantage to this is that @command{pgawk} can produce
-a standard representation. The disadvantage is that all source code
+a standard representation. The disadvantage is that all source-code
comments are lost, as are the distinctions among multiple @code{BEGIN}
and @code{END} rules. Also, things such as:
@@ -14796,8 +15563,8 @@ come out as:
@noindent
which is correct, but possibly surprising.
-@cindex dynamic profiling
-@cindex profiling, dynamic
+@cindex profiling @command{awk} programs, dynamically
+@cindex @command{pgawk} program, dynamic profiling
Besides creating profiles when a program has completed,
@command{pgawk} can produce a profile while it is running.
This is useful if your @command{awk} program goes into an
@@ -14809,12 +15576,12 @@ $ pgawk -f myprog &
[1] 13992
@end example
-@cindex @command{kill} command
-@cindex @code{SIGUSR1} signal
+@c comma does NOT start secondary
+@cindex @command{kill} command, dynamic profiling
@cindex @code{USR1} signal
-@cindex signals, @code{SIGUSR1}
+@cindex signals, @code{USR1}/@code{SIGUSR1}
@noindent
-The shell prints a job number and process ID number, in this case, 13992.
+The shell prints a job number and process ID number; in this case, 13992.
Use the @command{kill} command to send the @code{USR1} signal
to @command{pgawk}:
@@ -14843,11 +15610,28 @@ You may send @command{pgawk} the @code{USR1} signal as many times as you like.
Each time, the profile and function call trace are appended to the output
profile file.
-@cindex @code{SIGHUP} signal
@cindex @code{HUP} signal
-@cindex signals, @code{SIGHUP}
+@cindex signals, @code{HUP}/@code{SIGHUP}
If you use the @code{HUP} signal instead of the @code{USR1} signal,
-@command{pgawk} produces the profile and the function call trace, and then exits.
+@command{pgawk} produces the profile and the function call trace and then exits.
+
+@cindex @code{INT} signal (MS-DOS)
+@cindex signals, @code{INT}/@code{SIGINT} (MS-DOS)
+@cindex @code{QUIT} signal (MS-DOS)
+@cindex signals, @code{QUIT}/@code{SIGQUIT} (MS-DOS)
+When @command{pgawk} runs on MS-DOS or MS-Windows, it uses the
+@code{INT} and @code{QUIT} signals for producing the profile and, in
+the case of the @code{INT} signal, @command{pgawk} exits. This is
+because these systems don't support the @command{kill} command, so the
+only signals you can deliver to a program are those generated by the
+keyboard. The @code{INT} signal is generated by the
+@kbd{@value{CTL}-@key{C}} or @kbd{@value{CTL}-@key{BREAK}} key, while the
+@code{QUIT} signal is generated by the @kbd{@value{CTL}-@key{\}} key.
+@c ENDOFRANGE advgaw
+@c ENDOFRANGE gawadv
+@c ENDOFRANGE pgawk
+@c ENDOFRANGE awkp
+@c ENDOFRANGE proawk
@node Invoking Gawk, Library Functions, Advanced Features, Top
@chapter Running @command{awk} and @command{gawk}
@@ -14878,12 +15662,10 @@ full details.
@node Command Line, Options, Invoking Gawk, Invoking Gawk
@section Invoking @command{awk}
-@cindex command line
-@cindex invocation of @command{gawk}
-@cindex arguments, command-line
-@cindex options, command-line
-@cindex long options
-@cindex options, long
+@cindex command line, invoking @command{awk} from
+@cindex @command{awk}, invoking
+@cindex arguments, command-line, invoking @command{awk}
+@cindex options, command-line, invoking @command{awk}
There are two ways to run @command{awk}---with an explicit program or with
one or more program files. Here are templates for both of them; items
@@ -14894,28 +15676,39 @@ awk @r{[@var{options}]} -f progfile @r{[@code{--}]} @var{file} @dots{}
awk @r{[@var{options}]} @r{[@code{--}]} '@var{program}' @var{file} @dots{}
@end example
+@cindex GNU long options
+@cindex long options
+@cindex options, long
Besides traditional one-letter POSIX-style options, @command{gawk} also
supports GNU long options.
-@cindex empty program
-@cindex dark corner
-@cindex lint checks
+@cindex dark corner, invoking @command{awk}
+@cindex lint checking, empty programs
It is possible to invoke @command{awk} with an empty program:
@example
awk '' datafile1 datafile2
@end example
+@cindex @code{--lint} option
@noindent
-Doing so makes little sense though; @command{awk} exits
+Doing so makes little sense, though; @command{awk} exits
silently when given an empty program.
@value{DARKCORNER}
If @option{--lint} has
-been specified on the command-line, @command{gawk} issues a
+been specified on the command line, @command{gawk} issues a
warning that the program is empty.
@node Options, Other Arguments, Command Line, Invoking Gawk
@section Command-Line Options
+@c STARTOFRANGE ocl
+@cindex options, command-line
+@c STARTOFRANGE clo
+@cindex command line, options
+@c STARTOFRANGE gnulo
+@cindex GNU long options
+@c STARTOFRANGE longo
+@cindex options, long
Options begin with a dash and consist of a single character.
GNU-style long options consist of two dashes and a keyword.
@@ -14927,6 +15720,7 @@ by whitespace.
If a particular option with a value is given more than once, it is the
last value that counts.
+@cindex POSIX @command{awk}, GNU long options and
Each long option for @command{gawk} has a corresponding
POSIX-style option.
The long and short options are
@@ -14937,27 +15731,24 @@ The options and their meanings are as follows:
@item -F @var{fs}
@itemx --field-separator @var{fs}
@cindex @code{-F} option
-@cindex command-line option, @code{-F}
@cindex @code{--field-separator} option
-@cindex command-line option, @code{--field-separator}
+@cindex @code{FS} variable, @code{--field-separator} option and
Sets the @code{FS} variable to @var{fs}
(@pxref{Field Separators, ,Specifying How Fields Are Separated}).
@item -f @var{source-file}
@itemx --file @var{source-file}
@cindex @code{-f} option
-@cindex command-line option, @code{-f}
@cindex @code{--file} option
-@cindex command-line option, @code{--file}
+@cindex @command{awk} programs, location of
Indicates that the @command{awk} program is to be found in @var{source-file}
instead of in the first non-option argument.
@item -v @var{var}=@var{val}
@itemx --assign @var{var}=@var{val}
@cindex @code{-v} option
-@cindex command-line option, @code{-v}
@cindex @code{--assign} option
-@cindex command-line option, @code{--assign}
+@cindex variables, setting
Sets the variable @var{var} to the value @var{val} @emph{before}
execution of the program begins. Such variable values are available
inside the @code{BEGIN} rule
@@ -14967,6 +15758,10 @@ The @option{-v} option can only set one variable, but it can be used
more than once, setting another variable each time, like this:
@samp{awk @w{-v foo=1} @w{-v bar=2} @dots{}}.
+@c last comma is part of secondary
+@cindex built-in variables, @code{-v} option, setting with
+@c last comma is part of tertiary
+@cindex variables, built-in, @code{-v} option, setting with
@strong{Caution:} Using @option{-v} to set the values of the built-in
variables may lead to surprising results. @command{awk} will reset the
values of those variables as it needs to, possibly ignoring any
@@ -14974,11 +15769,9 @@ predefined value you may have given.
@item -mf @var{N}
@itemx -mr @var{N}
-@cindex @code{-mf} option
-@cindex command-line option, @code{-mf}
-@cindex @code{-mr} option
-@cindex command-line option, @code{-mr}
-Set various memory limits to the value @var{N}. The @samp{f} flag sets
+@cindex @code{-mf}/@code{-mr} options
+@cindex memory, setting limits
+Sets various memory limits to the value @var{N}. The @samp{f} flag sets
the maximum number of fields and the @samp{r} flag sets the maximum
record size. These two flags and the @option{-m} option are from the
Bell Laboratories research version of Unix @command{awk}. They are provided
@@ -14989,7 +15782,6 @@ it continues to accept them to avoid breaking old programs.)
@item -W @var{gawk-opt}
@cindex @code{-W} option
-@cindex command-line option, @code{-W}
Following the POSIX standard, implementation-specific
options are supplied as arguments to the @option{-W} option. These options
also have corresponding GNU-style long options.
@@ -14998,15 +15790,21 @@ the abbreviations remain unique.
The full list of @command{gawk}-specific options is provided next.
@item --
+@cindex command line, options, end of
+@cindex options, command-line, end of
Signals the end of the command-line options. The following arguments
are not treated as options even if they begin with @samp{-}. This
interpretation of @option{--} follows the POSIX argument parsing
conventions.
+@cindex @code{-} (hyphen), filenames beginning with
+@cindex hyphen (@code{-}), filenames beginning with
This is useful if you have @value{FN}s that start with @samp{-},
or in shell scripts, if you have @value{FN}s that will be specified
by the user that could start with @samp{-}.
@end table
+@c ENDOFRANGE gnulo
+@c ENDOFRANGE longo
The previous list described options mandated by the POSIX standard,
as well as options available in the Bell Laboratories version of @command{awk}.
@@ -15018,10 +15816,8 @@ The following list describes @command{gawk}-specific options:
@itemx --compat
@itemx --traditional
@cindex @code{--compat} option
-@cindex command-line option, @code{--compat}
@cindex @code{--traditional} option
-@cindex command-line option, @code{--traditional}
-@cindex compatibility mode
+@cindex compatibility mode (@command{gawk}), specifying
Specifies @dfn{compatibility mode}, in which the GNU extensions to
the @command{awk} language are disabled, so that @command{gawk} behaves just
like the Bell Laboratories research version of Unix @command{awk}.
@@ -15033,42 +15829,42 @@ which summarizes the extensions. Also see
@item -W copyright
@itemx --copyright
@cindex @code{--copyright} option
-@cindex command-line option, @code{--copyright}
+@cindex GPL (General Public License), printing
Print the short version of the General Public License and then exit.
@item -W copyleft
@itemx --copyleft
@cindex @code{--copyleft} option
-@cindex command-line option, @code{--copyleft}
Just like @option{--copyright}.
This option may disappear in a future version of @command{gawk}.
@cindex @code{--dump-variables} option
-@cindex command-line option, @code{--dump-variables}
-@cindex @file{awkvars.out} global variable list output file
+@cindex @code{awkvars.out} file
+@cindex files, @code{awkvars.out}
+@cindex variables, global, printing list of
@item -W dump-variables@r{[}=@var{file}@r{]}
@itemx --dump-variables@r{[}=@var{file}@r{]}
-Print a sorted list of global variables, their types, and final values
+Prints a sorted list of global variables, their types, and final values
to @var{file}. If no @var{file} is provided, @command{gawk} prints this
-list to a file named @file{awkvars.out} in the current directory.
+list to the file named @file{awkvars.out} in the current directory.
-@cindex common mistakes
-@cindex mistakes, common
-@cindex errors, common
-Having a list of all the global variables is a good way to look for
+@c last comma is part of secondary
+@cindex troubleshooting, typographical errors, global variables
+Having a list of all global variables is a good way to look for
typographical errors in your programs.
You would also use this option if you have a large program with a lot of
functions, and you want to be sure that your functions don't
inadvertently use global variables that you meant to be local.
(This is a particularly easy mistake to make with simple variable
-names like @code{i}, @code{j}, and so on.)
+names like @code{i}, @code{j}, etc.)
@item -W gen-po
@itemx --gen-po
@cindex @code{--gen-po} option
-@cindex command-line option, @code{--gen-po}
-Analyze the source program and
-generate a GNU @code{gettext} Portable Object file on standard
+@cindex portable object files, generating
+@cindex files, portable object, generating
+Analyzes the source program and
+generates a GNU @code{gettext} Portable Object file on standard
output for all string constants that have been marked for translation.
@xref{Internationalization, ,Internationalization with @command{gawk}},
for information about this option.
@@ -15078,63 +15874,68 @@ for information about this option.
@itemx --help
@itemx --usage
@cindex @code{--help} option
-@cindex command-line option, @code{--help}
@cindex @code{--usage} option
-@cindex command-line option, @code{--usage}
-Print a ``usage'' message summarizing the short and long style options
+@cindex GNU long options, printing list of
+@cindex options, printing list of
+@cindex printing, list of options
+Prints a ``usage'' message summarizing the short and long style options
that @command{gawk} accepts and then exit.
@item -W lint@r{[}=fatal@r{]}
@itemx --lint@r{[}=fatal@r{]}
@cindex @code{--lint} option
-@cindex command-line option, @code{--lint}
-@cindex lint checks
-@cindex fatal errors
-Warn about constructs that are dubious or non-portable to
+@cindex lint checking, issuing warnings
+@cindex warnings, issuing
+Warns about constructs that are dubious or nonportable to
other @command{awk} implementations.
Some warnings are issued when @command{gawk} first reads your program. Others
are issued at runtime, as your program executes.
With an optional argument of @samp{fatal},
lint warnings become fatal errors.
-This may be drastic but its use will certainly encourage the
+This may be drastic, but its use will certainly encourage the
development of cleaner @command{awk} programs.
@item -W lint-old
@itemx --lint-old
@cindex @code{--lint-old} option
-@cindex command-line option, @code{--lint-old}
-@cindex lint checks
-Warn about constructs that are not available in the original version of
+Warns about constructs that are not available in the original version of
@command{awk} from Version 7 Unix
(@pxref{V7/SVR3.1, ,Major Changes Between V7 and SVR3.1}).
@item -W non-decimal-data
@itemx --non-decimal-data
@cindex @code{--non-decimal-data} option
-@cindex command-line option, @code{--non-decimal-data}
+@cindex hexadecimal, values, enabling interpretation of
+@c comma is part of primary
+@cindex octal values, enabling interpretation of
Enable automatic interpretation of octal and hexadecimal
values in input data
-(@pxref{Non-decimal Data, ,Allowing Non-Decimal Input Data}).
+(@pxref{Nondecimal Data, ,Allowing Nondecimal Input Data}).
+@cindex troubleshooting, @code{--non-decimal-data} option
@strong{Caution:} This option can severely break old programs.
Use with care.
@item -W posix
@itemx --posix
@cindex @code{--posix} option
-@cindex command-line option, @code{--posix}
@cindex POSIX mode
-Operate in strict POSIX mode. This disables all @command{gawk}
+@c last comma is part of tertiary
+@cindex @command{gawk}, extensions, disabling
+Operates in strict POSIX mode. This disables all @command{gawk}
extensions (just like @option{--traditional}) and adds the following additional
restrictions:
@c IMPORTANT! Keep this list in sync with the one in node POSIX
@itemize @bullet
+@cindex escape sequences, unrecognized
@item
@code{\x} escape sequences are not recognized
(@pxref{Escape Sequences}).
+@cindex newlines
+@cindex whitespace, newlines as
@item
Newlines do not act as whitespace to separate fields when @code{FS} is
equal to a single space
@@ -15148,31 +15949,44 @@ Newlines are not allowed after @samp{?} or @samp{:}
The synonym @code{func} for the keyword @code{function} is not
recognized (@pxref{Definition Syntax, ,Function Definition Syntax}).
+@cindex @code{*} (asterisk), @code{**} operator
+@cindex asterisk (@code{*}), @code{**} operator
+@cindex @code{*} (asterisk), @code{**=} operator
+@cindex asterisk (@code{*}), @code{**=} operator
+@cindex @code{^} (caret), @code{^} operator
+@cindex caret (@code{^}), @code{^} operator
+@cindex @code{^} (caret), @code{^=} operator
+@cindex caret (@code{^}), @code{^=} operator
@item
The @samp{**} and @samp{**=} operators cannot be used in
place of @samp{^} and @samp{^=} (@pxref{Arithmetic Ops, ,Arithmetic Operators},
and also @pxref{Assignment Ops, ,Assignment Expressions}).
+@cindex @code{FS} variable, as TAB character
@item
Specifying @samp{-Ft} on the command-line does not set the value
-of @code{FS} to be a single tab character
+of @code{FS} to be a single TAB character
(@pxref{Field Separators, ,Specifying How Fields Are Separated}).
+@c comma does not start secondary
+@cindex @code{fflush} function, unsupported
@item
The @code{fflush} built-in function is not supported
(@pxref{I/O Functions, ,Input/Output Functions}).
@end itemize
-@cindex automatic warnings
-@cindex warnings, automatic
+@c @cindex automatic warnings
+@c @cindex warnings, automatic
+@cindex @code{--traditional} option, @code{--posix} option and
+@cindex @code{--posix} option, @code{--traditional} option and
If you supply both @option{--traditional} and @option{--posix} on the
-command-line, @option{--posix} takes precedence. @command{gawk}
+command line, @option{--posix} takes precedence. @command{gawk}
also issues a warning if both options are supplied.
@item -W profile@r{[}=@var{file}@r{]}
@itemx --profile@r{[}=@var{file}@r{]}
@cindex @code{--profile} option
-@cindex command-line option, @code{--profile}
+@cindex @command{awk} programs, profiling, enabling
Enable profiling of @command{awk} programs
(@pxref{Profiling, ,Profiling Your @command{awk} Programs}).
By default, profiles are created in a file named @file{awkprof.out}.
@@ -15187,8 +16001,8 @@ call counts for each function.
@item -W re-interval
@itemx --re-interval
@cindex @code{--re-interval} option
-@cindex command-line option, @code{--re-interval}
-Allow interval expressions
+@cindex regular expressions, interval expressions and
+Allows interval expressions
(@pxref{Regexp Operators, , Regular Expression Operators})
in regexps.
Because interval expressions were traditionally not available in @command{awk},
@@ -15198,18 +16012,20 @@ programs from breaking.
@item -W source @var{program-text}
@itemx --source @var{program-text}
@cindex @code{--source} option
-@cindex command-line option, @code{--source}
-Program source code is taken from the @var{program-text}. This option
-allows you to mix source code in files with source
-code that you enter on the command-line. This is particularly useful
+@cindex source code, mixing
+Allows you to mix source code in files with source
+code that you enter on the command line.
+Program source code is taken from the @var{program-text}.
+This is particularly useful
when you have library functions that you want to use from your command-line
programs (@pxref{AWKPATH Variable, ,The @env{AWKPATH} Environment Variable}).
@item -W version
@itemx --version
@cindex @code{--version} option
-@cindex command-line option, @code{--version}
-Print version information for this particular copy of @command{gawk}.
+@c last comma is part of tertiary
+@cindex @command{gawk}, versions of, information about, printing
+Prints version information for this particular copy of @command{gawk}.
This allows you to determine if your copy of @command{gawk} is up to date
with respect to whatever the Free Software Foundation is currently
distributing.
@@ -15221,13 +16037,15 @@ As long as program text has been supplied,
any other options are flagged as invalid with a warning message but
are otherwise ignored.
+@cindex @code{-F} option, @code{-Ft} sets @code{FS} to TAB
In compatibility mode, as a special case, if the value of @var{fs} supplied
-to the @option{-F} option is @samp{t}, then @code{FS} is set to the tab
-character (@code{"\t"}). This is only true for @option{--traditional} and not
+to the @option{-F} option is @samp{t}, then @code{FS} is set to the TAB
+character (@code{"\t"}). This is true only for @option{--traditional} and not
for @option{--posix}
(@pxref{Field Separators, ,Specifying How Fields Are Separated}).
-The @option{-f} option may be used more than once on the command-line.
+@cindex @code{-f} option, on command line
+The @option{-f} option may be used more than once on the command line.
If it is, @command{awk} reads its program source from all of the named files, as
if they had been concatenated together into one big file. This is
useful for creating libraries of @command{awk} functions. These functions
@@ -15239,7 +16057,7 @@ function names must be unique.)
Library functions can still be used, even if the program is entered at the terminal,
by specifying @samp{-f /dev/tty}. After typing your program,
-type @kbd{Ctrl-d} (the end-of-file character) to terminate it.
+type @kbd{@value{CTL}-d} (the end-of-file character) to terminate it.
(You may also use @samp{-f -} to read program source from the standard
input but then you will not be able to also use the standard input as a
source of data.)
@@ -15251,18 +16069,19 @@ input for your source code; it allows you to easily mix command-line
and library source code
(@pxref{AWKPATH Variable, ,The @env{AWKPATH} Environment Variable}).
+@cindex @code{--source} option
If no @option{-f} or @option{--source} option is specified, then @command{gawk}
uses the first non-option command-line argument as the text of the
program source code.
@cindex @code{POSIXLY_CORRECT} environment variable
-@cindex environment variable, @code{POSIXLY_CORRECT}
-@cindex lint checks
+@cindex lint checking, @code{POSIXLY_CORRECT} environment variable
+@cindex POSIX mode
If the environment variable @env{POSIXLY_CORRECT} exists,
then @command{gawk} behaves in strict POSIX mode, exactly as if
you had supplied the @option{--posix} command-line option.
Many GNU programs look for this environment variable to turn on
-strict POSIX mode. If @option{--lint} is supplied on the command-line
+strict POSIX mode. If @option{--lint} is supplied on the command line
and @command{gawk} turns on POSIX mode because of @env{POSIXLY_CORRECT},
then it issues a warning message indicating that POSIX
mode is in effect.
@@ -15275,8 +16094,8 @@ POSIXLY_CORRECT=true
export POSIXLY_CORRECT
@end example
-@cindex @command{csh} utility
-For a @command{csh} compatible
+@cindex @command{csh} utility, @code{POSIXLY_CORRECT} environment variable
+For a @command{csh}-compatible
shell,@footnote{Not recommended.}
you would add this line to the @file{.login} file in your home directory:
@@ -15284,14 +16103,19 @@ you would add this line to the @file{.login} file in your home directory:
setenv POSIXLY_CORRECT true
@end example
+@cindex portability, @code{POSIXLY_CORRECT} environment variable
Having @env{POSIXLY_CORRECT} set is not recommended for daily use,
but it is good for testing the portability of your programs to other
environments.
+@c ENDOFRANGE ocl
+@c ENDOFRANGE clo
@node Other Arguments, AWKPATH Variable, Options, Invoking Gawk
@section Other Command-Line Arguments
+@cindex command line, arguments
+@cindex arguments, command-line
-Any additional arguments on the command-line are normally treated as
+Any additional arguments on the command line are normally treated as
input files to be processed in the order specified. However, an
argument that has the form @code{@var{var}=@var{value}}, assigns
the value @var{value} to the variable @var{var}---it does not specify a
@@ -15299,8 +16123,8 @@ file at all.
(This was discussed earlier in
@ref{Assignment Options, ,Assigning Variables on the Command Line}.)
-@cindex @code{ARGIND} variable
-@cindex @code{ARGV} variable
+@cindex @code{ARGIND} variable, command-line arguments
+@cindex @code{ARGC}/@code{ARGV} variables, command-line arguments
All these arguments are made available to your @command{awk} program in the
@code{ARGV} array (@pxref{Built-in Variables}). Command-line options
and the program text (if present) are omitted from @code{ARGV}.
@@ -15309,6 +16133,7 @@ included. As each element of @code{ARGV} is processed, @command{gawk}
sets the variable @code{ARGIND} to the index in @code{ARGV} of the
current element.
+@cindex input files, variable assignments and
The distinction between @value{FN} arguments and variable-assignment
arguments is made when @command{awk} is about to open the next input file.
At that point in execution, it checks the @value{FN} to see whether
@@ -15322,8 +16147,8 @@ variables assigned in this fashion are @emph{not} available inside a
(@pxref{BEGIN/END, ,The @code{BEGIN} and @code{END} Special Patterns}),
because such rules are run before @command{awk} begins scanning the argument list.
-@cindex dark corner
-The variable values given on the command-line are processed for escape
+@cindex dark corner, escape sequences
+The variable values given on the command line are processed for escape
sequences (@pxref{Escape Sequences}).
@value{DARKCORNER}
@@ -15343,8 +16168,7 @@ output formats before scanning the @value{DF}s. It is also useful for
controlling state if multiple passes are needed over a @value{DF}. For
example:
-@cindex multiple passes over data
-@cindex passes, multiple
+@cindex files, multiple passes over
@example
awk 'pass == 1 @{ @var{pass 1 stuff} @}
pass == 2 @{ @var{pass 2 stuff} @}' pass=1 mydata pass=2 mydata
@@ -15357,12 +16181,9 @@ strictly necessary. It remains for historical compatibility.
@node AWKPATH Variable, Obsolete, Other Arguments, Invoking Gawk
@section The @env{AWKPATH} Environment Variable
@cindex @env{AWKPATH} environment variable
-@cindex environment variable, @env{AWKPATH}
-@cindex search path
-@cindex directory search
-@cindex path, search
-@cindex search path, for source files
-@cindex differences between @command{gawk} and @command{awk}
+@cindex directories, searching
+@cindex search paths, for source files
+@cindex differences in @command{awk} and @command{gawk}, @code{AWKPATH} environment variable
@ifinfo
The previous @value{SECTION} described how @command{awk} program files can be named
on the command-line with the @option{-f} option.
@@ -15378,12 +16199,12 @@ file with the specified name.
The search path is a string consisting of directory names
separated by colons. @command{gawk} gets its search path from the
@env{AWKPATH} environment variable. If that variable does not exist,
-@command{gawk} uses a default path, which is
+@command{gawk} uses a default path,
@samp{.:/usr/local/share/awk}.@footnote{Your version of @command{gawk}
may use a different directory; it
will depend upon how @command{gawk} was built and installed. The actual
directory is the value of @samp{$(datadir)} generated when
-@command{gawk} was configured. You probably don't need to worry about this
+@command{gawk} was configured. You probably don't need to worry about this,
though.} (Programs written for use by
system administrators should use an @env{AWKPATH} variable that
does not include the current directory, @file{.}.)
@@ -15391,12 +16212,12 @@ does not include the current directory, @file{.}.)
The search path feature is particularly useful for building libraries
of useful @command{awk} functions. The library files can be placed in a
standard directory in the default path and then specified on
-the command-line with a short @value{FN}. Otherwise, the full @value{FN}
+the command line with a short @value{FN}. Otherwise, the full @value{FN}
would have to be typed for each file.
By using both the @option{--source} and @option{-f} options, your command-line
-@command{awk} programs can use facilities in @command{awk} library files.
-@xref{Library Functions, , A Library of @command{awk} Functions}.
+@command{awk} programs can use facilities in @command{awk} library files
+(@pxref{Library Functions, , A Library of @command{awk} Functions}).
Path searching is not done if @command{gawk} is in compatibility mode.
This is true for both @option{--traditional} and @option{--posix}.
@xref{Options, ,Command-Line Options}.
@@ -15426,9 +16247,9 @@ found, and @command{gawk} no longer needs to use @env{AWKPATH}.
@node Obsolete, Undocumented, AWKPATH Variable, Invoking Gawk
@section Obsolete Options and/or Features
-@cindex deprecated options
-@cindex obsolete options
-@cindex deprecated features
+@cindex features, advanced, See advanced features
+@cindex options, deprecated
+@cindex features, deprecated
@cindex obsolete features
This @value{SECTION} describes features and/or command-line options from
previous releases of @command{gawk} that are either not available in the
@@ -15437,13 +16258,15 @@ they will @emph{not} be in the next release).
@c update this section for each release!
+@cindex @code{next file} statement, deprecated
+@cindex @code{nextfile} statement, @code{next file} statement and
For @value{PVERSION} @value{VERSION} of @command{gawk}, there are no
deprecated command-line options
@c or other deprecated features
from the previous version of @command{gawk}.
The use of @samp{next file} (two words) for @code{nextfile} was deprecated
in @command{gawk} 3.0 but still worked. Starting with @value{PVERSION} 3.1, the
-two word usage is no longer accepted.
+two-word usage is no longer accepted.
The process-related special files described in
@ref{Special Process, ,Special Files for Process-Related Information},
@@ -15523,6 +16346,10 @@ explanation.
You can insert newlines after the @samp{;} in @code{for} loops.
This seems to have been a long-undocumented feature in Unix @command{awk}.
+Similarly, you may use @code{print} or @code{printf} statements in the
+@var{init} and @var{increment} parts of a @code{for} loop. This is another
+long-undocumented ``feature'' of Unix @code{awk}.
+
If the environment variable @env{WHINY_USERS} exists
when @command{gawk} is run,
then the associative @code{for} loop will go through the array
@@ -15531,24 +16358,32 @@ The comparison used for sorting is simple string comparison;
any non-English or non-ASCII locales are not taken into account.
@code{IGNORECASE} does not affect the comparison either.
+In addition, if @env{WHINY_USERS} is set, the profiled version of a
+program generated by @option{--profile} will print all 8-bit characters
+verbatim, instead of using the octal equivalent.
+
@end ignore
@node Known Bugs, , Undocumented, Invoking Gawk
@section Known Bugs in @command{gawk}
-@cindex bugs, known in @command{gawk}
-@cindex known bugs
+@cindex @command{gawk}, debugging
+@cindex debugging @command{gawk}
+@cindex troubleshooting, @command{gawk}
@itemize @bullet
+@cindex troubleshooting, @code{-F} option
+@cindex @code{-F} option, troubleshooting
+@cindex @code{FS} variable, changing value of
@item
The @option{-F} option for changing the value of @code{FS}
(@pxref{Options, ,Command-Line Options})
is not necessary given the command-line variable
-assignment feature; it remains only for backwards compatibility.
+assignment feature; it remains only for backward compatibility.
@item
-Syntactically invalid single character programs tend to overflow
+Syntactically invalid single-character programs tend to overflow
the parse stack, generating a rather unhelpful message. Such programs
-are surprisingly difficult to diagnose in the completely general case
+are surprisingly difficult to diagnose in the completely general case,
and the effort to do so really is not worth it.
@end itemize
@@ -15579,6 +16414,12 @@ It contains the following chapters:
@node Library Functions, Sample Programs, Invoking Gawk, Top
@chapter A Library of @command{awk} Functions
+@c STARTOFRANGE libf
+@cindex libraries of @command{awk} functions
+@c STARTOFRANGE flib
+@cindex functions, library
+@c STARTOFRANGE fudlib
+@cindex functions, user-defined, library of
@ref{User-defined, ,User-Defined Functions}, describes how to write
your own @command{awk} functions. Writing functions is important, because
@@ -15605,21 +16446,20 @@ these example library functions and programs from the Texinfo source
for this @value{DOCUMENT}.
(This has already been done as part of the @command{gawk} distribution.)
-If you have written one or more useful, general purpose @command{awk} functions
+If you have written one or more useful, general-purpose @command{awk} functions
and would like to contribute them to the author's collection of @command{awk}
programs, see
@ref{How To Contribute, ,How to Contribute}, for more information.
-@cindex portability issues
+@cindex portability, example programs
The programs in this @value{CHAPTER} and in
@ref{Sample Programs, ,Practical @command{awk} Programs},
freely use features that are @command{gawk}-specific.
-It is straightforward to rewrite these programs for
-different implementations of @command{awk}.
+Rewriting these programs for different implementations of awk is pretty straightforward.
Diagnostic error messages are sent to @file{/dev/stderr}.
-Use @samp{| "cat 1>&2"} instead of @samp{> "/dev/stderr"}, if your system
-does not have a @file{/dev/stderr} or if you cannot use @command{gawk}.
+Use @samp{| "cat 1>&2"} instead of @samp{> "/dev/stderr"} if your system
+does not have a @file{/dev/stderr}, or if you cannot use @command{gawk}.
A number of programs use @code{nextfile}
(@pxref{Nextfile Statement, ,Using @command{gawk}'s @code{nextfile} Statement})
@@ -15628,6 +16468,8 @@ to skip any remaining input in the input file.
shows you how to write a function that does the same thing.
@c 12/2000: Thanks to Nelson Beebe for pointing out the output issue.
+@cindex case sensitivity, example programs
+@cindex @code{IGNORECASE} variable, in example programs
Finally, some of the programs choose to ignore upper- and lowercase
distinctions in their input. They do so by assigning one to @code{IGNORECASE}.
You can achieve almost the same effect@footnote{The effects are
@@ -15643,7 +16485,7 @@ beginning of the program:
@noindent
Also, verify that all regexp and string constants used in
-comparisons only use lowercase letters.
+comparisons use only lowercase letters.
@menu
* Library Names:: How to best name private global variables in
@@ -15660,15 +16502,19 @@ comparisons only use lowercase letters.
@node Library Names, General Functions, Library Functions, Library Functions
@section Naming Library Function Global Variables
-@cindex names, use of
-@cindex namespace issues in @command{awk}
-@cindex documenting @command{awk} programs
-@cindex programs, documenting
+@cindex names, arrays/variables
+@cindex names, functions
+@cindex namespace issues
+@cindex @command{awk} programs, documenting
+@cindex documentation, of @command{awk} programs
Due to the way the @command{awk} language evolved, variables are either
@dfn{global} (usable by the entire program) or @dfn{local} (usable just by
a specific function). There is no intermediate state analogous to
@code{static} variables in C.
+@cindex variables, global, for library functions
+@cindex private variables
+@cindex variables, private
Library functions often need to have global variables that they can use to
preserve state information between calls to the function---for example,
@code{getopt}'s variable @code{_opti}
@@ -15682,14 +16528,15 @@ either another library function or a user's main program. For example, a
name like @samp{i} or @samp{j} is not a good choice, because user programs
often use variable names like these for their own purposes.
-@cindex conventions, programming
-@cindex programming conventions
+@cindex programming conventions, private variable names
The example programs shown in this @value{CHAPTER} all start the names of their
private variables with an underscore (@samp{_}). Users generally don't use
leading underscores in their variable names, so this convention immediately
decreases the chances that the variable name will be accidentally shared
with the user's program.
+@cindex @code{_} (underscore), in names of private variables
+@cindex underscore (@code{_}), in names of private variables
In addition, several of the library functions use a prefix that helps
indicate what function or set of functions use the variables---for example,
@code{_pw_byname} in the user database routines
@@ -15699,7 +16546,7 @@ chance of inadvertent conflict among variable names. Note that this
convention is used equally well for variable names and for private
function names as well.@footnote{While all the library routines could have
been rewritten to use this convention, this was not done, in order to
-show how my own @command{awk} programming style has evolved, and to
+show how my own @command{awk} programming style has evolved and to
provide some basis for this discussion.}
As a final note on variable naming, if a function makes global variables
@@ -15711,6 +16558,7 @@ The leading capital letter indicates that it is global, while the fact that
the variable name is not all capital letters indicates that the variable is
not one of @command{awk}'s built-in variables, such as @code{FS}.
+@cindex @code{--dump-variables} option
It is also important that @emph{all} variables in library
functions that do not need to save state are, in fact, declared
local.@footnote{@command{gawk}'s @option{--dump-variables} command-line
@@ -15727,6 +16575,9 @@ function lib_func(x, y, l1, l2)
@}
@end example
+@cindex arrays, associative, library functions and
+@cindex libraries of @command{awk} functions, associative arrays and
+@cindex functions, library, associative arrays and
@cindex Tcl
A different convention, common in the Tcl community, is to use a single
associative array to hold the values needed by the library function(s), or
@@ -15765,9 +16616,15 @@ programming use.
@node Nextfile Function, Assert Function, General Functions, General Functions
@subsection Implementing @code{nextfile} as a Function
-@cindex skipping input files
@cindex input files, skipping
-The @code{nextfile} statement presented in
+@c STARTOFRANGE libfnex
+@cindex libraries of @command{awk} functions, @code{nextfile} statement
+@c STARTOFRANGE flibnex
+@cindex functions, library, @code{nextfile} statement
+@c STARTOFRANGE nexim
+@cindex @code{nextfile} statement, implementing
+@cindex @command{gawk}, @code{nextfile} statement in
+The @code{nextfile} statement, presented in
@ref{Nextfile Statement, ,Using @command{gawk}'s @code{nextfile} Statement},
is a @command{gawk}-specific extension---it is not available in most other
implementations of @command{awk}. This @value{SECTION} shows two versions of a
@@ -15784,8 +16641,7 @@ function nextfile() @{ _abandon_ = FILENAME; next @}
_abandon_ == FILENAME @{ next @}
@end example
-@cindex conventions, programming
-@cindex programming conventions
+@cindex programming conventions, @code{nextfile} statement
Because it supplies a rule that must be executed first, this file should
be included before the main program. This rule compares the current
@value{DF}'s name (which is always in the @code{FILENAME} variable) to
@@ -15800,7 +16656,7 @@ all the records from the current @value{DF}.
The end of the file is eventually reached and
a new @value{DF} is opened, changing the value of @code{FILENAME}.
Once this happens, the comparison of @code{_abandon_} to @code{FILENAME}
-fails and execution continues with the first rule of the ``real'' program.
+fails, and execution continues with the first rule of the ``real'' program.
The @code{nextfile} function itself simply sets the value of @code{_abandon_}
and then executes a @code{next} statement to start the
@@ -15819,7 +16675,7 @@ This initial version has a subtle problem.
If the same @value{DF} is listed @emph{twice} on the commandline,
one right after the other
or even with just a variable assignment between them,
-this code skips right through the file, a second time, even though
+this code skips right through the file a second time, even though
it should stop when it gets to the end of the first occurrence.
A second version of @code{nextfile} that remedies this problem
is shown here:
@@ -15885,12 +16741,22 @@ next one, which saves a lot of time. This is particularly important in
@command{awk}, because @command{awk} programs are generally I/O-bound (i.e.,
they spend most of their time doing input and output, instead of performing
computations).
+@c ENDOFRANGE libfnex
+@c ENDOFRANGE flibnex
+@c ENDOFRANGE nexim
@node Assert Function, Round Function, Nextfile Function, General Functions
@subsection Assertions
+@c STARTOFRANGE asse
@cindex assertions
-@cindex @code{assert} C library function
+@c STARTOFRANGE assef
+@cindex @code{assert} function (C library)
+@c STARTOFRANGE libfass
+@cindex libraries of @command{awk} functions, assertions
+@c STARTOFRANGE flibass
+@cindex functions, library, assertions
+@cindex @command{awk} programs, lengthy, assertions
When writing large programs, it is often useful to know
that a condition or set of conditions is true. Before proceeding with a
particular computation, you make a statement about what you believe to be
@@ -15963,7 +16829,7 @@ is false, it prints a message to standard error, using the @code{string}
parameter to describe the failed condition. It then sets the variable
@code{_assert_exit} to one and executes the @code{exit} statement.
The @code{exit} statement jumps to the @code{END} rule. If the @code{END}
-rules finds @code{_assert_exit} to be true, it then exits immediately.
+rules finds @code{_assert_exit} to be true, it exits immediately.
The purpose of the test in the @code{END} rule is to
keep any other @code{END} rules from running. When an assertion fails, the
@@ -15990,6 +16856,7 @@ If the assertion fails, you see a message similar to the following:
mydata:1357: assertion failed: a <= 5 && b >= 17.1
@end example
+@cindex @code{END} pattern, @code{assert} user-defined function and
There is a small problem with this version of @code{assert}.
An @code{END} rule is automatically added
to the program calling @code{assert}. Normally, if a program consists
@@ -15999,14 +16866,26 @@ attempts to read the input @value{DF}s or standard input
(@pxref{Using BEGIN/END, , Startup and Cleanup Actions}),
most likely causing the program to hang as it waits for input.
+@cindex @code{BEGIN} pattern, @code{assert} user-defined function and
There is a simple workaround to this:
make sure the @code{BEGIN} rule always ends
with an @code{exit} statement.
+@c ENDOFRANGE asse
+@c ENDOFRANGE assef
+@c ENDOFRANGE flibass
+@c ENDOFRANGE libfass
@node Round Function, Cliff Random Function, Assert Function, General Functions
@subsection Rounding Numbers
@cindex rounding
+@cindex rounding numbers
+@cindex numbers, rounding
+@cindex libraries of @command{awk} functions, rounding numbers
+@cindex functions, library, rounding numbers
+@cindex @code{print} statement, @code{sprintf} function and
+@cindex @code{printf} statement, @code{sprintf} function and
+@cindex @code{sprintf} function, @code{print}/@code{printf} statements and
The way @code{printf} and @code{sprintf}
(@pxref{Printf, , Using @code{printf} Statements for Fancier Printing})
perform rounding often depends upon the system's C @code{sprintf}
@@ -16022,7 +16901,7 @@ does unbiased rounding:
@cindex @code{round} user-defined function
@example
@c file eg/lib/round.awk
-# round --- do normal rounding
+# round.awk --- do normal rounding
@c endfile
@ignore
@c file eg/lib/round.awk
@@ -16067,6 +16946,8 @@ function round(x, ival, aval, fraction)
@subsection The Cliff Random Number Generator
@cindex random numbers, Cliff
@cindex Cliff random numbers
+@cindex numbers, Cliff random
+@cindex functions, library, Cliff random numbers
The Cliff random number
generator@footnote{@uref{http://mathworld.wolfram.com/CliffRandomNumberGenerator.hmtl}}
@@ -16109,8 +16990,10 @@ isn't random enough, you might try using this function instead.
@node Ordinal Functions, Join Function, Cliff Random Function, General Functions
@subsection Translating Between Characters and Numbers
-@cindex numeric character values
-@cindex values of characters as numbers
+@cindex libraries of @command{awk} functions, character values as numbers
+@cindex functions, library, character values as numbers
+@cindex characters, values of as numbers
+@cindex numbers, as values of characters
One commercial implementation of @command{awk} supplies a built-in function,
@code{ord}, which takes a character and returns the numeric value for that
character in the machine's character set. If the string passed to
@@ -16166,14 +17049,14 @@ function _ord_init( low, high, i, t)
@c endfile
@end example
-@cindex character sets (machine character encodings)
+@cindex character sets
@cindex character encodings
@cindex ASCII
@cindex EBCDIC
@cindex mark parity
Some explanation of the numbers used by @code{chr} is worthwhile.
The most prominent character set in use today is ASCII. Although an
-eight-bit byte can hold 256 distinct values (from 0 to 255), ASCII only
+8-bit byte can hold 256 distinct values (from 0 to 255), ASCII only
defines characters that use the values from 0 to 127.@footnote{ASCII
has been extended in many countries to use the values from 128 to 255
for country-specific characters. If your system uses these extensions,
@@ -16227,7 +17110,10 @@ function. It is commented out for production use.
@node Join Function, Gettimeofday Function, Ordinal Functions, General Functions
@subsection Merging an Array into a String
-@cindex merging strings
+@cindex libraries of @command{awk} functions, merging arrays into strings
+@cindex functions, library, merging arrays into strings
+@cindex strings, merging arrays into
+@cindex arrays, merging into strings
When doing string processing, it is often useful to be able to join
all the strings in an array into one long string. The following function,
@code{join}, accomplishes this task. It is used later in several of
@@ -16270,7 +17156,7 @@ function join(array, start, end, sep, result, i)
@end example
An optional additional argument is the separator to use when joining the
-strings back together. If the caller supplies a non-empty value,
+strings back together. If the caller supplies a nonempty value,
@code{join} uses it; if it is not supplied, it has a null
value. In this case, @code{join} uses a single blank as a default
separator for the strings. If the value is equal to @code{SUBSEP},
@@ -16284,8 +17170,10 @@ more difficult than they really need to be.}
@node Gettimeofday Function, , Join Function, General Functions
@subsection Managing the Time of Day
-@cindex formatted timestamps
+@cindex libraries of @command{awk} functions, managing, time
+@cindex functions, library, managing time
@cindex timestamps, formatted
+@cindex time, managing
The @code{systime} and @code{strftime} functions described in
@ref{Time Functions, ,Using @command{gawk}'s Timestamp Functions},
provide the minimum functionality necessary for dealing with the time of day
@@ -16382,8 +17270,14 @@ of the current time.
@node Data File Management, Getopt Function, General Functions, Library Functions
@section @value{DDF} Management
+@c STARTOFRANGE dataf
+@cindex files, managing
+@c STARTOFRANGE libfdataf
+@cindex libraries of @command{awk} functions, managing, @value{DF}s
+@c STARTOFRANGE flibdataf
+@cindex functions, library, managing @value{DF}s
This @value{SECTION} presents functions that are useful for managing
-command-line datafiles.
+command-line @value{DF}s.
@menu
* Filetrans Function:: A function for handling data file transitions.
@@ -16395,8 +17289,9 @@ command-line datafiles.
@node Filetrans Function, Rewind Function, Data File Management, Data File Management
@subsection Noting @value{DDF} Boundaries
-@cindex per file initialization and cleanup
-The @code{BEGIN} and @code{END} rules are each executed exactly once, at
+@cindex files, managing, @value{DF} boundaries
+@cindex files, initialization and cleanup
+The @code{BEGIN} and @code{END} rules are each executed exactly once at
the beginning and end of your @command{awk} program, respectively
(@pxref{BEGIN/END, ,The @code{BEGIN} and @code{END} Special Patterns}).
We (the @command{gawk} authors) once had a user who mistakenly thought that the
@@ -16500,6 +17395,7 @@ how it simplifies writing the main program.
@node Rewind Function, File Checking, Filetrans Function, Data File Management
@subsection Rereading the Current File
+@cindex files, reading
Another request for a new built-in function was for a @code{rewind}
function that would make it possible to reread the current file.
The requesting user didn't want to have to use @code{getline}
@@ -16565,11 +17461,10 @@ for a function version of @code{nextfile}.
@node File Checking, Ignoring Assigns, Rewind Function, Data File Management
@subsection Checking for Readable @value{DDF}s
-@cindex fatal errors
+@cindex troubleshooting, readable @value{DF}s
+@c comma is part of primary
@cindex readable @value{DF}s, checking
-@cindex non-readable @value{DF}s, skipping
-@cindex @value{DF}s, non-readable, skipping
-@cindex @value{DF}s, readable, checking
+@cindex files, skipping
Normally, if you give @command{awk} a @value{DF} that isn't readable,
it stops with a fatal error. There are times when you
might want to just ignore such files and keep going. You can
@@ -16604,7 +17499,7 @@ BEGIN @{
@c endfile
@end example
-@cindex fatal errors
+@cindex troubleshooting, @code{getline} function
In @command{gawk}, the @code{getline} won't be fatal (unless
@option{--posix} is in force).
Removing the element from @code{ARGV} with @code{delete}
@@ -16615,6 +17510,8 @@ skips the file (since it's no longer in the list).
@node Ignoring Assigns, , File Checking, Data File Management
@subsection Treating Assignments as @value{FFN}s
+@cindex assignments as filenames
+@cindex filenames, assignments as
Occasionally, you might not want @command{awk} to process command-line
variable assignments
(@pxref{Assignment Options, ,Assigning Variables on the Command Line}).
@@ -16669,13 +17566,24 @@ The use of @code{No_command_assign} allows you to disable command-line
assignments at invocation time, by giving the variable a true value.
When not set, it is initially zero (i.e., false), so the command-line arguments
are left alone.
+@c ENDOFRANGE dataf
+@c ENDOFRANGE flibdataf
+@c ENDOFRANGE libfdataf
@node Getopt Function, Passwd Functions, Data File Management, Library Functions
@section Processing Command-Line Options
-@cindex @code{getopt} C library function
-@cindex processing arguments
-@cindex argument processing
+@c STARTOFRANGE libfclo
+@cindex libraries of @command{awk} functions, command-line options
+@c STARTOFRANGE flibclo
+@cindex functions, library, command-line options
+@c STARTOFRANGE clop
+@cindex command-line options, processing
+@c STARTOFRANGE oclp
+@cindex options, command-line, processing
+@c STARTOFRANGE clibf
+@cindex functions, library, C library
+@cindex arguments, processing
Most utilities on POSIX compatible systems take options, or ``switches,'' on
the command line that can be used to change the way a program behaves.
@command{awk} is an example of such a program
@@ -16686,6 +17594,7 @@ correctly obey the command-line option. For example, @command{awk}'s
The first occurrence on the command line of either @option{--} or a
string that does not begin with @samp{-} ends the options.
+@cindex @code{getopt} function (C library)
Modern Unix systems provide a C function named @code{getopt} for processing
command-line arguments. The programmer provides a string describing the
one-letter options. If an option requires an argument, it is followed in the
@@ -16698,7 +17607,7 @@ When it returns @minus{}1, there are no options left on the command line.
When using @code{getopt}, options that do not take arguments can be
grouped together. Furthermore, options that take arguments require that the
-argument is present. The argument can immediately follow the option letter
+argument is present. The argument can immediately follow the option letter,
or it can be a separate command-line argument.
Given a hypothetical program that takes
@@ -16723,7 +17632,7 @@ and that @samp{foo} is the argument to the @option{-b} option.
@table @code
@item optind
The index in the argument value array (@code{argv}) where the first
-non-option command-line argument can be found.
+nonoption command-line argument can be found.
@item optarg
The string value of the argument to an option.
@@ -16789,6 +17698,7 @@ We have left it alone, since using @code{substr} is more portable.}
The discussion that follows walks through the code a bit at a time:
+@cindex @code{getopt} user-defined function
@example
@c file eg/lib/getopt.awk
# getopt.awk --- do C library getopt(3) function in awk
@@ -16805,7 +17715,7 @@ The discussion that follows walks through the code a bit at a time:
@end ignore
@c file eg/lib/getopt.awk
# External variables:
-# Optind -- index in ARGV of first non-option argument
+# Optind -- index in ARGV of first nonoption argument
# Optarg -- string value of argument to current option
# Opterr -- if nonzero, print our own diagnostic
# Optopt -- current option letter
@@ -16861,7 +17771,7 @@ The regular expression that is used, @code{@w{/^-[^: \t\n\f\r\v\b]/}}, is
perhaps a bit of overkill; it checks for a @samp{-} followed by anything
that is not whitespace and not a colon.
If the current command-line argument does not match this pattern,
-it is not an option, and it ends option processing.
+it is not an option, and it ends option processing:
@example
@c file eg/lib/getopt.awk
@@ -16929,7 +17839,7 @@ If the option requires an argument, the option letter is followed by a colon
in the @code{options} string. If there are remaining characters in the
current command-line argument (@code{argv[Optind]}), then the rest of that
string is assigned to @code{Optarg}. Otherwise, the next command-line
-argument is used (@samp{-xFOO} vs.@: @samp{@w{-x FOO}}). In either case,
+argument is used (@samp{-xFOO} versus @samp{@w{-x FOO}}). In either case,
@code{_opti} is reset to zero, because there are no more characters left to
examine in the current command-line argument. Continuing:
@@ -17005,26 +17915,43 @@ not try to interpret the @option{-a}, etc., as its own options.
Several of the sample programs presented in
@ref{Sample Programs, ,Practical @command{awk} Programs},
use @code{getopt} to process their arguments.
+@c ENDOFRANGE libfclo
+@c ENDOFRANGE flibclo
+@c ENDOFRANGE clop
+@c ENDOFRANGE oclp
@node Passwd Functions, Group Functions, Getopt Function, Library Functions
@section Reading the User Database
+@c STARTOFRANGE libfudata
+@cindex libraries of @command{awk} functions, user database, reading
+@c STARTOFRANGE flibudata
+@cindex functions, library, user database, reading
+@c last comma is part of primary
+@c STARTOFRANGE udatar
+@cindex user database, reading
+@c last comma is part of secondary
+@c STARTOFRANGE dataur
+@cindex database, users, reading
+@cindex @code{PROCINFO} array
The @code{PROCINFO} array
(@pxref{Built-in Variables})
-provides access to the current user's real and effective user and group id
+provides access to the current user's real and effective user and group ID
numbers, and if available, the user's supplementary group set.
However, because these are numbers, they do not provide very useful
information to the average user. There needs to be some way to find the
-user information associated with the user and group numbers. This
+user information associated with the user and group ID numbers. This
@value{SECTION} presents a suite of functions for retrieving information from the
user database. @xref{Group Functions, ,Reading the Group Database},
for a similar suite that retrieves information from the group database.
-@cindex @code{getpwent} C library function
-@cindex user information
+@cindex @code{getpwent} function (C library)
+@cindex @code{getpwent} user-defined function
+@cindex users, information about, retrieving
@cindex login information
@cindex account information
@cindex password file
+@cindex files, password
The POSIX standard does not define the file where user information is
kept. Instead, it provides the @code{<pwd.h>} header file
and several C language subroutines for obtaining user information.
@@ -17044,7 +17971,7 @@ is defined as returning a pointer to a @code{struct passwd}. Each time it
is called, it returns the next entry in the database. When there are
no more entries, it returns @code{NULL}, the null pointer. When this
happens, the C program should call @code{endpwent} to close the database.
-Following is @command{pwcat}, a C program that ``cats'' the password database.
+Following is @command{pwcat}, a C program that ``cats'' the password database:
@c Use old style function header for portability to old systems (SunOS, HP/UX).
@@ -17100,10 +18027,10 @@ The user's login name.
The user's encrypted password. This may not be available on some systems.
@item User-ID
-The user's numeric user-id number.
+The user's numeric user ID number.
@item Group-ID
-The user's numeric group-id number.
+The user's numeric group ID number.
@item Full name
The user's full name, and perhaps other information associated with the
@@ -17124,9 +18051,9 @@ shell, such as @command{bash}.
@item Encrypted password @tab The user's encrypted password. This may not be available on some systems.
-@item User-ID @tab The user's numeric user-id number.
+@item User-ID @tab The user's numeric user ID number.
-@item Group-ID @tab The user's numeric group-id number.
+@item Group-ID @tab The user's numeric group ID number.
@item Full name @tab The user's full name, and perhaps other information associated with the
user.
@@ -17213,6 +18140,7 @@ function _pw_init( oldfs, oldrs, olddol0, pwcat, using_fw)
@c endfile
@end example
+@cindex @code{BEGIN} pattern, @code{pwcat} program
The @code{BEGIN} rule sets a private variable to the directory where
@command{pwcat} is stored. Because it is used to help out an @command{awk} library
routine, we have chosen to put it in @file{/usr/local/libexec/awk};
@@ -17220,11 +18148,12 @@ however, you might want it to be in a different directory on your system.
The function @code{_pw_init} keeps three copies of the user information
in three associative arrays. The arrays are indexed by username
-(@code{_pw_byname}), by user-id number (@code{_pw_byuid}), and by order of
+(@code{_pw_byname}), by user ID number (@code{_pw_byuid}), and by order of
occurrence (@code{_pw_bycount}).
The variable @code{_pw_inited} is used for efficiency; @code{_pw_init}
needs only to be called once.
+@cindex @code{getline} command, @code{_pw_init} function
Because this function uses @code{getline} to read information from
@command{pwcat}, it first saves the values of @code{FS}, @code{RS}, and @code{$0}.
It notes in the variable @code{using_fw} whether field splitting
@@ -17250,8 +18179,9 @@ The use of @code{@w{_pw_count}} is explained shortly.
@c NEXT ED: All of these functions don't need the ... in ... test. Just
@c return the array element, which will be "" if not already there. Duh.
+@cindex @code{getpwnam} function (C library)
The @code{getpwnam} function takes a username as a string argument. If that
-user is in the database, it returns the appropriate line. Otherwise it
+user is in the database, it returns the appropriate line. Otherwise, it
returns the null string:
@cindex @code{getpwnam} user-defined function
@@ -17269,9 +18199,10 @@ function getpwnam(name)
@end group
@end example
+@cindex @code{getpwuid} function (C library)
Similarly,
-the @code{getpwuid} function takes a user-id number argument. If that
-user number is in the database, it returns the appropriate line. Otherwise it
+the @code{getpwuid} function takes a user ID number argument. If that
+user number is in the database, it returns the appropriate line. Otherwise, it
returns the null string:
@cindex @code{getpwuid} user-defined function
@@ -17287,6 +18218,7 @@ function getpwuid(uid)
@c endfile
@end example
+@cindex @code{getpwent} function (C library)
The @code{getpwent} function simply steps through the database, one entry at
a time. It uses @code{_pw_count} to track its current position in the
@code{_pw_bycount} array:
@@ -17304,6 +18236,7 @@ function getpwent()
@c endfile
@end example
+@cindex @code{endpwent} function (C library)
The @code{@w{endpwent}} function resets @code{@w{_pw_count}} to zero, so that
subsequent calls to @code{getpwent} start over again:
@@ -17317,7 +18250,7 @@ function endpwent()
@c endfile
@end example
-A conscious design decision in this suite is that each subroutine calls
+A conscious design decision in this suite was made that each subroutine calls
@code{@w{_pw_init}} to initialize the database arrays. The overhead of running
a separate process to generate the user database, and the I/O to scan it,
are only incurred if the user's main program actually calls one of these
@@ -17337,14 +18270,30 @@ clutters up the code.
The @command{id} program in @ref{Id Program, ,Printing out User Information},
uses these functions.
+@c ENDOFRANGE libfudata
+@c ENDOFRANGE flibudata
+@c ENDOFRANGE udatar
+@c ENDOFRANGE dataur
@node Group Functions, , Passwd Functions, Library Functions
@section Reading the Group Database
-@cindex @code{getgrent} C library function
-@cindex group information
+@c STARTOFRANGE libfgdata
+@cindex libraries of @command{awk} functions, group database, reading
+@c STARTOFRANGE flibgdata
+@cindex functions, library, group database, reading
+@c STARTOFRANGE gdatar
+@cindex group database, reading
+@c STARTOFRANGE datagr
+@cindex database, group, reading
+@cindex @code{PROCINFO} array
+@cindex @code{getgrent} function (C library)
+@cindex @code{getgrent} user-defined function
+@c comma is part of primary
+@cindex groups, information about
@cindex account information
@cindex group file
+@cindex files, group
Much of the discussion presented in
@ref{Passwd Functions, ,Reading the User Database},
applies to the group database as well. Although there has traditionally
@@ -17375,6 +18324,14 @@ is as follows:
* Public Domain
*/
+/* For OS/2, do nothing. */
+#if HAVE_CONFIG_H
+#include <config.h>
+#endif
+
+#ifndef HAVE_GETPGRENT
+int main() { exit(0); }
+#else
@c endfile
@end ignore
@c file eg/lib/grcat.c
@@ -17406,6 +18363,11 @@ char **argv;
@}
@c endfile
@end example
+@ignore
+@c file eg/lib/grcat.c
+#endif /* HAVE_GETPGRENT */
+@c endfile
+@end ignore
Each line in the group database represents one group. The fields are
separated with colons and represent the following information:
@@ -17420,14 +18382,14 @@ The encrypted group password. In practice, this field is never used. It is
usually empty or set to @samp{*}.
@item Group ID Number
-The numeric group-id number. This number should be unique within the file.
+The numeric group ID number. This number is unique within the file.
@item Group Member List
A comma-separated list of usernames. These users are members of the group.
Modern Unix systems allow users to be members of several groups
simultaneously. If your system does, then there are elements
@code{"group1"} through @code{"group@var{N}"} in @code{PROCINFO}
-for those group-id numbers.
+for those group ID numbers.
(Note that @code{PROCINFO} is a @command{gawk} extension;
@pxref{Built-in Variables}.)
@end table
@@ -17440,14 +18402,14 @@ for those group-id numbers.
it is usually empty or set to @samp{*}.
@item Group-ID @tab
-The group's numeric group-id number; this number should be unique within the file.
+The group's numeric group ID number; this number should be unique within the file.
@item Group member list @tab
A comma-separated list of usernames. These users are members of the group.
Modern Unix systems allow users to be members of several groups
simultaneously. If your system does, then there are elements
@code{"group1"} through @code{"group@var{N}"} in @code{PROCINFO}
-for those group-id numbers.
+for those group ID numbers.
(Note that @code{PROCINFO} is a @command{gawk} extension;
@pxref{Built-in Variables}.)
@end multitable
@@ -17468,6 +18430,7 @@ $ grcat
Here are the functions for obtaining information from the group database.
There are several, modeled after the C library functions of the same names:
+@cindex @code{getline} command, @code{_gr_init} user-defined function
@cindex @code{_gr_init} user-defined function
@example
@c file eg/lib/groupawk.in
@@ -17550,10 +18513,10 @@ The @code{@w{_gr_init}} function first saves @code{FS}, @code{FIELDWIDTHS}, @cod
scanning the group information.
The group information is stored is several associative arrays.
-The arrays are indexed by group name (@code{@w{_gr_byname}}), by group-id number
+The arrays are indexed by group name (@code{@w{_gr_byname}}), by group ID number
(@code{@w{_gr_bygid}}), and by position in the database (@code{@w{_gr_bycount}}).
There is an additional array indexed by username (@code{@w{_gr_groupsbyuser}}),
-which is a space-separated list of groups that each user belongs to.
+which is a space-separated list of groups to which each user belongs.
Unlike the user database, it is possible to have multiple records in the
database for the same group. This is common when a group has a large number
@@ -17565,7 +18528,7 @@ tvpeople:*:101:david,conan,tom,joan
@end example
For this reason, @code{_gr_init} looks to see if a group name or
-group-id number is already seen. If it is, then the usernames are
+group ID number is already seen. If it is, then the usernames are
simply concatenated onto the previous list of users. (There is actually a
subtle problem with the code just presented. Suppose that
the first time there were no names. This code adds the names with
@@ -17576,6 +18539,7 @@ Finally, @code{_gr_init} closes the pipeline to @command{grcat}, restores
initializes @code{_gr_count} to zero
(it is used later), and makes @code{_gr_inited} nonzero.
+@cindex @code{getgrnam} function (C library)
The @code{getgrnam} function takes a group name as its argument, and if that
group exists, it is returned. Otherwise, @code{getgrnam} returns the null
string:
@@ -17593,8 +18557,9 @@ function getgrnam(group)
@c endfile
@end example
-The @code{getgrgid} function is similar, it takes a numeric group-id and
-looks up the information associated with that group-id:
+@cindex @code{getgrgid} function (C library)
+The @code{getgrgid} function is similar, it takes a numeric group ID and
+looks up the information associated with that group ID:
@cindex @code{getgrgid} user-defined function
@example
@@ -17609,10 +18574,11 @@ function getgrgid(gid)
@c endfile
@end example
+@cindex @code{getgruser} function (C library)
The @code{getgruser} function does not have a C counterpart. It takes a
username and returns the list of groups that have the user as a member:
-@cindex @code{getgruser} user-defined function
+@cindex @code{getgruser} function, user-defined
@example
@c file eg/lib/groupawk.in
function getgruser(user)
@@ -17625,6 +18591,7 @@ function getgruser(user)
@c endfile
@end example
+@cindex @code{getgrent} function (C library)
The @code{getgrent} function steps through the database one entry at a time.
It uses @code{_gr_count} to track its position in the list:
@@ -17640,7 +18607,9 @@ function getgrent()
@}
@c endfile
@end example
+@c ENDOFRANGE clibf
+@cindex @code{endgrent} function (C library)
The @code{endgrent} function resets @code{_gr_count} to zero so that @code{getgrent} can
start over again:
@@ -17665,9 +18634,18 @@ simple, relying on @command{awk}'s associative arrays to do work.
The @command{id} program in @ref{Id Program, ,Printing out User Information},
uses these functions.
+@c ENDOFRANGE libfgdata
+@c ENDOFRANGE flibgdata
+@c ENDOFRANGE gdatar
+@c ENDOFRANGE libf
+@c ENDOFRANGE flib
+@c ENDOFRANGE fudlib
+@c ENDOFRANGE datagr
@node Sample Programs, Language History, Library Functions, Top
@chapter Practical @command{awk} Programs
+@c STARTOFRANGE awkpex
+@cindex @command{awk} programs, examples of
@ref{Library Functions, ,A Library of @command{awk} Functions},
presents the idea that reading programs in a language contributes to
@@ -17732,6 +18710,9 @@ cut.awk -- -c1-8 myfiles > results
@node Clones, Miscellaneous Programs, Running Examples, Sample Programs
@section Reinventing Wheels for Fun and Profit
+@c last comma is part of secondary
+@c STARTOFRANGE posimawk
+@cindex POSIX, programs, implementing in @command{awk}
This @value{SECTION} presents a number of POSIX utilities that are implemented in
@command{awk}. Reinventing these programs in @command{awk} is often enjoyable,
@@ -17759,11 +18740,17 @@ The programs are presented in alphabetical order.
@subsection Cutting out Fields and Columns
@cindex @command{cut} utility
+@c STARTOFRANGE cut
+@cindex @command{cut} utility
+@c STARTOFRANGE ficut
+@cindex fields, cutting
+@c STARTOFRANGE colcut
+@cindex columns, cutting
The @command{cut} utility selects, or ``cuts,'' characters or fields
from its standard input and sends them to its standard output.
Fields are separated by tabs by default,
but you may supply a command-line option to change the field
-@dfn{delimiter} (i.e., the field separator character). @command{cut}'s
+@dfn{delimiter} (i.e., the field-separator character). @command{cut}'s
definition of fields is less general than @command{awk}'s.
A common use of @command{cut} might be to pull out just the login name of
@@ -17787,7 +18774,7 @@ dashes. The list @samp{1-8,15,22-35} specifies characters 1 through
Use @var{list} as the list of fields to cut out.
@item -d @var{delim}
-Use @var{delim} as the field separator character instead of the tab
+Use @var{delim} as the field-separator character instead of the tab
character.
@item -s
@@ -17850,15 +18837,17 @@ page.
screen.
@end ifnottex
+@cindex @code{BEGIN} pattern, running @command{awk} programs and
+@cindex @code{FS} variable, running @command{awk} programs and
Next comes a @code{BEGIN} rule that parses the command-line options.
-It sets @code{FS} to a single tab character, because that is @command{cut}'s
+It sets @code{FS} to a single TAB character, because that is @command{cut}'s
default field separator. The output field separator is also set to be the
same as the input field separator. Then @code{getopt} is used to step
-through the command-line options. One or the other of the variables
+through the command-line options. Exactly one of the variables
@code{by_fields} or @code{by_chars} is set to true, to indicate that
processing should be done by fields or by characters, respectively.
When cutting by characters, the output field separator is set to the null
-string.
+string:
@example
@c file eg/prog/cut.awk
@@ -17895,6 +18884,7 @@ BEGIN \
@c endfile
@end example
+@cindex field separators, spaces as
Special care is taken when the field delimiter is a space. Using
a single space (@code{@w{" "}}) for the value of @code{FS} is
incorrect---@command{awk} would separate fields with runs of spaces,
@@ -17931,7 +18921,7 @@ list of fields or characters:
@c endfile
@end example
-@code{set_fieldlist} is used to split the field list apart at the commas,
+@code{set_fieldlist} is used to split the field list apart at the commas
and into an array. Then, for each element of the array, it looks to
see if it is actually a range, and if so, splits it apart. The range
is verified to make sure the first number is smaller than the second.
@@ -17969,7 +18959,7 @@ function set_fieldlist( n, m, i, j, k, f, g)
The @code{set_charlist} function is more complicated than @code{set_fieldlist}.
The idea here is to use @command{gawk}'s @code{FIELDWIDTHS} variable
(@pxref{Constant Size, ,Reading Fixed-Width Data}),
-which describes constant width input. When using a character list, that is
+which describes constant-width input. When using a character list, that is
exactly what we have.
Setting up @code{FIELDWIDTHS} is more complicated than simply listing the
@@ -18069,12 +19059,21 @@ other @command{awk} implementations to use @code{substr}
it is also extremely painful.
The @code{FIELDWIDTHS} variable supplies an elegant solution to the problem
of picking the input line apart by characters.
+@c ENDOFRANGE cut
+@c ENDOFRANGE ficut
+@c ENDOFRANGE colcut
@c Exercise: Rewrite using split with "".
@node Egrep Program, Id Program, Cut Program, Clones
@subsection Searching for Regular Expressions in Files
+@c STARTOFRANGE regexps
+@cindex regular expressions, searching for
+@c STARTOFRANGE sfregexp
+@cindex searching, files for regular expressions
+@c STARTOFRANGE fsregexp
+@cindex files, searching for regular expressions
@cindex @command{egrep} utility
The @command{egrep} utility searches files for patterns. It uses regular
expressions that are almost identical to those available in @command{awk}
@@ -18175,7 +19174,7 @@ BEGIN @{
@end example
Next comes the code that handles the @command{egrep}-specific behavior. If no
-pattern is supplied with @option{-e}, the first non-option on the
+pattern is supplied with @option{-e}, the first nonoption on the
command line is used. The @command{awk} command-line arguments up to @code{ARGV[Optind]}
are cleared, so that @command{awk} won't try to process them as files. If no
files are specified, the standard input is used, and if multiple files are
@@ -18227,9 +19226,9 @@ commented out since it is not necessary with @command{gawk}:
The @code{beginfile} function is called by the rule in @file{ftrans.awk}
when each new file is processed. In this case, it is very simple; all it
does is initialize a variable @code{fcount} to zero. @code{fcount} tracks
-how many lines in the current file matched the pattern.
-(Naming the parameter @code{junk} shows we know that @code{beginfile}
-is called with a parameter, but that we're not interested in its value.):
+how many lines in the current file matched the pattern
+(naming the parameter @code{junk} shows we know that @code{beginfile}
+is called with a parameter, but that we're not interested in its value):
@example
@c file eg/prog/egrep.awk
@@ -18247,7 +19246,7 @@ matched. @code{no_print} is true only if the exit status is desired.
therefore only prints line counts if printing and counting are enabled.
The output format must be adjusted depending upon the number of files to
process. Finally, @code{fcount} is added to @code{total}, so that we
-know how many lines altogether matched the pattern:
+know the total number of lines that matched the pattern:
@example
@c file eg/prog/egrep.awk
@@ -18272,6 +19271,8 @@ using the @samp{!} operator. @code{fcount} is incremented with the value of
successful or unsuccessful match. If the line does not match, the
@code{next} statement just moves on to the next record.
+@cindex @code{!} (exclamation point), @code{!} operator
+@cindex exclamation point (@code{!}), @code{!} operator
A number of additional tests are made, but they are only done if we
are not counting lines. First, if the user only wants exit status
(@code{no_print} is true), then it is enough to know that @emph{one}
@@ -18313,7 +19314,7 @@ if necessary:
@end example
The @code{END} rule takes care of producing the correct exit status. If
-there are no matches, the exit status is one, otherwise it is zero:
+there are no matches, the exit status is one; otherwise it is zero:
@example
@c file eg/prog/egrep.awk
@@ -18344,7 +19345,9 @@ function usage( e)
The variable @code{e} is used so that the function fits nicely
on the printed page.
-@cindex backslash continuation
+@cindex @code{END} pattern, backslash continuation and
+@cindex @code{\} (backslash), continuing lines and
+@cindex backslash (@code{\}), continuing lines and
Just a note on programming style: you may have noticed that the @code{END}
rule uses backslash continuation, with the open brace on a line by
itself. This is so that it more closely resembles the way functions
@@ -18353,14 +19356,19 @@ in this @value{CHAPTER}
use this style. You can decide for yourself if you like writing
your @code{BEGIN} and @code{END} rules this way
or not.
+@c ENDOFRANGE regexps
+@c ENDOFRANGE sfregexp
+@c ENDOFRANGE fsregexp
@node Id Program, Split Program, Egrep Program, Clones
@subsection Printing out User Information
+@cindex printing, user information
+@cindex users, information about, printing
@cindex @command{id} utility
-The @command{id} utility lists a user's real and effective user-id numbers,
-real and effective group-id numbers, and the user's group set, if any.
-@command{id} only prints the effective user-id and group-id if they are
+The @command{id} utility lists a user's real and effective user ID numbers,
+real and effective group ID numbers, and the user's group set, if any.
+@command{id} only prints the effective user ID and group ID if they are
different from the real ones. If possible, @command{id} also supplies the
corresponding user and group names. The output might look like this:
@@ -18383,10 +19391,10 @@ and the group database library functions
The program is fairly straightforward. All the work is done in the
@code{BEGIN} rule. The user and group ID numbers are obtained from
@code{PROCINFO}.
-The code is repetitive. The entry in the user database for the real user-id
+The code is repetitive. The entry in the user database for the real user ID
number is split into parts at the @samp{:}. The name is the first field.
-Similar code is used for the effective user-id number and the group
-numbers.
+Similar code is used for the effective user ID number and the group
+numbers:
@cindex @code{id.awk} program
@example
@@ -18473,8 +19481,8 @@ BEGIN \
The test in the @code{for} loop is worth noting.
Any supplementary groups in the @code{PROCINFO} array have the
indices @code{"group1"} through @code{"group@var{N}"} for some
-@var{N}; i.e., the total number of supplementary groups.
-The problem is, we don't know in advance how many of these groups
+@var{N}, i.e., the total number of supplementary groups.
+However, we don't know in advance how many of these groups
there are.
This loop works by starting at one, concatenating the value with
@@ -18496,9 +19504,11 @@ arguments and perform in the same way.
@node Split Program, Tee Program, Id Program, Clones
@subsection Splitting a Large File into Pieces
+@c STARTOFRANGE filspl
+@cindex files, splitting
@cindex @code{split} utility
The @code{split} program splits large text files into smaller pieces.
-The usage is as follows:
+Usage is as follows:
@example
split @r{[}-@var{count}@r{]} file @r{[} @var{prefix} @r{]}
@@ -18519,7 +19529,7 @@ Here is a version of @code{split} in @command{awk}. It uses the @code{ord} and
The program first sets its defaults, and then tests to make sure there are
not too many arguments. It then looks at each argument in turn. The
-first argument could be a minus followed by a number. If it is, this happens
+first argument could be a minus sign followed by a number. If it is, this happens
to look like a negative number, so it is made positive, and that is the
count of lines. The data @value{FN} is skipped over and the final argument
is used as the prefix for the output @value{FN}s:
@@ -18629,15 +19639,19 @@ screen.
page.
@end ifnotinfo
-This program is a bit sloppy; it relies on @command{awk} to close the last file
-for it automatically, instead of doing it in an @code{END} rule.
+This program is a bit sloppy; it relies on @command{awk} to automatically close the last file
+instead of doing it in an @code{END} rule.
It also assumes that letters are contiguous in the character set,
which isn't true for EBCDIC systems.
@c BFD...
+@c ENDOFRANGE filspl
@node Tee Program, Uniq Program, Split Program, Clones
@subsection Duplicating Output into Multiple Files
+@c last comma is part of secondary
+@cindex files, multiple, duplicating output into
+@cindex output, duplicating into files
@cindex @code{tee} utility
The @code{tee} program is known as a ``pipe fitting.'' @code{tee} copies
its standard input to its standard output and also duplicates it to the
@@ -18752,8 +19766,13 @@ END \
@end example
@node Uniq Program, Wc Program, Tee Program, Clones
-@subsection Printing Non-Duplicated Lines of Text
+@subsection Printing Nonduplicated Lines of Text
+@c STARTOFRANGE prunt
+@cindex printing, unduplicated lines of text
+@c first comma is part of primary
+@c STARTOFRANGE tpul
+@cindex text, printing, unduplicated lines of
@cindex @command{uniq} utility
The @command{uniq} utility reads sorted lines of data on its standard
input, and by default removes duplicate lines. In other words, it only
@@ -18764,22 +19783,22 @@ options. The usage is as follows:
uniq @r{[}-udc @r{[}-@var{n}@r{]]} @r{[}+@var{n}@r{]} @r{[} @var{input file} @r{[} @var{output file} @r{]]}
@end example
-The option meanings are:
+The options for @command{uniq} are:
@table @code
@item -d
-Only print repeated lines.
+Pnly print only repeated lines.
@item -u
-Only print non-repeated lines.
+Print only nonrepeated lines.
@item -c
Count lines. This option overrides @option{-d} and @option{-u}. Both repeated
-and non-repeated lines are counted.
+and nonrepeated lines are counted.
@item -@var{n}
Skip @var{n} fields before comparing lines. The definition of fields
-is similar to @command{awk}'s default: non-whitespace characters separated
+is similar to @command{awk}'s default: nonwhitespace characters separated
by runs of spaces and/or tabs.
@item +@var{n}
@@ -18813,12 +19832,12 @@ treating such an option as the option letter @samp{2} with an argument of
like a number), @code{Optarg} is
concatenated with the option digit and then the result is added to zero to make
it into a number. If there is only one digit in the option, then
-@code{Optarg} is not needed. @code{Optind} must be decremented so that
+@code{Optarg} is not needed. In this case, @code{Optind} must be decremented so that
@code{getopt} processes it next time. This code is admittedly a bit
tricky.
If no options are supplied, then the default is taken, to print both
-repeated and non-repeated lines. The output file, if provided, is assigned
+repeated and nonrepeated lines. The output file, if provided, is assigned
to @code{outputfile}. Early on, @code{outputfile} is initialized to the
standard output, @file{/dev/stdout}:
@@ -18948,13 +19967,13 @@ executed only for the very first line of data. It sets @code{last} equal to
The second rule does the work. The variable @code{equal} is one or zero,
depending upon the results of @code{are_equal}'s comparison. If @command{uniq}
is counting repeated lines, and the lines are equal, then it increments the @code{count} variable.
-Otherwise it prints the line and resets @code{count},
+Otherwise, it prints the line and resets @code{count},
since the two lines are not equal.
If @command{uniq} is not counting, and if the lines are equal, @code{count} is incremented.
Nothing is printed, since the point is to remove duplicates.
Otherwise, if @command{uniq} is counting repeated lines and more than
-one line is seen, or if @command{uniq} is counting non-repeated lines
+one line is seen, or if @command{uniq} is counting nonrepeated lines
and only one line is seen, then the line is printed, and @code{count}
is reset.
@@ -19002,10 +20021,22 @@ END @{
@}
@c endfile
@end example
+@c ENDOFRANGE prunt
+@c ENDOFRANGE tpul
@node Wc Program, , Uniq Program, Clones
@subsection Counting Things
+@c STARTOFRANGE count
+@cindex counting
+@c STARTOFRANGE infco
+@cindex input files, counting elements in
+@c STARTOFRANGE woco
+@cindex words, counting
+@c STARTOFRANGE chco
+@cindex characters, counting
+@c STARTOFRANGE lico
+@cindex lines, counting
@cindex @command{wc} utility
The @command{wc} (word count) utility counts lines, words, and characters in
one or more input files. Its usage is as follows:
@@ -19020,16 +20051,16 @@ the files. The options and their meanings are shown in the following list:
@table @code
@item -l
-Only count lines.
+Count only lines.
@item -w
-Only count words.
-A ``word'' is a contiguous sequence of non-whitespace characters, separated
-by spaces and/or tabs. Happily, this is the normal way @command{awk} separates
+Count only words.
+A ``word'' is a contiguous sequence of nonwhitespace characters, separated
+by spaces and/or tabs. Luckily, this is the normal way @command{awk} separates
fields in its input data.
@item -c
-Only count characters.
+Count only characters.
@end table
Implementing @command{wc} in @command{awk} is particularly elegant,
@@ -19039,7 +20070,7 @@ and it can easily tell us how long a line is.
This uses the @code{getopt} library function
(@pxref{Getopt Function, ,Processing Command-Line Options})
-and the file transition functions
+and the file-transition functions
(@pxref{Filetrans Function, ,Noting @value{DDF} Boundaries}).
This version has one notable difference from traditional versions of
@@ -19114,9 +20145,16 @@ function beginfile(file)
@end example
The @code{endfile} function adds the current file's numbers to the running
-totals of lines, words, and characters. It then prints out those numbers
+totals of lines, words, and characters.@footnote{@command{wc} can't just use the value of
+@code{FNR} in @code{endfile}. If you examine
+the code in
+@ref{Filetrans Function, , Noting @value{DDF} Boundaries}
+you will see that
+@code{FNR} has already been reset by the time
+@code{endfile} is called.} It then prints out those numbers
for the file that was just read. It relies on @code{beginfile} to reset the
numbers for the following @value{DF}:
+@c ONE DAY: make the above footnote an exercise, instead of giving away the answer.
@c NEXT ED: make order for += be lines, words, chars
@example
@@ -19145,12 +20183,7 @@ is needed because the newline character separating records (the value
of @code{RS}) is not part of the record itself, and thus not included
in its length. Next, @code{lines} is incremented for each line read,
and @code{words} is incremented by the value of @code{NF}, which is the
-number of ``words'' on this line:@footnote{@command{wc} can't just use
-the value of @code{FNR} in @code{endfile}. If you examine the code in
-@ref{Filetrans Function, ,Noting @value{DDF} Boundaries},
-you will see that @code{FNR} has already been reset by the time
-@code{endfile} is called.}
-@c ONE DAY: make the above an exercise, instead of giving away the answer.
+number of ``words'' on this line:
@example
@c file eg/prog/wc.awk
@@ -19163,7 +20196,7 @@ you will see that @code{FNR} has already been reset by the time
@c endfile
@end example
-Finally, the @code{END} rule simply prints the totals for all the files.
+Finally, the @code{END} rule simply prints the totals for all the files:
@example
@c file eg/prog/wc.awk
@@ -19180,6 +20213,12 @@ END @{
@}
@c endfile
@end example
+@c ENDOFRANGE count
+@c ENDOFRANGE infco
+@c ENDOFRANGE lico
+@c ENDOFRANGE woco
+@c ENDOFRANGE chco
+@c ENDOFRANGE posimawk
@node Miscellaneous Programs, , Clones, Sample Programs
@section A Grab Bag of @command{awk} Programs
@@ -19205,9 +20244,14 @@ We hope you find them both interesting and enjoyable.
@node Dupword Program, Alarm Program, Miscellaneous Programs, Miscellaneous Programs
@subsection Finding Duplicated Words in a Document
+@c last comma is part of secondary
+@cindex words, duplicate, searching for
+@cindex searching, for words
+@c first comma is part of primary
+@cindex documents, searching
A common error when writing large amounts of prose is to accidentally
duplicate words. Typically you will see this in text as something like ``the
-the program does the following @dots{}.'' When the text is online, often
+the program does the following@dots{}'' When the text is online, often
the duplicated words occur at the end of one line and the beginning of
another, making them very difficult to spot.
@c as here!
@@ -19220,13 +20264,13 @@ word on the next line.
@cindex Texinfo
The first two statements make sure that the line is all lowercase,
so that, for example, ``The'' and ``the'' compare equal to each other.
-The next statement replaces non-alphanumeric and non-whitespace characters
+The next statement replaces nonalphanumeric and nonwhitespace characters
with spaces, so that punctuation does not affect the comparison either.
The characters are replaced with spaces so that formatting controls
don't create nonsense words (e.g., the Texinfo @samp{@@code@{NF@}}
becomes @samp{codeNF} if punctuation is simply deleted). The record is
-then re-split into fields, yielding just the actual words on the line,
-and insuring that there are no empty fields.
+then resplit into fields, yielding just the actual words on the line,
+and ensuring that there are no empty fields.
If there are no fields left after removing all the punctuation, the
current record is skipped. Otherwise, the program loops through each
@@ -19274,6 +20318,10 @@ word, comparing it to the previous one:
Arnold Robbins
@end quotation
+@c STARTOFRANGE tialarm
+@cindex time, alarm clock example program
+@c STARTOFRANGE alaex
+@cindex alarm clock example program
The following program is a simple ``alarm clock'' program.
You give it a time of day and an optional message. At the specified time,
it prints the message on the standard output. In addition, you can give it
@@ -19287,9 +20335,10 @@ All the work is done in the @code{BEGIN} rule. The first part is argument
checking and setting of defaults: the delay, the count, and the message to
print. If the user supplied a message without the ASCII BEL
character (known as the ``alert'' character, @code{"\a"}), then it is added to
-the message. (On many systems, printing the ASCII BEL generates some sort
-of audible alert. Thus when the alarm goes off, the system calls attention
-to itself in case the user is not looking at their computer or terminal.):
+the message. (On many systems, printing the ASCII BEL generates an
+audible alert. Thus when the alarm goes off, the system calls attention
+to itself in case the user is not looking at the computer or terminal.)
+Here is the program:
@cindex @code{alarm.awk} program
@example
@@ -19415,10 +20464,14 @@ seconds are necessary:
@}
@c endfile
@end example
+@c ENDOFRANGE tialarm
+@c ENDOFRANGE alaex
@node Translate Program, Labels Program, Alarm Program, Miscellaneous Programs
@subsection Transliterating Characters
+@c STARTOFRANGE chtra
+@cindex characters, transliterating
@cindex @command{tr} utility
The system @command{tr} utility transliterates characters. For example, it is
often used to map uppercase letters into lowercase for further processing:
@@ -19429,6 +20482,9 @@ often used to map uppercase letters into lowercase for further processing:
@command{tr} requires two lists of characters.@footnote{On some older
System V systems,
+@ifset ORA
+including Solaris,
+@end ifset
@command{tr} may require that the lists be written as
range expressions enclosed in square brackets (@samp{[a-z]}) and quoted,
to prevent the shell from attempting a @value{FN} expansion. This is
@@ -19458,19 +20514,18 @@ and @code{gsub} built-in functions
program was written before @command{gawk} acquired the ability to
split each character in a string into separate array elements.}
@c Exercise: How might you use this new feature to simplify the program?
-
There are two functions. The first, @code{stranslate}, takes three
arguments:
@table @code
@item from
-A list of characters to translate from.
+A list of characters from which to translate.
@item to
-A list of characters to translate to.
+A list of characters to which to translate.
@item target
-The string to do the translation on.
+The string on which to do the translation.
@end table
Associative arrays make the translation part fairly easy. @code{t_ar} holds
@@ -19562,17 +20617,23 @@ An obvious improvement to this program would be to set up the
@code{t_ar} array only once, in a @code{BEGIN} rule. However, this
assumes that the ``from'' and ``to'' lists
will never change throughout the lifetime of the program.
+@c ENDOFRANGE chtra
@node Labels Program, Word Sorting, Translate Program, Miscellaneous Programs
@subsection Printing Mailing Labels
+@c STARTOFRANGE prml
+@cindex printing, mailing labels
+@c comma is part of primary
+@c STARTOFRANGE mlprint
+@cindex mailing labels, printing
Here is a ``real world''@footnote{``Real world'' is defined as
``a program actually used to get something done.''}
program. This
script reads lists of names and
addresses and generates mailing labels. Each page of labels has 20 labels
-on it, two across and ten down. The addresses are guaranteed to be no more
-than five lines of data. Each address is separated from the next by a blank
+on it, 2 across and 10 down. The addresses are guaranteed to be no more
+than 5 lines of data. Each address is separated from the next by a blank
line.
The basic idea is to read 20 labels worth of data. Each line of each label
@@ -19592,7 +20653,7 @@ have to print horizontally; @code{line[1]} next to @code{line[6]},
accomplish this. The outer loop, controlled by @code{i}, steps through
every 10 lines of data; this is each row of labels. The inner loop,
controlled by @code{j}, goes through the lines within the row.
-As @code{j} goes from 0 to 4, @samp{i+j} is the @code{j}'th line in
+As @code{j} goes from 0 to 4, @samp{i+j} is the @code{j}-th line in
the row, and @samp{i+j+5} is the entry next to it. The output ends up
looking something like this:
@@ -19608,7 +20669,7 @@ line 5 line 10
As a final note, an extra blank line is printed at lines 21 and 61, to keep
the output lined up on the labels. This is dependent on the particular
brand of labels in use when the program was written. You will also note
-that there are two blank lines at the top and two blank lines at the bottom.
+that there are 2 blank lines at the top and 2 blank lines at the bottom.
The @code{END} rule arranges to flush the final page of labels; there may
not have been an even multiple of 20 labels in the data:
@@ -19678,10 +20739,15 @@ END \
@}
@c endfile
@end example
+@c ENDOFRANGE prml
+@c ENDOFRANGE mlprint
@node Word Sorting, History Sorting, Labels Program, Miscellaneous Programs
-@subsection Generating Word Usage Counts
+@subsection Generating Word-Usage Counts
+@c last comma is part of secondary
+@c STARTOFRANGE worus
+@cindex words, usage counts, generating
@c NEXT ED: Rewrite this whole section and example
The following @command{awk} program prints
the number of occurrences of each word in its input. It illustrates the
@@ -19773,7 +20839,7 @@ Assuming we have saved this program in a file named @file{wordfreq.awk},
and that the data is in @file{file1}, the following pipeline:
@example
-awk -f wordfreq.awk file1 | sort +1 -nr
+awk -f wordfreq.awk file1 | sort -k 2nr
@end example
@noindent
@@ -19794,7 +20860,7 @@ the @code{END} action to:
@example
@c file eg/prog/wordfreq.awk
END @{
- sort = "sort +1 -nr"
+ sort = "sort -k 2nr"
for (word in freq)
printf "%s\t%d\n", word, freq[word] | sort
close(sort)
@@ -19806,12 +20872,16 @@ This way of sorting must be used on systems that do not
have true pipes at the command-line (or batch-file) level.
See the general operating system documentation for more information on how
to use the @command{sort} program.
+@c ENDOFRANGE worus
@node History Sorting, Extract Program, Word Sorting, Miscellaneous Programs
@subsection Removing Duplicates from Unsorted Text
+@c last comma is part of secondary
+@c STARTOFRANGE lidu
+@cindex lines, duplicate, removing
The @command{uniq} program
-(@pxref{Uniq Program, ,Printing Non-Duplicated Lines of Text}),
+(@pxref{Uniq Program, ,Printing Nonduplicated Lines of Text}),
removes duplicate lines from @emph{sorted} data.
Suppose, however, you need to remove duplicate lines from a @value{DF} but
@@ -19872,10 +20942,16 @@ print data[lines[i]], lines[i]
This works because @code{data[$0]} is incremented each time a line is
seen.
+@c ENDOFRANGE lidu
@node Extract Program, Simple Sed, History Sorting, Miscellaneous Programs
@subsection Extracting Programs from Texinfo Source Files
+@c STARTOFRANGE texse
+@cindex Texinfo, extracting programs from source files
+@c last comma is part of secondary
+@c STARTOFRANGE fitex
+@cindex files, Texinfo, extracting programs from
@ifnotinfo
Both this chapter and the previous chapter
(@ref{Library Functions, ,A Library of @command{awk} Functions})
@@ -19919,13 +20995,13 @@ files as @samp{@@@@}.
@item
Comments start with either @samp{@@c} or @samp{@@comment}.
-The file extraction program works by using special comments that start
+The file-extraction program works by using special comments that start
at the beginning of a line.
@item
Lines containing @samp{@@group} and @samp{@@end group} commands bracket
example text that should not be split across a page boundary.
-(Unfortunately, @TeX{} isn't always smart enough to do things exactly right
+(Unfortunately, @TeX{} isn't always smart enough to do things exactly right,
and we have to give it some help.)
@end itemize
@@ -20131,13 +21207,15 @@ END @{
@}
@c endfile
@end example
+@c ENDOFRANGE texse
+@c ENDOFRANGE fitex
@node Simple Sed, Igawk Program, Extract Program, Miscellaneous Programs
@subsection A Simple Stream Editor
@cindex @command{sed} utility
-@cindex stream editor
-The @command{sed} utility is a ``stream editor,'' a program that reads a
+@cindex stream editors
+The @command{sed} utility is a stream editor, a program that reads a
stream of data, makes changes to it, and passes it on.
It is often used to make global changes to a large file or to a stream
of data generated by a pipeline of commands.
@@ -20150,7 +21228,7 @@ command1 < orig.data | sed 's/old/new/g' | command2 > result
Here, @samp{s/old/new/g} tells @command{sed} to look for the regexp
@samp{old} on each input line and globally replace it with the text
-@samp{new}, (i.e., all the occurrences on a line). This is similar to
+@samp{new}, i.e., all the occurrences on a line. This is similar to
@command{awk}'s @code{gsub} function
(@pxref{String Functions, ,String Manipulation Functions}).
@@ -20161,8 +21239,8 @@ are provided, the standard input is used:
@cindex Brennan, Michael
@cindex @command{awksed.awk} program
-@cindex simple stream editor
-@cindex stream editor, simple
+@c @cindex simple stream editor
+@c @cindex stream editor, simple
@example
@c file eg/prog/awksed.awk
# awksed.awk --- do s/foo/bar/g using just print
@@ -20249,7 +21327,7 @@ BEGIN {
{ gsub(pat, repl); print }
-Exercise: what are the advantages and disadvantages of this version vs. sed?
+Exercise: what are the advantages and disadvantages of this version versus sed?
Advantage: egrep regexps
speed (?)
Disadvantage: no & in replacement text
@@ -20260,6 +21338,10 @@ Others?
@node Igawk Program, , Simple Sed, Miscellaneous Programs
@subsection An Easy Way to Use Library Functions
+@c STARTOFRANGE libfex
+@cindex libraries of @command{awk} functions, example program for using
+@c STARTOFRANGE flibex
+@cindex functions, library, example program for using
Using library functions in @command{awk} can be very beneficial. It
encourages code reuse and the writing of general functions. Programs are
smaller and therefore clearer.
@@ -20297,7 +21379,7 @@ including the ability to have multiple source files specified via
@option{-f}, and the ability to mix command-line and library source files.
The program is written using the POSIX Shell (@command{sh}) command language.
-The way the program works is as follows:
+It works as follows:
@enumerate
@item
@@ -20315,9 +21397,9 @@ text is just echoed directly. The @command{echo} program automatically
supplies a trailing newline.
@item
-Source @value{FN}s provided with @option{-f}. We use a neat trick and echo
-@samp{@@include @var{filename}} into the temporary file. Since the file
-inclusion program works the way @command{gawk} does, this gets the text
+Source @value{FN}s, provided with @option{-f}. We use a neat trick and echo
+@samp{@@include @var{filename}} into the temporary file. Since the file-inclusion
+program works the way @command{gawk} does, this gets the text
of the file included into the program at the correct point.
@end enumerate
@@ -20372,7 +21454,7 @@ to get the @command{gawk} version information, and then exits.
@end table
If none of the @option{-f}, @option{--file}, @option{-Wfile}, @option{--source},
-or @option{-Wsource} arguments are supplied, then the first non-option argument
+or @option{-Wsource} arguments are supplied, then the first nonoption argument
should be the @command{awk} program. If there are no command-line
arguments left, @command{igawk} prints an error message and exits.
Otherwise, the first argument is echoed into @file{/tmp/ig.s.$$}.
@@ -20381,7 +21463,7 @@ In any case, after the arguments have been processed,
program.
@cindex @command{sed} utility
-@cindex stream editor
+@cindex stream editors
The @samp{$$} in @command{sh} represents the current process ID number.
It is often used in shell programs to generate unique temporary @value{FN}s.
This allows multiple users to run @command{igawk} without worrying
@@ -20641,9 +21723,10 @@ the initial collected @command{awk} program much simpler; all the
@samp{@@include} processing can be done once.
@item
-The @code{pathto} function doesn't try to save the line read with
-@code{getline} when testing for the file's accessibility. Trying to save
-this line for use with the main program complicates things considerably.
+Not trying to save the line read with @code{getline}
+in the @code{pathto} function when testing for the
+file's accessibility for use with the main program simplifies things
+considerably.
@c what problem does this engender though - exercise
@c answer, reading from "-" or /dev/stdin
@@ -20664,10 +21747,12 @@ features to a program; they can often be layered on top. With @command{igawk},
there is no real reason to build @samp{@@include} processing into
@command{gawk} itself.
-@cindex search path
-@cindex directory search
-@cindex path, search
-@cindex search path, for source files
+@cindex search paths, for source files
+@c comma is part of primary
+@cindex source files, search path for
+@c last comma is part of secondary
+@cindex files, source, search path for
+@cindex directories, searching
As an additional example of this, consider the idea of having two
files in a directory in the search path:
@@ -20691,6 +21776,9 @@ upon startup. Instead, it would be very simple to modify @command{igawk}
to do this. Since @command{igawk} can process nested @samp{@@include}
directives, @file{default.awk} could simply contain @samp{@@include}
statements for the desired library functions.
+@c ENDOFRANGE libfex
+@c ENDOFRANGE flibex
+@c ENDOFRANGE awkpex
@c Exercise: make this change
@@ -20741,11 +21829,11 @@ 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 systems
-derived from 4.4BSD--Lite, use various versions of @command{gawk}
+through 4.3-Reno. Subsequent versions of Berkeley Unix, and 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
+evolution of the @command{awk} language, with cross-references to other parts
of the @value{DOCUMENT} where you can find more information.
@menu
@@ -20763,6 +21851,10 @@ of the @value{DOCUMENT} where you can find more information.
@node V7/SVR3.1, SVR4, Language History, Language History
@appendixsec Major Changes Between V7 and SVR3.1
+@c STARTOFRANGE gawkv
+@cindex @command{awk}, versions of
+@c STARTOFRANGE gawkv1
+@cindex @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
@@ -20843,11 +21935,12 @@ Multiple @code{BEGIN} and @code{END} rules
Multidimensional arrays
(@pxref{Multi-dimensional, ,Multidimensional Arrays}).
@end itemize
+@c ENDOFRANGE gawkv1
@node SVR4, POSIX, V7/SVR3.1, Language History
@appendixsec Changes Between SVR3.1 and SVR4
-@cindex @command{awk} language, V.4 version
+@cindex @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}):
@@ -20905,6 +21998,8 @@ Processing of escape sequences inside command-line variable assignments
@node POSIX, BTL, SVR4, Language History
@appendixsec Changes Between SVR4 and POSIX @command{awk}
+@cindex @command{awk}, versions of, changes between SVR4 and POSIX @command{awk}
+@cindex POSIX @command{awk}, changes in @command{awk} versions
The POSIX Command Language and Utilities standard for @command{awk} (1992)
introduced the following changes into the language:
@@ -20957,24 +22052,27 @@ and @ref{Assignment Ops, ,Assignment Expressions}).
@item
Specifying @samp{-Ft} on the command line does not set the value
-of @code{FS} to be a single tab character
+of @code{FS} to be a single TAB character
(@pxref{Field Separators, ,Specifying How Fields Are Separated}).
@item
The @code{fflush} built-in function is not supported
(@pxref{I/O Functions, ,Input/Output Functions}).
@end itemize
+@c ENDOFRANGE gawkv
@node BTL, POSIX/GNU, POSIX, Language History
@appendixsec Extensions in the Bell Laboratories @command{awk}
+@cindex @command{awk}, versions of, See Also Bell Laboratories @command{awk}
@cindex extensions, Bell Laboratories @command{awk}
+@cindex Bell Laboratories @command{awk} extensions
@cindex Kernighan, Brian
Brian Kernighan, one of the original designers of Unix @command{awk},
has made his version available via his home page
(@pxref{Other Versions, ,Other Freely Available @command{awk} Implementations}).
This @value{SECTION} describes extensions in his version of @command{awk} that are
-not in POSIX @command{awk}.
+not in POSIX @command{awk}:
@itemize @bullet
@item
@@ -21051,7 +22149,12 @@ I've tried to follow this general order, esp. for the 3.0 and 3.1 sections:
Within each category, be alphabetical.
@end ignore
-@cindex compatibility mode
+@c STARTOFRANGE fripls
+@cindex compatibility mode (@command{gawk}), extensions
+@c STARTOFRANGE exgnot
+@cindex extensions, in @command{gawk}, not in POSIX @command{awk}
+@c STARTOFRANGE posnot
+@cindex POSIX, @command{gawk} extensions not included in
The GNU implementation, @command{gawk}, adds a large number of features.
This @value{SECTION} lists them in the order they were added to @command{gawk}.
They can all be disabled with either the @option{--traditional} or
@@ -21119,7 +22222,7 @@ through @code{ARGV} (@pxref{Built-in Variables}).
@item
The @code{ERRNO} variable, which contains the system error message when
-@code{getline} returns @minus{}1 or when @code{close} fails
+@code{getline} returns @minus{}1 or @code{close} fails
(@pxref{Built-in Variables}).
@item
@@ -21136,8 +22239,8 @@ The ability to use GNU-style long-named options that start with @option{--}
(@pxref{Options, ,Command-Line Options}).
@item
-The @option{--source} option for mixing command-line and library
-file source code
+The @option{--source} option for mixing command-line and library-file
+source code
(@pxref{Options, ,Command-Line Options}).
@end itemize
@@ -21236,7 +22339,7 @@ and
@item
The ability to use octal and hexadecimal constants in @command{awk}
program source code
-(@pxref{Non-decimal-numbers, ,Octal and Hexadecimal Numbers}).
+(@pxref{Nondecimal-numbers, ,Octal and Hexadecimal Numbers}).
@item
The @samp{|&} operator for two-way I/O to a coprocess
@@ -21309,7 +22412,7 @@ underscore to mark strings that should be translated
@item
The @option{--non-decimal-data} option to allow non-decimal
input data
-(@pxref{Non-decimal Data, ,Allowing Non-Decimal Input Data}).
+(@pxref{Nondecimal Data, ,Allowing Nondecimal Input Data}).
@item
The @option{--profile} option and @command{pgawk}, the
@@ -21350,9 +22453,13 @@ The source code now uses new-style function definitions, with
@c XXX ADD MORE STUFF HERE
+@c ENDOFRANGE fripls
+@c ENDOFRANGE exgnot
+@c ENDOFRANGE posnot
+
@node Contributors, , POSIX/GNU, Language History
@appendixsec Major Contributors to @command{gawk}
-@cindex contributors to @command{gawk}
+@cindex @command{gawk}, list of contributors to
@quotation
@i{Always give credit where credit is due.}@*
Anonymous
@@ -21433,7 +22540,7 @@ provided help in porting @command{gawk} to Cray systems.
@item
@cindex Rommel, Kai Uwe
Kai Uwe Rommel
-provided the port to OS/2 and its documentation.
+provided the initial port to OS/2 and its documentation.
@item
@cindex Jaegermann, Michal
@@ -21501,6 +22608,15 @@ provided the initial version of the @code{asort} function
as well as the code for the new optional third argument to the @code{match} function.
@item
+@cindex Buening, Andreas
+Andreas Buening
+updated the @command{gawk} port for OS/2.
+
+@cindex Hasegawa, Isamu
+Isamu Hasegawa,
+of IBM in Japan, contributed support for multibyte characters.
+
+@item
@cindex Robbins, Arnold
Arnold Robbins
has been working on @command{gawk} since 1988, at first
@@ -21510,8 +22626,12 @@ helping David Trueman, and as the primary maintainer since around 1994.
@node Installation, Notes, Language History, Top
@appendix Installing @command{gawk}
-@cindex Linux
-@cindex GNU/Linux
+@c last two commas are part of see also
+@cindex operating systems, See Also GNU/Linux, PC operating systems, Unix
+@c STARTOFRANGE gligawk
+@cindex @command{gawk}, installing
+@c STARTOFRANGE ingawk
+@cindex 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
@@ -21533,6 +22653,7 @@ the respective ports.
@node Gawk Distribution, Unix Installation, Installation, Installation
@appendixsec The @command{gawk} Distribution
+@cindex source code, @command{gawk}
This @value{SECTION} describes how to get the @command{gawk}
distribution, how to extract it, and then what is in the various files and
@@ -21546,23 +22667,21 @@ subdirectories.
@node Getting, Extracting, Gawk Distribution, Gawk Distribution
@appendixsubsec Getting the @command{gawk} Distribution
-@cindex getting @command{gawk}
-@cindex anonymous @command{ftp}
-@cindex @command{ftp}, anonymous
-@cindex source code, @command{gawk}
-@cindex @command{gawk}, source code
+@c last comma is part of secondary
+@cindex @command{gawk}, source code, obtaining
There are three ways to get GNU software:
@itemize @bullet
@item
Copy it from someone else who already has it.
-@cindex FSF
-@cindex Free Software Foundation
+@cindex FSF (Free Software Foundation)
+@cindex Free Software Foundation (FSF)
@item
Order @command{gawk} directly from the Free Software Foundation.
-Software distributions are available for Unix, MS-DOS, and VMS, on
-tape and CD-ROM. Their address is:
+Software distributions are available for
+Gnu/Linux, Unix, and MS-Windows, in several CD packages.
+Their address is:
@display
Free Software Foundation
@@ -21571,7 +22690,7 @@ Boston, MA 02111-1307 USA
Phone: +1-617-542-5942
Fax (including Japan): +1-617-542-2652
Email: @email{gnu@@gnu.org}
-URL: @uref{http://www.gnu.org/}
+URL: @uref{http://www.gnu.org}
@end display
@noindent
@@ -21580,7 +22699,7 @@ and to the production of more free software.
@item
Retrieve @command{gawk} by using anonymous @command{ftp} to the Internet host
-@code{gnudist.gnu.org}, in the directory @file{/gnu/gawk}.
+@code{ftp.gnu.org}, in the directory @file{/gnu/gawk}.
@end itemize
The GNU software archive is mirrored around the world.
@@ -21617,7 +22736,7 @@ 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 80 denote ``beta'' or non-production software; you might not want
+or equal to 80 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 system, you need to make other arrangements
for getting and extracting the @command{gawk} distribution. You should consult
@@ -21625,6 +22744,8 @@ a local expert.
@node Distribution contents, , Extracting, Gawk Distribution
@appendixsubsec Contents of the @command{gawk} Distribution
+@c STARTOFRANGE gawdis
+@cindex @command{gawk}, distribution
The @command{gawk} distribution has a number of C source files,
documentation files,
@@ -21634,8 +22755,8 @@ as well as several subdirectories related to different non-Unix
operating systems:
@table @asis
-@item Various @samp{.c}, @samp{.y}, and @samp{.h} files:
-These files are the actual @command{gawk} source code.
+@item Various @samp{.c}, @samp{.y}, and @samp{.h} files
+The actual @command{gawk} source code.
@end table
@table @file
@@ -21663,15 +22784,15 @@ on its difficulty.
@item LIMITATIONS
A list of those factors that limit @command{gawk}'s performance.
-Most of these depend on the hardware or operating system software, and
+Most of these depend on the hardware or operating system software and
are not limits in @command{gawk} itself.
@item POSIX.STD
-A description of one area where the POSIX standard for @command{awk} is
+A description of one area in which the POSIX standard for @command{awk} is
incorrect as well as how @command{gawk} handles the problem.
-@cindex artificial intelligence, using @command{gawk}
-@cindex AI programming, using @command{gawk}
+@c comma is part of primary
+@cindex artificial intelligence, @command{gawk} and
@item doc/awkforai.txt
A short article describing why @command{gawk} is a good language for
AI (Artificial Intelligence) programming.
@@ -21797,6 +22918,7 @@ 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.
@end table
+@c ENDOFRANGE gawdis
@node Unix Installation, Non-Unix Installation, Gawk Distribution, Installation
@appendixsec Compiling and Installing @command{gawk} on Unix
@@ -21814,7 +22936,7 @@ to configure @command{gawk} for your system yourself.
@node Quick Installation, Additional Configuration Options, Unix Installation, Unix Installation
@appendixsubsec Compiling @command{gawk} for Unix
-@cindex installation, unix
+@c @cindex installation, unix
After you have extracted the @command{gawk} distribution, @command{cd}
to @file{gawk-@value{VERSION}.@value{PATCHLEVEL}}. Like most GNU software,
@command{gawk} is configured
@@ -21877,15 +22999,18 @@ please send in a bug report
@node Additional Configuration Options, Configuration Philosophy, Quick Installation, Unix Installation
@appendixsubsec Additional Configuration Options
+@cindex @command{gawk}, configuring, options
+@c comma is part of primary
+@cindex configuration options, @command{gawk}
There are several additional options you may use on the @command{configure}
-command line when compiling @command{gawk} from scratch.
+command line when compiling @command{gawk} from scratch, including:
@table @code
@cindex @code{--enable-portals} configuration option
@cindex configuration option, @code{--enable-portals}
@item --enable-portals
-This option causes @command{gawk} to treat pathnames that begin
+Treat pathnames that begin
with @file{/p} as BSD portal files when doing two-way I/O with
the @samp{|&} operator
(@pxref{Portal Files, , Using @command{gawk} with BSD Portals}).
@@ -21893,6 +23018,7 @@ the @samp{|&} operator
@cindex Linux
@cindex GNU/Linux
@cindex @code{--with-included-gettext} configuration option
+@cindex @code{--with-included-gettext} configuration option, configuring @command{gawk} with
@cindex configuration option, @code{--with-included-gettext}
@item --with-included-gettext
Use the version of the @code{gettext} library that comes with @command{gawk}.
@@ -21903,7 +23029,7 @@ All known modern GNU/Linux systems use Glibc 2. Use this option on any other sy
@cindex @code{--disable-nls} configuration option
@cindex configuration option, @code{--disable-nls}
@item --disable-nls
-Disable all message translation facilities.
+Disable all message-translation facilities.
This is usually not desirable, but it may bring you some slight performance
improvement.
You should also use this option if @option{--with-included-gettext}
@@ -21913,7 +23039,7 @@ doesn't work on your system.
@node Configuration Philosophy, , Additional Configuration Options, Unix Installation
@appendixsubsec The Configuration Process
-@cindex configuring @command{gawk}
+@cindex @command{gawk}, configuring
This @value{SECTION} is of interest only if you know something about using the
C language and the Unix operating system.
@@ -21938,7 +23064,7 @@ facts about your variant of Unix. For example, there may not be an
@code{st_blksize} element in the @code{stat} structure. In this case,
@samp{HAVE_ST_BLKSIZE} is undefined.
-@cindex @code{custom.h} configuration file
+@cindex @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}.
@@ -22052,7 +23178,10 @@ If these steps do not work, please send in a bug report
@node PC Installation, VMS Installation, BeOS Installation, Non-Unix Installation
@appendixsubsec Installation on PC Operating Systems
-@cindex installation, pc operating systems
+@c first comma is part of primary
+@cindex PC operating systems, @command{gawk} on, installing
+@c {PC, gawk on} is the secondary term
+@cindex operating systems, PC, @command{gawk} on, installing
This @value{SECTION} covers installation and usage of @command{gawk} on x86 machines
running DOS, any version of Windows, or OS/2.
In this @value{SECTION}, the term ``Win32''
@@ -22071,6 +23200,8 @@ distribution.
and OS/2.
* PC Using:: Running @command{gawk} on MS-DOS, Win32 and
OS/2.
+* Cygwin:: Building and running @command{gawk} for
+ Cygwin.
@end menu
@node PC Binary Installation, PC Compiling, PC Installation, PC Installation
@@ -22088,8 +23219,28 @@ edited.
The binary distribution contains a separate file describing the
contents. In particular, it may include more than one version of the
-@command{gawk} executable. OS/2 binary distributions may have a
-different arrangement, but installation is similar.
+@command{gawk} executable.
+
+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}.
+If you already have a file @file{/usr/info/dir} from another package
+@emph{do not overwrite it!} Instead enter the following commands at your prompt
+(replace @samp{x:} by your installation drive):
+
+@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
+@end example
+
+However, the files can be installed anywhere provided @env{AWKPATH} is
+set properly.
+
+The binary distribution may contain a separate file containing additional
+or more detailed installation instructions.
@node PC Compiling, PC Using, PC Binary Installation, PC Installation
@appendixsubsubsec Compiling @command{gawk} for PC Operating Systems
@@ -22103,11 +23254,11 @@ used to build 16-bit versions for MS-DOS and OS/2. The file
additional notes, and @file{pc/Makefile} contains important information on
compilation options.
-To build @command{gawk}, copy the files in the @file{pc} directory
-(@emph{except} for @file{ChangeLog}) to the directory with the rest of
-the @command{gawk} sources. The @file{Makefile} contains a configuration
-section with comments and may need to be edited in order to work with
-your @command{make} utility.
+To build @command{gawk} for MS-DOS, Win32, and OS/2 (16 bit; for 32 bit (EMX)
+see below), copy the files in the @file{pc} directory (@emph{except} for
+@file{ChangeLog}) to the directory with the rest of the @command{gawk} sources.
+The @file{Makefile} contains a configuration section with comments and may need
+to be edited in order to work with your @command{make} utility.
The @file{Makefile} contains a number of targets for building various MS-DOS,
Win32, and OS/2 versions. A list of targets is printed if the @command{make}
@@ -22125,18 +23276,108 @@ companion utilities or appropriate GNU utilities. However, some editing of
replacement. Details can be found in @file{README_d/README.pc}
and in the file @file{pc/Makefile.tst}.
-@node PC Using, , PC Compiling, PC Installation
-@appendixsubsubsec Using @command{gawk} on PC Operating Systems
+To build @command{gawk} for OS/2 (32 bit, EMX), there are three possibilities:
-@cindex search path
-@cindex directory search
-@cindex path, search
-@cindex search path, for source files
+@enumerate 1
+@item
+Using the @command{configure} script included in the official @command{gawk} distribution.
+@command{configure} need not be recreated but a number of restrictions exist
+when using this choice:
+
+@itemize @bullet
+@item
+An external @code{gettext} library cannot be used. I.e. the @command{configure} option
+@option{--without-included-gettext} does not work. Unfortunately,
+the internal @code{gettext} library is seriuosly broken for OS/2.
+Therefore you have to use @option{--disable-nls}.
+
+@item
+Executables must be linked statically (@code{a.out} format only).
+@samp{make install} does not work.
+
+These restrictions are due to restrictions in Autoconf 2.13 and cannot be
+avoided. They will vanish as soon as @command{gawk} moves on to Autoconf 2.5x.
+Now enter the following commands at your @command{sh} prompt:
+
+@example
+$ CC="gcc"; export CC
+$ CFLAGS="-O2"; export CFLAGS
+$ AWK="awk"; export AWK
+$ LD="ld"; export LD
+$ LDFLAGS="-Zexe"; export LDFLAGS
+$ RANLIB="ranlib"; export RANLIB
+$ ac_cv_header_sys_socket_h="yes"
+$ export ac_cv_header_sys_socket_h
+$ ./configure --prefix=c:/usr --disable-nls
+$ make
+@end example
+@end itemize
+
+@item
+Using a special version of Autoconf 2.13 for OS/2 to recreate @command{configure}.
+Not tested. In principle this should work but the same restrictions
+apply as in 1, but the environment variables @env{CC}, @env{AWK},
+@env{LDFLAGS} and @env{RANLIB} are not necessary.
+
+@item
+Using Autoconf 2.5x to recreate @command{configure} (2.52f or higher recommended).
+Some patches must be applied to @file{Makefile.am} and @file{test/Makefile.am}
+and @file{po/Makefile.in.in}. Currently not supported.
+@end enumerate
+
+@strong{Note:} Even if the compiled @command{gawk.exe} executable contains a DOS header
+(@code{a.out} format), it does @emph{not} work under DOS. To compile an executable
+that runs under DOS, @env{CPPFLAGS} must be set to @code{"-DPIPES_SIMULATED"}.
+But then some nonstandard extensions of @command{gawk} (e.g., @samp{|&}) do not work!
+
+After compilation the internal tests can be performed. Enter
+@samp{make check CMP="diff -a"} at your command prompt. All tests
+but the @code{pid} test are expected to work properly. The @code{pid}
+test might or might not work, no idea why.
+
+@strong{Note:} Most OS/2 ports of GNU @command{make} are not able to handle
+the Makefiles of this package. If you encounter any problems with @command{make}
+try GNU @command{make} 3.79.1. You should find the latest version on
+@uref{ftp://ftp.unixos2.org}.
+
+
+@node PC Using, Cygwin, PC Compiling, PC Installation
+@appendixsubsubsec Using @command{gawk} on PC Operating Systems
+@c STARTOFRANGE opgawx
+@cindex operating systems, PC, @command{gawk} on
+@c STARTOFRANGE pcgawon
+@cindex PC operating systems, @command{gawk} on
+
+With the exception of the Cygwin environment,
+the @samp{|&} operator and TCP/IP networking
+(@pxref{TCP/IP Networking, , Using @command{gawk} for Network Programming})
+are not supported for MS-DOS or MS-Windows. EMX (OS/2 only) does support
+at least the @samp{|&} operator.
+
+@cindex search paths
+@cindex @command{gawk}, OS/2 version of
+@cindex @command{gawk}, MS-DOS version of
+@cindex @code{;} (semicolon), @code{AWKPATH} variable and
+@cindex semicolon (@code{;}), @code{AWKPATH} variable and
+@cindex @code{AWKPATH} environment variable
The OS/2 and MS-DOS versions of @command{gawk} search for program files as
described in @ref{AWKPATH Variable, ,The @env{AWKPATH} Environment 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 is @code{@w{".;c:/lib/awk;c:/gnu/lib/awk"}}.
+then the default search path for OS/2 (16 bit) and MS-DOS versions is
+@code{@w{".;c:/lib/awk;c:/gnu/lib/awk"}}.
+
+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
+@code{@w{".;c:/usr/share/awk;e:/usr/share/awk"}}.
An @command{sh}-like shell (as opposed to @command{command.com} under MS-DOS
or @command{cmd.exe} under OS/2) may be useful for @command{awk} programming.
@@ -22149,11 +23390,12 @@ examine its documentation for handling command lines; in particular,
the setting for @command{gawk} in the shell configuration may need to be
changed and the @code{ignoretype} option may also be of interest.
+@cindex differences in @command{awk} and @command{gawk}, @code{BINMODE} variable
@cindex @code{BINMODE} variable
Under OS/2 and 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 allows
-control over these translations and is interpreted as follows.
+control over these translations and is interpreted as follows:
@itemize @bullet
@item
@@ -22200,7 +23442,7 @@ the setting of @code{RS} giving the fewest ``surprises'' is open to debate.
@command{mawk} uses @samp{RS = "\r\n"} if binary mode is set on read, which is
appropriate for files with the DOS-style end-of-line.
-To Illustrate, the following examples set binary mode on writes for standard
+To illustrate, the following examples set binary mode on writes for standard
output and other files, and set @code{ORS} as the ``usual'' DOS-style
end-of-line:
@@ -22236,6 +23478,32 @@ gawk -f binmode1.awk @dots{}
With proper quoting, in the first example the setting of @code{RS} can be
moved into the @code{BEGIN} rule.
+@node Cygwin, , PC Using, PC Installation
+@appendixsubsubsec Using @command{gawk} In The Cygwin Environment
+
+@command{gawk} can be used ``out of the box'' under Windows if you are
+using the Cygwin environment.@footnote{@uref{http://www.cygwin.com}}
+This environment provides an excellent simulation of Unix, using the
+GNU tools, such as @command{bash}, the GNU Compiler Collection (GCC),
+GNU Make, and other GNU tools. Compilation and installation for Cygwin
+is the same as for a Unix system:
+
+@example
+tar -xvpzf gawk-@value{VERSION}.@value{PATCHLEVEL}.tar.gz
+cd gawk-@value{VERSION}.@value{PATCHLEVEL}
+./configure
+make
+@end example
+
+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.
+
+@strong{Note:} The @samp{|&} operator and TCP/IP networking
+(@pxref{TCP/IP Networking, , Using @command{gawk} for Network Programming})
+are fully supported in the Cygwin environment. This is not true
+for any other environment for MS-DOS or MS-Windows.
+
@node VMS Installation, , PC Installation, Non-Unix Installation
@appendixsubsec How to Compile and Install @command{gawk} on VMS
@@ -22375,10 +23643,10 @@ flag is required to force Unix style 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.
-@cindex search path
-@cindex directory search
-@cindex path, search
-@cindex search path, for source files
+@c @cindex directory search
+@c @cindex path, search
+@cindex search paths
+@cindex 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 @samp{AWKPATH} can be used to override this default. The format
@@ -22589,6 +23857,8 @@ The @samp{-mr @var{val}} option
has been ``stolen'' to enable Tandem users to process fixed-length
records with no ``end-of-line'' character. That is, @samp{-mr 74} tells
@command{gawk} to read the input file as fixed 74-byte records.
+@c ENDOFRANGE opgawx
+@c ENDOFRANGE pcgawon
@node Bugs, Other Versions, Unsupported, Installation
@appendixsec Reporting Problems and Bugs
@@ -22599,10 +23869,10 @@ The Hitchhiker's Guide to the Galaxy
@end quotation
@c the radio show, not the book. :-)
-@cindex bug reports
-@cindex problem reports
-@cindex reporting bugs
-@cindex reporting problems
+@c STARTOFRANGE dbugg
+@cindex debugging @command{gawk}, bug reports
+@c STARTOFRANGE tblgawb
+@cindex 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.
@@ -22621,7 +23891,7 @@ the compiler you used to compile @command{gawk}, and the exact results
us decide whether the problem is really in the documentation.
@cindex @code{bug-gawk@@gnu.org} bug reporting address
-@cindex emaill address for bug reports, @code{bug-gawk@@gnu.org}
+@cindex email address for bug reports, @code{bug-gawk@@gnu.org}
@cindex bug reports, email address, @code{bug-gawk@@gnu.org}
Once you have a precise problem, send email to @email{bug-gawk@@gnu.org}.
@@ -22634,7 +23904,7 @@ mail to me. If necessary, I can be reached directly at
email list is archived at the GNU Project.
@emph{All email should be in English, since that is my native language.}
-@cindex @code{comp.lang.awk} Usenet news group
+@cindex @code{comp.lang.awk} newsgroup
@strong{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,
@@ -22676,9 +23946,8 @@ Darrel Hankerson, @email{hankedr@@mail.auburn.edu}.
@item MS-Windows
Juan Grigera, @email{juan@@biophnet.unlp.edu.ar}.
-@cindex Rommel, Kai Uwe
@item OS/2
-Kai Uwe Rommel, @email{rommel@@ars.de}.
+The Unix for OS/2 team, @email{gawk-maintainer@@unixos2.org}.
@cindex Davies, Stephen
@item Tandem
@@ -22705,8 +23974,7 @@ Darrel Hankerson, @email{hankedr@@mail.auburn.edu}.
@cindex Grigera, Juan
@item MS-Windows @tab Juan Grigera, @email{juan@@biophnet.unlp.edu.ar}.
-@cindex Rommel, Kai Uwe
-@item OS/2 @tab Kai Uwe Rommel, @email{rommel@@ars.de}.
+@item OS/2 @tab The Unix for OS/2 team, @email{gawk-maintainer@@unixos2.org}.
@cindex Davies, Stephen
@item Tandem @tab Stephen Davies, @email{scldad@@sdc.com.au}.
@@ -22717,10 +23985,13 @@ Darrel Hankerson, @email{hankedr@@mail.auburn.edu}.
If your bug is also reproducible under Unix, please send a copy of your
report to the @email{bug-gawk@@gnu.org} email list as well.
+@c ENDOFRANGE dbugg
+@c ENDOFRANGE tblgawb
@node Other Versions, , Bugs, Installation
@appendixsec Other Freely Available @command{awk} Implementations
-@cindex other @command{awk} implementations
+@c STARTOFRANGE awkim
+@cindex @command{awk}, implementations
@ignore
From: emory!amc.com!brennan (Michael Brennan)
Subject: C++ comments in awk programs
@@ -22740,8 +24011,7 @@ This @value{SECTION} briefly describes where to get them:
@table @asis
@cindex Kernighan, Brian
-@cindex Unix @command{awk}, source code
-@cindex source code, Unix @command{awk}
+@cindex source code, Bell Laboratories @command{awk}
@item Unix @command{awk}
Brian Kernighan has made his implementation of
@command{awk} freely available.
@@ -22768,11 +24038,8 @@ works quite nicely.
@xref{BTL, ,Extensions in the Bell Laboratories @command{awk}},
for a list of extensions in this @command{awk} that are not in POSIX @command{awk}.
-@cindex GPL
-@cindex General Public License
-@cindex GNU General Public License
@cindex Brennan, Michael
-@cindex @command{mawk}, source code
+@cindex @command{mawk} program
@cindex source code, @command{mawk}
@item @command{mawk}
Michael Brennan has written an independent implementation of @command{awk},
@@ -22838,8 +24105,7 @@ The @code{BINMODE} special variable for non-Unix operating systems
The next version of @command{mawk} will support @code{nextfile}.
@cindex Sumner, Andrew
-@cindex @command{awka} compiler for @command{awk} programs
-@cindex @command{awka}, source code
+@cindex @command{awka} compiler for @command{awk}
@cindex source code, @command{awka}
@item @command{awka}
Written by Andrew Sumner,
@@ -22848,12 +24114,6 @@ and links them with a library of functions that provides the core
@command{awk} functionality.
It also has a number of extensions.
-@cindex GPL
-@cindex General Public License
-@cindex GNU General Public License
-@cindex LGPL
-@cindex Lesser General Public License
-@cindex GNU Lesser General Public License
The @command{awk} translator is released under the GPL, and the library
is under the LGPL.
@@ -22864,9 +24124,16 @@ Go to @uref{http://awka.sourceforge.net}.
To get @command{awka}, go to @uref{http://awka.sourceforge.net}.
You can reach Andrew Sumner at @email{andrew_sumner@@bigfoot.com}.
@end table
+@c ENDOFRANGE gligawk
+@c ENDOFRANGE ingawk
+@c ENDOFRANGE awkim
@node Notes, Basic Concepts, Installation, Top
@appendix Implementation Notes
+@c STARTOFRANGE gawii
+@cindex @command{gawk}, implementation issues
+@c STARTOFRANGE impis
+@cindex implementation issues, @command{gawk}
This appendix contains information mainly of interest to implementors and
maintainers of @command{gawk}. Everything in it applies specifically to
@@ -22883,6 +24150,11 @@ maintainers of @command{gawk}. Everything in it applies specifically to
@node Compatibility Mode, Additions, Notes, Notes
@appendixsec Downward Compatibility and Debugging
+@cindex @command{gawk}, implementation issues, downward compatibility
+@cindex @command{gawk}, implementation issues, debugging
+@cindex troubleshooting, @command{gawk}
+@c first comma is part of primary
+@cindex implementation issues, @command{gawk}, debugging
@xref{POSIX/GNU, ,Extensions in @command{gawk} Not in POSIX @command{awk}},
for a summary of the GNU extensions to the @command{awk} language and program.
@@ -22895,7 +24167,7 @@ is one more option available on the command line:
@table @code
@item -W parsedebug
@itemx --parsedebug
-Print out the parse stack information as the program is being parsed.
+Prints out the parse stack information as the program is being parsed.
@end table
This option is intended only for serious @command{gawk} developers
@@ -22923,8 +24195,12 @@ as well as any considerations you should bear in mind.
@node Adding Code, New Ports, Additions, Additions
@appendixsubsec Adding New Features
-@cindex adding new features
+@c STARTOFRANGE adfgaw
+@cindex adding, features to @command{gawk}
+@c STARTOFRANGE fadgaw
@cindex features, adding to @command{gawk}
+@c STARTOFRANGE gawadf
+@cindex @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
@@ -22958,11 +24234,10 @@ read it, please do so, preferably @emph{before} starting to modify @command{gawk
the GNU Project's
@command{ftp}
site, at
-@uref{ftp://gnudist.gnu.org/gnu/GNUInfo/standards.text}.
+@uref{ftp://ftp.gnu.org/gnu/GNUInfo/standards.text}.
Texinfo, Info, and DVI versions are also available.)
-@cindex @command{gawk}, coding style
-@cindex coding style used in @command{gawk}
+@cindex @command{gawk}, coding style in
@item
Use the @command{gawk} coding style.
The C code for @command{gawk} follows the instructions in the
@@ -23085,13 +24360,18 @@ 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.
+@c ENDOFRANGE adfgaw
+@c ENDOFRANGE gawadf
+@c ENDOFRANGE fadgaw
@node New Ports, , Adding Code, Additions
@appendixsubsec Porting @command{gawk} to a New Operating System
+@cindex portability, @command{gawk}
+@cindex operating systems, porting @command{gawk} to
@cindex porting @command{gawk}
If you want to port @command{gawk} to a new operating system, there are
-several steps to follow:
+several steps:
@enumerate 1
@item
@@ -23105,15 +24385,12 @@ the previous @value{SECTION}
concerning coding style, submission of diffs, and so on.
@item
-When doing a port, bear in mind that your code must co-exist peacefully
+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.
-@cindex GPL
-@cindex General Public License
-@cindex GNU General Public License
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
@@ -23182,7 +24459,7 @@ already. If you have questions, please contact me, or
@end enumerate
Following these steps makes it much easier to integrate your changes
-into @command{gawk} and have them co-exist happily with other
+into @command{gawk} and have them coexist happily with other
operating systems' code that is already there.
In the code that you supply and maintain, feel free to use a
@@ -23199,8 +24476,12 @@ Warning! Warning!}@*
The Robot
@end quotation
-@cindex Linux
-@cindex GNU/Linux
+@c STARTOFRANGE gladfgaw
+@cindex @command{gawk}, functions, adding
+@c STARTOFRANGE adfugaw
+@cindex adding, functions to @command{gawk}
+@c STARTOFRANGE fubadgaw
+@cindex functions, built-in, adding to @command{gawk}
Beginning with @command{gawk} 3.1, 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
@@ -23222,6 +24503,8 @@ upon the next release.
@node Internals, Sample Library, Dynamic Extensions, Dynamic Extensions
@appendixsubsec A Minimal Introduction to @command{gawk} Internals
+@c STARTOFRANGE gawint
+@cindex @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
@@ -23233,47 +24516,48 @@ are the files @file{awk.h}, @file{builtin.c}, and @file{eval.c}.
Reading @file{awk.y} in order to see how the parse tree is built
would also be of use.
+@cindex @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:
@table @code
+@cindex floating-point, numbers, @code{AWKNUM} internal type
+@cindex numbers, floating-point, @code{AWKNUM} internal type
@cindex @code{AWKNUM} internal type
-@cindex internal type, @code{AWKNUM}
@item AWKNUM
An @code{AWKNUM} is the internal type of @command{awk}
floating-point numbers. Typically, it is a C @code{double}.
@cindex @code{NODE} internal type
-@cindex internal type, @code{NODE}
+@cindex strings, @code{NODE} internal type
+@cindex numbers, @code{NODE} internal type
@item NODE
Just about everything is done using objects of type @code{NODE}.
These contain both strings and numbers, as well as variables and arrays.
@cindex @code{force_number} internal function
-@cindex internal function, @code{force_number}
+@cindex numeric, values
@item 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.
@cindex @code{force_string} internal function
-@cindex internal function, @code{force_string}
@item 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.
+@c comma is part of primary
+@cindex parameters, number of
@cindex @code{param_cnt} internal variable
-@cindex internal variable, @code{param_cnt}
@item n->param_cnt
The number of parameters actually passed in a function call at runtime.
@cindex @code{stptr} internal variable
@cindex @code{stlen} internal variable
-@cindex internal variable, @code{stptr}
-@cindex internal variable, @code{stlen}
@item n->stptr
@itemx n->stlen
The data and length of a @code{NODE}'s string value, respectively.
@@ -23283,26 +24567,24 @@ the value in @code{n->stptr[n->stlen]}, assign @code{'\0'} to it,
call the routine, and then restore the value.
@cindex @code{type} internal variable
-@cindex internal variable, @code{type}
@item n->type
The type of the @code{NODE}. This is a C @code{enum}. Values should
be either @code{Node_var} or @code{Node_var_array} for function
parameters.
@cindex @code{vname} internal variable
-@cindex internal variable, @code{vname}
@item n->vname
The ``variable name'' of a node. This is not of much use inside
externally written extensions.
+@cindex arrays, associative, clearing
@cindex @code{assoc_clear} internal function
-@cindex internal function, @code{assoc_clear}
@item void assoc_clear(NODE *n)
Clears the associative array pointed to by @code{n}.
Make sure that @samp{n->type == Node_var_array} first.
+@cindex arrays, elements, installing
@cindex @code{assoc_lookup} internal function
-@cindex internal function, @code{assoc_lookup}
@item NODE **assoc_lookup(NODE *symbol, NODE *subs, int reference)
Finds, and installs if necessary, array elements.
@code{symbol} is the array, @code{subs} is the subscript.
@@ -23311,15 +24593,15 @@ This is usually a value created with @code{tmp_string} (see below).
value before it is created. Typically, @code{FALSE} is the
correct value to use from extension functions.
+@cindex strings
@cindex @code{make_string} internal function
-@cindex internal function, @code{make_string}
@item 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.
+@cindex numbers
@cindex @code{make_number} internal function
-@cindex internal function, @code{make_number}
@item 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
@@ -23327,34 +24609,32 @@ of @command{gawk} memory management is helpful.
@cindex @code{tmp_string} internal function
@item NODE *tmp_string(char *s, size_t len);
-@cindex internal function, @code{tmp_string}
Take a C string and turn it into a pointer to a @code{NODE} that
can be stored appropriately. This is temporary storage; understanding
of @command{gawk} memory management is helpful.
@cindex @code{tmp_number} internal function
@item NODE *tmp_number(AWKNUM val)
-@cindex internal function, @code{tmp_number}
Take an @code{AWKNUM} and turn it into a pointer to a @code{NODE} that
can be stored appropriately. This is temporary storage;
understanding of @command{gawk} memory management is helpful.
+@c comma is part of primary
+@cindex nodes, duplicating
@cindex @code{dupnode} internal function
-@cindex internal function, @code{dupnode}
@item 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.
+@cindex memory, releasing
@cindex @code{free_temp} internal macro
-@cindex internal macro, @code{free_temp}
@item void free_temp(NODE *n)
This macro releases the memory associated with a @code{NODE}
allocated with @code{tmp_string} or @code{tmp_number}.
Understanding of @command{gawk} memory management is helpful.
@cindex @code{make_builtin} internal function
-@cindex internal function, @code{make_builtin}
@item void make_builtin(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}
@@ -23371,24 +24651,25 @@ do_xxx(NODE *tree)
@}
@end example
+@cindex arguments, retrieving
@cindex @code{get_argument} internal function
-@cindex internal function, @code{get_argument}
@item NODE *get_argument(NODE *tree, int i)
This function is called from within a C extension function to get
-the @code{i}'th argument from the function call.
+the @code{i}-th argument from the function call.
The first argument is argument zero.
+@c last comma is part of secondary
+@cindex functions, return values, setting
@cindex @code{set_value} internal function
@item void set_value(NODE *tree)
-@cindex internal function, @code{set_value}
This function is called from within a C extension function to set
the return value from the extension function. This value is
what the @command{awk} program sees as the return value from the
new @command{awk} function.
+@cindex @code{ERRNO} variable
@cindex @code{update_ERRNO} internal function
@item void update_ERRNO(void)
-@cindex internal function, @code{update_ERRNO}
This function is called from within a C extension function to set
the value of @command{gawk}'s @code{ERRNO} variable, based on the current
value of the C @code{errno} variable.
@@ -23398,7 +24679,7 @@ It is provided as a convenience.
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 ``boiler plate'' code shows how to do this:
+The following boilerplate code shows how to do this:
@smallexample
NODE *the_arg;
@@ -23424,9 +24705,21 @@ assoc_clear(the_arg);
Again, you should spend time studying the @command{gawk} internals;
don't just blindly copy this code.
+@c ENDOFRANGE gawint
@node Sample Library, , Internals, Dynamic Extensions
@appendixsubsec Directory and File Operation Built-ins
+@c comma is part of primary
+@c STARTOFRANGE chdirg
+@cindex @code{chdir} function, implementing in @command{gawk}
+@c comma is part of primary
+@c STARTOFRANGE statg
+@cindex @code{stat} function, implementing in @command{gawk}
+@c last comma is part of secondary
+@c STARTOFRANGE filre
+@cindex files, information about, retrieving
+@c STARTOFRANGE dirch
+@cindex 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
@@ -23586,8 +24879,6 @@ of that number, respectively.
@node Internal File Ops, Using Internal File Ops, Internal File Description, Sample Library
@appendixsubsubsec C Code for @code{chdir} and @code{stat}
-@cindex Linux
-@cindex GNU/Linux
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
@@ -23617,8 +24908,7 @@ 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.
-@cindex conventions, programming
-@cindex programming conventions
+@cindex 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{NODE *} argument, usually called @code{tree}, that
@@ -23763,8 +25053,7 @@ set the return value, and return:
@}
@end example
-@cindex conventions, programming
-@cindex programming conventions
+@cindex 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{dlload} that does the job:
@@ -23789,8 +25078,8 @@ implement system calls such as @code{chown}, @code{chmod}, and @code{umask}.
@node Using Internal File Ops, , Internal File Ops, Sample Library
@appendixsubsubsec Integrating the Extensions
-@cindex Linux
-@cindex GNU/Linux
+@c last comma is part of secondary
+@cindex @command{gawk}, interpreter, 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
@@ -23804,7 +25093,7 @@ $ gcc -shared -DHAVE_CONFIG_H -c -O -g -I@var{idir} filefuncs.c
$ ld -o filefuncs.so -shared filefuncs.o
@end example
-@cindex @code{extension} built-in function
+@cindex @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
@@ -23854,6 +25143,13 @@ $ gawk -f testff.awk
@print{} data["uid"] = 2076
@print{} testff.awk modified: 07 19 99 08:25:36
@end example
+@c ENDOFRANGE filre
+@c ENDOFRANGE dirch
+@c ENDOFRANGE statg
+@c ENDOFRANGE chdirg
+@c ENDOFRANGE gladfgaw
+@c ENDOFRANGE adfugaw
+@c ENDOFRANGE fubadgaw
@node Future Extensions, , Dynamic Extensions, Notes
@appendixsec Probable Future Extensions
@@ -23912,14 +25208,14 @@ Following is a list of probable future changes visible at the
@c these are ordered by likelihood
@table @asis
-@item Loadable Module Interface
+@item 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.
-@item @code{RECLEN} variable for fixed length records
+@item @code{RECLEN} variable for fixed-length records
Along with @code{FIELDWIDTHS}, this would speed up the processing of
fixed-length records.
@code{PROCINFO["RS"]} would be @code{"RS"} or @code{"RECLEN"},
@@ -23938,7 +25234,7 @@ Add @samp{%'d} for putting in commas in formatting numeric values.
@item Databases
It may be possible to map a GDBM/NDBM/SDBM file into an @command{awk} array.
-@item Large Character Sets
+@item Large character sets
It would be nice if @command{gawk} could handle UTF-8 and other
character sets that are larger than eight bits.
@@ -23950,7 +25246,7 @@ Following is a list of probable improvements that will make @command{gawk}'s
source code easier to work with:
@table @asis
-@item Loadable Module Mechanics
+@item Loadable module mechanics
The current extension mechanism works
(@pxref{Dynamic Extensions, ,Adding New Built-in Functions to @command{gawk}}),
but is rather primitive. It requires a fair amount of manual work
@@ -23960,17 +25256,17 @@ The GNU @command{libtool} package provides a number of features that
would make using loadable modules much easier.
@command{gawk} should be changed to use @command{libtool}.
-@item Loadable Module Internals
+@item 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
+@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
stores one copy of the index value.
-@item Integrating the DBUG Library
+@item Integrating the DBUG library
Integrating Fred Fish's DBUG library would be helpful during development,
but it's a lot of work to do.
@end table
@@ -23979,7 +25275,7 @@ Following is a list of probable improvements that will make @command{gawk}
perform better:
@table @asis
-@item An Improved Version of @code{dfa}
+@item An improved version of @code{dfa}
The @code{dfa} pattern matcher from GNU @command{grep} has some
problems. Either a new version or a fixed one will deal with some
important regexp matching issues.
@@ -23997,6 +25293,8 @@ into a C program which the user would then compile, using the normal
C compiler and a special @command{gawk} library to provide all the needed
functions (regexps, fields, associative arrays, type coercion, and so on).
+@c last comma is part of secondary
+@cindex @command{gawk}, interpreter, adding code to
An easier possibility might be for an intermediate phase of @command{gawk} to
convert the parse tree into a linear byte code form like the one used
in GNU Emacs Lisp. The recursive evaluator would then be replaced by
@@ -24010,11 +25308,14 @@ the programs in the test suite could use documenting in this @value{DOCUMENT}.
@xref{Additions, ,Making Additions to @command{gawk}},
if you are interested in tackling any of these projects.
+@c ENDOFRANGE impis
+@c ENDOFRANGE gawii
@node Basic Concepts, Glossary, Notes, Top
@appendix Basic Programming Concepts
-@cindex basic programming concepts
-@cindex programming concepts, basic
+@cindex programming, concepts
+@c STARTOFRANGE procon
+@cindex programming, concepts
This @value{APPENDIX} attempts to define some of the basic concepts
and terms that are used throughout the rest of this @value{DOCUMENT}.
@@ -24104,9 +25405,7 @@ some input data and produce results.
@end ifnottex
@cindex compiled programs
-@cindex programs, compiled
@cindex interpreted programs
-@cindex programs, interpreted
The ``program'' in the figure can be either a compiled
program@footnote{Compiled programs are typically written
in lower-level languages such as C, C++, Fortran, or Ada,
@@ -24257,17 +25556,17 @@ This step corresponds to @command{awk}'s @code{END} rule
After the cake comes out of the oven, you still have to wrap it in
plastic wrap to keep anyone from tasting it, as well as wash
-the mixing bowls and other utensils.
+the mixing bowls and utensils.
@end table
-@cindex algorithm, definition of
+@cindex algorithms
An @dfn{algorithm} is a detailed set of instructions necessary to accomplish
a task, or process data. It is much the same as a recipe for baking
a cake. Programs implement algorithms. Often, it is up to you to design
the algorithm and implement it, simultaneously.
-@cindex record, definition of
-@cindex fields, definition of
+@cindex records
+@cindex fields
The ``logical chunks'' we talked about previously are called @dfn{records},
similar to the records a company keeps on employees, a school keeps for
students, or a doctor keeps for patients.
@@ -24277,12 +25576,13 @@ to as the @dfn{fields} of the record.
The act of reading data is termed @dfn{input}, and that of
generating results, not too surprisingly, is termed @dfn{output}.
-They are often referred to together as ``Input/Output,''
+They are often referred to together as ``input/output,''
and even more often, as ``I/O'' for short.
(You will also see ``input'' and ``output'' used as verbs.)
@cindex data-driven languages
-@cindex language, data-driven
+@c comma is part of primary
+@cindex languages, data-driven
@command{awk} manages the reading of data for you, as well as the
breaking it up into records and fields. Your program's job is to
tell @command{awk} what to with the data. You do this by describing
@@ -24294,12 +25594,12 @@ and easier to read.
@node Basic Data Typing, Floating Point Issues, Basic High Level, Basic Concepts
@appendixsec Data Values in a Computer
-@cindex variable, definition of
+@cindex variables
In a program,
you keep track of information and values in things called @dfn{variables}.
A variable is just a name for a given value, such as @code{first_name},
@code{last_name}, @code{address}, and so on.
-@command{awk} has several pre-defined variables, and it has
+@command{awk} has several predefined variables, and it has
special names to refer to the current input record
and the fields of the record.
You may also group multiple
@@ -24307,7 +25607,7 @@ associated values under one name, as an array.
@cindex values, numeric
@cindex values, string
-@cindex scalar, definition of
+@cindex scalar values
Data, particularly in @command{awk}, consists of either numeric
values, such as 42 or 3.1415927, or string values.
String values are essentially anything that's not a number, such as a name.
@@ -24317,9 +25617,10 @@ Individual variables, as well as numeric and string variables, are
referred to as @dfn{scalar} values.
Groups of values, such as arrays, are not scalars.
-@cindex integer, definition of
-@cindex floating-point, definition of
-Within computers, there are two kinds of numeric values: @dfn{integers},
+@cindex integers
+@cindex floating-point, numbers
+@cindex numbers, floating-point
+Within computers, there are two kinds of numeric values: @dfn{integers}
and @dfn{floating-point}.
In school, integer values were referred to as ``whole'' numbers---that is,
numbers without any fractional part, such as 1, 42, or @minus{}17.
@@ -24328,15 +25629,15 @@ The disadvantage is that their range is limited. On most modern systems,
this range is @minus{}2,147,483,648 to 2,147,483,647.
@cindex unsigned integers
-@cindex integer, unsigned
+@cindex integers, unsigned
Integer values come in two flavors: @dfn{signed} and @dfn{unsigned}.
Signed values may be negative or positive, with the range of values just
described.
Unsigned values are always positive. On most modern systems,
the range is from 0 to 4,294,967,295.
-@cindex double-precision floating-point, definition of
-@cindex single-precision floating-point, definition of
+@cindex double-precision floating-point
+@cindex single-precision floating-point
Floating-point numbers represent what are called ``real'' numbers; i.e.,
those that do have a fractional part, such as 3.1415927.
The advantage to floating-point numbers is that they
@@ -24354,8 +25655,7 @@ or @dfn{bits}. Modern computers group bits into groups of eight, called @dfn{by
Advanced applications sometimes have to manipulate bits directly,
and @command{gawk} provides functions for doing so.
-@cindex null string, definition of
-@cindex empty string, definition of
+@cindex null strings
While you are probably used to the idea of a number without a value (i.e., zero),
it takes a bit more getting used to the idea of zero-length character data.
Nevertheless, such a thing exists.
@@ -24375,7 +25675,7 @@ its right. Each column may contain either a 0 or a 1.
Thus, binary 1010 represents 1 times 8, plus 0 times 4, plus 1 times 2,
plus 0 times 1, or decimal 10.
Octal and hexadecimal are discussed more in
-@ref{Non-decimal-numbers, ,Octal and Hexadecimal Numbers}.
+@ref{Nondecimal-numbers, ,Octal and Hexadecimal Numbers}.
Programs are written in programming languages.
Hundreds, if not thousands, of programming languages exist.
@@ -24390,7 +25690,7 @@ as ``K&R'' C, after the initials of Brian Kernighan and Dennis Ritchie,
the authors of the first book on C. (Dennis Ritchie created the language,
and Brian Kernighan was one of the creators of @command{awk}.)
-In the mid-1980's, an effort began to produce an international standard
+In the mid-1980s, an effort began to produce an international standard
for C. This work culminated in 1989, with the production of the ANSI
standard for C. This standard became an ISO standard in 1990.
Where it makes sense, POSIX @command{awk} is compatible with 1990 ISO C.
@@ -24403,18 +25703,18 @@ with this standard.
@appendixsec Floating-Point Number Caveats
As mentioned earlier, floating-point numbers represent what are called
-``real'' numbers; i.e., those that have a fractional part. @command{awk}
+``real'' numbers, i.e., those that have a fractional part. @command{awk}
uses double-precision floating-point numbers to represent all
numeric values. This @value{SECTION} describes some of the issues
involved in using floating-point numbers.
There is a very nice paper on floating-point arithmetic by
-David Goldberg, @cite{What Every
-Computer Scientist Should Know About Floating-point Arithmetic},
+David Goldberg, ``What Every
+Computer Scientist Should Know About Floating-point Arithmetic,''
@cite{ACM Computing Surveys} @strong{23}, 1 (1991-03),
-5-48.@footnote{@uref{http://www.validgh.com/goldberg/paper.ps}}
+5-48.@footnote{@uref{http://www.validgh.com/goldberg/paper.ps}.}
This is worth reading if you are interested in the details,
-but it does require a background in Computer Science.
+but it does require a background in computer science.
Internally, @command{awk} keeps both the numeric value
(double-precision floating-point) and the string value for a variable.
@@ -24469,7 +25769,7 @@ On most modern machines, most of the time,
value exactly.@footnote{Pathological cases can require up to
752 digits (!), but we doubt that you need to worry about this.}
-@cindex floating-point, precision issues
+@cindex floating-point
Unlike numbers in the abstract sense (such as what you studied in high school
or college math), numbers stored in computers are limited in certain ways.
They cannot represent an infinite number of digits, nor can they always
@@ -24488,7 +25788,7 @@ $ awk '@{ printf("%010d\n", $1 * 100) @}'
@print{} 0000051580
515.82
@print{} 0000051582
-@kbd{Ctrl-d}
+@kbd{@value{CTL}-d}
@end example
@noindent
@@ -24499,8 +25799,8 @@ represent numbers.
@cindex negative zero
@cindex positive zero
+@c comma is part of primary
@cindex zero, negative vs.@: positive
-@cindex floating-point, positive and negative values for zero
Another peculiarity of floating-point numbers on modern systems
is that they often have more than one representation for the number zero!
In particular, it is possible to represent ``minus zero'' as well as
@@ -24522,6 +25822,7 @@ $ gawk 'BEGIN @{ mz = -0 ; pz = 0
It helps to keep this in mind should you process numeric data
that contains negative zero values; the fact that the zero is negative
is noted and can affect comparisons.
+@c ENDOFRANGE procon
@node Glossary, Copying, Basic Concepts, Top
@unnumbered Glossary
@@ -24815,7 +26116,7 @@ The epoch on Unix and POSIX systems is 1970-01-01 00:00:00 UTC.
See also ``GMT'' and ``UTC.''
@item Escape Sequences
-A special sequence of characters used for describing non-printing
+A special sequence of characters used for describing nonprinting
characters, such as @samp{\n} for newline or @samp{\033} for the ASCII
ESC (Escape) character. (@xref{Escape Sequences}.)
@@ -24833,7 +26134,7 @@ and
@ref{Constant Size, ,Reading Fixed-Width Data}.)
@item Flag
-A variable whose truth value indicates the existence or non-existence
+A variable whose truth value indicates the existence or nonexistence
of some condition.
@item Floating-Point Number
@@ -24861,11 +26162,11 @@ functions, and also allows you to define your own.
@item FSF
See ``Free Software Foundation.''
-@cindex FSF
-@cindex Free Software Foundation
+@cindex FSF (Free Software Foundation)
+@cindex Free Software Foundation (FSF)
@cindex Stallman, Richard
@item Free Software Foundation
-A non-profit organization dedicated
+A nonprofit organization dedicated
to the production and distribution of freely distributable software.
It was founded by Richard M.@: Stallman, the author of the original
Emacs editor. GNU Emacs is the most widely used version of Emacs today.
@@ -24873,8 +26174,8 @@ Emacs editor. GNU Emacs is the most widely used version of Emacs today.
@item @command{gawk}
The GNU implementation of @command{awk}.
-@cindex GPL
-@cindex General Public License
+@cindex GPL (General Public License)
+@cindex General Public License (GPL)
@cindex GNU General Public License
@item General Public License
This document describes the terms under which @command{gawk} and its source
@@ -24886,8 +26187,8 @@ This is the old term for UTC.
It is the time of day used as the epoch for Unix and POSIX systems.
See also ``Epoch'' and ``UTC.''
-@cindex FSF
-@cindex Free Software Foundation
+@cindex FSF (Free Software Foundation)
+@cindex Free Software Foundation (FSF)
@cindex GNU Project
@item GNU
``GNU's not Unix''. An on-going project of the Free Software Foundation
@@ -24975,8 +26276,8 @@ meaning. Keywords are reserved and may not be used as variable names.
and
@code{exit}.
-@cindex LGPL
-@cindex Lesser General Public License
+@cindex LGPL (Lesser General Public License)
+@cindex Lesser General Public License (LGPL)
@cindex GNU Lesser General Public License
@item Lesser General Public License
This document describes the terms under which binary library archives
@@ -25209,7 +26510,7 @@ reference time for day and date calculations.
See also ``Epoch'' and ``GMT.''
@item Whitespace
-A sequence of space, tab, or newline characters occurring inside an input
+A sequence of space, TAB, or newline characters occurring inside an input
record or a string.
@end table
@@ -25617,8 +26918,8 @@ Public License instead of this License.
@node GNU Free Documentation License, Index, Copying, Top
@unnumbered GNU Free Documentation License
@center Version 1.1, March 2000
-@cindex FDL
-@cindex Free Documentation License
+@cindex FDL (Free Documentation License)
+@cindex Free Documentation License (FDL)
@cindex GNU Free Documentation License
@display
@@ -26037,7 +27338,7 @@ Consistency issues:
no @print before @dots
values of expressions in the text (@code{x} has the value 15),
should be in roman, not @code
- Use tab and not TAB
+ Use TAB and not tab
Use ESC and not ESCAPE
Use space and not blank to describe the space bar's character
The term "blank" is thus basically reserved for "blank lines" etc.
@@ -26045,7 +27346,7 @@ Consistency issues:
closing `.' of a sentence and after (pxref{...}). This is
a change from earlier versions.
" " should have an @w{} around it
- Use "non-" everywhere
+ Use "non-" only with language names or acronyms, or the words bug and option
Use @command{ftp} when talking about anonymous ftp
Use uppercase and lowercase, not "upper-case" and "lower-case"
or "upper case" and "lower case"
@@ -26067,6 +27368,7 @@ Consistency issues:
Use "startup"/"cleanup", not "start-up"/"clean-up"
Use @code{do}, and not @code{do}-@code{while}, except where
actually discussing the do-while.
+ Use "versus" in text and "vs." in index entries
The words "a", "and", "as", "between", "for", "from", "in", "of",
"on", "that", "the", "to", "with", and "without",
should not be capitalized in @chapter, @section etc.
diff --git a/doc/gawkinet.info b/doc/gawkinet.info
index 3d5e5d3f..3c1f9722 100644
--- a/doc/gawkinet.info
+++ b/doc/gawkinet.info
@@ -1,4 +1,4 @@
-This is gawkinet.info, produced by makeinfo version 4.0 from
+This is gawkinet.info, produced by makeinfo version 4.2 from
gawkinet.texi.
INFO-DIR-SECTION GNU Packages
@@ -6,12 +6,12 @@ START-INFO-DIR-ENTRY
* Gawkinet: (gawkinet). TCP/IP Internetworking With `gawk'.
END-INFO-DIR-ENTRY
- This file documents the networking features in GNU `awk'.
+This is Edition 1.1 of `TCP/IP Internetworking With `gawk'', for the
+3.1.1 (or later) version of the GNU implementation of AWK.
+
- This is Edition 1.1 of `TCP/IP Internetworking With `gawk'', for the
-3.1.0 (or later) version of the GNU implementation of AWK.
+ Copyright (C) 2000, 2001, 2002 Free Software Foundation, Inc.
- Copyright (C) 2000, 2001 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
@@ -26,7 +26,30 @@ texts being (a) (see below), and with the Back-Cover Texts being (b)
b. "You have freedom to copy and modify this GNU Manual, like GNU
software. Copies published by the Free Software Foundation raise
funds for GNU development."
+
+ This file documents the networking features in GNU `awk'.
+
+This is Edition 1.1 of `TCP/IP Internetworking With `gawk'', for the
+3.1.1 (or later) version of the GNU implementation of AWK.
+
+
+ Copyright (C) 2000, 2001, 2002 Free Software Foundation, Inc.
+
+
+ Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being "GNU General Public License", the Front-Cover
+texts being (a) (see below), and with the Back-Cover Texts being (b)
+(see below). A copy of the license is included in the section entitled
+"GNU Free Documentation License".
+
+ a. "A GNU Manual"
+ b. "You have freedom to copy and modify this GNU Manual, like GNU
+ software. Copies published by the Free Software Foundation raise
+ funds for GNU development."
+

File: gawkinet.info, Node: Top, Next: Preface, Prev: (dir), Up: (dir)
@@ -36,6 +59,27 @@ General Introduction
This file documents the networking features in GNU Awk (`gawk')
version 3.1 and later.
+This is Edition 1.1 of `TCP/IP Internetworking With `gawk'', for the
+3.1.1 (or later) version of the GNU implementation of AWK.
+
+
+ Copyright (C) 2000, 2001, 2002 Free Software Foundation, Inc.
+
+
+ Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being "GNU General Public License", the Front-Cover
+texts being (a) (see below), and with the Back-Cover Texts being (b)
+(see below). A copy of the license is included in the section entitled
+"GNU Free Documentation License".
+
+ a. "A GNU Manual"
+
+ b. "You have freedom to copy and modify this GNU Manual, like GNU
+ software. Copies published by the Free Software Foundation raise
+ funds for GNU development."
+
* Menu:
* Preface:: About this document.
@@ -57,7 +101,7 @@ version 3.1 and later.
* Special File Fields:: The fields in the special file name.
* Comparing Protocols:: Differences between the protocols.
* File /inet/tcp:: The TCP special file.
-* File /inet/udp:: The UDB special file.
+* File /inet/udp:: The UDP special file.
* File /inet/raw:: The RAW special file.
* TCP Connecting:: Making a TCP connection.
* Troubleshooting:: Troubleshooting TCP/IP connections.
@@ -378,12 +422,13 @@ This can be done with file-like handling of network connections.
family of protocols for the convenience of simple connection handling.
The advanced features are available when programming in C or Perl. In
fact, the network programming in this major node is very similar to
-what is described in books like `Internet Programming with Python',
+what is described in books such as `Internet Programming with Python',
`Advanced Perl Programming', or `Web Client Programming with Perl'.
-But it's done here without first having to learn object-oriented
-ideology, underlying languages such as Tcl/Tk, Perl, Python, or all of
-the libraries necessary to extend these languages before they are ready
-for the Internet.
+
+ However, you can do the programming here without first having to
+learn object-oriented ideology; underlying languages such as Tcl/Tk,
+Perl, Python; or all of the libraries necessary to extend these
+languages before they are ready for the Internet.
This major node demonstrates how to use the TCP protocol. The other
protocols are much less important for most users (UDP) or even
@@ -407,23 +452,23 @@ untractable (RAW).

File: gawkinet.info, Node: Gawk Special Files, Next: TCP Connecting, Prev: Using Networking, Up: Using Networking
-`gawk' Networking Mechanisms
-============================
+`gawk''s Networking Mechanisms
+==============================
The `|&' operator introduced in `gawk' 3.1 for use in communicating
-with a "co-process" is described in *Note Two-way Communications With
+with a "coprocess" is described in *Note Two-way Communications With
Another Process: (gawk)Two-way I/O. It shows how to do two-way I/O to a
separate process, sending it data with `print' or `printf' and reading
data with `getline'. If you haven't read it already, you should detour
there to do so.
`gawk' transparently extends the two-way I/O mechanism to simple
-networking through the use of special file names. When a "co-process"
-is started that matches the special files we are about to describe,
+networking through the use of special file names. When a "coprocess"
+that matches the special files we are about to describe is started,
`gawk' creates the appropriate network connection, and then two-way I/O
proceeds as usual.
- At the C, C++ (and basic Perl) level, networking is accomplished via
+ At the C, C++, and Perl level, networking is accomplished via
"sockets", an Application Programming Interface (API) originally
developed at the University of California at Berkeley that is now used
almost universally for TCP/IP networking. Socket level programming,
@@ -434,7 +479,7 @@ from a high-level language like `awk'. The special files provided in
and easier to use.
The special file name for network access is made up of several
-fields, all of them mandatory, none of them optional:
+fields, all of which are mandatory:
/inet/PROTOCOL/LOCALPORT/HOSTNAME/REMOTEPORT
@@ -457,7 +502,7 @@ The Fields of the Special File Name
This node explains the meaning of all the other fields, as well as
the range of values and the defaults. All of the fields are mandatory.
To let the system pick a value, or if the field doesn't apply to the
-protocol, specify it as `0'.
+protocol, specify it as `0':
PROTOCOL
Determines which member of the TCP/IP family of protocols is
@@ -468,34 +513,34 @@ PROTOCOL
LOCALPORT
Determines which port on the local machine is used to communicate
across the network. It has no meaning with `/inet/raw' and must
- therefore be `0'. Application level clients usually use `0' to
+ therefore be `0'. Application-level clients usually use `0' to
indicate they do not care which local port is used--instead they
- specify a remote port to connect to. It is vital for application
- level servers to use a number different from `0' here because
- their service has to be available at a specific publicly-known
- port number. It is possible to use a name from `/etc/services'
- here.
+ specify a remote port to connect to. It is vital for
+ application-level servers to use a number different from `0' here
+ because their service has to be available at a specific publicly
+ known port number. It is possible to use a name from
+ `/etc/services' here.
HOSTNAME
Determines which remote host is to be at the other end of the
- connection. Application level servers must fill this field with a
+ connection. Application-level servers must fill this field with a
`0' to indicate their being open for all other hosts to connect to
them and enforce connection level server behavior this way. It is
- not possible for an application level server to restrict its
+ not possible for an application-level server to restrict its
availability to one remote host by entering a host name here.
- Application level clients must enter a name different from `0'.
+ Application-level clients must enter a name different from `0'.
The name can be either symbolic (e.g., `jpl-devvax.jpl.nasa.gov')
or numeric (e.g., `128.149.1.143').
REMOTEPORT
Determines which port on the remote machine is used to communicate
across the network. It has no meaning with `/inet/raw' and must
- therefore be 0. For `/inet/tcp' and `/inet/udp', application
- level clients _must_ use a number other than `0' to indicate which
- port on the remote machine they want to connect to. Application
- level servers must not fill this field with a `0'. Instead they
- specify a local port for clients to connect to. It is possible to
- use a name from `/etc/services' here.
+ therefore be 0. For `/inet/tcp' and `/inet/udp',
+ application-level clients _must_ use a number other than `0' to
+ indicate to which port on the remote machine they want to connect.
+ Application-level servers must not fill this field with a `0'.
+ Instead they specify a local port to which clients connect. It is
+ possible to use a name from `/etc/services' here.
Experts in network programming will notice that the usual
client/server asymmetry found at the level of the socket API is not
@@ -503,7 +548,7 @@ visible here. This is for the sake of simplicity of the high-level
concept. If this asymmetry is necessary for your application, use
another language. For `gawk', it is more important to enable users to
write a client program with a minimum of code. What happens when first
-accessing a network connection is seen in the following pseudo-code:
+accessing a network connection is seen in the following pseudocode:
if ((name of remote host given) && (other side accepts connection)) {
rendez-vous successful; transmit with getline or print
@@ -524,7 +569,7 @@ is too complicated, focus on the three lines printed in *bold*. All the
examples in *Note Networking With `gawk': Using Networking, use only the
patterns printed in bold letters.
-PROTOCOL LOCAL HOST REMOTE RESULTING CONNECTION LEVEL
+PROTOCOL LOCAL HOST REMOTE RESULTING CONNECTION-LEVEL
PORT NAME PORT BEHAVIOR
*tcp* *0* *x* *x* *Dedicated client, fails
if immediately connecting
@@ -566,7 +611,7 @@ available and demonstrate the differences between them.
* Menu:
* File /inet/tcp:: The TCP special file.
-* File /inet/udp:: The UDB special file.
+* File /inet/udp:: The UDP special file.
* File /inet/raw:: The RAW special file.

@@ -575,7 +620,7 @@ File: gawkinet.info, Node: File /inet/tcp, Next: File /inet/udp, Prev: Compar
`/inet/tcp'
...........
- Once again, always use TCP. (Use UDP when low-overhead is a
+ Once again, always use TCP. (Use UDP when low overhead is a
necessity, and use RAW for network experimentation.) The first example
is the sender program:
@@ -642,7 +687,7 @@ File: gawkinet.info, Node: File /inet/raw, Prev: File /inet/udp, Up: Comparin
This is an IP-level protocol. Only `root' is allowed to access this
special file. It is meant to be the basis for implementing and
-experimenting with transport level protocols.(1) In the most general
+experimenting with transport-level protocols.(1) In the most general
case, the sender has to supply the encapsulating header bytes in front
of the packet and the receiver has to strip the additional bytes from
the message.
@@ -711,7 +756,7 @@ Establishing a TCP Connection
Let's observe a network connection at work. Type in the following
program and watch the output. Within a second, it connects via TCP
-(`/inet/tcp') to the machine it is running on (`localhost'), and asks
+(`/inet/tcp') to the machine it is running on (`localhost') and asks
the service `daytime' on the machine what time it is:
BEGIN {
@@ -753,7 +798,7 @@ line from the special file `/inet/tcp/0/localhost/daytime'. We could
also have printed a line into the special file. But instead we just
read a line with the time, printed it, and closed the connection.
(While we could just let `gawk' close the connection by finishing the
-program, in this Info file we are pedantic, and always explicitly close
+program, in this Info file we are pedantic and always explicitly close
the connections.)

@@ -762,24 +807,24 @@ File: gawkinet.info, Node: Troubleshooting, Next: Interacting, Prev: TCP Conn
Troubleshooting Connection Problems
===================================
- It may well be that for some reason the above program does not run
-on your machine. When looking at possible reasons for this, you will
-learn much about typical problems that arise in network programming.
-First of all, your implementation of `gawk' may not support network
-access because it is a pre-3.1 version or you do not have a network
-interface in your machine. Perhaps your machine uses some other
-protocol like DECnet or Novell's IPX. For the rest of this major node,
-we will assume you work on a Unix machine that supports TCP/IP. If the
-above program does not run on such a machine, it may help to replace
-the name `localhost' with the name of your machine or its IP address.
-If it does, you could replace `localhost' with the name of another
-machine in your vicinity. This way, the program connects to another
-machine. Now you should see the date and time being printed by the
-program. Otherwise your machine may not support the `daytime' service.
-Try changing the service to `chargen' or `ftp'. This way, the program
-connects to other services that should give you some response. If you
-are curious, you should have a look at your file `/etc/services'. It
-could look like this:
+ It may well be that for some reason the program shown in the
+previous example does not run on your machine. When looking at possible
+reasons for this, you will learn much about typical problems that arise
+in network programming. First of all, your implementation of `gawk' may
+not support network access because it is a pre-3.1 version or you do
+not have a network interface in your machine. Perhaps your machine
+uses some other protocol, such as DECnet or Novell's IPX. For the rest
+of this major node, we will assume you work on a Unix machine that
+supports TCP/IP. If the previous example program does not run on your
+machine, it may help to replace the name `localhost' with the name of
+your machine or its IP address. If it does, you could replace
+`localhost' with the name of another machine in your vicinity--this
+way, the program connects to another machine. Now you should see the
+date and time being printed by the program, otherwise your machine may
+not support the `daytime' service. Try changing the service to
+`chargen' or `ftp'. This way, the program connects to other services
+that should give you some response. If you are curious, you should have
+a look at your `/etc/services' file. It could look like this:
# /etc/services:
#
@@ -813,13 +858,13 @@ could look like this:
Here, you find a list of services that traditional Unix machines
usually support. If your GNU/Linux machine does not do so, it may be
that these services are switched off in some startup script. Systems
-running some flavor of Microsoft Windows usually do _not_ support such
+running some flavor of Microsoft Windows usually do _not_ support these
services. Nevertheless, it _is_ possible to do networking with `gawk'
on Microsoft Windows.(1) The first column of the file gives the name of
-the service, the second a unique number, and the protocol that one can
-use to connect to this service. The rest of the line is treated as a
-comment. You see that some services (`echo') support TCP as well as
-UDP.
+the service, and the second column gives a unique number and the
+protocol that one can use to connect to this service. The rest of the
+line is treated as a comment. You see that some services (`echo')
+support TCP as well as UDP.
---------- Footnotes ----------
@@ -857,7 +902,7 @@ program repeatedly reads lines that come as a reply. When no more lines
are coming (because the service has closed the connection), the program
also closes the connection. Try replacing `"NAME"' with your login name
(or the name of someone else logged in). For a list of all users
-currently logged in, replace NAME with an empty string `""'.
+currently logged in, replace NAME with an empty string (`""').
The final `close' command could be safely deleted from the above
script, because the operating system closes any open connection by
@@ -897,7 +942,7 @@ Setting Up a Service
somewhere on the Internet and request a particular service. Now we set
up such a service to mimic the behavior of the `daytime' service. Such
a server does not know in advance who is going to connect to it over
-the network. Therefore we cannot insert a name for the host to connect
+the network. Therefore, we cannot insert a name for the host to connect
to in our special file name.
Start the following program in one window. Notice that the service
@@ -930,13 +975,13 @@ Start the server program in both windows. The first one works, but the
second one complains that it could not open the connection. Each port
on a single machine can only be used by one server program at a time.
Now terminate the server program and change the name `8888' to `echo'.
-After restarting it, the server program does not run any more and you
-know why: there already is an `echo' service running on your machine.
+After restarting it, the server program does not run any more, and you
+know why: there is already an `echo' service running on your machine.
But even if this isn't true, you would not get your own `echo' server
running on a Unix machine, because the ports with numbers smaller than
1024 (`echo' is at port 7) are reserved for `root'. On machines
running some flavor of Microsoft Windows, there is no restriction that
-reserves ports 1 to 1024 for a privileged user; hence you can start an
+reserves ports 1 to 1024 for a privileged user; hence, you can start an
`echo' server there.
Turning this short server program into something really useful is
@@ -1076,7 +1121,7 @@ following:
(1) Version 1.0 of HTTP was defined in RFC 1945. HTTP 1.1 was
initially specified in RFC 2068. In June 1999, RFC 2068 was made
-obsolete by RFC 2616. It is an update without any substantial changes.
+obsolete by RFC 2616, an update without any substantial changes.

File: gawkinet.info, Node: Primitive Service, Next: Interacting Service, Prev: Web page, Up: Using Networking
@@ -1097,7 +1142,7 @@ not know in advance which host will connect to our service.
and close the connection. Here, we adhere to the modern syntax of HTTP.
The steps are as follows:
- 1. Send a status line telling the web browser that everything is OK.
+ 1. Send a status line telling the web browser that everything is okay.
2. Send a line to tell the browser how many bytes follow in the body
of the message. This was not necessary earlier because both
@@ -1156,7 +1201,7 @@ node, we develop a main program (a `BEGIN' pattern and its action)
that will become the core of event-driven execution controlled by a
graphical user interface (GUI). Each HTTP event that the user triggers
by some action within the browser is received in this central
-procedure. Parameters and menu choices are extracted from this request
+procedure. Parameters and menu choices are extracted from this request,
and an appropriate measure is taken according to the user's choice.
For example:
@@ -1352,19 +1397,19 @@ the function `CGI_setup' as part of the web server "core logic"
framework. The code presented there handles almost everything necessary
for CGI requests. One thing it doesn't do is handle encoded characters
in the requests. For example, an `&' is encoded as a percent sign
-followed by the hexadecimal value--`%26'. These encoded values should
+followed by the hexadecimal value: `%26'. These encoded values should
be decoded. Following is a simple library to perform these tasks.
This code is used for all web server examples used throughout the rest
of this Info file. If you want to use it for your own web server,
store the source code into a file named `inetlib.awk'. Then you can
include these functions into your code by placing the following
-statement into your program:
+statement into your program (on the first line of your script):
@include inetlib.awk
-on the first line of your script. But beware, this mechanism is only
-possible if you invoke your web server script with `igawk' instead of
-the usual `awk' or `gawk'. Here is the code:
+But beware, this mechanism is only possible if you invoke your web
+server script with `igawk' instead of the usual `awk' or `gawk'. Here
+is the code:
# CGI Library and core of a web server
# Global arrays
@@ -1483,13 +1528,13 @@ although there is nothing to enforce this:
}
This works by splitting the string apart around an encoded character.
-The two digits are converted to lowercase and looked up in a string of
-hex digits. Note that `0' is not in the string on purpose; `index'
-returns zero when it's not found, automatically giving the correct
-value! Once the hexadecimal value is converted from characters in a
-string into a numerical value, `sprintf' converts the value back into a
-real character. The following is a simple test harness for the above
-functions:
+The two digits are converted to lowercase characters and looked up in a
+string of hex digits. Note that `0' is not in the string on purpose;
+`index' returns zero when it's not found, automatically giving the
+correct value! Once the hexadecimal value is converted from characters
+in a string into a numerical value, `sprintf' converts the value back
+into a real character. The following is a simple test harness for the
+above functions:
BEGIN {
CGI_setup("GET",
@@ -1530,7 +1575,7 @@ File: gawkinet.info, Node: Simple Server, Next: Caveats, Prev: Interacting Se
A Simple Web Server
===================
- In the preceding node, we built the core logic for event driven GUIs.
+ In the preceding node, we built the core logic for event-driven GUIs.
In this node, we finally extend the core to a real application. No one
would actually write a commercial web server in `gawk', but it is
instructive to see that it is feasible in principle.
@@ -1614,9 +1659,9 @@ holds the HTML page contents:
Now we are down to the heart of ELIZA, so you can see how it works.
Initially the user does not say anything; then ELIZA resets its money
counter and asks the user to tell what comes to mind open heartedly.
-The subsequent answers are converted to uppercase and stored for later
-comparison. ELIZA presents the bill when being confronted with a
-sentence that contains the phrase "shut up." Otherwise, it looks for
+The subsequent answers are converted to uppercase characters and stored
+for later comparison. ELIZA presents the bill when being confronted with
+a sentence that contains the phrase "shut up." Otherwise, it looks for
keywords in the sentence, conjugates the rest of the sentence, remembers
the keyword for later use, and finally selects an answer from the set of
possible answers:
@@ -1723,14 +1768,14 @@ Network Programming Caveats
By now it should be clear that debugging a networked application is
more complicated than debugging a single-process single-hosted
application. The behavior of a networked application sometimes looks
-non-causal because it is not reproducible in a strong sense. Whether a
+noncausal because it is not reproducible in a strong sense. Whether a
network application works or not sometimes depends on the following:
- * How crowded the underlying network is.
+ * How crowded the underlying network is
- * If the party at the other end is running or not.
+ * If the party at the other end is running or not
- * The state of the party at the other end.
+ * The state of the party at the other end
The most difficult problems for a beginner arise from the hidden
states of the underlying network. After closing a TCP connection, it's
@@ -1900,17 +1945,17 @@ technology that may shape the future of networking.
We often refer to the site-independent core of the server that we
built in *Note A Simple Web Server: Simple Server. When building new
-and non-trivial servers, we always copy this building block and append
+and nontrivial servers, we always copy this building block and append
new instances of the two functions `SetUpServer' and `HandleGET'.
This makes a lot of sense, since this scheme of event-driven
execution provides `gawk' with an interface to the most widely accepted
-standard for GUIs: the web browser. Now, `gawk' can even rival Tcl/Tk.
+standard for GUIs: the web browser. Now, `gawk' can rival even Tcl/Tk.
Tcl and `gawk' have much in common. Both are simple scripting
languages that allow us to quickly solve problems with short programs.
-But Tcl has Tk on top of it and `gawk' had nothing comparable up to
-now. While Tcl needs a large and ever changing library (Tk, which was
+But Tcl has Tk on top of it, and `gawk' had nothing comparable up to
+now. While Tcl needs a large and ever-changing library (Tk, which was
bound to the X Window System until recently), `gawk' needs just the
networking interface and some kind of browser on the client's side.
Besides better portability, the most important advantage of this
@@ -1935,7 +1980,7 @@ VRML, or whatever else comes along to do our work.

File: gawkinet.info, Node: PANIC, Next: GETURL, Prev: Some Applications and Techniques, Up: Some Applications and Techniques
-PANIC: an Emergency Web Server
+PANIC: An Emergency Web Server
==============================
At first glance, the `"Hello, world"' example in *Note A Primitive
@@ -3674,7 +3719,6 @@ GNU Free Documentation License
******************************
Version 1.1, March 2000
-
Copyright (C) 2000 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
@@ -3682,7 +3726,6 @@ GNU Free Documentation License
of this license document, but changing it is not allowed.
-
0. PREAMBLE
The purpose of this License is to make a manual, textbook, or other
@@ -3769,7 +3812,6 @@ GNU Free Documentation License
Page" means the text near the most prominent appearance of the
work's title, preceding the beginning of the body of the text.
-
2. VERBATIM COPYING
You may copy and distribute the Document in any medium, either
@@ -3786,7 +3828,6 @@ GNU Free Documentation License
You may also lend copies, under the same conditions stated above,
and you may publicly display copies.
-
3. COPYING IN QUANTITY
If you publish printed copies of the Document numbering more than
@@ -3827,7 +3868,6 @@ GNU Free Documentation License
copies, to give them a chance to provide you with an updated
version of the Document.
-
4. MODIFICATIONS
You may copy and distribute a Modified Version of the Document
@@ -3933,7 +3973,6 @@ GNU Free Documentation License
License give permission to use their names for publicity for or to
assert or imply endorsement of any Modified Version.
-
5. COMBINING DOCUMENTS
You may combine the Document with other documents released under
@@ -3959,7 +3998,6 @@ GNU Free Documentation License
"Acknowledgements", and any sections entitled "Dedications". You
must delete all sections entitled "Endorsements."
-
6. COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other
@@ -3975,7 +4013,6 @@ GNU Free Documentation License
this License in all other respects regarding verbatim copying of
that document.
-
7. AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other
@@ -3995,7 +4032,6 @@ GNU Free Documentation License
aggregate. Otherwise they must appear on covers around the whole
aggregate.
-
8. TRANSLATION
Translation is considered a kind of modification, so you may
@@ -4009,7 +4045,6 @@ GNU Free Documentation License
disagreement between the translation and the original English
version of this License, the original English version will prevail.
-
9. TERMINATION
You may not copy, modify, sublicense, or distribute the Document
@@ -4020,7 +4055,6 @@ GNU Free Documentation License
from you under this License will not have their licenses
terminated so long as such parties remain in full compliance.
-
10. FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions of
@@ -4074,9 +4108,11 @@ Index
* Menu:
-* /inet/raw special files: File /inet/raw.
-* /inet/tcp special files: File /inet/tcp.
-* /inet/udp special files: File /inet/udp.
+* /inet/ files (gawk): Gawk Special Files.
+* /inet/raw special files (gawk): File /inet/raw.
+* /inet/tcp special files (gawk): File /inet/tcp.
+* /inet/udp special files (gawk): File /inet/udp.
+* advanced features, network connections: Troubleshooting.
* agent <1>: MOBAGWHO.
* agent: Challenges.
* AI: Challenges.
@@ -4086,161 +4122,213 @@ Index
* BLAST, Basic Local Alignment Search Tool: PROTBASE.
* blocking: Making Connections.
* Boutell, Thomas: STATIST.
-* CGI <1>: MOBAGWHO.
-* CGI <2>: Interacting Service.
-* CGI: Web page.
-* client: Making Connections.
+* CGI (Common Gateway Interface): MOBAGWHO.
+* CGI (Common Gateway Interface), dynamic web pages and: Web page.
+* CGI (Common Gateway Interface), library: CGI Lib.
+* clients: Making Connections.
* Clinton, Bill: Challenges.
+* Common Gateway Interface, See CGI: Web page.
* Computational Biology: PROTBASE.
-* Contest: Challenges.
-* cron: STOXPRED.
+* contest: Challenges.
+* cron utility: STOXPRED.
* CSV format: STOXPRED.
-* dark corner: File /inet/raw.
+* dark corner, RAW protocol: File /inet/raw.
* Dow Jones Industrial Index: STOXPRED.
* ELIZA program: Simple Server.
+* email: Email.
* FASTA/Pearson format: PROTBASE.
+* filenames, for network access: Gawk Special Files.
+* files, /inet/ (gawk): Gawk Special Files.
+* files, /inet/raw (gawk): File /inet/raw.
+* files, /inet/tcp (gawk): File /inet/tcp.
+* files, /inet/udp (gawk): File /inet/udp.
* finger utility: Setting Up.
-* FTP: Basic Protocols.
-* getline built-in function: TCP Connecting.
+* FTP (File Transfer Protocol): Basic Protocols.
+* gawk, networking: Using Networking.
+* gawk, networking, connections <1>: TCP Connecting.
+* gawk, networking, connections: Special File Fields.
+* gawk, networking, filenames: Gawk Special Files.
+* gawk, networking, See Also email: Email.
+* gawk, networking, service, establishing: Setting Up.
+* gawk, networking, troubleshooting: Caveats.
+* gawk, web and, See web service: Interacting Service.
+* getline command: TCP Connecting.
* GETURL program: GETURL.
-* gif image format <1>: STATIST.
-* gif image format: Web page.
+* GIF image format <1>: STATIST.
+* GIF image format: Web page.
* GNU/Linux <1>: REMCONF.
* GNU/Linux <2>: Interacting.
* GNU/Linux: Troubleshooting.
* GNUPlot utility <1>: STATIST.
* GNUPlot utility: Interacting Service.
-* GUI <1>: Simple Server.
-* GUI: Interacting Service.
* Hoare, C.A.R. <1>: PROTBASE.
* Hoare, C.A.R.: MOBAGWHO.
-* HTML: Web page.
-* HTTP <1>: Web page.
-* HTTP: Basic Protocols.
+* hostname field: Special File Fields.
+* HTML (Hypertext Markup Language): Web page.
+* HTTP (Hypertext Transfer Protocol) <1>: Web page.
+* HTTP (Hypertext Transfer Protocol): Basic Protocols.
+* HTTP (Hypertext Transfer Protocol), record separators and: Web page.
* HTTP server, core logic: Interacting Service.
* Humphrys, Mark: Simple Server.
-* image format <1>: STATIST.
-* image format: Interacting Service.
-* JavaScript <1>: STATIST.
-* JavaScript: Some Applications and Techniques.
+* Hypertext Markup Language (HTML): Web page.
+* Hypertext Transfer Protocol, See HTTP: Web page.
+* image format: STATIST.
+* images, in web pages: Interacting Service.
+* images, retrieving over networks: Web page.
+* input/output, two-way, See Also gawk, networking: Gawk Special Files.
+* Internet, See networks: Interacting.
+* JavaScript: STATIST.
* Linux <1>: REMCONF.
* Linux <2>: Interacting.
* Linux: Troubleshooting.
* Lisp: MOBAGWHO.
+* localport field: Gawk Special Files.
* Loebner, Hugh: Challenges.
-* Loui, Ronald P.: Challenges.
+* Loui, Ronald: Challenges.
* MAZE: MAZE.
-* Microsoft Windows <1>: WEBGRAB.
-* Microsoft Windows <2>: Setting Up.
-* Microsoft Windows: Troubleshooting.
+* Microsoft Windows: WEBGRAB.
+* Microsoft Windows, networking: Troubleshooting.
+* Microsoft Windows, networking, ports: Setting Up.
* MiniSQL: REMCONF.
* MOBAGWHO program: MOBAGWHO.
* NCBI, National Center for Biotechnology Information: PROTBASE.
-* network <1>: Caveats.
-* network <2>: Gawk Special Files.
-* network: Using Networking.
+* networks, gawk and: Using Networking.
+* networks, gawk and, connections <1>: TCP Connecting.
+* networks, gawk and, connections: Special File Fields.
+* networks, gawk and, filenames: Gawk Special Files.
+* networks, gawk and, See Also email: Email.
+* networks, gawk and, service, establishing: Setting Up.
+* networks, gawk and, troubleshooting: Caveats.
+* networks, ports, reserved: Setting Up.
+* networks, ports, specifying: Special File Fields.
+* networks, See Also web pages: PANIC.
* Numerical Recipes: STATIST.
+* ORS variable, HTTP and: Web page.
+* ORS variable, POP and: Email.
* PANIC program: PANIC.
* Perl: Using Networking.
+* Perl, gawk networking and: Using Networking.
* Perlis, Alan: MAZE.
-* png image format <1>: STATIST.
-* png image format: Web page.
-* POP: Email.
+* pipes, networking and: TCP Connecting.
+* PNG image format <1>: STATIST.
+* PNG image format: Web page.
+* POP (Post Office Protocol): Email.
+* Post Office Protocol (POP): Email.
* PostScript: STATIST.
* PROLOG: Challenges.
* PROTBASE: PROTBASE.
-* ps image format: STATIST.
+* protocol field: Special File Fields.
+* PS image format: STATIST.
* Python: Using Networking.
-* RAW: File /inet/raw.
+* Python, gawk networking and: Using Networking.
+* RAW protocol: File /inet/raw.
+* record separators, HTTP and: Web page.
+* record separators, POP and: Email.
* REMCONF program: REMCONF.
-* reserved ports: Setting Up.
-* RFC 1939: Email.
-* RFC 1945: Web page.
-* RFC 2068 <1>: Interacting Service.
-* RFC 2068: Web page.
-* RFC 2616: Web page.
-* RFC 821: Email.
+* remoteport field: Gawk Special Files.
* robot <1>: WEBGRAB.
-* robot <2>: GETURL.
* robot: Challenges.
-* server <1>: Setting Up.
-* server: Making Connections.
-* SMTP <1>: Email.
-* SMTP: Basic Protocols.
+* RS variable, HTTP and: Web page.
+* RS variable, POP and: Email.
+* servers <1>: Setting Up.
+* servers: Making Connections.
+* servers, as hosts: Special File Fields.
+* servers, HTTP: Interacting Service.
+* servers, web: Simple Server.
+* Simple Mail Transfer Protocol (SMTP): Email.
+* SMTP (Simple Mail Transfer Protocol) <1>: Email.
+* SMTP (Simple Mail Transfer Protocol): Basic Protocols.
* SPAK utility: File /inet/raw.
* STATIST program: STATIST.
* STOXPRED program: STOXPRED.
* synchronous communications: Making Connections.
-* Tcl/Tk <1>: Some Applications and Techniques.
* Tcl/Tk: Using Networking.
-* TCP <1>: Interacting.
-* TCP: File /inet/tcp.
-* UDP <1>: Interacting.
-* UDP: File /inet/udp.
+* Tcl/Tk, gawk and <1>: Some Applications and Techniques.
+* Tcl/Tk, gawk and: Using Networking.
+* TCP (Transmission Control Protocol) <1>: File /inet/tcp.
+* TCP (Transmission Control Protocol): Using Networking.
+* TCP (Transmission Control Protocol), connection, establishing: TCP Connecting.
+* TCP (Transmission Control Protocol), UDP and: Interacting.
+* TCP/IP, protocols, selecting: Special File Fields.
+* TCP/IP, sockets and: Gawk Special Files.
+* Transmission Control Protocol, See TCP: Using Networking.
+* troubleshooting, gawk, networks: Caveats.
+* troubleshooting, networks, connections: Troubleshooting.
+* troubleshooting, networks, timeouts: Caveats.
+* UDP (User Datagram Protocol): File /inet/udp.
+* UDP (User Datagram Protocol), TCP and: Interacting.
+* Unix, network ports and: Setting Up.
* URLCHK program: URLCHK.
+* User Datagram Protocol, See UDP: File /inet/udp.
+* vertical bar (|), |& operator (I/O): TCP Connecting.
* VRML: MAZE.
+* web browsers, See web service: Interacting Service.
+* web pages: Web page.
+* web pages, images in: Interacting Service.
+* web pages, retrieving: GETURL.
+* web servers: Simple Server.
+* web service <1>: PANIC.
+* web service: Primitive Service.
* WEBGRAB program: WEBGRAB.
* Weizenbaum, Joseph: Simple Server.
-* xbm image format: Interacting Service.
-* Yahoo: STOXPRED.
-* Yahoo! <1>: REMCONF.
-* Yahoo! <2>: Simple Server.
-* Yahoo!: Web page.
-* |& I/O operator: TCP Connecting.
+* XBM image format: Interacting Service.
+* Yahoo! <1>: STOXPRED.
+* Yahoo!: REMCONF.
+* | (vertical bar), |& operator (I/O): TCP Connecting.

Tag Table:
-Node: Top1119
-Node: Preface3953
-Node: Introduction5331
-Node: Stream Communications6355
-Node: Datagram Communications7523
-Node: The TCP/IP Protocols9148
-Ref: The TCP/IP Protocols-Footnote-19824
-Node: Basic Protocols9981
-Node: Ports11288
-Node: Making Connections12685
-Ref: Making Connections-Footnote-115256
-Node: Using Networking15303
-Node: Gawk Special Files17627
-Node: Special File Fields19649
-Node: Comparing Protocols24957
-Node: File /inet/tcp25537
-Node: File /inet/udp26550
-Node: File /inet/raw27658
-Ref: File /inet/raw-Footnote-130678
-Node: TCP Connecting30758
-Node: Troubleshooting33093
-Ref: Troubleshooting-Footnote-136090
-Node: Interacting36609
-Node: Setting Up39332
-Node: Email42818
-Node: Web page45139
-Ref: Web page-Footnote-147939
-Node: Primitive Service48142
-Node: Interacting Service50869
-Ref: Interacting Service-Footnote-159992
-Node: CGI Lib60024
-Node: Simple Server66994
-Ref: Simple Server-Footnote-174716
-Node: Caveats74817
-Node: Challenges75958
-Node: Some Applications and Techniques84617
-Node: PANIC87073
-Node: GETURL88786
-Node: REMCONF91404
-Node: URLCHK96875
-Node: WEBGRAB100705
-Node: STATIST105150
-Ref: STATIST-Footnote-1116851
-Node: MAZE117296
-Node: MOBAGWHO123476
-Ref: MOBAGWHO-Footnote-1137412
-Node: STOXPRED137467
-Node: PROTBASE151742
-Node: Links164833
-Node: GNU Free Documentation License168265
-Node: Index188159
+Node: Top1132
+Node: Preface5684
+Node: Introduction7062
+Node: Stream Communications8086
+Node: Datagram Communications9254
+Node: The TCP/IP Protocols10879
+Ref: The TCP/IP Protocols-Footnote-111555
+Node: Basic Protocols11712
+Node: Ports13019
+Node: Making Connections14416
+Ref: Making Connections-Footnote-116987
+Node: Using Networking17034
+Node: Gawk Special Files19387
+Node: Special File Fields21386
+Node: Comparing Protocols26692
+Node: File /inet/tcp27272
+Node: File /inet/udp28285
+Node: File /inet/raw29393
+Ref: File /inet/raw-Footnote-132413
+Node: TCP Connecting32493
+Node: Troubleshooting34826
+Ref: Troubleshooting-Footnote-137877
+Node: Interacting38396
+Node: Setting Up41121
+Node: Email44610
+Node: Web page46931
+Ref: Web page-Footnote-149731
+Node: Primitive Service49928
+Node: Interacting Service52657
+Ref: Interacting Service-Footnote-161781
+Node: CGI Lib61813
+Node: Simple Server68795
+Ref: Simple Server-Footnote-176528
+Node: Caveats76629
+Node: Challenges77766
+Node: Some Applications and Techniques86425
+Node: PANIC88881
+Node: GETURL90594
+Node: REMCONF93212
+Node: URLCHK98683
+Node: WEBGRAB102513
+Node: STATIST106958
+Ref: STATIST-Footnote-1118659
+Node: MAZE119104
+Node: MOBAGWHO125284
+Ref: MOBAGWHO-Footnote-1139220
+Node: STOXPRED139275
+Node: PROTBASE153550
+Node: Links166641
+Node: GNU Free Documentation License170073
+Node: Index189956

End Tag Table
diff --git a/doc/gawkinet.texi b/doc/gawkinet.texi
index 2ffb5814..d51ce794 100644
--- a/doc/gawkinet.texi
+++ b/doc/gawkinet.texi
@@ -3,6 +3,7 @@
@setfilename gawkinet.info
@settitle TCP/IP Internetworking With @command{gawk}
@c %**end of header (This is for running Texinfo on a region.)
+@c FIXME: web vs. Web
@c inside ifinfo for older versions of texinfo.tex
@ifinfo
@@ -64,20 +65,18 @@
@set TITLE TCP/IP Internetworking With @command{gawk}
@set EDITION 1.1
-@set UPDATE-MONTH March, 2001
+@set UPDATE-MONTH April, 2002
@c gawk versions:
@set VERSION 3.1
-@set PATCHLEVEL 0
-
-@ifinfo
-This file documents the networking features in GNU @command{awk}.
+@set PATCHLEVEL 1
+@copying
This is Edition @value{EDITION} of @cite{@value{TITLE}},
for the @value{VERSION}.@value{PATCHLEVEL} (or later) version of the GNU
implementation of AWK.
-
-Copyright (C) 2000, 2001 Free Software Foundation, Inc.
-
+@sp 2
+Copyright (C) 2000, 2001, 2002 Free Software Foundation, Inc.
+@sp 2
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
@@ -95,6 +94,12 @@ texts being (a) (see below), and with the Back-Cover Texts being (b)
software. Copies published by the Free Software Foundation raise
funds for GNU development.''
@end enumerate
+@end copying
+
+@ifinfo
+This file documents the networking features in GNU @command{awk}.
+
+@insertcopying
@end ifinfo
@setchapternewpage odd
@@ -111,16 +116,6 @@ funds for GNU development.''
@page
@vskip 0pt plus 1filll
-Copyright @copyright{} 2000, 2001 Free Software Foundation, Inc.
-@sp 1
-@b{User Friendly} Copyright @copyright{} 2000 J.D.@: ``Iliad'' Frazier.
-Reprinted by permission.
-@sp 2
-
-This is Edition @value{EDITION} of @cite{@value{TITLE}},
-for the @value{VERSION}.@value{PATCHLEVEL} (or later) version of the GNU
-implementation of AWK.
-
@sp 2
Published by:
@sp 1
@@ -135,23 +130,8 @@ URL: @uref{http://www.gnu.org/} @*
ISBN 1-882114-93-0 @*
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with the
-Invariant Sections being ``GNU General Public License'', the Front-Cover
-texts being (a) (see below), and with the Back-Cover Texts being (b)
-(see below). A copy of the license is included in the section entitled
-``GNU Free Documentation License''.
-
-@enumerate a
-@item
-``A GNU Manual''
+@insertcopying
-@item
-``You have freedom to copy and modify this GNU Manual, like GNU
-software. Copies published by the Free Software Foundation raise
-funds for GNU development.''
-@end enumerate
@c @sp 2
@c Cover art by ?????.
@end titlepage
@@ -169,6 +149,8 @@ funds for GNU development.''
This file documents the networking features in GNU Awk (@command{gawk})
version 3.1 and later.
+
+@insertcopying
@end ifinfo
@menu
@@ -192,7 +174,7 @@ version 3.1 and later.
* Special File Fields:: The fields in the special file name.
* Comparing Protocols:: Differences between the protocols.
* File /inet/tcp:: The TCP special file.
-* File /inet/udp:: The UDB special file.
+* File /inet/udp:: The UDP special file.
* File /inet/raw:: The RAW special file.
* TCP Connecting:: Making a TCP connection.
* Troubleshooting:: Troubleshooting TCP/IP connections.
@@ -414,9 +396,9 @@ when using @command{gawk} for network programming.
All other user-level protocols use either TCP or UDP to do their basic
communications. Examples are SMTP (Simple Mail Transfer Protocol),
FTP (File Transfer Protocol) and HTTP (HyperText Transfer Protocol).
-@cindex SMTP
-@cindex FTP
-@cindex HTTP
+@cindex SMTP (Simple Mail Transfer Protocol)
+@cindex FTP (File Transfer Protocol)
+@cindex HTTP (Hypertext Transfer Protocol)
@node Ports, , Basic Protocols, The TCP/IP Protocols
@subsection TCP and UDP Ports
@@ -456,7 +438,7 @@ such as HTTP or FTP, determine who is the client and who is the
server. Often, it turns out that the client and server are the
same in both roles.)
-@cindex server
+@cindex servers
The @dfn{server} is the system providing the service, such as the
web server or email server. It is the @dfn{host} (system) which
is @emph{connected to} in a transaction.
@@ -466,7 +448,7 @@ the phone@footnote{In the days before voice mail systems!}, the
server process (usually) has to be started first and waiting
for a connection.
-@cindex client
+@cindex clients
The @dfn{client} is the system requesting the service.
It is the system @emph{initiating the connection} in a transaction.
(Just as when you pick up the phone to call an office or store.)
@@ -522,7 +504,10 @@ RAW&&X&\cr
@comment node-name, next, previous, up
@chapter Networking With @command{gawk}
-@cindex network
+@c STARTOFRANGE netgawk
+@cindex networks, @command{gawk} and
+@c STARTOFRANGE gawknet
+@cindex @command{gawk}, networking
The @command{awk} programming language was originally developed as a
pattern-matching language for writing short programs to perform
data manipulation tasks.
@@ -547,15 +532,21 @@ The advanced
features are available when programming in C or Perl. In fact, the
network programming
in this @value{CHAPTER}
-is very similar to what is described in books like
+is very similar to what is described in books such as
@cite{Internet Programming with Python},
@cite{Advanced Perl Programming},
or
@cite{Web Client Programming with Perl}.
-But it's done here without first having to learn object-oriented ideology, underlying
-languages such as Tcl/Tk, Perl, Python, or all of the libraries necessary to
-extend these languages before they are ready for the Internet.
+@cindex Perl, @command{gawk} networking and
+@cindex Python, @command{gawk} networking and
+@cindex Tcl/Tk, @command{gawk} and
+However, you can do the programming here without first having to learn object-oriented
+ideology; underlying languages such as Tcl/Tk, Perl, Python; or all of
+the libraries necessary to extend these languages before they are ready for the Internet.
+
+@cindex Transmission Control Protocol, See TCP
+@cindex TCP (Transmission Control Protocol)
This @value{CHAPTER} demonstrates how to use the TCP protocol. The
other protocols are much less important for most users (UDP) or even
untractable (RAW).
@@ -577,11 +568,10 @@ untractable (RAW).
@node Gawk Special Files, TCP Connecting, Using Networking, Using Networking
@comment node-name, next, previous, up
-@section @command{gawk} Networking Mechanisms
-@cindex network
+@section @command{gawk}'s Networking Mechanisms
The @samp{|&} operator introduced in @command{gawk} 3.1 for use in
-communicating with a @dfn{co-process} is described in
+communicating with a @dfn{coprocess} is described in
@ref{Two-way I/O, ,Two-way Communications With Another Process, gawk, GAWK: Effective AWK Programming}.
It shows how to do two-way I/O to a
separate process, sending it data with @code{print} or @code{printf} and
@@ -589,11 +579,15 @@ reading data with @code{getline}. If you haven't read it already, you should
detour there to do so.
@command{gawk} transparently extends the two-way I/O mechanism to simple networking through
-the use of special @value{FN}s. When a ``co-process'' is started that matches
-the special files we are about to describe, @command{gawk} creates the appropriate network
+the use of special @value{FN}s. When a ``coprocess'' that matches
+the special files we are about to describe
+is started, @command{gawk} creates the appropriate network
connection, and then two-way I/O proceeds as usual.
-At the C, C++ (and basic Perl) level, networking is accomplished
+@c last comma is part of see-also
+@cindex input/output, two-way, See Also @command{gawk}, networking
+@cindex TCP/IP, sockets and
+At the C, C++, and Perl level, networking is accomplished
via @dfn{sockets}, an Application Programming Interface (API) originally
developed at the University of California at Berkeley that is now used
almost universally for TCP/IP networking.
@@ -604,13 +598,23 @@ The special files provided in @command{gawk} hide the details from
the programmer, making things much simpler and easier to use.
@c Who sez we can't toot our own horn occasionally?
+@c STARTOFRANGE filenet
+@cindex filenames, for network access
+@c STARTOFRANGE gawnetf
+@cindex @command{gawk}, networking, filenames
+@c STARTOFRANGE netgawf
+@cindex networks, @command{gawk} and, filenames
The special @value{FN} for network access is made up of several fields, all
-of them mandatory, none of them optional:
+of which are mandatory:
@example
/inet/@var{protocol}/@var{localport}/@var{hostname}/@var{remoteport}
@end example
+@cindex @code{/inet/} files (@command{gawk})
+@cindex files, @code{/inet/} (@command{gawk})
+@cindex localport field
+@cindex remoteport field
The @file{/inet/} field is, of course, constant when accessing the network.
The @var{localport} and @var{remoteport} fields do not have a meaning
when used with @file{/inet/raw} because ``ports'' only apply to
@@ -627,9 +631,12 @@ to be @samp{0}.
This @value{SECTION} explains the meaning of all the other fields,
as well as the range of values and the defaults.
All of the fields are mandatory. To let the system pick a value,
-or if the field doesn't apply to the protocol, specify it as @samp{0}.
+or if the field doesn't apply to the protocol, specify it as @samp{0}:
@table @var
+@cindex protocol field
+@c last comma is part of secondary
+@cindex TCP/IP, protocols, selecting
@item protocol
Determines which member of the TCP/IP
family of protocols is selected to transport the data across the
@@ -638,23 +645,26 @@ network. There are three possible values (always written in lowercase):
explained later in this @value{SECTION}.
@item localport
+@cindex networks, ports, specifying
Determines which port on the local
machine is used to communicate across the network. It has no meaning
-with @file{/inet/raw} and must therefore be @samp{0}. Application level clients
+with @file{/inet/raw} and must therefore be @samp{0}. Application-level clients
usually use @samp{0} to indicate they do not care which local port is
used---instead they specify a remote port to connect to. It is vital for
-application level servers to use a number different from @samp{0} here
-because their service has to be available at a specific publicly-known
+application-level servers to use a number different from @samp{0} here
+because their service has to be available at a specific publicly known
port number. It is possible to use a name from @file{/etc/services} here.
@item hostname
+@cindex hostname field
+@cindex servers, as hosts
Determines which remote host is to
-be at the other end of the connection. Application level servers must fill
+be at the other end of the connection. Application-level servers must fill
this field with a @samp{0} to indicate their being open for all other hosts
to connect to them and enforce connection level server behavior this way.
-It is not possible for an application level server to restrict its
+It is not possible for an application-level server to restrict its
availability to one remote host by entering a host name here.
-Application level clients must enter a name different from @samp{0}.
+Application-level clients must enter a name different from @samp{0}.
The name can be either symbolic
(e.g., @samp{jpl-devvax.jpl.nasa.gov}) or numeric (e.g., @samp{128.149.1.143}).
@@ -663,13 +673,15 @@ Determines which port on the remote
machine is used to communicate across the network. It has no meaning
with @file{/inet/raw} and must therefore be 0.
For @file{/inet/tcp} and @file{/inet/udp},
-application level clients @emph{must} use a number
-other than @samp{0} to indicate which port on the remote machine
-they want to connect to. Application level servers must not fill this field with
-a @samp{0}. Instead they specify a local port for clients to connect to.
+application-level clients @emph{must} use a number
+other than @samp{0} to indicate to which port on the remote machine
+they want to connect. Application-level servers must not fill this field with
+a @samp{0}. Instead they specify a local port to which clients connect.
It is possible to use a name from @file{/etc/services} here.
@end table
+@cindex networks, @command{gawk} and, connections
+@cindex @command{gawk}, networking, connections
Experts in network programming will notice that the usual
client/server asymmetry found at the level of the socket API is not visible
here. This is for the sake of simplicity of the high-level concept. If this
@@ -678,7 +690,7 @@ use another language.
For @command{gawk}, it is
more important to enable users to write a client program with a minimum
of code. What happens when first accessing a network connection is seen
-in the following pseudo-code:
+in the following pseudocode:
@smallexample
if ((name of remote host given) && (other side accepts connection)) @{
@@ -705,7 +717,7 @@ patterns printed in bold letters.
@multitable {12345678901234} {123456} {123456} {1234567} {1234567890123456789012345}
@item @sc{protocol} @tab @sc{local port} @tab @sc{host name}
-@tab @sc{remote port} @tab @sc{Resulting connection level behavior}
+@tab @sc{remote port} @tab @sc{Resulting connection-level behavior}
@item @strong{tcp} @tab @strong{0} @tab @strong{x} @tab @strong{x} @tab
@strong{Dedicated client, fails if immediately connecting to a
server on the other side fails}
@@ -740,16 +752,17 @@ available and demonstrate the differences between them.
@menu
* File /inet/tcp:: The TCP special file.
-* File /inet/udp:: The UDB special file.
+* File /inet/udp:: The UDP special file.
* File /inet/raw:: The RAW special file.
@end menu
@node File /inet/tcp, File /inet/udp, Comparing Protocols, Comparing Protocols
@subsubsection @file{/inet/tcp}
-@cindex @file{/inet/tcp} special files
-@cindex TCP
+@cindex @code{/inet/tcp} special files (@command{gawk})
+@cindex files, @code{/inet/tcp} (@command{gawk})
+@cindex TCP (Transmission Control Protocol)
Once again, always use TCP.
-(Use UDP when low-overhead is a necessity, and use RAW for
+(Use UDP when low overhead is a necessity, and use RAW for
network experimentation.)
The first example is the sender
program:
@@ -783,8 +796,10 @@ first, and it waits for the receiver to read a line.
@node File /inet/udp, File /inet/raw, File /inet/tcp, Comparing Protocols
@subsubsection @file{/inet/udp}
-@cindex @file{/inet/udp} special files
-@cindex UDP
+@cindex @code{/inet/udp} special files (@command{gawk})
+@cindex files, @code{/inet/udp} (@command{gawk})
+@cindex UDP (User Datagram Protocol)
+@cindex User Datagram Protocol, See UDP
The server and client programs that use UDP are almost identical to their TCP counterparts;
only the @var{protocol} has changed. As before, it does matter which side
starts first. The receiving side blocks and waits for the sender.
@@ -818,18 +833,19 @@ such as data acquisition, logging, and even stateless services like NFS.
@node File /inet/raw, , File /inet/udp, Comparing Protocols
@subsubsection @file{/inet/raw}
-@cindex @file{/inet/raw} special files
-@cindex RAW
+@cindex @code{/inet/raw} special files (@command{gawk})
+@cindex files, @code{/inet/raw} (@command{gawk})
+@cindex RAW protocol
This is an IP-level protocol. Only @code{root} is allowed to access this
special file. It is meant to be the basis for implementing
-and experimenting with transport level protocols.@footnote{This special file
+and experimenting with transport-level protocols.@footnote{This special file
is reserved, but not otherwise currently implemented.}
In the most general case,
the sender has to supply the encapsulating header bytes in front of the
packet and the receiver has to strip the additional bytes from the message.
-@cindex dark corner
+@cindex dark corner, RAW protocol
RAW receivers cannot receive packets sent with TCP or UDP because the
operating system does not deliver the packets to a RAW receiver. The
operating system knows about some of the protocols on top of IP
@@ -894,13 +910,18 @@ implies that line separation with @code{RS} does not work as usual.
@node TCP Connecting, Troubleshooting, Gawk Special Files, Using Networking
@section Establishing a TCP Connection
+@c STARTOFRANGE tcpcon
+@cindex TCP (Transmission Control Protocol), connection, establishing
+@c STARTOFRANGE netcon
+@cindex networks, @command{gawk} and, connections
+@c STARTOFRANGE gawcon
+@cindex @command{gawk}, networking, connections
Let's observe a network connection at work. Type in the following program
and watch the output. Within a second, it connects via TCP (@file{/inet/tcp})
-to the machine it is running on (@samp{localhost}), and asks the service
+to the machine it is running on (@samp{localhost}) and asks the service
@samp{daytime} on the machine what time it is:
-@cindex @code{|&} I/O operator
-@cindex @code{getline} built-in function
+@cindex @code{getline} command
@example
BEGIN @{
"/inet/tcp/0/localhost/daytime" |& getline
@@ -920,12 +941,15 @@ being read like any other file (@samp{getline <
"/inet/tcp/0/localhost/daytime")}.
@item
+@cindex @code{|} (vertical bar), @code{|&} operator (I/O)
+@cindex vertical bar (@code{|}), @code{|&} operator (I/O)
The operator @samp{|&} has not been part of any @command{awk}
implementation (until now).
It is actually the only extension of the @command{awk}
language needed (apart from the special files) to introduce network access.
@end itemize
+@cindex pipes, networking and
The @samp{|&} operator was introduced in @command{gawk} 3.1 in order to
overcome the crucial restriction that access to files and pipes in
@command{awk} is always unidirectional. It was formerly impossible to use
@@ -951,29 +975,32 @@ We could also have printed a line into the special file. But instead we just
read a line with the time, printed it, and closed the connection.
(While we could just let @command{gawk} close the connection by finishing
the program, in this @value{DOCUMENT}
-we are pedantic, and always explicitly close the connections.)
+we are pedantic and always explicitly close the connections.)
@node Troubleshooting, Interacting, TCP Connecting, Using Networking
@section Troubleshooting Connection Problems
-It may well be that for some reason the above program does not run on your
+@cindex advanced features, network connections
+@c last comma is part of secondary
+@cindex troubleshooting, networks, connections
+It may well be that for some reason the program shown in the previous example does not run on your
machine. When looking at possible reasons for this, you will learn much
about typical problems that arise in network programming. First of all,
your implementation of @command{gawk} may not support network access
because it is
a pre-3.1 version or you do not have a network interface in your machine.
-Perhaps your machine uses some other protocol
-like DECnet or Novell's IPX. For the rest of this @value{CHAPTER},
+Perhaps your machine uses some other protocol, such as
+DECnet or Novell's IPX. For the rest of this @value{CHAPTER},
we will assume
-you work on a Unix machine that supports TCP/IP. If the above program does
-not run on such a machine, it may help to replace the name
+you work on a Unix machine that supports TCP/IP. If the previous example program does
+not run on your machine, it may help to replace the name
@samp{localhost} with the name of your machine or its IP address. If it
does, you could replace @samp{localhost} with the name of another machine
-in your vicinity. This way, the program connects to another machine.
-Now you should see the date and time being printed by the program.
-Otherwise your machine may not support the @samp{daytime} service.
+in your vicinity---this way, the program connects to another machine.
+Now you should see the date and time being printed by the program,
+otherwise your machine may not support the @samp{daytime} service.
Try changing the service to @samp{chargen} or @samp{ftp}. This way, the program
connects to other services that should give you some response. If you are
-curious, you should have a look at your file @file{/etc/services}. It could
+curious, you should have a look at your @file{/etc/services} file. It could
look like this:
@ignore
@@ -1035,11 +1062,11 @@ irc 194/udp
@cindex Linux
@cindex GNU/Linux
-@cindex Microsoft Windows
+@cindex Microsoft Windows, networking
Here, you find a list of services that traditional Unix machines usually
support. If your GNU/Linux machine does not do so, it may be that these
services are switched off in some startup script. Systems running some
-flavor of Microsoft Windows usually do @emph{not} support such services.
+flavor of Microsoft Windows usually do @emph{not} support these services.
Nevertheless, it @emph{is} possible to do networking with @command{gawk} on
Microsoft
Windows.@footnote{Microsoft prefered to ignore the TCP/IP
@@ -1050,8 +1077,8 @@ their TCP/IP implementation to Microsoft Windows for Workgroups 3.11, but it was
a rather rudimentary and half-hearted implementation. Nevertheless,
the equivalent of @file{/etc/services} resides under
@file{c:\windows\services} on Microsoft Windows.}
-The first column of the file gives the name of the service,
-the second a unique number, and the protocol that one can use to connect to
+The first column of the file gives the name of the service, and
+the second column gives a unique number and the protocol that one can use to connect to
this service.
The rest of the line is treated as a comment.
You see that some services (@samp{echo}) support TCP as
@@ -1086,7 +1113,7 @@ lines are coming (because the service has closed the connection), the
program also closes the connection. Try replacing @code{"@var{name}"} with your
login name (or the name of someone else logged in). For a list
of all users currently logged in, replace @var{name} with an empty string
-@code{""}.
+(@code{""}).
@cindex Linux
@cindex GNU/Linux
@@ -1166,8 +1193,9 @@ remember the advice Douglas E.@: Comer and David Stevens give in
Volume III of their series @cite{Internetworking With TCP}
(page 14):
-@cindex TCP
-@cindex UDP
+@cindex TCP (Transmission Control Protocol), UDP and
+@cindex UDP (User Datagram Protocol), TCP and
+@cindex Internet, See networks
@quotation
When designing client-server applications, beginners are strongly
advised to use TCP because it provides reliable, connection-oriented
@@ -1178,11 +1206,15 @@ or the application cannot tolerate virtual circuit overhead.
@node Setting Up, Email, Interacting, Using Networking
@section Setting Up a Service
+@c last comma is part of tertiary
+@cindex networks, @command{gawk} and, service, establishing
+@c last comma is part of tertiary
+@cindex @command{gawk}, networking, service, establishing
The preceding programs behaved as clients that connect to a server somewhere
on the Internet and request a particular service. Now we set up such a
service to mimic the behavior of the @samp{daytime} service.
Such a server does not know in advance who is going to connect to it over
-the network. Therefore we cannot insert a name for the host to connect to
+the network. Therefore, we cannot insert a name for the host to connect to
in our special @value{FN}.
Start the following program in one window. Notice that the service does
@@ -1195,7 +1227,7 @@ Also notice that the service name has to be entered into a different field
of the special @value{FN} because we are setting up a server, not a client:
@cindex @command{finger} utility
-@cindex server
+@cindex servers
@example
BEGIN @{
print strftime() |& "/inet/tcp/8888/0/0"
@@ -1217,8 +1249,10 @@ Sat Sep 27 19:08:16 CEST 1997
@noindent
Both programs explicitly close the connection.
-@cindex Microsoft Windows
-@cindex reserved ports
+@c first comma is part of primary
+@cindex Microsoft Windows, networking, ports
+@cindex networks, ports, reserved
+@cindex Unix, network ports and
Now we will intentionally make a mistake to see what happens when the name
@samp{8888} (the so-called port) is already used by another service.
Start the server
@@ -1226,14 +1260,14 @@ program in both windows. The first one works, but the second one
complains that it could not open the connection. Each port on a single
machine can only be used by one server program at a time. Now terminate the
server program and change the name @samp{8888} to @samp{echo}. After restarting it,
-the server program does not run any more and you know why: there already is
+the server program does not run any more, and you know why: there is already
an @samp{echo} service running on your machine. But even if this isn't true,
you would not get
your own @samp{echo} server running on a Unix machine,
because the ports with numbers smaller
than 1024 (@samp{echo} is at port 7) are reserved for @code{root}.
On machines running some flavor of Microsoft Windows, there is no restriction
-that reserves ports 1 to 1024 for a privileged user; hence you can start
+that reserves ports 1 to 1024 for a privileged user; hence, you can start
an @samp{echo} server there.
Turning this short server program into something really useful is simple.
@@ -1265,10 +1299,14 @@ execute arbitrary commands, anyone would be free to do @samp{rm -rf *}.
@node Email, Web page, Setting Up, Using Networking
@section Reading Email
-@cindex POP
-@cindex SMTP
-@cindex RFC 1939
-@cindex RFC 821
+@c @cindex RFC 1939
+@c @cindex RFC 821
+@cindex @command{gawk}, networking, See Also email
+@cindex networks, @command{gawk} and, See Also email
+@cindex POP (Post Office Protocol)
+@cindex SMTP (Simple Mail Transfer Protocol)
+@cindex Post Office Protocol (POP)
+@cindex Simple Mail Transfer Protocol (SMTP)
The distribution of email is usually done by dedicated email servers that
communicate with your machine using special protocols. To receive email, we
will use the Post Office Protocol (POP). Sending can be done with the much
@@ -1279,6 +1317,7 @@ RFC 821 defines SMTP. See
@uref{http://rfc.fh-koeln.de/doc/rfc/html/rfc.html, RFCs in HTML}.}
@end ignore
+@cindex email
When you type in the following program, replace the @var{emailhost} by the
name of your local email server. Ask your administrator if the server has a
POP service, and then use its name or number in the program below.
@@ -1306,7 +1345,11 @@ BEGIN @{
@}
@end example
-@cindex RFC 1939
+@c @cindex RFC 1939
+@cindex record separators, POP and
+@cindex @code{RS} variable, POP and
+@cindex @code{ORS} variable, POP and
+@cindex POP (Post Office Protocol)
The record separators @code{RS} and @code{ORS} are redefined because the
protocol (POP) requires CR-LF to separate lines. After identifying
yourself to the email service, the command @samp{retr 1} instructs the
@@ -1323,9 +1366,11 @@ message it reads, but instead leaves it on the server.
@node Web page, Primitive Service, Email, Using Networking
@section Reading a Web Page
-@cindex HTTP
-@cindex RFC 2068
-@cindex RFC 2616
+@cindex web pages
+@cindex HTTP (Hypertext Transfer Protocol)
+@cindex Hypertext Transfer Protocol, See HTTP
+@c @cindex RFC 2068
+@c @cindex RFC 2616
Retrieving a web page from a web server is as simple as
retrieving email from an email server. We only have to use a
@@ -1387,9 +1432,13 @@ BEGIN @{
@}
@end example
-@cindex RFC 1945
-@cindex HTML
-@cindex Yahoo!
+@c @cindex RFC 1945
+@cindex record separators, HTTP and
+@cindex @code{RS} variable, HTTP and
+@cindex @code{ORS} variable, HTTP and
+@cindex HTTP (Hypertext Transfer Protocol), record separators and
+@cindex HTML (Hypertext Markup Language)
+@cindex Hypertext Markup Language (HTML)
Again, lines are separated by a redefined @code{RS} and @code{ORS}.
The @code{GET} request that we send to the server is the only kind of
HTTP request that existed when the web was created in the early 1990s.
@@ -1398,7 +1447,7 @@ service to transmit a web page (here the home page of the Yahoo! search
engine). Version 1.0 added the request methods @code{HEAD} and
@code{POST}. The current version of HTTP is 1.1,@footnote{Version 1.0 of
HTTP was defined in RFC 1945. HTTP 1.1 was initially specified in RFC
-2068. In June 1999, RFC 2068 was made obsolete by RFC 2616. It is an update
+2068. In June 1999, RFC 2068 was made obsolete by RFC 2616, an update
without any substantial changes.} and knows the additional request
methods @code{OPTIONS}, @code{PUT}, @code{DELETE}, and @code{TRACE}.
You can fill in any valid web address, and the program prints the
@@ -1410,9 +1459,11 @@ then you get the body of the page in HTML. The lines of the headers also
have the same form as in POP. There is the name of a parameter,
then a colon, and finally the value of that parameter.
-@cindex CGI
-@cindex @file{gif} image format
-@cindex @file{png} image format
+@cindex CGI (Common Gateway Interface), dynamic web pages and
+@cindex Common Gateway Interface, See CGI
+@cindex GIF image format
+@cindex PNG image format
+@cindex images, retrieving over networks
Images (@file{.png} or @file{.gif} files) can also be retrieved this way,
but then you
get binary data that should be redirected into a file. Another
@@ -1443,6 +1494,8 @@ Another good source is @cite{The CGI Resource Index}}.@footnote{@uref{http://www
@node Primitive Service, Interacting Service, Web page, Using Networking
@section A Primitive Web Service
+@c STARTOFRANGE webser
+@cindex web service
Now we know enough about HTTP to set up a primitive web service that just
says @code{"Hello, world"} when someone connects to it with a browser.
Compared
@@ -1460,7 +1513,7 @@ The steps are as follows:
@enumerate 1
@item
Send a status line telling the web browser that everything
-is OK.
+is okay.
@item
Send a line to tell the browser how many bytes follow in the
@@ -1509,7 +1562,11 @@ use a proxy to connect to your machine.
@node Interacting Service, Simple Server, Primitive Service, Using Networking
@section A Web Service with Interaction
-@cindex GUI
+@cindex @command{gawk}, web and, See web service
+@cindex web browsers, See web service
+@c comma is part of primary
+@cindex HTTP server, core logic
+@cindex servers, HTTP
@ifinfo
This node shows how to set up a simple web server.
The subnode is a library file that we will use with all the examples in
@@ -1527,7 +1584,7 @@ that will become the core of event-driven execution controlled by a
graphical user interface (GUI).
Each HTTP event that the user triggers by some action within the browser
is received in this central procedure. Parameters and menu choices are
-extracted from this request and an appropriate measure is taken according to
+extracted from this request, and an appropriate measure is taken according to
the user's choice.
For example:
@@ -1615,8 +1672,7 @@ is the first run, @code{GETARG["Method"]} is not initialized yet, hence the
case selection over the method does nothing. Now that the home page is
initialized, the server can start communicating to a client browser.
-@cindex RFC 2068
-@cindex CGI
+@c @cindex RFC 2068
It does so by printing the HTTP header into the network connection
(@samp{print @dots{} |& HttpService}). This command blocks execution of
the server script until a client connects. If this server
@@ -1703,7 +1759,6 @@ function HandleGET() @{
@}
@end example
-@cindex CGI
The disadvantage of this approach is that our server is slow and can
handle only one request at a time. Its main advantage, however, is that
the server
@@ -1713,8 +1768,9 @@ consists of just one @command{gawk} program. No need for installing an
This program can be started on the same host that runs your browser.
Then let your browser point to @uref{http://localhost:8080}.
-@cindex @file{xbm} image format
-@cindex image format
+@cindex XBM image format
+@cindex images, in web pages
+@cindex web pages, images in
@cindex GNUPlot utility
It is also possible to include images into the HTML pages.
Most browsers support the not very well-known
@@ -1734,13 +1790,15 @@ Phil Smith III,@*
@uref{http://www.netfunny.com/rhf/jokes/99/Mar/http.html}
@end quotation
+@c STARTOFRANGE cgilib
+@cindex CGI (Common Gateway Interface), library
In @ref{Interacting Service, ,A Web Service with Interaction},
we saw the function @code{CGI_setup} as part of the web server
``core logic'' framework. The code presented there handles almost
everything necessary for CGI requests.
One thing it doesn't do is handle encoded characters in the requests.
For example, an @samp{&} is encoded as a percent sign followed by
-the hexadecimal value---@samp{%26}. These encoded values should be
+the hexadecimal value: @samp{%26}. These encoded values should be
decoded.
Following is a simple library to perform these tasks.
This code is used for all web server examples
@@ -1748,14 +1806,15 @@ used throughout the rest of this @value{DOCUMENT}.
If you want to use it for your own web server, store the source code
into a file named @file{inetlib.awk}. Then you can include
these functions into your code by placing the following statement
-into your program:
+into your program
+(on the first line of your script):
@example
@@include inetlib.awk
@end example
@noindent
-on the first line of your script. But beware, this mechanism is
+But beware, this mechanism is
only possible if you invoke your web server script with @command{igawk}
instead of the usual @command{awk} or @command{gawk}.
Here is the code:
@@ -1896,7 +1955,7 @@ function _CGI_decode(str, hexdigs, i, pre, code1, code2,
@end example
This works by splitting the string apart around an encoded character.
-The two digits are converted to lowercase and looked up in a string
+The two digits are converted to lowercase characters and looked up in a string
of hex digits. Note that @code{0} is not in the string on purpose;
@code{index} returns zero when it's not found, automatically giving
the correct value! Once the hexadecimal value is converted from
@@ -1946,16 +2005,15 @@ p2=stuff%26junk&percent=a %25 sign
@node Simple Server, Caveats, Interacting Service, Using Networking
@section A Simple Web Server
-@cindex GUI
-In the preceding @value{SECTION}, we built the core logic for event driven GUIs.
+@c STARTOFRANGE webserx
+@cindex web servers
+@c STARTOFRANGE serweb
+@cindex servers, web
+In the preceding @value{SECTION}, we built the core logic for event-driven GUIs.
In this @value{SECTION}, we finally extend the core to a real application.
No one would actually write a commercial web server in @command{gawk}, but
it is instructive to see that it is feasible in principle.
-@iftex
-@image{uf002331,4in}
-@end iftex
-
@cindex ELIZA program
@cindex Weizenbaum, Joseph
The application is ELIZA, the famous program by Joseph Weizenbaum that
@@ -2005,7 +2063,6 @@ initialize the HTML pages and some variables. These initializations
determine the way your HTML pages look (colors, titles, menu
items, etc.).
-@cindex GUI
The function @code{HandleGET} is a nested case selection that decides
which page the user wants to see next. Each nesting level refers to a menu
level of the GUI. Each case implements a certain action of the menu. On the
@@ -2049,7 +2106,7 @@ function HandleGET() @{
Now we are down to the heart of ELIZA, so you can see how it works.
Initially the user does not say anything; then ELIZA resets its money
counter and asks the user to tell what comes to mind open heartedly.
-The subsequent answers are converted to uppercase and stored for
+The subsequent answers are converted to uppercase characters and stored for
later comparison. ELIZA presents the bill when being confronted with
a sentence that contains the phrase ``shut up.'' Otherwise, it looks for
keywords in the sentence, conjugates the rest of the sentence, remembers
@@ -2315,7 +2372,6 @@ function SetUpEliza() @{
@cindex Humphrys, Mark
@cindex ELIZA program
-@cindex Yahoo!
Some interesting remarks and details (including the original source code
of ELIZA) are found on Mark Humphrys' home page. Yahoo! also has a
page with a collection of ELIZA-like programs. Many of them are written
@@ -2325,25 +2381,28 @@ explain how to modify the Java source code.
@node Caveats, Challenges, Simple Server, Using Networking
@section Network Programming Caveats
+@cindex networks, @command{gawk} and, troubleshooting
+@cindex @command{gawk}, networking, troubleshooting
+@cindex troubleshooting, @command{gawk}, networks
By now it should be clear
that debugging a networked application is more
complicated than debugging a single-process single-hosted application.
-The behavior of a networked application sometimes looks non-causal because
+The behavior of a networked application sometimes looks noncausal because
it is not reproducible in a strong sense. Whether a network application
works or not sometimes depends on the following:
@itemize @bullet
@item
-How crowded the underlying network is.
+How crowded the underlying network is
@item
-If the party at the other end is running or not.
+If the party at the other end is running or not
@item
-The state of the party at the other end.
+The state of the party at the other end
@end itemize
-@cindex network
+@cindex troubleshooting, networks, timeouts
The most difficult problems for a beginner arise from the hidden states of the
underlying network. After closing a TCP connection, it's often necessary to wait
a short while before reopening the connection. Even more difficult is the
@@ -2357,7 +2416,7 @@ provides a list of still ``active'' connections.
@section Where To Go From Here
@cindex Loebner, Hugh
-@cindex Contest
+@cindex contest
Now, you have learned enough to build your own application. You could,
for example, take part in the
Loebner Contest
@@ -2434,7 +2493,7 @@ some passages from the text:
@cindex AI
@cindex PROLOG
-@cindex Loui, Ronald P.
+@cindex Loui, Ronald
@cindex agent
@quotation
The GAWK manual can
@@ -2517,22 +2576,21 @@ explore leading edge technology that may shape the future of networking.
We often refer to the site-independent core of the server that
we built in
@ref{Simple Server, ,A Simple Web Server}.
-When building new and non-trivial servers, we
+When building new and nontrivial servers, we
always copy this building block and append new instances of the two
functions @code{SetUpServer} and @code{HandleGET}.
This makes a lot of sense, since
this scheme of event-driven
execution provides @command{gawk} with an interface to the most widely
-accepted standard for GUIs: the web browser. Now, @command{gawk} can even rival
+accepted standard for GUIs: the web browser. Now, @command{gawk} can rival even
Tcl/Tk.
-@cindex Tcl/Tk
-@cindex JavaScript
+@cindex Tcl/Tk, @command{gawk} and
Tcl and @command{gawk} have much in common. Both are simple scripting languages
that allow us to quickly solve problems with short programs. But Tcl has Tk
-on top of it and @command{gawk} had nothing comparable up to now. While Tcl
-needs a large and ever changing library (Tk, which was bound to the X Window
+on top of it, and @command{gawk} had nothing comparable up to now. While Tcl
+needs a large and ever-changing library (Tk, which was bound to the X Window
System until recently), @command{gawk} needs just the networking interface
and some kind of browser on the client's side. Besides better portability,
the most important advantage of this approach (embracing well-established
@@ -2554,8 +2612,10 @@ We can use HTML, JavaScript, VRML, or whatever else comes along to do our work.
@end menu
@node PANIC, GETURL, Some Applications and Techniques, Some Applications and Techniques
-@section PANIC: an Emergency Web Server
+@section PANIC: An Emergency Web Server
@cindex PANIC program
+@cindex networks, See Also web pages
+@cindex web service
At first glance, the @code{"Hello, world"} example in
@ref{Primitive Service, ,A Primitive Web Service},
seems useless. By adding just a few lines, we can turn it into something useful.
@@ -2599,7 +2659,7 @@ BEGIN @{
@node GETURL, REMCONF, PANIC, Some Applications and Techniques
@section GETURL: Retrieving Web Pages
@cindex GETURL program
-@cindex robot
+@cindex web pages, retrieving
GETURL is a versatile building block for shell scripts that need to retrieve
files from the Internet. It takes a web address as a command-line parameter and
tries to retrieve the contents of this address. The contents are printed
@@ -2995,9 +3055,9 @@ sure that none of the above reveals too much information about your system.
@cindex GNUPlot utility
@cindex image format
-@cindex @file{gif} image format
-@cindex @file{png} image format
-@cindex @file{ps} image format
+@cindex GIF image format
+@cindex PNG image format
+@cindex PS image format
@cindex Boutell, Thomas
@iftex
@image{statist,3in}
@@ -3529,7 +3589,7 @@ of the server's CGI script. So, to implement a mobile agent,
we must not only write the agent program to start on the client
side, but also the CGI script to receive the agent on the server side.
-@cindex CGI
+@cindex CGI (Common Gateway Interface)
@cindex apache
@item
The @code{PUT} method can also be used for migration. HTTP does not
@@ -3822,7 +3882,7 @@ the originating host, whose name is stored in @code{MOBVAR["MyOrigin"]}.
@node STOXPRED, PROTBASE, MOBAGWHO, Some Applications and Techniques
@section STOXPRED: Stock Market Prediction As A Service
@cindex STOXPRED program
-@cindex Yahoo
+@cindex Yahoo!
@quotation
@i{Far out in the uncharted backwaters of the unfashionable end of
the Western Spiral arm of the Galaxy lies a small unregarded yellow sun.}
@@ -3841,7 +3901,7 @@ were unhappy.} @*
Douglas Adams, @cite{The Hitch Hiker's Guide to the Galaxy}
@end quotation
-@cindex @command{cron}
+@cindex @command{cron} utility
Valuable services on the Internet are usually @emph{not} implemented
as mobile agents. There are much simpler ways of implementing services.
All Unix systems provide, for example, the @command{cron} service.
diff --git a/doc/texinfo.tex b/doc/texinfo.tex
index 0b5b9033..df62a127 100644
--- a/doc/texinfo.tex
+++ b/doc/texinfo.tex
@@ -3,10 +3,10 @@
% Load plain if necessary, i.e., if running under initex.
\expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi
%
-\def\texinfoversion{2001-03-28.08}
+\def\texinfoversion{2002-03-26.08}
%
% Copyright (C) 1985, 86, 88, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99,
-% 2000, 01 Free Software Foundation, Inc.
+% 2000, 01, 02 Free Software Foundation, Inc.
%
% This texinfo.tex file is free software; you can redistribute it and/or
% modify it under the terms of the GNU General Public License as
@@ -30,14 +30,17 @@
% Please try the latest version of texinfo.tex before submitting bug
% reports; you can get the latest version from:
% ftp://ftp.gnu.org/gnu/texinfo.tex
-% (and all GNU mirrors, see http://www.gnu.org/order/ftp.html)
-% ftp://texinfo.org/tex/texinfo.tex
-% ftp://us.ctan.org/macros/texinfo/texinfo.tex
-% (and all CTAN mirrors, finger ctan@us.ctan.org for a list).
-% /home/gd/gnu/doc/texinfo.tex on the GNU machines.
+% (and all GNU mirrors, see http://www.gnu.org/order/ftp.html)
+% ftp://texinfo.org/texinfo/texinfo.tex
+% ftp://tug.org/tex/texinfo.tex
+% (and all CTAN mirrors, see http://www.ctan.org),
+% and /home/gd/gnu/doc/texinfo.tex on the GNU machines.
+%
% The texinfo.tex in any given Texinfo distribution could well be out
% of date, so if that's what you're using, please check.
-% Texinfo has a small home page at http://texinfo.org/.
+%
+% Texinfo has a small home page at http://texinfo.org/ and also
+% http://www.gnu.org/software/texinfo.
%
% Send bug reports to bug-texinfo@gnu.org. Please include including a
% complete document in each bug report with which we can reproduce the
@@ -50,13 +53,13 @@
% texindex foo.??
% tex foo.texi
% tex foo.texi
-% dvips foo.dvi -o # or whatever, to process the dvi file; this makes foo.ps.
-% The extra runs of TeX get the cross-reference information correct.
+% dvips foo.dvi -o # or whatever; this makes foo.ps.
+% The extra TeX runs get the cross-reference information correct.
% Sometimes one run after texindex suffices, and sometimes you need more
% than two; texi2dvi does it as many times as necessary.
%
% It is possible to adapt texinfo.tex for other languages. You can get
-% the existing language-specific files from ftp://ftp.gnu.org/gnu/texinfo/.
+% the existing language-specific files from the full Texinfo distribution.
\message{Loading texinfo [version \texinfoversion]:}
@@ -170,6 +173,16 @@
}%
\fi
+% add check for \lastpenalty to plain's definitions. If the last thing
+% we did was a \nobreak, we don't want to insert more space.
+%
+\def\smallbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\smallskipamount
+ \removelastskip\penalty-50\smallskip\fi\fi}
+\def\medbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\medskipamount
+ \removelastskip\penalty-100\medskip\fi\fi}
+\def\bigbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\bigskipamount
+ \removelastskip\penalty-200\bigskip\fi\fi}
+
% For @cropmarks command.
% Do @cropmarks to get crop marks.
%
@@ -431,7 +444,7 @@
% environments. --karl, 6may93
%{\advance \baselineskip by -\singlespaceskip
%\kern \baselineskip}%
- \setleading \singlespaceskip
+ \setleading\singlespaceskip
}
%% Simple single-character @ commands
@@ -823,18 +836,43 @@ where each line of input produces a line of output.}
%
\def\asis#1{#1}
-% @math means output in math mode.
-% We don't use $'s directly in the definition of \math because control
-% sequences like \math are expanded when the toc file is written. Then,
-% we read the toc file back, the $'s will be normal characters (as they
-% should be, according to the definition of Texinfo). So we must use a
-% control sequence to switch into and out of math mode.
+% @math outputs its argument in math mode.
+% We don't use $'s directly in the definition of \math because we need
+% to set catcodes according to plain TeX first, to allow for subscripts,
+% superscripts, special math chars, etc.
+%
+% @math does not do math typesetting in section titles, index
+% entries, and other such contexts where the catcodes are set before
+% @math gets a chance to work. This could perhaps be fixed, but for now
+% at least we can have real math in the main text, where it's needed most.
+%
+\let\implicitmath = $%$ font-lock fix
+%
+% One complication: _ usually means subscripts, but it could also mean
+% an actual _ character, as in @math{@var{some_variable} + 1}. So make
+% _ within @math be active (mathcode "8000), and distinguish by seeing
+% if the current family is \slfam, which is what @var uses.
+%
+{\catcode95 = \active % 95 = _
+\gdef\mathunderscore{%
+ \catcode95=\active
+ \def_{\ifnum\fam=\slfam \_\else\sb\fi}%
+}}
%
-% This isn't quite enough for @math to work properly in indices, but it
-% seems unlikely it will ever be needed there.
+% Another complication: we want \\ (and @\) to output a \ character.
+% FYI, plain.tex uses \\ as a temporary control sequence (why?), but
+% this is not advertised and we don't care. Texinfo does not
+% otherwise define @\.
+%
+% The \mathchar is class=0=ordinary, family=7=ttfam, position=5C=\.
+\def\mathbackslash{\ifnum\fam=\ttfam \mathchar"075C \else\backslash \fi}
%
-\let\implicitmath = $
-\def\math#1{\implicitmath #1\implicitmath}
+\def\math{%
+ \tex
+ \mathcode`\_="8000 \mathunderscore
+ \let\\ = \mathbackslash
+ \implicitmath\finishmath}
+\def\finishmath#1{#1\implicitmath\Etex}
% @bullet and @minus need the same treatment as @math, just above.
\def\bullet{\implicitmath\ptexbullet\implicitmath}
@@ -917,10 +955,12 @@ where each line of input produces a line of output.}
\def\dopdfimage#1#2#3{%
\def\imagewidth{#2}%
\def\imageheight{#3}%
+ % without \immediate, pdftex seg faults when the same image is
+ % included twice. (Version 3.14159-pre-1.0-unofficial-20010704.)
\ifnum\pdftexversion < 14
- \pdfimage
+ \immediate\pdfimage
\else
- \pdfximage
+ \immediate\pdfximage
\fi
\ifx\empty\imagewidth\else width \imagewidth \fi
\ifx\empty\imageheight\else height \imageheight \fi
@@ -932,8 +972,8 @@ where each line of input produces a line of output.}
\ifnum\pdftexversion < 14 \else
\pdfrefximage \pdflastximage
\fi}
- \def\pdfmkdest#1{\pdfdest name{#1} xyz}
- \def\pdfmkpgn#1{#1@}
+ \def\pdfmkdest#1{{\normalturnoffactive \pdfdest name{#1} xyz}}
+ \def\pdfmkpgn#1{#1}
\let\linkcolor = \Blue % was Cyan, but that seems light?
\def\endlink{\Black\pdfendlink}
% Adding outlines to PDF; macros for calculating structure of outlines
@@ -945,7 +985,7 @@ where each line of input produces a line of output.}
\expandafter\xdef\csname#1\endcsname{\the\tempnum}}
\def\pdfmakeoutlines{{%
\openin 1 \jobname.toc
- \ifeof 1\else\bgroup
+ \ifeof 1\else\begingroup
\closein 1
\indexnofonts
\def\tt{}
@@ -955,32 +995,34 @@ where each line of input produces a line of output.}
\edef\myrbrace{\iffalse{\else\string}\fi}\let\}=\myrbrace
%
\def\chapentry ##1##2##3{}
+ \let\appendixentry = \chapentry
\def\unnumbchapentry ##1##2{}
\def\secentry ##1##2##3##4{\advancenumber{chap##2}}
- \def\unnumbsecentry ##1##2{}
+ \def\unnumbsecentry ##1##2##3{\advancenumber{chap##2}}
\def\subsecentry ##1##2##3##4##5{\advancenumber{sec##2.##3}}
- \def\unnumbsubsecentry ##1##2{}
+ \def\unnumbsubsecentry ##1##2##3##4{\advancenumber{sec##2.##3}}
\def\subsubsecentry ##1##2##3##4##5##6{\advancenumber{subsec##2.##3.##4}}
- \def\unnumbsubsubsecentry ##1##2{}
+ \def\unnumbsubsubsecentry ##1##2##3##4##5{\advancenumber{subsec##2.##3.##4}}
\input \jobname.toc
\def\chapentry ##1##2##3{%
\pdfoutline goto name{\pdfmkpgn{##3}}count-\expnumber{chap##2}{##1}}
+ \let\appendixentry = \chapentry
\def\unnumbchapentry ##1##2{%
\pdfoutline goto name{\pdfmkpgn{##2}}{##1}}
\def\secentry ##1##2##3##4{%
\pdfoutline goto name{\pdfmkpgn{##4}}count-\expnumber{sec##2.##3}{##1}}
- \def\unnumbsecentry ##1##2{%
- \pdfoutline goto name{\pdfmkpgn{##2}}{##1}}
+ \def\unnumbsecentry ##1##2##3{%
+ \pdfoutline goto name{\pdfmkpgn{##3}}{##1}}
\def\subsecentry ##1##2##3##4##5{%
\pdfoutline goto name{\pdfmkpgn{##5}}count-\expnumber{subsec##2.##3.##4}{##1}}
- \def\unnumbsubsecentry ##1##2{%
- \pdfoutline goto name{\pdfmkpgn{##2}}{##1}}
+ \def\unnumbsubsecentry ##1##2##3##4{%
+ \pdfoutline goto name{\pdfmkpgn{##4}}{##1}}
\def\subsubsecentry ##1##2##3##4##5##6{%
\pdfoutline goto name{\pdfmkpgn{##6}}{##1}}
- \def\unnumbsubsubsecentry ##1##2{%
- \pdfoutline goto name{\pdfmkpgn{##2}}{##1}}
+ \def\unnumbsubsubsecentry ##1##2##3##4##5{%
+ \pdfoutline goto name{\pdfmkpgn{##5}}{##1}}
\input \jobname.toc
- \egroup\fi
+ \endgroup\fi
}}
\def\makelinks #1,{%
\def\params{#1}\def\E{END}%
@@ -1030,6 +1072,7 @@ where each line of input produces a line of output.}
\def\pdfurl#1{%
\begingroup
\normalturnoffactive\def\@{@}%
+ \let\value=\expandablevalue
\leavevmode\Red
\startlink attr{/Border [0 0 0]}%
user{/Subtype /Link /A << /S /URI /URI (#1) >>}%
@@ -1057,9 +1100,8 @@ where each line of input produces a line of output.}
\def\makelink{\addtokens{\toksB}%
{\noexpand\pdflink{\the\toksC}}\toksC={}\global\countA=0}
\def\pdflink#1{%
- \startlink attr{/Border [0 0 0]} goto name{\mkpgn{#1}}
+ \startlink attr{/Border [0 0 0]} goto name{\pdfmkpgn{#1}}
\linkcolor #1\endlink}
- \def\mkpgn#1{#1@}
\def\done{\edef\st{\global\noexpand\toksA={\the\toksB}}\st}
\fi % \ifx\pdfoutput
@@ -1076,9 +1118,26 @@ where each line of input produces a line of output.}
% We don't need math for this one.
\def\ttsl{\tenttsl}
-% Use Computer Modern fonts at \magstephalf (11pt).
-\newcount\mainmagstep
-\mainmagstep=\magstephalf
+% Default leading.
+\newdimen\textleading \textleading = 13.2pt
+
+% Set the baselineskip to #1, and the lineskip and strut size
+% correspondingly. There is no deep meaning behind these magic numbers
+% used as factors; they just match (closely enough) what Knuth defined.
+%
+\def\lineskipfactor{.08333}
+\def\strutheightpercent{.70833}
+\def\strutdepthpercent {.29167}
+%
+\def\setleading#1{%
+ \normalbaselineskip = #1\relax
+ \normallineskip = \lineskipfactor\normalbaselineskip
+ \normalbaselines
+ \setbox\strutbox =\hbox{%
+ \vrule width0pt height\strutheightpercent\baselineskip
+ depth \strutdepthpercent \baselineskip
+ }%
+}
% Set the font macro #1 to the font named #2, adding on the
% specified font prefix (normally `cm').
@@ -1108,13 +1167,16 @@ where each line of input produces a line of output.}
\def\scshape{csc}
\def\scbshape{csc}
+\newcount\mainmagstep
\ifx\bigger\relax
-\let\mainmagstep=\magstep1
-\setfont\textrm\rmshape{12}{1000}
-\setfont\texttt\ttshape{12}{1000}
+ % not really supported.
+ \let\mainmagstep=\magstep1
+ \setfont\textrm\rmshape{12}{1000}
+ \setfont\texttt\ttshape{12}{1000}
\else
-\setfont\textrm\rmshape{10}{\mainmagstep}
-\setfont\texttt\ttshape{10}{\mainmagstep}
+ \mainmagstep=\magstephalf
+ \setfont\textrm\rmshape{10}{\mainmagstep}
+ \setfont\texttt\ttshape{10}{\mainmagstep}
\fi
% Instead of cmb10, you many want to use cmbx10.
% cmbx10 is a prettier font on its own, but cmb10
@@ -1145,6 +1207,18 @@ where each line of input produces a line of output.}
\font\smalli=cmmi9
\font\smallsy=cmsy9
+% Fonts for small examples (8pt).
+\setfont\smallerrm\rmshape{8}{1000}
+\setfont\smallertt\ttshape{8}{1000}
+\setfont\smallerbf\bfshape{10}{800}
+\setfont\smallerit\itshape{8}{1000}
+\setfont\smallersl\slshape{8}{1000}
+\setfont\smallersf\sfshape{8}{1000}
+\setfont\smallersc\scshape{10}{800}
+\setfont\smallerttsl\ttslshape{10}{800}
+\font\smalleri=cmmi8
+\font\smallersy=cmsy8
+
% Fonts for title page:
\setfont\titlerm\rmbshape{12}{\magstep3}
\setfont\titleit\itbshape{10}{\magstep4}
@@ -1182,20 +1256,6 @@ where each line of input produces a line of output.}
\font\seci=cmmi12 scaled \magstep1
\font\secsy=cmsy10 scaled \magstep2
-% \setfont\ssecrm\bxshape{10}{\magstep1} % This size an font looked bad.
-% \setfont\ssecit\itshape{10}{\magstep1} % The letters were too crowded.
-% \setfont\ssecsl\slshape{10}{\magstep1}
-% \setfont\ssectt\ttshape{10}{\magstep1}
-% \setfont\ssecsf\sfshape{10}{\magstep1}
-
-%\setfont\ssecrm\bfshape{10}{1315} % Note the use of cmb rather than cmbx.
-%\setfont\ssecit\itshape{10}{1315} % Also, the size is a little larger than
-%\setfont\ssecsl\slshape{10}{1315} % being scaled magstep1.
-%\setfont\ssectt\ttshape{10}{1315}
-%\setfont\ssecsf\sfshape{10}{1315}
-
-%\let\ssecbf=\ssecrm
-
% Subsection fonts (13.15pt).
\setfont\ssecrm\rmbshape{12}{\magstephalf}
\setfont\ssecit\itbshape{10}{1315}
@@ -1212,17 +1272,16 @@ where each line of input produces a line of output.}
% In order for the font changes to affect most math symbols and letters,
% we have to define the \textfont of the standard families. Since
-% texinfo doesn't allow for producing subscripts and superscripts, we
-% don't bother to reset \scriptfont and \scriptscriptfont (which would
-% also require loading a lot more fonts).
+% texinfo doesn't allow for producing subscripts and superscripts except
+% in the main text, we don't bother to reset \scriptfont and
+% \scriptscriptfont (which would also require loading a lot more fonts).
%
\def\resetmathfonts{%
- \textfont0 = \tenrm \textfont1 = \teni \textfont2 = \tensy
- \textfont\itfam = \tenit \textfont\slfam = \tensl \textfont\bffam = \tenbf
- \textfont\ttfam = \tentt \textfont\sffam = \tensf
+ \textfont0=\tenrm \textfont1=\teni \textfont2=\tensy
+ \textfont\itfam=\tenit \textfont\slfam=\tensl \textfont\bffam=\tenbf
+ \textfont\ttfam=\tentt \textfont\sffam=\tensf
}
-
% The font-changing commands redefine the meanings of \tenSTYLE, instead
% of just \STYLE. We do this so that font changes will continue to work
% in math mode, where it is the current \fam that is relevant in most
@@ -1233,7 +1292,7 @@ where each line of input produces a line of output.}
\let\tenrm=\textrm \let\tenit=\textit \let\tensl=\textsl
\let\tenbf=\textbf \let\tentt=\texttt \let\smallcaps=\textsc
\let\tensf=\textsf \let\teni=\texti \let\tensy=\textsy \let\tenttsl=\textttsl
- \resetmathfonts}
+ \resetmathfonts \setleading{\textleading}}
\def\titlefonts{%
\let\tenrm=\titlerm \let\tenit=\titleit \let\tensl=\titlesl
\let\tenbf=\titlebf \let\tentt=\titlett \let\smallcaps=\titlesc
@@ -1262,7 +1321,14 @@ where each line of input produces a line of output.}
\let\tenbf=\smallbf \let\tentt=\smalltt \let\smallcaps=\smallsc
\let\tensf=\smallsf \let\teni=\smalli \let\tensy=\smallsy
\let\tenttsl=\smallttsl
- \resetmathfonts \setleading{11pt}}
+ \resetmathfonts \setleading{10.5pt}}
+\def\smallerfonts{%
+ \let\tenrm=\smallerrm \let\tenit=\smallerit \let\tensl=\smallersl
+ \let\tenbf=\smallerbf \let\tentt=\smallertt \let\smallcaps=\smallersc
+ \let\tensf=\smallersf \let\teni=\smalleri \let\tensy=\smallersy
+ \let\tenttsl=\smallerttsl
+ \resetmathfonts \setleading{9.5pt}}
+\let\smallexamplefonts = \smallerfonts
% Set up the default fonts, so we can use them for creating boxes.
%
@@ -1376,11 +1442,19 @@ where each line of input produces a line of output.}
\def\realdash{-}
\def\codedash{-\discretionary{}{}{}}
-\def\codeunder{\ifusingtt{\normalunderscore\discretionary{}{}{}}{\_}}
+\def\codeunder{%
+ % this is all so @math{@code{var_name}+1} can work. In math mode, _
+ % is "active" (mathcode"8000) and \normalunderscore (or \char95, etc.)
+ % will therefore expand the active definition of _, which is us
+ % (inside @code that is), therefore an endless loop.
+ \ifusingtt{\ifmmode
+ \mathchar"075F % class 0=ordinary, family 7=ttfam, pos 0x5F=_.
+ \else\normalunderscore \fi
+ \discretionary{}{}{}}%
+ {\_}%
+}
\def\codex #1{\tclose{#1}\endgroup}
-%\let\exp=\tclose %Was temporary
-
% @kbd is like @code, except that if the argument is just one @key command,
% then @kbd has no effect.
@@ -1565,6 +1639,10 @@ where each line of input produces a line of output.}
\oldpage
\endgroup
%
+ % Need this before the \...aftertitlepage checks so that if they are
+ % in effect the toc pages will come out with page numbers.
+ \HEADINGSon
+ %
% If they want short, they certainly want long too.
\ifsetshortcontentsaftertitlepage
\shortcontents
@@ -1578,10 +1656,6 @@ where each line of input produces a line of output.}
\global\let\contents = \relax
\global\let\shortcontents = \relax
\fi
- %
- \ifpdf \pdfmakepagedesttrue \fi
- %
- \HEADINGSon
}
\def\finishtitlepage{%
@@ -2339,18 +2413,19 @@ width0pt\relax} \fi
\let\item = \relax
}
-% Ignore @ignore ... @end ignore.
+% Ignore @ignore, @ifhtml, @ifinfo, @ifplaintext, @ifnottex, @html, @menu,
+% @direntry, and @documentdescription.
%
\def\ignore{\doignore{ignore}}
-
-% Ignore @ifinfo, @ifhtml, @ifnottex, @html, @menu, and @direntry text.
-%
-\def\ifinfo{\doignore{ifinfo}}
\def\ifhtml{\doignore{ifhtml}}
+\def\ifinfo{\doignore{ifinfo}}
+\def\ifplaintext{\doignore{ifplaintext}}
\def\ifnottex{\doignore{ifnottex}}
\def\html{\doignore{html}}
\def\menu{\doignore{menu}}
\def\direntry{\doignore{direntry}}
+\def\documentdescription{\doignore{documentdescription}}
+\def\documentdescriptionword{documentdescription}
% @dircategory CATEGORY -- specify a category of the dir file
% which this file should belong to. Ignore this in TeX.
@@ -2377,14 +2452,21 @@ width0pt\relax} \fi
% We must not have @c interpreted as a control sequence.
\catcode`\@ = 12
%
- % Make the letter c a comment character so that the rest of the line
- % will be ignored. This way, the document can have (for example)
- % @c @end ifinfo
- % and the @end ifinfo will be properly ignored.
- % (We've just changed @ to catcode 12.)
- \catcode`\c = 14
+ \def\ignoreword{#1}%
+ \ifx\ignoreword\documentdescriptionword
+ % The c kludge breaks documentdescription, since
+ % `documentdescription' contains a `c'. Means not everything will
+ % be ignored inside @documentdescription, but oh well...
+ \else
+ % Make the letter c a comment character so that the rest of the line
+ % will be ignored. This way, the document can have (for example)
+ % @c @end ifinfo
+ % and the @end ifinfo will be properly ignored.
+ % (We've just changed @ to catcode 12.)
+ \catcode`\c = 14
+ \fi
%
- % And now expand that command.
+ % And now expand the command defined above.
\doignoretext
}
@@ -2456,10 +2538,14 @@ width0pt\relax} \fi
\let\tenrm=\nullfont \let\tenit=\nullfont \let\tensl=\nullfont
\let\tenbf=\nullfont \let\tentt=\nullfont \let\smallcaps=\nullfont
\let\tensf=\nullfont
- % Similarly for index fonts (mostly for their use in smallexample).
+ % Similarly for index fonts.
\let\smallrm=\nullfont \let\smallit=\nullfont \let\smallsl=\nullfont
\let\smallbf=\nullfont \let\smalltt=\nullfont \let\smallsc=\nullfont
\let\smallsf=\nullfont
+ % Similarly for smallexample fonts.
+ \let\smallerrm=\nullfont \let\smallerit=\nullfont \let\smallersl=\nullfont
+ \let\smallerbf=\nullfont \let\smallertt=\nullfont \let\smallersc=\nullfont
+ \let\smallersf=\nullfont
%
% Don't complain when characters are missing from the fonts.
\tracinglostchars = 0
@@ -2571,19 +2657,21 @@ width0pt\relax} \fi
\def\ifclearfail{\nestedignore{ifclear}}
\defineunmatchedend{ifclear}
-% @iftex, @ifnothtml, @ifnotinfo always succeed; we read the text
-% following, through the first @end iftex (etc.). Make `@end iftex'
-% (etc.) valid only after an @iftex.
+% @iftex, @ifnothtml, @ifnotinfo, @ifnotplaintext always succeed; we
+% read the text following, through the first @end iftex (etc.). Make
+% `@end iftex' (etc.) valid only after an @iftex.
%
\def\iftex{\conditionalsucceed{iftex}}
\def\ifnothtml{\conditionalsucceed{ifnothtml}}
\def\ifnotinfo{\conditionalsucceed{ifnotinfo}}
+\def\ifnotplaintext{\conditionalsucceed{ifnotplaintext}}
\defineunmatchedend{iftex}
\defineunmatchedend{ifnothtml}
\defineunmatchedend{ifnotinfo}
+\defineunmatchedend{ifnotplaintext}
-% We can't just want to start a group at @iftex (for example) and end it
-% at @end iftex, since then @set commands inside the conditional have no
+% We can't just want to start a group at @iftex (etc.) and end it at
+% @end iftex, since then @set commands inside the conditional have no
% effect (they'd get reverted at the end of the group). So we must
% define \Eiftex to redefine itself to be its previous value. (We can't
% just define it to fail again with an ``unmatched end'' error, since
@@ -2696,9 +2784,23 @@ width0pt\relax} \fi
\def\docodeindex#1{\edef\indexname{#1}\parsearg\singlecodeindexer}
\def\singlecodeindexer #1{\doind{\indexname}{\code{#1}}}
+% Take care of texinfo commands likely to appear in an index entry.
+% (Must be a way to avoid doing expansion at all, and thus not have to
+% laboriously list every single command here.)
+%
\def\indexdummies{%
\def\ { }%
+\def\@{@}% change to @@ when we switch to @ as escape char in aux files.
+% Need these in case \tex is in effect and \{ is a \delimiter again.
+% But can't use \lbracecmd and \rbracecmd because texindex assumes
+% braces and backslashes are used only as delimiters.
+\let\{ = \mylbrace
+\let\} = \myrbrace
+\def\_{{\realbackslash _}}%
+\normalturnoffactive
+%
% Take care of the plain tex accent commands.
+\def\,##1{\realbackslash ,{##1}}%
\def\"{\realbackslash "}%
\def\`{\realbackslash `}%
\def\'{\realbackslash '}%
@@ -2711,69 +2813,66 @@ width0pt\relax} \fi
\def\u{\realbackslash u}%
\def\v{\realbackslash v}%
\def\H{\realbackslash H}%
+\def\dotless##1{\realbackslash dotless {##1}}%
% Take care of the plain tex special European modified letters.
-\def\oe{\realbackslash oe}%
-\def\ae{\realbackslash ae}%
-\def\aa{\realbackslash aa}%
-\def\OE{\realbackslash OE}%
-\def\AE{\realbackslash AE}%
\def\AA{\realbackslash AA}%
-\def\o{\realbackslash o}%
+\def\AE{\realbackslash AE}%
+\def\L{\realbackslash L}%
+\def\OE{\realbackslash OE}%
\def\O{\realbackslash O}%
+\def\aa{\realbackslash aa}%
+\def\ae{\realbackslash ae}%
\def\l{\realbackslash l}%
-\def\L{\realbackslash L}%
+\def\oe{\realbackslash oe}%
+\def\o{\realbackslash o}%
\def\ss{\realbackslash ss}%
-% Take care of texinfo commands likely to appear in an index entry.
-% (Must be a way to avoid doing expansion at all, and thus not have to
-% laboriously list every single command here.)
-\def\@{@}% will be @@ when we switch to @ as escape char.
-% Need these in case \tex is in effect and \{ is a \delimiter again.
-% But can't use \lbracecmd and \rbracecmd because texindex assumes
-% braces and backslashes are used only as delimiters.
-\let\{ = \mylbrace
-\let\} = \myrbrace
-\def\_{{\realbackslash _}}%
-\def\w{\realbackslash w }%
+%
+% Although these internals commands shouldn't show up, sometimes they do.
\def\bf{\realbackslash bf }%
+\def\gtr{\realbackslash gtr}%
+\def\hat{\realbackslash hat}%
+\def\less{\realbackslash less}%
%\def\rm{\realbackslash rm }%
-\def\sl{\realbackslash sl }%
\def\sf{\realbackslash sf}%
+\def\sl{\realbackslash sl }%
+\def\tclose##1{\realbackslash tclose {##1}}%
\def\tt{\realbackslash tt}%
-\def\gtr{\realbackslash gtr}%
-\def\less{\realbackslash less}%
-\def\hat{\realbackslash hat}%
+%
+\def\b##1{\realbackslash b {##1}}%
+\def\i##1{\realbackslash i {##1}}%
+\def\sc##1{\realbackslash sc {##1}}%
+\def\t##1{\realbackslash t {##1}}%
+\def\r##1{\realbackslash r {##1}}%
+%
\def\TeX{\realbackslash TeX}%
-\def\dots{\realbackslash dots }%
-\def\result{\realbackslash result}%
-\def\equiv{\realbackslash equiv}%
-\def\expansion{\realbackslash expansion}%
-\def\print{\realbackslash print}%
-\def\error{\realbackslash error}%
-\def\point{\realbackslash point}%
-\def\copyright{\realbackslash copyright}%
-\def\tclose##1{\realbackslash tclose {##1}}%
+\def\acronym##1{\realbackslash acronym {##1}}%
+\def\cite##1{\realbackslash cite {##1}}%
\def\code##1{\realbackslash code {##1}}%
-\def\uref##1{\realbackslash uref {##1}}%
-\def\url##1{\realbackslash url {##1}}%
-\def\env##1{\realbackslash env {##1}}%
\def\command##1{\realbackslash command {##1}}%
+\def\dfn##1{\realbackslash dfn {##1}}%
+\def\dots{\realbackslash dots }%
+\def\emph##1{\realbackslash emph {##1}}%
+\def\env##1{\realbackslash env {##1}}%
+\def\file##1{\realbackslash file {##1}}%
+\def\kbd##1{\realbackslash kbd {##1}}%
+\def\key##1{\realbackslash key {##1}}%
+\def\math##1{\realbackslash math {##1}}%
\def\option##1{\realbackslash option {##1}}%
-\def\dotless##1{\realbackslash dotless {##1}}%
\def\samp##1{\realbackslash samp {##1}}%
-\def\,##1{\realbackslash ,{##1}}%
-\def\t##1{\realbackslash t {##1}}%
-\def\r##1{\realbackslash r {##1}}%
-\def\i##1{\realbackslash i {##1}}%
-\def\b##1{\realbackslash b {##1}}%
-\def\sc##1{\realbackslash sc {##1}}%
-\def\cite##1{\realbackslash cite {##1}}%
-\def\key##1{\realbackslash key {##1}}%
-\def\file##1{\realbackslash file {##1}}%
+\def\strong##1{\realbackslash strong {##1}}%
+\def\uref##1{\realbackslash uref {##1}}%
+\def\url##1{\realbackslash url {##1}}%
\def\var##1{\realbackslash var {##1}}%
-\def\kbd##1{\realbackslash kbd {##1}}%
-\def\dfn##1{\realbackslash dfn {##1}}%
-\def\emph##1{\realbackslash emph {##1}}%
-\def\acronym##1{\realbackslash acronym {##1}}%
+\def\w{\realbackslash w }%
+%
+% These math commands don't seem likely to be used in index entries.
+\def\copyright{\realbackslash copyright}%
+\def\equiv{\realbackslash equiv}%
+\def\error{\realbackslash error}%
+\def\expansion{\realbackslash expansion}%
+\def\point{\realbackslash point}%
+\def\print{\realbackslash print}%
+\def\result{\realbackslash result}%
%
% Handle some cases of @value -- where the variable name does not
% contain - or _, and the value does not contain any
@@ -2787,7 +2886,7 @@ width0pt\relax} \fi
% If an index command is used in an @example environment, any spaces
% therein should become regular spaces in the raw index file, not the
-% expansion of \tie (\\leavevmode \penalty \@M \ ).
+% expansion of \tie (\leavevmode \penalty \@M \ ).
{\obeyspaces
\gdef\unsepspaces{\obeyspaces\let =\space}}
@@ -2798,7 +2897,10 @@ width0pt\relax} \fi
\def\indexdummydots{...}
\def\indexnofonts{%
-% Just ignore accents.
+\def\@{@}%
+% how to handle braces?
+\def\_{\normalunderscore}%
+%
\let\,=\indexdummyfont
\let\"=\indexdummyfont
\let\`=\indexdummyfont
@@ -2814,45 +2916,49 @@ width0pt\relax} \fi
\let\H=\indexdummyfont
\let\dotless=\indexdummyfont
% Take care of the plain tex special European modified letters.
-\def\oe{oe}%
-\def\ae{ae}%
-\def\aa{aa}%
-\def\OE{OE}%
-\def\AE{AE}%
\def\AA{AA}%
-\def\o{o}%
+\def\AE{AE}%
+\def\L{L}%
+\def\OE{OE}%
\def\O{O}%
+\def\aa{aa}%
+\def\ae{ae}%
\def\l{l}%
-\def\L{L}%
+\def\oe{oe}%
+\def\o{o}%
\def\ss{ss}%
-\let\w=\indexdummyfont
-\let\t=\indexdummyfont
-\let\r=\indexdummyfont
-\let\i=\indexdummyfont
+%
+% Don't no-op \tt, since it isn't a user-level command
+% and is used in the definitions of the active chars like <, >, |, etc.
+% Likewise with the other plain tex font commands.
+%\let\tt=\indexdummyfont
+%
\let\b=\indexdummyfont
-\let\emph=\indexdummyfont
-\let\strong=\indexdummyfont
-\let\cite=\indexdummyfont
+\let\i=\indexdummyfont
+\let\r=\indexdummyfont
\let\sc=\indexdummyfont
-%Don't no-op \tt, since it isn't a user-level command
-% and is used in the definitions of the active chars like <, >, |...
-%\let\tt=\indexdummyfont
-\let\tclose=\indexdummyfont
-\let\code=\indexdummyfont
-\let\url=\indexdummyfont
-\let\uref=\indexdummyfont
-\let\env=\indexdummyfont
+\let\t=\indexdummyfont
+%
+\let\TeX=\indexdummytex
\let\acronym=\indexdummyfont
+\let\cite=\indexdummyfont
+\let\code=\indexdummyfont
\let\command=\indexdummyfont
-\let\option=\indexdummyfont
+\let\dfn=\indexdummyfont
+\let\dots=\indexdummydots
+\let\emph=\indexdummyfont
+\let\env=\indexdummyfont
\let\file=\indexdummyfont
-\let\samp=\indexdummyfont
\let\kbd=\indexdummyfont
\let\key=\indexdummyfont
+\let\math=\indexdummyfont
+\let\option=\indexdummyfont
+\let\samp=\indexdummyfont
+\let\strong=\indexdummyfont
+\let\uref=\indexdummyfont
+\let\url=\indexdummyfont
\let\var=\indexdummyfont
-\let\TeX=\indexdummytex
-\let\dots=\indexdummydots
-\def\@{@}%
+\let\w=\indexdummyfont
}
% To define \realbackslash, we must make \ not be an escape.
@@ -3454,8 +3560,8 @@ width0pt\relax} \fi
\gdef\thischaptername{#1}%
\xdef\thischapter{\putwordAppendix{} \appendixletter: \noexpand\thischaptername}%
\toks0 = {#1}%
-\edef\temp{\noexpand\writetocentry{\realbackslash chapentry{\the\toks0}%
- {\putwordAppendix{} \appendixletter}}}%
+\edef\temp{\noexpand\writetocentry{\realbackslash appendixentry{\the\toks0}%
+ {\appendixletter}}}%
\temp
\appendixnoderef
\global\let\section = \appendixsec
@@ -3532,7 +3638,8 @@ width0pt\relax} \fi
\def\unnumberedseczzz #1{%
\plainsecheading {#1}\gdef\thissection{#1}%
\toks0 = {#1}%
-\edef\temp{\noexpand\writetocentry{\realbackslash unnumbsecentry{\the\toks0}}}%
+\edef\temp{\noexpand\writetocentry{\realbackslash unnumbsecentry%
+ {\the\toks0}{\the\chapno}}}%
\temp
\unnumbnoderef
\nobreak
@@ -3571,7 +3678,7 @@ width0pt\relax} \fi
\plainsubsecheading {#1}\gdef\thissection{#1}%
\toks0 = {#1}%
\edef\temp{\noexpand\writetocentry{\realbackslash unnumbsubsecentry%
- {\the\toks0}}}%
+ {\the\toks0}{\the\chapno}{\the\secno}}}%
\temp
\unnumbnoderef
\nobreak
@@ -3612,7 +3719,7 @@ width0pt\relax} \fi
\plainsubsubsecheading {#1}\gdef\thissection{#1}%
\toks0 = {#1}%
\edef\temp{\noexpand\writetocentry{\realbackslash unnumbsubsubsecentry%
- {\the\toks0}}}%
+ {\the\toks0}{\the\chapno}{\the\secno}{\the\subsecno}}}%
\temp
\unnumbnoderef
\nobreak
@@ -3824,7 +3931,7 @@ width0pt\relax} \fi
% argument, which will end up as the last argument to the \...entry macro.
%
% We open the .toc file here instead of at @setfilename or any other
-% given time so that @contents can be put in the document anywhere.
+% fixed time so that @contents can be put in the document anywhere.
%
\newif\iftocfileopened
\def\writetocentry#1{%
@@ -3833,6 +3940,14 @@ width0pt\relax} \fi
\global\tocfileopenedtrue
\fi
\iflinks \write\tocfile{#1{\folio}}\fi
+ %
+ % Tell \shipout to create a page destination if we're doing pdf, which
+ % will be the target of the links in the table of contents. We can't
+ % just do it on every page because the title pages are numbered 1 and
+ % 2 (the page numbers aren't printed), and so are the first two pages
+ % of the document. Thus, we'd have two destinations named `1', and
+ % two named `2'.
+ \ifpdf \pdfmakepagedesttrue \fi
}
\newskip\contentsrightmargin \contentsrightmargin=1in
@@ -3888,6 +4003,7 @@ width0pt\relax} \fi
\startcontents{\putwordShortTOC}%
%
\let\chapentry = \shortchapentry
+ \let\appendixentry = \shortappendixentry
\let\unnumbchapentry = \shortunnumberedentry
% We want a true roman here for the page numbers.
\secfonts
@@ -3896,11 +4012,11 @@ width0pt\relax} \fi
\hyphenpenalty = 10000
\advance\baselineskip by 1pt % Open it up a little.
\def\secentry ##1##2##3##4{}
- \def\unnumbsecentry ##1##2{}
+ \def\unnumbsecentry ##1##2##3{}
\def\subsecentry ##1##2##3##4##5{}
- \def\unnumbsubsecentry ##1##2{}
+ \def\unnumbsubsecentry ##1##2##3##4{}
\def\subsubsecentry ##1##2##3##4##5##6{}
- \def\unnumbsubsubsecentry ##1##2{}
+ \def\unnumbsubsubsecentry ##1##2##3##4##5{}
\openin 1 \jobname.toc
\ifeof 1 \else
\closein 1
@@ -3923,16 +4039,23 @@ width0pt\relax} \fi
% The last argument is the page number.
% The arguments in between are the chapter number, section number, ...
-% Chapter-level things, for both the long and short contents.
+% Chapters, in the main contents.
\def\chapentry#1#2#3{\dochapentry{#2\labelspace#1}{#3}}
-
-% See comments in \dochapentry re vbox and related settings
+%
+% Chapters, in the short toc.
+% See comments in \dochapentry re vbox and related settings.
\def\shortchapentry#1#2#3{%
\tocentry{\shortchaplabel{#2}\labelspace #1}{\doshortpageno\bgroup#3\egroup}%
}
+% Appendices, in the main contents.
+\def\appendixentry#1#2#3{\dochapentry{\putwordAppendix{} #2\labelspace#1}{#3}}
+%
+% Appendices, in the short toc.
+\let\shortappendixentry = \shortchapentry
+
% Typeset the label for a chapter or appendix for the short contents.
-% The arg is, e.g. `Appendix A' for an appendix, or `3' for a chapter.
+% The arg is, e.g., `Appendix A' for an appendix, or `3' for a chapter.
% We could simplify the code here by writing out an \appendixentry
% command in the toc file for appendices, instead of using \chapentry
% for both, but it doesn't seem worth it.
@@ -3940,38 +4063,31 @@ width0pt\relax} \fi
\newdimen\shortappendixwidth
%
\def\shortchaplabel#1{%
- % Compute width of word "Appendix", may change with language.
- \setbox0 = \hbox{\shortcontrm \putwordAppendix}%
- \shortappendixwidth = \wd0
- %
- % We typeset #1 in a box of constant width, regardless of the text of
- % #1, so the chapter titles will come out aligned.
- \setbox0 = \hbox{#1}%
- \dimen0 = \ifdim\wd0 > \shortappendixwidth \shortappendixwidth \else 0pt \fi
- %
- % This space should be plenty, since a single number is .5em, and the
+ % This space should be enough, since a single number is .5em, and the
% widest letter (M) is 1em, at least in the Computer Modern fonts.
+ % But use \hss just in case.
% (This space doesn't include the extra space that gets added after
% the label; that gets put in by \shortchapentry above.)
- \advance\dimen0 by 1.1em
- \hbox to \dimen0{#1\hfil}%
+ \dimen0 = 1em
+ \hbox to \dimen0{#1\hss}%
}
+% Unnumbered chapters.
\def\unnumbchapentry#1#2{\dochapentry{#1}{#2}}
\def\shortunnumberedentry#1#2{\tocentry{#1}{\doshortpageno\bgroup#2\egroup}}
% Sections.
\def\secentry#1#2#3#4{\dosecentry{#2.#3\labelspace#1}{#4}}
-\def\unnumbsecentry#1#2{\dosecentry{#1}{#2}}
+\def\unnumbsecentry#1#2#3{\dosecentry{#1}{#3}}
% Subsections.
\def\subsecentry#1#2#3#4#5{\dosubsecentry{#2.#3.#4\labelspace#1}{#5}}
-\def\unnumbsubsecentry#1#2{\dosubsecentry{#1}{#2}}
+\def\unnumbsubsecentry#1#2#3#4{\dosubsecentry{#1}{#4}}
% And subsubsections.
\def\subsubsecentry#1#2#3#4#5#6{%
\dosubsubsecentry{#2.#3.#4.#5\labelspace#1}{#6}}
-\def\unnumbsubsubsecentry#1#2{\dosubsubsecentry{#1}{#2}}
+\def\unnumbsubsubsecentry#1#2#3#4#5{\dosubsubsecentry{#1}{#5}}
% This parameter controls the indentation of the various levels.
\newdimen\tocindent \tocindent = 3pc
@@ -4012,7 +4128,7 @@ width0pt\relax} \fi
\def\tocentry#1#2{\begingroup
\vskip 0pt plus1pt % allow a little stretch for the sake of nice page breaks
% Do not use \turnoffactive in these arguments. Since the toc is
- % typeset in cmr, so characters such as _ would come out wrong; we
+ % typeset in cmr, characters such as _ would come out wrong; we
% have to do the usual translation tricks.
\entry{#1}{#2}%
\endgroup}
@@ -4032,36 +4148,27 @@ width0pt\relax} \fi
\message{environments,}
% @foo ... @end foo.
+% @point{}, @result{}, @expansion{}, @print{}, @equiv{}.
+%
% Since these characters are used in examples, it should be an even number of
% \tt widths. Each \tt character is 1en, so two makes it 1em.
-% Furthermore, these definitions must come after we define our fonts.
-\newbox\dblarrowbox \newbox\longdblarrowbox
-\newbox\pushcharbox \newbox\bullbox
-\newbox\equivbox \newbox\errorbox
-
-%{\tentt
-%\global\setbox\dblarrowbox = \hbox to 1em{\hfil$\Rightarrow$\hfil}
-%\global\setbox\longdblarrowbox = \hbox to 1em{\hfil$\mapsto$\hfil}
-%\global\setbox\pushcharbox = \hbox to 1em{\hfil$\dashv$\hfil}
-%\global\setbox\equivbox = \hbox to 1em{\hfil$\ptexequiv$\hfil}
-% Adapted from the manmac format (p.420 of TeXbook)
-%\global\setbox\bullbox = \hbox to 1em{\kern.15em\vrule height .75ex width .85ex
-% depth .1ex\hfil}
-%}
-
-% @point{}, @result{}, @expansion{}, @print{}, @equiv{}.
+%
\def\point{$\star$}
\def\result{\leavevmode\raise.15ex\hbox to 1em{\hfil$\Rightarrow$\hfil}}
\def\expansion{\leavevmode\raise.1ex\hbox to 1em{\hfil$\mapsto$\hfil}}
\def\print{\leavevmode\lower.1ex\hbox to 1em{\hfil$\dashv$\hfil}}
\def\equiv{\leavevmode\lower.1ex\hbox to 1em{\hfil$\ptexequiv$\hfil}}
+% The @error{} command.
% Adapted from the TeXbook's \boxit.
+%
+\newbox\errorbox
+%
{\tentt \global\dimen0 = 3em}% Width of the box.
\dimen2 = .55pt % Thickness of rules
% The text. (`r' is open on the right, `e' somewhat less so on the left.)
\setbox0 = \hbox{\kern-.75pt \tensf error\kern-1.5pt}
-
+%
\global\setbox\errorbox=\hbox to \dimen0{\hfil
\hsize = \dimen0 \advance\hsize by -5.8pt % Space to left+right.
\advance\hsize by -2\dimen2 % Rules.
@@ -4072,8 +4179,7 @@ width0pt\relax} \fi
\kern3pt\vrule width\dimen2}% Space to right.
\hrule height\dimen2}
\hfil}
-
-% The @error{} command.
+%
\def\error{\leavevmode\lower.7ex\copy\errorbox}
% @tex ... @end tex escapes into raw Tex temporarily.
@@ -4113,9 +4219,9 @@ width0pt\relax} \fi
\def\@{@}%
\let\Etex=\endgroup}
-% Define @lisp ... @endlisp.
+% Define @lisp ... @end lisp.
% @lisp does a \begingroup so it can rebind things,
-% including the definition of @endlisp (which normally is erroneous).
+% including the definition of @end lisp (which normally is erroneous).
% Amount to narrow the margins by for @lisp.
\newskip\lispnarrowing \lispnarrowing=0.4in
@@ -4146,9 +4252,17 @@ width0pt\relax} \fi
% is reset to zero; thus the \afterenvbreak inserts no space -- but the
% start of the next paragraph will insert \parskip
%
-\def\aboveenvbreak{{\advance\envskipamount by \parskip
-\endgraf \ifdim\lastskip<\envskipamount
-\removelastskip \penalty-50 \vskip\envskipamount \fi}}
+\def\aboveenvbreak{{%
+ \ifnum\lastpenalty < 10000
+ \advance\envskipamount by \parskip
+ \endgraf
+ \ifdim\lastskip<\envskipamount
+ \removelastskip
+ \penalty-50
+ \vskip\envskipamount
+ \fi
+ \fi
+}}
\let\afterenvbreak = \aboveenvbreak
@@ -4280,7 +4394,7 @@ width0pt\relax} \fi
\def\smalllispx{\begingroup
\def\Esmalllisp{\nonfillfinish\endgroup}%
\def\Esmallexample{\nonfillfinish\endgroup}%
- \smallfonts
+ \smallexamplefonts
\lisp
}
@@ -4291,12 +4405,12 @@ width0pt\relax} \fi
\let\Edisplay = \nonfillfinish
\gobble
}
-
+%
% @smalldisplay (when @smallbook): @display plus smaller fonts.
%
\def\smalldisplayx{\begingroup
\def\Esmalldisplay{\nonfillfinish\endgroup}%
- \smallfonts \rm
+ \smallexamplefonts \rm
\display
}
@@ -4308,12 +4422,12 @@ width0pt\relax} \fi
\let\Eformat = \nonfillfinish
\gobble
}
-
+%
% @smallformat (when @smallbook): @format plus smaller fonts.
%
\def\smallformatx{\begingroup
\def\Esmallformat{\nonfillfinish\endgroup}%
- \smallfonts \rm
+ \smallexamplefonts \rm
\format
}
@@ -4505,6 +4619,21 @@ width0pt\relax} \fi
\endgroup\nonfillfinish\endgroup
}
+% @copying ... @end copying.
+% Save the text away for @insertcopying later.
+%
+\newbox\copyingbox
+%
+\def\copying{\begingroup
+ \parindent = 0pt % looks wrong on title page
+ \def\Ecopying{\egroup\endgroup}%
+ \global\setbox\copyingbox = \vbox\bgroup
+}
+
+% @insertcopying.
+%
+\def\insertcopying{\unvcopy\copyingbox}
+
\message{defuns,}
% @defun etc.
@@ -4833,7 +4962,7 @@ width0pt\relax} \fi
% #1 is the data type, #2 the name, #3 the args.
\def\deftypefunheaderx #1#2 #3\relax{%
\doind {fn}{\code{#2}}% Make entry in function index
-\begingroup\defname {\defheaderxcond#1\relax$$$#2}{\putwordDeftypefun}%
+\begingroup\defname {\defheaderxcond#1\relax$.$#2}{\putwordDeftypefun}%
\deftypefunargs {#3}\endgroup %
\catcode 61=\other % Turn off change made in \defparsebody
}
@@ -4842,9 +4971,9 @@ width0pt\relax} \fi
\def\deftypefn{\defmethparsebody\Edeftypefn\deftypefnx\deftypefnheader}
-% \defheaderxcond#1\relax$$$
+% \defheaderxcond#1\relax$.$
% puts #1 in @code, followed by a space, but does nothing if #1 is null.
-\def\defheaderxcond#1#2$$${\ifx#1\relax\else\code{#1#2} \fi}
+\def\defheaderxcond#1#2$.${\ifx#1\relax\else\code{#1#2} \fi}
% #1 is the classification. #2 is the data type. #3 is the name and args.
\def\deftypefnheader #1#2#3{\deftypefnheaderx{#1}{#2}#3 \relax}
@@ -4854,7 +4983,7 @@ width0pt\relax} \fi
\begingroup
\normalparens % notably, turn off `&' magic, which prevents
% at least some C++ text from working
-\defname {\defheaderxcond#2\relax$$$#3}{#1}%
+\defname {\defheaderxcond#2\relax$.$#3}{#1}%
\deftypefunargs {#4}\endgroup %
\catcode 61=\other % Turn off change made in \defparsebody
}
@@ -4900,7 +5029,7 @@ width0pt\relax} \fi
\def\deftypeopheader#1#2#3#4{%
\dosubind{fn}{\code{#3}}{\putwordon\ \code{#1}}% entry in function index
\begingroup
- \defname{\defheaderxcond#2\relax$$$#3}
+ \defname{\defheaderxcond#2\relax$.$#3}
{\deftypeopcategory\ \putwordon\ \code{#1}}%
\deftypefunargs{#4}%
\endgroup
@@ -4915,7 +5044,7 @@ width0pt\relax} \fi
\def\deftypemethodheader#1#2#3#4{%
\dosubind{fn}{\code{#3}}{\putwordon\ \code{#1}}% entry in function index
\begingroup
- \defname{\defheaderxcond#2\relax$$$#3}{\putwordMethodon\ \code{#1}}%
+ \defname{\defheaderxcond#2\relax$.$#3}{\putwordMethodon\ \code{#1}}%
\deftypefunargs{#4}%
\endgroup
}
@@ -4929,7 +5058,7 @@ width0pt\relax} \fi
\def\deftypeivarheader#1#2#3{%
\dosubind{vr}{\code{#3}}{\putwordof\ \code{#1}}% entry in variable index
\begingroup
- \defname{\defheaderxcond#2\relax$$$#3}
+ \defname{\defheaderxcond#2\relax$.$#3}
{\putwordInstanceVariableof\ \code{#1}}%
\defvarargs{#3}%
\endgroup
@@ -5012,7 +5141,7 @@ width0pt\relax} \fi
% is actually part of the data type, which should not be put into the index.
\def\deftypevarheader #1#2{%
\dovarind#2 \relax% Make entry in variables index
-\begingroup\defname {\defheaderxcond#1\relax$$$#2}{\putwordDeftypevar}%
+\begingroup\defname {\defheaderxcond#1\relax$.$#2}{\putwordDeftypevar}%
\interlinepenalty=10000
\endgraf\nobreak\vskip -\parskip\nobreak
\endgroup}
@@ -5023,7 +5152,7 @@ width0pt\relax} \fi
\def\deftypevr{\defvrparsebody\Edeftypevr\deftypevrx\deftypevrheader}
\def\deftypevrheader #1#2#3{\dovarind#3 \relax%
-\begingroup\defname {\defheaderxcond#2\relax$$$#3}{#1}
+\begingroup\defname {\defheaderxcond#2\relax$.$#3}{#1}
\interlinepenalty=10000
\endgraf\nobreak\vskip -\parskip\nobreak
\endgroup}
@@ -5183,7 +5312,7 @@ width0pt\relax} \fi
\message{Warning: redefining \the\macname}%
\else
\expandafter\ifx\csname \the\macname\endcsname \relax
- \else \errmessage{The name \the\macname\space is reserved}\fi
+ \else \errmessage{Macro name \the\macname\space already defined}\fi
\global\cslet{macsave.\the\macname}{\the\macname}%
\global\expandafter\let\csname ismacro.\the\macname\endcsname=1%
% Add the macroname to \macrolist
@@ -5464,13 +5593,15 @@ width0pt\relax} \fi
\ifpdf
\leavevmode
\getfilename{#4}%
- \ifnum\filenamelength>0
- \startlink attr{/Border [0 0 0]}%
- goto file{\the\filename.pdf} name{#1@}%
- \else
- \startlink attr{/Border [0 0 0]}%
- goto name{#1@}%
- \fi
+ {\normalturnoffactive
+ \ifnum\filenamelength>0
+ \startlink attr{/Border [0 0 0]}%
+ goto file{\the\filename.pdf} name{#1}%
+ \else
+ \startlink attr{/Border [0 0 0]}%
+ goto name{#1}%
+ \fi
+ }%
\linkcolor
\fi
%
@@ -5732,8 +5863,15 @@ width0pt\relax} \fi
%
\smallfonts \rm
%
- % Hang the footnote text off the number.
- \hang
+ % Because we use hanging indentation in footnotes, a @noindent appears
+ % to exdent this text, so make it be a no-op. makeinfo does not use
+ % hanging indentation so @noindent can still be needed within footnote
+ % text after an @example or the like (not that this is good style).
+ \let\noindent = \relax
+ %
+ % Hang the footnote text off the number. Use \everypar in case the
+ % footnote extends for more than one paragraph.
+ \everypar = {\hang}%
\textindent{\thisfootno}%
%
% Don't crash into the line above the footnote text. Since this
@@ -5750,24 +5888,6 @@ width0pt\relax} \fi
}%end \catcode `\@=11
-% Set the baselineskip to #1, and the lineskip and strut size
-% correspondingly. There is no deep meaning behind these magic numbers
-% used as factors; they just match (closely enough) what Knuth defined.
-%
-\def\lineskipfactor{.08333}
-\def\strutheightpercent{.70833}
-\def\strutdepthpercent {.29167}
-%
-\def\setleading#1{%
- \normalbaselineskip = #1\relax
- \normallineskip = \lineskipfactor\normalbaselineskip
- \normalbaselines
- \setbox\strutbox =\hbox{%
- \vrule width0pt height\strutheightpercent\baselineskip
- depth \strutdepthpercent \baselineskip
- }%
-}
-
% @| inserts a changebar to the left of the current line. It should
% surround any changed text. This approach does *not* work if the
% change spans more than two lines of output. To handle that, we would
@@ -5832,41 +5952,44 @@ width0pt\relax} \fi
\global\warnednoepsftrue
\fi
\else
- \imagexxx #1,,,\finish
+ \imagexxx #1,,,,,\finish
\fi
}
%
% Arguments to @image:
% #1 is (mandatory) image filename; we tack on .eps extension.
% #2 is (optional) width, #3 is (optional) height.
-% #4 is just the usual extra ignored arg for parsing this stuff.
-\def\imagexxx#1,#2,#3,#4\finish{%
+% #4 is (ignored optional) html alt text.
+% #5 is (ignored optional) extension.
+% #6 is just the usual extra ignored arg for parsing this stuff.
+\newif\ifimagevmode
+\def\imagexxx#1,#2,#3,#4,#5,#6\finish{\begingroup
+ \catcode`\^^M = 5 % in case we're inside an example
+ \normalturnoffactive % allow _ et al. in names
+ % If the image is by itself, center it.
+ \ifvmode
+ \imagevmodetrue
+ \nobreak\bigskip
+ % Usually we'll have text after the image which will insert
+ % \parskip glue, so insert it here too to equalize the space
+ % above and below.
+ \nobreak\vskip\parskip
+ \nobreak
+ \line\bgroup\hss
+ \fi
+ %
+ % Output the image.
\ifpdf
- \centerline{\dopdfimage{#1}{#2}{#3}}%
+ \dopdfimage{#1}{#2}{#3}%
\else
% \epsfbox itself resets \epsf?size at each figure.
\setbox0 = \hbox{\ignorespaces #2}\ifdim\wd0 > 0pt \epsfxsize=#2\relax \fi
\setbox0 = \hbox{\ignorespaces #3}\ifdim\wd0 > 0pt \epsfysize=#3\relax \fi
- \begingroup
- \catcode`\^^M = 5 % in case we're inside an example
- \normalturnoffactive % allow _ et al. in names
- % If the image is by itself, center it.
- \ifvmode
- \nobreak\bigskip
- % Usually we'll have text after the image which will insert
- % \parskip glue, so insert it here too to equalize the space
- % above and below.
- \nobreak\vskip\parskip
- \nobreak
- \centerline{\epsfbox{#1.eps}}%
- \bigbreak
- \else
- % In the middle of a paragraph, no extra space.
- \epsfbox{#1.eps}%
- \fi
- \endgroup
+ \epsfbox{#1.eps}%
\fi
-}
+ %
+ \ifimagevmode \hss \egroup \bigbreak \fi % space after the image
+\endgroup}
\message{localization,}
@@ -5935,8 +6058,9 @@ should work if nowhere else does.}
}
% Parameters in order: 1) textheight; 2) textwidth; 3) voffset;
-% 4) hoffset; 5) binding offset; 6) topskip. Then whoever calls us can
-% set \parskip and call \setleading for \baselineskip.
+% 4) hoffset; 5) binding offset; 6) topskip. We also call
+% \setleading{\textleading}, so the caller should define \textleading.
+% The caller should also set \parskip.
%
\def\internalpagesizes#1#2#3#4#5#6{%
\voffset = #3\relax
@@ -5957,6 +6081,8 @@ should work if nowhere else does.}
\normaloffset = #4\relax
\bindingoffset = #5\relax
%
+ \setleading{\textleading}
+ %
\parindent = \defaultparindent
\setemergencystretch
}
@@ -5973,7 +6099,7 @@ should work if nowhere else does.}
% @letterpaper (the default).
\def\letterpaper{{\globaldefs = 1
\parskip = 3pt plus 2pt minus 1pt
- \setleading{13.2pt}%
+ \textleading = 13.2pt
%
% If page is nothing but text, make it come out even.
\internalpagesizes{46\baselineskip}{6in}{\voffset}{.25in}{\bindingoffset}{36pt}%
@@ -5982,7 +6108,7 @@ should work if nowhere else does.}
% Use @smallbook to reset parameters for 7x9.5 (or so) format.
\def\smallbook{{\globaldefs = 1
\parskip = 2pt plus 1pt
- \setleading{12pt}%
+ \textleading = 12pt
%
\internalpagesizes{7.5in}{5.in}{\voffset}{.25in}{\bindingoffset}{16pt}%
%
@@ -5997,8 +6123,8 @@ should work if nowhere else does.}
% Use @afourpaper to print on European A4 paper.
\def\afourpaper{{\globaldefs = 1
- \setleading{12pt}%
\parskip = 3pt plus 2pt minus 1pt
+ \textleading = 12pt
%
\internalpagesizes{53\baselineskip}{160mm}{\voffset}{4mm}{\bindingoffset}{44pt}%
%
@@ -6010,8 +6136,8 @@ should work if nowhere else does.}
% From romildo@urano.iceb.ufop.br, 2 July 2000.
% He also recommends making @example and @lisp be small.
\def\afivepaper{{\globaldefs = 1
- \setleading{12.5pt}%
\parskip = 2pt plus 1pt minus 0.1pt
+ \textleading = 12.5pt
%
\internalpagesizes{166mm}{120mm}{\voffset}{-8mm}{\bindingoffset}{8pt}%
%
@@ -6029,11 +6155,13 @@ should work if nowhere else does.}
% A specific text layout, 24x15cm overall, intended for A4 paper. Top margin
% 29mm, hence bottom margin 28mm, nominal side margin 3cm.
\def\afourlatex{{\globaldefs = 1
- \setleading{13.6pt}%
+ \textleading = 13.6pt
%
\afourpaper
\internalpagesizes{237mm}{150mm}{3.6mm}{3.6mm}{3mm}{7mm}%
%
+ % Must explicitly reset to 0 because we call \afourpaper, apparently,
+ % although this does not entirely make sense.
\globaldefs = 0
}}
@@ -6041,8 +6169,6 @@ should work if nowhere else does.}
\def\afourwide{%
\afourpaper
\internalpagesizes{6.5in}{9.5in}{\hoffset}{\normaloffset}{\bindingoffset}{7mm}%
- %
- \globaldefs = 0
}
% @pagesizes TEXTHEIGHT[,TEXTWIDTH]
@@ -6056,7 +6182,7 @@ should work if nowhere else does.}
\globaldefs = 1
%
\parskip = 3pt plus 2pt minus 1pt
- \setleading{13.2pt}%
+ \setleading{\textleading}%
%
\internalpagesizes{#1}{\hsize}{\voffset}{\normaloffset}{\bindingoffset}{44pt}%
}}
@@ -6086,7 +6212,7 @@ should work if nowhere else does.}
\def\normalless{<}
\def\normalgreater{>}
\def\normalplus{+}
-\def\normaldollar{$}
+\def\normaldollar{$}%$ font-lock fix
% This macro is used to make a character print one way in ttfont
% where it can probably just be output, and another way in other fonts,
@@ -6135,7 +6261,7 @@ should work if nowhere else does.}
\catcode`\+=\active
\def+{{\tt \char 43}}
\catcode`\$=\active
-\def${\ifusingit{{\sl\$}}\normaldollar}
+\def${\ifusingit{{\sl\$}}\normaldollar}%$ font-lock fix
%\catcode 27=\active
%\def^^[{$\diamondsuit$}
@@ -6180,7 +6306,7 @@ should work if nowhere else does.}
@let<=@normalless
@let>=@normalgreater
@let+=@normalplus
-@let$=@normaldollar}
+@let$=@normaldollar}%$ font-lock fix
@def@normalturnoffactive{@let"=@normaldoublequote
@let\=@normalbackslash
@@ -6191,7 +6317,7 @@ should work if nowhere else does.}
@let<=@normalless
@let>=@normalgreater
@let+=@normalplus
-@let$=@normaldollar}
+@let$=@normaldollar}%$ font-lock fix
% Make _ and + \other characters, temporarily.
% This is canceled by @fixbackslash.
diff --git a/doc/uf002331.eps b/doc/uf002331.eps
deleted file mode 100644
index 89791cfd..00000000
--- a/doc/uf002331.eps
+++ /dev/null
@@ -1,1155 +0,0 @@
-%!PS-Adobe-2.0 EPSF-1.2
-%%Title: /home/jkahrs/uf002331.ps
-%%Creator: XV Version 3.10a Rev: 12/29/94 (PNG patch 1.2) - by John Bradley
-%%CreationDate: Oct 14 22:02
-%%For:jkahrs jkahrs
-%%Pages: 1
-%%DocumentFonts:
-%%BoundingBox: -1 259 595 529
-%%BeginPreview: 597 269 1 269
-% 000000000000000080000000202018000400000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
-% f0f0f8d8f0c0c80080000078302000000600000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
-% 982080c89040580090000010202000181400000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
-% 982080c898c07000f8c400303030382c3c00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
-% b020f8a888403000c44c0010202008046400000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
-% e02080a888c02000842800303020083c4600000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
-% b02080b898403000c4300010202008444400000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
-% 9060c898f0c83000c83000303030084c6c00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
-% 98f0f898e07c2000f8200078181c083c3c00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
-% 000000000000000000200000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
-% 000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
-% 000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
-% ab6aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa000d55555555555555555555555555555555555555555555555555555555500155555555555555555555555555555555555555540
-% fffffffffffffffffffffffffffffffffffffffffffff000ffffffffffffffffffffffffffffffffffffffffffffffffffffffffff803fffffffffffffffffffffffffffffffffffffffe0
-% fffffffffffffffffffffffffffffffffffffffffffff001ffffffffffffffffffffffffffffffffffffffffffffffffffffffffff003fffffffffffffffffffffffffffffffffffffffe0
-% 555555555555555555555555555555555555555555557000eaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaab803aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa0
-% 000000000000000000000000000000000000000000007001c00000000000000000000000000000000000000000000000000000000300300000000000000000000000000000000000000000
-% 000000000000000000000000000000000000000000007780e00000000000000000000000000000000000000000000000000000000380380000000000000000000000000000000000000000
-% 0000000000000000000000000000000000000000000070fdc00000000000000000000000000000000000000000000000000000000300300000000000000000000000000000000000000000
-% 000000000000000000000000000000000000000000007000e00000000000000000000000000000000000000000000000000000000380380000000000000000000000000000000000000000
-% 0000000000000000000000000000000000000000000070fcc00000000000000000000000000000000000000000000000000000000300300000000000000000000000000000000000000000
-% 0000000000000000000000000000000000000000000070dbe00000000000000000000000000000000000000000000000000000000380380000000000000000000000000000000000000000
-% 00000000000000000000000000000000000000000000708dc00000000000000000000000000000000000000000000000000000000300300000000000000000000000000000000000000000
-% 00000000000000000000000000000000000000000000718be00000000000000000000000000000000000000000000000000000000380380000000000000000000000000000000000000000
-% 00000000000000000000000000000000000000000000707bc00000000000000000000000000000000000000000000000000000000300300000000000000000000000000000000000000000
-% 000000000000000000000000000000000000000000007000e00000000000000000000000000000000000000000000000000000000380380000000000000000000000000000000000000000
-% 000000000000000000000000000000000000000000007181c00000000000000000000000000000000000000000000000000000000300300000000000000000000000000000000000000000
-% 0000000000000000000000000000000000000000000070fce00000000000000000000000000000000000000000000000000000000380380f00bc3c1c09f020f3cffffc3030e0e700f1cf00
-% 000000000000000000000000000000000000000000007001c00000000000000000000000000000000000000000000000000000000300301f51b83e1ec9c020db6cfffe2078f1e780fbe980
-% 000000000000000000000000000000000000000000007070e000000000000000000000000000000000000000000000000000000003803804516013324d00608a38002260419b34c0223980
-% 0000000000000000000000000000000000000000000070d9c000000000000000000000000000000000000000000000000000000003003006196c31a34960608a6b082240810a1460343f00
-% 00000000000000000000000000000000000000000000718ce000000000000000000000000000000000000000000000000000000003803804097c31634de070d3df102180b90a1460143f00
-% 0000000000000000000000000000000000000000000070cdc0000000000000000000000000000000000000000000000000000000030030040b4011426d0060e3900821818e1e3440142880
-% 000000000000000000000000000000000000000000007078e0000000000000000000000000000000000000000000000000000000038038040e403246e800f082501821818e1424c0146880
-% 000000000000000000000000000000000000000000007001c0000000000000000000000000000000000000000000000000000000030030040646164699309082519061011a366583344980
-% 00000000000000000000000000000000000000000000700ce00000000000000000000000000000000000000000000000000000000380380f067c1c6cd9f090c25f182101f1e3c701f7cf00
-% 00000000000000000000000000000000000000000000700dc00000000000000000000000000000000000000000000000000000000300301c0638183889c010826e102100c1c38600e38c00
-% 000000000000000000000000000000000000000000007180e00000000000000000000000000000000000000000000000000000000380380000000000000000000000000000000000000000
-% 0000000000000000000000000000000000000000000070f1c00000000000000000000000000000000000000000000000000000000300300000000000000000000000000000000000000000
-% 00000000000000000000000000000000000000000000701ee0000000000000000000000000000000000000000000000000000000038038073e1f3e821808618f7bf7dc037c7130b8093de0
-% 00000000000000000000000000000000000000000000707bc000000000000000000000000000000000000000000000000000000003003007be1938a2380871dc6fff1e0366f928be0971a0
-% 0000000000000000000000000000000000000000000071c1e00000000000000000000000000000000000000000000000000000000380380ce00920b26008c3104444130322892ca3094080
-% 000000000000000000000000000000000000000000007000c000000000000000000000000000000000000000000000000000000003003008660f3cb25c1c821f4c4f91876d8f2ca1097da0
-% 0000000000000000000000000000000000000000000077fde0000000000000000000000000000000000000000000000000000000038038187e0b78b2fc1d863c58cf3185390a2ca10ef0e0
-% 000000000000000000000000000000000000000000007000c000000000000000000000000000000000000000000000000000000003003018f009a0aa861d041070481107290a2ab30f41e0
-% 000000000000000000000000000000000000000000007779e000000000000000000000000000000000000000000000000000000003803810a00881aa841d1c7040cc1207ed0a2aa6094120
-% 0000000000000000000000000000000000000000000077f8c000000000000000000000000000000000000000000000000000000003003011a00ba7ae9c3534d3c0c8d60ca5126bbc0b47a0
-% 000000000000000000000000000000000000000000007089e00000000000000000000000000000000000000000000000000000000380381f200e3ca6f825e79f40c79c08e7f3e9981b7d80
-% 00000000000000000000000000000000000000000000718cc000000000000000000000000000000000000000000000000000000003003004200810804004c2084006000080c18000003000
-% 0000000000000000000000000000000000000000000070f9e00000000000000000000000000000000000000000000000000000000380380000000000000000000000000000000000000000
-% 000000000000000000000000000000000000000000007000c00000000000000000000000000000000000000000000000000000000300300000000000000000000000000000001000000000
-% 000000000000000000000000000000000000000000007059e00000000000000000000000000000000000000000000000000000000380380f8633defe1e73c1fa4df0466f917ffe08700160
-% 0000000000000000000000000000000000000000000070fcc00000000000000000000000000000000000000000000000000000000300300c647719fe3edb61fe4ff0666fdb75fac8f04160
-% 000000000000000000000000000000000000000000007081e00000000000000000000000000000000000000000000000000000000380380828c41910208920224c40ee64d64862cd804940
-% 0000000000000000000000000000000000000000000070fcc00000000000000000000000000000000000000000000000000000000300301f3887d310378f60269c40ecf59e7c62edb04960
-% 0000000000000000000000000000000000000000000070f9e00000000000000000000000000000000000000000000000000000000380381c11871e103d0dc0239440feb7bef862e9f85960
-% 000000000000000000000000000000000000000000007000c00000000000000000000000000000000000000000000000000000000300301839041c10310b40269c40b6e7924062ed585b40
-% 0000000000000000000000000000000000000000000070e9e0000000000000000000000000000000000000000000000000000000038038182d0c1810210a40261ec0b6f4924662bb187b40
-% 0000000000000000000000000000000000000000000071acc00000000000000000000000000000000000000000000000000000000300300be734f01021132064a2408394936e629b706640
-% 0000000000000000000000000000000000000000000070ede00000000000000000000000000000000000000000000000000000000380380f43e7d81031f32026a2408394d17c62cbe02660
-% 000000000000000000000000000000000000000000007078c00000000000000000000000000000000000000000000000000000000300300400c3001000c020000240021410304289800020
-% 000000000000000000000000000000000000000000007001e00000000000000000000000000000000000000000000000000000000380380000000000000000000000000000000000000000
-% 0000000000000000000000000000000000000000000076f8c00000000000000000000000000000000000000000000000000000000300300000000000000000000000000000000000000000
-% 0000000000000000000000000000000000000000000074a9e000000000000000000000000000000000000000000000000000000003803807fff7c1c7820a4bfc7004fa107c4de3ff000000
-% 000000000000000000000000000000000000000000007080c00000000000000000000000000000000000000000000000000000000300300c7106034cc24e4fc4e864820826497611000000
-% 000000000000000000000000000000000000000000007081e00000000000000000000000000000000000000000000000000000000380381811040608424e5c45806482d8224d1001000000
-% 0000000000000000000000000000000000000000000070fcc0000c346f87cf9fbfffc08071f27efc3f66f80783080406000000000300301f11f5c7c8424cd4c3f026f2d061c91fc7000000
-% 000000000000000000000000000000000000000000007001e00004646887fedc7fffe180f91afdfc3865ec1fb3180c46000000000380380f13c787e842c794c0f875e2d023891f0e000000
-% 000000000000000000000000000000000000000000007480c000066c68c4285006023303811ac1006064040217380e62000000000300300191040030c2d6dcc0087483d062893408000000
-% 467efe7f0000000007f1bf00037e3181fcc63dff000077fde000038c4984699f84061603f932ddb87e441c0217781a620000000003803801111c04708334b4c1884c8b7026896420000000
-% 46f0e678000000000239b3c186e6610018c4f6d800007080c00001884b05cfbe06061c03f9e6f9f8f87c780204d81272000000000300301b113d06d98134a6c1b84cbb782cd944e0000000
-% 46c0424000000000060db0c0ccc361000987c01800007181e00001885e078db004040c000fc6c1806074600604d81ed2000000000380380e11e503cf0334a6c0f04cf22838f983c8000000
-% c4dc464e00000000060db040498161000985fc1800007080c000018858060890440608020b0681004044400604c81e5a000000000300300410c40106000080006004402000600308000000
-% 7dfe7cfe00000000020d3040798343000905fe18000070fde0000188ca040891c40408031906812063c40006040832ce000000000380380000000000000000000000000000000000000000
-% f4806cc0000000000619b1c03302c1000904031800007000c000010fcb0408df04061801f106c1a03e44601f840823c6000000000300300000000000000000000000000000000000000000
-% c480c4c100000000023133803306c3020b0d8618000070e9e00001060804084c04001000610000001800201800080004000000000380380000000000000000000000000000000000000000
-% c487c6c30000000003611700219c6f0399bdce10000071acc00000000000000000000000000000000000000000000000000000000300300000000000000000000000000000000000000000
-% c4fe467e0000000003c19c0061f87f01f9fcfc18000071ade00000000000000000000000000000000000000000000000000000000380380000000000000000000000000000000000000000
-% 4478c27800000000010008002040100020401000000070f8c000019f3fd3e8708801837f3e60c0871f81873f0080df00000000000300300000000000000000000000000000000000000000
-% 000000000000000000000000000000000000000000007001e0000198f6370cd1c801a16d6060c08d18188d30018859c0000000000380380000000000000000000000000000000000000000
-% 00000000000000000030701c2100057180102061c0007010c000038886340881d801b1084040c1981018982001cc58c0000000000300300000000000000000000000000000000000000000
-% d608fcfc0000000000f9f9fc330c1ff3e01867ffe00070f9e000029b8636e9835801b10c7e40c19b9f98907e01cc5060000000000380380000000000000000000000000000000000000000
-% b718f1ce0000000001c9858073181d863038ce08300071acc000028f0637c9025801b188f84081b7de18907c034c5040000000000300300000000000000000000000000000000000000000
-% 371980c60000000007018d007330018c1039cc00300070ede000039b06361b03d801390c40c081b05014b06003ce58c0000000000380380000000000000000000000000000000000000000
-% 3739bccc0000000007f98bf8d3e00198102dcfe0e00070c8c00007d906340b0b5041ad0840c18120d056a0e0834b5980000000000300300000000000000000000000000000000000000000
-% 35ebe0f800000000000df380d320019810266c07800070a9e000045986341b3679c1270847cf9da391f3a3278669db00000000000380380000000001800000000000000000000000000000
-% 34c900d8000000000005c300fb30019830266c02000071f8c0000458863419e47f81a3087e7cf9be1f319e3e0268ce00000000000300300000000001800000000000000000000000000000
-% 34c9028c00000000060d83079b10011060226c3800007009e0000050802008c00c010108306060180c009c1800204000000000000380380000000001000000000000000000000000000000
-% 340d0ecc8000000003b9013d0b180119e0206cf00000700cc00000000000000000000000000000000000000000000000000000000300300000000001000000000000000000000000000000
-% 340cfcc68000000001f181f90a08010f802027c3000070f9e00000000000000000000000000000000000000000000000000000000380380000000001000000000000000000000000000000
-% 200440000000000000000000000000000000000000007000c00000f98b7ffe07ffc44242c4307fe2fc03c6319fbfdf8f7f8000000300300000000001000000000000000000000000000000
-% 00000000000000000000000000000000000000000000700de00003898b6c600c0c466246c4306c66c0074e7198be301d6c00000003803800000000010000000080701c40818811e0387000
-% 00000000000000000000000000000000000000000000700cc000030d0b0c40040c4e634c86600c64800c0e63988620300c00000003003000000000030000000081fcfe619fcc37f1fff800
-% 000000000000000000000000000000000000000000007081e00006070b087e0dc98e637882c00c44fc1fce7299863f7f0c000000038038000000000100000000818580e3380c7211818c00
-% 0000000000000000000000000000000000000000000071e0c000044f0b0cf807cf8a737881800c7df00febb2df063c3f8c000000030030000000000300000001808d80e7110e6273018c00
-% 00000000000000000000000800000000000000000000703de000047b0b08400c0d9e5b4d81800c64800029b7db042000cc00000003803800000000020000000181f9fcbd3f96f3f3f9b800
-% 00000000000000000000000c0000000000000000000070e0c00004321b08430c089b4a4587000c4486086936510420a18c00000003003000000000020000000181f3809db013b21301f000
-% 0000000000000000000000040000000000000000000070e1e00007f33b0c470408934e469d000c448e0ce814518633b38c00000003803800000000020000000181998099b013b20b019000
-% 00000000000000000000000400000000000000000000703cc00003d3fb087c0408d146c2f9000c44f807c81858841f1f0c00000003003000000000020000000181890689b0f1321b0f1800
-% 0000000000000000000000040000000000000000000070f9e00000108208300408410200610000046003001050840c0c00000000038038000000000200000001818d9e81b3d012f33d8800
-% 000000000000000000000006000000000000000000007180c00000000000000000000000000000000000000000000000000000000300300000000006000000018184f0809e101381e10c00
-% 0000000000000000000000020000000000000000000070e1e000004000300850100009c000030c060000000000000000000000000380380000000004000000000000000000000000000000
-% 00000000000000000000000200000000000000000000703cc00001f213f80cfc7c4689f018bf7f7e0000000000000000000000000300300000000004000000000000000000000000000000
-% 000000000000000000000002000000000000000000007079e000019b13001cc4e6448d3c18b02160000000000000000000000000038038000000000400000000000000000000078c040f00
-% 0000000000000000000000010000000000000000000071c0c000030b1b001c44c2c68d8c18a023400000000000000000000000000300300000000004000000000278634fc7f03fcc06ff80
-% 000000000000000000000000000000000000000000007039e000060d93f014dd8285cd04193f26fc00000000000000000000000003803800000000040000000186fc636e6700780c06ff00
-% 0000000000000000000000010000000000000000000070f8c000060b9b0016790285e50c1f703ce0000000000000000000000000030030000000000c00000001998642246c00230c060e00
-% 000000000000000000000001000000000000000000007181e000041aca001ed90685ad98192026c0000000000000000000000000038038000000000c000000009902c224efe07f8c0c1800
-% 000000000000000000000001000000000000000000007180c00004327208368d0c853d381121a2c30000000000000000000000000300300000000008000000007306820f9f007e080c3820
-% 0000000000000000000000018000000000000000000070f9e00006723338228d9c9d9df01123a2474000000000000000000000000380380000000008000000006206820e8c0060180e3020
-% 00000000000000000000000080000000000000000000703cc00007c231f02285f0fd08c0113e237c400000000000000000000000030030000000000800000000620c820c481060c8346060
-% 0000000000000000000000008000000000000000000071c1e00000000000000000000000000000000000000000000000000000000380380000000008000000004318de0c6cf077cdecffe0
-% 000000000000000000000000800000000000000000007038c000000000000000000000000000000000000000000000000000000003003000000000080000000041f0fe0c67c03f9fccff60
-% 000000000000000000000000c0000000000000000000703de000000000000000000000000000000000000000000000000000000003803800000000080000000000c0200022001c0f04e000
-% 0000000000000000000000004000000000000000000071e0c00000000000000000000000000000000000000000000000000000000300300000000008000000000000000000000000000000
-% 000000000000000000000000400000000000000000007781e00000000000000000000000000000000000000000000000000000000380380000000000000000000000000000000000000000
-% 00000000000000000000000040000000000000000000707cc00000000000000000000000000000000000000000000000000000000300300000000008000000000000000000000000000000
-% 000000000000000000000000600000000000000000007009e0000000000000000000000000000000000000000000000000000000038038000000001000000000000000000c000000000000
-% 000000000000000000000000200000000000000000007780c00000000000000000000000000000000000000000000000000000000300300000000010000000000000000004000000000000
-% 0000000000000000000000002000000000000000000070fde00000000000000000000000000000000000000000000000000000000380380000000010000000000000000006000000000000
-% 000000000000000000000000000000000000000000007000c00000000000000000000000000000000000000000000000000000000300300000000010000000000000000002000000000000
-% 000000000000000000000000000000000000000000007189e00000000000000000000000000000000000000000000000000000000380380000000010000000000000000001000000000000
-% 00000000000000000000000000000000000000000000708cc00000000000000000000000000000000000000000000000000000000300300000000010000000000000000001000000000000
-% 000000000000000000000000007c00000000000000007021e000000000000000000000000000000000000003e0000000000000000380380000000030000000000000000001800003e00000
-% 00000000000000000000000001ffc00000000000000070f8c00000000300000000000000000000000000000ffe00000000000000030030000000003000000000000000000080000ffe0000
-% 00000000000000000000000003007000000000000000718de00000000300000000000000000000000000001803800000000000000380380000000020000000000000000000c00018038000
-% 0000000000000000000000000e001800000000000000708cc00000000200000000000000000000000000007000c0000000000000030030000000002000000000000000000040007000c000
-% 0000000000000000000000001800060000000000000070ffe0000000020000000000000000000000000000c000300000000000000380380000000020000000000000000000200080003000
-% 000000000000000000000000300003000000000000007001c00000000200000000000000000000000000018000180000000000000300300000000020000000000000000000300180001800
-% 000000000000000000000000300001800000000000007084e000000002000000000000000000000000000100000c0000000000000380380000000020000000000000000000100100000800
-% 000000000000000000000000300000c000000000000073fdc00000000200000000000000000000000000010000040000000000000300300000000060000000000000000000100300000c00
-% 0000000000000000000000002020004000000000000073f8e00000000600000000000000000000000000030100060000000000000380380000000060000000000000000000080301000600
-% 00000000000000000000000063f800400000000000007085c00000000400000000000000000000000000031dc002000000000000030030000000004000000000000000000008021d800200
-% 00000000000000000000000066c8002000000000000073fce00000000400000000000000000000000000037640030000000000000380380000000040000000000000000000040276400300
-% 0000000000000000000000006866002000000000000073f9c0000000040000000000000000000000000002c3200100000000000003003000000000400000000000000000000402c3600100
-% 000000000000000000000000382200300000000000007000e00000000400000000000000000000000000018130018000000000000380380000000040000000000000000000020381200180
-% 000000000000000000000000303200180000000000007079c0000000040000000000000000000000000001819000c000000000000300300000000040000000000000000000020301b00080
-% 0000000000000000000000002031000c00000000000071a8e00000000c000000000000000000000000000100900060000000000003803800000000c0000000000000000000010300900040
-% 000000000000000000000000201100040000000000007081c000000008000000000000000000000000000100980020000000000003003000000000c0000000000000000000018200980060
-% 0000000000000000000000000012600400000000000077f8e00000000800000000000000000000000000000093002000000000000380380000000080000000000000000000008000930040
-% 0000000000000000000000000012f80400000000000077fdc00000000800000000000000000000000000000097c0200000000000030030000000008000000000000000000000c00097c060
-% 0000000000000000000000000011dc040000000000007000e0000000080000000000000000000000000000009e6020000000000003803800000000800000000000000000000000009d6060
-% 000000000000000000000000001b86040000000000007001c000000008000000000000000000000000000000dc3060000000000003003000000000800000000000000000000000003c3040
-% 000000000000000000000000080d8b040000000000007000e0000000080000000000000000000000000000406c5020000000000003803800000000800000000000000000000000c0cc5060
-% 0000000000000000000000000c38090c0000000000007001c000000008000000000000000000000000000061c0686000000000000300300000000180000000000000000000000061804040
-% 0000000000000000000000000c681b0c0000000000007000e0000000100000000000000000000000000000634098600000000000038038000000018000000000000000000000006300d840
-% 0000000000000000000000000cd003880000000000007001c0000000100000000000000000000000000000e680184000000000000300300000000100000000000000000000000066801840
-% 0000000000000000000000003fb01c8c0000000000007000e0000000100000000000000000000000000001fd80e440000000000003803800000001000000000000000000000003fd80ec40
-% 0000000000000000000000003fc000c80000000000007001c0000000100000000000000000000000000001be000440000000000003003000000001000000000000000000000003b6000440
-% 000000000000000000000000280000c40000000000007000e0000000100000000000000000000000000001c0000420000000000003803800000001000000000000000000000001c0000440
-% 000000000000000000000000680000440000000000007001c00000001000000000000000000000000000034000062000000000000300300000000100000000000000000000000240000660
-% 000000000000000000000000abc000460000000000007000e000000010000000000000000000000000000cde00023000000000000380380000000100000000000000000000000dde000220
-% 000000000000000000000001be7000620000000000007001c000000010000000000000000000000000001db380031000000000000300300000000100000000000000000000001df3800300
-% 000000000000000000000002041800210000000000007000e000000030000000000000000000000000001020c0030800000000000380380000000000000000000000000000003021c00300
-% 0000000000000000000000020c0e00308000000000007001c00000002000000000000000000000000000106060018400000000000300300000000100000000000000000000001063600180
-% 000000000000000000000001fa860030c000000000007000e000000020000000000000000000000000001f9020018600000000000380380000000200000000000000000000001f9f200180
-% 00000000000000000000000003c20038c000000000007001c0000000200000000000000000000000000000182001c60000000000030030000000020000000000000000000000001fa00180
-% 00000000000000000000000001c20008c000000000007000e0000000200000000000000000000000000000081000660000000000038038000000020000000000000000000000000f300040
-% 00000000000000000000000001c3000c6000000000007001c00000002000000000000000000000000000000c1800630000000000030030000000020000000000000000000000000e180060
-% 0000000000000000000000000103801e2000000000007000e0000000600000000000000000000000000000081c00f3000000000003803800000002000000000000000000000000103c00e0
-% 000000000000000000000000030280162000000000007001c000000060000000000000000000000000000018240091000000000003003000000002000000000000000000000000182400a0
-% 000000000000000000000000030080321000000000007000e000000040000000000000000000000000000018040191800000000003803800000006000000000000000000000000180401a0
-% 000000000000000000000000030080221000000000007001c00000004000000000000000000000000000001804031080000000000300300000000600000000000000000000000018040300
-% 0000000000000000000000000300c02318000000000077f8e000000040000000000000000000000000000018060318c0000000000380380000000400000000000000000000000010040320
-% 000000000000000000000000010040478800000000007089c00000004000000000000000000000000000000802022c40000000000300300000000400000000000000000000000018020220
-% 000000000000000000000000018041cce40000000000718ce000000040000000000000000000000000000008020c6760000000000380380000000400000000000000000000000008020c60
-% 0000000000000000000000000180cf8db6000000000070f9c0000000c000000000000000000000000000000c067c6db000000000030030000000040000000000000000000000000804fc60
-% 00000000000000000000000000c0fa1bd300000000007060e0000000c000000000000000000000000000000407d0dc9800000000038038000000040000000000000000000000000c07b0c0
-% 00000000000000000000000000c0803b118000000000700dc0000000800000000000000000000000000000040401db88000000000300300000000c0000000000000000000000000c040180
-% 0000000000000000000000000041806270800000000071f8e0000000800000000000000000000000000000020c033584000000000380380000000c000000000000000000000000020c0320
-% 00000000000000000000000000e301d750c00000000071adc000000080000000000000000000000000000007180e3284000000000300300000000800000000000000000000000007180e60
-% 000000000000000000000000008307bd50400000000070bce0000000800000000000000000000000000000041839ea8600000000038038000000080000000000000000000000000c1039e0
-% 00000000000000000000000000821c765840000000007011c00000018000000000000000000000000000000410ebb2c600000000030030000000080000000000000000000000000c10eba0
-% 0000000000000000000000000182fadfa840000000007000e00000018000000000000000000000000000000c17d6fac6000000000380380000000800000000000000000f0000000837d6e0
-% 0000000000000000000000000107c5b1aec00000000076f9c0000001000000000000000000000000000000083e2f4d640000000003003000000008000000000000000008000000087d2d80
-% 000000000000000000000000010f29ed9780000000007000e0000001000000000000000000000000000000087aceacbc000000000380380000001800000000000000001000000018795b60
-% 000000000000000000000000037fabcad4c00000000077f9c00000010000000000000000000000000000001b7c9eaeb4000000000300300000001800000000000000002180000003fe9e40
-% 000000000000000000000000023fd6ead6800000000077fce000000100000000000000000000000000000013fd7556b0000000000380380000001000000000000000000380000011fd7540
-% 000000000000000000000000020faccad600000000007001c0000001000000000000000000000000000000117d6d56a00000000003003000000010000000000000000004000000127e6d40
-% 000000000000000000000000024fadb564000000000077f8e0000003000000000000000000000000000000127eeaab300000000003803800000010000000000000000000018000127cdaa0
-% 000000000000000000000000035fdb957600000000007001c00000020000000000000000000000000000001efcdaabb00000000003003000000010000000000000000001ffc0001e7edaa0
-% 000000000000000000000000018f992aaa000000000077f8e00000020000000000000000000000000000000c7ecd55500000000003803800000000000000000000000003d870000cfcdaa0
-% 000000000000000000000000000fdb6ab3000000000077fdc0000002000000000000000000000000000000007d9aab58000000000300300000000000000000000000000e08d80001fd9aa0
-% 000000000000000000000000000fb74abb00000000007000e0000002000000000000000000000000000000007db9555800000000038038000000000000000000000000120ccc0007fdb540
-% 000000000000000000000000001fb35ab200000000007001c000000200000000000000000000000000000000fddd55d000000000030030000000000000000000000000e64cb60006fddd40
-% 000000000000000000000000000fbbaab700000000007000e0000002000000000000000000000000000000007d995598000000000380380000000000000000000000018c44a58018fd1940
-% 000000000000000000000000000fb3555b000000000070e1c0000002000000000000000000000000000000007d3b55d80000000003003000000000000000000000000236cd9ac036ff5b40
-% 000000000000000000000000001fb7555b000000000077f8e000000000000000000000000000000000000000ff5a5598000000000380380000000000000000000000066385a57064ff5a40
-% 000000000000000000000000001fab55590000000000760dc000000200000000000000000000000000000000fd59aaa800000000030030000000000000000000000003c709d530d5ff55a0
-% 000000000000000000000000001feb555b000000000077b8e000000400000000000000000000000000000000ff5a55a8000000000380380000000000000000000000014c9bd559aaff5940
-% 000000000000000000000000001feb555d000000000070e1c000000400000000000000000000000000000000ff5daad80000000003003000000000000000000000000038912aa72aff5aa0
-% 000000000000000000000000001feb555900000000007040e000000000000000000000000000000000000000ff5aaaa80000000003803800000000000000000000000008e355576afe5aa0
-% 000000000000000000000000001fcb555b000000000073f9c000000000000000000000000000000000000000fe5aaad80000000003003000000000000000000000000009c35556aaff5540
-% 000000000000000000000000001feb555d0000000000760ce000000000000000000000000000000000000000ffd95588000000000380380000000000000000000000000f0195572afe5540
-% 000000000000000000000000001fab5553000000000077bdc000000000000000000000000000000000000000fc5d55b8000000000300300000000000000000000000000000e55754fcdaa0
-% 000000000000000000000000001fab2ab5000000000070f0e000000000000000000000000000000000000000fd5955c80000000003803800000000000000000000000000007aaeabfd5d40
-% 000000000000000000000000001fab555500000000007001c000000000000000000000000000000000000000fd5d55980000000003003000000000000000000000000000001d5f56fd5940
-% 000000000000000000000000001fd7555b000000000073f0e000000000000000000000000000000000000000fd5955a80000000003803800000000000000000000000000000658acfd5d40
-% 000000000000000000000000001fabaab30000000000761dc000000000000000000000000000000000000000fd5d55d8000000000300300000000000000000000000000000038b4cfd5940
-% 000000000000000000000000001f95555b0000000000760ce0003fff40000000000000000000000000000000fead559800000000038038000fffd000000000000000000c0001f158fd5b40
-% 000000000000000000000000001fabaab2000000000073f1c001f4005c000000000000000000000000000000fd5955b000000000030030007d0017000000000000000007c0003e70fd5d40
-% 000000000000000000000000001fd3555b00000000007000e003008006000000000000000000000000000000fe5b5598000000000380380042200180000000000000000000000fe0fd5140
-% 000000000000000000000000001fab2abb000000000073cdc0037a0001800000000000000000000000000000fd5a55d80000000003003000d4800060000000000000000800000180fd5d40
-% 000000000000000000000000001fab553300000000007668e006048000800000000000000000000000000000fd5955500000000003803801911000300000000000000007e0000000fd5aa0
-% 000000000000000003800000001fcbaaba0000000000743dc007f00000c00000000000000000000000000000fe5aab580000000003003001fc4000100000000000000001c0000000fe5540
-% 000000000000000002000000001fdb2ab30000000000731ce00d7c8000400000000000000000000000000000fedd55d800000000038038035f000010000000000000000000000000fed540
-% 000000000000000004c00000001feb555b00000000007001c00a840000600000000000000000000000000000ff5955180000000003003003a1000030000000000000000000000000fd5d40
-% 000000000000000004800000001fcb555a00000000007000e00aa60000a00000000000000000000000000000fe5b55d0000000000380380229900038000000000000000000000000fe52a0
-% 000000000000000000800000003fdb555b00000000007001c00d260000a00000000000000000000000000000feba55580000000003003002c9800028000000000000000000000000fedaa0
-% 000000000000000001000000003fcb2ab300000000007000e019420000a00000000000000000000000000000fea955d8000000000380380650800028000000000000000000000000fd5940
-% 000000000000000000008000017fd5f55b000000000071fcc00d520001a00000000000000000000000000000ff5faa980000000003003002aa80006c000000000000000000000000feafa0
-% 0000000000000000007fedf07fdfebc55b00000000007707e009230eff300000000000000000000000000000fe5e55d80000000003803806a0c3bf88000000000000000000000000fe5e40
-% 000000000000000000c13b7fe99fcbf55500000000007001c01d49fb80200000000000000000000000000000ff5faaa80000000003003003547ed008000000000000000000000000ff5fa0
-% 0000000000000000008219894adfd5955980000000007098e009200000200000000000000000000000000000fe4d55a8000000000380380248000004000000000000000000000000fead40
-% 000000000000000000ff4b6ab55fd5d5558000000000718dc01a4400003000000000000000000000000000007f5caaa80000000003003006910000080000000000000000000000007e5ca0
-% 000000000000000000225b55555febd55d0000000000708ce00a9000002000000000000000000000000000007eaf55980000000003803802a400000c0000000000000000000000007eaf40
-% 00000000000000000026d155555fcb6ab5800000000070f9c00d400300200000000000000000000000000000ff5a556c00000000030030035000c008000000000000000000000000ff5240
-% 0000000000000000003f932aaa9feb155580000000007000e0090805002000000000000000000000000000007f59554800000000038038064200c0080000000000000000000000007ebac0
-% 0000000000000000002013aaaaafeb6ab280000000007603c01aa003002000000000000000000000000000007f36ab5c0000000003003006a801c0080000000000000000000000007e5280
-% 00000000000000000036132aaaafeaaab5800000000073fce01d0802002000000000000000000000000000007f5955a80000000003803805420080080000000000000000000000007f5aa0
-% 0000000000000000001c11550aaff6aaba80000000007001c018a000002000000000000000000000000000007fb355ac0000000003003006a80000080000000000000000000000007eb540
-% 00000000000000000007dfa9f94fc6aab280000000007000e0150000002000000000000000000000000000007e3655280000000003803806400000080000000000000000000000007eb540
-% 00000000000000000000012fdffff6553580000000007001c01a5200006000000000000000000000000000007eb4d5ac0000000003003006948000000000000000000000000000007ebaa0
-% 0000000000000000000001fc000fcf556a80000000007000e01a8c00002000000000000000000000000000007f732b280000000003803806a1000008000000000000000000000000fe72a0
-% 0000000000000000000000c0001fed55658000000000708dc01a080000200000000000000000000000000000fe7aab6c0000000003003006430000000000000000000000000000007f76a0
-% 000000000000000000000000000fce556a800000000073fce0194800002000000000000000000000000000007ef555a80000000003803806920000080000000000000000000000007e72a0
-% 0000000000000000000c0000000fddaaaa80000000007081c01a0800002000000000000000000000000000007e6aab2c000000000300300522000000000000000000000000000000fd6aa0
-% 00000000000000000003c000001fcd5575800000000070fce014a80000200000000000000000000000000000ff6555a8000000000380380642000008000000000000000000000000ff6aa0
-% 000000000000000000000000001fdcaaaa80000000007181c019080000200000000000000000000000000000fe6aab2c000000000300300692000000000000000000000000000000fe6aa0
-% 0000000000000000000c6000001fed556580000000007080e01a480000600000000000000000000000000000feeaab68000000000380380542000008000000000000000000000000feeaa0
-% 00000000000000000007c000001fcd556a800000000077f9c014080000200000000000000000000000000000fe6aaaac000000000300300613000000000000000000000000000000fe6aa0
-% 000000000000000000000000001fed556a800000000077fce019480000400000000000000000000000000000fecaaaa8000000000380380542000008000000000000000000000000fed540
-% 000000000000000000000000001f99555580000000007001c00a080000200000000000000000000000000000feeaabac000000000300300281000008000000000000000000000000fccaa0
-% 000000000000000000000000003fdb556a800000000070fee014880000200000000000000000000000000001fdcaab28000000000380380652000008000000000000000000000000fdeaa0
-% 000000000000000000000000001f1a556a8000000000708bc01a080000200000000000000000000000000000f8daab6c000000000300300682000008000000000000000000000001fad540
-% 000000000000000000000000001f79aad580000000007189e018480000200000000000000000000000000000fdcaaaa8000000000380380601000008000000000000000000000000facaa0
-% 000000000000000000000000000f9d554ac00000000070dfc0150c00002000000000000000000000000000007ad5572c00000000030030055100000800000000000000000000000079daa0
-% 000000000000000000000000000f5aaad4c0000000007061e0180c00003000000000000000000000000000007aeaaa5400000000038038060000000c0000000000000000000000007ad2a0
-% 00000000000000000000000000035d556a800000000074b8c01a840000200000000000000000000000000000159556d400000000030030054100000800000000000000000000000052ad40
-% 00000000000000000000000000015aaaaac00000000076f9e0180c000020000000000000000000000000000012d556ac0000000003803806110000080000000000000000000000001ad540
-% 000000000000000000000000000312aad4c0000000007000c019080000300000000000000000000000000000199554a4000000000300300680000008000000000000000000000000199540
-% 0000000000000000000000000001dd55eb80000000007181e0120c00002000000000000000000000000000000eaaaf1c0000000003803804410000080000000000000000000000000daaa0
-% 0000000000000000000000000000f2aabf000000000070fcc01884000010000000000000000000000000000007d557f800000000030030070100000c000000000000000000000000079540
-% 0000000000000000000000000000d9559400000000007001e01404000020000000000000000000000000000006caaca000000000038038042100000800000000000000000000000006caa0
-% 0000000000000000000000000000ef11a600000000007000c011040001f0000000000000000000000000000006788ab000000000030030048100007c000000000000000000000000067880
-% 0000000000000000000000000000edff2c000000000071e1e01c02001f100000000000000000000000000000076ffd600000000003803807008007c400000000000000000000000006dfe0
-% 0000000000000000000000000001eac6ec0000000000703cc037d37ff08800000000000000000000000000000f563560000000000300300df4dffc220000000000000000000000000f4e60
-% 0000000000000000000000000000ed67280000000000703fe0607fe0038800000000000000000000000000000f57954000000000038038081fe801e20000000000000000000000000ed720
-% 0000000000000000000000000001eabc58000000000071c1c0400680184400000000000000000000000000000769eac0000000000300301001b006110000000000000000000000000769e0
-% 0000000000000000000000000000eaa5d000000000007020e0400cd007b400000000000000000000000000000f4a2ac00000000003803810013400ed0000000000000000000000000f5500
-% 0000000000000000000000000001bd5518000000000070f9c0800cd00c6400000000000000000000000000000d6aaa800000000003003030013403198000000000000000000000000f6560
-% 0000000000000000000000000001a555700000000000718ce08007b0018400000000000000000000000000000db55580000000000380382001e400f100000000000000000000000007b540
-% 0000124924800000000000000001b6aa900000000000708ce880000002020000012492480000000000000000073555800000000003003920000400008000002492490000000000000f3540
-% ffffffffffc00000000000000001b3aab0000000000070fffffffffffffffffffffffffe00000000000000000dda95800000000003803fffffffffffffffffffffff8000000000000f5d40
-% efdfeeeeeec00000000000000001bdd6b000000000007001f7df6efff6fef7dfbedddddc00000000000000000d6d75000000000003003ddfbb75ffdf7fdfbfdddddd800000000000096e60
-% bd7abbbbbbc00000000000000001bcfca000000000007000ed75fbd55fabdd7aebf7777600000000000000000967cb000000000003803b7aefdf5575d57af57777778000000000000b67e0
-% ebd7eeeeeec00000000000000001b61360000000000070f9ffdfaebffaff77d7bf5ddddc00000000000000000db8b3000000000003003fd7bd75ffdf7fd7afdddddd8000000000000db080
-% bebebbbbbdc00000000000000001b355400000000000708cf5757dd557aaaebeeaf7776e00000000000000000d9d56000000000003803d7eebdf556ad57d7d77777b800000000000099aa0
-% ffffffffffc000000000000000019dd5600000000000718dfffffffffffffffffffffffc000000000000000009aeab000000000003003fffffffffffffffffffffff8000000000000dbea0
-% 0000000000000000000000000001b55560000000000070f8c000400094aac0000000000000000000000000000dd2ab00000000000380300010000aaaa000000000000000000000000dcaa0
-% 000000000000000000000000000155557000000000007061e0002025295580000000000000000000000000000d95538000000000030038000801555560000000000000000000000009aaa0
-% 00000000000000000000000000019aaae000000000007000c0001008aaab000000000000000000000000000009d557000000000003803000040429554000000000000000000000000d9540
-% 0000000000000000000000000001b555f000000000007339e0001002555200000000000000000000000000000daaaf00000000000300380006214aaa8000000000000000000000000daaa0
-% 0000000000000000000000000001baa9200000000000760cc0000848aaac000000000000000000000000000009d5490000000000038030000204155580000000000000000000000009d540
-% 00000000000000000000000000013957600000000000740de00006010aa800000000000000000000000000001daabb0000000000030038000100aaaa0000000000000000000000001beaa0
-% 0000000000000000000000000001b54ea000000000007608c000020a5550000000000000000000000000000019aa6500000000000380300000910154000000000000000000000000198a60
-% 0000000000000000000000000001353920000000000073f9e0000100922000000000000000000000000000000989cb00000000000300300000402a880000000000000000000000000d29c0
-% fffffffffffffffffffffffffffffffffffffffffffff040ffffffffffffffffffffffffffffffffffffffffffffffffffffffffff803fffffffffffffffffffffffffffffffffffffffe0
-% fffffffffffffffffffffffffffffffffffffffffffff001ffffffffffffffffffffffffffffffffffffffffffffffffffffffffff003fffffffffffffffffffffffffffffffffffffffe0
-%%EndImage
-%%EndPreview
-save
-countdictstack
-mark
-newpath
-/showpage {} def
-%%EndProlog
-%%Page 1 1
-%%DocumentFonts:
-
-
-% remember original state
-/origstate save def
-
-% build a temporary dictionary
-20 dict begin
-
-% define string to hold a scanline's worth of data
-/pix 90 string def
-
-% define space for color conversions
-/grays 720 string def % space for gray scale line
-/npixls 0 def
-/rgbindx 0 def
-
-% lower left corner
--53 259 translate
-
-% size of image (on paper, in 1/72inch coords)
-720.00000 274.03200 scale
-
-% dimensions of data
-720 274 1
-
-% mapping matrix
-[720 0 0 -274 0 274]
-
-{currentfile pix readhexstring pop}
-image
-ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
-ffffffffffffffffffffffffffffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
-ffffffffffffffffffffffffffffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
-ffffffffffffffffffffffffffffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
-ffffffffffffffffffffffffffffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
-ffffffffffffffffffffffffffffffffffff
-fffdfffffffffffffffffffffffffbfffffffefeff3fffdfffffffffffffffffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
-ffffffffffffffffffffffffffffffffffff
-f670f070fff8787878393879f9bffbfffffc3e7effffffcfffffffffffffffffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
-ffffffffffffffffffffffffffffffffffff
-f77773f37ff9f33efbf9bb7dfd3ffb7fffff7efeffff3f5fffffffffffffffffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
-ffffffffffffffffffffffffffffffffffff
-f773f7f37ff9fb3efbf9bb39fc7ff839dffe7e7e7e3e9e1fffffffffffffffffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
-ffffffffffffffffffffffffffffffffffff
-f779f0727ff87a7ef83abbbdfe7ff9dd9fff7efeffbfdcdfffffffffffffffffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
-ffffffffffffffffffffffffffffffffffff
-f77cfbf0fff9f8fefbfabbb9fefffbdebffe7e7effbe1dcfffffffffffffffffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
-ffffffffffffffffffffffffffffffffffff
-f67777f2fffbf27efbfa3b3dfe7ff9de7fff7efeffbddddfffffffffffffffffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
-ffffffffffffffffffffffffffffffffffff
-f27273727ff9fb7cf9bb3879be7ff9be7ffe7e7e7fbd9c9fffffffffffffffffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
-ffffffffffffffffffffffffffffffffffff
-f8f8f8777ff9fb38783b38fc1efff83efffc3f3f1fbe1e1fffffffffffffffffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
-ffffffffffffffffffffffffffffffffffff
-fffffffffffffffffffffffffffffffeffffffffffffffffffffffffffffffffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
-ffffffffffffffffffffffffffffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
-ffffffffffffffffffffffffffffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
-ffffffffffffffffffffffffffffffffffff
-aaaaaaaaaaaaaaa4aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaafff95555555555
-555555555555555555555555555555555555555555555557ff5555555555555555555555
-555555555555555555555555555555555555
-00000000000000000000000000000000000000000000000000000000007ff80000000000
-000000000000000000000000000000000000000000000003fe0000000000000000000000
-000000000000000000000000000000000000
-00000000000000000000000000000000000000000000000000000000007ff00000000000
-000000000000000000000000000000000000000000000007fe0000000000000000000000
-000000000000000000000000000000000000
-15555555555555555555555555555555555555555555555555555555547ff8aaaaaaaaaa
-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa3fe2aaaaaaaaaaaaaaaaaaaaa
-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa8
-3ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7ff1ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe7fe7fffffffffffffffffffff
-fffffffffffffffffffffffffffffffffff8
-1ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc43f8ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe3fe3fffffffffffffffffffff
-fffffffffffffffffffffffffffffffffff8
-3ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7811ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe7fe7fffffffffffffffffffff
-fffffffffffffffffffffffffffffffffff8
-1ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7ff8ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe3fe3fffffffffffffffffffff
-fffffffffffffffffffffffffffffffffff8
-3ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7819ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe7fe7fffffffffffffffffffff
-fffffffffffffffffffffffffffffffffff8
-1ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7920ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe3fe3fffffffffffffffffffff
-fffffffffffffffffffffffffffffffffff8
-3ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7b91ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe7fe7fffffffffffffffffffff
-fffffffffffffffffffffffffffffffffff8
-1ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc73a0ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe3fe3fffffffffffffffffffff
-fffffffffffffffffffffffffffffffffff8
-3ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7c21ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe7fe7fffffffffffffffffffff
-fffffffffffffffffffffffffffffffffff8
-1ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7ff8ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe3fe3fffffffffffffffffffff
-fffffffffffffffffffffffffffffffffff8
-3ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc73f1ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe7fe7fffffffffffffffffffff
-fffffffffffffffffffffffffffffffffff8
-1ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7818ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe3fe3f87fa1e1f1fb07ef86180
-001e7e78f8c7f87187fffffffffffffffff8
-3ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7ff1ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe7fe7f05723e0f09b1fef92498
-000efc3870c3f820b3fffffffffffffffff8
-1ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7c78ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe3fe3fdd74ff666d97fcfbae3f
-feecfdf32659feee33fffffffffffffffff8
-3ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7931ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe7fe7fcf349e72e5b4fcfbaca7
-beedfbf7af5cfe5e07fffffffffffffffff8
-1ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7398ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe3fe3fdfb41e74e590fc796107
-7ef3fa37af5cff5e07fffffffffffffffff8
-3ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7991ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe7fe7fdfa5ff75ec97fcf8e37f
-bef3f38f0e5dff5ebbfffffffffffffffff8
-1ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7c38ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe3fe3fdf8dfe6dc8bff87bed7f
-3ef3f38f5ed9ff5cbbfffffffffffffffff8
-3ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7ff1ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe7fe7fdfcdcf4dcb367b7bed73
-7cf7f72e4cd3e65db3fffffffffffffffff8
-1ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7f98ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe3fe3f87cc1f1c99307b79ed07
-3ef7f070e1c7f04187fffffffffffffffff8
-3ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7f91ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe7fe7f1fce3f3e3bb1ff7bec8f
-7ef7f9f1e3cff8e39ffffffffffffffffff8
-1ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc73f8ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe3fe3fffffffffffffffffffff
-fffffffffffffffffffffffffffffffffff8
-3ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7871ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe7fe7fffffffffffffffffffff
-fffffffffffffffffffffffffffffffffff8
-1ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7f08ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe3fe3fc60f060bef3fbcf38420
-411fe41c767a3fb61061fffffffffffffff8
-3ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7c21ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe7fe7fc20f363aee3fbc711c80
-070fe4c836ba0fb47247fffffffffffffff8
-1ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc71f0ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe3fe3f98ffb6fa6cffb9e77ddd
-df67e6ebb69ae7b5fb5ffffffffffffffff8
-3ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7ff9ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe7fe7fbccf861a6d1f1bef059d
-8373c493869af7b41243fffffffffffffff8
-1ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc4010ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe3fe3f3c0fa43a681f13ce1d39
-8673d637ae9af7887887fffffffffffffff8
-3ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7ff9ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe7fe7f387fb2faabcf17df7c7d
-bf77c6b7aeaa6785f0dffffffffffffffff8
-1ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc4430ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe3fe3f7affbbf2abdf171c7df9
-9f6fc097aeaacfb5f6dffffffffffffffff8
-3ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc4039ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe7fe7f72ffa2c28b1e565961f9
-b94f9ad76ca21fa5c258fffffffffffffff8
-1ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7bb0ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe3fe3f06ff8e1ac83ed0c305f9
-c31fb8c060b33f2413417ffffffffffffff8
-3ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7399ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe7fe7fdeffbf7bfdffd9efbdff
-cffffbf9f3fffffe7f6ffffffffffffffff8
-1ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7830ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe3fe3fffffffffffffffffffff
-fffffffffffffffffffffffffffffffffff8
-3ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7ff9ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe7fe7fffffffffffffffffffff
-ffffffffff7ffffffffffffffffffffffff8
-1ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7d30ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe3fe3f83ce61080f0c61f02d90
-7dcc8374000fbc7ff4107d20fffffffffff8
-3ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7819ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe7fe7f9cdc47300e0924f00d80
-7ccc81245029b87df471dd27fffffffffff8
-1ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7bf0ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe3fe3fbeb9df377efbb6feed9d
-f88cd94dbce993fdb5f7cd3ffffffffffff8
-3ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7819ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe7fe7f063bc1677e4384fecb1d
-f898530c1ce8927db4104d21fffffffffff8
-1ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7830ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe3fe3f1f73c70f7e1791fee35d
-f80a42083ce8b03d34e1cd43fffffffffff8
-3ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7ff9ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe7fe7f3e37df1f7e77a5fecb1d
-fa48c36dfce8953d25f7d56ffffffffffff8
-1ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc78b0ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe3fe3f3e979f3f7ef7adfecf09
-fa485b6dccea273c25e7d15ffffffffffff8
-3ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7299ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe7fe7fa0c6587f7ef766fcdaed
-fbe35b648ceb247ccd861968bffffffffff8
-1ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7890ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe3fe3f85e0c13f7e7066fecaed
-fbe359741ce9a0fecc30d9613ffffffffff8
-3ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7c39ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe7fe7fdff9e7ff7ff9feffffed
-ffef5f7e7debb3fffef9ff77fffffffffff8
-1ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7ff0ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe3fe3fffffffffffffffffffff
-fffffffffffffffffffffffffffffffffff8
-3ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc4839ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe7fe7fffffffffffffffffffff
-fffffffffffffffffffffffffffffffffff8
-1ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc5ab0ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe3fe3fc00041f1c3efada01c7f
-d82f7c1d90e007fffffffffffffffffffff8
-3ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7bf9ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe7fe7f9c77cfe599ed8d81d8bc
-dbefbecdb44f77fffffffffffffffffffff8
-1ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7bf0ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe3fe3f3f77dfcfbded8d1dd3fc
-dbe93eed977ff7fffffffffffffffffffff8
-3ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7819ffff9e5c83
-c183020001fbfc706c081e04c83fc3e7bfdfcfffffffffe7fe7f077051c1bded9959e07e
-c8697cf1b701c7fffffffffffffffffffff8
-1ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7ff0ffffdcdcbb
-c0091c0000f3f83728101e3cd09f02673f9dcfffffffffe3fe3f8761c3c0bde9c359f83c
-50e97ee3b7078ffffffffffffffffffffff8
-3ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc5bf9ffffcc9cb9
-debd7fcfee67e3f729f7fcfcdfdfef463f8cefffffffffe7fe7ff377dffe79e94919ffbc
-5be17cebb65fbffffffffffffffffffffff8
-1fff3b01f9f005cc080c07ffffffffc07207ffe40e73f019ce1007fffc4010ffffe39db3
-dcb303dfcf4fe03669123c0ddf1fef443f2cefffffffffe3fe3ff7771fdc7be65a59f3bd
-9ba47ecbb4defffffffffffffffffffffff8
-3fff3b0efbf005c878cc3fffffffffee3261f3c8ccf7ff39d8493ffffc7bf9fffff3bda7
-d1820fcfcf1fe030c830383c1c3fefd93f6c6fffffffffe7fe7f277617c933f65ac9f23d
-9a243e9935d8fffffffffffffffffffffff8
-1fff3b7e73ff3dc9fdedffffffffffcf9279f999e4f7ffb3c1ff3ffffc73f0fffff3bd0f
-c3927fdfdf9fff81c9f3fcfc5cffcfd93f096fffffffffe3fe3f8f70d7e187e65ac9f87d
-986ebe3833e1bffffffffffffffffffffff8
-3fff3a6367ff39d91dcd8fffffffffcf927dfdb3f4f7ffb3d01f3ffffc7bf9fffff3bd3f
-cfbb7ddfcfbfefa7cbf7fdfdddffcfd9bf0d2fffffffffe7fe7fdf79dff7cffffbfffcff
-ddfefffcffe7bffffffffffffffffffffff8
-1fff02030fff3c100c180fffffffffef967dfc33e5e7ffb7d00f3ffffc7810fffff3b9af
-dfbb71dfdfbfe737cbf6fce1dfffcfdfbe698fffffffffe3fe3fffffffffffffffffffff
-fffffffffffffffffffffffffffffffffff8
-3fff127f9fff385bfc99ffffffffffcf3271fe67e9f7ffb7dfe73ffffc7ff9fffff781a7
-dfb907dfcf3ff077c9f2fe0ddcff03dfbee1cfffffffffe7fe7fffffffffffffffffffff
-fffffffffffffffffffffffffffffffffff8
-1fff7a7d9fff79dbf9d9f7ffffffffee7663fe67c9e7efa793cf3ffffc78b0fffff7cfbf
-dfbd9fdfff7ffcf7ffffff3ffeff3fffbfffdfffffffffe3fe3fffffffffffffffffffff
-fffffffffffffffffffffffffffffffffff8
-3fff72789fff79dbc1c9e7ffffffffe4f747fef31c87e332118f7ffffc7299ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe7fe7fffffffffffffffffffff
-fffffffffffffffffffffffffffffffffff8
-1fff7701bfff79d80dcc0fffffffffe1f31ffcf03c07f030181f3ffffc7290ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe3fe3fffffffffffffffffffff
-fffffffffffffffffffffffffffffffffff8
-3fff738f3fff7ddc39ec3ffffffffff7ffbffefdff7ffefdff7ffffffc7839fffff30601
-60bc7bbff3e4060cf9fbc703f3c607fbf907ffffffffffe7fe7fffffffffffffffffffff
-fffffffffffffffffffffffffffffffffff8
-1ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7ff0fffff3384e
-479971bff2f494fcf9fb973f3b967ff3bd31ffffffffffe3fe3fffffffffffffffffffff
-fffffffffffffffffffffffffffffffffff8
-3ffffffffffffffffffffffffffffffe7c7f1ef7ffd473ff7efcf1fffc7f79ffffe3bbce
-5fbbf13ff277bdfdf9f33f7f3b3efff19d39ffffffffffe7fe7fffffffffffffffffffff
-fffffffffffffffffffffffffffffffffff8
-1fffe1efc1fc014fb8181ffffffffff830301e679f0060ff3cc000fffc7830ffffeb23ce
-48b3e53ff2779c0df9f323033b7c0ff19d7cffffffffffe3fe3fffffffffffffffffffff
-fffffffffffffffffffffffffffffffffff8
-3fffc04fc078024738718ffffffffff1b3d3fc673f13ce7e398fbe7ffc7299ffffeb87ce
-41b7ed3ff273b83dfbf2410f3b7c1fe59d7dffffffffffe7fe7fffffffffffffffffffff
-fffffffffffffffffffffffffffffffffff8
-1fff8e4fce3fde4733f9cfffffffffc7f397fc667ff39f7e319ffe7ffc7890ffffe327ce
-4f27e13ff6379df9fbf27d7f5a7cffe18d39ffffffffffe3fe3fffffffffffffffffffff
-fffffffffffffffffffffffffffffffffff8
-3fff9f4fdfbf9e4632199fffffffffc033a03960fff33f7e9180f8fffc79b9ffffc137ce
-5fa7a57df297bdf9f3f6f97d4af8fbe5a533ffffffffffe7fe7fffffffffffffffffffff
-fffffffffffffffffffffffffffffffffff8
-1fff3f4fcfa0de50a0f83fffffffffff9063f966fff33f7ecc9fc3fffc7ab0ffffdd33ce
-5f264c31f6c7bdc18312e37062e6c3ccb127ffffffffffe3fe3ffffffffff3ffffffffff
-fffffffffffffffffffffffffffffffffff8
-3fff3e5fcf329e59b7f93fffffffffffd1e7f8267ff33e7ecc9feffffc7039ffffdd3bce
-5f30dc03f2e7bc0c18320f06730e0fecb98fffffffffffe7fe7ffffffffff3ffffffffff
-fffffffffffffffffffffffffffffffffff8
-1fff7c5fce7f9e59b7eb9fffffffffcf93e7c3277ff77cfeec9e3ffffc7fb0fffffd7bfe
-ffb9ff9ff7f7be7cfcff3f9ffb1f3ffefdffffffffffffe3fe3ffffffffff7ffffffffff
-fffffffffffffffffffffffffffffffffff8
-3fff38de08ff9e5f97899bffffffffe237f617a73ff730fefc987ffffc7f99ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe7fe7ffffffffff7ffffffffff
-fffffffffffffffffffffffffffffffffff8
-1fff01c0e1ff9e5f9819cbfffffffff073f037afbff783fefec1e7fffc7830ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe3fe3ffffffffff7ffffffffff
-fffffffffffffffffffffffffffffffffff8
-3fffefe7f7fffeffddfffffffffffffffffffffffffffffffffffffffc7ff9fffff833a4
-000fc001ddede9de7c00e81fe1ce730201038403ffffffe7fe7ffffffffff7ffffffffff
-fffffffffffffffffffffffffffffffffff8
-1ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7f90ffffe3b3a4
-9cff9f9dccedc9de7c9cc9ffc58c733a0e7f149fffffffe3fe3ffffffffff7fffffffbfc
-7f1dfbf3bf70fe3c7ffee7fff7fffffffff8
-3ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7f99ffffe797a7
-9dffdf9d8ce59bccff9cdbff9f8ce33bcefe7f9fffffffe7fe7fffffffffe7fffffffbf0
-180cf3019e4070003f7c81ce73fffffffff8
-1ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc7bf0ffffcfc7a7
-bc0f91b38ce43be9ff9dd81f018c6b33ce04079fffffffe3fe3ffffffffff7fffffffbf3
-d3f8e63f9c6f73f39f3d9cce77fffffffff8
-3ffffffffffffffffffffffffffffffffffffffffffffffffffffffffc70f9ffffdd87a7
-983fc183ac643bf3ff9c107f80a26907ce1e039fffffffe7fe7fffffffffe7fffffff3fb
-93f8c7778cec67f39f993ede67fffffffff8
-1fffffffffffffffffffffffffffffffffffbffffffffffffffffffffc7e10ffffdc27a7
-bdff9f930d2593f3ff9cdbfffeb24127defff99fffffffe3fe3fffffffffeffffffff3f0
-301a1603486060323fc67e9eeffffffffff8
-3fffffffffffffffffffffffffffffffffff9ffffffffffffffffffffc78f9ffffde6f27
-bde79fbb25add3c7ff9ddbcfbcb64d77defaf39fffffffe7fe7fffffffffeffffffff3f0
-63fb127f626f67f07fe67c9ecffffffffff8
-1fffffffffffffffffffffffffffffffffffdffffffffffffffffffffc78f0ffffc06627
-9dc7dfbb658dcb17ff9ddb8f98bf5d73ce62639fffffffe3fe3fffffffffeffffffff3f3
-33fb327f626fa7f37feefc9ecffffffffff8
-3fffffffffffffffffffffffffffffffffffdffffffffffffffffffffc7e19ffffe16027
-bc1fdfb975c9e837ff9dd83fc1bf3d3bdf07079fffffffe7fe7fffffffffeffffffff3f3
-b7cbb278766f27873fcef99cfffffffffff8
-1fffffffffffffffffffffffffffffffffffdffffffffffffffffffffc7830ffffff7bef
-be7fdfbdf7effcf7ffffdcffe7ff7d7bdf9f9fffffffffe3fe3fffffffffeffffffff3f3
-930bf2617f686613bfce6398dffffffffff8
-3fffffffffffffffffffffffffffffffffffcffffffffffffffffffffc73f9ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe7fe7fffffffffcffffffff3f3
-d87bfb0f7f63f0f79fdf0fc29ffffffffff8
-1ffffffff3ffffffffffffffffffffffffffeffffffffffffffffffffc78f0fffffdfffe
-7fbd7f7fffb1ffffe79fcfffffffffffffffffffffffffe3fe3fffffffffdfffffffffff
-fffffffffffffffffffffffffffffffffff8
-3ffffffff7ffffffffffffffffffffffffffeffffffffffffffffffffc7e19fffff06f60
-3f981c1dcbb07f3a04040fffffffffffffffffffffffffe7fe7fffffffffdfffffffffff
-fffffffffffffffffffffffffffffffffff8
-1ffffffff7ffffffffffffffffffffffffffeffffffffffffffffffffc7c30fffff32767
-ff19d8cddb961f3a7ef4ffffffffffffffffffffffffffe3fe3fffffffffdfffffffffff
-ffffffffffc39fdf87dffffffffffffffff8
-3ffffffff7fffffffffffffffffffffffffff7fffffffffffffffffffc71f9ffffe7a727
-ff1dd9e9cb939f3afee5ffffffffffffffffffffffffffe7fe7fffffffffdfffffffffec
-3ce581c07e019fc8039f3ffffffffffffff8
-1ffffffff7fffffffffffffffffffffffffffffffffffffffffffffffc7e30ffffcf9360
-7f5913ebd197df3606c81fffffffffffffffffffffffffe3fe3fffffffffdffffffff3c8
-1ce48cc7fc3f9fc8071f7ffffffffffffff8
-3ffffffff7fffffffffffffffffffffffffff7fffffffffffffffffffc7839ffffcfa327
-ff4c37ebd0d79f047e18ffffffffffffffffffffffffffe7fe7fffffffff9ffffffff333
-cdeedc9ffee79fcf8f0f7ffffffffffffff8
-1ffffffff7fffffffffffffffffffffffffff7fffffffffffffffffffc73f0ffffdf29af
-ff0937cbd2933f36fec9ffffffffffffffffffffffffffe3fe3fffffffff9ffffffffb37
-e9eed880fc039f9f3f4e7ffffffffffffff8
-3ffffffff7fffffffffffffffffffffffffff7fffffffffffffffffffc73f9ffffde6c6f
-be4b979bd6163f76f2e9e7ffffffffffffffffffffffffe7fe7fffffffffbffffffffc67
-cbef8307fc0fbf9e3e6efffffffffffffff8
-1ffffffff7fffffffffffffffffffffffffff3fffffffffffffffffffc7830ffffcc6e66
-3eeb931b13107f76e2edc5ffffffffffffffffffffffffe3fe3fffffffffbffffffffcef
-cbef8b9ffcff3f8e7e0efffffffffffffff8
-3fffffffe7fffffffffffffffffffffffffffbfffffffffffffffffffc7e19ffffc1ee70
-7eebd07817b9ff760ee41dffffffffffffffffffffffffe7fe7fffffffffbffffffffcef
-9bef9dbf7cf9be5cfc0efffffffffffffff8
-1fffffffe7fffffffffffffffffffffffffffbfffffffffffffffffffc71f0ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe3fe3fffffffffbffffffffde7
-390f9c987c41909800e7fffffffffffffff8
-3fffffffeffffffffffffffffffffffffffffbfffffffffffffffffffc7e39ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe7fe7fffffffffbffffffffdf0
-780f9cc1fe03019804e4fffffffffffffff8
-1fffffffeffffffffffffffffffffffffffff9fffffffffffffffffffc7e10ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe3fe3fffffffffbffffffffff9
-fefffeefff1f87d8ffe5fffffffffffffff8
-3fffffffeffffffffffffffffffffffffffffdfffffffffffffffffffc70f9ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe7fe7fffffffffbfffffffffff
-fffffffffffffffffffffffffffffffffff8
-1fffffffeffffffffffffffffffffffffffffdfffffffffffffffffffc43f0ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe3fe3fffffffffffffffffffff
-fffffffffffffffffffffffffffffffffff8
-3fffffffeffffffffffffffffffffffffffffdfffffffffffffffffffc7c19ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe7fe7fffffffffbfffffffffff
-fffffffffffffffffffffffffffffffffff8
-1fffffffeffffffffffffffffffffffffffffcfffffffffffffffffffc7fb0ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe3fe3fffffffff7fffffffffff
-ffffff9ffffffffffffffffffffffffffff8
-3fffffffcffffffffffffffffffffffffffffefffffffffffffffffffc43f9ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe7fe7fffffffff7fffffffffff
-ffffffdffffffffffffffffffffffffffff8
-1fffffffcffffffffffffffffffffffffffffefffffffffffffffffffc7810ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe3fe3fffffffff7fffffffffff
-ffffffcffffffffffffffffffffffffffff8
-3fffffffdffffffffffffffffffffffffffffffffffffffffffffffffc7ff9ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe7fe7fffffffff7fffffffffff
-ffffffeffffffffffffffffffffffffffff8
-1fffffffdffffffffffffffffffffffffffffffffffffffffffffffffc73b0ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe3fe3fffffffff7fffffffffff
-fffffff7fffffffffffffffffffffffffff8
-3fffffffdffffffffffffffffffffffffffffffffffffffffffffffffc7b99ffffffffff
-ffffffffffffffffffffffffffffffffffffffffffffffe7fe7fffffffff7fffffffffff
-fffffff7fffffffffffffffffffffffffff8
-1fffffffdffffffffffffffffffffffffffffffc1ffffffffffffffffc7ef0ffffffffff
-ffffffffffffffffffffffffffffe0ffffffffffffffffe3fe3ffffffffe7fffffffffff
-fffffff3ffffe0fffffffffffffffffffff8
-3fffffffdffffffffffffffffffffffffffffff001fffffffffffffffc7839ffffffffe7
-ffffffffffffffffffffffffffff800fffffffffffffffe7fe7ffffffffe7fffffffffff
-fffffffbffff800ffffffffffffffffffff8
-1fffffffdfffffffffffffffffffffffffffffe7fc7ffffffffffffffc7390ffffffffe7
-ffffffffffffffffffffffffffff3fe3ffffffffffffffe3fe3ffffffffeffffffffffff
-fffffff9ffff3fe3fffffffffffffffffff8
-3fffffff9fffffffffffffffffffffffffffff8fff3ffffffffffffffc7b99ffffffffef
-fffffffffffffffffffffffffffc7ff9ffffffffffffffe7fe7ffffffffeffffffffffff
-fffffffdfffc7ff9fffffffffffffffffff8
-1fffffff9fffffffffffffffffffffffffffff3fffcffffffffffffffc7800ffffffffef
-fffffffffffffffffffffffffff9fffe7fffffffffffffe3fe3ffffffffeffffffffffff
-fffffffefffbfffe7ffffffffffffffffff8
-3fffffffbffffffffffffffffffffffffffffe7fffe7fffffffffffffc7ff1ffffffffef
-fffffffffffffffffffffffffff3ffff3fffffffffffffe7fe7ffffffffeffffffffffff
-fffffffe7ff3ffff3ffffffffffffffffff8
-1fffffffbffffffffffffffffffffffffffffe7ffff3fffffffffffffc7bd8ffffffffef
-fffffffffffffffffffffffffff7ffff9fffffffffffffe3fe3ffffffffeffffffffffff
-ffffffff7ff7ffffbffffffffffffffffff8
-3fffffffbffffffffffffffffffffffffffffe7ffff9fffffffffffffc6011ffffffffef
-fffffffffffffffffffffffffff7ffffdfffffffffffffe7fe7ffffffffcffffffffffff
-ffffffff7fe7ffff9ffffffffffffffffff8
-1fffffffbffffffffffffffffffffffffffffefefffdfffffffffffffc6038ffffffffcf
-ffffffffffffffffffffffffffe7f7ffcfffffffffffffe3fe3ffffffffcffffffffffff
-ffffffffbfe7f7ffcffffffffffffffffff8
-3fffffffbffffffffffffffffffffffffffffce03ffdfffffffffffffc7bd1ffffffffdf
-ffffffffffffffffffffffffffe711ffefffffffffffffe7fe7ffffffffdffffffffffff
-ffffffffbfef13ffeffffffffffffffffff8
-1fffffffbffffffffffffffffffffffffffffcc9bffefffffffffffffc6018ffffffffdf
-ffffffffffffffffffffffffffe44dffe7ffffffffffffe3fe3ffffffffdffffffffffff
-ffffffffdfec4dffe7fffffffffffffffff8
-3fffffffbffffffffffffffffffffffffffffcbccffefffffffffffffc6031ffffffffdf
-ffffffffffffffffffffffffffe9e6fff7ffffffffffffe7fe7ffffffffdffffffffffff
-ffffffffdfe9e4fff7fffffffffffffffff8
-1fffffff3ffffffffffffffffffffffffffffe3eeffe7ffffffffffffc7ff8ffffffffdf
-fffffffffffffffffffffffffff3f67ff3ffffffffffffe3fe3ffffffffdffffffffffff
-ffffffffefe3f6fff3fffffffffffffffff8
-3fffffff3ffffffffffffffffffffffffffffe7e6fff3ffffffffffffc7c31ffffffffdf
-fffffffffffffffffffffffffff3f37ff9ffffffffffffe7fe7ffffffffdffffffffffff
-ffffffffefe7f27ffbfffffffffffffffff8
-1fffffff7ffffffffffffffffffffffffffffefe77ff9ffffffffffffc72b8ffffffff9f
-fffffffffffffffffffffffffff7fb7ffcffffffffffffe3fe3ffffffff9ffffffffffff
-fffffffff7e7fb7ffdfffffffffffffffff8
-3fffffff7ffffffffffffffffffffffffffffeff77ffdffffffffffffc7bf1ffffffffbf
-fffffffffffffffffffffffffff7fb3ffeffffffffffffe7fe7ffffffff9ffffffffffff
-fffffffff3effb3ffcfffffffffffffffff8
-1fffffff7fffffffffffffffffffffffffffffff6cffdffffffffffffc4038ffffffffbf
-fffffffffffffffffffffffffffffb67feffffffffffffe3fe3ffffffffbffffffffffff
-fffffffffbfffb67fdfffffffffffffffff8
-3fffffff7fffffffffffffffffffffffffffffff683fdffffffffffffc4011ffffffffbf
-fffffffffffffffffffffffffffffb41feffffffffffffe7fe7ffffffffbffffffffffff
-fffffffff9fffb41fcfffffffffffffffff8
-1fffffff7fffffffffffffffffffffffffffffff711fdffffffffffffc7ff8ffffffffbf
-fffffffffffffffffffffffffffffb0cfeffffffffffffe3fe3ffffffffbffffffffffff
-fffffffffffffb14fcfffffffffffffffff8
-3fffffff7fffffffffffffffffffffffffffffff23cfdffffffffffffc7ff1ffffffffbf
-fffffffffffffffffffffffffffff91e7cffffffffffffe7fe7ffffffffbffffffffffff
-fffffffffffffe1e7dfffffffffffffffff8
-1fffffff7fffffffffffffffffffffffffffffbf93a7dffffffffffffc7ff8ffffffffbf
-fffffffffffffffffffffffffffdfc9d7effffffffffffe3fe3ffffffffbffffffffffff
-fffffffffff9f99d7cfffffffffffffffff8
-3fffffff7fffffffffffffffffffffffffffff9e3fb79ffffffffffffc7ff1ffffffffbf
-fffffffffffffffffffffffffffcf1fcbcffffffffffffe7fe7ffffffff3ffffffffffff
-fffffffffffcf3fdfdfffffffffffffffff8
-1ffffffeffffffffffffffffffffffffffffff9cbf279ffffffffffffc7ff8ffffffff7f
-fffffffffffffffffffffffffffce5fb3cffffffffffffe3fe3ffffffff3ffffffffffff
-fffffffffffce7f93dfffffffffffffffff8
-3ffffffeffffffffffffffffffffffffffffff997fe3bffffffffffffc7ff1ffffffff7f
-fffffffffffffffffffffffffff8cbff3dffffffffffffe7fe7ffffffff7ffffffffffff
-fffffffffffccbff3dfffffffffffffffff8
-1ffffffefffffffffffffffffffffffffffffe027f1b9ffffffffffffc7ff8ffffffff7f
-fffffffffffffffffffffffffff013f8ddffffffffffffe3fe3ffffffff7ffffffffffff
-ffffffffffe013f89dfffffffffffffffff8
-3ffffffefffffffffffffffffffffffffffffe01fff9bffffffffffffc7ff1ffffffff7f
-fffffffffffffffffffffffffff20fffddffffffffffffe7fe7ffffffff7ffffffffffff
-ffffffffffe24fffddfffffffffffffffff8
-1ffffffefffffffffffffffffffffffffffffebffff9dffffffffffffc7ff8ffffffff7f
-fffffffffffffffffffffffffff1ffffdeffffffffffffe3fe3ffffffff7ffffffffffff
-fffffffffff1ffffddfffffffffffffffff8
-3ffffffefffffffffffffffffffffffffffffcbffffddffffffffffffc7ff1ffffffff7f
-ffffffffffffffffffffffffffe5ffffceffffffffffffe7fe7ffffffff7ffffffffffff
-ffffffffffedffffccfffffffffffffffff8
-1ffffffefffffffffffffffffffffffffffffaa1fffdcffffffffffffc7ff8ffffffff7f
-ffffffffffffffffffffffffff990fffee7fffffffffffe3fe3ffffffff7ffffffffffff
-ffffffffff910fffee7ffffffffffffffff8
-3ffffffefffffffffffffffffffffffffffff20c7ffceffffffffffffc7ff1ffffffff7f
-ffffffffffffffffffffffffff1263ffe77fffffffffffe7fe7ffffffff7ffffffffffff
-ffffffffff1063ffe77ffffffffffffffff8
-1ffffffeffffffffffffffffffffffffffffefdf3ffef7fffffffffffc7ff8fffffffe7f
-ffffffffffffffffffffffffff7ef9ffe7bfffffffffffe3fe3fffffffffffffffffffff
-fffffffffe7ef1ffe7bffffffffffffffff8
-3ffffffeffffffffffffffffffffffffffffef9f8ffe7bfffffffffffc7ff1fffffffeff
-ffffffffffffffffffffffffff7cfcfff3dfffffffffffe7fe7ffffffff7ffffffffffff
-ffffffffff7ce4fff3dffffffffffffffff8
-1ffffffcfffffffffffffffffffffffffffff02bcffe79fffffffffffc7ff8fffffffeff
-ffffffffffffffffffffffffff037efff3cfffffffffffe3fe3fffffffefffffffffffff
-ffffffffff0306fff3dffffffffffffffff8
-3ffffffeffffffffffffffffffffffffffffffe1effe39fffffffffffc7ff1fffffffeff
-ffffffffffffffffffffffffffff3efff1cfffffffffffe7fe7fffffffefffffffffffff
-ffffffffffff02fff3cffffffffffffffff8
-1ffffffcfffffffffffffffffffffffffffffff1efffb9fffffffffffc7ff8fffffffeff
-ffffffffffffffffffffffffffffbf7ffccfffffffffffe3fe3fffffffefffffffffffff
-ffffffffffff867ffdcffffffffffffffff8
-3ffffffdfffffffffffffffffffffffffffffff1e7ff9cfffffffffffc7ff1fffffffeff
-ffffffffffffffffffffffffffff9f3ffce7ffffffffffe7fe7fffffffefffffffffffff
-ffffffffffff8f3ffceffffffffffffffff8
-1ffffffdfffffffffffffffffffffffffffffff7e3ff0efffffffffffc7ff8fffffffcff
-ffffffffffffffffffffffffffffbf1ff867ffffffffffe3fe3fffffffefffffffffffff
-ffffffffffff7e1ff86ffffffffffffffff8
-3ffffffdffffffffffffffffffffffffffffffe7ebff4efffffffffffc7ff1fffffffcff
-ffffffffffffffffffffffffffff3edffb77ffffffffffe7fe7fffffffefffffffffffff
-ffffffffffff3edffa67fffffffffffffff8
-1ffffffdffffffffffffffffffffffffffffffe7fbfe6f7ffffffffffc7ff8fffffffdff
-ffffffffffffffffffffffffffff3fdff373ffffffffffe3fe3fffffffcfffffffffffff
-ffffffffffff3fdff273fffffffffffffff8
-3ffffffdffffffffffffffffffffffffffffffe7fbfeef7ffffffffffc7ff1fffffffdff
-ffffffffffffffffffffffffffff3fdfe77bffffffffffe7fe7fffffffcfffffffffffff
-ffffffffffff3fdfe773fffffffffffffff8
-1ffffffdffffffffffffffffffffffffffffffe7f9fee73ffffffffffc4038fffffffdff
-ffffffffffffffffffffffffffff3fcfe739ffffffffffe3fe3fffffffdfffffffffffff
-ffffffffffff7fdfe639fffffffffffffff8
-3ffffff9fffffffffffffffffffffffffffffff7fdfdc3bffffffffffc7bb1fffffffdff
-ffffffffffffffffffffffffffffbfefee9dffffffffffe7fe7fffffffdfffffffffffff
-ffffffffffff3fefee9dfffffffffffffff8
-1ffffff9fffffffffffffffffffffffffffffff3fdf198dffffffffffc7398fffffffdff
-ffffffffffffffffffffffffffffbfef9cc4ffffffffffe3fe3fffffffdfffffffffffff
-ffffffffffffbfef9cccfffffffffffffff8
-3ffffffbfffffffffffffffffffffffffffffff3f983924ffffffffffc7831fffffff9ff
-ffffffffffffffffffffffffffff9fcc1c927fffffffffe7fe7fffffffdfffffffffffff
-ffffffffffffbfd81c827ffffffffffffff8
-1ffffffbfffffffffffffffffffffffffffffff9f82f2167fffffffffc7cf8fffffff9ff
-ffffffffffffffffffffffffffffdfc1791b3fffffffffe3fe3fffffffdfffffffffffff
-ffffffffffff9fc279133ffffffffffffff8
-3ffffffbfffffffffffffffffffffffffffffff9fbfe2773fffffffffc7f91fffffffbff
-ffffffffffffffffffffffffffffdfdff123bfffffffffe7fe7fffffff9fffffffffffff
-ffffffffffff9fdff333bffffffffffffff8
-1ffffffbfffffffffffffffffffffffffffffffdf3fcec7bfffffffffc7038fffffffbff
-ffffffffffffffffffffffffffffef9fe653dfffffffffe3fe3fffffff9fffffffffffff
-ffffffffffffef9fe6539ffffffffffffff8
-3ffffffbfffffffffffffffffffffffffffffff8e7f14579fffffffffc7291fffffffbff
-ffffffffffffffffffffffffffffc73f8e6bdfffffffffe7fe7fffffffbfffffffffffff
-ffffffffffffc73f8c73dffffffffffffff8
-1ffffffbfffffffffffffffffffffffffffffffbe7c2157dfffffffffc7a18fffffffbff
-ffffffffffffffffffffffffffffdf3e30abcfffffffffe3fe3fffffffbfffffffffffff
-ffffffffffff9f7e308bcffffffffffffff8
-3ffffff3fffffffffffffffffffffffffffffffbef1c4d3dfffffffffc7f71fffffff3ff
-ffffffffffffffffffffffffffffdf78a269cfffffffffe7fe7fffffffbfffffffffffff
-ffffffffffff9f78a279cffffffffffffff8
-1ffffff3fffffffffffffffffffffffffffffff3e82902bdfffffffffc7ff8fffffff3ff
-ffffffffffffffffffffffffffff9f414829cfffffffffe3fe3fffffffbfffffffffffff
-ffff87ffffffbe414829cffffffffffffff8
-3ffffff7fffffffffffffffffffffffffffffff7c1d27289fffffffffc4831fffffff7ff
-ffffffffffffffffffffffffffffbe0e8594dfffffffffe7fe7fffffffbfffffffffffff
-ffffbfffffffbc169394dffffffffffffff8
-1ffffff7fffffffffffffffffffffffffffffff786b09343fffffffffc7ff8fffffff7ff
-ffffffffffffffffffffffffffffbc298a9a1fffffffffe3fe3fffffff3fffffffffffff
-ffff7fffffff3c3524961ffffffffffffff8
-3ffffff7ffffffffffffffffffffffffffffffe402a1a959fffffffffc4031fffffff7ff
-ffffffffffffffffffffffffffff241b0a8a5fffffffffe7fe7fffffff3fffffffffffff
-fffef3ffffffe00b0d4adffffffffffffff8
-1ffffff7ffffffffffffffffffffffffffffffee0148a94bfffffffffc4018fffffff7ff
-ffffffffffffffffffffffffffff6014554a7fffffffffe3fe3fffffff7fffffffffffff
-ffffe3ffffff7014554adffffffffffffff8
-3ffffff7ffffffffffffffffffffffffffffffef8299a94ffffffffffc7ff1fffffff7ff
-ffffffffffffffffffffffffffff7414954affffffffffe7fe7fffffff7fffffffffffff
-ffffdfffffff6c0c954afffffffffffffff8
-1fffffffffffffffffffffffffffffffffffffed829254dffffffffffc4038ffffffe7ff
-ffffffffffffffffffffffffffff6c08aaa67fffffffffe3fe3fffffff7fffffffffffff
-fffffff3ffff6c192aa4fffffffffffffff8
-3fffffffffffffffffffffffffffffffffffffe50123544ffffffffffc7ff1ffffffefff
-ffffffffffffffffffffffffffff08192aa27fffffffffe7fe7fffffff7fffffffffffff
-fffff001ffff0c092aa67ffffffffffffff8
-1ffffffffffffffffffffffffffffffffffffff38336aaaffffffffffc4038ffffffefff
-ffffffffffffffffffffffffffff9c0995557fffffffffe3fe3fffffffffffffffffffff
-ffffe13c7fff98192aa4fffffffffffffff8
-3fffffffffffffffffffffffffffffffffffffff8124aa67fffffffffc4011ffffffefff
-fffffffffffffffffffffffffffffc132aa53fffffffffe7fe7fffffffffffffffffffff
-ffff8fb93ffff0132aa37ffffffffffffff8
-1fffffffffffffffffffffffffffffffffffffff8245aa27fffffffffc7ff8ffffffefff
-fffffffffffffffffffffffffffffc1235553fffffffffe3fe3fffffffffffffffffffff
-ffff6f999fffc01255567ffffffffffffff8
-3fffffffffffffffffffffffffffffffffffffff02652a6ffffffffffc7ff1ffffffefff
-fffffffffffffffffffffffffffff81115517fffffffffe7fe7fffffffffffffffffffff
-fff8cd9a4fffc81115517ffffffffffffff8
-1fffffffffffffffffffffffffffffffffffffff8222aa47fffffffffc7ff8ffffffefff
-fffffffffffffffffffffffffffffc1335533fffffffffe3fe3fffffffffffffffffffff
-fff39ddad3ff381735527ffffffffffffff8
-3fffffffffffffffffffffffffffffffffffffff82655527fffffffffc78f1ffffffefff
-fffffffffffffffffffffffffffffc1625513fffffffffe7fe7fffffffffffffffffffff
-ffee499329fe480525537ffffffffffffff8
-1fffffffffffffffffffffffffffffffffffffff02455527fffffffffc4038ffffffffff
-fffffffffffffffffffffffffffff8052d533fffffffffe3fe3fffffffffffffffffffff
-ffcce3d2d47cd8052d513ffffffffffffff8
-3fffffffffffffffffffffffffffffffffffffff02a55537fffffffffc4f91ffffffefff
-fffffffffffffffffffffffffffff81532aabfffffffffe7fe7fffffffffffffffffffff
-ffe1c7b15679500552ab3ffffffffffffff8
-1fffffffffffffffffffffffffffffffffffffff00a55527fffffffffc4238ffffffdfff
-fffffffffffffffffffffffffffff8052d52bfffffffffe3fe3fffffffffffffffffffff
-fff59b215532a80535517ffffffffffffff8
-3fffffffffffffffffffffffffffffffffffffff00a55517fffffffffc78f1ffffffdfff
-fffffffffffffffffffffffffffff80512a93fffffffffe7fe7fffffffffffffffffffff
-fffe3b76aac6a8052aa93ffffffffffffff8
-1fffffffffffffffffffffffffffffffffffffff00a55537fffffffffc7df8ffffffffff
-fffffffffffffffffffffffffffff8052aaabfffffffffe3fe3fffffffffffffffffffff
-ffffb8e55544a80d2aab3ffffffffffffff8
-3fffffffffffffffffffffffffffffffffffffff01a55527fffffffffc6031ffffffffff
-fffffffffffffffffffffffffffff80d2aa93fffffffffe7fe7fffffffffffffffffffff
-ffffb1e5554aa80555527ffffffffffffff8
-1fffffffffffffffffffffffffffffffffffffff00a55517fffffffffc4f98ffffffffff
-fffffffffffffffffffffffffffff8013553bfffffffffe3fe3fffffffffffffffffffff
-ffff87f35546a80d55513ffffffffffffff8
-3fffffffffffffffffffffffffffffffffffffff02a55567fffffffffc4211ffffffffff
-fffffffffffffffffffffffffffff81d15523fffffffffe7fe7fffffffffffffffffffff
-fffffff8d54558192ab33ffffffffffffff8
-1fffffffffffffffffffffffffffffffffffffff02a6aa57fffffffffc7878ffffffffff
-fffffffffffffffffffffffffffff8153551bfffffffffe3fe3fffffffffffffffffffff
-fffffffc2a8aa01515517ffffffffffffff8
-3fffffffffffffffffffffffffffffffffffffff02a55557fffffffffc7ff1ffffffffff
-fffffffffffffffffffffffffffff81515533fffffffffe7fe7fffffffffffffffffffff
-ffffffff1505481535533ffffffffffffff8
-1fffffffffffffffffffffffffffffffffffffff01455527fffffffffc6078ffffffffff
-fffffffffffffffffffffffffffff8153552bfffffffffe3fe3fffffffffffffffffffff
-ffffffffcd3a981515523ffffffffffffff8
-3fffffffffffffffffffffffffffffffffffffff02a2aa67fffffffffc4f11ffffffffff
-fffffffffffffffffffffffffffff81515513fffffffffe7fe7fffffffffffffffffffff
-ffffffffe3a5981535537ffffffffffffff8
-1fffc000bfffffffffffffffffffffffffffffff03555527fffffffffc4f98fffe0005ff
-fffffffffffffffffffffffffffff80a95533fffffffffe3fe3fff80017fffffffffffff
-ffff9ffff075381525527ffffffffffffff8
-3ffe0bffa3ffffffffffffffffffffffffffffff02a2aa6ffffffffffc6071fff05ffd1f
-fffffffffffffffffffffffffffff81535527fffffffffe7fe7ffc17ff47ffffffffffff
-ffffc1fffe0c781515517ffffffffffffff8
-1ffef77ff9ffffffffffffffffffffffffffffff01655527fffffffffc7ff8ffe7fbffcf
-fffffffffffffffffffffffffffff80d25533fffffffffe3fe3ffdeefff3ffffffffffff
-ffffffffff80f81575537ffffffffffffff8
-3ffcadfffe7fffffffffffffffffffffffffffff02a6aa27fffffffffc6191ffe42ffff3
-fffffffffffffffffffffffffffff8152d513fffffffffe7fe7ff95bfffcffffffffffff
-ffffbffffff3f81515527ffffffffffffff8
-1ff9bbbfff3fffffffffffffffffffffffffffff02a55667fffffffffc4cb8ffcfdbfffb
-fffffffffffffffffffffffffffff81535557fffffffffe3fe3ff3777ffe7fffffffffff
-ffffc0fffffff8152aa57ffffffffffffff8
-3ff80effffbfffffffffffffffffffe3ffffffff01a2aa2ffffffffffc5e11ffc07ffff9
-fffffffffffffffffffffffffffff80d2aa53fffffffffe7fe7ff01dffff7fffffffffff
-fffff1fffffff80d55527ffffffffffffff8
-1ff283ffffbfffffffffffffffffffefffffffff0126aa67fffffffffc6718ff941bfffd
-fffffffffffffffffffffffffffff80915513fffffffffe3fe3fe507ffff7fffffffffff
-fffffffffffff80955557ffffffffffffff8
-3ff17bffff3fffffffffffffffffffd9ffffffff00a55527fffffffffc7ff1ffabdffffc
-fffffffffffffffffffffffffffff80535573fffffffffe7fe7fe2f7fffe7fffffffffff
-fffffffffffff81515557ffffffffffffff8
-1ff7597fff1fffffffffffffffffffdbffffffff01a5552ffffffffffc7ff8ffaacffffa
-fffffffffffffffffffffffffffff80d25517fffffffffe3fe3feeb37ffe3fffffffffff
-fffffffffffff80d6aa27ffffffffffffff8
-3ff4d9ffff5ffffffffffffffffffffbfffffffe01255527fffffffffc7ff1ff96cffffa
-fffffffffffffffffffffffffffff80a2d553fffffffffe7fe7fe9b3fffebfffffffffff
-fffffffffffff8092aa97ffffffffffffff8
-1fe6bdffff5ffffffffffffffffffff7fffffffe01a6aa67fffffffffc7ff8ff35effffa
-fffffffffffffffffffffffffffff80ab5513fffffffffe3fe3fcd7bfffebfffffffffff
-fffffffffffff81535537ffffffffffffff8
-3ff2adfffe4ffffffffffffffffffffffbfffff401505527fffffffffc7019ff956ffff2
-fffffffffffffffffffffffffffff80502ab3fffffffffe7fe7feaabfffc9fffffffffff
-fffffffffffff80a82aa7ffffffffffffff8
-1fe6dcf101dffffffffffffffffffffc00907c0100a1d527fffffffffc47c0ffb6e78806
-7ffffffffffffffffffffffffffff80d0d513fffffffffe3fe3fcaf9e203bfffffffffff
-fffffffffffff80d0d513ffffffffffffff8
-3ff4b604bfdffffffffffffffffffff9f62400b301a05557fffffffffc7ff1ff15b023fe
-fffffffffffffffffffffffffffff80502aabfffffffffe7fe7fe55c097fbfffffffffff
-fffffffffffff80502ab7ffffffffffffff8
-1ff37fffffeffffffffffffffffffffbef33b5a901535533fffffffffc7b38ffb6fffffe
-fffffffffffffffffffffffffffff80d9552bfffffffffe3fe3fedbfffffdfffffffffff
-fffffffffffff80a95513ffffffffffffff8
-3fe6d7ffffdffffffffffffffffffff805a4aa5501515553fffffffffc7391ff2ddffffe
-7ffffffffffffffffffffffffffffc051aaabfffffffffe7fe7fcb77ffffbfffffffffff
-fffffffffffffc0d1aaabffffffffffffff8
-1ff4bfffffcffffffffffffffffffffeed25555500a15517fffffffffc7b98ffab7ffffe
-fffffffffffffffffffffffffffffc0a85533fffffffffe3fe3feadfffff9fffffffffff
-fffffffffffffc0a85533ffffffffffffff8
-3ff5dbfcffdffffffffffffffffffffec975555501a4aa53fffffffffc7831ff95ffe7fe
-fffffffffffffffffffffffffffff8052d549fffffffffe7fe7fe57ff9ffbfffffffffff
-fffffffffffff8056d54bffffffffffffff8
-1ff2bffcffdffffffffffffffffffffe0366aaab00a75553fffffffffc7ff8ffb7bfd7fe
-fffffffffffffffffffffffffffffc053555bfffffffffe3fe3fcdeff9ffbfffffffffff
-fffffffffffffc0a29529ffffffffffffff8
-3fe577f8ffdffffffffffffffffffffeff62aaaa80a4aa6bfffffffffc4fe1ff2affe7fe
-fffffffffffffffffffffffffffffc064aa51fffffffffe7fe7fcabff1ffbfffffffffff
-fffffffffffffc0d6b529ffffffffffffff8
-1fe5dffdffdffffffffffffffffffffe4f66aaaa80aaaa53fffffffffc6018ff17bfeffe
-fffffffffffffffffffffffffffffc053552bfffffffffe3fe3fd5effbffbfffffffffff
-fffffffffffffc052a52bffffffffffffff8
-3feabfffffdfffffffffffffffffffff1f7557aa804aaa2bfffffffffc7ff1ff3afffffe
-fffffffffffffffffffffffffffffc0265529fffffffffe7fe7fcabfffffbfffffffffff
-fffffffffffffc0a55a69ffffffffffffff8
-1fe377ffffdfffffffffffffffffffffc102b03581caaa6bfffffffffc7ff8ff57fffffe
-fffffffffffffffffffffffffffffc0e4d56bfffffffffe3fe3fcdffffffbfffffffffff
-fffffffffffffc0a55529ffffffffffffff8
-3fe6ddfffffffffffffffffffffffffffff68100004d5653fffffffffc7ff1ff2d6ffffc
-fffffffffffffffffffffffffffffc0a59529fffffffffe7fe7fcb5bffffffffffffffff
-fffffffffffffc0a2aa69ffffffffffffff8
-1feafbffffdffffffffffffffffffffffff01fff818554abfffffffffc7ff8ff2b9ffffe
-fffffffffffffffffffffffffffffc0466a6bfffffffffe3fe3fcaf7ffffbfffffffffff
-fffffffffffff80c6aa4bffffffffffffff8
-3fe5b3fffffffffffffffffffffffffffff9ffff009554d3fffffffffc7b91ff2fbffffe
-fffffffffffffffffffffffffffff80c2aa49fffffffffe7fe7fcde7ffffffffffffffff
-fffffffffffffc044aa59ffffffffffffff8
-1feb77ffffdfffffffffffffffffffffffffffff818d54abfffffffffc6018ff35bffffe
-fffffffffffffffffffffffffffffc085552bfffffffffe3fe3fcb6fffffbfffffffffff
-fffffffffffffc0c6aaa9ffffffffffffff8
-3fe2f7ffffffffffffffffffffffffff9fffffff8112aaabfffffffffc7bf1ff2fbffffe
-fffffffffffffffffffffffffffffc0caaa69fffffffffe7fe7fd6efffffffffffffffff
-fffffffffffff814aaaabffffffffffffff8
-1fedb7ffffdfffffffffffffffffffffe1ffffff01955453fffffffffc7818ff5abffffe
-fffffffffffffffffffffffffffff804d552bfffffffffe3fe3fcdefffffbfffffffffff
-fffffffffffff804aaa29ffffffffffffff8
-3fe6f7ffffffffffffffffffffffffffffffffff011aaaabfffffffffc73f1ff37bffffe
-fffffffffffffffffffffffffffff80caaa69fffffffffe7fe7fcb6fffffffffffffffff
-fffffffffffff80caaa69ffffffffffffff8
-1fe5b7ffffdfffffffffffffffffffff9cffffff009554d3fffffffffc7bf8ff2dbffffc
-fffffffffffffffffffffffffffff808aaa4bfffffffffe3fe3fd5efffffbfffffffffff
-fffffffffffff808aaa49ffffffffffffff8
-3fe6f3ffffffffffffffffffffffffffc1ffffff019554abfffffffffc4031ff5fbffffe
-fffffffffffffffffffffffffffff80caaaa9fffffffffe7fe7fcf67ffffffffffffffff
-fffffffffffff80caaadbffffffffffffff8
-1fe5f7ffffdfffffffffffffffffffffffffffff009554abfffffffffc4018ff35bffffd
-fffffffffffffffffffffffffffff809aaaabfffffffffe3fe3fd5efffffbfffffffffff
-fffffffffffff80955491ffffffffffffff8
-3ff5b7ffffdfffffffffffffffffffffffffffff03355553fffffffffc7ff1ffafbffffe
-fffffffffffffffffffffffffffff808aaa29fffffffffe7fe7febf7ffffbfffffffffff
-fffffffffffff819aaa69ffffffffffffff8
-1ff6fbffffdffffffffffffffffffffffffffffe012554abfffffffffc7808ff5bbffffe
-fffffffffffffffffffffffffffff011aaa6bfffffffffe3fe3fcd6fffffbfffffffffff
-fffffffffffff810aaaabffffffffffffff8
-3fe5f7ffffdfffffffffffffffffffffffffffff072d54abfffffffffc7ba1ff2fbffffe
-fffffffffffffffffffffffffffff8392aa49fffffffffe7fe7fcbefffffbfffffffffff
-fffffffffffff029554a9ffffffffffffff8
-1fe7bbffffdfffffffffffffffffffffffffffff0432a953fffffffffc73b0ff3dbffffe
-fffffffffffffffffffffffffffff811aaaabfffffffffe3fe3fcff7ffffbfffffffffff
-fffffffffffff829aaaa9ffffffffffffff8
-3feafbffffdfffffffffffffffffffffffffffff831555a9fffffffffc7901ff579ffffe
-fffffffffffffffffffffffffffffc2955469fffffffffe7fe7fd577ffffbfffffffffff
-fffffffffffffc312aaa9ffffffffffffff8
-1fe5ffffffcfffffffffffffffffffffffffffff852aa959fffffffffc7cf0ff3f9ffffe
-7ffffffffffffffffffffffffffffc28aaad5fffffffffe3fe3fcfffffff9fffffffffff
-fffffffffffffc296aa55ffffffffffffff8
-3fe7bbffffdfffffffffffffffffffffffffffffe51554abfffffffffc5a39ff2bdffffe
-ffffffffffffffffffffffffffffff5355495fffffffffe7fe7fd5f7ffffbfffffffffff
-fffffffffffffd6a954d5ffffffffffffff8
-1fe6fbffffdffffffffffffffffffffffffffffff52aaaa9fffffffffc4830ff3f9ffffe
-ffffffffffffffffffffffffffffff69554a9fffffffffe3fe3fcf77ffffbfffffffffff
-ffffffffffffff2955555ffffffffffffff8
-3fedffffffdfffffffffffffffffffffffffffffe76aa959fffffffffc7ff9ff37bffffe
-7fffffffffffffffffffffffffffff33555adfffffffffe7fe7fcbffffffbfffffffffff
-ffffffffffffff3355559ffffffffffffff8
-1febbbffffdffffffffffffffffffffffffffffff11550a3fffffffffc73f0ff6f9ffffe
-ffffffffffffffffffffffffffffff8aaa871fffffffffe3fe3fddf7ffffbfffffffffff
-ffffffffffffff92aa8b1ffffffffffffff8
-3fe5fbffffcffffffffffffffffffffffffffffff86aaa07fffffffffc7819ff3bdfffff
-7fffffffffffffffffffffffffffffc155403fffffffffe7fe7fc7f7ffff9fffffffffff
-ffffffffffffffc355407ffffffffffffff8
-1feffbffffdffffffffffffffffffffffffffffff935535ffffffffffc7ff0ff5fdffffe
-ffffffffffffffffffffffffffffffc9aa9affffffffffe3fe3fdef7ffffbfffffffffff
-ffffffffffffffc9aa9afffffffffffffff8
-3fe77bfffe0ffffffffffffffffffffffffffffff88772cffffffffffc7ff9ff77dffff0
-7fffffffffffffffffffffffffffffcc3baa7fffffffffe7fe7fdbf7fffc1fffffffffff
-ffffffffffffffcc3baafffffffffffffff8
-1fe1fdffe0effffffffffffffffffffffffffffff890069ffffffffffc70f0ff1fefff07
-7fffffffffffffffffffffffffffffc48014ffffffffffe3fe3fc7fbffc1dfffffffffff
-ffffffffffffffc90014fffffffffffffff8
-3fc82c800f77fffffffffffffffffffffffffffff0a9c89ffffffffffc7e19fe4164007b
-bfffffffffffffffffffffffffffff854e54ffffffffffe7fe7f9059001eefffffffffff
-ffffffffffffff858cd4fffffffffffffff8
-1fdf805ff877fffffffffffffffffffffffffffff894c6bffffffffffc7e00fcfc00ffe3
-bfffffffffffffffffffffffffffff854355ffffffffffe3fe3fbf00bff0efffffffffff
-ffffffffffffff894655fffffffffffffff8
-3fbff93fe7bbfffffffffffffffffffffffffffff0aa1d3ffffffffffc71f1fdffcbff3d
-dfffffffffffffffffffffffffffffc4b0a9ffffffffffe7fe7f7ff27fcf77ffffffffff
-ffffffffffffffc4b0a9fffffffffffffff8
-1fbffb2ffc4bfffffffffffffffffffffffffffff8aad17ffffffffffc7ef8fdff997fc2
-5fffffffffffffffffffffffffffff85aea9ffffffffffe3fe3f7ff65ff897ffffffffff
-ffffffffffffff8557a9fffffffffffffff8
-3fbffb2ff399fffffffffffffffffffffffffffff215573ffffffffffc7831fbff997f9c
-dfffffffffffffffffffffffffffff94aaabffffffffffe7fe7e7ff65fe733ffffffffff
-ffffffffffffff84d429fffffffffffffff8
-1f7ff84ffc3bfffffffffffffffffffffffffffff2d5547ffffffffffc7398fbffc27ff3
-dfffffffffffffffffffffffffffff925553ffffffffffe3fe3efff0dff877ffffffffff
-ffffffffffffffc255d3fffffffffffffff8
-167ffffffffdffffff6db6dbfffffffffffffffff24aab7ffffffffffc7b98bbffffffef
-effffff6db6dbfffffffffffffffffc65553ffffffffffe7fe36ffffdffffbfffffedb6d
-b7ffffffffffff865557fffffffffffffff8
-000000000000000000000001fffffffffffffffff262aa7ffffffffffc78000000000000
-0000000000000fffffffffffffffff912b53ffffffffffe3fe0000000000000000000000
-03ffffffffffff851553fffffffffffffff8
-088449200082008100888889fffffffffffffffff2114a7ffffffffffc7ff04104880048
-0841020911111fffffffffffffffff949457ffffffffffe7fe1102245001040102011111
-13ffffffffffffb48ca7fffffffffffffff8
-1111040aaa28aa142a222221fffffffffffffffff2181afffffffffffc7ff89450215502
-a11428a044444fffffffffffffffffb4c1a7ffffffffffe3fe2428810554515428544444
-43ffffffffffffa4c0a7fffffffffffffff8
-022450a0008200a140888889fffffffffffffffff24f64fffffffffffc783001028a0028
-0441420511111fffffffffffffffff923a67ffffffffffe7fe0142145001040142811111
-13ffffffffffff927baffffffffffffffff8
-1488850aaa54aa0a0a222211fffffffffffffffff26555fffffffffffc7b985454115542
-aa8a08a844448fffffffffffffffff93154fffffffffffe3fe1408a10554a95414144444
-23ffffffffffffb32a4ffffffffffffffff8
-000000000000000000000001fffffffffffffffff31154fffffffffffc73900000000000
-0000000000001fffffffffffffffffb28aa7ffffffffffe7fe0000000000000000000000
-03ffffffffffff920aaffffffffffffffff8
-1fffbfffd5557ffffffffffffffffffffffffffff25554fffffffffffc7839fffdfffb5a
-a9ffffffffffffffffffffffffffff916aa7ffffffffffe3fe7fff7fffaaaaffffffffff
-ffffffffffffff91aaa7fffffffffffffff8
-3fffdffaaaaa7ffffffffffffffffffffffffffff555547ffffffffffc7cf0fffefed6b5
-53ffffffffffffffffffffffffffff935563ffffffffffe7fe3fffbff55554ffffffffff
-ffffffffffffffb2aaa3fffffffffffffff8
-1fffefb75aaafffffffffffffffffffffffffffff32aa8fffffffffffc7ff9ffff7fbaaa
-a7ffffffffffffffffffffffffffffb15547ffffffffffe3fe7fffdfdeb555ffffffffff
-ffffffffffffff935547fffffffffffffff8
-3fffe7eed555fffffffffffffffffffffffffffff255507ffffffffffc6630ffff7fed55
-6fffffffffffffffffffffffffffff92aa87ffffffffffe7fe3fffcef5aaabffffffffff
-ffffffffffffff92aa87fffffffffffffff8
-1ffff3fdaaa9fffffffffffffffffffffffffffff22ab6fffffffffffc4f99ffffbdbaaa
-9fffffffffffffffffffffffffffffb155b7ffffffffffe3fe7fffefdf5553ffffffffff
-ffffffffffffffb155b7fffffffffffffff8
-3ffffbdb5557fffffffffffffffffffffffffffff63544fffffffffffc5f90ffffcff7aa
-bfffffffffffffffffffffffffffff12aa27ffffffffffe7fe3ffff7faaaafffffffffff
-ffffffffffffff20aa27fffffffffffffff8
-1ffffdfefaaffffffffffffffffffffffffffffff2558afffffffffffc4fb9ffffefad55
-7fffffffffffffffffffffffffffff32acd7ffffffffffe3fe7ffffb77f55fffffffffff
-ffffffffffffff33ac6ffffffffffffffff8
-3ffffeffd5dffffffffffffffffffffffffffffff65636fffffffffffc6030fffff7fb6e
-ffffffffffffffffffffffffffffffb3b1a7ffffffffffe7fe7ffffdfeabbfffffffffff
-ffffffffffffff96b1a7fffffffffffffff8
-00000000000000000000000000000000000000000000000000000000007df80000000000
-000000000000000000000000000000000000000000000003fe0000000000000000000000
-000000000000000000000000000000000000
-00000000000000000000000000000000000000000000000000000000007ff00000000000
-000000000000000000000000000000000000000000000007fe0000000000000000000000
-000000000000000000000000000000000000
-
-
-showpage
-
-% stop using temporary dictionary
-end
-
-% restore original state
-origstate restore
-
-%%Trailer
-cleartomark
-countdictstack exch sub { end } repeat
-restore
-%%EOF
diff --git a/doc/uf002331.jpg b/doc/uf002331.jpg
deleted file mode 100644
index 3fd1b784..00000000
--- a/doc/uf002331.jpg
+++ /dev/null
Binary files differ
generated by cgit v1.2.3 (git 2.25.1) at 2025-05-04 19:33:56 +0000