tcpclient — Open TCP client connections and return MATLAB-compatible client structs for socket I/O workflows.

tcpclient(host, port) opens a TCP/IP connection to a remote endpoint and returns a MATLAB-compatible client struct. The struct stores socket metadata and an internal handle used by related networking builtins like read, write, and readline.

Syntax

client = tcpclient(host, port)
client = tcpclient(host, port, Name, Value, ...)

Inputs

Returns

Errors

How tcpclient works

• tcpclient(host, port) resolves the hostname (IPv4, IPv6, or DNS) and connects using the default 10 second ConnectTimeout. Ports must lie in the range 0–65535.
• Name-value pairs mirror MATLAB defaults: Timeout (non-negative seconds, determines read/write timeouts), ConnectTimeout (non-negative seconds, controls how long connection establishment waits), ByteOrder ("little-endian" or "big-endian"), InputBufferSize, OutputBufferSize, UserData, and Name. Unknown options raise RunMat:tcpclient:InvalidNameValue.
• Successful calls return a struct whose fields match MATLAB’s tcpclient object, including callback placeholders (BytesAvailableFcn, BytesAvailableFcnMode, BytesAvailableFcnCount), connection metadata (Address, Port, ServerAddress, ServerPort, LocalAddress, LocalPort), and configuration (Timeout, ConnectTimeout, buffer sizes, ByteOrder). Hidden fields __tcpclient_id and __tcpserver_id retain the live socket handle for companion networking builtins.
• Read and write timeouts are enforced using the Timeout value. Passing inf keeps operations blocking. The returned struct reports the configured timeout verbatim.
• Connection failures raise RunMat:tcpclient:ConnectionFailed with the OS error message. Invalid addresses, ports, or name-value arguments raise the corresponding MATLAB-style diagnostics.

Does RunMat run tcpclient on the GPU?

Networking always happens on the host CPU. If host, port, or name-value arguments reside on the GPU, RunMat gathers them automatically before the socket is created. The returned struct is CPU-resident, and no acceleration-provider hooks are required.

GPU memory and residency

No. RunMat automatically gathers GPU scalars before opening sockets. The returned struct—and all networking operations—run on the CPU, so gpuArray offers no benefit for tcpclient.

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
55000

Customizing 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-endian

Storing 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:

demo

Detecting connection failures with a shorter connect timeout

try
    client = tcpclient("192.0.2.20", 65530, "ConnectTimeout", 0.2);
catch err
    disp(err.identifier)
end

Expected output:

RunMat:tcpclient:ConnectionFailed

Keeping 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
Inf

Using tcpclient with coding agents

Open a RunMat example with live inputs, then ask the agent to explain how tcpclient changes the result.

FAQ

Related Io functions

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.

Getting started · Benchmarks · Pricing