2021 001 Add getWindowSz function to Posix.TTY structure

Proposal 2021-001

Add getWindowSz function to Posix.TTY structure

Author: John Reppy
Last revised: February 6, 2021
Status: proposed
Discussion: issue #30

---

Unix systems (and Linux) typically support an ioctl system call to get the size of the window from a file descriptor when it is attached to a TTY. While this mechanism is not part of the POSIX standard, it is common across Unix systems and seems to most naturally fit into the Posix.TTY structure.

Synopsis

signature POSIX_TTY
structure Posix.TTY : POSIX_TTY

Interface

val getWindowSz : file_desc -> { nLines : int, nCols : int } option

Description

• getWindowSz fd
  returns SOME{nLines, nCols} if the file descriptor fd is attached to a TTY device and the window-size query is supported. Otherwise, it returns NONE.

Discussion

The UNIX interface (introduced in Berkeley Unix) can be used as follows:

struct winsize {
    unsigned short  ws_row;
    unsigned short  ws_col;
    unsigned short  ws_xpixel;
    unsigned short  ws_ypixel;
};

int getWindowSz (int fd, int *nLines, int *nCols)
{
    struct winsize wsz;

    int sts = ioctl (fd, TIOCGWINSZ, &wsz);

    if (sts == 0) {
	*nLines = wsz.ws_row;
	*nCols = wsz.ws_col;
    }

    return sts;
}

The additional fields ws_xpixel and ws_ypixel may hold the window dimension in pixels on some systems, but that feature is not always supported and we ignore those fields.

For the SML API, this proposal returns NONE whenever the query fails, which might be because the file descriptor is invalid, or is not a TTY, or the system does not support the operation. Thus, a valid implementation can always return NONE.

Impact

This addition should not affect existing code.

Rationale

This mechanism is useful for implementing cursor-based screen editing in SML (e.g., for input editing in a REPL). It is more reliable than relying on environment variables that may (or may not) be defined.

Adding it to the POSIX.TTY structure seems natural, since it works at the level of file descriptors, which not part of the UNIX signature (the other possible place).

---

History

• [2021-02-06] proposed

---