tcpclient — Open a TCP client connection for socket I/O workflows.
tcpclient(host,port) opens a TCP/IP connection to a remote endpoint. The returned client value exposes connection and configuration properties used by read, write, and readline.
Syntax
client = tcpclient(host, port)
client = tcpclient(host, port, Name, Value, ...)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
host | StringScalar | Yes | — | Server hostname or IP address. |
port | NumericScalar | Yes | — | Server TCP port (0..65535). |
name_value_pairs | Any | Variadic | — | Name/Value options such as Timeout, ConnectTimeout, ByteOrder, UserData, Name, InputBufferSize, and OutputBufferSize. |
Returns
| Name | Type | Description |
|---|---|---|
client | Any | tcpclient handle struct for subsequent read/write/close operations. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:tcpclient:InvalidAddress | Host/address argument is not a valid string scalar. | tcpclient: invalid host argument |
RunMat:tcpclient:InvalidPort | Port argument is non-scalar, non-integer, non-finite, or out of range. | tcpclient: invalid port argument |
RunMat:tcpclient:InvalidNameValue | Name/Value arguments are malformed, unsupported, or have invalid values. | tcpclient: invalid name-value arguments |
RunMat:tcpclient:ConnectionFailed | Socket connect attempt fails. | tcpclient: unable to connect |
RunMat:tcpclient:InternalError | Internal stream setup or metadata query fails. | tcpclient: internal error |
How tcpclient works
tcpclient(host,port)resolves IPv4, IPv6, or DNS hostnames and connects using a default 10-secondConnectTimeout. The documented port range is 1 through 65535.TimeoutandConnectTimeoutaccept nonnegative double values orInf. The currently documentedEnableTransferDelayoption is not implemented yet.- RunMat mode additionally accepts typed-integer port and timeout values, port zero, and the legacy constructor options
ByteOrder,InputBufferSize,OutputBufferSize,UserData, andName. Integer values that enter a seconds boundary must be exactly representable as double. - Successful calls currently return a RunMat client structure rather than a MATLAB handle object. Public port properties are double values; private fields retain the live socket identity for companion networking builtins.
- Read and write timeouts are enforced using the
Timeoutvalue. Passinginfkeeps operations blocking. The returned struct reports the configured timeout verbatim. - Connection failures raise
RunMat:tcpclient:ConnectionFailedwith the operating-system error message. Invalid addresses, ports, or name-value arguments use stable RunMat error identifiers. - Automatically resident inputs are gathered transparently. Explicit gpuArray input requires RunMat mode and still produces a host client value.
Does RunMat run tcpclient on the GPU?
Networking always happens on the host CPU. RunMat gathers automatically resident arguments through their exact owning provider before creating the socket. Explicit gpuArray intent is checked separately before provider access.
GPU memory and residency
No. Networking and the returned client value are host-side. Automatic residency is gathered transparently; explicit gpuArray input is accepted only in RunMat mode.
Examples
Connecting to a loopback server for local testing
client = tcpclient("127.0.0.1", 55000);
disp(client.Address)
disp(client.Port)Expected output:
127.0.0.1
55000Customizing tcpclient timeouts and byte order
client = tcpclient("localhost", 60000, "Timeout", 5, "ConnectTimeout", 2, "ByteOrder", "big-endian");
disp(client.Timeout)
disp(client.ConnectTimeout)
disp(client.ByteOrder)Expected output:
5
2
big-endianStoring session metadata in UserData
meta = struct("session", "demo", "started", "2024-01-01T00:00:00Z");
client = tcpclient("example.com", 80, "UserData", meta);
disp(client.UserData.session)Expected output:
demoDetecting connection failures with a shorter connect timeout
try
client = tcpclient("192.0.2.20", 65530, "ConnectTimeout", 0.2);
catch err
disp(err.identifier)
endExpected output:
RunMat:tcpclient:ConnectionFailedKeeping a streaming connection open with infinite timeouts
client = tcpclient("data.example.com", 50000, "Timeout", inf, "ConnectTimeout", inf);
disp(client.Timeout)
disp(client.ConnectTimeout)Expected output:
Inf
InfUsing tcpclient with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how tcpclient changes the result.
Run a small tcpclient example, explain the result, then change one input and compare the output.
FAQ
Which byte orders are supported?⌄
In RunMat mode, the legacy ByteOrder constructor option accepts "little-endian" and "big-endian". Other values raise RunMat:tcpclient:InvalidNameValue.
Can I pass inf for Timeout or ConnectTimeout?⌄
Yes. Timeout = inf keeps I/O blocking, and ConnectTimeout = inf waits indefinitely for a connection.
How do I close the client?⌄
Call close(client) to release the socket.
Where do buffer sizes apply?⌄
The RunMat-mode InputBufferSize and OutputBufferSize options record desired limits for future buffered I/O behavior. They are not part of the current documented constructor surface.
Does the builtin support IPv6?⌄
Yes. Pass an IPv6 literal (for example "::1") or a hostname that resolves to IPv6. The returned struct reports the chosen address family.
What happens when the server rejects the connection?⌄
tcpclient raises RunMat:tcpclient:ConnectionFailed with the OS error (such as “connection refused”).
Can I pass an integer port?⌄
MATLAB-compatible mode expects the documented double port. RunMat mode also accepts every typed-integer class and validates the value directly in the 1-through-65535 structural range.
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 tcpclient is executed, line by line, in Rust.
- View the source for tcpclient 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.