Annotation of src/usr.bin/awk/README.md, Revision 1.9
1.9 ! millert 1: # OpenBSD Awk
1.1 millert 2:
1.9 ! millert 3: This is a fork of The One True Awk, as shipped with OpenBSD. It
! 4: includes changes not present in the upstream version because they
! 5: are OpenBSD-specific, are still open PRs, or were rejected by the
! 6: upstream maintainer. This version of `awk` relies on APIs that are
! 7: not present in some other systems, such as `asprintf`, `pledge`,
! 8: `reallocarray`, `srandom_deterministic` and `strlcpy`.
! 9:
! 10: ## What is upstream? ##
! 11:
! 12: Upstream is the bsd-features branch of https://github.com/onetrueawk/awk.
1.1 millert 13:
14: This is the version of `awk` described in _The AWK Programming Language_,
1.7 millert 15: Second Edition, by Al Aho, Brian Kernighan, and Peter Weinberger
16: (Addison-Wesley, 2024, ISBN-13 978-0138269722, ISBN-10 0138269726).
17:
18: ## What's New? ##
19:
20: This version of Awk handles UTF-8 and comma-separated values (CSV) input.
21:
22: ### Strings ###
23:
24: Functions that process strings now count Unicode code points, not bytes;
25: this affects `length`, `substr`, `index`, `match`, `split`,
26: `sub`, `gsub`, and others. Note that code
27: points are not necessarily characters.
28:
29: UTF-8 sequences may appear in literal strings and regular expressions.
30: Aribtrary characters may be included with `\u` followed by 1 to 8 hexadecimal digits.
31:
32: ### Regular expressions ###
33:
34: Regular expressions may include UTF-8 code points, including `\u`.
35: Character classes are likely to be limited to about 256 characters
36: when expanded.
37:
38: ### CSV ###
39:
40: The option `--csv` turns on CSV processing of input:
41: fields are separated by commas, fields may be quoted with
1.8 millert 42: double-quote (`"`) characters, quoted fields may contain embedded newlines.
1.7 millert 43: In CSV mode, `FS` is ignored.
44:
45: If no explicit separator argument is provided,
46: field-splitting in `split` is determined by CSV mode.
1.1 millert 47:
48: ## Copyright
49:
50: Copyright (C) Lucent Technologies 1997<br/>
51: All Rights Reserved
52:
53: Permission to use, copy, modify, and distribute this software and
54: its documentation for any purpose and without fee is hereby
55: granted, provided that the above copyright notice appear in all
56: copies and that both that the copyright notice and this
57: permission notice and warranty disclaimer appear in supporting
58: documentation, and that the name Lucent Technologies or any of
59: its entities not be used in advertising or publicity pertaining
60: to distribution of the software without specific, written prior
61: permission.
62:
63: LUCENT DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
64: INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS.
65: IN NO EVENT SHALL LUCENT OR ANY OF ITS ENTITIES BE LIABLE FOR ANY
66: SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
67: WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER
68: IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
69: ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
70: THIS SOFTWARE.
71:
72: ## Distribution and Reporting Problems
73:
74: Changes, mostly bug fixes and occasional enhancements, are listed
75: in `FIXES`. If you distribute this code further, please please please
76: distribute `FIXES` with it.
77:
1.9 ! millert 78: If you find errors, please report them to bugs@openbsd.org rather
! 79: than the upstream maintainer unless you can also reproduce the
! 80: problem with an unmodified version of the upstream awk.
! 81:
! 82: ## Submitting Patches
! 83:
! 84: Patches may be submitted to the tech@openbsd.org mailing list, or
! 85: bugs@openbsd.org if you are fixing a bug.
1.1 millert 86:
87: ## Building
88:
89: The program itself is created by
90:
91: make
92:
93: which should produce a sequence of messages roughly like this:
94:
1.7 millert 95: bison -d awkgram.y
96: awkgram.y: warning: 44 shift/reduce conflicts [-Wconflicts-sr]
97: awkgram.y: warning: 85 reduce/reduce conflicts [-Wconflicts-rr]
98: awkgram.y: note: rerun with option '-Wcounterexamples' to generate conflict counterexamples
99: gcc -g -Wall -pedantic -Wcast-qual -O2 -c -o awkgram.tab.o awkgram.tab.c
100: gcc -g -Wall -pedantic -Wcast-qual -O2 -c -o b.o b.c
101: gcc -g -Wall -pedantic -Wcast-qual -O2 -c -o main.o main.c
102: gcc -g -Wall -pedantic -Wcast-qual -O2 -c -o parse.o parse.c
103: gcc -g -Wall -pedantic -Wcast-qual -O2 maketab.c -o maketab
104: ./maketab awkgram.tab.h >proctab.c
105: gcc -g -Wall -pedantic -Wcast-qual -O2 -c -o proctab.o proctab.c
106: gcc -g -Wall -pedantic -Wcast-qual -O2 -c -o tran.o tran.c
107: gcc -g -Wall -pedantic -Wcast-qual -O2 -c -o lib.o lib.c
108: gcc -g -Wall -pedantic -Wcast-qual -O2 -c -o run.o run.c
109: gcc -g -Wall -pedantic -Wcast-qual -O2 -c -o lex.o lex.c
110: gcc -g -Wall -pedantic -Wcast-qual -O2 awkgram.tab.o b.o main.o parse.o proctab.o tran.o lib.o run.o lex.o -lm
1.1 millert 111:
112: This produces an executable `a.out`; you will eventually want to
113: move this to some place like `/usr/bin/awk`.
114:
115: If your system does not have `yacc` or `bison` (the GNU
116: equivalent), you need to install one of them first.
117:
1.6 millert 118: NOTE: This version uses ISO/IEC C99, as you should also. We have
1.1 millert 119: compiled this without any changes using `gcc -Wall` and/or local C
120: compilers on a variety of systems, but new systems or compilers
121: may raise some new complaint; reports of difficulties are
122: welcome.
123:
124: This compiles without change on Macintosh OS X using `gcc` and
125: the standard developer tools.
126:
1.4 millert 127: You can also use `make CC=g++` to build with the GNU C++ compiler,
128: should you choose to do so.
129:
1.5 millert 130: ## A Note About Releases
131:
1.7 millert 132: We don't usually do releases.
1.5 millert 133:
1.1 millert 134: #### Last Updated
1.4 millert 135:
1.9 ! millert 136: Mon 30 Oct 2023 12:53:07 MDT