explain(1) explain(1) NAME explain - displays the explanation for an error message SYNOPSIS explain 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. 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 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 ALSO caterr(1), gencat(1), catgetmsg(3C), catmsgfmt(3C), msg(7D). Page 3