Dart RawSocketOption

last modified October 18, 2026

The RawSocketOption class in Dart provides low-level access to socket configuration options. It's used with RawSocket for custom network protocol implementations.

RawSocketOption allows setting platform-specific socket options not exposed through higher-level APIs. It's part of Dart's dart:io library.

Basic Definition

RawSocketOption represents a socket option that can be set or queried on a RawSocket. It encapsulates the option level, the numeric option name, and the raw value bytes.

The level and option fields correspond to the level and optname arguments of the OS setsockopt and getsockopt calls. Dart provides the levelSocket, levelIPv4, levelIPv6, levelTcp, and levelUdp constants for common levels. Option numbers themselves remain platform-specific.

Enabling Socket Reuse

This example demonstrates enabling SO_REUSEADDR to allow address reuse.

import 'dart:io';

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

  // SO_REUSEADDR is option 2 at the SOL_SOCKET level on Linux
  var reuseAddr = RawSocketOption.fromBool(
    RawSocketOption.levelSocket,
    2,
    true
  );

  socket.setRawOption(reuseAddr);
  print('SO_REUSEADDR set to 1');

  await socket.close();
}

We create a socket and enable SO_REUSEADDR, which allows binding to addresses in TIME_WAIT state. This is useful for server sockets that restart frequently. The example is shown on a connected socket; option numbers are platform-specific.

$ dart main.dart
SO_REUSEADDR set to 1

Setting TCP Keepalive

This example configures TCP keepalive to detect dead connections.

import 'dart:io';

void main() async {
  var socket = await RawSocket.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('TCP Keepalive enabled');

  await socket.close();
}

We enable SO_KEEPALIVE which causes TCP to periodically verify the connection is still alive. This helps detect network failures without application traffic.

$ dart main.dart
TCP Keepalive enabled

Configuring Receive Buffer Size

This example sets the socket receive buffer size for better performance.

import 'dart:io';

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

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

  socket.setRawOption(rcvBuf);
  print('Receive buffer size set to 64KB');

  await socket.close();
}

We configure SO_RCVBUF to increase the kernel receive buffer size. Larger buffers improve throughput for high-bandwidth connections.

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

Disabling Nagle's Algorithm

This example disables Nagle's algorithm for low-latency communication.

import 'dart:io';

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

  // TCP_NODELAY is option 1 at the IPPROTO_TCP level
  var noDelay = RawSocketOption.fromBool(
    RawSocketOption.levelTcp,
    1,
    true // disable Nagle's algorithm
  );

  socket.setRawOption(noDelay);
  print('Nagle\'s algorithm disabled');

  await socket.close();
}

TCP_NODELAY disables Nagle's algorithm which buffers small packets. This reduces latency for interactive applications at the cost of more packets.

$ dart main.dart
Nagle's algorithm disabled

Querying Socket Options

This example shows how to query current socket option values.

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

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

  var queryRcvBuf = RawSocketOption(
    RawSocketOption.levelSocket,
    8, // SO_RCVBUF on Linux
    Uint8List(4) // buffer for the integer result
  );

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

  await socket.close();
}

We create a RawSocketOption with a buffer to hold the result, then call getRawOption to retrieve the current value. The buffer must be large enough for the option's value.

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

Best Practices

• Platform awareness: Option numbers and behavior differ across OSes
• Error handling: setRawOption and getRawOption throw OSError on failure
• Documentation: Consult OS headers for level and option numbers
• Testing: Verify option effects in your environment

Source

Dart RawSocketOption Documentation

This tutorial covered Dart's RawSocketOption class with practical examples showing common socket configurations for performance and reliability tuning.

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.