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