BIO_S_CONNECT(3SSL)

📦

version 4.0.3 · 14 versions

💅 BIO_S_CONNECT 💅

okay bestie, gather round, because this is the connect BIO page from OpenSSL and it's genuinely iconic. it's in section 3SSL of the OpenSSL manual, and it's literally all about making TCP/IP connections with nothing but BIO routines. no cap. 🫶

✨ NAME ✨

BIO_s_connect, BIO_new_connect, BIO_set_conn_hostname, BIO_set_conn_port, BIO_set_conn_address, BIO_set_conn_ip_family, BIO_get_conn_hostname, BIO_get_conn_port, BIO_get_conn_address, BIO_get_conn_ip_family, BIO_set_nbio, BIO_set_sock_type, BIO_get_sock_type, BIO_get0_dgram_bio, BIO_do_connect — aka the connect BIO 🌈

🌸 SYNOPSIS 🌸

#include <openssl/bio.h>

const BIO_METHOD *BIO_s_connect(void);

BIO *BIO_new_connect(const char *name);

long BIO_set_conn_hostname(BIO *b, char *name);
long BIO_set_conn_port(BIO *b, char *port);
long BIO_set_conn_address(BIO *b, BIO_ADDR *addr);
long BIO_set_conn_ip_family(BIO *b, long family);
const char *BIO_get_conn_hostname(BIO *b);
const char *BIO_get_conn_port(BIO *b);
const BIO_ADDR *BIO_get_conn_address(BIO *b);
const long BIO_get_conn_ip_family(BIO *b);

long BIO_set_nbio(BIO *b, long n);

int BIO_set_sock_type(BIO *b, int sock_type);
int BIO_get_sock_type(BIO *b);
int BIO_get0_dgram_bio(BIO *B, BIO **dgram_bio);

long BIO_do_connect(BIO *b);

💖 DESCRIPTION 💖

so BIO_s_connect() hands you the connect BIO method. it's basically a little wrapper round your platform's TCP/IP socket connection routines. 🎀

the whole vibe: with connect BIOs you can make TCP/IP connections and move data around using only BIO routines. every platform-specific operation gets hidden behind the BIO abstraction, which is the moment honestly, main character energy. ✨

read and write operations on a connect BIO do I/O on the underlying connection. and if there's no connection yet but the port and hostname are set up properly (more on those below), then a connection gets established first. it's giving "i got you, bestie". 🦋

connect BIOs support BIO_puts() and BIO_gets(). periodt.

if the close flag is set on a connect BIO, then any active connection gets shut down and the socket closed when the BIO is freed. 💀

calling BIO_reset() on a connect BIO closes any active connection and resets the BIO into a state where it can connect to the same host again. reusing, recycling, sustainable queen. 👑

BIO_new_connect() is just BIO_new() and BIO_set_conn_hostname() combined into one single call — it creates a brand new connect BIO with hostname name. two birds, one slay. 🌸

BIO_set_conn_hostname() uses the string name to set the hostname. the hostname can be an IP address, and if that address is an IPv6 one it must be enclosed in brackets [ and ]. the hostname can also include the port in the form hostname:port; go peep BIO_parse_hostserv(3) and BIO_set_conn_port() for the details.

BIO_set_conn_port() sets the port to port. port can be the numerical form, or a service string like "http", which gets mapped to a port number using the system function getservbyname(). iconic.

BIO_set_conn_address() sets the address and port information using a BIO_ADDR(3ssl).

BIO_set_conn_ip_family() sets the IP family.

BIO_get_conn_hostname() returns the hostname of the connect BIO, or NULL if the BIO is initialized but no hostname is set. careful bestie — this return value is an internal pointer which should not be modified. 🙈

BIO_get_conn_port() returns the port as a string. also an internal pointer, also should not be modified. hands off, queen.

BIO_get_conn_address() returns the address information as a BIO_ADDR. internal pointer, do not modify. i'm serious. ✋

BIO_get_conn_ip_family() returns the IP family of the connect BIO.

BIO_set_nbio() sets the non blocking I/O flag to n. if n is zero then blocking I/O is set. if n is 1 then non blocking I/O is set. blocking I/O is the default. and listen — the call to BIO_set_nbio() should be made before the connection is established, because non blocking I/O gets set during the connect process. timing is everything, no cap. ⏰

BIO_do_connect() attempts to connect the supplied BIO. it performs an SSL/TLS handshake as far as supported by the BIO. for non-SSL BIOs the connection happens typically at TCP level. if domain name resolution yields multiple IP addresses, all of them get tried after connect() failures — it really said "we're not leaving until we find the one". the function returns 1 if the connection was established successfully, and a zero or negative value if the connection could not be established. the call BIO_should_retry() should be used for non blocking connect BIOs to figure out if the call should be retried. and if a connection has already been established, this call has no effect — like, nothing, zero, nada. 💀

BIO_set_sock_type() can be used to set a socket type value as would be passed in a call to socket(2). the only currently supported values are SOCK_STREAM (the default) and SOCK_DGRAM. if SOCK_DGRAM is configured, the connection created is a UDP datagram socket handled via BIO_s_datagram(3). I/O calls such as BIO_read(3) and BIO_write(3) are forwarded transparently to an internal BIO_s_datagram(3) instance. that created BIO_s_datagram(3) instance can be retrieved using BIO_get0_dgram_bio() if you want, which writes a pointer to the BIO_s_datagram(3) instance to *dgram_bio. the lifetime of that internal BIO_s_datagram(3) is managed by BIO_s_connect() — so you do not need to free it yourself. let the BIO handle its own business. 🫶

BIO_get_sock_type() retrieves the value set using BIO_set_sock_type().

🌈 NOTES 🌈

if blocking I/O is set, then a non positive return value from any I/O call is caused by an error condition — although a zero return will normally mean that the connection was closed. 😭

if the port name is supplied as part of the hostname then this will override any value set with BIO_set_conn_port(). this may be undesirable if the application does not wish to allow connection to arbitrary ports. you can avoid this by checking for the presence of the ':' character in the passed hostname and either indicating an error or truncating the string at that point. bestie, pls check your colons. 🙏

the values returned by BIO_get_conn_hostname(), BIO_get_conn_address(), and BIO_get_conn_port() are updated when a connection attempt is made. before any connection attempt, the values returned are those set by the application itself. so like, they change on you. that's just the lore. 📖

applications do not have to call BIO_do_connect(), but may wish to do so to separate the connection process from other I/O processing.

if non blocking I/O is set then retries will be requested as appropriate. ✨

in addition to BIO_should_read() and BIO_should_write() it's also possible for BIO_should_io_special() to be true during the initial connection process, with the reason BIO_RR_CONNECT. if that comes back, it's an indication that a connection attempt would block — so the application should then take appropriate action to wait until the underlying socket has connected and retry the call. don't rush her, she's connecting. 💅

BIO_set_conn_hostname(), BIO_set_conn_port(), BIO_get_conn_hostname(), BIO_set_conn_address(), BIO_get_conn_port(), BIO_get_conn_address(), BIO_set_conn_ip_family(), BIO_get_conn_ip_family(), BIO_set_nbio(), and BIO_do_connect() are macros. plot twist, i know. 😭

🎀 RETURN VALUES 🎀

BIO_s_connect() returns the connect BIO method.
BIO_set_conn_address(), BIO_set_conn_port(), and BIO_set_conn_ip_family() return 1, or <=0 if an error occurs.
BIO_set_conn_hostname() returns 1 on success and <=0 on failure.
BIO_get_conn_address() returns the address information, or NULL if none was set.
BIO_get_conn_hostname() returns the connected hostname, or NULL if none was set.
BIO_get_conn_ip_family() returns the address family, or -1 if none was set.
BIO_get_conn_port() returns a string representing the connected port, or NULL if not set.
BIO_set_nbio() returns 1, or <=0 if an error occurs.
BIO_do_connect() returns 1 if the connection was successfully established and <=0 if the connection failed.
BIO_set_sock_type() returns 1 on success or 0 on failure.
BIO_get_sock_type() returns a socket type or 0 if the call is not supported.
BIO_get0_dgram_bio() returns 1 on success or 0 on failure.

🦋 EXAMPLES 🦋

this example connects to a webserver on the local host and attempts to retrieve a page, then copies the result to standard output. slay. ✨

BIO *cbio, *out;
int len;
char tmpbuf[1024];

cbio = BIO_new_connect("localhost:http");
out = BIO_new_fp(stdout, BIO_NOCLOSE);
if (BIO_do_connect(cbio) <= 0) {
    fprintf(stderr, "Error connecting to server\n");
    ERR_print_errors_fp(stderr);
    exit(1);
}
BIO_puts(cbio, "GET / HTTP/1.0\n\n");
for (;;) {
    len = BIO_read(cbio, tmpbuf, 1024);
    if (len <= 0)
        break;
    BIO_write(out, tmpbuf, len);
}
BIO_free(cbio);
BIO_free(out);

👑 SEE ALSO 👑

BIO_ADDR(3)
BIO_parse_hostserv(3)

📜 HISTORY 📜

BIO_set_conn_int_port(), BIO_get_conn_int_port(), BIO_set_conn_ip(), and BIO_get_conn_ip() were removed in OpenSSL 1.1.0. use BIO_set_conn_address() and BIO_get_conn_address() instead. rip to those guys, gone but not forgotten. 💀

connect BIOs support BIO_gets(), and BIO_get0_dgram_bio(), BIO_get_sock_type(), BIO_set_sock_type() were added in OpenSSL 3.2. glow up. ✨

💜 COPYRIGHT 💜

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.

and that's the whole page, bestie 💖 this was OpenSSL 4.0.3, dated 2026-09-29, for BIO_S_CONNECT(3SSL). go forth and connect responsibly 🫶✨🎀

📦 where this page comes from

ubuntu stonking: libssl-doc 4.0.3-1ubuntu1 · Apache-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms