1mono-shlib-cop(1)           General Commands Manual          mono-shlib-cop(1)
2
3
4

NAME

6       mono-shlib-cop - Shared Library Usage Checker
7

SYNOPSIS

9       mono-shlib-cop [OPTIONS]* [ASSEMBLY-FILE-NAME]*
10

OPTIONS

12       -p, --prefixes=PREFIX
13              Mono   installation   prefixes.    This   is   to   find   $pre‐
14              fix/etc/mono/config.  The default is based upon the location  of
15              mscorlib.dll, and is normally correct.
16

DESCRIPTION

18       mono-shlib-cop  is  a tool that inspects a managed assembly looking for
19       erroneous or suspecious usage of shared libraries.
20
21       The tool takes one or more assembly filenames, and inspects each assem‐
22       bly specified.
23
24       The errors checked for include:
25
26       *      Does the shared library exist?
27
28       *      Does the requested symbol exist within the shared library?
29
30       The warnings checked for include:
31
32       *      Is  the  target  shared  library a versioned library?  (Relevant
33              only on Unix systems, not Mac OS X or Windows.)
34
35       In general, only versioned libraries such as libc.so.6 are  present  on
36       the  user's  machine, and efforts to load libc.so will result in a Sys‐
37       tem.DllNotFoundException.  There are three solutions to this:
38
39       1.     Require that the user install any -devel packages which  provide
40              the  unversioned  library.   This usually requires that the user
41              install a large number of additional packages, complicating  the
42              installation process.
43
44       2.     Use  a  fully versioned name in your DllImport statements.  This
45              requires editing your source code and recompiling  whenever  you
46              need to target a different version of the shared library.
47
48       3.     Provide  an  assembly.config  file which contains <dllmap/> ele‐
49              ments to remap the shared library name used by your assembly  to
50              the actual versioned shared library present on the users system.
51              Mono  provides  a  number  of  pre-existing  <dllmap/>  entries,
52              including ones for libc.so and libX11.so.
53

EXAMPLE

55       The following code contains examples of the above errors and warnings:
56            using System.Runtime.InteropServices; // for DllImport
57            class Demo {
58                 [DllImport ("bad-library-name")]
59                 private static extern void BadLibraryName ();
60
61                 [DllImport ("libc.so")]
62                 private static extern void BadSymbolName ();
63
64                 [DllImport ("libcap.so")]
65                 private static extern int cap_clear (IntPtr cap_p);
66            }
67
68       Bad library name
69              Assuming that the library bad-library-name doesn't exist on your
70              machine, Demo.BadLibraryName  will  generate  an  error,  as  it
71              requires  a  shared library which cannot be loaded.  This may be
72              ignorable; see BUGS
73
74       Bad symbol name
75              Demo.BadSymbolName will generate an error, as libc.so  (remapped
76              to  libc.so.6  by  mono's  $prefix/etc/mono/config file) doesn't
77              contain the function BadSymbolName
78
79       Unversioned library dependency
80              Assuming you have the file libcap.so , Demo.cap_clear will  gen‐
81              erate  a  warning because, while libcap.so could be loaded, lib‐
82              cap.so might not exist on the users machine (on  FC2,  /lib/lib‐
83              cap.so  is  provided by libcap-devel , and you can't assume that
84              end users will have any -devel packages installed).
85

FIXING CODE

87       The fix depends on the warning or error:
88
89       Bad library names
90              Use a valid library name in the DllImport attribute, or  provide
91              a  <dllmap/>  entry to map your existing library name to a valid
92              library name.
93
94       Bad symbol names
95              Reference a symbol that actually exists in the target library.
96
97       Unversioned library dependency
98              Provide a <dllmap/> entry  to  reference  a  properly  versioned
99              library, or ignore the warning (see BUGS ).
100

DLLMAP ENTRIES

102       Mono looks for an ASSEMBLY-NAME mapping information.  For example, with
103       mcs.exe , Mono would read mcs.exe.config ,  and  for  Mono.Posix.dll  ,
104       Mono would read Mono.Posix.dll.config
105
106       The  .config file is an XML document containing a top-level <configura‐
107       tion/> section with nested <dllmap/> entries, which  contains  dll  and
108       target  attributes.   The  dll attribute should contain the same string
109       used in your DllImport attribute value, and the target attribute speci‐
110       fies which shared library mono should actually load at runtime.
111
112       A sample .config file is:
113            <configuration>
114                 <dllmap dll="gtkembedmoz" target="libgtkembedmoz.so" />
115            </configuration>
116

BUGS

118       *      Only  DllImport  entries  are  checked;  the  surrounding  IL is
119              ignored.  Consequently, if  a  runtime  check  is  performed  to
120              choose which shared library to invoke, an error will be reported
121              even though the specified library is never used.  Consider  this
122              code:
123                   using System.Runtime.InteropServices; // for DllImport
124                   class Beep {
125                        [DllImport ("kernel32.dll")]
126                        private static extern int Beep (int dwFreq, int dwDuration);
127
128                        [DllImport ("libcurses.so")]
129                        private static extern int beep ();
130
131                        public static void Beep ()
132                        {
133                             if (System.IO.Path.DirectorySeparatorChar == '\\') {
134                                  Beep (750, 300);
135                             }
136                             else {
137                                  beep ();
138                             }
139                        }
140                   }
141              If  mono-shlib-cop  is  run  on  this assembly, an error will be
142              reported for using kernel32.dll , even though kernel32.dll  will
143              never be used on Unix platforms.
144
145       *      mono-shlib-cop  currently  only examines the shared library file
146              extension to determine if a warning should be generated.  A  .so
147              extension will always generate a warning, even if the .so is not
148              a symlink, isn't provided in a -devel package, and there  is  no
149              versioned    shared   library   (possible   examples   including
150              /usr/lib/libtcl8.4.so, /usr/lib/libubsec.so, etc.).
151
152              Consequently, warnings for any such libraries are  useless,  and
153              incorrect.
154
155              Windows  and  Mac  OS  X  will never generate warnings, as these
156              platforms use different shared library extensions.
157

MAILING LISTS

159       Visit   http://lists.ximian.com/mailman/listinfo/mono-devel-list    for
160       details.
161

WEB SITE

163       Visit http://www.mono-project.com for details
164
165
166
167                                                             mono-shlib-cop(1)
Impressum