From 76cd4baec8f5c266c8047cc88981f84701e1fc7a Mon Sep 17 00:00:00 2001 From: Jeffrey Hutzelman Date: Thu, 21 Feb 2013 19:25:18 -0500 Subject: Substitute paths into man pages Generate the man pages for zwgc, zctl, zhm, and zephyrd at build time, so they can refer to the paths actually used instead of whatever was used on Athena in the 1980's. --- clients/zctl/Makefile.in | 13 +- clients/zctl/zctl.1 | 311 -------------- clients/zctl/zctl.1.in | 311 ++++++++++++++ configure.ac | 3 +- server/Makefile.in | 13 +- server/zephyrd.8 | 126 ------ server/zephyrd.8.in | 129 ++++++ zhm/Makefile.in | 13 +- zhm/zhm.8 | 106 ----- zhm/zhm.8.in | 106 +++++ zwgc/Makefile.in | 13 +- zwgc/zwgc.1 | 1070 ---------------------------------------------- zwgc/zwgc.1.in | 1067 +++++++++++++++++++++++++++++++++++++++++++++ 13 files changed, 1663 insertions(+), 1618 deletions(-) delete mode 100644 clients/zctl/zctl.1 create mode 100644 clients/zctl/zctl.1.in delete mode 100644 server/zephyrd.8 create mode 100644 server/zephyrd.8.in delete mode 100644 zhm/zhm.8 create mode 100644 zhm/zhm.8.in delete mode 100644 zwgc/zwgc.1 create mode 100644 zwgc/zwgc.1.in diff --git a/clients/zctl/Makefile.in b/clients/zctl/Makefile.in index 105fe10..fa8d4ae 100644 --- a/clients/zctl/Makefile.in +++ b/clients/zctl/Makefile.in @@ -22,6 +22,12 @@ LIBTOOL=@LIBTOOL@ CC=@CC@ INSTALL=@INSTALL@ +editman = sed \ + -e 's|@datadir[@]|${datadir}|g' \ + -e 's|@sysconfdir[@]|${sysconfdir}|g' \ + -e 's|@sbindir[@]|${sbindir}|g' \ + -e 's|@lsbindir[@]|${lsbindir}|g' + LIBZEPHYR=${BUILDTOP}/lib/libzephyr.la CPPFLAGS=@CPPFLAGS@ CFLAGS=@CFLAGS@ @@ -32,7 +38,7 @@ LIBS=${LIBZEPHYR} @SS_LIBS@ @LIBS@ -lcom_err SS_OBJS=zctl_cmds.o OBJS= zctl.o @SS_OBJS@ -all: zctl +all: zctl zctl.1 zctl: ${OBJS} ${LIBZEPHYR} ${LIBTOOL} --mode=link ${CC} ${LDFLAGS} -o $@ ${OBJS} ${LIBS} @@ -43,6 +49,10 @@ zctl_cmds.c: zctl_cmds.ct .c.o: ${CC} -c ${ALL_CFLAGS} $< +zctl.1: ${srcdir}/zctl.1.in Makefile + ${editman} ${srcdir}/$@.in > $@.tmp + mv $@.tmp $@ + check: install: zctl @@ -52,6 +62,7 @@ install: zctl clean: ${LIBTOOL} --mode=clean rm -f zctl rm -f ${OBJS} zctl_cmds.c + rm -f zctl.1 ${OBJS}: ${top_srcdir}/h/sysdep.h ${BUILDTOP}/h/config.h ${OBJS}: ${BUILDTOP}/h/zephyr/zephyr.h ${BUILDTOP}/h/zephyr/zephyr_err.h diff --git a/clients/zctl/zctl.1 b/clients/zctl/zctl.1 deleted file mode 100644 index c94bbf9..0000000 --- a/clients/zctl/zctl.1 +++ /dev/null @@ -1,311 +0,0 @@ -.\" $Id$ -.\" -.\" Copyright 1987,1988 by the Massachusetts Institute of Technology -.\" All rights reserved. The file /usr/include/zephyr/mit-copyright.h -.\" specifies the terms and conditions for redistribution. -.\" -.\" -.TH ZCTL 1 "July 1, 1988" "MIT Project Athena" -.ds ]W MIT Project Athena -.SH NAME -zctl \- zephyr control program -.SH SYNOPSIS -.B zctl -[ -.I options -] -.SH DESCRIPTION -.I Zctl -is a general purpose control program for the -.I Zephyr(1) -Notification Service. It allows the user to subscribe to specific -notice types, to save the subscriptions in a file (default -$HOME/.zephyr.subs), to change his location information, and to send -control messages to the HostManager, -.I zhm(8), -and the WindowGram client, -.I zwgc(1). -.PP -The commands may be typed on the command line, or may be entered -interactively by just typing -.I zctl -and then typing commands to the prompt. -.br -.B NOTE: -For all commands accepting an optional \fIrecipient\fR argument, the -\fIrecipient\fR defaults to your Kerberos principal. You may also -subscribe to recipient ``\fI*\fR''. If you specify a recipient, it is -silently converted to ``\fI*\fR''. -.br -The commands are as follows: -.TP 15 -.B add \fIclass instance\fR [ \fIrecipient\fR ] -Subscribe to \fIclass, instance, recipient\fR, and add this triplet to -the subscriptions file. -.TP -.B add_unsubscription \fIclass instance\fR [ \fIrecipient\fR ] -Unsubscribe to \fIclass, instance, recipient\fR, and add this triplet -to the subscriptions file as an un-subscription. -For an explanation of un-subscriptions, see below. -.TP -.B cancel -Cancel all subscriptions. -.TP -.B defaults -Retrieve the default subscription list from the Zephyr server. -.TP -.B delete \fIclass instance\fR [ \fIrecipient\fR ] -Unsubscribe to \fIclass, instance, recipient\fR, and remove this triplet -from the subscriptions file. -.TP -.B delete_unsubscription \fIclass instance\fR [ \fIrecipient\fR ] -Unsubscribe to \fIclass, instance, recipient\fR, and remove this triplet -from the subscriptions file as an un-subscription. -.TP -.B file \fR[ \fIfile\fR ] -Set default subscriptions file to \fIfile\fR. If \fIfile\fR isn't specified, -show what the current subscriptions file is. -.TP -.B flush_locs -Tell the Zephyr servers to flush all location information associated with -the user. This should only be used to remove any incorrect data that may have -been left after a system crash. -.TP -.B hide -Hide your location as maintained by the Zephyr server. This does not -affect the value of the exposure variable (see below, under -.B set). -.TP -.B hm_flush -Tell the HostManager, -.I zhm(8), -to ask the server to flush all state associated with the current host. -.TP -.B list \fR[ \fIfile\fR ] -List contents of current subscriptions file or -.I file. -Any macros in the file (see below) are displayed verbatim and not expanded. -.TP -.B list_requests -List all available commands. May be abbreviated by '?'. -.TP -.B load \fR[ \fIfile\fR ] -Subscribe to all subscription triplets and unsubscribe to all -un-subscription triplets in current subscriptions file or \fIfile\fR. -.TP -.B new_server -Tell the HostManager, -.I zhm(8), -to find a new Zephyr server. -.TP -.B quit -Exit from \fIzctl. -.TP -.B retrieve -Retrieve all current subscriptions from the Zephyr server. These include -subscriptions that might have been made by other programs, such as -.I znol(1). -.TP -.B save \fR[ \fIfile\fR ] -Save all current subscriptions (as returned by the Zephyr server) -into current subscriptions file or \fIfile\fR. The -file will be replaced. -.TP -.B set \fIvar\fR [ \fIvalue\fR ] -Set the value of Zephyr variable \fIvar\fR to \fIvalue\fR, or null if -no \fIvalue\fR is specified. The variable \fBexposure\fR has special -significance, and can only be set to the values none, opstaff, realm-visible, -realm-announced, net-visible, and net-announced. Setting this variable -immediately updates the information in the Zephyr servers (see below for -an explanation of the exposure levels). In addition, -setting this variable to none automatically performs the equivalent of a -.B wg_shutdown -command, and setting it to one of the other values automatically -performs the equivalent of a -.B wg_startup -command. -.br -The variable \fBresolved_addresses\fR determines whether zwgc will, -for an IP address indicating the origin of a message, attempt to look -up the hostname corresponding to that IP address. The value none -indicates that hostnames will never be found, and that the zwgc -fromhost variable will thus always contain an IP address (in -dotted-decimal form). The value all indicates that there will always -be an attempt to look up a hostname. Note that in this case, if you -have any subscriptions with recipient ``\fI*\fR'', these subscriptions -may be revealed to other Zephyr users who operate their own DNS name -servers. Any other value is interpreted as a regular expression; -hostname lookup attempts will occur only if the IP address matches -this regular expression. -.br -Any variable settings you make will be stored in \fI$HOME/.zephyr.vars\fR -.TP -.B show \fIvar\fR [ \fIvar\fR \ ... ] -Show the value of the specified Zephyr variables. If a variable is not -defined in the user's own variables file, the system variables file -(\fI/etc/athena/zephyr.vars\fR) is searched for a default value. -.TP -.B subscribe \fIclass instance\fR [ \fIrecipient\fR ] -Subscribe to \fIclass, instance, recipient\fR, but don't add this triplet to -the subscriptions file. -.TP -.B unhide -Make your location as maintained by the Zephyr server visible. This does not -affect the value of the exposure variable. -.TP -.B unload \fR[ \fIfile\fR ] -Unsubscribe to all subscription triplets in current subscriptions file -or \fIfile\fR. Un-subscriptions in the file are ignored. -.TP -.B unset \fIvar\fR [ \fIvar\fR \ ... ] -Delete the definitions of the specified Zephyr variables. -.TP -.B unsubscribe \fIclass instance\fR [ \fIrecipient\fR ] -Unsubscribe to \fIclass, instance, recipient\fR, but don't remove this triplet -from the subscriptions file. -.TP -.B wg_exit -Tell the WindowGram client, -.I zwgc(1), -to exit. -.TP -.B wg_read -Tell the WindowGram client, -.I zwgc(1), -to reread its description file. -.TP -.B wg_shutdown -Tell the WindowGram client to shutdown; this causes it to ignore all -notices until a wg_startup command is issued. -.TP -.B wg_startup -Tell the WindowGram client to start accepting notices again; useful -after a wg_shutdown command has been issued. -.SH MACROS and SUBSCRIPTION FILES -There are three macros, -.I %host%, %canon%, \fRand\fI %me%. %host% -is converted to the current hostname, \fI%canon%\fR is converted to the -official hostname as returned by -.I gethostbyname(3), -and \fI%me%\fR is converted to your Kerberos principal. These macros can be -used in your \fI$HOME/.zephyr.subs\fR file or as arguments to commands -to specify the -.I class -or -.I instance -fields. A sample \fI$HOME/.zephyr.subs\fR file might contain the following: -.PP -.nf - message,urgent,%me% - syslog,%host%,* - mail,pop,%me% -.fi -.PP -.I Zctl -reads the environment variable \fBWGFILE\fR, to find the name of the -file where the windowgram port resides. If \fBWGFILE\fR is not set, -the file name defaults to /tmp/wg.\fIuid\fR, where \fIuid\fR is the -user's UNIX uid. -.SH UN-SUBSCRIPTIONS -The zephyr server, -.I zephyrd(8), -maintains default subscriptions which are automatically added to all -users' subscriptions at the time of their first subscription during a -login session. If you wish to automatically remove some of these -default subscriptions, you use -.B un-subscriptions. -When you -.B load -a subscription file containing -un-subscriptions, the un-subscriptions are automatically sent to the -server as if you had used the -.B unsubscribe -command. -.SH EXPOSURE LEVELS -The different exposure levels affect the operation of zephyr and its -interaction with the user, as follows: -.TP 10 -.I none -This completely disables Zephyr for the user. The user is not -registered with Zephyr. No user location information is -retained by Zephyr. No login or logout announcements will be -sent. No subscriptions will be entered for the user, and no notices -will be displayed by -.I zwgc(1). -.TP -.I opstaff -The user is registered with Zephyr. No login or logout -announcements will be sent, and location information will only be -visible to Operations staff. Default subscriptions and any additional -personal subscriptions will be entered for the user. -.TP -.I realm-visible -The user is registered with Zephyr. User location information is retained by -Zephyr and made available only to users within the user's -Kerberos realm. No login or logout announcements will be sent. This -is the system default. Default subscriptions and any additional -personal subscriptions will be entered for the user. -.TP -.I realm-announced -The user is registered with Zephyr. User location information is retained by -Zephyr and made available only to users authenticated within the user's -Kerberos realm. Login and logout announcements will be sent, but only to -users within the user's Kerberos realm who have explicitly requested -such via subscriptions. Default subscriptions and any additional -personal subscriptions will be entered for the user. -.TP -.I net-visible -The user is registered with Zephyr. User location information is -retained by Zephyr and made available to any authenticated user who -requests such. Login and logout announcements will be sent only to users -within the user's Kerberos realm who have explicitly requested such via -subscriptions. Default subscriptions and any additional personal -subscriptions will be entered for the user. -.TP -.I net-announced -The user is registered with Zephyr. User location information is retained by -Zephyr and made available to any authenticated user who requests such. Login -and logout announcements will be sent to any user has requested such. -Default subscriptions and any additional personal -subscriptions will be entered for the user. -.SH EXAMPLES -.TP 25 -.B zctl -Runs \fIzctl\fR in interactive mode. -.TP -.B zctl load -Load subscriptions and un-subscriptions from \fI$HOME/.zephyr.subs\fR file. -.TP -.B zctl sub message personal -Subscribe to personal messages, but don't add this to the -subscriptions file. -.TP -.B zctl save -Save all current subscriptions to the default subscriptions file. -.TP -.B zctl set exposure none -Set your exposure level to `none', effectively turning off Zephyr. -.SH SEE ALSO -zephyr(1), zwgc(1), zhm(8), zephyrd(8) -gethostbyname(3) -.br -Project Athena Technical Plan Section E.4.1, `Zephyr Notification -Service' -.SH FILES -/tmp/wg.* -.br -$HOME/.zephyr.subs -.br -$ZEPHYR_VARS or $HOME/.zephyr.vars -.br -/etc/athena/zephyr.vars -.SH AUTHOR -.PP -Robert S. French (MIT-Project Athena) -.sp -.SH RESTRICTIONS -Copyright (c) 1987,1988 by the Massachusetts Institute of Technology. -All Rights Reserved. -.br -.I zephyr(1) -specifies the terms and conditions for redistribution. diff --git a/clients/zctl/zctl.1.in b/clients/zctl/zctl.1.in new file mode 100644 index 0000000..d3835d3 --- /dev/null +++ b/clients/zctl/zctl.1.in @@ -0,0 +1,311 @@ +.\" $Id$ +.\" +.\" Copyright 1987,1988 by the Massachusetts Institute of Technology +.\" All rights reserved. The file /usr/include/zephyr/mit-copyright.h +.\" specifies the terms and conditions for redistribution. +.\" +.\" +.TH ZCTL 1 "July 1, 1988" "MIT Project Athena" +.ds ]W MIT Project Athena +.SH NAME +zctl \- zephyr control program +.SH SYNOPSIS +.B zctl +[ +.I options +] +.SH DESCRIPTION +.I Zctl +is a general purpose control program for the +.I Zephyr(1) +Notification Service. It allows the user to subscribe to specific +notice types, to save the subscriptions in a file (default +$HOME/.zephyr.subs), to change his location information, and to send +control messages to the HostManager, +.I zhm(8), +and the WindowGram client, +.I zwgc(1). +.PP +The commands may be typed on the command line, or may be entered +interactively by just typing +.I zctl +and then typing commands to the prompt. +.br +.B NOTE: +For all commands accepting an optional \fIrecipient\fR argument, the +\fIrecipient\fR defaults to your Kerberos principal. You may also +subscribe to recipient ``\fI*\fR''. If you specify a recipient, it is +silently converted to ``\fI*\fR''. +.br +The commands are as follows: +.TP 15 +.B add \fIclass instance\fR [ \fIrecipient\fR ] +Subscribe to \fIclass, instance, recipient\fR, and add this triplet to +the subscriptions file. +.TP +.B add_unsubscription \fIclass instance\fR [ \fIrecipient\fR ] +Unsubscribe to \fIclass, instance, recipient\fR, and add this triplet +to the subscriptions file as an un-subscription. +For an explanation of un-subscriptions, see below. +.TP +.B cancel +Cancel all subscriptions. +.TP +.B defaults +Retrieve the default subscription list from the Zephyr server. +.TP +.B delete \fIclass instance\fR [ \fIrecipient\fR ] +Unsubscribe to \fIclass, instance, recipient\fR, and remove this triplet +from the subscriptions file. +.TP +.B delete_unsubscription \fIclass instance\fR [ \fIrecipient\fR ] +Unsubscribe to \fIclass, instance, recipient\fR, and remove this triplet +from the subscriptions file as an un-subscription. +.TP +.B file \fR[ \fIfile\fR ] +Set default subscriptions file to \fIfile\fR. If \fIfile\fR isn't specified, +show what the current subscriptions file is. +.TP +.B flush_locs +Tell the Zephyr servers to flush all location information associated with +the user. This should only be used to remove any incorrect data that may have +been left after a system crash. +.TP +.B hide +Hide your location as maintained by the Zephyr server. This does not +affect the value of the exposure variable (see below, under +.B set). +.TP +.B hm_flush +Tell the HostManager, +.I zhm(8), +to ask the server to flush all state associated with the current host. +.TP +.B list \fR[ \fIfile\fR ] +List contents of current subscriptions file or +.I file. +Any macros in the file (see below) are displayed verbatim and not expanded. +.TP +.B list_requests +List all available commands. May be abbreviated by '?'. +.TP +.B load \fR[ \fIfile\fR ] +Subscribe to all subscription triplets and unsubscribe to all +un-subscription triplets in current subscriptions file or \fIfile\fR. +.TP +.B new_server +Tell the HostManager, +.I zhm(8), +to find a new Zephyr server. +.TP +.B quit +Exit from \fIzctl. +.TP +.B retrieve +Retrieve all current subscriptions from the Zephyr server. These include +subscriptions that might have been made by other programs, such as +.I znol(1). +.TP +.B save \fR[ \fIfile\fR ] +Save all current subscriptions (as returned by the Zephyr server) +into current subscriptions file or \fIfile\fR. The +file will be replaced. +.TP +.B set \fIvar\fR [ \fIvalue\fR ] +Set the value of Zephyr variable \fIvar\fR to \fIvalue\fR, or null if +no \fIvalue\fR is specified. The variable \fBexposure\fR has special +significance, and can only be set to the values none, opstaff, realm-visible, +realm-announced, net-visible, and net-announced. Setting this variable +immediately updates the information in the Zephyr servers (see below for +an explanation of the exposure levels). In addition, +setting this variable to none automatically performs the equivalent of a +.B wg_shutdown +command, and setting it to one of the other values automatically +performs the equivalent of a +.B wg_startup +command. +.br +The variable \fBresolved_addresses\fR determines whether zwgc will, +for an IP address indicating the origin of a message, attempt to look +up the hostname corresponding to that IP address. The value none +indicates that hostnames will never be found, and that the zwgc +fromhost variable will thus always contain an IP address (in +dotted-decimal form). The value all indicates that there will always +be an attempt to look up a hostname. Note that in this case, if you +have any subscriptions with recipient ``\fI*\fR'', these subscriptions +may be revealed to other Zephyr users who operate their own DNS name +servers. Any other value is interpreted as a regular expression; +hostname lookup attempts will occur only if the IP address matches +this regular expression. +.br +Any variable settings you make will be stored in \fI$HOME/.zephyr.vars\fR +.TP +.B show \fIvar\fR [ \fIvar\fR \ ... ] +Show the value of the specified Zephyr variables. If a variable is not +defined in the user's own variables file, the system variables file +(\fI@sysconfdir@/zephyr/zephyr.vars\fR) is searched for a default value. +.TP +.B subscribe \fIclass instance\fR [ \fIrecipient\fR ] +Subscribe to \fIclass, instance, recipient\fR, but don't add this triplet to +the subscriptions file. +.TP +.B unhide +Make your location as maintained by the Zephyr server visible. This does not +affect the value of the exposure variable. +.TP +.B unload \fR[ \fIfile\fR ] +Unsubscribe to all subscription triplets in current subscriptions file +or \fIfile\fR. Un-subscriptions in the file are ignored. +.TP +.B unset \fIvar\fR [ \fIvar\fR \ ... ] +Delete the definitions of the specified Zephyr variables. +.TP +.B unsubscribe \fIclass instance\fR [ \fIrecipient\fR ] +Unsubscribe to \fIclass, instance, recipient\fR, but don't remove this triplet +from the subscriptions file. +.TP +.B wg_exit +Tell the WindowGram client, +.I zwgc(1), +to exit. +.TP +.B wg_read +Tell the WindowGram client, +.I zwgc(1), +to reread its description file. +.TP +.B wg_shutdown +Tell the WindowGram client to shutdown; this causes it to ignore all +notices until a wg_startup command is issued. +.TP +.B wg_startup +Tell the WindowGram client to start accepting notices again; useful +after a wg_shutdown command has been issued. +.SH MACROS and SUBSCRIPTION FILES +There are three macros, +.I %host%, %canon%, \fRand\fI %me%. %host% +is converted to the current hostname, \fI%canon%\fR is converted to the +official hostname as returned by +.I gethostbyname(3), +and \fI%me%\fR is converted to your Kerberos principal. These macros can be +used in your \fI$HOME/.zephyr.subs\fR file or as arguments to commands +to specify the +.I class +or +.I instance +fields. A sample \fI$HOME/.zephyr.subs\fR file might contain the following: +.PP +.nf + message,urgent,%me% + syslog,%host%,* + mail,pop,%me% +.fi +.PP +.I Zctl +reads the environment variable \fBWGFILE\fR, to find the name of the +file where the windowgram port resides. If \fBWGFILE\fR is not set, +the file name defaults to /tmp/wg.\fIuid\fR, where \fIuid\fR is the +user's UNIX uid. +.SH UN-SUBSCRIPTIONS +The zephyr server, +.I zephyrd(8), +maintains default subscriptions which are automatically added to all +users' subscriptions at the time of their first subscription during a +login session. If you wish to automatically remove some of these +default subscriptions, you use +.B un-subscriptions. +When you +.B load +a subscription file containing +un-subscriptions, the un-subscriptions are automatically sent to the +server as if you had used the +.B unsubscribe +command. +.SH EXPOSURE LEVELS +The different exposure levels affect the operation of zephyr and its +interaction with the user, as follows: +.TP 10 +.I none +This completely disables Zephyr for the user. The user is not +registered with Zephyr. No user location information is +retained by Zephyr. No login or logout announcements will be +sent. No subscriptions will be entered for the user, and no notices +will be displayed by +.I zwgc(1). +.TP +.I opstaff +The user is registered with Zephyr. No login or logout +announcements will be sent, and location information will only be +visible to Operations staff. Default subscriptions and any additional +personal subscriptions will be entered for the user. +.TP +.I realm-visible +The user is registered with Zephyr. User location information is retained by +Zephyr and made available only to users within the user's +Kerberos realm. No login or logout announcements will be sent. This +is the system default. Default subscriptions and any additional +personal subscriptions will be entered for the user. +.TP +.I realm-announced +The user is registered with Zephyr. User location information is retained by +Zephyr and made available only to users authenticated within the user's +Kerberos realm. Login and logout announcements will be sent, but only to +users within the user's Kerberos realm who have explicitly requested +such via subscriptions. Default subscriptions and any additional +personal subscriptions will be entered for the user. +.TP +.I net-visible +The user is registered with Zephyr. User location information is +retained by Zephyr and made available to any authenticated user who +requests such. Login and logout announcements will be sent only to users +within the user's Kerberos realm who have explicitly requested such via +subscriptions. Default subscriptions and any additional personal +subscriptions will be entered for the user. +.TP +.I net-announced +The user is registered with Zephyr. User location information is retained by +Zephyr and made available to any authenticated user who requests such. Login +and logout announcements will be sent to any user has requested such. +Default subscriptions and any additional personal +subscriptions will be entered for the user. +.SH EXAMPLES +.TP 25 +.B zctl +Runs \fIzctl\fR in interactive mode. +.TP +.B zctl load +Load subscriptions and un-subscriptions from \fI$HOME/.zephyr.subs\fR file. +.TP +.B zctl sub message personal +Subscribe to personal messages, but don't add this to the +subscriptions file. +.TP +.B zctl save +Save all current subscriptions to the default subscriptions file. +.TP +.B zctl set exposure none +Set your exposure level to `none', effectively turning off Zephyr. +.SH SEE ALSO +zephyr(1), zwgc(1), zhm(8), zephyrd(8) +gethostbyname(3) +.br +Project Athena Technical Plan Section E.4.1, `Zephyr Notification +Service' +.SH FILES +/tmp/wg.* +.br +$HOME/.zephyr.subs +.br +$ZEPHYR_VARS or $HOME/.zephyr.vars +.br +@sysconfdir@/zephyr/zephyr.vars +.SH AUTHOR +.PP +Robert S. French (MIT-Project Athena) +.sp +.SH RESTRICTIONS +Copyright (c) 1987,1988 by the Massachusetts Institute of Technology. +All Rights Reserved. +.br +.I zephyr(1) +specifies the terms and conditions for redistribution. diff --git a/configure.ac b/configure.ac index 96e8c52..7278b41 100644 --- a/configure.ac +++ b/configure.ac @@ -397,4 +397,5 @@ AC_OUTPUT(Makefile clients/Makefile clients/zaway/Makefile clients/zlocate/Makefile clients/znol/Makefile clients/zshutdown_notify/Makefile clients/zstat/Makefile clients/zwrite/Makefile lib/Makefile - server/Makefile zhm/Makefile zwgc/Makefile) + server/Makefile zhm/Makefile zwgc/Makefile + ) diff --git a/server/Makefile.in b/server/Makefile.in index 7d244be..dc51a96 100644 --- a/server/Makefile.in +++ b/server/Makefile.in @@ -21,6 +21,12 @@ LIBTOOL=@LIBTOOL@ CC=@CC@ INSTALL=@INSTALL@ +editman = sed \ + -e 's|@datadir[@]|${datadir}|g' \ + -e 's|@sysconfdir[@]|${sysconfdir}|g' \ + -e 's|@sbindir[@]|${sbindir}|g' \ + -e 's|@lsbindir[@]|${lsbindir}|g' + LIBZEPHYR=${BUILDTOP}/lib/libzephyr.la CPPFLAGS=@CPPFLAGS@ CFLAGS=@CFLAGS@ @@ -34,7 +40,7 @@ OBJS= zsrv_err.o access.o acl_files.o bdump.o class.o client.o common.o \ dispatch.o kstuff.o main.o server.o subscr.o timer.o uloc.o \ zstring.o realm.o version.o utf8proc.o -all: zephyrd +all: zephyrd zephyrd.8 zephyrd: ${OBJS} ${LIBZEPHYR} ${LIBTOOL} --mode=link ${CC} ${LDFLAGS} -o $@ ${OBJS} ${LIBS} ${HESIOD_LIBS} @@ -46,6 +52,10 @@ zsrv_err.c: zsrv_err.et .c.o: ${CC} -c ${ALL_CFLAGS} $< +zephyrd.8: ${srcdir}/zephyrd.8.in Makefile + ${editman} ${srcdir}/$@.in > $@.tmp + mv $@.tmp $@ + check: # No dependency on zephyrd, to avoid rebuilding version.o. @@ -59,6 +69,7 @@ install: clean: ${LIBTOOL} --mode=clean rm -f zephyrd rm -f ${OBJS} zsrv_err.[ch] + rm -f zephyrd.8 ${OBJS}: zserver.h zsrv_err.h timer.h zsrv_conf.h zstring.h access.h acl.h ${OBJS}: ${top_srcdir}/h/internal.h ${top_srcdir}/h/sysdep.h diff --git a/server/zephyrd.8 b/server/zephyrd.8 deleted file mode 100644 index abd1d6b..0000000 --- a/server/zephyrd.8 +++ /dev/null @@ -1,126 +0,0 @@ -.\" $Id$ -.\" -.\" Copyright 1987 by the Massachusetts Institute of Technology -.\" All rights reserved. The file /usr/include/zephyr/mit-copyright.h -.\" specifies the terms and conditions for redistribution. -.\" -.TH ZEPHYRD 8 "July 1, 1988" "MIT Project Athena" -.ds ]W MIT Project Athena -.SH NAME -zephyrd \- Zephyr server daemon -.SH SYNOPSIS -.I /usr/etc/zephyrd -[ -.BI \-d -] -.SH DESCRIPTION -.I zephyrd -is the central server for the Zephyr Notification System. -It maintains a location database of all currently logged-in users, and a -subscription database for each user's Zephyr clients. -.PP -.I zephyrd -communicates with daemons running on other Zephyr server hosts, to -provide a reliable service. -.PP -While running, any unusual conditions are recorded via -.I syslog(3) -to facility local6 at various levels. -The -.BI \-d -option enables logging of additional debugging information. -.PP -When a -.B zephyrd -is executed, it requests a list of server machines from Hesiod and -initializes its state from any -\fIzephyrd\fRs executing on the other known servers. This initialization -is only performed after the \fIzephyrd\fRs have authenticated themselves -to each other via Kerberos. -The server then enters a dispatch loop, servicing requests from clients and -other servers. -.SH SIGNALS -.B SIGUSR1 -enables logging of additional debugging information. -.br -.B SIGUSR2 -disables the logging of additional debugging information. -.br -.B SIGHUP -causes -.I zephyrd -to re-read the default subscription file and to re-query Hesiod about -valid peers. Any peers which are not responding and no longer -mentioned in Hesiod are flushed; any peers not previously named by -Hesiod are added. -.br -.B SIGINT \fRand\fB SIGTERM -cause -.I zephyrd -to gracefully shut down. -.br -.B SIGFPE -causes -.I zephyrd -to dump the location and subscription databases to -.I /var/tmp/zephyr.db -in an ASCII format. -.SH ACCESS CONTROL -Certain notice classes are restricted by the Zephyr server. Each such -class has access control lists enumerating who may transmit (xmt-*.acl) or -subscribe to that particular class. Subscriptions may be -restricted either absolutely (sub-*.acl files), or by instance restrictions. -iws-*.acl files control subscriptions to wildcarded instances. -iui-*.acl files control subscriptions to instances which are not the -Kerberos principal identity of the subscriber. -If an access control list of a given type is absent, there is no -restriction of that type on the class, except that any notices of the -class must be authenticated. -The class registry lists all classes which are restricted. -.SH FILES -.TP 10 -.I /etc/zephyr/acl/class-registry.acl: -List of classes which are restricted -.TP -.I /etc/zephyr/acl/iws-*.acl: -Access Control Lists for instance-wildcard restrictions -.TP -.I /etc/zephyr/acl/iui-*.acl: -Access Control Lists for instance-identity restrictions -.TP -.I /etc/zephyr/acl/sub-*.acl: -Access Control Lists for subscribing -.TP -.I /etc/zephyr/acl/xmt-*.acl: -Access Control Lists for transmitting -.TP -.I /etc/zephyr/srvtab: -Kerberos 4 Service keys -.TP -.I /etc/zephyr/krb5.keytab: -Kerberos V Service keys -.TP -.I /etc/zephyr/ztkts: -Current Kerberos tickets for exchange with other servers -.TP -.I /var/tmp/zephyr.db: -File containing an ASCII dump of the database. -.SH BUGS -The current implementation of the Zephyr server (\fIzephyrd(8)\fR) makes -no distinction between realm-announced, net-visible and net-announced -exposure levels. -.SH SEE ALSO -zephyr(1), zhm(8), kerberosintro(1), hesiod(3), access_control_lists(?), -syslog(3) -.br -Athena Technical Plan, Sections E.4.1 (Zephyr Notification Service) and -E.2.1 (Kerberos Authentication and Authorization System) -.SH AUTHOR -.PP -John T. Kohl, MIT Project Athena and Digital Equipment Corporation -.SH RESTRICTIONS -Copyright (c) 1987,1988 by the Massachusetts Institute of Technology. -All Rights Reserved. -.br -.I zephyr(1) -specifies the terms and conditions for redistribution. diff --git a/server/zephyrd.8.in b/server/zephyrd.8.in new file mode 100644 index 0000000..eef9780 --- /dev/null +++ b/server/zephyrd.8.in @@ -0,0 +1,129 @@ +.\" $Id$ +.\" +.\" Copyright 1987 by the Massachusetts Institute of Technology +.\" All rights reserved. The file /usr/include/zephyr/mit-copyright.h +.\" specifies the terms and conditions for redistribution. +.\" +.TH ZEPHYRD 8 "July 1, 1988" "MIT Project Athena" +.ds ]W MIT Project Athena +.SH NAME +zephyrd \- Zephyr server daemon +.SH SYNOPSIS +.I @sbindir@/zephyrd +[ +.BI \-d +] +.SH DESCRIPTION +.I zephyrd +is the central server for the Zephyr Notification System. +It maintains a location database of all currently logged-in users, and a +subscription database for each user's Zephyr clients. +.PP +.I zephyrd +communicates with daemons running on other Zephyr server hosts, to +provide a reliable service. +.PP +While running, any unusual conditions are recorded via +.I syslog(3) +to facility local6 at various levels. +The +.BI \-d +option enables logging of additional debugging information. +.PP +When a +.B zephyrd +is executed, it requests a list of server machines from Hesiod and +initializes its state from any +\fIzephyrd\fRs executing on the other known servers. This initialization +is only performed after the \fIzephyrd\fRs have authenticated themselves +to each other via Kerberos. +The server then enters a dispatch loop, servicing requests from clients and +other servers. +.SH SIGNALS +.B SIGUSR1 +enables logging of additional debugging information. +.br +.B SIGUSR2 +disables the logging of additional debugging information. +.br +.B SIGHUP +causes +.I zephyrd +to re-read the default subscription file and to re-query Hesiod about +valid peers. Any peers which are not responding and no longer +mentioned in Hesiod are flushed; any peers not previously named by +Hesiod are added. +.br +.B SIGINT \fRand\fB SIGTERM +cause +.I zephyrd +to gracefully shut down. +.br +.B SIGFPE +causes +.I zephyrd +to dump the location and subscription databases to +.I /var/tmp/zephyr.db +in an ASCII format. +.SH ACCESS CONTROL +Certain notice classes are restricted by the Zephyr server. Each such +class has access control lists enumerating who may transmit (xmt-*.acl) or +subscribe to that particular class. Subscriptions may be +restricted either absolutely (sub-*.acl files), or by instance restrictions. +iws-*.acl files control subscriptions to wildcarded instances. +iui-*.acl files control subscriptions to instances which are not the +Kerberos principal identity of the subscriber. +If an access control list of a given type is absent, there is no +restriction of that type on the class, except that any notices of the +class must be authenticated. +The class registry lists all classes which are restricted. +.SH FILES +.TP 10 +.I @sysconfdir@/zephyr/acl/class-registry.acl: +List of classes which are restricted +.TP +.I @sysconfdir@/zephyr/acl/iws-*.acl: +Access Control Lists for instance-wildcard restrictions +.TP +.I @sysconfdir@/zephyr/acl/iui-*.acl: +Access Control Lists for instance-identity restrictions +.TP +.I @sysconfdir@/zephyr/acl/sub-*.acl: +Access Control Lists for subscribing +.TP +.I @sysconfdir@/zephyr/acl/xmt-*.acl: +Access Control Lists for transmitting +.TP +.I @sysconfdir@/zephyr/srvtab: +Kerberos 4 Service keys +.TP +.I @sysconfdir@/zephyr/krb5.keytab: +Kerberos V Service keys +.TP +.I /var/run/zephyrd.tkt4: +Current Kerberos 4 tickets for exchange with other servers +.TP +.I /var/run/zephyrd.tkt: +Current Kerberos 5 tickets for exchange with other servers +.TP +.I /var/tmp/zephyr.db: +File containing an ASCII dump of the database. +.SH BUGS +The current implementation of the Zephyr server (\fIzephyrd(8)\fR) makes +no distinction between realm-announced, net-visible and net-announced +exposure levels. +.SH SEE ALSO +zephyr(1), zhm(8), kerberosintro(1), hesiod(3), access_control_lists(?), +syslog(3) +.br +Athena Technical Plan, Sections E.4.1 (Zephyr Notification Service) and +E.2.1 (Kerberos Authentication and Authorization System) +.SH AUTHOR +.PP +John T. Kohl, MIT Project Athena and Digital Equipment Corporation +.SH RESTRICTIONS +Copyright (c) 1987,1988 by the Massachusetts Institute of Technology. +All Rights Reserved. +.br +.I zephyr(1) +specifies the terms and conditions for redistribution. diff --git a/zhm/Makefile.in b/zhm/Makefile.in index 801575d..cbaf6ab 100644 --- a/zhm/Makefile.in +++ b/zhm/Makefile.in @@ -21,6 +21,12 @@ LIBTOOL=@LIBTOOL@ CC=@CC@ INSTALL=@INSTALL@ +editman = sed \ + -e 's|@datadir[@]|${datadir}|g' \ + -e 's|@sysconfdir[@]|${sysconfdir}|g' \ + -e 's|@sbindir[@]|${sbindir}|g' \ + -e 's|@lsbindir[@]|${lsbindir}|g' + LIBZEPHYR=${BUILDTOP}/lib/libzephyr.la CPPFLAGS=@CPPFLAGS@ CFLAGS=@CFLAGS@ @@ -30,11 +36,15 @@ HESIOD_LIBS=@HESIOD_LIBS@ OBJS= timer.o queue.o zhm.o zhm_client.o zhm_server.o -all: zhm +all: zhm zhm.8 zhm: ${OBJS} ${LIBZEPHYR} ${LIBTOOL} --mode=link ${CC} ${LDFLAGS} -o $@ ${OBJS} ${LIBZEPHYR} ${HESIOD_LIBS} -lcom_err +zhm.8: ${srcdir}/zhm.8.in Makefile + ${editman} ${srcdir}/$@.in > $@.tmp + mv $@.tmp $@ + .c.o: ${CC} -c ${ALL_CFLAGS} $< @@ -47,6 +57,7 @@ install: zhm clean: ${LIBTOOL} --mode=clean rm -f zhm rm -f ${OBJS} + rm -f zhm.8 ${OBJS}: zhm.h timer.h ${top_srcdir}/h/internal.h ${top_srcdir}/h/sysdep.h ${OBJS}: ${BUILDTOP}/h/config.h ${BUILDTOP}/h/zephyr/zephyr.h diff --git a/zhm/zhm.8 b/zhm/zhm.8 deleted file mode 100644 index 6610e3f..0000000 --- a/zhm/zhm.8 +++ /dev/null @@ -1,106 +0,0 @@ -.\" $Id$ -.\" -.\" Copyright 1987, 1988 by the Massachusetts Institute of Technology -.\" All rights reserved. The file /usr/include/zephyr/mit-copyright.h -.\" specifies the terms and conditions for redistribution. -.\" -.\" -.TH ZHM 8 "November 1, 1988" "MIT Project Athena" -.ds ]W MIT Project Athena -.SH NAME -zhm \- Zephyr HostManager -.SH SYNOPSIS -.B /usr/sbin/zhm -[ -.BI -d -] [ -.BI -n -] [ -.BI -h -] [ -.BI -r -] [ -.BI -i -] [ -.BI -f -] [ -.BI -N -] [ -.BI server -.BI ... -] -.SH DESCRIPTION -.I Zhm -is the link between a client machine and the zephyr server. All -notices sent from programs on the client are funneled through -.I zhm. -This allows all client programs to be much simpler in function, since -the HostManager is responsible for handling errors, retransmitting -lost notices, and holding all notices until they are acknowledged. -.PP -The -.I -d -option turns on debugging mode, and sends its information to syslog -LOG_DAEMON messages. -.PP -The -.I -n -option causes zhm to not attempt to put itself in the background. -.PP -The -.I -h -option causes -.I zhm -to send a shutdown message and exit upon delivery of a SIGHUP signal. -The normal action on SIGHUP is to send a flush notice to the zephyr server. -.PP -The -.I -r -option causes -.I zhm -to send a boot notice to the server and exit when the notice is acknowledged. -.PP -The -.I -i -option indicates that -.I zhm -is being started by -.I inetd(8). -When this option is specified, -.I zhm -assumes that file descriptor zero (0) is bound to the UDP datagram port -designated for hostmanager use. In this mode, SIGHUP is handled as if the -.I -h -option were specified. -.PP -The -.I -f -option disables the "flush" operation which allows any client to flush -all subscriptions for the host. -.PP -The -.I -N -option supresses the initial "boot" message that flushes all subscriptions -for the host, which is useful if you're restarting zhm on a host that -people are using. -.PP -The optional -.I server -arguments are used to replace the set of server names supplied by -the -.I hesiod(3) -name server. -.SH SEE ALSO -zephyr(1), zephyrd(8), inetd(8) -.br -Project Athena Technical Plan Section E.4.1, `Zephyr Notification -Service' -.SH AUTHOR -.PP -David C. Jedlinsky, MIT Project Athena -.SH RESTRICTIONS -Copyright (c) 1987,1988 by the Massachusetts Institute of Technology. -All Rights Reserved. -.br -.I zephyr(1) -specifies the terms and conditions for redistribution. diff --git a/zhm/zhm.8.in b/zhm/zhm.8.in new file mode 100644 index 0000000..15961dd --- /dev/null +++ b/zhm/zhm.8.in @@ -0,0 +1,106 @@ +.\" $Id$ +.\" +.\" Copyright 1987, 1988 by the Massachusetts Institute of Technology +.\" All rights reserved. The file /usr/include/zephyr/mit-copyright.h +.\" specifies the terms and conditions for redistribution. +.\" +.\" +.TH ZHM 8 "November 1, 1988" "MIT Project Athena" +.ds ]W MIT Project Athena +.SH NAME +zhm \- Zephyr HostManager +.SH SYNOPSIS +.B @lsbindir@/zhm +[ +.BI -d +] [ +.BI -n +] [ +.BI -h +] [ +.BI -r +] [ +.BI -i +] [ +.BI -f +] [ +.BI -N +] [ +.BI server +.BI ... +] +.SH DESCRIPTION +.I Zhm +is the link between a client machine and the zephyr server. All +notices sent from programs on the client are funneled through +.I zhm. +This allows all client programs to be much simpler in function, since +the HostManager is responsible for handling errors, retransmitting +lost notices, and holding all notices until they are acknowledged. +.PP +The +.I -d +option turns on debugging mode, and sends its information to syslog +LOG_DAEMON messages. +.PP +The +.I -n +option causes zhm to not attempt to put itself in the background. +.PP +The +.I -h +option causes +.I zhm +to send a shutdown message and exit upon delivery of a SIGHUP signal. +The normal action on SIGHUP is to send a flush notice to the zephyr server. +.PP +The +.I -r +option causes +.I zhm +to send a boot notice to the server and exit when the notice is acknowledged. +.PP +The +.I -i +option indicates that +.I zhm +is being started by +.I inetd(8). +When this option is specified, +.I zhm +assumes that file descriptor zero (0) is bound to the UDP datagram port +designated for hostmanager use. In this mode, SIGHUP is handled as if the +.I -h +option were specified. +.PP +The +.I -f +option disables the "flush" operation which allows any client to flush +all subscriptions for the host. +.PP +The +.I -N +option supresses the initial "boot" message that flushes all subscriptions +for the host, which is useful if you're restarting zhm on a host that +people are using. +.PP +The optional +.I server +arguments are used to replace the set of server names supplied by +the +.I hesiod(3) +name server. +.SH SEE ALSO +zephyr(1), zephyrd(8), inetd(8) +.br +Project Athena Technical Plan Section E.4.1, `Zephyr Notification +Service' +.SH AUTHOR +.PP +David C. Jedlinsky, MIT Project Athena +.SH RESTRICTIONS +Copyright (c) 1987,1988 by the Massachusetts Institute of Technology. +All Rights Reserved. +.br +.I zephyr(1) +specifies the terms and conditions for redistribution. diff --git a/zwgc/Makefile.in b/zwgc/Makefile.in index 63c77c2..595ab99 100644 --- a/zwgc/Makefile.in +++ b/zwgc/Makefile.in @@ -24,6 +24,12 @@ YACC=@YACC@ INSTALL=@INSTALL@ INSTANTIATE=${srcdir}/instantiate +editman = sed \ + -e 's|@datadir[@]|${datadir}|g' \ + -e 's|@sysconfdir[@]|${sysconfdir}|g' \ + -e 's|@sbindir[@]|${sbindir}|g' \ + -e 's|@lsbindir[@]|${lsbindir}|g' + LIBZEPHYR=${BUILDTOP}/lib/libzephyr.la CPPFLAGS=@CPPFLAGS@ CFLAGS=@CFLAGS@ @@ -43,7 +49,7 @@ OBJS= port_dictionary.o pointer_dictionary.o unsigned_long_dictionary.o \ standard_ports.o xselect.o xmark.o xrevstack.o xerror.o \ new_string.o new_memory.o plus.o -all: zwgc +all: zwgc zwgc.1 zwgc: ${OBJS} ${LIBZEPHYR} ${LIBTOOL} --mode=link ${CC} ${LDFLAGS} -o $@ ${OBJS} ${LIBS} @@ -84,6 +90,10 @@ y.tab.c y.tab.h: ${srcdir}/parser.y .c.o: ${CC} -c ${ALL_CFLAGS} $< +zwgc.1: ${srcdir}/zwgc.1.in Makefile + ${editman} ${srcdir}/$@.in > $@.tmp + mv $@.tmp $@ + check: install: zwgc @@ -98,6 +108,7 @@ clean: rm -f unsigned_long_dictionary.[ch] string_dictionary.[ch] rm -f int_dictionary.[ch] char_stack.h string_stack.h xmode_stack.h rm -f y.tab.[ch] + rm -f zwgc.1 ${OBJS}: ${top_srcdir}/h/sysdep.h ${BUILDTOP}/h/config.h zephyr.o: ${BUILDTOP}/h/zephyr/zephyr.h ${BUILDTOP}/h/zephyr/zephyr_err.h diff --git a/zwgc/zwgc.1 b/zwgc/zwgc.1 deleted file mode 100644 index d2d597c..0000000 --- a/zwgc/zwgc.1 +++ /dev/null @@ -1,1070 +0,0 @@ -.\" $Id$ -.\" # end of TP (cf }N below) -.\" # copied here, since we use @ in some of our tags, and that -.\" # messes up \w and \h -.de }1 -.ds ]X \&\\*(]B\\ -.nr )E 0 -.if !"\\$1"" .nr )I \\$1n -.}f -.ll \\n(LLu -.in \\n()Ru+\\n(INu+\\n()Iu -.ti \\n(INu -.ie !\\n()Iu+\\n()Ru-\w'\\*(]X'u-3p \{\\*(]X -.br\} -.el \\*(]X\h@|\\n()Iu+\\n()Ru@\c -.}f -.. -.de }N -.if \\n()E .br -.di -.if "\\n()E"0" .}f -.if "\\n()E"1" .}1 -.if "\\n()E"2" .}2 -.nr )E 0 -.. -.\" # tagged paragraph (paragraph with hanging label, but no para spacing) -.de TQ -.if !"\\$1"" .nr )I \\$1n -.ne 1.1v -.in \\n()Ru -.nr )E 1 -.ns -.it 1 }N -.di ]B -.. -.TH ZWGC 1 "November 30, 1989" "MIT Project Athena" -.SH NAME -zwgc \- Zephyr Windowgram Client program -.SH SYNOPSIS -.B zwgc -[ \-reenter ] [ \-nofork ] [ \-ttymode ] [ \-f -.I filename -] [ \-subfile -.I filename -] [ \-loc -.I text -] [ \-default -.I portname -] [ \-disable -.I portname -] ... [ output driver options ] -[ X Toolkit options... ] -.SH DESCRIPTION -.I Zwgc -is the main -.I 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. - -.SS "Selection of Zephyr Notices" -.PP -.I 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 -.IR zctl (1). -The user's subscription file defaults to -.IR $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. - -.PP -The -.I zctl -command is used to manipulate and change subscriptions. See the -.IR zctl (1) -man page for details. - -.SS "Zephyr Description Files" -.PP -.I Zwgc -formats its output messages according to the commands in its -description file. The user's description file -.RI ( $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. -.PP -Every time a notice is received, -.I zwgc -runs through the description file, and executes the appropriate commands. - -.SS "Zephyr Description File Syntax" -.PP -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 */"). - -.SH "DESCRIPTION LANGUAGE" -.SS 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. -.PP -String literals are specified by putting the contents in "double quotes". -.PP -Variables are set using the -.B set -command (see "COMMANDS", below). They are -referenced in an expression by using the form -.IR $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. -.PP -Functions are called using a C-like syntax, -\fBfname\fR(\fIexpr1\fR,\fIexpr2\fR), where -.B fname -is the -function name and -.IB expr n -are the arguments. -.PP -Binary operators use infix notation, such as "a == b". -.PP -Some commands use an expression list (exprlist), which is simply a set -of expressions separated by whitespace (e.g. $var1 "lit1" $var2). - -.SS "Default variables" -.PP -The following variables are always available: -.TP 5 -.B 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. -.TP 5 -.B 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 -.IR kinit (1) -but has not run ``zctl sub'' to -register this change with the Zephyr servers. -.TP -.B class -The class of the current notice. -.TP -.B date -The date on which the notice was sent. -.TP -.B default -The default output format for the current notice -.TP -.B error -An error message from the port read/write commands. -.TP -.B fromhost -The full name of the host from which the notice appears to have been -sent. -.I This is not fully reliable, -as the information used to determine this hostname is not guaranteed to -be correct (even for authentic messages). -.TP -.B fullsender -The notice sender's name, including the zephyr realm name. -.TP -.B instance -The instance of the current notice. -.TP -.B kind -The kind of notice. -.TP -.B message -The full text of the message, with nulls converted to newlines. -.TP -.B number_of_fields -The number of fields in the message (a string representation of a -decimal number). -.TP -.B opcode -The opcode of the current notice. -.TP -.B output_driver -The name of the output driver in use. -.TP -.B port -The port from which the notice was sent. -.TP -.B realm -The local zephyr realm. -.TP -.B recipient -The recipient for the current notice. If the notice is a multicast -(sent to several people), the recipient is set to ``*''. -.TP -.B sender -Usually a shortened version of fullsender. If the realm of the sender -is equal to the realm of the recipient, -.I sender -omits the realm name. -.TP -.B time -The time of day at which the notice was sent. -.TP -.B user -The full zephyr name of the user (e.g. marc@ATHENA.MIT.EDU). -.TP -.B version -The current version of -.IR zwgc . -.TP -.B zephyr_version -The protocol version of the notice. -.PP -All of these variables (except for error, output_driver, and version) -are re-set before each notice is processed. - -.SS Functions -.PP -Following is a list of functions available for use in the description -file. -.TP 5 -.BI buffer () -The contents of the current output buffer. -.TP -.BI downcase (expr) -Returns the value of \fIexpr\fR, converted to lower case. -.TP -.BI get (expr) -Returns a line from the port named \fIexpr\fR. 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. -.TP -.BI getenv (expr) -Returns the value of the environment variable \fIexpr\fR, or the empty -string if it does not exist. - -.TP -.BI lany "(expr1, expr2), " rany "(expr1, expr2)" -Return a number of characters equal to the length of -.I expr2 -from the beginning -.RB ( lany ) -or end -.RB ( rany ) -of -.I expr1 -(e.g. lany("1234567890","foo") would return "123"). -If -.I expr1 -is a variable reference, the variable -is modified to remove the characters returned. -If -.I expr2 -is longer than -.IR expr1 , -the value of -.I expr1 -is returned (and -.I expr1 -is set to "", if a variable). -.TP -.BI lbreak "(expr1, expr2), " rbreak "(expr1, expr2)" -.I Expr2 -defines a set of characters. The function returns the longest -initial -.RB ( lbreak ) -or final -.RB ( rbreak ) -string from -.I expr1 -composed of characters -.I not -in this set (e.g. lbreak("characters", "tuv") would return "charac"). If -.I expr1 -is a variable reference, the variable -is modified to remove the characters returned. If no characters -in -.IR expr2 " are in " "expr1, " then " expr1 " -is returned (and -.I expr1 -is set to "", if a variable). -.TP -.BI lspan "(expr1, expr2), " rspan "(expr1, expr2)" -These functions are the negation of the -.B break -functions; the returned string consists of characters -.I in -the set defined by -.I expr2 -.TP -.BI protect (expr) -Returns a string which will be evaluated identically to \fIexpr\fR, -but will not affect any surrounding environments. That is, any -characters which could close outside environments are quoted, and any -environments in \fIexpr\fR which are not closed at the end are closed. -.TP -.BI substitute (expr) -Evaluates variable references of the form \fI$variable\fR in expr and -converts $$ to $. -.TP -.BI upcase (expr) -Returns the value of \fIexpr\fR, converted to upper case. -.TP -.BI verbatim (expr) -Returns a string that will be displayed exactly as \fIexpr\fR looks. -Anything which could be mistaken for an environment is quoted. -.TP -.BI stylestrip (expr) -Returns \fIexpr\fR with all environments stripped out. -.TP -.BI zvar (expr) -Returns the value of the zephyr variable \fIexpr\fR, -or the empty -string if it does not exist. [Zephyr variables -can be set and examined with -.IR zctl (1).] - -.SS Operators -.PP -Following is a list of operators which can be used in the description -file to compose expressions: -.TP -.IB expr1 " + " expr2 -String concatenation of -.IR expr1 " and " expr2 -.TP -.IB expr1 " == " expr2 -True if the two expressions are equal, false otherwise. -.TP -.IB expr1 " =~ " expr2 -True if the regular expression pattern -.IR expr2 " matches " expr1. -.TP -.IB expr1 " !~ " expr2 -Negation of "=~". -.TP -.IB expr1 " != " expr2 -Negation of "==" -.TP -\fIexpr1\fB and \fIexpr2\fR, \fIexpr1\fB & \fIexpr2\fR -True if -.IR expr1 " and " expr2 -are both true. -.TP -\fIexpr1\fB or \fIexpr2\fR, \fIexpr1\fB | \fIexpr2\fR -True if either of -.IR expr1 " or " expr2 -are true. -.TP -\fB! \fIexpr1\fR, \fBnot \fIexpr1\fR -The logical negation of -.I expr1. - -.SS Commands -.PP -Following is a list of the commands usable in the description -language: -.TP 5 -.BI appendport " expr1 expr2" -Creates a port called \fIexpr1\fR. All output to the port will be -appended to the file \fIexpr2\fR. There is no input. If the file is -created, its mode is set to read-write, owner only (no access for others). -.TP -.B break -Exits the innermost if, case, or while block. -.TP -\fBcase \fIexpr1\fR [ ((\fBmatch \fIexpr\fR [,\fIexpr ...\fR]) | \fBdefault\fR)\fI commands \fR] ... \fBendcase\fR -Evaluates \fIexpr1\fR. Then, each of the match expressions is -evaluated in order. The first time an expression matches \fIexpr1\fR, -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. -.TP -.B clearbuf -Clears the output buffer (see below for details on buffering). -.TP -.BI closeinput " expr" -Closes the file associated with \fIexpr\fR. -.TP -.BI closeoutput " expr" -Sends an EOF (end-of-file) to the process if \fIexpr\fR was a port created by -execport, or closes the file if it was created by outputport or -appendport. -.TP -.BI closeport " expr" -Closes both input and output of \fIexpr\fR as defined above. -.TP -.BI 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. -.TP -.BI exec " exprlist" -Executes a program without any input or output. A command named by -\fIexprlist\fR 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). -.TP -.BI execport " expr1 exprlist" -Creates a port called \fIexpr1\fR. A command named by \fIexprlist\fR -is executed, as described above for \fBexec\fR. -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. -.TP -.B exit -Completes processing of the current notice. The remainder of the -description file is ignored after execution of this command. -.\" hack because the following line otherwise breaks because it is too long. -.TP -\fBif \fIexpr1 \fBthen \fIcommands1\fR [\fBelseif \fIexpr2 \fBthen \fIcommands2\fR] ... [\fBelse \fIcommandsn\fR] \fBendif\fR -If \fIexpr1\fR evaluates to true, execute \fIcommands1\fI, etc. [A conditional -construct, similar to the constructs in the C shell (csh).] -.TP -.BI inputport " expr1 expr2" -Creates a port called \fIexpr1\fR. All input from the port comes from -the file \fIexpr2\fR. There is no output. -.TP -.B noop -does nothing -.TP -.BI outputport " expr1 expr2" -Creates a port called \fIexpr1\fR. The file \fIexpr2\fR will be -truncated, or created if it does not exist. All output to the port -will be appended to the file \fIexpr2\fR. There is no input. If the file is -created, its mode is set to read-write, owner only (no access for others). -.TP -.BI 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. -.TP -.B put \fR[\fIexpr \fR[\fIexprlist\fR]] -Sends data to a port. If \fIexpr\fR is provided, then it is used as the -port, otherwise the port used is the -port corresponding to the default output device. -If \fIexprlist\fR 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. -.TP -.BI set " variable " = " expr" -sets -.I variable -equal to -.IR expr . -Variable can later be -referenced by -.IR $variable . -.TP -.BI 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 \fIendshow\fR 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: -.nf -show - this is some text - from: $sender -endshow -.fi -.TP -.BI while " expr " do " statements " endwhile -Executes \fIstatements\fR until \fIexpr\fR is false. - -.SH PORTS -.PP -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. - -.SH OUTPUT -The output is usually collected in the -.I "output buffer" -and saved until a -.I 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. - -.PP -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 -.RB `` @(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). -.PP -The following output devices are supported: -.TP 5 -stdout -Sends the string to standard output exactly as is. -.TP -stderr -Sends the string to standard error exactly as is. -.TP -plain -Sends the string with all formatting environments removed to standard -output. -.TP -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 -.IR termcap (5)) -for the terminal named by the TERM environment variable. -Supported @ commands are: -.RS 10 -.TP 15 -@roman -Roman (plain) letters (turns off all special modes). -.TP -@b or @bold -Bold letters. If not available, reverse video, else underline. -.TP -@i or @italic -Italic letters (underlining, if available). -.TP -@beep -"bl" termcap entry, else "^G" (beep the terminal); limited to once per -message. -.TP -@l or @left -left aligned -.TP -@c or @center -center aligned -.TP -@r or @right -right aligned -.RE -.IP "" 5 -Other @-commands are silently ignored. -.TP 5 -X -Displays one window per string output to the port. The output is -formatted according to @ commands embedded in the string. Supported -@ commands are: -.RS 10 -.TP 15 -@roman -turns off @italic and @bold -.TP -@b or @bold -turns on boldface -.TP -@i or @italic -turns on italics -.TP -@l or @left -left aligned -.TP -@c or @center -center aligned -.TP -@r or @right -right aligned -.TP -@large -large type size -.TP -@medium -medium type size -.TP -@small -small type size -.TP -@beep -Ring the X bell (limited to once per message) -.TP -@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. -.TP -@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. -.RE -.IP "" 5 -Any other environment name not corresponding to the above environment -names will set the current ``substyle.'' -.IP -The attributes of a given block of text are determined by any active -environments, evaluated in the context of the current style and -substyle. -.IP -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 -.I style -variable. Note that it \fBmust always\fR have exactly two ``.'' -characters in it. -.IP -The substyle is determined by @ commands in the message text. -.IP -Zwgc variables which the X output device reads are: -.RS 10 -.TP 15 -default_X_geometry -default geometry for notices, set from resources -.TP -X_geometry -overrides geometry in resource file, if set -.TP -default_X_background -default background color for notices, set from resources -.TP -X_background -overrides bgcolor in resource file, if set -.TP -style -style, as described above -.RE -.IP "" 5 -The expected geometry values are described below. -.IP -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: -.RS 10 -.TP 10 -zwgc.style.\fIstylenames\fR.geometry -geometry for messages of the specified style -.TP -zwgc.style.\fIstylenames\fR.background -background color for messages of the specified style -.TP -zwgc.style.\fIstylenames\fR.substyle.\fIsubstylename\fR.fontfamily -fontfamily name for the specified style and substyle -.TP -zwgc.style.\fIstylenames\fR.substyle.\fIsubstylename\fR.foreground -foreground color for the specified style and substyle -.TP -zwgc.fontfamily.\fIfontfamilyname\fR.\fIsize\fR.\fIface\fR -specifies the fonts for a given fontfamily. \fIsize\fR is one -of small, medium, or large, and \fIface\fR is one of roman, -bold, italic, or bolditalic. -.RE -.IP "" 5 -The best way to get started in customizing X resources for -.I zwgc -is to examine the default application resources and other users' -resources to understand how they specify the default appearance. - -.SH "X RESOURCES" -Other X resources used by -.I zwgc -are listed below. -Entries like -.sp -.nf -.in +5 -zwgc*option: value -Zwgc*option: value -zwgc.option: value -*option: value -\&.option: value -.in -5 -.fi -.sp -will work. -.PP -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: -.nf -.in +5 -command-line arguments (\-xrm) -contents of file named by XENVIRONMENT environment variable -X server resource database (see \fIxrdb\fR(1)) -application resources file -.in -5 -.fi -.PP -Logical values can be ( Yes On True T ) or ( No Off False nil ). -.TP 15 -\fBOPTION:\fR -\fBMEANING [default]:\fR -.TP -cursorCode -number of a code from the cursorfont (should be an even integer, see -\fI\fR) to use for the windows. -.TP -foreground -Primary foreground color -.TP -Foreground -Secondary foreground color (if foreground not set) [BlackPixel is the default if neither is set] -.TP -background -Primary background color -.TP -Background -Secondary background color (if background not set) [WhitePixel is the -default if neither is set] -.TP -borderColor -Primary border color -.TP -BorderColor -Secondary border color (if borderColor not set) [BlackPixel is the -default if neither is set] -.TP -pointerColor -Primary mouse pointer color [foreground color is the default if not set] -.TP -reverseVideo -(logical) Toggles foreground and background (and border, if it matches -foreground or background). -.TP -ReverseVideo -Secondary toggle, if reverseVideo is not set. [off is the default if -neither is set] -.TP -borderWidth -Primary border width selector -.TP -BorderWidth -Secondary border width selector (if borderWidth is not set) [1 is the -default value if neither is set] -.TP -internalBorder -Primary border between edge and text -.TP -InternalBorder -Secondary selector (if internalBorder not set) [2 is the default value -if neither is set] -.TP -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. -.TP -Geometry -Secondary position specifer. [+0+0 is the default if neither is set.] -.TP -resetSaver -(logical) Primary value to force screen to unsave when a message first -appears. -.TP -ResetSaver -(logical) Secondary value to force screen to unsave. [default True] -.TP -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 -.IR 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. -.TP -ReverseStack -Secondary value to enable reverse stacking. [default False] -.TP -title -(string) Primary window title -.TP -Title -Secondary window title [defaults to the last pathname component -of the program name, usually "zwgc"] -.TP -transient -(logical) Primary value which determines if zephyrgram windows will be -created with the \fBWM_TRANSIENT_FOR\fR property set. If this -resource is true, the property will be set, telling certain -windowmanagers to treat zephyrgram windows specially. For instance, -\fItwm\fR will not put decorations on transient windows, \fImwm\fR -will not let you iconify them, and \fIuwm\fR ignores the resource -entirely. -.TP -Transient -Secondary transient determining value [default False] -.TP -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), -.I zwgc -sets the \fB_NET_WM_DESKTOP\fR property to 0xFFFFFFFF for each zephyrgram -window, indicating that it should appear on all desktops. -.TP -AllDesktops -Secondary value determining whether zephyrgram windows should appear -on all desktops. -.TP -scrollDelete -(logical) If true, scrolling over a zgram will cause it -to be deleted -.TP -ScrollDelete -Secondary value to enable deletion of a zgram by scrolling over it -[default False] -.TP -enableDelete -(logical) If true, zwgc creates a WM_PROTOCOLS property on all zgrams, with -WM_DELETE_WINDOW as contents. -.TP -EnableDelete -Secondary value to enable WM_DELETE_WINDOW protocol on zgrams [default False] -.TP -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. -.TP -MinTimeToLive -Secondary value of ``minimum time to live.'' -.TP -iconName -(string) Primary icon name -.TP -IconName -Secondary icon name [defaults to the last pathname component -of the program name, usually "zwgc"] -.TP -name -(string) Primary window class name -.TP -name -Secondary window class name [defaults to the last pathname component -of the program name, usually "zwgc"] -.TP -synchronous -(logical) Primary X synchronous mode specifier. On means to put the X -library into synchronous mode. -.TP -Synchronous -Secondary X synchronous mode specifier. [default is `off'] -.PP -The window class is always "Zwgc". -.SH X BUTTONS -.PP -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. -.PP -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. -.PP -.B WARNING: -If you do this with too many WindowGrams under the mouse, it is -possible for your subscriptions to be lost. If \fIzctl retrieve\fR -returns nothing, then issue a \fIzctl load\fR command to re-subscribe -to your default set of subscriptions. If you use znol, then \fIznol -\-q &\fR will restore the subscriptions you need for \fIznol\fR. -.PP -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. - -.SH ADDITIONAL X FEATURES -If -.I zwgc -receives a WM_DELETE_WINDOW, it destroys the zephyrgram as if it were -clicked on. -.PP -If a zephyrgram is unmapped, it is removed from the stacking order -used by reverseStack. - -.SH COMMAND LINE -.I zwgc -is normally invoked from -.IR /usr/athena/lib/init/login , -.IR $HOME/.xsession , -or -.I /usr/athena/lib/init/xsession -in the foreground. When it has successfully set your location and -obtained subscriptions, it will put itself into the background (unless -the \-nofork option has been specified). At this point it is safe to -invoke additional zephyr commands, such as -.IR znol (1). -(You can also put these commands in the -.I initprogs -Zephyr variable; the value of this variable is passed as the argument to -the -.IR system (3) -library call during initialization.) -.I 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 -.I fallback -was set to ``false''. If -.I fallback -is set to ``true'', -.I zwgc -will fall back to ``ttymode'' (making the tty driver the default output -device) if it can't open the X display. If -.I fallback -is not set and the display cannot be opened, -.I zwgc -prints an explanatory message and exits with a status of 1. -.PP -If the -.I \-ttymode -option is specified, -.I zwgc -will ignore any X display and use the terminal as its primary output -device. This flag overrides any setting of the fallback variable. -.PP -If the -.I \-loc -option is specified, -.I 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. -.PP -The -.I \-reenter -option is provided for compatibility with the previous version of -.IR zwgc . -.PP -.I zwgc -will exit cleanly (unset location and cancel subscriptions) on: -.nf - SIGTERM - SIGHUP - XIOError (with a message to stderr) -.fi -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 -.I zwgc -nofork & -.PP -If -.I zwgc -receives a SIGUSR1, it will rewrite the file used to store the -WindowGram port number ($WGFILE or /tmp/wg.\fIuid\fR), in the event -that the file has been lost. -.SH CONTROL MESSAGES -In order to allow some special user controls over the behavior of -.IR zwgc , -certain Zephyr control notices can be sent directly to -.I zwgc -using the -.IR zctl (1) -program. Currently implemented controls are -.TP 15 -wg_read -tell -.I zwgc -to re-read the current description file. -.TP -wg_shutdown -tell -.I zwgc -to cancel all subscriptions and stop acting on incoming notices. -.I zwgc -saves the subscriptions that were in effect at the time of the shutdown -so that it can restore them later if needed. -.TP -wg_startup -tell -.I zwgc -to restart from being shutdown and reinstall the saved subscriptions. -.PP -Other control messages may be implemented in the future. - -.SH EXAMPLES -For an example of a description file, see -.IR /usr/athena/share/zephyr/zwgc.desc . -For an example of X resources, see -.IR /usr/athena/share/zephyr/zwgc_resources . - -.SH BUGS -The X selection code can highlight the wrong portions of messages -containing formatted text placed with the @center() or @right() -directives. -.PP -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''.) -.SH FILES -.TP 15 -$HOME/.zwgc.desc -Default location of user's description file -.TP -/usr/athena/share/zephyr/zwgc.desc -System-wide description file -.TP -/usr/athena/share/zephyr/zwgc_resources -Default X application resources. -.TP -$ZEPHYR_VARS or $HOME/.zephyr.vars -File containing variable definitions -.TP -$HOME/.zephyr.subs -Supplementary subscription file -.TP -$HOME/.Xresources -Standard X resources file -.TP -$WGFILE or /tmp/wg.\fIuid\fR -File used to store WindowGram port number for other clients -.SH 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) -.br -Project Athena Technical Plan Section E.4.1, `Zephyr Notification Service' -.SH AUTHORS -.nf -John Carr (MIT/Project Athena) -Marc Horowitz (MIT/Project Athena) -Mark Lillibridge (MIT/Project Athena) -.fi -.SH RESTRICTIONS -Copyright (c) 1989 by the Massachusetts Institute of Technology. -All Rights Reserved. -.br -.I zephyr(1) -specifies the terms and conditions for redistribution. diff --git a/zwgc/zwgc.1.in b/zwgc/zwgc.1.in new file mode 100644 index 0000000..88a7ba4 --- /dev/null +++ b/zwgc/zwgc.1.in @@ -0,0 +1,1067 @@ +.\" $Id$ +.\" # end of TP (cf }N below) +.\" # copied here, since we use @ in some of our tags, and that +.\" # messes up \w and \h +.de }1 +.ds ]X \&\\*(]B\\ +.nr )E 0 +.if !"\\$1"" .nr )I \\$1n +.}f +.ll \\n(LLu +.in \\n()Ru+\\n(INu+\\n()Iu +.ti \\n(INu +.ie !\\n()Iu+\\n()Ru-\w'\\*(]X'u-3p \{\\*(]X +.br\} +.el \\*(]X\h@|\\n()Iu+\\n()Ru@\c +.}f +.. +.de }N +.if \\n()E .br +.di +.if "\\n()E"0" .}f +.if "\\n()E"1" .}1 +.if "\\n()E"2" .}2 +.nr )E 0 +.. +.\" # tagged paragraph (paragraph with hanging label, but no para spacing) +.de TQ +.if !"\\$1"" .nr )I \\$1n +.ne 1.1v +.in \\n()Ru +.nr )E 1 +.ns +.it 1 }N +.di ]B +.. +.TH ZWGC 1 "November 30, 1989" "MIT Project Athena" +.SH NAME +zwgc \- Zephyr Windowgram Client program +.SH SYNOPSIS +.B zwgc +[ \-reenter ] [ \-nofork ] [ \-ttymode ] [ \-f +.I filename +] [ \-subfile +.I filename +] [ \-loc +.I text +] [ \-default +.I portname +] [ \-disable +.I portname +] ... [ output driver options ] +[ X Toolkit options... ] +.SH DESCRIPTION +.I Zwgc +is the main +.I 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. + +.SS "Selection of Zephyr Notices" +.PP +.I 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 +.IR zctl (1). +The user's subscription file defaults to +.IR $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. + +.PP +The +.I zctl +command is used to manipulate and change subscriptions. See the +.IR zctl (1) +man page for details. + +.SS "Zephyr Description Files" +.PP +.I Zwgc +formats its output messages according to the commands in its +description file. The user's description file +.RI ( $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. +.PP +Every time a notice is received, +.I zwgc +runs through the description file, and executes the appropriate commands. + +.SS "Zephyr Description File Syntax" +.PP +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 */"). + +.SH "DESCRIPTION LANGUAGE" +.SS 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. +.PP +String literals are specified by putting the contents in "double quotes". +.PP +Variables are set using the +.B set +command (see "COMMANDS", below). They are +referenced in an expression by using the form +.IR $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. +.PP +Functions are called using a C-like syntax, +\fBfname\fR(\fIexpr1\fR,\fIexpr2\fR), where +.B fname +is the +function name and +.IB expr n +are the arguments. +.PP +Binary operators use infix notation, such as "a == b". +.PP +Some commands use an expression list (exprlist), which is simply a set +of expressions separated by whitespace (e.g. $var1 "lit1" $var2). + +.SS "Default variables" +.PP +The following variables are always available: +.TP 5 +.B 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. +.TP 5 +.B 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 +.IR kinit (1) +but has not run ``zctl sub'' to +register this change with the Zephyr servers. +.TP +.B class +The class of the current notice. +.TP +.B date +The date on which the notice was sent. +.TP +.B default +The default output format for the current notice +.TP +.B error +An error message from the port read/write commands. +.TP +.B fromhost +The full name of the host from which the notice appears to have been +sent. +.I This is not fully reliable, +as the information used to determine this hostname is not guaranteed to +be correct (even for authentic messages). +.TP +.B fullsender +The notice sender's name, including the zephyr realm name. +.TP +.B instance +The instance of the current notice. +.TP +.B kind +The kind of notice. +.TP +.B message +The full text of the message, with nulls converted to newlines. +.TP +.B number_of_fields +The number of fields in the message (a string representation of a +decimal number). +.TP +.B opcode +The opcode of the current notice. +.TP +.B output_driver +The name of the output driver in use. +.TP +.B port +The port from which the notice was sent. +.TP +.B realm +The local zephyr realm. +.TP +.B recipient +The recipient for the current notice. If the notice is a multicast +(sent to several people), the recipient is set to ``*''. +.TP +.B sender +Usually a shortened version of fullsender. If the realm of the sender +is equal to the realm of the recipient, +.I sender +omits the realm name. +.TP +.B time +The time of day at which the notice was sent. +.TP +.B user +The full zephyr name of the user (e.g. marc@ATHENA.MIT.EDU). +.TP +.B version +The current version of +.IR zwgc . +.TP +.B zephyr_version +The protocol version of the notice. +.PP +All of these variables (except for error, output_driver, and version) +are re-set before each notice is processed. + +.SS Functions +.PP +Following is a list of functions available for use in the description +file. +.TP 5 +.BI buffer () +The contents of the current output buffer. +.TP +.BI downcase (expr) +Returns the value of \fIexpr\fR, converted to lower case. +.TP +.BI get (expr) +Returns a line from the port named \fIexpr\fR. 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. +.TP +.BI getenv (expr) +Returns the value of the environment variable \fIexpr\fR, or the empty +string if it does not exist. + +.TP +.BI lany "(expr1, expr2), " rany "(expr1, expr2)" +Return a number of characters equal to the length of +.I expr2 +from the beginning +.RB ( lany ) +or end +.RB ( rany ) +of +.I expr1 +(e.g. lany("1234567890","foo") would return "123"). +If +.I expr1 +is a variable reference, the variable +is modified to remove the characters returned. +If +.I expr2 +is longer than +.IR expr1 , +the value of +.I expr1 +is returned (and +.I expr1 +is set to "", if a variable). +.TP +.BI lbreak "(expr1, expr2), " rbreak "(expr1, expr2)" +.I Expr2 +defines a set of characters. The function returns the longest +initial +.RB ( lbreak ) +or final +.RB ( rbreak ) +string from +.I expr1 +composed of characters +.I not +in this set (e.g. lbreak("characters", "tuv") would return "charac"). If +.I expr1 +is a variable reference, the variable +is modified to remove the characters returned. If no characters +in +.IR expr2 " are in " "expr1, " then " expr1 " +is returned (and +.I expr1 +is set to "", if a variable). +.TP +.BI lspan "(expr1, expr2), " rspan "(expr1, expr2)" +These functions are the negation of the +.B break +functions; the returned string consists of characters +.I in +the set defined by +.I expr2 +.TP +.BI protect (expr) +Returns a string which will be evaluated identically to \fIexpr\fR, +but will not affect any surrounding environments. That is, any +characters which could close outside environments are quoted, and any +environments in \fIexpr\fR which are not closed at the end are closed. +.TP +.BI substitute (expr) +Evaluates variable references of the form \fI$variable\fR in expr and +converts $$ to $. +.TP +.BI upcase (expr) +Returns the value of \fIexpr\fR, converted to upper case. +.TP +.BI verbatim (expr) +Returns a string that will be displayed exactly as \fIexpr\fR looks. +Anything which could be mistaken for an environment is quoted. +.TP +.BI stylestrip (expr) +Returns \fIexpr\fR with all environments stripped out. +.TP +.BI zvar (expr) +Returns the value of the zephyr variable \fIexpr\fR, +or the empty +string if it does not exist. [Zephyr variables +can be set and examined with +.IR zctl (1).] + +.SS Operators +.PP +Following is a list of operators which can be used in the description +file to compose expressions: +.TP +.IB expr1 " + " expr2 +String concatenation of +.IR expr1 " and " expr2 +.TP +.IB expr1 " == " expr2 +True if the two expressions are equal, false otherwise. +.TP +.IB expr1 " =~ " expr2 +True if the regular expression pattern +.IR expr2 " matches " expr1. +.TP +.IB expr1 " !~ " expr2 +Negation of "=~". +.TP +.IB expr1 " != " expr2 +Negation of "==" +.TP +\fIexpr1\fB and \fIexpr2\fR, \fIexpr1\fB & \fIexpr2\fR +True if +.IR expr1 " and " expr2 +are both true. +.TP +\fIexpr1\fB or \fIexpr2\fR, \fIexpr1\fB | \fIexpr2\fR +True if either of +.IR expr1 " or " expr2 +are true. +.TP +\fB! \fIexpr1\fR, \fBnot \fIexpr1\fR +The logical negation of +.I expr1. + +.SS Commands +.PP +Following is a list of the commands usable in the description +language: +.TP 5 +.BI appendport " expr1 expr2" +Creates a port called \fIexpr1\fR. All output to the port will be +appended to the file \fIexpr2\fR. There is no input. If the file is +created, its mode is set to read-write, owner only (no access for others). +.TP +.B break +Exits the innermost if, case, or while block. +.TP +\fBcase \fIexpr1\fR [ ((\fBmatch \fIexpr\fR [,\fIexpr ...\fR]) | \fBdefault\fR)\fI commands \fR] ... \fBendcase\fR +Evaluates \fIexpr1\fR. Then, each of the match expressions is +evaluated in order. The first time an expression matches \fIexpr1\fR, +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. +.TP +.B clearbuf +Clears the output buffer (see below for details on buffering). +.TP +.BI closeinput " expr" +Closes the file associated with \fIexpr\fR. +.TP +.BI closeoutput " expr" +Sends an EOF (end-of-file) to the process if \fIexpr\fR was a port created by +execport, or closes the file if it was created by outputport or +appendport. +.TP +.BI closeport " expr" +Closes both input and output of \fIexpr\fR as defined above. +.TP +.BI 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. +.TP +.BI exec " exprlist" +Executes a program without any input or output. A command named by +\fIexprlist\fR 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). +.TP +.BI execport " expr1 exprlist" +Creates a port called \fIexpr1\fR. A command named by \fIexprlist\fR +is executed, as described above for \fBexec\fR. +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. +.TP +.B exit +Completes processing of the current notice. The remainder of the +description file is ignored after execution of this command. +.\" hack because the following line otherwise breaks because it is too long. +.TP +\fBif \fIexpr1 \fBthen \fIcommands1\fR [\fBelseif \fIexpr2 \fBthen \fIcommands2\fR] ... [\fBelse \fIcommandsn\fR] \fBendif\fR +If \fIexpr1\fR evaluates to true, execute \fIcommands1\fI, etc. [A conditional +construct, similar to the constructs in the C shell (csh).] +.TP +.BI inputport " expr1 expr2" +Creates a port called \fIexpr1\fR. All input from the port comes from +the file \fIexpr2\fR. There is no output. +.TP +.B noop +does nothing +.TP +.BI outputport " expr1 expr2" +Creates a port called \fIexpr1\fR. The file \fIexpr2\fR will be +truncated, or created if it does not exist. All output to the port +will be appended to the file \fIexpr2\fR. There is no input. If the file is +created, its mode is set to read-write, owner only (no access for others). +.TP +.BI 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. +.TP +.B put \fR[\fIexpr \fR[\fIexprlist\fR]] +Sends data to a port. If \fIexpr\fR is provided, then it is used as the +port, otherwise the port used is the +port corresponding to the default output device. +If \fIexprlist\fR 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. +.TP +.BI set " variable " = " expr" +sets +.I variable +equal to +.IR expr . +Variable can later be +referenced by +.IR $variable . +.TP +.BI 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 \fIendshow\fR 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: +.nf +show + this is some text + from: $sender +endshow +.fi +.TP +.BI while " expr " do " statements " endwhile +Executes \fIstatements\fR until \fIexpr\fR is false. + +.SH PORTS +.PP +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. + +.SH OUTPUT +The output is usually collected in the +.I "output buffer" +and saved until a +.I 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. + +.PP +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 +.RB `` @(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). +.PP +The following output devices are supported: +.TP 5 +stdout +Sends the string to standard output exactly as is. +.TP +stderr +Sends the string to standard error exactly as is. +.TP +plain +Sends the string with all formatting environments removed to standard +output. +.TP +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 +.IR termcap (5)) +for the terminal named by the TERM environment variable. +Supported @ commands are: +.RS 10 +.TP 15 +@roman +Roman (plain) letters (turns off all special modes). +.TP +@b or @bold +Bold letters. If not available, reverse video, else underline. +.TP +@i or @italic +Italic letters (underlining, if available). +.TP +@beep +"bl" termcap entry, else "^G" (beep the terminal); limited to once per +message. +.TP +@l or @left +left aligned +.TP +@c or @center +center aligned +.TP +@r or @right +right aligned +.RE +.IP "" 5 +Other @-commands are silently ignored. +.TP 5 +X +Displays one window per string output to the port. The output is +formatted according to @ commands embedded in the string. Supported +@ commands are: +.RS 10 +.TP 15 +@roman +turns off @italic and @bold +.TP +@b or @bold +turns on boldface +.TP +@i or @italic +turns on italics +.TP +@l or @left +left aligned +.TP +@c or @center +center aligned +.TP +@r or @right +right aligned +.TP +@large +large type size +.TP +@medium +medium type size +.TP +@small +small type size +.TP +@beep +Ring the X bell (limited to once per message) +.TP +@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. +.TP +@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. +.RE +.IP "" 5 +Any other environment name not corresponding to the above environment +names will set the current ``substyle.'' +.IP +The attributes of a given block of text are determined by any active +environments, evaluated in the context of the current style and +substyle. +.IP +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 +.I style +variable. Note that it \fBmust always\fR have exactly two ``.'' +characters in it. +.IP +The substyle is determined by @ commands in the message text. +.IP +Zwgc variables which the X output device reads are: +.RS 10 +.TP 15 +default_X_geometry +default geometry for notices, set from resources +.TP +X_geometry +overrides geometry in resource file, if set +.TP +default_X_background +default background color for notices, set from resources +.TP +X_background +overrides bgcolor in resource file, if set +.TP +style +style, as described above +.RE +.IP "" 5 +The expected geometry values are described below. +.IP +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: +.RS 10 +.TP 10 +zwgc.style.\fIstylenames\fR.geometry +geometry for messages of the specified style +.TP +zwgc.style.\fIstylenames\fR.background +background color for messages of the specified style +.TP +zwgc.style.\fIstylenames\fR.substyle.\fIsubstylename\fR.fontfamily +fontfamily name for the specified style and substyle +.TP +zwgc.style.\fIstylenames\fR.substyle.\fIsubstylename\fR.foreground +foreground color for the specified style and substyle +.TP +zwgc.fontfamily.\fIfontfamilyname\fR.\fIsize\fR.\fIface\fR +specifies the fonts for a given fontfamily. \fIsize\fR is one +of small, medium, or large, and \fIface\fR is one of roman, +bold, italic, or bolditalic. +.RE +.IP "" 5 +The best way to get started in customizing X resources for +.I zwgc +is to examine the default application resources and other users' +resources to understand how they specify the default appearance. + +.SH "X RESOURCES" +Other X resources used by +.I zwgc +are listed below. +Entries like +.sp +.nf +.in +5 +zwgc*option: value +Zwgc*option: value +zwgc.option: value +*option: value +\&.option: value +.in -5 +.fi +.sp +will work. +.PP +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: +.nf +.in +5 +command-line arguments (\-xrm) +contents of file named by XENVIRONMENT environment variable +X server resource database (see \fIxrdb\fR(1)) +application resources file +.in -5 +.fi +.PP +Logical values can be ( Yes On True T ) or ( No Off False nil ). +.TP 15 +\fBOPTION:\fR +\fBMEANING [default]:\fR +.TP +cursorCode +number of a code from the cursorfont (should be an even integer, see +\fI\fR) to use for the windows. +.TP +foreground +Primary foreground color +.TP +Foreground +Secondary foreground color (if foreground not set) [BlackPixel is the default if neither is set] +.TP +background +Primary background color +.TP +Background +Secondary background color (if background not set) [WhitePixel is the +default if neither is set] +.TP +borderColor +Primary border color +.TP +BorderColor +Secondary border color (if borderColor not set) [BlackPixel is the +default if neither is set] +.TP +pointerColor +Primary mouse pointer color [foreground color is the default if not set] +.TP +reverseVideo +(logical) Toggles foreground and background (and border, if it matches +foreground or background). +.TP +ReverseVideo +Secondary toggle, if reverseVideo is not set. [off is the default if +neither is set] +.TP +borderWidth +Primary border width selector +.TP +BorderWidth +Secondary border width selector (if borderWidth is not set) [1 is the +default value if neither is set] +.TP +internalBorder +Primary border between edge and text +.TP +InternalBorder +Secondary selector (if internalBorder not set) [2 is the default value +if neither is set] +.TP +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. +.TP +Geometry +Secondary position specifer. [+0+0 is the default if neither is set.] +.TP +resetSaver +(logical) Primary value to force screen to unsave when a message first +appears. +.TP +ResetSaver +(logical) Secondary value to force screen to unsave. [default True] +.TP +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 +.IR 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. +.TP +ReverseStack +Secondary value to enable reverse stacking. [default False] +.TP +title +(string) Primary window title +.TP +Title +Secondary window title [defaults to the last pathname component +of the program name, usually "zwgc"] +.TP +transient +(logical) Primary value which determines if zephyrgram windows will be +created with the \fBWM_TRANSIENT_FOR\fR property set. If this +resource is true, the property will be set, telling certain +windowmanagers to treat zephyrgram windows specially. For instance, +\fItwm\fR will not put decorations on transient windows, \fImwm\fR +will not let you iconify them, and \fIuwm\fR ignores the resource +entirely. +.TP +Transient +Secondary transient determining value [default False] +.TP +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), +.I zwgc +sets the \fB_NET_WM_DESKTOP\fR property to 0xFFFFFFFF for each zephyrgram +window, indicating that it should appear on all desktops. +.TP +AllDesktops +Secondary value determining whether zephyrgram windows should appear +on all desktops. +.TP +scrollDelete +(logical) If true, scrolling over a zgram will cause it +to be deleted +.TP +ScrollDelete +Secondary value to enable deletion of a zgram by scrolling over it +[default False] +.TP +enableDelete +(logical) If true, zwgc creates a WM_PROTOCOLS property on all zgrams, with +WM_DELETE_WINDOW as contents. +.TP +EnableDelete +Secondary value to enable WM_DELETE_WINDOW protocol on zgrams [default False] +.TP +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. +.TP +MinTimeToLive +Secondary value of ``minimum time to live.'' +.TP +iconName +(string) Primary icon name +.TP +IconName +Secondary icon name [defaults to the last pathname component +of the program name, usually "zwgc"] +.TP +name +(string) Primary window class name +.TP +name +Secondary window class name [defaults to the last pathname component +of the program name, usually "zwgc"] +.TP +synchronous +(logical) Primary X synchronous mode specifier. On means to put the X +library into synchronous mode. +.TP +Synchronous +Secondary X synchronous mode specifier. [default is `off'] +.PP +The window class is always "Zwgc". +.SH X BUTTONS +.PP +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. +.PP +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. +.PP +.B WARNING: +If you do this with too many WindowGrams under the mouse, it is +possible for your subscriptions to be lost. If \fIzctl retrieve\fR +returns nothing, then issue a \fIzctl load\fR command to re-subscribe +to your default set of subscriptions. If you use znol, then \fIznol +\-q &\fR will restore the subscriptions you need for \fIznol\fR. +.PP +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. + +.SH ADDITIONAL X FEATURES +If +.I zwgc +receives a WM_DELETE_WINDOW, it destroys the zephyrgram as if it were +clicked on. +.PP +If a zephyrgram is unmapped, it is removed from the stacking order +used by reverseStack. + +.SH COMMAND LINE +.I zwgc +is normally invoked from +.IR $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 +.IR znol (1). +(You can also put these commands in the +.I initprogs +Zephyr variable; the value of this variable is passed as the argument to +the +.IR system (3) +library call during initialization.) +.I 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 +.I fallback +was set to ``false''. If +.I fallback +is set to ``true'', +.I zwgc +will fall back to ``ttymode'' (making the tty driver the default output +device) if it can't open the X display. If +.I fallback +is not set and the display cannot be opened, +.I zwgc +prints an explanatory message and exits with a status of 1. +.PP +If the +.I \-ttymode +option is specified, +.I zwgc +will ignore any X display and use the terminal as its primary output +device. This flag overrides any setting of the fallback variable. +.PP +If the +.I \-loc +option is specified, +.I 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. +.PP +The +.I \-reenter +option is provided for compatibility with the previous version of +.IR zwgc . +.PP +.I zwgc +will exit cleanly (unset location and cancel subscriptions) on: +.nf + SIGTERM + SIGHUP + XIOError (with a message to stderr) +.fi +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 +.I zwgc -nofork & +.PP +If +.I zwgc +receives a SIGUSR1, it will rewrite the file used to store the +WindowGram port number ($WGFILE or /tmp/wg.\fIuid\fR), in the event +that the file has been lost. +.SH CONTROL MESSAGES +In order to allow some special user controls over the behavior of +.IR zwgc , +certain Zephyr control notices can be sent directly to +.I zwgc +using the +.IR zctl (1) +program. Currently implemented controls are +.TP 15 +wg_read +tell +.I zwgc +to re-read the current description file. +.TP +wg_shutdown +tell +.I zwgc +to cancel all subscriptions and stop acting on incoming notices. +.I zwgc +saves the subscriptions that were in effect at the time of the shutdown +so that it can restore them later if needed. +.TP +wg_startup +tell +.I zwgc +to restart from being shutdown and reinstall the saved subscriptions. +.PP +Other control messages may be implemented in the future. + +.SH EXAMPLES +For an example of a description file, see +.IR @datadir@/zephyr/zwgc.desc . +For an example of X resources, see +.IR @datadir@/zephyr/zwgc_resources . + +.SH BUGS +The X selection code can highlight the wrong portions of messages +containing formatted text placed with the @center() or @right() +directives. +.PP +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''.) +.SH FILES +.TP 15 +$HOME/.zwgc.desc +Default location of user's description file +.TP +@datadir@/zephyr/zwgc.desc +System-wide description file +.TP +@datadir@/zephyr/zwgc_resources +Default X application resources. +.TP +$ZEPHYR_VARS or $HOME/.zephyr.vars +File containing variable definitions +.TP +$HOME/.zephyr.subs +Supplementary subscription file +.TP +$HOME/.Xresources +Standard X resources file +.TP +$WGFILE or /tmp/wg.\fIuid\fR +File used to store WindowGram port number for other clients +.SH 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) +.br +Project Athena Technical Plan Section E.4.1, `Zephyr Notification Service' +.SH AUTHORS +.nf +John Carr (MIT/Project Athena) +Marc Horowitz (MIT/Project Athena) +Mark Lillibridge (MIT/Project Athena) +.fi +.SH RESTRICTIONS +Copyright (c) 1989 by the Massachusetts Institute of Technology. +All Rights Reserved. +.br +.I zephyr(1) +specifies the terms and conditions for redistribution. -- cgit v1.2.3