IO::FileDescriptor

Creates an IO::FileDescriptor from an existing system file descriptor or handle.

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

NOTE: On Windows, the handle should have been created with FILE_FLAG_OVERLAPPED.

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

NOTE: Only implemented on UNIX targets. Raises on Windows.

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

NOTE: Only implemented on UNIX targets. Raises on Windows.

Returns whether I/O operations on this file descriptor block the current thread. If false, operations might opt to suspend the current fiber instead.

This might be different from the internal file descriptor. For example, when STDIN is a terminal on Windows, this returns false since the underlying blocking reads are done on a completely separate thread.

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

WARNING: The file descriptor 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 file descriptor.

Whether or not to close the file descriptor when this object is finalized. Disabling this is useful in order to create an IO wrapper over a file descriptor returned from a C API that keeps ownership of the descriptor. Do note that, if the fd is closed by its owner at any point, any IO operations will then fail.

Whether or not to close the file descriptor when this object is finalized. Disabling this is useful in order to create an IO wrapper over a file descriptor returned from a C API that keeps ownership of the descriptor. Do note that, if the fd is closed by its owner at any point, any IO operations will then fail.

Returns true if this IO is closed.

IO defines returns false, but including types may override.

Yields self to the given block, enables character processing for the duration of the block, and returns the block's value.

The so called cooked mode is the standard behavior of a terminal, doing line wise editing by the terminal and only sending the input to the program on a newline.

Raises IO::Error if this IO is not a terminal device.

Enables character processing on this IO.

The so called cooked mode is the standard behavior of a terminal, doing line wise editing by the terminal and only sending the input to the program on a newline.

Raises IO::Error if this IO is not a terminal device.

Yields self to the given block, enables character echoing for the duration of the block, and returns the block's value.

This causes user input to be displayed as they are entered on the terminal.

Raises IO::Error if this IO is not a terminal device.

Enables character echoing on this IO.

This causes user input to be displayed as they are entered on the terminal.

Raises IO::Error if this IO is not a terminal device.

Returns the raw file-descriptor handle. Its type is platform-specific.

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

Finalizes the file descriptor 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. It's recommended to always close the file descriptor explicitly via #close (or implicitly using the .open constructor).

Resource release can be disabled with close_on_finalize = false.

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

Places an exclusive advisory lock. Only one process may hold an exclusive lock for a given file descriptor at a given time. IO::Error is raised if blocking is set to false and any existing lock is set.

Places a shared advisory lock. More than one process may hold a shared lock for a given file descriptor at a given time. IO::Error is raised if blocking is set to false and an existing exclusive lock is set.

Removes an existing advisory lock held by this process.

Flushes all data written to this File Descriptor to the disk device so that all changed information can be retrieved even if the system crashes or is rebooted. The call blocks until the device reports that the transfer has completed. To reduce disk activity the flush_metadata parameter can be set to false, then the syscall fdatasync will be used and only data required for subsequent data retrieval is flushed. Metadata such as modified time and access time is not written.

NOTE: Metadata is flushed even when flush_metadata is false on Windows and DragonFly BSD.

Returns a File::Info object for this file descriptor, or raises IO::Error in case of an error.

Certain fields like the file size may not be updated until an explicit flush.

File.write("testfile", "abc")

file = File.new("testfile", "a")
file.info.size # => 3
file << "defgh"
file.info.size # => 3
file.flush
file.info.size # => 8

Use File.info if the file is not open and a path to the file is available.

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>

Yields self to the given block, disables character echoing for the duration of the block, and returns the block's value.

This will prevent displaying back to the user what they enter on the terminal.

Raises IO::Error if this IO is not a terminal device.

print "Enter password: "
password = STDIN.noecho &.gets.try &.chomp
puts

Disables character echoing on this IO.

This will prevent displaying back to the user what they enter on the terminal.

Raises IO::Error if this IO is not a terminal device.

Sets the current position (in bytes) in this IO.

File.write("testfile", "hello")

file = File.new("testfile")
file.pos = 3
file.gets_to_end # => "lo"

Yields self to the given block, enables raw mode for the duration of the block, and returns the block's value.

In raw mode every keypress is directly sent to the program, no interpretation is done by the terminal. On Windows, this also enables ANSI input escape sequences.

Raises IO::Error if this IO is not a terminal device.

Enables raw mode on this IO.

In raw mode every keypress is directly sent to the program, no interpretation is done by the terminal. On Windows, this also enables ANSI input escape sequences.

Raises IO::Error if this IO is not a terminal device.

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.

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

Seeks to a given offset (in bytes) according to the whence argument. Returns self.

File.write("testfile", "abc")

file = File.new("testfile")
file.gets(3) # => "abc"
file.seek(1, IO::Seek::Set)
file.gets(2) # => "bc"
file.seek(-1, IO::Seek::Current)
file.gets(1) # => "c"

Same as seek but yields to the block after seeking and eventually seeks back to the original position when the block returns.

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 number of seconds to wait when writing before raising an IO::TimeoutError.

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

DEPRECATED

DEPRECATED

DEPRECATED