postgres/doc/man/monitor.1

.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/monitor.1,v 1.1.1.1 1996/08/18 22:14:25 scrappy Exp $
.TH MONITOR UNIX 11/05/95 Postgres95 Postgres95
.SH NAME
monitor \(em run the interactive terminal monitor
.SH SYNOPSIS
.BR monitor
[\c
.BR "-N"
]
[\c
.BR "-Q"
]
[\c
.BR "-T"
]
[\c
.BR "-a"
system]
[\c
.BR "-c"
query]
[\c
.BR "-d"
path]
.br
.in +5n
[\c
.BR "-h"
hostname]
[\c
.BR "-p"
port]
[\c
.BR "-q"
]
[\c
.BR "-t"
tty_device]
[dbname]
.in -5n
.SH DESCRIPTION
The interactive terminal monitor is a simple frontend to Postgres retained
for backwards compatiblity.   Users are encouraged to the use the
.IR "psql"
interface instead.
.PP
.IR "monitor"
enables you to formulate, edit and review queries before issuing them
to Postgres.  If changes must be made, a Unix editor may be called
to edit the
.BR "query buffer"
managed by the terminal monitor.  The editor used is determined by the
value of the
.SM EDITOR
environment variable.  If
.SM EDITOR
is not set, then
.BR "vi"
is used by default.
.PP
.IR "Monitor"
is a frontend application, like any other.  Hence, a
.IR "postmaster"
process must be running on the database server host before
.IR "monitor"
is executed.  In addition, the correct 
.IR "postmaster"
port number must be specified
as described below.
.PP
The optional argument
.IR dbname
specifies the name of the database to be accessed.  This database must
already have been created using 
.IR createdb .
.IR Dbname
defaults to the value of the
.SM USER
environment variable.
.PP
.IR "Monitor"
understands the following command-line options:
.TP 5n
.BR "-N"
Specifies that query results will be dumped to the screen without any
attempt at formatting.  This is useful in with the
.BR -c
option in shell scripts.
.TP
.BR "-Q"
Produces extremely unverbose output.
This is useful 
with the
.BR -c
option in shell scripts.
.TP
.BR "-T"
Specifies that attribute names will not be printed.
This is useful 
with the
.BR -c
option in shell scripts.
.TP
.BR "-a" " system"
Specifies an authentication system
.IR "system"
(see 
.IR introduction (1))
to use in connecting to the 
.IR postmaster
process.  The default is site-specific.
.TP
.BR "-c" " query"
Specifies that
.IR "monitor"
is to execute one query string,
.IR "query" ,
and then exit.  This is useful for shell scripts, typically in
conjunction with the
.BR -N
and
.BR -T
options.  Examples of shell scripts in the Postgres distribution using 
.IB "monitor" " -c"
include 
.IR createdb ,
.IR destroydb , 
.IR createuser , 
and
.IR destroyuser ,
.TP
.BR "-d" " path"
.IR path
specifies the path name of the file or tty to which frontend (i.e., 
.IR monitor )
debugging messages are to be written; the default is not to generate
any debugging messages.
.TP
.BR "-h" " hostname"
Specifies the hostname of the machine on which the 
.IR postmaster
is running.  Defaults to the name of the local host, or the value of
the
.SM PGHOST
environment variable (if set).
.TP
.BR "-p" " port"
Specifies the Internet TCP port on which the
.IR postmaster
is listening for connections.  Defaults to 5432, or the value of the
.SM PGPORT
environment variable (if set).
.TP
.BR "-q"
Specifies that the monitor should do its work quietly.  By default, it
prints welcome and exit messages and the queries it sends to the
backend.  If this option is used, none of this happens.
.TP
.BR "-t" " tty_device"
.IR "tty_device"
specifies the path name to the file or tty
to which backend (i.e., 
.IR postgres )
debugging messages are to be written; the default is 
.IR "/dev/null" .
.TP
.BR "-s"
parses after each query (enables "single step" mode).
.TP
.BR "-S"
Turns off sending query when ";" is encountered.
.PP
You may set environment variables to avoid typing some of the above
options.  See the 
.SM "ENVIRONMENT VARIABLES"
section below.
.SH "MESSAGES AND PROMPTS"
The terminal monitor gives a variety of messages to keep the user
informed of the status of the monitor and the query buffer.
.PP
The terminal monitor displays two kinds of messages:
.IP go
The query buffer is empty and the terminal monitor is ready for input.
Anything typed will be added to the buffer.
.IP *
This prompt is typed at the beginning of each line when the terminal
monitor is waiting for input.
.SH "TERMINAL MONITOR COMMANDS"
.IP \ee
Enter the editor to edit the query buffer.
.IP \eg
Submit query buffer to Postgres for execution.
.IP \eh
Get on-line help.
.IP "\ei \fIfilename\fR"
Include the file 
.IR filename
into the query buffer.
.IP \ep
Print the current contents of the query buffer.
.IP \eq
Exit from the terminal monitor.
.IP \er
Reset (clear) the query buffer.
.IP \es
Escape to a Unix subshell.  To return to the terminal monitor, type
\*(lqexit\*(rq at the shell prompt.
.IP \et
Print the current time.
.IP "\ew \fIfilename\fR"
Store (write) the query buffer to an external file
.IR filename .
.IP \e\e
Produce a single backslash at the current location in query buffer.
.IP \e;
Produce a single semi-colon at the current location in query buffer.
.SH "ENVIRONMENT VARIABLES"
You may set any of the following environment variables to avoid
specifying command-line options:
.nf
hostname:	PGHOST
port:		PGPORT
tty:		PGTTY
options:		PGOPTION
realm:		PGREALM
.fi
.PP
If 
.SM PGOPTION
is specified, then the options it contains are parsed
.BR before
any command-line options.
.PP
.SM PGREALM
only applies if 
.IR Kerberos
authentication is in use.  If this environment variable is set, Postgres
will attempt authentication with servers for this realm and use
separate ticket files to avoid conflicts with local ticket files.  See
.IR introduction (1)
for additional information on 
.IR Kerberos .
.PP
See 
.IR introduction (libpq)
for additional details.
.SH "RETURN VALUE"
When executed with the
.BR "-c"
option,
.IR monitor
returns 0 to the shell on successful query completion, 1 otherwise.
.SH "SEE ALSO"
introduction(libpq),
createdb(1),
createuser(1),
postgres(1),
postmaster(1).
.SH BUGS
Does not poll for asynchronous notification events generated by
.IR listen (l)
and 
.IR notify (l).
.PP
Escapes (backslash characters) cannot be commented out.
.SH "SEE ALSO"
psql(1)