End of Life Ruby 3.1 has reached end of life and gets no more fixes. Switch to Ruby 4.0 →
IO.read
static VALUE
rb_io_s_read(int argc, VALUE *argv, VALUE io)
{
VALUE opt, offset;
struct foreach_arg arg;
argc = rb_scan_args(argc, argv, "13:", NULL, NULL, &offset, NULL, &opt);
open_key_args(io, argc, argv, opt, &arg);
if (NIL_P(arg.io)) return Qnil;
if (!NIL_P(offset)) {
struct seek_arg sarg;
int state = 0;
sarg.io = arg.io;
sarg.offset = offset;
sarg.mode = SEEK_SET;
rb_protect(seek_before_access, (VALUE)&sarg, &state);
if (state) {
rb_io_close(arg.io);
rb_jump_tag(state);
}
if (arg.argc == 2) arg.argc = 1;
}
return rb_ensure(io_s_read, (VALUE)&arg, rb_io_close, arg.io);
}
Opens the file, optionally seeks to the given offset, then returns length bytes (defaulting to the rest of the file). read ensures the file is closed before returning.
If name starts with a pipe character ("|") and the receiver is the IO class, a subprocess is created in the same way as Kernel#open, and its output is returned. Consider to use File.read to disable the behavior of subprocess invocation.
Options
The options hash accepts the following keys:
- :encoding
-
string or encoding
Specifies the encoding of the read string.
:encodingwill be ignored iflengthis specified. SeeEncoding.aliasesfor possible encodings. - :mode
-
string or integer
Specifies the mode argument for open(). It must start with an “r”, otherwise it will cause an error. See
IO.newfor the list of possible modes. - :open_args
-
array
Specifies arguments for open() as an array. This key can not be used in combination with either
:encodingor:mode.
Examples:
File.read("testfile") #=> "This is line one\nThis is line two\nThis is line three\nAnd so on...\n" File.read("testfile", 20) #=> "This is line one\nThi" File.read("testfile", 20, 10) #=> "ne one\nThis is line " File.read("binfile", mode: "rb") #=> "\xF7\x00\x00\x0E\x12" IO.read("|ls -a") #=> ".\n..\n"...