docs/libcurl/curl_easy_escape.3

   1 .\" **************************************************************************
   2 .\" *                                  _   _ ____  _
   3 .\" *  Project                     ___| | | |  _ \| |
   4 .\" *                             / __| | | | |_) | |
   5 .\" *                            | (__| |_| |  _ <| |___
   6 .\" *                             \___|\___/|_| \_\_____|
   7 .\" *
   8 .\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
   9 .\" *
  10 .\" * This software is licensed as described in the file COPYING, which
  11 .\" * you should have received as part of this distribution. The terms
  12 .\" * are also available at https://curl.haxx.se/docs/copyright.html.
  13 .\" *
  14 .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
  15 .\" * copies of the Software, and permit persons to whom the Software is
  16 .\" * furnished to do so, under the terms of the COPYING file.
  17 .\" *
  18 .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
  19 .\" * KIND, either express or implied.
  20 .\" *
  21 .\" **************************************************************************
  22 .\"
  23 .TH curl_easy_escape 3 "August 12, 2017" "libcurl 7.59.0" "libcurl Manual"
  24
  25 .SH NAME
  26 curl_easy_escape - URL encodes the given string
  27 .SH SYNOPSIS
  28 .B #include <curl/curl.h>
  29 .sp
  30 .BI "char *curl_easy_escape( CURL *" curl ", const char *" string
  31 .BI ", int "length " );"
  32 .ad
  33 .SH DESCRIPTION
  34 This function converts the given input \fIstring\fP to a URL encoded string
  35 and returns that as a new allocated string. All input characters that are not
  36 a-z, A-Z, 0-9, '-', '.', '_' or '~' are converted to their "URL escaped"
  37 version (%NN where NN is a two-digit hexadecimal number).
  38
  39 If \fIlength\fP is set to 0 (zero), \fIcurl_easy_escape(3)\fP uses strlen() on
  40 the input \fIstring\fP to find out the size.
  41
  42 You must \fIcurl_free(3)\fP the returned string when you're done with it.
  43 .SH ENCODING
  44 libcurl is typically not aware of, nor does it care about, character
  45 encodings. \fIcurl_easy_escape(3)\fP encodes the data byte-by-byte into the
  46 URL encoded version without knowledge or care for what particular character
  47 encoding the application or the receiving server may assume that the data
  48 uses.
  49
  50 The caller of \fIcurl_easy_escape(3)\fP must make sure that the data passed in
  51 to the function is encoded correctly.
  52 .SH AVAILABILITY
  53 Added in 7.15.4 and replaces the old \fIcurl_escape(3)\fP function.
  54 .SH RETURN VALUE
  55 A pointer to a zero terminated string or NULL if it failed.
  56 .SH EXAMPLE
  57 .nf
  58 CURL *curl = curl_easy_init();
  59 if(curl) {
  60   char *output = curl_easy_escape(curl, "data to convert", 15);
  61   if(output) {
  62     printf("Encoded: %s\\n", output);
  63     curl_free(output);
  64   }
  65 }
  66 .fi
  67 .SH "SEE ALSO"
  68 .BR curl_easy_unescape "(3), " curl_free "(3), " RFC 3986