=begin pod :kind("Type") :subkind("role") :category("domain-specific")

=TITLE role IO::Socket

=SUBTITLE Network socket

    role IO::Socket { ... }

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

=head1 Methods

=head2 method recv

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

Receive a packet and return it, either as a L<Blob|/type/Blob> if
C<:bin> was passed, or a L<Str|/type/Str> if not.
Receives up to C<$elems> or C<65535> (whichever is smaller) bytes or characters.

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 routine get

Defined as:

    method get(IO::Socket:D: --> Str:D)

Reads a single line of input from the socket, removing the trailing newline
characters (as set by L«C<.nl-in>|/routine/nl-in»). Returns C<Nil>, if no
more input is available.

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 print>.

Fails if the socket is not connected.

=head2 method put

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

Writes the supplied string, with a C<\n> appended to it,
to the socket, thus sending it to other end of the connection.

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
