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