Description
Affected page
https://www.php.net/manual/en/function.socket-atmark.php
Current issue
The header for Example 1 reads, "Example # 1 Using socket_atmark() to set the source address," which does not accurately describe the example (or the functionality of socket_atmark).
It looks like when the documentation of this function was added for PHP 8.3, the page for socket_bind() may have served as a template.
Suggested improvement
It would be brief and accurate (albeit arguably tautological) to change the header to "Example # 1 Using socket_atmark() to see if the socket is at the out-of-band mark."
Alternately, it might be changed to "Example # 1 Using socket_atmark() to see if the socket is ready to read out-of-band data."
Additional context
If one wanted to provide a more complete example of using this function, something like this might also work:
$socketServer = socket_create( AF_INET, SOCK_STREAM, SOL_TCP );
socket_set_option( $socketServer, SOL_SOCKET, SO_REUSEADDR, 1 );
socket_bind( $socketServer, '127.0.0.1' );
socket_listen( $socketServer );
$socketClient = socket_create( AF_INET, SOCK_STREAM, SOL_TCP );
socket_getsockname( $socketServer, $stAddr, $uPort );
socket_connect( $socketClient, $stAddr, $uPort );
$socket = socket_accept( $socketServer );
socket_shutdown( $socket, 1 );
$st = 'This is normal data.';
socket_send( $socketClient, $st, strlen( $st ), 0 );
$st = '!'; # TCP only allows one byte of urgent data.
socket_send( $socketClient, $st, strlen( $st ), MSG_OOB );
$st = 'Not so urgent.';
socket_send( $socketClient, $st, strlen( $st ), 0 );
socket_shutdown( $socketClient );
do {
if ( socket_atmark( $socket ) ) {
$rc = socket_recv( $socket, $st, 65536, MSG_OOB );
echo "Received urgent data: ({$rc}) {$st}\n";
} else {
$rc = socket_recv( $socket, $st, 1024, 0 );
echo "Received normal data: ({$rc}) {$st}\n";
}
} while ( $rc > 0 );
socket_close( $socketServer );
socket_close( $socketClient );
socket_close( $socket );Which produces the output:
Received normal data: (20) This is normal data.
Received urgent data: (1) !
Received normal data: (14) Not so urgent.
Received normal data: (0)
Could use the whole thing (for completeness), or just the do-while loop (for brevity).