Description:
------------
---
From manual page: http://www.php.net/function.socket-recvmsg
---

The documentation on php.net describes the usage for the socket_recvmsg function as follows:

        int socket_recvmsg ( resource $socket , string &$message [, int $flags = 0 ] )

But this is entirely incorrect and it should probably read something like this:

        int socket_recvmsg( resource $socket, array $data [, int flags = 0] )


With array $msghdr being constructed as follows (taken from the php unit tests):

        $data = array (
            "name" => array (
                "family" => AF_INET6,
                "addr" => "::1"),
            "buffer_size" => 2000,
            "controllen" => socket_cmsg_space(IPPROTO_IPV6, IPV6_PKTINFO),
        );


When attempting to use the function as described in the documentation, I wrote the code snippet (labeled as file "y.php") which obviously failed miserably: Executing the snippet provided the following warning message:

        Warning: socket_recvmsg() expects parameter 2 to be array, string given in /env/php/y.php on line 7
        string(0) ""
        NULL

At which point, I adjusted the snippet (lato utilize an array which the function claims it wanted (labeled z.php): Now, executing the snippet produced the following message:

        Warning: socket_recvmsg(): error converting user data (path: msghdr): The key 'controllen' is required in /env/php/z.php on line 10
        array (0) {
        }
        bool(false)

After gathering the necessary information to fill out this bug report, I now realize that the method I used to explore the use of this function is 100% incorrect, however, as it is described in the documentation, what I attempted to do should have produced some sort of better clue as to why it was wrong. 

Instead, the messages muddied the water even more until I looked at the socket_recvmsg.phpt code used to test the function.

Further, if you look at the function socket_sendmsg, it does refer to the requirement for an array, but it doesn't make any mention of the requirement for the structure of that array (which now seems to be relevant after viewing the unit test).

If you could change the documentation to reflect the actual requirements, that would just be awesome.

I appreciate your time and attention.


Test script:
---------------
--------- file y.php ------------
        <?php //7.3.0-dev
        // File: y.php

        $sockets = array();
        socket_create_pair(AF_UNIX, SOCK_STREAM, 0, $sockets);

        $rcvBuffer = "";
        $undescribed_integer = socket_recvmsg($sockets[0], $rcvBuffer, 0);

        var_dump($rcvBuffer,$undescribed_integer)
        ?>
--------- file z.php ------------
        <?php // 7.3.0-dev
        //File: z.php

        $sockets = array();
        socket_create_pair(AF_UNIX, SOCK_STREAM, 0, $sockets);

        $rcvBuffer = array();
        $undescribed_integer = socket_recvmsg($sockets[0], $rcvBuffer, 0);

        var_dump($rcvBuffer,$undescribed_integer);
        ?>