DtMsgLogMessage(library call) DtMsgLogMessage(library call)
NAMEDtMsgLogMessage — logs a message
SYNOPSIS
#include <Dt/MsgLog.h>
void DtMsgLogMessage(
const char* program_name,
DtMsgLogType msg_type,
const char* format,
va_list args);
DESCRIPTION
The DtMsgLogMessage function logs the given arguments in one message.
The format of the message is specified by format and thus is controlled
by the application. The format of each logged entry is:
*** <Msgtype_string>( <Msg_type>): <Program_name>: PID <Proc_id>: <Date>
<The_message>
*** [ <Bytes_output>]
The value of <Msgtype_string> depends on the value of msg_type. Its
value is:
INFORMATION
if msg_type is DtMsgLogInformation
STDERR if msg_type is DtMsgLogStderr
DEBUG if msg_type is DtMsgLogDebug
WARNING if msg_type is DtMsgLogWarning
ERROR if msg_type is DtMsgLogError
UNKNOWN for all other values of msg_type
<Msgtype_string> is prefaced with the string *** and one space charac‐
ter. <Msg_type> is replaced with the value of the msg_type argument
(placed within parentheses). <Program_name> is replaced with the value
of the program_name. <Proc_id> is the application's process id.
<Date> is the date and time the message is logged. <The_message> is
the formatted message including the arguments. <Bytes_output>
(enclosed in brackets) is replaced with the number of bytes output for
the message and header information. (The number of bytes printed for
the line containing <Bytes_output> is not included.). A colon and a
space (respectively) are printed after the closing parenthesis for
<Msg_type>, <Program_name>, and <Proc_id>.
One newline is output after the date and one newline is output after
the message. After the message, a line beginning with the string *** is
output, followed by a space character, a [ character, the number of
bytes printed, a ] character, and,finally, two newlines (one blank line
separates messages).
The message type string and date specification are localized and thus
are retrieved from the current locale's message catalog. It is the
application's responsibility to localize the message to be logged.
An example log entry is:
*** WARNING(3): fontview: PID 12312: Thu Jun 13 16:51:51 1995
The specified font 'fixed' could not be loaded.
*** [109]
To log a multi-line message, use a single call to DtMsgLogMessage.
DtMsgLogMessage attempts to open the following files in the indicated
sequence (by calling the fopen function with the a+ option). It uses
the first file that is successfully opened.
$HOME/.dt/errorlog
This file is used only if the environment variable HOME is
defined.
/var/dt/tmp/$DTUSERSESSION/errorlog
This file is used only if the environment variable DTUSERSES‐
SION is defined.
<filename>/tmp/<user_name>.errorlog</filename>
In this filename, <user_name> is replaced by the user's login
name. The login name is determined by using the environment
variable LOGNAME, if it is defined, or USER, if LOGNAME is
not defined. If neither variable is defined, DtMsgLogMessage
uses the getpwuid function to determine <user_name>.
DtMsgLogMessage calls DtMsgLogOpenFile to determine where to log the
message. If DtMsgLogOpenFile returns NULL, DtMsgLogMessage will output
the message to stderr.
ARGUMENTS
program_name
Specifies a string "tag" to identify the application issuing
the message. This is generally an application's argv[0] so
the message can be traced to an executable program.
msg_type Specifies the DtMsgLogType structure that defines the message
type. See "Structures" in this man page.
format Specifies the sprintf format of the message.
args Specifies the variable number of arguments needed by format.
STRUCTURES
The msg_type argument is specified as a DtMsgLogType enumeration data
type, with the following members:
DtMsgLogInformation
Designates informational messages that do not have to be
brought to the user's immediate attention (for example, sta‐
tus information). It is acceptable to not present messages
of this type to the user.
DtMsgLogDebug
Designates debugging messages written by the application (for
example, via a -debug command line option).
DtMsgLogStderr
Designates messages that an application produces to log the
stderr from a child process.
DtMsgLogWarning
Designates messages for errors that are not severe enough to
cause program termination.
DtMsgLogError
Designates messages for fatal errors that require program
termination.
RETURN VALUE
None.
ENVIRONMENT VARIABLES
The values of the following environment variables determine which file
is opened by DtMsgLogMessage: HOME, LOGNAME, USER, and DTUSERSESSION.
See "Description" in this man page for more information.
Because DtMsgLogMessage calls the catopen function, it is indirectly
influenced by the environment variables that affect catopen, such as
LANG, and NLSPATH. See catopen(3) for more information.
RESOURCES
None.
ACTIONS/MESSAGES
The default mechanism to view the message log is to invoke the Watch
Errors action which is located in the Application Manager's Desk‐
top_Tools folder.
ERRORS/WARNINGS
None.
EXAMPLES
The following code fragment illustrates how to log a localized warning
message:
#include <nl_types.h>
char *s1, *s2; /* temp strings - catgets may return
a pointer to a static buffer */
nl_catd catd = catopen ("app.cat", 0);
s1 = strdup (catgets (catd, 4, 10, "string 1"));
s2 = strdup (catgets (catd, 4, 10, "string 2"));
DtMsgLogMessage (argv[0],
DtMsgLogWarning,
"%s %s",
s1, s2);
FILES
See DtMsgLogOpenFile(3).
SEE ALSODtMsgLogOpenFile(3), DtMsgLogSetHandler(3)
DtMsgLogMessage(library call)