secure/lib/libcrypto/man/BIO_s_connect.3

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  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' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  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 "2008-09-27" "0.9.8i" "OpenSSL"
 133 .SH "NAME"
 134 BIO_s_connect, BIO_set_conn_hostname, BIO_set_conn_port,
 135 BIO_set_conn_ip, BIO_set_conn_int_port, BIO_get_conn_hostname,
 136 BIO_get_conn_port, BIO_get_conn_ip, BIO_get_conn_int_port,
 137 BIO_set_nbio, BIO_do_connect \- connect BIO
 138 .SH "SYNOPSIS"
 139 .IX Header "SYNOPSIS"
 140 .Vb 1
 141 \& #include <openssl/bio.h>
 142 .Ve
 143 .PP
 144 .Vb 1
 145 \& BIO_METHOD * BIO_s_connect(void);
 146 .Ve
 147 .PP
 148 .Vb 1
 149 \& BIO *BIO_new_connect(char *name);
 150 .Ve
 151 .PP
 152 .Vb 8
 153 \& long BIO_set_conn_hostname(BIO *b, char *name);
 154 \& long BIO_set_conn_port(BIO *b, char *port);
 155 \& long BIO_set_conn_ip(BIO *b, char *ip);
 156 \& long BIO_set_conn_int_port(BIO *b, char *port);
 157 \& char *BIO_get_conn_hostname(BIO *b);
 158 \& char *BIO_get_conn_port(BIO *b);
 159 \& char *BIO_get_conn_ip(BIO *b, dummy);
 160 \& long BIO_get_conn_int_port(BIO *b, int port);
 161 .Ve
 162 .PP
 163 .Vb 1
 164 \& long BIO_set_nbio(BIO *b, long n);
 165 .Ve
 166 .PP
 167 .Vb 1
 168 \& int BIO_do_connect(BIO *b);
 169 .Ve
 170 .SH "DESCRIPTION"
 171 .IX Header "DESCRIPTION"
 172 \&\fIBIO_s_connect()\fR returns the connect \s-1BIO\s0 method. This is a wrapper
 173 round the platform's \s-1TCP/IP\s0 socket connection routines.
 174 .PP
 175 Using connect BIOs, \s-1TCP/IP\s0 connections can be made and data
 176 transferred using only \s-1BIO\s0 routines. In this way any platform
 177 specific operations are hidden by the \s-1BIO\s0 abstraction.
 178 .PP
 179 Read and write operations on a connect \s-1BIO\s0 will perform I/O
 180 on the underlying connection. If no connection is established
 181 and the port and hostname (see below) is set up properly then
 182 a connection is established first.
 183 .PP
 184 Connect BIOs support \fIBIO_puts()\fR but not \fIBIO_gets()\fR.
 185 .PP
 186 If the close flag is set on a connect \s-1BIO\s0 then any active
 187 connection is shutdown and the socket closed when the \s-1BIO\s0
 188 is freed.
 189 .PP
 190 Calling \fIBIO_reset()\fR on a connect \s-1BIO\s0 will close any active
 191 connection and reset the \s-1BIO\s0 into a state where it can connect
 192 to the same host again.
 193 .PP
 194 \&\fIBIO_get_fd()\fR places the underlying socket in \fBc\fR if it is not \s-1NULL\s0,
 195 it also returns the socket . If \fBc\fR is not \s-1NULL\s0 it should be of
 196 type (int *).
 197 .PP
 198 \&\fIBIO_set_conn_hostname()\fR uses the string \fBname\fR to set the hostname.
 199 The hostname can be an \s-1IP\s0 address. The hostname can also include the
 200 port in the form hostname:port . It is also acceptable to use the
 201 form \*(L"hostname/any/other/path\*(R" or \*(L"hostname:port/any/other/path\*(R".
 202 .PP
 203 \&\fIBIO_set_conn_port()\fR sets the port to \fBport\fR. \fBport\fR can be the
 204 numerical form or a string such as \*(L"http\*(R". A string will be looked
 205 up first using \fIgetservbyname()\fR on the host platform but if that
 206 fails a standard table of port names will be used. Currently the
 207 list is http, telnet, socks, https, ssl, ftp, gopher and wais.
 208 .PP
 209 \&\fIBIO_set_conn_ip()\fR sets the \s-1IP\s0 address to \fBip\fR using binary form,
 210 that is four bytes specifying the \s-1IP\s0 address in big-endian form.
 211 .PP
 212 \&\fIBIO_set_conn_int_port()\fR sets the port using \fBport\fR. \fBport\fR should
 213 be of type (int *).
 214 .PP
 215 \&\fIBIO_get_conn_hostname()\fR returns the hostname of the connect \s-1BIO\s0 or
 216 \&\s-1NULL\s0 if the \s-1BIO\s0 is initialized but no hostname is set.
 217 This return value is an internal pointer which should not be modified.
 218 .PP
 219 \&\fIBIO_get_conn_port()\fR returns the port as a string.
 220 .PP
 221 \&\fIBIO_get_conn_ip()\fR returns the \s-1IP\s0 address in binary form.
 222 .PP
 223 \&\fIBIO_get_conn_int_port()\fR returns the port as an int.
 224 .PP
 225 \&\fIBIO_set_nbio()\fR sets the non blocking I/O flag to \fBn\fR. If \fBn\fR is
 226 zero then blocking I/O is set. If \fBn\fR is 1 then non blocking I/O
 227 is set. Blocking I/O is the default. The call to \fIBIO_set_nbio()\fR
 228 should be made before the connection is established because
 229 non blocking I/O is set during the connect process.
 230 .PP
 231 \&\fIBIO_new_connect()\fR combines \fIBIO_new()\fR and \fIBIO_set_conn_hostname()\fR into
 232 a single call: that is it creates a new connect \s-1BIO\s0 with \fBname\fR.
 233 .PP
 234 \&\fIBIO_do_connect()\fR attempts to connect the supplied \s-1BIO\s0. It returns 1
 235 if the connection was established successfully. A zero or negative
 236 value is returned if the connection could not be established, the
 237 call \fIBIO_should_retry()\fR should be used for non blocking connect BIOs
 238 to determine if the call should be retried.
 239 .SH "NOTES"
 240 .IX Header "NOTES"
 241 If blocking I/O is set then a non positive return value from any
 242 I/O call is caused by an error condition, although a zero return
 243 will normally mean that the connection was closed.
 244 .PP
 245 If the port name is supplied as part of the host name then this will
 246 override any value set with \fIBIO_set_conn_port()\fR. This may be undesirable
 247 if the application does not wish to allow connection to arbitrary
 248 ports. This can be avoided by checking for the presence of the ':'
 249 character in the passed hostname and either indicating an error or
 250 truncating the string at that point.
 251 .PP
 252 The values returned by \fIBIO_get_conn_hostname()\fR, \fIBIO_get_conn_port()\fR,
 253 \&\fIBIO_get_conn_ip()\fR and \fIBIO_get_conn_int_port()\fR are updated when a
 254 connection attempt is made. Before any connection attempt the values
 255 returned are those set by the application itself.
 256 .PP
 257 Applications do not have to call \fIBIO_do_connect()\fR but may wish to do
 258 so to separate the connection process from other I/O processing.
 259 .PP
 260 If non blocking I/O is set then retries will be requested as appropriate.
 261 .PP
 262 It addition to \fIBIO_should_read()\fR and \fIBIO_should_write()\fR it is also
 263 possible for \fIBIO_should_io_special()\fR to be true during the initial
 264 connection process with the reason \s-1BIO_RR_CONNECT\s0. If this is returned
 265 then this is an indication that a connection attempt would block,
 266 the application should then take appropriate action to wait until
 267 the underlying socket has connected and retry the call.
 268 .PP
 269 \&\fIBIO_set_conn_hostname()\fR, \fIBIO_set_conn_port()\fR, \fIBIO_set_conn_ip()\fR,
 270 \&\fIBIO_set_conn_int_port()\fR, \fIBIO_get_conn_hostname()\fR, \fIBIO_get_conn_port()\fR,
 271 \&\fIBIO_get_conn_ip()\fR, \fIBIO_get_conn_int_port()\fR, \fIBIO_set_nbio()\fR and
 272 \&\fIBIO_do_connect()\fR are macros.
 273 .SH "RETURN VALUES"
 274 .IX Header "RETURN VALUES"
 275 \&\fIBIO_s_connect()\fR returns the connect \s-1BIO\s0 method.
 276 .PP
 277 \&\fIBIO_get_fd()\fR returns the socket or \-1 if the \s-1BIO\s0 has not
 278 been initialized.
 279 .PP
 280 \&\fIBIO_set_conn_hostname()\fR, \fIBIO_set_conn_port()\fR, \fIBIO_set_conn_ip()\fR and
 281 \&\fIBIO_set_conn_int_port()\fR always return 1.
 282 .PP
 283 \&\fIBIO_get_conn_hostname()\fR returns the connected hostname or \s-1NULL\s0 is
 284 none was set.
 285 .PP
 286 \&\fIBIO_get_conn_port()\fR returns a string representing the connected
 287 port or \s-1NULL\s0 if not set.
 288 .PP
 289 \&\fIBIO_get_conn_ip()\fR returns a pointer to the connected \s-1IP\s0 address in
 290 binary form or all zeros if not set.
 291 .PP
 292 \&\fIBIO_get_conn_int_port()\fR returns the connected port or 0 if none was
 293 set.
 294 .PP
 295 \&\fIBIO_set_nbio()\fR always returns 1.
 296 .PP
 297 \&\fIBIO_do_connect()\fR returns 1 if the connection was successfully
 298 established and 0 or \-1 if the connection failed.
 299 .SH "EXAMPLE"
 300 .IX Header "EXAMPLE"
 301 This is example connects to a webserver on the local host and attempts
 302 to retrieve a page and copy the result to standard output.
 303 .PP
 304 .Vb 19
 305 \& BIO *cbio, *out;
 306 \& int len;
 307 \& char tmpbuf[1024];
 308 \& ERR_load_crypto_strings();
 309 \& cbio = BIO_new_connect("localhost:http");
 310 \& out = BIO_new_fp(stdout, BIO_NOCLOSE);
 311 \& if(BIO_do_connect(cbio) <= 0) {
 312 \&        fprintf(stderr, "Error connecting to server\en");
 313 \&        ERR_print_errors_fp(stderr);
 314 \&        /* whatever ... */
 315 \&        }
 316 \& BIO_puts(cbio, "GET / HTTP/1.0\en\en");
 317 \& for(;;) {
 318 \&        len = BIO_read(cbio, tmpbuf, 1024);
 319 \&        if(len <= 0) break;
 320 \&        BIO_write(out, tmpbuf, len);
 321 \& }
 322 \& BIO_free(cbio);
 323 \& BIO_free(out);
 324 .Ve
 325 .SH "SEE ALSO"
 326 .IX Header "SEE ALSO"
 327 \&\s-1TBA\s0