Debian Codegraph @

upstream/debian-unstable/man1/pm-gawk.1

raw
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.