Header And Logo
|
00001 /* 00002 * psql - the PostgreSQL interactive terminal 00003 * 00004 * Copyright (c) 2000-2013, PostgreSQL Global Development Group 00005 * 00006 * src/bin/psql/help.c 00007 */ 00008 #include "postgres_fe.h" 00009 00010 #ifndef WIN32 00011 #ifdef HAVE_PWD_H 00012 #include <pwd.h> /* for getpwuid() */ 00013 #endif 00014 #include <sys/types.h> /* (ditto) */ 00015 #include <unistd.h> /* for geteuid() */ 00016 #else 00017 #include <win32.h> 00018 #endif 00019 00020 #ifndef WIN32 00021 #include <sys/ioctl.h> /* for ioctl() */ 00022 #endif 00023 00024 #ifdef HAVE_TERMIOS_H 00025 #include <termios.h> 00026 #endif 00027 00028 #include "common.h" 00029 #include "help.h" 00030 #include "input.h" 00031 #include "settings.h" 00032 #include "sql_help.h" 00033 00034 00035 /* 00036 * PLEASE: 00037 * If you change something in this file, also make the same changes 00038 * in the DocBook documentation, file ref/psql-ref.sgml. If you don't 00039 * know how to do it, please find someone who can help you. 00040 */ 00041 00042 00043 /* 00044 * usage 00045 * 00046 * print out command line arguments 00047 */ 00048 #define ON(var) (var ? _("on") : _("off")) 00049 00050 void 00051 usage(void) 00052 { 00053 const char *env; 00054 const char *user; 00055 00056 #ifndef WIN32 00057 struct passwd *pw = NULL; 00058 #endif 00059 00060 /* Find default user, in case we need it. */ 00061 user = getenv("PGUSER"); 00062 if (!user) 00063 { 00064 #if !defined(WIN32) && !defined(__OS2__) 00065 pw = getpwuid(geteuid()); 00066 if (pw) 00067 user = pw->pw_name; 00068 else 00069 { 00070 psql_error("could not get current user name: %s\n", strerror(errno)); 00071 exit(EXIT_FAILURE); 00072 } 00073 #else /* WIN32 */ 00074 char buf[128]; 00075 DWORD bufsize = sizeof(buf) - 1; 00076 00077 if (GetUserName(buf, &bufsize)) 00078 user = buf; 00079 #endif /* WIN32 */ 00080 } 00081 00082 printf(_("psql is the PostgreSQL interactive terminal.\n\n")); 00083 printf(_("Usage:\n")); 00084 printf(_(" psql [OPTION]... [DBNAME [USERNAME]]\n\n")); 00085 00086 printf(_("General options:\n")); 00087 /* Display default database */ 00088 env = getenv("PGDATABASE"); 00089 if (!env) 00090 env = user; 00091 printf(_(" -c, --command=COMMAND run only single command (SQL or internal) and exit\n")); 00092 printf(_(" -d, --dbname=DBNAME database name to connect to (default: \"%s\")\n"), env); 00093 printf(_(" -f, --file=FILENAME execute commands from file, then exit\n")); 00094 printf(_(" -l, --list list available databases, then exit\n")); 00095 printf(_(" -v, --set=, --variable=NAME=VALUE\n" 00096 " set psql variable NAME to VALUE\n")); 00097 printf(_(" -V, --version output version information, then exit\n")); 00098 printf(_(" -X, --no-psqlrc do not read startup file (~/.psqlrc)\n")); 00099 printf(_(" -1 (\"one\"), --single-transaction\n" 00100 " execute as a single transaction (if non-interactive)\n")); 00101 printf(_(" -?, --help show this help, then exit\n")); 00102 00103 printf(_("\nInput and output options:\n")); 00104 printf(_(" -a, --echo-all echo all input from script\n")); 00105 printf(_(" -e, --echo-queries echo commands sent to server\n")); 00106 printf(_(" -E, --echo-hidden display queries that internal commands generate\n")); 00107 printf(_(" -L, --log-file=FILENAME send session log to file\n")); 00108 printf(_(" -n, --no-readline disable enhanced command line editing (readline)\n")); 00109 printf(_(" -o, --output=FILENAME send query results to file (or |pipe)\n")); 00110 printf(_(" -q, --quiet run quietly (no messages, only query output)\n")); 00111 printf(_(" -s, --single-step single-step mode (confirm each query)\n")); 00112 printf(_(" -S, --single-line single-line mode (end of line terminates SQL command)\n")); 00113 00114 printf(_("\nOutput format options:\n")); 00115 printf(_(" -A, --no-align unaligned table output mode\n")); 00116 printf(_(" -F, --field-separator=STRING\n" 00117 " set field separator (default: \"%s\")\n"), 00118 DEFAULT_FIELD_SEP); 00119 printf(_(" -H, --html HTML table output mode\n")); 00120 printf(_(" -P, --pset=VAR[=ARG] set printing option VAR to ARG (see \\pset command)\n")); 00121 printf(_(" -R, --record-separator=STRING\n" 00122 " set record separator (default: newline)\n")); 00123 printf(_(" -t, --tuples-only print rows only\n")); 00124 printf(_(" -T, --table-attr=TEXT set HTML table tag attributes (e.g., width, border)\n")); 00125 printf(_(" -x, --expanded turn on expanded table output\n")); 00126 printf(_(" -z, --field-separator-zero\n" 00127 " set field separator to zero byte\n")); 00128 printf(_(" -0, --record-separator-zero\n" 00129 " set record separator to zero byte\n")); 00130 00131 printf(_("\nConnection options:\n")); 00132 /* Display default host */ 00133 env = getenv("PGHOST"); 00134 printf(_(" -h, --host=HOSTNAME database server host or socket directory (default: \"%s\")\n"), 00135 env ? env : _("local socket")); 00136 /* Display default port */ 00137 env = getenv("PGPORT"); 00138 printf(_(" -p, --port=PORT database server port (default: \"%s\")\n"), 00139 env ? env : DEF_PGPORT_STR); 00140 /* Display default user */ 00141 env = getenv("PGUSER"); 00142 if (!env) 00143 env = user; 00144 printf(_(" -U, --username=USERNAME database user name (default: \"%s\")\n"), env); 00145 printf(_(" -w, --no-password never prompt for password\n")); 00146 printf(_(" -W, --password force password prompt (should happen automatically)\n")); 00147 00148 printf(_("\nFor more information, type \"\\?\" (for internal commands) or \"\\help\" (for SQL\n" 00149 "commands) from within psql, or consult the psql section in the PostgreSQL\n" 00150 "documentation.\n\n")); 00151 printf(_("Report bugs to <[email protected]>.\n")); 00152 } 00153 00154 00155 /* 00156 * slashUsage 00157 * 00158 * print out help for the backslash commands 00159 */ 00160 void 00161 slashUsage(unsigned short int pager) 00162 { 00163 FILE *output; 00164 char *currdb; 00165 00166 currdb = PQdb(pset.db); 00167 00168 output = PageOutput(103, pager); 00169 00170 /* if you add/remove a line here, change the row count above */ 00171 00172 fprintf(output, _("General\n")); 00173 fprintf(output, _(" \\copyright show PostgreSQL usage and distribution terms\n")); 00174 fprintf(output, _(" \\g [FILE] or ; execute query (and send results to file or |pipe)\n")); 00175 fprintf(output, _(" \\gset [PREFIX] execute query and store results in psql variables\n")); 00176 fprintf(output, _(" \\h [NAME] help on syntax of SQL commands, * for all commands\n")); 00177 fprintf(output, _(" \\q quit psql\n")); 00178 fprintf(output, _(" \\watch [SEC] execute query every SEC seconds\n")); 00179 fprintf(output, "\n"); 00180 00181 fprintf(output, _("Query Buffer\n")); 00182 fprintf(output, _(" \\e [FILE] [LINE] edit the query buffer (or file) with external editor\n")); 00183 fprintf(output, _(" \\ef [FUNCNAME [LINE]] edit function definition with external editor\n")); 00184 fprintf(output, _(" \\p show the contents of the query buffer\n")); 00185 fprintf(output, _(" \\r reset (clear) the query buffer\n")); 00186 #ifdef USE_READLINE 00187 fprintf(output, _(" \\s [FILE] display history or save it to file\n")); 00188 #endif 00189 fprintf(output, _(" \\w FILE write query buffer to file\n")); 00190 fprintf(output, "\n"); 00191 00192 fprintf(output, _("Input/Output\n")); 00193 fprintf(output, _(" \\copy ... perform SQL COPY with data stream to the client host\n")); 00194 fprintf(output, _(" \\echo [STRING] write string to standard output\n")); 00195 fprintf(output, _(" \\i FILE execute commands from file\n")); 00196 fprintf(output, _(" \\ir FILE as \\i, but relative to location of current script\n")); 00197 fprintf(output, _(" \\o [FILE] send all query results to file or |pipe\n")); 00198 fprintf(output, _(" \\qecho [STRING] write string to query output stream (see \\o)\n")); 00199 fprintf(output, "\n"); 00200 00201 fprintf(output, _("Informational\n")); 00202 fprintf(output, _(" (options: S = show system objects, + = additional detail)\n")); 00203 fprintf(output, _(" \\d[S+] list tables, views, and sequences\n")); 00204 fprintf(output, _(" \\d[S+] NAME describe table, view, sequence, or index\n")); 00205 fprintf(output, _(" \\da[S] [PATTERN] list aggregates\n")); 00206 fprintf(output, _(" \\db[+] [PATTERN] list tablespaces\n")); 00207 fprintf(output, _(" \\dc[S+] [PATTERN] list conversions\n")); 00208 fprintf(output, _(" \\dC[+] [PATTERN] list casts\n")); 00209 fprintf(output, _(" \\dd[S] [PATTERN] show object descriptions not displayed elsewhere\n")); 00210 fprintf(output, _(" \\ddp [PATTERN] list default privileges\n")); 00211 fprintf(output, _(" \\dD[S+] [PATTERN] list domains\n")); 00212 fprintf(output, _(" \\det[+] [PATTERN] list foreign tables\n")); 00213 fprintf(output, _(" \\des[+] [PATTERN] list foreign servers\n")); 00214 fprintf(output, _(" \\deu[+] [PATTERN] list user mappings\n")); 00215 fprintf(output, _(" \\dew[+] [PATTERN] list foreign-data wrappers\n")); 00216 fprintf(output, _(" \\df[antw][S+] [PATRN] list [only agg/normal/trigger/window] functions\n")); 00217 fprintf(output, _(" \\dF[+] [PATTERN] list text search configurations\n")); 00218 fprintf(output, _(" \\dFd[+] [PATTERN] list text search dictionaries\n")); 00219 fprintf(output, _(" \\dFp[+] [PATTERN] list text search parsers\n")); 00220 fprintf(output, _(" \\dFt[+] [PATTERN] list text search templates\n")); 00221 fprintf(output, _(" \\dg[+] [PATTERN] list roles\n")); 00222 fprintf(output, _(" \\di[S+] [PATTERN] list indexes\n")); 00223 fprintf(output, _(" \\dl list large objects, same as \\lo_list\n")); 00224 fprintf(output, _(" \\dL[S+] [PATTERN] list procedural languages\n")); 00225 fprintf(output, _(" \\dm[S+] [PATTERN] list materialized views\n")); 00226 fprintf(output, _(" \\dn[S+] [PATTERN] list schemas\n")); 00227 fprintf(output, _(" \\do[S] [PATTERN] list operators\n")); 00228 fprintf(output, _(" \\dO[S+] [PATTERN] list collations\n")); 00229 fprintf(output, _(" \\dp [PATTERN] list table, view, and sequence access privileges\n")); 00230 fprintf(output, _(" \\drds [PATRN1 [PATRN2]] list per-database role settings\n")); 00231 fprintf(output, _(" \\ds[S+] [PATTERN] list sequences\n")); 00232 fprintf(output, _(" \\dt[S+] [PATTERN] list tables\n")); 00233 fprintf(output, _(" \\dT[S+] [PATTERN] list data types\n")); 00234 fprintf(output, _(" \\du[+] [PATTERN] list roles\n")); 00235 fprintf(output, _(" \\dv[S+] [PATTERN] list views\n")); 00236 fprintf(output, _(" \\dE[S+] [PATTERN] list foreign tables\n")); 00237 fprintf(output, _(" \\dx[+] [PATTERN] list extensions\n")); 00238 fprintf(output, _(" \\dy [PATTERN] list event triggers\n")); 00239 fprintf(output, _(" \\l[+] [PATTERN] list databases\n")); 00240 fprintf(output, _(" \\sf[+] FUNCNAME show a function's definition\n")); 00241 fprintf(output, _(" \\z [PATTERN] same as \\dp\n")); 00242 fprintf(output, "\n"); 00243 00244 fprintf(output, _("Formatting\n")); 00245 fprintf(output, _(" \\a toggle between unaligned and aligned output mode\n")); 00246 fprintf(output, _(" \\C [STRING] set table title, or unset if none\n")); 00247 fprintf(output, _(" \\f [STRING] show or set field separator for unaligned query output\n")); 00248 fprintf(output, _(" \\H toggle HTML output mode (currently %s)\n"), 00249 ON(pset.popt.topt.format == PRINT_HTML)); 00250 fprintf(output, _(" \\pset NAME [VALUE] set table output option\n" 00251 " (NAME := {format|border|expanded|fieldsep|fieldsep_zero|footer|null|\n" 00252 " numericlocale|recordsep|recordsep_zero|tuples_only|title|tableattr|pager})\n")); 00253 fprintf(output, _(" \\t [on|off] show only rows (currently %s)\n"), 00254 ON(pset.popt.topt.tuples_only)); 00255 fprintf(output, _(" \\T [STRING] set HTML <table> tag attributes, or unset if none\n")); 00256 fprintf(output, _(" \\x [on|off|auto] toggle expanded output (currently %s)\n"), 00257 pset.popt.topt.expanded == 2 ? "auto" : ON(pset.popt.topt.expanded)); 00258 fprintf(output, "\n"); 00259 00260 fprintf(output, _("Connection\n")); 00261 if (currdb) 00262 fprintf(output, _(" \\c[onnect] [DBNAME|- USER|- HOST|- PORT|-]\n" 00263 " connect to new database (currently \"%s\")\n"), 00264 currdb); 00265 else 00266 fprintf(output, _(" \\c[onnect] [DBNAME|- USER|- HOST|- PORT|-]\n" 00267 " connect to new database (currently no connection)\n")); 00268 fprintf(output, _(" \\encoding [ENCODING] show or set client encoding\n")); 00269 fprintf(output, _(" \\password [USERNAME] securely change the password for a user\n")); 00270 fprintf(output, _(" \\conninfo display information about current connection\n")); 00271 fprintf(output, "\n"); 00272 00273 fprintf(output, _("Operating System\n")); 00274 fprintf(output, _(" \\cd [DIR] change the current working directory\n")); 00275 fprintf(output, _(" \\setenv NAME [VALUE] set or unset environment variable\n")); 00276 fprintf(output, _(" \\timing [on|off] toggle timing of commands (currently %s)\n"), 00277 ON(pset.timing)); 00278 fprintf(output, _(" \\! [COMMAND] execute command in shell or start interactive shell\n")); 00279 fprintf(output, "\n"); 00280 00281 fprintf(output, _("Variables\n")); 00282 fprintf(output, _(" \\prompt [TEXT] NAME prompt user to set internal variable\n")); 00283 fprintf(output, _(" \\set [NAME [VALUE]] set internal variable, or list all if no parameters\n")); 00284 fprintf(output, _(" \\unset NAME unset (delete) internal variable\n")); 00285 fprintf(output, "\n"); 00286 00287 fprintf(output, _("Large Objects\n")); 00288 fprintf(output, _(" \\lo_export LOBOID FILE\n" 00289 " \\lo_import FILE [COMMENT]\n" 00290 " \\lo_list\n" 00291 " \\lo_unlink LOBOID large object operations\n")); 00292 00293 ClosePager(output); 00294 } 00295 00296 00297 00298 /* 00299 * helpSQL -- help with SQL commands 00300 * 00301 * Note: we assume caller removed any trailing spaces in "topic". 00302 */ 00303 void 00304 helpSQL(const char *topic, unsigned short int pager) 00305 { 00306 #define VALUE_OR_NULL(a) ((a) ? (a) : "") 00307 00308 if (!topic || strlen(topic) == 0) 00309 { 00310 /* Print all the available command names */ 00311 int screen_width; 00312 int ncolumns; 00313 int nrows; 00314 FILE *output; 00315 int i; 00316 int j; 00317 00318 #ifdef TIOCGWINSZ 00319 struct winsize screen_size; 00320 00321 if (ioctl(fileno(stdout), TIOCGWINSZ, &screen_size) == -1) 00322 screen_width = 80; /* ioctl failed, assume 80 */ 00323 else 00324 screen_width = screen_size.ws_col; 00325 #else 00326 screen_width = 80; /* default assumption */ 00327 #endif 00328 00329 ncolumns = (screen_width - 3) / (QL_MAX_CMD_LEN + 1); 00330 ncolumns = Max(ncolumns, 1); 00331 nrows = (QL_HELP_COUNT + (ncolumns - 1)) / ncolumns; 00332 00333 output = PageOutput(nrows + 1, pager); 00334 00335 fputs(_("Available help:\n"), output); 00336 00337 for (i = 0; i < nrows; i++) 00338 { 00339 fprintf(output, " "); 00340 for (j = 0; j < ncolumns - 1; j++) 00341 fprintf(output, "%-*s", 00342 QL_MAX_CMD_LEN + 1, 00343 VALUE_OR_NULL(QL_HELP[i + j * nrows].cmd)); 00344 if (i + j * nrows < QL_HELP_COUNT) 00345 fprintf(output, "%s", 00346 VALUE_OR_NULL(QL_HELP[i + j * nrows].cmd)); 00347 fputc('\n', output); 00348 } 00349 00350 ClosePager(output); 00351 } 00352 else 00353 { 00354 int i, 00355 j, 00356 x = 0; 00357 bool help_found = false; 00358 FILE *output = NULL; 00359 size_t len, 00360 wordlen; 00361 int nl_count = 0; 00362 00363 /* 00364 * We first try exact match, then first + second words, then first 00365 * word only. 00366 */ 00367 len = strlen(topic); 00368 00369 for (x = 1; x <= 3; x++) 00370 { 00371 if (x > 1) /* Nothing on first pass - try the opening 00372 * word(s) */ 00373 { 00374 wordlen = j = 1; 00375 while (topic[j] != ' ' && j++ < len) 00376 wordlen++; 00377 if (x == 2) 00378 { 00379 j++; 00380 while (topic[j] != ' ' && j++ <= len) 00381 wordlen++; 00382 } 00383 if (wordlen >= len) /* Don't try again if the same word */ 00384 { 00385 if (!output) 00386 output = PageOutput(nl_count, pager); 00387 break; 00388 } 00389 len = wordlen; 00390 } 00391 00392 /* Count newlines for pager */ 00393 for (i = 0; QL_HELP[i].cmd; i++) 00394 { 00395 if (pg_strncasecmp(topic, QL_HELP[i].cmd, len) == 0 || 00396 strcmp(topic, "*") == 0) 00397 { 00398 nl_count += 5 + QL_HELP[i].nl_count; 00399 00400 /* If we have an exact match, exit. Fixes \h SELECT */ 00401 if (pg_strcasecmp(topic, QL_HELP[i].cmd) == 0) 00402 break; 00403 } 00404 } 00405 00406 if (!output) 00407 output = PageOutput(nl_count, pager); 00408 00409 for (i = 0; QL_HELP[i].cmd; i++) 00410 { 00411 if (pg_strncasecmp(topic, QL_HELP[i].cmd, len) == 0 || 00412 strcmp(topic, "*") == 0) 00413 { 00414 PQExpBufferData buffer; 00415 00416 initPQExpBuffer(&buffer); 00417 QL_HELP[i].syntaxfunc(&buffer); 00418 help_found = true; 00419 fprintf(output, _("Command: %s\n" 00420 "Description: %s\n" 00421 "Syntax:\n%s\n\n"), 00422 QL_HELP[i].cmd, 00423 _(QL_HELP[i].help), 00424 buffer.data); 00425 /* If we have an exact match, exit. Fixes \h SELECT */ 00426 if (pg_strcasecmp(topic, QL_HELP[i].cmd) == 0) 00427 break; 00428 } 00429 } 00430 if (help_found) /* Don't keep trying if we got a match */ 00431 break; 00432 } 00433 00434 if (!help_found) 00435 fprintf(output, _("No help available for \"%s\".\nTry \\h with no arguments to see available help.\n"), topic); 00436 00437 ClosePager(output); 00438 } 00439 } 00440 00441 00442 00443 void 00444 print_copyright(void) 00445 { 00446 puts( 00447 "PostgreSQL Database Management System\n" 00448 "(formerly known as Postgres, then as Postgres95)\n\n" 00449 "Portions Copyright (c) 1996-2013, PostgreSQL Global Development Group\n\n" 00450 "Portions Copyright (c) 1994, The Regents of the University of California\n\n" 00451 "Permission to use, copy, modify, and distribute this software and its\n" 00452 "documentation for any purpose, without fee, and without a written agreement\n" 00453 "is hereby granted, provided that the above copyright notice and this\n" 00454 "paragraph and the following two paragraphs appear in all copies.\n\n" 00455 "IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR\n" 00456 "DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING\n" 00457 "LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS\n" 00458 "DOCUMENTATION, EVEN IF THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE\n" 00459 "POSSIBILITY OF SUCH DAMAGE.\n\n" 00460 "THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,\n" 00461 "INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY\n" 00462 "AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS\n" 00463 "ON AN \"AS IS\" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATIONS TO\n" 00464 "PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.\n" 00465 ); 00466 }
1.7.1