socket.7: Add info about 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 <[email protected]>

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 <[email protected]>

---

man7/socket.7 +6 -0

index 2f915da..6177ab1 100644
@@ -618,6 +618,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

Quoted 6 lines · Pavel Emelyanov

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 <[email protected]>

Pavel, I have applied this patch, but would like to clarify some details. See below.

Quoted 22 lines

---

man7/socket.7 +12 -0

index 2f915da..6177ab1 100644
@@ -618,6 +618,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.

man7/socket.7 for details on control messages. · line 636

Quoted 4 lines

man7/socket.7 +4 -0

+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

So, if I set SO_PEEK_OFF to 5 and do a recv(fs, buf, 10, MSG_PEEK), then the offset will end up at 15, and the next MSG_PEEK would retrieve at offset 15, right?

man7/socket.7 for details on control messages. · line 639

Quoted 3 lines

man7/socket.7 +3 -0

+(similarly, receiving the data from queue without the
+.BR MSG_PEEK
+flag will result in respectively decreased offset value).

What does this mean? Is it correct that if I set SO_PEEK_OFF to 5 and do a recv(fs, buf, 10, 0), then the offset will end up at 0, and the next MSG_PEEK would retrieve at offset 0?

Or, rather, does a recv()
without MSG_PEEK leave the offset unchanged, so that the next MSG_PEEK would retrieve at offset 5?

Thanks,

Michael

Quoted 33 lines · Michael Kerrisk (man-pages)

Quoted 6 lines · Pavel Emelyanov

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 <[email protected]>

Pavel, I have applied this patch, but would like to clarify some details. See below.

Quoted 22 lines

---

man7/socket.7 +12 -0

index 2f915da..6177ab1 100644
@@ -618,6 +618,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.

Quoted 8 lines

man7/socket.7 for details on control messages. · line 636

Quoted 4 lines

man7/socket.7 +4 -0

+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

So, if I set SO_PEEK_OFF to 5 and do a recv(fs, buf, 10, MSG_PEEK), then the offset will end up at 15, and the next MSG_PEEK would retrieve at offset 15, right?

Exactly.

Quoted 7 lines

man7/socket.7 for details on control messages. · line 639

Quoted 3 lines

man7/socket.7 +3 -0

+(similarly, receiving the data from queue without the
+.BR MSG_PEEK
+flag will result in respectively decreased offset value).

What does this mean? Is it correct that if I set SO_PEEK_OFF to 5 and do a recv(fs, buf, 10, 0), then the offset will end up at 0, and the next MSG_PEEK would retrieve at offset 0?

Yes.

Quoted 3 lines

Or, rather, does a recv()
without MSG_PEEK leave the offset unchanged, so that the next MSG_PEEK would retrieve at offset 5?

No. The logic behind that is -- if you set peek-offset and _receive_ some message (removing it from the queue) the peek-offset is adjusted (decreased) so that the next message you will _peek_ after that would be the same as if it was if you didn't do the receive before. (sorry for my English, subjunctive is bad :( ).

IOW, here's the queue:

   msg0, msg1, msg2, msg3, msg4

You set peek off to 2 (^ below)

   msg0, msg1, msg2, msg3, msg4
                ^(2)

Now you peek a message, get msg2 and the queue is updated like this:

   msg0, msg1, msg2, msg3, msg4
                      ^(3)

i.e. -- peek-off is increased. Next message peek-ed will be msg3. Now what happens if you receive a message:

msg1, msg2, msg3, msg4

               ^(2)

msg0 is removed from the queue and the peek-off is decreased down to 2 to still point to the msg3, since you haven't yet peek-ed one.

Hope this makes things more clear.

Quoted 1 line

Hope this makes things more clear.

Yep, that helps considerably. I've extensively reworked your text, adding quite a bit more detail. Could you check the text below please?

Cheers,

Michael

SO_PEEK_OFF (since Linux 3.4)
This option, which is currently supported only for unix(7) sockets, sets the value of the "peek offset" for the recv(2) system call when used with MSG_PEEK flag.

When this option is set to a negative value (it is set to -1 for all new sockets), traditional behavior is provided:
recv(2) with the MSG_PEEK flag will peek data from the front of the queue.

When the option is set to a value greater than or equal to zero, then the next peek at data queued in the socket will occur at the byte offset specified by the option value. At the same time, the "peek offset" will be incremented by the number of bytes that were peeked from the queue, so that a subsequent peek will return the next data in the queue.i

If data is removed from the front of the queue via a call to recv(2) (or similar) without the MSG_PEEK flag, the "peek offset" will be decreased by the number of bytes removed. In other words, receiving data without the MSG_PEEK flag will cause the "peek offset" to be adjusted to maintain the correct relative position in the queued data, so that a subsequent peek will retrieve the data that would have been retrieved had the data not been removed.

For datagram sockets, if the "peek offset" points to the middle of a packet, the data returned will be marked with the MSG_TRUNC flag.

The following example serves to illustrate the use of SO_PEEK_OFF. Suppose a stream socket has the following queued input data:

aabbccddeeff

The following sequence of recv(2) calls would have the effect noted in the comments:

int ov = 4; // Set peek offset to 4
setsockopt(fd, SOL_SOCKET, SO_PEEK_OFF, &ov, sizeof(ov));

recv(fd, buf, 2, MSG_PEEK); // Peeks "cc"; offset set to 6 recv(fd, buf, 2, MSG_PEEK); // Peeks "dd"; offset set to 8
recv(fd, buf, 2, 0); // Reads "aa"; offset set to 6
recv(fd, buf, 2, MSG_PEEK); // Peeks "ee"; offset set to 8
.