5.2 The editmap Program

The editmap program is supplied in source form with V8.12 and above sendmail. It can also be supplied in pre-compiled form by your vendor.^[3] It is used to edit or view individual items in database files and is run from the command line like this:

^[3] Whenever you update to a newer version of sendmail, always update the version of the editmap program in parallel. Old or vendor versions might not interoperate well with an updated sendmail.

% editmap -q  switches dbtype dbfile key  
% editmap -x  switches dbtype dbfile key  
% editmap -u  switches dbtype dbfile key new_value  

We'll discuss the switches in the next section. The dbtype can be dbm (which uses the ndbm(3) library routines), hash, or btree (both of which use the db(3) library routines). The dbfile is the location and name (full path or relative name) for the database file that will be edited. For dbm files, the .pag and .dir suffixes are added automatically. For the db files, the .db suffix will be added automatically if it is not already included in the name.

The key is the name of the item in the database that you wish to view or edit. If you are just viewing an item's value, include the -q command-line flag and omit the new_value. If you need to delete an item and its value, include the -x command-line flag and omit the new_value. If you are updating an item's value, or inserting a new value, include the -u command-line switch and the new_value. The new_value, when present, should be quoted to prevent internal characters and spaces from being interpreted by the shell. For example:

'$0@'  the new_value should be quoted

In addition, some special characters, such as !, need to be prefixed with a backslash to prevent them from being interpreted by some shells (such as the csh and tcsh shells):

'%0\!%1@%2'  prefix the ! character with a backslash

The editmap program opens the database for reading when the -q is specified, and for read/write when the -u or -x is specified. If none of those three command-line switches is present, editmap prints a usage message and exits. If you attempt to update (with -u) or delete from (with -x) a database for which you lack write permission, the following error will print, and editmap will exit:

editmap: error opening type dbtype map dbfile:  Permission denied

If you specify a key that does not exist in the database, editmap will print the following error and exit:

editmap: couldn't find key key in map dbfile  

The editmap program reads the sendmail configuration file to find a value for the TrustedUser option (TrustedUser). If that option is set, and if editmap is run by root, editmap will change the ownership of the database to the user specified by the TrustedUser option.

The editmap program should not be used to edit a database file for which you have the original text source file. With the original text it is always better to generate a new database using makemap (Section 5.5). That way you can track changes in human readable form, and avoid getting the source and database files out of sync.^[4]

^[4] For very large databases, it might be faster to use editmap than to rebuild the database from source text each time.

The editmap program is useful to fix problems in databases for which you lack the original text source. Vendor-supplied databases frequently fall into this category, as do distributed databases for which the original source is protected or lost. In this latter instance, however, it might be better to dump the database with makemap (Section 5.5), and use that dump as source to create a new, original text file.

5.2.1 editmap Command-Line Switches

The command-line switches for editmap precede the dbtype:

% editmap -q  switches dbtype dbfile key  
% editmap -x  switches dbtype dbfile key  
% editmap -u  switches dbtype dbfile key new_value  

Switches are single characters, prefixed with a - character. Switches can also be combined:

-N -f  good
-Nf    also good

The complete list of switches is shown in Table 5-3. (See getopt(3) for additional information about the way switches are handled.) In the sections that follow we describe each switch in detail.