/
mono-shlib-cop.1
151 lines (149 loc) · 4.72 KB
/
mono-shlib-cop.1
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
.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 behavior 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 libc.so.6 are present on the
user's machine, and efforts to load libc.so will result in a
System.DllNotFoundException. There are three solutions to this:
.TP
1.
Require that the user install any -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 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 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 libc.so and 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
.B bad-library-name
doesn't exist on your machine, Demo.BadLibraryName will generate an error, as
it requires a shared library which doesn't exist.
.TP
Bad symbol name
Demo.BadSymbolName will generate an error, as libc.so (remapped to libc.so.6
by mono's $prefix/etc/mono/config file) doesn't contain the function
BadSymbolName.
.TP
Unversioned library dependency
Assuming you have the file libcap.so, Demo.cap_clear will generate a
warning because, while libcap.so could be loaded, libcap.so might not exist on
the users machine (on FC2, /lib/libcap.so is provided by
.I libcap-devel
, and you can't assume that end users will have any -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 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 .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
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
.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 .so is not a symlink,
isn't provided in a -devel package, and there is no versioned shared library
(possible examples including /usr/lib/libtcl8.4.so, /usr/lib/libubsec.so,
etc.).
.PP
Consequently, warnings for any such libraries are useless, and incorrect.
.PP
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