Introduce some new doxygen content. Not yet converted to use libmnl.
Signed-off-by: Duncan Roe <duncan_roe@xxxxxxxxxxxxxxx>
---
doxygen/Makefile.am | 1 +
doxygen/doxygen.cfg.in | 2 ++
src/iftable.c | 53 +++++++++++++++++++++++++-----------------
3 files changed, 35 insertions(+), 21 deletions(-)
diff --git a/doxygen/Makefile.am b/doxygen/Makefile.am
index 6135f25..aae1ccc 100644
--- a/doxygen/Makefile.am
+++ b/doxygen/Makefile.am
@@ -2,6 +2,7 @@ if HAVE_DOXYGEN
doc_srcs = $(top_srcdir)/src/libnetfilter_queue.c\
$(top_srcdir)/src/nlmsg.c\
+ $(top_srcdir)/src/iftable.c\
$(top_srcdir)/src/extra/checksum.c\
$(top_srcdir)/src/extra/ipv4.c\
$(top_srcdir)/src/extra/pktbuff.c\
diff --git a/doxygen/doxygen.cfg.in b/doxygen/doxygen.cfg.in
index e69dcd7..c795df1 100644
--- a/doxygen/doxygen.cfg.in
+++ b/doxygen/doxygen.cfg.in
@@ -17,6 +17,8 @@ EXCLUDE_SYMBOLS = EXPORT_SYMBOL \
nfnl_handle \
nfnl_subsys_handle \
mnl_socket \
+ ifindex_node \
+ nlif_handle \
nfnl_callback2 \
tcp_flag_word
EXAMPLE_PATTERNS =
diff --git a/src/iftable.c b/src/iftable.c
index aab59b3..22c3952 100644
--- a/src/iftable.c
+++ b/src/iftable.c
@@ -2,6 +2,7 @@
*
* (C) 2004 by Astaro AG, written by Harald Welte <hwelte@xxxxxxxxxx>
* (C) 2008 by Pablo Neira Ayuso <pablo@xxxxxxxxxxxxx>
+ * (C) 2024 by Duncan Roe <duncan_roe@xxxxxxxxxxxxxxx>
*
* This software is Free Software and licensed under GNU GPLv2+.
*/
@@ -25,11 +26,14 @@
#include "linux_list.h"
/**
- * \defgroup iftable Functions in iftable.c [DEPRECATED]
- * This documentation is provided for the benefit of maintainers of legacy code.
+ * \defgroup iftable Functions to manage a table of network interfaces
+ * These functions maintain a database of the name and flags of each
+ * network interface.
*
- * New applications should use
- * [libmnl](https://netfilter.org/projects/libmnl/doxygen/html/).
+ * mnl API programs may instead use
+ * [libmnl](https://netfilter.org/projects/libmnl/doxygen/html/)
+ * calls directly to maintain an
+ * interface table with more (or less!) data points, e.g. MTU.
* @{
*/
@@ -52,8 +56,8 @@ struct nlif_handle {
};
/* iftable_add - Add/Update an entry to/in the interface table
- * @n: netlink message header of a RTM_NEWLINK message
- * @arg: not used
+ * \param n: netlink message header of a RTM_NEWLINK message
+ * \param arg: not used
*
* This function adds/updates an entry in the intrface table.
* Returns -1 on error, 1 on success.
@@ -114,8 +118,8 @@ static int iftable_add(struct nlmsghdr *n, void *arg)
}
/* iftable_del - Delete an entry from the interface table
- * @n: netlink message header of a RTM_DELLINK nlmsg
- * @arg: not used
+ * \param n: netlink message header of a RTM_DELLINK nlmsg
+ * \param arg: not used
*
* Delete an entry from the interface table.
* Returns -1 on error, 0 if no matching entry was found or 1 on success.
@@ -148,9 +152,10 @@ static int iftable_del(struct nlmsghdr *n, void *arg)
return 0;
}
-/** Get the name for an ifindex
+/**
+ * nlif_index2name - get the name for an ifindex
*
- * \param nlif_handle A pointer to a ::nlif_handle created
+ * \param h pointer to nlif_handle created by nlif_open()
* \param index ifindex to be resolved
* \param name interface name, pass a buffer of IFNAMSIZ size
* \return -1 on error, 1 on success
@@ -182,9 +187,10 @@ int nlif_index2name(struct nlif_handle *h,
return -1;
}
-/** Get the flags for an ifindex
+/**
+ * nlif_get_ifflags - get the flags for an ifindex
*
- * \param nlif_handle A pointer to a ::nlif_handle created
+ * \param h pointer to nlif_handle created by nlif_open()
* \param index ifindex to be resolved
* \param flags pointer to variable used to store the interface flags
* \return -1 on error, 1 on success
@@ -215,7 +221,8 @@ int nlif_get_ifflags(const struct nlif_handle *h,
return -1;
}
-/** Initialize interface table
+/**
+ * nlif_open - initialize interface table
*
* Initialize rtnl interface and interface table
* Call this before any nlif_* function
@@ -262,10 +269,10 @@ err:
return NULL;
}
-/** Destructor of interface table
+/**
+ * nlif_close - free all resources associated with the interface table
*
- * \param nlif_handle A pointer to a ::nlif_handle created
- * via nlif_open()
+ * \param h pointer to nlif_handle created by nlif_open()
*/
void nlif_close(struct nlif_handle *h)
{
@@ -289,9 +296,12 @@ void nlif_close(struct nlif_handle *h)
h = NULL; /* bugtrap */
}
-/** Receive message from netlink and update interface table
+/**
+ * nlif_catch - receive message from netlink and update interface table
+ *
+ * FIXME - elaborate a bit
*
- * \param nlif_handle A pointer to a ::nlif_handle created
+ * \param h pointer to nlif_handle created by nlif_open()
* \return 0 if OK
*/
int nlif_catch(struct nlif_handle *h)
@@ -316,7 +326,7 @@ static int nlif_catch_multi(struct nlif_handle *h)
/**
* nlif_query - request a dump of interfaces available in the system
- * @h: pointer to a valid nlif_handler
+ * \param h: pointer to a valid nlif_handler
*/
int nlif_query(struct nlif_handle *h)
{
@@ -328,9 +338,10 @@ int nlif_query(struct nlif_handle *h)
return nlif_catch_multi(h);
}
-/** Returns socket descriptor for the netlink socket
+/**
+ * nlif_fd - get file descriptor for the netlink socket
*
- * \param nlif_handle A pointer to a ::nlif_handle created
+ * \param h pointer to nlif_handle created by nlif_open()
* \return The fd or -1 if there's an error
*/
int nlif_fd(struct nlif_handle *h)
--
2.35.8
