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