Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

FileStream.Read Method

Reads a block of bytes from the stream and writes the data in a given buffer.

[Visual Basic]
Overrides Public Function Read( _
   <InteropServices.In(), _
   Out()> ByVal array() As Byte, _
   ByVal offset As Integer, _
   ByVal count As Integer _
) As Integer
[C#]
public override int Read(
   [
   In,
   Out
] byte[] array,
 int offset,
 int count
);
[C++]
public: int Read(
   [
   In,
   Out
] unsigned char array __gc[],
 int offset,
 int count
);
[JScript]
public override function Read(
   array : Byte[],
 offset : int,
 count : int
) : int;

Parameters

array
When this method returns, contains the specified byte array with the values between offset and (offset + count - 1) replaced by the bytes read from the current source.
offset
The byte offset in array at which to begin reading.
count
The maximum number of bytes to read.

Return Value

The total number of bytes read into the buffer. This might be less than the number of bytes requested if that number of bytes are not currently available, or zero if the end of the stream is reached.

Exceptions

Exception Type Condition
ArgumentNullException array is a null reference (Nothing in Visual Basic).
ArgumentOutOfRangeException offset or count is negative.
NotSupportedException The stream does not support reading.
IOException An I/O error occurs.
ArgumentException offset and count describe an invalid range in array.
ObjectDisposedException Methods were called after the stream was closed.

Remarks

This method overrides Read.

The offset parameter gives the offset of the byte in array (the buffer index) at which to begin reading, and the count parameter gives the maximum number of bytes to be read from this stream. The returned value is the actual number of bytes read, or zero if the end of the stream is reached. If the read operation is successful, the current position of the stream is advanced by the number of bytes read. If an exception occurs, the current position of the stream is unchanged.

The Read method returns zero only after reaching the end of the stream. Otherwise, Read always reads at least one byte from the stream before returning. If no data is available from the stream upon a call to Read, the method will block until at least one byte of data can be returned. An implementation is free to return fewer bytes than requested even if the end of the stream has not been reached.

Use BinaryReader for reading primitive data types.

For an example of using this method, see the Example section below. The following table lists examples of other typical or related I/O tasks.

To do this... See the example in this topic...
Create a text file. Writing Text to a File
Write to a text file. Writing Text to a File
Read from a text file. Reading Text from a File
Append text to a file. Opening and Appending to a Log File

File.AppendText

FileInfo.AppendText

Rename or move a file. File.Move

FileInfo.MoveTo

Copy a file. File.Copy

FileInfo.CopyTo

Get the size of a file. FileInfo.Length
Get the attributes of a file. File.GetAttributes
Set the attributes of a file. File.SetAttributes
Determine if a file exists. File.Exists
Read from a binary file. Reading and Writing to a Newly Created Data File
Write to a binary file. Reading and Writing to a Newly Created Data File
Create a directory. Directory.CreateDirectory

Directory.CreateDirectory

Example

[Visual Basic, C#, C++] The following example demonstrates reading a specified number of bytes from an existing file.

[Visual Basic] 
Imports System
Imports System.IO

Class FSRead

    Public Shared Sub Main()
        'Create a file stream from an existing file.
        Dim fi As New FileInfo("c:\csc.txt")
        Dim fs As FileStream = fi.OpenRead()

        'Read 100 bytes into an array from the specified file.
        Dim nBytes As Integer = 100
        Dim ByteArray(nBytes) As Byte
        Dim nBytesRead As Integer = fs.Read(ByteArray, 0, nBytes)
        Console.WriteLine("{0} bytes have been read from the specified file.", nBytesRead.ToString())
    End Sub 'Main
End Class 'FSRead

[C#] 
using System;
using System.IO;

class FSRead
{
    public static void Main()
    {
        //Create a file stream from an existing file.
        FileInfo fi=new FileInfo("c:\\csc.txt");       
        FileStream fs=fi.OpenRead();
        
        //Read 100 bytes into an array from the specified file.
        int nBytes=100;
        byte[] ByteArray=new byte[nBytes];
        int nBytesRead=fs.Read(ByteArray, 0, nBytes);
        Console.WriteLine("{0} bytes have been read from the specified file.", nBytesRead.ToString());
    }
}

[C++] 
#using <mscorlib.dll>

using namespace System;
using namespace System::IO;

int main() {
    //Create a file stream from an existing file.
    FileInfo* fi = new FileInfo(S"c:\\csc.txt");       
    FileStream* fs = fi->OpenRead();

    //Read 100 bytes into an array from the specified file.
    int nBytes=100;
    Byte ByteArray[] = new Byte[nBytes];
    int nBytesRead = fs->Read(ByteArray, 0, nBytes);
    Console::WriteLine(S"{0} bytes have been read from the specified file.", __box(nBytesRead));
}

[JScript] No example is available for JScript. To view a Visual Basic, C#, or C++ example, click the Language Filter button Language Filter in the upper-left corner of the page.

Requirements

Platforms: Windows 98, Windows NT 4.0, Windows Millennium Edition, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 family, .NET Compact Framework, Common Language Infrastructure (CLI) Standard

See Also

FileStream Class | FileStream Members | System.IO Namespace | Working with I/O | Reading Text from a File | Writing Text to a File

Show:
© 2014 Microsoft