update from main archive 960921
[kopensolaris-gnu/glibc.git] / FAQ
1                 Frequently Asked Question on GNU C Library
2
3 As every FAQ this one also tries to answer questions the user might have
4 when using the package.  Please make sure you read this before sending
5 questions or bug reports to the maintainers.
6
7 The GNU C Library is very complex.  The building process exploits the
8 features available in tools generally available.  But many things can
9 only be done using GNU tools.  Also the code is sometimes hard to
10 understand because it has to be portable but on the other hand must be
11 fast.  But you need not understand the details to use GNU C Library.
12 This will only be necessary if you intend to contribute or change it.
13
14 If you have any questions you think should be answered in this document,
15 please let me know.
16
17                                                   --drepper@cygnus.com
18 \f
19 ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
20 [Q1]    ``What systems does the GNU C Library run on?''
21
22 [Q2]    ``What compiler do I need to build GNU libc?''
23
24 [Q3]    ``When starting make I get only error messages.
25           What's wrong?''
26
27 [Q4]    ``After I changed configure.in I get `Autoconf version X.Y.
28           or higher is required for this script'.  What can I do?''
29
30 [Q5]    ``Do I need a special linker or archiver?''
31
32 [Q6]    ``Do I need some more things to compile GNU C Library?''
33
34 [Q7]    ``When I run `nm -u libc.so' on the produced library I still
35           find unresolved symbols?  Can this be ok?''
36
37 [Q8]    ``Can I replace the libc on my Linux system with GNU libc?''
38
39 [Q9]    ``I expect GNU libc to be 100% source code compatible with
40           the old Linux based GNU libc.  Why isn't it like this?''
41
42 [Q10]   ``Why does getlogin() always return NULL on my Linux box?''
43
44 [Q11]   ``Where are the DST_* constants found in <sys/time.h> on many
45           systems?''
46
47 [Q12]   ``The `gencat' utility cannot process the input which are
48           successfully used on my Linux libc based system.  Why?''
49
50 [Q13]   ``How do I configure GNU libc so that the essential libraries
51           like libc.so go into /lib and the other into /usr/lib?''
52
53 [Q14]   ``When linking with the new libc I get unresolved symbols
54           `crypt' and `setkey'.  Why aren't these functions in the
55           libc anymore?''
56
57 [Q15]   ``What are these `add-ons'?''
58 \f
59 ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
60 [Q1]    ``What systems does the GNU C Library run on?''
61
62 [A1] {UD} This is difficult to answer.  The file `README' lists the
63 architectures GNU libc is known to run *at some time*.  This does not
64 mean that it still can be compiled and run on them in the moment.
65
66 The systems glibc is known to work on in the moment and most probably
67 in the future are:
68
69         *-*-gnu                 GNU Hurd
70         i[3456]86-*-linux       Linux-2.0 on Intel
71         m68k-*-linux            Linux-2.0 on Motorola 680x0
72         alpha-*-linux           Linux-2.0 on DEC Alpha
73
74 Other Linux platforms are also on the way to be supported but I need
75 some success reports first.
76
77 If you have a system not listed above (or in the `README' file) and
78 you are really interested in porting it, contact
79
80         <bug-glibc@prep.ai.mit.edu>
81
82
83 ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
84 [Q2]    ``What compiler do I need to build GNU libc?''
85
86 [A2] {UD} It is (almost) impossible to compile GNU C Library using a
87 different compiler than GNU CC.  A lot of extensions of GNU CC are
88 used to increase the portability and speed.
89
90 But this does not mean you have to use GNU CC for using the GNU C
91 Library.  In fact you should be able to use the native C compiler
92 because the success only depends on the binutils: the linker and
93 archiver.
94
95 The GNU CC is found like all other GNU packages on
96         ftp://prep.ai.mit.edu/pub/gnu
97 or better one of the many mirror sites.
98
99 You always should try to use the latest official release.  Older
100 versions might not have all the features GNU libc could use.
101
102
103 ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
104 [Q3]    ``When starting `make' I get only errors messages.
105           What's wrong?''
106
107 [A3] {UD} You definitely need GNU make to translate GNU libc.  No
108 other make program has the needed functionality.
109
110 Versions before 3.74 have bugs which prevent correct execution so you
111 should upgrade to the latest version before starting the compilation.
112
113
114 ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
115 [Q4]    ``After I changed configure.in I get `Autoconf version X.Y.
116           or higher is required for this script'.  What can I do?''
117
118 [A4] {UD} You have to get the specified autoconf version (or a later)
119 from your favourite mirror of prep.ai.mit.edu.
120
121
122 ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
123 [Q5]    ``Do I need a special linker or archiver?''
124
125 [A5] {UD} If your native versions are not too buggy you can probably
126 work with them.  But GNU libc works best with GNU binutils.
127
128 On systems where the native linker does not support weak symbols you
129 will not get a really ISO C compliant C library.  Generally speaking
130 you should use the GNU binutils if they provide at least the same
131 functionality as your system's tools.
132
133 Always get the newest release of GNU binutils available.
134 Older releases are known to have bugs that affect building the GNU C
135 Library.
136
137
138 ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
139 [Q6]    ``Do I need some more things to compile GNU C Library?''
140
141 [A6] {UD} Yes, there are some more :-).
142
143 * GNU gettext; the GNU libc is internationalized and partly localized.
144   For bringing the messages for the different languages in the needed
145   form the tools from the GNU gettext package are necessary.  See
146   ftp://prep.ai.mit.edu/pub/gnu or better any mirror site.
147
148 * lots of diskspace (for i?86-linux this means, e.g., ~70MB).
149
150   You should avoid compiling on a NFS mounted device.  This is very
151   slow.
152
153 * plenty of time (approx 1h for i?86-linux on i586@133 or 2.5h on
154   i486@66 or 4.5h on i486@33).
155
156   If you have some more measurements let me know.
157
158 * Some files depend on special tools.  E.g., files ending in .gperf
159   need a `gperf' program.  The GNU version (part of libg++) is known
160   to work while some vendor versions do not.
161
162 * When compiling for Linux:
163
164   + the header files of the Linux kernel must be available in the
165     search path of the CPP as <linux/*.h> and <asm/*.h>.
166
167 * Some files depend on special tools.  E.g., files ending in .gperf
168   need a `gperf' program.  The GNU version (part of libg++) is known
169   to work while some vendor versions do not.
170
171 ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
172 [Q7]    ``When I run `nm -u libc.so' on the produced library I still
173           find unresolved symbols?  Can this be ok?''
174
175 [A7] {UD} Yes, this is ok.  There can be several kinds of unresolved
176 symbols:
177
178 * magic symbols automatically generated by the linker.  Names are
179   often like __start_* and __stop_*
180
181 * symbols starting with _dl_* come from the dynamic linker
182
183 * symbols resolved by using libgcc.a
184   (__udivdi3, __umoddi3, or similar)
185
186 * weak symbols, which need not be resolved at all
187   (currently fabs among others; this gets resolved if the program
188    is linked against libm, too.)
189
190 Generally, you should make sure you find a real program which produces
191 errors while linking before deciding there is a problem.
192
193
194 ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
195 [Q8]    ``Can I replace the libc on my Linux system with GNU libc?''
196
197 [A8] {UD} You cannot replace any existing libc for Linux with GNU
198 libc.  There are different versions of C libraries and you can run
199 libcs with different major version independently.
200
201 For Linux there are today two libc versions:
202         libc-4          old a.out libc
203         libc-5          current ELF libc
204
205 GNU libc will have the major number 6 and therefore you can have this
206 additionally installed.  For more information consult documentation for
207 shared library handling.  The Makefiles of GNU libc will automatically
208 generate the needed symbolic links which the linker will use.
209
210
211 ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
212 [Q9]    ``I expect GNU libc to be 100% source code compatible with
213           the old Linux based GNU libc.  Why isn't it like this?''
214
215 [A9] {DMT,UD} Not every extension in Linux libc's history was well
216 thought-out.  In fact it had a lot of problems with standards compliance
217 and with cleanliness.  With the introduction of a new version number these
218 errors now can be corrected.  Here is a list of the known source code
219 incompatibilities:
220
221 * _GNU_SOURCE: glibc does not automatically define _GNU_SOURCE.  Thus,
222   if a program depends on GNU extensions or some other non-standard
223   functionality, it is necessary to compile it with C compiler option
224   -D_GNU_SOURCE, or better, to put `#define _GNU_SOURCE' at the beginning
225   of your source files, before any C library header files are included.
226   This difference normally manifests itself in the form of missing
227   prototypes and/or data type definitions.  Thus, if you get such errors,
228   the first thing you should do is try defining _GNU_SOURCE and see if
229   that makes the problem go away.
230
231   For more information consult the file `NOTES' part of the GNU C
232   library sources.
233
234 * reboot(): GNU libc sanitizes the interface of reboot() to be more
235   compatible with the interface used on other OSes.  In particular,
236   reboot() as implemented in glibc takes just one argument.  This argument
237   corresponds to the third argument of the Linux reboot system call.
238   That is, a call of the form reboot(a, b, c) needs to be changed into
239   reboot(c).
240      Beside this the header <sys/reboot.h> defines the needed constants
241   for the argument.  These RB_* constants should be used instead of the
242   cryptic magic numbers.
243
244 * swapon(): the interface of this function didn't changed, but the
245   prototype is in a separate header file <sys/swap.h>.  For the additional
246   argument of of swapon() you should use the SWAP_* constants from
247   <linux/swap.h>, which get defined when <sys/swap.h> is included.
248
249 * errno: If a program uses variable "errno", then it _must_ include header
250   file <errno.h>.  The old libc often (erroneously) declared this variable
251   implicitly as a side-effect of including other libc header files.  glibc
252   is careful to avoid such namespace pollution, which, in turn, means that
253   you really need to include the header files that you depend on.  This
254   difference normally manifests itself in the form of the compiler
255   complaining about the references of the undeclared symbol "errno".
256
257 * Linux-specific syscalls: All Linux system calls now have appropriate
258   library wrappers and corresponding declarations in various header files.
259   This is because the syscall() macro that was traditionally used to
260   work around missing syscall wrappers are inherently non-portable and
261   error-prone.  The following tables lists all the new syscall stubs,
262   the header-file declaring their interface and the system call name.
263
264        syscall name:    wrapper name:   declaring header file:
265        -------------    -------------   ----------------------
266        bdflush          bdflush         <sys/kdaemon.h>
267        create_module    create_module   <sys/module.h>
268        delete_module    delete_module   <sys/module.h>
269        get_kernel_syms  get_kernel_syms <sys/module.h>
270        init_module      init_module     <sys/module.h>
271        syslog           ksyslog_ctl     <sys/klog.h>
272
273 * lpd: Older versions of lpd depend on a routine called _validuser().
274   The library does not provide this function, but instead provides
275   __ivaliduser() which has a slightly different interfaces.  Simply
276   upgrading to a newer lpd should fix this problem (e.g., the 4.4BSD
277   lpd is known to be working).
278
279 * resolver functions/BIND: like on many other systems the functions of
280   the resolver library are not included in the libc itself.  There is
281   a separate library libresolv.  If you find some symbols starting with
282   `res_*' undefined simply add -lresolv to your call of the linker.
283
284
285 ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
286 [Q10]   ``Why does getlogin() always return NULL on my Linux box?''
287
288 [A10] {UD} The GNU C library has a format for the UTMP and WTMP file
289 which differs from what your system currently has.  It was extended to
290 fulfill the needs of the next years when IPv6 is introduced.  So the
291 record size is different, fields might have a different position and
292 so reading the files written by functions from the one library cannot
293 be read by functions from the other library.  Sorry, but this is what
294 a major release is for.  It's better to have a cut now than having no
295 means to support the new techniques later.
296
297
298 ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
299 [Q11]   ``Where are the DST_* constants found in <sys/time.h> on many
300           systems?''
301
302 [A11] {UD} These constants come from the old BSD days and are not used
303 today anymore (even the Linux based glibc does not implement the handling
304 although the constants are defined).
305
306 Instead GNU libc contains the zone database handling and compatibility
307 code for POSIX TZ environment variable handling.
308
309
310 ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
311 [Q12]   ``The `gencat' utility cannot process the input which are
312           successfully used on my Linux libc based system.  Why?''
313
314 [A12] {UD} Unlike the author of the `gencat' program which is distributed
315 with Linux libc I have read the underlying standards before writing the
316 code.  It is completely compatible with the specification given in
317 X/Open Portability Guide.
318
319 To ease the transition from the Linux version some of the non-standard
320 features are also present in the `gencat' program of GNU libc.  This
321 mainly includes the use of symbols for the message number and the automatic
322 generation of header files which contain the needed #defines to map the
323 symbols to integers.
324
325 Here is a simple SED script to convert at least some Linux specific
326 catalog files to the XPG4 form:
327
328 -----------------------------------------------------------------------
329 # Change catalog source in Linux specific format to standard XPG format.
330 # Ulrich Drepper <drepper@cygnus.com>, 1996.
331 #
332 /^\$ #/ {
333   h
334   s/\$ #\([^ ]*\).*/\1/
335   x
336   s/\$ #[^ ]* *\(.*\)/\$ \1/
337 }
338
339 /^# / {
340   s/^# \(.*\)/\1/
341   G
342   s/\(.*\)\n\(.*\)/\2 \1/
343 }
344 -----------------------------------------------------------------------
345
346
347 ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
348 [Q13]   ``How do I configure GNU libc so that the essential libraries
349           like libc.so go into /lib and the other into /usr/lib?''
350
351 [A13] {UD} Like all other GNU packages GNU libc is configured to use a
352 base directory and install all files relative to this.  If you intend
353 to really use GNU libc on your system this base directory is /usr.  I.e.,
354 you run
355         configure --prefix=/usr <other_options>
356
357 Some systems like Linux have a filesystem standard which makes a
358 difference between essential libraries and others.  Essential
359 libraries are placed in /lib because this directory is required to be
360 located on the same disk partition as /.  The /usr subtree might be
361 found on another partition/disk.
362
363 To install the essential libraries which come with GNU libc in /lib
364 one must explicitly tell this.  Autoconf has no option for this so you
365 have to use the file where all user supplied additional information
366 should go in: `configparms' (see the `INSTALL' file).  For Linux the
367 `configparms' file should contain:
368
369 slibdir=/lib
370 sysconfdir=/etc
371
372 The first line specifies the directory for the essential libraries,
373 the second line the directory for file which are by tradition placed
374 in a directory named /etc.
375
376
377 ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
378 [Q14]   ``When linking with the new libc I get unresolved symbols
379           `crypt' and `setkey'.  Why aren't these functions in the
380           libc anymore?''
381
382 [A14] {UD} Remember the US restrictions of exporting cryptographic
383 programs and source code.  Until this law gets abolished we cannot
384 ship the cryptographic function together with the libc.
385
386 But of course we provide the code and there is an very easy way to use
387 this code.  First get the extra package.  People in the US way get it
388 from the same place they got the GNU libc from.  People outside the US
389 should get the code from ftp.uni-c.dk [129.142.6.74], or another
390 archive site outside the USA.  The README explains how to install the
391 sources.
392
393 If you already have the crypt code on your system the reason for the
394 failure is probably that you failed to link with -lcrypt.  The crypto
395 functions are in a separate library to make it possible to export GNU
396 libc binaries from the US.
397
398
399 ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
400 [Q15]   ``What are these `add-ons'?''
401
402 [A15] {UD} To avoid complications with external or external source
403 code some optional parts of the libc are distributed as separate
404 packages (e.g., the crypt package, see Q14).
405
406 To ease the use as part of GNU libc the installer just has to unpack
407 the package and tell the configuration script about these additional
408 subdirectories using the --enable-add-ons option.  When you add the
409 crypt add-on you just have to use
410
411         configure --enable-add-ons=crypt,XXX ...
412
413 where XXX are possible other add-ons and ... means the rest of the
414 normal option list.
415
416 You can use add-ons also to overwrite some files in glibc.  The add-on
417 system dependent subdirs are search first.  It is also possible to add
418 banner files (use a file named `Banner') or create shared libraries.
419
420 Using add-ons has the big advantage that the makefiles of the GNU libc
421 can be used.  Only some few stub rules must be written to get
422 everything running.  Even handling of architecture dependent
423 compilation is provided.  The GNU libc's sysdeps/ directory shows how
424 to use this feature.
425
426
427 ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
428 \f
429 Answers were given by:
430 {UD} Ulrich Drepper, <drepper@cygnus.com>
431 {DMT} David Mosberger-Tang, <davidm@AZStarNet.com>
432
433 Amended by:
434 {RM} Roland McGrath, <roland@gnu.ai.mit.edu>
435 \f
436 Local Variables:
437  mode:text
438 End: