#!/usr/bin/env python # # A GUI configurator for generating fetchmail configuration files. # by Eric S. Raymond, . # Requires Python with Tkinter, and the following OS-dependent services: # posix, posixpath, socket version = "1.43" from Tkinter import * from Dialog import * import sys, time, os, string, socket, getopt, tempfile # # Define the data structures the GUIs will be tossing around # class Configuration: def __init__(self): self.poll_interval = 0 # Normally, run in foreground self.logfile = None # No logfile, initially self.idfile = os.environ["HOME"] + "/.fetchids" # Default idfile, initially self.postmaster = None # No last-resort address, initially self.bouncemail = TRUE # Bounce errors to users self.spambounce = FALSE # Bounce spam errors self.properties = None # No exiguous properties self.invisible = FALSE # Suppress Received line & spoof? self.syslog = FALSE # Use syslogd for logging? self.servers = [] # List of included sites Configuration.typemap = ( ('poll_interval', 'Int'), ('logfile', 'String'), ('idfile', 'String'), ('postmaster', 'String'), ('bouncemail', 'Boolean'), ('spambounce', 'Boolean'), ('properties', 'String'), ('syslog', 'Boolean'), ('invisible', 'Boolean')) def __repr__(self): str = ""; if self.syslog != ConfigurationDefaults.syslog: str = str + ("set syslog\n") elif self.logfile: str = str + ("set logfile \"%s\"\n" % (self.logfile,)); if self.idfile != ConfigurationDefaults.idfile: str = str + ("set idfile \"%s\"\n" % (self.idfile,)); if self.postmaster != ConfigurationDefaults.postmaster: str = str + ("set postmaster \"%s\"\n" % (self.postmaster,)); if self.bouncemail: str = str + ("set bouncemail\n") else: str = str + ("set nobouncemail\n") if self.spambounce: str = str + ("set spambounce\n") else: str = str + ("set no spambounce\n") if self.properties != ConfigurationDefaults.properties: str = str + ("set properties \"%s\"\n" % (self.properties,)); if self.poll_interval > 0: str = str + "set daemon " + `self.poll_interval` + "\n" for site in self.servers: str = str + repr(site) return str def __delitem__(self, name): for si in range(len(self.servers)): if self.servers[si].pollname == name: del self.servers[si] break def __str__(self): return "[Configuration: " + repr(self) + "]" class Server: def __init__(self): self.pollname = None # Poll label self.via = None # True name of host self.active = TRUE # Poll status self.interval = 0 # Skip interval self.protocol = 'auto' # Default to auto protocol self.port = 0 # Port number to use self.uidl = FALSE # Don't use RFC1725 UIDLs by default self.auth = 'any' # Default to password authentication self.timeout = 300 # 5-minute timeout self.envelope = 'Received' # Envelope-address header self.envskip = 0 # Number of envelope headers to skip self.qvirtual = None # Name prefix to strip self.aka = [] # List of DNS aka names self.dns = TRUE # Enable DNS lookup on multidrop self.localdomains = [] # Domains to be considered local self.interface = None # IP address and range self.monitor = None # IP address and range self.plugin = None # Plugin command for going to server self.plugout = None # Plugin command for going to listener self.netsec = None # IPV6 security options self.principal = None # Kerberos principal self.esmtpname = None # ESMTP 2554 name self.esmtppassword = None # ESMTP 2554 password self.tracepolls = FALSE # Add trace-poll info to headers self.users = [] # List of user entries for site Server.typemap = ( ('pollname', 'String'), ('via', 'String'), ('active', 'Boolean'), ('interval', 'Int'), ('protocol', 'String'), ('port', 'Int'), ('uidl', 'Boolean'), ('auth', 'String'), ('timeout', 'Int'), ('envelope', 'String'), ('envskip', 'Int'), ('qvirtual', 'String'), # leave aka out ('dns', 'Boolean'), # leave localdomains out ('interface', 'String'), ('monitor', 'String'), ('plugin', 'String'), ('plugout', 'String'), ('esmtpname', 'String'), ('esmtppassword', 'String'), ('netsec', 'String'), ('principal', 'String'), ('tracepolls','Boolean')) def dump(self, folded): res = "" if self.active: res = res + "poll" else: res = res + "skip" res = res + (" " + self.pollname) if self.via: res = res + (" via " + str(self.via) + "\n"); if self.protocol != ServerDefaults.protocol: res = res + " with proto " + self.protocol if self.port != defaultports[self.protocol] and self.port: res = res + " port " + `self.port` if self.timeout != ServerDefaults.timeout: res = res + " timeout " + `self.timeout` if self.interval != ServerDefaults.interval: res = res + " interval " + `self.interval` if self.envelope != ServerDefaults.envelope or self.envskip != ServerDefaults.envskip: if self.envskip: res = res + " envelope " + `self.envskip` + " " + self.envelope else: res = res + " envelope " + self.envelope if self.qvirtual: res = res + (" qvirtual " + str(self.qvirtual) + "\n"); if self.auth != ServerDefaults.auth: res = res + " auth " + self.auth if self.dns != ServerDefaults.dns or self.uidl != ServerDefaults.uidl: res = res + " and options" if self.dns != ServerDefaults.dns: res = res + flag2str(self.dns, 'dns') if self.uidl != ServerDefaults.uidl: res = res + flag2str(self.uidl, 'uidl') if folded: res = res + "\n " else: res = res + " " if self.aka: res = res + "aka" for x in self.aka: res = res + " " + x if self.aka and self.localdomains: res = res + " " if self.localdomains: res = res + ("localdomains") for x in self.localdomains: res = res + " " + x if (self.aka or self.localdomains): if folded: res = res + "\n " else: res = res + " " if self.tracepolls: res = res + "tracepolls\n" if self.interface: res = res + " interface " + str(self.interface) if self.monitor: res = res + " monitor " + str(self.monitor) if self.plugin: res = res + " plugin " + `self.plugin` if self.plugout: res = res + " plugout " + `self.plugout` if self.netsec: res = res + " netsec " + str(self.netsec) if self.principal: res = res + " principal " + `self.principal` if self.esmtpname: res = res + " esmtpname " + `self.esmtpname` if self.esmtppassword: res = res + " esmtppassword " + `self.esmtppassword` if self.interface or self.monitor or self.netsec or self.principal or self.plugin or self.plugout: if folded: res = res + "\n" if res[-1] == " ": res = res[0:-1] for user in self.users: res = res + repr(user) res = res + "\n" return res; def __delitem__(self, name): for ui in range(len(self.users)): if self.users[ui].remote == name: del self.users[ui] break def __repr__(self): return self.dump(TRUE) def __str__(self): return "[Server: " + self.dump(FALSE) + "]" class User: def __init__(self): if os.environ.has_key("USER"): self.remote = os.environ["USER"] # Remote username elif os.environ.has_key("LOGNAME"): self.remote = os.environ["LOGNAME"] else: print "Can't get your username!" sys.exit(1) self.localnames = [self.remote,]# Local names self.password = None # Password for mail account access self.mailboxes = [] # Remote folders to retrieve from self.smtphunt = [] # Hosts to forward to self.fetchdomains = [] # Domains to fetch from self.smtpaddress = None # Append this to MAIL FROM line self.smtpname = None # Use this for RCPT TO self.preconnect = None # Connection setup self.postconnect = None # Connection wrapup self.mda = None # Mail Delivery Agent self.bsmtp = None # BSMTP output file self.lmtp = FALSE # Use LMTP rather than SMTP? self.antispam = "" # Listener's spam-block code self.keep = FALSE # Keep messages self.flush = FALSE # Flush messages self.fetchall = FALSE # Fetch old messages self.rewrite = TRUE # Rewrite message headers self.forcecr = FALSE # Force LF -> CR/LF self.stripcr = FALSE # Strip CR self.pass8bits = FALSE # Force BODY=7BIT self.mimedecode = FALSE # Undo MIME armoring self.dropstatus = FALSE # Drop incoming Status lines self.dropdelivered = FALSE # Drop incoming Delivered-To lines self.idle = FALSE # IDLE after poll self.limit = 0 # Message size limit self.warnings = 3600 # Size warning interval (see tunable.h) self.fetchlimit = 0 # Max messages fetched per batch self.fetchsizelimit = 100 # Max message sizes fetched per transaction self.fastuidl = 10 # Do fast uidl 9 out of 10 times self.batchlimit = 0 # Max message forwarded per batch self.expunge = 0 # Interval between expunges (IMAP) self.ssl = 0 # Enable Seccure Socket Layer self.sslkey = None # SSL key filename self.sslcert = None # SSL certificate filename self.sslproto = None # Force SSL? self.sslcertck = 0 # Enable strict SSL cert checking self.sslcertpath = None # Path to trusted certificates self.sslfingerprint = None # SSL key fingerprint to check self.properties = None # Extension properties User.typemap = ( ('remote', 'String'), # leave out mailboxes and localnames ('password', 'String'), # Leave out smtphunt, fetchdomains ('smtpaddress', 'String'), ('smtpname', 'String'), ('preconnect', 'String'), ('postconnect', 'String'), ('mda', 'String'), ('bsmtp', 'String'), ('lmtp', 'Boolean'), ('antispam', 'String'), ('keep', 'Boolean'), ('flush', 'Boolean'), ('fetchall', 'Boolean'), ('rewrite', 'Boolean'), ('forcecr', 'Boolean'), ('stripcr', 'Boolean'), ('pass8bits', 'Boolean'), ('mimedecode', 'Boolean'), ('dropstatus', 'Boolean'), ('dropdelivered', 'Boolean'), ('idle', 'Boolean'), ('limit', 'Int'), ('warnings', 'Int'), ('fetchlimit', 'Int'), ('fetchsizelimit', 'Int'), ('fastuidl', 'Int'), ('batchlimit', 'Int'), ('expunge', 'Int'), ('ssl', 'Boolean'), ('sslkey', 'String'), ('sslcert', 'String'), ('sslcertck', 'Boolean'), ('sslcertpath', 'String'), ('sslfingerprint', 'String'), ('properties', 'String')) def __repr__(self): res = " " res = res + "user " + `self.remote` + " there "; if self.password: res = res + "with password " + `self.password` + " " if self.localnames: res = res + "is" for x in self.localnames: res = res + " " + `x` res = res + " here" if (self.keep != UserDefaults.keep or self.flush != UserDefaults.flush or self.fetchall != UserDefaults.fetchall or self.rewrite != UserDefaults.rewrite or self.forcecr != UserDefaults.forcecr or self.stripcr != UserDefaults.stripcr or self.pass8bits != UserDefaults.pass8bits or self.mimedecode != UserDefaults.mimedecode or self.dropstatus != UserDefaults.dropstatus or self.dropdelivered != UserDefaults.dropdelivered or self.idle != UserDefaults.idle): res = res + " options" if self.keep != UserDefaults.keep: res = res + flag2str(self.keep, 'keep') if self.flush != UserDefaults.flush: res = res + flag2str(self.flush, 'flush') if self.fetchall != UserDefaults.fetchall: res = res + flag2str(self.fetchall, 'fetchall') if self.rewrite != UserDefaults.rewrite: res = res + flag2str(self.rewrite, 'rewrite') if self.forcecr != UserDefaults.forcecr: res = res + flag2str(self.forcecr, 'forcecr') if self.stripcr != UserDefaults.stripcr: res = res + flag2str(self.stripcr, 'stripcr') if self.pass8bits != UserDefaults.pass8bits: res = res + flag2str(self.pass8bits, 'pass8bits') if self.mimedecode != UserDefaults.mimedecode: res = res + flag2str(self.mimedecode, 'mimedecode') if self.dropstatus != UserDefaults.dropstatus: res = res + flag2str(self.dropstatus, 'dropstatus') if self.dropdelivered != UserDefaults.dropdelivered: res = res + flag2str(self.dropdelivered, 'dropdelivered') if self.idle != UserDefaults.idle: res = res + flag2str(self.idle, 'idle') if self.limit != UserDefaults.limit: res = res + " limit " + `self.limit` if self.warnings != UserDefaults.warnings: res = res + " warnings " + `self.warnings` if self.fetchlimit != UserDefaults.fetchlimit: res = res + " fetchlimit " + `self.fetchlimit` if self.fetchsizelimit != UserDefaults.fetchsizelimit: res = res + " fetchsizelimit " + `self.fetchsizelimit` if self.fastuidl != UserDefaults.fastuidl: res = res + " fastuidl " + `self.fastuidl` if self.batchlimit != UserDefaults.batchlimit: res = res + " batchlimit " + `self.batchlimit` if self.ssl and self.ssl != UserDefaults.ssl: res = res + flag2str(self.ssl, 'ssl') if self.sslkey and self.sslkey != UserDefaults.sslkey: res = res + " sslkey " + `self.sslkey` if self.sslcert and self.sslcert != UserDefaults.sslcert: res = res + " sslcert " + `self.sslcert` if self.sslproto and self.sslproto != UserDefaults.sslproto: res = res + " sslproto " + `self.sslproto` if self.sslcertck and self.sslcertck != UserDefaults.sslcertck: res = res + flag2str(self.sslcertck, 'sslcertck') if self.sslcertpath and self.sslcertpath != UserDefaults.sslcertpath: res = res + " sslcertpath " + `self.sslcertpath` if self.sslfingerprint and self.sslfingerprint != UserDefaults.sslfingerprint: res = res + " sslfingerprint " + `self.sslfingerprint` if self.expunge != UserDefaults.expunge: res = res + " expunge " + `self.expunge` res = res + "\n" trimmed = self.smtphunt; if trimmed != [] and trimmed[len(trimmed) - 1] == "localhost": trimmed = trimmed[0:len(trimmed) - 1] if trimmed != [] and trimmed[len(trimmed) - 1] == hostname: trimmed = trimmed[0:len(trimmed) - 1] if trimmed != []: res = res + " smtphost " for x in trimmed: res = res + " " + x res = res + "\n" trimmed = self.fetchdomains if trimmed != [] and trimmed[len(trimmed) - 1] == hostname: trimmed = trimmed[0:len(trimmed) - 1] if trimmed != []: res = res + " fetchdomains " for x in trimmed: res = res + " " + x res = res + "\n" if self.mailboxes: res = res + " folder" for x in self.mailboxes: res = res + " " + x res = res + "\n" for fld in ('smtpaddress', 'preconnect', 'postconnect', 'mda', 'bsmtp', 'properties'): if getattr(self, fld): res = res + " %s %s\n" % (fld, `getattr(self, fld)`) if self.lmtp != UserDefaults.lmtp: res = res + flag2str(self.lmtp, 'lmtp') if self.antispam != UserDefaults.antispam: res = res + " antispam " + self.antispam + "\n" return res; def __str__(self): return "[User: " + repr(self) + "]" # # Helper code # defaultports = {"auto":0, "POP2":109, "POP3":110, "APOP":110, "KPOP":1109, "IMAP":143, "ETRN":25, "ODMR":366} authlist = ("any", "password", "gssapi", "kerberos", "ssh", "otp") listboxhelp = { 'title' : 'List Selection Help', 'banner': 'List Selection', 'text' : """ You must select an item in the list box (by clicking on it). """} def flag2str(value, string): # make a string representation of a .fetchmailrc flag or negated flag str = "" if value != None: str = str + (" ") if value == FALSE: str = str + ("no ") str = str + string; return str class LabeledEntry(Frame): # widget consisting of entry field with caption to left def bind(self, key, action): self.E.bind(key, action) def focus_set(self): self.E.focus_set() def __init__(self, Master, text, textvar, lwidth, ewi
<!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