From fede784fa2ca73f8efaca013a4e488736986bf13 Mon Sep 17 00:00:00 2001
From: Daniel Stenberg <daniel@haxx.se>
Date: Wed, 19 Apr 2006 09:08:15 +0000
Subject: [PATCH] the new conversion stuff documented (mostly by David
 McCreedy)

---
 docs/libcurl/curl_easy_setopt.3  | 47 +++++++++++++++++++++++++++++++-
 docs/libcurl/curl_version_info.3 | 28 +++++++++++++++++--
 2 files changed, 72 insertions(+), 3 deletions(-)

diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3
index 18718efb0..69fa8b3cf 100644
--- a/docs/libcurl/curl_easy_setopt.3
+++ b/docs/libcurl/curl_easy_setopt.3
@@ -21,7 +21,7 @@
 .\" * $Id$
 .\" **************************************************************************
 .\"
-.TH curl_easy_setopt 3 "21 Feb 2006" "libcurl 7.15.2" "libcurl Manual"
+.TH curl_easy_setopt 3 "19 Apr 2006" "libcurl 7.15.4" "libcurl Manual"
 .SH NAME
 curl_easy_setopt \- set options for a curl easy handle
 .SH SYNOPSIS
@@ -263,6 +263,51 @@ and trust file settings.
 Data pointer to pass to the ssl context callback set by the option
 \fICURLOPT_SSL_CTX_FUNCTION\fP, this is the pointer you'll get as third
 parameter, otherwise \fBNULL\fP. (Added in 7.11.0)
+.IP CURLOPT_CONV_TO_NETWORK_FUNCTION
+.IP CURLOPT_CONV_FROM_NETWORK_FUNCTION
+.IP CURLOPT_CONV_FROM_UTF8_FUNCTION
+Function pointers that should match the following prototype: CURLcode
+function(char *ptr, size_t length);
+
+These three options apply to non-ASCII platforms only.  They are available
+only if \fBCURL_DOES_CONVERSIONS\fP was defined when libcurl was built. When
+this is the case, \fIcurl_version_info(3)\fP will return the CURL_VERSION_CONV
+feature bit set.
+
+The data to be converted is in a buffer pointed to by the ptr parameter.  The
+amount of data to convert is indicated by the length parameter.  The converted
+data overlays the input data in the buffer pointed to by the ptr parameter.
+CURLE_OK should be returned upon successful conversion.  A CURLcode return
+value defined by curl.h, such as CURLE_CONV_FAILED, should be returned if an
+error was encountered.
+
+\fBCURLOPT_CONV_TO_NETWORK_FUNCTION\fP and
+\fBCURLOPT_CONV_FROM_NETWORK_FUNCTION\fP convert between the host encoding and
+the network encoding.  They are used when commands or ASCII data are
+sent/received over the network.
+
+\fBCURLOPT_CONV_FROM_UTF8_FUNCTION\fP is called to convert from UTF8 into the
+host encoding.  It is required only for SSL processing.
+
+If you set a callback pointer to NULL, or don't set it at all, the built-in
+libcurl iconv functions will be used.  If HAVE_ICONV was not defined when
+libcurl was built, and no callback has been established, conversion will
+return the CURLE_CONV_REQD error code.
+
+If HAVE_ICONV is defined, CURL_ICONV_CODESET_OF_HOST must also be defined.
+For example:
+
+ \&#define CURL_ICONV_CODESET_OF_HOST "IBM-1047"
+
+The iconv code in libcurl will default the network and UTF8 codeset names as
+follows:
+
+ \&#define CURL_ICONV_CODESET_OF_NETWORK "ISO8859-1"
+
+ \&#define CURL_ICONV_CODESET_FOR_UTF8   "UTF-8"
+
+You will need to override these definitions if they are different on your
+system.
 .SH ERROR OPTIONS
 .IP CURLOPT_ERRORBUFFER
 Pass a char * to a buffer that the libcurl may store human readable error
diff --git a/docs/libcurl/curl_version_info.3 b/docs/libcurl/curl_version_info.3
index 80653fb3c..a9fd55d59 100644
--- a/docs/libcurl/curl_version_info.3
+++ b/docs/libcurl/curl_version_info.3
@@ -1,6 +1,27 @@
-.\" $Id$
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2006, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" *
+.\" * This software is licensed as described in the file COPYING, which
+.\" * you should have received as part of this distribution. The terms
+.\" * are also available at http://curl.haxx.se/docs/copyright.html.
+.\" *
+.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+.\" * copies of the Software, and permit persons to whom the Software is
+.\" * furnished to do so, under the terms of the COPYING file.
+.\" *
+.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+.\" * KIND, either express or implied.
+.\" *
+.\" * $Id$
+.\" **************************************************************************
 .\"
-.TH curl_version_info 3 "11 Mar 2005" "libcurl 7.13.2" "libcurl Manual"
+.TH curl_version_info 3 "19 Apr 2006" "libcurl 7.15.4" "libcurl Manual"
 .SH NAME
 curl_version_info - returns run-time libcurl version info
 .SH SYNOPSIS
@@ -98,6 +119,9 @@ libcurl was built with support for SSPI. This is only available on Windows and
 makes libcurl use Windows-provided functions for NTLM authentication. It also
 allows libcurl to use the current user and the current user's password without
 the app having to pass them on. (Added in 7.13.2)
+.IP CURL_VERSION_CONV
+libcurl was built with support for character conversions, as provided by the
+CUURLOPT_CONV_* callbacks. (Added in 7.15.4)
 .RE
 \fIssl_version\fP is an ascii string for the OpenSSL version used. If libcurl
 has no SSL support, this is NULL.