Penguin
Recent Changes
Blame: perldbmfilter(1)
EditPageHistoryDiffInfoLikePages
Annotated edit history of perldbmfilter(1) version 1, including all changes. View license author blame.
Rev Author # Line
1 perry 1 PERLDBMFILTER
2 !!!PERLDBMFILTER
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 SEE ALSO
7 AUTHOR
8 ----
9 !!NAME
10
11
12 perldbmfilter - Perl DBM Filters
13 !!SYNOPSIS
14
15
16 $db = tie %hash, 'DBM', ...
17 $old_filter = $db-
18 !!DESCRIPTION
19
20
21 The four filter_* methods shown above are available
22 in all the DBM modules that ship with Perl,
23 namely DB_File, GDBM_File, NDBM_File, ODBM_File and
24 SDBM_File.
25
26
27 Each of the methods work identically, and are used to
28 install (or uninstall) a single DBM Filter.
29 The only difference between them is the place that the
30 filter is installed.
31
32
33 To summarise:
34
35
36 __filter_store_key__
37
38
39 If a filter has been installed with this method, it will be
40 invoked every time you write a key to a DBM
41 database.
42
43
44 __filter_store_value__
45
46
47 If a filter has been installed with this method, it will be
48 invoked every time you write a value to a DBM
49 database.
50
51
52 __filter_fetch_key__
53
54
55 If a filter has been installed with this method, it will be
56 invoked every time you read a key from a DBM
57 database.
58
59
60 __filter_fetch_value__
61
62
63 If a filter has been installed with this method, it will be
64 invoked every time you read a value from a
65 DBM database.
66
67
68 You can use any combination of the methods from none to all
69 four.
70
71
72 All filter methods return the existing filter, if present,
73 or undef in not.
74
75
76 To delete a filter pass undef to it.
77
78
79 __The Filter__
80
81
82 When each filter is called by Perl, a local copy of
83 $_ will contain the key or value to be filtered.
84 Filtering is achieved by modifying the contents of
85 $_. The return code from the filter is
86 ignored.
87
88
89 __An Example -- the NULL termination
90 problem.__
91
92
93 DBM Filters are useful for a class of
94 problems where you ''always'' want to make the same
95 transformation to all keys, all values or both.
96
97
98 For example, consider the following scenario. You have a
99 DBM database that you need to share with a
100 third-party C application. The C application assumes that
101 ''all'' keys and values are NULL
102 terminated. Unfortunately when Perl writes to
103 DBM databases it doesn't use
104 NULL termination, so your Perl application
105 will have to manage NULL termination itself.
106 When you write to the database you will have to use
107 something like this:
108
109
110 $hash{
111 Similarly the NULL needs to be taken into account when you are considering the length of existing keys/values.
112
113
114 It would be much better if you could ignore the
115 NULL terminations issue in the main
116 application code and have a mechanism that automatically
117 added the terminating NULL to all keys and
118 values whenever you write to the database and have them
119 removed when you read from the database. As I'm sure you
120 have already guessed, this is a problem that
121 DBM Filters can fix very easily.
122
123
124 use strict ;
125 use warnings ;
126 use SDBM_File ;
127 use Fcntl ;
128 my %hash ;
129 my $filename =
130 my $db = tie(%hash, 'SDBM_File', $filename, O_RDWRO_CREAT, 0640)
131 or die
132 # Install DBM Filters
133 $db-
134 $hash{
135 The code above uses SDBM_File, but it will work with any of the DBM modules.
136
137
138 Hopefully the contents of each of the filters should be
139 self-explanatory. Both ``fetch'' filters remove the
140 terminating NULL , and both ``store'' filters
141 add a terminating NULL .
142
143
144 __Another Example -- Key is a C int.__
145
146
147 Here is another real-life example. By default, whenever Perl
148 writes to a DBM database it always writes the
149 key and value as strings. So when you use this:
150
151
152 $hash{12345} =
153 the key 12345 will get stored in the DBM database as the 5 byte string ``12345''. If you actually want the key to be stored in the DBM database as a C int, you will have to use pack when writing, and unpack when reading.
154
155
156 Here is a DBM Filter that does
157 it:
158
159
160 use strict ;
161 use warnings ;
162 use DB_File ;
163 my %hash ;
164 my $filename =
165 my $db = tie %hash, 'DB_File', $filename, O_CREATO_RDWR, 0666, $DB_HASH
166 or die
167 $db-
168 The code above uses DB_File, but again it will work with any of the DBM modules.
169
170
171 This time only two filters have been used -- we only need to
172 manipulate the contents of the key, so it wasn't necessary
173 to install any value filters.
174 !!SEE ALSO
175
176
177 DB_File, GDBM_File, NDBM_File, ODBM_File and
178 SDBM_File.
179 !!AUTHOR
180
181
182 Paul Marquess
183 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.