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
|
.\"
.\" name: dlperl.man
.\" synopsis: dlperl man page
.\" sccsid: @(#)dlperl.man 1.4 10/16/92 (DLPERL)
.\"
.ds RP 10/16/92
.rn '' }`
.de Sh
.br
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp
.if t .sp .5v
.if n .sp
..
.de Ip
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
'''
''' Set up \*(-- to give an unbreakable dash;
''' string Tr holds user defined translation string.
''' Bell System Logo is used as a dummy character.
'''
.tr \(*W-|\(bv\*(Tr
.ie n \{\
.ds -- \(*W-
.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
.ds L" ""
.ds R" ""
.ds L' '
.ds R' '
'br\}
.el\{\
.ds -- \(em\|
.tr \*(Tr
.ds L" ``
.ds R" ''
.ds L' `
.ds R' '
'br\}
.TH DLPERL 1 "\*(RP"
.UC
.SH NAME
dlperl \- dynamic link-editor subroutines for perl
.SH SYNOPSIS
.nf
.ft B
$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)
.ft
.fi
.LP
.nf
.ft B
$DL_VERSION
$DL_WARN
$dl_errno
$dl_errstr
.ft
.fi
.SH DESCRIPTION
.I Dlperl
is \fIperl\fP plus user defined subroutines (\fIusubs\fP) 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.
.Sh "Subroutines"
All \fIdlperl\fP 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 \fIdlopen(3x)\fP for a complete
description. The following subroutines are defined by \fIdlperl\fP:
.Ip "&dl_open($file)" 8 2
Adds the shared object \fI$file\fP to \fIdlperl\fP'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.
.Ip "&dl_sym($dl_so, $symbol)" 8 2
Obtains an address binding for the function \fI$symbol\fP as it occurs
in the shared object identified by \fI$dl_so\fP. When an error occurs
an undef value is returned.
.Ip "&dl_call($dl_func, $parms_desc, $return_desc, @parms)" 8 2
Calls the function identified by \fI$dl_func\fP. The function's entry
parameters are described by \fI$parms_desc\fP and assigned values from
\fI@parms\fP. The function's exit value is described by
\fI$return_desc\fP. 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
underlying function may have been called).
.Sp
The descriptions are sequences of characters that give the order and
type of parameters:
.nf
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.
.fi
Each letter may optionally be preceded by a number that gives a repeat
count. An array is specified by a preceding \fI[array_size\fP] (or
\fI&\fP as a shorthand for \fI[1]\fP). (Multi-dimension arrays are not
currently supported.) Each scalar or array element is initialized from
\fI@parms\fP. A preceding \fI-\fP leaves the parameter uninitialized.
Type \fIp\fP expects a preceding \fI<buffer_length>\fP. A preceding
\fI+\fP specifies that after the function is called that particular
parameter's value is to be returned (multiple values are returned for
array types, a \fI+\fP with a integral type like \fIi\fP returns an
undef value). The \fI$return_desc\fP contains only one letter with no
repeat count, \fI-\fP or \fI+\fP.
.Sp
An undef or zero-length \fI$parm_desc\fP means the function has no
parameters. An undef or a zero-length \fI$return_desc\fP 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 \fIf\fP is supported, compilers typically pass floats as
doubles.
.Ip "&dl_close($dl_so)" 8 2
Removes the shared object identified by \fI$dl_so\fP from
\fIdlperl\fP's address space. If successful, a value of zero is
returned. When an error occurs a non-zero value is returned.
.Sh "Predefined Names"
The following names have special meaning to \fIdlperl\fP.
.Ip $DL_VERSION 8
The version of \fIdlperl\fP. This variable is read-only.
.Ip $DL_WARN 8
The current value of the \fIdlperl\fP warning flag. Default is 1. If
non-zero, when errors occur warnings are sent to standard error. The
warning is the same information that is stored in $dl_errstr.
.Ip $dl_errno 8
The error number for the error that occurred. If a \fIdlperl\fP
subroutine completes successfully $dl_errno is set to zero. This variable
is read-only.
.Ip $dl_errstr 8
The error message for the error that occurred. If a \fIdlperl\fP
subroutine completes successfully $dl_errstr is set to a zero length
string. This variable is read-only.
.SH EXAMPLES
This is an example of calling a simple C function:
.Sp
.nf
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/(['\e\e])/\e\e$1/g;
eval <<EOC;
sub example {
&dl_call('$dl_func', "2[2]a i &d -+[4]a", undef, @_);
}
EOC
@vals = &example("hacker,", "Perl", "another", "Just", 1, 2);
print "@vals\en";
&dl_close($dl_so);
die "$0: $dl_errstr" if($dl_errno);
unlink('example.c', 'example.o', 'example.so');
.fi
.LP
If a more complicated interface is needed, the dynamically linked
function can define \fIusubs\fP by calling internal \fIperl\fP
functions.
.SH AUTHOR
Eric Fifer <egf@sbi.com>
.SH SEE ALSO
.BR perl (1),
.BR dlopen (3X),
.BR ld (1)
.SH BUGS
Additional parameter types should be implemented to support structures,
multi-dimension arrays, pointers to arrays, pointers to functions, etc.
.LP
Unlike the \fIpack\fP operator, the repeat count precedes the letter in
the \fI$parm_desc\fP syntax. The array size preceding the parameter
letter is also unconventional.
.LP
All errors set $dl_errno to 1.
.rn }` ''
|
