# File

The **File** object lets you read and write binary data from and to a file on disk (or in a Zip file, FTP site, etc). While the Microsoft _Scripting.FileSystemObject_ object lets you read and write files already, it only supports text, not binary data. You can also use the **File** object to modify a file's attributes and timestamps.

You can obtain a **File** object using the [**FSUtil**](fsutil)**.OpenFile** and [**Item**](item)**.Open** methods. You can open a file in one of three modes:

* _read mode_ - you can read data from the file via the **Read** method. You cannot write to it or modify its attributes.
* _write mode_ - you can write data to the file via the **Write** method, and you can also modify the file's attributes. You cannot read data from it.
* _modify mode_ - you can modify the file's attributes and timestamps, but you cannot read or write data.

| Property Name      | Return Type                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ------------------ | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| _\<default value>_ | _string_                          | Returns the full pathname of the file.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| error              | _int_                             | <p>Returns a Win32 error code that indicates the success or failure of the last operation. If the previous operation succeeded this will generally be <strong>0</strong>.</p><p>For example, if you try to open a non-existing file for reading using <strong>FSUtil.OpenFile</strong>, a valid <strong>File</strong> object will be returned - but the file itself would not be open. You can check if <strong>error</strong> returns <strong>0</strong> before proceeding to use the <strong>File</strong> object.</p> |
| path               | _object:_[**Path**](path)         | Returns the full pathname of the file as a [**Path**](path) object.                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| size               | _object:_[**FileSize**](filesize) | Returns a [**FileSize**](filesize) object representing the size of this file, in bytes.                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| tell               | _object:_[**FileSize**](filesize) | Returns a [**FileSize**](filesize) object representing the current position of the read or write cursor within this file, in bytes.                                                                                                                                                                                                                                                                                                                                                                                      |

| Method Name | **Arguments**                                                                                                     | Return Type                                                                        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ----------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Close       | _none_                                                                                                            | _none_                                                                             | <p>Closes the underlying file handle. After this call the <strong>File</strong> object is still valid but it can no longer read or write data.</p><p>If you want to use the <strong>SetAttr</strong> method to modify the attributes of a file you have created, you may want to call <strong>Close</strong> first otherwise the file system will set the <em>A</em> (archive) attribute on the file whether you want it set or not.</p><p>You may also want to close a file manually if you want to delete it, as some scripting languages (e.g. <em>JScript</em>) have lazy garbage collection and otherwise may keep the file handle open much longer than you intend.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Read        | <p>&#x3C;<a href="blob:target">blob:target</a>><br>&#x3C;int:size></p>                                            | <p><em>int</em> or<br><em>object:</em><a href="blob"><strong>Blob</strong></a></p> | <p>Reads data from the file. If you provide a <em>target</em> <a href="blob"><strong>Blob</strong></a> as the first parameter, the data will be stored in that <strong>Blob</strong>. Otherwise, a <strong>Blob</strong> will be created automatically.<br>The optional <em>size</em> parameter specifies the number of bytes to read - the default behavior is to read the remaining contents of the file.<br>A maximum of 1 GB (1073741824 bytes) can be read per call, whether a size is specified or implicit. To read a larger file, you must call <strong>Read</strong> multiple times.<br>If you provide a <strong>Blob</strong> then the return value indicates the number of bytes read successfully from the file. If a <strong>Blob</strong> isn't provided then the return value is the automatically created <strong>Blob</strong> - you can use its <strong>size</strong> property to discover the number of bytes that were read.<br>If <strong>Read</strong> returns zero (or an empty <strong>Blob</strong>), you can use the <strong>error</strong> property to test if anything went wrong, or if the file simply had no more data.</p> |
| Seek        | <p>&#x3C;int:delta><br>&#x3C;string:method></p>                                                                   | _object:_[**FileSize**](filesize)                                                  | <p>Moves the read or write cursor within this file. The <em>delta</em> parameter specifies how many bytes to move - how this is interpreted depends on the optional <em>method</em> parameter:</p><p><em>b</em> - move relative to the beginning of the file<br><em>e</em> - move relative to the end of the file<br><em>c</em> - move relative to the current position (this is the default method)</p><p>The return value is a <a href="filesize"><strong>FileSize</strong></a> object indicating the new cursor position.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| SetAttr     | <p><em>object:</em><a href="fileattr"><strong>FileAttr</strong></a><br>or &#x3C;string:attributes></p>            | _bool_                                                                             | <p>Modifies the attributes of this file. You can either pass a string indicating the attributes to set, or a **<a href="fileattr">FileAttr</a>**object. When using a string, valid attributes are:</p><p><em>a</em> - archive<br><em>c</em> - compressed<br><em>e</em> - encrypted<br><em>h</em> - hidden<br><em>n</em> - normal<br><em>r</em> - read-only<br><em>s</em> - system<br>p - pinned<br>i - non-content indexed</p><p>Note that both <em>c</em> and <em>e</em> attributes cannot be set at the same time.</p><p>When you pass a string you can also use <strong>+</strong> and <strong>-</strong> to turn some attributes on or off without affecting others. For example, <strong>SetAttr("-r")</strong> would turn off the read-only attribute.</p><p>The return value is <strong>True</strong> if the operation was successful.</p>                                                                                                                                                                                                                                                                                                          |
| SetTime     | <p>&#x3C;date:modify><br>&#x3C;date:create><br>&#x3C;date:access></p>                                             | _bool_                                                                             | <p>Modifies one or more of the file's timestamps. The <em>create</em> and <em>access</em> parameters are optional. If you wish to specify no change for a timestamp, specify <strong>0</strong>.</p><p>Timestamps are specified as local time - use <strong>SetTimeUTC</strong> to specify them as UTC.</p><p>The return value is <strong>True</strong> for success.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| SetTimeUTC  | <p>&#x3C;date:modify><br>&#x3C;date:create><br>&#x3C;date:access></p>                                             | _bool_                                                                             | <p>Modifies one or more of the file's timestamps. The <em>create</em> and <em>access</em> parameters are optional. If you wish to specify no change for a timestamp, specify <strong>0</strong>.</p><p>Timestamps are specified as UTC time - use <strong>SetTime</strong> to specify them as local time.</p><p>The return value is <strong>True</strong> for success.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Truncate    | _none_                                                                                                            | _bool_                                                                             | <p>Truncates the file at the current position of the write cursor. You can use this in conjunction with the <strong>Seek</strong> method to pre-allocate a file's space on disk, for greater performance (i.e. seek to the final size of the file, truncate at that point, and then seek back to the start and write the data).</p><p>The return value is <strong>True</strong> for success.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Write       | <p>&#x3C;<a href="blob:source">blob:source</a>> or &#x3C;string:source><br>&#x3C;int:from><br>&#x3C;int:size></p> | int                                                                                | <p>Writes data from the specified <strong>Blob</strong> (or array) or <em>string</em> to the file.<br>By default the entire contents of the <strong>Blob</strong> will be written, but you can use the optional <em>from</em> parameter to specify the source byte offset, and the <em>size</em> parameter to specify the number of bytes to write.<br>A maximum of 1 GB (1073741824 bytes) can be written per call, whether a size is specified or implicit. To write a larger amount of data, you must call <strong>Write</strong> multiple times.<br>If you provide a <em>string</em> rather than a Blob, the string will be automatically encoded as UTF-8.<br>The return value indicates the number of bytes successfully written to the file.<br>If <strong>Write</strong> returns zero, you can use the <strong>error</strong> property to test if anything went wrong or if there was simply no data to write (e.g. the specified <strong>Blob</strong> was empty).</p>                                                                                                                                                                            |
