Input Context Variables

The Xt Intrinsics provides the XtAddInput facility, which allows an application to register interest in any data available from a particular file descriptor. When programming in C, the application provides a handler function, which is invoked when input is available. It is up to the handler to read the data from the input source and to handle character escaping and line continuations.

dtksh also supports the XtAddInput facility, but takes it a step further and makes it easier for shell programmers to use. By default, when a shell script registers interest in a file descriptor, dtksh invokes the shell script's input handler only when a complete line of text has been received. A complete line of text is defined as a line terminated either by an unescaped newline character or by the end of the file. The input handler is also called if no data is available and the end of the file has been reached. The handler can then use XtRemoveInput to remove the input source and to close the file descriptor. The advantage of this default behavior is that input handlers need not be concerned with escape processing or with handling line continuations. The disadvantage is that it assumes that all of the input is line-oriented and contains no binary information.

dtksh also supports a "raw" input mode if the input source contains binary information or if the input handler wants to read the data from the input source directly. In raw mode, dtksh does not read any of the data from the input source. Whenever dtksh is notified that input is available on the input source, it invokes the shell script's input handler. It is then the handler's responsibility to read the incoming data, perform any required buffering and escape processing, and detect when the end of the file has been reached (so that the input source can be removed and the file descriptor closed). This mode seldom needs to be used by a dtksh script.

Whether the input handler has been configured to operate in the default mode or in raw mode, dtksh sets up several environment variables before calling the shell script's input handler. These environment variables provide the input handler with everything needed to handle the incoming data. The environment variables are:

INPUT_LINE

If operating in the default mode, this variable contains the next complete line of input available from the input source. If INPUT_EOF is true, then there is no data in this buffer. If operating in raw mode, then this variable always contains an empty string.

INPUT_EOF

If operating in the default mode, this variable is set to false anytime INPUT_LINE contains data, and it is set to true when the end of file is reached. When the end of file is reached, the shell script's input handler should unregister the input source and close the file descriptor. If operating in raw mode, this variable is always set to false.

INPUT_SOURCE

This indicates the file descriptor for which input is available. If operating in raw mode, this file descriptor is used to obtain the pending input. The file descriptor is also used to close the input source, when no longer needed.

INPUT_ID

This indicates the ID returned by XtAddInput, when the input source was originally registered. This information is needed to remove the input source with XtRemoveInput.