PostgreSQL Source Code  git master
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros
help.c
Go to the documentation of this file.
1 /*
2  * psql - the PostgreSQL interactive terminal
3  *
4  * Copyright (c) 2000-2017, PostgreSQL Global Development Group
5  *
6  * src/bin/psql/help.c
7  */
8 #include "postgres_fe.h"
9 
10 #ifndef WIN32
11 #include <unistd.h> /* for geteuid() */
12 #else
13 #include <win32.h>
14 #endif
15 
16 #ifndef WIN32
17 #include <sys/ioctl.h> /* for ioctl() */
18 #endif
19 
20 #ifdef HAVE_TERMIOS_H
21 #include <termios.h>
22 #endif
23 
24 #include "common.h"
25 #include "common/username.h"
26 #include "help.h"
27 #include "input.h"
28 #include "settings.h"
29 #include "sql_help.h"
30 
31 
32 /*
33  * PLEASE:
34  * If you change something in this file, also make the same changes
35  * in the DocBook documentation, file ref/psql-ref.sgml. If you don't
36  * know how to do it, please find someone who can help you.
37  */
38 
39 
40 /*
41  * usage
42  *
43  * print out command line arguments
44  */
45 #define ON(var) (var ? _("on") : _("off"))
46 
47 void
48 usage(unsigned short int pager)
49 {
50  const char *env;
51  const char *user;
52  char *errstr;
53  FILE *output;
54 
55  /* Find default user, in case we need it. */
56  user = getenv("PGUSER");
57  if (!user)
58  {
59  user = get_user_name(&errstr);
60  if (!user)
61  {
62  psql_error("%s\n", errstr);
63  exit(EXIT_FAILURE);
64  }
65  }
66 
67  /*
68  * Keep this line count in sync with the number of lines printed below!
69  * Use "psql --help=options | wc" to count correctly.
70  */
71  output = PageOutput(61, pager ? &(pset.popt.topt) : NULL);
72 
73  fprintf(output, _("psql is the PostgreSQL interactive terminal.\n\n"));
74  fprintf(output, _("Usage:\n"));
75  fprintf(output, _(" psql [OPTION]... [DBNAME [USERNAME]]\n\n"));
76 
77  fprintf(output, _("General options:\n"));
78  /* Display default database */
79  env = getenv("PGDATABASE");
80  if (!env)
81  env = user;
82  fprintf(output, _(" -c, --command=COMMAND run only single command (SQL or internal) and exit\n"));
83  fprintf(output, _(" -d, --dbname=DBNAME database name to connect to (default: \"%s\")\n"), env);
84  fprintf(output, _(" -f, --file=FILENAME execute commands from file, then exit\n"));
85  fprintf(output, _(" -l, --list list available databases, then exit\n"));
86  fprintf(output, _(" -v, --set=, --variable=NAME=VALUE\n"
87  " set psql variable NAME to VALUE\n"
88  " (e.g., -v ON_ERROR_STOP=1)\n"));
89  fprintf(output, _(" -V, --version output version information, then exit\n"));
90  fprintf(output, _(" -X, --no-psqlrc do not read startup file (~/.psqlrc)\n"));
91  fprintf(output, _(" -1 (\"one\"), --single-transaction\n"
92  " execute as a single transaction (if non-interactive)\n"));
93  fprintf(output, _(" -?, --help[=options] show this help, then exit\n"));
94  fprintf(output, _(" --help=commands list backslash commands, then exit\n"));
95  fprintf(output, _(" --help=variables list special variables, then exit\n"));
96 
97  fprintf(output, _("\nInput and output options:\n"));
98  fprintf(output, _(" -a, --echo-all echo all input from script\n"));
99  fprintf(output, _(" -b, --echo-errors echo failed commands\n"));
100  fprintf(output, _(" -e, --echo-queries echo commands sent to server\n"));
101  fprintf(output, _(" -E, --echo-hidden display queries that internal commands generate\n"));
102  fprintf(output, _(" -L, --log-file=FILENAME send session log to file\n"));
103  fprintf(output, _(" -n, --no-readline disable enhanced command line editing (readline)\n"));
104  fprintf(output, _(" -o, --output=FILENAME send query results to file (or |pipe)\n"));
105  fprintf(output, _(" -q, --quiet run quietly (no messages, only query output)\n"));
106  fprintf(output, _(" -s, --single-step single-step mode (confirm each query)\n"));
107  fprintf(output, _(" -S, --single-line single-line mode (end of line terminates SQL command)\n"));
108 
109  fprintf(output, _("\nOutput format options:\n"));
110  fprintf(output, _(" -A, --no-align unaligned table output mode\n"));
111  fprintf(output, _(" -F, --field-separator=STRING\n"
112  " field separator for unaligned output (default: \"%s\")\n"),
114  fprintf(output, _(" -H, --html HTML table output mode\n"));
115  fprintf(output, _(" -P, --pset=VAR[=ARG] set printing option VAR to ARG (see \\pset command)\n"));
116  fprintf(output, _(" -R, --record-separator=STRING\n"
117  " record separator for unaligned output (default: newline)\n"));
118  fprintf(output, _(" -t, --tuples-only print rows only\n"));
119  fprintf(output, _(" -T, --table-attr=TEXT set HTML table tag attributes (e.g., width, border)\n"));
120  fprintf(output, _(" -x, --expanded turn on expanded table output\n"));
121  fprintf(output, _(" -z, --field-separator-zero\n"
122  " set field separator for unaligned output to zero byte\n"));
123  fprintf(output, _(" -0, --record-separator-zero\n"
124  " set record separator for unaligned output to zero byte\n"));
125 
126  fprintf(output, _("\nConnection options:\n"));
127  /* Display default host */
128  env = getenv("PGHOST");
129  fprintf(output, _(" -h, --host=HOSTNAME database server host or socket directory (default: \"%s\")\n"),
130  env ? env : _("local socket"));
131  /* Display default port */
132  env = getenv("PGPORT");
133  fprintf(output, _(" -p, --port=PORT database server port (default: \"%s\")\n"),
134  env ? env : DEF_PGPORT_STR);
135  /* Display default user */
136  env = getenv("PGUSER");
137  if (!env)
138  env = user;
139  fprintf(output, _(" -U, --username=USERNAME database user name (default: \"%s\")\n"), env);
140  fprintf(output, _(" -w, --no-password never prompt for password\n"));
141  fprintf(output, _(" -W, --password force password prompt (should happen automatically)\n"));
142 
143  fprintf(output, _("\nFor more information, type \"\\?\" (for internal commands) or \"\\help\" (for SQL\n"
144  "commands) from within psql, or consult the psql section in the PostgreSQL\n"
145  "documentation.\n\n"));
146  fprintf(output, _("Report bugs to <pgsql-bugs@postgresql.org>.\n"));
147 
148  ClosePager(output);
149 }
150 
151 
152 /*
153  * slashUsage
154  *
155  * print out help for the backslash commands
156  */
157 void
158 slashUsage(unsigned short int pager)
159 {
160  FILE *output;
161  char *currdb;
162 
163  currdb = PQdb(pset.db);
164 
165  /*
166  * Keep this line count in sync with the number of lines printed below!
167  * Use "psql --help=commands | wc" to count correctly. It's okay to count
168  * the USE_READLINE line even in builds without that.
169  */
170  output = PageOutput(122, pager ? &(pset.popt.topt) : NULL);
171 
172  fprintf(output, _("General\n"));
173  fprintf(output, _(" \\copyright show PostgreSQL usage and distribution terms\n"));
174  fprintf(output, _(" \\crosstabview [COLUMNS] execute query and display results in crosstab\n"));
175  fprintf(output, _(" \\errverbose show most recent error message at maximum verbosity\n"));
176  fprintf(output, _(" \\g [FILE] or ; execute query (and send results to file or |pipe)\n"));
177  fprintf(output, _(" \\gexec execute query, then execute each value in its result\n"));
178  fprintf(output, _(" \\gset [PREFIX] execute query and store results in psql variables\n"));
179  fprintf(output, _(" \\gx [FILE] as \\g, but forces expanded output mode\n"));
180  fprintf(output, _(" \\q quit psql\n"));
181  fprintf(output, _(" \\watch [SEC] execute query every SEC seconds\n"));
182  fprintf(output, "\n");
183 
184  fprintf(output, _("Help\n"));
185 
186  fprintf(output, _(" \\? [commands] show help on backslash commands\n"));
187  fprintf(output, _(" \\? options show help on psql command-line options\n"));
188  fprintf(output, _(" \\? variables show help on special variables\n"));
189  fprintf(output, _(" \\h [NAME] help on syntax of SQL commands, * for all commands\n"));
190  fprintf(output, "\n");
191 
192  fprintf(output, _("Query Buffer\n"));
193  fprintf(output, _(" \\e [FILE] [LINE] edit the query buffer (or file) with external editor\n"));
194  fprintf(output, _(" \\ef [FUNCNAME [LINE]] edit function definition with external editor\n"));
195  fprintf(output, _(" \\ev [VIEWNAME [LINE]] edit view definition with external editor\n"));
196  fprintf(output, _(" \\p show the contents of the query buffer\n"));
197  fprintf(output, _(" \\r reset (clear) the query buffer\n"));
198 #ifdef USE_READLINE
199  fprintf(output, _(" \\s [FILE] display history or save it to file\n"));
200 #endif
201  fprintf(output, _(" \\w FILE write query buffer to file\n"));
202  fprintf(output, "\n");
203 
204  fprintf(output, _("Input/Output\n"));
205  fprintf(output, _(" \\copy ... perform SQL COPY with data stream to the client host\n"));
206  fprintf(output, _(" \\echo [STRING] write string to standard output\n"));
207  fprintf(output, _(" \\i FILE execute commands from file\n"));
208  fprintf(output, _(" \\ir FILE as \\i, but relative to location of current script\n"));
209  fprintf(output, _(" \\o [FILE] send all query results to file or |pipe\n"));
210  fprintf(output, _(" \\qecho [STRING] write string to query output stream (see \\o)\n"));
211  fprintf(output, "\n");
212 
213  fprintf(output, _("Conditional\n"));
214  fprintf(output, _(" \\if EXPR begin conditional block\n"));
215  fprintf(output, _(" \\elif EXPR alternative within current conditional block\n"));
216  fprintf(output, _(" \\else final alternative within current conditional block\n"));
217  fprintf(output, _(" \\endif end conditional block\n"));
218  fprintf(output, "\n");
219 
220  fprintf(output, _("Informational\n"));
221  fprintf(output, _(" (options: S = show system objects, + = additional detail)\n"));
222  fprintf(output, _(" \\d[S+] list tables, views, and sequences\n"));
223  fprintf(output, _(" \\d[S+] NAME describe table, view, sequence, or index\n"));
224  fprintf(output, _(" \\da[S] [PATTERN] list aggregates\n"));
225  fprintf(output, _(" \\dA[+] [PATTERN] list access methods\n"));
226  fprintf(output, _(" \\db[+] [PATTERN] list tablespaces\n"));
227  fprintf(output, _(" \\dc[S+] [PATTERN] list conversions\n"));
228  fprintf(output, _(" \\dC[+] [PATTERN] list casts\n"));
229  fprintf(output, _(" \\dd[S] [PATTERN] show object descriptions not displayed elsewhere\n"));
230  fprintf(output, _(" \\dD[S+] [PATTERN] list domains\n"));
231  fprintf(output, _(" \\ddp [PATTERN] list default privileges\n"));
232  fprintf(output, _(" \\dE[S+] [PATTERN] list foreign tables\n"));
233  fprintf(output, _(" \\det[+] [PATTERN] list foreign tables\n"));
234  fprintf(output, _(" \\des[+] [PATTERN] list foreign servers\n"));
235  fprintf(output, _(" \\deu[+] [PATTERN] list user mappings\n"));
236  fprintf(output, _(" \\dew[+] [PATTERN] list foreign-data wrappers\n"));
237  fprintf(output, _(" \\df[antw][S+] [PATRN] list [only agg/normal/trigger/window] functions\n"));
238  fprintf(output, _(" \\dF[+] [PATTERN] list text search configurations\n"));
239  fprintf(output, _(" \\dFd[+] [PATTERN] list text search dictionaries\n"));
240  fprintf(output, _(" \\dFp[+] [PATTERN] list text search parsers\n"));
241  fprintf(output, _(" \\dFt[+] [PATTERN] list text search templates\n"));
242  fprintf(output, _(" \\dg[S+] [PATTERN] list roles\n"));
243  fprintf(output, _(" \\di[S+] [PATTERN] list indexes\n"));
244  fprintf(output, _(" \\dl list large objects, same as \\lo_list\n"));
245  fprintf(output, _(" \\dL[S+] [PATTERN] list procedural languages\n"));
246  fprintf(output, _(" \\dm[S+] [PATTERN] list materialized views\n"));
247  fprintf(output, _(" \\dn[S+] [PATTERN] list schemas\n"));
248  fprintf(output, _(" \\do[S] [PATTERN] list operators\n"));
249  fprintf(output, _(" \\dO[S+] [PATTERN] list collations\n"));
250  fprintf(output, _(" \\dp [PATTERN] list table, view, and sequence access privileges\n"));
251  fprintf(output, _(" \\drds [PATRN1 [PATRN2]] list per-database role settings\n"));
252  fprintf(output, _(" \\dRp[+] [PATTERN] list replication publications\n"));
253  fprintf(output, _(" \\dRs[+] [PATTERN] list replication subscriptions\n"));
254  fprintf(output, _(" \\ds[S+] [PATTERN] list sequences\n"));
255  fprintf(output, _(" \\dt[S+] [PATTERN] list tables\n"));
256  fprintf(output, _(" \\dT[S+] [PATTERN] list data types\n"));
257  fprintf(output, _(" \\du[S+] [PATTERN] list roles\n"));
258  fprintf(output, _(" \\dv[S+] [PATTERN] list views\n"));
259  fprintf(output, _(" \\dx[+] [PATTERN] list extensions\n"));
260  fprintf(output, _(" \\dy [PATTERN] list event triggers\n"));
261  fprintf(output, _(" \\l[+] [PATTERN] list databases\n"));
262  fprintf(output, _(" \\sf[+] FUNCNAME show a function's definition\n"));
263  fprintf(output, _(" \\sv[+] VIEWNAME show a view's definition\n"));
264  fprintf(output, _(" \\z [PATTERN] same as \\dp\n"));
265  fprintf(output, "\n");
266 
267  fprintf(output, _("Formatting\n"));
268  fprintf(output, _(" \\a toggle between unaligned and aligned output mode\n"));
269  fprintf(output, _(" \\C [STRING] set table title, or unset if none\n"));
270  fprintf(output, _(" \\f [STRING] show or set field separator for unaligned query output\n"));
271  fprintf(output, _(" \\H toggle HTML output mode (currently %s)\n"),
273  fprintf(output, _(" \\pset [NAME [VALUE]] set table output option\n"
274  " (NAME := {format|border|expanded|fieldsep|fieldsep_zero|footer|null|\n"
275  " numericlocale|recordsep|recordsep_zero|tuples_only|title|tableattr|pager|\n"
276  " unicode_border_linestyle|unicode_column_linestyle|unicode_header_linestyle})\n"));
277  fprintf(output, _(" \\t [on|off] show only rows (currently %s)\n"),
279  fprintf(output, _(" \\T [STRING] set HTML <table> tag attributes, or unset if none\n"));
280  fprintf(output, _(" \\x [on|off|auto] toggle expanded output (currently %s)\n"),
281  pset.popt.topt.expanded == 2 ? "auto" : ON(pset.popt.topt.expanded));
282  fprintf(output, "\n");
283 
284  fprintf(output, _("Connection\n"));
285  if (currdb)
286  fprintf(output, _(" \\c[onnect] {[DBNAME|- USER|- HOST|- PORT|-] | conninfo}\n"
287  " connect to new database (currently \"%s\")\n"),
288  currdb);
289  else
290  fprintf(output, _(" \\c[onnect] {[DBNAME|- USER|- HOST|- PORT|-] | conninfo}\n"
291  " connect to new database (currently no connection)\n"));
292  fprintf(output, _(" \\conninfo display information about current connection\n"));
293  fprintf(output, _(" \\encoding [ENCODING] show or set client encoding\n"));
294  fprintf(output, _(" \\password [USERNAME] securely change the password for a user\n"));
295  fprintf(output, "\n");
296 
297  fprintf(output, _("Operating System\n"));
298  fprintf(output, _(" \\cd [DIR] change the current working directory\n"));
299  fprintf(output, _(" \\setenv NAME [VALUE] set or unset environment variable\n"));
300  fprintf(output, _(" \\timing [on|off] toggle timing of commands (currently %s)\n"),
301  ON(pset.timing));
302  fprintf(output, _(" \\! [COMMAND] execute command in shell or start interactive shell\n"));
303  fprintf(output, "\n");
304 
305  fprintf(output, _("Variables\n"));
306  fprintf(output, _(" \\prompt [TEXT] NAME prompt user to set internal variable\n"));
307  fprintf(output, _(" \\set [NAME [VALUE]] set internal variable, or list all if no parameters\n"));
308  fprintf(output, _(" \\unset NAME unset (delete) internal variable\n"));
309  fprintf(output, "\n");
310 
311  fprintf(output, _("Large Objects\n"));
312  fprintf(output, _(" \\lo_export LOBOID FILE\n"
313  " \\lo_import FILE [COMMENT]\n"
314  " \\lo_list\n"
315  " \\lo_unlink LOBOID large object operations\n"));
316 
317  ClosePager(output);
318 }
319 
320 
321 /*
322  * helpVariables
323  *
324  * show list of available variables (options) from command line
325  */
326 void
327 helpVariables(unsigned short int pager)
328 {
329  FILE *output;
330 
331  /*
332  * Keep this line count in sync with the number of lines printed below!
333  * Use "psql --help=variables | wc" to count correctly; but notice that
334  * Windows builds currently print one more line than non-Windows builds.
335  * Using the larger number is fine.
336  */
337  output = PageOutput(88, pager ? &(pset.popt.topt) : NULL);
338 
339  fprintf(output, _("List of specially treated variables\n\n"));
340 
341  fprintf(output, _("psql variables:\n"));
342  fprintf(output, _("Usage:\n"));
343  fprintf(output, _(" psql --set=NAME=VALUE\n or \\set NAME VALUE inside psql\n\n"));
344 
345  fprintf(output, _(" AUTOCOMMIT if set, successful SQL commands are automatically committed\n"));
346  fprintf(output, _(" COMP_KEYWORD_CASE determines the case used to complete SQL key words\n"
347  " [lower, upper, preserve-lower, preserve-upper]\n"));
348  fprintf(output, _(" DBNAME the currently connected database name\n"));
349  fprintf(output, _(" ECHO controls what input is written to standard output\n"
350  " [all, errors, none, queries]\n"));
351  fprintf(output, _(" ECHO_HIDDEN if set, display internal queries executed by backslash commands;\n"
352  " if set to \"noexec\", just show without execution\n"));
353  fprintf(output, _(" ENCODING current client character set encoding\n"));
354  fprintf(output, _(" FETCH_COUNT the number of result rows to fetch and display at a time\n"
355  " (default: 0=unlimited)\n"));
356  fprintf(output, _(" HISTCONTROL controls command history [ignorespace, ignoredups, ignoreboth]\n"));
357  fprintf(output, _(" HISTFILE file name used to store the command history\n"));
358  fprintf(output, _(" HISTSIZE max number of commands to store in the command history\n"));
359  fprintf(output, _(" HOST the currently connected database server host\n"));
360  fprintf(output, _(" IGNOREEOF number of EOFs needed to terminate an interactive session\n"));
361  fprintf(output, _(" LASTOID value of the last affected OID\n"));
362  fprintf(output, _(" ON_ERROR_ROLLBACK if set, an error doesn't stop a transaction (uses implicit savepoints)\n"));
363  fprintf(output, _(" ON_ERROR_STOP stop batch execution after error\n"));
364  fprintf(output, _(" PORT server port of the current connection\n"));
365  fprintf(output, _(" PROMPT1 specifies the standard psql prompt\n"));
366  fprintf(output, _(" PROMPT2 specifies the prompt used when a statement continues from a previous line\n"));
367  fprintf(output, _(" PROMPT3 specifies the prompt used during COPY ... FROM STDIN\n"));
368  fprintf(output, _(" QUIET run quietly (same as -q option)\n"));
369  fprintf(output, _(" SHOW_CONTEXT controls display of message context fields [never, errors, always]\n"));
370  fprintf(output, _(" SINGLELINE end of line terminates SQL command mode (same as -S option)\n"));
371  fprintf(output, _(" SINGLESTEP single-step mode (same as -s option)\n"));
372  fprintf(output, _(" USER the currently connected database user\n"));
373  fprintf(output, _(" VERBOSITY controls verbosity of error reports [default, verbose, terse]\n"));
374 
375  fprintf(output, _("\nDisplay settings:\n"));
376  fprintf(output, _("Usage:\n"));
377  fprintf(output, _(" psql --pset=NAME[=VALUE]\n or \\pset NAME [VALUE] inside psql\n\n"));
378 
379  fprintf(output, _(" border border style (number)\n"));
380  fprintf(output, _(" columns target width for the wrapped format\n"));
381  fprintf(output, _(" expanded (or x) expanded output [on, off, auto]\n"));
382  fprintf(output, _(" fieldsep field separator for unaligned output (default \"%s\")\n"), DEFAULT_FIELD_SEP);
383  fprintf(output, _(" fieldsep_zero set field separator for unaligned output to zero byte\n"));
384  fprintf(output, _(" footer enable or disable display of the table footer [on, off]\n"));
385  fprintf(output, _(" format set output format [unaligned, aligned, wrapped, html, asciidoc, ...]\n"));
386  fprintf(output, _(" linestyle set the border line drawing style [ascii, old-ascii, unicode]\n"));
387  fprintf(output, _(" null set the string to be printed in place of a null value\n"));
388  fprintf(output, _(" numericlocale enable or disable display of a locale-specific character to separate\n"
389  " groups of digits [on, off]\n"));
390  fprintf(output, _(" pager control when an external pager is used [yes, no, always]\n"));
391  fprintf(output, _(" recordsep record (line) separator for unaligned output\n"));
392  fprintf(output, _(" recordsep_zero set record separator for unaligned output to zero byte\n"));
393  fprintf(output, _(" tableattr (or T) specify attributes for table tag in html format or proportional\n"
394  " column widths for left-aligned data types in latex-longtable format\n"));
395  fprintf(output, _(" title set the table title for any subsequently printed tables\n"));
396  fprintf(output, _(" tuples_only if set, only actual table data is shown\n"));
397  fprintf(output, _(" unicode_border_linestyle\n"
398  " unicode_column_linestyle\n"
399  " unicode_header_linestyle\n"
400  " set the style of Unicode line drawing [single, double]\n"));
401 
402  fprintf(output, _("\nEnvironment variables:\n"));
403  fprintf(output, _("Usage:\n"));
404 
405 #ifndef WIN32
406  fprintf(output, _(" NAME=VALUE [NAME=VALUE] psql ...\n or \\setenv NAME [VALUE] inside psql\n\n"));
407 #else
408  fprintf(output, _(" set NAME=VALUE\n psql ...\n or \\setenv NAME [VALUE] inside psql\n\n"));
409 #endif
410 
411  fprintf(output, _(" COLUMNS number of columns for wrapped format\n"));
412  fprintf(output, _(" PAGER name of external pager program\n"));
413  fprintf(output, _(" PGAPPNAME same as the application_name connection parameter\n"));
414  fprintf(output, _(" PGDATABASE same as the dbname connection parameter\n"));
415  fprintf(output, _(" PGHOST same as the host connection parameter\n"));
416  fprintf(output, _(" PGPASSWORD connection password (not recommended)\n"));
417  fprintf(output, _(" PGPASSFILE password file name\n"));
418  fprintf(output, _(" PGPORT same as the port connection parameter\n"));
419  fprintf(output, _(" PGUSER same as the user connection parameter\n"));
420  fprintf(output, _(" PSQL_EDITOR, EDITOR, VISUAL\n"
421  " editor used by the \\e, \\ef, and \\ev commands\n"));
422  fprintf(output, _(" PSQL_EDITOR_LINENUMBER_ARG\n"
423  " how to specify a line number when invoking the editor\n"));
424  fprintf(output, _(" PSQL_HISTORY alternative location for the command history file\n"));
425  fprintf(output, _(" PSQLRC alternative location for the user's .psqlrc file\n"));
426  fprintf(output, _(" SHELL shell used by the \\! command\n"));
427  fprintf(output, _(" TMPDIR directory for temporary files\n"));
428 
429  ClosePager(output);
430 }
431 
432 
433 /*
434  * helpSQL -- help with SQL commands
435  *
436  * Note: we assume caller removed any trailing spaces in "topic".
437  */
438 void
439 helpSQL(const char *topic, unsigned short int pager)
440 {
441 #define VALUE_OR_NULL(a) ((a) ? (a) : "")
442 
443  if (!topic || strlen(topic) == 0)
444  {
445  /* Print all the available command names */
446  int screen_width;
447  int ncolumns;
448  int nrows;
449  FILE *output;
450  int i;
451  int j;
452 
453 #ifdef TIOCGWINSZ
454  struct winsize screen_size;
455 
456  if (ioctl(fileno(stdout), TIOCGWINSZ, &screen_size) == -1)
457  screen_width = 80; /* ioctl failed, assume 80 */
458  else
459  screen_width = screen_size.ws_col;
460 #else
461  screen_width = 80; /* default assumption */
462 #endif
463 
464  ncolumns = (screen_width - 3) / (QL_MAX_CMD_LEN + 1);
465  ncolumns = Max(ncolumns, 1);
466  nrows = (QL_HELP_COUNT + (ncolumns - 1)) / ncolumns;
467 
468  output = PageOutput(nrows + 1, pager ? &(pset.popt.topt) : NULL);
469 
470  fputs(_("Available help:\n"), output);
471 
472  for (i = 0; i < nrows; i++)
473  {
474  fprintf(output, " ");
475  for (j = 0; j < ncolumns - 1; j++)
476  fprintf(output, "%-*s",
477  QL_MAX_CMD_LEN + 1,
478  VALUE_OR_NULL(QL_HELP[i + j * nrows].cmd));
479  if (i + j * nrows < QL_HELP_COUNT)
480  fprintf(output, "%s",
481  VALUE_OR_NULL(QL_HELP[i + j * nrows].cmd));
482  fputc('\n', output);
483  }
484 
485  ClosePager(output);
486  }
487  else
488  {
489  int i,
490  j,
491  x = 0;
492  bool help_found = false;
493  FILE *output = NULL;
494  size_t len,
495  wordlen;
496  int nl_count = 0;
497 
498  /*
499  * We first try exact match, then first + second words, then first
500  * word only.
501  */
502  len = strlen(topic);
503 
504  for (x = 1; x <= 3; x++)
505  {
506  if (x > 1) /* Nothing on first pass - try the opening
507  * word(s) */
508  {
509  wordlen = j = 1;
510  while (topic[j] != ' ' && j++ < len)
511  wordlen++;
512  if (x == 2)
513  {
514  j++;
515  while (topic[j] != ' ' && j++ <= len)
516  wordlen++;
517  }
518  if (wordlen >= len) /* Don't try again if the same word */
519  {
520  if (!output)
521  output = PageOutput(nl_count, pager ? &(pset.popt.topt) : NULL);
522  break;
523  }
524  len = wordlen;
525  }
526 
527  /* Count newlines for pager */
528  for (i = 0; QL_HELP[i].cmd; i++)
529  {
530  if (pg_strncasecmp(topic, QL_HELP[i].cmd, len) == 0 ||
531  strcmp(topic, "*") == 0)
532  {
533  nl_count += 5 + QL_HELP[i].nl_count;
534 
535  /* If we have an exact match, exit. Fixes \h SELECT */
536  if (pg_strcasecmp(topic, QL_HELP[i].cmd) == 0)
537  break;
538  }
539  }
540 
541  if (!output)
542  output = PageOutput(nl_count, pager ? &(pset.popt.topt) : NULL);
543 
544  for (i = 0; QL_HELP[i].cmd; i++)
545  {
546  if (pg_strncasecmp(topic, QL_HELP[i].cmd, len) == 0 ||
547  strcmp(topic, "*") == 0)
548  {
550 
551  initPQExpBuffer(&buffer);
552  QL_HELP[i].syntaxfunc(&buffer);
553  help_found = true;
554  fprintf(output, _("Command: %s\n"
555  "Description: %s\n"
556  "Syntax:\n%s\n\n"),
557  QL_HELP[i].cmd,
558  _(QL_HELP[i].help),
559  buffer.data);
560  /* If we have an exact match, exit. Fixes \h SELECT */
561  if (pg_strcasecmp(topic, QL_HELP[i].cmd) == 0)
562  break;
563  }
564  }
565  if (help_found) /* Don't keep trying if we got a match */
566  break;
567  }
568 
569  if (!help_found)
570  fprintf(output, _("No help available for \"%s\".\nTry \\h with no arguments to see available help.\n"), topic);
571 
572  ClosePager(output);
573  }
574 }
575 
576 
577 
578 void
580 {
581  puts(
582  "PostgreSQL Database Management System\n"
583  "(formerly known as Postgres, then as Postgres95)\n\n"
584  "Portions Copyright (c) 1996-2017, PostgreSQL Global Development Group\n\n"
585  "Portions Copyright (c) 1994, The Regents of the University of California\n\n"
586  "Permission to use, copy, modify, and distribute this software and its\n"
587  "documentation for any purpose, without fee, and without a written agreement\n"
588  "is hereby granted, provided that the above copyright notice and this\n"
589  "paragraph and the following two paragraphs appear in all copies.\n\n"
590  "IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR\n"
591  "DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING\n"
592  "LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS\n"
593  "DOCUMENTATION, EVEN IF THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE\n"
594  "POSSIBILITY OF SUCH DAMAGE.\n\n"
595  "THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,\n"
596  "INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY\n"
597  "AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS\n"
598  "ON AN \"AS IS\" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATIONS TO\n"
599  "PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.\n"
600  );
601 }
PGconn * db
Definition: settings.h:82
void print_copyright(void)
Definition: help.c:579
PsqlSettings pset
Definition: startup.c:33
static void output(uint64 loop_count)
void ClosePager(FILE *pagerpipe)
Definition: print.c:2900
enum printFormat format
Definition: print.h:98
printTableOpt topt
Definition: print.h:165
#define ON(var)
Definition: help.c:45
int pg_strcasecmp(const char *s1, const char *s2)
Definition: pgstrcasecmp.c:36
void usage(unsigned short int pager)
Definition: help.c:48
const char * get_user_name(char **errstr)
Definition: username.c:31
static void help(const char *progname)
Definition: oid2name.c:172
int pg_strncasecmp(const char *s1, const char *s2, size_t n)
Definition: pgstrcasecmp.c:69
unsigned short int expanded
Definition: print.h:99
FILE * PageOutput(int lines, const printTableOpt *topt)
Definition: print.c:2851
bool tuples_only
Definition: print.h:107
void psql_error(const char *fmt,...)
Definition: common.c:220
void helpVariables(unsigned short int pager)
Definition: help.c:327
char * PQdb(const PGconn *conn)
Definition: fe-connect.c:5882
#define Max(x, y)
Definition: c.h:800
#define NULL
Definition: c.h:229
WalTimeSample buffer[LAG_TRACKER_BUFFER_SIZE]
Definition: walsender.c:214
printQueryOpt popt
Definition: settings.h:91
static char * user
Definition: pg_regress.c:92
void helpSQL(const char *topic, unsigned short int pager)
Definition: help.c:439
int i
#define EXIT_FAILURE
Definition: settings.h:151
#define DEFAULT_FIELD_SEP
Definition: settings.h:15
#define VALUE_OR_NULL(a)
#define _(x)
Definition: elog.c:84
void slashUsage(unsigned short int pager)
Definition: help.c:158
void initPQExpBuffer(PQExpBuffer str)
Definition: pqexpbuffer.c:89