Example - The GNU C Library

Previous: Adding Severity Classes, Up: Formatted Messages

#### 12.22.3 How to use `fmtmsg` and `addseverity`

Here is a simple example program to illustrate the use of the both functions described in this section.

         #include <fmtmsg.h>

         int
         main (void)
         {
           addseverity (5, "NOTE2");
           fmtmsg (MM_PRINT, "only1field", MM_INFO, "text2", "action2", "tag2");
           fmtmsg (MM_PRINT, "UX:cat", 5, "invalid syntax", "refer to manual",
                   "UX:cat:001");
           fmtmsg (MM_PRINT, "label:foo", 6, "text", "action", "tag");
           return 0;
         }

The second call to `fmtmsg` illustrates a use of this function as it usually occurs on System V systems, which heavily use this function. It seems worthwhile to give a short explanation here of how this system works on System V. The value of the label field (`UX:cat`) says that the error occurred in the Unix program `cat`. The explanation of the error follows and the value for the action parameter is `"refer to manual"`. One could be more specific here, if necessary. The tag field contains, as proposed above, the value of the string given for the label parameter, and additionally a unique ID (`001` in this case). For a GNU environment this string could contain a reference to the corresponding node in the Info page for the program.

Running this program without specifying the `MSGVERB` and `SEV_LEVEL` function produces the following output:

         UX:cat: NOTE2: invalid syntax
         TO FIX: refer to manual UX:cat:001

We see the different fields of the message and how the extra glue (the colons and the `TO FIX` string) are printed. But only one of the three calls to `fmtmsg` produced output. The first call does not print anything because the label parameter is not in the correct form. The string must contain two fields, separated by a colon (see Printing Formatted Messages). The third `fmtmsg` call produced no output since the class with the numeric value `6` is not defined. Although a class with numeric value `5` is also not defined by default, the call to `addseverity` introduces it and the second call to `fmtmsg` produces the above output.

When we change the environment of the program to contain `SEV_LEVEL=XXX,6,NOTE` when running it we get a different result:

         UX:cat: NOTE2: invalid syntax
         TO FIX: refer to manual UX:cat:001
         label:foo: NOTE: text
         TO FIX: action tag

Now the third call to `fmtmsg` produced some output and we see how the string `NOTE` from the environment variable appears in the message.

Now we can reduce the output by specifying which fields we are interested in. If we additionally set the environment variable `MSGVERB` to the value `severity:label:action` we get the following output:

         UX:cat: NOTE2
         TO FIX: refer to manual
         label:foo: NOTE
         TO FIX: action

I.e., the output produced by the text and the tag parameters to `fmtmsg` vanished. Please also note that now there is no colon after the `NOTE` and `NOTE2` strings in the output. This is not necessary since there is no more output on this line because the text is missing.