[PATCH libnetfilter_queue v3 1/4] src: doc: revise doxygen for all other modules

[PATCH libnetfilter_queue v3 1/4] src: doc: revise doxygen for all other modules

[Duncan Roe]

I.e. all modules except "Netlink message helper functions"
- different cross-reference for man page and html
- remove duplicate description for nflog_fd
- try to differentiate between "rare" and "common" errors
- gh is a Netfilter log *group* handle (cf h)
- minor native English corrections
- update Linux source reference
- document actual return values

Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au>
---
v2: Add man page cross reference for LibrarySetup
v3: Same as v2 but 3 extra patches have banked up behind this one
 src/libnetfilter_log.c | 100 +++++++++++++++++++++++++++++------------
 1 file changed, 71 insertions(+), 29 deletions(-)

diff --git a/src/libnetfilter_log.c b/src/libnetfilter_log.c
index 546d667..8124a30 100644
--- a/src/libnetfilter_log.c
+++ b/src/libnetfilter_log.c
@@ -207,8 +207,21 @@ struct nfnl_handle *nflog_nfnlh(struct nflog_handle *h)
 	}
 \endverbatim
  *
- * Data and information about the packet can be fetch by using message parsing
- * functions (See \link Parsing \endlink).
+ * Data and information about the packet can be fetched by using message parsing
+ * \htmlonly
+ functions (See <a class="el" href="group__Parsing.html">Parsing</a>).
+\endhtmlonly
+ * \manonly
+functions.
+.PP
+\fBSee also:\fP
+.RS 4
+\fBLibrarySetup\fP man page (\fBman nflog_open\fP)
+.br
+\fBParsing\fP man page (\fBman nflog_get_gid\fP)
+.RE
+.PP
+\endmanonly
  * @{
  */
 
@@ -220,9 +233,6 @@ struct nfnl_handle *nflog_nfnlh(struct nflog_handle *h)
  * given log connection handle. The file descriptor can then be used for
  * receiving the logged packets for processing.
  *
- * This function returns a file descriptor that can be used for communication
- * over the netlink connection associated with the given log connection
- * handle.
  */
 int nflog_fd(struct nflog_handle *h)
 {
@@ -279,7 +289,9 @@ out_free:
  * it by calling nflog_close(). A new netlink connection is obtained internally
  * and associated with the log connection handle returned.
  *
- * \return a pointer to a new log handle or NULL on failure.
+ * \return a pointer to a new log handle or NULL on failure with \b errno set.
+ * \par Errors
+ * from underlying calls, in exceptional circumstances
  */
 struct nflog_handle *nflog_open(void)
 {
@@ -335,7 +347,9 @@ int nflog_handle_packet(struct nflog_handle *h, char *buf, int len)
  *
  * This function closes the nflog handler and free associated resources.
  *
- * \return 0 on success, non-zero on failure.
+ * \return 0 on success, -1 on failure with \b errno set.
+ * \par Errors
+ * as for __close__(2)
  */
 int nflog_close(struct nflog_handle *h)
 {
@@ -352,7 +366,9 @@ int nflog_close(struct nflog_handle *h)
  * Binds the given log connection handle to process packets belonging to
  * the given protocol family (ie. PF_INET, PF_INET6, etc).
  *
- * \return integer inferior to 0 in case of failure
+ * \return 0 on success, -1 on failure with \b errno set.
+ * \par Errors
+ * \b EOPNOTSUPP Not running as root
  */
 int nflog_bind_pf(struct nflog_handle *h, uint16_t pf)
 {
@@ -367,6 +383,9 @@ int nflog_bind_pf(struct nflog_handle *h, uint16_t pf)
  *
  * Unbinds the given nflog handle from processing packets belonging
  * to the given protocol family.
+ * \return 0 on success, -1 on failure with \b errno set.
+ * \par Errors
+ * \b EOPNOTSUPP Not running as root
  */
 int nflog_unbind_pf(struct nflog_handle *h, uint16_t pf)
 {
@@ -387,15 +406,22 @@ int nflog_unbind_pf(struct nflog_handle *h, uint16_t pf)
  * \param h Netfilter log handle obtained via call to nflog_open()
  * \param num the number of the group to bind to
  *
- * \return a nflog_g_handle pointing to the newly created group
+ * \return an nflog_g_handle for the newly created group or NULL on failure.
+ * \par Errors
+ * \b EBUSY This process has already binded to the group
+ * \n
+ * \b EOPNOTSUPP Request rejected by kernel. Another process has already
+ * binded to the group, or this process is not running as root
  */
 struct nflog_g_handle *
 nflog_bind_group(struct nflog_handle *h, uint16_t num)
 {
 	struct nflog_g_handle *gh;
 
-	if (find_gh(h, num))
+	if (find_gh(h, num)) {
+		errno = EBUSY;
 		return NULL;
+	}
 
 	gh = calloc(1, sizeof(*gh));
 	if (!gh)
@@ -426,7 +452,9 @@ nflog_bind_group(struct nflog_handle *h, uint16_t num)
  * nflog_unbind_group - unbind a group handle.
  * \param gh Netfilter log group handle obtained via nflog_bind_group()
  *
- * \return -1 in case of error and errno is explicity in case of error.
+ * \return 0 on success, -1 on failure with \b errno set.
+ * \par Errors
+ * from underlying calls, in exceptional circumstances
  */
 int nflog_unbind_group(struct nflog_g_handle *gh)
 {
@@ -441,7 +469,7 @@ int nflog_unbind_group(struct nflog_g_handle *gh)
 
 /**
  * nflog_set_mode - set the amount of packet data that nflog copies to userspace
- * \param gh Netfilter log handle obtained by call to nflog_bind_group().
+ * \param gh Netfilter log group handle obtained by call to nflog_bind_group().
  * \param mode the part of the packet that we are interested in
  * \param range size of the packet that we want to get
  *
@@ -452,7 +480,9 @@ int nflog_unbind_group(struct nflog_g_handle *gh)
  * - NFULNL_COPY_META - copy only packet metadata
  * - NFULNL_COPY_PACKET - copy entire packet
  *
- * \return -1 on error; >= otherwise.
+ * \return 0 on success, -1 on failure with \b errno set.
+ * \par Errors
+ * from underlying calls, in exceptional circumstances
  */
 int nflog_set_mode(struct nflog_g_handle *gh,
 		   uint8_t mode, uint32_t range)
@@ -477,7 +507,7 @@ int nflog_set_mode(struct nflog_g_handle *gh,
 
 /**
  * nflog_set_timeout - set the maximum time to push log buffer for this group
- * \param gh Netfilter log handle obtained by call to nflog_bind_group().
+ * \param gh Netfilter log group handle obtained by call to nflog_bind_group().
  * \param timeout Time to wait until the log buffer is pushed to userspace
  *
  * This function allows to set the maximum time that nflog waits until it
@@ -485,7 +515,9 @@ int nflog_set_mode(struct nflog_g_handle *gh,
  * Basically, nflog implements a buffer to reduce the computational cost
  * of delivering the log message to userspace.
  *
- * \return -1 in case of error and errno is explicity set.
+ * \return 0 on success, -1 on failure with \b errno set.
+ * \par Errors
+ * from underlying calls, in exceptional circumstances
  */
 int nflog_set_timeout(struct nflog_g_handle *gh, uint32_t timeout)
 {
@@ -504,13 +536,15 @@ int nflog_set_timeout(struct nflog_g_handle *gh, uint32_t timeout)
 
 /**
  * nflog_set_qthresh - set the maximum amount of logs in buffer for this group
- * \param gh Netfilter log handle obtained by call to nflog_bind_group().
+ * \param gh Netfilter log group handle obtained by call to nflog_bind_group().
  * \param qthresh Maximum number of log entries
  *
  * This function determines the maximum number of log entries in the buffer
  * until it is pushed to userspace.
  *
- * \return -1 in case of error and errno is explicity set.
+ * \return 0 on success, -1 on failure with \b errno set.
+ * \par Errors
+ * from underlying calls, in exceptional circumstances
  */
 int nflog_set_qthresh(struct nflog_g_handle *gh, uint32_t qthresh)
 {
@@ -529,17 +563,19 @@ int nflog_set_qthresh(struct nflog_g_handle *gh, uint32_t qthresh)
 
 /**
  * nflog_set_nlbufsiz - set the size of the nflog buffer for this group
- * \param gh Netfilter log handle obtained by call to nflog_bind_group().
+ * \param gh Netfilter log group handle obtained by call to nflog_bind_group().
  * \param nlbufsiz Size of the nflog buffer
  *
  * This function sets the size (in bytes) of the buffer that is used to
  * stack log messages in nflog.
  *
- * NOTE: The use of this function is strongly discouraged. The default
+ * \warning The use of this function is strongly discouraged. The default
  * buffer size (which is one memory page) provides the optimum results
  * in terms of performance. Do not use this function in your applications.
  *
- * \return -1 in case of error and errno is explicity set.
+ * \return 0 on success, -1 on failure with \b errno set.
+ * \par Errors
+ * from underlying calls, in exceptional circumstances
  */
 int nflog_set_nlbufsiz(struct nflog_g_handle *gh, uint32_t nlbufsiz)
 {
@@ -565,7 +601,7 @@ int nflog_set_nlbufsiz(struct nflog_g_handle *gh, uint32_t nlbufsiz)
 
 /**
  * nflog_set_flags - set the nflog flags for this group
- * \param gh Netfilter log handle obtained by call to nflog_bind_group().
+ * \param gh Netfilter log group handle obtained by call to nflog_bind_group().
  * \param flags Flags that you want to set
  *
  * There are two existing flags:
@@ -573,7 +609,9 @@ int nflog_set_nlbufsiz(struct nflog_g_handle *gh, uint32_t nlbufsiz)
  *	- NFULNL_CFG_F_SEQ: This enables local nflog sequence numbering.
  *	- NFULNL_CFG_F_SEQ_GLOBAL: This enables global nflog sequence numbering.
  *
- * \return -1 in case of error and errno is explicity set.
+ * \return 0 on success, -1 on failure with \b errno set.
+ * \par Errors
+ * from underlying calls, in exceptional circumstances
  */
 int nflog_set_flags(struct nflog_g_handle *gh, uint16_t flags)
 {
@@ -671,9 +709,11 @@ uint32_t nflog_get_nfmark(struct nflog_data *nfad)
  * \param nfad Netlink packet data handle passed to callback function
  * \param tv structure to fill with timestamp info
  *
- * Retrieves the received timestamp when the given logged packet.
+ * Retrieves the received timestamp from the given logged packet.
  *
- * \return 0 on success, a negative value on failure.
+ * \return 0 on success, -1 on failure with \b errno set.
+ * \par Errors
+ * from underlying calls, in exceptional circumstances
  */
 int nflog_get_timestamp(struct nflog_data *nfad, struct timeval *tv)
 {
@@ -698,8 +738,8 @@ int nflog_get_timestamp(struct nflog_data *nfad, struct timeval *tv)
  * returned index is 0, the packet was locally generated or the input
  * interface is not known (ie. POSTROUTING?).
  *
- * \warning all nflog_get_dev() functions return 0 if not set, since linux
- * only allows ifindex >= 1, see net/core/dev.c:2600  (in 2.6.13.1)
+ * \warning all nflog_get_dev() functions return 0 if not set, since Linux
+ * only allows ifindex >= 1, see net/core/dev.c:9819  (in 5.14.3)
  */
 uint32_t nflog_get_indev(struct nflog_data *nfad)
 {
@@ -782,7 +822,7 @@ struct nfulnl_msg_packet_hw *nflog_get_packet_hw(struct nflog_data *nfad)
  * data retrieved by this function will depend on the mode set with the
  * nflog_set_mode() function.
  *
- * \return -1 on error, otherwise > 0.
+ * \return payload length, or -1 if this is not available
  */
 int nflog_get_payload(struct nflog_data *nfad, char **data)
 {
@@ -798,7 +838,7 @@ int nflog_get_payload(struct nflog_data *nfad, char **data)
  * \param nfad Netlink packet data handle passed to callback function
  *
  * \return the string prefix that is specified as argument to the iptables'
- * NFLOG target.
+ * NFLOG target or NULL if this is not available.
  */
 char *nflog_get_prefix(struct nflog_data *nfad)
 {
@@ -919,11 +959,13 @@ do {								\
  *	- NFLOG_XML_TIME: include the timestamp
  *	- NFLOG_XML_ALL: include all the logging information (all flags set)
  *
- * You can combine this flags with an binary OR.
+ * You can combine these flags with a bitwise OR.
  *
  * \return -1 in case of failure, otherwise the length of the string that
  * would have been printed into the buffer (in case that there is enough
  * room in it). See snprintf() return value for more information.
+ * \par Errors
+ * from underlying calls, in exceptional circumstances
  */
 int nflog_snprintf_xml(char *buf, size_t rem, struct nflog_data *tb, int flags)
 {
-- 
2.17.5

[PATCH libnetfilter_queue v3 2/4] src: doc: Insert SYNOPSIS sections for man pages

[Duncan Roe]

Also a few more minor native English corrections

Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au>
---
 src/libnetfilter_log.c | 37 ++++++++++++++++++++++++++++++-------
 src/nlmsg.c            |  7 +++++++
 2 files changed, 37 insertions(+), 7 deletions(-)

diff --git a/src/libnetfilter_log.c b/src/libnetfilter_log.c
index 8124a30..581f612 100644
--- a/src/libnetfilter_log.c
+++ b/src/libnetfilter_log.c
@@ -221,6 +221,11 @@ functions.
 \fBParsing\fP man page (\fBman nflog_get_gid\fP)
 .RE
 .PP
+.SH SYNOPSIS
+.nf
+\fB
+#include <stddef.h>
+#include <libnetfilter_log/libnetfilter_log.h>
 \endmanonly
  * @{
  */
@@ -338,6 +343,13 @@ int nflog_handle_packet(struct nflog_handle *h, char *buf, int len)
  * When the program has finished with libnetfilter_log, it has to call
  * the nflog_close() function to release all associated resources.
  *
+ * \manonly
+.SH SYNOPSIS
+.nf
+\fB
+#include <netinet/in.h>
+#include <libnetfilter_log/libnetfilter_log.h>
+\endmanonly
  * @{
  */
 
@@ -634,6 +646,13 @@ int nflog_set_flags(struct nflog_g_handle *gh, uint16_t flags)
 
 /**
  * \defgroup Parsing Message parsing functions
+ * \manonly
+.SH SYNOPSIS
+.nf
+\fB
+#include <stddef.h>
+#include <libnetfilter_log/libnetfilter_log.h>
+\endmanonly
  * @{
  */
 
@@ -748,6 +767,7 @@ uint32_t nflog_get_indev(struct nflog_data *nfad)
 
 /**
  * nflog_get_physindev - get the physical interface that the packet was received
+ * through
  * \param nfad Netlink packet data handle passed to callback function
  *
  * \return The index of the physical device the packet was received via.
@@ -760,10 +780,10 @@ uint32_t nflog_get_physindev(struct nflog_data *nfad)
 }
 
 /**
- * nflog_get_outdev - gets the interface that the packet will be routed out
+ * nflog_get_outdev - gets the interface that the packet will be routed to
  * \param nfad Netlink packet data handle passed to callback function
  *
- * \return The index of the device the packet will be sent out.  If the
+ * \return The index of the device the packet will be sent to.  If the
  * returned index is 0, the packet is destined for localhost or the output
  * interface is not yet known (ie. PREROUTING?).
  */
@@ -773,15 +793,12 @@ uint32_t nflog_get_outdev(struct nflog_data *nfad)
 }
 
 /**
- * nflog_get_physoutdev - get the physical interface that the packet output
+ * nflog_get_physoutdev - get the physical interface for packet output
  * \param nfad Netlink packet data handle passed to callback function
  *
- * The index of the physical device the packet will be sent out. If the
+ * \return Index of physical device the packet will be routed to. If the
  * returned index is 0, the packet is destined for localhost or the
  * physical output interface is not yet known (ie. PREROUTING?).
- *
- * \return The index of physical interface that the packet output will be
- * routed out.
  */
 uint32_t nflog_get_physoutdev(struct nflog_data *nfad)
 {
@@ -938,6 +955,12 @@ do {								\
 
 /**
  * \defgroup Printing Printing
+ * \manonly
+.SH SYNOPSIS
+.nf
+\fB
+#include <libnetfilter_log/libnetfilter_log.h>
+\endmanonly
  * @{
  */
 
diff --git a/src/nlmsg.c b/src/nlmsg.c
index 98c6768..587a046 100644
--- a/src/nlmsg.c
+++ b/src/nlmsg.c
@@ -14,6 +14,13 @@
 
 /**
  * \defgroup nlmsg Netlink message helper functions
+ * \manonly
+.SH SYNOPSIS
+.nf
+\fB
+#include <netinet/in.h>
+#include <libnetfilter_log/libnetfilter_log.h>
+\endmanonly
  * @{
  */
 
-- 
2.17.5

[PATCH libnetfilter_queue v3 3/4] src: doc: Add \return for nflog_get_packet_hw()

[Duncan Roe]

Also indicate that hw_addrlen has NBO in struct nfulnl_msg_packet_hw

Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au>
---
 src/libnetfilter_log.c | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/src/libnetfilter_log.c b/src/libnetfilter_log.c
index 581f612..66669af 100644
--- a/src/libnetfilter_log.c
+++ b/src/libnetfilter_log.c
@@ -818,11 +818,15 @@ uint32_t nflog_get_physoutdev(struct nflog_data *nfad)
  * The nfulnl_msg_packet_hw structure is defined in libnetfilter_log.h as:
  * \verbatim
 	struct nfulnl_msg_packet_hw {
-		uint16_t       hw_addrlen;
+		uint16_t       hw_addrlen; // Network Byte Order
 		uint16_t       _pad;
 		uint8_t        hw_addr[8];
 	} __attribute__ ((packed));
 \endverbatim
+ *
+ * \return Pointer to struct nfulnl_msg_packet_hw from originating host
+ * or NULL if none available (e.g. locally-originated packet not for \b lo
+ * interface).
  */
 struct nfulnl_msg_packet_hw *nflog_get_packet_hw(struct nflog_data *nfad)
 {
-- 
2.17.5

[PATCH libnetfilter_queue v3 4/4] src: doc: Document nflog_callback_register() and nflog_handle_packet()

[Duncan Roe]

utils/nfulnl_test.c uses these functions

Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au>
---
 src/libnetfilter_log.c | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/src/libnetfilter_log.c b/src/libnetfilter_log.c
index 66669af..27a6a2d 100644
--- a/src/libnetfilter_log.c
+++ b/src/libnetfilter_log.c
@@ -323,6 +323,20 @@ struct nflog_handle *nflog_open(void)
  * @}
  */
 
+/**
+ * \addtogroup Log
+ * @{
+ */
+
+/**
+ * nflog_callback_register - register function to process packets
+ *
+ * \param gh Netfilter log group handle obtained by call to nflog_bind_group()
+ * \param cb callback function to call for each logged packet
+ * \param data custom data to pass to the callback function
+ \return 0
+ */
+
 int nflog_callback_register(struct nflog_g_handle *gh, nflog_callback *cb,
 			     void *data)
 {
@@ -332,11 +346,29 @@ int nflog_callback_register(struct nflog_g_handle *gh, nflog_callback *cb,
 	return 0;
 }
 
+/**
+ * nflog_handle_packet - handle a packet received from the nflog subsystem
+ * \param h Netfilter log handle obtained via call to nflog_open()
+ * \param buf nflog data received from the kernel
+ * \param len length of packet data in buffer
+ *
+ * Triggers an associated callback for each packet contained in \b buf.
+ * Data can be read from the queue using nflog_fd() and \b recv().
+ * See example code in the Detailed Description.
+ * \return 0 on success, -1 if either the callback returned -ve or \b buf
+ * contains corrupt data. \b errno is not reliably set:
+ * caller should zeroise first if interested.
+ */
+
 int nflog_handle_packet(struct nflog_handle *h, char *buf, int len)
 {
 	return nfnl_handle_packet(h->nfnlh, buf, len);
 }
 
+/**
+ * @}
+ */
+
 /**
  * \addtogroup LibrarySetup
  *
-- 
2.17.5

Re: [PATCH libnetfilter_queue v3 1/4] src: doc: revise doxygen for all other modules

[Duncan Roe]

Hi Pablo,

Sorry - the title line should have "PATCH libnetfilter_log" instead of
"PATCH libnetfilter_queue".

Would you prefer if I re-posted the series?

Please advise,

Cheers ... Duncan.