lib/doc.c

   1 /*
   2  * lib/doc.c            Documentation Purpose
   3  *
   4  *      This library is free software; you can redistribute it and/or
   5  *      modify it under the terms of the GNU Lesser General Public
   6  *      License as published by the Free Software Foundation version 2.1
   7  *      of the License.
   8  *
   9  * Copyright (c) 2003-2008 Thomas Graf <tgraf@suug.ch>
  10  */
  11
  12 /**
  13  * @mainpage
  14  *
  15  * @section intro Introduction
  16  *
  17  * libnl is a set of libraries to deal with the netlink protocol and some
  18  * of the high level protocols implemented on top of it. Its goal is to
  19  * simplify netlink protocol usage and to create an abstraction layer using
  20  * object based interfaces for various netlink based subsystems.The library
  21  * was developed and tested on the 2.6.x kernel releases but it may work with
  22  * older kernel series.
  23  *
  24  * @section toc Table of Contents
  25  *
  26  * - \subpage core_doc
  27  * - \subpage route_doc
  28  * - \subpage genl_doc
  29  * - \subpage nf_doc
  30  *
  31  * @section remarks Remarks
  32  *
  33  * @subsection cache_alloc Allocation of Caches
  34  *
  35  * Almost all subsystem provide a function to allocate a new cache
  36  * of some form. The function usually looks like this:
  37  * @code
  38  * struct nl_cache *<object name>_alloc_cache(struct nl_sock *sk);
  39  * @endcode
  40  *
  41  * These functions allocate a new cache for the own object type,
  42  * initializes it properly and updates it to represent the current
  43  * state of their master, e.g. a link cache would include all
  44  * links currently configured in the kernel.
  45  *
  46  * Some of the allocation functions may take additional arguments
  47  * to further specify what will be part of the cache.
  48  *
  49  * All such functions return a newly allocated cache or NULL
  50  * in case of an error.
  51  *
  52  * @subsection addr Setting of Addresses
  53  * @code
  54  * int <object name>_set_addr(struct nl_object *, struct nl_addr *)
  55  * @endcode
  56  *
  57  * All attribute functions avaiable for assigning addresses to objects
  58  * take a struct nl_addr argument. The provided address object is
  59  * validated against the address family of the object if known already.
  60  * The assignment fails if the address families mismatch. In case the
  61  * address family has not been specified yet, the address family of
  62  * the new address is elected to be the new requirement.
  63  *
  64  * The function will acquire a new reference on the address object
  65  * before assignment, the caller is NOT responsible for this.
  66  *
  67  * All functions return 0 on success or a negative error code.
  68  *
  69  * @subsection flags Flags to Character StringTranslations
  70  * All functions converting a set of flags to a character string follow
  71  * the same principles, therefore, the following information applies
  72  * to all functions convertings flags to a character string and vice versa.
  73  *
  74  * @subsubsection flags2str Flags to Character String
  75  * @code
  76  * char *<object name>_flags2str(int flags, char *buf, size_t len)
  77  * @endcode
  78  * @arg flags           Flags.
  79  * @arg buf             Destination buffer.
  80  * @arg len             Buffer length.
  81  *
  82  * Converts the specified flags to a character string separated by
  83  * commas and stores it in the specified destination buffer.
  84  *
  85  * @return The destination buffer
  86  *
  87  * @subsubsection str2flags Character String to Flags
  88  * @code
  89  * int <object name>_str2flags(const char *name)
  90  * @endcode
  91  * @arg name            Name of flag.
  92  *
  93  * Converts the provided character string specifying a flag
  94  * to the corresponding numeric value.
  95  *
  96  * @return Link flag or a negative value if none was found.
  97  *
  98  * @subsubsection type2str Type to Character String
  99  * @code
 100  * char *<object name>_<type>2str(int type, char *buf, size_t len)
 101  * @endcode
 102  * @arg type            Type as numeric value
 103  * @arg buf             Destination buffer.
 104  * @arg len             Buffer length.
 105  *
 106  * Converts an identifier (type) to a character string and stores
 107  * it in the specified destination buffer.
 108  *
 109  * @return The destination buffer or the type encoded in hexidecimal
 110  *         form if the identifier is unknown.
 111  *
 112  * @subsubsection str2type Character String to Type
 113  * @code
 114  * int <object name>_str2<type>(const char *name)
 115  * @endcode
 116  * @arg name            Name of identifier (type).
 117  *
 118  * Converts the provided character string specifying a identifier
 119  * to the corresponding numeric value.
 120  *
 121  * @return Identifier as numeric value or a negative value if none was found.
 122  *
 123  * @page core_doc Core Library (-lnl)
 124  *
 125  * @section core_intro Introduction
 126  *
 127  * The core library contains the fundamentals required to communicate over
 128  * netlink sockets. It deals with connecting and unconnecting of sockets,
 129  * sending and receiving of data, provides a customizeable receiving state
 130  * machine, and provides a abstract data type framework which eases the
 131  * implementation of object based netlink protocols where objects are added,
 132  * removed, or modified with the help of netlink messages.
 133  *
 134  * @section core_toc Table of Contents
 135  *
 136  * - \ref proto_fund
 137  * - \ref sk_doc
 138  * - \ref rxtx_doc
 139  * - \ref cb_doc
 140  *
 141  * @section proto_fund Netlink Protocol Fundamentals
 142  *
 143  * The netlink protocol is a socket based IPC mechanism used for communication
 144  * between userspace processes and the kernel. The netlink protocol uses the
 145  * \c AF_NETLINK address family and defines a protocol type for each subsystem
 146  * protocol (e.g. NETLINK_ROUTE, NETLINK_NETFILTER, etc). Its addressing
 147  * schema is based on a 32 bit port number, formerly referred to as PID, which
 148  * uniquely identifies each peer.
 149  *
 150  * The netlink protocol is based on messages each limited to the size of a
 151  * memory page and consists of the netlink message header (struct nlmsghdr)
 152  * plus the payload attached to it. The payload can consist of arbitary data
 153  * but often contains a fixed sized family specifc header followed by a
 154  * stream of \ref attr_doc. The use of attributes dramatically increases
 155  * the flexibility of the protocol and allows for the protocol to be
 156  * extended while maintaining backwards compatibility.
 157  *
 158  * The netlink message header (struct nlmsghdr):
 159  * @code
 160  * 0                   1                   2                   3
 161  * 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
 162  * +-------------------------------------------------------------+
 163  * |                          Length                             |
 164  * +------------------------------+------------------------------+
 165  * |            Type              |           Flags              |
 166  * +------------------------------+------------------------------+
 167  * |                      Sequence Number                        |
 168  * +-------------------------------------------------------------+
 169  * |                       Port (Address)                        |
 170  * +-------------------------------------------------------------+
 171  * @endcode
 172  *
 173  * Netlink differs between requests, notifications, and replies. Requests
 174  * are messages which have the \c NLM_F_REQUEST flag set and are meant to
 175  * request an action from the receiver. A request is typically sent from
 176  * a userspace process to the kernel. Every request should be assigned a
 177  * sequence number which should be incremented for each request sent on the
 178  * sending side. Depending on the nature of the request, the receiver may
 179  * reply to the request with regular netlink messages which should contain
 180  * the same sequence number as the request it relates to. Notifications are
 181  * of informal nature and don't expect a reply, therefore the sequence number
 182  * is typically set to 0. It should be noted that unlike in protocols such as
 183  * TCP there is no strict enforcment of the sequence number. The sole purpose
 184  * of sequence numbers is to assist a sender in relating replies to the
 185  * corresponding requests.
 186  *
 187  * @msc
 188  * A,B;
 189  * A=>B [label="GET (seq=1, NLM_F_REQUEST)"];
 190  * A<=B [label="PUT (seq=1)"];
 191  * ...;
 192  * A<=B [label="NOTIFY (seq=0)"];
 193  * @endmsc
 194  *
 195  * If the size of a reply exceeds the size of a memory page and thus exceeds
 196  * the maximum message size, the reply can be split into a series of multipart
 197  * messages. A multipart message has the \c flag NLM_F_MULTI set and the
 198  * receiver is expected to continue parsing the reply until the special
 199  * message type \c NLMSG_DONE is received.
 200  *
 201  * @msc
 202  * A,B;
 203  * A=>B [label="GET (seq=1, NLM_F_REQUEST)"];
 204  * A<=B [label="PUT (seq=1, NLM_F_MULTI)"];
 205  * ...;
 206  * A<=B [label="PUT (seq=1, NLM_F_MULTI)"];
 207  * A<=B [label="NLMSG_DONE (seq=1)"];
 208  * @endmsc
 209  *
 210  * Errors can be reported using the standard message type \c NLMSG_ERROR which
 211  * can carry an error code and the netlink mesage header of the request.
 212  * Error messages should set their sequence number to the sequence number
 213  * of the message which caused the error.
 214  *
 215  * @msc
 216  * A,B;
 217  * A=>B [label="GET (seq=1, NLM_F_REQUEST)"];
 218  * A<=B [label="NLMSG_ERROR code=EINVAL (seq=1)"];
 219  * @endmsc
 220  *
 221  * The \c NLMSG_ERROR message type is also used to send acknowledge messages.
 222  * An acknowledge message can be requested by setting the \c NLM_F_ACK flag
 223  * message except that the error code is set to 0.
 224  *
 225  * @msc
 226  * A,B;
 227  * A=>B [label="GET (seq=1, NLM_F_REQUEST | NLM_F_ACK)"];
 228  * A<=B [label="ACK (seq=1)"];
 229  * @endmsc
 230  *
 231  * @section sk_doc Dealing with Netlink Sockets
 232  *
 233  * In order to use the netlink protocol, a netlink socket is required. Each
 234  * socket defines a completely independent context for sending and receiving
 235  * of messages. The netlink socket and all its related attributes are
 236  * represented by struct nl_sock.
 237  *
 238  * @code
 239  * nl_socket_alloc()                      Allocate new socket structure.
 240  * nl_socket_free(s)                      Free socket structure.
 241  * @endcode
 242  *
 243  * @subsection local_port Local Port
 244  * The local port number uniquely identifies the socket and is used to
 245  * address it. A unique local port is generated automatically when the socket
 246  * is allocated. It will consist of the Process ID (22 bits) and a random
 247  * number (10 bits) to allow up to 1024 sockets per process.
 248  *
 249  * @code
 250  * nl_socket_get_local_port(sk)           Return the peer's port number.
 251  * nl_socket_set_local_port(sk, port)     Set the peer's port number.
 252  * @endcode
 253  *
 254  * @subsection peer_port Peer Port
 255  * A peer port can be assigned to the socket which will result in all unicast
 256  * messages sent over the socket to be addresses to the corresponding peer. If
 257  * no peer is specified, the kernel will try to automatically bind the socket
 258  * to a kernel side socket of the same netlink protocol family. It is common
 259  * practice not to bind the socket to a peer port as typically only one kernel
 260  * side socket exists per netlink protocol family.
 261  *
 262  * @code
 263  * nl_socket_get_peer_port(sk)            Return the local port number.
 264  * nl_socket_set_peer_port(sk, port)      Set the local port number.
 265  * @endcode
 266  *
 267  * @subsection sock_fd File Descriptor
 268  * The file descriptor of the socket(2).
 269  *
 270  * @code
 271  * nl_socket_get_fd(sk)                   Return file descriptor.
 272  * nl_socket_set_buffer_size(sk, rx, tx)  Set buffer size of socket.
 273  * nl_socket_set_nonblocking(sk)          Set socket to non-blocking state.
 274  * @endcode
 275  *
 276  * @subsection group_sub Group Subscriptions
 277  * Each socket can subscribe to multicast groups of the netlink protocol
 278  * family it is bound to. The socket will then receive a copy of each
 279  * message sent to any of the groups. Multicast groups are commonly used
 280  * to implement event notifications. Prior to kernel 2.6.14 the group
 281  * subscription was performed using a bitmask which limited the number of
 282  * groups per protocol family to 32. This outdated interface can still be
 283  * accessed via the function nl_join_groups even though it is not recommended
 284  * for new code. Starting with 2.6.14 a new method was introduced which
 285  * supports subscribing to an almost unlimited number of multicast groups.
 286  *
 287  * @code
 288  * nl_socket_add_membership(sk, group)    Become a member of a multicast group.
 289  * nl_socket_drop_membership(sk, group)   Drop multicast group membership.
 290  * nl_join_groups(sk, groupmask)          Join a multicast group (obsolete).
 291  * @endcode
 292  *
 293  * @subsection seq_num Sequence Numbers
 294  * The socket keeps track of the sequence numbers used. The library will
 295  * automatically verify the sequence number of messages received unless
 296  * the check was disabled using the function nl_socket_disable_seq_check().
 297  * When a message is sent using nl_send_auto_complete(), the sequence number
 298  * is automatically filled in, and replies will be verified correctly.
 299  *
 300  * @code
 301  * nl_socket_disable_seq_check(sk)        Disable checking of sequece numbers.
 302  * nl_socket_use_seq(sk)                  Use sequence number and bump to next.
 303  * @endcode
 304  *
 305  * @subsection sock_cb Callback Configuration
 306  * Every socket is associated a callback configuration which enables the
 307  * applications to hook into various internal functions and control the
 308  * receiving and sendings semantics. For more information, see section
 309  * \ref cb_doc.
 310  *
 311  * @code
 312  * nl_socket_alloc_cb(cb)                 Allocate socket based on callback set.
 313  * nl_socket_get_cb(sk)                   Return callback configuration.
 314  * nl_socket_set_cb(sk, cb)               Replace callback configuration.
 315  * nl_socket_modify_cb(sk, ...)           Modify a specific callback function.
 316  * @endcode
 317  *
 318  * @subsection sk_other Other Functions
 319  * @code
 320  * nl_socket_enable_auto_ack(sock)        Enable automatic request of ACK.
 321  * nl_socket_disable_auto_ack(sock)       Disable automatic request of ACK.
 322  * nl_socket_enable_msg_peek(sock)        Enable message peeking.
 323  * nl_socket_disable_msg_peek(sock)       Disable message peeking.
 324  * nl_socket_set_passcred(sk, state)      Enable/disable credential passing.
 325  * nl_socket_recv_pktinfo(sk, state)      Enable/disable packet information.
 326  * @endcode
 327  *
 328  * @section rxtx_doc Sending and Receiving of Data
 329  *
 330  * @subsection recv_semantisc Receiving Semantics
 331  * @code
 332  *          nl_recvmsgs_default(set)
 333  *                 | cb = nl_socket_get_cb(sk)
 334  *                 v
 335  *          nl_recvmsgs(sk, cb)
 336  *                 |           [Application provides nl_recvmsgs() replacement]
 337  *                 |- - - - - - - - - - - - - - - v
 338  *                 |                     cb->cb_recvmsgs_ow()
 339  *                 |
 340  *                 |               [Application provides nl_recv() replacement]
 341  * +-------------->|- - - - - - - - - - - - - - - v
 342  * |           nl_recv()                   cb->cb_recv_ow()
 343  * |  +----------->|<- - - - - - - - - - - - - - -+
 344  * |  |            v
 345  * |  |      Parse Message
 346  * |  |            |- - - - - - - - - - - - - - - v
 347  * |  |            |                         NL_CB_MSG_IN()
 348  * |  |            |<- - - - - - - - - - - - - - -+
 349  * |  |            |
 350  * |  |            |- - - - - - - - - - - - - - - v
 351  * |  |      Sequence Check                NL_CB_SEQ_CHECK()
 352  * |  |            |<- - - - - - - - - - - - - - -+
 353  * |  |            |
 354  * |  |            |- - - - - - - - - - - - - - - v  [ NLM_F_ACK is set ]
 355  * |  |            |                      NL_CB_SEND_ACK()
 356  * |  |            |<- - - - - - - - - - - - - - -+
 357  * |  |            |
 358  * |  |      +-----+------+--------------+----------------+--------------+
 359  * |  |      v            v              v                v              v
 360  * |  | Valid Message    ACK       NO-OP Message  End of Multipart     Error
 361  * |  |      |            |              |                |              |
 362  * |  |      v            v              v                v              v
 363  * |  |NL_CB_VALID()  NL_CB_ACK()  NL_CB_SKIPPED()  NL_CB_FINISH()  cb->cb_err()
 364  * |  |      |            |              |                |              |
 365  * |  |      +------------+--------------+----------------+              v
 366  * |  |                                  |                           (FAILURE)
 367  * |  |                                  |  [Callback returned NL_SKIP]
 368  * |  |  [More messages to be parsed]    |<-----------
 369  * |  +----------------------------------|
 370  * |                                     |
 371  * |         [is Multipart message]      |
 372  * +-------------------------------------|  [Callback returned NL_STOP]
 373  *                                       |<-----------
 374  *                                       v
 375  *                                   (SUCCESS)
 376  *
 377  *                          At any time:
 378  *                                Message Format Error
 379  *                                         |- - - - - - - - - - - - v
 380  *                                         v                  NL_CB_INVALID()
 381  *                                     (FAILURE)
 382  *
 383  *                                Message Overrun (Kernel Lost Data)
 384  *                                         |- - - - - - - - - - - - v
 385  *                                         v                  NL_CB_OVERRUN()
 386  *                                     (FAILURE)
 387  *
 388  *                                Callback returned negative error code
 389  *                                     (FAILURE)
 390  * @endcode
 391  *
 392  * @subsection send_semantics Sending Semantisc
 393  *
 394  * @code
 395  *     nl_send_auto_complete(sk, msg)
 396  *             | [Automatically completes netlink message header]
 397  *             | [(local port, sequence number)                 ]
 398  *             |
 399  *             |                   [Application provies nl_send() replacement]
 400  *             |- - - - - - - - - - - - - - - - - - - - v
 401  *             v                                 cb->cb_send_ow()
 402  *         nl_send(sk, msg)
 403  *             | [If available, add peer port and credentials]
 404  *             v
 405  *        nl_sendmsg(sk, msg, msghdr)
 406  *             |- - - - - - - - - - - - - - - - - - - - v
 407  *             |                                 NL_CB_MSG_OUT()
 408  *             |<- - - - - - - - - - - - - - - - - - - -+
 409  *             v
 410  *         sendmsg()
 411  * @endcode
 412  *
 413  * @section cb_doc Callback Configurations
 414  * Callbacks and overwriting capabilities are provided to control various
 415  * semantics of the library. All callback functions are packed together in
 416  * struct nl_cb which is attached to a netlink socket or passed on to
 417  * the respective functions directly.
 418  *
 419  * @subsection cb_ret_doc Callback Return Values
 420  * Callback functions can control the flow of the calling layer by returning
 421  * appropriate error codes:
 422  * @code
 423  * Action ID        | Description
 424  * -----------------+-------------------------------------------------------
 425  * NL_OK            | Proceed with whatever comes next.
 426  * NL_SKIP          | Skip message currently being processed and continue
 427  *                  | with next message.
 428  * NL_STOP          | Stop parsing and discard all remaining messages in
 429  *                  | this set of messages.
 430  * @endcode
 431  *
 432  * All callbacks are optional and a default action is performed if no
 433  * application specific implementation is provided:
 434  *
 435  * @code
 436  * Callback ID       | Default Return Value
 437  * ------------------+----------------------
 438  * NL_CB_VALID       | NL_OK
 439  * NL_CB_FINISH      | NL_STOP
 440  * NL_CB_OVERRUN     | NL_STOP
 441  * NL_CB_SKIPPED     | NL_SKIP
 442  * NL_CB_ACK         | NL_STOP
 443  * NL_CB_MSG_IN      | NL_OK
 444  * NL_CB_MSG_OUT     | NL_OK
 445  * NL_CB_INVALID     | NL_STOP
 446  * NL_CB_SEQ_CHECK   | NL_OK
 447  * NL_CB_SEND_ACK    | NL_OK
 448  *                   |
 449  * Error Callback    | NL_STOP
 450  * @endcode
 451  *
 452  * In order to simplify typical usages of the library, different sets of
 453  * default callback implementations exist:
 454  * @code
 455  * NL_CB_DEFAULT: No additional actions
 456  * NL_CB_VERBOSE: Automatically print warning and error messages to a file
 457  *                descriptor as appropriate. This is useful for CLI based
 458  *                applications.
 459  * NL_CB_DEBUG:   Print informal debugging information for each message
 460  *                received. This will result in every message beint sent or
 461  *                received to be printed to the screen in a decoded,
 462  *                human-readable format.
 463  * @endcode
 464  *
 465  * @par 1) Setting up a callback set
 466  * @code
 467  * // Allocate a callback set and initialize it to the verbose default set
 468  * struct nl_cb *cb = nl_cb_alloc(NL_CB_VERBOSE);
 469  *
 470  * // Modify the set to call my_func() for all valid messages
 471  * nl_cb_set(cb, NL_CB_VALID, NL_CB_CUSTOM, my_func, NULL);
 472  *
 473  * // Set the error message handler to the verbose default implementation
 474  * // and direct it to print all errors to the given file descriptor.
 475  * FILE *file = fopen(...);
 476  * nl_cb_err(cb, NL_CB_VERBOSE, NULL, file);
 477  * @endcode
 478  *
 479  * @page route_doc Routing Family
 480  *
 481  * @page genl_doc Generic Netlink Family
 482  *
 483  * @page nf_doc Netfilter Subsystem
 484  */