xenial (1) mono-shlib-cop.1.gz

Provided by: mono-devel_4.2.1.102+dfsg2-7ubuntu4_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)