secure/lib/libcrypto/man/BIO_s_connect.3

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