# class Socket

- Socket
- IO
- Reference
- Object

##
Included Modules

- Crystal::System::Socket
- IO::Buffered

##
Direct Known Subclasses

- IPSocket
- UNIXSocket

##
Defined in:

socket.cr
socket/address.cr
socket/addrinfo.cr
socket/common.cr
socket/server.cr

##
Constructors

- .new(family : Family, type : Type, protocol : Protocol = Protocol::IP, blocking = nil)

  Creates a socket.

  DEPRECATED parameter `#blocking` Use Socket.set_blocking instead.

- .new(fd, family : Family, type : Type, protocol : Protocol = Protocol::IP, blocking = nil)

  Creates a Socket from an existing system file descriptor or socket handle.

  DEPRECATED parameter `#blocking` Use Socket.set_blocking instead.

- .tcp(family : Family, blocking = nil) : self

  Creates a TCP socket.

  DEPRECATED parameter `#blocking` Use Socket.set_blocking instead.

- .udp(family : Family, blocking = nil) : self

  Creates an UDP socket.

  DEPRECATED parameter `#blocking` Use Socket.set_blocking instead.

- .unix(type : Type = Type::STREAM, blocking = nil) : self

  Creates an UNIX socket.

  DEPRECATED parameter `#blocking` Use Socket.set_blocking instead.

##
Class Method Summary

- .fcntl(fd, cmd, arg = 0)
- .get_blocking(fd : Handle) : Bool

  Returns whether the blocking mode of fd is blocking (true) or non blocking (false).

- .ip?(string : String)

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

  DEPRECATED Use `IPAddress.valid?` instead

- .set_blocking(fd : Handle, value : Bool)

  Changes the blocking mode of fd to be blocking (true) or non blocking (false).

##
Instance Method Summary

- #accept : Socket

  Accepts an incoming connection.

- #accept? : Socket | Nil

  Accepts an incoming connection.

- #bind(host : String, port : Int) : Nil

  Binds the socket to a local address.

- #bind(port : Int)

  Binds the socket on port to all local interfaces.

- #bind(addr : Socket::Address) : Nil

  Binds the socket to a local address.

- #blocking

  Returns whether the socket's mode is blocking (true) or non blocking (false).

  DEPRECATED Use Socket.get_blocking instead.

- #blocking=(value)

  Changes the socket's mode to blocking (true) or non blocking (false).

  DEPRECATED Use Socket.set_blocking instead.

- #broadcast=(val : Bool)
- #broadcast? : Bool
- #close_on_exec=(arg : Bool)
- #close_on_exec?
- #close_read

  Calls `shutdown(2)` with `SHUT_RD`

- #close_write

  Calls `shutdown(2)` with `SHUT_WR`

- #closed? : Bool

  Returns `true` if this `IO` is closed.

- #connect(host : String, port : Int, connect_timeout = nil) : Nil

  Connects the socket to a remote host:port.

- #connect(addr, timeout = nil) : Nil

  Connects the socket to a remote address.

- #connect(addr, timeout = nil, &)

  Tries to connect to a remote address.

- #family : Family
- #fcntl(cmd, arg = 0)
- #fd

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

- #finalize

  Finalizes the socket resource.

- #inspect(io : IO) : Nil

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

- #keepalive=(val : Bool)
- #keepalive?
- #linger
- #linger=(val : Int | Nil)

  WARNING The behavior of `SO_LINGER` is platform specific.

- #listen(backlog : Int = SOMAXCONN) : Nil

  Tells the previously bound socket to listen for incoming connections.

- #listen(backlog : Int = SOMAXCONN, &)

  Tries to listen for connections on the previously bound socket.

- #protocol : Protocol
- #read_timeout : Time::Span | Nil

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

- #read_timeout=(read_timeout : Time::Span | Nil)

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

- #read_timeout=(read_timeout : Number) : Number

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

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

- #receive(message : Bytes) : Tuple(Int32, Address)

  Receives a binary message from the previously bound address.

- #receive(max_message_size = 512) : Tuple(String, Address)

  Receives a text message from the previously bound address.

- #recv_buffer_size : Int32
- #recv_buffer_size=(val : Int32)
- #reuse_address=(val : Bool)
- #reuse_address? : Bool
- #reuse_port=(val : Bool)
- #reuse_port? : Bool
- #send(message, to addr : Address) : Int32

  Sends a message to the specified remote address.

- #send(message) : Int32

  Sends a message to a previously connected remote address.

- #send_buffer_size : Int32
- #send_buffer_size=(val : Int32)
- #sendfile(file : IO::FileDescriptor, offset : Int, count : Int) : Int64

  Writes count bytes from file to socket starting from the byte at offset, avoiding to copy data between the kernel and user spaces (zero- copy).

- #tty?

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

- #type : Type
- #write_timeout : Time::Span | Nil

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

- #write_timeout=(write_timeout : Time::Span | Nil)

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

- #write_timeout=(write_timeout : Number) : Number

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

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

### Instance methods inherited from module `Crystal::System::Socket`

__evloop_data : EventLoop::Polling::Arena::Index __evloop_data, __evloop_data=(__evloop_data : EventLoop::Polling::Arena::Index) __evloop_data=, close_volatile_fd? : Int32 | Nil close_volatile_fd?, socket_close(&)
socket_close socket_close

### Class methods inherited from module `Crystal::System::Socket`

fcntl(fd, cmd, arg = 0) fcntl, get_blocking(fd : Handle) get_blocking, sendfile(sockfd, fd, offset, count, flags) sendfile, set_blocking(fd : Handle, value : Bool) set_blocking, socket(family, type, protocol, blocking) : Handle socket, socketpair(type : ::Socket::Type, protocol : ::Socket::Protocol, blocking : Bool) : Tuple(Handle, Handle) socketpair

### Instance methods inherited from module `IO::Buffered`

buffer_size : Int32 buffer_size, buffer_size=(value) buffer_size=, close : Nil close, flush : self flush, flush_on_newline=(flush_on_newline : Bool) : Bool flush_on_newline=, flush_on_newline? : Bool flush_on_newline?, peek : Bytes peek, pos : Int64 pos, read(slice : Bytes) : Int32 read, read_buffering=(read_buffering : Bool) : Bool read_buffering=, read_buffering? : Bool read_buffering?, rewind : self rewind, sync=(sync : Bool) : Bool sync=, sync? : Bool sync?, unbuffered_close unbuffered_close, unbuffered_flush unbuffered_flush, unbuffered_read(slice : Bytes) unbuffered_read, unbuffered_rewind unbuffered_rewind, unbuffered_write(slice : Bytes) unbuffered_write, write(slice : Bytes) : Nil write

### Instance methods inherited from class `IO`

<<(obj : _) : self <<, close close, closed? : Bool closed?, each_byte(&) : Nil
each_byte each_byte, each_char(&) : Nil
each_char each_char, each_line(*args, **options, &block : String -> ) : Nil
each_line(*args, **options) each_line, encoding : String encoding, flush flush, getb_to_end : Bytes getb_to_end, gets(delimiter : Char, limit : Int, chomp = false) : String | Nil
gets(chomp : Bool = true) : String | Nil
gets(limit : Int, chomp : Bool = false) : String | Nil
gets(delimiter : Char, chomp : Bool = false) : String | Nil
gets(delimiter : String, chomp = false) : String | Nil gets, gets_to_end : String gets_to_end, peek : Bytes | Nil peek, pos pos, pos=(value) pos=, print(obj : _) : Nil
print(*objects : _) : Nil print, printf(format_string : String, args : Array | Tuple) : Nil
printf(format_string : String, *args) : Nil printf, puts(string : String) : Nil
puts(obj : _) : Nil
puts : Nil
puts(*objects : _) : Nil puts, read(slice : Bytes) read, read_at(offset, bytesize, & : IO -> ) read_at, read_byte : UInt8 | Nil read_byte, read_bytes(type, format : IO::ByteFormat = IO::ByteFormat::SystemEndian) read_bytes, read_char : Char | Nil read_char, read_fully(slice : Bytes) : Int32 read_fully, read_fully?(slice : Bytes) : Int32 | Nil read_fully?, read_greedy(slice : Bytes) : Int32 read_greedy, read_line(*args, **options) : String read_line, read_string(bytesize : Int) : String read_string, read_utf8(slice : Bytes) : Int32 read_utf8, read_utf8_byte : UInt8 | Nil read_utf8_byte, rewind rewind, seek(offset, whence : Seek = Seek::Set) seek, set_encoding(encoding : String, invalid : Symbol | Nil = nil) : Nil set_encoding, skip(bytes_count : Int) : Nil skip, skip_to_end : Nil skip_to_end, tell tell, tty? : Bool tty?, write(slice : Bytes) : Nil write, write_byte(byte : UInt8) : Nil write_byte, write_bytes(object : _, format : IO::ByteFormat = IO::ByteFormat::SystemEndian) : Nil write_bytes, write_string(slice : Bytes) : Nil write_string, write_utf8(slice : Bytes) : Nil write_utf8

### Class methods inherited from class `IO`

copy(src : IO, dst : IO, limit : Int) : Int64
copy(src : IO, dst : IO) : Int64 copy, pipe(read_blocking : Bool | Nil = nil, write_blocking : Bool | Nil = nil) : Tuple(IO::FileDescriptor, IO::FileDescriptor)
pipe(read_blocking = nil, write_blocking = nil, &) pipe, same_content?(stream1 : IO, stream2 : IO) : Bool same_content?

### Instance methods inherited from class `Reference`

==(other : self)
==(other : JSON::Any)
==(other : YAML::Any)
==(other) ==, dup dup, hash(hasher) hash, initialize initialize, inspect(io : IO) : Nil inspect, object_id : UInt64 object_id, pretty_print(pp) : Nil pretty_print, same?(other : Reference) : Bool
same?(other : Nil) same?, to_s(io : IO) : Nil to_s

### Constructor methods inherited from class `Reference`

new new, unsafe_construct(address : Pointer, *args, **opts) : self unsafe_construct

### Class methods inherited from class `Reference`

pre_initialize(address : Pointer) pre_initialize

### Instance methods inherited from class `Object`

! : Bool !, !=(other) !=, !~(other) !~, ==(other) ==, ===(other : JSON::Any)
===(other : YAML::Any)
===(other) ===, =~(other) =~, as(type : Class) as, as?(type : Class) as?, class class, dup dup, hash(hasher)
hash hash, in?(collection : Object) : Bool
in?(*values : Object) : Bool in?, inspect(io : IO) : Nil
inspect : String inspect, is_a?(type : Class) : Bool is_a?, itself itself, nil? : Bool nil?, not_nil!(message)
not_nil! not_nil!, pretty_inspect(width = 79, newline = "\n", indent = 0) : String pretty_inspect, pretty_print(pp : PrettyPrint) : Nil pretty_print, responds_to?(name : Symbol) : Bool responds_to?, tap(&) tap, to_json(io : IO) : Nil
to_json : String to_json, to_pretty_json(indent : String = " ") : String
to_pretty_json(io : IO, indent : String = " ") : Nil to_pretty_json, to_s(io : IO) : Nil
to_s : String to_s, to_yaml(io : IO) : Nil
to_yaml : String to_yaml, try(&) try, unsafe_as(type : T.class) forall T unsafe_as

### Class methods inherited from class `Object`

from_json(string_or_io : String | IO, root : String)
from_json(string_or_io : String | IO) from_json, from_yaml(string_or_io : String | IO) from_yaml

### Macros inherited from class `Object`

class_getter(*names, &block) class_getter, class_getter!(*names) class_getter!, class_getter?(*names, &block) class_getter?, class_property(*names, &block) class_property, class_property!(*names) class_property!, class_property?(*names, &block) class_property?, class_setter(*names) class_setter, def_clone def_clone, def_equals(*fields) def_equals, def_equals_and_hash(*fields) def_equals_and_hash, def_hash(*fields) def_hash, delegate(*methods, to object) delegate, forward_missing_to(delegate) forward_missing_to, getter(*names, &block) getter, getter!(*names) getter!, getter?(*names, &block) getter?, property(*names, &block) property, property!(*names) property!, property?(*names, &block) property?, setter(*names) setter

##
Constructor Detail

def self.new(family : Family, type : Type, protocol : Protocol = Protocol::IP, blocking = nil) #

Creates a socket. Consider using `TCPSocket`, `TCPServer`, `UDPSocket`, `UNIXSocket` or `UNIXServer` unless you need full control over the socket.

DEPRECATED parameter `#blocking` Use Socket.set_blocking instead.

def self.new(fd, family : Family, type : Type, protocol : Protocol = Protocol::IP, blocking = nil) #

Creates a Socket from an existing system file descriptor or socket handle.

This adopts fd into the IO system that will reconfigure it as per the event loop runtime requirements.

NOTE On Windows, the handle must have been created with `WSA_FLAG_OVERLAPPED`.

DEPRECATED parameter `#blocking` Use Socket.set_blocking instead.

def self.tcp(family : Family, blocking = nil) : self #

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

DEPRECATED parameter `#blocking` Use Socket.set_blocking instead.

def self.udp(family : Family, blocking = nil) : self #

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

DEPRECATED parameter `#blocking` Use Socket.set_blocking instead.

def self.unix(type : Type = Type::STREAM, blocking = nil) : self #

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

DEPRECATED parameter `#blocking` Use Socket.set_blocking instead.

##
Class Method Detail

def self.fcntl(fd, cmd, arg = 0) #
def self.get_blocking(fd : Handle) : Bool #

Returns whether the blocking mode of fd is blocking (true) or non blocking (false).

NOTE Only implemented on UNIX targets. Raises on Windows.

def self.ip?(string : String) #

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

DEPRECATED Use `IPAddress.valid?` instead

def self.set_blocking(fd : Handle, value : Bool) #

Changes the blocking mode of fd to be blocking (true) or non blocking (false).

##
Instance Method Detail

def accept : 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

def accept? : Socket | Nil #

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

def bind(host : String, port : Int) : Nil #

Binds the socket to a local address.

    require "socket"

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

def bind(port : Int) #

Binds the socket on port to all local interfaces.

    require "socket"

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

def bind(addr : Socket::Address) : Nil #

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)

def blocking #

Returns whether the socket's mode is blocking (true) or non blocking (false).

DEPRECATED Use Socket.get_blocking instead.

def blocking=(value) #

Changes the socket's mode to blocking (true) or non blocking (false).

WARNING The socket has been configured to behave correctly with the event loop runtime requirements. Changing the blocking mode can cause the event loop to misbehave, for example block the entire program when a fiber tries to read from this socket.

DEPRECATED Use Socket.set_blocking instead.

def broadcast=(val : Bool) #
def broadcast? : Bool #
def close_on_exec=(arg : Bool) #
def close_on_exec? #
def close_read #

Calls `shutdown(2)` with `SHUT_RD`

def close_write #

Calls `shutdown(2)` with `SHUT_WR`

def closed? : Bool #
Description copied from class IO

Returns `true` if this `IO` is closed.

`IO` defines returns `false`, but including types may override.

def connect(host : String, port : Int, connect_timeout = nil) : Nil #

Connects the socket to a remote host:port.

    require "socket"

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

def connect(addr, timeout = nil) : Nil #

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")

def connect(addr, timeout = nil, &) #

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

def family : Family #
def fcntl(cmd, arg = 0) #
def fd #

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`)

The returned system socket has been configured as per the IO system runtime requirements. If the returned socket must be in a specific mode or have a specific set of flags set, then they must be applied, even when it feels redundant, because even the same target isn't guaranteed to have the same requirements at runtime.

def finalize #

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.

def inspect(io : IO) : Nil #
Description copied from class Reference

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>

def keepalive=(val : Bool) #
def keepalive? #
def linger #
def linger=(val : Int | Nil) #

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.

def listen(backlog : Int = SOMAXCONN) : Nil #

Tells the previously bound socket to listen for incoming connections.

def listen(backlog : Int = SOMAXCONN, &) #

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

def protocol : Protocol #
def read_timeout : Time::Span | Nil #

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

def read_timeout=(read_timeout : Time::Span | Nil) #

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

def read_timeout=(read_timeout : Number) : Number #

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

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

def receive(message : Bytes) : Tuple(Int32, Address) #

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)

def receive(max_message_size = 512) : Tuple(String, Address) #

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

def recv_buffer_size : Int32 #
def recv_buffer_size=(val : Int32) #
def reuse_address=(val : Bool) #
def reuse_address? : Bool #
def reuse_port=(val : Bool) #
def reuse_port? : Bool #
def send(message, to addr : Address) : Int32 #

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)

def send(message) : Int32 #

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])

def send_buffer_size : Int32 #
def send_buffer_size=(val : Int32) #
def sendfile(file : IO::FileDescriptor, offset : Int, count : Int) : Int64 #

Writes count bytes from file to socket starting from the byte at offset, avoiding to copy data between the kernel and user spaces (zero- copy).

Returns how many bytes have actually been written. This should always be count but may be less, for example if offset + count is greater than the file size.

Doesn't directly read from file so the current file position (`IO#pos`) doesn't change.

For example, to send an entire file minus the first 44 bytes:

    require "socket"

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

    File.open("audio.wav") do |file|
      sock.sendfile(file, 44, file.info.size - 44)
      file.pos # => 0
    end

The method leverages the `#sendfile` (UNIX) and `TransmitFile` (Windows) syscalls when available for the copy to happen entirely in the kernel. The feature is emulated in user space on other targets.

@[Experimental]

def tty? #
Description copied from class IO

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

def type : Type #
def write_timeout : Time::Span | Nil #

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

def write_timeout=(write_timeout : Time::Span | Nil) #

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

def write_timeout=(write_timeout : Number) : Number #

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

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