An introduction to the dart:io library

Written by Mads AgerMarch 2012 (updated September 2018)

The dart:io libraryis aimed at code that runs in Flutter and the standalone Dart VM.In this article we will give you a feel forwhat is currently possible with dart:ioby going through a couple of examples.

Note: When writing a Flutter app, use Flutter-specific APIs instead of dart:io whenever possible. For example, use the Flutter asset support to load images and other assets into your app.

Dart is a single-threaded programming language.If an operation blocks the Dart thread,the application makes no progress before that operation completes.For scalability it is therefore crucial that no I/O operations block.Instead of blocking on I/O operations,dart:io uses an asynchronous programming model inspired bynode.js,EventMachine, andTwisted.

The Dart VM and the event loop

Before we dive into asynchronous I/O operations,it might be useful to explain how the standalone Dart VM operates.

When executing a server-side application,the Dart VM runs in an event loop withan associated event queue of pending asynchronous operations.The VM terminates when it has executed the current code to completionand no more pending operations are in the queue.

One simple way to add an event to the event queue is toschedule a function to be called in the future.You can do this by creating aTimer object.The following example registers a timer with the event queueand then drops off the end of main().Because a pending operation is in the event queue,the VM does not terminate at that point.After one second,the timer fires and the code in the argument callback executes.Once that code executes to completion,no more pending operations are in the event queueand the VM terminates.

import 'dart:async';
 
void main() {
  Timer(Duration(seconds: 1), () => print('timer'));
  print('end of main');
}

Running this example at the command line, we get:

$ dart timer.dart
end of main
timer

Had we made the timer repeating by using theTimer.periodic constructor,the VM would not terminateand would continue to print out ‘timer’ every second.

File system access

The dart:io library provides access to files and directories through theFile andDirectory classes.

The following example prints its own source code.To determine the location of the source code being executed,we use thePlatformclass.

import 'dart:convert';
import 'dart:io';
 
Future<void> main() async {
  var file = File(Platform.script.toFilePath());
  print("${await (file.readAsString(encoding: ascii))}");
}

Notice that the readAsString() method is asynchronous;it returns a Futurethat returns the contents of the fileonce the file has been read from the underlying system.This asynchronicity allows the Dart thread to perform other workwhile waiting for the I/O operation to complete.

To illustrate more detailed file operations,let’s change the example to read the contentsonly up to the first semicolon and then to print that.You could do this in two ways:either open the file for random access,or open aStreamfor the file and stream in the data.

Here is a version that opens the file for random access operations.The code opens the file for reading and then reads one byte at a timeuntil it encounters the char code for ;.

import 'dart:io';
 
Future<void> main() async {
  final semicolon = ';'.codeUnitAt(0);
  var result = <int>[];
 
  final script = File(Platform.script.toFilePath());
  RandomAccessFile file = await script.open(mode: FileMode.read);
 
  // Deal with each byte.
  while (true) {
    final byte = await file.readByte();
    result.add(byte);
    if (byte == semicolon) {
      print(String.fromCharCodes(result));
      await file.close();
      break;
    }
  }
}

When you see a use of async or await, you are seeing a Future in action.Both the open() and readByte() methods return a Future object.

This code is, of course,a very simple use of random-access operations.Operations are available for writing,seeking to a given position, truncating, and so on.

Let’s implement a version using a stream.The following code opens the file for reading presenting the contentas a stream of lists of bytes. Like all streams in Dart you listen onthis stream (using await for) and the data is given in chunks.

import 'dart:io';
 
Future<void> main() async {
  var result = <int>[];
 
  Stream<List<int>> stream = File(Platform.script.toFilePath()).openRead();
  final semicolon = ';'.codeUnitAt(0);
 
  await for (var data in stream) {
    for (int i = 0; i < data.length; i++) {
      result.add(data[i]);
      if (data[i] == semicolon) {
        print(String.fromCharCodes(result));
        return;
      }
    }
  }
}

The stream subscription is implicitly handled by await for.Exiting the await for statement — using break, return, or an uncaught exception —cancels the subscription.

Stream<List<int>> is used in multiple places in dart:io:when working with stdin, files, sockets, HTTP connections, and so on.Similarly, IOSink objectsare used to stream data tostdout, files, sockets, HTTP connections, and so on.

Interacting with processes

For the simple case, useProcess.run()to run a processand collect its output. Use run() when you don’tneed interactive control over the process.

import 'dart:io';
 
Future<void> main() async {
  // List all files in the current directory,
  // in UNIX-like operating systems.
  ProcessResult results = await Process.run('ls', ['-l']);
  print(results.stdout);
}

You can also start a process by creating aProcess objectusingProcess.start().

Once you have a Process object you can interact with the processby writing data to its stdin sink,reading data from its stderr and stdout streams,and killing the process.When the process exits, the exitCode future completes withthe exit code of the process.

The following example runs ls -l in a separate processand prints the output and the exit code for the process to stdout.Since we are interested in getting lines,we use aUtf8Decoder(which decodes chunks of bytes into strings) followed by aLineSplitter(which splits the strings at line boundaries).

import 'dart:convert';
import 'dart:io';
 
Future<void> main() async {
  final process = await Process.start('ls', ['-l']);
  var lineStream =
      process.stdout.transform(Utf8Decoder()).transform(LineSplitter());
  await for (var line in lineStream) {
    print(line);
  }
 
  await process.stderr.drain();
  print('exit code: ${await process.exitCode}');
}

Notice that exitCode can complete before all of the lines of outputhave been processed. Also notethat we do not explicitly close the process. In order tonot leak resources we have to listen to both the stderr and stdoutstreams. We use await for to listen to stdout,and stderr.drain() to listen to (and discard) stderr.

Instead of printing the output to stdout,we can use the streaming classesto pipe the output of the process to a file.

import 'dart:io';
 
Future<void> main() async {
  final output = File('output.txt').openWrite();
  Process process = await Process.start('ls', ['-l']);
 
  // Wait for the process to finish; get the exit code.
  final exitCode = (await Future.wait([
    process.stdout.pipe(output), // Send stdout to file.
    process.stderr.drain(), // Discard stderr.
    process.exitCode
  ]))[2];
 
  print('exit code: $exitCode');
}

Writing web servers

dart:io makes it easy to write HTTP servers and clients.To write a simple web server,all you have to do is create anHttpServerand hook up a listener (using await for) to its stream of HttpRequests.

Here is a simple web serverthat just answers ‘Hello, world’ to any request.

import 'dart:io';
 
Future<void> main() async {
  final server = await HttpServer.bind('127.0.0.1', 8082);
  await for (HttpRequest request in server) {
    request.response.write('Hello, world');
    await request.response.close();
  }
}

Running this applicationand pointing your browser to ‘http://127.0.0.1:8082’gives you ‘Hello, world’ as expected.

Let’s add a bit more and actually serve files.The base path for every file that we serve will bethe location of the script.If no path is specified in a request we will serve index.html.For a request with a path,we will attempt to find the file and serve it.If the file is not found we will respond with a ‘404 Not Found’ status.We make use of the streaming interfaceto pipe all the data read from a file directly to the response stream.

import 'dart:io';
 
Future<void> runServer(String basePath) async {
  final server = await HttpServer.bind('127.0.0.1', 8082);
  await for (HttpRequest request in server) {
    await handleRequest(basePath, request);
  }
}
 
Future<void> handleRequest(String basePath, HttpRequest request) async {
  final String path = request.uri.toFilePath();
  // PENDING: Do more security checks here.
  final String resultPath = path == '/' ? '/index.html' : path;
  final File file = File('$basePath$resultPath');
  if (await file.exists()) {
    try {
      await request.response.addStream(file.openRead());
    } catch (exception) {
      print('Error happened: $exception');
      await sendInternalError(request.response);
    }
  } else {
    await sendNotFound(request.response);
  }
}
 
Future<void> sendInternalError(HttpResponse response) async {
  response.statusCode = HttpStatus.internalServerError;
  await response.close();
}
 
Future<void> sendNotFound(HttpResponse response) async {
  response.statusCode = HttpStatus.notFound;
  await response.close();
}
 
Future<void> main() async {
  // Compute base path for the request based on the location of the
  // script, and then start the server.
  final script = File(Platform.script.toFilePath());
  await runServer(script.parent.path);
}

Writing HTTP clients is very similar to using theHttpClientclass.

Feature requests welcome

The dart:io library is already capable of performing a lot of tasks.For example, the pub.dev site uses dart:io.

Please give dart:io a spin and let us know what you think.Feature requests are very welcome!When you file a bug or feature request,use dartbug.com.To find reported issues, search for thelibrary-io label.