Use __pthread_sig_cancel and __pthread_sig_restart everywhere instead
[kopensolaris-gnu/glibc.git] / FAQ
diff --git a/FAQ b/FAQ
index f1ba410..c4ab812 100644 (file)
--- a/FAQ
+++ b/FAQ
@@ -5,7 +5,7 @@ and using glibc.  Please make sure you read this before sending questions or
 bug reports to the maintainers.
 
 The GNU C library is very complex.  The installation process has not been
-completely automated; there are too many variables. You can do substantial
+completely automated; there are too many variables.  You can do substantial
 damage to your system by installing the library incorrectly.  Make sure you
 understand what you are undertaking before you begin.
 
@@ -38,6 +38,7 @@ please let me know.
 1.13.  Why do I get messages about missing thread functions when I use
        librt?  I don't even use threads.
 1.14.  What's the problem with configure --enable-omitfp?
+1.15.  I get failures during `make check'.  What shall I do?
 
 2. Installation and configuration issues
 
@@ -85,6 +86,8 @@ please let me know.
 2.20.  What do I need for C++ development?
 2.21.  Even statically linked programs need some shared libraries
        which is not acceptable for me.  What can I do?
+2.22.  I just upgraded my Linux system to glibc and now I get
+       errors whenever I try to link any program.
 
 3. Source and binary incompatibilities, and what to do about them
 
@@ -123,6 +126,7 @@ please let me know.
 4.3.   When I set the timezone by setting the TZ environment variable
        to EST5EDT things go wrong since glibc computes the wrong time
        from this information.
+4.4.   What other sources of documentation about glibc are available?
 
 \f
 ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ 
@@ -171,7 +175,7 @@ GNU CC is found, like all other GNU packages, on
 and the many mirror sites.  ftp.gnu.org is always overloaded, so try to find
 a local mirror first.
 
-You always should try to use the latest official release.  Older versions
+You should always try to use the latest official release.  Older versions
 may not have all the features GNU libc requires.  The current releases of
 egcs (1.0.2) and GNU CC (2.8.1) should work with the GNU C library (for
 powerpc see question question 1.5).
@@ -276,6 +280,17 @@ on a recent kernel) does not necessarily work.  For example you can't use
 new kernel features when using old kernel headers for compiling the GNU C
 library.
 
+{ZW} Even if you are using a 2.0 kernel on your machine, we recommend you
+compile GNU libc with 2.1 kernel headers.  That way you won't have to
+recompile libc if you ever upgrade to kernel 2.1 or 2.2.  To tell libc which
+headers to use, give configure the --with-headers switch
+(e.g. --with-headers=/usr/src/linux-2.1.107/include).
+
+Note that you must configure the 2.1 kernel if you do this; otherwise libc
+will be unable to find <linux/version.h>.  Just copy .config from your 2.0
+kernel sources to the 2.1 tree, do `make oldconfig', and say no to all the
+new options.
+
 
 1.8.   The compiler hangs while building iconvdata modules.  What's
        wrong?
@@ -376,10 +391,10 @@ any other link path.
 1.14.  What's the problem with configure --enable-omitfp?
 
 {AJ} When --enable-omitfp is set the libraries are built without frame
-pointers. Some compilers produce buggy code for this model and therefore we
+pointers.  Some compilers produce buggy code for this model and therefore we
 don't advise using it at the moment.
 
-If you use --enable-omitfp, you're on your own. If you encounter problems
+If you use --enable-omitfp, you're on your own.  If you encounter problems
 with a library that was build this way, we advise you to rebuild the library
 without --enable-omitfp.  If the problem vanishes consider tracking the
 problem down and report it as compiler failure.
@@ -391,6 +406,30 @@ the library names.
 The compilation of these extra libraries and the compiler optimizations slow
 down the build process and need more disk space.
 
+
+1.15.  I get failures during `make check'.  What shall I do?
+
+{AJ} The testsuite should compile and run cleanly on your system, every
+failure should be looked into.  Depending on the failure I wouldn't advise
+installing the library at all.
+
+You should consider using the `glibcbug' script to report the failure,
+providing as much detail as possible.  If you run a test directly, please
+remember to set up the environment correctly.  You want to test the compiled
+library - and not your installed one.  The best way is to copy the exact
+command line which failed and run the test from the subdirectory for this
+test in the sources.
+
+There are some failures which are not directly related to the GNU libc:
+- Some compiler produce buggy code.  The current egcs snapshots are ok and
+  the not yet released egcs 1.1 should be ok.  gcc 2.8.1 might cause some
+  failures, gcc 2.7.2.x is so buggy, that explicit checks have been used so
+  that you can't build with it.
+- The kernel might have bugs.  For example on Linux/Alpha 2.0.34 the
+  floating point handling has quite a number of bugs and therefore most of
+  the test cases in the math subdirectory will fail.  The current Linux 2.1
+  development kernels have fixes for the floating point support on Alpha.
+
 \f
 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 
 
@@ -802,6 +841,25 @@ option is using NSS.  There is no switch anymore.  Therefore it is
 *highly* recommended *not* to use --enable-static-nss since this makes
 the behaviour of the programs on the system inconsistent.
 
+
+2.22.  I just upgraded my Linux system to glibc and now I get
+       errors whenever I try to link any program.
+
+{ZW} This happens when you have installed glibc as the primary C library but
+have stray symbolic links pointing at your old C library.  If the first
+`libc.so' the linker finds is libc 5, it will use that.  Your program
+expects to be linked with glibc, so the link fails.
+
+The most common case is that glibc put its `libc.so' in /usr/lib, but there
+was a `libc.so' from libc 5 in /lib, which gets searched first.  To fix the
+problem, just delete /lib/libc.so.  You may also need to delete other
+symbolic links in /lib, such as /lib/libm.so if it points to libm.so.5.
+
+{AJ} The perl script test-installation.pl which is run as last step during
+an installation of glibc that is configured with --prefix=/usr should help
+detect these situations.  If the script reports problems, something is
+really screwed up.
+
 \f
 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 
 
@@ -995,11 +1053,11 @@ siginterrupt().
        functions.  Why?
 
 {AJ} glibc 2.1 has special string functions that are faster than the normal
-library functions. Some of the functions are additionally implemented as
+library functions.  Some of the functions are additionally implemented as
 inline functions and others as macros.
 
 The optimized string functions are only used when compiling with
-optimizations (-O1 or higher). The behavior can be changed with two feature
+optimizations (-O1 or higher).  The behavior can be changed with two feature
 macros:
 
 * __NO_STRING_INLINES: Don't do any string optimizations.
@@ -1008,7 +1066,7 @@ macros:
 
 Since some of these string functions are now additionally defined as macros,
 code like "char *strncpy();" doesn't work anymore (and is unnecessary, since
-<string.h> has the necessary declarations). Either change your code or
+<string.h> has the necessary declarations).  Either change your code or
 define __NO_STRING_INLINES.
 
 {UD} Another problem in this area is that gcc still has problems on machines
@@ -1033,22 +1091,37 @@ This disables the optimization for that specific call.
 {RM,AJ} Constructs like:
 static FILE *InPtr = stdin;
 
-lead to this message. This is correct behaviour with glibc since stdin is
-not a constant expression. Please note that a strict reading of ISO C does
+lead to this message.  This is correct behaviour with glibc since stdin is
+not a constant expression.  Please note that a strict reading of ISO C does
 not allow above constructs.
 
 One of the advantages of this is that you can assign to stdin, stdout, and
 stderr just like any other global variable (e.g. `stdout = my_stream;'),
 which can be very useful with custom streams that you can write with libio
-(but beware this is not necessarily portable). The reason to implement it
+(but beware this is not necessarily portable).  The reason to implement it
 this way were versioning problems with the size of the FILE structure.
 
+To fix those programs you've got to initialize the variable at run time.
+This can be done, e.g. in main, like:
+
+static FILE *InPtr;
+int main(void)
+{
+  InPtr = stdin;
+}
+
+or by constructors (beware this is gcc specific):
+
+static FILE *InPtr;
+static void inPtr_construct (void) __attribute__((constructor));
+static void inPtr_construct (void) { InPtr = stdin; }
+
 
 3.10.  I can't compile with gcc -traditional (or
        -traditional-cpp). Why?
 
 {AJ} glibc2 does break -traditional and -traditonal-cpp - and will continue
-to do so. For example constructs of the form:
+to do so.  For example constructs of the form:
 
 enum {foo
 #define foo foo
@@ -1063,7 +1136,7 @@ check with #ifdef).
 
 {AJ} The GNU C library is compatible with the ANSI/ISO C standard.  If
 you're using `gcc -ansi', the glibc includes which are specified in the
-standard follow the standard. The ANSI/ISO C standard defines what has to be
+standard follow the standard.  The ANSI/ISO C standard defines what has to be
 in the include files - and also states that nothing else should be in the
 include files (btw. you can still enable additional standards with feature
 flags).
@@ -1134,6 +1207,20 @@ So, please avoid sending bug reports about time related problems if you use
 the POSIX method and you have not verified something is really broken by
 reading the POSIX standards.
 
+
+4.4.   What other sources of documentation about glibc are available?
+
+{AJ} The FSF has a page about the GNU C library at
+<http://www.gnu.org/software/libc/>.  The problem data base of open and
+solved bugs in GNU libc is available at
+<http://www-gnats.gnu.org:8080/cgi-bin/wwwgnats.pl>.  Eric Green has written
+a HowTo for converting from Linux libc5 to glibc2.  The HowTo is accessable
+via the FSF page and at <http://www.imaxx.net/~thrytis/glibc>.  Frodo
+Looijaard describes a different way installing glibc2 as secondary libc at
+<http://huizen.dds.nl/~frodol/glibc>.
+
+Please note that this is not a complete list.
+
 \f
 ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~