zwgc - Zephyr Windowgram Client program
zwgc [ -reenter ] [ -nofork ] [ -ttymode ] [ -f
filename ] [ -subfile filename ] [ -loc text ] [
-default portname ] [ -disable portname ] ... [ output driver
options ] [ X Toolkit options... ]
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.
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.
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.
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 */").
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).
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.
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).]
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.
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 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.
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:
-
- 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:
-
- 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.
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".
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.
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.
zwgc is normally invoked from $HOME/.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.
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.
For an example of a description file, see
/etc/zephyr/zwgc.desc. For an example of X resources, see
/etc/zephyr/zwgc_resources.
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''.)
- $HOME/.zwgc.desc
- Default location of user's description file
- /etc/zephyr/zwgc.desc
- System-wide description file
- /etc/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
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'
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>
Copyright (c) 1989 by the Massachusetts Institute of Technology.
All Rights Reserved.
zephyr(1) specifies the terms and conditions for redistribution.