+.\"
+.\" 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 DESCRIPTION
.I mono-shlib-cop
is a tool that inspects a managed assembly looking for
-erroneous or suspecious behavior of shared libraries.
+erroneous or suspecious usage of shared libraries.
.PP
The tool takes one or more assembly filenames, and inspects each assembly
specified.
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:
+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 -devel packages which provide the
+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 DllImport statements. This requires
+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 assembly.config file which contains <dllmap/> elements to remap
+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 libc.so and libX11.so.
+<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
.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.
+.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
-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.
+.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 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
+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 -devel packages installed).
+, 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 DllImport attribute, or provide a <dllmap/>
+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
.I Mono.Posix.dll.config
\.
.PP
-The .config file is an XML document containing a top-level <configuration/>
+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
-DllImport attribute value, and the target attribute specifies which shared
+.B DllImport
+attribute value, and the target attribute specifies which shared
library mono should
.I actually
load at runtime.
</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 .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,
+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.).
-.PP
+.Sp
Consequently, warnings for any such libraries are useless, and incorrect.
-.PP
+.Sp
Windows and Mac OS X will never generate warnings, as these
platforms use different shared library extensions.
.SH MAILING LISTS
projects / mono.git / commitdiff