Generalize schmeme parsing of OSSL_HTTP_parse_url() to OSSL_parse_url()

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

=pod

=head1 NAME

OSSL_parse_url,
OSSL_HTTP_parse_url,
OCSP_parse_url
- http utility functions

=head1 SYNOPSIS

 #include <openssl/http.h>

 int OSSL_parse_url(const char *url, char **pscheme, char **puser, char **phost,
                    char **pport, int *pport_num,
                    char **ppath, char **pquery, char **pfrag);
 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_parse_url() parses its input string I<url> as a URL of the form
C<[scheme://][userinfo@]host[:port][/path][?query][#fragment]> and splits it up
into scheme, userinfo, host, port, path, query, and fragment components.
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 C<0>.
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</>.
Each non-NULL result pointer argument I<pscheme>, 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 scheme, userinfo, port, query, and fragment components
an empty string is provided.

OSSL_HTTP_parse_url() is a special form of OSSL_parse_url()
where the scheme, if given, must be C<http> or C<https>.
If I<pssl> is not NULL, I<*pssl> is assigned 1 in case parsing was successful
and the scheme is C<https>, else 0.
The port component is optional and defaults to C<443> if the scheme is C<https>,
else C<80>.

Calling the deprecated function 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