man/mono-shlib-cop.1

   1 .\"
   2 .\" mono-shlib-cop manual page.
   3 .\" (C) 2005-2006 Jonathan Pryor
   4 .\" Author:
   5 .\"   Jonathan Pryor (jonpryor@vt.edu)
   6 .\"
   7 .de Sp \" Vertical space (when we can't use .PP)
   8 .if t .sp .5v
   9 .if n .sp
  10 ..
  11 .TH "mono-shlib-cop" 1
  12 .SH NAME
  13 mono-shlib-cop \- Shared Library Usage Checker
  14 .SH SYNOPSIS
  15 .B mono-shlib-cop
  16 [OPTIONS]* [ASSEMBLY-FILE-NAME]*
  17 .SH OPTIONS
  18 .TP
  19 .I \-p, --prefixes=PREFIX
  20 Mono installation prefixes.  This is to find $prefix/etc/mono/config.
  21 The default is based upon the location of mscorlib.dll, and is normally
  22 correct.
  23 .PP
  24 .SH DESCRIPTION
  25 .I mono-shlib-cop
  26 is a tool that inspects a managed assembly looking for
  27 erroneous or suspecious usage of shared libraries.
  28 .PP
  29 The tool takes one or more assembly filenames, and inspects each assembly
  30 specified.
  31 .PP
  32 The errors checked for include:
  33 .TP
  34 *
  35 Does the shared library exist?
  36 .TP
  37 *
  38 Does the requested symbol exist within the shared library?
  39 .PP
  40 The warnings checked for include:
  41 .TP
  42 *
  43 Is the target shared library a versioned library?  (Relevant only on Unix
  44 systems, not Mac OS X or Windows.)
  45 .PP
  46 In general, only versioned libraries such as
  47 .I libc.so.6
  48 are present on the
  49 user's machine, and efforts to load
  50 .I libc.so
  51 will result in a
  52 .B System.DllNotFoundException.
  53 There are three solutions to this:
  54 .TP
  55 1.
  56 Require that the user install any
  57 .I -devel
  58 packages which provide the
  59 unversioned library.  This usually requires that the user install a large
  60 number of additional packages, complicating the installation process.
  61 .TP
  62 2.
  63 Use a fully versioned name in your
  64 .B DllImport
  65 statements.  This requires
  66 editing your source code and recompiling whenever you need to target a
  67 different version of the shared library.
  68 .TP
  69 3.
  70 Provide an
  71 .I assembly.config
  72 file which contains <dllmap/> elements to remap
  73 the shared library name used by your assembly to the actual versioned shared
  74 library present on the users system.  Mono provides a number of pre-existing
  75 <dllmap/> entries, including ones for
  76 .I libc.so
  77 and
  78 .I libX11.so.
  79 .SH EXAMPLE
  80 The following code contains examples of the above errors and warnings:
  81 .nf
  82         using System.Runtime.InteropServices; // for DllImport
  83         class Demo {
  84                 [DllImport ("bad-library-name")]
  85                 private static extern void BadLibraryName ();
  86
  87                 [DllImport ("libc.so")]
  88                 private static extern void BadSymbolName ();
  89
  90                 [DllImport ("libcap.so")]
  91                 private static extern int cap_clear (IntPtr cap_p);
  92         }
  93 .fi
  94 .TP
  95 Bad library name
  96 Assuming that the library
  97 .I bad-library-name
  98 doesn't exist on your machine,
  99 .I Demo.BadLibraryName
 100 will generate an error, as
 101 it requires a shared library which cannot be loaded.
 102 This may be ignorable; see
 103 .B BUGS
 104 .
 105 .TP
 106 Bad symbol name
 107 .I Demo.BadSymbolName
 108 will generate an error, as
 109 .I libc.so
 110 (remapped to
 111 .I libc.so.6
 112 by mono's
 113 .I $prefix/etc/mono/config
 114 file) doesn't contain the function
 115 .I BadSymbolName
 116 .
 117 .TP
 118 Unversioned library dependency
 119 Assuming you have the file
 120 .I libcap.so
 121 ,
 122 .I Demo.cap_clear
 123 will generate a
 124 warning because, while
 125 .I libcap.so
 126 could be loaded,
 127 .I libcap.so
 128 might not exist on
 129 the users machine (on FC2,
 130 .I /lib/libcap.so
 131 is provided by
 132 .I libcap-devel
 133 , and you can't assume that end users will have any
 134 .I "-devel"
 135 packages installed).
 136 .SH FIXING CODE
 137 The fix depends on the warning or error:
 138 .TP
 139 Bad library names
 140 Use a valid library name in the
 141 .B DllImport
 142 attribute, or provide a <dllmap/>
 143 entry to map your existing library name to a valid library name.
 144 .TP
 145 Bad symbol names
 146 Reference a symbol that actually exists in the target library.
 147 .TP
 148 Unversioned library dependency
 149 Provide a <dllmap/> entry to reference a properly versioned library, or ignore
 150 the warning (see
 151 .B BUGS
 152 ).
 153 .SH DLLMAP ENTRIES
 154 Mono looks for an
 155 .I ASSEMBLY-NAME
 156 \.config file for each assembly loaded, and reads this file to find Dll
 157 mapping information.  For example, with
 158 .I mcs.exe
 159 , Mono would read
 160 .I mcs.exe.config
 161 , and for
 162 .I Mono.Posix.dll
 163 , Mono would read
 164 .I Mono.Posix.dll.config
 165 \.
 166 .PP
 167 The
 168 .I .config
 169 file is an XML document containing a top-level <configuration/>
 170 section with nested <dllmap/> entries, which contains
 171 .B dll
 172 and
 173 .B target
 174 attributes.  The dll attribute should contain the same string used in your
 175 .B DllImport
 176 attribute value, and the target attribute specifies which shared
 177 library mono should
 178 .I actually
 179 load at runtime.
 180 .PP
 181 A sample .config file is:
 182 .nf
 183         <configuration>
 184                 <dllmap dll="gtkembedmoz" target="libgtkembedmoz.so" />
 185         </configuration>
 186 .fi
 187 .SH BUGS
 188 .TP
 189 *
 190 Only
 191 .B DllImport
 192 entries are checked; the surrounding IL is ignored.  Consequently, if a runtime
 193 check is performed to choose which shared library to invoke, an error will be
 194 reported even though the specified library is never used.  Consider this code:
 195 .nf
 196         using System.Runtime.InteropServices; // for DllImport
 197         class Beep {
 198                 [DllImport ("kernel32.dll")]
 199                 private static extern int Beep (int dwFreq, int dwDuration);
 200
 201                 [DllImport ("libcurses.so")]
 202                 private static extern int beep ();
 203
 204                 public static void Beep ()
 205                 {
 206                         if (System.IO.Path.DirectorySeparatorChar == '\\\\') {
 207                                 Beep (750, 300);
 208                         }
 209                         else {
 210                                 beep ();
 211                         }
 212                 }
 213         }
 214 .fi
 215 If
 216 .I mono-shlib-cop
 217 is run on this assembly, an error will be reported for using
 218 .I kernel32.dll
 219 , even though
 220 .I kernel32.dll
 221 will never be used on Unix platforms.
 222 .TP
 223 *
 224 .I mono-shlib-cop
 225 currently only examines the shared library file extension to determine if a
 226 warning should be generated.  A
 227 .I .so
 228 extension will always generate a warning, even if the
 229 .I .so
 230 is not a symlink,
 231 isn't provided in a
 232 .I -devel
 233 package, and there is no versioned shared library
 234 (possible examples including
 235 .I /usr/lib/libtcl8.4.so,
 236 .I /usr/lib/libubsec.so,
 237 etc.).
 238 .Sp
 239 Consequently, warnings for any such libraries are useless, and incorrect.
 240 .Sp
 241 Windows and Mac OS X will never generate warnings, as these
 242 platforms use different shared library extensions.
 243 .SH MAILING LISTS
 244 Visit http://lists.ximian.com/mailman/listinfo/mono-devel-list for details.
 245 .SH WEB SITE
 246 Visit http://www.mono-project.com for details