Mercurial > pub > dyncall > dyncall
annotate dyncall/dyncall.3 @ 362:78dfa2f9783a
- added helper function dcGetModeFromCCSigChar() mapping callconv sig chars to respective mode
- added a signature-based syscall to callf testcode
- manual clarification about dcReset usage in combination with dcMode
| author | Tassilo Philipp |
|---|---|
| date | Tue, 14 Apr 2020 16:56:57 +0200 |
| parents | 32736025371f |
| children | 71c884e610f0 |
| rev | line source |
|---|---|
|
362
78dfa2f9783a
- added helper function dcGetModeFromCCSigChar() mapping callconv sig chars to respective mode
Tassilo Philipp
parents:
360
diff
changeset
|
1 .\" Copyright (c) 2007-2020 Daniel Adler <dadler AT uni-goettingen DOT de>, |
| 0 | 2 .\" Tassilo Philipp <tphilipp AT potion-studios DOT com> |
| 3 .\" | |
| 4 .\" Permission to use, copy, modify, and distribute this software for any | |
| 5 .\" purpose with or without fee is hereby granted, provided that the above | |
| 6 .\" copyright notice and this permission notice appear in all copies. | |
| 7 .\" | |
| 8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES | |
| 9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF | |
| 10 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR | |
| 11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | |
| 12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN | |
| 13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF | |
| 14 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | |
| 15 .\" | |
| 16 .Dd $Mdocdate$ | |
| 17 .Dt dyncall 3 | |
| 18 .Sh NAME | |
| 19 .Nm dyncall | |
| 20 .Nd encapsulation of architecture-, OS- and compiler-specific function call | |
| 21 semantics | |
| 22 .Sh SYNOPSIS | |
| 23 .In dyncall.h | |
| 24 .Ft DCCallVM * | |
| 25 .Fn dcNewCallVM "DCsize size" | |
| 26 .Ft void | |
| 27 .Fn dcFree "DCCallVM * vm" | |
| 28 .Ft void | |
| 29 .Fn dcMode "DCCallVM * vm" "DCint mode" | |
| 30 .Ft void | |
| 31 .Fn dcReset "DCCallVM * vm" | |
| 32 .Ft void | |
| 33 .Fn dcArgBool "DCCallVM * vm" "DCbool arg" | |
| 34 .Ft void | |
| 35 .Fn dcArgChar "DCCallVM * vm" "DCchar arg" | |
| 36 .Ft void | |
| 37 .Fn dcArgShort "DCCallVM * vm" "DCshort arg" | |
| 38 .Ft void | |
| 39 .Fn dcArgInt "DCCallVM * vm" "DCint arg" | |
| 40 .Ft void | |
| 41 .Fn dcArgLong "DCCallVM * vm" "DClong arg" | |
| 42 .Ft void | |
| 43 .Fn dcArgLongLong "DCCallVM * vm" "DClonglong arg" | |
| 44 .Ft void | |
| 45 .Fn dcArgFloat "DCCallVM * vm" "DCfloat arg" | |
| 46 .Ft void | |
| 47 .Fn dcArgDouble "DCCallVM * vm" "DCdouble arg" | |
| 48 .Ft void | |
| 49 .Fn dcArgPointer "DCCallVM * vm" "DCpointer arg" | |
| 50 .Ft DCvoid | |
| 51 .Fn dcCallVoid "DCCallVM * vm" "DCpointer funcptr" | |
| 52 .Ft DCbool | |
| 53 .Fn dcCallBool "DCCallVM * vm" "DCpointer funcptr" | |
| 54 .Ft DCchar | |
| 55 .Fn dcCallChar "DCCallVM * vm" "DCpointer funcptr" | |
| 56 .Ft DCshort | |
| 57 .Fn dcCallShort "DCCallVM * vm" "DCpointer funcptr" | |
| 58 .Ft DCint | |
| 59 .Fn dcCallInt "DCCallVM * vm" "DCpointer funcptr" | |
| 60 .Ft DClong | |
| 61 .Fn dcCallLong "DCCallVM * vm" "DCpointer funcptr" | |
| 62 .Ft DClonglong | |
| 63 .Fn dcCallLongLong "DCCallVM * vm" "DCpointer funcptr" | |
| 64 .Ft DCfloat | |
| 65 .Fn dcCallFloat "DCCallVM * vm" "DCpointer funcptr" | |
| 66 .Ft DCdouble | |
| 67 .Fn dcCallDouble "DCCallVM * vm" "DCpointer funcptr" | |
| 68 .Ft DCpointer | |
| 69 .Fn dcCallPointer "DCCallVM * vm" "DCpointer funcptr" | |
| 70 .Ft void | |
| 71 .Fn dcArgF "DCCallVM * vm" "const DCsigchar * signature" "..." | |
| 72 .Ft void | |
| 73 .Fn dcVArgF "DCCallVM * vm" "const DCsigchar * signature" "va_list args" | |
| 74 .Ft void | |
| 75 .Fn dcCallF "DCCallVM * vm" "DCValue * result" "DCpointer funcptr" "const DCsigchar * signature" "..." | |
| 76 .Ft void | |
| 77 .Fn dcVCallF "DCCallVM * vm" "DCValue * result" "DCpointer funcptr" "const DCsigchar * signature" "va_list args" | |
| 78 .Sh DESCRIPTION | |
| 79 The | |
| 80 .Nm | |
| 81 library encapsulates architecture-, OS- and compiler-specific function call | |
| 82 semantics in a virtual "bind argument parameters from left to right and then | |
| 83 call" interface allowing programmers to call C functions in a completely | |
| 84 dynamic manner. | |
| 85 .Pp | |
| 86 In other words, instead of calling a function directly, the | |
| 87 .Nm | |
| 88 library provides a mechanism to push the function parameters manually and to | |
| 89 issue the call afterwards. | |
| 90 .Pp | |
| 91 Since the idea behind this concept is similar to call dispatching mechanisms | |
| 92 of virtual machines, the object that can be dynamically loaded with arguments, | |
| 93 and then used to actually invoke the call, is called CallVM. It is possible to | |
| 94 change the calling convention used by the CallVM at run-time. Due to the fact | |
| 95 that nearly every platform comes with one or more distinct calling conventions, the | |
| 96 .Nm | |
| 97 library project intends to be a portable and open-source approach to the variety of | |
| 98 compiler-specific binary interfaces, platform specific subtleties, and so on... | |
| 99 .Pp | |
| 100 .Fn dcNewCallVM | |
| 101 creates a new CallVM object, where | |
| 102 .Ar size | |
| 103 specifies the max size of the internal stack that will be allocated and used to | |
| 104 bind the arguments to. Use | |
| 105 .Fn dcFree | |
| 106 to destroy the CallVM object. | |
| 107 .Pp | |
| 108 .Fn dcMode | |
| 109 sets the calling convention to use. See dyncall.h for a list of | |
| 110 available modes. Note that some mode/platform combinations don't make any | |
| 111 sense (e.g. using a PowerPC calling convention on a MIPS platform) and are | |
| 112 silently ignored. | |
| 113 .Pp | |
| 114 .Fn dcReset | |
|
362
78dfa2f9783a
- added helper function dcGetModeFromCCSigChar() mapping callconv sig chars to respective mode
Tassilo Philipp
parents:
360
diff
changeset
|
115 resets the internal stack of arguments and prepares it for a new call. This |
|
78dfa2f9783a
- added helper function dcGetModeFromCCSigChar() mapping callconv sig chars to respective mode
Tassilo Philipp
parents:
360
diff
changeset
|
116 function should be called after setting the call mode (using dcMode), but prior |
|
78dfa2f9783a
- added helper function dcGetModeFromCCSigChar() mapping callconv sig chars to respective mode
Tassilo Philipp
parents:
360
diff
changeset
|
117 to binding arguments to the CallVM (except for when setting mode |
|
78dfa2f9783a
- added helper function dcGetModeFromCCSigChar() mapping callconv sig chars to respective mode
Tassilo Philipp
parents:
360
diff
changeset
|
118 DC_SIGCHAR_CC_ELLIPSIS_VARARGS, which is used prior to binding varargs of |
|
78dfa2f9783a
- added helper function dcGetModeFromCCSigChar() mapping callconv sig chars to respective mode
Tassilo Philipp
parents:
360
diff
changeset
|
119 variadic functions). Use it also when reusing a CallVM, as arguments don't get |
|
78dfa2f9783a
- added helper function dcGetModeFromCCSigChar() mapping callconv sig chars to respective mode
Tassilo Philipp
parents:
360
diff
changeset
|
120 flushed automatically after a function call invocation. Note: you should also |
|
78dfa2f9783a
- added helper function dcGetModeFromCCSigChar() mapping callconv sig chars to respective mode
Tassilo Philipp
parents:
360
diff
changeset
|
121 call this function after initial creation of the a CallVM object, as |
|
78dfa2f9783a
- added helper function dcGetModeFromCCSigChar() mapping callconv sig chars to respective mode
Tassilo Philipp
parents:
360
diff
changeset
|
122 dcNewCallVM doesn't do this, implicitly. |
| 0 | 123 .Pp |
| 124 .Fn dcArgBool , | |
| 125 .Fn dcArgChar , | |
| 126 .Fn dcArgShort , | |
| 127 .Fn dcArgInt , | |
| 128 .Fn dcArgLong , | |
| 129 .Fn dcArgLongLong , | |
| 130 .Fn dcArgFloat , | |
| 131 .Fn dcArgDouble | |
| 132 and | |
| 133 .Fn dcArgPointer | |
| 134 are used to bind arguments of the named types to the CallVM object. Arguments should | |
| 135 be bound in | |
| 136 .Em "left to right" | |
| 137 order regarding the C function prototype. | |
| 138 .Pp | |
| 139 .Fn dcCallVoid , | |
| 140 .Fn dcCallBool , | |
| 141 .Fn dcCallChar , | |
| 142 .Fn dcCallShort , | |
| 143 .Fn dcCallInt , | |
| 144 .Fn dcCallLong , | |
| 145 .Fn dcCallLongLong , | |
| 146 .Fn dcCallFloat , | |
| 147 .Fn dcCallDouble | |
| 148 and | |
| 149 .Fn dcCallPointer | |
| 150 call the function with the bound arguments and returning the named type, where | |
| 151 .Ar funcptr | |
| 152 is a pointer to the function to call. After the invocation of the function | |
| 153 call, the argument values are still bound to the CallVM and a second call | |
| 154 using the same arguments can be issued. Call | |
| 155 .Fn reset | |
| 156 to clear the internal argument stack. | |
| 157 .Pp | |
| 158 .Fn dcArgF , | |
| 159 .Fn dcVArgF , | |
| 160 .Fn dcCallF | |
| 161 and | |
| 162 .Fn dcVCallF | |
| 163 can be used to bind arguments in a printf-style call, using a signature | |
| 164 string encoding the argument types and return type. The former 2 only bind | |
| 165 the arguments to the | |
| 166 .Ar vm | |
| 167 object (and ignore return types specified in the | |
| 168 signature), whereas the latter two issue a call to the given function pointer, | |
| 169 afterwards. The return value will be stored in | |
| 170 .Ar result . | |
|
360
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
250
diff
changeset
|
171 The signature string also features calling convention mode selection. |
| 0 | 172 For information about the signature format, refer to the |
| 173 .Nm | |
| 174 manual in PDF format. | |
| 175 .Sh EXAMPLE | |
| 176 Let's say, we want to make a call to the function: | |
| 177 .Bd -literal -offset indent | |
| 178 double sqrt(double x); | |
| 179 .Ed | |
| 180 .Pp | |
| 181 Using the | |
| 182 .Nm | |
| 183 library, this function would be called as follows: | |
| 184 .Bd -literal -offset indent | |
| 185 double r; | |
| 186 DCCallVM* vm = dcNewCallVM(4096); | |
| 187 dcMode(vm, DC_CALL_C_DEFAULT); | |
| 188 dcReset(vm); | |
| 189 dcArgDouble(vm, 4.2373); | |
| 190 r = dcCallDouble(vm, (DCpointer)&sqrt); | |
| 191 dcFree(vm); | |
| 192 .Ed | |
|
250
7cb8a0aaf638
- note about c99 (+ anon struct/union) requirements in doc
Tassilo Philipp
parents:
93
diff
changeset
|
193 .Sh CONFORMING TO |
|
7cb8a0aaf638
- note about c99 (+ anon struct/union) requirements in doc
Tassilo Philipp
parents:
93
diff
changeset
|
194 The dyncall library needs at least a c99 compiler with additional support for |
|
7cb8a0aaf638
- note about c99 (+ anon struct/union) requirements in doc
Tassilo Philipp
parents:
93
diff
changeset
|
195 anonymous structs/unions (which were introduced officially in c11). Given that |
|
7cb8a0aaf638
- note about c99 (+ anon struct/union) requirements in doc
Tassilo Philipp
parents:
93
diff
changeset
|
196 those are generally supported by pretty much all major c99 conforming compilers |
|
7cb8a0aaf638
- note about c99 (+ anon struct/union) requirements in doc
Tassilo Philipp
parents:
93
diff
changeset
|
197 (as default extension), it should build fine with a c99 toolchain. Strictly |
|
7cb8a0aaf638
- note about c99 (+ anon struct/union) requirements in doc
Tassilo Philipp
parents:
93
diff
changeset
|
198 speaking, dyncall conforms to c11, though. |
|
7cb8a0aaf638
- note about c99 (+ anon struct/union) requirements in doc
Tassilo Philipp
parents:
93
diff
changeset
|
199 .Ed |
| 0 | 200 .Sh SEE ALSO |
| 201 .Xr dyncallback 3 , | |
| 202 .Xr dynload 3 | |
| 203 and the | |
| 204 .Nm | |
| 93 | 205 manual (available in HTML and PDF format) for more information. |
| 0 | 206 .Sh AUTHORS |
| 207 .An "Daniel Adler" Aq dadler@uni-goettingen.de | |
| 208 .An "Tassilo Philipp" Aq tphilipp@potion-studios.com |