contrib/sb-posix/README

   1 -*- Text -*-
   2
   3 Note: this file's description of a POSIX binding for Common Lisp does
   4 not necessarily describe the state of the sb-posix module.  If you're
   5 looking for a description sb-posix, look at sb-posix.texinfo in this
   6 directory.
   7
   8 * Scope
   9
  10 The scope of this interface is "operating system calls on a typical
  11 Unixlike platform".  This is section 2 of the Unix manual, plus
  12 section 3 calls that are (a) typically found in libc, but (b) not part
  13 of the C standard.  For example, we intend to provide support for
  14 opendir() and readdir(), but not for printf().  Note that we do not
  15 assert or imply any claim of conformance with the official standards
  16 issued by POSIX groups or SVID or anyone else: we're simply using
  17 "POSIX" in a generic sense to refer to Unix and Unix-like systems.
  18
  19 Some facilities are omitted where they offer absolutely no additional
  20 use over some portable function, or would be actively dangerous to the
  21 consistency of Lisp.  Not all functions are available on all
  22 platforms.  [TBD: unavailable functions should (a) not exist, or (b)
  23 exist but signal some kind of "not available on this platform" error]
  24
  25 The general intent is for a low-level interface.  There are three
  26 reasons for this: it's easier to write a high-level interface given a
  27 low-level one than vice versa, there are fewer philosophical
  28 disagreements about what it should look like, and the work of
  29 implementing it is easily parallelisable - and in fact, can be
  30 attempted on an as-needed basis by the various people who want it.
  31
  32 * Symbol names
  33
  34 In SBCL this interface is in the SB-POSIX package.  This package
  35 contains a Lisp function for each supported Unix function, and a
  36 variable or constant for each supported unix constant.  A symbol name
  37 is derived from the C binding's name, by (a) uppercasing, then (b)
  38 removing leading underscores (#\_) then replacing remaining underscore
  39 characters with the hyphen (#\-). The requirement to uppercase is so
  40 that in a standard upcasing reader the user may write posix:creat
  41 instead of posix:|creat| as would otherise be required - some
  42 extra-standard implementations may have alternative means to achieve
  43 the same effect.
  44
  45 No other changes to "Lispify" symbol names are made, so creat()
  46 becomes CREAT, not CREATE
  47
  48 The user is encouraged not to (USE-PACKAGE :SB-POSIX) but instead to
  49 use the SB-POSIX: prefix on all references, as some of our symbols
  50 have the same name as CL symbols (OPEN, CLOSE, SIGNAL etc).
  51
  52 [ Rationale: We use similar names to the C bindings so that unix
  53 manual pages can be used for documentation.  To avoid name clashes
  54 with CL or other functions, the approaches considered were (a) prefix
  55 the names of clashing symbols with "POSIX-" or similar, (b) prefix
  56 _all_ symbols with "POSIX-", (c) use the packaging system to resolve
  57 ambiguities.  (a) was rejected as the set of symbols we may
  58 potentially clash with is not fixed (for example, if new symbols are
  59 added to SB-EXT) so symbols might have to be renamed over the lifetime
  60 of SB-POSIX, which is not good.  The choice between (b) and (c) was
  61 made on the grounds that POSIX-OPEN is about as much typing as
  62 SB-POSIX:OPEN anyway, and symbol munging is, the author feels,
  63 slightly tacky, when there's a package system available to do it more
  64 cleanly ]
  65
  66
  67 * Types
  68
  69 Some functions accept objects such as filenames or file
  70 descriptors. In the C binding to POSIX these are represented as
  71 strings and small integers respectively. For the Lisp programmer's
  72 convenience we introduce designators such that CL pathnames or open
  73 streams can be passed to these functions.
  74
  75 ** file-descriptor
  76
  77 A file-descriptor is a non-negative small integer.
  78
  79 A file-stream is a designator for a file-descriptor: the streams file
  80 descriptor is extracted.  Note that mixing io operations on a stream
  81 with operations directly on its descriptor may produce unexpected
  82 results if the stream is buffered.
  83
  84 ** filename
  85
  86 A filename is a string.
  87
  88 A pathname is a designator for a filename: the filename is computed
  89 using the same mechanism as the implementation would use to map
  90 pathnames to OS filenames internally.
  91
  92 In an implementation that supports pathnames to files on other hosts,
  93 using mechanisms not available to the underlying OS (for example,
  94 using an FTP or HTTP client in the Lisp implementation), the effect
  95 of supplying this interface with a pathname to such a file is undefined.
  96
  97
  98 ** buffer
  99
 100 A buffer is an opaque object which represents an area of memory that
 101 system calls may access.  It has accessors BUFFER-START and
 102 BUFFER-LENGTH, and can be created using ALLOCATE-BUFFER or GET-BUFFER.
 103
 104 [ TODO: GET-BUFFER is a silly name.  Come up with a better one ]
 105
 106 The object NIL is a designator for a buffer, meaning a NULL pointer.
 107
 108 A vector of (UNSIGNED-BYTE 8) is a designator for a buffer: it is
 109 converted to a buffer of appropriate start and length using an
 110 identity mapping.  This may or may not involve creating a copy of the
 111 data.
 112
 113 A vector of CHARACTER is a designator for a buffer: it is converted to
 114 a buffer of appropriate start and length using an implementation-
 115 defined transformation that obviously depends on the implementation's
 116 representation of characters.  This may or may not involve creating a
 117 copy of the data.
 118
 119 Implementations may optionally extend these designators to include
 120 other types - for example, types that already exist in the
 121 implementation's FFI.
 122
 123 ** Structures, unions
 124
 125 C structures and unions are opaque to Lisp and may be implemented
 126 using any appropriate method. Structure names are chosen according to
 127 the general rules for symbols.
 128
 129 Accessors must be provided for each documented field in the
 130 structure. These are named structure-name-field-name where the two
 131 components are chosen according to the general rules, with the
 132 exception that in cases where all fields in a given structure have a
 133 common prefix, that prefix is omitted. For example, stat.st_dev in C
 134 becomes STAT-DEV in Lisp.
 135
 136 For any structure that the user may need to allocate himself, there
 137 must also be a MAKE-structure-name function. This takes keyword
 138 arguments with names deriving from each documented field name
 139 according to the general rules for symbols.
 140
 141 [ TDB: GC issues for buffers/structures/unions: probably a
 142 WITHOUT-MOVING macro or similar that will stop them from being moved
 143 or collected during its extent ]
 144
 145
 146 ** Type conversion functions
 147
 148 For each of these types there is a function of the same name that
 149 converts any valid designator for the type into an object of said type.
 150
 151 This example is merely an example: actual output will vary between
 152 systems, implementations and environments
 153
 154 (with-open-file (o "/tmp/foo" :direction :output)
 155   (sb-posix:file-descriptor o))
 156 => 4
 157
 158 [ TBD: some memorable and nicely uniform protocol for transforming
 159 objects of these new types into instances of the Lisp-friendly types
 160 that may designate them: e.g how to get a stream from a fd ]
 161
 162
 163 * Function parameters
 164
 165 The calling convention is modelled after that of CMUCL's UNIX package:
 166 in particular, it's like the C interface except that
 167
 168 a) length arguments are omitted or optional where the sensible value
 169 is obvious.  For example,
 170
 171 (read fd buffer &optional (length (length buffer))) => bytes-read
 172
 173 b) where C simulates "out" parameters using pointers (for instance, in
 174 pipe() or socketpair()) these may be optional or omitted in the Lisp
 175 interface: if not provided, appropriate objects will be allocated and
 176 returned (using multiple return values if necessary).
 177
 178 c) some functions accept objects such as filenames or file
 179 descriptors.  Wherever these are specified as such in the C bindings,
 180 the Lisp interface accepts designators for them as specified in the
 181 'Types' section above
 182
 183 [ Rationale: Keeping exact 1:1 correspondence with C conventions is
 184 less important here, as the function argument list can easily be
 185 accessed to find out exactly what the arguments are.  Designators
 186 are primarily a convenience feature ]
 187
 188 * Function return values
 189
 190 The return value is usually the same as for the C binding, except in
 191 error cases: where the C function is defined as returning some
 192 sentinel value and setting "errno" on error, we instead signal an
 193 error of type SYSCALL-ERROR.  The actual error value ("errno") is
 194 stored in this condition and can be accessed with SYSCALL-ERRNO.
 195 [TBA: some interface to strerror, to get the user-readable translation
 196 of the error number]
 197
 198 We do not automatically translate the returned value into "Lispy"
 199 objects - for example, SB-POSIX:OPEN returns a small integer, not a
 200 stream.  Exception: boolean-returning functions (or, more commonly,
 201 macros) do not return a C integer, but instead a lisp boolean [ or
 202 maybe "true"/"false" in CLtS parlance ]; the rationale behind this
 203 exception is that there is nothing that can be meaningfully done with
 204 the boolean except test for truth or falsity -- it cannot be passed
 205 meaningfully to other POSIX functions.
 206
 207 [ Rationale: This is an interface to POSIX, not a high-level interface
 208 that uses POSIX, and many people using it will actually want to mess
 209 with the file descriptors directly.  People needing Lispy interfaces
 210 can implement them atop this - or indeed, use the existing COMMON-LISP
 211 package, which already has many high-level constructs built on top of
 212 the operating system ;-) ]
 213
 214
 215 * Implementation
 216
 217 The initial implementation is in contrib/sb-posix, and being filled
 218 out on an as-needed basis.  Contributions following these style rules
 219 are welcome from anyone who writes them, provided the author is happy
 220 to release the code as Public Domain or MIT-style licence.
 221
 222 See/update the TODO list for current status
 223
 224 ** Designators
 225
 226 See designator.lisp, add a define-designator form
 227
 228 ** Adding functions
 229
 230 The use of DEFINE-CALL macro in interface.lisp should be obvious from
 231 the existing examples, if less so from the macroexpansion
 232
 233
 234
 235
 236
 237 GC issues
 238
 239 buffers that refer to C stuff are probably not movable by GC anyway
 240
 241 a buffer that refers to a Lisp object may have trouble if the Lisp
 242 object is moved
 243
 244