@@ -42,6 +42,55 @@ static int data_cb(const struct nlmsghdr *nlh, void *data);
* [libmnl](https://netfilter.org/projects/libmnl/doxygen/html/)
* calls directly to maintain an
* interface table with more (or less!) data points, e.g. MTU.
+ *
+ * Programs access an nlif database through an opaque __struct nlif_handle__
+ * interface resolving handle. Call nlif_open() to get a handle:
+ * \verbatim
+ h = nlif_open();
+ if (h == NULL) {
+ perror("nlif_open");
+ exit(EXIT_FAILURE);
+ }
+\endverbatim
+ * Once the handler is open, you need to fetch the interface table at a
+ * whole via a call to nlif_query.
+ * \verbatim
+ nlif_query(h);
+\endverbatim
+ * libnetfilter_queue is able to update the interface mapping
+ * when a new interface appears.
+ * To do so, you need to call nlif_catch() on the handler after each
+ * interface related event. The simplest way to get and treat event is to run
+ * a **select()** or **poll()** against the nlif and netilter_queue
+ * file descriptors.
+ * E.g. use nlif_fd() to get the nlif file descriptor, then give this fd to
+ * **poll()** as in this code snippet (error-checking removed):
+ * \verbatim
+ if_fd = nlif_fd(h);
+ qfd = mnl_socket_get_fd(nl); // For mnl API or ...
+ qfd = nfq_fd(qh); // For nfnl API
+ . . .
+ fds[0].fd = ifd;
+ fds[0].events = POLLIN;
+ fds[1].fd = qfd;
+ fds[1].events = POLLIN;
+ for(;;)
+ {
+ poll((struct pollfd *)&fds, 2, -1);
+ if (fds[0].revents & POLLIN)
+ nlif_catch(h);
+\endverbatim
+ * Don't forget to close the handler when you don't need the feature anymore:
+ * \verbatim
+ nlif_close(h);
+\endverbatim
+ *
+ * \manonly
+.SH SYNOPSIS
+.nf
+\fB
+#include <libnetfilter_queue/libnetfilter_queue.h>
+\endmanonly
* @{
*/
@@ -128,8 +177,8 @@ int nlif_get_ifflags(const struct nlif_handle *h,
/**
* nlif_open - initialize interface table
*
- * Open a netlink socket and initialize interface table
- * Call this before any nlif_* function
+ * Open a netlink socket and initialise interface table.
+ * Call this before any other nlif_* function
*
* \return NULL on error, else valid pointer to an nlif_handle structure
*/
@@ -191,8 +240,6 @@ void nlif_close(struct nlif_handle *h)
/**
* nlif_catch - receive message from netlink and update interface table
*
- * FIXME - elaborate a bit
- *
* \param h pointer to nlif_handle created by nlif_open()
* \return 0 if OK
*/
@@ -218,7 +265,7 @@ int nlif_catch(struct nlif_handle *h)
/**
* nlif_query - request a dump of interfaces available in the system
* \param h: pointer to a valid nlif_handler
- * \return -1 on err with errno set, else >=0
+ * \return -1 on error with errno set, else >=0
*/
EXPORT_SYMBOL
int nlif_query(struct nlif_handle *h)
@@ -1284,34 +1284,7 @@ uint32_t nfq_get_physoutdev(struct nfq_data *nfad)
* \param name pointer to the buffer to receive the interface name;
* not more than \c IFNAMSIZ bytes will be copied to it.
* \return -1 in case of error, >0 if it succeed.
- *
- * To use a nlif_handle, You need first to call nlif_open() and to open
- * an handler. Don't forget to store the result as it will be used
- * during all your program life:
- * \verbatim
- h = nlif_open();
- if (h == NULL) {
- perror("nlif_open");
- exit(EXIT_FAILURE);
- }
-\endverbatim
- * Once the handler is open, you need to fetch the interface table at a
- * whole via a call to nlif_query.
- * \verbatim
- nlif_query(h);
-\endverbatim
- * libnfnetlink is able to update the interface mapping when a new interface
- * appears. To do so, you need to call nlif_catch() on the handler after each
- * interface related event. The simplest way to get and treat event is to run
- * a select() or poll() against the nlif file descriptor. To get this file
- * descriptor, you need to use nlif_fd:
- * \verbatim
- if_fd = nlif_fd(h);
-\endverbatim
- * Don't forget to close the handler when you don't need the feature anymore:
- * \verbatim
- nlif_close(h);
-\endverbatim
+ * \sa __nlif_open__(3)
*
*/
EXPORT_SYMBOL
@@ -1330,9 +1303,8 @@ int nfq_get_indev_name(struct nlif_handle *nlif_handle,
* \param name pointer to the buffer to receive the interface name;
* not more than \c IFNAMSIZ bytes will be copied to it.
*
- * See nfq_get_indev_name() documentation for nlif_handle usage.
- *
* \return -1 in case of error, > 0 if it succeed.
+ * \sa __nlif_open__(3)
*/
EXPORT_SYMBOL
int nfq_get_physindev_name(struct nlif_handle *nlif_handle,
@@ -1350,9 +1322,8 @@ int nfq_get_physindev_name(struct nlif_handle *nlif_handle,
* \param name pointer to the buffer to receive the interface name;
* not more than \c IFNAMSIZ bytes will be copied to it.
*
- * See nfq_get_indev_name() documentation for nlif_handle usage.
- *
* \return -1 in case of error, > 0 if it succeed.
+ * \sa __nlif_open__(3)
*/
EXPORT_SYMBOL
int nfq_get_outdev_name(struct nlif_handle *nlif_handle,
@@ -1370,9 +1341,8 @@ int nfq_get_outdev_name(struct nlif_handle *nlif_handle,
* \param name pointer to the buffer to receive the interface name;
* not more than \c IFNAMSIZ bytes will be copied to it.
*
- * See nfq_get_indev_name() documentation for nlif_handle usage.
- *
* \return -1 in case of error, > 0 if it succeed.
+ * \sa __nlif_open__(3)
*/
EXPORT_SYMBOL
Also in iftable.c: - Expand usage description to cover nlif_catch. - Add SYNOPSIS. - Fix some doc typos. Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au> --- src/iftable.c | 57 ++++++++++++++++++++++++++++++++++++---- src/libnetfilter_queue.c | 38 +++------------------------ 2 files changed, 56 insertions(+), 39 deletions(-)