IO#pread

pread(maxlen, offset) → string

pread(maxlen, offset, out_string) → string

static VALUE
rb_io_pread(int argc, VALUE *argv, VALUE io)
{
    VALUE len, offset, str;
    rb_io_t *fptr;
    ssize_t n;
    struct prdwr_internal_arg arg = {.io = io};
    int shrinkable;

    rb_scan_args(argc, argv, "21", &len, &offset, &str);
    arg.count = NUM2SIZET(len);
    arg.offset = NUM2OFFT(offset);

    shrinkable = io_setstrbuf(&str, (long)arg.count);
    if (arg.count == 0) return str;
    arg.buf = RSTRING_PTR(str);

    GetOpenFile(io, fptr);
    rb_io_check_byte_readable(fptr);

    arg.fd = fptr->fd;
    rb_io_check_closed(fptr);

    rb_str_locktmp(str);
    n = (ssize_t)rb_ensure(pread_internal_call, (VALUE)&arg, rb_str_unlocktmp, str);

    if (n < 0) {
        rb_sys_fail_path(fptr->pathv);
    }
    io_set_read_length(str, n, shrinkable);
    if (n == 0 && arg.count > 0) {
        rb_eof_error();
    }

    return str;
}

Behaves like IO#readpartial, except that it:

Reads at the given offset (in bytes).
Disregards, and does not modify, the stream’s position (see Position).
Bypasses any user space buffering in the stream.

Because this method does not disturb the stream’s state (its position, in particular), pread allows multiple threads and processes to use the same IO object for reading at various offsets.

Example

f = File.open('t.txt')
f.read # => "First line\nSecond line\n\nFourth line\nFifth line\n"
f.pos  # => 52
# Read 12 bytes at offset 0.
f.pread(12, 0) # => "First line\n"
# Read 9 bytes at offset 8.
f.pread(9, 8)  # => "ne\nSecon"
f.close

Not available on some platforms.

See also #pos= #pressed? #pos #print also in 4.1 · 4.0 · 3.4 · 3.2 · 3.1 · 3.0

‹ prev#pos= next ›#pressed?