BIO_s_connect.pod revision 295016 
1=pod
2
3=head1 NAME
4
5BIO_s_connect, BIO_set_conn_hostname, BIO_set_conn_port,
6BIO_set_conn_ip, BIO_set_conn_int_port, BIO_get_conn_hostname,
7BIO_get_conn_port, BIO_get_conn_ip, BIO_get_conn_int_port,
8BIO_set_nbio, BIO_do_connect - connect BIO
9
10=head1 SYNOPSIS
11
12 #include <openssl/bio.h>
13
14 BIO_METHOD * BIO_s_connect(void);
15
16 BIO *BIO_new_connect(char *name);
17
18 long BIO_set_conn_hostname(BIO *b, char *name);
19 long BIO_set_conn_port(BIO *b, char *port);
20 long BIO_set_conn_ip(BIO *b, char *ip);
21 long BIO_set_conn_int_port(BIO *b, char *port);
22 char *BIO_get_conn_hostname(BIO *b);
23 char *BIO_get_conn_port(BIO *b);
24 char *BIO_get_conn_ip(BIO *b);
25 long BIO_get_conn_int_port(BIO *b);
26
27 long BIO_set_nbio(BIO *b, long n);
28
29 int BIO_do_connect(BIO *b);
30
31=head1 DESCRIPTION
32
33BIO_s_connect() returns the connect BIO method. This is a wrapper
34round the platform's TCP/IP socket connection routines.
35
36Using connect BIOs, TCP/IP connections can be made and data
37transferred using only BIO routines. In this way any platform
38specific operations are hidden by the BIO abstraction.
39
40Read and write operations on a connect BIO will perform I/O
41on the underlying connection. If no connection is established
42and the port and hostname (see below) is set up properly then
43a connection is established first.
44
45Connect BIOs support BIO_puts() but not BIO_gets().
46
47If the close flag is set on a connect BIO then any active
48connection is shutdown and the socket closed when the BIO
49is freed.
50
51Calling BIO_reset() on a connect BIO will close any active
52connection and reset the BIO into a state where it can connect
53to the same host again.
54
55BIO_get_fd() places the underlying socket in B<c> if it is not NULL,
56it also returns the socket . If B<c> is not NULL it should be of
57type (int *).
58
59BIO_set_conn_hostname() uses the string B<name> to set the hostname.
60The hostname can be an IP address. The hostname can also include the
61port in the form hostname:port . It is also acceptable to use the
62form "hostname/any/other/path" or "hostname:port/any/other/path".
63
64BIO_set_conn_port() sets the port to B<port>. B<port> can be the
65numerical form or a string such as "http". A string will be looked
66up first using getservbyname() on the host platform but if that
67fails a standard table of port names will be used. Currently the
68list is http, telnet, socks, https, ssl, ftp, gopher and wais.
69
70BIO_set_conn_ip() sets the IP address to B<ip> using binary form,
71that is four bytes specifying the IP address in big-endian form.
72
73BIO_set_conn_int_port() sets the port using B<port>. B<port> should
74be of type (int *).
75
76BIO_get_conn_hostname() returns the hostname of the connect BIO or
77NULL if the BIO is initialized but no hostname is set.
78This return value is an internal pointer which should not be modified.
79
80BIO_get_conn_port() returns the port as a string.
81
82BIO_get_conn_ip() returns the IP address in binary form.
83
84BIO_get_conn_int_port() returns the port as an int.
85
86BIO_set_nbio() sets the non blocking I/O flag to B<n>. If B<n> is
87zero then blocking I/O is set. If B<n> is 1 then non blocking I/O
88is set. Blocking I/O is the default. The call to BIO_set_nbio()
89should be made before the connection is established because 
90non blocking I/O is set during the connect process.
91
92BIO_new_connect() combines BIO_new() and BIO_set_conn_hostname() into
93a single call: that is it creates a new connect BIO with B<name>.
94
95BIO_do_connect() attempts to connect the supplied BIO. It returns 1
96if the connection was established successfully. A zero or negative
97value is returned if the connection could not be established, the
98call BIO_should_retry() should be used for non blocking connect BIOs
99to determine if the call should be retried.
100
101=head1 NOTES
102
103If blocking I/O is set then a non positive return value from any
104I/O call is caused by an error condition, although a zero return
105will normally mean that the connection was closed.
106
107If the port name is supplied as part of the host name then this will
108override any value set with BIO_set_conn_port(). This may be undesirable
109if the application does not wish to allow connection to arbitrary
110ports. This can be avoided by checking for the presence of the ':'
111character in the passed hostname and either indicating an error or
112truncating the string at that point.
113
114The values returned by BIO_get_conn_hostname(), BIO_get_conn_port(),
115BIO_get_conn_ip() and BIO_get_conn_int_port() are updated when a
116connection attempt is made. Before any connection attempt the values
117returned are those set by the application itself.
118
119Applications do not have to call BIO_do_connect() but may wish to do
120so to separate the connection process from other I/O processing.
121
122If non blocking I/O is set then retries will be requested as appropriate.
123
124It addition to BIO_should_read() and BIO_should_write() it is also
125possible for BIO_should_io_special() to be true during the initial
126connection process with the reason BIO_RR_CONNECT. If this is returned
127then this is an indication that a connection attempt would block,
128the application should then take appropriate action to wait until
129the underlying socket has connected and retry the call.
130
131BIO_set_conn_hostname(), BIO_set_conn_port(), BIO_set_conn_ip(),
132BIO_set_conn_int_port(), BIO_get_conn_hostname(), BIO_get_conn_port(),
133BIO_get_conn_ip(), BIO_get_conn_int_port(), BIO_set_nbio() and
134BIO_do_connect() are macros.
135
136=head1 RETURN VALUES
137
138BIO_s_connect() returns the connect BIO method.
139
140BIO_get_fd() returns the socket or -1 if the BIO has not
141been initialized.
142
143BIO_set_conn_hostname(), BIO_set_conn_port(), BIO_set_conn_ip() and
144BIO_set_conn_int_port() always return 1.
145
146BIO_get_conn_hostname() returns the connected hostname or NULL is
147none was set.
148
149BIO_get_conn_port() returns a string representing the connected
150port or NULL if not set.
151
152BIO_get_conn_ip() returns a pointer to the connected IP address in
153binary form or all zeros if not set.
154
155BIO_get_conn_int_port() returns the connected port or 0 if none was
156set.
157
158BIO_set_nbio() always returns 1.
159
160BIO_do_connect() returns 1 if the connection was successfully
161established and 0 or -1 if the connection failed.
162
163=head1 EXAMPLE
164
165This is example connects to a webserver on the local host and attempts
166to retrieve a page and copy the result to standard output.
167
168
169 BIO *cbio, *out;
170 int len;
171 char tmpbuf[1024];
172 ERR_load_crypto_strings();
173 cbio = BIO_new_connect("localhost:http");
174 out = BIO_new_fp(stdout, BIO_NOCLOSE);
175 if(BIO_do_connect(cbio) <= 0) {
176	fprintf(stderr, "Error connecting to server\n");
177	ERR_print_errors_fp(stderr);
178	/* whatever ... */
179	}
180 BIO_puts(cbio, "GET / HTTP/1.0\n\n");
181 for(;;) {	
182	len = BIO_read(cbio, tmpbuf, 1024);
183	if(len <= 0) break;
184	BIO_write(out, tmpbuf, len);
185 }
186 BIO_free(cbio);
187 BIO_free(out);
188
189
190=head1 SEE ALSO
191
192TBA
193