Skip to content

Commit 8e905db

Browse files
Steve WishnouskyColin Robertson
authored andcommitted
Update fread.md to include clobbering effects in text mode (MicrosoftDocs#578)
* Update fread.md Since istream::read has started using fread(), we've received multiple reports that they expected the data past the amount read to be the same as prior to the call. This update clarifies the reasons and effects of the buffer clobbering that occurs. * Update fread.md I'm attempting to simplify this for internationalization.
1 parent e956856 commit 8e905db

File tree

1 file changed

+7
-3
lines changed
  • docs/c-runtime-library/reference

1 file changed

+7
-3
lines changed

docs/c-runtime-library/reference/fread.md

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: "fread"
3-
ms.date: "11/04/2016"
3+
ms.date: "11/28/2018"
44
apiname: ["fread"]
55
apilocation: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"]
66
apitype: "DLLExport"
@@ -41,11 +41,13 @@ Pointer to **FILE** structure.
4141

4242
**fread** returns the number of full items actually read, which may be less than *count* if an error occurs or if the end of the file is encountered before reaching *count*. Use the **feof** or **ferror** function to distinguish a read error from an end-of-file condition. If *size* or *count* is 0, **fread** returns 0 and the buffer contents are unchanged. If *stream* or *buffer* is a null pointer, **fread** invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function sets **errno** to **EINVAL** and returns 0.
4343

44-
See [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information on these, and other, error codes.
44+
See [\_doserrno, errno, \_sys\_errlist, and \_sys\_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information on these error codes.
4545

4646
## Remarks
4747

48-
The **fread** function reads up to *count* items of *size* bytes from the input *stream* and stores them in *buffer*. The file pointer associated with *stream* (if there is one) is increased by the number of bytes actually read. If the given stream is opened in text mode, carriage return-linefeed pairs are replaced with single linefeed characters. The replacement has no effect on the file pointer or the return value. The file-pointer position is indeterminate if an error occurs. The value of a partially read item cannot be determined.
48+
The **fread** function reads up to *count* items of *size* bytes from the input *stream* and stores them in *buffer*. The file pointer associated with *stream* (if there is one) is increased by the number of bytes actually read. If the given stream is opened in [text mode](../../c-runtime-library/text-and-binary-mode-file-i-o.md), Windows-style newlines are converted into Unix-style newlines. That is, carriage return-linefeed (CRLF) pairs are replaced by single linefeed (LF) characters. The replacement has no effect on the file pointer or the return value. The file-pointer position is indeterminate if an error occurs. The value of a partially read item cannot be determined.
49+
50+
When used on a text mode stream, if the amount of data requested (that is, *size* \* *count*) is greater than the internal **FILE** \* buffer size (by default this is 4096 bytes, configurable by using [setvbuf](../../c-runtime-library/reference/setvbuf.md)), stream data is copied directly into the user-provided buffer, and newline conversion is done in that buffer. Since the converted data may be shorter than the stream data copied into the buffer, data past *buffer*\[*return_value* \* *size*] (where *return_value* is the return value from **fread**) may contain unconverted data from the file. For this reason, we recommend you null-terminate character data at *buffer*\[*return_value* \* *size*] if the intent of the buffer is to act as a C-style string. See [fopen](fopen-wfopen.md) for details on the effects of text mode and binary mode.
4951

5052
This function locks out other threads. If you need a non-locking version, use **_fread_nolock**.
5153

@@ -110,5 +112,7 @@ Contents of buffer = zyxwvutsrqponmlkjihgfedcb
110112
## See also
111113

112114
[Stream I/O](../../c-runtime-library/stream-i-o.md)<br/>
115+
[Text and Binary File I/O](../../c-runtime-library/text-and-binary-mode-file-i-o.md)<br />
116+
[fopen](fopen-wfopen.md)<br />
113117
[fwrite](fwrite.md)<br/>
114118
[_read](read.md)<br/>

0 commit comments

Comments
 (0)