annotate R/rdyncall/man/dyncall.Rd @ 66:7a61dd082341 default tip

pydc: - fix double free triggered by capsule destructor, when freeing pydc and callback objects, manually
author Tassilo Philipp
date Fri, 24 May 2024 18:16:29 +0200
parents 0cfcc391201f
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
1 \name{dyncall}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
2 \alias{.dyncall}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
3 \alias{dyncall}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
4 \alias{.dyncall.default}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
5 \alias{.dyncall.cdecl}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
6 \alias{.dyncall.stdcall}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
7 \alias{.dyncall.thiscall}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
8 \alias{.dyncall.thiscall.msvc}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
9 \alias{.dyncall.thiscall.gcc}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
10 \alias{.dyncall.fastcall.msvc}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
11 \alias{.dyncall.fastcall.gcc}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
12 \alias{signature}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
13 \alias{call signature}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
14 \alias{type signature}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
15 \title{Foreign Function Interface with support for almost all C types}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
16 \description{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
17 Functions to call pre-compiled code with support for most C argument and return types.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
18 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
19 \usage{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
20 .dyncall( address, signature, ... , callmode = "default" )
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
21 .dyncall.default ( address, signature, ... )
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
22 .dyncall.cdecl ( address, signature, ... )
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
23 .dyncall.stdcall ( address, signature, ... )
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
24 .dyncall.thiscall ( address, signature, ... )
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
25 .dyncall.thiscall.msvc( address, signature, ... )
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
26 .dyncall.thiscall.gcc ( address, signature, ... )
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
27 .dyncall.fastcall.msvc( address, signature, ... )
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
28 .dyncall.fastcall.gcc ( address, signature, ... )
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
29 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
30 \arguments{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
31 \item{address}{external pointer to foreign function.}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
32 \item{signature}{character string specifying the \emph{call signature} that describes the foreign function type. See details.}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
33 \item{callmode}{character string specifying the \emph{calling convention}. This argument has no effect on most platforms, but on Microsoft Windows 32-Bit Intel/x86 platforms. See details.}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
34 \item{...}{arguments to be passed to the foreign function. Arguments are converted from R to C values according to the \emph{call signature}. See details.}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
35 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
36 \details{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
37 \code{.dyncall} offers a flexible Foreign Function Interface (FFI) for
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
38 the C language with support for calls to arbitrary pre-compiled
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
39 C function types at run-time. Almost all C fundamental
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
40 argument- and return types are supported including extended support for
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
41 pointers. No limitations is given for arity as well.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
42 In addition, on the Microsoft Windows 32-Bit Intel/x86 platform, it supports multiple calling conventions to
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
43 interoperate with System DLLs.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
44 Foreign C function types are specified via plain text \emph{type signatures}.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
45 The foreign C function type of the target function is known to the FFI
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
46 in advance, before preparation of the foreign call via plain text
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
47 \emph{type signature} information.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
48 This has several advantages: R arguments do not need to match exactly.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
49 Although R lacks some fundamental C value types, they are supported via
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
50 coercion at this interface (e.g. C \code{float} and 64-bit integer).
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
51 Arity and argument type checks help make this interface type-safe
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
52 to a certain degree and encourage end-users to use interface from
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
53 the interpreter prompt for rapid application development.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
54
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
55 The foreign function to be called is specified by \code{address}, which is an external pointer that is obtained from \code{\link{.dynsym}} or \code{\link{getNativeSymbolInfo}}.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
56
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
57 \code{signature} is a character string that specifies the formal argument-and-return types of the
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
58 foreign function using a \emph{call signature} string. It should match the function type of the foreign function given by \code{address},
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
59 otherwise this can lead to a \strong{fatal R process crash}.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
60
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
61 The calling convention is specified \emph{explicitly} via function \code{.dyncall}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
62 using the \code{callmode} argument or \emph{implicitly} by using \code{.dyncall.*}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
63 functions. See details below.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
64
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
65 Arguments passed via \code{...} are converted to C according to \code{signature} ; see below for details.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
66
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
67 Given that the \code{signature} matches the foreign function type, the FFI provides a certain level of type-safety to users, when
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
68 exposing foreign functions via call wrappers such as done in \code{\link{dynbind}} and \code{\link{dynport}}.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
69 Several basic argument type-safety checks are done during preparation of the foreign function call:
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
70 The arity of formals and actual arguments must match and they must be compatible as well.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
71 Otherwise, the foreign function call is aborted with an error before risking a fatal system crash.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
72 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
73 \value{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
74 Functions return the received C return value converted to an R value. See section \sQuote{Call Signature} below for details.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
75 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
76 \section{Type Signature}{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
77 Type signatures are used by almost all other signature formats (call, library, structure and union signature) and also by the low-level (un)-\code{\link{packing}} functions.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
78
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
79 The following table gives a list of valid type signatures for all supported C types.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
80
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
81 \tabular{clll}{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
82 \strong{Type Signature} \tab \strong{C type} \tab \strong{valid R argument types} \tab \strong{R return type}\cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
83 '\code{B}' \tab bool \tab raw,logical,integer,double \tab logical\cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
84 '\code{c}' \tab char \tab raw,logical,integer,double \tab integer\cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
85 '\code{C}' \tab unsigned char \tab raw,logical,integer,double \tab integer\cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
86 '\code{s}' \tab short \tab raw,logical,integer,double \tab integer\cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
87 '\code{S}' \tab unsigned short \tab raw,logical,integer,double \tab integer\cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
88 '\code{i}' \tab int \tab raw,logical,integer,double \tab integer\cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
89 '\code{I}' \tab unsigned int \tab raw,logical,integer,double \tab double\cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
90 '\code{j}' \tab long \tab raw,logical,integer,double \tab double\cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
91 '\code{J}' \tab unsigned long \tab raw,logical,integer,double \tab double\cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
92 '\code{l}' \tab long long \tab raw,logical,integer,double \tab double\cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
93 '\code{L}' \tab unsigned long long \tab raw,logical,integer,double \tab double\cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
94 '\code{f}' \tab float \tab raw,logical,integer,double \tab double\cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
95 '\code{d}' \tab double \tab raw,logical,integer,double \tab double\cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
96 '\code{p}' \tab \emph{C pointer} \tab \emph{any vector},externalptr,NULL \tab externalptr\cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
97 '\code{Z}' \tab char* \tab character,NULL \tab character or NULL\cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
98 '\code{x}' \tab SEXP \tab \emph{any} \tab \emph{any}\cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
99 '\code{v}' \tab void \tab \emph{invalid} \tab NULL\cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
100 '\code{*}' \ldots \tab \emph{C type}* (pointer) \tab \emph{any vector},externalptr,NULL \tab externalptr\cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
101 "\code{*<}" \emph{typename} '\code{>}' \tab \emph{typename}* (pointer) \tab raw,externalptr \tab externalptr\cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
102 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
103
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
104 The last two rows of the table the above refer to \emph{typed pointer} signatures.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
105 If they appear as a return type signature, the external pointer returned is
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
106 a S3 \code{struct} object. See \code{\link{new.struct}} for details.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
107
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
108 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
109 \section{Call Signatures}{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
110 Call Signatures are used by \code{\link{.dyncall}} and \code{\link{new.callback}} to describe foreign C function types.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
111 The general form of a call signature is as following:
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
112
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
113 \tabular{lll}{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
114 (\emph{argument-type})* \tab \code{')'} \tab \emph{return-type} \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
115 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
116
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
117 The calling sequence given by the \bold{argument types signature} is specified in direct \emph{left-to-right} order of the formal argument types defined in C.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
118 The type signatures are put in sequence without any white space in between.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
119 A closing bracket character '\code{)}' marks the end of argument types, followed by a
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
120 single \bold{return type signature}.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
121
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
122 Derived pointer types can be specified as untyped pointers via \code{'p'}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
123 or via prefix \code{'*'} following the underlying base type (e.g. \code{'*d'} for \code{double *})
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
124 which is more type-safe. For example, this can prevent users from passing a \code{numeric} R atomic as \code{int*} if using \code{'*i'} instead of \code{'p'}.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
125
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
126 Dervied pointer types to aggregate \code{union} or \code{struct} types are
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
127 supported in combination with the framework for handling foreign data types.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
128 See \code{\link{new.struct}} for details. Once a C type is registered,
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
129 the signature \code{*<}\emph{typename}\code{>} can be used to refer to a pointer to an aggregate C object \emph{type}\code{*}.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
130 If typed pointers to aggregate objects are used as a return type and the corresponding type information exists, the returned value can be printed and accessed symbolically.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
131
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
132 Here are some examples of C function prototypes and corresponding call signatures:
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
133
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
134 \tabular{rll}{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
135 \tab \emph{C Function Prototype} \tab \emph{Call Signature} \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
136 \code{double} \tab \code{sqrt(double);} \tab \code{"d)d"} \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
137 \code{double} \tab \code{dnorm(double,double,double,int);} \tab \code{"dddi)d"} \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
138 \code{void} \tab \code{R_isort(int*,int);} \tab \code{"pi)v"} or \code{"*ii)v"} \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
139 \code{void} \tab \code{revsort(double*,int*,int);} \tab \code{"ppi)v"} or \code{"*d*ii)v"}\cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
140 \code{int} \tab \code{SDL_PollEvents(SDL_Event *);} \tab \code{"p)i"} or \code{"*<SDL_Event>)i"} \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
141 \code{SDL_Surface*} \tab \code{SDL_SetVideoMode(int,int,int,int);} \tab \code{"iiii)p"} or \code{"iiii)*<SDL_Surface>"} \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
142 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
143
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
144 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
145
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
146 \section{Calling convention}{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
147 Calling Conventions specify \sQuote{how} sub-routine calls are performed, and, \sQuote{how} arguments and results are passed,
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
148 on machine-level. They differ significantly among families of CPU Architectures
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
149 as well as OS and Compiler implementations.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
150
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
151 On most platforms, a single \code{"default"} C Calling Convention is used.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
152 As an exception, on the Microsoft Windows 32-Bit Intel/x86 platform several calling conventions are common.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
153 Most of the C libraries still use a \code{"default"} C ( also known as \code{"cdecl"} )
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
154 calling convention, but when working with Microsoft System APIs and DLLs, the \code{"stdcall"}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
155 calling convention must be used.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
156
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
157 It follows a description of supported Win32 Calling Conventions:
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
158
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
159 \describe{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
160 \item{\code{"cdecl"}}{Dummy alias to \emph{default}}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
161 \item{\code{"stdcall"}}{C functions with \emph{stdcall} calling convention. Useful for all Microsoft Windows System Libraries (e.g. KERNEL32.DLL, USER32.DLL, OPENGL32.DLL ...). Third-party libraries usually prefer the default C \emph{cdecl} calling convention. }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
162 \item{\code{"fastcall.msvc"}}{C functions with \emph{fastcall} calling convention compiled with Microsoft Visual C++ Compiler. Very rare usage.}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
163 \item{\code{"fastcall.gcc"}}{C functions with \emph{fastcall} calling convention compiled with GNU C Compiler. Very rare usage.}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
164 \item{\code{"thiscall"}}{C++ member functions.}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
165 \item{\code{"thiscall.gcc"}}{C++ member functions compiled with GNU C Compiler.}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
166 \item{\code{"thiscall.msvc"}}{C++ member functions compiled with Microsoft Visual C++ Compiler.}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
167 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
168
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
169 As of the current version of this package and for practical reasons, the \code{callmode} argument does not have an effect on almost
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
170 all platforms, except that if R is running on Microsoft Windows 32-Bit Intel/x86 platform, \code{.dyncall} uses the specified calling convention.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
171 For example, when loading OpenGL across platforms, \code{"stdcall"} should be used instead of \code{"default"},
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
172 because on Windows, OpenGL is a System DLL. This is very exceptional, as in most other cases, \code{"default"} (or \code{"cdecl"}, the alias) need to be used
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
173 for normal C shared libraries on Windows.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
174
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
175 At this stage of development, support for C++ calls should be considered experimental.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
176 Support for Fortran is planed but not yet implemented in dyncall.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
177 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
178 \section{Portability}{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
179 The implementation is based on the \emph{dyncall} library (part of the DynCall project).
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
180
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
181 The following processor architectures are supported: X86 32- and 64-bit, ARM v4t-v7 oabi/eabi (aapcs) and armhf including support for Thumb ISA, PowerPC 32-bit, MIPS 32- and 64-Bit, SPARC 32- and 64-bit; The library
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
182 has been built and tested to work on various OSs: Linux, Mac OS X, Windows 32/64-bit, BSDs, Haiku, Nexenta/Open Solaris, Solaris, Minix and Plan9,
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
183 as well as embedded platforms such as Linux/ARM (OpenMoko, Beagleboard, Gumstix, Efika MX, Raspberry Pi), Nintendo DS (ARM), Sony Playstation Portable (MIPS 32-bit/eabi) and iOS (ARM - armv6 mode ok, armv7 unstable).
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
184 In the context of R, dyncall has currently no support for PowerPC 64-Bit.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
185 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
186 \note{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
187 The target address, calling convention and call signature \strong{MUST} match foreign function type, otherwise the invocation could lead to a \strong{fatal R process crash}.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
188 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
189 \examples{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
190 \donttest{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
191 mathlib <- dynfind(c("msvcrt","m","m.so.6"))
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
192 x <- .dynsym(mathlib,"sqrt")
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
193 .dyncall(x, "d)d", 144L)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
194 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
195 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
196 \references{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
197 Adler, D. (2012) \dQuote{Foreign Library Interface}, \emph{The R Journal}, \bold{4(1)}, 30--40, June 2012.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
198 \url{http://journal.r-project.org/archive/2012-1/RJournal_2012-1_Adler.pdf}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
199
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
200 Adler, D., Philipp, T. (2008) \emph{DynCall Project}.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
201 \url{http://dyncall.org}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
202 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
203 \seealso{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
204 \code{\link{.dynsym}} and \code{\link[base]{getNativeSymbolInfo}} for resolving symbols,
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
205 \code{\link{dynbind}} for binding several foreign functions via thin call wrappers,
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
206 \code{\link[base]{.C}} for the traditional FFI to C.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
207 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
208 \keyword{programming}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
209 \keyword{interface}