Debian Codegraph @

upstream/debian-unstable/man3/BIO_s_connect.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "BIO_S_CONNECT 3SSL"
58 .TH BIO_S_CONNECT 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 BIO_s_connect, BIO_new_connect,
65 BIO_set_conn_hostname, BIO_set_conn_port,
66 BIO_set_conn_address, BIO_set_conn_ip_family,
67 BIO_get_conn_hostname, BIO_get_conn_port,
68 BIO_get_conn_address, BIO_get_conn_ip_family,
69 BIO_set_nbio, BIO_set_sock_type, BIO_get_sock_type, BIO_get0_dgram_bio,
70 BIO_do_connect \- connect BIO
71 .SH SYNOPSIS
72 .IX Header "SYNOPSIS"
73 .Vb 1
74 \& #include <openssl/bio.h>
75 \&
76 \& const BIO_METHOD *BIO_s_connect(void);
77 \&
78 \& BIO *BIO_new_connect(const char *name);
79 \&
80 \& long BIO_set_conn_hostname(BIO *b, char *name);
81 \& long BIO_set_conn_port(BIO *b, char *port);
82 \& long BIO_set_conn_address(BIO *b, BIO_ADDR *addr);
83 \& long BIO_set_conn_ip_family(BIO *b, long family);
84 \& const char *BIO_get_conn_hostname(BIO *b);
85 \& const char *BIO_get_conn_port(BIO *b);
86 \& const BIO_ADDR *BIO_get_conn_address(BIO *b);
87 \& const long BIO_get_conn_ip_family(BIO *b);
88 \&
89 \& long BIO_set_nbio(BIO *b, long n);
90 \&
91 \& int BIO_set_sock_type(BIO *b, int sock_type);
92 \& int BIO_get_sock_type(BIO *b);
93 \& int BIO_get0_dgram_bio(BIO *B, BIO **dgram_bio);
94 \&
95 \& long BIO_do_connect(BIO *b);
96 .Ve
97 .SH DESCRIPTION
98 .IX Header "DESCRIPTION"
99 \&\fBBIO_s_connect()\fR returns the connect BIO method. This is a wrapper
100 round the platform's TCP/IP socket connection routines.
101 .PP
102 Using connect BIOs, TCP/IP connections can be made and data
103 transferred using only BIO routines. In this way any platform
104 specific operations are hidden by the BIO abstraction.
105 .PP
106 Read and write operations on a connect BIO will perform I/O
107 on the underlying connection. If no connection is established
108 and the port and hostname (see below) is set up properly then
109 a connection is established first.
110 .PP
111 Connect BIOs support \fBBIO_puts()\fR and \fBBIO_gets()\fR.
112 .PP
113 If the close flag is set on a connect BIO then any active
114 connection is shutdown and the socket closed when the BIO
115 is freed.
116 .PP
117 Calling \fBBIO_reset()\fR on a connect BIO will close any active
118 connection and reset the BIO into a state where it can connect
119 to the same host again.
120 .PP
121 \&\fBBIO_new_connect()\fR combines \fBBIO_new()\fR and \fBBIO_set_conn_hostname()\fR into
122 a single call: that is it creates a new connect BIO with hostname \fBname\fR.
123 .PP
124 \&\fBBIO_set_conn_hostname()\fR uses the string \fBname\fR to set the hostname.
125 The hostname can be an IP address; if the address is an IPv6 one, it
126 must be enclosed in brackets \f(CW\*(C`[\*(C'\fR and \f(CW\*(C`]\*(C'\fR.
127 The hostname can also include the port in the form hostname:port;
128 see \fBBIO_parse_hostserv\fR\|(3) and \fBBIO_set_conn_port()\fR for details.
129 .PP
130 \&\fBBIO_set_conn_port()\fR sets the port to \fBport\fR. \fBport\fR can be the
131 numerical form or a service string such as "http", which
132 will be mapped to a port number using the system function \fBgetservbyname()\fR.
133 .PP
134 \&\fBBIO_set_conn_address()\fR sets the address and port information using
135 a \fBBIO_ADDR\fR\|(3ssl).
136 .PP
137 \&\fBBIO_set_conn_ip_family()\fR sets the IP family.
138 .PP
139 \&\fBBIO_get_conn_hostname()\fR returns the hostname of the connect BIO or
140 NULL if the BIO is initialized but no hostname is set.
141 This return value is an internal pointer which should not be modified.
142 .PP
143 \&\fBBIO_get_conn_port()\fR returns the port as a string.
144 This return value is an internal pointer which should not be modified.
145 .PP
146 \&\fBBIO_get_conn_address()\fR returns the address information as a BIO_ADDR.
147 This return value is an internal pointer which should not be modified.
148 .PP
149 \&\fBBIO_get_conn_ip_family()\fR returns the IP family of the connect BIO.
150 .PP
151 \&\fBBIO_set_nbio()\fR sets the non blocking I/O flag to \fBn\fR. If \fBn\fR is
152 zero then blocking I/O is set. If \fBn\fR is 1 then non blocking I/O
153 is set. Blocking I/O is the default. The call to \fBBIO_set_nbio()\fR
154 should be made before the connection is established because
155 non blocking I/O is set during the connect process.
156 .PP
157 \&\fBBIO_do_connect()\fR attempts to connect the supplied BIO.
158 This performs an SSL/TLS handshake as far as supported by the BIO.
159 For non-SSL BIOs the connection is done typically at TCP level.
160 If domain name resolution yields multiple IP addresses all of them are tried
161 after \fBconnect()\fR failures.
162 The function returns 1 if the connection was established successfully.
163 A zero or negative value is returned if the connection could not be established.
164 The call \fBBIO_should_retry()\fR should be used for non blocking connect BIOs
165 to determine if the call should be retried.
166 If a connection has already been established this call has no effect.
167 .PP
168 \&\fBBIO_set_sock_type()\fR can be used to set a socket type value as would be passed in
169 a call to \fBsocket\fR\|(2). The only currently supported values are \fBSOCK_STREAM\fR (the
170 default) and \fBSOCK_DGRAM\fR. If \fBSOCK_DGRAM\fR is configured, the connection
171 created is a UDP datagram socket handled via \fBBIO_s_datagram\fR\|(3).
172 I/O calls such as \fBBIO_read\fR\|(3) and \fBBIO_write\fR\|(3) are forwarded transparently
173 to an internal \fBBIO_s_datagram\fR\|(3) instance. The created \fBBIO_s_datagram\fR\|(3)
174 instance can be retrieved using \fBBIO_get0_dgram_bio()\fR if desired, which writes
175 a pointer to the \fBBIO_s_datagram\fR\|(3) instance to \fI*dgram_bio\fR. The lifetime
176 of the internal \fBBIO_s_datagram\fR\|(3) is managed by \fBBIO_s_connect()\fR and does not
177 need to be freed by the caller.
178 .PP
179 \&\fBBIO_get_sock_type()\fR retrieves the value set using \fBBIO_set_sock_type()\fR.
180 .SH NOTES
181 .IX Header "NOTES"
182 If blocking I/O is set then a non positive return value from any
183 I/O call is caused by an error condition, although a zero return
184 will normally mean that the connection was closed.
185 .PP
186 If the port name is supplied as part of the hostname then this will
187 override any value set with \fBBIO_set_conn_port()\fR. This may be undesirable
188 if the application does not wish to allow connection to arbitrary
189 ports. This can be avoided by checking for the presence of the ':'
190 character in the passed hostname and either indicating an error or
191 truncating the string at that point.
192 .PP
193 The values returned by \fBBIO_get_conn_hostname()\fR, \fBBIO_get_conn_address()\fR,
194 and \fBBIO_get_conn_port()\fR are updated when a connection attempt is made.
195 Before any connection attempt the values returned are those set by the
196 application itself.
197 .PP
198 Applications do not have to call \fBBIO_do_connect()\fR but may wish to do
199 so to separate the connection process from other I/O processing.
200 .PP
201 If non blocking I/O is set then retries will be requested as appropriate.
202 .PP
203 It addition to \fBBIO_should_read()\fR and \fBBIO_should_write()\fR it is also
204 possible for \fBBIO_should_io_special()\fR to be true during the initial
205 connection process with the reason BIO_RR_CONNECT. If this is returned
206 then this is an indication that a connection attempt would block,
207 the application should then take appropriate action to wait until
208 the underlying socket has connected and retry the call.
209 .PP
210 \&\fBBIO_set_conn_hostname()\fR, \fBBIO_set_conn_port()\fR, \fBBIO_get_conn_hostname()\fR,
211 \&\fBBIO_set_conn_address()\fR, \fBBIO_get_conn_port()\fR, \fBBIO_get_conn_address()\fR,
212 \&\fBBIO_set_conn_ip_family()\fR, \fBBIO_get_conn_ip_family()\fR,
213 \&\fBBIO_set_nbio()\fR, and \fBBIO_do_connect()\fR are macros.
214 .SH "RETURN VALUES"
215 .IX Header "RETURN VALUES"
216 \&\fBBIO_s_connect()\fR returns the connect BIO method.
217 .PP
218 \&\fBBIO_set_conn_address()\fR, \fBBIO_set_conn_port()\fR, and \fBBIO_set_conn_ip_family()\fR
219 return 1 or <=0 if an error occurs.
220 .PP
221 \&\fBBIO_set_conn_hostname()\fR returns 1 on success and <=0 on failure.
222 .PP
223 \&\fBBIO_get_conn_address()\fR returns the address information or NULL if none
224 was set.
225 .PP
226 \&\fBBIO_get_conn_hostname()\fR returns the connected hostname or NULL if
227 none was set.
228 .PP
229 \&\fBBIO_get_conn_ip_family()\fR returns the address family or \-1 if none was set.
230 .PP
231 \&\fBBIO_get_conn_port()\fR returns a string representing the connected
232 port or NULL if not set.
233 .PP
234 \&\fBBIO_set_nbio()\fR returns 1 or <=0 if an error occurs.
235 .PP
236 \&\fBBIO_do_connect()\fR returns 1 if the connection was successfully
237 established and <=0 if the connection failed.
238 .PP
239 \&\fBBIO_set_sock_type()\fR returns 1 on success or 0 on failure.
240 .PP
241 \&\fBBIO_get_sock_type()\fR returns a socket type or 0 if the call is not supported.
242 .PP
243 \&\fBBIO_get0_dgram_bio()\fR returns 1 on success or 0 on failure.
244 .SH EXAMPLES
245 .IX Header "EXAMPLES"
246 This is example connects to a webserver on the local host and attempts
247 to retrieve a page and copy the result to standard output.
248 .PP
249 .Vb 3
250 \& BIO *cbio, *out;
251 \& int len;
252 \& char tmpbuf[1024];
253 \&
254 \& cbio = BIO_new_connect("localhost:http");
255 \& out = BIO_new_fp(stdout, BIO_NOCLOSE);
256 \& if (BIO_do_connect(cbio) <= 0) {
257 \& fprintf(stderr, "Error connecting to server\en");
258 \& ERR_print_errors_fp(stderr);
259 \& exit(1);
260 \& }
261 \& BIO_puts(cbio, "GET / HTTP/1.0\en\en");
262 \& for (;;) {
263 \& len = BIO_read(cbio, tmpbuf, 1024);
264 \& if (len <= 0)
265 \& break;
266 \& BIO_write(out, tmpbuf, len);
267 \& }
268 \& BIO_free(cbio);
269 \& BIO_free(out);
270 .Ve
271 .SH "SEE ALSO"
272 .IX Header "SEE ALSO"
273 \&\fBBIO_ADDR\fR\|(3), \fBBIO_parse_hostserv\fR\|(3)
274 .SH HISTORY
275 .IX Header "HISTORY"
276 \&\fBBIO_set_conn_int_port()\fR, \fBBIO_get_conn_int_port()\fR, \fBBIO_set_conn_ip()\fR, and \fBBIO_get_conn_ip()\fR
277 were removed in OpenSSL 1.1.0.
278 Use \fBBIO_set_conn_address()\fR and \fBBIO_get_conn_address()\fR instead.
279 .PP
280 Connect BIOs support \fBBIO_gets()\fR, \fBBIO_get0_dgram_bio()\fR, \fBBIO_get_sock_type()\fR,
281 \&\fBBIO_set_sock_type()\fR were added in OpenSSL 3.2.
282 .SH COPYRIGHT
283 .IX Header "COPYRIGHT"
284 Copyright 2000\-2025 The OpenSSL Project Authors. All Rights Reserved.
285 .PP
286 Licensed under the Apache License 2.0 (the "License"). You may not use
287 this file except in compliance with the License. You can obtain a copy
288 in the file LICENSE in the source distribution or at
289 <https://www.openssl.org/source/license.html>.