484 lines
20 KiB
C
484 lines
20 KiB
C
/*
|
|
* 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
|
|
*/
|