doc/man3/OSSL_HTTP_parse_url.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 OSSL_parse_url,
   6 OSSL_HTTP_parse_url,
   7 OCSP_parse_url
   8 - http utility functions
   9
  10 =head1 SYNOPSIS
  11
  12  #include <openssl/http.h>
  13
  14  int OSSL_parse_url(const char *url, char **pscheme, char **puser, char **phost,
  15                     char **pport, int *pport_num,
  16                     char **ppath, char **pquery, char **pfrag);
  17  int OSSL_HTTP_parse_url(const char *url,
  18                          int *pssl, char **puser, char **phost,
  19                          char **pport, int *pport_num,
  20                          char **ppath, char **pquery, char **pfrag);
  21
  22 Deprecated since OpenSSL 3.0, can be hidden entirely by defining
  23 B<OPENSSL_API_COMPAT> with a suitable version value, see
  24 L<openssl_user_macros(7)>:
  25
  26  int OCSP_parse_url(const char *url, char **phost, char **pport, char **ppath,
  27                     int *pssl);
  28
  29 =head1 DESCRIPTION
  30
  31 OSSL_parse_url() parses its input string I<url> as a URL of the form
  32 C<[scheme://][userinfo@]host[:port][/path][?query][#fragment]> and splits it up
  33 into scheme, userinfo, host, port, path, query, and fragment components.
  34 The host component may be a DNS name or an IP address
  35 where IPv6 addresses should be enclosed in square brackets C<[> and C<]>.
  36 The port component is optional and defaults to C<0>.
  37 If given, it must be in decimal form.  If the I<pport_num> argument is not NULL
  38 the integer value of the port number is assigned to I<*pport_num> on success.
  39 The path component is also optional and defaults to C</>.
  40 Each non-NULL result pointer argument I<pscheme>, I<puser>, I<phost>, I<pport>,
  41 I<ppath>, I<pquery>, and I<pfrag>, is assigned the respective url component.
  42 On success, they are guaranteed to contain non-NULL string pointers, else NULL.
  43 It is the reponsibility of the caller to free them using L<OPENSSL_free(3)>.
  44 If I<pquery> is NULL, any given query component is handled as part of the path.
  45 A string returned via I<*ppath> is guaranteed to begin with a C</> character.
  46 For absent scheme, userinfo, port, query, and fragment components
  47 an empty string is provided.
  48
  49 OSSL_HTTP_parse_url() is a special form of OSSL_parse_url()
  50 where the scheme, if given, must be C<http> or C<https>.
  51 If I<pssl> is not NULL, I<*pssl> is assigned 1 in case parsing was successful
  52 and the scheme is C<https>, else 0.
  53 The port component is optional and defaults to C<443> if the scheme is C<https>,
  54 else C<80>.
  55
  56 Calling the deprecated function OCSP_parse_url(url, host, port, path, ssl)
  57 is equivalent to
  58 OSSL_HTTP_parse_url(url, ssl, NULL, host, port, NULL, path, NULL, NULL).
  59
  60 =head1 RETURN VALUES
  61
  62 OSSL_HTTP_parse_url() and OCSP_parse_url()
  63 return 1 on success, 0 on error.
  64
  65 =head1 SEE ALSO
  66
  67 L<OSSL_HTTP_transfer(3)>
  68
  69 =head1 HISTORY
  70
  71 OOSSL_HTTP_parse_url() was added in OpenSSL 3.0.
  72 OCSP_parse_url() was deprecated in OpenSSL 3.0.
  73
  74 =head1 COPYRIGHT
  75
  76 Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
  77
  78 Licensed under the Apache License 2.0 (the "License").  You may not use
  79 this file except in compliance with the License.  You can obtain a copy
  80 in the file LICENSE in the source distribution or at
  81 L<https://www.openssl.org/source/license.html>.
  82
  83 =cut