Support Docs & Contrib

doc/man/copy.l

@@ -0,0 +1,162 @@
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/doc/man/Attic/copy.l,v 1.1.1.1 1996/08/18 22:14:21 scrappy Exp $
+.TH COPY SQL 11/05/95 Postgres95 Postgres95
+.SH NAME
+copy \(em copy data to or from a class from or to a Unix file.
+.SH SYNOPSIS
+.nf
+\fBcopy\fP [\fBbinary\fP] [\fBnonulls\fP] classname 
+	\fBto\fP|\fBfrom\fP "filename"|\fBstdin\fR|\fBstdout\fR
+	[\fBUSING DELIMITERS\fP delim]
+.fi
+.SH DESCRIPTION
+.BR Copy
+moves data between Postgres classes and standard Unix files.  The
+keyword
+.BR binary
+changes the behavior of field formatting, as described below.
+.IR Classname
+is the name of an existing class.
+.IR Filename
+is the Unix pathname of the file.  In place of a filename, the
+keywords
+.BR "stdin" " and " "stdout"
+can be used so that input to
+.BR copy
+can be written by a Libpq application and output from the
+.BR copy
+command can be read by a Libpq application.  The
+.BR 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
+.BR copy
+command, but is not generally portable, and the files generated are
+somewhat larger, although this factor is highly dependent on the data
+itself.
+.PP
+By default,
+.BR copy
+uses a tab (\\t) character as a delimiter.  The delimiter may also be changed
+to any other single-character with the use of 
+.BR "USING DELIMITERS" .
+Characters in data fields which happen to match the delimiter character
+will be quoted.
+.PP
+You must have read access on any class whose values are read by the 
+.BR copy
+command, and either write or append access to a class to which values
+are being appended by the
+.BR copy
+command.
+.SH FORMAT OF OUTPUT FILES
+.SS "ASCII COPY FORMAT"
+When
+.BR copy
+is used without the
+.BR binary
+keyword, the file generated will have each instance on a line, with
+each attribute separated by the delimiter character.  Embedded delimiter
+characters 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 
+.BR copy
+itself.
+.PP
+The actual format for each instance is
+.nf
+<attr1><tab><attr2><tab>...<tab><attrn><newline>
+.fi
+.PP
+If 
+.BR copy
+is sending its output to standard output instead of a file, it will
+send a backslash(\\) and a period (.) followed immediately by a newline,
+on a line by themselves, when it is done.  Similarly, if
+.BR copy
+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,
+.BR copy
+will terminate (followed by the backend itself) if a true EOF is
+encountered.
+.PP
+The backslash character has special meaning.
+.BR NULL
+attributes are output as \\N.
+A literal backslash character is output as two consecutive backslashes.
+A literal tab character is represented as a backslash and a tab.
+A literal newline character is represented as a backslash and a newline.
+When loading ASCII data not generated by Postgres95, you will need to
+convert backslash characters (\\) to double-backslashes (\\\\) so
+they are loaded properly.
+.SS "BINARY COPY FORMAT"
+In the case of
+.BR "copy binary" ,
+the first four bytes in the file will be the number of instances in
+the file.  If this number is
+.IR zero,
+the
+.BR "copy binary"
+command will read until end of file is encountered.  Otherwise, it
+will stop reading when this number of instances has been read.
+Remaining data in the file will be ignored.
+.PP
+The format for each instance in the file is as follows.  Note that
+this format must be followed
+.BR EXACTLY .
+Unsigned four-byte integer quantities are called uint32 in the below
+description.
+.nf
+uint32 totallength (not including itself),
+uint32 number of null attributes
+[uint32 attribute number of first null attribute
+ ...
+ uint32 attribute number of nth null attribute],
+<data>
+.fi
+.bp
+.SS "ALIGNMENT OF BINARY DATA"
+On Sun-3s, 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 preceded by the attribute's
+length; arrays are simply contiguous streams of the array element
+type.
+.SH "SEE ALSO"
+insert(l), create table(l), vacuum(l), libpq.
+.SH BUGS
+Files used as arguments to the
+.BR copy
+command must reside on or be accessible to the the database server
+machine by being either on local disks or a networked file system.
+.PP
+.BR Copy
+stops operation at the first error.  This should not lead to problems
+in the event of a
+.BR "copy from" ,
+but the target relation will, of course, be partially modified in a
+.BR "copy to" .
+The 
+.IR vacuum (l)
+query should be used to clean up after a failed
+.BR "copy" .
+.PP
+Because Postgres operates out of a different directory than the user's
+working directory at the time Postgres is invoked, the result of copying
+to a file \*(lqfoo\*(rq (without additional path information) may
+yield unexpected results for the naive user.  In this case,
+\*(lqfoo\*(rq will wind up in
+.SM $PGDATA\c
+/foo.  In general, the full pathname should be used when specifying
+files to be copied.
+.PP
+.BR Copy
+has virtually no error checking, and a malformed input file will
+likely cause the backend to crash.  You should avoid using 
+.BR copy
+for input whenever possible.