contrib/sb-posix/sb-posix.texinfo

   1 @node sb-posix
   2 @section sb-posix
   3 @cindex Operating System Interface
   4 @cindex System Calls
   5 @cindex Posix
   6
   7 Sb-posix is the supported interface for calling out to the operating
   8 system.@footnote{The functionality contained in the package
   9 @code{SB-UNIX} is for SBCL internal use only; its contents are likely to
  10 change from version to version.}
  11
  12 The scope of this interface is "operating system calls on a typical
  13 Unixlike platform".  This is section 2 of the Unix manual, plus section
  14 3 calls that are (a) typically found in libc, but (b) not part of the C
  15 standard.  For example, we intend to provide support for
  16 @code{opendir()} and @code{readdir()}, but not for @code{printf()}.
  17 That said, if your favourite system call is not included yet, you are
  18 encouraged to submit a patch to the SBCL mailing list.
  19
  20 Some facilities are omitted where they offer absolutely no additional
  21 use over some portable function, or would be actively dangerous to the
  22 consistency of Lisp.  Not all functions are available on all
  23 platforms.  [TBD: unavailable functions should (a) not exist, or (b)
  24 exist but signal some kind of "not available on this platform" error]
  25
  26 The general intent is for a low-level interface.  There are three
  27 reasons for this: it's easier to write a high-level interface given a
  28 low-level one than vice versa, there are fewer philosophical
  29 disagreements about what it should look like, and the work of
  30 implementing it is easily parallelisable - and in fact, can be
  31 attempted on an as-needed basis by the various people who want it.
  32
  33 @subsection Lisp names for system calls
  34
  35 All symbols are in the @code{SB-POSIX} package.  This package contains a
  36 Lisp function for each supported Unix system call or function, and a
  37 variable or constant for each supported Unix constant.  A symbol name is
  38 derived from the C binding's name, by (a) uppercasing, then (b) removing
  39 leading underscores (@code{#\_}) then replacing remaining underscore
  40 characters with the hyphen (@code{#\-}). The requirement to uppercase is
  41 so that in a standard upcasing reader the user may write
  42 @code{posix:creat} instead of @code{posix:|creat|} as would otherise be
  43 required.
  44
  45 No other changes to "Lispify" symbol names are made, so @code{creat()}
  46 becomes @code{CREAT}, not @code{CREATE}.
  47
  48 The user is encouraged not to @code{(USE-PACKAGE :SB-POSIX)} but instead
  49 to use the @code{SB-POSIX:} prefix on all references, as some of our
  50 symbols have the same name as CL symbols (@code{OPEN}, @code{CLOSE},
  51 @code{SIGNAL} etc).
  52
  53 @quotation
  54 Rationale: We use similar names to the C bindings so that unix manual
  55 pages can be used for documentation.  To avoid name clashes with CL or
  56 other functions, the approaches considered were (a) prefix the names of
  57 clashing symbols with "POSIX-" or similar, (b) prefix @emph{all} symbols with
  58 "POSIX-", (c) use the packaging system to resolve ambiguities.  (a) was
  59 rejected as the set of symbols we may potentially clash with is not
  60 fixed (for example, if new symbols are added to @code{SB-EXT}) so
  61 symbols might have to be renamed over the lifetime of SB-POSIX, which is
  62 not good.  The choice between (b) and (c) was made on the grounds that
  63 @code{POSIX-OPEN} is about as much typing as @code{SB-POSIX:OPEN}
  64 anyway, and symbol munging is, the author feels, slightly tacky, when
  65 there's a package system available to do it more cleanly.
  66 @end quotation
  67
  68 @subsection Types
  69
  70 Generally, marshalling between Lisp and C data types is done using
  71 SBCL's FFI. @xref{Foreign Function Interface}.
  72
  73 Some functions accept objects such as filenames or file
  74 descriptors. In the C binding to POSIX these are represented as
  75 strings and small integers respectively. For the Lisp programmer's
  76 convenience we introduce designators such that CL pathnames or open
  77 streams can be passed to these functions.
  78
  79 @subsubsection File-descriptors
  80
  81 A file-descriptor is a non-negative small integer.
  82
  83 A file-stream is a designator for a file-descriptor: the stream's file
  84 descriptor is extracted.  Note that mixing io operations on a stream
  85 with operations directly on its descriptor may produce unexpected
  86 results if the stream is buffered.
  87
  88 @subsubsection Filenames
  89
  90 A filename is a string.
  91
  92 A pathname is a designator for a filename: the filename is computed
  93 using the same mechanism that SBCL uses to map pathnames to OS filenames
  94 internally.
  95
  96 @subsubsection Type conversion functions
  97
  98 For each of these types there is a function of the same name that
  99 converts any valid designator for the type into an object of said type.
 100
 101 @lisp
 102 (with-open-file (o "/tmp/foo" :direction :output)
 103   (sb-posix:file-descriptor o))
 104 => 4
 105 @end lisp
 106
 107 @subsection Function parameters
 108
 109 The calling convention is modelled after that of CMUCL's @code{UNIX}
 110 package: in particular, it's like the C interface except that:
 111
 112 @enumerate a
 113 @item
 114 Length arguments are omitted or optional where the sensible value
 115 is obvious.  For example, @code{read} would be defined this way:
 116
 117 @lisp
 118 (read fd buffer &optional (length (length buffer))) => bytes-read
 119 @end lisp
 120
 121 @item
 122 Where C simulates "out" parameters using pointers (for instance, in
 123 @code{pipe()} or @code{socketpair()}) these may be optional or omitted
 124 in the Lisp interface: if not provided, appropriate objects will be
 125 allocated and returned (using multiple return values if necessary).
 126
 127 @item
 128 Some functions accept objects such as filenames or file descriptors.
 129 Wherever these are specified as such in the C bindings, the Lisp
 130 interface accepts designators for them as specified in the 'Types'
 131 section above.
 132 @end enumerate
 133
 134 @quotation
 135 Rationale: Keeping exact 1:1 correspondence with C conventions is less
 136 important here, as the function argument list can easily be accessed to
 137 find out exactly what the arguments are.  Designators are primarily a
 138 convenience feature.
 139 @end quotation
 140
 141 @subsection Function return values
 142
 143 The return value is usually the same as for the C binding, except in
 144 error cases: where the C function is defined as returning some sentinel
 145 value and setting @code{errno} on error, we instead signal an error of
 146 type @code{SYSCALL-ERROR}.  The actual error value (@code{errno}) is
 147 stored in this condition and can be accessed with @code{SYSCALL-ERRNO}.
 148 [TBD: some interface to @code{strerror}, to get the user-readable
 149 translation of the error number]
 150
 151 We do not automatically translate the returned value into "Lispy"
 152 objects -- for example, @code{SB-POSIX:OPEN} returns a small integer,
 153 not a stream.  Exception: boolean-returning functions (or, more
 154 commonly, macros) do not return a C integer, but instead a lisp boolean
 155 [ or maybe "true"/"false" in CLtS parlance ]; the rationale behind this
 156 exception is that there is nothing that can be meaningfully done with
 157 the boolean except test for truth or falsity -- it cannot be passed
 158 meaningfully to other POSIX functions.
 159
 160 @quotation
 161 Rationale: This is an interface to POSIX, not a high-level interface
 162 that uses POSIX, and many people using it will actually want to mess
 163 with the file descriptors directly.  People needing Lispy interfaces can
 164 implement them atop this - or indeed, use the existing COMMON-LISP
 165 package, which already has many high-level constructs built on top of
 166 the operating system ;-)
 167 @end quotation
 168