EXPLAIN(1) Last changed: 7-21-97
NAME
explain - Displays the explanation for an error message
SYNOPSIS
explain msgid
IMPLEMENTATION
UNICOS systems
IRIX systems
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 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 UNICOS systems and 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;
the third column lists the publication number in which explanations
for messages in that group code can be found.
UNICOS group codes
---------------------------------------------------------------
Group Code Software Product Publication
---------------------------------------------------------------
apprentice MPP Apprentice tool Online only
as CAL assembler SR-3108
asm Cray Assembler for MPP (CAM) Online only
atchop atchop(1) performance tool Online only
atexpert atexpert(1) performance tool Online only
builddefs builddefs(1) command of the UNICOS Online only
glossary
cc Cray Standard C compiler Online only
cf90 CF90 Fortran language Online only
cld Loader for CRAY T3E systems Online only
cmd UNICOS utilities that are compliant Online only
with XPG4
dbg cdbx(1), debug(1), symdebug(3F), and Online only
symdump(3F) debugging commands
define define(1) command of the UNICOS Online only
glossary
deplib deplib(1) command Online only
df df(1) utility Online only
dm Data Migration Facility SG-2135
du du(1) utility Online only
ex ex(1) and vi(1) utilities Online only
flowv flowview(1) performance tool Online only
fmp fmp(1) Fortran vectorization SR-3771
translator
fpp fpp(1) Fortran vectorization analyzer SR-3771
fsquota File system quota feature Online only
hpm hpm(1) performance tool Online only
hpmall hpmall(8) performance tool Online only
hpmflop hpmflop(8) performance tool Online only
jt jt(1) performance tool Online only
jumpv jumpview(1) performance tool Online only
ldr segldr(1) and ld(1) loader commands SR-0066
lib Fortran and I/O libraries Online only
libm Mathematical libraries SG-2138
libp Pascal library Online only
lprof libprof library Online only
ltrace Jumptrace library Online only
mppldr Loader for CRAY T3D systems Online only
mtdump mtdump(1) performance tool Online only
nqs Network Queuing System Online only
perf libperf library Online only
perfdmp perfdmp(1) performance tool Online only
perfv perfview(1) performance tool Online only
proc procstat(1) performance tool Online only
procv procview(1) performance tool Online only
prof prof(1) performance tool Online only
profv profview(1) performance tool Online only
ps ps(1) utility Online only
sh Standard shell Online only
sys UNICOS system error list SR-2012
(syserrlist[])
syslog System message logger (newsys(8) and Online only
syslogd(8))
talk talk(1B) utility Online only
urm Unified Resource Manager Online only
usm UNICOS Source Manager (USM) SG-2097
---------------------------------------------------------------
IRIX group codes
---------------------------------------------------------------
Group Code Software Product Publication
---------------------------------------------------------------
cf90 f90 version 7.2 Online only
lib Fortran 90 library version 2.0, and Online only
libffio
msgsys explain(1) and caterr(1) utilities Online only
---------------------------------------------------------------
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 LCMESSAGES 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
LCMESSAGES category to ensure that the path name of the catalog is in
the message system search path.
On UNICOS systems, you can use the whichcat(1) utility to determine
which catalog is being accessed by explain. For more information, see
whichcat(1).
On UNICOS systems, see the catopen(3C) man page for a description of
the NLSPATH, LANG, and LCMESSAGES components.
On IRIX systems, see environ(5) for a description of the NLSPATH,
LANG, and LLCMESSAGES 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
MSGFORMAT and CMDMSGFORMAT environment variables. Both variables
can be set to define the fields and the order of the fields to be
included in message output.
The MSGFORMAT variable controls the format in which you receive error
messages from programs that use the message formatting function
catmsgfmt(3C). On UNICOS systems, these are most messages in group
codes other than cmd. On IRIX systems, these are most messages in
group codes other than msgsys.
On UNICOS systems, the CMDMSGFORMAT variable controls the format in
which you receive error messages issued by system utilities that are
included in the XPG4 standard. These are messages in the cmd group
code. A separate environment variable is provided to control message
output from these utilities, because it is often desirable to capture
and process this output through a script or program; limiting the
output to one line makes this easier. The default format (shown
below) for non-utility messages outputs at least two lines. The
CMDMSGFORMAT variable exists to provide a one-line default format for
utility messages.
On IRIX systems, the explain and caterr utilities use either
CMDMSGFORMAT or MSGFORMAT variables; however, CMDMSGFORMAT is used
before MSGFORMAT.
Message Format Syntax
Valid fields for MSGFORMAT and CMDMSGFORMAT 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 MSGFORMAT or
CMDMSGFORMAT, the corresponding message field is not printed.
The default message format is produced by the following assumed
MSGFORMAT contents:
%G-%N %C: %S %P\n %M\n
For messages issued by UNICOS utilities, and by the IRIX utilities
explain(1) and caterr(1), the default message format is produced by
the following assumed CMDMSGFORMAT contents:
%G-%N: %C %M\n
Messages issued from the cmd group code determine their format
according to the following precedence:
1. Content of CMDMSGFORMAT variable, if it exists
2. Content of MSGFORMAT variable, if it exists
3. 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 MSGFORMAT. The following table lists special characters
that can be embedded.
--------------------------------
Description Symbol Sequence
--------------------------------
New-line NL \n
character (LF)
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 hh \xhh
number
--------------------------------
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).
NOTES
On UNICOS systems, if this utility is installed with a privilege
assignment list (PAL), a user with one of the following active
categories is allowed to perform the actions shown:
Active Category Action
system, secadm In a privileged administrator shell environment,
allowed to write shell-redirected output to any
file.
sysadm Shell-redirected output is subject to security
label restrictions.
If the PRIVSU configuration option is enabled, the super user can
write shell-redirected output to any file.
SEE ALSO
UNICOS systems
caterr(1), catxt(1), gencat(1), whichcat(1)
catgetmsg(3C), catgets(3C), catmsgfmt(3C), catopen(3C), strftime(3C)
in the UNICOS System Libraries Reference Manual, publication SR-2080
nltypes(5), msg(7D) in the UNICOS File Formats and Special Files
Reference Manual, publication SR-2014
IRIX systems
caterr(1), gencat(1)
catgetmsg(3C), catmsgfmt(3C)
msg(7D)
Cray Research publications
UNICOS Message System Programmer's Guide, publication SG-2121
Segment Loader (SEGLDR) and ld Reference Manual, publication SR-0066
UNICOS System Calls Reference Manual, publication SR-2012
UNICOS Source Manager (USM) User's Guide, publication SG-2097
Cray Data Migration Facility (DMF) Administrator's Guide, publication
SG-2135
Intrinsic Procedures Reference Manual, publication SR-2138
Cray Assembly Language (CAL) for Cray PVP Systems Reference Manual,
publication SR-3108
UNICOS User Commands Reference Manual, publication SR-2011, for the
printed version of this man page.