OSSL_HTTP_parse_url(): Handle any userinfo, query, and fragment components

[openssl.git] / doc / man3 / OSSL_HTTP_parse_url.pod

diff --git a/doc/man3/OSSL_HTTP_parse_url.pod b/doc/man3/OSSL_HTTP_parse_url.pod
new file mode 100644 (file)
index 0000000..5933e95
--- /dev/null
+++ b/doc/man3/OSSL_HTTP_parse_url.pod
@@ -0,0 +1,73 @@
+=pod
+
+=head1 NAME
+
+OSSL_HTTP_parse_url,
+OCSP_parse_url
+- http utility functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/http.h>
+
+ int OSSL_HTTP_parse_url(const char *url,
+                         int *pssl, char **puser, char **phost,
+                         char **pport, int *pport_num,
+                         char **ppath, char **pquery, char **pfrag);
+
+Deprecated since OpenSSL 3.0, can be hidden entirely by defining
+B<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
+
+ int OCSP_parse_url(const char *url, char **phost, char **pport, char **ppath,
+                    int *pssl);
+
+=head1 DESCRIPTION
+
+OSSL_HTTP_parse_url() parses its input string I<url> as a URL of the form
+C<[http[s]://][userinfo@]host[:port][/path][?query][#fragment]> and splits it up
+into userinfo, host, port, path, query, and fragment components
+and a flag indicating whether it begins with C<https>.
+The host component may be a DNS name or an IP address
+where IPv6 addresses should be enclosed in square brackets C<[> and C<]>.
+The port component is optional and defaults to "443" for HTTPS, else "80".
+If given, it must be in decimal form.  If the I<pport_num> argument is not NULL
+the integer value of the port number is assigned to I<*pport_num> on success.
+The path component is also optional and defaults to C</>.
+If I<pssl> is not NULL, I<*pssl> is assigned 1 in case parsing was successful
+and the schema part is present and is C<https>, else 0.
+Each non-NULL result pointer argument I<puser>, I<phost>, I<pport>, I<ppath>,
+I<pquery>, and I<pfrag>, is assigned the respective url component.
+On success, they are guaranteed to contain non-NULL string pointers, else NULL.
+It is the reponsibility of the caller to free them using L<OPENSSL_free(3)>.
+If I<pquery> is NULL, any given query component is handled as part of the path.
+A string returned via I<*ppath> is guaranteed to begin with a C</> character.
+For absent userinfo, query, and fragment components an empty string is given.
+
+Calling the deprecated fucntion OCSP_parse_url(url, host, port, path, ssl) is
+equivalent to OSSL_HTTP_parse_url(url, ssl, NULL, host, port, NULL, path, NULL, NULL).
+
+=head1 RETURN VALUES
+
+OSSL_HTTP_parse_url() and OCSP_parse_url()
+return 1 on success, 0 on error.
+
+=head1 SEE ALSO
+
+L<OSSL_HTTP_transfer(3)>
+
+=head1 HISTORY
+
+OOSSL_HTTP_parse_url() was added in OpenSSL 3.0.
+OCSP_parse_url() was deprecated in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut