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 −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:

.nr )E 0
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.

.nr )E 0
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.

.nr )E 0
The class of the current notice.

.nr )E 0
The date on which the notice was sent.

.nr )E 0
The default output format for the current notice

.nr )E 0
An error message from the port read/write commands.

.nr )E 0
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). 

.nr )E 0
The notice sender’s name, including the zephyr realm name.

.nr )E 0
The instance of the current notice.

.nr )E 0
The kind of notice.

.nr )E 0
The full text of the message, with nulls converted to newlines.

.nr )E 0
The number of fields in the message (a string representation of a decimal number).

.nr )E 0
The opcode of the current notice.

.nr )E 0
The name of the output driver in use.

.nr )E 0
The port from which the notice was sent.

.nr )E 0
The local zephyr realm.

.nr )E 0
The recipient for the current notice.  If the notice is a multicast (sent to several people), the recipient is set to “∗”.

.nr )E 0
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. 

.nr )E 0
The time of day at which the notice was sent.

.nr )E 0
The full zephyr name of the user (e.g. marc@ATHENA.MIT.EDU).

.nr )E 0
The current version of zwgc.

.nr )E 0
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. 

.nr )E 0
The contents of the current output buffer.

.nr )E 0
Returns the value of expr, converted to lower case. 

.nr )E 0
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. 

.nr )E 0
Returns the value of the environment variable expr, or the empty string if it does not exist. 
 

.nr )E 0
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). 

.nr )E 0
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). 

.nr )E 0
These functions are the negation of the break functions; the returned string consists of characters in the set defined by expr2

.nr )E 0
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. 

.nr )E 0
Evaluates variable references of the form $variable in expr and converts $$ to $. 

.nr )E 0
Returns the value of expr, converted to upper case. 

.nr )E 0
Returns a string that will be displayed exactly as expr looks.  Anything which could be mistaken for an environment is quoted. 

.nr )E 0
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:

.nr )E 0
String concatenation of expr1 and expr2

.nr )E 0
True if the two expressions are equal, false otherwise.

.nr )E 0
True if the regular expression pattern expr2 matches expr1. 

.nr )E 0
Negation of "=~".

.nr )E 0
Negation of "=="

.nr )E 0
True if expr1 and expr2 are both true. 

.nr )E 0
True if either of expr1 or expr2 are true. 

.nr )E 0
The logical negation of expr1. 
 

Commands

Following is a list of the commands usable in the description language:

.nr )E 0
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). 

.nr )E 0
Exits the innermost if, case, or while block.

.nr )E 0
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. 

.nr )E 0
Clears the output buffer (see below for details on buffering).

.nr )E 0
Closes the file associated with expr. 

.nr )E 0
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. 

.nr )E 0
Closes both input and output of expr as defined above. 

.nr )E 0
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.

.nr )E 0
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). 

.nr )E 0
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. 

.nr )E 0
Completes processing of the current notice.  The remainder of the description file is ignored after execution of this command.

.nr )E 0
If expr1 evaluates to true, execute commands1, etc. [A conditional construct, similar to the constructs in the C shell (csh).]

.nr )E 0
Creates a port called expr1.  All input from the port comes from the file expr2.  There is no output. 

.nr )E 0
does nothing

.nr )E 0
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). 

.nr )E 0
adds the values of the expressions to the current output buffer.  The values of the expressions are separated by spaces in the output.

.nr )E 0
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. 

.nr )E 0
sets variable equal to expr. Variable can later be referenced by $variable.

.nr )E 0
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

.nr )E 0
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:

.nr )E 0
Sends the string to standard output exactly as is.

.nr )E 0
Sends the string to standard error exactly as is.

.nr )E 0
Sends the string with all formatting environments removed to standard output.

.nr )E 0
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:

Other @-commands are silently ignored. 

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. 
 

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 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 ). 

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. 
 

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 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. 

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 &
 

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

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 @center() or @right() directives. 
 

FILES

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. 

MIT Project Athena  —  November 30, 1989