Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 30 additions & 25 deletions docs/c-runtime-library/reference/read.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,57 +55,61 @@ translation.priority.ht:
- "zh-tw"
---
# _read

Reads data from a file.

## Syntax

```

int _read(
int _read(
int fd,
void *buffer,
unsigned int count
);
```

#### Parameters
`fd`
File descriptor referring to the open file.
### Parameters

*fd*
File descriptor referring to the open file.

*buffer*
Storage location for data.
*buffer*
Storage location for data.

*count*
Maximum number of bytes.
*count*
Maximum number of bytes.

## Return Value
_**read** returns the number of bytes read, which might be less than *count* if there are fewer than *count* bytes left in the file or if the file was opened in text mode, in which case each carriage return-line feed (CR-LF) pair is replaced with a single linefeed character. Only the single linefeed character is counted in the return value. The replacement does not affect the file pointer.

`_read` returns the number of bytes read, which might be less than *count* if there are fewer than *count* bytes left in the file or if the file was opened in text mode, in which case each carriage return-line feed pair `\r\n` is replaced with a single linefeed character `\n`. Only the single linefeed character is counted in the return value. The replacement does not affect the file pointer.

If the function tries to read at end of file, it returns 0. If `fd` is invalid, the file is not open for reading, or the file is locked, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function returns -1 and sets `errno` to `EBADF`.
If the function tries to read at end of file, it returns 0. If *fd* is not valid, the file is not open for reading, or the file is locked, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function returns -1 and sets `errno` to `EBADF`.

If *buffer* is **NULL**, the invalid parameter handler is invoked. If execution is allowed to continue, the function returns -1 and `errno` is set to `EINVAL`.
If *buffer* is **NULL**, the invalid parameter handler is invoked. If execution is allowed to continue, the function returns -1 and `errno` is set to `EINVAL`.

For more information about this and other return codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md).
For more information about this and other return codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md).

## Remarks
The `_read` function reads a maximum of *count* bytes into *buffer* from the file associated with `fd`. The read operation begins at the current position of the file pointer associated with the given file. After the read operation, the file pointer points to the next unread character.

The `_read` function reads a maximum of *count* bytes into *buffer* from the file associated with *fd*. The read operation begins at the current position of the file pointer associated with the given file. After the read operation, the file pointer points to the next unread character.

If the file was opened in text mode, the read terminates when `_read` encounters a CTRL+Z character, which is treated as an end-of-file indicator. Use [_lseek](../../c-runtime-library/reference/lseek-lseeki64.md) to clear the end-of-file indicator.
If the file was opened in text mode, the read terminates when `_read` encounters a CTRL+Z character, which is treated as an end-of-file indicator. Use [_lseek](../../c-runtime-library/reference/lseek-lseeki64.md) to clear the end-of-file indicator.

## Requirements

|Routine|Required header|
|-------------|---------------------|
|`_read`|\<io.h>|

For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md) in the Introduction.
For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md).

## Libraries
All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md).

All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md).

## Example

```
```C
// crt_read.c
/* This program opens a file named crt_read.txt
* and tries to read 60,000 bytes from
Expand Down Expand Up @@ -143,22 +147,23 @@ int main( void )
}
```

## Input: crt_read.txt
### Input: crt_read.txt

```
Line one.
Line two.
```

## Output
### Output

```
Read 19 bytes from file
```

## See Also
[Low-Level I/O](../../c-runtime-library/low-level-i-o.md)
[_creat, _wcreat](../../c-runtime-library/reference/creat-wcreat.md)
[fread](../../c-runtime-library/reference/fread.md)
[_open, _wopen](../../c-runtime-library/reference/open-wopen.md)
[_write](../../c-runtime-library/reference/write.md)

[Low-Level I/O](../../c-runtime-library/low-level-i-o.md)
[_creat, _wcreat](../../c-runtime-library/reference/creat-wcreat.md)
[fread](../../c-runtime-library/reference/fread.md)
[_open, _wopen](../../c-runtime-library/reference/open-wopen.md)
[_write](../../c-runtime-library/reference/write.md)