[TUHS] Unix APIs: elegant or not?

[Warren Toomey <wkt@tuhs.org>]

I was just reading this book review:
http://www.pathsensitive.com/2018/10/book-review-philosophy-of-software.html
and came across these paragraphs:

    <book quote>
    The mechanism for file IO provided by the Unix operating system
    and its descendants, such as Linux, is a beautiful example of a
    deep interface. There are only five basic system calls for I/O,
    with simple signatures:

    int open(const char* path, int flags, mode_t permissions);
    ssize_t read(int fd, void* buffer, size_t count);
    ssize_t write(int fd, const void* buffer, size_t count);
    off_t lseek(int fd, off_t offset, int referencePosition);
    int close(int fd);
    </book quote>

  The POSIX file API is a great example, but not of a deep
  interface. Rather, it’s a great example of how code with a very
  complicated interface may look deceptively simple when reduced to C-style
  function signatures. It’s a stateful API with interesting orderings
  and interactions between calls. The flags and permissions parameters
  of open hide an enormous amount of complexity, with hidden requirements
  like “exactly one of these five bits should be specified.” open may
  return 20 different error codes, each with their own meaning, and many
  with references to specific implementations.

  The authors of SibylIFS tried to write down an exact description of the
  open interface. Their annotated version[1] of the POSIX standard is over
  3000 words. Not counting basic machinery, it took them over 200 lines[2]
  to write down the properties of open in higher-order logic, and another
  70 to give the interactions between open and close.
  [1]: https://github.com/sibylfs/sibylfs_src/blob/8a7f53ba58654249b0ec0725ce3887840d6a1812/fs_spec/src/posix/open.md
  [2]: https://github.com/sibylfs/sibylfs_src/blob/8a7f53ba58654249b0ec0725ce3887840d6a1812/fs_spec/src/t_fs_spec_fs_command_properties.lem_cppo#L460

I just thought it was a thought-provoking comment on the apparent elegance
of the Unix file API that actually has some subtle complexity.

Cheers, Warren