2 * psql - the PostgreSQL interactive terminal
4 * Copyright (c) 2000-2009, PostgreSQL Global Development Group
6 * $PostgreSQL: pgsql/src/bin/psql/help.c,v 1.135 2009/01/06 23:01:57 momjian Exp $
8 #include "postgres_fe.h"
14 #include <pwd.h> /* for getpwuid() */
16 #include <sys/types.h> /* (ditto) */
17 #include <unistd.h> /* for geteuid() */
23 #include <sys/ioctl.h> /* for ioctl() */
41 * If you change something in this file, also make the same changes
42 * in the DocBook documentation, file ref/psql-ref.sgml. If you don't
43 * know how to do it, please find someone who can help you.
50 * print out command line arguments
52 #define ON(var) (var ? _("on") : _("off"))
61 struct passwd *pw = NULL;
64 /* Find default user, in case we need it. */
65 user = getenv("PGUSER");
68 #if !defined(WIN32) && !defined(__OS2__)
69 pw = getpwuid(geteuid());
74 psql_error("could not get current user name: %s\n", strerror(errno));
79 DWORD bufsize = sizeof(buf) - 1;
81 if (GetUserName(buf, &bufsize))
86 /* >>> If this " is the start of the string then it ought to end there to fit in 80 columns >> " */
87 printf(_("This is psql %s, the PostgreSQL interactive terminal.\n\n"),
90 puts(_(" psql [OPTIONS]... [DBNAME [USERNAME]]\n"));
92 puts(_("General options:"));
93 /* Display default database */
94 env = getenv("PGDATABASE");
97 printf(_(" -d DBNAME specify database name to connect to (default: \"%s\")\n"), env);
98 puts(_(" -c COMMAND run only single command (SQL or internal) and exit"));
99 puts(_(" -f FILENAME execute commands from file, then exit"));
100 puts(_(" -1 (\"one\") execute command file as a single transaction"));
101 puts(_(" -l list available databases, then exit"));
102 puts(_(" -v NAME=VALUE set psql variable NAME to VALUE"));
103 puts(_(" -X do not read startup file (~/.psqlrc)"));
104 puts(_(" --help show this help, then exit"));
105 puts(_(" --version output version information, then exit"));
107 puts(_("\nInput and output options:"));
108 puts(_(" -a echo all input from script"));
109 puts(_(" -e echo commands sent to server"));
110 puts(_(" -E display queries that internal commands generate"));
111 puts(_(" -q run quietly (no messages, only query output)"));
112 puts(_(" -o FILENAME send query results to file (or |pipe)"));
113 puts(_(" -n disable enhanced command line editing (readline)"));
114 puts(_(" -s single-step mode (confirm each query)"));
115 puts(_(" -S single-line mode (end of line terminates SQL command)"));
116 puts(_(" -L FILENAME send session log to file"));
118 puts(_("\nOutput format options:"));
119 puts(_(" -A unaligned table output mode (-P format=unaligned)"));
120 puts(_(" -H HTML table output mode (-P format=html)"));
121 puts(_(" -t print rows only (-P tuples_only)"));
122 puts(_(" -T TEXT set HTML table tag attributes (width, border) (-P tableattr=)"));
123 puts(_(" -x turn on expanded table output (-P expanded)"));
124 puts(_(" -P VAR[=ARG] set printing option VAR to ARG (see \\pset command)"));
125 printf(_(" -F STRING set field separator (default: \"%s\") (-P fieldsep=)\n"),
127 puts(_(" -R STRING set record separator (default: newline) (-P recordsep=)"));
129 puts(_("\nConnection options:"));
130 /* Display default host */
131 env = getenv("PGHOST");
132 printf(_(" -h HOSTNAME database server host or socket directory (default: \"%s\")\n"),
133 env ? env : _("local socket"));
134 /* Display default port */
135 env = getenv("PGPORT");
136 printf(_(" -p PORT database server port (default: \"%s\")\n"),
137 env ? env : DEF_PGPORT_STR);
138 /* Display default user */
139 env = getenv("PGUSER");
142 printf(_(" -U NAME database user name (default: \"%s\")\n"), env);
143 puts(_(" -W force password prompt (should happen automatically)"));
146 "\nFor more information, type \"\\?\" (for internal commands) or \"\\help\"\n"
147 "(for SQL commands) from within psql, or consult the psql section in\n"
148 "the PostgreSQL documentation.\n\n"
149 "Report bugs to <pgsql-bugs@postgresql.org>."));
156 * print out help for the backslash commands
159 slashUsage(unsigned short int pager)
163 output = PageOutput(78, pager);
165 /* if you add/remove a line here, change the row count above */
168 * if this " is the start of the string then it ought to end there to fit
171 fprintf(output, _("General\n"));
172 fprintf(output, _(" \\copyright show PostgreSQL usage and distribution terms\n"));
173 fprintf(output, _(" \\g [FILE] or ; execute query (and send results to file or |pipe)\n"));
174 fprintf(output, _(" \\h [NAME] help on syntax of SQL commands, * for all commands\n"));
175 fprintf(output, _(" \\q quit psql\n"));
176 fprintf(output, "\n");
178 fprintf(output, _("Query Buffer\n"));
179 fprintf(output, _(" \\e [FILE] edit the query buffer (or file) with external editor\n"));
180 fprintf(output, _(" \\p show the contents of the query buffer\n"));
181 fprintf(output, _(" \\r reset (clear) the query buffer\n"));
183 fprintf(output, _(" \\s [FILE] display history or save it to file\n"));
185 fprintf(output, _(" \\w FILE write query buffer to file\n"));
186 fprintf(output, "\n");
188 fprintf(output, _("Input/Output\n"));
189 fprintf(output, _(" \\copy ... perform SQL COPY with data stream to the client host\n"));
190 fprintf(output, _(" \\echo [STRING] write string to standard output\n"));
191 fprintf(output, _(" \\i FILE execute commands from file\n"));
192 fprintf(output, _(" \\o [FILE] send all query results to file or |pipe\n"));
193 fprintf(output, _(" \\qecho [STRING] write string to query output stream (see \\o)\n"));
194 fprintf(output, "\n");
196 fprintf(output, _("Informational\n"));
197 fprintf(output, _(" Modifiers: S = show system objects + = Additional detail\n"));
198 fprintf(output, _(" \\l[+] list all databases\n"));
199 fprintf(output, _(" \\d[S+] list tables, views, and sequences\n"));
200 fprintf(output, _(" \\d[S+] NAME describe table, view, sequence, or index\n"));
201 fprintf(output, _(" \\da[S] [PATTERN] list aggregate functions\n"));
202 fprintf(output, _(" \\db[+] [PATTERN] list tablespaces\n"));
203 fprintf(output, _(" \\dc[S] [PATTERN] list conversions\n"));
204 fprintf(output, _(" \\dC [PATTERN] list casts\n"));
205 fprintf(output, _(" \\dd [PATTERN] show comment for object\n"));
206 fprintf(output, _(" \\dd[S] [PATTERN] list comments on objects\n"));
207 fprintf(output, _(" \\dD[S] [PATTERN] list domains\n"));
208 fprintf(output, _(" \\des[+] [PATTERN] list foreign servers\n"));
209 fprintf(output, _(" \\deu[+] [PATTERN] list user mappings\n"));
210 fprintf(output, _(" \\dew[+] [PATTERN] list foreign-data wrappers\n"));
211 fprintf(output, _(" \\df[S+] [PATTERN] list functions\n"));
212 fprintf(output, _(" \\dF[+] [PATTERN] list text search configurations\n"));
213 fprintf(output, _(" \\dFd[+] [PATTERN] list text search dictionaries\n"));
214 fprintf(output, _(" \\dFp[+] [PATTERN] list text search parsers\n"));
215 fprintf(output, _(" \\dFt[+] [PATTERN] list text search templates\n"));
216 fprintf(output, _(" \\dg [PATTERN] list roles (groups)\n"));
217 fprintf(output, _(" \\di[S+] [PATTERN] list indexes\n"));
218 fprintf(output, _(" \\dl list large objects, same as \\lo_list\n"));
219 fprintf(output, _(" \\dn[+] [PATTERN] list schemas\n"));
220 fprintf(output, _(" \\do[S] [PATTERN] list operators\n"));
221 fprintf(output, _(" \\dp [PATTERN] list table, view, and sequence access privileges\n"));
222 fprintf(output, _(" \\z [PATTERN] same as \\dp\n"));
223 fprintf(output, _(" \\ds[S+] [PATTERN] list sequences\n"));
224 fprintf(output, _(" \\dt[S+] [PATTERN] list tables\n"));
225 fprintf(output, _(" \\dT[S+] [PATTERN] list data types\n"));
226 fprintf(output, _(" \\du [PATTERN] list roles (users)\n"));
227 fprintf(output, _(" \\dv[S+] [PATTERN] list views\n"));
228 fprintf(output, "\n");
230 fprintf(output, _("Formatting\n"));
231 fprintf(output, _(" \\a toggle between unaligned and aligned output mode\n"));
232 fprintf(output, _(" \\C [STRING] set table title, or unset if none\n"));
233 fprintf(output, _(" \\f [STRING] show or set field separator for unaligned query output\n"));
234 fprintf(output, _(" \\H toggle HTML output mode (currently %s)\n"),
235 ON(pset.popt.topt.format == PRINT_HTML));
236 fprintf(output, _(" \\pset NAME [VALUE] set table output option\n"
237 " (NAME := {format|border|expanded|fieldsep|footer|null|\n"
238 " numericlocale|recordsep|tuples_only|title|tableattr|pager})\n"));
239 fprintf(output, _(" \\t [on|off] show only rows (currently %s)\n"),
240 ON(pset.popt.topt.tuples_only));
241 fprintf(output, _(" \\T [STRING] set HTML <table> tag attributes, or unset if none\n"));
242 fprintf(output, _(" \\x [on|off] toggle expanded output (currently %s)\n"),
243 ON(pset.popt.topt.expanded));
244 fprintf(output, "\n");
246 fprintf(output, _("Connection\n"));
247 fprintf(output, _(" \\c[onnect] [DBNAME|- USER|- HOST|- PORT|-]\n"
248 " connect to new database (currently \"%s\")\n"),
250 fprintf(output, _(" \\encoding [ENCODING] show or set client encoding\n"));
251 fprintf(output, _(" \\password [USERNAME] securely change the password for a user\n"));
252 fprintf(output, "\n");
254 fprintf(output, _("External\n"));
255 fprintf(output, _(" \\cd [DIR] change the current working directory\n"));
256 fprintf(output, _(" \\timing [on|off] toggle timing of commands (currently %s)\n"),
258 fprintf(output, _(" \\! [COMMAND] execute command in shell or start interactive shell\n"));
259 fprintf(output, "\n");
261 fprintf(output, _("Variable\n"));
262 fprintf(output, _(" \\prompt [TEXT] NAME prompt user to set internal variable\n"));
263 fprintf(output, _(" \\set [NAME [VALUE]] set internal variable, or list all if no parameters\n"));
264 fprintf(output, _(" \\unset NAME unset (delete) internal variable\n"));
265 fprintf(output, "\n");
267 fprintf(output, _("Large Object\n"));
268 fprintf(output, _(" \\lo_export LOBOID FILE\n"
269 " \\lo_import FILE [COMMENT]\n"
271 " \\lo_unlink LOBOID large object operations\n"));
273 if (output != stdout)
277 pqsignal(SIGPIPE, SIG_DFL);
285 * helpSQL -- help with SQL commands
289 helpSQL(const char *topic, unsigned short int pager)
291 #define VALUE_OR_NULL(a) ((a) ? (a) : "")
293 if (!topic || strlen(topic) == 0)
295 /* Print all the available command names */
304 struct winsize screen_size;
306 if (ioctl(fileno(stdout), TIOCGWINSZ, &screen_size) == -1)
307 screen_width = 80; /* ioctl failed, assume 80 */
309 screen_width = screen_size.ws_col;
311 screen_width = 80; /* default assumption */
314 ncolumns = (screen_width - 3) / (QL_MAX_CMD_LEN + 1);
315 ncolumns = Max(ncolumns, 1);
316 nrows = (QL_HELP_COUNT + (ncolumns - 1)) / ncolumns;
318 output = PageOutput(nrows + 1, pager);
320 fputs(_("Available help:\n"), output);
322 for (i = 0; i < nrows; i++)
324 fprintf(output, " ");
325 for (j = 0; j < ncolumns-1; j++)
326 fprintf(output, "%-*s",
328 VALUE_OR_NULL(QL_HELP[i + j * nrows].cmd));
329 if (i + j * nrows < QL_HELP_COUNT)
330 fprintf(output, "%s",
331 VALUE_OR_NULL(QL_HELP[i + j * nrows].cmd));
335 /* Only close if we used the pager */
336 if (output != stdout)
340 pqsignal(SIGPIPE, SIG_DFL);
349 bool help_found = false;
356 /* User gets two chances: exact match, then the first word */
358 /* First pass : strip trailing spaces and semicolons */
360 while (topic[len - 1] == ' ' || topic[len - 1] == ';')
363 for (x = 1; x <= 3; x++) /* Three chances to guess that word... */
365 if (x > 1) /* Nothing on first pass - try the opening
369 while (topic[j] != ' ' && j++ < len)
374 while (topic[j] != ' ' && j++ <= len)
377 if (wordlen >= len) /* Don't try again if the same word */
379 output = PageOutput(nl_count, pager);
385 /* Count newlines for pager */
386 for (i = 0; QL_HELP[i].cmd; i++)
388 if (pg_strncasecmp(topic, QL_HELP[i].cmd, len) == 0 ||
389 strcmp(topic, "*") == 0)
392 for (ch = QL_HELP[i].syntax; *ch != '\0'; ch++)
395 /* If we have an exact match, exit. Fixes \h SELECT */
396 if (pg_strcasecmp(topic, QL_HELP[i].cmd) == 0)
401 output = PageOutput(nl_count, pager);
403 for (i = 0; QL_HELP[i].cmd; i++)
405 if (pg_strncasecmp(topic, QL_HELP[i].cmd, len) == 0 ||
406 strcmp(topic, "*") == 0)
409 fprintf(output, _("Command: %s\n"
414 _(QL_HELP[i].syntax));
415 /* If we have an exact match, exit. Fixes \h SELECT */
416 if (pg_strcasecmp(topic, QL_HELP[i].cmd) == 0)
420 if (help_found) /* Don't keep trying if we got a match */
425 fprintf(output, _("No help available for \"%-.*s\".\nTry \\h with no arguments to see available help.\n"), (int) len, topic);
427 /* Only close if we used the pager */
428 if (output != stdout)
432 pqsignal(SIGPIPE, SIG_DFL);
441 print_copyright(void)
444 "PostgreSQL Data Base Management System\n\n"
445 "Portions Copyright (c) 1996-2009, PostgreSQL Global Development Group\n\n"
446 "This software is based on Postgres95, formerly known as Postgres, which\n"
447 "contains the following notice:\n\n"
448 "Portions Copyright(c) 1994, Regents of the University of California\n\n"
449 "Permission to use, copy, modify, and distribute this software and its\n"
450 "documentation for any purpose, without fee, and without a written agreement\n"
451 "is hereby granted, provided that the above copyright notice and this paragraph\n"
452 "and the following two paragraphs appear in all copies.\n\n"
453 "IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR\n"
454 "DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST\n"
455 "PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF\n"
456 "THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH\n"
458 "THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING,\n"
459 "BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A\n"
460 "PARTICULAR PURPOSE.THE SOFTWARE PROVIDED HEREUNDER IS ON AN \"AS IS\" BASIS,\n"
461 "AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE,\n"
462 "SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS."