home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 5 / FreshFish_July-August1994.bin / bbs / gnu / gawk-2.15.5-diffs.lha / src / diffs / gawk-2.15.5.diffs
Text File  |  1994-07-12  |  502KB  |  12,599 lines
  1. diff -rc --new-file /src/baseline/gawk-2.15.5/Makefile.in gawk-2.15.5/Makefile.in
  2. *** /src/baseline/gawk-2.15.5/Makefile.in    Wed Dec 29 11:25:34 1993
  3. --- gawk-2.15.5/Makefile.in    Sun Jun 12 21:43:01 1994
  4. ***************
  5. *** 19,98 ****
  6.   # along with GAWK; see the file COPYING.  If not, write to
  7.   # the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  8.   
  9. ! # User tunable macros -- CHANGE THESE IN Makefile.in RATHER THAN IN 
  10. ! # Makefile, OR configure WILL OVERWRITE YOUR CHANGES
  11.   
  12. ! prefix = /usr/local
  13.   exec_prefix = $(prefix)
  14. - binprefix =
  15. - manprefix =
  16.   
  17.   bindir = $(exec_prefix)/bin
  18.   libdir = $(exec_prefix)/lib
  19. ! mandir = $(prefix)/man/man1
  20. ! manext = .1
  21.   infodir = $(prefix)/info
  22.   
  23. ! #    The provided "configure" is used to turn a config file (samples in
  24. ! #    the "config" directory into commands to edit config.in into
  25. ! #    a suitable config.h and to edit Makefile.in into Makefile.
  26. ! #    To port GAWK, create an appropriate config file using the ones in
  27. ! #    the config directory as examples and using the comments in config.in
  28. ! #    as a guide.
  29. ! 
  30. ! CC=         gcc -g
  31. ! ##MAKE_CC## CC = cc
  32. ! 
  33. ! PROFILE=    #-pg
  34. ! DEBUG=        #-DMALLOCDEBUG #-DDEBUG #-DFUNC_TRACE #-DMPROF
  35. ! LINKSTATIC=    #-Bstatic
  36. ! WARN=        #-W -Wunused -Wimplicit -Wreturn-type -Wcomment    # for gcc only
  37. ! 
  38. ! # Parser to use on grammar - any one of the following will work
  39. ! PARSER = bison -y
  40. ! #PARSER = yacc
  41. ! #PARSER = byacc
  42. ! 
  43. ! # Set LIBS to any libraries that are machine specific
  44. ! LIBS =
  45. ! 
  46. ! # Cray 2 running Unicos 5.0.7
  47. ! ##MAKE_LIBNET## LIBS = -lnet
  48. ! 
  49. ! 
  50. ! # Systems with alloca in /lib/libPW.a
  51. ! ##MAKE_ALLOCA_PW## LIBS = -lPW
  52. ! 
  53. ! # ALLOCA - only needed if you use bison
  54. ! #    Set equal to alloca.o if your system is S5 and you don't have
  55. ! #    alloca. Uncomment one of the rules below to make alloca.o from
  56. ! #    either alloca.s or alloca.c.
  57. ! #    This should have already been done automatically by configure.
  58. ! #
  59. ! #    Some systems have alloca in libPW.a, so LIBS=-lPW may work, too.
  60. ! ##MAKE_ALLOCA_C## ALLOCA= alloca.o
  61. ! ##MAKE_ALLOCA_S## ALLOCA= alloca.o
  62. ! 
  63. ! VFLAGS=
  64. ! 
  65. ! # VMS POSIX, VAXC V3.2
  66. ! ##MAKE_VMS-Posix## VFLAGS = -UVMS -D__STDC__=0
  67.   
  68. ! # HP/Apollo running cc version 6.7 or earlier
  69. ! ##MAKE_Apollo## VFLAGS = -U__STDC__ -A run,sys5.3
  70. ! ##MAKE_Apollo## LIBS = -A sys,any
  71.   
  72. ! # SGI IRIX 4.0.5 cc flags
  73. ! ##MAKE_SGI## VFLAGS = -cckr
  74. ! 
  75. ! ##MAKE_NeXT## VFLAGS = -DGFMT_WORKAROUND
  76. ! 
  77. ! CFLAGS = -O
  78. ! FLAGS = -DGAWK -DHAVE_CONFIG_H $(VFLAGS) $(DEBUG) $(PROFILE) $(WARN)
  79. ! LDFLAGS = $(LINKSTATIC) $(PROFILE)
  80.   
  81.   .c.o:
  82. !     $(CC) $(CFLAGS) $(FLAGS) -c $<
  83.   
  84.   # object files
  85.   AWKOBJS = main.o eval.o builtin.o msg.o iop.o io.o field.o array.o \
  86. --- 19,66 ----
  87.   # along with GAWK; see the file COPYING.  If not, write to
  88.   # the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  89.   
  90. ! #### Start of system configuration section. ####
  91.   
  92. ! VPATH = @srcdir@
  93. ! srcdir = @srcdir@
  94. ! 
  95. ! # Common prefix for machine-independent installed files.
  96. ! prefix = /gnu
  97. ! # Common prefix for machine-dependent installed files.
  98.   exec_prefix = $(prefix)
  99.   
  100. + # Directory to install executables in.
  101.   bindir = $(exec_prefix)/bin
  102. + # Directory to install libraries in.
  103.   libdir = $(exec_prefix)/lib
  104. ! # Directory to install the Info files in.
  105.   infodir = $(prefix)/info
  106. + # Directory to install the man page in.
  107. + mandir = $(prefix)/man/man$(manext)
  108. + # Number to put on the man page filename.
  109. + manext = 1
  110. + 
  111. + # Program to install executables.
  112. + INSTALL_PROGRAM = @INSTALL_PROGRAM@
  113. + # Program to install data like man pages.
  114. + INSTALL_DATA = @INSTALL_DATA@
  115. + # Generic install program.
  116. + INSTALL = @INSTALL@
  117. + 
  118. + CC = @CC@
  119. + DEFS = @DEFS@
  120. + CFLAGS = @CFLAGS@
  121.   
  122. ! LDFLAGS = @LDFLAGS@
  123. ! LIBS = @LIBS@
  124.   
  125. ! YACC = @YACC@
  126.   
  127. ! #### End of system configuration section. ####
  128.   
  129. + # "-I." is needed to find config.h in the build directory.
  130.   .c.o:
  131. !     $(CC) -c -I. -I$(srcdir) $(DEFS) $(CFLAGS) $< $(OUTPUT_OPTION)
  132.   
  133.   # object files
  134.   AWKOBJS = main.o eval.o builtin.o msg.o iop.o io.o field.o array.o \
  135. ***************
  136. *** 137,142 ****
  137. --- 105,112 ----
  138.   # Release of gawk.  There can be no leading or trailing white space here!
  139.   REL=2.15
  140.   
  141. + all:    gawk
  142. + 
  143.   # rules to build gawk
  144.   gawk:    $(ALLOBJS) $(GNUOBJS) $(REOBJS)
  145.       $(CC) -o gawk $(LDFLAGS) $(ALLOBJS) $(GNUOBJS) $(REOBJS) -lm $(LIBS)
  146. ***************
  147. *** 150,172 ****
  148.   main.o:    patchlevel.h
  149.   
  150.   awktab.c:    awk.y
  151. !     $(PARSER) -v awk.y
  152. ! ##MAKE_VMS-Posix##     mv ytab.c awktab.c
  153. ! ##MAKE_VMS-Posix## dummy.awk_tab.target:
  154. !     sed '/^extern char .malloc(), .realloc();$$/d' y.tab.c >awktab.c
  155. !     rm y.tab.c
  156.   
  157.   awktab.o:    awk.h
  158.   
  159. ! config.h:    config.in
  160. !     @echo You must provide a config.h!
  161. !     @echo Run \"./configure\" to build it for known systems
  162. !     @echo or copy config.in to config.h and edit it.; exit 1
  163.   
  164.   install:    gawk gawk.info
  165. !     cp gawk $(bindir) && chmod 755 $(bindir)/gawk
  166. !     cp gawk.1 $(mandir)/gawk$(manext) && chmod 644 $(mandir)/gawk$(manext)
  167. !     cp gawk.info* $(infodir) && chmod 644 $(infodir)/gawk.info*
  168.   
  169.   uninstall:
  170.       rm -f $(bindir)/gawk $(mandir)/gawk$(manext) $(infodir)/gawk.info*
  171. --- 120,141 ----
  172.   main.o:    patchlevel.h
  173.   
  174.   awktab.c:    awk.y
  175. !     @echo "expect 40 shift/reduce conflicts"
  176. !     $(YACC) -v $(srcdir)/awk.y
  177. !     @sed '/extern char.*malloc/d' <y.tab.c >awktab.c
  178. !     @rm y.tab.c
  179.   
  180.   awktab.o:    awk.h
  181.   
  182. ! # On AmigaDOS, there is no "native awk", so install gawk as both
  183. ! # /bin/gawk and /bin/awk.
  184.   
  185.   install:    gawk gawk.info
  186. !     $(INSTALL_PROGRAM) gawk $(bindir)/awk
  187. !     $(INSTALL_PROGRAM) gawk $(bindir)/gawk
  188. !     $(INSTALL_DATA) $(srcdir)/gawk.1 $(mandir)/gawk$(manext)
  189. !     cd $(srcdir); for f in gawk.info*; \
  190. !     do $(INSTALL_DATA) $$f $(infodir)/$$f; done
  191.   
  192.   uninstall:
  193.       rm -f $(bindir)/gawk $(mandir)/gawk$(manext) $(infodir)/gawk.info*
  194. ***************
  195. *** 181,193 ****
  196.   # One of these rules should have already been selected by running configure.
  197.   
  198.   
  199. - ##MAKE_ALLOCA_S## alloca.o:    alloca.s
  200. - ##MAKE_ALLOCA_S##     /lib/cpp < alloca.s | sed '/^#/d' > t.s
  201. - ##MAKE_ALLOCA_S##     as t.s -o alloca.o
  202. - ##MAKE_ALLOCA_S##     rm t.s
  203. - 
  204. - ##MAKE_ALLOCA_C## alloca.o:    alloca.c
  205. - 
  206.   # auxiliary rules for release maintenance
  207.   lint:    $(ALLSRC)
  208.       lint -hcbax $(FLAGS) $(ALLSRC)
  209. --- 150,155 ----
  210. ***************
  211. *** 215,228 ****
  212.       rm -f $(ALLDOC) gawk.log config.h
  213.   
  214.   gawk.dvi:    gawk.texi
  215. !     cp support/texinfo.tex .
  216. !     tex gawk.texi; texindex gawk.??
  217. !     tex gawk.texi; texindex gawk.??
  218. !     tex gawk.texi
  219.       rm -f texinfo.tex
  220.   
  221.   gawk.info:    gawk.texi
  222. !     makeinfo gawk.texi
  223.   
  224.   dist:    $(AWKSRC) $(GNUSRC) $(DOCS) $(MISC) $(COPIES) $(SUPPORT) distclean
  225.       -rm -rf gawk-$(REL)*
  226. --- 177,190 ----
  227.       rm -f $(ALLDOC) gawk.log config.h
  228.   
  229.   gawk.dvi:    gawk.texi
  230. !     cp $(srcdir)/support/texinfo.tex .
  231. !     tex $(srcdir)/gawk.texi; texindex gawk.??
  232. !     tex $(srcdir)/gawk.texi; texindex gawk.??
  233. !     tex $(srcdir)/gawk.texi
  234.       rm -f texinfo.tex
  235.   
  236.   gawk.info:    gawk.texi
  237. !     makeinfo $(srcdir)/gawk.texi
  238.   
  239.   dist:    $(AWKSRC) $(GNUSRC) $(DOCS) $(MISC) $(COPIES) $(SUPPORT) distclean
  240.       -rm -rf gawk-$(REL)*
  241. ***************
  242. *** 264,266 ****
  243. --- 226,242 ----
  244.   
  245.   check:    test
  246.   
  247. + Makefile:    config.status $(srcdir)/Makefile.in
  248. +         $(SHELL) config.status
  249. + 
  250. + config.h:    stamp-config ;
  251. + 
  252. + stamp-config:    config.status $(srcdir)/config.h.in
  253. +         $(SHELL) config.status
  254. +         touch stamp-config
  255. + 
  256. + configure:    configure.in
  257. +         autoconf $(ACFLAGS)
  258. + 
  259. + config.h.in:    configure.in
  260. +         autoheader $(ACFLAGS)
  261. diff -rc --new-file /src/baseline/gawk-2.15.5/Product-Info gawk-2.15.5/Product-Info
  262. *** /src/baseline/gawk-2.15.5/Product-Info    Thu Jan  1 00:00:00 1970
  263. --- gawk-2.15.5/Product-Info    Tue Jul 12 17:12:01 1994
  264. ***************
  265. *** 0 ****
  266. --- 1,31 ----
  267. + .name
  268. + gawk
  269. + .fullname
  270. + GNU awk, pattern scanning and processing language
  271. + .type
  272. + Programmer Tool
  273. + .short
  274. + Pattern scanning & processing.
  275. + .description
  276. + Gawk is the GNU Project's implementation of the AWK programming
  277. + language.  It conforms to the definition of the language in the POSIX
  278. + 1003.2 Command Language And Utilities Standard.  This version in turn
  279. + is based on the description in "The AWK Programming Language", by Aho,
  280. + Kernighan, and Weinberger, with the additional features defined in the
  281. + System V Release 4 version of UNIX awk.  Gawk also provides some
  282. + GNU-specific extensions.
  283. + 
  284. + The command line consists of options to gawk itself, the AWK program
  285. + text (if not supplied via the -f or --file options), and values to be
  286. + made available in the ARGC and ARGV pre-defined AWK variables.
  287. + .version
  288. + 2.15.5
  289. + .author
  290. + Paul Rubin
  291. + Jay Fenlason
  292. + .requirements
  293. + Amiga binary requires ixemul.library.
  294. + .distribution
  295. + GNU Public License
  296. + .described-by
  297. + Fred Fish (fnf@amigalib.com)
  298. diff -rc --new-file /src/baseline/gawk-2.15.5/README.amiga gawk-2.15.5/README.amiga
  299. *** /src/baseline/gawk-2.15.5/README.amiga    Tue Jun  1 15:22:31 1993
  300. --- gawk-2.15.5/README.amiga    Sun Jun 12 21:43:03 1994
  301. ***************
  302. *** 24,30 ****
  303.   Amiga under AmigaOS with gcc
  304.   DOPRNT_MISSING 1
  305.   ENVSEP ','
  306. ! DEFPATH  ".,/usr/local/lib"
  307.   HAVE_UNDERSCORE_SETJMP 1
  308.   SRANDOM_PROTO 1
  309.   STDC_HEADERS 1
  310. --- 24,30 ----
  311.   Amiga under AmigaOS with gcc
  312.   DOPRNT_MISSING 1
  313.   ENVSEP ','
  314. ! DEFPATH  ".,/gnu/lib"
  315.   HAVE_UNDERSCORE_SETJMP 1
  316.   SRANDOM_PROTO 1
  317.   STDC_HEADERS 1
  318. diff -rc --new-file /src/baseline/gawk-2.15.5/awk.h gawk-2.15.5/awk.h
  319. *** /src/baseline/gawk-2.15.5/awk.h    Wed May 11 22:28:46 1994
  320. --- gawk-2.15.5/awk.h    Sun Jun 12 21:43:07 1994
  321. ***************
  322. *** 67,74 ****
  323.   #define const
  324.   #endif
  325.   
  326. ! #ifndef SIGTYPE
  327. ! #define SIGTYPE    void
  328.   #endif
  329.   
  330.   #ifdef SIZE_T_MISSING
  331. --- 67,74 ----
  332.   #define const
  333.   #endif
  334.   
  335. ! #ifndef RETSIGTYPE
  336. ! #define RETSIGTYPE    void
  337.   #endif
  338.   
  339.   #ifdef SIZE_T_MISSING
  340. ***************
  341. *** 191,197 ****
  342.   #endif
  343.   
  344.   #ifndef DEFPATH
  345. ! #define DEFPATH    ".:/usr/local/lib/awk:/usr/lib/awk"
  346.   #endif
  347.   
  348.   #ifndef ENVSEP
  349. --- 191,197 ----
  350.   #endif
  351.   
  352.   #ifndef DEFPATH
  353. ! #define DEFPATH    ".:/local/lib/awk:/gnu/lib/awk"
  354.   #endif
  355.   
  356.   #ifndef ENVSEP
  357. ***************
  358. *** 723,729 ****
  359.   extern Regexp *mk_re_parse P((char *s, int ignorecase));
  360.   extern void load_environ P((void));
  361.   extern char *arg_assign P((char *arg));
  362. ! extern SIGTYPE catchsig P((int sig, int code));
  363.   /* msg.c */
  364.   extern void err P((const char *s, const char *emsg, va_list argp));
  365.   #if _MSC_VER == 510
  366. --- 723,729 ----
  367.   extern Regexp *mk_re_parse P((char *s, int ignorecase));
  368.   extern void load_environ P((void));
  369.   extern char *arg_assign P((char *arg));
  370. ! extern RETSIGTYPE catchsig P((int sig, int code));
  371.   /* msg.c */
  372.   extern void err P((const char *s, const char *emsg, va_list argp));
  373.   #if _MSC_VER == 510
  374. diff -rc --new-file /src/baseline/gawk-2.15.5/config/amigados gawk-2.15.5/config/amigados
  375. *** /src/baseline/gawk-2.15.5/config/amigados    Thu Jan  1 00:00:00 1970
  376. --- gawk-2.15.5/config/amigados    Sun Jun 12 21:43:23 1994
  377. ***************
  378. *** 0 ****
  379. --- 1,6 ----
  380. + Amiga under AmigaOS with gcc
  381. + ENVSEP ','
  382. + DEFPATH  ".,/gnu/lib"
  383. + HAVE_UNDERSCORE_SETJMP 1
  384. + SRANDOM_PROTO 1
  385. + STDC_HEADERS 1
  386. diff -rc --new-file /src/baseline/gawk-2.15.5/config.h.in gawk-2.15.5/config.h.in
  387. *** /src/baseline/gawk-2.15.5/config.h.in    Thu Jan  1 00:00:00 1970
  388. --- gawk-2.15.5/config.h.in    Sun Jun 12 21:43:26 1994
  389. ***************
  390. *** 0 ****
  391. --- 1,290 ----
  392. + /*
  393. +  * config.h -- configuration definitions for gawk.
  394. +  *
  395. +  * __SYSTEM__
  396. +  */
  397. + 
  398. + /* 
  399. +  * Copyright (C) 1991, 1992, 1993 the Free Software Foundation, Inc.
  400. +  * 
  401. +  * This file is part of GAWK, the GNU implementation of the
  402. +  * AWK Progamming Language.
  403. +  * 
  404. +  * GAWK is free software; you can redistribute it and/or modify
  405. +  * it under the terms of the GNU General Public License as published by
  406. +  * the Free Software Foundation; either version 2, or (at your option)
  407. +  * any later version.
  408. +  * 
  409. +  * GAWK is distributed in the hope that it will be useful,
  410. +  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  411. +  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  412. +  * GNU General Public License for more details.
  413. +  * 
  414. +  * You should have received a copy of the GNU General Public License
  415. +  * along with GAWK; see the file COPYING.  If not, write to
  416. +  * the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  417. +  */
  418. + 
  419. + /*
  420. +  * This file isolates configuration dependencies for gnu awk.
  421. +  * You should know something about your system, perhaps by having
  422. +  * a manual handy, when you edit this file.  You should copy config.h-dist
  423. +  * to config.h, and edit config.h.  Do not modify config.h-dist, so that
  424. +  * it will be easy to apply any patches that may be distributed.
  425. +  *
  426. +  * The general idea is that systems conforming to the various standards
  427. +  * should need to do the least amount of changing.  Definining the various
  428. +  * items in ths file usually means that your system is missing that
  429. +  * particular feature.
  430. +  *
  431. +  * The order of preference in standard conformance is ANSI C, POSIX,
  432. +  * and the SVID.
  433. +  *
  434. +  * If you have no clue as to what's going on with your system, try
  435. +  * compiling gawk without editing this file and see what shows up
  436. +  * missing in the link stage.  From there, you can probably figure out
  437. +  * which defines to turn on.
  438. +  */
  439. + 
  440. + /**************************/
  441. + /* Miscellanious features */
  442. + /**************************/
  443. + 
  444. + /*
  445. +  * BLKSIZE_MISSING
  446. +  *
  447. +  * Check your /usr/include/sys/stat.h file.  If the stat structure
  448. +  * does not have a member named st_blksize, define this.  (This will
  449. +  * most likely be the case on most System V systems prior to V.4.)
  450. +  */
  451. + #undef BLKSIZE_MISSING
  452. + 
  453. + /*
  454. +  * RETSIGTYPE
  455. +  *
  456. +  * The return type of the routines passed to the signal function.
  457. +  * Modern systems use `void', older systems use `int'.
  458. +  * If left undefined, it will default to void.
  459. +  */
  460. + #undef RETSIGTYPE
  461. + 
  462. + /*
  463. +  * SIZE_T_MISSING
  464. +  *
  465. +  * If your system has no typedef for size_t, define this to get a default
  466. +  */
  467. + #undef SIZE_T_MISSING
  468. + 
  469. + /*
  470. +  * CHAR_UNSIGNED
  471. +  *
  472. +  * If your machine uses unsigned characters (IBM RT and RS/6000 and others)
  473. +  * then define this for use in regex.c
  474. +  */
  475. + #undef CHAR_UNSIGNED
  476. + 
  477. + /*
  478. +  * HAVE_UNDERSCORE_SETJMP
  479. +  *
  480. +  * Check in your /usr/include/setjmp.h file.  If there are routines
  481. +  * there named _setjmp and _longjmp, then you should define this.
  482. +  * Typically only systems derived from Berkeley Unix have this.
  483. +  */
  484. + 
  485. + #undef HAVE_UNDERSCORE_SETJMP
  486. + 
  487. + /***********************************************/
  488. + /* Missing library subroutines or system calls */
  489. + /***********************************************/
  490. + 
  491. + /*
  492. +  * MEMCMP_MISSING
  493. +  * MEMCPY_MISSING
  494. +  * MEMSET_MISSING
  495. +  *
  496. +  * These three routines are for manipulating blocks of memory. Most
  497. +  * likely they will either all three be present or all three be missing,
  498. +  * so they're grouped together.
  499. +  */
  500. + 
  501. + #undef MEMCMP_MISSING
  502. + #undef MEMCPY_MISSING
  503. + #undef MEMSET_MISSING
  504. + 
  505. + /*
  506. +  * RANDOM_MISSING
  507. +  *
  508. +  * Your system does not have the random(3) suite of random number
  509. +  * generating routines.  These are different than the old rand(3)
  510. +  * routines!
  511. +  */
  512. + #undef RANDOM_MISSING
  513. + 
  514. + /*
  515. +  * STRCASE_MISSING
  516. +  *
  517. +  * Your system does not have the strcasemp() and strncasecmp()
  518. +  * routines that originated in Berkeley Unix.
  519. +  */
  520. + #undef STRCASE_MISSING
  521. + 
  522. + /*
  523. +  * STRCHR_MISSING
  524. +  *
  525. +  * Your system does not have the strchr() and strrchr() functions.
  526. +  */
  527. + #undef STRCHR_MISSING
  528. + 
  529. + /*
  530. +  * STRERROR_MISSING
  531. +  *
  532. +  * Your system lacks the ANSI C strerror() routine for returning the
  533. +  * strings associated with errno values.
  534. +  */
  535. + #undef STRERROR_MISSING
  536. + 
  537. + /*
  538. +  * STRTOD_MISSING
  539. +  *
  540. +  * Your system does not have the strtod() routine for converting
  541. +  * strings to double precision floating point values.
  542. +  */
  543. + #undef STRTOD_MISSING
  544. + 
  545. + /*
  546. +  * STRFTIME_MISSING
  547. +  *
  548. +  * Your system lacks the ANSI C strftime() routine for formatting
  549. +  * broken down time values.
  550. +  */
  551. + #undef STRFTIME_MISSING
  552. + 
  553. + /*
  554. +  * TZSET_MISSING
  555. +  *
  556. +  * If you have a 4.2 BSD vintage system, then the strftime() routine
  557. +  * supplied in the missing directory won't be enough, because it relies on the
  558. +  * tzset() routine from System V / Posix.  Fortunately, there is an
  559. +  * emulation for tzset() too that should do the trick.  If you don't
  560. +  * have tzset(), define this.
  561. +  */
  562. + #undef TZSET_MISSING
  563. + 
  564. + /*
  565. +  * TZNAME_MISSING
  566. +  *
  567. +  * Some systems do not support the external variables tzname and daylight.
  568. +  * If this is the case *and* strftime() is missing, define this.
  569. +  */
  570. + #undef TZNAME_MISSING
  571. + 
  572. + /*
  573. +  * STDC_HEADERS
  574. +  *
  575. +  * If your system does have ANSI compliant header files that
  576. +  * provide prototypes for library routines, then define this.
  577. +  */
  578. + #undef STDC_HEADERS
  579. + 
  580. + /*
  581. +  * NO_TOKEN_PASTING
  582. +  *
  583. +  * If your compiler define's __STDC__ but does not support token
  584. +  * pasting (tok##tok), then define this.
  585. +  */
  586. + #undef NO_TOKEN_PASTING
  587. + 
  588. + /*****************************************************************/
  589. + /* Stuff related to the Standard I/O Library.             */
  590. + /*****************************************************************/
  591. + /* Much of this is (still, unfortunately) black magic in nature. */
  592. + /* You may have to use some or all of these together to get gawk */
  593. + /* to work correctly.                         */
  594. + /*****************************************************************/
  595. + 
  596. + /*
  597. +  * NON_STD_SPRINTF
  598. +  *
  599. +  * Look in your /usr/include/stdio.h file.  If the return type of the
  600. +  * sprintf() function is NOT `int', define this.
  601. +  */
  602. + #undef NON_STD_SPRINTF
  603. + 
  604. + /*
  605. +  * VPRINTF_MISSING
  606. +  *
  607. +  * Define this if your system lacks vprintf() and the other routines
  608. +  * that go with it.  This will trigger an attempt to use _doprnt().
  609. +  * If you don't have that, this attempt will fail and you are on your own.
  610. +  */
  611. + #undef VPRINTF_MISSING
  612. + 
  613. + /*
  614. +  * Casts from size_t to int and back.  These will become unnecessary
  615. +  * at some point in the future, but for now are required where the
  616. +  * two types are a different representation.
  617. +  */
  618. + #undef SZTC
  619. + #undef INTC
  620. + 
  621. + /*
  622. +  * SYSTEM_MISSING
  623. +  *
  624. +  * Define this if your library does not provide a system function
  625. +  * or you are not entirely happy with it and would rather use
  626. +  * a provided replacement (atari only).
  627. +  */
  628. + #undef SYSTEM_MISSING
  629. + 
  630. + /*
  631. +  * FMOD_MISSING
  632. +  *
  633. +  * Define this if your system lacks the fmod() function and modf() will
  634. +  * be used instead.
  635. +  */
  636. + #undef FMOD_MISSING
  637. + 
  638. + 
  639. + /*******************************/
  640. + /* Gawk configuration options. */
  641. + /*******************************/
  642. + 
  643. + /*
  644. +  * DEFPATH
  645. +  *
  646. +  * The default search path for the -f option of gawk.  It is used
  647. +  * if the AWKPATH environment variable is undefined.  The default
  648. +  * definition is provided here.  Most likely you should not change
  649. +  * this.
  650. +  */
  651. + 
  652. + #define DEFPATH    ".,/local/lib/awk,/gnu/lib/awk"        /* HACK - fnf */
  653. + #define ENVSEP    ','                    /* HACK - fnf */
  654. + 
  655. + /*
  656. +  * alloca already has a prototype defined - don't redefine it
  657. +  */
  658. + #undef ALLOCA_PROTO
  659. + 
  660. + /*
  661. +  * srandom already has a prototype defined - don't redefine it
  662. +  */
  663. + #undef SRANDOM_PROTO
  664. + 
  665. + /*
  666. +  * getpgrp() in sysvr4 and POSIX takes no argument
  667. +  */
  668. + #undef GETPGRP_NOARG
  669. + 
  670. + /*
  671. +  * define const to nothing if not __STDC__
  672. +  */
  673. + #ifndef __STDC__
  674. + #define const
  675. + #endif
  676. + 
  677. + /* If svr4 and not gcc */
  678. + #undef SVR4
  679. + #ifdef SVR4
  680. + #define __svr4__ 1
  681. + #endif
  682. diff -rc --new-file /src/baseline/gawk-2.15.5/config.in gawk-2.15.5/config.in
  683. *** /src/baseline/gawk-2.15.5/config.in    Sun May  1 18:20:10 1994
  684. --- gawk-2.15.5/config.in    Sun Jun 12 21:43:29 1994
  685. ***************
  686. *** 272,278 ****
  687.    * this.
  688.    */
  689.   
  690. ! /* #define DEFPATH    ".:/usr/lib/awk:/usr/local/lib/awk" */
  691.   /* #define ENVSEP    ':' */
  692.   
  693.   /*
  694. --- 272,278 ----
  695.    * this.
  696.    */
  697.   
  698. ! /* #define DEFPATH    ".:/local/lib/awk:/gnu/lib/awk" */
  699.   /* #define ENVSEP    ':' */
  700.   
  701.   /*
  702. diff -rc --new-file /src/baseline/gawk-2.15.5/configure gawk-2.15.5/configure
  703. *** /src/baseline/gawk-2.15.5/configure    Tue May 18 12:34:04 1993
  704. --- gawk-2.15.5/configure    Sun Jun 12 21:53:47 1994
  705. ***************
  706. *** 1,36 ****
  707. ! #! /bin/sh
  708. ! #
  709. ! # configure -- produce a config.h from a known configuration
  710.   
  711. ! case "$#" in
  712. ! 1)    ;;
  713. ! *)    echo "Usage:  $0 system_type" >&2
  714. !     echo "Known systems:  `cd config; echo ;ls -C`" >&2
  715. !     exit 2
  716. !     ;;
  717. ! esac
  718. ! 
  719. ! if [ -f config/$1 ]; then
  720. !     sh ./mungeconf config/$1 config.in >config.h
  721. ! 
  722. !     # echo #echo lines to stdout
  723. !     sed -n '/^#echo /s///p' config/$1
  724. ! 
  725. !     case "$1" in
  726. !     bsd44)    ln -s Makefile.bsd44 Makefile ; exit 0 ;;
  727. !     esac
  728. ! 
  729. !     sed -n '/^MAKE_.*/s//s,^##&## ,,/p' config/$1 >sedscr
  730. !     if [ -s sedscr ]
  731. !     then
  732. !         sed -f sedscr Makefile.in >Makefile
  733. !     else
  734. !         cp Makefile.in Makefile
  735.       fi
  736. !     rm -f sedscr
  737.   else
  738. !     echo "\`$1' is not a known configuration."
  739. !     echo "Either construct one based on the examples in the config directory,"
  740. !     echo "or copy config.in to config.h and edit it."
  741. !     exit 1
  742.   fi
  743. --- 1,899 ----
  744. ! #!/bin/sh
  745. ! # Guess values for system-dependent variables and create Makefiles.
  746. ! # Generated automatically using autoconf version 1.11 
  747. ! # Copyright (C) 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
  748. ! 
  749. ! # This configure script is free software; you can redistribute it and/or
  750. ! # modify it under the terms of the GNU General Public License as published
  751. ! # by the Free Software Foundation; either version 2, or (at your option)
  752. ! # any later version.
  753. ! 
  754. ! # This script is distributed in the hope that it will be useful, but
  755. ! # WITHOUT ANY WARRANTY; without even the implied warranty of
  756. ! # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
  757. ! # Public License for more details.
  758. ! 
  759. ! # You should have received a copy of the GNU General Public License
  760. ! # along with this program; if not, write to the Free Software
  761. ! # Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  762. ! 
  763. ! # Save the original args to write them into config.status later.
  764. ! configure_args="$*"
  765. ! 
  766. ! # Only options that might do something get documented.
  767. ! ac_usage="Usage: configure [options] [host]
  768. ! Options: [defaults in brackets after descriptions]
  769. ! --build=BUILD        configure for building on BUILD [BUILD=HOST]
  770. ! --disable-FEATURE    do not include FEATURE (same as --enable-FEATURE=no)
  771. ! --enable-FEATURE[=ARG]    include FEATURE [ARG=yes]
  772. ! --exec-prefix=PREFIX    install host dependent files in PREFIX [/usr/local]
  773. ! --help            print this message
  774. ! --host=HOST        configure for HOST [guessed]
  775. ! --prefix=PREFIX        install host independent files in PREFIX [/usr/local]
  776. ! --quiet, --silent    do not print \`checking for...' messages
  777. ! --srcdir=DIR        find the sources in DIR [configure dir or ..]
  778. ! --target=TARGET        configure for TARGET [TARGET=HOST]
  779. ! --verbose        print results of checks
  780. ! --version        print the version of autoconf that created configure
  781. ! --with-PACKAGE[=ARG]    use PACKAGE [ARG=yes]
  782. ! --without-PACKAGE    do not use PACKAGE (same as --with-PACKAGE=no)
  783. ! --x-includes=DIR    X include files are in DIR
  784. ! --x-libraries=DIR    X library files are in DIR"
  785. ! 
  786. ! # Initialize some variables set by options.
  787. ! # The variables have the same names as the options, with
  788. ! # dashes changed to underlines.
  789. ! build=NONE
  790. ! exec_prefix=
  791. ! host=NONE
  792. ! no_create=
  793. ! nonopt=NONE
  794. ! norecursion=
  795. ! prefix=
  796. ! program_prefix=
  797. ! program_suffix=
  798. ! program_transform_name=
  799. ! silent=
  800. ! srcdir=
  801. ! target=NONE
  802. ! verbose=
  803. ! x_includes=
  804. ! x_libraries=
  805. ! 
  806. ! ac_prev=
  807. ! for ac_option
  808. ! do
  809. ! 
  810. !   # If the previous option needs an argument, assign it.
  811. !   if test -n "$ac_prev"; then
  812. !     eval "$ac_prev=\$ac_option"
  813. !     ac_prev=
  814. !     continue
  815. !   fi
  816. ! 
  817. !   # Accept (but ignore some of) the important Cygnus configure
  818. !   # options, so we can diagnose typos.
  819. ! 
  820. !   case "$ac_option" in
  821. !   -*=*) ac_optarg=`/bin/echo "$ac_option" | sed 's/[-_a-zA-Z0-9]*=//'` ;;
  822. !   *) ac_optarg= ;;
  823. !   esac
  824. ! 
  825. !   case "$ac_option" in
  826. ! 
  827. !   -build | --build | --buil | --bui | --bu | --b)
  828. !     ac_prev=build ;;
  829. !   -build=* | --build=* | --buil=* | --bui=* | --bu=* | --b=*)
  830. !     build="$ac_optarg" ;;
  831. ! 
  832. !   -disable-* | --disable-*)
  833. !     ac_feature=`/bin/echo $ac_option|sed -e 's/-*disable-//'`
  834. !     # Reject names that aren't valid shell variable names.
  835. !     if test -n "`/bin/echo $ac_feature| sed 's/[-a-zA-Z0-9_]//g'`"; then
  836. !       /bin/echo "configure: $ac_feature: invalid feature name" >&2; exit 1
  837. !     fi
  838. !     ac_feature=`/bin/echo $ac_feature| sed 's/-/_/g'`
  839. !     eval "enable_${ac_feature}=no" ;;
  840. ! 
  841. !   -enable-* | --enable-*)
  842. !     ac_feature=`/bin/echo $ac_option|sed -e 's/-*enable-//' -e 's/=.*//'`
  843. !     # Reject names that aren't valid shell variable names.
  844. !     if test -n "`/bin/echo $ac_feature| sed 's/[-_a-zA-Z0-9]//g'`"; then
  845. !       /bin/echo "configure: $ac_feature: invalid feature name" >&2; exit 1
  846. !     fi
  847. !     ac_feature=`/bin/echo $ac_feature| sed 's/-/_/g'`
  848. !     case "$ac_option" in
  849. !       *=*) ;;
  850. !       *) ac_optarg=yes ;;
  851. !     esac
  852. !     eval "enable_${ac_feature}='$ac_optarg'" ;;
  853. ! 
  854. !   # For backward compatibility, recognize -exec-prefix and --exec_prefix.
  855. !   -exec-prefix | --exec_prefix | --exec-prefix | --exec-prefi \
  856. !   | --exec-pref | --exec-pre | --exec-pr | --exec-p | --exec- \
  857. !   | --exec | --exe | --ex)
  858. !     ac_prev=exec_prefix ;;
  859. !   -exec-prefix=* | --exec_prefix=* | --exec-prefix=* | --exec-prefi=* \
  860. !   | --exec-pref=* | --exec-pre=* | --exec-pr=* | --exec-p=* | --exec-=* \
  861. !   | --exec=* | --exe=* | --ex=*)
  862. !     exec_prefix="$ac_optarg" ;;
  863. ! 
  864. !   -gas | --gas | --ga | --g)
  865. !     with_gas=yes ;; # Obsolete; use --with-gas.
  866. ! 
  867. !   -help | --help | --hel | --he)
  868. !     cat << EOF
  869. ! $ac_usage
  870. ! EOF
  871. !     exit 0 ;;
  872. ! 
  873. !   -host | --host | --hos | --ho)
  874. !     ac_prev=host ;;
  875. !   -host=* | --host=* | --hos=* | --ho=*)
  876. !     host="$ac_optarg" ;;
  877. ! 
  878. !   -nfp | --nfp | --nf)
  879. !     with_fp=no ;; # Obsolete; use --without-fp.
  880. ! 
  881. !   -no-create | --no-create | --no-creat | --no-crea | --no-cre \
  882. !   | --no-cr | --no-c)
  883. !     no_create=yes ;;
  884. ! 
  885. !   -norecursion | --norecursion | --norecursio | --norecursi \
  886. !   | --norecurs | --norecur | --norecu | --norec | --nore | --nor)
  887. !     norecursion=yes ;;
  888. ! 
  889. !   -prefix | --prefix | --prefi | --pref | --pre | --pr | --p)
  890. !     ac_prev=prefix ;;
  891. !   -prefix=* | --prefix=* | --prefi=* | --pref=* | --pre=* | --pr=* | --p=*)
  892. !     prefix="$ac_optarg" ;;
  893. ! 
  894. !   -program-prefix | --program-prefix | --program-prefi | --program-pref \
  895. !   | --program-pre | --program-pr | --program-p)
  896. !     ac_prev=program_prefix ;;
  897. !   -program-prefix=* | --program-prefix=* | --program-prefi=* \
  898. !   | --program-pref=* | --program-pre=* | --program-pr=* | --program-p=*)
  899. !     program_prefix="$ac_optarg" ;;
  900. ! 
  901. !   -program-suffix | --program-suffix | --program-suffi | --program-suff \
  902. !   | --program-suf | --program-su | --program-s)
  903. !     ac_prev=program_suffix ;;
  904. !   -program-suffix=* | --program-suffix=* | --program-suffi=* \
  905. !   | --program-suff=* | --program-suf=* | --program-su=* | --program-s=*)
  906. !     program_suffix="$ac_optarg" ;;
  907. ! 
  908. !   -program-transform-name | --program-transform-name \
  909. !   | --program-transform-nam | --program-transform-na \
  910. !   | --program-transform-n | --program-transform- \
  911. !   | --program-transform | --program-transfor \
  912. !   | --program-transfo | --program-transf \
  913. !   | --program-trans | --program-tran \
  914. !   | --progr-tra | --program-tr | --program-t)
  915. !     ac_prev=program_transform_name ;;
  916. !   -program-transform-name=* | --program-transform-name=* \
  917. !   | --program-transform-nam=* | --program-transform-na=* \
  918. !   | --program-transform-n=* | --program-transform-=* \
  919. !   | --program-transform=* | --program-transfor=* \
  920. !   | --program-transfo=* | --program-transf=* \
  921. !   | --program-trans=* | --program-tran=* \
  922. !   | --progr-tra=* | --program-tr=* | --program-t=*)
  923. !     program_transform_name="$ac_optarg" ;;
  924. ! 
  925. !   -q | -quiet | --quiet | --quie | --qui | --qu | --q \
  926. !   | -silent | --silent | --silen | --sile | --sil)
  927. !     silent=yes ;;
  928. ! 
  929. !   -srcdir | --srcdir | --srcdi | --srcd | --src | --sr)
  930. !     ac_prev=srcdir ;;
  931. !   -srcdir=* | --srcdir=* | --srcdi=* | --srcd=* | --src=* | --sr=*)
  932. !     srcdir="$ac_optarg" ;;
  933. ! 
  934. !   -target | --target | --targe | --targ | --tar | --ta | --t)
  935. !     ac_prev=target ;;
  936. !   -target=* | --target=* | --targe=* | --targ=* | --tar=* | --ta=* | --t=*)
  937. !     target="$ac_optarg" ;;
  938. ! 
  939. !   -v | -verbose | --verbose | --verbos | --verbo | --verb)
  940. !     verbose=yes ;;
  941. ! 
  942. !   -version | --version | --versio | --versi | --vers)
  943. !     /bin/echo "configure generated by autoconf version 1.11"
  944. !     exit 0 ;;
  945. ! 
  946. !   -with-* | --with-*)
  947. !     ac_package=`/bin/echo $ac_option|sed -e 's/-*with-//' -e 's/=.*//'`
  948. !     # Reject names that aren't valid shell variable names.
  949. !     if test -n "`/bin/echo $ac_package| sed 's/[-_a-zA-Z0-9]//g'`"; then
  950. !       /bin/echo "configure: $ac_package: invalid package name" >&2; exit 1
  951. !     fi
  952. !     ac_package=`/bin/echo $ac_package| sed 's/-/_/g'`
  953. !     case "$ac_option" in
  954. !       *=*) ;;
  955. !       *) ac_optarg=yes ;;
  956. !     esac
  957. !     eval "with_${ac_package}='$ac_optarg'" ;;
  958. ! 
  959. !   -without-* | --without-*)
  960. !     ac_package=`/bin/echo $ac_option|sed -e 's/-*without-//'`
  961. !     # Reject names that aren't valid shell variable names.
  962. !     if test -n "`/bin/echo $ac_package| sed 's/[-a-zA-Z0-9_]//g'`"; then
  963. !       /bin/echo "configure: $ac_package: invalid package name" >&2; exit 1
  964. !     fi
  965. !     ac_package=`/bin/echo $ac_package| sed 's/-/_/g'`
  966. !     eval "with_${ac_package}=no" ;;
  967. ! 
  968. !   --x) with_x=yes ;; # Obsolete; use --with-x.
  969. ! 
  970. !   -x-includes | --x-includes | --x-include | --x-includ | --x-inclu \
  971. !   | --x-incl | --x-inc | --x-in | --x-i)
  972. !     ac_prev=x_includes ;;
  973. !   -x-includes=* | --x-includes=* | --x-include=* | --x-includ=* | --x-inclu=* \
  974. !   | --x-incl=* | --x-inc=* | --x-in=* | --x-i=*)
  975. !     x_includes="$ac_optarg" ;;
  976. ! 
  977. !   -x-libraries | --x-libraries | --x-librarie | --x-librari \
  978. !   | --x-librar | --x-libra | --x-libr | --x-lib | --x-li | --x-l)
  979. !     ac_prev=x_libraries ;;
  980. !   -x-libraries=* | --x-libraries=* | --x-librarie=* | --x-librari=* \
  981. !   | --x-librar=* | --x-libra=* | --x-libr=* | --x-lib=* | --x-li=* | --x-l=*)
  982. !     x_libraries="$ac_optarg" ;;
  983. ! 
  984. !   -*) /bin/echo "configure: $ac_option: invalid option; use --help to show usage" >&2; exit 1
  985. !     ;;
  986. ! 
  987. !   *) 
  988. !     if test -n "`/bin/echo $ac_option| sed 's/[-a-z0-9.]//g'`"; then
  989. !       /bin/echo "configure: warning: $ac_option: invalid host type" >&2
  990. !     fi
  991. !     if test "x$nonopt" != xNONE; then
  992. !       /bin/echo "configure: can only configure for one host and one target at a time" >&2; exit 1
  993. !     fi
  994. !     nonopt="$ac_option"
  995. !     ;;
  996. ! 
  997. !   esac
  998. ! done
  999. ! 
  1000. ! if test -n "$ac_prev"; then
  1001. !   /bin/echo "configure: missing argument to --`/bin/echo $ac_prev | sed 's/_/-/g'`" >&2; exit 1
  1002. ! fi
  1003. ! 
  1004. ! trap 'rm -fr conftest* confdefs* core $ac_clean_files; exit 1' 1 2 15
  1005. ! trap 'rm -fr confdefs* $ac_clean_files' 0
  1006. ! 
  1007. ! # Save the original args if we used an alternate arg parser.
  1008. ! ac_configure_temp="${configure_args-$*}"
  1009. ! # Strip out --no-create and --norecursion so they don't pile up.
  1010. ! configure_args=
  1011. ! for ac_arg in $ac_configure_temp; do
  1012. !   case "$ac_arg" in
  1013. !   -no-create | --no-create | --no-creat | --no-crea | --no-cre \
  1014. !   | --no-cr | --no-c) ;;
  1015. !   -norecursion | --norecursion | --norecursio | --norecursi \
  1016. !   | --norecurs | --norecur | --norecu | --norec | --nore | --nor) ;;
  1017. !   *) configure_args="$configure_args $ac_arg" ;;
  1018. !   esac
  1019. ! done
  1020. ! 
  1021. ! # NLS nuisances.
  1022. ! # These must not be set unconditionally because not all systems understand
  1023. ! # e.g. LANG=C (notably SCO).
  1024. ! if test "${LC_ALL+set}" = 'set'; then LC_ALL=C; export LC_ALL; fi
  1025. ! if test "${LANG+set}"   = 'set'; then LANG=C;   export LANG;   fi
  1026. ! 
  1027. ! # confdefs.h avoids OS command line length limits that DEFS can exceed.
  1028. ! rm -rf conftest* confdefs.h
  1029. ! # AIX cpp loses on an empty file, so make sure it contains at least a newline.
  1030. ! /bin/echo > confdefs.h
  1031. ! 
  1032. ! # A filename unique to this package, relative to the directory that
  1033. ! # configure is in, which we can look for to find out if srcdir is correct.
  1034. ! ac_unique_file=awk.y
  1035. ! 
  1036. ! # Find the source files, if location was not specified.
  1037. ! if test -z "$srcdir"; then
  1038. !   ac_srcdir_defaulted=yes
  1039. !   # Try the directory containing this script, then `..'.
  1040. !   ac_prog=$0
  1041. !   ac_confdir=`/bin/echo $ac_prog|sed 's%/[^/][^/]*$%%'`
  1042. !   test "x$ac_confdir" = "x$ac_prog" && ac_confdir=.
  1043. !   srcdir=$ac_confdir
  1044. !   if test ! -r $srcdir/$ac_unique_file; then
  1045. !     srcdir=..
  1046. !   fi
  1047. ! fi
  1048. ! if test ! -r $srcdir/$ac_unique_file; then
  1049. !   if test x$ac_srcdir_defaulted = xyes; then
  1050. !     /bin/echo "configure: can not find sources in ${ac_confdir} or .." >&2; exit 1
  1051. !   else
  1052. !     /bin/echo "configure: can not find sources in ${srcdir}" >&2; exit 1
  1053. !   fi
  1054. ! fi
  1055. ! ac_ext=c
  1056. ! # CFLAGS is not in ac_cpp because -g, -O, etc. are not valid cpp options.
  1057. ! ac_cpp='${CPP}'
  1058. ! ac_compile='${CC-cc} $CFLAGS $LDFLAGS conftest.${ac_ext} -o conftest $LIBS >/dev/null 2>&1'
  1059. ! 
  1060. ! 
  1061. ! 
  1062. ! 
  1063. ! # We want these before the checks, so the checks can modify their values.
  1064. ! test -z "$CFLAGS" && CFLAGS= auto_cflags=1
  1065. ! test -z "$LDFLAGS" && LDFLAGS=
  1066. ! 
  1067. ! if test -z "$CC"; then
  1068. !   # Extract the first word of `gcc', so it can be a program name with args.
  1069. !   set ac_dummy gcc; ac_word=$2
  1070. !   test -n "$silent" || /bin/echo "checking for $ac_word"
  1071. !   IFS="${IFS=     }"; ac_save_ifs="$IFS"; IFS="${IFS}:"
  1072. !   for ac_dir in $PATH; do
  1073. !     test -z "$ac_dir" && ac_dir=.
  1074. !     if test -f $ac_dir/$ac_word; then
  1075. !       CC="gcc"
  1076. !       break
  1077. !     fi
  1078. !   done
  1079. !   IFS="$ac_save_ifs"
  1080. ! fi
  1081. ! test -z "$CC" && CC="cc"
  1082. ! test -n "$CC" && test -n "$verbose" && /bin/echo "    setting CC to $CC"
  1083. ! 
  1084. ! # Find out if we are using GNU C, under whatever name.
  1085. ! cat > conftest.c <<EOF
  1086. ! #ifdef __GNUC__
  1087. !   yes
  1088. ! #endif
  1089. ! EOF
  1090. ! ${CC-cc} -E conftest.c > conftest.out 2>&1
  1091. ! if egrep yes conftest.out >/dev/null 2>&1; then
  1092. !   GCC=1 # For later tests.
  1093. ! fi
  1094. ! rm -f conftest*
  1095. ! 
  1096. ! 
  1097. ! # If we're using gcc and the user hasn't specified CFLAGS, add -O to CFLAGS.
  1098. ! test -n "$GCC" && test -n "$auto_cflags" && CFLAGS="$CFLAGS -O2"
  1099. ! 
  1100. ! 
  1101. ! test -n "$silent" || /bin/echo "checking how to run the C preprocessor"
  1102. ! if test -z "$CPP"; then
  1103. !   # This must be in double quotes, not single quotes, because CPP may get
  1104. !   # substituted into the Makefile and ``${CC-cc}'' will simply confuse
  1105. !   # make.  It must be expanded now.
  1106. !   CPP="${CC-cc} -E"
  1107. !   cat > conftest.${ac_ext} <<EOF
  1108. ! #include "confdefs.h"
  1109. ! #include <stdio.h>
  1110. ! Syntax Error
  1111. ! EOF
  1112. ! # Some shells (Coherent) do redirections in the wrong order, so need
  1113. ! # the parens.
  1114. ! ac_err=`eval "($ac_cpp conftest.${ac_ext} >/dev/null) 2>&1"`
  1115. ! if test -z "$ac_err"; then
  1116. !   :
  1117. ! else
  1118. !   rm -rf conftest*
  1119. !   CPP="${CC-cc} -E -traditional-cpp"
  1120. !   cat > conftest.${ac_ext} <<EOF
  1121. ! #include "confdefs.h"
  1122. ! #include <stdio.h>
  1123. ! Syntax Error
  1124. ! EOF
  1125. ! # Some shells (Coherent) do redirections in the wrong order, so need
  1126. ! # the parens.
  1127. ! ac_err=`eval "($ac_cpp conftest.${ac_ext} >/dev/null) 2>&1"`
  1128. ! if test -z "$ac_err"; then
  1129. !   :
  1130. ! else
  1131. !   rm -rf conftest*
  1132. !   CPP=/lib/cpp
  1133. ! fi
  1134. ! rm -f conftest*
  1135. ! fi
  1136. ! rm -f conftest*
  1137. ! fi
  1138. ! test -n "$verbose" && /bin/echo "    setting CPP to $CPP"
  1139. ! 
  1140. ! if test -n "$GCC"; then
  1141. !   test -n "$silent" || /bin/echo "checking whether -traditional is needed"
  1142. !   ac_pattern="Autoconf.*'x'"
  1143. !   ac_prog='#include <sgtty.h>
  1144. ! Autoconf TIOCGETP'
  1145. !   cat > conftest.${ac_ext} <<EOF
  1146. ! #include "confdefs.h"
  1147. ! $ac_prog
  1148. ! EOF
  1149. ! eval "$ac_cpp conftest.${ac_ext} > conftest.out 2>&1"
  1150. ! if egrep "$ac_pattern" conftest.out >/dev/null 2>&1; then
  1151. !   rm -rf conftest*
  1152. !   ac_need_trad=1
  1153. ! 
  1154. ! fi
  1155. ! rm -f conftest*
  1156. ! 
  1157.   
  1158. !   if test -z "$ac_need_trad"; then
  1159. !     ac_prog='#include <termio.h>
  1160. ! Autoconf TCGETA'
  1161. !     cat > conftest.${ac_ext} <<EOF
  1162. ! #include "confdefs.h"
  1163. ! $ac_prog
  1164. ! EOF
  1165. ! eval "$ac_cpp conftest.${ac_ext} > conftest.out 2>&1"
  1166. ! if egrep "$ac_pattern" conftest.out >/dev/null 2>&1; then
  1167. !   rm -rf conftest*
  1168. !   ac_need_trad=1
  1169. ! 
  1170. ! fi
  1171. ! rm -f conftest*
  1172. ! 
  1173. !   fi
  1174. !   test -n "$ac_need_trad" && CC="$CC -traditional"
  1175. ! fi
  1176. ! 
  1177. ! # Make sure to not get the incompatible SysV /etc/install and
  1178. ! # /usr/sbin/install, which might be in PATH before a BSD-like install,
  1179. ! # or the SunOS /usr/etc/install directory, or the AIX /bin/install,
  1180. ! # or the AFS install, which mishandles nonexistent args, or
  1181. ! # /usr/ucb/install on SVR4, which tries to use the nonexistent group
  1182. ! # `staff', or /sbin/install on IRIX which has incompatible command-line
  1183. ! # syntax.  Sigh.
  1184. ! #
  1185. ! #     On most BSDish systems install is in /usr/bin, not /usr/ucb
  1186. ! #     anyway.
  1187. ! # This turns out not to be true, so the mere pathname isn't an indication
  1188. ! # of whether the program works.  What we really need is a set of tests for
  1189. ! # the install program to see if it actually works in all the required ways.
  1190. ! #
  1191. ! # Avoid using ./install, which might have been erroneously created
  1192. ! # by make from ./install.sh.
  1193. ! if test -z "${INSTALL}"; then
  1194. !   test -n "$silent" || /bin/echo "checking for a BSD compatible install"
  1195. !   IFS="${IFS=     }"; ac_save_ifs="$IFS"; IFS="${IFS}:"
  1196. !   for ac_dir in $PATH; do
  1197. !     case "$ac_dir" in
  1198. !     ''|.|/gnu/etc|/sbin|/usr/sbin|/usr/etc|/usr/afsws/bin|/usr/ucb) ;;
  1199. !     *)
  1200. !       # OSF1 and SCO ODT 3.0 have their own names for install.
  1201. !       for ac_prog in installbsd scoinst install; do
  1202. !         if test -f $ac_dir/$ac_prog; then
  1203. !       if test $ac_prog = install &&
  1204. !             grep dspmsg $ac_dir/$ac_prog >/dev/null 2>&1; then
  1205. !         # AIX install.  It has an incompatible calling convention.
  1206. !         # OSF/1 installbsd also uses dspmsg, but is usable.
  1207. !         :
  1208. !       else
  1209. !         INSTALL="$ac_dir/$ac_prog -c"
  1210. !         break 2
  1211. !       fi
  1212.       fi
  1213. !       done
  1214. !       ;;
  1215. !     esac
  1216. !   done
  1217. !   IFS="$ac_save_ifs"
  1218. ! fi
  1219. ! 
  1220. ! if test -z "$INSTALL"; then
  1221. !   # As a last resort, use the slow shell script.
  1222. !   for ac_dir in ${srcdir} ${srcdir}/.. ${srcdir}/../..; do
  1223. !     if test -f $ac_dir/install.sh; then
  1224. !       INSTALL="$ac_dir/install.sh -c"; break
  1225. !     fi
  1226. !   done
  1227. ! fi
  1228. ! if test -z "$INSTALL"; then
  1229. !   /bin/echo "configure: can not find install.sh in ${srcdir} or ${srcdir}/.. or ${srcdir}/../.." >&2; exit 1
  1230. ! fi
  1231. ! test -n "$verbose" && /bin/echo "    setting INSTALL to $INSTALL"
  1232. ! 
  1233. ! # Use test -z because SunOS4 sh mishandles ${INSTALL_PROGRAM-'${INSTALL}'}.
  1234. ! # It thinks the first close brace ends the variable substitution.
  1235. ! test -z "$INSTALL_PROGRAM" && INSTALL_PROGRAM='${INSTALL}'
  1236. ! test -n "$verbose" && /bin/echo "    setting INSTALL_PROGRAM to $INSTALL_PROGRAM"
  1237. ! 
  1238. ! test -z "$INSTALL_DATA" && INSTALL_DATA='${INSTALL} -m 644'
  1239. ! test -n "$verbose" && /bin/echo "    setting INSTALL_DATA to $INSTALL_DATA"
  1240. ! 
  1241. ! for ac_prog in 'bison -y' byacc
  1242. ! do
  1243. ! if test -z "$YACC"; then
  1244. !   # Extract the first word of `$ac_prog', so it can be a program name with args.
  1245. !   set ac_dummy $ac_prog; ac_word=$2
  1246. !   test -n "$silent" || /bin/echo "checking for $ac_word"
  1247. !   IFS="${IFS=     }"; ac_save_ifs="$IFS"; IFS="${IFS}:"
  1248. !   for ac_dir in $PATH; do
  1249. !     test -z "$ac_dir" && ac_dir=.
  1250. !     if test -f $ac_dir/$ac_word; then
  1251. !       YACC="$ac_prog"
  1252. !       break
  1253. !     fi
  1254. !   done
  1255. !   IFS="$ac_save_ifs"
  1256. ! fi
  1257. ! 
  1258. ! test -n "$YACC" && test -n "$verbose" && /bin/echo "    setting YACC to $YACC"
  1259. ! 
  1260. ! test -n "$YACC" && break
  1261. ! done
  1262. ! test -n "$YACC" || YACC="yacc"
  1263. ! 
  1264. ! test -n "$silent" || /bin/echo "checking for return type of signal handlers"
  1265. ! cat > conftest.${ac_ext} <<EOF
  1266. ! #include "confdefs.h"
  1267. ! #include <sys/types.h>
  1268. ! #include <signal.h>
  1269. ! #ifdef signal
  1270. ! #undef signal
  1271. ! #endif
  1272. ! extern void (*signal ()) ();
  1273. ! int main() { return 0; }
  1274. ! int t() { int i;; return 0; }
  1275. ! EOF
  1276. ! if eval $ac_compile; then
  1277. !   rm -rf conftest*
  1278. !   
  1279. ! {
  1280. ! test -n "$verbose" && \
  1281. ! /bin/echo "    defining" RETSIGTYPE to be "void"
  1282. ! /bin/echo "#define" RETSIGTYPE "void" >> confdefs.h
  1283. ! DEFS="$DEFS -DRETSIGTYPE=void"
  1284. ! ac_sed_defs="${ac_sed_defs}\${ac_dA}RETSIGTYPE\${ac_dB}RETSIGTYPE\${ac_dC}void\${ac_dD}
  1285. ! \${ac_uA}RETSIGTYPE\${ac_uB}RETSIGTYPE\${ac_uC}void\${ac_uD}
  1286. ! \${ac_eA}RETSIGTYPE\${ac_eB}RETSIGTYPE\${ac_eC}void\${ac_eD}
  1287. ! "
  1288. ! }
  1289. ! 
  1290. ! 
  1291. ! else
  1292. !   rm -rf conftest*
  1293. !   
  1294. ! {
  1295. ! test -n "$verbose" && \
  1296. ! /bin/echo "    defining" RETSIGTYPE to be "int"
  1297. ! /bin/echo "#define" RETSIGTYPE "int" >> confdefs.h
  1298. ! DEFS="$DEFS -DRETSIGTYPE=int"
  1299. ! ac_sed_defs="${ac_sed_defs}\${ac_dA}RETSIGTYPE\${ac_dB}RETSIGTYPE\${ac_dC}int\${ac_dD}
  1300. ! \${ac_uA}RETSIGTYPE\${ac_uB}RETSIGTYPE\${ac_uC}int\${ac_uD}
  1301. ! \${ac_eA}RETSIGTYPE\${ac_eB}RETSIGTYPE\${ac_eC}int\${ac_eD}
  1302. ! "
  1303. ! }
  1304. ! 
  1305. ! fi
  1306. ! rm -f conftest*
  1307. ! 
  1308. ! 
  1309. ! test -n "$silent" || /bin/echo "checking for ANSI C header files"
  1310. ! cat > conftest.${ac_ext} <<EOF
  1311. ! #include "confdefs.h"
  1312. ! #include <stdlib.h>
  1313. ! #include <stdarg.h>
  1314. ! #include <string.h>
  1315. ! #include <float.h>
  1316. ! EOF
  1317. ! # Some shells (Coherent) do redirections in the wrong order, so need
  1318. ! # the parens.
  1319. ! ac_err=`eval "($ac_cpp conftest.${ac_ext} >/dev/null) 2>&1"`
  1320. ! if test -z "$ac_err"; then
  1321. !   rm -rf conftest*
  1322. !   # SunOS 4.x string.h does not declare mem*, contrary to ANSI.
  1323. ! /bin/echo '#include "confdefs.h"
  1324. ! #include <string.h>' > conftest.${ac_ext}
  1325. ! eval "$ac_cpp conftest.${ac_ext} > conftest.out 2>&1"
  1326. ! if egrep "memchr" conftest.out >/dev/null 2>&1; then
  1327. !   rm -rf conftest*
  1328. !   # SGI's /bin/cc from Irix-4.0.5 gets non-ANSI ctype macros unless using -ansi.
  1329. ! cat > conftest.${ac_ext} <<EOF
  1330. ! #include "confdefs.h"
  1331. ! #include <ctype.h>
  1332. ! #define ISLOWER(c) ('a' <= (c) && (c) <= 'z')
  1333. ! #define TOUPPER(c) (ISLOWER(c) ? 'A' + ((c) - 'a') : (c))
  1334. ! #define XOR(e,f) (((e) && !(f)) || (!(e) && (f)))
  1335. ! int main () { int i; for (i = 0; i < 256; i++)
  1336. ! if (XOR (islower (i), ISLOWER (i)) || toupper (i) != TOUPPER (i)) exit(2);
  1337. ! exit (0); }
  1338. ! 
  1339. ! EOF
  1340. ! eval $ac_compile
  1341. ! if test -s conftest && (./conftest; exit) 2>/dev/null; then
  1342. !   # ISC 2.0.2 stdlib.h does not declare free, contrary to ANSI.
  1343. ! /bin/echo '#include "confdefs.h"
  1344. ! #include <stdlib.h>' > conftest.${ac_ext}
  1345. ! eval "$ac_cpp conftest.${ac_ext} > conftest.out 2>&1"
  1346. ! if egrep "free" conftest.out >/dev/null 2>&1; then
  1347. !   rm -rf conftest*
  1348. !   
  1349. ! {
  1350. ! test -n "$verbose" && \
  1351. ! /bin/echo "    defining STDC_HEADERS"
  1352. ! /bin/echo "#define" STDC_HEADERS "1" >> confdefs.h
  1353. ! DEFS="$DEFS -DSTDC_HEADERS=1"
  1354. ! ac_sed_defs="${ac_sed_defs}\${ac_dA}STDC_HEADERS\${ac_dB}STDC_HEADERS\${ac_dC}1\${ac_dD}
  1355. ! \${ac_uA}STDC_HEADERS\${ac_uB}STDC_HEADERS\${ac_uC}1\${ac_uD}
  1356. ! \${ac_eA}STDC_HEADERS\${ac_eB}STDC_HEADERS\${ac_eC}1\${ac_eD}
  1357. ! "
  1358. ! }
  1359. ! 
  1360. ! 
  1361. ! fi
  1362. ! rm -f conftest*
  1363. ! 
  1364. ! 
  1365. ! fi
  1366. ! rm -fr conftest*
  1367. ! 
  1368. ! fi
  1369. ! rm -f conftest*
  1370. ! 
  1371. ! 
  1372. ! fi
  1373. ! rm -f conftest*
  1374. ! 
  1375. ! 
  1376. ! test -n "$silent" || /bin/echo "checking for _setjmp declaration in <setjmp.h>"
  1377. ! cat > conftest.${ac_ext} <<EOF
  1378. ! #include "confdefs.h"
  1379. ! #include <setjmp.h>
  1380. ! int main() { return 0; }
  1381. ! int t() { jmp_buf buf; _setjmp (buf); return 0; }
  1382. ! EOF
  1383. ! if eval $ac_compile; then
  1384. !   rm -rf conftest*
  1385. !   
  1386. ! {
  1387. ! test -n "$verbose" && \
  1388. ! /bin/echo "    defining HAVE_UNDERSCORE_SETJMP"
  1389. ! /bin/echo "#define" HAVE_UNDERSCORE_SETJMP "1" >> confdefs.h
  1390. ! DEFS="$DEFS -DHAVE_UNDERSCORE_SETJMP=1"
  1391. ! ac_sed_defs="${ac_sed_defs}\${ac_dA}HAVE_UNDERSCORE_SETJMP\${ac_dB}HAVE_UNDERSCORE_SETJMP\${ac_dC}1\${ac_dD}
  1392. ! \${ac_uA}HAVE_UNDERSCORE_SETJMP\${ac_uB}HAVE_UNDERSCORE_SETJMP\${ac_uC}1\${ac_uD}
  1393. ! \${ac_eA}HAVE_UNDERSCORE_SETJMP\${ac_eB}HAVE_UNDERSCORE_SETJMP\${ac_eC}1\${ac_eD}
  1394. ! "
  1395. ! }
  1396. ! 
  1397. ! 
  1398. ! fi
  1399. ! rm -f conftest*
  1400. ! 
  1401. ! 
  1402. ! 
  1403. ! # The preferred way to propogate these variables is regular @ substitutions.
  1404. ! if test -n "$prefix"; then
  1405. !   ac_prsub="s%^prefix\\([     ]*\\)=\\([     ]*\\).*$%prefix\\1=\\2$prefix%"
  1406. ! else
  1407. !   prefix=/usr/local
  1408. ! fi
  1409. ! if test -n "$exec_prefix"; then
  1410. !   ac_prsub="$ac_prsub
  1411. ! s%^exec_prefix\\([     ]*\\)=\\([     ]*\\).*$%exec_prefix\\1=\\2$exec_prefix%"
  1412.   else
  1413. !   exec_prefix='${prefix}' # Let make expand it.
  1414. ! fi
  1415. ! 
  1416. ! # Any assignment to VPATH causes Sun make to only execute
  1417. ! # the first set of double-colon rules, so remove it if not needed.
  1418. ! # If there is a colon in the path, we need to keep it.
  1419. ! if test "x$srcdir" = x.; then
  1420. !   ac_vpsub='/^[     ]*VPATH[     ]*=[^:]*$/d'
  1421.   fi
  1422. + 
  1423. + # Quote sed substitution magic chars in DEFS.
  1424. + cat >conftest.def <<EOF
  1425. + $DEFS
  1426. + EOF
  1427. + ac_escape_ampersand_and_backslash='s%[&\\]%\\&%g'
  1428. + DEFS=`sed "$ac_escape_ampersand_and_backslash" <conftest.def`
  1429. + rm -f conftest.def
  1430. + # Substitute for predefined variables.
  1431. + 
  1432. + trap 'rm -f config.status; exit 1' 1 2 15
  1433. + /bin/echo creating config.status
  1434. + # Some systems, like AmigaDOS, won't allow you to remove a script that is
  1435. + # being executed, so just move it out of the way instead.
  1436. + if test -f config.status; then mv config.status config.status.old; else true; fi
  1437. + cat > config.status <<EOF
  1438. + #!/bin/sh
  1439. + # Generated automatically by configure.
  1440. + # Run this file to recreate the current configuration.
  1441. + # This directory was configured as follows,
  1442. + # on host `(hostname || uname -n) 2>/dev/null | sed 1q`:
  1443. + #
  1444. + # $0 $configure_args
  1445. + 
  1446. + ac_cs_usage="Usage: config.status [--recheck] [--version] [--help]"
  1447. + for ac_option
  1448. + do
  1449. +   case "\$ac_option" in
  1450. +   -recheck | --recheck | --rechec | --reche | --rech | --rec | --re | --r)
  1451. +     /bin/echo running \${CONFIG_SHELL-/bin/sh} $0 $configure_args --no-create
  1452. +     exec \${CONFIG_SHELL-/bin/sh} $0 $configure_args --no-create ;;
  1453. +   -version | --version | --versio | --versi | --vers | --ver | --ve | --v)
  1454. +     /bin/echo "config.status generated by autoconf version 1.11"
  1455. +     exit 0 ;;
  1456. +   -help | --help | --hel | --he | --h)
  1457. +     /bin/echo "\$ac_cs_usage"; exit 0 ;;
  1458. +   *) /bin/echo "\$ac_cs_usage"; exit 1 ;;
  1459. +   esac
  1460. + done
  1461. + 
  1462. + trap 'rm -fr Makefile config.h conftest*; exit 1' 1 2 15
  1463. + CC='$CC'
  1464. + CFLAGS='$CFLAGS'
  1465. + LDFLAGS='$LDFLAGS'
  1466. + CPP='$CPP'
  1467. + INSTALL='$INSTALL'
  1468. + INSTALL_PROGRAM='$INSTALL_PROGRAM'
  1469. + INSTALL_DATA='$INSTALL_DATA'
  1470. + YACC='$YACC'
  1471. + LIBS='$LIBS'
  1472. + srcdir='$srcdir'
  1473. + top_srcdir='$top_srcdir'
  1474. + prefix='$prefix'
  1475. + exec_prefix='$exec_prefix'
  1476. + ac_prsub='$ac_prsub'
  1477. + ac_vpsub='$ac_vpsub'
  1478. + extrasub='$extrasub'
  1479. + EOF
  1480. + cat >> config.status <<\EOF
  1481. + 
  1482. + ac_given_srcdir=$srcdir
  1483. + 
  1484. + CONFIG_FILES=${CONFIG_FILES-"Makefile"}
  1485. + for ac_file in .. ${CONFIG_FILES}; do if test "x$ac_file" != x..; then
  1486. +   # Remove last slash and all that follows it.  Not all systems have dirname.
  1487. +   ac_dir=`/bin/echo $ac_file|sed 's%/[^/][^/]*$%%'`
  1488. +   if test "$ac_dir" != "$ac_file" && test "$ac_dir" != .; then
  1489. +     # The file is in a subdirectory.
  1490. +     test ! -d "$ac_dir" && mkdir "$ac_dir"
  1491. +     ac_dir_suffix="/$ac_dir"
  1492. +   else
  1493. +     ac_dir_suffix=
  1494. +   fi
  1495. + 
  1496. +   # A "../" for each directory in $ac_dir_suffix.
  1497. +   ac_dots=`/bin/echo $ac_dir_suffix|sed 's%/[^/]*%../%g'`
  1498. +   case "$ac_given_srcdir" in
  1499. +   .)  srcdir=.
  1500. +       if test -z "$ac_dir_suffix"; then top_srcdir=.
  1501. +       else top_srcdir=`/bin/echo $ac_dots|sed 's%/$%%'`; fi ;;
  1502. +   /*) srcdir="$ac_given_srcdir$ac_dir_suffix"; top_srcdir="$ac_given_srcdir" ;;
  1503. +   *) # Relative path.
  1504. +     srcdir="$ac_dots$ac_given_srcdir$ac_dir_suffix"
  1505. +     top_srcdir="$ac_dots$ac_given_srcdir" ;;
  1506. +   esac
  1507. + 
  1508. +   /bin/echo creating "$ac_file"
  1509. +   rm -f "$ac_file"
  1510. +   comment_str="Generated automatically from `/bin/echo $ac_file|sed 's|.*/||'`.in by configure."
  1511. +   case "$ac_file" in
  1512. +     *.c | *.h | *.C | *.cc | *.m )  /bin/echo "/* $comment_str */" > "$ac_file" ;;
  1513. +     * )          /bin/echo "# $comment_str"     > "$ac_file" ;;
  1514. +   esac
  1515. +   sed -e "
  1516. + $ac_prsub
  1517. + $ac_vpsub
  1518. + $extrasub
  1519. + s%@CC@%$CC%g
  1520. + s%@CFLAGS@%$CFLAGS%g
  1521. + s%@LDFLAGS@%$LDFLAGS%g
  1522. + s%@CPP@%$CPP%g
  1523. + s%@INSTALL@%$INSTALL%g
  1524. + s%@INSTALL_PROGRAM@%$INSTALL_PROGRAM%g
  1525. + s%@INSTALL_DATA@%$INSTALL_DATA%g
  1526. + s%@YACC@%$YACC%g
  1527. + s%@LIBS@%$LIBS%g
  1528. + s%@srcdir@%$srcdir%g
  1529. + s%@top_srcdir@%$top_srcdir%g
  1530. + s%@prefix@%$prefix%g
  1531. + s%@exec_prefix@%$exec_prefix%g
  1532. + s%@DEFS@%-DHAVE_CONFIG_H%" $ac_given_srcdir/${ac_file}.in >> $ac_file
  1533. + fi; done
  1534. + 
  1535. + # These sed commands are put into ac_sed_defs when defining a macro.
  1536. + # They are broken into pieces to make the sed script easier to manage.
  1537. + # They are passed to sed as "A NAME B NAME C VALUE D", where NAME
  1538. + # is the cpp macro being defined and VALUE is the value it is being given.
  1539. + # Each defining turns into a single global substitution command.
  1540. + # Hopefully no one uses "!" as a variable value.
  1541. + # Other candidates for the sed separators, like , and @, do get used.
  1542. + #
  1543. + # ac_d sets the value in "#define NAME VALUE" lines.
  1544. + ac_dA='s!^\([     ]*\)#\([     ]*define[     ][     ]*\)'
  1545. + ac_dB='\([     ][     ]*\)[^     ]*!\1#\2'
  1546. + ac_dC='\3'
  1547. + ac_dD='!g'
  1548. + # ac_u turns "#undef NAME" with trailing blanks into "#define NAME VALUE".
  1549. + ac_uA='s!^\([     ]*\)#\([     ]*\)undef\([     ][     ]*\)'
  1550. + ac_uB='\([     ]\)!\1#\2define\3'
  1551. + ac_uC=' '
  1552. + ac_uD='\4!g'
  1553. + # ac_e turns "#undef NAME" without trailing blanks into "#define NAME VALUE".
  1554. + ac_eA='s!^\([     ]*\)#\([     ]*\)undef\([     ][     ]*\)'
  1555. + ac_eB='$!\1#\2define\3'
  1556. + ac_eC=' '
  1557. + ac_eD='!g'
  1558. + rm -f conftest.sed
  1559. + EOF
  1560. + # Turn off quoting long enough to insert the sed commands.
  1561. + rm -f conftest.sh
  1562. + cat > conftest.sh <<EOF
  1563. + $ac_sed_defs
  1564. + EOF
  1565. + 
  1566. + # Break up $ac_sed_defs (now in conftest.sh) because some shells have a limit
  1567. + # on the size of here documents.
  1568. + 
  1569. + # Maximum number of lines to put in a single here document.
  1570. + ac_max_sh_lines=9
  1571. + 
  1572. + while :
  1573. + do
  1574. +   # wc gives bogus results for an empty file on some AIX systems.
  1575. +   ac_lines=`grep -c . conftest.sh`
  1576. +   if test -z "$ac_lines" || test "$ac_lines" -eq 0; then break; fi
  1577. +   rm -f conftest.s1 conftest.s2
  1578. +   sed ${ac_max_sh_lines}q conftest.sh > conftest.s1 # Like head -9.
  1579. +   sed 1,${ac_max_sh_lines}d conftest.sh > conftest.s2 # Like tail +10.
  1580. +   # Write a limited-size here document to append to conftest.sed.
  1581. +   /bin/echo 'cat >> conftest.sed <<CONFEOF' >> config.status
  1582. +   cat conftest.s1 >> config.status
  1583. +   /bin/echo 'CONFEOF' >> config.status
  1584. +   rm -f conftest.s1 conftest.sh
  1585. +   mv conftest.s2 conftest.sh
  1586. + done
  1587. + rm -f conftest.sh
  1588. + 
  1589. + # Now back to your regularly scheduled config.status.
  1590. + cat >> config.status <<\EOF
  1591. + # This sed command replaces #undef's with comments.  This is necessary, for
  1592. + # example, in the case of _POSIX_SOURCE, which is predefined and required
  1593. + # on some systems where configure will not decide to define it in
  1594. + # config.h.
  1595. + cat >> conftest.sed <<\CONFEOF
  1596. + s,^[     ]*#[     ]*undef[     ][     ]*[a-zA-Z_][a-zA-Z_0-9]*,/* & */,
  1597. + CONFEOF
  1598. + rm -f conftest.h
  1599. + # Break up the sed commands because old seds have small limits.
  1600. + ac_max_sed_lines=20
  1601. + 
  1602. + CONFIG_HEADERS=${CONFIG_HEADERS-"config.h"}
  1603. + for ac_file in .. ${CONFIG_HEADERS}; do if test "x$ac_file" != x..; then
  1604. +   /bin/echo creating $ac_file
  1605. + 
  1606. +   cp $ac_given_srcdir/$ac_file.in conftest.h1
  1607. +   cp conftest.sed conftest.stm
  1608. +   while :
  1609. +   do
  1610. +     ac_lines=`grep -c . conftest.stm`
  1611. +     if test -z "$ac_lines" || test "$ac_lines" -eq 0; then break; fi
  1612. +     rm -f conftest.s1 conftest.s2 conftest.h2
  1613. +     sed ${ac_max_sed_lines}q conftest.stm > conftest.s1 # Like head -20.
  1614. +     sed 1,${ac_max_sed_lines}d conftest.stm > conftest.s2 # Like tail +21.
  1615. +     sed -f conftest.s1 < conftest.h1 > conftest.h2
  1616. +     rm -f conftest.s1 conftest.h1 conftest.stm
  1617. +     mv conftest.h2 conftest.h1
  1618. +     mv conftest.s2 conftest.stm
  1619. +   done
  1620. +   rm -f conftest.stm conftest.h
  1621. +   /bin/echo "/* $ac_file.  Generated automatically by configure.  */" > conftest.h
  1622. +   cat conftest.h1 >> conftest.h
  1623. +   rm -f conftest.h1
  1624. +   if cmp -s $ac_file conftest.h 2>/dev/null; then
  1625. +     # The file exists and we would not be changing it.
  1626. +     /bin/echo "$ac_file is unchanged"
  1627. +     rm -f conftest.h
  1628. +   else
  1629. +     rm -f $ac_file
  1630. +     mv conftest.h $ac_file
  1631. +   fi
  1632. + fi; done
  1633. + rm -f conftest.sed
  1634. + 
  1635. + 
  1636. + 
  1637. + exit 0
  1638. + EOF
  1639. + chmod +x config.status
  1640. + # Some shells look in PATH for config.status without the "./".
  1641. + test -n "$no_create" || ${CONFIG_SHELL-/bin/sh} ./config.status
  1642. + 
  1643. diff -rc --new-file /src/baseline/gawk-2.15.5/configure.in gawk-2.15.5/configure.in
  1644. *** /src/baseline/gawk-2.15.5/configure.in    Thu Jan  1 00:00:00 1970
  1645. --- gawk-2.15.5/configure.in    Sun Jun 12 21:43:35 1994
  1646. ***************
  1647. *** 0 ****
  1648. --- 1,28 ----
  1649. + dnl Process this file with autoconf to produce a configure script.
  1650. + AC_INIT(awk.y)
  1651. + AC_CONFIG_HEADER(config.h)
  1652. + 
  1653. + # We want these before the checks, so the checks can modify their values.
  1654. + test -z "$CFLAGS" && CFLAGS= auto_cflags=1
  1655. + test -z "$LDFLAGS" && LDFLAGS=
  1656. + 
  1657. + AC_PROG_CC
  1658. + 
  1659. + # If we're using gcc and the user hasn't specified CFLAGS, add -O to CFLAGS.
  1660. + test -n "$GCC" && test -n "$auto_cflags" && CFLAGS="$CFLAGS -O2"
  1661. + 
  1662. + AC_SUBST(CFLAGS)dnl
  1663. + AC_SUBST(LDFLAGS)dnl
  1664. + 
  1665. + AC_PROG_CPP
  1666. + AC_GCC_TRADITIONAL
  1667. + AC_PROG_INSTALL
  1668. + AC_PROG_YACC
  1669. + AC_RETSIGTYPE
  1670. + AC_STDC_HEADERS
  1671. + 
  1672. + AC_COMPILE_CHECK(_setjmp declaration in <setjmp.h>,
  1673. +          [#include <setjmp.h>], [jmp_buf buf; _setjmp (buf)],
  1674. +          AC_DEFINE(HAVE_UNDERSCORE_SETJMP))
  1675. + 
  1676. + AC_OUTPUT(Makefile)
  1677. diff -rc --new-file /src/baseline/gawk-2.15.5/dfa.h gawk-2.15.5/dfa.h
  1678. *** /src/baseline/gawk-2.15.5/dfa.h    Tue Jan  4 17:18:17 1994
  1679. --- gawk-2.15.5/dfa.h    Sun Jun 12 21:43:38 1994
  1680. ***************
  1681. *** 23,35 ****
  1682. --- 23,39 ----
  1683.      name space. */
  1684.   
  1685.   /* Number of bits in an unsigned char. */
  1686. + #ifndef CHARBITS
  1687.   #define CHARBITS 8
  1688. + #endif
  1689.   
  1690.   /* First integer value that is greater than any character code. */
  1691.   #define NOTCHAR (1 << CHARBITS)
  1692.   
  1693.   /* INTBITS need not be exact, just a lower bound. */
  1694. + #ifndef INTBITS
  1695.   #define INTBITS (CHARBITS * sizeof (int))
  1696. + #endif
  1697.   
  1698.   /* Number of ints required to hold a bit for every character. */
  1699.   #define CHARCLASS_INTS ((NOTCHAR + INTBITS - 1) / INTBITS)
  1700. diff -rc --new-file /src/baseline/gawk-2.15.5/gawk.1 gawk-2.15.5/gawk.1
  1701. *** /src/baseline/gawk-2.15.5/gawk.1    Mon Apr 18 18:04:03 1994
  1702. --- gawk-2.15.5/gawk.1    Sun Jun 12 21:43:43 1994
  1703. ***************
  1704. *** 329,335 ****
  1705.   the 
  1706.   .B \-f
  1707.   option.  If this variable does not exist, the default path is
  1708. ! \fB".:/usr/lib/awk:/usr/local/lib/awk"\fR.
  1709.   If a file name given to the
  1710.   .B \-f
  1711.   option contains a ``/'' character, no path search is performed.
  1712. --- 329,335 ----
  1713.   the 
  1714.   .B \-f
  1715.   option.  If this variable does not exist, the default path is
  1716. ! \fB".:/local/lib/awk:/gnu/lib/awk"\fR.
  1717.   If a file name given to the
  1718.   .B \-f
  1719.   option contains a ``/'' character, no path search is performed.
  1720. diff -rc --new-file /src/baseline/gawk-2.15.5/gawk.info gawk-2.15.5/gawk.info
  1721. *** /src/baseline/gawk-2.15.5/gawk.info    Thu Jan  1 00:00:00 1970
  1722. --- gawk-2.15.5/gawk.info    Sun Jun 12 22:28:57 1994
  1723. ***************
  1724. *** 0 ****
  1725. --- 1,204 ----
  1726. + This is Info file gawk.info, produced by Makeinfo-1.55 from the input
  1727. + file /gnu/src/amiga/gawk-2.15.5/gawk.texi.
  1728. + 
  1729. +    This file documents `awk', a program that you can use to select
  1730. + particular records in a file and perform operations upon them.
  1731. + 
  1732. +    This is Edition 0.15 of `The GAWK Manual',
  1733. + for the 2.15 version of the GNU implementation
  1734. + of AWK.
  1735. + 
  1736. +    Copyright (C) 1989, 1991, 1992, 1993 Free Software Foundation, Inc.
  1737. + 
  1738. +    Permission is granted to make and distribute verbatim copies of this
  1739. + manual provided the copyright notice and this permission notice are
  1740. + preserved on all copies.
  1741. + 
  1742. +    Permission is granted to copy and distribute modified versions of
  1743. + this manual under the conditions for verbatim copying, provided that
  1744. + the entire resulting derived work is distributed under the terms of a
  1745. + permission notice identical to this one.
  1746. + 
  1747. +    Permission is granted to copy and distribute translations of this
  1748. + manual into another language, under the above conditions for modified
  1749. + versions, except that this permission notice may be stated in a
  1750. + translation approved by the Foundation.
  1751. + 
  1752. + 
  1753. + Indirect:
  1754. + gawk.info-1: 1079
  1755. + gawk.info-2: 48275
  1756. + gawk.info-3: 98104
  1757. + gawk.info-4: 146775
  1758. + gawk.info-5: 195898
  1759. + gawk.info-6: 243621
  1760. + gawk.info-7: 291484
  1761. + gawk.info-8: 340862
  1762. + gawk.info-9: 380695
  1763. + 
  1764. + Tag Table:
  1765. + (Indirect)
  1766. + Node: Top1079
  1767. + Node: Preface3990
  1768. + Node: History5583
  1769. + Node: Copying7926
  1770. + Node: This Manual27078
  1771. + Node: Sample Data Files28922
  1772. + Node: Getting Started31714
  1773. + Node: Very Simple33425
  1774. + Node: Two Rules35393
  1775. + Node: More Complex37477
  1776. + Node: Running gawk40463
  1777. + Node: One-shot41412
  1778. + Node: Read Terminal42548
  1779. + Node: Long43607
  1780. + Node: Executable Scripts44949
  1781. + Node: Comments47172
  1782. + Node: Statements/Lines48275
  1783. + Node: When51166
  1784. + Node: Reading Files53081
  1785. + Node: Records54808
  1786. + Node: Fields58042
  1787. + Node: Non-Constant Fields60655
  1788. + Node: Changing Fields62479
  1789. + Node: Field Separators65852
  1790. + Node: Constant Size75488
  1791. + Node: Multiple Line79036
  1792. + Node: Getline81432
  1793. + Node: Close Input91176
  1794. + Node: Printing92632
  1795. + Node: Print93631
  1796. + Node: Print Examples95765
  1797. + Node: Output Separators98104
  1798. + Node: OFMT99842
  1799. + Node: Printf100986
  1800. + Node: Basic Printf101890
  1801. + Node: Control Letters103315
  1802. + Node: Format Modifiers105129
  1803. + Node: Printf Examples107634
  1804. + Node: Redirection110316
  1805. + Node: File/Pipe Redirection111052
  1806. + Node: Close Output114525
  1807. + Node: Special Files117029
  1808. + Node: One-liners121963
  1809. + Node: Patterns124685
  1810. + Node: Kinds of Patterns125663
  1811. + Node: Regexp126668
  1812. + Node: Regexp Usage127612
  1813. + Node: Regexp Operators129641
  1814. + Node: Case-sensitivity135119
  1815. + Node: Comparison Patterns137429
  1816. + Node: Boolean Patterns139590
  1817. + Node: Expression Patterns141100
  1818. + Node: Ranges142540
  1819. + Node: BEGIN/END143950
  1820. + Node: Empty146504
  1821. + Node: Actions146775
  1822. + Node: Expressions149155
  1823. + Node: Constants151176
  1824. + Node: Variables156741
  1825. + Node: Assignment Options158350
  1826. + Node: Arithmetic Ops160034
  1827. + Node: Concatenation161700
  1828. + Node: Comparison Ops163048
  1829. + Node: Boolean Ops167473
  1830. + Node: Assignment Ops169936
  1831. + Node: Increment Ops174010
  1832. + Node: Conversion176506
  1833. + Node: Values179581
  1834. + Node: Conditional Exp182164
  1835. + Node: Function Calls183492
  1836. + Node: Precedence186256
  1837. + Node: Statements189639
  1838. + Node: If Statement191322
  1839. + Node: While Statement192850
  1840. + Node: Do Statement194813
  1841. + Node: For Statement195898
  1842. + Node: Break Statement199090
  1843. + Node: Continue Statement200699
  1844. + Node: Next Statement203322
  1845. + Node: Next File Statement205266
  1846. + Node: Exit Statement208312
  1847. + Node: Arrays209927
  1848. + Node: Array Intro211129
  1849. + Node: Reference to Elements214632
  1850. + Node: Assigning Elements216575
  1851. + Node: Array Example217077
  1852. + Node: Scanning an Array218808
  1853. + Node: Delete221108
  1854. + Node: Numeric Array Subscripts222088
  1855. + Node: Multi-dimensional223968
  1856. + Node: Multi-scanning227196
  1857. + Node: Built-in228818
  1858. + Node: Calling Built-in229775
  1859. + Node: Numeric Functions231039
  1860. + Node: String Functions234386
  1861. + Node: I/O Functions243621
  1862. + Node: Time Functions246245
  1863. + Node: User-defined254329
  1864. + Node: Definition Syntax255047
  1865. + Node: Function Example259039
  1866. + Node: Function Caveats260114
  1867. + Node: Return Statement263157
  1868. + Node: Built-in Variables265540
  1869. + Node: User-modified266576
  1870. + Node: Auto-set270853
  1871. + Node: Command Line276592
  1872. + Node: Options277517
  1873. + Node: Other Arguments284591
  1874. + Node: AWKPATH Variable286957
  1875. + Node: Obsolete289095
  1876. + Node: Undocumented290355
  1877. + Node: Language History290543
  1878. + Node: V7/S5R3.1291484
  1879. + Node: S5R4294188
  1880. + Node: POSIX295725
  1881. + Node: POSIX/GNU296443
  1882. + Node: Installation298074
  1883. + Node: Gawk Distribution298940
  1884. + Node: Extracting299393
  1885. + Node: Distribution contents300988
  1886. + Node: Unix Installation303792
  1887. + Node: Quick Installation304483
  1888. + Node: Configuration Philosophy305652
  1889. + Node: New Configurations307978
  1890. + Node: VMS Installation310080
  1891. + Node: VMS Compilation310639
  1892. + Node: VMS Installation Details312254
  1893. + Node: VMS Running313891
  1894. + Node: VMS POSIX315477
  1895. + Node: MS-DOS Installation316865
  1896. + Node: Atari Installation317793
  1897. + Node: Gawk Summary323555
  1898. + Node: Command Line Summary324316
  1899. + Node: Language Summary326749
  1900. + Node: Variables/Fields328834
  1901. + Node: Fields Summary329560
  1902. + Node: Built-in Summary331027
  1903. + Node: Arrays Summary334232
  1904. + Node: Data Type Summary335507
  1905. + Node: Rules Summary336980
  1906. + Node: Pattern Summary338629
  1907. + Node: Regexp Summary340862
  1908. + Node: Actions Summary342082
  1909. + Node: Operator Summary342997
  1910. + Node: Control Flow Summary344358
  1911. + Node: I/O Summary344964
  1912. + Node: Printf Summary346843
  1913. + Node: Special File Summary348669
  1914. + Node: Numeric Functions Summary350727
  1915. + Node: String Functions Summary351563
  1916. + Node: Time Functions Summary353395
  1917. + Node: String Constants Summary354159
  1918. + Node: Functions Summary355542
  1919. + Node: Historical Features356601
  1920. + Node: Sample Program357458
  1921. + Node: Bugs361712
  1922. + Node: Notes364560
  1923. + Node: Compatibility Mode365089
  1924. + Node: Future Extensions365922
  1925. + Node: Improvements368219
  1926. + Node: Glossary370254
  1927. + Node: Index380695
  1928. + 
  1929. + End Tag Table
  1930. diff -rc --new-file /src/baseline/gawk-2.15.5/gawk.info-1 gawk-2.15.5/gawk.info-1
  1931. *** /src/baseline/gawk-2.15.5/gawk.info-1    Thu Jan  1 00:00:00 1970
  1932. --- gawk-2.15.5/gawk.info-1    Sun Jun 12 22:28:48 1994
  1933. ***************
  1934. *** 0 ****
  1935. --- 1,1069 ----
  1936. + This is Info file gawk.info, produced by Makeinfo-1.55 from the input
  1937. + file /gnu/src/amiga/gawk-2.15.5/gawk.texi.
  1938. + 
  1939. +    This file documents `awk', a program that you can use to select
  1940. + particular records in a file and perform operations upon them.
  1941. + 
  1942. +    This is Edition 0.15 of `The GAWK Manual',
  1943. + for the 2.15 version of the GNU implementation
  1944. + of AWK.
  1945. + 
  1946. +    Copyright (C) 1989, 1991, 1992, 1993 Free Software Foundation, Inc.
  1947. + 
  1948. +    Permission is granted to make and distribute verbatim copies of this
  1949. + manual provided the copyright notice and this permission notice are
  1950. + preserved on all copies.
  1951. + 
  1952. +    Permission is granted to copy and distribute modified versions of
  1953. + this manual under the conditions for verbatim copying, provided that
  1954. + the entire resulting derived work is distributed under the terms of a
  1955. + permission notice identical to this one.
  1956. + 
  1957. +    Permission is granted to copy and distribute translations of this
  1958. + manual into another language, under the above conditions for modified
  1959. + versions, except that this permission notice may be stated in a
  1960. + translation approved by the Foundation.
  1961. + 
  1962. + 
  1963. + File: gawk.info,  Node: Top,  Next: Preface,  Prev: (dir),  Up: (dir)
  1964. + 
  1965. + General Introduction
  1966. + ********************
  1967. + 
  1968. +    This file documents `awk', a program that you can use to select
  1969. + particular records in a file and perform operations upon them.
  1970. + 
  1971. +    This is Edition 0.15 of `The GAWK Manual',
  1972. + for the 2.15 version of the GNU implementation
  1973. + of AWK.
  1974. + 
  1975. + * Menu:
  1976. + 
  1977. + * Preface::                     What you can do with `awk'; brief history
  1978. +                                 and acknowledgements.
  1979. + * Copying::                     Your right to copy and distribute `gawk'.
  1980. + * This Manual::                 Using this manual.
  1981. +                                 Includes sample input files that you can use.
  1982. + * Getting Started::             A basic introduction to using `awk'.
  1983. +                                 How to run an `awk' program.
  1984. +                                 Command line syntax.
  1985. + * Reading Files::               How to read files and manipulate fields.
  1986. + * Printing::                    How to print using `awk'.  Describes the
  1987. +                                 `print' and `printf' statements.
  1988. +                                 Also describes redirection of output.
  1989. + * One-liners::                  Short, sample `awk' programs.
  1990. + * Patterns::                    The various types of patterns
  1991. +                                 explained in detail.
  1992. + * Actions::                     The various types of actions are
  1993. +                                 introduced here.  Describes
  1994. +                                 expressions and the various operators in
  1995. +                                 detail.  Also describes comparison expressions.
  1996. + * Expressions::                 Expressions are the basic building
  1997. +                                 blocks of statements.
  1998. + * Statements::                  The various control statements are
  1999. +                                 described in detail.
  2000. + * Arrays::                      The description and use of arrays.
  2001. +                                 Also includes array-oriented control
  2002. +                                 statements.
  2003. + * Built-in::                    The built-in functions are summarized here.
  2004. + * User-defined::                User-defined functions are described in detail.
  2005. + * Built-in Variables::          Built-in Variables
  2006. + * Command Line::                How to run `gawk'.
  2007. + * Language History::            The evolution of the `awk' language.
  2008. + * Installation::                Installing `gawk' under
  2009. +                                 various operating systems.
  2010. + * Gawk Summary::                `gawk' Options and Language Summary.
  2011. + * Sample Program::              A sample `awk' program with a
  2012. +                                 complete explanation.
  2013. + * Bugs::                        Reporting Problems and Bugs.
  2014. + * Notes::                       Something about the
  2015. +                                 implementation of `gawk'.
  2016. + * Glossary::                    An explanation of some unfamiliar terms.
  2017. + * Index::
  2018. + 
  2019. + 
  2020. + File: gawk.info,  Node: Preface,  Next: Copying,  Prev: Top,  Up: Top
  2021. + 
  2022. + Preface
  2023. + *******
  2024. + 
  2025. +    If you are like many computer users, you would frequently like to
  2026. + make changes in various text files wherever certain patterns appear, or
  2027. + extract data from parts of certain lines while discarding the rest.  To
  2028. + write a program to do this in a language such as C or Pascal is a
  2029. + time-consuming inconvenience that may take many lines of code.  The job
  2030. + may be easier with `awk'.
  2031. + 
  2032. +    The `awk' utility interprets a special-purpose programming language
  2033. + that makes it possible to handle simple data-reformatting jobs easily
  2034. + with just a few lines of code.
  2035. + 
  2036. +    The GNU implementation of `awk' is called `gawk'; it is fully upward
  2037. + compatible with the System V Release 4 version of `awk'.  `gawk' is
  2038. + also upward compatible with the POSIX (draft) specification of the
  2039. + `awk' language.  This means that all properly written `awk' programs
  2040. + should work with `gawk'.  Thus, we usually don't distinguish between
  2041. + `gawk' and other `awk' implementations in this manual.
  2042. + 
  2043. +    This manual teaches you what `awk' does and how you can use `awk'
  2044. + effectively.  You should already be familiar with basic system commands
  2045. + such as `ls'.  Using `awk' you can:
  2046. + 
  2047. +    * manage small, personal databases
  2048. + 
  2049. +    * generate reports
  2050. + 
  2051. +    * validate data
  2052. + 
  2053. +    * produce indexes, and perform other document preparation tasks
  2054. + 
  2055. +    * even experiment with algorithms that can be adapted later to other
  2056. +      computer languages
  2057. + 
  2058. + * Menu:
  2059. + 
  2060. + * History::                     The history of `gawk' and
  2061. +                                 `awk'.  Acknowledgements.
  2062. + 
  2063. + 
  2064. + File: gawk.info,  Node: History,  Prev: Preface,  Up: Preface
  2065. + 
  2066. + History of `awk' and `gawk'
  2067. + ===========================
  2068. + 
  2069. +    The name `awk' comes from the initials of its designers: Alfred V.
  2070. + Aho, Peter J. Weinberger, and Brian W. Kernighan.  The original version
  2071. + of `awk' was written in 1977.  In 1985 a new version made the
  2072. + programming language more powerful, introducing user-defined functions,
  2073. + multiple input streams, and computed regular expressions.  This new
  2074. + version became generally available with System V Release 3.1.  The
  2075. + version in System V Release 4 added some new features and also cleaned
  2076. + up the behavior in some of the "dark corners" of the language.  The
  2077. + specification for `awk' in the POSIX Command Language and Utilities
  2078. + standard further clarified the language based on feedback from both the
  2079. + `gawk' designers, and the original `awk' designers.
  2080. + 
  2081. +    The GNU implementation, `gawk', was written in 1986 by Paul Rubin
  2082. + and Jay Fenlason, with advice from Richard Stallman.  John Woods
  2083. + contributed parts of the code as well.  In 1988 and 1989, David
  2084. + Trueman, with help from Arnold Robbins, thoroughly reworked `gawk' for
  2085. + compatibility with the newer `awk'.  Current development (1992) focuses
  2086. + on bug fixes, performance improvements, and standards compliance.
  2087. + 
  2088. +    We need to thank many people for their assistance in producing this
  2089. + manual.  Jay Fenlason contributed many ideas and sample programs.
  2090. + Richard Mlynarik and Robert J. Chassell gave helpful comments on early
  2091. + drafts of this manual.  The paper `A Supplemental Document for `awk''
  2092. + by John W.  Pierce of the Chemistry Department at UC San Diego,
  2093. + pinpointed several issues relevant both to `awk' implementation and to
  2094. + this manual, that would otherwise have escaped us.  David Trueman, Pat
  2095. + Rankin, and Michal Jaegermann also contributed sections of the manual.
  2096. + 
  2097. +    The following people provided many helpful comments on this edition
  2098. + of the manual: Rick Adams, Michael Brennan, Rich Burridge, Diane Close,
  2099. + Christopher ("Topher") Eliot, Michael Lijewski, Pat Rankin, Miriam
  2100. + Robbins, and Michal Jaegermann.  Robert J. Chassell provided much
  2101. + valuable advice on the use of Texinfo.
  2102. + 
  2103. +    Finally, we would like to thank Brian Kernighan of Bell Labs for
  2104. + invaluable assistance during the testing and debugging of `gawk', and
  2105. + for help in clarifying numerous points about the language.
  2106. + 
  2107. + 
  2108. + File: gawk.info,  Node: Copying,  Next: This Manual,  Prev: Preface,  Up: Top
  2109. + 
  2110. + GNU GENERAL PUBLIC LICENSE
  2111. + **************************
  2112. + 
  2113. +                          Version 2, June 1991
  2114. + 
  2115. +      Copyright (C) 1989, 1991 Free Software Foundation, Inc.
  2116. +      675 Mass Ave, Cambridge, MA 02139, USA
  2117. +      
  2118. +      Everyone is permitted to copy and distribute verbatim copies
  2119. +      of this license document, but changing it is not allowed.
  2120. + 
  2121. + Preamble
  2122. + ========
  2123. + 
  2124. +    The licenses for most software are designed to take away your
  2125. + freedom to share and change it.  By contrast, the GNU General Public
  2126. + License is intended to guarantee your freedom to share and change free
  2127. + software--to make sure the software is free for all its users.  This
  2128. + General Public License applies to most of the Free Software
  2129. + Foundation's software and to any other program whose authors commit to
  2130. + using it.  (Some other Free Software Foundation software is covered by
  2131. + the GNU Library General Public License instead.)  You can apply it to
  2132. + your programs, too.
  2133. + 
  2134. +    When we speak of free software, we are referring to freedom, not
  2135. + price.  Our General Public Licenses are designed to make sure that you
  2136. + have the freedom to distribute copies of free software (and charge for
  2137. + this service if you wish), that you receive source code or can get it
  2138. + if you want it, that you can change the software or use pieces of it in
  2139. + new free programs; and that you know you can do these things.
  2140. + 
  2141. +    To protect your rights, we need to make restrictions that forbid
  2142. + anyone to deny you these rights or to ask you to surrender the rights.
  2143. + These restrictions translate to certain responsibilities for you if you
  2144. + distribute copies of the software, or if you modify it.
  2145. + 
  2146. +    For example, if you distribute copies of such a program, whether
  2147. + gratis or for a fee, you must give the recipients all the rights that
  2148. + you have.  You must make sure that they, too, receive or can get the
  2149. + source code.  And you must show them these terms so they know their
  2150. + rights.
  2151. + 
  2152. +    We protect your rights with two steps: (1) copyright the software,
  2153. + and (2) offer you this license which gives you legal permission to copy,
  2154. + distribute and/or modify the software.
  2155. + 
  2156. +    Also, for each author's protection and ours, we want to make certain
  2157. + that everyone understands that there is no warranty for this free
  2158. + software.  If the software is modified by someone else and passed on, we
  2159. + want its recipients to know that what they have is not the original, so
  2160. + that any problems introduced by others will not reflect on the original
  2161. + authors' reputations.
  2162. + 
  2163. +    Finally, any free program is threatened constantly by software
  2164. + patents.  We wish to avoid the danger that redistributors of a free
  2165. + program will individually obtain patent licenses, in effect making the
  2166. + program proprietary.  To prevent this, we have made it clear that any
  2167. + patent must be licensed for everyone's free use or not licensed at all.
  2168. + 
  2169. +    The precise terms and conditions for copying, distribution and
  2170. + modification follow.
  2171. + 
  2172. +     TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
  2173. + 
  2174. +   1. This License applies to any program or other work which contains a
  2175. +      notice placed by the copyright holder saying it may be distributed
  2176. +      under the terms of this General Public License.  The "Program",
  2177. +      below, refers to any such program or work, and a "work based on
  2178. +      the Program" means either the Program or any derivative work under
  2179. +      copyright law: that is to say, a work containing the Program or a
  2180. +      portion of it, either verbatim or with modifications and/or
  2181. +      translated into another language.  (Hereinafter, translation is
  2182. +      included without limitation in the term "modification".)  Each
  2183. +      licensee is addressed as "you".
  2184. + 
  2185. +      Activities other than copying, distribution and modification are
  2186. +      not covered by this License; they are outside its scope.  The act
  2187. +      of running the Program is not restricted, and the output from the
  2188. +      Program is covered only if its contents constitute a work based on
  2189. +      the Program (independent of having been made by running the
  2190. +      Program).  Whether that is true depends on what the Program does.
  2191. + 
  2192. +   2. You may copy and distribute verbatim copies of the Program's
  2193. +      source code as you receive it, in any medium, provided that you
  2194. +      conspicuously and appropriately publish on each copy an appropriate
  2195. +      copyright notice and disclaimer of warranty; keep intact all the
  2196. +      notices that refer to this License and to the absence of any
  2197. +      warranty; and give any other recipients of the Program a copy of
  2198. +      this License along with the Program.
  2199. + 
  2200. +      You may charge a fee for the physical act of transferring a copy,
  2201. +      and you may at your option offer warranty protection in exchange
  2202. +      for a fee.
  2203. + 
  2204. +   3. You may modify your copy or copies of the Program or any portion
  2205. +      of it, thus forming a work based on the Program, and copy and
  2206. +      distribute such modifications or work under the terms of Section 1
  2207. +      above, provided that you also meet all of these conditions:
  2208. + 
  2209. +        a. You must cause the modified files to carry prominent notices
  2210. +           stating that you changed the files and the date of any change.
  2211. + 
  2212. +        b. You must cause any work that you distribute or publish, that
  2213. +           in whole or in part contains or is derived from the Program
  2214. +           or any part thereof, to be licensed as a whole at no charge
  2215. +           to all third parties under the terms of this License.
  2216. + 
  2217. +        c. If the modified program normally reads commands interactively
  2218. +           when run, you must cause it, when started running for such
  2219. +           interactive use in the most ordinary way, to print or display
  2220. +           an announcement including an appropriate copyright notice and
  2221. +           a notice that there is no warranty (or else, saying that you
  2222. +           provide a warranty) and that users may redistribute the
  2223. +           program under these conditions, and telling the user how to
  2224. +           view a copy of this License.  (Exception: if the Program
  2225. +           itself is interactive but does not normally print such an
  2226. +           announcement, your work based on the Program is not required
  2227. +           to print an announcement.)
  2228. + 
  2229. +      These requirements apply to the modified work as a whole.  If
  2230. +      identifiable sections of that work are not derived from the
  2231. +      Program, and can be reasonably considered independent and separate
  2232. +      works in themselves, then this License, and its terms, do not
  2233. +      apply to those sections when you distribute them as separate
  2234. +      works.  But when you distribute the same sections as part of a
  2235. +      whole which is a work based on the Program, the distribution of
  2236. +      the whole must be on the terms of this License, whose permissions
  2237. +      for other licensees extend to the entire whole, and thus to each
  2238. +      and every part regardless of who wrote it.
  2239. + 
  2240. +      Thus, it is not the intent of this section to claim rights or
  2241. +      contest your rights to work written entirely by you; rather, the
  2242. +      intent is to exercise the right to control the distribution of
  2243. +      derivative or collective works based on the Program.
  2244. + 
  2245. +      In addition, mere aggregation of another work not based on the
  2246. +      Program with the Program (or with a work based on the Program) on
  2247. +      a volume of a storage or distribution medium does not bring the
  2248. +      other work under the scope of this License.
  2249. + 
  2250. +   4. You may copy and distribute the Program (or a work based on it,
  2251. +      under Section 2) in object code or executable form under the terms
  2252. +      of Sections 1 and 2 above provided that you also do one of the
  2253. +      following:
  2254. + 
  2255. +        a. Accompany it with the complete corresponding machine-readable
  2256. +           source code, which must be distributed under the terms of
  2257. +           Sections 1 and 2 above on a medium customarily used for
  2258. +           software interchange; or,
  2259. + 
  2260. +        b. Accompany it with a written offer, valid for at least three
  2261. +           years, to give any third party, for a charge no more than your
  2262. +           cost of physically performing source distribution, a complete
  2263. +           machine-readable copy of the corresponding source code, to be
  2264. +           distributed under the terms of Sections 1 and 2 above on a
  2265. +           medium customarily used for software interchange; or,
  2266. + 
  2267. +        c. Accompany it with the information you received as to the offer
  2268. +           to distribute corresponding source code.  (This alternative is
  2269. +           allowed only for noncommercial distribution and only if you
  2270. +           received the program in object code or executable form with
  2271. +           such an offer, in accord with Subsection b above.)
  2272. + 
  2273. +      The source code for a work means the preferred form of the work for
  2274. +      making modifications to it.  For an executable work, complete
  2275. +      source code means all the source code for all modules it contains,
  2276. +      plus any associated interface definition files, plus the scripts
  2277. +      used to control compilation and installation of the executable.
  2278. +      However, as a special exception, the source code distributed need
  2279. +      not include anything that is normally distributed (in either
  2280. +      source or binary form) with the major components (compiler,
  2281. +      kernel, and so on) of the operating system on which the executable
  2282. +      runs, unless that component itself accompanies the executable.
  2283. + 
  2284. +      If distribution of executable or object code is made by offering
  2285. +      access to copy from a designated place, then offering equivalent
  2286. +      access to copy the source code from the same place counts as
  2287. +      distribution of the source code, even though third parties are not
  2288. +      compelled to copy the source along with the object code.
  2289. + 
  2290. +   5. You may not copy, modify, sublicense, or distribute the Program
  2291. +      except as expressly provided under this License.  Any attempt
  2292. +      otherwise to copy, modify, sublicense or distribute the Program is
  2293. +      void, and will automatically terminate your rights under this
  2294. +      License.  However, parties who have received copies, or rights,
  2295. +      from you under this License will not have their licenses
  2296. +      terminated so long as such parties remain in full compliance.
  2297. + 
  2298. +   6. You are not required to accept this License, since you have not
  2299. +      signed it.  However, nothing else grants you permission to modify
  2300. +      or distribute the Program or its derivative works.  These actions
  2301. +      are prohibited by law if you do not accept this License.
  2302. +      Therefore, by modifying or distributing the Program (or any work
  2303. +      based on the Program), you indicate your acceptance of this
  2304. +      License to do so, and all its terms and conditions for copying,
  2305. +      distributing or modifying the Program or works based on it.
  2306. + 
  2307. +   7. Each time you redistribute the Program (or any work based on the
  2308. +      Program), the recipient automatically receives a license from the
  2309. +      original licensor to copy, distribute or modify the Program
  2310. +      subject to these terms and conditions.  You may not impose any
  2311. +      further restrictions on the recipients' exercise of the rights
  2312. +      granted herein.  You are not responsible for enforcing compliance
  2313. +      by third parties to this License.
  2314. + 
  2315. +   8. If, as a consequence of a court judgment or allegation of patent
  2316. +      infringement or for any other reason (not limited to patent
  2317. +      issues), conditions are imposed on you (whether by court order,
  2318. +      agreement or otherwise) that contradict the conditions of this
  2319. +      License, they do not excuse you from the conditions of this
  2320. +      License.  If you cannot distribute so as to satisfy simultaneously
  2321. +      your obligations under this License and any other pertinent
  2322. +      obligations, then as a consequence you may not distribute the
  2323. +      Program at all.  For example, if a patent license would not permit
  2324. +      royalty-free redistribution of the Program by all those who
  2325. +      receive copies directly or indirectly through you, then the only
  2326. +      way you could satisfy both it and this License would be to refrain
  2327. +      entirely from distribution of the Program.
  2328. + 
  2329. +      If any portion of this section is held invalid or unenforceable
  2330. +      under any particular circumstance, the balance of the section is
  2331. +      intended to apply and the section as a whole is intended to apply
  2332. +      in other circumstances.
  2333. + 
  2334. +      It is not the purpose of this section to induce you to infringe any
  2335. +      patents or other property right claims or to contest validity of
  2336. +      any such claims; this section has the sole purpose of protecting
  2337. +      the integrity of the free software distribution system, which is
  2338. +      implemented by public license practices.  Many people have made
  2339. +      generous contributions to the wide range of software distributed
  2340. +      through that system in reliance on consistent application of that
  2341. +      system; it is up to the author/donor to decide if he or she is
  2342. +      willing to distribute software through any other system and a
  2343. +      licensee cannot impose that choice.
  2344. + 
  2345. +      This section is intended to make thoroughly clear what is believed
  2346. +      to be a consequence of the rest of this License.
  2347. + 
  2348. +   9. If the distribution and/or use of the Program is restricted in
  2349. +      certain countries either by patents or by copyrighted interfaces,
  2350. +      the original copyright holder who places the Program under this
  2351. +      License may add an explicit geographical distribution limitation
  2352. +      excluding those countries, so that distribution is permitted only
  2353. +      in or among countries not thus excluded.  In such case, this
  2354. +      License incorporates the limitation as if written in the body of
  2355. +      this License.
  2356. + 
  2357. +  10. The Free Software Foundation may publish revised and/or new
  2358. +      versions of the General Public License from time to time.  Such
  2359. +      new versions will be similar in spirit to the present version, but
  2360. +      may differ in detail to address new problems or concerns.
  2361. + 
  2362. +      Each version is given a distinguishing version number.  If the
  2363. +      Program specifies a version number of this License which applies
  2364. +      to it and "any later version", you have the option of following
  2365. +      the terms and conditions either of that version or of any later
  2366. +      version published by the Free Software Foundation.  If the Program
  2367. +      does not specify a version number of this License, you may choose
  2368. +      any version ever published by the Free Software Foundation.
  2369. + 
  2370. +  11. If you wish to incorporate parts of the Program into other free
  2371. +      programs whose distribution conditions are different, write to the
  2372. +      author to ask for permission.  For software which is copyrighted
  2373. +      by the Free Software Foundation, write to the Free Software
  2374. +      Foundation; we sometimes make exceptions for this.  Our decision
  2375. +      will be guided by the two goals of preserving the free status of
  2376. +      all derivatives of our free software and of promoting the sharing
  2377. +      and reuse of software generally.
  2378. + 
  2379. +                                 NO WARRANTY
  2380. + 
  2381. +  12. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
  2382. +      WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
  2383. +      LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
  2384. +      HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
  2385. +      WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT
  2386. +      NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
  2387. +      FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE
  2388. +      QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
  2389. +      PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
  2390. +      SERVICING, REPAIR OR CORRECTION.
  2391. + 
  2392. +  13. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
  2393. +      WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
  2394. +      MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE
  2395. +      LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
  2396. +      INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
  2397. +      INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
  2398. +      DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
  2399. +      OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
  2400. +      OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
  2401. +      ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
  2402. + 
  2403. +                       END OF TERMS AND CONDITIONS
  2404. + 
  2405. + How to Apply These Terms to Your New Programs
  2406. + =============================================
  2407. + 
  2408. +    If you develop a new program, and you want it to be of the greatest
  2409. + possible use to the public, the best way to achieve this is to make it
  2410. + free software which everyone can redistribute and change under these
  2411. + terms.
  2412. + 
  2413. +    To do so, attach the following notices to the program.  It is safest
  2414. + to attach them to the start of each source file to most effectively
  2415. + convey the exclusion of warranty; and each file should have at least
  2416. + the "copyright" line and a pointer to where the full notice is found.
  2417. + 
  2418. +      ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES.
  2419. +      Copyright (C) 19YY  NAME OF AUTHOR
  2420. +      
  2421. +      This program is free software; you can redistribute it and/or modify
  2422. +      it under the terms of the GNU General Public License as published by
  2423. +      the Free Software Foundation; either version 2 of the License, or
  2424. +      (at your option) any later version.
  2425. +      
  2426. +      This program is distributed in the hope that it will be useful,
  2427. +      but WITHOUT ANY WARRANTY; without even the implied warranty of
  2428. +      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  2429. +      GNU General Public License for more details.
  2430. +      
  2431. +      You should have received a copy of the GNU General Public License
  2432. +      along with this program; if not, write to the Free Software
  2433. +      Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  2434. + 
  2435. +    Also add information on how to contact you by electronic and paper
  2436. + mail.
  2437. + 
  2438. +    If the program is interactive, make it output a short notice like
  2439. + this when it starts in an interactive mode:
  2440. + 
  2441. +      Gnomovision version 69, Copyright (C) 19YY NAME OF AUTHOR
  2442. +      Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
  2443. +      type `show w'.
  2444. +      This is free software, and you are welcome to redistribute it
  2445. +      under certain conditions; type `show c' for details.
  2446. + 
  2447. +    The hypothetical commands `show w' and `show c' should show the
  2448. + appropriate parts of the General Public License.  Of course, the
  2449. + commands you use may be called something other than `show w' and `show
  2450. + c'; they could even be mouse-clicks or menu items--whatever suits your
  2451. + program.
  2452. + 
  2453. +    You should also get your employer (if you work as a programmer) or
  2454. + your school, if any, to sign a "copyright disclaimer" for the program,
  2455. + if necessary.  Here is a sample; alter the names:
  2456. + 
  2457. +      Yoyodyne, Inc., hereby disclaims all copyright interest in the program
  2458. +      `Gnomovision' (which makes passes at compilers) written by James Hacker.
  2459. +      
  2460. +      SIGNATURE OF TY COON, 1 April 1989
  2461. +      Ty Coon, President of Vice
  2462. + 
  2463. +    This General Public License does not permit incorporating your
  2464. + program into proprietary programs.  If your program is a subroutine
  2465. + library, you may consider it more useful to permit linking proprietary
  2466. + applications with the library.  If this is what you want to do, use the
  2467. + GNU Library General Public License instead of this License.
  2468. + 
  2469. + 
  2470. + File: gawk.info,  Node: This Manual,  Next: Getting Started,  Prev: Copying,  Up: Top
  2471. + 
  2472. + Using this Manual
  2473. + *****************
  2474. + 
  2475. +    The term `awk' refers to a particular program, and to the language
  2476. + you use to tell this program what to do.  When we need to be careful,
  2477. + we call the program "the `awk' utility" and the language "the `awk'
  2478. + language."  The term `gawk' refers to a version of `awk' developed as
  2479. + part the GNU project.  The purpose of this manual is to explain both the
  2480. + `awk' language and how to run the `awk' utility.
  2481. + 
  2482. +    While concentrating on the features of `gawk', the manual will also
  2483. + attempt to describe important differences between `gawk' and other
  2484. + `awk' implementations.  In particular, any features that are not in the
  2485. + POSIX standard for `awk' will be noted.
  2486. + 
  2487. +    The term "`awk' program" refers to a program written by you in the
  2488. + `awk' programming language.
  2489. + 
  2490. +    *Note Getting Started with `awk': Getting Started, for the bare
  2491. + essentials you need to know to start using `awk'.
  2492. + 
  2493. +    Some useful "one-liners" are included to give you a feel for the
  2494. + `awk' language (*note Useful "One-liners": One-liners.).
  2495. + 
  2496. +    A sample `awk' program has been provided for you (*note Sample
  2497. + Program::.).
  2498. + 
  2499. +    If you find terms that you aren't familiar with, try looking them up
  2500. + in the glossary (*note Glossary::.).
  2501. + 
  2502. +    The entire `awk' language is summarized for quick reference in *Note
  2503. + `gawk' Summary: Gawk Summary.  Look there if you just need to refresh
  2504. + your memory about a particular feature.
  2505. + 
  2506. +    Most of the time complete `awk' programs are used as examples, but in
  2507. + some of the more advanced sections, only the part of the `awk' program
  2508. + that illustrates the concept being described is shown.
  2509. + 
  2510. + * Menu:
  2511. + 
  2512. + * Sample Data Files::           Sample data files for use in the `awk'
  2513. +                                 programs illustrated in this manual.
  2514. + 
  2515. + 
  2516. + File: gawk.info,  Node: Sample Data Files,  Prev: This Manual,  Up: This Manual
  2517. + 
  2518. + Data Files for the Examples
  2519. + ===========================
  2520. + 
  2521. +    Many of the examples in this manual take their input from two sample
  2522. + data files.  The first, called `BBS-list', represents a list of
  2523. + computer bulletin board systems together with information about those
  2524. + systems.  The second data file, called `inventory-shipped', contains
  2525. + information about shipments on a monthly basis.  Each line of these
  2526. + files is one "record".
  2527. + 
  2528. +    In the file `BBS-list', each record contains the name of a computer
  2529. + bulletin board, its phone number, the board's baud rate, and a code for
  2530. + the number of hours it is operational.  An `A' in the last column means
  2531. + the board operates 24 hours a day.  A `B' in the last column means the
  2532. + board operates evening and weekend hours, only.  A `C' means the board
  2533. + operates only on weekends.
  2534. + 
  2535. +      aardvark     555-5553     1200/300          B
  2536. +      alpo-net     555-3412     2400/1200/300     A
  2537. +      barfly       555-7685     1200/300          A
  2538. +      bites        555-1675     2400/1200/300     A
  2539. +      camelot      555-0542     300               C
  2540. +      core         555-2912     1200/300          C
  2541. +      fooey        555-1234     2400/1200/300     B
  2542. +      foot         555-6699     1200/300          B
  2543. +      macfoo       555-6480     1200/300          A
  2544. +      sdace        555-3430     2400/1200/300     A
  2545. +      sabafoo      555-2127     1200/300          C
  2546. + 
  2547. +    The second data file, called `inventory-shipped', represents
  2548. + information about shipments during the year.  Each record contains the
  2549. + month of the year, the number of green crates shipped, the number of
  2550. + red boxes shipped, the number of orange bags shipped, and the number of
  2551. + blue packages shipped, respectively.  There are 16 entries, covering
  2552. + the 12 months of one year and 4 months of the next year.
  2553. + 
  2554. +      Jan  13  25  15 115
  2555. +      Feb  15  32  24 226
  2556. +      Mar  15  24  34 228
  2557. +      Apr  31  52  63 420
  2558. +      May  16  34  29 208
  2559. +      Jun  31  42  75 492
  2560. +      Jul  24  34  67 436
  2561. +      Aug  15  34  47 316
  2562. +      Sep  13  55  37 277
  2563. +      Oct  29  54  68 525
  2564. +      Nov  20  87  82 577
  2565. +      Dec  17  35  61 401
  2566. +      
  2567. +      Jan  21  36  64 620
  2568. +      Feb  26  58  80 652
  2569. +      Mar  24  75  70 495
  2570. +      Apr  21  70  74 514
  2571. + 
  2572. +    If you are reading this in GNU Emacs using Info, you can copy the
  2573. + regions of text showing these sample files into your own test files.
  2574. + This way you can try out the examples shown in the remainder of this
  2575. + document.  You do this by using the command `M-x write-region' to copy
  2576. + text from the Info file into a file for use with `awk' (*Note Misc File
  2577. + Ops: (emacs)Misc File Ops, for more information).  Using this
  2578. + information, create your own `BBS-list' and `inventory-shipped' files,
  2579. + and practice what you learn in this manual.
  2580. + 
  2581. + 
  2582. + File: gawk.info,  Node: Getting Started,  Next: Reading Files,  Prev: This Manual,  Up: Top
  2583. + 
  2584. + Getting Started with `awk'
  2585. + **************************
  2586. + 
  2587. +    The basic function of `awk' is to search files for lines (or other
  2588. + units of text) that contain certain patterns.  When a line matches one
  2589. + of the patterns, `awk' performs specified actions on that line.  `awk'
  2590. + keeps processing input lines in this way until the end of the input
  2591. + file is reached.
  2592. + 
  2593. +    When you run `awk', you specify an `awk' "program" which tells `awk'
  2594. + what to do.  The program consists of a series of "rules".  (It may also
  2595. + contain "function definitions", but that is an advanced feature, so we
  2596. + will ignore it for now.  *Note User-defined Functions: User-defined.)
  2597. + Each rule specifies one pattern to search for, and one action to
  2598. + perform when that pattern is found.
  2599. + 
  2600. +    Syntactically, a rule consists of a pattern followed by an action.
  2601. + The action is enclosed in curly braces to separate it from the pattern.
  2602. + Rules are usually separated by newlines.  Therefore, an `awk' program
  2603. + looks like this:
  2604. + 
  2605. +      PATTERN { ACTION }
  2606. +      PATTERN { ACTION }
  2607. +      ...
  2608. + 
  2609. + * Menu:
  2610. + 
  2611. + * Very Simple::                 A very simple example.
  2612. + * Two Rules::                   A less simple one-line example with two rules.
  2613. + * More Complex::                A more complex example.
  2614. + * Running gawk::                How to run `gawk' programs;
  2615. +                                 includes command line syntax.
  2616. + * Comments::                    Adding documentation to `gawk' programs.
  2617. + * Statements/Lines::            Subdividing or combining statements into lines.
  2618. + * When::                        When to use `gawk' and
  2619. +                                 when to use other things.
  2620. + 
  2621. + 
  2622. + File: gawk.info,  Node: Very Simple,  Next: Two Rules,  Prev: Getting Started,  Up: Getting Started
  2623. + 
  2624. + A Very Simple Example
  2625. + =====================
  2626. + 
  2627. +    The following command runs a simple `awk' program that searches the
  2628. + input file `BBS-list' for the string of characters: `foo'.  (A string
  2629. + of characters is usually called, a "string".  The term "string" is
  2630. + perhaps based on similar usage in English, such as "a string of
  2631. + pearls," or, "a string of cars in a train.")
  2632. + 
  2633. +      awk '/foo/ { print $0 }' BBS-list
  2634. + 
  2635. + When lines containing `foo' are found, they are printed, because
  2636. + `print $0' means print the current line.  (Just `print' by itself means
  2637. + the same thing, so we could have written that instead.)
  2638. + 
  2639. +    You will notice that slashes, `/', surround the string `foo' in the
  2640. + actual `awk' program.  The slashes indicate that `foo' is a pattern to
  2641. + search for.  This type of pattern is called a "regular expression", and
  2642. + is covered in more detail later (*note Regular Expressions as Patterns:
  2643. + Regexp.).  There are single-quotes around the `awk' program so that the
  2644. + shell won't interpret any of it as special shell characters.
  2645. + 
  2646. +    Here is what this program prints:
  2647. + 
  2648. +      fooey        555-1234     2400/1200/300     B
  2649. +      foot         555-6699     1200/300          B
  2650. +      macfoo       555-6480     1200/300          A
  2651. +      sabafoo      555-2127     1200/300          C
  2652. + 
  2653. +    In an `awk' rule, either the pattern or the action can be omitted,
  2654. + but not both.  If the pattern is omitted, then the action is performed
  2655. + for *every* input line.  If the action is omitted, the default action
  2656. + is to print all lines that match the pattern.
  2657. + 
  2658. +    Thus, we could leave out the action (the `print' statement and the
  2659. + curly braces) in the above example, and the result would be the same:
  2660. + all lines matching the pattern `foo' would be printed.  By comparison,
  2661. + omitting the `print' statement but retaining the curly braces makes an
  2662. + empty action that does nothing; then no lines would be printed.
  2663. + 
  2664. + 
  2665. + File: gawk.info,  Node: Two Rules,  Next: More Complex,  Prev: Very Simple,  Up: Getting Started
  2666. + 
  2667. + An Example with Two Rules
  2668. + =========================
  2669. + 
  2670. +    The `awk' utility reads the input files one line at a time.  For
  2671. + each line, `awk' tries the patterns of each of the rules.  If several
  2672. + patterns match then several actions are run, in the order in which they
  2673. + appear in the `awk' program.  If no patterns match, then no actions are
  2674. + run.
  2675. + 
  2676. +    After processing all the rules (perhaps none) that match the line,
  2677. + `awk' reads the next line (however, *note The `next' Statement: Next
  2678. + Statement.).  This continues until the end of the file is reached.
  2679. + 
  2680. +    For example, the `awk' program:
  2681. + 
  2682. +      /12/  { print $0 }
  2683. +      /21/  { print $0 }
  2684. + 
  2685. + contains two rules.  The first rule has the string `12' as the pattern
  2686. + and `print $0' as the action.  The second rule has the string `21' as
  2687. + the pattern and also has `print $0' as the action.  Each rule's action
  2688. + is enclosed in its own pair of braces.
  2689. + 
  2690. +    This `awk' program prints every line that contains the string `12'
  2691. + *or* the string `21'.  If a line contains both strings, it is printed
  2692. + twice, once by each rule.
  2693. + 
  2694. +    If we run this program on our two sample data files, `BBS-list' and
  2695. + `inventory-shipped', as shown here:
  2696. + 
  2697. +      awk '/12/ { print $0 }
  2698. +           /21/ { print $0 }' BBS-list inventory-shipped
  2699. + 
  2700. + we get the following output:
  2701. + 
  2702. +      aardvark     555-5553     1200/300          B
  2703. +      alpo-net     555-3412     2400/1200/300     A
  2704. +      barfly       555-7685     1200/300          A
  2705. +      bites        555-1675     2400/1200/300     A
  2706. +      core         555-2912     1200/300          C
  2707. +      fooey        555-1234     2400/1200/300     B
  2708. +      foot         555-6699     1200/300          B
  2709. +      macfoo       555-6480     1200/300          A
  2710. +      sdace        555-3430     2400/1200/300     A
  2711. +      sabafoo      555-2127     1200/300          C
  2712. +      sabafoo      555-2127     1200/300          C
  2713. +      Jan  21  36  64 620
  2714. +      Apr  21  70  74 514
  2715. + 
  2716. + Note how the line in `BBS-list' beginning with `sabafoo' was printed
  2717. + twice, once for each rule.
  2718. + 
  2719. + 
  2720. + File: gawk.info,  Node: More Complex,  Next: Running gawk,  Prev: Two Rules,  Up: Getting Started
  2721. + 
  2722. + A More Complex Example
  2723. + ======================
  2724. + 
  2725. +    Here is an example to give you an idea of what typical `awk'
  2726. + programs do.  This example shows how `awk' can be used to summarize,
  2727. + select, and rearrange the output of another utility.  It uses features
  2728. + that haven't been covered yet, so don't worry if you don't understand
  2729. + all the details.
  2730. + 
  2731. +      ls -l | awk '$5 == "Nov" { sum += $4 }
  2732. +                   END { print sum }'
  2733. + 
  2734. +    This command prints the total number of bytes in all the files in the
  2735. + current directory that were last modified in November (of any year).
  2736. + (In the C shell you would need to type a semicolon and then a backslash
  2737. + at the end of the first line; in a POSIX-compliant shell, such as the
  2738. + Bourne shell or the Bourne-Again shell, you can type the example as
  2739. + shown.)
  2740. + 
  2741. +    The `ls -l' part of this example is a command that gives you a
  2742. + listing of the files in a directory, including file size and date.  Its
  2743. + output looks like this:
  2744. + 
  2745. +      -rw-r--r--  1 close        1933 Nov  7 13:05 Makefile
  2746. +      -rw-r--r--  1 close       10809 Nov  7 13:03 gawk.h
  2747. +      -rw-r--r--  1 close         983 Apr 13 12:14 gawk.tab.h
  2748. +      -rw-r--r--  1 close       31869 Jun 15 12:20 gawk.y
  2749. +      -rw-r--r--  1 close       22414 Nov  7 13:03 gawk1.c
  2750. +      -rw-r--r--  1 close       37455 Nov  7 13:03 gawk2.c
  2751. +      -rw-r--r--  1 close       27511 Dec  9 13:07 gawk3.c
  2752. +      -rw-r--r--  1 close        7989 Nov  7 13:03 gawk4.c
  2753. + 
  2754. + The first field contains read-write permissions, the second field
  2755. + contains the number of links to the file, and the third field
  2756. + identifies the owner of the file.  The fourth field contains the size
  2757. + of the file in bytes.  The fifth, sixth, and seventh fields contain the
  2758. + month, day, and time, respectively, that the file was last modified.
  2759. + Finally, the eighth field contains the name of the file.
  2760. + 
  2761. +    The `$5 == "Nov"' in our `awk' program is an expression that tests
  2762. + whether the fifth field of the output from `ls -l' matches the string
  2763. + `Nov'.  Each time a line has the string `Nov' in its fifth field, the
  2764. + action `{ sum += $4 }' is performed.  This adds the fourth field (the
  2765. + file size) to the variable `sum'.  As a result, when `awk' has finished
  2766. + reading all the input lines, `sum' is the sum of the sizes of files
  2767. + whose lines matched the pattern.  (This works because `awk' variables
  2768. + are automatically initialized to zero.)
  2769. + 
  2770. +    After the last line of output from `ls' has been processed, the
  2771. + `END' rule is executed, and the value of `sum' is printed.  In this
  2772. + example, the value of `sum' would be 80600.
  2773. + 
  2774. +    These more advanced `awk' techniques are covered in later sections
  2775. + (*note Overview of Actions: Actions.).  Before you can move on to more
  2776. + advanced `awk' programming, you have to know how `awk' interprets your
  2777. + input and displays your output.  By manipulating fields and using
  2778. + `print' statements, you can produce some very useful and spectacular
  2779. + looking reports.
  2780. + 
  2781. + 
  2782. + File: gawk.info,  Node: Running gawk,  Next: Comments,  Prev: More Complex,  Up: Getting Started
  2783. + 
  2784. + How to Run `awk' Programs
  2785. + =========================
  2786. + 
  2787. +    There are several ways to run an `awk' program.  If the program is
  2788. + short, it is easiest to include it in the command that runs `awk', like
  2789. + this:
  2790. + 
  2791. +      awk 'PROGRAM' INPUT-FILE1 INPUT-FILE2 ...
  2792. + 
  2793. + where PROGRAM consists of a series of patterns and actions, as
  2794. + described earlier.
  2795. + 
  2796. +    When the program is long, it is usually more convenient to put it in
  2797. + a file and run it with a command like this:
  2798. + 
  2799. +      awk -f PROGRAM-FILE INPUT-FILE1 INPUT-FILE2 ...
  2800. + 
  2801. + * Menu:
  2802. + 
  2803. + * One-shot::                    Running a short throw-away `awk' program.
  2804. + * Read Terminal::               Using no input files (input from
  2805. +                                 terminal instead).
  2806. + * Long::                        Putting permanent `awk' programs in files.
  2807. + * Executable Scripts::          Making self-contained `awk' programs.
  2808. + 
  2809. + 
  2810. + File: gawk.info,  Node: One-shot,  Next: Read Terminal,  Prev: Running gawk,  Up: Running gawk
  2811. + 
  2812. + One-shot Throw-away `awk' Programs
  2813. + ----------------------------------
  2814. + 
  2815. +    Once you are familiar with `awk', you will often type simple
  2816. + programs at the moment you want to use them.  Then you can write the
  2817. + program as the first argument of the `awk' command, like this:
  2818. + 
  2819. +      awk 'PROGRAM' INPUT-FILE1 INPUT-FILE2 ...
  2820. + 
  2821. + where PROGRAM consists of a series of PATTERNS and ACTIONS, as
  2822. + described earlier.
  2823. + 
  2824. +    This command format instructs the shell to start `awk' and use the
  2825. + PROGRAM to process records in the input file(s).  There are single
  2826. + quotes around PROGRAM so that the shell doesn't interpret any `awk'
  2827. + characters as special shell characters.  They also cause the shell to
  2828. + treat all of PROGRAM as a single argument for `awk' and allow PROGRAM
  2829. + to be more than one line long.
  2830. + 
  2831. +    This format is also useful for running short or medium-sized `awk'
  2832. + programs from shell scripts, because it avoids the need for a separate
  2833. + file for the `awk' program.  A self-contained shell script is more
  2834. + reliable since there are no other files to misplace.
  2835. + 
  2836. + 
  2837. + File: gawk.info,  Node: Read Terminal,  Next: Long,  Prev: One-shot,  Up: Running gawk
  2838. + 
  2839. + Running `awk' without Input Files
  2840. + ---------------------------------
  2841. + 
  2842. +    You can also run `awk' without any input files.  If you type the
  2843. + command line:
  2844. + 
  2845. +      awk 'PROGRAM'
  2846. + 
  2847. + then `awk' applies the PROGRAM to the "standard input", which usually
  2848. + means whatever you type on the terminal.  This continues until you
  2849. + indicate end-of-file by typing `Control-d'.
  2850. + 
  2851. +    For example, if you execute this command:
  2852. + 
  2853. +      awk '/th/'
  2854. + 
  2855. + whatever you type next is taken as data for that `awk' program.  If you
  2856. + go on to type the following data:
  2857. + 
  2858. +      Kathy
  2859. +      Ben
  2860. +      Tom
  2861. +      Beth
  2862. +      Seth
  2863. +      Karen
  2864. +      Thomas
  2865. +      `Control-d'
  2866. + 
  2867. + then `awk' prints this output:
  2868. + 
  2869. +      Kathy
  2870. +      Beth
  2871. +      Seth
  2872. + 
  2873. + as matching the pattern `th'.  Notice that it did not recognize
  2874. + `Thomas' as matching the pattern.  The `awk' language is "case
  2875. + sensitive", and matches patterns exactly.  (However, you can override
  2876. + this with the variable `IGNORECASE'.  *Note Case-sensitivity in
  2877. + Matching: Case-sensitivity.)
  2878. + 
  2879. + 
  2880. + File: gawk.info,  Node: Long,  Next: Executable Scripts,  Prev: Read Terminal,  Up: Running gawk
  2881. + 
  2882. + Running Long Programs
  2883. + ---------------------
  2884. + 
  2885. +    Sometimes your `awk' programs can be very long.  In this case it is
  2886. + more convenient to put the program into a separate file.  To tell `awk'
  2887. + to use that file for its program, you type:
  2888. + 
  2889. +      awk -f SOURCE-FILE INPUT-FILE1 INPUT-FILE2 ...
  2890. + 
  2891. +    The `-f' instructs the `awk' utility to get the `awk' program from
  2892. + the file SOURCE-FILE.  Any file name can be used for SOURCE-FILE.  For
  2893. + example, you could put the program:
  2894. + 
  2895. +      /th/
  2896. + 
  2897. + into the file `th-prog'.  Then this command:
  2898. + 
  2899. +      awk -f th-prog
  2900. + 
  2901. + does the same thing as this one:
  2902. + 
  2903. +      awk '/th/'
  2904. + 
  2905. + which was explained earlier (*note Running `awk' without Input Files:
  2906. + Read Terminal.).  Note that you don't usually need single quotes around
  2907. + the file name that you specify with `-f', because most file names don't
  2908. + contain any of the shell's special characters.  Notice that in
  2909. + `th-prog', the `awk' program did not have single quotes around it.  The
  2910. + quotes are only needed for programs that are provided on the `awk'
  2911. + command line.
  2912. + 
  2913. +    If you want to identify your `awk' program files clearly as such,
  2914. + you can add the extension `.awk' to the file name.  This doesn't affect
  2915. + the execution of the `awk' program, but it does make "housekeeping"
  2916. + easier.
  2917. + 
  2918. + 
  2919. + File: gawk.info,  Node: Executable Scripts,  Prev: Long,  Up: Running gawk
  2920. + 
  2921. + Executable `awk' Programs
  2922. + -------------------------
  2923. + 
  2924. +    Once you have learned `awk', you may want to write self-contained
  2925. + `awk' scripts, using the `#!' script mechanism.  You can do this on
  2926. + many Unix systems (1) (and someday on GNU).
  2927. + 
  2928. +    For example, you could create a text file named `hello', containing
  2929. + the following (where `BEGIN' is a feature we have not yet discussed):
  2930. + 
  2931. +      #! /bin/awk -f
  2932. +      
  2933. +      # a sample awk program
  2934. +      BEGIN    { print "hello, world" }
  2935. + 
  2936. + After making this file executable (with the `chmod' command), you can
  2937. + simply type:
  2938. + 
  2939. +      hello
  2940. + 
  2941. + at the shell, and the system will arrange to run `awk' (2) as if you
  2942. + had typed:
  2943. + 
  2944. +      awk -f hello
  2945. + 
  2946. + Self-contained `awk' scripts are useful when you want to write a
  2947. + program which users can invoke without knowing that the program is
  2948. + written in `awk'.
  2949. + 
  2950. +    If your system does not support the `#!' mechanism, you can get a
  2951. + similar effect using a regular shell script.  It would look something
  2952. + like this:
  2953. + 
  2954. +      : The colon makes sure this script is executed by the Bourne shell.
  2955. +      awk 'PROGRAM' "$@"
  2956. + 
  2957. +    Using this technique, it is *vital* to enclose the PROGRAM in single
  2958. + quotes to protect it from interpretation by the shell.  If you omit the
  2959. + quotes, only a shell wizard can predict the results.
  2960. + 
  2961. +    The `"$@"' causes the shell to forward all the command line
  2962. + arguments to the `awk' program, without interpretation.  The first
  2963. + line, which starts with a colon, is used so that this shell script will
  2964. + work even if invoked by a user who uses the C shell.
  2965. + 
  2966. +    ---------- Footnotes ----------
  2967. + 
  2968. +    (1)  The `#!' mechanism works on Unix systems derived from Berkeley
  2969. + Unix, System V Release 4, and some System V Release 3 systems.
  2970. + 
  2971. +    (2)  The line beginning with `#!' lists the full pathname of an
  2972. + interpreter to be run, and an optional initial command line argument to
  2973. + pass to that interpreter.  The operating system then runs the
  2974. + interpreter with the given argument and the full argument list of the
  2975. + executed program.  The first argument in the list is the full pathname
  2976. + of the `awk' program.  The rest of the argument list will either be
  2977. + options to `awk', or data files, or both.
  2978. + 
  2979. + 
  2980. + File: gawk.info,  Node: Comments,  Next: Statements/Lines,  Prev: Running gawk,  Up: Getting Started
  2981. + 
  2982. + Comments in `awk' Programs
  2983. + ==========================
  2984. + 
  2985. +    A "comment" is some text that is included in a program for the sake
  2986. + of human readers, and that is not really part of the program.  Comments
  2987. + can explain what the program does, and how it works.  Nearly all
  2988. + programming languages have provisions for comments, because programs are
  2989. + typically hard to understand without their extra help.
  2990. + 
  2991. +    In the `awk' language, a comment starts with the sharp sign
  2992. + character, `#', and continues to the end of the line.  The `awk'
  2993. + language ignores the rest of a line following a sharp sign.  For
  2994. + example, we could have put the following into `th-prog':
  2995. + 
  2996. +      # This program finds records containing the pattern `th'.  This is how
  2997. +      # you continue comments on additional lines.
  2998. +      /th/
  2999. + 
  3000. +    You can put comment lines into keyboard-composed throw-away `awk'
  3001. + programs also, but this usually isn't very useful; the purpose of a
  3002. + comment is to help you or another person understand the program at a
  3003. + later time.
  3004. + 
  3005. diff -rc --new-file /src/baseline/gawk-2.15.5/gawk.info-2 gawk-2.15.5/gawk.info-2
  3006. *** /src/baseline/gawk-2.15.5/gawk.info-2    Thu Jan  1 00:00:00 1970
  3007. --- gawk-2.15.5/gawk.info-2    Sun Jun 12 22:28:49 1994
  3008. ***************
  3009. *** 0 ****
  3010. --- 1,1236 ----
  3011. + This is Info file gawk.info, produced by Makeinfo-1.55 from the input
  3012. + file /gnu/src/amiga/gawk-2.15.5/gawk.texi.
  3013. + 
  3014. +    This file documents `awk', a program that you can use to select
  3015. + particular records in a file and perform operations upon them.
  3016. + 
  3017. +    This is Edition 0.15 of `The GAWK Manual',
  3018. + for the 2.15 version of the GNU implementation
  3019. + of AWK.
  3020. + 
  3021. +    Copyright (C) 1989, 1991, 1992, 1993 Free Software Foundation, Inc.
  3022. + 
  3023. +    Permission is granted to make and distribute verbatim copies of this
  3024. + manual provided the copyright notice and this permission notice are
  3025. + preserved on all copies.
  3026. + 
  3027. +    Permission is granted to copy and distribute modified versions of
  3028. + this manual under the conditions for verbatim copying, provided that
  3029. + the entire resulting derived work is distributed under the terms of a
  3030. + permission notice identical to this one.
  3031. + 
  3032. +    Permission is granted to copy and distribute translations of this
  3033. + manual into another language, under the above conditions for modified
  3034. + versions, except that this permission notice may be stated in a
  3035. + translation approved by the Foundation.
  3036. + 
  3037. + 
  3038. + File: gawk.info,  Node: Statements/Lines,  Next: When,  Prev: Comments,  Up: Getting Started
  3039. + 
  3040. + `awk' Statements versus Lines
  3041. + =============================
  3042. + 
  3043. +    Most often, each line in an `awk' program is a separate statement or
  3044. + separate rule, like this:
  3045. + 
  3046. +      awk '/12/  { print $0 }
  3047. +           /21/  { print $0 }' BBS-list inventory-shipped
  3048. + 
  3049. +    But sometimes statements can be more than one line, and lines can
  3050. + contain several statements.  You can split a statement into multiple
  3051. + lines by inserting a newline after any of the following:
  3052. + 
  3053. +      ,    {    ?    :    ||    &&    do    else
  3054. + 
  3055. + A newline at any other point is considered the end of the statement.
  3056. + (Splitting lines after `?' and `:' is a minor `gawk' extension.  The
  3057. + `?' and `:' referred to here is the three operand conditional
  3058. + expression described in *Note Conditional Expressions: Conditional Exp.)
  3059. + 
  3060. +    If you would like to split a single statement into two lines at a
  3061. + point where a newline would terminate it, you can "continue" it by
  3062. + ending the first line with a backslash character, `\'.  This is allowed
  3063. + absolutely anywhere in the statement, even in the middle of a string or
  3064. + regular expression.  For example:
  3065. + 
  3066. +      awk '/This program is too long, so continue it\
  3067. +       on the next line/ { print $1 }'
  3068. + 
  3069. + We have generally not used backslash continuation in the sample
  3070. + programs in this manual.  Since in `gawk' there is no limit on the
  3071. + length of a line, it is never strictly necessary; it just makes
  3072. + programs prettier.  We have preferred to make them even more pretty by
  3073. + keeping the statements short.  Backslash continuation is most useful
  3074. + when your `awk' program is in a separate source file, instead of typed
  3075. + in on the command line.  You should also note that many `awk'
  3076. + implementations are more picky about where you may use backslash
  3077. + continuation.  For maximal portability of your `awk' programs, it is
  3078. + best not to split your lines in the middle of a regular expression or a
  3079. + string.
  3080. + 
  3081. +    *Warning: backslash continuation does not work as described above
  3082. + with the C shell.*  Continuation with backslash works for `awk'
  3083. + programs in files, and also for one-shot programs *provided* you are
  3084. + using a POSIX-compliant shell, such as the Bourne shell or the
  3085. + Bourne-again shell.  But the C shell used on Berkeley Unix behaves
  3086. + differently!  There, you must use two backslashes in a row, followed by
  3087. + a newline.
  3088. + 
  3089. +    When `awk' statements within one rule are short, you might want to
  3090. + put more than one of them on a line.  You do this by separating the
  3091. + statements with a semicolon, `;'.  This also applies to the rules
  3092. + themselves.  Thus, the previous program could have been written:
  3093. + 
  3094. +      /12/ { print $0 } ; /21/ { print $0 }
  3095. + 
  3096. + *Note:* the requirement that rules on the same line must be separated
  3097. + with a semicolon is a recent change in the `awk' language; it was done
  3098. + for consistency with the treatment of statements within an action.
  3099. + 
  3100. + 
  3101. + File: gawk.info,  Node: When,  Prev: Statements/Lines,  Up: Getting Started
  3102. + 
  3103. + When to Use `awk'
  3104. + =================
  3105. + 
  3106. +    You might wonder how `awk' might be useful for you.  Using additional
  3107. + utility programs, more advanced patterns, field separators, arithmetic
  3108. + statements, and other selection criteria, you can produce much more
  3109. + complex output.  The `awk' language is very useful for producing
  3110. + reports from large amounts of raw data, such as summarizing information
  3111. + from the output of other utility programs like `ls'.  (*Note A More
  3112. + Complex Example: More Complex.)
  3113. + 
  3114. +    Programs written with `awk' are usually much smaller than they would
  3115. + be in other languages.  This makes `awk' programs easy to compose and
  3116. + use.  Often `awk' programs can be quickly composed at your terminal,
  3117. + used once, and thrown away.  Since `awk' programs are interpreted, you
  3118. + can avoid the usually lengthy edit-compile-test-debug cycle of software
  3119. + development.
  3120. + 
  3121. +    Complex programs have been written in `awk', including a complete
  3122. + retargetable assembler for 8-bit microprocessors (*note Glossary::., for
  3123. + more information) and a microcode assembler for a special purpose Prolog
  3124. + computer.  However, `awk''s capabilities are strained by tasks of such
  3125. + complexity.
  3126. + 
  3127. +    If you find yourself writing `awk' scripts of more than, say, a few
  3128. + hundred lines, you might consider using a different programming
  3129. + language.  Emacs Lisp is a good choice if you need sophisticated string
  3130. + or pattern matching capabilities.  The shell is also good at string and
  3131. + pattern matching; in addition, it allows powerful use of the system
  3132. + utilities.  More conventional languages, such as C, C++, and Lisp, offer
  3133. + better facilities for system programming and for managing the complexity
  3134. + of large programs.  Programs in these languages may require more lines
  3135. + of source code than the equivalent `awk' programs, but they are easier
  3136. + to maintain and usually run more efficiently.
  3137. + 
  3138. + 
  3139. + File: gawk.info,  Node: Reading Files,  Next: Printing,  Prev: Getting Started,  Up: Top
  3140. + 
  3141. + Reading Input Files
  3142. + *******************
  3143. + 
  3144. +    In the typical `awk' program, all input is read either from the
  3145. + standard input (by default the keyboard, but often a pipe from another
  3146. + command) or from files whose names you specify on the `awk' command
  3147. + line.  If you specify input files, `awk' reads them in order, reading
  3148. + all the data from one before going on to the next.  The name of the
  3149. + current input file can be found in the built-in variable `FILENAME'
  3150. + (*note Built-in Variables::.).
  3151. + 
  3152. +    The input is read in units called records, and processed by the
  3153. + rules one record at a time.  By default, each record is one line.  Each
  3154. + record is split automatically into fields, to make it more convenient
  3155. + for a rule to work on its parts.
  3156. + 
  3157. +    On rare occasions you will need to use the `getline' command, which
  3158. + can do explicit input from any number of files (*note Explicit Input
  3159. + with `getline': Getline.).
  3160. + 
  3161. + * Menu:
  3162. + 
  3163. + * Records::                     Controlling how data is split into records.
  3164. + * Fields::                      An introduction to fields.
  3165. + * Non-Constant Fields::         Non-constant Field Numbers.
  3166. + * Changing Fields::             Changing the Contents of a Field.
  3167. + * Field Separators::            The field separator and how to change it.
  3168. + * Constant Size::               Reading constant width data.
  3169. + * Multiple Line::               Reading multi-line records.
  3170. + * Getline::                     Reading files under explicit program control
  3171. +                                 using the `getline' function.
  3172. + * Close Input::                 Closing an input file (so you can read from
  3173. +                                 the beginning once more).
  3174. + 
  3175. + 
  3176. + File: gawk.info,  Node: Records,  Next: Fields,  Prev: Reading Files,  Up: Reading Files
  3177. + 
  3178. + How Input is Split into Records
  3179. + ===============================
  3180. + 
  3181. +    The `awk' language divides its input into records and fields.
  3182. + Records are separated by a character called the "record separator".  By
  3183. + default, the record separator is the newline character, defining a
  3184. + record to be a single line of text.
  3185. + 
  3186. +    Sometimes you may want to use a different character to separate your
  3187. + records.  You can use a different character by changing the built-in
  3188. + variable `RS'.  The value of `RS' is a string that says how to separate
  3189. + records; the default value is `"\n"', the string containing just a
  3190. + newline character.  This is why records are, by default, single lines.
  3191. + 
  3192. +    `RS' can have any string as its value, but only the first character
  3193. + of the string is used as the record separator.  The other characters are
  3194. + ignored.  `RS' is exceptional in this regard; `awk' uses the full value
  3195. + of all its other built-in variables.
  3196. + 
  3197. +    You can change the value of `RS' in the `awk' program with the
  3198. + assignment operator, `=' (*note Assignment Expressions: Assignment
  3199. + Ops.).  The new record-separator character should be enclosed in
  3200. + quotation marks to make a string constant.  Often the right time to do
  3201. + this is at the beginning of execution, before any input has been
  3202. + processed, so that the very first record will be read with the proper
  3203. + separator.  To do this, use the special `BEGIN' pattern (*note `BEGIN'
  3204. + and `END' Special Patterns: BEGIN/END.).  For example:
  3205. + 
  3206. +      awk 'BEGIN { RS = "/" } ; { print $0 }' BBS-list
  3207. + 
  3208. + changes the value of `RS' to `"/"', before reading any input.  This is
  3209. + a string whose first character is a slash; as a result, records are
  3210. + separated by slashes.  Then the input file is read, and the second rule
  3211. + in the `awk' program (the action with no pattern) prints each record.
  3212. + Since each `print' statement adds a newline at the end of its output,
  3213. + the effect of this `awk' program is to copy the input with each slash
  3214. + changed to a newline.
  3215. + 
  3216. +    Another way to change the record separator is on the command line,
  3217. + using the variable-assignment feature (*note Invoking `awk': Command
  3218. + Line.).
  3219. + 
  3220. +      awk '{ print $0 }' RS="/" BBS-list
  3221. + 
  3222. + This sets `RS' to `/' before processing `BBS-list'.
  3223. + 
  3224. +    Reaching the end of an input file terminates the current input
  3225. + record, even if the last character in the file is not the character in
  3226. + `RS'.
  3227. + 
  3228. +    The empty string, `""' (a string of no characters), has a special
  3229. + meaning as the value of `RS': it means that records are separated only
  3230. + by blank lines.  *Note Multiple-Line Records: Multiple Line, for more
  3231. + details.
  3232. + 
  3233. +    The `awk' utility keeps track of the number of records that have
  3234. + been read so far from the current input file.  This value is stored in a
  3235. + built-in variable called `FNR'.  It is reset to zero when a new file is
  3236. + started.  Another built-in variable, `NR', is the total number of input
  3237. + records read so far from all files.  It starts at zero but is never
  3238. + automatically reset to zero.
  3239. + 
  3240. +    If you change the value of `RS' in the middle of an `awk' run, the
  3241. + new value is used to delimit subsequent records, but the record
  3242. + currently being processed (and records already processed) are not
  3243. + affected.
  3244. + 
  3245. + 
  3246. + File: gawk.info,  Node: Fields,  Next: Non-Constant Fields,  Prev: Records,  Up: Reading Files
  3247. + 
  3248. + Examining Fields
  3249. + ================
  3250. + 
  3251. +    When `awk' reads an input record, the record is automatically
  3252. + separated or "parsed" by the interpreter into chunks called "fields".
  3253. + By default, fields are separated by whitespace, like words in a line.
  3254. + Whitespace in `awk' means any string of one or more spaces and/or tabs;
  3255. + other characters such as newline, formfeed, and so on, that are
  3256. + considered whitespace by other languages are *not* considered
  3257. + whitespace by `awk'.
  3258. + 
  3259. +    The purpose of fields is to make it more convenient for you to refer
  3260. + to these pieces of the record.  You don't have to use them--you can
  3261. + operate on the whole record if you wish--but fields are what make
  3262. + simple `awk' programs so powerful.
  3263. + 
  3264. +    To refer to a field in an `awk' program, you use a dollar-sign, `$',
  3265. + followed by the number of the field you want.  Thus, `$1' refers to the
  3266. + first field, `$2' to the second, and so on.  For example, suppose the
  3267. + following is a line of input:
  3268. + 
  3269. +      This seems like a pretty nice example.
  3270. + 
  3271. + Here the first field, or `$1', is `This'; the second field, or `$2', is
  3272. + `seems'; and so on.  Note that the last field, `$7', is `example.'.
  3273. + Because there is no space between the `e' and the `.', the period is
  3274. + considered part of the seventh field.
  3275. + 
  3276. +    No matter how many fields there are, the last field in a record can
  3277. + be represented by `$NF'.  So, in the example above, `$NF' would be the
  3278. + same as `$7', which is `example.'.  Why this works is explained below
  3279. + (*note Non-constant Field Numbers: Non-Constant Fields.).  If you try
  3280. + to refer to a field beyond the last one, such as `$8' when the record
  3281. + has only 7 fields, you get the empty string.
  3282. + 
  3283. +    Plain `NF', with no `$', is a built-in variable whose value is the
  3284. + number of fields in the current record.
  3285. + 
  3286. +    `$0', which looks like an attempt to refer to the zeroth field, is a
  3287. + special case: it represents the whole input record.  This is what you
  3288. + would use if you weren't interested in fields.
  3289. + 
  3290. +    Here are some more examples:
  3291. + 
  3292. +      awk '$1 ~ /foo/ { print $0 }' BBS-list
  3293. + 
  3294. + This example prints each record in the file `BBS-list' whose first
  3295. + field contains the string `foo'.  The operator `~' is called a
  3296. + "matching operator" (*note Comparison Expressions: Comparison Ops.); it
  3297. + tests whether a string (here, the field `$1') matches a given regular
  3298. + expression.
  3299. + 
  3300. +    By contrast, the following example:
  3301. + 
  3302. +      awk '/foo/ { print $1, $NF }' BBS-list
  3303. + 
  3304. + looks for `foo' in *the entire record* and prints the first field and
  3305. + the last field for each input record containing a match.
  3306. + 
  3307. + 
  3308. + File: gawk.info,  Node: Non-Constant Fields,  Next: Changing Fields,  Prev: Fields,  Up: Reading Files
  3309. + 
  3310. + Non-constant Field Numbers
  3311. + ==========================
  3312. + 
  3313. +    The number of a field does not need to be a constant.  Any
  3314. + expression in the `awk' language can be used after a `$' to refer to a
  3315. + field.  The value of the expression specifies the field number.  If the
  3316. + value is a string, rather than a number, it is converted to a number.
  3317. + Consider this example:
  3318. + 
  3319. +      awk '{ print $NR }'
  3320. + 
  3321. + Recall that `NR' is the number of records read so far: 1 in the first
  3322. + record, 2 in the second, etc.  So this example prints the first field
  3323. + of the first record, the second field of the second record, and so on.
  3324. + For the twentieth record, field number 20 is printed; most likely, the
  3325. + record has fewer than 20 fields, so this prints a blank line.
  3326. + 
  3327. +    Here is another example of using expressions as field numbers:
  3328. + 
  3329. +      awk '{ print $(2*2) }' BBS-list
  3330. + 
  3331. +    The `awk' language must evaluate the expression `(2*2)' and use its
  3332. + value as the number of the field to print.  The `*' sign represents
  3333. + multiplication, so the expression `2*2' evaluates to 4.  The
  3334. + parentheses are used so that the multiplication is done before the `$'
  3335. + operation; they are necessary whenever there is a binary operator in
  3336. + the field-number expression.  This example, then, prints the hours of
  3337. + operation (the fourth field) for every line of the file `BBS-list'.
  3338. + 
  3339. +    If the field number you compute is zero, you get the entire record.
  3340. + Thus, `$(2-2)' has the same value as `$0'.  Negative field numbers are
  3341. + not allowed.
  3342. + 
  3343. +    The number of fields in the current record is stored in the built-in
  3344. + variable `NF' (*note Built-in Variables::.).  The expression `$NF' is
  3345. + not a special feature: it is the direct consequence of evaluating `NF'
  3346. + and using its value as a field number.
  3347. + 
  3348. + 
  3349. + File: gawk.info,  Node: Changing Fields,  Next: Field Separators,  Prev: Non-Constant Fields,  Up: Reading Files
  3350. + 
  3351. + Changing the Contents of a Field
  3352. + ================================
  3353. + 
  3354. +    You can change the contents of a field as seen by `awk' within an
  3355. + `awk' program; this changes what `awk' perceives as the current input
  3356. + record.  (The actual input is untouched: `awk' never modifies the input
  3357. + file.)
  3358. + 
  3359. +    Consider this example:
  3360. + 
  3361. +      awk '{ $3 = $2 - 10; print $2, $3 }' inventory-shipped
  3362. + 
  3363. + The `-' sign represents subtraction, so this program reassigns field
  3364. + three, `$3', to be the value of field two minus ten, `$2 - 10'.  (*Note
  3365. + Arithmetic Operators: Arithmetic Ops.) Then field two, and the new
  3366. + value for field three, are printed.
  3367. + 
  3368. +    In order for this to work, the text in field `$2' must make sense as
  3369. + a number; the string of characters must be converted to a number in
  3370. + order for the computer to do arithmetic on it.  The number resulting
  3371. + from the subtraction is converted back to a string of characters which
  3372. + then becomes field three.  *Note Conversion of Strings and Numbers:
  3373. + Conversion.
  3374. + 
  3375. +    When you change the value of a field (as perceived by `awk'), the
  3376. + text of the input record is recalculated to contain the new field where
  3377. + the old one was.  Therefore, `$0' changes to reflect the altered field.
  3378. + Thus,
  3379. + 
  3380. +      awk '{ $2 = $2 - 10; print $0 }' inventory-shipped
  3381. + 
  3382. + prints a copy of the input file, with 10 subtracted from the second
  3383. + field of each line.
  3384. + 
  3385. +    You can also assign contents to fields that are out of range.  For
  3386. + example:
  3387. + 
  3388. +      awk '{ $6 = ($5 + $4 + $3 + $2) ; print $6 }' inventory-shipped
  3389. + 
  3390. + We've just created `$6', whose value is the sum of fields `$2', `$3',
  3391. + `$4', and `$5'.  The `+' sign represents addition.  For the file
  3392. + `inventory-shipped', `$6' represents the total number of parcels
  3393. + shipped for a particular month.
  3394. + 
  3395. +    Creating a new field changes the internal `awk' copy of the current
  3396. + input record--the value of `$0'.  Thus, if you do `print $0' after
  3397. + adding a field, the record printed includes the new field, with the
  3398. + appropriate number of field separators between it and the previously
  3399. + existing fields.
  3400. + 
  3401. +    This recomputation affects and is affected by several features not
  3402. + yet discussed, in particular, the "output field separator", `OFS',
  3403. + which is used to separate the fields (*note Output Separators::.), and
  3404. + `NF' (the number of fields; *note Examining Fields: Fields.).  For
  3405. + example, the value of `NF' is set to the number of the highest field
  3406. + you create.
  3407. + 
  3408. +    Note, however, that merely *referencing* an out-of-range field does
  3409. + *not* change the value of either `$0' or `NF'.  Referencing an
  3410. + out-of-range field merely produces a null string.  For example:
  3411. + 
  3412. +      if ($(NF+1) != "")
  3413. +          print "can't happen"
  3414. +      else
  3415. +          print "everything is normal"
  3416. + 
  3417. + should print `everything is normal', because `NF+1' is certain to be
  3418. + out of range.  (*Note The `if' Statement: If Statement, for more
  3419. + information about `awk''s `if-else' statements.)
  3420. + 
  3421. +    It is important to note that assigning to a field will change the
  3422. + value of `$0', but will not change the value of `NF', even when you
  3423. + assign the null string to a field.  For example:
  3424. + 
  3425. +      echo a b c d | awk '{ OFS = ":"; $2 = "" ; print ; print NF }'
  3426. + 
  3427. + prints
  3428. + 
  3429. +      a::c:d
  3430. +      4
  3431. + 
  3432. + The field is still there, it just has an empty value.  You can tell
  3433. + because there are two colons in a row.
  3434. + 
  3435. + 
  3436. + File: gawk.info,  Node: Field Separators,  Next: Constant Size,  Prev: Changing Fields,  Up: Reading Files
  3437. + 
  3438. + Specifying how Fields are Separated
  3439. + ===================================
  3440. + 
  3441. +    (This section is rather long; it describes one of the most
  3442. + fundamental operations in `awk'.  If you are a novice with `awk', we
  3443. + recommend that you re-read this section after you have studied the
  3444. + section on regular expressions, *Note Regular Expressions as Patterns:
  3445. + Regexp.)
  3446. + 
  3447. +    The way `awk' splits an input record into fields is controlled by
  3448. + the "field separator", which is a single character or a regular
  3449. + expression.  `awk' scans the input record for matches for the
  3450. + separator; the fields themselves are the text between the matches.  For
  3451. + example, if the field separator is `oo', then the following line:
  3452. + 
  3453. +      moo goo gai pan
  3454. + 
  3455. + would be split into three fields: `m', ` g' and ` gai  pan'.
  3456. + 
  3457. +    The field separator is represented by the built-in variable `FS'.
  3458. + Shell programmers take note!  `awk' does not use the name `IFS' which
  3459. + is used by the shell.
  3460. + 
  3461. +    You can change the value of `FS' in the `awk' program with the
  3462. + assignment operator, `=' (*note Assignment Expressions: Assignment
  3463. + Ops.).  Often the right time to do this is at the beginning of
  3464. + execution, before any input has been processed, so that the very first
  3465. + record will be read with the proper separator.  To do this, use the
  3466. + special `BEGIN' pattern (*note `BEGIN' and `END' Special Patterns:
  3467. + BEGIN/END.).  For example, here we set the value of `FS' to the string
  3468. + `","':
  3469. + 
  3470. +      awk 'BEGIN { FS = "," } ; { print $2 }'
  3471. + 
  3472. + Given the input line,
  3473. + 
  3474. +      John Q. Smith, 29 Oak St., Walamazoo, MI 42139
  3475. + 
  3476. + this `awk' program extracts the string ` 29 Oak St.'.
  3477. + 
  3478. +    Sometimes your input data will contain separator characters that
  3479. + don't separate fields the way you thought they would.  For instance, the
  3480. + person's name in the example we've been using might have a title or
  3481. + suffix attached, such as `John Q. Smith, LXIX'.  From input containing
  3482. + such a name:
  3483. + 
  3484. +      John Q. Smith, LXIX, 29 Oak St., Walamazoo, MI 42139
  3485. + 
  3486. + the previous sample program would extract ` LXIX', instead of ` 29 Oak
  3487. + St.'.  If you were expecting the program to print the address, you
  3488. + would be surprised.  So choose your data layout and separator
  3489. + characters carefully to prevent such problems.
  3490. + 
  3491. +    As you know, by default, fields are separated by whitespace sequences
  3492. + (spaces and tabs), not by single spaces: two spaces in a row do not
  3493. + delimit an empty field.  The default value of the field separator is a
  3494. + string `" "' containing a single space.  If this value were interpreted
  3495. + in the usual way, each space character would separate fields, so two
  3496. + spaces in a row would make an empty field between them.  The reason
  3497. + this does not happen is that a single space as the value of `FS' is a
  3498. + special case: it is taken to specify the default manner of delimiting
  3499. + fields.
  3500. + 
  3501. +    If `FS' is any other single character, such as `","', then each
  3502. + occurrence of that character separates two fields.  Two consecutive
  3503. + occurrences delimit an empty field.  If the character occurs at the
  3504. + beginning or the end of the line, that too delimits an empty field.  The
  3505. + space character is the only single character which does not follow these
  3506. + rules.
  3507. + 
  3508. +    More generally, the value of `FS' may be a string containing any
  3509. + regular expression.  Then each match in the record for the regular
  3510. + expression separates fields.  For example, the assignment:
  3511. + 
  3512. +      FS = ", \t"
  3513. + 
  3514. + makes every area of an input line that consists of a comma followed by a
  3515. + space and a tab, into a field separator.  (`\t' stands for a tab.)
  3516. + 
  3517. +    For a less trivial example of a regular expression, suppose you want
  3518. + single spaces to separate fields the way single commas were used above.
  3519. + You can set `FS' to `"[ ]"'.  This regular expression matches a single
  3520. + space and nothing else.
  3521. + 
  3522. +    `FS' can be set on the command line.  You use the `-F' argument to
  3523. + do so.  For example:
  3524. + 
  3525. +      awk -F, 'PROGRAM' INPUT-FILES
  3526. + 
  3527. + sets `FS' to be the `,' character.  Notice that the argument uses a
  3528. + capital `F'.  Contrast this with `-f', which specifies a file
  3529. + containing an `awk' program.  Case is significant in command options:
  3530. + the `-F' and `-f' options have nothing to do with each other.  You can
  3531. + use both options at the same time to set the `FS' argument *and* get an
  3532. + `awk' program from a file.
  3533. + 
  3534. +    The value used for the argument to `-F' is processed in exactly the
  3535. + same way as assignments to the built-in variable `FS'.  This means that
  3536. + if the field separator contains special characters, they must be escaped
  3537. + appropriately.  For example, to use a `\' as the field separator, you
  3538. + would have to type:
  3539. + 
  3540. +      # same as FS = "\\"
  3541. +      awk -F\\\\ '...' files ...
  3542. + 
  3543. + Since `\' is used for quoting in the shell, `awk' will see `-F\\'.
  3544. + Then `awk' processes the `\\' for escape characters (*note Constant
  3545. + Expressions: Constants.), finally yielding a single `\' to be used for
  3546. + the field separator.
  3547. + 
  3548. +    As a special case, in compatibility mode (*note Invoking `awk':
  3549. + Command Line.), if the argument to `-F' is `t', then `FS' is set to the
  3550. + tab character.  (This is because if you type `-F\t', without the quotes,
  3551. + at the shell, the `\' gets deleted, so `awk' figures that you really
  3552. + want your fields to be separated with tabs, and not `t's.  Use `-v
  3553. + FS="t"' on the command line if you really do want to separate your
  3554. + fields with `t's.)
  3555. + 
  3556. +    For example, let's use an `awk' program file called `baud.awk' that
  3557. + contains the pattern `/300/', and the action `print $1'.  Here is the
  3558. + program:
  3559. + 
  3560. +      /300/   { print $1 }
  3561. + 
  3562. +    Let's also set `FS' to be the `-' character, and run the program on
  3563. + the file `BBS-list'.  The following command prints a list of the names
  3564. + of the bulletin boards that operate at 300 baud and the first three
  3565. + digits of their phone numbers:
  3566. + 
  3567. +      awk -F- -f baud.awk BBS-list
  3568. + 
  3569. + It produces this output:
  3570. + 
  3571. +      aardvark     555
  3572. +      alpo
  3573. +      barfly       555
  3574. +      bites        555
  3575. +      camelot      555
  3576. +      core         555
  3577. +      fooey        555
  3578. +      foot         555
  3579. +      macfoo       555
  3580. +      sdace        555
  3581. +      sabafoo      555
  3582. + 
  3583. + Note the second line of output.  If you check the original file, you
  3584. + will see that the second line looked like this:
  3585. + 
  3586. +      alpo-net     555-3412     2400/1200/300     A
  3587. + 
  3588. +    The `-' as part of the system's name was used as the field
  3589. + separator, instead of the `-' in the phone number that was originally
  3590. + intended.  This demonstrates why you have to be careful in choosing
  3591. + your field and record separators.
  3592. + 
  3593. +    The following program searches the system password file, and prints
  3594. + the entries for users who have no password:
  3595. + 
  3596. +      awk -F: '$2 == ""' /etc/passwd
  3597. + 
  3598. + Here we use the `-F' option on the command line to set the field
  3599. + separator.  Note that fields in `/etc/passwd' are separated by colons.
  3600. + The second field represents a user's encrypted password, but if the
  3601. + field is empty, that user has no password.
  3602. + 
  3603. +    According to the POSIX standard, `awk' is supposed to behave as if
  3604. + each record is split into fields at the time that it is read.  In
  3605. + particular, this means that you can change the value of `FS' after a
  3606. + record is read, but before any of the fields are referenced.  The value
  3607. + of the fields (i.e. how they were split) should reflect the old value
  3608. + of `FS', not the new one.
  3609. + 
  3610. +    However, many implementations of `awk' do not do this.  Instead,
  3611. + they defer splitting the fields until a field reference actually
  3612. + happens, using the *current* value of `FS'!  This behavior can be
  3613. + difficult to diagnose. The following example illustrates the results of
  3614. + the two methods.  (The `sed' command prints just the first line of
  3615. + `/etc/passwd'.)
  3616. + 
  3617. +      sed 1q /etc/passwd | awk '{ FS = ":" ; print $1 }'
  3618. + 
  3619. + will usually print
  3620. + 
  3621. +      root
  3622. + 
  3623. + on an incorrect implementation of `awk', while `gawk' will print
  3624. + something like
  3625. + 
  3626. +      root:nSijPlPhZZwgE:0:0:Root:/:
  3627. + 
  3628. +    There is an important difference between the two cases of `FS = " "'
  3629. + (a single blank) and `FS = "[ \t]+"' (which is a regular expression
  3630. + matching one or more blanks or tabs).  For both values of `FS', fields
  3631. + are separated by runs of blanks and/or tabs.  However, when the value of
  3632. + `FS' is `" "', `awk' will strip leading and trailing whitespace from
  3633. + the record, and then decide where the fields are.
  3634. + 
  3635. +    For example, the following expression prints `b':
  3636. + 
  3637. +      echo ' a b c d ' | awk '{ print $2 }'
  3638. + 
  3639. + However, the following prints `a':
  3640. + 
  3641. +      echo ' a b c d ' | awk 'BEGIN { FS = "[ \t]+" } ; { print $2 }'
  3642. + 
  3643. + In this case, the first field is null.
  3644. + 
  3645. +    The stripping of leading and trailing whitespace also comes into
  3646. + play whenever `$0' is recomputed.  For instance, this pipeline
  3647. + 
  3648. +      echo '   a b c d' | awk '{ print; $2 = $2; print }'
  3649. + 
  3650. + produces this output:
  3651. + 
  3652. +         a b c d
  3653. +      a b c d
  3654. + 
  3655. + The first `print' statement prints the record as it was read, with
  3656. + leading whitespace intact.  The assignment to `$2' rebuilds `$0' by
  3657. + concatenating `$1' through `$NF' together, separated by the value of
  3658. + `OFS'.  Since the leading whitespace was ignored when finding `$1', it
  3659. + is not part of the new `$0'.  Finally, the last `print' statement
  3660. + prints the new `$0'.
  3661. + 
  3662. +    The following table summarizes how fields are split, based on the
  3663. + value of `FS'.
  3664. + 
  3665. + `FS == " "'
  3666. +      Fields are separated by runs of whitespace.  Leading and trailing
  3667. +      whitespace are ignored.  This is the default.
  3668. + 
  3669. + `FS == ANY SINGLE CHARACTER'
  3670. +      Fields are separated by each occurrence of the character.  Multiple
  3671. +      successive occurrences delimit empty fields, as do leading and
  3672. +      trailing occurrences.
  3673. + 
  3674. + `FS == REGEXP'
  3675. +      Fields are separated by occurrences of characters that match
  3676. +      REGEXP.  Leading and trailing matches of REGEXP delimit empty
  3677. +      fields.
  3678. + 
  3679. + 
  3680. + File: gawk.info,  Node: Constant Size,  Next: Multiple Line,  Prev: Field Separators,  Up: Reading Files
  3681. + 
  3682. + Reading Fixed-width Data
  3683. + ========================
  3684. + 
  3685. +    (This section discusses an advanced, experimental feature.  If you
  3686. + are a novice `awk' user, you may wish to skip it on the first reading.)
  3687. + 
  3688. +    `gawk' 2.13 introduced a new facility for dealing with fixed-width
  3689. + fields with no distinctive field separator.  Data of this nature arises
  3690. + typically in one of at least two ways:  the input for old FORTRAN
  3691. + programs where numbers are run together, and the output of programs
  3692. + that did not anticipate the use of their output as input for other
  3693. + programs.
  3694. + 
  3695. +    An example of the latter is a table where all the columns are lined
  3696. + up by the use of a variable number of spaces and *empty fields are just
  3697. + spaces*.  Clearly, `awk''s normal field splitting based on `FS' will
  3698. + not work well in this case.  (Although a portable `awk' program can use
  3699. + a series of `substr' calls on `$0', this is awkward and inefficient for
  3700. + a large number of fields.)
  3701. + 
  3702. +    The splitting of an input record into fixed-width fields is
  3703. + specified by assigning a string containing space-separated numbers to
  3704. + the built-in variable `FIELDWIDTHS'.  Each number specifies the width
  3705. + of the field *including* columns between fields.  If you want to ignore
  3706. + the columns between fields, you can specify the width as a separate
  3707. + field that is subsequently ignored.
  3708. + 
  3709. +    The following data is the output of the `w' utility.  It is useful
  3710. + to illustrate the use of `FIELDWIDTHS'.
  3711. + 
  3712. +       10:06pm  up 21 days, 14:04,  23 users
  3713. +      User     tty       login  idle   JCPU   PCPU  what
  3714. +      hzuo     ttyV0     8:58pm            9      5  vi p24.tex
  3715. +      hzang    ttyV3     6:37pm    50                -csh
  3716. +      eklye    ttyV5     9:53pm            7      1  em thes.tex
  3717. +      dportein ttyV6     8:17pm  1:47                -csh
  3718. +      gierd    ttyD3    10:00pm     1                elm
  3719. +      dave     ttyD4     9:47pm            4      4  w
  3720. +      brent    ttyp0    26Jun91  4:46  26:46   4:41  bash
  3721. +      dave     ttyq4    26Jun9115days     46     46  wnewmail
  3722. + 
  3723. +    The following program takes the above input, converts the idle time
  3724. + to number of seconds and prints out the first two fields and the
  3725. + calculated idle time.  (This program uses a number of `awk' features
  3726. + that haven't been introduced yet.)
  3727. + 
  3728. +      BEGIN  { FIELDWIDTHS = "9 6 10 6 7 7 35" }
  3729. +      NR > 2 {
  3730. +          idle = $4
  3731. +          sub(/^  */, "", idle)   # strip leading spaces
  3732. +          if (idle == "") idle = 0
  3733. +          if (idle ~ /:/) { split(idle, t, ":"); idle = t[1] * 60 + t[2] }
  3734. +          if (idle ~ /days/) { idle *= 24 * 60 * 60 }
  3735. +      
  3736. +          print $1, $2, idle
  3737. +      }
  3738. + 
  3739. +    Here is the result of running the program on the data:
  3740. + 
  3741. +      hzuo      ttyV0  0
  3742. +      hzang     ttyV3  50
  3743. +      eklye     ttyV5  0
  3744. +      dportein  ttyV6  107
  3745. +      gierd     ttyD3  1
  3746. +      dave      ttyD4  0
  3747. +      brent     ttyp0  286
  3748. +      dave      ttyq4  1296000
  3749. + 
  3750. +    Another (possibly more practical) example of fixed-width input data
  3751. + would be the input from a deck of balloting cards.  In some parts of
  3752. + the United States, voters make their choices by punching holes in
  3753. + computer cards.  These cards are then processed to count the votes for
  3754. + any particular candidate or on any particular issue.  Since a voter may
  3755. + choose not to vote on some issue, any column on the card may be empty.
  3756. + An `awk' program for processing such data could use the `FIELDWIDTHS'
  3757. + feature to simplify reading the data.
  3758. + 
  3759. +    This feature is still experimental, and will likely evolve over time.
  3760. + 
  3761. + 
  3762. + File: gawk.info,  Node: Multiple Line,  Next: Getline,  Prev: Constant Size,  Up: Reading Files
  3763. + 
  3764. + Multiple-Line Records
  3765. + =====================
  3766. + 
  3767. +    In some data bases, a single line cannot conveniently hold all the
  3768. + information in one entry.  In such cases, you can use multi-line
  3769. + records.
  3770. + 
  3771. +    The first step in doing this is to choose your data format: when
  3772. + records are not defined as single lines, how do you want to define them?
  3773. + What should separate records?
  3774. + 
  3775. +    One technique is to use an unusual character or string to separate
  3776. + records.  For example, you could use the formfeed character (written
  3777. + `\f' in `awk', as in C) to separate them, making each record a page of
  3778. + the file.  To do this, just set the variable `RS' to `"\f"' (a string
  3779. + containing the formfeed character).  Any other character could equally
  3780. + well be used, as long as it won't be part of the data in a record.
  3781. + 
  3782. +    Another technique is to have blank lines separate records.  By a
  3783. + special dispensation, a null string as the value of `RS' indicates that
  3784. + records are separated by one or more blank lines.  If you set `RS' to
  3785. + the null string, a record always ends at the first blank line
  3786. + encountered.  And the next record doesn't start until the first nonblank
  3787. + line that follows--no matter how many blank lines appear in a row, they
  3788. + are considered one record-separator. (End of file is also considered a
  3789. + record separator.)
  3790. + 
  3791. +    The second step is to separate the fields in the record.  One way to
  3792. + do this is to put each field on a separate line: to do this, just set
  3793. + the variable `FS' to the string `"\n"'.  (This simple regular
  3794. + expression matches a single newline.)
  3795. + 
  3796. +    Another way to separate fields is to divide each of the lines into
  3797. + fields in the normal manner.  This happens by default as a result of a
  3798. + special feature: when `RS' is set to the null string, the newline
  3799. + character *always* acts as a field separator.  This is in addition to
  3800. + whatever field separations result from `FS'.
  3801. + 
  3802. +    The original motivation for this special exception was probably so
  3803. + that you get useful behavior in the default case (i.e., `FS == " "').
  3804. + This feature can be a problem if you really don't want the newline
  3805. + character to separate fields, since there is no way to prevent it.
  3806. + However, you can work around this by using the `split' function to
  3807. + break up the record manually (*note Built-in Functions for String
  3808. + Manipulation: String Functions.).
  3809. + 
  3810. + 
  3811. + File: gawk.info,  Node: Getline,  Next: Close Input,  Prev: Multiple Line,  Up: Reading Files
  3812. + 
  3813. + Explicit Input with `getline'
  3814. + =============================
  3815. + 
  3816. +    So far we have been getting our input files from `awk''s main input
  3817. + stream--either the standard input (usually your terminal) or the files
  3818. + specified on the command line.  The `awk' language has a special
  3819. + built-in command called `getline' that can be used to read input under
  3820. + your explicit control.
  3821. + 
  3822. +    This command is quite complex and should *not* be used by beginners.
  3823. + It is covered here because this is the chapter on input.  The examples
  3824. + that follow the explanation of the `getline' command include material
  3825. + that has not been covered yet.  Therefore, come back and study the
  3826. + `getline' command *after* you have reviewed the rest of this manual and
  3827. + have a good knowledge of how `awk' works.
  3828. + 
  3829. +    `getline' returns 1 if it finds a record, and 0 if the end of the
  3830. + file is encountered.  If there is some error in getting a record, such
  3831. + as a file that cannot be opened, then `getline' returns -1.  In this
  3832. + case, `gawk' sets the variable `ERRNO' to a string describing the error
  3833. + that occurred.
  3834. + 
  3835. +    In the following examples, COMMAND stands for a string value that
  3836. + represents a shell command.
  3837. + 
  3838. + `getline'
  3839. +      The `getline' command can be used without arguments to read input
  3840. +      from the current input file.  All it does in this case is read the
  3841. +      next input record and split it up into fields.  This is useful if
  3842. +      you've finished processing the current record, but you want to do
  3843. +      some special processing *right now* on the next record.  Here's an
  3844. +      example:
  3845. + 
  3846. +           awk '{
  3847. +                if (t = index($0, "/*")) {
  3848. +                     if (t > 1)
  3849. +                          tmp = substr($0, 1, t - 1)
  3850. +                     else
  3851. +                          tmp = ""
  3852. +                     u = index(substr($0, t + 2), "*/")
  3853. +                     while (u == 0) {
  3854. +                          getline
  3855. +                          t = -1
  3856. +                          u = index($0, "*/")
  3857. +                     }
  3858. +                     if (u <= length($0) - 2)
  3859. +                          $0 = tmp substr($0, t + u + 3)
  3860. +                     else
  3861. +                          $0 = tmp
  3862. +                }
  3863. +                print $0
  3864. +           }'
  3865. + 
  3866. +      This `awk' program deletes all C-style comments, `/* ...  */',
  3867. +      from the input.  By replacing the `print $0' with other
  3868. +      statements, you could perform more complicated processing on the
  3869. +      decommented input, like searching for matches of a regular
  3870. +      expression.  (This program has a subtle problem--can you spot it?)
  3871. + 
  3872. +      This form of the `getline' command sets `NF' (the number of
  3873. +      fields; *note Examining Fields: Fields.), `NR' (the number of
  3874. +      records read so far; *note How Input is Split into Records:
  3875. +      Records.), `FNR' (the number of records read from this input
  3876. +      file), and the value of `$0'.
  3877. + 
  3878. +      *Note:* the new value of `$0' is used in testing the patterns of
  3879. +      any subsequent rules.  The original value of `$0' that triggered
  3880. +      the rule which executed `getline' is lost.  By contrast, the
  3881. +      `next' statement reads a new record but immediately begins
  3882. +      processing it normally, starting with the first rule in the
  3883. +      program.  *Note The `next' Statement: Next Statement.
  3884. + 
  3885. + `getline VAR'
  3886. +      This form of `getline' reads a record into the variable VAR.  This
  3887. +      is useful when you want your program to read the next record from
  3888. +      the current input file, but you don't want to subject the record
  3889. +      to the normal input processing.
  3890. + 
  3891. +      For example, suppose the next line is a comment, or a special
  3892. +      string, and you want to read it, but you must make certain that it
  3893. +      won't trigger any rules.  This version of `getline' allows you to
  3894. +      read that line and store it in a variable so that the main
  3895. +      read-a-line-and-check-each-rule loop of `awk' never sees it.
  3896. + 
  3897. +      The following example swaps every two lines of input.  For
  3898. +      example, given:
  3899. + 
  3900. +           wan
  3901. +           tew
  3902. +           free
  3903. +           phore
  3904. + 
  3905. +      it outputs:
  3906. + 
  3907. +           tew
  3908. +           wan
  3909. +           phore
  3910. +           free
  3911. + 
  3912. +      Here's the program:
  3913. + 
  3914. +           awk '{
  3915. +                if ((getline tmp) > 0) {
  3916. +                     print tmp
  3917. +                     print $0
  3918. +                } else
  3919. +                     print $0
  3920. +           }'
  3921. + 
  3922. +      The `getline' function used in this way sets only the variables
  3923. +      `NR' and `FNR' (and of course, VAR).  The record is not split into
  3924. +      fields, so the values of the fields (including `$0') and the value
  3925. +      of `NF' do not change.
  3926. + 
  3927. + `getline < FILE'
  3928. +      This form of the `getline' function takes its input from the file
  3929. +      FILE.  Here FILE is a string-valued expression that specifies the
  3930. +      file name.  `< FILE' is called a "redirection" since it directs
  3931. +      input to come from a different place.
  3932. + 
  3933. +      This form is useful if you want to read your input from a
  3934. +      particular file, instead of from the main input stream.  For
  3935. +      example, the following program reads its input record from the
  3936. +      file `foo.input' when it encounters a first field with a value
  3937. +      equal to 10 in the current input file.
  3938. + 
  3939. +           awk '{
  3940. +               if ($1 == 10) {
  3941. +                    getline < "foo.input"
  3942. +                    print
  3943. +               } else
  3944. +                    print
  3945. +           }'
  3946. + 
  3947. +      Since the main input stream is not used, the values of `NR' and
  3948. +      `FNR' are not changed.  But the record read is split into fields in
  3949. +      the normal manner, so the values of `$0' and other fields are
  3950. +      changed.  So is the value of `NF'.
  3951. + 
  3952. +      This does not cause the record to be tested against all the
  3953. +      patterns in the `awk' program, in the way that would happen if the
  3954. +      record were read normally by the main processing loop of `awk'.
  3955. +      However the new record is tested against any subsequent rules,
  3956. +      just as when `getline' is used without a redirection.
  3957. + 
  3958. + `getline VAR < FILE'
  3959. +      This form of the `getline' function takes its input from the file
  3960. +      FILE and puts it in the variable VAR.  As above, FILE is a
  3961. +      string-valued expression that specifies the file from which to
  3962. +      read.
  3963. + 
  3964. +      In this version of `getline', none of the built-in variables are
  3965. +      changed, and the record is not split into fields.  The only
  3966. +      variable changed is VAR.
  3967. + 
  3968. +      For example, the following program copies all the input files to
  3969. +      the output, except for records that say `@include FILENAME'.  Such
  3970. +      a record is replaced by the contents of the file FILENAME.
  3971. + 
  3972. +           awk '{
  3973. +                if (NF == 2 && $1 == "@include") {
  3974. +                     while ((getline line < $2) > 0)
  3975. +                          print line
  3976. +                     close($2)
  3977. +                } else
  3978. +                     print
  3979. +           }'
  3980. + 
  3981. +      Note here how the name of the extra input file is not built into
  3982. +      the program; it is taken from the data, from the second field on
  3983. +      the `@include' line.
  3984. + 
  3985. +      The `close' function is called to ensure that if two identical
  3986. +      `@include' lines appear in the input, the entire specified file is
  3987. +      included twice.  *Note Closing Input Files and Pipes: Close Input.
  3988. + 
  3989. +      One deficiency of this program is that it does not process nested
  3990. +      `@include' statements the way a true macro preprocessor would.
  3991. + 
  3992. + `COMMAND | getline'
  3993. +      You can "pipe" the output of a command into `getline'.  A pipe is
  3994. +      simply a way to link the output of one program to the input of
  3995. +      another.  In this case, the string COMMAND is run as a shell
  3996. +      command and its output is piped into `awk' to be used as input.
  3997. +      This form of `getline' reads one record from the pipe.
  3998. + 
  3999. +      For example, the following program copies input to output, except
  4000. +      for lines that begin with `@execute', which are replaced by the
  4001. +      output produced by running the rest of the line as a shell command:
  4002. + 
  4003. +           awk '{
  4004. +                if ($1 == "@execute") {
  4005. +                     tmp = substr($0, 10)
  4006. +                     while ((tmp | getline) > 0)
  4007. +                          print
  4008. +                     close(tmp)
  4009. +                } else
  4010. +                     print
  4011. +           }'
  4012. + 
  4013. +      The `close' function is called to ensure that if two identical
  4014. +      `@execute' lines appear in the input, the command is run for each
  4015. +      one.  *Note Closing Input Files and Pipes: Close Input.
  4016. + 
  4017. +      Given the input:
  4018. + 
  4019. +           foo
  4020. +           bar
  4021. +           baz
  4022. +           @execute who
  4023. +           bletch
  4024. + 
  4025. +      the program might produce:
  4026. + 
  4027. +           foo
  4028. +           bar
  4029. +           baz
  4030. +           hack     ttyv0   Jul 13 14:22
  4031. +           hack     ttyp0   Jul 13 14:23     (gnu:0)
  4032. +           hack     ttyp1   Jul 13 14:23     (gnu:0)
  4033. +           hack     ttyp2   Jul 13 14:23     (gnu:0)
  4034. +           hack     ttyp3   Jul 13 14:23     (gnu:0)
  4035. +           bletch
  4036. + 
  4037. +      Notice that this program ran the command `who' and printed the
  4038. +      result.  (If you try this program yourself, you will get different
  4039. +      results, showing you who is logged in on your system.)
  4040. + 
  4041. +      This variation of `getline' splits the record into fields, sets the
  4042. +      value of `NF' and recomputes the value of `$0'.  The values of
  4043. +      `NR' and `FNR' are not changed.
  4044. + 
  4045. + `COMMAND | getline VAR'
  4046. +      The output of the command COMMAND is sent through a pipe to
  4047. +      `getline' and into the variable VAR.  For example, the following
  4048. +      program reads the current date and time into the variable
  4049. +      `current_time', using the `date' utility, and then prints it.
  4050. + 
  4051. +           awk 'BEGIN {
  4052. +                "date" | getline current_time
  4053. +                close("date")
  4054. +                print "Report printed on " current_time
  4055. +           }'
  4056. + 
  4057. +      In this version of `getline', none of the built-in variables are
  4058. +      changed, and the record is not split into fields.
  4059. + 
  4060. + 
  4061. + File: gawk.info,  Node: Close Input,  Prev: Getline,  Up: Reading Files
  4062. + 
  4063. + Closing Input Files and Pipes
  4064. + =============================
  4065. + 
  4066. +    If the same file name or the same shell command is used with
  4067. + `getline' more than once during the execution of an `awk' program, the
  4068. + file is opened (or the command is executed) only the first time.  At
  4069. + that time, the first record of input is read from that file or command.
  4070. + The next time the same file or command is used in `getline', another
  4071. + record is read from it, and so on.
  4072. + 
  4073. +    This implies that if you want to start reading the same file again
  4074. + from the beginning, or if you want to rerun a shell command (rather than
  4075. + reading more output from the command), you must take special steps.
  4076. + What you must do is use the `close' function, as follows:
  4077. + 
  4078. +      close(FILENAME)
  4079. + 
  4080. + or
  4081. + 
  4082. +      close(COMMAND)
  4083. + 
  4084. +    The argument FILENAME or COMMAND can be any expression.  Its value
  4085. + must exactly equal the string that was used to open the file or start
  4086. + the command--for example, if you open a pipe with this:
  4087. + 
  4088. +      "sort -r names" | getline foo
  4089. + 
  4090. + then you must close it with this:
  4091. + 
  4092. +      close("sort -r names")
  4093. + 
  4094. +    Once this function call is executed, the next `getline' from that
  4095. + file or command will reopen the file or rerun the command.
  4096. + 
  4097. +    `close' returns a value of zero if the close succeeded.  Otherwise,
  4098. + the value will be non-zero.  In this case, `gawk' sets the variable
  4099. + `ERRNO' to a string describing the error that occurred.
  4100. + 
  4101. + 
  4102. + File: gawk.info,  Node: Printing,  Next: One-liners,  Prev: Reading Files,  Up: Top
  4103. + 
  4104. + Printing Output
  4105. + ***************
  4106. + 
  4107. +    One of the most common things that actions do is to output or "print"
  4108. + some or all of the input.  For simple output, use the `print'
  4109. + statement.  For fancier formatting use the `printf' statement.  Both
  4110. + are described in this chapter.
  4111. + 
  4112. + * Menu:
  4113. + 
  4114. + * Print::                       The `print' statement.
  4115. + * Print Examples::              Simple examples of `print' statements.
  4116. + * Output Separators::           The output separators and how to change them.
  4117. + * OFMT::                        Controlling Numeric Output With `print'.
  4118. + * Printf::                      The `printf' statement.
  4119. + * Redirection::                 How to redirect output to multiple
  4120. +                                 files and pipes.
  4121. + * Special Files::               File name interpretation in `gawk'.
  4122. +                                 `gawk' allows access to
  4123. +                                 inherited file descriptors.
  4124. + 
  4125. + 
  4126. + File: gawk.info,  Node: Print,  Next: Print Examples,  Prev: Printing,  Up: Printing
  4127. + 
  4128. + The `print' Statement
  4129. + =====================
  4130. + 
  4131. +    The `print' statement does output with simple, standardized
  4132. + formatting.  You specify only the strings or numbers to be printed, in a
  4133. + list separated by commas.  They are output, separated by single spaces,
  4134. + followed by a newline.  The statement looks like this:
  4135. + 
  4136. +      print ITEM1, ITEM2, ...
  4137. + 
  4138. + The entire list of items may optionally be enclosed in parentheses.  The
  4139. + parentheses are necessary if any of the item expressions uses a
  4140. + relational operator; otherwise it could be confused with a redirection
  4141. + (*note Redirecting Output of `print' and `printf': Redirection.).  The
  4142. + relational operators are `==', `!=', `<', `>', `>=', `<=', `~' and `!~'
  4143. + (*note Comparison Expressions: Comparison Ops.).
  4144. + 
  4145. +    The items printed can be constant strings or numbers, fields of the
  4146. + current record (such as `$1'), variables, or any `awk' expressions.
  4147. + The `print' statement is completely general for computing *what* values
  4148. + to print.  With two exceptions, you cannot specify *how* to print
  4149. + them--how many columns, whether to use exponential notation or not, and
  4150. + so on.  (*Note Output Separators::, and *Note Controlling Numeric
  4151. + Output with `print': OFMT.) For that, you need the `printf' statement
  4152. + (*note Using `printf' Statements for Fancier Printing: Printf.).
  4153. + 
  4154. +    The simple statement `print' with no items is equivalent to `print
  4155. + $0': it prints the entire current record.  To print a blank line, use
  4156. + `print ""', where `""' is the null, or empty, string.
  4157. + 
  4158. +    To print a fixed piece of text, use a string constant such as
  4159. + `"Hello there"' as one item.  If you forget to use the double-quote
  4160. + characters, your text will be taken as an `awk' expression, and you
  4161. + will probably get an error.  Keep in mind that a space is printed
  4162. + between any two items.
  4163. + 
  4164. +    Most often, each `print' statement makes one line of output.  But it
  4165. + isn't limited to one line.  If an item value is a string that contains a
  4166. + newline, the newline is output along with the rest of the string.  A
  4167. + single `print' can make any number of lines this way.
  4168. + 
  4169. + 
  4170. + File: gawk.info,  Node: Print Examples,  Next: Output Separators,  Prev: Print,  Up: Printing
  4171. + 
  4172. + Examples of `print' Statements
  4173. + ==============================
  4174. + 
  4175. +    Here is an example of printing a string that contains embedded
  4176. + newlines:
  4177. + 
  4178. +      awk 'BEGIN { print "line one\nline two\nline three" }'
  4179. + 
  4180. + produces output like this:
  4181. + 
  4182. +      line one
  4183. +      line two
  4184. +      line three
  4185. + 
  4186. +    Here is an example that prints the first two fields of each input
  4187. + record, with a space between them:
  4188. + 
  4189. +      awk '{ print $1, $2 }' inventory-shipped
  4190. + 
  4191. + Its output looks like this:
  4192. + 
  4193. +      Jan 13
  4194. +      Feb 15
  4195. +      Mar 15
  4196. +      ...
  4197. + 
  4198. +    A common mistake in using the `print' statement is to omit the comma
  4199. + between two items.  This often has the effect of making the items run
  4200. + together in the output, with no space.  The reason for this is that
  4201. + juxtaposing two string expressions in `awk' means to concatenate them.
  4202. + For example, without the comma:
  4203. + 
  4204. +      awk '{ print $1 $2 }' inventory-shipped
  4205. + 
  4206. + prints:
  4207. + 
  4208. +      Jan13
  4209. +      Feb15
  4210. +      Mar15
  4211. +      ...
  4212. + 
  4213. +    Neither example's output makes much sense to someone unfamiliar with
  4214. + the file `inventory-shipped'.  A heading line at the beginning would
  4215. + make it clearer.  Let's add some headings to our table of months (`$1')
  4216. + and green crates shipped (`$2').  We do this using the `BEGIN' pattern
  4217. + (*note `BEGIN' and `END' Special Patterns: BEGIN/END.) to force the
  4218. + headings to be printed only once:
  4219. + 
  4220. +      awk 'BEGIN {  print "Month Crates"
  4221. +                    print "----- ------" }
  4222. +                 {  print $1, $2 }' inventory-shipped
  4223. + 
  4224. + Did you already guess what happens?  This program prints the following:
  4225. + 
  4226. +      Month Crates
  4227. +      ----- ------
  4228. +      Jan 13
  4229. +      Feb 15
  4230. +      Mar 15
  4231. +      ...
  4232. + 
  4233. + The headings and the table data don't line up!  We can fix this by
  4234. + printing some spaces between the two fields:
  4235. + 
  4236. +      awk 'BEGIN { print "Month Crates"
  4237. +                   print "----- ------" }
  4238. +                 { print $1, "     ", $2 }' inventory-shipped
  4239. + 
  4240. +    You can imagine that this way of lining up columns can get pretty
  4241. + complicated when you have many columns to fix.  Counting spaces for two
  4242. + or three columns can be simple, but more than this and you can get
  4243. + "lost" quite easily.  This is why the `printf' statement was created
  4244. + (*note Using `printf' Statements for Fancier Printing: Printf.); one of
  4245. + its specialties is lining up columns of data.
  4246. + 
  4247. diff -rc --new-file /src/baseline/gawk-2.15.5/gawk.info-3 gawk-2.15.5/gawk.info-3
  4248. *** /src/baseline/gawk-2.15.5/gawk.info-3    Thu Jan  1 00:00:00 1970
  4249. --- gawk-2.15.5/gawk.info-3    Sun Jun 12 22:28:50 1994
  4250. ***************
  4251. *** 0 ****
  4252. --- 1,1288 ----
  4253. + This is Info file gawk.info, produced by Makeinfo-1.55 from the input
  4254. + file /gnu/src/amiga/gawk-2.15.5/gawk.texi.
  4255. + 
  4256. +    This file documents `awk', a program that you can use to select
  4257. + particular records in a file and perform operations upon them.
  4258. + 
  4259. +    This is Edition 0.15 of `The GAWK Manual',
  4260. + for the 2.15 version of the GNU implementation
  4261. + of AWK.
  4262. + 
  4263. +    Copyright (C) 1989, 1991, 1992, 1993 Free Software Foundation, Inc.
  4264. + 
  4265. +    Permission is granted to make and distribute verbatim copies of this
  4266. + manual provided the copyright notice and this permission notice are
  4267. + preserved on all copies.
  4268. + 
  4269. +    Permission is granted to copy and distribute modified versions of
  4270. + this manual under the conditions for verbatim copying, provided that
  4271. + the entire resulting derived work is distributed under the terms of a
  4272. + permission notice identical to this one.
  4273. + 
  4274. +    Permission is granted to copy and distribute translations of this
  4275. + manual into another language, under the above conditions for modified
  4276. + versions, except that this permission notice may be stated in a
  4277. + translation approved by the Foundation.
  4278. + 
  4279. + 
  4280. + File: gawk.info,  Node: Output Separators,  Next: OFMT,  Prev: Print Examples,  Up: Printing
  4281. + 
  4282. + Output Separators
  4283. + =================
  4284. + 
  4285. +    As mentioned previously, a `print' statement contains a list of
  4286. + items, separated by commas.  In the output, the items are normally
  4287. + separated by single spaces.  But they do not have to be spaces; a
  4288. + single space is only the default.  You can specify any string of
  4289. + characters to use as the "output field separator" by setting the
  4290. + built-in variable `OFS'.  The initial value of this variable is the
  4291. + string `" "', that is, just a single space.
  4292. + 
  4293. +    The output from an entire `print' statement is called an "output
  4294. + record".  Each `print' statement outputs one output record and then
  4295. + outputs a string called the "output record separator".  The built-in
  4296. + variable `ORS' specifies this string.  The initial value of the
  4297. + variable is the string `"\n"' containing a newline character; thus,
  4298. + normally each `print' statement makes a separate line.
  4299. + 
  4300. +    You can change how output fields and records are separated by
  4301. + assigning new values to the variables `OFS' and/or `ORS'.  The usual
  4302. + place to do this is in the `BEGIN' rule (*note `BEGIN' and `END'
  4303. + Special Patterns: BEGIN/END.), so that it happens before any input is
  4304. + processed.  You may also do this with assignments on the command line,
  4305. + before the names of your input files.
  4306. + 
  4307. +    The following example prints the first and second fields of each
  4308. + input record separated by a semicolon, with a blank line added after
  4309. + each line:
  4310. + 
  4311. +      awk 'BEGIN { OFS = ";"; ORS = "\n\n" }
  4312. +                 { print $1, $2 }'  BBS-list
  4313. + 
  4314. +    If the value of `ORS' does not contain a newline, all your output
  4315. + will be run together on a single line, unless you output newlines some
  4316. + other way.
  4317. + 
  4318. + 
  4319. + File: gawk.info,  Node: OFMT,  Next: Printf,  Prev: Output Separators,  Up: Printing
  4320. + 
  4321. + Controlling Numeric Output with `print'
  4322. + =======================================
  4323. + 
  4324. +    When you use the `print' statement to print numeric values, `awk'
  4325. + internally converts the number to a string of characters, and prints
  4326. + that string.  `awk' uses the `sprintf' function to do this conversion.
  4327. + For now, it suffices to say that the `sprintf' function accepts a
  4328. + "format specification" that tells it how to format numbers (or
  4329. + strings), and that there are a number of different ways that numbers
  4330. + can be formatted.  The different format specifications are discussed
  4331. + more fully in *Note Using `printf' Statements for Fancier Printing:
  4332. + Printf.
  4333. + 
  4334. +    The built-in variable `OFMT' contains the default format
  4335. + specification that `print' uses with `sprintf' when it wants to convert
  4336. + a number to a string for printing.  By supplying different format
  4337. + specifications as the value of `OFMT', you can change how `print' will
  4338. + print your numbers.  As a brief example:
  4339. + 
  4340. +      awk 'BEGIN { OFMT = "%d"  # print numbers as integers
  4341. +                   print 17.23 }'
  4342. + 
  4343. + will print `17'.
  4344. + 
  4345. + 
  4346. + File: gawk.info,  Node: Printf,  Next: Redirection,  Prev: OFMT,  Up: Printing
  4347. + 
  4348. + Using `printf' Statements for Fancier Printing
  4349. + ==============================================
  4350. + 
  4351. +    If you want more precise control over the output format than `print'
  4352. + gives you, use `printf'.  With `printf' you can specify the width to
  4353. + use for each item, and you can specify various stylistic choices for
  4354. + numbers (such as what radix to use, whether to print an exponent,
  4355. + whether to print a sign, and how many digits to print after the decimal
  4356. + point).  You do this by specifying a string, called the "format
  4357. + string", which controls how and where to print the other arguments.
  4358. + 
  4359. + * Menu:
  4360. + 
  4361. + * Basic Printf::                Syntax of the `printf' statement.
  4362. + * Control Letters::             Format-control letters.
  4363. + * Format Modifiers::            Format-specification modifiers.
  4364. + * Printf Examples::             Several examples.
  4365. + 
  4366. + 
  4367. + File: gawk.info,  Node: Basic Printf,  Next: Control Letters,  Prev: Printf,  Up: Printf
  4368. + 
  4369. + Introduction to the `printf' Statement
  4370. + --------------------------------------
  4371. + 
  4372. +    The `printf' statement looks like this:
  4373. + 
  4374. +      printf FORMAT, ITEM1, ITEM2, ...
  4375. + 
  4376. + The entire list of arguments may optionally be enclosed in parentheses.
  4377. + The parentheses are necessary if any of the item expressions uses a
  4378. + relational operator; otherwise it could be confused with a redirection
  4379. + (*note Redirecting Output of `print' and `printf': Redirection.).  The
  4380. + relational operators are `==', `!=', `<', `>', `>=', `<=', `~' and `!~'
  4381. + (*note Comparison Expressions: Comparison Ops.).
  4382. + 
  4383. +    The difference between `printf' and `print' is the argument FORMAT.
  4384. + This is an expression whose value is taken as a string; it specifies
  4385. + how to output each of the other arguments.  It is called the "format
  4386. + string".
  4387. + 
  4388. +    The format string is the same as in the ANSI C library function
  4389. + `printf'.  Most of FORMAT is text to be output verbatim.  Scattered
  4390. + among this text are "format specifiers", one per item.  Each format
  4391. + specifier says to output the next item at that place in the format.
  4392. + 
  4393. +    The `printf' statement does not automatically append a newline to its
  4394. + output.  It outputs only what the format specifies.  So if you want a
  4395. + newline, you must include one in the format.  The output separator
  4396. + variables `OFS' and `ORS' have no effect on `printf' statements.
  4397. + 
  4398. + 
  4399. + File: gawk.info,  Node: Control Letters,  Next: Format Modifiers,  Prev: Basic Printf,  Up: Printf
  4400. + 
  4401. + Format-Control Letters
  4402. + ----------------------
  4403. + 
  4404. +    A format specifier starts with the character `%' and ends with a
  4405. + "format-control letter"; it tells the `printf' statement how to output
  4406. + one item.  (If you actually want to output a `%', write `%%'.)  The
  4407. + format-control letter specifies what kind of value to print.  The rest
  4408. + of the format specifier is made up of optional "modifiers" which are
  4409. + parameters such as the field width to use.
  4410. + 
  4411. +    Here is a list of the format-control letters:
  4412. + 
  4413. + `c'
  4414. +      This prints a number as an ASCII character.  Thus, `printf "%c",
  4415. +      65' outputs the letter `A'.  The output for a string value is the
  4416. +      first character of the string.
  4417. + 
  4418. + `d'
  4419. +      This prints a decimal integer.
  4420. + 
  4421. + `i'
  4422. +      This also prints a decimal integer.
  4423. + 
  4424. + `e'
  4425. +      This prints a number in scientific (exponential) notation.  For
  4426. +      example,
  4427. + 
  4428. +           printf "%4.3e", 1950
  4429. + 
  4430. +      prints `1.950e+03', with a total of four significant figures of
  4431. +      which three follow the decimal point.  The `4.3' are "modifiers",
  4432. +      discussed below.
  4433. + 
  4434. + `f'
  4435. +      This prints a number in floating point notation.
  4436. + 
  4437. + `g'
  4438. +      This prints a number in either scientific notation or floating
  4439. +      point notation, whichever uses fewer characters.
  4440. + 
  4441. + `o'
  4442. +      This prints an unsigned octal integer.
  4443. + 
  4444. + `s'
  4445. +      This prints a string.
  4446. + 
  4447. + `x'
  4448. +      This prints an unsigned hexadecimal integer.
  4449. + 
  4450. + `X'
  4451. +      This prints an unsigned hexadecimal integer.  However, for the
  4452. +      values 10 through 15, it uses the letters `A' through `F' instead
  4453. +      of `a' through `f'.
  4454. + 
  4455. + `%'
  4456. +      This isn't really a format-control letter, but it does have a
  4457. +      meaning when used after a `%': the sequence `%%' outputs one `%'.
  4458. +      It does not consume an argument.
  4459. + 
  4460. + 
  4461. + File: gawk.info,  Node: Format Modifiers,  Next: Printf Examples,  Prev: Control Letters,  Up: Printf
  4462. + 
  4463. + Modifiers for `printf' Formats
  4464. + ------------------------------
  4465. + 
  4466. +    A format specification can also include "modifiers" that can control
  4467. + how much of the item's value is printed and how much space it gets.  The
  4468. + modifiers come between the `%' and the format-control letter.  Here are
  4469. + the possible modifiers, in the order in which they may appear:
  4470. + 
  4471. + `-'
  4472. +      The minus sign, used before the width modifier, says to
  4473. +      left-justify the argument within its specified width.  Normally
  4474. +      the argument is printed right-justified in the specified width.
  4475. +      Thus,
  4476. + 
  4477. +           printf "%-4s", "foo"
  4478. + 
  4479. +      prints `foo '.
  4480. + 
  4481. + `WIDTH'
  4482. +      This is a number representing the desired width of a field.
  4483. +      Inserting any number between the `%' sign and the format control
  4484. +      character forces the field to be expanded to this width.  The
  4485. +      default way to do this is to pad with spaces on the left.  For
  4486. +      example,
  4487. + 
  4488. +           printf "%4s", "foo"
  4489. + 
  4490. +      prints ` foo'.
  4491. + 
  4492. +      The value of WIDTH is a minimum width, not a maximum.  If the item
  4493. +      value requires more than WIDTH characters, it can be as wide as
  4494. +      necessary.  Thus,
  4495. + 
  4496. +           printf "%4s", "foobar"
  4497. + 
  4498. +      prints `foobar'.
  4499. + 
  4500. +      Preceding the WIDTH with a minus sign causes the output to be
  4501. +      padded with spaces on the right, instead of on the left.
  4502. + 
  4503. + `.PREC'
  4504. +      This is a number that specifies the precision to use when printing.
  4505. +      This specifies the number of digits you want printed to the right
  4506. +      of the decimal point.  For a string, it specifies the maximum
  4507. +      number of characters from the string that should be printed.
  4508. + 
  4509. +    The C library `printf''s dynamic WIDTH and PREC capability (for
  4510. + example, `"%*.*s"') is supported.  Instead of supplying explicit WIDTH
  4511. + and/or PREC values in the format string, you pass them in the argument
  4512. + list.  For example:
  4513. + 
  4514. +      w = 5
  4515. +      p = 3
  4516. +      s = "abcdefg"
  4517. +      printf "<%*.*s>\n", w, p, s
  4518. + 
  4519. + is exactly equivalent to
  4520. + 
  4521. +      s = "abcdefg"
  4522. +      printf "<%5.3s>\n", s
  4523. + 
  4524. + Both programs output `<**abc>'.  (We have used the bullet symbol "*" to
  4525. + represent a space, to clearly show you that there are two spaces in the
  4526. + output.)
  4527. + 
  4528. +    Earlier versions of `awk' did not support this capability.  You may
  4529. + simulate it by using concatenation to build up the format string, like
  4530. + so:
  4531. + 
  4532. +      w = 5
  4533. +      p = 3
  4534. +      s = "abcdefg"
  4535. +      printf "<%" w "." p "s>\n", s
  4536. + 
  4537. + This is not particularly easy to read, however.
  4538. + 
  4539. + 
  4540. + File: gawk.info,  Node: Printf Examples,  Prev: Format Modifiers,  Up: Printf
  4541. + 
  4542. + Examples of Using `printf'
  4543. + --------------------------
  4544. + 
  4545. +    Here is how to use `printf' to make an aligned table:
  4546. + 
  4547. +      awk '{ printf "%-10s %s\n", $1, $2 }' BBS-list
  4548. + 
  4549. + prints the names of bulletin boards (`$1') of the file `BBS-list' as a
  4550. + string of 10 characters, left justified.  It also prints the phone
  4551. + numbers (`$2') afterward on the line.  This produces an aligned
  4552. + two-column table of names and phone numbers:
  4553. + 
  4554. +      aardvark   555-5553
  4555. +      alpo-net   555-3412
  4556. +      barfly     555-7685
  4557. +      bites      555-1675
  4558. +      camelot    555-0542
  4559. +      core       555-2912
  4560. +      fooey      555-1234
  4561. +      foot       555-6699
  4562. +      macfoo     555-6480
  4563. +      sdace      555-3430
  4564. +      sabafoo    555-2127
  4565. + 
  4566. +    Did you notice that we did not specify that the phone numbers be
  4567. + printed as numbers?  They had to be printed as strings because the
  4568. + numbers are separated by a dash.  This dash would be interpreted as a
  4569. + minus sign if we had tried to print the phone numbers as numbers.  This
  4570. + would have led to some pretty confusing results.
  4571. + 
  4572. +    We did not specify a width for the phone numbers because they are the
  4573. + last things on their lines.  We don't need to put spaces after them.
  4574. + 
  4575. +    We could make our table look even nicer by adding headings to the
  4576. + tops of the columns.  To do this, use the `BEGIN' pattern (*note
  4577. + `BEGIN' and `END' Special Patterns: BEGIN/END.) to force the header to
  4578. + be printed only once, at the beginning of the `awk' program:
  4579. + 
  4580. +      awk 'BEGIN { print "Name      Number"
  4581. +                   print "----      ------" }
  4582. +           { printf "%-10s %s\n", $1, $2 }' BBS-list
  4583. + 
  4584. +    Did you notice that we mixed `print' and `printf' statements in the
  4585. + above example?  We could have used just `printf' statements to get the
  4586. + same results:
  4587. + 
  4588. +      awk 'BEGIN { printf "%-10s %s\n", "Name", "Number"
  4589. +                   printf "%-10s %s\n", "----", "------" }
  4590. +           { printf "%-10s %s\n", $1, $2 }' BBS-list
  4591. + 
  4592. + By outputting each column heading with the same format specification
  4593. + used for the elements of the column, we have made sure that the headings
  4594. + are aligned just like the columns.
  4595. + 
  4596. +    The fact that the same format specification is used three times can
  4597. + be emphasized by storing it in a variable, like this:
  4598. + 
  4599. +      awk 'BEGIN { format = "%-10s %s\n"
  4600. +                   printf format, "Name", "Number"
  4601. +                   printf format, "----", "------" }
  4602. +           { printf format, $1, $2 }' BBS-list
  4603. + 
  4604. +    See if you can use the `printf' statement to line up the headings and
  4605. + table data for our `inventory-shipped' example covered earlier in the
  4606. + section on the `print' statement (*note The `print' Statement: Print.).
  4607. + 
  4608. + 
  4609. + File: gawk.info,  Node: Redirection,  Next: Special Files,  Prev: Printf,  Up: Printing
  4610. + 
  4611. + Redirecting Output of `print' and `printf'
  4612. + ==========================================
  4613. + 
  4614. +    So far we have been dealing only with output that prints to the
  4615. + standard output, usually your terminal.  Both `print' and `printf' can
  4616. + also send their output to other places.  This is called "redirection".
  4617. + 
  4618. +    A redirection appears after the `print' or `printf' statement.
  4619. + Redirections in `awk' are written just like redirections in shell
  4620. + commands, except that they are written inside the `awk' program.
  4621. + 
  4622. + * Menu:
  4623. + 
  4624. + * File/Pipe Redirection::       Redirecting Output to Files and Pipes.
  4625. + * Close Output::                How to close output files and pipes.
  4626. + 
  4627. + 
  4628. + File: gawk.info,  Node: File/Pipe Redirection,  Next: Close Output,  Prev: Redirection,  Up: Redirection
  4629. + 
  4630. + Redirecting Output to Files and Pipes
  4631. + -------------------------------------
  4632. + 
  4633. +    Here are the three forms of output redirection.  They are all shown
  4634. + for the `print' statement, but they work identically for `printf' also.
  4635. + 
  4636. + `print ITEMS > OUTPUT-FILE'
  4637. +      This type of redirection prints the items onto the output file
  4638. +      OUTPUT-FILE.  The file name OUTPUT-FILE can be any expression.
  4639. +      Its value is changed to a string and then used as a file name
  4640. +      (*note Expressions as Action Statements: Expressions.).
  4641. + 
  4642. +      When this type of redirection is used, the OUTPUT-FILE is erased
  4643. +      before the first output is written to it.  Subsequent writes do not
  4644. +      erase OUTPUT-FILE, but append to it.  If OUTPUT-FILE does not
  4645. +      exist, then it is created.
  4646. + 
  4647. +      For example, here is how one `awk' program can write a list of BBS
  4648. +      names to a file `name-list' and a list of phone numbers to a file
  4649. +      `phone-list'.  Each output file contains one name or number per
  4650. +      line.
  4651. + 
  4652. +           awk '{ print $2 > "phone-list"
  4653. +                  print $1 > "name-list" }' BBS-list
  4654. + 
  4655. + `print ITEMS >> OUTPUT-FILE'
  4656. +      This type of redirection prints the items onto the output file
  4657. +      OUTPUT-FILE.  The difference between this and the single-`>'
  4658. +      redirection is that the old contents (if any) of OUTPUT-FILE are
  4659. +      not erased.  Instead, the `awk' output is appended to the file.
  4660. + 
  4661. + `print ITEMS | COMMAND'
  4662. +      It is also possible to send output through a "pipe" instead of
  4663. +      into a file.   This type of redirection opens a pipe to COMMAND
  4664. +      and writes the values of ITEMS through this pipe, to another
  4665. +      process created to execute COMMAND.
  4666. + 
  4667. +      The redirection argument COMMAND is actually an `awk' expression.
  4668. +      Its value is converted to a string, whose contents give the shell
  4669. +      command to be run.
  4670. + 
  4671. +      For example, this produces two files, one unsorted list of BBS
  4672. +      names and one list sorted in reverse alphabetical order:
  4673. + 
  4674. +           awk '{ print $1 > "names.unsorted"
  4675. +                  print $1 | "sort -r > names.sorted" }' BBS-list
  4676. + 
  4677. +      Here the unsorted list is written with an ordinary redirection
  4678. +      while the sorted list is written by piping through the `sort'
  4679. +      utility.
  4680. + 
  4681. +      Here is an example that uses redirection to mail a message to a
  4682. +      mailing list `bug-system'.  This might be useful when trouble is
  4683. +      encountered in an `awk' script run periodically for system
  4684. +      maintenance.
  4685. + 
  4686. +           report = "mail bug-system"
  4687. +           print "Awk script failed:", $0 | report
  4688. +           print "at record number", FNR, "of", FILENAME  | report
  4689. +           close(report)
  4690. + 
  4691. +      We call the `close' function here because it's a good idea to close
  4692. +      the pipe as soon as all the intended output has been sent to it.
  4693. +      *Note Closing Output Files and Pipes: Close Output, for more
  4694. +      information on this.  This example also illustrates the use of a
  4695. +      variable to represent a FILE or COMMAND: it is not necessary to
  4696. +      always use a string constant.  Using a variable is generally a
  4697. +      good idea, since `awk' requires you to spell the string value
  4698. +      identically every time.
  4699. + 
  4700. +    Redirecting output using `>', `>>', or `|' asks the system to open a
  4701. + file or pipe only if the particular FILE or COMMAND you've specified
  4702. + has not already been written to by your program, or if it has been
  4703. + closed since it was last written to.
  4704. + 
  4705. + 
  4706. + File: gawk.info,  Node: Close Output,  Prev: File/Pipe Redirection,  Up: Redirection
  4707. + 
  4708. + Closing Output Files and Pipes
  4709. + ------------------------------
  4710. + 
  4711. +    When a file or pipe is opened, the file name or command associated
  4712. + with it is remembered by `awk' and subsequent writes to the same file or
  4713. + command are appended to the previous writes.  The file or pipe stays
  4714. + open until `awk' exits.  This is usually convenient.
  4715. + 
  4716. +    Sometimes there is a reason to close an output file or pipe earlier
  4717. + than that.  To do this, use the `close' function, as follows:
  4718. + 
  4719. +      close(FILENAME)
  4720. + 
  4721. + or
  4722. + 
  4723. +      close(COMMAND)
  4724. + 
  4725. +    The argument FILENAME or COMMAND can be any expression.  Its value
  4726. + must exactly equal the string used to open the file or pipe to begin
  4727. + with--for example, if you open a pipe with this:
  4728. + 
  4729. +      print $1 | "sort -r > names.sorted"
  4730. + 
  4731. + then you must close it with this:
  4732. + 
  4733. +      close("sort -r > names.sorted")
  4734. + 
  4735. +    Here are some reasons why you might need to close an output file:
  4736. + 
  4737. +    * To write a file and read it back later on in the same `awk'
  4738. +      program.  Close the file when you are finished writing it; then
  4739. +      you can start reading it with `getline' (*note Explicit Input with
  4740. +      `getline': Getline.).
  4741. + 
  4742. +    * To write numerous files, successively, in the same `awk' program.
  4743. +      If you don't close the files, eventually you may exceed a system
  4744. +      limit on the number of open files in one process.  So close each
  4745. +      one when you are finished writing it.
  4746. + 
  4747. +    * To make a command finish.  When you redirect output through a pipe,
  4748. +      the command reading the pipe normally continues to try to read
  4749. +      input as long as the pipe is open.  Often this means the command
  4750. +      cannot really do its work until the pipe is closed.  For example,
  4751. +      if you redirect output to the `mail' program, the message is not
  4752. +      actually sent until the pipe is closed.
  4753. + 
  4754. +    * To run the same program a second time, with the same arguments.
  4755. +      This is not the same thing as giving more input to the first run!
  4756. + 
  4757. +      For example, suppose you pipe output to the `mail' program.  If you
  4758. +      output several lines redirected to this pipe without closing it,
  4759. +      they make a single message of several lines.  By contrast, if you
  4760. +      close the pipe after each line of output, then each line makes a
  4761. +      separate message.
  4762. + 
  4763. +    `close' returns a value of zero if the close succeeded.  Otherwise,
  4764. + the value will be non-zero.  In this case, `gawk' sets the variable
  4765. + `ERRNO' to a string describing the error that occurred.
  4766. + 
  4767. + 
  4768. + File: gawk.info,  Node: Special Files,  Prev: Redirection,  Up: Printing
  4769. + 
  4770. + Standard I/O Streams
  4771. + ====================
  4772. + 
  4773. +    Running programs conventionally have three input and output streams
  4774. + already available to them for reading and writing.  These are known as
  4775. + the "standard input", "standard output", and "standard error output".
  4776. + These streams are, by default, terminal input and output, but they are
  4777. + often redirected with the shell, via the `<', `<<', `>', `>>', `>&' and
  4778. + `|' operators.  Standard error is used only for writing error messages;
  4779. + the reason we have two separate streams, standard output and standard
  4780. + error, is so that they can be redirected separately.
  4781. + 
  4782. +    In other implementations of `awk', the only way to write an error
  4783. + message to standard error in an `awk' program is as follows:
  4784. + 
  4785. +      print "Serious error detected!\n" | "cat 1>&2"
  4786. + 
  4787. + This works by opening a pipeline to a shell command which can access the
  4788. + standard error stream which it inherits from the `awk' process.  This
  4789. + is far from elegant, and is also inefficient, since it requires a
  4790. + separate process.  So people writing `awk' programs have often
  4791. + neglected to do this.  Instead, they have sent the error messages to the
  4792. + terminal, like this:
  4793. + 
  4794. +      NF != 4 {
  4795. +         printf("line %d skipped: doesn't have 4 fields\n", FNR) > "/dev/tty"
  4796. +      }
  4797. + 
  4798. + This has the same effect most of the time, but not always: although the
  4799. + standard error stream is usually the terminal, it can be redirected, and
  4800. + when that happens, writing to the terminal is not correct.  In fact, if
  4801. + `awk' is run from a background job, it may not have a terminal at all.
  4802. + Then opening `/dev/tty' will fail.
  4803. + 
  4804. +    `gawk' provides special file names for accessing the three standard
  4805. + streams.  When you redirect input or output in `gawk', if the file name
  4806. + matches one of these special names, then `gawk' directly uses the
  4807. + stream it stands for.
  4808. + 
  4809. + `/dev/stdin'
  4810. +      The standard input (file descriptor 0).
  4811. + 
  4812. + `/dev/stdout'
  4813. +      The standard output (file descriptor 1).
  4814. + 
  4815. + `/dev/stderr'
  4816. +      The standard error output (file descriptor 2).
  4817. + 
  4818. + `/dev/fd/N'
  4819. +      The file associated with file descriptor N.  Such a file must have
  4820. +      been opened by the program initiating the `awk' execution
  4821. +      (typically the shell).  Unless you take special pains, only
  4822. +      descriptors 0, 1 and 2 are available.
  4823. + 
  4824. +    The file names `/dev/stdin', `/dev/stdout', and `/dev/stderr' are
  4825. + aliases for `/dev/fd/0', `/dev/fd/1', and `/dev/fd/2', respectively,
  4826. + but they are more self-explanatory.
  4827. + 
  4828. +    The proper way to write an error message in a `gawk' program is to
  4829. + use `/dev/stderr', like this:
  4830. + 
  4831. +      NF != 4 {
  4832. +        printf("line %d skipped: doesn't have 4 fields\n", FNR) > "/dev/stderr"
  4833. +      }
  4834. + 
  4835. +    `gawk' also provides special file names that give access to
  4836. + information about the running `gawk' process.  Each of these "files"
  4837. + provides a single record of information.  To read them more than once,
  4838. + you must first close them with the `close' function (*note Closing
  4839. + Input Files and Pipes: Close Input.).  The filenames are:
  4840. + 
  4841. + `/dev/pid'
  4842. +      Reading this file returns the process ID of the current process,
  4843. +      in decimal, terminated with a newline.
  4844. + 
  4845. + `/dev/ppid'
  4846. +      Reading this file returns the parent process ID of the current
  4847. +      process, in decimal, terminated with a newline.
  4848. + 
  4849. + `/dev/pgrpid'
  4850. +      Reading this file returns the process group ID of the current
  4851. +      process, in decimal, terminated with a newline.
  4852. + 
  4853. + `/dev/user'
  4854. +      Reading this file returns a single record terminated with a
  4855. +      newline.  The fields are separated with blanks.  The fields
  4856. +      represent the following information:
  4857. + 
  4858. +     `$1'
  4859. +           The value of the `getuid' system call.
  4860. + 
  4861. +     `$2'
  4862. +           The value of the `geteuid' system call.
  4863. + 
  4864. +     `$3'
  4865. +           The value of the `getgid' system call.
  4866. + 
  4867. +     `$4'
  4868. +           The value of the `getegid' system call.
  4869. + 
  4870. +      If there are any additional fields, they are the group IDs
  4871. +      returned by `getgroups' system call.  (Multiple groups may not be
  4872. +      supported on all systems.)
  4873. + 
  4874. +    These special file names may be used on the command line as data
  4875. + files, as well as for I/O redirections within an `awk' program.  They
  4876. + may not be used as source files with the `-f' option.
  4877. + 
  4878. +    Recognition of these special file names is disabled if `gawk' is in
  4879. + compatibility mode (*note Invoking `awk': Command Line.).
  4880. + 
  4881. +      *Caution*:  Unless your system actually has a `/dev/fd' directory
  4882. +      (or any of the other above listed special files), the
  4883. +      interpretation of these file names is done by `gawk' itself.  For
  4884. +      example, using `/dev/fd/4' for output will actually write on file
  4885. +      descriptor 4, and not on a new file descriptor that was `dup''ed
  4886. +      from file descriptor 4.  Most of the time this does not matter;
  4887. +      however, it is important to *not* close any of the files related
  4888. +      to file descriptors 0, 1, and 2.  If you do close one of these
  4889. +      files, unpredictable behavior will result.
  4890. + 
  4891. + 
  4892. + File: gawk.info,  Node: One-liners,  Next: Patterns,  Prev: Printing,  Up: Top
  4893. + 
  4894. + Useful "One-liners"
  4895. + *******************
  4896. + 
  4897. +    Useful `awk' programs are often short, just a line or two.  Here is a
  4898. + collection of useful, short programs to get you started.  Some of these
  4899. + programs contain constructs that haven't been covered yet.  The
  4900. + description of the program will give you a good idea of what is going
  4901. + on, but please read the rest of the manual to become an `awk' expert!
  4902. + 
  4903. +    Since you are reading this in Info, each line of the example code is
  4904. + enclosed in quotes, to represent text that you would type literally.
  4905. + The examples themselves represent shell commands that use single quotes
  4906. + to keep the shell from interpreting the contents of the program.  When
  4907. + reading the examples, focus on the text between the open and close
  4908. + quotes.
  4909. + 
  4910. + `awk '{ if (NF > max) max = NF }'
  4911. + `     END { print max }''
  4912. +      This program prints the maximum number of fields on any input line.
  4913. + 
  4914. + `awk 'length($0) > 80''
  4915. +      This program prints every line longer than 80 characters.  The sole
  4916. +      rule has a relational expression as its pattern, and has no action
  4917. +      (so the default action, printing the record, is used).
  4918. + 
  4919. + `awk 'NF > 0''
  4920. +      This program prints every line that has at least one field.  This
  4921. +      is an easy way to delete blank lines from a file (or rather, to
  4922. +      create a new file similar to the old file but from which the blank
  4923. +      lines have been deleted).
  4924. + 
  4925. + `awk '{ if (NF > 0) print }''
  4926. +      This program also prints every line that has at least one field.
  4927. +      Here we allow the rule to match every line, then decide in the
  4928. +      action whether to print.
  4929. + 
  4930. + `awk 'BEGIN { for (i = 1; i <= 7; i++)'
  4931. + `               print int(101 * rand()) }''
  4932. +      This program prints 7 random numbers from 0 to 100, inclusive.
  4933. + 
  4934. + `ls -l FILES | awk '{ x += $4 } ; END { print "total bytes: " x }''
  4935. +      This program prints the total number of bytes used by FILES.
  4936. + 
  4937. + `expand FILE | awk '{ if (x < length()) x = length() }'
  4938. + `                  END { print "maximum line length is " x }''
  4939. +      This program prints the maximum line length of FILE.  The input is
  4940. +      piped through the `expand' program to change tabs into spaces, so
  4941. +      the widths compared are actually the right-margin columns.
  4942. + 
  4943. + `awk 'BEGIN { FS = ":" }'
  4944. + `     { print $1 | "sort" }' /etc/passwd'
  4945. +      This program prints a sorted list of the login names of all users.
  4946. + 
  4947. + `awk '{ nlines++ }'
  4948. + `     END { print nlines }''
  4949. +      This programs counts lines in a file.
  4950. + 
  4951. + `awk 'END { print NR }''
  4952. +      This program also counts lines in a file, but lets `awk' do the
  4953. +      work.
  4954. + 
  4955. + `awk '{ print NR, $0 }''
  4956. +      This program adds line numbers to all its input files, similar to
  4957. +      `cat -n'.
  4958. + 
  4959. + 
  4960. + File: gawk.info,  Node: Patterns,  Next: Actions,  Prev: One-liners,  Up: Top
  4961. + 
  4962. + Patterns
  4963. + ********
  4964. + 
  4965. +    Patterns in `awk' control the execution of rules: a rule is executed
  4966. + when its pattern matches the current input record.  This chapter tells
  4967. + all about how to write patterns.
  4968. + 
  4969. + * Menu:
  4970. + 
  4971. + * Kinds of Patterns::           A list of all kinds of patterns.
  4972. +                                 The following subsections describe
  4973. +                                 them in detail.
  4974. + * Regexp::                      Regular expressions such as `/foo/'.
  4975. + * Comparison Patterns::         Comparison expressions such as `$1 > 10'.
  4976. + * Boolean Patterns::            Combining comparison expressions.
  4977. + * Expression Patterns::         Any expression can be used as a pattern.
  4978. + * Ranges::                      Pairs of patterns specify record ranges.
  4979. + * BEGIN/END::                   Specifying initialization and cleanup rules.
  4980. + * Empty::                       The empty pattern, which matches every record.
  4981. + 
  4982. + 
  4983. + File: gawk.info,  Node: Kinds of Patterns,  Next: Regexp,  Prev: Patterns,  Up: Patterns
  4984. + 
  4985. + Kinds of Patterns
  4986. + =================
  4987. + 
  4988. +    Here is a summary of the types of patterns supported in `awk'.
  4989. + 
  4990. + `/REGULAR EXPRESSION/'
  4991. +      A regular expression as a pattern.  It matches when the text of the
  4992. +      input record fits the regular expression.  (*Note Regular
  4993. +      Expressions as Patterns: Regexp.)
  4994. + 
  4995. + `EXPRESSION'
  4996. +      A single expression.  It matches when its value, converted to a
  4997. +      number, is nonzero (if a number) or nonnull (if a string).  (*Note
  4998. +      Expressions as Patterns: Expression Patterns.)
  4999. + 
  5000. + `PAT1, PAT2'
  5001. +      A pair of patterns separated by a comma, specifying a range of
  5002. +      records.  (*Note Specifying Record Ranges with Patterns: Ranges.)
  5003. + 
  5004. + `BEGIN'
  5005. + `END'
  5006. +      Special patterns to supply start-up or clean-up information to
  5007. +      `awk'.  (*Note `BEGIN' and `END' Special Patterns: BEGIN/END.)
  5008. + 
  5009. + `NULL'
  5010. +      The empty pattern matches every input record.  (*Note The Empty
  5011. +      Pattern: Empty.)
  5012. + 
  5013. + 
  5014. + File: gawk.info,  Node: Regexp,  Next: Comparison Patterns,  Prev: Kinds of Patterns,  Up: Patterns
  5015. + 
  5016. + Regular Expressions as Patterns
  5017. + ===============================
  5018. + 
  5019. +    A "regular expression", or "regexp", is a way of describing a class
  5020. + of strings.  A regular expression enclosed in slashes (`/') is an `awk'
  5021. + pattern that matches every input record whose text belongs to that
  5022. + class.
  5023. + 
  5024. +    The simplest regular expression is a sequence of letters, numbers, or
  5025. + both.  Such a regexp matches any string that contains that sequence.
  5026. + Thus, the regexp `foo' matches any string containing `foo'.  Therefore,
  5027. + the pattern `/foo/' matches any input record containing `foo'.  Other
  5028. + kinds of regexps let you specify more complicated classes of strings.
  5029. + 
  5030. + * Menu:
  5031. + 
  5032. + * Regexp Usage::                How to Use Regular Expressions
  5033. + * Regexp Operators::            Regular Expression Operators
  5034. + * Case-sensitivity::            How to do case-insensitive matching.
  5035. + 
  5036. + 
  5037. + File: gawk.info,  Node: Regexp Usage,  Next: Regexp Operators,  Prev: Regexp,  Up: Regexp
  5038. + 
  5039. + How to Use Regular Expressions
  5040. + ------------------------------
  5041. + 
  5042. +    A regular expression can be used as a pattern by enclosing it in
  5043. + slashes.  Then the regular expression is matched against the entire
  5044. + text of each record.  (Normally, it only needs to match some part of
  5045. + the text in order to succeed.)  For example, this prints the second
  5046. + field of each record that contains `foo' anywhere:
  5047. + 
  5048. +      awk '/foo/ { print $2 }' BBS-list
  5049. + 
  5050. +    Regular expressions can also be used in comparison expressions.  Then
  5051. + you can specify the string to match against; it need not be the entire
  5052. + current input record.  These comparison expressions can be used as
  5053. + patterns or in `if', `while', `for', and `do' statements.
  5054. + 
  5055. + `EXP ~ /REGEXP/'
  5056. +      This is true if the expression EXP (taken as a character string)
  5057. +      is matched by REGEXP.  The following example matches, or selects,
  5058. +      all input records with the upper-case letter `J' somewhere in the
  5059. +      first field:
  5060. + 
  5061. +           awk '$1 ~ /J/' inventory-shipped
  5062. + 
  5063. +      So does this:
  5064. + 
  5065. +           awk '{ if ($1 ~ /J/) print }' inventory-shipped
  5066. + 
  5067. + `EXP !~ /REGEXP/'
  5068. +      This is true if the expression EXP (taken as a character string)
  5069. +      is *not* matched by REGEXP.  The following example matches, or
  5070. +      selects, all input records whose first field *does not* contain
  5071. +      the upper-case letter `J':
  5072. + 
  5073. +           awk '$1 !~ /J/' inventory-shipped
  5074. + 
  5075. +    The right hand side of a `~' or `!~' operator need not be a constant
  5076. + regexp (i.e., a string of characters between slashes).  It may be any
  5077. + expression.  The expression is evaluated, and converted if necessary to
  5078. + a string; the contents of the string are used as the regexp.  A regexp
  5079. + that is computed in this way is called a "dynamic regexp".  For example:
  5080. + 
  5081. +      identifier_regexp = "[A-Za-z_][A-Za-z_0-9]+"
  5082. +      $0 ~ identifier_regexp
  5083. + 
  5084. + sets `identifier_regexp' to a regexp that describes `awk' variable
  5085. + names, and tests if the input record matches this regexp.
  5086. + 
  5087. + 
  5088. + File: gawk.info,  Node: Regexp Operators,  Next: Case-sensitivity,  Prev: Regexp Usage,  Up: Regexp
  5089. + 
  5090. + Regular Expression Operators
  5091. + ----------------------------
  5092. + 
  5093. +    You can combine regular expressions with the following characters,
  5094. + called "regular expression operators", or "metacharacters", to increase
  5095. + the power and versatility of regular expressions.
  5096. + 
  5097. +    Here is a table of metacharacters.  All characters not listed in the
  5098. + table stand for themselves.
  5099. + 
  5100. + `^'
  5101. +      This matches the beginning of the string or the beginning of a line
  5102. +      within the string.  For example:
  5103. + 
  5104. +           ^@chapter
  5105. + 
  5106. +      matches the `@chapter' at the beginning of a string, and can be
  5107. +      used to identify chapter beginnings in Texinfo source files.
  5108. + 
  5109. + `$'
  5110. +      This is similar to `^', but it matches only at the end of a string
  5111. +      or the end of a line within the string.  For example:
  5112. + 
  5113. +           p$
  5114. + 
  5115. +      matches a record that ends with a `p'.
  5116. + 
  5117. + `.'
  5118. +      This matches any single character except a newline.  For example:
  5119. + 
  5120. +           .P
  5121. + 
  5122. +      matches any single character followed by a `P' in a string.  Using
  5123. +      concatenation we can make regular expressions like `U.A', which
  5124. +      matches any three-character sequence that begins with `U' and ends
  5125. +      with `A'.
  5126. + 
  5127. + `[...]'
  5128. +      This is called a "character set".  It matches any one of the
  5129. +      characters that are enclosed in the square brackets.  For example:
  5130. + 
  5131. +           [MVX]
  5132. + 
  5133. +      matches any one of the characters `M', `V', or `X' in a string.
  5134. + 
  5135. +      Ranges of characters are indicated by using a hyphen between the
  5136. +      beginning and ending characters, and enclosing the whole thing in
  5137. +      brackets.  For example:
  5138. + 
  5139. +           [0-9]
  5140. + 
  5141. +      matches any digit.
  5142. + 
  5143. +      To include the character `\', `]', `-' or `^' in a character set,
  5144. +      put a `\' in front of it.  For example:
  5145. + 
  5146. +           [d\]]
  5147. + 
  5148. +      matches either `d', or `]'.
  5149. + 
  5150. +      This treatment of `\' is compatible with other `awk'
  5151. +      implementations, and is also mandated by the POSIX Command Language
  5152. +      and Utilities standard.  The regular expressions in `awk' are a
  5153. +      superset of the POSIX specification for Extended Regular
  5154. +      Expressions (EREs).  POSIX EREs are based on the regular
  5155. +      expressions accepted by the traditional `egrep' utility.
  5156. + 
  5157. +      In `egrep' syntax, backslash is not syntactically special within
  5158. +      square brackets.  This means that special tricks have to be used to
  5159. +      represent the characters `]', `-' and `^' as members of a
  5160. +      character set.
  5161. + 
  5162. +      In `egrep' syntax, to match `-', write it as `---', which is a
  5163. +      range containing only `-'.  You may also give `-' as the first or
  5164. +      last character in the set.  To match `^', put it anywhere except
  5165. +      as the first character of a set.  To match a `]', make it the
  5166. +      first character in the set.  For example:
  5167. + 
  5168. +           []d^]
  5169. + 
  5170. +      matches either `]', `d' or `^'.
  5171. + 
  5172. + `[^ ...]'
  5173. +      This is a "complemented character set".  The first character after
  5174. +      the `[' *must* be a `^'.  It matches any characters *except* those
  5175. +      in the square brackets (or newline).  For example:
  5176. + 
  5177. +           [^0-9]
  5178. + 
  5179. +      matches any character that is not a digit.
  5180. + 
  5181. + `|'
  5182. +      This is the "alternation operator" and it is used to specify
  5183. +      alternatives.  For example:
  5184. + 
  5185. +           ^P|[0-9]
  5186. + 
  5187. +      matches any string that matches either `^P' or `[0-9]'.  This
  5188. +      means it matches any string that contains a digit or starts with
  5189. +      `P'.
  5190. + 
  5191. +      The alternation applies to the largest possible regexps on either
  5192. +      side.
  5193. + 
  5194. + `(...)'
  5195. +      Parentheses are used for grouping in regular expressions as in
  5196. +      arithmetic.  They can be used to concatenate regular expressions
  5197. +      containing the alternation operator, `|'.
  5198. + 
  5199. + `*'
  5200. +      This symbol means that the preceding regular expression is to be
  5201. +      repeated as many times as possible to find a match.  For example:
  5202. + 
  5203. +           ph*
  5204. + 
  5205. +      applies the `*' symbol to the preceding `h' and looks for matches
  5206. +      to one `p' followed by any number of `h's.  This will also match
  5207. +      just `p' if no `h's are present.
  5208. + 
  5209. +      The `*' repeats the *smallest* possible preceding expression.
  5210. +      (Use parentheses if you wish to repeat a larger expression.)  It
  5211. +      finds as many repetitions as possible.  For example:
  5212. + 
  5213. +           awk '/\(c[ad][ad]*r x\)/ { print }' sample
  5214. + 
  5215. +      prints every record in the input containing a string of the form
  5216. +      `(car x)', `(cdr x)', `(cadr x)', and so on.
  5217. + 
  5218. + `+'
  5219. +      This symbol is similar to `*', but the preceding expression must be
  5220. +      matched at least once.  This means that:
  5221. + 
  5222. +           wh+y
  5223. + 
  5224. +      would match `why' and `whhy' but not `wy', whereas `wh*y' would
  5225. +      match all three of these strings.  This is a simpler way of
  5226. +      writing the last `*' example:
  5227. + 
  5228. +           awk '/\(c[ad]+r x\)/ { print }' sample
  5229. + 
  5230. + `?'
  5231. +      This symbol is similar to `*', but the preceding expression can be
  5232. +      matched once or not at all.  For example:
  5233. + 
  5234. +           fe?d
  5235. + 
  5236. +      will match `fed' and `fd', but nothing else.
  5237. + 
  5238. + `\'
  5239. +      This is used to suppress the special meaning of a character when
  5240. +      matching.  For example:
  5241. + 
  5242. +           \$
  5243. + 
  5244. +      matches the character `$'.
  5245. + 
  5246. +      The escape sequences used for string constants (*note Constant
  5247. +      Expressions: Constants.) are valid in regular expressions as well;
  5248. +      they are also introduced by a `\'.
  5249. + 
  5250. +    In regular expressions, the `*', `+', and `?' operators have the
  5251. + highest precedence, followed by concatenation, and finally by `|'.  As
  5252. + in arithmetic, parentheses can change how operators are grouped.
  5253. + 
  5254. + 
  5255. + File: gawk.info,  Node: Case-sensitivity,  Prev: Regexp Operators,  Up: Regexp
  5256. + 
  5257. + Case-sensitivity in Matching
  5258. + ----------------------------
  5259. + 
  5260. +    Case is normally significant in regular expressions, both when
  5261. + matching ordinary characters (i.e., not metacharacters), and inside
  5262. + character sets.  Thus a `w' in a regular expression matches only a
  5263. + lower case `w' and not an upper case `W'.
  5264. + 
  5265. +    The simplest way to do a case-independent match is to use a character
  5266. + set: `[Ww]'.  However, this can be cumbersome if you need to use it
  5267. + often; and it can make the regular expressions harder for humans to
  5268. + read.  There are two other alternatives that you might prefer.
  5269. + 
  5270. +    One way to do a case-insensitive match at a particular point in the
  5271. + program is to convert the data to a single case, using the `tolower' or
  5272. + `toupper' built-in string functions (which we haven't discussed yet;
  5273. + *note Built-in Functions for String Manipulation: String Functions.).
  5274. + For example:
  5275. + 
  5276. +      tolower($1) ~ /foo/  { ... }
  5277. + 
  5278. + converts the first field to lower case before matching against it.
  5279. + 
  5280. +    Another method is to set the variable `IGNORECASE' to a nonzero
  5281. + value (*note Built-in Variables::.).  When `IGNORECASE' is not zero,
  5282. + *all* regexp operations ignore case.  Changing the value of
  5283. + `IGNORECASE' dynamically controls the case sensitivity of your program
  5284. + as it runs.  Case is significant by default because `IGNORECASE' (like
  5285. + most variables) is initialized to zero.
  5286. + 
  5287. +      x = "aB"
  5288. +      if (x ~ /ab/) ...   # this test will fail
  5289. +      
  5290. +      IGNORECASE = 1
  5291. +      if (x ~ /ab/) ...   # now it will succeed
  5292. + 
  5293. +    In general, you cannot use `IGNORECASE' to make certain rules
  5294. + case-insensitive and other rules case-sensitive, because there is no way
  5295. + to set `IGNORECASE' just for the pattern of a particular rule.  To do
  5296. + this, you must use character sets or `tolower'.  However, one thing you
  5297. + can do only with `IGNORECASE' is turn case-sensitivity on or off
  5298. + dynamically for all the rules at once.
  5299. + 
  5300. +    `IGNORECASE' can be set on the command line, or in a `BEGIN' rule.
  5301. + Setting `IGNORECASE' from the command line is a way to make a program
  5302. + case-insensitive without having to edit it.
  5303. + 
  5304. +    The value of `IGNORECASE' has no effect if `gawk' is in
  5305. + compatibility mode (*note Invoking `awk': Command Line.).  Case is
  5306. + always significant in compatibility mode.
  5307. + 
  5308. + 
  5309. + File: gawk.info,  Node: Comparison Patterns,  Next: Boolean Patterns,  Prev: Regexp,  Up: Patterns
  5310. + 
  5311. + Comparison Expressions as Patterns
  5312. + ==================================
  5313. + 
  5314. +    "Comparison patterns" test relationships such as equality between
  5315. + two strings or numbers.  They are a special case of expression patterns
  5316. + (*note Expressions as Patterns: Expression Patterns.).  They are written
  5317. + with "relational operators", which are a superset of those in C.  Here
  5318. + is a table of them:
  5319. + 
  5320. + `X < Y'
  5321. +      True if X is less than Y.
  5322. + 
  5323. + `X <= Y'
  5324. +      True if X is less than or equal to Y.
  5325. + 
  5326. + `X > Y'
  5327. +      True if X is greater than Y.
  5328. + 
  5329. + `X >= Y'
  5330. +      True if X is greater than or equal to Y.
  5331. + 
  5332. + `X == Y'
  5333. +      True if X is equal to Y.
  5334. + 
  5335. + `X != Y'
  5336. +      True if X is not equal to Y.
  5337. + 
  5338. + `X ~ Y'
  5339. +      True if X matches the regular expression described by Y.
  5340. + 
  5341. + `X !~ Y'
  5342. +      True if X does not match the regular expression described by Y.
  5343. + 
  5344. +    The operands of a relational operator are compared as numbers if they
  5345. + are both numbers.  Otherwise they are converted to, and compared as,
  5346. + strings (*note Conversion of Strings and Numbers: Conversion., for the
  5347. + detailed rules).  Strings are compared by comparing the first character
  5348. + of each, then the second character of each, and so on, until there is a
  5349. + difference.  If the two strings are equal until the shorter one runs
  5350. + out, the shorter one is considered to be less than the longer one.
  5351. + Thus, `"10"' is less than `"9"', and `"abc"' is less than `"abcd"'.
  5352. + 
  5353. +    The left operand of the `~' and `!~' operators is a string.  The
  5354. + right operand is either a constant regular expression enclosed in
  5355. + slashes (`/REGEXP/'), or any expression, whose string value is used as
  5356. + a dynamic regular expression (*note How to Use Regular Expressions:
  5357. + Regexp Usage.).
  5358. + 
  5359. +    The following example prints the second field of each input record
  5360. + whose first field is precisely `foo'.
  5361. + 
  5362. +      awk '$1 == "foo" { print $2 }' BBS-list
  5363. + 
  5364. + Contrast this with the following regular expression match, which would
  5365. + accept any record with a first field that contains `foo':
  5366. + 
  5367. +      awk '$1 ~ "foo" { print $2 }' BBS-list
  5368. + 
  5369. + or, equivalently, this one:
  5370. + 
  5371. +      awk '$1 ~ /foo/ { print $2 }' BBS-list
  5372. + 
  5373. + 
  5374. + File: gawk.info,  Node: Boolean Patterns,  Next: Expression Patterns,  Prev: Comparison Patterns,  Up: Patterns
  5375. + 
  5376. + Boolean Operators and Patterns
  5377. + ==============================
  5378. + 
  5379. +    A "boolean pattern" is an expression which combines other patterns
  5380. + using the "boolean operators" "or" (`||'), "and" (`&&'), and "not"
  5381. + (`!').  Whether the boolean pattern matches an input record depends on
  5382. + whether its subpatterns match.
  5383. + 
  5384. +    For example, the following command prints all records in the input
  5385. + file `BBS-list' that contain both `2400' and `foo'.
  5386. + 
  5387. +      awk '/2400/ && /foo/' BBS-list
  5388. + 
  5389. +    The following command prints all records in the input file
  5390. + `BBS-list' that contain *either* `2400' or `foo', or both.
  5391. + 
  5392. +      awk '/2400/ || /foo/' BBS-list
  5393. + 
  5394. +    The following command prints all records in the input file
  5395. + `BBS-list' that do *not* contain the string `foo'.
  5396. + 
  5397. +      awk '! /foo/' BBS-list
  5398. + 
  5399. +    Note that boolean patterns are a special case of expression patterns
  5400. + (*note Expressions as Patterns: Expression Patterns.); they are
  5401. + expressions that use the boolean operators.  *Note Boolean Expressions:
  5402. + Boolean Ops, for complete information on the boolean operators.
  5403. + 
  5404. +    The subpatterns of a boolean pattern can be constant regular
  5405. + expressions, comparisons, or any other `awk' expressions.  Range
  5406. + patterns are not expressions, so they cannot appear inside boolean
  5407. + patterns.  Likewise, the special patterns `BEGIN' and `END', which
  5408. + never match any input record, are not expressions and cannot appear
  5409. + inside boolean patterns.
  5410. + 
  5411. + 
  5412. + File: gawk.info,  Node: Expression Patterns,  Next: Ranges,  Prev: Boolean Patterns,  Up: Patterns
  5413. + 
  5414. + Expressions as Patterns
  5415. + =======================
  5416. + 
  5417. +    Any `awk' expression is also valid as an `awk' pattern.  Then the
  5418. + pattern "matches" if the expression's value is nonzero (if a number) or
  5419. + nonnull (if a string).
  5420. + 
  5421. +    The expression is reevaluated each time the rule is tested against a
  5422. + new input record.  If the expression uses fields such as `$1', the
  5423. + value depends directly on the new input record's text; otherwise, it
  5424. + depends only on what has happened so far in the execution of the `awk'
  5425. + program, but that may still be useful.
  5426. + 
  5427. +    Comparison patterns are actually a special case of this.  For
  5428. + example, the expression `$5 == "foo"' has the value 1 when the value of
  5429. + `$5' equals `"foo"', and 0 otherwise; therefore, this expression as a
  5430. + pattern matches when the two values are equal.
  5431. + 
  5432. +    Boolean patterns are also special cases of expression patterns.
  5433. + 
  5434. +    A constant regexp as a pattern is also a special case of an
  5435. + expression pattern.  `/foo/' as an expression has the value 1 if `foo'
  5436. + appears in the current input record; thus, as a pattern, `/foo/'
  5437. + matches any record containing `foo'.
  5438. + 
  5439. +    Other implementations of `awk' that are not yet POSIX compliant are
  5440. + less general than `gawk': they allow comparison expressions, and
  5441. + boolean combinations thereof (optionally with parentheses), but not
  5442. + necessarily other kinds of expressions.
  5443. + 
  5444. + 
  5445. + File: gawk.info,  Node: Ranges,  Next: BEGIN/END,  Prev: Expression Patterns,  Up: Patterns
  5446. + 
  5447. + Specifying Record Ranges with Patterns
  5448. + ======================================
  5449. + 
  5450. +    A "range pattern" is made of two patterns separated by a comma, of
  5451. + the form `BEGPAT, ENDPAT'.  It matches ranges of consecutive input
  5452. + records.  The first pattern BEGPAT controls where the range begins, and
  5453. + the second one ENDPAT controls where it ends.  For example,
  5454. + 
  5455. +      awk '$1 == "on", $1 == "off"'
  5456. + 
  5457. + prints every record between `on'/`off' pairs, inclusive.
  5458. + 
  5459. +    A range pattern starts out by matching BEGPAT against every input
  5460. + record; when a record matches BEGPAT, the range pattern becomes "turned
  5461. + on".  The range pattern matches this record.  As long as it stays
  5462. + turned on, it automatically matches every input record read.  It also
  5463. + matches ENDPAT against every input record; when that succeeds, the
  5464. + range pattern is turned off again for the following record.  Now it
  5465. + goes back to checking BEGPAT against each record.
  5466. + 
  5467. +    The record that turns on the range pattern and the one that turns it
  5468. + off both match the range pattern.  If you don't want to operate on
  5469. + these records, you can write `if' statements in the rule's action to
  5470. + distinguish them.
  5471. + 
  5472. +    It is possible for a pattern to be turned both on and off by the same
  5473. + record, if both conditions are satisfied by that record.  Then the
  5474. + action is executed for just that record.
  5475. + 
  5476. + 
  5477. + File: gawk.info,  Node: BEGIN/END,  Next: Empty,  Prev: Ranges,  Up: Patterns
  5478. + 
  5479. + `BEGIN' and `END' Special Patterns
  5480. + ==================================
  5481. + 
  5482. +    `BEGIN' and `END' are special patterns.  They are not used to match
  5483. + input records.  Rather, they are used for supplying start-up or
  5484. + clean-up information to your `awk' script.  A `BEGIN' rule is executed,
  5485. + once, before the first input record has been read.  An `END' rule is
  5486. + executed, once, after all the input has been read.  For example:
  5487. + 
  5488. +      awk 'BEGIN { print "Analysis of `foo'" }
  5489. +           /foo/ { ++foobar }
  5490. +           END   { print "`foo' appears " foobar " times." }' BBS-list
  5491. + 
  5492. +    This program finds the number of records in the input file `BBS-list'
  5493. + that contain the string `foo'.  The `BEGIN' rule prints a title for the
  5494. + report.  There is no need to use the `BEGIN' rule to initialize the
  5495. + counter `foobar' to zero, as `awk' does this for us automatically
  5496. + (*note Variables::.).
  5497. + 
  5498. +    The second rule increments the variable `foobar' every time a record
  5499. + containing the pattern `foo' is read.  The `END' rule prints the value
  5500. + of `foobar' at the end of the run.
  5501. + 
  5502. +    The special patterns `BEGIN' and `END' cannot be used in ranges or
  5503. + with boolean operators (indeed, they cannot be used with any operators).
  5504. + 
  5505. +    An `awk' program may have multiple `BEGIN' and/or `END' rules.  They
  5506. + are executed in the order they appear, all the `BEGIN' rules at
  5507. + start-up and all the `END' rules at termination.
  5508. + 
  5509. +    Multiple `BEGIN' and `END' sections are useful for writing library
  5510. + functions, since each library can have its own `BEGIN' or `END' rule to
  5511. + do its own initialization and/or cleanup.  Note that the order in which
  5512. + library functions are named on the command line controls the order in
  5513. + which their `BEGIN' and `END' rules are executed.  Therefore you have
  5514. + to be careful to write such rules in library files so that the order in
  5515. + which they are executed doesn't matter.  *Note Invoking `awk': Command
  5516. + Line, for more information on using library functions.
  5517. + 
  5518. +    If an `awk' program only has a `BEGIN' rule, and no other rules,
  5519. + then the program exits after the `BEGIN' rule has been run.  (Older
  5520. + versions of `awk' used to keep reading and ignoring input until end of
  5521. + file was seen.)  However, if an `END' rule exists as well, then the
  5522. + input will be read, even if there are no other rules in the program.
  5523. + This is necessary in case the `END' rule checks the `NR' variable.
  5524. + 
  5525. +    `BEGIN' and `END' rules must have actions; there is no default
  5526. + action for these rules since there is no current record when they run.
  5527. + 
  5528. + 
  5529. + File: gawk.info,  Node: Empty,  Prev: BEGIN/END,  Up: Patterns
  5530. + 
  5531. + The Empty Pattern
  5532. + =================
  5533. + 
  5534. +    An empty pattern is considered to match *every* input record.  For
  5535. + example, the program:
  5536. + 
  5537. +      awk '{ print $1 }' BBS-list
  5538. + 
  5539. + prints the first field of every record.
  5540. + 
  5541. diff -rc --new-file /src/baseline/gawk-2.15.5/gawk.info-4 gawk-2.15.5/gawk.info-4
  5542. *** /src/baseline/gawk-2.15.5/gawk.info-4    Thu Jan  1 00:00:00 1970
  5543. --- gawk-2.15.5/gawk.info-4    Sun Jun 12 22:28:51 1994
  5544. ***************
  5545. *** 0 ****
  5546. --- 1,1305 ----
  5547. + This is Info file gawk.info, produced by Makeinfo-1.55 from the input
  5548. + file /gnu/src/amiga/gawk-2.15.5/gawk.texi.
  5549. + 
  5550. +    This file documents `awk', a program that you can use to select
  5551. + particular records in a file and perform operations upon them.
  5552. + 
  5553. +    This is Edition 0.15 of `The GAWK Manual',
  5554. + for the 2.15 version of the GNU implementation
  5555. + of AWK.
  5556. + 
  5557. +    Copyright (C) 1989, 1991, 1992, 1993 Free Software Foundation, Inc.
  5558. + 
  5559. +    Permission is granted to make and distribute verbatim copies of this
  5560. + manual provided the copyright notice and this permission notice are
  5561. + preserved on all copies.
  5562. + 
  5563. +    Permission is granted to copy and distribute modified versions of
  5564. + this manual under the conditions for verbatim copying, provided that
  5565. + the entire resulting derived work is distributed under the terms of a
  5566. + permission notice identical to this one.
  5567. + 
  5568. +    Permission is granted to copy and distribute translations of this
  5569. + manual into another language, under the above conditions for modified
  5570. + versions, except that this permission notice may be stated in a
  5571. + translation approved by the Foundation.
  5572. + 
  5573. + 
  5574. + File: gawk.info,  Node: Actions,  Next: Expressions,  Prev: Patterns,  Up: Top
  5575. + 
  5576. + Overview of Actions
  5577. + *******************
  5578. + 
  5579. +    An `awk' program or script consists of a series of rules and
  5580. + function definitions, interspersed.  (Functions are described later.
  5581. + *Note User-defined Functions: User-defined.)
  5582. + 
  5583. +    A rule contains a pattern and an action, either of which may be
  5584. + omitted.  The purpose of the "action" is to tell `awk' what to do once
  5585. + a match for the pattern is found.  Thus, the entire program looks
  5586. + somewhat like this:
  5587. + 
  5588. +      [PATTERN] [{ ACTION }]
  5589. +      [PATTERN] [{ ACTION }]
  5590. +      ...
  5591. +      function NAME (ARGS) { ... }
  5592. +      ...
  5593. + 
  5594. +    An action consists of one or more `awk' "statements", enclosed in
  5595. + curly braces (`{' and `}').  Each statement specifies one thing to be
  5596. + done.  The statements are separated by newlines or semicolons.
  5597. + 
  5598. +    The curly braces around an action must be used even if the action
  5599. + contains only one statement, or even if it contains no statements at
  5600. + all.  However, if you omit the action entirely, omit the curly braces as
  5601. + well.  (An omitted action is equivalent to `{ print $0 }'.)
  5602. + 
  5603. +    Here are the kinds of statements supported in `awk':
  5604. + 
  5605. +    * Expressions, which can call functions or assign values to variables
  5606. +      (*note Expressions as Action Statements: Expressions.).  Executing
  5607. +      this kind of statement simply computes the value of the expression
  5608. +      and then ignores it.  This is useful when the expression has side
  5609. +      effects (*note Assignment Expressions: Assignment Ops.).
  5610. + 
  5611. +    * Control statements, which specify the control flow of `awk'
  5612. +      programs.  The `awk' language gives you C-like constructs (`if',
  5613. +      `for', `while', and so on) as well as a few special ones (*note
  5614. +      Control Statements in Actions: Statements.).
  5615. + 
  5616. +    * Compound statements, which consist of one or more statements
  5617. +      enclosed in curly braces.  A compound statement is used in order
  5618. +      to put several statements together in the body of an `if',
  5619. +      `while', `do' or `for' statement.
  5620. + 
  5621. +    * Input control, using the `getline' command (*note Explicit Input
  5622. +      with `getline': Getline.), and the `next' statement (*note The
  5623. +      `next' Statement: Next Statement.).
  5624. + 
  5625. +    * Output statements, `print' and `printf'.  *Note Printing Output:
  5626. +      Printing.
  5627. + 
  5628. +    * Deletion statements, for deleting array elements.  *Note The
  5629. +      `delete' Statement: Delete.
  5630. + 
  5631. + 
  5632. + File: gawk.info,  Node: Expressions,  Next: Statements,  Prev: Actions,  Up: Top
  5633. + 
  5634. + Expressions as Action Statements
  5635. + ********************************
  5636. + 
  5637. +    Expressions are the basic building block of `awk' actions.  An
  5638. + expression evaluates to a value, which you can print, test, store in a
  5639. + variable or pass to a function.  But beyond that, an expression can
  5640. + assign a new value to a variable or a field, with an assignment
  5641. + operator.
  5642. + 
  5643. +    An expression can serve as a statement on its own.  Most other kinds
  5644. + of statements contain one or more expressions which specify data to be
  5645. + operated on.  As in other languages, expressions in `awk' include
  5646. + variables, array references, constants, and function calls, as well as
  5647. + combinations of these with various operators.
  5648. + 
  5649. + * Menu:
  5650. + 
  5651. + * Constants::                   String, numeric, and regexp constants.
  5652. + * Variables::                   Variables give names to values for later use.
  5653. + * Arithmetic Ops::              Arithmetic operations (`+', `-', etc.)
  5654. + * Concatenation::               Concatenating strings.
  5655. + * Comparison Ops::              Comparison of numbers and strings
  5656. +                                 with `<', etc.
  5657. + * Boolean Ops::                 Combining comparison expressions
  5658. +                                 using boolean operators
  5659. +                                 `||' ("or"), `&&' ("and") and `!' ("not").
  5660. + 
  5661. + * Assignment Ops::              Changing the value of a variable or a field.
  5662. + * Increment Ops::               Incrementing the numeric value of a variable.
  5663. + 
  5664. + * Conversion::                  The conversion of strings to numbers
  5665. +                                 and vice versa.
  5666. + * Values::                      The whole truth about numbers and strings.
  5667. + * Conditional Exp::             Conditional expressions select
  5668. +                                 between two subexpressions under control
  5669. +                                 of a third subexpression.
  5670. + * Function Calls::              A function call is an expression.
  5671. + * Precedence::                  How various operators nest.
  5672. + 
  5673. + 
  5674. + File: gawk.info,  Node: Constants,  Next: Variables,  Prev: Expressions,  Up: Expressions
  5675. + 
  5676. + Constant Expressions
  5677. + ====================
  5678. + 
  5679. +    The simplest type of expression is the "constant", which always has
  5680. + the same value.  There are three types of constants: numeric constants,
  5681. + string constants, and regular expression constants.
  5682. + 
  5683. +    A "numeric constant" stands for a number.  This number can be an
  5684. + integer, a decimal fraction, or a number in scientific (exponential)
  5685. + notation.  Note that all numeric values are represented within `awk' in
  5686. + double-precision floating point.  Here are some examples of numeric
  5687. + constants, which all have the same value:
  5688. + 
  5689. +      105
  5690. +      1.05e+2
  5691. +      1050e-1
  5692. + 
  5693. +    A string constant consists of a sequence of characters enclosed in
  5694. + double-quote marks.  For example:
  5695. + 
  5696. +      "parrot"
  5697. + 
  5698. + represents the string whose contents are `parrot'.  Strings in `gawk'
  5699. + can be of any length and they can contain all the possible 8-bit ASCII
  5700. + characters including ASCII NUL.  Other `awk' implementations may have
  5701. + difficulty with some character codes.
  5702. + 
  5703. +    Some characters cannot be included literally in a string constant.
  5704. + You represent them instead with "escape sequences", which are character
  5705. + sequences beginning with a backslash (`\').
  5706. + 
  5707. +    One use of an escape sequence is to include a double-quote character
  5708. + in a string constant.  Since a plain double-quote would end the string,
  5709. + you must use `\"' to represent a single double-quote character as a
  5710. + part of the string.  The backslash character itself is another
  5711. + character that cannot be included normally; you write `\\' to put one
  5712. + backslash in the string.  Thus, the string whose contents are the two
  5713. + characters `"\' must be written `"\"\\"'.
  5714. + 
  5715. +    Another use of backslash is to represent unprintable characters such
  5716. + as newline.  While there is nothing to stop you from writing most of
  5717. + these characters directly in a string constant, they may look ugly.
  5718. + 
  5719. +    Here is a table of all the escape sequences used in `awk':
  5720. + 
  5721. + `\\'
  5722. +      Represents a literal backslash, `\'.
  5723. + 
  5724. + `\a'
  5725. +      Represents the "alert" character, control-g, ASCII code 7.
  5726. + 
  5727. + `\b'
  5728. +      Represents a backspace, control-h, ASCII code 8.
  5729. + 
  5730. + `\f'
  5731. +      Represents a formfeed, control-l, ASCII code 12.
  5732. + 
  5733. + `\n'
  5734. +      Represents a newline, control-j, ASCII code 10.
  5735. + 
  5736. + `\r'
  5737. +      Represents a carriage return, control-m, ASCII code 13.
  5738. + 
  5739. + `\t'
  5740. +      Represents a horizontal tab, control-i, ASCII code 9.
  5741. + 
  5742. + `\v'
  5743. +      Represents a vertical tab, control-k, ASCII code 11.
  5744. + 
  5745. + `\NNN'
  5746. +      Represents the octal value NNN, where NNN are one to three digits
  5747. +      between 0 and 7.  For example, the code for the ASCII ESC (escape)
  5748. +      character is `\033'.
  5749. + 
  5750. + `\xHH...'
  5751. +      Represents the hexadecimal value HH, where HH are hexadecimal
  5752. +      digits (`0' through `9' and either `A' through `F' or `a' through
  5753. +      `f').  Like the same construct in ANSI C, the escape sequence
  5754. +      continues until the first non-hexadecimal digit is seen.  However,
  5755. +      using more than two hexadecimal digits produces undefined results.
  5756. +      (The `\x' escape sequence is not allowed in POSIX `awk'.)
  5757. + 
  5758. +    A "constant regexp" is a regular expression description enclosed in
  5759. + slashes, such as `/^beginning and end$/'.  Most regexps used in `awk'
  5760. + programs are constant, but the `~' and `!~' operators can also match
  5761. + computed or "dynamic" regexps (*note How to Use Regular Expressions:
  5762. + Regexp Usage.).
  5763. + 
  5764. +    Constant regexps may be used like simple expressions.  When a
  5765. + constant regexp is not on the right hand side of the `~' or `!~'
  5766. + operators, it has the same meaning as if it appeared in a pattern, i.e.
  5767. + `($0 ~ /foo/)' (*note Expressions as Patterns: Expression Patterns.).
  5768. + This means that the two code segments,
  5769. + 
  5770. +      if ($0 ~ /barfly/ || $0 ~ /camelot/)
  5771. +          print "found"
  5772. + 
  5773. + and
  5774. + 
  5775. +      if (/barfly/ || /camelot/)
  5776. +          print "found"
  5777. + 
  5778. + are exactly equivalent.  One rather bizarre consequence of this rule is
  5779. + that the following boolean expression is legal, but does not do what
  5780. + the user intended:
  5781. + 
  5782. +      if (/foo/ ~ $1) print "found foo"
  5783. + 
  5784. +    This code is "obviously" testing `$1' for a match against the regexp
  5785. + `/foo/'.  But in fact, the expression `(/foo/ ~ $1)' actually means
  5786. + `(($0 ~ /foo/) ~ $1)'.  In other words, first match the input record
  5787. + against the regexp `/foo/'.  The result will be either a 0 or a 1,
  5788. + depending upon the success or failure of the match.  Then match that
  5789. + result against the first field in the record.
  5790. + 
  5791. +    Since it is unlikely that you would ever really wish to make this
  5792. + kind of test, `gawk' will issue a warning when it sees this construct in
  5793. + a program.
  5794. + 
  5795. +    Another consequence of this rule is that the assignment statement
  5796. + 
  5797. +      matches = /foo/
  5798. + 
  5799. + will assign either 0 or 1 to the variable `matches', depending upon the
  5800. + contents of the current input record.
  5801. + 
  5802. +    Constant regular expressions are also used as the first argument for
  5803. + the `sub' and `gsub' functions (*note Built-in Functions for String
  5804. + Manipulation: String Functions.).
  5805. + 
  5806. +    This feature of the language was never well documented until the
  5807. + POSIX specification.
  5808. + 
  5809. +    You may be wondering, when is
  5810. + 
  5811. +      $1 ~ /foo/ { ... }
  5812. + 
  5813. + preferable to
  5814. + 
  5815. +      $1 ~ "foo" { ... }
  5816. + 
  5817. +    Since the right-hand sides of both `~' operators are constants, it
  5818. + is more efficient to use the `/foo/' form: `awk' can note that you have
  5819. + supplied a regexp and store it internally in a form that makes pattern
  5820. + matching more efficient.  In the second form, `awk' must first convert
  5821. + the string into this internal form, and then perform the pattern
  5822. + matching.  The first form is also better style; it shows clearly that
  5823. + you intend a regexp match.
  5824. + 
  5825. + 
  5826. + File: gawk.info,  Node: Variables,  Next: Arithmetic Ops,  Prev: Constants,  Up: Expressions
  5827. + 
  5828. + Variables
  5829. + =========
  5830. + 
  5831. +    Variables let you give names to values and refer to them later.  You
  5832. + have already seen variables in many of the examples.  The name of a
  5833. + variable must be a sequence of letters, digits and underscores, but it
  5834. + may not begin with a digit.  Case is significant in variable names; `a'
  5835. + and `A' are distinct variables.
  5836. + 
  5837. +    A variable name is a valid expression by itself; it represents the
  5838. + variable's current value.  Variables are given new values with
  5839. + "assignment operators" and "increment operators".  *Note Assignment
  5840. + Expressions: Assignment Ops.
  5841. + 
  5842. +    A few variables have special built-in meanings, such as `FS', the
  5843. + field separator, and `NF', the number of fields in the current input
  5844. + record.  *Note Built-in Variables::, for a list of them.  These
  5845. + built-in variables can be used and assigned just like all other
  5846. + variables, but their values are also used or changed automatically by
  5847. + `awk'.  Each built-in variable's name is made entirely of upper case
  5848. + letters.
  5849. + 
  5850. +    Variables in `awk' can be assigned either numeric or string values.
  5851. + By default, variables are initialized to the null string, which is
  5852. + effectively zero if converted to a number.  There is no need to
  5853. + "initialize" each variable explicitly in `awk', the way you would in C
  5854. + or most other traditional languages.
  5855. + 
  5856. + * Menu:
  5857. + 
  5858. + * Assignment Options::          Setting variables on the command line
  5859. +                                 and a summary of command line syntax.
  5860. +                                 This is an advanced method of input.
  5861. + 
  5862. + 
  5863. + File: gawk.info,  Node: Assignment Options,  Prev: Variables,  Up: Variables
  5864. + 
  5865. + Assigning Variables on the Command Line
  5866. + ---------------------------------------
  5867. + 
  5868. +    You can set any `awk' variable by including a "variable assignment"
  5869. + among the arguments on the command line when you invoke `awk' (*note
  5870. + Invoking `awk': Command Line.).  Such an assignment has this form:
  5871. + 
  5872. +      VARIABLE=TEXT
  5873. + 
  5874. + With it, you can set a variable either at the beginning of the `awk'
  5875. + run or in between input files.
  5876. + 
  5877. +    If you precede the assignment with the `-v' option, like this:
  5878. + 
  5879. +      -v VARIABLE=TEXT
  5880. + 
  5881. + then the variable is set at the very beginning, before even the `BEGIN'
  5882. + rules are run.  The `-v' option and its assignment must precede all the
  5883. + file name arguments, as well as the program text.
  5884. + 
  5885. +    Otherwise, the variable assignment is performed at a time determined
  5886. + by its position among the input file arguments: after the processing of
  5887. + the preceding input file argument.  For example:
  5888. + 
  5889. +      awk '{ print $n }' n=4 inventory-shipped n=2 BBS-list
  5890. + 
  5891. + prints the value of field number `n' for all input records.  Before the
  5892. + first file is read, the command line sets the variable `n' equal to 4.
  5893. + This causes the fourth field to be printed in lines from the file
  5894. + `inventory-shipped'.  After the first file has finished, but before the
  5895. + second file is started, `n' is set to 2, so that the second field is
  5896. + printed in lines from `BBS-list'.
  5897. + 
  5898. +    Command line arguments are made available for explicit examination by
  5899. + the `awk' program in an array named `ARGV' (*note Built-in
  5900. + Variables::.).
  5901. + 
  5902. +    `awk' processes the values of command line assignments for escape
  5903. + sequences (*note Constant Expressions: Constants.).
  5904. + 
  5905. + 
  5906. + File: gawk.info,  Node: Arithmetic Ops,  Next: Concatenation,  Prev: Variables,  Up: Expressions
  5907. + 
  5908. + Arithmetic Operators
  5909. + ====================
  5910. + 
  5911. +    The `awk' language uses the common arithmetic operators when
  5912. + evaluating expressions.  All of these arithmetic operators follow normal
  5913. + precedence rules, and work as you would expect them to.  This example
  5914. + divides field three by field four, adds field two, stores the result
  5915. + into field one, and prints the resulting altered input record:
  5916. + 
  5917. +      awk '{ $1 = $2 + $3 / $4; print }' inventory-shipped
  5918. + 
  5919. +    The arithmetic operators in `awk' are:
  5920. + 
  5921. + `X + Y'
  5922. +      Addition.
  5923. + 
  5924. + `X - Y'
  5925. +      Subtraction.
  5926. + 
  5927. + `- X'
  5928. +      Negation.
  5929. + 
  5930. + `+ X'
  5931. +      Unary plus.  No real effect on the expression.
  5932. + 
  5933. + `X * Y'
  5934. +      Multiplication.
  5935. + 
  5936. + `X / Y'
  5937. +      Division.  Since all numbers in `awk' are double-precision
  5938. +      floating point, the result is not rounded to an integer: `3 / 4'
  5939. +      has the value 0.75.
  5940. + 
  5941. + `X % Y'
  5942. +      Remainder.  The quotient is rounded toward zero to an integer,
  5943. +      multiplied by Y and this result is subtracted from X.  This
  5944. +      operation is sometimes known as "trunc-mod."  The following
  5945. +      relation always holds:
  5946. + 
  5947. +           b * int(a / b) + (a % b) == a
  5948. + 
  5949. +      One possibly undesirable effect of this definition of remainder is
  5950. +      that `X % Y' is negative if X is negative.  Thus,
  5951. + 
  5952. +           -17 % 8 = -1
  5953. + 
  5954. +      In other `awk' implementations, the signedness of the remainder
  5955. +      may be machine dependent.
  5956. + 
  5957. + `X ^ Y'
  5958. + `X ** Y'
  5959. +      Exponentiation: X raised to the Y power.  `2 ^ 3' has the value 8.
  5960. +      The character sequence `**' is equivalent to `^'.  (The POSIX
  5961. +      standard only specifies the use of `^' for exponentiation.)
  5962. + 
  5963. + 
  5964. + File: gawk.info,  Node: Concatenation,  Next: Comparison Ops,  Prev: Arithmetic Ops,  Up: Expressions
  5965. + 
  5966. + String Concatenation
  5967. + ====================
  5968. + 
  5969. +    There is only one string operation: concatenation.  It does not have
  5970. + a specific operator to represent it.  Instead, concatenation is
  5971. + performed by writing expressions next to one another, with no operator.
  5972. + For example:
  5973. + 
  5974. +      awk '{ print "Field number one: " $1 }' BBS-list
  5975. + 
  5976. + produces, for the first record in `BBS-list':
  5977. + 
  5978. +      Field number one: aardvark
  5979. + 
  5980. +    Without the space in the string constant after the `:', the line
  5981. + would run together.  For example:
  5982. + 
  5983. +      awk '{ print "Field number one:" $1 }' BBS-list
  5984. + 
  5985. + produces, for the first record in `BBS-list':
  5986. + 
  5987. +      Field number one:aardvark
  5988. + 
  5989. +    Since string concatenation does not have an explicit operator, it is
  5990. + often necessary to insure that it happens where you want it to by
  5991. + enclosing the items to be concatenated in parentheses.  For example, the
  5992. + following code fragment does not concatenate `file' and `name' as you
  5993. + might expect:
  5994. + 
  5995. +      file = "file"
  5996. +      name = "name"
  5997. +      print "something meaningful" > file name
  5998. + 
  5999. + It is necessary to use the following:
  6000. + 
  6001. +      print "something meaningful" > (file name)
  6002. + 
  6003. +    We recommend you use parentheses around concatenation in all but the
  6004. + most common contexts (such as in the right-hand operand of `=').
  6005. + 
  6006. + 
  6007. + File: gawk.info,  Node: Comparison Ops,  Next: Boolean Ops,  Prev: Concatenation,  Up: Expressions
  6008. + 
  6009. + Comparison Expressions
  6010. + ======================
  6011. + 
  6012. +    "Comparison expressions" compare strings or numbers for
  6013. + relationships such as equality.  They are written using "relational
  6014. + operators", which are a superset of those in C.  Here is a table of
  6015. + them:
  6016. + 
  6017. + `X < Y'
  6018. +      True if X is less than Y.
  6019. + 
  6020. + `X <= Y'
  6021. +      True if X is less than or equal to Y.
  6022. + 
  6023. + `X > Y'
  6024. +      True if X is greater than Y.
  6025. + 
  6026. + `X >= Y'
  6027. +      True if X is greater than or equal to Y.
  6028. + 
  6029. + `X == Y'
  6030. +      True if X is equal to Y.
  6031. + 
  6032. + `X != Y'
  6033. +      True if X is not equal to Y.
  6034. + 
  6035. + `X ~ Y'
  6036. +      True if the string X matches the regexp denoted by Y.
  6037. + 
  6038. + `X !~ Y'
  6039. +      True if the string X does not match the regexp denoted by Y.
  6040. + 
  6041. + `SUBSCRIPT in ARRAY'
  6042. +      True if array ARRAY has an element with the subscript SUBSCRIPT.
  6043. + 
  6044. +    Comparison expressions have the value 1 if true and 0 if false.
  6045. + 
  6046. +    The rules `gawk' uses for performing comparisons are based on those
  6047. + in draft 11.2 of the POSIX standard.  The POSIX standard introduced the
  6048. + concept of a "numeric string", which is simply a string that looks like
  6049. + a number, for example, `" +2"'.
  6050. + 
  6051. +    When performing a relational operation, `gawk' considers the type of
  6052. + an operand to be the type it received on its last *assignment*, rather
  6053. + than the type of its last *use* (*note Numeric and String Values:
  6054. + Values.).  This type is *unknown* when the operand is from an
  6055. + "external" source: field variables, command line arguments, array
  6056. + elements resulting from a `split' operation, and the value of an
  6057. + `ENVIRON' element.  In this case only, if the operand is a numeric
  6058. + string, then it is considered to be of both string type and numeric
  6059. + type.  If at least one operand of a comparison is of string type only,
  6060. + then a string comparison is performed.  Any numeric operand will be
  6061. + converted to a string using the value of `CONVFMT' (*note Conversion of
  6062. + Strings and Numbers: Conversion.).  If one operand of a comparison is
  6063. + numeric, and the other operand is either numeric or both numeric and
  6064. + string, then `gawk' does a numeric comparison.  If both operands have
  6065. + both types, then the comparison is numeric.  Strings are compared by
  6066. + comparing the first character of each, then the second character of
  6067. + each, and so on.  Thus `"10"' is less than `"9"'.  If there are two
  6068. + strings where one is a prefix of the other, the shorter string is less
  6069. + than the longer one.  Thus `"abc"' is less than `"abcd"'.
  6070. + 
  6071. +    Here are some sample expressions, how `gawk' compares them, and what
  6072. + the result of the comparison is.
  6073. + 
  6074. + `1.5 <= 2.0'
  6075. +      numeric comparison (true)
  6076. + 
  6077. + `"abc" >= "xyz"'
  6078. +      string comparison (false)
  6079. + 
  6080. + `1.5 != " +2"'
  6081. +      string comparison (true)
  6082. + 
  6083. + `"1e2" < "3"'
  6084. +      string comparison (true)
  6085. + 
  6086. + `a = 2; b = "2"'
  6087. + `a == b'
  6088. +      string comparison (true)
  6089. + 
  6090. +      echo 1e2 3 | awk '{ print ($1 < $2) ? "true" : "false" }'
  6091. + 
  6092. + prints `false' since both `$1' and `$2' are numeric strings and thus
  6093. + have both string and numeric types, thus dictating a numeric comparison.
  6094. + 
  6095. +    The purpose of the comparison rules and the use of numeric strings is
  6096. + to attempt to produce the behavior that is "least surprising," while
  6097. + still "doing the right thing."
  6098. + 
  6099. +    String comparisons and regular expression comparisons are very
  6100. + different.  For example,
  6101. + 
  6102. +      $1 == "foo"
  6103. + 
  6104. + has the value of 1, or is true, if the first field of the current input
  6105. + record is precisely `foo'.  By contrast,
  6106. + 
  6107. +      $1 ~ /foo/
  6108. + 
  6109. + has the value 1 if the first field contains `foo', such as `foobar'.
  6110. + 
  6111. +    The right hand operand of the `~' and `!~' operators may be either a
  6112. + constant regexp (`/.../'), or it may be an ordinary expression, in
  6113. + which case the value of the expression as a string is a dynamic regexp
  6114. + (*note How to Use Regular Expressions: Regexp Usage.).
  6115. + 
  6116. +    In very recent implementations of `awk', a constant regular
  6117. + expression in slashes by itself is also an expression.  The regexp
  6118. + `/REGEXP/' is an abbreviation for this comparison expression:
  6119. + 
  6120. +      $0 ~ /REGEXP/
  6121. + 
  6122. +    In some contexts it may be necessary to write parentheses around the
  6123. + regexp to avoid confusing the `gawk' parser.  For example, `(/x/ - /y/)
  6124. + > threshold' is not allowed, but `((/x/) - (/y/)) > threshold' parses
  6125. + properly.
  6126. + 
  6127. +    One special place where `/foo/' is *not* an abbreviation for `$0 ~
  6128. + /foo/' is when it is the right-hand operand of `~' or `!~'! *Note
  6129. + Constant Expressions: Constants, where this is discussed in more detail.
  6130. + 
  6131. + 
  6132. + File: gawk.info,  Node: Boolean Ops,  Next: Assignment Ops,  Prev: Comparison Ops,  Up: Expressions
  6133. + 
  6134. + Boolean Expressions
  6135. + ===================
  6136. + 
  6137. +    A "boolean expression" is a combination of comparison expressions or
  6138. + matching expressions, using the boolean operators "or" (`||'), "and"
  6139. + (`&&'), and "not" (`!'), along with parentheses to control nesting.
  6140. + The truth of the boolean expression is computed by combining the truth
  6141. + values of the component expressions.
  6142. + 
  6143. +    Boolean expressions can be used wherever comparison and matching
  6144. + expressions can be used.  They can be used in `if', `while' `do' and
  6145. + `for' statements.  They have numeric values (1 if true, 0 if false),
  6146. + which come into play if the result of the boolean expression is stored
  6147. + in a variable, or used in arithmetic.
  6148. + 
  6149. +    In addition, every boolean expression is also a valid boolean
  6150. + pattern, so you can use it as a pattern to control the execution of
  6151. + rules.
  6152. + 
  6153. +    Here are descriptions of the three boolean operators, with an
  6154. + example of each.  It may be instructive to compare these examples with
  6155. + the analogous examples of boolean patterns (*note Boolean Operators and
  6156. + Patterns: Boolean Patterns.), which use the same boolean operators in
  6157. + patterns instead of expressions.
  6158. + 
  6159. + `BOOLEAN1 && BOOLEAN2'
  6160. +      True if both BOOLEAN1 and BOOLEAN2 are true.  For example, the
  6161. +      following statement prints the current input record if it contains
  6162. +      both `2400' and `foo'.
  6163. + 
  6164. +           if ($0 ~ /2400/ && $0 ~ /foo/) print
  6165. + 
  6166. +      The subexpression BOOLEAN2 is evaluated only if BOOLEAN1 is true.
  6167. +      This can make a difference when BOOLEAN2 contains expressions that
  6168. +      have side effects: in the case of `$0 ~ /foo/ && ($2 == bar++)',
  6169. +      the variable `bar' is not incremented if there is no `foo' in the
  6170. +      record.
  6171. + 
  6172. + `BOOLEAN1 || BOOLEAN2'
  6173. +      True if at least one of BOOLEAN1 or BOOLEAN2 is true.  For
  6174. +      example, the following command prints all records in the input
  6175. +      file `BBS-list' that contain *either* `2400' or `foo', or both.
  6176. + 
  6177. +           awk '{ if ($0 ~ /2400/ || $0 ~ /foo/) print }' BBS-list
  6178. + 
  6179. +      The subexpression BOOLEAN2 is evaluated only if BOOLEAN1 is false.
  6180. +      This can make a difference when BOOLEAN2 contains expressions
  6181. +      that have side effects.
  6182. + 
  6183. + `!BOOLEAN'
  6184. +      True if BOOLEAN is false.  For example, the following program
  6185. +      prints all records in the input file `BBS-list' that do *not*
  6186. +      contain the string `foo'.
  6187. + 
  6188. +           awk '{ if (! ($0 ~ /foo/)) print }' BBS-list
  6189. + 
  6190. + 
  6191. + File: gawk.info,  Node: Assignment Ops,  Next: Increment Ops,  Prev: Boolean Ops,  Up: Expressions
  6192. + 
  6193. + Assignment Expressions
  6194. + ======================
  6195. + 
  6196. +    An "assignment" is an expression that stores a new value into a
  6197. + variable.  For example, let's assign the value 1 to the variable `z':
  6198. + 
  6199. +      z = 1
  6200. + 
  6201. +    After this expression is executed, the variable `z' has the value 1.
  6202. + Whatever old value `z' had before the assignment is forgotten.
  6203. + 
  6204. +    Assignments can store string values also.  For example, this would
  6205. + store the value `"this food is good"' in the variable `message':
  6206. + 
  6207. +      thing = "food"
  6208. +      predicate = "good"
  6209. +      message = "this " thing " is " predicate
  6210. + 
  6211. + (This also illustrates concatenation of strings.)
  6212. + 
  6213. +    The `=' sign is called an "assignment operator".  It is the simplest
  6214. + assignment operator because the value of the right-hand operand is
  6215. + stored unchanged.
  6216. + 
  6217. +    Most operators (addition, concatenation, and so on) have no effect
  6218. + except to compute a value.  If you ignore the value, you might as well
  6219. + not use the operator.  An assignment operator is different; it does
  6220. + produce a value, but even if you ignore the value, the assignment still
  6221. + makes itself felt through the alteration of the variable.  We call this
  6222. + a "side effect".
  6223. + 
  6224. +    The left-hand operand of an assignment need not be a variable (*note
  6225. + Variables::.); it can also be a field (*note Changing the Contents of a
  6226. + Field: Changing Fields.) or an array element (*note Arrays in `awk':
  6227. + Arrays.).  These are all called "lvalues", which means they can appear
  6228. + on the left-hand side of an assignment operator.  The right-hand
  6229. + operand may be any expression; it produces the new value which the
  6230. + assignment stores in the specified variable, field or array element.
  6231. + 
  6232. +    It is important to note that variables do *not* have permanent types.
  6233. + The type of a variable is simply the type of whatever value it happens
  6234. + to hold at the moment.  In the following program fragment, the variable
  6235. + `foo' has a numeric value at first, and a string value later on:
  6236. + 
  6237. +      foo = 1
  6238. +      print foo
  6239. +      foo = "bar"
  6240. +      print foo
  6241. + 
  6242. + When the second assignment gives `foo' a string value, the fact that it
  6243. + previously had a numeric value is forgotten.
  6244. + 
  6245. +    An assignment is an expression, so it has a value: the same value
  6246. + that is assigned.  Thus, `z = 1' as an expression has the value 1.  One
  6247. + consequence of this is that you can write multiple assignments together:
  6248. + 
  6249. +      x = y = z = 0
  6250. + 
  6251. + stores the value 0 in all three variables.  It does this because the
  6252. + value of `z = 0', which is 0, is stored into `y', and then the value of
  6253. + `y = z = 0', which is 0, is stored into `x'.
  6254. + 
  6255. +    You can use an assignment anywhere an expression is called for.  For
  6256. + example, it is valid to write `x != (y = 1)' to set `y' to 1 and then
  6257. + test whether `x' equals 1.  But this style tends to make programs hard
  6258. + to read; except in a one-shot program, you should rewrite it to get rid
  6259. + of such nesting of assignments.  This is never very hard.
  6260. + 
  6261. +    Aside from `=', there are several other assignment operators that do
  6262. + arithmetic with the old value of the variable.  For example, the
  6263. + operator `+=' computes a new value by adding the right-hand value to
  6264. + the old value of the variable.  Thus, the following assignment adds 5
  6265. + to the value of `foo':
  6266. + 
  6267. +      foo += 5
  6268. + 
  6269. + This is precisely equivalent to the following:
  6270. + 
  6271. +      foo = foo + 5
  6272. + 
  6273. + Use whichever one makes the meaning of your program clearer.
  6274. + 
  6275. +    Here is a table of the arithmetic assignment operators.  In each
  6276. + case, the right-hand operand is an expression whose value is converted
  6277. + to a number.
  6278. + 
  6279. + `LVALUE += INCREMENT'
  6280. +      Adds INCREMENT to the value of LVALUE to make the new value of
  6281. +      LVALUE.
  6282. + 
  6283. + `LVALUE -= DECREMENT'
  6284. +      Subtracts DECREMENT from the value of LVALUE.
  6285. + 
  6286. + `LVALUE *= COEFFICIENT'
  6287. +      Multiplies the value of LVALUE by COEFFICIENT.
  6288. + 
  6289. + `LVALUE /= QUOTIENT'
  6290. +      Divides the value of LVALUE by QUOTIENT.
  6291. + 
  6292. + `LVALUE %= MODULUS'
  6293. +      Sets LVALUE to its remainder by MODULUS.
  6294. + 
  6295. + `LVALUE ^= POWER'
  6296. + `LVALUE **= POWER'
  6297. +      Raises LVALUE to the power POWER.  (Only the `^=' operator is
  6298. +      specified by POSIX.)
  6299. + 
  6300. + 
  6301. + File: gawk.info,  Node: Increment Ops,  Next: Conversion,  Prev: Assignment Ops,  Up: Expressions
  6302. + 
  6303. + Increment Operators
  6304. + ===================
  6305. + 
  6306. +    "Increment operators" increase or decrease the value of a variable
  6307. + by 1.  You could do the same thing with an assignment operator, so the
  6308. + increment operators add no power to the `awk' language; but they are
  6309. + convenient abbreviations for something very common.
  6310. + 
  6311. +    The operator to add 1 is written `++'.  It can be used to increment
  6312. + a variable either before or after taking its value.
  6313. + 
  6314. +    To pre-increment a variable V, write `++V'.  This adds 1 to the
  6315. + value of V and that new value is also the value of this expression.
  6316. + The assignment expression `V += 1' is completely equivalent.
  6317. + 
  6318. +    Writing the `++' after the variable specifies post-increment.  This
  6319. + increments the variable value just the same; the difference is that the
  6320. + value of the increment expression itself is the variable's *old* value.
  6321. + Thus, if `foo' has the value 4, then the expression `foo++' has the
  6322. + value 4, but it changes the value of `foo' to 5.
  6323. + 
  6324. +    The post-increment `foo++' is nearly equivalent to writing `(foo +=
  6325. + 1) - 1'.  It is not perfectly equivalent because all numbers in `awk'
  6326. + are floating point: in floating point, `foo + 1 - 1' does not
  6327. + necessarily equal `foo'.  But the difference is minute as long as you
  6328. + stick to numbers that are fairly small (less than a trillion).
  6329. + 
  6330. +    Any lvalue can be incremented.  Fields and array elements are
  6331. + incremented just like variables.  (Use `$(i++)' when you wish to do a
  6332. + field reference and a variable increment at the same time.  The
  6333. + parentheses are necessary because of the precedence of the field
  6334. + reference operator, `$'.)
  6335. + 
  6336. +    The decrement operator `--' works just like `++' except that it
  6337. + subtracts 1 instead of adding.  Like `++', it can be used before the
  6338. + lvalue to pre-decrement or after it to post-decrement.
  6339. + 
  6340. +    Here is a summary of increment and decrement expressions.
  6341. + 
  6342. + `++LVALUE'
  6343. +      This expression increments LVALUE and the new value becomes the
  6344. +      value of this expression.
  6345. + 
  6346. + `LVALUE++'
  6347. +      This expression causes the contents of LVALUE to be incremented.
  6348. +      The value of the expression is the *old* value of LVALUE.
  6349. + 
  6350. + `--LVALUE'
  6351. +      Like `++LVALUE', but instead of adding, it subtracts.  It
  6352. +      decrements LVALUE and delivers the value that results.
  6353. + 
  6354. + `LVALUE--'
  6355. +      Like `LVALUE++', but instead of adding, it subtracts.  It
  6356. +      decrements LVALUE.  The value of the expression is the *old* value
  6357. +      of LVALUE.
  6358. + 
  6359. + 
  6360. + File: gawk.info,  Node: Conversion,  Next: Values,  Prev: Increment Ops,  Up: Expressions
  6361. + 
  6362. + Conversion of Strings and Numbers
  6363. + =================================
  6364. + 
  6365. +    Strings are converted to numbers, and numbers to strings, if the
  6366. + context of the `awk' program demands it.  For example, if the value of
  6367. + either `foo' or `bar' in the expression `foo + bar' happens to be a
  6368. + string, it is converted to a number before the addition is performed.
  6369. + If numeric values appear in string concatenation, they are converted to
  6370. + strings.  Consider this:
  6371. + 
  6372. +      two = 2; three = 3
  6373. +      print (two three) + 4
  6374. + 
  6375. + This eventually prints the (numeric) value 27.  The numeric values of
  6376. + the variables `two' and `three' are converted to strings and
  6377. + concatenated together, and the resulting string is converted back to the
  6378. + number 23, to which 4 is then added.
  6379. + 
  6380. +    If, for some reason, you need to force a number to be converted to a
  6381. + string, concatenate the null string with that number.  To force a string
  6382. + to be converted to a number, add zero to that string.
  6383. + 
  6384. +    A string is converted to a number by interpreting a numeric prefix
  6385. + of the string as numerals: `"2.5"' converts to 2.5, `"1e3"' converts to
  6386. + 1000, and `"25fix"' has a numeric value of 25.  Strings that can't be
  6387. + interpreted as valid numbers are converted to zero.
  6388. + 
  6389. +    The exact manner in which numbers are converted into strings is
  6390. + controlled by the `awk' built-in variable `CONVFMT' (*note Built-in
  6391. + Variables::.).  Numbers are converted using a special version of the
  6392. + `sprintf' function (*note Built-in Functions: Built-in.) with `CONVFMT'
  6393. + as the format specifier.
  6394. + 
  6395. +    `CONVFMT''s default value is `"%.6g"', which prints a value with at
  6396. + least six significant digits.  For some applications you will want to
  6397. + change it to specify more precision.  Double precision on most modern
  6398. + machines gives you 16 or 17 decimal digits of precision.
  6399. + 
  6400. +    Strange results can happen if you set `CONVFMT' to a string that
  6401. + doesn't tell `sprintf' how to format floating point numbers in a useful
  6402. + way.  For example, if you forget the `%' in the format, all numbers
  6403. + will be converted to the same constant string.
  6404. + 
  6405. +    As a special case, if a number is an integer, then the result of
  6406. + converting it to a string is *always* an integer, no matter what the
  6407. + value of `CONVFMT' may be.  Given the following code fragment:
  6408. + 
  6409. +      CONVFMT = "%2.2f"
  6410. +      a = 12
  6411. +      b = a ""
  6412. + 
  6413. + `b' has the value `"12"', not `"12.00"'.
  6414. + 
  6415. +    Prior to the POSIX standard, `awk' specified that the value of
  6416. + `OFMT' was used for converting numbers to strings.  `OFMT' specifies
  6417. + the output format to use when printing numbers with `print'.  `CONVFMT'
  6418. + was introduced in order to separate the semantics of conversions from
  6419. + the semantics of printing.  Both `CONVFMT' and `OFMT' have the same
  6420. + default value: `"%.6g"'.  In the vast majority of cases, old `awk'
  6421. + programs will not change their behavior.  However, this use of `OFMT'
  6422. + is something to keep in mind if you must port your program to other
  6423. + implementations of `awk'; we recommend that instead of changing your
  6424. + programs, you just port `gawk' itself!
  6425. + 
  6426. + 
  6427. + File: gawk.info,  Node: Values,  Next: Conditional Exp,  Prev: Conversion,  Up: Expressions
  6428. + 
  6429. + Numeric and String Values
  6430. + =========================
  6431. + 
  6432. +    Through most of this manual, we present `awk' values (such as
  6433. + constants, fields, or variables) as *either* numbers *or* strings.
  6434. + This is a convenient way to think about them, since typically they are
  6435. + used in only one way, or the other.
  6436. + 
  6437. +    In truth though, `awk' values can be *both* string and numeric, at
  6438. + the same time.  Internally, `awk' represents values with a string, a
  6439. + (floating point) number, and an indication that one, the other, or both
  6440. + representations of the value are valid.
  6441. + 
  6442. +    Keeping track of both kinds of values is important for execution
  6443. + efficiency:  a variable can acquire a string value the first time it is
  6444. + used as a string, and then that string value can be used until the
  6445. + variable is assigned a new value.  Thus, if a variable with only a
  6446. + numeric value is used in several concatenations in a row, it only has
  6447. + to be given a string representation once.  The numeric value remains
  6448. + valid, so that no conversion back to a number is necessary if the
  6449. + variable is later used in an arithmetic expression.
  6450. + 
  6451. +    Tracking both kinds of values is also important for precise numerical
  6452. + calculations.  Consider the following:
  6453. + 
  6454. +      a = 123.321
  6455. +      CONVFMT = "%3.1f"
  6456. +      b = a " is a number"
  6457. +      c = a + 1.654
  6458. + 
  6459. + The variable `a' receives a string value in the concatenation and
  6460. + assignment to `b'.  The string value of `a' is `"123.3"'.  If the
  6461. + numeric value was lost when it was converted to a string, then the
  6462. + numeric use of `a' in the last statement would lose information.  `c'
  6463. + would be assigned the value 124.954 instead of 124.975.  Such errors
  6464. + accumulate rapidly, and very adversely affect numeric computations.
  6465. + 
  6466. +    Once a numeric value acquires a corresponding string value, it stays
  6467. + valid until a new assignment is made.  If `CONVFMT' (*note Conversion
  6468. + of Strings and Numbers: Conversion.) changes in the meantime, the old
  6469. + string value will still be used.  For example:
  6470. + 
  6471. +      BEGIN {
  6472. +          CONVFMT = "%2.2f"
  6473. +          a = 123.456
  6474. +          b = a ""                # force `a' to have string value too
  6475. +          printf "a = %s\n", a
  6476. +          CONVFMT = "%.6g"
  6477. +          printf "a = %s\n", a
  6478. +          a += 0                  # make `a' numeric only again
  6479. +          printf "a = %s\n", a    # use `a' as string
  6480. +      }
  6481. + 
  6482. + This program prints `a = 123.46' twice, and then prints `a = 123.456'.
  6483. + 
  6484. +    *Note Conversion of Strings and Numbers: Conversion, for the rules
  6485. + that specify how string values are made from numeric values.
  6486. + 
  6487. + 
  6488. + File: gawk.info,  Node: Conditional Exp,  Next: Function Calls,  Prev: Values,  Up: Expressions
  6489. + 
  6490. + Conditional Expressions
  6491. + =======================
  6492. + 
  6493. +    A "conditional expression" is a special kind of expression with
  6494. + three operands.  It allows you to use one expression's value to select
  6495. + one of two other expressions.
  6496. + 
  6497. +    The conditional expression looks the same as in the C language:
  6498. + 
  6499. +      SELECTOR ? IF-TRUE-EXP : IF-FALSE-EXP
  6500. + 
  6501. + There are three subexpressions.  The first, SELECTOR, is always
  6502. + computed first.  If it is "true" (not zero and not null) then
  6503. + IF-TRUE-EXP is computed next and its value becomes the value of the
  6504. + whole expression.  Otherwise, IF-FALSE-EXP is computed next and its
  6505. + value becomes the value of the whole expression.
  6506. + 
  6507. +    For example, this expression produces the absolute value of `x':
  6508. + 
  6509. +      x > 0 ? x : -x
  6510. + 
  6511. +    Each time the conditional expression is computed, exactly one of
  6512. + IF-TRUE-EXP and IF-FALSE-EXP is computed; the other is ignored.  This
  6513. + is important when the expressions contain side effects.  For example,
  6514. + this conditional expression examines element `i' of either array `a' or
  6515. + array `b', and increments `i'.
  6516. + 
  6517. +      x == y ? a[i++] : b[i++]
  6518. + 
  6519. + This is guaranteed to increment `i' exactly once, because each time one
  6520. + or the other of the two increment expressions is executed, and the
  6521. + other is not.
  6522. + 
  6523. + 
  6524. + File: gawk.info,  Node: Function Calls,  Next: Precedence,  Prev: Conditional Exp,  Up: Expressions
  6525. + 
  6526. + Function Calls
  6527. + ==============
  6528. + 
  6529. +    A "function" is a name for a particular calculation.  Because it has
  6530. + a name, you can ask for it by name at any point in the program.  For
  6531. + example, the function `sqrt' computes the square root of a number.
  6532. + 
  6533. +    A fixed set of functions are "built-in", which means they are
  6534. + available in every `awk' program.  The `sqrt' function is one of these.
  6535. + *Note Built-in Functions: Built-in, for a list of built-in functions
  6536. + and their descriptions.  In addition, you can define your own functions
  6537. + in the program for use elsewhere in the same program.  *Note
  6538. + User-defined Functions: User-defined, for how to do this.
  6539. + 
  6540. +    The way to use a function is with a "function call" expression,
  6541. + which consists of the function name followed by a list of "arguments"
  6542. + in parentheses.  The arguments are expressions which give the raw
  6543. + materials for the calculation that the function will do.  When there is
  6544. + more than one argument, they are separated by commas.  If there are no
  6545. + arguments, write just `()' after the function name.  Here are some
  6546. + examples:
  6547. + 
  6548. +      sqrt(x^2 + y^2)      # One argument
  6549. +      atan2(y, x)          # Two arguments
  6550. +      rand()               # No arguments
  6551. + 
  6552. +    *Do not put any space between the function name and the
  6553. + open-parenthesis!*  A user-defined function name looks just like the
  6554. + name of a variable, and space would make the expression look like
  6555. + concatenation of a variable with an expression inside parentheses.
  6556. + Space before the parenthesis is harmless with built-in functions, but
  6557. + it is best not to get into the habit of using space to avoid mistakes
  6558. + with user-defined functions.
  6559. + 
  6560. +    Each function expects a particular number of arguments.  For
  6561. + example, the `sqrt' function must be called with a single argument, the
  6562. + number to take the square root of:
  6563. + 
  6564. +      sqrt(ARGUMENT)
  6565. + 
  6566. +    Some of the built-in functions allow you to omit the final argument.
  6567. + If you do so, they use a reasonable default.  *Note Built-in Functions:
  6568. + Built-in, for full details.  If arguments are omitted in calls to
  6569. + user-defined functions, then those arguments are treated as local
  6570. + variables, initialized to the null string (*note User-defined
  6571. + Functions: User-defined.).
  6572. + 
  6573. +    Like every other expression, the function call has a value, which is
  6574. + computed by the function based on the arguments you give it.  In this
  6575. + example, the value of `sqrt(ARGUMENT)' is the square root of the
  6576. + argument.  A function can also have side effects, such as assigning the
  6577. + values of certain variables or doing I/O.
  6578. + 
  6579. +    Here is a command to read numbers, one number per line, and print the
  6580. + square root of each one:
  6581. + 
  6582. +      awk '{ print "The square root of", $1, "is", sqrt($1) }'
  6583. + 
  6584. + 
  6585. + File: gawk.info,  Node: Precedence,  Prev: Function Calls,  Up: Expressions
  6586. + 
  6587. + Operator Precedence (How Operators Nest)
  6588. + ========================================
  6589. + 
  6590. +    "Operator precedence" determines how operators are grouped, when
  6591. + different operators appear close by in one expression.  For example,
  6592. + `*' has higher precedence than `+'; thus, `a + b * c' means to multiply
  6593. + `b' and `c', and then add `a' to the product (i.e., `a + (b * c)').
  6594. + 
  6595. +    You can overrule the precedence of the operators by using
  6596. + parentheses.  You can think of the precedence rules as saying where the
  6597. + parentheses are assumed if you do not write parentheses yourself.  In
  6598. + fact, it is wise to always use parentheses whenever you have an unusual
  6599. + combination of operators, because other people who read the program may
  6600. + not remember what the precedence is in this case.  You might forget,
  6601. + too; then you could make a mistake.  Explicit parentheses will help
  6602. + prevent any such mistake.
  6603. + 
  6604. +    When operators of equal precedence are used together, the leftmost
  6605. + operator groups first, except for the assignment, conditional and
  6606. + exponentiation operators, which group in the opposite order.  Thus, `a
  6607. + - b + c' groups as `(a - b) + c'; `a = b = c' groups as `a = (b = c)'.
  6608. + 
  6609. +    The precedence of prefix unary operators does not matter as long as
  6610. + only unary operators are involved, because there is only one way to
  6611. + parse them--innermost first.  Thus, `$++i' means `$(++i)' and `++$x'
  6612. + means `++($x)'.  However, when another operator follows the operand,
  6613. + then the precedence of the unary operators can matter.  Thus, `$x^2'
  6614. + means `($x)^2', but `-x^2' means `-(x^2)', because `-' has lower
  6615. + precedence than `^' while `$' has higher precedence.
  6616. + 
  6617. +    Here is a table of the operators of `awk', in order of increasing
  6618. + precedence:
  6619. + 
  6620. + assignment
  6621. +      `=', `+=', `-=', `*=', `/=', `%=', `^=', `**='.  These operators
  6622. +      group right-to-left.  (The `**=' operator is not specified by
  6623. +      POSIX.)
  6624. + 
  6625. + conditional
  6626. +      `?:'.  This operator groups right-to-left.
  6627. + 
  6628. + logical "or".
  6629. +      `||'.
  6630. + 
  6631. + logical "and".
  6632. +      `&&'.
  6633. + 
  6634. + array membership
  6635. +      `in'.
  6636. + 
  6637. + matching
  6638. +      `~', `!~'.
  6639. + 
  6640. + relational, and redirection
  6641. +      The relational operators and the redirections have the same
  6642. +      precedence level.  Characters such as `>' serve both as
  6643. +      relationals and as redirections; the context distinguishes between
  6644. +      the two meanings.
  6645. + 
  6646. +      The relational operators are `<', `<=', `==', `!=', `>=' and `>'.
  6647. + 
  6648. +      The I/O redirection operators are `<', `>', `>>' and `|'.
  6649. + 
  6650. +      Note that I/O redirection operators in `print' and `printf'
  6651. +      statements belong to the statement level, not to expressions.  The
  6652. +      redirection does not produce an expression which could be the
  6653. +      operand of another operator.  As a result, it does not make sense
  6654. +      to use a redirection operator near another operator of lower
  6655. +      precedence, without parentheses.  Such combinations, for example
  6656. +      `print foo > a ? b : c', result in syntax errors.
  6657. + 
  6658. + concatenation
  6659. +      No special token is used to indicate concatenation.  The operands
  6660. +      are simply written side by side.
  6661. + 
  6662. + add, subtract
  6663. +      `+', `-'.
  6664. + 
  6665. + multiply, divide, mod
  6666. +      `*', `/', `%'.
  6667. + 
  6668. + unary plus, minus, "not"
  6669. +      `+', `-', `!'.
  6670. + 
  6671. + exponentiation
  6672. +      `^', `**'.  These operators group right-to-left.  (The `**'
  6673. +      operator is not specified by POSIX.)
  6674. + 
  6675. + increment, decrement
  6676. +      `++', `--'.
  6677. + 
  6678. + field
  6679. +      `$'.
  6680. + 
  6681. + 
  6682. + File: gawk.info,  Node: Statements,  Next: Arrays,  Prev: Expressions,  Up: Top
  6683. + 
  6684. + Control Statements in Actions
  6685. + *****************************
  6686. + 
  6687. +    "Control statements" such as `if', `while', and so on control the
  6688. + flow of execution in `awk' programs.  Most of the control statements in
  6689. + `awk' are patterned on similar statements in C.
  6690. + 
  6691. +    All the control statements start with special keywords such as `if'
  6692. + and `while', to distinguish them from simple expressions.
  6693. + 
  6694. +    Many control statements contain other statements; for example, the
  6695. + `if' statement contains another statement which may or may not be
  6696. + executed.  The contained statement is called the "body".  If you want
  6697. + to include more than one statement in the body, group them into a
  6698. + single compound statement with curly braces, separating them with
  6699. + newlines or semicolons.
  6700. + 
  6701. + * Menu:
  6702. + 
  6703. + * If Statement::                Conditionally execute
  6704. +                                 some `awk' statements.
  6705. + * While Statement::             Loop until some condition is satisfied.
  6706. + * Do Statement::                Do specified action while looping until some
  6707. +                                 condition is satisfied.
  6708. + * For Statement::               Another looping statement, that provides
  6709. +                                 initialization and increment clauses.
  6710. + * Break Statement::             Immediately exit the innermost enclosing loop.
  6711. + * Continue Statement::          Skip to the end of the innermost
  6712. +                                 enclosing loop.
  6713. + * Next Statement::              Stop processing the current input record.
  6714. + * Next File Statement::         Stop processing the current file.
  6715. + * Exit Statement::              Stop execution of `awk'.
  6716. + 
  6717. + 
  6718. + File: gawk.info,  Node: If Statement,  Next: While Statement,  Prev: Statements,  Up: Statements
  6719. + 
  6720. + The `if' Statement
  6721. + ==================
  6722. + 
  6723. +    The `if'-`else' statement is `awk''s decision-making statement.  It
  6724. + looks like this:
  6725. + 
  6726. +      if (CONDITION) THEN-BODY [else ELSE-BODY]
  6727. + 
  6728. + CONDITION is an expression that controls what the rest of the statement
  6729. + will do.  If CONDITION is true, THEN-BODY is executed; otherwise,
  6730. + ELSE-BODY is executed (assuming that the `else' clause is present).
  6731. + The `else' part of the statement is optional.  The condition is
  6732. + considered false if its value is zero or the null string, and true
  6733. + otherwise.
  6734. + 
  6735. +    Here is an example:
  6736. + 
  6737. +      if (x % 2 == 0)
  6738. +          print "x is even"
  6739. +      else
  6740. +          print "x is odd"
  6741. + 
  6742. +    In this example, if the expression `x % 2 == 0' is true (that is,
  6743. + the value of `x' is divisible by 2), then the first `print' statement
  6744. + is executed, otherwise the second `print' statement is performed.
  6745. + 
  6746. +    If the `else' appears on the same line as THEN-BODY, and THEN-BODY
  6747. + is not a compound statement (i.e., not surrounded by curly braces),
  6748. + then a semicolon must separate THEN-BODY from `else'.  To illustrate
  6749. + this, let's rewrite the previous example:
  6750. + 
  6751. +      awk '{ if (x % 2 == 0) print "x is even"; else
  6752. +              print "x is odd" }'
  6753. + 
  6754. + If you forget the `;', `awk' won't be able to parse the statement, and
  6755. + you will get a syntax error.
  6756. + 
  6757. +    We would not actually write this example this way, because a human
  6758. + reader might fail to see the `else' if it were not the first thing on
  6759. + its line.
  6760. + 
  6761. + 
  6762. + File: gawk.info,  Node: While Statement,  Next: Do Statement,  Prev: If Statement,  Up: Statements
  6763. + 
  6764. + The `while' Statement
  6765. + =====================
  6766. + 
  6767. +    In programming, a "loop" means a part of a program that is (or at
  6768. + least can be) executed two or more times in succession.
  6769. + 
  6770. +    The `while' statement is the simplest looping statement in `awk'.
  6771. + It repeatedly executes a statement as long as a condition is true.  It
  6772. + looks like this:
  6773. + 
  6774. +      while (CONDITION)
  6775. +        BODY
  6776. + 
  6777. + Here BODY is a statement that we call the "body" of the loop, and
  6778. + CONDITION is an expression that controls how long the loop keeps
  6779. + running.
  6780. + 
  6781. +    The first thing the `while' statement does is test CONDITION.  If
  6782. + CONDITION is true, it executes the statement BODY.  (CONDITION is true
  6783. + when the value is not zero and not a null string.)  After BODY has been
  6784. + executed, CONDITION is tested again, and if it is still true, BODY is
  6785. + executed again.  This process repeats until CONDITION is no longer
  6786. + true.  If CONDITION is initially false, the body of the loop is never
  6787. + executed.
  6788. + 
  6789. +    This example prints the first three fields of each record, one per
  6790. + line.
  6791. + 
  6792. +      awk '{ i = 1
  6793. +             while (i <= 3) {
  6794. +                 print $i
  6795. +                 i++
  6796. +             }
  6797. +      }'
  6798. + 
  6799. + Here the body of the loop is a compound statement enclosed in braces,
  6800. + containing two statements.
  6801. + 
  6802. +    The loop works like this: first, the value of `i' is set to 1.
  6803. + Then, the `while' tests whether `i' is less than or equal to three.
  6804. + This is the case when `i' equals one, so the `i'-th field is printed.
  6805. + Then the `i++' increments the value of `i' and the loop repeats.  The
  6806. + loop terminates when `i' reaches 4.
  6807. + 
  6808. +    As you can see, a newline is not required between the condition and
  6809. + the body; but using one makes the program clearer unless the body is a
  6810. + compound statement or is very simple.  The newline after the open-brace
  6811. + that begins the compound statement is not required either, but the
  6812. + program would be hard to read without it.
  6813. + 
  6814. + 
  6815. + File: gawk.info,  Node: Do Statement,  Next: For Statement,  Prev: While Statement,  Up: Statements
  6816. + 
  6817. + The `do'-`while' Statement
  6818. + ==========================
  6819. + 
  6820. +    The `do' loop is a variation of the `while' looping statement.  The
  6821. + `do' loop executes the BODY once, then repeats BODY as long as
  6822. + CONDITION is true.  It looks like this:
  6823. + 
  6824. +      do
  6825. +        BODY
  6826. +      while (CONDITION)
  6827. + 
  6828. +    Even if CONDITION is false at the start, BODY is executed at least
  6829. + once (and only once, unless executing BODY makes CONDITION true).
  6830. + Contrast this with the corresponding `while' statement:
  6831. + 
  6832. +      while (CONDITION)
  6833. +        BODY
  6834. + 
  6835. + This statement does not execute BODY even once if CONDITION is false to
  6836. + begin with.
  6837. + 
  6838. +    Here is an example of a `do' statement:
  6839. + 
  6840. +      awk '{ i = 1
  6841. +             do {
  6842. +                print $0
  6843. +                i++
  6844. +             } while (i <= 10)
  6845. +      }'
  6846. + 
  6847. + prints each input record ten times.  It isn't a very realistic example,
  6848. + since in this case an ordinary `while' would do just as well.  But this
  6849. + reflects actual experience; there is only occasionally a real use for a
  6850. + `do' statement.
  6851. + 
  6852. diff -rc --new-file /src/baseline/gawk-2.15.5/gawk.info-5 gawk-2.15.5/gawk.info-5
  6853. *** /src/baseline/gawk-2.15.5/gawk.info-5    Thu Jan  1 00:00:00 1970
  6854. --- gawk-2.15.5/gawk.info-5    Sun Jun 12 22:28:52 1994
  6855. ***************
  6856. *** 0 ****
  6857. --- 1,1256 ----
  6858. + This is Info file gawk.info, produced by Makeinfo-1.55 from the input
  6859. + file /gnu/src/amiga/gawk-2.15.5/gawk.texi.
  6860. + 
  6861. +    This file documents `awk', a program that you can use to select
  6862. + particular records in a file and perform operations upon them.
  6863. + 
  6864. +    This is Edition 0.15 of `The GAWK Manual',
  6865. + for the 2.15 version of the GNU implementation
  6866. + of AWK.
  6867. + 
  6868. +    Copyright (C) 1989, 1991, 1992, 1993 Free Software Foundation, Inc.
  6869. + 
  6870. +    Permission is granted to make and distribute verbatim copies of this
  6871. + manual provided the copyright notice and this permission notice are
  6872. + preserved on all copies.
  6873. + 
  6874. +    Permission is granted to copy and distribute modified versions of
  6875. + this manual under the conditions for verbatim copying, provided that
  6876. + the entire resulting derived work is distributed under the terms of a
  6877. + permission notice identical to this one.
  6878. + 
  6879. +    Permission is granted to copy and distribute translations of this
  6880. + manual into another language, under the above conditions for modified
  6881. + versions, except that this permission notice may be stated in a
  6882. + translation approved by the Foundation.
  6883. + 
  6884. + 
  6885. + File: gawk.info,  Node: For Statement,  Next: Break Statement,  Prev: Do Statement,  Up: Statements
  6886. + 
  6887. + The `for' Statement
  6888. + ===================
  6889. + 
  6890. +    The `for' statement makes it more convenient to count iterations of a
  6891. + loop.  The general form of the `for' statement looks like this:
  6892. + 
  6893. +      for (INITIALIZATION; CONDITION; INCREMENT)
  6894. +        BODY
  6895. + 
  6896. + This statement starts by executing INITIALIZATION.  Then, as long as
  6897. + CONDITION is true, it repeatedly executes BODY and then INCREMENT.
  6898. + Typically INITIALIZATION sets a variable to either zero or one,
  6899. + INCREMENT adds 1 to it, and CONDITION compares it against the desired
  6900. + number of iterations.
  6901. + 
  6902. +    Here is an example of a `for' statement:
  6903. + 
  6904. +      awk '{ for (i = 1; i <= 3; i++)
  6905. +                print $i
  6906. +      }'
  6907. + 
  6908. + This prints the first three fields of each input record, one field per
  6909. + line.
  6910. + 
  6911. +    In the `for' statement, BODY stands for any statement, but
  6912. + INITIALIZATION, CONDITION and INCREMENT are just expressions.  You
  6913. + cannot set more than one variable in the INITIALIZATION part unless you
  6914. + use a multiple assignment statement such as `x = y = 0', which is
  6915. + possible only if all the initial values are equal.  (But you can
  6916. + initialize additional variables by writing their assignments as
  6917. + separate statements preceding the `for' loop.)
  6918. + 
  6919. +    The same is true of the INCREMENT part; to increment additional
  6920. + variables, you must write separate statements at the end of the loop.
  6921. + The C compound expression, using C's comma operator, would be useful in
  6922. + this context, but it is not supported in `awk'.
  6923. + 
  6924. +    Most often, INCREMENT is an increment expression, as in the example
  6925. + above.  But this is not required; it can be any expression whatever.
  6926. + For example, this statement prints all the powers of 2 between 1 and
  6927. + 100:
  6928. + 
  6929. +      for (i = 1; i <= 100; i *= 2)
  6930. +        print i
  6931. + 
  6932. +    Any of the three expressions in the parentheses following the `for'
  6933. + may be omitted if there is nothing to be done there.  Thus,
  6934. + `for (;x > 0;)' is equivalent to `while (x > 0)'.  If the CONDITION is
  6935. + omitted, it is treated as TRUE, effectively yielding an "infinite loop"
  6936. + (i.e., a loop that will never terminate).
  6937. + 
  6938. +    In most cases, a `for' loop is an abbreviation for a `while' loop,
  6939. + as shown here:
  6940. + 
  6941. +      INITIALIZATION
  6942. +      while (CONDITION) {
  6943. +        BODY
  6944. +        INCREMENT
  6945. +      }
  6946. + 
  6947. + The only exception is when the `continue' statement (*note The
  6948. + `continue' Statement: Continue Statement.) is used inside the loop;
  6949. + changing a `for' statement to a `while' statement in this way can
  6950. + change the effect of the `continue' statement inside the loop.
  6951. + 
  6952. +    There is an alternate version of the `for' loop, for iterating over
  6953. + all the indices of an array:
  6954. + 
  6955. +      for (i in array)
  6956. +          DO SOMETHING WITH array[i]
  6957. + 
  6958. + *Note Arrays in `awk': Arrays, for more information on this version of
  6959. + the `for' loop.
  6960. + 
  6961. +    The `awk' language has a `for' statement in addition to a `while'
  6962. + statement because often a `for' loop is both less work to type and more
  6963. + natural to think of.  Counting the number of iterations is very common
  6964. + in loops.  It can be easier to think of this counting as part of
  6965. + looping rather than as something to do inside the loop.
  6966. + 
  6967. +    The next section has more complicated examples of `for' loops.
  6968. + 
  6969. + 
  6970. + File: gawk.info,  Node: Break Statement,  Next: Continue Statement,  Prev: For Statement,  Up: Statements
  6971. + 
  6972. + The `break' Statement
  6973. + =====================
  6974. + 
  6975. +    The `break' statement jumps out of the innermost `for', `while', or
  6976. + `do'-`while' loop that encloses it.  The following example finds the
  6977. + smallest divisor of any integer, and also identifies prime numbers:
  6978. + 
  6979. +      awk '# find smallest divisor of num
  6980. +           { num = $1
  6981. +             for (div = 2; div*div <= num; div++)
  6982. +               if (num % div == 0)
  6983. +                 break
  6984. +             if (num % div == 0)
  6985. +               printf "Smallest divisor of %d is %d\n", num, div
  6986. +             else
  6987. +               printf "%d is prime\n", num  }'
  6988. + 
  6989. +    When the remainder is zero in the first `if' statement, `awk'
  6990. + immediately "breaks out" of the containing `for' loop.  This means that
  6991. + `awk' proceeds immediately to the statement following the loop and
  6992. + continues processing.  (This is very different from the `exit'
  6993. + statement which stops the entire `awk' program.  *Note The `exit'
  6994. + Statement: Exit Statement.)
  6995. + 
  6996. +    Here is another program equivalent to the previous one.  It
  6997. + illustrates how the CONDITION of a `for' or `while' could just as well
  6998. + be replaced with a `break' inside an `if':
  6999. + 
  7000. +      awk '# find smallest divisor of num
  7001. +           { num = $1
  7002. +             for (div = 2; ; div++) {
  7003. +               if (num % div == 0) {
  7004. +                 printf "Smallest divisor of %d is %d\n", num, div
  7005. +                 break
  7006. +               }
  7007. +               if (div*div > num) {
  7008. +                 printf "%d is prime\n", num
  7009. +                 break
  7010. +               }
  7011. +             }
  7012. +      }'
  7013. + 
  7014. + 
  7015. + File: gawk.info,  Node: Continue Statement,  Next: Next Statement,  Prev: Break Statement,  Up: Statements
  7016. + 
  7017. + The `continue' Statement
  7018. + ========================
  7019. + 
  7020. +    The `continue' statement, like `break', is used only inside `for',
  7021. + `while', and `do'-`while' loops.  It skips over the rest of the loop
  7022. + body, causing the next cycle around the loop to begin immediately.
  7023. + Contrast this with `break', which jumps out of the loop altogether.
  7024. + Here is an example:
  7025. + 
  7026. +      # print names that don't contain the string "ignore"
  7027. +      
  7028. +      # first, save the text of each line
  7029. +      { names[NR] = $0 }
  7030. +      
  7031. +      # print what we're interested in
  7032. +      END {
  7033. +         for (x in names) {
  7034. +             if (names[x] ~ /ignore/)
  7035. +                 continue
  7036. +             print names[x]
  7037. +         }
  7038. +      }
  7039. + 
  7040. +    If one of the input records contains the string `ignore', this
  7041. + example skips the print statement for that record, and continues back to
  7042. + the first statement in the loop.
  7043. + 
  7044. +    This is not a practical example of `continue', since it would be
  7045. + just as easy to write the loop like this:
  7046. + 
  7047. +      for (x in names)
  7048. +        if (names[x] !~ /ignore/)
  7049. +          print names[x]
  7050. + 
  7051. +    The `continue' statement in a `for' loop directs `awk' to skip the
  7052. + rest of the body of the loop, and resume execution with the
  7053. + increment-expression of the `for' statement.  The following program
  7054. + illustrates this fact:
  7055. + 
  7056. +      awk 'BEGIN {
  7057. +           for (x = 0; x <= 20; x++) {
  7058. +               if (x == 5)
  7059. +                   continue
  7060. +               printf ("%d ", x)
  7061. +           }
  7062. +           print ""
  7063. +      }'
  7064. + 
  7065. + This program prints all the numbers from 0 to 20, except for 5, for
  7066. + which the `printf' is skipped.  Since the increment `x++' is not
  7067. + skipped, `x' does not remain stuck at 5.  Contrast the `for' loop above
  7068. + with the `while' loop:
  7069. + 
  7070. +      awk 'BEGIN {
  7071. +           x = 0
  7072. +           while (x <= 20) {
  7073. +               if (x == 5)
  7074. +                   continue
  7075. +               printf ("%d ", x)
  7076. +               x++
  7077. +           }
  7078. +           print ""
  7079. +      }'
  7080. + 
  7081. + This program loops forever once `x' gets to 5.
  7082. + 
  7083. +    As described above, the `continue' statement has no meaning when
  7084. + used outside the body of a loop.  However, although it was never
  7085. + documented, historical implementations of `awk' have treated the
  7086. + `continue' statement outside of a loop as if it were a `next' statement
  7087. + (*note The `next' Statement: Next Statement.).  By default, `gawk'
  7088. + silently supports this usage.  However, if `-W posix' has been
  7089. + specified on the command line (*note Invoking `awk': Command Line.), it
  7090. + will be treated as an error, since the POSIX standard specifies that
  7091. + `continue' should only be used inside the body of a loop.
  7092. + 
  7093. + 
  7094. + File: gawk.info,  Node: Next Statement,  Next: Next File Statement,  Prev: Continue Statement,  Up: Statements
  7095. + 
  7096. + The `next' Statement
  7097. + ====================
  7098. + 
  7099. +    The `next' statement forces `awk' to immediately stop processing the
  7100. + current record and go on to the next record.  This means that no
  7101. + further rules are executed for the current record.  The rest of the
  7102. + current rule's action is not executed either.
  7103. + 
  7104. +    Contrast this with the effect of the `getline' function (*note
  7105. + Explicit Input with `getline': Getline.).  That too causes `awk' to
  7106. + read the next record immediately, but it does not alter the flow of
  7107. + control in any way.  So the rest of the current action executes with a
  7108. + new input record.
  7109. + 
  7110. +    At the highest level, `awk' program execution is a loop that reads
  7111. + an input record and then tests each rule's pattern against it.  If you
  7112. + think of this loop as a `for' statement whose body contains the rules,
  7113. + then the `next' statement is analogous to a `continue' statement: it
  7114. + skips to the end of the body of this implicit loop, and executes the
  7115. + increment (which reads another record).
  7116. + 
  7117. +    For example, if your `awk' program works only on records with four
  7118. + fields, and you don't want it to fail when given bad input, you might
  7119. + use this rule near the beginning of the program:
  7120. + 
  7121. +      NF != 4 {
  7122. +        printf("line %d skipped: doesn't have 4 fields", FNR) > "/dev/stderr"
  7123. +        next
  7124. +      }
  7125. + 
  7126. + so that the following rules will not see the bad record.  The error
  7127. + message is redirected to the standard error output stream, as error
  7128. + messages should be.  *Note Standard I/O Streams: Special Files.
  7129. + 
  7130. +    According to the POSIX standard, the behavior is undefined if the
  7131. + `next' statement is used in a `BEGIN' or `END' rule.  `gawk' will treat
  7132. + it as a syntax error.
  7133. + 
  7134. +    If the `next' statement causes the end of the input to be reached,
  7135. + then the code in the `END' rules, if any, will be executed.  *Note
  7136. + `BEGIN' and `END' Special Patterns: BEGIN/END.
  7137. + 
  7138. + 
  7139. + File: gawk.info,  Node: Next File Statement,  Next: Exit Statement,  Prev: Next Statement,  Up: Statements
  7140. + 
  7141. + The `next file' Statement
  7142. + =========================
  7143. + 
  7144. +    The `next file' statement is similar to the `next' statement.
  7145. + However, instead of abandoning processing of the current record, the
  7146. + `next file' statement instructs `awk' to stop processing the current
  7147. + data file.
  7148. + 
  7149. +    Upon execution of the `next file' statement, `FILENAME' is updated
  7150. + to the name of the next data file listed on the command line, `FNR' is
  7151. + reset to 1, and processing starts over with the first rule in the
  7152. + progam.  *Note Built-in Variables::.
  7153. + 
  7154. +    If the `next file' statement causes the end of the input to be
  7155. + reached, then the code in the `END' rules, if any, will be executed.
  7156. + *Note `BEGIN' and `END' Special Patterns: BEGIN/END.
  7157. + 
  7158. +    The `next file' statement is a `gawk' extension; it is not
  7159. + (currently) available in any other `awk' implementation.  You can
  7160. + simulate its behavior by creating a library file named `nextfile.awk',
  7161. + with the following contents.  (This sample program uses user-defined
  7162. + functions, a feature that has not been presented yet.  *Note
  7163. + User-defined Functions: User-defined, for more information.)
  7164. + 
  7165. +      # nextfile --- function to skip remaining records in current file
  7166. +      
  7167. +      # this should be read in before the "main" awk program
  7168. +      
  7169. +      function nextfile() { _abandon_ = FILENAME; next }
  7170. +      
  7171. +      _abandon_ == FILENAME && FNR > 1   { next }
  7172. +      _abandon_ == FILENAME && FNR == 1  { _abandon_ = "" }
  7173. + 
  7174. +    The `nextfile' function simply sets a "private" variable(1) to the
  7175. + name of the current data file, and then retrieves the next record.
  7176. + Since this file is read before the main `awk' program, the rules that
  7177. + follows the function definition will be executed before the rules in
  7178. + the main program.  The first rule continues to skip records as long as
  7179. + the name of the input file has not changed, and this is not the first
  7180. + record in the file.  This rule is sufficient most of the time.  But
  7181. + what if the *same* data file is named twice in a row on the command
  7182. + line?  This rule would not process the data file the second time.  The
  7183. + second rule catches this case: If the data file name is what was being
  7184. + skipped, but `FNR' is 1, then this is the second time the file is being
  7185. + processed, and it should not be skipped.
  7186. + 
  7187. +    The `next file' statement would be useful if you have many data
  7188. + files to process, and due to the nature of the data, you expect that you
  7189. + would not want to process every record in the file.  In order to move
  7190. + on to the next data file, you would have to continue scanning the
  7191. + unwanted records (as described above).  The `next file' statement
  7192. + accomplishes this much more efficiently.
  7193. + 
  7194. +    ---------- Footnotes ----------
  7195. + 
  7196. +    (1)  Since all variables in `awk' are global, this program uses the
  7197. + common practice of prefixing the variable name with an underscore.  In
  7198. + fact, it also suffixes the variable name with an underscore, as extra
  7199. + insurance against using a variable name that might be used in some
  7200. + other library file.
  7201. + 
  7202. + 
  7203. + File: gawk.info,  Node: Exit Statement,  Prev: Next File Statement,  Up: Statements
  7204. + 
  7205. + The `exit' Statement
  7206. + ====================
  7207. + 
  7208. +    The `exit' statement causes `awk' to immediately stop executing the
  7209. + current rule and to stop processing input; any remaining input is
  7210. + ignored.
  7211. + 
  7212. +    If an `exit' statement is executed from a `BEGIN' rule the program
  7213. + stops processing everything immediately.  No input records are read.
  7214. + However, if an `END' rule is present, it is executed (*note `BEGIN' and
  7215. + `END' Special Patterns: BEGIN/END.).
  7216. + 
  7217. +    If `exit' is used as part of an `END' rule, it causes the program to
  7218. + stop immediately.
  7219. + 
  7220. +    An `exit' statement that is part of an ordinary rule (that is, not
  7221. + part of a `BEGIN' or `END' rule) stops the execution of any further
  7222. + automatic rules, but the `END' rule is executed if there is one.  If
  7223. + you do not want the `END' rule to do its job in this case, you can set
  7224. + a variable to nonzero before the `exit' statement, and check that
  7225. + variable in the `END' rule.
  7226. + 
  7227. +    If an argument is supplied to `exit', its value is used as the exit
  7228. + status code for the `awk' process.  If no argument is supplied, `exit'
  7229. + returns status zero (success).
  7230. + 
  7231. +    For example, let's say you've discovered an error condition you
  7232. + really don't know how to handle.  Conventionally, programs report this
  7233. + by exiting with a nonzero status.  Your `awk' program can do this using
  7234. + an `exit' statement with a nonzero argument.  Here's an example of this:
  7235. + 
  7236. +      BEGIN {
  7237. +             if (("date" | getline date_now) < 0) {
  7238. +               print "Can't get system date" > "/dev/stderr"
  7239. +               exit 4
  7240. +             }
  7241. +      }
  7242. + 
  7243. + 
  7244. + File: gawk.info,  Node: Arrays,  Next: Built-in,  Prev: Statements,  Up: Top
  7245. + 
  7246. + Arrays in `awk'
  7247. + ***************
  7248. + 
  7249. +    An "array" is a table of values, called "elements".  The elements of
  7250. + an array are distinguished by their indices.  "Indices" may be either
  7251. + numbers or strings.  Each array has a name, which looks like a variable
  7252. + name, but must not be in use as a variable name in the same `awk'
  7253. + program.
  7254. + 
  7255. + * Menu:
  7256. + 
  7257. + * Array Intro::                 Introduction to Arrays
  7258. + * Reference to Elements::       How to examine one element of an array.
  7259. + * Assigning Elements::          How to change an element of an array.
  7260. + * Array Example::               Basic Example of an Array
  7261. + * Scanning an Array::           A variation of the `for' statement.
  7262. +                                 It loops through the indices of
  7263. +                                 an array's existing elements.
  7264. + * Delete::                      The `delete' statement removes
  7265. +                                 an element from an array.
  7266. + * Numeric Array Subscripts::    How to use numbers as subscripts in `awk'.
  7267. + * Multi-dimensional::           Emulating multi-dimensional arrays in `awk'.
  7268. + * Multi-scanning::              Scanning multi-dimensional arrays.
  7269. + 
  7270. + 
  7271. + File: gawk.info,  Node: Array Intro,  Next: Reference to Elements,  Prev: Arrays,  Up: Arrays
  7272. + 
  7273. + Introduction to Arrays
  7274. + ======================
  7275. + 
  7276. +    The `awk' language has one-dimensional "arrays" for storing groups
  7277. + of related strings or numbers.
  7278. + 
  7279. +    Every `awk' array must have a name.  Array names have the same
  7280. + syntax as variable names; any valid variable name would also be a valid
  7281. + array name.  But you cannot use one name in both ways (as an array and
  7282. + as a variable) in one `awk' program.
  7283. + 
  7284. +    Arrays in `awk' superficially resemble arrays in other programming
  7285. + languages; but there are fundamental differences.  In `awk', you don't
  7286. + need to specify the size of an array before you start to use it.
  7287. + Additionally, any number or string in `awk' may be used as an array
  7288. + index.
  7289. + 
  7290. +    In most other languages, you have to "declare" an array and specify
  7291. + how many elements or components it contains.  In such languages, the
  7292. + declaration causes a contiguous block of memory to be allocated for that
  7293. + many elements.  An index in the array must be a positive integer; for
  7294. + example, the index 0 specifies the first element in the array, which is
  7295. + actually stored at the beginning of the block of memory.  Index 1
  7296. + specifies the second element, which is stored in memory right after the
  7297. + first element, and so on.  It is impossible to add more elements to the
  7298. + array, because it has room for only as many elements as you declared.
  7299. + 
  7300. +    A contiguous array of four elements might look like this,
  7301. + conceptually, if the element values are `8', `"foo"', `""' and `30':
  7302. + 
  7303. +      +---------+---------+--------+---------+
  7304. +      |    8    |  "foo"  |   ""   |    30   |    value
  7305. +      +---------+---------+--------+---------+
  7306. +           0         1         2         3        index
  7307. + 
  7308. + Only the values are stored; the indices are implicit from the order of
  7309. + the values.  `8' is the value at index 0, because `8' appears in the
  7310. + position with 0 elements before it.
  7311. + 
  7312. +    Arrays in `awk' are different: they are "associative".  This means
  7313. + that each array is a collection of pairs: an index, and its
  7314. + corresponding array element value:
  7315. + 
  7316. +      Element 4     Value 30
  7317. +      Element 2     Value "foo"
  7318. +      Element 1     Value 8
  7319. +      Element 3     Value ""
  7320. + 
  7321. + We have shown the pairs in jumbled order because their order is
  7322. + irrelevant.
  7323. + 
  7324. +    One advantage of an associative array is that new pairs can be added
  7325. + at any time.  For example, suppose we add to the above array a tenth
  7326. + element whose value is `"number ten"'.  The result is this:
  7327. + 
  7328. +      Element 10    Value "number ten"
  7329. +      Element 4     Value 30
  7330. +      Element 2     Value "foo"
  7331. +      Element 1     Value 8
  7332. +      Element 3     Value ""
  7333. + 
  7334. + Now the array is "sparse" (i.e., some indices are missing): it has
  7335. + elements 1-4 and 10, but doesn't have elements 5, 6, 7, 8, or 9.
  7336. + 
  7337. +    Another consequence of associative arrays is that the indices don't
  7338. + have to be positive integers.  Any number, or even a string, can be an
  7339. + index.  For example, here is an array which translates words from
  7340. + English into French:
  7341. + 
  7342. +      Element "dog" Value "chien"
  7343. +      Element "cat" Value "chat"
  7344. +      Element "one" Value "un"
  7345. +      Element 1     Value "un"
  7346. + 
  7347. + Here we decided to translate the number 1 in both spelled-out and
  7348. + numeric form--thus illustrating that a single array can have both
  7349. + numbers and strings as indices.
  7350. + 
  7351. +    When `awk' creates an array for you, e.g., with the `split' built-in
  7352. + function, that array's indices are consecutive integers starting at 1.
  7353. + (*Note Built-in Functions for String Manipulation: String Functions.)
  7354. + 
  7355. + 
  7356. + File: gawk.info,  Node: Reference to Elements,  Next: Assigning Elements,  Prev: Array Intro,  Up: Arrays
  7357. + 
  7358. + Referring to an Array Element
  7359. + =============================
  7360. + 
  7361. +    The principal way of using an array is to refer to one of its
  7362. + elements.  An array reference is an expression which looks like this:
  7363. + 
  7364. +      ARRAY[INDEX]
  7365. + 
  7366. + Here, ARRAY is the name of an array.  The expression INDEX is the index
  7367. + of the element of the array that you want.
  7368. + 
  7369. +    The value of the array reference is the current value of that array
  7370. + element.  For example, `foo[4.3]' is an expression for the element of
  7371. + array `foo' at index 4.3.
  7372. + 
  7373. +    If you refer to an array element that has no recorded value, the
  7374. + value of the reference is `""', the null string.  This includes elements
  7375. + to which you have not assigned any value, and elements that have been
  7376. + deleted (*note The `delete' Statement: Delete.).  Such a reference
  7377. + automatically creates that array element, with the null string as its
  7378. + value.  (In some cases, this is unfortunate, because it might waste
  7379. + memory inside `awk').
  7380. + 
  7381. +    You can find out if an element exists in an array at a certain index
  7382. + with the expression:
  7383. + 
  7384. +      INDEX in ARRAY
  7385. + 
  7386. + This expression tests whether or not the particular index exists,
  7387. + without the side effect of creating that element if it is not present.
  7388. + The expression has the value 1 (true) if `ARRAY[INDEX]' exists, and 0
  7389. + (false) if it does not exist.
  7390. + 
  7391. +    For example, to test whether the array `frequencies' contains the
  7392. + index `"2"', you could write this statement:
  7393. + 
  7394. +      if ("2" in frequencies) print "Subscript \"2\" is present."
  7395. + 
  7396. +    Note that this is *not* a test of whether or not the array
  7397. + `frequencies' contains an element whose *value* is `"2"'.  (There is no
  7398. + way to do that except to scan all the elements.)  Also, this *does not*
  7399. + create `frequencies["2"]', while the following (incorrect) alternative
  7400. + would do so:
  7401. + 
  7402. +      if (frequencies["2"] != "") print "Subscript \"2\" is present."
  7403. + 
  7404. + 
  7405. + File: gawk.info,  Node: Assigning Elements,  Next: Array Example,  Prev: Reference to Elements,  Up: Arrays
  7406. + 
  7407. + Assigning Array Elements
  7408. + ========================
  7409. + 
  7410. +    Array elements are lvalues: they can be assigned values just like
  7411. + `awk' variables:
  7412. + 
  7413. +      ARRAY[SUBSCRIPT] = VALUE
  7414. + 
  7415. + Here ARRAY is the name of your array.  The expression SUBSCRIPT is the
  7416. + index of the element of the array that you want to assign a value.  The
  7417. + expression VALUE is the value you are assigning to that element of the
  7418. + array.
  7419. + 
  7420. + 
  7421. + File: gawk.info,  Node: Array Example,  Next: Scanning an Array,  Prev: Assigning Elements,  Up: Arrays
  7422. + 
  7423. + Basic Example of an Array
  7424. + =========================
  7425. + 
  7426. +    The following program takes a list of lines, each beginning with a
  7427. + line number, and prints them out in order of line number.  The line
  7428. + numbers are not in order, however, when they are first read:  they are
  7429. + scrambled.  This program sorts the lines by making an array using the
  7430. + line numbers as subscripts.  It then prints out the lines in sorted
  7431. + order of their numbers.  It is a very simple program, and gets confused
  7432. + if it encounters repeated numbers, gaps, or lines that don't begin with
  7433. + a number.
  7434. + 
  7435. +      {
  7436. +        if ($1 > max)
  7437. +          max = $1
  7438. +        arr[$1] = $0
  7439. +      }
  7440. +      
  7441. +      END {
  7442. +        for (x = 1; x <= max; x++)
  7443. +          print arr[x]
  7444. +      }
  7445. + 
  7446. +    The first rule keeps track of the largest line number seen so far;
  7447. + it also stores each line into the array `arr', at an index that is the
  7448. + line's number.
  7449. + 
  7450. +    The second rule runs after all the input has been read, to print out
  7451. + all the lines.
  7452. + 
  7453. +    When this program is run with the following input:
  7454. + 
  7455. +      5  I am the Five man
  7456. +      2  Who are you?  The new number two!
  7457. +      4  . . . And four on the floor
  7458. +      1  Who is number one?
  7459. +      3  I three you.
  7460. + 
  7461. + its output is this:
  7462. + 
  7463. +      1  Who is number one?
  7464. +      2  Who are you?  The new number two!
  7465. +      3  I three you.
  7466. +      4  . . . And four on the floor
  7467. +      5  I am the Five man
  7468. + 
  7469. +    If a line number is repeated, the last line with a given number
  7470. + overrides the others.
  7471. + 
  7472. +    Gaps in the line numbers can be handled with an easy improvement to
  7473. + the program's `END' rule:
  7474. + 
  7475. +      END {
  7476. +        for (x = 1; x <= max; x++)
  7477. +          if (x in arr)
  7478. +            print arr[x]
  7479. +      }
  7480. + 
  7481. + 
  7482. + File: gawk.info,  Node: Scanning an Array,  Next: Delete,  Prev: Array Example,  Up: Arrays
  7483. + 
  7484. + Scanning all Elements of an Array
  7485. + =================================
  7486. + 
  7487. +    In programs that use arrays, often you need a loop that executes
  7488. + once for each element of an array.  In other languages, where arrays are
  7489. + contiguous and indices are limited to positive integers, this is easy:
  7490. + the largest index is one less than the length of the array, and you can
  7491. + find all the valid indices by counting from zero up to that value.  This
  7492. + technique won't do the job in `awk', since any number or string may be
  7493. + an array index.  So `awk' has a special kind of `for' statement for
  7494. + scanning an array:
  7495. + 
  7496. +      for (VAR in ARRAY)
  7497. +        BODY
  7498. + 
  7499. + This loop executes BODY once for each different value that your program
  7500. + has previously used as an index in ARRAY, with the variable VAR set to
  7501. + that index.
  7502. + 
  7503. +    Here is a program that uses this form of the `for' statement.  The
  7504. + first rule scans the input records and notes which words appear (at
  7505. + least once) in the input, by storing a 1 into the array `used' with the
  7506. + word as index.  The second rule scans the elements of `used' to find
  7507. + all the distinct words that appear in the input.  It prints each word
  7508. + that is more than 10 characters long, and also prints the number of
  7509. + such words.  *Note Built-in Functions: Built-in, for more information
  7510. + on the built-in function `length'.
  7511. + 
  7512. +      # Record a 1 for each word that is used at least once.
  7513. +      {
  7514. +        for (i = 1; i <= NF; i++)
  7515. +          used[$i] = 1
  7516. +      }
  7517. +      
  7518. +      # Find number of distinct words more than 10 characters long.
  7519. +      END {
  7520. +        for (x in used)
  7521. +          if (length(x) > 10) {
  7522. +            ++num_long_words
  7523. +            print x
  7524. +        }
  7525. +        print num_long_words, "words longer than 10 characters"
  7526. +      }
  7527. + 
  7528. + *Note Sample Program::, for a more detailed example of this type.
  7529. + 
  7530. +    The order in which elements of the array are accessed by this
  7531. + statement is determined by the internal arrangement of the array
  7532. + elements within `awk' and cannot be controlled or changed.  This can
  7533. + lead to problems if new elements are added to ARRAY by statements in
  7534. + BODY; you cannot predict whether or not the `for' loop will reach them.
  7535. + Similarly, changing VAR inside the loop can produce strange results.
  7536. + It is best to avoid such things.
  7537. + 
  7538. + 
  7539. + File: gawk.info,  Node: Delete,  Next: Numeric Array Subscripts,  Prev: Scanning an Array,  Up: Arrays
  7540. + 
  7541. + The `delete' Statement
  7542. + ======================
  7543. + 
  7544. +    You can remove an individual element of an array using the `delete'
  7545. + statement:
  7546. + 
  7547. +      delete ARRAY[INDEX]
  7548. + 
  7549. +    You can not refer to an array element after it has been deleted; it
  7550. + is as if you had never referred to it and had never given it any value.
  7551. + You can no longer obtain any value the element once had.
  7552. + 
  7553. +    Here is an example of deleting elements in an array:
  7554. + 
  7555. +      for (i in frequencies)
  7556. +        delete frequencies[i]
  7557. + 
  7558. + This example removes all the elements from the array `frequencies'.
  7559. + 
  7560. +    If you delete an element, a subsequent `for' statement to scan the
  7561. + array will not report that element, and the `in' operator to check for
  7562. + the presence of that element will return 0:
  7563. + 
  7564. +      delete foo[4]
  7565. +      if (4 in foo)
  7566. +        print "This will never be printed"
  7567. + 
  7568. +    It is not an error to delete an element which does not exist.
  7569. + 
  7570. + 
  7571. + File: gawk.info,  Node: Numeric Array Subscripts,  Next: Multi-dimensional,  Prev: Delete,  Up: Arrays
  7572. + 
  7573. + Using Numbers to Subscript Arrays
  7574. + =================================
  7575. + 
  7576. +    An important aspect of arrays to remember is that array subscripts
  7577. + are *always* strings.  If you use a numeric value as a subscript, it
  7578. + will be converted to a string value before it is used for subscripting
  7579. + (*note Conversion of Strings and Numbers: Conversion.).
  7580. + 
  7581. +    This means that the value of the `CONVFMT' can potentially affect
  7582. + how your program accesses elements of an array.  For example:
  7583. + 
  7584. +      a = b = 12.153
  7585. +      data[a] = 1
  7586. +      CONVFMT = "%2.2f"
  7587. +      if (b in data)
  7588. +          printf "%s is in data", b
  7589. +      else
  7590. +          printf "%s is not in data", b
  7591. + 
  7592. + should print `12.15 is not in data'.  The first statement gives both
  7593. + `a' and `b' the same numeric value.  Assigning to `data[a]' first gives
  7594. + `a' the string value `"12.153"' (using the default conversion value of
  7595. + `CONVFMT', `"%.6g"'), and then assigns 1 to `data["12.153"]'.  The
  7596. + program then changes the value of `CONVFMT'.  The test `(b in data)'
  7597. + forces `b' to be converted to a string, this time `"12.15"', since the
  7598. + value of `CONVFMT' only allows two significant digits.  This test fails,
  7599. + since `"12.15"' is a different string from `"12.153"'.
  7600. + 
  7601. +    According to the rules for conversions (*note Conversion of Strings
  7602. + and Numbers: Conversion.), integer values are always converted to
  7603. + strings as integers, no matter what the value of `CONVFMT' may happen
  7604. + to be.  So the usual case of
  7605. + 
  7606. +      for (i = 1; i <= maxsub; i++)
  7607. +          do something with array[i]
  7608. + 
  7609. + will work, no matter what the value of `CONVFMT'.
  7610. + 
  7611. +    Like many things in `awk', the majority of the time things work as
  7612. + you would expect them to work.  But it is useful to have a precise
  7613. + knowledge of the actual rules, since sometimes they can have a subtle
  7614. + effect on your programs.
  7615. + 
  7616. + 
  7617. + File: gawk.info,  Node: Multi-dimensional,  Next: Multi-scanning,  Prev: Numeric Array Subscripts,  Up: Arrays
  7618. + 
  7619. + Multi-dimensional Arrays
  7620. + ========================
  7621. + 
  7622. +    A multi-dimensional array is an array in which an element is
  7623. + identified by a sequence of indices, not a single index.  For example, a
  7624. + two-dimensional array requires two indices.  The usual way (in most
  7625. + languages, including `awk') to refer to an element of a two-dimensional
  7626. + array named `grid' is with `grid[X,Y]'.
  7627. + 
  7628. +    Multi-dimensional arrays are supported in `awk' through
  7629. + concatenation of indices into one string.  What happens is that `awk'
  7630. + converts the indices into strings (*note Conversion of Strings and
  7631. + Numbers: Conversion.) and concatenates them together, with a separator
  7632. + between them.  This creates a single string that describes the values
  7633. + of the separate indices.  The combined string is used as a single index
  7634. + into an ordinary, one-dimensional array.  The separator used is the
  7635. + value of the built-in variable `SUBSEP'.
  7636. + 
  7637. +    For example, suppose we evaluate the expression `foo[5,12]="value"'
  7638. + when the value of `SUBSEP' is `"@"'.  The numbers 5 and 12 are
  7639. + converted to strings and concatenated with an `@' between them,
  7640. + yielding `"5@12"'; thus, the array element `foo["5@12"]' is set to
  7641. + `"value"'.
  7642. + 
  7643. +    Once the element's value is stored, `awk' has no record of whether
  7644. + it was stored with a single index or a sequence of indices.  The two
  7645. + expressions `foo[5,12]' and `foo[5 SUBSEP 12]' always have the same
  7646. + value.
  7647. + 
  7648. +    The default value of `SUBSEP' is the string `"\034"', which contains
  7649. + a nonprinting character that is unlikely to appear in an `awk' program
  7650. + or in the input data.
  7651. + 
  7652. +    The usefulness of choosing an unlikely character comes from the fact
  7653. + that index values that contain a string matching `SUBSEP' lead to
  7654. + combined strings that are ambiguous.  Suppose that `SUBSEP' were `"@"';
  7655. + then `foo["a@b", "c"]' and `foo["a", "b@c"]' would be indistinguishable
  7656. + because both would actually be stored as `foo["a@b@c"]'.  Because
  7657. + `SUBSEP' is `"\034"', such confusion can arise only when an index
  7658. + contains the character with ASCII code 034, which is a rare event.
  7659. + 
  7660. +    You can test whether a particular index-sequence exists in a
  7661. + "multi-dimensional" array with the same operator `in' used for single
  7662. + dimensional arrays.  Instead of a single index as the left-hand operand,
  7663. + write the whole sequence of indices, separated by commas, in
  7664. + parentheses:
  7665. + 
  7666. +      (SUBSCRIPT1, SUBSCRIPT2, ...) in ARRAY
  7667. + 
  7668. +    The following example treats its input as a two-dimensional array of
  7669. + fields; it rotates this array 90 degrees clockwise and prints the
  7670. + result.  It assumes that all lines have the same number of elements.
  7671. + 
  7672. +      awk '{
  7673. +           if (max_nf < NF)
  7674. +                max_nf = NF
  7675. +           max_nr = NR
  7676. +           for (x = 1; x <= NF; x++)
  7677. +                vector[x, NR] = $x
  7678. +      }
  7679. +      
  7680. +      END {
  7681. +           for (x = 1; x <= max_nf; x++) {
  7682. +                for (y = max_nr; y >= 1; --y)
  7683. +                     printf("%s ", vector[x, y])
  7684. +                printf("\n")
  7685. +           }
  7686. +      }'
  7687. + 
  7688. + When given the input:
  7689. + 
  7690. +      1 2 3 4 5 6
  7691. +      2 3 4 5 6 1
  7692. +      3 4 5 6 1 2
  7693. +      4 5 6 1 2 3
  7694. + 
  7695. + it produces:
  7696. + 
  7697. +      4 3 2 1
  7698. +      5 4 3 2
  7699. +      6 5 4 3
  7700. +      1 6 5 4
  7701. +      2 1 6 5
  7702. +      3 2 1 6
  7703. + 
  7704. + 
  7705. + File: gawk.info,  Node: Multi-scanning,  Prev: Multi-dimensional,  Up: Arrays
  7706. + 
  7707. + Scanning Multi-dimensional Arrays
  7708. + =================================
  7709. + 
  7710. +    There is no special `for' statement for scanning a
  7711. + "multi-dimensional" array; there cannot be one, because in truth there
  7712. + are no multi-dimensional arrays or elements; there is only a
  7713. + multi-dimensional *way of accessing* an array.
  7714. + 
  7715. +    However, if your program has an array that is always accessed as
  7716. + multi-dimensional, you can get the effect of scanning it by combining
  7717. + the scanning `for' statement (*note Scanning all Elements of an Array:
  7718. + Scanning an Array.) with the `split' built-in function (*note Built-in
  7719. + Functions for String Manipulation: String Functions.).  It works like
  7720. + this:
  7721. + 
  7722. +      for (combined in ARRAY) {
  7723. +        split(combined, separate, SUBSEP)
  7724. +        ...
  7725. +      }
  7726. + 
  7727. + This finds each concatenated, combined index in the array, and splits it
  7728. + into the individual indices by breaking it apart where the value of
  7729. + `SUBSEP' appears.  The split-out indices become the elements of the
  7730. + array `separate'.
  7731. + 
  7732. +    Thus, suppose you have previously stored in `ARRAY[1, "foo"]'; then
  7733. + an element with index `"1\034foo"' exists in ARRAY.  (Recall that the
  7734. + default value of `SUBSEP' contains the character with code 034.)
  7735. + Sooner or later the `for' statement will find that index and do an
  7736. + iteration with `combined' set to `"1\034foo"'.  Then the `split'
  7737. + function is called as follows:
  7738. + 
  7739. +      split("1\034foo", separate, "\034")
  7740. + 
  7741. + The result of this is to set `separate[1]' to 1 and `separate[2]' to
  7742. + `"foo"'.  Presto, the original sequence of separate indices has been
  7743. + recovered.
  7744. + 
  7745. + 
  7746. + File: gawk.info,  Node: Built-in,  Next: User-defined,  Prev: Arrays,  Up: Top
  7747. + 
  7748. + Built-in Functions
  7749. + ******************
  7750. + 
  7751. +    "Built-in" functions are functions that are always available for
  7752. + your `awk' program to call.  This chapter defines all the built-in
  7753. + functions in `awk'; some of them are mentioned in other sections, but
  7754. + they are summarized here for your convenience.  (You can also define
  7755. + new functions yourself.  *Note User-defined Functions: User-defined.)
  7756. + 
  7757. + * Menu:
  7758. + 
  7759. + * Calling Built-in::            How to call built-in functions.
  7760. + * Numeric Functions::           Functions that work with numbers,
  7761. +                                 including `int', `sin' and `rand'.
  7762. + * String Functions::            Functions for string manipulation,
  7763. +                                 such as `split', `match', and `sprintf'.
  7764. + * I/O Functions::               Functions for files and shell commands.
  7765. + * Time Functions::              Functions for dealing with time stamps.
  7766. + 
  7767. + 
  7768. + File: gawk.info,  Node: Calling Built-in,  Next: Numeric Functions,  Prev: Built-in,  Up: Built-in
  7769. + 
  7770. + Calling Built-in Functions
  7771. + ==========================
  7772. + 
  7773. +    To call a built-in function, write the name of the function followed
  7774. + by arguments in parentheses.  For example, `atan2(y + z, 1)' is a call
  7775. + to the function `atan2', with two arguments.
  7776. + 
  7777. +    Whitespace is ignored between the built-in function name and the
  7778. + open-parenthesis, but we recommend that you avoid using whitespace
  7779. + there.  User-defined functions do not permit whitespace in this way, and
  7780. + you will find it easier to avoid mistakes by following a simple
  7781. + convention which always works: no whitespace after a function name.
  7782. + 
  7783. +    Each built-in function accepts a certain number of arguments.  In
  7784. + most cases, any extra arguments given to built-in functions are
  7785. + ignored.  The defaults for omitted arguments vary from function to
  7786. + function and are described under the individual functions.
  7787. + 
  7788. +    When a function is called, expressions that create the function's
  7789. + actual parameters are evaluated completely before the function call is
  7790. + performed.  For example, in the code fragment:
  7791. + 
  7792. +      i = 4
  7793. +      j = sqrt(i++)
  7794. + 
  7795. + the variable `i' is set to 5 before `sqrt' is called with a value of 4
  7796. + for its actual parameter.
  7797. + 
  7798. + 
  7799. + File: gawk.info,  Node: Numeric Functions,  Next: String Functions,  Prev: Calling Built-in,  Up: Built-in
  7800. + 
  7801. + Numeric Built-in Functions
  7802. + ==========================
  7803. + 
  7804. +    Here is a full list of built-in functions that work with numbers:
  7805. + 
  7806. + `int(X)'
  7807. +      This gives you the integer part of X, truncated toward 0.  This
  7808. +      produces the nearest integer to X, located between X and 0.
  7809. + 
  7810. +      For example, `int(3)' is 3, `int(3.9)' is 3, `int(-3.9)' is -3,
  7811. +      and `int(-3)' is -3 as well.
  7812. + 
  7813. + `sqrt(X)'
  7814. +      This gives you the positive square root of X.  It reports an error
  7815. +      if X is negative.  Thus, `sqrt(4)' is 2.
  7816. + 
  7817. + `exp(X)'
  7818. +      This gives you the exponential of X, or reports an error if X is
  7819. +      out of range.  The range of values X can have depends on your
  7820. +      machine's floating point representation.
  7821. + 
  7822. + `log(X)'
  7823. +      This gives you the natural logarithm of X, if X is positive;
  7824. +      otherwise, it reports an error.
  7825. + 
  7826. + `sin(X)'
  7827. +      This gives you the sine of X, with X in radians.
  7828. + 
  7829. + `cos(X)'
  7830. +      This gives you the cosine of X, with X in radians.
  7831. + 
  7832. + `atan2(Y, X)'
  7833. +      This gives you the arctangent of `Y / X' in radians.
  7834. + 
  7835. + `rand()'
  7836. +      This gives you a random number.  The values of `rand' are
  7837. +      uniformly-distributed between 0 and 1.  The value is never 0 and
  7838. +      never 1.
  7839. + 
  7840. +      Often you want random integers instead.  Here is a user-defined
  7841. +      function you can use to obtain a random nonnegative integer less
  7842. +      than N:
  7843. + 
  7844. +           function randint(n) {
  7845. +                return int(n * rand())
  7846. +           }
  7847. + 
  7848. +      The multiplication produces a random real number greater than 0
  7849. +      and less than N.  We then make it an integer (using `int') between
  7850. +      0 and `N - 1'.
  7851. + 
  7852. +      Here is an example where a similar function is used to produce
  7853. +      random integers between 1 and N.  Note that this program will
  7854. +      print a new random number for each input record.
  7855. + 
  7856. +           awk '
  7857. +           # Function to roll a simulated die.
  7858. +           function roll(n) { return 1 + int(rand() * n) }
  7859. +           
  7860. +           # Roll 3 six-sided dice and print total number of points.
  7861. +           {
  7862. +                 printf("%d points\n", roll(6)+roll(6)+roll(6))
  7863. +           }'
  7864. + 
  7865. +      *Note:* `rand' starts generating numbers from the same point, or
  7866. +      "seed", each time you run `awk'.  This means that a program will
  7867. +      produce the same results each time you run it.  The numbers are
  7868. +      random within one `awk' run, but predictable from run to run.
  7869. +      This is convenient for debugging, but if you want a program to do
  7870. +      different things each time it is used, you must change the seed to
  7871. +      a value that will be different in each run.  To do this, use
  7872. +      `srand'.
  7873. + 
  7874. + `srand(X)'
  7875. +      The function `srand' sets the starting point, or "seed", for
  7876. +      generating random numbers to the value X.
  7877. + 
  7878. +      Each seed value leads to a particular sequence of "random" numbers.
  7879. +      Thus, if you set the seed to the same value a second time, you
  7880. +      will get the same sequence of "random" numbers again.
  7881. + 
  7882. +      If you omit the argument X, as in `srand()', then the current date
  7883. +      and time of day are used for a seed.  This is the way to get random
  7884. +      numbers that are truly unpredictable.
  7885. + 
  7886. +      The return value of `srand' is the previous seed.  This makes it
  7887. +      easy to keep track of the seeds for use in consistently reproducing
  7888. +      sequences of random numbers.
  7889. + 
  7890. + 
  7891. + File: gawk.info,  Node: String Functions,  Next: I/O Functions,  Prev: Numeric Functions,  Up: Built-in
  7892. + 
  7893. + Built-in Functions for String Manipulation
  7894. + ==========================================
  7895. + 
  7896. +    The functions in this section look at or change the text of one or
  7897. + more strings.
  7898. + 
  7899. + `index(IN, FIND)'
  7900. +      This searches the string IN for the first occurrence of the string
  7901. +      FIND, and returns the position in characters where that occurrence
  7902. +      begins in the string IN.  For example:
  7903. + 
  7904. +           awk 'BEGIN { print index("peanut", "an") }'
  7905. + 
  7906. +      prints `3'.  If FIND is not found, `index' returns 0.  (Remember
  7907. +      that string indices in `awk' start at 1.)
  7908. + 
  7909. + `length(STRING)'
  7910. +      This gives you the number of characters in STRING.  If STRING is a
  7911. +      number, the length of the digit string representing that number is
  7912. +      returned.  For example, `length("abcde")' is 5.  By contrast,
  7913. +      `length(15 * 35)' works out to 3.  How?  Well, 15 * 35 = 525, and
  7914. +      525 is then converted to the string `"525"', which has three
  7915. +      characters.
  7916. + 
  7917. +      If no argument is supplied, `length' returns the length of `$0'.
  7918. + 
  7919. +      In older versions of `awk', you could call the `length' function
  7920. +      without any parentheses.  Doing so is marked as "deprecated" in the
  7921. +      POSIX standard.  This means that while you can do this in your
  7922. +      programs, it is a feature that can eventually be removed from a
  7923. +      future version of the standard.  Therefore, for maximal
  7924. +      portability of your `awk' programs you should always supply the
  7925. +      parentheses.
  7926. + 
  7927. + `match(STRING, REGEXP)'
  7928. +      The `match' function searches the string, STRING, for the longest,
  7929. +      leftmost substring matched by the regular expression, REGEXP.  It
  7930. +      returns the character position, or "index", of where that
  7931. +      substring begins (1, if it starts at the beginning of STRING).  If
  7932. +      no match if found, it returns 0.
  7933. + 
  7934. +      The `match' function sets the built-in variable `RSTART' to the
  7935. +      index.  It also sets the built-in variable `RLENGTH' to the length
  7936. +      in characters of the matched substring.  If no match is found,
  7937. +      `RSTART' is set to 0, and `RLENGTH' to -1.
  7938. + 
  7939. +      For example:
  7940. + 
  7941. +           awk '{
  7942. +                  if ($1 == "FIND")
  7943. +                    regex = $2
  7944. +                  else {
  7945. +                    where = match($0, regex)
  7946. +                    if (where)
  7947. +                      print "Match of", regex, "found at", where, "in", $0
  7948. +                  }
  7949. +           }'
  7950. + 
  7951. +      This program looks for lines that match the regular expression
  7952. +      stored in the variable `regex'.  This regular expression can be
  7953. +      changed.  If the first word on a line is `FIND', `regex' is
  7954. +      changed to be the second word on that line.  Therefore, given:
  7955. + 
  7956. +           FIND fo*bar
  7957. +           My program was a foobar
  7958. +           But none of it would doobar
  7959. +           FIND Melvin
  7960. +           JF+KM
  7961. +           This line is property of The Reality Engineering Co.
  7962. +           This file created by Melvin.
  7963. + 
  7964. +      `awk' prints:
  7965. + 
  7966. +           Match of fo*bar found at 18 in My program was a foobar
  7967. +           Match of Melvin found at 26 in This file created by Melvin.
  7968. + 
  7969. + `split(STRING, ARRAY, FIELDSEP)'
  7970. +      This divides STRING into pieces separated by FIELDSEP, and stores
  7971. +      the pieces in ARRAY.  The first piece is stored in `ARRAY[1]', the
  7972. +      second piece in `ARRAY[2]', and so forth.  The string value of the
  7973. +      third argument, FIELDSEP, is a regexp describing where to split
  7974. +      STRING (much as `FS' can be a regexp describing where to split
  7975. +      input records).  If the FIELDSEP is omitted, the value of `FS' is
  7976. +      used.  `split' returns the number of elements created.
  7977. + 
  7978. +      The `split' function, then, splits strings into pieces in a manner
  7979. +      similar to the way input lines are split into fields.  For example:
  7980. + 
  7981. +           split("auto-da-fe", a, "-")
  7982. + 
  7983. +      splits the string `auto-da-fe' into three fields using `-' as the
  7984. +      separator.  It sets the contents of the array `a' as follows:
  7985. + 
  7986. +           a[1] = "auto"
  7987. +           a[2] = "da"
  7988. +           a[3] = "fe"
  7989. + 
  7990. +      The value returned by this call to `split' is 3.
  7991. + 
  7992. +      As with input field-splitting, when the value of FIELDSEP is `"
  7993. +      "', leading and trailing whitespace is ignored, and the elements
  7994. +      are separated by runs of whitespace.
  7995. + 
  7996. + `sprintf(FORMAT, EXPRESSION1,...)'
  7997. +      This returns (without printing) the string that `printf' would
  7998. +      have printed out with the same arguments (*note Using `printf'
  7999. +      Statements for Fancier Printing: Printf.).  For example:
  8000. + 
  8001. +           sprintf("pi = %.2f (approx.)", 22/7)
  8002. + 
  8003. +      returns the string `"pi = 3.14 (approx.)"'.
  8004. + 
  8005. + `sub(REGEXP, REPLACEMENT, TARGET)'
  8006. +      The `sub' function alters the value of TARGET.  It searches this
  8007. +      value, which should be a string, for the leftmost substring
  8008. +      matched by the regular expression, REGEXP, extending this match as
  8009. +      far as possible.  Then the entire string is changed by replacing
  8010. +      the matched text with REPLACEMENT.  The modified string becomes
  8011. +      the new value of TARGET.
  8012. + 
  8013. +      This function is peculiar because TARGET is not simply used to
  8014. +      compute a value, and not just any expression will do: it must be a
  8015. +      variable, field or array reference, so that `sub' can store a
  8016. +      modified value there.  If this argument is omitted, then the
  8017. +      default is to use and alter `$0'.
  8018. + 
  8019. +      For example:
  8020. + 
  8021. +           str = "water, water, everywhere"
  8022. +           sub(/at/, "ith", str)
  8023. + 
  8024. +      sets `str' to `"wither, water, everywhere"', by replacing the
  8025. +      leftmost, longest occurrence of `at' with `ith'.
  8026. + 
  8027. +      The `sub' function returns the number of substitutions made (either
  8028. +      one or zero).
  8029. + 
  8030. +      If the special character `&' appears in REPLACEMENT, it stands for
  8031. +      the precise substring that was matched by REGEXP.  (If the regexp
  8032. +      can match more than one string, then this precise substring may
  8033. +      vary.)  For example:
  8034. + 
  8035. +           awk '{ sub(/candidate/, "& and his wife"); print }'
  8036. + 
  8037. +      changes the first occurrence of `candidate' to `candidate and his
  8038. +      wife' on each input line.
  8039. + 
  8040. +      Here is another example:
  8041. + 
  8042. +           awk 'BEGIN {
  8043. +                   str = "daabaaa"
  8044. +                   sub(/a*/, "c&c", str)
  8045. +                   print str
  8046. +           }'
  8047. + 
  8048. +      prints `dcaacbaaa'.  This show how `&' can represent a non-constant
  8049. +      string, and also illustrates the "leftmost, longest" rule.
  8050. + 
  8051. +      The effect of this special character (`&') can be turned off by
  8052. +      putting a backslash before it in the string.  As usual, to insert
  8053. +      one backslash in the string, you must write two backslashes.
  8054. +      Therefore, write `\\&' in a string constant to include a literal
  8055. +      `&' in the replacement.  For example, here is how to replace the
  8056. +      first `|' on each line with an `&':
  8057. + 
  8058. +           awk '{ sub(/\|/, "\\&"); print }'
  8059. + 
  8060. +      *Note:* as mentioned above, the third argument to `sub' must be an
  8061. +      lvalue.  Some versions of `awk' allow the third argument to be an
  8062. +      expression which is not an lvalue.  In such a case, `sub' would
  8063. +      still search for the pattern and return 0 or 1, but the result of
  8064. +      the substitution (if any) would be thrown away because there is no
  8065. +      place to put it.  Such versions of `awk' accept expressions like
  8066. +      this:
  8067. + 
  8068. +           sub(/USA/, "United States", "the USA and Canada")
  8069. + 
  8070. +      But that is considered erroneous in `gawk'.
  8071. + 
  8072. + `gsub(REGEXP, REPLACEMENT, TARGET)'
  8073. +      This is similar to the `sub' function, except `gsub' replaces
  8074. +      *all* of the longest, leftmost, *nonoverlapping* matching
  8075. +      substrings it can find.  The `g' in `gsub' stands for "global,"
  8076. +      which means replace everywhere.  For example:
  8077. + 
  8078. +           awk '{ gsub(/Britain/, "United Kingdom"); print }'
  8079. + 
  8080. +      replaces all occurrences of the string `Britain' with `United
  8081. +      Kingdom' for all input records.
  8082. + 
  8083. +      The `gsub' function returns the number of substitutions made.  If
  8084. +      the variable to be searched and altered, TARGET, is omitted, then
  8085. +      the entire input record, `$0', is used.
  8086. + 
  8087. +      As in `sub', the characters `&' and `\' are special, and the third
  8088. +      argument must be an lvalue.
  8089. + 
  8090. + `substr(STRING, START, LENGTH)'
  8091. +      This returns a LENGTH-character-long substring of STRING, starting
  8092. +      at character number START.  The first character of a string is
  8093. +      character number one.  For example, `substr("washington", 5, 3)'
  8094. +      returns `"ing"'.
  8095. + 
  8096. +      If LENGTH is not present, this function returns the whole suffix of
  8097. +      STRING that begins at character number START.  For example,
  8098. +      `substr("washington", 5)' returns `"ington"'.  This is also the
  8099. +      case if LENGTH is greater than the number of characters remaining
  8100. +      in the string, counting from character number START.
  8101. + 
  8102. + `tolower(STRING)'
  8103. +      This returns a copy of STRING, with each upper-case character in
  8104. +      the string replaced with its corresponding lower-case character.
  8105. +      Nonalphabetic characters are left unchanged.  For example,
  8106. +      `tolower("MiXeD cAsE 123")' returns `"mixed case 123"'.
  8107. + 
  8108. + `toupper(STRING)'
  8109. +      This returns a copy of STRING, with each lower-case character in
  8110. +      the string replaced with its corresponding upper-case character.
  8111. +      Nonalphabetic characters are left unchanged.  For example,
  8112. +      `toupper("MiXeD cAsE 123")' returns `"MIXED CASE 123"'.
  8113. + 
  8114. diff -rc --new-file /src/baseline/gawk-2.15.5/gawk.info-6 gawk-2.15.5/gawk.info-6
  8115. *** /src/baseline/gawk-2.15.5/gawk.info-6    Thu Jan  1 00:00:00 1970
  8116. --- gawk-2.15.5/gawk.info-6    Sun Jun 12 22:28:53 1994
  8117. ***************
  8118. *** 0 ****
  8119. --- 1,1234 ----
  8120. + This is Info file gawk.info, produced by Makeinfo-1.55 from the input
  8121. + file /gnu/src/amiga/gawk-2.15.5/gawk.texi.
  8122. + 
  8123. +    This file documents `awk', a program that you can use to select
  8124. + particular records in a file and perform operations upon them.
  8125. + 
  8126. +    This is Edition 0.15 of `The GAWK Manual',
  8127. + for the 2.15 version of the GNU implementation
  8128. + of AWK.
  8129. + 
  8130. +    Copyright (C) 1989, 1991, 1992, 1993 Free Software Foundation, Inc.
  8131. + 
  8132. +    Permission is granted to make and distribute verbatim copies of this
  8133. + manual provided the copyright notice and this permission notice are
  8134. + preserved on all copies.
  8135. + 
  8136. +    Permission is granted to copy and distribute modified versions of
  8137. + this manual under the conditions for verbatim copying, provided that
  8138. + the entire resulting derived work is distributed under the terms of a
  8139. + permission notice identical to this one.
  8140. + 
  8141. +    Permission is granted to copy and distribute translations of this
  8142. + manual into another language, under the above conditions for modified
  8143. + versions, except that this permission notice may be stated in a
  8144. + translation approved by the Foundation.
  8145. + 
  8146. + 
  8147. + File: gawk.info,  Node: I/O Functions,  Next: Time Functions,  Prev: String Functions,  Up: Built-in
  8148. + 
  8149. + Built-in Functions for Input/Output
  8150. + ===================================
  8151. + 
  8152. + `close(FILENAME)'
  8153. +      Close the file FILENAME, for input or output.  The argument may
  8154. +      alternatively be a shell command that was used for redirecting to
  8155. +      or from a pipe; then the pipe is closed.
  8156. + 
  8157. +      *Note Closing Input Files and Pipes: Close Input, regarding closing
  8158. +      input files and pipes.  *Note Closing Output Files and Pipes:
  8159. +      Close Output, regarding closing output files and pipes.
  8160. + 
  8161. + `system(COMMAND)'
  8162. +      The system function allows the user to execute operating system
  8163. +      commands and then return to the `awk' program.  The `system'
  8164. +      function executes the command given by the string COMMAND.  It
  8165. +      returns, as its value, the status returned by the command that was
  8166. +      executed.
  8167. + 
  8168. +      For example, if the following fragment of code is put in your `awk'
  8169. +      program:
  8170. + 
  8171. +           END {
  8172. +                system("mail -s 'awk run done' operator < /dev/null")
  8173. +           }
  8174. + 
  8175. +      the system operator will be sent mail when the `awk' program
  8176. +      finishes processing input and begins its end-of-input processing.
  8177. + 
  8178. +      Note that much the same result can be obtained by redirecting
  8179. +      `print' or `printf' into a pipe.  However, if your `awk' program
  8180. +      is interactive, `system' is useful for cranking up large
  8181. +      self-contained programs, such as a shell or an editor.
  8182. + 
  8183. +      Some operating systems cannot implement the `system' function.
  8184. +      `system' causes a fatal error if it is not supported.
  8185. + 
  8186. + Controlling Output Buffering with `system'
  8187. + ------------------------------------------
  8188. + 
  8189. +    Many utility programs will "buffer" their output; they save
  8190. + information to be written to a disk file or terminal in memory, until
  8191. + there is enough to be written in one operation.  This is often more
  8192. + efficient than writing every little bit of information as soon as it is
  8193. + ready.  However, sometimes it is necessary to force a program to
  8194. + "flush" its buffers; that is, write the information to its destination,
  8195. + even if a buffer is not full.  You can do this from your `awk' program
  8196. + by calling `system' with a null string as its argument:
  8197. + 
  8198. +      system("")   # flush output
  8199. + 
  8200. + `gawk' treats this use of the `system' function as a special case, and
  8201. + is smart enough not to run a shell (or other command interpreter) with
  8202. + the empty command.  Therefore, with `gawk', this idiom is not only
  8203. + useful, it is efficient.  While this idiom should work with other `awk'
  8204. + implementations, it will not necessarily avoid starting an unnecessary
  8205. + shell.
  8206. + 
  8207. + 
  8208. + File: gawk.info,  Node: Time Functions,  Prev: I/O Functions,  Up: Built-in
  8209. + 
  8210. + Functions for Dealing with Time Stamps
  8211. + ======================================
  8212. + 
  8213. +    A common use for `awk' programs is the processing of log files.  Log
  8214. + files often contain time stamp information, indicating when a
  8215. + particular log record was written.  Many programs log their time stamp
  8216. + in the form returned by the `time' system call, which is the number of
  8217. + seconds since a particular epoch.  On POSIX systems, it is the number
  8218. + of seconds since Midnight, January 1, 1970, UTC.
  8219. + 
  8220. +    In order to make it easier to process such log files, and to easily
  8221. + produce useful reports, `gawk' provides two functions for working with
  8222. + time stamps.  Both of these are `gawk' extensions; they are not
  8223. + specified in the POSIX standard, nor are they in any other known version
  8224. + of `awk'.
  8225. + 
  8226. + `systime()'
  8227. +      This function returns the current time as the number of seconds
  8228. +      since the system epoch.  On POSIX systems, this is the number of
  8229. +      seconds since Midnight, January 1, 1970, UTC.  It may be a
  8230. +      different number on other systems.
  8231. + 
  8232. + `strftime(FORMAT, TIMESTAMP)'
  8233. +      This function returns a string.  It is similar to the function of
  8234. +      the same name in the ANSI C standard library.  The time specified
  8235. +      by TIMESTAMP is used to produce a string, based on the contents of
  8236. +      the FORMAT string.
  8237. + 
  8238. +    The `systime' function allows you to compare a time stamp from a log
  8239. + file with the current time of day.  In particular, it is easy to
  8240. + determine how long ago a particular record was logged.  It also allows
  8241. + you to produce log records using the "seconds since the epoch" format.
  8242. + 
  8243. +    The `strftime' function allows you to easily turn a time stamp into
  8244. + human-readable information.  It is similar in nature to the `sprintf'
  8245. + function, copying non-format specification characters verbatim to the
  8246. + returned string, and substituting date and time values for format
  8247. + specifications in the FORMAT string.  If no TIMESTAMP argument is
  8248. + supplied, `gawk' will use the current time of day as the time stamp.
  8249. + 
  8250. +    `strftime' is guaranteed by the ANSI C standard to support the
  8251. + following date format specifications:
  8252. + 
  8253. + `%a'
  8254. +      The locale's abbreviated weekday name.
  8255. + 
  8256. + `%A'
  8257. +      The locale's full weekday name.
  8258. + 
  8259. + `%b'
  8260. +      The locale's abbreviated month name.
  8261. + 
  8262. + `%B'
  8263. +      The locale's full month name.
  8264. + 
  8265. + `%c'
  8266. +      The locale's "appropriate" date and time representation.
  8267. + 
  8268. + `%d'
  8269. +      The day of the month as a decimal number (01-31).
  8270. + 
  8271. + `%H'
  8272. +      The hour (24-hour clock) as a decimal number (00-23).
  8273. + 
  8274. + `%I'
  8275. +      The hour (12-hour clock) as a decimal number (01-12).
  8276. + 
  8277. + `%j'
  8278. +      The day of the year as a decimal number (001-366).
  8279. + 
  8280. + `%m'
  8281. +      The month as a decimal number (01-12).
  8282. + 
  8283. + `%M'
  8284. +      The minute as a decimal number (00-59).
  8285. + 
  8286. + `%p'
  8287. +      The locale's equivalent of the AM/PM designations associated with
  8288. +      a 12-hour clock.
  8289. + 
  8290. + `%S'
  8291. +      The second as a decimal number (00-61).  (Occasionally there are
  8292. +      minutes in a year with one or two leap seconds, which is why the
  8293. +      seconds can go from 0 all the way to 61.)
  8294. + 
  8295. + `%U'
  8296. +      The week number of the year (the first Sunday as the first day of
  8297. +      week 1) as a decimal number (00-53).
  8298. + 
  8299. + `%w'
  8300. +      The weekday as a decimal number (0-6).  Sunday is day 0.
  8301. + 
  8302. + `%W'
  8303. +      The week number of the year (the first Monday as the first day of
  8304. +      week 1) as a decimal number (00-53).
  8305. + 
  8306. + `%x'
  8307. +      The locale's "appropriate" date representation.
  8308. + 
  8309. + `%X'
  8310. +      The locale's "appropriate" time representation.
  8311. + 
  8312. + `%y'
  8313. +      The year without century as a decimal number (00-99).
  8314. + 
  8315. + `%Y'
  8316. +      The year with century as a decimal number.
  8317. + 
  8318. + `%Z'
  8319. +      The time zone name or abbreviation, or no characters if no time
  8320. +      zone is determinable.
  8321. + 
  8322. + `%%'
  8323. +      A literal `%'.
  8324. + 
  8325. +    If a conversion specifier is not one of the above, the behavior is
  8326. + undefined.  (This is because the ANSI standard for C leaves the
  8327. + behavior of the C version of `strftime' undefined, and `gawk' will use
  8328. + the system's version of `strftime' if it's there.  Typically, the
  8329. + conversion specifier will either not appear in the returned string, or
  8330. + it will appear literally.)
  8331. + 
  8332. +    Informally, a "locale" is the geographic place in which a program is
  8333. + meant to run.  For example, a common way to abbreviate the date
  8334. + September 4, 1991 in the United States would be "9/4/91".  In many
  8335. + countries in Europe, however, it would be abbreviated "4.9.91".  Thus,
  8336. + the `%x' specification in a `"US"' locale might produce `9/4/91', while
  8337. + in a `"EUROPE"' locale, it might produce `4.9.91'.  The ANSI C standard
  8338. + defines a default `"C"' locale, which is an environment that is typical
  8339. + of what most C programmers are used to.
  8340. + 
  8341. +    A public-domain C version of `strftime' is shipped with `gawk' for
  8342. + systems that are not yet fully ANSI-compliant.  If that version is used
  8343. + to compile `gawk' (*note Installing `gawk': Installation.), then the
  8344. + following additional format specifications are available:
  8345. + 
  8346. + `%D'
  8347. +      Equivalent to specifying `%m/%d/%y'.
  8348. + 
  8349. + `%e'
  8350. +      The day of the month, padded with a blank if it is only one digit.
  8351. + 
  8352. + `%h'
  8353. +      Equivalent to `%b', above.
  8354. + 
  8355. + `%n'
  8356. +      A newline character (ASCII LF).
  8357. + 
  8358. + `%r'
  8359. +      Equivalent to specifying `%I:%M:%S %p'.
  8360. + 
  8361. + `%R'
  8362. +      Equivalent to specifying `%H:%M'.
  8363. + 
  8364. + `%T'
  8365. +      Equivalent to specifying `%H:%M:%S'.
  8366. + 
  8367. + `%t'
  8368. +      A TAB character.
  8369. + 
  8370. + `%k'
  8371. +      is replaced by the hour (24-hour clock) as a decimal number (0-23).
  8372. +      Single digit numbers are padded with a blank.
  8373. + 
  8374. + `%l'
  8375. +      is replaced by the hour (12-hour clock) as a decimal number (1-12).
  8376. +      Single digit numbers are padded with a blank.
  8377. + 
  8378. + `%C'
  8379. +      The century, as a number between 00 and 99.
  8380. + 
  8381. + `%u'
  8382. +      is replaced by the weekday as a decimal number [1 (Monday)-7].
  8383. + 
  8384. + `%V'
  8385. +      is replaced by the week number of the year (the first Monday as
  8386. +      the first day of week 1) as a decimal number (01-53).  The method
  8387. +      for determining the week number is as specified by ISO 8601 (to
  8388. +      wit: if the week containing January 1 has four or more days in the
  8389. +      new year, then it is week 1, otherwise it is week 53 of the
  8390. +      previous year and the next week is week 1).
  8391. + 
  8392. + `%Ec %EC %Ex %Ey %EY %Od %Oe %OH %OI'
  8393. + `%Om %OM %OS %Ou %OU %OV %Ow %OW %Oy'
  8394. +      These are "alternate representations" for the specifications that
  8395. +      use only the second letter (`%c', `%C', and so on).  They are
  8396. +      recognized, but their normal representations are used.  (These
  8397. +      facilitate compliance with the POSIX `date' utility.)
  8398. + 
  8399. + `%v'
  8400. +      The date in VMS format (e.g. 20-JUN-1991).
  8401. + 
  8402. +    Here are two examples that use `strftime'.  The first is an `awk'
  8403. + version of the C `ctime' function.  (This is a user defined function,
  8404. + which we have not discussed yet.  *Note User-defined Functions:
  8405. + User-defined, for more information.)
  8406. + 
  8407. +      # ctime.awk
  8408. +      #
  8409. +      # awk version of C ctime(3) function
  8410. +      
  8411. +      function ctime(ts,    format)
  8412. +      {
  8413. +          format = "%a %b %e %H:%M:%S %Z %Y"
  8414. +          if (ts == 0)
  8415. +              ts = systime()         # use current time as default
  8416. +          return strftime(format, ts)
  8417. +      }
  8418. + 
  8419. +    This next example is an `awk' implementation of the POSIX `date'
  8420. + utility.  Normally, the `date' utility prints the current date and time
  8421. + of day in a well known format.  However, if you provide an argument to
  8422. + it that begins with a `+', `date' will copy non-format specifier
  8423. + characters to the standard output, and will interpret the current time
  8424. + according to the format specifiers in the string.  For example:
  8425. + 
  8426. +      date '+Today is %A, %B %d, %Y.'
  8427. + 
  8428. + might print
  8429. + 
  8430. +      Today is Thursday, July 11, 1991.
  8431. + 
  8432. +    Here is the `awk' version of the `date' utility.
  8433. + 
  8434. +      #! /bin/gawk -f
  8435. +      #
  8436. +      # date --- implement the P1003.2 Draft 11 'date' command
  8437. +      #
  8438. +      # Bug: does not recognize the -u argument.
  8439. +      
  8440. +      BEGIN    \
  8441. +      {
  8442. +          format = "%a %b %e %H:%M:%S %Z %Y"
  8443. +          exitval = 0
  8444. +      
  8445. +          if (ARGC > 2)
  8446. +              exitval = 1
  8447. +          else if (ARGC == 2) {
  8448. +              format = ARGV[1]
  8449. +              if (format ~ /^\+/)
  8450. +                  format = substr(format, 2)    # remove leading +
  8451. +          }
  8452. +          print strftime(format)
  8453. +          exit exitval
  8454. +      }
  8455. + 
  8456. + 
  8457. + File: gawk.info,  Node: User-defined,  Next: Built-in Variables,  Prev: Built-in,  Up: Top
  8458. + 
  8459. + User-defined Functions
  8460. + **********************
  8461. + 
  8462. +    Complicated `awk' programs can often be simplified by defining your
  8463. + own functions.  User-defined functions can be called just like built-in
  8464. + ones (*note Function Calls::.), but it is up to you to define them--to
  8465. + tell `awk' what they should do.
  8466. + 
  8467. + * Menu:
  8468. + 
  8469. + * Definition Syntax::           How to write definitions and what they mean.
  8470. + * Function Example::            An example function definition and
  8471. +                                 what it does.
  8472. + * Function Caveats::            Things to watch out for.
  8473. + * Return Statement::            Specifying the value a function returns.
  8474. + 
  8475. + 
  8476. + File: gawk.info,  Node: Definition Syntax,  Next: Function Example,  Prev: User-defined,  Up: User-defined
  8477. + 
  8478. + Syntax of Function Definitions
  8479. + ==============================
  8480. + 
  8481. +    Definitions of functions can appear anywhere between the rules of the
  8482. + `awk' program.  Thus, the general form of an `awk' program is extended
  8483. + to include sequences of rules *and* user-defined function definitions.
  8484. + 
  8485. +    The definition of a function named NAME looks like this:
  8486. + 
  8487. +      function NAME (PARAMETER-LIST) {
  8488. +           BODY-OF-FUNCTION
  8489. +      }
  8490. + 
  8491. + NAME is the name of the function to be defined.  A valid function name
  8492. + is like a valid variable name: a sequence of letters, digits and
  8493. + underscores, not starting with a digit.  Functions share the same pool
  8494. + of names as variables and arrays.
  8495. + 
  8496. +    PARAMETER-LIST is a list of the function's arguments and local
  8497. + variable names, separated by commas.  When the function is called, the
  8498. + argument names are used to hold the argument values given in the call.
  8499. + The local variables are initialized to the null string.
  8500. + 
  8501. +    The BODY-OF-FUNCTION consists of `awk' statements.  It is the most
  8502. + important part of the definition, because it says what the function
  8503. + should actually *do*.  The argument names exist to give the body a way
  8504. + to talk about the arguments; local variables, to give the body places
  8505. + to keep temporary values.
  8506. + 
  8507. +    Argument names are not distinguished syntactically from local
  8508. + variable names; instead, the number of arguments supplied when the
  8509. + function is called determines how many argument variables there are.
  8510. + Thus, if three argument values are given, the first three names in
  8511. + PARAMETER-LIST are arguments, and the rest are local variables.
  8512. + 
  8513. +    It follows that if the number of arguments is not the same in all
  8514. + calls to the function, some of the names in PARAMETER-LIST may be
  8515. + arguments on some occasions and local variables on others.  Another way
  8516. + to think of this is that omitted arguments default to the null string.
  8517. + 
  8518. +    Usually when you write a function you know how many names you intend
  8519. + to use for arguments and how many you intend to use as locals.  By
  8520. + convention, you should write an extra space between the arguments and
  8521. + the locals, so other people can follow how your function is supposed to
  8522. + be used.
  8523. + 
  8524. +    During execution of the function body, the arguments and local
  8525. + variable values hide or "shadow" any variables of the same names used
  8526. + in the rest of the program.  The shadowed variables are not accessible
  8527. + in the function definition, because there is no way to name them while
  8528. + their names have been taken away for the local variables.  All other
  8529. + variables used in the `awk' program can be referenced or set normally
  8530. + in the function definition.
  8531. + 
  8532. +    The arguments and local variables last only as long as the function
  8533. + body is executing.  Once the body finishes, the shadowed variables come
  8534. + back.
  8535. + 
  8536. +    The function body can contain expressions which call functions.  They
  8537. + can even call this function, either directly or by way of another
  8538. + function.  When this happens, we say the function is "recursive".
  8539. + 
  8540. +    There is no need in `awk' to put the definition of a function before
  8541. + all uses of the function.  This is because `awk' reads the entire
  8542. + program before starting to execute any of it.
  8543. + 
  8544. +    In many `awk' implementations, the keyword `function' may be
  8545. + abbreviated `func'.  However, POSIX only specifies the use of the
  8546. + keyword `function'.  This actually has some practical implications.  If
  8547. + `gawk' is in POSIX-compatibility mode (*note Invoking `awk': Command
  8548. + Line.), then the following statement will *not* define a function:
  8549. + 
  8550. +      func foo() { a = sqrt($1) ; print a }
  8551. + 
  8552. + Instead it defines a rule that, for each record, concatenates the value
  8553. + of the variable `func' with the return value of the function `foo', and
  8554. + based on the truth value of the result, executes the corresponding
  8555. + action.  This is probably not what was desired.  (`awk' accepts this
  8556. + input as syntactically valid, since functions may be used before they
  8557. + are defined in `awk' programs.)
  8558. + 
  8559. + 
  8560. + File: gawk.info,  Node: Function Example,  Next: Function Caveats,  Prev: Definition Syntax,  Up: User-defined
  8561. + 
  8562. + Function Definition Example
  8563. + ===========================
  8564. + 
  8565. +    Here is an example of a user-defined function, called `myprint', that
  8566. + takes a number and prints it in a specific format.
  8567. + 
  8568. +      function myprint(num)
  8569. +      {
  8570. +           printf "%6.3g\n", num
  8571. +      }
  8572. + 
  8573. + To illustrate, here is an `awk' rule which uses our `myprint' function:
  8574. + 
  8575. +      $3 > 0     { myprint($3) }
  8576. + 
  8577. + This program prints, in our special format, all the third fields that
  8578. + contain a positive number in our input.  Therefore, when given:
  8579. + 
  8580. +       1.2   3.4    5.6   7.8
  8581. +       9.10 11.12 -13.14 15.16
  8582. +      17.18 19.20  21.22 23.24
  8583. + 
  8584. + this program, using our function to format the results, prints:
  8585. + 
  8586. +         5.6
  8587. +        21.2
  8588. + 
  8589. +    Here is a rather contrived example of a recursive function.  It
  8590. + prints a string backwards:
  8591. + 
  8592. +      function rev (str, len) {
  8593. +          if (len == 0) {
  8594. +              printf "\n"
  8595. +              return
  8596. +          }
  8597. +          printf "%c", substr(str, len, 1)
  8598. +          rev(str, len - 1)
  8599. +      }
  8600. + 
  8601. + 
  8602. + File: gawk.info,  Node: Function Caveats,  Next: Return Statement,  Prev: Function Example,  Up: User-defined
  8603. + 
  8604. + Calling User-defined Functions
  8605. + ==============================
  8606. + 
  8607. +    "Calling a function" means causing the function to run and do its
  8608. + job.  A function call is an expression, and its value is the value
  8609. + returned by the function.
  8610. + 
  8611. +    A function call consists of the function name followed by the
  8612. + arguments in parentheses.  What you write in the call for the arguments
  8613. + are `awk' expressions; each time the call is executed, these
  8614. + expressions are evaluated, and the values are the actual arguments.  For
  8615. + example, here is a call to `foo' with three arguments (the first being
  8616. + a string concatenation):
  8617. + 
  8618. +      foo(x y, "lose", 4 * z)
  8619. + 
  8620. +      *Caution:* whitespace characters (spaces and tabs) are not allowed
  8621. +      between the function name and the open-parenthesis of the argument
  8622. +      list.  If you write whitespace by mistake, `awk' might think that
  8623. +      you mean to concatenate a variable with an expression in
  8624. +      parentheses.  However, it notices that you used a function name
  8625. +      and not a variable name, and reports an error.
  8626. + 
  8627. +    When a function is called, it is given a *copy* of the values of its
  8628. + arguments.  This is called "call by value".  The caller may use a
  8629. + variable as the expression for the argument, but the called function
  8630. + does not know this: it only knows what value the argument had.  For
  8631. + example, if you write this code:
  8632. + 
  8633. +      foo = "bar"
  8634. +      z = myfunc(foo)
  8635. + 
  8636. + then you should not think of the argument to `myfunc' as being "the
  8637. + variable `foo'."  Instead, think of the argument as the string value,
  8638. + `"bar"'.
  8639. + 
  8640. +    If the function `myfunc' alters the values of its local variables,
  8641. + this has no effect on any other variables.  In particular, if `myfunc'
  8642. + does this:
  8643. + 
  8644. +      function myfunc (win) {
  8645. +        print win
  8646. +        win = "zzz"
  8647. +        print win
  8648. +      }
  8649. + 
  8650. + to change its first argument variable `win', this *does not* change the
  8651. + value of `foo' in the caller.  The role of `foo' in calling `myfunc'
  8652. + ended when its value, `"bar"', was computed.  If `win' also exists
  8653. + outside of `myfunc', the function body cannot alter this outer value,
  8654. + because it is shadowed during the execution of `myfunc' and cannot be
  8655. + seen or changed from there.
  8656. + 
  8657. +    However, when arrays are the parameters to functions, they are *not*
  8658. + copied.  Instead, the array itself is made available for direct
  8659. + manipulation by the function.  This is usually called "call by
  8660. + reference".  Changes made to an array parameter inside the body of a
  8661. + function *are* visible outside that function.  This can be *very*
  8662. + dangerous if you do not watch what you are doing.  For example:
  8663. + 
  8664. +      function changeit (array, ind, nvalue) {
  8665. +           array[ind] = nvalue
  8666. +      }
  8667. +      
  8668. +      BEGIN {
  8669. +                 a[1] = 1 ; a[2] = 2 ; a[3] = 3
  8670. +                 changeit(a, 2, "two")
  8671. +                 printf "a[1] = %s, a[2] = %s, a[3] = %s\n", a[1], a[2], a[3]
  8672. +            }
  8673. + 
  8674. + prints `a[1] = 1, a[2] = two, a[3] = 3', because calling `changeit'
  8675. + stores `"two"' in the second element of `a'.
  8676. + 
  8677. + 
  8678. + File: gawk.info,  Node: Return Statement,  Prev: Function Caveats,  Up: User-defined
  8679. + 
  8680. + The `return' Statement
  8681. + ======================
  8682. + 
  8683. +    The body of a user-defined function can contain a `return' statement.
  8684. + This statement returns control to the rest of the `awk' program.  It
  8685. + can also be used to return a value for use in the rest of the `awk'
  8686. + program.  It looks like this:
  8687. + 
  8688. +      return EXPRESSION
  8689. + 
  8690. +    The EXPRESSION part is optional.  If it is omitted, then the returned
  8691. + value is undefined and, therefore, unpredictable.
  8692. + 
  8693. +    A `return' statement with no value expression is assumed at the end
  8694. + of every function definition.  So if control reaches the end of the
  8695. + function body, then the function returns an unpredictable value.  `awk'
  8696. + will not warn you if you use the return value of such a function; you
  8697. + will simply get unpredictable or unexpected results.
  8698. + 
  8699. +    Here is an example of a user-defined function that returns a value
  8700. + for the largest number among the elements of an array:
  8701. + 
  8702. +      function maxelt (vec,   i, ret) {
  8703. +           for (i in vec) {
  8704. +                if (ret == "" || vec[i] > ret)
  8705. +                     ret = vec[i]
  8706. +           }
  8707. +           return ret
  8708. +      }
  8709. + 
  8710. + You call `maxelt' with one argument, which is an array name.  The local
  8711. + variables `i' and `ret' are not intended to be arguments; while there
  8712. + is nothing to stop you from passing two or three arguments to `maxelt',
  8713. + the results would be strange.  The extra space before `i' in the
  8714. + function parameter list is to indicate that `i' and `ret' are not
  8715. + supposed to be arguments.  This is a convention which you should follow
  8716. + when you define functions.
  8717. + 
  8718. +    Here is a program that uses our `maxelt' function.  It loads an
  8719. + array, calls `maxelt', and then reports the maximum number in that
  8720. + array:
  8721. + 
  8722. +      awk '
  8723. +      function maxelt (vec,   i, ret) {
  8724. +           for (i in vec) {
  8725. +                if (ret == "" || vec[i] > ret)
  8726. +                     ret = vec[i]
  8727. +           }
  8728. +           return ret
  8729. +      }
  8730. +      
  8731. +      # Load all fields of each record into nums.
  8732. +      {
  8733. +                for(i = 1; i <= NF; i++)
  8734. +                     nums[NR, i] = $i
  8735. +      }
  8736. +      
  8737. +      END {
  8738. +           print maxelt(nums)
  8739. +      }'
  8740. + 
  8741. +    Given the following input:
  8742. + 
  8743. +       1 5 23 8 16
  8744. +      44 3 5 2 8 26
  8745. +      256 291 1396 2962 100
  8746. +      -6 467 998 1101
  8747. +      99385 11 0 225
  8748. + 
  8749. + our program tells us (predictably) that:
  8750. + 
  8751. +      99385
  8752. + 
  8753. + is the largest number in our array.
  8754. + 
  8755. + 
  8756. + File: gawk.info,  Node: Built-in Variables,  Next: Command Line,  Prev: User-defined,  Up: Top
  8757. + 
  8758. + Built-in Variables
  8759. + ******************
  8760. + 
  8761. +    Most `awk' variables are available for you to use for your own
  8762. + purposes; they never change except when your program assigns values to
  8763. + them, and never affect anything except when your program examines them.
  8764. + 
  8765. +    A few variables have special built-in meanings.  Some of them `awk'
  8766. + examines automatically, so that they enable you to tell `awk' how to do
  8767. + certain things.  Others are set automatically by `awk', so that they
  8768. + carry information from the internal workings of `awk' to your program.
  8769. + 
  8770. +    This chapter documents all the built-in variables of `gawk'.  Most
  8771. + of them are also documented in the chapters where their areas of
  8772. + activity are described.
  8773. + 
  8774. + * Menu:
  8775. + 
  8776. + * User-modified::               Built-in variables that you change
  8777. +                                 to control `awk'.
  8778. + * Auto-set::                    Built-in variables where `awk'
  8779. +                                 gives you information.
  8780. + 
  8781. + 
  8782. + File: gawk.info,  Node: User-modified,  Next: Auto-set,  Prev: Built-in Variables,  Up: Built-in Variables
  8783. + 
  8784. + Built-in Variables that Control `awk'
  8785. + =====================================
  8786. + 
  8787. +    This is a list of the variables which you can change to control how
  8788. + `awk' does certain things.
  8789. + 
  8790. + `CONVFMT'
  8791. +      This string is used by `awk' to control conversion of numbers to
  8792. +      strings (*note Conversion of Strings and Numbers: Conversion.).
  8793. +      It works by being passed, in effect, as the first argument to the
  8794. +      `sprintf' function.  Its default value is `"%.6g"'.  `CONVFMT' was
  8795. +      introduced by the POSIX standard.
  8796. + 
  8797. + `FIELDWIDTHS'
  8798. +      This is a space separated list of columns that tells `gawk' how to
  8799. +      manage input with fixed, columnar boundaries.  It is an
  8800. +      experimental feature that is still evolving.  Assigning to
  8801. +      `FIELDWIDTHS' overrides the use of `FS' for field splitting.
  8802. +      *Note Reading Fixed-width Data: Constant Size, for more
  8803. +      information.
  8804. + 
  8805. +      If `gawk' is in compatibility mode (*note Invoking `awk': Command
  8806. +      Line.), then `FIELDWIDTHS' has no special meaning, and field
  8807. +      splitting operations are done based exclusively on the value of
  8808. +      `FS'.
  8809. + 
  8810. + `FS'
  8811. +      `FS' is the input field separator (*note Specifying how Fields are
  8812. +      Separated: Field Separators.).  The value is a single-character
  8813. +      string or a multi-character regular expression that matches the
  8814. +      separations between fields in an input record.
  8815. + 
  8816. +      The default value is `" "', a string consisting of a single space.
  8817. +      As a special exception, this value actually means that any
  8818. +      sequence of spaces and tabs is a single separator.  It also causes
  8819. +      spaces and tabs at the beginning or end of a line to be ignored.
  8820. + 
  8821. +      You can set the value of `FS' on the command line using the `-F'
  8822. +      option:
  8823. + 
  8824. +           awk -F, 'PROGRAM' INPUT-FILES
  8825. + 
  8826. +      If `gawk' is using `FIELDWIDTHS' for field-splitting, assigning a
  8827. +      value to `FS' will cause `gawk' to return to the normal,
  8828. +      regexp-based, field splitting.
  8829. + 
  8830. + `IGNORECASE'
  8831. +      If `IGNORECASE' is nonzero, then *all* regular expression matching
  8832. +      is done in a case-independent fashion.  In particular, regexp
  8833. +      matching with `~' and `!~', and the `gsub' `index', `match',
  8834. +      `split' and `sub' functions all ignore case when doing their
  8835. +      particular regexp operations.  *Note:* since field splitting with
  8836. +      the value of the `FS' variable is also a regular expression
  8837. +      operation, that too is done with case ignored.  *Note
  8838. +      Case-sensitivity in Matching: Case-sensitivity.
  8839. + 
  8840. +      If `gawk' is in compatibility mode (*note Invoking `awk': Command
  8841. +      Line.), then `IGNORECASE' has no special meaning, and regexp
  8842. +      operations are always case-sensitive.
  8843. + 
  8844. + `OFMT'
  8845. +      This string is used by `awk' to control conversion of numbers to
  8846. +      strings (*note Conversion of Strings and Numbers: Conversion.) for
  8847. +      printing with the `print' statement.  It works by being passed, in
  8848. +      effect, as the first argument to the `sprintf' function.  Its
  8849. +      default value is `"%.6g"'.  Earlier versions of `awk' also used
  8850. +      `OFMT' to specify the format for converting numbers to strings in
  8851. +      general expressions; this has been taken over by `CONVFMT'.
  8852. + 
  8853. + `OFS'
  8854. +      This is the output field separator (*note Output Separators::.).
  8855. +      It is output between the fields output by a `print' statement.  Its
  8856. +      default value is `" "', a string consisting of a single space.
  8857. + 
  8858. + `ORS'
  8859. +      This is the output record separator.  It is output at the end of
  8860. +      every `print' statement.  Its default value is a string containing
  8861. +      a single newline character, which could be written as `"\n"'.
  8862. +      (*Note Output Separators::.)
  8863. + 
  8864. + `RS'
  8865. +      This is `awk''s input record separator.  Its default value is a
  8866. +      string containing a single newline character, which means that an
  8867. +      input record consists of a single line of text.  (*Note How Input
  8868. +      is Split into Records: Records.)
  8869. + 
  8870. + `SUBSEP'
  8871. +      `SUBSEP' is the subscript separator.  It has the default value of
  8872. +      `"\034"', and is used to separate the parts of the name of a
  8873. +      multi-dimensional array.  Thus, if you access `foo[12,3]', it
  8874. +      really accesses `foo["12\0343"]' (*note Multi-dimensional Arrays:
  8875. +      Multi-dimensional.).
  8876. + 
  8877. + 
  8878. + File: gawk.info,  Node: Auto-set,  Prev: User-modified,  Up: Built-in Variables
  8879. + 
  8880. + Built-in Variables that Convey Information
  8881. + ==========================================
  8882. + 
  8883. +    This is a list of the variables that are set automatically by `awk'
  8884. + on certain occasions so as to provide information to your program.
  8885. + 
  8886. + `ARGC'
  8887. + `ARGV'
  8888. +      The command-line arguments available to `awk' programs are stored
  8889. +      in an array called `ARGV'.  `ARGC' is the number of command-line
  8890. +      arguments present.  *Note Invoking `awk': Command Line.  `ARGV' is
  8891. +      indexed from zero to `ARGC - 1'.  For example:
  8892. + 
  8893. +           awk 'BEGIN {
  8894. +                  for (i = 0; i < ARGC; i++)
  8895. +                      print ARGV[i]
  8896. +                }' inventory-shipped BBS-list
  8897. + 
  8898. +      In this example, `ARGV[0]' contains `"awk"', `ARGV[1]' contains
  8899. +      `"inventory-shipped"', and `ARGV[2]' contains `"BBS-list"'.  The
  8900. +      value of `ARGC' is 3, one more than the index of the last element
  8901. +      in `ARGV' since the elements are numbered from zero.
  8902. + 
  8903. +      The names `ARGC' and `ARGV', as well the convention of indexing
  8904. +      the array from 0 to `ARGC - 1', are derived from the C language's
  8905. +      method of accessing command line arguments.
  8906. + 
  8907. +      Notice that the `awk' program is not entered in `ARGV'.  The other
  8908. +      special command line options, with their arguments, are also not
  8909. +      entered.  But variable assignments on the command line *are*
  8910. +      treated as arguments, and do show up in the `ARGV' array.
  8911. + 
  8912. +      Your program can alter `ARGC' and the elements of `ARGV'.  Each
  8913. +      time `awk' reaches the end of an input file, it uses the next
  8914. +      element of `ARGV' as the name of the next input file.  By storing a
  8915. +      different string there, your program can change which files are
  8916. +      read.  You can use `"-"' to represent the standard input.  By
  8917. +      storing additional elements and incrementing `ARGC' you can cause
  8918. +      additional files to be read.
  8919. + 
  8920. +      If you decrease the value of `ARGC', that eliminates input files
  8921. +      from the end of the list.  By recording the old value of `ARGC'
  8922. +      elsewhere, your program can treat the eliminated arguments as
  8923. +      something other than file names.
  8924. + 
  8925. +      To eliminate a file from the middle of the list, store the null
  8926. +      string (`""') into `ARGV' in place of the file's name.  As a
  8927. +      special feature, `awk' ignores file names that have been replaced
  8928. +      with the null string.
  8929. + 
  8930. + `ARGIND'
  8931. +      The index in `ARGV' of the current file being processed.  Every
  8932. +      time `gawk' opens a new data file for processing, it sets `ARGIND'
  8933. +      to the index in `ARGV' of the file name.  Thus, the condition
  8934. +      `FILENAME == ARGV[ARGIND]' is always true.
  8935. + 
  8936. +      This variable is useful in file processing; it allows you to tell
  8937. +      how far along you are in the list of data files, and to
  8938. +      distinguish between multiple successive instances of the same
  8939. +      filename on the command line.
  8940. + 
  8941. +      While you can change the value of `ARGIND' within your `awk'
  8942. +      program, `gawk' will automatically set it to a new value when the
  8943. +      next file is opened.
  8944. + 
  8945. +      This variable is a `gawk' extension; in other `awk' implementations
  8946. +      it is not special.
  8947. + 
  8948. + `ENVIRON'
  8949. +      This is an array that contains the values of the environment.  The
  8950. +      array indices are the environment variable names; the values are
  8951. +      the values of the particular environment variables.  For example,
  8952. +      `ENVIRON["HOME"]' might be `/u/close'.  Changing this array does
  8953. +      not affect the environment passed on to any programs that `awk'
  8954. +      may spawn via redirection or the `system' function.  (In a future
  8955. +      version of `gawk', it may do so.)
  8956. + 
  8957. +      Some operating systems may not have environment variables.  On
  8958. +      such systems, the array `ENVIRON' is empty.
  8959. + 
  8960. + `ERRNO'
  8961. +      If a system error occurs either doing a redirection for `getline',
  8962. +      during a read for `getline', or during a `close' operation, then
  8963. +      `ERRNO' will contain a string describing the error.
  8964. + 
  8965. +      This variable is a `gawk' extension; in other `awk' implementations
  8966. +      it is not special.
  8967. + 
  8968. + `FILENAME'
  8969. +      This is the name of the file that `awk' is currently reading.  If
  8970. +      `awk' is reading from the standard input (in other words, there
  8971. +      are no files listed on the command line), `FILENAME' is set to
  8972. +      `"-"'.  `FILENAME' is changed each time a new file is read (*note
  8973. +      Reading Input Files: Reading Files.).
  8974. + 
  8975. + `FNR'
  8976. +      `FNR' is the current record number in the current file.  `FNR' is
  8977. +      incremented each time a new record is read (*note Explicit Input
  8978. +      with `getline': Getline.).  It is reinitialized to 0 each time a
  8979. +      new input file is started.
  8980. + 
  8981. + `NF'
  8982. +      `NF' is the number of fields in the current input record.  `NF' is
  8983. +      set each time a new record is read, when a new field is created,
  8984. +      or when `$0' changes (*note Examining Fields: Fields.).
  8985. + 
  8986. + `NR'
  8987. +      This is the number of input records `awk' has processed since the
  8988. +      beginning of the program's execution.  (*note How Input is Split
  8989. +      into Records: Records.).  `NR' is set each time a new record is
  8990. +      read.
  8991. + 
  8992. + `RLENGTH'
  8993. +      `RLENGTH' is the length of the substring matched by the `match'
  8994. +      function (*note Built-in Functions for String Manipulation: String
  8995. +      Functions.).  `RLENGTH' is set by invoking the `match' function.
  8996. +      Its value is the length of the matched string, or -1 if no match
  8997. +      was found.
  8998. + 
  8999. + `RSTART'
  9000. +      `RSTART' is the start-index in characters of the substring matched
  9001. +      by the `match' function (*note Built-in Functions for String
  9002. +      Manipulation: String Functions.).  `RSTART' is set by invoking the
  9003. +      `match' function.  Its value is the position of the string where
  9004. +      the matched substring starts, or 0 if no match was found.
  9005. + 
  9006. + 
  9007. + File: gawk.info,  Node: Command Line,  Next: Language History,  Prev: Built-in Variables,  Up: Top
  9008. + 
  9009. + Invoking `awk'
  9010. + **************
  9011. + 
  9012. +    There are two ways to run `awk': with an explicit program, or with
  9013. + one or more program files.  Here are templates for both of them; items
  9014. + enclosed in `[...]' in these templates are optional.
  9015. + 
  9016. +    Besides traditional one-letter POSIX-style options, `gawk' also
  9017. + supports GNU long named options.
  9018. + 
  9019. +      awk [POSIX OR GNU STYLE OPTIONS] -f progfile [`--'] FILE ...
  9020. +      awk [POSIX OR GNU STYLE OPTIONS] [`--'] 'PROGRAM' FILE ...
  9021. + 
  9022. + * Menu:
  9023. + 
  9024. + * Options::                     Command line options and their meanings.
  9025. + * Other Arguments::             Input file names and variable assignments.
  9026. + * AWKPATH Variable::            Searching directories for `awk' programs.
  9027. + * Obsolete::                    Obsolete Options and/or features.
  9028. + * Undocumented::                Undocumented Options and Features.
  9029. + 
  9030. + 
  9031. + File: gawk.info,  Node: Options,  Next: Other Arguments,  Prev: Command Line,  Up: Command Line
  9032. + 
  9033. + Command Line Options
  9034. + ====================
  9035. + 
  9036. +    Options begin with a minus sign, and consist of a single character.
  9037. + GNU style long named options consist of two minus signs and a keyword
  9038. + that can be abbreviated if the abbreviation allows the option to be
  9039. + uniquely identified.  If the option takes an argument, then the keyword
  9040. + is immediately followed by an equals sign (`=') and the argument's
  9041. + value.  For brevity, the discussion below only refers to the
  9042. + traditional short options; however the long and short options are
  9043. + interchangeable in all contexts.
  9044. + 
  9045. +    Each long named option for `gawk' has a corresponding POSIX-style
  9046. + option.  The options and their meanings are as follows:
  9047. + 
  9048. + `-F FS'
  9049. + `--field-separator=FS'
  9050. +      Sets the `FS' variable to FS (*note Specifying how Fields are
  9051. +      Separated: Field Separators.).
  9052. + 
  9053. + `-f SOURCE-FILE'
  9054. + `--file=SOURCE-FILE'
  9055. +      Indicates that the `awk' program is to be found in SOURCE-FILE
  9056. +      instead of in the first non-option argument.
  9057. + 
  9058. + `-v VAR=VAL'
  9059. + `--assign=VAR=VAL'
  9060. +      Sets the variable VAR to the value VAL *before* execution of the
  9061. +      program begins.  Such variable values are available inside the
  9062. +      `BEGIN' rule (see below for a fuller explanation).
  9063. + 
  9064. +      The `-v' option can only set one variable, but you can use it more
  9065. +      than once, setting another variable each time, like this:
  9066. +      `-v foo=1 -v bar=2'.
  9067. + 
  9068. + `-W GAWK-OPT'
  9069. +      Following the POSIX standard, options that are implementation
  9070. +      specific are supplied as arguments to the `-W' option.  With
  9071. +      `gawk', these arguments may be separated by commas, or quoted and
  9072. +      separated by whitespace.  Case is ignored when processing these
  9073. +      options.  These options also have corresponding GNU style long
  9074. +      named options.  The following `gawk'-specific options are
  9075. +      available:
  9076. + 
  9077. +     `-W compat'
  9078. +     `--compat'
  9079. +           Specifies "compatibility mode", in which the GNU extensions in
  9080. +           `gawk' are disabled, so that `gawk' behaves just like Unix
  9081. +           `awk'.  *Note Extensions in `gawk' not in POSIX `awk':
  9082. +           POSIX/GNU, which summarizes the extensions.  Also see *Note
  9083. +           Downward Compatibility and Debugging: Compatibility Mode.
  9084. + 
  9085. +     `-W copyleft'
  9086. +     `-W copyright'
  9087. +     `--copyleft'
  9088. +     `--copyright'
  9089. +           Print the short version of the General Public License.  This
  9090. +           option may disappear in a future version of `gawk'.
  9091. + 
  9092. +     `-W help'
  9093. +     `-W usage'
  9094. +     `--help'
  9095. +     `--usage'
  9096. +           Print a "usage" message summarizing the short and long style
  9097. +           options that `gawk' accepts, and then exit.
  9098. + 
  9099. +     `-W lint'
  9100. +     `--lint'
  9101. +           Provide warnings about constructs that are dubious or
  9102. +           non-portable to other `awk' implementations.  Some warnings
  9103. +           are issued when `gawk' first reads your program.  Others are
  9104. +           issued at run-time, as your program executes.
  9105. + 
  9106. +     `-W posix'
  9107. +     `--posix'
  9108. +           Operate in strict POSIX mode.  This disables all `gawk'
  9109. +           extensions (just like `-W compat'), and adds the following
  9110. +           additional restrictions:
  9111. + 
  9112. +              * `\x' escape sequences are not recognized (*note Constant
  9113. +                Expressions: Constants.).
  9114. + 
  9115. +              * The synonym `func' for the keyword `function' is not
  9116. +                recognized (*note Syntax of Function Definitions:
  9117. +                Definition Syntax.).
  9118. + 
  9119. +              * The operators `**' and `**=' cannot be used in place of
  9120. +                `^' and `^=' (*note Arithmetic Operators: Arithmetic
  9121. +                Ops., and also *note Assignment Expressions: Assignment
  9122. +                Ops.).
  9123. + 
  9124. +              * Specifying `-Ft' on the command line does not set the
  9125. +                value of `FS' to be a single tab character (*note
  9126. +                Specifying how Fields are Separated: Field Separators.).
  9127. + 
  9128. +           Although you can supply both `-W compat' and `-W posix' on the
  9129. +           command line, `-W posix' will take precedence.
  9130. + 
  9131. +     `-W source=PROGRAM-TEXT'
  9132. +     `--source=PROGRAM-TEXT'
  9133. +           Program source code is taken from the PROGRAM-TEXT.  This
  9134. +           option allows you to mix `awk' source code in files with
  9135. +           program source code that you would enter on the command line.
  9136. +           This is particularly useful when you have library functions
  9137. +           that you wish to use from your command line programs (*note
  9138. +           The `AWKPATH' Environment Variable: AWKPATH Variable.).
  9139. + 
  9140. +     `-W version'
  9141. +     `--version'
  9142. +           Prints version information for this particular copy of `gawk'.
  9143. +           This is so you can determine if your copy of `gawk' is up to
  9144. +           date with respect to whatever the Free Software Foundation is
  9145. +           currently distributing.  This option may disappear in a
  9146. +           future version of `gawk'.
  9147. + 
  9148. + `--'
  9149. +      Signals the end of the command line options.  The following
  9150. +      arguments are not treated as options even if they begin with `-'.
  9151. +      This interpretation of `--' follows the POSIX argument parsing
  9152. +      conventions.
  9153. + 
  9154. +      This is useful if you have file names that start with `-', or in
  9155. +      shell scripts, if you have file names that will be specified by
  9156. +      the user which could start with `-'.
  9157. + 
  9158. +    Any other options are flagged as invalid with a warning message, but
  9159. + are otherwise ignored.
  9160. + 
  9161. +    In compatibility mode, as a special case, if the value of FS supplied
  9162. + to the `-F' option is `t', then `FS' is set to the tab character
  9163. + (`"\t"').  This is only true for `-W compat', and not for `-W posix'
  9164. + (*note Specifying how Fields are Separated: Field Separators.).
  9165. + 
  9166. +    If the `-f' option is *not* used, then the first non-option command
  9167. + line argument is expected to be the program text.
  9168. + 
  9169. +    The `-f' option may be used more than once on the command line.  If
  9170. + it is, `awk' reads its program source from all of the named files, as
  9171. + if they had been concatenated together into one big file.  This is
  9172. + useful for creating libraries of `awk' functions.  Useful functions can
  9173. + be written once, and then retrieved from a standard place, instead of
  9174. + having to be included into each individual program.  You can still type
  9175. + in a program at the terminal and use library functions, by specifying
  9176. + `-f /dev/tty'.  `awk' will read a file from the terminal to use as part
  9177. + of the `awk' program.  After typing your program, type `Control-d' (the
  9178. + end-of-file character) to terminate it.  (You may also use `-f -' to
  9179. + read program source from the standard input, but then you will not be
  9180. + able to also use the standard input as a source of data.)
  9181. + 
  9182. +    Because it is clumsy using the standard `awk' mechanisms to mix
  9183. + source file and command line `awk' programs, `gawk' provides the
  9184. + `--source' option.  This does not require you to pre-empt the standard
  9185. + input for your source code, and allows you to easily mix command line
  9186. + and library source code (*note The `AWKPATH' Environment Variable:
  9187. + AWKPATH Variable.).
  9188. + 
  9189. +    If no `-f' or `--source' option is specified, then `gawk' will use
  9190. + the first non-option command line argument as the text of the program
  9191. + source code.
  9192. + 
  9193. + 
  9194. + File: gawk.info,  Node: Other Arguments,  Next: AWKPATH Variable,  Prev: Options,  Up: Command Line
  9195. + 
  9196. + Other Command Line Arguments
  9197. + ============================
  9198. + 
  9199. +    Any additional arguments on the command line are normally treated as
  9200. + input files to be processed in the order specified.  However, an
  9201. + argument that has the form `VAR=VALUE', means to assign the value VALUE
  9202. + to the variable VAR--it does not specify a file at all.
  9203. + 
  9204. +    All these arguments are made available to your `awk' program in the
  9205. + `ARGV' array (*note Built-in Variables::.).  Command line options and
  9206. + the program text (if present) are omitted from the `ARGV' array.  All
  9207. + other arguments, including variable assignments, are included.
  9208. + 
  9209. +    The distinction between file name arguments and variable-assignment
  9210. + arguments is made when `awk' is about to open the next input file.  At
  9211. + that point in execution, it checks the "file name" to see whether it is
  9212. + really a variable assignment; if so, `awk' sets the variable instead of
  9213. + reading a file.
  9214. + 
  9215. +    Therefore, the variables actually receive the specified values after
  9216. + all previously specified files have been read.  In particular, the
  9217. + values of variables assigned in this fashion are *not* available inside
  9218. + a `BEGIN' rule (*note `BEGIN' and `END' Special Patterns: BEGIN/END.),
  9219. + since such rules are run before `awk' begins scanning the argument list.
  9220. + The values given on the command line are processed for escape sequences
  9221. + (*note Constant Expressions: Constants.).
  9222. + 
  9223. +    In some earlier implementations of `awk', when a variable assignment
  9224. + occurred before any file names, the assignment would happen *before*
  9225. + the `BEGIN' rule was executed.  Some applications came to depend upon
  9226. + this "feature."  When `awk' was changed to be more consistent, the `-v'
  9227. + option was added to accommodate applications that depended upon this
  9228. + old behavior.
  9229. + 
  9230. +    The variable assignment feature is most useful for assigning to
  9231. + variables such as `RS', `OFS', and `ORS', which control input and
  9232. + output formats, before scanning the data files.  It is also useful for
  9233. + controlling state if multiple passes are needed over a data file.  For
  9234. + example:
  9235. + 
  9236. +      awk 'pass == 1  { PASS 1 STUFF }
  9237. +           pass == 2  { PASS 2 STUFF }' pass=1 datafile pass=2 datafile
  9238. + 
  9239. +    Given the variable assignment feature, the `-F' option is not
  9240. + strictly necessary.  It remains for historical compatibility.
  9241. + 
  9242. + 
  9243. + File: gawk.info,  Node: AWKPATH Variable,  Next: Obsolete,  Prev: Other Arguments,  Up: Command Line
  9244. + 
  9245. + The `AWKPATH' Environment Variable
  9246. + ==================================
  9247. + 
  9248. +    The previous section described how `awk' program files can be named
  9249. + on the command line with the `-f' option.  In some `awk'
  9250. + implementations, you must supply a precise path name for each program
  9251. + file, unless the file is in the current directory.
  9252. + 
  9253. +    But in `gawk', if the file name supplied in the `-f' option does not
  9254. + contain a `/', then `gawk' searches a list of directories (called the
  9255. + "search path"), one by one, looking for a file with the specified name.
  9256. + 
  9257. +    The search path is actually a string consisting of directory names
  9258. + separated by colons.  `gawk' gets its search path from the `AWKPATH'
  9259. + environment variable.  If that variable does not exist, `gawk' uses the
  9260. + default path, which is `.:/local/lib/awk:/gnu/lib/awk'.  (Programs
  9261. + written by system administrators should use an `AWKPATH' variable that
  9262. + does not include the current directory, `.'.)
  9263. + 
  9264. +    The search path feature is particularly useful for building up
  9265. + libraries of useful `awk' functions.  The library files can be placed
  9266. + in a standard directory that is in the default path, and then specified
  9267. + on the command line with a short file name.  Otherwise, the full file
  9268. + name would have to be typed for each file.
  9269. + 
  9270. +    By combining the `--source' and `-f' options, your command line
  9271. + `awk' programs can use facilities in `awk' library files.
  9272. + 
  9273. +    Path searching is not done if `gawk' is in compatibility mode.  This
  9274. + is true for both `-W compat' and `-W posix'.  *Note Command Line
  9275. + Options: Options.
  9276. + 
  9277. +    *Note:* if you want files in the current directory to be found, you
  9278. + must include the current directory in the path, either by writing `.'
  9279. + as an entry in the path, or by writing a null entry in the path.  (A
  9280. + null entry is indicated by starting or ending the path with a colon, or
  9281. + by placing two colons next to each other (`::').)  If the current
  9282. + directory is not included in the path, then files cannot be found in
  9283. + the current directory.  This path search mechanism is identical to the
  9284. + shell's.
  9285. + 
  9286. + 
  9287. + File: gawk.info,  Node: Obsolete,  Next: Undocumented,  Prev: AWKPATH Variable,  Up: Command Line
  9288. + 
  9289. + Obsolete Options and/or Features
  9290. + ================================
  9291. + 
  9292. +    This section describes features and/or command line options from the
  9293. + previous release of `gawk' that are either not available in the current
  9294. + version, or that are still supported but deprecated (meaning that they
  9295. + will *not* be in the next release).
  9296. + 
  9297. +    For version 2.15 of `gawk', the following command line options from
  9298. + version 2.11.1 are no longer recognized.
  9299. + 
  9300. + `-c'
  9301. +      Use `-W compat' instead.
  9302. + 
  9303. + `-V'
  9304. +      Use `-W version' instead.
  9305. + 
  9306. + `-C'
  9307. +      Use `-W copyright' instead.
  9308. + 
  9309. + `-a'
  9310. + `-e'
  9311. +      These options produce an "unrecognized option" error message but
  9312. +      have no effect on the execution of `gawk'.  The POSIX standard now
  9313. +      specifies traditional `awk' regular expressions for the `awk'
  9314. +      utility.
  9315. + 
  9316. +    The public-domain version of `strftime' that is distributed with
  9317. + `gawk' changed for the 2.14 release.  The `%V' conversion specifier
  9318. + that used to generate the date in VMS format was changed to `%v'.  This
  9319. + is because the POSIX standard for the `date' utility now specifies a
  9320. + `%V' conversion specifier.  *Note Functions for Dealing with Time
  9321. + Stamps: Time Functions, for details.
  9322. + 
  9323. + 
  9324. + File: gawk.info,  Node: Undocumented,  Prev: Obsolete,  Up: Command Line
  9325. + 
  9326. + Undocumented Options and Features
  9327. + =================================
  9328. + 
  9329. +    This section intentionally left blank.
  9330. + 
  9331. + 
  9332. + File: gawk.info,  Node: Language History,  Next: Installation,  Prev: Command Line,  Up: Top
  9333. + 
  9334. + The Evolution of the `awk' Language
  9335. + ***********************************
  9336. + 
  9337. +    This manual describes the GNU implementation of `awk', which is
  9338. + patterned after the POSIX specification.  Many `awk' users are only
  9339. + familiar with the original `awk' implementation in Version 7 Unix,
  9340. + which is also the basis for the version in Berkeley Unix (through
  9341. + 4.3-Reno).  This chapter briefly describes the evolution of the `awk'
  9342. + language.
  9343. + 
  9344. + * Menu:
  9345. + 
  9346. + * V7/S5R3.1::                   The major changes between V7 and
  9347. +                                 System V Release 3.1.
  9348. + * S5R4::                        Minor changes between System V
  9349. +                                 Releases 3.1 and 4.
  9350. + * POSIX::                       New features from the POSIX standard.
  9351. + * POSIX/GNU::                   The extensions in `gawk'
  9352. +                                 not in POSIX `awk'.
  9353. + 
  9354. diff -rc --new-file /src/baseline/gawk-2.15.5/gawk.info-7 gawk-2.15.5/gawk.info-7
  9355. *** /src/baseline/gawk-2.15.5/gawk.info-7    Thu Jan  1 00:00:00 1970
  9356. --- gawk-2.15.5/gawk.info-7    Sun Jun 12 22:28:55 1994
  9357. ***************
  9358. *** 0 ****
  9359. --- 1,1265 ----
  9360. + This is Info file gawk.info, produced by Makeinfo-1.55 from the input
  9361. + file /gnu/src/amiga/gawk-2.15.5/gawk.texi.
  9362. + 
  9363. +    This file documents `awk', a program that you can use to select
  9364. + particular records in a file and perform operations upon them.
  9365. + 
  9366. +    This is Edition 0.15 of `The GAWK Manual',
  9367. + for the 2.15 version of the GNU implementation
  9368. + of AWK.
  9369. + 
  9370. +    Copyright (C) 1989, 1991, 1992, 1993 Free Software Foundation, Inc.
  9371. + 
  9372. +    Permission is granted to make and distribute verbatim copies of this
  9373. + manual provided the copyright notice and this permission notice are
  9374. + preserved on all copies.
  9375. + 
  9376. +    Permission is granted to copy and distribute modified versions of
  9377. + this manual under the conditions for verbatim copying, provided that
  9378. + the entire resulting derived work is distributed under the terms of a
  9379. + permission notice identical to this one.
  9380. + 
  9381. +    Permission is granted to copy and distribute translations of this
  9382. + manual into another language, under the above conditions for modified
  9383. + versions, except that this permission notice may be stated in a
  9384. + translation approved by the Foundation.
  9385. + 
  9386. + 
  9387. + File: gawk.info,  Node: V7/S5R3.1,  Next: S5R4,  Prev: Language History,  Up: Language History
  9388. + 
  9389. + Major Changes between V7 and S5R3.1
  9390. + ===================================
  9391. + 
  9392. +    The `awk' language evolved considerably between the release of
  9393. + Version 7 Unix (1978) and the new version first made widely available in
  9394. + System V Release 3.1 (1987).  This section summarizes the changes, with
  9395. + cross-references to further details.
  9396. + 
  9397. +    * The requirement for `;' to separate rules on a line (*note `awk'
  9398. +      Statements versus Lines: Statements/Lines.).
  9399. + 
  9400. +    * User-defined functions, and the `return' statement (*note
  9401. +      User-defined Functions: User-defined.).
  9402. + 
  9403. +    * The `delete' statement (*note The `delete' Statement: Delete.).
  9404. + 
  9405. +    * The `do'-`while' statement (*note The `do'-`while' Statement: Do
  9406. +      Statement.).
  9407. + 
  9408. +    * The built-in functions `atan2', `cos', `sin', `rand' and `srand'
  9409. +      (*note Numeric Built-in Functions: Numeric Functions.).
  9410. + 
  9411. +    * The built-in functions `gsub', `sub', and `match' (*note Built-in
  9412. +      Functions for String Manipulation: String Functions.).
  9413. + 
  9414. +    * The built-in functions `close', which closes an open file, and
  9415. +      `system', which allows the user to execute operating system
  9416. +      commands (*note Built-in Functions for Input/Output: I/O
  9417. +      Functions.).
  9418. + 
  9419. +    * The `ARGC', `ARGV', `FNR', `RLENGTH', `RSTART', and `SUBSEP'
  9420. +      built-in variables (*note Built-in Variables::.).
  9421. + 
  9422. +    * The conditional expression using the operators `?' and `:' (*note
  9423. +      Conditional Expressions: Conditional Exp.).
  9424. + 
  9425. +    * The exponentiation operator `^' (*note Arithmetic Operators:
  9426. +      Arithmetic Ops.) and its assignment operator form `^=' (*note
  9427. +      Assignment Expressions: Assignment Ops.).
  9428. + 
  9429. +    * C-compatible operator precedence, which breaks some old `awk'
  9430. +      programs (*note Operator Precedence (How Operators Nest):
  9431. +      Precedence.).
  9432. + 
  9433. +    * Regexps as the value of `FS' (*note Specifying how Fields are
  9434. +      Separated: Field Separators.), and as the third argument to the
  9435. +      `split' function (*note Built-in Functions for String
  9436. +      Manipulation: String Functions.).
  9437. + 
  9438. +    * Dynamic regexps as operands of the `~' and `!~' operators (*note
  9439. +      How to Use Regular Expressions: Regexp Usage.).
  9440. + 
  9441. +    * Escape sequences (*note Constant Expressions: Constants.) in
  9442. +      regexps.
  9443. + 
  9444. +    * The escape sequences `\b', `\f', and `\r' (*note Constant
  9445. +      Expressions: Constants.).
  9446. + 
  9447. +    * Redirection of input for the `getline' function (*note Explicit
  9448. +      Input with `getline': Getline.).
  9449. + 
  9450. +    * Multiple `BEGIN' and `END' rules (*note `BEGIN' and `END' Special
  9451. +      Patterns: BEGIN/END.).
  9452. + 
  9453. +    * Simulated multi-dimensional arrays (*note Multi-dimensional
  9454. +      Arrays: Multi-dimensional.).
  9455. + 
  9456. + 
  9457. + File: gawk.info,  Node: S5R4,  Next: POSIX,  Prev: V7/S5R3.1,  Up: Language History
  9458. + 
  9459. + Changes between S5R3.1 and S5R4
  9460. + ===============================
  9461. + 
  9462. +    The System V Release 4 version of Unix `awk' added these features
  9463. + (some of which originated in `gawk'):
  9464. + 
  9465. +    * The `ENVIRON' variable (*note Built-in Variables::.).
  9466. + 
  9467. +    * Multiple `-f' options on the command line (*note Invoking `awk':
  9468. +      Command Line.).
  9469. + 
  9470. +    * The `-v' option for assigning variables before program execution
  9471. +      begins (*note Invoking `awk': Command Line.).
  9472. + 
  9473. +    * The `--' option for terminating command line options.
  9474. + 
  9475. +    * The `\a', `\v', and `\x' escape sequences (*note Constant
  9476. +      Expressions: Constants.).
  9477. + 
  9478. +    * A defined return value for the `srand' built-in function (*note
  9479. +      Numeric Built-in Functions: Numeric Functions.).
  9480. + 
  9481. +    * The `toupper' and `tolower' built-in string functions for case
  9482. +      translation (*note Built-in Functions for String Manipulation:
  9483. +      String Functions.).
  9484. + 
  9485. +    * A cleaner specification for the `%c' format-control letter in the
  9486. +      `printf' function (*note Using `printf' Statements for Fancier
  9487. +      Printing: Printf.).
  9488. + 
  9489. +    * The ability to dynamically pass the field width and precision
  9490. +      (`"%*.*d"') in the argument list of the `printf' function (*note
  9491. +      Using `printf' Statements for Fancier Printing: Printf.).
  9492. + 
  9493. +    * The use of constant regexps such as `/foo/' as expressions, where
  9494. +      they are equivalent to use of the matching operator, as in `$0 ~
  9495. +      /foo/' (*note Constant Expressions: Constants.).
  9496. + 
  9497. + 
  9498. + File: gawk.info,  Node: POSIX,  Next: POSIX/GNU,  Prev: S5R4,  Up: Language History
  9499. + 
  9500. + Changes between S5R4 and POSIX `awk'
  9501. + ====================================
  9502. + 
  9503. +    The POSIX Command Language and Utilities standard for `awk'
  9504. + introduced the following changes into the language:
  9505. + 
  9506. +    * The use of `-W' for implementation-specific options.
  9507. + 
  9508. +    * The use of `CONVFMT' for controlling the conversion of numbers to
  9509. +      strings (*note Conversion of Strings and Numbers: Conversion.).
  9510. + 
  9511. +    * The concept of a numeric string, and tighter comparison rules to go
  9512. +      with it (*note Comparison Expressions: Comparison Ops.).
  9513. + 
  9514. +    * More complete documentation of many of the previously undocumented
  9515. +      features of the language.
  9516. + 
  9517. + 
  9518. + File: gawk.info,  Node: POSIX/GNU,  Prev: POSIX,  Up: Language History
  9519. + 
  9520. + Extensions in `gawk' not in POSIX `awk'
  9521. + =======================================
  9522. + 
  9523. +    The GNU implementation, `gawk', adds these features:
  9524. + 
  9525. +    * The `AWKPATH' environment variable for specifying a path search for
  9526. +      the `-f' command line option (*note Invoking `awk': Command Line.).
  9527. + 
  9528. +    * The various `gawk' specific features available via the `-W'
  9529. +      command line option (*note Invoking `awk': Command Line.).
  9530. + 
  9531. +    * The `ARGIND' variable, that tracks the movement of `FILENAME'
  9532. +      through `ARGV'.  (*note Built-in Variables::.).
  9533. + 
  9534. +    * The `ERRNO' variable, that contains the system error message when
  9535. +      `getline' returns -1, or when `close' fails.  (*note Built-in
  9536. +      Variables::.).
  9537. + 
  9538. +    * The `IGNORECASE' variable and its effects (*note Case-sensitivity
  9539. +      in Matching: Case-sensitivity.).
  9540. + 
  9541. +    * The `FIELDWIDTHS' variable and its effects (*note Reading
  9542. +      Fixed-width Data: Constant Size.).
  9543. + 
  9544. +    * The `next file' statement for skipping to the next data file
  9545. +      (*note The `next file' Statement: Next File Statement.).
  9546. + 
  9547. +    * The `systime' and `strftime' built-in functions for obtaining and
  9548. +      printing time stamps (*note Functions for Dealing with Time
  9549. +      Stamps: Time Functions.).
  9550. + 
  9551. +    * The `/dev/stdin', `/dev/stdout', `/dev/stderr', and `/dev/fd/N'
  9552. +      file name interpretation (*note Standard I/O Streams: Special
  9553. +      Files.).
  9554. + 
  9555. +    * The `-W compat' option to turn off these extensions (*note
  9556. +      Invoking `awk': Command Line.).
  9557. + 
  9558. +    * The `-W posix' option for full POSIX compliance (*note Invoking
  9559. +      `awk': Command Line.).
  9560. + 
  9561. + 
  9562. + File: gawk.info,  Node: Installation,  Next: Gawk Summary,  Prev: Language History,  Up: Top
  9563. + 
  9564. + Installing `gawk'
  9565. + *****************
  9566. + 
  9567. +    This chapter provides instructions for installing `gawk' on the
  9568. + various platforms that are supported by the developers.  The primary
  9569. + developers support Unix (and one day, GNU), while the other ports were
  9570. + contributed.  The file `ACKNOWLEDGMENT' in the `gawk' distribution
  9571. + lists the electronic mail addresses of the people who did the
  9572. + respective ports.
  9573. + 
  9574. + * Menu:
  9575. + 
  9576. + * Gawk Distribution::           What is in the `gawk' distribution.
  9577. + * Unix Installation::           Installing `gawk' under various versions
  9578. +                                 of Unix.
  9579. + * VMS Installation::            Installing `gawk' on VMS.
  9580. + * MS-DOS Installation::         Installing `gawk' on MS-DOS.
  9581. + * Atari Installation::          Installing `gawk' on the Atari ST.
  9582. + 
  9583. + 
  9584. + File: gawk.info,  Node: Gawk Distribution,  Next: Unix Installation,  Prev: Installation,  Up: Installation
  9585. + 
  9586. + The `gawk' Distribution
  9587. + =======================
  9588. + 
  9589. +    This section first describes how to get and extract the `gawk'
  9590. + distribution, and then discusses what is in the various files and
  9591. + subdirectories.
  9592. + 
  9593. + * Menu:
  9594. + 
  9595. + * Extracting::                  How to get and extract the distribution.
  9596. + * Distribution contents::       What is in the distribution.
  9597. + 
  9598. + 
  9599. + File: gawk.info,  Node: Extracting,  Next: Distribution contents,  Prev: Gawk Distribution,  Up: Gawk Distribution
  9600. + 
  9601. + Getting the `gawk' Distribution
  9602. + -------------------------------
  9603. + 
  9604. +    `gawk' is distributed as a `tar' file compressed with the GNU Zip
  9605. + program, `gzip'.  You can get it via anonymous `ftp' to the Internet
  9606. + host `prep.ai.mit.edu'.  Like all GNU software, it will be archived at
  9607. + other well known systems, from which it will be possible to use some
  9608. + sort of anonymous `uucp' to obtain the distribution as well.  You can
  9609. + also order `gawk' on tape or CD-ROM directly from the Free Software
  9610. + Foundation.  (The address is on the copyright page.) Doing so directly
  9611. + contributes to the support of the foundation and to the production of
  9612. + more free software.
  9613. + 
  9614. +    Once you have the distribution (for example, `gawk-2.15.0.tar.z'),
  9615. + first use `gzip' to expand the file, and then use `tar' to extract it.
  9616. + You can use the following pipeline to produce the `gawk' distribution:
  9617. + 
  9618. +      # Under System V, add 'o' to the tar flags
  9619. +      gzip -d -c gawk-2.15.0.tar.z | tar -xvpf -
  9620. + 
  9621. + This will create a directory named `gawk-2.15' in the current directory.
  9622. + 
  9623. +    The distribution file name is of the form `gawk-2.15.N.tar.Z'.  The
  9624. + N represents a "patchlevel", meaning that minor bugs have been fixed in
  9625. + the major release.  The current patchlevel is 0, but when retrieving
  9626. + distributions, you should get the version with the highest patchlevel.
  9627. + 
  9628. +    If you are not on a Unix system, you will need to make other
  9629. + arrangements for getting and extracting the `gawk' distribution.  You
  9630. + should consult a local expert.
  9631. + 
  9632. + 
  9633. + File: gawk.info,  Node: Distribution contents,  Prev: Extracting,  Up: Gawk Distribution
  9634. + 
  9635. + Contents of the `gawk' Distribution
  9636. + -----------------------------------
  9637. + 
  9638. +    `gawk' has a number of C source files, documentation files,
  9639. + subdirectories and files related to the configuration process (*note
  9640. + Compiling and Installing `gawk' on Unix: Unix Installation.), and
  9641. + several subdirectories related to different, non-Unix, operating
  9642. + systems.
  9643. + 
  9644. + various `.c', `.y', and `.h' files
  9645. +      The C and YACC source files are the actual `gawk' source code.
  9646. + 
  9647. + `README'
  9648. + `README.VMS'
  9649. + `README.dos'
  9650. + `README.rs6000'
  9651. + `README.ultrix'
  9652. +      Descriptive files: `README' for `gawk' under Unix, and the rest
  9653. +      for the various hardware and software combinations.
  9654. + 
  9655. + `PORTS'
  9656. +      A list of systems to which `gawk' has been ported, and which have
  9657. +      successfully run the test suite.
  9658. + 
  9659. + `ACKNOWLEDGMENT'
  9660. +      A list of the people who contributed major parts of the code or
  9661. +      documentation.
  9662. + 
  9663. + `NEWS'
  9664. +      A list of changes to `gawk' since the last release or patch.
  9665. + 
  9666. + `COPYING'
  9667. +      The GNU General Public License.
  9668. + 
  9669. + `FUTURES'
  9670. +      A brief list of features and/or changes being contemplated for
  9671. +      future releases, with some indication of the time frame for the
  9672. +      feature, based on its difficulty.
  9673. + 
  9674. + `LIMITATIONS'
  9675. +      A list of those factors that limit `gawk''s performance.  Most of
  9676. +      these depend on the hardware or operating system software, and are
  9677. +      not limits in `gawk' itself.
  9678. + 
  9679. + `PROBLEMS'
  9680. +      A file describing known problems with the current release.
  9681. + 
  9682. + `gawk.1'
  9683. +      The `troff' source for a manual page describing `gawk'.
  9684. + 
  9685. + `gawk.texinfo'
  9686. +      The `texinfo' source file for this Info file.  It should be
  9687. +      processed with TeX to produce a printed manual, and with
  9688. +      `makeinfo' to produce the Info file.
  9689. + 
  9690. + `Makefile.in'
  9691. + `config'
  9692. + `config.in'
  9693. + `configure'
  9694. + `missing'
  9695. + `mungeconf'
  9696. +      These files and subdirectories are used when configuring `gawk'
  9697. +      for various Unix systems.  They are explained in detail in *Note
  9698. +      Compiling and Installing `gawk' on Unix: Unix Installation.
  9699. + 
  9700. + `atari'
  9701. +      Files needed for building `gawk' on an Atari ST.  *Note Installing
  9702. +      `gawk' on the Atari ST: Atari Installation, for details.
  9703. + 
  9704. + `pc'
  9705. +      Files needed for building `gawk' under MS-DOS.  *Note Installing
  9706. +      `gawk' on MS-DOS: MS-DOS Installation, for details.
  9707. + 
  9708. + `vms'
  9709. +      Files needed for building `gawk' under VMS.  *Note Compiling
  9710. +      Installing and Running `gawk' on VMS: VMS Installation, for
  9711. +      details.
  9712. + 
  9713. + `test'
  9714. +      Many interesting `awk' programs, provided as a test suite for
  9715. +      `gawk'.  You can use `make test' from the top level `gawk'
  9716. +      directory to run your version of `gawk' against the test suite.
  9717. +      If `gawk' successfully passes `make test' then you can be
  9718. +      confident of a successful port.
  9719. + 
  9720. + 
  9721. + File: gawk.info,  Node: Unix Installation,  Next: VMS Installation,  Prev: Gawk Distribution,  Up: Installation
  9722. + 
  9723. + Compiling and Installing `gawk' on Unix
  9724. + =======================================
  9725. + 
  9726. +    Often, you can compile and install `gawk' by typing only two
  9727. + commands.  However, if you do not use a supported system, you may need
  9728. + to configure `gawk' for your system yourself.
  9729. + 
  9730. + * Menu:
  9731. + 
  9732. + * Quick Installation::          Compiling `gawk' on a
  9733. +                                 supported Unix version.
  9734. + * Configuration Philosophy::    How it's all supposed to work.
  9735. + * New Configurations::          What to do if there is no supplied
  9736. +                                 configuration for your system.
  9737. + 
  9738. + 
  9739. + File: gawk.info,  Node: Quick Installation,  Next: Configuration Philosophy,  Prev: Unix Installation,  Up: Unix Installation
  9740. + 
  9741. + Compiling `gawk' for a Supported Unix Version
  9742. + ---------------------------------------------
  9743. + 
  9744. +    After you have extracted the `gawk' distribution, `cd' to
  9745. + `gawk-2.15'.  Look in the `config' subdirectory for a file that matches
  9746. + your hardware/software combination.  In general, only the software is
  9747. + relevant; for example `sunos41' is used for SunOS 4.1, on both Sun 3
  9748. + and Sun 4 hardware.
  9749. + 
  9750. +    If you find such a file, run the command:
  9751. + 
  9752. +      # assume you have SunOS 4.1
  9753. +      ./configure sunos41
  9754. + 
  9755. +    This produces a `Makefile' and `config.h' tailored to your system.
  9756. + You may wish to edit the `Makefile' to use a different C compiler, such
  9757. + as `gcc', the GNU C compiler, if you have it.  You may also wish to
  9758. + change the `CFLAGS' variable, which controls the command line options
  9759. + that are passed to the C compiler (such as optimization levels, or
  9760. + compiling for debugging).
  9761. + 
  9762. +    After you have configured `Makefile' and `config.h', type:
  9763. + 
  9764. +      make
  9765. + 
  9766. + and shortly thereafter, you should have an executable version of `gawk'.
  9767. + That's all there is to it!
  9768. + 
  9769. + 
  9770. + File: gawk.info,  Node: Configuration Philosophy,  Next: New Configurations,  Prev: Quick Installation,  Up: Unix Installation
  9771. + 
  9772. + The Configuration Process
  9773. + -------------------------
  9774. + 
  9775. +    (This section is of interest only if you know something about using
  9776. + the C language and the Unix operating system.)
  9777. + 
  9778. +    The source code for `gawk' generally attempts to adhere to industry
  9779. + standards wherever possible.  This means that `gawk' uses library
  9780. + routines that are specified by the ANSI C standard and by the POSIX
  9781. + operating system interface standard.  When using an ANSI C compiler,
  9782. + function prototypes are provided to help improve the compile-time
  9783. + checking.
  9784. + 
  9785. +    Many older Unix systems do not support all of either the ANSI or the
  9786. + POSIX standards.  The `missing' subdirectory in the `gawk' distribution
  9787. + contains replacement versions of those subroutines that are most likely
  9788. + to be missing.
  9789. + 
  9790. +    The `config.h' file that is created by the `configure' program
  9791. + contains definitions that describe features of the particular operating
  9792. + system where you are attempting to compile `gawk'.  For the most part,
  9793. + it lists which standard subroutines are *not* available.  For example,
  9794. + if your system lacks the `getopt' routine, then `GETOPT_MISSING' would
  9795. + be defined.
  9796. + 
  9797. +    `config.h' also defines constants that describe facts about your
  9798. + variant of Unix.  For example, there may not be an `st_blksize' element
  9799. + in the `stat' structure.  In this case `BLKSIZE_MISSING' would be
  9800. + defined.
  9801. + 
  9802. +    Based on the list in `config.h' of standard subroutines that are
  9803. + missing, `missing.c' will do a `#include' of the appropriate file(s)
  9804. + from the `missing' subdirectory.
  9805. + 
  9806. +    Conditionally compiled code in the other source files relies on the
  9807. + other definitions in the `config.h' file.
  9808. + 
  9809. +    Besides creating `config.h', `configure' produces a `Makefile' from
  9810. + `Makefile.in'.  There are a number of lines in `Makefile.in' that are
  9811. + system or feature specific.  For example, there is line that begins
  9812. + with `##MAKE_ALLOCA_C##'.  This is normally a comment line, since it
  9813. + starts with `#'.  If a configuration file has `MAKE_ALLOCA_C' in it,
  9814. + then `configure' will delete the `##MAKE_ALLOCA_C##' from the beginning
  9815. + of the line.  This will enable the rules in the `Makefile' that use a C
  9816. + version of `alloca'.  There are several similar features that work in
  9817. + this fashion.
  9818. + 
  9819. + 
  9820. + File: gawk.info,  Node: New Configurations,  Prev: Configuration Philosophy,  Up: Unix Installation
  9821. + 
  9822. + Configuring `gawk' for a New System
  9823. + -----------------------------------
  9824. + 
  9825. +    (This section is of interest only if you know something about using
  9826. + the C language and the Unix operating system, and if you have to install
  9827. + `gawk' on a system that is not supported by the `gawk' distribution.
  9828. + If you are a C or Unix novice, get help from a local expert.)
  9829. + 
  9830. +    If you need to configure `gawk' for a Unix system that is not
  9831. + supported in the distribution, first see *Note The Configuration
  9832. + Process: Configuration Philosophy.  Then, copy `config.in' to
  9833. + `config.h', and copy `Makefile.in' to `Makefile'.
  9834. + 
  9835. +    Next, edit both files.  Both files are liberally commented, and the
  9836. + necessary changes should be straightforward.
  9837. + 
  9838. +    While editing `config.h', you need to determine what library
  9839. + routines you do or do not have by consulting your system documentation,
  9840. + or by perusing your actual libraries using the `ar' or `nm' utilities.
  9841. + In the worst case, simply do not define *any* of the macros for missing
  9842. + subroutines.  When you compile `gawk', the final link-editing step will
  9843. + fail.  The link editor will provide you with a list of unresolved
  9844. + external references--these are the missing subroutines.  Edit
  9845. + `config.h' again and recompile, and you should be set.
  9846. + 
  9847. +    Editing the `Makefile' should also be straightforward.  Enable or
  9848. + disable the lines that begin with `##MAKE_WHATEVER##', as appropriate.
  9849. + Select the correct C compiler and `CFLAGS' for it.  Then run `make'.
  9850. + 
  9851. +    Getting a correct configuration is likely to be an iterative process.
  9852. + Do not be discouraged if it takes you several tries.  If you have no
  9853. + luck whatsoever, please report your system type, and the steps you took.
  9854. + Once you do have a working configuration, please send it to the
  9855. + maintainers so that support for your system can be added to the
  9856. + official release.
  9857. + 
  9858. +    *Note Reporting Problems and Bugs: Bugs, for information on how to
  9859. + report problems in configuring `gawk'.  You may also use the same
  9860. + mechanisms for sending in new configurations.
  9861. + 
  9862. + 
  9863. + File: gawk.info,  Node: VMS Installation,  Next: MS-DOS Installation,  Prev: Unix Installation,  Up: Installation
  9864. + 
  9865. + Compiling, Installing, and Running `gawk' on VMS
  9866. + ================================================
  9867. + 
  9868. +    This section describes how to compile and install `gawk' under VMS.
  9869. + 
  9870. + * Menu:
  9871. + 
  9872. + * VMS Compilation::             How to compile `gawk' under VMS.
  9873. + * VMS Installation Details::    How to install `gawk' under VMS.
  9874. + * VMS Running::                 How to run `gawk' under VMS.
  9875. + * VMS POSIX::                   Alternate instructions for VMS POSIX.
  9876. + 
  9877. + 
  9878. + File: gawk.info,  Node: VMS Compilation,  Next: VMS Installation Details,  Prev: VMS Installation,  Up: VMS Installation
  9879. + 
  9880. + Compiling `gawk' under VMS
  9881. + --------------------------
  9882. + 
  9883. +    To compile `gawk' under VMS, there is a `DCL' command procedure that
  9884. + will issue all the necessary `CC' and `LINK' commands, and there is
  9885. + also a `Makefile' for use with the `MMS' utility.  From the source
  9886. + directory, use either
  9887. + 
  9888. +      $ @[.VMS]VMSBUILD.COM
  9889. + 
  9890. + or
  9891. + 
  9892. +      $ MMS/DESCRIPTION=[.VMS]DECSRIP.MMS GAWK
  9893. + 
  9894. +    Depending upon which C compiler you are using, follow one of the sets
  9895. + of instructions in this table:
  9896. + 
  9897. + VAX C V3.x
  9898. +      Use either `vmsbuild.com' or `descrip.mms' as is.  These use
  9899. +      `CC/OPTIMIZE=NOLINE', which is essential for Version 3.0.
  9900. + 
  9901. + VAX C V2.x
  9902. +      You must have Version 2.3 or 2.4; older ones won't work.  Edit
  9903. +      either `vmsbuild.com' or `descrip.mms' according to the comments
  9904. +      in them.  For `vmsbuild.com', this just entails removing two `!'
  9905. +      delimiters.  Also edit `config.h' (which is a copy of file
  9906. +      `[.config]vms-conf.h') and comment out or delete the two lines
  9907. +      `#define __STDC__ 0' and `#define VAXC_BUILTINS' near the end.
  9908. + 
  9909. + GNU C
  9910. +      Edit `vmsbuild.com' or `descrip.mms'; the changes are different
  9911. +      from those for VAX C V2.x, but equally straightforward.  No
  9912. +      changes to `config.h' should be needed.
  9913. + 
  9914. + DEC C
  9915. +      Edit `vmsbuild.com' or `descrip.mms' according to their comments.
  9916. +      No changes to `config.h' should be needed.
  9917. + 
  9918. +    `gawk' 2.15 has been tested under VAX/VMS 5.5-1 using VAX C V3.2,
  9919. + GNU C 1.40 and 2.3.  It should work without modifications for VMS V4.6
  9920. + and up.
  9921. + 
  9922. + 
  9923. + File: gawk.info,  Node: VMS Installation Details,  Next: VMS Running,  Prev: VMS Compilation,  Up: VMS Installation
  9924. + 
  9925. + Installing `gawk' on VMS
  9926. + ------------------------
  9927. + 
  9928. +    To install `gawk', all you need is a "foreign" command, which is a
  9929. + `DCL' symbol whose value begins with a dollar sign.
  9930. + 
  9931. +      $ GAWK :== $device:[directory]GAWK
  9932. + 
  9933. + (Substitute the actual location of `gawk.exe' for
  9934. + `device:[directory]'.) The symbol should be placed in the `login.com'
  9935. + of any user who wishes to run `gawk', so that it will be defined every
  9936. + time the user logs on.  Alternatively, the symbol may be placed in the
  9937. + system-wide `sylogin.com' procedure, which will allow all users to run
  9938. + `gawk'.
  9939. + 
  9940. +    Optionally, the help entry can be loaded into a VMS help library:
  9941. + 
  9942. +      $ LIBRARY/HELP SYS$HELP:HELPLIB [.VMS]GAWK.HLP
  9943. + 
  9944. + (You may want to substitute a site-specific help library rather than
  9945. + the standard VMS library `HELPLIB'.)  After loading the help text,
  9946. + 
  9947. +      $ HELP GAWK
  9948. + 
  9949. + will provide information about both the `gawk' implementation and the
  9950. + `awk' programming language.
  9951. + 
  9952. +    The logical name `AWK_LIBRARY' can designate a default location for
  9953. + `awk' program files.  For the `-f' option, if the specified filename
  9954. + has no device or directory path information in it, `gawk' will look in
  9955. + the current directory first, then in the directory specified by the
  9956. + translation of `AWK_LIBRARY' if the file was not found.  If after
  9957. + searching in both directories, the file still is not found, then `gawk'
  9958. + appends the suffix `.awk' to the filename and the file search will be
  9959. + re-tried.  If `AWK_LIBRARY' is not defined, that portion of the file
  9960. + search will fail benignly.
  9961. + 
  9962. + 
  9963. + File: gawk.info,  Node: VMS Running,  Next: VMS POSIX,  Prev: VMS Installation Details,  Up: VMS Installation
  9964. + 
  9965. + Running `gawk' on VMS
  9966. + ---------------------
  9967. + 
  9968. +    Command line parsing and quoting conventions are significantly
  9969. + different on VMS, so examples in this manual or from other sources
  9970. + often need minor changes.  They *are* minor though, and all `awk'
  9971. + programs should run correctly.
  9972. + 
  9973. +    Here are a couple of trivial tests:
  9974. + 
  9975. +      $ gawk -- "BEGIN {print ""Hello, World!""}"
  9976. +      $ gawk -"W" version     ! could also be -"W version" or "-W version"
  9977. + 
  9978. + Note that upper-case and mixed-case text must be quoted.
  9979. + 
  9980. +    The VMS port of `gawk' includes a `DCL'-style interface in addition
  9981. + to the original shell-style interface (see the help entry for details).
  9982. + One side-effect of dual command line parsing is that if there is only a
  9983. + single parameter (as in the quoted string program above), the command
  9984. + becomes ambiguous.  To work around this, the normally optional `--'
  9985. + flag is required to force Unix style rather than `DCL' parsing.  If any
  9986. + other dash-type options (or multiple parameters such as data files to be
  9987. + processed) are present, there is no ambiguity and `--' can be omitted.
  9988. + 
  9989. +    The default search path when looking for `awk' program files
  9990. + specified by the `-f' option is `"SYS$DISK:[],AWK_LIBRARY:"'.  The
  9991. + logical name `AWKPATH' can be used to override this default.  The format
  9992. + of `AWKPATH' is a comma-separated list of directory specifications.
  9993. + When defining it, the value should be quoted so that it retains a single
  9994. + translation, and not a multi-translation `RMS' searchlist.
  9995. + 
  9996. + 
  9997. + File: gawk.info,  Node: VMS POSIX,  Prev: VMS Running,  Up: VMS Installation
  9998. + 
  9999. + Building and using `gawk' under VMS POSIX
  10000. + -----------------------------------------
  10001. + 
  10002. +    Ignore the instructions above, although `vms/gawk.hlp' should still
  10003. + be made available in a help library.  Make sure that the two scripts,
  10004. + `configure' and `mungeconf', are executable; use `chmod +x' on them if
  10005. + necessary.  Then execute the following commands:
  10006. + 
  10007. +      $ POSIX
  10008. +      psx> configure vms-posix
  10009. +      psx> make awktab.c gawk
  10010. + 
  10011. + The first command will construct files `config.h' and `Makefile' out of
  10012. + templates.  The second command will compile and link `gawk'.  Due to a
  10013. + `make' bug in VMS POSIX V1.0 and V1.1, the file `awktab.c' must be
  10014. + given as an explicit target or it will not be built and the final link
  10015. + step will fail.  Ignore the warning `"Could not find lib m in lib
  10016. + list"'; it is harmless, caused by the explicit use of `-lm' as a linker
  10017. + option which is not needed under VMS POSIX.  Under V1.1 (but not V1.0)
  10018. + a problem with the `yacc' skeleton `/etc/yyparse.c' will cause a
  10019. + compiler warning for `awktab.c', followed by a linker warning about
  10020. + compilation warnings in the resulting object module.  These warnings
  10021. + can be ignored.
  10022. + 
  10023. +    Once built, `gawk' will work like any other shell utility.  Unlike
  10024. + the normal VMS port of `gawk', no special command line manipulation is
  10025. + needed in the VMS POSIX environment.
  10026. + 
  10027. + 
  10028. + File: gawk.info,  Node: MS-DOS Installation,  Next: Atari Installation,  Prev: VMS Installation,  Up: Installation
  10029. + 
  10030. + Installing `gawk' on MS-DOS
  10031. + ===========================
  10032. + 
  10033. +    The first step is to get all the files in the `gawk' distribution
  10034. + onto your PC.  Move all the files from the `pc' directory into the main
  10035. + directory where the other files are.  Edit the file `make.bat' so that
  10036. + it will be an acceptable MS-DOS batch file.  This means making sure
  10037. + that all lines are terminated with the ASCII carriage return and line
  10038. + feed characters.  restrictions.
  10039. + 
  10040. +    `gawk' has only been compiled with version 5.1 of the Microsoft C
  10041. + compiler.  The file `make.bat' from the `pc' directory assumes that you
  10042. + have this compiler.
  10043. + 
  10044. +    Copy the file `setargv.obj' from the library directory where it
  10045. + resides to the `gawk' source code directory.
  10046. + 
  10047. +    Run `make.bat'.  This will compile `gawk' for you, and link it.
  10048. + That's all there is to it!
  10049. + 
  10050. + 
  10051. + File: gawk.info,  Node: Atari Installation,  Prev: MS-DOS Installation,  Up: Installation
  10052. + 
  10053. + Installing `gawk' on the Atari ST
  10054. + =================================
  10055. + 
  10056. +    This section assumes that you are running TOS.  It applies to other
  10057. + Atari models (STe, TT) as well.
  10058. + 
  10059. +    In order to use `gawk', you need to have a shell, either text or
  10060. + graphics, that does not map all the characters of a command line to
  10061. + upper case.  Maintaining case distinction in option flags is very
  10062. + important (*note Invoking `awk': Command Line.).  Popular shells like
  10063. + `gulam' or `gemini' will work, as will newer versions of `desktop'.
  10064. + Support for I/O redirection is necessary to make it easy to import
  10065. + `awk' programs from other environments.  Pipes are nice to have, but
  10066. + not vital.
  10067. + 
  10068. +    If you have received an executable version of `gawk', place it, as
  10069. + usual, anywhere in your `PATH' where your shell will find it.
  10070. + 
  10071. +    While executing, `gawk' creates a number of temporary files.  `gawk'
  10072. + looks for either of the environment variables `TEMP' or `TMPDIR', in
  10073. + that order.  If either one is found, its value is assumed to be a
  10074. + directory for temporary files.  This directory must exist, and if you
  10075. + can spare the memory, it is a good idea to put it on a RAM drive.  If
  10076. + neither `TEMP' nor `TMPDIR' are found, then `gawk' uses the current
  10077. + directory for its temporary files.
  10078. + 
  10079. +    The ST version of `gawk' searches for its program files as described
  10080. + in *Note The `AWKPATH' Environment Variable: AWKPATH Variable.  On the
  10081. + ST, the default value for the `AWKPATH' variable is
  10082. + `".,c:\lib\awk,c:\gnu\lib\awk"'.  The search path can be modified by
  10083. + explicitly setting `AWKPATH' to whatever you wish.  Note that colons
  10084. + cannot be used on the ST to separate elements in the `AWKPATH'
  10085. + variable, since they have another, reserved, meaning.  Instead, you
  10086. + must use a comma to separate elements in the path.  If you are
  10087. + recompiling `gawk' on the ST, then you can choose a new default search
  10088. + path, by setting the value of `DEFPATH' in the file `...\config\atari'.
  10089. + You may choose a different separator character by setting the value of
  10090. + `ENVSEP' in the same file.  The new values will be used when creating
  10091. + the header file `config.h'.
  10092. + 
  10093. +    Although `awk' allows great flexibility in doing I/O redirections
  10094. + from within a program, this facility should be used with care on the ST.
  10095. + In some circumstances the OS routines for file handle pool processing
  10096. + lose track of certain events, causing the computer to crash, and
  10097. + requiring a reboot.  Often a warm reboot is sufficient.  Fortunately,
  10098. + this happens infrequently, and in rather esoteric situations.  In
  10099. + particular, avoid having one part of an `awk' program using `print'
  10100. + statements explicitly redirected to `"/dev/stdout"', while other
  10101. + `print' statements use the default standard output, and a calling shell
  10102. + has redirected standard output to a file.
  10103. + 
  10104. +    When `gawk' is compiled with the ST version of `gcc' and its usual
  10105. + libraries, it will accept both `/' and `\' as path separators.  While
  10106. + this is convenient, it should be remembered that this removes one,
  10107. + technically legal, character (`/') from your file names, and that it
  10108. + may create problems for external programs, called via the `system()'
  10109. + function, which may not support this convention.  Whenever it is
  10110. + possible that a file created by `gawk' will be used by some other
  10111. + program, use only backslashes.  Also remember that in `awk',
  10112. + backslashes in strings have to be doubled in order to get literal
  10113. + backslashes.
  10114. + 
  10115. +    The initial port of `gawk' to the ST was done with `gcc'.  If you
  10116. + wish to recompile `gawk' from scratch, you will need to use a compiler
  10117. + that accepts ANSI standard C (such as `gcc', Turbo C, or Prospero C).
  10118. + If `sizeof(int) != sizeof(int *)', the correctness of the generated
  10119. + code depends heavily on the fact that all function calls have function
  10120. + prototypes in the current scope.  If your compiler does not accept
  10121. + function prototypes, you will probably have to add a number of casts to
  10122. + the code.
  10123. + 
  10124. +    If you are using `gcc', make sure that you have up-to-date libraries.
  10125. + Older versions have problems with some library functions (`atan2()',
  10126. + `strftime()', the `%g' conversion in `sprintf()') which may affect the
  10127. + operation of `gawk'.
  10128. + 
  10129. +    In the `atari' subdirectory of the `gawk' distribution is a version
  10130. + of the `system()' function that has been tested with `gulam' and `msh';
  10131. + it should work with other shells as well.  With `gulam', it passes the
  10132. + string to be executed without spawning an extra copy of a shell.  It is
  10133. + possible to replace this version of `system()' with a similar function
  10134. + from a library or from some other source if that version would be a
  10135. + better choice for the shell you prefer.
  10136. + 
  10137. +    The files needed to recompile `gawk' on the ST can be found in the
  10138. + `atari' directory.  The provided files and instructions below assume
  10139. + that you have the GNU C compiler (`gcc'), the `gulam' shell, and an ST
  10140. + version of `sed'. The `Makefile' is set up to use `byacc' as a `yacc'
  10141. + replacement.  With a different set of tools some adjustments and/or
  10142. + editing will be needed.
  10143. + 
  10144. +    `cd' to the `atari' directory.  Copy `Makefile.st' to `makefile' in
  10145. + the source (parent) directory.  Possibly adjust `../config/atari' to
  10146. + suit your system.  Execute the script `mkconf.g' which will create the
  10147. + header file `../config.h'.  Go back to the source directory.  If you
  10148. + are not using `gcc', check the file `missing.c'.  It may be necessary
  10149. + to change forward slashes in the references to files from the `atari'
  10150. + subdirectory into backslashes.  Type `make' and enjoy.
  10151. + 
  10152. +    Compilation with `gcc' of some of the bigger modules, like
  10153. + `awk_tab.c', may require a full four megabytes of memory.  On smaller
  10154. + machines you would need to cut down on optimizations, or you would have
  10155. + to switch to another, less memory hungry, compiler.
  10156. + 
  10157. + 
  10158. + File: gawk.info,  Node: Gawk Summary,  Next: Sample Program,  Prev: Installation,  Up: Top
  10159. + 
  10160. + `gawk' Summary
  10161. + **************
  10162. + 
  10163. +    This appendix provides a brief summary of the `gawk' command line
  10164. + and the `awk' language.  It is designed to serve as "quick reference."
  10165. + It is therefore terse, but complete.
  10166. + 
  10167. + * Menu:
  10168. + 
  10169. + * Command Line Summary::        Recapitulation of the command line.
  10170. + * Language Summary::            A terse review of the language.
  10171. + * Variables/Fields::            Variables, fields, and arrays.
  10172. + * Rules Summary::               Patterns and Actions, and their
  10173. +                                 component parts.
  10174. + * Functions Summary::           Defining and calling functions.
  10175. + * Historical Features::         Some undocumented but supported "features".
  10176. + 
  10177. + 
  10178. + File: gawk.info,  Node: Command Line Summary,  Next: Language Summary,  Prev: Gawk Summary,  Up: Gawk Summary
  10179. + 
  10180. + Command Line Options Summary
  10181. + ============================
  10182. + 
  10183. +    The command line consists of options to `gawk' itself, the `awk'
  10184. + program text (if not supplied via the `-f' option), and values to be
  10185. + made available in the `ARGC' and `ARGV' predefined `awk' variables:
  10186. + 
  10187. +      awk [POSIX OR GNU STYLE OPTIONS] -f source-file [`--'] FILE ...
  10188. +      awk [POSIX OR GNU STYLE OPTIONS] [`--'] 'PROGRAM' FILE ...
  10189. + 
  10190. +    The options that `gawk' accepts are:
  10191. + 
  10192. + `-F FS'
  10193. + `--field-separator=FS'
  10194. +      Use FS for the input field separator (the value of the `FS'
  10195. +      predefined variable).
  10196. + 
  10197. + `-f PROGRAM-FILE'
  10198. + `--file=PROGRAM-FILE'
  10199. +      Read the `awk' program source from the file PROGRAM-FILE, instead
  10200. +      of from the first command line argument.
  10201. + 
  10202. + `-v VAR=VAL'
  10203. + `--assign=VAR=VAL'
  10204. +      Assign the variable VAR the value VAL before program execution
  10205. +      begins.
  10206. + 
  10207. + `-W compat'
  10208. + `--compat'
  10209. +      Specifies compatibility mode, in which `gawk' extensions are turned
  10210. +      off.
  10211. + 
  10212. + `-W copyleft'
  10213. + `-W copyright'
  10214. + `--copyleft'
  10215. + `--copyright'
  10216. +      Print the short version of the General Public License on the error
  10217. +      output.  This option may disappear in a future version of `gawk'.
  10218. + 
  10219. + `-W help'
  10220. + `-W usage'
  10221. + `--help'
  10222. + `--usage'
  10223. +      Print a relatively short summary of the available options on the
  10224. +      error output.
  10225. + 
  10226. + `-W lint'
  10227. + `--lint'
  10228. +      Give warnings about dubious or non-portable `awk' constructs.
  10229. + 
  10230. + `-W posix'
  10231. + `--posix'
  10232. +      Specifies POSIX compatibility mode, in which `gawk' extensions are
  10233. +      turned off and additional restrictions apply.
  10234. + 
  10235. + `-W source=PROGRAM-TEXT'
  10236. + `--source=PROGRAM-TEXT'
  10237. +      Use PROGRAM-TEXT as `awk' program source code.  This option allows
  10238. +      mixing command line source code with source code from files, and is
  10239. +      particularly useful for mixing command line programs with library
  10240. +      functions.
  10241. + 
  10242. + `-W version'
  10243. + `--version'
  10244. +      Print version information for this particular copy of `gawk' on
  10245. +      the error output.  This option may disappear in a future version
  10246. +      of `gawk'.
  10247. + 
  10248. + `--'
  10249. +      Signal the end of options.  This is useful to allow further
  10250. +      arguments to the `awk' program itself to start with a `-'.  This
  10251. +      is mainly for consistency with the argument parsing conventions of
  10252. +      POSIX.
  10253. + 
  10254. +    Any other options are flagged as invalid, but are otherwise ignored.
  10255. + *Note Invoking `awk': Command Line, for more details.
  10256. + 
  10257. + 
  10258. + File: gawk.info,  Node: Language Summary,  Next: Variables/Fields,  Prev: Command Line Summary,  Up: Gawk Summary
  10259. + 
  10260. + Language Summary
  10261. + ================
  10262. + 
  10263. +    An `awk' program consists of a sequence of pattern-action statements
  10264. + and optional function definitions.
  10265. + 
  10266. +      PATTERN    { ACTION STATEMENTS }
  10267. +      
  10268. +      function NAME(PARAMETER LIST)     { ACTION STATEMENTS }
  10269. + 
  10270. +    `gawk' first reads the program source from the PROGRAM-FILE(s) if
  10271. + specified, or from the first non-option argument on the command line.
  10272. + The `-f' option may be used multiple times on the command line.  `gawk'
  10273. + reads the program text from all the PROGRAM-FILE files, effectively
  10274. + concatenating them in the order they are specified.  This is useful for
  10275. + building libraries of `awk' functions, without having to include them
  10276. + in each new `awk' program that uses them.  To use a library function in
  10277. + a file from a program typed in on the command line, specify `-f
  10278. + /dev/tty'; then type your program, and end it with a `Control-d'.
  10279. + *Note Invoking `awk': Command Line.
  10280. + 
  10281. +    The environment variable `AWKPATH' specifies a search path to use
  10282. + when finding source files named with the `-f' option.  The default
  10283. + path, which is `.:/local/lib/awk:/gnu/lib/awk' is used if `AWKPATH' is
  10284. + not set.  If a file name given to the `-f' option contains a `/'
  10285. + character, no path search is performed.  *Note The `AWKPATH'
  10286. + Environment Variable: AWKPATH Variable, for a full description of the
  10287. + `AWKPATH' environment variable.
  10288. + 
  10289. +    `gawk' compiles the program into an internal form, and then proceeds
  10290. + to read each file named in the `ARGV' array.  If there are no files
  10291. + named on the command line, `gawk' reads the standard input.
  10292. + 
  10293. +    If a "file" named on the command line has the form `VAR=VAL', it is
  10294. + treated as a variable assignment: the variable VAR is assigned the
  10295. + value VAL.  If any of the files have a value that is the null string,
  10296. + that element in the list is skipped.
  10297. + 
  10298. +    For each line in the input, `gawk' tests to see if it matches any
  10299. + PATTERN in the `awk' program.  For each pattern that the line matches,
  10300. + the associated ACTION is executed.
  10301. + 
  10302. + 
  10303. + File: gawk.info,  Node: Variables/Fields,  Next: Rules Summary,  Prev: Language Summary,  Up: Gawk Summary
  10304. + 
  10305. + Variables and Fields
  10306. + ====================
  10307. + 
  10308. +    `awk' variables are dynamic; they come into existence when they are
  10309. + first used.  Their values are either floating-point numbers or strings.
  10310. + `awk' also has one-dimension arrays; multiple-dimensional arrays may be
  10311. + simulated.  There are several predefined variables that `awk' sets as a
  10312. + program runs; these are summarized below.
  10313. + 
  10314. + * Menu:
  10315. + 
  10316. + * Fields Summary::              Input field splitting.
  10317. + * Built-in Summary::            `awk''s built-in variables.
  10318. + * Arrays Summary::              Using arrays.
  10319. + * Data Type Summary::           Values in `awk' are numbers or strings.
  10320. + 
  10321. + 
  10322. + File: gawk.info,  Node: Fields Summary,  Next: Built-in Summary,  Prev: Variables/Fields,  Up: Variables/Fields
  10323. + 
  10324. + Fields
  10325. + ------
  10326. + 
  10327. +    As each input line is read, `gawk' splits the line into FIELDS,
  10328. + using the value of the `FS' variable as the field separator.  If `FS'
  10329. + is a single character, fields are separated by that character.
  10330. + Otherwise, `FS' is expected to be a full regular expression.  In the
  10331. + special case that `FS' is a single blank, fields are separated by runs
  10332. + of blanks and/or tabs.  Note that the value of `IGNORECASE' (*note
  10333. + Case-sensitivity in Matching: Case-sensitivity.) also affects how
  10334. + fields are split when `FS' is a regular expression.
  10335. + 
  10336. +    Each field in the input line may be referenced by its position, `$1',
  10337. + `$2', and so on.  `$0' is the whole line.  The value of a field may be
  10338. + assigned to as well.  Field numbers need not be constants:
  10339. + 
  10340. +      n = 5
  10341. +      print $n
  10342. + 
  10343. + prints the fifth field in the input line.  The variable `NF' is set to
  10344. + the total number of fields in the input line.
  10345. + 
  10346. +    References to nonexistent fields (i.e., fields after `$NF') return
  10347. + the null-string.  However, assigning to a nonexistent field (e.g.,
  10348. + `$(NF+2) = 5') increases the value of `NF', creates any intervening
  10349. + fields with the null string as their value, and causes the value of
  10350. + `$0' to be recomputed, with the fields being separated by the value of
  10351. + `OFS'.
  10352. + 
  10353. +    *Note Reading Input Files: Reading Files, for a full description of
  10354. + the way `awk' defines and uses fields.
  10355. + 
  10356. + 
  10357. + File: gawk.info,  Node: Built-in Summary,  Next: Arrays Summary,  Prev: Fields Summary,  Up: Variables/Fields
  10358. + 
  10359. + Built-in Variables
  10360. + ------------------
  10361. + 
  10362. +    `awk''s built-in variables are:
  10363. + 
  10364. + `ARGC'
  10365. +      The number of command line arguments (not including options or the
  10366. +      `awk' program itself).
  10367. + 
  10368. + `ARGIND'
  10369. +      The index in `ARGV' of the current file being processed.  It is
  10370. +      always true that `FILENAME == ARGV[ARGIND]'.
  10371. + 
  10372. + `ARGV'
  10373. +      The array of command line arguments.  The array is indexed from 0
  10374. +      to `ARGC' - 1.  Dynamically changing the contents of `ARGV' can
  10375. +      control the files used for data.
  10376. + 
  10377. + `CONVFMT'
  10378. +      The conversion format to use when converting numbers to strings.
  10379. + 
  10380. + `FIELDWIDTHS'
  10381. +      A space separated list of numbers describing the fixed-width input
  10382. +      data.
  10383. + 
  10384. + `ENVIRON'
  10385. +      An array containing the values of the environment variables.  The
  10386. +      array is indexed by variable name, each element being the value of
  10387. +      that variable.  Thus, the environment variable `HOME' would be in
  10388. +      `ENVIRON["HOME"]'.  Its value might be `/u/close'.
  10389. + 
  10390. +      Changing this array does not affect the environment seen by
  10391. +      programs which `gawk' spawns via redirection or the `system'
  10392. +      function.  (This may change in a future version of `gawk'.)
  10393. + 
  10394. +      Some operating systems do not have environment variables.  The
  10395. +      array `ENVIRON' is empty when running on these systems.
  10396. + 
  10397. + `ERRNO'
  10398. +      The system error message when an error occurs using `getline' or
  10399. +      `close'.
  10400. + 
  10401. + `FILENAME'
  10402. +      The name of the current input file.  If no files are specified on
  10403. +      the command line, the value of `FILENAME' is `-'.
  10404. + 
  10405. + `FNR'
  10406. +      The input record number in the current input file.
  10407. + 
  10408. + `FS'
  10409. +      The input field separator, a blank by default.
  10410. + 
  10411. + `IGNORECASE'
  10412. +      The case-sensitivity flag for regular expression operations.  If
  10413. +      `IGNORECASE' has a nonzero value, then pattern matching in rules,
  10414. +      field splitting with `FS', regular expression matching with `~'
  10415. +      and `!~', and the `gsub', `index', `match', `split' and `sub'
  10416. +      predefined functions all ignore case when doing regular expression
  10417. +      operations.
  10418. + 
  10419. + `NF'
  10420. +      The number of fields in the current input record.
  10421. + 
  10422. + `NR'
  10423. +      The total number of input records seen so far.
  10424. + 
  10425. + `OFMT'
  10426. +      The output format for numbers for the `print' statement, `"%.6g"'
  10427. +      by default.
  10428. + 
  10429. + `OFS'
  10430. +      The output field separator, a blank by default.
  10431. + 
  10432. + `ORS'
  10433. +      The output record separator, by default a newline.
  10434. + 
  10435. + `RS'
  10436. +      The input record separator, by default a newline.  `RS' is
  10437. +      exceptional in that only the first character of its string value
  10438. +      is used for separating records.  If `RS' is set to the null
  10439. +      string, then records are separated by blank lines.  When `RS' is
  10440. +      set to the null string, then the newline character always acts as
  10441. +      a field separator, in addition to whatever value `FS' may have.
  10442. + 
  10443. + `RSTART'
  10444. +      The index of the first character matched by `match'; 0 if no match.
  10445. + 
  10446. + `RLENGTH'
  10447. +      The length of the string matched by `match'; -1 if no match.
  10448. + 
  10449. + `SUBSEP'
  10450. +      The string used to separate multiple subscripts in array elements,
  10451. +      by default `"\034"'.
  10452. + 
  10453. +    *Note Built-in Variables::, for more information.
  10454. + 
  10455. + 
  10456. + File: gawk.info,  Node: Arrays Summary,  Next: Data Type Summary,  Prev: Built-in Summary,  Up: Variables/Fields
  10457. + 
  10458. + Arrays
  10459. + ------
  10460. + 
  10461. +    Arrays are subscripted with an expression between square brackets
  10462. + (`[' and `]').  Array subscripts are *always* strings; numbers are
  10463. + converted to strings as necessary, following the standard conversion
  10464. + rules (*note Conversion of Strings and Numbers: Conversion.).
  10465. + 
  10466. +    If you use multiple expressions separated by commas inside the square
  10467. + brackets, then the array subscript is a string consisting of the
  10468. + concatenation of the individual subscript values, converted to strings,
  10469. + separated by the subscript separator (the value of `SUBSEP').
  10470. + 
  10471. +    The special operator `in' may be used in an `if' or `while'
  10472. + statement to see if an array has an index consisting of a particular
  10473. + value.
  10474. + 
  10475. +      if (val in array)
  10476. +              print array[val]
  10477. + 
  10478. +    If the array has multiple subscripts, use `(i, j, ...) in array' to
  10479. + test for existence of an element.
  10480. + 
  10481. +    The `in' construct may also be used in a `for' loop to iterate over
  10482. + all the elements of an array.  *Note Scanning all Elements of an Array:
  10483. + Scanning an Array.
  10484. + 
  10485. +    An element may be deleted from an array using the `delete' statement.
  10486. + 
  10487. +    *Note Arrays in `awk': Arrays, for more detailed information.
  10488. + 
  10489. + 
  10490. + File: gawk.info,  Node: Data Type Summary,  Prev: Arrays Summary,  Up: Variables/Fields
  10491. + 
  10492. + Data Types
  10493. + ----------
  10494. + 
  10495. +    The value of an `awk' expression is always either a number or a
  10496. + string.
  10497. + 
  10498. +    Certain contexts (such as arithmetic operators) require numeric
  10499. + values.  They convert strings to numbers by interpreting the text of
  10500. + the string as a numeral.  If the string does not look like a numeral,
  10501. + it converts to 0.
  10502. + 
  10503. +    Certain contexts (such as concatenation) require string values.
  10504. + They convert numbers to strings by effectively printing them with
  10505. + `sprintf'.  *Note Conversion of Strings and Numbers: Conversion, for
  10506. + the details.
  10507. + 
  10508. +    To force conversion of a string value to a number, simply add 0 to
  10509. + it.  If the value you start with is already a number, this does not
  10510. + change it.
  10511. + 
  10512. +    To force conversion of a numeric value to a string, concatenate it
  10513. + with the null string.
  10514. + 
  10515. +    The `awk' language defines comparisons as being done numerically if
  10516. + both operands are numeric, or if one is numeric and the other is a
  10517. + numeric string.  Otherwise one or both operands are converted to
  10518. + strings and a string comparison is performed.
  10519. + 
  10520. +    Uninitialized variables have the string value `""' (the null, or
  10521. + empty, string).  In contexts where a number is required, this is
  10522. + equivalent to 0.
  10523. + 
  10524. +    *Note Variables::, for more information on variable naming and
  10525. + initialization; *note Conversion of Strings and Numbers: Conversion.,
  10526. + for more information on how variable values are interpreted.
  10527. + 
  10528. + 
  10529. + File: gawk.info,  Node: Rules Summary,  Next: Functions Summary,  Prev: Variables/Fields,  Up: Gawk Summary
  10530. + 
  10531. + Patterns and Actions
  10532. + ====================
  10533. + 
  10534. + * Menu:
  10535. + 
  10536. + * Pattern Summary::             Quick overview of patterns.
  10537. + * Regexp Summary::              Quick overview of regular expressions.
  10538. + * Actions Summary::             Quick overview of actions.
  10539. + 
  10540. +    An `awk' program is mostly composed of rules, each consisting of a
  10541. + pattern followed by an action.  The action is enclosed in `{' and `}'.
  10542. + Either the pattern may be missing, or the action may be missing, but,
  10543. + of course, not both.  If the pattern is missing, the action is executed
  10544. + for every single line of input.  A missing action is equivalent to this
  10545. + action,
  10546. + 
  10547. +      { print }
  10548. + 
  10549. + which prints the entire line.
  10550. + 
  10551. +    Comments begin with the `#' character, and continue until the end of
  10552. + the line.  Blank lines may be used to separate statements.  Normally, a
  10553. + statement ends with a newline, however, this is not the case for lines
  10554. + ending in a `,', `{', `?', `:', `&&', or `||'.  Lines ending in `do' or
  10555. + `else' also have their statements automatically continued on the
  10556. + following line.  In other cases, a line can be continued by ending it
  10557. + with a `\', in which case the newline is ignored.
  10558. + 
  10559. +    Multiple statements may be put on one line by separating them with a
  10560. + `;'.  This applies to both the statements within the action part of a
  10561. + rule (the usual case), and to the rule statements.
  10562. + 
  10563. +    *Note Comments in `awk' Programs: Comments, for information on
  10564. + `awk''s commenting convention; *note `awk' Statements versus Lines:
  10565. + Statements/Lines., for a description of the line continuation mechanism
  10566. + in `awk'.
  10567. + 
  10568. + 
  10569. + File: gawk.info,  Node: Pattern Summary,  Next: Regexp Summary,  Prev: Rules Summary,  Up: Rules Summary
  10570. + 
  10571. + Patterns
  10572. + --------
  10573. + 
  10574. +    `awk' patterns may be one of the following:
  10575. + 
  10576. +      /REGULAR EXPRESSION/
  10577. +      RELATIONAL EXPRESSION
  10578. +      PATTERN && PATTERN
  10579. +      PATTERN || PATTERN
  10580. +      PATTERN ? PATTERN : PATTERN
  10581. +      (PATTERN)
  10582. +      ! PATTERN
  10583. +      PATTERN1, PATTERN2
  10584. +      BEGIN
  10585. +      END
  10586. + 
  10587. +    `BEGIN' and `END' are two special kinds of patterns that are not
  10588. + tested against the input.  The action parts of all `BEGIN' rules are
  10589. + merged as if all the statements had been written in a single `BEGIN'
  10590. + rule.  They are executed before any of the input is read.  Similarly,
  10591. + all the `END' rules are merged, and executed when all the input is
  10592. + exhausted (or when an `exit' statement is executed).  `BEGIN' and `END'
  10593. + patterns cannot be combined with other patterns in pattern expressions.
  10594. + `BEGIN' and `END' rules cannot have missing action parts.
  10595. + 
  10596. +    For `/REGULAR-EXPRESSION/' patterns, the associated statement is
  10597. + executed for each input line that matches the regular expression.
  10598. + Regular expressions are extensions of those in `egrep', and are
  10599. + summarized below.
  10600. + 
  10601. +    A RELATIONAL EXPRESSION may use any of the operators defined below in
  10602. + the section on actions.  These generally test whether certain fields
  10603. + match certain regular expressions.
  10604. + 
  10605. +    The `&&', `||', and `!' operators are logical "and," logical "or,"
  10606. + and logical "not," respectively, as in C.  They do short-circuit
  10607. + evaluation, also as in C, and are used for combining more primitive
  10608. + pattern expressions.  As in most languages, parentheses may be used to
  10609. + change the order of evaluation.
  10610. + 
  10611. +    The `?:' operator is like the same operator in C.  If the first
  10612. + pattern matches, then the second pattern is matched against the input
  10613. + record; otherwise, the third is matched.  Only one of the second and
  10614. + third patterns is matched.
  10615. + 
  10616. +    The `PATTERN1, PATTERN2' form of a pattern is called a range
  10617. + pattern.  It matches all input lines starting with a line that matches
  10618. + PATTERN1, and continuing until a line that matches PATTERN2, inclusive.
  10619. + A range pattern cannot be used as an operand to any of the pattern
  10620. + operators.
  10621. + 
  10622. +    *Note Patterns::, for a full description of the pattern part of `awk'
  10623. + rules.
  10624. + 
  10625. diff -rc --new-file /src/baseline/gawk-2.15.5/gawk.info-8 gawk-2.15.5/gawk.info-8
  10626. *** /src/baseline/gawk-2.15.5/gawk.info-8    Thu Jan  1 00:00:00 1970
  10627. --- gawk-2.15.5/gawk.info-8    Sun Jun 12 22:28:55 1994
  10628. ***************
  10629. *** 0 ****
  10630. --- 1,1173 ----
  10631. + This is Info file gawk.info, produced by Makeinfo-1.55 from the input
  10632. + file /gnu/src/amiga/gawk-2.15.5/gawk.texi.
  10633. + 
  10634. +    This file documents `awk', a program that you can use to select
  10635. + particular records in a file and perform operations upon them.
  10636. + 
  10637. +    This is Edition 0.15 of `The GAWK Manual',
  10638. + for the 2.15 version of the GNU implementation
  10639. + of AWK.
  10640. + 
  10641. +    Copyright (C) 1989, 1991, 1992, 1993 Free Software Foundation, Inc.
  10642. + 
  10643. +    Permission is granted to make and distribute verbatim copies of this
  10644. + manual provided the copyright notice and this permission notice are
  10645. + preserved on all copies.
  10646. + 
  10647. +    Permission is granted to copy and distribute modified versions of
  10648. + this manual under the conditions for verbatim copying, provided that
  10649. + the entire resulting derived work is distributed under the terms of a
  10650. + permission notice identical to this one.
  10651. + 
  10652. +    Permission is granted to copy and distribute translations of this
  10653. + manual into another language, under the above conditions for modified
  10654. + versions, except that this permission notice may be stated in a
  10655. + translation approved by the Foundation.
  10656. + 
  10657. + 
  10658. + File: gawk.info,  Node: Regexp Summary,  Next: Actions Summary,  Prev: Pattern Summary,  Up: Rules Summary
  10659. + 
  10660. + Regular Expressions
  10661. + -------------------
  10662. + 
  10663. +    Regular expressions are the extended kind found in `egrep'.  They
  10664. + are composed of characters as follows:
  10665. + 
  10666. + `C'
  10667. +      matches the character C (assuming C is a character with no special
  10668. +      meaning in regexps).
  10669. + 
  10670. + `\C'
  10671. +      matches the literal character C.
  10672. + 
  10673. + `.'
  10674. +      matches any character except newline.
  10675. + 
  10676. + `^'
  10677. +      matches the beginning of a line or a string.
  10678. + 
  10679. + `$'
  10680. +      matches the end of a line or a string.
  10681. + 
  10682. + `[ABC...]'
  10683. +      matches any of the characters ABC... (character class).
  10684. + 
  10685. + `[^ABC...]'
  10686. +      matches any character except ABC... and newline (negated character
  10687. +      class).
  10688. + 
  10689. + `R1|R2'
  10690. +      matches either R1 or R2 (alternation).
  10691. + 
  10692. + `R1R2'
  10693. +      matches R1, and then R2 (concatenation).
  10694. + 
  10695. + `R+'
  10696. +      matches one or more R's.
  10697. + 
  10698. + `R*'
  10699. +      matches zero or more R's.
  10700. + 
  10701. + `R?'
  10702. +      matches zero or one R's.
  10703. + 
  10704. + `(R)'
  10705. +      matches R (grouping).
  10706. + 
  10707. +    *Note Regular Expressions as Patterns: Regexp, for a more detailed
  10708. + explanation of regular expressions.
  10709. + 
  10710. +    The escape sequences allowed in string constants are also valid in
  10711. + regular expressions (*note Constant Expressions: Constants.).
  10712. + 
  10713. + 
  10714. + File: gawk.info,  Node: Actions Summary,  Prev: Regexp Summary,  Up: Rules Summary
  10715. + 
  10716. + Actions
  10717. + -------
  10718. + 
  10719. +    Action statements are enclosed in braces, `{' and `}'.  Action
  10720. + statements consist of the usual assignment, conditional, and looping
  10721. + statements found in most languages.  The operators, control statements,
  10722. + and input/output statements available are patterned after those in C.
  10723. + 
  10724. + * Menu:
  10725. + 
  10726. + * Operator Summary::            `awk' operators.
  10727. + * Control Flow Summary::        The control statements.
  10728. + * I/O Summary::                 The I/O statements.
  10729. + * Printf Summary::              A summary of `printf'.
  10730. + * Special File Summary::        Special file names interpreted internally.
  10731. + * Numeric Functions Summary::   Built-in numeric functions.
  10732. + * String Functions Summary::    Built-in string functions.
  10733. + * Time Functions Summary::      Built-in time functions.
  10734. + * String Constants Summary::    Escape sequences in strings.
  10735. + 
  10736. + 
  10737. + File: gawk.info,  Node: Operator Summary,  Next: Control Flow Summary,  Prev: Actions Summary,  Up: Actions Summary
  10738. + 
  10739. + Operators
  10740. + .........
  10741. + 
  10742. +    The operators in `awk', in order of increasing precedence, are:
  10743. + 
  10744. + `= += -= *= /= %= ^='
  10745. +      Assignment.  Both absolute assignment (`VAR=VALUE') and operator
  10746. +      assignment (the other forms) are supported.
  10747. + 
  10748. + `?:'
  10749. +      A conditional expression, as in C.  This has the form `EXPR1 ?
  10750. +      eXPR2 : EXPR3'.  If EXPR1 is true, the value of the expression is
  10751. +      EXPR2; otherwise it is EXPR3.  Only one of EXPR2 and EXPR3 is
  10752. +      evaluated.
  10753. + 
  10754. + `||'
  10755. +      Logical "or".
  10756. + 
  10757. + `&&'
  10758. +      Logical "and".
  10759. + 
  10760. + `~ !~'
  10761. +      Regular expression match, negated match.
  10762. + 
  10763. + `< <= > >= != =='
  10764. +      The usual relational operators.
  10765. + 
  10766. + `BLANK'
  10767. +      String concatenation.
  10768. + 
  10769. + `+ -'
  10770. +      Addition and subtraction.
  10771. + 
  10772. + `* / %'
  10773. +      Multiplication, division, and modulus.
  10774. + 
  10775. + `+ - !'
  10776. +      Unary plus, unary minus, and logical negation.
  10777. + 
  10778. + `^'
  10779. +      Exponentiation (`**' may also be used, and `**=' for the assignment
  10780. +      operator, but they are not specified in the POSIX standard).
  10781. + 
  10782. + `++ --'
  10783. +      Increment and decrement, both prefix and postfix.
  10784. + 
  10785. + `$'
  10786. +      Field reference.
  10787. + 
  10788. +    *Note Expressions as Action Statements: Expressions, for a full
  10789. + description of all the operators listed above.  *Note Examining Fields:
  10790. + Fields, for a description of the field reference operator.
  10791. + 
  10792. + 
  10793. + File: gawk.info,  Node: Control Flow Summary,  Next: I/O Summary,  Prev: Operator Summary,  Up: Actions Summary
  10794. + 
  10795. + Control Statements
  10796. + ..................
  10797. + 
  10798. +    The control statements are as follows:
  10799. + 
  10800. +      if (CONDITION) STATEMENT [ else STATEMENT ]
  10801. +      while (CONDITION) STATEMENT
  10802. +      do STATEMENT while (CONDITION)
  10803. +      for (EXPR1; EXPR2; EXPR3) STATEMENT
  10804. +      for (VAR in ARRAY) STATEMENT
  10805. +      break
  10806. +      continue
  10807. +      delete ARRAY[INDEX]
  10808. +      exit [ EXPRESSION ]
  10809. +      { STATEMENTS }
  10810. + 
  10811. +    *Note Control Statements in Actions: Statements, for a full
  10812. + description of all the control statements listed above.
  10813. + 
  10814. + 
  10815. + File: gawk.info,  Node: I/O Summary,  Next: Printf Summary,  Prev: Control Flow Summary,  Up: Actions Summary
  10816. + 
  10817. + I/O Statements
  10818. + ..............
  10819. + 
  10820. +    The input/output statements are as follows:
  10821. + 
  10822. + `getline'
  10823. +      Set `$0' from next input record; set `NF', `NR', `FNR'.
  10824. + 
  10825. + `getline <FILE'
  10826. +      Set `$0' from next record of FILE; set `NF'.
  10827. + 
  10828. + `getline VAR'
  10829. +      Set VAR from next input record; set `NF', `FNR'.
  10830. + 
  10831. + `getline VAR <FILE'
  10832. +      Set VAR from next record of FILE.
  10833. + 
  10834. + `next'
  10835. +      Stop processing the current input record.  The next input record
  10836. +      is read and processing starts over with the first pattern in the
  10837. +      `awk' program.  If the end of the input data is reached, the `END'
  10838. +      rule(s), if any, are executed.
  10839. + 
  10840. + `next file'
  10841. +      Stop processing the current input file.  The next input record
  10842. +      read comes from the next input file.  `FILENAME' is updated, `FNR'
  10843. +      is set to 1, and processing starts over with the first pattern in
  10844. +      the `awk' program.  If the end of the input data is reached, the
  10845. +      `END' rule(s), if any, are executed.
  10846. + 
  10847. + `print'
  10848. +      Prints the current record.
  10849. + 
  10850. + `print EXPR-LIST'
  10851. +      Prints expressions.
  10852. + 
  10853. + `print EXPR-LIST > FILE'
  10854. +      Prints expressions on FILE.
  10855. + 
  10856. + `printf FMT, EXPR-LIST'
  10857. +      Format and print.
  10858. + 
  10859. + `printf FMT, EXPR-LIST > file'
  10860. +      Format and print on FILE.
  10861. + 
  10862. +    Other input/output redirections are also allowed.  For `print' and
  10863. + `printf', `>> FILE' appends output to the FILE, and `| COMMAND' writes
  10864. + on a pipe.  In a similar fashion, `COMMAND | getline' pipes input into
  10865. + `getline'.  `getline' returns 0 on end of file, and -1 on an error.
  10866. + 
  10867. +    *Note Explicit Input with `getline': Getline, for a full description
  10868. + of the `getline' statement.  *Note Printing Output: Printing, for a
  10869. + full description of `print' and `printf'.  Finally, *note The `next'
  10870. + Statement: Next Statement., for a description of how the `next'
  10871. + statement works.
  10872. + 
  10873. + 
  10874. + File: gawk.info,  Node: Printf Summary,  Next: Special File Summary,  Prev: I/O Summary,  Up: Actions Summary
  10875. + 
  10876. + `printf' Summary
  10877. + ................
  10878. + 
  10879. +    The `awk' `printf' statement and `sprintf' function accept the
  10880. + following conversion specification formats:
  10881. + 
  10882. + `%c'
  10883. +      An ASCII character.  If the argument used for `%c' is numeric, it
  10884. +      is treated as a character and printed.  Otherwise, the argument is
  10885. +      assumed to be a string, and the only first character of that
  10886. +      string is printed.
  10887. + 
  10888. + `%d'
  10889. + `%i'
  10890. +      A decimal number (the integer part).
  10891. + 
  10892. + `%e'
  10893. +      A floating point number of the form `[-]d.ddddddE[+-]dd'.
  10894. + 
  10895. + `%f'
  10896. +      A floating point number of the form [`-']`ddd.dddddd'.
  10897. + 
  10898. + `%g'
  10899. +      Use `%e' or `%f' conversion, whichever produces a shorter string,
  10900. +      with nonsignificant zeros suppressed.
  10901. + 
  10902. + `%o'
  10903. +      An unsigned octal number (again, an integer).
  10904. + 
  10905. + `%s'
  10906. +      A character string.
  10907. + 
  10908. + `%x'
  10909. +      An unsigned hexadecimal number (an integer).
  10910. + 
  10911. + `%X'
  10912. +      Like `%x', except use `A' through `F' instead of `a' through `f'
  10913. +      for decimal 10 through 15.
  10914. + 
  10915. + `%%'
  10916. +      A single `%' character; no argument is converted.
  10917. + 
  10918. +    There are optional, additional parameters that may lie between the
  10919. + `%' and the control letter:
  10920. + 
  10921. + `-'
  10922. +      The expression should be left-justified within its field.
  10923. + 
  10924. + `WIDTH'
  10925. +      The field should be padded to this width.  If WIDTH has a leading
  10926. +      zero, then the field is padded with zeros.  Otherwise it is padded
  10927. +      with blanks.
  10928. + 
  10929. + `.PREC'
  10930. +      A number indicating the maximum width of strings or digits to the
  10931. +      right of the decimal point.
  10932. + 
  10933. +    Either or both of the WIDTH and PREC values may be specified as `*'.
  10934. + In that case, the particular value is taken from the argument list.
  10935. + 
  10936. +    *Note Using `printf' Statements for Fancier Printing: Printf, for
  10937. + examples and for a more detailed description.
  10938. + 
  10939. + 
  10940. + File: gawk.info,  Node: Special File Summary,  Next: Numeric Functions Summary,  Prev: Printf Summary,  Up: Actions Summary
  10941. + 
  10942. + Special File Names
  10943. + ..................
  10944. + 
  10945. +    When doing I/O redirection from either `print' or `printf' into a
  10946. + file, or via `getline' from a file, `gawk' recognizes certain special
  10947. + file names internally.  These file names allow access to open file
  10948. + descriptors inherited from `gawk''s parent process (usually the shell).
  10949. + The file names are:
  10950. + 
  10951. + `/dev/stdin'
  10952. +      The standard input.
  10953. + 
  10954. + `/dev/stdout'
  10955. +      The standard output.
  10956. + 
  10957. + `/dev/stderr'
  10958. +      The standard error output.
  10959. + 
  10960. + `/dev/fd/N'
  10961. +      The file denoted by the open file descriptor N.
  10962. + 
  10963. +    In addition the following files provide process related information
  10964. + about the running `gawk' program.
  10965. + 
  10966. + `/dev/pid'
  10967. +      Reading this file returns the process ID of the current process,
  10968. +      in decimal, terminated with a newline.
  10969. + 
  10970. + `/dev/ppid'
  10971. +      Reading this file returns the parent process ID of the current
  10972. +      process, in decimal, terminated with a newline.
  10973. + 
  10974. + `/dev/pgrpid'
  10975. +      Reading this file returns the process group ID of the current
  10976. +      process, in decimal, terminated with a newline.
  10977. + 
  10978. + `/dev/user'
  10979. +      Reading this file returns a single record terminated with a
  10980. +      newline.  The fields are separated with blanks.  The fields
  10981. +      represent the following information:
  10982. + 
  10983. +     `$1'
  10984. +           The value of the `getuid' system call.
  10985. + 
  10986. +     `$2'
  10987. +           The value of the `geteuid' system call.
  10988. + 
  10989. +     `$3'
  10990. +           The value of the `getgid' system call.
  10991. + 
  10992. +     `$4'
  10993. +           The value of the `getegid' system call.
  10994. + 
  10995. +      If there are any additional fields, they are the group IDs
  10996. +      returned by `getgroups' system call.  (Multiple groups may not be
  10997. +      supported on all systems.)
  10998. + 
  10999. + These file names may also be used on the command line to name data
  11000. + files.  These file names are only recognized internally if you do not
  11001. + actually have files by these names on your system.
  11002. + 
  11003. +    *Note Standard I/O Streams: Special Files, for a longer description
  11004. + that provides the motivation for this feature.
  11005. + 
  11006. + 
  11007. + File: gawk.info,  Node: Numeric Functions Summary,  Next: String Functions Summary,  Prev: Special File Summary,  Up: Actions Summary
  11008. + 
  11009. + Numeric Functions
  11010. + .................
  11011. + 
  11012. +    `awk' has the following predefined arithmetic functions:
  11013. + 
  11014. + `atan2(Y, X)'
  11015. +      returns the arctangent of Y/X in radians.
  11016. + 
  11017. + `cos(EXPR)'
  11018. +      returns the cosine in radians.
  11019. + 
  11020. + `exp(EXPR)'
  11021. +      the exponential function.
  11022. + 
  11023. + `int(EXPR)'
  11024. +      truncates to integer.
  11025. + 
  11026. + `log(EXPR)'
  11027. +      the natural logarithm function.
  11028. + 
  11029. + `rand()'
  11030. +      returns a random number between 0 and 1.
  11031. + 
  11032. + `sin(EXPR)'
  11033. +      returns the sine in radians.
  11034. + 
  11035. + `sqrt(EXPR)'
  11036. +      the square root function.
  11037. + 
  11038. + `srand(EXPR)'
  11039. +      use EXPR as a new seed for the random number generator.  If no EXPR
  11040. +      is provided, the time of day is used.  The return value is the
  11041. +      previous seed for the random number generator.
  11042. + 
  11043. + 
  11044. + File: gawk.info,  Node: String Functions Summary,  Next: Time Functions Summary,  Prev: Numeric Functions Summary,  Up: Actions Summary
  11045. + 
  11046. + String Functions
  11047. + ................
  11048. + 
  11049. +    `awk' has the following predefined string functions:
  11050. + 
  11051. + `gsub(R, S, T)'
  11052. +      for each substring matching the regular expression R in the string
  11053. +      T, substitute the string S, and return the number of substitutions.
  11054. +      If T is not supplied, use `$0'.
  11055. + 
  11056. + `index(S, T)'
  11057. +      returns the index of the string T in the string S, or 0 if T is
  11058. +      not present.
  11059. + 
  11060. + `length(S)'
  11061. +      returns the length of the string S.  The length of `$0' is
  11062. +      returned if no argument is supplied.
  11063. + 
  11064. + `match(S, R)'
  11065. +      returns the position in S where the regular expression R occurs,
  11066. +      or 0 if R is not present, and sets the values of `RSTART' and
  11067. +      `RLENGTH'.
  11068. + 
  11069. + `split(S, A, R)'
  11070. +      splits the string S into the array A on the regular expression R,
  11071. +      and returns the number of fields.  If R is omitted, `FS' is used
  11072. +      instead.
  11073. + 
  11074. + `sprintf(FMT, EXPR-LIST)'
  11075. +      prints EXPR-LIST according to FMT, and returns the resulting
  11076. +      string.
  11077. + 
  11078. + `sub(R, S, T)'
  11079. +      this is just like `gsub', but only the first matching substring is
  11080. +      replaced.
  11081. + 
  11082. + `substr(S, I, N)'
  11083. +      returns the N-character substring of S starting at I.  If N is
  11084. +      omitted, the rest of S is used.
  11085. + 
  11086. + `tolower(STR)'
  11087. +      returns a copy of the string STR, with all the upper-case
  11088. +      characters in STR translated to their corresponding lower-case
  11089. +      counterparts.  Nonalphabetic characters are left unchanged.
  11090. + 
  11091. + `toupper(STR)'
  11092. +      returns a copy of the string STR, with all the lower-case
  11093. +      characters in STR translated to their corresponding upper-case
  11094. +      counterparts.  Nonalphabetic characters are left unchanged.
  11095. + 
  11096. + `system(CMD-LINE)'
  11097. +      Execute the command CMD-LINE, and return the exit status.
  11098. + 
  11099. + 
  11100. + File: gawk.info,  Node: Time Functions Summary,  Next: String Constants Summary,  Prev: String Functions Summary,  Up: Actions Summary
  11101. + 
  11102. + Built-in time functions
  11103. + .......................
  11104. + 
  11105. +    The following two functions are available for getting the current
  11106. + time of day, and for formatting time stamps.
  11107. + 
  11108. + `systime()'
  11109. +      returns the current time of day as the number of seconds since a
  11110. +      particular epoch (Midnight, January 1, 1970 UTC, on POSIX systems).
  11111. + 
  11112. + `strftime(FORMAT, TIMESTAMP)'
  11113. +      formats TIMESTAMP according to the specification in FORMAT.  The
  11114. +      current time of day is used if no TIMESTAMP is supplied.  *Note
  11115. +      Functions for Dealing with Time Stamps: Time Functions, for the
  11116. +      details on the conversion specifiers that `strftime' accepts.
  11117. + 
  11118. + 
  11119. + File: gawk.info,  Node: String Constants Summary,  Prev: Time Functions Summary,  Up: Actions Summary
  11120. + 
  11121. + String Constants
  11122. + ................
  11123. + 
  11124. +    String constants in `awk' are sequences of characters enclosed
  11125. + between double quotes (`"').  Within strings, certain "escape sequences"
  11126. + are recognized, as in C.  These are:
  11127. + 
  11128. + `\\'
  11129. +      A literal backslash.
  11130. + 
  11131. + `\a'
  11132. +      The "alert" character; usually the ASCII BEL character.
  11133. + 
  11134. + `\b'
  11135. +      Backspace.
  11136. + 
  11137. + `\f'
  11138. +      Formfeed.
  11139. + 
  11140. + `\n'
  11141. +      Newline.
  11142. + 
  11143. + `\r'
  11144. +      Carriage return.
  11145. + 
  11146. + `\t'
  11147. +      Horizontal tab.
  11148. + 
  11149. + `\v'
  11150. +      Vertical tab.
  11151. + 
  11152. + `\xHEX DIGITS'
  11153. +      The character represented by the string of hexadecimal digits
  11154. +      following the `\x'.  As in ANSI C, all following hexadecimal
  11155. +      digits are considered part of the escape sequence.  (This feature
  11156. +      should tell us something about language design by committee.)
  11157. +      E.g., `"\x1B"' is a string containing the ASCII ESC (escape)
  11158. +      character.  (The `\x' escape sequence is not in POSIX `awk'.)
  11159. + 
  11160. + `\DDD'
  11161. +      The character represented by the 1-, 2-, or 3-digit sequence of
  11162. +      octal digits.  Thus, `"\033"' is also a string containing the
  11163. +      ASCII ESC (escape) character.
  11164. + 
  11165. + `\C'
  11166. +      The literal character C.
  11167. + 
  11168. +    The escape sequences may also be used inside constant regular
  11169. + expressions (e.g., the regexp `/[ \t\f\n\r\v]/' matches whitespace
  11170. + characters).
  11171. + 
  11172. +    *Note Constant Expressions: Constants.
  11173. + 
  11174. + 
  11175. + File: gawk.info,  Node: Functions Summary,  Next: Historical Features,  Prev: Rules Summary,  Up: Gawk Summary
  11176. + 
  11177. + Functions
  11178. + =========
  11179. + 
  11180. +    Functions in `awk' are defined as follows:
  11181. + 
  11182. +      function NAME(PARAMETER LIST) { STATEMENTS }
  11183. + 
  11184. +    Actual parameters supplied in the function call are used to
  11185. + instantiate the formal parameters declared in the function.  Arrays are
  11186. + passed by reference, other variables are passed by value.
  11187. + 
  11188. +    If there are fewer arguments passed than there are names in
  11189. + PARAMETER-LIST, the extra names are given the null string as value.
  11190. + Extra names have the effect of local variables.
  11191. + 
  11192. +    The open-parenthesis in a function call of a user-defined function
  11193. + must immediately follow the function name, without any intervening
  11194. + white space.  This is to avoid a syntactic ambiguity with the
  11195. + concatenation operator.
  11196. + 
  11197. +    The word `func' may be used in place of `function' (but not in POSIX
  11198. + `awk').
  11199. + 
  11200. +    Use the `return' statement to return a value from a function.
  11201. + 
  11202. +    *Note User-defined Functions: User-defined, for a more complete
  11203. + description.
  11204. + 
  11205. + 
  11206. + File: gawk.info,  Node: Historical Features,  Prev: Functions Summary,  Up: Gawk Summary
  11207. + 
  11208. + Historical Features
  11209. + ===================
  11210. + 
  11211. +    There are two features of historical `awk' implementations that
  11212. + `gawk' supports.  First, it is possible to call the `length' built-in
  11213. + function not only with no arguments, but even without parentheses!
  11214. + 
  11215. +      a = length
  11216. + 
  11217. + is the same as either of
  11218. + 
  11219. +      a = length()
  11220. +      a = length($0)
  11221. + 
  11222. + This feature is marked as "deprecated" in the POSIX standard, and
  11223. + `gawk' will issue a warning about its use if `-W lint' is specified on
  11224. + the command line.
  11225. + 
  11226. +    The other feature is the use of the `continue' statement outside the
  11227. + body of a `while', `for', or `do' loop.  Traditional `awk'
  11228. + implementations have treated such usage as equivalent to the `next'
  11229. + statement.  `gawk' will support this usage if `-W posix' has not been
  11230. + specified.
  11231. + 
  11232. + 
  11233. + File: gawk.info,  Node: Sample Program,  Next: Bugs,  Prev: Gawk Summary,  Up: Top
  11234. + 
  11235. + Sample Program
  11236. + **************
  11237. + 
  11238. +    The following example is a complete `awk' program, which prints the
  11239. + number of occurrences of each word in its input.  It illustrates the
  11240. + associative nature of `awk' arrays by using strings as subscripts.  It
  11241. + also demonstrates the `for X in ARRAY' construction.  Finally, it shows
  11242. + how `awk' can be used in conjunction with other utility programs to do
  11243. + a useful task of some complexity with a minimum of effort.  Some
  11244. + explanations follow the program listing.
  11245. + 
  11246. +      awk '
  11247. +      # Print list of word frequencies
  11248. +      {
  11249. +          for (i = 1; i <= NF; i++)
  11250. +              freq[$i]++
  11251. +      }
  11252. +      
  11253. +      END {
  11254. +          for (word in freq)
  11255. +              printf "%s\t%d\n", word, freq[word]
  11256. +      }'
  11257. + 
  11258. +    The first thing to notice about this program is that it has two
  11259. + rules.  The first rule, because it has an empty pattern, is executed on
  11260. + every line of the input.  It uses `awk''s field-accessing mechanism
  11261. + (*note Examining Fields: Fields.) to pick out the individual words from
  11262. + the line, and the built-in variable `NF' (*note Built-in Variables::.)
  11263. + to know how many fields are available.
  11264. + 
  11265. +    For each input word, an element of the array `freq' is incremented to
  11266. + reflect that the word has been seen an additional time.
  11267. + 
  11268. +    The second rule, because it has the pattern `END', is not executed
  11269. + until the input has been exhausted.  It prints out the contents of the
  11270. + `freq' table that has been built up inside the first action.
  11271. + 
  11272. +    Note that this program has several problems that would prevent it
  11273. + from being useful by itself on real text files:
  11274. + 
  11275. +    * Words are detected using the `awk' convention that fields are
  11276. +      separated by whitespace and that other characters in the input
  11277. +      (except newlines) don't have any special meaning to `awk'.  This
  11278. +      means that punctuation characters count as part of words.
  11279. + 
  11280. +    * The `awk' language considers upper and lower case characters to be
  11281. +      distinct.  Therefore, `foo' and `Foo' are not treated by this
  11282. +      program as the same word.  This is undesirable since in normal
  11283. +      text, words are capitalized if they begin sentences, and a
  11284. +      frequency analyzer should not be sensitive to that.
  11285. + 
  11286. +    * The output does not come out in any useful order.  You're more
  11287. +      likely to be interested in which words occur most frequently, or
  11288. +      having an alphabetized table of how frequently each word occurs.
  11289. + 
  11290. +    The way to solve these problems is to use some of the more advanced
  11291. + features of the `awk' language.  First, we use `tolower' to remove case
  11292. + distinctions.  Next, we use `gsub' to remove punctuation characters.
  11293. + Finally, we use the system `sort' utility to process the output of the
  11294. + `awk' script.  First, here is the new version of the program:
  11295. + 
  11296. +      awk '
  11297. +      # Print list of word frequencies
  11298. +      {
  11299. +          $0 = tolower($0)    # remove case distinctions
  11300. +          gsub(/[^a-z0-9_ \t]/, "", $0)  # remove punctuation
  11301. +          for (i = 1; i <= NF; i++)
  11302. +              freq[$i]++
  11303. +      }
  11304. +      
  11305. +      END {
  11306. +          for (word in freq)
  11307. +              printf "%s\t%d\n", word, freq[word]
  11308. +      }'
  11309. + 
  11310. +    Assuming we have saved this program in a file named `frequency.awk',
  11311. + and that the data is in `file1', the following pipeline
  11312. + 
  11313. +      awk -f frequency.awk file1 | sort +1 -nr
  11314. + 
  11315. + produces a table of the words appearing in `file1' in order of
  11316. + decreasing frequency.
  11317. + 
  11318. +    The `awk' program suitably massages the data and produces a word
  11319. + frequency table, which is not ordered.
  11320. + 
  11321. +    The `awk' script's output is then sorted by the `sort' command and
  11322. + printed on the terminal.  The options given to `sort' in this example
  11323. + specify to sort using the second field of each input line (skipping one
  11324. + field), that the sort keys should be treated as numeric quantities
  11325. + (otherwise `15' would come before `5'), and that the sorting should be
  11326. + done in descending (reverse) order.
  11327. + 
  11328. +    We could have even done the `sort' from within the program, by
  11329. + changing the `END' action to:
  11330. + 
  11331. +      END {
  11332. +          sort = "sort +1 -nr"
  11333. +          for (word in freq)
  11334. +              printf "%s\t%d\n", word, freq[word] | sort
  11335. +          close(sort)
  11336. +      }'
  11337. + 
  11338. +    See the general operating system documentation for more information
  11339. + on how to use the `sort' command.
  11340. + 
  11341. + 
  11342. + File: gawk.info,  Node: Bugs,  Next: Notes,  Prev: Sample Program,  Up: Top
  11343. + 
  11344. + Reporting Problems and Bugs
  11345. + ***************************
  11346. + 
  11347. +    If you have problems with `gawk' or think that you have found a bug,
  11348. + please report it to the developers; we cannot promise to do anything
  11349. + but we might well want to fix it.
  11350. + 
  11351. +    Before reporting a bug, make sure you have actually found a real bug.
  11352. + Carefully reread the documentation and see if it really says you can do
  11353. + what you're trying to do.  If it's not clear whether you should be able
  11354. + to do something or not, report that too; it's a bug in the
  11355. + documentation!
  11356. + 
  11357. +    Before reporting a bug or trying to fix it yourself, try to isolate
  11358. + it to the smallest possible `awk' program and input data file that
  11359. + reproduces the problem.  Then send us the program and data file, some
  11360. + idea of what kind of Unix system you're using, and the exact results
  11361. + `gawk' gave you.  Also say what you expected to occur; this will help
  11362. + us decide whether the problem was really in the documentation.
  11363. + 
  11364. +    Once you have a precise problem, send e-mail to (Internet)
  11365. + `bug-gnu-utils@prep.ai.mit.edu' or (UUCP)
  11366. + `mit-eddie!prep.ai.mit.edu!bug-gnu-utils'.  Please include the version
  11367. + number of `gawk' you are using.  You can get this information with the
  11368. + command `gawk -W version '{}' /dev/null'.  You should send carbon
  11369. + copies of your mail to David Trueman at `david@cs.dal.ca', and to
  11370. + Arnold Robbins, who can be reached at `arnold@skeeve.atl.ga.us'.  David
  11371. + is most likely to fix code problems, while Arnold is most likely to fix
  11372. + documentation problems.
  11373. + 
  11374. +    Non-bug suggestions are always welcome as well.  If you have
  11375. + questions about things that are unclear in the documentation or are
  11376. + just obscure features, ask Arnold Robbins; he will try to help you out,
  11377. + although he may not have the time to fix the problem.  You can send him
  11378. + electronic mail at the Internet address above.
  11379. + 
  11380. +    If you find bugs in one of the non-Unix ports of `gawk', please send
  11381. + an electronic mail message to the person who maintains that port.  They
  11382. + are listed below, and also in the `README' file in the `gawk'
  11383. + distribution.  Information in the `README' file should be considered
  11384. + authoritative if it conflicts with this manual.
  11385. + 
  11386. +    The people maintaining the non-Unix ports of `gawk' are:
  11387. + 
  11388. + MS-DOS
  11389. +      The port to MS-DOS is maintained by Scott Deifik.  His electronic
  11390. +      mail address is `scottd@amgen.com'.
  11391. + 
  11392. + VMS
  11393. +      The port to VAX VMS is maintained by Pat Rankin.  His electronic
  11394. +      mail address is `rankin@eql.caltech.edu'.
  11395. + 
  11396. + Atari ST
  11397. +      The port to the Atari ST is maintained by Michal Jaegermann.  His
  11398. +      electronic mail address is `ntomczak@vm.ucs.ualberta.ca'.
  11399. + 
  11400. +    If your bug is also reproducible under Unix, please send copies of
  11401. + your report to the general GNU bug list, as well as to Arnold Robbins
  11402. + and David Trueman, at the addresses listed above.
  11403. + 
  11404. + 
  11405. + File: gawk.info,  Node: Notes,  Next: Glossary,  Prev: Bugs,  Up: Top
  11406. + 
  11407. + Implementation Notes
  11408. + ********************
  11409. + 
  11410. +    This appendix contains information mainly of interest to
  11411. + implementors and maintainers of `gawk'.  Everything in it applies
  11412. + specifically to `gawk', and not to other implementations.
  11413. + 
  11414. + * Menu:
  11415. + 
  11416. + * Compatibility Mode::          How to disable certain `gawk' extensions.
  11417. + * Future Extensions::           New features we may implement soon.
  11418. + * Improvements::                Suggestions for improvements by volunteers.
  11419. + 
  11420. + 
  11421. + File: gawk.info,  Node: Compatibility Mode,  Next: Future Extensions,  Prev: Notes,  Up: Notes
  11422. + 
  11423. + Downward Compatibility and Debugging
  11424. + ====================================
  11425. + 
  11426. +    *Note Extensions in `gawk' not in POSIX `awk': POSIX/GNU, for a
  11427. + summary of the GNU extensions to the `awk' language and program.  All
  11428. + of these features can be turned off by invoking `gawk' with the `-W
  11429. + compat' option, or with the `-W posix' option.
  11430. + 
  11431. +    If `gawk' is compiled for debugging with `-DDEBUG', then there is
  11432. + one more option available on the command line:
  11433. + 
  11434. + `-W parsedebug'
  11435. +      Print out the parse stack information as the program is being
  11436. +      parsed.
  11437. + 
  11438. +    This option is intended only for serious `gawk' developers, and not
  11439. + for the casual user.  It probably has not even been compiled into your
  11440. + version of `gawk', since it slows down execution.
  11441. + 
  11442. + 
  11443. + File: gawk.info,  Node: Future Extensions,  Next: Improvements,  Prev: Compatibility Mode,  Up: Notes
  11444. + 
  11445. + Probable Future Extensions
  11446. + ==========================
  11447. + 
  11448. +    This section briefly lists extensions that indicate the directions
  11449. + we are currently considering for `gawk'.  The file `FUTURES' in the
  11450. + `gawk' distributions lists these extensions, as well as several others.
  11451. + 
  11452. + `RS' as a regexp
  11453. +      The meaning of `RS' may be generalized along the lines of `FS'.
  11454. + 
  11455. + Control of subprocess environment
  11456. +      Changes made in `gawk' to the array `ENVIRON' may be propagated to
  11457. +      subprocesses run by `gawk'.
  11458. + 
  11459. + Databases
  11460. +      It may be possible to map a GDBM/NDBM/SDBM file into an `awk'
  11461. +      array.
  11462. + 
  11463. + Single-character fields
  11464. +      The null string, `""', as a field separator, will cause field
  11465. +      splitting and the `split' function to separate individual
  11466. +      characters.  Thus, `split(a, "abcd", "")' would yield `a[1] ==
  11467. +      "a"', `a[2] == "b"', and so on.
  11468. + 
  11469. + More `lint' warnings
  11470. +      There are more things that could be checked for portability.
  11471. + 
  11472. + `RECLEN' variable for fixed length records
  11473. +      Along with `FIELDWIDTHS', this would speed up the processing of
  11474. +      fixed-length records.
  11475. + 
  11476. + `RT' variable to hold the record terminator
  11477. +      It is occasionally useful to have access to the actual string of
  11478. +      characters that matched the `RS' variable.  The `RT' variable
  11479. +      would hold these characters.
  11480. + 
  11481. + A `restart' keyword
  11482. +      After modifying `$0', `restart' would restart the pattern matching
  11483. +      loop, without reading a new record from the input.
  11484. + 
  11485. + A `|&' redirection
  11486. +      The `|&' redirection, in place of `|', would open a two-way
  11487. +      pipeline for communication with a sub-process (via `getline' and
  11488. +      `print' and `printf').
  11489. + 
  11490. + `IGNORECASE' affecting all comparisons
  11491. +      The effects of the `IGNORECASE' variable may be generalized to all
  11492. +      string comparisons, and not just regular expression operations.
  11493. + 
  11494. + A way to mix command line source code and library files
  11495. +      There may be a new option that would make it possible to easily
  11496. +      use library functions from a program entered on the command line.
  11497. + 
  11498. + GNU-style long options
  11499. +      We will add GNU-style long options to `gawk' for compatibility
  11500. +      with other GNU programs.  (For example, `--field-separator=:'
  11501. +      would be equivalent to `-F:'.)
  11502. + 
  11503. + 
  11504. + File: gawk.info,  Node: Improvements,  Prev: Future Extensions,  Up: Notes
  11505. + 
  11506. + Suggestions for Improvements
  11507. + ============================
  11508. + 
  11509. +    Here are some projects that would-be `gawk' hackers might like to
  11510. + take on.  They vary in size from a few days to a few weeks of
  11511. + programming, depending on which one you choose and how fast a
  11512. + programmer you are.  Please send any improvements you write to the
  11513. + maintainers at the GNU project.
  11514. + 
  11515. +   1. Compilation of `awk' programs: `gawk' uses a Bison (YACC-like)
  11516. +      parser to convert the script given it into a syntax tree; the
  11517. +      syntax tree is then executed by a simple recursive evaluator.
  11518. +      This method incurs a lot of overhead, since the recursive
  11519. +      evaluator performs many procedure calls to do even the simplest
  11520. +      things.
  11521. + 
  11522. +      It should be possible for `gawk' to convert the script's parse tree
  11523. +      into a C program which the user would then compile, using the
  11524. +      normal C compiler and a special `gawk' library to provide all the
  11525. +      needed functions (regexps, fields, associative arrays, type
  11526. +      coercion, and so on).
  11527. + 
  11528. +      An easier possibility might be for an intermediate phase of `awk'
  11529. +      to convert the parse tree into a linear byte code form like the
  11530. +      one used in GNU Emacs Lisp.  The recursive evaluator would then be
  11531. +      replaced by a straight line byte code interpreter that would be
  11532. +      intermediate in speed between running a compiled program and doing
  11533. +      what `gawk' does now.
  11534. + 
  11535. +      This may actually happen for the 3.0 version of `gawk'.
  11536. + 
  11537. +   2. An error message section has not been included in this version of
  11538. +      the manual.  Perhaps some nice beta testers will document some of
  11539. +      the messages for the future.
  11540. + 
  11541. +   3. The programs in the test suite could use documenting in this
  11542. +      manual.
  11543. + 
  11544. +   4. The programs and data files in the manual should be available in
  11545. +      separate files to facilitate experimentation.
  11546. + 
  11547. +   5. See the `FUTURES' file for more ideas.  Contact us if you would
  11548. +      seriously like to tackle any of the items listed there.
  11549. + 
  11550. + 
  11551. + File: gawk.info,  Node: Glossary,  Next: Index,  Prev: Notes,  Up: Top
  11552. + 
  11553. + Glossary
  11554. + ********
  11555. + 
  11556. + Action
  11557. +      A series of `awk' statements attached to a rule.  If the rule's
  11558. +      pattern matches an input record, the `awk' language executes the
  11559. +      rule's action.  Actions are always enclosed in curly braces.
  11560. +      *Note Overview of Actions: Actions.
  11561. + 
  11562. + Amazing `awk' Assembler
  11563. +      Henry Spencer at the University of Toronto wrote a retargetable
  11564. +      assembler completely as `awk' scripts.  It is thousands of lines
  11565. +      long, including machine descriptions for several 8-bit
  11566. +      microcomputers.  It is a good example of a program that would have
  11567. +      been better written in another language.
  11568. + 
  11569. + ANSI
  11570. +      The American National Standards Institute.  This organization
  11571. +      produces many standards, among them the standard for the C
  11572. +      programming language.
  11573. + 
  11574. + Assignment
  11575. +      An `awk' expression that changes the value of some `awk' variable
  11576. +      or data object.  An object that you can assign to is called an
  11577. +      "lvalue".  *Note Assignment Expressions: Assignment Ops.
  11578. + 
  11579. + `awk' Language
  11580. +      The language in which `awk' programs are written.
  11581. + 
  11582. + `awk' Program
  11583. +      An `awk' program consists of a series of "patterns" and "actions",
  11584. +      collectively known as "rules".  For each input record given to the
  11585. +      program, the program's rules are all processed in turn.  `awk'
  11586. +      programs may also contain function definitions.
  11587. + 
  11588. + `awk' Script
  11589. +      Another name for an `awk' program.
  11590. + 
  11591. + Built-in Function
  11592. +      The `awk' language provides built-in functions that perform various
  11593. +      numerical, time stamp related, and string computations.  Examples
  11594. +      are `sqrt' (for the square root of a number) and `substr' (for a
  11595. +      substring of a string).  *Note Built-in Functions: Built-in.
  11596. + 
  11597. + Built-in Variable
  11598. +      `ARGC', `ARGIND', `ARGV', `CONVFMT', `ENVIRON', `ERRNO',
  11599. +      `FIELDWIDTHS', `FILENAME', `FNR', `FS', `IGNORECASE', `NF', `NR',
  11600. +      `OFMT', `OFS', `ORS', `RLENGTH', `RSTART', `RS', and `SUBSEP', are
  11601. +      the variables that have special meaning to `awk'.  Changing some
  11602. +      of them affects `awk''s running environment.  *Note Built-in
  11603. +      Variables::.
  11604. + 
  11605. + Braces
  11606. +      See "Curly Braces."
  11607. + 
  11608. + C
  11609. +      The system programming language that most GNU software is written
  11610. +      in.  The `awk' programming language has C-like syntax, and this
  11611. +      manual points out similarities between `awk' and C when
  11612. +      appropriate.
  11613. + 
  11614. + CHEM
  11615. +      A preprocessor for `pic' that reads descriptions of molecules and
  11616. +      produces `pic' input for drawing them.  It was written by Brian
  11617. +      Kernighan, and is available from `netlib@research.att.com'.
  11618. + 
  11619. + Compound Statement
  11620. +      A series of `awk' statements, enclosed in curly braces.  Compound
  11621. +      statements may be nested.  *Note Control Statements in Actions:
  11622. +      Statements.
  11623. + 
  11624. + Concatenation
  11625. +      Concatenating two strings means sticking them together, one after
  11626. +      another, giving a new string.  For example, the string `foo'
  11627. +      concatenated with the string `bar' gives the string `foobar'.
  11628. +      *Note String Concatenation: Concatenation.
  11629. + 
  11630. + Conditional Expression
  11631. +      An expression using the `?:' ternary operator, such as `EXPR1 ?
  11632. +      EXPR2 : EXPR3'.  The expression EXPR1 is evaluated; if the result
  11633. +      is true, the value of the whole expression is the value of EXPR2
  11634. +      otherwise the value is EXPR3.  In either case, only one of EXPR2
  11635. +      and EXPR3 is evaluated.  *Note Conditional Expressions:
  11636. +      Conditional Exp.
  11637. + 
  11638. + Constant Regular Expression
  11639. +      A constant regular expression is a regular expression written
  11640. +      within slashes, such as `/foo/'.  This regular expression is chosen
  11641. +      when you write the `awk' program, and cannot be changed doing its
  11642. +      execution.  *Note How to Use Regular Expressions: Regexp Usage.
  11643. + 
  11644. + Comparison Expression
  11645. +      A relation that is either true or false, such as `(a < b)'.
  11646. +      Comparison expressions are used in `if', `while', and `for'
  11647. +      statements, and in patterns to select which input records to
  11648. +      process.  *Note Comparison Expressions: Comparison Ops.
  11649. + 
  11650. + Curly Braces
  11651. +      The characters `{' and `}'.  Curly braces are used in `awk' for
  11652. +      delimiting actions, compound statements, and function bodies.
  11653. + 
  11654. + Data Objects
  11655. +      These are numbers and strings of characters.  Numbers are
  11656. +      converted into strings and vice versa, as needed.  *Note
  11657. +      Conversion of Strings and Numbers: Conversion.
  11658. + 
  11659. + Dynamic Regular Expression
  11660. +      A dynamic regular expression is a regular expression written as an
  11661. +      ordinary expression.  It could be a string constant, such as
  11662. +      `"foo"', but it may also be an expression whose value may vary.
  11663. +      *Note How to Use Regular Expressions: Regexp Usage.
  11664. + 
  11665. + Escape Sequences
  11666. +      A special sequence of characters used for describing nonprinting
  11667. +      characters, such as `\n' for newline, or `\033' for the ASCII ESC
  11668. +      (escape) character.  *Note Constant Expressions: Constants.
  11669. + 
  11670. + Field
  11671. +      When `awk' reads an input record, it splits the record into pieces
  11672. +      separated by whitespace (or by a separator regexp which you can
  11673. +      change by setting the built-in variable `FS').  Such pieces are
  11674. +      called fields.  If the pieces are of fixed length, you can use the
  11675. +      built-in variable `FIELDWIDTHS' to describe their lengths.  *Note
  11676. +      How Input is Split into Records: Records.
  11677. + 
  11678. + Format
  11679. +      Format strings are used to control the appearance of output in the
  11680. +      `printf' statement.  Also, data conversions from numbers to strings
  11681. +      are controlled by the format string contained in the built-in
  11682. +      variable `CONVFMT'.  *Note Format-Control Letters: Control Letters.
  11683. + 
  11684. + Function
  11685. +      A specialized group of statements often used to encapsulate general
  11686. +      or program-specific tasks.  `awk' has a number of built-in
  11687. +      functions, and also allows you to define your own.  *Note Built-in
  11688. +      Functions: Built-in.  Also, see *Note User-defined Functions:
  11689. +      User-defined.
  11690. + 
  11691. + `gawk'
  11692. +      The GNU implementation of `awk'.
  11693. + 
  11694. + GNU
  11695. +      "GNU's not Unix".  An on-going project of the Free Software
  11696. +      Foundation to create a complete, freely distributable,
  11697. +      POSIX-compliant computing environment.
  11698. + 
  11699. + Input Record
  11700. +      A single chunk of data read in by `awk'.  Usually, an `awk' input
  11701. +      record consists of one line of text.  *Note How Input is Split
  11702. +      into Records: Records.
  11703. + 
  11704. + Keyword
  11705. +      In the `awk' language, a keyword is a word that has special
  11706. +      meaning.  Keywords are reserved and may not be used as variable
  11707. +      names.
  11708. + 
  11709. +      `awk''s keywords are: `if', `else', `while', `do...while', `for',
  11710. +      `for...in', `break', `continue', `delete', `next', `function',
  11711. +      `func', and `exit'.
  11712. + 
  11713. + Lvalue
  11714. +      An expression that can appear on the left side of an assignment
  11715. +      operator.  In most languages, lvalues can be variables or array
  11716. +      elements.  In `awk', a field designator can also be used as an
  11717. +      lvalue.
  11718. + 
  11719. + Number
  11720. +      A numeric valued data object.  The `gawk' implementation uses
  11721. +      double precision floating point to represent numbers.
  11722. + 
  11723. + Pattern
  11724. +      Patterns tell `awk' which input records are interesting to which
  11725. +      rules.
  11726. + 
  11727. +      A pattern is an arbitrary conditional expression against which
  11728. +      input is tested.  If the condition is satisfied, the pattern is
  11729. +      said to "match" the input record.  A typical pattern might compare
  11730. +      the input record against a regular expression.  *Note Patterns::.
  11731. + 
  11732. + POSIX
  11733. +      The name for a series of standards being developed by the IEEE
  11734. +      that specify a Portable Operating System interface.  The "IX"
  11735. +      denotes the Unix heritage of these standards.  The main standard
  11736. +      of interest for `awk' users is P1003.2, the Command Language and
  11737. +      Utilities standard.
  11738. + 
  11739. + Range (of input lines)
  11740. +      A sequence of consecutive lines from the input file.  A pattern
  11741. +      can specify ranges of input lines for `awk' to process, or it can
  11742. +      specify single lines.  *Note Patterns::.
  11743. + 
  11744. + Recursion
  11745. +      When a function calls itself, either directly or indirectly.  If
  11746. +      this isn't clear, refer to the entry for "recursion."
  11747. + 
  11748. + Redirection
  11749. +      Redirection means performing input from other than the standard
  11750. +      input stream, or output to other than the standard output stream.
  11751. + 
  11752. +      You can redirect the output of the `print' and `printf' statements
  11753. +      to a file or a system command, using the `>', `>>', and `|'
  11754. +      operators.  You can redirect input to the `getline' statement using
  11755. +      the `<' and `|' operators.  *Note Redirecting Output of `print'
  11756. +      and `printf': Redirection.
  11757. + 
  11758. + Regular Expression
  11759. +      See "regexp."
  11760. + 
  11761. + Regexp
  11762. +      Short for "regular expression".  A regexp is a pattern that
  11763. +      denotes a set of strings, possibly an infinite set.  For example,
  11764. +      the regexp `R.*xp' matches any string starting with the letter `R'
  11765. +      and ending with the letters `xp'.  In `awk', regexps are used in
  11766. +      patterns and in conditional expressions.  Regexps may contain
  11767. +      escape sequences.  *Note Regular Expressions as Patterns: Regexp.
  11768. + 
  11769. + Rule
  11770. +      A segment of an `awk' program, that specifies how to process single
  11771. +      input records.  A rule consists of a "pattern" and an "action".
  11772. +      `awk' reads an input record; then, for each rule, if the input
  11773. +      record satisfies the rule's pattern, `awk' executes the rule's
  11774. +      action.  Otherwise, the rule does nothing for that input record.
  11775. + 
  11776. + Side Effect
  11777. +      A side effect occurs when an expression has an effect aside from
  11778. +      merely producing a value.  Assignment expressions, increment
  11779. +      expressions and function calls have side effects.  *Note
  11780. +      Assignment Expressions: Assignment Ops.
  11781. + 
  11782. + Special File
  11783. +      A file name interpreted internally by `gawk', instead of being
  11784. +      handed directly to the underlying operating system.  For example,
  11785. +      `/dev/stdin'.  *Note Standard I/O Streams: Special Files.
  11786. + 
  11787. + Stream Editor
  11788. +      A program that reads records from an input stream and processes
  11789. +      them one or more at a time.  This is in contrast with batch
  11790. +      programs, which may expect to read their input files in entirety
  11791. +      before starting to do anything, and with interactive programs,
  11792. +      which require input from the user.
  11793. + 
  11794. + String
  11795. +      A datum consisting of a sequence of characters, such as `I am a
  11796. +      string'.  Constant strings are written with double-quotes in the
  11797. +      `awk' language, and may contain escape sequences.  *Note Constant
  11798. +      Expressions: Constants.
  11799. + 
  11800. + Whitespace
  11801. +      A sequence of blank or tab characters occurring inside an input
  11802. +      record or a string.
  11803. + 
  11804. diff -rc --new-file /src/baseline/gawk-2.15.5/gawk.info-9 gawk-2.15.5/gawk.info-9
  11805. *** /src/baseline/gawk-2.15.5/gawk.info-9    Thu Jan  1 00:00:00 1970
  11806. --- gawk-2.15.5/gawk.info-9    Sun Jun 12 22:28:56 1994
  11807. ***************
  11808. *** 0 ****
  11809. --- 1,359 ----
  11810. + This is Info file gawk.info, produced by Makeinfo-1.55 from the input
  11811. + file /gnu/src/amiga/gawk-2.15.5/gawk.texi.
  11812. + 
  11813. +    This file documents `awk', a program that you can use to select
  11814. + particular records in a file and perform operations upon them.
  11815. + 
  11816. +    This is Edition 0.15 of `The GAWK Manual',
  11817. + for the 2.15 version of the GNU implementation
  11818. + of AWK.
  11819. + 
  11820. +    Copyright (C) 1989, 1991, 1992, 1993 Free Software Foundation, Inc.
  11821. + 
  11822. +    Permission is granted to make and distribute verbatim copies of this
  11823. + manual provided the copyright notice and this permission notice are
  11824. + preserved on all copies.
  11825. + 
  11826. +    Permission is granted to copy and distribute modified versions of
  11827. + this manual under the conditions for verbatim copying, provided that
  11828. + the entire resulting derived work is distributed under the terms of a
  11829. + permission notice identical to this one.
  11830. + 
  11831. +    Permission is granted to copy and distribute translations of this
  11832. + manual into another language, under the above conditions for modified
  11833. + versions, except that this permission notice may be stated in a
  11834. + translation approved by the Foundation.
  11835. + 
  11836. + 
  11837. + File: gawk.info,  Node: Index,  Prev: Glossary,  Up: Top
  11838. + 
  11839. + Index
  11840. + *****
  11841. + 
  11842. + * Menu:
  11843. + 
  11844. + * $ (field operator):                   Fields.
  11845. + * -assign option:                       Options.
  11846. + * -compat option:                       Options.
  11847. + * -copyleft option:                     Options.
  11848. + * -copyright option:                    Options.
  11849. + * -field-separator option:              Options.
  11850. + * -file option:                         Options.
  11851. + * -help option:                         Options.
  11852. + * -lint option:                         Options.
  11853. + * -posix option:                        Options.
  11854. + * -source option:                       Options.
  11855. + * -usage option:                        Options.
  11856. + * -version option:                      Options.
  11857. + * AWKPATH environment variable:         AWKPATH Variable.
  11858. + * awk language:                         This Manual.
  11859. + * awk program:                          This Manual.
  11860. + * BEGIN special pattern:                BEGIN/END.
  11861. + * break statement:                      Break Statement.
  11862. + * continue statement:                   Continue Statement.
  11863. + * delete statement:                     Delete.
  11864. + * END special pattern:                  BEGIN/END.
  11865. + * exit statement:                       Exit Statement.
  11866. + * for (x in ...):                       Scanning an Array.
  11867. + * for statement:                        For Statement.
  11868. + * if statement:                         If Statement.
  11869. + * next file statement:                  Next File Statement.
  11870. + * next statement:                       Next Statement.
  11871. + * printf statement, syntax of:          Basic Printf.
  11872. + * printf, format-control characters:    Control Letters.
  11873. + * printf, modifiers:                    Format Modifiers.
  11874. + * print statement:                      Print.
  11875. + * return statement:                     Return Statement.
  11876. + * while statement:                      While Statement.
  11877. + * /dev/fd/:                             Special Files.
  11878. + * /dev/pgrpid:                          Special Files.
  11879. + * /dev/pid:                             Special Files.
  11880. + * /dev/ppid:                            Special Files.
  11881. + * /dev/stderr:                          Special Files.
  11882. + * /dev/stdin:                           Special Files.
  11883. + * /dev/stdout:                          Special Files.
  11884. + * /dev/user:                            Special Files.
  11885. + * BBS-list file:                        Sample Data Files.
  11886. + * inventory-shipped file:               Sample Data Files.
  11887. + * #!:                                   Executable Scripts.
  11888. + * #:                                    Comments.
  11889. + * -F option:                            Field Separators.
  11890. + * -f option:                            Long.
  11891. + * -v option:                            Options.
  11892. + * -W option:                            Options.
  11893. + * print $0:                             Very Simple.
  11894. + * accessing fields:                     Fields.
  11895. + * acronym:                              History.
  11896. + * action, curly braces:                 Actions.
  11897. + * action, default:                      Very Simple.
  11898. + * action, definition of:                Actions.
  11899. + * action, separating statements:        Actions.
  11900. + * addition:                             Arithmetic Ops.
  11901. + * and operator:                         Boolean Ops.
  11902. + * anonymous ftp:                        Extracting.
  11903. + * anonymous uucp:                       Extracting.
  11904. + * applications of awk:                  When.
  11905. + * ARGIND:                               Auto-set.
  11906. + * arguments in function call:           Function Calls.
  11907. + * arguments, command line:              Command Line.
  11908. + * ARGV:                                 Other Arguments.
  11909. + * arithmetic operators:                 Arithmetic Ops.
  11910. + * array assignment:                     Assigning Elements.
  11911. + * array reference:                      Reference to Elements.
  11912. + * arrays:                               Array Intro.
  11913. + * arrays, definition of:                Array Intro.
  11914. + * arrays, deleting an element:          Delete.
  11915. + * arrays, multi-dimensional subscripts: Multi-dimensional.
  11916. + * arrays, presence of elements:         Reference to Elements.
  11917. + * arrays, special for statement:        Scanning an Array.
  11918. + * assignment operators:                 Assignment Ops.
  11919. + * assignment to fields:                 Changing Fields.
  11920. + * associative arrays:                   Array Intro.
  11921. + * backslash continuation:               Statements/Lines.
  11922. + * basic function of gawk:               Getting Started.
  11923. + * body of a loop:                       While Statement.
  11924. + * boolean expressions:                  Boolean Ops.
  11925. + * boolean operators:                    Boolean Ops.
  11926. + * boolean patterns:                     Boolean Patterns.
  11927. + * buffering output:                     I/O Functions.
  11928. + * buffers, flushing:                    I/O Functions.
  11929. + * built-in functions:                   Built-in.
  11930. + * built-in variables:                   Built-in Variables.
  11931. + * built-in variables, user modifiable:  User-modified.
  11932. + * call by reference:                    Function Caveats.
  11933. + * call by value:                        Function Caveats.
  11934. + * calling a function:                   Function Calls.
  11935. + * case sensitivity:                     Read Terminal.
  11936. + * changing contents of a field:         Changing Fields.
  11937. + * close:                                Close Input.
  11938. + * close:                                Close Output.
  11939. + * closing input files and pipes:        Close Input.
  11940. + * closing output files and pipes:       Close Output.
  11941. + * command line:                         Command Line.
  11942. + * command line formats:                 Running gawk.
  11943. + * command line, setting FS on:          Field Separators.
  11944. + * comments:                             Comments.
  11945. + * comparison expressions:               Comparison Ops.
  11946. + * comparison expressions as patterns:   Comparison Patterns.
  11947. + * computed regular expressions:         Regexp Usage.
  11948. + * concatenation:                        Concatenation.
  11949. + * conditional expression:               Conditional Exp.
  11950. + * constants, types of:                  Constants.
  11951. + * continuation of lines:                Statements/Lines.
  11952. + * control statement:                    Statements.
  11953. + * conversion of strings and numbers:    Conversion.
  11954. + * conversion of strings and numbers:    Values.
  11955. + * conversions, during subscripting:     Numeric Array Subscripts.
  11956. + * CONVFMT:                              Numeric Array Subscripts.
  11957. + * CONVFMT:                              Comparison Ops.
  11958. + * CONVFMT:                              Conversion.
  11959. + * curly braces:                         Actions.
  11960. + * default action:                       Very Simple.
  11961. + * default pattern:                      Very Simple.
  11962. + * defining functions:                   Definition Syntax.
  11963. + * deleting elements of arrays:          Delete.
  11964. + * deprecated features:                  Obsolete.
  11965. + * deprecated options:                   Obsolete.
  11966. + * differences: gawk and awk:            Getline.
  11967. + * directory search:                     AWKPATH Variable.
  11968. + * division:                             Arithmetic Ops.
  11969. + * documenting awk programs:             Comments.
  11970. + * dynamic regular expressions:          Regexp Usage.
  11971. + * element assignment:                   Assigning Elements.
  11972. + * element of array:                     Reference to Elements.
  11973. + * empty pattern:                        Empty.
  11974. + * ENVIRON:                              Auto-set.
  11975. + * ERRNO:                                Getline.
  11976. + * escape sequence notation:             Constants.
  11977. + * examining fields:                     Fields.
  11978. + * executable scripts:                   Executable Scripts.
  11979. + * explicit input:                       Getline.
  11980. + * exponentiation:                       Arithmetic Ops.
  11981. + * expression:                           Expressions.
  11982. + * expression, conditional:              Conditional Exp.
  11983. + * expressions, assignment:              Assignment Ops.
  11984. + * expressions, boolean:                 Boolean Ops.
  11985. + * expressions, comparison:              Comparison Ops.
  11986. + * field separator, FS:                  Field Separators.
  11987. + * field separator, choice of:           Field Separators.
  11988. + * field separator: on command line:     Field Separators.
  11989. + * field, changing contents of:          Changing Fields.
  11990. + * fields:                               Fields.
  11991. + * fields, separating:                   Field Separators.
  11992. + * file descriptors:                     Special Files.
  11993. + * file, awk program:                    Long.
  11994. + * FILENAME:                             Reading Files.
  11995. + * flushing buffers:                     I/O Functions.
  11996. + * FNR:                                  Records.
  11997. + * format specifier:                     Control Letters.
  11998. + * format string:                        Basic Printf.
  11999. + * formatted output:                     Printf.
  12000. + * FS:                                   Field Separators.
  12001. + * ftp, anonymous:                       Extracting.
  12002. + * function call:                        Function Calls.
  12003. + * function definition:                  Definition Syntax.
  12004. + * functions, user-defined:              User-defined.
  12005. + * getline:                              Getline.
  12006. + * getting gawk:                         Extracting.
  12007. + * gsub:                                 String Functions.
  12008. + * history of awk:                       History.
  12009. + * how awk works:                        Two Rules.
  12010. + * increment operators:                  Increment Ops.
  12011. + * input:                                Reading Files.
  12012. + * input file, sample:                   Sample Data Files.
  12013. + * input redirection:                    Getline.
  12014. + * input, getline command:               Getline.
  12015. + * input, explicit:                      Getline.
  12016. + * input, multiple line records:         Multiple Line.
  12017. + * input, standard:                      Read Terminal.
  12018. + * installation, atari:                  Atari Installation.
  12019. + * installation, ms-dos:                 MS-DOS Installation.
  12020. + * installation, unix:                   Quick Installation.
  12021. + * installation, vms:                    VMS Installation.
  12022. + * interaction, awk and other programs:  I/O Functions.
  12023. + * invocation of gawk:                   Command Line.
  12024. + * language, awk:                        This Manual.
  12025. + * length:                               String Functions.
  12026. + * logical operations:                   Boolean Ops.
  12027. + * long options:                         Command Line.
  12028. + * loop:                                 While Statement.
  12029. + * loops, exiting:                       Break Statement.
  12030. + * lvalue:                               Assignment Ops.
  12031. + * manual, using this:                   This Manual.
  12032. + * match:                                String Functions.
  12033. + * match:                                String Functions.
  12034. + * metacharacters:                       Regexp Operators.
  12035. + * modifiers (in format specifiers):     Format Modifiers.
  12036. + * multi-dimensional subscripts:         Multi-dimensional.
  12037. + * multiple line records:                Multiple Line.
  12038. + * multiple passes over data:            Other Arguments.
  12039. + * multiple statements on one line:      Statements/Lines.
  12040. + * multiplication:                       Arithmetic Ops.
  12041. + * NF:                                   Fields.
  12042. + * not operator:                         Boolean Ops.
  12043. + * NR:                                   Records.
  12044. + * number of fields, NF:                 Fields.
  12045. + * number of records, NR or FNR:         Records.
  12046. + * numbers, used as subscripts:          Numeric Array Subscripts.
  12047. + * numeric constant:                     Constants.
  12048. + * numeric value:                        Constants.
  12049. + * obsolete features:                    Obsolete.
  12050. + * obsolete options:                     Obsolete.
  12051. + * OFMT:                                 Conversion.
  12052. + * OFMT:                                 OFMT.
  12053. + * OFS:                                  Output Separators.
  12054. + * one-liners:                           One-liners.
  12055. + * operator precedence:                  Precedence.
  12056. + * operators, $:                         Fields.
  12057. + * operators, arithmetic:                Arithmetic Ops.
  12058. + * operators, assignment:                Assignment Ops.
  12059. + * operators, boolean:                   Boolean Ops.
  12060. + * operators, increment:                 Increment Ops.
  12061. + * operators, regexp matching:           Regexp Usage.
  12062. + * operators, relational:                Comparison Patterns.
  12063. + * operators, relational:                Comparison Ops.
  12064. + * operators, string:                    Concatenation.
  12065. + * operators, string-matching:           Regexp Usage.
  12066. + * options, command line:                Command Line.
  12067. + * options, long:                        Command Line.
  12068. + * or operator:                          Boolean Ops.
  12069. + * ORS:                                  Output Separators.
  12070. + * output:                               Printing.
  12071. + * output field separator, OFS:          Output Separators.
  12072. + * output record separator, ORS:         Output Separators.
  12073. + * output redirection:                   Redirection.
  12074. + * output, buffering:                    I/O Functions.
  12075. + * output, formatted:                    Printf.
  12076. + * output, piping:                       File/Pipe Redirection.
  12077. + * passes, multiple:                     Other Arguments.
  12078. + * path, search:                         AWKPATH Variable.
  12079. + * pattern, case sensitive:              Read Terminal.
  12080. + * pattern, comparison expressions:      Comparison Patterns.
  12081. + * pattern, default:                     Very Simple.
  12082. + * pattern, definition of:               Patterns.
  12083. + * pattern, empty:                       Empty.
  12084. + * pattern, regular expressions:         Regexp.
  12085. + * patterns, BEGIN:                      BEGIN/END.
  12086. + * patterns, END:                        BEGIN/END.
  12087. + * patterns, boolean:                    Boolean Patterns.
  12088. + * patterns, range:                      Ranges.
  12089. + * patterns, types of:                   Kinds of Patterns.
  12090. + * pipes for output:                     File/Pipe Redirection.
  12091. + * precedence:                           Precedence.
  12092. + * printing:                             Printing.
  12093. + * program file:                         Long.
  12094. + * program, awk:                         This Manual.
  12095. + * program, definition of:               Getting Started.
  12096. + * program, self contained:              Executable Scripts.
  12097. + * programs, documenting:                Comments.
  12098. + * quotient:                             Arithmetic Ops.
  12099. + * range pattern:                        Ranges.
  12100. + * reading files:                        Reading Files.
  12101. + * reading files, getline command:       Getline.
  12102. + * reading files, multiple line records: Multiple Line.
  12103. + * record separator:                     Records.
  12104. + * records, multiple line:               Multiple Line.
  12105. + * redirection of input:                 Getline.
  12106. + * redirection of output:                Redirection.
  12107. + * reference to array:                   Reference to Elements.
  12108. + * regexp:                               Regexp.
  12109. + * regexp as expression:                 Comparison Ops.
  12110. + * regexp operators:                     Comparison Ops.
  12111. + * regexp search operators:              Regexp Usage.
  12112. + * regular expression matching operators: Regexp Usage.
  12113. + * regular expression metacharacters:    Regexp Operators.
  12114. + * regular expressions as field separators: Field Separators.
  12115. + * regular expressions as patterns:      Regexp.
  12116. + * regular expressions, computed:        Regexp Usage.
  12117. + * relational operators:                 Comparison Ops.
  12118. + * relational operators:                 Comparison Patterns.
  12119. + * remainder:                            Arithmetic Ops.
  12120. + * removing elements of arrays:          Delete.
  12121. + * RLENGTH:                              String Functions.
  12122. + * RS:                                   Records.
  12123. + * RSTART:                               String Functions.
  12124. + * rule, definition of:                  Getting Started.
  12125. + * running awk programs:                 Running gawk.
  12126. + * running long programs:                Long.
  12127. + * sample input file:                    Sample Data Files.
  12128. + * scanning an array:                    Scanning an Array.
  12129. + * script, definition of:                Getting Started.
  12130. + * scripts, executable:                  Executable Scripts.
  12131. + * scripts, shell:                       Executable Scripts.
  12132. + * search path:                          AWKPATH Variable.
  12133. + * self contained programs:              Executable Scripts.
  12134. + * shell scripts:                        Executable Scripts.
  12135. + * side effect:                          Assignment Ops.
  12136. + * single quotes, why needed:            One-shot.
  12137. + * split:                                String Functions.
  12138. + * sprintf:                              String Functions.
  12139. + * standard error output:                Special Files.
  12140. + * standard input:                       Read Terminal.
  12141. + * standard input:                       Reading Files.
  12142. + * standard input:                       Special Files.
  12143. + * standard output:                      Special Files.
  12144. + * strftime:                             Time Functions.
  12145. + * string constants:                     Constants.
  12146. + * string operators:                     Concatenation.
  12147. + * string-matching operators:            Regexp Usage.
  12148. + * sub:                                  String Functions.
  12149. + * subscripts in arrays:                 Multi-dimensional.
  12150. + * SUBSEP:                               Multi-dimensional.
  12151. + * substr:                               String Functions.
  12152. + * subtraction:                          Arithmetic Ops.
  12153. + * system:                               I/O Functions.
  12154. + * systime:                              Time Functions.
  12155. + * time of day:                          Time Functions.
  12156. + * time stamps:                          Time Functions.
  12157. + * tolower:                              String Functions.
  12158. + * toupper:                              String Functions.
  12159. + * use of comments:                      Comments.
  12160. + * user-defined functions:               User-defined.
  12161. + * user-defined variables:               Variables.
  12162. + * uses of awk:                          Preface.
  12163. + * using this manual:                    This Manual.
  12164. + * uucp, anonymous:                      Extracting.
  12165. + * variables, user-defined:              Variables.
  12166. + * when to use awk:                      When.
  12167. + 
  12168. + 
  12169. diff -rc --new-file /src/baseline/gawk-2.15.5/gawk.texi gawk-2.15.5/gawk.texi
  12170. *** /src/baseline/gawk-2.15.5/gawk.texi    Thu May  6 13:37:11 1993
  12171. --- gawk-2.15.5/gawk.texi    Sun Jun 12 21:44:03 1994
  12172. ***************
  12173. *** 7567,7573 ****
  12174.   Here is the @code{awk} version of the @code{date} utility.
  12175.   
  12176.   @smallexample
  12177. ! #! /usr/bin/gawk -f
  12178.   #
  12179.   # date --- implement the P1003.2 Draft 11 'date' command
  12180.   #
  12181. --- 7567,7573 ----
  12182.   Here is the @code{awk} version of the @code{date} utility.
  12183.   
  12184.   @smallexample
  12185. ! #! /bin/gawk -f
  12186.   #
  12187.   # date --- implement the P1003.2 Draft 11 'date' command
  12188.   #
  12189. ***************
  12190. *** 8555,8561 ****
  12191.   separated by colons.  @code{gawk} gets its search path from the
  12192.   @code{AWKPATH} environment variable.  If that variable does not exist,
  12193.   @code{gawk} uses the default path, which is
  12194. ! @samp{.:/usr/lib/awk:/usr/local/lib/awk}.  (Programs written by
  12195.   system administrators should use an @code{AWKPATH} variable that
  12196.   does not include the current directory, @samp{.}.)@refill
  12197.   
  12198. --- 8555,8561 ----
  12199.   separated by colons.  @code{gawk} gets its search path from the
  12200.   @code{AWKPATH} environment variable.  If that variable does not exist,
  12201.   @code{gawk} uses the default path, which is
  12202. ! @samp{.:/local/lib/awk:/gnu/lib/awk}.  (Programs written by
  12203.   system administrators should use an @code{AWKPATH} variable that
  12204.   does not include the current directory, @samp{.}.)@refill
  12205.   
  12206. ***************
  12207. *** 9674,9680 ****
  12208.   The environment variable @code{AWKPATH} specifies a search path to use
  12209.   when finding source files named with the @samp{-f} option.  The default
  12210.   path, which is
  12211. ! @samp{.:/usr/lib/awk:/usr/local/lib/awk} is used if @code{AWKPATH} is not set.
  12212.   If a file name given to the @samp{-f} option contains a @samp{/} character,
  12213.   no path search is performed.
  12214.   @xref{AWKPATH Variable, ,The @code{AWKPATH} Environment Variable},
  12215. --- 9674,9680 ----
  12216.   The environment variable @code{AWKPATH} specifies a search path to use
  12217.   when finding source files named with the @samp{-f} option.  The default
  12218.   path, which is
  12219. ! @samp{.:/local/lib/awk:/gnu/lib/awk} is used if @code{AWKPATH} is not set.
  12220.   If a file name given to the @samp{-f} option contains a @samp{/} character,
  12221.   no path search is performed.
  12222.   @xref{AWKPATH Variable, ,The @code{AWKPATH} Environment Variable},
  12223. diff -rc --new-file /src/baseline/gawk-2.15.5/io.c gawk-2.15.5/io.c
  12224. *** /src/baseline/gawk-2.15.5/io.c    Wed May 11 22:50:41 1994
  12225. --- gawk-2.15.5/io.c    Sun Jun 12 21:44:08 1994
  12226. ***************
  12227. *** 556,563 ****
  12228. --- 556,565 ----
  12229.           status++;
  12230.       }
  12231.       if (fflush(stderr)) {
  12232. + #ifndef __amigados__  /* HACK (fnf) */
  12233.           warning("error writing standard error (%s).", strerror(errno));
  12234.           status++;
  12235. + #endif
  12236.       }
  12237.       for (rp = red_head; rp != NULL; rp = rp->next)
  12238.           /* flush both files and pipes, what the heck */
  12239. ***************
  12240. *** 598,605 ****
  12241. --- 600,609 ----
  12242.           status++;
  12243.       }
  12244.       if (fflush(stderr)) {
  12245. + #ifndef __amigados__  /* HACK (fnf) */
  12246.           warning("error writing standard error (%s).", strerror(errno));
  12247.           status++;
  12248. + #endif
  12249.       }
  12250.       return status;
  12251.   }
  12252. ***************
  12253. *** 909,915 ****
  12254.   wait_any(interesting)
  12255.   int interesting;    /* pid of interest, if any */
  12256.   {
  12257. !     SIGTYPE (*hstat)(), (*istat)(), (*qstat)();
  12258.       int pid;
  12259.       int status = 0;
  12260.       struct redirect *redp;
  12261. --- 913,919 ----
  12262.   wait_any(interesting)
  12263.   int interesting;    /* pid of interest, if any */
  12264.   {
  12265. !     RETSIGTYPE (*hstat)(), (*istat)(), (*qstat)();
  12266.       int pid;
  12267.       int status = 0;
  12268.       struct redirect *redp;
  12269. diff -rc --new-file /src/baseline/gawk-2.15.5/main.c gawk-2.15.5/main.c
  12270. *** /src/baseline/gawk-2.15.5/main.c    Sun May  1 18:38:49 1994
  12271. --- gawk-2.15.5/main.c    Sun Jun 12 21:44:12 1994
  12272. ***************
  12273. *** 33,39 ****
  12274.   static void init_args P((int argc0, int argc, char *argv0, char **argv));
  12275.   static void init_vars P((void));
  12276.   static void pre_assign P((char *v));
  12277. ! SIGTYPE catchsig P((int sig, int code));
  12278.   static void gawk_option P((char *optstr));
  12279.   static void nostalgia P((void));
  12280.   static void version P((void));
  12281. --- 33,39 ----
  12282.   static void init_args P((int argc0, int argc, char *argv0, char **argv));
  12283.   static void init_vars P((void));
  12284.   static void pre_assign P((char *v));
  12285. ! RETSIGTYPE catchsig P((int sig, int code));
  12286.   static void gawk_option P((char *optstr));
  12287.   static void nostalgia P((void));
  12288.   static void version P((void));
  12289. ***************
  12290. *** 148,157 ****
  12291.       setvbuf(stdout, NULL, _IOLBF, BUFSIZ);
  12292.   #endif
  12293.   
  12294. !     (void) signal(SIGFPE,  (SIGTYPE (*) P((int))) catchsig);
  12295. !     (void) signal(SIGSEGV, (SIGTYPE (*) P((int))) catchsig);
  12296.   #ifdef SIGBUS
  12297. !     (void) signal(SIGBUS,  (SIGTYPE (*) P((int))) catchsig);
  12298.   #endif
  12299.   
  12300.       myname = gawk_name(argv[0]);
  12301. --- 148,157 ----
  12302.       setvbuf(stdout, NULL, _IOLBF, BUFSIZ);
  12303.   #endif
  12304.   
  12305. !     (void) signal(SIGFPE,  (RETSIGTYPE (*) P((int))) catchsig);
  12306. !     (void) signal(SIGSEGV, (RETSIGTYPE (*) P((int))) catchsig);
  12307.   #ifdef SIGBUS
  12308. !     (void) signal(SIGBUS,  (RETSIGTYPE (*) P((int))) catchsig);
  12309.   #endif
  12310.   
  12311.       myname = gawk_name(argv[0]);
  12312. ***************
  12313. *** 628,634 ****
  12314.       }
  12315.   }
  12316.   
  12317. ! SIGTYPE
  12318.   catchsig(sig, code)
  12319.   int sig, code;
  12320.   {
  12321. --- 628,634 ----
  12322.       }
  12323.   }
  12324.   
  12325. ! RETSIGTYPE
  12326.   catchsig(sig, code)
  12327.   int sig, code;
  12328.   {
  12329. diff -rc --new-file /src/baseline/gawk-2.15.5/pc/config.h gawk-2.15.5/pc/config.h
  12330. *** /src/baseline/gawk-2.15.5/pc/config.h    Wed Dec 29 11:44:38 1993
  12331. --- gawk-2.15.5/pc/config.h    Sun Jun 12 21:44:14 1994
  12332. ***************
  12333. *** 258,264 ****
  12334.    * this.
  12335.    */
  12336.   
  12337. ! /* #define DEFPATH    ".:/usr/lib/awk:/usr/local/lib/awk" */
  12338.   /* #define ENVSEP    ':' */
  12339.   #define ENVSEP    ';'
  12340.   
  12341. --- 258,264 ----
  12342.    * this.
  12343.    */
  12344.   
  12345. ! /* #define DEFPATH    ".:/local/lib/awk:/gnu/lib/awk" */
  12346.   /* #define ENVSEP    ':' */
  12347.   #define ENVSEP    ';'
  12348.   
  12349. diff -rc --new-file /src/baseline/gawk-2.15.5/protos.h gawk-2.15.5/protos.h
  12350. *** /src/baseline/gawk-2.15.5/protos.h    Sun May  1 18:20:21 1994
  12351. --- gawk-2.15.5/protos.h    Sun Jun 12 22:08:10 1994
  12352. ***************
  12353. *** 69,75 ****
  12354. --- 69,77 ----
  12355.   extern int fprintf P((FILE *, const char *, ...));
  12356.   #if !defined(MSDOS) && !defined(__GNU_LIBRARY__)
  12357.   #ifdef __STDC__
  12358. + #ifndef __amigados__    /* HACK - conflicts with stdio.h - FIXME */
  12359.   extern size_t fwrite P((const aptr_t, size_t, size_t, FILE *));
  12360. + #endif
  12361.   #else
  12362.   extern int fwrite();
  12363.   #endif
  12364. ***************
  12365. *** 84,90 ****
  12366.   extern int isatty P((int));
  12367.   extern void exit P((int));
  12368.   extern int system P((const char *));
  12369. ! extern int sscanf P((const char *, const char *, ...));
  12370.   #ifndef toupper
  12371.   extern int toupper P((int));
  12372.   #endif
  12373. --- 86,92 ----
  12374.   extern int isatty P((int));
  12375.   extern void exit P((int));
  12376.   extern int system P((const char *));
  12377. ! /* extern int sscanf P((const char *, const char *, ...)); */
  12378.   #ifndef toupper
  12379.   extern int toupper P((int));
  12380.   #endif
  12381. diff -rc --new-file /src/baseline/gawk-2.15.5/test/Makefile gawk-2.15.5/test/Makefile
  12382. *** /src/baseline/gawk-2.15.5/test/Makefile    Tue May 10 22:57:41 1994
  12383. --- gawk-2.15.5/test/Makefile    Sun Jun 12 21:49:01 1994
  12384. ***************
  12385. *** 1,4 ****
  12386. --- 1,6 ----
  12387.   SHELL = /bin/sh
  12388. + #COMPARE = cmp
  12389. + COMPARE = diff
  12390.   
  12391.   bigtest:    basic poundbang gawk.extensions
  12392.   
  12393. ***************
  12394. *** 14,20 ****
  12395.   poundbang::
  12396.       cp ../gawk /tmp && chmod +x poundbang && ./poundbang poundbang >tmp
  12397.       rm -f /tmp/gawk
  12398. !     cmp poundbang.good tmp && rm -f tmp
  12399.   
  12400.   msg::
  12401.       @echo 'Any output from "cmp" is bad news, although some differences'
  12402. --- 16,22 ----
  12403.   poundbang::
  12404.       cp ../gawk /tmp && chmod +x poundbang && ./poundbang poundbang >tmp
  12405.       rm -f /tmp/gawk
  12406. !     -$(COMPARE) poundbang.good tmp && rm -f tmp
  12407.   
  12408.   msg::
  12409.       @echo 'Any output from "cmp" is bad news, although some differences'
  12410. ***************
  12411. *** 24,30 ****
  12412.   
  12413.   swaplns::
  12414.       @../gawk -f swaplns.awk data >tmp
  12415. !     cmp swaplns.good tmp && rm -f tmp
  12416.   
  12417.   messages::
  12418.       @../gawk -f messages.awk >out2 2>out3
  12419. --- 26,32 ----
  12420.   
  12421.   swaplns::
  12422.       @../gawk -f swaplns.awk data >tmp
  12423. !     -$(COMPARE) swaplns.good tmp && rm -f tmp
  12424.   
  12425.   messages::
  12426.       @../gawk -f messages.awk >out2 2>out3
  12427. ***************
  12428. *** 32,62 ****
  12429.   
  12430.   argarray::
  12431.       @TEST=test echo just a test | ../gawk -f argarray.awk argarray.awk - >tmp
  12432. !     cmp argarray.good tmp && rm -f tmp
  12433.   
  12434.   fstabplus::
  12435.       @echo '1        2' | ../gawk -f fstabplus >tmp
  12436. !     cmp fstabplus.good tmp && rm -f tmp
  12437.   
  12438.   fsrs::
  12439.       @../gawk -f fsrs.awk fsrs.in >tmp
  12440. !     cmp fsrs.good tmp && rm -f tmp
  12441.   
  12442.   igncfs::
  12443.       @../gawk -f igncfs.awk igncfs.in >tmp
  12444. !     cmp igncfs.good tmp && rm -f tmp
  12445.   
  12446.   longwrds::
  12447.       @../gawk -f longwrds.awk manpage | sort >tmp
  12448. !     cmp longwrds.good tmp && rm -f tmp
  12449.   
  12450.   fieldwdth::
  12451.       @echo '123456789' | ../gawk -v FIELDWIDTHS="2 3 4" '{ print $$2}' >tmp
  12452. !     cmp fieldwdth.good tmp && rm -f tmp
  12453.   
  12454.   ignrcase::
  12455.       @echo xYz | ../gawk -v IGNORECASE=1 '{ sub(/y/, ""); print}' >tmp
  12456. !     cmp ignrcase.good tmp && rm -f tmp
  12457.   
  12458.   regtest::
  12459.       @echo 'Some of the output from regtest is very system specific, do not'
  12460. --- 34,64 ----
  12461.   
  12462.   argarray::
  12463.       @TEST=test echo just a test | ../gawk -f argarray.awk argarray.awk - >tmp
  12464. !     -$(COMPARE) argarray.good tmp && rm -f tmp
  12465.   
  12466.   fstabplus::
  12467.       @echo '1        2' | ../gawk -f fstabplus >tmp
  12468. !     -$(COMPARE) fstabplus.good tmp && rm -f tmp
  12469.   
  12470.   fsrs::
  12471.       @../gawk -f fsrs.awk fsrs.in >tmp
  12472. !     -$(COMPARE) fsrs.good tmp && rm -f tmp
  12473.   
  12474.   igncfs::
  12475.       @../gawk -f igncfs.awk igncfs.in >tmp
  12476. !     -$(COMPARE) igncfs.good tmp && rm -f tmp
  12477.   
  12478.   longwrds::
  12479.       @../gawk -f longwrds.awk manpage | sort >tmp
  12480. !     -$(COMPARE) longwrds.good tmp && rm -f tmp
  12481.   
  12482.   fieldwdth::
  12483.       @echo '123456789' | ../gawk -v FIELDWIDTHS="2 3 4" '{ print $$2}' >tmp
  12484. !     -$(COMPARE) fieldwdth.good tmp && rm -f tmp
  12485.   
  12486.   ignrcase::
  12487.       @echo xYz | ../gawk -v IGNORECASE=1 '{ sub(/y/, ""); print}' >tmp
  12488. !     -$(COMPARE) ignrcase.good tmp && rm -f tmp
  12489.   
  12490.   regtest::
  12491.       @echo 'Some of the output from regtest is very system specific, do not'
  12492. ***************
  12493. *** 66,72 ****
  12494.   
  12495.   posix::
  12496.       @echo '1:2,3 4' | ../gawk -f posix >tmp
  12497. !     cmp posix.good tmp && rm -f tmp
  12498.   
  12499.   manyfiles::
  12500.       @rm -rf junk
  12501. --- 68,74 ----
  12502.   
  12503.   posix::
  12504.       @echo '1:2,3 4' | ../gawk -f posix >tmp
  12505. !     -$(COMPARE) posix.good tmp && rm -f tmp
  12506.   
  12507.   manyfiles::
  12508.       @rm -rf junk
  12509. ***************
  12510. *** 79,106 ****
  12511.   
  12512.   compare::
  12513.       @../gawk -f compare.awk 0 1 compare.in >tmp
  12514. !     cmp compare.good tmp && rm -f tmp
  12515.   
  12516.   arrayref::
  12517.       @../gawk -f arrayref >tmp
  12518. !     cmp arrayref.good tmp && rm -f tmp
  12519.   
  12520.   rs::
  12521.       @../gawk -v RS="" '{ print $$1, $$2}' rs.data >tmp
  12522. !     cmp rs.good tmp && rm -f tmp
  12523.   
  12524.   fsbs::
  12525.       @../gawk -v FS='\' '{ print $$1, $$2 }' fsbs.in >tmp
  12526. !     cmp fsbs.good tmp && rm -f tmp
  12527.   
  12528.   inftest::
  12529.       @echo This test is very machine specific...
  12530.       @../gawk -f inftest.awk >tmp
  12531. !     cmp inftest.good tmp && rm -f tmp
  12532.   
  12533.   getline::
  12534.       @../gawk -f getline.awk getline.awk getline.awk >tmp
  12535. !     cmp getline.good tmp && rm -f tmp
  12536.   
  12537.   rand::
  12538.       @echo The following line should just be 19 random numbers between 1 and 100
  12539. --- 81,108 ----
  12540.   
  12541.   compare::
  12542.       @../gawk -f compare.awk 0 1 compare.in >tmp
  12543. !     -$(COMPARE) compare.good tmp && rm -f tmp
  12544.   
  12545.   arrayref::
  12546.       @../gawk -f arrayref >tmp
  12547. !     -$(COMPARE) arrayref.good tmp && rm -f tmp
  12548.   
  12549.   rs::
  12550.       @../gawk -v RS="" '{ print $$1, $$2}' rs.data >tmp
  12551. !     -$(COMPARE) rs.good tmp && rm -f tmp
  12552.   
  12553.   fsbs::
  12554.       @../gawk -v FS='\' '{ print $$1, $$2 }' fsbs.in >tmp
  12555. !     -$(COMPARE) fsbs.good tmp && rm -f tmp
  12556.   
  12557.   inftest::
  12558.       @echo This test is very machine specific...
  12559.       @../gawk -f inftest.awk >tmp
  12560. !     -$(COMPARE) inftest.good tmp && rm -f tmp
  12561.   
  12562.   getline::
  12563.       @../gawk -f getline.awk getline.awk getline.awk >tmp
  12564. !     -$(COMPARE) getline.good tmp && rm -f tmp
  12565.   
  12566.   rand::
  12567.       @echo The following line should just be 19 random numbers between 1 and 100
  12568. ***************
  12569. *** 123,130 ****
  12570.       cmp splitargv.good tmp && rm -f tmp
  12571.   
  12572.   awkpath::
  12573. !     @AWKPATH=".:lib" ../gawk -f awkpath.awk >tmp
  12574. !     cmp awkpath.good tmp && rm -f tmp
  12575.   
  12576.   nfset::
  12577.       @../gawk -f nfset.awk nfset.in >tmp
  12578. --- 125,132 ----
  12579.       cmp splitargv.good tmp && rm -f tmp
  12580.   
  12581.   awkpath::
  12582. ! #    @AWKPATH=".:lib" ../gawk -f awkpath.awk >tmp
  12583. ! #    cmp awkpath.good tmp && rm -f tmp
  12584.   
  12585.   nfset::
  12586.       @../gawk -f nfset.awk nfset.in >tmp
  12587. diff -rc --new-file /src/baseline/gawk-2.15.5/test/poundbang gawk-2.15.5/test/poundbang
  12588. *** /src/baseline/gawk-2.15.5/test/poundbang    Tue Oct 19 20:07:58 1993
  12589. --- gawk-2.15.5/test/poundbang    Sun Jun 12 21:44:24 1994
  12590. ***************
  12591. *** 1,3 ****
  12592. ! #! /tmp/gawk -f 
  12593.       { ccount += length($0) }
  12594.   END { printf "average line length is %2.4f\n", ccount/NR}
  12595. --- 1,3 ----
  12596. ! #!/tmp/gawk -f 
  12597.       { ccount += length($0) }
  12598.   END { printf "average line length is %2.4f\n", ccount/NR}
  12599.