| 1 |
.ds EP \fIGAWK: Effective AWK Programming\fP |
| 2 |
.ds PM \fIPersistent Memory gawk User Manual\fP |
| 3 |
.TH PM-GAWK 1 "Nov 17 2022" "Free Software Foundation" "Utility Commands" |
| 4 |
.SH NAME |
| 5 |
persistent memory gawk \- persistent data and functions |
| 6 |
.SH SYNOPSIS |
| 7 |
.ft CW |
| 8 |
.nf |
| 9 |
truncate -s \f(CIsize\fP heap.pma |
| 10 |
export GAWK_PERSIST_FILE=heap.pma |
| 11 |
gawk .\^.\^. |
| 12 |
.sp |
| 13 |
truncate -s \f(CIsize\fP heap.pma |
| 14 |
GAWK_PERSIST_FILE=heap.pma gawk .\^.\^. |
| 15 |
.sp |
| 16 |
truncate -s \f(CIsize\fP heap.pma |
| 17 |
alias pm='GAWK_PERSIST_FILE=heap.pma' |
| 18 |
pm gawk .\^.\^. # succinct |
| 19 |
.sp |
| 20 |
unset GAWK_PERSIST_FILE # disable persistence |
| 21 |
.sp |
| 22 |
export GAWK_PERSIST_FILE=other_heap.pma # change heap |
| 23 |
.sp |
| 24 |
rm heap.pma # delete heap |
| 25 |
.fi |
| 26 |
.ft R |
| 27 |
.SH DESCRIPTION |
| 28 |
.PP |
| 29 |
.I Gawk |
| 30 |
5.2 and later supports a persistent memory feature that |
| 31 |
can store script-defined variables and functions in a |
| 32 |
file for later use. The feature, called |
| 33 |
.IR pm-gawk , |
| 34 |
is described in \*(EP and in \*(PM. |
| 35 |
.PP |
| 36 |
.I pm-gawk |
| 37 |
is activated by passing to |
| 38 |
.I gawk |
| 39 |
the name of an initially empty |
| 40 |
(all-zero-bytes) |
| 41 |
.IR "heap file" , |
| 42 |
via the environment variable |
| 43 |
\f(CWGAWK_PERSIST_FILE\fP. |
| 44 |
.I pm-gawk |
| 45 |
retains script-defined variables and functions in the heap file for |
| 46 |
use in subsequent |
| 47 |
.I gawk |
| 48 |
invocations. |
| 49 |
.PP |
| 50 |
.I pm-gawk |
| 51 |
offers at least two advantages compared with the existing \f(CWrwarray\fP |
| 52 |
extension: it offers constant-time (``O(1) time'') access to individual |
| 53 |
elements of persistent associative arrays, and it can store script-defined |
| 54 |
functions in addition to variables. |
| 55 |
.SH EXAMPLES |
| 56 |
.PP |
| 57 |
Demonstrate persistent variables: |
| 58 |
.sp .5 |
| 59 |
.RS |
| 60 |
.nf |
| 61 |
.ft CW |
| 62 |
$ \f(CBtruncate -s 1G heap.pma\fP # create heap file |
| 63 |
$ \f(CBexport GAWK_PERSIST_FILE=heap.pma\fP # "ambient" env var |
| 64 |
$ \f(CBgawk 'BEGIN { print ++i }'\fP |
| 65 |
1 |
| 66 |
$ \f(CBgawk 'BEGIN { print ++i }'\fP |
| 67 |
2 |
| 68 |
$ \f(CBgawk 'BEGIN { print ++i }'\fP |
| 69 |
3 |
| 70 |
.ft R |
| 71 |
.fi |
| 72 |
.RE |
| 73 |
.PP |
| 74 |
To pass the environment variable on per-command basis: |
| 75 |
.sp .5 |
| 76 |
.RS |
| 77 |
.nf |
| 78 |
.ft CW |
| 79 |
$ \f(CBunset GAWK_PERSIST_FILE\fP |
| 80 |
$ \f(CBGAWK_PERSIST_FILE=heap.pma gawk 'BEGIN { print ++i }'\fP |
| 81 |
4 |
| 82 |
$ \f(CBGAWK_PERSIST_FILE=heap.pma gawk 'BEGIN { print ++i }'\fP |
| 83 |
5 |
| 84 |
$ \f(CBGAWK_PERSIST_FILE=heap.pma gawk 'BEGIN { print ++i }'\fP |
| 85 |
6 |
| 86 |
.ft R |
| 87 |
.fi |
| 88 |
.RE |
| 89 |
.PP |
| 90 |
To reduce visual clutter of per-command environment variable passing: |
| 91 |
.sp .5 |
| 92 |
.RS |
| 93 |
.nf |
| 94 |
.ft CW |
| 95 |
$ \f(CBalias pm='GAWK_PERSIST_FILE=heap.pma'\fP |
| 96 |
$ \f(CBpm gawk 'BEGIN { print ++i }'\fP |
| 97 |
7 |
| 98 |
$ \f(CBpm gawk 'BEGIN { print ++i }'\fP |
| 99 |
8 |
| 100 |
.ft R |
| 101 |
.fi |
| 102 |
.RE |
| 103 |
.PP |
| 104 |
To refrain from activating persistence: |
| 105 |
.sp .5 |
| 106 |
.RS |
| 107 |
.nf |
| 108 |
.ft CW |
| 109 |
$ \f(CBunset GAWK_PERSIST_FILE\fP |
| 110 |
$ \f(CBgawk 'BEGIN { print ++i }'\fP |
| 111 |
1 |
| 112 |
$ \f(CBgawk 'BEGIN { print ++i }'\fP |
| 113 |
1 |
| 114 |
.ft R |
| 115 |
.fi |
| 116 |
.RE |
| 117 |
.PP |
| 118 |
To permanently ``forget'' the contents of the heap file: |
| 119 |
.sp .5 |
| 120 |
.RS |
| 121 |
.nf |
| 122 |
.ft CW |
| 123 |
$ \f(CBrm heap.pma\fP |
| 124 |
.ft R |
| 125 |
.fi |
| 126 |
.RE |
| 127 |
.PP |
| 128 |
.SH ENVIRONMENT VARIABLES |
| 129 |
.PP |
| 130 |
\f(CWGAWK_PERSIST_FILE\fP contains the name of a heap file where |
| 131 |
script-defined variables and functions are stored. If this environment |
| 132 |
variable is not visible to |
| 133 |
.IR gawk , |
| 134 |
the |
| 135 |
persistence feature is not activated and |
| 136 |
.I gawk |
| 137 |
behaves in |
| 138 |
its traditional manner. |
| 139 |
.SH VERSION INFORMATION |
| 140 |
.PP |
| 141 |
Persistent memory |
| 142 |
.I gawk |
| 143 |
was first released in |
| 144 |
.I gawk |
| 145 |
5.2. |
| 146 |
.SH AUTHORS |
| 147 |
Arnold Robbins, the maintainer of |
| 148 |
.IR gawk , |
| 149 |
implemented |
| 150 |
.I pm-gawk |
| 151 |
using a persistent memory allocator (pma) provided by |
| 152 |
Terence Kelly. An earlier proof-of-concept prototype |
| 153 |
of persistent |
| 154 |
.I gawk |
| 155 |
was developed by Haris Volos, Zi Fan |
| 156 |
Tan, and Jianan Li using a fork of the official |
| 157 |
.I gawk |
| 158 |
sources. |
| 159 |
.SH CAVEATS |
| 160 |
The GNU/Linux CIFS filesystem is known to cause problems |
| 161 |
for the persistent memory allocator. Do not use a backing file |
| 162 |
on such a filesystem with |
| 163 |
.IR pm-gawk . |
| 164 |
.SH BUG REPORTS |
| 165 |
Follow the procedures in \*(EP and in \*(PM. |
| 166 |
For suspected |
| 167 |
bugs related to persistence (as opposed to other |
| 168 |
non-persistence-related |
| 169 |
.I gawk |
| 170 |
bugs) please also send |
| 171 |
e-mail to Terence Kelly at one or more of these addresses: |
| 172 |
\f([email protected]\fP, |
| 173 |
\f([email protected]\fP, |
| 174 |
or |
| 175 |
\f([email protected]\fP. |
| 176 |
.SH SEE ALSO |
| 177 |
.IR gawk (1), |
| 178 |
\*(EP, |
| 179 |
and |
| 180 |
\*(PM. |
| 181 |
The two manuals should be available in the Info subsystem |
| 182 |
if Info installed on your system. |
| 183 |
.PP |
| 184 |
See \f(CWhttps://web.eecs.umich.edu/~tpkelly/pma/\fP for |
| 185 |
the latest source code and manual. |
| 186 |
.SH COPYING PERMISSIONS |
| 187 |
Copyright \(co 2022 |
| 188 |
Terence Kelly. |
| 189 |
.PP |
| 190 |
Permission is granted to make and distribute verbatim copies of |
| 191 |
this manual page provided the copyright notice and this permission |
| 192 |
notice are preserved on all copies. |
| 193 |
.ig |
| 194 |
Permission is granted to process this file through troff and print the |
| 195 |
results, provided the printed document carries copying permission |
| 196 |
notice identical to this one except for the removal of this paragraph |
| 197 |
(this paragraph not being relevant to the printed manual page). |
| 198 |
.. |
| 199 |
.PP |
| 200 |
Permission is granted to copy and distribute modified versions of this |
| 201 |
manual page under the conditions for verbatim copying, provided that |
| 202 |
the entire resulting derived work is distributed under the terms of a |
| 203 |
permission notice identical to this one. |
| 204 |
.PP |
| 205 |
Permission is granted to copy and distribute translations of this |
| 206 |
manual page into another language, under the above conditions for |
| 207 |
modified versions, except that this permission notice may be stated in |
| 208 |
a translation approved by the Foundation. |