[dart:io] Document raw sockets are not operating system raw sockets.
This change clarifies that dart:io's RawSocket is not an operating system
raw socket, which can be used to access the raw network protocol layer, but
is instead an API for accessing the transport protocol layer.
Closes https://github.com/dart-lang/sdk/issues/36792.
Change-Id: Id7a413184cb878e179778e4b5535abdc5527b270
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/100844
Commit-Queue: Jonas Termansen <sortie@google.com>
Reviewed-by: Lasse R.H. Nielsen <lrn@google.com>
diff --git a/sdk/lib/io/socket.dart b/sdk/lib/io/socket.dart
index 02fb46a..ec03664 100644
--- a/sdk/lib/io/socket.dart
+++ b/sdk/lib/io/socket.dart
@@ -556,8 +556,13 @@
}
/**
- * The [RawSocket] is a low-level interface to a socket, exposing the raw
- * events signaled by the system. It's a [Stream] of [RawSocketEvent]s.
+ * A [RawSocket] is an unbuffered interface to a TCP socket.
+ *
+ * The raw socket delivers the data stream in the same chunks as the underlying
+ * operating system.
+ *
+ * It is not the same as a
+ * [POSIX raw socket](http://man7.org/linux/man-pages/man7/raw.7.html).
*/
abstract class RawSocket implements Stream<RawSocketEvent> {
/**
@@ -830,12 +835,16 @@
}
/**
- * The [RawDatagramSocket] is a low-level interface to an UDP socket,
- * exposing the raw events signaled by the system. It's a [Stream] of
- * [RawSocketEvent]s.
+ * A [RawDatagramSocket] is an unbuffered interface to a UDP socket.
+ *
+ * The raw datagram socket delivers the datagrams in the same chunks as the
+ * underlying operating system. It's a [Stream] of [RawSocketEvent]s.
*
* Note that the event [RawSocketEvent.readClosed] will never be
* received as an UDP socket cannot be closed by a remote peer.
+ *
+ * It is not the same as a
+ * [POSIX raw socket](http://man7.org/linux/man-pages/man7/raw.7.html).
*/
abstract class RawDatagramSocket extends Stream<RawSocketEvent> {
/**
