Build: fix parallelism problem. Bug 2566
[exim.git] / src / OS / os.Configuring
CommitLineData
61ec970d
PH
1Configuring Exim for different Operating Systems
2------------------------------------------------
3
4These notes describe the way in which Exim is configured at the C program level
5for different operating systems. The normal configuration options that apply
6independently of the operating system are specified by creating files in the
7Local directory, as described in chapter 4 of the manual.
8
9These notes cover the os.* files in the OS directory, and contain information
10for people who want to port the program to some new OS, or to modify the
11configuration for an existing port. If you are just wanting to compile Exim on
12a system that it already knows about, you do not need to read further unless
13there are problems.
14
15The os.c-<ostype> files
16-----------------------
17
18There may be an os.c-<ostype> file for each operating system, but for many of
19them it is not necessary. No error occurs is there isn't one. There is a
20generic file called os.c which contains code that is common to two or more OS
21for setting a restarting or a non-restarting signal, for computing the load
22average, and for finding all the network interface addresses. A few OS have
23their own individual code for one or more of these. When they do, the code is
24put into an os.c-<ostype> file, which also defines a macro such as
25OS_RESTARTING_SIGNAL (for example) to cut out the common code in the generic
26os.c.
27
28The os.h-<ostype> files
29-----------------------
30
31For each OS that Exim knows about, there is an os.h-<ostype> file, where
32<ostype> is the OS name. The relevant file is included as a C header file for
33all Exim compilation by pointing a symbolic link called os.h at it from the
34build directory. The settings are as follows:
35
36The select() function
37---------------------
38
39There is a difference in the data type for the second argument to the select()
40function in some OS. The macro SELECT_ARG2_TYPE can be used to define the type.
41If it is not defined in os.h, then it is defaulted to fs_set in exim.h.
42
43The dn_expand() function
44------------------------
45
46There is a difference in the data type for the fourth argument to the
47dn_expand() function in some OS. The macro DN_EXPAND_ARG4_TYPE can be used to
48define the type. If it is not defined in os.h, then it is defaulted to char *
49in exim.h.
50
51The h_errno variable
52--------------------
53
54If NEED_H_ERRNO is defined, then a definition of the form
55
56extern int h_errno
57
58is included in the compiled code of Exim.
59
60The strerror() function
61-----------------------
62
63Most systems provide the ANSI standard strerror() function; older systems may
64instead have an errlist[] variable in which to look up error texts. Defining
65STRERROR_FROM_ERRLIST causes Exim to build its own strerror() function that
66mimics the ANSI function by lookup up the error code in errlist.
67
68Truncating files
69----------------
70
71The fcntl() option for truncating the length of a file is called F_FREESP in
72most systems; in some, however, it is called O_TRUNC. Some os.h files define
73F_FREESP to be O_TRUNC for this reason.
74
75Finding local interfaces
76------------------------
77
78The SIOCGIFCONF ioctl for finding local interfaces behaves differently on BSD
79systems. It returns a vector of ifreq blocks containing sockaddr structures
80that can be longer than their sizeof definition, making the returned ifreq
81blocks longer than their sizeof definitions. BSD sockaddrs structures contain
82an sa_len field giving the actual size. To cope with difference, there is a
83macro called HAVE_SA_LEN. If it is defined, code that works on BSD systems is
84used. Otherwise, the objects returned by SIOCGIFCONF are assumed to be of
85length sizeof(struct ifreq).
86
87On some operating systems, the SIOCGIFCONF ioctl returns the IP addresses
88with the list of interfaces, and there is no need to call SIOCGIFADDR for each
89individual address. Mostly, making the second call does no harm, but on Linux
90when there are IP aliases, it causes things to go wrong. This also happens on
6f5a440a 91BSDI and GNU Hurd. Therefore, there is now a macro to cut it out, called
61ec970d
PH
92SIOCGIFCONF_GIVES_ADDR.
93
94Note that, if IPv6 support is configured, Exim cannot find the IPv6 addresses
95on local interfaces by itself. You need to set the local_interfaces option in
96this situation.
97
98Computing load averages
99-----------------------
100
101There are several different ways that load averages are computed. One-off code
102is put in the os.c-<ostype>, but several OS use similar methods, and these
103are coded in the generic os.c, using a number of parameters to make variations
104between OS.
105
106Sometimes the load average is not available to unprivileged callers. If
107LOAD_AVG_NEEDS_ROOT is set, Exim ensures that it is root before trying to
108obtain a load average value.
109
110(1) If HAVE_BSD_GETLOADAVG is defined, Exim uses a simple call to the
111getloadavg() function.
112
113(2) If HAVE_KSTAT is defined, Exim uses the kstat package as found in Solaris 2
114(but nowhere else as yet). It uses some supplementary definitions:
115
116 LOAD_AVG_KSTAT the kstat to use
117 LOAD_AVG_KSTAT_MODULE the module to access
118 LOAD_AVG_KSTAT_SYMBOL the symbol containing the value we want
119 LOAD_AVG_KSTAT_FIELD the field identity
120
121(3) If HAVE_DEV_KMEM is defined, Exim reads load average values from the
122/dev/kmem device. It uses some supplementary definitions:
123
124 LOAD_AVG_TYPE the data type
125 LOAD_AVG_SYMBOL the symbol to look up
126 KERNEL_PATH the name of the kernel
127 FSCALE a scaling factor
128
129Sometimes FSCALE is defined in system headers so need not be defined in the
130os.h-<ostype> file.
131
132Glibc systems and IP options
133----------------------------
134
135The code for inspecting IP options is the same in all OS except for systems
136using glibc (e.g. Linux), which uses a different structure to return data from
137getsockopt(). To handle this, there is a macro called
138
139 GLIBC_IP_OPTIONS
140
141which should be set for Linux (in os.h-Linux) and any other operating system
142that uses glibc.
143
144Options for statvfs()
145---------------------
146
147The following settings apply to the compilation of the Exim monitor as well as
148to the main Exim binary.
149
150#undefine HAVE_STATFS
151
152Exim has options for checking the amount of space in the spool partition
153before accepting a message, and the monitor has the ability to display a
154stripchart of the percentage fullness of a particular disc partition, usually
155/var/spool/mail. The standard way of finding out the data is to call the
156statvfs() function, but some operating systems use statfs() and some may not
157have the ability at all. The Exim code uses STATVFS() for this function and
158this gets defined appropriately. HAVE_STATFS is defined before including the
159os.h file; undefining it suppresses the code for checking a partition in the
160main binary, and for monitoring disc partition in the monitor.
161
162When HAVE_STATFS is defined, the distinction between statvfs() and statfs() is
163made by checking HAVE_SYS_STATVFS_H. If it is defined, then sys/statvfs.h is
164included. Otherwise, STATVFS() is defined as a macro for statfs(), and some
165further includes are done, according to the following definitions:
166
167#define HAVE_SYS_MOUNT_H
168#define HAVE_VFS_H
169
170Each of those definitions causes the inclusion of the corresponding system
171header file in the Exim monitor compilation. For example, the first one causes
172
173#include <sys/mount.h>
174
175to be obeyed. Different systems may require different combinations of these
176headers.
177
178The sys/resource.h header
179-------------------------
180
181One OS does not have the sys/resource.h header. If NO_SYS_RESOURCE_H is defined
182in an os.h-<ostype> file, then the #include for this header is skipped in
183exim.h.
184
929ba01c
PH
185Support for login_cap functions
186-------------------------------
187
188Some of the BSD systems support functions for controlling the resources that
79378e0f
PH
189user processes can use (e.g. login_getpwclass). If HAVE_SETCLASSRESOURCES is
190defined, Exim supports this feature for running pipe deliveries, using the
191setclassresources() function.
929ba01c 192
61ec970d
PH
193The crypt_h header
194------------------
195
196Some OS require crypt.h to be included to get a prototype for the crypt()
197function. This is needed only when compiling with AUTH support. If CRYPT_H is
198defined, then this header is included.
199
200mmap() support
201--------------
202
203The CDB support includes the option of handling file operations by using
204mmap()/munmap(). This gives a reasonable performance increase which will
205probably scale over multiple processes (since the files are mapped read-only
206shared). The vast majority of modern operating systems will support mmap
207(certainly in the simplified way that it is being used here). For example any
208BSD 4.x derived or POSIX compliant system will support it, as will pretty much
209any system using dynamically shared link libraries.
210
211If the OS is believed to support mmap() then the symbol HAVE_MMAP is defined.
212Not all systems that support mmap will have had their config files updated to
213reflect this. Currently Linux, Sun, BSD and SGI/mips systems have been updated.
214
215*** End ***