92-10-06 print_sys_log, psl Syntax: psl LOG_SELECTOR {-control_args} Function: prints selected portions of system logs, including the syserr log, Answering Service, admin commands, and Data Management logs. Various control arguments are used to determine which portions of the log are printed, and the format of the output. Arguments: LOG_SELECTOR is either the pathname of a named log or log family to be monitored, or one of the "log selection" control arguments listed below. Control arguments (log selection): -pathname LOG_PATH, -pn LOG_PATH specifies that the named log or log family is to be examined. -admin specifies that the admin commands log is to be examined. The admin commands log family is called "admin_log", and is located in the >sc1>as_logs directory. This argument is incompatible with any of the other log selection control arguments, or an explicit log pathname. -answering_service, -as specifies that the Answering Service log is to be examined. The Answering Service log family is called "log", and is located in the >sc1>as_logs directory. This argument is incompatible with any of the other log selection control arguments, or an explicit log pathname. -dm_system, -dms specifies that the Data Management system log for the process's current AIM authorization is to be examined. The Data Management log family is called "dm_system_log", and its location depends on the AIM access class of the log. This argument is incompatible with any of the other log selection control arguments, or an explicit log pathname. Reading the log requires access to the dm_admin_ gate. -mc_log LOG_NAME, -mcl LOG_NAME specifies that the message coordinator (daemon) log named LOG_NAME is to be examined. All message coordinator logs are located in the >sc1>as_logs directory; their names depend on the daemon to which they belong. This argument is incompatible with any of the other log selection control arguments, or an explicit log pathname. -syserr specifies that the syserr log is to be examined. The syserr log family is named "syserr_log". The first segment in the family is >sl1>syserr_log; there may be a history segment in >sl1, and older history segments are in the directory >sc1>syserr_log. This argument is incompatible with any of the other log selection control arguments, or an explicit log pathname. Control arguments (limit selection): -from TIME, -fm TIME, -from NUMBER, -fm NUMBER specifies that the first message examined is the first message at or after the specified time or sequence number; if -reverse is specified, the first message is the one at or before the specified value. If no -from value is specified, the default is the first message in the log, or the last if -reverse is specified. This is incompatible with -last. -to TIME, -to NUMBER specifies the last message to be examined, either by message time or sequence number. If not specified, the default is all the remaining messages in the log. This is incompatible with -for. -last NUMBER, -lt NUMBER, -last TIME, -lt TIME specifies that only the last NUMBER messages, or the messages since TIME, are to be printed. If a NUMBER is specified, it specifies the actual number of messages to be printed, not the number of messages examined in the log. This is incompatible with -from and -for. -for TIME, -for NUMBER specifies a number of messages to print, or a time interval relative to the starting time (specified by -from) in which the messages must be contained. The number of messages is the actual number of messages printed, not the number of messages examined in the log. This is incompatible with -to and -last. -forward, -fwd specifies that the log is to be examined starting with the oldest message selected by other control arguments, and proceed forwards. (Default) -reverse, -rv specifies that the log is to be examined, starting with the most recent message selected by other control arguments and proceeding backwards. Control arguments (message selection): -exclude STR-1 ... STR-n, -ex STR-1 ... STR-n no message whose text contains one of the specified strings (STR-1 to STR-n) is processed. A string is interpreted either as a text string, which must be an exact substring of the message text, or, if surrounded by slashes, as a regular to match against the message text. See the "Notes on String Matching" section below for details. -match STR-1 ... STR-n, -mh STR-1 ... STR-n only messages whose text contains one of the specified strings (STR-1 to STR-n) are processed. The strings are processed as for -exclude. -all_text, -atxt specifies that all log messages are to be processed, regardless of text contents, cancelling the effect of any preceding -match or -exclude. (Default) -severity SEV-1 ... SEV-n, -sv SEV-1 ... SEV-n only messages of the specified severity (severities) are processed. The severity values (SEV-1 to SEV-n) may either be decimal integers, or ranges consisting a pair of decimal integers separated by a colon ("20:29"). If multiple severities are specified, or the -severity control argument is specified more than once, all messages with any of those severities are printed. A severity value must be between -100 and 100. See the "Notes (severity values)" below for details. -all_severities, -asv messages of all severities are printed. This cancels the effect of any previous -severity control arguments. (Default) Control arguments (message expansion): -expand {CLASS-1 ... CLASS-n}, -exp {CLASS-1 ... CLASS-n} specifies that binary data is to be expanded and displayed along with the message text, for the selected messages. If a data class value (CLASS-1 to CLASS-n) is specified, only binary data of the specified classes will be expanded; otherwise, all selected messages with binary data will be expanded. The type of expansion depends on whether the -octal or -interpret control arguments are also specified. See the "List of data classes" section below for details. By default, no messages are expanded. -no_expand, -nexp specifies that no messages are to be displayed with binary data expanded. This cancels the effect of any previous -expand control arguments. By default, no messages are expanded. -octal, -oc specifies that the binary data in expanded messages is to be displayed in octal, rather than, or in addition to, the interpreted representation. If both octal and interpreted representations are desired, both the -octal and -interpret control arguments must be supplied. -interpret, -int specifies that the binary data in expanded messages is to be displayed as interpreted text, by calling the appropriate expand_XXX_msg_ program for the data class of the message. If the -octal control argument is also specified, the binary data is displayed both in interpreted form and as octal data. (Default) -match_data STR-1 ... STR-n, -md STR-1 ... STR-n only messages whose interpreted expanded data contains one of the specified strings (STR-1 to STR-n) are processed. The strings are processed as for -exclude. Note: This control argument merely matches against the textual interpretation of the expanded data; if this interpretation is to be displayed as well, the -interpret control argument must also be specified. -exclude_data STR-1 ... STR-n, -exd STR-1 ... STR-n no message whose interpreted expanded data contains one of the specified strings (STR-1 to STR-n) is processed. The strings are processed as for -exclude. Note: This control argument merely matches against the textual interpretation of the expanded data; if this interpretation is to be displayed as well, the -interpret control argument must also be specified. -all_data, -ad specifies that all log messages are to be processed, regardless of interpreted expanded data contents, cancelling the effect of any preceeding -match_data or -exclude_data. (Default) -match_data_class CLASS-1 ... CLASS-n, -mdc CLASS-1 ... CLASS-n only messages whose binary data class is one of the specified strings (CLASS-1 to CLASS-n) are processed. Note: This control argument merely matches against the data class; if the binary data is to be displayed as well, the -octal or -interpret control argument must also be specified. -exclude_data_class CLASS-1 ... CLASS-n, -exdc CLASS-1 ... CLASS-n no message whose binary data class is one of the specified strings (CLASS-1 to CLASS-n) is processed. Note: This control argument merely matches against the data class; if the binary data is to be displayed as well, the -octal or -interpret control argument must also be specified. -all_data_classes, -adc specifies that all log messages are to be processed, regardless of binary data class, cancelling the effect of any preceeding -match_data or -exclude_data. (Default) Control arguments (message format): -line_length N, -ll N specifies the line length used when formatting message text and data for printing. The value (N) must be between 25 and 500. By default, it is the line length associated with the user_output I/O switch, or, if none (as for an absentee), it is 132 (for line printer output). -indent N, -ind N specifies that all messages are to be formatted for printing prefixed with N spaces. The value of N must be between 0 and 50. The indentation is printed before any data associated with the message, including the message prefix. By default, there is no indentation. -continuation_indent N, -ci N specifies that all messages are to be formatted for printing with continuation lines prefixed by N spaces, or, if the keyword "standard" or "std" is used in place of a number, with the continuation lines indented sufficiently to line up under the first character of the text of the message. The value of N must be between 0 and 50. By default, continuation lines are indented to the "standard" indentation. -prefix STRING, -pfx STRING Specifies that all messages are to be formatted with the specified string as a prefix. This prefix appears after the indentation (if any was specified). The prefix must explicitly include trailing spaces, if any are desired to separate the prefix from the message text. By default, there is no prefix. -duplicates, -dup inhibits the printing of "=" messages for messages whose text is the same as the previous message printed. All messages are printed exactly as they appear in the log. -no_duplicates, -ndup prints "==" for messages whose text is the same as the previous message printed. (Default) -date_format FORMAT_STRING, -dfmt FORMAT_STRING specifies a date/time format string (see time_format.gi.info) to be used when formatting the date when successive messages are printed with different dates. The date string is printed on a line entirely by itself, preceded by a blank line. If the date format string is blank, no date separators will be printed; this should be used if a -time_format string is specified that includes the date as well. The default date string is "^9999yc-^my-^dm ^da ^za", which prints as "1984-10-31 Wed est". By specifying null strings for date, time, and number formats, the log can be printed and saved; it can then be compared to another log script later, without spurious mis-compares because the times and sequence numbers do not match. -time_format FORMAT_STRING, -tfmt FORMAT_STRING specifies a date/time format string (see time_format.gi.info) to be used when formatting the message time portion of the message. If the string is null, no time is printed with the messages. The default time format is "iso_time", which prints as "23:21:59". -number_format IOA_STRING, -nfmt IOA_STRING specifies an ioa_ string to be used when printing the sequence number for the message. If the string is null, no sequence number is printed with the message. The default is "^7d". Control arguments (miscellaneous): -header, -he specifies that a header is to be printed giving the times and sequence numbers of the first and last messages processed. (Default) -no_header, -nhe specifies that no header is to be printed. -process_id, -pid specifies that the process_id of the process which logged the message is to be printed -no_process_id, -npid specifies that the process_id is not to be printed. (Default) -data_class, -dc specifies that the binary data class of the message is to be printed. Note: This control argument merely specifies that the data class name is to be printed; if the binary data is to be displayed as well, the -octal or -interpret control argument must also be specified. -no_data_class, -ndc specifies that the binary data class of the message is not to be printed. Note: This control argument merely specifies that the data class name is not to be printed; if the binary data is not to be printed as well, the -no_expand control argument must also be specified. (Default) -absolute_pathname, -absp specifies that the absolute pathname of any log segment examined while processing messages is to be printed; the pathname of each segment is printed only once, whenever segments are switched. -no_absolute_pathname, -nabsp specifies that log segment pathnames are not to be printed. (Default) -output_switch NAME, -osw NAME specifies that the messages are to be written on the named I/O switch. The default is user_output. -procedure NAME, -proc NAME specifies that entrypoints in the procedure called NAME are to be used instead of entrypoints in log_read_ to read the log. This is used to read logs protected by inner-ring subsystems, where the inner-ring subsystem provides a replacement log-reading procedure. See the "Notes on inner-ring logs" section, below. Notes on string matching: The strings specified by -match and -exclude, or by -match_data and -exclude_data, are processed in sequence. An arbitrary number of strings may follow any of those control arguments, and each string will be treated as if it was preceded by another instance of the control argument, except that any string beginning with a hyphen and not immediately following one of the match/exclude control arguments is treated as a new control argument, and no more strings are picked up until the next match/exclude argument. A string may be either a text string, in which case it is tested simply to see whether it is a substring in the message, or it may be a regular expression, which is matched against the message. A string will be interpreted as a regular expression if it begins and ends with "/" characters. Each log message is processed against the set of strings, matching its text (or data) to see if it contains the string. There are two simple cases: only match strings, and only exclude strings. In the case of only match strings, any log message that matches any of the strings will be printed. In the case of only exclude strings, a log message will be printed only if it matches none of the strings. The more complicated case where match and exclude strings are mixed is handled as follows: test the message against each string in turn. If the message matches, and the string is a "-match" string, the "print-this-message" flag is set on. If the message matches, and the string is a "-exclude" string, the flag is set off. Otherwise, the flag is unaffected. The flag's initial value is on if the first string was a "-exclude" string, and off if the first string was a "-match" string. List of data classes: A data class is a short string (1 to 16 characters) stored with any message that contains binary data, and is used to identify the expander procedure used to expand the data into its interpreted textual form. The data class is specified when the message is placed into the log. syserr identifies an old-style syserr log message. The "syserr binary" code (see syserr_binary_defs.incl.pl1 for a list) is the first word of the data in the message; the remaining words of data are the real binary syserr data. io_status identifies a message indicating the status of an I/O device or an error on that device. Binary data of this class should be interpreted using the io_error_summary command. hwfault identifies a message containing machine state information from a hardware failure. Binary data of this class should be interpreted using the display_cpu_error command. mos identifies a message containing information about a main memory auto-corrected error. Binary data of this class should be interpreted using the mos_edac_summary command. segdamage identifies a message containing information about damage to a particular storage system object. voldamage identifies a message containing information about damage to a particular storage system volume. mdc_del_uidpath identifies a message containing the UID pathname of a master directory which is missing but still registered. mmdam identifies a message containing information about the location of main memory frames removed from service due to parity errors. mpc_poll identifies a message which contains MPC data filed by poll_mpc. Binary data of this class should be interpreted using the mpc_data_summary command. fnp_poll identifies a message which contains FNP data filed by poll_fnp. Binary data of this class should be interpreted using the fnp_data_summary command. config identifies a message containing a copy of "cards" from the system config deck. vtoce identifies a message containing a copy of a VTOCE which was found inconsistant by the system scavenger. access_audit identifies a message containing information about access attempts to various system objects. ibm3270_mde identifies a message containing data about an error encountered by the 3270 multiplexer. Access required: For all logs except inner-ring logs, read permission is required on the log segments themselves, and status permission is required on their containing directories. If an access error is encountered searching for older history logs, the search is stopped at that point, and no further history will be available. For the logs selected by control arguments, the control argument descriptions list the standard history directories for the logs. For inner-ring logs (the Data Management system log is the only standard inner-ring log), access to the logs is required, as is access to the gate used by the log-reading procedure (see -procedure). Notes on message selection: Messages are selected for printing in a series of steps, each of which filters out certain messages according to the control arguments specified. The set of messages at each step is any message that were left after the previous step. If a control argument was not specified, then its corresponding step eliminates no messages. Note that the -expand control arguments do NOT select messages, but only affect how their contents are displayed: 1) -to (stop looking after specified message) 2) -from (stop looking before specified number) 3) -for TIME (stop looking after specified time) 4) -last TIME (stop looking before specified time) 5) -severity 6) -exclude (eliminate matching messages) 7) -match (eliminate non-matching messages) 8) -exclude_data (eliminate matching messages) 9) -match_data (eliminate non-matching messages) 10) -for NUMBER (stop after NUMBER are printed) 11) -last NUMBER (stop after NUMBER are printed) Notes on severity values: Severity values in log messages are used to indicate the importance of the message being logged, in a general way. Most logs use increasing severity to indicate increasing importance, but the actual meaning depends on the log. For the Answering Service and Message Coordinator logs, the severities have the following meanings: 0 => Message just logged 1 => Message logged and printed on a console 2 => Message logged and printed on a console with bells 3 => Message logged, printed, and the system crashed For the syserr log, the severities have different meanings: 0 => Message logged and printed on syserr console 1 => Message logged, printed, and the system crashed 2 => Message logged, printed, and the process writing the message is terminated. 3 => Message logged and printed, and console alarm sounded 4 => Message just logged, or printed if logging mechanism is inoperable 5 => Message just logged, or discarded if it can't be logged The severities 20 to 25, 30 to 35, and 40 to 45 are handled just like 0 to 5, but are different to indicate that the originating program was writing an access audit message, rather than just an informative message. Notes on inner-ring logs: Some applications create logs in an inner ring that must be read using a special interface. The only standard log to do this is the Data Management system log, and it is read by specifying the -dm_system control argument which supplies both the pathname and the procedure name (dm_log_read_). Other applications may provide their own special procedures for log reading, in which case both the log pathname and the procedure name must be supplied explicitly via the -pathname and -procedure control arguments. Note that a log read using a reader procedure may enforce additional access requirements as well as requiring access to the log itself. In particular, the user must have access to the reader procedure. Compatibility features-- The following control arguments are accepted for compatibility with the old print_syserr_log and print_log commands: -action => -severity -next => -for -debug, -db => -duplicates The effect of print_syserr_log's -class argument can be achieved by supplying a range to the -severity argument: "-class 2" is replaced by "-severity 20:29". ----------------------------------------------------------- Historical Background This edition of the Multics software materials and documentation is provided and donated to Massachusetts Institute of Technology by Group BULL including BULL HN Information Systems Inc. as a contribution to computer science knowledge. This donation is made also to give evidence of the common contributions of Massachusetts Institute of Technology, Bell Laboratories, General Electric, Honeywell Information Systems Inc., Honeywell BULL Inc., Groupe BULL and BULL HN Information Systems Inc. to the development of this operating system. Multics development was initiated by Massachusetts Institute of Technology Project MAC (1963-1970), renamed the MIT Laboratory for Computer Science and Artificial Intelligence in the mid 1970s, under the leadership of Professor Fernando Jose Corbato. Users consider that Multics provided the best software architecture for managing computer hardware properly and for executing programs. Many subsequent operating systems incorporated Multics principles. Multics was distributed in 1975 to 2000 by Group Bull in Europe , and in the U.S. by Bull HN Information Systems Inc., as successor in interest by change in name only to Honeywell Bull Inc. and Honeywell Information Systems Inc. . ----------------------------------------------------------- Permission to use, copy, modify, and distribute these programs and their documentation for any purpose and without fee is hereby granted,provided that the below copyright notice and historical background appear in all copies and that both the copyright notice and historical background and this permission notice appear in supporting documentation, and that the names of MIT, HIS, BULL or BULL HN not be used in advertising or publicity pertaining to distribution of the programs without specific prior written permission. Copyright 1972 by Massachusetts Institute of Technology and Honeywell Information Systems Inc. Copyright 2006 by BULL HN Information Systems Inc. Copyright 2006 by Bull SAS All Rights Reserved