More progress. More work.

[tripe-android] / sys.scala

/* -*-scala-*-
 *
 * System-level hacking
 *
 * (c) 2018 Straylight/Edgeware
 */

/*----- Licensing notice --------------------------------------------------*
 *
 * This file is part of the Trivial IP Encryption (TrIPE) Android app.
 *
 * TrIPE is free software: you can redistribute it and/or modify it under
 * the terms of the GNU General Public License as published by the Free
 * Software Foundation; either version 3 of the License, or (at your
 * option) any later version.
 *
 * TrIPE is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with TrIPE.  If not, see <https://www.gnu.org/licenses/>.
 */

package uk.org.distorted.tripe; package object sys {

/*----- Imports -----------------------------------------------------------*/

import scala.collection.convert.decorateAsJava._;
import scala.collection.mutable.HashSet;

import java.io.{BufferedReader, BufferedWriter, Closeable, File,
		FileDescriptor, FileInputStream, FileOutputStream,
		InputStream, InputStreamReader,
		OutputStream, OutputStreamWriter};
import java.nio.{ByteBuffer, CharBuffer};
import java.nio.charset.Charset;
import java.util.Date;

/*----- Some magic for C strings ------------------------------------------*/

type CString = Array[Byte];

/* We do this by hand, rather than relying on the JNI's built-in conversions,
 * because we use the default encoding taken from the locale settings, rather
 * than the ridiculous `modified UTF-8' which is (a) insensitive to the
 * user's chosen locale and (b) not actually UTF-8 either.
 */

class InvalidCStringException(msg: String) extends Exception(msg);

object StringImplicits {
  implicit class ConvertJStringToCString(s: String) {
    /* Magic to convert a string into a C string (null-terminated bytes). */

    def toCString: CString = {
      /* Convert the receiver to a C string. */

      val enc = Charset.defaultCharset.newEncoder;
      val in = CharBuffer.wrap(s);
      var sz: Int = (s.length*enc.averageBytesPerChar + 1).toInt;
      var out = ByteBuffer.allocate(sz);

      loop[CString] { exit =>
	/* If there's still stuff to encode, then encode it.  Otherwise,
	 * there must be some dregs left in the encoder, so flush them out.
	 */
	val r = if (in.hasRemaining) enc.encode(in, out, true)
		else enc.flush(out);

	/* Sift through the wreckage to figure out what to do. */
	if (r.isError) r.throwException();
	else if (r.isOverflow) {
	  /* No space in the buffer.  Make it bigger. */

	  sz *= 2;
	  val newout = ByteBuffer.allocate(sz);
	  out.flip(); newout.put(out);
	  out = newout;
	} else if (r.isUnderflow) {
	  /* All done.  Check that there are no unexpected zero bytes -- so
	   * this will indeed be a valid C string -- and convert into a byte
	   * array that the C code will be able to pick apart.
	   */

	  out.flip(); val n = out.limit; val u = out.array;
	  if ({val z = u.indexOf(0); 0 <= z && z < n})
	    throw new InvalidCStringException("null byte in encoding");
	  val v = new Array[Byte](n + 1);
	  out.array.copyToArray(v, 0, n);
	  v(n) = 0;
	  exit(v);
	}
      }
    }
  }

  implicit class ConvertCStringToJString(v: CString) {
    /* Magic to convert a C string into a `proper' string. */

    def toJString: String = {
      /* Convert the receiver to a C string.
       *
       * We do this by hand, rather than relying on the JNI's built-in
       * conversions, because we use the default encoding taken from the
       * locale settings, rather than the ridiculous `modified UTF-8' which
       * is (a) insensitive to the user's chosen locale and (b) not actually
       * UTF-8 either.
       */

      val inlen = v.indexOf(0) match {
	case -1 => v.length
	case n => n
      }
      val dec = Charset.defaultCharset.newDecoder;
      val in = ByteBuffer.wrap(v, 0, inlen);
      dec.decode(in).toString
    }
  }
}
import StringImplicits._;

/*----- Main code ---------------------------------------------------------*/

/* Import the native code library. */
System.loadLibrary("toy");

/* Native types.
 *
 * See `jni.c'.  There's no good way to hand a C pointer into Java, so we
 * just copy whole structures into Java byte arrays and hope.  Well, also we
 * tag them so we can detect mixups.
 */
type Wrapper = Array[Byte];
class NativeObjectTypeException(msg: String) extends RuntimeException(msg);

/*----- Error codes -------------------------------------------------------*/

/* Machinery for collecting error information from C. */
protected case class ErrorEntry(val tag: String, val err: Int);
@native protected def errtab: Array[ErrorEntry];
@native protected def strerror(err: Int): CString;

object Errno extends Enumeration {
  /* System errors.
   *
   * There are two slight difficulties here.
   *
   *   * Not all target systems have the same errors.  C has a preprocessor
   *	 to deal with this, but we don't; so instead we'll define all of the
   *	 errors we'll ever need, but maybe with bogus values.
   *
   *   * Some systems reuse code numbers for two different error names, e.g.,
   *	 both `EAGAIN' and `EWOULDBLOCK' are the same on Linux -- but not
   *	 necessarily on other systems.  Scala's `Enumeration' machinery
   *	 doesn't like sharing `id' numbers between values.
   *
   * We augment the value type with an additional `code' value which is the
   * actual system error code; we arbitrarily pick one error symbol with a
   * given code to be `canonical', i.e., it has E.id == E.code; the others
   * have synthetic `id' values.  And symbols which don't correspond to any
   * error on the target system have synthetic `id' /and/ `code', so that
   * they can still be spoken about, but won't match any real error.
   */

  private val tagmap = { // map names to numbers based on what C reports
    val b = Map.newBuilder[String, Int];
    for (ErrorEntry(tag, err) <- errtab) b += tag -> err;
    b.result
  }

  private val seen = HashSet[Int]();	// which error codes have been taken

  private var wrong = -256;		// next synthetic code
  private def nextwrong: Int = { val w = wrong; wrong -= 1; w }

  class Val private[Errno](tag: String, val code: Int, id: Int)
	  extends super.Val(id, tag) {
    /* Our augmented error type. */

    def message: String = strerror(code).toJString;
  }
  private class UnknownError(code: Int)
	  extends Val("<unknown>", code, code);

  private def err(tag: String, code: Int): Val = {
    /* Construct an error symbol given its tag string and a code number. */

    if (code < 0) new Val(tag, code, code)
    else if (seen contains code) new Val(tag, code, nextwrong)
    else { seen += code; new Val(tag, code, code) }
  }
  private def err(tag: String): Val =
    err(tag, tagmap.getOrElse(tag, nextwrong));

  def byid(id: Int): Value = {
    if (seen contains id) apply(id)
    else new UnknownError(id)
  }

  val OK = err("OK", 0);		// `errno' zero is a real thing

  /*
     ;;; The errno name table is very boring to type.  To make life less
     ;;; awful, put the errno names in this list and evaluate the code to
     ;;; get Emacs to regenerate it.

     (let ((errors '(EPERM ENOENT ESRCH EINTR EIO ENXIO E2BIG ENOEXEC EBADF
		     ECHILD EAGAIN ENOMEM EACCES EFAULT ENOTBLK EBUSY EEXIST
		     EXDEV ENODEV ENOTDIR EISDIR EINVAL ENFILE EMFILE ENOTTY
		     ETXTBSY EFBIG ENOSPC ESPIPE EROFS EMLINK EPIPE EDOM
		     ERANGE

		     EDEADLK ENAMETOOLONG ENOLCK ENOSYS ENOTEMPTY ELOOP
		     EWOULDBLOCK ENOMSG EIDRM ECHRNG EL2NSYNC EL3HLT EL3RST
		     ELNRNG EUNATCH ENOCSI EL2HLT EBADE EBADR EXFULL ENOANO
		     EBADRQC EBADSLT EDEADLOCK EBFONT ENOSTR ENODATA ETIME
		     ENOSR ENONET ENOPKG EREMOTE ENOLINK EADV ESRMNT ECOMM
		     EPROTO EMULTIHOP EDOTDOT EBADMSG EOVERFLOW ENOTUNIQ
		     EBADFD EREMCHG ELIBACC ELIBBAD ELIBSCN ELIBMAX ELIBEXEC
		     EILSEQ ERESTART ESTRPIPE EUSERS ENOTSOCK EDESTADDRREQ
		     EMSGSIZE EPROTOTYPE ENOPROTOOPT EPROTONOSUPPORT
		     ESOCKTNOSUPPORT EOPNOTSUPP EPFNOSUPPORT EAFNOSUPPORT
		     EADDRINUSE EADDRNOTAVAIL ENETDOWN ENETUNREACH ENETRESET
		     ECONNABORTED ECONNRESET ENOBUFS EISCONN ENOTCONN
		     ESHUTDOWN ETOOMANYREFS ETIMEDOUT ECONNREFUSED EHOSTDOWN
		     EHOSTUNREACH EALREADY EINPROGRESS ESTALE EUCLEAN ENOTNAM
		     ENAVAIL EISNAM EREMOTEIO EDQUOT ENOMEDIUM EMEDIUMTYPE
		     ECANCELED ENOKEY EKEYEXPIRED EKEYREVOKED EKEYREJECTED
		     EOWNERDEAD ENOTRECOVERABLE ERFKILL EHWPOISON)))
       (save-excursion
	 (goto-char (point-min))
	 (search-forward (concat "***" "BEGIN errtab" "***"))
	 (beginning-of-line 2)
	 (delete-region (point)
			(progn
			  (search-forward "***END***")
			  (beginning-of-line)
			  (point)))
	 (dolist (err errors)
	   (insert (format "  val %s = err(\"%s\");\n" err err)))))
  */
  /***BEGIN errtab***/
  val EPERM = err("EPERM");
  val ENOENT = err("ENOENT");
  val ESRCH = err("ESRCH");
  val EINTR = err("EINTR");
  val EIO = err("EIO");
  val ENXIO = err("ENXIO");
  val E2BIG = err("E2BIG");
  val ENOEXEC = err("ENOEXEC");
  val EBADF = err("EBADF");
  val ECHILD = err("ECHILD");
  val EAGAIN = err("EAGAIN");
  val ENOMEM = err("ENOMEM");
  val EACCES = err("EACCES");
  val EFAULT = err("EFAULT");
  val ENOTBLK = err("ENOTBLK");
  val EBUSY = err("EBUSY");
  val EEXIST = err("EEXIST");
  val EXDEV = err("EXDEV");
  val ENODEV = err("ENODEV");
  val ENOTDIR = err("ENOTDIR");
  val EISDIR = err("EISDIR");
  val EINVAL = err("EINVAL");
  val ENFILE = err("ENFILE");
  val EMFILE = err("EMFILE");
  val ENOTTY = err("ENOTTY");
  val ETXTBSY = err("ETXTBSY");
  val EFBIG = err("EFBIG");
  val ENOSPC = err("ENOSPC");
  val ESPIPE = err("ESPIPE");
  val EROFS = err("EROFS");
  val EMLINK = err("EMLINK");
  val EPIPE = err("EPIPE");
  val EDOM = err("EDOM");
  val ERANGE = err("ERANGE");
  val EDEADLK = err("EDEADLK");
  val ENAMETOOLONG = err("ENAMETOOLONG");
  val ENOLCK = err("ENOLCK");
  val ENOSYS = err("ENOSYS");
  val ENOTEMPTY = err("ENOTEMPTY");
  val ELOOP = err("ELOOP");
  val EWOULDBLOCK = err("EWOULDBLOCK");
  val ENOMSG = err("ENOMSG");
  val EIDRM = err("EIDRM");
  val ECHRNG = err("ECHRNG");
  val EL2NSYNC = err("EL2NSYNC");
  val EL3HLT = err("EL3HLT");
  val EL3RST = err("EL3RST");
  val ELNRNG = err("ELNRNG");
  val EUNATCH = err("EUNATCH");
  val ENOCSI = err("ENOCSI");
  val EL2HLT = err("EL2HLT");
  val EBADE = err("EBADE");
  val EBADR = err("EBADR");
  val EXFULL = err("EXFULL");
  val ENOANO = err("ENOANO");
  val EBADRQC = err("EBADRQC");
  val EBADSLT = err("EBADSLT");
  val EDEADLOCK = err("EDEADLOCK");
  val EBFONT = err("EBFONT");
  val ENOSTR = err("ENOSTR");
  val ENODATA = err("ENODATA");
  val ETIME = err("ETIME");
  val ENOSR = err("ENOSR");
  val ENONET = err("ENONET");
  val ENOPKG = err("ENOPKG");
  val EREMOTE = err("EREMOTE");
  val ENOLINK = err("ENOLINK");
  val EADV = err("EADV");
  val ESRMNT = err("ESRMNT");
  val ECOMM = err("ECOMM");
  val EPROTO = err("EPROTO");
  val EMULTIHOP = err("EMULTIHOP");
  val EDOTDOT = err("EDOTDOT");
  val EBADMSG = err("EBADMSG");
  val EOVERFLOW = err("EOVERFLOW");
  val ENOTUNIQ = err("ENOTUNIQ");
  val EBADFD = err("EBADFD");
  val EREMCHG = err("EREMCHG");
  val ELIBACC = err("ELIBACC");
  val ELIBBAD = err("ELIBBAD");
  val ELIBSCN = err("ELIBSCN");
  val ELIBMAX = err("ELIBMAX");
  val ELIBEXEC = err("ELIBEXEC");
  val EILSEQ = err("EILSEQ");
  val ERESTART = err("ERESTART");
  val ESTRPIPE = err("ESTRPIPE");
  val EUSERS = err("EUSERS");
  val ENOTSOCK = err("ENOTSOCK");
  val EDESTADDRREQ = err("EDESTADDRREQ");
  val EMSGSIZE = err("EMSGSIZE");
  val EPROTOTYPE = err("EPROTOTYPE");
  val ENOPROTOOPT = err("ENOPROTOOPT");
  val EPROTONOSUPPORT = err("EPROTONOSUPPORT");
  val ESOCKTNOSUPPORT = err("ESOCKTNOSUPPORT");
  val EOPNOTSUPP = err("EOPNOTSUPP");
  val EPFNOSUPPORT = err("EPFNOSUPPORT");
  val EAFNOSUPPORT = err("EAFNOSUPPORT");
  val EADDRINUSE = err("EADDRINUSE");
  val EADDRNOTAVAIL = err("EADDRNOTAVAIL");
  val ENETDOWN = err("ENETDOWN");
  val ENETUNREACH = err("ENETUNREACH");
  val ENETRESET = err("ENETRESET");
  val ECONNABORTED = err("ECONNABORTED");
  val ECONNRESET = err("ECONNRESET");
  val ENOBUFS = err("ENOBUFS");
  val EISCONN = err("EISCONN");
  val ENOTCONN = err("ENOTCONN");
  val ESHUTDOWN = err("ESHUTDOWN");
  val ETOOMANYREFS = err("ETOOMANYREFS");
  val ETIMEDOUT = err("ETIMEDOUT");
  val ECONNREFUSED = err("ECONNREFUSED");
  val EHOSTDOWN = err("EHOSTDOWN");
  val EHOSTUNREACH = err("EHOSTUNREACH");
  val EALREADY = err("EALREADY");
  val EINPROGRESS = err("EINPROGRESS");
  val ESTALE = err("ESTALE");
  val EUCLEAN = err("EUCLEAN");
  val ENOTNAM = err("ENOTNAM");
  val ENAVAIL = err("ENAVAIL");
  val EISNAM = err("EISNAM");
  val EREMOTEIO = err("EREMOTEIO");
  val EDQUOT = err("EDQUOT");
  val ENOMEDIUM = err("ENOMEDIUM");
  val EMEDIUMTYPE = err("EMEDIUMTYPE");
  val ECANCELED = err("ECANCELED");
  val ENOKEY = err("ENOKEY");
  val EKEYEXPIRED = err("EKEYEXPIRED");
  val EKEYREVOKED = err("EKEYREVOKED");
  val EKEYREJECTED = err("EKEYREJECTED");
  val EOWNERDEAD = err("EOWNERDEAD");
  val ENOTRECOVERABLE = err("ENOTRECOVERABLE");
  val ERFKILL = err("ERFKILL");
  val EHWPOISON = err("EHWPOISON");
  /***end***/
}
import Errno.{Val => Errno, EEXIST, EISDIR, ENOENT, ENOTDIR};

object SystemError {
  /* Pattern matching for `SystemError', below. */

  def apply(err: Errno, what: String): SystemError =
    new SystemError(err, what);
  def unapply(e: Exception): Option[(Errno, String)] = e match {
    case e: SystemError => Some((e.err, e.what))
    case _ => None
  }
}
class SystemError (val err: Errno, val what: String) extends Exception {
  /* An error from a syscall or similar, usually from native code. */

  /* A constructor which takes an error number, for easier access from C. */
  private def this(err: Int, what: CString)
    { this(Errno.byid(err).asInstanceOf[Errno], what.toJString); }

  override def getMessage(): String = s"$what: ${err.message}";
}

/*----- Basic file operations ---------------------------------------------*/

@native protected def unlink(path: CString);
def unlink(path: String) { unlink(path.toCString); }
@native protected def rmdir(path: CString);
def rmdir(path: String) { rmdir(path.toCString); }
@native protected def mkdir(path: CString, mode: Int);
def mkdir(path: String, mode: Int) { mkdir(path.toCString, mode); }
@native protected def mkfile(path: CString, mode: Int);
def mkfile(path: String, mode: Int) { mkfile(path.toCString, mode); }
@native protected def rename(from: CString, to: CString);
def rename(from: String, to: String)
  { rename(from.toCString, to.toCString); }

@native def fdint(fd: FileDescriptor): Int;
@native def newfd(fd: Int): FileDescriptor;
@native def isatty(fd: FileDescriptor): Boolean;

/*----- File status information -------------------------------------------*/

/* These are the traditional values, but the C code carefully arranges to
 * return them regardless of what your kernel actually thinks.
 */
final val S_IFMT = 0xf000;
final val S_IFIFO = 0x1000;
final val S_IFCHR = 0x2000;
final val S_IFDIR = 0x4000;
final val S_IFBLK = 0x6000;
final val S_IFREG = 0x8000;
final val S_IFLNK = 0xa000;
final val S_IFSOCK = 0xc000;

/* Primitive read-the-file-status calls. */
@native protected def stat(path: CString): sys.FileInfo;
def stat(path: String): sys.FileInfo = stat(path.toCString);
@native protected def lstat(path: CString): sys.FileInfo;
def lstat(path: String): sys.FileInfo = lstat(path.toCString);

object FileInfo extends Enumeration {
  /* A simple enumeration of things a file might be.
   *
   * `HDLNK' is a hard link, used in `tar' files.
   */
  val FIFO, CHR, DIR, BLK, REG, LNK, SOCK, HDLNK, UNK = Value;
  type Type = Value;
}
import FileInfo._;

class FileInfo private[this](val devMajor: Int, val devMinor: Int,
			     val ino: Long, val mode: Int, val nlink: Int,
			     val uid: Int, val gid: Int,
			     _rdevMinor: Int, _rdevMajor: Int,
			     val size: Long,
			     val blksize: Int, val blocks: Long,
			     val atime: Date, val mtime: Date,
			     val ctime: Date) {
  /* Information about a file.  This is constructed directly from native
   * code.
   */

  private def this(devMajor: Int, devMinor: Int, ino: Long,
		   mode: Int, nlink: Int, uid: Int, gid: Int,
		   rdevMinor: Int, rdevMajor: Int,
		   size: Long, blksize: Int, blocks: Long,
		   atime: Long, mtime: Long, ctime: Long) {
    /* Lightly cook the values from the underlying `struct stat'. */

    this(devMajor, devMinor, ino, mode, nlink, uid, gid,
	 rdevMajor, rdevMinor, size, blksize, blocks,
	 new Date(atime), new Date(mtime), new Date(ctime));
  }

  /* Return the file permissions only. */
  def perms: Int = mode&0xfff;

  /* Return the filetype, as a `FileInfo.Type'. */
  def ftype: Type = (mode&S_IFMT) match {
    case S_IFIFO => FIFO
    case S_IFCHR => CHR
    case S_IFDIR => DIR
    case S_IFBLK => BLK
    case S_IFREG => REG
    case S_IFLNK => LNK
    case S_IFSOCK => SOCK
    case _ => UNK
  }

  private[this] def mustBeDevice() {
    /* Insist that you only ask for `rdev' fields on actual device nodes. */
    ftype match {
      case CHR | BLK => ok;
      case _ => throw new IllegalArgumentException("Object is not a device");
    }
  }

  /* Query the device-node numbers. */
  def rdevMajor: Int = { mustBeDevice(); _rdevMajor }
  def rdevMinor: Int = { mustBeDevice(); _rdevMinor }
}

/*----- Listing directories -----------------------------------------------*/

/* Primitive operations. */
@native protected def opendir(path: CString): Wrapper;
@native protected def readdir(path: CString, dir: Wrapper): CString;
@native protected def closedir(path: CString, dir: Wrapper);

protected abstract class BaseDirIterator[T](cpath: CString)
	extends LookaheadIterator[T] with Closeable {
  /* The underlying machinery for directory iterators.
   *
   * Subclasses must define `mangle' to convert raw filenames into a T.
   * We keep track of the path C-string, because we need to keep passing that
   * back to C for inclusion in error messages.  Recording higher-level
   * things is left for subclasses.
   */

  /* Constructors from more convenient types. */
  def this(path: String) { this(path.toCString); }
  def this(dir: File) { this(dir.getPath); }

  /* Cleaning up after ourselves. */
  override def close() { closedir(cpath, dir); }
  override protected def finalize() { super.finalize(); close(); }

  /* Subclass responsibility. */
  protected def mangle(file: String): T;

  /* Main machinery. */
  private[this] val dir = opendir(cpath);
  override protected def fetch(): Option[T] = readdir(cpath, dir) match {
    case null => None
    case f => f.toJString match {
      case "." | ".." => fetch()
      case jf => Some(mangle(jf))
    }
  }
}

class DirIterator(val path: String) extends BaseDirIterator[String](path) {
  /* Iterator over the basenames of files in a directory. */

  def this(dir: File) { this(dir.getPath); }

  override protected def mangle(file: String): String = file;
}

class DirFilesIterator private[this](val dir: File, cpath: CString)
	extends BaseDirIterator[File](cpath) {
  /* Iterator over full `File' objects in a directory. */

  def this(dir: File) { this(dir, dir.getPath.toCString); }
  def this(path: String) { this(new File(path), path.toCString); }

  override protected def mangle(file: String): File = new File(dir, file);
}

/*----- File locking ------------------------------------------------------*/

/* Primitive operations.  The low `mode' bits are for the lock file if we
 * have to create it.
 */
final val LKF_EXCL = 0x1000;
final val LKF_WAIT = 0x2000;
@native protected def lock(path: CString, mode: Int): Wrapper;
@native protected def unlock(lock: Wrapper);

class FileLock(path: String, flags: Int) extends Closeable {
  /* A class which represents a held lock on a file. */

  /* Constructors.  The default is to take an exclusive lock or fail
   * immediately.
   */
  def this(file: File, flags: Int) { this(file.getPath, flags); }
  def this(path: String) { this(path, LKF_EXCL | 0x1b6); }
  def this(file: File) { this(file.getPath, LKF_EXCL | 0x1b6); }

  /* The low-level lock object, actually a file descriptor. */
  private[this] val lk = lock(path.toCString, flags);

  /* Making sure things get cleaned up. */
  override def close() { unlock(lk); }
  override protected def finalize() { super.finalize(); close(); }
}

/*----- File implicits ----------------------------------------------------*/

object FileImplicits {
  implicit class FileOps(file: File) {
    /* Augment `File' with operations which throw informative (if low-level
     * and system-specific) exceptions rather than returning unhelpful
     * win/lose booleans.  These have names ending with `_!' because they
     * might explode.
     *
     * And some other useful methods.
     */

    /* Constructing names of files in a directory.  Honestly, I'm surprised
     * there isn't a method for this already.
     */
    def /(sub: String): File = new File(file, sub);

    /* Simple file operations. */
    def unlink_!() { unlink(file.getPath); }
    def rmdir_!() { rmdir(file.getPath); }
    def mkdir_!(mode: Int) { mkdir(file.getPath, mode); }
    def mkdir_!() { mkdir_!(0x1ff); }
    def mkfile_!(mode: Int) { mkfile(file.getPath, mode); }
    def mkfile_!() { mkfile_!(0x1b6); }
    def rename_!(to: File) { rename(file.getPath, to.getPath); }

    /* Listing directories. */
    def withFilesIterator[T](body: DirFilesIterator => T): T = {
      val iter = new DirFilesIterator(file.getPath);
      try { body(iter) } finally { iter.close(); }
    }
    def foreachFile(fn: File => Unit) { withFilesIterator(_.foreach(fn)) }
    def files_! : Seq[File] = withFilesIterator { _.toSeq };

    /* Low-level lFile information. */
    def stat_! : FileInfo = stat(file.getPath);
    def lstat_! : FileInfo = lstat(file.getPath);

    /* Specific file-status queries. */
    private[this] def statish[T](statfn: String => FileInfo,
				 ifexists: FileInfo => T,
				 ifmissing: => T): T =
      (try { statfn(file.getPath) }
       catch { case SystemError(ENOENT, _) => null }) match {
	case null => ifmissing
	case st => ifexists(st)
      };
    def exists_! : Boolean = statish(stat _, _ => true, false);
    def isfifo_! : Boolean = statish(stat _, _.ftype == FIFO, false);
    def isblk_! : Boolean = statish(stat _, _.ftype == BLK, false);
    def isdir_! : Boolean = statish(stat _, _.ftype == DIR, false);
    def ischr_! : Boolean = statish(stat _, _.ftype == CHR, false);
    def isreg_! : Boolean = statish(stat _, _.ftype == REG, false);
    def islnk_! : Boolean = statish(lstat _, _.ftype == LNK, false);
    def issock_! : Boolean = statish(stat _, _.ftype == SOCK, false);

    /* Slightly more cooked file operations. */
    def remove_!() {
      /* Delete a file, or directory, whatever it is. */
      try { unlink_!(); return; }
      catch {
	case SystemError(ENOENT, _) => return;
	case SystemError(EISDIR, _) =>
	  try { rmdir_!(); return; }
	  catch { case SystemError(ENOENT, _) => return; }
      }
    }

    def rmTree() {
      /* Delete a thing recursively. */
      def walk(f: File) {
	if (f.isdir_!) f.foreachFile(walk _);
	f.remove_!();
      }
      walk(file);
    }

    def mkdirNew_!() {
      /* Make a directory if there's nothing there already. */
      try { mkdir_!(); }
      catch { case SystemError(EEXIST, _) => ok; }
    }

    /* File locking. */
    def lock_!(flags: Int): FileLock = new FileLock(file.getPath, flags);
    def lock_!(): FileLock = lock_!(LKF_EXCL | 0x1b6);
    def withLock[T](flags: Int)(body: => T): T = {
      val lk = lock_!(flags);
      try { body } finally { lk.close(); }
    }
    def withLock[T](body: => T): T = withLock(LKF_EXCL | 0x1b6) { body };

    /* Opening files.  Again, I'm surprised this isn't here already. */
    def open(): FileInputStream = new FileInputStream(file);
    def openForOutput(): FileOutputStream = new FileOutputStream(file);
    def reader(): BufferedReader =
      new BufferedReader(new InputStreamReader(open()));
    def writer(): BufferedWriter =
      new BufferedWriter(new OutputStreamWriter(openForOutput()));
    def withInput[T](body: FileInputStream => T): T = {
      val in = open();
      try { body(in) }
      finally { in.close(); }
    }
    def withOutput[T](body: FileOutputStream => T): T = {
      val out = openForOutput();
      try { body(out) } finally { out.close(); }
    }
    def withReader[T](body: BufferedReader => T): T = withInput { in =>
      body(new BufferedReader(new InputStreamReader(in)))
    };
    def withWriter[T](body: BufferedWriter => T): T = withOutput { out =>
      val w = new BufferedWriter(new OutputStreamWriter(out));
      /* Do this the hard way, so that we flush the `BufferedWriter'. */
      try { body(w) } finally { w.close(); }
    }
  }
}
import FileImplicits._;

/*----- Miscellaneous file hacks ------------------------------------------*/

def freshFile(d: File): File = {
  /* Return the name of a freshly created file in directory D. */

  val buf = new Array[Byte](6);
  val b = new StringBuilder;

  loop[File] { exit =>
    /* Keep going until we find a fresh one. */

    /* Provide a prefix.  Mostly this is to prevent the file starting with
     * an unfortunate character like `-'.
     */
    b ++= "tmp.";

    /* Generate some random bytes. */
    rng.nextBytes(buf);

    /* Now turn the bytes into a filename.  This is a cheesy implementation
     * of Base64 encoding.
     */
    var a = 0;
    var n = 0;

    for (x <- buf) {
      a = (a << 8) | x; n += 8;
      while (n >= 6) {
	val y = (a >> n - 6)&0x3f; n -= 6;
	b += (if (y < 26) 'A' + y
	      else if (y < 52) 'a' + (y - 26)
	      else if (y < 62) '0' + (y - 52)
	      else if (y == 62) '+'
	      else '-').toChar;
      }
    }

    /* Make the filename, and try to create the file.  If we succeed, we
     * win.
     */
    val f = d/b.result; b.clear();
    try { f.mkfile_!(); exit(f); }
    catch { case SystemError(EEXIST, _) => ok; }
  }
}

/*----- Running a command -------------------------------------------------*/

private val devnull = new File("/dev/null");

private def captureStream(in: InputStream, out: StringBuilder) {
  /* Capture the INSTREAM's contents in a string. */

  for ((buf, n) <- blocks(new InputStreamReader(in)))
    out.appendAll(buf, 0, n);
}

class SubprocessFailed(val cmd: Seq[String], rc: Int, stderr: String)
	extends Exception {
  override def getMessage(): String =
    s"process (${quoteTokens(cmd)}) failed (rc = $rc):\n" + stderr
}

def runCommand(cmd: String*): (String, String) = {
  /* Run a command, returning its stdout and stderr. */

  withCleaner { clean =>

    /* Create the child process and pick up the ends of its streams. */
    val pb = new ProcessBuilder(cmd.asJava).redirectInput(devnull);
    val kid = pb.start(); clean { kid.destroy(); }
    val out = kid.getInputStream(); clean { out.close(); }
    val err = kid.getErrorStream(); clean { err.close(); }

    /* Capture the output in threads, so we don't block.  Also, wait for the
     * child to complete.  Amazingly, messing with threads here isn't too
     * much of a disaster.
     */
    val bout, berr = new StringBuilder;
    val rdout = thread("capture process stdout", daemon = false) {
      captureStream(out, bout);
    }
    val rderr = thread("capture process stderr", daemon = false) {
      captureStream(err, berr);
    }
    val wait = thread("await process exit", daemon = false) {
      kid.waitFor();
    }
    rdout.join(); rderr.join(); wait.join();

    /* Check the exit status. */
    val rc = kid.exitValue;
    if (rc != 0) throw new SubprocessFailed(cmd, rc, berr.result);

    /* We're all done. */
    return (bout.result, berr.result);
  }
}

/*----- Interrupt triggers ------------------------------------------------*/

private val triggerLock = new Object;
private final val maxTriggers = 2;
private var nTriggers = 0;
private var triggers: List[Wrapper] = Nil;

@native protected def makeTrigger(): Wrapper;
@native protected def destroyTrigger(trig: Wrapper);
@native protected def resetTrigger(trig: Wrapper);
@native protected def trigger(trig: Wrapper);

private def getTrigger(): Wrapper = {
  triggerLock synchronized {
    if (nTriggers == 0)
      makeTrigger()
    else {
      val trig = triggers.head;
      triggers = triggers.tail;
      nTriggers -= 1;
      trig
    }
  }
}

private def putTrigger(trig: Wrapper) {
  resetTrigger(trig);
  triggerLock synchronized {
    if (nTriggers >= maxTriggers)
      destroyTrigger(trig);
    else {
      triggers ::= trig;
      nTriggers += 1;
    }
  }
}

private def withTrigger[T](body: Wrapper => T): T = {
  val trig = getTrigger();
  try { body(trig) }
  finally { putTrigger(trig); }
}

def interruptWithTrigger[T](body: Wrapper => T): T = {
  /* interruptWithTrigger { TRIG => BODY }
   *
   * Execute BODY and return its result.  If the thread receives an
   * interrupt, the trigger TRIG will be pulled.  See `interruptably' for the
   * full semantics.
   */

  withTrigger { trig =>
    interruptably { body(trig) } onInterrupt { trigger(trig); }
  };
}

/*----- Connecting to a server --------------------------------------------*/

/* Primitive operations. */
final val CF_CLOSERD = 1;
final val CF_CLOSEWR = 2;
final val CF_CLOSEMASK = CF_CLOSERD | CF_CLOSEWR;
@native protected def connect(path: CString, trig: Wrapper): Wrapper;
@native protected def send(conn: Wrapper, buf: CString,
			   start: Int, len: Int, trig: Wrapper);
@native protected def recv(conn: Wrapper, buf: CString,
			   start: Int, len: Int, trig: Wrapper): Int;
@native def closeconn(conn: Wrapper, how: Int);

class Connection(path: String) extends Closeable {

  /* The underlying primitive connection. */
  private[this] val conn = interruptWithTrigger { trig =>
    connect(path.toCString, trig);
  };

  /* Alternative constructors. */
  def this(file: File) { this(file.getPath); }

  /* Cleanup.*/
  override def close() { closeconn(conn, CF_CLOSEMASK); }
  override protected def finalize() { super.finalize(); close(); }

  class Input private[Connection] extends InputStream {
    /* An input stream which reads from the connection. */

    override def read(): Int = {
      val buf = new Array[Byte](1);
      val n = read(buf, 0, 1);
      if (n < 0) -1 else buf(0)&0xff;
    }
    override def read(buf: Array[Byte]): Int =
      read(buf, 0, buf.length);
    override def read(buf: Array[Byte], start: Int, len: Int) =
      interruptWithTrigger { trig => recv(conn, buf, start, len, trig); };
    override def close() { closeconn(conn, CF_CLOSERD); }
  }
  lazy val input = new Input;

  class Output private[Connection] extends OutputStream {
    /* An output stream which writes to the connection. */

    override def write(b: Int) { write(Array[Byte](b.toByte), 0, 1); }
    override def write(buf: Array[Byte]) { write(buf, 0, buf.length); }
    override def write(buf: Array[Byte], start: Int, len: Int)
      { interruptWithTrigger { trig => send(conn, buf, start, len, trig); } }
    override def close() { closeconn(conn, CF_CLOSEWR); }
  }
  lazy val output = new Output;
}

/*----- Crypto-library hacks ----------------------------------------------*/

@native def hashsz(hash: String): Int;
      /* Return the output hash size for the named HASH function, or -1. */

/*----- That's all, folks -------------------------------------------------*/

}