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

       Please refer to handle.c on how to set up a socketpair.

       datafd  can  be 0, and knet_handle_add_datafd will create a properly populated socket pair
       the same way as ping_test, or a value higher than 0. A  negative  number  will  return  an
       error. On exit knet_handle_free will take care to cleanup the socketpair only if they have
       been created by knet_handle_add_datafd.

       It is possible to pass either sockets or normal fds. 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.

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.

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

SEE ALSO

       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_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_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_link_insert_acl(3)

COPYRIGHT

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