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