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.
  24
  25 @menu
  26 * Lisp names for C names::
  27 * Types::
  28 * Function Parameters::
  29 * Function Return Values::
  30 * Lisp objects and C structures::
  31 * Functions with idiosyncratic bindings::
  32 @end menu
  33
  34
  35 @node Lisp names for C names
  36 @subsection  Lisp names for C names
  37
  38 All symbols are in the @code{SB-POSIX} package.  This package contains a
  39 Lisp function for each supported Unix system call or function, a
  40 variable or constant for each supported Unix constant, an object type
  41 for each supported Unix structure type, and a slot name for each
  42 supported Unix structure member.  A symbol name is derived from the C
  43 binding's name, by (a) uppercasing, then (b) removing leading
  44 underscores (@code{#\_}) then replacing remaining underscore characters
  45 with the hyphen (@code{#\-}). The requirement to uppercase is so that in
  46 a standard upcasing reader the user may write @code{sb-posix:creat}
  47 instead of @code{sb-posix:|creat|} as would otherise be required.
  48
  49 No other changes to ``Lispify'' symbol names are made, so @code{creat()}
  50 becomes @code{CREAT}, not @code{CREATE}.
  51
  52 The user is encouraged not to @code{(USE-PACKAGE :SB-POSIX)} but instead
  53 to use the @code{SB-POSIX:} prefix on all references, as some of the
  54 symbols symbols contained in the SB-POSIX package have the same name as
  55 CL symbols (@code{OPEN}, @code{CLOSE}, @code{SIGNAL} etc).
  56
  57 @node Types
  58 @subsection Types
  59
  60 Generally, marshalling between Lisp and C data types is done using
  61 SBCL's FFI. @xref{Foreign Function Interface}.
  62
  63 Some functions accept objects such as filenames or file descriptors.  In
  64 the C binding to POSIX these are represented as strings and small
  65 integers respectively. For the Lisp programmer's convenience we
  66 introduce designators such that CL pathnames or open streams can be
  67 passed to these functions.  For example, @code{rename} accepts both
  68 pathnames and strings as its arguments.
  69
  70 @menu
  71 * File-descriptors::
  72 * Filenames::
  73 @end menu
  74
  75 @node File-descriptors
  76 @subsubsection File-descriptors
  77
  78 @include type-sb-posix-file-descriptor.texinfo
  79 @include type-sb-posix-file-descriptor-designator.texinfo
  80 @include fun-sb-posix-file-descriptor.texinfo
  81
  82 @node Filenames
  83 @subsubsection Filenames
  84
  85 @include type-sb-posix-filename.texinfo
  86 @include type-sb-posix-filename-designator.texinfo
  87 @include fun-sb-posix-filename.texinfo
  88
  89 @node Function Parameters
  90 @subsection Function Parameters
  91
  92 The calling convention is modelled after that of CMUCL's @code{UNIX}
  93 package: in particular, it's like the C interface except that:
  94
  95 @enumerate a
  96 @item
  97 Length arguments are omitted or optional where the sensible value
  98 is obvious.  For example, @code{read} would be defined this way:
  99
 100 @lisp
 101 (read fd buffer &optional (length (length buffer))) => bytes-read
 102 @end lisp
 103
 104 @item
 105 Where C simulates ``out'' parameters using pointers (for instance, in
 106 @code{pipe()} or @code{socketpair()}) these may be optional or omitted
 107 in the Lisp interface: if not provided, appropriate objects will be
 108 allocated and returned (using multiple return values if necessary).
 109
 110 @item
 111 Some functions accept objects such as filenames or file descriptors.
 112 Wherever these are specified as such in the C bindings, the Lisp
 113 interface accepts designators for them as specified in the 'Types'
 114 section above.
 115
 116 @item
 117 A few functions have been included in sb-posix that do not correspond
 118 exactly with their C counterparts.  These are described in
 119 @xref{Functions with idiosyncratic bindings}.
 120
 121 @end enumerate
 122
 123 @node Function Return Values
 124 @subsection  Function Return Values
 125
 126 The return value is usually the same as for the C binding, except in
 127 error cases: where the C function is defined as returning some sentinel
 128 value and setting @code{errno} on error, we instead signal an error of
 129 type @code{SYSCALL-ERROR}.  The actual error value (@code{errno}) is
 130 stored in this condition and can be accessed with @code{SYSCALL-ERRNO}.
 131
 132 We do not automatically translate the returned value into ``Lispy''
 133 objects -- for example, @code{SB-POSIX:OPEN} returns a small integer,
 134 not a stream.  Exception: boolean-returning functions (or, more
 135 commonly, macros) do not return a C integer, but instead a Lisp
 136 boolean.
 137
 138 @node Lisp objects and C structures
 139 @subsection Lisp objects and C structures
 140
 141 Sb-posix provides various Lisp object types to stand in for C
 142 structures in the POSIX library.  Lisp bindings to C functions that
 143 accept, manipulate, or return C structures accept, manipulate, or
 144 return instances of these Lisp types instead of instances of alien
 145 types.
 146
 147 The names of the Lisp types are chosen according to the general rules
 148 described above.  For example Lisp objects of type @code{STAT} stand
 149 in for C structures of type @code{struct stat}.
 150
 151 Accessors are provided for each standard field in the structure. These
 152 are named @code{@var{structure-name}-@var{field-name}} where the two
 153 components are chosen according to the general name conversion rules,
 154 with the exception that in cases where all fields in a given structure
 155 have a common prefix, that prefix is omitted. For example,
 156 @code{stat.st_dev} in C becomes @code{STAT-DEV} in Lisp.
 157
 158 @c This was in the README, but it proves to be false about sb-posix.
 159 @ignore
 160 For each Lisp object type corresponding to a C structure type, there
 161 is a @code{make-@var{structure-name}} function that takes keyword
 162 arguments with names deriving from each documented field name
 163 according to the name conversion rules for accessors.
 164 @end ignore
 165
 166
 167 Because sb-posix might not support all semi-standard or
 168 implementation-dependent members of all structure types on your system
 169 (patches welcome), here is an enumeration of all supported Lisp
 170 objects corresponding to supported POSIX structures, and the supported
 171 slots for those structures.
 172
 173 @itemize
 174
 175 @item flock
 176 @include class-sb-posix-flock.texinfo
 177
 178 @item passwd
 179 @include class-sb-posix-passwd.texinfo
 180
 181 @item stat
 182 @include class-sb-posix-stat.texinfo
 183
 184 @item termios
 185 @include class-sb-posix-termios.texinfo
 186
 187 @item timeval
 188 @include class-sb-posix-timeval.texinfo
 189 @end itemize
 190
 191 @node Functions with idiosyncratic bindings
 192 @subsection Functions with idiosyncratic bindings
 193
 194 A few functions in sb-posix don't correspond directly to their C
 195 counterparts.
 196
 197 @itemize
 198 @item getcwd
 199 @include fun-sb-posix-getcwd.texinfo
 200 @item readlink
 201 @include fun-sb-posix-readlink.texinfo
 202 @item syslog
 203 @include fun-sb-posix-syslog.texinfo
 204 @end itemize