tcpclient — Open a TCP client socket that connects to MATLAB-compatible servers.

tcpclient(host, port) opens a TCP/IP connection to a remote server and returns a MATLAB-compatible struct that mirrors the tcpclient object. The struct tracks connection metadata (remote address and port, byte order, timeouts, and callback configuration) and carries an opaque identifier that other RunMat networking builtins use to operate on the live socket.

How tcpclient works in RunMat

• 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.

How tcpclient runs 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

FAQ

Which byte orders are supported?

"little-endian" (default) and "big-endian". Any other string raises 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?

A companion builtin will release the socket. Until then, tests can use internal helpers to drop clients when finished.

Where do buffer sizes apply?

InputBufferSize and OutputBufferSize store the desired limits for future buffered I/O builtins. The current implementation records the values for compatibility.

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”).

Related functions to explore

These functions work well alongside tcpclient. Each page has runnable examples you can try in the browser.

tcpserver, accept, fread, fwrite, close, read, readline, write

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how tcpclient works, line by line, in Rust.

• View tcpclient.rs on GitHub
• Learn how the 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 — faster, on any GPU, with no license required.

• Simulations that took hours now take minutes. RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed.
• Start running code in seconds. Open the browser sandbox or download a single binary. No license server, no IT ticket, no setup.
• A full development environment. GPU-accelerated 2D and 3D plotting, automatic versioning on every save, and a browser IDE you can share with a link.

Getting started · Benchmarks · Pricing