mono-shlib-cop(1) General Commands Manual mono-shlib-cop(1)
NAME
mono-shlib-cop - Shared Library Usage Checker
SYNOPSIS
mono-shlib-cop [OPTIONS]* [ASSEMBLY-FILE-NAME]*
OPTIONS
-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.
DESCRIPTION
mono-shlib-cop is a tool that inspects a managed assembly looking for erroneous or suspecious usage of shared libraries.
The tool takes one or more assembly filenames, and inspects each assembly specified.
The errors checked for include:
* Does the shared library exist?
* Does the requested symbol exist within the shared library?
The warnings checked for include:
* Is the target shared library a versioned library? (Relevant only on Unix systems, not Mac OS X or Windows.)
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 Sys-
tem.DllNotFoundException. There are three solutions to this:
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.
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.
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
ones for libc.so and libX11.so.
EXAMPLE
The following code contains examples of the above errors and warnings:
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);
}
Bad library name
Assuming that the library bad-library-name doesn't exist on your machine, Demo.BadLibraryName will generate an error, as it requires
a shared library which cannot be loaded. This may be ignorable; see BUGS
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
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 libcap-devel , and you can't assume that end users will
have any -devel packages installed).
FIXING CODE
The fix depends on the warning or error:
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.
Bad symbol names
Reference a symbol that actually exists in the target library.
Unversioned library dependency
Provide a <dllmap/> entry to reference a properly versioned library, or ignore the warning (see BUGS ).
DLLMAP ENTRIES
Mono looks for an ASSEMBLY-NAME mapping information. For example, with mcs.exe , Mono would read mcs.exe.config , and for Mono.Posix.dll ,
Mono would read Mono.Posix.dll.config
The .config file is an XML document containing a top-level <configuration/> section with nested <dllmap/> entries, which contains dll and
target attributes. The dll attribute should contain the same string used in your DllImport attribute value, and the target attribute spec-
ifies which shared library mono should actually load at runtime.
A sample .config file is:
<configuration>
<dllmap dll="gtkembedmoz" target="libgtkembedmoz.so" />
</configuration>
BUGS
* Only 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:
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 ();
}
}
}
If mono-shlib-cop is run on this assembly, an error will be reported for using kernel32.dll , even though kernel32.dll will never be
used on Unix platforms.
* mono-shlib-cop currently only examines the shared library file extension to determine if a warning should be generated. A .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 ver-
sioned shared library (possible examples including /usr/lib/libtcl8.4.so, /usr/lib/libubsec.so, etc.).
Consequently, warnings for any such libraries are useless, and incorrect.
Windows and Mac OS X will never generate warnings, as these platforms use different shared library extensions.
MAILING LISTS
Visit http://lists.ximian.com/mailman/listinfo/mono-devel-list for details.
WEB SITE
Visit http://www.mono-project.com for details
mono-shlib-cop(1)