mono-shlib-cop.1

.\" 
.\" 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