KNET_HANDLE_NEW_EX(3)

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

💖 KNET_HANDLE_NEW_EX(3) 💖

okay so bestie, welcome to the Kronosnet Programmer's Manual — this is the page for knet_handle_new_ex(3), and it's literally the moment your whole knet journey begins. buckle up 🎀

✨ NAME ✨

knet_handle_new_ex — create a new instance of a knet handle

🌸 SYNOPSIS 🌸

#include <libknet.h>

knet_handle_t knet_handle_new_ex(
    knet_node_id_t  host_id,
    int             log_fd,
    uint8_t         default_log_level,
    uint64_t        flags
);

🦋 DESCRIPTION 🦋

knet_handle_new_ex — yes that's the whole name, she's the whole vibe, the main character fr fr. here's the tea on every single parameter 👇

  • host_id — every host in a knet is identified by a unique ID. when you're creating a new handle, you must specify your local host_id (and bestie, 0 to UINT16_MAX are all valid, so you've got range 💅). but listen — it is the user's responsibility to check that the value is unique, or bad things might happen. and by "bad things" we mean bad things. not me warning you twice 😭
  • log_fd — the write file descriptor. if you set it to a value > 0, it'll be used to write log packets from libknet to your application. set it to 0 and logging from libknet is disabled. ngl you can enable logging at any given time later (see the logging API, she's right there ✨). now the important part: make sure to either read from this filedescriptor properly and/or mark it O_NONBLOCK, otherwise if the fd becomes full, libknet could block. 💀 it is strongly encouraged to use pipes (ex: pipe(2) or pipe2(2)) for logging fds due to the atomic nature of writes between fds. see also the libknet test suite for reference and guidance. and heads up — the caller is responsible for management of the FD. eg. knet will not close it when knet_handle_free(3) is called. she's yours, you take care of her 🫶
  • default_log_level — if logfd is specified, it will initialize all subsystems to log at the default_log_level value. (see the logging API again, obsessed ✨)
  • flags — bitwise OR of some of the following flags:
    • KNET_HANDLE_FLAG_PRIVILEGED: use privileged operations setting up the communication sockets. if disabled, failure to acquire large enough socket buffers is ignored but logged. and bestie, inadequate buffers lead to poor performance. periodt.

🌈 RETURN VALUE 🌈

on success, a new knet_handle_t is returned. iconic. 👑

on failure, NULL is returned and errno is set. and here are the knet-specific errno values so you know exactly what went wrong:

  • ENAMETOOLONG — socket buffers couldn't be set big enough and KNET_HANDLE_FLAG_PRIVILEGED was specified
  • ERANGE — buffer size readback returned unexpected type

🎀 SEE ALSO 🎀

the whole friend group, no cap — go read all of them:

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

and that's the page bestie!! 💖 this was kronosnet, dated 2026-07-20, filed under KNET_HANDLE_NEW_EX(3). go make that handle, slay, and don't forget to check your host_id uniqueness or it's giving chaos 😭✨
📦 where this page comes from