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