help.c 13.5 KB
Newer Older
Peter Eisentraut's avatar
Peter Eisentraut committed
1 2 3
/*
 * psql - the PostgreSQL interactive terminal
 *
Bruce Momjian's avatar
Bruce Momjian committed
4
 * Copyright (c) 2000-2004, PostgreSQL Global Development Group
Peter Eisentraut's avatar
Peter Eisentraut committed
5
 *
6
 * $PostgreSQL: pgsql/src/bin/psql/help.c,v 1.94 2004/10/06 18:39:16 momjian Exp $
Peter Eisentraut's avatar
Peter Eisentraut committed
7
 */
8
#include "postgres_fe.h"
9
#include "common.h"
10
#include "print.h"
11 12 13
#include "help.h"

#include <signal.h>
14
#include <errno.h>
15 16 17

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

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

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

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

35 36 37 38 39 40 41
/*
 * 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.
 */

42 43 44 45

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

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

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

Bruce Momjian's avatar
Bruce Momjian committed
60
	/* Find default user, in case we need it. */
61
	user = getenv("PGUSER");
Bruce Momjian's avatar
Bruce Momjian committed
62 63
	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);
		}
Bruce Momjian's avatar
Bruce Momjian committed
73
#else							/* WIN32 */
74 75 76 77 78
		char		buf[128];
		DWORD		bufsize = sizeof(buf) - 1;

		if (GetUserName(buf, &bufsize))
			user = buf;
Bruce Momjian's avatar
Bruce Momjian committed
79
#endif   /* WIN32 */
Bruce Momjian's avatar
Bruce Momjian committed
80
	}
81

82
/* If this " is the start of the string then it ought to end there to fit in 80 columns >> " */
83
	printf(_("This is psql %s, the PostgreSQL interactive terminal.\n\n"),
84
		   PG_VERSION);
85
	puts(_("Usage:"));
86
	puts(_("  psql [OPTIONS]... [DBNAME [USERNAME]]\n"));
Bruce Momjian's avatar
Bruce Momjian committed
87

88
	puts(_("General options:"));
Bruce Momjian's avatar
Bruce Momjian committed
89 90 91 92
	/* Display default database */
	env = getenv("PGDATABASE");
	if (!env)
		env = user;
93
	printf(_("  -d DBNAME       specify database name to connect to (default: \"%s\")\n"), env);
94 95 96
	puts(_("  -c COMMAND      run only single command (SQL or internal) and exit"));
	puts(_("  -f FILENAME     execute commands from file, then exit"));
	puts(_("  -l              list available databases, then exit"));
97
	puts(_("  -v NAME=VALUE   set psql variable NAME to VALUE"));
98 99 100 101 102 103 104 105 106 107 108
	puts(_("  -X              do not read startup file (~/.psqlrc)"));
	puts(_("  --help          show this help, then exit"));
	puts(_("  --version       output version information, then exit"));

	puts(_("\nInput and output options:"));
	puts(_("  -a              echo all input from script"));
	puts(_("  -e              echo commands sent to server"));
	puts(_("  -E              display queries that internal commands generate"));
	puts(_("  -q              run quietly (no messages, only query output)"));
	puts(_("  -o FILENAME     send query results to file (or |pipe)"));
	puts(_("  -n              disable enhanced command line editing (readline)"));
109 110
	puts(_("  -s              single-step mode (confirm each query)"));
	puts(_("  -S              single-line mode (end of line terminates SQL command)"));
111 112 113 114 115 116 117

	puts(_("\nOutput format options:"));
	puts(_("  -A              unaligned table output mode (-P format=unaligned)"));
	puts(_("  -H              HTML table output mode (-P format=html)"));
	puts(_("  -t              print rows only (-P tuples_only)"));
	puts(_("  -T TEXT         set HTML table tag attributes (width, border) (-P tableattr=)"));
	puts(_("  -x              turn on expanded table output (-P expanded)"));
118
	puts(_("  -P VAR[=ARG]    set printing option VAR to ARG (see \\pset command)"));
119
	printf(_("  -F STRING       set field separator (default: \"%s\") (-P fieldsep=)\n"),
120
		   DEFAULT_FIELD_SEP);
121
	puts(_("  -R STRING       set record separator (default: newline) (-P recordsep=)"));
Bruce Momjian's avatar
Bruce Momjian committed
122

123
	puts(_("\nConnection options:"));
Bruce Momjian's avatar
Bruce Momjian committed
124 125
	/* Display default host */
	env = getenv("PGHOST");
126
	printf(_("  -h HOSTNAME     database server host or socket directory (default: \"%s\")\n"),
127
		   env ? env : _("local socket"));
Bruce Momjian's avatar
Bruce Momjian committed
128 129
	/* Display default port */
	env = getenv("PGPORT");
130
	printf(_("  -p PORT         database server port (default: \"%s\")\n"),
131
		   env ? env : DEF_PGPORT_STR);
Bruce Momjian's avatar
Bruce Momjian committed
132 133 134 135
	/* Display default user */
	env = getenv("PGUSER");
	if (!env)
		env = user;
136
	printf(_("  -U NAME         database user name (default: \"%s\")\n"), env);
137
	puts(_("  -W              prompt for password (should happen automatically)"));
138 139

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


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

#ifndef TIOCGWINSZ
Bruce Momjian's avatar
Bruce Momjian committed
154 155 156 157
struct winsize
{
	int			ws_row;
	int			ws_col;
158 159 160 161
};
#endif

void
162
slashUsage(unsigned short int pager)
163
{
164
	FILE	   *output;
165

166
	output = PageOutput(67, pager);
167

168
	/* if you add/remove a line here, change the row count above */
Bruce Momjian's avatar
Bruce Momjian committed
169 170 171 172 173

	/*
	 * if this " is the start of the string then it ought to end there to
	 * fit in 80 columns >> "
	 */
174
	fprintf(output, _("General\n"));
175
	fprintf(output, _("  \\c[onnect] [DBNAME|- [USER]]\n"
Bruce Momjian's avatar
Bruce Momjian committed
176
		"                 connect to new database (currently \"%s\")\n"),
177
			PQdb(pset.db));
178 179
	fprintf(output, _("  \\cd [DIR]      change the current working directory\n"));
	fprintf(output, _("  \\copyright     show PostgreSQL usage and distribution terms\n"));
180 181
	fprintf(output, _("  \\encoding [ENCODING]\n"
					  "                 show or set client encoding\n"));
182 183
	fprintf(output, _("  \\h [NAME]      help on syntax of SQL commands, * for all commands\n"));
	fprintf(output, _("  \\q             quit psql\n"));
184 185
	fprintf(output, _("  \\set [NAME [VALUE]]\n"
					  "                 set internal variable, or list all if no parameters\n"));
186
	fprintf(output, _("  \\timing        toggle timing of commands (currently %s)\n"),
187
			ON(pset.timing));
188 189
	fprintf(output, _("  \\unset NAME    unset (delete) internal variable\n"));
	fprintf(output, _("  \\! [COMMAND]   execute command in shell or start interactive shell\n"));
190
	fprintf(output, "\n");
191 192

	fprintf(output, _("Query Buffer\n"));
193 194 195 196
	fprintf(output, _("  \\e [FILE]      edit the query buffer (or file) with external editor\n"));
	fprintf(output, _("  \\g [FILE]      send query buffer to server (and results to file or |pipe)\n"));
	fprintf(output, _("  \\p             show the contents of the query buffer\n"));
	fprintf(output, _("  \\r             reset (clear) the query buffer\n"));
197
#ifdef USE_READLINE
198
	fprintf(output, _("  \\s [FILE]      display history or save it to file\n"));
199
#endif
200
	fprintf(output, _("  \\w FILE        write query buffer to file\n"));
201
	fprintf(output, "\n");
202

203
	fprintf(output, _("Input/Output\n"));
204
	fprintf(output, _("  \\echo [STRING] write string to standard output\n"));
205
	fprintf(output, _("  \\i FILE        execute commands from file\n"));
206
	fprintf(output, _("  \\o [FILE]      send all query results to file or |pipe\n"));
207
	fprintf(output, _("  \\qecho [STRING]\n"
Bruce Momjian's avatar
Bruce Momjian committed
208
	"                 write string to query output stream (see \\o)\n"));
209
	fprintf(output, "\n");
210

211
	fprintf(output, _("Informational\n"));
212 213 214 215
	fprintf(output, _("  \\d [NAME]      describe table, index, sequence, or view\n"));
	fprintf(output, _("  \\d{t|i|s|v|S} [PATTERN] (add \"+\" for more detail)\n"
					  "                 list tables/indexes/sequences/views/system tables\n"));
	fprintf(output, _("  \\da [PATTERN]  list aggregate functions\n"));
216
	fprintf(output, _("  \\db [PATTERN]  list tablespaces (add \"+\" for more detail)\n"));
217 218 219 220 221
	fprintf(output, _("  \\dc [PATTERN]  list conversions\n"));
	fprintf(output, _("  \\dC            list casts\n"));
	fprintf(output, _("  \\dd [PATTERN]  show comment for object\n"));
	fprintf(output, _("  \\dD [PATTERN]  list domains\n"));
	fprintf(output, _("  \\df [PATTERN]  list functions (add \"+\" for more detail)\n"));
222
	fprintf(output, _("  \\dg [PATTERN]  list groups\n"));
223
	fprintf(output, _("  \\dn [PATTERN]  list schemas (add \"+\" for more detail)\n"));
224 225
	fprintf(output, _("  \\do [NAME]     list operators\n"));
	fprintf(output, _("  \\dl            list large objects, same as \\lo_list\n"));
226
	fprintf(output, _("  \\dp [PATTERN]  list table, view and sequence access privileges\n"));
227 228 229
	fprintf(output, _("  \\dT [PATTERN]  list data types (add \"+\" for more detail)\n"));
	fprintf(output, _("  \\du [PATTERN]  list users\n"));
	fprintf(output, _("  \\l             list all databases (add \"+\" for more detail)\n"));
230
	fprintf(output, _("  \\z [PATTERN]   list table, view and sequence access privileges (same as \\dp)\n"));
231
	fprintf(output, "\n");
232 233

	fprintf(output, _("Formatting\n"));
234 235 236 237
	fprintf(output, _("  \\a             toggle between unaligned and aligned output mode\n"));
	fprintf(output, _("  \\C [STRING]    set table title, or unset if none\n"));
	fprintf(output, _("  \\f [STRING]    show or set field separator for unaligned query output\n"));
	fprintf(output, _("  \\H             toggle HTML output mode (currently %s)\n"),
238
			ON(pset.popt.topt.format == PRINT_HTML));
239 240
	fprintf(output, _("  \\pset NAME [VALUE]\n"
					  "                 set table output option\n"
241
					  "                 (NAME := {format|border|expanded|fieldsep|footer|null|\n"
Bruce Momjian's avatar
Bruce Momjian committed
242
	"                 recordsep|tuples_only|title|tableattr|pager})\n"));
243 244 245 246 247
	fprintf(output, _("  \\t             show only rows (currently %s)\n"),
			ON(pset.popt.topt.tuples_only));
	fprintf(output, _("  \\T [STRING]    set HTML <table> tag attributes, or unset if none\n"));
	fprintf(output, _("  \\x             toggle expanded output (currently %s)\n"),
			ON(pset.popt.topt.expanded));
248
	fprintf(output, "\n");
Bruce Momjian's avatar
Bruce Momjian committed
249

250 251
	fprintf(output, _("Copy, Large Object\n"));
	fprintf(output, _("  \\copy ...      perform SQL COPY with data stream to the client host\n"));
Bruce Momjian's avatar
Bruce Momjian committed
252 253
	fprintf(output, _("  \\lo_export LOBOID FILE\n"
					  "  \\lo_import FILE [COMMENT] \n"
254
					  "  \\lo_list\n"
Bruce Momjian's avatar
Bruce Momjian committed
255
				   "  \\lo_unlink LOBOID    large object operations\n"));
256

257
	if (output != stdout)
Bruce Momjian's avatar
Bruce Momjian committed
258
	{
259
		pclose(output);
Bruce Momjian's avatar
Hi!  
Bruce Momjian committed
260
#ifndef WIN32
Bruce Momjian's avatar
Bruce Momjian committed
261
		pqsignal(SIGPIPE, SIG_DFL);
Bruce Momjian's avatar
Hi!  
Bruce Momjian committed
262
#endif
Bruce Momjian's avatar
Bruce Momjian committed
263
	}
264 265 266 267 268 269 270 271 272
}



/*
 * helpSQL -- help with SQL commands
 *
 */
void
273
helpSQL(const char *topic, unsigned short int pager)
274
{
275 276
#define VALUE_OR_NULL(a) ((a) ? (a) : "")

Bruce Momjian's avatar
Bruce Momjian committed
277
	if (!topic || strlen(topic) == 0)
278
	{
279
		int			i;
280
		int			items_per_column = (QL_HELP_COUNT + 2) / 3;
Bruce Momjian's avatar
Bruce Momjian committed
281
		FILE	   *output;
282

Bruce Momjian's avatar
Bruce Momjian committed
283
		output = PageOutput(items_per_column + 1, pager);
Bruce Momjian's avatar
Bruce Momjian committed
284

285
		fputs(_("Available help:\n"), output);
Bruce Momjian's avatar
Bruce Momjian committed
286

287
		for (i = 0; i < items_per_column; i++)
Bruce Momjian's avatar
Bruce Momjian committed
288
		{
289
			fprintf(output, "  %-26s%-26s",
Bruce Momjian's avatar
Bruce Momjian committed
290 291
					VALUE_OR_NULL(QL_HELP[i].cmd),
					VALUE_OR_NULL(QL_HELP[i + items_per_column].cmd));
292
			if (i + 2 * items_per_column < QL_HELP_COUNT)
293
				fprintf(output, "%-26s",
294
				   VALUE_OR_NULL(QL_HELP[i + 2 * items_per_column].cmd));
295 296 297 298 299 300 301 302 303
			fputc('\n', output);
		}
		/* Only close if we used the pager */
		if (output != stdout)
		{
			pclose(output);
#ifndef WIN32
			pqsignal(SIGPIPE, SIG_DFL);
#endif
Bruce Momjian's avatar
Bruce Momjian committed
304
		}
305
	}
Bruce Momjian's avatar
Bruce Momjian committed
306
	else
307
	{
Bruce Momjian's avatar
Bruce Momjian committed
308 309
		int			i;
		bool		help_found = false;
310
		FILE	   *output;
311
		size_t		len;
312
		int			nl_count = 0;
Bruce Momjian's avatar
Bruce Momjian committed
313
		char	   *ch;
314

315
		/* don't care about trailing spaces or semicolons */
Peter Eisentraut's avatar
Peter Eisentraut committed
316
		len = strlen(topic);
317
		while (topic[len - 1] == ' ' || topic[len - 1] == ';')
Peter Eisentraut's avatar
Peter Eisentraut committed
318
			len--;
Bruce Momjian's avatar
Bruce Momjian committed
319

320 321 322
		/* Count newlines for pager */
		for (i = 0; QL_HELP[i].cmd; i++)
		{
323
			if (pg_strncasecmp(topic, QL_HELP[i].cmd, len) == 0 ||
324 325 326 327 328 329 330
				strcmp(topic, "*") == 0)
			{
				nl_count += 5;
				for (ch = QL_HELP[i].syntax; *ch != '\0'; ch++)
					if (*ch == '\n')
						nl_count++;
				/* If we have an exact match, exit.  Fixes \h SELECT */
331
				if (pg_strcasecmp(topic, QL_HELP[i].cmd) == 0)
332 333 334 335 336 337
					break;
			}
		}

		output = PageOutput(nl_count, pager);

Bruce Momjian's avatar
Bruce Momjian committed
338 339
		for (i = 0; QL_HELP[i].cmd; i++)
		{
340
			if (pg_strncasecmp(topic, QL_HELP[i].cmd, len) == 0 ||
Bruce Momjian's avatar
Bruce Momjian committed
341 342 343
				strcmp(topic, "*") == 0)
			{
				help_found = true;
344
				fprintf(output, _("Command:     %s\n"
345 346 347 348 349
								  "Description: %s\n"
								  "Syntax:\n%s\n\n"),
						QL_HELP[i].cmd,
						gettext(QL_HELP[i].help),
						gettext(QL_HELP[i].syntax));
350
				/* If we have an exact match, exit.  Fixes \h SELECT */
351
				if (pg_strcasecmp(topic, QL_HELP[i].cmd) == 0)
352
					break;
Bruce Momjian's avatar
Bruce Momjian committed
353 354 355 356
			}
		}

		if (!help_found)
357 358 359 360 361 362 363 364 365 366
			fprintf(output, _("No help available for \"%-.*s\".\nTry \\h with no arguments to see available help.\n"), (int) len, topic);

		/* Only close if we used the pager */
		if (output != stdout)
		{
			pclose(output);
#ifndef WIN32
			pqsignal(SIGPIPE, SIG_DFL);
#endif
		}
367 368 369 370 371 372 373 374
	}
}



void
print_copyright(void)
{
Bruce Momjian's avatar
Bruce Momjian committed
375
	puts(
376
		 "PostgreSQL Data Base Management System\n\n"
Bruce Momjian's avatar
Bruce Momjian committed
377
		 "Portions Copyright (c) 1996-2004, PostgreSQL Global Development Group\n\n"
378 379
		 "This software is based on Postgres95, formerly known as Postgres, which\n"
		 "contains the following notice:\n\n"
Bruce Momjian's avatar
Bruce Momjian committed
380
		 "Portions Copyright(c) 1994, Regents of the University of California\n\n"
381 382 383 384 385 386 387 388 389 390 391 392 393 394
		 "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."
395
		);
396
}