<!-- $Id: Xterm-Title.html,v 1.6 1998/01/07 19:39:02 ric Exp $ -->
<html>
<head>
<title>How to change the title of an xterm</title>
</head>
<body>
<h1>How to change the title of an xterm</h1>
<h2>Richard Lister,
<tt><a href="mailto:ric@giccs.georgetown.edu">ric@giccs.georgetown.edu</a></tt>
</h2>
<p>
$Revision: 1.6 $,
<!-- hhmts start -->
Last modified: Wed Jan 7 14:34:31 EST 1998
<!-- hhmts end -->
<p>
<hr>
<em>This document explains how to use escape sequences to dynamically change
window and icon titles of an xterm. Examples are given for several shells,
and the appendix gives escape sequences for some other terminal types.</em>
<hr>
<ul>
<li><a href="#location">Where to find this document</a>
<li><a href="#static">Static titles</a>
<li><a href="#dynamic">Dynamic titles</a>
<li><a href="#examples">Examples for different shells</a>
<ul>
<li><a href="#zsh">zsh</a>
<li><a href="#bash">bash</a>
<li><a href="#tcsh">tcsh</a>
<li><a href="#csh">csh</a>
<li><a href="#ksh">ksh</a>
</ul>
<li><a href="#appendix">Appendix: escapes for other terminal types</a>
<ul>
<li><a href="#xwsh">SGI <tt>wsh</tt>, <tt>xwsh</tt> and
<tt>winterm</tt></a>
<li><a href="#dtterm">CDE <tt>dtterm</tt></a>
<li><a href="#cmdtool">Sun <tt>cmdtool</tt> and <tt>shelltool</tt></a>
<li><a href="#example">Example</a>
</ul>
<li><a href="#credits">Credits</a>
</ul>
<hr>
<h2><a name="location">Where to find this document</a></h2>
<p>
This document is now part of the <a href="http://sunsite.unc.edu/LDP/HOWTO/">
Linux HOWTO Index</a> and can be found at
<a href="http://sunsite.unc.edu/LDP/HOWTO/mini/Xterm-Title.html">
<tt>http://sunsite.unc.edu/LDP/HOWTO/mini/Xterm-Title.html</tt></a>.
<p>
The latest version can always be found at
<a href="http://www.giccs.georgetown.edu/~ric/howto/Xterm-Title.html">
<tt>http://www.giccs.georgetown.edu/~ric/howto/Xterm-Title.html</tt></a>.
<p>
<hr>
<h2><a name="static">Static titles</a></h2>
<p>
A static title may be set for any of the terminals <tt>xterm</tt>,
<tt>color-xterm</tt> or <tt>rxvt</tt>, by using the <tt>-T</tt> and
<tt>-n</tt> switches:
<pre>
xterm -T "My XTerm's Title" -n "My XTerm's Icon Title"
</pre>
<h2><a name="dynamic">Dynamic titles</a></h2>
<p>
Many people find it useful to set the title of a terminal to reflect
dynamic information, such as the name of the host the user is logged
into, the current working directory, etc.
<p>
This may be done by using XTerm escape sequences. The following sequences
are useful in this respect:
<pre>
ESC]0;<i>string</i>BEL Set icon name and window title to <i>string</i>
ESC]1;<i>string</i>BEL Set icon name to <i>string</i>
ESC]2;<i>string</i>BEL Set window title to <i>string</i>
</pre>
where <tt>ESC</tt> is the <i>escape</i> character (\033), and <tt>BEL</tt> is
the <i>bell</i> character (\007).
<p>
<strong>Note</strong>: these sequences apply to most xterm derivatives,
such as <tt>nxterm</tt>, <tt>color-xterm</tt> and <tt>rxvt</tt>. Other
terminal types often use different escapes; see the
<a href="#appendix">appendix</a> for examples. For the full list of
xterm escape sequences see the file
<a href="http://www.giccs.georgetown.edu/~ric/howto/ctlseq2.txt">
<tt>ctlseq2.txt</tt></a>, which comes with the xterm distribution, or
<a href="http://www.giccs.georgetown.edu/~ric/howto/xterm.seq">
<tt>xterm.seq</tt></a>, which comes with the
<a href="http://babayaga.math.fu-berlin.de:80/%7Erxvt/">
<tt>rxvt</tt> distribution</a>.
<p>
These escapes really need to be applied every time the prompt changes.
This way the string is updated with every command you issue and can keep
track of information such as current working directory, username, hostname,
etc. Some shells provide special functions for this purpose, some don't
and we have to insert the title sequences directly into the prompt
string.
<p>
<hr>
<h2><a name="examples">Examples for different shells</a></h2>
<p>
In all the examples below we test the environment variable <tt>TERM</tt>
to make sure we only apply the escapes to xterms. We test for
<tt>TERM=xterm*</tt>; the wildcard is because some variants (such as
rxvt) can set <tt>TERM=xterm-color</tt>.
<h3><a name="zsh"><tt>zsh</tt></a></h3>
<p>
zsh provides some functions and expansions, which we will use:
<pre>
precmd () a function which is executed just before each prompt
chpwd () a function which is executed whenever the directory is changed
\e escape sequence for escape (ESC)
\a escape sequence for bell (BEL)
%n expands to $USERNAME
%m expands to hostname up to first '.'
%~ expands to directory, replacing $HOME with '~'
</pre>
There are many more expansions available: see <tt>'man zshmisc'</tt>.
<p>
Thus, the following inserted in <tt>~/.zshrc</tt> will set the xterm title
to "<tt><i>username</i>@<i>hostname</i>: <i>directory</i></tt>" ...
<pre>
case $TERM in
xterm*)
precmd () {print -Pn "\e]0;%n@%m: %~\a"}
;;
esac
</pre>
This could also be achieved by using <tt>chpwd()</tt> instead
of <tt>precmd()</tt>.
<h3><a name="bash"><tt>bash</tt></a></h3>
<p>
<tt>bash</tt> supplies a variable <tt>PROMPT_COMMAND</tt> which contains a
command to execute before the prompt. This example (inserted in
<tt>~/.bashrc</tt>) sets the title to
"<tt><i>username</i>@<i>hostname</i>: <i>directory</i></tt>":
<pre>
PROMPT_COMMAND='echo -ne "\033]0;${USER}@${HOSTNAME}: ${PWD}\007"'
</pre>
where <tt>\033</tt> is the character code for ESC, and <tt>\007</tt> for BEL.
Note that the quoting is important here: variables are expanded in
<tt>"..."</tt>, and not expanded in <tt>'...'</tt>. So <tt>PROMPT_COMMAND</tt>
is set to an unexpanded value, but the variables inside <tt>"..."</tt>
are expanded when <tt>PROMPT_COMMAND</tt> is used.
<p>
However, <tt>PWD</tt> produces the full directory path. If we want to
use the <tt>'~'</tt> shorthand we need to embed the escape string in the
prompt, which allows us to take advantage of the following prompt expansions
provided by the shell:
<pre>
\u expands to $USERNAME
\h expands to hostname up to first '.'
\w expands to directory, replacing $HOME with '~'
\[...\] embeds a sequence of non-printing characters
</pre>
<p>
Thus, the following produces a prompt of "<tt>bash$ </tt>", and an xterm
title of "<tt><i>username</i>@<i>hostname</i>: <i>directory</i></tt>" ...
<pre>
case $TERM in
xterm*)
PS1="\[\033]0;\u@\h: \w\007\]bash\$ "
;;
*)
PS1="bash\$ "
;;
esac
</pre>
Note the use of <tt>\[...\]</tt>, which tells <tt>bash</tt> to ignore
the non-printing control characters when calculating the width
of the prompt. Otherwise line editing commands get confused while
placing the cursor.
<h3><a name="tcsh"><tt>tcsh</tt></a></h3>
<p>
<tt>tcsh</tt> has functions and expansions similar to those of
<tt>zsh</tt>:
<pre>
precmd () a function which is executed just before each prompt
cwdcmd () a function which is executed whenever the directory is changed
%n expands to username
%m expands to hostname
%~ expands to directory, replacing $HOME with '~'
</pre>
<p>
Unfortunately, there is no equivalent to zsh's <tt>print</tt> command allowing
us to use prompt escapes in the title string, so the best we can do is to use
shell variables (in <tt>~/.tcshrc</tt>):
<pre>
switch ($TERM)
case "xterm*":
alias precmd 'echo -n "\033]0;${HOST}:$cwd\007"'
breaksw
endsw
</pre>
but this gives the directory's full path instead of using '~'. Instead you
can insert the string in the prompt:
<pre>
switch ($TERM)
case "xterm*":
set prompt="%{\033]0;%n@%m:%~\007%}tcsh%% "
breaksw
default:
set prompt="tcsh%% "
breaksw
endsw
</pre>
which sets a prompt of "<tt>tcsh% </tt>", and an xterm title and icon
of "<tt><i>username</i>@<i>hostname</i>: <i>directory</i></tt>". Note that
the "<tt>%{...%}</tt>" must be placed around escape sequences (and cannot
be the last item in the prompt: see <tt>'man tcsh'</tt> for the details).
<h3><a name="csh"><tt>csh</tt></a></h3>
<p>
This is very difficult indeed in <tt>csh</tt>, and we end up doing something
like the following (in <tt>~/.cshrc</tt>):
<pre>
switch ($TERM)
case "xterm*":
set host=`hostname`
set user=`whoami`
alias cd 'cd \!*; set prompt="^[]0;${user}@${host}: ${cwd}^Gcsh% "'
breaksw
default:
set prompt='csh% '
breaksw
endsw
</pre>
where we have had to alias the <tt>cd</tt> command to do all the work of
setting the prompt. Note that the '<tt>^[</tt>' and '<tt>^G</tt>' in
the prompt string are single characters for ESC and BEL
(can be entered in emacs using '<tt>C-q ESC</tt>' and '<tt>C-q C-g</tt>').
<p>
I strongly recommend abandoning csh in favour of a more advanced shell:
zsh, bash or tcsh.
<h3><a name="ksh"><tt>ksh</tt></a></h3>
<p>
<tt>ksh</tt> provides little in the way of functions and expansions, so
we have to insert the escape string in the prompt to have it updated
dynamically. This example produces a title of
"<tt><i>username</i>@<i>hostname</i>: <i>directory</i></tt>" and a prompt
of <tt>"ksh$ "</tt>.
<pre>
case $TERM in
xterm*)
HOST=`hostname`
PS1='^[]0;${USER}@${HOST}: ${PWD}^Gksh$ '
;;
*)
PS1='ksh$ '
;;
esac
</pre>
However, <tt>PWD</tt> produces the full directory path. We can remove the
prefix of <tt>$HOME/</tt> from the directory using the <tt>${...##...}</tt>
construct. We can also use <tt>${...%%...}</tt> to truncate the hostname:
<pre>
HOST=`hostname`
HOST=${HOST%%.*}
PS1='^[]0;${USER}@${HOST}: ${PWD##${HOME}/}^Gksh$ '
</pre>
Note that the '<tt>^[</tt>' and '<tt>^G</tt>' in
the prompt string are single characters for ESC and BEL
(can be entered in emacs using '<tt>C-q ESC</tt>' and '<tt>C-q C-g</tt>').
<p>
<hr>
<h2><a name="appendix">Appendix</a>: escapes for other terminal types</h2>
<h3><a name="xwsh">SGI <tt>wsh</tt>, <tt>xwsh</tt> and <tt>winterm</tt></a>
</h3>
<p>
These terminals set <tt>TERM=iris-ansi</tt> and use the following escapes:
<pre>
ESC P 1 .y <i>string</i> ESC \\ Set window title to <i>string</i>
ESC P 3 .y <i>string</i> ESC \\ Set icon title to <i>string</i>
</pre>
For the full list of <tt>xwsh</tt> escapes see <tt>xwsh(1G)</tt>.
<h3><a name="cmdtool">Sun <tt>cmdtool</tt> and <tt>shelltool</tt></a></h3>
<p>
<tt>cmdtool</tt> and <tt>shelltool</tt> both set <tt>TERM=sun-cmd</tt>
and use the following escapes:
<pre>
ESC ] l <i>string</i> ESC \ Set window title to <i>string</i>
ESC ] L <i>string</i> ESC \ Set icon title to <i>string</i>
</pre>
These are truly awful programs: use something else.
<h3><a name="dtterm">CDE <tt>dtterm</tt></a></h3>
<p>
<tt>dtterm</tt> sets <tt>TERM=dtterm</tt>, and appears to recognise both the
standard <tt>xterm</tt> escape sequences and the Sun <tt>cmdtool</tt>
sequences. (I've only tested this on a Sun ... anyone have HP and DEC
versions they can test for me?).
<h3><a name="example">Example</a></h3>
<p>
Here's my full setup using <tt>zsh</tt> to handle all these terminal types:
<pre>
case $TERM in
xterm*|dtterm)
precmd () {print -Pn "\e]0;%n@%m: %~\a"} ## window & icon title
;;
iris-ansi)
precmd () {
print -Pn "\eP1.y%n@%m: %~\e\\" ## window title
print -Pn "\eP3.y%n@%m: %~\e\\" ## icon title
}
;;
sun-cmd)
precmd () {
print -Pn "\e]l%n@%m: %~\e\\" ## window title
print -Pn "\e]L%n@%m: %~\e\\" ## icon title
}
;;
esac
</pre>
<hr>
<h2><a name="credits">Credits</a></h2>
Thanks to the following people.
<dl>
<dt>Paul D. Smith <psmith@BayNetworks.COM> and
Christophe Martin <cmartin@ipnl.in2p3.fr>
<dd>both pointed out that I had the quotes the wrong way round in the
<tt>bash</tt> <tt>PROMPT_COMMAND</tt>. Getting them right
means variables <i>are</i> expanded dynamically.
<dt>Paul D. Smith <psmith@BayNetworks.COM>
<dd>suggested the use of <tt>\[...\]</tt> in the <tt>bash</tt>
prompt for embedding non-printing characters.
<dt>Christophe Martin <cmartin@ipnl.in2p3.fr>
<dd>provided the solution for <tt>ksh</tt>.
<dt>Keith Turner <keith@silvaco.com>
<dd>supplied the escape sequences for Sun <tt>cmdtool</tt> and
<tt>shelltool</tt>.
</dl>
<hr>
</body>
</html>
