unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OpenBSD-3.6)
Page:
Section:
Apropos / Subsearch:
optional field



Hash::Util(3p)   Perl Programmers Reference Guide  Hash::Util(3p)


NAME
       Hash::Util - A selection of general-utility hash subrou-
       tines

SYNOPSIS
         use Hash::Util qw(lock_keys   unlock_keys
                           lock_value  unlock_value
                           lock_hash   unlock_hash
                           hash_seed);

         %hash = (foo => 42, bar => 23);
         lock_keys(%hash);
         lock_keys(%hash, @keyset);
         unlock_keys(%hash);

         lock_value  (%hash, 'foo');
         unlock_value(%hash, 'foo');

         lock_hash  (%hash);
         unlock_hash(%hash);

         my $hashes_are_randomised = hash_seed() != 0;

DESCRIPTION
       "Hash::Util" contains special functions for manipulating
       hashes that don't really warrant a keyword.

       By default "Hash::Util" does not export anything.

       Restricted hashes

       5.8.0 introduces the ability to restrict a hash to a cer-
       tain set of keys.  No keys outside of this set can be
       added.  It also introduces the ability to lock an individ-
       ual key so it cannot be deleted and the value cannot be
       changed.

       This is intended to largely replace the deprecated
       pseudo-hashes.

       lock_keys
       unlock_keys
             lock_keys(%hash);
             lock_keys(%hash, @keys);

           Restricts the given %hash's set of keys to @keys.  If
           @keys is not given it restricts it to its current key-
           set.  No more keys can be added. delete() and exists()
           will still work, but will not alter the set of allowed
           keys. Note: the current implementation prevents the
           hash from being bless()ed while it is in a locked
           state. Any attempt to do so will raise an exception.
           Of course you can still bless() the hash before you
           call lock_keys() so this shouldn't be a problem.



perl v5.8.5                 2002-11-06                          1





Hash::Util(3p)   Perl Programmers Reference Guide  Hash::Util(3p)


             unlock_keys(%hash);

           Removes the restriction on the %hash's keyset.

       lock_value
       unlock_value
             lock_value  (%hash, $key);
             unlock_value(%hash, $key);

           Locks and unlocks an individual key of a hash.  The
           value of a locked key cannot be changed.

           %hash must have already been locked for this to have
           useful effect.

       lock_hash
       unlock_hash
               lock_hash(%hash);

           lock_hash() locks an entire hash, making all keys and
           values readonly.  No value can be changed, no keys can
           be added or deleted.

               unlock_hash(%hash);

           unlock_hash() does the opposite of lock_hash().  All
           keys and values are made read/write.  All values can
           be changed and keys can be added and deleted.

       hash_seed
               my $hash_seed = hash_seed();

           hash_seed() returns the seed number used to randomise
           hash ordering.  Zero means the "traditional" random
           hash ordering, non-zero means the new even more random
           hash ordering introduced in Perl 5.8.1.

           Note that the hash seed is sensitive information: by
           knowing it one can craft a denial-of-service attack
           against Perl code, even remotely, see "Algorithmic
           Complexity Attacks" in perlsec for more information.
           Do not disclose the hash seed to people who don't need
           to know it.  See also "PERL_HASH_SEED_DEBUG" in perl-
           run.

CAVEATS
       Note that the trapping of the restricted operations is not
       atomic: for example

           eval { %hash = (illegal_key => 1) }

       leaves the %hash empty rather than with its original con-
       tents.




perl v5.8.5                 2002-11-06                          2





Hash::Util(3p)   Perl Programmers Reference Guide  Hash::Util(3p)


AUTHOR
       Michael G Schwern <schwernATpobox.com> on top of code by
       Nick Ing-Simmons and Jeffrey Friedl.

SEE ALSO
       Scalar::Util, List::Util, Hash::Util, and "Algorithmic
       Complexity Attacks" in perlsec.


















































perl v5.8.5                 2002-11-06                          3