plucky (3) knet_handle_add_datafd.3.gz

Provided by: libknet-doc_1.30-1ubuntu1_all bug

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 (C) 2010-2024 Red Hat, Inc. All rights reserved.