BIO_ADDR(3ossl)

📦 version 3.5.0, in opensuse-leap 16.0

✨ BIO_ADDR(3ossl) — the whole vibe ✨

okay so this is the BIO_ADDR(3ossl) page from OpenSSL, and honestly bestie, it's a good one. it's all about BIO_ADDR — the little wrapper that holds every kind of socket address OpenSSL fumbles with. pull up a chair, we're gonna go through it 💅

🌸 SYNOPSIS 🌸

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

typedef union bio_addr_st BIO_ADDR;

BIO_ADDR *BIO_ADDR_new(void);
int BIO_ADDR_copy(BIO_ADDR *dst, const BIO_ADDR *src);
BIO_ADDR *BIO_ADDR_dup(const BIO_ADDR *ap);
void BIO_ADDR_free(BIO_ADDR *ap);
void BIO_ADDR_clear(BIO_ADDR *ap);
int BIO_ADDR_rawmake(BIO_ADDR *ap, int family,
                     const void *where, size_t wherelen, unsigned short port);
int BIO_ADDR_family(const BIO_ADDR *ap);
int BIO_ADDR_rawaddress(const BIO_ADDR *ap, void *p, size_t *l);
unsigned short BIO_ADDR_rawport(const BIO_ADDR *ap);
char *BIO_ADDR_hostname_string(const BIO_ADDR *ap, int numeric);
char *BIO_ADDR_service_string(const BIO_ADDR *ap, int numeric);
char *BIO_ADDR_path_string(const BIO_ADDR *ap);

🦋 DESCRIPTION 🦋

so BIO_ADDR is basically a glow-up wrapper around all the socket address types OpenSSL deals with. right now it's transparently serving AF_INET, AF_INET6 and AF_UNIX, depending on what your platform actually has available. no cap, it just adapts 💖

here's the whole friend group, one by one:

  • BIO_ADDR_new() — makes a brand-new, unfilled BIO_ADDR, ready to be handed to routines that fill it with info, like BIO_accept_ex().
  • BIO_ADDR_copy() — copies the contents of src into dst. and listen: neither src nor dst can be NULL, periodt.
  • BIO_ADDR_dup() — creates a fresh BIO_ADDR with a copy of the address data in ap.
  • BIO_ADDR_free() — frees a BIO_ADDR that came from BIO_ADDR_new() or BIO_ADDR_dup(). if you pass NULL? nothing happens. very chill of it.
  • BIO_ADDR_clear() — wipes any data inside the given BIO_ADDR and sets it back to an uninitialised state. clean slate energy ✨
  • BIO_ADDR_rawmake() — takes a protocol family, a byte array of size wherelen with an address in network byte order pointed at by where, and a port number in network byte order in port, then populates the given BIO_ADDR with all of that. ⚠️ tiny exception: for the AF_UNIX protocol family, port is meaningless and therefore ignored. and if this creates an AF_UNIX BIO_ADDR, wherelen is expected to be the length of the path string — not including the terminating NUL, like what strlen() gives you. more on all that under "RAW ADDRESSES" below 👇
  • BIO_ADDR_family() — returns the protocol family of the given BIO_ADDR. the possible non-error results are one of the constants AF_INET, AF_INET6 and AF_UNIX. it'll also hand you AF_UNSPEC if the BIO_ADDR hasn't been initialised yet (it's giving "idk yet").
  • BIO_ADDR_rawaddress() — writes the raw address of the given BIO_ADDR into the area pointed at by p if p is non-NULL, and sets *l to be the amount of bytes the raw address takes up if l is non-NULL. pro tip from the manpage itself: if you only wanna find out the size of the address, call it with p set to NULL. the raw address will be in network byte order, most significant byte first. and if this is an AF_UNIX BIO_ADDR, l gets the length of the path string (again, not including the terminating NUL, like strlen() returns). "RAW ADDRESSES" section, we love you 💜
  • BIO_ADDR_rawport() — returns the raw port of the given BIO_ADDR. the raw port is in network byte order.
  • BIO_ADDR_hostname_string() — returns a character string with the hostname of the given BIO_ADDR. if numeric is 1, the string will contain the numerical form of the address. this only works for BIO_ADDR of the protocol families AF_INET and AF_INET6. and the returned string has been allocated on the heap, so you must free it with OPENSSL_free(). don't forget, bestie 😭
  • BIO_ADDR_service_string() — returns a character string with the service name of the port of the given BIO_ADDR. if numeric is 1, the string will contain the port number. again, only works for BIO_ADDR of the protocol families AF_INET and AF_INET6, and again the returned string is heap-allocated and must be freed with OPENSSL_free().
  • BIO_ADDR_path_string() — returns a character string with the path of the given BIO_ADDR. this one only works for BIO_ADDR of the protocol family AF_UNIX. and yes, heap-allocated, yes, OPENSSL_free() it. every single time 🫶

🧚 RAW ADDRESSES 🧚

okay both BIO_ADDR_rawmake() and BIO_ADDR_rawaddress() take a pointer to a network byte order address of a specific site. internally, those get treated as a pointer to struct in_addr (for AF_INET), struct in6_addr (for AF_INET6) or char * (for AF_UNIX) — all depending on the protocol family the address is for. it's giving shapeshifter 💀

🔥 RETURN VALUES 🔥

the string-producing girlies — BIO_ADDR_hostname_string(), BIO_ADDR_service_string() and BIO_ADDR_path_string() — will return NULL on error, and they leave an error indication on the OpenSSL error stack.

BIO_ADDR_copy() returns 1 on success or 0 on error.

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 whole rule 🌈

🎀 SEE ALSO 🎀

👑 HISTORY 👑

BIO_ADDR_copy() and BIO_ADDR_dup() were added in OpenSSL 3.2. newer additions to the friend group, and we're obsessed 💖

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>.

alright bestie, that's the whole page 💅 this was OpenSSL 3.5.0, dated 2026-09-25, signed off with love and a little sparkle ✨ mwah 🫶🎀

📦 where this page comes from