socket_sendmsg — Funktion · PHP-Referenz

Signatur

socket_sendmsg(Socket $socket, array $message, int $flags = 0): int|false

Beschreibung

socket_sendmsg() ist eine erweiterte Funktion zum Senden von Daten über einen Socket. Im Gegensatz zu socket_send() oder socket_write() erlaubt sie das Senden von mehreren Datenpuffern gleichzeitig (Scatter/Gather I/O) sowie das Übermitteln von zusätzlichen Steuerinformationen (sog. Ancillary Data oder Control Messages), wie sie z. B. für das Übertragen von Dateideskriptoren über Unix-Domain-Sockets benötigt werden.

Der Parameter $message ist ein assoziatives Array, das die Struktur einer msghdr-Struktur aus der C-Bibliothek widerspiegelt. Es kann die Schlüssel name (Zieladresse), iov (Array von Datenpuffern als Strings) und control (Array von Steuerinformationen) enthalten. Diese Funktion ist besonders nützlich, wenn Low-Level-Netzwerkprogrammierung oder die Interprozesskommunikation über Unix-Sockets erforderlich ist.

Die Funktion gibt die Anzahl der gesendeten Bytes zurück oder false bei einem Fehler. Mit socket_last_error() lässt sich der genaue Fehlercode ermitteln.

Parameter

Name	Typ	Default	Beschreibung
$socket Pflicht	Socket		Eine gültige `Socket`-Instanz, die mit `socket_create()` oder `socket_accept()` erstellt wurde.
$message Pflicht	array		Ein assoziatives Array mit der Nachrichtenstruktur. Unterstützte Schlüssel: `name`: Zieladresse als Array (z. B. `['family' => AF_INET, 'addr' => '127.0.0.1', 'port' => 1234]`) `iov`: Array von Strings, die als Datenpuffer verwendet werden (Scatter/Gather) `control`: Array von Steuerinformations-Arrays (Ancillary Data)
$flags	int	0	Bitmaske aus Socket-Flags, z. B. `MSG_DONTWAIT`, `MSG_DONTROUTE` oder `MSG_OOB`. Standardmäßig `0`.

Rückgabewert

Typ

int|false

Beschreibung

Gibt die Anzahl der erfolgreich gesendeten Bytes als int zurück. Bei einem Fehler wird false zurückgegeben; der genaue Fehler kann mit socket_last_error() abgefragt werden.

Beispiele

Einfache Nachricht über UDP-Socket senden

<?php
$socket = socket_create(AF_INET, SOCK_DGRAM, SOL_UDP);
if ($socket === false) {
    die('socket_create() fehlgeschlagen: ' . socket_strerror(socket_last_error()));
}

$message = [
    'name' => [
        'family' => AF_INET,
        'addr'   => '127.0.0.1',
        'port'   => 9000,
    ],
    'iov' => [
        'Hallo, ',
        'Welt!',
    ],
];

$bytesSent = socket_sendmsg($socket, $message, 0);
if ($bytesSent === false) {
    echo 'Fehler beim Senden: ' . socket_strerror(socket_last_error($socket));
} else {
    echo 'Bytes gesendet: ' . $bytesSent;
}

socket_close($socket);

Bytes gesendet: 13

Nachricht über Unix-Domain-Socket mit mehreren Puffern senden

<?php
$socketPath = '/tmp/test.sock';

$socket = socket_create(AF_UNIX, SOCK_DGRAM, 0);
if ($socket === false) {
    die('socket_create() fehlgeschlagen: ' . socket_strerror(socket_last_error()));
}

// Sende mehrere Datenpuffer in einem einzigen Aufruf (Scatter/Gather I/O)
$message = [
    'name' => [
        'family' => AF_UNIX,
        'path'   => $socketPath,
    ],
    'iov' => [
        'Teil 1: ',
        'Hallo',
        ' Welt',
    ],
];

$bytesSent = socket_sendmsg($socket, $message, MSG_DONTWAIT);
if ($bytesSent === false) {
    echo 'Fehler: ' . socket_strerror(socket_last_error($socket));
} else {
    echo 'Insgesamt gesendet: ' . $bytesSent . ' Bytes';
}

socket_close($socket);

Insgesamt gesendet: 16 Bytes

// Wichtig · Fallstricke

PHP-Version: Obwohl die Funktion intern schon länger existierte, wurde die Socket-Klasse als Typ für den ersten Parameter erst mit PHP 8.0 eingeführt. In PHP 7.x war die Funktion ggf. als experimentell oder nicht verfügbar dokumentiert.

Plattformabhängigkeit: socket_sendmsg() ist auf Windows-Systemen möglicherweise nicht vollständig unterstützt oder verhält sich anders als auf Unix/Linux. Besonders Ancillary Data und das Übertragen von Dateideskriptoren über Sockets sind POSIX-spezifische Funktionen.

Fehlerbehandlung: Da die Funktion false bei Fehlern zurückgibt, sollte immer mit === false geprüft werden, da 0 ein gültiger Rückgabewert (0 gesendete Bytes) sein kann.

Siehe auch

socket_recvmsg socket_send socket_sendto socket_create socket_last_error socket_strerror