SocketListen
SocketListen[socket,fun]
starts listening on the specified socket, asynchronously applying fun whenever data is received on the socket.
SocketListen[port,fun]
starts listening for active connections on the specified port of 127.0.0.1.
SocketListen[address,fun]
starts listening for active connections on the specified address address on the local machine.
SocketListen[spec,opts]
starts listening for active connections defined by spec using the options opts.
SocketListen[spec]
starts listening for active connections defined by spec, but does not set up handler functions, etc.
Details and Options
- In SocketListen[socket,…], socket is of the form SocketObject[…].
- SocketListen[…] gives a SocketListener object.
- For ZMQ sockets, fun is by default applied whether or not a complete message is received.
- For raw TCP sockets, fun is by default applied to every data buffer generated by the operating system.
- For web sockets, fun is by default applied to complete messages.
- If SocketListen[spec,…] creates a new SocketObject, that socket is closed automatically when DeleteObject is called on the returned SocketListener.
- With the option settings RecordSeparators->"s" or RecordSeparators->{"s1","s2",…}, fun is applied to each block of data received between successive delimiters matching s or the si.
- For web sockets, fun is applied to data as it is received if RecordSeparators->None. The data is not guaranteed to be a complete message or message fragment. Users will be responsible for buffering data.
- For web sockets, fun will be applied to unread data that is still on the socket at the time the listener is installed.
- The function fun is applied to an association representing each event, with the following default keys:
-
"Data" the data received, as a string "Socket" the SocketObject being listened on "SourceSocket" the SocketObject that generated the event "Timestamp" time when the event occurred (as a DateObject) - The following additional keys can also be requested in HandlerFunctionsKeys:
-
"DataBytes" the raw data received, as a list of byte values "DataByteArray" the raw data received, as a ByteArray object "MultipartComplete" whether a multipart ZMQ or web socket message is complete - For web sockets, fun is by default applied to an association containing the keys "Socket", "Data", "DataByteArray" and "MultipartComplete", in addition to the following:
-
"Type" the type of the web socket message "BytesLeftInChunk" the number of bytes left unread in the current message fragment - The value of the "Type" key will be either "String" or "Binary".
- SocketListen accepts the following options:
-
CharacterEncoding $CharacterEncoding the character encoding to assume HandlerFunctionsKeys Default keys to include in the data association HandlerFunctions Automatic how to handle socket events RecordSeparators Automatic how messages are taken to be delimited - The following events can be generated while listening on the socket:
-
"DataReceived" data is available on the socket
Examples
open all close allBasic Examples (2)
Listen on an available socket to print off the association for the event:
listener = SocketListen[Automatic, Echo]Send some data (printed messages may appear in the Messages window):
server = listener["Socket"];
client = SocketConnect[server];
WriteString[client, "message from client"]Delete the listener and close the sockets:
DeleteObject[listener];
Close[client]You can also set up listeners for web sockets:
webSocket = SocketConnect["wss://echo.websocket.org"]SocketListen[webSocket, Print]Scope (2)
Listen on a TCP socket on an open port on your system, printing off all data:
listener = SocketListen[Automatic, Print]Connect to the socket with a web browser:
server = listener["Socket"];URLBuild[<|"Scheme" -> "http", "Port" -> server["DestinationPort"], "Domain" -> First[server["DestinationIPAddress"]]|>]Opening the URL with the system browser will print the request in the Messages window:
SystemOpen[%]DeleteObject[listener]Make a pair of client and server sockets:
server = SocketOpen[Automatic, "ZMQ"];
client = SocketConnect[server];Submit to the server socket a HandlerFunctions for incoming data to save the message inside a variable:
listener = SocketListen[server, (msg = #Data)&]When the client writes to the socket, the server will print the message:
WriteString[client, DateString[]]msgChange the HandlerFunctions to additionally print the data as a list of bytes:
SetOptions[listener, HandlerFunctionsKeys -> {"DataBytes"}];SetOptions[listener, HandlerFunctions -> <|"DataReceived" :> Function[{data}, msg = data["DataBytes"]]|>];WriteString[client, "hello"]msgStop listening for events with this socket:
DeleteObject[listener]Because the listener no longer exists, messages sent to the server will not call any HandlerFunctions:
WriteString[client, "a new message"]The handler function did not update the value of msg:
msgThe message can be read from the server with SocketReadMessage:
ByteArrayToString@SocketReadMessage[server]Close /@ {server, client}Options (4)
HandlerFunctionsKeys (1)
Modify the HandlerFunctionsKeys to be only the data as a ByteArray with "DataByteArray":
listener = SocketListen[Automatic, Print, HandlerFunctionsKeys -> {"DataByteArray"}]Change the value after starting listening on the socket:
SetOptions[listener, HandlerFunctionsKeys -> {"DataBytes"}];Show the updated value of the HandlerFunctionsKeys:
listener[HandlerFunctionsKeys]Stop listening and close the socket:
DeleteObject[listener]HandlerFunctions (1)
Specify the function to run on generated data with HandlerFunctions and the "DataReceived" event:
listener = SocketListen[Automatic, HandlerFunctions -> <|"DataReceived" :> Print|>]Change the value after starting it:
SetOptions[listener, HandlerFunctions -> <|"DataReceived" :> Function[{data}, msg = data]|>];Stop listening and close the socket:
DeleteObject[listener];CharacterEncoding (1)
Listen for messages, encoding the string key "Data" with a different encoding and encoding the "DataBytes" normally:
listener = SocketListen[Automatic, (msg = <|$CharacterEncoding -> FromCharacterCode[#DataBytes, $CharacterEncoding], "ZapfDingbats" -> #Data|>)&, HandlerFunctionsKeys -> {"Data", "DataBytes"}, CharacterEncoding -> "ZapfDingbats"]client = SocketConnect[listener["Socket"]]WriteString[client, "hello world"]Inspect the message to see the different encodings:
msgStop listening and close the socket:
DeleteObject[listener]RecordSeparators (1)
Listen on a socket, splitting up messages by whitespace:
msgs = {};
listener = SocketListen[Automatic, AppendTo[msgs, #Data]&, RecordSeparators -> {"XXX", "YYY"}]Create a client and send a message on this client to the listener's socket:
client = SocketConnect[listener["Socket"]];
WriteString[client, "helloXXXworldYYYfromXXXtheYYYWolframXXXLanguageYYY!"]Now msgs will have the message string split up by the RecordSeparators value:
msgsStop listening and close the socket:
DeleteObject[listener];Listen on a socket, splitting up messages by a set number of bytes:
Applications (1)
Start a web server, sending a basic HTML page back as the response to all clients:
listener = SocketListen[Automatic, Function[{assoc},
With[{client = assoc["SourceSocket"], html = "<html>
<body>
<h1>Hello from the Wolfram Language</h1>
Today's date is : " <> DateString[] <> "
</body>
</html>"},
WriteString[client, "HTTP/1.1 200 OK
Date: " <> DateString[] <> " " <> $TimeZoneEntity["ShortName"] <> "
Content-Type: text/html
Content-Length: " <> ToString[StringLength[html]] <> "
" <> html <> "
"
];
Close[client]
]
]
]Import the result from the Wolfram Language:
url = URLBuild[<|"Scheme" -> "http", "Domain" -> First[listener["Socket"]["DestinationIPAddress"]], "Port" -> listener["Socket"]["DestinationPort"]|>]response = URLRead[url]ImportString[response["Body"]]Open the website in your system browser:
SystemOpen[url]Stop listening and close the socket:
DeleteObject[listener];Possible Issues (2)
It is not possible to read from web sockets that have a SocketListener installed:
webSocket = SocketConnect["wss://echo.websocket.org"];
SocketListen[webSocket, Print];
SocketReadMessage[webSocket]It is not possible to create servers for web sockets:
SocketListen[{"127.0.0.1", "ws"}]Interactive Examples (1)
Listen on a socket, continuously writing again to the server a rotated message as soon as a message is received:
listener = SocketListen[Automatic, Function[WriteString[client, message = StringRotateLeft[#Data]]]];
server = listener["Socket"];
client = SocketConnect[server];WriteString[client, "Hello world from the Wolfram Language --- "]Visualize the dynamic rotation of the string:
Dynamic[Style[message, 16]]Stop listening and close the sockets:
DeleteObject[listener];
Close[client]Text
Wolfram Research (2017), SocketListen, Wolfram Language function, https://reference.wolfram.com/language/ref/SocketListen.html (updated 2026).
CMS
Wolfram Language. 2017. "SocketListen." Wolfram Language & System Documentation Center. Wolfram Research. Last Modified 2026. https://reference.wolfram.com/language/ref/SocketListen.html.
APA
Wolfram Language. (2017). SocketListen. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/SocketListen.html