From 7d2fafe636e5527b90688c9615f59cdcdfdff470 Mon Sep 17 00:00:00 2001 From: Bruce Momjian Date: Thu, 4 Dec 1997 20:26:37 +0000 Subject: [PATCH] Update description for PGHOST and unix domain sockets. Add warning for failed connections. --- src/interfaces/libpq/fe-connect.c | 5 +- src/man/createdb.1 | 10 +- src/man/createuser.1 | 10 +- src/man/destroydb.1 | 10 +- src/man/destroyuser.1 | 10 +- src/man/libpq.3 | 7 +- src/man/monitor.1 | 269 -------------------------------------- src/man/postmaster.1 | 7 +- src/man/psql.1 | 14 +- 9 files changed, 35 insertions(+), 307 deletions(-) delete mode 100644 src/man/monitor.1 diff --git a/src/interfaces/libpq/fe-connect.c b/src/interfaces/libpq/fe-connect.c index 84fa1f6742..89bed13ac1 100644 --- a/src/interfaces/libpq/fe-connect.c +++ b/src/interfaces/libpq/fe-connect.c @@ -7,7 +7,7 @@ * * * IDENTIFICATION - * $Header: /cvsroot/pgsql/src/interfaces/libpq/fe-connect.c,v 1.50 1997/12/04 00:28:11 scrappy Exp $ + * $Header: /cvsroot/pgsql/src/interfaces/libpq/fe-connect.c,v 1.51 1997/12/04 20:26:09 momjian Exp $ * *------------------------------------------------------------------------- */ @@ -572,7 +572,8 @@ connectDB(PGconn *conn) if (connect(port->sock, (struct sockaddr *) & port->raddr, len) < 0) { (void) sprintf(conn->errorMessage, - "connectDB() failed: Is the postmaster running at '%s' on port '%s'?\n", + "connectDB() failed: Is the postmaster accepting%s connections at '%s' on port '%s'?\n", + conn->pghost ? " TCP/IP(with -i)" : "", conn->pghost ? conn->pghost : "UNIX Socket", conn->pgport); goto connect_errReturn; diff --git a/src/man/createdb.1 b/src/man/createdb.1 index 1831b6228a..23c1d71a3b 100644 --- a/src/man/createdb.1 +++ b/src/man/createdb.1 @@ -1,6 +1,6 @@ .\" This is -*-nroff-*- .\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/src/man/Attic/createdb.1,v 1.4 1997/11/07 06:33:57 thomas Exp $ +.\" $Header: /cvsroot/pgsql/src/man/Attic/createdb.1,v 1.5 1997/12/04 20:26:18 momjian Exp $ .TH CREATEDB UNIX 11/05/95 PostgreSQL PostgreSQL .SH NAME createdb \(em create a database @@ -68,13 +68,11 @@ Specifies the alternate database location for this database. .BR "-h" " host" 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). +is running. Defaults to the using local Unix domain sockets. .TP .BR "-p" " port" -Specifies the Internet TCP port on which the +Specifies the Internet TCP/IP port or local Unix domain socket file +extension on which the .IR postmaster is listening for connections. Defaults to 5432, or the value of the .SM PGPORT diff --git a/src/man/createuser.1 b/src/man/createuser.1 index 31a26578ea..fdd29fb527 100644 --- a/src/man/createuser.1 +++ b/src/man/createuser.1 @@ -1,6 +1,6 @@ .\" This is -*-nroff-*- .\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/src/man/Attic/createuser.1,v 1.3 1997/08/26 17:29:55 momjian Exp $ +.\" $Header: /cvsroot/pgsql/src/man/Attic/createuser.1,v 1.4 1997/12/04 20:26:20 momjian Exp $ .TH CREATEUSER UNIX 11/05/95 PostgreSQL PostgreSQL .SH NAME createuser \(em create a Postgres user @@ -60,13 +60,11 @@ process. The default is site-specific. .BR "-h" " host" 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). +is running. Defaults to using local Unix domain sockets. .TP .BR "-p" " port" -Specifies the Internet TCP port on which the +Specifies the TCP/IP port or local Unix domain socket file +extension on which the .IR postmaster is listening for connections. Defaults to 5432, or the value of the .SM PGPORT diff --git a/src/man/destroydb.1 b/src/man/destroydb.1 index 0192fecd3c..4d5187dc75 100644 --- a/src/man/destroydb.1 +++ b/src/man/destroydb.1 @@ -1,6 +1,6 @@ .\" This is -*-nroff-*- .\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/src/man/Attic/destroydb.1,v 1.4 1997/08/26 17:29:55 momjian Exp $ +.\" $Header: /cvsroot/pgsql/src/man/Attic/destroydb.1,v 1.5 1997/12/04 20:26:24 momjian Exp $ .TH DESTROYDB UNIX 11/05/95 PostgreSQL PostgreSQL .SH NAME destroydb \(em destroy an existing database @@ -70,13 +70,11 @@ process. The default is site-specific. .BR "-h" " host" 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). +is running. Defaults to using local Unix domain sockets. .TP .BR "-p" " port" -Specifies the Internet TCP port on which the +Specifies the TCP/IP port or local Unix domain socket file extension +on which the .IR postmaster is listening for connections. Defaults to 5432, or the value of the .SM PGPORT diff --git a/src/man/destroyuser.1 b/src/man/destroyuser.1 index 71fbaadd91..0b458f13c6 100644 --- a/src/man/destroyuser.1 +++ b/src/man/destroyuser.1 @@ -1,6 +1,6 @@ .\" This is -*-nroff-*- .\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/src/man/Attic/destroyuser.1,v 1.3 1997/08/26 17:29:59 momjian Exp $ +.\" $Header: /cvsroot/pgsql/src/man/Attic/destroyuser.1,v 1.4 1997/12/04 20:26:26 momjian Exp $ .TH DESTROYUSER UNIX 11/05/95 PostgreSQL PostgreSQL .SH NAME destroyuser \(em destroy a Postgres user and associated databases @@ -60,13 +60,11 @@ process. The default is site-specific. .BR "-h" " host" 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). +is running. Defaults to using local Unix domain sockets. .TP .BR "-p" " port" -Specifies the Internet TCP port on which the +Specifies the TCP/IP port or local Unix domain socket file extension +on which the .IR postmaster is listening for connections. Defaults to 5432, or the value of the .SM PGPORT diff --git a/src/man/libpq.3 b/src/man/libpq.3 index 1a64338fde..7adcd3c3de 100644 --- a/src/man/libpq.3 +++ b/src/man/libpq.3 @@ -1,6 +1,6 @@ .\" This is -*-nroff-*- .\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/src/man/Attic/libpq.3,v 1.10 1997/11/14 15:41:30 thomas Exp $ +.\" $Header: /cvsroot/pgsql/src/man/Attic/libpq.3,v 1.11 1997/12/04 20:26:31 momjian Exp $ .TH LIBPQ INTRO 03/12/94 PostgreSQL PostgreSQL .SH DESCRIPTION Libpq is the programmer's interface to Postgres. Libpq is a set of @@ -33,6 +33,8 @@ an application program: \(bu .B PGHOST sets the default server name. +If it is set to a non-zero-length string, it causes TCP/IP +communication to be used, rather than the default local Unix domain sockets. .sp \(bu .B PGOPTIONS @@ -40,7 +42,8 @@ sets additional runtime options for the Postgres backend. .sp \(bu .B PGPORT -sets the default port for communicating with the Postgres backend. +sets the default port or local Unix domain socket file extension +for communicating with the Postgres backend. .sp \(bu .B PGTTY diff --git a/src/man/monitor.1 b/src/man/monitor.1 deleted file mode 100644 index 6bc7b28da4..0000000000 --- a/src/man/monitor.1 +++ /dev/null @@ -1,269 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/src/man/Attic/monitor.1,v 1.3 1997/08/26 17:30:02 momjian Exp $ -.TH MONITOR UNIX 11/05/95 PostgreSQL PostgreSQL -.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 pgintro (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 pgintro (1) -for additional information on -.IR Kerberos . -.PP -See -.IR pgintro (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" -libpq(3), -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) diff --git a/src/man/postmaster.1 b/src/man/postmaster.1 index de016b904c..14d2fc52e4 100644 --- a/src/man/postmaster.1 +++ b/src/man/postmaster.1 @@ -1,6 +1,6 @@ .\" This is -*-nroff-*- .\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/src/man/Attic/postmaster.1,v 1.8 1997/11/07 21:25:07 momjian Exp $ +.\" $Header: /cvsroot/pgsql/src/man/Attic/postmaster.1,v 1.9 1997/12/04 20:26:35 momjian Exp $ .TH POSTMASTER UNIX 11/05/95 PostgreSQL PostgreSQL .SH "NAME" postmaster \(em run the Postgres postmaster @@ -189,7 +189,8 @@ If the option string contains any spaces, the entire string must be quoted. .TP .BR "-p" " port" -Specifies the Internet TCP port on which the +Specifies the TCP/IP port or local Unix domain socket file extension +on which the .IR postmaster is to listen for connections from frontend applications. Defaults to 5432, or the value of the @@ -199,8 +200,6 @@ default port then all frontend application users must specify the same port (using command-line options or .SM PGPORT\c ) when starting any libpq application, including psql. -Local Unix domain sockets also use this port number as an identifier -to allow unix domain communication with multiple postmasters. .SH "WARNINGS" If at all possible, .BR "do not" diff --git a/src/man/psql.1 b/src/man/psql.1 index f09f607ffd..ccde0d72e3 100644 --- a/src/man/psql.1 +++ b/src/man/psql.1 @@ -1,6 +1,6 @@ .\" This is -*-nroff-*- .\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/src/man/Attic/psql.1,v 1.19 1997/12/02 03:43:54 scrappy Exp $ +.\" $Header: /cvsroot/pgsql/src/man/Attic/psql.1,v 1.20 1997/12/04 20:26:37 momjian Exp $ .TH PSQL UNIX 1/20/96 PostgreSQL PostgreSQL .SH NAME psql \(em run the interactive query front-end @@ -151,10 +151,9 @@ The default is "|". .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). +is running. +Without this option, communication is performed using +local Unix domain sockets. .TP .BR "-H" Turns on @@ -171,7 +170,8 @@ Do not use the readline library for input line editing and command history. Put all output into filename .TP .BR "-p" " port" -Specifies the Internet TCP port on which the +Specifies the TCP/IP port or local Unix domain socket file +extension on which the .IR postmaster is listening for connections. Defaults to 5432, or the value of the .SM PGPORT @@ -394,6 +394,8 @@ tty: PGTTY options: PGOPTION realm: PGREALM .fi +Setting PGHOST to a non-zero-length string causes TCP/IP communication +to be used, rather than the default local Unix domain sockets. .PP If .SM PGOPTION -- 2.11.0