=begin pod

=TITLE role IO::Socket

=SUBTITLE Network socket

    role IO::Socket does IO { ... }

C<IO::Socket> contains read and write methods for sockets. It is usually used
through L<IO::Socket::INET>.

=head1 Methods

=head2 method recv

    method recv(IO::Socket:D: Cool $elems = Inf)

Receive a package and return it, either as a L<Blob|/type/Blob> or a
L<Str|/type/Str> (depending on whether the socket is binary). If C<$elems> is
supplied, only that many bytes or characters are returned.

Fails if the socket is not connected.

=head2 method read

    method read(IO::Socket:D: Int(Cool) $bytes)

Reads C<$bytes> bytes from the socket and returns them in a
L<Blob|/type/Blob>.

Fails if the socket is not connected.

=head2 method print

    method print(IO::Socket:D: Str(Cool) $string)

Writes the supplied string to the socket, thus sending it to other end of the
connection. The binary version is L<#method write>.

Fails if the socket is not connected.

=head2 method write

    method write(IO::Socket:D: Blob:D $buf)

Writes the supplied buffer to the socket, thus sending it to other end of the
connection. The string version is L<#method send>.

Fails if the socket is not connected.

=head2 method close

    method close(IO::Socket:D)

Closes the socket.

Fails if the socket is not connected.

=head2 method native-descriptor

    method native-descriptor()

This returns a value that the operating system would understand as a "socket descriptor" and
is suitable for passing to a native function that requires a socket descriptor as an
argument such as C<setsockopt>.

=end pod
