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
8

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

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

SEE ALSO

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