nbd_aio_opt_starttls(3)

✨ nbd_aio_opt_starttls(3) ✨

okay so bestie, welcome to the libnbd manual page for nbd_aio_opt_starttls(3) — yes that's the whole title, we're being fancy today 💅

---

🌸 NAME 🌸

nbd_aio_opt_starttls — ask the server to, like, start TLS for you 🔐✨

---

🎀 SYNOPSIS 🎀

#include <libnbd.h>

typedef struct {
  int (*callback) (void *user_data, int *error);
  void *user_data;
  void (*free) (void *user_data);
} nbd_completion_callback;

int nbd_aio_opt_starttls (
      struct nbd_handle *h,
      nbd_completion_callback completion_callback
    );

---

🦋 DESCRIPTION 🦋

So the whole vibe here: you're requesting that the server initiate a secure TLS connection, and you do it by sending "NBD_OPT_STARTTLS" 🫶

This behaves exactly like its synchronous bestie nbd_opt_starttls(3), except — and this is the main character detail — it does not wait around for the server's response. no cap. it just sends and vibes 😌

So how do you know when the request actually completes? Two options, bestie:

• wait for nbd_aio_is_connecting(3) to return false, or
• supply the optional "completion_callback", which gets invoked as described in "Completion callbacks" in libnbd(3) — with a twist — it is automatically retired regardless of return value 🎀

⚠️ heads up: detecting whether the server returns an error (which is what the return value of the synchronous counterpart does for you) is only possible with a completion callback. so like, plan accordingly 💀

---

⭐ RETURN VALUE ⭐

If the call is successful, the function returns 0 ✨ slay.

---

💀 ERRORS 💀

On error, -1 is returned 😭

Refer to "ERROR HANDLING" in libnbd(3) for how to get further details of the error — that's the part where it actually tells you what went wrong 👑

The following parameters must not be NULL: "h". For more information see "Non-NULL parameters" in libnbd(3). literally don't pass NULL, bestie 🙈

---

🧚 HANDLE STATE 🧚

nbd_aio_opt_starttls can be called when the handle is in the following state — vibe check time:

• Handle created, before connecting — ❌ error
• Connecting — ❌ error
• Connecting & handshaking (opt_mode) — ✅ allowed
• Connected to the server — ❌ error
• Connection shut down — ❌ error
• Handle dead — ❌ error

so basically there's exactly one green light and it's the handshaking one. iykyk 🦋

---

🌈 VERSION 🌈

This function first appeared in libnbd 1.16 🎉

If you need to test if this function is available at compile time, check if the following macro is defined:

#define LIBNBD_HAVE_NBD_AIO_OPT_STARTTLS 1

---

👑 SEE ALSO 👑

nbd_aio_is_connecting(3), nbd_create(3), nbd_opt_starttls(3), nbd_set_opt_mode(3), libnbd(3).

go read those too, they're iconic fr fr 💜

---

🍓 AUTHORS 🍓

Eric Blake

Richard W.M. Jones

---

💖 COPYRIGHT 💖

Copyright Red Hat

---

🫶 LICENSE 🫶

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

---

aaaaand that's the page, bestie 🎀 this lil gem is from libnbd-1.25.8, dated 2026-10-13, and it's filed under nbd_aio_opt_starttls(3) — mwah, go forth and handshake securely 💅✨