* ChangeLog: Started

  * mono-shlib-cop.1: Document another BUG/design issue that it doesn't check
    for; formatting/style changes.

svn path=/trunk/mono/; revision=56121

1 files changed, 121 insertions, 26 deletions

diff --git a/man/mono-shlib-cop.1 b/man/mono-shlib-cop.1
index 4a9bf51a72a..79a397197e6 100644
--- a/man/mono-shlib-cop.1
+++ b/man/mono-shlib-cop.1
@@ -1,3 +1,13 @@
+.\" 
+.\" mono-shlib-cop manual page.
+.\" (C) 2005-2006 Jonathan Pryor
+.\" Author:
+.\"   Jonathan Pryor (jonpryor@vt.edu)
+.\"
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
 .TH "mono-shlib-cop" 1
 .SH NAME
 mono-shlib-cop \- Shared Library Usage Checker
@@ -14,7 +24,7 @@ correct.
 .SH DESCRIPTION
 .I mono-shlib-cop 
 is a tool that inspects a managed assembly looking for
-erroneous or suspecious behavior of shared libraries.
+erroneous or suspecious usage of shared libraries.
 .PP
 The tool takes one or more assembly filenames, and inspects each assembly
 specified.
@@ -33,25 +43,39 @@ The warnings checked for include:
 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:
+In general, only versioned libraries such as 
+.I libc.so.6 
+are present on the 
+user's machine, and efforts to load 
+.I libc.so 
+will result in a 
+.B System.DllNotFoundException.  
+There are three solutions to this:
 .TP 
 1.
-Require that the user install any -devel packages which provide the 
+Require that the user install any 
+.I -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
+Use a fully versioned name in your 
+.B 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
+Provide an 
+.I 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.
+<dllmap/> entries, including ones for 
+.I libc.so 
+and 
+.I libX11.so.
 .SH EXAMPLE
 The following code contains examples of the above errors and warnings:
 .nf
@@ -70,26 +94,52 @@ The following code contains examples of the above errors and warnings:
 .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.
+.I bad-library-name
+doesn't exist on your machine, 
+.I Demo.BadLibraryName 
+will generate an error, as
+it requires a shared library which cannot be loaded.
+This may be ignorable; see 
+.B BUGS
+.
 .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.
+.I Demo.BadSymbolName 
+will generate an error, as 
+.I libc.so 
+(remapped to 
+.I libc.so.6
+by mono's 
+.I $prefix/etc/mono/config 
+file) doesn't contain the function
+.I 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 
+Assuming you have the file 
+.I libcap.so
+, 
+.I Demo.cap_clear 
+will generate a
+warning because, while 
+.I libcap.so 
+could be loaded, 
+.I libcap.so 
+might not exist on
+the users machine (on FC2, 
+.I /lib/libcap.so 
+is provided by 
 .I libcap-devel
-, and you can't assume that end users will have any -devel packages installed).
+, and you can't assume that end users will have any 
+.I "-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/>
+Use a valid library name in the 
+.B DllImport 
+attribute, or provide a <dllmap/>
 entry to map your existing library name to a valid library name.
 .TP
 Bad symbol names
@@ -114,13 +164,16 @@ mapping information.  For example, with
 .I Mono.Posix.dll.config
 \.
 .PP
-The .config file is an XML document containing a top-level <configuration/>
+The 
+.I .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
+.B DllImport 
+attribute value, and the target attribute specifies which shared
 library mono should 
 .I actually
 load at runtime.
@@ -132,17 +185,59 @@ A sample .config file is:
 	</configuration>
 .fi
 .SH BUGS
+.TP
+*
+Only 
+.B 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:
+.nf
+	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 ();
+			}
+		}
+	}
+.fi
+If 
+.I mono-shlib-cop
+is run on this assembly, an error will be reported for using
+.I kernel32.dll
+, even though 
+.I kernel32.dll
+will never be used on Unix platforms.
+.TP 
+*
 .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,
+extension will always generate a warning, even if the 
+.I .so 
+is not a symlink,
+isn't provided in a 
+.I -devel 
+package, and there is no versioned shared library 
+(possible examples including 
+.I /usr/lib/libtcl8.4.so, 
+.I /usr/lib/libubsec.so,
 etc.).
-.PP
+.Sp
 Consequently, warnings for any such libraries are useless, and incorrect.
-.PP
+.Sp
 Windows and Mac OS X will never generate warnings, as these
 platforms use different shared library extensions.
 .SH MAILING LISTS