GNU Info

(guile.info)Conventions

---

Next: Ports and File Descriptors Up: POSIX

---

Enter node , (file) or (file)node

POSIX Interface Conventions
===========================

These interfaces provide access to operating system facilities.  They
provide a simple wrapping around the underlying C interfaces to make
usage from Scheme more convenient.  They are also used to implement the
Guile port of Note: The Scheme shell (scsh).

Generally there is a single procedure for each corresponding Unix
facility.  There are some exceptions, such as procedures implemented for
speed and convenience in Scheme with no primitive Unix equivalent,
e.g., `copy-file'.

The interfaces are intended as far as possible to be portable across
different versions of Unix.  In some cases procedures which can't be
implemented on particular systems may become no-ops, or perform limited
actions.  In other cases they may throw errors.

General naming conventions are as follows:

   * The Scheme name is often identical to the name of the underlying
     Unix facility.

   * Underscores in Unix procedure names are converted to hyphens.

   * Procedures which destructively modify Scheme data have exclaimation
     marks appended, e.g., `recv!'.

   * Predicates (returning only `#t' or `#f') have question marks
     appended, e.g., `access?'.

   * Some names are changed to avoid conflict with dissimilar interfaces
     defined by scsh, e.g., `primitive-fork'.

   * Unix preprocessor names such as `EPERM' or `R_OK' are converted to
     Scheme variables of the same name (underscores are not replaced
     with hyphens).

Unexpected conditions are generally handled by raising exceptions.
There are a few procedures which return a special value if they don't
succeed, e.g., `getenv' returns `#f' if it the requested string is not
found in the environment.  These cases are noted in the documentation.

For ways to deal with exceptions, Note: Exceptions.

Errors which the C-library would report by returning a NULL pointer or
through some other means are reported by raising a `system-error'
exception.  The value of the Unix `errno' variable is available in the
data passed by the exception.

Here's an ad-hoc(1) way to extract the `errno' value from an exception:

     (catch
      'system-error
      (lambda ()
        (mkdir "/this-ought-to-fail-if-I'm-not-root"))
      (lambda stuff
        (let ((errno (car (list-ref stuff 4))))
          (cond
           ((= errno EACCES)
            (display "You're not allowed to do that."))
           ((= errno EEXIST)
            (display "Already exists."))
           (#t
            (display (strerror errno))))
          (newline))))

The important thing to note is that the `errno' value can be extracted
with `(car (list-ref stuff 4))'.

---------- Footnotes ----------

(1) This may be changed in the future; be prepared to rewrite this sort
of code.