Dart SocketOption

last modified October 18, 2026

The SocketOption class in Dart provides a way to configure socket options for network communication. It's part of Dart's dart:io library and is used with TCP Socket and RawSocket objects.

Socket options control low-level behaviors of network sockets, such as TCP no-delay, keep-alive, and buffer sizes. Dart exposes TCP no-delay directly through SocketOption.tcpNoDelay; other options are available through the lower-level RawSocketOption.

Basic Definition

SocketOption represents a socket-level configuration option that can be applied to sockets. The class exposes one public predefined option, tcpNoDelay.

Options are applied with Socket.setOption or RawSocket.setOption, which take a SocketOption and a boolean. For platform-specific options that are not exposed by SocketOption, use RawSocketOption together with setRawOption and getRawOption.

Enabling TCP_NODELAY

This example enables TCP_NODELAY on a TCP socket.

import 'dart:io';

void main() async {
  var socket = await Socket.connect('example.com', 80);

  // Send each write immediately instead of coalescing small packets
  var enabled = socket.setOption(SocketOption.tcpNoDelay, true);
  print('TCP_NODELAY enabled: $enabled');

  socket.destroy();
}

We create a TCP socket and enable TCP_NODELAY. With this option the socket does not wait to coalesce small writes into larger packets. The setOption method returns true when the option was set successfully.

$ dart main.dart
TCP_NODELAY enabled: true

Setting TCP_NODELAY on a RawSocket

This example applies the same option to a RawSocket.

import 'dart:io';

void main() async {
  var socket = await RawSocket.connect('example.com', 80);

  var enabled = socket.setOption(SocketOption.tcpNoDelay, true);
  print('RawSocket TCP_NODELAY enabled: $enabled');

  await socket.close();
}

A RawSocket accepts the same SocketOption values. We enable TCP_NODELAY here as well so that small writes are transmitted without delay.

$ dart main.dart
RawSocket TCP_NODELAY enabled: true

Configuring Keep-Alive

This example demonstrates enabling TCP keep-alive on a socket.

import 'dart:io';

void main() async {
  var socket = await Socket.connect('example.com', 80);

  // SO_KEEPALIVE is option 9 at the SOL_SOCKET level on Linux
  var keepAlive = RawSocketOption.fromBool(
    RawSocketOption.levelSocket,
    9,
    true
  );
  socket.setRawOption(keepAlive);

  print('Keep-alive enabled');
  socket.destroy();
}

TCP keep-alive periodically checks if the connection is still alive. This helps detect broken connections when no data is being transmitted. RawSocketOption.fromBool builds the low-level option; the numeric option name 9 is SO_KEEPALIVE on Linux and may differ on other platforms.

$ dart main.dart
Keep-alive enabled

Setting Custom Socket Option

This example shows how to set a custom socket option not predefined in Dart.

import 'dart:io';

void main() async {
  var socket = await Socket.connect('example.com', 80);

  // SO_RCVBUF is option 8 at the SOL_SOCKET level on Linux
  var rcvBuf = RawSocketOption.fromInt(
    RawSocketOption.levelSocket,
    8,
    65536
  );
  socket.setRawOption(rcvBuf);

  print('Receive buffer size set to 64KB');
  socket.destroy();
}

We create a custom socket option by specifying the level, option name, and value. This example sets SO_RCVBUF (option 8 on Linux) to 65536 bytes. The kernel may adjust the requested size.

$ dart main.dart
Receive buffer size set to 64KB

Reading a Socket Option

This example reads the current receive buffer size.

import 'dart:io';
import 'dart:typed_data';

void main() async {
  var socket = await Socket.connect('example.com', 80);

  // The option value must be a buffer large enough for the result
  var queryRcvBuf = RawSocketOption(
    RawSocketOption.levelSocket,
    8, // SO_RCVBUF on Linux
    Uint8List(4)
  );

  var value = socket.getRawOption(queryRcvBuf);
  var bufSize = ByteData.sublistView(value).getInt32(0, Endian.host);
  print('Current receive buffer size: $bufSize bytes');

  socket.destroy();
}

We create a RawSocketOption with a 4-byte buffer, call getRawOption, and decode the result with ByteData. Larger buffers can improve performance for high-bandwidth connections but use more memory.

$ dart main.dart
Current receive buffer size: 131072 bytes

Best Practices

• Portable option: Use SocketOption.tcpNoDelay for TCP no-delay
• Set early: Configure options immediately after connecting
• Platform support: RawSocketOption numbers are platform-specific
• Error handling: setRawOption and getRawOption throw OSError on failure
• Test: Verify option effects in your specific environment

Source

Dart SocketOption Documentation

This tutorial covered Dart's SocketOption class with practical examples showing common socket configurations and custom options for network programming.

Author

My name is Jan Bodnar, and I am a passionate programmer with extensive programming experience. I have been writing programming articles since 2007. To date, I have authored over 1,400 articles and 8 e-books. I possess more than ten years of experience in teaching programming.

List all Dart tutorials.