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