Name

Synopsis

Description

Contool captures and displays any messages sent to the system console. Each message is timestamped as it arrives. The messages are displayed in a scrolling text window, so the user can scroll through old messages.

When a message arrives, contool will beep and, if closed, begin blinking its icon until the user opens the tool. This behavior can be changed by modifying the default contool properties.

Contool must be run under either Open Windows or X Windows. It accepts the standard Open Windows command line options.

Options

\(hyc file

specifies an alternate configuration file. Contool normally reads its configuration information from the path specified in the CONTOOL_FILTERS environment variable or, if CONTOOL_FILTERS is not defined, from ~/.contool.

\(hyf

forces contool to fork itself into the background after acquiring the console. This option is most useful when starting contool from your ~/.xinitrc or ~/.openwin-init file, where multiple tools are started in the background. Even if contool is started first, other tools may begin running and produce error messages before contool can acquire the console. By using the -f option you can start contool in the foreground, preventing other tools from starting until contool has acquired the console.

\(hyi input

specifies an alternate input source. Contool normally reads messages from the system console. If -i is used, contool will read messages from the specified input. Input must be the pathname of a either a FIFO, or a character special device like /dev/tty. Input can also be given as `-', indicating that contool should read messages from its standard input.

\(hyl

enables logging when contool starts. Initially, contool does not log messages to a file. This option allows logging to be started automatically. Logging behavior can be enabled and disabled via the `File' menu (see below).

\(hyL logfile

specifies an alternate log file. The value of logfile overrides any log file stored in the configuration file. The -l and -L options used together allow multiple copies of contool to be started on a single machine, with each copy logging to a different file, without having to create and maintain multiple configuration files.

\(hyn

prevents contool from acquiring the console when it starts. This is most useful when testing a new version of contool, so that the test copy does not interfere with any previously running console tool.

User Interface

Contool presents the user with a control panel containing three buttons and a scrolling text window. Console messages appear in the text window; contool's behavior is managed with the File, View, and Edit buttons. These buttons have several menu choices associated with them:

File: Load Configuration...

brings up the Load Configuration dialog box. This dialog contains a non-exclusive setting, a text field, and a single Load button. The setting has two entries: `Tool Properties' and `Filter Definitions'. The user can choose which of these items to load from the configuration file. The default action is to load both properties and filters from the file.

The text field contains the path of the configuration file. By default,

this is either the value of the -c option (above), the value of the CONTOOL_FILTERS environment variable, or ~/.contool. This text field provides file name completion, like csh(1) , by typing a space or carriage return.

After determining which components to be read from the file, and the name of

the file, clicking on the Load button will cause the desired elements to be read from the file. If filters are loaded, any existing filters are discarded. If contool was in the middle of filtering a multi-line message, that filtering action is terminated.

Contool can read files created by all previous versions of

contool. Files written by contool cannot be read by any previous version.

File: Save Configuration...

is analogous to the Load Configuration operation, bringing up a dialog box containing a non-exclusive setting, a text field, and a Save button. In the same manner as the Load Configuration dialog, the user indiactes which items he desires to save, specifies the destination file, and clicks on the Save button to save the information.

Contool writes the data in a format incompatible with previous

versions (release 3.0 or earlier) of the tool.

File: Start Logging

starts logging console messages to the log file specified by the tool properties, or the -L option (above). The tool properties also contains a switch which determines whether messages are written before or after filtering occurs. If before, all messages are logged. If after, a message is written to the log if it does not match a filter and the default action in the tool properties has `Log message' enabled; or if it matches a filter with both the `Save' and `Log message' attributes set.

The log file is written in such a manner that multiple invocations of

contool can write to the same log file without conflict. New messages are always appended to the log file. Log files can be forcibly flushed with a SIGHUP; see SIGNALS, below.

File: Stop Logging

stops the logging process.

File: Print

uses the `Print Filter' specified in the tool properties to print the contents of the console. Only messages saved in the console can be printed.

File: About Contool...

provides a brief history of contool, and allows users to send e-mail to the contool developer.

View: Archive...

opens the message archive dialog box. This dialog box displays a scrolling window containing all messages archived from the main console display. See MESSAGE ARCHIVE, below.

View: Archive Messages

moves all the messages in the console display to the message archive. This is a handy way to remove already viewed messages from the console without losing them for later review. By periodically moving messages to the archive, only the most recent messages will be visible in the main console display. Messages can be archived automatically as well; see TOOL PROPERTIES, below.

View: Become Console

ensures that contool has the system console attribute. SunOS allows exactly one process in the system to own the console. If some other process takes control of the console, the user can reassign the console attribute to contool using this menu selection.

View: Clear Messages

clears all messages from the console text display.

View: Reset Filter

interrupts filtering of a multi-line filter. If the user incorrectly specifies the end pattern of a multi-line filter, contool may never stop processing the filter, causing all subsequent console messages to be incorrectly handled. This selection resets the effect of any multi-line filter that may be in effect.

When processing a multi-line filter, contool displays the

starting filter pattern in the left window footer. If the left footer is blank, contool is not processing a multi-line filter.

Edit: Filters...

brings up the Filters dialog box. See EDITING FILTERS, below.

Edit: Properties...

brings up the Tool Properties dialog box. See TOOL PROPERTIES, below.

Editing Filters

Filters

This scrolling list shows the starting pattern of each filter currently used by contool. The pattern text is preceded by a small glyph indicating whether the filter is a single-line or multi-line filter.

If exactly one item in the list is selected, the properties of that filter

will be displayed in the dialog box. If no, or more than one, filter is selected, the remainder of the dialog box is grayed out.

Insert

This button inserts a new blank filter into the scrolling list, allowing the user to add new filters to the filter set. A menu attached to the button allows the user to select the insert point: at the top of the list, before the current selection, after the current selection, or at the bottom of the list. The `before' and `after' choices are only enabled if exactly one filter in the list is selected. The default position is the bottom of the list.

Edit

This button edits the currently selected filters in the list. The menu attached to this button has four choices: Cut, Copy, Paste, and Delete.

The Cut operation removes the selected filters from the list

and places them on the clipboard, where they can subsequently be pasted back into the list.

The Copy operation copies the selected filters to the clipboard.

The filters are not removed from the list. The copied filters can subsequently be pasted back into the list.

The Paste operation copies filters from the clipboard into the list.

This selection has a menu which specifies the paste position: at the top of the list, before the current selection, after the current selection, or at the bottom of the list. The `before' and `after' choices are only enabled if exactly one filter in the list is selected. The default position is the bottom of the list.

The Delete operation removes the selected filters from the list

without placing them on the clipboard. Once deleted, filters cannot be recovered with a paste operation.

The Cut, Copy, and Delete selections are only presented

if one or more filters in the list are selected. The Paste selection is only available after a Cut or Copy operation.

Update

This button updates the currently selected filter using the values presented in the remainder of the dialog box. This button is only accessible if exactly one filter in the list is selected.

Update is used to modify an existing filter. When just that filter

is selected, its attributes are placed into the other dialog elements described below. After adjusting the filter attributes, the user clicks the Update button to apply the changes to the currently selected filter.

In a similar manner, Update is used to apply attributes to a new,

blank filter placed in the list via the Insert button.

Type

The Type toggle indicates whether a filter will match just a single line message, or will match a multiple line message. When `Single line filter' is chosen, the End pattern item is disabled, and the user must specify the pattern which will match a single line of text written to the console. When `Multi-line filter' is selected, the End pattern item is enabled, and the user needs to specify both a starting and an ending pattern. All text following a line which matches the starting pattern, up to and including a line which matches the ending pattern, is considered to be part of the filtered message.

Pattern

This text field specifies the regular expression which matches the first (and, in the case of single line filters, the only) line of text in the filtered message. Any valid regular expression is permitted. Users that are trying to match some text exactly should be aware that regular expressions can match text anywhere in a line, and that the expression should be anchored to the start (or end) of the line by using the "^" (or "$") metacharacters. For more information on regular expressions, see ed(1) .

As a special extension to regular expressions, contool recognizes

a backslash (`\') followed by one or more octal digits as a single character in the expression. This allows non-printing characters, such as control characters, to be inserted in the text pattern. If a backslash is followed by any other character, it is placed in the pattern verbatim. Thus, to create an expression which matches a control-G followed by a backslash, the pattern `\007\' would suffice.

End pattern

If the Type is set to `Multi-line filter', this field must contain the regular expression which matches the last line of the block of text handled by this filter.

Timeout

If the Type is set to `Multi-line filter', this field sets a limit on how long contool will process the filter. This prevents filters with erroneous end patterns from absorbing all console output once they begin filtering. The default value, 0, indicates that no timeout is in effect.

Comment

This text field contains any comments regarding the filter the user wishes to record. Since some filters can be rather arcane, it is suggested that users comment their filters.

When matched

This exclusive setting dictates the behavior of contool when a filter is matched. If `Save message' is chosen, the message is copied into the console display, and various actions can be taken. If `Ignore message' is selected, the filter text is discarded and no further actions are taken by contool.

When saved

If When matched is set to `Save message', this non-exclusive choice item will be enabled, allowing the user to specify what contool should do with this message.

The `Beep' choice causes the terminal bell to be sounded. If

selected, the beep counter to the right of this item is enabled, allowing the user to choose anywhere from one brief beep up to 99 annoying beeps.

The `Command' choice causes a single command to be executed.

The text field to the right of this item must contain the command to be executed. Contool will write the text of the message to the standard input of the command. For example, using `mail -s 'Contool output' user' as the command would mail the message text to the user.

The `Flash icon' choice causes the contool icon to flash,

alternating between the `Check console' and `Flash' icons.

The `Log message' choice causes the message to be written to

the message log, if logging is enabled and is performed after filtering.

The `Open window' choice causes contool to open from

its iconic state, and to move in front of any obscuring windows.

The `Timestamp' choice causes contool to write a timestamp

to the console before copying the message into the console. The timestamp is written in conjunction with the timestamp resolution specified in the Tool Properties dialog.

Apply

This button makes the filters contained in the scrolling list the current set of active filters. Until this button is clicked, all changes made to the filters are not used by contool. After clicking Accept, the changed filters become the current working set.

Note that even after clicking Accept, the configuration file is

not updated. To make the changes permanent between invocations of contool, press the Apply and Save button, or use the Save Configuration dialog to save the changed filters.

Apply and Save

This button makes the filters in the scrolling list the current set of active filters and writes those filters and the tool properties to the current configuration file. To write the filters to a different file, or to write just the filters without the tool properties, press the Apply button and use the Save Configuration dialog instead.

Reset

This button discards any changes made to the current filter set, restoring the filter list to match the current filter set in use by contool.

Tool Properties

Default action

This non-exclusive setting determines the actions taken by contool when a message arrives which does not match any filter. The various choices in this setting exactly correspond to the When saved setting the Filters dialog, above.

Log file

This text field contains the path of the file to which messages will be logged. This field must be filled in before logging is enabled.

Log messages

If this exclusive setting is set to `before filtering', all messages will be logged. If set to `after filtering', messages that match filters whose `When matched' behavior is set to `Ignore message' will not be logged.

Archive messages

This exclusive setting determines how messages will be moved from the main console display to the message archive. If set to `Manually', messages will only be archived when the user selects Archive Messages from the View menu in the main contool window. If set to `When closing contool', messages are copied to the archive whenever the contool window is closed. This mode assumes that you typically open contool, read all the messages, and close the window. Each time you open the window, you'll only see messages that have arrived since you last closed contool.

Archived messages can be viewed in the message archive, described below.

Print filter

This text field specifies the command to be used to print the console. The default is `lpr'. Local site dependencies may require a different command.

\*(lqAll is well\*(rq icon

This text field contains the path of a file in either icon or XBM format. Icon-format files may be created with iconedit(1) ; XBM-format files are created with a number of tools. If the path is not absolute, the value of the ICON_PATH environment variable will be used to find the file. ICON_PATH should contain a list of directories, separated by colons. The contained image will be used as contool's regular icon image. This image is displayed whenever no flashing is in effect.

\*(lqAll is well\*(rq icon mask

This text field contains the path of a file in either icon or XBM format. The contained image will be used to mask contool's `All is well' icon image when contool is run on a color desktop. Masking is not supported on monochrome desktops. The `All is well' icon is not masked if this field is left blank.

\*(lqCheck console\*(rq icon

This image is alternated with the `Flash' icon image whenever flashing is required.

\*(lqCheck console\*(rq icon mask

This image will be used to mask contool's `Check console' icon image when contool is run on a color desktop. The `Check console' icon is not masked if this field is left blank.

\*(lqFlash\*(rq icon

This image is alternated with the `Check console' icon image whenever flashing is required. Ideally, all three icons should be the same size.

\*(lqFlash\*(rq icon mask

This image will be used to mask contool's `Flash' icon image when contool is run on a color desktop. The `Flash' icon is not masked if this field is left blank.

Timestamp resolution

This numeric field specifies the minimum number of seconds to wait before writing a new timestamp to the console. Messages which require timestamping will only write a timestamp if this number of seconds have transpired since the last timestamp.

Maximum message text

This numeric field determines the maximum size, in bytes, of messages that will be stored in the console. When writing a message to the console would exceed this limit, some number of bytes, as determined by the Overflow delete amount, below, will be removed from the front of the console. This feature prevents the console from becoming so large over time that it begins to swamp system resources.

Overflow delete amount

When writing a message to the console would exceed the Maximum message text, above, text will be deleted from the beginning of the console to make room. This numeric field specifies how many bytes to remove to make room. Contool will attempt to remove whole messages within the constraints of the console size to preserve a readable console.

Apply

This button makes the values in the dialog box the current tool properties. Until this button is clicked, all changes made to the properties are not used by contool. After clicking Accept, the changed values become the current properties.

Note that even after clicking Accept, the configuration file is

not updated. To make the changes permanent between invocations of contool, use the Save Configuration dialog to save the changed properties.

Reset

This button discards any changes in the dialog box made to the current properties, restoring the properties to match the current properties in use by contool.

Message Archive

Clear

The Clear button removes all the messages from the archive. Normally, the archive works like the main contool display: it retains a certain amount of text, and deletes the oldest messages as new messages arrive in excess of that amount. The Clear button circumvents this feature and explicitly clears the archive display.

The archive window will hold ten times the amount of text specified for the

main console display, as determined by the Maximum message text value in the Tool Properties dialog, described above.

Print

The Print button prints the contents of the archive, using the `Print Filter' specified in the Tool Properties dialog.

Configuration File Format

Environment Variables

CONTOOL_FILTERS

specifies the file from which contool reads its filters and properties. If not defined, ~/.contool is used. If -c is specified, it overrides the use of CONTOOL_FILTERS.

CONTOOL_LABEL

specifies the label to be placed in contool's main window. The default label contains the current release number of contool.

CONTOOL_LOGNAME

specifies the name to be prefixed to each message written to the console log file. If this variable is not defined, the machine's hostname is used.

ICON_PATH

contains a colon-separated list of directories which contool will search to find the icon files specified in various tool properties.

Signals

SIGHUP

Upon receipt of SIGHUP, contool will close and reopen its log file, if logging is enabled. This guarantees that logged messages are flushed to disk.

SIGUSR1

Upon receipt of SIGUSR1, contool will stop blinking its icon. This is a handy way to stop blinking without opening contool.

Files

~/.contool    configuration file

See Also

Author

Chuck Musciano
Advanced Technology Department
Harris Corporation
PO Box 37, MS 16/1912
Melbourne, FL 32902
(407) 727-6131
E-mail: chuck@trantor.harris-atd.com
Fax: (407) 729-3363

Bugs

Contool is a view-only tool, and there is no way to type commands on the console.

Window system bugs may cause unusual, but harmless, quirks in the behavior of contool. In particular, displaying a menu in a dialog box without actually selecting an item from that menu may cause the dialog box to close.

Table of Contents

• Name
• Synopsis
• Description
• Options
• User Interface
• Editing Filters
• Tool Properties
• Message Archive
• Configuration File Format
• Environment Variables
• Signals
• Files
• See Also
• Author
• Bugs