Creates a Socket from an existing socket file descriptor / handle.

Creates a TCP socket. Consider using TCPSocket or TCPServer unless you need full control over the socket.

Creates an UNIX socket. Consider using UNIXSocket or UNIXServer unless you need full control over the socket.

Returns true if the string represents a valid IPv4 or IPv6 address.

DEPRECATED Use IPAddress.valid? instead

Creates an UDP socket. Consider using UDPSocket unless you need full control over the socket.

Accepts an incoming connection.

Returns the client socket. Raises an IO::Error (closed stream) exception if the server is closed after invoking this method.

require "socket"

server = TCPServer.new(2202)
socket = server.accept
socket.puts Time.utc
socket.close

Accepts an incoming connection.

Returns the client Socket or nil if the server is closed after invoking this method.

require "socket"

server = TCPServer.new(2202)
if socket = server.accept?
  socket.puts Time.utc
  socket.close
end

Binds the socket to a local address.

require "socket"

sock = Socket.tcp(Socket::Family::INET)
sock.bind "localhost", 1234

Binds the socket on port to all local interfaces.

require "socket"

sock = Socket.tcp(Socket::Family::INET6)
sock.bind 1234

Binds the socket to a local address.

require "socket"

sock = Socket.udp(Socket::Family::INET)
sock.bind Socket::IPAddress.new("192.168.1.25", 80)

Calls shutdown(2) with SHUT_RD

Calls shutdown(2) with SHUT_WR

Returns true if this IO is closed.

IO defines returns false, but including types may override.

Connects the socket to a remote host:port.

require "socket"

sock = Socket.tcp(Socket::Family::INET)
sock.connect "crystal-lang.org", 80

Connects the socket to a remote address. Raises if the connection failed.

require "socket"

sock = Socket.unix
sock.connect Socket::UNIXAddress.new("/tmp/service.sock")

Tries to connect to a remote address. Yields an IO::TimeoutError or an Socket::ConnectError error if the connection failed.

Returns the handle associated with this socket from the operating system.

• on POSIX platforms, this is a file descriptor (Int32)
• on Windows, this is a SOCKET handle (LibC::SOCKET)

Finalizes the socket resource.

This involves releasing the handle to the operating system, i.e. closing it. It does not implicitly call #flush, so data waiting in the buffer may be lost. By default write buffering is disabled, though (sync? == true). It's recommended to always close the socket explicitly via #close.

This method is a no-op if the file descriptor has already been closed.

Appends a String representation of this object which includes its class name, its object address and the values of all instance variables.

class Person
  def initialize(@name : String, @age : Int32)
  end
end

Person.new("John", 32).inspect # => #<Person:0x10fd31f20 @name="John", @age=32>

WARNING The behavior of SO_LINGER is platform specific. Bad things may happen especially with nonblocking sockets. See Cross-Platform Testing of SO_LINGER by Nybek for more information.

• nil: disable SO_LINGER
• Int: enable SO_LINGER and set timeout to Int seconds
  • 0: abort on close (socket buffer is discarded and RST sent to peer). Depends on platform and whether shutdown() was called first.
  • >=1: abort after Int seconds on close. Linux and Cygwin may block on close.

Tells the previously bound socket to listen for incoming connections.

Tries to listen for connections on the previously bound socket. Yields an Socket::Error on failure.

The time to wait when reading before raising an IO::TimeoutError.

The time to wait when reading before raising an IO::TimeoutError.

Sets the number of seconds to wait when reading before raising an IO::TimeoutError.

DEPRECATED Use #read_timeout=(Time::Span?) instead.

Receives a binary message from the previously bound address.

require "socket"

server = Socket.udp(Socket::Family::INET)
server.bind("localhost", 1234)

message = Bytes.new(32)
bytes_read, client_addr = server.receive(message)

Receives a text message from the previously bound address.

require "socket"

server = Socket.udp(Socket::Family::INET)
server.bind("localhost", 1234)

message, client_addr = server.receive

Sends a message to the specified remote address. Returns the number of bytes sent. Does not guarantee that the entire message is sent. That's only the case when the return value is equivalent to message.bytesize. #write ensures the entire message is sent but it requires an established connection.

require "socket"

server = Socket::IPAddress.new("10.0.3.1", 2022)
sock = Socket.udp(Socket::Family::INET)
sock.connect("example.com", 2000)
sock.send("text query", to: server)

Sends a message to a previously connected remote address. Returns the number of bytes sent. Does not guarantee that the entire message is sent. That's only the case when the return value is equivalent to message.bytesize. #write ensures the entire message is sent.

require "socket"

sock = Socket.udp(Socket::Family::INET)
sock.connect("example.com", 2000)
sock.send("text message")

sock = Socket.unix(Socket::Type::DGRAM)
sock.connect Socket::UNIXAddress.new("/tmp/service.sock")
sock.send(Bytes[0])

Returns true if this IO is associated with a terminal device (tty), false otherwise.

IO returns false, but including types may override.

STDIN.tty?          # => true
IO::Memory.new.tty? # => false

Sets the time to wait when writing before raising an IO::TimeoutError.

Sets the time to wait when writing before raising an IO::TimeoutError.

Sets the number of seconds to wait when writing before raising an IO::TimeoutError.

DEPRECATED Use #write_timeout=(Time::Span?) instead.