Annotation of src/usr.bin/awk/README.md, Revision 1.10
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:
36: ### CSV ###
37:
38: The option `--csv` turns on CSV processing of input:
39: fields are separated by commas, fields may be quoted with
1.8 millert 40: double-quote (`"`) characters, quoted fields may contain embedded newlines.
1.7 millert 41: In CSV mode, `FS` is ignored.
42:
43: If no explicit separator argument is provided,
44: field-splitting in `split` is determined by CSV mode.
1.1 millert 45:
46: ## Copyright
47:
48: Copyright (C) Lucent Technologies 1997<br/>
49: All Rights Reserved
50:
51: Permission to use, copy, modify, and distribute this software and
52: its documentation for any purpose and without fee is hereby
53: granted, provided that the above copyright notice appear in all
54: copies and that both that the copyright notice and this
55: permission notice and warranty disclaimer appear in supporting
56: documentation, and that the name Lucent Technologies or any of
57: its entities not be used in advertising or publicity pertaining
58: to distribution of the software without specific, written prior
59: permission.
60:
61: LUCENT DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
62: INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS.
63: IN NO EVENT SHALL LUCENT OR ANY OF ITS ENTITIES BE LIABLE FOR ANY
64: SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
65: WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER
66: IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
67: ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
68: THIS SOFTWARE.
69:
70: ## Distribution and Reporting Problems
71:
72: Changes, mostly bug fixes and occasional enhancements, are listed
73: in `FIXES`. If you distribute this code further, please please please
74: distribute `FIXES` with it.
75:
1.9 millert 76: If you find errors, please report them to bugs@openbsd.org rather
77: than the upstream maintainer unless you can also reproduce the
78: problem with an unmodified version of the upstream awk.
79:
80: ## Submitting Patches
81:
82: Patches may be submitted to the tech@openbsd.org mailing list, or
83: bugs@openbsd.org if you are fixing a bug.
1.1 millert 84:
85: ## Building
86:
87: The program itself is created by
88:
89: make
90:
91: which should produce a sequence of messages roughly like this:
92:
1.7 millert 93: bison -d awkgram.y
94: awkgram.y: warning: 44 shift/reduce conflicts [-Wconflicts-sr]
95: awkgram.y: warning: 85 reduce/reduce conflicts [-Wconflicts-rr]
96: awkgram.y: note: rerun with option '-Wcounterexamples' to generate conflict counterexamples
97: gcc -g -Wall -pedantic -Wcast-qual -O2 -c -o awkgram.tab.o awkgram.tab.c
98: gcc -g -Wall -pedantic -Wcast-qual -O2 -c -o b.o b.c
99: gcc -g -Wall -pedantic -Wcast-qual -O2 -c -o main.o main.c
100: gcc -g -Wall -pedantic -Wcast-qual -O2 -c -o parse.o parse.c
101: gcc -g -Wall -pedantic -Wcast-qual -O2 maketab.c -o maketab
102: ./maketab awkgram.tab.h >proctab.c
103: gcc -g -Wall -pedantic -Wcast-qual -O2 -c -o proctab.o proctab.c
104: gcc -g -Wall -pedantic -Wcast-qual -O2 -c -o tran.o tran.c
105: gcc -g -Wall -pedantic -Wcast-qual -O2 -c -o lib.o lib.c
106: gcc -g -Wall -pedantic -Wcast-qual -O2 -c -o run.o run.c
107: gcc -g -Wall -pedantic -Wcast-qual -O2 -c -o lex.o lex.c
108: 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 109:
110: This produces an executable `a.out`; you will eventually want to
111: move this to some place like `/usr/bin/awk`.
112:
113: If your system does not have `yacc` or `bison` (the GNU
114: equivalent), you need to install one of them first.
115:
1.6 millert 116: NOTE: This version uses ISO/IEC C99, as you should also. We have
1.1 millert 117: compiled this without any changes using `gcc -Wall` and/or local C
118: compilers on a variety of systems, but new systems or compilers
119: may raise some new complaint; reports of difficulties are
120: welcome.
121:
122: This compiles without change on Macintosh OS X using `gcc` and
123: the standard developer tools.
124:
1.4 millert 125: You can also use `make CC=g++` to build with the GNU C++ compiler,
126: should you choose to do so.
127:
1.5 millert 128: ## A Note About Releases
129:
1.7 millert 130: We don't usually do releases.
1.5 millert 131:
1.1 millert 132: #### Last Updated
1.4 millert 133:
1.9 millert 134: Mon 30 Oct 2023 12:53:07 MDT