1 .\" $Id: zwgc.1,v 1.24 2000/08/10 15:10:52 ghudson Exp $
2 ' # end of TP (cf }N below)
3 ' # copied here, since we use @ in some of our tags, and that
4 ' # messes up \w and \h
8 .if !"\\$1"" .nr )I \\$1n
11 .in \\n()Ru+\\n(INu+\\n()Iu
13 .ie !\\n()Iu+\\n()Ru-\w'\\*(]X'u-3p \{\\*(]X
15 .el \\*(]X\h@|\\n()Iu+\\n()Ru@\c
26 ' # tagged paragraph (paragraph with hanging label, but no para spacing)
28 .if !"\\$1"" .nr )I \\$1n
36 .TH ZWGC 1 "November 30, 1989" "MIT Project Athena"
38 zwgc \- Zephyr Windowgram Client program
41 [ \-reenter ] [ \-nofork ] [ \-ttymode ] [ \-f
51 ] ... [ output driver options ]
52 [ X Toolkit options... ]
57 client. It is responsible for receiving selected zephyr notices on
58 behalf of the user, formatting them, and displaying them using
59 one or more of the output devices.
61 .SS "Selection of Zephyr Notices"
64 subscribes to various notice classes and instances on behalf of the
65 user. Only notices in the subscription list will be received. The
66 subscription list is composed of the default subscriptions (stored on
67 the server), the user's subscriptions file, and any subscriptions made
70 The user's subscription file defaults to
71 .IR $HOME/.zephyr.subs ,
72 or it can be specified with the \-subfile
73 option. If "\-" is specified as the subscription filename, the
74 subscriptions will be read from standard input.
79 command is used to manipulate and change subscriptions. See the
83 .SS "Zephyr Description Files"
86 formats its output messages according to the commands in its
87 description file. The user's description file
88 .RI ( $HOME/.zwgc.desc
89 by default, or whatever is specified by -f) is read, or the system file
90 is read if the user's does not exist.
92 Every time a notice is received,
94 runs through the description file, and executes the appropriate commands.
96 .SS "Zephyr Description File Syntax"
98 A description file is simply a list of commands. Whitespace (spaces,
99 tabs, and line breaks) is used
100 to separate tokens. The type and amount of whitespace separating tokens
102 Comments can be delimited by # and newline (for line-oriented comments,
103 e.g. "# this is a comment" on a line by itself) or by /* and */ (e.g. "/*
104 this is a comment */").
106 .SH "DESCRIPTION LANGUAGE"
108 Expressions are used by certain commands.
109 They are composed from string literals, variable references,
110 function calls, and operators. Parentheses can be used anywhere in an
111 expression to group expressions or increase readability.
113 String literals are specified by putting the contents in "double quotes".
115 Variables are set using the
117 command (see "COMMANDS", below). They are
118 referenced in an expression by using the form
120 Some variables are set by default for each notice.
121 All other variables retain their values between notice interpretations,
122 so that if you set a variable, it retains that value until later
125 Functions are called using a C-like syntax,
126 \fBfname\fR(\fIexpr1\fR,\fIexpr2\fR), where
133 Binary operators use infix notation, such as "a == b".
135 Some commands use an expression list (exprlist), which is simply a set
136 of expressions separated by whitespace (e.g. $var1 "lit1" $var2).
138 .SS "Default variables"
140 The following variables are always available:
143 Numeric variables are assigned values corresponding to that field in the
144 notice (the body of each notice is conceptually an array of fields, each
145 terminated with a null character). If the number is greater than the
146 number of fields actually in the notice, the value is "". For example,
147 the standard zwrite messages have two fields: $1 is the signature, and
148 $2 is the text of the message.
151 An indication of the authenticity of the notice. ``yes'' means the
152 notice is authentic, ``no'' means it is not, and ``forged'' means that
153 the message claimed to be authentic but the verification of the claim
154 failed. The ``forged'' indication usually appears when a user has
155 changed his Kerberos tickets with
157 but has not run ``zctl sub'' to
158 register this change with the Zephyr servers.
161 The class of the current notice.
164 The date on which the notice was sent.
167 The default output format for the current notice
170 An error message from the port read/write commands.
173 The full name of the host from which the notice appears to have been
175 .I This is not fully reliable,
176 as the information used to determine this hostname is not guaranteed to
177 be correct (even for authentic messages).
180 The notice sender's name, including the zephyr realm name.
183 The instance of the current notice.
189 The full text of the message, with nulls converted to newlines.
192 The number of fields in the message (a string representation of a
196 The opcode of the current notice.
199 The name of the output driver in use.
202 The port from which the notice was sent.
205 The local zephyr realm.
208 The recipient for the current notice. If the notice is a multicast
209 (sent to several people), the recipient is set to ``*''.
212 Usually a shortened version of fullsender. If the realm of the sender
213 is equal to the realm of the recipient,
215 omits the realm name.
218 The time of day at which the notice was sent.
221 The full zephyr name of the user (e.g. marc@ATHENA.MIT.EDU).
224 The current version of
228 The protocol version of the notice.
230 All of these variables (except for error, output_driver, and version)
231 are re-set before each notice is processed.
235 Following is a list of functions available for use in the description
239 The contents of the current output buffer.
242 Returns the value of \fIexpr\fR, converted to lower case.
245 Returns a line from the port named \fIexpr\fR. If there is no text
246 waiting on the port (e.g. the program connected to the port has not
247 printed any output), this function will wait until it can read a line of
251 Returns the value of the environment variable \fIexpr\fR, or the empty
252 string if it does not exist.
255 .BI lany "(expr1, expr2), " rany "(expr1, expr2)"
256 Return a number of characters equal to the length of
264 (e.g. lany("1234567890","foo") would return "123").
267 is a variable reference, the variable
268 is modified to remove the characters returned.
277 is set to "", if a variable).
279 .BI lbreak "(expr1, expr2), " rbreak "(expr1, expr2)"
281 defines a set of characters. The function returns the longest
288 composed of characters
290 in this set (e.g. lbreak("characters", "tuv") would return "charac"). If
292 is a variable reference, the variable
293 is modified to remove the characters returned. If no characters
295 .IR expr2 " are in " "expr1, " then " expr1 "
298 is set to "", if a variable).
300 .BI lspan "(expr1, expr2), " rspan "(expr1, expr2)"
301 These functions are the negation of the
303 functions; the returned string consists of characters
309 Returns a string which will be evaluated identically to \fIexpr\fR,
310 but will not affect any surrounding environments. That is, any
311 characters which could close outside environments are quoted, and any
312 environments in \fIexpr\fR which are not closed at the end are closed.
314 .BI substitute (expr)
315 Evaluates variable references of the form \fI$variable\fR in expr and
319 Returns the value of \fIexpr\fR, converted to upper case.
322 Returns a string that will be displayed exactly as \fIexpr\fR looks.
323 Anything which could be mistaken for an environment is quoted.
325 .BI stylestrip (expr)
326 Returns \fIexpr\fR with all environments stripped out.
329 Returns the value of the zephyr variable \fIexpr\fR,
331 string if it does not exist. [Zephyr variables
332 can be set and examined with
337 Following is a list of operators which can be used in the description
338 file to compose expressions:
340 .IB expr1 " + " expr2
341 String concatenation of
342 .IR expr1 " and " expr2
344 .IB expr1 " == " expr2
345 True if the two expressions are equal, false otherwise.
347 .IB expr1 " =~ " expr2
348 True if the regular expression pattern
349 .IR expr2 " matches " expr1.
351 .IB expr1 " !~ " expr2
354 .IB expr1 " != " expr2
357 \fIexpr1\fB and \fIexpr2\fR, \fIexpr1\fB & \fIexpr2\fR
359 .IR expr1 " and " expr2
362 \fIexpr1\fB or \fIexpr2\fR, \fIexpr1\fB | \fIexpr2\fR
364 .IR expr1 " or " expr2
367 \fB! \fIexpr1\fR, \fBnot \fIexpr1\fR
368 The logical negation of
373 Following is a list of the commands usable in the description
376 .BI appendport " expr1 expr2"
377 Creates a port called \fIexpr1\fR. All output to the port will be
378 appended to the file \fIexpr2\fR. There is no input. If the file is
379 created, its mode is set to read-write, owner only (no access for others).
382 Exits the innermost if, case, or while block.
385 \fBcase \fIexpr1\fR [ ((\fBmatch \fIexpr\fR [,\fIexpr ...\fR]) | \fBdefault\fR)\fI commands \fR] ... \fBendcase\fR
386 Evaluates \fIexpr1\fR. Then, each of the match expressions is
387 evaluated in order. The first time an expression matches \fIexpr1\fR,
388 then the body of commands under it is executed, and the rest of the case
389 statement is skipped. This compare is case-insensitive. default always
390 matches, so it should always appear as the last set of commands. See
391 the default description file for an example of use.
394 Clears the output buffer (see below for details on buffering).
396 .BI closeinput " expr"
397 Closes the file associated with \fIexpr\fR.
399 .BI closeoutput " expr"
400 Sends an EOF (end-of-file) to the process if \fIexpr\fR was a port created by
401 execport, or closes the file if it was created by outputport or
404 .BI closeport " expr"
405 Closes both input and output of \fIexpr\fR as defined above.
407 .BI fields " variable1 ..."
408 sets the list of variables to be equal to the fields in the
409 notice. If there are more variables than fields, the extra
410 variables are left empty.
413 Executes a program without any input or output. A command named by
414 \fIexprlist\fR is executed. Each expression is used as an argument to
415 the program; the first expression names the program (it may be either an
416 absolute pathname, or a program name; the user's PATH is searched to
417 find simple program names).
419 .BI execport " expr1 exprlist"
420 Creates a port called \fIexpr1\fR. A command named by \fIexprlist\fR
421 is executed, as described above for \fBexec\fR.
422 All output to the port is sent to the standard input
423 of the process. Reading from the port will return the standard output
427 Completes processing of the current notice. The remainder of the
428 description file is ignored after execution of this command.
429 .\" hack because the following line otherwise breaks because it is too long.
432 \fBif \fIexpr1 \fBthen \fIcommands1\fR [\fBelseif \fIexpr2 \fBthen \fIcommands2\fR] ... [\fBelse \fIcommandsn\fR] \fBendif\fR
433 If \fIexpr1\fR evaluates to true, execute \fIcommands1\fI, etc. [A conditional
434 construct, similar to the constructs in the C shell (csh).]
436 .BI inputport " expr1 expr2"
437 Creates a port called \fIexpr1\fR. All input from the port comes from
438 the file \fIexpr2\fR. There is no output.
443 .BI outputport " expr1 expr2"
444 Creates a port called \fIexpr1\fR. The file \fIexpr2\fR will be
445 truncated, or created if it does not exist. All output to the port
446 will be appended to the file \fIexpr2\fR. There is no input. If the file is
447 created, its mode is set to read-write, owner only (no access for others).
449 .BI print " expr1 ..."
450 adds the values of the expressions to the current output buffer. The
451 values of the expressions are separated by spaces in the output.
453 .B put \fR[\fIexpr \fR[\fIexprlist\fR]]
454 Sends data to a port. If \fIexpr\fR is provided, then it is used as the
455 port, otherwise the port used is the
456 port corresponding to the default output device.
457 If \fIexprlist\fR is provided, the expressions in the list are sent to
458 the port, separated by spaces. If it is omitted, then the contents
459 of the output buffer are sent as the data.
461 .BI set " variable " = " expr"
466 Variable can later be
470 .BI show " text " endshow
471 Appends text to the output buffer. This command is special, because
472 the string does not need to be quoted. Whitespace at the beginning or
473 end of the lines of text is ignored. The \fIendshow\fR must appear as
474 the first token on a line (it may only be preceded on that line by whitespace).
475 Variable substitutions and formatting commands
476 (but not expressions or functions) are processed in the text. Example:
484 .BI while " expr " do " statements " endwhile
485 Executes \fIstatements\fR until \fIexpr\fR is false.
489 Ports are an abstraction encompassing all I/O forms of which
490 zwgc is capable. There are pre-existing output ports corresponding to each
491 of the output devices, and more ports can be created with the
492 port commands described above.
495 The output is usually collected in the
499 command sends the output to an output device (such as an X display or a
500 terminal). The output buffer is implicitly cleared after each notice is
501 completely processed.
504 Output devices are implemented as output ports. A message is
505 displayed in a device-dependent manner when a string is output to the
506 port corresponding to the output device. Formatting commands are
507 embedded in the text as @ commands of the form @command(text).
508 Command names are case-insensitive and consist of alphanumeric
509 characters and underscores. Valid brackets are () [] {} and <>.
510 If the command name is empty (such as in
513 environment with no changes is created (This is useful to temporarily
514 change some parameter of the output, such as the font).
516 The following output devices are supported:
519 Sends the string to standard output exactly as is.
522 Sends the string to standard error exactly as is.
525 Sends the string with all formatting environments removed to standard
529 Does formatting on the message according to @ commands embedded in the
531 with appropriate mode-changing sequences, is sent to the standard output.
532 The appropriate characteristics of the display are taken from
533 the TERMCAP entry (see
535 for the terminal named by the TERM environment variable.
536 Supported @ commands are:
540 .\" Emphasis. Use underline if available, else reverse video.
543 Roman (plain) letters (turns off all special modes).
546 Bold letters. If not available, reverse video, else underline.
549 Italic letters (underlining, if available).
552 "bl" termcap entry, else "^G" (beep the terminal); limited to once per
556 .\" "mb"/"me" termcap entry, else nothing.
559 .\" "so"/"se" termcap entry.
562 .\" "us"/"ue" termcap entry.
574 Other @-commands are silently ignored.
577 Displays one window per string output to the port. The output is
578 formatted according to @ commands embedded in the string. Supported
583 turns off @italic and @bold
610 Ring the X bell (limited to once per message)
613 sets the current font to the font specified in the contents of the
614 environment (e.g. @font(fixed)). This will remain in effect for the
615 rest of the environment (a temporary change can be achieved by enclosing the
616 font-change in an @(...) environment). If the named font is not
617 available, the font ``fixed'' is used instead.
620 sets the color to the color specified in the contents of the
621 environment. The color name should appear in the X color name database.
622 This color will remain in effect for the rest of the environment. If
623 the named color is not available, the default foreground color is used.
626 Any other environment name not corresponding to the above environment
627 names will set the current ``substyle.''
629 The attributes of a given block of text are determined by any active
630 environments, evaluated in the context of the current style and
633 The style is specific to each window. Its name has three dot
634 (``.'') separated fields, which are by default the values of the class,
635 instance, and recipient variables, with all dots changed to underscores
636 (``_'') and all letters converted to lowercase. The style can be
637 altered by setting the
639 variable. Note that it \fBmust always\fR have exactly two ``.''
642 The substyle is determined by @ commands in the message text.
644 Zwgc variables which the X output device reads are:
648 default geometry for notices, set from resources
651 overrides geometry in resource file, if set
654 default background color for notices, set from resources
657 overrides bgcolor in resource file, if set
660 style, as described above
663 The expected geometry values are described below.
665 The fonts and color for a piece of text are determined by the styles
666 defined in the X resources file. The following resources relating to
667 text style are used by zwgc:
670 zwgc.style.\fIstylenames\fR.geometry
671 geometry for messages of the specified style
673 zwgc.style.\fIstylenames\fR.background
674 background color for messages of the specified style
676 zwgc.style.\fIstylenames\fR.substyle.\fIsubstylename\fR.fontfamily
677 fontfamily name for the specified style and substyle
679 zwgc.style.\fIstylenames\fR.substyle.\fIsubstylename\fR.foreground
680 foreground color for the specified style and substyle
682 zwgc.fontfamily.\fIfontfamilyname\fR.\fIsize\fR.\fIface\fR
683 specifies the fonts for a given fontfamily. \fIsize\fR is one
684 of small, medium, or large, and \fIface\fR is one of roman,
685 bold, italic, or bolditalic.
688 The best way to get started in customizing X resources for
690 is to examine the default application resources and other users'
691 resources to understand how they specify the default appearance.
694 Other X resources used by
711 An entry labeled with zwgc*option in any of the sources takes precedence
712 over Zwgc*option, which takes precedence over *option entries.
713 The following sources are searched in order:
716 command-line arguments (-xrm)
717 contents of file named by XENVIRONMENT environment variable
718 X server resource database (see \fIxrdb\fR(1))
719 application resources file
723 Logical values can be ( Yes On True T ) or ( No Off False nil ).
726 \fBMEANING [default]:\fR
729 number of a code from the cursorfont (should be an even integer, see
730 \fI<X11/cursorfont.h>\fR) to use for the windows.
733 Primary foreground color
736 Secondary foreground color (if foreground not set) [BlackPixel is the default if neither is set]
739 Primary background color
742 Secondary background color (if background not set) [WhitePixel is the
743 default if neither is set]
749 Secondary border color (if borderColor not set) [BlackPixel is the
750 default if neither is set]
753 Primary mouse pointer color [foreground color is the default if not set]
756 (logical) Toggles foreground and background (and border, if it matches
757 foreground or background).
760 Secondary toggle, if reverseVideo is not set. [off is the default if
764 Primary border width selector
767 Secondary border width selector (if borderWidth is not set) [1 is the
768 default value if neither is set]
771 Primary border between edge and text
774 Secondary selector (if internalBorder not set) [2 is the default value
778 Primary POSITION (not size) geometry specifier.
779 The geometry should be of the form "{+|\-}x{+|\-}y", specifying an (x,y)
780 coordinate for a corner of the window displaying the notice. The
781 interpretation of positive and negative location specifications follows
782 the X conventions. A special location of `c' for either x or y
783 indicates that the window should be centered along that axis. Example:
784 a geometry of "+0+c" specifies the window should be at the top of the
785 screen, centered horizontally.
788 Secondary position specifer. [+0+0 is the default if neither is set.]
791 (logical) Primary value to force screen to unsave when a message first
795 (logical) Secondary value to force screen to unsave. [default True]
798 (logical) Primary value to specify that zwgc should attempt to stack
799 WindowGram windows such that the oldest messages
800 normally show on top. Some X window managers may silently ignore
802 attempts to restack its windows. This option can cause some unusual
803 interactions with other windows if the user manually restacks either the
804 other windows or the WindowGram windows.
807 Secondary value to enable reverse stacking. [default False]
810 (string) Primary window title
813 Secondary window title [defaults to the last pathname component
814 of the program name, usually "zwgc"]
817 (logical) Primary value which determines if zephyrgram windows will be
818 created with the \fBWM_TRANSIENT_FOR\fR property set. If this
819 resource is true, the property will be set, telling certain
820 windowmanagers to treat zephyrgram windows specially. For instance,
821 \fItwm\fR will not put decorations on transient windows, \fImwm\fR
822 will not let you iconify them, and \fIuwm\fR ignores the resource
826 Secondary transient determining value [default False]
829 (logical) If true, zwgc creates a WM_PROTOCOLS property on all zgrams, with
830 WM_DELETE_WINDOW as contents.
833 Secondary value to enable WM_DELETE_WINDOW protocol on zgrams [default False]
836 Primary value which specifies the minimum amount of time (``minimum time to
837 live'') a WindowGram must be on-screen (in milliseconds) until it can
838 be destroyed. This feature is useful to avoid accidentally clicking
839 on new WindowGrams when trying to delete old ones.
842 Secondary value of ``minimum time to live.''
845 (string) Primary icon name
848 Secondary icon name [defaults to the last pathname component
849 of the program name, usually "zwgc"]
852 (string) Primary window class name
855 Secondary window class name [defaults to the last pathname component
856 of the program name, usually "zwgc"]
859 (logical) Primary X synchronous mode specifier. On means to put the X
860 library into synchronous mode.
863 Secondary X synchronous mode specifier. [default is `off']
865 The window class is always "Zwgc".
868 Clicking and releasing any button without the shift key depressed while
869 the pointer remains inside a WindowGram window will cause it to
870 disappear. If the pointer leaves the window
871 while the button is depressed, the window does not disappear; this
872 provides a way to avoid accidentally losing messages.
874 If the control button is held down while clicking on a WindowGram,
875 then that WindowGram and all windowgrams under the point where the
876 button is released will be erased.
879 If you do this with too many WindowGrams under the mouse, it is
880 possible for your subscriptions to be lost. If \fIzctl retrieve\fR
881 returns nothing, then issue a \fIzctl load\fR command to re-subscribe
882 to your default set of subscriptions. If you use znol, then \fIznol
883 -q &\fR will restore the subscriptions you need for \fIznol\fR.
885 Portions of the text of a message may be selected for "pasting" into other X
886 applications by using the shift key in cooperation with the pointer
888 Holding the Shift key while depressing Button1 (usually the left button)
889 will set a marker at the
890 text under the pointer. Dragging the pointer with Shift-Button1 still
891 depressed extends the selection from the start point, until the button
892 is released. The end of the selection may also be
893 indicated by releasing Button1, holding down the Shift key, and pressing
894 Button3 (usually the right button) at the desired endpoint of the selection.
895 The selection will appear with the text and background colors reversed.
897 .SH ADDITIONAL X FEATURES
900 receives a WM_DELETE_WINDOW, it destroys the zephyrgram as if it were
903 If a zephyrgram is unmapped, it is removed from the stacking order
904 used by reverseStack.
908 is normally invoked from
909 .IR /usr/athena/lib/init/login ,
910 .IR $HOME/.xsession ,
912 .I /usr/athena/lib/init/xsession
913 in the foreground. When it has successfully set your location and
914 obtained subscriptions, it will put itself into the background (unless
915 the \-nofork option has been specified). At this point it is safe to
916 invoke additional zephyr commands, such as
918 (You can also put these commands in the
920 Zephyr variable; the value of this variable is passed as the argument to
923 library call during initialization.)
925 will exit with an exit
926 status of 0 if it was able to open the X display successfully or 1 if it
927 couldn't open the display and the Zephyr variable
929 was set to ``false''. If
933 will fall back to ``ttymode'' (making the tty driver the default output
934 device) if it can't open the X display. If
936 is not set and the display cannot be opened,
938 prints an explanatory message and exits with a status of 1.
944 will ignore any X display and use the terminal as its primary output
945 device. This flag overrides any setting of the fallback variable.
951 will use the specified string as the tty field for the location it
952 sets. This allows users to potentially specify more useful auxiliary
953 information than their ttys or display names.
957 option is provided for compatibility with the previous version of
961 will exit cleanly (unset location and cancel subscriptions) on:
965 XIOError (with a message to stderr)
967 SIGHUP is what it expects to get upon logout. Also, the signals
968 SIGINT, SIGQUIT, and SIGTSTP are ignored because they can be sent
969 inadvertently, and bizarre side-effects can result. If you want them
970 to be acted on, then run
974 In order to allow some special user controls over the behavior of
976 certain Zephyr control notices can be sent directly to
980 program. Currently implemented controls are
985 to re-read the current description file.
990 to cancel all subscriptions and stop acting on incoming notices.
992 saves the subscriptions that were in effect at the time of the shutdown
993 so that it can restore them later if needed.
998 to restart from being shutdown and reinstall the saved subscriptions.
1000 Other control messages may be implemented in the future.
1003 For an example of a description file, see
1004 .IR /usr/athena/share/zephyr/zwgc.desc .
1005 For an example of X resources, see
1006 .IR /usr/athena/share/zephyr/zwgc_resources .
1009 The X selection code can highlight the wrong portions of messages
1010 containing formatted text placed with the @center() or @right()
1013 If you are using Kerberos support and get new tickets (using
1014 ``kinit''), you must send a subscription notice to the server (using a
1015 command such as ``zctl load /dev/null'') or all received Zephyr
1016 notices will appear to be unauthentic. (If all received Zephyr
1017 notices appear to be forged, your tickets have probably expired, in
1018 which case you must get new tickets and then run ``zctl load
1023 Default location of user's description file
1025 /usr/athena/share/zephyr/zwgc.desc
1026 System-wide description file
1028 /usr/athena/share/zephyr/zwgc_resources
1029 Default X application resources.
1032 File containing variable definitions
1035 Supplementary subscription file
1038 Standard X resources file
1040 $WGFILE or /tmp/wg.\fIuid\fR
1041 File used to store WindowGram port number for other clients
1043 csh(1), kinit(1), xrdb(1), zctl(1), zephyr(1), znol(1), X(1), getenv(3),
1044 system(3), termcap(5), zephyrd(8), zhm(8)
1046 Project Athena Technical Plan Section E.4.1, `Zephyr Notification Service'
1049 John Carr (MIT/Project Athena) <jfc@athena.mit.edu>
1050 Marc Horowitz (MIT/Project Athena) <marc@athena.mit.edu>
1051 Mark Lillibridge (MIT/Project Athena) <mdl@CS.CMU.EDU>
1054 Copyright (c) 1989 by the Massachusetts Institute of Technology.
1055 All Rights Reserved.
1058 specifies the terms and conditions for redistribution.
projects / 1ts-debian.git / blob