Switch from OpenSSL 0.9.7d to 0.9.7e.
[dragonfly.git] / secure / lib / libcrypto / man / BIO_s_connect.3
CommitLineData
74dab6c2
JR
1.rn '' }`
2''' $RCSfile$$Revision$$Date$
3'''
4''' $Log$
5'''
6.de Sh
984263bc
MD
7.br
8.if t .Sp
9.ne 5
10.PP
11\fB\\$1\fR
12.PP
13..
74dab6c2 14.de Sp
984263bc
MD
15.if t .sp .5v
16.if n .sp
17..
74dab6c2 18.de Ip
984263bc
MD
19.br
20.ie \\n(.$>=3 .ne \\$3
21.el .ne 3
22.IP "\\$1" \\$2
23..
74dab6c2 24.de Vb
984263bc
MD
25.ft CW
26.nf
27.ne \\$1
28..
74dab6c2 29.de Ve
984263bc
MD
30.ft R
31
32.fi
33..
74dab6c2
JR
34'''
35'''
36''' Set up \*(-- to give an unbreakable dash;
37''' string Tr holds user defined translation string.
38''' Bell System Logo is used as a dummy character.
39'''
984263bc 40.tr \(*W-|\(bv\*(Tr
984263bc 41.ie n \{\
74dab6c2
JR
42.ds -- \(*W-
43.ds PI pi
44.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
45.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
46.ds L" ""
47.ds R" ""
48''' \*(M", \*(S", \*(N" and \*(T" are the equivalent of
49''' \*(L" and \*(R", except that they are used on ".xx" lines,
50''' such as .IP and .SH, which do another additional levels of
51''' double-quote interpretation
52.ds M" """
53.ds S" """
54.ds N" """""
55.ds T" """""
56.ds L' '
57.ds R' '
58.ds M' '
59.ds S' '
60.ds N' '
61.ds T' '
984263bc
MD
62'br\}
63.el\{\
74dab6c2
JR
64.ds -- \(em\|
65.tr \*(Tr
66.ds L" ``
67.ds R" ''
68.ds M" ``
69.ds S" ''
70.ds N" ``
71.ds T" ''
72.ds L' `
73.ds R' '
74.ds M' `
75.ds S' '
76.ds N' `
77.ds T' '
78.ds PI \(*p
984263bc 79'br\}
74dab6c2
JR
80.\" If the F register is turned on, we'll generate
81.\" index entries out stderr for the following things:
82.\" TH Title
83.\" SH Header
84.\" Sh Subsection
85.\" Ip Item
86.\" X<> Xref (embedded
87.\" Of course, you have to process the output yourself
88.\" in some meaninful fashion.
89.if \nF \{
90.de IX
91.tm Index:\\$1\t\\n%\t"\\$2"
984263bc 92..
74dab6c2
JR
93.nr % 0
94.rr F
984263bc 95.\}
74dab6c2
JR
96.TH BIO_s_connect 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
97.UC
98.if n .hy 0
984263bc 99.if n .na
74dab6c2
JR
100.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
101.de CQ \" put $1 in typewriter font
102.ft CW
103'if n "\c
104'if t \\&\\$1\c
105'if n \\&\\$1\c
106'if n \&"
107\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
108'.ft R
109..
110.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
111. \" AM - accent mark definitions
984263bc 112.bd B 3
74dab6c2 113. \" fudge factors for nroff and troff
984263bc 114.if n \{\
74dab6c2
JR
115. ds #H 0
116. ds #V .8m
117. ds #F .3m
118. ds #[ \f1
119. ds #] \fP
984263bc
MD
120.\}
121.if t \{\
74dab6c2
JR
122. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
123. ds #V .6m
124. ds #F 0
125. ds #[ \&
126. ds #] \&
984263bc 127.\}
74dab6c2 128. \" simple accents for nroff and troff
984263bc 129.if n \{\
74dab6c2
JR
130. ds ' \&
131. ds ` \&
132. ds ^ \&
133. ds , \&
134. ds ~ ~
135. ds ? ?
136. ds ! !
137. ds /
138. ds q
984263bc
MD
139.\}
140.if t \{\
74dab6c2
JR
141. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
142. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
143. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
144. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
145. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
146. ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
147. ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
148. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
149. ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
984263bc 150.\}
74dab6c2 151. \" troff and (daisy-wheel) nroff accents
984263bc
MD
152.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
153.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
74dab6c2
JR
154.ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
155.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
156.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
157.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
984263bc
MD
158.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
159.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
160.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
161.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
162.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
163.ds ae a\h'-(\w'a'u*4/10)'e
164.ds Ae A\h'-(\w'A'u*4/10)'E
74dab6c2
JR
165.ds oe o\h'-(\w'o'u*4/10)'e
166.ds Oe O\h'-(\w'O'u*4/10)'E
167. \" corrections for vroff
984263bc
MD
168.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
169.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
74dab6c2 170. \" for low resolution devices (crt and lpr)
984263bc
MD
171.if \n(.H>23 .if \n(.V>19 \
172\{\
74dab6c2
JR
173. ds : e
174. ds 8 ss
175. ds v \h'-1'\o'\(aa\(ga'
176. ds _ \h'-1'^
177. ds . \h'-1'.
178. ds 3 3
179. ds o a
180. ds d- d\h'-1'\(ga
181. ds D- D\h'-1'\(hy
182. ds th \o'bp'
183. ds Th \o'LP'
184. ds ae ae
185. ds Ae AE
186. ds oe oe
187. ds Oe OE
984263bc
MD
188.\}
189.rm #[ #] #H #V #F C
984263bc
MD
190.SH "NAME"
191BIO_s_connect, BIO_set_conn_hostname, BIO_set_conn_port,
192BIO_set_conn_ip, BIO_set_conn_int_port, BIO_get_conn_hostname,
193BIO_get_conn_port, BIO_get_conn_ip, BIO_get_conn_int_port,
74dab6c2 194BIO_set_nbio, BIO_do_connect \- connect BIO
984263bc 195.SH "SYNOPSIS"
74dab6c2 196.PP
984263bc
MD
197.Vb 1
198\& #include <openssl/bio.h>
199.Ve
200.Vb 1
201\& BIO_METHOD * BIO_s_connect(void);
202.Ve
203.Vb 1
204\& BIO *BIO_new_connect(char *name);
205.Ve
206.Vb 8
207\& long BIO_set_conn_hostname(BIO *b, char *name);
208\& long BIO_set_conn_port(BIO *b, char *port);
209\& long BIO_set_conn_ip(BIO *b, char *ip);
210\& long BIO_set_conn_int_port(BIO *b, char *port);
211\& char *BIO_get_conn_hostname(BIO *b);
212\& char *BIO_get_conn_port(BIO *b);
213\& char *BIO_get_conn_ip(BIO *b, dummy);
214\& long BIO_get_conn_int_port(BIO *b, int port);
215.Ve
216.Vb 1
217\& long BIO_set_nbio(BIO *b, long n);
218.Ve
219.Vb 1
220\& int BIO_do_connect(BIO *b);
221.Ve
222.SH "DESCRIPTION"
74dab6c2
JR
223\fIBIO_s_connect()\fR returns the connect BIO method. This is a wrapper
224round the platform's TCP/IP socket connection routines.
984263bc 225.PP
74dab6c2
JR
226Using connect BIOs, TCP/IP connections can be made and data
227transferred using only BIO routines. In this way any platform
228specific operations are hidden by the BIO abstraction.
984263bc 229.PP
74dab6c2 230Read and write operations on a connect BIO will perform I/O
984263bc
MD
231on the underlying connection. If no connection is established
232and the port and hostname (see below) is set up properly then
233a connection is established first.
234.PP
235Connect BIOs support \fIBIO_puts()\fR but not \fIBIO_gets()\fR.
236.PP
74dab6c2
JR
237If the close flag is set on a connect BIO then any active
238connection is shutdown and the socket closed when the BIO
984263bc
MD
239is freed.
240.PP
74dab6c2
JR
241Calling \fIBIO_reset()\fR on a connect BIO will close any active
242connection and reset the BIO into a state where it can connect
984263bc
MD
243to the same host again.
244.PP
74dab6c2
JR
245\fIBIO_get_fd()\fR places the underlying socket in \fBc\fR if it is not NULL,
246it also returns the socket . If \fBc\fR is not NULL it should be of
984263bc
MD
247type (int *).
248.PP
74dab6c2
JR
249\fIBIO_set_conn_hostname()\fR uses the string \fBname\fR to set the hostname.
250The hostname can be an IP address. The hostname can also include the
984263bc
MD
251port in the form hostname:port . It is also acceptable to use the
252form \*(L"hostname/any/other/path\*(R" or \*(L"hostname:port/any/other/path\*(R".
253.PP
74dab6c2 254\fIBIO_set_conn_port()\fR sets the port to \fBport\fR. \fBport\fR can be the
984263bc
MD
255numerical form or a string such as \*(L"http\*(R". A string will be looked
256up first using \fIgetservbyname()\fR on the host platform but if that
257fails a standard table of port names will be used. Currently the
258list is http, telnet, socks, https, ssl, ftp, gopher and wais.
259.PP
74dab6c2
JR
260\fIBIO_set_conn_ip()\fR sets the IP address to \fBip\fR using binary form,
261that is four bytes specifying the IP address in big-endian form.
984263bc 262.PP
74dab6c2 263\fIBIO_set_conn_int_port()\fR sets the port using \fBport\fR. \fBport\fR should
984263bc
MD
264be of type (int *).
265.PP
74dab6c2
JR
266\fIBIO_get_conn_hostname()\fR returns the hostname of the connect BIO or
267NULL if the BIO is initialized but no hostname is set.
984263bc
MD
268This return value is an internal pointer which should not be modified.
269.PP
74dab6c2 270\fIBIO_get_conn_port()\fR returns the port as a string.
984263bc 271.PP
74dab6c2 272\fIBIO_get_conn_ip()\fR returns the IP address in binary form.
984263bc 273.PP
74dab6c2 274\fIBIO_get_conn_int_port()\fR returns the port as an int.
984263bc 275.PP
74dab6c2 276\fIBIO_set_nbio()\fR sets the non blocking I/O flag to \fBn\fR. If \fBn\fR is
984263bc
MD
277zero then blocking I/O is set. If \fBn\fR is 1 then non blocking I/O
278is set. Blocking I/O is the default. The call to \fIBIO_set_nbio()\fR
279should be made before the connection is established because
280non blocking I/O is set during the connect process.
281.PP
74dab6c2
JR
282\fIBIO_new_connect()\fR combines \fIBIO_new()\fR and \fIBIO_set_conn_hostname()\fR into
283a single call: that is it creates a new connect BIO with \fBname\fR.
984263bc 284.PP
74dab6c2 285\fIBIO_do_connect()\fR attempts to connect the supplied BIO. It returns 1
984263bc
MD
286if the connection was established successfully. A zero or negative
287value is returned if the connection could not be established, the
288call \fIBIO_should_retry()\fR should be used for non blocking connect BIOs
289to determine if the call should be retried.
290.SH "NOTES"
984263bc
MD
291If blocking I/O is set then a non positive return value from any
292I/O call is caused by an error condition, although a zero return
293will normally mean that the connection was closed.
294.PP
295If the port name is supplied as part of the host name then this will
296override any value set with \fIBIO_set_conn_port()\fR. This may be undesirable
297if the application does not wish to allow connection to arbitrary
74dab6c2 298ports. This can be avoided by checking for the presence of the \*(L':\*(R'
984263bc
MD
299character in the passed hostname and either indicating an error or
300truncating the string at that point.
301.PP
302The values returned by \fIBIO_get_conn_hostname()\fR, \fIBIO_get_conn_port()\fR,
74dab6c2 303\fIBIO_get_conn_ip()\fR and \fIBIO_get_conn_int_port()\fR are updated when a
984263bc
MD
304connection attempt is made. Before any connection attempt the values
305returned are those set by the application itself.
306.PP
307Applications do not have to call \fIBIO_do_connect()\fR but may wish to do
308so to separate the connection process from other I/O processing.
309.PP
310If non blocking I/O is set then retries will be requested as appropriate.
311.PP
312It addition to \fIBIO_should_read()\fR and \fIBIO_should_write()\fR it is also
313possible for \fIBIO_should_io_special()\fR to be true during the initial
74dab6c2 314connection process with the reason BIO_RR_CONNECT. If this is returned
984263bc
MD
315then this is an indication that a connection attempt would block,
316the application should then take appropriate action to wait until
317the underlying socket has connected and retry the call.
318.PP
74dab6c2
JR
319\fIBIO_set_conn_hostname()\fR, \fIBIO_set_conn_port()\fR, \fIBIO_set_conn_ip()\fR,
320\fIBIO_set_conn_int_port()\fR, \fIBIO_get_conn_hostname()\fR, \fIBIO_get_conn_port()\fR,
321\fIBIO_get_conn_ip()\fR, \fIBIO_get_conn_int_port()\fR, \fIBIO_set_nbio()\fR and
322\fIBIO_do_connect()\fR are macros.
984263bc 323.SH "RETURN VALUES"
74dab6c2 324\fIBIO_s_connect()\fR returns the connect BIO method.
984263bc 325.PP
74dab6c2 326\fIBIO_get_fd()\fR returns the socket or \-1 if the BIO has not
984263bc
MD
327been initialized.
328.PP
74dab6c2
JR
329\fIBIO_set_conn_hostname()\fR, \fIBIO_set_conn_port()\fR, \fIBIO_set_conn_ip()\fR and
330\fIBIO_set_conn_int_port()\fR always return 1.
984263bc 331.PP
74dab6c2 332\fIBIO_get_conn_hostname()\fR returns the connected hostname or NULL is
984263bc
MD
333none was set.
334.PP
74dab6c2
JR
335\fIBIO_get_conn_port()\fR returns a string representing the connected
336port or NULL if not set.
984263bc 337.PP
74dab6c2 338\fIBIO_get_conn_ip()\fR returns a pointer to the connected IP address in
984263bc
MD
339binary form or all zeros if not set.
340.PP
74dab6c2 341\fIBIO_get_conn_int_port()\fR returns the connected port or 0 if none was
984263bc
MD
342set.
343.PP
74dab6c2 344\fIBIO_set_nbio()\fR always returns 1.
984263bc 345.PP
74dab6c2 346\fIBIO_do_connect()\fR returns 1 if the connection was successfully
984263bc
MD
347established and 0 or \-1 if the connection failed.
348.SH "EXAMPLE"
984263bc
MD
349This is example connects to a webserver on the local host and attempts
350to retrieve a page and copy the result to standard output.
351.PP
352.Vb 19
353\& BIO *cbio, *out;
354\& int len;
355\& char tmpbuf[1024];
356\& ERR_load_crypto_strings();
357\& cbio = BIO_new_connect("localhost:http");
358\& out = BIO_new_fp(stdout, BIO_NOCLOSE);
359\& if(BIO_do_connect(cbio) <= 0) {
360\& fprintf(stderr, "Error connecting to server\en");
361\& ERR_print_errors_fp(stderr);
362\& /* whatever ... */
363\& }
364\& BIO_puts(cbio, "GET / HTTP/1.0\en\en");
365\& for(;;) {
366\& len = BIO_read(cbio, tmpbuf, 1024);
367\& if(len <= 0) break;
368\& BIO_write(out, tmpbuf, len);
369\& }
370\& BIO_free(cbio);
371\& BIO_free(out);
372.Ve
373.SH "SEE ALSO"
74dab6c2
JR
374TBA
375
376.rn }` ''
377.IX Title "BIO_s_connect 3"
378.IX Name "BIO_s_connect, BIO_set_conn_hostname, BIO_set_conn_port,
379BIO_set_conn_ip, BIO_set_conn_int_port, BIO_get_conn_hostname,
380BIO_get_conn_port, BIO_get_conn_ip, BIO_get_conn_int_port,
381BIO_set_nbio, BIO_do_connect - connect BIO"
382
383.IX Header "NAME"
384
385.IX Header "SYNOPSIS"
386
387.IX Header "DESCRIPTION"
388
389.IX Header "NOTES"
390
391.IX Header "RETURN VALUES"
392
393.IX Header "EXAMPLE"
394
984263bc 395.IX Header "SEE ALSO"
74dab6c2 396