Early Preview

This is currently very much a preview. Please feel free to try things out, but don't be upset if anything is not yet working. Feedback is welcome over on our GitHub Dicussions page.

class System.​IO.​FileStream

Assembly: System.Runtime

Inheritance: object → MarshalByRefObject → Stream → FileStream

Implemented Interfaces

Provides a <see cref="T:System.IO.Stream" /> for a file, supporting both synchronous and asynchronous read and write operations.

Properties

public bool
CanRead
Gets a value that indicates whether the current stream supports reading.
public bool
CanSeek
Gets a value that indicates whether the current stream supports seeking.
public bool
CanWrite
Gets a value that indicates whether the current stream supports writing.
public nint
Handle
Gets the operating system file handle for the file that the current <see langword="FileStream" /> object encapsulates.
public bool
IsAsync
Gets a value that indicates whether the <see langword="FileStream" /> was opened asynchronously or synchronously.
public long
Length
Gets the length in bytes of the stream.
public string
Name
Gets the absolute path of the file opened in the <see langword="FileStream" /> .
public long
Position
Gets or sets the current position of this stream.
SafeFileHandle
Gets a <see cref="T:Microsoft.Win32.SafeHandles.SafeFileHandle" /> object that represents the operating system file handle for the file that the current <see cref="T:System.IO.FileStream" /> object encapsulates.
public bool
CanTimeout
Gets a value that determines whether the current stream can time out.
public int
ReadTimeout
Gets or sets a value, in milliseconds, that determines how long the stream will attempt to read before timing out.
public int
WriteTimeout
Gets or sets a value, in milliseconds, that determines how long the stream will attempt to write before timing out.

Methods

public IAsyncResult
BeginRead​(byte[] buffer, int offset, int count, AsyncCallback? callback, object state)
Begins an asynchronous read operation. Consider using <see cref="M:System.IO.FileStream.ReadAsync(System.Byte[],System.Int32,System.Int32,System.Threading.CancellationToken)" /> instead.
Returns An object that references the asynchronous read.
buffer The buffer to read data into.
offset The byte offset in <paramref name="array" /> at which to begin reading.
count The maximum number of bytes to read.
callback The method to be called when the asynchronous read operation is completed.
state A user-provided object that distinguishes this particular asynchronous read request from other requests.
public IAsyncResult
BeginWrite​(byte[] buffer, int offset, int count, AsyncCallback? callback, object state)
Begins an asynchronous write operation. Consider using <see cref="M:System.IO.FileStream.WriteAsync(System.Byte[],System.Int32,System.Int32,System.Threading.CancellationToken)" /> instead.
Returns An object that references the asynchronous write.
buffer The buffer containing data to write to the current stream.
offset The zero-based byte offset in <paramref name="array" /> at which to begin copying bytes to the current stream.
count The maximum number of bytes to write.
callback The method to be called when the asynchronous write operation is completed.
state A user-provided object that distinguishes this particular asynchronous write request from other requests.
public void
CopyTo​(Stream destination, int bufferSize)
Reads the bytes from the current stream and writes them to another stream, using a specified buffer size. Both streams positions are advanced by the number of bytes copied.
destination The stream to which the contents of the current stream will be copied.
bufferSize The size of the buffer. This value must be greater than zero.
CopyToAsync​(Stream destination, int bufferSize, Threading.​CancellationToken cancellationToken)
Asynchronously reads the bytes from the current file stream and writes them to another stream, using a specified buffer size and cancellation token.
Returns A task that represents the asynchronous copy operation.
destination The stream to which the contents of the current file stream will be copied.
bufferSize The size, in bytes, of the buffer. This value must be greater than zero.
cancellationToken The token to monitor for cancellation requests. The default value is <see cref="P:System.Threading.CancellationToken.None" /> .
protected void
Dispose​(bool disposing)
Releases the unmanaged resources used by the <see cref="T:System.IO.FileStream" /> and optionally releases the managed resources.
disposing <see langword="true" /> to release both managed and unmanaged resources; <see langword="false" /> to release only unmanaged resources.
DisposeAsync​()
Asynchronously releases the unmanaged resources used by the <see cref="T:System.IO.FileStream" /> .
Returns A task that represents the asynchronous dispose operation.
public int
EndRead​(IAsyncResult asyncResult)
Waits for the pending asynchronous read operation to complete. (Consider using <see cref="M:System.IO.FileStream.ReadAsync(System.Byte[],System.Int32,System.Int32,System.Threading.CancellationToken)" /> instead.)
Returns The number of bytes read from the stream, between 0 and the number of bytes you requested. Streams only return 0 at the end of the stream, otherwise, they should block until at least 1 byte is available.
asyncResult The reference to the pending asynchronous request to wait for.
public void
EndWrite​(IAsyncResult asyncResult)
Ends an asynchronous write operation and blocks until the I/O operation is complete. (Consider using <see cref="M:System.IO.FileStream.WriteAsync(System.Byte[],System.Int32,System.Int32,System.Threading.CancellationToken)" /> instead.)
asyncResult The pending asynchronous I/O request.
protected void
Finalize​()
Ensures that resources are freed and other cleanup operations are performed when the garbage collector reclaims the <see langword="FileStream" /> .
public void
Flush​()
Clears buffers for this stream and causes any buffered data to be written to the file.
public void
Flush​(bool flushToDisk)
Clears buffers for this stream and causes any buffered data to be written to the file, and also clears all intermediate file buffers.
flushToDisk <see langword="true" /> to flush all intermediate file buffers; otherwise, <see langword="false" /> .
FlushAsync​(Threading.​CancellationToken cancellationToken)
Asynchronously clears all buffers for this stream, causes any buffered data to be written to the file, and monitors cancellation requests.
Returns A task that represents the asynchronous flush operation.
cancellationToken The token to monitor for cancellation requests.
public void
Lock​(long position, long length)
Prevents other processes from reading from or writing to the <see cref="T:System.IO.FileStream" /> .
position The beginning of the range to lock. The value of this parameter must be equal to or greater than zero (0).
length The range to be locked.
public int
Read​(byte[] buffer, int offset, int count)
Reads a block of bytes from the stream and writes the data in a given buffer.
Returns 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.
offset The byte offset in <paramref name="array" /> at which the read bytes will be placed.
count The maximum number of bytes to read.
public int
Read​(Span<​byte> buffer)
Reads a sequence of bytes from the current file stream and advances the position within the file stream by the number of bytes read.
Returns The total number of bytes read into the buffer. This can be less than the number of bytes allocated in the buffer if that many bytes are not currently available, or zero (0) if the end of the stream has been reached.
buffer A region of memory. When this method returns, the contents of this region are replaced by the bytes read from the current file stream.
ReadAsync​(byte[] buffer, int offset, int count, Threading.​CancellationToken cancellationToken)
Asynchronously reads a sequence of bytes from the current file stream and writes them to a byte array beginning at a specified offset, advances the position within the file stream by the number of bytes read, and monitors cancellation requests.
Returns A task that represents the asynchronous read operation and wraps the total number of bytes read into the buffer. The result value can be less than the number of bytes requested if the number of bytes currently available is less than the requested number, or it can be 0 (zero) if the end of the stream has been reached.
buffer The buffer to write the data into.
offset The byte offset in <paramref name="buffer" /> at which to begin writing data from the stream.
count The maximum number of bytes to read.
cancellationToken The token to monitor for cancellation requests.
ReadAsync​(Memory<​byte> buffer, Threading.​CancellationToken cancellationToken = null)
Asynchronously reads a sequence of bytes from the current file stream and writes them to a memory region, advances the position within the file stream by the number of bytes read, and monitors cancellation requests.
Returns A task that represents the asynchronous read operation and wraps the total number of bytes read into the buffer. The result value can be less than the number of bytes requested if the number of bytes currently available is less than the requested number, or it can be 0 (zero) if the end of the stream has been reached.
buffer The buffer to write the data into.
cancellationToken The token to monitor for cancellation requests. The default value is <see cref="P:System.Threading.CancellationToken.None" /> .
public int
ReadByte​()
Reads a byte from the file and advances the read position one byte.
Returns The byte, cast to an <see cref="T:System.Int32" /> , or -1 if the end of the stream has been reached.
public long
Seek​(long offset, SeekOrigin origin)
Sets the current position of this stream to the given value.
Returns The new position in the stream.
offset The point relative to <paramref name="origin" /> from which to begin seeking.
origin Specifies the beginning, the end, or the current position as a reference point for <paramref name="offset" /> , using a value of type <see cref="T:System.IO.SeekOrigin" /> .
public void
SetLength​(long value)
Sets the length of this stream to the given value.
value The new length of the stream.
public void
Unlock​(long position, long length)
Allows access by other processes to all or part of a file that was previously locked.
position The beginning of the range to unlock.
length The range to be unlocked.
public void
Write​(byte[] buffer, int offset, int count)
Writes a block of bytes to the file stream.
offset The zero-based byte offset in <paramref name="array" /> from which to begin copying bytes to the stream.
count The maximum number of bytes to write.
public void
Write​(ReadOnlySpan<​byte> buffer)
Writes a sequence of bytes from a read-only span to the current file stream and advances the current position within this file stream by the number of bytes written.
buffer A region of memory. This method copies the contents of this region to the current file stream.
WriteAsync​(byte[] buffer, int offset, int count, Threading.​CancellationToken cancellationToken)
Asynchronously writes a sequence of bytes to the current stream, advances the current position within this stream by the number of bytes written, and monitors cancellation requests.
Returns A task that represents the asynchronous write operation.
buffer The buffer to write data from.
offset The zero-based byte offset in <paramref name="buffer" /> from which to begin copying bytes to the stream.
count The maximum number of bytes to write.
cancellationToken The token to monitor for cancellation requests.
WriteAsync​(ReadOnlyMemory<​byte> buffer, Threading.​CancellationToken cancellationToken = null)
Asynchronously writes a sequence of bytes from a memory region to the current file stream, advances the current position within this file stream by the number of bytes written, and monitors cancellation requests.
Returns A task that represents the asynchronous write operation.
buffer The region of memory to write data from.
cancellationToken The token to monitor for cancellation requests. The default value is <see cref="P:System.Threading.CancellationToken.None" /> .
public void
WriteByte​(byte value)
Writes a byte to the current position in the file stream.
value A byte to write to the stream.
public void
Close​()
Inherited from Stream
Closes the current stream and releases any resources (such as sockets and file handles) associated with the current stream. Instead of calling this method, ensure that the stream is properly disposed.
public void
CopyTo​(Stream destination)
Inherited from Stream
Reads the bytes from the current stream and writes them to another stream. Both streams positions are advanced by the number of bytes copied.
destination The stream to which the contents of the current stream will be copied.
CopyToAsync​(Stream destination)
Inherited from Stream
Asynchronously reads the bytes from the current stream and writes them to another stream. Both streams positions are advanced by the number of bytes copied.
Returns A task that represents the asynchronous copy operation.
destination The stream to which the contents of the current stream will be copied.
CopyToAsync​(Stream destination, int bufferSize)
Inherited from Stream
Asynchronously reads the bytes from the current stream and writes them to another stream, using a specified buffer size. Both streams positions are advanced by the number of bytes copied.
Returns A task that represents the asynchronous copy operation.
destination The stream to which the contents of the current stream will be copied.
bufferSize The size, in bytes, of the buffer. This value must be greater than zero. The default size is 81920.
CopyToAsync​(Stream destination, Threading.​CancellationToken cancellationToken)
Inherited from Stream
Asynchronously reads the bytes from the current stream and writes them to another stream, using a specified cancellation token. Both streams positions are advanced by the number of bytes copied.
Returns A task that represents the asynchronous copy operation.
destination The stream to which the contents of the current stream will be copied.
cancellationToken The token to monitor for cancellation requests. The default value is <see cref="P:System.Threading.CancellationToken.None" /> .
CreateWaitHandle​()
Inherited from Stream
Allocates a <see cref="T:System.Threading.WaitHandle" /> object.
Returns A reference to the allocated <see langword="WaitHandle" /> .
public void
Dispose​()
Inherited from Stream
Releases all resources used by the <see cref="T:System.IO.Stream" /> .
FlushAsync​()
Inherited from Stream
Asynchronously clears all buffers for this stream and causes any buffered data to be written to the underlying device.
Returns A task that represents the asynchronous flush operation.
protected void
ObjectInvariant​()
Inherited from Stream
Provides support for a <see cref="T:System.Diagnostics.Contracts.Contract" /> .
ReadAsync​(byte[] buffer, int offset, int count)
Inherited from Stream
Asynchronously reads a sequence of bytes from the current stream and advances the position within the stream by the number of bytes read.
Returns A task that represents the asynchronous read operation. The value of the <paramref name="TResult" /> parameter contains the total number of bytes read into the buffer. The result value can be less than the number of bytes requested if the number of bytes currently available is less than the requested number, or it can be 0 (zero) if <paramref name="count" /> is 0 or if the end of the stream has been reached.
buffer The buffer to write the data into.
offset The byte offset in <paramref name="buffer" /> at which to begin writing data from the stream.
count The maximum number of bytes to read.
public int
ReadAtLeast​(Span<​byte> buffer, int minimumBytes, bool throwOnEndOfStream = true)
Inherited from Stream
Reads at least a minimum number of bytes from the current stream and advances the position within the stream by the number of bytes read.
Returns The total number of bytes read into the buffer. This is guaranteed to be greater than or equal to <paramref name="minimumBytes" /> when <paramref name="throwOnEndOfStream" /> is <see langword="true" /> . This will be less than <paramref name="minimumBytes" /> when the end of the stream is reached and <paramref name="throwOnEndOfStream" /> is <see langword="false" /> . This can be less than the number of bytes allocated in the buffer if that many bytes are not currently available.
buffer A region of memory. When this method returns, the contents of this region are replaced by the bytes read from the current stream.
minimumBytes The minimum number of bytes to read into the buffer.
throwOnEndOfStream <see langword="true" /> to throw an exception if the end of the stream is reached before reading <paramref name="minimumBytes" /> of bytes; <see langword="false" /> to return less than <paramref name="minimumBytes" /> when the end of the stream is reached. The default is <see langword="true" /> .
ReadAtLeastAsync​(Memory<​byte> buffer, int minimumBytes, bool throwOnEndOfStream = true, Threading.​CancellationToken cancellationToken = null)
Inherited from Stream
Asynchronously reads at least a minimum number of bytes from the current stream, advances the position within the stream by the number of bytes read, and monitors cancellation requests.
Returns A task that represents the asynchronous read operation. The value of its <see cref="P:System.Threading.Tasks.ValueTask`1.Result" /> property contains the total number of bytes read into the buffer. This is guaranteed to be greater than or equal to <paramref name="minimumBytes" /> when <paramref name="throwOnEndOfStream" /> is <see langword="true" /> . This will be less than <paramref name="minimumBytes" /> when the end of the stream is reached and <paramref name="throwOnEndOfStream" /> is <see langword="false" /> . This can be less than the number of bytes allocated in the buffer if that many bytes are not currently available.
buffer The region of memory to write the data into.
minimumBytes The minimum number of bytes to read into the buffer.
throwOnEndOfStream <see langword="true" /> to throw an exception if the end of the stream is reached before reading <paramref name="minimumBytes" /> of bytes; <see langword="false" /> to return less than <paramref name="minimumBytes" /> when the end of the stream is reached. The default is <see langword="true" /> .
cancellationToken The token to monitor for cancellation requests.
public void
ReadExactly​(byte[] buffer, int offset, int count)
Inherited from Stream
Reads <paramref name="count" /> number of bytes from the current stream and advances the position within the stream.
buffer An array of bytes. When this method returns, the buffer contains the specified byte array with the values between <paramref name="offset" /> and ( <paramref name="offset" /> + <paramref name="count" /> - 1) replaced by the bytes read from the current stream.
offset The byte offset in <paramref name="buffer" /> at which to begin storing the data read from the current stream.
count The number of bytes to be read from the current stream.
public void
ReadExactly​(Span<​byte> buffer)
Inherited from Stream
Reads bytes from the current stream and advances the position within the stream until the <paramref name="buffer" /> is filled.
buffer A region of memory. When this method returns, the contents of this region are replaced by the bytes read from the current stream.
ReadExactlyAsync​(byte[] buffer, int offset, int count, Threading.​CancellationToken cancellationToken = null)
Inherited from Stream
Asynchronously reads <paramref name="count" /> number of bytes from the current stream, advances the position within the stream, and monitors cancellation requests.
Returns A task that represents the asynchronous read operation.
buffer The buffer to write the data into.
offset The byte offset in <paramref name="buffer" /> at which to begin writing data from the stream.
count The number of bytes to be read from the current stream.
cancellationToken The token to monitor for cancellation requests.
ReadExactlyAsync​(Memory<​byte> buffer, Threading.​CancellationToken cancellationToken = null)
Inherited from Stream
Asynchronously reads bytes from the current stream, advances the position within the stream until the <paramref name="buffer" /> is filled, and monitors cancellation requests.
Returns A task that represents the asynchronous read operation.
buffer The buffer to write the data into.
cancellationToken The token to monitor for cancellation requests.
WriteAsync​(byte[] buffer, int offset, int count)
Inherited from Stream
Asynchronously writes a sequence of bytes to the current stream and advances the current position within this stream by the number of bytes written.
Returns A task that represents the asynchronous write operation.
buffer The buffer to write data from.
offset The zero-based byte offset in <paramref name="buffer" /> from which to begin copying bytes to the stream.
count The maximum number of bytes to write.
public object
GetLifetimeService​()
Inherited from MarshalByRefObject
Retrieves the current lifetime service object that controls the lifetime policy for this instance.
Returns An object of type <see cref="T:System.Runtime.Remoting.Lifetime.ILease" /> used to control the lifetime policy for this instance.
public object
InitializeLifetimeService​()
Inherited from MarshalByRefObject
Obtains a lifetime service object to control the lifetime policy for this instance.
Returns An object of type <see cref="T:System.Runtime.Remoting.Lifetime.ILease" /> used to control the lifetime policy for this instance. This is the current lifetime service object for this instance if one exists; otherwise, a new lifetime service object initialized to the value of the <see cref="P:System.Runtime.Remoting.Lifetime.LifetimeServices.LeaseManagerPollTime" /> property.
protected MarshalByRefObject
MemberwiseClone​(bool cloneIdentity)
Inherited from MarshalByRefObject
Creates a shallow copy of the current <see cref="T:System.MarshalByRefObject" /> object.
Returns A shallow copy of the current <see cref="T:System.MarshalByRefObject" /> object.
cloneIdentity <see langword="false" /> to delete the current <see cref="T:System.MarshalByRefObject" /> object's identity, which will cause the object to be assigned a new identity when it is marshaled across a remoting boundary. A value of <see langword="false" /> is usually appropriate. <see langword="true" /> to copy the current <see cref="T:System.MarshalByRefObject" /> object's identity to its clone, which will cause remoting client calls to be routed to the remote server object.
public bool
Equals​(object obj)
Inherited from object
Determines whether the specified object is equal to the current object.
Returns <see langword="true" /> if the specified object is equal to the current object; otherwise, <see langword="false" /> .
obj The object to compare with the current object.
public int
GetHashCode​()
Inherited from object
Serves as the default hash function.
Returns A hash code for the current object.
public Type
GetType​()
Inherited from object
Gets the <see cref="T:System.Type" /> of the current instance.
Returns The exact runtime type of the current instance.
protected object
MemberwiseClone​()
Inherited from object
Creates a shallow copy of the current <see cref="T:System.Object" /> .
Returns A shallow copy of the current <see cref="T:System.Object" /> .
public string
ToString​()
Inherited from object
Returns a string that represents the current object.
Returns A string that represents the current object.