'\" t
.\" $Header: /home/mea/src/CVSROOT/zmailer/man/zmailer.3.in,v 1.12 2003/08/28 23:51:29 mea Exp $
.ds ]W ZMailer 2.99
.TH ZMAILER 3zm "2003-Aug-28"
.SH NAME
mail_open, mail_priority, mail_abort, mail_close, mail_close_alternate, mail_alloc, mail_free, mail_host
\- zmailer message submission interface
.SH SYNOPSIS
\fB
.nf
#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()
.fi
\fR
.PP
The main program against which this library is liked is expected to
export
.nf
   char *progname;
.fi
variable which carries a copy of
.I argv[0]
or something else that programmer wants to set.
.PP
Linkage time:
.B -lzmailer
.SH DESCRIPTION
These routines may be used by any program wishing to submit mail.
.I mail_open
will return a \fBFILE *\fR 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
.IR mail_open .
The choices are predetermined by the capabilities of
the mailer, and are defined in the header file.  The known possibilities
are:
.IP 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.
.IP MSG_FAX
intended for fax transmissions.
.IP MSG_UUCP
intended for old style UUCP format message headers
.IP MSG_X400
intended for X.400(88) messages.
.PP
The
.IR mail_open ()
routine will look for
.B FULLNAME
and
.B PRETTYLOGIN
environment variables and translate them into message envelope data
for use by the mailer if it generates a sender address header for the message.
.PP
Note that the return value from the
.IR mail_open ()
routine corresponds to the return value of an
.IR fopen (3),
and similarly the return values from
.IR mail_abort ()
and
.IR mail_close ()
correspond to the return value of
.IR fclose (3).
.PP
The
.I mail_priority
variable has default value of 0, and is used on scanning Zmailer
configuration variable
.BR ROUTERDIRS ,
which tells alternate router directories under the
.B POSTOFFICE
directory.
At value 0,
.B ROUTERDIRS
variable is not used.
At higher values, successive directory from "ROUTERDIRS" is taken.
See below about Z\-Environment.
.PP
The
.IR mail_close_alternate ()
can be used to send currently open message file to some alternate
destination, and is used at
.IR smtpserver (8zm)
to send some quick-action requests directly to the
.IR scheduler (8zm).
.PP
The
.IR mail_alloc ()
and
.IR mail_free ()
routines are used to provide memory space for internal data structures.
The versions of these routines in the library simply call
.IR malloc (3)
and
.IR free (3)
but an application may override them if desired.
.PP
Similarly the
.IR 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.

.SH ENVELOPE HEADER LINES
The message envelope headers are used to carry meta-information about
the message.  The goal is to carry transport-envelope information
separate from message (RFC-822) headers, and body.
.ta 1i 1.5i 2.0i 2.5i
.nf
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
.fi
.SH EXAMPLE
.ta 1i 1.5i 2.0i 2.5i
.nf
	\&\fI... set up signal handlers ...\fR
	\fBFILE\fR *mfp = mail_open(\fBMSG_RFC822\fR,0);
	\fBif\fR (mfp != \fBNULL\fR) {
		\&\fI... output the mail message to mfp ...\fR
	} \fBelse\fR
		\&\fI... error handling for not being able to open the file ...\fR
	\fBif\fR (some application processing went wrong
			\fB||\fR we took an interrupt)
		(\fBvoid\fR) mail_abort(mfp);
	\fBelse if\fR (mail_close(mfp) == \fBEOF\fR)
		\&\fI... error handling if something went wrong ...\fR
.fi
.PP
.SH ENVIRONMENT VARIABLES
.PP
.IP FULLNAME
.RS
variable defines textual fullname, for example: "Sample User"
.RE
.IP PRETTYLOGIN
.RS
variable defines \fBuser@node\fR format of what user wants to claim as his/her
own address (it must match those of mail router accepts.)
.RE
.IP LOGNAME
.IP USERNAME
.IP USER
.RS
Environment variables picked up in sequence in order to find
an idea about user's identity to be stored into a line like:
.PP
.nf
  recvfrom STDIN (username@hostname)
.fi
.PP
which is purely cosmetic documenting thing.
.RE
.PP
.SH Z\-ENVIRONMENT VARIABLES
.PP
.IP POSTOFFICE
.RS
defines directory where all POSTOFFICE functions are under.
.br
Example:
.B POSTOFFICE=/var/spool/postoffice
.RE
.IP ROUTERDIRS
.RS
defines a `:' separated list of alternate router directories.
If these are defined at all, they \fBmust\fR exist, if alternate
queueing priority mechanism is desired to be used.
.br
Example:
.B ROUTERDIRS=router1:router2:router3:router4
.RE
.IP ROUTERDIRHASH
.RS
Value ``1'' at this variable means that all router directories
.B must
have subdirectories with names ``A'' thru ``Z'', alike 
.RE
.IP ROUTERNOTIFY
.RS
defines an \fIAF_UNIX/DGRAM\fR type local notification socket into
which a receiving client \fImay\fR inform the
.IR router (8zm)
that there is some new job available.
.RE
.IP INPUTDIRS
.RS
.I 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.
.PP
Presence of this also activates checking of
.IR INPUTDIRHASH ,
and
.IR INPUTNOTIFY .
.RE
.IP INPUTDIRHASH=1
.RS
This is analogous to
.IR ROUTERDIRHASH .
.RE
.IP INPUTNOTIFY
.RS
This is analogous to
.IR ROUTERNOTIFY .
.RE
.PP
.SH FILES
.IP \fI/var/spool/postoffice/public/\fR
$POSTOFFICE/public/
.IP \fI/var/spool/postoffice/router/\fR
$POSTOFFICE/router/
.IP \fI/var/spool/postoffice/{ROUTERDIRS}/\fR
$POSTOFFICE/{ROUTERDIRS}/
.IP \fI/var/spool/postoffice/.router.notify\fR
$POSTOFFICE/.router.notify
.SH SEE ALSO
.IR sendmail (8zm),
.IR zmailer (1zm),
.IR zmailer.conf (5zm).
.br
RFC-2822
.SH AUTHOR
This program authored and copyright by:
.RS 3em
Rayan Zachariassen <no address>
.RE
.B ROUTERDIRS
mechanism is by:
.RS 3em
Matti Aarnio <mea@nic.funet.fi>
.RE