2 * psql - the PostgreSQL interactive terminal
4 * Copyright (c) 2000-2004, PostgreSQL Global Development Group
6 * $PostgreSQL: pgsql/src/bin/psql/help.c,v 1.95 2004/10/12 21:54:44 petere Exp $
8 #include "postgres_fe.h"
18 #include <pwd.h> /* for getpwuid() */
20 #include <sys/types.h> /* (ditto) */
21 #include <unistd.h> /* for getuid() */
33 #define _(x) gettext((x))
37 * If you change something in this file, also make the same changes
38 * in the DocBook documentation, file ref/psql-ref.sgml. If you don't
39 * know how to do it, please find someone who can help you.
46 * print out command line arguments
48 #define ON(var) (var ? _("on") : _("off"))
57 struct passwd *pw = NULL;
60 /* Find default user, in case we need it. */
61 user = getenv("PGUSER");
65 pw = getpwuid(geteuid());
70 psql_error("could not get current user name: %s\n", strerror(errno));
75 DWORD bufsize = sizeof(buf) - 1;
77 if (GetUserName(buf, &bufsize))
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"),
86 puts(_(" psql [OPTIONS]... [DBNAME [USERNAME]]\n"));
88 puts(_("General options:"));
89 /* Display default database */
90 env = getenv("PGDATABASE");
93 printf(_(" -d DBNAME specify database name to connect to (default: \"%s\")\n"), env);
94 puts(_(" -c COMMAND run only single command (SQL or internal) and exit"));
95 puts(_(" -f FILENAME execute commands from file, then exit"));
96 puts(_(" -l list available databases, then exit"));
97 puts(_(" -v NAME=VALUE set psql variable NAME to VALUE"));
98 puts(_(" -X do not read startup file (~/.psqlrc)"));
99 puts(_(" --help show this help, then exit"));
100 puts(_(" --version output version information, then exit"));
102 puts(_("\nInput and output options:"));
103 puts(_(" -a echo all input from script"));
104 puts(_(" -e echo commands sent to server"));
105 puts(_(" -E display queries that internal commands generate"));
106 puts(_(" -q run quietly (no messages, only query output)"));
107 puts(_(" -o FILENAME send query results to file (or |pipe)"));
108 puts(_(" -n disable enhanced command line editing (readline)"));
109 puts(_(" -s single-step mode (confirm each query)"));
110 puts(_(" -S single-line mode (end of line terminates SQL command)"));
112 puts(_("\nOutput format options:"));
113 puts(_(" -A unaligned table output mode (-P format=unaligned)"));
114 puts(_(" -H HTML table output mode (-P format=html)"));
115 puts(_(" -t print rows only (-P tuples_only)"));
116 puts(_(" -T TEXT set HTML table tag attributes (width, border) (-P tableattr=)"));
117 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"),
121 puts(_(" -R STRING set record separator (default: newline) (-P recordsep=)"));
123 puts(_("\nConnection options:"));
124 /* Display default host */
125 env = getenv("PGHOST");
126 printf(_(" -h HOSTNAME database server host or socket directory (default: \"%s\")\n"),
127 env ? env : _("local socket"));
128 /* Display default port */
129 env = getenv("PGPORT");
130 printf(_(" -p PORT database server port (default: \"%s\")\n"),
131 env ? env : DEF_PGPORT_STR);
132 /* Display default user */
133 env = getenv("PGUSER");
136 printf(_(" -U NAME database user name (default: \"%s\")\n"), env);
137 puts(_(" -W prompt for password (should happen automatically)"));
140 "\nFor more information, type \"\\?\" (for internal commands) or \"\\help\"\n"
141 "(for SQL commands) from within psql, or consult the psql section in\n"
142 "the PostgreSQL documentation.\n\n"
143 "Report bugs to <pgsql-bugs@postgresql.org>."));
150 * print out help for the backslash commands
162 slashUsage(unsigned short int pager)
166 output = PageOutput(67, pager);
168 /* if you add/remove a line here, change the row count above */
171 * if this " is the start of the string then it ought to end there to
172 * fit in 80 columns >> "
174 fprintf(output, _("General\n"));
175 fprintf(output, _(" \\c[onnect] [DBNAME|- [USER]]\n"
176 " connect to new database (currently \"%s\")\n"),
178 fprintf(output, _(" \\cd [DIR] change the current working directory\n"));
179 fprintf(output, _(" \\copyright show PostgreSQL usage and distribution terms\n"));
180 fprintf(output, _(" \\encoding [ENCODING]\n"
181 " show or set client encoding\n"));
182 fprintf(output, _(" \\h [NAME] help on syntax of SQL commands, * for all commands\n"));
183 fprintf(output, _(" \\q quit psql\n"));
184 fprintf(output, _(" \\set [NAME [VALUE]]\n"
185 " set internal variable, or list all if no parameters\n"));
186 fprintf(output, _(" \\timing toggle timing of commands (currently %s)\n"),
188 fprintf(output, _(" \\unset NAME unset (delete) internal variable\n"));
189 fprintf(output, _(" \\! [COMMAND] execute command in shell or start interactive shell\n"));
190 fprintf(output, "\n");
192 fprintf(output, _("Query Buffer\n"));
193 fprintf(output, _(" \\e [FILE] edit the query buffer (or file) with external editor\n"));
194 fprintf(output, _(" \\g [FILE] send query buffer to server (and results to file or |pipe)\n"));
195 fprintf(output, _(" \\p show the contents of the query buffer\n"));
196 fprintf(output, _(" \\r reset (clear) the query buffer\n"));
198 fprintf(output, _(" \\s [FILE] display history or save it to file\n"));
200 fprintf(output, _(" \\w FILE write query buffer to file\n"));
201 fprintf(output, "\n");
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"
208 " write string to query output stream (see \\o)\n"));
209 fprintf(output, "\n");
211 fprintf(output, _("Informational\n"));
212 fprintf(output, _(" \\d [NAME] describe table, index, sequence, or view\n"));
213 fprintf(output, _(" \\d{t|i|s|v|S} [PATTERN] (add \"+\" for more detail)\n"
214 " list tables/indexes/sequences/views/system tables\n"));
215 fprintf(output, _(" \\da [PATTERN] list aggregate functions\n"));
216 fprintf(output, _(" \\db [PATTERN] list tablespaces (add \"+\" for more detail)\n"));
217 fprintf(output, _(" \\dc [PATTERN] list conversions\n"));
218 fprintf(output, _(" \\dC list casts\n"));
219 fprintf(output, _(" \\dd [PATTERN] show comment for object\n"));
220 fprintf(output, _(" \\dD [PATTERN] list domains\n"));
221 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 fprintf(output, _(" \\do [NAME] list operators\n"));
225 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 fprintf(output, _(" \\dT [PATTERN] list data types (add \"+\" for more detail)\n"));
228 fprintf(output, _(" \\du [PATTERN] list users\n"));
229 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");
233 fprintf(output, _("Formatting\n"));
234 fprintf(output, _(" \\a toggle between unaligned and aligned output mode\n"));
235 fprintf(output, _(" \\C [STRING] set table title, or unset if none\n"));
236 fprintf(output, _(" \\f [STRING] show or set field separator for unaligned query output\n"));
237 fprintf(output, _(" \\H toggle HTML output mode (currently %s)\n"),
238 ON(pset.popt.topt.format == PRINT_HTML));
239 fprintf(output, _(" \\pset NAME [VALUE]\n"
240 " set table output option\n"
241 " (NAME := {format|border|expanded|fieldsep|footer|null|\n"
242 " recordsep|tuples_only|title|tableattr|pager})\n"));
243 fprintf(output, _(" \\t show only rows (currently %s)\n"),
244 ON(pset.popt.topt.tuples_only));
245 fprintf(output, _(" \\T [STRING] set HTML <table> tag attributes, or unset if none\n"));
246 fprintf(output, _(" \\x toggle expanded output (currently %s)\n"),
247 ON(pset.popt.topt.expanded));
248 fprintf(output, "\n");
250 fprintf(output, _("Copy, Large Object\n"));
251 fprintf(output, _(" \\copy ... perform SQL COPY with data stream to the client host\n"));
252 fprintf(output, _(" \\lo_export LOBOID FILE\n"
253 " \\lo_import FILE [COMMENT] \n"
255 " \\lo_unlink LOBOID large object operations\n"));
257 if (output != stdout)
261 pqsignal(SIGPIPE, SIG_DFL);
269 * helpSQL -- help with SQL commands
273 helpSQL(const char *topic, unsigned short int pager)
275 #define VALUE_OR_NULL(a) ((a) ? (a) : "")
277 if (!topic || strlen(topic) == 0)
280 int items_per_column = (QL_HELP_COUNT + 2) / 3;
283 output = PageOutput(items_per_column + 1, pager);
285 fputs(_("Available help:\n"), output);
287 for (i = 0; i < items_per_column; i++)
289 fprintf(output, " %-26s%-26s",
290 VALUE_OR_NULL(QL_HELP[i].cmd),
291 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));
297 /* Only close if we used the pager */
298 if (output != stdout)
302 pqsignal(SIGPIPE, SIG_DFL);
309 bool help_found = false;
315 /* don't care about trailing spaces or semicolons */
317 while (topic[len - 1] == ' ' || topic[len - 1] == ';')
320 /* Count newlines for pager */
321 for (i = 0; QL_HELP[i].cmd; i++)
323 if (pg_strncasecmp(topic, QL_HELP[i].cmd, len) == 0 ||
324 strcmp(topic, "*") == 0)
327 for (ch = QL_HELP[i].syntax; *ch != '\0'; ch++)
330 /* If we have an exact match, exit. Fixes \h SELECT */
331 if (pg_strcasecmp(topic, QL_HELP[i].cmd) == 0)
336 output = PageOutput(nl_count, pager);
338 for (i = 0; QL_HELP[i].cmd; i++)
340 if (pg_strncasecmp(topic, QL_HELP[i].cmd, len) == 0 ||
341 strcmp(topic, "*") == 0)
344 fprintf(output, _("Command: %s\n"
348 gettext(QL_HELP[i].help),
349 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)
357 fprintf(output, _("No help available for \"%-.*s\".\nTry \\h with no arguments to see available help.\n"), (int) len, topic);
359 /* Only close if we used the pager */
360 if (output != stdout)
364 pqsignal(SIGPIPE, SIG_DFL);
373 print_copyright(void)
376 "PostgreSQL Data Base Management System\n\n"
377 "Portions Copyright (c) 1996-2004, PostgreSQL Global Development Group\n\n"
378 "This software is based on Postgres95, formerly known as Postgres, which\n"
379 "contains the following notice:\n\n"
380 "Portions Copyright(c) 1994, Regents of the University of California\n\n"
381 "Permission to use, copy, modify, and distribute this software and its\n"
382 "documentation for any purpose, without fee, and without a written agreement\n"
383 "is hereby granted, provided that the above copyright notice and this paragraph\n"
384 "and the following two paragraphs appear in all copies.\n\n"
385 "IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR\n"
386 "DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST\n"
387 "PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF\n"
388 "THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH\n"
390 "THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING,\n"
391 "BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A\n"
392 "PARTICULAR PURPOSE.THE SOFTWARE PROVIDED HEREUNDER IS ON AN \"AS IS\" BASIS,\n"
393 "AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE,\n"
394 "SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS."