doc: add libnetfilter_log doxygen documentation and update copyright notice

This patch adds the libnetfilter_log documentation in doxygen format.
I have also added myself to the copyright header in the
libnetfilter_log.c file according to my contributions available in
the git repository.

Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>

3 files changed, 616 insertions, 6 deletions

diff --git a/configure.in b/configure.in
index 94bf52e..cdde6ad 100644
--- a/configure.in
+++ b/configure.in
@@ -31,5 +31,5 @@ LIBNFLOG_LIBS="$LIBNFNETLINK_LIBS"
 AC_SUBST(LIBNFLOG_LIBS)
 
 dnl Output the makefile
-AC_OUTPUT(Makefile src/Makefile include/Makefile include/libnetfilter_log/Makefile utils/Makefile libnetfilter_log.pc)
+AC_OUTPUT(Makefile src/Makefile include/Makefile include/libnetfilter_log/Makefile utils/Makefile libnetfilter_log.pc doxygen.cfg)
 
diff --git a/doxygen.cfg.in b/doxygen.cfg.in
new file mode 100644
index 0000000..37bfa7c
--- /dev/null
+++ b/doxygen.cfg.in
@@ -0,0 +1,184 @@
+DOXYFILE_ENCODING      = UTF-8
+PROJECT_NAME           = @PACKAGE@
+PROJECT_NUMBER         = @VERSION@
+OUTPUT_DIRECTORY       = doxygen
+CREATE_SUBDIRS         = NO
+OUTPUT_LANGUAGE        = English
+BRIEF_MEMBER_DESC      = YES
+REPEAT_BRIEF           = YES
+ABBREVIATE_BRIEF       = 
+ALWAYS_DETAILED_SEC    = NO
+INLINE_INHERITED_MEMB  = NO
+FULL_PATH_NAMES        = NO
+STRIP_FROM_PATH        = 
+STRIP_FROM_INC_PATH    = 
+SHORT_NAMES            = NO
+JAVADOC_AUTOBRIEF      = NO
+QT_AUTOBRIEF           = NO
+MULTILINE_CPP_IS_BRIEF = NO
+INHERIT_DOCS           = YES
+SEPARATE_MEMBER_PAGES  = NO
+TAB_SIZE               = 8
+ALIASES                = 
+OPTIMIZE_OUTPUT_FOR_C  = YES
+OPTIMIZE_OUTPUT_JAVA   = NO
+OPTIMIZE_FOR_FORTRAN   = NO
+OPTIMIZE_OUTPUT_VHDL   = NO
+BUILTIN_STL_SUPPORT    = NO
+CPP_CLI_SUPPORT        = NO
+SIP_SUPPORT            = NO
+DISTRIBUTE_GROUP_DOC   = NO
+SUBGROUPING            = YES
+TYPEDEF_HIDES_STRUCT   = NO
+EXTRACT_ALL            = NO
+EXTRACT_PRIVATE        = NO
+EXTRACT_STATIC         = NO
+EXTRACT_LOCAL_CLASSES  = YES
+EXTRACT_LOCAL_METHODS  = NO
+EXTRACT_ANON_NSPACES   = NO
+HIDE_UNDOC_MEMBERS     = NO
+HIDE_UNDOC_CLASSES     = NO
+HIDE_FRIEND_COMPOUNDS  = NO
+HIDE_IN_BODY_DOCS      = NO
+INTERNAL_DOCS          = NO
+CASE_SENSE_NAMES       = YES
+HIDE_SCOPE_NAMES       = NO
+SHOW_INCLUDE_FILES     = YES
+INLINE_INFO            = YES
+SORT_MEMBER_DOCS       = YES
+SORT_BRIEF_DOCS        = NO
+SORT_GROUP_NAMES       = NO
+SORT_BY_SCOPE_NAME     = NO
+GENERATE_TODOLIST      = YES
+GENERATE_TESTLIST      = YES
+GENERATE_BUGLIST       = YES
+GENERATE_DEPRECATEDLIST= YES
+ENABLED_SECTIONS       = 
+MAX_INITIALIZER_LINES  = 30
+SHOW_USED_FILES        = YES
+SHOW_DIRECTORIES       = NO
+FILE_VERSION_FILTER    = 
+QUIET                  = NO
+WARNINGS               = YES
+WARN_IF_UNDOCUMENTED   = YES
+WARN_IF_DOC_ERROR      = YES
+WARN_NO_PARAMDOC       = NO
+WARN_FORMAT            = "$file:$line: $text"
+WARN_LOGFILE           = 
+INPUT                  = .
+INPUT_ENCODING         = UTF-8
+FILE_PATTERNS          = *.c
+RECURSIVE              = YES
+EXCLUDE                = 
+EXCLUDE_SYMLINKS       = NO
+EXCLUDE_PATTERNS       = 
+EXCLUDE_SYMBOLS        = 
+EXAMPLE_PATH           = 
+EXAMPLE_PATTERNS       = 
+EXAMPLE_RECURSIVE      = NO
+IMAGE_PATH             = 
+INPUT_FILTER           = 
+FILTER_PATTERNS        = 
+FILTER_SOURCE_FILES    = NO
+SOURCE_BROWSER         = YES
+INLINE_SOURCES         = NO
+STRIP_CODE_COMMENTS    = YES
+REFERENCED_BY_RELATION = NO
+REFERENCES_RELATION    = NO
+REFERENCES_LINK_SOURCE = YES
+USE_HTAGS              = NO
+VERBATIM_HEADERS       = YES
+ALPHABETICAL_INDEX     = NO
+COLS_IN_ALPHA_INDEX    = 5
+IGNORE_PREFIX          = 
+GENERATE_HTML          = YES
+HTML_OUTPUT            = html
+HTML_FILE_EXTENSION    = .html
+HTML_HEADER            = 
+HTML_STYLESHEET        = 
+HTML_ALIGN_MEMBERS     = YES
+GENERATE_HTMLHELP      = NO
+GENERATE_DOCSET        = NO
+DOCSET_FEEDNAME        = "Doxygen generated docs"
+DOCSET_BUNDLE_ID       = org.doxygen.Project
+HTML_DYNAMIC_SECTIONS  = NO
+CHM_FILE               = 
+HHC_LOCATION           = 
+GENERATE_CHI           = NO
+BINARY_TOC             = NO
+TOC_EXPAND             = NO
+DISABLE_INDEX          = NO
+ENUM_VALUES_PER_LINE   = 4
+GENERATE_TREEVIEW      = NO
+TREEVIEW_WIDTH         = 250
+GENERATE_LATEX         = NO
+LATEX_OUTPUT           = latex
+LATEX_CMD_NAME         = latex
+MAKEINDEX_CMD_NAME     = makeindex
+COMPACT_LATEX          = NO
+PAPER_TYPE             = a4wide
+EXTRA_PACKAGES         = 
+LATEX_HEADER           = 
+PDF_HYPERLINKS         = YES
+USE_PDFLATEX           = YES
+LATEX_BATCHMODE        = NO
+LATEX_HIDE_INDICES     = NO
+GENERATE_RTF           = NO
+RTF_OUTPUT             = rtf
+COMPACT_RTF            = NO
+RTF_HYPERLINKS         = NO
+RTF_STYLESHEET_FILE    = 
+RTF_EXTENSIONS_FILE    = 
+GENERATE_MAN           = YES
+MAN_OUTPUT             = man
+MAN_EXTENSION          = .3
+MAN_LINKS              = NO
+GENERATE_XML           = NO
+XML_OUTPUT             = xml
+XML_SCHEMA             = 
+XML_DTD                = 
+XML_PROGRAMLISTING     = YES
+GENERATE_AUTOGEN_DEF   = NO
+GENERATE_PERLMOD       = NO
+PERLMOD_LATEX          = NO
+PERLMOD_PRETTY         = YES
+PERLMOD_MAKEVAR_PREFIX = 
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = NO
+EXPAND_ONLY_PREDEF     = NO
+SEARCH_INCLUDES        = YES
+INCLUDE_PATH           = 
+INCLUDE_FILE_PATTERNS  = 
+PREDEFINED             = 
+EXPAND_AS_DEFINED      = 
+SKIP_FUNCTION_MACROS   = YES
+TAGFILES               = 
+GENERATE_TAGFILE       = 
+ALLEXTERNALS           = NO
+EXTERNAL_GROUPS        = YES
+PERL_PATH              = /usr/bin/perl
+CLASS_DIAGRAMS         = YES
+MSCGEN_PATH            = 
+HIDE_UNDOC_RELATIONS   = YES
+HAVE_DOT               = YES
+CLASS_GRAPH            = YES
+COLLABORATION_GRAPH    = YES
+GROUP_GRAPHS           = YES
+UML_LOOK               = NO
+TEMPLATE_RELATIONS     = NO
+INCLUDE_GRAPH          = YES
+INCLUDED_BY_GRAPH      = YES
+CALL_GRAPH             = NO
+CALLER_GRAPH           = NO
+GRAPHICAL_HIERARCHY    = YES
+DIRECTORY_GRAPH        = YES
+DOT_IMAGE_FORMAT       = png
+DOT_PATH               = 
+DOTFILE_DIRS           = 
+DOT_GRAPH_MAX_NODES    = 50
+MAX_DOT_GRAPH_DEPTH    = 0
+DOT_TRANSPARENT        = YES
+DOT_MULTI_TARGETS      = NO
+GENERATE_LEGEND        = YES
+DOT_CLEANUP            = YES
+SEARCHENGINE           = NO
diff --git a/src/libnetfilter_log.c b/src/libnetfilter_log.c
index cad78aa..49033a2 100644
--- a/src/libnetfilter_log.c
+++ b/src/libnetfilter_log.c
@@ -1,6 +1,7 @@
 /* libnetfilter_log.c: generic library for access to NFLOG
  *
  * (C) 2005 by Harald Welte <laforge@gnumonks.org>
+ * (C) 2005, 2008-2010 by Pablo Neira Ayuso <pablo@netfilter.org>
  *
  *  This program is free software; you can redistribute it and/or modify
  *  it under the terms of the GNU General Public License version 2 
@@ -31,6 +32,35 @@
 #include <libnfnetlink/libnfnetlink.h>
 #include <libnetfilter_log/libnetfilter_log.h>
 
+/**
+ * \mainpage
+ *
+ * libnetfilter_log is a userspace library providing interface to packets
+ * that have been logged by the kernel packet filter. It is is part of a
+ * system that deprecates the old syslog/dmesg based packet logging.
+ *
+ * libnetfilter_log homepage is:
+ * 	http://netfilter.org/projects/libnetfilter_log/
+ *
+ * \section Dependencies
+ * libnetfilter_log requires libnfnetlink and a kernel that includes the
+ * nfnetlink_log subsystem (i.e. 2.6.14 or later).
+ *
+ * \section Main Features
+ *  - receiving to-be-logged packets from the kernel nfnetlink_log subsystem
+ *
+ * \section Git Tree
+ * The current development version of libnetfilter_log can be accessed
+ * at https://git.netfilter.org/cgi-bin/gitweb.cgi?p=libnetfilter_log.git
+ *
+ * \section Using libnetfilter_log
+ *
+ * To write your own program using libnetfilter_log, you should start by
+ * reading the doxygen documentation (start by \link LibrarySetup \endlink
+ * page) and nfulnl_test.c source file.
+ *
+ */
+
 struct nflog_handle
 {
 	struct nfnl_handle *nfnlh;
@@ -144,11 +174,69 @@ struct nfnl_handle *nflog_nfnlh(struct nflog_handle *h)
 	return h->nfnlh;
 }
 
+/**
+ *
+ * \defgroup Log Group handling
+ *
+ * Once libnetfilter_log library has been initialised (See
+ * \link LibrarySetup \endlink), it is possible to bind the program to
+ * a specific group. This can be done using nflog_bind_group().
+ *
+ * The group can then be tuned via nflog_set_mode() among many others.
+ *
+ * Here's a little code snippet that binds to the group 100:
+ * \verbatim
+	printf("binding this socket to group 0\n");
+	qh = nflog_bind_group(h, 0);
+	if (!qh) {
+		fprintf(stderr, "no handle for grup 0\n");
+		exit(1);
+	}
+
+	printf("setting copy_packet mode\n");
+	if (nflog_set_mode(qh, NFULNL_COPY_PACKET, 0xffff) < 0) {
+		fprintf(stderr, "can't set packet copy mode\n");
+		exit(1);
+	}
+\endverbatim
+ *
+ * Next step is the handling of incoming packets which can be done via a loop:
+ *
+ * \verbatim
+	fd = nflog_fd(h);
+
+	while ((rv = recv(fd, buf, sizeof(buf), 0)) && rv >= 0) {
+		printf("pkt received (len=%u)\n", rv);
+		nflog_handle_packet(h, buf, rv);
+	}
+\endverbatim
+ *
+ * Data and information about the packet can be fetch by using message parsing
+ * functions (See \link Parsing \endlink).
+ * @{
+ */
+
+/**
+ * nflog_fd - get the file descriptor associated with the nflog handler
+ * \param log handler obtained via call to nflog_open()
+ *
+ * \return a file descriptor for the netlink connection associated with the
+ * 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)
 {
 	return nfnl_fd(nflog_nfnlh(h));
 }
 
+/**
+ * @}
+ */
+
 struct nflog_handle *nflog_open_nfnl(struct nfnl_handle *nfnlh)
 {
 	struct nflog_handle *h;
@@ -183,6 +271,21 @@ out_free:
 	return NULL;
 }
 
+/**
+ * \addtogroup LibrarySetup
+ * @{
+ */
+
+/**
+ * nflog_open - open a nflog handler
+ *
+ * This function obtains a netfilter log connection handle. When you are
+ * finished with the handle returned by this function, you should destroy
+ * 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.
+ */
 struct nflog_handle *nflog_open(void)
 {
 	struct nfnl_handle *nfnlh;
@@ -204,6 +307,10 @@ struct nflog_handle *nflog_open(void)
 	return lh;
 }
 
+/**
+ * @}
+ */
+
 int nflog_callback_register(struct nflog_g_handle *gh, nflog_callback *cb,
 			     void *data)
 {
@@ -218,6 +325,23 @@ int nflog_handle_packet(struct nflog_handle *h, char *buf, int len)
 	return nfnl_handle_packet(h->nfnlh, buf, len);
 }
 
+/**
+ * \addtogroup LibrarySetup
+ *
+ * When the program has finished with libnetfilter_log, it has to call
+ * the nflog_close() function to release all associated resources.
+ *
+ * @{
+ */
+
+/**
+ * nflog_close - close a nflog handler
+ * \param h Netfilter log handle obtained via call to nflog_open()
+ *
+ * This function closes the nflog handler and free associated resources.
+ *
+ * \return 0 on success, non-zero on failure.
+ */
 int nflog_close(struct nflog_handle *h)
 {
 	int ret = nfnl_close(h->nfnlh);
@@ -225,19 +349,51 @@ int nflog_close(struct nflog_handle *h)
 	return ret;
 }
 
-/* bind nf_log from a specific protocol family */
+/**
+ * nflog_bind_pf - bind a nflog handler to a given protocol family
+ * \param h Netfilter log handle obtained via call to nflog_open()
+ * \param pf protocol family to bind to nflog handler obtained from nflog_open()
+ *
+ * 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
+ */
 int nflog_bind_pf(struct nflog_handle *h, u_int16_t pf)
 {
 	return __build_send_cfg_msg(h, NFULNL_CFG_CMD_PF_BIND, 0, pf);
 }
 
-/* unbind nf_log from a specific protocol family */
+
+/**
+ * nflog_unbind_pf - unbind nflog handler from a protocol family
+ * \param h Netfilter log handle obtained via call to nflog_open()
+ * \param pf protocol family to unbind family from
+ *
+ * Unbinds the given nflog handle from processing packets belonging
+ * to the given protocol family.
+ */
 int nflog_unbind_pf(struct nflog_handle *h, u_int16_t pf)
 {
 	return __build_send_cfg_msg(h, NFULNL_CFG_CMD_PF_UNBIND, 0, pf);
 }
 
-/* bind this socket to a specific group number */
+/**
+ * @}
+ */
+
+/**
+ * \addtogroup Log Group handling
+ * @{
+ */
+
+/**
+ * nflog_bind_group - bind a new handle to a specific group number.
+ * \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
+ */
 struct nflog_g_handle *
 nflog_bind_group(struct nflog_handle *h, u_int16_t num)
 {
@@ -263,7 +419,21 @@ nflog_bind_group(struct nflog_handle *h, u_int16_t num)
 	return gh;
 }
 
-/* unbind this socket from a specific group number */
+/**
+ * @}
+ */
+
+/**
+ * \addtogroup Log Group handling
+ * @{
+ */
+
+/**
+ * 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.
+ */
 int nflog_unbind_group(struct nflog_g_handle *gh)
 {
 	int ret = __build_send_cfg_msg(gh->h, NFULNL_CFG_CMD_UNBIND, gh->id, 0);
@@ -275,6 +445,21 @@ int nflog_unbind_group(struct nflog_g_handle *gh)
 	return ret;
 }
 
+/**
+ * nflog_set_mode - set the amount of packet data that nflog copies to userspace
+ * \param qh Netfilter log 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
+ *
+ * Sets the amount of data to be copied to userspace for each packet logged
+ * to the given group.
+ *
+ * - NFULNL_COPY_NONE - do not copy any data
+ * - NFULNL_COPY_META - copy only packet metadata
+ * - NFULNL_COPY_PACKET - copy entire packet
+ *
+ * \return -1 on error; >= otherwise.
+ */
 int nflog_set_mode(struct nflog_g_handle *gh,
 		   u_int8_t mode, u_int32_t range)
 {
@@ -296,6 +481,18 @@ int nflog_set_mode(struct nflog_g_handle *gh,
 	return nfnl_query(gh->h->nfnlh, &u.nmh);
 }
 
+/**
+ * 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 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
+ * pushes the log buffer to userspace if no new logged packets have occured.
+ * 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.
+ */
 int nflog_set_timeout(struct nflog_g_handle *gh, u_int32_t timeout)
 {
 	union {
@@ -311,6 +508,16 @@ int nflog_set_timeout(struct nflog_g_handle *gh, u_int32_t timeout)
 	return nfnl_query(gh->h->nfnlh, &u.nmh);
 }
 
+/**
+ * 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 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.
+ */
 int nflog_set_qthresh(struct nflog_g_handle *gh, u_int32_t qthresh)
 {
 	union {
@@ -326,6 +533,16 @@ int nflog_set_qthresh(struct nflog_g_handle *gh, u_int32_t qthresh)
 	return nfnl_query(gh->h->nfnlh, &u.nmh);
 }
 
+/**
+ * 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 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.
+ *
+ * \return -1 in case of error and errno is explicity set.
+ */
 int nflog_set_nlbufsiz(struct nflog_g_handle *gh, u_int32_t nlbufsiz)
 {
 	union {
@@ -348,6 +565,18 @@ int nflog_set_nlbufsiz(struct nflog_g_handle *gh, u_int32_t nlbufsiz)
 	return status;
 }
 
+/**
+ * nflog_set_flags - set the nflog flags for this group
+ * \param gh Netfilter log handle obtained by call to nflog_bind_group().
+ * \param flags Flags that you want to set
+ *
+ * There are two existing flags:
+ *
+ *	- 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.
+ */
 int nflog_set_flags(struct nflog_g_handle *gh, u_int16_t flags)
 {
 	union {
@@ -363,34 +592,91 @@ int nflog_set_flags(struct nflog_g_handle *gh, u_int16_t flags)
 	return nfnl_query(gh->h->nfnlh, &u.nmh);
 }
 
+/**
+ * @}
+ */
+
+/**
+ * \defgroup Parsing Message parsing functions
+ * @{
+ */
 
+/**
+ * nflog_get_msg_packet_hdr - return the metaheader that wraps the packet
+ * \param nfad Netlink packet data handle passed to callback function
+ *
+ * \return the netfilter log netlink packet header for the given nflog_data
+ * argument.  Typically, the nflog_data value is passed as the 3rd parameter
+ * to the callback function set by a call to nflog_callback_register().
+ *
+ * The nfulnl_msg_packet_hdr structure is defined in libnetfilter_log.h as:
+ *\verbatim
+	struct nfulnl_msg_packet_hdr {
+	        u_int16_t       hw_protocol;    // hw protocol (network order)
+	        u_int8_t        hook;           // netfilter hook
+		u_int8_t        _pad;
+	} __attribute__ ((packed));
+\endverbatim
+ */
 struct nfulnl_msg_packet_hdr *nflog_get_msg_packet_hdr(struct nflog_data *nfad)
 {
 	return nfnl_get_pointer_to_data(nfad->nfa, NFULA_PACKET_HDR,
 					 struct nfulnl_msg_packet_hdr);
 }
 
-
+/**
+ * nflog_get_hwtype - get the hardware link layer type from logging data
+ * \param nfad pointer to logging data
+ *
+ * \return the hardware link layer type.
+ */
 u_int16_t nflog_get_hwtype(struct nflog_data *nfad)
 {
 	return ntohs(nfnl_get_data(nfad->nfa, NFULA_HWTYPE, u_int16_t));
 }
 
+/**
+ * nflog_get_hwhdrlen - get the length of the hardware link layer header
+ * \param nfad pointer to logging data
+ *
+ * \return the size of the hardware link layer header
+ */
 u_int16_t nflog_get_msg_packet_hwhdrlen(struct nflog_data *nfad)
 {
 	return ntohs(nfnl_get_data(nfad->nfa, NFULA_HWLEN, u_int16_t));
 }
 
+/**
+ * nflog_get_msg_packet_hwhdr - get the hardware link layer header
+ * \param nfad pointer to logging data
+ *
+ * \return the hardware link layer header
+ */
 char *nflog_get_msg_packet_hwhdr(struct nflog_data *nfad)
 {
 	return nfnl_get_pointer_to_data(nfad->nfa, NFULA_HWHEADER, char);
 }
 
+/**
+ * nflog_get_nfmark - get the packet mark
+ * \param nfad Netlink packet data handle passed to callback function
+ *
+ * \return the netfilter mark currently assigned to the logged packet.
+ */
 u_int32_t nflog_get_nfmark(struct nflog_data *nfad)
 {
 	return ntohl(nfnl_get_data(nfad->nfa, NFULA_MARK, u_int32_t));
 }
 
+/**
+ * nflog_get_timestamp - get the packet timestamp
+ * \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.
+ *
+ * \return 0 on success, a negative value on failure.
+ */
 int nflog_get_timestamp(struct nflog_data *nfad, struct timeval *tv)
 {
 	struct nfulnl_msg_packet_timestamp *uts;
@@ -406,32 +692,100 @@ int nflog_get_timestamp(struct nflog_data *nfad, struct timeval *tv)
 	return 0;
 }
 
+/**
+ * nflog_get_indev - get the interface that the packet was received through
+ * \param nfad Netlink packet data handle passed to callback function
+ *
+ * \return The index of the device the packet was received via. If the
+ * 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)
+ */
 u_int32_t nflog_get_indev(struct nflog_data *nfad)
 {
 	return ntohl(nfnl_get_data(nfad->nfa, NFULA_IFINDEX_INDEV, u_int32_t));
 }
 
+/**
+ * nflog_get_physindev - get the physical interface that the packet was received
+ * \param nfad Netlink packet data handle passed to callback function
+ *
+ * \return The index of the physical device the packet was received via.
+ * If the returned index is 0, the packet was locally generated or the
+ * physical input interface is no longer known (ie. POSTROUTING?).
+ */
 u_int32_t nflog_get_physindev(struct nflog_data *nfad)
 {
 	return ntohl(nfnl_get_data(nfad->nfa, NFULA_IFINDEX_PHYSINDEV, u_int32_t));
 }
 
+/**
+ * nflog_get_outdev - gets the interface that the packet will be routed out
+ * \param nfad Netlink packet data handle passed to callback function
+ *
+ * \return The index of the device the packet will be sent out.  If the
+ * returned index is 0, the packet is destined for localhost or the output
+ * interface is not yet known (ie. PREROUTING?).
+ */
 u_int32_t nflog_get_outdev(struct nflog_data *nfad)
 {
 	return ntohl(nfnl_get_data(nfad->nfa, NFULA_IFINDEX_OUTDEV, u_int32_t));
 }
 
+/**
+ * nflog_get_physoutdev - get the physical interface that the 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
+ * 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.
+ */
 u_int32_t nflog_get_physoutdev(struct nflog_data *nfad)
 {
 	return ntohl(nfnl_get_data(nfad->nfa, NFULA_IFINDEX_PHYSOUTDEV, u_int32_t));
 }
 
+/**
+ * nflog_get_packet_hw - get hardware address
+ * \param nfad Netlink packet data handle passed to callback function
+ *
+ * Retrieves the hardware address associated with the given packet.
+ * For ethernet packets, the hardware address returned (if any) will be the
+ * MAC address of the packet source host. The destination MAC address is not
+ * known until after POSTROUTING and a successful ARP request, so cannot
+ * currently be retrieved.
+ *
+ * The nfulnl_msg_packet_hw structure is defined in libnetfilter_log.h as:
+ * \verbatim
+        struct nfulnl_msg_packet_hw {
+                u_int16_t       hw_addrlen;
+                u_int16_t       _pad;
+                u_int8_t        hw_addr[8];
+        } __attribute__ ((packed));
+\endverbatim
+ */
 struct nfulnl_msg_packet_hw *nflog_get_packet_hw(struct nflog_data *nfad)
 {
 	return nfnl_get_pointer_to_data(nfad->nfa, NFULA_HWADDR,
 					struct nfulnl_msg_packet_hw);
 }
 
+/**
+ * nflog_get_payload - get payload of the logged packet
+ * \param nfad Netlink packet data handle passed to callback function
+ * \param data Pointer of pointer that will be pointed to the payload
+ *
+ * Retrieve the payload for a logged packet. The actual amount and type of
+ * data retrieved by this function will depend on the mode set with the
+ * nflog_set_mode() function.
+ *
+ * \return -1 on error, otherwise > 0.
+ */
 int nflog_get_payload(struct nflog_data *nfad, char **data)
 {
 	*data = nfnl_get_pointer_to_data(nfad->nfa, NFULA_PAYLOAD, char);
@@ -441,11 +795,24 @@ int nflog_get_payload(struct nflog_data *nfad, char **data)
 	return -1;
 }
 
+/**
+ * nflog_get_prefix - get the logging string prefix
+ * \param nfad Netlink packet data handle passed to callback function
+ *
+ * \return the string prefix that is specified as argument to the iptables'
+ * NFLOG target.
+ */
 char *nflog_get_prefix(struct nflog_data *nfad)
 {
 	return nfnl_get_pointer_to_data(nfad->nfa, NFULA_PREFIX, char);
 }
 
+/**
+ * nflog_get_uid - get the UID of the user that has generated the packet
+ * \param nfad Netlink packet data handle passed to callback function
+ *
+ * \return the UID of the user that has genered the packet, if any.
+ */
 int nflog_get_uid(struct nflog_data *nfad, u_int32_t *uid)
 {
 	if (!nfnl_attr_present(nfad->nfa, NFULA_UID))
@@ -455,6 +822,12 @@ int nflog_get_uid(struct nflog_data *nfad, u_int32_t *uid)
 	return 0;
 }
 
+/**
+ * nflog_get_gid - get the GID of the user that has generated the packet
+ * \param nfad Netlink packet data handle passed to callback function
+ *
+ * \return the GID of the user that has genered the packet, if any.
+ */
 int nflog_get_gid(struct nflog_data *nfad, u_int32_t *gid)
 {
 	if (!nfnl_attr_present(nfad->nfa, NFULA_GID))
@@ -464,6 +837,14 @@ int nflog_get_gid(struct nflog_data *nfad, u_int32_t *gid)
 	return 0;
 }
 
+/**
+ * nflog_get_seq - get the local nflog sequence number
+ * \param nfad Netlink packet data handle passed to callback function
+ *
+ * You must enable this via nflog_set_flags().
+ *
+ * \return the local nflog sequence number.
+ */
 int nflog_get_seq(struct nflog_data *nfad, u_int32_t *seq)
 {
 	if (!nfnl_attr_present(nfad->nfa, NFULA_SEQ))
@@ -473,6 +854,14 @@ int nflog_get_seq(struct nflog_data *nfad, u_int32_t *seq)
 	return 0;
 }
 
+/**
+ * nflog_get_seq_global - get the global nflog sequence number
+ * \param nfad Netlink packet data handle passed to callback function
+ *
+ * You must enable this via nflog_set_flags().
+ *
+ * \return the global nflog sequence number.
+ */
 int nflog_get_seq_global(struct nflog_data *nfad, u_int32_t *seq)
 {
 	if (!nfnl_attr_present(nfad->nfa, NFULA_SEQ_GLOBAL))
@@ -482,6 +871,10 @@ int nflog_get_seq_global(struct nflog_data *nfad, u_int32_t *seq)
 	return 0;
 }
 
+/**
+ * @}
+ */
+
 #define SNPRINTF_FAILURE(ret, rem, offset, len)			\
 do {								\
 	if (ret < 0)						\
@@ -493,6 +886,35 @@ do {								\
 	rem -= ret;						\
 } while (0)
 
+/**
+ * \defgroup Printing
+ * @{
+ */
+
+/**
+ * nflog_snprintf_xml - print the logged packet in XML format into a buffer
+ * \param buf The buffer that you want to use to print the logged packet
+ * \param rem The size of the buffer that you have passed
+ * \param tb Netlink packet data handle passed to callback function
+ * \param flags The flag that tell what to print into the buffer
+ *
+ * This function supports the following flags:
+ *
+ *	- NFLOG_XML_PREFIX: include the string prefix
+ *	- NFLOG_XML_HW: include the hardware link layer address
+ *	- NFLOG_XML_MARK: include the packet mark
+ *	- NFLOG_XML_DEV: include the device information
+ *	- NFLOG_XML_PHYSDEV: include the physical device information
+ *	- NFLOG_XML_PAYLOAD: include the payload (in hexadecimal)
+ *	- 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.
+ *
+ * \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.
+ */
 int nflog_snprintf_xml(char *buf, size_t rem, struct nflog_data *tb, int flags)
 {
 	struct nfulnl_msg_packet_hdr *ph;
@@ -639,3 +1061,7 @@ int nflog_snprintf_xml(char *buf, size_t rem, struct nflog_data *tb, int flags)
 
 	return len;
 }
+
+/**
+ * @}
+ */