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