.\" XXX standard disclaimer belongs here....
.\" $Header: /private/postgres/ref/postquel/RCS/copy,v 1.13 1992/07/14 05:54:17 ptong Exp $
.SP COPY COMMANDS 6/14/90
.XA 2 Copy
.uh NAME
.lp
copy \*- copy data to or from a class from or to a \*(UU file.
.uh SYNOPSIS
.lp
.(l
\fBcopy\fR [\fBbinary\fR] classname direction ( "filename" | \fBstdin\fR | \fBstdout\fR )
.)l
.uh DESCRIPTION
.lp
.b Copy
moves data between \*(PP classes and standard \*(UU files.
The keyword
.b binary
change the behavior of field formatting,
as described below.
.i Classname
is the name of an existing class.
.i Direction
is either 
.b to
or 
.b from .
.i Filename
is the \*(UU pathname of the file.  In place of a filename, stdin and stdout
can be used so that input to
.b copy
can be written by a LIBPQ application and 
output from the
.b copy
command can be read by a LIBPQ application.
The 
.b binary
keyword will force all data to be stored/read as binary objects rather than
as ASCII text.  It is somewhat faster than the normal
.b copy
command, but is not generally portable, and the files generated are somewhat
larger, although this factor is highly dependent on the data itself.
.uh FORMAT OF OUTPUT FILES
.lp
When
.b copy
is used without the
.b binary
keyword, the file generated will have each instance on a line, with each
attribute separated by tabs (\t).  Embedded tabs will be preceeded 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 
.b copy
itself.
.lp
Note that on input to 
.b copy
backslashes are considered to be special control characters, and should be
doubled if you want to embed a backslash, ie, the string "12\\19\\88" will be
converted by
.b copy
to "12\19\88".  The actual format for each instance is
.lp
<attr1><tab><attr2><tab>...<tab><attrn><newline>
.lp
If 
.b copy
is sending its output to standard output instead of a file, it will send a
period (.) followed immediately by a newline, on a line by themselves, when
it is done.  Similarly, if
.b copy
is reading from standard input, it will expect a period (.) followed by a
newline, as the first two characters on a line, to denote end-of-file.
However,
.b copy
will terminate (followed by the backend itself) if a true EOF is encountered.
.lp
.b NULL
attributes are handled simply as null strings, that is, consecutive tabs in
the input file denote a 
.b NULL
attribute.
.lp
In the case of
.b copy
.b binary,
the first four bytes in the file will be the number of instances in the file.
If this number is
.i zero,
the
.b copy
.b binary
command will read until end of file is encountered.  Otherwise, it will
.i stop
reading when this number of instances has been read.  Remaining data in the
file will be ignored.
.lp
The format for each instance in the file is as follows.  Note that this format
must be followed
.i EXACTLY.
Unsigned four byte integer quantities are called uint32 in the below
description.
.lp
uint32 totallength (not including itself),
.lp
uint32 number of null attributes
.lp
[uint32 attribute number of first null attribute
.lp
...
.lp
uint32 attribute number of nth null attribute],
.lp
<data>
.lp
.i "Alignment of binary data"
.lp
On Sun 3's, 2 byte attributes are aligned on two-byte boundaries, and all
larger attributes are aligned on four-byte boundaries.  Character attributes
are aligned on single-byte boundaries.  On other machines, all attributes
larger than 1 byte are aligned on four-byte boundaries.  Note that variable
length attributes are preceeded by the attribute's length; arrays are simply
contiguous streams of the array element type.
.lp
.uh "SEE ALSO"
.lp
append(commands), create(commands), vacuum(commands), libpq.
.uh BUGS
.lp
.A Files 
used as arguments to the
.b copy
command must reside on or be accessable to the
the database server machine by being either on local disks or a networked
file system.
.lp
.b Copy
stops operation at the first error.
This should not lead to problems
in the event of a
.b copy
.b from,
but the target relation will, of course, be partially modified
in a
.b copy 
.b to.
The ``vacuum'' query should be used to clean up after a
failed copy.
.lp
Because \*(PP operates out of a different directory 
than the user's working directory at the time \*(PP is invoked,
the result of copying to a file 
.q "foo"
(without additional path information)
may yield unexpected results for the naive user.
The full pathname should be used when specifying files to be copied.
.lp
.b Copy
has virtually no error checking, and a malformed input file will likely cause
the backend to crash.  Humans should avoid using copy for input whenever
possible.
