IO::FileDescriptor - Crystal 1.20.3

# class IO::FileDescriptor

- IO::FileDescriptor
- IO
- Reference
- Object

##
Overview

An `IO` over a file descriptor.

##
Included Modules

- Crystal::System::FileDescriptor
- IO::Buffered

##
Direct Known Subclasses

- File

##
Defined in:

io/console.cr
io/file_descriptor.cr

##
Constructors

- .new(fd : Handle, blocking = nil, *, close_on_finalize = true)

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

  DEPRECATED parameter `#blocking` Use IO::FileDescriptor.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).

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

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

##
Macro Summary

- cooked_from_tc_mode!

  DEPRECATED

- noecho_from_tc_mode!

  DEPRECATED

- raw_from_tc_mode!

  DEPRECATED

##
Instance Method Summary

- #blocking : Bool

  Returns whether I/O operations on this file descriptor block the current thread.

  DEPRECATED Use IO::FileDescriptor.get_blocking instead.

- #blocking=(value : Bool) : Nil

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

  DEPRECATED Use IO::FileDescriptor.set_blocking instead.

- #close_on_exec=(value : Bool) : Bool
- #close_on_exec? : Bool
- #close_on_finalize=(close_on_finalize : Bool)

  Whether or not to close the file descriptor when this object is finalized.

- #close_on_finalize? : Bool

  Whether or not to close the file descriptor when this object is finalized.

- #closed? : Bool

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

- #cooked(& : self -> _)

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

- #cooked! : Nil

  Enables character processing on this `IO`.

- #echo(& : self -> _)

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

- #echo! : Nil

  Enables character echoing on this `IO`.

- #fcntl(cmd : Int, arg : Int = 0) : Int
- #fd : Handle

  Returns the raw file-descriptor handle.

- #finalize : Nil

  Finalizes the file descriptor resource.

- #flock_exclusive(blocking = true, &)
- #flock_exclusive(blocking : Bool = true) : Nil

  Places an exclusive advisory lock.

- #flock_shared(blocking = true, &)
- #flock_shared(blocking : Bool = true) : Nil

  Places a shared advisory lock.

- #flock_unlock : Nil

  Removes an existing advisory lock held by this process.

- #fsync(flush_metadata : Bool = true) : Nil

  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.

- #info : File::Info

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

- #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.

- #noecho(& : self -> _)

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

- #noecho! : Nil

  Disables character echoing on this `IO`.

- #pos=(value)

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

- #pretty_print(pp)
- #raw(& : self -> _)

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

- #raw! : Nil

  Enables raw mode on this `IO`.

- #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.

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

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

- #reopen(other : IO::FileDescriptor) : IO::FileDescriptor
- #seek(offset, whence : Seek = Seek::Set)

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

- #seek(offset, whence : Seek = Seek::Set, &)

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

- #tty? : Bool

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

- #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.

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

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

### 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 module `Crystal::System::FileDescriptor`

__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?, file_descriptor_close(&) : Nil
file_descriptor_close file_descriptor_close

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

cfmakeraw(termios) cfmakeraw, fcntl(fd, cmd, arg = 0) fcntl, from_stdio(fd) from_stdio, pread(file, buffer, offset) pread, system_info(fd) system_info, system_pipe : StaticArray(LibC::Int, 2) system_pipe, write_fully(fd : LibC::Int, pointer : Pointer, size : Int32 = 1) : Nil
write_fully(fd : LibC::Int, slice : Slice(UInt8)) : Nil write_fully

### 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(fd : Handle, blocking = nil, *, close_on_finalize = true) #

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

DEPRECATED parameter `#blocking` Use IO::FileDescriptor.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.set_blocking(fd : Handle, value : Bool) #

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

NOTE Only implemented on UNIX targets. Raises on Windows.

##
Macro Detail

macro cooked_from_tc_mode! #

DEPRECATED

macro noecho_from_tc_mode! #

DEPRECATED

macro raw_from_tc_mode! #

DEPRECATED

##
Instance Method Detail

def blocking : Bool #

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.

DEPRECATED Use IO::FileDescriptor.get_blocking instead.

def blocking=(value : Bool) : Nil #

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.

DEPRECATED Use IO::FileDescriptor.set_blocking instead.

def close_on_exec=(value : Bool) : Bool #
def close_on_exec? : Bool #
def close_on_finalize=(close_on_finalize : Bool) #

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.

def close_on_finalize? : Bool #

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.

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 cooked(& : self -> _) #

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.

def cooked! : Nil #

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.

def echo(& : self -> _) #

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.

def echo! : Nil #

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.

def fcntl(cmd : Int, arg : Int = 0) : Int #
def fd : Handle #

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.

def finalize : Nil #

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.

def flock_exclusive(blocking = true, &) #
def flock_exclusive(blocking : Bool = true) : Nil #

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.

def flock_shared(blocking = true, &) #
def flock_shared(blocking : Bool = true) : Nil #

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.

def flock_unlock : Nil #

Removes an existing advisory lock held by this process.

def fsync(flush_metadata : Bool = true) : Nil #

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.

def info : File::Info #

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.

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 noecho(& : self -> _) #

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

def noecho! : Nil #

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.

def pos=(value) #

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"

def pretty_print(pp) #
def raw(& : self -> _) #

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.

def raw! : Nil #

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.

def 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 read_timeout=(read_timeout : Time::Span | Nil) #

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

def reopen(other : IO::FileDescriptor) : IO::FileDescriptor #
def seek(offset, whence : Seek = Seek::Set) #

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"

def seek(offset, whence : Seek = Seek::Set, &) #

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

def tty? : Bool #
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 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.

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

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