class Socket
Included Modules
- Crystal::System::Socket
- IO::Buffered
Direct Known Subclasses
Defined in:
socket.crsocket/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. 
- 
        .new(fd, family : Family, type : Type, protocol : Protocol = Protocol::IP, blocking = nil)
        
          Creates a Socket from an existing system file descriptor or socket handle. 
- 
        .tcp(family : Family, blocking = nil) : self
        
          Creates a TCP socket. 
- 
        .unix(type : Type = Type::STREAM, blocking = nil) : self
        
          Creates an UNIX socket. 
Class Method Summary
- .fcntl(fd, cmd, arg = 0)
- 
        .ip?(string : String)
        
          Returns trueif the string represents a valid IPv4 or IPv6 address.DEPRECATED Use IPAddress.valid?instead
- 
        .udp(family : Family, blocking = nil)
        
          Creates an UDP socket. 
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). 
- 
        #blocking=(value)
        
          Changes the socket's mode to blocking (true) or non blocking (false). 
- #broadcast=(val : Bool)
- #broadcast? : Bool
- #close_on_exec=(arg : Bool)
- #close_on_exec?
- 
        #close_read
        
          Calls shutdown(2)withSHUT_RD
- 
        #close_write
        
          Calls shutdown(2)withSHUT_WR
- 
        #closed? : Bool
        
          Returns trueif thisIOis 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_LINGERis 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)
- 
        #tty?
        
          Returns trueif thisIOis associated with a terminal device (tty),falseotherwise.
- #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, 
    
  
    
      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
    flush, 
    
  
    
      flush_on_newline=(flush_on_newline)
    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)
    read_buffering=, 
    
  
    
      read_buffering? : Bool
    read_buffering?, 
    
  
    
      rewind
    rewind, 
    
  
    
      sync=(sync)
    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(&) : Nileach_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(limit : Int, chomp = false) : String | Nil
gets(delimiter : Char, limit : Int, chomp = false) : String | Nil
gets(delimiter : Char, chomp = false) : String | Nil
gets(delimiter : String, chomp = false) : String | Nil
gets(chomp = true) : 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, args : Array | Tuple) : Nil
printf(format_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_line(*args, **options) : String read_line, read_string(bytesize : Int) : String read_string, read_utf8(slice : Bytes) 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, dst, limit : Int) : Int64copy(src, dst) : Int64 copy, pipe(read_blocking = nil, write_blocking = 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, root : String)from_json(string_or_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
Creates a socket. Consider using TCPSocket, TCPServer, UDPSocket,
UNIXSocket or UNIXServer unless you need full control over the socket.
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.
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.
Class Method Detail
Returns true if the string represents a valid IPv4 or IPv6 address.
DEPRECATED  Use IPAddress.valid? instead
Instance Method Detail
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.closeAccepts 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
endBinds the socket to a local address.
require "socket"
sock = Socket.tcp(Socket::Family::INET)
sock.bind "localhost", 1234Binds the socket on port to all local interfaces.
require "socket"
sock = Socket.tcp(Socket::Family::INET6)
sock.bind 1234Binds the socket to a local address.
require "socket"
sock = Socket.udp(Socket::Family::INET)
sock.bind Socket::IPAddress.new("192.168.1.25", 80)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.
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", 80Connects 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)
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.
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.
Tells the previously bound socket to listen for incoming connections.
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.receiveSends 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? # => falseSets the number of seconds to wait when writing before raising an IO::TimeoutError.
DEPRECATED  Use #write_timeout=(Time::Span?) instead.