152 lines
5.2 KiB
Plaintext
152 lines
5.2 KiB
Plaintext
<!-- $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 <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>
|