KNET_HAND...DD_DATAFD(3)

📦
version 1.35 · 7 versions
, in fedora 43, fedora 44

💖 KNET_HAND...DD_DATAFD 💖

okay bestie, welcome to the Kronosnet Programmer's Manual ✨ this one's called knet_handle_add_datafd and it's literally the "hey knet, here's a file descriptor, go talk to people" function. she's iconic, she's essential, let's get into it 🫶

🌸 NAME 🌸

knet_handle_add_datafd — Install a file descriptor for communication.

✨ SYNOPSIS ✨

#include <libknet.h>

int knet_handle_add_datafd(
    knet_handle_t  knet_h,
    int           *datafd,
    int8_t        *channel
);

🦋 DESCRIPTION 🦋

knet_handle_add_datafd

IMPORTANT, no cap: to add a datafd to knet, knet_handle_enable_sock_notify MUST be set and it has to be able to handle both errors (-1) and 0 bytes read / write from the provided datafd. On read error (< 0) from datafd, the socket is automatically removed from polling so we don't spin on dead sockets (we're not doing that today 💀). It is safe to call knet_handle_remove_datafd even on sockets that have been removed. periodt.

Now the parameters, one by one, iykyk:

  • knet_h — pointer to knet_handle_t. she's the main character, your handle.
  • *datafd — read/write file descriptor. knet will read data here to send to the other hosts and will write data received from the network. Each data packet can be of max size KNET_MAX_PACKET_SIZE! Applications using knet_send/knet_recv will receive a proper error if the packet size is not within boundaries. Applications using their own functions to write to the datafd should NOT write more than KNET_MAX_PACKET_SIZE. (that's the vibe check, respect the limit fr fr)

datafd can be 0, and knet_handle_add_datafd will create an internal SOCK_DGRAM AF_UNIX socketpair for communication (valid for both testing and production, bestie — yes, production too 💅). SOCK_DGRAM provides atomic message boundaries, ensuring each write becomes one distinct read on the other end. A value higher than 0 provides a user-managed file descriptor. A negative number will return an error. On exit knet_handle_free will cleanup socketpairs created by knet_handle_add_datafd, but will not close user-provided fds. (she's not your mom, she's not cleaning up your fds)

SUPPORTED file descriptor types (user-provided):

  • TAP devices (e.g., from libnozzle) — PRIMARY use case 👑
  • Regular sockets (must be bound or connected)
  • Character devices (opened with O_RDWR)
  • Any bidirectional file descriptor

UNSUPPORTED file descriptor types:

  • User-created socketpairs — will NOT work (knet needs both ends but API only accepts one fd). Use datafd=0 for knet-managed pairs.
  • Pipes (all types) — each pipe fd only supports unidirectional data flow, knet requires bidirectional I/O on the same fd
  • Unconnected sockets
REQUIREMENT: The file descriptor MUST be bidirectional — knet needs to both read and write using the SAME fd. User provided datafd will be marked as non-blocking and close-on-exec.
  • *channel — This value is analogous to the tag in VLAN tagging. A negative value will auto-allocate a channel. Setting a value between 0 and 31 will try to allocate that specific channel (unless already in use).

It is possible to add up to 32 datafds but be aware that each one of them must have a receiving end on the other host. 🌈

Example: hostA channel 0 will be delivered to datafd on hostB channel 0, hostA channel 1 to hostB channel 1.

Each channel must have a unique file descriptor.

If your application could have 2 channels on one host and one channel on another host, then you can use dst_host_filter to manipulate channel values on TX and RX. slay.

🎀 RETURN VALUE 🎀

knet_handle_add_datafd returns:

  • 0 — on success, *datafd will be populated with a socket if the original value was 0 or if a specific fd was set, the value is untouched. *channel will be populated with a channel number if the original value was negative or the value is untouched if a specific channel was requested. (win 🫶)
  • -1 — on error and errno is set. *datafd and *channel are untouched or empty. 😭

🔥 SEE ALSO 🔥

the whole friend group, all invited to the group chat:

Copyright (C) 2010-2026 Red Hat, Inc. All rights reserved.

and that's the whole page, bestie 🧚 stay hydrated, keep your fds bidirectional, and remember: you're doing amazing sweetie 💅

kronosnet · 2026-07-20 · mwah, love u, bye 💖

📦 where this page comes from