mtcp_peek

NAME

mtcp_peek − Peek into the bytestream from a monitoring socket

SYNOPSIS

#include <mos_api.h>

ssize_t mtcp_peek(mctx_t mctx, int sockid, int side, char *buf, size_t len);

DESCRIPTION

mtcp_peek() can be used to peek up to len number of bytes from a monitoring socket via socket descriptor sockid into the buffer (unfragmented) starting at buf. It is the responsibility of the user to allocate memory for buf array.

For cases when the total number of buffered unread bytes in the socket are less than len, mtcp_peek() copies entire data to buf and returns the actual number of bytes that can be used by the application.

An mtcp_peek() call takes two additional argument named mctx , that represents the per-core mTCP context in an application (see mtcp_create_context() for details); and side that informs the stack whether it needs to peek the client (MOS_SIDE_CLI) or server (MOS_SIDE_SVR) side.

RETURN VALUE

On success, the number of bytes read is returned. It is not an error if this number is smaller than the number of bytes requested; this may happen when the socket has fewer number of bytes buffered at that moment. On all errors, -1 is returned and errno is set appropriately.

ERRORS

EACCES

The mctx argument is invalid.

EBADF

The socket descriptor sockid is invalid.

EINVAL

The buffer management of the monitoring socket with sockid was already disabled.

ENOTSOCK

The socket referred to by sockid has invalid type

ENOTCONN

Th socket referred to by sockid is in a TCP state that disallows read operations.

ENODATA

The socket referred to by sockid does not have any available bytes in its buffer for reading.

EPERM

The caller is not permitted to access this function.

NOTES

Since TCP flow control applies between end-hosts, the receive buffer managed by mOS can become full while new packets continue to arrive. Silent TCP ring buffer overwriting is undesirable since the application may not notice the buffer overflow. Instead, mOS raises an error event to explicitly notify the application about the buffer overflow. The application can either drain the buffer by reading the data (by calling mtcp_peek()) or enlarge the buffer (by calling mtcp_setsockopt()). Otherwise, the stack overwrites the buffer with the new data, and adjusts the internal peek pointer. To notify the application about the overwriting, mtcp_peek() fails right after overwriting. Subsequent function calls continue to read the data from the new position.

AUTHORS

mOS development team <mtcp-user@list.ndsl.kaist.edu>

SEE ALSO

mtcp_ppeek(), mtcp_socket(), mtcp_getsockopt()

COLOPHON

This page is part of mOS release 0.3 docs section. A description of the project, and information about reporting bugs, can be found at http://mos.kaist.edu/.