1.0.23.50: Less magic constants in the MIPS backend.
[sbcl.git] / 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
217 @item flock
218 @include class-sb-posix-flock.texinfo
219
220 @item passwd
221 @include class-sb-posix-passwd.texinfo
222
223 @item stat
224 @include class-sb-posix-stat.texinfo
225
226 @item termios
227 @include class-sb-posix-termios.texinfo
228
229 @item timeval
230 @include class-sb-posix-timeval.texinfo
231 @end itemize
232
233 @node Functions with idiosyncratic bindings
234 @subsection Functions with idiosyncratic bindings
235
236 A few functions in sb-posix don't correspond directly to their C
237 counterparts.
238
239 @itemize
240 @item getcwd
241 @include fun-sb-posix-getcwd.texinfo
242 @item readlink
243 @include fun-sb-posix-readlink.texinfo
244 @item syslog
245 @include fun-sb-posix-syslog.texinfo
246 @end itemize