txt: ## socket.md
  role IO::Socket
  
  Network socket
  
  ```raku
  role IO::Socket { ... }
  ```
  
  `IO::Socket` contains read and write methods for sockets. It is usually used through [`IO::Socket::INET`](/type/IO/Socket/INET).
  
  # [Methods](#role_IO::Socket "go to top of document")[§](#Methods "direct link")
  
  ## [method recv](#role_IO::Socket "go to top of document")[§](#method_recv "direct link")
  
  ```raku
  method recv(IO::Socket:D: Cool $elems = Inf, :$bin)
  ```
  
  Receive a packet and return it, either as a [`Blob`](/type/Blob) if `:bin` was passed, or a [`Str`](/type/Str) if not. Receives up to `$elems` or `65535` (whichever is smaller) bytes or characters.
  
  If the socket has previously been read from in non-`:bin` mode, it's not always safe to read from it in `:bin` mode again. Depending on the decoder it's possible for the `:bin` read to skip over bytes that the decoder has read ahead messing up the order of bytes and chars. This effect can occur with the UTF-8 decoder and if the previously decoded char could still receive combiners.
  
  In Rakudo versions prior to 2024.07 mixing of binary and non-binary reads is unsupported.
  
  Fails if the socket is not connected.
  
  ## [method read](#role_IO::Socket "go to top of document")[§](#method_read "direct link")
  
  ```raku
  method read(IO::Socket:D: Int(Cool) $bytes)
  ```
  
  Reads `$bytes` bytes from the socket and returns them in a [`Blob`](/type/Blob).
  
  The same caveat of mixed binary and non-binary reads described in [method recv](#method_recv) applies.
  
  Fails if the socket is not connected.
  
  ## [routine get](#role_IO::Socket "go to top of document")[§](#routine_get "direct link")
  
  ```raku
  method get(IO::Socket:D: --> Str:D)
  ```
  
  Reads a single line of input from the socket, removing the trailing newline characters (as set by [`.nl-in`](/routine/nl-in)). Returns [`Nil`](/type/Nil), if no more input is available.
  
  Fails if the socket is not connected.
  
  ## [method print](#role_IO::Socket "go to top of document")[§](#method_print "direct link")
  
  ```raku
  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 [method write](#method_write).
  
  Fails if the socket is not connected.
  
  ## [method write](#role_IO::Socket "go to top of document")[§](#method_write "direct link")
  
  ```raku
  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 [method print](#method_print).
  
  Fails if the socket is not connected.
  
  ## [method put](#role_IO::Socket "go to top of document")[§](#method_put "direct link")
  
  ```raku
  method put(IO::Socket:D: Str(Cool) $string)
  ```
  
  Writes the supplied string, with a `\n` appended to it, to the socket, thus sending it to other end of the connection.
  
  Fails if the socket is not connected.
  
  ## [method close](#role_IO::Socket "go to top of document")[§](#method_close "direct link")
  
  ```raku
  method close(IO::Socket:D)
  ```
  
  Closes the socket.
  
  Fails if the socket is not connected.
  
  ## [method native-descriptor](#role_IO::Socket "go to top of document")[§](#method_native-descriptor "direct link")
  
  ```raku
  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 `setsockopt`.
  