freebsd-dev/usr.sbin/watch/watch.8

.\"
.\" $FreeBSD$
.\"
.Dd November 24, 2001
.Dt WATCH 8
.Os
.Sh NAME
.Nm watch
.Nd snoop on another tty line
.Sh SYNOPSIS
.Nm
.Op Fl cinotW
.Op Fl f Ar snpdev
.Op Ar tty
.Sh DESCRIPTION
The
.Nm
utility allows the user to examine all data coming through a specified tty
using the
.Xr snp 4
device.
If the
.Xr snp 4
device is not available,
.Nm
will attempt to load the module
.Pq Nm snp .
The
.Nm
utility writes to standard output.
.Pp
The options are as follows:
.Bl -tag -width indent
.It Fl c
Reconnect on close.
If the tty observed by
.Nm
is closed,  automatically reattach to the same tty.
If this option is not specified,
.Nm
will request a new tty if running in interactive mode or exit if running
without a controlling tty.
.It Fl f Ar snpdev
If this option is specified,
.Nm
will use
.Ar snpdev
as the
.Xr snp 4
device.
Without this option,
.Nm
will attempt to find the next available
.Xr snp 4
device.
.It Fl i
Force interactive mode.
Interactive mode is a default if
.Nm
is started from a tty.
If output is redirected to a file, interactive mode can still be requested
by specifying this option.
.It Fl n
Disable the ability to switch the watched tty interactively.
This disables
both change requests made with <control-X> as well as automatic prompting
when the current tty is closed or overflows.
In all cases where a prompt
would be displayed,
.Nm
will exit.
The reconnect flags are unaffected by
this option.
When this flag is used, <control-X> is passed through to the terminal.
.It Fl o
Reconnect on overflow.
The behavior of
.Nm
if the observed tty overflows is similar to the behavior if the observed tty
is closed.
For more info see
.Xr snp 4 .
.It Fl t
Print the date and time when observation of a given tty is started.
.It Fl W
Allow write access to observed tty.
.It Ar tty
Tty may be specified as a tty-style device, such as a pseudo tty device,
a virtual console, or a serial line, etc.
Names may be preceded by
.Pa /dev/ .
.El
.Sh OPERATION
While running in interactive mode, all user input is discarded except for:
.Pp
.Bl -tag -width "XXXX" -compact
.It Sy "<control-G>"
Exit
.Nm .
.It Sy "<control-W>"
Clear screen.
.It Sy "<control-X>"
Change attached tty, unless this feature is disabled, in which case
control-X is passed to the terminal as with other control characters.
.El
.Sh SEE ALSO
.Xr pty 4 ,
.Xr sio 4 ,
.Xr snp 4 ,
.Xr kldload 8
.Sh BUGS
No terminal emulation is performed.
All user output is reproduced as-is.
.Sh AUTHORS
.An Ugen J.S. Antsilevich Aq ugen@NetVision.net.il
.Sh HISTORY
The
.Nm
utility first appeared in
.Fx 2.1 .
Rewrite manual page to use mandoc correctly and fix english grammar. 1995-02-22 23:47:51 +00:00			`.\"`
$Id$ -> $FreeBSD$ 1999-08-28 01:35:59 +00:00			`.\" $FreeBSD$`
Rewrite manual page to use mandoc correctly and fix english grammar. 1995-02-22 23:47:51 +00:00			`.\"`
Add an -f option which allows one to specify a snp device to use. Previously, watch would always use the first device it could successfully open, but this isn't always desired. Specifically, it may not be desired during debugging (of snp), or if a particular snp device has different permissions (which makes since after snp.c 1.64). 2001-11-24 15:41:38 +00:00			`.Dd November 24, 2001`
Watch fresh-made manpage.. 1995-02-17 16:40:32 +00:00			`.Dt WATCH 8`
			`.Os`
			`.Sh NAME`
Rewrite manual page to use mandoc correctly and fix english grammar. 1995-02-22 23:47:51 +00:00			`.Nm watch`
			`.Nd snoop on another tty line`
Fix a bunch of spelling errors in a bunch of man pages. 1996-01-30 13:52:50 +00:00			`.Sh SYNOPSIS`
mdoc(7) police: use the new features of the Nm macro. 2000-11-20 20:10:44 +00:00			`.Nm`
Remove the sentence about only root being able to run watch(8). It was never technically true (it's snp(4) that required root, not watch(8)), and after snp.c 1.64, isn't even effectively true, since who can run watch(8) depends on the permissions of the snp device(s). Sort options in SYNOPSIS and DESCRIPTION while I'm here. 2001-11-24 15:51:34 +00:00			`.Op Fl cinotW`
Add an -f option which allows one to specify a snp device to use. Previously, watch would always use the first device it could successfully open, but this isn't always desired. Specifically, it may not be desired during debugging (of snp), or if a particular snp device has different permissions (which makes since after snp.c 1.64). 2001-11-24 15:41:38 +00:00			`.Op Fl f Ar snpdev`
``tty'' is not required parameter 1999-10-30 14:52:24 +00:00			`.Op Ar tty`
Watch fresh-made manpage.. 1995-02-17 16:40:32 +00:00			`.Sh DESCRIPTION`
The .Nm utility 2002-07-14 14:47:15 +00:00			`The`
			`.Nm`
			`utility allows the user to examine all data coming through a specified tty`
Talk about what the user needs to do to get the snp devices, and how watch(8) will try to help them by loading the module. PR: 25420 2001-11-24 17:02:58 +00:00			`using the`
			`.Xr snp 4`
			`device.`
			`If the`
			`.Xr snp 4`
			`device is not available,`
			`.Nm`
			`will attempt to load the module`
			`.Pq Nm snp .`
The .Nm utility 2002-07-14 14:47:15 +00:00			`The`
			`.Nm`
			`utility writes to standard output.`
Rewrite manual page to use mandoc correctly and fix english grammar. 1995-02-22 23:47:51 +00:00			`.Pp`
			`The options are as follows:`
Use err(3). 1997-10-27 12:21:10 +00:00			`.Bl -tag -width indent`
Rewrite manual page to use mandoc correctly and fix english grammar. 1995-02-22 23:47:51 +00:00			`.It Fl c`
Mechanically kill hard sentence breaks. 2004-07-02 23:13:00 +00:00			`Reconnect on close.`
			`If the tty observed by`
Use err(3). 1997-10-27 12:21:10 +00:00			`.Nm`
Rewrite manual page to use mandoc correctly and fix english grammar. 1995-02-22 23:47:51 +00:00			`is closed, automatically reattach to the same tty.`
			`If this option is not specified,`
Use err(3). 1997-10-27 12:21:10 +00:00			`.Nm`
Rewrite manual page to use mandoc correctly and fix english grammar. 1995-02-22 23:47:51 +00:00			`will request a new tty if running in interactive mode or exit if running`
			`without a controlling tty.`
Add an -f option which allows one to specify a snp device to use. Previously, watch would always use the first device it could successfully open, but this isn't always desired. Specifically, it may not be desired during debugging (of snp), or if a particular snp device has different permissions (which makes since after snp.c 1.64). 2001-11-24 15:41:38 +00:00			`.It Fl f Ar snpdev`
			`If this option is specified,`
			`.Nm`
			`will use`
			`.Ar snpdev`
			`as the`
			`.Xr snp 4`
			`device.`
			`Without this option,`
			`.Nm`
			`will attempt to find the next available`
			`.Xr snp 4`
			`device.`
Rewrite manual page to use mandoc correctly and fix english grammar. 1995-02-22 23:47:51 +00:00			`.It Fl i`
			`Force interactive mode.`
			`Interactive mode is a default if`
Use err(3). 1997-10-27 12:21:10 +00:00			`.Nm`
Rewrite manual page to use mandoc correctly and fix english grammar. 1995-02-22 23:47:51 +00:00			`is started from a tty.`
			`If output is redirected to a file, interactive mode can still be requested`
			`by specifying this option.`
Remove the sentence about only root being able to run watch(8). It was never technically true (it's snp(4) that required root, not watch(8)), and after snp.c 1.64, isn't even effectively true, since who can run watch(8) depends on the permissions of the snp device(s). Sort options in SYNOPSIS and DESCRIPTION while I'm here. 2001-11-24 15:51:34 +00:00			`.It Fl n`
Mechanically kill hard sentence breaks. 2004-07-02 23:13:00 +00:00			`Disable the ability to switch the watched tty interactively.`
			`This disables`
Remove the sentence about only root being able to run watch(8). It was never technically true (it's snp(4) that required root, not watch(8)), and after snp.c 1.64, isn't even effectively true, since who can run watch(8) depends on the permissions of the snp device(s). Sort options in SYNOPSIS and DESCRIPTION while I'm here. 2001-11-24 15:51:34 +00:00			`both change requests made with <control-X> as well as automatic prompting`
Mechanically kill hard sentence breaks. 2004-07-02 23:13:00 +00:00			`when the current tty is closed or overflows.`
			`In all cases where a prompt`
Remove the sentence about only root being able to run watch(8). It was never technically true (it's snp(4) that required root, not watch(8)), and after snp.c 1.64, isn't even effectively true, since who can run watch(8) depends on the permissions of the snp device(s). Sort options in SYNOPSIS and DESCRIPTION while I'm here. 2001-11-24 15:51:34 +00:00			`would be displayed,`
			`.Nm`
Mechanically kill hard sentence breaks. 2004-07-02 23:13:00 +00:00			`will exit.`
			`The reconnect flags are unaffected by`
Remove the sentence about only root being able to run watch(8). It was never technically true (it's snp(4) that required root, not watch(8)), and after snp.c 1.64, isn't even effectively true, since who can run watch(8) depends on the permissions of the snp device(s). Sort options in SYNOPSIS and DESCRIPTION while I'm here. 2001-11-24 15:51:34 +00:00			`this option.`
			`When this flag is used, <control-X> is passed through to the terminal.`
Rewrite manual page to use mandoc correctly and fix english grammar. 1995-02-22 23:47:51 +00:00			`.It Fl o`
			`Reconnect on overflow.`
Fix a bunch of spelling errors in a bunch of man pages. 1996-01-30 13:52:50 +00:00			`The behavior of`
Use err(3). 1997-10-27 12:21:10 +00:00			`.Nm`
Rewrite manual page to use mandoc correctly and fix english grammar. 1995-02-22 23:47:51 +00:00			`if the observed tty overflows is similar to the behavior if the observed tty`
			`is closed.`
			`For more info see`
			`.Xr snp 4 .`
			`.It Fl t`
			`Print the date and time when observation of a given tty is started.`
same 1995-02-27 19:48:19 +00:00			`.It Fl W`
			`Allow write access to observed tty.`
Rewrite manual page to use mandoc correctly and fix english grammar. 1995-02-22 23:47:51 +00:00			`.It Ar tty`
Fix typos, mostly s/ an / a / where appropriate and a few s/an/and/ Add FreeBSD Id tag where missing. 2002-12-30 21:18:15 +00:00			`Tty may be specified as a tty-style device, such as a pseudo tty device,`
Update to use new calling conventions 1995-02-25 20:14:31 +00:00			`a virtual console, or a serial line, etc.`
Add missing .El. -Wall cleaning. 2000-01-23 20:27:32 +00:00			`Names may be preceded by`
			`.Pa /dev/ .`
			`.El`
Rewrite manual page to use mandoc correctly and fix english grammar. 1995-02-22 23:47:51 +00:00			`.Sh OPERATION`
			`While running in interactive mode, all user input is discarded except for:`
			`.Pp`
			`.Bl -tag -width "XXXX" -compact`
Remove breakage of 1.8.2.2, choose slightly better character for quit. 1996-12-30 09:01:50 +00:00			`.It Sy "<control-G>"`
Rewrite manual page to use mandoc correctly and fix english grammar. 1995-02-22 23:47:51 +00:00			`Exit`
mdoc(7) police: use the new features of the Nm macro. 2000-11-20 20:10:44 +00:00			`.Nm .`
Rewrite manual page to use mandoc correctly and fix english grammar. 1995-02-22 23:47:51 +00:00			`.It Sy "<control-W>"`
			`Clear screen.`
			`.It Sy "<control-X>"`
o When "-n" is used with watch, it disables the use of <control-X> to change terminals being watched. This change makes watch pass the <control-X> through to the terminal if it's not being intercepted-- previously, the keypress would simply be dropped. 2001-11-07 19:15:19 +00:00			`Change attached tty, unless this feature is disabled, in which case`
			`control-X is passed to the terminal as with other control characters.`
Add missing .El. -Wall cleaning. 2000-01-23 20:27:32 +00:00			`.El`
Watch fresh-made manpage.. 1995-02-17 16:40:32 +00:00			`.Sh SEE ALSO`
Rewrite manual page to use mandoc correctly and fix english grammar. 1995-02-22 23:47:51 +00:00			`.Xr pty 4 ,`
Sort cross references. 1997-01-20 00:03:00 +00:00			`.Xr sio 4 ,`
Talk about what the user needs to do to get the snp devices, and how watch(8) will try to help them by loading the module. PR: 25420 2001-11-24 17:02:58 +00:00			`.Xr snp 4 ,`
			`.Xr kldload 8`
Watch fresh-made manpage.. 1995-02-17 16:40:32 +00:00			`.Sh BUGS`
Rewrite manual page to use mandoc correctly and fix english grammar. 1995-02-22 23:47:51 +00:00			`No terminal emulation is performed.`
			`All user output is reproduced as-is.`
.Sh AUTHOR -> .Sh AUTHORS. Use .An/.Aq. 1998-03-23 08:31:20 +00:00			`.Sh AUTHORS`
Use err(3). 1997-10-27 12:21:10 +00:00			`.An Ugen J.S. Antsilevich Aq ugen@NetVision.net.il`
Watch fresh-made manpage.. 1995-02-17 16:40:32 +00:00			`.Sh HISTORY`
The .Nm utility 2002-07-14 14:47:15 +00:00			`The`
			`.Nm`
			`utility first appeared in`
Use the .Fx macro where appropriate. 1996-08-23 00:57:08 +00:00			`.Fx 2.1 .`