{
    "mode": "man",
    "parameter": "perldbmfilter",
    "section": "1",
    "url": "https://www.chedong.com/phpMan.php/man/perldbmfilter/1/json",
    "generated": "2026-10-05T07:45:59Z",
    "synopsis": "$db = tie %hash, 'DBM', ...\n$oldfilter = $db->filterstorekey  ( sub { ... } );\n$oldfilter = $db->filterstorevalue( sub { ... } );\n$oldfilter = $db->filterfetchkey  ( sub { ... } );\n$oldfilter = $db->filterfetchvalue( sub { ... } );",
    "sections": {
        "NAME": {
            "content": "perldbmfilter - Perl DBM Filters\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "$db = tie %hash, 'DBM', ...\n\n$oldfilter = $db->filterstorekey  ( sub { ... } );\n$oldfilter = $db->filterstorevalue( sub { ... } );\n$oldfilter = $db->filterfetchkey  ( sub { ... } );\n$oldfilter = $db->filterfetchvalue( sub { ... } );\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "The four \"filter*\" methods shown above are available in all the DBM modules that ship with\nPerl, namely DBFile, GDBMFile, NDBMFile, ODBMFile and SDBMFile.\n\nEach of the methods works identically, and is used to install (or uninstall) a single DBM\nFilter. The only difference between them is the place that the filter is installed.\n\nTo summarise:\n",
            "subsections": [
                {
                    "name": "filter_store_key",
                    "content": "If a filter has been installed with this method, it will be invoked every time you write\na key to a DBM database.\n"
                },
                {
                    "name": "filter_store_value",
                    "content": "If a filter has been installed with this method, it will be invoked every time you write\na value to a DBM database.\n"
                },
                {
                    "name": "filter_fetch_key",
                    "content": "If  a filter has been installed with this method, it will be invoked every time you read\na key from a DBM database.\n"
                },
                {
                    "name": "filter_fetch_value",
                    "content": "If a filter has been installed with this method, it will be invoked every time you  read\na value from a DBM database.\n\nYou can use any combination of the methods from none to all four.\n\nAll filter methods return the existing filter, if present, or \"undef\" if not.\n\nTo delete a filter pass \"undef\" to it.\n"
                },
                {
                    "name": "The Filter",
                    "content": "When  each  filter  is called by Perl, a local copy of $ will contain the key or value to be\nfiltered. Filtering is achieved by modifying the contents of $. The  return  code  from  the\nfilter is ignored.\n"
                },
                {
                    "name": "An Example: the NULL termination problem.",
                    "content": "DBM  Filters  are  useful  for  a  class  of  problems where you always want to make the same\ntransformation to all keys, all values or both.\n\nFor example, consider the following scenario. You have a DBM database that you need to  share\nwith a third-party C application. The C application assumes that all keys and values are NULL\nterminated.  Unfortunately when Perl writes to DBM databases it doesn't use NULL termination,\nso your Perl application will have to manage NULL termination itself. When you write  to  the\ndatabase you will have to use something like this:\n\n$hash{\"$key\\0\"} = \"$value\\0\";\n\nSimilarly  the  NULL  needs  to  be taken into account when you are considering the length of\nexisting keys/values.\n\nIt would be much better if  you  could  ignore  the  NULL  terminations  issue  in  the  main\napplication  code  and  have a mechanism that automatically added the terminating NULL to all\nkeys and values whenever you write to the database and have them removed when you  read  from\nthe  database.  As  I'm sure you have already guessed, this is a problem that DBM Filters can\nfix very easily.\n\nuse v5.36;\nuse SDBMFile;\nuse Fcntl;\n\nmy %hash;\nmy $filename = \"filt\";\nunlink $filename;\n\nmy $db = tie(%hash, 'SDBMFile', $filename, ORDWR|OCREAT, 0640)\nor die \"Cannot open $filename: $!\\n\";\n\n# Install DBM Filters\n$db->filterfetchkey  ( sub { s/\\0$//    } );\n$db->filterstorekey  ( sub { $ .= \"\\0\" } );\n$db->filterfetchvalue(\nsub { no warnings 'uninitialized'; s/\\0$// } );\n$db->filterstorevalue( sub { $ .= \"\\0\" } );\n\n$hash{\"abc\"} = \"def\";\nmy $a = $hash{\"ABC\"};\n# ...\nundef $db;\nuntie %hash;\n\nThe code above uses SDBMFile, but it will work with any of the DBM modules.\n\nHopefully the contents of each of  the  filters  should  be  self-explanatory.  Both  \"fetch\"\nfilters remove the terminating NULL, and both \"store\" filters add a terminating NULL.\n"
                },
                {
                    "name": "Another Example: Key is a C int.",
                    "content": "Here  is  another  real-life  example.  By default, whenever Perl writes to a DBM database it\nalways writes the key and value as strings. So when you use this:\n\n$hash{12345} = \"something\";\n\nthe key 12345 will get stored in the DBM database as  the  5  byte  string  \"12345\".  If  you\nactually  want  the  key  to  be  stored in the DBM database as a C int, you will have to use\n\"pack\" when writing, and \"unpack\" when reading.\n\nHere is a DBM Filter that does it:\n\nuse v5.36;\nuse DBFile;\nmy %hash;\nmy $filename = \"filt\";\nunlink $filename;\n\n\nmy $db = tie %hash, 'DBFile', $filename, OCREAT|ORDWR, 0666,\n$DBHASH or die \"Cannot open $filename: $!\\n\";\n\n$db->filterfetchkey  ( sub { $ = unpack(\"i\", $) } );\n$db->filterstorekey  ( sub { $ = pack (\"i\", $) } );\n$hash{123} = \"def\";\n# ...\nundef $db;\nuntie %hash;\n\nThe code above uses DBFile, but again it will work with any of the DBM modules.\n\nThis time only two filters have been used; we only need to manipulate  the  contents  of  the\nkey, so it wasn't necessary to install any value filters.\n"
                }
            ]
        },
        "SEE ALSO": {
            "content": "DBFile, GDBMFile, NDBMFile, ODBMFile and SDBMFile.\n",
            "subsections": []
        },
        "AUTHOR": {
            "content": "Paul Marquess\n\nperl v5.38.2                                 2026-08-18                             PERLDBMFILTER(1)",
            "subsections": []
        }
    },
    "summary": "perldbmfilter - Perl DBM Filters",
    "flags": [],
    "examples": [],
    "see_also": []
}