End of Life Ruby 3.1 has reached end of life and gets no more fixes. Switch to Ruby 4.0 →
IO#advise
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
}
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
IOstream 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 anInteger. RangeError-
One of the arguments given was too big/small.
- This list is not exhaustive; other
Errno -
exceptions are also possible.