summaryrefslogtreecommitdiffstats
path: root/lib
diff options
context:
space:
mode:
authorThomas Graf <tgraf@suug.ch>2010-11-19 01:25:37 (GMT)
committerThomas Graf <tgraf@suug.ch>2010-11-19 01:25:37 (GMT)
commit6545206187c97136d69c5a456257cafa104667bc (patch)
tree0da17b738942c485f57853e0c3400e4fba531c5a /lib
parent5a08c8ff4cf9573f307ef2843d2a44f1f0a14980 (diff)
downloadlibnl-6545206187c97136d69c5a456257cafa104667bc.zip
libnl-6545206187c97136d69c5a456257cafa104667bc.tar.gz
libnl-6545206187c97136d69c5a456257cafa104667bc.tar.bz2
Documentation updates
- moved documentation from lib/doc.c to doc/src/ - splitted pages into separate files - worked over core sections, explaining the receiving and sending behaviour in much more details including the the available mechanisms to customize the behaviour - updated the html stylesheet file for increased readability, probably needs some doxygen patching to achieve what I am looking for. - enabled call graphs, not expanded by default
Diffstat (limited to 'lib')
-rw-r--r--lib/doc.c487
1 files changed, 0 insertions, 487 deletions
diff --git a/lib/doc.c b/lib/doc.c
deleted file mode 100644
index 4272a59..0000000
--- a/lib/doc.c
+++ /dev/null
@@ -1,487 +0,0 @@
-/*
- * lib/doc.c Documentation Purpose
- *
- * This library is free software; you can redistribute it and/or
- * modify it under the terms of the GNU Lesser General Public
- * License as published by the Free Software Foundation version 2.1
- * of the License.
- *
- * Copyright (c) 2003-2008 Thomas Graf <tgraf@suug.ch>
- */
-
-/**
- * @mainpage
- *
- * @section intro Introduction
- *
- * libnl is a set of libraries to deal with the netlink protocol and some
- * of the high level protocols implemented on top of it. Its goal is to
- * simplify netlink protocol usage and to create an abstraction layer using
- * object based interfaces for various netlink based subsystems.The library
- * was developed and tested on the 2.6.x kernel releases but it may work with
- * older kernel series.
- *
- * @section toc Table of Contents
- *
- * - \subpage core_doc
- * - \subpage route_doc
- * - \subpage genl_doc
- * - \subpage nf_doc
- *
- * @section remarks Remarks
- *
- * @subsection cache_alloc Allocation of Caches
- *
- * Almost all subsystem provide a function to allocate a new cache
- * of some form. The function usually looks like this:
- * @code
- * struct nl_cache *<object name>_alloc_cache(struct nl_sock *sk);
- * @endcode
- *
- * These functions allocate a new cache for the own object type,
- * initializes it properly and updates it to represent the current
- * state of their master, e.g. a link cache would include all
- * links currently configured in the kernel.
- *
- * Some of the allocation functions may take additional arguments
- * to further specify what will be part of the cache.
- *
- * All such functions return a newly allocated cache or NULL
- * in case of an error.
- *
- * @subsection addr Setting of Addresses
- * @code
- * int <object name>_set_addr(struct nl_object *, struct nl_addr *)
- * @endcode
- *
- * All attribute functions avaiable for assigning addresses to objects
- * take a struct nl_addr argument. The provided address object is
- * validated against the address family of the object if known already.
- * The assignment fails if the address families mismatch. In case the
- * address family has not been specified yet, the address family of
- * the new address is elected to be the new requirement.
- *
- * The function will acquire a new reference on the address object
- * before assignment, the caller is NOT responsible for this.
- *
- * All functions return 0 on success or a negative error code.
- *
- * @subsection flags Flags to Character StringTranslations
- * All functions converting a set of flags to a character string follow
- * the same principles, therefore, the following information applies
- * to all functions convertings flags to a character string and vice versa.
- *
- * @subsubsection flags2str Flags to Character String
- * @code
- * char *<object name>_flags2str(int flags, char *buf, size_t len)
- * @endcode
- * @arg flags Flags.
- * @arg buf Destination buffer.
- * @arg len Buffer length.
- *
- * Converts the specified flags to a character string separated by
- * commas and stores it in the specified destination buffer.
- *
- * @return The destination buffer
- *
- * @subsubsection str2flags Character String to Flags
- * @code
- * int <object name>_str2flags(const char *name)
- * @endcode
- * @arg name Name of flag.
- *
- * Converts the provided character string specifying a flag
- * to the corresponding numeric value.
- *
- * @return Link flag or a negative value if none was found.
- *
- * @subsubsection type2str Type to Character String
- * @code
- * char *<object name>_<type>2str(int type, char *buf, size_t len)
- * @endcode
- * @arg type Type as numeric value
- * @arg buf Destination buffer.
- * @arg len Buffer length.
- *
- * Converts an identifier (type) to a character string and stores
- * it in the specified destination buffer.
- *
- * @return The destination buffer or the type encoded in hexidecimal
- * form if the identifier is unknown.
- *
- * @subsubsection str2type Character String to Type
- * @code
- * int <object name>_str2<type>(const char *name)
- * @endcode
- * @arg name Name of identifier (type).
- *
- * Converts the provided character string specifying a identifier
- * to the corresponding numeric value.
- *
- * @return Identifier as numeric value or a negative value if none was found.
- *
- * @page core_doc Core Library (-lnl)
- *
- * @section core_intro Introduction
- *
- * The core library contains the fundamentals required to communicate over
- * netlink sockets. It deals with connecting and unconnecting of sockets,
- * sending and receiving of data, provides a customizeable receiving state
- * machine, and provides a abstract data type framework which eases the
- * implementation of object based netlink protocols where objects are added,
- * removed, or modified with the help of netlink messages.
- *
- * @section core_toc Table of Contents
- *
- * - \ref proto_fund
- * - \ref sk_doc
- * - \ref rxtx_doc
- * - \ref cb_doc
- *
- * @section proto_fund Netlink Protocol Fundamentals
- *
- * The netlink protocol is a socket based IPC mechanism used for communication
- * between userspace processes and the kernel. The netlink protocol uses the
- * \c AF_NETLINK address family and defines a protocol type for each subsystem
- * protocol (e.g. NETLINK_ROUTE, NETLINK_NETFILTER, etc). Its addressing
- * schema is based on a 32 bit port number, formerly referred to as PID, which
- * uniquely identifies each peer.
- *
- * The netlink protocol is based on messages each limited to the size of a
- * memory page and consists of the netlink message header (struct nlmsghdr)
- * plus the payload attached to it. The payload can consist of arbitary data
- * but often contains a fixed sized family specifc header followed by a
- * stream of \ref attr_doc. The use of attributes dramatically increases
- * the flexibility of the protocol and allows for the protocol to be
- * extended while maintaining backwards compatibility.
- *
- * The netlink message header (struct nlmsghdr):
- * @code
- * 0 1 2 3
- * 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
- * +-------------------------------------------------------------+
- * | Length |
- * +------------------------------+------------------------------+
- * | Type | Flags |
- * +------------------------------+------------------------------+
- * | Sequence Number |
- * +-------------------------------------------------------------+
- * | Port (Address) |
- * +-------------------------------------------------------------+
- * @endcode
- *
- * Netlink differs between requests, notifications, and replies. Requests
- * are messages which have the \c NLM_F_REQUEST flag set and are meant to
- * request an action from the receiver. A request is typically sent from
- * a userspace process to the kernel. Every request should be assigned a
- * sequence number which should be incremented for each request sent on the
- * sending side. Depending on the nature of the request, the receiver may
- * reply to the request with regular netlink messages which should contain
- * the same sequence number as the request it relates to. Notifications are
- * of informal nature and don't expect a reply, therefore the sequence number
- * is typically set to 0. It should be noted that unlike in protocols such as
- * TCP there is no strict enforcment of the sequence number. The sole purpose
- * of sequence numbers is to assist a sender in relating replies to the
- * corresponding requests.
- *
- * @msc
- * A,B;
- * A=>B [label="GET (seq=1, NLM_F_REQUEST)"];
- * A<=B [label="PUT (seq=1)"];
- * ...;
- * A<=B [label="NOTIFY (seq=0)"];
- * @endmsc
- *
- * If the size of a reply exceeds the size of a memory page and thus exceeds
- * the maximum message size, the reply can be split into a series of multipart
- * messages. A multipart message has the \c flag NLM_F_MULTI set and the
- * receiver is expected to continue parsing the reply until the special
- * message type \c NLMSG_DONE is received.
- *
- * @msc
- * A,B;
- * A=>B [label="GET (seq=1, NLM_F_REQUEST)"];
- * A<=B [label="PUT (seq=1, NLM_F_MULTI)"];
- * ...;
- * A<=B [label="PUT (seq=1, NLM_F_MULTI)"];
- * A<=B [label="NLMSG_DONE (seq=1)"];
- * @endmsc
- *
- * Errors can be reported using the standard message type \c NLMSG_ERROR which
- * can carry an error code and the netlink mesage header of the request.
- * Error messages should set their sequence number to the sequence number
- * of the message which caused the error.
- *
- * @msc
- * A,B;
- * A=>B [label="GET (seq=1, NLM_F_REQUEST)"];
- * A<=B [label="NLMSG_ERROR code=EINVAL (seq=1)"];
- * @endmsc
- *
- * The \c NLMSG_ERROR message type is also used to send acknowledge messages.
- * An acknowledge message can be requested by setting the \c NLM_F_ACK flag
- * message except that the error code is set to 0.
- *
- * @msc
- * A,B;
- * A=>B [label="GET (seq=1, NLM_F_REQUEST | NLM_F_ACK)"];
- * A<=B [label="ACK (seq=1)"];
- * @endmsc
- *
- * @section sk_doc Dealing with Netlink Sockets
- *
- * In order to use the netlink protocol, a netlink socket is required. Each
- * socket defines a completely independent context for sending and receiving
- * of messages. The netlink socket and all its related attributes are
- * represented by struct nl_sock.
- *
- * @code
- * nl_socket_alloc() Allocate new socket structure.
- * nl_socket_free(s) Free socket structure.
- * @endcode
- *
- * @subsection local_port Local Port
- * The local port number uniquely identifies the socket and is used to
- * address it. A unique local port is generated automatically when the socket
- * is allocated. It will consist of the Process ID (22 bits) and a random
- * number (10 bits) to allow up to 1024 sockets per process.
- *
- * @code
- * nl_socket_get_local_port(sk) Return the peer's port number.
- * nl_socket_set_local_port(sk, port) Set the peer's port number.
- * @endcode
- *
- * @subsection peer_port Peer Port
- * A peer port can be assigned to the socket which will result in all unicast
- * messages sent over the socket to be addresses to the corresponding peer. If
- * no peer is specified, the kernel will try to automatically bind the socket
- * to a kernel side socket of the same netlink protocol family. It is common
- * practice not to bind the socket to a peer port as typically only one kernel
- * side socket exists per netlink protocol family.
- *
- * @code
- * nl_socket_get_peer_port(sk) Return the local port number.
- * nl_socket_set_peer_port(sk, port) Set the local port number.
- * @endcode
- *
- * @subsection sock_fd File Descriptor
- * The file descriptor of the socket(2).
- *
- * @code
- * nl_socket_get_fd(sk) Return file descriptor.
- * nl_socket_set_buffer_size(sk, rx, tx) Set buffer size of socket.
- * nl_socket_set_nonblocking(sk) Set socket to non-blocking state.
- * @endcode
- *
- * @subsection group_sub Group Subscriptions
- * Each socket can subscribe to multicast groups of the netlink protocol
- * family it is bound to. The socket will then receive a copy of each
- * message sent to any of the groups. Multicast groups are commonly used
- * to implement event notifications. Prior to kernel 2.6.14 the group
- * subscription was performed using a bitmask which limited the number of
- * groups per protocol family to 32. This outdated interface can still be
- * accessed via the function nl_join_groups even though it is not recommended
- * for new code. Starting with 2.6.14 a new method was introduced which
- * supports subscribing to an almost unlimited number of multicast groups.
- *
- * @code
- * nl_socket_add_membership(sk, group) Become a member of a multicast group.
- * nl_socket_drop_membership(sk, group) Drop multicast group membership.
- * nl_join_groups(sk, groupmask) Join a multicast group (obsolete).
- * @endcode
- *
- * @subsection seq_num Sequence Numbers
- * The socket keeps track of the sequence numbers used. The library will
- * automatically verify the sequence number of messages received unless
- * the check was disabled using the function nl_socket_disable_seq_check().
- * When a message is sent using nl_send_auto_complete(), the sequence number
- * is automatically filled in, and replies will be verified correctly.
- *
- * @code
- * nl_socket_disable_seq_check(sk) Disable checking of sequece numbers.
- * nl_socket_use_seq(sk) Use sequence number and bump to next.
- * @endcode
- *
- * @subsection sock_cb Callback Configuration
- * Every socket is associated a callback configuration which enables the
- * applications to hook into various internal functions and control the
- * receiving and sendings semantics. For more information, see section
- * \ref cb_doc.
- *
- * @code
- * nl_socket_alloc_cb(cb) Allocate socket based on callback set.
- * nl_socket_get_cb(sk) Return callback configuration.
- * nl_socket_set_cb(sk, cb) Replace callback configuration.
- * nl_socket_modify_cb(sk, ...) Modify a specific callback function.
- * @endcode
- *
- * @subsection sk_other Other Functions
- * @code
- * nl_socket_enable_auto_ack(sock) Enable automatic request of ACK.
- * nl_socket_disable_auto_ack(sock) Disable automatic request of ACK.
- * nl_socket_enable_msg_peek(sock) Enable message peeking.
- * nl_socket_disable_msg_peek(sock) Disable message peeking.
- * nl_socket_set_passcred(sk, state) Enable/disable credential passing.
- * nl_socket_recv_pktinfo(sk, state) Enable/disable packet information.
- * @endcode
- *
- * @section rxtx_doc Sending and Receiving of Data
- *
- * @subsection recv_semantisc Receiving Semantics
- * @code
- * nl_recvmsgs_default(set)
- * | cb = nl_socket_get_cb(sk)
- * v
- * nl_recvmsgs(sk, cb)
- * | [Application provides nl_recvmsgs() replacement]
- * |- - - - - - - - - - - - - - - v
- * | cb->cb_recvmsgs_ow()
- * |
- * | [Application provides nl_recv() replacement]
- * +-------------->|- - - - - - - - - - - - - - - v
- * | nl_recv() cb->cb_recv_ow()
- * | +----------->|<- - - - - - - - - - - - - - -+
- * | | v
- * | | Parse Message
- * | | |- - - - - - - - - - - - - - - v
- * | | | NL_CB_MSG_IN()
- * | | |<- - - - - - - - - - - - - - -+
- * | | |
- * | | |- - - - - - - - - - - - - - - v
- * | | Sequence Check NL_CB_SEQ_CHECK()
- * | | |<- - - - - - - - - - - - - - -+
- * | | |
- * | | |- - - - - - - - - - - - - - - v [ NLM_F_ACK is set ]
- * | | | NL_CB_SEND_ACK()
- * | | |<- - - - - - - - - - - - - - -+
- * | | |
- * | | +-----+------+--------------+----------------+--------------+
- * | | v v v v v
- * | | Valid Message ACK NO-OP Message End of Multipart Error
- * | | | | | | |
- * | | v v v v v
- * | |NL_CB_VALID() NL_CB_ACK() NL_CB_SKIPPED() NL_CB_FINISH() cb->cb_err()
- * | | | | | | |
- * | | +------------+--------------+----------------+ v
- * | | | (FAILURE)
- * | | | [Callback returned NL_SKIP]
- * | | [More messages to be parsed] |<-----------
- * | +----------------------------------|
- * | |
- * | [is Multipart message] |
- * +-------------------------------------| [Callback returned NL_STOP]
- * |<-----------
- * v
- * (SUCCESS)
- *
- * At any time:
- * Message Format Error
- * |- - - - - - - - - - - - v
- * v NL_CB_INVALID()
- * (FAILURE)
- *
- * Message Overrun (Kernel Lost Data)
- * |- - - - - - - - - - - - v
- * v NL_CB_OVERRUN()
- * (FAILURE)
- *
- * Callback returned negative error code
- * (FAILURE)
- * @endcode
- *
- * @subsection send_semantics Sending Semantisc
- *
- * @code
- * nl_send_auto_complete(sk, msg)
- * | [Automatically completes netlink message header]
- * | [(local port, sequence number) ]
- * |
- * | [Application provies nl_send() replacement]
- * |- - - - - - - - - - - - - - - - - - - - v
- * v cb->cb_send_ow()
- * nl_send(sk, msg)
- * |
- * v
- * nl_send_iovec()
- * | [If available, add peer port and credentials]
- * v
- * nl_sendmsg(sk, msg, msghdr)
- * |- - - - - - - - - - - - - - - - - - - - v
- * | NL_CB_MSG_OUT()
- * |<- - - - - - - - - - - - - - - - - - - -+
- * v
- * sendmsg()
- * @endcode
- *
- * @section cb_doc Callback Configurations
- * Callbacks and overwriting capabilities are provided to control various
- * semantics of the library. All callback functions are packed together in
- * struct nl_cb which is attached to a netlink socket or passed on to
- * the respective functions directly.
- *
- * @subsection cb_ret_doc Callback Return Values
- * Callback functions can control the flow of the calling layer by returning
- * appropriate error codes:
- * @code
- * Action ID | Description
- * -----------------+-------------------------------------------------------
- * NL_OK | Proceed with whatever comes next.
- * NL_SKIP | Skip message currently being processed and continue
- * | with next message.
- * NL_STOP | Stop parsing and discard all remaining messages in
- * | this set of messages.
- * @endcode
- *
- * All callbacks are optional and a default action is performed if no
- * application specific implementation is provided:
- *
- * @code
- * Callback ID | Default Return Value
- * ------------------+----------------------
- * NL_CB_VALID | NL_OK
- * NL_CB_FINISH | NL_STOP
- * NL_CB_OVERRUN | NL_STOP
- * NL_CB_SKIPPED | NL_SKIP
- * NL_CB_ACK | NL_STOP
- * NL_CB_MSG_IN | NL_OK
- * NL_CB_MSG_OUT | NL_OK
- * NL_CB_INVALID | NL_STOP
- * NL_CB_SEQ_CHECK | NL_OK
- * NL_CB_SEND_ACK | NL_OK
- * |
- * Error Callback | NL_STOP
- * @endcode
- *
- * In order to simplify typical usages of the library, different sets of
- * default callback implementations exist:
- * @code
- * NL_CB_DEFAULT: No additional actions
- * NL_CB_VERBOSE: Automatically print warning and error messages to a file
- * descriptor as appropriate. This is useful for CLI based
- * applications.
- * NL_CB_DEBUG: Print informal debugging information for each message
- * received. This will result in every message beint sent or
- * received to be printed to the screen in a decoded,
- * human-readable format.
- * @endcode
- *
- * @par 1) Setting up a callback set
- * @code
- * // Allocate a callback set and initialize it to the verbose default set
- * struct nl_cb *cb = nl_cb_alloc(NL_CB_VERBOSE);
- *
- * // Modify the set to call my_func() for all valid messages
- * nl_cb_set(cb, NL_CB_VALID, NL_CB_CUSTOM, my_func, NULL);
- *
- * // Set the error message handler to the verbose default implementation
- * // and direct it to print all errors to the given file descriptor.
- * FILE *file = fopen(...);
- * nl_cb_err(cb, NL_CB_VERBOSE, NULL, file);
- * @endcode
- *
- * @page route_doc Routing Family
- *
- * @page genl_doc Generic Netlink Family
- *
- * @page nf_doc Netfilter Subsystem
- */