Getting Started: Input And Output

Input and Output

Input and output is an active area of development in Hack; this page describes a proposed standard API, with a prototype available in hsl-experimental, known as "HSL IO".

HSL IO is currently not recommended in CLI server mode: error handling is based on the errno C variable, which has unpredictable behavior in CLI server mode.

HSL IO differs from most other language's standard IO libraries in two particularly significant ways:

  • provide as much safety as possible through the type system instead of runtime checking. For example, files opened read-only are a different type to those opened write-only; read-write files are a supertype of both read-only- and write-only- files.
  • designed primarily for asynchronous IO; blocking operations are not generally exposed.

Additional design goals include:

  • be internally consistent
  • reduce end-user boilerplate. For example, automatically retry calls that fail with EAGAIN
  • make the most obvious way to do things as safe as possible
  • /support/ all reasonable behavior even if unsafe
  • be convenient for common cases, but not at the cost of consistency or safety

For a more detailed overview, see the documentation for IO\Handle; basic operations include:

namespace Hack\GettingStarted\HSLIO;

use namespace HH\Lib\{File, IO};

async function main_async(): Awaitable<void> {
  // STDIN for CLI, or HTTP POST data
  $_in = IO\request_input();
  // STDOUT for CLI, or HTTP response
  $out = IO\request_output();

  $message = "Hello, world\n";
  await $out->writeAsync($message);

  // copy to a temporary file, automatically closed at scope exit
  await using ($f = File\temporary_file()) {
    await $f->writeAsync($message);

    await $f->seekAsync(0);
    $content = await $f->readAsync();
    await $out->writeAsync($content);
Hello, world
Hello, world