check for iconv only once (#7873)
[mono-project.git] / man / mono-shlib-cop.1
blob79a397197e6bb62e294409c616b754747c784a1b
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
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 
35 Does the shared library exist?
36 .TP
38 Does the requested symbol exist within the shared library?
39 .PP
40 The warnings checked for include:
41 .TP
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 
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
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
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 ();
87                 [DllImport ("libc.so")]
88                 private static extern void BadSymbolName ();
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
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
118 Unversioned library dependency
119 Assuming you have the file 
120 .I libcap.so
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:
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.
145 Bad symbol names
146 Reference a symbol that actually exists in the target library.
148 Unversioned library dependency
149 Provide a <dllmap/> entry to reference a properly versioned library, or ignore
150 the warning (see 
151 .B BUGS
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
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
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.
181 A sample .config file is:
183         <configuration>
184                 <dllmap dll="gtkembedmoz" target="libgtkembedmoz.so" />
185         </configuration>
187 .SH BUGS
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:
196         using System.Runtime.InteropServices; // for DllImport
197         class Beep {
198                 [DllImport ("kernel32.dll")]
199                 private static extern int Beep (int dwFreq, int dwDuration);
201                 [DllImport ("libcurses.so")]
202                 private static extern int beep ();
204                 public static void Beep ()
205                 {
206                         if (System.IO.Path.DirectorySeparatorChar == '\\\\') {
207                                 Beep (750, 300);
208                         }
209                         else {
210                                 beep ();
211                         }
212                 }
213         }
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 
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.).
239 Consequently, warnings for any such libraries are useless, and incorrect.
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