Preview Ruby 4.1 is a preview. It can change before the final release. Switch to Ruby 4.0 →
IO.read
static VALUE
rb_io_s_read(int argc, VALUE *argv, VALUE io)
{
VALUE opt, offset;
rb_len_t off;
struct foreach_arg arg;
argc = rb_scan_args(argc, argv, "13:", NULL, NULL, &offset, NULL, &opt);
if (!NIL_P(offset) && (off = NUM2LEN(offset)) < 0) {
rb_raise(rb_eArgError, "negative offset %"PRIdLEN" given", off);
}
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 stream, reads and returns some or all of its content, and closes the stream; returns nil if no bytes were read.
The first argument must be a string that is the path to a file.
With only argument path given, reads in text mode and returns the entire content of the file at the given path:
File.read('t.txt') # => "First line\nSecond line\n\nFourth line\nFifth line\n" File.read('t.ja') # => "こんにちは" File.read('t.dat') # => "\xFE\xFF\x99\x90\x99\x91\x99\x92\x99\x93\x99\x94"
On Windows, text mode can terminate reading and leave bytes in the file unread when encountering certain special bytes. Consider using IO.binread if all bytes in the file should be read.
With argument length, returns length bytes if available:
File.read('t.txt', 7) # => "First l" File.read('t.ja', 7) # => "\xE3\x81\x93\xE3\x82\x93\xE3" File.read('t.dat', 7) # => "\xFE\xFF\x99\x90\x99\x91\x99"
Returns all bytes if length is larger than the files size:
File.read('t.txt', 700) # => "First line\r\nSecond line\r\n\r\nFourth line\r\nFifth line\r\n" File.read('t.ja', 700) # => "\xE3\x81\x93\xE3\x82\x93\xE3\x81\xAB\xE3\x81\xA1\xE3\x81\xAF" File.read('t.dat', 700) # => "\xFE\xFF\x99\x90\x99\x91\x99\x92\x99\x93\x99\x94"
With arguments length and offset, returns length bytes if available, beginning at the given offset:
File.read('t.txt', 10, 2) # => "rst line\r\n" File.read('t.ja', 10, 2) # => "\x93\xE3\x82\x93\xE3\x81\xAB\xE3\x81\xA1" File.read('t.dat', 10, 2) # => "\x99\x90\x99\x91\x99\x92\x99\x93\x99\x94"
Returns nil if offset is past the end of the stream:
File.read('t.txt', 10, 200) # => nil
Optional keyword arguments opts specify: