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