Re: [bug-mailutils] Library Documentation

[Sergey Poznyakoff]

Hi Andrew,

> To give something back to the community, I've put together some
> documentation for some of the library functions. 
> 
> The URL is:
> 
> http://arbarnes.co.uk/dokuwiki/doku.php

That's *nice* :) Thanks a lot!

One minor point: in dokuwiki/doku.php?id=lists you have:

 struct mu_list_t

But the mu_list_t type is a pointer to structure. So this should be:

 struct _mu_list *mu_list_t

Also, a goot thing to note in dokuwiki/doku.php?id=logging would be this:

The function mu_diag_syslog_printer (as well as its counterpart
mu_diag_stderr_printer) is never used directly. Instead, it is
registered as the output mechanism for MU diagnosticts functions.
For example:

  /* The debug object is used by MU to output diagnostic messages */
  mu_debug_t debug;

  /* Obtain global debug object */ 
  mu_diag_get_debug (&debug);

  /* Register the output function to use with this debug object */ 
  mu_debug_set_print (debug, mu_diag_syslog_printer, NULL);

(For version 2.0.x, it is also a good idea to set:

  mu_debug_default_printer = mu_diag_syslog_printer;

This will ensure that any newly created mu_debug_t objects
will be assigned mu_diag_syslog_printer by default. This hack
be removed in future releases).
  
After this, any diagnostics functions, such as mu_error, mu_diag_printf
or mu_diag_output, will direct their output to syslog. The syslog
facility should be set using openlog(3), as usual. Syslog priority
depends on the particular output function: mu_error uses LOG_ERR,
mu_diag_* family map their first argument (mu_log_level_t) to the
corresponding priority. For example:

  mu_diag_output(MU_DIAG_CRIT, "terminated: %s", reason);

will log its message using LOG_CRIT.

For the list of available values for mu_log_level_t, see
include/mailutils/diag.h
  
Regards,
Sergey