PostgreSQL Source Code  git master
help.c
Go to the documentation of this file.
1 /*
2  * psql - the PostgreSQL interactive terminal
3  *
4  * Copyright (c) 2000-2023, 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/logging.h"
26 #include "common/username.h"
27 #include "help.h"
28 #include "input.h"
29 #include "settings.h"
30 #include "sql_help.h"
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 /* Some helper macros to make the code less verbose */
40 #define HELP0(str) appendPQExpBufferStr(&buf, _(str))
41 #define HELPN(str,...) appendPQExpBuffer(&buf, _(str), __VA_ARGS__)
42 #define ON(var) ((var) ? _("on") : _("off"))
43 
44 
45 /*
46  * usage
47  *
48  * print out command line arguments
49  */
50 void
51 usage(unsigned short int pager)
52 {
53  const char *env;
54  const char *user;
55  char *errstr;
56  PQExpBufferData buf;
57  int nlcount;
58  FILE *output;
59 
60  /* Find default user, in case we need it. */
61  user = getenv("PGUSER");
62  if (!user)
63  {
64  user = get_user_name(&errstr);
65  if (!user)
66  pg_fatal("%s", errstr);
67  }
68 
69  /*
70  * To avoid counting the output lines manually, build the output in "buf"
71  * and then count them.
72  */
73  initPQExpBuffer(&buf);
74 
75  HELP0("psql is the PostgreSQL interactive terminal.\n\n");
76  HELP0("Usage:\n");
77  HELP0(" psql [OPTION]... [DBNAME [USERNAME]]\n\n");
78 
79  HELP0("General options:\n");
80  /* Display default database */
81  env = getenv("PGDATABASE");
82  if (!env)
83  env = user;
84  HELP0(" -c, --command=COMMAND run only single command (SQL or internal) and exit\n");
85  HELPN(" -d, --dbname=DBNAME database name to connect to (default: \"%s\")\n",
86  env);
87  HELP0(" -f, --file=FILENAME execute commands from file, then exit\n");
88  HELP0(" -l, --list list available databases, then exit\n");
89  HELP0(" -v, --set=, --variable=NAME=VALUE\n"
90  " set psql variable NAME to VALUE\n"
91  " (e.g., -v ON_ERROR_STOP=1)\n");
92  HELP0(" -V, --version output version information, then exit\n");
93  HELP0(" -X, --no-psqlrc do not read startup file (~/.psqlrc)\n");
94  HELP0(" -1 (\"one\"), --single-transaction\n"
95  " execute as a single transaction (if non-interactive)\n");
96  HELP0(" -?, --help[=options] show this help, then exit\n");
97  HELP0(" --help=commands list backslash commands, then exit\n");
98  HELP0(" --help=variables list special variables, then exit\n");
99 
100  HELP0("\nInput and output options:\n");
101  HELP0(" -a, --echo-all echo all input from script\n");
102  HELP0(" -b, --echo-errors echo failed commands\n");
103  HELP0(" -e, --echo-queries echo commands sent to server\n");
104  HELP0(" -E, --echo-hidden display queries that internal commands generate\n");
105  HELP0(" -L, --log-file=FILENAME send session log to file\n");
106  HELP0(" -n, --no-readline disable enhanced command line editing (readline)\n");
107  HELP0(" -o, --output=FILENAME send query results to file (or |pipe)\n");
108  HELP0(" -q, --quiet run quietly (no messages, only query output)\n");
109  HELP0(" -s, --single-step single-step mode (confirm each query)\n");
110  HELP0(" -S, --single-line single-line mode (end of line terminates SQL command)\n");
111 
112  HELP0("\nOutput format options:\n");
113  HELP0(" -A, --no-align unaligned table output mode\n");
114  HELP0(" --csv CSV (Comma-Separated Values) table output mode\n");
115  HELPN(" -F, --field-separator=STRING\n"
116  " field separator for unaligned output (default: \"%s\")\n",
117  DEFAULT_FIELD_SEP);
118  HELP0(" -H, --html HTML table output mode\n");
119  HELP0(" -P, --pset=VAR[=ARG] set printing option VAR to ARG (see \\pset command)\n");
120  HELP0(" -R, --record-separator=STRING\n"
121  " record separator for unaligned output (default: newline)\n");
122  HELP0(" -t, --tuples-only print rows only\n");
123  HELP0(" -T, --table-attr=TEXT set HTML table tag attributes (e.g., width, border)\n");
124  HELP0(" -x, --expanded turn on expanded table output\n");
125  HELP0(" -z, --field-separator-zero\n"
126  " set field separator for unaligned output to zero byte\n");
127  HELP0(" -0, --record-separator-zero\n"
128  " set record separator for unaligned output to zero byte\n");
129 
130  HELP0("\nConnection options:\n");
131  /* Display default host */
132  env = getenv("PGHOST");
133  HELPN(" -h, --host=HOSTNAME database server host or socket directory (default: \"%s\")\n",
134  env ? env : _("local socket"));
135  /* Display default port */
136  env = getenv("PGPORT");
137  HELPN(" -p, --port=PORT database server port (default: \"%s\")\n",
138  env ? env : DEF_PGPORT_STR);
139  /* Display default user */
140  HELPN(" -U, --username=USERNAME database user name (default: \"%s\")\n",
141  user);
142  HELP0(" -w, --no-password never prompt for password\n");
143  HELP0(" -W, --password force password prompt (should happen automatically)\n");
144 
145  HELP0("\nFor more information, type \"\\?\" (for internal commands) or \"\\help\" (for SQL\n"
146  "commands) from within psql, or consult the psql section in the PostgreSQL\n"
147  "documentation.\n\n");
148  HELPN("Report bugs to <%s>.\n", PACKAGE_BUGREPORT);
149  HELPN("%s home page: <%s>\n", PACKAGE_NAME, PACKAGE_URL);
150 
151  /* Now we can count the lines. */
152  nlcount = 0;
153  for (const char *ptr = buf.data; *ptr; ptr++)
154  {
155  if (*ptr == '\n')
156  nlcount++;
157  }
158 
159  /* And dump the output, with appropriate pagination. */
160  output = PageOutput(nlcount, pager ? &(pset.popt.topt) : NULL);
161 
162  fputs(buf.data, output);
163 
164  ClosePager(output);
165 
166  termPQExpBuffer(&buf);
167 }
168 
169 
170 /*
171  * slashUsage
172  *
173  * print out help for the backslash commands
174  */
175 void
176 slashUsage(unsigned short int pager)
177 {
178  PQExpBufferData buf;
179  int nlcount;
180  FILE *output;
181  char *currdb;
182 
183  currdb = PQdb(pset.db);
184 
185  /*
186  * To avoid counting the output lines manually, build the output in "buf"
187  * and then count them.
188  */
189  initPQExpBuffer(&buf);
190 
191  HELP0("General\n");
192  HELP0(" \\bind [PARAM]... set query parameters\n");
193  HELP0(" \\copyright show PostgreSQL usage and distribution terms\n");
194  HELP0(" \\crosstabview [COLUMNS] execute query and display result in crosstab\n");
195  HELP0(" \\errverbose show most recent error message at maximum verbosity\n");
196  HELP0(" \\g [(OPTIONS)] [FILE] execute query (and send result to file or |pipe);\n"
197  " \\g with no arguments is equivalent to a semicolon\n");
198  HELP0(" \\gdesc describe result of query, without executing it\n");
199  HELP0(" \\gexec execute query, then execute each value in its result\n");
200  HELP0(" \\gset [PREFIX] execute query and store result in psql variables\n");
201  HELP0(" \\gx [(OPTIONS)] [FILE] as \\g, but forces expanded output mode\n");
202  HELP0(" \\q quit psql\n");
203  HELP0(" \\watch [[i=]SEC] [c=N] [m=MIN]\n"
204  " execute query every SEC seconds, up to N times\n"
205  " stop if less than MIN rows are returned\n");
206  HELP0("\n");
207 
208  HELP0("Help\n");
209 
210  HELP0(" \\? [commands] show help on backslash commands\n");
211  HELP0(" \\? options show help on psql command-line options\n");
212  HELP0(" \\? variables show help on special variables\n");
213  HELP0(" \\h [NAME] help on syntax of SQL commands, * for all commands\n");
214  HELP0("\n");
215 
216  HELP0("Query Buffer\n");
217  HELP0(" \\e [FILE] [LINE] edit the query buffer (or file) with external editor\n");
218  HELP0(" \\ef [FUNCNAME [LINE]] edit function definition with external editor\n");
219  HELP0(" \\ev [VIEWNAME [LINE]] edit view definition with external editor\n");
220  HELP0(" \\p show the contents of the query buffer\n");
221  HELP0(" \\r reset (clear) the query buffer\n");
222 #ifdef USE_READLINE
223  HELP0(" \\s [FILE] display history or save it to file\n");
224 #endif
225  HELP0(" \\w FILE write query buffer to file\n");
226  HELP0("\n");
227 
228  HELP0("Input/Output\n");
229  HELP0(" \\copy ... perform SQL COPY with data stream to the client host\n");
230  HELP0(" \\echo [-n] [STRING] write string to standard output (-n for no newline)\n");
231  HELP0(" \\i FILE execute commands from file\n");
232  HELP0(" \\ir FILE as \\i, but relative to location of current script\n");
233  HELP0(" \\o [FILE] send all query results to file or |pipe\n");
234  HELP0(" \\qecho [-n] [STRING] write string to \\o output stream (-n for no newline)\n");
235  HELP0(" \\warn [-n] [STRING] write string to standard error (-n for no newline)\n");
236  HELP0("\n");
237 
238  HELP0("Conditional\n");
239  HELP0(" \\if EXPR begin conditional block\n");
240  HELP0(" \\elif EXPR alternative within current conditional block\n");
241  HELP0(" \\else final alternative within current conditional block\n");
242  HELP0(" \\endif end conditional block\n");
243  HELP0("\n");
244 
245  HELP0("Informational\n");
246  HELP0(" (options: S = show system objects, + = additional detail)\n");
247  HELP0(" \\d[S+] list tables, views, and sequences\n");
248  HELP0(" \\d[S+] NAME describe table, view, sequence, or index\n");
249  HELP0(" \\da[S] [PATTERN] list aggregates\n");
250  HELP0(" \\dA[+] [PATTERN] list access methods\n");
251  HELP0(" \\dAc[+] [AMPTRN [TYPEPTRN]] list operator classes\n");
252  HELP0(" \\dAf[+] [AMPTRN [TYPEPTRN]] list operator families\n");
253  HELP0(" \\dAo[+] [AMPTRN [OPFPTRN]] list operators of operator families\n");
254  HELP0(" \\dAp[+] [AMPTRN [OPFPTRN]] list support functions of operator families\n");
255  HELP0(" \\db[+] [PATTERN] list tablespaces\n");
256  HELP0(" \\dc[S+] [PATTERN] list conversions\n");
257  HELP0(" \\dconfig[+] [PATTERN] list configuration parameters\n");
258  HELP0(" \\dC[+] [PATTERN] list casts\n");
259  HELP0(" \\dd[S] [PATTERN] show object descriptions not displayed elsewhere\n");
260  HELP0(" \\dD[S+] [PATTERN] list domains\n");
261  HELP0(" \\ddp [PATTERN] list default privileges\n");
262  HELP0(" \\dE[S+] [PATTERN] list foreign tables\n");
263  HELP0(" \\des[+] [PATTERN] list foreign servers\n");
264  HELP0(" \\det[+] [PATTERN] list foreign tables\n");
265  HELP0(" \\deu[+] [PATTERN] list user mappings\n");
266  HELP0(" \\dew[+] [PATTERN] list foreign-data wrappers\n");
267  HELP0(" \\df[anptw][S+] [FUNCPTRN [TYPEPTRN ...]]\n"
268  " list [only agg/normal/procedure/trigger/window] functions\n");
269  HELP0(" \\dF[+] [PATTERN] list text search configurations\n");
270  HELP0(" \\dFd[+] [PATTERN] list text search dictionaries\n");
271  HELP0(" \\dFp[+] [PATTERN] list text search parsers\n");
272  HELP0(" \\dFt[+] [PATTERN] list text search templates\n");
273  HELP0(" \\dg[S+] [PATTERN] list roles\n");
274  HELP0(" \\di[S+] [PATTERN] list indexes\n");
275  HELP0(" \\dl[+] list large objects, same as \\lo_list\n");
276  HELP0(" \\dL[S+] [PATTERN] list procedural languages\n");
277  HELP0(" \\dm[S+] [PATTERN] list materialized views\n");
278  HELP0(" \\dn[S+] [PATTERN] list schemas\n");
279  HELP0(" \\do[S+] [OPPTRN [TYPEPTRN [TYPEPTRN]]]\n"
280  " list operators\n");
281  HELP0(" \\dO[S+] [PATTERN] list collations\n");
282  HELP0(" \\dp[S] [PATTERN] list table, view, and sequence access privileges\n");
283  HELP0(" \\dP[itn+] [PATTERN] list [only index/table] partitioned relations [n=nested]\n");
284  HELP0(" \\drds [ROLEPTRN [DBPTRN]] list per-database role settings\n");
285  HELP0(" \\drg[S] [PATTERN] list role grants\n");
286  HELP0(" \\dRp[+] [PATTERN] list replication publications\n");
287  HELP0(" \\dRs[+] [PATTERN] list replication subscriptions\n");
288  HELP0(" \\ds[S+] [PATTERN] list sequences\n");
289  HELP0(" \\dt[S+] [PATTERN] list tables\n");
290  HELP0(" \\dT[S+] [PATTERN] list data types\n");
291  HELP0(" \\du[S+] [PATTERN] list roles\n");
292  HELP0(" \\dv[S+] [PATTERN] list views\n");
293  HELP0(" \\dx[+] [PATTERN] list extensions\n");
294  HELP0(" \\dX [PATTERN] list extended statistics\n");
295  HELP0(" \\dy[+] [PATTERN] list event triggers\n");
296  HELP0(" \\l[+] [PATTERN] list databases\n");
297  HELP0(" \\sf[+] FUNCNAME show a function's definition\n");
298  HELP0(" \\sv[+] VIEWNAME show a view's definition\n");
299  HELP0(" \\z[S] [PATTERN] same as \\dp\n");
300  HELP0("\n");
301 
302  HELP0("Large Objects\n");
303  HELP0(" \\lo_export LOBOID FILE write large object to file\n");
304  HELP0(" \\lo_import FILE [COMMENT]\n"
305  " read large object from file\n");
306  HELP0(" \\lo_list[+] list large objects\n");
307  HELP0(" \\lo_unlink LOBOID delete a large object\n");
308  HELP0("\n");
309 
310  HELP0("Formatting\n");
311  HELP0(" \\a toggle between unaligned and aligned output mode\n");
312  HELP0(" \\C [STRING] set table title, or unset if none\n");
313  HELP0(" \\f [STRING] show or set field separator for unaligned query output\n");
314  HELPN(" \\H toggle HTML output mode (currently %s)\n",
315  ON(pset.popt.topt.format == PRINT_HTML));
316  HELP0(" \\pset [NAME [VALUE]] set table output option\n"
317  " (border|columns|csv_fieldsep|expanded|fieldsep|\n"
318  " fieldsep_zero|footer|format|linestyle|null|\n"
319  " numericlocale|pager|pager_min_lines|recordsep|\n"
320  " recordsep_zero|tableattr|title|tuples_only|\n"
321  " unicode_border_linestyle|unicode_column_linestyle|\n"
322  " unicode_header_linestyle)\n");
323  HELPN(" \\t [on|off] show only rows (currently %s)\n",
324  ON(pset.popt.topt.tuples_only));
325  HELP0(" \\T [STRING] set HTML <table> tag attributes, or unset if none\n");
326  HELPN(" \\x [on|off|auto] toggle expanded output (currently %s)\n",
327  pset.popt.topt.expanded == 2 ? _("auto") : ON(pset.popt.topt.expanded));
328  HELP0("\n");
329 
330  HELP0("Connection\n");
331  if (currdb)
332  HELPN(" \\c[onnect] {[DBNAME|- USER|- HOST|- PORT|-] | conninfo}\n"
333  " connect to new database (currently \"%s\")\n",
334  currdb);
335  else
336  HELP0(" \\c[onnect] {[DBNAME|- USER|- HOST|- PORT|-] | conninfo}\n"
337  " connect to new database (currently no connection)\n");
338  HELP0(" \\conninfo display information about current connection\n");
339  HELP0(" \\encoding [ENCODING] show or set client encoding\n");
340  HELP0(" \\password [USERNAME] securely change the password for a user\n");
341  HELP0("\n");
342 
343  HELP0("Operating System\n");
344  HELP0(" \\cd [DIR] change the current working directory\n");
345  HELP0(" \\getenv PSQLVAR ENVVAR fetch environment variable\n");
346  HELP0(" \\setenv NAME [VALUE] set or unset environment variable\n");
347  HELPN(" \\timing [on|off] toggle timing of commands (currently %s)\n",
348  ON(pset.timing));
349  HELP0(" \\! [COMMAND] execute command in shell or start interactive shell\n");
350  HELP0("\n");
351 
352  HELP0("Variables\n");
353  HELP0(" \\prompt [TEXT] NAME prompt user to set internal variable\n");
354  HELP0(" \\set [NAME [VALUE]] set internal variable, or list all if no parameters\n");
355  HELP0(" \\unset NAME unset (delete) internal variable\n");
356 
357  /* Now we can count the lines. */
358  nlcount = 0;
359  for (const char *ptr = buf.data; *ptr; ptr++)
360  {
361  if (*ptr == '\n')
362  nlcount++;
363  }
364 
365  /* And dump the output, with appropriate pagination. */
366  output = PageOutput(nlcount, pager ? &(pset.popt.topt) : NULL);
367 
368  fputs(buf.data, output);
369 
370  ClosePager(output);
371 
372  termPQExpBuffer(&buf);
373 }
374 
375 
376 /*
377  * helpVariables
378  *
379  * show list of available variables (options) from command line
380  */
381 void
382 helpVariables(unsigned short int pager)
383 {
384  PQExpBufferData buf;
385  int nlcount;
386  FILE *output;
387 
388  /*
389  * To avoid counting the output lines manually, build the output in "buf"
390  * and then count them.
391  */
392  initPQExpBuffer(&buf);
393 
394  HELP0("List of specially treated variables\n\n");
395 
396  HELP0("psql variables:\n");
397  HELP0("Usage:\n");
398  HELP0(" psql --set=NAME=VALUE\n or \\set NAME VALUE inside psql\n\n");
399 
400  HELP0(" AUTOCOMMIT\n"
401  " if set, successful SQL commands are automatically committed\n");
402  HELP0(" COMP_KEYWORD_CASE\n"
403  " determines the case used to complete SQL key words\n"
404  " [lower, upper, preserve-lower, preserve-upper]\n");
405  HELP0(" DBNAME\n"
406  " the currently connected database name\n");
407  HELP0(" ECHO\n"
408  " controls what input is written to standard output\n"
409  " [all, errors, none, queries]\n");
410  HELP0(" ECHO_HIDDEN\n"
411  " if set, display internal queries executed by backslash commands;\n"
412  " if set to \"noexec\", just show them without execution\n");
413  HELP0(" ENCODING\n"
414  " current client character set encoding\n");
415  HELP0(" ERROR\n"
416  " \"true\" if last query failed, else \"false\"\n");
417  HELP0(" FETCH_COUNT\n"
418  " the number of result rows to fetch and display at a time (0 = unlimited)\n");
419  HELP0(" HIDE_TABLEAM\n"
420  " if set, table access methods are not displayed\n");
421  HELP0(" HIDE_TOAST_COMPRESSION\n"
422  " if set, compression methods are not displayed\n");
423  HELP0(" HISTCONTROL\n"
424  " controls command history [ignorespace, ignoredups, ignoreboth]\n");
425  HELP0(" HISTFILE\n"
426  " file name used to store the command history\n");
427  HELP0(" HISTSIZE\n"
428  " maximum number of commands to store in the command history\n");
429  HELP0(" HOST\n"
430  " the currently connected database server host\n");
431  HELP0(" IGNOREEOF\n"
432  " number of EOFs needed to terminate an interactive session\n");
433  HELP0(" LASTOID\n"
434  " value of the last affected OID\n");
435  HELP0(" LAST_ERROR_MESSAGE\n"
436  " LAST_ERROR_SQLSTATE\n"
437  " message and SQLSTATE of last error, or empty string and \"00000\" if none\n");
438  HELP0(" ON_ERROR_ROLLBACK\n"
439  " if set, an error doesn't stop a transaction (uses implicit savepoints)\n");
440  HELP0(" ON_ERROR_STOP\n"
441  " stop batch execution after error\n");
442  HELP0(" PORT\n"
443  " server port of the current connection\n");
444  HELP0(" PROMPT1\n"
445  " specifies the standard psql prompt\n");
446  HELP0(" PROMPT2\n"
447  " specifies the prompt used when a statement continues from a previous line\n");
448  HELP0(" PROMPT3\n"
449  " specifies the prompt used during COPY ... FROM STDIN\n");
450  HELP0(" QUIET\n"
451  " run quietly (same as -q option)\n");
452  HELP0(" ROW_COUNT\n"
453  " number of rows returned or affected by last query, or 0\n");
454  HELP0(" SERVER_VERSION_NAME\n"
455  " SERVER_VERSION_NUM\n"
456  " server's version (in short string or numeric format)\n");
457  HELP0(" SHELL_ERROR\n"
458  " \"true\" if the last shell command failed, \"false\" if it succeeded\n");
459  HELP0(" SHELL_EXIT_CODE\n"
460  " exit status of the last shell command\n");
461  HELP0(" SHOW_ALL_RESULTS\n"
462  " show all results of a combined query (\\;) instead of only the last\n");
463  HELP0(" SHOW_CONTEXT\n"
464  " controls display of message context fields [never, errors, always]\n");
465  HELP0(" SINGLELINE\n"
466  " if set, end of line terminates SQL commands (same as -S option)\n");
467  HELP0(" SINGLESTEP\n"
468  " single-step mode (same as -s option)\n");
469  HELP0(" SQLSTATE\n"
470  " SQLSTATE of last query, or \"00000\" if no error\n");
471  HELP0(" USER\n"
472  " the currently connected database user\n");
473  HELP0(" VERBOSITY\n"
474  " controls verbosity of error reports [default, verbose, terse, sqlstate]\n");
475  HELP0(" VERSION\n"
476  " VERSION_NAME\n"
477  " VERSION_NUM\n"
478  " psql's version (in verbose string, short string, or numeric format)\n");
479 
480  HELP0("\nDisplay settings:\n");
481  HELP0("Usage:\n");
482  HELP0(" psql --pset=NAME[=VALUE]\n or \\pset NAME [VALUE] inside psql\n\n");
483 
484  HELP0(" border\n"
485  " border style (number)\n");
486  HELP0(" columns\n"
487  " target width for the wrapped format\n");
488  HELP0(" expanded (or x)\n"
489  " expanded output [on, off, auto]\n");
490  HELPN(" fieldsep\n"
491  " field separator for unaligned output (default \"%s\")\n",
492  DEFAULT_FIELD_SEP);
493  HELP0(" fieldsep_zero\n"
494  " set field separator for unaligned output to a zero byte\n");
495  HELP0(" footer\n"
496  " enable or disable display of the table footer [on, off]\n");
497  HELP0(" format\n"
498  " set output format [unaligned, aligned, wrapped, html, asciidoc, ...]\n");
499  HELP0(" linestyle\n"
500  " set the border line drawing style [ascii, old-ascii, unicode]\n");
501  HELP0(" null\n"
502  " set the string to be printed in place of a null value\n");
503  HELP0(" numericlocale\n"
504  " enable display of a locale-specific character to separate groups of digits\n");
505  HELP0(" pager\n"
506  " control when an external pager is used [yes, no, always]\n");
507  HELP0(" recordsep\n"
508  " record (line) separator for unaligned output\n");
509  HELP0(" recordsep_zero\n"
510  " set record separator for unaligned output to a zero byte\n");
511  HELP0(" tableattr (or T)\n"
512  " specify attributes for table tag in html format, or proportional\n"
513  " column widths for left-aligned data types in latex-longtable format\n");
514  HELP0(" title\n"
515  " set the table title for subsequently printed tables\n");
516  HELP0(" tuples_only\n"
517  " if set, only actual table data is shown\n");
518  HELP0(" unicode_border_linestyle\n"
519  " unicode_column_linestyle\n"
520  " unicode_header_linestyle\n"
521  " set the style of Unicode line drawing [single, double]\n");
522 
523  HELP0("\nEnvironment variables:\n");
524  HELP0("Usage:\n");
525 
526 #ifndef WIN32
527  HELP0(" NAME=VALUE [NAME=VALUE] psql ...\n or \\setenv NAME [VALUE] inside psql\n\n");
528 #else
529  HELP0(" set NAME=VALUE\n psql ...\n or \\setenv NAME [VALUE] inside psql\n\n");
530 #endif
531 
532  HELP0(" COLUMNS\n"
533  " number of columns for wrapped format\n");
534  HELP0(" PGAPPNAME\n"
535  " same as the application_name connection parameter\n");
536  HELP0(" PGDATABASE\n"
537  " same as the dbname connection parameter\n");
538  HELP0(" PGHOST\n"
539  " same as the host connection parameter\n");
540  HELP0(" PGPASSFILE\n"
541  " password file name\n");
542  HELP0(" PGPASSWORD\n"
543  " connection password (not recommended)\n");
544  HELP0(" PGPORT\n"
545  " same as the port connection parameter\n");
546  HELP0(" PGUSER\n"
547  " same as the user connection parameter\n");
548  HELP0(" PSQL_EDITOR, EDITOR, VISUAL\n"
549  " editor used by the \\e, \\ef, and \\ev commands\n");
550  HELP0(" PSQL_EDITOR_LINENUMBER_ARG\n"
551  " how to specify a line number when invoking the editor\n");
552  HELP0(" PSQL_HISTORY\n"
553  " alternative location for the command history file\n");
554  HELP0(" PSQL_PAGER, PAGER\n"
555  " name of external pager program\n");
556 #ifndef WIN32
557  HELP0(" PSQL_WATCH_PAGER\n"
558  " name of external pager program used for \\watch\n");
559 #endif
560  HELP0(" PSQLRC\n"
561  " alternative location for the user's .psqlrc file\n");
562  HELP0(" SHELL\n"
563  " shell used by the \\! command\n");
564  HELP0(" TMPDIR\n"
565  " directory for temporary files\n");
566 
567  /* Now we can count the lines. */
568  nlcount = 0;
569  for (const char *ptr = buf.data; *ptr; ptr++)
570  {
571  if (*ptr == '\n')
572  nlcount++;
573  }
574 
575  /* And dump the output, with appropriate pagination. */
576  output = PageOutput(nlcount, pager ? &(pset.popt.topt) : NULL);
577 
578  fputs(buf.data, output);
579 
580  ClosePager(output);
581 
582  termPQExpBuffer(&buf);
583 }
584 
585 
586 /*
587  * helpSQL -- help with SQL commands
588  *
589  * Note: we assume caller removed any trailing spaces in "topic".
590  */
591 void
592 helpSQL(const char *topic, unsigned short int pager)
593 {
594 #define VALUE_OR_NULL(a) ((a) ? (a) : "")
595 
596  if (!topic || strlen(topic) == 0)
597  {
598  /* Print all the available command names */
599  int screen_width;
600  int ncolumns;
601  int nrows;
602  FILE *output;
603  int i;
604  int j;
605 
606  /* Find screen width to determine how many columns will fit */
607 #ifdef TIOCGWINSZ
608  struct winsize screen_size;
609 
610  if (ioctl(fileno(stdout), TIOCGWINSZ, &screen_size) == -1)
611  screen_width = 80; /* ioctl failed, assume 80 */
612  else
613  screen_width = screen_size.ws_col;
614 #else
615  screen_width = 80; /* default assumption */
616 #endif
617 
618  ncolumns = (screen_width - 3) / (QL_MAX_CMD_LEN + 1);
619  ncolumns = Max(ncolumns, 1);
620  nrows = (QL_HELP_COUNT + (ncolumns - 1)) / ncolumns;
621 
622  output = PageOutput(nrows + 1, pager ? &(pset.popt.topt) : NULL);
623 
624  fputs(_("Available help:\n"), output);
625 
626  for (i = 0; i < nrows; i++)
627  {
628  fprintf(output, " ");
629  for (j = 0; j < ncolumns - 1; j++)
630  fprintf(output, "%-*s",
631  QL_MAX_CMD_LEN + 1,
632  VALUE_OR_NULL(QL_HELP[i + j * nrows].cmd));
633  if (i + j * nrows < QL_HELP_COUNT)
634  fprintf(output, "%s",
635  VALUE_OR_NULL(QL_HELP[i + j * nrows].cmd));
636  fputc('\n', output);
637  }
638 
639  ClosePager(output);
640  }
641  else
642  {
643  int i,
644  pass;
645  FILE *output = NULL;
646  size_t len,
647  wordlen,
648  j;
649  int nl_count;
650 
651  /*
652  * len is the amount of the input to compare to the help topic names.
653  * We first try exact match, then first + second words, then first
654  * word only.
655  */
656  len = strlen(topic);
657 
658  for (pass = 1; pass <= 3; pass++)
659  {
660  if (pass > 1) /* Nothing on first pass - try the opening
661  * word(s) */
662  {
663  wordlen = j = 1;
664  while (j < len && topic[j++] != ' ')
665  wordlen++;
666  if (pass == 2 && j < len)
667  {
668  wordlen++;
669  while (j < len && topic[j++] != ' ')
670  wordlen++;
671  }
672  if (wordlen >= len)
673  {
674  /* Failed to shorten input, so try next pass if any */
675  continue;
676  }
677  len = wordlen;
678  }
679 
680  /*
681  * Count newlines for pager. This logic must agree with what the
682  * following loop will do!
683  */
684  nl_count = 0;
685  for (i = 0; QL_HELP[i].cmd; i++)
686  {
687  if (pg_strncasecmp(topic, QL_HELP[i].cmd, len) == 0 ||
688  strcmp(topic, "*") == 0)
689  {
690  /* magic constant here must match format below! */
691  nl_count += 7 + QL_HELP[i].nl_count;
692 
693  /* If we have an exact match, exit. Fixes \h SELECT */
694  if (pg_strcasecmp(topic, QL_HELP[i].cmd) == 0)
695  break;
696  }
697  }
698  /* If no matches, don't open the output yet */
699  if (nl_count == 0)
700  continue;
701 
702  if (!output)
703  output = PageOutput(nl_count, pager ? &(pset.popt.topt) : NULL);
704 
705  for (i = 0; QL_HELP[i].cmd; i++)
706  {
707  if (pg_strncasecmp(topic, QL_HELP[i].cmd, len) == 0 ||
708  strcmp(topic, "*") == 0)
709  {
710  PQExpBufferData buffer;
711  char *url;
712 
713  initPQExpBuffer(&buffer);
714  QL_HELP[i].syntaxfunc(&buffer);
715  url = psprintf("https://www.postgresql.org/docs/%s/%s.html",
716  strstr(PG_VERSION, "devel") ? "devel" : PG_MAJORVERSION,
717  QL_HELP[i].docbook_id);
718  /* # of newlines in format must match constant above! */
719  fprintf(output, _("Command: %s\n"
720  "Description: %s\n"
721  "Syntax:\n%s\n\n"
722  "URL: %s\n\n"),
723  QL_HELP[i].cmd,
724  _(QL_HELP[i].help),
725  buffer.data,
726  url);
727  free(url);
728  termPQExpBuffer(&buffer);
729 
730  /* If we have an exact match, exit. Fixes \h SELECT */
731  if (pg_strcasecmp(topic, QL_HELP[i].cmd) == 0)
732  break;
733  }
734  }
735  break;
736  }
737 
738  /* If we never found anything, report that */
739  if (!output)
740  {
741  output = PageOutput(2, pager ? &(pset.popt.topt) : NULL);
742  fprintf(output, _("No help available for \"%s\".\n"
743  "Try \\h with no arguments to see available help.\n"),
744  topic);
745  }
746 
747  ClosePager(output);
748  }
749 }
750 
751 
752 
753 void
754 print_copyright(void)
755 {
756  puts("PostgreSQL Database Management System\n"
757  "(formerly known as Postgres, then as Postgres95)\n\n"
758  "Portions Copyright (c) 1996-2023, PostgreSQL Global Development Group\n\n"
759  "Portions Copyright (c) 1994, The Regents of the University of California\n\n"
760  "Permission to use, copy, modify, and distribute this software and its\n"
761  "documentation for any purpose, without fee, and without a written agreement\n"
762  "is hereby granted, provided that the above copyright notice and this\n"
763  "paragraph and the following two paragraphs appear in all copies.\n\n"
764  "IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR\n"
765  "DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING\n"
766  "LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS\n"
767  "DOCUMENTATION, EVEN IF THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE\n"
768  "POSSIBILITY OF SUCH DAMAGE.\n\n"
769  "THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,\n"
770  "INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY\n"
771  "AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS\n"
772  "ON AN \"AS IS\" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATIONS TO\n"
773  "PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.\n");
774 }
Max
#define Max(x, y)
Definition: c.h:987
_
#define _(x)
Definition: elog.c:91
PQdb
char * PQdb(const PGconn *conn)
Definition: fe-connect.c:7094
ClosePager
void ClosePager(FILE *pagerpipe)
Definition: print.c:3141
PageOutput
FILE * PageOutput(int lines, const printTableOpt *topt)
Definition: print.c:3089
PRINT_HTML
@ PRINT_HTML
Definition: print.h:34
free
#define free(a)
Definition: header.h:65
VALUE_OR_NULL
#define VALUE_OR_NULL(a)
HELPN
#define HELPN(str,...)
Definition: help.c:41
HELP0
#define HELP0(str)
Definition: help.c:40
usage
void usage(unsigned short int pager)
Definition: help.c:51
slashUsage
void slashUsage(unsigned short int pager)
Definition: help.c:176
ON
#define ON(var)
Definition: help.c:42
helpVariables
void helpVariables(unsigned short int pager)
helpSQL
void helpSQL(const char *topic, unsigned short int pager)
print_copyright
void print_copyright(void)
output
FILE * output
Definition: pg_test_timing.c:182
j
int j
Definition: isn.c:74
i
int i
Definition: isn.c:73
generate_unaccent_rules.help
help
Definition: generate_unaccent_rules.py:280
generate_unaccent_rules.stdout
stdout
Definition: generate_unaccent_rules.py:35
pg_fatal
#define pg_fatal(...)
Definition: pg_backup_utils.h:36
len
const void size_t len
Definition: pg_crc32c_sse42.c:24
user
static char * user
Definition: pg_regress.c:112
buf
static char * buf
Definition: pg_test_fsync.c:67
pg_strcasecmp
int pg_strcasecmp(const char *s1, const char *s2)
Definition: pgstrcasecmp.c:36
fprintf
#define fprintf
Definition: port.h:242
pg_strncasecmp
int pg_strncasecmp(const char *s1, const char *s2, size_t n)
Definition: pgstrcasecmp.c:69
postgres_fe.h
initPQExpBuffer
void initPQExpBuffer(PQExpBuffer str)
Definition: pqexpbuffer.c:90
termPQExpBuffer
void termPQExpBuffer(PQExpBuffer str)
Definition: pqexpbuffer.c:129
psprintf
char * psprintf(const char *fmt,...)
Definition: psprintf.c:46
DEFAULT_FIELD_SEP
#define DEFAULT_FIELD_SEP
Definition: settings.h:15
pset
PsqlSettings pset
Definition: startup.c:32
_psqlSettings::popt
printQueryOpt popt
Definition: settings.h:91
_psqlSettings::timing
bool timing
Definition: settings.h:118
_psqlSettings::db
PGconn * db
Definition: settings.h:82
printQueryOpt::topt
printTableOpt topt
Definition: print.h:185
printTableOpt::expanded
unsigned short int expanded
Definition: print.h:114
printTableOpt::tuples_only
bool tuples_only
Definition: print.h:126
printTableOpt::format
enum printFormat format
Definition: print.h:113
get_user_name
const char * get_user_name(char **errstr)
Definition: username.c:31