help.c 9.85 KB
Newer Older
Peter Eisentraut's avatar
Peter Eisentraut committed
1 2 3 4 5
/*
 * psql - the PostgreSQL interactive terminal
 *
 * Copyright 2000 by PostgreSQL Global Development Team
 *
Bruce Momjian's avatar
Bruce Momjian committed
6
 * $Header: /cvsroot/pgsql/src/bin/psql/help.c,v 1.14 2000/01/26 16:10:01 momjian Exp $
Peter Eisentraut's avatar
Peter Eisentraut committed
7
 */
8 9 10 11 12 13 14 15
#include <c.h>
#include "help.h"

#include <stdio.h>
#include <stdlib.h>
#include <signal.h>

#ifndef WIN32
Bruce Momjian's avatar
Bruce Momjian committed
16
#include <sys/ioctl.h>			/* for ioctl() */
17
#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 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38
#else
#define strcasecmp(x,y) stricmp(x,y)
#define popen(x,y) _popen(x,y)
#define pclose(x) _pclose(x)
#endif

#include <pqsignal.h>
#include <libpq-fe.h>

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


/*
 * usage
 *
39
 * print out command line arguments
40 41 42
 */
#define ON(var) (var ? "on" : "off")

Bruce Momjian's avatar
Bruce Momjian committed
43 44
void
usage(void)
45
{
Bruce Momjian's avatar
Bruce Momjian committed
46 47 48
	const char *env;
	const char *user;

49
#ifndef WIN32
Bruce Momjian's avatar
Bruce Momjian committed
50 51
	struct passwd *pw = NULL;

52 53
#endif

Bruce Momjian's avatar
Bruce Momjian committed
54 55 56 57
	/* Find default user, in case we need it. */
	user = getenv("USER");
	if (!user)
	{
58
#ifndef WIN32
Bruce Momjian's avatar
Bruce Momjian committed
59 60 61 62 63 64 65 66
		pw = getpwuid(getuid());
		if (pw)
			user = pw->pw_name;
		else
		{
			perror("getpwuid()");
			exit(EXIT_FAILURE);
		}
67
#else
Bruce Momjian's avatar
Bruce Momjian committed
68
		user = "?";
69
#endif
Bruce Momjian's avatar
Bruce Momjian committed
70
	}
71

72 73 74 75 76
/* If this " is the start of the string then it ought to end there to fit in 80 columns >> " */
    puts(  "This is psql, the PostgreSQL interactive terminal.");
	puts(  "\nUsage:");
    puts(  "  psql [options] [dbname [username]]");
    puts(  "\nOptions:");
Peter Eisentraut's avatar
Peter Eisentraut committed
77 78
	puts(  "  -A              Unaligned table output mode (-P format=unaligned)");
	puts(  "  -c <query>      Run only single query (or slash command) and exit");
Bruce Momjian's avatar
Bruce Momjian committed
79 80 81 82 83

	/* Display default database */
	env = getenv("PGDATABASE");
	if (!env)
		env = user;
Peter Eisentraut's avatar
Peter Eisentraut committed
84
	printf("  -d <dbname>     Specify database name to connect to (default: %s)\n", env);
Bruce Momjian's avatar
Bruce Momjian committed
85

86 87
	puts(  "  -e              Echo all input in non-interactive mode");
	puts(  "  -E              Display queries that internal commands generate");
Peter Eisentraut's avatar
Peter Eisentraut committed
88 89
	puts(  "  -f <filename>   Execute queries from file, then exit");
	puts(  "  -F <string>     Set field separator (default: \"" DEFAULT_FIELD_SEP "\") (-P fieldsep=)");
Bruce Momjian's avatar
Bruce Momjian committed
90 91 92

	/* Display default host */
	env = getenv("PGHOST");
Peter Eisentraut's avatar
Peter Eisentraut committed
93
	printf("  -h <host>       Specify database server host (default: ");
Bruce Momjian's avatar
Bruce Momjian committed
94
	if (env)
95
		fputs(env, stdout);
Bruce Momjian's avatar
Bruce Momjian committed
96
	else
97 98
		fputs("domain socket", stdout);
	puts(")");
Bruce Momjian's avatar
Bruce Momjian committed
99

100 101 102
	puts(  "  -H              HTML table output mode (-P format=html)");
	puts(  "  -l              List available databases, then exit");
	puts(  "  -n              Do not use readline or history");
Peter Eisentraut's avatar
Peter Eisentraut committed
103
	puts(  "  -o <filename>   Send query output to filename (or |pipe)");
Bruce Momjian's avatar
Bruce Momjian committed
104 105 106

	/* Display default port */
	env = getenv("PGPORT");
Peter Eisentraut's avatar
Peter Eisentraut committed
107
	printf("  -p <port>       Specify database server port (default: %s)\n",
Bruce Momjian's avatar
Bruce Momjian committed
108
	   env ? env : "hardwired");
Bruce Momjian's avatar
Bruce Momjian committed
109

110 111 112 113 114 115
	puts(  "  -P var[=arg]    Set printing option 'var' to 'arg' (see \\pset command)");
	puts(  "  -q              Run quietly (no messages, only query output)");
	puts(  "  -s              Single step mode (confirm each query)");
	puts(  "  -S              Single line mode (newline terminates query)");
	puts(  "  -t              Don't print headings and row count (-P tuples_only)");
	puts(  "  -T text         Set HTML table tag options (width, border) (-P tableattr=)");
Bruce Momjian's avatar
Bruce Momjian committed
116 117 118 119 120

	/* Display default user */
	env = getenv("PGUSER");
	if (!env)
		env = user;
Peter Eisentraut's avatar
Peter Eisentraut committed
121
	printf("  -U <username>   Specifiy username, \"?\"=prompt (default user: %s)\n", env);
Bruce Momjian's avatar
Bruce Momjian committed
122

123 124 125 126
	puts(  "  -x              Turn on expanded table output (-P expanded)");
	puts(  "  -v name=val     Set psql variable 'name' to 'value'");
	puts(  "  -V              Show version information and exit");
	puts(  "  -W              Prompt for password (should happen automatically)");
Bruce Momjian's avatar
Bruce Momjian committed
127

128
    puts(  "\nFor more information, type \"\\?\" (for internal commands) or \"\\help\"");
Peter Eisentraut's avatar
Peter Eisentraut committed
129 130 131
    puts(  "(for SQL commands) from within psql, or consult the psql section in");
    puts(  "the PostgreSQL manual, which accompanies the distribution and is also");
    puts(  "available at <http://www.postgresql.org>.");
132
    puts(  "Report bugs to <pgsql-bugs@postgresql.org>.");
133 134

#ifndef WIN32
Bruce Momjian's avatar
Bruce Momjian committed
135 136
	if (pw)
		free(pw);
137 138 139 140 141 142 143 144 145 146 147 148
#endif
}



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

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

155 156 157
#endif

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

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

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

	/* if you add/remove a line here, change the row test above */
193 194
	fprintf(fout, " \\?             help\n");
	fprintf(fout, " \\c[onnect] [dbname|- [user|?]]\n"
Bruce Momjian's avatar
Bruce Momjian committed
195
		  "                 connect to new database (currently '%s')\n", PQdb(pset.db));
196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211
	fprintf(fout, " \\copy ...      perform SQL COPY with data stream to the client machine");
	fprintf(fout, " \\copyright     show PostgreSQL usage and distribution terms\n");
	fprintf(fout, " \\d <table>     describe table (or view, index, sequence)\n");
	fprintf(fout, " \\d{i|s|t|v|S}  list only indices/sequences/tables/views/system tables\n");
	fprintf(fout, " \\da            list aggregates\n");
	fprintf(fout, " \\dd [object]   list comment for table, type, function, or operator\n");
	fprintf(fout, " \\df            list functions\n");
	fprintf(fout, " \\do            list operators\n");
	fprintf(fout, " \\dT            list data types\n");
	fprintf(fout, " \\e [fname]     edit the current query buffer or <fname> with external editor\n");
	fprintf(fout, " \\echo <text>   write text to stdout\n");
	fprintf(fout, " \\g [fname]     send query to backend (and results in <fname> or |pipe)\n");
	fprintf(fout, " \\h [cmd]       help on syntax of sql commands, * for all commands\n");
	fprintf(fout, " \\i <fname>     read and execute queries from filename\n");
	fprintf(fout, " \\l             list all databases\n");
	fprintf(fout, " \\lo_export, \\lo_import, \\lo_list, \\lo_unlink\n"
Bruce Momjian's avatar
Bruce Momjian committed
212
		  "                 large object operations\n");
213 214 215 216 217 218 219
	fprintf(fout, " \\o [fname]     send all query results to <fname>, or |pipe\n");
	fprintf(fout, " \\p             show the content of the current query buffer\n");
	fprintf(fout, " \\pset [opt]    set table output options\n");
	fprintf(fout, " \\q             quit psql\n");
	fprintf(fout, " \\qecho <text>  write text to query output stream (see \\o)\n");
	fprintf(fout, " \\r             reset (clear) the query buffer\n");
	fprintf(fout, " \\s [fname]     print history or save it in <fname>\n");
220 221 222 223
	fprintf(fout, " \\set <var> <value>  set internal variable\n");
	fprintf(fout, " \\t             don't show table headers or footers (currently %s)\n", ON(pset.popt.topt.tuples_only));
	fprintf(fout, " \\unset <var>   unset (delete) internal variable\n");
	fprintf(fout, " \\x             toggle expanded output (currently %s)\n", ON(pset.popt.topt.expanded));
224 225 226
	fprintf(fout, " \\w <fname>     write current query buffer to a file\n");
	fprintf(fout, " \\z             list table access permissions\n");
	fprintf(fout, " \\! [cmd]       shell escape or command\n");
Bruce Momjian's avatar
Bruce Momjian committed
227 228 229 230

	if (usePipe)
	{
		pclose(fout);
Bruce Momjian's avatar
Hi!  
Bruce Momjian committed
231
#ifndef WIN32
Bruce Momjian's avatar
Bruce Momjian committed
232
		pqsignal(SIGPIPE, SIG_DFL);
Bruce Momjian's avatar
Hi!  
Bruce Momjian committed
233
#endif
Bruce Momjian's avatar
Bruce Momjian committed
234
	}
235 236 237 238 239 240 241 242 243 244 245
}



/*
 * helpSQL -- help with SQL commands
 *
 */
void
helpSQL(const char *topic)
{
Bruce Momjian's avatar
Bruce Momjian committed
246
	if (!topic || strlen(topic) == 0)
247
	{
Bruce Momjian's avatar
Bruce Momjian committed
248 249 250
		char		left_center_right;	/* Which column we're displaying */
		int			i;			/* Index into QL_HELP[] */

251
		puts("Available help:");
Bruce Momjian's avatar
Bruce Momjian committed
252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275

		left_center_right = 'L';/* Start with left column */
		i = 0;
		while (QL_HELP[i].cmd != NULL)
		{
			switch (left_center_right)
			{
				case 'L':
					printf("    %-25s", QL_HELP[i].cmd);
					left_center_right = 'C';
					break;
				case 'C':
					printf("%-25s", QL_HELP[i].cmd);
					left_center_right = 'R';
					break;
				case 'R':
					printf("%-25s\n", QL_HELP[i].cmd);
					left_center_right = 'L';
					break;
			}
			i++;
		}
		if (left_center_right != 'L')
			puts("\n");
276 277
	}

Bruce Momjian's avatar
Bruce Momjian committed
278
	else
279
	{
Bruce Momjian's avatar
Bruce Momjian committed
280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295
		int			i;
		bool		help_found = false;

		for (i = 0; QL_HELP[i].cmd; i++)
		{
			if (strcasecmp(QL_HELP[i].cmd, topic) == 0 ||
				strcmp(topic, "*") == 0)
			{
				help_found = true;
				printf("Command: %s\nDescription: %s\nSyntax:\n%s\n\n",
					 QL_HELP[i].cmd, QL_HELP[i].help, QL_HELP[i].syntax);
			}
		}

		if (!help_found)
			printf("No help available for '%s'.\nTry \\h with no arguments to see available help.\n", topic);
296 297 298 299 300 301 302 303 304
	}
}




void
print_copyright(void)
{
Bruce Momjian's avatar
Bruce Momjian committed
305
	puts(
Bruce Momjian's avatar
Bruce Momjian committed
306
		 "PostgreSQL Data Base Management System\n\n"
Bruce Momjian's avatar
Bruce Momjian committed
307
	 "Portions Copyright (c) 1996-2000, PostgreSQL, Inc\n\n"
Bruce Momjian's avatar
Bruce Momjian committed
308 309
		 "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
310
	 "Portions Copyright(c) 1994 - 7 Regents of the University of California\n\n"
Bruce Momjian's avatar
Bruce Momjian committed
311 312 313 314 315 316 317 318 319 320 321 322 323 324
		 "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.");
325
}