Debian Codegraph @

upstream/mageia-cauldron/man1/perldbmfilter.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (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 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "PERLDBMFILTER 1"
61 .TH PERLDBMFILTER 1 2024-05-07 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 perldbmfilter \- Perl DBM Filters
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& $db = tie %hash, \*(AqDBM\*(Aq, ...
72 \&
73 \& $old_filter = $db\->filter_store_key ( sub { ... } );
74 \& $old_filter = $db\->filter_store_value( sub { ... } );
75 \& $old_filter = $db\->filter_fetch_key ( sub { ... } );
76 \& $old_filter = $db\->filter_fetch_value( sub { ... } );
77 .Ve
78 .SH DESCRIPTION
79 .IX Header "DESCRIPTION"
80 The four \f(CW\*(C`filter_*\*(C'\fR methods shown above are available in all the DBM
81 modules that ship with Perl, namely DB_File, GDBM_File, NDBM_File,
82 ODBM_File and SDBM_File.
83 .PP
84 Each of the methods works identically, and is used to install (or
85 uninstall) a single DBM Filter. The only difference between them is the
86 place that the filter is installed.
87 .PP
88 To summarise:
89 .IP \fBfilter_store_key\fR 5
90 .IX Item "filter_store_key"
91 If a filter has been installed with this method, it will be invoked
92 every time you write a key to a DBM database.
93 .IP \fBfilter_store_value\fR 5
94 .IX Item "filter_store_value"
95 If a filter has been installed with this method, it will be invoked
96 every time you write a value to a DBM database.
97 .IP \fBfilter_fetch_key\fR 5
98 .IX Item "filter_fetch_key"
99 If a filter has been installed with this method, it will be invoked
100 every time you read a key from a DBM database.
101 .IP \fBfilter_fetch_value\fR 5
102 .IX Item "filter_fetch_value"
103 If a filter has been installed with this method, it will be invoked
104 every time you read a value from a DBM database.
105 .PP
106 You can use any combination of the methods from none to all four.
107 .PP
108 All filter methods return the existing filter, if present, or \f(CW\*(C`undef\*(C'\fR
109 if not.
110 .PP
111 To delete a filter pass \f(CW\*(C`undef\*(C'\fR to it.
112 .SS "The Filter"
113 .IX Subsection "The Filter"
114 When each filter is called by Perl, a local copy of \f(CW$_\fR will contain
115 the key or value to be filtered. Filtering is achieved by modifying
116 the contents of \f(CW$_\fR. The return code from the filter is ignored.
117 .SS "An Example: the NULL termination problem"
118 .IX Subsection "An Example: the NULL termination problem"
119 DBM Filters are useful for a class of problems where you \fIalways\fR
120 want to make the same transformation to all keys, all values or both.
121 .PP
122 For example, consider the following scenario. You have a DBM database
123 that you need to share with a third\-party C application. The C application
124 assumes that \fIall\fR keys and values are NULL terminated. Unfortunately
125 when Perl writes to DBM databases it doesn\*(Aqt use NULL termination, so
126 your Perl application will have to manage NULL termination itself. When
127 you write to the database you will have to use something like this:
128 .PP
129 .Vb 1
130 \& $hash{"$key\e0"} = "$value\e0";
131 .Ve
132 .PP
133 Similarly the NULL needs to be taken into account when you are considering
134 the length of existing keys/values.
135 .PP
136 It would be much better if you could ignore the NULL terminations issue
137 in the main application code and have a mechanism that automatically
138 added the terminating NULL to all keys and values whenever you write to
139 the database and have them removed when you read from the database. As I\*(Aqm
140 sure you have already guessed, this is a problem that DBM Filters can
141 fix very easily.
142 .PP
143 .Vb 3
144 \& use v5.36;
145 \& use SDBM_File;
146 \& use Fcntl;
147 \&
148 \& my %hash;
149 \& my $filename = "filt";
150 \& unlink $filename;
151 \&
152 \& my $db = tie(%hash, \*(AqSDBM_File\*(Aq, $filename, O_RDWR|O_CREAT, 0640)
153 \& or die "Cannot open $filename: $!\en";
154 \&
155 \& # Install DBM Filters
156 \& $db\->filter_fetch_key ( sub { s/\e0$// } );
157 \& $db\->filter_store_key ( sub { $_ .= "\e0" } );
158 \& $db\->filter_fetch_value(
159 \& sub { no warnings \*(Aquninitialized\*(Aq; s/\e0$// } );
160 \& $db\->filter_store_value( sub { $_ .= "\e0" } );
161 \&
162 \& $hash{"abc"} = "def";
163 \& my $x = $hash{"ABC"};
164 \& # ...
165 \& undef $db;
166 \& untie %hash;
167 .Ve
168 .PP
169 The code above uses SDBM_File, but it will work with any of the DBM
170 modules.
171 .PP
172 Hopefully the contents of each of the filters should be
173 self\-explanatory. Both "fetch" filters remove the terminating NULL,
174 and both "store" filters add a terminating NULL.
175 .SS "Another Example: Key is a C int"
176 .IX Subsection "Another Example: Key is a C int"
177 Here is another real\-life example. By default, whenever Perl writes to
178 a DBM database it always writes the key and value as strings. So when
179 you use this:
180 .PP
181 .Vb 1
182 \& $hash{12345} = "something";
183 .Ve
184 .PP
185 the key 12345 will get stored in the DBM database as the 5 byte string
186 "12345". If you actually want the key to be stored in the DBM database
187 as a C int, you will have to use \f(CW\*(C`pack\*(C'\fR when writing, and \f(CW\*(C`unpack\*(C'\fR
188 when reading.
189 .PP
190 Here is a DBM Filter that does it:
191 .PP
192 .Vb 5
193 \& use v5.36;
194 \& use DB_File;
195 \& my %hash;
196 \& my $filename = "filt";
197 \& unlink $filename;
198 \&
199 \&
200 \& my $db = tie %hash, \*(AqDB_File\*(Aq, $filename, O_CREAT|O_RDWR, 0666,
201 \& $DB_HASH or die "Cannot open $filename: $!\en";
202 \&
203 \& $db\->filter_fetch_key ( sub { $_ = unpack("i", $_) } );
204 \& $db\->filter_store_key ( sub { $_ = pack ("i", $_) } );
205 \& $hash{123} = "def";
206 \& # ...
207 \& undef $db;
208 \& untie %hash;
209 .Ve
210 .PP
211 The code above uses DB_File, but again it will work with any of the
212 DBM modules.
213 .PP
214 This time only two filters have been used; we only need to manipulate
215 the contents of the key, so it wasn\*(Aqt necessary to install any value
216 filters.
217 .SH "SEE ALSO"
218 .IX Header "SEE ALSO"
219 DB_File, GDBM_File, NDBM_File, ODBM_File and SDBM_File.
220 .SH AUTHOR
221 .IX Header "AUTHOR"
222 Paul Marquess