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