[doc-en] master: Add: socket_sendmsg function doc (#2039)
| From: | songmeifeng via GitHub | 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>