1mono-shlib-cop(1) General Commands Manual mono-shlib-cop(1)
2
6 mono-shlib-cop - Shared Library Usage Checker
7
9 mono-shlib-cop [OPTIONS]* [ASSEMBLY-FILE-NAME]*
10
12 -p, --prefixes=PREFIX
13 Mono installation prefixes. This is to find $pre‐
14 fix/etc/mono/config. The default is based upon the location of
15 mscorlib.dll, and is normally correct.
16
18 mono-shlib-cop is a tool that inspects a managed assembly looking for
19 erroneous or suspecious usage of shared libraries.
20 The tool takes one or more assembly filenames, and inspects each assem‐
22 bly specified.
23 The errors checked for include:
25 * Does the shared library exist?
27 * Does the requested symbol exist within the shared library?
29 The warnings checked for include:
31 * Is the target shared library a versioned library? (Relevant
33 only on Unix systems, not Mac OS X or Windows.)
34 In general, only versioned libraries such as libc.so.6 are present on
36 the user's machine, and efforts to load libc.so will result in a Sys‐
37 tem.DllNotFoundException. There are three solutions to this:
38 1. Require that the user install any -devel packages which provide
40 the unversioned library. This usually requires that the user
41 install a large number of additional packages, complicating the
42 installation process.
43 2. Use a fully versioned name in your DllImport statements. This
45 requires editing your source code and recompiling whenever you
46 need to target a different version of the shared library.
47 3. Provide an assembly.config file which contains <dllmap/> ele‐
49 ments to remap the shared library name used by your assembly to
50 the actual versioned shared library present on the users system.
51 Mono provides a number of pre-existing <dllmap/> entries,
52 including ones for libc.so and libX11.so.
53
55 The following code contains examples of the above errors and warnings:
56 using System.Runtime.InteropServices; // for DllImport
57 class Demo {
58 [DllImport ("bad-library-name")]
59 private static extern void BadLibraryName ();
60 [DllImport ("libc.so")]
62 private static extern void BadSymbolName ();
63 [DllImport ("libcap.so")]
65 private static extern int cap_clear (IntPtr cap_p);
66 }
67 Bad library name
69 Assuming that the library bad-library-name doesn't exist on your
70 machine, Demo.BadLibraryName will generate an error, as it
71 requires a shared library which cannot be loaded. This may be
72 ignorable; see BUGS
73 Bad symbol name
75 Demo.BadSymbolName will generate an error, as libc.so (remapped
76 to libc.so.6 by mono's $prefix/etc/mono/config file) doesn't
77 contain the function BadSymbolName
78 Unversioned library dependency
80 Assuming you have the file libcap.so , Demo.cap_clear will gen‐
81 erate a warning because, while libcap.so could be loaded, lib‐
82 cap.so might not exist on the users machine (on FC2, /lib/lib‐
83 cap.so is provided by libcap-devel , and you can't assume that
84 end users will have any -devel packages installed).
85
87 The fix depends on the warning or error:
88 Bad library names
90 Use a valid library name in the DllImport attribute, or provide
91 a <dllmap/> entry to map your existing library name to a valid
92 library name.
93 Bad symbol names
95 Reference a symbol that actually exists in the target library.
96 Unversioned library dependency
98 Provide a <dllmap/> entry to reference a properly versioned
99 library, or ignore the warning (see BUGS ).
100
102 Mono looks for an ASSEMBLY-NAME mapping information. For example, with
103 mcs.exe , Mono would read mcs.exe.config , and for Mono.Posix.dll ,
104 Mono would read Mono.Posix.dll.config
105 The .config file is an XML document containing a top-level <configura‐
107 tion/> section with nested <dllmap/> entries, which contains dll and
108 target attributes. The dll attribute should contain the same string
109 used in your DllImport attribute value, and the target attribute speci‐
110 fies which shared library mono should actually load at runtime.
111 A sample .config file is:
113 <configuration>
114 <dllmap dll="gtkembedmoz" target="libgtkembedmoz.so" />
115 </configuration>
116
118 * Only DllImport entries are checked; the surrounding IL is
119 ignored. Consequently, if a runtime check is performed to
120 choose which shared library to invoke, an error will be reported
121 even though the specified library is never used. Consider this
122 code:
123 using System.Runtime.InteropServices; // for DllImport
124 class Beep {
125 [DllImport ("kernel32.dll")]
126 private static extern int Beep (int dwFreq, int dwDuration);
127 [DllImport ("libcurses.so")]
129 private static extern int beep ();
130 public static void Beep ()
132 {
133 if (System.IO.Path.DirectorySeparatorChar == '\\') {
134 Beep (750, 300);
135 }
136 else {
137 beep ();
138 }
139 }
140 }
141 If mono-shlib-cop is run on this assembly, an error will be
142 reported for using kernel32.dll , even though kernel32.dll will
143 never be used on Unix platforms.
144 * mono-shlib-cop currently only examines the shared library file
146 extension to determine if a warning should be generated. A .so
147 extension will always generate a warning, even if the .so is not
148 a symlink, isn't provided in a -devel package, and there is no
149 versioned shared library (possible examples including
150 /usr/lib/libtcl8.4.so, /usr/lib/libubsec.so, etc.).
151 Consequently, warnings for any such libraries are useless, and
153 incorrect.
154 Windows and Mac OS X will never generate warnings, as these
156 platforms use different shared library extensions.
157
159 Visit http://lists.ximian.com/mailman/listinfo/mono-devel-list for
160 details.
161
163 Visit http://www.mono-project.com for details
164 mono-shlib-cop(1)