Adding upstream version 15.5.upstream/15.5

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 145 insertions, 0 deletions

diff --git a/doc/src/sgml/man7/CREATE_CONVERSION.7 b/doc/src/sgml/man7/CREATE_CONVERSION.7
new file mode 100644
index 0000000..834af46
--- /dev/null
+++ b/doc/src/sgml/man7/CREATE_CONVERSION.7
@@ -0,0 +1,145 @@
+'\" t
+.\"     Title: CREATE CONVERSION
+.\"    Author: The PostgreSQL Global Development Group
+.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
+.\"      Date: 2023
+.\"    Manual: PostgreSQL 15.5 Documentation
+.\"    Source: PostgreSQL 15.5
+.\"  Language: English
+.\"
+.TH "CREATE CONVERSION" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+CREATE_CONVERSION \- define a new encoding conversion
+.SH "SYNOPSIS"
+.sp
+.nf
+CREATE [ DEFAULT ] CONVERSION \fIname\fR
+    FOR \fIsource_encoding\fR TO \fIdest_encoding\fR FROM \fIfunction_name\fR
+.fi
+.SH "DESCRIPTION"
+.PP
+\fBCREATE CONVERSION\fR
+defines a new conversion between two character set encodings\&.
+.PP
+Conversions that are marked
+DEFAULT
+can be used for automatic encoding conversion between client and server\&. To support that usage, two conversions, from encoding A to B
+\fIand\fR
+from encoding B to A, must be defined\&.
+.PP
+To be able to create a conversion, you must have
+EXECUTE
+privilege on the function and
+CREATE
+privilege on the destination schema\&.
+.SH "PARAMETERS"
+.PP
+DEFAULT
+.RS 4
+The
+DEFAULT
+clause indicates that this conversion is the default for this particular source to destination encoding\&. There should be only one default encoding in a schema for the encoding pair\&.
+.RE
+.PP
+\fIname\fR
+.RS 4
+The name of the conversion\&. The conversion name can be schema\-qualified\&. If it is not, the conversion is defined in the current schema\&. The conversion name must be unique within a schema\&.
+.RE
+.PP
+\fIsource_encoding\fR
+.RS 4
+The source encoding name\&.
+.RE
+.PP
+\fIdest_encoding\fR
+.RS 4
+The destination encoding name\&.
+.RE
+.PP
+\fIfunction_name\fR
+.RS 4
+The function used to perform the conversion\&. The function name can be schema\-qualified\&. If it is not, the function will be looked up in the path\&.
+.sp
+The function must have the following signature:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+conv_proc(
+    integer,  \-\- source encoding ID
+    integer,  \-\- destination encoding ID
+    cstring,  \-\- source string (null terminated C string)
+    internal, \-\- destination (fill with a null terminated C string)
+    integer,  \-\- source string length
+    boolean   \-\- if true, don\*(Aqt throw an error if conversion fails
+) RETURNS integer;
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+The return value is the number of source bytes that were successfully converted\&. If the last argument is false, the function must throw an error on invalid input, and the return value is always equal to the source string length\&.
+.RE
+.SH "NOTES"
+.PP
+Neither the source nor the destination encoding can be
+SQL_ASCII, as the server\*(Aqs behavior for cases involving the
+SQL_ASCII
+\(lqencoding\(rq
+is hard\-wired\&.
+.PP
+Use
+\fBDROP CONVERSION\fR
+to remove user\-defined conversions\&.
+.PP
+The privileges required to create a conversion might be changed in a future release\&.
+.SH "EXAMPLES"
+.PP
+To create a conversion from encoding
+UTF8
+to
+LATIN1
+using
+\fBmyfunc\fR:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+CREATE CONVERSION myconv FOR \*(AqUTF8\*(Aq TO \*(AqLATIN1\*(Aq FROM myfunc;
+.fi
+.if n \{\
+.RE
+.\}
+.SH "COMPATIBILITY"
+.PP
+\fBCREATE CONVERSION\fR
+is a
+PostgreSQL
+extension\&. There is no
+\fBCREATE CONVERSION\fR
+statement in the SQL standard, but a
+\fBCREATE TRANSLATION\fR
+statement that is very similar in purpose and syntax\&.
+.SH "SEE ALSO"
+ALTER CONVERSION (\fBALTER_CONVERSION\fR(7)), CREATE FUNCTION (\fBCREATE_FUNCTION\fR(7)), DROP CONVERSION (\fBDROP_CONVERSION\fR(7))