path: root/lib/doc.c

/*
 * 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)
 *             | [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
 */