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
host- Type
StringScalar- Required
- Yes
- Description
- Server hostname or IP address.
port- Type
NumericScalar- Required
- Yes
- Description
- Server TCP port (0..65535).
name_value_pairs- Type
Any- Required
- Variadic
- Description
- Name/Value options such as Timeout, ConnectTimeout, ByteOrder, UserData, Name, InputBufferSize, and OutputBufferSize.
Returns
client- Type
Any- Description
- tcpclient object with sealed authority for read/write/close operations.
Errors
RunMat:network:UnsupportedTarget- When
- A native TCP socket operation is requested in a browser target.
- Message
native TCP sockets are unavailable on this target
RunMat:Cancelled- When
- An invocation is cancelled before or during a pending TCP operation.
- Message
TCP invocation was cancelled
RunMat:tcpclient:InvalidAddress- When
- Host/address argument is not a valid string scalar.
- Message
tcpclient: invalid host argument
Endpoint and options
tcpclient(host,port) resolves IPv4, IPv6, or DNS hostnames and connects using a default 10-second ConnectTimeout. The documented port range is 1 through 65535.
The current RunMat parser accepts nonnegative double values or Inf for Timeout and ConnectTimeout. Timeout = 0 and Inf leave I/O blocking, but a zero ConnectTimeout currently fails connection setup; use a positive value or Inf for connection attempts. The documented EnableTransferDelay option is not implemented.
RunMat mode additionally accepts typed-integer port and timeout values, port zero, and legacy constructor options ByteOrder, InputBufferSize, OutputBufferSize, UserData, and Name. Integer values entering a seconds boundary must be exactly representable as double.
Read and write timeouts use the captured Timeout. Passing Inf keeps operations blocking. The returned value reports the configured timeout verbatim.
Result, placement, and failures
RunMat returns a tcpclient object with a sealed session-owned socket authority, not a MATLAB handle-class implementation. Public port properties are double; editing visible properties does not reconfigure the live connection.
Connection failures raise RunMat:tcpclient:ConnectionFailed with the operating-system error. Invalid addresses, ports, and Name/Value controls use stable RunMat identifiers.
Automatically resident inputs gather through their owner. Explicit gpuArray input requires RunMat mode; the result remains host-resident. No accelerator kernel participates in TCP connection setup.
Illustrative programs
Connecting to a loopback server for local testing
client = tcpclient("127.0.0.1", 55000);
disp(client.Address)
disp(client.Port)
Expected display: 127.0.0.1
55000
Customizing 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 display: 5
2
big-endian
Storing 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 display: demo
Detecting connection failures
try
client = tcpclient("192.0.2.20", 65530, "ConnectTimeout", 0.2);
catch err
disp(err.identifier)
end
Expected error when the endpoint refuses or times out: RunMat:tcpclient:ConnectionFailed
Keeping a streaming connection open
client = tcpclient("data.example.com", 50000, "Timeout", inf, "ConnectTimeout", inf);
disp(client.Timeout)
disp(client.ConnectTimeout)
Expected display: Inf
Inf
Example
Connect to a local TCP peer
client = tcpclient('__RUNMAT_LOOPBACK_HOST__', __RUNMAT_LOOPBACK_PORT__);
assert(client.Connected);
assert(strcmp(client.Address, '__RUNMAT_LOOPBACK_HOST__'));
assert(client.Port == __RUNMAT_LOOPBACK_PORT__);
write(client, uint8(9));
close(client);Using 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; 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 do not currently resize the operating-system socket buffers.
Does the builtin support IPv6?⌄
Yes. Pass an IPv6 literal (for example "::1") or a hostname that resolves to IPv6. The returned value 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?⌄
Compatible mode expects the documented double port. RunMat mode also accepts every typed-integer class and validates it directly in the 1-through-65535 structural range.
Related Io functions
Repl Fs
addpath · cd · copyfile · delete · dir · exist · fileattrib · fileparts · filesep · fullfile · genpath · getenv · getpref · isenv · isfile · isfolder · ispref · ls · matlabroot · memmapfile · memmapfile.subsasgn · memmapfile.subsref · 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 · getvaropts · parquetDatastore · parquetinfo · parquetread · readcell · readmatrix · readtable · readtimetable · setvaropts · setvartype · spreadsheetImportOptions · writecell · writematrix · writetable · writetimetable · xlsread · xlswrite
Data
commit · data.copy · data.create · data.delete · data.exists · data.export · data.import · data.inspect · data.list · data.move · data.open · DataArray.chunk_shape · DataArray.codec · DataArray.dtype · DataArray.fill · DataArray.name · DataArray.rank · DataArray.read · DataArray.resize · DataArray.shape · DataArray.write · Dataset.array · Dataset.arrays · Dataset.attrs · Dataset.begin · Dataset.get_attr · Dataset.has_array · Dataset.id · Dataset.path · Dataset.refresh · Dataset.set_attr · Dataset.set_attrs · Dataset.snapshot · Dataset.version · DataTransaction.abort · DataTransaction.commit · DataTransaction.create_array · DataTransaction.delete_array · DataTransaction.fill · DataTransaction.id · DataTransaction.resize · DataTransaction.set_attr · DataTransaction.set_attrs · DataTransaction.status · DataTransaction.write
Filetext
fclose · feof · fgetl · fgets · fileread · filewrite · fopen · fprintf · fread · frewind · fwrite · readlines · writelines
Import
Json
Source you can read
Every RunMat function's source is public. 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 a runtime that executes MATLAB-syntax code fast on any GPU. The runtime is free for individuals, including freelancers; students and faculty at an academic institution, for teaching or research there; contributors to an open-source project, for work on that project; organizations with 250 or fewer people and US$10M or less in annual revenue; and anyone, for non-production use. See runmat.com/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.