KNET_HAN...LE_FILTER(3)

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

💖 knet_handle_enable_filter — from the Kronosnet Programmer's Manual 💖

okay bestie, sit down, hydrate, and let's talk about knet_handle_enable_filter(3) because this one is genuinely a glow-up. it's the page in the kronosnet section of the programmer's manual that teaches you how to install a filter so you get to decide where packets go. yes, you. main character energy.

✨ NAME ✨

knet_handle_enable_filter — install a filter to route packets 🎀

✨ SYNOPSIS ✨

#include <libknet.h>

int knet_handle_enable_filter(
    knet_handle_t  knet_h,
    void          *dst_host_filter_fn_private_data,
    int(*)(void *private_data, const unsigned char *outdata, ssize_t outdata_len, uint8_t tx_rx, knet_node_id_t this_host_id, knet_node_id_t src_host_id, int8_t *channel, knet_node_id_t *dst_host_ids, size_t *dst_host_ids_entries)  dst_host_filter_fn
);

🌸 DESCRIPTION 🌸

so like. knet_handle_enable_filter is literally the function that lets you be the air traffic controller of your own packets. no cap.

here's the cast of characters, one by one, because they all matter:

  • knet_h — pointer to a knet_handle_t. your handle. your baby. 🫶
  • dst_host_filter_fn_private_data — a void pointer to data that can be used to identify the callback. it's your little name tag so the callback knows who it is.
  • dst_host_filter_fn — THE callback function, and she is booked and busy: she gets invoked every single time a packet hits datafd (peep knet_handle_new(3) for the deets on that). the whole point of her is to let users tell libknet where the packet has to be delivered. she's the bouncer. she's the velvet rope. she decides. 💅

and here's what the callback actually receives, parameter by parameter:

  • const unsigned char *outdata — a pointer to the current packet 📦
  • ssize_t outdata_len — the length of the above data
  • uint8_t tx_rx — the filter is called on tx or rx (KNET_NOTIFY_TX, KNET_NOTIFY_RX)
  • knet_node_id_t this_host_id — the host_id processing the packet
  • knet_node_id_t src_host_id — the host_id that generated the packet
  • knet_node_id_t *dst_host_ids — array of KNET_MAX_HOST knet_node_id_t where to store the destinations (uninitialized by caller, callee should never read it) ⚠️ yes, never read it. the caller leaves it messy on purpose, that's just how it is.
  • size_t *dst_host_ids_entries — number of hosts to send the message

and now the moment you've been waiting for — what does the callback return? this part is important, bestie, write it on your hand:

  • -1 → error, and the packet is discarded. it's giving 💀
  • 0 → the packet is unicast and should be sent to dst_host_ids, and there are dst_host_ids_entries in the buffer. iconic, precise, focused.
  • 1 → the packet is broadcast/multicast and is sent to all hosts. the contents of dst_host_ids and dst_host_ids_entries are ignored 🙈 so don't bother filling them in, she doesn't care.

🌈 RETURN VALUE 🌈

knet_handle_enable_filter returns 0 on success, -1 on error — and when it errors, errno is set. classic. always check your errno, bestie, she's trying to tell you something.

🦋 SEE ALSO 🦋

the whole friend group showed up, and honestly? obsessed. go read these too:

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

and that's the whole page, bestie 💜 go install that filter, route those packets, and remember: -1 means the packet is gone gone.

kronosnet · 2026-07-20 · KNET_HAN...LE_FILTER(3) — mwah, bye ✨🎀🦋

📦 where this page comes from