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