mono-shlib-cop

SYNOPSIS
       mono-shlib-cop [OPTIONS]* [ASSEMBLY-FILE-NAME]*

OPTIONS
       -p, --prefixes=PREFIX
              Mono   installation   prefixes.    This   is   to   find   $pre-
              fix/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 assem-
       bly 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/> ele-
              ments 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 ();


       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  gen-
              erate  a  warning because, while libcap.so could be loaded, lib-
              cap.so might not exist on the users machine (on  FC2,  /lib/lib-
              cap.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 <configura-
       tion/> 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 speci-
       fies 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);
                        }
                   }
              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)