Small fixes
[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 =for comment
46 The following is ONE verbatim block.  To make sure it's rendered as
47 one block and not several, the blank lines in between have one space.
48 They should be left as is.
49
50  host + ':' + service  => *host = "host", *service = "service"
51  host + ':' + '*'      => *host = "host", *service = NULL
52  host + ':'            => *host = "host", *service = NULL
53         ':' + service  => *host = NULL, *service = "service"
54   '*' + ':' + service  => *host = NULL, *service = "service"
55  
56  in case no ':' is present in the string, the result depends on
57  hostserv_prio, as follows:
58  
59  when hostserv_prio == BIO_PARSE_PRIO_HOST
60  host                 => *host = "host", *service untouched
61  
62  when hostserv_prio == BIO_PARSE_PRIO_SERV
63  service              => *host untouched, *service = "service"
64
65 =head1 SEE ALSO
66
67 L<BIO_ADDRINFO(3)>