<CHAPTER ID="ZREF-ZMAILER3"><?dbhtml filename="zref-zmailer3.html">
<TITLE>zmailer(3) Reference</TITLE>

<VARIABLELIST>
<VARLISTENTRY><TERM>Usage:</><LISTITEM>
<SYNOPSIS>
#include &lt;stdio.h&gt;
#include &lt;zmailer.h&gt;

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();
</SYNOPSIS>

<PARA>
At linkage time use <USERINPUT>-lzmailer</>.
</PARA>

<PARA>
<FUNCTION>mail_open()</> will return a <FUNCTION>FILE *</> to
a message file that should be written to by the application.
This message file contains three parts:
<ITEMIZEDLIST>
<LISTITEM><PARA>
the message envelope
</PARA></LISTITEM>
<LISTITEM><PARA>
the message header
</PARA></LISTITEM>
<LISTITEM><PARA>
the message body
</PARA></LISTITEM>
</ITEMIZEDLIST>
The exact format of
these components depend on the message protocol,
which must be specified as the parameter to <FUNCTION>mail_open()</>.
The choices are predetermined by the capabilities of the
mailer, and are defined in the header file.
The known possibilities are:

<VARIABLELIST>
<VARLISTENTRY><TERM><LITERAL>MSG_RFC822</></TERM><LISTITEM><PARA>
this is the only format supported by default by the mailer.
The message headers and body in this format are defined by the IETF
Request For Comments 822 and 1123. 
The message envelope syntax is similar to the message header syntax.
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY><TERM><LITERAL>MSG_FAX</></TERM><LISTITEM><PARA>
intended for fax transmissions.
(never used)
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY><TERM><LITERAL>MSG_UUCP</></TERM><LISTITEM><PARA>
intended for old style UUCP format message headers
(never used)
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY><TERM><LITERAL>MSG_X400</></TERM><LISTITEM><PARA>
intended for X.400(88) messages.
</PARA></LISTITEM></VARLISTENTRY>
</VARIABLELIST>
</PARA>

<PARA>
The <FUNCTION>mail_open()</> routine will look for $<VARNAME>FULLNAME</> 
and $<VARNAME>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.
</PARA>

<PARA>
Note that the return value from the <FUNCTION>mail_open()</> routine
corresponds to the return value of an <FUNCTION>fopen(3)</>, and similarly
the return values from <FUNCTION>mail_abort()</> and <FUNCTION>mail_close()</>
correspond to the return value of <FUNCTION>fclose(3)</>.
</PARA>

<PARA>
The <FUNCTION>mail_priority</> variable has a default value of 0, 
and is used on scanning Zmailer configuration variable 
$<VARNAME>ROUTERDIRS</>, which tells alternate router directories
under the <FILENAME CLASS="DIRECTORY">$<VARNAME>POSTOFFICE</>/</>
directory.
At value 0, $<VARNAME>ROUTERDIRS</> variable is not used.
At higher values, successive directory from $<VARNAME>ROUTERDIRS</> is taken. 
See below about Z-Environment.
</PARA>

<PARA>
The <FUNCTION>mail_close_alternate(3)</> can be used to send currently
open message file to some alternate destination, and is used at
<EMPHASIS>smtpserver(8)</> to send some quick-action requests
directly to the <EMPHASIS>scheduler(8)</>.
</PARA>

<PARA>
The <FUNCTION>mail_alloc()</> and <FUNCTION>mail_free()</> routines are
used  to provide memory space for internal data structures.
The versions of these routines in the library simply call
<FUNCTION>malloc(3)</> and <FUNCTION>free(3)</> but an application
may override them if desired.
</PARA>

<PARA>
Similarly the <FUNCTION>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.
</PARA>
</LISTITEM></VARLISTENTRY>

<VARLISTENTRY><TERM>Envelope header lines:</TERM><LISTITEM><PARA>
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.
At first the message starts with a set of envelope headers 
(*-prefix denotes optional):
<SYNOPSIS>
 *external \n
 *rcvdfrom %s@%s (%s) \n
 *bodytype %s \n
 *with %s \n
 *identinfo %s \n

Either:
  from &lt;%s&gt; \n
Or:
  channel error \n

 *envid %s \n
 *notaryret %s \n

Then for each recipient pairs of:

 *todsn [NOTIFY=...] [ORCPT=...] \n
 to &lt;%s&gt; \n

Just before the data starts, a magic entry:

 env-end \n
</SYNOPSIS>
</PARA>

<PARA>
Then starts the message RFC-822 headers, and below it, the body.
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY><TERM>Example:</TERM><LISTITEM><PARA>

<SYNOPSIS>
 ... 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 ...
</SYNOPSIS>

</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY><TERM>Environment variables:</TERM><LISTITEM><PARA>

<VARIABLELIST>
<VARLISTENTRY><TERM><VARNAME>FULLNAME</></><LISTITEM><PARA>
variable defines textual fullname, 
for example: ``Sample User''
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY><TERM><VARNAME>PRETTYLOGIN</></><LISTITEM><PARA>
variable defines 
<EMPHASIS>user@node</> format of what user wants to claim as 
his/her own address (it must match those of mail router accepts.)
</PARA></LISTITEM></VARLISTENTRY>
</VARIABLELIST>


</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY><TERM>Z-environment variables:</TERM><LISTITEM><PARA>

<VARIABLELIST>

<VARLISTENTRY><TERM><VARNAME>POSTOFFICE</></><LISTITEM><PARA>
defines the directory where all
 <FILENAME CLASS=DIRECTORY>$<VARNAME>POSTOFFICE</>/</> functions are. 
Example:
<SYNOPSIS>
  POSTOFFICE=/var/spool/postoffice/
</SYNOPSIS>
</PARA></LISTITEM></VARLISTENTRY>

<VARLISTENTRY><TERM><VARNAME>ROUTERDIRS</></><LISTITEM><PARA>
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:
<SYNOPSIS>
  ROUTERDIRS=router1:router2:router3:router4
</SYNOPSIS>
</PARA></LISTITEM></VARLISTENTRY>
</VARIABLELIST>

</PARA></LISTITEM></VARLISTENTRY>
</VARIABLELIST>

</CHAPTER>
