run makeindex during PDF generation
[haskell-report.git] / report / lib-cforeign.verb
1 \section{@Foreign.C@}
2 \label{sec:CForeign}
3
4 The module @Foreign.C@ combines the interfaces of all modules providing
5 C-specific marshalling support.  The modules are @Foreign.C.Types@,
6 @Foreign.C.String@, and @Foreign.C.Error@.
7
8 \begin{table}
9   \begin{center}
10     \begin{tabular}{|l|l|l|}
11       \hline
12       C symbol          & Haskell symbol & Constraint on concrete C type\\
13       \hline\hline
14       @HsChar@     & @Char@    
15       & integral type\\
16       \hline
17       @HsInt@      & @Int@
18       & signed integral type, $\geq30$ bit\\
19       \hline
20       @HsInt8@     & @Int8@
21       & signed integral type, 8 bit; @int8_t@ if available\\
22       \hline
23       @HsInt16@    & @Int16@
24       & signed integral type, 16 bit; @int16_t@ if available\\
25       \hline
26       @HsInt32@    & @Int32@
27       & signed integral type, 32 bit; @int32_t@ if available\\
28       \hline
29       @HsInt64@    & @Int64@
30       & signed integral type, 64 bit; @int64_t@ if available\\ 
31       \hline
32       @HsWord8@    & @Word8@
33       & unsigned integral type, 8 bit; @uint8_t@ if available\\
34       \hline
35       @HsWord16@   & @Word16@
36       & unsigned integral type, 16 bit; @uint16_t@ if available\\
37       \hline
38       @HsWord32@   & @Word32@
39       & unsigned integral type, 32 bit; @uint32_t@ if available\\
40       \hline
41       @HsWord64@   & @Word64@
42       & unsigned integral type, 64 bit; @uint64_t@ if available\\
43       \hline
44       @HsFloat@    & @Float@
45       & floating point type\\
46      \hline
47       @HsDouble@   & @Double@
48       & floating point type\\
49      \hline
50       @HsBool@     & @Bool@
51       & @int@\\
52      \hline
53       @HsPtr@      & @Ptr a@
54       & @(void *)@\\
55      \hline
56       @HsFunPtr@   & @FunPtr a@
57       & @(void (*)(void))@\\
58      \hline
59       @HsStablePtr@& @StablePtr a@
60       & @(void *)@\\
61      \hline
62     \end{tabular}
63     \caption{C Interface to Basic Haskell Types}
64     \label{tab:c-haskell-types}
65   \end{center}
66 \end{table}
67 %
68 \begin{table}
69   \begin{center}
70 %    \begin{tabular}{|l|l|l|}
71     \begin{tabular}{|l|l|p{30ex}|}
72       \hline
73       CPP symbol           & Haskell value & Description\\
74       \hline\hline
75       @HS_CHAR_MIN@ & @minBound :: Char@
76       & \\
77       \hline
78       @HS_CHAR_MAX@ & @maxBound :: Char@
79       & \\
80       \hline
81       @HS_INT_MIN@ & @minBound :: Int@
82       & \\
83       \hline
84       @HS_INT_MAX@ & @maxBound :: Int@
85       & \\
86       \hline
87       @HS_INT8_MIN@ & @minBound :: Int8@
88       & \\
89       \hline
90       @HS_INT8_MAX@ & @maxBound :: Int8@
91       & \\
92       \hline
93       @HS_INT16_MIN@ & @minBound :: Int16@
94       & \\
95       \hline
96       @HS_INT16_MAX@ & @maxBound :: Int16@
97       & \\
98       \hline
99       @HS_INT32_MIN@ & @minBound :: Int32@
100       & \\
101       \hline
102       @HS_INT32_MAX@ & @maxBound :: Int32@
103       & \\
104       \hline
105       @HS_INT64_MIN@ & @minBound :: Int64@
106       & \\
107       \hline
108       @HS_INT64_MAX@ & @maxBound :: Int64@
109       & \\
110       \hline
111       @HS_WORD8_MAX@ & @maxBound :: Word8@
112       & \\
113       \hline
114       @HS_WORD16_MAX@ & @maxBound :: Word16@
115       & \\
116       \hline
117       @HS_WORD32_MAX@ & @maxBound :: Word32@
118       & \\
119       \hline
120       @HS_WORD64_MAX@ & @maxBound :: Word64@
121       & \\
122       \hline
123       @HS_FLOAT_RADIX@ & @floatRadix :: Float@
124       & \\
125       \hline
126       @HS_FLOAT_ROUND@ & n/a
127       & rounding style as per~\cite{C99}\\
128       \hline
129       @HS_FLOAT_EPSILON@ & n/a
130       & difference between 1 and the least value greater
131       than 1 as per~\cite{C99}\\
132       \hline
133       @HS_DOUBLE_EPSILON@ & n/a
134       & (as above)\\
135       \hline
136       @HS_FLOAT_DIG@ & n/a
137       & number of decimal digits as per~\cite{C99}\\
138       \hline
139       @HS_DOUBLE_DIG@ & n/a
140       & (as above)\\
141       \hline
142       @HS_FLOAT_MANT_DIG@ & @floatDigits :: Float@
143       & \\
144       \hline
145       @HS_DOUBLE_MANT_DIG@ & @floatDigits :: Double@
146       & \\
147       \hline
148       @HS_FLOAT_MIN@ & n/a
149       & minimum floating point number as per~\cite{C99}\\
150       \hline
151       @HS_DOUBLE_MIN@ & n/a
152       & (as above)\\
153       \hline
154       @HS_FLOAT_MIN_EXP@ & @fst . floatRange :: Float@
155       & \\
156       \hline
157       @HS_DOUBLE_MIN_EXP@ & @fst . floatRange :: Double@
158       & \\
159       \hline
160       @HS_FLOAT_MIN_10_EXP@ & n/a
161       & minimum decimal exponent as per~\cite{C99}\\
162       \hline
163       @HS_DOUBLE_MIN_10_EXP@ & n/a
164       & (as above)\\
165       \hline
166       @HS_FLOAT_MAX@ & n/a
167       & maximum floating point number as per~\cite{C99}\\
168       \hline
169       @HS_DOUBLE_MAX@ & n/a
170       & (as above)\\
171       \hline
172       @HS_FLOAT_MAX_EXP@ & @snd . floatRange :: Float@
173       & \\
174       \hline
175       @HS_DOUBLE_MAX_EXP@ & @snd . floatRange :: Double@
176       & \\
177       \hline
178       @HS_FLOAT_MAX_10_EXP@ & n/a
179       & maximum decimal exponent as per~\cite{C99}\\
180       \hline
181       @HS_DOUBLE_MAX_10_EXP@ & n/a
182       & (as above)\\
183       \hline
184       @HS_BOOL_FALSE@ & False
185       & \\
186       \hline
187       @HS_BOOL_TRUE@ & True
188       & \\
189       \hline
190     \end{tabular}
191     \caption{C Interface to Range and Precision of Basic Types}
192     \label{tab:c-haskell-values}
193   \end{center}
194 \end{table}
195 %
196 Every Haskell system that implements the FFI needs to provide a C header file
197 named @HsFFI.h@ that defines the C symbols listed in
198 Tables~\ref{tab:c-haskell-types} and~\ref{tab:c-haskell-values}.
199 Table~\ref{tab:c-haskell-types} table lists symbols that represent types
200 together with the Haskell type that they represent and any constraints that
201 are placed on the concrete C types that implement these symbols.  When a C
202 type @HsT@ represents a Haskell type @T@, the occurrence of @T@
203 in a foreign function declaration should be matched by @HsT@ in the
204 corresponding C function prototype.  Indeed, where the Haskell system
205 translates Haskell to C code that invokes @foreign@ @import@ed C
206 routines, such prototypes need to be provided and included via the header that
207 can be specified in external entity strings for foreign C functions (cf.\ 
208 Section~\ref{sec:ccall}); otherwise, the system behaviour is undefined.  It is
209 guaranteed that the Haskell value @nullPtr@ is mapped to @(HsPtr) NULL@ in C and @nullFunPtr@ is mapped to @(HsFunPtr) NULL@ and
210 vice versa.
211
212 Table~\ref{tab:c-haskell-values} contains symbols characterising the range and
213 precision of the types from Table~\ref{tab:c-haskell-types}.  Where available,
214 the table states the corresponding Haskell values.  All C symbols, with the
215 exception of @HS_FLOAT_ROUND@ are constants that are suitable for use in
216 @#if@ preprocessing directives.  Note that there is only one rounding
217 style (@HS_FLOAT_ROUND@) and one radix (@HS_FLOAT_RADIX@), as
218 this is all that is supported by ISO C~\cite{C99}.
219
220 Moreover, an implementation that does not support 64 bit integral types on the
221 C side should implement @HsInt64@ and @HsWord64@ as a structure.  In
222 this case, the bounds @HS_INT64_MIN@, @HS_INT64_MAX@, and
223 @HS_WORD64_MAX@ are undefined.
224
225 In addition, to the symbols from Table~\ref{tab:c-haskell-types}
226 and~\ref{tab:c-haskell-values}, the header @HsFFI.h@ must also contain
227 the following prototypes:
228 %
229 \begin{quote}
230 \begin{verbatim}
231 void hs_init     (int *argc, char **argv[]);
232 void hs_exit     (void);
233 void hs_set_argv (int argc, char *argv[]);
234
235 void hs_perform_gc (void);
236
237 void hs_free_stable_ptr (HsStablePtr sp);
238 void hs_free_fun_ptr    (HsFunPtr fp);
239 \end{verbatim}
240 \end{quote}
241 %
242 These routines are useful for mixed language programs, where the main
243 application is implemented in a foreign language that accesses routines
244 implemented in Haskell.  The function @hs_init()@ initialises the
245 Haskell system and provides it with the available command line arguments.
246 Upon return, the arguments solely intended for the Haskell runtime system are
247 removed (i.e., the values that @argc@ and @argv@ point to may have
248 changed).  This function must be called during program startup before any
249 Haskell function is invoked; otherwise, the system behaviour is undefined.
250 Conversely, the Haskell system is deinitialised by a call to
251 @hs_exit()@.  Multiple invocations of @hs_init()@ are permitted,
252 provided that they are followed by an equal number of calls to
253 @hs_exit()@ and that the first call to @hs_exit()@ is after the
254 last call to @hs_init()@.  In addition to nested calls to
255 @hs_init()@, the Haskell system may be de-initialised with
256 @hs_exit()@ and be re-initialised with @hs_init()@ at a later
257 point in time.  This ensures that repeated initialisation due to multiple
258 libraries being implemented in Haskell is covered.
259
260 The Haskell system will ignore the command line arguments passed to the second
261 and any following calls to @hs_init()@.  Moreover, @hs_init()@ may
262 be called with @NULL@ for both @argc@ and @argv@, signalling
263 the absence of command line arguments.
264
265 The function @hs_set_argv()@ sets the values returned by the functions
266 @getProgName@ and @getArgs@ of the module @System@ (Section~\ref{System}).  This function may only be invoked after
267 @hs_init()@.  Moreover, if @hs_set_argv()@ is called at all, this
268 call must precede the first invocation of @getProgName@ and
269 @getArgs@.  Note that the separation of @hs_init()@ and
270 @hs_set_argv()@ is essential in cases where in addition to the Haskell
271 system other libraries that process command line arguments during
272 initialisation are used.
273
274 The function @hs_perform_gc()@ advises the Haskell storage manager to
275 perform a garbage collection, where the storage manager makes an effort to
276 releases all unreachable objects.  This function must not be invoked from C
277 functions that are imported @unsafe@ into Haskell code nor may it be used
278 from a finalizer.
279
280 Finally, @hs_free_stable_ptr()@ and @hs_free_fun_ptr()@ are
281 the C counterparts of the Haskell functions @freeStablePtr@ and
282 @freeHaskellFunPtr@.
283