contrib/sb-posix/README

   1 -*- Text -*-
   2
   3 * Scope
   4
   5 The scope of this interface is "operating system calls on a typical
   6 Unixlike platform".  This is section 2 of the Unix manual, plus
   7 section 3 calls that are (a) typically found in libc, but (b) not part
   8 of the C standard.  For example, we intend to provide support for
   9 opendir() and readdir() , but not for printf()
  10
  11 Some facilities are omitted where they offer absolutely no additional
  12 use over some portable function, or would be actively dangerous to the
  13 consistency of Lisp.  Not all functions are available on all
  14 platforms.  [TBD: unavailable functions should (a) not exist, or (b)
  15 exist but signal some kind of "not available on this platform" error]
  16
  17 The general intent is for a low-level interface.  There are three
  18 reasons for this: it's easier to write a high-level interface given a
  19 low-level one than vice versa, there are fewer philosophical
  20 disagreements about what it should look like, and the work of
  21 implementing it is easily parallelisable - and in fact, can be
  22 attempted on an as-needed basis by the various people who want it.
  23
  24 * Function names
  25
  26 The package name for this interface is SB-POSIX.  In this package
  27 there is a Lisp function for each supported Unix function, and a
  28 variable or constant for each supported unix constant.  A symbol name
  29 is derived from the C binding's name, by (a) uppercasing, then (b)
  30 replacing underscore (#\_) characters with the hyphen (#\-)
  31
  32 No other changes to "Lispify" symbol names are made, so creat()
  33 becomes CREAT, not CREATE
  34
  35 The user is encouraged not to (USE-PACKAGE :SB-POSIX) but instead to
  36 use the SB-POSIX: prefix on all references, as some of our symbols
  37 have the same name as CL symbols (OPEN, CLOSE, SIGNAL etc).
  38
  39 [ Rationale: We use similar names to the C bindings so that unix
  40 manual pages can be used for documentation.  To avoid name clashes
  41 with CL or other functions, the approaches considered were (a) prefix
  42 the names of clashing symbols with "POSIX-" or similar, (b) prefix
  43 _all_ symbols with "POSIX-", (c) use the packaging system to resolve
  44 ambiguities.  (a) was rejected as the set of symbols we may
  45 potentially clash with is not fixed (for example, if new symbols are
  46 added to SB-EXT) so symbols might have to be renamed over the lifetime
  47 of SB-POSIX, which is not good.  The choice between (b) and (c) was
  48 made on the grounds that POSIX-OPEN is about as much typing as
  49 SB-POSIX:OPEN anyway, and symbol munging is, the author feels,
  50 slightly tacky, when there's a package system available to do it more
  51 cleanly ]
  52
  53
  54 * Parameters
  55
  56 The calling convention is modelled after that of CMUCL's UNIX package:
  57 in particular, it's like the C interface except
  58
  59 a) length arguments are omitted or optional where the sensible value
  60 is obvious.  For example,
  61
  62 (read fd buffer &optional (length (length buffer))) => bytes-read
  63
  64 b) where C simulates "out" parameters using pointers (for instance, in
  65 pipe() or socketpair()) we may use multiple return values instead.
  66 This doesn't apply to data transfer functions that fill buffers.
  67
  68 c) some functions accept objects such as filenames or file
  69 descriptors.  In the C bindings these are strings and small integers
  70 respectively.  For the Lisp programmer's convenience we introduce
  71 "filename designators" and "file descriptor designator" concepts such
  72 that CL pathnames or open streams can be passed to these functions.
  73
  74 [ Rationale: Keeping exact 1:1 correspondence with C conventions is
  75 less important here, as the function argument list can easily be
  76 accessed to find out exactly what the arguments are.  Designators
  77 are primarily a convenience feature ]
  78
  79 * Return values
  80
  81 The return value is usually the same as for the C binding, except in
  82 error cases: where the C function is defined as returning some
  83 sentinel value and setting "errno" on error, we instead signal an
  84 error of type SYSCALL-ERROR.  The actual error value ("errno") is
  85 stored in this condition and can be accessed with SYSCALL-ERRNO.
  86 [TBA: some interface to strerror, to get the user-readable translation
  87 of the error number]
  88
  89 We do not automatically translate the returned value into "Lispy"
  90 objects - for example, SB-POSIX:OPEN returns a small integer, not a
  91 stream.
  92
  93 [ Rationale: This is an interface to POSIX, not a high-level interface
  94 that uses POSIX, and many people using it will actually want to mess
  95 with the file descriptors directly.  People needing Lispy interfaces
  96 can implement them atop this - or indeed, use the existing COMMON-LISP
  97 package, which already has many high-level constructs built on top of
  98 the operating system ;-) ]
  99
 100
 101 * Implementation
 102
 103 The initial implementation is in contrib/sb-posix, and being filled
 104 out on an as-needed basis.  Contributions following these style rules
 105 are welcome from anyone who writes them, provided the author is happy
 106 to release the code as Public Domain or MIT-style licence.
 107
 108 See/update the TODO list for current status
 109
 110 ** Designators
 111
 112 See designator.lisp, add a define-designator form
 113
 114 ** Adding functions
 115
 116 The use of DEFINE-CALL macro in interface.lisp should be obvious from
 117 the existing examples, if less so from the macroexpansion
 118