man > pm-gawk(1)

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 vari‐
       ables and functions in a file for later use.  The feature, called pm-gawk,  is  described  in
       GAWK: Effective AWK Programming and in Persistent 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 environment variable GAWK_PERSIST_FILE.  pm-gawk retains  script-defined  vari‐
       ables 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 of‐
       fers 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 func‐
       tions are stored.  If this environment variable is not visible to gawk, the persistence  fea‐
       ture 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 alloca‐
       tor  (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 backing 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 suspected bugs related to persistence (as opposed to  other  non-persistence-re‐
       lated  gawk bugs) please also send e-mail to Terence Kelly at one or more of these addresses:
       tpkelly AT acm.org, tpkelly AT eecs.edu, or tpkelly AT cs.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 verbatim copying, provided that the entire resulting derived work is  distrib‐
       uted under the terms of a permission notice 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  no‐
       tice may be stated in a translation approved by the Foundation.

Free Software Foundation                     Nov 17 2022                                  PM-GAWK(1)