NE_SOCK_INIT(3)

📦
version 0.37.1 · 12 versions
, in arch rolling

✨ NE_SOCK_INIT(3) — the neon API reference, bestie edition ✨

okay so this is the neon manual page for ne_sock_init / ne_sock_exit, aka the "wake the library up" and "put the library to bed" duo. section 3, library functions, we love to see it 💖

🌸 NAME 🌸

ne_sock_init, ne_sock_exit — literally just doing library initialization. that's the whole job. perform library initialization. slay.

🎀 SYNOPSIS 🎀

#include <ne_socket.h>

int ne_sock_init(void);

void ne_sock_exit(void);

no cap, that's the entire API surface. two functions. one gives you an int back, one gives you nothing back. balance ✨

🦋 DESCRIPTION 🦋

so here's the vibe: on some platforms and in some configurations, neon might be out here using socket libraries or SSL libraries that need global initialization before you can touch them. like they need to be warmed up first, iykyk. to do that initialization, the ne_sock_init function must be called before any other library functions are used. not optional. must. before any other library functions. periodt.

once you're fully done using neon, ne_sock_exit can be called to perform de-initialization of the socket or SSL libraries, if necessary. (if necessary!! it's conditional, don't come for me.)

and here's the cute part — uses of ne_sock_init and ne_sock_exit are "reference counted". so if N calls to ne_sock_init happen, only the Nth call to ne_sock_exit will have any effect. so you can stack them like little nesting dolls 🪆 and only the last one out actually turns off the lights.

ne_sock_init will set the disposition of the SIGPIPE signal to ignored. meanwhile ne_sock_exit makes no change to the SIGPIPE disposition at all. it's giving "not my department" 💅

🌈 the SSL callback situation (a saga)

both SSL libraries supported by neon — OpenSSL and GnuTLS — require callbacks to be registered to allow thread-safe use of SSL. and these callbacks are stored as global variables, so their state persists for as long as the library in question is loaded into the process. so far so fine, right?

but 😭 if multiple users of the SSL library exist within the process, this can be problematic — especially if one of them is dynamically loaded (and may subsequently be unloaded). that's the messy part. it's giving drama.

so: if neon is configured using the --enable-threadsafe-ssl flag, thread-safe SSL support will be enabled automatically, as covered in the next section. otherwise, it is not safe to use neon with SSL in a multi-threaded process. like genuinely not safe, bestie, be careful. the ne_has_support(3) function can be used to determine whether neon is built to enable thread-safety support in the SSL library. use it. it's right there. 🫶

💜 Thread-safe SSL with OpenSSL

neon follows two simple rules when dealing with the OpenSSL locking callbacks, and honestly? iconic of it:

  • ne_sock_init will set thread-safety locking callbacks if and only if no locking callbacks are already registered.
  • ne_sock_exit will unset the thread-safety locking callbacks if and only if the locking callbacks registered are those registered by ne_sock_init.

applications and libraries should be able to co-operate to ensure that SSL use is always thread-safe — if similar rules are always followed. teamwork makes the dream work 🤝

🧚 Thread-safe SSL with GnuTLS

okay this one's a little different. the cryptography library used by GnuTLS, libgcrypt, only supports an initialization operation to register thread-safety callbacks. there's no un-register. no take-backs. so:

  • ne_sock_init will register the thread-safe locking callbacks on first use.
  • ne_sock_exit cannot unregister them. it simply cannot, don't ask her to.

and because of that, if multiple users of GnuTLS are present within the process, it is unsafe to dynamically unload neon from the process if neon is configured with thread-safe SSL support enabled — since the callbacks would be left pointing at unmapped memory once neon is unloaded. that's the danger zone 💀 don't do it.

⭐ RETURN VALUE ⭐

ne_sock_init returns zero on success, or non-zero on error. that's it, that's the contract.

⚠️ but listen — if an error occurs, no further use of the neon library should be attempted. like at all. put it down. walk away. do not pass go. 🙈

🍓 SEE ALSO 🍓

Copyright © 2001-2026 Joe Orton

and that's the page, bestie 🎀 — brought to you by the neon API reference, dated 03/20/2026, page NE_SOCK_INIT(3), closing out exactly like it opened. go forth and initialize responsibly ✨💖

📦 where this page comes from