Provided by: mono-devel_3.2.8+dfsg-4ubuntu1_all bug

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 System.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 specifies 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   versioned   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)