QTERM(1)

NAME
qterm - Query Terminal

SYNOPSIS
qterm [ +|-alt ] [ +|-always ] [ +|-longname ] [ -querystr string ] [ +|-quiet ] [ +|-real ] [ +|-sent ] [ +|-timeout ] [ +|-trycommon ] [ +|-usrtab ] [ +|-watch ] [ +|-systab ] [ -wait interval ] [ -file tabfile ]
qterm -version

DESCRIPTION
Qterm is used to query a terminal to determine its name. This is done by sending a special query sequence to the terminal, reading in a response, and comparing it against a table of possible responses. The ``name'' printed to standard output should be one found in the termcap(5) (or terminfo(5) for System V systems) database.

Qterm works by first reading all the appropriate qtermtab files. It then goes through and tries to query the terminal first using all of the entries that were specified as primary in the qtermtab file(s). Upon receiving a response to a query for a primary entry, qterm will then proceed to query the terminal using all entries marked as secondary which have a termname field which matches the primary's nextname field. Upon receiving a response to a secondary query, the secondary's nextname field will be used as the name printed to standard output. i.e. Given a matching primary entry with a termname of vt100 and a nextname of ansi, and a secondary entry with a termname of ansi and a nextname of xterm, qterm will output xterm as the terminal name to standard output.

For csh(1) users, putting a line in your .login file such as:

setenv TERM `qterm`

should automagically set your terminal type. For sh(1) users, putting these lines in your .profile file should set your terminal type:

TERM=`qterm`
export TERM

By default, qterm uses the system tab file /usr/pkg/etc/qtermtab to obtain information for querying terminals.

OPTIONS

If the environment variable $QTERMOPTIONS is set, it is first parsed for any of the options listed below. Options specified on the command line override options from $QTERMOPTIONS.

+alt
    Use the alternate string ``<ESCAPE>[c'' when asking the terminal to identify itself. This string is recognized by most ANSI compatible terminals.

-alt
    Don't use the alternate string, but the string found in the tabfile being used. This is the default.

+always
    Always send the terminal query string. Normally the query string is only sent if it differs from the last string sent.

-always
    Only send the terminal query string if it differs from the last string sent. This is the default.

-file tabfile
    Use <tabfile> to find information for querying the terminal.

+longname
    Print only the long (verbose) terminal name.

-longname
    Don't print the long (verbose) terminal name. This is the default.

-querystr string
    Use string as the string to send to query the terminal. The default is the query field from qtermtab.

+quiet
    Be quiet and only print the terminal name to standard output.

-quiet
    Don't be quiet and only print the terminal name to standard output. This is the default.

+real
    Determine the real name of a terminal by using secondary entries in qtermtab to query for the actual terminal type.

-real
    Don't use secondary entries to determine the real type of terminal. Only primary entries will be used. This is the default.

+watch
    Watch the characters sent and received to the terminal.

-watch
    Don't watch the characters sent and received to the terminal. This is the default.

+timeout
    Wait for timeout when listening for response string. This is useful if the first entry in a qtermtab doesn't have a response string with an ending character that is common with the rest of the qtermtab entries.

-timeout
    Disable waiting for timeout when listening for response string. This is the default.

+trycommon
    Try sending common query sequences. After each sequence is sent, qterm checks for a response. If a response is received, the normal terminal information is display. The common answerback sequences used are those defined by the comseq entry in qtermtab.

-trycommon
    Don't try sending common query sequences. Only use those sequences specified in the qtermtab file(s). This is the default.

-version
    Print version information and exit.

+usrtab
    Use $HOME/.qtermtab to find information for querying the terminal.

-usrtab
    Don't use $HOME/.qtermtab to find information for querying the terminal. This is the default.

+sent
    Display the final response sent from the terminal in a ``nice'' fashion.

-sent
    Don't display the final response sent from the terminal. This is the default.

+systab
    Use /usr/pkg/etc/qtermtab to find information for querying the terminal. This is the default

-systab
    Don't use system tab file to find information for querying the terminal.

-wait interval
    Set the wait (timeout) period to interval (in seconds).

QTERMTAB
The format of the file $HOME/.qtermtab and qterm's system tab file /usr/pkg/etc/qtermtab, consists fields seperated by white space (tabs and/or spaces). Blank lines or lines starting with the character ``#'' are ignored and may be used as comment lines. A character preceeded by a ``^'' is taken to mean the control character. (i.e. ``^['' is interpretted as an <ESCAPE>). Both the query and response fields may contain octal values preceeded by a `\'. (i.e. <ESCAPE> can be represented by `\033'.)

The first field contains a keyword which indicates how the rest of the line should be parsed. Each keyword can be in upper and/or lower case and most can be appreviated to as few as 3 characters.

    primary and secondary
        Both primary and secondary lines consist of six fields:

        keyword
            The keyword primary or secondary.

        query
            The string to use to query the terminal.

        response
            The string to expect in response to a query.

        termname
            The name of the terminal (compatible with termcap(5) and terminfo(5)) to print to standard output (stdout).

        nextname
            The name of the next terminal entry to try. A ``-'' (dash) means none.

        description
            A description of the terminal to be printed to standard error (stderr). This field may contain white space (space and/or tab) characters.

    comseq
        List of common query sequences for use with the +trycommon option. Each sequence specified should be seperated by white space.

    If the first field does not match one of these keywords, then the line is assumed to be an old style entry containing four fields. The first field is the string that should be used to query the terminal. The second field is the string to expect in response to the query. The third field is the terminal name. The fourth field is the description of the terminal.

The response field can be a regular expression denoted by a leading backslash (`\'). i.e. "^[[123" matches the string "^[[123", whereas "^[\[123]" matches "^[1" or "^[2" or "^[3". Each character in a regular expression must be prefixed with a leading backslash. See ed(1) for regular expression information.

Below is a sample file:

    #
    # Common Send sequences for use with +trycommon
    #
    comseq  ^[Z ^[[c ^[[0c ^[[>c ^[[<0I ^E
    #
    #
    #KEY    SEND    RECEIVE         TERM    NEXT    DESCRIPTION
    prime   ^[Z     ^[[?1;0c        vt100   vt100   DEC VT100
    prime   ^[Z     ^[[?1;1c        vt100   vt100   DEC VT100 with STP
    prime   ^[Z     ^[[?1;2c        vt100   vt100   ANSI/VT100 Clone
    second  ^[[>c   ^[[?1;20;0c     vt100   vt100   Real DEC VT100 or Clone
    second  ^[[>c   ^[[?1;2c        vt100   xterm   XTerm Workstation Emulator

RETURN VALUES
qterm exits with the following status:

    0   Terminal was recognized.

    1   General error.

    2   Terminal not recognized.

AUTHOR
Michael A. Cooper,
University Computing Services,
University of Southern California.

FILES
/usr/pkg/etc/qtermtab    - System table
$HOME/.qtermtab    - User's table
/etc/termcap    - termcap(5) database

SEE ALSO
csh(1), ed(1), sh(1), termcap(5)

DIAGNOSTICS

Terminal not recognized - defaults to dumb.
    qterm did not receive a response from the terminal, or the response did not match any that qterm has stored internally. Use the +watch option to check to see which is the case.

BUGS
Many terminals do not send a response at all.