RC 9:
[haskell-report.git] / ffi / ffi.tex
1 % The Haskell 98 Foreign Function Interface
2 % [An Addendum to the Definition of Haskell 98]
3 %
4 % Editor: Manuel M T Chakravarty
5 %
6 % Copyright [2002..2003] Manuel M T Chakravarty
7 %
8 % The authors intend this Report to belong to the entire Haskell community, and
9 % so we grant permission to copy and distribute it for any purpose, provided
10 % that it is reproduced in its entirety, including this Notice. Modified
11 % versions of this Report may also be copied and distributed for any purpose,
12 % provided that the modified version is clearly presented as such, and that it
13 % does not claim to be a definition of the Haskell 98 Foreign Function
14 % Interface.
15
16 % Changes since RC8:
17 % * 5.8: `MarshallAlloc.reallocBytes' is no longer permitted on memory
18 % allocated with `alloca' or `allocaBytes'.
19 % * 6.1: Deinitialisation of the RTS via `hs_exit()' followed by
20 % (re)initialisation with `hs_init()' must be supported.
21 %
22 % Changes since RC7:
23 % * Clarified the lexis of C identifiers and C header file names
24 % * In `ForeignPtr', added `mallocForeignPtrArray' and `mallocForeignPtrArray0'
25 % * Clarified spec of allocations functions adding constraints taken from the
26 % corresponding C routines
27 % * `mallocBytes' and `allocaBytes' must align memory sufficiently for any
28 % basic foreign type that fits into the allocated block
29 % * Removed typos in the description of the module `ForeignPtr'
30 % * Added Peter Gammie to the list of acknowledged people
31 % * `addForeignPtrFinalizer' guarantees that finalizers for a single foreign
32 % pointer are executed in the opposite order as they were added.
33 % * `Storable': Require that the size is divisible by the alignment
34 % * Added Ross Paterson to the list of acknowledged people
35 % * Added hs_free_fun_ptr() and hs_free_stable_ptr()
36 % * Changed order of arguments of `mkIOError' and `annotateIOError' to match
37 % with the current implementation in GHC's FFI libraries.
38 %
39 % Changes since RC6:
40 % * Fixed typos
41 %
42 % Changes since RC5:
43 % * Author list: changed Alastair Reid's institution
44 % * 1.4: Clarified the wording
45 % * 4.1: Explicitly stated that access to pre-processor symbols is not
46 % provided by the FFI
47 % * 4.1.1: Removed [lib] from impent syntax and discussion
48 % * 4.1.3: Added parentheses round FunPtr ft to make it easier to
49 % understand a tolerably complex type.
50 % * 4.1.4: Removed all mention of library objects; clarified that header files
51 % do not impact the semantics of foreign calls, but may be required
52 % for correct code generation by some systems
53 % * 5.2: Clarified that all operations in Bits are member functions of the
54 % type class. Reverse the meaning of the sign of the second argument
55 % for `rotate' and `shift' (this makes it the same as GHC used all
56 % the time). `bitSize' on `Integer' etc is now undefined.
57 % * 5.5: Finalisers must be external functions to facilitate the
58 % implementation on Haskell systems that do not support pre-emptive
59 % concurrency.
60 % Added mallocForeignPtr and mallocForeignPtrBytes.
61 % * 6: Specified that HsBool==int in table2
62 % Relabelled column 1 in table 3 (C symbol -> CPP symbol)
63 % Replaced 0 and 1 with HS_BOOL_FALSE/TRUE
64 % * 6.1: Clarified that nullPtr (nullFunPtr) coincides with (HsPtr) NULL and
65 % (HsFunPtr) NULL, respectively.
66 % Allowing multiple calls to hs_init() and clarified the constraints
67 % on the relative timing between hs_set_argv() and
68 % getProgName/getArgs.
69 % Added hs_perform_gc().
70 %
71 % Changes since RC4:
72 % * 5.6: Clarified documentation of `StablePtr's (RC 5)
73 %
74 % Changes between RC2 and RC4:
75 %
76 % * 5.8: Clarified documentation for `MarshalAlloc.free'.
77 % * 5.8: Added `MarshalAlloc.realloc'.
78 % * 3: Added the new safety level `threadsafe' with an explanation at the end
79 % of 3.3.
80 % * 3: Replaced the nontermional `entity' by `impent' and `expent' to
81 % distinguish between import and export entities (as they are defined
82 % differently in later sections).
83 % * 3.2: Clarified the description of foreign types; so far, `IO ()' was
84 % strictly speaking not included as a valid return type. Currently,
85 % functions of type `a -> ()' are included. Do we want this? Their use
86 % might not be portable if they include side effects.
87 % * 4.1.5: New section discussing the traps & pitfalls of type promotion with
88 % C bindings.
89
90 % TODO:
91 % * Implement HTMLization. (Malcolm suggests using
92 % <http://pauillac.inria.fr/~maranget/hevea/>)
93
94 % TODO after Version 1.0:
95 %
96 % * Review suggestions by Antony Courtney <antony@apocalypse.org> re FFI
97 % support for Java.
98
99
100 \documentclass[a4paper,twoside]{article}
101
102 \usepackage{a4wide}
103 \usepackage{grammar} % Get it from
104 % http://www.cse.unsw.edu.au/~chak/haskell/grammar.sty
105 \usepackage{version}
106 \usepackage{url}
107 \usepackage[fleqn]{amsmath}
108
109
110 % version control
111 %
112 %\includeversion{DRAFT}
113 \excludeversion{DRAFT}
114 \excludeversion{FUTURE} % material for future extensions
115
116 %\def\Version{\relax}
117 \def\Version{\\(Release Candidate 9)}
118 \begin{DRAFT}%
119 {
120 \gdef\Version{%
121 \\
122 \textbf{--- DRAFT ---}\\[1ex]
123 \ttfamily\scriptsize
124 $\relax$Id: ffi.tex,v 1.42 2003/05/21 12:19:17 chak Exp $\relax$%
125 \ignorespaces}
126 }
127 \end{DRAFT}
128
129 % setting of code
130 %
131 \newcommand{\code}[1]{\texttt{#1}} % inline code fragment
132 \makeatletter
133 \newenvironment{codedesc}{% % description of code pieces
134 \list{}{\labelwidth\z@
135 \let\makelabel\codedesclabel}
136 }{%
137 \endlist
138 }
139 \newcommand*{\codedesclabel}[1]{%
140 \hspace{-\leftmargin}
141 \parbox[b]{\labelwidth}{\makebox[0pt][l]{\code{#1}}\\}\hfil\relax
142 }
143 \makeatother
144 \newcommand{\combineitems}{\vspace*{-\itemsep}\vspace*{-\parsep}\vspace*{-1em}}
145 \newcommand{\us}{\char"5F}
146
147 % general
148 %
149 \newcommand{\clearemptydoublepage}{%
150 \newpage{\pagestyle{empty}\cleardoublepage}}
151
152
153 \begin{document}
154 \pagestyle{headings}
155
156 \title{%
157 The Haskell 98 Foreign Function Interface 1.0\\
158 An Addendum to the Haskell 98 Report%
159 \Version}
160 \author{
161 Manuel Chakravarty [editor], University of New South Wales\\
162 Sigbjorn Finne, Galois Connections, Inc.\\
163 Fergus Henderson, University of Melbourne\\
164 Marcin Kowalczyk, Warsaw University\\
165 Daan Leijen, University of Utrecht\\
166 Simon Marlow, Microsoft Research, Cambridge\\
167 Erik Meijer, Microsoft Corporation\\
168 Sven Panne, BetaResearch GmbH\\
169 Simon Peyton Jones, Microsoft Research, Cambridge\\
170 Alastair Reid, Reid Consulting (UK) Ltd.\\
171 Malcolm Wallace, University of York\\
172 Michael Weber, University of Aachen
173 }
174 \date{}
175 \maketitle
176 \par\vfill
177 \noindent
178 Copyright (c) [2002..2003] Manuel M. T. Chakravarty
179 \par\noindent
180 \emph{The authors intend this Report to belong to the entire Haskell
181 community, and so we grant permission to copy and distribute it for any
182 purpose, provided that it is reproduced in its entirety, including this
183 Notice. Modified versions of this Report may also be copied and distributed
184 for any purpose, provided that the modified version is clearly presented as
185 such, and that it does not claim to be a definition of the Haskell 98
186 Foreign Function Interface.}
187 \par\bigskip\noindent
188 The master version of the Haskell FFI Report is at \url{haskell.org}. Any
189 corrections or changes in the report are found there.
190 \thispagestyle{empty}
191
192
193 \clearemptydoublepage
194 \pagenumbering{roman}
195 \tableofcontents
196
197 \clearemptydoublepage
198 \section*{Preface}
199
200 The definition of Haskell 98~\cite{haskell98}, while being comprehensive with
201 respect to the functional core language, does lack a range of features of more
202 operational flavour, such as a foreign language interface, concurrency
203 support, and fully fledged exception handling. As these features are of
204 central importance to many real world applications of the language, there is a
205 danger that different implementations become de facto incompatible for such
206 applications due to system-specific extensions of the core language. The
207 present FFI specification is aimed at reducing this risk by defining a simple,
208 yet comprehensive extension to Haskell 98 for the purpose of interfacing to
209 program components implemented in a language other than Haskell.
210
211 The goal behind this foreign function interface (FFI) specification is
212 twofold: It enables (1) to describe in Haskell the interface to foreign
213 functionality and (2) to use from foreign code Haskell routines. More
214 precisely, its aim is to support the implementation of programs in a mixture
215 of Haskell and other languages such that the source code is portable across
216 different implementations of Haskell and non-Haskell systems as well as
217 independent of the architecture and operating system.
218
219 The design as presented in this report builds on experiences with a number of
220 foreign function interfaces that, over time, have been provided by the major
221 Haskell implementations. Central in the final design was the goal to be
222 comprehensive while being simple and minimising changes with respect to
223 Haskell 98; the latter includes to avoid pollution of the name space with new
224 keywords. Consequently, as much as possible of the FFI functionality is
225 realised in the form of libraries. Simplicity generally overruled maximum
226 convenience for the programmer as a design goal. Thus, support for more
227 convenient interface specifications is the domain of system-independent tools
228 that generate code following the present specification.
229
230 \subsection*{Acknowledgements}
231
232 We heartly thank the kind people who assisted us with their comments and
233 suggestions on the \code{ffi@haskell.org} mailing list as well as all the
234 users of previous versions of the FFI who helped to shape the development by
235 their feedback. We thank Olaf Chitil, Peter Gammie, Wolfram Kahl, Martin D.
236 Kealey, Ian Lynagh, Ross Paterson, and George Russell for errata to previous
237 versions of this report.
238
239
240 \clearemptydoublepage
241 \pagenumbering{arabic}
242 \section{Introduction}
243
244 The extension of Haskell 98 defined in this report facilitates the use of
245 non-Haskell code from Haskell and vice versa in a portable manner. Intrusion
246 into Haskell 98 has been kept to a minimum and the defined facilities have
247 been extensively tested with large libraries.
248
249 The present Version 1.0 of the FFI report does only fully specify the
250 interaction between Haskell code with code that follows the C calling
251 convention. However, the design of the FFI is such that it enables the
252 modular extension of the present definition to include the calling conventions
253 of other programming languages, such as C++ and Java. A precise definition of
254 the support for those languages is expected to be included in later versions
255 of this report.
256
257 \subsection{Embedding Into Haskell 98}
258
259 The present report is to be regarded as an addendum to the Haskell 98
260 Report~\cite{haskell98}. As such, syntactic and semantic definitions refer to
261 names and definitions in the Haskell 98 Report where appropriate without
262 further explanation. Care has been taken to invalidate as few as possible
263 legal Haskell 98 programs in the process of adding FFI support. In
264 particular, only a single addition to the set of reserved identifiers, namely
265 \code{foreign}, has been made.
266
267 Moreover, it is expected that the present FFI specification will be considered
268 for inclusion into future revisions of the Haskell standard.
269
270 \subsection{Language-Specific FFI Support}
271
272 The core of the present specification is independent of the foreign language
273 that is used in conjunction with Haskell. However, there are two areas where
274 FFI specifications must become language specific: (1) the specification of
275 external names and (2) the marshalling of the basic types of a foreign
276 language. As an example of the former, consider that in C~\cite{C} a simple
277 identifier is sufficient to identify an object, while
278 Java~\cite{gosling-etal:Java}, in general, requires a qualified name in
279 conjunction with argument and result types to resolve possible overloading.
280 Regarding the second point, consider that many languages do not specify the
281 exact representation of some basic types. For example the type \code{int} in
282 C may be 16, 32, or 64 bits wide. Similarly, the Haskell report guarantees
283 only that \code{Int} covers at least the range \([-2^{29}, 2^{29} - 1]\). As
284 a consequence, to reliably represent values of C's \code{int} in Haskell, we
285 have to introduce a new type \code{CInt}, which is guaranteed to match the
286 representation of \code{int}.
287
288 The specification of external names, dependent on a calling convention, is
289 described in Section~\ref{sec:extent}, whereas the marshalling of the basic
290 types in dependence on a foreign language is described in
291 Section~\ref{sec:marshalling}.
292
293 \subsection{Contexts}
294
295 For a given Haskell system, we define the \emph{Haskell context} to be the
296 execution context of the abstract machine on which the Haskell system is
297 based. This includes the heap, stacks, and the registers of the abstract
298 machine and their mapping onto a concrete architecture. We call any other
299 execution context an \emph{external context.} Generally, we cannot assume any
300 compatibility between the data formats and calling conventions between the
301 Haskell context and a given external context, except where the Haskell 98
302 report explicitly prescribes a specific data format.
303
304 The principal goal of a foreign function interface is to provide a
305 programmable interface between the Haskell context and external contexts. As
306 a result Haskell threads can access data in external contexts and invoke
307 functions that are executed in an external context as well as vice versa. In
308 the rest of this report, external contexts are usually identified by a calling
309 convention.
310
311 \subsection{Cross Language Type Consistency}
312
313 Given that many external languages support static types, the question arises
314 whether the consistency of Haskell types with the types of the external
315 language can be enforced for foreign functions. Unfortunately, this is, in
316 general, not possible without a significant investment on the part of the
317 implementor of the Haskell system (i.e., without implementing a dedicated type
318 checker). For example, in the case of the C calling convention, the only
319 other approach would be to generate a C prototype from the Haskell type and
320 leave it to the C compiler to match this prototype with the prototype that is
321 specified in a C header file for the imported function. However, the Haskell
322 type is lacking some information that would be required to pursue this route.
323 In particular, the Haskell type does not contain any information as to when
324 \code{const} modifiers have to be emitted.
325
326 As a consequence, this report does not require the Haskell system to check
327 consistency with foreign types. Nevertheless, Haskell systems are encouraged
328 to provide any cross language consistency checks that can be implemented with
329 reasonable effort.
330
331
332 \newpage
333 \section{Lexical Structure}
334
335 In the following, all formal grammatical definitions are based on the same
336 notation as that defined in the Haskell 98
337 Report~\cite[Section~2.1]{haskell98} and we make free use of all nonterminals
338 defined in the Haskell 98 Report. The only addition to the lexical structure
339 of Haskell 98~\cite[Section~2]{haskell98} is a single new reserved identifier
340 (namely, \code{foreign}) and a set of special identifiers. The latter have a
341 special meaning only within foreign declarations, but may be used as ordinary
342 identifiers elsewhere.
343
344 The following productions are added:
345 %
346 \begin{grammar}
347 \grule{reservedid}{%
348 foreign}
349 \grule{specialid}{%
350 export \galt\ import \galt\ safe \galt\ threadsafe \galt\ unsafe}
351 \gor{%
352 ccall \galt\ cplusplus \galt\ dotnet \galt\ jvm \galt\ stdcall}
353 \gor{%
354 \gverbal{system-specific calling conventions}}
355 \end{grammar}
356 %
357 The special identifiers \code{ccall}, \code{cplusplus}, \code{dotnet},
358 \code{jvm}, and \code{stdcall} are defined to denote calling conventions.
359 However, a concrete implementation of the FFI is free to support additional,
360 system-specific calling conventions whose name is not explicitly listed here.
361
362 To refer to objects of an external C context, we introduce the following
363 phrases:
364 %
365 \begin{grammar}
366 \grule[C header filename]{chname}{%
367 \grepeat{\gnterm{chchar}} .\ h}
368 \grule[C identifier]{cid}{%
369 \gnterm{letter} \grepeat{\gnterm{letter} \galt\ \gnterm{ascDigit}}}
370 \grule{chchar}{%
371 \gnterm{letter} \galt\ \gnterm{ascSymbol}\gminus{\&}}
372 \grule{letter}{%
373 \gnterm{ascSmall} \galt\ \gnterm{ascLarge} \galt\ \_}
374 \end{grammar}
375 %
376 The range of lexemes that are admissible for \gnterm{chname} is a subset of
377 those permitted as arguments to the \code{\#{}include} directive in C. In
378 particular, a file name \gnterm{chname} must end in the suffix \code{.h}. The
379 lexemes produced by \gnterm{cid} coincide with those allowed as C identifiers,
380 as specified in~\cite{C}.
381
382 \newpage
383 \section{Foreign Declarations}
384
385 This section describes the extension of Haskell 98 by foreign declarations.
386 The following production for the nonterminal \gnterm{topdecl} extends the same
387 nonterminal from the Haskell 98 Report. All other nonterminals are new.
388 %
389 \begin{grammar}
390 \grule{topdecl}{%
391 foreign \gnterm{fdecl}}
392 \grule[define variable]{fdecl}{%
393 import \gnterm{callconv} \gopt{\gnterm{safety}} \gnterm{impent}
394 \gnterm{var} {::}\ \gnterm{ftype}}
395 \gor[expose variable]{%
396 export \gnterm{callconv} \gnterm{expent}
397 \gnterm{var} {::}\ \gnterm{ftype}}
398 \grule[calling convention]{callconv}{%
399 ccall \galt\ stdcall \galt\ cplusplus \galt\ jvm \galt\ dotnet}
400 \gor{%
401 \gverbal{system-specific calling conventions}}
402 \grule[imported external entity]{impent}{%
403 \gopt{\gnterm{string}}}
404 \grule[exported entity]{expent}{%
405 \gopt{\gnterm{string}}}
406 \grule{safety}{%
407 unsafe \galt\ safe \galt\ threadsafe}
408 \end{grammar}
409 %
410 There are two flavours of foreign declarations: import and export
411 declarations. An import declaration makes an \emph{external entity,} i.e., a
412 function or memory location defined in an external context, available in the
413 Haskell context. Conversely, an export declaration defines a function of the
414 Haskell context as an external entity in an external context. Consequently,
415 the two types of declarations differ in that an import declaration defines a
416 new variable, whereas an export declaration uses a variable that is already
417 defined in the Haskell module.
418
419 The external context that contains the external entity is determined by the
420 calling convention given in the foreign declaration. Consequently, the exact
421 form of the specification of the external entity is dependent on both the
422 calling convention and on whether it appears in an import declaration (as
423 \gnterm{impent}) or in an export declaration (as \gnterm{expent}). To provide
424 syntactic uniformity in the presence of different calling conventions, it is
425 guaranteed that the description of an external entity lexically appears as a
426 Haskell string lexeme. The only exception is where this string would be the
427 empty string (i.e., be of the form \code{""}); in this case, the string may be
428 omitted in its entirety.
429
430 \subsection{Calling Conventions}
431 \label{sec:call-conv}
432
433 The binary interface to an external entity on a given architecture is
434 determined by a calling convention. It often depends on the programming
435 language in which the external entity is implemented, but usually is more
436 dependent on the system for which the external entity has been compiled.
437
438 As an example of how the calling convention is dominated by the system rather
439 than the programming language, consider that an entity compiled to byte code
440 for the Java Abstract Machine (JVM)~\cite{lindholm-etal:JVM} needs to be
441 invoked by the rules of the JVM rather than that of the source language in
442 which it is implemented (the entity might be implemented in Oberon, for
443 example).
444
445 Any implementation of the Haskell 98 FFI must at least implement the C calling
446 convention denoted by \code{ccall}. All other calling conventions are
447 optional. Generally, the set of calling conventions is open, i.e., individual
448 implementations may elect to support additional calling conventions. In
449 addition to \code{ccall}, Table~\ref{tab:callconv} specifies a range of
450 identifiers for common calling conventions.
451 %
452 \begin{table}[tbp]
453 \begin{center}
454 \begin{tabular}{|l|l|}
455 \hline
456 Identifier & Represented calling convention\\
457 \hline\hline
458 \code{ccall}
459 & Calling convention of the standard C compiler on a system\\
460 \code{cplusplus}
461 & Calling convention of the standard C{+}{+} compiler on a system\\
462 \code{dotnet}
463 & Calling convention of the \textsc{.net} platform\\
464 \code{jvm}
465 & Calling convention of the Java Abstract Machine\\
466 \code{stdcall}
467 & Calling convention of the Win32 API (matches Pascal conventions)\\
468 \hline
469 \end{tabular}
470 \caption{Calling conventions}
471 \label{tab:callconv}
472 \end{center}
473 \end{table}
474 %
475 Implementations need not implement all of these conventions, but if any is
476 implemented, it must use the listed name. For any other calling convention,
477 implementations are free to choose a suitable name.
478
479 The present report does only define the semantics of the calling conventions
480 \code{ccall} and \code{stdcall}. Later versions of the report are expected to
481 cover more calling conventions.
482
483 It should be noted that the code generated by a Haskell system to implement a
484 particular calling convention may vary widely with the target code of that
485 system. For example, the calling convention \code{jvm} will be trivial to
486 implement for a Haskell compiler generating Java code, whereas for a Haskell
487 compiler generating C code, the Java Native Interface (JNI)~\cite{liang:JNI}
488 has to be targeted.
489
490 \subsection{Foreign Types}
491 \label{sec:foreign-types}
492
493 The following types constitute the set of \emph{basic foreign types}:
494 %
495 \begin{itemize}
496 \item \code{Char}, \code{Int}, \code{Double}, \code{Float}, and \code{Bool} as
497 exported by the Haskell 98 \code{Prelude} as well as
498 \item \code{Int8}, \code{Int16}, \code{Int32}, \code{Int64}, \code{Word8},
499 \code{Word16}, \code{Word32}, \code{Word64}, \code{Ptr a}, \code{FunPtr a},
500 and \code{StablePtr a}, for any type \code{a}, as exported by \code{Foreign}
501 (Section~\ref{sec:Foreign}).
502 \end{itemize}
503 %
504 A Haskell system that implements the FFI needs to be able to pass these types
505 between the Haskell and the external context as function arguments and
506 results.
507
508 Foreign types are produced according to the following grammar:
509 %
510 \begin{grammar}
511 \grule{ftype}{%
512 \gnterm{frtype}}
513 \gor{%
514 \gnterm{fatype} -> \gnterm{ftype}}
515 \grule{frtype}{%
516 \gnterm{fatype}}
517 \gor{%
518 ()}
519 \grule[$k\geq0$]{fatype}{%
520 \gnterm{qtycon} \gnterm[1]{atype} \gellipse\ \gnterm[k]{atype}}
521 \end{grammar}
522 %
523 A foreign type is the Haskell type of an external entity. Only a subset of
524 Haskell's types are permissible as foreign types, as only a restricted set of
525 types can be canonically transferred between the Haskell context and an
526 external context. A foreign type generally has the form
527 \[
528 \textit{at}_1\code{ -> }\cdots\code{ -> }\textit{at}_n\code{ -> }\textit{rt}
529 \]
530 where \(n\geq0\). It implies that the arity of the external entity is $n$.
531
532 The argument types \(\textit{at}_i\) produced by \gnterm{fatype} must be
533 \emph{marshallable foreign types;} that is, each \(\textit{at}_i\) is either
534 (1) a basic foreign type or (2) a type synonym or renamed datatype of a
535 marshallable foreign type. Moreover, the result type \textit{rt} produced by
536 \gnterm{frtype} must be a \emph{marshallable foreign result type;} that is, it
537 is either a marshallable foreign type, the type \code{()}, or a type matching
538 \code{Prelude.IO }$t$, where $t$ is a marshallable foreign type or \code{()}.
539
540 External functions are generally strict in all arguments.
541
542 \subsection{Import Declarations}
543 \label{sec:import}
544
545 Generally, an import declaration has the form
546 %
547 \[
548 \code{foreign}~\code{import}~c~e~v~\code{{::}}~t
549 \]
550 %
551 which declares the variable $v$ of type $t$ to be defined externally.
552 Moreover, it specifies that $v$ is evaluated by executing the external entity
553 identified by the string $e$ using calling convention $c$. The precise form
554 of $e$ depends on the calling convention and is detailed in
555 Section~\ref{sec:extent}. If a variable $v$ is defined by an import
556 declaration, no other top-level declaration for $v$ is allowed in the same
557 module. For example, the declaration
558 %
559 \begin{quote}
560 \begin{verbatim}
561 foreign import ccall "string.h strlen" cstrlen :: Ptr CChar -> IO CSize
562 \end{verbatim}
563 \end{quote}
564 %
565 introduces the function \code{cstrlen}, which invokes the external function
566 \code{strlen} using the standard C calling convention. Some external entities
567 can be imported as pure functions; for example,
568 %
569 \begin{quote}
570 \begin{verbatim}
571 foreign import ccall "math.h sin" sin :: CDouble -> CDouble.
572 \end{verbatim}
573 \end{quote}
574 %
575 Whether a particular form of external entity places a constraint on the
576 Haskell type with which it can be imported is defined in
577 Section~\ref{sec:extent}. Although, some forms of external entities restrict
578 the set of Haskell types that are permissible, the system can generally not
579 guarantee the consistency between the Haskell type given in an import
580 declaration and the argument and result types of the external entity. It is
581 the responsibility of the programmer to ensure this consistency.
582
583 Optionally, an import declaration can specify, after the calling convention,
584 the safety level that should be used when invoking an external entity. A
585 \code{safe} call is less efficient, but guarantees to leave the Haskell system
586 in a state that allows callbacks from the external code. In contrast, an
587 \code{unsafe} call, while carrying less overhead, must not trigger a callback
588 into the Haskell system. If it does, the system behaviour is undefined. The
589 default for an invocation is to be \code{safe}. Note that a callback into
590 the Haskell system implies that a garbage collection might be triggered after
591 an external entity was called, but before this call returns. Consequently,
592 objects other than stable pointers (cf.\ Section~\ref{sec:StablePtr}) may be
593 moved or garbage collected by the storage manager.
594
595 The safety level \code{threadsafe} is relevant only for Haskell systems that
596 support concurrency in the form of non-Haskell threads that may preempt the
597 Haskell runtime as well as preempt foreign calls. On such systems, a foreign
598 call marked as \code{threadsafe} must be executed by a separate non-Haskell
599 thread, but otherwise behaves as a \code{safe} call. This implies that even
600 if that separate thread is blocked, the Haskell runtime can still make
601 progress. In contrast, when a \code{safe} or \code{unsafe} foreign call
602 blocks, the Haskell runtime also blocks. On Haskell systems that do not
603 support the use of non-Haskell threads, \code{threadsafe} implies the same
604 behaviour as \code{safe}.
605
606 \subsection{Export Declarations}
607
608 The general form of export declarations is
609 %
610 \[
611 \code{foreign}~\code{export}~c~e~v~\code{{::}}~t
612 \]
613 %
614 Such a declaration enables external access to $v$, which may be a value, field
615 name, or class method that is declared on the top-level of the same module or
616 imported. Moreover, the Haskell system defines the external entity described
617 by the string $e$, which may be used by external code using the calling
618 convention $c$; an external invocation of the external entity $e$ is
619 translated into evaluation of $v$. The type $t$ must be an instance of the
620 type of $v$. For example, we may have
621 %
622 \begin{quote}
623 \begin{verbatim}
624 foreign export ccall "addInt" (+) :: Int -> Int -> Int
625 foreign export ccall "addFloat" (+) :: Float -> Float -> Float
626 \end{verbatim}
627 \end{quote}
628
629 If an evaluation triggered by an external invocation of an exported Haskell
630 value returns with an exception, the system behaviour is undefined. Thus,
631 Haskell exceptions have to be caught within Haskell and explicitly marshalled
632 to the foreign code.
633
634
635 \section{Specification of External Entities}
636 \label{sec:extent}
637
638 Each foreign declaration has to specify the external entity that is accessed
639 or provided by that declaration. The syntax and semantics of the notation
640 that is required to uniquely determine an external entity depends heavily on
641 the calling convention by which this entity is accessed. For example, for the
642 calling convention \code{ccall}, a global label is sufficient. However, to
643 uniquely identify a method in the calling convention \code{jvm}, type
644 information has to be provided. For the latter, there is a choice between the
645 Java source-level syntax of types and the syntax expected by JNI---but,
646 clearly, the syntax of the specification of an external entity depends on the
647 calling convention and may be non-trivial.
648
649 Consequently, the FFI does not fix a general syntax for denoting external
650 entities, but requires both \gnterm{impent} and \gnterm{expent} to take the
651 form of a Haskell \gnterm{string} literal. The formation rules for the values
652 of these strings depend on the calling convention and a Haskell system
653 implementing a particular calling convention will have to parse these strings
654 in accordance with the calling convention.
655
656 Defining \gnterm{impent} and \gnterm{expent} to take the form of a
657 \gnterm{string} implies that all information that is needed to statically
658 analyse the Haskell program is separated from the information needed to
659 generate the code interacting with the foreign language. This is, in
660 particular, helpful for tools processing Haskell source code. When ignoring
661 the entity information provided by \gnterm{impent} or \gnterm{expent}, foreign
662 import and export declarations are still sufficient to infer identifier
663 definition and use information as well as type information.
664
665 For more complex calling conventions, there is a choice between the user-level
666 syntax for identifying entities (e.g., Java or C{+}{+}) and the system-level
667 syntax (e.g., the type syntax of JNI or mangled C{+}{+}, respectively). If
668 such a choice exists, the user-level syntax is preferred. Not only because it
669 is more user friendly, but also because the system-level syntax may not be
670 entirely independent of the particular implementation of the foreign language.
671
672 The following defines the syntax for specifying external entities and their
673 semantics for the calling conventions \code{ccall} and \code{stdcall}. Other
674 calling conventions from Table~\ref{tab:callconv} are expected to be defined
675 in future versions of this report.
676
677
678 \subsection{Standard C Calls}
679 \label{sec:ccall}
680
681 The following defines the structure of external entities for foreign
682 declarations under the \code{ccall} calling convention for both import and
683 export declarations separately. Afterwards additional constraints on the type
684 of foreign functions are defined.
685
686 The FFI covers only access to C functions and global variables. There are no
687 mechanisms to access other entities of C programs. In particular, there is no
688 support for accessing pre-processor symbols from Haskell, which includes
689 \code{\#define}d constants. Access from Haskell to such entities is the
690 domain of language-specific tools, which provide added convenience over the
691 plain FFI as defined in this report.
692
693 \subsubsection{Import Declarations}
694
695 For import declarations, the syntax for the specification of external entities
696 under the \code{ccall} calling convention is as follows:
697 %
698 \begin{grammar}
699 \grule[static function or address]{impent}{%
700 " \gopt{static} \gopt{\gnterm{chname}} \gopt{\&}
701 \gopt{\gnterm{cid}} "}
702 \gor[stub factory importing addresses]{%
703 " dynamic "}
704 \gor[stub factory exporting thunks]{%
705 " wrapper "}
706 \end{grammar}
707 %
708 The first alternative either imports a static function \gnterm{cid} or, if
709 \gterm\& precedes the identifier, a static address. If \gnterm{cid} is
710 omitted, it defaults to the name of the imported Haskell variable. The
711 optional filename \gnterm{chname} specifies a C header file, where the
712 intended meaning is that the header file declares the C entity identified by
713 \gnterm{cid}. In particular, when the Haskell system compiles Haskell to C
714 code, the directive
715 %
716 \begin{quote}
717 \gterm{\#include "\gnterm{chname}"}
718 \end{quote}
719 %
720 needs to be placed into any generated C file that refers to the foreign entity
721 before the first occurrence of that entity in the generated C file.
722
723 The second and third alternative, identified by the keywords \gterm{dynamic}
724 and \gterm{wrapper}, respectively, import stub functions that have to be
725 generated by the Haskell system. In the case of \gterm{dynamic}, the stub
726 converts C function pointers into Haskell functions; and conversely, in the
727 case of \gterm{wrapper}, the stub converts Haskell thunks to C function
728 pointers.
729
730 If neither of the specifiers \code{static}, \code{dynamic}, or \code{wrapper}
731 is given, \code{static} is assumed. The specifier \code{static} is
732 nevertheless needed so that we can import C routines that are named
733 \code{dynamic} or \code{wrapper}.
734
735 \subsubsection{Export Declarations}
736
737 External entities in \gnterm{ccall} export declarations are of the form
738 %
739 \begin{grammar}
740 \grule{expent}{%
741 " \gopt{\gnterm{cid}} "}
742 \end{grammar}
743 %
744 The optional C identifier \gnterm{cid} defines the external name by which the
745 exported Haskell variable is accessible in C. If it is omitted, the external
746 name defaults to the name of the exported Haskell variable.
747
748 \subsubsection{Constraints on Foreign Function Types}
749
750 In the case of import declaration, there are, depending on the kind of import
751 declaration, constraints regarding the admissible Haskell type that the
752 variable defined in the import may have. These constraints are specified in
753 the following.
754 %
755 \begin{description}
756 \item[Static Functions.] A static function can be of any foreign type; in
757 particular, the result type may or may not be in the IO monad. If a
758 function that is not pure is not imported in the IO monad, the system
759 behaviour is undefined. Generally, no check for consistency with the C type
760 of the imported label is performed.
761
762 As an example, consider
763 %
764 \begin{quote}
765 \begin{verbatim}
766 foreign import ccall "static stdlib.h" system :: Ptr CChar -> IO CInt
767 \end{verbatim}
768 \end{quote}
769 %
770 This declaration imports the \code{system()} function whose prototype is
771 available from \code{stdlib.h}.
772
773 \item[Static addresses.] The type of an imported address is constrained to be
774 of the form \code{Ptr }\textit{a} or \code{FunPtr }\textit{a}, where
775 \textit{a} can be any type.
776
777 As an example, consider
778 %
779 \begin{quote}
780 \begin{verbatim}
781 foreign import ccall "errno.h &errno" errno :: Ptr CInt
782 \end{verbatim}
783 \end{quote}
784 %
785 It imports the address of the variable \code{errno}, which is of the C type
786 \code{int}.
787
788 \item[Dynamic import.] The type of a \gnterm{dynamic} stub has to be of the
789 form \code{(FunPtr }\textit{ft}\code{) -> }\textit{ft}, where \textit{ft} may
790 be any foreign type.
791
792 As an example, consider
793 %
794 \begin{quote}
795 \begin{verbatim}
796 foreign import ccall "dynamic"
797 mkFun :: FunPtr (CInt -> IO ()) -> (CInt -> IO ())
798 \end{verbatim}
799 \end{quote}
800 %
801 The stub factory \code{mkFun} converts any pointer to a C function that gets
802 an integer value as its only argument and does not have a return value into
803 a corresponding Haskell function.
804
805 \item[Dynamic wrapper.] The type of a \gnterm{wrapper} stub has to be of the
806 form \textit{ft}\code{ -> }\code{IO (FunPtr }\textit{ft}\code), where
807 \textit{ft} may be any foreign type.
808
809 As an example, consider
810 %
811 \begin{quote}
812 \begin{verbatim}
813 foreign import ccall "wrapper"
814 mkCallback :: IO () -> IO (FunPtr (IO ()))
815 \end{verbatim}
816 \end{quote}
817 %
818 The stub factory \code{mkCallback} turns any Haskell computation of type
819 \code{IO ()} into a C function pointer that can be passed to C routines,
820 which can call back into the Haskell context by invoking the referenced
821 function.
822
823 \end{description}
824
825 \subsubsection{Specification of Header Files}
826
827 A C header specified in an import declaration is always included by
828 \gterm{\#include "\gnterm{chname}"}. There is no explicit support for
829 \gterm{\#include <\gnterm{chname}>} style inclusion. The ISO C99~\cite{C99}
830 standard guarantees that any search path that would be used for a
831 \gterm{\#include <\gnterm{chname}>} is also used for \gterm{\#include
832 "\gnterm{chname}"} and it is guaranteed that these paths are searched after
833 all paths that are unique to \gterm{\#include "\gnterm{chname}"}. Furthermore,
834 we require that \gnterm{chname} ends on \code{.h} to make parsing of the
835 specification of external entities unambiguous.
836
837 The specification of include files has been kept to a minimum on purpose.
838 Libraries often require a multitude of include directives, some of which may
839 be system-dependent. Any design that attempts to cover all possible
840 configurations would introduce significant complexity. Moreover, in the
841 current design, a custom include file can be specified that uses the standard
842 C preprocessor features to include all relevant headers.
843
844 Header files have no impact on the semantics of a foreign call, and whether an
845 implementation uses the header file or not is implementation-defined.
846 However, as some implementations may require a header file that supplies a
847 correct prototype for external functions in order to generate correct code,
848 portable FFI code must include suitable header files.
849
850 \subsubsection{C Argument Promotion}
851
852 The argument passing conventions of C are dependant on whether a function
853 prototype for the called functions is in scope at a call site. In particular,
854 if no function prototype is in scope, \emph{default argument promotion} is
855 applied to integral and floating types. In general, it cannot be expected
856 from a Haskell system that it is aware of whether a given C function was
857 compiled with or without a function prototype being in scope. For the sake of
858 portability, we thus require that a Haskell system generally implements calls
859 to C functions as well as C stubs for Haskell functions as if a function
860 prototype for the called function is in scope.
861
862 This convention implies that the onus for ensuring the match between C and
863 Haskell code is placed on the FFI user. In particular, when a C function that
864 was compiled without a prototype is called from Haskell, the Haskell signature
865 at the corresponding \code{foreign import} declaration must use the types
866 \emph{after} argument promotion. For example, consider the following C
867 function definition, which lacks a prototype:
868 %
869 \begin{quote}
870 \begin{verbatim}
871 void foo (a) {
872 float a;
873 ...
874 }
875 \end{verbatim}
876 \end{quote}
877 %
878 The lack of a prototype implies that a C compiler will apply default argument
879 promotion to the parameter \code{a}, and thus, \code{foo} will expect to
880 receive a value of type \code{double}, \emph{not} \code{float}. Hence, the
881 correct \code{foreign import} declaration is
882 %
883 \begin{quote}
884 \begin{verbatim}
885 foreign import ccall foo :: Double -> IO ()
886 \end{verbatim}
887 \end{quote}
888
889 In contrast, a C function compiled with the prototype
890 %
891 \begin{quote}
892 \begin{verbatim}
893 void foo (float a);
894 \end{verbatim}
895 \end{quote}
896 %
897 requires
898 %
899 \begin{quote}
900 \begin{verbatim}
901 foreign import ccall foo :: Float -> IO ()
902 \end{verbatim}
903 \end{quote}
904
905 A similar situation arises in the case of \code{foreign export} declarations
906 that use types that would be altered under the C default argument promotion
907 rules. When calling such Haskell functions from C, a function prototype
908 matching the signature provided in the \code{foreign export} declaration must
909 be in scope; otherwise, the C compiler will erroneously apply the promotion
910 rules to all function arguments.
911
912 Note that for a C function defined to a accept a variable number of arguments,
913 all arguments beyond the explicitly typed arguments suffer argument promotion.
914 However, because C permits the calling convention to be different for such
915 functions; a Haskell system will, in general, not be able to make use of
916 variable argument functions. Hence, their use is deprecated in portable code.
917
918
919 \subsection{Win32 API Calls}
920
921 The specification of external entities under the \code{stdcall} calling
922 convention is identical to that for standard C calls. The two calling
923 conventions only differ in the generated code.
924
925
926 \begin{FUTURE} % ===== Material for future extension =======================
927
928 \subsection{C{+}{+} Calls}
929
930 The syntax for the specification of external entities under the
931 \code{cplusplus} calling convention is
932
933 \subsection{JVM Calls}
934
935 The syntax for the specification of external entities under the \code{jvm}
936 calling convention is
937 %
938 \begin{grammar}
939 \grule{impent}{%
940 "\gnterm{jtype} \gnterm{jqid}(\gnterm{jtypes})"}
941 \gor[constructor call]{%
942 "new \gnterm{jqid}(\gnterm{jtypes})"}
943 \grule[$n\geq0$]{jtypes}{%
944 \gnterm[1]{jtype},\gellipse,\gnterm[n]{jtype}}
945 \end{grammar}
946 %
947 where \gnterm{jqid} is a qualified Java identifier and \gnterm{jtype} a Java
948 types as defined in~\cite{gosling-etal:Java}.
949
950 \begin{verbatim}
951 FIXME:
952 - force the inclusion of the return type in case of "new"?
953 \end{verbatim}
954
955 \subsection{.NET Calls}
956
957 The syntax for the specification of external entities under the \code{dotnet}
958 calling convention is
959
960 \end{FUTURE}% =============================================================
961
962
963 \newpage
964 \section{Marshalling}
965 \label{sec:marshalling}
966
967 In addition to the language extension discussed in previous sections, the FFI
968 includes a set of standard libraries, which ease portable use of foreign
969 functions as well as marshalling of compound structures. Generally, the
970 marshalling of Haskell structures into a foreign representation and vice versa
971 can be implemented in either Haskell or the foreign language. At least where
972 the foreign language is at a significantly lower level, e.g.\ C, there are
973 good reasons for doing the marshalling in Haskell:
974 %
975 \begin{itemize}
976 \item Haskell's lazy evaluation strategy would require any foreign code that
977 attempts to access Haskell structures to force the evaluation of these
978 structures before accessing them. This would lead to complicated code in the
979 foreign language, but does not need any extra consideration when coding the
980 marshalling in Haskell.
981 \item Despite the fact that marshalling code in Haskell tends to look like C
982 in Haskell syntax, the strong type system still catches many errors that
983 would otherwise lead to difficult-to-debug runtime faults.
984 \item Direct access to Haskell heap structures from a language like
985 C---especially, when marshalling from C to Haskell, i.e., when Haskell
986 structures are created---carries the risk of corrupting the heap, which
987 usually leads to faults that are very hard to debug.
988 \end{itemize}
989 %
990 Consequently, the Haskell FFI emphasises Haskell-side marshalling.
991
992 The interface to the marshalling libraries is provided by the module
993 \code{Foreign} plus a language-dependent module per supported language. In
994 particular, the standard requires the availability of the module
995 \code{CForeign}, which simplifies portable interfacing with external C code.
996 Language-dependent modules, such as \code{CForeign}, generally provide Haskell
997 types representing the basic types of the foreign language using a
998 representation that is compatible with the foreign types as implemented by the
999 default implementation of the foreign language on the present architecture.
1000 This is especially important for languages where the standard leaves some
1001 aspects of the implementation of basic types open. For example, in C, the
1002 size of the various integral types is not fixed. Thus, to represent C
1003 interfaces faithfully in Haskell, for each integral type in C, we need to have
1004 an integral type in Haskell that is guaranteed to have the same size as the
1005 corresponding C type.
1006
1007 In the following, the interface of the language independent support is
1008 defined. The interface for C-specific support is discussed in
1009 Section~\ref{sec:c-marshalling}.
1010
1011 \subsection{\code{Foreign}}
1012 \label{sec:Foreign}
1013
1014 The module \code{Foreign} combines the interfaces of all modules providing
1015 language-independent marshalling support. These modules are \code{Bits},
1016 \code{Int}, \code{Word}, \code{Ptr}, \code{ForeignPtr}, \code{StablePtr},
1017 \code{Storable}, \code{MarshalAlloc}, \code{MarshalArray},
1018 \code{MarshalError}, and \code{MarshalUtils}.
1019
1020 Furthermore, \code{Foreign} provides the following function:
1021 %
1022 \begin{codedesc}
1023 \item[unsafePerformIO ::\ IO a -> a] Execute an \code{IO} action in place of a
1024 pure computations. For the behaviour to be predictable, the IO computation
1025 should be free of side effects and independent of its environment.
1026
1027 If the \code{IO} computation wrapped in \code{unsafePerformIO} performs side
1028 effects, then the relative order in which those side effects take place
1029 (relative to the main \code{IO} trunk, or other calls to
1030 \code{unsafePerformIO}) is indeterminate.
1031
1032 Great care should be exercised in the use of this function. Not only
1033 because of the danger of introducing side effects, but also because
1034 \code{unsafePerformIO} may compromise typing, for example, when it is used
1035 in conjunction with polymorphic references.
1036 \end{codedesc}
1037
1038 \subsection{\code{Bits}}
1039
1040 This module provides functions implementing typical bit operations overloaded
1041 for the standard integral types \code{Int} and \code{Integer} as well as the
1042 types provided by the modules \code{Int} and \code{Word} in
1043 Section~\ref{sec:Int-Word}. The overloading is implemented via a new type
1044 class \code{Bits}, which is a subclass of \code{Num} and has the following
1045 member functions:
1046 %
1047 \begin{codedesc}
1048 \item[(.\&.), (.|.), xor ::\ Bits a => a -> a -> a] Implement bitwise
1049 conjunction, disjunction, and exclusive or. The infix operators have the
1050 following precedences:
1051 %
1052 \begin{quote}
1053 \begin{verbatim}
1054 infixl 7 .&.
1055 infixl 6 `xor`
1056 infixl 5 .|.
1057 \end{verbatim}
1058 \end{quote}
1059
1060 \item[complement ::\ Bits a => a -> a] Calculate the bitwise complement of the
1061 argument.
1062
1063 \item[shift, rotate ::\ Bits a => a -> Int -> a] Shift or rotate the bit
1064 pattern to the left for a positive second argument and to the right for a
1065 negative argument. The function \code{shift} performs sign extension on
1066 signed number types; i.e., right shifts fill the top bits with 1 if the
1067 number is negative and with 0 otherwise. These operators have the following
1068 precedences as infix operators:
1069 %
1070 \begin{quote}
1071 \begin{verbatim}
1072 infixl 8 `shift`, `rotate`
1073 \end{verbatim}
1074 \end{quote}
1075 %
1076 The function \code{rotate} is undefined for types where \code{bitSize}
1077 returns 0.
1078
1079 \item[bit ::\ Bits a => Int -> a] Obtain a value where only the $n$th bit
1080 is set.
1081
1082 \item[setBit, clearBit, complementBit ::\ a -> Int -> a] Set, clear, or
1083 complement the bit at the given position.
1084
1085 \item[testBit ::\ Bits a => a -> Int -> Bool] Check whether the $n$th bit of
1086 the first argument is set.
1087
1088 \item[bitSize~~::\ Bits a => a -> Int]
1089 \item[isSigned~::\ Bits a => a -> Bool]\combineitems Respectively, query the
1090 number of bits of values of type \code{a} and whether these values are
1091 signed. These functions never evaluate their argument. The function
1092 \code{bitSize} is undefined for types that do not have a have a fixed
1093 bitsize (e.g., \code{Integer}).
1094
1095 \item[shiftL,~~shiftR~~::\ Bits a => a -> Int -> a]
1096 \item[rotateL,~rotateR~::\ Bits a => a -> Int -> a]\combineitems The functions
1097 \code{shiftR} and \code{rotateR} are synonyms for \code{shift} and
1098 \code{rotate}; \code{shiftL} and \code{rotateL} negate the second argument.
1099 These operators have the following precedences as infix operators:
1100 %
1101 \begin{quote}
1102 \begin{verbatim}
1103 infixl 8 `shiftL`, `shiftR`, `rotateL`, `rotateR`
1104 \end{verbatim}
1105 \end{quote}
1106
1107 \end{codedesc}
1108 %
1109 Bits are numbered from 0 with bit 0 being the least significant bit. A
1110 minimal complete definition of the type class \code{Bits} must include
1111 definitions for the following functions: \code{(.\&.)}, \code{(.|.)},
1112 \code{xor}, \code{complement}, \code{shift}, \code{rotate}, \code{bitSize},
1113 and \code{isSigned}.
1114
1115 \subsection{\code{Int} and \code{Word}}
1116 \label{sec:Int-Word}
1117
1118 The two modules \code{Int} and \code{Word} provide the following signed and
1119 unsigned integral types of fixed size:
1120 %
1121 \begin{quote}
1122 \begin{tabular}{|l|l|l|}
1123 \hline
1124 Size in bits & Signed & Unsigned\\\hline\hline
1125 8 & \code{Int8} & \code{Word8}\\
1126 16 & \code{Int16} & \code{Word16}\\
1127 32 & \code{Int32} & \code{Word32}\\
1128 64 & \code{Int64} & \code{Word34}\\
1129 \hline
1130 \end{tabular}
1131 \end{quote}
1132 %
1133 For these integral types, the modules \code{Int} and \code{Word} export class
1134 instances for all types classes for which \code{Int} has an instance; this
1135 includes the type class \code{Bits}. The constraints on the implementation of
1136 these instances are also the same as those outlined for \code{Int} in the
1137 Haskell Report. There is, however, the additional constraint that all
1138 arithmetic on the fixed-sized types is performed modulo \(2^n\).
1139
1140 \subsection{\code{Ptr}}
1141 \label{sec:Ptr}
1142
1143 The module \code{Ptr} provides typed pointers to foreign entities. We
1144 distinguish two kinds of pointers: pointers to data and pointers to functions.
1145 It is understood that these two kinds of pointers may be represented
1146 differently as they may be references to data and text segments, respectively.
1147
1148 \subsubsection{Data Pointers}
1149
1150 The interface defining data pointers and associated operations is as follows:
1151 %
1152 \begin{codedesc}
1153 \item[data Ptr a] A value of type \code{Ptr a} represents a pointer to an
1154 object, or an array of objects, which may be marshalled to or from Haskell
1155 values of type \code{a}. The type \code{a} will normally be an instance of
1156 class \code{Storable} (see Section~\ref{sec:Storable}), which provides the
1157 necessary marshalling operations.
1158
1159 Instances for the classes \code{Eq}, \code{Ord}, and \code{Show} are
1160 provided.
1161 \item[nullPtr ::\ Ptr a] The constant \code{nullPtr} contains a distinguished
1162 value of \code{Ptr} that is not associated with a valid memory location.
1163 \item[castPtr ::\ Ptr a -> Ptr b] The \code{castPtr} function casts a pointer
1164 from one type to another.
1165 \item[plusPtr ::\ Ptr a -> Int -> Ptr b] Advances the given address by the
1166 given offset in bytes.
1167 \item[alignPtr ::\ Ptr a -> Int -> Ptr a] Given an arbitrary address and an
1168 alignment constraint, \code{alignPtr} yields an address, the same or next
1169 higher, that fulfills the alignment constraint. An alignment constraint
1170 \code{x} is fulfilled by any address divisible by \code{x}. This operation
1171 is idempotent.
1172 \item[minusPtr ::\ Ptr a -> Ptr b -> Int] Compute the offset required to get
1173 from the first to the second argument. We have
1174 %
1175 \begin{quote}
1176 \begin{verbatim}
1177 p2 == p1 `plusPtr` (p2 `minusPtr` p1)
1178 \end{verbatim}
1179 \end{quote}
1180 \end{codedesc}
1181 %
1182 It should be noted that the use of \code{Int} for pointer differences
1183 essentially forces any implementation to represent \code{Int} in as many bits
1184 as used in the representation of pointer values.
1185
1186 \subsubsection{Function Pointers}
1187
1188 The interface defining function pointers and associated operations is as
1189 follows:
1190 %
1191 \begin{codedesc}
1192 \item[data FunPtr a] A value of type \code{FunPtr a} is a pointer to a piece
1193 of code. It may be the pointer to a C function or to a Haskell function
1194 created using a wrapper stub as outlined in Section~\ref{sec:ccall}. For
1195 example,
1196 %
1197 \begin{quote}
1198 \begin{verbatim}
1199 type Compare = Int -> Int -> Bool
1200 foreign import ccall "wrapper"
1201 mkCompare :: Compare -> IO (FunPtr Compare)
1202 \end{verbatim}
1203 \end{quote}
1204
1205 Instances for the classes \code{Eq}, \code{Ord}, and \code{Show} are
1206 provided.
1207 \item[nullFunPtr ::\ FunPtr a] The constant \code{nullFunPtr} contains a
1208 distinguished value of \code{FunPtr} that is not associated with a valid
1209 memory location.
1210 \item[castFunPtr ::\ FunPtr a -> FunPtr b] Cast a \code{FunPtr} to a
1211 \code{FunPtr} of a different type.
1212 \item[freeHaskellFunPtr ::\ FunPtr a -> IO ()] Release the storage associated
1213 with the given \code{FunPtr}, which must have been obtained from a wrapper
1214 stub. This should be called whenever the return value from a foreign import
1215 wrapper function is no longer required; otherwise, the storage it uses will
1216 leak.
1217 \end{codedesc}
1218
1219 Moreover, there are two functions that are only valid on architectures where
1220 data and function pointers range over the same set of addresses. Only where
1221 bindings to external libraries are made whose interface already relies on this
1222 assumption, should the use of \code{castFunPtrToPtr} and
1223 \code{castPtrToFunPtr} be considered; otherwise, it is recommended to avoid
1224 using these functions.
1225 %
1226 \begin{codedesc}
1227 \item[castFunPtrToPtr ::\ FunPtr a -> Ptr b]
1228 \item[castPtrToFunPtr ::\ Ptr a -> FunPtr b] \combineitems These two functions
1229 cast \code{Ptr}s to \code{FunPtr}s and vice versa.
1230 \end{codedesc}
1231
1232 \subsection{\code{ForeignPtr}}
1233 \label{sec:ForeignPtr}
1234
1235 The type \code{ForeignPtr} represents references to objects that are
1236 maintained in a foreign language, i.e., objects that are not part of the data
1237 structures usually managed by the Haskell storage manager. The essential
1238 difference between \code{ForeignPtr}s and vanilla memory references of type
1239 \code{Ptr} is that the former may be associated with finalizers. A finalizer
1240 is a routine that is invoked when the Haskell storage manager detects
1241 that---within the Haskell heap and stack---there are no more references left
1242 that are pointing to the \code{ForeignPtr}. Typically, the finalizer will,
1243 then, invoke routines in the foreign language that free the resources bound by
1244 the foreign object.
1245
1246 The type \code{ForeignPtr} is parameterised in the same way as \code{Ptr}
1247 (cf.\ Section~\ref{sec:Ptr}). The data type and associated operations have
1248 the following signature and purpose:
1249 %
1250 \begin{codedesc}
1251 \item[data ForeignPtr a] A value of type \code{ForeignPtr a} represents a
1252 pointer to an object, or an array of objects, which may be marshalled to or
1253 from Haskell values of type \code{a}. The type \code{a} will normally be an
1254 instance of class \code{Storable} (see Section~\ref{sec:Storable}), which
1255 provides the marshalling operations.
1256
1257 Instances for the classes \code{Eq}, \code{Ord}, and \code{Show} are
1258 provided. Equality and ordering of two foreign pointers are the same as for
1259 the plain pointers that can be obtained with \code{foreignPtrToPtr} from
1260 those foreign pointers.
1261
1262 \item[newForeignPtr ::\ Ptr a -> FunPtr (Ptr a -> IO ()) -> IO (ForeignPtr a)]
1263 Turn a plain memory reference into a foreign pointer by associating a
1264 finalizer with the reference. The finalizer is represented by a pointer to
1265 an external function, which will be executed after the last reference to the
1266 foreign pointer is dropped. On invocation, the finalizer the pointer from
1267 which the foreign pointer was created as an argument. Note that there is no
1268 guarantee on how soon the finalizer is executed after the last reference was
1269 dropped; this depends on the details of the Haskell storage manager. The
1270 only guarantee is that the finalizer runs before the program terminates.
1271
1272 Whether a finaliser may call back into the Haskell system is system
1273 dependent. Portable code may not rely on such call backs.
1274
1275 \item[addForeignPtrFinalizer ::\ ForeignPtr a -> FunPtr (Ptr a -> IO ()) -> IO
1276 ()] Add another finalizer to the given foreign pointer. All finalizers
1277 associated with a single foreign pointer are executed in the opposite order
1278 of their addition---i.e., the finalizer added last will be executed first.
1279
1280 \item[mallocForeignPtr ::\ Storable a => IO (ForeignPtr a)] Allocate a block
1281 of memory that is sufficient to hold values of type \code{a}. The size of
1282 the memory area is determined by the function \code{Storable.sizeOf}
1283 (Section~\ref{sec:Storable}). This corresponds to
1284 \code{MarshalAlloc.malloc} (Section~\ref{sec:MarshalAlloc}), but
1285 automatically attaches a finalizer that frees the block of memory as soon as
1286 all references to that block of of memory have been dropped. It is
1287 \emph{not} guaranteed that the block of memory was allocated by
1288 \code{MarshalAlloc.malloc}; so, \code{MarshalAlloc.realloc} must not be
1289 applied to the resulting pointer.
1290
1291 \item[mallocForeignPtrBytes ::\ Int -> IO (ForeignPtr a)] Allocate a block of
1292 memory of the given number of bytes with a finalizer attached that frees the
1293 block of memory as soon as all references to that block of memory have
1294 been dropped. As for \code{mallocForeignPtr}, \code{MarshalAlloc.realloc}
1295 must not be applied to the resulting pointer.
1296
1297 \item[mallocForeignPtrArray~ ::\ Storable a => Int -> IO (ForeignPtr a)]
1298 \item[mallocForeignPtrArray0 ::\ Storable a => Int -> IO (ForeignPtr a)]%
1299 \combineitems These functions correspond to \code{MarshalArray}'s
1300 \code{mallocArray} and \code{mallocArray0}, respectively, but yield a memory
1301 area that has a finalizer attached that releases the memory area. As with
1302 the previous two functions, it is not guaranteed that the block of memory
1303 was allocated by \code{MarshalAlloc.malloc}.
1304
1305 \item[withForeignPtr ::\ ForeignPtr a -> (Ptr a -> IO b) -> IO b]
1306 This is a way to obtain the pointer living inside a foreign pointer. This
1307 function takes a function which is applied to that pointer. The resulting
1308 \code{IO} action is then executed. The foreign pointer is kept alive at least
1309 during the whole action, even if it is not used directly inside. Note that
1310 it is not safe to return the pointer from the action and use it after the
1311 action completes. All uses of the pointer should be inside the
1312 \code{withForeignPtr} bracket.
1313
1314 More precisely, the foreign pointer may be finalized after
1315 \code{withForeignPtr} is finished if the first argument was the last
1316 occurrence of that foreign pointer. Finalisation of the foreign pointer
1317 might render the pointer that is passed to the function useless.
1318 Consequently, this pointer cannot be used safely anymore after the
1319 \code{withForeignPtr} is finished, unless the function
1320 \code{touchForeignPtr} is used to explicitly keep the foreign pointer alive.
1321
1322 This function is normally used for marshalling data to or from the object
1323 pointed to by the \code{ForeignPtr}, using the operations from the
1324 \code{Storable} class.
1325
1326 \item[foreignPtrToPtr ::\ ForeignPtr a -> Ptr a]
1327
1328 Extract the pointer component of a foreign pointer. This is a potentially
1329 dangerous operation. If the argument to \code{foreignPtrToPtr} is the last
1330 usage occurrence of the given foreign pointer, then its finalizer(s) will be
1331 run, which potentially invalidates the plain pointer just obtained. Hence,
1332 \code{touchForeignPtr} must be used wherever it has to be guaranteed that
1333 the pointer lives on---i.e., has another usage occurrence.
1334
1335 It should be noticed that this function does not need to be monadic when
1336 used in combination with \code{touchForeignPtr}. Until the
1337 \code{foreignPtrToPtr} is executed, the thunk representing the suspended
1338 call keeps the foreign pointer alive. Afterwards, the
1339 \code{touchForeignPtr} keeps the pointer alive.
1340
1341 To avoid subtle coding errors, hand written marshalling code should
1342 preferably use the function \code{withForeignPtr} rather than combinations
1343 of \code{foreignPtrToPtr} and \code{touchForeignPtr}. However, the later
1344 routines are occasionally preferred in tool-generated marshalling code.
1345
1346 \item[touchForeignPtr ::\ ForeignPtr a -> IO ()] Ensure that the foreign
1347 pointer in question is alive at the given place in the sequence of \code{IO}
1348 actions. In particular, \code{withForeignPtr} does a \code{touchForeignPtr}
1349 after it executes the user action.
1350
1351 This function can be used to express liveness dependencies between
1352 \code{ForeignPtr}s: For example, if the finalizer for one \code{ForeignPtr}
1353 touches a second \code{ForeignPtr}, then it is ensured that the second
1354 \code{ForeignPtr} will stay alive at least as long as the first. This can be
1355 useful when you want to manipulate interior pointers to a foreign structure:
1356 You can use \code{touchForeignPtr} to express the requirement that the
1357 exterior pointer must not be finalized until the interior pointer is no
1358 longer referenced.
1359
1360 \item[castForeignPtr ::\ ForeignPtr a -> ForeignPtr b] Cast a
1361 \code{ForeignPtr} parameterised by one type into another type.
1362 \end{codedesc}
1363
1364 \subsection{\code{StablePtr}}
1365 \label{sec:StablePtr}
1366
1367 A \emph{stable pointer} is a reference to a Haskell expression that is
1368 guaranteed not to be affected by garbage collection, i.e., it will neither be
1369 deallocated nor will the value of the stable pointer itself change during
1370 garbage collection (ordinary references may be relocated during garbage
1371 collection). Consequently, stable pointers can be passed to foreign code,
1372 which can treat it as an opaque reference to a Haskell value.
1373
1374 The data type and associated operations have the following signature and
1375 purpose:
1376 %
1377 \begin{codedesc}
1378 \item[data StablePtr a] Values of this type represent a stable reference to a
1379 Haskell value of type \code{a}. Note that a stable pointer may not be
1380 dereferenced with routines from the class \code{Storable} (in contrast to
1381 \code{Ptr} and \code{ForeignPtr}). Any attempt to do so will lead to
1382 undefined behaviour.
1383
1384 \item[newStablePtr ::\ a -> IO (StablePtr a)] Create a stable pointer
1385 referring to the given Haskell value.
1386
1387 \item[deRefStablePtr ::\ StablePtr a -> IO a] Obtain the Haskell value
1388 referenced by a stable pointer, i.e., the same value that was passed to the
1389 corresponding call to \code{makeStablePtr}. If the argument to
1390 \code{deRefStablePtr} has already been freed using \code{freeStablePtr}, the
1391 behaviour of \code{deRefStablePtr} is undefined.
1392
1393 \item[freeStablePtr ::\ StablePtr a -> IO ()] Dissolve the association between
1394 the stable pointer and the Haskell value. Afterwards, if the stable pointer
1395 is passed to \code{deRefStablePtr} or \code{freeStablePtr}, the behaviour is
1396 undefined. However, the stable pointer may still be passed to
1397 \code{castStablePtrToPtr}, but the \code{Ptr ()} value returned by
1398 \code{castStablePtrToPtr}, in this case, is undefined (in particular, it may
1399 be \code{Ptr.nullPtr}). Nevertheless, the call to \code{castStablePtrToPtr}
1400 is guaranteed not to diverge.
1401
1402 \item[castStablePtrToPtr ::\ StablePtr a -> Ptr ()] Coerce a stable pointer to
1403 an address. No guarantees are made about the resulting value, except that
1404 the original stable pointer can be recovered by \code{castPtrToStablePtr}.
1405 In particular, the address may not refer to an accessible memory location and
1406 any attempt to pass it to the member functions of the class \code{Storable}
1407 (Section~\ref{sec:Storable}) leads to undefined behaviour.
1408
1409 \item[castPtrToStablePtr ::\ Ptr () -> StablePtr a] The inverse of
1410 \code{castStablePtrToPtr}, i.e., we have the identity
1411 %
1412 \begin{quote}
1413 \begin{verbatim}
1414 sp == castPtrToStablePtr (castStablePtrToPtr sp)
1415 \end{verbatim}
1416 \end{quote}
1417 %
1418 for any stable pointer \code{sp} on which \code{freeStablePtr} has not been
1419 executed yet. Moreover, \code{castPtrToStablePtr} may only be applied to
1420 pointers that have been produced by \code{castStablePtrToPtr}.
1421 \end{codedesc}
1422
1423 It is important to free stable pointers that are no longer required by using
1424 \code{freeStablePtr}. Otherwise, the object referenced by the stable pointer
1425 will be retained in the heap.
1426
1427
1428 \subsection{\code{Storable}}
1429 \label{sec:Storable}
1430
1431 To code marshalling in Haskell, Haskell data structures need to be translated
1432 into the binary representation of a corresponding data structure of the
1433 foreign language and vice versa. To this end, the module \code{Storable}
1434 provides routines that manipulate primitive data types stored in unstructured
1435 memory blocks. The class \code{Storable} is instantiated for all primitive
1436 types that can be stored in raw memory. Reading and writing these types to
1437 arbitrary memory locations is implemented by the member functions of the
1438 class. The member functions, furthermore, encompass support for computing the
1439 storage requirements and alignment restrictions of storable types.
1440
1441 Memory addresses are represented as values of type \code{Ptr a}
1442 (Section~\ref{sec:Ptr}), where \code{a} is a storable type. The type argument
1443 to \code{Ptr} provides some type safety in marshalling code, as pointers to
1444 different types cannot be mixed without an explicit cast. Moreover, it
1445 assists in resolving overloading.
1446
1447 The class \code{Storable} is instantiated for all standard basic types of
1448 Haskell, the fixed size integral types of the modules \code{Int} and
1449 \code{Word} (Section~\ref{sec:Int-Word}), data and function pointers
1450 (Section~\ref{sec:Ptr}), and stable pointers (Section~\ref{sec:StablePtr}).
1451 There is no instance of \code{Storable} for foreign pointers. The intention
1452 is to ensure that storing a foreign pointer requires an explicit cast to a
1453 plain \code{Ptr}, which makes it obvious that the finalizers of the foreign
1454 pointer may be invoked at this point if no other reference to the pointer
1455 exists anymore.
1456
1457 The signatures and behaviour of the member functions of the class
1458 \code{Storable} are as follows:
1459 %
1460 \begin{codedesc}
1461 \item[sizeOf~~~~::\ Storable a => a -> Int]
1462 \item[alignment~::\ Storable a => a -> Int]\combineitems The function
1463 \code{sizeOf} computes the storage requirements (in bytes) of the argument,
1464 and alignment computes the alignment constraint of the argument. An
1465 alignment constraint \code{x} is fulfilled by any address divisible by
1466 \code{x}. Both functions do not evaluate their argument, but compute the
1467 result on the basis of the type of the argument alone. We require that the
1468 size is divisible by the alignment. (Thus each element of a contiguous
1469 array of storable values will be properly aligned if the first one is.)
1470
1471 \item[peekElemOff ::\ Storable a => Ptr a -> Int -> IO a] Read a value from a
1472 memory area regarded as an array of values of the same kind. The first
1473 argument specifies the start address of the array and the second the index
1474 into the array (the first element of the array has index 0).
1475
1476 \item[pokeElemOff ::\ Storable a => Ptr a -> Int -> a -> IO ()] Write a value
1477 to a memory area regarded as an array of values of the same kind. The first
1478 and second argument are as for \code{peekElemOff}.
1479
1480 \item[peekByteOff ::\ Storable a => Ptr a -> Int -> IO a] Read a value from a
1481 memory location given by a base address and byte offset from that base
1482 address.
1483
1484 \item[pokeByteOff ::\ Storable a => Ptr a -> Int -> a -> IO ()] Write a value
1485 to a memory location given by a base address and offset from that base
1486 address.
1487
1488 \item[peek ::\ Storable a => Ptr a -> IO a] Read a value from the given memory
1489 location.
1490
1491 \item[poke ::\ Storable a => Ptr a -> a -> IO ()] Write the given value to the
1492 given memory location.
1493 \end{codedesc}
1494 %
1495 On some architectures, the \code{peek} and \code{poke} functions might require
1496 properly aligned addresses to function correctly. Thus, portable code should
1497 ensure that when peeking or poking values of some type \code{a}, the alignment
1498 constraint for \code{a}, as given by the function \code{alignment} is
1499 fulfilled.
1500
1501 A minimal complete definition of \code{Storable} needs to define
1502 \code{sizeOf}, \code{alignment}, one of \code{peek}, \code{peekElemOff}, or
1503 \code{peekByteOff}, and one of \code{poke}, \code{pokeElemOff}, and
1504 \code{pokeByteOff}.
1505
1506 \subsection{\code{MarshalAlloc}}
1507 \label{sec:MarshalAlloc}
1508
1509 The module \code{MarshalAlloc} provides operations to allocate and deallocate
1510 blocks of raw memory (i.e., unstructured chunks of memory outside of the area
1511 maintained by the Haskell storage manager). These memory blocks are commonly
1512 used to pass compound data structures to foreign functions or to provide space
1513 in which compound result values are obtained from foreign functions. For
1514 example, Haskell lists are typically passed as C arrays to C functions; the
1515 storage space for such an array can be allocated by the following functions:
1516 %
1517 \begin{codedesc}
1518 \item[malloc ::\ Storable a => IO (Ptr a)] Allocate a block of memory that is
1519 sufficient to hold values of type \code{a}. The size of the memory area is
1520 determined by the function \code{Storable.sizeOf}
1521 (Section~\ref{sec:Storable}).
1522
1523 \item[mallocBytes ::\ Int -> IO (Ptr a)] Allocate a block of memory of the
1524 given number of bytes. The block of memory is sufficiently aligned for any
1525 of the basic foreign types (see Section~\ref{sec:foreign-types}) that fits
1526 into a memory block of the allocated size.
1527
1528 \item[alloca ::\ Storable a => (Ptr a -> IO b) -> IO b] Allocate a block of
1529 memory of the same size as \code{malloc}, but the reference is passed to a
1530 computation instead of being returned. When the computation terminates,
1531 free the memory area again. The operation is exception-safe; i.e.,
1532 allocated memory is freed if an exception is thrown in the marshalling
1533 computation.
1534
1535 \item[allocaBytes ::\ Int -> (Ptr a -> IO b) -> IO b] As \code{alloca}, but
1536 allocate a memory area of the given size. The same alignment constraint as
1537 for \code{mallocBytes} holds.
1538
1539 \item[realloc ::\ Storable b => Ptr a -> IO (Ptr b)] Resize a memory area that
1540 was allocated with \code{malloc} or \code{mallocBytes} to the size needed to
1541 store values of type \code{b}. The returned pointer may refer to an
1542 entirely different memory area, but will be suitably aligned to hold values
1543 of type \code{b}. The contents of the referenced memory area will be the
1544 same as of the original pointer up to the minimum of the size of values of
1545 type \code{a} and \code{b}. If the argument to \code{realloc} is
1546 \code{Ptr.nullPtr}, \code{realloc} behaves like \code{malloc}.
1547
1548 \item[reallocBytes ::\ Ptr a -> Int -> IO (Ptr a)] As \code{realloc}, but
1549 allocate a memory area of the given size. In addition, if the requested size
1550 is 0, \code{reallocBytes} behaves like \code{free}.
1551
1552 \item[free ::\ Ptr a -> IO ()] Free a block of memory that was allocated with
1553 \code{malloc}, \code{mallocBytes}, \code{realloc}, \code{reallocBytes}, or
1554 any of the allocation functions from \code{MarshalArray} (see
1555 Section~\ref{sec:MarshalArray}).
1556 \end{codedesc}
1557 %
1558 If any of allocation functions fails, a value of \code{Ptr.nullPtr} is
1559 produced. If \code{free} or \code{reallocBytes} is applied to a memory area
1560 that has been allocated with \code{alloca} or \code{allocaBytes}, the
1561 behaviour is undefined. Any further access to memory areas allocated with
1562 \code{alloca} or \code{allocaBytes}, after the computation that was passed to
1563 the allocation function has terminated, leads to undefined behaviour. Any
1564 further access to the memory area referenced by a pointer passed to
1565 \code{realloc}, \code{reallocBytes}, or \code{free} entails undefined
1566 behaviour.
1567
1568 \subsection{\code{MarshalArray}}
1569 \label{sec:MarshalArray}
1570
1571 The module \code{MarshalArray} provides operations for marshalling Haskell
1572 lists into monolithic arrays and vice versa. Most functions come in two
1573 flavours: one for arrays terminated by a special termination element and one
1574 where an explicit length parameter is used to determine the extent of an
1575 array. The typical example for the former case are C's NUL terminated
1576 strings. However, please note that C strings should usually be marshalled
1577 using the functions provided by \code{CString} (Section~\ref{sec:CString}) as
1578 the Unicode encoding has to be taken into account. All functions specifically
1579 operating on arrays that are terminated by a special termination element have
1580 a name ending on \code{0}---e.g., \code{mallocArray} allocates space for an
1581 array of the given size, whereas \code{mallocArray0} allocates space for one
1582 more element to ensure that there is room for the terminator.
1583
1584 The following functions are provided by the module:
1585 %
1586 \begin{codedesc}
1587 \item[mallocArray~~::\ Storable a => Int -> IO (Ptr a)]
1588 \item[allocaArray~~::\ Storable a => Int -> (Ptr a -> IO b) -> IO b]
1589 \combineitems
1590 \item[reallocArray~::\ Storable a => Ptr a -> Int -> IO (Ptr a)]\combineitems
1591 The functions behave like the functions \code{malloc}, \code{alloca}, and
1592 \code{realloc} provided by the module \code{MarshalAlloc}
1593 (Section~\ref{sec:MarshalAlloc}), respectively, except that they allocate a
1594 memory area that can hold an array of elements of the given length, instead
1595 of storage for just a single element.
1596
1597 \item[mallocArray0~~::\ Storable a => Int -> IO (Ptr a)]
1598 \item[allocaArray0~~::\ Storable a => Int -> (Ptr a -> IO b) -> IO b]\combineitems
1599 \item[reallocArray0~::\ Storable a => Ptr a -> Int -> IO (Ptr a)]\combineitems
1600 These functions are like the previous three functions, but reserve storage
1601 space for one additional array element to allow for a termination indicator.
1602
1603 \item[peekArray ::\ Storable a => Int -> Ptr a -> IO {[a]}] Marshal an array of
1604 the given length and starting at the address indicated by the pointer
1605 argument into a Haskell list using \code{Storable.peekElemOff} to obtain the
1606 individual elements. The order of elements in the list matches the order in
1607 the array.
1608
1609 \item[pokeArray ::\ Storable a => Ptr a -> {[a]} -> IO ()] Marshal the elements
1610 of the given list into an array whose start address is determined by the
1611 first argument using \code{Storable.pokeElemOff} to write the individual
1612 elements. The order of elements in the array matches that in the list.
1613
1614 \item[peekArray0 ::\ (Storable a, Eq a) => a -> Ptr a -> IO {[a]}] Marshal an
1615 array like \code{peekArray}, but instead of the length of the array a
1616 terminator element is specified by the first argument. All elements of the
1617 array, starting with the first element, up to, but excluding the first
1618 occurrence of an element that is equal (as determined by \code{==}) to the
1619 terminator are marshalled.
1620
1621 \item[pokeArray0 ::\ Storable a => a -> Ptr a -> {[a]} -> IO ()]
1622 Marshal an array like \code{pokeArray}, but write a terminator value
1623 (determined by the first argument) after the last element of the list. Note
1624 that the terminator must not occur in the marshalled list if it should be
1625 possible to extract the list with \code{peekArray0}.
1626
1627 \item[newArray~~::\ Storable a => {[a]} -> IO (Ptr a)]
1628 \item[withArray~::\ Storable a => {[a]} -> (Ptr a -> IO b) -> IO b]\combineitems
1629 These two functions combine \code{mallocArray} and \code{allocaArray},
1630 respectively, with \code{pokeArray}; i.e., they allocate a memory area for
1631 an array whose length matches that of the list, and then, marshal the list
1632 into that memory area.
1633
1634 \item[newArray0~~::\ Storable a => a -> {[a]} -> IO (Ptr a)]
1635 \item[withArray0~::\ Storable a => a -> {[a]} -> (Ptr a -> IO b) -> IO b]\combineitems
1636 These two functions combine \code{mallocArray0} and \code{allocaArray0},
1637 respectively, with the function \code{pokeArray0}; i.e., they allocate a
1638 memory area for
1639 an array whose length matches that of the list, and then, marshal the list
1640 into that memory area. The first argument determines the terminator.
1641
1642 \item[copyArray ::\ Storable a => Ptr a -> Ptr a -> Int -> IO ()]
1643 \item[moveArray ::\ Storable a => Ptr a -> Ptr a -> Int -> IO ()]\combineitems
1644 These two functions copy entire arrays and behave like the routines
1645 \code{MarshalUtils.copyBytes} and \code{MarshalUtils.moveBytes},
1646 respectively (Section~\ref{sec:MarshalUtils}). In particular,
1647 \code{moveArray} allows the source and destination array to overlap, whereas
1648 \code{copyArray} does not allow overlapping arrays. Both functions take a
1649 reference to the destination array as their first, and a reference to the
1650 source as their second argument. However, in contrast to the routines from
1651 \code{MarshalUtils} the third argument here specifies the number of array
1652 elements (whose type is specified by the parametrised pointer arguments)
1653 instead of the number of bytes to copy.
1654
1655 \item[lengthArray0 ::\ (Storable a, Eq a) => a -> Ptr a -> IO Int] Determine
1656 the length of an array whose end is marked by the first occurrence of the
1657 given terminator (first argument). The length is measured in array elements
1658 (not bytes) and does not include the terminator.
1659
1660 \item[advancePtr ::\ Storable a => Ptr a -> Int -> Ptr a] Advance a reference
1661 to an array by as many array elements (not bytes) as specified.
1662 \end{codedesc}
1663
1664 \subsection{\code{MarshalError}}
1665 \label{sec:MarshalError}
1666
1667 The module \code{MarshalError} provides language independent routines for
1668 converting error conditions of external functions into Haskell \code{IO} monad
1669 exceptions. It consists out of two parts. The first part extends the I/O
1670 error facilities of the \code{IO} module of the Haskell 98 Library Report with
1671 functionality to construct I/O errors. The second part provides a set of
1672 functions that ease turning exceptional result values into I/O errors.
1673
1674 \subsubsection{I/O Errors}
1675 %
1676 The following functions can be used to construct values of type
1677 \code{IOError}.
1678 %
1679 \begin{codedesc}
1680 \item[data IOErrorType] This is an abstract type that contains a value for
1681 each variant of \code{IOError}.
1682
1683 \item[mkIOError ::\ IOErrorType -> String -> Maybe Handle -> Maybe FilePath
1684 -> IOError] Construct an \code{IOError} of the given type where the second
1685 argument describes the error location and the third and fourth argument
1686 contain the file handle and file path of the file involved in the error if
1687 applicable.
1688
1689 \item[alreadyExistsErrorType ::\ IOErrorType] I/O error where the operation
1690 failed because one of its arguments already exists.
1691
1692 \item[doesNotExistErrorType ::\ IOErrorType] I/O error where the operation
1693 failed because one of its arguments does not exist.
1694
1695 \item[alreadyInUseErrorType ::\ IOErrorType] I/O error where the operation
1696 failed because one of its arguments is a single-use resource, which is
1697 already being used.
1698
1699 \item[fullErrorType ::\ IOErrorType] I/O error where the operation failed
1700 because the device is full.
1701
1702 \item[eofErrorType ::\ IOErrorType] I/O error where the operation failed
1703 because the end of file has been reached.
1704
1705 \item[illegalOperationType ::\ IOErrorType] I/O error where the operation is
1706 not possible.
1707
1708 \item[permissionErrorType ::\ IOErrorType] I/O error where the operation failed
1709 because the user does not have sufficient operating system privilege to
1710 perform that operation.
1711
1712 \item[userErrorType ::\ IOErrorType] I/O error that is programmer-defined.
1713
1714 \item[annotateIOError ::\ IOError -> String -> Maybe Handle -> Maybe
1715 FilePath -> IOError] Adds a location description and maybe a file path and
1716 file handle to an I/O error. If any of the file handle or file path is not
1717 given the corresponding value in the I/O error remains unaltered.
1718 \end{codedesc}
1719
1720 \subsubsection{Result Value Checks}
1721
1722 The following routines are useful for testing return values and raising an I/O
1723 exception in case of values indicating an error state.
1724 %
1725 \begin{codedesc}
1726 \item[throwIf ::\ (a -> Bool) -> (a -> String) -> IO a -> IO a] Execute the
1727 computation determined by the third argument. If the predicate provided in
1728 the first argument yields \code{True} when applied to the result of that
1729 computation, raise an \code{IO} exception that includes an error message
1730 obtained by applying the second argument to the result of the computation.
1731 If no exception is raised, the result of the computation is the result of
1732 the whole operation.
1733
1734 \item[throwIf\us ::\ (a -> Bool) -> (a -> String) -> IO a -> IO ()]
1735 Operate as \code{throwIf} does, but discard the result of the computation
1736 in any case.
1737
1738 \item[throwIfNeg~~::\ (Ord a, Num a) => (a -> String) -> IO a -> IO a]
1739 \item[throwIfNeg\us~::\ (Ord a, Num a) => (a -> String) -> IO a -> IO ()]\combineitems
1740 These two functions are instances of \code{throwIf} and \code{throwIf\us},
1741 respectively, where the predicate is \code{(< 0)}.
1742
1743 \item[throwIfNull ::\ String -> IO (Ptr a) -> IO (Ptr a)] This is an instance
1744 of \code{throwIf}, where the predicate is \code{(== Ptr.nullPtr)} and the
1745 error message is constant.
1746
1747 \item[void ::\ IO a -> IO ()]
1748 Discard the result of a computation.
1749 \end{codedesc}
1750
1751 \subsection{\code{MarshalUtils}}
1752 \label{sec:MarshalUtils}
1753
1754 Finally, the module \code{MarshalUtils} provides a set of useful auxiliary
1755 routines.
1756 %
1757 \begin{codedesc}
1758 \item[new ::\ Storable a => a -> IO (Ptr a)] This function first applies
1759 \code{MarshalAlloc.malloc} (Section~\ref{sec:MarshalAlloc}) to its
1760 argument, and then, stores the argument in the newly allocated memory area
1761 using \code{Storable.poke} (Section~\ref{sec:Storable}).
1762
1763 \item[with ::\ Storable a => a -> (Ptr a -> IO b) -> IO b] This function is
1764 like \code{new}, but uses \code{MarshalAlloc.alloca} instead of
1765 \code{MarshalAlloc.malloc}.
1766
1767 \item[fromBool~::\ Num a => Bool -> a]
1768 \item[toBool~~~::\ Num a => a -> Bool]\combineitems These two functions
1769 implement conversions between Haskell Boolean values and numeric
1770 representations of Boolean values, where \code{False} is represented by
1771 \code{0} and \code{True} by any non-zero value.
1772
1773 \item[maybeNew ::\ (a -> IO (Ptr a)) -> (Maybe a -> IO (Ptr a))]
1774 Lift a function that marshals a value of type \code{a} to a function that
1775 marshals a value of type \code{Maybe a}. In case, where the latter is
1776 \code{Nothing}, return \code{Ptr.nullPtr} (Section~\ref{sec:Ptr})
1777
1778 \item[maybeWith ::\ (a -> (Ptr b -> IO c) -> IO c)%
1779 -> (Maybe a -> (Ptr b -> IO c) -> IO c)] This function lifts a
1780 \code{MarshalAlloc.alloca} based marshalling function for \code{a} to
1781 \code{Maybe a}. It marshals values \code{Nothing} in the same way as
1782 \code{maybeNew}.
1783
1784 \item[maybePeek ::\ (Ptr a -> IO b) -> (Ptr a -> IO (Maybe b))] Given a
1785 function that marshals a value stored in the referenced memory area to a
1786 value of type \code{b}, lift it to producing a value of type \code{Maybe b}.
1787 If the pointer is \code{Ptr.nullPtr}, produce \code{Nothing}.
1788
1789 % Move to `Data.List.withMany' in new library spec.
1790 %\item[withMany ::\ (a -> (b -> res) -> res) -> {[a]} -> ({[b]} -> res) -> res]
1791 % Lift a marshalling function of the \code{with} family to operate on a list
1792 % of values.
1793
1794 \item[copyBytes ::\ Ptr a -> Ptr a -> Int -> IO ()]
1795 \item[moveBytes ::\ Ptr a -> Ptr a -> Int -> IO ()]\combineitems These two
1796 functions are Haskell variants of the standard C library routines
1797 \code{memcpy()} and \code{memmove()}, respectively. As with their C
1798 counterparts, \code{moveBytes} allows the source and destination array to
1799 overlap, whereas \code{copyBytes} does not allow overlapping areas. Both
1800 functions take a reference to the destination area as their first, and a
1801 reference to the source as their second argument---i.e., the argument order
1802 is as in an assignment.
1803 \end{codedesc}
1804
1805 \newpage
1806 \section{C-Specific Marshalling}
1807 \label{sec:c-marshalling}
1808
1809 \subsection{\code{CForeign}}
1810 \label{sec:CForeign}
1811
1812 The module \code{CForeign} combines the interfaces of all modules providing
1813 C-specific marshalling support. The modules are \code{CTypes},
1814 \code{CString}, and \code{CError}.
1815
1816 \begin{table}
1817 \begin{center}
1818 \begin{tabular}{|l|l|l|}
1819 \hline
1820 C symbol & Haskell symbol & Constraint on concrete C type\\
1821 \hline\hline
1822 \code{HsChar} & \code{Char}
1823 & integral type\\
1824 \hline
1825 \code{HsInt} & \code{Int}
1826 & signed integral type, $\geq30$ bit\\
1827 \hline
1828 \code{HsInt8} & \code{Int8}
1829 & signed integral type, 8 bit; \code{int8\_t} if available\\
1830 \hline
1831 \code{HsInt16} & \code{Int16}
1832 & signed integral type, 16 bit; \code{int16\_t} if available\\
1833 \hline
1834 \code{HsInt32} & \code{Int32}
1835 & signed integral type, 32 bit; \code{int32\_t} if available\\
1836 \hline
1837 \code{HsInt64} & \code{Int64}
1838 & signed integral type, 64 bit; \code{int64\_t} if available\\
1839 \hline
1840 \code{HsWord8} & \code{Word8}
1841 & unsigned integral type, 8 bit; \code{uint8\_t} if available\\
1842 \hline
1843 \code{HsWord16} & \code{Word16}
1844 & unsigned integral type, 16 bit; \code{uint16\_t} if available\\
1845 \hline
1846 \code{HsWord32} & \code{Word32}
1847 & unsigned integral type, 32 bit; \code{uint32\_t} if available\\
1848 \hline
1849 \code{HsWord64} & \code{Word64}
1850 & unsigned integral type, 64 bit; \code{uint64\_t} if available\\
1851 \hline
1852 \code{HsFloat} & \code{Float}
1853 & floating point type\\
1854 \hline
1855 \code{HsDouble} & \code{Double}
1856 & floating point type\\
1857 \hline
1858 \code{HsBool} & \code{Bool}
1859 & \code{int}\\
1860 \hline
1861 \code{HsPtr} & \code{Ptr a}
1862 & \code{(void *)}\\
1863 \hline
1864 \code{HsFunPtr} & \code{FunPtr a}
1865 & \code{(void (*)(void))}\\
1866 \hline
1867 \code{HsForeignPtr}& \code{ForeignPtr a}
1868 & \code{(void *)}\\
1869 \hline
1870 \code{HsStablePtr}& \code{StablePtr a}
1871 & \code{(void *)}\\
1872 \hline
1873 \end{tabular}
1874 \caption{C Interface to Basic Haskell Types}
1875 \label{tab:c-haskell-types}
1876 \end{center}
1877 \end{table}
1878 %
1879 \begin{table}
1880 \begin{center}
1881 % \begin{tabular}{|l|l|l|}
1882 \begin{tabular}{|l|l|p{30ex}|}
1883 \hline
1884 CPP symbol & Haskell value & Description\\
1885 \hline\hline
1886 \code{HS\_CHAR\_MIN} & \code{minBound ::\ Char}
1887 & \\
1888 \hline
1889 \code{HS\_CHAR\_MAX} & \code{maxBound ::\ Char}
1890 & \\
1891 \hline
1892 \code{HS\_INT\_MIN} & \code{minBound ::\ Int}
1893 & \\
1894 \hline
1895 \code{HS\_INT\_MAX} & \code{maxBound ::\ Int}
1896 & \\
1897 \hline
1898 \code{HS\_INT8\_MIN} & \code{minBound ::\ Int8}
1899 & \\
1900 \hline
1901 \code{HS\_INT8\_MAX} & \code{maxBound ::\ Int8}
1902 & \\
1903 \hline
1904 \code{HS\_INT16\_MIN} & \code{minBound ::\ Int16}
1905 & \\
1906 \hline
1907 \code{HS\_INT16\_MAX} & \code{maxBound ::\ Int16}
1908 & \\
1909 \hline
1910 \code{HS\_INT32\_MIN} & \code{minBound ::\ Int32}
1911 & \\
1912 \hline
1913 \code{HS\_INT32\_MAX} & \code{maxBound ::\ Int32}
1914 & \\
1915 \hline
1916 \code{HS\_INT64\_MIN} & \code{minBound ::\ Int64}
1917 & \\
1918 \hline
1919 \code{HS\_INT64\_MAX} & \code{maxBound ::\ Int64}
1920 & \\
1921 \hline
1922 \code{HS\_WORD8\_MAX} & \code{maxBound ::\ Word8}
1923 & \\
1924 \hline
1925 \code{HS\_WORD16\_MAX} & \code{maxBound ::\ Word16}
1926 & \\
1927 \hline
1928 \code{HS\_WORD32\_MAX} & \code{maxBound ::\ Word32}
1929 & \\
1930 \hline
1931 \code{HS\_WORD64\_MAX} & \code{maxBound ::\ Word64}
1932 & \\
1933 \hline
1934 \code{HS\_FLOAT\_RADIX} & \code{floatRadix ::\ Float}
1935 & \\
1936 \hline
1937 \code{HS\_FLOAT\_ROUND} & n/a
1938 & rounding style as per~\cite{C99}\\
1939 \hline
1940 \code{HS\_FLOAT\_EPSILON} & n/a
1941 & difference between 1 and the least value greater
1942 than 1 as per~\cite{C99}\\
1943 \hline
1944 \code{HS\_DOUBLE\_EPSILON} & n/a
1945 & (as above)\\
1946 \hline
1947 \code{HS\_FLOAT\_DIG} & n/a
1948 & number of decimal digits as per~\cite{C99}\\
1949 \hline
1950 \code{HS\_DOUBLE\_DIG} & n/a
1951 & (as above)\\
1952 \hline
1953 \code{HS\_FLOAT\_MANT\_DIG} & \code{floatDigits ::\ Float}
1954 & \\
1955 \hline
1956 \code{HS\_DOUBLE\_MANT\_DIG} & \code{floatDigits ::\ Double}
1957 & \\
1958 \hline
1959 \code{HS\_FLOAT\_MIN} & n/a
1960 & minimum floating point number as per~\cite{C99}\\
1961 \hline
1962 \code{HS\_DOUBLE\_MIN} & n/a
1963 & (as above)\\
1964 \hline
1965 \code{HS\_FLOAT\_MIN\_EXP} & \code{fst .\ floatRange ::\ Float}
1966 & \\
1967 \hline
1968 \code{HS\_DOUBLE\_MIN\_EXP} & \code{fst .\ floatRange ::\ Double}
1969 & \\
1970 \hline
1971 \code{HS\_FLOAT\_MIN\_10\_EXP} & n/a
1972 & minimum decimal exponent as per~\cite{C99}\\
1973 \hline
1974 \code{HS\_DOUBLE\_MIN\_10\_EXP} & n/a
1975 & (as above)\\
1976 \hline
1977 \code{HS\_FLOAT\_MAX} & n/a
1978 & maximum floating point number as per~\cite{C99}\\
1979 \hline
1980 \code{HS\_DOUBLE\_MAX} & n/a
1981 & (as above)\\
1982 \hline
1983 \code{HS\_FLOAT\_MAX\_EXP} & \code{snd .\ floatRange ::\ Float}
1984 & \\
1985 \hline
1986 \code{HS\_DOUBLE\_MAX\_EXP} & \code{snd .\ floatRange ::\ Double}
1987 & \\
1988 \hline
1989 \code{HS\_FLOAT\_MAX\_10\_EXP} & n/a
1990 & maximum decimal exponent as per~\cite{C99}\\
1991 \hline
1992 \code{HS\_DOUBLE\_MAX\_10\_EXP} & n/a
1993 & (as above)\\
1994 \hline
1995 \code{HS\_BOOL\_FALSE} & False
1996 & \\
1997 \hline
1998 \code{HS\_BOOL\_TRUE} & True
1999 & \\
2000 \hline
2001 \end{tabular}
2002 \caption{C Interface to Range and Precision of Basic Types}
2003 \label{tab:c-haskell-values}
2004 \end{center}
2005 \end{table}
2006 %
2007 Every Haskell system that implements the FFI needs to provide a C header file
2008 named \code{HsFFI.h} that defines the C symbols listed in
2009 Tables~\ref{tab:c-haskell-types} and~\ref{tab:c-haskell-values}.
2010 Table~\ref{tab:c-haskell-types} table lists symbols that represent types
2011 together with the Haskell type that they represent and any constraints that
2012 are placed on the concrete C types that implement these symbols. When a C
2013 type \code{HsT} represents a Haskell type \code{T}, the occurrence of \code{T}
2014 in a foreign function declaration should be matched by \code{HsT} in the
2015 corresponding C function prototype. Indeed, where the Haskell system
2016 translates Haskell to C code that invokes \code{foreign} \code{import}ed C
2017 routines, such prototypes need to be provided and included via the header that
2018 can be specified in external entity strings for foreign C functions (cf.\
2019 Section~\ref{sec:ccall}); otherwise, the system behaviour is undefined. It is
2020 guaranteed that the Haskell value \code{nullPtr} is mapped to \code{(HsPtr)
2021 NULL} in C and \code{nullFunPtr} is mapped to \code{(HsFunPtr) NULL} and
2022 vice versa.
2023
2024 Table~\ref{tab:c-haskell-values} contains symbols characterising the range and
2025 precision of the types from Table~\ref{tab:c-haskell-types}. Where available,
2026 the table states the corresponding Haskell values. All C symbols, with the
2027 exception of \code{HS\_FLOAT\_ROUND} are constants that are suitable for use in
2028 \code{\#if} preprocessing directives. Note that there is only one rounding
2029 style (\code{HS\_FLOAT\_ROUND}) and one radix (\code{HS\_FLOAT\_RADIX}), as
2030 this is all that is supported by ISO C~\cite{C99}.
2031
2032 Moreover, an implementation that does not support 64 bit integral types on the
2033 C side should implement \code{HsInt64} and \code{HsWord64} as a structure. In
2034 this case, the bounds \code{HS\_INT64\_MIN}, \code{HS\_INT64\_MAX}, and
2035 \code{HS\_WORD64\_MAX} are undefined.
2036
2037 In addition, to the symbols from Table~\ref{tab:c-haskell-types}
2038 and~\ref{tab:c-haskell-values}, the header \code{HsFFI.h} must also contain
2039 the following prototypes:
2040 %
2041 \begin{quote}
2042 \begin{verbatim}
2043 void hs_init (int *argc, char **argv[]);
2044 void hs_exit (void);
2045 void hs_set_argv (int argc, char *argv[]);
2046
2047 void hs_perform_gc (void);
2048
2049 void hs_free_stable_ptr (HsStablePtr sp);
2050 void hs_free_fun_ptr (HsFunPtr fp);
2051 \end{verbatim}
2052 \end{quote}
2053 %
2054 These routines are useful for mixed language programs, where the main
2055 application is implemented in a foreign language that accesses routines
2056 implemented in Haskell. The function \code{hs\_init()} initialises the
2057 Haskell system and provides it with the available command line arguments.
2058 Upon return, the arguments solely intended for the Haskell runtime system are
2059 removed (i.e., the values that \code{argc} and \code{argv} point to may have
2060 changed). This function must be called during program startup before any
2061 Haskell function is invoked; otherwise, the system behaviour is undefined.
2062 Conversely, the Haskell system is deinitialised by a call to
2063 \code{hs\_exit()}. Multiple invocations of \code{hs\_init()} are permitted,
2064 provided that they are followed by an equal number of calls to
2065 \code{hs\_exit()} and that the first call to \code{hs\_exit()} is after the
2066 last call to \code{hs\_init()}. In addition to nested calls to
2067 \code{hs\_init()}, the Haskell system may be de-initialised with
2068 \code{hs\_exit()} and be re-initialised with \code{hs\_init()} at a later
2069 point in time. This ensures that repeated initialisation due to multiple
2070 libraries being implemented in Haskell is covered.
2071
2072 The Haskell system will ignore the command line arguments passed to the second
2073 and any following calls to \code{hs\_init()}. Moreover, \code{hs\_init()} may
2074 be called with \code{NULL} for both \code{argc} and \code{argv}, signalling
2075 the absence of command line arguments.
2076
2077 The function \code{hs\_set\_argv()} sets the values returned by the functions
2078 \code{getProgName} and \code{getArgs} of the module \code{System} defined in
2079 the Haskell 98 Library Report. This function may only be invoked after
2080 \code{hs\_init()}. Moreover, if \code{hs\_set\_argv()} is called at all, this
2081 call must precede the first invocation of \code{getProgName} and
2082 \code{getArgs}. Note that the separation of \code{hs\_init()} and
2083 \code{hs\_set\_argv()} is essential in cases where in addition to the Haskell
2084 system other libraries that process command line arguments during
2085 initialisation are used.
2086
2087 The function \code{hs\_perform\_gc()} advises the Haskell storage manager to
2088 perform a garbage collection, where the storage manager makes an effort to
2089 releases all unreachable objects. This function must not be invoked from C
2090 functions that are imported \code{unsafe} into Haskell code nor may it be used
2091 from a finalizer.
2092
2093 Finally, \code{hs\_free\_stable\_ptr()} and \code{hs\_free\_fun\_ptr()} are
2094 the C counterparts of the Haskell functions \code{freeStablePtr} and
2095 \code{freeHaskellFunPtr}.
2096 \subsection{\code{CTypes}}
2097 \label{sec:CTypes}
2098
2099 The modules \code{CTypes} provide Haskell types that represent basic C types.
2100 They are needed to accurately represent C function prototypes, and so, to
2101 access C library interfaces in Haskell. The Haskell system is not required to
2102 represent those types exactly as C does, but the following guarantees are
2103 provided concerning a Haskell type \code{CT} representing a C type \code{t}:
2104 %
2105 \begin{itemize}
2106 \item If a C function prototype has \code{t} as an argument or result type,
2107 the use of \code{CT} in the corresponding position in a foreign declaration
2108 permits the Haskell program to access the full range of values encoded by
2109 the C type; and conversely, any Haskell value for \code{CT} has a valid
2110 representation in C.
2111 \item \code{Storable.sizeOf (undefined ::\ T)} will yield the same value as
2112 \code{sizeof (t)} in C.
2113 \item \code{Storable.alignment (undefined ::\ T)} matches the alignment
2114 constraint enforced by the C implementation for \code{t}.
2115 \item \code{Storable.peek} and \code{Storable.poke} map all values of
2116 \code{CT} to the corresponding value of \code{t} and vice versa.
2117 \item When an instance of \code{Bounded} is defined for \code{CT}, the values
2118 of \code{minBound} and \code{maxBound} coincide with \code{t\_MIN} and
2119 \code{t\_MAX} in C.
2120 \item When an instance of \code{Eq} or \code{Ord} is defined for \code{CT},
2121 the predicates defined by the type class implement the same relation as the
2122 corresponding predicate in C on \code{t}.
2123 \item When an instance of \code{Num}, \code{Read}, \code{Integral},
2124 \code{Fractional}, \code{Floating}, \code{RealFrac}, or \code{RealFloat} is
2125 defined for \code{CT}, the arithmetic operations defined by the type class
2126 implement the same function as the corresponding arithmetic operations (if
2127 available) in C on \code{t}.
2128 \item When an instance of \code{Bits} is defined for \code{CT}, the bitwise
2129 operation defined by the type class implement the same function as the
2130 corresponding bitwise operation in C on \code{t}.
2131 \end{itemize}
2132 %
2133 It follows from these guarantees that all types exported by \code{CTypes} are
2134 represented as type synonyms or \code{newtype}s of basic foreign types as
2135 defined in Section~\ref{sec:foreign-types}.
2136
2137 The module \code{CTypes} provides the following integral types, including
2138 instances for \code{Eq}, \code{Ord}, \code{Num}, \code{Read}, \code{Show},
2139 \code{Enum}, \code{Storable}, \code{Bounded}, \code{Real}, \code{Integral},
2140 and \code{Bits}:
2141 %
2142 \begin{quote}
2143 \begin{tabular}{|l|l|l|}
2144 \hline
2145 Haskell type & Represented C type\\\hline\hline
2146 \code{CChar} & \code{char}\\\hline
2147 \code{CSChar} & \code{signed char}\\\hline
2148 \code{CUChar} & \code{unsigned char}\\\hline
2149 \code{CShort} & \code{short}\\\hline
2150 \code{CUShort} & \code{unsigned short}\\\hline
2151 \code{CInt} & \code{int}\\\hline
2152 \code{CUInt} & \code{unsigned int}\\\hline
2153 \code{CLong} & \code{long}\\\hline
2154 \code{CULong} & \code{unsigned long}\\\hline
2155 \code{CLLong} & \code{long long}\\\hline
2156 \code{CULLong} & \code{unsigned long long}\\\hline
2157 \end{tabular}
2158 \end{quote}
2159 %
2160 Moreover, it provides the following floating point types, including instances
2161 for \code{Eq}, \code{Ord}, \code{Num}, \code{Read}, \code{Show}, \code{Enum},
2162 \code{Storable}, \code{Real}, \code{Fractional}, \code{Floating},
2163 \code{RealFrac}, and \code{RealFloat}:
2164 %
2165 \begin{quote}
2166 \begin{tabular}{|l|l|l|}
2167 \hline
2168 Haskell type & Represented C type\\\hline\hline
2169 \code{CFloat} & \code{float}\\\hline
2170 \code{CDouble} & \code{double}\\\hline
2171 \code{CLDouble} & \code{long double}\\\hline
2172 \end{tabular}
2173 \end{quote}
2174 %
2175 The module provides the following integral types, including instances for
2176 \code{Eq}, \code{Ord}, \code{Num}, \code{Read}, \code{Show}, \code{Enum},
2177 \code{Storable}, \code{Bounded}, \code{Real}, \code{Integral}, and
2178 \code{Bits}:
2179 %
2180 \begin{quote}
2181 \begin{tabular}{|l|l|l|}
2182 \hline
2183 Haskell type & Represented C type\\\hline\hline
2184 \code{CPtrdiff} & \code{ptrdiff\_t}\\\hline
2185 \code{CSize} & \code{size\_t}\\\hline
2186 \code{CWChar} & \code{wchar\_t}\\\hline
2187 \code{CSigAtomic}& \code{sig\_atomic\_t}\\\hline
2188 \end{tabular}
2189 \end{quote}
2190 %
2191 Moreover, it provides the following numeric types, including instances for
2192 \code{Eq}, \code{Ord}, \code{Num}, \code{Read}, \code{Show}, \code{Enum}, and
2193 \code{Storable}:
2194 %
2195 \begin{quote}
2196 \begin{tabular}{|l|l|l|}
2197 \hline
2198 Haskell type & Represented C type\\\hline\hline
2199 \code{CClock} & \code{clock\_t}\\\hline
2200 \code{CTime} & \code{time\_t}\\\hline
2201 \end{tabular}
2202 \end{quote}
2203 %
2204 And finally, the following types, including instances for \code{Eq} and
2205 \code{Storable}, are provided:
2206 %
2207 \begin{quote}
2208 \begin{tabular}{|l|l|l|}
2209 \hline
2210 Haskell type & Represented C type\\\hline\hline
2211 \code{CFile} & \code{FILE}\\\hline
2212 \code{CFpos} & \code{fpos\_t}\\\hline
2213 \code{CJmpBuf} & \code{jmp\_buf}\\\hline
2214 \end{tabular}
2215 \end{quote}
2216
2217 \subsection{\code{CString}}
2218 \label{sec:CString}
2219
2220 The module \code{CString} provides routines marshalling Haskell into C strings
2221 and vice versa. The marshalling takes the current Unicode encoding on the
2222 Haskell side into account. As a consequence, no guarantees can be made about
2223 the relative length of a Haskell string and its corresponding C string, and
2224 therefore, all routines provided by \code{CString} combine memory allocation
2225 and marshalling.
2226 %
2227 \begin{codedesc}
2228 \item[type CString = Ptr CChar] A C string is a reference to an array of C
2229 characters terminated by NUL.
2230
2231 \item[type CStringLen = (CString, Int)] In addition to NUL-terminated strings,
2232 the module \code{CString} also supports strings with explicit length
2233 information.
2234
2235 \item[peekCString~~~~::\ CString~~~~-> IO String]
2236 \item[peekCStringLen~::\ CStringLen~-> IO String]\combineitems
2237 Marshal a C string to Haskell. There are two variants of the routine, one
2238 for each supported string representation.
2239
2240 \item[newCString~~~~::\ String -> IO CString]
2241 \item[newCStringLen~::\ String -> IO CStringLen] \combineitems Allocate a
2242 memory area for a Haskell string and marshal the string into its C
2243 representation. There are two variants of the routine, one for each
2244 supported string representation.
2245
2246 \item[withCString~~~~::\ String -> (CString~~~~-> IO a) -> IO a]
2247 \item[withCStringLen~::\ String -> (CStringLen~-> IO a) -> IO a] \combineitems
2248 These two routines operate as \code{newCString} and \code{newCStringLen},
2249 respectively, but handle memory allocation and deallocation like
2250 \code{MarshalAlloc.alloca} (Section~\ref{sec:MarshalAlloc}).
2251
2252 \item[castCharToCChar ::\ Char -> CChar]
2253 \item[castCCharToChar ::\ CChar -> Char] \combineitems These two functions cast
2254 Haskell characters to C characters and vice versa while ignoring the Unicode
2255 encoding of the Haskell character. These functions should be used with
2256 care.
2257 \end{codedesc}
2258
2259 \subsection{\code{CError}}
2260 \label{sec:CError}
2261
2262 The module CError facilitates C-specific error handling of \code{errno}. In
2263 Haskell, we represent values of \code{errno} by
2264 %
2265 \begin{quote}
2266 \begin{verbatim}
2267 newtype Errno = Errno CInt
2268 \end{verbatim}
2269 \end{quote}
2270 %
2271 which has an instance for the type class \code{Eq}. The implementation of
2272 \code{Errno} is disclosed on purpose. Different operating systems and/or C
2273 libraries often support different values of \code{errno}. This module defines
2274 the common values, but due to the open definition of \code{Errno} users may
2275 add definitions which are not predefined. The predefined values are the
2276 following:
2277 %
2278 \begin{quote}
2279 \begin{verbatim}
2280 eOK, e2BIG, eACCES, eADDRINUSE, eADDRNOTAVAIL, eADV, eAFNOSUPPORT, eAGAIN,
2281 eALREADY, eBADF, eBADMSG, eBADRPC, eBUSY, eCHILD, eCOMM, eCONNABORTED,
2282 eCONNREFUSED, eCONNRESET, eDEADLK, eDESTADDRREQ, eDIRTY, eDOM, eDQUOT,
2283 eEXIST, eFAULT, eFBIG, eFTYPE, eHOSTDOWN, eHOSTUNREACH, eIDRM, eILSEQ,
2284 eINPROGRESS, eINTR, eINVAL, eIO, eISCONN, eISDIR, eLOOP, eMFILE, eMLINK,
2285 eMSGSIZE, eMULTIHOP, eNAMETOOLONG, eNETDOWN, eNETRESET, eNETUNREACH,
2286 eNFILE, eNOBUFS, eNODATA, eNODEV, eNOENT, eNOEXEC, eNOLCK, eNOLINK,
2287 eNOMEM, eNOMSG, eNONET, eNOPROTOOPT, eNOSPC, eNOSR, eNOSTR, eNOSYS,
2288 eNOTBLK, eNOTCONN, eNOTDIR, eNOTEMPTY, eNOTSOCK, eNOTTY, eNXIO,
2289 eOPNOTSUPP, ePERM, ePFNOSUPPORT, ePIPE, ePROCLIM, ePROCUNAVAIL,
2290 ePROGMISMATCH, ePROGUNAVAIL, ePROTO, ePROTONOSUPPORT, ePROTOTYPE,
2291 eRANGE, eREMCHG, eREMOTE, eROFS, eRPCMISMATCH, eRREMOTE, eSHUTDOWN,
2292 eSOCKTNOSUPPORT, eSPIPE, eSRCH, eSRMNT, eSTALE, eTIME, eTIMEDOUT,
2293 eTOOMANYREFS, eTXTBSY, eUSERS, eWOULDBLOCK, eXDEV
2294 :: Errno
2295 \end{verbatim}
2296 \end{quote}
2297 %
2298 The meaning of these values corresponds to that of the C constants of the same
2299 name with the leading "e" converted to upper-case.
2300
2301 The module \code{CError} provides the following functions:
2302 %
2303 \begin{codedesc}
2304 \item[isValidErrno ::\ Errno -> Bool] Yield \code{True} if the given
2305 \code{Errno} value is valid on the system. This implies that the \code{Eq}
2306 instance of \code{Errno} is also system dependent as it is only defined for
2307 valid values of \code{Errno}.
2308
2309 \item[getErrno ::\ IO Errno] Get the current value of \code{errno}.
2310
2311 \item[resetErrno ::\ IO ()] Reset \code{errno} to \code{eOK}.
2312
2313 \item[errnoToIOError ::\ String -> Errno -> Maybe Handle -> Maybe String ->
2314 IOError] Compute a Haskell 98 I/O error based on the given \code{Errno}
2315 value. The first argument to the function should specify the location where
2316 the error occurred and the third and fourth can be used to specify a file
2317 handle and filename in the course of whose manipulation the error occurred.
2318 This is optional information, which can be used to improve the accuracy of
2319 error messages.
2320
2321 \item[throwErrno ::\ String -> IO a] Apply \code{errnoToIOError} to the value
2322 currently returned by \code{getErrno}. Its first argument specifies the
2323 location---no extra information about a file handle or filename can be
2324 provided in this case.
2325
2326 \item[throwErrnoIf~~:: (a -> Bool) -> String -> IO a -> IO a]
2327 \item[throwErrnoIf\us~:: (a -> Bool) -> String -> IO a -> IO ()]\combineitems
2328 Behave like \code{throwErrno} in case that the result of the \code{IO}
2329 action fulfils the predicate passed as a first argument. The second variant
2330 discards the result after error handling.
2331
2332 \item[throwErrnoIfRetry~~:: (a -> Bool) -> String -> IO a -> IO a]
2333 \item[throwErrnoIfRetry\us~:: (a -> Bool) -> String -> IO a -> IO ()]%
2334 \combineitems Like \code{throwErrnoIf} and \code{throwErrnoIf\us}, but retry
2335 the \code{IO} action when it yields the error code \code{eINTR}---this amounts
2336 to the standard retry loop for interrupted POSIX system calls.
2337
2338 \item[throwErrnoIfMinus1~~:: Num a => String -> IO a -> IO a]
2339 \item[throwErrnoIfMinus1\us~:: Num a => String -> IO a -> IO ()]\combineitems
2340 Instantiate \code{throwErrnoIf} and \code{throwErrnoIf\us} with the predicate
2341 \code{(== -1)}.
2342
2343 \item[throwErrnoIfMinus1Retry~~:: Num a => String -> IO a -> IO a]
2344 \item[throwErrnoIfMinus1Retry\us~:: Num a => String -> IO a -> IO ()]%
2345 \combineitems Instantiate \code{throwErrnoIfRetry} and
2346 \code{throwErrnoIfRetry\us} with the predicate \code{(== -1)}.
2347
2348 \item[throwErrnoIfNull~~~~~~:: String -> IO (Ptr a) -> IO (Ptr a)]
2349 \item[throwErrnoIfNullRetry~:: String -> IO (Ptr a) -> IO (Ptr a)]%
2350 \combineitems Instantiate \code{throwErrnoIf} and \code{throwErrnoIfRetry}
2351 with the predicate \code{(== Ptr.nullPtr)}.
2352 \end{codedesc}
2353
2354
2355 \bibliographystyle{plain}
2356 \bibliography{ffi}
2357
2358 \end{document}