Commit 2fd7010f authored by Simon Marlow's avatar Simon Marlow
Browse files

remove old lib docs

parent b40abc54
\section{@Foreign.C.Error@}
\label{sec:CError}
The module @Foreign.C.Error@ facilitates C-specific error handling of @errno@. In
Haskell, we represent values of @errno@ by
%
\begin{quote}
\begin{verbatim}
newtype Errno = Errno CInt
\end{verbatim}
\end{quote}
%
which has an instance for the type class @Eq@. The implementation of
@Errno@ is disclosed on purpose. Different operating systems and/or C
libraries often support different values of @errno@. This module defines
the common values, but due to the open definition of @Errno@ users may
add definitions which are not predefined. The predefined values are the
following:
%
\begin{quote}
\begin{verbatim}
eOK, e2BIG, eACCES, eADDRINUSE, eADDRNOTAVAIL, eADV,
eAFNOSUPPORT, eAGAIN, eALREADY, eBADF, eBADMSG, eBADRPC,
eBUSY, eCHILD, eCOMM, eCONNABORTED, eCONNREFUSED,
eCONNRESET, eDEADLK, eDESTADDRREQ, eDIRTY, eDOM, eDQUOT,
eEXIST, eFAULT, eFBIG, eFTYPE, eHOSTDOWN, eHOSTUNREACH,
eIDRM, eILSEQ, eINPROGRESS, eINTR, eINVAL, eIO, eISCONN,
eISDIR, eLOOP, eMFILE, eMLINK, eMSGSIZE, eMULTIHOP,
eNAMETOOLONG, eNETDOWN, eNETRESET, eNETUNREACH, eNFILE,
eNOBUFS, eNODATA, eNODEV, eNOENT, eNOEXEC, eNOLCK,
eNOLINK, eNOMEM, eNOMSG, eNONET, eNOPROTOOPT, eNOSPC,
eNOSR, eNOSTR, eNOSYS, eNOTBLK, eNOTCONN, eNOTDIR,
eNOTEMPTY, eNOTSOCK, eNOTTY, eNXIO, eOPNOTSUPP, ePERM,
ePFNOSUPPORT, ePIPE, ePROCLIM, ePROCUNAVAIL,
ePROGMISMATCH, ePROGUNAVAIL, ePROTO, ePROTONOSUPPORT,
ePROTOTYPE, eRANGE, eREMCHG, eREMOTE, eROFS, eRPCMISMATCH,
eRREMOTE, eSHUTDOWN, eSOCKTNOSUPPORT, eSPIPE, eSRCH,
eSRMNT, eSTALE, eTIME, eTIMEDOUT, eTOOMANYREFS, eTXTBSY,
eUSERS, eWOULDBLOCK, eXDEV
:: Errno
\end{verbatim}
\end{quote}
%
The meaning of these values corresponds to that of the C constants of the same
name with the leading "e" converted to upper-case.
The module @Foreign.C.Error@ provides the following functions:
%
\begin{codedesc}
\item[isValidErrno ::\ Errno -> Bool] Yield @True@ if the given
@Errno@ value is valid on the system. This implies that the @Eq@
instance of @Errno@ is also system dependent as it is only defined for
valid values of @Errno@.
\item[getErrno ::\ IO Errno] Get the current value of @errno@.
\item[resetErrno ::\ IO ()] Reset @errno@ to @eOK@.
\item[errnoToIOError ::\ String -> Errno -> Maybe Handle -> Maybe String]
\item[~~~~~~~~~~~~~~~-> Maybe String -> IOError]\combineitems
Compute a Haskell I/O error based on the given @Errno@
value. The first argument to the function should specify the location where
the error occurred and the third and fourth can be used to specify a file
handle and filename in the course of whose manipulation the error occurred.
This is optional information, which can be used to improve the accuracy of
error messages.
\item[throwErrno ::\ String -> IO a] Apply @errnoToIOError@ to the value
currently returned by @getErrno@. Its first argument specifies the
location---no extra information about a file handle or filename can be
provided in this case.
\item[throwErrnoIf~~:: (a -> Bool) -> String -> IO a -> IO a]
\item[throwErrnoIf\_~:: (a -> Bool) -> String -> IO a -> IO ()]\combineitems
Behave like @throwErrno@ in case that the result of the @IO@
action fulfils the predicate passed as a first argument. The second variant
discards the result after error handling.
\item[throwErrnoIfRetry~~:: (a -> Bool) -> String -> IO a -> IO a]
\item[throwErrnoIfRetry\_~:: (a -> Bool) -> String -> IO a -> IO ()]%
\combineitems Like @throwErrnoIf@ and @throwErrnoIf_@, but retry
the @IO@ action when it yields the error code @eINTR@---this amounts
to the standard retry loop for interrupted POSIX system calls.
\item[throwErrnoIfMinus1~~:: Num a => String -> IO a -> IO a]
\item[throwErrnoIfMinus1\_~:: Num a => String -> IO a -> IO ()]\combineitems
Instantiate @throwErrnoIf@ and @throwErrnoIf_@ with the predicate
@(== -1)@.
\item[throwErrnoIfMinus1Retry~~:: Num a => String -> IO a -> IO a]
\item[throwErrnoIfMinus1Retry\_~:: Num a => String -> IO a -> IO ()]%
\combineitems Instantiate @throwErrnoIfRetry@ and
@throwErrnoIfRetry_@ with the predicate @(== -1)@.
\item[throwErrnoIfNull~~~~~~:: String -> IO (Ptr a) -> IO (Ptr a)]
\item[throwErrnoIfNullRetry~:: String -> IO (Ptr a) -> IO (Ptr a)]%
\combineitems Instantiate @throwErrnoIf@ and @throwErrnoIfRetry@
with the predicate @(== Ptr.nullPtr)@.
\end{codedesc}
\section{@Foreign.C@}
\label{sec:CForeign}
The module @Foreign.C@ combines the interfaces of all modules providing
C-specific marshalling support. The modules are @Foreign.C.Types@,
@Foreign.C.String@, and @Foreign.C.Error@.
\begin{table}
\begin{center}
\begin{tabular}{|l|l|l|}
\hline
C symbol & Haskell symbol & Constraint on concrete C type\\
\hline\hline
@HsChar@ & @Char@
& integral type\\
\hline
@HsInt@ & @Int@
& signed integral type, $\geq30$ bit\\
\hline
@HsInt8@ & @Int8@
& signed integral type, 8 bit; @int8_t@ if available\\
\hline
@HsInt16@ & @Int16@
& signed integral type, 16 bit; @int16_t@ if available\\
\hline
@HsInt32@ & @Int32@
& signed integral type, 32 bit; @int32_t@ if available\\
\hline
@HsInt64@ & @Int64@
& signed integral type, 64 bit; @int64_t@ if available\\
\hline
@HsWord8@ & @Word8@
& unsigned integral type, 8 bit; @uint8_t@ if available\\
\hline
@HsWord16@ & @Word16@
& unsigned integral type, 16 bit; @uint16_t@ if available\\
\hline
@HsWord32@ & @Word32@
& unsigned integral type, 32 bit; @uint32_t@ if available\\
\hline
@HsWord64@ & @Word64@
& unsigned integral type, 64 bit; @uint64_t@ if available\\
\hline
@HsFloat@ & @Float@
& floating point type\\
\hline
@HsDouble@ & @Double@
& floating point type\\
\hline
@HsBool@ & @Bool@
& @int@\\
\hline
@HsPtr@ & @Ptr a@
& @(void *)@\\
\hline
@HsFunPtr@ & @FunPtr a@
& @(void (*)(void))@\\
\hline
@HsStablePtr@& @StablePtr a@
& @(void *)@\\
\hline
\end{tabular}
\caption{C Interface to Basic Haskell Types}
\label{tab:c-haskell-types}
\end{center}
\end{table}
%
\begin{table}
\begin{center}
% \begin{tabular}{|l|l|l|}
\begin{tabular}{|l|l|p{30ex}|}
\hline
CPP symbol & Haskell value & Description\\
\hline\hline
@HS_CHAR_MIN@ & @minBound :: Char@
& \\
\hline
@HS_CHAR_MAX@ & @maxBound :: Char@
& \\
\hline
@HS_INT_MIN@ & @minBound :: Int@
& \\
\hline
@HS_INT_MAX@ & @maxBound :: Int@
& \\
\hline
@HS_INT8_MIN@ & @minBound :: Int8@
& \\
\hline
@HS_INT8_MAX@ & @maxBound :: Int8@
& \\
\hline
@HS_INT16_MIN@ & @minBound :: Int16@
& \\
\hline
@HS_INT16_MAX@ & @maxBound :: Int16@
& \\
\hline
@HS_INT32_MIN@ & @minBound :: Int32@
& \\
\hline
@HS_INT32_MAX@ & @maxBound :: Int32@
& \\
\hline
@HS_INT64_MIN@ & @minBound :: Int64@
& \\
\hline
@HS_INT64_MAX@ & @maxBound :: Int64@
& \\
\hline
@HS_WORD8_MAX@ & @maxBound :: Word8@
& \\
\hline
@HS_WORD16_MAX@ & @maxBound :: Word16@
& \\
\hline
@HS_WORD32_MAX@ & @maxBound :: Word32@
& \\
\hline
@HS_WORD64_MAX@ & @maxBound :: Word64@
& \\
\hline
@HS_FLOAT_RADIX@ & @floatRadix :: Float@
& \\
\hline
@HS_FLOAT_ROUND@ & n/a
& rounding style as per~\cite{C99}\\
\hline
@HS_FLOAT_EPSILON@ & n/a
& difference between 1 and the least value greater
than 1 as per~\cite{C99}\\
\hline
@HS_DOUBLE_EPSILON@ & n/a
& (as above)\\
\hline
@HS_FLOAT_DIG@ & n/a
& number of decimal digits as per~\cite{C99}\\
\hline
@HS_DOUBLE_DIG@ & n/a
& (as above)\\
\hline
@HS_FLOAT_MANT_DIG@ & @floatDigits :: Float@
& \\
\hline
@HS_DOUBLE_MANT_DIG@ & @floatDigits :: Double@
& \\
\hline
@HS_FLOAT_MIN@ & n/a
& minimum floating point number as per~\cite{C99}\\
\hline
@HS_DOUBLE_MIN@ & n/a
& (as above)\\
\hline
@HS_FLOAT_MIN_EXP@ & @fst . floatRange :: Float@
& \\
\hline
@HS_DOUBLE_MIN_EXP@ & @fst . floatRange :: Double@
& \\
\hline
@HS_FLOAT_MIN_10_EXP@ & n/a
& minimum decimal exponent as per~\cite{C99}\\
\hline
@HS_DOUBLE_MIN_10_EXP@ & n/a
& (as above)\\
\hline
@HS_FLOAT_MAX@ & n/a
& maximum floating point number as per~\cite{C99}\\
\hline
@HS_DOUBLE_MAX@ & n/a
& (as above)\\
\hline
@HS_FLOAT_MAX_EXP@ & @snd . floatRange :: Float@
& \\
\hline
@HS_DOUBLE_MAX_EXP@ & @snd . floatRange :: Double@
& \\
\hline
@HS_FLOAT_MAX_10_EXP@ & n/a
& maximum decimal exponent as per~\cite{C99}\\
\hline
@HS_DOUBLE_MAX_10_EXP@ & n/a
& (as above)\\
\hline
@HS_BOOL_FALSE@ & False
& \\
\hline
@HS_BOOL_TRUE@ & True
& \\
\hline
\end{tabular}
\caption{C Interface to Range and Precision of Basic Types}
\label{tab:c-haskell-values}
\end{center}
\end{table}
%
Every Haskell system that implements the FFI needs to provide a C header file
named @HsFFI.h@ that defines the C symbols listed in
Tables~\ref{tab:c-haskell-types} and~\ref{tab:c-haskell-values}.
Table~\ref{tab:c-haskell-types} table lists symbols that represent types
together with the Haskell type that they represent and any constraints that
are placed on the concrete C types that implement these symbols. When a C
type @HsT@ represents a Haskell type @T@, the occurrence of @T@
in a foreign function declaration should be matched by @HsT@ in the
corresponding C function prototype. Indeed, where the Haskell system
translates Haskell to C code that invokes @foreign@ @import@ed C
routines, such prototypes need to be provided and included via the header that
can be specified in external entity strings for foreign C functions (cf.\
Section~\ref{sec:ccall}); otherwise, the system behaviour is undefined. It is
guaranteed that the Haskell value @nullPtr@ is mapped to @(HsPtr) NULL@ in C and @nullFunPtr@ is mapped to @(HsFunPtr) NULL@ and
vice versa.
Table~\ref{tab:c-haskell-values} contains symbols characterising the range and
precision of the types from Table~\ref{tab:c-haskell-types}. Where available,
the table states the corresponding Haskell values. All C symbols, with the
exception of @HS_FLOAT_ROUND@ are constants that are suitable for use in
@#if@ preprocessing directives. Note that there is only one rounding
style (@HS_FLOAT_ROUND@) and one radix (@HS_FLOAT_RADIX@), as
this is all that is supported by ISO C~\cite{C99}.
Moreover, an implementation that does not support 64 bit integral types on the
C side should implement @HsInt64@ and @HsWord64@ as a structure. In
this case, the bounds @HS_INT64_MIN@, @HS_INT64_MAX@, and
@HS_WORD64_MAX@ are undefined.
In addition, to the symbols from Table~\ref{tab:c-haskell-types}
and~\ref{tab:c-haskell-values}, the header @HsFFI.h@ must also contain
the following prototypes:
%
\begin{quote}
\begin{verbatim}
void hs_init (int *argc, char **argv[]);
void hs_exit (void);
void hs_set_argv (int argc, char *argv[]);
void hs_perform_gc (void);
void hs_free_stable_ptr (HsStablePtr sp);
void hs_free_fun_ptr (HsFunPtr fp);
\end{verbatim}
\end{quote}
%
These routines are useful for mixed language programs, where the main
application is implemented in a foreign language that accesses routines
implemented in Haskell. The function @hs_init()@ initialises the
Haskell system and provides it with the available command line arguments.
Upon return, the arguments solely intended for the Haskell runtime system are
removed (i.e., the values that @argc@ and @argv@ point to may have
changed). This function must be called during program startup before any
Haskell function is invoked; otherwise, the system behaviour is undefined.
Conversely, the Haskell system is deinitialised by a call to
@hs_exit()@. Multiple invocations of @hs_init()@ are permitted,
provided that they are followed by an equal number of calls to
@hs_exit()@ and that the first call to @hs_exit()@ is after the
last call to @hs_init()@. In addition to nested calls to
@hs_init()@, the Haskell system may be de-initialised with
@hs_exit()@ and be re-initialised with @hs_init()@ at a later
point in time. This ensures that repeated initialisation due to multiple
libraries being implemented in Haskell is covered.
The Haskell system will ignore the command line arguments passed to the second
and any following calls to @hs_init()@. Moreover, @hs_init()@ may
be called with @NULL@ for both @argc@ and @argv@, signalling
the absence of command line arguments.
The function @hs_set_argv()@ sets the values returned by the functions
@getProgName@ and @getArgs@ of the module @System@ (Section~\ref{System}). This function may only be invoked after
@hs_init()@. Moreover, if @hs_set_argv()@ is called at all, this
call must precede the first invocation of @getProgName@ and
@getArgs@. Note that the separation of @hs_init()@ and
@hs_set_argv()@ is essential in cases where in addition to the Haskell
system other libraries that process command line arguments during
initialisation are used.
The function @hs_perform_gc()@ advises the Haskell storage manager to
perform a garbage collection, where the storage manager makes an effort to
releases all unreachable objects. This function must not be invoked from C
functions that are imported @unsafe@ into Haskell code nor may it be used
from a finalizer.
Finally, @hs_free_stable_ptr()@ and @hs_free_fun_ptr()@ are
the C counterparts of the Haskell functions @freeStablePtr@ and
@freeHaskellFunPtr@.
\section{@Foreign.C.String@}
\label{sec:CString}
The module @Foreign.C.String@ provides routines marshalling Haskell into C strings
and vice versa. The marshalling converts each Haskell character, representing
a Unicode code point, to one or more bytes in a manner that, by default, is
determined by the current locale. As a consequence, no guarantees can be made
about the relative length of a Haskell string and its corresponding C string,
and therefore, all routines provided by @Foreign.C.String@ combine memory
allocation and marshalling. The translation between Unicode and the encoding
of the current locale may be lossy. The function @charIsRepresentable@
identifies the characters that can be accurately translated; unrepresentable
characters are converted to `?'.
%
\begin{codedesc}
\item[type CString = Ptr CChar] A C string is a reference to an array of C
characters terminated by NUL.
\item[type CStringLen = (Ptr CChar, Int)] In addition to NUL-terminated
strings, the module @Foreign.C.String@ also supports strings with explicit
length information in bytes.
\item[peekCString~~~~::\ CString~~~~-> IO String]
\item[peekCStringLen~::\ CStringLen~-> IO String]\combineitems
Marshal a C string to Haskell. There are two variants of the routine, one
for each supported string representation.
\item[newCString~~~~::\ String -> IO CString]
\item[newCStringLen~::\ String -> IO CStringLen] \combineitems Allocate a
memory area for a Haskell string and marshal the string into its C
representation. There are two variants of the routine, one for each
supported string representation. The memory area allocated by these
routines may be deallocated using @Foreign.Marshal.Alloc.free@.
\item[withCString~~~~::\ String -> (CString~~~~-> IO a) -> IO a]
\item[withCStringLen~::\ String -> (CStringLen~-> IO a) -> IO a] \combineitems
These two routines operate as @newCString@ and @newCStringLen@,
respectively, but handle memory allocation and deallocation like
@Foreign.Marshal.Alloc.alloca@ (Section~\ref{sec:MarshalAlloc}).
\item[charIsRepresentable ::\ Char -> IO Bool] Determine whether the argument
can be represented in the current locale.
\end{codedesc}
Some C libraries require to ignore the Unicode capabilities of Haskell and
treat values of type @Char@ as single byte characters. Hence, the module
@CString@ provides a variant of the above marshalling routines that
truncates character sets correspondingly. These functions should be used with
care, as a loss of information can occur.
%
\begin{codedesc}
\item[castCharToCChar ::\ Char -> CChar]
\item[castCCharToChar ::\ CChar -> Char] \combineitems These two functions cast
Haskell characters to C characters and vice versa while ignoring the Unicode
encoding of the Haskell character. More precisely, only the first 256
character points are preserved.
\item[peekCAString~~~~::\ CString~~~~-> IO String]
\item[peekCAStringLen~::\ CStringLen~-> IO String]\combineitems
\item[newCAString~~~~~::\ String -> IO CString]\combineitems
\item[newCAStringLen~~::\ String -> IO CStringLen] \combineitems
\item[withCAString~~~~::\ String -> (CString~~~~-> IO a) -> IO a]\combineitems
\item[withCAStringLen~::\ String -> (CStringLen~-> IO a) -> IO a]
\combineitems These functions for whole-string marshalling cast Haskell
characters to C characters and vice versa while ignoring the Unicode
encoding of Haskell characters.
\end{codedesc}
To simplify bindings to C libraries that use @wchar_t@ for character
sets that cannot be encoded in byte strings, the module @Foreign.C.String@ also
exports a variant of the above string marshalling routines for wide
characters---i.e., for the C @wchar_t@ type.\footnote{Note that if the
platform defines @__STDC_ISO_10646__@ then @wchar_t@
characters are Unicode code points, and thus, the conversion between Haskell
@Char@ and @CWchar@ is a simple cast. On other platforms, the
translation is locale-dependent, just as for @CChar@.}
%
\begin{codedesc}
\item[type CWString~~~~= Ptr CWchar]
\item[type CWStringLen~= (Ptr CWchar, Int)] \combineitems
Wide character strings in a NUL-terminated version and a variant with
explicit length information in number of wide characters.
\item[peekCWString~~~~::\ CWString~~~~-> IO String]
\item[peekCWStringLen~::\ CWStringLen~-> IO String]\combineitems
\item[newCWString~~~~~::\ String -> IO CWString]\combineitems
\item[newCWStringLen~~::\ String -> IO CWStringLen] \combineitems
\item[withCWString~~~~::\ String -> (CWString~~~~-> IO a) -> IO a]\combineitems
\item[withCWStringLen~::\ String -> (CWStringLen~-> IO a) -> IO a]
\combineitems String marshalling for wide character strings. The interface
is the same as for byte strings.
\end{codedesc}
\section{@Foreign.C.Types@}
\label{sec:CTypes}
The modules @Foreign.C.Types@ provide Haskell types that represent basic C types.
They are needed to accurately represent C function prototypes, and so, to
access C library interfaces in Haskell. The Haskell system is not required to
represent those types exactly as C does, but the following guarantees are
provided concerning a Haskell type @CT@ representing a C type @t@:
%
\begin{itemize}
\item If a C function prototype has @t@ as an argument or result type,
the use of @CT@ in the corresponding position in a foreign declaration
permits the Haskell program to access the full range of values encoded by
the C type; and conversely, any Haskell value for @CT@ has a valid
representation in C.
\item @Foreign.Storable.sizeOf (undefined :: CT)@ will yield the same value as
@sizeof (t)@ in C.
\item @Foreign.Storable.alignment (undefined :: CT)@ matches the alignment
constraint enforced by the C implementation for @t@.
\item @Foreign.Storable.peek@ and @Foreign.Storable.poke@ map all values of
@CT@ to the corresponding value of @t@ and vice versa.
\item When an instance of @Bounded@ is defined for @CT@, the values
of @minBound@ and @maxBound@ coincide with @t_MIN@ and
@t_MAX@ in C.
\item When an instance of @Eq@ or @Ord@ is defined for @CT@,
the predicates defined by the type class implement the same relation as the
corresponding predicate in C on @t@.
\item When an instance of @Num@, @Read@, @Integral@,
@Fractional@, @Floating@, @RealFrac@, or @RealFloat@ is
defined for @CT@, the arithmetic operations defined by the type class
implement the same function as the corresponding arithmetic operations (if
available) in C on @t@.
\item When an instance of @Bits@ is defined for @CT@, the bitwise
operation defined by the type class implement the same function as the
corresponding bitwise operation in C on @t@.
\end{itemize}
%
All types exported by @Foreign.C.Types@ must be represented as @newtype@s of
basic foreign types as defined in Section~\ref{sec:foreign-types} and the
export must be abstract.
The module @Foreign.C.Types@ provides the following integral types, including
instances for @Eq@, @Ord@, @Num@, @Read@, @Show@,
@Enum@, @Storable@, @Bounded@, @Real@, @Integral@,
and @Bits@:
%
\begin{quote}
\begin{tabular}{|l|l|l|}
\hline
Haskell type & Represented C type\\\hline\hline
@CChar@ & @char@\\\hline
@CSChar@ & @signed char@\\\hline
@CUChar@ & @unsigned char@\\\hline
@CShort@ & @short@\\\hline
@CUShort@ & @unsigned short@\\\hline
@CInt@ & @int@\\\hline
@CUInt@ & @unsigned int@\\\hline
@CLong@ & @long@\\\hline
@CULong@ & @unsigned long@\\\hline
@CLLong@ & @long long@\\\hline
@CULLong@ & @unsigned long long@\\\hline
\end{tabular}
\end{quote}
%
Moreover, it provides the following floating point types, including instances
for @Eq@, @Ord@, @Num@, @Read@, @Show@, @Enum@,
@Storable@, @Real@, @Fractional@, @Floating@,
@RealFrac@, and @RealFloat@:
%
\begin{quote}
\begin{tabular}{|l|l|l|}
\hline
Haskell type & Represented C type\\\hline\hline
@CFloat@ & @float@\\\hline
@CDouble@ & @double@\\\hline
@CLDouble@ & @long double@\\\hline
\end{tabular}
\end{quote}
%
The module provides the following integral types, including instances for
@Eq@, @Ord@, @Num@, @Read@, @Show@, @Enum@,
@Storable@, @Bounded@, @Real@, @Integral@, and
@Bits@:
%
\begin{quote}
\begin{tabular}{|l|l|l|}
\hline
Haskell type & Represented C type\\\hline\hline
@CPtrdiff@ & @ptrdiff_t@\\\hline
@CSize@ & @size_t@\\\hline
@CWchar@ & @wchar_t@\\\hline
@CSigAtomic@& @sig_atomic_t@\\\hline
\end{tabular}
\end{quote}
%
Moreover, it provides the following numeric types, including instances for
@Eq@, @Ord@, @Num@, @Read@, @Show@, @Enum@, and
@Storable@:
%
\begin{quote}
\begin{tabular}{|l|l|l|}
\hline
Haskell type & Represented C type\\\hline\hline
@CClock@ & @clock_t@\\\hline
@CTime@ & @time_t@\\\hline
\end{tabular}
\end{quote}
%
And finally, the following types, including instances for @Eq@ and
@Storable@, are provided:
%
\begin{quote}
\begin{tabular}{|l|l|l|}
\hline
Haskell type & Represented C type\\\hline\hline
@CFile@ & @FILE@\\\hline
@CFpos@ & @fpos_t@\\\hline
@CJmpBuf@ & @jmp_buf@\\\hline
\end{tabular}
\end{quote}
\section{@Data.Bits@}
This module provides functions implementing typical bit operations overloaded
for the standard integral types @Int@ and @Integer@ as well as the
types provided by the modules @Int@ and @Word@ in
Section~\ref{sec:Int-Word}. The overloading is implemented via a new type
class @Bits@, which is a subclass of @Num@ and has the following
member functions:
%
\begin{codedesc}
\item[(.\&.), (.|.), xor ::\ Bits a => a -> a -> a] Implement bitwise
conjunction, disjunction, and exclusive or. The infix operators have the
following precedences:
%
\begin{quote}
\begin{verbatim}
infixl 7 .&.
infixl 6 `xor`
infixl 5 .|.
\end{verbatim}
\end{quote}
\item[complement ::\ Bits a => a -> a] Calculate the bitwise complement of the
argument.
\item[shift, rotate ::\ Bits a => a -> Int -> a] Shift or rotate the bit
pattern to the left for a positive second argument and to the right for a
negative argument. The function @shift@ performs sign extension on
signed number types; i.e., right shifts fill the top bits with 1 if the
number is negative and with 0 otherwise. These operators have the following
precedences as infix operators:
%
\begin{quote}
\begin{verbatim}
infixl 8 `shift`, `rotate`
\end{verbatim}
\end{quote}
%
For unbounded types (e.g., @Integer@), @rotate@ is equivalent to
@shift@. An instance can define either this unified @rotate@ or
@rotateL@ and @rotateR@, depending on which is more convenient for
the type in question.
\item[bit ::\ Bits a => Int -> a] Obtain a value where only the $n$th bit
is set.
\item[setBit, clearBit, complementBit ::\ a -> Int -> a] Set, clear, or
complement the bit at the given position.
\item[testBit ::\ Bits a => a -> Int -> Bool] Check whether the $n$th bit of
the first argument is set.