diff options
author | Jonathan Pryor <jpryor@novell.com> | 2005-06-13 19:10:49 +0400 |
---|---|---|
committer | Jonathan Pryor <jpryor@novell.com> | 2005-06-13 19:10:49 +0400 |
commit | 403f701b50937526cbd7627a166f3c535cf4fafc (patch) | |
tree | 225c1ed90f52acd3679fc94ea22fcfd14c9e50ed /man/mono-shlib-cop.1 | |
parent | 0435e44a4a373e431387d818bf4fc524b0c21603 (diff) |
* man/mono-shlib-cop.1: Add man page for mono-shlib-cop program.
svn path=/trunk/mono/; revision=45879
Diffstat (limited to 'man/mono-shlib-cop.1')
-rw-r--r-- | man/mono-shlib-cop.1 | 151 |
1 files changed, 151 insertions, 0 deletions
diff --git a/man/mono-shlib-cop.1 b/man/mono-shlib-cop.1 new file mode 100644 index 00000000000..4a9bf51a72a --- /dev/null +++ b/man/mono-shlib-cop.1 @@ -0,0 +1,151 @@ +.TH "mono-shlib-cop" 1 +.SH NAME +mono-shlib-cop \- Shared Library Usage Checker +.SH SYNOPSIS +.B mono-shlib-cop +[OPTIONS]* [ASSEMBLY-FILE-NAME]* +.SH OPTIONS +.TP +.I \-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. +.PP +.SH DESCRIPTION +.I mono-shlib-cop +is a tool that inspects a managed assembly looking for +erroneous or suspecious behavior of shared libraries. +.PP +The tool takes one or more assembly filenames, and inspects each assembly +specified. +.PP +The errors checked for include: +.TP +* +Does the shared library exist? +.TP +* +Does the requested symbol exist within the shared library? +.PP +The warnings checked for include: +.TP +* +Is the target shared library a versioned library? (Relevant only on Unix +systems, not Mac OS X or Windows.) +.PP +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: +.TP +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. +.TP +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. +.TP +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 libc.so and libX11.so. +.SH EXAMPLE +The following code contains examples of the above errors and warnings: +.nf + 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); + } +.fi +.TP +Bad library name +Assuming that the library +.B bad-library-name +doesn't exist on your machine, Demo.BadLibraryName will generate an error, as +it requires a shared library which doesn't exist. +.TP +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. +.TP +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 +.I libcap-devel +, and you can't assume that end users will have any -devel packages installed). +.SH FIXING CODE +The fix depends on the warning or error: +.TP +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. +.TP +Bad symbol names +Reference a symbol that actually exists in the target library. +.TP +Unversioned library dependency +Provide a <dllmap/> entry to reference a properly versioned library, or ignore +the warning (see +.B BUGS +). +.SH DLLMAP ENTRIES +Mono looks for an +.I ASSEMBLY-NAME +\.config file for each assembly loaded, and reads this file to find Dll +mapping information. For example, with +.I mcs.exe +, Mono would read +.I mcs.exe.config +, and for +.I Mono.Posix.dll +, Mono would read +.I Mono.Posix.dll.config +\. +.PP +The .config file is an XML document containing a top-level <configuration/> +section with nested <dllmap/> entries, which contains +.B dll +and +.B 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 +.I actually +load at runtime. +.PP +A sample .config file is: +.nf + <configuration> + <dllmap dll="gtkembedmoz" target="libgtkembedmoz.so" /> + </configuration> +.fi +.SH BUGS +.I mono-shlib-cop +currently only examines the shared library file extension to determine if a +warning should be generated. A +.I .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.). +.PP +Consequently, warnings for any such libraries are useless, and incorrect. +.PP +Windows and Mac OS X will never generate warnings, as these +platforms use different shared library extensions. +.SH MAILING LISTS +Visit http://lists.ximian.com/mailman/listinfo/mono-devel-list for details. +.SH WEB SITE +Visit http://www.mono-project.com for details |