11.6.7 Customer-supplied Routine Substitutions, $[...]

A substitution of the form $[image,routine,argument] is used to find and call a customer-supplied routine. At run-time on UNIX, the MTA uses dlopen and dlsym to dynamically load and call the specified routine from the shared library image. The routine is then called as a function with the following argument list:

status := routine (argument, arglength, result, reslength)

argument and result are 252 byte long character string buffers. On UNIX, argument and result are passed as a pointer to a character string, (for example, in C, as char*.) arglength and reslength are signed, long integers passed by reference. On input, argument contains the argument string from the rewrite rule template, and arglength the length of that string. On return, the resultant string should be placed in result and its length in reslength. This resultant string will then replace the “$[image,routine,argument]” in the rewrite rule template. The routine should return 0 if the rewrite rule should fail and -1 if the rewrite rule should succeed.

This mechanism allows the rewriting process to be extended in all sorts of complex ways. For example, a call to some type of name service could be performed and the result used to alter the address in some fashion. Directory service lookups for forward pointing addresses (e.g., To: addresses) to the host siroe.com might be performed as follows with the following rewrite rule. The $F, described in 11.6.12 Direction-and-Location-Specific Rewrite Rules ($B, $E, $F, $R) causes this rule to be used only for forward pointing addresses:

siroe.com $F$[LOOKUP_IMAGE,LOOKUP,$U]

A forward pointing address jdoe@siroe.com will, when it matches this rewrite rule, cause LOOKUP_IMAGE (which is a shared library on UNIX) to be loaded into memory, and then cause the routine LOOKUP called with jdoe as the argument parameter. The routine LOOKUP might then return a different address, say, John.Doe%eng.siroe.com in the result parameter and the value -1 to indicate that the rewrite rule succeeded. The percent sign in the result string (see 11.4.2 Repeated Rewrites Template, A%B John.Doe@eng.siroe.com as the address to be rewritten.

On UNIX systems, the site-supplied shared library image should be world readable.