socket.7: Document SO_PEEK_OFF option

Since Linux 3.4 there appeared an ability to specify the
offset in bytes from which the data will be MSG_PEEK-ed.
Describe this socket option in the socket(7) page, where
all the other socket options are described.

Signed-off-by: Pavel Emelyanov <xemul@parallels.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

1 files changed, 27 insertions, 0 deletions

diff --git a/man7/socket.7 b/man7/socket.7
index 97e5a8c1..22052bad 100644
--- a/man7/socket.7
+++ b/man7/socket.7
@@ -628,6 +628,33 @@ for details on control messages.
 Gets the socket type as an integer (e.g.,
 .BR SOCK_STREAM ).
 This socket option is read-only.
+.TP
+.BR SO_PEEK_OFF " (since Linux 3.4)"
+This option controls the behavior of
+.BR recv(2)
+system call when used with
+.BR MSG_PEEK
+flag.
+
+When this value is negative (kernel sets -1 to all new sockets by default)
+the behavior of the
+.BR recv(2)
+is not affected at all.
+When it's set to zero or positive value, peeking the data would occur from
+the respective position in bytes. At the same time this offset will be
+incremented on the amount of bytes peeked from queue, so that the
+subsequent attempt to peek the data would result in next data in queue
+(similarly, receiving the data from queue without the
+.BR MSG_PEEK
+flag will result in respectively decreased offset value).
+For datagram sockets, if the offset points to the middle of a packet,
+the data returned will be marked with the
+.BR MSG_TRUNC
+flag.
+
+Since Linux 3.4 this option is supported for
+.BR unix(7)
+sockets only.
 .SS Signals
 When writing onto a connection-oriented socket that has been shut down
 (by the local or the remote end)