Merge branch 'vendor/OPENSSL'
[dragonfly.git] / secure / lib / libcrypto / man / BIO_s_connect.3
CommitLineData
aac4ff6f 1.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
8b0cefbb
JR
2.\"
3.\" Standard preamble:
4.\" ========================================================================
5.de Sh \" Subsection heading
984263bc
MD
6.br
7.if t .Sp
8.ne 5
9.PP
10\fB\\$1\fR
11.PP
12..
8b0cefbb 13.de Sp \" Vertical space (when we can't use .PP)
984263bc
MD
14.if t .sp .5v
15.if n .sp
16..
8b0cefbb 17.de Vb \" Begin verbatim text
984263bc
MD
18.ft CW
19.nf
20.ne \\$1
21..
8b0cefbb 22.de Ve \" End verbatim text
984263bc 23.ft R
984263bc
MD
24.fi
25..
8b0cefbb
JR
26.\" Set up some character translations and predefined strings. \*(-- will
27.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
aac4ff6f
PA
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
8b0cefbb 33.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
984263bc 34.ie n \{\
8b0cefbb
JR
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' ""
984263bc
MD
43'br\}
44.el\{\
8b0cefbb
JR
45. ds -- \|\(em\|
46. ds PI \(*p
47. ds L" ``
48. ds R" ''
984263bc 49'br\}
8b0cefbb
JR
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"
984263bc 58..
8b0cefbb
JR
59. nr % 0
60. rr F
984263bc 61.\}
8b0cefbb 62.\"
aac4ff6f
PA
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.\"
8b0cefbb
JR
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
984263bc 71.if n \{\
8b0cefbb
JR
72. ds #H 0
73. ds #V .8m
74. ds #F .3m
75. ds #[ \f1
76. ds #] \fP
984263bc
MD
77.\}
78.if t \{\
8b0cefbb
JR
79. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80. ds #V .6m
81. ds #F 0
82. ds #[ \&
83. ds #] \&
984263bc 84.\}
8b0cefbb 85. \" simple accents for nroff and troff
984263bc 86.if n \{\
8b0cefbb
JR
87. ds ' \&
88. ds ` \&
89. ds ^ \&
90. ds , \&
91. ds ~ ~
92. ds /
984263bc
MD
93.\}
94.if t \{\
8b0cefbb
JR
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'
984263bc 101.\}
8b0cefbb 102. \" troff and (daisy-wheel) nroff accents
984263bc
MD
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
8b0cefbb 112. \" corrections for vroff
984263bc
MD
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'
8b0cefbb 115. \" for low resolution devices (crt and lpr)
984263bc
MD
116.if \n(.H>23 .if \n(.V>19 \
117\{\
8b0cefbb
JR
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
984263bc
MD
127.\}
128.rm #[ #] #H #V #F C
8b0cefbb
JR
129.\" ========================================================================
130.\"
131.IX Title "BIO_s_connect 3"
18ed9402 132.TH BIO_s_connect 3 "2008-09-27" "0.9.8i" "OpenSSL"
984263bc
MD
133.SH "NAME"
134BIO_s_connect, BIO_set_conn_hostname, BIO_set_conn_port,
135BIO_set_conn_ip, BIO_set_conn_int_port, BIO_get_conn_hostname,
136BIO_get_conn_port, BIO_get_conn_ip, BIO_get_conn_int_port,
74dab6c2 137BIO_set_nbio, BIO_do_connect \- connect BIO
984263bc 138.SH "SYNOPSIS"
8b0cefbb 139.IX Header "SYNOPSIS"
984263bc
MD
140.Vb 1
141\& #include <openssl/bio.h>
aac4ff6f
PA
142.Ve
143.PP
144.Vb 1
984263bc 145\& BIO_METHOD * BIO_s_connect(void);
aac4ff6f
PA
146.Ve
147.PP
148.Vb 1
984263bc 149\& BIO *BIO_new_connect(char *name);
aac4ff6f
PA
150.Ve
151.PP
152.Vb 8
984263bc
MD
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);
aac4ff6f
PA
161.Ve
162.PP
163.Vb 1
984263bc 164\& long BIO_set_nbio(BIO *b, long n);
aac4ff6f
PA
165.Ve
166.PP
167.Vb 1
984263bc
MD
168\& int BIO_do_connect(BIO *b);
169.Ve
170.SH "DESCRIPTION"
8b0cefbb
JR
171.IX Header "DESCRIPTION"
172\&\fIBIO_s_connect()\fR returns the connect \s-1BIO\s0 method. This is a wrapper
173round the platform's \s-1TCP/IP\s0 socket connection routines.
984263bc 174.PP
8b0cefbb
JR
175Using connect BIOs, \s-1TCP/IP\s0 connections can be made and data
176transferred using only \s-1BIO\s0 routines. In this way any platform
177specific operations are hidden by the \s-1BIO\s0 abstraction.
984263bc 178.PP
8b0cefbb 179Read and write operations on a connect \s-1BIO\s0 will perform I/O
984263bc
MD
180on the underlying connection. If no connection is established
181and the port and hostname (see below) is set up properly then
182a connection is established first.
183.PP
184Connect BIOs support \fIBIO_puts()\fR but not \fIBIO_gets()\fR.
185.PP
8b0cefbb
JR
186If the close flag is set on a connect \s-1BIO\s0 then any active
187connection is shutdown and the socket closed when the \s-1BIO\s0
984263bc
MD
188is freed.
189.PP
8b0cefbb
JR
190Calling \fIBIO_reset()\fR on a connect \s-1BIO\s0 will close any active
191connection and reset the \s-1BIO\s0 into a state where it can connect
984263bc
MD
192to the same host again.
193.PP
8b0cefbb
JR
194\&\fIBIO_get_fd()\fR places the underlying socket in \fBc\fR if it is not \s-1NULL\s0,
195it also returns the socket . If \fBc\fR is not \s-1NULL\s0 it should be of
984263bc
MD
196type (int *).
197.PP
8b0cefbb
JR
198\&\fIBIO_set_conn_hostname()\fR uses the string \fBname\fR to set the hostname.
199The hostname can be an \s-1IP\s0 address. The hostname can also include the
984263bc
MD
200port in the form hostname:port . It is also acceptable to use the
201form \*(L"hostname/any/other/path\*(R" or \*(L"hostname:port/any/other/path\*(R".
202.PP
8b0cefbb 203\&\fIBIO_set_conn_port()\fR sets the port to \fBport\fR. \fBport\fR can be the
984263bc
MD
204numerical form or a string such as \*(L"http\*(R". A string will be looked
205up first using \fIgetservbyname()\fR on the host platform but if that
206fails a standard table of port names will be used. Currently the
207list is http, telnet, socks, https, ssl, ftp, gopher and wais.
208.PP
8b0cefbb
JR
209\&\fIBIO_set_conn_ip()\fR sets the \s-1IP\s0 address to \fBip\fR using binary form,
210that is four bytes specifying the \s-1IP\s0 address in big-endian form.
984263bc 211.PP
8b0cefbb 212\&\fIBIO_set_conn_int_port()\fR sets the port using \fBport\fR. \fBport\fR should
984263bc
MD
213be of type (int *).
214.PP
8b0cefbb
JR
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.
984263bc
MD
217This return value is an internal pointer which should not be modified.
218.PP
8b0cefbb 219\&\fIBIO_get_conn_port()\fR returns the port as a string.
984263bc 220.PP
8b0cefbb 221\&\fIBIO_get_conn_ip()\fR returns the \s-1IP\s0 address in binary form.
984263bc 222.PP
8b0cefbb 223\&\fIBIO_get_conn_int_port()\fR returns the port as an int.
984263bc 224.PP
8b0cefbb 225\&\fIBIO_set_nbio()\fR sets the non blocking I/O flag to \fBn\fR. If \fBn\fR is
984263bc
MD
226zero then blocking I/O is set. If \fBn\fR is 1 then non blocking I/O
227is set. Blocking I/O is the default. The call to \fIBIO_set_nbio()\fR
228should be made before the connection is established because
229non blocking I/O is set during the connect process.
230.PP
8b0cefbb
JR
231\&\fIBIO_new_connect()\fR combines \fIBIO_new()\fR and \fIBIO_set_conn_hostname()\fR into
232a single call: that is it creates a new connect \s-1BIO\s0 with \fBname\fR.
984263bc 233.PP
8b0cefbb 234\&\fIBIO_do_connect()\fR attempts to connect the supplied \s-1BIO\s0. It returns 1
984263bc
MD
235if the connection was established successfully. A zero or negative
236value is returned if the connection could not be established, the
237call \fIBIO_should_retry()\fR should be used for non blocking connect BIOs
238to determine if the call should be retried.
239.SH "NOTES"
8b0cefbb 240.IX Header "NOTES"
984263bc
MD
241If blocking I/O is set then a non positive return value from any
242I/O call is caused by an error condition, although a zero return
243will normally mean that the connection was closed.
244.PP
245If the port name is supplied as part of the host name then this will
246override any value set with \fIBIO_set_conn_port()\fR. This may be undesirable
247if the application does not wish to allow connection to arbitrary
8b0cefbb 248ports. This can be avoided by checking for the presence of the ':'
984263bc
MD
249character in the passed hostname and either indicating an error or
250truncating the string at that point.
251.PP
252The values returned by \fIBIO_get_conn_hostname()\fR, \fIBIO_get_conn_port()\fR,
8b0cefbb 253\&\fIBIO_get_conn_ip()\fR and \fIBIO_get_conn_int_port()\fR are updated when a
984263bc
MD
254connection attempt is made. Before any connection attempt the values
255returned are those set by the application itself.
256.PP
257Applications do not have to call \fIBIO_do_connect()\fR but may wish to do
258so to separate the connection process from other I/O processing.
259.PP
260If non blocking I/O is set then retries will be requested as appropriate.
261.PP
262It addition to \fIBIO_should_read()\fR and \fIBIO_should_write()\fR it is also
263possible for \fIBIO_should_io_special()\fR to be true during the initial
8b0cefbb 264connection process with the reason \s-1BIO_RR_CONNECT\s0. If this is returned
984263bc
MD
265then this is an indication that a connection attempt would block,
266the application should then take appropriate action to wait until
267the underlying socket has connected and retry the call.
268.PP
8b0cefbb
JR
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.
984263bc 273.SH "RETURN VALUES"
8b0cefbb
JR
274.IX Header "RETURN VALUES"
275\&\fIBIO_s_connect()\fR returns the connect \s-1BIO\s0 method.
984263bc 276.PP
8b0cefbb 277\&\fIBIO_get_fd()\fR returns the socket or \-1 if the \s-1BIO\s0 has not
984263bc
MD
278been initialized.
279.PP
8b0cefbb
JR
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.
984263bc 282.PP
8b0cefbb 283\&\fIBIO_get_conn_hostname()\fR returns the connected hostname or \s-1NULL\s0 is
984263bc
MD
284none was set.
285.PP
8b0cefbb
JR
286\&\fIBIO_get_conn_port()\fR returns a string representing the connected
287port or \s-1NULL\s0 if not set.
984263bc 288.PP
8b0cefbb 289\&\fIBIO_get_conn_ip()\fR returns a pointer to the connected \s-1IP\s0 address in
984263bc
MD
290binary form or all zeros if not set.
291.PP
8b0cefbb 292\&\fIBIO_get_conn_int_port()\fR returns the connected port or 0 if none was
984263bc
MD
293set.
294.PP
8b0cefbb 295\&\fIBIO_set_nbio()\fR always returns 1.
984263bc 296.PP
8b0cefbb 297\&\fIBIO_do_connect()\fR returns 1 if the connection was successfully
984263bc
MD
298established and 0 or \-1 if the connection failed.
299.SH "EXAMPLE"
8b0cefbb 300.IX Header "EXAMPLE"
984263bc
MD
301This is example connects to a webserver on the local host and attempts
302to retrieve a page and copy the result to standard output.
303.PP
aac4ff6f 304.Vb 19
984263bc
MD
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);
324.Ve
325.SH "SEE ALSO"
326.IX Header "SEE ALSO"
8b0cefbb 327\&\s-1TBA\s0