secure/lib/libcrypto/man/BIO_s_connect.3

   1 .\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.35)
   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 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  67 .\"
  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
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  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'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 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
 112 .    \" corrections for vroff
 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'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 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
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "BIO_s_connect 3"
 132 .TH BIO_s_connect 3 "2017-11-02" "1.0.2m" "OpenSSL"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 138 BIO_s_connect, BIO_new_connect, BIO_set_conn_hostname, BIO_set_conn_port,
 139 BIO_set_conn_ip, BIO_set_conn_int_port, BIO_get_conn_hostname,
 140 BIO_get_conn_port, BIO_get_conn_ip, BIO_get_conn_int_port,
 141 BIO_set_nbio, BIO_do_connect \- connect BIO
 142 .SH "SYNOPSIS"
 143 .IX Header "SYNOPSIS"
 144 .Vb 1
 145 \& #include <openssl/bio.h>
 146 \&
 147 \& BIO_METHOD * BIO_s_connect(void);
 148 \&
 149 \& BIO *BIO_new_connect(char *name);
 150 \&
 151 \& long BIO_set_conn_hostname(BIO *b, char *name);
 152 \& long BIO_set_conn_port(BIO *b, char *port);
 153 \& long BIO_set_conn_ip(BIO *b, char *ip);
 154 \& long BIO_set_conn_int_port(BIO *b, char *port);
 155 \& char *BIO_get_conn_hostname(BIO *b);
 156 \& char *BIO_get_conn_port(BIO *b);
 157 \& char *BIO_get_conn_ip(BIO *b);
 158 \& long BIO_get_conn_int_port(BIO *b);
 159 \&
 160 \& long BIO_set_nbio(BIO *b, long n);
 161 \&
 162 \& int BIO_do_connect(BIO *b);
 163 .Ve
 164 .SH "DESCRIPTION"
 165 .IX Header "DESCRIPTION"
 166 \&\fIBIO_s_connect()\fR returns the connect \s-1BIO\s0 method. This is a wrapper
 167 round the platform's \s-1TCP/IP\s0 socket connection routines.
 168 .PP
 169 Using connect BIOs, \s-1TCP/IP\s0 connections can be made and data
 170 transferred using only \s-1BIO\s0 routines. In this way any platform
 171 specific operations are hidden by the \s-1BIO\s0 abstraction.
 172 .PP
 173 Read and write operations on a connect \s-1BIO\s0 will perform I/O
 174 on the underlying connection. If no connection is established
 175 and the port and hostname (see below) is set up properly then
 176 a connection is established first.
 177 .PP
 178 Connect BIOs support \fIBIO_puts()\fR but not \fIBIO_gets()\fR.
 179 .PP
 180 If the close flag is set on a connect \s-1BIO\s0 then any active
 181 connection is shutdown and the socket closed when the \s-1BIO\s0
 182 is freed.
 183 .PP
 184 Calling \fIBIO_reset()\fR on a connect \s-1BIO\s0 will close any active
 185 connection and reset the \s-1BIO\s0 into a state where it can connect
 186 to the same host again.
 187 .PP
 188 \&\fIBIO_get_fd()\fR places the underlying socket in \fBc\fR if it is not \s-1NULL,\s0
 189 it also returns the socket . If \fBc\fR is not \s-1NULL\s0 it should be of
 190 type (int *).
 191 .PP
 192 \&\fIBIO_set_conn_hostname()\fR uses the string \fBname\fR to set the hostname.
 193 The hostname can be an \s-1IP\s0 address. The hostname can also include the
 194 port in the form hostname:port . It is also acceptable to use the
 195 form \*(L"hostname/any/other/path\*(R" or \*(L"hostname:port/any/other/path\*(R".
 196 .PP
 197 \&\fIBIO_set_conn_port()\fR sets the port to \fBport\fR. \fBport\fR can be the
 198 numerical form or a string such as \*(L"http\*(R". A string will be looked
 199 up first using \fIgetservbyname()\fR on the host platform but if that
 200 fails a standard table of port names will be used. Currently the
 201 list is http, telnet, socks, https, ssl, ftp, gopher and wais.
 202 .PP
 203 \&\fIBIO_set_conn_ip()\fR sets the \s-1IP\s0 address to \fBip\fR using binary form,
 204 that is four bytes specifying the \s-1IP\s0 address in big-endian form.
 205 .PP
 206 \&\fIBIO_set_conn_int_port()\fR sets the port using \fBport\fR. \fBport\fR should
 207 be of type (int *).
 208 .PP
 209 \&\fIBIO_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 \&\fIBIO_get_conn_port()\fR returns the port as a string.
 214 .PP
 215 \&\fIBIO_get_conn_ip()\fR returns the \s-1IP\s0 address in binary form.
 216 .PP
 217 \&\fIBIO_get_conn_int_port()\fR returns the port as an int.
 218 .PP
 219 \&\fIBIO_set_nbio()\fR sets the non blocking I/O flag to \fBn\fR. If \fBn\fR is
 220 zero then blocking I/O is set. If \fBn\fR is 1 then non blocking I/O
 221 is set. Blocking I/O is the default. The call to \fIBIO_set_nbio()\fR
 222 should be made before the connection is established because
 223 non blocking I/O is set during the connect process.
 224 .PP
 225 \&\fIBIO_new_connect()\fR combines \fIBIO_new()\fR and \fIBIO_set_conn_hostname()\fR into
 226 a single call: that is it creates a new connect \s-1BIO\s0 with \fBname\fR.
 227 .PP
 228 \&\fIBIO_do_connect()\fR attempts to connect the supplied \s-1BIO.\s0 It returns 1
 229 if the connection was established successfully. A zero or negative
 230 value is returned if the connection could not be established, the
 231 call \fIBIO_should_retry()\fR should be used for non blocking connect BIOs
 232 to determine if the call should be retried.
 233 .SH "NOTES"
 234 .IX Header "NOTES"
 235 If blocking I/O is set then a non positive return value from any
 236 I/O call is caused by an error condition, although a zero return
 237 will normally mean that the connection was closed.
 238 .PP
 239 If the port name is supplied as part of the host name then this will
 240 override any value set with \fIBIO_set_conn_port()\fR. This may be undesirable
 241 if the application does not wish to allow connection to arbitrary
 242 ports. This can be avoided by checking for the presence of the ':'
 243 character in the passed hostname and either indicating an error or
 244 truncating the string at that point.
 245 .PP
 246 The values returned by \fIBIO_get_conn_hostname()\fR, \fIBIO_get_conn_port()\fR,
 247 \&\fIBIO_get_conn_ip()\fR and \fIBIO_get_conn_int_port()\fR are updated when a
 248 connection attempt is made. Before any connection attempt the values
 249 returned are those set by the application itself.
 250 .PP
 251 Applications do not have to call \fIBIO_do_connect()\fR but may wish to do
 252 so to separate the connection process from other I/O processing.
 253 .PP
 254 If non blocking I/O is set then retries will be requested as appropriate.
 255 .PP
 256 It addition to \fIBIO_should_read()\fR and \fIBIO_should_write()\fR it is also
 257 possible for \fIBIO_should_io_special()\fR to be true during the initial
 258 connection process with the reason \s-1BIO_RR_CONNECT.\s0 If this is returned
 259 then this is an indication that a connection attempt would block,
 260 the application should then take appropriate action to wait until
 261 the underlying socket has connected and retry the call.
 262 .PP
 263 \&\fIBIO_set_conn_hostname()\fR, \fIBIO_set_conn_port()\fR, \fIBIO_set_conn_ip()\fR,
 264 \&\fIBIO_set_conn_int_port()\fR, \fIBIO_get_conn_hostname()\fR, \fIBIO_get_conn_port()\fR,
 265 \&\fIBIO_get_conn_ip()\fR, \fIBIO_get_conn_int_port()\fR, \fIBIO_set_nbio()\fR and
 266 \&\fIBIO_do_connect()\fR are macros.
 267 .SH "RETURN VALUES"
 268 .IX Header "RETURN VALUES"
 269 \&\fIBIO_s_connect()\fR returns the connect \s-1BIO\s0 method.
 270 .PP
 271 \&\fIBIO_get_fd()\fR returns the socket or \-1 if the \s-1BIO\s0 has not
 272 been initialized.
 273 .PP
 274 \&\fIBIO_set_conn_hostname()\fR, \fIBIO_set_conn_port()\fR, \fIBIO_set_conn_ip()\fR and
 275 \&\fIBIO_set_conn_int_port()\fR always return 1.
 276 .PP
 277 \&\fIBIO_get_conn_hostname()\fR returns the connected hostname or \s-1NULL\s0 is
 278 none was set.
 279 .PP
 280 \&\fIBIO_get_conn_port()\fR returns a string representing the connected
 281 port or \s-1NULL\s0 if not set.
 282 .PP
 283 \&\fIBIO_get_conn_ip()\fR returns a pointer to the connected \s-1IP\s0 address in
 284 binary form or all zeros if not set.
 285 .PP
 286 \&\fIBIO_get_conn_int_port()\fR returns the connected port or 0 if none was
 287 set.
 288 .PP
 289 \&\fIBIO_set_nbio()\fR always returns 1.
 290 .PP
 291 \&\fIBIO_do_connect()\fR returns 1 if the connection was successfully
 292 established and 0 or \-1 if the connection failed.
 293 .SH "EXAMPLE"
 294 .IX Header "EXAMPLE"
 295 This is example connects to a webserver on the local host and attempts
 296 to retrieve a page and copy the result to standard output.
 297 .PP
 298 .Vb 10
 299 \& BIO *cbio, *out;
 300 \& int len;
 301 \& char tmpbuf[1024];
 302 \& ERR_load_crypto_strings();
 303 \& cbio = BIO_new_connect("localhost:http");
 304 \& out = BIO_new_fp(stdout, BIO_NOCLOSE);
 305 \& if(BIO_do_connect(cbio) <= 0) {
 306 \&        fprintf(stderr, "Error connecting to server\en");
 307 \&        ERR_print_errors_fp(stderr);
 308 \&        /* whatever ... */
 309 \&        }
 310 \& BIO_puts(cbio, "GET / HTTP/1.0\en\en");
 311 \& for(;;) {
 312 \&        len = BIO_read(cbio, tmpbuf, 1024);
 313 \&        if(len <= 0) break;
 314 \&        BIO_write(out, tmpbuf, len);
 315 \& }
 316 \& BIO_free(cbio);
 317 \& BIO_free(out);
 318 .Ve
 319 .SH "SEE ALSO"
 320 .IX Header "SEE ALSO"
 321 \&\s-1TBA\s0