CDE/cde/doc/C/guides/man/m3_Dt/MsgLogS.sgm

<!-- $XConsortium: MsgLogS.sgm /main/9 1996/11/12 11:26:42 cdedoc $ -->
<!-- (c) Copyright 1996 Digital Equipment Corporation. -->
<!-- (c) Copyright 1996 Hewlett-Packard Company. -->
<!-- (c) Copyright 1996 International Business Machines Corp. -->
<!-- (c) Copyright 1996 Sun Microsystems, Inc. -->
<!-- (c) Copyright 1996 Novell, Inc. -->
<!-- (c) Copyright 1996 FUJITSU LIMITED. -->
<!-- (c) Copyright 1996 Hitachi. -->
<![ %CDE.C.CDE; [<refentry id="CDE.MSG.DtMsgLogSetHandler">]]>
<![ %CDE.C.XO; [<refentry id="XCSA.MSG.DtMsgLogSetHandler">]]>
<refmeta><refentrytitle>
DtMsgLogSetHandler
</refentrytitle><manvolnum>library call</manvolnum></refmeta><refnamediv>
<refname><function>DtMsgLogSetHandler</function></refname><refpurpose>
installs an alternate message logging handler
</refpurpose></refnamediv><refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;Dt/MsgLog.h></funcsynopsisinfo>
<funcdef>DtMsgLogHandler <function>DtMsgLogSetHandler</function></funcdef>
<paramdef>DtMsgLogHandler <parameter>handler</parameter></paramdef>
</funcsynopsis>
</refsynopsisdiv><refsect1>
<title>DESCRIPTION</title>
<para>The <function>DtMsgLogSetHandler</function> function
installs an alternate message logging handler that will be
invoked when <function>DtMsgLogMessage</function> is called.
If <symbol role="Variable">handler</symbol> is <symbol role="define">NULL</symbol>,
the default handler is installed.
</para>
<para><function>DtMsgLogSetHandler</function> is optional and should
be used only to override the default message logging handler.
If the handler function wants to log a message, it must use the
format and file specified in &cdeman.DtMsgLogMessage;
so applications can reliably parse the log file. (If the handler
wants to log a message, it can obtain the byte count to output
by using the return value from a call to
<function>vfprint</function>.)
</para>
<para>The <function>DtMsgLogHandler</function> handler function has
the following arguments:
</para>
<variablelist>
<varlistentry><term><symbol role="Variable">program_name</symbol></term>
<listitem>
<para>A string "tag" to identify the application
issuing the message. This is generally an application's
<literal>argv[0]</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry><term><symbol role="Variable">msg_type</symbol></term>
<listitem>
<para>The message type.
</para>
</listitem>
</varlistentry>
<varlistentry><term><symbol role="Variable">format</symbol></term>
<listitem>
<para>Specifies the <function>sprintf</function> format of the message.
</para>
</listitem>
</varlistentry>
<varlistentry><term><symbol role="Variable">args</symbol></term>
<listitem>
<para>Specifies the variable number of arguments needed by
<symbol role="Variable">format</symbol>.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>The handler function should not call <function>DtMsgLogMessage</function>.
</para>
<para>A sample use of the <function>DtMsgLogSetHandler</function> function
is in an application that prints the
CDE data types and actions databases. If an error occurs when the
databases are loaded, the error messages are logged and the application
is not able to get the messages. However, if the application installs
a message logging handler, when the database loading code encounters
an error, the application's installed handler will be invoked to give
the application access to the database loading error messages.
</para>
</refsect1><refsect1>
<title>ARGUMENTS</title>
<variablelist>
<varlistentry><term><symbol role="Variable">handler</symbol></term>
<listitem>
<para>Specifies a message handler function.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1><refsect1>
<title>ENVIRONMENT VARIABLES</title>
<para>None.
</para>
</refsect1><refsect1>
<title>RESOURCES</title>
<para>None.</para>
</refsect1><refsect1>
<title>ACTIONS/MESSAGES</title>
<para>None.
</para>
</refsect1><refsect1>
<title>ERRORS/WARNINGS</title>
<para>None.</para>
</refsect1><refsect1>
<title>EXAMPLES</title>
<para>The following code installs a
<function>DtMsgLogHandler</function> handler
and then calls <function>DtDbLoad</function> to load the CDE
data typing and action databases. If an error occurs when the
databases are loaded, the handler function will be invoked.
The handler writes the message to an alternate file. After the databases are
loaded, the default handler is restored.
</para>
<programlisting>
(void) DtMsgLogSetHandler (msglog_handler);
DtDbLoad ();
(void) DtMsgLogSetHandler (NULL);

void my_handler (
    const char    * prog_name,
    DtMsgLogType    msg_type,
    const char    * format,
    va_list         args)
{
   FILE	     *fp;

   fp = fopen ("/tmp/foo", "a+");

   (void) fprintf (fp, "progname = %s\n\tformat = %s\n\tmsg_type = %d\n",
		prog_name, format, msg_type);
   (void) vfprintf (fp, format, args);
   (void) fprintf (fp, "\n");
}
</programlisting>
</refsect1><refsect1>
<title>RETURN VALUE</title>
<para>If <function>DtMsgLogMessage</function> completes
successfully, it returns the previously installed handler.
If it fails, it returns <symbol role="define">NULL</symbol>.
</para>
</refsect1><refsect1>
<title>FILES</title>
<para>None.
</para>
</refsect1><refsect1>
<title>SEE ALSO</title>
<para>&cdeman.DtMsgLogMessage;,
&cdeman.DtMsgLogOpenFile;</para>
</refsect1></refentry>