Debian Codegraph @

upstream/debian-unstable/man1/perldbmfilter.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "PERLDBMFILTER 1"
58 .TH PERLDBMFILTER 1 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 perldbmfilter \- Perl DBM Filters
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& $db = tie %hash, \*(AqDBM\*(Aq, ...
69 \&
70 \& $old_filter = $db\->filter_store_key ( sub { ... } );
71 \& $old_filter = $db\->filter_store_value( sub { ... } );
72 \& $old_filter = $db\->filter_fetch_key ( sub { ... } );
73 \& $old_filter = $db\->filter_fetch_value( sub { ... } );
74 .Ve
75 .SH DESCRIPTION
76 .IX Header "DESCRIPTION"
77 The four \f(CW\*(C`filter_*\*(C'\fR methods shown above are available in all the DBM
78 modules that ship with Perl, namely DB_File, GDBM_File, NDBM_File,
79 ODBM_File and SDBM_File.
80 .PP
81 Each of the methods works identically, and is used to install (or
82 uninstall) a single DBM Filter. The only difference between them is the
83 place that the filter is installed.
84 .PP
85 To summarise:
86 .IP \fBfilter_store_key\fR 5
87 .IX Item "filter_store_key"
88 If a filter has been installed with this method, it will be invoked
89 every time you write a key to a DBM database.
90 .IP \fBfilter_store_value\fR 5
91 .IX Item "filter_store_value"
92 If a filter has been installed with this method, it will be invoked
93 every time you write a value to a DBM database.
94 .IP \fBfilter_fetch_key\fR 5
95 .IX Item "filter_fetch_key"
96 If a filter has been installed with this method, it will be invoked
97 every time you read a key from a DBM database.
98 .IP \fBfilter_fetch_value\fR 5
99 .IX Item "filter_fetch_value"
100 If a filter has been installed with this method, it will be invoked
101 every time you read a value from a DBM database.
102 .PP
103 You can use any combination of the methods from none to all four.
104 .PP
105 All filter methods return the existing filter, if present, or \f(CW\*(C`undef\*(C'\fR
106 if not.
107 .PP
108 To delete a filter pass \f(CW\*(C`undef\*(C'\fR to it.
109 .SS "The Filter"
110 .IX Subsection "The Filter"
111 When each filter is called by Perl, a local copy of \f(CW$_\fR will contain
112 the key or value to be filtered. Filtering is achieved by modifying
113 the contents of \f(CW$_\fR. The return code from the filter is ignored.
114 .SS "An Example: the NULL termination problem"
115 .IX Subsection "An Example: the NULL termination problem"
116 DBM Filters are useful for a class of problems where you \fIalways\fR
117 want to make the same transformation to all keys, all values or both.
118 .PP
119 For example, consider the following scenario. You have a DBM database
120 that you need to share with a third-party C application. The C application
121 assumes that \fIall\fR keys and values are NULL terminated. Unfortunately
122 when Perl writes to DBM databases it doesn't use NULL termination, so
123 your Perl application will have to manage NULL termination itself. When
124 you write to the database you will have to use something like this:
125 .PP
126 .Vb 1
127 \& $hash{"$key\e0"} = "$value\e0";
128 .Ve
129 .PP
130 Similarly the NULL needs to be taken into account when you are considering
131 the length of existing keys/values.
132 .PP
133 It would be much better if you could ignore the NULL terminations issue
134 in the main application code and have a mechanism that automatically
135 added the terminating NULL to all keys and values whenever you write to
136 the database and have them removed when you read from the database. As I'm
137 sure you have already guessed, this is a problem that DBM Filters can
138 fix very easily.
139 .PP
140 .Vb 3
141 \& use v5.36;
142 \& use SDBM_File;
143 \& use Fcntl;
144 \&
145 \& my %hash;
146 \& my $filename = "filt";
147 \& unlink $filename;
148 \&
149 \& my $db = tie(%hash, \*(AqSDBM_File\*(Aq, $filename, O_RDWR|O_CREAT, 0640)
150 \& or die "Cannot open $filename: $!\en";
151 \&
152 \& # Install DBM Filters
153 \& $db\->filter_fetch_key ( sub { s/\e0$// } );
154 \& $db\->filter_store_key ( sub { $_ .= "\e0" } );
155 \& $db\->filter_fetch_value(
156 \& sub { no warnings \*(Aquninitialized\*(Aq; s/\e0$// } );
157 \& $db\->filter_store_value( sub { $_ .= "\e0" } );
158 \&
159 \& $hash{"abc"} = "def";
160 \& my $x = $hash{"ABC"};
161 \& # ...
162 \& undef $db;
163 \& untie %hash;
164 .Ve
165 .PP
166 The code above uses SDBM_File, but it will work with any of the DBM
167 modules.
168 .PP
169 Hopefully the contents of each of the filters should be
170 self-explanatory. Both "fetch" filters remove the terminating NULL,
171 and both "store" filters add a terminating NULL.
172 .SS "Another Example: Key is a C int"
173 .IX Subsection "Another Example: Key is a C int"
174 Here is another real-life example. By default, whenever Perl writes to
175 a DBM database it always writes the key and value as strings. So when
176 you use this:
177 .PP
178 .Vb 1
179 \& $hash{12345} = "something";
180 .Ve
181 .PP
182 the key 12345 will get stored in the DBM database as the 5 byte string
183 "12345". If you actually want the key to be stored in the DBM database
184 as a C int, you will have to use \f(CW\*(C`pack\*(C'\fR when writing, and \f(CW\*(C`unpack\*(C'\fR
185 when reading.
186 .PP
187 Here is a DBM Filter that does it:
188 .PP
189 .Vb 5
190 \& use v5.36;
191 \& use DB_File;
192 \& my %hash;
193 \& my $filename = "filt";
194 \& unlink $filename;
195 \&
196 \&
197 \& my $db = tie %hash, \*(AqDB_File\*(Aq, $filename, O_CREAT|O_RDWR, 0666,
198 \& $DB_HASH or die "Cannot open $filename: $!\en";
199 \&
200 \& $db\->filter_fetch_key ( sub { $_ = unpack("i", $_) } );
201 \& $db\->filter_store_key ( sub { $_ = pack ("i", $_) } );
202 \& $hash{123} = "def";
203 \& # ...
204 \& undef $db;
205 \& untie %hash;
206 .Ve
207 .PP
208 The code above uses DB_File, but again it will work with any of the
209 DBM modules.
210 .PP
211 This time only two filters have been used; we only need to manipulate
212 the contents of the key, so it wasn't necessary to install any value
213 filters.
214 .SH "SEE ALSO"
215 .IX Header "SEE ALSO"
216 DB_File, GDBM_File, NDBM_File, ODBM_File and SDBM_File.
217 .SH AUTHOR
218 .IX Header "AUTHOR"
219 Paul Marquess