1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
|
DLPERL(1) USER COMMANDS DLPERL(1)
NAME
dlperl - dynamic link-editor subroutines for perl
SYNOPSIS
$dl_so = &dl_open($file)
$dl_func = &dl_sym($dl_so, $symbol)
@vals = &dl_call($dl_func, $parms_desc, $return_desc, @parms)
$dl_err = &dl_close($dl_so)
$DL_VERSION
$DL_WARN
$dl_errno
$dl_errstr
DESCRIPTION
_D_l_p_e_r_l is _p_e_r_l plus user defined subroutines (_u_s_u_b_s) that
interface to the dynamic link-editor and can call most C and
Fortran functions whose object code has been linked into a
shared object file.
Subroutines
All _d_l_p_e_r_l subroutines set the two predefined names
$dl_errno and $dl_errstr. Only partial descriptions of
&dl_open, &dl_sym and &dl_close appear below, see _d_l_o_p_e_n(_3_x)
for a complete description. The following subroutines are
defined by _d_l_p_e_r_l:
&dl_open($file)
Adds the shared object $_f_i_l_e to _d_l_p_e_r_l's address
space. Returns a descriptor that can be used for
later reference to the object in calls to &dl_sym
and &dl_close. When an error occurs an undef value
is returned.
&dl_sym($dl_so, $symbol)
Obtains an address binding for the function $_s_y_m_b_o_l
as it occurs in the shared object identified by
$_d_l__s_o. When an error occurs an undef value is
returned.
&dl_call($dl_func, $parms_desc, $return_desc, @parms)
Calls the function identified by $_d_l__f_u_n_c. The
function's entry parameters are described by
$_p_a_r_m_s__d_e_s_c and assigned values from @_p_a_r_m_s. The
function's exit value is described by $_r_e_t_u_r_n__d_e_s_c.
An array is returned that contains the values of any
result parameters and the return value. When an
error occurs because of a problem parsing the
descriptions or because of an incorrect parameter
count no values are returned (although the underly-
ing function may have been called).
Sun Release 4.1 Last change: 10/16/92 1
DLPERL(1) USER COMMANDS DLPERL(1)
The descriptions are sequences of characters that
give the order and type of parameters:
c A signed char value.
C An unsigned char value.
s A signed short value.
S An unsigned short value.
i A signed integer value.
I An unsigned integer value.
l A signed long value.
L An unsigned long value.
f A single-precision float.
d A double-precision float.
a An ascii (null-terminated) string.
p A pointer to <length> buffer.
Each letter may optionally be preceded by a number
that gives a repeat count. An array is specified by
a preceding [_a_r_r_a_y__s_i_z_e] (or & as a shorthand for
[_1]). (Multi-dimension arrays are not currently
supported.) Each scalar or array element is ini-
tialized from @_p_a_r_m_s. A preceding - leaves the
parameter uninitialized. Type _p expects a preceding
<_b_u_f_f_e_r__l_e_n_g_t_h>. A preceding + specifies that after
the function is called that particular parameter's
value is to be returned (multiple values are
returned for array types, a + with a integral type
like _i returns an undef value). The $_r_e_t_u_r_n__d_e_s_c
contains only one letter with no repeat count, - or
+.
An undef or zero-length $_p_a_r_m__d_e_s_c means the func-
tion has no parameters. An undef or a zero-length
$_r_e_t_u_r_n__d_e_s_c means the function returns void.
Strings or buffers that must be a specific length
(because the values are overwritten) must be pre-
extended. Although type _f is supported, compilers
typically pass floats as doubles.
&dl_close($dl_so)
Removes the shared object identified by $_d_l__s_o from
_d_l_p_e_r_l's address space. If successful, a value of
zero is returned. When an error occurs a non-zero
value is returned.
Predefined Names
The following names have special meaning to _d_l_p_e_r_l.
$DL_VERSION
The version of _d_l_p_e_r_l. This variable is read-only.
Sun Release 4.1 Last change: 10/16/92 2
DLPERL(1) USER COMMANDS DLPERL(1)
$DL_WARN
The current value of the _d_l_p_e_r_l warning flag.
Default is 1. If non-zero, when errors occur warn-
ings are sent to standard error. The warning is the
same information that is stored in $dl_errstr.
$dl_errno
The error number for the error that occurred. If a
_d_l_p_e_r_l subroutine completes successfully $dl_errno
is set to zero. This variable is read-only.
$dl_errstr
The error message for the error that occurred. If a
_d_l_p_e_r_l subroutine completes successfully $dl_errstr
is set to a zero length string. This variable is
read-only.
EXAMPLES
This is an example of calling a simple C function:
open(OUT, ">example.c");
print OUT <<'EOC';
void
example(a1, a2, i1, d1, a3)
char *a1[2];
char *a2[2];
int i1;
double *d1;
char *a3[4];
{
a3[i1 + (int) *d1] = a1[0];
a3[i1 * (int) *d1] = a1[1];
a3[(int) *d1 - i1] = a2[0];
a3[(int) *d1 - 2 * i1] = a2[1];
}
EOC
close(OUT);
system("cc -c example.c;ld -o example.so example.o");
$dl_so = &dl_open("example.so");
die "$0: $dl_errstr" if($dl_errno);
$dl_func = &dl_sym($dl_so, "example");
die "$0: $dl_errstr" if($dl_errno);
$dl_func =~ s/(['\\])/\\$1/g;
eval <<EOC;
sub example {
&dl_call('$dl_func', "2[2]a i &d -+[4]a", undef, @_);
}
EOC
Sun Release 4.1 Last change: 10/16/92 3
DLPERL(1) USER COMMANDS DLPERL(1)
@vals = &example("hacker,", "Perl", "another", "Just", 1, 2);
print "@vals\n";
&dl_close($dl_so);
die "$0: $dl_errstr" if($dl_errno);
unlink('example.c', 'example.o', 'example.so');
If a more complicated interface is needed, the dynamically
linked function can define _u_s_u_b_s by calling internal _p_e_r_l
functions.
AUTHOR
Eric Fifer <egf@sbi.com>
SEE ALSO
perl(1), dlopen(3X), ld(1)
BUGS
Additional parameter types should be implemented to support
structures, multi-dimension arrays, pointers to arrays,
pointers to functions, etc.
Unlike the _p_a_c_k operator, the repeat count precedes the
letter in the $_p_a_r_m__d_e_s_c syntax. The array size preceding
the parameter letter is also unconventional.
All errors set $dl_errno to 1.
Sun Release 4.1 Last change: 10/16/92 4
|
