Skip to contentSkip to conversation

libnetfilter_log documentation

PATCH New Gregor Maier 1 participant 1 message May 11, 2006 netfilter

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 libnetfilter_log documentation

Hi,

I've written a small API Doc for the libnetfilter_log library. And since I don't like to write manpages from hand, I just added doxygen-style comments to the header file and used doxygen to generate the manpages from it.

The converted docs (manpage, html, pdf) can be found at http://www.net.informatik.tu-muenchen.de/~gregor/projects/

cu
Gregor

libnetfilter_log/libnetfilter_log.h +353 -3
Index: include/libnetfilter_log/libnetfilter_log.h
===================================================================
@@ -11,54 +11,404 @@
 
 #include <libnetfilter_log/linux_nfnetlink_log.h>
 
+/**
+ * @file libnetfilter_log
+ *
+ * libnetfilter_log is a userspace library providing interface to
+ * packets that have been logged by the kernel packet filter. It is part
+ * of the netfilter project and can be found at http://www.netfilter.org/
+ *
+ * @author libnetfilter_log (C) 2005 by Harald Welte <[email protected]>
+ *
+ * @author This software may be used and distributed according to the terms
+ *   of the GNU General Public License, incorporated herein by reference.
+ *
+ * @author Documentation by Gregor Maier <[email protected]>, with a lot 
+ * of stuff taken from Brad Fisher's <[email protected]> libnetfilter_queue
+ * documentation.
+ */
+
 struct nflog_handle;
 struct nflog_g_handle;
 struct nflog_data;
 
 extern int nflog_errno;
 
+/**
+ * @brief Returns the netfilter netlink handle used by h
+ *
+ * @param h A netfilter log handle. See nflog_open()
+ * @return The netfilter netlink handle of h, that is used by
+ * libnfnetlink to talk to the kernel.
+ */
 extern struct nfnl_handle *nflog_nfnlh(struct nflog_handle *h);
-extern int nflog_fd(struct nflog_handle *h);
 
+
+/**
+ * @brief Callback prototype.
+ *
+ * nflog_callback function pointeres are registered with libnetfilter_log
+ * to handle received packets. The callback function is called for each 
+ * received packet. 
+ *
+ * @param gh A netfilter log group handle (see nflog_bind_group())
+ * @param nfmsg Pointer to a netfilter netlink message ??? 
+ * @param nfd Data structure containing the netfilter netlink attributes
+ * 	received from kernel.  This pointer is passed to many of the informational
+ * 	functions, such as nflog_get_nfmark(), nflog_get_payload(), etc. Should
+ * 	not be manipulated directly
+ * @param data The value passed as data parameter of nflog_callback_register()
+ * @return You must return zero on success. nflog_handle_packet() will
+ * 	return this value.
+ */
 typedef int nflog_callback(struct nflog_g_handle *gh, struct nfgenmsg *nfmsg,
-			    struct nflog_data *nfd, void *data);
+			    struct nflog_data *nfad, void *data);
 
 
+/**
+ * @brief Obtains netfilter log connection handle.
+ *
+ * Obtains netfilter log connection handle. When you are finished with the
+ * handle, you should destroy it by calling nflog_close(). A new netlink 
+ * connection is obtained internally and associated with the queue 
+ * connection handle returned.
+ * 
+ * @return Pointer to a new log handle or NULL on failure
+ * 
+ */
 extern struct nflog_handle *nflog_open(void);
+
+/**
+ * @brief Obtains netfilter log connection handle.
+ *
+ * Obtains netfilter log connection handle using an existing 
+ * netlink connection. This function is used internally to 
+ * implement nflog_open(), and should typically not be called directly.
+ * 
+ * @param nfnlh Pointer to netfilter netlink handler
+ * @return Pointer to a new log handle or NULL on failure
+ * 
+ */
 extern struct nflog_handle *nflog_open_nfnl(struct nfnl_handle *nfnlh);
+
+
+/**
+ * @brief Close netfilter log connection
+ *
+ * Close a netfilter log connection associated with the connection
+ * handle and free resources.
+ * 
+ * @param h Pointer to netfilter log connection handle as obtained from
+ * nflog_open()
+ * @return 0 on successs, non-zero on error and errno is set accordingly
+ * 
+ */
 extern int nflog_close(struct nflog_handle *h);
 
+
+/**
+ * @brief Binds the netfilter_log kernel logging backend to PF. 
+ *
+ * Binds the netfilter_log kernel logging bind to the specified 
+ * protocol family (like PF_INET).
+ * 
+ * @param h Pointer to netfilter log connection handle.
+ * @param pf Protocal Family (see socket(2))
+ * @return 0 on successs, non-zero on error and errno is set accordingly\n
+ * EEXIST  libnetfilter_log handler is already registered for this protocol
+ *     family. This error can be igrnored safely.\n
+ * EBUSY   Another libnetfilter_log handler is registered XXX:\n
+ * EINVAL  Invalid Protocol Family has been specified.\n
+ *
+ * NOTE: libnfnetlink currently catches the error and issues
+ * a perror() call, which will clear errno. To get the behaviour described
+ * above, comment out the perror() call in libnfnetlink/src/libnfnetlink.c
+ */
 extern int nflog_bind_pf(struct nflog_handle *h, u_int16_t pf);
+
+
+/**
+ * @brief Unbinds the netfilter_log kernel logging backend from PF. (Dangerous)
+ *
+ * Unbinds the netfilter_log kernel logging backend from PF. (Dangerous). 
+ * Calling this function may break other programs using libnetfilter_log. You 
+ * should not use it! Not to unbind the logger is safe!
+ * 
+ * @param h Pointer to netfilter log connection handle.
+ * @param pf Protocal Family (see socket(2))
+ * @return 0 on successs, non-zero on error and errno is set accordingly\n
+ * EINVAL  Invalid Protocol Family has been specified.
+ */
 extern int nflog_unbind_pf(struct nflog_handle *h, u_int16_t pf);
 
+/** 
+ * @brief Bind the connection handle to a loggroup. 
+ * 
+ * Bind  the connection handle to a loggroup. This call returns a 
+ * group handle, which is usesd for later calls and for identifying
+ * the loggroup. 
+ * 
+ * @param h Pointer to netfilter log connection handle.
+ * @param num The number of loggroup. 
+ * @return gh A netfilter log group handle.
+ */
 extern struct nflog_g_handle *nflog_bind_group(struct nflog_handle *h,
 						 u_int16_t num);
+
+/** 
+ * @brief Unbind and free a group handle. 
+ *
+ * Unbinds the specified group handle from its loggroup. The gh
+ * is freed by this call. 
+ * 
+ * @param gh A netfilter log group handle (see nflog_bind_group())
+ * @return 0 on successs, non-zero on error and errno is set accordingly?
+ */
 extern int nflog_unbind_group(struct nflog_g_handle *gh);
 
+/**
+ * @brief Sets the amount of data copied to userspace for each packet
+ *
+ * Sets the amount of data copied to userspace for each packet. 
+ *
+ * @param gh A netfilter log group handle (see nflog_bind_group())
+ * @param mode How much data to copy:\n
+ *		\b NFULNL_COPY_NONE Do not copy data to userspace\n
+ *		\b NFULNL_COPY_META Copy only packet queuing metadata (The actual 
+ *		packet data itself is not copied)\n
+ *		\b NFULNL_COPY_PACKET Copy metadata and up to range bytes of packet data
+ *	@param len The amount of packet data to copy when mode is NFULNL_COPY_PACKET. 
+ *		Use 0 or 0xffff to copy the whole packet. 
+ *	@return 0 on success, non-zero on error. errno is set accordingly.
+ */
 extern int nflog_set_mode(struct nflog_g_handle *gh,
 			  u_int8_t mode, unsigned int len);
+
+/** 
+ * @brief Set flush timeout.
+ *
+ * Time before flushing queued packets from kernel to userspace. 
+ * This prevents packets from never being flushed to userspace if 
+ * qthreshhold is not request. Packets are either flushed to
+ * userspace when the timeout expires or when qthreshold packets
+ * are queued. (See nflog_set_qthresh()).  
+ *
+ * @param gh A netfilter log group handle (see nflog_bind_group())
+ * @param timeout The timeout to set in 1/100 s. (i.e. multiples of 10ms)??
+ * @return 0 on success, non-zero on error. errno is set accordingly
+ * XXX: is this true??
+ */
 extern int nflog_set_timeout(struct nflog_g_handle *gh, u_int32_t timeout);
+
+/** 
+ * @brief UNUSED
+ */
 extern int nflog_set_flags(struct nflog_g_handle *gh, u_int16_t flags);
+
+/** 
+ * @brief Set transmit threshold
+ *
+ * Number of packet to queue inside kernel.  Setting this value to,
+ * e.g.  10 accumulates ten packets inside the kernel and transmits
+ * them as one netlink multipart message to userspace.  Default  is
+ * 1 (for backwards compatibility). See also nflog_set_timeout().
+ *
+ * @param gh A netfilter log group handle (see nflog_bind_group())
+ * @param qthresh The value of the threshold
+ * @return 0 on success, non-zero on error. errno is set accordingly
+ * XXX: is this true??
+ */
 extern int nflog_set_qthresh(struct nflog_g_handle *gh, u_int32_t qthresh);
+
+/** 
+ * @brief Set the kernel buffer size. 
+ * 
+ * Set the size of the kernel buffer that are used to packets before they
+ * are trasnmitted to userspace. Please note that the netlink message 
+ * headers are also included, so you have to add this margin to
+ * the payload size you want to queue. ???
+ *
+ * @param gh A netfilter log group handle (see nflog_bind_group())
+ * @param nlbufsiz The size of the kernel buffer in bytes. 
+ * @return 0 on success, non-zero on error. errno is set accordingly
+ * XXX: is this true? 
+ */
 extern int nflog_set_nlbufsiz(struct nflog_g_handle *gh, u_int32_t nlbufsiz);
 
+/** 
+ * @brief Register callback function that receives packets
+ *
+ * Register a callback function that receives packets for the given 
+ * group. This callback will be called for each packet logged to
+ * userspace. 
+ *
+ * @param gh A netfilter log group handle (see nflog_bind_group())
+ * @param cb Callback function pointer
+ * @param data Custom data that is passed to the callback function
+ * @return 0 on success, Won't fail.
+ */
 extern int nflog_callback_register(struct nflog_g_handle *gh, 
 				    nflog_callback *cb, void *data);
+
+/**
+ * @brief Return fd associated with netfilter log handle 
+ *
+ * Returns the filedescriptor associated with the netfilter log
+ * handle. This fd is used to received logged packets from the
+ * kernel using recv(2). The data received from recv is then
+ * passed ti nflog_handle_packet()
+ *
+ * @param h Netfilter log handle. See nflog_open()
+ * @return Returns a file descriptor that can be used with the recv(2)
+ *     system call.
+ */
+extern int nflog_fd(struct nflog_handle *h);
+
+/**
+ * @brief Handle packet(s) received from kernel. 
+ *
+ * Packets that have been received from the kernel with recv(2) are 
+ * handed to nflog_handle_packet(), which will trigger the associated
+ * callback functions (see nflog_callback_register()).
+ *
+ * @param h Netfilter log handle. See nflog_open()
+ * @param buf The buffer containing the received data. This is the same
+ *     buffer that recv(2) has filled.
+ * @param len Size of the buffer. This is the length returned from the
+ *     recv(2) call.
+ * @return 0 on success, non-zero on error. Negative values are returned
+ * 	when internal errors occured. Otherwise the return value of the 
+ * 	callback is returned (which must return zero on success). 
+ */
 extern int nflog_handle_packet(struct nflog_handle *h, char *buf, int len);
 
+/**
+ * @brief Returns netfilter log packet header 
+ * 
+ * Returns netfilter log packet header for the given nflog_data argument. 
+ * This function is intended to be called from the callback. 
+ *
+ * @param nfad  Netlink packet attribute data passed to callback function.
+ * @return Netlink packet header for the given packet data. The struct contains
+ * 	the following fields:\n
+ * 	\e "u_int16_t hw_protocol" The ethertype of the packet in network byte order\n
+ * 	\e "u_int8_t hook" The netfilter hook where this packet was intercepted
+ */
+extern struct nfulnl_msg_packet_hdr *nflog_get_msg_packet_hdr(struct nflog_data *nfad);
 
-extern struct nfulnl_msg_packet_hdr *nflog_get_msg_packet_hdr(struct nflog_data *nfad);
+
+/**
+ * @brief Returns netfilter mark currently assigned to the packet.
+ * 
+ * @param nfad  Netlink packet attribute data passed to callback function.
+ * @return The netfilter mark currently assigned to the packet.
+ */
 extern u_int32_t nflog_get_nfmark(struct nflog_data *nfad);
+
+/**
+ * @brief Returns the timestamp of the packet.
+ * 
+ * @param nfad  Netlink packet attribute data passed to callback function.
+ * @param tv Structure to fill with timestamp info
+ * @return  0 on success, -1 on failure (tv is unmodified on failure).
+ */
 extern int nflog_get_timestamp(struct nflog_data *nfad, struct timeval *tv);
+
+/**
+ * @brief Return ingresss interface index 
+ *
+ * @param nfad  Netlink packet attribute data passed to callback function.
+ * @return The index of the physical device the queued packet was received via.
+ *     If the returned index is 0, the packet was locally generated or the
+ *     physical input interface is no longer known. If the packet arrived
+ *     on a bridged port, indev is the bridge group??
+ */ 
 extern u_int32_t nflog_get_indev(struct nflog_data *nfad);
+
+/**
+ * @brief Return physical ingresss interface index 
+ *
+ * @param nfad  Netlink packet attribute data passed to callback function.
+ * @return The index of the physical device the queued packet was received via.
+ *     If the returned index is 0, the packet was locally generated or the
+ *     physical input interface is no longer known. If the packet arrived
+ *     on a bridged port physindev returns the number of the interface where
+ *     the packet entered the system. 
+ */ 
 extern u_int32_t nflog_get_physindev(struct nflog_data *nfad);
+
+/**
+ * @brief Return egress interface index
+ *
+ * @param nfad  Netlink packet attribute data passed to callback function.
+ * @see nflog_get_indev()
+ */
 extern u_int32_t nflog_get_outdev(struct nflog_data *nfad);
+
+/**
+ * @brief Return physical egress interface index
+ *
+ * @param nfad  Netlink packet attribute data passed to callback function.
+ * @see nflog_get_indev()
+ */
 extern u_int32_t nflog_get_physoutdev(struct nflog_data *nfad);
+
+/** 
+ * @brief Returns hardware addresss of the packet. 
+ *
+ * Retrieves the hardware address associated with the given queued packet.
+ * For ethernet packets, the hardware address returned (if any) will be the
+ * MAC address of the packet source host. Empty for packets generated on the
+ * local machine
+ *
+ * @param nfad  Netlink packet attribute data passed to callback function.
+ * @return The source hardware address associated with the queued packet, or NULL if
+ *     unknown. The struct contains the following fields:\n
+ *     \e "u_int16_t hw_addrlen" Length of the hardware address\n
+ *     \e "u_int8_t hw_addr[8]" The hardware address.
+ */
 extern struct nfulnl_msg_packet_hw *nflog_get_packet_hw(struct nflog_data *nfad);
+
+/**
+ * @brief Retrieve packet payload
+ *
+ * Retrieve the packet data of logged packet, starting with the Layer 3 header
+ * (e.g. IP or IPv6). The actual amount of data available depends on the
+ * copy mode specified by nflog_set_mode().
+ *
+ * @param nfad  Netlink packet attribute data passed to callback function.
+ * @param data  A pointer to the packet data is returned in data. 
+ * @returns Length of the packet data pointed to by *data on success, -1
+ *     on failure.
+ */
 extern int nflog_get_payload(struct nflog_data *nfad, char **data);
+
+/**
+ * @brief Return log prefix
+ *
+ * @param nfad  Netlink packet attribute data passed to callback function.
+ * @returns The Log Prefix of this packet. 
+ */
 extern char *nflog_get_prefix(struct nflog_data *nfad);
+
+/** 
+ * @brief Return uid of packet "owner"
+ *
+ * @param nfad  Netlink packet attribute data passed to callback function
+ * @param uid The uid of the packet owner is placed here.
+ * @returns 0 on success, -1 on error
+ */
 extern int nflog_get_uid(struct nflog_data *nfad, u_int32_t *uid);
+
+/**
+ * @brief UNUSED
+ */
 extern int nflog_get_seq(struct nflog_data *nfad, u_int32_t *seq);
+
+/**
+ * @brief UNUSED
+ */
 extern int nflog_get_seq_global(struct nflog_data *nfad, u_int32_t *seq);
 
+
 #endif	/* __LIBNETFILTER_LOG_H */
libnetfilter_log.doxygen.conf +1237 -0

1,237 lines not on this page · raw message

makedoc.sh +32 -0
Index: makedoc.sh
===================================================================
@@ -0,0 +1,32 @@
+#!/bin/sh
+
+# Ugly script a wrapper around doxygen, to generate the docs for
+# libnetfilter_log. Run it from the top-level-src dir of 
+# libnetfilter_log
+#
+# Complain to Gregor Maier <[email protected]> if you don't like
+# this script
+
+if [ ! -d doc ]
+then 
+	mkdir doc
+fi
+
+# We misuse doxygen to generate just on manpage for the whole lib.
+# Normally doxygen would use the filename of the source file as 
+# heading (and as manpage filename), but I just want the
+# heading and filename to be libnetfilter_log (i.e. the manpage
+# should be libnetfilter_log.3 and not libnetfilter_log.h.3)
+if [ ! -e doc/libnetfilter_log ]
+then
+	ln -s ../include/libnetfilter_log/libnetfilter_log.h doc/libnetfilter_log
+fi 
+
+if [ ! -h doc/libnetfilter_log ]
+then
+	echo "ERROR: doc/libnetfilter_log exists but is not a symlink. Exiting"
+fi
+
+doxygen libnetfilter_log.doxygen.conf 
+
+make -C doc/latex

Property changes on: makedoc.sh
___________________________________________________________________
Name: svn:executable
+ *