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