<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="File" super="IO" type="class">    
<p/>
  A <classname>File</classname> is an abstraction of any file object accessible by the
  program and is closely associated with class <classname>IO</classname>, page
  329. <classname>File</classname> includes the methods of module
  <modulename>FileTest</modulename> as class methods, allowing you to write (for example)
  <tt>File.exist?("foo")</tt>.
<p/>
  In this section, <em>permission bits</em>  
  are a platform-specific set of bits that indicate permissions of a
  file.  On Unix-based systems, permissions are viewed as a set of
  three octets, for the owner, the group, and the rest of the world.  For
  each of these entities, permissions may be set to read, write, or
  execute (or search, if a directory) the file:
<p/>
  <center>
    <table>
<tr>
<td colspan="3">Owner</td>
<td colspan="3">Group</td>
<td colspan="3">Other</td>
</tr>
<tr>
  <td>r</td>
  <td>w</td>
  <td>x</td>
  <td>r</td>
  <td>w</td>
  <td>x</td>
  <td>r</td>
  <td>w</td>
  <td>x</td>
</tr>
<tr>
  <td>4</td>
  <td>2</td>
  <td>1</td>
  <td>4</td>
  <td>2</td>
  <td>1</td>
  <td>4</td>
  <td>2</td>
  <td>1</td>
</tr>
</table>
<p/>
  </center>
<p/>
  The permission bits <tt>0644</tt> (in octal) would thus be interpreted as
  read/write for owner, and read-only for group and other.  Higher-order bits
  may also be used to indicate the type of file (plain, directory,
  pipe, socket, and so on) and various other special features.
<p/>
  On non-Posix operating systems, there may be only the ability to make a
  file read-only or not.  In this case, the remaining permission bits
  will be synthesized to resemble typical values.  For instance, on
  Windows NT the default permission bits are <tt>0644</tt>, which means
  read/write for owner, read-only for all others.  The only change
  that can be made is to make the file read-only, which is reported as
  <tt>0444</tt>.
  <mixins>
    <mixin name="FileTest">
   blockdev?, chardev?, directory?, executable?, executable_real?,
   exist?, exists?, file?, grpowned?, owned?, pipe?, readable?,
   readable_real?, setgid?, setuid?, size, size?, socket?, sticky?,
   symlink?, writable?, writable_real?, zero?</mixin>
  </mixins>
<p/>
  <methods type="class">
<p/>
        <method name="atime" ref="atime">
      <callseq>
        File.atime( <obj>fileName</obj> )
        <returns><obj>aTime</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the last access time for the named file.
<p/>
<codefragment>
<fullcode><![CDATA[        File.atime("testfile")
]]></fullcode><rubycode>
<tr>
  <td><tt>File.atime("testfile")</tt></td>
  <td>&#187;</td>
  <td><tt>Sun<nbsp/>Mar<nbsp/>04<nbsp/>23:25:54<nbsp/>CST<nbsp/>2001</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="basename" ref="basename">
      <callseq>
        File.basename( <obj>fileName</obj> <opt>, <obj>aSuffix</obj></opt> )
        <returns><obj>aNewString</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the last component of the filename given in
      <obj>fileName</obj>, which must be formed using forward slashes
      (``<tt>/</tt>'') regardless of the separator used on the local
      file system.  If <obj>aSuffix</obj> is given and present at the end
      of <obj>fileName</obj>, it is removed.
<p/>
<codefragment>
<fullcode><![CDATA[        File.basename("/home/gumby/work/ruby.rb")
        File.basename("/home/gumby/work/ruby.rb", ".rb")
]]></fullcode><rubycode>
<tr>
  <td><tt>File.basename("/home/gumby/work/ruby.rb")</tt></td>
  <td>&#187;</td>
  <td><tt>"ruby.rb"</tt></td>
</tr>
<tr>
  <td><tt>File.basename("/home/gumby/work/ruby.rb",<nbsp/>".rb")</tt></td>
  <td>&#187;</td>
  <td><tt>"ruby"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="chmod" ref="chmod">
      <callseq>
        File.chmod( <obj>aModeInt</obj> <optn>, <obj>fileName</obj></optn> )
        <returns><obj>anInteger</obj></returns>
      </callseq>
      <desc>
<p/>
      Changes permission bits on the
      named file(s) to the bit pattern represented by <obj>aModeInt</obj>.
      Actual effects are operating system dependent (see the beginning
      of this section).  On Unix systems, see <tt>chmod(2)</tt> for
      details.  Returns the number of files processed.
<p/>
<codefragment>
<fullcode><![CDATA[!-          f = File.new("out", "w");
!-          f.close
        File.chmod(0644, "testfile", "out")
!-          File.delete("out");
]]></fullcode><rubycode>
<tr>
  <td><tt>File.chmod(0644,<nbsp/>"testfile",<nbsp/>"out")</tt></td>
  <td>&#187;</td>
  <td><tt>2</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="chown" ref="chown">
      <callseq>
        File.chown( <obj>anOwnerInt</obj>,
        <obj>aGroupInt</obj> <optn>, <obj>fileName</obj></optn> )
        <returns><obj>anInteger</obj></returns>
      </callseq>
      <desc>
<p/>
      Changes the owner and group of the named file(s) to the given
      numeric owner and group id's.      
      Only a process with superuser
      privileges may change the owner of a file.  The current owner of
      a file may change the file's group to any group to which the
      owner belongs.  A <tt>nil</tt> or -1 owner or group id is
      ignored.
        Returns the number of files processed.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        File.chown(nil, 100, "testfile")
]]></fullcode>
File.chown(nil,<nbsp/>100,<nbsp/>"testfile")
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="ctime" ref="ctime">
      <callseq>
        File.ctime( <obj>fileName</obj> )
        <returns><obj>aTime</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the change time for the named file (the time at which
      directory information about the file was changed, not the file
      itself).
<p/>
<codefragment>
<fullcode><![CDATA[        File.ctime("testfile")
]]></fullcode><rubycode>
<tr>
  <td><tt>File.ctime("testfile")</tt></td>
  <td>&#187;</td>
  <td><tt>Sun<nbsp/>Mar<nbsp/>04<nbsp/>23:28:25<nbsp/>CST<nbsp/>2001</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="delete" ref="delete">
      <callseq>
        File.delete( <optn><obj>fileName</obj></optn> )
        <returns><obj>aFixnum</obj></returns>
      </callseq>
      <desc>
<p/>
      Deletes the named file(s).
        Returns the number of files processed.
      See also <ccm><file>dir</file><front>Dir</front><back>rmdir</back><mref>rmdir</mref></ccm>.
<p/>
<codefragment>
<fullcode><![CDATA[        File.new("testrm", "w+").close
        File.delete("testrm")
]]></fullcode><rubycode>
<tr>
  <td><tt>File.new("testrm",<nbsp/>"w+").close</tt></td>
  <td>&#187;</td>
  <td><tt>nil</tt></td>
</tr>
<tr>
  <td><tt>File.delete("testrm")</tt></td>
  <td>&#187;</td>
  <td><tt>1</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="dirname" ref="dirname">
      <callseq>
        File.dirname( <obj>fileName</obj> )
        <returns><obj>fileName</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns all components of the filename given in
      <obj>fileName</obj> except the last one.  The filename must be
      formed using forward slashes (``<tt>/</tt>'') regardless of the
      separator used on the local file system.
<p/>
<codefragment>
<fullcode><![CDATA[        File.dirname("/home/gumby/work/ruby.rb")
]]></fullcode><rubycode>
<tr>
  <td><tt>File.dirname("/home/gumby/work/ruby.rb")</tt></td>
  <td>&#187;</td>
  <td><tt>"/home/gumby/work"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="expand_path" ref="expand_path">
      <callseq>
        File.expand_path( <obj>fileName</obj>
        <opt>, <obj>aDirString</obj></opt> )
        <returns><obj>fileName</obj></returns>
      </callseq>
      <desc>
<p/>
      Converts a pathname to an absolute pathname.      
      Relative paths
      are referenced from the current working directory of the process 
      unless <obj>aDirString</obj> is given, in which case it will be used 
      as the starting point.  The given pathname may start with a
      ``<tt>~</tt>'', which expands to the process owner's home directory
      (the environment variable <tt>HOME</tt>      
      must be set correctly).
      ``<tt>~</tt><obj>user</obj>'' expands to the named user's home
      directory.
<p/>
<codefragment>
<fullcode><![CDATA[        File.expand_path("~oracle/bin")
        File.expand_path("../../bin", "/tmp/x")
]]></fullcode><rubycode>
<tr>
  <td><tt>File.expand_path("~oracle/bin")</tt></td>
  <td>&#187;</td>
  <td><tt>"/home/oracle/bin"</tt></td>
</tr>
<tr>
  <td><tt>File.expand_path("../../bin",<nbsp/>"/tmp/x")</tt></td>
  <td>&#187;</td>
  <td><tt>"/bin"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="ftype" ref="ftype">
      <callseq>
        File.ftype( <obj>fileName</obj> )
        <returns><obj>fileType</obj></returns>
      </callseq>
      <desc>
<p/>
      Identifies the type of the named file;
      the return string is one of 
        ``<tt>file</tt>'',
        ``<tt>directory</tt>'',
        ``<tt>characterSpecial</tt>'',
        ``<tt>blockSpecial</tt>'',
        ``<tt>fifo</tt>'',
        ``<tt>link</tt>'', or
        ``<tt>socket</tt>''.
<p/>
<codefragment>
<fullcode><![CDATA[        File.ftype("testfile")
        File.ftype("/dev/tty")
        File.ftype("/tmp/.X11-unix/X0")
]]></fullcode><rubycode>
<tr>
  <td><tt>File.ftype("testfile")</tt></td>
  <td>&#187;</td>
  <td><tt>"file"</tt></td>
</tr>
<tr>
  <td><tt>File.ftype("/dev/tty")</tt></td>
  <td>&#187;</td>
  <td><tt>"characterSpecial"</tt></td>
</tr>
<tr>
  <td><tt>File.ftype("/tmp/.X11-unix/X0")</tt></td>
  <td>&#187;</td>
  <td><tt>"socket"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="join" ref="join">
      <callseq>
        File.join( <optn><obj>aString</obj></optn> )
        <returns><obj>fileName</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns a new string formed by joining the strings
      using <classconst><file>file</file><front>File</front><back>SEPARATOR</back><mref>SEPARATOR</mref></classconst> (see Table 22.2 on page 308).
<p/>
<codefragment>
<fullcode><![CDATA[        File.join("usr", "mail", "gumby")
]]></fullcode><rubycode>
<tr>
  <td><tt>File.join("usr",<nbsp/>"mail",<nbsp/>"gumby")</tt></td>
  <td>&#187;</td>
  <td><tt>"usr/mail/gumby"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
  <figure type="table">
    <caption>Path separator constants (platform-specific)</caption>    
    <table>
<p/>
      <toprule/><tr>
  <td><tt>ALT_SEPARATOR</tt></td>
  <td>Alternate path separator.</td>
</tr>
<tr>
  <td><tt>PATH_SEPARATOR</tt></td>
  <td>Character that separates filenames in 
        a search path (such as ``:'' or ``;'').</td>
</tr>
<tr>
  <td><tt>SEPARATOR</tt></td>
  <td>Character that separates directory
        components in a filename (such as ``\'' or ``/'').</td>
</tr>
<tr>
  <td><tt>Separator</tt></td>
  <td>Alias for <const>SEPARATOR</const>.</td>
</tr>
<bottomrule/></table>
<p/>
  </figure>
<p/>
        <method name="link" ref="link">
      <callseq>
        File.link( <obj>anOldName</obj>, <obj>aNewName</obj> )
        <returns>0</returns>
      </callseq>
      <desc>
<p/>
      Creates a new name for an existing file using a hard link.
      Will not overwrite <obj>aNewName</obj> if it already exists (raising
      a subclass of <exception>SystemCallError</exception>).
      Not available on all platforms.
<p/>
<codefragment>
<fullcode><![CDATA[        File.link("testfile", ".testfile")
        IO.readlines(".testfile")[0]
!-          File.delete(".testfile");
]]></fullcode><rubycode>
<tr>
  <td><tt>File.link("testfile",<nbsp/>".testfile")</tt></td>
  <td>&#187;</td>
  <td><tt>0</tt></td>
</tr>
<tr>
  <td><tt>IO.readlines(".testfile")[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="lstat" ref="lstat">
      <callseq>
        File.lstat( <obj>fileName</obj> )
        <returns><obj>aStat</obj></returns>
      </callseq>
      <desc>
<p/>
      Same as <cim><file>io</file><front>IO</front><back>stat</back><mref>stat</mref></cim>, but does not follow the last symbolic link.
      Instead, reports on the link itself.
<p/>
<codefragment>
<fullcode><![CDATA[        File.symlink("testfile", "link2test")
        File.stat("testfile").size
        File.lstat("link2test").size
        File.stat("link2test").size
!-          File.delete("link2test");
]]></fullcode><rubycode>
<tr>
  <td><tt>File.symlink("testfile",<nbsp/>"link2test")</tt></td>
  <td>&#187;</td>
  <td><tt>0</tt></td>
</tr>
<tr>
  <td><tt>File.stat("testfile").size</tt></td>
  <td>&#187;</td>
  <td><tt>66</tt></td>
</tr>
<tr>
  <td><tt>File.lstat("link2test").size</tt></td>
  <td>&#187;</td>
  <td><tt>8</tt></td>
</tr>
<tr>
  <td><tt>File.stat("link2test").size</tt></td>
  <td>&#187;</td>
  <td><tt>66</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="mtime" ref="mtime">
      <callseq>
        File.mtime( <obj>fileName</obj> )
        <returns><obj>aTime</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the modification time for the named file.
<p/>
<codefragment>
<fullcode><![CDATA[        File.mtime("testfile")
]]></fullcode><rubycode>
<tr>
  <td><tt>File.mtime("testfile")</tt></td>
  <td>&#187;</td>
  <td><tt>Tue<nbsp/>Feb<nbsp/>27<nbsp/>00:11:18<nbsp/>CST<nbsp/>2001</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="new" ref="new">
      <callseq>
                File.new( <obj>fileName</obj>, <obj>aModeString</obj>="r" )
          <returns><obj>file</obj></returns><br/>File.new( <obj>fileName</obj> <opt>, <obj>aModeNum</obj> <opt><obj>aPermNum</obj></opt></opt> ) 
          <returns><obj>file</obj></returns>
      </callseq>
      <desc>
              Opens the file named by <obj>fileName</obj> according to
      <obj>aModeString</obj> (default is ``r'') and returns a new <classname>File</classname>
      object.  See Table 22.5 on page 331 for a description
      of <obj>aModeString</obj>.  The file mode may optionally be specified
      as a <classname>Fixnum</classname> by <em>or</em>-ing together the flags described in 
      Table 22.3 on page 309.
      Optional permission bits may be given in 
      <obj>aPermNum</obj>.  These mode and permission bits are platform
      dependent; on Unix systems, see <tt>open(2)</tt> for details.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        f = File.new("testfile", "r")
        f = File.new("newfile",  "w+")
        f = File.new("newfile", File::CREAT|File::TRUNC|File::RDWR, 0644)
]]></fullcode>
f<nbsp/>=<nbsp/>File.new("testfile",<nbsp/>"r")
f<nbsp/>=<nbsp/>File.new("newfile",<nbsp/><nbsp/>"w+")
f<nbsp/>=<nbsp/>File.new("newfile",<nbsp/>File::CREAT|File::TRUNC|File::RDWR,<nbsp/>0644)
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
  <figure type="table">
    <caption>Open-mode constants</caption>    
    <table>
<p/>
      <toprule/><tr>
  <td><tt>APPEND</tt></td>
  <td>Open the file in append mode; all writes will occur at
      end of file.</td>
</tr>
<tr>
  <td><tt>CREAT</tt></td>
  <td>Create the file on open if it does not exist.</td>
</tr>
<tr>
  <td><tt>EXCL</tt></td>
  <td>When used with CREAT, open will fail if the file exists.</td>
</tr>
<tr>
  <td><tt>NOCTTY</tt></td>
  <td>When opening a terminal device (see
      <cim><file>io</file><front>IO</front><back>isatty</back><mref>isatty</mref></cim> on page 335), do not allow it to 
      become the controlling terminal.</td>
</tr>
<tr>
  <td><tt>NONBLOCK</tt></td>
  <td>Open the file in nonblocking mode.</td>
</tr>
<tr>
  <td><tt>RDONLY</tt></td>
  <td>Open for reading only.</td>
</tr>
<tr>
  <td><tt>RDWR</tt></td>
  <td>Open for reading and writing.</td>
</tr>
<tr>
  <td><tt>TRUNC</tt></td>
  <td>Open the file and truncate it to zero length
      if the file exists.</td>
</tr>
<tr>
  <td><tt>WRONLY</tt></td>
  <td>Open for writing only.</td>
</tr>
<bottomrule/></table>
<p/>
  </figure>
<p/>
        <method name="open" ref="open">
      <callseq>
                File.open( <obj>fileName</obj>, <obj>aModeString</obj>="r" )
          <returns><obj>file</obj></returns><br/>File.open( <obj>fileName</obj> <opt>, <obj>aModeNum</obj> <opt><obj>aPermNum</obj></opt></opt> ) 
          <returns><obj>file</obj></returns><br/>File.open( <obj>fileName</obj>, <obj>aModeString</obj>="r" )
          <block>{| <obj>file</obj> | <blockbody>block</blockbody> }</block>
 <returns><tt>nil</tt></returns><br/>File.open( <obj>fileName</obj> <opt>, <obj>aModeNum</obj> <opt><obj>aPermNum</obj></opt></opt> ) 
          <block>{| <obj>file</obj> | <blockbody>block</blockbody> }</block>
 <returns><tt>nil</tt></returns><br/>
      </callseq>
      <desc>
<p/>
      With no associated block, <meth>open</meth> is a synonym for <ccm><file>file</file><front>File</front><back>new</back><mref>new</mref></ccm>.
     If the optional code block is given, it will be passed <obj>file</obj>
     as an argument, and the file will automatically be closed when
     the block terminates. In this instance, <ccm><file>file</file><front>File</front><back>open</back><mref>open</mref></ccm> returns <tt>nil</tt>.
<p/>
      </desc>
    </method>
<p/>
        <method name="readlink" ref="readlink">
      <callseq>
        File.readlink( <obj>fileName</obj> )
        <returns><obj>fileName</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the given symbolic link as a string.
      Not available on all platforms.
<p/>
<codefragment>
<fullcode><![CDATA[        File.symlink("testfile", "link2test")
        File.readlink("link2test")
!-          File.delete("link2test");
]]></fullcode><rubycode>
<tr>
  <td><tt>File.symlink("testfile",<nbsp/>"link2test")</tt></td>
  <td>&#187;</td>
  <td><tt>0</tt></td>
</tr>
<tr>
  <td><tt>File.readlink("link2test")</tt></td>
  <td>&#187;</td>
  <td><tt>"testfile"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="rename" ref="rename">
      <callseq>
        File.rename( <obj>anOldName</obj>, <obj>aNewName</obj> )
        <returns>0</returns>
      </callseq>
      <desc>
<p/>
      Renames the given file to the new name.
      Raises a <exception>SystemCallError</exception> if the file cannot be renamed.
<p/>
<codefragment>
<fullcode><![CDATA[!-          File.link("testfile", "afile")
        File.rename("afile", "afile.bak")
!-          File.delete("afile.bak")
]]></fullcode><rubycode>
<tr>
  <td><tt>File.rename("afile",<nbsp/>"afile.bak")</tt></td>
  <td>&#187;</td>
  <td><tt>0</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="size" ref="size">
      <callseq>
        File.size( <obj>fileName</obj> )
        <returns><obj>anInteger</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the size of the file in bytes.
<p/>
<codefragment>
<fullcode><![CDATA[        File.size("testfile")
]]></fullcode><rubycode>
<tr>
  <td><tt>File.size("testfile")</tt></td>
  <td>&#187;</td>
  <td><tt>66</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="split" ref="split">
      <callseq>
        File.split( <obj>fileName</obj> )
        <returns><obj>anArray</obj></returns>
      </callseq>
      <desc>
<p/>
      Splits the given string into a directory and a file component and
      returns them in a two-element array.  See also <ccm><file>file</file><front>File</front><back>dirname</back><mref>dirname</mref></ccm> and
      <ccm><file>file</file><front>File</front><back>basename</back><mref>basename</mref></ccm>.
<p/>
<codefragment>
<fullcode><![CDATA[        File.split("/home/gumby/.profile")
]]></fullcode><rubycode>
<tr>
  <td><tt>File.split("/home/gumby/.profile")</tt></td>
  <td>&#187;</td>
  <td><tt>["/home/gumby",<nbsp/>".profile"]</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="stat" ref="stat">
      <callseq>
        File.stat( <obj>fileName</obj> )
        <returns><obj>aStat</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns a <classname>File::Stat</classname> object for the named file
      (see <const>File::Stat</const>, page 313).
<p/>
<codefragment>
<fullcode><![CDATA[        File.stat("testfile").mtime
]]></fullcode><rubycode>
<tr>
  <td><tt>File.stat("testfile").mtime</tt></td>
  <td>&#187;</td>
  <td><tt>Tue<nbsp/>Feb<nbsp/>27<nbsp/>00:11:18<nbsp/>CST<nbsp/>2001</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="symlink" ref="symlink">
      <callseq>
        File.symlink( <obj>anOldName</obj>, <obj>aNewName</obj> )
        <returns>0 or <tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Creates a symbolic link called <obj>aNewName</obj> for the existing
      file <obj>anOldName</obj>.
      Returns <tt>nil</tt> on all platforms that do not support
      symbolic links.
<p/>
<codefragment>
<fullcode><![CDATA[        File.symlink("testfile", "link2test")
!-          File.delete("link2test");
]]></fullcode><rubycode>
<tr>
  <td><tt>File.symlink("testfile",<nbsp/>"link2test")</tt></td>
  <td>&#187;</td>
  <td><tt>0</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="truncate" ref="truncate">
      <callseq>
        File.truncate( <obj>fileName</obj>, <obj>anInteger</obj> )
        <returns>0</returns>
      </callseq>
      <desc>
<p/>
      Truncates the file <obj>fileName</obj> to be at most <obj>anInteger</obj>
      bytes long.  Not available on all platforms.
<p/>
<codefragment>
<fullcode><![CDATA[        f = File.new("out", "w")
        f.write("1234567890")
        f.close
        File.truncate("out", 5)
        File.size("out")
!-          File.delete("out");
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>f<nbsp/>=<nbsp/>File.new("out",<nbsp/>"w")</tt></td>
</tr>
<tr>
  <td><tt>f.write("1234567890")</tt></td>
  <td>&#187;</td>
  <td><tt>10</tt></td>
</tr>
<tr>
  <td><tt>f.close</tt></td>
  <td>&#187;</td>
  <td><tt>nil</tt></td>
</tr>
<tr>
  <td><tt>File.truncate("out",<nbsp/>5)</tt></td>
  <td>&#187;</td>
  <td><tt>0</tt></td>
</tr>
<tr>
  <td><tt>File.size("out")</tt></td>
  <td>&#187;</td>
  <td><tt>5</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="umask" ref="umask">
      <callseq>
        File.umask( <opt><obj>anInteger</obj></opt> )
        <returns><obj>anInteger</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the current umask value for this process.      
      If the
      optional argument is given, set the umask to that value and
      return the previous value. Umask values are <em>subtracted</em>
      from the default permissions; so a umask of <tt>0222</tt> would make 
      a file read-only for everyone.
      See also the discussion of permissions on page 305.
<p/>
<codefragment>
<fullcode><![CDATA[!-        File.umask(0022)
        File.umask(0006)
        File.umask
]]></fullcode><rubycode>
<tr>
  <td><tt>File.umask(0006)</tt></td>
  <td>&#187;</td>
  <td><tt>18</tt></td>
</tr>
<tr>
  <td><tt>File.umask</tt></td>
  <td>&#187;</td>
  <td><tt>6</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="unlink" ref="unlink">
      <callseq>
        File.unlink( <optn><obj>fileName</obj></optn> )
        <returns><obj>anInteger</obj></returns>
      </callseq>
      <desc>
<p/>
      Synonym for <ccm><file>file</file><front>File</front><back>delete</back><mref>delete</mref></ccm>.
      See also <ccm><file>dir</file><front>Dir</front><back>rmdir</back><mref>rmdir</mref></ccm>.
<p/>
      </desc>
    </method>
<p/>
        <method name="utime" ref="utime">
      <callseq>
        File.utime( <obj>anAccessTime</obj>,
        <obj>aModTime</obj> <optn>, <obj>fileName</obj></optn> )
        <returns><obj>aFixnum</obj></returns>
      </callseq>
      <desc>
<p/>
      Changes the access and modification times on a number of files.
      The times must be instances of class <classname>Time</classname> or integers
        representing the number of seconds since epoch.
      Returns the number of files processed.
      Not available on all platforms.
<p/>
<codefragment>
<fullcode><![CDATA[        File.utime(0, 0, "testfile")
        File.mtime("testfile")
        File.utime(0, Time.now, "testfile")
        File.mtime("testfile")
]]></fullcode><rubycode>
<tr>
  <td><tt>File.utime(0,<nbsp/>0,<nbsp/>"testfile")</tt></td>
  <td>&#187;</td>
  <td><tt>1</tt></td>
</tr>
<tr>
  <td><tt>File.mtime("testfile")</tt></td>
  <td>&#187;</td>
  <td><tt>Wed<nbsp/>Dec<nbsp/>31<nbsp/>18:00:00<nbsp/>CST<nbsp/>1969</tt></td>
</tr>
<tr>
  <td><tt>File.utime(0,<nbsp/>Time.now,<nbsp/>"testfile")</tt></td>
  <td>&#187;</td>
  <td><tt>1</tt></td>
</tr>
<tr>
  <td><tt>File.mtime("testfile")</tt></td>
  <td>&#187;</td>
  <td><tt>Sun<nbsp/>Mar<nbsp/>04<nbsp/>23:28:25<nbsp/>CST<nbsp/>2001</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
  </methods>
<p/>
  <methods type="instance">
<p/>
        <method name="atime" ref="atime">
      <callseq>
        <obj>file</obj>.atime
        <returns><obj>aTime</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the last access time for <obj>file</obj>, or epoch if <obj>file</obj> has
      not been accessed.
<p/>
<codefragment>
<fullcode><![CDATA[        File.new("testfile").atime
]]></fullcode><rubycode>
<tr>
  <td><tt>File.new("testfile").atime</tt></td>
  <td>&#187;</td>
  <td><tt>Wed<nbsp/>Dec<nbsp/>31<nbsp/>18:00:00<nbsp/>CST<nbsp/>1969</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="chmod" ref="chmod">
      <callseq>
        <obj>file</obj>.chmod( <obj>aModeInt</obj> )
        <returns><tt>0</tt></returns>
      </callseq>
      <desc>
<p/>
        Changes permission bits on <obj>file</obj> to the bit pattern
        represented by <obj>aModeInt</obj>.  Actual effects are platform
        dependent; on Unix systems, see <tt>chmod(2)</tt> for details. 
      See the discussion of permissions on page 305.
<p/>
<codefragment>
<fullcode><![CDATA[          f = File.new("out", "w");
          f.chmod(0644)
!-          f.close
!-          File.delete("out");
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>f<nbsp/>=<nbsp/>File.new("out",<nbsp/>"w");</tt></td>
</tr>
<tr>
  <td><tt>f.chmod(0644)</tt></td>
  <td>&#187;</td>
  <td><tt>0</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="chown" ref="chown">
      <callseq>
        <obj>file</obj>.chown( <obj>anOwnerInt</obj>, <obj>aGroupInt</obj> )
        <returns>0</returns>
      </callseq>
      <desc>
<p/>
      Changes the owner and group of <obj>file</obj> to the given
      numeric owner and group id's.      
      Only a process with superuser
      privileges may change the owner of a file.  The current owner of
      a file may change the file's group to any group to which the
      owner belongs.  A <tt>nil</tt> or -1 owner or group id is
      ignored.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        File.new("testfile").chown(502, 1000)
]]></fullcode>
File.new("testfile").chown(502,<nbsp/>1000)
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="ctime" ref="ctime">
      <callseq>
        <obj>file</obj>.ctime
        <returns><obj>aTime</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the change time for <obj>file</obj> (that is, the time
      directory information about the file was changed, not the file
      itself).
<p/>
<codefragment>
<fullcode><![CDATA[        File.new("testfile").ctime
]]></fullcode><rubycode>
<tr>
  <td><tt>File.new("testfile").ctime</tt></td>
  <td>&#187;</td>
  <td><tt>Sun<nbsp/>Mar<nbsp/>04<nbsp/>23:28:25<nbsp/>CST<nbsp/>2001</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="flock" ref="flock">
      <callseq>
        <obj>file</obj>.flock ( <obj>aLockingConstant</obj> )
       <returns>0 or <const>false</const></returns>
      </callseq>
      <desc>
<p/>
     Locks or unlocks a file according to <obj>aLockingConstant</obj> (a
     logical
     <em>or</em> of the values in Table
     22.4 on page 312). Returns <const>false</const> if
     <const>File::LOCK_NB</const> is specified and the operation would
     otherwise have blocked.
     Not available on all platforms.
<p/>
<codefragment>
<fullcode><![CDATA[        File.new("testfile").flock(File::LOCK_UN)
]]></fullcode><rubycode>
<tr>
  <td><tt>File.new("testfile").flock(File::LOCK_UN)</tt></td>
  <td>&#187;</td>
  <td><tt>0</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
  <figure type="table">
    <caption>Lock-mode constants</caption>    
    <table>
<p/>
      <toprule/><tr>
  <td><tt>LOCK_EX</tt></td>
  <td>Exclusive lock. Only one process may hold an
      exclusive lock for a given file at a time.</td>
</tr>
<tr>
  <td><tt>LOCK_NB</tt></td>
  <td>Don't block when locking. May be combined
      with other lock options using logical or.</td>
</tr>
<tr>
  <td><tt>LOCK_SH</tt></td>
  <td>Shared lock. Multiple processes may each hold a
      shared lock for a given file at the same time.</td>
</tr>
<tr>
  <td><tt>LOCK_UN</tt></td>
  <td>Unlock.</td>
</tr>
<bottomrule/></table>
<p/>
  </figure>
<p/>
        <method name="lstat" ref="lstat">
      <callseq>
        <obj>file</obj>.lstat
        <returns><obj>aStat</obj></returns>
      </callseq>
      <desc>
<p/>
      Same as <cim><file>io</file><front>IO</front><back>stat</back><mref>stat</mref></cim>, but does not follow the last symbolic link.
      Instead, reports on the link itself.
<p/>
<codefragment>
<fullcode><![CDATA[        File.symlink("testfile", "link2test")
        File.stat("testfile").size
        f = File.new("link2test")
        f.lstat.size
        f.stat.size
!-          f.close
!-          File.delete("link2test");
]]></fullcode><rubycode>
<tr>
  <td><tt>File.symlink("testfile",<nbsp/>"link2test")</tt></td>
  <td>&#187;</td>
  <td><tt>0</tt></td>
</tr>
<tr>
  <td><tt>File.stat("testfile").size</tt></td>
  <td>&#187;</td>
  <td><tt>66</tt></td>
</tr>
<tr>
<td colspan="3"><tt>f<nbsp/>=<nbsp/>File.new("link2test")</tt></td>
</tr>
<tr>
  <td><tt>f.lstat.size</tt></td>
  <td>&#187;</td>
  <td><tt>8</tt></td>
</tr>
<tr>
  <td><tt>f.stat.size</tt></td>
  <td>&#187;</td>
  <td><tt>66</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="mtime" ref="mtime">
      <callseq>
        <obj>file</obj>.mtime
        <returns><obj>aTime</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the modification time for <obj>file</obj>.
<p/>
<codefragment>
<fullcode><![CDATA[        File.new("testfile").mtime
]]></fullcode><rubycode>
<tr>
  <td><tt>File.new("testfile").mtime</tt></td>
  <td>&#187;</td>
  <td><tt>Sun<nbsp/>Mar<nbsp/>04<nbsp/>23:28:25<nbsp/>CST<nbsp/>2001</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="path" ref="path">
      <callseq>
        <obj>file</obj>.path
        <returns><obj>fileName</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the pathname used to create <obj>file</obj> as a string.
<p/>
<codefragment>
<fullcode><![CDATA[        File.new("testfile").path
]]></fullcode><rubycode>
<tr>
  <td><tt>File.new("testfile").path</tt></td>
  <td>&#187;</td>
  <td><tt>"testfile"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="truncate" ref="truncate">
      <callseq>
        <obj>file</obj>.truncate( <obj>anInteger</obj> )
        <returns>0</returns>
      </callseq>
      <desc>
<p/>
      Truncates <obj>file</obj> to at most <obj>anInteger</obj> bytes. The file
      must be opened for writing.
      Not available on all platforms.
<p/>
<codefragment>
<fullcode><![CDATA[        f = File.new("out", "w")
        f.syswrite("1234567890")
        f.truncate(5)
        f.close()
        File.size("out")
!-          File.delete("out");
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>f<nbsp/>=<nbsp/>File.new("out",<nbsp/>"w")</tt></td>
</tr>
<tr>
  <td><tt>f.syswrite("1234567890")</tt></td>
  <td>&#187;</td>
  <td><tt>10</tt></td>
</tr>
<tr>
  <td><tt>f.truncate(5)</tt></td>
  <td>&#187;</td>
  <td><tt>0</tt></td>
</tr>
<tr>
  <td><tt>f.close()</tt></td>
  <td>&#187;</td>
  <td><tt>nil</tt></td>
</tr>
<tr>
  <td><tt>File.size("out")</tt></td>
  <td>&#187;</td>
  <td><tt>5</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
  </methods>
<p/>
</class>
</ppdoc>