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, supply a true
 114 @code{AS-DIRECTORY} argument to @code{SB-EXT:PARSE-NATIVE-NAMESTRING}.
 115 Likewise, if it is necessary to supply the name of a directory to a
 116 POSIX function in non-directory syntax, supply a true @code{AS-FILE}
 117 argument to @code{SB-EXT:NATIVE-NAMESTRING}.
 118
 119 @node Type conversion functions
 120 @subsubsection Type conversion functions
 121
 122 For each of these types there is a function of the same name that
 123 converts any valid designator for the type into an object of said type.
 124
 125 @lisp
 126 (with-open-file (o "/tmp/foo" :direction :output)
 127   (sb-posix:file-descriptor o))
 128 => 4
 129 @end lisp
 130
 131 @node Function Parameters
 132 @subsection Function Parameters
 133
 134 The calling convention is modelled after that of CMUCL's @code{UNIX}
 135 package: in particular, it's like the C interface except that:
 136
 137 @enumerate a
 138 @item
 139 Length arguments are omitted or optional where the sensible value
 140 is obvious.  For example, @code{read} would be defined this way:
 141
 142 @lisp
 143 (read fd buffer &optional (length (length buffer))) => bytes-read
 144 @end lisp
 145
 146 @item
 147 Where C simulates ``out'' parameters using pointers (for instance, in
 148 @code{pipe()} or @code{socketpair()}) these may be optional or omitted
 149 in the Lisp interface: if not provided, appropriate objects will be
 150 allocated and returned (using multiple return values if necessary).
 151
 152 @item
 153 Some functions accept objects such as filenames or file descriptors.
 154 Wherever these are specified as such in the C bindings, the Lisp
 155 interface accepts designators for them as specified in the 'Types'
 156 section above.
 157
 158 @item
 159 A few functions have been included in sb-posix that do not correspond
 160 exactly with their C counterparts.  These are described in
 161 @xref{Functions with idiosyncratic bindings}.
 162
 163 @end enumerate
 164
 165 @node Function Return Values
 166 @subsection  Function Return Values
 167
 168 The return value is usually the same as for the C binding, except in
 169 error cases: where the C function is defined as returning some sentinel
 170 value and setting @code{errno} on error, we instead signal an error of
 171 type @code{SYSCALL-ERROR}.  The actual error value (@code{errno}) is
 172 stored in this condition and can be accessed with @code{SYSCALL-ERRNO}.
 173
 174 We do not automatically translate the returned value into ``Lispy''
 175 objects -- for example, @code{SB-POSIX:OPEN} returns a small integer,
 176 not a stream.  Exception: boolean-returning functions (or, more
 177 commonly, macros) do not return a C integer, but instead a Lisp
 178 boolean.
 179
 180 @node Lisp objects and C structures
 181 @subsection Lisp objects and C structures
 182
 183 Sb-posix provides various Lisp object types to stand in for C
 184 structures in the POSIX library.  Lisp bindings to C functions that
 185 accept, manipulate, or return C structures accept, manipulate, or
 186 return instances of these Lisp types instead of instances of alien
 187 types.
 188
 189 The names of the Lisp types are chosen according to the general rules
 190 described above.  For example Lisp objects of type @code{STAT} stand
 191 in for C structures of type @code{struct stat}.
 192
 193 Accessors are provided for each standard field in the structure. These
 194 are named @code{@var{structure-name}-@var{field-name}} where the two
 195 components are chosen according to the general name conversion rules,
 196 with the exception that in cases where all fields in a given structure
 197 have a common prefix, that prefix is omitted. For example,
 198 @code{stat.st_dev} in C becomes @code{STAT-DEV} in Lisp.
 199
 200 @c This was in the README, but it proves to be false about sb-posix.
 201 @ignore
 202 For each Lisp object type corresponding to a C structure type, there
 203 is a @code{make-@var{structure-name}} function that takes keyword
 204 arguments with names deriving from each documented field name
 205 according to the name conversion rules for accessors.
 206 @end ignore
 207
 208
 209 Because sb-posix might not support all semi-standard or
 210 implementation-dependent members of all structure types on your system
 211 (patches welcome), here is an enumeration of all supported Lisp
 212 objects corresponding to supported POSIX structures, and the supported
 213 slots for those structures.
 214
 215 @itemize
 216 @item passwd
 217 @include class-sb-posix-passwd.texinfo
 218
 219 @item stat
 220 @include class-sb-posix-stat.texinfo
 221
 222 @item termios
 223 @include class-sb-posix-termios.texinfo
 224
 225 @item timeval
 226 @include class-sb-posix-timeval.texinfo
 227 @end itemize
 228
 229 @node Functions with idiosyncratic bindings
 230 @subsection Functions with idiosyncratic bindings
 231
 232 A few functions in sb-posix don't correspond directly to their C
 233 counterparts.
 234
 235 @itemize
 236 @item getcwd
 237 @include fun-sb-posix-getcwd.texinfo
 238 @item readlink
 239 @include fun-sb-posix-readlink.texinfo
 240 @item syslog
 241 @include fun-sb-posix-syslog.texinfo
 242 @end itemize