.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\" ========================================================================
.de Sh \" Subsection heading
.de Sp \" Vertical space (when we can't use .PP)
.de Vb \" Begin verbatim text
.de Ve \" End verbatim text
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. | will give a
.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
. tm Index:\\$1\t\\n%\t"\\$2"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. \" simple accents for nroff and troff
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
.\" ========================================================================
.IX Title "PERLDBMFILTER 1"
.TH PERLDBMFILTER 1 "2006-01-07" "perl v5.8.8" "Perl Programmers Reference Guide"
perldbmfilter \- Perl DBM Filters
\& $db = tie %hash, 'DBM', ...
\& $old_filter = $db->filter_store_key ( sub { ... } );
\& $old_filter = $db->filter_store_value( sub { ... } );
\& $old_filter = $db->filter_fetch_key ( sub { ... } );
\& $old_filter = $db->filter_fetch_value( sub { ... } );
The four \f(CW\*(C`filter_*\*(C'\fR methods shown above are available in all the \s-1DBM\s0
modules that ship with Perl, namely DB_File, GDBM_File, NDBM_File,
Each of the methods work identically, and are used to install (or
uninstall) a single \s-1DBM\s0 Filter. The only difference between them is the
place that the filter is installed.
.IP "\fBfilter_store_key\fR" 5
.IX Item "filter_store_key"
If a filter has been installed with this method, it will be invoked
every time you write a key to a \s-1DBM\s0 database.
.IP "\fBfilter_store_value\fR" 5
.IX Item "filter_store_value"
If a filter has been installed with this method, it will be invoked
every time you write a value to a \s-1DBM\s0 database.
.IP "\fBfilter_fetch_key\fR" 5
.IX Item "filter_fetch_key"
If a filter has been installed with this method, it will be invoked
every time you read a key from a \s-1DBM\s0 database.
.IP "\fBfilter_fetch_value\fR" 5
.IX Item "filter_fetch_value"
If a filter has been installed with this method, it will be invoked
every time you read a value from a \s-1DBM\s0 database.
You can use any combination of the methods from none to all four.
All filter methods return the existing filter, if present, or \f(CW\*(C`undef\*(C'\fR
To delete a filter pass \f(CW\*(C`undef\*(C'\fR to it.
.IX Subsection "The Filter"
When each filter is called by Perl, a local copy of \f(CW$_\fR will contain
the key or value to be filtered. Filtering is achieved by modifying
the contents of \f(CW$_\fR. The return code from the filter is ignored.
.Sh "An Example \*(-- the \s-1NULL\s0 termination problem."
.IX Subsection "An Example the NULL termination problem."
\&\s-1DBM\s0 Filters are useful for a class of problems where you \fIalways\fR
want to make the same transformation to all keys, all values or both.
For example, consider the following scenario. You have a \s-1DBM\s0 database
that you need to share with a third-party C application. The C application
assumes that \fIall\fR keys and values are \s-1NULL\s0 terminated. Unfortunately
when Perl writes to \s-1DBM\s0 databases it doesn't use \s-1NULL\s0 termination, so
your Perl application will have to manage \s-1NULL\s0 termination itself. When
you write to the database you will have to use something like this:
\& $hash{"$key\e0"} = "$value\e0";
Similarly the \s-1NULL\s0 needs to be taken into account when you are considering
the length of existing keys/values.
It would be much better if you could ignore the \s-1NULL\s0 terminations issue
in the main application code and have a mechanism that automatically
added the terminating \s-1NULL\s0 to all keys and values whenever you write to
the database and have them removed when you read from the database. As I'm
sure you have already guessed, this is a problem that \s-1DBM\s0 Filters can
\& my $filename = "filt";
\& my $db = tie(%hash, 'SDBM_File', $filename, O_RDWR|O_CREAT, 0640)
\& or die "Cannot open $filename: $!\en";
\& $db->filter_fetch_key ( sub { s/\e0$// } );
\& $db->filter_store_key ( sub { $_ .= "\e0" } );
\& $db->filter_fetch_value(
\& sub { no warnings 'uninitialized'; s/\e0$// } );
\& $db->filter_store_value( sub { $_ .= "\e0" } );
The code above uses SDBM_File, but it will work with any of the \s-1DBM\s0
Hopefully the contents of each of the filters should be
self\-explanatory. Both \*(L"fetch\*(R" filters remove the terminating \s-1NULL\s0,
and both \*(L"store\*(R" filters add a terminating \s-1NULL\s0.
.Sh "Another Example \*(-- Key is a C int."
.IX Subsection "Another Example Key is a C int."
Here is another real-life example. By default, whenever Perl writes to
a \s-1DBM\s0 database it always writes the key and value as strings. So when
\& $hash{12345} = "something";
the key 12345 will get stored in the \s-1DBM\s0 database as the 5 byte string
\&\*(L"12345\*(R". If you actually want the key to be stored in the \s-1DBM\s0 database
as a C int, you will have to use \f(CW\*(C`pack\*(C'\fR when writing, and \f(CW\*(C`unpack\*(C'\fR
Here is a \s-1DBM\s0 Filter that does it:
\& my $filename = "filt";
\& my $db = tie %hash, 'DB_File', $filename, O_CREAT|O_RDWR, 0666, $DB_HASH
\& or die "Cannot open $filename: $!\en";
\& $db->filter_fetch_key ( sub { $_ = unpack("i", $_) } );
\& $db->filter_store_key ( sub { $_ = pack ("i", $_) } );
The code above uses DB_File, but again it will work with any of the
This time only two filters have been used \*(-- we only need to manipulate
the contents of the key, so it wasn't necessary to install any value
DB_File, GDBM_File, NDBM_File, ODBM_File and SDBM_File.
projects / OpenSPARC-T2-SAM / blob