Return to libcurl-url.3 CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / curl / docs / libcurl

curl

    1: .\" **************************************************************************
    2: .\" *                                  _   _ ____  _
    3: .\" *  Project                     ___| | | |  _ \| |
    4: .\" *                             / __| | | | |_) | |
    5: .\" *                            | (__| |_| |  _ <| |___
    6: .\" *                             \___|\___/|_| \_\_____|
    7: .\" *
    8: .\" * Copyright (C) 1998 - 2018, 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: .TH libcurl 3 "September 10, 2018" "libcurl 7.70.0" "libcurl url interface"
   23: 
   24: .SH NAME
   25: libcurl-url \- URL interface overview
   26: .SH DESCRIPTION
   27: The URL interface provides a set of functions for parsing and generating URLs.
   28: .SH INCLUDE
   29: You still only include <curl/curl.h> in your code. Note that the URL API was
   30: introduced in 7.62.0.
   31: .SH CREATE
   32: Create a handle that holds URL info and resources with \fIcurl_url(3)\fP:
   33: 
   34:   CURLU *h = curl_url();
   35: .SH CLEANUP
   36: When done with it, clean it up with \fIcurl_url_cleanup(3)\fP:
   37: 
   38:   curl_url_cleanup(h);
   39: .SH DUPLICATE
   40: When you need a copy of a handle, just duplicate it with \fIcurl_url_dup(3)\fP:
   41: 
   42:   CURLU *nh = curl_url_dup(h);
   43: .SH PARSING
   44: By "setting" a URL to the handle with \fIcurl_url_set(3)\fP, the URL is parsed
   45: and stored in the handle. If the URL is not syntactically correct it will
   46: return an error instead.
   47: 
   48: .nf
   49:   rc = curl_url_set(h, CURLUPART_URL,
   50:                     "https://example.com:449/foo/bar?name=moo", 0);
   51: .fi
   52: 
   53: The zero in the fourth argument is a bitmask for changing specific features.
   54: 
   55: If successful, this stores the URL in its individual parts within the handle.
   56: .SH REDIRECT
   57: When a handle already contains info about a URL, setting a relative URL will
   58: make it "redirect" to adapt to it.
   59: 
   60:   rc = curl_url_set(h, CURLUPART_URL, "../test?another", 0);
   61: .SH "GET URL"
   62: The `CURLU` handle represents a URL and you can easily extract that with
   63: \fIcurl_url_get(3)\fP:
   64: 
   65:   char *url;
   66:   rc = curl_url_get(h, CURLUPART_URL, &url, 0);
   67:   curl_free(url);
   68: 
   69: The zero in the fourth argument is a bitmask for changing specific features.
   70: .SH "GET PARTS"
   71: When a URL has been parsed or parts have been set, you can extract those
   72: pieces from the handle at any time.
   73: 
   74: .nf
   75:   rc = curl_url_get(h, CURLUPART_HOST, &host, 0);
   76:   rc = curl_url_get(h, CURLUPART_SCHEME, &scheme, 0);
   77:   rc = curl_url_get(h, CURLUPART_USER, &user, 0);
   78:   rc = curl_url_get(h, CURLUPART_PASSWORD, &password, 0);
   79:   rc = curl_url_get(h, CURLUPART_PORT, &port, 0);
   80:   rc = curl_url_get(h, CURLUPART_PATH, &path, 0);
   81:   rc = curl_url_get(h, CURLUPART_QUERY, &query, 0);
   82:   rc = curl_url_get(h, CURLUPART_FRAGMENT, &fragment, 0);
   83: .fi
   84: 
   85: Extracted parts are not URL decoded unless the user also asks for it with the
   86: CURLU_URLDECODE flag set in the fourth bitmask argument.
   87: 
   88: Remember to free the returned string with \fIcurl_free(3)\fP when you're done
   89: with it!
   90: .SH "SET PARTS"
   91: A user set individual URL parts, either after having parsed a full URL or
   92: instead of parsing such.
   93: 
   94: .nf
   95:   rc = curl_url_set(urlp, CURLUPART_HOST, "www.example.com", 0);
   96:   rc = curl_url_set(urlp, CURLUPART_SCHEME, "https", 0);
   97:   rc = curl_url_set(urlp, CURLUPART_USER, "john", 0);
   98:   rc = curl_url_set(urlp, CURLUPART_PASSWORD, "doe", 0);
   99:   rc = curl_url_set(urlp, CURLUPART_PORT, "443", 0);
  100:   rc = curl_url_set(urlp, CURLUPART_PATH, "/index.html", 0);
  101:   rc = curl_url_set(urlp, CURLUPART_QUERY, "name=john", 0);
  102:   rc = curl_url_set(urlp, CURLUPART_FRAGMENT, "anchor", 0);
  103: .fi
  104: 
  105: Set parts are not URL encoded unless the user asks for it with the
  106: `CURLU_URLENCODE` flag.
  107: .SH "APPENDQUERY"
  108: An application can append a string to the right end of the query part with the
  109: `CURLU_APPENDQUERY` flag to \fIcurl_url_set(3)\fP.
  110: 
  111: Imagine a handle that holds the URL `https://example.com/?shoes=2`. An
  112: application can then add the string `hat=1` to the query part like this:
  113: 
  114: .nf
  115:   rc = curl_url_set(urlp, CURLUPART_QUERY, "hat=1", CURLU_APPENDQUERY);
  116: .fi
  117: 
  118: It will even notice the lack of an ampersand (`&`) separator so it will inject
  119: one too, and the handle's full URL will then equal
  120: `https://example.com/?shoes=2&hat=1`.
  121: 
  122: The appended string can of course also get URL encoded on add, and if asked to
  123: URL encode, the encoding process will skip the '=' character. For example,
  124: append `candy=N&N` to what we already have, and URL encode it to deal with the
  125: ampersand in the data:
  126: 
  127: .nf
  128:   rc = curl_url_set(urlp, CURLUPART_QUERY, "candy=N&N",
  129:                     CURLU_APPENDQUERY | CURLU_URLENCODE);
  130: .fi
  131: 
  132: Now the URL looks like
  133: .nf
  134:   https://example.com/?shoes=2&hat=1&candy=N%26N`
  135: .fi
  136: .SH "SEE ALSO"
  137: .BR curl_url "(3), " curl_url_cleanup "(3), " curl_url_get "(3), "
  138: .BR curl_url_dup "(3), " curl_url_set "(3), " CURLOPT_URL "(3), "