diff options
Diffstat (limited to 'upstream/fedora-40/man3/rwarray.3am')
| -rw-r--r-- | upstream/fedora-40/man3/rwarray.3am | 131 |
1 files changed, 131 insertions, 0 deletions
diff --git a/upstream/fedora-40/man3/rwarray.3am b/upstream/fedora-40/man3/rwarray.3am new file mode 100644 index 00000000..dbebf519 --- /dev/null +++ b/upstream/fedora-40/man3/rwarray.3am @@ -0,0 +1,131 @@ +.TH RWARRAY 3am "Mar 11 2022" "Free Software Foundation" "GNU Awk Extension Modules" +.SH NAME +writea, reada, writeall, readall \- write and read gawk arrays to/from files +.SH SYNOPSIS +.ft CW +@load "rwarray" +.sp +ret = writea(file, array) +.br +ret = reada(file, array) +.br +ret = writeall(file) +.br +ret = readall(file) +.ft R +.SH DESCRIPTION +The +.I rwarray +extension adds functions named +.BR writea() , +.BR reada() , +.BR writeall() , +and +.BR readall() , +as follows. +.TP +.B writea() +This function takes a string argument, which is the name of the +file to which dump the array, and the array itself as the second +argument. +.B writea() +understands multidimensional arrays. +It returns one on success, or zero upon failure. +.TP +.B reada() +is the inverse of +.BR writea() ; +it reads the file named as its first argument, filling in +the array named as the second argument. It clears the array +first. +Here too, the return value is one on success and zero upon failure. +.TP +.B writeall() +This function takes a string argument, which is the name of the +file to which dump the state of all variables. Calling this function +is completely equivalent to calling +.B writea() +with the second argument equal to +.BR SYMTAB . +It returns one on success, or zero upon failure. +.TP +.B readall() +This function takes a string argument, which is the name of the +file from which to read the contents of various global variables. +For each variable in the file, the data is loaded unless the variable +already exists. If the variable already exists, the data for that variable +in the file is ignored. +It returns one on success, or zero upon failure. +.SH NOTES +The array created by +.B reada() +is identical to that written by +.B writea() +in the sense that the contents are the same. However, due +to implementation issues, the array traversal order of the recreated +array will likely be different from that of the original array. +As array traversal order in AWK is by default undefined, this is +not (technically) a problem. If you need to guarantee a particular +traversal order, use the array sorting features in +.I gawk +to do so. +.PP +The file contains binary data. All integral values are written +in network byte order. +However, double precision floating-point values are written as +native binary data. Thus, arrays containing only string data +can theoretically be dumped on systems with one byte order and +restored on systems with a different one, but this has not been tried. +.\" .SH BUGS +.SH EXAMPLE +.ft CW +.nf +@load "rwarray" +\&... +ret = writea("arraydump.bin", array) +\&... +ret = reada("arraydump.bin", array) +\&... +ret = writeall("globalstate.bin") +\&... +ret = readall("globalstate.bin") +.fi +.ft R +.SH "SEE ALSO" +.IR "GAWK: Effective AWK Programming" , +.IR filefuncs (3am), +.IR fnmatch (3am), +.IR fork (3am), +.IR inplace (3am), +.IR ordchr (3am), +.IR readdir (3am), +.IR readfile (3am), +.IR revoutput (3am), +.IR time (3am). +.SH AUTHOR +Arnold Robbins, +.BR arnold@skeeve.com . +.SH COPYING PERMISSIONS +Copyright \(co 2012, 2013, 2018, 2022 +Free Software Foundation, Inc. +.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. +.\" vim: set filetype=nroff : |