204 lines
4.9 KiB
Groff
204 lines
4.9 KiB
Groff
|
.ds EP \fIGAWK: Effective AWK Programming\fP
|
||
|
|
.ds PM \fIPersistent Memory gawk User Manual\fP
|
||
|
|
.TH PM-GAWK 1 "Aug 14 2022" "Free Software Foundation" "Utility Commands"
|
||
|
|
.SH NAME
|
||
|
|
persistent memory gawk \- persistent data and functions
|
||
|
|
.SH SYNOPSIS
|
||
|
|
.ft CW
|
||
|
|
.nf
|
||
|
|
truncate -s \f(CIsize\fP heap.pma
|
||
|
|
export GAWK_PERSIST_FILE=heap.pma
|
||
|
|
gawk .\^.\^.
|
||
|
|
.sp
|
||
|
|
truncate -s \f(CIsize\fP heap.pma
|
||
|
|
GAWK_PERSIST_FILE=heap.pma gawk .\^.\^.
|
||
|
|
.sp
|
||
|
|
truncate -s \f(CIsize\fP heap.pma
|
||
|
|
alias pm='GAWK_PERSIST_FILE=heap.pma'
|
||
|
|
pm gawk .\^.\^. # succinct
|
||
|
|
.sp
|
||
|
|
unset GAWK_PERSIST_FILE # disable persistence
|
||
|
|
.sp
|
||
|
|
export GAWK_PERSIST_FILE=other_heap.pma # change heap
|
||
|
|
.sp
|
||
|
|
rm heap.pma # delete heap
|
||
|
|
.fi
|
||
|
|
.ft R
|
||
|
|
.SH DESCRIPTION
|
||
|
|
.PP
|
||
|
|
.I Gawk
|
||
|
|
5.2 and later supports a persistent memory feature that
|
||
|
|
can store script-defined variables and functions in a
|
||
|
|
file for later use. The feature, called
|
||
|
|
.IR pm-gawk ,
|
||
|
|
is described in \*(EP and in \*(PM.
|
||
|
|
.PP
|
||
|
|
.I pm-gawk
|
||
|
|
is activated by passing to
|
||
|
|
.I gawk
|
||
|
|
the name of an initially empty
|
||
|
|
(all-zero-bytes)
|
||
|
|
.IR "heap file" ,
|
||
|
|
via the environment variable
|
||
|
|
\f(CWGAWK_PERSIST_FILE\fP.
|
||
|
|
.I pm-gawk
|
||
|
|
retains script-defined variables and functions in the heap file for
|
||
|
|
use in subsequent
|
||
|
|
.I gawk
|
||
|
|
invocations.
|
||
|
|
.PP
|
||
|
|
.I pm-gawk
|
||
|
|
offers at least two advantages compared with the existing \f(CWrwarray\fP
|
||
|
|
extension: it offers constant-time (``O(1) time'') access to individual
|
||
|
|
elements of persistent associative arrays, and it can store script-defined
|
||
|
|
functions in addition to variables.
|
||
|
|
.SH EXAMPLES
|
||
|
|
.PP
|
||
|
|
Demonstrate persistent variables:
|
||
|
|
.sp .5
|
||
|
|
.RS
|
||
|
|
.nf
|
||
|
|
.ft CW
|
||
|
|
$ \f(CBtruncate -s 1G heap.pma\fP # create heap file
|
||
|
|
$ \f(CBexport GAWK_PERSIST_FILE=heap.pma\fP # "ambient" env var
|
||
|
|
$ \f(CBgawk 'BEGIN { print ++i }'\fP
|
||
|
|
1
|
||
|
|
$ \f(CBgawk 'BEGIN { print ++i }'\fP
|
||
|
|
2
|
||
|
|
$ \f(CBgawk 'BEGIN { print ++i }'\fP
|
||
|
|
3
|
||
|
|
.ft R
|
||
|
|
.fi
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
To pass the environment variable on per-command basis:
|
||
|
|
.sp .5
|
||
|
|
.RS
|
||
|
|
.nf
|
||
|
|
.ft CW
|
||
|
|
$ \f(CBunset GAWK_PERSIST_FILE\fP
|
||
|
|
$ \f(CBGAWK_PERSIST_FILE=heap.pma gawk 'BEGIN { print ++i }'\fP
|
||
|
|
4
|
||
|
|
$ \f(CBGAWK_PERSIST_FILE=heap.pma gawk 'BEGIN { print ++i }'\fP
|
||
|
|
5
|
||
|
|
$ \f(CBGAWK_PERSIST_FILE=heap.pma gawk 'BEGIN { print ++i }'\fP
|
||
|
|
6
|
||
|
|
.ft R
|
||
|
|
.fi
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
To reduce visual clutter of per-command environment variable passing:
|
||
|
|
.sp .5
|
||
|
|
.RS
|
||
|
|
.nf
|
||
|
|
.ft CW
|
||
|
|
$ \f(CBalias pm='GAWK_PERSIST_FILE=heap.pma'\fP
|
||
|
|
$ \f(CBpm gawk 'BEGIN { print ++i }'\fP
|
||
|
|
7
|
||
|
|
$ \f(CBpm gawk 'BEGIN { print ++i }'\fP
|
||
|
|
8
|
||
|
|
.ft R
|
||
|
|
.fi
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
To refrain from activating persistence:
|
||
|
|
.sp .5
|
||
|
|
.RS
|
||
|
|
.nf
|
||
|
|
.ft CW
|
||
|
|
$ \f(CBunset GAWK_PERSIST_FILE\fP
|
||
|
|
$ \f(CBgawk 'BEGIN { print ++i }'\fP
|
||
|
|
1
|
||
|
|
$ \f(CBgawk 'BEGIN { print ++i }'\fP
|
||
|
|
1
|
||
|
|
.ft R
|
||
|
|
.fi
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
To permanently ``forget'' the contents of the heap file:
|
||
|
|
.sp .5
|
||
|
|
.RS
|
||
|
|
.nf
|
||
|
|
.ft CW
|
||
|
|
$ \f(CBrm heap.pma\fP
|
||
|
|
.ft R
|
||
|
|
.fi
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
.SH ENVIRONMENT VARIABLES
|
||
|
|
.PP
|
||
|
|
\f(CWGAWK_PERSIST_FILE\fP contains the name of a heap file where
|
||
|
|
script-defined variables and functions are stored. If this environment
|
||
|
|
variable is not visible to
|
||
|
|
.IR gawk ,
|
||
|
|
the
|
||
|
|
persistence feature is not activated and
|
||
|
|
.I gawk
|
||
|
|
behaves in
|
||
|
|
its traditional manner.
|
||
|
|
.SH VERSION INFORMATION
|
||
|
|
.PP
|
||
|
|
Persistent memory
|
||
|
|
.I gawk
|
||
|
|
was first released in
|
||
|
|
.I gawk
|
||
|
|
5.2.
|
||
|
|
.SH AUTHORS
|
||
|
|
Arnold Robbins, the maintainer of
|
||
|
|
.IR gawk ,
|
||
|
|
implemented
|
||
|
|
.I pm-gawk
|
||
|
|
using a persistent memory allocator (pma) provided by
|
||
|
|
Terence Kelly. An earlier proof-of-concept prototype
|
||
|
|
of persistent
|
||
|
|
.I gawk
|
||
|
|
was developed by Haris Volos, Zi Fan
|
||
|
|
Tan, and Jianan Li using a fork of the official
|
||
|
|
.I gawk
|
||
|
|
sources.
|
||
|
|
.SH BUG REPORTS
|
||
|
|
Follow the procedures in \*(EP and in \*(PM.
|
||
|
|
For suspected
|
||
|
|
bugs related to persistence (as opposed to other
|
||
|
|
non-persistence-related
|
||
|
|
.I gawk
|
||
|
|
bugs) please also send
|
||
|
|
e-mail to Terence Kelly at one or more of these addresses:
|
||
|
|
\f(CWtpkelly@acm.org\fP,
|
||
|
|
\f(CWtpkelly@eecs.umich.edu\fP,
|
||
|
|
or
|
||
|
|
\f(CWtpkelly@cs.princeton.edu\fP.
|
||
|
|
.SH SEE ALSO
|
||
|
|
.IR gawk (1),
|
||
|
|
\*(EP,
|
||
|
|
and
|
||
|
|
\*(PM.
|
||
|
|
The two manuals should be available in the Info subsystem
|
||
|
|
if Info installed on your system.
|
||
|
|
.PP
|
||
|
|
See \f(CWhttps://web.eecs.umich.edu/~tpkelly/pma/\fP for
|
||
|
|
the latest source code and manual.
|
||
|
|
.SH COPYING PERMISSIONS
|
||
|
|
Copyright \(co 2022
|
||
|
|
Terence Kelly.
|
||
|
|
.PP
|
||
|
|
Permission is granted to make and distribute verbatim copies of
|
||
|
|
this manual page provided the copyright notice and this permission
|
||
|
|
notice are preserved on all copies.
|
||
|
|
.ig
|
||
|
|
Permission is granted to process this file through troff and print the
|
||
|
|
results, provided the printed document carries copying permission
|
||
|
|
notice identical to this one except for the removal of this paragraph
|
||
|
|
(this paragraph not being relevant to the printed manual page).
|
||
|
|
..
|
||
|
|
.PP
|
||
|
|
Permission is granted to copy and distribute modified versions of this
|
||
|
|
manual page under the conditions for verbatim copying, provided that
|
||
|
|
the entire resulting derived work is distributed under the terms of a
|
||
|
|
permission notice identical to this one.
|
||
|
|
.PP
|
||
|
|
Permission is granted to copy and distribute translations of this
|
||
|
|
manual page into another language, under the above conditions for
|
||
|
|
modified versions, except that this permission notice may be stated in
|
||
|
|
a translation approved by the Foundation.
|