Also in iftable.c: - Expand usage description to cover nlif_catch. - Add SYNOPSIS. - Fix some doc typos. Signed-off-by: Duncan Roe <duncan_roe@xxxxxxxxxxxxxxx> --- src/iftable.c | 57 ++++++++++++++++++++++++++++++++++++---- src/libnetfilter_queue.c | 38 +++------------------------ 2 files changed, 56 insertions(+), 39 deletions(-) diff --git a/src/iftable.c b/src/iftable.c index 76a6cad..1a53893 100644 --- a/src/iftable.c +++ b/src/iftable.c @@ -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) diff --git a/src/libnetfilter_queue.c b/src/libnetfilter_queue.c index 3c3f951..1be2333 100644 --- a/src/libnetfilter_queue.c +++ b/src/libnetfilter_queue.c @@ -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 -- 2.35.8
