NAME
zwgc - Zephyr Windowgram Client program
SYNOPSIS
zwgc [ -reenter ] [ -nofork ] [ -ttymode ] [ -f filename ] [ -subfile
filename ] [ -loc text ] [ -default portname ] [ -disable portname ]
... [ output driver options ] [ X Toolkit options... ]
DESCRIPTION
Zwgc is the main zephyr(1) client. It is responsible for receiving
selected zephyr notices on behalf of the user, formatting them, and
displaying them using one or more of the output devices.
Selection of Zephyr Notices
Zwgc subscribes to various notice classes and instances on behalf of
the user. Only notices in the subscription list will be received. The
subscription list is composed of the default subscriptions (stored on
the server), the user’s subscriptions file, and any subscriptions made
using zctl(1). The user’s subscription file defaults to
$HOME/.zephyr.subs, or it can be specified with the -subfile option.
If "-" is specified as the subscription filename, the subscriptions
will be read from standard input.
The zctl command is used to manipulate and change subscriptions. See
the zctl(1) man page for details.
Zephyr Description Files
Zwgc formats its output messages according to the commands in its
description file. The user’s description file ($HOME/.zwgc.desc by
default, or whatever is specified by -f) is read, or the system file is
read if the user’s does not exist.
Every time a notice is received, zwgc runs through the description
file, and executes the appropriate commands.
Zephyr Description File Syntax
A description file is simply a list of commands. Whitespace (spaces,
tabs, and line breaks) is used to separate tokens. The type and amount
of whitespace separating tokens is irrelevant. Comments can be
delimited by # and newline (for line-oriented comments, e.g. "# this is
a comment" on a line by itself) or by /* and */ (e.g. "/* this is a
comment */").
DESCRIPTION LANGUAGE
Expressions
Expressions are used by certain commands. They are composed from
string literals, variable references, function calls, and operators.
Parentheses can be used anywhere in an expression to group expressions
or increase readability.
String literals are specified by putting the contents in "double
quotes".
Variables are set using the set command (see "COMMANDS", below). They
are referenced in an expression by using the form $varname. Some
variables are set by default for each notice. All other variables
retain their values between notice interpretations, so that if you set
a variable, it retains that value until later modified.
Functions are called using a C-like syntax, fname(expr1,expr2), where
fname is the function name and exprn are the arguments.
Binary operators use infix notation, such as "a == b".
Some commands use an expression list (exprlist), which is simply a set
of expressions separated by whitespace (e.g. $var1 "lit1" $var2).
Default variables
The following variables are always available:
1, ...
Numeric variables are assigned values corresponding to that field
in the notice (the body of each notice is conceptually an array of
fields, each terminated with a null character). If the number is
greater than the number of fields actually in the notice, the
value is "". For example, the standard zwrite messages have two
fields: $1 is the signature, and $2 is the text of the message.
auth An indication of the authenticity of the notice. ‘‘yes’’ means
the notice is authentic, ‘‘no’’ means it is not, and ‘‘forged’’
means that the message claimed to be authentic but the
verification of the claim failed. The ‘‘forged’’ indication
usually appears when a user has changed his Kerberos tickets with
kinit(1) but has not run ‘‘zctl sub’’ to register this change with
the Zephyr servers.
class
The class of the current notice.
date The date on which the notice was sent.
default
The default output format for the current notice
error
An error message from the port read/write commands.
fromhost
The full name of the host from which the notice appears to have
been sent. This is not fully reliable, as the information used to
determine this hostname is not guaranteed to be correct (even for
authentic messages).
fullsender
The notice sender’s name, including the zephyr realm name.
instance
The instance of the current notice.
kind The kind of notice.
message
The full text of the message, with nulls converted to newlines.
number_of_fields
The number of fields in the message (a string representation of a
decimal number).
opcode
The opcode of the current notice.
output_driver
The name of the output driver in use.
port The port from which the notice was sent.
realm
The local zephyr realm.
recipient
The recipient for the current notice. If the notice is a
multicast (sent to several people), the recipient is set to ‘‘*’’.
sender
Usually a shortened version of fullsender. If the realm of the
sender is equal to the realm of the recipient, sender omits the
realm name.
time The time of day at which the notice was sent.
user The full zephyr name of the user (e.g. marc@ATHENA.MIT.EDU).
version
The current version of zwgc.
zephyr_version
The protocol version of the notice.
All of these variables (except for error, output_driver, and version)
are re-set before each notice is processed.
Functions
Following is a list of functions available for use in the description
file.
buffer()
The contents of the current output buffer.
downcase(expr)
Returns the value of expr, converted to lower case.
get(expr)
Returns a line from the port named expr. If there is no text
waiting on the port (e.g. the program connected to the port has
not printed any output), this function will wait until it can read
a line of text from the port.
getenv(expr)
Returns the value of the environment variable expr, or the empty
string if it does not exist.
lany(expr1, expr2), rany(expr1, expr2)
Return a number of characters equal to the length of expr2 from
the beginning (lany) or end (rany) of expr1 (e.g.
lany("1234567890","foo") would return "123"). If expr1 is a
variable reference, the variable is modified to remove the
characters returned. If expr2 is longer than expr1, the value of
expr1 is returned (and expr1 is set to "", if a variable).
lbreak(expr1, expr2), rbreak(expr1, expr2)
Expr2 defines a set of characters. The function returns the
longest initial (lbreak) or final (rbreak) string from expr1
composed of characters not in this set (e.g. lbreak("characters",
"tuv") would return "charac"). If expr1 is a variable reference,
the variable is modified to remove the characters returned. If no
characters in expr2 are in expr1, then expr1 is returned (and
expr1 is set to "", if a variable).
lspan(expr1, expr2), rspan(expr1, expr2)
These functions are the negation of the break functions; the
returned string consists of characters in the set defined by expr2
protect(expr)
Returns a string which will be evaluated identically to expr, but
will not affect any surrounding environments. That is, any
characters which could close outside environments are quoted, and
any environments in expr which are not closed at the end are
closed.
substitute(expr)
Evaluates variable references of the form $variable in expr and
converts $$ to $.
upcase(expr)
Returns the value of expr, converted to upper case.
verbatim(expr)
Returns a string that will be displayed exactly as expr looks.
Anything which could be mistaken for an environment is quoted.
stylestrip(expr)
Returns expr with all environments stripped out.
zvar(expr)
Returns the value of the zephyr variable expr, or the empty string
if it does not exist. [Zephyr variables can be set and examined
with zctl(1).]
Operators
Following is a list of operators which can be used in the description
file to compose expressions:
expr1 + expr2
String concatenation of expr1 and expr2
expr1 == expr2
True if the two expressions are equal, false otherwise.
expr1 =~ expr2
True if the regular expression pattern expr2 matches expr1.
expr1 !~ expr2
Negation of "=~".
expr1 != expr2
Negation of "=="
expr1 and expr2, expr1 & expr2
True if expr1 and expr2 are both true.
expr1 or expr2, expr1 | expr2
True if either of expr1 or expr2 are true.
! expr1, not expr1
The logical negation of expr1.
Commands
Following is a list of the commands usable in the description language:
appendport expr1 expr2
Creates a port called expr1. All output to the port will be
appended to the file expr2. There is no input. If the file is
created, its mode is set to read-write, owner only (no access for
others).
break
Exits the innermost if, case, or while block.
case expr1 [ ((match expr [,expr ...]) | default) commands ] ...
endcase
Evaluates expr1. Then, each of the match expressions is evaluated
in order. The first time an expression matches expr1, then the
body of commands under it is executed, and the rest of the case
statement is skipped. This compare is case-insensitive. default
always matches, so it should always appear as the last set of
commands. See the default description file for an example of use.
clearbuf
Clears the output buffer (see below for details on buffering).
closeinput expr
Closes the file associated with expr.
closeoutput expr
Sends an EOF (end-of-file) to the process if expr was a port
created by execport, or closes the file if it was created by
outputport or appendport.
closeport expr
Closes both input and output of expr as defined above.
fields variable1 ...
sets the list of variables to be equal to the fields in the
notice. If there are more variables than fields, the extra
variables are left empty.
exec exprlist
Executes a program without any input or output. A command named
by exprlist is executed. Each expression is used as an argument
to the program; the first expression names the program (it may be
either an absolute pathname, or a program name; the user’s PATH is
searched to find simple program names).
execport expr1 exprlist
Creates a port called expr1. A command named by exprlist is
executed, as described above for exec. All output to the port is
sent to the standard input of the process. Reading from the port
will return the standard output of the process.
exit Completes processing of the current notice. The remainder of the
description file is ignored after execution of this command.
if expr1 then commands1 [elseif expr2 then commands2] ... [else
commandsn] endif
If expr1 evaluates to true, execute commands1, etc. [A conditional
construct, similar to the constructs in the C shell (csh).]
inputport expr1 expr2
Creates a port called expr1. All input from the port comes from
the file expr2. There is no output.
noop does nothing
outputport expr1 expr2
Creates a port called expr1. The file expr2 will be truncated, or
created if it does not exist. All output to the port will be
appended to the file expr2. There is no input. If the file is
created, its mode is set to read-write, owner only (no access for
others).
print expr1 ...
adds the values of the expressions to the current output buffer.
The values of the expressions are separated by spaces in the
output.
put [expr [exprlist]]
Sends data to a port. If expr is provided, then it is used as the
port, otherwise the port used is the port corresponding to the
default output device. If exprlist is provided, the expressions
in the list are sent to the port, separated by spaces. If it is
omitted, then the contents of the output buffer are sent as the
data.
set variable = expr
sets variable equal to expr. Variable can later be referenced by
$variable.
show text endshow
Appends text to the output buffer. This command is special,
because the string does not need to be quoted. Whitespace at the
beginning or end of the lines of text is ignored. The endshow
must appear as the first token on a line (it may only be preceded
on that line by whitespace). Variable substitutions and
formatting commands (but not expressions or functions) are
processed in the text. Example:
show
this is some text
from: $sender
endshow
while expr do statements endwhile
Executes statements until expr is false.
PORTS
Ports are an abstraction encompassing all I/O forms of which zwgc is
capable. There are pre-existing output ports corresponding to each of
the output devices, and more ports can be created with the port
commands described above.
OUTPUT
The output is usually collected in the output buffer and saved until a
put command sends the output to an output device (such as an X display
or a terminal). The output buffer is implicitly cleared after each
notice is completely processed.
Output devices are implemented as output ports. A message is displayed
in a device-dependent manner when a string is output to the port
corresponding to the output device. Formatting commands are embedded
in the text as @ commands of the form @command(text). Command names
are case-insensitive and consist of alphanumeric characters and
underscores. Valid brackets are () [] {} and <>. If the command name
is empty (such as in ‘‘@(foo)’’), then a new environment with no
changes is created (This is useful to temporarily change some parameter
of the output, such as the font).
The following output devices are supported:
stdout
Sends the string to standard output exactly as is.
stderr
Sends the string to standard error exactly as is.
plain
Sends the string with all formatting environments removed to
standard output.
tty Does formatting on the message according to @ commands embedded in
the text. The output, with appropriate mode-changing sequences,
is sent to the standard output. The appropriate characteristics
of the display are taken from the TERMCAP entry (see termcap(5))
for the terminal named by the TERM environment variable.
Supported @ commands are:
@roman Roman (plain) letters (turns off all special
modes).
@b or @bold Bold letters. If not available, reverse
video, else underline.
@i or @italic Italic letters (underlining, if available).
@beep "bl" termcap entry, else "^G" (beep the
terminal); limited to once per message.
@l or @left left aligned
@c or @center center aligned
@r or @right right aligned
Other @-commands are silently ignored.
X Displays one window per string output to the port. The output is
formatted according to @ commands embedded in the string.
Supported @ commands are:
@roman turns off @italic and @bold
@b or @bold turns on boldface
@i or @italic turns on italics
@l or @left left aligned
@c or @center center aligned
@r or @right right aligned
@large large type size
@medium medium type size
@small small type size
@beep Ring the X bell (limited to once per message)
@font sets the current font to the font specified in
the contents of the environment (e.g.
@font(fixed)). This will remain in effect for
the rest of the environment (a temporary
change can be achieved by enclosing the font-
change in an @(...) environment). If the
named font is not available, the font
‘‘fixed’’ is used instead.
@color sets the color to the color specified in the
contents of the environment. The color name
should appear in the X color name database.
This color will remain in effect for the rest
of the environment. If the named color is not
available, the default foreground color is
used.
Any other environment name not corresponding to the above
environment names will set the current ‘‘substyle.’’
The attributes of a given block of text are determined by any
active environments, evaluated in the context of the current style
and substyle.
The style is specific to each window. Its name has three dot
(‘‘.’’) separated fields, which are by default the values of the
class, instance, and recipient variables, with all dots changed to
underscores (‘‘_’’) and all letters converted to lowercase. The
style can be altered by setting the style variable. Note that it
must always have exactly two ‘‘.’’ characters in it.
The substyle is determined by @ commands in the message text.
Zwgc variables which the X output device reads are:
default_X_geometry
default geometry for notices, set from
resources
X_geometry overrides geometry in resource file, if set
default_X_background
default background color for notices, set from
resources
X_background overrides bgcolor in resource file, if set
style style, as described above
The expected geometry values are described below.
The fonts and color for a piece of text are determined by the
styles defined in the X resources file. The following resources
relating to text style are used by zwgc:
zwgc.style.stylenames.geometry
geometry for messages of the specified style
zwgc.style.stylenames.background
background color for messages of the specified
style
zwgc.style.stylenames.substyle.substylename.fontfamily
fontfamily name for the specified style and
substyle
zwgc.style.stylenames.substyle.substylename.foreground
foreground color for the specified style and
substyle
zwgc.fontfamily.fontfamilyname.size.face
specifies the fonts for a given fontfamily. size
is one of small, medium, or large, and face is one
of roman, bold, italic, or bolditalic.
The best way to get started in customizing X resources for zwgc is
to examine the default application resources and other users’
resources to understand how they specify the default appearance.
X RESOURCES
Other X resources used by zwgc are listed below. Entries like
zwgc*option: value
Zwgc*option: value
zwgc.option: value
*option: value
.option: value
will work.
An entry labeled with zwgc*option in any of the sources takes
precedence over Zwgc*option, which takes precedence over *option
entries. The following sources are searched in order:
command-line arguments (-xrm)
contents of file named by XENVIRONMENT environment variable
X server resource database (see xrdb(1))
application resources file
Logical values can be ( Yes On True T ) or ( No Off False nil ).
OPTION: MEANING [default]:
cursorCode number of a code from the cursorfont (should be an even
integer, see <X11/cursorfont.h>) to use for the windows.
foreground Primary foreground color
Foreground Secondary foreground color (if foreground not set)
[BlackPixel is the default if neither is set]
background Primary background color
Background Secondary background color (if background not set)
[WhitePixel is the default if neither is set]
borderColor Primary border color
BorderColor Secondary border color (if borderColor not set)
[BlackPixel is the default if neither is set]
pointerColor Primary mouse pointer color [foreground color is the
default if not set]
reverseVideo (logical) Toggles foreground and background (and border,
if it matches foreground or background).
ReverseVideo Secondary toggle, if reverseVideo is not set. [off is
the default if neither is set]
borderWidth Primary border width selector
BorderWidth Secondary border width selector (if borderWidth is not
set) [1 is the default value if neither is set]
internalBorder Primary border between edge and text
InternalBorder Secondary selector (if internalBorder not set) [2 is the
default value if neither is set]
geometry Primary POSITION (not size) geometry specifier. The
geometry should be of the form "{+|-}x{+|-}y",
specifying an (x,y) coordinate for a corner of the
window displaying the notice. The interpretation of
positive and negative location specifications follows
the X conventions. A special location of ‘c’ for either
x or y indicates that the window should be centered
along that axis. Example: a geometry of "+0+c"
specifies the window should be at the top of the screen,
centered horizontally.
Geometry Secondary position specifer. [+0+0 is the default if
neither is set.]
resetSaver (logical) Primary value to force screen to unsave when a
message first appears.
ResetSaver (logical) Secondary value to force screen to unsave.
[default True]
reverseStack (logical) Primary value to specify that zwgc should
attempt to stack WindowGram windows such that the oldest
messages normally show on top. Some X window managers
may silently ignore zwgc’s attempts to restack its
windows. This option can cause some unusual
interactions with other windows if the user manually
restacks either the other windows or the WindowGram
windows.
ReverseStack Secondary value to enable reverse stacking. [default
False]
title (string) Primary window title
Title Secondary window title [defaults to the last pathname
component of the program name, usually "zwgc"]
transient (logical) Primary value which determines if zephyrgram
windows will be created with the WM_TRANSIENT_FOR
property set. If this resource is true, the property
will be set, telling certain windowmanagers to treat
zephyrgram windows specially. For instance, twm will
not put decorations on transient windows, mwm will not
let you iconify them, and uwm ignores the resource
entirely.
Transient Secondary transient determining value [default False]
allDesktops (logical) Primary value which determines if zephyrgram
windows should appear on all desktops, for those window
managers which support multiple desktops (sometimes
referred to as workspaces). When this resource is true
(the default), zwgc sets the _NET_WM_DESKTOP property to
0xFFFFFFFF for each zephyrgram window, indicating that
it should appear on all desktops.
AllDesktops Secondary value determining whether zephyrgram windows
should appear on all desktops.
scrollDelete (logical) If true, scrolling over a zgram will cause it
to be deleted
ScrollDelete Secondary value to enable deletion of a zgram by
scrolling over it [default False]
enableDelete (logical) If true, zwgc creates a WM_PROTOCOLS property
on all zgrams, with WM_DELETE_WINDOW as contents.
EnableDelete Secondary value to enable WM_DELETE_WINDOW protocol on
zgrams [default False]
minTimeToLive Primary value which specifies the minimum amount of time
(‘‘minimum time to live’’) a WindowGram must be on-
screen (in milliseconds) until it can be destroyed.
This feature is useful to avoid accidentally clicking on
new WindowGrams when trying to delete old ones.
MinTimeToLive Secondary value of ‘‘minimum time to live.’’
iconName (string) Primary icon name
IconName Secondary icon name [defaults to the last pathname
component of the program name, usually "zwgc"]
name (string) Primary window class name
name Secondary window class name [defaults to the last
pathname component of the program name, usually "zwgc"]
synchronous (logical) Primary X synchronous mode specifier. On
means to put the X library into synchronous mode.
Synchronous Secondary X synchronous mode specifier. [default is
‘off’]
The window class is always "Zwgc".
X BUTTONS
Clicking and releasing any button without the shift key depressed while
the pointer remains inside a WindowGram window will cause it to
disappear. If the pointer leaves the window while the button is
depressed, the window does not disappear; this provides a way to avoid
accidentally losing messages.
If the control button is held down while clicking on a WindowGram, then
that WindowGram and all windowgrams under the point where the button is
released will be erased.
WARNING: If you do this with too many WindowGrams under the mouse, it
is possible for your subscriptions to be lost. If zctl retrieve
returns nothing, then issue a zctl load command to re-subscribe to your
default set of subscriptions. If you use znol, then znol -q & will
restore the subscriptions you need for znol.
Portions of the text of a message may be selected for "pasting" into
other X applications by using the shift key in cooperation with the
pointer buttons. Holding the Shift key while depressing Button1
(usually the left button) will set a marker at the text under the
pointer. Dragging the pointer with Shift-Button1 still depressed
extends the selection from the start point, until the button is
released. The end of the selection may also be indicated by releasing
Button1, holding down the Shift key, and pressing Button3 (usually the
right button) at the desired endpoint of the selection. The selection
will appear with the text and background colors reversed.
ADDITIONAL X FEATURES
If zwgc receives a WM_DELETE_WINDOW, it destroys the zephyrgram as if
it were clicked on.
If a zephyrgram is unmapped, it is removed from the stacking order used
by reverseStack.
COMMAND LINE
zwgc is normally invoked from /usr/athena/lib/init/login,
$HOME/.xsession, or /usr/athena/lib/init/xsession in the foreground.
When it has successfully set your location and obtained subscriptions,
it will put itself into the background (unless the -nofork option has
been specified). At this point it is safe to invoke additional zephyr
commands, such as znol(1). (You can also put these commands in the
initprogs Zephyr variable; the value of this variable is passed as the
argument to the system(3) library call during initialization.) zwgc
will exit with an exit status of 0 if it was able to open the X display
successfully or 1 if it couldn’t open the display and the Zephyr
variable fallback was set to ‘‘false’’. If fallback is set to ‘‘true’’,
zwgc will fall back to ‘‘ttymode’’ (making the tty driver the default
output device) if it can’t open the X display. If fallback is not set
and the display cannot be opened, zwgc prints an explanatory message
and exits with a status of 1.
If the -ttymode option is specified, zwgc will ignore any X display and
use the terminal as its primary output device. This flag overrides any
setting of the fallback variable.
If the -loc option is specified, zwgc will use the specified string as
the tty field for the location it sets. This allows users to
potentially specify more useful auxiliary information than their ttys
or display names.
The -reenter option is provided for compatibility with the previous
version of zwgc.
zwgc will exit cleanly (unset location and cancel subscriptions) on:
SIGTERM
SIGHUP
XIOError (with a message to stderr)
SIGHUP is what it expects to get upon logout. Also, the signals
SIGINT, SIGQUIT, and SIGTSTP are ignored because they can be sent
inadvertently, and bizarre side-effects can result. If you want them
to be acted on, then run zwgc -nofork &
If zwgc receives a SIGUSR1, it will rewrite the file used to store the
WindowGram port number ($WGFILE or /tmp/wg.uid), in the event that the
file has been lost.
CONTROL MESSAGES
In order to allow some special user controls over the behavior of zwgc,
certain Zephyr control notices can be sent directly to zwgc using the
zctl(1) program. Currently implemented controls are
wg_read tell zwgc to re-read the current description file.
wg_shutdown tell zwgc to cancel all subscriptions and stop acting on
incoming notices. zwgc saves the subscriptions that
were in effect at the time of the shutdown so that it
can restore them later if needed.
wg_startup tell zwgc to restart from being shutdown and reinstall
the saved subscriptions.
Other control messages may be implemented in the future.
EXAMPLES
For an example of a description file, see
/usr/athena/share/zephyr/zwgc.desc. For an example of X resources, see
/usr/athena/share/zephyr/zwgc_resources.
BUGS
The X selection code can highlight the wrong portions of messages
containing formatted text placed with the @center() or @right()
directives.
If you are using Kerberos support and get new tickets (using
‘‘kinit’’), you must send a subscription notice to the server (using a
command such as ‘‘zctl load /dev/null’’) or all received Zephyr notices
will appear to be unauthentic. (If all received Zephyr notices appear
to be forged, your tickets have probably expired, in which case you
must get new tickets and then run ‘‘zctl load /dev/null’’.)
FILES
$HOME/.zwgc.desc
Default location of user’s description file
/usr/athena/share/zephyr/zwgc.desc
System-wide description file
/usr/athena/share/zephyr/zwgc_resources
Default X application resources.
$ZEPHYR_VARS or $HOME/.zephyr.vars
File containing variable definitions
$HOME/.zephyr.subs
Supplementary subscription file
$HOME/.Xresources
Standard X resources file
$WGFILE or /tmp/wg.uid
File used to store WindowGram port number for other
clients
SEE ALSO
csh(1), kinit(1), xrdb(1), zctl(1), zephyr(1), znol(1), X(1),
getenv(3), system(3), termcap(5), zephyrd(8), zhm(8)
Project Athena Technical Plan Section E.4.1, ‘Zephyr Notification
Service’
AUTHORS
John Carr (MIT/Project Athena) <jfc@athena.mit.edu>
Marc Horowitz (MIT/Project Athena) <marc@athena.mit.edu>
Mark Lillibridge (MIT/Project Athena) <mdl@CS.CMU.EDU>
RESTRICTIONS
Copyright (c) 1989 by the Massachusetts Institute of Technology. All
Rights Reserved.
zephyr(1) specifies the terms and conditions for redistribution.