PM-GAWK(1) Utility Commands PM-GAWK(1)
NAME
persistent memory gawk - persistent data and functions
SYNOPSIS
truncate -s size heap.pma
export GAWK_PERSIST_FILE=heap.pma
gawk ...
truncate -s size heap.pma
GAWK_PERSIST_FILE=heap.pma gawk ...
truncate -s size heap.pma
alias pm='GAWK_PERSIST_FILE=heap.pma'
pm gawk ... # succinct
unset GAWK_PERSIST_FILE # disable persistence
export GAWK_PERSIST_FILE=other_heap.pma # change heap
rm heap.pma # delete heap
DESCRIPTION
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 pm-gawk, is described in GAWK: Effective AWK Programming and in Per‐
sistent Memory gawk User Manual.
pm-gawk is activated by passing to gawk the name of an initially empty (all-zero-bytes) heap file, via the envi‐
ronment variable GAWK_PERSIST_FILE. pm-gawk retains script-defined variables and functions in the heap file for
use in subsequent gawk invocations.
pm-gawk offers at least two advantages compared with the existing rwarray 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.
EXAMPLES
Demonstrate persistent variables:
$ truncate -s 1G heap.pma # create heap file
$ export GAWK_PERSIST_FILE=heap.pma # "ambient" env var
$ gawk 'BEGIN { print ++i }'
1
$ gawk 'BEGIN { print ++i }'
2
$ gawk 'BEGIN { print ++i }'
3
To pass the environment variable on per-command basis:
$ unset GAWK_PERSIST_FILE
$ GAWK_PERSIST_FILE=heap.pma gawk 'BEGIN { print ++i }'
4
$ GAWK_PERSIST_FILE=heap.pma gawk 'BEGIN { print ++i }'
5
$ GAWK_PERSIST_FILE=heap.pma gawk 'BEGIN { print ++i }'
6
To reduce visual clutter of per-command environment variable passing:
$ alias pm='GAWK_PERSIST_FILE=heap.pma'
$ pm gawk 'BEGIN { print ++i }'
7
$ pm gawk 'BEGIN { print ++i }'
8
To refrain from activating persistence:
$ unset GAWK_PERSIST_FILE
$ gawk 'BEGIN { print ++i }'
1
$ gawk 'BEGIN { print ++i }'
1
To permanently ‘‘forget'' the contents of the heap file:
$ rm heap.pma
ENVIRONMENT VARIABLES
GAWK_PERSIST_FILE contains the name of a heap file where script-defined variables and functions are stored. If
this environment variable is not visible to gawk, the persistence feature is not activated and gawk behaves in
its traditional manner.
VERSION INFORMATION
Persistent memory gawk was first released in gawk 5.2.
AUTHORS
Arnold Robbins, the maintainer of gawk, implemented pm-gawk using a persistent memory allocator (pma) provided by
Terence Kelly. An earlier proof-of-concept prototype of persistent gawk was developed by Haris Volos, Zi Fan
Tan, and Jianan Li using a fork of the official gawk sources.
CAVEATS
The GNU/Linux CIFS filesystem is known to cause problems for the persistent memory allocator. Do not use a back‐
ing file on such a filesystem with pm-gawk.
BUG REPORTS
Follow the procedures in GAWK: Effective AWK Programming and in Persistent Memory gawk User Manual. For sus‐
pected bugs related to persistence (as opposed to other non-persistence-related gawk bugs) please also send e-
mail to Terence Kelly at one or more of these addresses: tpkelly@acm.org, tpkelly@eecs.umich.edu, or tp‐
kelly@cs.princeton.edu.
SEE ALSO
gawk(1), GAWK: Effective AWK Programming, and Persistent Memory gawk User Manual. The two manuals should be
available in the Info subsystem if Info installed on your system.
See https://web.eecs.umich.edu/~tpkelly/pma/ for the latest source code and manual.
COPYING PERMISSIONS
Copyright © 2022 Terence Kelly.
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.
Permission is granted to copy and distribute modified versions of this manual page under the conditions for ver‐
batim copying, provided that the entire resulting derived work is distributed under the terms of a permission no‐
tice identical to this one.
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 ap‐
proved by the Foundation.
Free Software Foundation Nov 17 2022 PM-GAWK(1)
NAME
persistent memory gawk - persistent data and functions
SYNOPSIS
truncate -s size heap.pma
export GAWK_PERSIST_FILE=heap.pma
gawk ...
truncate -s size heap.pma
GAWK_PERSIST_FILE=heap.pma gawk ...
truncate -s size heap.pma
alias pm='GAWK_PERSIST_FILE=heap.pma'
pm gawk ... # succinct
unset GAWK_PERSIST_FILE # disable persistence
export GAWK_PERSIST_FILE=other_heap.pma # change heap
rm heap.pma # delete heap
DESCRIPTION
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 pm-gawk, is described in GAWK: Effective AWK Programming and in Per‐
sistent Memory gawk User Manual.
pm-gawk is activated by passing to gawk the name of an initially empty (all-zero-bytes) heap file, via the envi‐
ronment variable GAWK_PERSIST_FILE. pm-gawk retains script-defined variables and functions in the heap file for
use in subsequent gawk invocations.
pm-gawk offers at least two advantages compared with the existing rwarray 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.
EXAMPLES
Demonstrate persistent variables:
$ truncate -s 1G heap.pma # create heap file
$ export GAWK_PERSIST_FILE=heap.pma # "ambient" env var
$ gawk 'BEGIN { print ++i }'
1
$ gawk 'BEGIN { print ++i }'
2
$ gawk 'BEGIN { print ++i }'
3
To pass the environment variable on per-command basis:
$ unset GAWK_PERSIST_FILE
$ GAWK_PERSIST_FILE=heap.pma gawk 'BEGIN { print ++i }'
4
$ GAWK_PERSIST_FILE=heap.pma gawk 'BEGIN { print ++i }'
5
$ GAWK_PERSIST_FILE=heap.pma gawk 'BEGIN { print ++i }'
6
To reduce visual clutter of per-command environment variable passing:
$ alias pm='GAWK_PERSIST_FILE=heap.pma'
$ pm gawk 'BEGIN { print ++i }'
7
$ pm gawk 'BEGIN { print ++i }'
8
To refrain from activating persistence:
$ unset GAWK_PERSIST_FILE
$ gawk 'BEGIN { print ++i }'
1
$ gawk 'BEGIN { print ++i }'
1
To permanently ‘‘forget'' the contents of the heap file:
$ rm heap.pma
ENVIRONMENT VARIABLES
GAWK_PERSIST_FILE contains the name of a heap file where script-defined variables and functions are stored. If
this environment variable is not visible to gawk, the persistence feature is not activated and gawk behaves in
its traditional manner.
VERSION INFORMATION
Persistent memory gawk was first released in gawk 5.2.
AUTHORS
Arnold Robbins, the maintainer of gawk, implemented pm-gawk using a persistent memory allocator (pma) provided by
Terence Kelly. An earlier proof-of-concept prototype of persistent gawk was developed by Haris Volos, Zi Fan
Tan, and Jianan Li using a fork of the official gawk sources.
CAVEATS
The GNU/Linux CIFS filesystem is known to cause problems for the persistent memory allocator. Do not use a back‐
ing file on such a filesystem with pm-gawk.
BUG REPORTS
Follow the procedures in GAWK: Effective AWK Programming and in Persistent Memory gawk User Manual. For sus‐
pected bugs related to persistence (as opposed to other non-persistence-related gawk bugs) please also send e-
mail to Terence Kelly at one or more of these addresses: tpkelly@acm.org, tpkelly@eecs.umich.edu, or tp‐
kelly@cs.princeton.edu.
SEE ALSO
gawk(1), GAWK: Effective AWK Programming, and Persistent Memory gawk User Manual. The two manuals should be
available in the Info subsystem if Info installed on your system.
See https://web.eecs.umich.edu/~tpkelly/pma/ for the latest source code and manual.
COPYING PERMISSIONS
Copyright © 2022 Terence Kelly.
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.
Permission is granted to copy and distribute modified versions of this manual page under the conditions for ver‐
batim copying, provided that the entire resulting derived work is distributed under the terms of a permission no‐
tice identical to this one.
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 ap‐
proved by the Foundation.
Free Software Foundation Nov 17 2022 PM-GAWK(1)