From 6e18d454004fcaff4b6064c04989db51393395e7 Mon Sep 17 00:00:00 2001 From: Pablo Neira Ayuso Date: Sat, 4 Sep 2010 13:19:28 +0200 Subject: src: convert documentation from kerneldoc to doxygen format Still missing several enumerations that should be documented. You still have to look at libnetfilter_conntrack.h to check conntrack object attributes. Signed-off-by: Pablo Neira Ayuso --- configure.in | 2 +- doxygen.cfg.in | 184 ++++++++++++++++++++++++ src/conntrack/api.c | 407 +++++++++++++++++++++++++++++++++------------------- src/expect/api.c | 218 +++++++++++++++++----------- src/main.c | 28 ++++ 5 files changed, 610 insertions(+), 229 deletions(-) create mode 100644 doxygen.cfg.in diff --git a/configure.in b/configure.in index 6451847..b5a8471 100644 --- a/configure.in +++ b/configure.in @@ -78,5 +78,5 @@ LIBNFCONNTRACK_LIBS="$LIBNFNETLINK_LIBS" AC_SUBST(LIBNFCONNTRACK_LIBS) dnl Output the makefile -AC_OUTPUT(Makefile src/Makefile include/Makefile utils/Makefile qa/Makefile include/libnetfilter_conntrack/Makefile include/internal/Makefile src/conntrack/Makefile src/expect/Makefile libnetfilter_conntrack.pc) +AC_OUTPUT(Makefile src/Makefile include/Makefile utils/Makefile qa/Makefile include/libnetfilter_conntrack/Makefile include/internal/Makefile src/conntrack/Makefile src/expect/Makefile libnetfilter_conntrack.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/conntrack/api.c b/src/conntrack/api.c index 41d9c88..d7f16fe 100644 --- a/src/conntrack/api.c +++ b/src/conntrack/api.c @@ -12,6 +12,57 @@ #include "internal/internal.h" +/** + * \mainpage + * + * libnetfilter_conntrack is a userspace library providing a programming + * interface (API) to the in-kernel connection tracking state table. The + * library libnetfilter_conntrack has been previously known as + * libnfnetlink_conntrack and libctnetlink. This library is currently used by + * conntrack-tools among many other applications. + * + * libnetfilter_conntrack homepage is: + * http://netfilter.org/projects/libnetfilter_conntrack/ + * + * \section Dependencies + * libnetfilter_conntrack requires libnfnetlink and a kernel that includes the + * nf_conntrack_netlink subsystem (i.e. 2.6.14 or later, >= 2.6.18 recommended). + * + * \section Main Features + * - listing/retrieving entries from the kernel connection tracking table. + * - inserting/modifying/deleting entries from the kernel connection tracking + * table. + * - listing/retrieving entries from the kernel expect table. + * - inserting/modifying/deleting entries from the kernel expect table. + * \section Git Tree + * The current development version of libnetfilter_conntrack can be accessed at + * https://git.netfilter.org/cgi-bin/gitweb.cgi?p=libnetfilter_conntrack.git + * + * \section Privileges + * You need the CAP_NET_ADMIN capability in order to allow your application + * to receive events from and to send commands to kernel-space, excepting + * the conntrack table dumping operation. + * + * \section using Using libnetfilter_conntrack + * To write your own program using libnetfilter_conntrack, you should start by + * reading the doxygen documentation (start by \link LibrarySetup \endlink page) + * and check examples available under utils/ in the libnetfilter_conntrack + * source code tree. You can compile these examples by invoking `make check'. + * + * \section Authors + * libnetfilter_conntrack has been almost entirely written by Pablo Neira Ayuso. + * + * \section python Python Binding + * pynetfilter_conntrack is a Python binding of libnetfilter_conntrack written + * by Victor Stinner. You can visit his official web site at + * http://software.inl.fr/trac/trac.cgi/wiki/pynetfilter_conntrack. + */ + +/** + * \defgroup ct Conntrack object handling + * @{ + */ + /** * nfct_conntrack_new - allocate a new conntrack * @@ -33,7 +84,7 @@ struct nf_conntrack *nfct_new(void) /** * nf_conntrack_destroy - release a conntrack object - * @ct: pointer to the conntrack object + * \param ct pointer to the conntrack object */ void nfct_destroy(struct nf_conntrack *ct) { @@ -44,7 +95,7 @@ void nfct_destroy(struct nf_conntrack *ct) /** * nf_sizeof - return the size in bytes of a certain conntrack object - * @ct: pointer to the conntrack object + * \param ct pointer to the conntrack object */ size_t nfct_sizeof(const struct nf_conntrack *ct) { @@ -57,11 +108,11 @@ size_t nfct_sizeof(const struct nf_conntrack *ct) * * Use this function if you want to allocate a conntrack object in the stack * instead of the heap. For example: - * - * char buf[nfct_maxsize()]; - * struct nf_conntrack *ct = (struct nf_conntrack *) buf; - * memset(ct, 0, nfct_maxsize()); - * + * \verbatim + char buf[nfct_maxsize()]; + struct nf_conntrack *ct = (struct nf_conntrack *) buf; + memset(ct, 0, nfct_maxsize()); +\endverbatim * Note: As for now this function returns the same size that nfct_sizeof(ct) * does although _this could change in the future_. Therefore, do not assume * that nfct_sizeof(ct) == nfct_maxsize(). @@ -73,7 +124,7 @@ size_t nfct_maxsize(void) /** * nfct_clone - clone a conntrack object - * @ct: pointer to a valid conntrack object + * \param ct pointer to a valid conntrack object * * On error, NULL is returned and errno is appropiately set. Otherwise, * a valid pointer to the clone conntrack is returned. @@ -93,8 +144,8 @@ struct nf_conntrack *nfct_clone(const struct nf_conntrack *ct) /** * nfct_setobjopt - set a certain option for a conntrack object - * @ct: conntrack object - * @option: option parameter + * \param ct conntrack object + * \param option option parameter * * In case of error, -1 is returned and errno is appropiately set. On success, * 0 is returned. @@ -113,8 +164,8 @@ int nfct_setobjopt(struct nf_conntrack *ct, unsigned int option) /** * nfct_getobjopt - get a certain option for a conntrack object - * @ct: conntrack object - * @option: option parameter + * \param ct conntrack object + * \param option option parameter * * In case of error, -1 is returned and errno is appropiately set. On success, * 0 is returned. @@ -131,11 +182,21 @@ int nfct_getobjopt(const struct nf_conntrack *ct, unsigned int option) return __getobjopt(ct, option); } +/** + * @} + */ + +/** + * \defgroup LibrarySetup Library setup + * @{ + */ + /** * nf_callback_register - register a callback - * @h: library handler - * @cb: callback used to process conntrack received - * @data: data used by the callback, if any. + * \param h library handler + * \param type message type (see enum nf_conntrack_msg_type definition) + * \param cb callback used to process conntrack received + * \param data data used by the callback, if any. * * This function register a callback to handle the conntrack received, * in case of error -1 is returned and errno is set appropiately, otherwise @@ -182,7 +243,7 @@ int nfct_callback_register(struct nfct_handle *h, /** * nfct_callback_unregister - unregister a callback - * @h: library handler + * \param h library handler */ void nfct_callback_unregister(struct nfct_handle *h) { @@ -201,9 +262,9 @@ void nfct_callback_unregister(struct nfct_handle *h) /** * nf_callback_register2 - register a callback - * @h: library handler - * @cb: callback used to process conntrack received - * @data: data used by the callback, if any. + * \param h library handler + * \param cb callback used to process conntrack received + * \param data data used by the callback, if any. * * This function register a callback to handle the conntrack received, * in case of error -1 is returned and errno is set appropiately, otherwise @@ -256,7 +317,7 @@ int nfct_callback_register2(struct nfct_handle *h, /** * nfct_callback_unregister2 - unregister a callback - * @h: library handler + * \param h library handler */ void nfct_callback_unregister2(struct nfct_handle *h) { @@ -273,16 +334,25 @@ void nfct_callback_unregister2(struct nfct_handle *h) h->nfnl_cb.attr_count = 0; } +/** + * @} + */ + +/** + * \defgroup ct Conntrack object handling + * @{ + */ + /** * nfct_set_attr - set the value of a certain conntrack attribute - * @ct: pointer to a valid conntrack - * @type: attribute type - * @value: pointer to the attribute value + * \param ct pointer to a valid conntrack + * \param type attribute type + * \param value pointer to the attribute value * * Note that certain attributes are unsettable: - * ATTR_USE - * ATTR_ID - * ATTR_*_COUNTER_* + * - ATTR_USE + * - ATTR_ID + * - ATTR_*_COUNTER_* * The call of this function for such attributes do nothing. */ void nfct_set_attr(struct nf_conntrack *ct, @@ -303,9 +373,9 @@ void nfct_set_attr(struct nf_conntrack *ct, /** * nfct_set_attr_u8 - set the value of a certain conntrack attribute - * @ct: pointer to a valid conntrack - * @type: attribute type - * @value: unsigned 8 bits attribute value + * \param ct pointer to a valid conntrack + * \param type attribute type + * \param value unsigned 8 bits attribute value */ void nfct_set_attr_u8(struct nf_conntrack *ct, const enum nf_conntrack_attr type, @@ -316,9 +386,9 @@ void nfct_set_attr_u8(struct nf_conntrack *ct, /** * nfct_set_attr_u16 - set the value of a certain conntrack attribute - * @ct: pointer to a valid conntrack - * @type: attribute type - * @value: unsigned 16 bits attribute value + * \param ct pointer to a valid conntrack + * \param type attribute type + * \param value unsigned 16 bits attribute value */ void nfct_set_attr_u16(struct nf_conntrack *ct, const enum nf_conntrack_attr type, @@ -329,9 +399,9 @@ void nfct_set_attr_u16(struct nf_conntrack *ct, /** * nfct_set_attr_u32 - set the value of a certain conntrack attribute - * @ct: pointer to a valid conntrack - * @type: attribute type - * @value: unsigned 32 bits attribute value + * \param ct pointer to a valid conntrack + * \param type attribute type + * \param value unsigned 32 bits attribute value */ void nfct_set_attr_u32(struct nf_conntrack *ct, const enum nf_conntrack_attr type, @@ -342,9 +412,9 @@ void nfct_set_attr_u32(struct nf_conntrack *ct, /** * nfct_set_attr_u64 - set the value of a certain conntrack attribute - * @ct: pointer to a valid conntrack - * @type: attribute type - * @value: unsigned 64 bits attribute value + * \param ct pointer to a valid conntrack + * \param type attribute type + * \param value unsigned 64 bits attribute value */ void nfct_set_attr_u64(struct nf_conntrack *ct, const enum nf_conntrack_attr type, @@ -355,8 +425,8 @@ void nfct_set_attr_u64(struct nf_conntrack *ct, /** * nfct_get_attr - get a conntrack attribute - * ct: pointer to a valid conntrack - * @type: attribute type + * \param ct pointer to a valid conntrack + * \param type attribute type * * In case of success a valid pointer to the attribute requested is returned, * on error NULL is returned and errno is set appropiately. @@ -383,8 +453,8 @@ const void *nfct_get_attr(const struct nf_conntrack *ct, /** * nfct_get_attr_u8 - get attribute of unsigned 8-bits long - * @ct: pointer to a valid conntrack - * @type: attribute type + * \param ct pointer to a valid conntrack + * \param type attribute type * * Returns the value of the requested attribute, if the attribute is not * set, 0 is returned. In order to check if the attribute is set or not, @@ -399,8 +469,8 @@ u_int8_t nfct_get_attr_u8(const struct nf_conntrack *ct, /** * nfct_get_attr_u16 - get attribute of unsigned 16-bits long - * @ct: pointer to a valid conntrack - * @type: attribute type + * \param ct pointer to a valid conntrack + * \param type attribute type * * Returns the value of the requested attribute, if the attribute is not * set, 0 is returned. In order to check if the attribute is set or not, @@ -415,8 +485,8 @@ u_int16_t nfct_get_attr_u16(const struct nf_conntrack *ct, /** * nfct_get_attr_u32 - get attribute of unsigned 32-bits long - * @ct: pointer to a valid conntrack - * @type: attribute type + * \param ct pointer to a valid conntrack + * \param type attribute type * * Returns the value of the requested attribute, if the attribute is not * set, 0 is returned. In order to check if the attribute is set or not, @@ -431,8 +501,8 @@ u_int32_t nfct_get_attr_u32(const struct nf_conntrack *ct, /** * nfct_get_attr_u64 - get attribute of unsigned 32-bits long - * @ct: pointer to a valid conntrack - * @type: attribute type + * \param ct pointer to a valid conntrack + * \param type attribute type * * Returns the value of the requested attribute, if the attribute is not * set, 0 is returned. In order to check if the attribute is set or not, @@ -447,8 +517,8 @@ u_int64_t nfct_get_attr_u64(const struct nf_conntrack *ct, /** * nfct_attr_is_set - check if a certain attribute is set - * @ct: pointer to a valid conntrack object - * @type: attribute type + * \param ct pointer to a valid conntrack object + * \param type attribute type * * On error, -1 is returned and errno is set appropiately, otherwise * the value of the attribute is returned. @@ -467,9 +537,9 @@ int nfct_attr_is_set(const struct nf_conntrack *ct, /** * nfct_attr_is_set_array - check if an array of attribute types is set - * @ct: pointer to a valid conntrack object - * @array: attribute type array - * @size: size of the array + * \param ct pointer to a valid conntrack object + * \param array attribute type array + * \param size size of the array * * On error, -1 is returned and errno is set appropiately, otherwise * the value of the attribute is returned. @@ -495,9 +565,9 @@ int nfct_attr_is_set_array(const struct nf_conntrack *ct, /** * nfct_attr_unset - unset a certain attribute - * @type: attribute type - * @ct: pointer to a valid conntrack object - * + * \param type attribute type + * \param ct pointer to a valid conntrack object + * * On error, -1 is returned and errno is set appropiately, otherwise * 0 is returned. */ @@ -517,9 +587,9 @@ int nfct_attr_unset(struct nf_conntrack *ct, /** * nfct_set_attr_grp - set a group of attributes - * @ct: pointer to a valid conntrack object - * @type: attribute group (see ATTR_GRP_*) - * @data: pointer to struct (see struct nfct_attr_grp_*) + * \param ct pointer to a valid conntrack object + * \param type attribute group (see ATTR_GRP_*) + * \param data pointer to struct (see struct nfct_attr_grp_*) * * Note that calling this function for ATTR_GRP_COUNTER_* does nothing since * counters are unsettable. @@ -541,9 +611,9 @@ void nfct_set_attr_grp(struct nf_conntrack *ct, /** * nfct_get_attr_grp - get an attribute group - * @ct: pointer to a valid conntrack object - * @type: attribute group (see ATTR_GRP_*) - * @data: pointer to struct (see struct nfct_attr_grp_*) + * \param ct pointer to a valid conntrack object + * \param type attribute group (see ATTR_GRP_*) + * \param data pointer to struct (see struct nfct_attr_grp_*) * * On error, it returns -1 and errno is appropriately set. On success, the * data pointer contains the attribute group. @@ -569,8 +639,8 @@ int nfct_get_attr_grp(const struct nf_conntrack *ct, /** * nfct_attr_grp_is_set - check if an attribute group is set - * @ct: pointer to a valid conntrack object - * @type: attribute group (see ATTR_GRP_*) + * \param ct pointer to a valid conntrack object + * \param type attribute group (see ATTR_GRP_*) * * If the attribute group is set, this function returns 1, otherwise 0. */ @@ -588,8 +658,8 @@ int nfct_attr_grp_is_set(const struct nf_conntrack *ct, /** * nfct_attr_grp_unset - unset an attribute group - * @ct: pointer to a valid conntrack object - * @type: attribute group (see ATTR_GRP_*) + * \param ct pointer to a valid conntrack object + * \param type attribute group (see ATTR_GRP_*) * * On error, it returns -1 and errno is appropriately set. On success, * this function returns 0. @@ -608,14 +678,23 @@ int nfct_attr_grp_unset(struct nf_conntrack *ct, return 0; } +/** + * @} + */ + +/** + * \defgroup nl Low level object to Netlink message + * @{ + */ + /** * nfct_build_conntrack - build a netlink message from a conntrack object - * @ssh: nfnetlink subsystem handler - * @req: buffer used to build the netlink message - * @size: size of the buffer passed - * @type: netlink message type - * @flags: netlink flags - * @ct: pointer to a conntrack object + * \param ssh nfnetlink subsystem handler + * \param req buffer used to build the netlink message + * \param size size of the buffer passed + * \param type netlink message type + * \param flags netlink flags + * \param ct pointer to a conntrack object * * This is a low level function for those that require to be close to * netlink details via libnfnetlink. If you do want to obviate the netlink @@ -640,11 +719,11 @@ int nfct_build_conntrack(struct nfnl_subsys_handle *ssh, /** * nfct_build_query - build a query in netlink message format for ctnetlink - * @ssh: nfnetlink subsystem handler - * @qt: query type - * @data: data required to build the query - * @req: buffer to build the netlink message - * @size: size of the buffer passed + * \param ssh nfnetlink subsystem handler + * \param qt query type + * \param data data required to build the query + * \param req buffer to build the netlink message + * \param size size of the buffer passed * * This is a low level function, use it if you want to require to work * with netlink details via libnfnetlink, otherwise we suggest you to @@ -654,18 +733,18 @@ int nfct_build_conntrack(struct nfnl_subsys_handle *ssh, * depending on the request. * * For query types: - * NFCT_Q_CREATE: add a new conntrack, if it exists, fail - * NFCT_O_CREATE_UPDATE: add a new conntrack, if it exists, update it - * NFCT_Q_UPDATE: update a conntrack - * NFCT_Q_DESTROY: destroy a conntrack - * NFCT_Q_GET: get a conntrack + * - NFCT_Q_CREATE: add a new conntrack, if it exists, fail + * - NFCT_O_CREATE_UPDATE: add a new conntrack, if it exists, update it + * - NFCT_Q_UPDATE: update a conntrack + * - NFCT_Q_DESTROY: destroy a conntrack + * - NFCT_Q_GET: get a conntrack * * Pass a valid pointer to a conntrack object. * * For query types: - * NFCT_Q_FLUSH: flush the conntrack table - * NFCT_Q_DUMP: dump the conntrack table - * NFCT_Q_DUMP_RESET: dump the conntrack table and reset counters + * - NFCT_Q_FLUSH: flush the conntrack table + * - NFCT_Q_DUMP: dump the conntrack table + * - NFCT_Q_DUMP_RESET: dump the conntrack table and reset counters * * Pass a valid pointer to the protocol family (u_int32_t) * @@ -722,9 +801,9 @@ int nfct_build_query(struct nfnl_subsys_handle *ssh, /** * nfct_parse_conntrack - translate a netlink message to a conntrack object - * @type: do the translation iif the message type is of a certain type - * @nlh: pointer to the netlink message - * @ct: pointer to the conntrack object + * \param type do the translation iif the message type is of a certain type + * \param nlh pointer to the netlink message + * \param ct pointer to the conntrack object * * This is a low level function, use it in case that you require to work * with netlink details via libnfnetlink. Otherwise, we suggest you to @@ -732,10 +811,10 @@ int nfct_build_query(struct nfnl_subsys_handle *ssh, * * The message types are: * - * NFCT_T_NEW: parse messages with new conntracks - * NFCT_T_UPDATE: parse messages with conntrack updates - * NFCT_T_DESTROY: parse messages with conntrack destroy - * NFCT_T_ALL: all message types + * - NFCT_T_NEW: parse messages with new conntracks + * - NFCT_T_UPDATE: parse messages with conntrack updates + * - NFCT_T_DESTROY: parse messages with conntrack destroy + * - NFCT_T_ALL: all message types * * The message type is a flag, therefore the can be combined, ie. * NFCT_T_NEW | NFCT_T_DESTROY to parse only new and destroy messages @@ -773,11 +852,20 @@ int nfct_parse_conntrack(enum nf_conntrack_msg_type type, return flags; } +/** + * @} + */ + +/** + * \defgroup cmd Send commands to kernel-space and receive replies + * @{ + */ + /** * nfct_query - send a query to ctnetlink and handle the reply - * @h: library handler - * @qt: query type - * @data: data required to send the query + * \param h library handler + * \param qt query type + * \param data data required to send the query * * On error, -1 is returned and errno is explicitely set. On success, 0 * is returned. @@ -803,9 +891,9 @@ int nfct_query(struct nfct_handle *h, /** * nfct_send - send a query to ctnetlink - * @h: library handler - * @qt: query type - * @data: data required to send the query + * \param h library handler + * \param qt query type + * \param data data required to send the query * * Like nfct_query but we do not wait for the reply from ctnetlink. * You can use nfct_send() and nfct_catch() to emulate nfct_query(). @@ -836,7 +924,7 @@ int nfct_send(struct nfct_handle *h, /** * nfct_catch - catch events - * @h: library handler + * \param h library handler * * On error, -1 is returned and errno is set appropiately. On success, * a value greater or equal to 0 is returned indicating the callback @@ -849,14 +937,23 @@ int nfct_catch(struct nfct_handle *h) return nfnl_catch(h->nfnlh); } +/** + * @} + */ + +/** + * \defgroup ct Conntrack object handling + * @{ + */ + /** * nfct_snprintf - print a conntrack object to a buffer - * @buf: buffer used to build the printable conntrack - * @size: size of the buffer - * @ct: pointer to a valid conntrack object - * @message_type: print message type (NFCT_T_UNKNOWN, NFCT_T_NEW,...) - * @output_type: print type (NFCT_O_DEFAULT, NFCT_O_XML, ...) - * @flags: extra flags for the output type (NFCT_OF_LAYER3) + * \param buf buffer used to build the printable conntrack + * \param size size of the buffer + * \param ct pointer to a valid conntrack object + * \param message_type print message type (NFCT_T_UNKNOWN, NFCT_T_NEW,...) + * \param output_type print type (NFCT_O_DEFAULT, NFCT_O_XML, ...) + * \param flags extra flags for the output type (NFCT_OF_LAYER3) * * If you are listening to events, probably you want to display the message * type as well. In that case, set the message type parameter to any of the @@ -864,13 +961,13 @@ int nfct_catch(struct nfct_handle *h) * If you pass NFCT_T_UNKNOWN, the message type will not be output. * * Currently, the output available are: - * NFCT_O_DEFAULT: default /proc-like output - * NFCT_O_XML: XML output + * - NFCT_O_DEFAULT: default /proc-like output + * - NFCT_O_XML: XML output * * The output flags are: - * NFCT_OF_SHOW_LAYER3: include layer 3 information in the output, + * - NFCT_OF_SHOW_LAYER3: include layer 3 information in the output, * this is *only* required by NFCT_O_DEFAULT. - * NFCT_OF_TIME: display time. + * - NFCT_OF_TIME: display time. * * This function returns the size of the information that _would_ have been * written to the buffer, even if there was no room for it. Thus, the @@ -890,10 +987,14 @@ int nfct_snprintf(char *buf, return __snprintf_conntrack(buf, size, ct, msg_type, out_type, flags); } +/** + * @} + */ + /** * nfct_compare - compare two conntrack objects - * @ct1: pointer to a valid conntrack object - * @ct2: pointer to a valid conntrack object + * \param ct1 pointer to a valid conntrack object + * \param ct2 pointer to a valid conntrack object * * This function only compare attribute set in both objects, ie. if a certain * attribute is not set in ct1 but it is in ct2, then the value of such @@ -915,9 +1016,9 @@ int nfct_compare(const struct nf_conntrack *ct1, /** * nfct_cmp - compare two conntrack objects - * @ct1: pointer to a valid conntrack object - * @ct2: pointer to a valid conntrack object - * @flags: flags + * \param ct1 pointer to a valid conntrack object + * \param ct2 pointer to a valid conntrack object + * \param flags flags * * This function only compare attribute set in both objects, by default * the comparison is not strict, ie. if a certain attribute is not set in one @@ -927,23 +1028,23 @@ int nfct_compare(const struct nf_conntrack *ct1, * * The available flags are: * - * NFCT_CMP_STRICT: the compared objects must have the same attributes + * - NFCT_CMP_STRICT: the compared objects must have the same attributes * and the same values, otherwise it returns that the objects are * different. - * NFCT_CMP_MASK: the first object is used as mask, this means that + * - NFCT_CMP_MASK: the first object is used as mask, this means that * if an attribute is present in ct1 but not in ct2, this function * returns that the objects are different. - * NFCT_CMP_ALL: full comparison of both objects - * NFCT_CMP_ORIG: it only compares the source and destination address; + * - NFCT_CMP_ALL: full comparison of both objects + * - NFCT_CMP_ORIG: it only compares the source and destination address; * source and destination ports; the layer 3 and 4 protocol numbers * of the original direction; and the id (if present). - * NFCT_CMP_REPL: like NFCT_CMP_REPL but it compares the flow + * - NFCT_CMP_REPL: like NFCT_CMP_REPL but it compares the flow * information that goes in the reply direction. - * NFCT_CMP_TIMEOUT_EQ: timeout(ct1) == timeout(ct2) - * NFCT_CMP_TIMEOUT_GT: timeout(ct1) > timeout(ct2) - * NFCT_CMP_TIMEOUT_LT: timeout(ct1) < timeout(ct2) - * NFCT_CMP_TIMEOUT_GE: timeout(ct1) >= timeout(ct2) - * NFCT_CMP_TIMEOUT_LE: timeout(ct1) <= timeout(ct2) + * - NFCT_CMP_TIMEOUT_EQ: timeout(ct1) == timeout(ct2) + * - NFCT_CMP_TIMEOUT_GT: timeout(ct1) > timeout(ct2) + * - NFCT_CMP_TIMEOUT_LT: timeout(ct1) < timeout(ct2) + * - NFCT_CMP_TIMEOUT_GE: timeout(ct1) >= timeout(ct2) + * - NFCT_CMP_TIMEOUT_LE: timeout(ct1) <= timeout(ct2) * * The status bits comparison is status(ct1) & status(ct2) == status(ct1). * @@ -962,9 +1063,9 @@ int nfct_cmp(const struct nf_conntrack *ct1, /** * nfct_copy - copy part of one source object to another - * @ct1: destination object - * @ct2: source object - * @flags: flags + * \param ct1 destination object + * \param ct2 source object + * \param flags flags * * This function copies one part of the source object to the target. * It behaves like clone but: @@ -973,13 +1074,13 @@ int nfct_cmp(const struct nf_conntrack *ct1, * 2) You can copy only a part of the source object to the target * * The current supported flags are: - * NFCT_CP_ALL: that copies the object entirely. - * NFCT_CP_ORIG and NFCT_CP_REPL: that can be used to copy the + * - NFCT_CP_ALL: that copies the object entirely. + * - NFCT_CP_ORIG and NFCT_CP_REPL: that can be used to copy the * information that identifies a flow in the original and the reply * direction. This information is usually composed of: source and * destination IP address; source and destination ports; layer 3 * and 4 protocol number. - * NFCT_CP_META: that copies the metainformation + * - NFCT_CP_META: that copies the metainformation * (all the attributes >= ATTR_TCP_STATE) */ void nfct_copy(struct nf_conntrack *ct1, @@ -1062,9 +1163,9 @@ void nfct_copy(struct nf_conntrack *ct1, /** * nfct_copy_attr - copy an attribute of one source object to another - * @ct1: destination object - * @ct2: source object - * @flags: flags + * \param ct1 destination object + * \param ct2 source object + * \param flags flags * * This function copies one attribute (if present) to another object. */ @@ -1079,6 +1180,16 @@ void nfct_copy_attr(struct nf_conntrack *ct1, } } +/** + * @} + */ + +/** + * \defgroup bsf Kernel-space filtering for events + * + * @{ + */ + /** * nfct_filter_create - create a filter * @@ -1092,7 +1203,7 @@ struct nfct_filter *nfct_filter_create(void) /** * nfct_filter_destroy - destroy a filter - * @filter: filter that we want to destroy + * \param filter filter that we want to destroy * * This function releases the memory that is used by the filter object. * However, please note that this function does *not* detach an already @@ -1107,9 +1218,9 @@ void nfct_filter_destroy(struct nfct_filter *filter) /** * nfct_filter_add_attr - add a filter attribute of the filter object - * @filter: filter object that we want to modify - * @type: filter attribute type - * @value: pointer to the value of the filter attribute + * \param filter filter object that we want to modify + * \param type filter attribute type + * \param value pointer to the value of the filter attribute * * Limitations: You can add up to 127 IPv4 addresses and masks for * NFCT_FILTER_SRC_IPV4 and, similarly, 127 for NFCT_FILTER_DST_IPV4. @@ -1132,9 +1243,9 @@ void nfct_filter_add_attr(struct nfct_filter *filter, /** * nfct_filter_add_attr_u32 - add an u32 filter attribute of the filter object - * @filter: filter object that we want to modify - * @type: filter attribute type - * @value: value of the filter attribute using unsigned int (32 bits). + * \param filter filter object that we want to modify + * \param type filter attribute type + * \param value value of the filter attribute using unsigned int (32 bits). * * Limitations: You can add up to 255 protocols which is a reasonable limit. */ @@ -1147,9 +1258,9 @@ void nfct_filter_add_attr_u32(struct nfct_filter *filter, /** * nfct_filter_set_logic - set the filter logic for an attribute type - * @filter: filter object that we want to modify - * @type: filter attribute type - * @logic: filter logic that we want to use + * \param filter filter object that we want to modify + * \param type filter attribute type + * \param logic filter logic that we want to use * * You can only use this function once to set the filtering logic for * one attribute. You can define two logics: NFCT_FILTER_POSITIVE_LOGIC @@ -1181,8 +1292,8 @@ int nfct_filter_set_logic(struct nfct_filter *filter, /** * nfct_filter_attach - attach a filter to a socket descriptor - * @fd: socket descriptor - * @filter: filter that we want to attach to the socket + * \param fd socket descriptor + * \param filter filter that we want to attach to the socket * * This function returns -1 on error and set errno appropriately. If the * function returns EINVAL probably you have found a bug in it. Please, @@ -1197,7 +1308,7 @@ int nfct_filter_attach(int fd, struct nfct_filter *filter) /** * nfct_filter_detach - detach an existing filter - * @fd: socket descriptor + * \param fd socket descriptor * * This function returns -1 on error and set errno appropriately. */ @@ -1207,3 +1318,7 @@ int nfct_filter_detach(int fd) return setsockopt(fd, SOL_SOCKET, SO_DETACH_FILTER, &val, sizeof(val)); } + +/** + * @} + */ diff --git a/src/expect/api.c b/src/expect/api.c index 7a11f53..d560178 100644 --- a/src/expect/api.c +++ b/src/expect/api.c @@ -12,6 +12,11 @@ #include "internal/internal.h" +/** + * \defgroup exp Expect object handling + * @{ + */ + /** * nfexp_new - allocate a new expectation * @@ -33,7 +38,7 @@ struct nf_expect *nfexp_new(void) /** * nfexp_destroy - release an expectation object - * @exp: pointer to the expectation object + * \param exp pointer to the expectation object */ void nfexp_destroy(struct nf_expect *exp) { @@ -44,7 +49,7 @@ void nfexp_destroy(struct nf_expect *exp) /** * nfexp_sizeof - return the size in bytes of a certain expect object - * @exp: pointer to the expect object + * \param exp pointer to the expect object */ size_t nfexp_sizeof(const struct nf_expect *exp) { @@ -57,11 +62,11 @@ size_t nfexp_sizeof(const struct nf_expect *exp) * * Use this function if you want to allocate a expect object in the stack * instead of the heap. For example: - * + * * char buf[nfexp_maxsize()]; * struct nf_expect *exp = (struct nf_expect *) buf; * memset(exp, 0, nfexp_maxsize()); - * + * * Note: As for now this function returns the same size that nfexp_sizeof(exp) * does although _this could change in the future_. Therefore, do not assume * that nfexp_sizeof(exp) == nfexp_maxsize(). @@ -73,7 +78,7 @@ size_t nfexp_maxsize(void) /** * nfexp_clone - clone a expectation object - * @exp: pointer to a valid expectation object + * \param exp pointer to a valid expectation object * * On error, NULL is returned and errno is appropiately set. Otherwise, * a valid pointer to the clone expect is returned. @@ -91,16 +96,25 @@ struct nf_expect *nfexp_clone(const struct nf_expect *exp) return clone; } +/** + * @} + */ + +/** + * \defgroup LibrarySetup Library setup + * @{ + */ + /** * nfexp_callback_register - register a callback - * @h: library handler - * @cb: callback used to process expect received - * @data: data used by the callback, if any. + * \param h library handler + * \param cb callback used to process expect received + * \param data data used by the callback, if any. * * This function register a callback to handle the expect received, * in case of error -1 is returned and errno is set appropiately, otherwise * 0 is returned. - * + * * Note that the data parameter is optional, if you do not want to pass any * data to your callback, then use NULL. */ @@ -142,7 +156,7 @@ int nfexp_callback_register(struct nfct_handle *h, /** * nfexp_callback_unregister - unregister a callback - * @h: library handler + * \param h library handler */ void nfexp_callback_unregister(struct nfct_handle *h) { @@ -161,20 +175,20 @@ void nfexp_callback_unregister(struct nfct_handle *h) /** * nfexp_callback_register2 - register a callback - * @h: library handler - * @cb: callback used to process expect received - * @data: data used by the callback, if any. + * \param h library handler + * \param cb callback used to process expect received + * \param data data used by the callback, if any. * * This function register a callback to handle the expect received, * in case of error -1 is returned and errno is set appropiately, otherwise * 0 is returned. - * + * * Note that the data parameter is optional, if you do not want to pass any * data to your callback, then use NULL. - * + * * NOTICE: The difference with nfexp_callback_register() is that this function * uses the new callback interface that includes the Netlink header. - * + * * WARNING: Don't mix nfexp_callback_register() and nfexp_callback_register2() * calls, use only once at a time. */ @@ -217,7 +231,7 @@ int nfexp_callback_register2(struct nfct_handle *h, /** * nfexp_callback_unregister2 - unregister a callback - * @h: library handler + * \param h library handler */ void nfexp_callback_unregister2(struct nfct_handle *h) { @@ -234,11 +248,20 @@ void nfexp_callback_unregister2(struct nfct_handle *h) h->nfnl_cb.attr_count = 0; } +/** + * @} + */ + +/** + * \defgroup exp Expect object handling + * @{ + */ + /** * nfexp_set_attr - set the value of a certain expect attribute - * @exp: pointer to a valid expect - * @type: attribute type - * @value: pointer to the attribute value + * \param exp pointer to a valid expect + * \param type attribute type + * \param value pointer to the attribute value * * Note that certain attributes are unsettable: * - ATTR_EXP_USE @@ -264,9 +287,9 @@ void nfexp_set_attr(struct nf_expect *exp, /** * nfexp_set_attr_u8 - set the value of a certain expect attribute - * @exp: pointer to a valid expect - * @type: attribute type - * @value: unsigned 8 bits attribute value + * \param exp pointer to a valid expect + * \param type attribute type + * \param value unsigned 8 bits attribute value */ void nfexp_set_attr_u8(struct nf_expect *exp, const enum nf_expect_attr type, @@ -277,9 +300,9 @@ void nfexp_set_attr_u8(struct nf_expect *exp, /** * nfexp_set_attr_u16 - set the value of a certain expect attribute - * @exp: pointer to a valid expect - * @type: attribute type - * @value: unsigned 16 bits attribute value + * \param exp pointer to a valid expect + * \param type attribute type + * \param value unsigned 16 bits attribute value */ void nfexp_set_attr_u16(struct nf_expect *exp, const enum nf_expect_attr type, @@ -290,9 +313,9 @@ void nfexp_set_attr_u16(struct nf_expect *exp, /** * nfexp_set_attr_u32 - set the value of a certain expect attribute - * @exp: pointer to a valid expect - * @type: attribute type - * @value: unsigned 32 bits attribute value + * \param exp pointer to a valid expect + * \param type attribute type + * \param value unsigned 32 bits attribute value */ void nfexp_set_attr_u32(struct nf_expect *exp, const enum nf_expect_attr type, @@ -303,8 +326,8 @@ void nfexp_set_attr_u32(struct nf_expect *exp, /** * nfexp_get_attr - get an expect attribute - * exp: pointer to a valid expect - * @type: attribute type + * \param exp pointer to a valid expect + * \param type attribute type * * In case of success a valid pointer to the attribute requested is returned, * on error NULL is returned and errno is set appropiately. @@ -329,8 +352,8 @@ const void *nfexp_get_attr(const struct nf_expect *exp, /** * nfexp_get_attr_u8 - get attribute of unsigned 8-bits long - * @exp: pointer to a valid expectation - * @type: attribute type + * \param exp pointer to a valid expectation + * \param type attribute type * * Returns the value of the requested attribute, if the attribute is not * set, 0 is returned. In order to check if the attribute is set or not, @@ -345,8 +368,8 @@ u_int8_t nfexp_get_attr_u8(const struct nf_expect *exp, /** * nfexp_get_attr_u16 - get attribute of unsigned 16-bits long - * @exp: pointer to a valid expectation - * @type: attribute type + * \param exp pointer to a valid expectation + * \param type attribute type * * Returns the value of the requested attribute, if the attribute is not * set, 0 is returned. In order to check if the attribute is set or not, @@ -361,8 +384,8 @@ u_int16_t nfexp_get_attr_u16(const struct nf_expect *exp, /** * nfexp_get_attr_u32 - get attribute of unsigned 32-bits long - * @exp: pointer to a valid expectation - * @type: attribute type + * \param exp pointer to a valid expectation + * \param type attribute type * * Returns the value of the requested attribute, if the attribute is not * set, 0 is returned. In order to check if the attribute is set or not, @@ -377,8 +400,8 @@ u_int32_t nfexp_get_attr_u32(const struct nf_expect *exp, /** * nfexp_attr_is_set - check if a certain attribute is set - * @exp: pointer to a valid expectation object - * @type: attribute type + * \param exp pointer to a valid expectation object + * \param type attribute type * * On error, -1 is returned and errno is set appropiately, otherwise * the value of the attribute is returned. @@ -397,9 +420,9 @@ int nfexp_attr_is_set(const struct nf_expect *exp, /** * nfexp_attr_unset - unset a certain attribute - * @type: attribute type - * @exp: pointer to a valid expectation object - * + * \param type attribute type + * \param exp pointer to a valid expectation object + * * On error, -1 is returned and errno is set appropiately, otherwise * 0 is returned. */ @@ -417,19 +440,28 @@ int nfexp_attr_unset(struct nf_expect *exp, return 0; } +/** + * @} + */ + +/** + * \defgroup nl Low level object to Netlink message + * @{ + */ + /** * nfexp_build_expect - build a netlink message from a conntrack object - * @ssh: nfnetlink subsystem handler - * @req: buffer used to build the netlink message - * @size: size of the buffer passed - * @type: netlink message type - * @flags: netlink flags - * @exp: pointer to a conntrack object + * \param ssh nfnetlink subsystem handler + * \param req buffer used to build the netlink message + * \param size size of the buffer passed + * \param type netlink message type + * \param flags netlink flags + * \param exp pointer to a conntrack object * * This is a low level function for those that require to be close to * netlink details via libnfnetlink. If you do want to obviate the netlink * details then we suggest you to use nfexp_query. - * + * * On error, -1 is returned and errno is appropiately set. * On success, 0 is returned. */ @@ -449,31 +481,31 @@ static int nfexp_build_expect(struct nfnl_subsys_handle *ssh, /** * nfexp_build_query - build a query in netlink message format for ctnetlink - * @ssh: nfnetlink subsystem handler - * @qt: query type - * @data: data required to build the query - * @req: buffer to build the netlink message - * @size: size of the buffer passed + * \param ssh nfnetlink subsystem handler + * \param qt query type + * \param data data required to build the query + * \param req buffer to build the netlink message + * \param size size of the buffer passed * * This is a low level function, use it if you want to require to work * with netlink details via libnfnetlink, otherwise we suggest you to * use nfexp_query. - * + * * The pointer to data can be a conntrack object or the protocol family * depending on the request. - * + * * For query types: * NFEXP_Q_CREATE * NFEXP_Q_DESTROY - * + * * Pass a valid pointer to an expectation object. - * + * * For query types: * NFEXP_Q_FLUSH * NFEXP_Q_DUMP - * + * * Pass a valid pointer to the protocol family (u_int8_t) - * + * * On success, 0 is returned. On error, -1 is returned and errno is set * appropiately. */ @@ -517,24 +549,24 @@ static int nfexp_build_query(struct nfnl_subsys_handle *ssh, /** * nfexp_parse_expect - translate a netlink message to a conntrack object - * @type: do the translation iif the message type is of a certain type - * @nlh: pointer to the netlink message - * @exp: pointer to the conntrack object + * \param type do the translation iif the message type is of a certain type + * \param nlh pointer to the netlink message + * \param exp pointer to the conntrack object * * This is a low level function, use it in case that you require to work * with netlink details via libnfnetlink. Otherwise, we suggest you to * use the high level API. - * + * * The message types are: - * + * * NFEXP_T_NEW: parse messages with new conntracks * NFEXP_T_UPDATE: parse messages with conntrack updates * NFEXP_T_DESTROY: parse messages with conntrack destroy * NFEXP_T_ALL: all message types - * + * * The message type is a flag, therefore the can be combined, ie. * NFEXP_T_NEW | NFEXP_T_DESTROY to parse only new and destroy messages - * + * * On error, NFEXP_T_ERROR is returned and errno is set appropiately. If * the message received is not of the requested type then 0 is returned, * otherwise this function returns the message type parsed. @@ -568,11 +600,20 @@ static int nfexp_parse_expect(enum nf_conntrack_msg_type type, return flags; } +/** + * @} + */ + +/** + * \defgroup cmd Send commands to kernel-space and receive replies + * @{ + */ + /** * nfexp_query - send a query to ctnetlink - * @h: library handler - * @qt: query type - * @data: data required to send the query + * \param h library handler + * \param qt query type + * \param data data required to send the query * * On error, -1 is returned and errno is explicitely set. On success, 0 * is returned. @@ -598,7 +639,7 @@ int nfexp_query(struct nfct_handle *h, /** * nfexp_catch - catch events - * @h: library handler + * \param h library handler * * On error, -1 is returned and errno is set appropiately. On success, * a value greater or equal to 0 is returned indicating the callback @@ -611,28 +652,37 @@ int nfexp_catch(struct nfct_handle *h) return nfnl_catch(h->nfnlh); } +/** + * @} + */ + +/** + * \defgroup exp Expect object handling + * @{ + */ + /** * nfexp_snprintf - print a conntrack object to a buffer - * @buf: buffer used to build the printable conntrack - * @size: size of the buffer - * @exp: pointer to a valid expectation object - * @message_type: print message type (NFEXP_T_UNKNOWN, NFEXP_T_NEW,...) - * @output_type: print type (NFEXP_O_DEFAULT, NFEXP_O_XML, ...) - * @flags: extra flags for the output type (NFEXP_OF_LAYER3) - * - * If you are listening to events, probably you want to display the message + * \param buf buffer used to build the printable conntrack + * \param size size of the buffer + * \param exp pointer to a valid expectation object + * \param message_type print message type (NFEXP_T_UNKNOWN, NFEXP_T_NEW,...) + * \param output_type print type (NFEXP_O_DEFAULT, NFEXP_O_XML, ...) + * \param flags extra flags for the output type (NFEXP_OF_LAYER3) + * + * If you are listening to events, probably you want to display the message * type as well. In that case, set the message type parameter to any of the * known existing types, ie. NFEXP_T_NEW, NFEXP_T_UPDATE, NFEXP_T_DESTROY. * If you pass NFEXP_T_UNKNOWN, the message type will not be output. - * + * * Currently, the output available are: * - NFEXP_O_DEFAULT: default /proc-like output * - NFEXP_O_XML: XML output - * + * * The output flags are: * - NFEXP_O_LAYER: include layer 3 information in the output, this is * *only* required by NFEXP_O_DEFAULT. - * + * * On error, -1 is returned and errno is set appropiately. Otherwise, * 0 is returned. */ @@ -649,3 +699,7 @@ int nfexp_snprintf(char *buf, return __snprintf_expect(buf, size, exp, msg_type, out_type, flags); } + +/** + * @} + */ diff --git a/src/main.c b/src/main.c index 87f1ae3..6da4198 100644 --- a/src/main.c +++ b/src/main.c @@ -58,6 +58,20 @@ out_free: return NULL; } +/** + * \defgroup LibrarySetup Library setup + * @{ + */ + + +/** + * nfct_open - open a ctnetlink handler + * \param subsys_id can be NFNL_SUBSYS_CTNETLINK or NFNL_SUBSYS_CTNETLINK_EXP + * \param subscriptions ctnetlink groups to subscribe to events + * + * This function returns a handler to send commands to and receive replies from + * kernel-space. On error, NULL is returned and errno is explicitly set. + */ struct nfct_handle *nfct_open(u_int8_t subsys_id, unsigned subscriptions) { struct nfnl_handle *nfnlh = nfnl_open(); @@ -73,6 +87,12 @@ struct nfct_handle *nfct_open(u_int8_t subsys_id, unsigned subscriptions) return nfcth; } +/** + * nfct_close - close a ctnetlink handler + * \param cth handler obtained via nfct_open() + * + * This function returns -1 on error and errno is explicitly set. + */ int nfct_close(struct nfct_handle *cth) { int err; @@ -103,6 +123,10 @@ int nfct_close(struct nfct_handle *cth) return err; } +/** + * nfct_fd - get the Netlink file descriptor of one existing ctnetlink handler + * \param cth handler obtained via nfct_open() + */ int nfct_fd(struct nfct_handle *cth) { return nfnl_fd(cth->nfnlh); @@ -112,3 +136,7 @@ const struct nfnl_handle *nfct_nfnlh(struct nfct_handle *cth) { return cth->nfnlh; } + +/** + * @} + */ -- cgit v1.2.3