BIO_ADDRINFO(3ossl)

📦
version 15.1 · 2 versions
, in freebsd 15.1

💅 BIO_ADDRINFO 💅

okay bestie, welcome to BIO_ADDRINFO(3ossl) — yes that's the whole manual name, we're in the OpenSSL corner of the universe now. this page is literally a whole friend group of functions that handle address info, so grab a snack 🍓 and let's get into it.

✨ NAME ✨

BIO_lookup_type, BIO_ADDRINFO, BIO_ADDRINFO_next, BIO_ADDRINFO_free, BIO_ADDRINFO_family, BIO_ADDRINFO_socktype, BIO_ADDRINFO_protocol, BIO_ADDRINFO_address, BIO_lookup_ex, BIO_lookup — all of these are the BIO_ADDRINFO type and its lil routines 🎀

🦋 SYNOPSIS 🦋

#include <sys/types.h>
#include <openssl/bio.h>

typedef union bio_addrinfo_st BIO_ADDRINFO;

enum BIO_lookup_type {
    BIO_LOOKUP_CLIENT, BIO_LOOKUP_SERVER
};

int BIO_lookup_ex(const char *host, const char *service, int lookup_type,
                  int family, int socktype, int protocol, BIO_ADDRINFO **res);
int BIO_lookup(const char *host, const char *service,
               enum BIO_lookup_type lookup_type,
               int family, int socktype, BIO_ADDRINFO **res);

const BIO_ADDRINFO *BIO_ADDRINFO_next(const BIO_ADDRINFO *bai);
int BIO_ADDRINFO_family(const BIO_ADDRINFO *bai);
int BIO_ADDRINFO_socktype(const BIO_ADDRINFO *bai);
int BIO_ADDRINFO_protocol(const BIO_ADDRINFO *bai);
const BIO_ADDR *BIO_ADDRINFO_address(const BIO_ADDRINFO *bai);
void BIO_ADDRINFO_free(BIO_ADDRINFO *bai);

🌸 DESCRIPTION 🌸

so. the BIO_ADDRINFO type is a wrapper for the address information types that your platform gives you. basically a cute lil envelope for whatever your OS hands over 🫶

and BIO_ADDRINFO normally forms a chain of several of them — so you can pick them off one by one, like a playlist you're working through. iconic behaviour honestly.

BIO_lookup_ex() looks up a specified host and service, and uses lookup_type to decide what the default address should be when host is NULL. the family, socktype and protocol args are what determine which protocol family, socket type and protocol get used for the lookup:

  • family can be any of AF_INET, AF_INET6, AF_UNIX and AF_UNSPEC.
  • socktype can be SOCK_STREAM, SOCK_DGRAM or 0. setting it to 0 means any type can be used, no gatekeeping 💅
  • protocol specifies a protocol like IPPROTO_TCP, IPPROTO_UDP or IPPORTO_SCTP (and yup, that's spelled exactly like that on the page — iykyk 🙈). if it's set to 0 then any protocol can be used.
  • res points at a pointer that holds the start of a BIO_ADDRINFO chain.

the AF_UNIX tea ☕: for the family AF_UNIX, BIO_lookup_ex() will ignore the service parameter and expects the host parameter to hold the path to the socket file. periodt.

BIO_lookup() does the same thing as BIO_lookup_ex(), BUT it doesn't give you the ability to select based on protocol — any protocol may be returned. lowkey the chill version.

<charonqua>now the little getter besties, each one doing exactly one job 👑</charonqua>

  • BIO_ADDRINFO_family() — returns the family of the given BIO_ADDRINFO. the result will be one of the constants AF_INET, AF_INET6 and AF_UNIX.
  • BIO_ADDRINFO_socktype() — returns the socket type of the given BIO_ADDRINFO. the result will be one of the constants SOCK_STREAM and SOCK_DGRAM.
  • BIO_ADDRINFO_protocol() — returns the protocol id of the given BIO_ADDRINFO. the result will be one of the constants IPPROTO_TCP and IPPROTO_UDP.
  • BIO_ADDRINFO_address() — returns the underlying BIO_ADDR of the given BIO_ADDRINFO.
  • BIO_ADDRINFO_next() — returns the next BIO_ADDRINFO in the chain from the given one. main character energy: always pointing at the next thing ✨
  • BIO_ADDRINFO_free() — frees the chain of BIO_ADDRINFO starting with the given one. and if the argument is NULL, nothing is done. no crash, no drama, we love a graceful no-op 💖

🌈 RETURN VALUES 🌈

  • BIO_lookup_ex() and BIO_lookup() return 1 on success and 0 when an error occurred — and in that error case they'll leave an error indication on the OpenSSL error stack, so go check it 👀
  • all the other functions described here return 0 or NULL when the information they should return isn't available. that's it, that's the vibe check.

🔥 NOTES 🔥

real talk: the BIO_lookup_ex() implementation uses the platform provided getaddrinfo() function. on Linux it is known that specifying 0 for the protocol will not return any SCTP based addresses when calling getaddrinfo(). so if you need an SCTP address, you gotta explicitly set the protocol parameter to BIO_lookup_ex() to IPPROTO_SCTP. ngl, the same may be true on other platforms too — so don't @ me.

💀 okay but seriously bestie, that SCTP thing is a real gotcha. explicitly set IPPROTO_SCTP or you will simply not get your address. no cap.

🎀 HISTORY 🎀

BIO_lookup_ex() was added in OpenSSL 1.1.1. a true icon of that era 💜

Copyright 2016-2024 The OpenSSL Project Authors. All Rights Reserved.

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 3.5.6, dated 2026-04-07, and you read it in BIO_ADDRINFO(3ossl) — go forth and look up some addresses, slay 💅✨🌸

📦 where this page comes from