| title | ms.custom | ms.date | ms.reviewer | ms.suite | ms.technology | ms.tgt_pltfrm | ms.topic | f1_keywords | dev_langs | helpviewer_keywords | ms.assetid | caps.latest.revision | author | ms.author | manager | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
CStdioFile Class | Microsoft Docs |
11/04/2016 |
|
reference |
|
|
|
88c2274c-4f0e-4327-882a-557ba4b3ae15 |
22 |
mikeblome |
mblome |
ghogen |
Represents a C run-time stream file as opened by the run-time function fopen.
class CStdioFile : public CFile
| Name | Description |
|---|---|
| CStdioFile::CStdioFile | Constructs a CStdioFile object from a path or file pointer. |
| Name | Description |
|---|---|
| CStdioFile::Open | Overloaded. Open is designed for use with the default CStdioFile constructor (Overrides CFile::Open). |
| CStdioFile::ReadString | Reads a single line of text. |
| CStdioFile::Seek | Positions the current file pointer. |
| CStdioFile::WriteString | Writes a single line of text. |
| Name | Description |
|---|---|
| CStdioFile::m_pStream | Contains a pointer to an open file. |
Stream files are buffered and can be opened in either text mode (the default) or binary mode.
Text mode provides special processing for carriage return-linefeed pairs. When you write a newline character (0x0A) to a text-mode CStdioFile object, the byte pair (0x0D, 0x0A) is sent to the file. When you read, the byte pair (0x0D, 0x0A) is translated to a single 0x0A byte.
The CFile functions Duplicate, LockRange, and UnlockRange are not supported for CStdioFile.
If you call these functions on a CStdioFile, you will get a CNotSupportedException.
For more information on using CStdioFile, see the articles Files in MFC and File Handling in the Run-Time Library Reference.
CStdioFile
Header: afx.h
Constructs and initializes a CStdioFile object.
CStdioFile();
CStdioFile(CAtlTransactionManager* pTM);
CStdioFile(FILE* pOpenStream);
CStdioFile(
LPCTSTR lpszFileName,
UINT nOpenFlags);
CStdioFile(
LPCTSTR lpszFileName,
UINT nOpenFlags,
CAtlTransactionManager* pTM);
pOpenStream
Specifies the file pointer returned by a call to the C run-time function fopen.
lpszFileName
Specifies a string that is the path to the desired file. The path can be relative or absolute.
nOpenFlags
Specifies options for file creation, file sharing, and file access modes. You can specify multiple options by using the bitwise OR ( |) operator.
One file access mode option is required; other modes are optional. See CFile::CFile for a list of mode options and other flags. In MFC version 3.0 and later, share flags are allowed.
pTM
Pointer to CAtlTransactionManager object.
The default constructor does not attach a file to the CStdioFile object. When using this constructor, you must use the CStdioFile::Open method to open a file and attach it to the CStdioFile object.
The single-parameter constructor attaches an open file stream to the CStdioFile object. Allowed pointer values include the predefined input/output file pointers stdin, stdout, or stderr.
The two-parameter constructor creates a CStdioFile object and opens the corresponding file with the given path.
If you pass NULL for either pOpenStream or lpszFileName, the constructor throws a CInvalidArgException*.
If the file cannot be opened or created, the constructor throws a CFileException*.
[!code-cppNVC_MFCFiles#37]
The m_pStream data member is the pointer to an open file as returned by the C run-time function fopen.
FILE* m_pStream;
It is NULL if the file has never been opened or has been closed.
Overloaded. Open is designed for use with the default CStdioFile constructor.
virtual BOOL Open(
LPCTSTR lpszFileName,
UINT nOpenFlags,
CFileException* pError = NULL);
virtual BOOL Open(
LPCTSTR lpszFileName,
UINT nOpenFlags,
CAtlTransactionManager* pTM,
CFileException* pError = NULL);
lpszFileName
A string that is the path to the desired file. The path can be relative or absolute.
nOpenFlags
Sharing and access mode. Specifies the action to take when opening the file. You can combine options by using the bitwise-OR (|) operator. One access permission and one share option are required; the modeCreate and modeNoInherit modes are optional.
pError
A pointer to an existing file-exception object that will receive the status of a failed operation.
pTM
Pointer to a CAtlTransactionManager object.
TRUE if successful; otherwise FALSE.
Reads text data into a buffer, up to a limit of nMax-1 characters, from the file associated with the CStdioFile object.
virtual LPTSTR ReadString(
LPTSTR lpsz,
UINT nMax);
virtual BOOL ReadString(CString& rString);
lpsz
Specifies a pointer to a user-supplied buffer that will receive a null-terminated text string.
nMax
Specifies the maximum number of characters to read, not counting the terminating null character.
rString
A reference to a CString object that will contain the string when the function returns.
A pointer to the buffer containing the text data. NULL if end-of-file was reached without reading any data; or if boolean, FALSE if end-of-file was reached without reading any data.
Reading is stopped by the first newline character. If, in that case, fewer than nMax-1 characters have been read, a newline character is stored in the buffer. A null character ('\0') is appended in either case.
CFile::Read is also available for text-mode input, but it does not terminate on a carriage return-linefeed pair.
Note
The CString version of this function removes the '\n' if present; the LPTSTR version does not.
[!code-cppNVC_MFCFiles#38]
Repositions the pointer in a previously opened file.
virtual ULONGLONG Seek(
LONGLONG lOff,
UINT nFrom);
lOff
Number of bytes to move the pointer.
nFrom
Pointer movement mode. Must be one of the following values:
-
CFile::begin: Move the file pointerlOffbytes forward from the beginning of the file. -
CFile::current: Move the file pointerlOffbytes from the current position in the file. -
CFile::end: Move the file pointerlOffbytes from the end of the file. Note thatlOffmust be negative to seek into the existing file; positive values will seek past the end of the file.
If the requested position is legal, Seek returns the new byte offset from the beginning of the file. Otherwise, the return value is undefined and a CFileException object is thrown.
The Seek function permits random access to a file's contents by moving the pointer a specified amount, absolutely or relatively. No data is actually read during the seek. If the requested position is larger than the size of the file, the file length will be extended to that position, and no exception will be thrown.
When a file is opened, the file pointer is positioned at offset 0, the beginning of the file.
This implementation of Seek is based on the Run-Time Library (CRT) function fseek. There are several limits on the usage of Seek on streams opened in text mode. For more information, see fseek, _fseeki64.
The following example shows how to use Seek to move the pointer 1000 bytes from the beginning of the cfile file. Note that Seek does not read data, so you must subsequently call CStdioFile::ReadString to read data.
[!code-cppNVC_MFCFiles#39]
Writes data from a buffer to the file associated with the CStdioFile object.
virtual void WriteString(LPCTSTR lpsz);
lpsz
Specifies a pointer to a buffer that contains a null-terminated string.
The terminating null character ( \0) is not written to the file. This method writes newline characters in lpsz to the file as a carriage return/linefeed pair.
If you want to write data that is not null-terminated to a file, use CStdioFile::Write or CFile::Write.
This method throws a CInvalidArgException* if you specify NULL for the lpsz parameter.
This method throws a CFileException* in response to file system errors.
[!code-cppNVC_MFCFiles#40]
CFile Class
Hierarchy Chart
CFile Class
CFile::Duplicate
CFile::LockRange
CFile::UnlockRange
CNotSupportedException Class