1KNET_HANDLE_ADD_DATAFD(3)Kronosnet Programmer's ManualKNET_HANDLE_ADD_DATAFD(3)
2
3
4

NAME

6       knet_handle_add_datafd - Install a file descriptor for communication.
7

SYNOPSIS

9       #include <libknet.h>
10
11       int knet_handle_add_datafd(
12           knet_handle_t  knet_h,
13           int           *datafd,
14           int8_t        *channel
15       );
16

DESCRIPTION

18       knet_handle_add_datafd
19
20       IMPORTANT:    In    order    to   add   datafd   to   knet,   knet_han‐
21       dle_enable_sock_notify MUST be set and be able to  handle  both  errors
22       (-1)  and  0 bytes read / write from the provided datafd. On read error
23       (< 0) from datafd, the socket is automatically removed from polling  to
24       avoid   spinning  on  dead  sockets.  It  is  safe  to  call  knet_han‐
25       dle_remove_datafd even on sockets that have been removed.
26
27       knet_h - pointer to knet_handle_t
28
29       *datafd - read/write file descriptor. knet will read data here to  send
30       to  the other hosts and will write data received from the network. Each
31       data packet can be of max size KNET_MAX_PACKET_SIZE! Applications using
32       knet_send/knet_recv  will  receive a proper error if the packet size is
33       not within boundaries. Applications using their own functions to  write
34       to the datafd should NOT write more than KNET_MAX_PACKET_SIZE.
35
36       Please refer to handle.c on how to set up a socketpair.
37
38       datafd can be 0, and knet_handle_add_datafd will create a properly pop‐
39       ulated socket pair the same way as ping_test, or a value higher than 0.
40       A  negative  number will return an error. On exit knet_handle_free will
41       take care to cleanup the socketpair only if they have been  created  by
42       knet_handle_add_datafd.
43
44       It  is  possible  to  pass  either sockets or normal fds. User provided
45       datafd will be marked as non-blocking and close-on-exec.
46
47       *channel - This value is analogous to the tag in VLAN tagging. A  nega‐
48       tive  value will auto-allocate a channel. Setting a value between 0 and
49       31 will try to allocate that specific channel (unless already in use).
50
51       It is possible to add up to 32 datafds but be aware that  each  one  of
52       them must have a receiving end on the other host.
53
54       Example: hostA channel 0 will be delivered to datafd on hostB channel 0
55       hostA channel 1 to hostB channel 1.
56
57       Each channel must have a unique file descriptor.
58
59       If your application could have 2 channels on one host and  one  channel
60       on another host, then you can use dst_host_filter to manipulate channel
61       values on TX and RX.
62

RETURN VALUE

64       knet_handle_add_datafd returns
65
66       0          on success, *datafd will be populated with a socket  if  the
67       original  value  was  0  or  if  a  specific  fd  was set, the value is
68       untouched. *channel will be populated with  a  channel  number  if  the
69       original  value  was  negative  or the value is untouched if a specific
70       channel was requested.
71
72       -1         on  error  and  errno  is  set.  *datafd  and  *channel  are
73       untouched or empty.
74

SEE ALSO

76       knet_handle_remove_datafd(3), knet_handle_get_stats(3),
77       knet_host_add(3), knet_handle_pmtud_setfreq(3),
78       knet_handle_pmtud_get(3), knet_handle_crypto_use_config(3),
79       knet_host_get_id_by_host_name(3), knet_host_get_status(3),
80       knet_link_add_acl(3), knet_link_get_pong_count(3),
81       knet_link_get_priority(3), knet_handle_free(3),
82       knet_handle_enable_sock_notify(3), knet_handle_get_datafd(3),
83       knet_recv(3), knet_link_get_ping_timers(3),
84       knet_log_get_subsystem_id(3), knet_host_remove(3),
85       knet_host_enable_status_change_notify(3), knet_strtoaddr(3),
86       knet_link_rm_acl(3), knet_send(3), knet_handle_enable_pmtud_notify(3),
87       knet_handle_get_transport_reconnect_interval(3),
88       knet_link_get_enable(3), knet_link_set_priority(3),
89       knet_log_set_loglevel(3), knet_handle_get_channel(3),
90       knet_link_get_config(3), knet_link_get_link_list(3),
91       knet_get_transport_list(3), knet_get_transport_id_by_name(3),
92       knet_log_get_loglevel_id(3), knet_handle_new_ex(3),
93       knet_host_set_name(3), knet_addrtostr(3), knet_handle_setfwd(3),
94       knet_get_compress_list(3), knet_host_set_policy(3),
95       knet_get_transport_name_by_id(3), knet_handle_enable_filter(3),
96       knet_handle_crypto_rx_clear_traffic(3), knet_handle_compress(3),
97       knet_link_get_status(3), knet_send_sync(3),
98       knet_log_get_loglevel_name(3), knet_handle_enable_access_lists(3),
99       knet_host_get_host_list(3), knet_host_get_policy(3),
100       knet_link_set_enable(3), knet_link_set_pong_count(3),
101       knet_log_get_subsystem_name(3), knet_host_get_name_by_host_id(3),
102       knet_link_clear_config(3), knet_log_get_loglevel(3),
103       knet_handle_new(3), knet_handle_pmtud_getfreq(3),
104       knet_handle_pmtud_set(3), knet_handle_clear_stats(3),
105       knet_link_set_config(3), knet_handle_crypto_set_config(3),
106       knet_handle_crypto(3), knet_get_crypto_list(3),
107       knet_handle_set_transport_reconnect_interval(3),
108       knet_link_clear_acl(3), knet_link_set_ping_timers(3),
109       knet_link_insert_acl(3)
110
112       Copyright (C) 2010-2020 Red Hat, Inc. All rights reserved.
113
114
115
116kronosnet                         2020-10-19         KNET_HANDLE_ADD_DATAFD(3)
Impressum