knet_handle_add_datafd - Man Page

#include <libknet.h>

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

knet_handle_add_datafd

IMPORTANT: In order to add datafd to knet, knet_handle_enable_sock_notify MUST be set and 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 to avoid spinning on dead sockets. It is safe to call knet_handle_remove_datafd even on sockets that have been removed.

knet_h - pointer to knet_handle_t

*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.

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). 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.

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.

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.

-1         on error and errno is set. *datafd and *channel are untouched or empty.

knet_handle_remove_datafd(3), knet_handle_get_stats(3), knet_host_add(3), knet_handle_pmtud_setfreq(3), knet_handle_pmtud_get(3), knet_handle_crypto_use_config(3), knet_host_get_id_by_host_name(3), knet_host_get_status(3), knet_link_add_acl(3), knet_link_get_pong_count(3), knet_link_get_priority(3), knet_handle_free(3), knet_handle_enable_sock_notify(3), knet_handle_get_datafd(3), knet_recv(3), knet_link_get_ping_timers(3), knet_log_get_subsystem_id(3), knet_host_remove(3), knet_host_enable_status_change_notify(3), knet_strtoaddr(3), knet_link_rm_acl(3), knet_send(3), knet_handle_enable_pmtud_notify(3), knet_get_crypto_cipher_list(3), knet_handle_get_transport_reconnect_interval(3), knet_link_get_enable(3), knet_link_set_priority(3), knet_log_set_loglevel(3), knet_handle_get_channel(3), knet_link_get_config(3), knet_link_get_link_list(3), knet_get_crypto_hash_list(3), knet_get_transport_list(3), knet_get_transport_id_by_name(3), knet_log_get_loglevel_id(3), knet_handle_new_ex(3), knet_host_set_name(3), knet_addrtostr(3), knet_handle_setfwd(3), knet_get_compress_list(3), knet_host_set_policy(3), knet_get_transport_name_by_id(3), knet_handle_enable_filter(3), knet_handle_crypto_rx_clear_traffic(3), knet_handle_compress(3), knet_link_get_status(3), knet_send_sync(3), knet_log_get_loglevel_name(3), knet_handle_enable_access_lists(3), knet_host_get_host_list(3), knet_host_get_policy(3), knet_link_set_enable(3), knet_link_set_pong_count(3), knet_log_get_subsystem_name(3), knet_host_get_name_by_host_id(3), knet_link_clear_config(3), knet_log_get_loglevel(3), knet_handle_new(3), knet_handle_pmtud_getfreq(3), knet_handle_pmtud_set(3), knet_handle_clear_stats(3), knet_link_set_config(3), knet_handle_crypto_set_config(3), knet_handle_crypto(3), knet_get_crypto_list(3), knet_handle_set_transport_reconnect_interval(3), knet_link_clear_acl(3), knet_link_set_ping_timers(3), knet_handle_setprio_dscp(3), knet_link_insert_acl(3)

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

knet_addrtostr(3), knet_get_compress_list(3), knet_get_crypto_cipher_list(3), knet_get_crypto_hash_list(3), knet_get_crypto_list(3), knet_get_transport_id_by_name(3), knet_get_transport_list(3), knet_get_transport_name_by_id(3), knet_handle_clear_stats(3), knet_handle_compress(3), knet_handle_crypto(3), knet_handle_crypto_rx_clear_traffic(3), knet_handle_crypto_set_config(3), knet_handle_crypto_use_config(3), knet_handle_enable_access_lists(3), knet_handle_enable_filter(3), knet_handle_enable_pmtud_notify(3), knet_handle_enable_sock_notify(3), knet_handle_free(3), knet_handle_get_channel(3), knet_handle_get_datafd(3), knet_handle_get_stats(3), knet_handle_get_transport_reconnect_interval(3), knet_handle_new(3), knet_handle_new_ex(3), knet_handle_pmtud_get(3), knet_handle_pmtud_getfreq(3), knet_handle_pmtud_set(3), knet_handle_pmtud_setfreq(3), knet_handle_remove_datafd(3), knet_handle_setfwd(3), knet_handle_setprio_dscp(3), knet_handle_set_transport_reconnect_interval(3), knet_host_add(3), knet_host_enable_status_change_notify(3), knet_host_get_host_list(3), knet_host_get_id_by_host_name(3), knet_host_get_name_by_host_id(3), knet_host_get_policy(3), knet_host_get_status(3), knet_host_remove(3), knet_host_set_name(3), knet_host_set_policy(3), knet_link_add_acl(3), knet_link_clear_acl(3), knet_link_clear_config(3), knet_link_get_config(3), knet_link_get_enable(3), knet_link_get_link_list(3), knet_link_get_ping_timers(3), knet_link_get_pong_count(3), knet_link_get_priority(3), knet_link_get_status(3), knet_link_insert_acl(3), knet_link_rm_acl(3), knet_link_set_config(3), knet_link_set_enable(3), knet_link_set_ping_timers(3), knet_link_set_pong_count(3), knet_link_set_priority(3), knet_log_get_loglevel(3), knet_log_get_loglevel_id(3), knet_log_get_loglevel_name(3), knet_log_get_subsystem_id(3), knet_log_get_subsystem_name(3), knet_log_set_loglevel(3), knet_recv(3), knet_send(3), knet_send_sync(3), knet_strtoaddr(3).