help.c 11 KB
Newer Older
Peter Eisentraut's avatar
Peter Eisentraut committed
1 2 3
/*
 * psql - the PostgreSQL interactive terminal
 *
4
 * Copyright 2000 by PostgreSQL Global Development Group
Peter Eisentraut's avatar
Peter Eisentraut committed
5
 *
6
 * $Header: /cvsroot/pgsql/src/bin/psql/help.c,v 1.40 2001/06/08 23:53:48 petere Exp $
Peter Eisentraut's avatar
Peter Eisentraut committed
7
 */
8
#include "postgres_fe.h"
9 10 11
#include "help.h"

#include <signal.h>
12
#include <errno.h>
13 14

#ifndef WIN32
Bruce Momjian's avatar
Bruce Momjian committed
15
#include <sys/ioctl.h>			/* for ioctl() */
16
#ifdef HAVE_PWD_H
Bruce Momjian's avatar
Bruce Momjian committed
17
#include <pwd.h>				/* for getpwuid() */
18
#endif
Bruce Momjian's avatar
Bruce Momjian committed
19 20
#include <sys/types.h>			/* (ditto) */
#include <unistd.h>				/* for getuid() */
21
#else
22
#include <win32.h>
23 24
#endif

25 26
#include "pqsignal.h"
#include "libpq-fe.h"
27 28 29 30 31

#include "settings.h"
#include "common.h"
#include "sql_help.h"

32 33
#define _(x) gettext((x))

34 35 36 37 38 39 40
/*
 * PLEASE:
 * If you change something in this file, also make the same changes
 * in the DocBook documentation, file ref/psql-ref.sgml. If you don't
 * know how to do it, please find someone who can help you.
 */

41 42 43 44

/*
 * usage
 *
45
 * print out command line arguments
46
 */
47
#define ON(var) (var ? _("on") : _("off"))
48

Bruce Momjian's avatar
Bruce Momjian committed
49 50
void
usage(void)
51
{
Bruce Momjian's avatar
Bruce Momjian committed
52 53 54
	const char *env;
	const char *user;

55
#ifndef WIN32
Bruce Momjian's avatar
Bruce Momjian committed
56
	struct passwd *pw = NULL;
57

58 59
#endif

Bruce Momjian's avatar
Bruce Momjian committed
60 61 62 63
	/* Find default user, in case we need it. */
	user = getenv("USER");
	if (!user)
	{
64
#ifndef WIN32
65
		pw = getpwuid(geteuid());
Bruce Momjian's avatar
Bruce Momjian committed
66 67 68 69
		if (pw)
			user = pw->pw_name;
		else
		{
70
			psql_error("could not get current user name: %s\n", strerror(errno));
Bruce Momjian's avatar
Bruce Momjian committed
71 72
			exit(EXIT_FAILURE);
		}
73
#else
Bruce Momjian's avatar
Bruce Momjian committed
74
		user = "?";
75
#endif
Bruce Momjian's avatar
Bruce Momjian committed
76
	}
77

78
/* If this " is the start of the string then it ought to end there to fit in 80 columns >> " */
79 80 81 82 83 84
	puts(_("This is psql, the PostgreSQL interactive terminal.\n"));
	puts(_("Usage:"));
	puts(_("  psql [options] [dbname [username]]\n"));
	puts(_("Options:"));
	puts(_("  -a              Echo all input from script"));
	puts(_("  -A              Unaligned table output mode (-P format=unaligned)"));
85
	puts(_("  -c COMMAND      Run only single command (SQL or interal) and exit"));
Bruce Momjian's avatar
Bruce Momjian committed
86 87 88 89 90

	/* Display default database */
	env = getenv("PGDATABASE");
	if (!env)
		env = user;
91
	printf(_("  -d DBNAME       Specify database name to connect to (default: %s)\n"), env);
Bruce Momjian's avatar
Bruce Momjian committed
92

93
	puts(_("  -e              Echo commands sent to server"));
94
	puts(_("  -E              Display queries that internal commands generate"));
95 96
	puts(_("  -f FILENAME     Execute commands from file, then exit"));
	printf(_("  -F STRING       Set field separator (default: \"%s\") (-P fieldsep=)\n"),
97
		   DEFAULT_FIELD_SEP);
Bruce Momjian's avatar
Bruce Momjian committed
98 99 100

	/* Display default host */
	env = getenv("PGHOST");
101
	printf(_("  -h HOSTNAME     Specify database server host (default: %s)\n"),
102
		   env ? env : _("local socket"));
Bruce Momjian's avatar
Bruce Momjian committed
103

104 105
	puts(_("  -H              HTML table output mode (-P format=html)"));
	puts(_("  -l              List available databases, then exit"));
106 107
	puts(_("  -n              Disable enhanced command line editing (readline)"));
	puts(_("  -o FILENAME     Send query results to file (or |pipe)"));
Bruce Momjian's avatar
Bruce Momjian committed
108 109 110

	/* Display default port */
	env = getenv("PGPORT");
111
	printf(_("  -p PORT         Specify database server port (default: %s)\n"),
112
		   env ? env : DEF_PGPORT_STR);
Bruce Momjian's avatar
Bruce Momjian committed
113

114
	puts(_("  -P VAR[=ARG]    Set printing option 'VAR' to 'ARG' (see \\pset command)"));
115
	puts(_("  -q              Run quietly (no messages, only query output)"));
116
	puts(_("  -R STRING       Set record separator (default: newline) (-P recordsep=)"));
117
	puts(_("  -s              Single step mode (confirm each query)"));
118
	puts(_("  -S              Single line mode (end of line terminates SQL command)"));
119
	puts(_("  -t              Print rows only (-P tuples_only)"));
120
	puts(_("  -T TEXT         Set HTML table tag attributes (width, border) (-P tableattr=)"));
Bruce Momjian's avatar
Bruce Momjian committed
121 122 123 124 125

	/* Display default user */
	env = getenv("PGUSER");
	if (!env)
		env = user;
126
	printf(_("  -U NAME         Specify database user name (default: %s)\n"), env);
127

128
	puts(_("  -v NAME=VALUE   Set psql variable 'NAME' to 'VALUE'"));
129 130 131 132 133 134 135 136
	puts(_("  -V              Show version information and exit"));
	puts(_("  -W              Prompt for password (should happen automatically)"));
	puts(_("  -x              Turn on expanded table output (-P expanded)"));
	puts(_("  -X              Do not read startup file (~/.psqlrc)"));

	puts(_(
		"\nFor more information, type \"\\?\" (for internal commands) or \"\\help\"\n"
		"(for SQL commands) from within psql, or consult the psql section in\n"
137
		"the PostgreSQL documentation.\n\n"
138
		"Report bugs to <pgsql-bugs@postgresql.org>."));
139 140 141 142 143 144 145 146 147 148 149
}



/*
 * slashUsage
 *
 * print out help for the backslash commands
 */

#ifndef TIOCGWINSZ
Bruce Momjian's avatar
Bruce Momjian committed
150 151 152 153
struct winsize
{
	int			ws_row;
	int			ws_col;
154
};
Bruce Momjian's avatar
Bruce Momjian committed
155

156 157 158
#endif

void
159
slashUsage(void)
160
{
Bruce Momjian's avatar
Bruce Momjian committed
161 162 163 164
	bool		usePipe = false;
	const char *pagerenv;
	FILE	   *fout;
	struct winsize screen_size;
165 166

#ifdef TIOCGWINSZ
167
	if (pset.notty == 0 &&
Bruce Momjian's avatar
Bruce Momjian committed
168 169 170 171
		(ioctl(fileno(stdout), TIOCGWINSZ, &screen_size) == -1 ||
		 screen_size.ws_col == 0 ||
		 screen_size.ws_row == 0))
	{
172
#endif
Bruce Momjian's avatar
Bruce Momjian committed
173 174
		screen_size.ws_row = 24;
		screen_size.ws_col = 80;
175
#ifdef TIOCGWINSZ
Bruce Momjian's avatar
Bruce Momjian committed
176
	}
177 178
#endif

179
	if (pset.notty == 0 &&
Bruce Momjian's avatar
Bruce Momjian committed
180 181
		(pagerenv = getenv("PAGER")) &&
		(pagerenv[0] != '\0') &&
182
		screen_size.ws_row <= 39 &&
Bruce Momjian's avatar
Bruce Momjian committed
183 184 185
		(fout = popen(pagerenv, "w")))
	{
		usePipe = true;
Bruce Momjian's avatar
Hi!  
Bruce Momjian committed
186
#ifndef WIN32
Bruce Momjian's avatar
Bruce Momjian committed
187
		pqsignal(SIGPIPE, SIG_IGN);
Bruce Momjian's avatar
Hi!  
Bruce Momjian committed
188
#endif
Bruce Momjian's avatar
Bruce Momjian committed
189 190 191 192 193
	}
	else
		fout = stdout;

	/* if you add/remove a line here, change the row test above */
194 195 196
	fprintf(fout, _(" \\a             toggle between unaligned and aligned output mode\n"));
	fprintf(fout, _(" \\c[onnect] [DBNAME|- [USER]]\n"
					"                connect to new database (currently \"%s\")\n"),
197
			PQdb(pset.db));
198 199 200
	fprintf(fout, _(" \\C TITLE       set table title\n"));
	fprintf(fout, _(" \\cd [DIRNAME]  change the current working directory\n"));
	fprintf(fout, _(" \\copy ...      perform SQL COPY with data stream to the client host\n"));
201
	fprintf(fout, _(" \\copyright     show PostgreSQL usage and distribution terms\n"));
202 203 204 205 206
	fprintf(fout, _(" \\d TABLE       describe table (or view, index, sequence)\n"));
	fprintf(fout, _(" \\d{t|i|s|v}... list tables/indices/sequences/views\n"));
	fprintf(fout, _(" \\d{p|S|l}      list access privileges, system tables, or large objects\n"));
	fprintf(fout, _(" \\da            list aggregate functions\n"));
	fprintf(fout, _(" \\dd NAME       show comment for table, type, function, or operator\n"));
207 208 209
	fprintf(fout, _(" \\df            list functions\n"));
	fprintf(fout, _(" \\do            list operators\n"));
	fprintf(fout, _(" \\dT            list data types\n"));
210 211 212 213 214 215 216
	fprintf(fout, _(" \\e FILENAME    edit the current query buffer or file with external editor\n"));
	fprintf(fout, _(" \\echo TEXT     write text to standard output\n"));
	fprintf(fout, _(" \\encoding ENCODING  set client encoding\n"));
	fprintf(fout, _(" \\f STRING      set field separator\n"));
	fprintf(fout, _(" \\g FILENAME    send SQL command to server (and write results to file or |pipe)\n"));
	fprintf(fout, _(" \\h NAME        help on syntax of SQL commands, * for all commands\n"));
	fprintf(fout, _(" \\H             toggle HTML output mode (currently %s)\n"),
217
			ON(pset.popt.topt.format == PRINT_HTML));
218
	fprintf(fout, _(" \\i FILENAME    execute commands from file\n"));
219 220 221
	fprintf(fout, _(" \\l             list all databases\n"));
	fprintf(fout, _(" \\lo_export, \\lo_import, \\lo_list, \\lo_unlink\n"
					"                large object operations\n"));
222
	fprintf(fout, _(" \\o FILENAME    send all query results to file or |pipe\n"));
223
	fprintf(fout, _(" \\p             show the content of the current query buffer\n"));
224 225
	fprintf(fout, _(" \\pset VAR      set table output option (VAR := {format|border|expanded|\n"
					"                fieldsep|null|recordsep|tuples_only|title|tableattr|pager})\n"));
226
	fprintf(fout, _(" \\q             quit psql\n"));
227
	fprintf(fout, _(" \\qecho TEXT    write text to query output stream (see \\o)\n"));
228
	fprintf(fout, _(" \\r             reset (clear) the query buffer\n"));
229 230
	fprintf(fout, _(" \\s FILENAME    print history or save it to file\n"));
	fprintf(fout, _(" \\set NAME VALUE  set internal variable\n"));
231 232
	fprintf(fout, _(" \\t             show only rows (currently %s)\n"),
			ON(pset.popt.topt.tuples_only));
233 234 235
	fprintf(fout, _(" \\T TEXT        set HTML table tag attributes\n"));
	fprintf(fout, _(" \\unset NAME    unset (delete) internal variable\n"));
	fprintf(fout, _(" \\w FILENAME    write current query buffer to file\n"));
236 237
	fprintf(fout, _(" \\x             toggle expanded output (currently %s)\n"),
			ON(pset.popt.topt.expanded));
238 239
	fprintf(fout, _(" \\z             list table access privileges\n"));
	fprintf(fout, _(" \\! [COMMAND]   execute command in shell or start interactive shell\n"));
Bruce Momjian's avatar
Bruce Momjian committed
240 241 242 243

	if (usePipe)
	{
		pclose(fout);
Bruce Momjian's avatar
Hi!  
Bruce Momjian committed
244
#ifndef WIN32
Bruce Momjian's avatar
Bruce Momjian committed
245
		pqsignal(SIGPIPE, SIG_DFL);
Bruce Momjian's avatar
Hi!  
Bruce Momjian committed
246
#endif
Bruce Momjian's avatar
Bruce Momjian committed
247
	}
248 249 250 251 252 253 254 255 256 257 258
}



/*
 * helpSQL -- help with SQL commands
 *
 */
void
helpSQL(const char *topic)
{
259 260
#define VALUE_OR_NULL(a) ((a) ? (a) : "")

Bruce Momjian's avatar
Bruce Momjian committed
261
	if (!topic || strlen(topic) == 0)
262
	{
263
		int			i;
264
		int			items_per_column = (QL_HELP_COUNT + 2) / 3;
Bruce Momjian's avatar
Bruce Momjian committed
265

266
		puts(_("Available help:"));
Bruce Momjian's avatar
Bruce Momjian committed
267

268
		for (i = 0; i < items_per_column; i++)
Bruce Momjian's avatar
Bruce Momjian committed
269
		{
Peter Eisentraut's avatar
Peter Eisentraut committed
270
			printf("  %-26s%-26s",
271 272
				   VALUE_OR_NULL(QL_HELP[i].cmd),
				   VALUE_OR_NULL(QL_HELP[i + items_per_column].cmd));
273
			if (i + 2 * items_per_column < QL_HELP_COUNT)
Peter Eisentraut's avatar
Peter Eisentraut committed
274
				printf("%-26s",
275
				   VALUE_OR_NULL(QL_HELP[i + 2 * items_per_column].cmd));
276
			fputc('\n', stdout);
Bruce Momjian's avatar
Bruce Momjian committed
277
		}
278 279
	}

Bruce Momjian's avatar
Bruce Momjian committed
280
	else
281
	{
Bruce Momjian's avatar
Bruce Momjian committed
282 283
		int			i;
		bool		help_found = false;
284
		size_t		len;
Peter Eisentraut's avatar
Peter Eisentraut committed
285 286 287

		/* don't care about trailing spaces */
		len = strlen(topic);
288
		while (topic[len - 1] == ' ')
Peter Eisentraut's avatar
Peter Eisentraut committed
289
			len--;
Bruce Momjian's avatar
Bruce Momjian committed
290 291 292

		for (i = 0; QL_HELP[i].cmd; i++)
		{
Peter Eisentraut's avatar
Peter Eisentraut committed
293
			if (strncasecmp(topic, QL_HELP[i].cmd, len) == 0 ||
Bruce Momjian's avatar
Bruce Momjian committed
294 295 296
				strcmp(topic, "*") == 0)
			{
				help_found = true;
297 298 299
				printf(_("Command:     %s\n"
						 "Description: %s\n"
						 "Syntax:\n%s\n\n"),
300
					 QL_HELP[i].cmd, QL_HELP[i].help, QL_HELP[i].syntax);
301 302 303
				/* If we have an exact match, exit.  Fixes \h SELECT */
				if (strcasecmp(topic, QL_HELP[i].cmd) == 0)
					break;
Bruce Momjian's avatar
Bruce Momjian committed
304 305 306 307
			}
		}

		if (!help_found)
308
			printf(_("No help available for '%-.*s'.\nTry \\h with no arguments to see available help.\n"), (int) len, topic);
309 310 311 312 313 314 315 316
	}
}



void
print_copyright(void)
{
Bruce Momjian's avatar
Bruce Momjian committed
317
	puts(
318
		 "PostgreSQL Data Base Management System\n\n"
319
		 "Portions Copyright (c) 1996-2001, PostgreSQL Global Development Group\n\n"
320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337
		 "This software is based on Postgres95, formerly known as Postgres, which\n"
		 "contains the following notice:\n\n"
		 "Portions Copyright(c) 1994 - 7 Regents of the University of California\n\n"
		 "Permission to use, copy, modify, and distribute this software and its\n"
		 "documentation for any purpose, without fee, and without a written agreement\n"
		 "is hereby granted, provided that the above copyright notice and this paragraph\n"
		 "and the following two paragraphs appear in all copies.\n\n"
		 "IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR\n"
		 "DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST\n"
		 "PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF\n"
		 "THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH\n"
		 "DAMAGE.\n\n"
		 "THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING,\n"
		 "BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A\n"
		 "PARTICULAR PURPOSE.THE SOFTWARE PROVIDED HEREUNDER IS ON AN \"AS IS\" BASIS,\n"
		 "AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE,\n"
		 "SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS."
	);
338
}