read

        # IO.read

(from ruby core)
---
    IO.read(name, [length [, offset]] [, opt])   -> string
    File.read(name, [length [, offset]] [, opt]) -> string

---

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.  `:encoding` will be
    ignored if `length` is specified.  See Encoding.aliases for 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.new for 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 `:encoding` or `: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"...


(from ruby core)
---
    read(maxlen = nil)             -> string or nil
    read(maxlen = nil, out_string) -> out_string or nil

---

Reads bytes from the stream (in binary mode):

*   If `maxlen` is `nil`, reads all bytes.
*   Otherwise reads `maxlen` bytes, if available.
*   Otherwise reads all bytes.


Returns a string (either a new string or the given `out_string`)
containing the bytes read. The encoding of the string depends on both
`maxLen` and `out_string`:

*   `maxlen` is `nil`: uses internal encoding of `self` (regardless of
    whether `out_string` was given).
*   `maxlen` not `nil`:

    *   `out_string` given: encoding of `out_string` not modified.
    *   `out_string` not given: ASCII-8BIT is used.



**Without Argument `out_string`**

When argument `out_string` is omitted, the returned value is a new
string:

    f = File.new('t.txt')
    f.read
    # => "This is line one.\nThis is the second line.\nThis is the third line.\n"
    f.rewind
    f.read(40)      # => "This is line one.\r\nThis is the second li"
    f.read(40)      # => "ne.\r\nThis is the third line.\r\n"
    f.read(40)      # => nil

If `maxlen` is zero, returns an empty string.

** With Argument `out_string`**

When argument `out_string` is given, the returned value is `out_string`,
whose content is replaced:

    f = File.new('t.txt')
    s = 'foo'      # => "foo"
    f.read(nil, s) # => "This is line one.\nThis is the second line.\nThis is the third line.\n"
    s              # => "This is line one.\nThis is the second line.\nThis is the third line.\n"
    f.rewind
    s = 'bar'
    f.read(40, s)  # => "This is line one.\r\nThis is the second li"
    s              # => "This is line one.\r\nThis is the second li"
    s = 'baz'
    f.read(40, s)  # => "ne.\r\nThis is the third line.\r\n"
    s              # => "ne.\r\nThis is the third line.\r\n"
    s = 'bat'
    f.read(40, s)  # => nil
    s              # => ""

Note that this method behaves like the fread() function in C. This means
it retries to invoke read(2) system calls to read data with the
specified maxlen (or until EOF).

This behavior is preserved even if the stream is in non-blocking mode.
(This method is non-blocking-flag insensitive as other methods.)

If you need the behavior like a single read(2) system call, consider
#readpartial, #read_nonblock, and #sysread.