Re-install OpenSSL 0.9.8k
[msysgit.git] / ssl / man / man3 / BIO_get_conn_hostname.3
blobf868229687e863fc4783c18ccf04931babf6f6ce
1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sh \" Subsection heading
6 .br
7 .if t .Sp
8 .ne 5
9 .PP
10 \fB\\$1\fR
11 .PP
13 .de Sp \" Vertical space (when we can't use .PP)
14 .if t .sp .5v
15 .if n .sp
17 .de Vb \" Begin verbatim text
18 .ft CW
19 .nf
20 .ne \\$1
22 .de Ve \" End verbatim text
23 .ft R
24 .fi
26 .\" Set up some character translations and predefined strings.  \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote.  | will give a
29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
32 .tr \(*W-|\(bv\*(Tr
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
34 .ie n \{\
35 .    ds -- \(*W-
36 .    ds PI pi
37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
39 .    ds L" ""
40 .    ds R" ""
41 .    ds C` ""
42 .    ds C' ""
43 'br\}
44 .el\{\
45 .    ds -- \|\(em\|
46 .    ds PI \(*p
47 .    ds L" ``
48 .    ds R" ''
49 'br\}
50 .\"
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
55 .if \nF \{\
56 .    de IX
57 .    tm Index:\\$1\t\\n%\t"\\$2"
59 .    nr % 0
60 .    rr F
61 .\}
62 .\"
63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
65 .hy 0
66 .if n .na
67 .\"
68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
70 .    \" fudge factors for nroff and troff
71 .if n \{\
72 .    ds #H 0
73 .    ds #V .8m
74 .    ds #F .3m
75 .    ds #[ \f1
76 .    ds #] \fP
77 .\}
78 .if t \{\
79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80 .    ds #V .6m
81 .    ds #F 0
82 .    ds #[ \&
83 .    ds #] \&
84 .\}
85 .    \" simple accents for nroff and troff
86 .if n \{\
87 .    ds ' \&
88 .    ds ` \&
89 .    ds ^ \&
90 .    ds , \&
91 .    ds ~ ~
92 .    ds /
93 .\}
94 .if t \{\
95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
102 .    \" troff and (daisy-wheel) nroff accents
103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110 .ds ae a\h'-(\w'a'u*4/10)'e
111 .ds Ae A\h'-(\w'A'u*4/10)'E
112 .    \" corrections for vroff
113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115 .    \" for low resolution devices (crt and lpr)
116 .if \n(.H>23 .if \n(.V>19 \
118 .    ds : e
119 .    ds 8 ss
120 .    ds o a
121 .    ds d- d\h'-1'\(ga
122 .    ds D- D\h'-1'\(hy
123 .    ds th \o'bp'
124 .    ds Th \o'LP'
125 .    ds ae ae
126 .    ds Ae AE
128 .rm #[ #] #H #V #F C
129 .\" ========================================================================
131 .IX Title "BIO_s_connect 3"
132 .TH BIO_s_connect 3 "2009-07-23" "0.9.8k" "OpenSSL"
133 .SH "NAME"
134 BIO_s_connect, BIO_set_conn_hostname, BIO_set_conn_port,
135 BIO_set_conn_ip, BIO_set_conn_int_port, BIO_get_conn_hostname,
136 BIO_get_conn_port, BIO_get_conn_ip, BIO_get_conn_int_port,
137 BIO_set_nbio, BIO_do_connect \- connect BIO
138 .SH "SYNOPSIS"
139 .IX Header "SYNOPSIS"
140 .Vb 1
141 \& #include <openssl/bio.h>
144 .Vb 1
145 \& BIO_METHOD * BIO_s_connect(void);
148 .Vb 1
149 \& BIO *BIO_new_connect(char *name);
152 .Vb 8
153 \& long BIO_set_conn_hostname(BIO *b, char *name);
154 \& long BIO_set_conn_port(BIO *b, char *port);
155 \& long BIO_set_conn_ip(BIO *b, char *ip);
156 \& long BIO_set_conn_int_port(BIO *b, char *port);
157 \& char *BIO_get_conn_hostname(BIO *b);
158 \& char *BIO_get_conn_port(BIO *b);
159 \& char *BIO_get_conn_ip(BIO *b, dummy);
160 \& long BIO_get_conn_int_port(BIO *b, int port);
163 .Vb 1
164 \& long BIO_set_nbio(BIO *b, long n);
167 .Vb 1
168 \& int BIO_do_connect(BIO *b);
170 .SH "DESCRIPTION"
171 .IX Header "DESCRIPTION"
172 \&\fIBIO_s_connect()\fR returns the connect \s-1BIO\s0 method. This is a wrapper
173 round the platform's \s-1TCP/IP\s0 socket connection routines.
175 Using connect BIOs, \s-1TCP/IP\s0 connections can be made and data
176 transferred using only \s-1BIO\s0 routines. In this way any platform
177 specific operations are hidden by the \s-1BIO\s0 abstraction.
179 Read and write operations on a connect \s-1BIO\s0 will perform I/O
180 on the underlying connection. If no connection is established
181 and the port and hostname (see below) is set up properly then
182 a connection is established first.
184 Connect BIOs support \fIBIO_puts()\fR but not \fIBIO_gets()\fR.
186 If the close flag is set on a connect \s-1BIO\s0 then any active
187 connection is shutdown and the socket closed when the \s-1BIO\s0
188 is freed.
190 Calling \fIBIO_reset()\fR on a connect \s-1BIO\s0 will close any active
191 connection and reset the \s-1BIO\s0 into a state where it can connect
192 to the same host again.
194 \&\fIBIO_get_fd()\fR places the underlying socket in \fBc\fR if it is not \s-1NULL\s0,
195 it also returns the socket . If \fBc\fR is not \s-1NULL\s0 it should be of
196 type (int *).
198 \&\fIBIO_set_conn_hostname()\fR uses the string \fBname\fR to set the hostname.
199 The hostname can be an \s-1IP\s0 address. The hostname can also include the
200 port in the form hostname:port . It is also acceptable to use the
201 form \*(L"hostname/any/other/path\*(R" or \*(L"hostname:port/any/other/path\*(R".
203 \&\fIBIO_set_conn_port()\fR sets the port to \fBport\fR. \fBport\fR can be the
204 numerical form or a string such as \*(L"http\*(R". A string will be looked
205 up first using \fIgetservbyname()\fR on the host platform but if that
206 fails a standard table of port names will be used. Currently the
207 list is http, telnet, socks, https, ssl, ftp, gopher and wais.
209 \&\fIBIO_set_conn_ip()\fR sets the \s-1IP\s0 address to \fBip\fR using binary form,
210 that is four bytes specifying the \s-1IP\s0 address in big-endian form.
212 \&\fIBIO_set_conn_int_port()\fR sets the port using \fBport\fR. \fBport\fR should
213 be of type (int *).
215 \&\fIBIO_get_conn_hostname()\fR returns the hostname of the connect \s-1BIO\s0 or
216 \&\s-1NULL\s0 if the \s-1BIO\s0 is initialized but no hostname is set.
217 This return value is an internal pointer which should not be modified.
219 \&\fIBIO_get_conn_port()\fR returns the port as a string.
221 \&\fIBIO_get_conn_ip()\fR returns the \s-1IP\s0 address in binary form.
223 \&\fIBIO_get_conn_int_port()\fR returns the port as an int.
225 \&\fIBIO_set_nbio()\fR sets the non blocking I/O flag to \fBn\fR. If \fBn\fR is
226 zero then blocking I/O is set. If \fBn\fR is 1 then non blocking I/O
227 is set. Blocking I/O is the default. The call to \fIBIO_set_nbio()\fR
228 should be made before the connection is established because 
229 non blocking I/O is set during the connect process.
231 \&\fIBIO_new_connect()\fR combines \fIBIO_new()\fR and \fIBIO_set_conn_hostname()\fR into
232 a single call: that is it creates a new connect \s-1BIO\s0 with \fBname\fR.
234 \&\fIBIO_do_connect()\fR attempts to connect the supplied \s-1BIO\s0. It returns 1
235 if the connection was established successfully. A zero or negative
236 value is returned if the connection could not be established, the
237 call \fIBIO_should_retry()\fR should be used for non blocking connect BIOs
238 to determine if the call should be retried.
239 .SH "NOTES"
240 .IX Header "NOTES"
241 If blocking I/O is set then a non positive return value from any
242 I/O call is caused by an error condition, although a zero return
243 will normally mean that the connection was closed.
245 If the port name is supplied as part of the host name then this will
246 override any value set with \fIBIO_set_conn_port()\fR. This may be undesirable
247 if the application does not wish to allow connection to arbitrary
248 ports. This can be avoided by checking for the presence of the ':'
249 character in the passed hostname and either indicating an error or
250 truncating the string at that point.
252 The values returned by \fIBIO_get_conn_hostname()\fR, \fIBIO_get_conn_port()\fR,
253 \&\fIBIO_get_conn_ip()\fR and \fIBIO_get_conn_int_port()\fR are updated when a
254 connection attempt is made. Before any connection attempt the values
255 returned are those set by the application itself.
257 Applications do not have to call \fIBIO_do_connect()\fR but may wish to do
258 so to separate the connection process from other I/O processing.
260 If non blocking I/O is set then retries will be requested as appropriate.
262 It addition to \fIBIO_should_read()\fR and \fIBIO_should_write()\fR it is also
263 possible for \fIBIO_should_io_special()\fR to be true during the initial
264 connection process with the reason \s-1BIO_RR_CONNECT\s0. If this is returned
265 then this is an indication that a connection attempt would block,
266 the application should then take appropriate action to wait until
267 the underlying socket has connected and retry the call.
269 \&\fIBIO_set_conn_hostname()\fR, \fIBIO_set_conn_port()\fR, \fIBIO_set_conn_ip()\fR,
270 \&\fIBIO_set_conn_int_port()\fR, \fIBIO_get_conn_hostname()\fR, \fIBIO_get_conn_port()\fR,
271 \&\fIBIO_get_conn_ip()\fR, \fIBIO_get_conn_int_port()\fR, \fIBIO_set_nbio()\fR and
272 \&\fIBIO_do_connect()\fR are macros.
273 .SH "RETURN VALUES"
274 .IX Header "RETURN VALUES"
275 \&\fIBIO_s_connect()\fR returns the connect \s-1BIO\s0 method.
277 \&\fIBIO_get_fd()\fR returns the socket or \-1 if the \s-1BIO\s0 has not
278 been initialized.
280 \&\fIBIO_set_conn_hostname()\fR, \fIBIO_set_conn_port()\fR, \fIBIO_set_conn_ip()\fR and
281 \&\fIBIO_set_conn_int_port()\fR always return 1.
283 \&\fIBIO_get_conn_hostname()\fR returns the connected hostname or \s-1NULL\s0 is
284 none was set.
286 \&\fIBIO_get_conn_port()\fR returns a string representing the connected
287 port or \s-1NULL\s0 if not set.
289 \&\fIBIO_get_conn_ip()\fR returns a pointer to the connected \s-1IP\s0 address in
290 binary form or all zeros if not set.
292 \&\fIBIO_get_conn_int_port()\fR returns the connected port or 0 if none was
293 set.
295 \&\fIBIO_set_nbio()\fR always returns 1.
297 \&\fIBIO_do_connect()\fR returns 1 if the connection was successfully
298 established and 0 or \-1 if the connection failed.
299 .SH "EXAMPLE"
300 .IX Header "EXAMPLE"
301 This is example connects to a webserver on the local host and attempts
302 to retrieve a page and copy the result to standard output.
304 .Vb 19
305 \& BIO *cbio, *out;
306 \& int len;
307 \& char tmpbuf[1024];
308 \& ERR_load_crypto_strings();
309 \& cbio = BIO_new_connect("localhost:http");
310 \& out = BIO_new_fp(stdout, BIO_NOCLOSE);
311 \& if(BIO_do_connect(cbio) <= 0) {
312 \&        fprintf(stderr, "Error connecting to server\en");
313 \&        ERR_print_errors_fp(stderr);
314 \&        /* whatever ... */
315 \&        }
316 \& BIO_puts(cbio, "GET / HTTP/1.0\en\en");
317 \& for(;;) {      
318 \&        len = BIO_read(cbio, tmpbuf, 1024);
319 \&        if(len <= 0) break;
320 \&        BIO_write(out, tmpbuf, len);
321 \& }
322 \& BIO_free(cbio);
323 \& BIO_free(out);
325 .SH "SEE ALSO"
326 .IX Header "SEE ALSO"
327 \&\s-1TBA\s0