TLSPOOL_SOCKET(3)

📦 version 0.9.7, in nixos 26.05

💅 TLSPOOL_SOCKET(3) — or, how to get your socket situation slayed

okay so real talk: this is the TLSPOOL_SOCKET(3) man page, and it's about one tiny little function that does a lot of heavy lifting behind the scenes. she's the friend who sets up the group chat and then never speaks again, but like — nothing works without her. 🫶

✨ NAME ✨

tlspool_socket — Setup the TLS Pool to use with a given socket path.

like, you give her a path, she gives you a file descriptor. that's the whole vibe. 🎀

🌸 SYNOPSIS 🌸

#include <tlspool/commands.h>
#include <tlspool/starttls.h>

int tlspool_socket (char *path);

two includes, one function, zero drama. we love a minimal queen. 👑

🦋 DESCRIPTION 🦋

tlspool_socket() returns a file descriptor for the TLS Pool. periodt.

so here's the tea on how she behaves — and yes, she's stateful, she remembers things:

  • On the very first call, the path argument is used as a path to the UNIX domain socket to use. 🛣️
  • On later calls, the argument is literally ignored — but the file descriptor you get back is instead the same one as before. same fd, same friend, no new vibes. 🙈
  • If the argument is NULL, that value gets replaced with the value of the socket_name configuration file as returned by tlspool_configvar() — or, if that fails, with the statically compiled value in TLSPOOL_DEFAULT_SOCKET_PATH. fallback queen behavior, honestly iconic. 💜

and here's the part nobody tells you upfront: all of the tlspool_XXX() functions that don't have a socket path argument call this function internally, to setup a shared access point to the TLS Pool. so she's not just sitting there looking cute — she's the whole infrastructure. 😭✨

oh and also? a "master thread" is created to retrieve and redistribute return values. yes, a real one, in quotes and everything. this mechanism facilitates multiple simultaneous commands being sent to the TLS Pool by independent threads. so like, all your threads can shout at the TLS Pool at once and this whole setup keeps it from descending into chaos. main character energy fr fr. 🔥

💖 RETURN VALUE 💖

  • The function returns a file descriptor >= 0 on success. slay. ✅
  • If an error occurs, the function returns -1 and errno is set appropriately. 😭 check your errno, bestie, she's telling you something.

🌈 AUTHOR 🌈

Written by Rick van Rein of OpenFortress.nl, for the ARPA2.net project. we stan. 👏

🍓 REPORTING BUGS 🍓

For any discussion, including about bugs, please use the mailing list found on http://lists.arpa2.org/mailman/listinfo/tls-pool.

also, please read the software distribution's README, INSTALL and TODO files for information about the tlspool-daemon implementation status. yes, all three. they're not decorative. 📚

Copyright © 2015 Rick van Rein, ARPA2.net.

ARPA2 is funded from InternetWide.org, which in turns receives donations from various funding sources with an interest in a private and secure Internet that gives users control over their online presence. This particular project has been sponsored in part by NCSC. 💸🌍

⭐ SEE ALSO ⭐

a little context that matters, so listen up:

the configuration file option socket_name influences the path at which the TLS Pool is available; this is not read by the client library, and when it differs from the default path in TLSPOOL_DEFAULT_SOCKET_PATH, this function is used to inform the client library once, before calling any of the other client functions. one time only. don't be weird about it. 😌

the TLS Pool API is documented in the include file <tlspool/commands.h> and <tlspool/starttls.h> for C, and the tlspool.py module for Python. 🐍

online resources may be found on the project home page, http://tlspool.arpa2.net.

💀 heads up bestie: that "argument is ignored on later calls, but the returned file descriptor is instead the same one as before" thing is real and by design. don't go thinking each call hands you a fresh fd. it does not. 🫶

and that's the whole page! brought to you by ARPA2.net, dated November 2015, living rent free in TLSPOOL_SOCKET(3) forever. mwah 💋✨🎀

📦 where this page comes from