3 @cindex Operating System Interface
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.}
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.
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
26 * Lisp names for C names::
28 * Lisp objects and C structures::
29 * Function Parameters::
30 * Function Return Values::
31 * Functions with idiosyncratic bindings::
35 @node Lisp names for C names
36 @subsection Lisp names for C names
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.
49 No other changes to ``Lispify'' symbol names are made, so @code{creat()}
50 becomes @code{CREAT}, not @code{CREATE}.
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).
60 Generally, marshalling between Lisp and C data types is done using
61 SBCL's FFI. @xref{Foreign Function Interface}.
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.
73 * Type conversion functions::
76 @node File-descriptors
77 @subsubsection File-descriptors
79 A file-descriptor is a non-negative small integer.
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.
86 @code{SB-EXT:MAKE-FD-STREAM} can be used to construct a stream
87 associated with a file descriptor.
90 @subsubsection Filenames
92 A filename is a string.
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
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
108 (merge-pathnames (make-pathname :name "FOO" :case :common)
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.
117 @node Type conversion functions
118 @subsubsection Type conversion functions
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.
124 (with-open-file (o "/tmp/foo" :direction :output)
125 (sb-posix:file-descriptor o))
129 @node Function Parameters
130 @subsection Function Parameters
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:
137 Length arguments are omitted or optional where the sensible value
138 is obvious. For example, @code{read} would be defined this way:
141 (read fd buffer &optional (length (length buffer))) => bytes-read
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).
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'
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}.
163 @node Function Return Values
164 @subsection Function Return Values
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}.
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
178 @node Lisp objects and C structures
179 @subsection Lisp objects and C structures
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
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}.
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.
198 @c This was in the README, but it proves to be false about sb-posix.
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.
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.
215 @include class-sb-posix-passwd.texinfo
218 @include class-sb-posix-stat.texinfo
221 @include class-sb-posix-termios.texinfo
224 @include class-sb-posix-timeval.texinfo
227 @node Functions with idiosyncratic bindings
228 @subsection Functions with idiosyncratic bindings
230 A few functions in sb-posix don't correspond directly to their C
235 @include fun-sb-posix-getcwd.texinfo
237 @include fun-sb-posix-readlink.texinfo
239 @include fun-sb-posix-syslog.texinfo