ZWGC(1) ZWGC(1)
NAME
zwgc - Zephyr Windowgram Client program
SYNOPSIS
zwgc [ -reenter ] [ -nofork ] [ -ttymode ] [ -f filename ]
[ -subfile filename ] [ -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 -sub-
file 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 sub-
scriptions. 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. Whites-
pace (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 */").
ZWGC(1) ZWGC(1)
DESCRIPTION LANGUAGE
Expressions
Expressions are used by certain commands. They are com-
posed from string literals, variable references, function
calls, and operators. Parentheses can be used anywhere in
an expression to group expressions or increase readabil-
ity.
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 mes-
sages 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 regis-
ter this change with the Zephyr servers.
class
The class of the current notice.
ZWGC(1) ZWGC(1)
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 reli-
able, as the information used to determine this host-
name 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 repre-
sentation 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 recipi-
ent 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.
ZWGC(1) ZWGC(1)
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 con-
nected 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 vari-
able 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
ZWGC(1) ZWGC(1)
lspan(expr1, expr2), rspan(expr1, expr2)
These functions are the negation of the break func-
tions; 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 environ-
ments. 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 other-
wise.
expr1 =~ expr2
True if the regular expression pattern expr2
matches expr1.
expr1 !~ expr2
Negation of "=~".
expr1 != expr2
Negation of "=="
ZWGC(1) ZWGC(1)
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 descrip-
tion 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 com-
mands 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 append-
port.
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 pro-
gram; the first expression names the program (it may be either an abso-
ZWGC(1) ZWGC(1)
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 expres-
sions 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 end-
show 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 func-
tions) 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.
ZWGC(1) ZWGC(1)
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 out-
put 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 man-
ner 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-insen-
sitive 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 ter-
minal named by the TERM environment variable. Supported @ commands are:
@roman Roman (plain) letters (turns off all spe-
cial 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
ZWGC(1) ZWGC(1)
@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 mes-
sage)
@font sets the current font to the font speci-
fied 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 ``sub-
style.''
The attributes of a given block of text are deter-
mined 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 recip-
ient 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 mes-
sage 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
ZWGC(1) ZWGC(1)
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 deter-
mined 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.substyle-
name.fontfamily
fontfamily name for the specified
style and substyle
zwgc.style.stylenames.substyle.substyle-
name.foreground
foreground color for the specified
style and substyle
zwgc.fontfamily.fontfamilyname.size.face
specifies the fonts for a given font-
family. 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 applica-
tion resources and other users' resources to under-
stand 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
will work.
An entry labeled with zwgc*option in any of the sources
takes precedence over Zwgc*option, which takes precedence
ZWGC(1) ZWGC(1)
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/cur-
sorfont.h>) to use for the windows.
foreground Primary foreground color
Foreground Secondary foreground color (if foreground
not set) [BlackPixel is the default if nei-
ther is set]
background Primary background color
Background Secondary background color (if background
not set) [WhitePixel is the default if nei-
ther 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 border-
Width 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
ZWGC(1) ZWGC(1)
geometry Primary POSITION (not size) geometry speci-
fier. The geometry should be of the form
"{+|-}x{+|-}y", specifying an (x,y) coordi-
nate for a corner of the window displaying
the notice. The interpretation of positive
and negative location specifications fol-
lows 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 nor-
mally 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 win-
dows if the user manually restacks either
the other windows or the WindowGram win-
dows.
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.
ZWGC(1) ZWGC(1)
[default False]
enableDelete (logical) If true, zwgc creates a WM_PROTO-
COLS 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 millisec-
onds) until it can be destroyed. This fea-
ture is useful to avoid accidentally click-
ing 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 speci-
fier. 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.
ZWGC(1) ZWGC(1)
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 sub-
scriptions. 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 but-
ton) 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 but-
ton 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 stack-
ing 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 and with no arguments. When it has successfully
set your location, 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 dur-
ing 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.
ZWGC(1) ZWGC(1)
previous version of zwgc.
zwgc will exit cleanly (unset location and cancel sub-
scriptions) 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 &
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 descrip-
tion 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/lib/zephyr/zwgc.desc. For an example of X
resources, see /usr/athena/lib/zephyr/zwgc_resources.
BUGS
The X selection code can highlight the wrong portions of
messages containing formatted text placed with the @cen-
ter() 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
ZWGC(1) ZWGC(1)
FILES
$HOME/.zwgc.desc
Default location of user's description file
/usr/athena/lib/zephyr/zwgc.desc
System-wide description file
/usr/athena/lib/zephyr/zwgc_resources
Default X application resources.
$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 Noti-
fication 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 Tech-
nology. All Rights Reserved.
zephyr(1) specifies the terms and conditions for redistri-
bution.
Man(1) output converted with
man2html