Code + docs review for escaping of option values (commit 11a020e).

tglsfdc · tglsfdc · commit cbc8d6563934 · 2015-06-29T12:42:52.000-04:00
Avoid memory leak from incorrect choice of how to free a StringInfo
(resetStringInfo doesn't do it).  Now that pg_split_opts doesn't scribble
on the optstr, mark that as "const" for clarity.  Attach the commentary in
protocol.sgml to the right place, and add documentation about the
user-visible effects of this change on postgres' -o option and libpq's
PGOPTIONS option.
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
@@ -1016,10 +1016,13 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
       <term><literal>options</literal></term>
       <listitem>
        <para>
-        Adds command-line options to send to the server at run-time.
-        For example, setting this to <literal>-c geqo=off</> sets the
+        Specifies command-line options to send to the server at connection
+        start.  For example, setting this to <literal>-c geqo=off</> sets the
         session's value of the <varname>geqo</> parameter to
-        <literal>off</>.  For a detailed discussion of the available
+        <literal>off</>.  Spaces within this string are considered to
+        separate command-line arguments, unless escaped with a backslash
+        (<literal>\</>); write <literal>\\</> to represent a literal
+        backslash.  For a detailed discussion of the available
         options, consult <xref linkend="runtime-config">.
        </para>
       </listitem>
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
@@ -4739,7 +4739,10 @@ StartupMessage (F)
 <para>
                         Command-line arguments for the backend.  (This is
                         deprecated in favor of setting individual run-time
-                        parameters.)
+                        parameters.)  Spaces within this string are
+                        considered to separate arguments, unless escaped with
+                        a backslash (<literal>\</>); write <literal>\\</> to
+                        represent a literal backslash.
 </para>
 </listitem>
 </varlistentry>
@@ -4748,11 +4751,8 @@ StartupMessage (F)
                 In addition to the above, any run-time parameter that can be
                 set at backend start time might be listed.  Such settings
                 will be applied during backend start (after parsing the
-                command-line options if any).  The values will act as
-                session defaults.  Spaces in option values need to be escaped
-                with a backslash (<literal>\</>). A literal backslash can be
-                passed by escaping it with another backslash
-                (i.e <literal>\\</>).
+                command-line arguments if any).  The values will act as
+                session defaults.
 </para>
 </listitem>
 </varlistentry>
diff --git a/doc/src/sgml/ref/postgres-ref.sgml b/doc/src/sgml/ref/postgres-ref.sgml
@@ -284,12 +284,18 @@ PostgreSQL documentation
       <term><option>-o <replaceable class="parameter">extra-options</replaceable></option></term>
       <listitem>
        <para>
-        The command-line-style options specified in <replaceable
+        The command-line-style arguments specified in <replaceable
         class="parameter">extra-options</replaceable> are passed to
         all server processes started by this
-        <command>postgres</command> process.  If the option string contains
-        any spaces, the entire string must be quoted;  multiple
-        option invocations are appended.
+        <command>postgres</command> process.
+       </para>
+
+       <para>
+        Spaces within <replaceable class="parameter">extra-options</> are
+        considered to separate arguments, unless escaped with a backslash
+        (<literal>\</>); write <literal>\\</> to represent a literal
+        backslash.  Multiple arguments can also be specified via multiple
+        uses of <option>-o</>.
        </para>
 
        <para>
diff --git a/src/backend/utils/init/postinit.c b/src/backend/utils/init/postinit.c
@@ -418,7 +418,7 @@ InitCommunication(void)
  * backslashes, with \\ representing a literal backslash.
  */
 void
-pg_split_opts(char **argv, int *argcp, char *optstr)
+pg_split_opts(char **argv, int *argcp, const char *optstr)
 {
 	StringInfoData s;
 
@@ -438,8 +438,8 @@ pg_split_opts(char **argv, int *argcp, char *optstr)
 			break;
 
 		/*
-		 * Parse a single option + value, stopping at the first space, unless
-		 * it's escaped.
+		 * Parse a single option, stopping at the first space, unless it's
+		 * escaped.
 		 */
 		while (*optstr)
 		{
@@ -457,10 +457,11 @@ pg_split_opts(char **argv, int *argcp, char *optstr)
 			optstr++;
 		}
 
-		/* now store the option */
+		/* now store the option in the next argv[] position */
 		argv[(*argcp)++] = pstrdup(s.data);
 	}
-	resetStringInfo(&s);
+
+	pfree(s.data);
 }
 
 /*
diff --git a/src/include/miscadmin.h b/src/include/miscadmin.h
@@ -408,7 +408,7 @@ extern AuxProcType MyAuxProcType;
  *****************************************************************************/
 
 /* in utils/init/postinit.c */
-extern void pg_split_opts(char **argv, int *argcp, char *optstr);
+extern void pg_split_opts(char **argv, int *argcp, const char *optstr);
 extern void InitializeMaxBackends(void);
 extern void InitPostgres(const char *in_dbname, Oid dboid, const char *username,
 			 Oid useroid, char *out_dbname);

Original file line number	Diff line number	Diff line change
`@@ -418,7 +418,7 @@ InitCommunication(void)`
`418`	`418`	`* backslashes, with \\ representing a literal backslash.`
`419`	`419`	`*/`
`420`	`420`	`void`
`421`		`-pg_split_opts(char *argv, int argcp, char *optstr)`
	`421`	`+pg_split_opts(char *argv, int argcp, const char *optstr)`
`422`	`422`	`{`
`423`	`423`	`StringInfoData s;`
`424`	`424`
`@@ -438,8 +438,8 @@ pg_split_opts(char *argv, int argcp, char *optstr)`
`438`	`438`	`break;`
`439`	`439`
`440`	`440`	`/*`
`441`		`- * Parse a single option + value, stopping at the first space, unless`
`442`		`- * it's escaped.`
	`441`	`+ * Parse a single option, stopping at the first space, unless it's`
	`442`	`+ * escaped.`
`443`	`443`	`*/`
`444`	`444`	`while (*optstr)`
`445`	`445`	`{`
`@@ -457,10 +457,11 @@ pg_split_opts(char *argv, int argcp, char *optstr)`
`457`	`457`	`optstr++;`
`458`	`458`	`}`
`459`	`459`
`460`		`- /* now store the option */`
	`460`	`+ /* now store the option in the next argv[] position */`
`461`	`461`	`argv[(*argcp)++] = pstrdup(s.data);`
`462`	`462`	`}`
`463`		`- resetStringInfo(&s);`
	`463`	`+`
	`464`	`+ pfree(s.data);`
`464`	`465`	`}`
`465`	`466`
`466`	`467`	`/*`