#!/usr/bin/perl -w
#
# Make a fetchmail release.
# Dumps a release notice and diffs as a MIME multipart message 
# in RELEASE_NOTES
#

my $project = "fetchmail";
my $website = "http://sourceforge.net/projects/$project";
my $mailfrom =pre { line-height: 125%; }
td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }
span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }
td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
.highlight .hll { background-color: #ffffcc }
.highlight .c { color: #888888 } /* Comment */
.highlight .err { color: #a61717; background-color: #e3d2d2 } /* Error */
.highlight .k { color: #008800; font-weight: bold } /* Keyword */
.highlight .ch { color: #888888 } /* Comment.Hashbang */
.highlight .cm { color: #888888 } /* Comment.Multiline */
.highlight .cp { color: #cc0000; font-weight: bold } /* Comment.Preproc */
.highlight .cpf { color: #888888 } /* Comment.PreprocFile */
.highlight .c1 { color: #888888 } /* Comment.Single */
.highlight .cs { color: #cc0000; font-weight: bold; background-color: #fff0f0 } /* Comment.Special */
.highlight .gd { color: #000000; background-color: #ffdddd } /* Generic.Deleted */
.highlight .ge { font-style: italic } /* Generic.Emph */
.highlight .gr { color: #aa0000 } /* Generic.Error */
.highlight .gh { color: #333333 } /* Generic.Heading */
.highlight .gi { color: #000000; background-color: #ddffdd } /* Generic.Inserted */
.highlight .go { color: #888888 } /* Generic.Output */
.highlight .gp { color: #555555 } /* Generic.Prompt */
.highlight .gs { font-weight: bold } /* Generic.Strong */
.highlight .gu { color: #666666 } /* Generic.Subheading */
.highlight .gt { color: #aa0000 } /* Generic.Traceback */
.highlight .kc { color: #008800; font-weight: bold } /* Keyword.Constant */
.highlight .kd { color: #008800; font-weight: bold } /* Keyword.Declaration */
.highlight .kn { color: #008800; font-weight: bold } /* Keyword.Namespace */
.highlight .kp { color: #008800 } /* Keyword.Pseudo */
.highlight .kr { color: #008800; font-weight: bold } /* Keyword.Reserved */
.highlight .kt { color: #888888; font-weight: bold } /* Keyword.Type */
.highlight .m { color: #0000DD; font-weight: bold } /* Literal.Number */
.highlight .s { color: #dd2200; background-color: #fff0f0 } /* Literal.String */
.highlight .na { color: #336699 } /* Name.Attribute */
.highlight .nb { color: #003388 } /* Name.Builtin */
.highlight .nc { color: #bb0066; font-weight: bold } /* Name.Class */
.highlight .no { color: #003366; font-weight: bold } /* Name.Constant */
.highlight .nd { color: #555555 } /* Name.Decorator */
.highlight .ne { color: #bb0066; font-weight: bold } /* Name.Exception */
.highlight .nf { color: #0066bb; font-weight: bold } /* Name.Function */
.highlight .nl { color: #336699; font-style: italic } /* Name.Label */
.highlight .nn { color: #bb0066; font-weight: bold } /* Name.Namespace */
.highlight .py { color: #336699; font-weight: bold } /* Name.Property */
.highlight .nt { color: #bb0066; font-weight: bold } /* Name.Tag */
.highlight .nv { color: #336699 } /* Name.Variable */
.highlight .ow { color: #008800 } /* Operator.Word */
.highlight .w { color: #bbbbbb } /* Text.Whitespace */
.highlight .mb { color: #0000DD; font-weight: bold } /* Literal.Number.Bin */
.highlight .mf { color: #0000DD; font-weight: bold } /* Literal.Number.Float */
.highlight .mh { color: #0000DD; font-weight: bold } /* Literal.Number.Hex */
.highlight .mi { color: #0000DD; font-weight: bold } /* Literal.Number.Integer */
.highlight .mo { color: #0000DD; font-weight: bold } /* Literal.Number.Oct */
.highlight .sa { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Affix */
.highlight .sb { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Backtick */
.highlight .sc { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Char */
.highlight .dl { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Delimiter */
.highlight .sd { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Doc */
.highlight .s2 { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Double */
.highlight .se { color: #0044dd; background-color: #fff0f0 } /* Literal.String.Escape */
.highlight .sh { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Heredoc */
.highlight .si { color: #3333bb; background-color: #fff0f0 } /* Literal.String.Interpol */
.highlight .sx { color: #22bb22; background-color: #f0fff0 } /* Literal.String.Other */
.highlight .sr { color: #008800; background-color: #fff0ff } /* Literal.String.Regex */
.highlight .s1 { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Single */
.highlight .ss { color: #aa6600; background-color: #fff0f0 } /* Literal.String.Symbol */
.highlight .bp { color: #003388 } /* Name.Builtin.Pseudo */
.highlight .fm { color: #0066bb; font-weight: bold } /* Name.Function.Magic */
.highlight .vc { color: #336699 } /* Name.Variable.Class */
.highlight .vg { color: #dd7700 } /* Name.Variable.Global */
.highlight .vi { color: #3333bb } /* Name.Variable.Instance */
.highlight .vm { color: #336699 } /* Name.Variable.Magic */
.highlight .il { color: #0000DD; font-weight: bold } /* Literal.Number.Integer.Long */
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
 <meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
 <title>TRIO</title>
 <link href="trio.css" rel="stylesheet" type="text/css">
</head>
<body>
<!-- Generated by Doxygen 1.2.12 -->
<center>
<a class="qindex" href="index.html">Main Page</a> &nbsp; <a class="qindex" href="modules.html">Modules</a> &nbsp; </center>
<hr><h1>User-defined Formatted Printing Functions.</h1>Functions for using customized formatting specifiers. 
<a href="#_details">More...</a><table border=0 cellpadding=0 cellspacing=0>
<tr><td colspan=2><br><h2>Functions</h2></td></tr>
<tr><td nowrap align=right valign=top>trio_pointer_t&nbsp;</td><td valign=bottom><a class="el" href="group___user_defined.html#a0">trio_register</a> (trio_callback_t callback, const char *name)</td></tr>
<tr><td>&nbsp;</td><td><font size=-1><em>Register new user-defined specifier.</em> <a href="#a0">More...</a><em></em></font><br><br></td></tr>
<tr><td nowrap align=right valign=top>void&nbsp;</td><td valign=bottom><a class="el" href="group___user_defined.html#a1">trio_unregister</a> (trio_pointer_t handle)</td></tr>
<tr><td>&nbsp;</td><td><font size=-1><em>Unregister an existing user-defined specifier.</em> <a href="#a1">More...</a><em></em></font><br><br></td></tr>
</table>
<hr><a name="_details"></a><h2>Detailed Description</h2>
Functions for using customized formatting specifiers.
<p>
<b>SYNOPSIS</b>
<p>
<div class="fragment"><pre>
cc ... -ltrio -lm

#include &lt;trio.h&gt;
#include &lt;triop.h&gt;
</pre></div>
<p>
<b>DESCRIPTION</b>
<p>
This documentation is incomplete.
<p>
<b>User-defined</b> <b>Specifier</b>
<p>
The user-defined specifier consists of a start character (\074 = '&lt;'), an optional namespace string followed by a namespace separator (\072 = ':'), a format string, and an end character (\076 = '&gt;').
<p>
The namespace string can consist of alphanumeric characters, and is used to define a named reference (see below). The namespace is case-sensitive. If no namespace is specified, then we use an unnamed reference (see below).
<p>
The format can consist of any character except the end character ('&gt;'), the namespace separator (':'), and the nil character (\000).
<p>
Any modifier can be used together with the user-defined specifier.
<p>
<b>Registering</b>
<p>
A user-defined specifier must be registered before it can be used. Unregistered user-defined specifiers are ignored. The <a class="el" href="group___user_defined.html#a0">trio_register</a> function is used to register a user-defined specifier. It takes two argument, a callback function and a namespace, and it returns a handle. The handle must be used to unregister the specifier later.
<p>
The following example registers a user-define specifier with the "my_namespace" namespace:
<p>
<div class="fragment"><pre>
  my_handle = trio_register(my_callback, "my_namespace");
</pre></div>
<p>
There can only be one user-defined specifier with a given namespace. There can be an unlimited number (subject to maximum length of the namespace) of different user-defined specifiers.
<p>
Passing NULL as the namespace argument results in an anonymous reference. There can be an unlimited number of anonymous references.
<p>
<b>REFERENCES</b>
<p>
There are two ways that a registered callback can be called. Either the user-defined specifier must contain the registered namespace in the format string, or the handle is passed as an argument to the formatted printing function.
<p>
If the namespace is used, then a user-defined pointer must be passed as an argument:
<p>
<div class="fragment"><pre>
  trio_printf("&lt;my_namespace:format&gt;\n", my_data);
</pre></div>
<p>
If the handle is used, then the user-defined specifier must not contain a namespace. Instead the handle must be passed as an argument, followed by a user-defined pointer:
<p>
<div class="fragment"><pre>
  trio_printf("&lt;format&gt;\n", my_handle, my_data);
</pre></div>
<p>
The two examples above are equivalent.
<p>
There must be exactly one user-defined pointer per user-defined specifier. This pointer can be used within the callback function with the trio_get_argument getter function (see below).
<p>
The format string is optional. It can be used within the callback function with the trio_get_format getter function.
<p>
<b>Anonymous</b> <b>References</b> Anonymous references are specified by passing NULL as the namespace.
<p>
The handle must be passed as an argument followed by a user-defined pointer. No namespace can be specified.
<p>
<div class="fragment"><pre>
  anon_handle = trio_register(callback, NULL);
  trio_printf("&lt;format&gt;\n", anon_handle, my_data);
</pre></div>
<p>
<b>Restrictions</b>
<p>
<ul>
<li> The length of the namespace string cannot exceed 63 characters. <li> The length of the user-defined format string cannot exceed 255 characters. <li> User-defined formatting cannot re-define existing specifiers. This restriction was imposed because the existing formatting specifiers have a well-defined behaviour, and any re-definition would apply globally to an application (imagine a third-party library changing the behaviour of a specifier that is crusial to your application).</ul>
<b>CALLBACK</b> <b>FUNCTION</b>
<p>
The callback function will be called if a matching user-defined specifier is found within the formatting string. The callback function takes one input parameter, an opaque reference which is needed by the private functions. It returns an <code>int</code>, which is currently ignored. The prototype is
<p>
<div class="fragment"><pre>
  int (*trio_callback_t)(void *ref);
</pre></div>
<p>
See the Example section for full examples.
<p>
<b>PRINTING</b> <b>FUNCTIONS</b>
<p>
The following printing functions must only be used inside a callback function. These functions will print to the same output medium as the printf function which invoked the callback function. For example, if the user-defined specifier is used in an sprintf function, then these print functions will output their result to the same string.
<p>
<b>Elementary</b> <b>Printing</b>
<p>
There are a number of function to print elementary data types.
<p>
<ul>
<li> trio_print_int Print a signed integer. For example: <div class="fragment"><pre>
  trio_print_int(42);
</pre></div> <li> trio_print_uint Print an unsigned integer. <li> trio_print_double Print a floating-point number. <li> trio_print_string Print a string. For example: <div class="fragment"><pre>
  trio_print_string("Hello World");
  trio_print_string(trio_get_format());
</pre></div> <li> trio_print_pointer Print a pointer.</ul>
<b>Formatted</b> <b>Printing</b>
<p>
The functions trio_print_ref, trio_vprint_ref, and trio_printv_ref outputs a formatted string just like its printf equivalents.
<p>
<div class="fragment"><pre>
  trio_print_ref(ref, "There are %d towels\n", 42);
  trio_print_ref(ref, "%&lt;recursive&gt;\n", recursive_writer, trio_get_argument());
</pre></div>
<p>
<b>GETTER</b> <b>AND</b> <b>SETTER</b> <b>FUNCTIONS</b>
<p>
The following getter and setter functions must only be used inside a callback function. They can either operate on the modifiers or on special data.
<p>
<b>Modifiers</b>
<p>
The value of a modifier, or a boolean indication of its presence or absence, can be found or set with the getter and setter functions. The generic prototypes of the these getter and setter functions are
<p>
<div class="fragment"><pre>
  int  trio_get_???(void *ref);
  void trio_set_???(void *ref, int);
</pre></div>
<p>
where ??? <code>refers</code> to a modifier. For example, to get the width of the user-defined specifier use
<p>
<div class="fragment"><pre>
  int width = trio_get_width(ref);
</pre></div>
<p>
<b>Special</b> <b>Data</b>
<p>
Consider the following user-defined specifier, in its two possible referencing presentations.
<p>
<div class="fragment"><pre>
  trio_printf("%&lt;format&gt;\n", namespace_writer, argument);
  trio_printf("%&lt;namespace:format&gt;\n", argument);
</pre></div>
<p>
trio_get_format will get the <code>format</code> string, and trio_get_argument} will get the <code>argument</code> parameter. There are no associated setter functions.
<p>
<b>EXAMPLES</b>
<p>
The following examples show various types of user-defined specifiers. Although each specifier is demonstrated in isolation, they can all co-exist within the same application.
<p>
<b>Time</b> <b>Example</b>
<p>
Print the time in the format "HOUR:MINUTE:SECOND" if "time" is specified inside the user-defined specifier.
<p>
<div class="fragment"><pre>
  static int time_writer(void *ref)
  {
    const char *format;
    time_t *data;
    char buffer[256];

    format = trio_get_format(ref);
    if ((format) &amp;&amp; (strcmp(format, "time") == 0)) {
      data = trio_get_argument(ref);
      if (data == NULL)
        return -1;
      strftime(buffer, sizeof(buffer), "%H:%M:%S", localtime(data));
      trio_print_string(ref, buffer);
    }
    return 0;
  }
</pre></div>
<p>
<div class="fragment"><pre>
  int main(void)
  {
    void *handle;
    time_t now = time(NULL);

    handle = trio_register(time_print, "my_time");

    trio_printf("%&lt;time&gt;\n", handle, &amp;now);
    trio_printf("%&lt;my_time:time&gt;\n", &amp;now);

    trio_unregister(handle);
    return 0;
  }
</pre></div>
<p>
<b>Complex</b> <b>Numbers</b> <b>Example</b>
<p>
Consider a complex number consisting of a real part, re, and an imaginary part, im.
<p>
<div class="fragment"><pre>
  struct Complex {
    double re;
    double im;
  };
</pre></div>
<p>
This example can print such a complex number in one of two formats. The default format is "re + i im". If the alternative modifier is used, then the format is "r exp(i theta)", where r is the length of the complex vector (re, im) and theta is its angle.
<p>
<div class="fragment"><pre>
  static int complex_print(void *ref)
  {
    struct Complex *data;
    const char *format;

    data = (struct Complex *)trio_get_argument(ref);
    if (data) {
      format = trio_get_format(ref);

      if (trio_get_alternative(ref)) {
        double r, theta;

        r = sqrt(pow(data-&gt;re, 2) + pow(data-&gt;im, 2));
        theta = acos(data-&gt;re / r);
        trio_print_ref(ref, "%#f exp(i %#f)", r, theta);

      } else {
        trio_print_ref(ref, "%#f + i %#f", data-&gt;re, data-&gt;im);
      }
    }
    return 0;
  }
</pre></div>
<p>
<div class="fragment"><pre>
  int main(void)
  {
    void *handle;

    handle = trio_register(complex_print, "complex");

    /* Normal format. With handle and the with namespace */
    trio_printf("%&lt;&gt;\n", handle, &amp;complex);
    trio_printf("%&lt;complex:&gt;\n", &amp;complex);
    /* In exponential notation */
    trio_printf("%#&lt;&gt;\n", handle, &amp;complex);
    trio_printf("%#&lt;complex:unused data&gt;\n", &amp;complex);

    trio_unregister(handle);
    return 0;
  }
</pre></div>
<p>
<b>RETURN</b> <b>VALUES</b>
<p>
<a class="el" href="group___user_defined.html#a0">trio_register</a> returns a handle, or NULL if an error occured.
<p>
<b>SEE</b> <b>ALSO</b>
<p>
<a class="el" href="group___printf.html#a0">trio_printf</a>
<p>
<b>NOTES</b>
<p>
User-defined specifiers, <a class="el" href="group___user_defined.html#a0">trio_register</a>, and <a class="el" href="group___user_defined.html#a1">trio_unregister</a> are not thread-safe. In multi-threaded applications they must be guarded by mutexes. Trio provides two special callback functions, called ":enter" and ":leave", which are invoked every time a thread-unsafe operation is attempted. As the thread model is determined by the application, these callback functions must be implemented by the application.
<p>
The following callback functions are for demonstration-purposes only. Replace their bodies with locking and unlocking of a mutex to achieve thread-safety. <div class="fragment"><pre>
  static int enter_region(void *ref)
  {
    fprintf(stderr, "Enter Region\n");
    return 1;
  }

  static int leave_region(void *ref)
  {
    fprintf(stderr, "Leave Region\n");
    return 1;
  }
</pre></div> These two callbacks must be registered before other callbacks are registered. <div class="fragment"><pre>
  trio_register(enter_region, ":enter");
  trio_register(leave_region, ":leave");

  another_handle = trio_register(another_callback, NULL);
</pre></div> <hr><h2>Function Documentation</h2>
<a name="a0" doxytag="trio.c::trio_register"></a><p>
<table width="100%" cellpadding="2" cellspacing="0" border="0">
  <tr>
    <td class="md">
      <table cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td class="md" nowrap valign="top"> trio_pointer_t trio_register </td>
          <td class="md" valign="top">(&nbsp;</td>
          <td class="md" nowrap valign="top">trio_callback_t&nbsp;</td>
          <td class="mdname" nowrap>&nbsp; <em>callback</em>, </td>
        </tr>
        <tr>
          <td></td>
          <td></td>
          <td class="md" nowrap>const char *&nbsp;</td>
          <td class="mdname" nowrap>&nbsp; <em>name</em></td>
        </tr>
        <tr>
          <td></td>
          <td class="md">)&nbsp;</td>
          <td class="md" colspan="2"></td>
        </tr>

      </table>
    </td>
  </tr>
</table>
<table cellspacing=5 cellpadding=0 border=0>
  <tr>
    <td>
      &nbsp;
    </td>
    <td>

<p>
Register new user-defined specifier.
<p>
<dl compact><dt><b>
Parameters: </b><dd>
<table border=0 cellspacing=2 cellpadding=0>
<tr><td valign=top><em>callback</em>&nbsp;</td><td>
</td></tr>
<tr><td valign=top><em>name</em>&nbsp;</td><td>
</td></tr>
</table>
</dl><dl compact><dt><b>
Returns: </b><dd>
Handle. </dl>    </td>
  </tr>
</table>
<a name="a1" doxytag="trio.c::trio_unregister"></a><p>
<table width="100%" cellpadding="2" cellspacing="0" border="0">
  <tr>
    <td class="md">
      <table cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td class="md" nowrap valign="top"> void trio_unregister </td>
          <td class="md" valign="top">(&nbsp;</td>
          <td class="md" nowrap valign="top">trio_pointer_t&nbsp;</td>
          <td class="mdname1" valign="top" nowrap>&nbsp; <em>handle</em>          </td>
          <td class="md" valign="top">)&nbsp;</td>
          <td class="md" nowrap></td>
        </tr>

      </table>
    </td>
  </tr>
</table>
<table cellspacing=5 cellpadding=0 border=0>
  <tr>
    <td>
      &nbsp;
    </td>
    <td>

<p>
Unregister an existing user-defined specifier.
<p>
<dl compact><dt><b>
Parameters: </b><dd>
<table border=0 cellspacing=2 cellpadding=0>
<tr><td valign=top><em>handle</em>&nbsp;</td><td>
</td></tr>
</table>
</dl>    </td>
  </tr>
</table>
<HR>
<center class="copyright">Copyright (C) 2001 Bj&oslash;rn Reese and Daniel Stenberg.</center>
</body>
</html>