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

nl_recv: improve function documentation

Browse source
This commit is contained in:
Thomas Graf 2012-11-06 14:21:18 +01:00
parent 6d52ae6440
commit fb42f19e2e
1 changed files with 33 additions and 13 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

46
lib/nl.c
View file

@ -404,29 +404,49 @@ errout:
/** /**
* Receive data from netlink socket * Receive data from netlink socket
* @arg sk Netlink socket. * @arg sk Netlink socket (required)
* @arg nla Destination pointer for peer's netlink address. (required) * @arg nla Netlink socket structure to hold address of peer (required)
* @arg buf Destination pointer for message content. (required) * @arg buf Destination pointer for message content (required)
* @arg creds Destination pointer for credentials. (optional) * @arg creds Destination pointer for credentials (optional)
* *
* Receives a netlink message, allocates a buffer in \c *buf and * Receives data from a connected netlink socket using recvmsg() and returns
* stores the message content. The peer's netlink address is stored * the number of bytes read. The read data is stored in a newly allocated
* in \c *nla. The caller is responsible for freeing the buffer allocated * buffer that is assigned to \c *buf. The peer's netlink address will be
* in \c *buf if a positive value is returned. Interrupted system calls * stored in \c *nla.
* are handled by repeating the read. The input buffer size is determined *
* by peeking before the actual read is done. * This function blocks until data is available to be read unless the socket
* has been put into non-blocking mode using nl_socket_set_nonblocking() in
* which case this function will return immediately with a return value of 0.
* *
* The buffer size used when reading from the netlink socket and thus limiting * The buffer size used when reading from the netlink socket and thus limiting
* the maximum size of a netlink message that can be read defaults to the size * the maximum size of a netlink message that can be read defaults to the size
* of a memory page (getpagesize()). The buffer size can be modified on a per * of a memory page (getpagesize()). The buffer size can be modified on a per
* socket level using the function nl_socket_set_msg_buf_size(). * socket level using the function nl_socket_set_msg_buf_size().
* *
* A non-blocking sockets causes the function to return immediately with * If message peeking is enabled using nl_socket_enable_msg_peek() the size of
* a return value of 0 if no data is available. * the message to be read will be determined using the MSG_PEEK flag prior to
* performing the actual read. This leads to an additional recvmsg() call for
* every read operation which has performance implications and is not
* recommended for high throughput protocols.
* *
* An eventual interruption of the recvmsg() system call is automatically
* handled by retrying the operation.
*
* If receiving of credentials has been enabled using the function
* nl_socket_set_passcred(), this function will allocate a new struct ucred
* filled with the received credentials and assign it to \c *creds. The caller
* is responsible for freeing the buffer.
*
* @note The caller is responsible to free the returned data buffer and if
* enabled, the credentials buffer.
*
* @see nl_socket_set_nonblocking()
* @see nl_socket_set_msg_buf_size() * @see nl_socket_set_msg_buf_size()
* @see nl_socket_enable_msg_peek()
* @see nl_socket_set_passcred()
* *
* @return Number of octets read, 0 on EOF or a negative error code. * @return Number of bytes read, 0 on EOF, 0 on no data event (non-blocking
* mode), or a negative error code.
*/ */
int nl_recv(struct nl_sock *sk, struct sockaddr_nl *nla, int nl_recv(struct nl_sock *sk, struct sockaddr_nl *nla,
unsigned char **buf, struct ucred **creds) unsigned char **buf, struct ucred **creds)