tcpserver — Create a TCP server listener for accept, read, and write workflows.
tcpserver(address,port) creates a TCP/IP listening socket, records its connection metadata, and returns a server value used by accept, read, write, and close.
Syntax
server = tcpserver(address, port)
server = tcpserver(address, port, Name, Value, ...)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
address | StringScalar | Yes | — | Bind address or hostname. |
port | NumericScalar | Yes | — | Listening TCP port (0..65535). |
name_value_pairs | Any | Variadic | — | Name/Value options such as Timeout, UserData, Name, and ByteOrder. |
Returns
| Name | Type | Description |
|---|---|---|
server | Any | tcpserver handle struct for accept/close operations. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:tcpserver:InvalidAddress | Address argument is not a valid string scalar. | tcpserver: invalid address argument |
RunMat:tcpserver:InvalidPort | Port argument is non-scalar, non-integer, non-finite, or out of range. | tcpserver: invalid port argument |
RunMat:tcpserver:InvalidNameValue | Name/Value arguments are malformed, unsupported, or have invalid values. | tcpserver: invalid name-value arguments |
RunMat:tcpserver:BindFailed | Socket bind operation fails. | tcpserver: unable to bind listener |
RunMat:tcpserver:InternalError | Internal listener metadata retrieval fails. | tcpserver: internal error |
How tcpserver works
tcpserver(address, port)binds to the requested interface; pass"0.0.0.0"or"::"to listen on every IPv4 or IPv6 adapter respectively.- The documented port range is 1 through 65535. In RunMat mode, port zero requests an ephemeral operating-system-assigned port that is reported by
ServerPort. Timeoutaccepts nonnegative double values orInf, andByteOrderaccepts little- or big-endian text. RunMat mode additionally accepts typed-integer port and timeout values plus the legacy constructor optionsUserDataandName.- The returned value is currently a RunMat server structure rather than a MATLAB handle object. Public port properties are double values, and
ClientPortis empty until a client connects. - The documented one-argument
tcpserver(port)form is not implemented yet; provide an address and port. - Automatically resident inputs are gathered transparently. Explicit gpuArray input requires RunMat mode and still produces a host server value.
- Bind failures raise
RunMat:tcpserver:BindFailedwith the operating-system error message.
Does RunMat run tcpserver on the GPU?
Networking occurs entirely on the host CPU. RunMat gathers automatically resident arguments through their exact owning provider before binding. Explicit gpuArray intent is checked separately before provider access.
GPU memory and residency
No. Socket binding and the returned server value are host-side. Automatic residency is gathered transparently; explicit gpuArray input is accepted only in RunMat mode.
Examples
Creating a loopback TCP server on a fixed port
srv = tcpserver("127.0.0.1", 55000);
disp(srv.ServerAddress)
disp(srv.ServerPort)Expected output:
127.0.0.1
55000Requesting an ephemeral port and inspecting the assigned value
srv = tcpserver("0.0.0.0", 0);
fprintf("Listening on %s:%d\n", srv.ServerAddress, srv.ServerPort)Expected output:
Listening on 0.0.0.0:54873 % actual port varies by runConfiguring the timeout and storing metadata in UserData
srv = tcpserver("localhost", 60000, "Timeout", 5, "UserData", struct("name", "demo"));
disp(srv.Timeout)
disp(srv.UserData.name)Expected output:
5
demoAssigning a custom server name
srv = tcpserver("::1", 45000, "Name", "LoopbackServer");
disp(srv.Name)Expected output:
LoopbackServerSelecting big-endian byte order for binary protocols
srv = tcpserver("127.0.0.1", 45001, "ByteOrder", "big-endian");
disp(srv.ByteOrder)Expected output:
big-endianHandle an invalid port
try
srv = tcpserver("127.0.0.1", 99999);
catch err
disp(err.identifier)
disp(err.message)
endExpected output:
RunMat:tcpserver:InvalidPort
RunMat:tcpserver:InvalidPort: tcpserver: port 99999 is outside the valid range 0–65535Using tcpserver with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how tcpserver changes the result.
Run a small tcpserver example, explain the result, then change one input and compare the output.
FAQ
What range of ports can I use?⌄
MATLAB-compatible mode accepts the documented range from 1 through 65535. RunMat mode also accepts port 0 to request an ephemeral port, which is reported in ServerPort.
How do I discover which clients are connected?⌄
The returned server value exposes Connected, ClientAddress, and ClientPort. Use accept to wait for an incoming connection and obtain its client value.
Does RunMat support IPv6?⌄
Yes. Pass an IPv6 literal (e.g., "::1") or hostname that resolves to IPv6. The returned ServerAddress reflects the bound address.
Can I change the timeout after creating the server?⌄
Not currently. Set Timeout when creating the server.
Does tcpserver fire callbacks like MATLAB’s BytesAvailableFcn?⌄
No. Callback properties are not currently active. Use accept, read, and write for explicit connection and data handling.
How do I close the server?⌄
Call close(server) to release the listener and its accepted clients.
Can I use GPU arrays for address or port?⌄
Automatically resident inputs are gathered transparently through their owning provider. Explicit gpuArray input requires RunMat mode because socket construction is a host operation without a documented GPU surface.
What happens if the port is already in use?⌄
tcpserver raises RunMat:tcpserver:BindFailed with the OS error message.
How do I pass additional socket options?⌄
Current support covers Timeout and ByteOrder; RunMat mode also provides the legacy Name and UserData options. Other socket options are not supported.
Is TLS supported?⌄
No. tcpserver currently provides plain TCP sockets only.
Related Io functions
Repl Fs
addpath · cd · copyfile · delete · dir · exist · fileattrib · fileparts · fullfile · genpath · getenv · getpref · isenv · isfile · isfolder · ispref · ls · matlabroot · memmapfile · mkdir · movefile · open · opentoline · path · pathsep · pcode · pwd · readstruct · rehash · restoredefaultpath · rmdir · rmpath · run · savepath · setenv · setpref · system · tempdir · tempname · uigetdir · uigetfile · uiputfile · unsetenv · userpath · what · winqueryreg · xmlread · xmlwrite
Tabular
arrayDatastore · csvread · csvwrite · detectImportOptions · dlmread · dlmwrite · fileDatastore · parquetDatastore · parquetinfo · parquetread · readcell · readmatrix · readtable · readtimetable · spreadsheetImportOptions · writecell · writematrix · writetable · writetimetable · xlsread · xlswrite
Filetext
fclose · feof · fgetl · fgets · fileread · filewrite · fopen · fprintf · fread · frewind · fwrite · readlines · writelines
Import
Json
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how tcpserver is executed, line by line, in Rust.
- View the source for tcpserver in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.