doc/crypto/BIO_parse_hostserv.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 BIO_parse_hostserv - utility routines to parse a standard host and service
   6 string
   7
   8 =head1 SYNOPSIS
   9
  10  #include <openssl/bio.h>
  11
  12  enum BIO_hostserv_priorities {
  13      BIO_PARSE_PRIO_HOST, BIO_PARSE_PRIO_SERV
  14  };
  15  int BIO_parse_hostserv(const char *hostserv, char **host, char **service,
  16                         enum BIO_hostserv_priorities hostserv_prio);
  17
  18 =head1 DESCRIPTION
  19
  20 BIO_parse_hostserv() will parse the information given in B<hostserv>,
  21 create strings with the host name and service name and give those
  22 back via B<host> and B<service>.  Those will need to be freed after
  23 they are used.  B<hostserv_prio> helps determine if B<hostserv> shall
  24 be interpreted primarly as a host name or a service name in ambiguous
  25 cases.
  26
  27 The syntax the BIO_parse_hostserv() recognises is:
  28
  29  host + ':' + service
  30  host + ':' + '*'
  31  host + ':'
  32         ':' + service
  33  '*'  + ':' + service
  34  host
  35  service
  36
  37 The host part can be a name or an IP address.  If it's a IPv6
  38 address, it MUST be enclosed in brackets, such as '[::1]'.
  39
  40 The service part can  be a service name or its port number.
  41
  42 The returned values will depend on the given B<hostserv> string
  43 and B<hostserv_prio>, as follows:
  44
  45  host + ':' + service  => *host = "host", *service = "service"
  46  host + ':' + '*'      => *host = "host", *service = NULL
  47  host + ':'            => *host = "host", *service = NULL
  48         ':' + service  => *host = NULL, *service = "service"
  49   '*' + ':' + service  => *host = NULL, *service = "service"
  50
  51  in case no ':' is present in the string, the result depends on
  52  hostserv_prio, as follows:
  53
  54  when hostserv_prio == BIO_PARSE_PRIO_HOST
  55  host                 => *host = "host", *service untouched
  56
  57  when hostserv_prio == BIO_PARSE_PRIO_SERV
  58  service              => *host untouched, *service = "service"
  59
  60 =head1 SEE ALSO
  61
  62 L<BIO_ADDRINFO(3)>