.. zsh-module-meta::
   :name: zsh/watch
   :summary: Reporting of login and logout events.

The ``zsh/watch`` module can be used to report when specific users log in or
out. This is controlled via the following parameters.

.. index:: single: LOGCHECK; Variable

``LOGCHECK``
    
    The interval in seconds between checks for login/logout activity
    using the ``watch`` parameter.
    

.. index:: single: watch; Variable

.. index:: single: WATCH; Variable

``watch`` <S> <Z> (``WATCH`` <S>)
    
    An array (colon-separated list) of login/logout events to report.
    
    If it contains the single word ``all``, then all login/logout events
    are reported.  If it contains the single word ``notme``, then all
    events are reported as with ``all`` except ``$USERNAME``.
    
    An entry in this list may consist of a username,
    an ``@`` followed by a remote hostname,
    and a ``%`` followed by a line (tty).  Any of these may
    be a pattern (be sure to quote this during the assignment to
    ``watch`` so that it does not immediately perform file generation);
    the setting of the ``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 ``EXTENDED_GLOB`` option set, the following:
    
    
    .. code-block:: zsh
       :class: example

        watch=('^(pws|barts)')
    
    
    causes reports for activity associated with any user other than ``pws``
    or ``barts``.
    

.. index:: single: WATCHFMT; Variable

``WATCHFMT``
    
    The format of login/logout reports if the ``watch`` parameter is set.
    Default is ``%n has %a %l from %m``.
    Recognizes the following escape sequences, many of which are described
    further in :zshsectref:`Simple Prompt Escapes <zshmisc>`:
    
    
    ``%n``
        
        The name of the user that logged in/out.
        
    
    ``%a``
        
        The observed action, i.e. "logged on" or "logged off".
        
    
    ``%l``
        
        The line (tty) the user is logged in on.
        
    
    ``%M``
        
        The full hostname of the remote host.
        
    
    ``%m``
        
        The hostname up to the first ``.``.  If only the
        IP address is available or the utmp field contains
        the name of an X-windows display, the whole name is printed.
        
        :emphasis:`NOTE:`
        The ``%m`` and ``%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.
        
    
    ``%F{``:var:`color`\ ``}`` (``%f``)
        
        Start (stop) using a different foreground color.
        
    
    ``%K{``:var:`color`\ ``}`` (``%k``)
        
        Start (stop) using a different background color.
        
    
    ``%H{``:var:`group`\ ``}``
        
        Change all character visual attributes using a highlighting
        specification from the ``.zle.hlgroups`` associative array.
        
    
    ``%S`` (``%s``)
        
        Start (stop) standout mode.
        
    
    ``%U`` (``%u``)
        
        Start (stop) underline mode.
        
    
    ``%B`` (``%b``)
        
        Start (stop) boldface mode.
        
    
    ``%t``
    
    ``%@``
        
        The time, in 12-hour, am/pm format.
        
    
    ``%T``
        
        The time, in 24-hour format.
        
    
    ``%w``
        
        The date in :var:`day`\ ``-``:var:`dd` format.
        
    
    ``%W``
        
        The date in :var:`mm`\ ``/``:var:`dd`\ ``/``:var:`yy` format.
        
    
    ``%D``
        
        The date in :var:`yy`\ ``-``:var:`mm`\ ``-``:var:`dd` format.
        
    
    ``%D{``:var:`string`\ ``}``
        
        The date formatted as :var:`string` using the ``strftime`` function, with
        zsh extensions as described for ``%D{``:var:`string`\ ``}`` escape sequence in
        :zshsectref:`Simple Prompt Escapes <zshmisc>`.
    
    ``%(``:var:`x`\ ``:``:var:`true-text`\ ``:``:var:`false-text`\ ``)``
        
        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 ``l``, ``n``, ``m``
        or ``M``, which indicate a \`true' result if the corresponding
        escape sequence would return a non-empty value; or it may be ``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.
        
    
    
    

Furthermore, the ``zsh/watch`` module makes available one builtin
command:

.. index:: single: log; Function

.. index:: single: watch, use of; Variable

.. index:: single: watching users; Command

.. index:: single: users, watching; Command

``log``
    
    List all users currently logged in who are affected by
    the current setting of the ``watch`` parameter.
    

