DTMSGLOGMESSAGE(3)

DtMsgLogMessage ✨

okay bestie, this is the library call page for DtMsgLogMessage — yes, the manual-name vibe is literally DtMsgLogMessage(library call), and we are about to make message logging make sense. It logs a message. That's the main-character job. 💅

🌸 NAME 🌸

DtMsgLogMessage — logs a message. Lowkey iconic, highkey useful. ✨

✨ 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, so the application controls it. 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

Heads up: <Msgtype_string> is prefaced with the string *** and one space character. <Msg_type> is replaced with the value of the msg_type argument, placed within parentheses. <Program_name> is replaced with the value of 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. No cap.

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. One call, one vibe. 💅

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 DTUSERSESSION is defined.
• /tmp/<user_name>.errorlog — 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. iykyk.
• 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, status 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. Literally none. That's the whole answer. 💀

🌈 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 Desktop_Tools folder. Very demure, very desktop-tools. 🎀

😭 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 ALSO 👑

DtMsgLogOpenFile(3), DtMsgLogSetHandler(3)

---

xoxo bestie 💖 — that's the DtMsgLogMessage(library call) source/version, and there's no date printed in this copy's footer, so I'm not inventing one 🙈💜