Home | History | Annotate | Line # | Download | only in man3 
      1 =pod
      2 
      3 =head1 NAME
      4 
      5 BIO_hostserv_priorities,
      6 BIO_parse_hostserv
      7 - utility routines to parse a standard host and service string
      8 
      9 =head1 SYNOPSIS
     10 
     11  #include <openssl/bio.h>
     12 
     13  enum BIO_hostserv_priorities {
     14      BIO_PARSE_PRIO_HOST, BIO_PARSE_PRIO_SERV
     15  };
     16  int BIO_parse_hostserv(const char *hostserv, char **host, char **service,
     17                         enum BIO_hostserv_priorities hostserv_prio);
     18 
     19 =head1 DESCRIPTION
     20 
     21 BIO_parse_hostserv() will parse the information given in B<hostserv>,
     22 create strings with the hostname and service name and give those
     23 back via B<host> and B<service>.  Those will need to be freed after
     24 they are used.  B<hostserv_prio> helps determine if B<hostserv> shall
     25 be interpreted primarily as a hostname or a service name in ambiguous
     26 cases.
     27 
     28 The syntax the BIO_parse_hostserv() recognises is:
     29 
     30  host + ':' + service
     31  host + ':' + '*'
     32  host + ':'
     33         ':' + service
     34  '*'  + ':' + service
     35  host
     36  service
     37 
     38 The host part can be a name or an IP address.  If it's a IPv6
     39 address, it MUST be enclosed in brackets, such as '[::1]'.
     40 
     41 The service part can be a service name or its port number.  A service name
     42 will be mapped to a port number using the system function getservbyname().
     43 
     44 The returned values will depend on the given B<hostserv> string
     45 and B<hostserv_prio>, as follows:
     46 
     47  host + ':' + service  => *host = "host", *service = "service"
     48  host + ':' + '*'      => *host = "host", *service = NULL
     49  host + ':'            => *host = "host", *service = NULL
     50         ':' + service  => *host = NULL, *service = "service"
     51   '*' + ':' + service  => *host = NULL, *service = "service"
     52 
     53  in case no ':' is present in the string, the result depends on
     54  hostserv_prio, as follows:
     55 
     56  when hostserv_prio == BIO_PARSE_PRIO_HOST
     57  host                 => *host = "host", *service untouched
     58 
     59  when hostserv_prio == BIO_PARSE_PRIO_SERV
     60  service              => *host untouched, *service = "service"
     61 
     62 =head1 RETURN VALUES
     63 
     64 BIO_parse_hostserv() returns 1 on success or 0 on error.
     65 
     66 =head1 SEE ALSO
     67 
     68 L<BIO_ADDRINFO(3)>
     69 
     70 =head1 COPYRIGHT
     71 
     72 Copyright 2016-2021 The OpenSSL Project Authors. All Rights Reserved.
     73 
     74 Licensed under the Apache License 2.0 (the "License").  You may not use
     75 this file except in compliance with the License.  You can obtain a copy
     76 in the file LICENSE in the source distribution or at
     77 L<https://www.openssl.org/source/license.html>.
     78 
     79 =cut
     80