BIO_ADDR(3ossl)

📦
version 15.1 · 2 versions
, in freebsd 15.1

💅 BIO_ADDR — the whole OpenSSL address-wrapper situation (it's from the OpenSSL manual, bestie)

Okay so this is the BIO_ADDR family of routines from OpenSSL, and honestly? It's giving "one union to hold every socket address you'll ever meet" and I'm obsessed. Sit down, grab a strawberry 🍓, we're doing this.

✨ NAME ✨

BIO_ADDR, BIO_ADDR_new, BIO_ADDR_copy, BIO_ADDR_dup, BIO_ADDR_clear, BIO_ADDR_free, BIO_ADDR_rawmake, BIO_ADDR_family, BIO_ADDR_rawaddress, BIO_ADDR_rawport, BIO_ADDR_hostname_string, BIO_ADDR_service_string, BIO_ADDR_path_string — all the BIO_ADDR routines, together, as a treat 🎀

🌸 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 a wrapper around, like, all the types of socket addresses OpenSSL deals with. Right now it transparently supports AF_INET, AF_INET6 and AF_UNIX — depending on what's actually available on the platform you're on at hand. Versatile queen 👑

  • BIO_ADDR_new() — makes you a brand new, unfilled BIO_ADDR, ready to be used with routines that will fill it with info, like BIO_accept_ex(). It's a blank canvas, main character energy.
  • BIO_ADDR_copy() — copies the contents of src into dst. Neither src nor dst can be NULL. No cap, they literally cannot.
  • BIO_ADDR_dup() — creates a new BIO_ADDR, with a copy of the address data in ap. Clone slay 💫
  • BIO_ADDR_free() — frees a BIO_ADDR that was created with BIO_ADDR_new() or BIO_ADDR_dup(). If the argument is NULL, nothing is done. She's unbothered, she simply does not react.
  • BIO_ADDR_clear() — clears any data held inside the provided BIO_ADDR and sets it back to an uninitialised state. Factory reset vibes.
  • 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 (except for the AF_UNIX protocol family, where port is meaningless and therefore ignored 🙈) and populates the given BIO_ADDR with them. In case this creates an AF_UNIX BIO_ADDR, wherelen is expected to be the length of the path string — not including the terminating NUL, like the result of a call to strlen(), iykyk. Read on about the addresses in "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 will also return AF_UNSPEC if the BIO_ADDR has not been initialised. She'll tell you who she is, or she'll tell you she doesn't know 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. A technique to only find out the size of the address is a call with p set to NULL. The raw address will be in network byte order, most significant byte first. In case this is an AF_UNIX BIO_ADDR, l gets the length of the path string — again, not including the terminating NUL, like the result of a call to strlen(). Read on in "RAW ADDRESSES" below, bestie ⭐
  • BIO_ADDR_rawport() — returns the raw port of the given BIO_ADDR. The raw port will be in network byte order. Byte order matters, don't play with her 💅
  • 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. The returned string has been allocated on the heap and must be freed with OPENSSL_free(). Heap-allocated means you free it. Not optional. Periodt.
  • 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. This only works for BIO_ADDR of the protocol families AF_INET and AF_INET6. The returned string has been allocated on the heap and must be freed with OPENSSL_free(). Same deal, same energy 🫶
  • BIO_ADDR_path_string() — returns a character string with the path of the given BIO_ADDR. This only works for BIO_ADDR of the protocol family AF_UNIX. The returned string has been allocated on the heap and must be freed with OPENSSL_free(). Yes, again. Free your strings, girlies 🧚

👑 RAW ADDRESSES 👑

Both BIO_ADDR_rawmake() and BIO_ADDR_rawaddress() take a pointer to a network byte order address of a specific site. Internally, those are 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. So like, the same pointer slot wears three different outfits depending on the family. Fashion icon behaviour 🌈

🔥 RETURN VALUES 🔥

  • The string producing functions BIO_ADDR_hostname_string(), BIO_ADDR_service_string() and BIO_ADDR_path_string() will return NULL on error and leave an error indication on the OpenSSL error stack. So if you get NULL, check the stack, it left receipts.
  • BIO_ADDR_copy() returns 1 on success or 0 on error.
  • All other functions described here return 0 or NULL when the information they should return isn't available. Not a whole crisis, just the info not being there 🫠

💜 SEE ALSO 💜

BIO_connect(3), BIO_s_connect(3)

⭐ HISTORY ⭐

BIO_ADDR_copy() and BIO_ADDR_dup() were added in OpenSSL 3.2. Newer girls on the block, we love them 🎀

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

Okay that's the whole page, bestie, you ate that 🍓✨ And for the sign-off: this lil beauty is from version 3.5.6, dated 2026-04-07, and it lives under the name BIO_ADDR(3ossl) in the OpenSSL fam. Go forth and wrap those socket addresses 💖👑

📦 where this page comes from