Interfacing with C

Here are the new concepts you'll need:

• An array inside a struct: VMIN and VTIME are indexes into the c_cc array. Assigning to an element updates the struct in place.
• UByte, as c_cc holds cc_t, which is unsigned char.
• Calling read directly, with a buffer we allocate.

We want VMIN = 0 and VTIME = n, which means "return as soon as any input is available, or after n tenths of a second". A timeout makes read return 0.

// In withRawMode, before calling tcsetattr
raw.c_cc(VMIN) = 0.toUByte
raw.c_cc(VTIME) = 1.toUByte

Now we can read a Byte on a timeout, returning None if no data is available.

def readByte(): Option[Byte] =
  Zone:
    val buffer = alloc[Byte]()
    unistd.read(STDIN_FILENO, buffer, 1.toCSize) match
      case 1 => Some(!buffer)
      case 0 => None
      case _ => throw new RuntimeException("Could not read input")

Distinguishing keys: after reading ESC, read again. A timeout means it was the Escape key. [ followed by A–D is an arrow key.

Terminal.readByte().map:
  case 27 =>
    Terminal.readByte() match
      case Some('[') =>
        Terminal.readByte() match
          case Some('A') => Key.Up
          case Some('B') => Key.Down
          case Some('C') => Key.Right
          case Some('D') => Key.Left
          case _         => Key.Escape
      case _ => Key.Escape
  case byte => Key.Character(byte.toChar)

Here are the new concepts you'll need:

• errno, which is how C functions report the reason for an error.
• Converting a C string, CString, to a Scala String using fromCString. strerror returns a CString.

import scala.scalanative.libc.errno.errno
import scala.scalanative.libc.string.strerror

def fail(message: String): Nothing =
  val code = errno
  throw new RuntimeException(s"$message: ${fromCString(strerror(code))}")

We read errno into a local variable before doing anything else. errno is shared by every C function we call, so any other call could change it. For the same reason we should call fail immediately after the call that failed.

Running with < /dev/null gives

java.lang.RuntimeException: Could not get terminal settings: Inappropriate ioctl for device

The message mentions ioctl, which is the system call tcgetattr uses on Linux. We'll meet ioctl directly in the next exercise.

Here are the new concepts you'll need:

• Out-parameters: allocate memory for the result, pass a pointer to it, and then read the result from the pointer using !.
• Casting pointers: the binding for ioctl expects a Ptr[Byte], but we have a Ptr[CInt]. We can convert one to the other with asInstanceOf. This doesn't change the pointer, just what Scala Native thinks it points to.

import scala.scalanative.posix.sys.ioctl.{FIONREAD, ioctl}

def bytesAvailable(): Int =
  Zone:
    // Space for ioctl to write its result into
    val count = alloc[CInt]()
    if ioctl(STDIN_FILENO, FIONREAD, count.asInstanceOf[Ptr[Byte]]) != 0 then
      throw new RuntimeException("Could not get number of bytes available")
    // Read the value count points to
    !count

Why does Scala Native's binding take a Ptr[Byte] when the third argument can point to anything? In C, ioctl is declared as

int ioctl(int fd, unsigned long request, ...);

The ... means ioctl is variadic: it takes any number of extra arguments, of any type. Variadic functions are awkward to call from other languages. On some platforms, including macOS on Apple Silicon, variadic arguments are passed differently from normal arguments, so a binding that pretends ioctl takes exactly three arguments might work on Linux and fail on a Mac. Scala Native avoids this by calling a small C function that takes exactly three arguments and passes them on to ioctl. The third argument had to be given some type, and void * (which Scala Native writes as Ptr[Byte] here) is the natural choice.

bytesAvailable gives us another way to distinguish the Escape key from escape codes. After reading ESC, if more bytes are available, it's probably an escape code. Unlike the timeout approach, this doesn't wait at all, but it can be fooled if the rest of the escape code hasn't arrived yet. This might happen, for example, over a slow network connection.

Here are the new concepts you'll need:

• Defining a struct using CStruct4, and accessing its fields.
• CLongInt, the type of ioctl's request, is an alias for Size. We convert an Int to a Size using toSize.

type winsize =
  CStruct4[CUnsignedShort, CUnsignedShort, CUnsignedShort, CUnsignedShort]

// 0x5413 on Linux; use 0x40087468 on macOS
val TIOCGWINSZ: CLongInt = 0x5413.toSize

def terminalSize(): (Int, Int) =
  Zone:
    val size = alloc[winsize]()
    if ioctl(STDOUT_FILENO, TIOCGWINSZ, size.asInstanceOf[Ptr[Byte]]) != 0 then
      throw new RuntimeException("Could not get terminal size")
    // _1 is ws_row and _2 is ws_col
    (size._1.toInt, size._2.toInt)

This is the same as the previous exercise, except ioctl writes into a struct instead of an int. We ask about standard output, as that's where we'll draw, but any file descriptor connected to the terminal will work.

Although the value of TIOCGWINSZ is different on Linux and macOS, the layout of struct winsize is the same. This means our definition of winsize is portable, but our value for TIOCGWINSZ is not.

size._1 isn't very readable. If you'd like names like size.ws_row, you can define extension methods in the same way that Scala Native's termiosOps does.

Here are the new concepts you'll need:

• Adding C code to a Scala Native project.
• Using @name when the Scala name differs from the C name.

With the C code above in winsize.c, the binding is

@extern
object WinSize:
  @name("workshop_tiocgwinsz")
  def TIOCGWINSZ: CLongInt = extern

and terminalSize uses WinSize.TIOCGWINSZ in place of the hard-coded value. Notice we've defined TIOCGWINSZ without parentheses, making it look like a constant. This is how Scala Native defines its own constants, such as ECHO.

If Scala Native doesn't find your C file you'll get a linking error like

undefined reference to `workshop_tiocgwinsz'

just like the misspelled isatty in the previous section.

Here are the new concepts you'll need:

• Signals and signal handlers.
• Creating C function pointers from Scala functions.

We add another function to our C file

#include <signal.h>

int workshop_sigwinch(void) { return SIGWINCH; }

and bind it in our extern object

@name("workshop_sigwinch")
def SIGWINCH: CInt = extern

The signal handler sets a flag in a top-level object. It starts as true, so we print the size when the program starts. The flag is @volatile as it is changed by the signal handler, outside the normal flow of the program.

object Resize:
  @volatile var resized = true

  val handler = CFuncPtr1.fromScalaFunction[CInt, Unit](_ => resized = true)

  def install(): Unit = signal(WinSize.SIGWINCH, handler)

The main loop reads with a timeout, and checks the flag each time around.

@main def watchSize(): Unit =
  Resize.install()
  Terminal.withRawMode:
    var byte = Terminal.readByte()
    while byte != Some('q'.toByte) do
      if Resize.resized then
        Resize.resized = false
        val (rows, cols) = terminalSize()
        print(s"$cols columns x $rows rows\r\n")
        System.out.flush()
      byte = Terminal.readByte()

There is one more wrinkle. If a signal arrives while our program is waiting in read, the read may fail with errno set to EINTR (interrupted system call). Our readByte from the first exercise throws an exception when read fails, which is not what we want here. The simplest fix is to treat a failed read as a timeout. A better fix is to check whether errno is EINTR, using what we learned earlier, and only treat that case as a timeout.

signal is the oldest and simplest way to install a signal handler. Its behavior varies between systems, and modern code should use sigaction instead. sigaction needs another struct, however, and signal is good enough for our purposes.