[doc-en] master: Add: socket_sendmsg function doc (#2039)

From: Date: Tue, 01 Sep 2026 20:07:06 +0000
Subject: [doc-en] master: Add: socket_sendmsg function doc (#2039)
Groups: php.doc.cvs 
Request: Send a blank email to doc-cvs+get-23693@lists.php.net to get a copy of this message
Author: songmeifeng (AtlanticF) Committer: GitHub (web-flow) Pusher: lacatoire Date: 2026-09-01T22:07:03+02:00 Commit: https://github.com/php/doc-en/commit/30b010f003975adc755ebbf6097d3462bb1875db Raw diff: https://github.com/php/doc-en/commit/30b010f003975adc755ebbf6097d3462bb1875db.diff Add: socket_sendmsg function doc (#2039) * Add: socket_sendmsg function doc * Use simpara for the inline-only para elements The DocBook Lint job requires simpara for para elements in the diff whose content is inline only. * Correct the message array structure and the flags table The message array read by socket_sendmsg() only has the keys name, iov and control, all of them optional; any other key is ignored. The flags key comes from the array returned by socket_recvmsg() and has no meaning when sending. control is a list of ancillary data messages, and it is each element that carries level, type and data, not control itself. name depends on the address family: addr and port for AF_INET, additionally flowinfo and scope_id for AF_INET6, and path for AF_UNIX, with an optional family key selecting the family explicitly. Also restore the MSG_EOR wording used by socket_send() and socket_sendto(), add the MSG_EOF row those two pages carry, and keep the original refpurpose. * Add examples for socket_sendmsg() The structure of the message array is the only hard part of this function, so the page needs to show it. The first example sends a datagram using name and iov, the second passes a file descriptor through the control key with SCM_RIGHTS, which is the reason to reach for socket_sendmsg() over socket_sendto(). * Fix inaccuracies in the socket_sendmsg() page Drop the MSG_EOF row: its description is the BSD semantics, and on Linux the constant is an alias of MSG_FIN which the kernel ignores for TCP, so the flag neither closes the sender side nor ends the transaction there. List the supported level and type pairs for control instead of leaving the shape of data unspecified, since the set is small and a pair outside it fails. Also: name the missing flags element, which only exists in the array filled in by socket_recvmsg(); state that addr accepts a host name and that family must match the socket; say that an empty iov sends no data rather than an empty message, which only holds for datagram sockets; add socket_create_pair() to the socket description, as the second example uses it; and note that the file descriptor example does not run on Windows. --------- Co-authored-by: Louis-Arnaud <la.catoire@gmail.com> Changed paths: M reference/sockets/functions/socket-sendmsg.xml Diff: diff --git a/reference/sockets/functions/socket-sendmsg.xml b/reference/sockets/functions/socket-sendmsg.xml index 33335fb12b30..fb28e05dc844 100644 --- a/reference/sockets/functions/socket-sendmsg.xml +++ b/reference/sockets/functions/socket-sendmsg.xml @@ -13,9 +13,11 @@ <methodparam><type>array</type><parameter>message</parameter></methodparam> <methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer>0</initializer></methodparam> </methodsynopsis> - <para> - </para> - &warn.undocumented.func; + <simpara> + The function <function>socket_sendmsg</function> sends the message described by + <parameter>message</parameter> through the socket <parameter>socket</parameter>, + using the <literal>sendmsg()</literal> system call. + </simpara> </refsect1> <refsect1 role="parameters"> @@ -25,21 +27,154 @@ <varlistentry> <term><parameter>socket</parameter></term> <listitem> - <para> - </para> + <simpara> + A <classname>Socket</classname> instance created with <function>socket_create</function>, + <function>socket_accept</function> or <function>socket_create_pair</function>. + </simpara> </listitem> </varlistentry> <varlistentry> <term><parameter>message</parameter></term> <listitem> - <para> - </para> + <simpara> + An associative array which may contain the following elements. All of them + are optional, and unrecognized keys are silently ignored. In particular + there is no <varname>flags</varname> element when sending; that key only + appears in the array filled in by <function>socket_recvmsg</function>. + </simpara> + <variablelist> + <varlistentry> + <term><varname>name</varname></term> + <listitem> + <simpara> + The address of the remote host, as an array. Its keys are + <varname>addr</varname> and <varname>port</varname> for + <constant>AF_INET</constant>; <varname>addr</varname>, + <varname>port</varname>, <varname>flowinfo</varname> and + <varname>scope_id</varname> for <constant>AF_INET6</constant>; and + <varname>path</varname> for <constant>AF_UNIX</constant>. + <varname>addr</varname> accepts an IP address or a host name, which is + then resolved. An optional <varname>family</varname> key selects the + address family explicitly; if omitted, the family of + <parameter>socket</parameter> is used. A family the socket does not + support makes the call fail. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>iov</varname></term> + <listitem> + <simpara> + A list of buffers holding the data to send, which are sent in order as a + single message. Array keys are ignored and the values are converted to + string. When this key is missing or empty, no data is sent and the + function returns <literal>0</literal>. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>control</varname></term> + <listitem> + <simpara> + A list of ancillary data messages. Each is an array with the keys + <varname>level</varname>, <varname>type</varname> and + <varname>data</varname>. Only the pairs below are supported, and their + availability depends on the platform. + </simpara> + <table> + <title>Supported ancillary data</title> + <tgroup cols="3"> + <thead> + <row> + <entry><varname>level</varname></entry> + <entry><varname>type</varname></entry> + <entry><varname>data</varname></entry> + </row> + </thead> + <tbody> + <row> + <entry><constant>SOL_SOCKET</constant></entry> + <entry><constant>SCM_RIGHTS</constant></entry> + <entry> + A non-empty list of <classname>Socket</classname> instances or + stream resources, whose file descriptors are sent to the receiving + process. + </entry> + </row> + <row> + <entry><constant>SOL_SOCKET</constant></entry> + <entry><constant>SCM_CREDENTIALS</constant></entry> + <entry> + An array with the keys <varname>pid</varname>, + <varname>uid</varname> and <varname>gid</varname>. Named + <constant>SCM_CREDS</constant> or <constant>SCM_CREDS2</constant> + on some systems. + </entry> + </row> + <row> + <entry><constant>IPPROTO_IPV6</constant></entry> + <entry><constant>IPV6_PKTINFO</constant></entry> + <entry> + An array with the keys <varname>addr</varname> and + <varname>ifindex</varname>. + </entry> + </row> + <row> + <entry><constant>IPPROTO_IPV6</constant></entry> + <entry><constant>IPV6_HOPLIMIT</constant></entry> + <entry>An <type>int</type>.</entry> + </row> + <row> + <entry><constant>IPPROTO_IPV6</constant></entry> + <entry><constant>IPV6_TCLASS</constant></entry> + <entry>An <type>int</type>.</entry> + </row> + </tbody> + </tgroup> + </table> + </listitem> + </varlistentry> + </variablelist> </listitem> </varlistentry> <varlistentry> <term><parameter>flags</parameter></term> <listitem> <para> + The value of <parameter>flags</parameter> can be any combination of the + following flags, joined with the binary OR (<literal>|</literal>) operator. + <table> + <title>Possible values for <parameter>flags</parameter></title> + <tgroup cols="2"> + <tbody> + <row> + <entry><constant>MSG_OOB</constant></entry> + <entry> + Send OOB (out-of-band) data. + </entry> + </row> + <row> + <entry><constant>MSG_EOR</constant></entry> + <entry> + Indicate a record mark. The sent data completes the record. + </entry> + </row> + <row> + <entry><constant>MSG_DONTWAIT</constant></entry> + <entry> + With this flag set, the function returns even if it would normally + have blocked. + </entry> + </row> + <row> + <entry><constant>MSG_DONTROUTE</constant></entry> + <entry> + Bypass routing, use direct interface. + </entry> + </row> + </tbody> + </tgroup> + </table> </para> </listitem> </varlistentry> @@ -71,6 +206,80 @@ </informaltable> </refsect1> + <refsect1 role="examples"> + &reftitle.examples; + <example> + <title>Sending a message with <function>socket_sendmsg</function></title> + <programlisting role="php"> +<![CDATA[ +<?php +$server = socket_create(AF_INET, SOCK_DGRAM, SOL_UDP); +socket_bind($server, '127.0.0.1', 1053); + +$client = socket_create(AF_INET, SOCK_DGRAM, SOL_UDP); +$sent = socket_sendmsg($client, [ + 'name' => ['addr' => '127.0.0.1', 'port' => 1053], + 'iov' => ['Hello ', 'world'], +], 0); + +echo "sent: $sent\n"; + +socket_recvfrom($server, $buffer, 64, 0, $from, $port); +echo "received: $buffer\n"; +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +sent: 11 +received: Hello world +]]> + </screen> + </example> + <example> + <title>Passing a file descriptor over a UNIX socket</title> + <simpara> + The <varname>control</varname> key carries ancillary data. With + <constant>SCM_RIGHTS</constant>, it transfers open file descriptors to the + process at the other end of a UNIX socket. This is not available on Windows. + </simpara> + <programlisting role="php"> +<![CDATA[ +<?php +socket_create_pair(AF_UNIX, SOCK_STREAM, 0, $pair); +[$sender, $receiver] = $pair; + +$file = fopen(__FILE__, 'r'); + +socket_sendmsg($sender, [ + // At least one byte of regular data must accompany the ancillary data. + 'iov' => ['fd'], + 'control' => [ + ['level' => SOL_SOCKET, 'type' => SCM_RIGHTS, 'data' => [$file]], + ], +], 0); + +$message = [ + 'buffer_size' => 16, + 'controllen' => socket_cmsg_space(SOL_SOCKET, SCM_RIGHTS, 1), +]; +socket_recvmsg($receiver, $message, 0); + +$received = $message['control'][0]['data'][0]; +echo "first line: ", fgets($received); +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +first line: <?php +]]> + </screen> + </example> + </refsect1> + <refsect1 role="seealso"> &reftitle.seealso; <para>

« previous php.doc.cvs (#23693) next »