stv0g/libnl
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

nl: improve API doc of transmit functions

Browse source 
Signed-off-by: Thomas Graf <tgraf@redhat.com>
This commit is contained in:
Thomas Graf 2012-11-08 01:29:12 +01:00
parent a721c1d445
commit b132ee7e27
4 changed files with 164 additions and 53 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
doc/Doxyfile.in
View file

@ -198,7 +198,9 @@ ALIASES = arg=\param \
"ref_core{2}=\ref_asciidoc{core,\1,\2 (Netlink Core Library Development Guide)}" \
"ref_route{2}=\ref_asciidoc{route,\1,\2 (Netlink Routing Development Guide)}" \
"core_doc{2}=\ref_core{\1,\2}" \
"route_doc{2}=\ref_route{\1,\2}"
"route_doc{2}=\ref_route{\1,\2}" \
"callback=\par Callback Invocation:\n" \
"lowlevel=\copydoc low_level_api"
# This tag can be used to specify a number of word-keyword mappings (TCL only).
# A mapping has the form "name=value". For example adding

1
doc/DoxygenLayout.xml
View file

@ -18,7 +18,6 @@
<tab type="files" visible="yes" title="" intro=""/>
<tab type="globals" visible="yes" title="" intro=""/>
</tab>
<tab type="dirs" visible="no" title="" intro=""/>
<tab type="examples" visible="yes" title="" intro=""/>
</navindex>

7
doc/src/hidden.c
View file

@ -32,4 +32,11 @@
accessor function is provided solely for the purpose of creating
objects for comparison and filtering.
\page low_level_api Low Level API
\note This is a low level API function. A high level function implementing
the same functionality with a simplified usage pattern exists. This
function is available as an alternative if the default library
behaviour is not desirable.
*/

205
lib/nl.c
View file

@ -158,12 +158,12 @@ void nl_close(struct nl_sock *sk)
*/
/**
* Transmit raw data over netlink socket.
* Transmit raw data over Netlink socket.
* @arg sk Netlink socket (required)
* @arg buf Buffer carrying data to send (required)
* @arg size Size of buffer (required)
*
* Transmits "raw" data over the specified netlink socket. Unlike the other
* Transmits "raw" data over the specified Netlink socket. Unlike the other
* transmit functions it does not modify the data in any way. It directly
* passes the buffer \c buf of \c size to sendto().
*
@ -199,17 +199,49 @@ int nl_sendto(struct nl_sock *sk, void *buf, size_t size)
}
/**
* Send netlink message with control over sendmsg() message header.
* @arg sk Netlink socket.
* @arg msg Netlink message to be sent.
* @arg hdr Sendmsg() message header.
* @return Number of characters sent on sucess or a negative error code.
* Transmit Netlink message using sendmsg()
* @arg sk Netlink socket (required)
* @arg msg Netlink message to be sent (required)
* @arg hdr sendmsg() message header (required)
*
* Transmits the message specified in \c hdr over the Netlink socket using the
* sendmsg() system call.
*
* @attention
* The `msg` argument will *not* be used to derive the message payload that
* is being sent out. The `msg` argument is *only* passed on to the
* `NL_CB_MSG_OUT` callback. The caller is responsible to initialize the
* `hdr` struct properly and have it point to the message payload and
* socket address.
*
* @note
* This function uses `nlmsg_set_src()` to modify the `msg` argument prior to
* invoking the `NL_CB_MSG_OUT` callback to provide the local port number.
*
* @callback This function triggers the `NL_CB_MSG_OUT` callback.
*
* @attention
* Think twice before using this function. It provides a low level access to
* the Netlink socket. Among other limitations, it does not add credentials
* even if enabled or respect the destination address specified in the `msg`
* object.
*
* @see nl_socket_set_local_port()
* @see nl_send_auto()
* @see nl_send_iovec()
*
* @return Number of bytes sent on success or a negative error code.
*
* @lowlevel
*/
int nl_sendmsg(struct nl_sock *sk, struct nl_msg *msg, struct msghdr *hdr)
{
struct nl_cb *cb;
int ret;
if (sk->s_fd < 0)
return -NLE_BAD_SOCK;
nlmsg_set_src(msg, &sk->s_local);
cb = sk->s_cb;
@ -227,13 +259,23 @@ int nl_sendmsg(struct nl_sock *sk, struct nl_msg *msg, struct msghdr *hdr)
/**
* Send netlink message.
* @arg sk Netlink socket.
* @arg msg Netlink message to be sent.
* @arg iov iovec to be sent.
* @arg iovlen number of struct iovec to be sent.
* @see nl_sendmsg()
* @return Number of characters sent on success or a negative error code.
* Transmit Netlink message (taking IO vector)
* @arg sk Netlink socket (required)
* @arg msg Netlink message to be sent (required)
* @arg iov IO vector to be sent (required)
* @arg iovlen Number of struct iovec to be sent (required)
*
* This function is identical to nl_send() except that instead of taking a
* `struct nl_msg` object it takes an IO vector. Please see the description
* of `nl_send()`.
*
* @callback This function triggers the `NL_CB_MSG_OUT` callback.
*
* @see nl_send()
*
* @return Number of bytes sent on success or a negative error code.
*
* @lowlevel
*/
int nl_send_iovec(struct nl_sock *sk, struct nl_msg *msg, struct iovec *iov, unsigned iovlen)
{
@ -272,14 +314,37 @@ int nl_send_iovec(struct nl_sock *sk, struct nl_msg *msg, struct iovec *iov, uns
return nl_sendmsg(sk, msg, &hdr);
}
/**
* Send netlink message.
* @arg sk Netlink socket.
* @arg msg Netlink message to be sent.
* @see nl_sendmsg()
* @return Number of characters sent on success or a negative error code.
* Transmit Netlink message
* @arg sk Netlink socket (required)
* @arg msg Netlink message (required)
*
* Transmits the Netlink message `msg` over the Netlink socket using the
* `sendmsg()` system call. This function is based on `nl_send_iovec()` but
* takes care of initializing a `struct iovec` based on the `msg` object.
*
* The message is addressed to the peer as specified in the socket by either
* the nl_socket_set_peer_port() or nl_socket_set_peer_groups() function.
* The peer address can be overwritten by specifying an address in the `msg`
* object using nlmsg_set_dst().
*
* If present in the `msg`, credentials set by the nlmsg_set_creds() function
* are added to the control buffer of the message.
*
* @callback This function triggers the `NL_CB_MSG_OUT` callback.
*
* @attention
* Unlike `nl_send_auto()`, this function does *not* finalize the message in
* terms of automatically adding needed flags or filling out port numbers.
*
* @see nl_send_auto()
* @see nl_send_iovec()
* @see nl_socket_set_peer_port()
* @see nl_socket_set_peer_groups()
* @see nlmsg_set_dst()
* @see nlmsg_set_creds()
*
* @return Number of bytes sent on success or a negative error code.
*/
int nl_send(struct nl_sock *sk, struct nl_msg *msg)
{
@ -291,6 +356,24 @@ int nl_send(struct nl_sock *sk, struct nl_msg *msg)
return nl_send_iovec(sk, msg, &iov, 1);
}
/**
* Finalize Netlink message
* @arg sk Netlink socket (required)
* @arg msg Netlink message (required)
*
* This function finalizes a Netlink message by completing the message with
* desirable flags and values depending on the socket configuration.
*
* - If not yet filled out, the source address of the message (`nlmsg_pid`)
* will be set to the local port number of the socket.
* - If not yet specified, the next available sequence number is assigned
* to the message (`nlmsg_seq`).
* - If not yet specified, the protocol field of the message will be set to
* the protocol field of the socket.
* - The `NLM_F_REQUEST` Netlink message flag will be set.
* - The `NLM_F_ACK` flag will be set if Auto-ACK mode is enabled on the
* socket.
*/
void nl_complete_msg(struct nl_sock *sk, struct nl_msg *msg)
{
struct nlmsghdr *nlh;
@ -311,25 +394,20 @@ void nl_complete_msg(struct nl_sock *sk, struct nl_msg *msg)
nlh->nlmsg_flags |= NLM_F_ACK;
}
void nl_auto_complete(struct nl_sock *sk, struct nl_msg *msg)
{
nl_complete_msg(sk, msg);
}
/**
* Automatically complete and send a netlink message
* @arg sk Netlink socket.
* @arg msg Netlink message to be sent.
* Finalize and transmit Netlink message
* @arg sk Netlink socket (required)
* @arg msg Netlink message (required)
*
* This function takes a netlink message and passes it on to
* nl_auto_complete() for completion.
* Finalizes the message by passing it to `nl_complete_msg()` and transmits it
* by passing it to `nl_send()`.
*
* Checks the netlink message \c nlh for completness and extends it
* as required before sending it out. Checked fields include pid,
* sequence nr, and flags.
* @callback This function triggers the `NL_CB_MSG_OUT` callback.
*
* @see nl_complete_msg()
* @see nl_send()
* @return Number of characters sent or a negative error code.
*
* @return Number of bytes sent or a negative error code.
*/
int nl_send_auto(struct nl_sock *sk, struct nl_msg *msg)
{
@ -343,27 +421,28 @@ int nl_send_auto(struct nl_sock *sk, struct nl_msg *msg)
return nl_send(sk, msg);
}
int nl_send_auto_complete(struct nl_sock *sk, struct nl_msg *msg)
{
return nl_send_auto(sk, msg);
}
/**
* Send netlink message and wait for response (sync request-response)
* @arg sk Netlink socket
* @arg msg Netlink message to be sent
* Finalize and transmit Netlink message and wait for ACK or error message
* @arg sk Netlink socket (required)
* @arg msg Netlink message (required)
*
* This function takes a netlink message and sends it using nl_send_auto().
* It will then wait for the response (ACK or error message) to be
* received. Threfore this function will block until the operation has
* been completed.
* Passes the `msg` to `nl_send_auto()` to finalize and transmit it. Frees the
* message and waits (sleeps) for the ACK or error message to be received.
*
* @note Disabling auto-ack (nl_socket_disable_auto_ack()) will cause
* this function to return immediately after sending. In this case,
* it is the responsibility of the caller to handle any eventual
* error messages returned.
* @attention
* Disabling Auto-ACK (nl_socket_disable_auto_ack()) will cause this function
* to return immediately after transmitting the message. However, the peer may
* still be returning an error message in response to the request. It is the
* responsibility of the caller to handle such messages.
*
* @callback This function triggers the `NL_CB_MSG_OUT` callback.
*
* @attention
* This function frees the `msg` object after transmitting it by calling
* `nlmsg_free()`.
*
* @see nl_send_auto().
* @see nl_wait_for_ack()
*
* @return 0 on success or a negative error code.
*/
@ -994,6 +1073,30 @@ errout:
return err;
}
/** @} */
/**
* @name Deprecated
* @{
*/
/**
* @deprecated Please use nl_complete_msg()
*/
void nl_auto_complete(struct nl_sock *sk, struct nl_msg *msg)
{
nl_complete_msg(sk, msg);
}
/**
* @deprecated Please use nl_send_auto()
*/
int nl_send_auto_complete(struct nl_sock *sk, struct nl_msg *msg)
{
return nl_send_auto(sk, msg);
}
/** @} */
/** @} */