# Read File
> Read the entire contents of a file.
## Usage
```javascript
var readFile = require( '@stdlib/fs/read-file' );
```
#### readFile( file\[, options], clbk )
Asynchronously reads the entire contents of a file.
```javascript
readFile( __filename, onFile );
function onFile( error, data ) {
if ( error ) {
throw error;
}
console.log( data );
}
```
The function accepts the same `options` and has the same defaults as [`fs.readFile()`][node-fs].
#### readFile.sync( file\[, options] )
Synchronously reads the entire contents of a `file`.
```javascript
var out = readFile.sync( __filename );
if ( out instanceof Error ) {
throw out;
}
console.log( out );
```
The function accepts the same `options` and has the same defaults as [`fs.readFileSync()`][node-fs].
## Notes
- The difference between this API and [`fs.readFileSync()`][node-fs] is that [`fs.readFileSync()`][node-fs] will throw if an `error` is encountered (e.g., if given a non-existent `path`) and this API will return an `error`. Hence, the following anti-pattern
```javascript
var fs = require( 'fs' );
var file = '/path/to/file.js';
// Check for existence to prevent an error being thrown...
if ( fs.existsSync( file ) ) {
file = fs.readFileSync( file );
}
```
can be replaced by an approach which addresses existence via `error` handling.
```javascript
var readFile = require( '@stdlib/fs/read-file' );
var file = '/path/to/file.js';
// Explicitly handle the error...
file = readFile.sync( file );
if ( file instanceof Error ) {
// You choose what to do...
console.error( file.message );
}
```
## Examples
```javascript
var readFile = require( '@stdlib/fs/read-file' );
/* Sync */
var file = readFile.sync( __filename, 'utf8' );
// returns
console.log( file instanceof Error );
// => false
file = readFile.sync( 'beepboop', {
'encoding': 'utf8'
});
// returns
console.log( file instanceof Error );
// => true
/* Async */
readFile( __filename, onFile );
readFile( 'beepboop', onFile );
function onFile( error, data ) {
if ( error ) {
if ( error.code === 'ENOENT' ) {
console.error( 'File does not exist.' );
} else {
throw error;
}
} else {
console.log( data );
}
}
```
* * *
## CLI
### Usage
```text
Usage: read-file [options]
Options:
-h, --help Print this message.
-V, --version Print the package version.
--enc, --encoding encoding Encoding.
--flag flag Flag. Default: 'r'.
```
### Notes
- Relative file paths are resolved relative to the current working directory.
- Errors are written to `stderr`.
- File contents are written to `stdout`.
### Examples
```bash
$ read-file ./README.md
```
[node-fs]: https://nodejs.org/api/fs.html