Using File Streams

From RAD Studio
Jump to: navigation, search

Go Up to Working with Files


The TFileStream class enables applications to read from and write to a file on disk. Because TFileStream is a stream object, it shares the common stream methods. You can use these methods to read from or write to the file, copy data to or from other stream classes, and read or write components values. See Using streams for details on the capabilities that file streams inherit by being stream classes.

In addition, file streams give you access to the file handle, so that you can use them with global file handling routines that require the file handle.

The content of this page also applies to the TBufferedFileStream class, which adds buffering support to the TFileStream class and optimizes its performance for multiple consecutive small reads or writes.

Creating and opening files using file streams

To create or open a file and get access to its handle, you simply instantiate a TFileStream. This opens or creates a specified file and provides methods to read from or write to it. If the file cannot be opened, the TFileStream constructor raises an exception.

Delphi:

 constructor Create(const filename: string; Mode: Word);

C++:

 __fastcall TFileStream(const UnicodeString FileName, Word Mode);

The Mode parameter specifies how the file should be opened when creating the file stream. The Mode parameter consists of an open mode and a share mode OR'ed together. The open mode must be one of the following values:

Open modes

Value Meaning

fmCreate

Create a file with the given name. If a file with the given name exists, open the file in write mode.

fmOpenRead

Open the file for reading only.

fmOpenWrite

Open the file for writing only. Writing to the file completely replaces the current contents.

fmOpenReadWrite

Open the file to modify the current contents rather than replace them.


The share mode can be one of the following values with the restrictions listed below:

Share modes

Value Meaning

fmShareCompat

Sharing is compatible with the way FCBs are opened (VCL applications only).

For more information about File Control Block structure, see The FCB Structure in the MSDN Library.

fmShareExclusive

Other applications can not open the file for any reason.

fmShareDenyWrite

Other applications can open the file for reading but not for writing.

fmShareDenyRead

Other applications can open the file for writing but not for reading (VCL applications only).

fmShareDenyNone

No attempt is made to prevent other applications from reading from or writing to the file.


Note that the share mode you can use depends on which open mode you used. The following table shows shared modes that are available for each open mode.

Shared modes available for each open mode

Open Mode fmShareCompat (VCL) fmShareExclusive fmShareDenyWrite fmShareDenyRead (VCL) fmShareDenyNone

fmOpenRead

Can't use

Can't use

Available

Can't use

Available

fmOpenWrite

Available

Available

Can't use

Available

Available

fmOpenReadWrite

Available

Available

Available

Available

Available


The file open and share mode constants are defined in the SysUtils unit.

Using the file handle

When you instantiate TFileStream you get access to the file handle. The file handle is contained in the Handle property. On Windows, Handle is a Windows file handle. Handle is read-only and reflects the mode in which the file was opened. If you want to change the attributes of the file Handle, you must create a new file stream object.

Some file manipulation routines take a file handle as a parameter. Once you have a file stream, you can use the Handle property in any situation in which you would use a file handle. Be aware that, unlike handle streams, file streams close file handles when the object is destroyed.

See Also