Refactoring BIO: add wrappers around sockaddr et al
[openssl.git] / 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)>