PM-GAWK(1)

💖 PM-GAWK — persistent memory gawk 💖

okay bestie, welcome to pm-gawk, aka persistent memory gawk, from the Utility Commands section of the manual. this is the page for PM-GAWK(1) and it's lowkey one of the coolest things gawk ever did. let's get into it 🦋

---

✨ NAME ✨

persistent memory gawk — persistent data and functions. yes, your variables AND your functions can just... stay. between runs. iconic behavior honestly 💅

---

🌸 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

like, that's the whole vibe. make a heap file, point an env var at it, and your gawk scripts get memory 🧠✨

---

🎀 DESCRIPTION 🎀

so gawk 5.2 and later has this persistent memory feature that can store script-defined variables and functions in a file so you can use them later. this feature is called pm-gawk, and it's described in GAWK: Effective AWK Programming and in the Persistent Memory gawk User Manual (go read those, they're the real ones, i'm just the hype girl).

pm-gawk wakes up when you hand gawk the name of an initially empty (all-zero-bytes) heap file, passed through the environment variable GAWK_PERSIST_FILE. and then — plot twist — pm-gawk keeps your script-defined variables and functions sitting in that heap file so your next gawk invocation can just pick them up like nothing happened. no cap. 🔥

ngl pm-gawk has at least two big advantages over the existing rwarray extension:

• it gives you constant-time (O(1) time) access to individual elements of persistent associative arrays — no scanning, no waiting, just instant vibes ⚡
• and it can store script-defined functions in addition to variables. functions!! in a file!! main character energy fr fr 👑

---

🍓 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

look at i just... remembering itself. obsessed 😭💖

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

same heap, same i, it just keeps counting. the persistence did NOT reset, bestie 🌈

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

the alias is the succinct route and honestly? aesthetic. 🎀

To refrain from activating persistence:

$ unset GAWK_PERSIST_FILE
$ gawk 'BEGIN { print ++i }'
1
$ gawk 'BEGIN { print ++i }'
1

no env var, no persistence, no memory — i resets to a fresh little 1 every single time. baby gawk behavior 🙈

To permanently ``forget'' the contents of the heap file:

$ rm heap.pma

gone. deleted. the heap has left the chat 💀 (you'll want to recreate it with truncate before using pm-gawk again, obviously)

---

🦋 ENVIRONMENT VARIABLES 🦋

• GAWK_PERSIST_FILE — holds the name of the heap file where script-defined variables and functions get stored. if this environment variable isn't visible to gawk, then the persistence feature is not activated and gawk just does its traditional gawk thing. no heap, no drama.

---

⭐ VERSION INFORMATION ⭐

Persistent memory gawk first dropped in gawk 5.2. that's the origin story, periodt.

---

👑 AUTHORS 👑

Arnold Robbins, the maintainer of gawk, implemented pm-gawk using a persistent memory allocator (pma) provided by Terence Kelly. 🫶

and 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. legends, all of them 💜

---

💀 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. like, seriously, don't. i'm begging 🙏

⚠️ pm-gawk throws a warning if the current version of gawk doesn't match the one that was first used with a particular backing storage file. mismatched versions = it will tell you about it.

---

😭 BUG REPORTS 😭

follow the procedures in GAWK: Effective AWK Programming and in the Persistent Memory gawk User Manual.

but if you're suspecting bugs related to persistence specifically (as opposed to other non-persistence-related gawk bugs, iykyk), please also send e-mail to Terence Kelly at one or more of these addresses:

• tpkelly@acm.org
• tpkelly@eecs.umich.edu
• tpkelly@cs.princeton.edu

---

🌈 SEE ALSO 🌈

• gawk(1)
• GAWK: Effective AWK Programming
• Persistent Memory gawk User Manual

both manuals should be available in the Info subsystem if Info is installed on your system 🧚

also: see https://web.eecs.umich.edu/~tpkelly/pma/ for the latest source code and manual. go, go look, it's right there 💖

---

📜 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 distributed 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 notice may be stated in a translation approved by the Foundation.

---

and that's the whole page, bestie 🎀 Free Software Foundation, June 01 2025 — that's who put this out and when. now go truncate yourself a heap and go off 💅✨🦋