ZMAILER(3zm) ZMAILER(3zm)
NAME
mail_open, mail_priority, mail_abort, mail_close, mail_close_alternate,
mail_alloc, mail_free, mail_host - zmailer message submission interface
SYNOPSIS
#include <stdio.h>
#include <zmailer.h>
FILE *mail_open(char *)
int mail_priority;
int mail_abort(FILE *)
int mail_close(FILE *)
int mail_close_alternate(FILE *mfp, char *where, char *suffix)
char *mail_alloc(unsigned int)
int mail_free(char *)
char *mail_host()
The main program against which this library is liked is expected to
export
char *progname;
variable which carries a copy of argv[0] or something else that pro-
grammer wants to set.
Linkage time: -lzmailer
DESCRIPTION
These routines may be used by any program wishing to submit mail.
mail_open will return a FILE * to a message file that should be written
to by the application. This message file contains three parts: the
message envelope, the message header, and the message body. The exact
format of these components depend on the message protocol, which must
be specified as the parameter to mail_open. The choices are predeter-
mined by the capabilities of the mailer, and are defined in the header
file. The known possibilities are:
MSG_RFC822
this is the only format supported by default by the mailer. The
message headers and body in this format are defined by the DARPA
Request For Comments 822 and 1123. The message envelope syntax
is similar to the message header syntax, but for complete
details refer to the ZMailer documentation.
MSG_FAX
intended for fax transmissions.
MSG_UUCP
intended for old style UUCP format message headers
MSG_X400
intended for X.400(88) messages.
The mail_open() routine will look for FULLNAME and PRETTYLOGIN environ-
ment variables and translate them into message envelope data for use by
the mailer if it generates a sender address header for the message.
Note that the return value from the mail_open() routine corresponds to
the return value of an fopen(3), and similarly the return values from
mail_abort() and mail_close() correspond to the return value of
fclose(3).
The mail_priority variable has default value of 0, and is used on scan-
ning Zmailer configuration variable ROUTERDIRS, which tells alternate
router directories under the POSTOFFICE directory. At value 0, ROUTER-
DIRS variable is not used. At higher values, successive directory from
"ROUTERDIRS" is taken. See below about Z-Environment.
The mail_close_alternate() can be used to send currently open message
file to some alternate destination, and is used at smtpserver(8zm) to
send some quick-action requests directly to the scheduler(8zm).
The mail_alloc() and mail_free() routines are used to provide memory
space for internal data structures. The versions of these routines in
the library simply call malloc(3) and free(3) but an application may
override them if desired.
Similarly the mail_host() routine is intended to return a unique string
for each host, by default the hostname, and this too is intended to be
overridden by an application that may already have this information
available in some form.
ENVELOPE HEADER LINES
The message envelope headers are used to carry meta-information about
the message. The goal is to carry transport-envelope information sepa-
rate from message (RFC-822) headers, and body.
At first the message starts with a set of envelope headers (*-prefix denotes optional):
*external \n
*rcvdfrom %s@%s (%s) \n
*bodytype %s \n
*with %s \n
*identinfo %s \n
Either:
from <%s> \n
Or:
channel error \n
*envid %s \n
*notaryret %s \n
Then for each recipient pairs of:
*todsn [NOTIFY=...] [ORCPT=...] \n
to <%s> \n
Just before the data starts, a magic entry:
env-end \n
Then starts the message RFC-822 headers, and below it, the body
EXAMPLE
... set up signal handlers ...
FILE *mfp = mail_open(MSG_RFC822,0);
if (mfp != NULL) {
... output the mail message to mfp ...
} else
... error handling for not being able to open the file ...
if (some application processing went wrong
|| we took an interrupt)
(void) mail_abort(mfp);
else if (mail_close(mfp) == EOF)
... error handling if something went wrong ...
ENVIRONMENT VARIABLES
FULLNAME
variable defines textual fullname, for example: "Sample User"
PRETTYLOGIN
variable defines user@node format of what user wants to claim as
his/her own address (it must match those of mail router
accepts.)
LOGNAME
USERNAME
USER
Environment variables picked up in sequence in order to find an
idea about user's identity to be stored into a line like:
recvfrom STDIN (username@hostname)
which is purely cosmetic documenting thing.
Z-ENVIRONMENT VARIABLES
POSTOFFICE
defines directory where all POSTOFFICE functions are under.
Example: POSTOFFICE=/var/spool/postoffice
ROUTERDIRS
defines a `:' separated list of alternate router directories.
If these are defined at all, they must exist, if alternate
queueing priority mechanism is desired to be used.
Example: ROUTERDIRS=router1:router2:router3:router4
ROUTERDIRHASH
Value ``1'' at this variable means that all router directories
must have subdirectories with names ``A'' thru ``Z'', alike
ROUTERNOTIFY
defines an AF_UNIX/DGRAM type local notification socket into
which a receiving client may inform the router(8zm) that there
is some new job available.
INPUTDIRS
Presence of this ZENV-variable means that messages will be tried
to be stored into these alternate directories (syntax alike with
ROUTERDIRS !) so that it can be leisurely analyzed (by e.g.
virus scanners) before feeding it onwards to virus scanners.
Presence of this also activates checking of INPUTDIRHASH, and
INPUTNOTIFY.
INPUTDIRHASH=1
This is analogous to ROUTERDIRHASH.
INPUTNOTIFY
This is analogous to ROUTERNOTIFY.
FILES
/var/spool/postoffice/public/
$POSTOFFICE/public/
/var/spool/postoffice/router/
$POSTOFFICE/router/
/var/spool/postoffice/{ROUTERDIRS}/
$POSTOFFICE/{ROUTERDIRS}/
/var/spool/postoffice/.router.notify
$POSTOFFICE/.router.notify
SEE ALSO
sendmail(8zm), zmailer(1zm), zmailer.conf(5zm).
RFC-2822
AUTHOR
This program authored and copyright by:
Rayan Zachariassen <no address>
ROUTERDIRS mechanism is by:
Matti Aarnio <mea@nic.funet.fi>
2003-Aug-28 ZMAILER(3zm)