method

advise

v2_1_10 - Show latest stable - 0 notes - Class: IO

1_8_6_287
1_8_7_72
1_8_7_330
1_9_1_378
1_9_2_180
1_9_3_125 (0)
1_9_3_392 (0)
2_1_10 (-38)
2_2_9 (0)
2_4_6 (0)
2_5_5 (0)
2_6_3 (0)
What's this?

advise(p1, p2 = v2, p3 = v3) public

Announce an intention to access data from the current file in a specific pattern. On platforms that do not support the posix_fadvise(2) system call, this method is a no-op.

advice is one of the following symbols:

:normal	No advice to give; the default assumption for an open file.
:sequential	The data will be accessed sequentially with lower offsets read before higher ones.
:random	The data will be accessed in random order.
:willneed	The data will be accessed in the near future.
:dontneed	The data will not be accessed in the near future.
:noreuse	The data will only be accessed once.

The semantics of a piece of advice are platform-dependent. See man 2 posix_fadvise for details.

“data” means the region of the current file that begins at offset and extends for len bytes. If len is 0, the region ends at the last byte of the file. By default, both offset and len are 0, meaning that the advice applies to the entire file.

If an error occurs, one of the following exceptions will be raised:

IOError	The IO stream is closed.
Errno::EBADF	The file descriptor of the current file is invalid.
Errno::EINVAL	An invalid value for advice was given.
Errno::ESPIPE	The file descriptor of the current file refers to a FIFO or pipe. (Linux raises Errno::EINVAL in this case).
TypeError	Either advice was not a Symbol, or one of the other arguments was not an Integer.
RangeError	One of the arguments given was too big/small.
This list is not exhaustive; other Errno	exceptions are also possible.

Show source

static VALUE
rb_io_advise(int argc, VALUE *argv, VALUE io)
{
    VALUE advice, offset, len;
    off_t off, l;
    rb_io_t *fptr;

    rb_scan_args(argc, argv, "12", &advice, &offset, &len);
    advice_arg_check(advice);

    io = GetWriteIO(io);
    GetOpenFile(io, fptr);

    off = NIL_P(offset) ? 0 : NUM2OFFT(offset);
    l   = NIL_P(len)    ? 0 : NUM2OFFT(len);

#ifdef HAVE_POSIX_FADVISE
    return do_io_advise(fptr, advice, off, l);
#else
    ((void)off, (void)l);       /* Ignore all hint */
    return Qnil;
#endif
}

advise

Related methods