[man] update man pages

Signed-off-by: Fabio M. Di Nitto <fdinitto@redhat.com>
kronosnet · Oct 30, 2017 · 562003e · 562003e
1 parent a338f5f
commit 562003e
Show file tree

Hide file tree

Showing 22 changed files with 83 additions and 75 deletions.
diff --git a/libknet/man/knet_handle_clear_stats.3 b/libknet/man/knet_handle_clear_stats.3
@@ -2,7 +2,7 @@
 .\" Generation date: Mon Oct 30 2017
 .TH knet_handle_clear_stats 3 2017-10-30 "kronosnet" "Kronosnet Programmer's Manual"
 .SH "NAME"
-knet_handle_clear_stats \- Clear knet stats - link and/or handle.
+knet_handle_clear_stats \- Clear knet stats, link and/or handle.
 .SH SYNOPSIS
 .nf
 .B #include <libknet.h>
@@ -18,7 +18,9 @@ knet_handle_clear_stats
 .PP 
 knet_h - pointer to knet_handle_t
 .PP 
-clear_option Which stats to clear (see below)
+clear_option - Which stats to clear, must be one of
+.PP 
+KNET_CLEARSTATS_HANDLE_ONLY or KNET_CLEARSTATS_HANDLE_AND_LINK
 .SH RETURN VALUE
 .PP
 0 on success -1 on error and errno is set. 

diff --git a/libknet/man/knet_handle_enable_filter.3 b/libknet/man/knet_handle_enable_filter.3
@@ -23,7 +23,7 @@ dst_host_filter_fn_private_data void pointer to data that can be used to identif
 .PP 
 dst_host_filter_fn - is a callback function that is invoked every time a packet hits datafd (see knet_handle_new(3)). the function allows users to tell libknet where the packet has to be delivered.
 .PP 
-const unsigned char *outdata - is a pointer to the current packet ssize_t outdata_len - lenght of the above data uint8_t tx_rx - filter is called on tx or rx (see defines below) knet_node_id_t this_host_id - host_id processing the packet knet_node_id_t src_host_id - host_id that generated the packet knet_node_id_t *dst_host_ids - array of KNET_MAX_HOST knet_node_id_t where to store the destinations size_t *dst_host_ids_entries - number of hosts to send the message
+const unsigned char *outdata - is a pointer to the current packet ssize_t outdata_len - length of the above data uint8_t tx_rx - filter is called on tx or rx (KNET_NOTIFY_TX, KNET_NOTIFY_RX) knet_node_id_t this_host_id - host_id processing the packet knet_node_id_t src_host_id - host_id that generated the packet knet_node_id_t *dst_host_ids - array of KNET_MAX_HOST knet_node_id_t where to store the destinations size_t *dst_host_ids_entries - number of hosts to send the message
 .PP 
 dst_host_filter_fn should return -1 on error, packet is discarded. 0 packet is unicast and should be sent to dst_host_ids and there are dst_host_ids_entries in the buffer. 1 packet is broadcast/multicast and is sent all hosts. contents of dst_host_ids and dst_host_ids_entries are ignored. (see also kronosnetd/etherfilter.* for an example that filters based on ether protocol)
 .SH RETURN VALUE

diff --git a/libknet/man/knet_handle_get_transport_name_by_id.3 b/libknet/man/knet_handle_get_transport_name_by_id.3
@@ -18,7 +18,7 @@ knet_handle_get_transport_name_by_id
 .PP 
 knet_h - pointer to knet_handle_t
 .PP 
-transport - one of the above KNET_TRANSPORT_xxx constants
+transport - one of the KNET_TRANSPORT_xxx constants
 .SH RETURN VALUE
 .PP
 knet_handle_get_transport_name_by_id returns:

diff --git a/libknet/man/knet_handle_new.3 b/libknet/man/knet_handle_new.3
@@ -19,9 +19,9 @@ knet_handle_new
 .PP 
 host_id - Each host in a knet is identified with a unique ID. when creating a new handle local host_id must be specified (0 to UINT16T_MAX are all valid). It is the user's responsibility to check that the value is unique, or bad things might happen.
 .PP 
-log_fd - Write file descriptor. If set to a value > 0, it will be used to write log packets (see below) from libknet to the application. Setting to 0 will disable logging from libknet. It is possible to enable logging at any given time (see logging API below). Make sure to either read from this filedescriptor properly and/or mark it O_NONBLOCK, otherwise if the fd becomes full, libknet could block.
+log_fd - Write file descriptor. If set to a value > 0, it will be used to write log packets from libknet to the application. Setting to 0 will disable logging from libknet. It is possible to enable logging at any given time (see logging API). Make sure to either read from this filedescriptor properly and/or mark it O_NONBLOCK, otherwise if the fd becomes full, libknet could block.
 .PP 
-default_log_level - If logfd is specified, it will initialize all subsystems to log at default_log_level value. (see logging API below)
+default_log_level - If logfd is specified, it will initialize all subsystems to log at default_log_level value. (see logging API)
 .SH RETURN VALUE
 .PP
 on success, a new knet_handle_t is returned. on failure, NULL is returned and errno is set. 

diff --git a/libknet/man/knet_host_enable_status_change_notify.3 b/libknet/man/knet_host_enable_status_change_notify.3
@@ -19,7 +19,7 @@ knet_host_enable_status_change_notify
 .PP 
 knet_h - pointer to knet_handle_t
 .PP 
-host_status_change_notify_fn_private_data void pointer to data that can be used to identify the callback.
+host_status_change_notify_fn_private_data - void pointer to data that can be used to identify the callback
 .PP 
 external, 0 if the host_id is configured locally or 1 if it has been added from remote nodes config. NOTE: dynamic topology is NOT currently implemented, but this is ready for future and can avoid an API/ABI breakage later on. This function MUST NEVER block or add substantial delays.
 .SH RETURN VALUE

diff --git a/libknet/man/knet_host_get_status.3 b/libknet/man/knet_host_get_status.3
@@ -19,6 +19,8 @@ knet_host_status_get
 .PP 
 knet_h - pointer to knet_handle_t
 .PP 
+host_id - see knet_host_add(3)
+.PP 
 status - pointer to knet_host_status struct
 .SH STRUCTURES
 .SS ""

diff --git a/libknet/man/knet_host_set_name.3 b/libknet/man/knet_host_set_name.3
@@ -19,7 +19,7 @@ knet_host_set_name
 .PP 
 knet_h - pointer to knet_handle_t
 .PP 
-host_id - see above
+host_id - see knet_host_add(3)
 .PP 
 name - this name will be used for pretty logging and eventually search for hosts (see also knet_handle_host_get_name(2) and knet_handle_host_get_id(3)). Only up to KNET_MAX_HOST_LEN - 1 bytes will be accepted and name has to be unique for each host.
 .SH RETURN VALUE

diff --git a/libknet/man/knet_host_set_policy.3 b/libknet/man/knet_host_set_policy.3
@@ -21,7 +21,7 @@ knet_h - pointer to knet_handle_t
 .PP 
 host_id - see knet_host_add(3)
 .PP 
-policy - there are currently 3 kind of simple switching policies as defined above, based on link configuration. KNET_LINK_POLICY_PASSIVE - the active link with the lowest priority will be used. if one or more active links share the same priority, the one with lowest link_id will be used.
+policy - there are currently 3 kind of simple switching policies based on link configuration. KNET_LINK_POLICY_PASSIVE - the active link with the lowest priority will be used. if one or more active links share the same priority, the one with lowest link_id will be used.
 .PP 
 KNET_LINK_POLICY_ACTIVE - all active links will be used simultaneously to send traffic. link priority is ignored.
 .PP 

diff --git a/libknet/man/knet_link_clear_config.3 b/libknet/man/knet_link_clear_config.3
@@ -19,9 +19,9 @@ knet_link_clear_config
 .PP 
 knet_h - pointer to knet_handle_t
 .PP 
-host_id - see above
+host_id - see knet_host_add(3)
 .PP 
-link_id - see above
+link_id - see knet_link_set_config(3)
 .SH RETURN VALUE
 .PP
 knet_link_clear_config returns 0 on success. -1 on error and errno is set. 

diff --git a/libknet/man/knet_link_get_enable.3 b/libknet/man/knet_link_get_enable.3
@@ -20,9 +20,9 @@ knet_link_get_enable
 .PP 
 knet_h - pointer to knet_handle_t
 .PP 
-host_id - see above
+host_id - see knet_host_add(3)
 .PP 
-link_id - see above
+link_id - see knet_link_set_config(3)
 .PP 
 enabled - 0 disable the link, 1 enable the link
 .SH RETURN VALUE

diff --git a/libknet/man/knet_link_get_ping_timers.3 b/libknet/man/knet_link_get_ping_timers.3
@@ -22,15 +22,15 @@ knet_link_get_ping_timers
 .PP 
 knet_h - pointer to knet_handle_t
 .PP 
-host_id - see above
+host_id - see knet_host_add(3)
 .PP 
-link_id - see above
+link_id - see knet_link_set_config(3)
 .PP 
-interval - ping intervall
+interval - ping interval
 .PP 
 timeout - if no pong is received within this time, the link is declared dead
 .PP 
-precision - how many values of latency are used to calculate the average link latency (see also get_status below)
+precision - how many values of latency are used to calculate the average link latency (see also knet_link_get_status(3))
 .SH RETURN VALUE
 .PP
 knet_link_get_ping_timers returns 0 on success -1 on error and errno is set. 

diff --git a/libknet/man/knet_link_get_pong_count.3 b/libknet/man/knet_link_get_pong_count.3
@@ -2,7 +2,7 @@
 .\" Generation date: Mon Oct 30 2017
 .TH knet_link_get_pong_count 3 2017-10-30 "kronosnet" "Kronosnet Programmer's Manual"
 .SH "NAME"
-knet_link_get_pong_count \- Get the poing count for a link.
+knet_link_get_pong_count \- Get the pong count for a link.
 .SH SYNOPSIS
 .nf
 .B #include <libknet.h>
@@ -20,11 +20,11 @@ knet_link_get_pong_count
 .PP 
 knet_h - pointer to knet_handle_t
 .PP 
-host_id - see above
+host_id - see knet_host_add(3)
 .PP 
-link_id - see above
+link_id - see knet_link_set_config(3)
 .PP 
-pong_count - see above
+pong_count - how many valid ping/pongs before a link is marked UP. default: 5, value should be > 0
 .SH RETURN VALUE
 .PP
 knet_link_get_pong_count returns 0 on success -1 on error and errno is set. 

diff --git a/libknet/man/knet_link_get_priority.3 b/libknet/man/knet_link_get_priority.3
@@ -20,9 +20,9 @@ knet_link_get_priority
 .PP 
 knet_h - pointer to knet_handle_t
 .PP 
-host_id - see above
+host_id - see knet_host_add(3)
 .PP 
-link_id - see above
+link_id - see knet_link_set_config(3)
 .PP 
 priority - gather the switching priority for this link see also knet_host_set_policy
 .SH RETURN VALUE

diff --git a/libknet/man/knet_link_get_status.3 b/libknet/man/knet_link_get_status.3
@@ -21,11 +21,11 @@ knet_link_get_status
 .PP 
 knet_h - pointer to knet_handle_t
 .PP 
-host_id - see above
+host_id - see knet_host_add(3)
 .PP 
-link_id - see above
+link_id - see knet_link_set_config(3)
 .PP 
-status - pointer to knet_link_status struct (see above)
+status - pointer to knet_link_status struct
 .PP 
 struct_size - max size of knet_link_status - allows library to add fields without ABI change. Returned structure will be truncated to this length and .size member indicates the full size.
 .SH STRUCTURES

diff --git a/libknet/man/knet_link_set_config.3 b/libknet/man/knet_link_set_config.3
@@ -27,7 +27,7 @@ host_id - see knet_host_add(3)
 .PP 
 link_id - see knet_link_set_config(3)
 .PP 
-transport - one of the above KNET_TRANSPORT_xxx constants
+transport - one of the KNET_TRANSPORT_xxx constants
 .PP 
 src_addr - sockaddr_storage that can be either IPv4 or IPv6
 .PP 

diff --git a/libknet/man/knet_link_set_enable.3 b/libknet/man/knet_link_set_enable.3
@@ -20,9 +20,9 @@ knet_link_set_enable
 .PP 
 knet_h - pointer to knet_handle_t
 .PP 
-host_id - see above
+host_id - see knet_host_add(3)
 .PP 
-link_id - see above
+link_id - see knet_link_set_config(3)
 .PP 
 enabled - 0 disable the link, 1 enable the link
 .SH RETURN VALUE

diff --git a/libknet/man/knet_link_set_ping_timers.3 b/libknet/man/knet_link_set_ping_timers.3
@@ -22,15 +22,15 @@ knet_link_set_ping_timers
 .PP 
 knet_h - pointer to knet_handle_t
 .PP 
-host_id - see above
+host_id - see knet_host_add(3)
 .PP 
-link_id - see above
+link_id - see knet_link_set_config(3)
 .PP 
 interval - specify the ping interval
 .PP 
 timeout - if no pong is received within this time, the link is declared dead
 .PP 
-precision - how many values of latency are used to calculate the average link latency (see also get_status below)
+precision - how many values of latency are used to calculate the average link latency (see also knet_link_get_status(3))
 .SH RETURN VALUE
 .PP
 knet_link_set_ping_timers returns 0 on success -1 on error and errno is set. 

diff --git a/libknet/man/knet_link_set_pong_count.3 b/libknet/man/knet_link_set_pong_count.3
@@ -2,7 +2,7 @@
 .\" Generation date: Mon Oct 30 2017
 .TH knet_link_set_pong_count 3 2017-10-30 "kronosnet" "Kronosnet Programmer's Manual"
 .SH "NAME"
-knet_link_set_pong_count \- Set the poing count for a link.
+knet_link_set_pong_count \- Set the pong count for a link.
 .SH SYNOPSIS
 .nf
 .B #include <libknet.h>
@@ -20,9 +20,9 @@ knet_link_set_pong_count
 .PP 
 knet_h - pointer to knet_handle_t
 .PP 
-host_id - see above
+host_id - see knet_host_add(3)
 .PP 
-link_id - see above
+link_id - see knet_link_set_config(3)
 .PP 
 pong_count - how many valid ping/pongs before a link is marked UP. default: 5, value should be > 0
 .SH RETURN VALUE

diff --git a/libknet/man/knet_link_set_priority.3 b/libknet/man/knet_link_set_priority.3
@@ -20,9 +20,9 @@ knet_link_set_priority
 .PP 
 knet_h - pointer to knet_handle_t
 .PP 
-host_id - see above
+host_id - see knet_host_add(3)
 .PP 
-link_id - see above
+link_id - see knet_link_set_config(3)
 .PP 
 priority - specify the switching priority for this link see also knet_host_set_policy
 .SH RETURN VALUE

diff --git a/libknet/man/knet_recv.3 b/libknet/man/knet_recv.3
@@ -21,6 +21,8 @@ knet_recv knet_h - pointer to knet_handle_t
 buff - pointer to buffer to store the received data
 .PP 
 buff_len - buffer length
+.PP 
+channel - channel number
 .SH RETURN VALUE
 .PP
 knet_recv is a commodity function to wrap iovec operations around a socket. It returns a call to readv(2). 

diff --git a/libknet/man/knet_send.3 b/libknet/man/knet_send.3
@@ -21,6 +21,8 @@ knet_send knet_h - pointer to knet_handle_t
 buff - pointer to the buffer of data to send
 .PP 
 buff_len - length of data to send
+.PP 
+channel - channel number
 .SH RETURN VALUE
 .PP
 knet_send is a commodity function to wrap iovec operations around a socket. It returns a call to writev(2). 

diff --git a/libknet/man/libknet.h.3 b/libknet/man/libknet.h.3
@@ -83,10 +83,12 @@ int           knet_strtoaddr(const char *, const char *, struct sockaddr_storage
 .RS
 .nf
 \fB
-struct knet_host_status {
-  uint8_t  \fIreachable\fP;
-  uint8_t  \fIremote\fP;
-  uint8_t  \fIexternal\fP;
+struct knet_handle_crypto_cfg {
+  char          \fIcrypto_model\fP;
+  char          \fIcrypto_cipher_type\fP;
+  char          \fIcrypto_hash_type\fP;
+  unsigned char \fIprivate_key\fP;
+  unsigned int  \fIprivate_key_len\fP;
 };
 \fP
 .fi
@@ -98,10 +100,30 @@ struct knet_host_status {
 .RS
 .nf
 \fB
-struct transport_info {
-  const char  *\fIname\fP;
-  uint8_t      \fIid\fP;
-  uint8_t      \fIproperties\fP;
+struct knet_handle_stats {
+  size_t   \fIsize\fP;
+  uint64_t \fItx_uncompressed_packets\fP;
+  uint64_t \fItx_compressed_packets\fP;
+  uint64_t \fItx_compressed_original_bytes\fP;
+  uint64_t \fItx_compressed_size_bytes\fP;
+  uint64_t \fItx_compress_time_ave\fP;
+  uint64_t \fItx_compress_time_min\fP;
+  uint64_t \fItx_compress_time_max\fP;
+  uint64_t \fIrx_compressed_packets\fP;
+  uint64_t \fIrx_compressed_original_bytes\fP;
+  uint64_t \fIrx_compressed_size_bytes\fP;
+  uint64_t \fIrx_compress_time_ave\fP;
+  uint64_t \fIrx_compress_time_min\fP;
+  uint64_t \fIrx_compress_time_max\fP;
+  uint64_t \fItx_crypt_packets\fP;
+  uint64_t \fItx_crypt_byte_overhead\fP;
+  uint64_t \fItx_crypt_time_ave\fP;
+  uint64_t \fItx_crypt_time_min\fP;
+  uint64_t \fItx_crypt_time_max\fP;
+  uint64_t \fIrx_crypt_packets\fP;
+  uint64_t \fIrx_crypt_time_ave\fP;
+  uint64_t \fIrx_crypt_time_min\fP;
+  uint64_t \fIrx_crypt_time_max\fP;
 };
 \fP
 .fi
@@ -113,12 +135,10 @@ struct transport_info {
 .RS
 .nf
 \fB
-struct knet_handle_crypto_cfg {
-  char          \fIcrypto_model\fP;
-  char          \fIcrypto_cipher_type\fP;
-  char          \fIcrypto_hash_type\fP;
-  unsigned char \fIprivate_key\fP;
-  unsigned int  \fIprivate_key_len\fP;
+struct transport_info {
+  const char  *\fIname\fP;
+  uint8_t      \fIid\fP;
+  uint8_t      \fIproperties\fP;
 };
 \fP
 .fi
@@ -145,30 +165,10 @@ struct knet_handle_compress_cfg {
 .RS
 .nf
 \fB
-struct knet_handle_stats {
-  size_t   \fIsize\fP;
-  uint64_t \fItx_uncompressed_packets\fP;
-  uint64_t \fItx_compressed_packets\fP;
-  uint64_t \fItx_compressed_original_bytes\fP;
-  uint64_t \fItx_compressed_size_bytes\fP;
-  uint64_t \fItx_compress_time_ave\fP;
-  uint64_t \fItx_compress_time_min\fP;
-  uint64_t \fItx_compress_time_max\fP;
-  uint64_t \fIrx_compressed_packets\fP;
-  uint64_t \fIrx_compressed_original_bytes\fP;
-  uint64_t \fIrx_compressed_size_bytes\fP;
-  uint64_t \fIrx_compress_time_ave\fP;
-  uint64_t \fIrx_compress_time_min\fP;
-  uint64_t \fIrx_compress_time_max\fP;
-  uint64_t \fItx_crypt_packets\fP;
-  uint64_t \fItx_crypt_byte_overhead\fP;
-  uint64_t \fItx_crypt_time_ave\fP;
-  uint64_t \fItx_crypt_time_min\fP;
-  uint64_t \fItx_crypt_time_max\fP;
-  uint64_t \fIrx_crypt_packets\fP;
-  uint64_t \fIrx_crypt_time_ave\fP;
-  uint64_t \fIrx_crypt_time_min\fP;
-  uint64_t \fIrx_crypt_time_max\fP;
+struct knet_host_status {
+  uint8_t  \fIreachable\fP;
+  uint8_t  \fIremote\fP;
+  uint8_t  \fIexternal\fP;
 };
 \fP
 .fi