Relax chown requirements when check_owner is false

[hcoop/debian/exim4.git] / debian / manpages / exim_dbmbuild.8

.\"                                      Hey, EMACS: -*- nroff -*-
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.TH EXIM_DBMBUILD 8 "March 26, 2003"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.\" \(oqthis text is enclosed in single quotes\(cq
.\" \(lqthis text is enclosed in double quotes\(rq
.SH NAME
exim_dbmbuild \- Build a DBM file.
.SH SYNOPSIS
.B exim_dbmbuild
.I [\-nolc] [\-nozero] [\-noduperr] [\-nowarn] inputfile|\- outputfile

.SH DESCRIPTION
The
.B exim_dbmbuild
program reads an input file containing keys and data in
the format used by the
.I lsearch
lookup (see section 9.1).
It writes a DBM file using the lower-cased alias names as keys and the
remainder of the information as data.
The lower-casing can be prevented by calling the program with the
.I \-nolc
option.

A terminating zero is included as part of the key string.
This is expected by the dbm lookup type.
However, if the option
.I \-nozero
is given, 
.B exim_dbmbuild
creates files without terminating zeroes in either the key strings or the
data strings.
The 
.I dbmnz
lookup type can be used with such files.

The program requires two arguments: the name of the input file (which can
be a single hyphen to indicate the standard input), and the name of the
output file.
It creates the output under a temporary name, and then renames it if all
went well.
If the native DB interface is in use (USE_DB is set in a compile-time
configuration file - this is common in free versions of Unix) the two file
names must be different, because in this mode the Berkeley DB functions
create a single output file using exactly the name given.
For example,

  exim_dbmbuild /etc/aliases /etc/aliases.db

reads the system alias file and creates a DBM version of it in
/etc/aliases.db.

In systems that use the
.I ndbm
routines (mostly proprietary versions of Unix), two files are used, with the
suffixes .dir and .pag.
In this environment, the suffixes are added to the second argument of
.B exim_dbmbuild,
so it can be the same as the first.
This is also the case when the Berkeley functions are used in
compatibility mode (though this is not recommended), because in that case
it adds a .db suffix to the file name.

If a duplicate key is encountered, the program outputs a warning, and when
it finishes, its return code is 1 rather than zero, unless the
.I \-noduperr
option is used.
By default, only the first of a set of duplicates is used - this makes it
compatible with lsearch lookups.
There is an option
.I \-lastdup
which causes it to use the data for the last duplicate instead.
There is also an option
.I \-nowarn,
which stops it listing duplicate keys to \(lqstderr\(rq.
For other errors, where it doesn't actually make a new file, the return
code is 2.

.SH BUGS
This manual page needs a major re-work. If somebody knows better groff
than us and has more experience in writing manual pages, any patches
would be greatly appreciated.

.SH SEE ALSO
.BR exim (8),
/usr/share/doc/exim4\-base/

.SH AUTHOR
This manual page was stitched together from spec.txt by
Andreas Metzler <ametzler at downhill.at.eu.org>,
for the Debian GNU/Linux system (but may be used by others).