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
|
.\"
.\" mono-shlib-cop manual page.
.\" (C) 2005-2006 Jonathan Pryor
.\" Author:
.\" Jonathan Pryor (jonpryor@vt.edu)
.\"
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.TH "mono-shlib-cop" 1
.SH NAME
mono-shlib-cop \- Shared Library Usage Checker
.SH SYNOPSIS
.B mono-shlib-cop
[OPTIONS]* [ASSEMBLY-FILE-NAME]*
.SH OPTIONS
.TP
.I \-p, --prefixes=PREFIX
Mono installation prefixes. This is to find $prefix/etc/mono/config.
The default is based upon the location of mscorlib.dll, and is normally
correct.
.PP
.SH DESCRIPTION
.I mono-shlib-cop
is a tool that inspects a managed assembly looking for
erroneous or suspecious usage of shared libraries.
.PP
The tool takes one or more assembly filenames, and inspects each assembly
specified.
.PP
The errors checked for include:
.TP
*
Does the shared library exist?
.TP
*
Does the requested symbol exist within the shared library?
.PP
The warnings checked for include:
.TP
*
Is the target shared library a versioned library? (Relevant only on Unix
systems, not Mac OS X or Windows.)
.PP
In general, only versioned libraries such as
.I libc.so.6
are present on the
user's machine, and efforts to load
.I libc.so
will result in a
.B System.DllNotFoundException.
There are three solutions to this:
.TP
1.
Require that the user install any
.I -devel
packages which provide the
unversioned library. This usually requires that the user install a large
number of additional packages, complicating the installation process.
.TP
2.
Use a fully versioned name in your
.B DllImport
statements. This requires
editing your source code and recompiling whenever you need to target a
different version of the shared library.
.TP
3.
Provide an
.I assembly.config
file which contains <dllmap/> elements to remap
the shared library name used by your assembly to the actual versioned shared
library present on the users system. Mono provides a number of pre-existing
<dllmap/> entries, including ones for
.I libc.so
and
.I libX11.so.
.SH EXAMPLE
The following code contains examples of the above errors and warnings:
.nf
using System.Runtime.InteropServices; // for DllImport
class Demo {
[DllImport ("bad-library-name")]
private static extern void BadLibraryName ();
[DllImport ("libc.so")]
private static extern void BadSymbolName ();
[DllImport ("libcap.so")]
private static extern int cap_clear (IntPtr cap_p);
}
.fi
.TP
Bad library name
Assuming that the library
.I bad-library-name
doesn't exist on your machine,
.I Demo.BadLibraryName
will generate an error, as
it requires a shared library which cannot be loaded.
This may be ignorable; see
.B BUGS
.
.TP
Bad symbol name
.I Demo.BadSymbolName
will generate an error, as
.I libc.so
(remapped to
.I libc.so.6
by mono's
.I $prefix/etc/mono/config
file) doesn't contain the function
.I BadSymbolName
.
.TP
Unversioned library dependency
Assuming you have the file
.I libcap.so
,
.I Demo.cap_clear
will generate a
warning because, while
.I libcap.so
could be loaded,
.I libcap.so
might not exist on
the users machine (on FC2,
.I /lib/libcap.so
is provided by
.I libcap-devel
, and you can't assume that end users will have any
.I "-devel"
packages installed).
.SH FIXING CODE
The fix depends on the warning or error:
.TP
Bad library names
Use a valid library name in the
.B DllImport
attribute, or provide a <dllmap/>
entry to map your existing library name to a valid library name.
.TP
Bad symbol names
Reference a symbol that actually exists in the target library.
.TP
Unversioned library dependency
Provide a <dllmap/> entry to reference a properly versioned library, or ignore
the warning (see
.B BUGS
).
.SH DLLMAP ENTRIES
Mono looks for an
.I ASSEMBLY-NAME
\.config file for each assembly loaded, and reads this file to find Dll
mapping information. For example, with
.I mcs.exe
, Mono would read
.I mcs.exe.config
, and for
.I Mono.Posix.dll
, Mono would read
.I Mono.Posix.dll.config
\.
.PP
The
.I .config
file is an XML document containing a top-level <configuration/>
section with nested <dllmap/> entries, which contains
.B dll
and
.B target
attributes. The dll attribute should contain the same string used in your
.B DllImport
attribute value, and the target attribute specifies which shared
library mono should
.I actually
load at runtime.
.PP
A sample .config file is:
.nf
<configuration>
<dllmap dll="gtkembedmoz" target="libgtkembedmoz.so" />
</configuration>
.fi
.SH BUGS
.TP
*
Only
.B DllImport
entries are checked; the surrounding IL is ignored. Consequently, if a runtime
check is performed to choose which shared library to invoke, an error will be
reported even though the specified library is never used. Consider this code:
.nf
using System.Runtime.InteropServices; // for DllImport
class Beep {
[DllImport ("kernel32.dll")]
private static extern int Beep (int dwFreq, int dwDuration);
[DllImport ("libcurses.so")]
private static extern int beep ();
public static void Beep ()
{
if (System.IO.Path.DirectorySeparatorChar == '\\\\') {
Beep (750, 300);
}
else {
beep ();
}
}
}
.fi
If
.I mono-shlib-cop
is run on this assembly, an error will be reported for using
.I kernel32.dll
, even though
.I kernel32.dll
will never be used on Unix platforms.
.TP
*
.I mono-shlib-cop
currently only examines the shared library file extension to determine if a
warning should be generated. A
.I .so
extension will always generate a warning, even if the
.I .so
is not a symlink,
isn't provided in a
.I -devel
package, and there is no versioned shared library
(possible examples including
.I /usr/lib/libtcl8.4.so,
.I /usr/lib/libubsec.so,
etc.).
.Sp
Consequently, warnings for any such libraries are useless, and incorrect.
.Sp
Windows and Mac OS X will never generate warnings, as these
platforms use different shared library extensions.
.SH MAILING LISTS
Visit http://lists.ximian.com/mailman/listinfo/mono-devel-list for details.
.SH WEB SITE
Visit http://www.mono-project.com for details
|
