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)