From 3ae6fb965f260eb1aaade68ff9c4d60d4c9c8e79 Mon Sep 17 00:00:00 2001 From: "Barton E. Schaefer" Date: Sun, 1 Feb 2015 14:00:24 -0800 Subject: 34446: add "ztie -r" and "zuntie -u", update documentation --- Doc/Zsh/mod_db_gdbm.yo | 40 ++++++++++++++++++++++++++++++++-------- 1 file changed, 32 insertions(+), 8 deletions(-) (limited to 'Doc') diff --git a/Doc/Zsh/mod_db_gdbm.yo b/Doc/Zsh/mod_db_gdbm.yo index 6065f860e..90974297c 100644 --- a/Doc/Zsh/mod_db_gdbm.yo +++ b/Doc/Zsh/mod_db_gdbm.yo @@ -11,17 +11,41 @@ The builtins in this module are: startitem() findex(ztie) -cindex(tied array, creating) -item(tt(ztie -d db/gdbm -f) var(filename) var(arrayname))( +cindex(database tied array, creating) +item(tt(ztie -d db/gdbm -f) var(filename) [ tt(-r) ] var(arrayname))( Open the GDBM database identified by var(filename) and, if successful, -create the associative array var(arrayname) linked to the file. Note -that var(arrayname) must be unset at the time tt(ztie) is called, and -is always created as a global parameter (as if with `tt(typeset -g)'). +create the associative array var(arrayname) linked to the file. To create +a local tied array, the parameter must first be declared, so commands +similar to the following would be executed inside a function scope: + +example(local -A sampledb +ztie -d db/gdbm -f sample.gdbm sampledb) + +The tt(-r) option opens the database file for reading only, creating a +parameter with the readonly attribute. Without this option, using +`tt(ztie)' on a file for which the user does not have write permission is +an error. If writable, the database is opened synchronously so fields +changed in var(arrayname) are immediately written to var(filename). + +Changes to the file modes var(filename) after it has been opened do not +alter the state of var(arrayname), but `tt(typeset -r) var(arrayname)' +works as expected. ) findex(zuntie) -cindex(tied array, destroying) -item(tt(zuntie) var(arrayname) ...)( +cindex(database tied array, destroying) +item(tt(zuntie) [ tt(-u) ] var(arrayname) ...)( Close the GDBM database associated with each var(arrayname) and then -unset the variable. +unset the parameter. The tt(-u) option forces an unset of parameters +made readonly with `tt(ztie -r)'. + +This happens automatically if the parameter is explicitly unset or its +local scope (function) ends. Note that a readonly parameter may not be +explicitly unset, so the only way to unset a global parameter created with +`tt(ztie -r)' is to use `tt(zuntie -u)'. ) enditem() + +The fields of an associative array tied to GDBM are neither cached nor +otherwise stored in memory, they are read from or written to the database +on each reference. Thus, for example, the values in a readonly array may +be changed by a second writer of the same database file. -- cgit 1.4.1