.\" **************************************************************************
.\" *                                  _   _ ____  _
.\" *  Project                     ___| | | |  _ \| |
.\" *                             / __| | | | |_) | |
.\" *                            | (__| |_| |  _ <| |___
.\" *                             \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 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 https://curl.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.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_CONV_FROM_NETWORK_FUNCTION 3 "December 04, 2023" "ibcurl 8.5.0" libcurl

.SH NAME
CURLOPT_CONV_FROM_NETWORK_FUNCTION \- convert data from network to host encoding
.SH SYNOPSIS
.nf
#include <curl/curl.h>

CURLcode conv_callback(char *ptr, size_t length);

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONV_FROM_NETWORK_FUNCTION,
                          conv_callback);
.SH DESCRIPTION
Pass a pointer to your callback function, which should match the prototype
shown above.

Applies to non-ASCII platforms. \fIcurl_version_info(3)\fP returns the
\fBCURL_VERSION_CONV\fP feature bit set if this option is provided.

The data to be converted is in a buffer pointed to by the \fIptr\fP parameter.
The amount of data to convert is indicated by the \fIlength\fP parameter.  The
converted data overlays the input data in the buffer pointed to by the ptr
parameter. \fICURLE_OK\fP must be returned upon successful conversion.  A
CURLcode return value defined by curl.h, such as \fICURLE_CONV_FAILED\fP,
should be returned if an error was encountered.

\fICURLOPT_CONV_FROM_NETWORK_FUNCTION(3)\fP converts to host encoding from the
network encoding.  It is used when commands or ASCII data are received over
the network.

If you set a callback pointer to NULL, or do not set it at all, the built-in
libcurl iconv functions are used. If HAVE_ICONV was not defined when libcurl
was built, and no callback has been established, the conversion returns the
\fBCURLE_CONV_REQD\fP error code.

If \fBHAVE_ICONV\fP is defined, \fBCURL_ICONV_CODESET_OF_HOST\fP must also be
defined. For example:

 \&#define CURL_ICONV_CODESET_OF_HOST "IBM-1047"

The iconv code in libcurl defaults 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 need to override these definitions if they are different on your system.
.SH DEFAULT
NULL
.SH PROTOCOLS
FTP, SMTP, IMAP, POP3
.SH EXAMPLE
.nf
static CURLcode my_conv_from_ascii_to_ebcdic(char *buffer, size_t length)
{
  int rc = 0;

  /* in-place convert 'buffer' from ASCII to EBCDIC */

  if(rc == 0) {
    /* success */
    return CURLE_OK;
  }
  else {
    return CURLE_CONV_FAILED;
  }
}

int main(void)
{
  CURL *curl = curl_easy_init();

  /* use platform-specific functions for codeset conversions */
  curl_easy_setopt(curl, CURLOPT_CONV_FROM_NETWORK_FUNCTION,
                   my_conv_from_ascii_to_ebcdic);
}
.fi
.SH AVAILABILITY
Not available and deprecated since 7.82.0.

Available only if \fBCURL_DOES_CONVERSIONS\fP was defined when libcurl was
built.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_CONV_FROM_UTF8_FUNCTION (3),
.BR CURLOPT_CONV_TO_NETWORK_FUNCTION (3)