Table of Contents for

sendmail, 4th Edition

The top-level Build script can be used to do a global build across all programs. For example, you can do this to build all the programs:

% ./Build

All the commands you can use with the master Build (The Build Script on page 346) are available to this Build.

The contrib directory contains user-contributed and unsupported code. Among its contents are perl(1) scripts, shell scripts, C-language source code, and patches. The README file in this directory explains some of the policy surrounding the programs. For more complete information you will need to dig through the source files yourself.

If you have software that you would like to see included in this directory, email a description of that program to sendmail@sendmail.org.

The devtools directory contains all the scripts and m4(1) source used to build sendmail and its libraries and companion programs. The README file there briefly describes the m4 macros used to configure your build process. We describe the current macros in Compile-Time Macro Reference on page 108. You should consult this file whenever a new release is issued because it will always have the most up-to-date information.

The devtools/Site directory is the default location for your m4 build configuration files. The README in that directory describes the strategy used to locate a build configuration file. Note that the -f command-line switch (-f on page 350) for the Build command can override use of that directory. Also note that the -Q command-line switch (-Q on page 352) for the Build command modifies the way an m4 file is found.

The doc directory contains only one subdirectory, op. The doc/op directory contains the sendmail “INSTALLATION AND OPERATION GUIDE.” That guide is supplied in troff(1) source (op.me), and as a ready-to-print PostScript document (op.ps).

This is the main document distributed with sendmail that describes that program. It is succinct, and it is always a good place to start for a quick but detailed overview.

The include directory contains four subdirectories. The include/libsmdb directory contains files that support the use of the libsmdb library of common database routines. The include/sendmail directory contains files useful for sendmail and for programs that share the sendmail definitions and declarations (for example, the mailstats program). The include/libmilter directory contains files that support use of the libmilter library of routines. The include/sm directory contains files that support use of the libsm library of routines.

The INSTALL file contains a brief list of steps for compiling and installing sendmail.

The KNOWNBUGS file contains a (not always up-to-date) list of the most difficult bugs to fix in the sendmail program. Presence of this file ought not suggest that sendmail is distributed with bugs. Rather, it should assure you that reported bugs are admitted to and dealt with.

If you encounter behavior with sendmail that appears to be a bug in sendmail and not in another program, document that bug carefully so that it can be repeated, then find the email address to which to submit your report at http://www.sendmail.org/support/.

If you encounter a security problem with sendmail, use the fingerprint and public key stored in the PGPKEYS file to encrypt a message before submitting a report. Always try to avoid sending security-related email in clear text.

The sendmail folks have defined a mail filter API^[29] called Milter. Using this API, third-party programmers (you, for example) can design programs to access mail messages as they are being processed by sendmail. Such real-time access allows email message content to be filtered and possibly rejected based on content—a potentially powerful antispam tool.

The README file in this directory describes the steps needed to design, compile, and run such a filter. But beware. The use of this API and creation of a filter program require the use of POSIX threads. If your OS lacks POSIX thread support, you will not be able to use this API.

For systems that support POSIX threads, we illustrate the creation and use of a mail filter program in Chapter 26 on page 1169.

To support many of the new features in sendmail, and to pave the way for more sophisticated versions in the future, the designers of sendmail decided to create a replacement for many of the routines in the standard C library. A quick glance at the libsm directory will reveal replacements, for example, of fput(3) and ungetc(3).

A library of these routines is built and used by sendmail automatically when you build that program. You need do nothing special here.

In the rare event that you need to port sendmail to an entirely new operating system, you will need to study the file README in the libsm directory, and examine (and perhaps tweak) some of the various C source files there.

Prior to V8.14, whenever sendmail was built, the various checks in the libsm directory were also built and executed. Beginning with V8.14, these checks are no longer automatically run. Instead, you must run them by hand using the following commands:

% cd libsm
% make -s check
← a great deal of output here
===================
All 18 tests passed
===================

Here, the -s switch was used with make(1) to suppress most of the compiler invocation lines. The check caused all the tests to be built and executed. The last three lines show that all the tests succeeded. If any of the tests fail on your operating system, examine the test output to see what went wrong. Perhaps you will need to define or undefine a build-time macro (Build m4 Macro Reference on page 69). For example, if the test hung like this:

This test takes about 8 seconds.
If it takes longer than 30 seconds, please interrupt it
and compile again without semaphore support, i.e.,-DSM_CONF_SEM=0

you would need to undefine SM_CONF_SEM (SM_... on page 139) and rebuild.

The libsmdb directory contains source for a library that supports opening, reading, writing, searching, and closing database files. The types of database files supported are Berkeley db (versions 1, 2, and 3), btree and hash, and ndbm. This library is used by makemap, praliases, editmap, and vacation.

The libsmutil directory contains source for a library of routines that are useful to sendmail and its companion programs. Among the routines is support for debugging with -d (The Syntax of -d on page 530), the checking of safe files and directories (-d44.4 on page 569), and other useful tasks.

The LICENSE file contains the legal jargon surrounding how, when, and why you can use the source and the programs produced by that source. It also includes instructions on how to get updated license information.

The top-level Makefile file can be used to globally compile all the programs in the distribution. It uses two environment variables: CONFIG and FLAGS. These can either be put into make’s environment as part of its command line, or put into your shell’s environment. The first technique is used when you wish to condition one of these variables just once or so. The second is useful when a variable setting is needed over and over during a prolonged development session.

The first technique looks like this:

% make CONFIG="-Q Server" FLAGS="-c"

Here, the CONFIG variable is used to set the location for your m4 build file, and the FLAGS variable is used to pass any other command-line switches you need to the Build program.

The second technique begins by conditioning your shell’s environment variables:

setenv CONFIG "-Q Server"                  ← the C shell and derivatives
CONFIG="-Q Server" ; export CONFIG         ← the Bourne shell and derivatives
setenv FLAGS "-c"                          ← the C shell and derivatives
FLAGS="-c" ; export FLAGS                  ← the Bourne shell and derivatives

You will see the result of declaring these two environment variables when you run the make(1) program, this time without having to specify those two variables in the command line:

% make all

See The Build Script on page 346 for an overview of how Build works, and what the -c and -Q switches do.

The PGPKEYS file contains the keys used to validate the authenticity of the sendmail distribution. To use them, however, you first need to unpack the distribution, then run pgp on the uncompressed tar file. This might give you the impression of safety, but be aware that a fake distribution can contain fake keys in a fake PGPKEYS file, and the fake PGPKEYS file will verify the fake distribution.

See Download the Source on page 42 for a description of the better way to validate your sendmail distribution.

The README file’s name should encourage you to do just what it says. Read that file whenever you download a fresh distribution. It contains lots of useful and up-to-date information.

Each release of sendmail is packaged with a file called RELEASE_NOTES, located in the top level of the source distribution. The RELEASE_NOTES file itemizes new features that have been added to each particular version of sendmail since version 8.1 (released in 1993). This file is very complete but, on the downside, can be difficult to parse.

Basically, the RELEASE_NOTES file is divided into sections, each of which deals with a separate release of sendmail. Each begins with a single line that contains the version number of the sendmail release, followed by a slash, followed by the version number of the configuration file release, followed by the date of the release. For example:

8.14.1/8.14.1  2007/04/03

Here, the second release of the V8.14 series (8.14.1) is indicated.^[30] The version and date are followed by sections that each document a change in the sendmail binary. Some sections are prefixed with a keyword and colon. For the most part, those keyword sections describe a change in something other than the binary^[31] and, for example, can look like this:

SECURITY: Some security matter was fixed, and the description of
        that fix will appear here.
This item describes a change made to the sendmail binary.
LIBMILTER: This documents a change made to one of the files in the
        libmilter directory.

The keywords and the meaning of each are shown in Table 2-2.

The test directory contains C-language programs that help the development team at sendmail.com solve problems concerning the porting of sendmail to other architectures. They are of interest only if you intend to port sendmail to a currently unsupported platform. Each .c file is somewhat self-documenting.

The first step in compiling sendmail is to establish an object directory and a Makefile that is appropriate to your machine architecture and operating system. You do this by running the Build script in the sendmail source directory:^[32]

% cd sendmail
% ./Build -n
Configuration: pfx=, os=SunOS, rel=4.1.4, rbase=4, rroot=4.1, arch=sun4, sfx=
Using M4=/usr/5bin/m4
Creating ../obj.SunOS.4.1.4.sun4/sendmail using ../devtools/OS/SunOS    ← many more
lines here
%

Here, Build found that our machine was a sun4, running the SunOS 4.1.4 release of Unix. Build then created the working directory ../obj.SunOS.4.1.4.sun4, set up symbolic links to all the source files in that directory, and finally generated a Makefile there.

The Build program understands several command-line switches that can be used to modify its behavior (see Table 2-3). Any switch or other command-line argument that is not in that table is carried through and passed as is to the make(1) program. For example, specifying the -n switch to Build (in the earlier example) caused Build to pass that switch to make(1), thereby preventing make(1) from actually building sendmail.

The make(1) program^[33] is used to compile and install sendmail. The Build script creates not only an object working directory, but also an appropriate Makefile in that directory using m4(1). Unless you tell Build to do otherwise, the Makefile it creates will be based solely on information it finds in the appropriate devtools/OS and devtools/Site subdirectories.

For most sites, this default behavior will produce the desired result. For other sites, different defaults are needed.

In this section, we discuss those m4 directives necessary for building a Makefile. To understand m4(1), leap ahead to Chapter 17 on page 584, review the information there, then return here.

Creating a Makefile with Build is simplicity itself. First decide whether you wish to maintain your m4 file inside the sendmail source tree, or outside it. If you choose to maintain your m4 file inside the source tree, just name it devtools/Site/site.config.m4 (see Build sendmail on page 53 for details) and run Build like this:

% ./Build

Note that here we have chosen to maintain all our Build m4 files inside the sendmail source tree. This approach allows administrators to rebuild sendmail without needing to remember where the m4 file is located.

If you choose to maintain your m4 file outside the source tree, use the -f command-line switch with Build to specify the location of that file:

% ./Build -f /usr/local/configs/sendmail/oursite.m4

Note that here we have chosen to maintain all our Build m4 files in a directory that is outside the sendmail distribution. This approach allows you to upgrade to new releases of sendmail without having to remember to copy the devtools/Site directory each time. The downside to this approach is that you must remember to use the -f command-line switch every time you build. If you fail to remember, or if someone else builds without knowing the need for -f, the created sendmail binary may not work as you expect or might lack the abilities you require.

Your m4 file is built using the directives shown in Table 2-4, which are described more fully in the sections that follow. One example of an m4 file might look like this:

define(`confOPTIMIZE', `-g')
define(`confENVDEF', `-DMATCHGECOS=0')
APPENDDEF(`confMAPDEF', `-DNIS')

Here we compile with -g to help debug new code we added, and with -DMATCHGECOS=0 to turn off support for fuzzy name matching (MATCHGECOS on page 120). Then we declare that we want to use nis(3) for aliases (with -DNIS).

Before creating your own m4 files, be sure to read devtools/README. That file always contains the latest information about building sendmail with m4(1).

After you have finished configuring your m4 build file, you are ready to build sendmail. First run the following command in the sendmail source directory:

# ./Build -f /path/to/your/m4/file -n

This command first creates the obj directory in which sendmail will be built, populates that directory with symbolic links, and places a configured Makefile there. It then displays all the commands that make will generate without actually executing them.

If you are building a plain vanilla sendmail, or if you have placed your m4 file in the devtools/Site directory, you can omit the -f and the path to your m4 build file. If you wish to tune sendmail to your custom needs first, before running Build, you need to create an m4 file (as discussed earlier).

You can create your Build m4 files either outside the sendmail distribution or inside a special directory inside the distribution. If you maintain them outside, you will have to use the -f switch each time you build, but will avoid having to copy them again for each release of sendmail.

If you create a special file inside the devtools/Site directory, that file will be included without the need for an -f. The name of the file is site.config.m4. If you want to maintain several master files in that directory, you can do so depending on your operating system type. When Build runs, it prints a line that looks like the following, split to fit the page:

Configuration: pfx=, os=SunOS, rel=4.1.4, rbase=4, rroot=4.1, arch=sun4, sfx=,variant=
optimized

Here, the name of the operating system is printed following the os=. If you were to create a file in the devtools/Site directory called site.SunOS.m4, it, too, would be automatically found and used without the need for an -f switch.

If you have defined the environment variable SENDMAIL_SUFFIX, the sfx= will be assigned that value with a dot in front of it. That value can be used to further tune the name of the files in devtools/Site. For example, if SENDMAIL_SUFFIX is defined as server, the Build script will find and use a file called site.SunOS.server.m4.

The devtools/Site directory is first searched for the literal name site.config.m4. If that is not found, it is searched for the file named site.os=sfx=.m4, and after that for the file named site.os=.m4.

If all looks well after you have run Build with an -n, you can run it again, this time without the -n.

After you run Build, you will likely find that you need to change one or more items in your m4 build file. Whenever you change that file, you will need to use the -c switch with Build to force it to create a new Makefile with your new information in it. You do this by adding the -c switch to Build’s command line:

% ./Build -c -f ../../builds/oursite.m4
% ./Build -c                               ← if using devtools/Site

For large compiles, such as sendmail, this process can be lengthy, but it is necessary, for without it your m4 build file changes will mysteriously appear to have no effect.

If, when you compiled sendmail, the linker reported _res_ routines as missing, you might need to specify the resolver library with -lresolv:

APPENDDEF(`confLIBS', `-lresolv')

This shows one way to include that library with m4 builds. Another way might look like this:

APPENDDEF(`confLIBS', `/usr/local/lib/libresolv.a')

To ensure that sendmail achieves its optimum use of lookups, make sure your resolver library is derived from the latest BIND release: BIND 8.3.3.^[34] You might also need to include -l44bsd on the LIBS= line if you are running BIND 4.9.

The tricky part is finding out which resolver library your system supports. With SunOS systems, for example, resolver support in the standard C library uses nis for name resolution. Although this setup might be good for most applications, it is inappropriate for sendmail. SunOS supplies a libresolv.a, but it is based on BIND 4.3 and so should probably be replaced with a newer version.

If your resolver library is not the correct one, you need to compile and install the newest version. You should do this even if it is used only by sendmail.

Some systems define sys_errlist differently than sendmail does. On such systems, you might see a spurious warning about sys_errlist being redefined.

In general, you should never get this error. But if you are building sendmail on a system that is similar to, but not identical to, one already supported, you might see such a warning. See ERRLIST_PREDEFINED on page 112 for a description of how to use ERRLIST_PREDEFINED to fix the problem, should it occur.

Some older compilers don’t recognize the "void *" expression. With such compilers, you might see an error something like this:

"./sendmail.h", line 735: syntax error at or near variable name "void"

If you get an error like this, you should define ARBPTR_T (...T on page 148) like this:

APPENDDEF(`confENVDEF', `-DARBPTR_T=\"char *\"')

If you are building sendmail using a compiler that claims to be ANSI-compliant, but is not really so, you might see an error like this:

ld: Undefined symbol
       strtoul

If you do, your compiler is mildly broken. Fortunately, sendmail offers an easy solution. Just edit your Build m4 file, and add a line such as the following:

APPENDDEF(`confENVDEF',`-DBROKEN_ANSI_LIBRARY=1')

Rebuild with the -c Build switch, and this problem will go away.

On old Unix systems and those that run non-ANSI-compliant C-language compilers, the following error might appear when compiling sendmail:

"daemon.c", line 678: warning: & before array or function: ignored
"daemon.c", line 678: warning: illegal pointer combination

These warnings are harmless and can be ignored.

As you watch the output while sendmail builds, you might notice commands being executed that you disagree with. Formatting of manuals, for example, might be a step you would rather skip. For each such problem, review the information in this and the next chapter. Correct your m4 build file and rerun Build, but this time add the -c switch. That switch causes Build to clear out the obj directory, then create a new Makefile with your new m4 build file settings:

# ./Build -c -f /path/to/your/m4/file

This can be an iterative process, so be patient.

Tuning sendmail to exactly fit your particular site’s needs can be a learning process. Be patient, as this and the next chapter contain a huge amount of information, and the way various macros interact can be confusing at first.

When sendmail is run as non-set-user-id root, it is run either as root when it is invoked by the root user, or as another user when it should not run as root. The sendmail distribution clearly cannot divine ahead of time what user you wish to use when not running sendmail as root. It could have chosen nobody, for example, but the user nobody does not exist under all versions of Unix.

You can choose your own username by using the confMSPQOWN build macro (confMSPQOWN on page 91) to place a line such as this into your build m4 file:

define(`confMSPQOWN', `nullmail')

If you change the username, you will also have to build and install your own submit.cf file, and include in the mc file, for that creation, a definition for the new users with the RunAsUser option (RunAsUser on page 1083), like this:

FEATURE(`msp')
define(`confRUN_AS_USER', `nullmail')

If you don’t change the name, sendmail will use the name smmsp, which stands for SendMail Message Submission Program.

Whether your keep the username chosen by the sendmail distribution, or choose a name of your own, you will need to add that name to your system’s passwd(5) services. Here we show how to do this with the traditional Unix passwd(5) file. Consider the lessons taught here, and apply them to your passwd(5) services in the manner most suitable to your Unix system:

nullmail:*:32764:32764:Null Mail:/no/such/directory:/bin/false

In this example of a line from a traditional Unix passwd(5) file, we have elected to create the user named nullmail. The line is divided into five fields by colons. The first field is the name of the new user. The second field is the user’s password. But because this user is not an actual person, we disable the password with an asterisk. On some systems you will need to put an x in this field, or the word NOPASSWORD. See your system documentation for what to use in this field to disable a password for this new user.

The third and fourth fields are the user and group ID for the user. Here, we chose high numbers that are unlikely to conflict with actual user numbers. Some versions of Unix restrict the size of the numbers you can use. See your system’s documentation. The fifth field is called the gecos field. It contains the full name of the users. We chose Null Mail, but you can choose any name you desire.

The last two fields are the home directory and shell for this user. The home directory should not exist, nor should it have the potential of ever existing. The shell should be a program that will never successfully run. We chose /bin/false because that program always exits with a nonzero (failure) value.

When sendmail is run as non-set-user-id root, it is run either as root when it is invoked by the root user (in which case it can read all files), or as another user when it should not run as root. To enable the sendmail program to read and write its queue when it is not root, it needs to always run as a predefined group. It does this by having its set-group-id permission set, and by running under an appropriate group. The sendmail distribution clearly cannot divine ahead of time what group you wish to use when not running sendmail as set-group-id. It could have chosen nogroup, for example, but the user nogroup does not exist under all versions of Unix.

You can choose your own group by using the confGBINGRP build macro (confGBIN... on page 76) to place a line such as the following into your build m4 file. But don’t chose a group that is shared by any other user. For security reasons, the group you choose should be used only by sendmail:

define(`confGBINGRP', `nullgroup')

If you change the group, you will also have to build and install your own submit.cf file, and include in the mc file, for that creation, a definition for that new group with the RunAsUser option (The RunAsUser option (V8.8 and above) on page 176), like this:

FEATURE(`msp')
define(`confRUN_AS_USER', `:nullgroup')

Note that the same option sets both the user and the group. A combined declaration might look like this:

FEATURE(`msp')
define(`confRUN_AS_USER', `nullmail:nullgroup')

If you don’t change the group, sendmail will use the group smmsp.

Whether you keep the group name chosen by the sendmail distribution, or choose a name of your own, you will need to add that name to your system’s group(5) services. Here we show how to do this with the traditional Unix group(5) file. Consider the lessons taught here, and apply them to your group(5) services in the manner most suitable to your Unix system:

nullgroup:*:32764:

In this example of a line from a traditional Unix group(5) file, we have elected to create the group named nullgroup. The line is divided into four fields by colons. The first field is the name of the new group. The second field is the group’s password. Because this group is not used by actual people, we disable the password with an asterisk. On some systems you will put an x in this field, or the word NOPASSWORD. See your system documentation to learn what is best to use in this field to disable a password for this new group.

The third field contains the group number. That number should match the number used in the group field of the passwd(5) file. The last field contains the usernames of those that should also belong to this group. Generally, this will be an empty field.

In a non-set-user-id root world, you run sendmail differently than the traditional manner to which you have become accustomed. There are two differences that you should attend to before installing the new non-set-user-id root setup. First, you need to decide how to drain the local message submission queue. Second, you need to decide on a name to differentiate the two roles with the syslog(8) facility.

For local mail submission, sendmail will use a separate queue, one that is group read/write by the group discussed in the previous section. The sendmail program, in local message submission mode, sends a message and then exits. As a consequence, there is nothing running that can drain that separate queue of any messages that might be deferred there. The best way to drain it is with a queue processing daemon, such as this:

/usr/sbin/sendmail -Ac -q30m

Here, the -Ac command-line switch tells sendmail to use the configuration file named submit.cf. This is the special message submission configuration file that knows about the second queue. The -q30m command-line switch causes sendmail to wake up once each 30 minutes and process any deferred messages it finds in the second queue.^[38]

To differentiate one sendmail from another in the logs created by the syslog(8) facility, you can use the -L command-line switch (-L on page 243). One suggestion looks like this:

/usr/sbin/sendmail -L mta-daemon -bd -q30m
/usr/sbin/sendmail -L msp-queue -Ac -q30m

The first line is the invocation of sendmail that is most common (with the -bd -q30m). The second line has been added to drain the second (mail submission) queue. The first will contain the identifier mta-daemon in its syslog(8) logfiles. The second will contain the identifier msp-queue. These identifiers are only suggestions, and you might prefer something more suitable to your site’s needs.

The sendmail program is usually started from a script in the etc directory. On System-V-based versions of Unix, that file is usually found in the /etc/init.d directory. On other versions of Unix, that file could live directly in the etc directory, and might be called rc or rc.local. Whichever file contains the commands to start sendmail on your system, look at it and determine how sendmail is currently started and stopped. You might, for example, find lines such as this, from a FreeBSD 4.0 sendmail startup file called rc:

case ${sendmail_enable} in
[Yy][Ee][Ss])
        if [ -r /etc/mail/sendmail.cf ]; then
                echo -n ` sendmail';    /usr/sbin/sendmail ${sendmail_flags}
        fi
        ;;
esac

To modify this setup for use in a non-set-user-id root scheme, you would need to add the following line to your /etc/rc.conf file:

sendmail_flags="${sendmail_flags} -L mta-daemon"

Then create the file /etc/rc.local (if it does not already exist), and add the following lines to it:

case ${sendmail_enable} in
[Yy][Ee][Ss])
        if [ -r /etc/mail/sendmail.cf ]; then
                echo -n ` msp-queue';     /usr/sbin/sendmail -L msp-queue -q30m
        fi
        ;;
esac

Take the time, now, to investigate how sendmail is started and stopped on your system. The new non-set-user-id root scheme will doubtless require special modifications on your part. Beginning with Solaris 7, for example, the pkill(8) command, as it is set up in /etc/init.d/sendmail, will not stop a sendmail that is running other than as root.

The submit.cf file is built for you automatically when you install sendmail.^[39] When you run make install, the following is one of the commands executed:

cd ../../cf/cf && make install-submit-cf

This command will create and install a default /etc/mail/submit.cf file if that file does not already exist. For most sites, this default will be suitable for your use as is. If you customize at all, however, you will need to create your own submit.cf file. If, for example, you changed the user and group names for the non-set-user-id root version of sendmail with the following in your build m4 file:

define(`confMSPQOWN', `nullmail')
define(`confGBINGRP', `nullgroup')

you will need to create a custom submit.cf file. You create a custom submit.cf file just like you create a sendmail.cf file (Configure with m4 on page 587). You begin by creating a file called submit.mc. You can use the file cf/cf/submit.mc as a template for your own, or you can edit that file directly. If you edit that file directly, you will need to copy your changes to the same directory each time you upgrade sendmail to a new version.

Note that the name submit.cf is hardcoded and cannot be changed. When sendmail runs, unless you have built it to do otherwise, it will look for submit.cf in the same directory that it looks for its standard configuration file. If you change the location of the standard configuration file with the _PATH_SENDMAILCF build-time macro (_PATH... on page 131), you will also want to change the directory in which the submit.cf file is located. That directory is defined with the _DIR_SENDMAILCF build-time macro.^[40] For example, your build m4 file might look, in part, like this:

APPENDDEF(`confENVDEF', `-D_PATH_SENDMAILCF=\"/opt/sendmail/sendmail.cf\"')
APPENDDEF(`confENVDEF', `-D_DIR_SENDMAILCF=\"/opt/sendmail/\"')

Here, the first line changes the location of the sendmail.cf file. The second line is necessary so that sendmail will look for submit.cf in that same directory. Without this second line, sendmail would look for sendmail.cf in /opt/sendmail, but would look for submit.cf in the default location, /etc/mail.

Note that a Build install will always try to place the submit.cf file into a directory that begins with /etc/mail. But you can prefix this directory with another directory name, as shown here:

# ./Build -E DESTDIR=/opt/sendmail install

This will cause the submit.cf file to be installed in the /opt/sendmail/etc/mail directory. If you have changed the location of your configuration files, as shown earlier, you will have to manually move the submit.cf file from its default installed location to your chosen location.^[41]

Table 2-5 shows how the Build process parallels the creation of the submit.cf file in certain limited ways.

Note again that _DIR_SENDMAILCF does not affect where Build install places the submit.cf file.

Finally, note that by renaming or relocating the queue directory with the confMSP_QUEUE_DIRBuild macro (confMSP_QUEUE_DIR on page 91), the MSP_QUEUE_DIR mc macro must also be updated so that a correct submit.cf file will be created.

Beginning with V8.10 sendmail, the configuration file and other files are located in /etc/mail. When installing, the following error can occur if /etc/mail is not a directory:

install -c -o bin -g bin -m 444 helpfile /etc/mail/helpfile
install: /etc/mail/helpfile: Not a directory
*** Error code 1

Here, /etc/mail is not a directory, but is instead a file. If the file /etc/mail is serving no current purpose, consider removing or renaming it and rerunning Build. If that file is still important, take the time now to discover why and change its name. All modern versions of sendmail are grounded in the /etc/mail directory, so taking time now to free that name will be well spent.

The name of the default directory, /etc/mail, is stored in the MAIL_SETTINGS_DIR mc configuration macro. You can redefine this macro to relocate that default to a new directory, but if you do, be certain that the declaration ends in a slash character:

define(`MAIL_SETTINGS_DIR', `/opt/sendmail/etc/')
                                              ↑
                                        must end in a slash

Note that the MAIL_SETTINGS_DIR mc configuration macro must specify a full pathname, one that starts with a slash. If it does not specify a full pathname, unexpected problems might arise when you run sendmail.

When upgrading from the vendor’s version of sendmail to the open source version of sendmail, vendor assumptions about program locations might not agree with the new sendmail locations. One way to check for a mismatch is to look at the version of sendmail under each of its names. Consider, for example, a check to see whether sendmail and the newaliases program are the same:

% newaliases -d0.1 < /dev/null | head −1
Version 8.9.2
% /usr/lib/sendmail -d0.1 < /dev/null | head −1
Version 8.12.7

Here we find that newaliases is not a symbolic link to sendmail as we expected. Finding the cause of this mismatch can take some investigation. Under BSDI 3.x, for example, the /usr/sbin/newaliases program is a hard link, not a symbolic link, so replacing sendmail will not affect it.

Append to an existing define Build directive

The APPENDDEF( ) m4 directive allows you to append new information to information that was previously defined. To illustrate, consider that the locations of your #include files are sometimes preset in the appropriate devtools/OS directory. For OS/UXPDS.V10, for example, the default is:

-I/usr/include -I/usr/ucbinclude

You can use this APPENDDEF( ) directive to add another directory to this list, without erasing what is already there:

APPENDDEF(`confINCDIRS', `-I/usr/local/include/db')

This causes the new directory to be appended to the declaration in the previous example:

-I/usr/include -I/usr/ucbinclude -I/usr/local/include/db

Even when you are not sure whether a macro has been given a value by default, you can safely use this APPENDDEF( ) directive because no harm is caused by appending to an empty definition. See also PREPENDDEF( ) in PREPENDDEF( ) on page 102.

Establish files before compiling Build macro

The confBEFORE macro is used to specify the presence of a special header file before compiling. The confBEFORE macro causes an appropriate BEFORE= directive to appear in your Makefile. It is very unlikely that you will ever have to change this from the value that is predefined for you. But if you do, you can do so like this illustration from SunOS 4.0:

define(`confBEFORE', `stdlib.h stddef.h limits.h')
PUSHDIVERT(3)
stddef.h stdlib.h limits.h:
        cp /dev/null $@
POPDIVERT

First, note that the declaration of confBEFORE requires a corresponding section of Makefile code to be inserted between diversions (PUSHDIVERT and POPDIVERT). The first line in this example says that the three files stdlib.h, stddef.h, and limits.h must exist in the obj... directory before sendmail can be compiled. It causes those three header files to be listed with the BEFORE= directive in the resulting Makefile:

BEFORE= stdlib.h stddef.h limits.h
...
sendmail: ${BEFORE} ${OBJS}

The diversion level 3 (in PUSHDIVERT) causes the two lines that follow to be inserted into the Makefile at the appropriate point. The diversion ends with POPDIVERT.

To illustrate further, suppose you want to include your own C-language source and header files with the Build of sendmail. One way to do this might be to add the following lines to your m4 build file:

APPENDDEF(`conf_sendmail_ENVDEF', `-DMYCODE')
APPENDDEF(`confBEFORE', `mycode.h')
APPENDDEF(`confSMOBJADD', `mycode.o')
PUSHDIVERT(3)
mycode.h mycode.c:
       ln -s /usr/local/src/mycode/$@
POPDIVERT

The first line adds -DMYCODE to the ENVDEF= line in Makefile (confENVDEF and conf_prog_ENVDEF on page 75). Here, we presume that C-language hooks have been added to the sendmail source, and that they are enabled/disabled by wrapping them in preprocessor conditionals.^[43] For example:

# ifdef MYCODE
                if (mycode(e->e_eid) < 0)
                       return FALSE;
# endif

The second line in your m4 file appends mycode.h to this confBEFORE macro. The third line causes the OBJADD= directive in Makefile to be given the value mycode.o (confOBJADD on page 93). This automatically adds that object filename to the list of all object files in Makefile:

... util.o version.o ${OBJADD}

Finally, the diversion adds Makefile commands to ensure that the symbolic links to the required C-language source files exist before sendmail is compiled.

Controls variations on objects Build macro

This confBLDVARIANT Build macro is used to convey to the make program a notion of how the compile should run. The possibilities are:

You use the confBLDVARIANT Build macro like this:

define(`confBLDVARIANT', `DEBUG')
define(`confBLDVARIANT', `OPTIMIZED')
define(`confBLDVARIANT', `PURIFY')

The -v command-line switch (-v on page 353) for the Build program uses command-line arguments of debug, optimized, and purify to automatically set this confBLDVARIANT macro.

Note that the arguments used for confBLDVARIANT are all uppercase, whereas those used for -v are all lowercase.

Variants are available only for FreeBSD and Linux as of V8.12.2 sendmail. If you are on another OS, this macro will silently be ignored. If you attempt to use PURIFY, you will see the following Build-time error:

Sorry, the purify build variant has not been plumbed yet. (Bummer.)

Read the RELEASE_NOTES file supplied with the sendmail source to see whether more recent versions support purify and other operating systems.

Location of devtools/bin Build macro

The confBUILDBIN macro is used to define the location of the devtools/bin directory. Normally, this macro will never have to be defined because the default value is correct, but there might be a rare circumstance when you will need to redefine it. If, for example, you need to move the devtools/bin directory to a different path, or rename it, you can do so like this:

define(`confBUILDBIN', `../../OLD_devtools/bin')

Note that the value given to confBUILDBIN must be either an absolute path or a path relative to the obj directory (sendmail is built inside the obj directory).

The confBUILDBIN macro sets the BUILDBIN= line in Makefile. Depending on your operating system, that line might or might not be used. For Solaris 2.5, for example, it is used like this:

INSTALL=${BUILDBIN}/install.sh

One use for confBUILDBIN can occur when you are actively modifying the sendmail code, and it becomes appropriate to maintain the source completely separate from the normal distribution tree.

Compiler used to build sendmail Build macro

The confCC macro is used to specify which C-language compiler to use when building sendmail. The default is probably appropriate for your system, but there might be times when a different compiler is preferred. For example, imagine that you wanted to use Sun’s unbundled compiler instead of gcc(1) under Solaris 2.5:

define(`confCC', `/usr/opt/SUNWspro/bin/cc')

The confCC macro might also be used to compile for testing with purify(1):

define(`confCC', `/usr/local/bin/purify cc')

Or you might need to use a specific version of gcc:

define(`confCC', `gcc -V2.7.2.1')

When compiling under Solaris with Sun’s unbundled compiler, you will need to declare the following two lines:

define(`confCC', `/opt/SUNWspro/bin/cc')
define(`confDEPEND_TYPE', `Solaris')

Here, a confDEPEND_TYPE of Solaris causes a Makefile to be constructed with correct dependencies for Sun’s unbundled compiler (confDEPEND_TYPE on page 73).

The confCC macro provides the value used with the CC= Makefile directive. This value is used to compile .o files from .c files, and to ld(1) the final sendmail executable.

Linker to use when confCC is inappropriate (V8.14 and later) Build macro

Some build systems do not use the compiler to link executables. For such systems, it is now possible to specify a linker to use in place of the compiler:

define(`confCCLINK', `/builds/osx/compat/bin/ld')

Because sendmail’s build is tuned to work best with the compiler, redefining the linker may not be as straightforward as you might expect. Be prepared to experiment with wrapper scripts, for example, to tweak command-line switches to get your linker to work.

Command-line switches to pass to the compiler Build macro

When compiling sendmail or its companion programs, you might need to add special command-line flags to the compiler’s invocation. One example might be the need to add a -nostdinc switch for gcc. The confCCOPTS macro allows you to do this. The following instructs the gcc compiler to allow traditional K&R instructions:

define(`confCCOPTS', `-traditional')

Command-line switches for shared-library objects Build macro

Use of this macro is not supported in the open source version of sendmail.

The copy command to use Build macro

The process of building sendmail includes initializing the contents of some associated files. One example is the statistics file. That file should begin as an empty file. The build process creates it with a command line such as this:

cp /dev/null statistics

For safety’s sake, especially if you changed the name of the statistics file with the confSTFILE macro (confSTFILE and confSTMODE on page 99), you might change the copy command’s invocation to:

define(`confCOPY', `cp -i')

The -i causes cp(1) to prompt for your OK if the target file already exists.

How to build Makefile dependencies Build macro

The confDEPEND_TYPE macro defines the method that should be included in your Makefile for use in creating make(1) dependencies. The methods supported are located in the devtools/M4/depend directory. We show them in Table 2-6.

Note that the correct Solaris method is usually chosen for you in an appropriate devtools/OS file. But in the rare case that the method is wrong or broken, you can use this confDEPEND_TYPE to select another method. For example, consider this broken implementation of an mkdep script:

mkdep -a -f Makefile -I. -DNEWDB *.c
cc: Warning: Option -f passed to ld
cc: Warning: File with unknown suffix (Makefile) passed to ld

In this example, we know we are running X11, and so we chose to replace the defective mkdep with the makedepend(1) program:

define(`confDEPEND_TYPE', `X11')

The new method is specified as the filename (with the .m4 suffix removed) in the devtools/M4/depend directory. Rerunning the Build with -c and this new definition will produce error-free output:

Making dependencies in obj.SunOS.4.1.3.sun4
makedepend -- -I. -I/usr/local/include/db -DNEWDB -DNEWDB -DMATCHGECOS=0 -- *.c
Making in obj.SunOS.4.1.3.sun4

Shared object dependencies Build macro

Ordinarily, sendmail and its companion programs, such as vacation, are linked statically. You might prefer to link some of your programs dynamically so that you can take advantage of shared libraries. Unfortunately, the macros needed to perform such linking are not available for the open source version of sendmail.

No preformatted manuals Build macro

Ordinarily, Build installs the unformatted manual pages in a place such as /usr/share/man/man8, which is in the man* directories. Unless it is told not to, it will also install the formatted pages in a place such as /usr/share/man/cat8, which is in the cat* directories. If your site stores only unformatted pages (perhaps to save disk space), you can prevent the installation of the formatted pages by using an m4 declaration such as this:

define(`confDONT_INSTALL_CATMAN')

Bin directory for mail.local and smrsh Build macro

The confEBINDIR macro tells the Build program where to install the smrsh(1) (Configure to Use smrsh on page 380) and mail.local(1) (FEATURE(local_lmtp) on page 625) programs when they are built. Defining it sets the directory where these programs will be installed, and where sendmail will look when executing them. For example:

define(`confEBINDIR', `/opt/mail/bin')

There is not a single default for this setting. Instead, it is usually predefined in one of the osytpe files (OSTYPE( ) m4 macro on page 590) specific to your operating system (normally /usr/libexec or /usr/sbin).

The smrsh(1) program is located in the smrsh subdirectory of the source distribution. It can be built like this:

% cd smrsh
% ./Build -f ../../builds/oursite.m4

The mail.local program is located in the mail.local subdirectory of the source distribution. It can be built like this:

% cd mail.local
% ./Build -f ../../builds/oursite.m4

Be sure that the setting of confEBINDIR in your m4 build file matches the setting in your configuration m4 file. If you fail to take this precaution, those programs will be installed in a directory different from the one in which sendmail expects to find them.

Pass -D switches during compilation Build macro

The conf_prog_ENVDEF macros are used to assign values to the ENVDEF= Makefile directive in the Makefiles for the various programs in the source tree. The ENVDEF= directive is primarily used to specify code that should be specially included or excluded when compiling. The following example shows support for identd(8) being excluded from the compiled binary of sendmail:^[44]

APPENDDEF(`conf_sendmail_ENVDEF', `-DIDENTPROTO=0')

Note that conf_prog_ENVDEF is often given values in the devtools/OS file for your architecture. To avoid clobbering those values, use APPENDDEF to define conf_prog_ENVDEF.

To use the conf_prog_ENVDEF macro, simply replace the "prog" with the name of any of the programs or library directories in the sendmail source tree. For example, conf_vacation_ENVDEF is used with the vacation program, and conf_mail_local_ENVDEF^[45] is used with the mail.local program.

When a single macro is needed to affect all programs, you can use the confENVDEF macro:

APPENDDEF(`confENVDEF', `-DNISPLUS=1')

Here we enable use of Sun’s NIS+ services (NISPLUS on page 129) for any program that will look up password, group, or similar information.

In Table 3-7 on page 121, the third column indicates whether it is appropriate to redefine a particular macro in your Makefile. Where appropriate, most will be defined with a confENVDEF macro.

Install the rmail program no matter what Build macro

The rmail(8) program is part of the UUCP suite of software. It handles mail that comes in via UUCP, modifies some address information, and hands the result to sendmail.

The rmail program is supplied with the sendmail source distribution because most implementations of that program are deficient in many ways. The source for rmail is from BSD 4.4 Unix and is probably not suitable for other environments. If you actually run UUCP, and if you need a more robust rmail, you are encouraged to port this program to your system.

Because using or installing this version of rmail is not recommended, the default action of Build is to print the following when invoked:

% cd rmail
% ./Build install
NOTE: This version of rmail is not suited for some operating
      systems.  You can force the install using
      'make force-install'.

If you want to change this default action, you can do so by defining this confFORCE_RMAIL macro:

define(`confFORCE_RMAIL', `TRUE')

With this definition in your m4 file, the default action of Build changes to:

% cd rmail
% ./Build install
install -c -o bin -g bin -m 555 rmail /usr/ucb

which does the install. The owner, group, and mode are set with confUBINOWN (confUBINOWN on page 101), confUBINGRP (confUBINGRP on page 101), and confUBINMODE (confUBINMODE on page 101), respectively.

The set-group-id settings Build macro

The non-set-user-id root version of sendmail (Install sendmail on page 60) uses a set-group-id means of identity instead of the normal set-user-id root means. That is, it assumes the group identity specified, no matter who runs it.

Three macros tune the group identity and permission for this non-set-user-id root version. They are:

Where to install the sendmail help file Build macro

The confHFDIR macro defines the location (directory) where the sendmail program’s help file should be installed. The help file contains help for SMTP and -bt rule-testing commands. It is very unlikely that you will ever have to change this from the value that is predefined for you (usually /etc/mail). But if you do, you can do so like this:

define(`confHFDIR', `/admin/mail/etc')

If you redefine this directory, you must also redefine the HELP_FILE configuration macro (HelpFile on page 1035) so that the correct path appears in your sendmail.cf file’s HelpFile option.

The name of the sendmail help file Build macro

Prior to V8.10 sendmail, the name of the SMTP and -bt rule-testing help file was sendmail.hf. Beginning with V8.10 sendmail, the default name is helpfile. To change back to the old name, perhaps for sentimental reasons, you can do the following:

define(`confHFFILE', `sendmail.hf')

If you redefine this name, you must also redefine the HELP_FILE configuration macro (HelpFile on page 1035) so that the correct name appears in your sendmail.cf file’s HelpFile option.

Compiler -I switches Build macro

The confINCDIRS macro defines the directories searched (using the compiler’s -I switch) for #include files. In general, this will be empty unless you are using libraries that are not normally used. For example, you might have installed the db(3) library in /usr/local/lib and its corresponding include files in /usr/local/include/db. In this case, you would define:

APPENDDEF(`confINCDIRS', `-I/usr/local/include/db')
APPENDDEF(`confLIBDIRS', `-L/usr/local/lib')

Here, we use the APPENDDEF directive to prevent (possibly) prior values from being overwritten. The -I will be passed to the C compiler. The -L will be passed to the loader.

Note that the -I must appear as part of the value. If you omit that switch, Build will not correct the mistake and your build of sendmail will fail.

Installed #include file settings Build macro

The libmilter library installs two #include files in /usr/include as a part of its build. Those two files are mfapi.h and mfdef.h. Other programs might also install #include files in future versions.

The location of the #include directory, and the ownership and permission of those #include files, can be changed with the following Build macros:

Program to install programs and files Build macro

The confINSTALL macro defines the program that will be used by make(1) to install sendmail. As distributed, the devtools/OS file for your machine’s architecture predefines this value for you. You should not need to redefine it unless you have customized your system in a way that makes that prior definition inappropriate:

define(`confINSTALL', `${BUILDBIN}/install.sh')

Here, we create a definition that tells make(1) to use devtools/bin/install.sh to install sendmail. The expression ${BUILDBIN} is a Makefile macro that defaults to the devtools/bin directory in the source distribution (see confBUILDBIN, confBUILDBIN on page 72, for a way to override that default).

Note that this macro also defines how manuals will be installed. It does not, however, control whether to install the manual pages (see the confNO_MAN_INSTALL macro, confNO_MAN_INSTALL on page 93). Nor does it define how to install symbolic links (see confLN, confLN on page 83).

Install unformatted manuals Build macro

Ordinarily, the manual pages are formatted when sendmail, or one of the companion programs, is built. These preformatted manuals are the ones installed in the cat manual directories when the program is installed. This confINSTALL_RAWMAN macro causes the unformatted (raw) manual pages to also be installed, but in the man manual directories. For example, with confINSTALL_RAWMAN defined:

% ./Build install
Configuration: pfx=, os=SunOS, rel=4.1.4, rbase=4, rroot=4.1, arch=sun4, sfx=
Making in ../obj.SunOS.4.1.4.sun4/sendmail
...
install -c -o bin -g bin -m 444 sendmail.0 /usr/man/cat8/sendmail.8
install -c -o bin -g bin -m 444 sendmail.8 /usr/man/man8/sendmail.8
... ← etc.

But with the confINSTALL_RAWMAN not defined:

% ./Build install
Configuration: pfx=, os=SunOS, rel=4.1.4, rbase=4, rroot=4.1, arch=sun4, sfx=
Making in ../obj.SunOS.4.1.4.sun4/sendmail
...
install -c -o bin -g bin -m 444 sendmail.0 /usr/man/cat8/sendmail.8
... ← etc.

The linker to use Build macro

Use of this macro is not supported in the open source version of sendmail.

Linker options Build macro

The confLDOPTS macro defines a list of operating-system-specific linker options. Those options are listed with the LDOPTS= directive in Makefile. As distributed, the devtools/OS file, for your machine’s architecture, predefines a list for you. For example, on SunOS machines the following is predefined:

define(`confLDOPTS', `-Bstatic')

This tells the linker to exclude dynamic library support for better security. If you wish to add linker options, use the APPENDDEF( ) directive to add them to the list (because other options probably already exist):

APPENDDEF(`confLDOPTS', `-s')

The linker option -s causes the executable file to be stripped of symbols, thus producing a somewhat smaller on-disk image. The example here shows one way to avoid having to remember to run install-strip with Build each time you install (confSTRIP on page 100).

Linker options for creating a shared library Build macro

Use of this macro is not supported in the open source version of sendmail as of V8.12. There is no guarantee that it will become available in a future release.

Location and modes for installed library files Build macro

Beginning with V8.12, one library, the libmilter library, is now installed centrally for your use in designing you own filter programs. The library file, libmilter.a, is installed by default in the /usr/lib directory. Two corresponding #include files, mfapi.h and mfdef.h, are installed by default in the /usr/include/libmilter directory. No Unix manual pages are installed. Instead, you must read HTML files located under the sendmail source tree, in libmilter/docs, to learn how to use this library.

A number of build-time macros can be used to modify the ownership, location, and modes of the installed library (installation of the #include files is described in confINC... on page 78):

Linker -L switches Build macro

The confLIBDIRS macro defines the directories that are searched for library files (using the linker’s -L switch). The libraries in these directories are searched before the standard system libraries. Consider the desire to have libraries in the path /usr/local/lib used by the linker in preference to those in the standard library path:

APPENDDEF(`confLIBDIRS', `-L/usr/local/lib')

For example, multiple libraries can be searched by listing them in a single definition:

APPENDDEF(`confLIBDIRS', `-L/usr/local/lib -L/usr/tools/lib')

Note that the values defined for this macro must be prefixed by a literal -L. This confLIBDIRS macro is often used in conjunction with the confINCDIRS macro (confINCDIRS on page 78).

Linker -l switches by program Build macro

The confLIBS and conf_prog_LIBS macros define a list of additional libraries to link against by name (using the loader’s -l switch). All devtools/OS files define defaults for this macro, so be sure to APPENDDEF( ) to avoid overwriting your defaults:

APPENDDEF(`confLIBS', `-ldb')
APPENDDEF(`conf_sendmail_LIBS', `-lwrap')

It is unlikely that you will have to add or change libraries in this list. To discover any you might need, run Build to completion and observe which routines the linker reports as missing.

The _prog_ part of the macro name is optional. If present, it should be the name of the specific program for which the build is being run. In the preceding example, -lwrap will be included in only the sendmail program’s build, but not in any other program’s build (as, for example, makemap). By excluding the _prog_ part of the macro name you create a declaration that affects all programs.

Note that for the mail.local program the _prog_ part can be either mail.local or mail_local with no difference in effect.

Automatic library search Build macro

The Build script automatically searches for critical (to sendmail) libraries and, if it finds any, automatically enables specific compile-time options. The list of libraries searched is in the internal confLIBSEARCH macro, which defaults to the following list:

db bind resolv 44bsd

The logic is that if a libdb.a or a libdb.so library is found in any of the directories listed with the confLIBSEARCHPATH macro (confLIBSEARCHPATH on page 83), -DNEWDB is automatically^[46] defined for confENVDEF (confENVDEF and conf_prog_ENVDEF on page 75).

Then the library that is found first (libbind.a, libbind.so, libresolv.a, or libresolv.so) is added to the list of libraries in the confLIBS macro (confLIBS and conf_prog_LIBS on page 82). If lib44bsd is found, and if libresolv was the first found, 44bsd is also added to the confLIBS macro.

In the rare instance that this automatic search misconfigures for your site or particular build, you can carefully^[47] redefine confLIBSEARCH. For example, suppose db has been installed at your site, but it is broken and you don’t have the time to fix it. You might do this:

dnl ********** Note, removed db until we fix it, bob **********
define('confLIBSEARCH', 'bind resolv 44bsd')

Note that you must use the dnl (delete to newline) directive to form a comment in m4(1).

Automatic library search Build macro

The directories searched by the confLIBSEARCH macro (as noted earlier) are defined by this confLIBSEARCHPATH macro. The default list is:

/lib /usr/lib /usr/shlib

It is not uncommon for bind libraries to be installed in nonstandard locations. If such is the case at your site, you can add that nonstandard location to this list with:

APPENDDEF(`confLIBSEARCHPATH', `/usr/local/lib/bind')

If your new location is more important than those in the default list, you can insert that location ahead of the others:

PREPENDDEF(`confLIBSEARCHPATH', `/usr/local/lib/bind')

Achieving the effect you seek can be time-consuming. You will need to rerun Build and observe its output until that effect is displayed.

Program to link files Build macro

As part of installing the sendmail suite of programs, some symbolic links have to be established. The program to create those symbolic links is called ln(1).

If you prefer to use a different program to create symbolic links, you can do so by defining, as shown here, a new program to use:

define(`confLN', `/usr/local/bin/ln')

Before specifying a new program, however, be sure that its command-line arguments (see the next section) are compatible with those used by the default program.

Prior to V8.12.5, this install macro could be used only for libmilter, not for the confLINKS programs (confLINKS on page 84). This has been fixed as of V8.12.6, and this install macro can be used for all the programs.

Switches for the program to link files Build macro

As part of installing the sendmail suite of programs, some symbolic links have to be established. The program to create those symbolic links is usually called ln(1), but it can be renamed with the confLN macro described in the previous section.

The default arguments given to the program are -f -s followed by the name of the file to symbolically link. You can change those arguments by using this confLNOPTS Build macro:

define(`confLNOPTS', `-s')

Here, we removed the -f switch, which forces an unconditional link. Another use for this confLNOPTS Build macro would be to devise arguments for a different or custom linking program (see the previous section).

What to link to sendmail Build macro

A few different names need to be created to make sendmail easier to use. Shown in Table 2-7, they are created by symbolic links to the sendmail binary (except smtpd, which is not automatically linked).

The names and locations of these links are defined with the confLINKS macro. The default values are:

${UBINDIR}/newaliases ${UBINDIR}/mailq ${UBINDIR}/hoststat ${UBINDIR}/purgestat

Here, ${UBINDIR} is separately defined with the confUBINDIR macro (confUBINDIR on page 100). For example, if you wished to put all the links in /usr/local/bin and wanted to add smtpd to the list, you could do this:

define(`confUBINDIR', `/usr/local/bin')
APPENDDEF(`confLINKS', `${UBINDIR}/smptd')

But be forewarned that if you put the links in a new location, you should probably also remove the old links from the former default location. Also note that -E DESTDIR (DESTDIR= on page 349) can be used to relocate all installation directories.

How to install manual pages Build macros

Online manual pages are installed in various ways and in various locations based on the version of Unix involved. For most installations, the defaults defined in your devtools/OS file will be perfect for your site. In the unlikely event that you prefer different settings, a wide range of Build macros is available (see Table 2-8).

${NROFF} ${MANDOC} sendmail.8 > sendmail.${MAN8SRC}

define(`confMAN1SRC', `txt')
define(`confMAN4SRC', `txt')
define(`confMAN5SRC', `txt')
define(`confMAN8SRC', `txt')

${NROFF} ${MANDOC} sendmail.8 > sendmail.txt

${INSTALL} -c -o ${MANOWN} -g ${MANGRP} -m ${MANMODE} sendmail.${MAN8SRC} ${MAN8}/sen
dmail.${MAN8EXT}

define(`confMANROOT', `/usr/local/man/cat')

${INSTALL} -c -o ${MANOWN} -g ${MANGRP} -m ${MANMODE} newaliases.${MAN1SRC} \
        ${MAN1}/newaliases.${MAN1EXT}

define(`confMANROOT', `/usr/local/manuals')
define(`confMAN1', `')
define(`confMAN4', `')
define(`confMAN5', `')
define(`confMAN8', `')

define(`confMANROOT', `')
define(`confMAN1', `/usr/man/users')
define(`confMAN4', `/usr/man/libraries')
define(`confMAN5', `/usr/man/files')
define(`confMAN8', `/usr/man/sysadmin')

define(`confMANROOTMAN', `/usr/local/man/man')

define(`confMAN1EXT', `man')
define(`confMAN5EXT', `man'
define(`confMAN8EXT', `man')

${INSTALL} -c -o ${MANOWN} -g ${MANGRP} -m ${MANMODE} aliases.${MAN5SRC} \
       ${MAN5}/aliases.${MAN5EXT}

define(`confMANMODE', `464')
define(`confMANOWN', `man')
define(`confMANGRP', `man')

groff -Tascii

define(`confNROFF', `nroff')

define(`confMANDOC', `-newman')

Which database libraries to use Build macro

The confMAPDEF macro defines the database library support you want. The currently available choices are listed in Table 2-9. Details are given in the section indicated.

If neither NDBM nor NEWDB is defined, sendmail will read the aliases into its symbol table every time it starts. This will make sendmail crawl every time it starts up and is not recommended.

External databases can be extremely valuable, especially in providing easy solutions for complex problems. Therefore, we recommend that you include a definition for all databases that your system supports, even if you don’t immediately see a need for them.

Here we illustrate the selection of two forms of database:^[49]

APPENDDEF(`confMAPDEF', `-DNEWDB -DNDBM')

When these two forms are selected, old databases are read by using NDBM, but new databases are created by using NEWDB. Read sendmail/README for details about and exceptions to this transition process.

Where and how to install sendmail Build macro

The sendmail binary is intended to run as root only when root runs it. The directory that it is installed in, and the permissions that it has, are defined by four macros:

Program to create installation directories (V8.14 and later) Build macro

By default, if this confMKDIR build macro is undefined, the system’s mkdir(1) program is executed with a -p argument to create installation directories as needed. The -p causes intermediate directories to also be created as needed, and prevents an error if a directory to be created already exists.

Beginning with V8.14, you may use this confMKDIR build macro to replace the default with a program of your own, perhaps a GNU version of mkdir(1):

define(`confMKDIR', `/usr/local/bin/mkdir')

Be aware, however, that installation is usually run by root, so avoid defining a shell script that lives in an unsafe directory.

Owner of the MSP queue Build macro

The non-set-user-id root version of sendmail used for local mail submission employs a queue that is separate from that used by the mail transfer agent (MTA) daemon. This separate queue is owned by smmsp (by default). If you prefer a different owner, you can redefine it with this confMSPQOWN Build macro. It is used like this:

define(`confMSPQOWN', `nullmail')       ← define a username
define(`confMSPQOWN', `67541')          ← define a user by number

If you specify an owner by a positive number that is not too large, it will usually work. If you define a name that is not in the /etc/passwd file (or in a related file such as /etc/master.passwd), the following error will print and the build will fail:

chown: unknown user id: nullmail

See also confMBINOWN in confMBIN... on page 89.

Location of the MSP queue Build macro

The non-set-user-id root version of sendmail used for local mail submission employs a queue that is located separately from that used by the MTA daemon. This separate queue is located by default in /var/spool/clientmqueue. If you prefer a different location or name, you can redefine it with this confMSP_QUEUE_DIR Build macro. Two ways to redefine it might look like this:

define(`confMSP_QUEUE_DIR',`/var/spool/mspqueue')           ← change the name
define(`confMSP_QUEUE_DIR',`/disk1/spool/clientmqueue')     ← change the location

Note that by renaming or relocating the queue directory with this confMSP_QUEUE_DIR Build macro, the MSP_QUEUE_DIR mc macro must also be placed into the submit.mc file and a new submit.cf file thereafter built:

MSP_QUEUE_DIR(`/var/spool/mspqueue')

Define MSP statistics file (V8.12.6 and later) Build macro

Beginning with V8.12.6 sendmail, the confMSP_STFILE Build macro may be used to define a new name under which the statistics file (StatusFile on page 1095) used by the MSP (The submit.cf File on page 66) invocation of sendmail can be installed. It is used like this:

define(`confMSP_STFILE', `mspstats')

Here, a statistics file with the new name mspstats will be installed in the default directory /var/spool/clientmqueue (unless you redefine the default directory using the confMSP_QUEUE_DIR [confMSP_QUEUE_DIR on page 91] Build macro). The default name for this statistics file is sm-client.st.

Note that if you rename this MSP statistics file, you will also have to redefine the StatusFile option (StatusFile on page 1095) in the submit.cf file (The submit.cf File on page 66) to reflect the new name. The proper way to modify that file is to first edit the cf/cf/submit.mc file in the source distribution, and then to regenerate a new submit.cf file, as shown next.

# cd cf/cf
... edit the submit.mc file here
 # make install-submit-cf
... the submit.cf file is re-created and installed here

See also the mailstats program and its -c command-line switch (-c on page 367), which is used to print the contents of this statistics file.

Compiler options for multithreading Build macro

Use of this macro is not supported in the open source version of sendmail.

Linker options for multithreading Build macro

Use of this macro is not supported in the open source version of sendmail.

Prevent installation of the help file Build macro

Ordinarily, sendmail’s help file will be installed automatically. You can see this in part of Build’s output:

install -c -o bin -g bin -m 444 helpfile /etc/mail/helpfile

There are legitimate reasons to suppress the installation of this help file. Consider a site that has added legal disclaimers to that file. Such a site might wish to leave the modified file in place, and prevent it from being overwritten during installation of sendmail. To prevent installation of the help file, you can define this confNO_HELPFILE_INSTALL macro:

define(`confNO_HELPFILE_INSTALL')

With this line in your m4 build file, the preceding install line will be eliminated during installation.

Prevent formatting of manuals Build macro

Ordinarily, when you build sendmail, the unformatted manual pages (those that end in a digit other than zero) are formatted and overwrite the corresponding file that ends in zero. When you run Build it looks like this:

groff -Tascii -man sendmail.8 > sendmail.0 || cp sendmail.0.dist sendmail.0

If you don’t want to format the manual pages (that is, to leave the zero-suffixed files untouched), you can define this confNO_MAN_BUILD macro. Then, when you run Build, the preceding formatting line (or lines) will be missing.

Prevent installation of manuals Build macro

The confNO_MAN_INSTALL macro prevents Build from installing manual pages. In a shared environment, one might not want to install manuals. In that situation, it is preferable to install manuals once, in a central location, rather than installing them for each new machine that is later brought up. For example, the first machine’s m4 build file might contain this:

define(`confMANROOT', `/usr/local/man/cat')

Then, the m4 build files for all future machines might contain this:

define(`confNO_MAN_BUILD')
define(`confNO_MAN_INSTALL')

Here, the first line prevents the formatted manuals from being created. The second line prevents the nonexistent manuals from being installed.

Prevent installation of the statistics file Build macro

The sendmail statistics file is ordinarily installed automatically:

cp /dev/null statistics
install -c -o bin -g bin -m 444 statistics /etc/mail/statistics

There are legitimate reasons to suppress the installation of this statistics file. Consider a site that has written custom software to monitor the sendmail program’s performance. Such a site might wish to eliminate the sendmail statistics file because it is redundant. To prevent installation of the statistics file, you can define this confNO_STATISTICS_INSTALL macro:

define(`confNO_STATISTICS_INSTALL')

With this line in your m4 build file, the earlier install line will be eliminated during installation.

Extra .o files to be linked in all programs Build macro

The confOBJADD macro defines additional object files that need to be included in sendmail and the programs associated with it (such as praliases). It is very unlikely that you will ever have to change the value for it that is predefined in your devtools/OS file. An exception to this might occur if you need to replace a standard C-library function with one that is customized to satisfy some local need. For example, consider a replacement for the syslog(3) routine. First, place a copy of syslog.c in all the source directories. Then, add this line to your site file:

define(`confOBJADD', `syslog.o')

Note that the confOBJADD macro takes the .o form of the object filename, not the source file name.

If you forget to put a copy of the source in one of the directories, you will see this (or a similar) error at build-time:

make: Fatal error: Don't know how to make target `syslog.o'

How to optimize the compile Build macro

The confOPTIMIZE macro sets the command-line switch that will be passed to the C-language compiler to tune its optimization. This macro assigns a value to the O= Makefile directive. Normally, it is correctly set for your site in your devtools/OS file.

One reason to change optimization might be to track down a bug that is causing your installation of sendmail to core-dump. Just add this line to your site file, and re-Build with -c:

define(`confOPTIMIZE', `-g')

The -g switch causes the compiler to produce a binary that can later be debugged with a symbolic debugger.

Most often, sendmail core dumps are caused by improper builds. Always be sure to keep your system and compiler #include files up-to-date and in synchronization with their corresponding libraries.

Note that the confOPTIMIZE macro is not the proper place to set other compile-time macros. Instead use confENVDEF (confENVDEF and conf_prog_ENVDEF on page 75).

The name of the ranlib program for library archive files Build macro

Some flavors of Unix require that the ranlib(1) program be run against a library, before that library can be used. For such systems, this confRANLIB macro is correctly defined for you to be ranlib. For other flavors of Unix, the ranlib(1) program is not necessary. For such systems, this confRANLIB macro is defined to be echo.

In the rare circumstance that the default definition is wrong for your site, you can change it by defining this confRANLIB macro:

define(`confRANLIB', `/afs/support/cc/ranlib')

Arguments to give the ranlib program Build macro

Many versions of the ranlib(1) program run successfully with no argument other than the name of the library file. On some other systems (notably Darwin and Rhapsody), the ranlib(1) program requires a -c argument before the library name. For all the supported architectures in devtools/OS, the presence or absence of other switches is correctly defined for you.

In the rare circumstance that you need to add or change a switch, you can do so with this confRANLIBOPTS macro:

define(`confRANLIBOPTS', `-v')         ← replace the switch
APPENDDEF(`confRANLIBOPTS', `-v')      ← add a switch

Define if libsm is required Build macro

Some of the programs in the source distribution, such as sendmail, require the libsm/libsm.a library. For those programs, this confREQUIRE_LIBSM build-time macro is already correctly defined.

Should you develop a program of your own that needs this library, you can modify its Makefile.m4 file to include it.

root-oriented program directory Build macro

Programs that should be executed only by root are considered "root-oriented.” Among those programs are editmap, makemap, mailstats, and praliases. Such programs are installed in a directory whose name is defined by the confSBINDIR macro. In general, this macro is correctly defined for you in your devtools/OS directory, but if you wish to install one or more of those programs in a different location, you can do so like this:

define(`confSBINDIR', `/opt/mail/sbin')

Here, we have defined the appropriate macros to force installation of the root-oriented programs in the /opt/mail/sbin directory. Naturally, this directory must be properly created ahead of time.

Note that -E DESTDIR (DESTDIR= on page 349) can be used to relocate all installation directories.

Group for set-user-id programs Build macro

The sendmail program often needs to run with appropriate group permissions to be able to determine the load average. On SunOS systems, for example, it needs to run as group kmem. The appropriate group is correctly defined for you in your devtools/OS file, but if you need to change that group, you can do so with this confSBINGRP macro:

define(`confSBINGRP', `mail')

Permissions for set-user-id programs Build macro

For the desired set-user-id behavior to occur, appropriate permissions need to be set during installation. The default permission is 4555. If you wish to change this default, you can do so with the confSBINMODE macro:

define(`confSBINMODE', `2555')          ← not recommended

Be aware that disabling set-user-id like this can cause some actions to fail, such as reading ~/.forward files or writing to the queue.

Owner for set-user-id programs Build macro

Two programs need to be executed as root no matter who runs them. One is sendmail (prior to V8.12), and the other is mail.local. Should one or both of these programs have to run as a user other than root, you can redefine the user with this confSBINOWN macro:

define(`confSBINOWN', `nullmail')

Note that this is just half of the solution. You will also need to tune the appropriate F=S delivery agent flag (see F=S on page 780 for a description of how to do this).

Shared library definitions Build macro

Future versions of sendmail might be able to use shared libraries. When they do, it will be possible to tune their specifications with the build-time macros shown in Table 2-10.

SHELL= for Makefile Build macro

The confSHELL macro is used to assign a value to the SHELL= directive in the created Makefile. That directive determines the shell that will be used to execute each command. The default is /bin/sh for most systems, and /usr/bin/sh for a few. In the extremely rare circumstance that the Bourne shell is not available in this standard location, or if you wish to use a different shell for building sendmail, you can redefine the shell using this confSHELL macro. For example:

define(`confSHELL', `/usr/local/bin/sh')

Note that use of any shell other than the Bourne shell might have unexpected results. Also note that the -E switch to Build cannot be used to pass this value in the environment.

Platform-specific #include file Build macro

The name of the operating-system-specific #include file needed to compile sendmail is normally correctly set for you in your devtools/OS file. You will need to define this for yourself only if you are porting sendmail to an entirely new platform.

Extra .o files to be linked in sendmail Build macro

This macro is deprecated in favor of the conf_prog_OBJADD macro described later.

Source files that correspond to confSMOBJADD Build macro

This macro is deprecated in favor of the conf_prog_SRCADD macro described later.

Shared object ld flag Build macro

This is the command-line switch used with the ld(1) command to create a shared library. Under FreeBSD and Linux it defaults to -soname, and under Solaris it defaults to -h. This Build macro is not currently used by the open source version of sendmail.

Extra .o files to be linked per program Build macro

The conf_prog_OBJADD macro defines additional object files that need to be included in a particular program. Note that it differs from the confOBJADD macro (see confOBJADD on page 93), which adds object files to all programs:

define(`conf_sendmail_OBJADD', `myfilter.o')

Here, we add an object to the object list for the sendmail program only. If this object needs to be generated from a source file, that source file should also be listed with conf_prog_OBJADD, described later.

It is very unlikely that you will ever have to change this value from the one that is predefined for you in your devtools/OS file.

Source that corresponds to conf_prog_OBJADD Build macro

If you ever add .o files to conf_prog_SRCADD (described earlier), and if those .o files need to be generated from .c files, you will need to list those corresponding .c files here:

define(`conf_sendmail_SRCADD', `myfilter.c')

Here, we add a source file to the source file list for the sendmail program only. To add source files to all programs, eliminate the _prog_ and use confSRCADD instead.

It is very unlikely that you will ever have to change this value from the one that is predefined for you in your devtools/OS file.

Location of sendmail source Build macro

All the auxiliary programs that are supplied with sendmail (such as mail.local and praliases) need pieces of source from the sendmail source directory to compile. The location of that directory defaults to ../../sendmail.^[50] Should you need to relocate that source tree (as you might, for example, if you wished to do extensive source modification in a new directory), you can redefine the source location with this confSRCDIR macro:

define(`confSRCDIR', `../../newsendmail')

Note that confSRCDIR gives a value to the SRCDIR= Makefile directive, and that make is run inside an obj... directory, hence the ../../ prefixing newsendmail.

Should you need to relocate the sendmail source to a totally different disk or machine, you must define confSRCDIR as a full pathname:

define(`confSRCDIR', `/usr/local/devel/sendmail/custome1.5/src')

Be careful never to define confSRCDIR under a temporary mount point, such as tmp_mnt, because that mount point might not exist the next time you try to Build. And note that SRCDIR= is always the current directory for sendmail, so nothing special needs to be done to Build if you move the source.

Use torek or portable for buffered file I/O Build macro

This build-time macro is no longer used as of V8.12 sendmail.

Prior to V8.10 sendmail, xf transcript files were always created on disk for each delivery, regardless of whether any information ever ended up in them. In fact, 99% of the time, the xf transcript is created and discarded without ever having been used. Unfortunately, the sendmail queue directory is disk-based, and therefore is limited in the number of I/O operations possible per second. Creating and removing useless files is expensive and has been shown to slow down sendmail.

Beginning with V8.10 sendmail it is possible to create and remove xf transcript files in memory, rather than on disk, and place them on disk only if they become large or need to be archived. This was made possible by the torek I/O library supplied with UCB 4.4 versions of Unix. For such versions, that library is used to create a memory-based file I/O inside sendmail, and thus speed up sendmail.

On the downside, for systems that lack the torek I/O library, this memory-based disk I/O is not available. Such systems are those based on System V or pre-4.4 BSD Unix, or Linux.

For all the flavors of Unix supported in devtools/OS, the selection of the type of I/O is correct. In the rare circumstance that you need to change this setting, you can do so with this confSTDIOTYPE macro:

define(`confSTDIOTYPE', `torek')         ← select torek I/O
define(`confSTDIOTYPE', `portable')      ← select non-torek I/O

If your Unix supports torek I/O, you will benefit in some additional ways. In addition to xf transcript files (The Transcript File: xf on page 401), datafiles (df files) are also buffered (The Data (Message Body) File: df on page 398). In future releases of sendmail, other transient files might also be buffered in memory.

If your Unix lacks torek I/O, you can still minimize the impact of xf files by moving them to a memory-based filesystem, such as tmpfs. This is done with the QUEUE_DIR configuration option’s wildcard extension for multiple queues (see Using qf, df, and xf Subdirectories on page 403).

As of V8.12, in-memory buffering of files is universal and no longer requires this Build macro.

Location of the statistics file Build macros

The confSTDIR macro defines the location (directory) where the sendmail program’s statistics file will be found (see The statistics File on page 365 for a description of this file). The confSTDIR macro assigns its value to the STDIR Makefile directive. It is very unlikely that you will ever have to change this from the value that is predefined for you in your devtools/OS file. But one reason to relocate this file would be the need to locate it on a read/write disk, where /etc/mail is mounted read-only:

define(`confSTDIR', `/var/run/statistics')

Note that if you redefine this directory, you must also redefine the STATUS_FILE configuration macro (The statistics File on page 365) so that the correct path appears in your sendmail.cf file’s StatusFile option.

Also note that -E DESTDIR (DESTDIR= on page 349) can be used to relocate all installation directories.

The name and mode of the statistics file Build macro

The confSTFILE macro defines the name of the sendmail program’s statistics file (see The statistics File on page 365). Normally that name is statistics. It is very unlikely that you will ever have to change this predefined value, but one reason to change the name might be a desire to use a more traditional name:

define(`confSTFILE', `sendmail.st')

Note that, if you redefine this name, you must also redefine the STATUS_FILE configuration macro (The statistics File on page 365) so that the correct name appears in your sendmail.cf file’s StatusFile option.

Beginning with V8.12.4 sendmail, the confSTMODE Build macro has been added to specify the initial permissions for the statistics file. The default permissions are 0600 (read/write only for the owner). These are the recommended permissions, but you might prefer slightly looser permissions if you wish to allow others to read that file with the mailstats program. To change the default, add a line such as the following to your Build m4 file:

define(`confSTMODE', `0640')

It’s OK to allow others to read the file, but it is never OK to allow others to write to that file. Although even looser permissions—say, 0644—might appear desirable, we discourage them because they can allow for a denial-of-service attack on the local machine.

The name of the program to strip the binary Build macro

This is the name of the strip(1) program, which removes symbol-table information from a program and creates a smaller binary. The default is the name strip. To strip a program with Build, install it with install-strip instead of install:

% ./Build install-strip
Configuration: pfx=, os=SunOS, rel=4.1.3, rbase=4, rroot=4.1, arch=sun4, sfx=
Making in ../obj.SunOS.4.1.3.sun4/praliases
install -c -o bin -g bin -m 555 praliases /usr/etc
strip  /usr/etc/praliases                                      ← note

In rare circumstances, you might need to use a different program or a differently located version of strip to perform this function. You change strip with the confSTRIP build macro:

define(`confSTRIP', `/usr/new/44BSD/strip')

If you wish to always strip the binary, you can use the confLDOPTS macro (see confLDOPTS on page 80 for a description of this end-run).

Command-line arguments for the strip program Build macro

Some versions of strip(1) offer options in the form of command-line switches. Solaris 5.5, for example, has a version of strip(1) that supports an -x switch (among others), which causes debugging and line numbers to be stripped, but not the symbol table. If you wished to add this switch to the invocation of strip(1), you could do so like this:

define(`confSTRIPOPTS', `-x')

See your online manual for strip(1) to find switches that might be suitable to your needs.

Location of user executables Build macro

User-executable programs are those that can be run without special permissions. The confUBINDIR macro determines where such programs will be installed. User programs for this macro are newaliases, mailq, hoststat, purgestat, vacation, and rmail. (Note that editmap, mailstats, makemap, and praliases use confSBINDIR, and that smrsh and mail.local use confEBINDIR.) The confUBINDIR macro is usually correctly defined inside your devtools/OS file. To redefine it, simply enter in your m4 build file a line that looks something like this:

define(`confUBINDIR', `/usr/local/bin')

Be forewarned, however, that if you relocate these programs, you might also have to remove earlier installed or vendor-supplied versions to avoid having users running the wrong programs. And note that -E DESTDIR (DESTDIR= on page 349) can be used to relocate all installation directories.

Group for user executables Build macro

The confUBINGRP macro determines the group ownership of user-executable files. This macro assigns its value to the BINGRP= Makefile directive, but only for the following programs: editmap, mailstats, makemap, praliases, rmail, vacation, and smrsh. This macro is usually correctly defined for you in your devtools/OS file. To change the group for these programs, you might do this:

define(`confUBINGRP', `users')

Note that the newaliases, mailq, hoststat, and purgestat programs are really symbolic links, so the concept of group does not apply.

Permissions for user executables Build macro

The confUBINMODE macro determines the permissions for user-executable files. This macro assigns its value to the BINMODE= Makefile directive, but only for the following programs: editmap, mailstats, makemap, praliases, rmail, vacation, and smrsh. This macro is usually correctly defined for you in your devtools/OS file. To change the permissions for these programs, you might do this:

define(`confUBINMODE', `111')

Note that the newaliases, mailq, hoststat, and purgestat programs are really symbolic links, so the concept of permissions does not apply.

Ownership of user executables Build macro

The confUBINOWN macro determines the ownership of user-executable files. This macro assigns its value to the BINOWN= Makefile directive, but only for the following programs: editmap, mailstats, makemap, praliases, rmail, vacation, and smrsh. This macro is usually correctly defined for you in your devtools/OS file. To change the ownership of these programs, you might do this:

define(`confUBINOWN', `sendmail')

Note that the newaliases, mailq, hoststat, and purgestat programs are really symbolic links, so the concept of ownership does not apply.

Prepend to an existing define Build directive

The PREPENDDEF( ) m4 directive allows you to insert new information before that which was previously defined. To illustrate, consider a custom C-language library you want searched first during the loading phase of compiling, where the default list of libraries (for SunOS.5.7) looks like this:

-lsocket -lnsl

If you need to insert another library at the head of this list, without erasing what is already there, you can use this PREPENDDEF( ) directive:

PREPENDDEF(`confLIBS', `-llocal')

This causes the previous declaration to be prefixed with a new (third) library:

-llocal -lsocket -lnsl

Note that you can safely use this PREPENDDEF( ) directive when in doubt as to whether a macro has been given a value by default because no harm can be caused by prepending to an empty definition. (See also APPENDDEF( ) in APPENDDEF( ) on page 69.)