diff --git a/doc/examples/files.rdoc b/doc/examples/files.rdoc
new file mode 100644
index 0000000000..f736132770
--- /dev/null
+++ b/doc/examples/files.rdoc
@@ -0,0 +1,26 @@
+# English text with newlines.
+text = <<~EOT
+  First line
+  Second line
+
+  Fourth line
+  Fifth line
+EOT
+
+# Russian text.
+russian = "\u{442 435 441 442}" # => "тест"
+
+# Binary data.
+data = "\u9990\u9991\u9992\u9993\u9994"
+
+# Text file.
+File.write('t.txt', text)
+
+# File with Russian text.
+File.write('t.rus', russian)
+
+# File with binary data.
+f = File.new('t.dat', 'wb:UTF-16')
+f.write(data)
+f.close
+
diff --git a/doc/io_streams.rdoc b/doc/io_streams.rdoc
new file mode 100644
index 0000000000..b686d67eb5
--- /dev/null
+++ b/doc/io_streams.rdoc
@@ -0,0 +1,350 @@
+== \IO Streams
+
+Ruby supports processing data as \IO streams;
+that is, as data that may be read, re-read, written, re-written,
+and traversed via iteration.
+
+Core classes with such support include:
+
+- IO, and its derived class File.
+- {StringIO}[rdoc-ref:StringIO]: for processing a string.
+- {ARGF}[rdoc-ref:ARGF]: for processing files cited on the command line.
+
+Pre-existing stream objects that are referenced by constants include:
+
+- $stdin: read-only instance of \IO.
+- $stdout: write-only instance of \IO.
+- $stderr: read-only instance of \IO.
+- \ARGF: read-only instance of \ARGF.
+
+You can create stream objects:
+
+- \File:
+
+  - File.new: returns a new \File object.
+  - File.open: passes a new \File object to given the block.
+
+- \IO:
+
+  - IO.new: returns a new \IO object for the given integer file descriptor.
+  - IO.open: passes a new \IO object to the given block.
+  - IO.popen: returns a new \IO object that is connected to the $stdin
+    and $stdout of a newly-launched subprocess.
+  - Kernel#open: returns a new \IO object connected to a given source:
+    stream, file, or subprocess.
+
+- \StringIO:
+
+  - StringIO.new: returns a new \StringIO object.
+  - StringIO.open: passes a new \StringIO object to the given block.
+
+(You cannot create an \ARGF object, but one already exists.)
+
+=== About the Examples
+
+Many examples here use these variables:
+
+  # English text with newlines.
+  text = <<~EOT
+    First line
+    Second line
+
+    Fourth line
+    Fifth line
+  EOT
+
+  # Russian text.
+  russian = "\u{442 435 441 442}" # => "тест"
+
+  # Binary data.
+  data = "\u9990\u9991\u9992\u9993\u9994"
+
+  # Text file.
+  File.write('t.txt', text)
+
+  # File with Russian text.
+  File.write('t.rus', russian)
+
+  # File with binary data.
+  f = File.new('t.dat', 'wb:UTF-16')
+  f.write(data)
+  f.close
+
+=== Position
+
+An \IO stream has a nonnegative integer _position_,
+which is the byte offset at which the next read or write is to occur;
+the relevant methods:
+
+- +#tell+ (aliased as #pos): Returns the current position (in bytes) in the stream:
+
+    f = File.new('t.txt')
+    f.tell # => 0
+    f.gets # => "First line\n"
+    f.tell # => 12
+    f.close
+
+- +#pos=+:  Sets the position of the stream (in bytes):
+
+    f = File.new('t.txt')
+    f.tell     # => 0
+    f.pos = 20 # => 20
+    f.tell     # => 20
+    f.close
+
+- +#seek+: Sets the position of the stream to a given integer +offset+
+  (in bytes), with respect to a given constant +whence+, which is one of:
+
+  - +:CUR+ or <tt>IO::SEEK_CUR</tt>:
+    Repositions the stream to its current position plus the given +offset+:
+
+      f = File.new('t.txt')
+      f.tell            # => 0
+      f.seek(20, :CUR)  # => 0
+      f.tell            # => 20
+      f.seek(-10, :CUR) # => 0
+      f.tell            # => 10
+      f.close
+
+  - +:END+ or <tt>IO::SEEK_END</tt>:
+    Repositions the stream to its end plus the given +offset+:
+
+      f = File.new('t.txt')
+      f.tell            # => 0
+      f.seek(0, :END)   # => 0  # Repositions to stream end.
+      f.tell            # => 52
+      f.seek(-20, :END) # => 0
+      f.tell            # => 32
+      f.seek(-40, :END) # => 0
+      f.tell            # => 12
+      f.close
+
+  - +:SET+ or <tt>IO:SEEK_SET</tt>:
+    Repositions the stream to the given +offset+:
+
+      f = File.new('t.txt')
+      f.tell            # => 0
+      f.seek(20, :SET) # => 0
+      f.tell           # => 20
+      f.seek(40, :SET) # => 0
+      f.tell           # => 40
+      f.close
+
+- +#rewind+: Positions the stream to the beginning:
+
+    f = File.new('t.txt')
+    f.tell     # => 0
+    f.gets     # => "First line\n"
+    f.tell     # => 12
+    f.rewind   # => 0
+    f.tell     # => 0
+    f.close
+
+=== Lines
+
+Some reader methods in \IO streams are line-oriented;
+such a method reads one or more lines,
+which are separated by an implicit or explicit line separator.
+
+These methods are included (except as noted) in classes Kernel, IO, File,
+and {ARGF}[rdoc-ref:ARGF]:
+
+- +#each_line+ - passes each line to the block; not in Kernel:
+
+    f = File.new('t.txt')
+    f.each_line {|line| p line }
+
+  Output:
+
+    "First line\n"
+    "Second line\n"
+    "\n"
+    "Fourth line\n"
+    "Fifth line\n"
+
+  The reading may begin mid-line:
+
+    f = File.new('t.txt')
+    f.pos = 27
+    f.each_line {|line| p line }
+
+  Output:
+
+    "rth line\n"
+    "Fifth line\n"
+
+- +#gets+ - returns the next line (which may begin mid-line):
+
+    f = File.new('t.txt')
+    f.gets      # => "First line\n"
+    f.gets      # => "Second line\n"
+    f.pos = 27
+    f.gets      # => "rth line\n"
+    f.readlines # => ["Fifth line\n"]
+    f.gets      # => nil
+
+- +#readline+ - like #gets, but raises an exception at end-of-file;
+  not in StringIO.
+
+- +#readlines+ - returns all remaining lines in an array;
+  may begin mid-line:
+
+    f = File.new('t.txt')
+    f.pos = 19
+    f.readlines # => ["ine\n", "\n", "Fourth line\n", "Fifth line\n"]
+    f.readlines # => []
+
+Each of these methods may be called with:
+
+- An optional line separator, +sep+.
+- An optional line-size limit, +limit+.
+- Both +sep+ and +limit+.
+
+==== Line Separator
+
+The default line separator is the given by the global variable <tt>$/</tt>,
+whose value is by default <tt>"\n"</tt>.
+The line to be read next is all data from the current position
+to the next line separator:
+
+  f = File.new('t.txt')
+  f.gets # => "First line\n"
+  f.gets # => "Second line\n"
+  f.gets # => "\n"
+  f.gets # => "Fourth line\n"
+  f.gets # => "Fifth line\n"
+  f.close
+
+You can specify a different line separator:
+
+  f = File.new('t.txt')
+  f.gets('l')   # => "First l"
+  f.gets('li')  # => "ine\nSecond li"
+  f.gets('lin') # => "ne\n\nFourth lin"
+  f.gets        # => "e\n"
+  f.close
+
+There are two special line separators:
+
+- +nil+: The entire stream is read into a single string:
+
+    f = File.new('t.txt')
+    f.gets(nil) # => "First line\nSecond line\n\nFourth line\nFifth line\n"
+    f.close
+
+- <tt>''</tt> (the empty string): The next "paragraph" is read
+  (paragraphs being separated by two consecutive line separators):
+
+    f = File.new('t.txt')
+    f.gets('') # => "First line\nSecond line\n\n"
+    f.gets('') # => "Fourth line\nFifth line\n"
+    f.close
+
+==== Line Limit
+
+The line to be read may be further defined by an optional integer argument +limit+,
+which specifies that the number of bytes returned may not be (much) longer
+than the given +limit+;
+a multi-byte character will not be split, and so a line may be slightly longer
+than the given limit.
+
+If +limit+ is not given, the line is determined only by +sep+.
+
+  # Text with 1-byte characters.
+  File.new('t.txt') {|f| f.gets(1) }  # => "F"
+  File.new('t.txt') {|f| f.gets(2) }  # => "Fi"
+  File.new('t.txt') {|f| f.gets(3) }  # => "Fir"
+  File.new('t.txt') {|f| f.gets(4) }  # => "Firs"
+  # No more than one line.
+  File.new('t.txt') {|f| f.gets(10) } # => "First line"
+  File.new('t.txt') {|f| f.gets(11) } # => "First line\n"
+  File.new('t.txt') {|f| f.gets(12) } # => "First line\n"
+
+  # Text with 2-byte characters, which will not be split.
+  File.new('r.rus') {|f| f.gets(1).size } # => 1
+  File.new('r.rus') {|f| f.gets(2).size } # => 1
+  File.new('r.rus') {|f| f.gets(3).size } # => 2
+  File.new('r.rus') {|f| f.gets(4).size } # => 2
+
+==== Line Separator and Line Limit
+
+With arguments +sep+ and +limit+ given,
+combines the two behaviors:
+
+- Returns the next line as determined by line separator +sep+.
+- But returns no more bytes than are allowed by the limit.
+
+Example:
+
+  File.new('t.txt') {|f| f.gets('li', 20) } # => "First li"
+  File.new('t.txt') {|f| f.gets('li', 2) }  # => "Fi"
+
+==== Line Number
+
+A readable \IO stream has a _line_ _number_,
+which is the non-negative integer line number
+in the stream where the next read will occur.
+
+A new stream is initially has line number +0+.
+
+\Method IO#lineno returns the line number.
+
+Reading lines from a stream usually changes its line number:
+
+  f = File.new('t.txt', 'r')
+  f.lineno   # => 0
+  f.readline # => "This is line one.\n"
+  f.lineno   # => 1
+  f.readline # => "This is the second line.\n"
+  f.lineno   # => 2
+  f.readline # => "Here's the third line.\n"
+  f.lineno   # => 3
+  f.eof?     # => true
+  f.close
+
+Iterating over lines in a stream usually changes its line number:
+
+   f = File.new('t.txt')
+   f.each_line do |line|
+     p "position=#{f.pos} eof?=#{f.eof?} lineno=#{f.lineno}"
+   end
+   f.close
+
+Output:
+
+  "position=11 eof?=false lineno=1"
+  "position=23 eof?=false lineno=2"
+  "position=24 eof?=false lineno=3"
+  "position=36 eof?=false lineno=4"
+  "position=47 eof?=true lineno=5"
+
+==== Line Options
+
+A number of \IO methods accept optional keyword arguments
+that determine how lines in a stream are to be treated:
+
+- +:chomp+: If +true+, line separators are omitted; default is +false+.
+
+=== Open and Closed \IO Streams
+
+A new \IO stream may be open for reading, open for writing, or both.
+
+You can close a stream using these methods:
+
+- +#close+ - closes the stream for both reading and writing.
+
+- +#close_read+ (not available in \ARGF) - closes the stream for reading.
+
+- +#close_write+ (not available in \ARGF) - closes the stream for writing.
+
+You can query whether a stream is closed using these methods:
+
+- +#closed?+ - returns whether the stream is closed.
+
+=== Stream End-of-File
+
+You can query whether a stream is at end-of-file using this method:
+
+- +#eof?+ (also aliased as +#eof+) -
+  returns whether the stream is at end-of-file.
+
diff --git a/file.c b/file.c
index 862f9630df..cf67dd2aaf 100644
--- a/file.c
+++ b/file.c
@@ -6527,6 +6527,602 @@ const char ruby_null_device[] =
  *  \Class \File extends module FileTest, supporting such singleton methods
  *  as <tt>File.exist?</tt>.
  *
+ *  === About the Examples
+ *
+ *  Many examples here use these variables:
+ *
+ *    :include: doc/examples/files.rdoc
+ *
+ *  == \File Access Modes
+ *
+ *  \Methods File.new and File.open each create a \File object for a given file path.
+ *
+ *  === \String Access Modes
+ *
+ *  \Methods File.new and File.open each may take string argument +mode+, which:
+ *
+ *  - Begins with a 1- or 2-character
+ *    {read/write mode}[rdoc-ref:File@Read-2FWrite+Mode].
+ *  - May also contain a 1-character {data mode}[rdoc-ref:File@Data+Mode].
+ *  - May also contain a 1-character
+ *    {file-create mode}[rdoc-ref:File@File-Create+Mode].
+ *
+ *  ==== Read/Write Mode
+ *
+ *  The read/write +mode+ determines:
+ *
+ *  - Whether the file is to be initially truncated.
+ *
+ *  - Whether reading is allowed, and if so:
+ *
+ *    - The initial read position in the file.
+ *    - Where in the file reading can occur.
+ *
+ *  - Whether writing is allowed, and if so:
+ *
+ *    - The initial write position in the file.
+ *    - Where in the file writing can occur.
+ *
+ *  These tables summarize:
+ *
+ *    Read/Write Modes for Existing File
+ *
+ *    |------|-----------|----------|----------|----------|-----------|
+ *    | R/W  | Initial   |          | Initial  |          | Initial   |
+ *    | Mode | Truncate? |  Read    | Read Pos |  Write   | Write Pos |
+ *    |------|-----------|----------|----------|----------|-----------|
+ *    | 'r'  |    No     | Anywhere |    0     |   Error  |     -     |
+ *    | 'w'  |    Yes    |   Error  |    -     | Anywhere |     0     |
+ *    | 'a'  |    No     |   Error  |    -     | End only |    End    |
+ *    | 'r+' |    No     | Anywhere |    0     | Anywhere |     0     |
+ *    | 'w+' |    Yes    | Anywhere |    0     | Anywhere |     0     |
+ *    | 'a+' |    No     | Anywhere |   End    | End only |    End    |
+ *    |------|-----------|----------|----------|----------|-----------|
+ *
+ *    Read/Write Modes for \File To Be Created
+ *
+ *    |------|----------|----------|----------|-----------|
+ *    | R/W  |          | Initial  |          | Initial   |
+ *    | Mode |  Read    | Read Pos |  Write   | Write Pos |
+ *    |------|----------|----------|----------|-----------|
+ *    | 'w'  |   Error  |    -     | Anywhere |     0     |
+ *    | 'a'  |   Error  |    -     | End only |     0     |
+ *    | 'w+' | Anywhere |    0     | Anywhere |     0     |
+ *    | 'a+' | Anywhere |    0     | End only |    End    |
+ *    |------|----------|----------|----------|-----------|
+ *
+ *  Note that modes <tt>'r'</tt> and <tt>'r+'</tt> are not allowed
+ *  for a non-existent file (exception raised).
+ *
+ *  In the tables:
+ *
+ *  - +Anywhere+ means that methods IO#rewind, IO#pos=, and IO#seek
+ *    may be used to change the file's position,
+ *    so that allowed reading or writing may occur anywhere in the file.
+ *  - <tt>End only</tt> means that writing can occur only at end-of-file,
+ *    and that methods IO#rewind, IO#pos=, and IO#seek do not affect writing.
+ *  - +Error+ means that an exception is raised if disallowed reading or writing
+ *    is attempted.
+ *
+ *  ===== Read/Write Modes for Existing \File
+ *
+ *  - <tt>'r'</tt>:
+ *
+ *    - File is not initially truncated:
+ *
+ *        f = File.new('t.txt') # => #<File:t.txt>
+ *        f.size == 0           # => false
+ *
+ *    - File's initial read position is 0:
+ *
+ *        f.pos # => 0
+ *
+ *    - File may be read anywhere; see IO#rewind, IO#pos=, IO#seek:
+ *
+ *        f.readline # => "First line\n"
+ *        f.readline # => "Second line\n"
+ *
+ *        f.rewind
+ *        f.readline # => "First line\n"
+ *
+ *        f.pos = 1
+ *        f.readline # => "irst line\n"
+ *
+ *        f.seek(1, :CUR)
+ *        f.readline # => "econd line\n"
+ *
+ *    - Writing is not allowed:
+ *
+ *        f.write('foo') # Raises IOError.
+ *
+ *  - <tt>'w'</tt>:
+ *
+ *    - File is initially truncated:
+ *
+ *        path = 't.tmp'
+ *        File.write(path, text)
+ *        f = File.new(path, 'w')
+ *        f.size == 0 # => true
+ *
+ *    - File's initial write position is 0:
+ *
+ *        f.pos # => 0
+ *
+ *    - File may be written anywhere (even past end-of-file);
+ *      see IO#rewind, IO#pos=, IO#seek:
+ *
+ *        f.write('foo')
+ *        f.flush
+ *        File.read(path) # => "foo"
+ *        f.pos # => 3
+ *
+ *        f.write('bar')
+ *        f.flush
+ *        File.read(path) # => "foobar"
+ *        f.pos # => 6
+ *
+ *        f.rewind
+ *        f.write('baz')
+ *        f.flush
+ *        File.read(path) # => "bazbar"
+ *        f.pos # => 3
+ *
+ *        f.pos = 3
+ *        f.write('foo')
+ *        f.flush
+ *        File.read(path) # => "bazfoo"
+ *        f.pos # => 6
+ *
+ *        f.seek(-3, :END)
+ *        f.write('bam')
+ *        f.flush
+ *        File.read(path) # => "bazbam"
+ *        f.pos # => 6
+ *
+ *        f.pos = 8
+ *        f.write('bah')  # Zero padding as needed.
+ *        f.flush
+ *        File.read(path) # => "bazbam\u0000\u0000bah"
+ *        f.pos # => 11
+ *
+ *    - Reading is not allowed:
+ *
+ *        f.read # Raises IOError.
+ *
+ *  - <tt>'a'</tt>:
+ *
+ *    - File is not initially truncated:
+ *
+ *        path = 't.tmp'
+ *        File.write(path, 'foo')
+ *        f = File.new(path, 'a')
+ *        f.size == 0 # => false
+ *
+ *    - File's initial position is 0 (but is ignored):
+ *
+ *        f.pos # => 0
+ *
+ *    - File may be written only at end-of-file;
+ *      IO#rewind, IO#pos=, IO#seek do not affect writing:
+ *
+ *        f.write('bar')
+ *        f.flush
+ *        File.read(path) # => "foobar"
+ *        f.write('baz')
+ *        f.flush
+ *        File.read(path) # => "foobarbaz"
+ *
+ *        f.rewind
+ *        f.write('bat')
+ *        f.flush
+ *        File.read(path) # => "foobarbazbat"
+ *
+ *    - Reading is not allowed:
+ *
+ *        f.read # Raises IOError.
+ *
+ *  - <tt>'r+'</tt>:
+ *
+ *    - File is not initially truncated:
+ *
+ *        path = 't.tmp'
+ *        File.write(path, text)
+ *        f = File.new(path, 'r+')
+ *        f.size == 0 # => false
+ *
+ *    - File's initial read position is 0:
+ *
+ *        f.pos # => 0
+ *
+ *    - File may be read or written anywhere (even past end-of-file);
+ *      see IO#rewind, IO#pos=, IO#seek:
+ *
+ *        f.readline # => "First line\n"
+ *        f.readline # => "Second line\n"
+ *
+ *        f.rewind
+ *        f.readline # => "First line\n"
+ *
+ *        f.pos = 1
+ *        f.readline # => "irst line\n"
+ *
+ *        f.seek(1, :CUR)
+ *        f.readline # => "econd line\n"
+ *
+ *        f.rewind
+ *        f.write('WWW')
+ *        f.flush
+ *        File.read(path)
+ *        # => "WWWst line\nSecond line\nFourth line\nFifth line\n"
+ *
+ *        f.pos = 10
+ *        f.write('XXX')
+ *        f.flush
+ *        File.read(path)
+ *        # => "WWWst lineXXXecond line\nFourth line\nFifth line\n"
+ *
+ *        f.seek(-6, :END)
+ *        # => 0
+ *        f.write('YYY')
+ *        # => 3
+ *        f.flush
+ *        # => #<File:t.tmp>
+ *        File.read(path)
+ *        # => "WWWst lineXXXecond line\nFourth line\nFifth YYYe\n"
+ *
+ *        f.seek(2, :END)
+ *        f.write('ZZZ') # Zero padding as needed.
+ *        f.flush
+ *        File.read(path)
+ *        # => "WWWst lineXXXecond line\nFourth line\nFifth YYYe\n\u0000\u0000ZZZ"
+ *
+ *
+ *  - <tt>'a+'</tt>:
+ *
+ *    - File is not initially truncated:
+ *
+ *        path = 't.tmp'
+ *        File.write(path, 'foo')
+ *        f = File.new(path, 'a+')
+ *        f.size == 0 # => false
+ *
+ *    - File's initial read position is 0:
+ *
+ *        f.pos # => 0
+ *
+ *    - File may be written only at end-of-file;
+ *      IO#rewind, IO#pos=, IO#seek do not affect writing:
+ *
+ *        f.write('bar')
+ *        f.flush
+ *        File.read(path)      # => "foobar"
+ *        f.write('baz')
+ *        f.flush
+ *        File.read(path)      # => "foobarbaz"
+ *
+ *        f.rewind
+ *        f.write('bat')
+ *        f.flush
+ *        File.read(path) # => "foobarbazbat"
+ *
+ *    - File may be read anywhere; see IO#rewind, IO#pos=, IO#seek:
+ *
+ *        f.rewind
+ *        f.read # => "foobarbazbat"
+ *
+ *        f.pos = 3
+ *        f.read # => "barbazbat"
+ *
+ *        f.seek(-3, :END)
+ *        f.read # => "bat"
+ *
+ *  ===== Read/Write Modes for \File To Be Created
+ *
+ *  Note that modes <tt>'r'</tt> and <tt>'r+'</tt> are not allowed
+ *  for a non-existent file (exception raised).
+ *
+ *  - <tt>'w'</tt>:
+ *
+ *    - File's initial write position is 0:
+ *
+ *        path = 't.tmp'
+ *        FileUtils.rm_f(path)
+ *        f = File.new(path, 'w')
+ *        f.pos # => 0
+ *
+ *    - File may be written anywhere (even past end-of-file);
+ *      see IO#rewind, IO#pos=, IO#seek:
+ *
+ *        f.write('foo')
+ *        f.flush
+ *        File.read(path) # => "foo"
+ *        f.pos # => 3
+ *
+ *        f.write('bar')
+ *        f.flush
+ *        File.read(path) # => "foobar"
+ *        f.pos # => 6
+ *
+ *        f.rewind
+ *        f.write('baz')
+ *        f.flush
+ *        File.read(path) # => "bazbar"
+ *        f.pos # => 3
+ *
+ *        f.pos = 3
+ *        f.write('foo')
+ *        f.flush
+ *        File.read(path) # => "bazfoo"
+ *        f.pos # => 6
+ *
+ *        f.seek(-3, :END)
+ *        f.write('bam')
+ *        f.flush
+ *        File.read(path) # => "bazbam"
+ *        f.pos # => 6
+ *
+ *        f.pos = 8
+ *        f.write('bah')  # Zero padding as needed.
+ *        f.flush
+ *        File.read(path) # => "bazbam\u0000\u0000bah"
+ *        f.pos # => 11
+ *
+ *    - Reading is not allowed:
+ *
+ *        f.read # Raises IOError.
+ *
+ *  - <tt>'a'</tt>:
+ *
+ *    - File's initial write position is 0:
+ *
+ *        path = 't.tmp'
+ *        FileUtils.rm_f(path)
+ *        f = File.new(path, 'a')
+ *        f.pos # => 0
+ *
+ *    - Writing occurs only at end-of-file:
+ *
+ *        f.write('foo')
+ *        f.pos # => 3
+ *        f.write('bar')
+ *        f.pos # => 6
+ *        f.flush
+ *        File.read(path) # => "foobar"
+ *
+ *        f.rewind
+ *        f.write('baz')
+ *        f.flush
+ *        File.read(path) # => "foobarbaz"
+ *
+ *    - Reading is not allowed:
+ *
+ *        f.read # Raises IOError.
+ *
+ *  - <tt>'w+'</tt>:
+ *
+ *    - File's initial position is 0:
+ *
+ *        path = 't.tmp'
+ *        FileUtils.rm_f(path)
+ *        f = File.new(path, 'w+')
+ *        f.pos # => 0
+ *
+ *    - File may be written anywhere (even past end-of-file);
+ *      see IO#rewind, IO#pos=, IO#seek:
+ *
+ *        f.write('foo')
+ *        f.flush
+ *        File.read(path) # => "foo"
+ *        f.pos # => 3
+ *
+ *        f.write('bar')
+ *        f.flush
+ *        File.read(path) # => "foobar"
+ *        f.pos # => 6
+ *
+ *        f.rewind
+ *        f.write('baz')
+ *        f.flush
+ *        File.read(path) # => "bazbar"
+ *        f.pos # => 3
+ *
+ *        f.pos = 3
+ *        f.write('foo')
+ *        f.flush
+ *        File.read(path) # => "bazfoo"
+ *        f.pos # => 6
+ *
+ *        f.seek(-3, :END)
+ *        f.write('bam')
+ *        f.flush
+ *        File.read(path) # => "bazbam"
+ *        f.pos # => 6
+ *
+ *        f.pos = 8
+ *        f.write('bah')  # Zero padding as needed.
+ *        f.flush
+ *        File.read(path) # => "bazbam\u0000\u0000bah"
+ *        f.pos # => 11
+ *
+ *    - File may be read anywhere (even past end-of-file);
+ *      see IO#rewind, IO#pos=, IO#seek:
+ *
+ *        f.rewind
+ *        # => 0
+ *        f.read
+ *        # => "bazbam\u0000\u0000bah"
+ *
+ *        f.pos = 3
+ *        # => 3
+ *        f.read
+ *        # => "bam\u0000\u0000bah"
+ *
+ *        f.seek(-3, :END)
+ *        # => 0
+ *        f.read
+ *        # => "bah"
+ *
+ *  - <tt>'a+'</tt>:
+ *
+ *    - File's initial write position is 0:
+ *
+ *        path = 't.tmp'
+ *        FileUtils.rm_f(path)
+ *        f = File.new(path, 'a+')
+ *        f.pos # => 0
+ *
+ *    - Writing occurs only at end-of-file:
+ *
+ *        f.write('foo')
+ *        f.pos # => 3
+ *        f.write('bar')
+ *        f.pos # => 6
+ *        f.flush
+ *        File.read(path) # => "foobar"
+ *
+ *        f.rewind
+ *        f.write('baz')
+ *        f.flush
+ *        File.read(path) # => "foobarbaz"
+ *
+ *    - File may be read anywhere (even past end-of-file);
+ *      see IO#rewind, IO#pos=, IO#seek:
+ *
+ *        f.rewind
+ *        f.read # => "foobarbaz"
+ *
+ *        f.pos = 3
+ *        f.read # => "barbaz"
+ *
+ *        f.seek(-3, :END)
+ *        f.read # => "baz"
+ *
+ *        f.pos = 800
+ *        f.read # => ""
+ *
+ *  ==== Data Mode
+ *
+ *  To specify whether data is to be treated as text or as binary data,
+ *  either of the following may be suffixed to any of the string read/write modes
+ *  above:
+ *
+ *  - <tt>'t'</tt>: Text data; sets the default external encoding
+ *    to <tt>Encoding::UTF_8</tt>;
+ *    on Windows, enables conversion between EOL and CRLF
+ *    and enables interpreting <tt>0x1A</tt> as an end-of-file marker.
+ *  - <tt>'b'</tt>: Binary data; sets the default external encoding
+ *    to <tt>Encoding::ASCII_8BIT</tt>;
+ *    on Windows, suppresses conversion between EOL and CRLF
+ *    and disables interpreting <tt>0x1A</tt> as an end-of-file marker.
+ *
+ *  If neither is given, the stream defaults to text data.
+ *
+ *  Examples:
+ *
+ *    File.new('t.txt', 'rt')
+ *    File.new('t.dat', 'rb')
+ *
+ *  When the data mode is specified, the read/write mode may not be omitted,
+ *  and the data mode must precede the file-create mode, if given:
+ *
+ *    File.new('t.dat', 'b')   # Raises an exception.
+ *    File.new('t.dat', 'rxb') # Raises an exception.
+ *
+ *  ==== \File-Create Mode
+ *
+ *  The following may be suffixed to any writable string mode above:
+ *
+ *  - <tt>'x'</tt>: Creates the file if it does not exist;
+ *    raises an exception if the file exists.
+ *
+ *  Example:
+ *
+ *    File.new('t.tmp', 'wx')
+ *
+ *  When the file-create mode is specified, the read/write mode may not be omitted,
+ *  and the file-create mode must follow the data mode:
+ *
+ *    File.new('t.dat', 'x')   # Raises an exception.
+ *    File.new('t.dat', 'rxb') # Raises an exception.
+ *
+ *  === \Integer Access Modes
+ *
+ *  When mode is an integer it must be one or more of the following constants,
+ *  which may be combined by the bitwise OR operator <tt>|</tt>:
+ *
+ *  - +File::RDONLY+: Open for reading only.
+ *  - +File::WRONLY+: Open for writing only.
+ *  - +File::RDWR+: Open for reading and writing.
+ *  - +File::APPEND+: Open for appending only.
+ *
+ *  Examples:
+ *
+ *    File.new('t.txt', File::RDONLY)
+ *    File.new('t.tmp', File::RDWR | File::CREAT | File::EXCL)
+ *
+ *  Note: Method IO#set_encoding does not allow the mode to be specified as an integer.
+ *
+ *  === File-Create Mode Specified as an \Integer
+ *
+ *  These constants may also be ORed into the integer mode:
+ *
+ *  - +File::CREAT+: Create file if it does not exist.
+ *  - +File::EXCL+: Raise an exception if +File::CREAT+ is given and the file exists.
+ *
+ *  === Data Mode Specified as an \Integer
+ *
+ *  Data mode cannot be specified as an integer.
+ *  When the stream access mode is given as an integer,
+ *  the data mode is always text, never binary.
+ *
+ *  Note that although there is a constant +File::BINARY+,
+ *  setting its value in an integer stream mode has no effect;
+ *  this is because, as documented in File::Constants,
+ *  the +File::BINARY+ value disables line code conversion,
+ *  but does not change the external encoding.
+ *
+ *  === Encodings
+ *
+ *  Any of the string modes above may specify encodings -
+ *  either external encoding only or both external and internal encodings -
+ *  by appending one or both encoding names, separated by colons:
+ *
+ *    f = File.new('t.dat', 'rb')
+ *    f.external_encoding # => #<Encoding:ASCII-8BIT>
+ *    f.internal_encoding # => nil
+ *    f = File.new('t.dat', 'rb:UTF-16')
+ *    f.external_encoding # => #<Encoding:UTF-16 (dummy)>
+ *    f.internal_encoding # => nil
+ *    f = File.new('t.dat', 'rb:UTF-16:UTF-16')
+ *    f.external_encoding # => #<Encoding:UTF-16 (dummy)>
+ *    f.internal_encoding # => #<Encoding:UTF-16>
+ *    f.close
+ *
+ *  The numerous encoding names are available in array Encoding.name_list:
+ *
+ *    Encoding.name_list.take(3) # => ["ASCII-8BIT", "UTF-8", "US-ASCII"]
+ *
+ *  When the external encoding is set, strings read are tagged by that encoding
+ *  when reading, and strings written are converted to that encoding when
+ *  writing.
+ *
+ *  When both external and internal encodings are set,
+ *  strings read are converted from external to internal encoding,
+ *  and strings written are converted from internal to external encoding.
+ *  For further details about transcoding input and output,
+ *  see {Encodings}[rdoc-ref:io_streams.rdoc@Encodings].
+ *
+ *  If the external encoding is <tt>'BOM|UTF-8'</tt>, <tt>'BOM|UTF-16LE'</tt>
+ *  or <tt>'BOM|UTF16-BE'</tt>,
+ *  Ruby checks for a Unicode BOM in the input document
+ *  to help determine the encoding.
+ *  For UTF-16 encodings the file open mode must be binary.
+ *  If the BOM is found,
+ *  it is stripped and the external encoding from the BOM is used.
+ *
+ *  Note that the BOM-style encoding option is case insensitive,
+ *  so <tt>'bom|utf-8'</tt> is also valid.
+ *
  *  == \File Permissions
  *
  *  A \File object has _permissions_, an octal integer representing
@@ -6584,34 +7180,6 @@ const char ruby_null_device[] =
  *  may be found in module File::Constants;
  *  an array of their names is returned by <tt>File::Constants.constants</tt>.
  *
- *  == Example Files
- *
- *  Many examples here use these filenames and their corresponding files:
- *
- *  - <tt>t.txt</tt>: A text-only file that is assumed to exist via:
- *
- *      text = <<~EOT
- *        First line
- *        Second line
- *
- *        Fourth line
- *        Fifth line
- *      EOT
- *      File.write('t.txt', text)
- *
- *  - <tt>t.dat</tt>: A data file that is assumed to exist via:
- *
- *      data = "\u9990\u9991\u9992\u9993\u9994"
- *      f = File.open('t.dat', 'wb:UTF-16')
- *      f.write(data)
- *      f.close
- *
- *  - <tt>t.rus</tt>: A Russian-language text file that is assumed to exist via:
- *
- *      File.write('t.rus', "\u{442 435 441 442}")
- *
- *  - <tt>t.tmp</tt>: A file that is assumed _not_ to exist.
- *
  *  == What's Here
  *
  *  First, what's elsewhere. \Class \File: