explain

Date:: 10-20-2011

NAME

explain - Displays the explanation for an error message

SYNOPSIS

explain msgid

IMPLEMENTATION

Cray Linux Environment (CLE)

DESCRIPTION

The explain utility retrieves and outputs a message explanation from an online explanation catalog. If the output device is a terminal, the output of explain is piped through the pager specified in the PAGER variable. If PAGER is not specified, the default pager more -s is used. If the output device is not a terminal, the output of explain is sent to the standard output device (stdout).

The explain utility requires the following argument.

msgid: Specifies the message ID string associated with a message that appears when an error message is output. This string consists of the product group code and the message number. The product group code (group) is a string that identifies the product issuing the message. The message number (msg#) specifies which message within the product you have received. Enter the message ID as an argument to explain in the form groupmsg# or in the form group-msg#. If the group code ends in a digit (for example, ftn), you must use a dash (-).

Location of Explanation Catalogs

To find the explanation for the message, explain searches the path specified in the NLSPATH environment variable for the group.exp file.

Message Format Variables

If msgid does not appear with the error message or if you want to change the format of the messages you receive, you can modify your MSG_FORMAT environment variable. This environment variable can be set to define the fields and the order of the fields to be included in message output.

The MSG_FORMAT variable controls the format in which you receive error messages.

Message Format Syntax

The valid fields for MSG_FORMAT are as follows.

%G: Group code
%N: Message number
%C: Command name
%S: Severity level
%P: Position of the error
%M: Message text
%D: Debugging information
%T: Time stamp

If one of the % fields is not present in the contents of MSG_FORMAT, the corresponding message field is not printed.

The default message format is produced by the following assumed MSG_FORMAT contents.

%G-%N  %C: %S %P\en  %M\en

The format of the time stamp (%T) can be overridden by the CFTIME environment variable. For details about time stamp formats, see the strftime(3c) man page, which documents the cftime function.

The Standard C printf escape sequences can also be embedded in the contents of MSG_FORMAT. This table lists special characters that can be embedded.

-------------------------------------------------------
Description                  Symbol        Sequence
-------------------------------------------------------
New-line character           NL (LF)       \n
Horizontal tab               HT            \t
Vertical tab                 VT            \v
Backspace                    BS            \b
Carriage return              CR            \r
Form feed                    FF            \f
Audible alert                BEL           \a
Backslash                    \             \\
Question mark                ?             \?
Single quotation mark        '             \'
Double quotation mark                      \"
Octal number                 ooo           \ooo
Hexadecimal number           hh            \xhh
-------------------------------------------------------

The escape \ooo consists of the backslash followed by 1, 2, or 3 octal digits, which are taken to specify the value of the desired character. A common example of this construction is \0, which specifies the null character. The escape \xhh consists of the backslash, followed by x, followed by hexadecimal digits, which are taken to specify the value of the desired character. There is no limit on the number of digits, but the behavior is undefined if the resulting character value exceeds that of the largest character.

Any characters other than those listed above are passed through without the backslash. For example, \q produces q.