secure/lib/libcrypto/man/man3/BIO_s_connect.3

   1 .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  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-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  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' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "BIO_S_CONNECT 3"
 136 .TH BIO_S_CONNECT 3 "2022-05-03" "1.1.1o" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 BIO_set_conn_address, BIO_get_conn_address, BIO_s_connect, BIO_new_connect, BIO_set_conn_hostname, BIO_set_conn_port, BIO_set_conn_ip_family, BIO_get_conn_ip_family, BIO_get_conn_hostname, BIO_get_conn_port, BIO_set_nbio, BIO_do_connect \- connect BIO
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/bio.h>
 147 \&
 148 \& const BIO_METHOD * BIO_s_connect(void);
 149 \&
 150 \& BIO *BIO_new_connect(char *name);
 151 \&
 152 \& long BIO_set_conn_hostname(BIO *b, char *name);
 153 \& long BIO_set_conn_port(BIO *b, char *port);
 154 \& long BIO_set_conn_address(BIO *b, BIO_ADDR *addr);
 155 \& long BIO_set_conn_ip_family(BIO *b, long family);
 156 \& const char *BIO_get_conn_hostname(BIO *b);
 157 \& const char *BIO_get_conn_port(BIO *b);
 158 \& const BIO_ADDR *BIO_get_conn_address(BIO *b);
 159 \& const long BIO_get_conn_ip_family(BIO *b);
 160 \&
 161 \& long BIO_set_nbio(BIO *b, long n);
 162 \&
 163 \& int BIO_do_connect(BIO *b);
 164 .Ve
 165 .SH "DESCRIPTION"
 166 .IX Header "DESCRIPTION"
 167 \&\fBBIO_s_connect()\fR returns the connect \s-1BIO\s0 method. This is a wrapper
 168 round the platform's \s-1TCP/IP\s0 socket connection routines.
 169 .PP
 170 Using connect BIOs, \s-1TCP/IP\s0 connections can be made and data
 171 transferred using only \s-1BIO\s0 routines. In this way any platform
 172 specific operations are hidden by the \s-1BIO\s0 abstraction.
 173 .PP
 174 Read and write operations on a connect \s-1BIO\s0 will perform I/O
 175 on the underlying connection. If no connection is established
 176 and the port and hostname (see below) is set up properly then
 177 a connection is established first.
 178 .PP
 179 Connect BIOs support \fBBIO_puts()\fR but not \fBBIO_gets()\fR.
 180 .PP
 181 If the close flag is set on a connect \s-1BIO\s0 then any active
 182 connection is shutdown and the socket closed when the \s-1BIO\s0
 183 is freed.
 184 .PP
 185 Calling \fBBIO_reset()\fR on a connect \s-1BIO\s0 will close any active
 186 connection and reset the \s-1BIO\s0 into a state where it can connect
 187 to the same host again.
 188 .PP
 189 \&\fBBIO_get_fd()\fR places the underlying socket in \fBc\fR if it is not \s-1NULL,\s0
 190 it also returns the socket . If \fBc\fR is not \s-1NULL\s0 it should be of
 191 type (int *).
 192 .PP
 193 \&\fBBIO_set_conn_hostname()\fR uses the string \fBname\fR to set the hostname.
 194 The hostname can be an \s-1IP\s0 address; if the address is an IPv6 one, it
 195 must be enclosed with brackets. The hostname can also include the
 196 port in the form hostname:port.
 197 .PP
 198 \&\fBBIO_set_conn_port()\fR sets the port to \fBport\fR. \fBport\fR can be the
 199 numerical form or a string such as \*(L"http\*(R". A string will be looked
 200 up first using \fBgetservbyname()\fR on the host platform but if that
 201 fails a standard table of port names will be used. This internal
 202 list is http, telnet, socks, https, ssl, ftp, and gopher.
 203 .PP
 204 \&\fBBIO_set_conn_address()\fR sets the address and port information using
 205 a \s-1\fBBIO_ADDR\s0\fR\|(3ssl).
 206 .PP
 207 \&\fBBIO_set_conn_ip_family()\fR sets the \s-1IP\s0 family.
 208 .PP
 209 \&\fBBIO_get_conn_hostname()\fR returns the hostname of the connect \s-1BIO\s0 or
 210 \&\s-1NULL\s0 if the \s-1BIO\s0 is initialized but no hostname is set.
 211 This return value is an internal pointer which should not be modified.
 212 .PP
 213 \&\fBBIO_get_conn_port()\fR returns the port as a string.
 214 This return value is an internal pointer which should not be modified.
 215 .PP
 216 \&\fBBIO_get_conn_address()\fR returns the address information as a \s-1BIO_ADDR.\s0
 217 This return value is an internal pointer which should not be modified.
 218 .PP
 219 \&\fBBIO_get_conn_ip_family()\fR returns the \s-1IP\s0 family of the connect \s-1BIO.\s0
 220 .PP
 221 \&\fBBIO_set_nbio()\fR sets the non blocking I/O flag to \fBn\fR. If \fBn\fR is
 222 zero then blocking I/O is set. If \fBn\fR is 1 then non blocking I/O
 223 is set. Blocking I/O is the default. The call to \fBBIO_set_nbio()\fR
 224 should be made before the connection is established because
 225 non blocking I/O is set during the connect process.
 226 .PP
 227 \&\fBBIO_new_connect()\fR combines \fBBIO_new()\fR and \fBBIO_set_conn_hostname()\fR into
 228 a single call: that is it creates a new connect \s-1BIO\s0 with \fBname\fR.
 229 .PP
 230 \&\fBBIO_do_connect()\fR attempts to connect the supplied \s-1BIO.\s0 It returns 1
 231 if the connection was established successfully. A zero or negative
 232 value is returned if the connection could not be established, the
 233 call \fBBIO_should_retry()\fR should be used for non blocking connect BIOs
 234 to determine if the call should be retried.
 235 .SH "NOTES"
 236 .IX Header "NOTES"
 237 If blocking I/O is set then a non positive return value from any
 238 I/O call is caused by an error condition, although a zero return
 239 will normally mean that the connection was closed.
 240 .PP
 241 If the port name is supplied as part of the hostname then this will
 242 override any value set with \fBBIO_set_conn_port()\fR. This may be undesirable
 243 if the application does not wish to allow connection to arbitrary
 244 ports. This can be avoided by checking for the presence of the ':'
 245 character in the passed hostname and either indicating an error or
 246 truncating the string at that point.
 247 .PP
 248 The values returned by \fBBIO_get_conn_hostname()\fR, \fBBIO_get_conn_address()\fR,
 249 and \fBBIO_get_conn_port()\fR are updated when a connection attempt is made.
 250 Before any connection attempt the values returned are those set by the
 251 application itself.
 252 .PP
 253 Applications do not have to call \fBBIO_do_connect()\fR but may wish to do
 254 so to separate the connection process from other I/O processing.
 255 .PP
 256 If non blocking I/O is set then retries will be requested as appropriate.
 257 .PP
 258 It addition to \fBBIO_should_read()\fR and \fBBIO_should_write()\fR it is also
 259 possible for \fBBIO_should_io_special()\fR to be true during the initial
 260 connection process with the reason \s-1BIO_RR_CONNECT.\s0 If this is returned
 261 then this is an indication that a connection attempt would block,
 262 the application should then take appropriate action to wait until
 263 the underlying socket has connected and retry the call.
 264 .PP
 265 \&\fBBIO_set_conn_hostname()\fR, \fBBIO_set_conn_port()\fR, \fBBIO_get_conn_hostname()\fR,
 266 \&\fBBIO_set_conn_address()\fR, \fBBIO_get_conn_port()\fR, \fBBIO_get_conn_address()\fR,
 267 \&\fBBIO_set_conn_ip_family()\fR, \fBBIO_get_conn_ip_family()\fR,
 268 \&\fBBIO_set_nbio()\fR, and \fBBIO_do_connect()\fR are macros.
 269 .SH "RETURN VALUES"
 270 .IX Header "RETURN VALUES"
 271 \&\fBBIO_s_connect()\fR returns the connect \s-1BIO\s0 method.
 272 .PP
 273 \&\fBBIO_get_fd()\fR returns the socket or \-1 if the \s-1BIO\s0 has not
 274 been initialized.
 275 .PP
 276 \&\fBBIO_set_conn_address()\fR, \fBBIO_set_conn_port()\fR, and \fBBIO_set_conn_ip_family()\fR
 277 always return 1.
 278 .PP
 279 \&\fBBIO_set_conn_hostname()\fR returns 1 on success and 0 on failure.
 280 .PP
 281 \&\fBBIO_get_conn_address()\fR returns the address information or \s-1NULL\s0 if none
 282 was set.
 283 .PP
 284 \&\fBBIO_get_conn_hostname()\fR returns the connected hostname or \s-1NULL\s0 if
 285 none was set.
 286 .PP
 287 \&\fBBIO_get_conn_ip_family()\fR returns the address family or \-1 if none was set.
 288 .PP
 289 \&\fBBIO_get_conn_port()\fR returns a string representing the connected
 290 port or \s-1NULL\s0 if not set.
 291 .PP
 292 \&\fBBIO_set_nbio()\fR always returns 1.
 293 .PP
 294 \&\fBBIO_do_connect()\fR returns 1 if the connection was successfully
 295 established and 0 or \-1 if the connection failed.
 296 .SH "EXAMPLES"
 297 .IX Header "EXAMPLES"
 298 This is example connects to a webserver on the local host and attempts
 299 to retrieve a page and copy the result to standard output.
 300 .PP
 301 .Vb 3
 302 \& BIO *cbio, *out;
 303 \& int len;
 304 \& char tmpbuf[1024];
 305 \&
 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 \&     exit(1);
 312 \& }
 313 \& BIO_puts(cbio, "GET / HTTP/1.0\en\en");
 314 \& for (;;) {
 315 \&     len = BIO_read(cbio, tmpbuf, 1024);
 316 \&     if (len <= 0)
 317 \&         break;
 318 \&     BIO_write(out, tmpbuf, len);
 319 \& }
 320 \& BIO_free(cbio);
 321 \& BIO_free(out);
 322 .Ve
 323 .SH "SEE ALSO"
 324 .IX Header "SEE ALSO"
 325 \&\s-1\fBBIO_ADDR\s0\fR\|(3)
 326 .SH "HISTORY"
 327 .IX Header "HISTORY"
 328 \&\fBBIO_set_conn_int_port()\fR, \fBBIO_get_conn_int_port()\fR, \fBBIO_set_conn_ip()\fR, and \fBBIO_get_conn_ip()\fR
 329 were removed in OpenSSL 1.1.0.
 330 Use \fBBIO_set_conn_address()\fR and \fBBIO_get_conn_address()\fR instead.
 331 .SH "COPYRIGHT"
 332 .IX Header "COPYRIGHT"
 333 Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved.
 334 .PP
 335 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 336 this file except in compliance with the License.  You can obtain a copy
 337 in the file \s-1LICENSE\s0 in the source distribution or at
 338 <https://www.openssl.org/source/license.html>.