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