explain(1)explain(1)NAMEexplain - displays the explanation for an error message
SYNOPSISexplain msgid
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 command 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 one or more digits (for example,
cf90), you must use the form that includes the dash (-).
Recognized Group Codes
The following tables show the products and group codes that have message
and explanation catalogs on IRIX systems. The first column lists the
group code (needed to look up the explanations for messages); the second
column gives the complete name of the software product or products
associated with the group code.
Group Code Software Product
acct Comprehensive System Accounting (CSA)
cf90 f90 version 7.2
dm Data Migration Facility
lib Fortran 90 library version 2.0, and libffio
msgsys explain(1) and caterr(1) utilities
nqs Network Queuing System
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.
The value of the NLSPATH variable depends on the LANG environment
variable or the LC_MESSAGES category. If explain cannot access an
existing explanation catalog, check the value of the NLSPATH environment
variable and either the LANG environment variable or the LC_MESSAGES
category to ensure that the pathname of the catalog is in the message
system search path.
Page 1
explain(1)explain(1)
See environ(5) for a description of the NLSPATH, LANG, and LC_MESSAGES
components.
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
and CMDMSG_FORMAT environment variables. Both variables 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 from programs that use the message formatting function
catmsgfmt(3C). These are most messages in group codes other than msgsys.
The explain and caterr utilities use either CMDMSG_FORMAT or MSG_FORMAT
variables; however, CMDMSG_FORMAT is used before MSG_FORMAT.
Message Format Syntax
Valid fields for MSG_FORMAT and CMDMSG_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 or
CMDMSG_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\n %M\n
For messages issued by the IRIX utilities explain(1) and caterr(1), the
default message format is produced by the following assumed CMDMSG_FORMAT
contents:
%G-%N: %C %M\n
Page 2
explain(1)explain(1)
Messages issued from the cmd group code determine their format according
to the following precedence:
1 Content of CMDMSG_FORMAT variable, if it exists
1 Content of MSG_FORMAT variable, if it exists
1 Default message format for utilities
The format of the time stamp (%T) is equivalent to that produced by the
cftime(3C) function and 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 also can be embedded in the
contents of MSG_FORMAT. The following table lists special characters
that can be embedded.
Description Symbol Sequence
New-line char 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 quot. ' \'
Double quot. " \"
Octal number ooo \ooo
Hex. 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 in this table are passed through
without the backslash, (for example, \q produces q).
SEE ALSOcaterr(1), gencat(1), catgetmsg(3C), catmsgfmt(3C), msg(7D).
Page 3
