<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/copy.sgml,v 1.27 2002/01/20 22:19:56 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/copy.sgml,v 1.28 2002/02/12 21:25:34 tgl Exp $
PostgreSQL documentation
-->
<term><replaceable class="parameter">filename</replaceable></term>
<listitem>
<para>
- The absolute Unix file name of the input or output file.
+ The absolute Unix path name of the input or output file.
</para>
</listitem>
</varlistentry>
By default, a text copy uses a tab ("\t") character as a delimiter
between fields. The field delimiter may be changed to any other single
character with the keyword phrase USING DELIMITERS. Characters
- in data fields which happen to match the delimiter character will
+ in data fields that happen to match the delimiter character will
be backslash quoted.
</para>
by the <application>PostgreSQL</application> user (the user ID the
server runs as), not the client.
<command>COPY</command> naming a file is only allowed to database
- superusers, since it allows writing on any file that the backend has
- privileges to write on.
+ superusers, since it allows reading or writing any file that the backend
+ has privileges to access.
<tip>
<para>
<title>File Formats</title>
<refsect2>
<refsect2info>
- <date>2001-01-02</date>
+ <date>2002-02-12</date>
</refsect2info>
<title>Text Format</title>
<para>
- When <command>COPY TO</command> is used without the BINARY option,
- the file generated will have each row (instance) on a single line, with each
- column (attribute) separated by the delimiter character. Embedded
- delimiter characters will be preceded by a backslash character
- ("\"). The attribute values themselves are strings generated by the
- output function associated with each attribute type. The output
- function for a type should not try to generate the backslash
- character; this will be handled by <command>COPY</command> itself.
+ When <command>COPY</command> is used without the BINARY option,
+ the file read or written is a text file with one line per table row.
+ Columns (attributes) in a row are separated by the delimiter character.
+ The attribute values themselves are strings generated by the
+ output function, or acceptable to the input function, of each
+ attribute's data type. The specified null-value string is used in
+ place of attributes that are NULL.
</para>
<para>
- The actual format for each instance is
- <programlisting>
-<attr1><<replaceable class=parameter>separator</replaceable>><attr2><<replaceable class=parameter>separator</replaceable>>...<<replaceable class=parameter>separator</replaceable>><attr<replaceable class="parameter">n</replaceable>><newline>
- </programlisting>
- Note that the end of each row is marked by a Unix-style newline
- ("\n"). <command>COPY FROM</command> will not behave as desired
- if given a file containing DOS- or Mac-style newlines.
+ If WITH OIDS is specified, the OID is read or written as the first column,
+ preceding the user data columns. (An error is raised if WITH OIDS is
+ specified for a table that does not have OIDs.)
</para>
<para>
- The OID is emitted as the first column if WITH OIDS is specified.
- (An error is raised if WITH OIDS is specified for a table that does not
- have OIDs.)
+ End of data can be represented by a single line containing just
+ backslash-period (<literal>\.</>). An end-of-data marker is
+ not necessary when reading from a Unix file, since the end of file
+ serves perfectly well; but an end marker must be provided when copying
+ data to or from a client application.
</para>
<para>
- If <command>COPY TO</command> is sending its output to standard
- output instead of a file, after the last row it will send a backslash ("\")
- and a period (".") followed by a newline.
- Similarly, if <command>COPY FROM</command> is reading
- from standard input, it will expect a backslash ("\") and a period
- (".") followed by a newline, as the first three characters on a
- line to denote end-of-file. However, <command>COPY FROM</command>
- will terminate correctly (followed by the backend itself) if the
- input connection is closed before this special end-of-file pattern is
- found.
+ Backslash characters (<literal>\</>) may be used in the
+ <command>COPY</command> data to quote data characters that might otherwise
+ be taken as row or column delimiters. In particular, the following
+ characters <emphasis>must</> be preceded by a backslash if they appear
+ as part of an attribute value: backslash itself, newline, and the current
+ delimiter character.
</para>
<para>
- The backslash character has other special meanings. A literal backslash
- character is represented as two
- consecutive backslashes ("\\"). A literal tab character is represented
- as a backslash and a tab. (If you are using something other than tab
- as the column delimiter, backslash that delimiter character to include
- it in data.) A literal newline character is
- represented as a backslash and a newline. When loading text data
- not generated by <application>PostgreSQL</application>,
- you will need to convert backslash
- characters ("\") to double-backslashes ("\\") to ensure that they
- are loaded properly.
+ The following special backslash sequences are recognized by
+ <command>COPY FROM</command>:
+
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Sequence</entry>
+ <entry>Represents</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><literal>\b</></entry>
+ <entry>Backspace (ASCII 8)</entry>
+ </row>
+ <row>
+ <entry><literal>\f</></entry>
+ <entry>Form feed (ASCII 12)</entry>
+ </row>
+ <row>
+ <entry><literal>\n</></entry>
+ <entry>Newline (ASCII 10)</entry>
+ </row>
+ <row>
+ <entry><literal>\r</></entry>
+ <entry>Carriage return (ASCII 13)</entry>
+ </row>
+ <row>
+ <entry><literal>\t</></entry>
+ <entry>Tab (ASCII 9)</entry>
+ </row>
+ <row>
+ <entry><literal>\v</></entry>
+ <entry>Vertical tab (ASCII 11)</entry>
+ </row>
+ <row>
+ <entry><literal>\</><replaceable>digits</></entry>
+ <entry>Backslash followed by one to three octal digits specifies
+ the character with that numeric code</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ Presently, <command>COPY TO</command> will never emit an octal-digits
+ backslash sequence, but it does use the other sequences listed above
+ for those control characters.
+ </para>
+ <para>
+ Never put a backslash before a data character <literal>N</> or period
+ (<literal>.</>). Such pairs will be mistaken for the default null string
+ or the end-of-data marker, respectively. Any other backslashed character
+ that is not mentioned in the above table will be taken to represent itself.
+ </para>
+ <para>
+ It is strongly recommended that applications generating COPY data convert
+ data newlines and carriage returns to the <literal>\n</> and
+ <literal>\r</> sequences respectively. At present
+ (<productname>PostgreSQL</productname> 7.2 and older versions) it is
+ possible to represent a data carriage return without any special quoting,
+ and to represent a data newline by a backslash and newline. However,
+ these representations will not be accepted by default in future releases.
+ </para>
+ <para>
+ Note that the end of each row is marked by a Unix-style newline
+ ("\n"). Presently, <command>COPY FROM</command> will not behave as
+ desired if given a file containing DOS- or Mac-style newlines.
+ This is expected to change in future releases.
</para>
</refsect2>
*
*
* IDENTIFICATION
- * $Header: /cvsroot/pgsql/src/backend/commands/copy.c,v 1.144 2001/12/04 21:19:57 tgl Exp $
+ * $Header: /cvsroot/pgsql/src/backend/commands/copy.c,v 1.145 2002/02/12 21:25:41 tgl Exp $
*
*-------------------------------------------------------------------------
*/
#endif
#define ISOCTAL(c) (((c) >= '0') && ((c) <= '7'))
-#define VALUE(c) ((c) - '0')
+#define OCTVALUE(c) ((c) - '0')
/* non-export function prototypes */
* Internal communications functions
*/
static void CopySendData(void *databuf, int datasize, FILE *fp);
-static void CopySendString(char *str, FILE *fp);
+static void CopySendString(const char *str, FILE *fp);
static void CopySendChar(char c, FILE *fp);
static void CopyGetData(void *databuf, int datasize, FILE *fp);
static int CopyGetChar(FILE *fp);
static int CopyGetEof(FILE *fp);
static int CopyPeekChar(FILE *fp);
-static void CopyDonePeek(FILE *fp, int c, int pickup);
+static void CopyDonePeek(FILE *fp, int c, bool pickup);
/*
* CopySendData sends output data either to the file
}
static void
-CopySendString(char *str, FILE *fp)
+CopySendString(const char *str, FILE *fp)
{
- CopySendData(str, strlen(str), fp);
+ CopySendData((void *) str, strlen(str), fp);
}
static void
/*
* CopyPeekChar reads a byte in "peekable" mode.
+ *
* after each call to CopyPeekChar, a call to CopyDonePeek _must_
* follow, unless EOF was returned.
- * CopyDonePeek will either take the peeked char off the steam
- * (if pickup is != 0) or leave it on the stream (if pickup == 0)
+ *
+ * CopyDonePeek will either take the peeked char off the stream
+ * (if pickup is true) or leave it on the stream (if pickup is false).
*/
static int
CopyPeekChar(FILE *fp)
}
static void
-CopyDonePeek(FILE *fp, int c, int pickup)
+CopyDonePeek(FILE *fp, int c, bool pickup)
{
if (!fp)
{
if (pickup)
{
- /*
- * We want to pick it up
- */
+ /* We want to pick it up */
(void) pq_getbyte();
}
/* If we didn't want to pick it up, just leave it where it sits */
/* We don't want to pick it up - so put it back in there */
ungetc(c, fp);
}
- /* If we wanted to pick it up, it's already there */
+ /* If we wanted to pick it up, it's already done */
}
}
{
int val;
- val = VALUE(c);
+ val = OCTVALUE(c);
c = CopyPeekChar(fp);
if (ISOCTAL(c))
{
- val = (val << 3) + VALUE(c);
- CopyDonePeek(fp, c, 1); /* Pick up the
- * character! */
+ val = (val << 3) + OCTVALUE(c);
+ CopyDonePeek(fp, c, true /*pick up*/);
c = CopyPeekChar(fp);
if (ISOCTAL(c))
{
- CopyDonePeek(fp, c, 1); /* pick up! */
- val = (val << 3) + VALUE(c);
+ val = (val << 3) + OCTVALUE(c);
+ CopyDonePeek(fp, c, true /*pick up*/);
}
else
{
if (c == EOF)
goto endOfFile;
- CopyDonePeek(fp, c, 0); /* Return to stream! */
+ CopyDonePeek(fp, c, false /*put back*/);
}
}
else
{
if (c == EOF)
goto endOfFile;
- CopyDonePeek(fp, c, 0); /* Return to stream! */
+ CopyDonePeek(fp, c, false /*put back*/);
}
c = val & 0377;
}
}
appendStringInfoCharMacro(&attribute_buf, c);
#ifdef MULTIBYTE
+ /* XXX shouldn't this be done even when encoding is the same? */
if (client_encoding != server_encoding)
{
/* get additional bytes of the char, if any */
{
char *string;
char c;
+ char delimc = delim[0];
#ifdef MULTIBYTE
+ bool same_encoding;
char *string_start;
int mblen;
int i;
#endif
#ifdef MULTIBYTE
- if (client_encoding != server_encoding)
+ same_encoding = (server_encoding == client_encoding);
+ if (!same_encoding)
{
string = (char *) pg_server_to_client((unsigned char *) server_string,
strlen(server_string));
else
{
string = server_string;
- string_start = NULL; /* unused, but keep compiler quiet */
+ string_start = NULL;
}
#else
string = server_string;
#endif
#ifdef MULTIBYTE
- for (; (mblen = (server_encoding == client_encoding ? 1 : pg_encoding_mblen(client_encoding, string))) &&
- ((c = *string) != '\0'); string += mblen)
+ for (; (c = *string) != '\0'; string += mblen)
#else
for (; (c = *string) != '\0'; string++)
#endif
{
- if (c == delim[0] || c == '\n' || c == '\\')
- CopySendChar('\\', fp);
#ifdef MULTIBYTE
- for (i = 0; i < mblen; i++)
- CopySendChar(*(string + i), fp);
-#else
- CopySendChar(c, fp);
+ mblen = 1;
#endif
+ switch (c)
+ {
+ case '\b':
+ CopySendString("\\b", fp);
+ break;
+ case '\f':
+ CopySendString("\\f", fp);
+ break;
+ case '\n':
+ CopySendString("\\n", fp);
+ break;
+ case '\r':
+ CopySendString("\\r", fp);
+ break;
+ case '\t':
+ CopySendString("\\t", fp);
+ break;
+ case '\v':
+ CopySendString("\\v", fp);
+ break;
+ case '\\':
+ CopySendString("\\\\", fp);
+ break;
+ default:
+ if (c == delimc)
+ CopySendChar('\\', fp);
+ CopySendChar(c, fp);
+#ifdef MULTIBYTE
+ /* XXX shouldn't this be done even when encoding is same? */
+ if (!same_encoding)
+ {
+ /* send additional bytes of the char, if any */
+ mblen = pg_encoding_mblen(client_encoding, string);
+ for (i = 1; i < mblen; i++)
+ CopySendChar(string[i], fp);
+ }
+#endif
+ break;
+ }
}
#ifdef MULTIBYTE
- if (client_encoding != server_encoding)
+ if (string_start)
pfree(string_start); /* pfree pg_server_to_client result */
#endif
}
projects / postgresql / commitdiff