man/mono-shlib-cop.1

   1 .TH "mono-shlib-cop" 1
   2 .SH NAME
   3 mono-shlib-cop \- Shared Library Usage Checker
   4 .SH SYNOPSIS
   5 .B mono-shlib-cop
   6 [OPTIONS]* [ASSEMBLY-FILE-NAME]*
   7 .SH OPTIONS
   8 .TP
   9 .I \-p, --prefixes=PREFIX
  10 Mono installation prefixes.  This is to find $prefix/etc/mono/config.
  11 The default is based upon the location of mscorlib.dll, and is normally
  12 correct.
  13 .PP
  14 .SH DESCRIPTION
  15 .I mono-shlib-cop
  16 is a tool that inspects a managed assembly looking for
  17 erroneous or suspecious behavior of shared libraries.
  18 .PP
  19 The tool takes one or more assembly filenames, and inspects each assembly
  20 specified.
  21 .PP
  22 The errors checked for include:
  23 .TP
  24 *
  25 Does the shared library exist?
  26 .TP
  27 *
  28 Does the requested symbol exist within the shared library?
  29 .PP
  30 The warnings checked for include:
  31 .TP
  32 *
  33 Is the target shared library a versioned library?  (Relevant only on Unix
  34 systems, not Mac OS X or Windows.)
  35 .PP
  36 In general, only versioned libraries such as libc.so.6 are present on the
  37 user's machine, and efforts to load libc.so will result in a
  38 System.DllNotFoundException.  There are three solutions to this:
  39 .TP
  40 1.
  41 Require that the user install any -devel packages which provide the
  42 unversioned library.  This usually requires that the user install a large
  43 number of additional packages, complicating the installation process.
  44 .TP
  45 2.
  46 Use a fully versioned name in your DllImport statements.  This requires
  47 editing your source code and recompiling whenever you need to target a
  48 different version of the shared library.
  49 .TP
  50 3.
  51 Provide an assembly.config file which contains <dllmap/> elements to remap
  52 the shared library name used by your assembly to the actual versioned shared
  53 library present on the users system.  Mono provides a number of pre-existing
  54 <dllmap/> entries, including libc.so and libX11.so.
  55 .SH EXAMPLE
  56 The following code contains examples of the above errors and warnings:
  57 .nf
  58         using System.Runtime.InteropServices; // for DllImport
  59         class Demo {
  60                 [DllImport ("bad-library-name")]
  61                 private static extern void BadLibraryName ();
  62
  63                 [DllImport ("libc.so")]
  64                 private static extern void BadSymbolName ();
  65
  66                 [DllImport ("libcap.so")]
  67                 private static extern int cap_clear (IntPtr cap_p);
  68         }
  69 .fi
  70 .TP
  71 Bad library name
  72 Assuming that the library
  73 .B bad-library-name
  74 doesn't exist on your machine, Demo.BadLibraryName will generate an error, as
  75 it requires a shared library which doesn't exist.
  76 .TP
  77 Bad symbol name
  78 Demo.BadSymbolName will generate an error, as libc.so (remapped to libc.so.6
  79 by mono's $prefix/etc/mono/config file) doesn't contain the function
  80 BadSymbolName.
  81 .TP
  82 Unversioned library dependency
  83 Assuming you have the file libcap.so, Demo.cap_clear will generate a
  84 warning because, while libcap.so could be loaded, libcap.so might not exist on
  85 the users machine (on FC2, /lib/libcap.so is provided by
  86 .I libcap-devel
  87 , and you can't assume that end users will have any -devel packages installed).
  88 .SH FIXING CODE
  89 The fix depends on the warning or error:
  90 .TP
  91 Bad library names
  92 Use a valid library name in the DllImport attribute, or provide a <dllmap/>
  93 entry to map your existing library name to a valid library name.
  94 .TP
  95 Bad symbol names
  96 Reference a symbol that actually exists in the target library.
  97 .TP
  98 Unversioned library dependency
  99 Provide a <dllmap/> entry to reference a properly versioned library, or ignore
 100 the warning (see
 101 .B BUGS
 102 ).
 103 .SH DLLMAP ENTRIES
 104 Mono looks for an
 105 .I ASSEMBLY-NAME
 106 \.config file for each assembly loaded, and reads this file to find Dll
 107 mapping information.  For example, with
 108 .I mcs.exe
 109 , Mono would read
 110 .I mcs.exe.config
 111 , and for
 112 .I Mono.Posix.dll
 113 , Mono would read
 114 .I Mono.Posix.dll.config
 115 \.
 116 .PP
 117 The .config file is an XML document containing a top-level <configuration/>
 118 section with nested <dllmap/> entries, which contains
 119 .B dll
 120 and
 121 .B target
 122 attributes.  The dll attribute should contain the same string used in your
 123 DllImport attribute value, and the target attribute specifies which shared
 124 library mono should
 125 .I actually
 126 load at runtime.
 127 .PP
 128 A sample .config file is:
 129 .nf
 130         <configuration>
 131                 <dllmap dll="gtkembedmoz" target="libgtkembedmoz.so" />
 132         </configuration>
 133 .fi
 134 .SH BUGS
 135 .I mono-shlib-cop
 136 currently only examines the shared library file extension to determine if a
 137 warning should be generated.  A
 138 .I .so
 139 extension will always generate a warning, even if the .so is not a symlink,
 140 isn't provided in a -devel package, and there is no versioned shared library
 141 (possible examples including /usr/lib/libtcl8.4.so, /usr/lib/libubsec.so,
 142 etc.).
 143 .PP
 144 Consequently, warnings for any such libraries are useless, and incorrect.
 145 .PP
 146 Windows and Mac OS X will never generate warnings, as these
 147 platforms use different shared library extensions.
 148 .SH MAILING LISTS
 149 Visit http://lists.ximian.com/mailman/listinfo/mono-devel-list for details.
 150 .SH WEB SITE
 151 Visit http://www.mono-project.com for details