[PATCH libnetfilter_log v2] src: doc: revise doxygen for all other modules

[PATCH libnetfilter_log v2] 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
 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

Re: [PATCH libnetfilter_log v2] src: doc: revise doxygen for all other modules

[Duncan Roe]

Hi Pablo,

You applied v3. No need to keep this one in the patchwork.

Cheers ... Duncan.