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 * Lisp objects and C structures::
  29 * Function Parameters::
  30 * Function Return Values::
  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 * Type conversion functions::
  74 @end menu
  75
  76 @node File-descriptors
  77 @subsubsection File-descriptors
  78
  79 A file-descriptor is a non-negative small integer.
  80
  81 A file-stream is a designator for a file-descriptor: the stream's file
  82 descriptor is extracted.  Note that mixing I/O operations on a stream
  83 with operations directly on its descriptor may produce unexpected
  84 results if the stream is buffered.
  85
  86 @code{SB-EXT:MAKE-FD-STREAM} can be used to construct a stream
  87 associated with a file descriptor.
  88
  89 @node Filenames
  90 @subsubsection Filenames
  91
  92 A filename is a string.
  93
  94 A pathname is a designator for a filename: the filename is computed
  95 using the same mechanism that SBCL uses to map pathnames to OS filenames
  96 internally.
  97
  98 Note that filename syntax is distinct from namestring syntax, and that
  99 @code{SB-EXT:PARSE-NATIVE-NAMESTRING} may be used to construct
 100 Lisp pathnames that denote POSIX filenames returned by system calls.
 101 @xref{Function sb-ext:parse-native-namestring}.  Additionally, notice
 102 that POSIX filename syntax does not distinguish the names of files
 103 from the names of directories.  Consequently, in order to parse the
 104 name of a directory in POSIX filename syntax into a pathname
 105 @code{defaults} for which
 106
 107 @lisp
 108 (merge-pathnames (make-pathname :name "FOO" :case :common)
 109                  defaults)
 110 @end lisp
 111
 112 @noindent
 113 returns a pathname that denotes a file in the directory, it's necessary
 114 to append a forward slash to the POSIX filename.  Otherwise, the last
 115 directory name will be parsed as a filename.
 116
 117 @node Type conversion functions
 118 @subsubsection Type conversion functions
 119
 120 For each of these types there is a function of the same name that
 121 converts any valid designator for the type into an object of said type.
 122
 123 @lisp
 124 (with-open-file (o "/tmp/foo" :direction :output)
 125   (sb-posix:file-descriptor o))
 126 => 4
 127 @end lisp
 128
 129 @node Function Parameters
 130 @subsection Function Parameters
 131
 132 The calling convention is modelled after that of CMUCL's @code{UNIX}
 133 package: in particular, it's like the C interface except that:
 134
 135 @enumerate a
 136 @item
 137 Length arguments are omitted or optional where the sensible value
 138 is obvious.  For example, @code{read} would be defined this way:
 139
 140 @lisp
 141 (read fd buffer &optional (length (length buffer))) => bytes-read
 142 @end lisp
 143
 144 @item
 145 Where C simulates ``out'' parameters using pointers (for instance, in
 146 @code{pipe()} or @code{socketpair()}) these may be optional or omitted
 147 in the Lisp interface: if not provided, appropriate objects will be
 148 allocated and returned (using multiple return values if necessary).
 149
 150 @item
 151 Some functions accept objects such as filenames or file descriptors.
 152 Wherever these are specified as such in the C bindings, the Lisp
 153 interface accepts designators for them as specified in the 'Types'
 154 section above.
 155
 156 @item
 157 A few functions have been included in sb-posix that do not correspond
 158 exactly with their C counterparts.  These are described in
 159 @xref{Functions with idiosyncratic bindings}.
 160
 161 @end enumerate
 162
 163 @node Function Return Values
 164 @subsection  Function Return Values
 165
 166 The return value is usually the same as for the C binding, except in
 167 error cases: where the C function is defined as returning some sentinel
 168 value and setting @code{errno} on error, we instead signal an error of
 169 type @code{SYSCALL-ERROR}.  The actual error value (@code{errno}) is
 170 stored in this condition and can be accessed with @code{SYSCALL-ERRNO}.
 171
 172 We do not automatically translate the returned value into ``Lispy''
 173 objects -- for example, @code{SB-POSIX:OPEN} returns a small integer,
 174 not a stream.  Exception: boolean-returning functions (or, more
 175 commonly, macros) do not return a C integer, but instead a Lisp
 176 boolean.
 177
 178 @node Lisp objects and C structures
 179 @subsection Lisp objects and C structures
 180
 181 Sb-posix provides various Lisp object types to stand in for C
 182 structures in the POSIX library.  Lisp bindings to C functions that
 183 accept, manipulate, or return C structures accept, manipulate, or
 184 return instances of these Lisp types instead of instances of alien
 185 types.
 186
 187 The names of the Lisp types are chosen according to the general rules
 188 described above.  For example Lisp objects of type @code{STAT} stand
 189 in for C structures of type @code{struct stat}.
 190
 191 Accessors are provided for each standard field in the structure. These
 192 are named @code{@var{structure-name}-@var{field-name}} where the two
 193 components are chosen according to the general name conversion rules,
 194 with the exception that in cases where all fields in a given structure
 195 have a common prefix, that prefix is omitted. For example,
 196 @code{stat.st_dev} in C becomes @code{STAT-DEV} in Lisp.
 197
 198 @c This was in the README, but it proves to be false about sb-posix.
 199 @ignore
 200 For each Lisp object type corresponding to a C structure type, there
 201 is a @code{make-@var{structure-name}} function that takes keyword
 202 arguments with names deriving from each documented field name
 203 according to the name conversion rules for accessors.
 204 @end ignore
 205
 206
 207 Because sb-posix might not support all semi-standard or
 208 implementation-dependent members of all structure types on your system
 209 (patches welcome), here is an enumeration of all supported Lisp
 210 objects corresponding to supported POSIX structures, and the supported
 211 slots for those structures.
 212
 213 @itemize
 214 @item passwd
 215 @include class-sb-posix-passwd.texinfo
 216
 217 @item stat
 218 @include class-sb-posix-stat.texinfo
 219
 220 @item termios
 221 @include class-sb-posix-termios.texinfo
 222
 223 @item timeval
 224 @include class-sb-posix-timeval.texinfo
 225 @end itemize
 226
 227 @node Functions with idiosyncratic bindings
 228 @subsection Functions with idiosyncratic bindings
 229
 230 A few functions in sb-posix don't correspond directly to their C
 231 counterparts.
 232
 233 @itemize
 234 @item getcwd
 235 @include fun-sb-posix-getcwd.texinfo
 236 @item readlink
 237 @include fun-sb-posix-readlink.texinfo
 238 @item syslog
 239 @include fun-sb-posix-syslog.texinfo
 240 @end itemize