Merge pull request #5714 from alexischr/update_bockbuild

[mono.git] / man / mono-shlib-cop.1

diff --git a/man/mono-shlib-cop.1 b/man/mono-shlib-cop.1
index 4a9bf51a72ac4158521fbdf8196a5eaddd8edc7d..79a397197e6bb62e294409c616b754747c784a1b 100644 (file)
--- 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
 .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
 .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.
 .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
 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.
 .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.
 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.
 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
 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
 .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 
 .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
 .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
 .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
 .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
 .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
 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
 .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
 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.
 library mono should 
 .I actually
 load at runtime.


@@ -132,17 +185,59 @@ A sample .config file is:
        </configuration>
 .fi
 .SH BUGS
        </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
 .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.).
 etc.).

-.PP
+.Sp

 Consequently, warnings for any such libraries are useless, and incorrect.
 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
 Windows and Mac OS X will never generate warnings, as these
 platforms use different shared library extensions.
 .SH MAILING LISTS