<ppdoc>
<copyright>
    Copyright (c) 2001 by Addison Wesley Longman.  This
    material may be distributed only subject to the terms and
    conditions set forth in the Open Publication License, v1.0 or
    later (the latest version is presently available at
    http://www.opencontent.org/openpub/).
</copyright>
<class name="IO" super="Object" type="class">  <subclasses>File</subclasses>
<p/>
  Class <classname>IO</classname> 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.
<p/>
  Many of the examples in this section use class <classname>File</classname>, the only
  standard subclass of <classname>IO</classname>.  The two classes are closely associated.
<p/>
  As used in this section, <em>aPortname</em> may take any of the
  following forms.        
<p/>
  <ul>
  <li> A plain string represents a filename suitable for the
    underlying operating system.
  </li><li> A string starting with ``<tt>|</tt>'' indicates a subprocess.  The
    remainder of the string following the ``<tt>|</tt>'' is invoked as a
    process with appropriate input/output channels connected to it.
  </li><li> A string equal to ``<tt>|-</tt>'' will create another Ruby
    instance as a subprocess.
  </li></ul>
<p/>
  Ruby will convert pathnames between different operating system
  conventions if possible.  For instance, on a Windows system the
  filename ``<tt>/gumby/ruby/test.rb</tt>'' will be opened as
  ``<tt>\gumby\ruby\test.rb</tt>''.  When specifying a
  Windows-style filename in a Ruby string, remember to escape the
  backslashes:
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        "c:\\gumby\\ruby\\test.rb"
]]></fullcode>
"c:\\gumby\\ruby\\test.rb"
</alltt>
</codefragment>
<p/>
  Our examples here will use the Unix-style forward slashes;
  <classconst><file>file</file><front>File</front><back>SEPARATOR</back><mref>SEPARATOR</mref></classconst> can be used to get the platform-specific
  separator character.
<p/>
  I/O ports may be opened in any one of several different modes, which are
  shown in this section as <em>aModeString</em>. This mode string must be one of the
  values listed in Table 22.5 on page 331.
<p/>
  <figure type="table">
    <caption>Mode strings</caption>    
    <table>
<th>
  <td><b>Mode</b></td>
  <td><b>Meaning</b></td>
</th>
<tr>
  <td>``r''</td>
  <td>Read-only, starts at beginning of file  (default mode).</td>
</tr>
<tr>
  <td>``r+''</td>
  <td>Read-write, starts at beginning of file.</td>
</tr>
<tr>
  <td>``w''</td>
  <td>Write-only, truncates existing file 
                   to zero length or creates a new file for writing.</td>
</tr>
<tr>
  <td>``w+''</td>
  <td>Read-write, truncates existing file to zero length
                   or creates a new file for reading and writing.</td>
</tr>
<tr>
  <td>``a''</td>
  <td>Write-only, starts at end of file if file exists,
                   otherwise creates a new file for writing.</td>
</tr>
<tr>
  <td>``a+''</td>
  <td>Read-write, starts at end of file if file exists,
                   otherwise creates a new file for reading and 
                           writing.</td>
</tr>
<tr>
  <td>``b''</td>
  <td>(DOS/Windows only) Binary file mode (may appear with 
                  any of the key letters listed above).</td>
</tr>
<bottomrule/></table>
<p/>
  </figure>
<p/>
  <mixins>
    <mixin name="Enumerable">
   collect, detect, each_with_index, entries, find, find_all, grep,
   include?, map, max, member?, min, reject, select, sort, to_a</mixin>
  </mixins>
<p/>
  <methods type="class">
<p/>
        <method name="foreach" ref="foreach">
      <callseq>
        IO.foreach( <obj>aPortName</obj>,
            <obj>aSepString</obj>=<var>$/</var> )
        <block>{| line | <blockbody>block</blockbody> }</block>
 <returns><tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Executes the block for every line in the
      named I/O port, where lines are separated by <em>aSepString</em>.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        IO.foreach("testfile") {|x| print "GOT ", x }
]]></fullcode>
IO.foreach("testfile")<nbsp/>{|x|<nbsp/>print<nbsp/>"GOT<nbsp/>",<nbsp/>x<nbsp/>}
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
GOT<nbsp/>This<nbsp/>is<nbsp/>line<nbsp/>one
GOT<nbsp/>This<nbsp/>is<nbsp/>line<nbsp/>two
GOT<nbsp/>This<nbsp/>is<nbsp/>line<nbsp/>three
GOT<nbsp/>And<nbsp/>so<nbsp/>on...
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="new" ref="new">
      <callseq>
        IO.new( <obj>anInteger</obj>, <obj>aModeString</obj> )
        <returns><obj>aFile</obj></returns>
      </callseq>
      <desc>
<p/>
        Returns a new <classname>File</classname> object (a stream) for the given
        integer file descriptor and mode string. See also <cim><file>io</file><front>IO</front><back>fileno</back><mref>fileno</mref></cim>.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        a = IO.new(2,"w")      # '2' is standard error
        $stderr.puts "Hello"
        a.puts "World"
]]></fullcode>
a<nbsp/>=<nbsp/>IO.new(2,"w")<nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/>#<nbsp/>'2'<nbsp/>is<nbsp/>standard<nbsp/>error
$stderr.puts<nbsp/>"Hello"
a.puts<nbsp/>"World"
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
Hello
World
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="pipe" ref="pipe">
      <callseq>
        IO.pipe <returns><obj>anArray</obj></returns>
      </callseq>
      <desc>
<p/>
      Creates a pair of pipe endpoints (connected to each other) and
      returns them as a two-element array of <classname>IO</classname> objects: <tt>[</tt>
      <obj>readFile</obj>, <obj>writeFile</obj> <tt>]</tt>.  Not available on all
      platforms.
<p/>
      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 <tt>rd.read</tt> will never
      return if it does not first issue a <tt>wr.close</tt>.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        rd, wr = IO.pipe

        if fork
          wr.close
          puts "Parent got: <#{rd.read}>"
          rd.close
          Process.wait
        else
          rd.close
          puts "Sending message to parent"
          wr.write "Hi Dad"
          wr.close
        end
]]></fullcode>
rd,<nbsp/>wr<nbsp/>=<nbsp/>IO.pipe
<p/>
if<nbsp/>fork
<nbsp/><nbsp/>wr.close
<nbsp/><nbsp/>puts<nbsp/>"Parent<nbsp/>got:<nbsp/>&lt;#{rd.read}&gt;"
<nbsp/><nbsp/>rd.close
<nbsp/><nbsp/>Process.wait
else
<nbsp/><nbsp/>rd.close
<nbsp/><nbsp/>puts<nbsp/>"Sending<nbsp/>message<nbsp/>to<nbsp/>parent"
<nbsp/><nbsp/>wr.write<nbsp/>"Hi<nbsp/>Dad"
<nbsp/><nbsp/>wr.close
end
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
Sending<nbsp/>message<nbsp/>to<nbsp/>parent
Parent<nbsp/>got:<nbsp/>&lt;Hi<nbsp/>Dad&gt;
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="popen" ref="popen">
      <callseq>
                IO.popen( <obj>aCmdString</obj>, <obj>aModeString</obj>="r" )
        <returns><obj>anIO</obj></returns><br/>IO.popen( <obj>aCmdString</obj>, <obj>aModeString</obj>="r" )
        <block>{| anIO | <blockbody>block</blockbody> }</block>
 <returns><tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Runs the specified command string as a subprocess; the
      subprocess's standard input and output will be connected 
      to the returned <classname>IO</classname> object.  If <obj>aCmdString</obj> starts with a
      ``<tt>-</tt>'', then a new instance of Ruby is started as the subprocess.
      The default mode for the new file object is ``r'', but
      <obj>aModeString</obj> may be
      set to any of the modes in Table 22.5 on page 331.                  
<p/>
      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.
<p/>
      If a block is given with a <obj>aCmdString</obj> of ``<tt>-</tt>'', 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 <tt>nil</tt>, and the child's
      standard in and standard out will be connected to the parent through the 
      pipe.
      Not available on all platforms.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        f = IO.popen("uname")
        p f.readlines
        puts "Parent is #{Process.pid}"
        IO.popen ("date") { |f| puts f.gets }
        IO.popen("-") {|f| $stderr.puts "#{Process.pid} is here, f is #{f}"}
]]></fullcode>
f<nbsp/>=<nbsp/>IO.popen("uname")
p<nbsp/>f.readlines
puts<nbsp/>"Parent<nbsp/>is<nbsp/>#{Process.pid}"
IO.popen<nbsp/>("date")<nbsp/>{<nbsp/>|f|<nbsp/>puts<nbsp/>f.gets<nbsp/>}
IO.popen("-")<nbsp/>{|f|<nbsp/>$stderr.puts<nbsp/>"#{Process.pid}<nbsp/>is<nbsp/>here,<nbsp/>f<nbsp/>is<nbsp/>#{f}"}
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
["Linux\n"]
Parent<nbsp/>is<nbsp/>15506
Sun<nbsp/>Mar<nbsp/><nbsp/>4<nbsp/>23:28:51<nbsp/>CST<nbsp/>2001
15509<nbsp/>is<nbsp/>here,<nbsp/>f<nbsp/>is
15506<nbsp/>is<nbsp/>here,<nbsp/>f<nbsp/>is<nbsp/>#&lt;IO:0x4018d518&gt;
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="readlines" ref="readlines">
      <callseq>
        IO.readlines( <obj>aPortName</obj>,
                <obj>aSepString</obj>=<var>$/</var> ) 
        <returns><obj>anArray</obj></returns>
      </callseq>
      <desc>
<p/>
      Reads the entire file specified by <obj>aPortName</obj> as individual
      lines, and returns those lines in an array.  Lines are 
      separated by <obj>aSepString</obj>.
<p/>
<codefragment>
<fullcode><![CDATA[        a = IO.readlines("testfile")
        a[0]
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>a<nbsp/>=<nbsp/>IO.readlines("testfile")</tt></td>
</tr>
<tr>
  <td><tt>a[0]</tt></td>
  <td>&#187;</td>
  <td><tt>"This<nbsp/>is<nbsp/>line<nbsp/>one\n"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="select" ref="select">
      <callseq>
        IO.select( <obj>readArray</obj> <opt>,
          <obj>writeArray</obj>
          <opt><obj>errorArray</obj> <opt><obj>timeout</obj></opt></opt></opt> )
        <returns><obj>anArray</obj><br/>or <tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      See <mim><file>kernel</file><front>Kernel</front><back>select</back><mref>select</mref></mim> on page 426.
<p/>
      </desc>
    </method>
<p/>
  </methods>
<p/>
  <methods type="instance">
<p/>
        <method name="&lt;&lt;" ref="_lt_lt">
      <callseq>
        <em>ios</em> &lt;&lt; <obj>anObject</obj>
        <returns><em>ios</em></returns>
      </callseq>
      <desc>
<p/>
      String Output---Writes <obj>anObject</obj> to <em>ios</em>. 
      <obj>anObject</obj> will be
      converted to a string using <meth>to_s</meth>.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        $stdout << "Hello " << "world!\n"
]]></fullcode>
$stdout<nbsp/>&lt;&lt;<nbsp/>"Hello<nbsp/>"<nbsp/>&lt;&lt;<nbsp/>"world!\n"
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
Hello<nbsp/>world!
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="binmode" ref="binmode">
      <callseq>
        <em>ios</em>.binmode <returns><em>ios</em></returns>
      </callseq>
      <desc>
<p/>
      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.
<p/>
      </desc>
    </method>
<p/>
        <method name="clone" ref="clone">
      <callseq>
        <em>ios</em>.clone <returns><obj>anIO</obj></returns>
      </callseq>
      <desc>
<p/>
      Creates a new I/O stream, copying all the attributes of <em>ios</em>.
      The file position is shared as well, so
      reading from the clone will alter the file position of the
      original, and vice-versa.
<p/>
      </desc>
    </method>
<p/>
        <method name="close" ref="close">
      <callseq>
        <em>ios</em>.close <returns><tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Closes <em>ios</em> and flushes any pending writes to the
      operating system.
      The stream is unavailable for any further
      data operations; an <exception>IOError</exception> is raised if such an attempt is 
      made.  I/O streams are automatically closed when they are claimed 
      by the garbage collector.
<p/>
      </desc>
    </method>
<p/>
        <method name="close_read" ref="close_read">
      <callseq>
        <em>ios</em>.close_read <returns><tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
            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 <exception>IOError</exception> if the stream is not duplexed.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        f = IO.popen("/bin/sh","r+")
        f.close_read
        f.readlines
]]></fullcode>
f<nbsp/>=<nbsp/>IO.popen("/bin/sh","r+")
f.close_read
f.readlines
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
prog.rb:3:in<nbsp/>`readlines':<nbsp/>not<nbsp/>opened<nbsp/>for<nbsp/>reading<nbsp/>(IOError)
	from<nbsp/>prog.rb:3
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="close_write" ref="close_write">
      <callseq>
        <em>ios</em>.close_write <returns><tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
            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 <exception>IOError</exception> if the stream is not duplexed.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        f = IO.popen("/bin/sh","r+")
        f.close_write
        f.print "nowhere"
]]></fullcode>
f<nbsp/>=<nbsp/>IO.popen("/bin/sh","r+")
f.close_write
f.print<nbsp/>"nowhere"
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
prog.rb:3:in<nbsp/>`write':<nbsp/>not<nbsp/>opened<nbsp/>for<nbsp/>writing<nbsp/>(IOError)
	from<nbsp/>prog.rb:3:in<nbsp/>`print'
	from<nbsp/>prog.rb:3
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="closed?" ref="closed_qm">
      <callseq>
        <em>ios</em>.closed? 
                <returns><const>true</const> or <const>false</const></returns>
      </callseq>
      <desc>
<p/>
      Returns <const>true</const> if <em>ios</em> is completely closed (for
      duplex streams, both reader and writer), <const>false</const> otherwise.
<p/>
<codefragment>
<fullcode><![CDATA[        f = File.new("testfile")
        f.close
        f.closed?
        f = IO.popen("/bin/sh","r+")
        f.close_write
        f.closed?
        f.close_read
        f.closed?
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>f<nbsp/>=<nbsp/>File.new("testfile")</tt></td>
</tr>
<tr>
  <td><tt>f.close</tt></td>
  <td>&#187;</td>
  <td><tt>nil</tt></td>
</tr>
<tr>
  <td><tt>f.closed?</tt></td>
  <td>&#187;</td>
  <td><tt>true</tt></td>
</tr>
<tr>
<td colspan="3"><tt>f<nbsp/>=<nbsp/>IO.popen("/bin/sh","r+")</tt></td>
</tr>
<tr>
  <td><tt>f.close_write</tt></td>
  <td>&#187;</td>
  <td><tt>nil</tt></td>
</tr>
<tr>
  <td><tt>f.closed?</tt></td>
  <td>&#187;</td>
  <td><tt>false</tt></td>
</tr>
<tr>
  <td><tt>f.close_read</tt></td>
  <td>&#187;</td>
  <td><tt>nil</tt></td>
</tr>
<tr>
  <td><tt>f.closed?</tt></td>
  <td>&#187;</td>
  <td><tt>true</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="each" ref="each">
      <callseq>
        <em>ios</em>.each( <obj>aSepString</obj>=<var>$/</var> )
        <block>{| line | <blockbody>block</blockbody> }</block>
 <returns><em>ios</em></returns>
      </callseq>
      <desc>
<p/>
      Executes the block for every line in <em>ios</em>, where lines are
      separated by <obj>aSepString</obj>.
      <em>ios</em> must be opened for reading or an
      <exception>IOerror</exception> will be raised.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        f = File.new("testfile")
        f.each {|line| puts "#{f.lineno}: #{line}" }
]]></fullcode>
f<nbsp/>=<nbsp/>File.new("testfile")
f.each<nbsp/>{|line|<nbsp/>puts<nbsp/>"#{f.lineno}:<nbsp/>#{line}"<nbsp/>}
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
1:<nbsp/>This<nbsp/>is<nbsp/>line<nbsp/>one
2:<nbsp/>This<nbsp/>is<nbsp/>line<nbsp/>two
3:<nbsp/>This<nbsp/>is<nbsp/>line<nbsp/>three
4:<nbsp/>And<nbsp/>so<nbsp/>on...
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="each_byte" ref="each_byte">
      <callseq>
        <em>ios</em>.each_byte <block>{| byte | <blockbody>block</blockbody> }</block>
<p/>
      <returns><tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      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 <exception>IOerror</exception> will be raised.
<p/>
<codefragment>
<fullcode><![CDATA[        f = File.new("testfile")
        checksum = 0
        f.each_byte {|x| checksum ^= x }
        checksum
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>f<nbsp/>=<nbsp/>File.new("testfile")</tt></td>
</tr>
<tr>
<td colspan="3"><tt>checksum<nbsp/>=<nbsp/>0</tt></td>
</tr>
<tr>
  <td><tt>f.each_byte<nbsp/>{|x|<nbsp/>checksum<nbsp/>^=<nbsp/>x<nbsp/>}</tt></td>
  <td>&#187;</td>
  <td><tt>nil</tt></td>
</tr>
<tr>
  <td><tt>checksum</tt></td>
  <td>&#187;</td>
  <td><tt>12</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="each_line" ref="each_line">
      <callseq>
        <em>ios</em>.each_line(
                <obj>aSepString</obj>=<var>$/</var> ) <block>{| line | <blockbody>block</blockbody> }</block>
<p/>
        <returns><em>ios</em></returns>
      </callseq>
      <desc>
<p/>
      Synonym for <cim><file>io</file><front>IO</front><back>each</back><mref>each</mref></cim>.
<p/>
      </desc>
    </method>
<p/>
        <method name="eof" ref="eof">
      <callseq>
        <em>ios</em>.eof 
                <returns><const>true</const> or <const>false</const></returns>
      </callseq>
      <desc>
<p/>
      Returns true if <em>ios</em> is at end of file.  The
      stream must be opened for reading or an <exception>IOError</exception> will be
      raised.
<p/>
<codefragment>
<fullcode><![CDATA[        f = File.new("testfile")
        dummy = f.readlines
        f.eof
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>f<nbsp/>=<nbsp/>File.new("testfile")</tt></td>
</tr>
<tr>
<td colspan="3"><tt>dummy<nbsp/>=<nbsp/>f.readlines</tt></td>
</tr>
<tr>
  <td><tt>f.eof</tt></td>
  <td>&#187;</td>
  <td><tt>true</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="eof?" ref="eof_qm">
      <callseq>
        <em>ios</em>.eof? 
                <returns><const>true</const> or <const>false</const></returns>
      </callseq>
      <desc>
<p/>
      Synonym for <cim><file>io</file><front>IO</front><back>eof</back><mref>eof</mref></cim>.
<p/>
      </desc>
    </method>
<p/>
        <method name="fcntl" ref="fcntl">
      <callseq>
        <em>ios</em>.fcntl( <obj>anIntegerCmd</obj>, <obj>anArg</obj> ) 
        <returns><obj>anInteger</obj></returns>
      </callseq>
      <desc>
<p/>
            Provides a mechanism for issuing low-level commands to control or
      query file-oriented I/O streams.
      Arguments and results are platform dependent.
      If <obj>anArg</obj> is a number, its value is passed directly.  If it is 
      a string, it is interpreted as a binary sequence of bytes.
      On Unix platforms, see <tt>fcntl(2)</tt> for details.
      Not implemented on all platforms.
<p/>
      </desc>
    </method>
<p/>
        <method name="fileno" ref="fileno">
      <callseq>
        <em>ios</em>.fileno <returns><obj>aFixnum</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns an integer representing the numeric file descriptor for <em>ios</em>.
<p/>
<codefragment>
<fullcode><![CDATA[        $stdin.fileno
        $stdout.fileno
]]></fullcode><rubycode>
<tr>
  <td><tt>$stdin.fileno</tt></td>
  <td>&#187;</td>
  <td><tt>0</tt></td>
</tr>
<tr>
  <td><tt>$stdout.fileno</tt></td>
  <td>&#187;</td>
  <td><tt>1</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="flush" ref="flush">
      <callseq>
        <em>ios</em>.flush <returns><em>ios</em></returns>
      </callseq>
      <desc>
<p/>
      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).
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        $stdout.print "no newline"
        $stdout.flush
]]></fullcode>
$stdout.print<nbsp/>"no<nbsp/>newline"
$stdout.flush
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
no<nbsp/>newline
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="getc" ref="getc">
      <callseq>
        <em>ios</em>.getc <returns><obj>aFixnum</obj> or <tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Gets the next 8-bit byte (0..255) from <em>ios</em>.
      Returns <tt>nil</tt> if called at end of file.
<p/>
<codefragment>
<fullcode><![CDATA[        f = File.new("testfile")
        f.getc
        f.getc
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>f<nbsp/>=<nbsp/>File.new("testfile")</tt></td>
</tr>
<tr>
  <td><tt>f.getc</tt></td>
  <td>&#187;</td>
  <td><tt>84</tt></td>
</tr>
<tr>
  <td><tt>f.getc</tt></td>
  <td>&#187;</td>
  <td><tt>104</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="gets" ref="gets">
      <callseq>
        <em>ios</em>.gets( <obj>aSepString</obj>=<var>$/</var> )
        <returns><obj>aString</obj> or <tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Reads the next ``line'' from the I/O stream; lines are separated
      by <obj>aSepString</obj>. A separator of <tt>nil</tt> reads the entire
      contents, and a zero-length separator reads the input a paragraph
      at a time (two successive newlines in the input separate
      paragraphs). The stream must be opened for reading or an
      <exception>IOerror</exception> will be raised.  The line read in will be
      returned and also assigned to 
      <var>$_</var>. Returns <tt>nil</tt> if called at end of file.
<p/>
<codefragment>
<fullcode><![CDATA[        File.new("testfile").gets
        $_
]]></fullcode><rubycode>
<tr>
  <td><tt>File.new("testfile").gets</tt></td>
  <td>&#187;</td>
  <td><tt>"This<nbsp/>is<nbsp/>line<nbsp/>one\n"</tt></td>
</tr>
<tr>
  <td><tt>$_</tt></td>
  <td>&#187;</td>
  <td><tt>"This<nbsp/>is<nbsp/>line<nbsp/>one\n"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="ioctl" ref="ioctl">
      <callseq>
        <em>ios</em>.ioctl( <obj>anIntegerCmd</obj>, <obj>anArg</obj> ) 
        <returns><obj>anInteger</obj></returns>
      </callseq>
      <desc>
<p/>
            Provides a mechanism for issuing low-level commands to control or
      query I/O devices.
      Arguments and results are platform dependent.
      If <obj>anArg</obj> is a number, its value is passed directly.  If it is 
      a string, it is interpreted as a binary sequence of bytes.
      On Unix platforms, see <tt>ioctl(2)</tt> for details.
      Not implemented on all platforms.
<p/>
      </desc>
    </method>
<p/>
        <method name="isatty" ref="isatty">
      <callseq>
        <em>ios</em>.isatty 
                <returns><const>true</const> or <const>false</const></returns>
      </callseq>
      <desc>
              Returns <const>true</const> if <em>ios</em> is associated with a
      terminal device (tty), <const>false</const> otherwise.
<p/>
<codefragment>
<fullcode><![CDATA[        File.new("testfile").isatty
        File.new("/dev/tty").isatty
]]></fullcode><rubycode>
<tr>
  <td><tt>File.new("testfile").isatty</tt></td>
  <td>&#187;</td>
  <td><tt>false</tt></td>
</tr>
<tr>
  <td><tt>File.new("/dev/tty").isatty</tt></td>
  <td>&#187;</td>
  <td><tt>true</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="lineno" ref="lineno">
      <callseq>
        <em>ios</em>.lineno <returns><obj>anInteger</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the current line number in <em>ios</em>.  The stream
      must be opened for reading. <meth>lineno</meth> counts the number of 
      times <meth>gets</meth> is called, rather than the number of
      newlines encountered. The two values will differ if <meth>gets</meth>
      is called with a separator other than newline. See also the
      <var>$.</var> variable.
<p/>
<codefragment>
<fullcode><![CDATA[        f = File.new("testfile")
        f.lineno
        f.gets 
        f.lineno
        f.gets 
        f.lineno
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>f<nbsp/>=<nbsp/>File.new("testfile")</tt></td>
</tr>
<tr>
  <td><tt>f.lineno</tt></td>
  <td>&#187;</td>
  <td><tt>0</tt></td>
</tr>
<tr>
  <td><tt>f.gets</tt></td>
  <td>&#187;</td>
  <td><tt>"This<nbsp/>is<nbsp/>line<nbsp/>one\n"</tt></td>
</tr>
<tr>
  <td><tt>f.lineno</tt></td>
  <td>&#187;</td>
  <td><tt>1</tt></td>
</tr>
<tr>
  <td><tt>f.gets</tt></td>
  <td>&#187;</td>
  <td><tt>"This<nbsp/>is<nbsp/>line<nbsp/>two\n"</tt></td>
</tr>
<tr>
  <td><tt>f.lineno</tt></td>
  <td>&#187;</td>
  <td><tt>2</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="lineno=" ref="lineno_eq">
      <callseq>
        <em>ios</em>.lineno = <obj>anInteger</obj> 
        <returns><obj>anInteger</obj></returns>
      </callseq>
      <desc>
<p/>
      Manually sets the current line number to the given
      value. <var>$.</var> is updated only on the next read.
<p/>
<codefragment>
<fullcode><![CDATA[        f = File.new("testfile")
        f.gets
        $.
        f.lineno = 1000
        f.lineno
        $. # lineno of last read
        f.gets 
        $. # lineno of last read
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>f<nbsp/>=<nbsp/>File.new("testfile")</tt></td>
</tr>
<tr>
  <td><tt>f.gets</tt></td>
  <td>&#187;</td>
  <td><tt>"This<nbsp/>is<nbsp/>line<nbsp/>one\n"</tt></td>
</tr>
<tr>
  <td><tt>$.</tt></td>
  <td>&#187;</td>
  <td><tt>1</tt></td>
</tr>
<tr>
<td colspan="3"><tt>f.lineno<nbsp/>=<nbsp/>1000</tt></td>
</tr>
<tr>
  <td><tt>f.lineno</tt></td>
  <td>&#187;</td>
  <td><tt>1000</tt></td>
</tr>
<tr>
  <td><tt>$.<nbsp/>#<nbsp/>lineno<nbsp/>of<nbsp/>last<nbsp/>read</tt></td>
  <td>&#187;</td>
  <td><tt>1</tt></td>
</tr>
<tr>
  <td><tt>f.gets</tt></td>
  <td>&#187;</td>
  <td><tt>"This<nbsp/>is<nbsp/>line<nbsp/>two\n"</tt></td>
</tr>
<tr>
  <td><tt>$.<nbsp/>#<nbsp/>lineno<nbsp/>of<nbsp/>last<nbsp/>read</tt></td>
  <td>&#187;</td>
  <td><tt>1001</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="pid" ref="pid">
      <callseq>
        <em>ios</em>.pid <returns><obj>aFixnum</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the process ID of a child process associated with
      <em>ios</em>. This will be set by <ccm><file>io</file><front>IO</front><back>popen</back><mref>popen</mref></ccm>.      
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        pipe = IO.popen("-")
        if pipe
          $stderr.puts "In parent, child pid is #{pipe.pid}"
!-          pipe.close
        else
          $stderr.puts "In child, pid is #{$$}"
        end
]]></fullcode>
pipe<nbsp/>=<nbsp/>IO.popen("-")
if<nbsp/>pipe
<nbsp/><nbsp/>$stderr.puts<nbsp/>"In<nbsp/>parent,<nbsp/>child<nbsp/>pid<nbsp/>is<nbsp/>#{pipe.pid}"
else
<nbsp/><nbsp/>$stderr.puts<nbsp/>"In<nbsp/>child,<nbsp/>pid<nbsp/>is<nbsp/>#{$$}"
end
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
In<nbsp/>parent,<nbsp/>child<nbsp/>pid<nbsp/>is<nbsp/>15545
In<nbsp/>child,<nbsp/>pid<nbsp/>is<nbsp/>15545
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="pos" ref="pos">
      <callseq>
        <em>ios</em>.pos <returns><obj>anInteger</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the current offset (in bytes) of <em>ios</em>.
<p/>
<codefragment>
<fullcode><![CDATA[        f = File.new("testfile")
        f.pos
        f.gets 
        f.pos
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>f<nbsp/>=<nbsp/>File.new("testfile")</tt></td>
</tr>
<tr>
  <td><tt>f.pos</tt></td>
  <td>&#187;</td>
  <td><tt>0</tt></td>
</tr>
<tr>
  <td><tt>f.gets</tt></td>
  <td>&#187;</td>
  <td><tt>"This<nbsp/>is<nbsp/>line<nbsp/>one\n"</tt></td>
</tr>
<tr>
  <td><tt>f.pos</tt></td>
  <td>&#187;</td>
  <td><tt>17</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="pos=" ref="pos_eq">
      <callseq>
        <em>ios</em>.pos = <obj>anInteger</obj>
        <returns>0</returns>
      </callseq>
      <desc>
<p/>
      Seeks to the given position (in bytes) in <em>ios</em>.
<p/>
<codefragment>
<fullcode><![CDATA[        f = File.new("testfile")
        f.pos = 17
        f.gets
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>f<nbsp/>=<nbsp/>File.new("testfile")</tt></td>
</tr>
<tr>
<td colspan="3"><tt>f.pos<nbsp/>=<nbsp/>17</tt></td>
</tr>
<tr>
  <td><tt>f.gets</tt></td>
  <td>&#187;</td>
  <td><tt>"This<nbsp/>is<nbsp/>line<nbsp/>two\n"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="print" ref="print">
      <callseq>
        <em>ios</em>.print( <optz><obj>anObject</obj>=<var>$_</var></optz> )
        <returns><tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
            Writes the given object(s) to <em>ios</em>.  The stream must be
      opened for writing.
      If the output record separator
      (<var>$\</var>)
      is not <tt>nil</tt>, it will be appended to the output. If 
      no arguments are given, prints <var>$_</var>. Objects that aren't
      strings will be converted by calling their <meth>to_s</meth> method.
      Returns <tt>nil</tt>.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        $stdout.print("This is ", 100, " percent.\n")
]]></fullcode>
$stdout.print("This<nbsp/>is<nbsp/>",<nbsp/>100,<nbsp/>"<nbsp/>percent.\n")
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
This<nbsp/>is<nbsp/>100<nbsp/>percent.
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="printf" ref="printf">
      <callseq>
        <em>ios</em>.printf( <obj>aFormatString</obj> 
                <optz>, <obj>anObject</obj></optz> )
       <returns><tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
           Formats and writes to <em>ios</em>, converting parameters under
     control of the format string. See <mim><file>kernel</file><front>Kernel</front><back>sprintf</back><mref>sprintf</mref></mim>
     on page 427 for details.
<p/>
      </desc>
    </method>
<p/>
        <method name="putc" ref="putc">
      <callseq>
        <em>ios</em>.putc( <obj>anObject</obj> )
        <returns><obj>anObject</obj></returns>
      </callseq>
      <desc>
<p/>
            Writes the given character (taken from a <classname>String</classname> or a <classname>Fixnum</classname>) 
      on <em>ios</em>.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        $stdout.putc "A"
        $stdout.putc 65
]]></fullcode>
$stdout.putc<nbsp/>"A"
$stdout.putc<nbsp/>65
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
AA
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="puts" ref="puts">
      <callseq>
        <em>ios</em>.puts( <optz><obj>anObject</obj></optz> )
        <returns><tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Writes the given objects to <em>ios</em> as with
      <cim><file>io</file><front>IO</front><back>print</back><mref>print</mref></cim>. 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.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        $stdout.puts("this", "is", "a", "test")
]]></fullcode>
$stdout.puts("this",<nbsp/>"is",<nbsp/>"a",<nbsp/>"test")
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
this
is
a
test
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="read" ref="read">
      <callseq>
        <em>ios</em>.read( <opt><obj>anInteger</obj></opt> )
        <returns><obj>aString</obj> or <tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Reads at most <obj>anInteger</obj> bytes from the I/O stream, or to the
      end of file if <obj>anInteger</obj> is omitted.
      Returns <tt>nil</tt> if called at end of file.
<p/>
<codefragment>
<fullcode><![CDATA[        f = File.new("testfile")
        f.read(16)
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>f<nbsp/>=<nbsp/>File.new("testfile")</tt></td>
</tr>
<tr>
  <td><tt>f.read(16)</tt></td>
  <td>&#187;</td>
  <td><tt>"This<nbsp/>is<nbsp/>line<nbsp/>one"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="readchar" ref="readchar">
      <callseq>
        <em>ios</em>.readchar <returns><obj>aFixnum</obj></returns>
      </callseq>
      <desc>
<p/>
      Reads a character as with <cim><file>io</file><front>IO</front><back>getc</back><mref>getc</mref></cim>, but raises an <exception>EOFError</exception> 
      on end of file.
<p/>
      </desc>
    </method>
<p/>
        <method name="readline" ref="readline">
      <callseq>
        <em>ios</em>.readline( <obj>aSepString</obj>=<var>$/</var> )
        <returns><obj>aString</obj></returns>
      </callseq>
      <desc>
<p/>
      Reads a line as with <cim><file>io</file><front>IO</front><back>gets</back><mref>gets</mref></cim>, but raises an <exception>EOFError</exception> 
      on end of file.
<p/>
      </desc>
    </method>
<p/>
        <method name="readlines" ref="readlines">
      <callseq>
        <em>ios</em>.readlines(
        <obj>aSepString</obj>=<var>$/</var> )
        <returns><obj>anArray</obj></returns>
      </callseq>
      <desc>
<p/>
      Reads all of the lines in <em>ios</em>, and returns them in
      <obj>anArray</obj>.
      Lines are separated by the
      optional <obj>aSepString</obj>.
      The stream must be opened for reading or an
      <exception>IOerror</exception> will be raised.
<p/>
<codefragment>
<fullcode><![CDATA[        f = File.new("testfile")
        f.readlines[0]
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>f<nbsp/>=<nbsp/>File.new("testfile")</tt></td>
</tr>
<tr>
  <td><tt>f.readlines[0]</tt></td>
  <td>&#187;</td>
  <td><tt>"This<nbsp/>is<nbsp/>line<nbsp/>one\n"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="reopen" ref="reopen">
      <callseq>
                        <em>ios</em>.reopen( <obj>anOtherIO</obj> ) <returns><em>ios</em></returns> <br/><em>ios</em>.reopen( <obj>aPath</obj>, <obj>aModeStr</obj> ) <returns><em>ios</em></returns>
      </callseq>
      <desc>
<p/>
      Reassociates
      <em>ios</em> with the I/O stream given in <obj>anOtherIO</obj> or to a
      new stream opened on <obj>aPath</obj>.  This may dynamically change
      the actual class of this stream.
<p/>
<codefragment>
<fullcode><![CDATA[        f1 = File.new("testfile")
        f2 = File.new("testfile")
        f2.readlines[0]
        f2.reopen(f1)
        f2.readlines[0]
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>f1<nbsp/>=<nbsp/>File.new("testfile")</tt></td>
</tr>
<tr>
<td colspan="3"><tt>f2<nbsp/>=<nbsp/>File.new("testfile")</tt></td>
</tr>
<tr>
  <td><tt>f2.readlines[0]</tt></td>
  <td>&#187;</td>
  <td><tt>"This<nbsp/>is<nbsp/>line<nbsp/>one\n"</tt></td>
</tr>
<tr>
  <td><tt>f2.reopen(f1)</tt></td>
  <td>&#187;</td>
  <td><tt>#&lt;File:0x4018d608&gt;</tt></td>
</tr>
<tr>
  <td><tt>f2.readlines[0]</tt></td>
  <td>&#187;</td>
  <td><tt>"This<nbsp/>is<nbsp/>line<nbsp/>one\n"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="rewind" ref="rewind">
      <callseq>
        <em>ios</em>.rewind <returns>0</returns>
      </callseq>
      <desc>
<p/>
      Positions <em>ios</em> to the beginning of input, resetting
      <meth>lineno</meth> to zero.
<p/>
<codefragment>
<fullcode><![CDATA[        f = File.new("testfile")
        f.readline
        f.rewind
        f.lineno
        f.readline
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>f<nbsp/>=<nbsp/>File.new("testfile")</tt></td>
</tr>
<tr>
  <td><tt>f.readline</tt></td>
  <td>&#187;</td>
  <td><tt>"This<nbsp/>is<nbsp/>line<nbsp/>one\n"</tt></td>
</tr>
<tr>
  <td><tt>f.rewind</tt></td>
  <td>&#187;</td>
  <td><tt>0</tt></td>
</tr>
<tr>
  <td><tt>f.lineno</tt></td>
  <td>&#187;</td>
  <td><tt>0</tt></td>
</tr>
<tr>
  <td><tt>f.readline</tt></td>
  <td>&#187;</td>
  <td><tt>"This<nbsp/>is<nbsp/>line<nbsp/>one\n"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="seek" ref="seek">
      <callseq>
        <em>ios</em>.seek( <obj>anInteger</obj>,
        <obj>whence</obj>=<tt>SEEK_SET</tt> )
        <returns>0</returns>
      </callseq>
      <desc>
<p/>
      Seeks to a given offset <obj>anInteger</obj> in the stream according
      to the value of <obj>whence</obj>:
<p/>
      <table>
<p/>
        <toprule/><tr>
  <td><classconst><file>io</file><front>IO</front><back>SEEK_CUR</back><mref>SEEK_CUR</mref></classconst></td>
  <td>Seeks to <obj>anInteger</obj> plus current position.</td>
</tr>
<tr>
  <td><classconst><file>io</file><front>IO</front><back>SEEK_END</back><mref>SEEK_END</mref></classconst></td>
  <td>Seeks to <obj>anInteger</obj> plus end of stream (you probably 
              want a negative value for <obj>anInteger</obj>).</td>
</tr>
<tr>
  <td><classconst><file>io</file><front>IO</front><back>SEEK_SET</back><mref>SEEK_SET</mref></classconst></td>
  <td>Seeks to the absolute location given by
              <obj>anInteger</obj>.</td>
</tr>
<bottomrule/></table>
<p/>
<codefragment>
<fullcode><![CDATA[        f = File.new("testfile")
        f.seek(-13, IO::SEEK_END)
        f.readline
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>f<nbsp/>=<nbsp/>File.new("testfile")</tt></td>
</tr>
<tr>
  <td><tt>f.seek(-13,<nbsp/>IO::SEEK_END)</tt></td>
  <td>&#187;</td>
  <td><tt>0</tt></td>
</tr>
<tr>
  <td><tt>f.readline</tt></td>
  <td>&#187;</td>
  <td><tt>"And<nbsp/>so<nbsp/>on...\n"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="stat" ref="stat">
      <callseq>
        <em>ios</em>.stat <returns><obj>aStat</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns status information for <em>ios</em> as an object of
      type <classname>File::Stat</classname>.  
<p/>
<codefragment>
<fullcode><![CDATA[        f = File.new("testfile")
        s = f.stat
        "%o" % s.mode
        s.blksize
        s.atime
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>f<nbsp/>=<nbsp/>File.new("testfile")</tt></td>
</tr>
<tr>
<td colspan="3"><tt>s<nbsp/>=<nbsp/>f.stat</tt></td>
</tr>
<tr>
  <td><tt>"%o"<nbsp/>%<nbsp/>s.mode</tt></td>
  <td>&#187;</td>
  <td><tt>"100644"</tt></td>
</tr>
<tr>
  <td><tt>s.blksize</tt></td>
  <td>&#187;</td>
  <td><tt>4096</tt></td>
</tr>
<tr>
  <td><tt>s.atime</tt></td>
  <td>&#187;</td>
  <td><tt>Sun<nbsp/>Mar<nbsp/>04<nbsp/>23:28:52<nbsp/>CST<nbsp/>2001</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="sync" ref="sync">
      <callseq>
        <em>ios</em>.sync 
                <returns><const>true</const> or <const>false</const></returns>
      </callseq>
      <desc>
<p/>
      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.
<p/>
<codefragment>
<fullcode><![CDATA[        f = File.new("testfile")
        f.sync
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>f<nbsp/>=<nbsp/>File.new("testfile")</tt></td>
</tr>
<tr>
  <td><tt>f.sync</tt></td>
  <td>&#187;</td>
  <td><tt>false</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="sync=" ref="sync_eq">
      <callseq>
        <em>ios</em>.sync = <obj>aBoolean</obj>
        <returns><obj>aBoolean</obj></returns>
      </callseq>
      <desc>
<p/>
      Sets the ``sync mode'' to <const>true</const> or <const>false</const>.  When
      sync mode is true, all output is immediately flushed to the
      underlying operating system and is not buffered internally.
      Returns the new state.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        f = File.new("testfile")
        f.sync = true
]]></fullcode>
f<nbsp/>=<nbsp/>File.new("testfile")
f.sync<nbsp/>=<nbsp/>true
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="sysread" ref="sysread">
      <callseq>
        <em>ios</em>.sysread( <obj>anInteger</obj> )
        <returns><obj>aString</obj></returns>
      </callseq>
      <desc>
              Reads <obj>anInteger</obj> 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 <exception>SystemCallError</exception> on error and <exception>EOFError</exception> at end of
      file.
<p/>
<codefragment>
<fullcode><![CDATA[        f = File.new("testfile")
        f.sysread(16)
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>f<nbsp/>=<nbsp/>File.new("testfile")</tt></td>
</tr>
<tr>
  <td><tt>f.sysread(16)</tt></td>
  <td>&#187;</td>
  <td><tt>"This<nbsp/>is<nbsp/>line<nbsp/>one"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="syswrite" ref="syswrite">
      <callseq>
        <em>ios</em>.syswrite( <obj>aString</obj> )
        <returns><obj>anInteger</obj></returns>
      </callseq>
      <desc>
<p/>
      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 <exception>SystemCallError</exception> on error.
<p/>
<codefragment>
<fullcode><![CDATA[        f = File.new("out", "w")
        f.syswrite("ABCDEF")
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>f<nbsp/>=<nbsp/>File.new("out",<nbsp/>"w")</tt></td>
</tr>
<tr>
  <td><tt>f.syswrite("ABCDEF")</tt></td>
  <td>&#187;</td>
  <td><tt>6</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="tell" ref="tell">
      <callseq>
        <em>ios</em>.tell <returns><obj>anInteger</obj></returns>
      </callseq>
      <desc>
<p/>
      Synonym for <cim><file>io</file><front>IO</front><back>pos</back><mref>pos</mref></cim>.
<p/>
      </desc>
    </method>
<p/>
        <method name="to_i" ref="to_i">
      <callseq>
        <em>ios</em>.to_i <returns><obj>anInteger</obj></returns>
      </callseq>
      <desc>
<p/>
      Synonym for <cim><file>io</file><front>IO</front><back>fileno</back><mref>fileno</mref></cim>.
<p/>
      </desc>
    </method>
<p/>
        <method name="to_io" ref="to_io">
      <callseq>
        <em>ios</em>.to_io <returns><em>ios</em></returns>
      </callseq>
      <desc>
<p/>
      Returns <em>ios</em>.
<p/>
      </desc>
    </method>
<p/>
        <method name="tty?" ref="tty_qm">
      <callseq>
        <em>ios</em>.tty? 
                <returns><const>true</const> or <const>false</const></returns>
      </callseq>
      <desc>
<p/>
      Synonym for <cim><file>io</file><front>IO</front><back>isatty</back><mref>isatty</mref></cim>.
<p/>
      </desc>
    </method>
<p/>
        <method name="ungetc" ref="ungetc">
      <callseq>
        <em>ios</em>.ungetc( <obj>anInteger</obj> )
        <returns><tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Pushes back one character 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
      <cim><file>io</file><front>IO</front><back>sysread</back><mref>sysread</mref></cim>).
<p/>
<codefragment>
<fullcode><![CDATA[        f = File.new("testfile")
        c = f.getc
        f.ungetc(c)
        f.getc
]]></fullcode><rubycode>
<tr>
  <td><tt>f<nbsp/>=<nbsp/>File.new("testfile")</tt></td>
  <td>&#187;</td>
  <td><tt>#&lt;File:0x4018d66c&gt;</tt></td>
</tr>
<tr>
  <td><tt>c<nbsp/>=<nbsp/>f.getc</tt></td>
  <td>&#187;</td>
  <td><tt>84</tt></td>
</tr>
<tr>
  <td><tt>f.ungetc(c)</tt></td>
  <td>&#187;</td>
  <td><tt>nil</tt></td>
</tr>
<tr>
  <td><tt>f.getc</tt></td>
  <td>&#187;</td>
  <td><tt>84</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="write" ref="write">
      <callseq>
        <em>ios</em>.write( <obj>aString</obj> )
        <returns><obj>anInteger</obj></returns>
      </callseq>
      <desc>
<p/>
            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 
      <meth>to_s</meth>.  Returns the number of bytes written.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        count = $stdout.write( "This is a test\n" )
        puts "That was #{count} bytes of data"
]]></fullcode>
count<nbsp/>=<nbsp/>$stdout.write(<nbsp/>"This<nbsp/>is<nbsp/>a<nbsp/>test\n"<nbsp/>)
puts<nbsp/>"That<nbsp/>was<nbsp/>#{count}<nbsp/>bytes<nbsp/>of<nbsp/>data"
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
This<nbsp/>is<nbsp/>a<nbsp/>test
That<nbsp/>was<nbsp/>15<nbsp/>bytes<nbsp/>of<nbsp/>data
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
  </methods>
<p/>
</class>
</ppdoc>