libnetfilter_log documentation
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
@@ -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
@@ -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
+ *