From 271cfc685b17938e67a8212f2df78c32989411d7 Mon Sep 17 00:00:00 2001 From: Oliver Kiddle Date: Tue, 2 Nov 2021 21:39:52 +0100 Subject: 49534, 49539: separate watch/log functionality out into a module --- Doc/Zsh/mod_watch.yo | 140 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 140 insertions(+) create mode 100644 Doc/Zsh/mod_watch.yo (limited to 'Doc/Zsh/mod_watch.yo') diff --git a/Doc/Zsh/mod_watch.yo b/Doc/Zsh/mod_watch.yo new file mode 100644 index 000000000..4eea89e23 --- /dev/null +++ b/Doc/Zsh/mod_watch.yo @@ -0,0 +1,140 @@ +COMMENT(!MOD!zsh/watch +Reporting of login and logout events. +!MOD!) +The tt(zsh/watch) module can be used to report when specific users log in or +out. This is controlled via the following parameters. + +startitem() +vindex(LOGCHECK) +item(tt(LOGCHECK))( +The interval in seconds between checks for login/logout activity +using the tt(watch) parameter. +) +vindex(watch) +vindex(WATCH) +item(tt(watch) (tt(WATCH) ))( +An array (colon-separated list) of login/logout events to report. + +If it contains the single word `tt(all)', then all login/logout events +are reported. If it contains the single word `tt(notme)', then all +events are reported as with `tt(all)' except tt($USERNAME). + +An entry in this list may consist of a username, +an `tt(@)' followed by a remote hostname, +and a `tt(%)' followed by a line (tty). Any of these may +be a pattern (be sure to quote this during the assignment to +tt(watch) so that it does not immediately perform file generation); +the setting of the tt(EXTENDED_GLOB) option is respected. +Any or all of these components may be present in an entry; +if a login/logout event matches all of them, +it is reported. + +For example, with the tt(EXTENDED_GLOB) option set, the following: + +example(watch=('^(pws|barts)')) + +causes reports for activity associated with any user other than tt(pws) +or tt(barts). +) +vindex(WATCHFMT) +item(tt(WATCHFMT))( +The format of login/logout reports if the tt(watch) parameter is set. +Default is `tt(%n has %a %l from %m)'. +Recognizes the following escape sequences: + +startitem() +item(tt(%n))( +The name of the user that logged in/out. +) +item(tt(%a))( +The observed action, i.e. "logged on" or "logged off". +) +item(tt(%l))( +The line (tty) the user is logged in on. +) +item(tt(%M))( +The full hostname of the remote host. +) +item(tt(%m))( +The hostname up to the first `tt(.)'. If only the +IP address is available or the utmp field contains +the name of an X-windows display, the whole name is printed. + +em(NOTE:) +The `tt(%m)' and `tt(%M)' escapes will work only if there is a host name +field in the utmp on your machine. Otherwise they are +treated as ordinary strings. +) +item(tt(%S) LPAR()tt(%s)RPAR())( +Start (stop) standout mode. +) +item(tt(%U) LPAR()tt(%u)RPAR())( +Start (stop) underline mode. +) +item(tt(%B) LPAR()tt(%b)RPAR())( +Start (stop) boldface mode. +) +xitem(tt(%t)) +item(tt(%@))( +The time, in 12-hour, am/pm format. +) +item(tt(%T))( +The time, in 24-hour format. +) +item(tt(%w))( +The date in `var(day)tt(-)var(dd)' format. +) +item(tt(%W))( +The date in `var(mm)tt(/)var(dd)tt(/)var(yy)' format. +) +item(tt(%D))( +The date in `var(yy)tt(-)var(mm)tt(-)var(dd)' format. +) +item(tt(%D{)var(string)tt(}))( +The date formatted as var(string) using the tt(strftime) function, with +zsh extensions as described by +ifzman(EXPANSION OF PROMPT SEQUENCES in zmanref(zshmisc))\ +ifnzman(noderef(Prompt Expansion)). +) +item(tt(%LPAR())var(x)tt(:)var(true-text)tt(:)var(false-text)tt(RPAR()))( +Specifies a ternary expression. +The character following the var(x) is +arbitrary; the same character is used to separate the text +for the "true" result from that for the "false" result. +Both the separator and the right parenthesis may be escaped +with a backslash. +Ternary expressions may be nested. + +The test character var(x) may be any one of `tt(l)', `tt(n)', `tt(m)' +or `tt(M)', which indicate a `true' result if the corresponding +escape sequence would return a non-empty value; or it may be `tt(a)', +which indicates a `true' result if the watched user has logged in, +or `false' if he has logged out. +Other characters evaluate to neither true nor false; the entire +expression is omitted in this case. + +If the result is `true', then the var(true-text) +is formatted according to the rules above and printed, +and the var(false-text) is skipped. +If `false', the var(true-text) is skipped and the var(false-text) +is formatted and printed. +Either or both of the branches may be empty, but +both separators must be present in any case. +) +enditem() +) +enditem() + +Furthermore, the tt(zsh/watch) module makes available one builtin +command: + +startitem() +findex(log) +vindex(watch, use of) +cindex(watching users) +cindex(users, watching) +item(tt(log))( +List all users currently logged in who are affected by +the current setting of the tt(watch) parameter. +) +enditem() -- cgit 1.4.1