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