diff options
Diffstat (limited to 'upstream/archlinux/man1/pm-gawk.1')
| -rw-r--r-- | upstream/archlinux/man1/pm-gawk.1 | 208 |
1 files changed, 208 insertions, 0 deletions
diff --git a/upstream/archlinux/man1/pm-gawk.1 b/upstream/archlinux/man1/pm-gawk.1 new file mode 100644 index 00000000..9f87d89b --- /dev/null +++ b/upstream/archlinux/man1/pm-gawk.1 @@ -0,0 +1,208 @@ +.ds EP \fIGAWK: Effective AWK Programming\fP +.ds PM \fIPersistent Memory gawk User Manual\fP +.TH PM-GAWK 1 "Nov 17 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 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 +.IR pm-gawk . +.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. |