From 8cf3fada2f87f2cbd0102389bf59434b45e911fe Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Fri, 8 Feb 2019 12:49:36 -0500 Subject: [PATCH] Doc: fix thinko in description of how to escape a backslash in bytea. Also clean up some discussion that had been left in a very confused state thanks to half-hearted adjustments for the change to standard_conforming_strings being the default. Discussion: https://postgr.es/m/154954987367.1297.4358910045409218@wrigleys.postgresql.org --- doc/src/sgml/datatype.sgml | 58 +++++++++++++++++--------------------- 1 file changed, 26 insertions(+), 32 deletions(-) diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml index 96b9ff9779..f519500d66 100644 --- a/doc/src/sgml/datatype.sgml +++ b/doc/src/sgml/datatype.sgml @@ -1335,9 +1335,9 @@ SELECT b, char_length(b) FROM test2; per byte, most significant nibble first. The entire string is preceded by the sequence \x (to distinguish it from the escape format). In some contexts, the initial backslash may - need to be escaped by doubling it, in the same cases in which backslashes - have to be doubled in escape format; details appear below. - The hexadecimal digits can + need to be escaped by doubling it + (see ). + For input, the hexadecimal digits can be either upper or lower case, and whitespace is permitted between digit pairs (but not within a digit pair nor in the starting \x sequence). @@ -1379,9 +1379,7 @@ SELECT '\xDEADBEEF'; values must be escaped, while all octet values can be escaped. In general, to escape an octet, convert it into its three-digit - octal value and precede it - by a backslash (or two backslashes, if writing the value as a - literal using escape string syntax). + octal value and precede it by a backslash. Backslash itself (octet decimal value 92) can alternatively be represented by double backslashes. @@ -1398,7 +1396,7 @@ SELECT '\xDEADBEEF'; Description Escaped Input Representation Example - Output Representation + Hex Representation @@ -1422,7 +1420,7 @@ SELECT '\xDEADBEEF'; 92 backslash - '\' or '\\134' + '\\' or '\134' SELECT '\\'::bytea; \x5c @@ -1442,39 +1440,35 @@ SELECT '\xDEADBEEF'; The requirement to escape non-printable octets varies depending on locale settings. In some instances you can get away - with leaving them unescaped. Note that the result in each of the examples - in was exactly one octet in - length, even though the output representation is sometimes - more than one character. + with leaving them unescaped. - The reason multiple backslashes are required, as shown - in , is that an input - string written as a string literal must pass through two parse - phases in the PostgreSQL server. - The first backslash of each pair is interpreted as an escape - character by the string-literal parser (assuming escape string - syntax is used) and is therefore consumed, leaving the second backslash of the - pair. (Dollar-quoted strings can be used to avoid this level - of escaping.) The remaining backslash is then recognized by the - bytea input function as starting either a three - digit octal value or escaping another backslash. For example, - a string literal passed to the server as '\001' - becomes \001 after passing through the - escape string parser. The \001 is then sent - to the bytea input function, where it is converted - to a single octet with a decimal value of 1. Note that the - single-quote character is not treated specially by bytea, - so it follows the normal rules for string literals. (See also - .) + The reason that single quotes must be doubled, as shown + in , is that this + is true for any string literal in a SQL command. The generic + string-literal parser consumes the outermost single quotes + and reduces any pair of single quotes to one data character. + What the bytea input function sees is just one + single quote, which it treats as a plain data character. + However, the bytea input function treats + backslashes as special, and the other behaviors shown in + are implemented by + that function. + + + + In some contexts, backslashes must be doubled compared to what is + shown above, because the generic string-literal parser will also + reduce pairs of backslashes to one data character; + see . Bytea octets are output in hex format by default. If you change to escape, - non-printable octet are converted to + non-printable octets are converted to their equivalent three-digit octal value and preceded by one backslash. Most printable octets are output by their standard representation in the client character set, e.g.: