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