Debian Codegraph @

upstream/opensuse-tumbleweed/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 "June 01 2025" "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 .PP
165 .I pm-gawk
166 produces a warning if the current version of
167 .I gawk
168 doesn't match the one that was first used with a particular
169 backing storage file.
170 .SH BUG REPORTS
171 Follow the procedures in \*(EP and in \*(PM.
172 For suspected
173 bugs related to persistence (as opposed to other
174 non-persistence-related
175 .I gawk
176 bugs) please also send
177 e-mail to Terence Kelly at one or more of these addresses:
178 \f([email protected]\fP,
179 \f([email protected]\fP,
180 or
181 \f([email protected]\fP.
182 .SH SEE ALSO
183 .IR gawk (1),
184 \*(EP,
185 and
186 \*(PM.
187 The two manuals should be available in the Info subsystem
188 if Info installed on your system.
189 .PP
190 See \f(CWhttps://web.eecs.umich.edu/~tpkelly/pma/\fP for
191 the latest source code and manual.
192 .SH COPYING PERMISSIONS
193 Copyright \(co 2022
194 Terence Kelly.
195 .PP
196 Permission is granted to make and distribute verbatim copies of
197 this manual page provided the copyright notice and this permission
198 notice are preserved on all copies.
199 .ig
200 Permission is granted to process this file through troff and print the
201 results, provided the printed document carries copying permission
202 notice identical to this one except for the removal of this paragraph
203 (this paragraph not being relevant to the printed manual page).
204 ..
205 .PP
206 Permission is granted to copy and distribute modified versions of this
207 manual page under the conditions for verbatim copying, provided that
208 the entire resulting derived work is distributed under the terms of a
209 permission notice identical to this one.
210 .PP
211 Permission is granted to copy and distribute translations of this
212 manual page into another language, under the above conditions for
213 modified versions, except that this permission notice may be stated in
214 a translation approved by the Foundation.