mtcp_peek 3 2017-02-02 "Linux" "mOS Library Functions Manual"
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 except
"ENODATA", -1 is returned and
"errno" is set appropriately.
On
"ENODATA" error, if the buffer outrun was occured, it would return
"(-1) * (the number of bytes overwritten on the buffer)" .
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ERRORS
10 "EACCES" The "mctx" argument is invalid.
10 "EBADF" The socket descriptor "sockid" is invalid.
10 "EINVAL" The buffer management of the monitoring socket with "sockid" was already disabled.
10 "ENOTSOCK" The socket referred to by "sockid" has invalid "type"
10 "ENOTCONN" Th socket referred to by "sockid" is in a TCP state that disallows read operations.
10 "ENODATA" The socket referred to by "sockid" does not have any available bytes in its buffer for reading.
10
"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.
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""".SH CONFORMING TO
""""POSIX.1-2001.
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
AUTHORS
mOS development team <[email protected]>
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 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/.
"""""""""""""""""""""""""""""""""""""""""""""""""""""