libnl 2.0

/tmp/buildd/libnl2-2.0/lib/doc.c

00001 /*
00002  * lib/doc.c            Documentation Purpose
00003  *
00004  *      This library is free software; you can redistribute it and/or
00005  *      modify it under the terms of the GNU Lesser General Public
00006  *      License as published by the Free Software Foundation version 2.1
00007  *      of the License.
00008  *
00009  * Copyright (c) 2003-2008 Thomas Graf <tgraf@suug.ch>
00010  */
00011 
00012 /**
00013  * @mainpage
00014  *
00015  * @section intro Introduction
00016  *
00017  * libnl is a set of libraries to deal with the netlink protocol and some
00018  * of the high level protocols implemented on top of it. Its goal is to
00019  * simplify netlink protocol usage and to create an abstraction layer using
00020  * object based interfaces for various netlink based subsystems.The library
00021  * was developed and tested on the 2.6.x kernel releases but it may work with
00022  * older kernel series.
00023  *
00024  * @section toc Table of Contents
00025  *
00026  * - \subpage core_doc
00027  * - \subpage route_doc
00028  * - \subpage genl_doc
00029  * - \subpage nf_doc
00030  *
00031  * @section remarks Remarks
00032  *
00033  * @subsection cache_alloc Allocation of Caches
00034  *
00035  * Almost all subsystem provide a function to allocate a new cache
00036  * of some form. The function usually looks like this:
00037  * @code
00038  * struct nl_cache *<object name>_alloc_cache(struct nl_sock *sk);
00039  * @endcode
00040  *
00041  * These functions allocate a new cache for the own object type,
00042  * initializes it properly and updates it to represent the current
00043  * state of their master, e.g. a link cache would include all
00044  * links currently configured in the kernel.
00045  *
00046  * Some of the allocation functions may take additional arguments
00047  * to further specify what will be part of the cache.
00048  *
00049  * All such functions return a newly allocated cache or NULL
00050  * in case of an error.
00051  *
00052  * @subsection addr Setting of Addresses
00053  * @code
00054  * int <object name>_set_addr(struct nl_object *, struct nl_addr *)
00055  * @endcode
00056  *
00057  * All attribute functions avaiable for assigning addresses to objects
00058  * take a struct nl_addr argument. The provided address object is
00059  * validated against the address family of the object if known already.
00060  * The assignment fails if the address families mismatch. In case the
00061  * address family has not been specified yet, the address family of
00062  * the new address is elected to be the new requirement.
00063  *
00064  * The function will acquire a new reference on the address object
00065  * before assignment, the caller is NOT responsible for this.
00066  *
00067  * All functions return 0 on success or a negative error code.
00068  *
00069  * @subsection flags Flags to Character StringTranslations
00070  * All functions converting a set of flags to a character string follow
00071  * the same principles, therefore, the following information applies
00072  * to all functions convertings flags to a character string and vice versa.
00073  *
00074  * @subsubsection flags2str Flags to Character String
00075  * @code
00076  * char *<object name>_flags2str(int flags, char *buf, size_t len)
00077  * @endcode
00078  * @arg flags           Flags.
00079  * @arg buf             Destination buffer.
00080  * @arg len             Buffer length.
00081  *
00082  * Converts the specified flags to a character string separated by
00083  * commas and stores it in the specified destination buffer.
00084  *
00085  * @return The destination buffer
00086  *
00087  * @subsubsection str2flags Character String to Flags
00088  * @code
00089  * int <object name>_str2flags(const char *name)
00090  * @endcode
00091  * @arg name            Name of flag.
00092  *
00093  * Converts the provided character string specifying a flag
00094  * to the corresponding numeric value.
00095  *
00096  * @return Link flag or a negative value if none was found.
00097  *
00098  * @subsubsection type2str Type to Character String
00099  * @code
00100  * char *<object name>_<type>2str(int type, char *buf, size_t len)
00101  * @endcode
00102  * @arg type            Type as numeric value
00103  * @arg buf             Destination buffer.
00104  * @arg len             Buffer length.
00105  *
00106  * Converts an identifier (type) to a character string and stores
00107  * it in the specified destination buffer.
00108  *
00109  * @return The destination buffer or the type encoded in hexidecimal
00110  *         form if the identifier is unknown.
00111  *
00112  * @subsubsection str2type Character String to Type
00113  * @code
00114  * int <object name>_str2<type>(const char *name)
00115  * @endcode
00116  * @arg name            Name of identifier (type).
00117  *
00118  * Converts the provided character string specifying a identifier
00119  * to the corresponding numeric value.
00120  *
00121  * @return Identifier as numeric value or a negative value if none was found.
00122  *
00123  * @page core_doc Core Library (-lnl)
00124  * 
00125  * @section core_intro Introduction
00126  *
00127  * The core library contains the fundamentals required to communicate over
00128  * netlink sockets. It deals with connecting and unconnecting of sockets,
00129  * sending and receiving of data, provides a customizeable receiving state
00130  * machine, and provides a abstract data type framework which eases the
00131  * implementation of object based netlink protocols where objects are added,
00132  * removed, or modified with the help of netlink messages.
00133  *
00134  * @section core_toc Table of Contents
00135  * 
00136  * - \ref proto_fund
00137  * - \ref sk_doc
00138  * - \ref rxtx_doc
00139  * - \ref cb_doc
00140  *
00141  * @section proto_fund Netlink Protocol Fundamentals
00142  *
00143  * The netlink protocol is a socket based IPC mechanism used for communication
00144  * between userspace processes and the kernel. The netlink protocol uses the
00145  * \c AF_NETLINK address family and defines a protocol type for each subsystem
00146  * protocol (e.g. NETLINK_ROUTE, NETLINK_NETFILTER, etc). Its addressing
00147  * schema is based on a 32 bit port number, formerly referred to as PID, which
00148  * uniquely identifies each peer.
00149  *
00150  * The netlink protocol is based on messages each limited to the size of a
00151  * memory page and consists of the netlink message header (struct nlmsghdr)
00152  * plus the payload attached to it. The payload can consist of arbitary data
00153  * but often contains a fixed sized family specifc header followed by a
00154  * stream of \ref attr_doc. The use of attributes dramatically increases
00155  * the flexibility of the protocol and allows for the protocol to be
00156  * extended while maintaining backwards compatibility.
00157  *
00158  * The netlink message header (struct nlmsghdr):
00159  * @code   
00160  * 0                   1                   2                   3
00161  * 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
00162  * +-------------------------------------------------------------+
00163  * |                          Length                             |
00164  * +------------------------------+------------------------------+
00165  * |            Type              |           Flags              |
00166  * +------------------------------+------------------------------+
00167  * |                      Sequence Number                        |
00168  * +-------------------------------------------------------------+
00169  * |                       Port (Address)                        |
00170  * +-------------------------------------------------------------+
00171  * @endcode
00172  *
00173  * Netlink differs between requests, notifications, and replies. Requests
00174  * are messages which have the \c NLM_F_REQUEST flag set and are meant to
00175  * request an action from the receiver. A request is typically sent from
00176  * a userspace process to the kernel. Every request should be assigned a
00177  * sequence number which should be incremented for each request sent on the
00178  * sending side. Depending on the nature of the request, the receiver may
00179  * reply to the request with regular netlink messages which should contain
00180  * the same sequence number as the request it relates to. Notifications are
00181  * of informal nature and don't expect a reply, therefore the sequence number
00182  * is typically set to 0. It should be noted that unlike in protocols such as
00183  * TCP there is no strict enforcment of the sequence number. The sole purpose
00184  * of sequence numbers is to assist a sender in relating replies to the
00185  * corresponding requests.
00186  *
00187  * @msc
00188  * A,B;
00189  * A=>B [label="GET (seq=1, NLM_F_REQUEST)"];
00190  * A<=B [label="PUT (seq=1)"];
00191  * ...;
00192  * A<=B [label="NOTIFY (seq=0)"];
00193  * @endmsc
00194  *
00195  * If the size of a reply exceeds the size of a memory page and thus exceeds
00196  * the maximum message size, the reply can be split into a series of multipart
00197  * messages. A multipart message has the \c flag NLM_F_MULTI set and the
00198  * receiver is expected to continue parsing the reply until the special
00199  * message type \c NLMSG_DONE is received.
00200  *
00201  * @msc
00202  * A,B;
00203  * A=>B [label="GET (seq=1, NLM_F_REQUEST)"];
00204  * A<=B [label="PUT (seq=1, NLM_F_MULTI)"];
00205  * ...;
00206  * A<=B [label="PUT (seq=1, NLM_F_MULTI)"];
00207  * A<=B [label="NLMSG_DONE (seq=1)"];
00208  * @endmsc
00209  *
00210  * Errors can be reported using the standard message type \c NLMSG_ERROR which
00211  * can carry an error code and the netlink mesage header of the request.
00212  * Error messages should set their sequence number to the sequence number
00213  * of the message which caused the error.
00214  *
00215  * @msc
00216  * A,B;
00217  * A=>B [label="GET (seq=1, NLM_F_REQUEST)"];
00218  * A<=B [label="NLMSG_ERROR code=EINVAL (seq=1)"];
00219  * @endmsc
00220  *
00221  * The \c NLMSG_ERROR message type is also used to send acknowledge messages.
00222  * An acknowledge message can be requested by setting the \c NLM_F_ACK flag
00223  * message except that the error code is set to 0.
00224  *
00225  * @msc
00226  * A,B;
00227  * A=>B [label="GET (seq=1, NLM_F_REQUEST | NLM_F_ACK)"];
00228  * A<=B [label="ACK (seq=1)"];
00229  * @endmsc
00230  *
00231  * @section sk_doc Dealing with Netlink Sockets
00232  *
00233  * In order to use the netlink protocol, a netlink socket is required. Each
00234  * socket defines a completely independent context for sending and receiving
00235  * of messages. The netlink socket and all its related attributes are
00236  * represented by struct nl_sock.
00237  *
00238  * @code
00239  * nl_socket_alloc()                      Allocate new socket structure.
00240  * nl_socket_free(s)                      Free socket structure.
00241  * @endcode
00242  *
00243  * @subsection local_port Local Port
00244  * The local port number uniquely identifies the socket and is used to
00245  * address it. A unique local port is generated automatically when the socket
00246  * is allocated. It will consist of the Process ID (22 bits) and a random
00247  * number (10 bits) to allow up to 1024 sockets per process.
00248  *
00249  * @code
00250  * nl_socket_get_local_port(sk)           Return the peer's port number.
00251  * nl_socket_set_local_port(sk, port)     Set the peer's port number.
00252  * @endcode
00253  *
00254  * @subsection peer_port Peer Port
00255  * A peer port can be assigned to the socket which will result in all unicast
00256  * messages sent over the socket to be addresses to the corresponding peer. If
00257  * no peer is specified, the kernel will try to automatically bind the socket
00258  * to a kernel side socket of the same netlink protocol family. It is common
00259  * practice not to bind the socket to a peer port as typically only one kernel
00260  * side socket exists per netlink protocol family.
00261  *
00262  * @code
00263  * nl_socket_get_peer_port(sk)            Return the local port number.
00264  * nl_socket_set_peer_port(sk, port)      Set the local port number.
00265  * @endcode
00266  *
00267  * @subsection sock_fd File Descriptor
00268  * The file descriptor of the socket(2).
00269  *
00270  * @code
00271  * nl_socket_get_fd(sk)                   Return file descriptor.
00272  * nl_socket_set_buffer_size(sk, rx, tx)  Set buffer size of socket.
00273  * nl_socket_set_nonblocking(sk)          Set socket to non-blocking state.
00274  * @endcode
00275  *
00276  * @subsection group_sub Group Subscriptions
00277  * Each socket can subscribe to multicast groups of the netlink protocol
00278  * family it is bound to. The socket will then receive a copy of each
00279  * message sent to any of the groups. Multicast groups are commonly used
00280  * to implement event notifications. Prior to kernel 2.6.14 the group
00281  * subscription was performed using a bitmask which limited the number of
00282  * groups per protocol family to 32. This outdated interface can still be
00283  * accessed via the function nl_join_groups even though it is not recommended
00284  * for new code. Starting with 2.6.14 a new method was introduced which
00285  * supports subscribing to an almost unlimited number of multicast groups.
00286  *
00287  * @code
00288  * nl_socket_add_membership(sk, group)    Become a member of a multicast group.
00289  * nl_socket_drop_membership(sk, group)   Drop multicast group membership.
00290  * nl_join_groups(sk, groupmask)          Join a multicast group (obsolete).
00291  * @endcode
00292  *
00293  * @subsection seq_num Sequence Numbers
00294  * The socket keeps track of the sequence numbers used. The library will
00295  * automatically verify the sequence number of messages received unless
00296  * the check was disabled using the function nl_socket_disable_seq_check().
00297  * When a message is sent using nl_send_auto_complete(), the sequence number
00298  * is automatically filled in, and replies will be verified correctly.
00299  *
00300  * @code
00301  * nl_socket_disable_seq_check(sk)        Disable checking of sequece numbers.
00302  * nl_socket_use_seq(sk)                  Use sequence number and bump to next.
00303  * @endcode
00304  *
00305  * @subsection sock_cb Callback Configuration
00306  * Every socket is associated a callback configuration which enables the
00307  * applications to hook into various internal functions and control the
00308  * receiving and sendings semantics. For more information, see section
00309  * \ref cb_doc.
00310  *
00311  * @code
00312  * nl_socket_alloc_cb(cb)                 Allocate socket based on callback set.
00313  * nl_socket_get_cb(sk)                   Return callback configuration.
00314  * nl_socket_set_cb(sk, cb)               Replace callback configuration.
00315  * nl_socket_modify_cb(sk, ...)           Modify a specific callback function.
00316  * @endcode
00317  *
00318  * @subsection sk_other Other Functions
00319  * @code
00320  * nl_socket_enable_auto_ack(sock)        Enable automatic request of ACK.
00321  * nl_socket_disable_auto_ack(sock)       Disable automatic request of ACK.
00322  * nl_socket_enable_msg_peek(sock)        Enable message peeking.
00323  * nl_socket_disable_msg_peek(sock)       Disable message peeking.
00324  * nl_socket_set_passcred(sk, state)      Enable/disable credential passing.
00325  * nl_socket_recv_pktinfo(sk, state)      Enable/disable packet information.
00326  * @endcode
00327  *
00328  * @section rxtx_doc Sending and Receiving of Data
00329  *
00330  * @subsection recv_semantisc Receiving Semantics
00331  * @code
00332  *          nl_recvmsgs_default(set)
00333  *                 | cb = nl_socket_get_cb(sk)
00334  *                 v
00335  *          nl_recvmsgs(sk, cb)
00336  *                 |           [Application provides nl_recvmsgs() replacement]
00337  *                 |- - - - - - - - - - - - - - - v
00338  *                 |                     cb->cb_recvmsgs_ow()
00339  *                 |
00340  *                 |               [Application provides nl_recv() replacement]
00341  * +-------------->|- - - - - - - - - - - - - - - v
00342  * |           nl_recv()                   cb->cb_recv_ow()
00343  * |  +----------->|<- - - - - - - - - - - - - - -+
00344  * |  |            v
00345  * |  |      Parse Message
00346  * |  |            |- - - - - - - - - - - - - - - v
00347  * |  |            |                         NL_CB_MSG_IN()
00348  * |  |            |<- - - - - - - - - - - - - - -+
00349  * |  |            |
00350  * |  |            |- - - - - - - - - - - - - - - v
00351  * |  |      Sequence Check                NL_CB_SEQ_CHECK()
00352  * |  |            |<- - - - - - - - - - - - - - -+
00353  * |  |            |
00354  * |  |            |- - - - - - - - - - - - - - - v  [ NLM_F_ACK is set ]
00355  * |  |            |                      NL_CB_SEND_ACK()
00356  * |  |            |<- - - - - - - - - - - - - - -+
00357  * |  |            |
00358  * |  |      +-----+------+--------------+----------------+--------------+
00359  * |  |      v            v              v                v              v
00360  * |  | Valid Message    ACK       NO-OP Message  End of Multipart     Error
00361  * |  |      |            |              |                |              |
00362  * |  |      v            v              v                v              v
00363  * |  |NL_CB_VALID()  NL_CB_ACK()  NL_CB_SKIPPED()  NL_CB_FINISH()  cb->cb_err()
00364  * |  |      |            |              |                |              |
00365  * |  |      +------------+--------------+----------------+              v
00366  * |  |                                  |                           (FAILURE)
00367  * |  |                                  |  [Callback returned NL_SKIP]
00368  * |  |  [More messages to be parsed]    |<-----------
00369  * |  +----------------------------------|
00370  * |                                     |
00371  * |         [is Multipart message]      |
00372  * +-------------------------------------|  [Callback returned NL_STOP]
00373  *                                       |<-----------
00374  *                                       v
00375  *                                   (SUCCESS)
00376  *
00377  *                          At any time:
00378  *                                Message Format Error
00379  *                                         |- - - - - - - - - - - - v
00380  *                                         v                  NL_CB_INVALID()
00381  *                                     (FAILURE)
00382  *
00383  *                                Message Overrun (Kernel Lost Data)
00384  *                                         |- - - - - - - - - - - - v
00385  *                                         v                  NL_CB_OVERRUN()
00386  *                                     (FAILURE)
00387  *
00388  *                                Callback returned negative error code
00389  *                                     (FAILURE)
00390  * @endcode
00391  *
00392  * @subsection send_semantics Sending Semantisc
00393  *
00394  * @code
00395  *     nl_send_auto_complete(sk, msg)
00396  *             | [Automatically completes netlink message header]
00397  *             | [(local port, sequence number)                 ]
00398  *             |
00399  *             |                   [Application provies nl_send() replacement]
00400  *             |- - - - - - - - - - - - - - - - - - - - v
00401  *             v                                 cb->cb_send_ow()
00402  *         nl_send(sk, msg)
00403  *             | [If available, add peer port and credentials]
00404  *             v
00405  *        nl_sendmsg(sk, msg, msghdr)
00406  *             |- - - - - - - - - - - - - - - - - - - - v
00407  *             |                                 NL_CB_MSG_OUT()
00408  *             |<- - - - - - - - - - - - - - - - - - - -+
00409  *             v
00410  *         sendmsg()
00411  * @endcode
00412  *
00413  * @section cb_doc Callback Configurations
00414  * Callbacks and overwriting capabilities are provided to control various
00415  * semantics of the library. All callback functions are packed together in
00416  * struct nl_cb which is attached to a netlink socket or passed on to 
00417  * the respective functions directly.
00418  *
00419  * @subsection cb_ret_doc Callback Return Values
00420  * Callback functions can control the flow of the calling layer by returning
00421  * appropriate error codes:
00422  * @code
00423  * Action ID        | Description
00424  * -----------------+-------------------------------------------------------
00425  * NL_OK            | Proceed with whatever comes next.
00426  * NL_SKIP          | Skip message currently being processed and continue
00427  *                  | with next message.
00428  * NL_STOP          | Stop parsing and discard all remaining messages in
00429  *                  | this set of messages.
00430  * @endcode
00431  *
00432  * All callbacks are optional and a default action is performed if no 
00433  * application specific implementation is provided:
00434  *
00435  * @code
00436  * Callback ID       | Default Return Value
00437  * ------------------+----------------------
00438  * NL_CB_VALID       | NL_OK
00439  * NL_CB_FINISH      | NL_STOP
00440  * NL_CB_OVERRUN     | NL_STOP
00441  * NL_CB_SKIPPED     | NL_SKIP
00442  * NL_CB_ACK         | NL_STOP
00443  * NL_CB_MSG_IN      | NL_OK
00444  * NL_CB_MSG_OUT     | NL_OK
00445  * NL_CB_INVALID     | NL_STOP
00446  * NL_CB_SEQ_CHECK   | NL_OK
00447  * NL_CB_SEND_ACK    | NL_OK
00448  *                   |
00449  * Error Callback    | NL_STOP
00450  * @endcode
00451  *
00452  * In order to simplify typical usages of the library, different sets of
00453  * default callback implementations exist:
00454  * @code
00455  * NL_CB_DEFAULT: No additional actions
00456  * NL_CB_VERBOSE: Automatically print warning and error messages to a file
00457  *                descriptor as appropriate. This is useful for CLI based
00458  *                applications.
00459  * NL_CB_DEBUG:   Print informal debugging information for each message
00460  *                received. This will result in every message beint sent or
00461  *                received to be printed to the screen in a decoded,
00462  *                human-readable format.
00463  * @endcode
00464  *
00465  * @par 1) Setting up a callback set
00466  * @code
00467  * // Allocate a callback set and initialize it to the verbose default set
00468  * struct nl_cb *cb = nl_cb_alloc(NL_CB_VERBOSE);
00469  *
00470  * // Modify the set to call my_func() for all valid messages
00471  * nl_cb_set(cb, NL_CB_VALID, NL_CB_CUSTOM, my_func, NULL);
00472  *
00473  * // Set the error message handler to the verbose default implementation
00474  * // and direct it to print all errors to the given file descriptor.
00475  * FILE *file = fopen(...);
00476  * nl_cb_err(cb, NL_CB_VERBOSE, NULL, file);
00477  * @endcode
00478  *
00479  * @page route_doc Routing Family
00480  *
00481  * @page genl_doc Generic Netlink Family
00482  *
00483  * @page nf_doc Netfilter Subsystem
00484  */