* io.c (rb_io_popen): update the document for the first argument and

  exceptions.

* process.c (rb_f_exec, rb_f_system): update the document for
  exceptions.


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@6540 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

1 files changed, 217 insertions, 209 deletions

diff --git a/io.c b/io.c
index f71ef8f0b6..14443da712 100644
--- a/io.c
+++ b/io.c
@@ -431,17 +431,17 @@ rb_io_fwrite(ptr, len, f)
 /*
  *  call-seq:
  *     ios.write(string)    => integer
- *  
+ *
  *  Writes the given string to <em>ios</em>. The stream must be opened
  *  for writing. If the argument is not a string, it will be converted
  *  to a string using <code>to_s</code>. Returns the number of bytes
  *  written.
- *     
+ *
  *     count = $stdout.write( "This is a test\n" )
  *     puts "That was #{count} bytes of data"
- *     
+ *
  *  <em>produces:</em>
- *     
+ *
  *     This is a test
  *     That was 15 bytes of data
  */
@@ -491,15 +491,15 @@ rb_io_write(io, str)
 /*
  *  call-seq:
  *     ios << obj     => ios
- *  
+ *
  *  String Output---Writes <i>obj</i> to <em>ios</em>.
  *  <i>obj</i> will be converted to a string using
  *  <code>to_s</code>.
- *     
+ *
  *     $stdout << "Hello " << "world!\n"
- *     
+ *
  *  <em>produces:</em>
- *     
+ *
  *     Hello world!
  */
 
@@ -515,16 +515,16 @@ rb_io_addstr(io, str)
 /*
  *  call-seq:
  *     ios.flush    => ios
- *  
+ *
  *  Flushes any buffered data within <em>ios</em> to the underlying
  *  operating system (note that this is Ruby internal buffering only;
  *  the OS may buffer the data as well).
- *     
+ *
  *     $stdout.print "no newline"
  *     $stdout.flush
- *     
+ *
  *  <em>produces:</em>
- *     
+ *
  *     no newline
  */
 
@@ -549,9 +549,9 @@ rb_io_flush(io)
  *  call-seq:
  *     ios.pos     => integer
  *     ios.tell    => integer
- *  
+ *
  *  Returns the current offset (in bytes) of <em>ios</em>.
- *     
+ *
  *     f = File.new("testfile")
  *     f.pos    #=> 0
  *     f.gets   #=> "This is line one\n"
@@ -590,19 +590,19 @@ rb_io_seek(io, offset, whence)
 /*
  *  call-seq:
  *     ios.seek(amount, whence=SEEK_SET) -> 0
- *  
+ *
  *  Seeks to a given offset <i>anInteger</i> in the stream according to
  *  the value of <i>whence</i>:
  *
  *    IO::SEEK_CUR  | Seeks to _amount_ plus current position
  *    --------------+----------------------------------------------------
- *    IO::SEEK_END  | Seeks to _amount_ plus end of stream (you probably 
+ *    IO::SEEK_END  | Seeks to _amount_ plus end of stream (you probably
  *                  | want a negative value for _amount_)
  *    --------------+----------------------------------------------------
  *    IO::SEEK_SET  | Seeks to the absolute location given by _amount_
  *
  *  Example:
- *     
+ *
  *     f = File.new("testfile")
  *     f.seek(-13, IO::SEEK_END)   #=> 0
  *     f.readline                  #=> "And so on...\n"
@@ -627,9 +627,9 @@ rb_io_seek_m(argc, argv, io)
 /*
  *  call-seq:
  *     ios.pos = integer    => 0
- *  
+ *
  *  Seeks to the given position (in bytes) in <em>ios</em>.
- *     
+ *
  *     f = File.new("testfile")
  *     f.pos = 17
  *     f.gets   #=> "This is line two\n"
@@ -653,10 +653,10 @@ rb_io_set_pos(io, offset)
 /*
  *  call-seq:
  *     ios.rewind    => 0
- *  
+ *
  *  Positions <em>ios</em> to the beginning of input, resetting
  *  <code>lineno</code> to zero.
- *     
+ *
  *     f = File.new("testfile")
  *     f.readline   #=> "This is line one\n"
  *     f.rewind     #=> 0
@@ -685,10 +685,10 @@ rb_io_rewind(io)
  *  call-seq:
  *     ios.eof     => true or false
  *     ios.eof?    => true or false
- *  
+ *
  *  Returns true if <em>ios</em> is at end of file. The stream must be
  *  opened for reading or an <code>IOError</code> will be raised.
- *     
+ *
  *     f = File.new("testfile")
  *     dummy = f.readlines
  *     f.eof   #=> true
@@ -722,12 +722,12 @@ rb_io_eof(io)
 /*
  *  call-seq:
  *     ios.sync    => true or false
- *  
+ *
  *  Returns the current ``sync mode'' of <em>ios</em>. When sync mode is
  *  true, all output is immediately flushed to the underlying operating
  *  system and is not buffered by Ruby internally. See also
  *  <code>IO#fsync</code>.
- *     
+ *
  *     f = File.new("testfile")
  *     f.sync   #=> false
  */
@@ -745,15 +745,15 @@ rb_io_sync(io)
 /*
  *  call-seq:
  *     ios.sync = boolean   => boolean
- *  
+ *
  *  Sets the ``sync mode'' to <code>true</code> or <code>false</code>.
  *  When sync mode is true, all output is immediately flushed to the
  *  underlying operating system and is not buffered internally. Returns
  *  the new state. See also <code>IO#fsync</code>.
- *     
+ *
  *     f = File.new("testfile")
  *     f.sync = true
- *     
+ *
  *  <em>(produces no output)</em>
  */
 
@@ -776,7 +776,7 @@ rb_io_set_sync(io, mode)
 /*
  *  call-seq:
  *     ios.fsync   => 0 or nil
- *  
+ *
  *  Immediately writes all buffered data in <em>ios</em> to disk.
  *  Returns <code>nil</code> if the underlying operating system does not
  *  support <em>fsync(2)</em>. Note that <code>fsync</code> differs from
@@ -810,10 +810,10 @@ rb_io_fsync(io)
  *  call-seq:
  *     ios.fileno    => fixnum
  *     ios.to_i      => fixnum
- *  
+ *
  *  Returns an integer representing the numeric file descriptor for
  *  <em>ios</em>.
- *     
+ *
  *     $stdin.fileno    #=> 0
  *     $stdout.fileno   #=> 1
  */
@@ -834,19 +834,19 @@ rb_io_fileno(io)
 /*
  *  call-seq:
  *     ios.pid    => fixnum
- *  
+ *
  *  Returns the process ID of a child process associated with
  *  <em>ios</em>. This will be set by <code>IO::popen</code>.
- *     
+ *
  *     pipe = IO.popen("-")
  *     if pipe
  *       $stderr.puts "In parent, child pid is #{pipe.pid}"
  *     else
  *       $stderr.puts "In child, pid is #{$$}"
  *     end
- *     
+ *
  *  <em>produces:</em>
- *     
+ *
  *     In child, pid is 26209
  *     In parent, child pid is 26209
  */
@@ -895,7 +895,7 @@ rb_io_inspect(obj)
 /*
  *  call-seq:
  *     ios.to_io -> ios
- *  
+ *
  *  Returns <em>ios</em>.
  */
 
@@ -1043,13 +1043,13 @@ read_all(fptr, siz, str)
 /*
  *  call-seq:
  *     ios.read([integer [, buffer]])    => string, buffer, or nil
- *  
+ *
  *  Reads at most <i>integer</i> bytes from the I/O stream, or to the
  *  end of file if <i>integer</i> is omitted or is <code>nil</code>.
  *  If the optional <i>buffer</i> argument is present, it must reference
  *  a String, which will receive the data. Returns <code>nil</code>
  *  if called at end of file.
- *     
+ *
  *     f = File.new("testfile")
  *     f.read(16)   #=> "This is line one"
  */
@@ -1335,7 +1335,7 @@ rb_io_gets(io)
 /*
  *  call-seq:
  *     ios.gets(sep_string=$/)   => string or nil
- *  
+ *
  *  Reads the next ``line'' from the I/O stream; lines are separated by
  *  <i>sep_string</i>. A separator of <code>nil</code> reads the entire
  *  contents, and a zero-length separator reads the input a paragraph at
@@ -1344,7 +1344,7 @@ rb_io_gets(io)
  *  will be raised. The line read in will be returned and also assigned
  *  to <code>$_</code>. Returns <code>nil</code> if called at end of
  *  file.
- *     
+ *
  *     File.new("testfile").gets   #=> "This is line one\n"
  *     $_                          #=> "This is line one\n"
  */
@@ -1374,14 +1374,14 @@ rb_io_gets_m(argc, argv, io)
 /*
  *  call-seq:
  *     ios.lineno    => integer
- *  
+ *
  *  Returns the current line number in <em>ios</em>. The stream must be
  *  opened for reading. <code>lineno</code> counts the number of times
  *  <code>gets</code> is called, rather than the number of newlines
  *  encountered. The two values will differ if <code>gets</code> is
  *  called with a separator other than newline. See also the
  *  <code>$.</code> variable.
- *     
+ *
  *     f = File.new("testfile")
  *     f.lineno   #=> 0
  *     f.gets     #=> "This is line one\n"
@@ -1404,10 +1404,10 @@ rb_io_lineno(io)
 /*
  *  call-seq:
  *     ios.lineno = integer    => integer
- *  
+ *
  *  Manually sets the current line number to the given value.
  *  <code>$.</code> is updated only on the next read.
- *     
+ *
  *     f = File.new("testfile")
  *     f.gets                     #=> "This is line one\n"
  *     $.                         #=> 1
@@ -1458,7 +1458,7 @@ argf_lineno()
 /*
  *  call-seq:
  *     ios.readline(sep_string=$/)   => string
- *  
+ *
  *  Reads a line as with <code>IO#gets</code>, but raises an
  *  <code>EOFError</code> on end of file.
  */
@@ -1480,14 +1480,14 @@ rb_io_readline(argc, argv, io)
 /*
  *  call-seq:
  *     ios.readlines(sep_string=$/)  =>   array
- *  
+ *
  *  Reads all of the lines in <em>ios</em>, and returns them in
  *  <i>anArray</i>. Lines are separated by the optional
  *  <i>sep_string</i>. If <i>set_string</i> is <code>nil</code>, the
  *  rest of the stream is returned as a single record.
  *  The stream must be opened for reading or an
  *  <code>IOError</code> will be raised.
- *     
+ *
  *     f = File.new("testfile")
  *     f.readlines[0]   #=> "This is line one\n"
  */
@@ -1520,16 +1520,16 @@ rb_io_readlines(argc, argv, io)
  *  call-seq:
  *     ios.each(sep_string=$/)      {|line| block }  => ios
  *     ios.each_line(sep_string=$/) {|line| block }  => ios
- *  
+ *
  *  Executes the block for every line in <em>ios</em>, where lines are
  *  separated by <i>sep_string</i>. <em>ios</em> must be opened for
  *  reading or an <code>IOError</code> will be raised.
- *     
+ *
  *     f = File.new("testfile")
  *     f.each {|line| puts "#{f.lineno}: #{line}" }
- *     
+ *
  *  <em>produces:</em>
- *     
+ *
  *     1: This is line one
  *     2: This is line two
  *     3: This is line three
@@ -1562,11 +1562,11 @@ rb_io_each_line(argc, argv, io)
 /*
  *  call-seq:
  *     ios.each_byte {|byte| block }  => ios
- *  
+ *
  *  Calls the given block once for each byte (0..255) in <em>ios</em>,
  *  passing the byte as an argument. The stream must be opened for
  *  reading or an <code>IOError</code> will be raised.
- *     
+ *
  *     f = File.new("testfile")
  *     checksum = 0
  *     f.each_byte {|x| checksum ^= x }   #=> #<File:testfile>
@@ -1608,10 +1608,10 @@ rb_io_each_byte(io)
 /*
  *  call-seq:
  *     ios.getc   => fixnum or nil
- *  
+ *
  *  Gets the next 8-bit byte (0..255) from <em>ios</em>. Returns
  *  <code>nil</code> if called at end of file.
- *     
+ *
  *     f = File.new("testfile")
  *     f.getc   #=> 84
  *     f.getc   #=> 104
@@ -1666,7 +1666,7 @@ rb_getc(f)
 /*
  *  call-seq:
  *     ios.readchar   => fixnum
- *  
+ *
  *  Reads a character as with <code>IO#getc</code>, but raises an
  *  <code>EOFError</code> on end of file.
  */
@@ -1686,13 +1686,13 @@ rb_io_readchar(io)
 /*
  *  call-seq:
  *     ios.ungetc(integer)   => nil
- *  
+ *
  *  Pushes back one character (passed as a parameter) onto <em>ios</em>,
  *  such that a subsequent buffered read will return it. Only one character
  *  may be pushed back before a subsequent read operation (that is,
  *  you will be able to read only the last of several characters that have been pushed
  *  back). Has no effect with unbuffered reads (such as <code>IO#sysread</code>).
- *     
+ *
  *     f = File.new("testfile")   #=> #<File:testfile>
  *     c = f.getc                 #=> 84
  *     f.ungetc(c)                #=> nil
@@ -1721,10 +1721,10 @@ rb_io_ungetc(io, c)
  *  call-seq:
  *     ios.isatty   => true or false
  *     ios.tty?     => true or false
- *  
+ *
  *  Returns <code>true</code> if <em>ios</em> is associated with a
  *  terminal device (tty), <code>false</code> otherwise.
- *     
+ *
  *     File.new("testfile").isatty   #=> false
  *     File.new("/dev/tty").isatty   #=> true
  */
@@ -1842,7 +1842,7 @@ rb_io_close(io)
 /*
  *  call-seq:
  *     ios.close   => nil
- *  
+ *
  *  Closes <em>ios</em> and flushes any pending writes to the operating
  *  system. The stream is unavailable for any further data operations;
  *  an <code>IOError</code> is raised if such an attempt is made. I/O
@@ -1872,11 +1872,11 @@ io_close(io)
 /*
  *  call-seq:
  *     ios.closed?    => true or false
- *  
+ *
  *  Returns <code>true</code> if <em>ios</em> is completely closed (for
  *  duplex streams, both reader and writer), <code>false</code>
  *  otherwise.
- *     
+ *
  *     f = File.new("testfile")
  *     f.close         #=> nil
  *     f.closed?       #=> true
@@ -1901,17 +1901,17 @@ rb_io_closed(io)
 /*
  *  call-seq:
  *     ios.close_read    => nil
- *  
+ *
  *  Closes the read end of a duplex I/O stream (i.e., one that contains
  *  both a read and a write stream, such as a pipe). Will raise an
  *  <code>IOError</code> if the stream is not duplexed.
- *     
+ *
  *     f = IO.popen("/bin/sh","r+")
  *     f.close_read
  *     f.readlines
- *     
+ *
  *  <em>produces:</em>
- *     
+ *
  *     prog.rb:3:in `readlines': not opened for reading (IOError)
  *     	from prog.rb:3
  */
@@ -1945,17 +1945,17 @@ rb_io_close_read(io)
 /*
  *  call-seq:
  *     ios.close_write   => nil
- *  
+ *
  *  Closes the write end of a duplex I/O stream (i.e., one that contains
  *  both a read and a write stream, such as a pipe). Will raise an
  *  <code>IOError</code> if the stream is not duplexed.
- *     
+ *
  *     f = IO.popen("/bin/sh","r+")
  *     f.close_write
  *     f.print "nowhere"
- *     
+ *
  *  <em>produces:</em>
- *     
+ *
  *     prog.rb:3:in `write': not opened for writing (IOError)
  *     	from prog.rb:3:in `print'
  *     	from prog.rb:3
@@ -1989,11 +1989,11 @@ rb_io_close_write(io)
 /*
  *  call-seq:
  *     ios.sysseek(offset, whence=SEEK_SET)   => integer
- *  
+ *
  *  Seeks to a given <i>offset</i> in the stream according to the value
  *  of <i>whence</i> (see <code>IO#seek</code> for values of
  *  <i>whence</i>). Returns the new offset into the file.
- *     
+ *
  *     f = File.new("testfile")
  *     f.sysseek(-13, IO::SEEK_END)   #=> 53
  *     f.sysread(10)                  #=> "And so on."
@@ -2031,12 +2031,12 @@ rb_io_sysseek(argc, argv, io)
 /*
  *  call-seq:
  *     ios.syswrite(string )   => integer
- *  
+ *
  *  Writes the given string to <em>ios</em> using a low-level write.
  *  Returns the number of bytes written. Do not mix with other methods
  *  that write to <em>ios</em> or you may get unpredictable results.
  *  Raises <code>SystemCallError</code> on error.
- *     
+ *
  *     f = File.new("out", "w")
  *     f.syswrite("ABCDEF")   #=> 6
  */
@@ -2073,13 +2073,13 @@ rb_io_syswrite(io, str)
 /*
  *  call-seq:
  *     ios.sysread(integer )    => string
- *  
+ *
  *  Reads <i>integer</i> bytes from <em>ios</em> using a low-level
  *  read and returns them as a string. Do not mix with other methods
  *  that read from <em>ios</em> or you may get unpredictable results.
  *  Raises <code>SystemCallError</code> on error and
  *  <code>EOFError</code> at end of file.
- *     
+ *
  *     f = File.new("testfile")
  *     f.sysread(16)   #=> "This is line one"
  */
@@ -2137,7 +2137,7 @@ rb_io_sysread(argc, argv, io)
 /*
  *  call-seq:
  *     ios.binmode    => ios
- *  
+ *
  *  Puts <em>ios</em> into binary mode. This is useful only in
  *  MS-DOS/Windows environments. Once a stream is in binary mode, it
  *  cannot be reset to nonbinary mode.
@@ -2798,43 +2798,51 @@ rb_io_popen(str, argc, argv, klass)
 
 /*
  *  call-seq:
- *     IO.popen(cmd_string, mode="r" )               => io
- *     IO.popen(cmd_string, mode="r" ) {|io| block } => obj
- *  
- *  Runs the specified command string as a subprocess; the subprocess's
+ *     IO.popen(cmd, mode="r")               => io
+ *     IO.popen(cmd, mode="r") {|io| block } => obj
+ *
+ *  Runs the specified command as a subprocess; the subprocess's
  *  standard input and output will be connected to the returned
- *  <code>IO</code> object. If <i>cmd_string</i> starts with a
+ *  <code>IO</code> object.  If _cmd_ is a +String+
  *  ``<code>-</code>'', then a new instance of Ruby is started as the
- *  subprocess. The default mode for the new file object is ``r'', but
- *  <i>mode</i> may be set to any of the modes listed in the description
- *  for class IO.
- *     
+ *  subprocess.  If <i>cmd</i> is an +Array+ of +String+, then it will
+ *  be used as the subprocess's +argv+ bypassing a shell.  The default
+ *  mode for the new file object is ``r'', but <i>mode</i> may be set
+ *  to any of the modes listed in the description for class IO.
+ *
+ *  Raises exceptions which <code>IO::pipe</code> and
+ *  <code>Kernel::system</code> raise.
+ *
  *  If a block is given, Ruby will run the command as a child connected
  *  to Ruby with a pipe. Ruby's end of the pipe will be passed as a
  *  parameter to the block. In this case <code>IO::popen</code> returns
  *  the value of the block.
- *     
- *  If a block is given with a <i>cmd_string</i> of ``<code>-</code>'',
+ *
+ *  If a block is given with a _cmd_ of ``<code>-</code>'',
  *  the block will be run in two separate processes: once in the parent,
  *  and once in a child. The parent process will be passed the pipe
  *  object as a parameter to the block, the child version of the block
  *  will be passed <code>nil</code>, and the child's standard in and
  *  standard out will be connected to the parent through the pipe. Not
  *  available on all platforms.
- *     
+ *
  *     f = IO.popen("uname")
  *     p f.readlines
  *     puts "Parent is #{Process.pid}"
- *     IO.popen ("date") { |f| puts f.gets }
+ *     IO.popen("date") { |f| puts f.gets }
  *     IO.popen("-") {|f| $stderr.puts "#{Process.pid} is here, f is #{f}"}
- *     
+ *     IO.popen(%w"sed -e s|^|<foo>| -e s&$&;zot;&", "r+") {|f|
+ *       f.puts "bar"; f.close_write; puts f.gets
+ *     }
+ *
  *  <em>produces:</em>
- *     
+ *
  *     ["Linux\n"]
  *     Parent is 26166
  *     Wed Apr  9 08:53:52 CDT 2003
  *     26169 is here, f is
  *     26166 is here, f is #<IO:0x401b3d44>
+ *     <foo>bar;zot;
  */
 
 static VALUE
@@ -2922,13 +2930,13 @@ rb_open_file(argc, argv, io)
  *  call-seq:
  *     IO.open(fd, mode_string="r" )               => io
  *     IO.open(fd, mode_string="r" ) {|io| block } => obj
- *  
+ *
  *  With no associated block, <code>open</code> is a synonym for
  *  <code>IO::new</code>. If the optional code block is given, it will
  *  be passed <i>io</i> as an argument, and the IO object will
  *  automatically be closed when the block terminates. In this instance,
  *  <code>IO::open</code> returns the value of the block.
- *     
+ *
  */
 
 static VALUE
@@ -2949,12 +2957,12 @@ rb_io_s_open(argc, argv, klass)
 /*
  *  call-seq:
  *     IO.sysopen(path, [mode, [perm]])  => fixnum
- *  
+ *
  *  Opens the given path, returning the underlying file descriptor as a
  *  <code>Fixnum</code>.
- *     
+ *
  *     IO.sysopen("testfile")   #=> 3
- *     
+ *
  */
 
 static VALUE
@@ -2985,21 +2993,21 @@ rb_io_s_sysopen(argc, argv)
  *  call-seq:
  *     open(path [, mode [, perm]] )                => io or nil
  *     open(path [, mode [. perm]] ) {|io| block }  => nil
- *  
+ *
  *  Creates an <code>IO</code> object connected to the given stream,
  *  file, or subprocess.
- *     
+ *
  *  If <i>path</i> does not start with a pipe character
  *  (``<code>|</code>''), treat it as the name of a file to open using
  *  the specified mode (defaulting to ``<code>r</code>''). (See the table
  *  of valid modes on page 331.) If a file is being created, its initial
  *  permissions may be set using the integer third parameter.
- *     
+ *
  *  If a block is specified, it will be invoked with the
  *  <code>File</code> object as a parameter, and the file will be
  *  automatically closed when the block terminates. The call always
  *  returns <code>nil</code> in this case.
- *     
+ *
  *  If <i>path</i> starts with a pipe character, a subprocess is
  *  created, connected to the caller by a pair of pipes. The returned
  *  <code>IO</code> object may be used to write to the standard input
@@ -3015,27 +3023,27 @@ rb_io_s_sysopen(argc, argv)
  *  will be connected to the child's <code>$stdin</code> and
  *  <code>$stdout</code>. The subprocess will be terminated at the end
  *  of the block.
- *     
+ *
  *     open("testfile") do |f|
  *       print f.gets
  *     end
- *     
+ *
  *  <em>produces:</em>
- *     
+ *
  *     This is line one
- *     
+ *
  *  Open a subprocess and read its output:
- *     
+ *
  *     cmd = open("|date")
  *     print cmd.gets
  *     cmd.close
- *     
+ *
  *  <em>produces:</em>
- *     
+ *
  *     Wed Apr  9 08:56:31 CDT 2003
- *     
+ *
  *  Open a subprocess running the same Ruby program:
- *     
+ *
  *     f = open("|-", "w+")
  *     if f == nil
  *       puts "in Child"
@@ -3043,13 +3051,13 @@ rb_io_s_sysopen(argc, argv)
  *     else
  *       puts "Got: #{f.gets}"
  *     end
- *     
+ *
  *  <em>produces:</em>
- *     
+ *
  *     Got: in Child
- *     
+ *
  *  Open a subprocess using a block to receive the I/O object:
- *     
+ *
  *     open("|-") do |f|
  *       if f == nil
  *         puts "in Child"
@@ -3057,9 +3065,9 @@ rb_io_s_sysopen(argc, argv)
  *         puts "Got: #{f.gets}"
  *       end
  *     end
- *     
+ *
  *  <em>produces:</em>
- *     
+ *
  *     Got: in Child
  */
 
@@ -3210,13 +3218,13 @@ io_reopen(io, nfile)
 
 /*
  *  call-seq:
- *     ios.reopen(other_IO)         => ios 
+ *     ios.reopen(other_IO)         => ios
  *     ios.reopen(path, mode_str)   => ios
- *  
+ *
  *  Reassociates <em>ios</em> with the I/O stream given in
  *  <i>other_IO</i> or to a new stream opened on <i>path</i>. This may
  *  dynamically change the actual class of this stream.
- *     
+ *
  *     f1 = File.new("testfile")
  *     f2 = File.new("testfile")
  *     f2.readlines[0]   #=> "This is line one\n"
@@ -3354,7 +3362,7 @@ rb_io_init_copy(dest, io)
 /*
  *  call-seq:
  *     ios.printf(format_string [, obj, ...] )   => nil
- *  
+ *
  *  Formats and writes to <em>ios</em>, converting parameters under
  *  control of the format string. See <code>Kernel#sprintf</code>
  *  for details.
@@ -3374,7 +3382,7 @@ rb_io_printf(argc, argv, out)
  *  call-seq:
  *     printf(io, string [, obj ... ] )    => nil
  *     printf(string [, obj ... ] )        => nil
- *  
+ *
  *  Equivalent to:
  *     io.write(sprintf(string, obj, ...)
  *  or
@@ -3406,7 +3414,7 @@ rb_f_printf(argc, argv)
  *  call-seq:
  *     ios.print()             => nil
  *     ios.print(obj, ...)     => nil
- *  
+ *
  *  Writes the given object(s) to <em>ios</em>. The stream must be
  *  opened for writing. If the output record separator (<code>$\</code>)
  *  is not <code>nil</code>, it will be appended to the output. If no
@@ -3414,11 +3422,11 @@ rb_f_printf(argc, argv)
  *  strings will be converted by calling their <code>to_s</code> method.
  *  With no argument, prints the contents of the variable <code>$_</code>.
  *  Returns <code>nil</code>.
- *     
+ *
  *     $stdout.print("This is ", 100, " percent.\n")
- *     
+ *
  *  <em>produces:</em>
- *     
+ *
  *     This is 100 percent.
  */
 
@@ -3460,7 +3468,7 @@ rb_io_print(argc, argv, out)
 /*
  *  call-seq:
  *     print(obj, ...)    => nil
- *  
+ *
  *  Prints each object in turn to <code>$stdout</code>. If the output
  *  field separator (<code>$,</code>) is not +nil+, its
  *  contents will appear between each field. If the output record
@@ -3468,14 +3476,14 @@ rb_io_print(argc, argv, out)
  *  appended to the output. If no arguments are given, prints
  *  <code>$_</code>. Objects that aren't strings will be converted by
  *  calling their <code>to_s</code> method.
- *     
+ *
  *     print "cat", [1,2,3], 99, "\n"
  *     $, = ", "
  *     $\ = "\n"
  *     print "cat", [1,2,3], 99
- *     
+ *
  *  <em>produces:</em>
- *     
+ *
  *     cat12399
  *     cat, 1, 2, 3, 99
  */
@@ -3492,16 +3500,16 @@ rb_f_print(argc, argv)
 /*
  *  call-seq:
  *     ios.putc(obj)    => obj
- *  
+ *
  *  If <i>obj</i> is <code>Numeric</code>, write the character whose
  *  code is <i>obj</i>, otherwise write the first character of the
  *  string representation of  <i>obj</i> to <em>ios</em>.
- *     
+ *
  *     $stdout.putc "A"
  *     $stdout.putc 65
- *     
+ *
  *  <em>produces:</em>
- *     
+ *
  *     AA
  */
 
@@ -3518,7 +3526,7 @@ rb_io_putc(io, ch)
 /*
  *  call-seq:
  *     putc(int)   => int
- *  
+ *
  *  Equivalent to:
  *
  *    $stdout.putc(int)
@@ -3551,17 +3559,17 @@ io_puts_ary(ary, out)
 /*
  *  call-seq:
  *     ios.puts(obj, ...)    => nil
- *  
+ *
  *  Writes the given objects to <em>ios</em> as with
  *  <code>IO#print</code>. Writes a record separator (typically a
  *  newline) after any that do not already end with a newline sequence.
  *  If called with an array argument, writes each element on a new line.
  *  If called without arguments, outputs a single record separator.
- *     
+ *
  *     $stdout.puts("this", "is", "a", "test")
- *     
+ *
  *  <em>produces:</em>
- *     
+ *
  *     this
  *     is
  *     a
@@ -3607,8 +3615,8 @@ rb_io_puts(argc, argv, out)
 /*
  *  call-seq:
  *     puts(obj, ...)    => nil
- *  
- *  Equivalent to 
+ *
+ *  Equivalent to
  *
  *      $stdout.puts(obj, ...)
  */
@@ -3633,18 +3641,18 @@ rb_p(obj)			/* for debug print within C code */
 /*
  *  call-seq:
  *     p(obj, ...)    => nil
- *  
+ *
  *  For each object, directly writes
  *  _obj_.+inspect+ followed by the current output
  *  record separator to the program's standard output. +p+
  *  bypasses the Ruby I/O libraries.
- *     
+ *
  *     S = Struct.new(:name, :state)
  *     s = S['dave', 'TX']
  *     p s
- *     
+ *
  *  <em>produces:</em>
- *     
+ *
  *     #<S name="dave", state="TX">
  */
 
@@ -3667,23 +3675,23 @@ rb_f_p(argc, argv)
 /*
  *  call-seq:
  *     obj.display(port=$>)    => nil
- *  
+ *
  *  Prints <i>obj</i> on the given port (default <code>$></code>).
  *  Equivalent to:
- *     
+ *
  *     def display(port=$>)
  *       port.write self
  *     end
- *     
+ *
  *  For example:
- *     
+ *
  *     1.display
  *     "cat".display
  *     [ 4, 5, 6 ].display
  *     puts
- *     
+ *
  *  <em>produces:</em>
- *     
+ *
  *     1cat456
  */
 
@@ -3799,7 +3807,7 @@ prep_path(io, path)
 /*
  *  call-seq:
  *     IO.new(fd, mode)   => io
- *  
+ *
  *  Returns a new <code>IO</code> object (a stream) for the given
  *  <code>IO</code> object or integer file descriptor and mode
  *  string. See also <code>IO#fileno</code> and
@@ -3810,9 +3818,9 @@ prep_path(io, path)
  *     a = IO.new(2,"w")      # '2' is standard error
  *     $stderr.puts "Hello"
  *     a.puts "World"
- *     
+ *
  *  <em>produces:</em>
- *     
+ *
  *     Hello
  *     World
  */
@@ -3893,7 +3901,7 @@ rb_io_initialize(argc, argv, io)
  *  call-seq:
  *     File.new(filename, mode="r")            => file
  *     File.new(filename [, mode [, perm]])    => file
- *  
+ *
 
  *  Opens the file named by _filename_ according to
  *  _mode_ (default is ``r'') and returns a new
@@ -3937,17 +3945,17 @@ rb_file_initialize(argc, argv, io)
 /*
  *  call-seq:
  *     IO.new(fd, mode_string)   => io
- *  
+ *
  *  Returns a new <code>IO</code> object (a stream) for the given
  *  integer file descriptor and mode string. See also
  *  <code>IO#fileno</code> and <code>IO::for_fd</code>.
- *     
+ *
  *     a = IO.new(2,"w")      # '2' is standard error
  *     $stderr.puts "Hello"
  *     a.puts "World"
- *     
+ *
  *  <em>produces:</em>
- *     
+ *
  *     Hello
  *     World
  */
@@ -3971,9 +3979,9 @@ rb_io_s_new(argc, argv, klass)
 /*
  *  call-seq:
  *     IO.for_fd(fd, mode)    => io
- *  
+ *
  *  Synonym for <code>IO::new</code>.
- *     
+ *
  */
 
 static VALUE
@@ -4172,7 +4180,7 @@ argf_getline(argc, argv)
 /*
  *  call-seq:
  *     gets(separator=$/)    => string or nil
- *  
+ *
  *  Returns (and assigns to <code>$_</code>) the next line from the list
  *  of files in +ARGV+ (or <code>$*</code>), or from standard
  *  input if no files are present on the command line. Returns
@@ -4183,17 +4191,17 @@ argf_getline(argc, argv)
  *  at a time, where paragraphs are divided by two consecutive newlines.
  *  If multiple filenames are present in +ARGV+,
  *  +gets(nil)+ will read the contents one file at a time.
- *     
+ *
  *     ARGV << "testfile"
  *     print while gets
- *     
+ *
  *  <em>produces:</em>
- *     
+ *
  *     This is line one
  *     This is line two
  *     This is line three
  *     And so on...
- *     
+ *
  *  The style of programming using <code>$_</code> as an implicit
  *  parameter is gradually losing favor in the Ruby community.
  */
@@ -4245,7 +4253,7 @@ rb_gets()
 /*
  *  call-seq:
  *     readline(separator=$/    => string
- *  
+ *
  *  Equivalent to <code>Kernel::gets</code>, except
  *  +readline+ raises +EOFError+ at end of file.
  */
@@ -4283,7 +4291,7 @@ rb_f_getc()
 /*
  *  call-seq:
  *     readlines(separator=$/)    => array
- *  
+ *
  *  Returns an array containing the lines returned by calling
  *  <code>Kernel.gets(<i>aString</i>)</code> until the end of file.
  */
@@ -4307,11 +4315,11 @@ rb_f_readlines(argc, argv)
 /*
  *  call-seq:
  *     `cmd`    => string
- *  
+ *
  *  Returns the standard output of running _cmd_ in a subshell.
  *  The built-in syntax <code>%x{...}</code> uses
  *  this method. Sets <code>$?</code> to the process status.
- *     
+ *
  *     `date`                   #=> "Wed Apr  9 08:56:30 CDT 2003\n"
  *     `ls testdir`.split[1]    #=> "main.rb"
  *     `echo oops && exit 99`   #=> "oops\n"
@@ -4342,11 +4350,11 @@ rb_f_backquote(obj, str)
 
 /*
  *  call-seq:
- *     IO.select(read_array 
- *               [, write_array 
- *               [, error_array 
+ *     IO.select(read_array
+ *               [, write_array
+ *               [, error_array
  *               [, timeout]]] ) =>  array  or  nil
- *  
+ *
  *  See <code>Kernel#select</code>.
  */
 
@@ -4591,7 +4599,7 @@ rb_io_ctl(io, req, arg, io_p)
 /*
  *  call-seq:
  *     ios.ioctl(integer_cmd, arg)    => integer
- *  
+ *
  *  Provides a mechanism for issuing low-level commands to control or
  *  query I/O devices. Arguments and results are platform dependent. If
  *  <i>arg</i> is a number, its value is passed directly. If it is a
@@ -4615,7 +4623,7 @@ rb_io_ioctl(argc, argv, io)
 /*
  *  call-seq:
  *     ios.fcntl(integer_cmd, arg)    => integer
- *  
+ *
  *  Provides a mechanism for issuing low-level commands to control or
  *  query file-oriented I/O streams. Arguments and results are platform
  *  dependent. If <i>arg</i> is a number, its value is passed
@@ -4645,7 +4653,7 @@ rb_io_fcntl(argc, argv, io)
 /*
  *  call-seq:
  *     syscall(fixnum [, args...])   => integer
- *  
+ *
  *  Calls the operating system function identified by _fixnum_,
  *  passing in the arguments, which must be either +String+
  *  objects, or +Integer+ objects that ultimately fit within
@@ -4653,11 +4661,11 @@ rb_io_fcntl(argc, argv, io)
  *  on the Atari-ST). The function identified by _fixnum_ is system
  *  dependent. On some Unix systems, the numbers may be obtained from a
  *  header file called <code>syscall.h</code>.
- *     
+ *
  *     syscall 4, 1, "hello\n", 6   # '4' is write(2) on our box
- *     
+ *
  *  <em>produces:</em>
- *     
+ *
  *     hello
  */
 
@@ -4773,21 +4781,21 @@ io_new_instance(args)
 /*
  *  call-seq:
  *     IO.pipe -> array
- *  
+ *
  *  Creates a pair of pipe endpoints (connected to each other) and
  *  returns them as a two-element array of <code>IO</code> objects:
  *  <code>[</code> <i>read_file</i>, <i>write_file</i> <code>]</code>. Not
  *  available on all platforms.
- *     
+ *
  *  In the example below, the two processes close the ends of the pipe
  *  that they are not using. This is not just a cosmetic nicety. The
  *  read end of a pipe will not generate an end of file condition if
  *  there are any writers with the pipe still open. In the case of the
  *  parent process, the <code>rd.read</code> will never return if it
  *  does not first issue a <code>wr.close</code>.
- *     
+ *
  *     rd, wr = IO.pipe
- *     
+ *
  *     if fork
  *       wr.close
  *       puts "Parent got: <#{rd.read}>"
@@ -4799,9 +4807,9 @@ io_new_instance(args)
  *       wr.write "Hi Dad"
  *       wr.close
  *     end
- *     
+ *
  *  <em>produces:</em>
- *     
+ *
  *     Sending message to parent
  *     Parent got: <Hi Dad>
  */
@@ -4869,19 +4877,19 @@ io_s_foreach(arg)
 /*
  *  call-seq:
  *     IO.foreach(name, sep_string=$/) {|line| block }   => nil
- *  
+ *
  *  Executes the block for every line in the named I/O port, where lines
  *  are separated by <em>sep_string</em>.
- *     
+ *
  *     IO.foreach("testfile") {|x| print "GOT ", x }
- *     
+ *
  *  <em>produces:</em>
- *     
+ *
  *     GOT This is line one
  *     GOT This is line two
  *     GOT This is line three
  *     GOT And so on...
- */     
+ */
 
 static VALUE
 rb_io_s_foreach(argc, argv)
@@ -4915,14 +4923,14 @@ io_s_readlines(arg)
 /*
  *  call-seq:
  *     IO.readlines(name, sep_string=$/)   => array
- *  
+ *
  *  Reads the entire file specified by <i>name</i> as individual
  *  lines, and returns those lines in an array. Lines are separated by
  *  <i>sep_string</i>.
- *     
+ *
  *     a = IO.readlines("testfile")
  *     a[0]   #=> "This is line one\n"
- *     
+ *
  */
 
 static VALUE
@@ -4952,11 +4960,11 @@ io_s_read(arg)
 /*
  *  call-seq:
  *     IO.read(rane, [length [, offset]] )   => string
- *  
+ *
  *  Opens the file, optionally seeks to the given offset, then returns
  *  <i>length</i> bytes (defaulting to the rest of the file).
  *  <code>read</code> ensures the file is closed before returning.
- *     
+ *
  *     IO.read("testfile")           #=> "This is line one\nThis is line two\nThis is line three\nAnd so on...\n"
  *     IO.read("testfile", 20)       #=> "This is line one\nThi"
  *     IO.read("testfile", 20, 10)   #=> "ne one\nThis is line "
@@ -5258,38 +5266,38 @@ opt_i_set(val)
  *  Class <code>IO</code> is the basis for all input and output in Ruby.
  *  An I/O stream may be <em>duplexed</em> (that is, bidirectional), and
  *  so may use more than one native operating system stream.
- *     
+ *
  *  Many of the examples in this section use class <code>File</code>,
  *  the only standard subclass of <code>IO</code>. The two classes are
  *  closely associated.
- *     
+ *
  *  As used in this section, <em>portname</em> may take any of the
  *  following forms.
- *     
+ *
  *  * A plain string represents a filename suitable for the underlying
  *    operating system.
- *     
+ *
  *  * A string starting with ``<code>|</code>'' indicates a subprocess.
  *    The remainder of the string following the ``<code>|</code>'' is
  *    invoked as a process with appropriate input/output channels
  *    connected to it.
- *     
+ *
  *  * A string equal to ``<code>|-</code>'' will create another Ruby
  *    instance as a subprocess.
- *     
+ *
  *  Ruby will convert pathnames between different operating system
  *  conventions if possible. For instance, on a Windows system the
  *  filename ``<code>/gumby/ruby/test.rb</code>'' will be opened as
  *  ``<code>\gumby\ruby\test.rb</code>''. When specifying a
  *  Windows-style filename in a Ruby string, remember to escape the
  *  backslashes:
- *     
+ *
  *     "c:\\gumby\\ruby\\test.rb"
- *     
+ *
  *  Our examples here will use the Unix-style forward slashes;
  *  <code>File::SEPARATOR</code> can be used to get the
  *  platform-specific separator character.
- *     
+ *
  *  I/O ports may be opened in any one of several different modes, which
  *  are shown in this section as <em>mode</em>. The mode may
  *  either be a Fixnum or a String. If numeric, it should be
@@ -5306,7 +5314,7 @@ opt_i_set(val)
  *    -----+--------------------------------------------------------
  *    "r+" |  Read-write, starts at beginning of file.
  *    -----+--------------------------------------------------------
- *    "w"  |  Write-only, truncates existing file 
+ *    "w"  |  Write-only, truncates existing file
  *         |  to zero length or creates a new file for writing.
  *    -----+--------------------------------------------------------
  *    "w+" |  Read-write, truncates existing file to zero length
@@ -5316,10 +5324,10 @@ opt_i_set(val)
  *         |  otherwise creates a new file for writing.
  *    -----+--------------------------------------------------------
  *    "a+" |  Read-write, starts at end of file if file exists,
- *         |  otherwise creates a new file for reading and 
+ *         |  otherwise creates a new file for reading and
  *         |  writing.
  *    -----+--------------------------------------------------------
- *     "b" |  (DOS/Windows only) Binary file mode (may appear with 
+ *     "b" |  (DOS/Windows only) Binary file mode (may appear with
  *         |  any of the key letters listed above).
  *
  *
@@ -5333,7 +5341,7 @@ opt_i_set(val)
 void
 Init_IO()
 {
-#ifdef __CYGWIN__ 
+#ifdef __CYGWIN__
 #include <sys/cygwin.h>
     static struct __cygwin_perfile pf[] =
     {