]>
Commit | Line | Data |
---|---|---|
8a0efa53 CF |
1 | \input texinfo.tex |
2 | @setfilename libc.info | |
3 | @tex | |
4 | % NOTE LOCAL KLUGE TO AVOID TOO MUCH WHITESPACE FROM "makedoc" | |
5 | \global\long\def\example{% | |
6 | \begingroup | |
7 | \let\aboveenvbreak=\par | |
8 | \let\afterenvbreak=\par | |
9 | \parskip=0pt | |
10 | \lisp} | |
11 | \global\long\def\Eexample{% | |
12 | \Elisp | |
13 | \endgroup | |
14 | \vskip -\parskip% to cancel out effect of following \par | |
15 | } | |
16 | % END LOCAL WHITESPACE KLUGE | |
17 | @end tex | |
18 | @syncodeindex fn cp | |
19 | ||
20 | @ifinfo | |
21 | @format | |
22 | START-INFO-DIR-ENTRY | |
23 | * libc:: The ANSI C library. | |
24 | END-INFO-DIR-ENTRY | |
25 | @end format | |
26 | @end ifinfo | |
27 | ||
28 | @ifinfo | |
29 | This file documents the ANSI C library. | |
30 | ||
5125f919 | 31 | Copyright (C) 1992, 1993, 1994-2004 Red Hat, Inc. |
8a0efa53 CF |
32 | |
33 | @file{libc} includes software developed by the | |
34 | University of California, Berkeley and its contributors. | |
35 | ||
36 | libc includes software developed by Martin Jackson, Graham Haley | |
37 | and Steve Chamberlain of Tadpole Technology and released to Cygnus. | |
38 | ||
76a7df52 | 39 | libc uses floating-point conversion software developed at AT&T, which |
8a0efa53 CF |
40 | includes this copyright information: |
41 | ||
42 | The author of this software is David M. Gay. | |
43 | ||
44 | Copyright (c) 1991 by AT&T. | |
45 | ||
46 | Permission to use, copy, modify, and distribute this software for any | |
47 | purpose without fee is hereby granted, provided that this entire notice | |
48 | is included in all copies of any software which is or includes a copy | |
49 | or modification of this software and in all copies of the supporting | |
50 | documentation for such software. | |
51 | ||
52 | THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED | |
53 | WARRANTY. IN PARTICULAR, NEITHER THE AUTHOR NOR AT&T MAKES ANY | |
54 | REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY | |
55 | OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE. | |
56 | ||
57 | Permission is granted to make and distribute verbatim copies of | |
58 | this manual provided the copyright notice and this permission notice | |
59 | are preserved on all copies. | |
60 | ||
61 | @ignore | |
62 | Permission is granted to process this file through Tex and print the | |
63 | results, provided the printed document carries copying permission | |
64 | notice identical to this one except for the removal of this paragraph | |
65 | (this paragraph not being relevant to the printed manual). | |
66 | ||
67 | @end ignore | |
68 | Permission is granted to copy and distribute modified versions of this | |
69 | manual under the conditions for verbatim copying, subject to the terms | |
70 | of the GNU General Public License, which includes the provision that the | |
71 | entire resulting derived work is distributed under the terms of a | |
72 | permission notice identical to this one. | |
73 | ||
74 | Permission is granted to copy and distribute translations of this manual | |
75 | into another language, under the above conditions for modified versions. | |
76 | @end ifinfo | |
77 | @iftex | |
78 | @c @smallbook | |
79 | @c @cropmarks | |
80 | @finalout | |
81 | @setchapternewpage odd | |
5e7d0a55 | 82 | @settitle Red Hat newlib C Library, Full |
8a0efa53 | 83 | @titlepage |
5e7d0a55 | 84 | @title The Red Hat newlib C Library |
8a0efa53 CF |
85 | @subtitle Full Configuration |
86 | @sp 1 | |
60b0838f | 87 | @subtitle @code{libc} 1.11.0 |
5e7d0a55 | 88 | @subtitle July 2002 |
8a0efa53 CF |
89 | @author {Steve Chamberlain} |
90 | @author {Roland Pesch} | |
5e7d0a55 TF |
91 | @author {Red Hat Support} |
92 | @author {Jeff Johnston} | |
8a0efa53 CF |
93 | @page |
94 | ||
95 | @tex | |
96 | {\parskip=0pt | |
5125f919 JJ |
97 | sac@@cygnus.com, pesch@@cygnus.com, jjohnstn@@redhat.com\hfill {\it The Red Hat newlib C Library}\par |
98 | Copyright \copyright{} 1992, 1993, 1994-2004 Red Hat Inc. | |
8a0efa53 CF |
99 | } |
100 | \global\parindent=0pt % Steve likes it this way | |
101 | @end tex | |
102 | ||
103 | @file{libc} includes software developed by the | |
104 | University of California, Berkeley and its contributors. | |
105 | ||
106 | @file{libc} includes software developed by Martin Jackson, Graham Haley | |
107 | and Steve Chamberlain of Tadpole Technology and released to Cygnus. | |
108 | ||
76a7df52 | 109 | @file{libc} uses floating-point conversion software developed at AT&T, |
8a0efa53 CF |
110 | which includes this copyright information: |
111 | ||
112 | @cartouche | |
113 | @quotation | |
114 | The author of this software is David M. Gay. | |
115 | ||
116 | Copyright (c) 1991 by AT&T. | |
117 | ||
118 | Permission to use, copy, modify, and distribute this software for any | |
119 | purpose without fee is hereby granted, provided that this entire notice | |
120 | is included in all copies of any software which is or includes a copy | |
121 | or modification of this software and in all copies of the supporting | |
122 | documentation for such software. | |
123 | ||
124 | THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED | |
125 | WARRANTY. IN PARTICULAR, NEITHER THE AUTHOR NOR AT&T MAKES ANY | |
126 | REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY | |
127 | OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE. | |
128 | @end quotation | |
129 | @end cartouche | |
130 | ||
131 | Permission is granted to make and distribute verbatim copies of | |
132 | this manual provided the copyright notice and this permission notice | |
133 | are preserved on all copies. | |
134 | ||
135 | Permission is granted to copy and distribute modified versions of this | |
136 | manual under the conditions for verbatim copying, subject to the terms | |
137 | of the GNU General Public License, which includes the provision that the | |
138 | entire resulting derived work is distributed under the terms of a | |
139 | permission notice identical to this one. | |
140 | ||
141 | Permission is granted to copy and distribute translations of this manual | |
142 | into another language, under the above conditions for modified versions. | |
143 | @end titlepage | |
144 | @end iftex | |
145 | ||
146 | @ifinfo | |
147 | @node Top | |
5e7d0a55 | 148 | @top The Red Hat newlib C Library |
8a0efa53 CF |
149 | |
150 | @c The menu contents depend on the configuration, so we include them | |
151 | @c as a separate file | |
152 | ||
153 | @c switch to set SIGNALS on or off, according to whether config picks up | |
154 | @c signal subdirectory: | |
155 | @include sigset.texi | |
dee51391 JJ |
156 | @include extra.texi |
157 | @include stdio64.texi | |
786ab12c | 158 | @include iconvset.texi |
8a0efa53 CF |
159 | |
160 | @menu | |
161 | * Stdlib:: | |
162 | * Ctype:: | |
163 | * Stdio:: | |
dee51391 JJ |
164 | @ifset STDIO64 |
165 | * Stdio64:: | |
166 | @end ifset | |
167 | ||
8a0efa53 | 168 | * Strings:: |
3c689185 | 169 | * Wchar strings:: |
8a0efa53 CF |
170 | @ifset SIGNALS |
171 | * Signals:: | |
172 | @end ifset | |
173 | ||
174 | * Timefns:: | |
175 | * Locale:: | |
176 | * Syscalls:: | |
778876f6 | 177 | |
8a0efa53 CF |
178 | * Misc:: |
179 | * Arglists:: | |
180 | * Reentrancy:: | |
786ab12c JJ |
181 | @ifset ICONV |
182 | * Iconv:: | |
183 | @end ifset | |
184 | ||
8a0efa53 CF |
185 | * Library Index:: |
186 | @end menu | |
187 | @end ifinfo | |
188 | ||
189 | @include targetdep.tex | |
190 | ||
191 | @node Arglists | |
192 | @chapter Variable Argument Lists | |
193 | ||
194 | The @code{printf} family of functions is defined to accept a variable | |
195 | number of arguments, rather than a fixed argument list. You can define | |
196 | your own functions with a variable argument list, by using macro | |
197 | definitions from either @file{stdarg.h} (for compatibility with ANSI C) | |
198 | or from @file{varargs.h} (for compatibility with a popular convention | |
199 | prior to ANSI C). | |
200 | ||
201 | @menu | |
202 | * Stdarg:: | |
203 | * Varargs:: | |
204 | @end menu | |
205 | ||
206 | @node Stdarg | |
207 | @section ANSI-standard macros, @file{stdarg.h} | |
208 | ||
209 | In ANSI C, a function has a variable number of arguments when its | |
210 | parameter list ends in an ellipsis (@code{...}). The parameter list | |
211 | must also include at least one explicitly named argument; that argument | |
212 | is used to initialize the variable list data structure. | |
213 | ||
214 | ANSI C defines three macros (@code{va_start}, @code{va_arg}, and | |
215 | @code{va_end}) to operate on variable argument lists. @file{stdarg.h} | |
216 | also defines a special type to represent variable argument lists: this | |
217 | type is called @code{va_list}. | |
218 | ||
219 | @menu | |
220 | * va_start:: | |
221 | * va_arg:: | |
222 | * va_end:: | |
223 | @end menu | |
224 | ||
225 | @page | |
226 | @node va_start | |
227 | @subsection Initialize variable argument list | |
228 | @findex va_start | |
229 | @strong{Synopsis} | |
230 | @example | |
231 | #include <stdarg.h> | |
232 | void va_start(va_list @var{ap}, @var{rightmost}); | |
233 | @end example | |
234 | ||
235 | @strong{Description}@* | |
236 | Use @code{va_start} to initialize the variable argument list @var{ap}, | |
237 | so that @code{va_arg} can extract values from it. @var{rightmost} is | |
238 | the name of the last explicit argument in the parameter list (the | |
239 | argument immediately preceding the ellipsis @samp{...} that flags | |
240 | variable arguments in an ANSI C function header). You can only use | |
241 | @code{va_start} in a function declared using this ellipsis notation | |
242 | (not, for example, in one of its subfunctions). | |
243 | ||
244 | @strong{Returns}@* | |
245 | @code{va_start} does not return a result. | |
246 | ||
247 | @strong{Portability}@* | |
248 | ANSI C requires @code{va_start}. | |
249 | ||
250 | @page | |
251 | @node va_arg | |
252 | @subsection Extract a value from argument list | |
253 | @findex va_arg | |
254 | @strong{Synopsis} | |
255 | @example | |
256 | #include <stdarg.h> | |
257 | @var{type} va_arg(va_list @var{ap}, @var{type}); | |
258 | @end example | |
259 | ||
260 | @strong{Description}@* | |
261 | @code{va_arg} returns the next unprocessed value from a variable | |
262 | argument list @var{ap} (which you must previously create with | |
263 | @var{va_start}). Specify the type for the value as the second parameter | |
264 | to the macro, @var{type}. | |
265 | ||
266 | You may pass a @code{va_list} object @var{ap} to a subfunction, and use | |
267 | @code{va_arg} from the subfunction rather than from the function | |
268 | actually declared with an ellipsis in the header; however, in that case | |
269 | you may @emph{only} use @code{va_arg} from the subfunction. ANSI C does | |
270 | not permit extracting successive values from a single variable-argument | |
271 | list from different levels of the calling stack. | |
272 | ||
273 | There is no mechanism for testing whether there is actually a next | |
274 | argument available; you might instead pass an argument count (or some | |
275 | other data that implies an argument count) as one of the fixed arguments | |
276 | in your function call. | |
277 | ||
278 | @strong{Returns}@* | |
279 | @code{va_arg} returns the next argument, an object of type @var{type}. | |
280 | ||
281 | @strong{Portability}@* | |
282 | ANSI C requires @code{va_arg}. | |
283 | ||
284 | @page | |
285 | @node va_end | |
286 | @subsection Abandon a variable argument list | |
287 | @findex va_end | |
288 | @strong{Synopsis} | |
289 | @example | |
290 | #include <stdarg.h> | |
291 | void va_end(va_list @var{ap}); | |
292 | @end example | |
293 | ||
294 | @strong{Description}@* | |
295 | Use @code{va_end} to declare that your program will not use the variable | |
296 | argument list @var{ap} any further. | |
297 | ||
298 | @strong{Returns}@* | |
299 | @code{va_end} does not return a result. | |
300 | ||
301 | @strong{Portability}@* | |
302 | ANSI C requires @code{va_end}. | |
303 | ||
304 | @node Varargs | |
305 | @section Traditional macros, @file{varargs.h} | |
306 | ||
307 | If your C compiler predates ANSI C, you may still be able to use | |
308 | variable argument lists using the macros from the @file{varargs.h} | |
309 | header file. These macros resemble their ANSI counterparts, but have | |
310 | important differences in usage. In particular, since traditional C has | |
311 | no declaration mechanism for variable argument lists, two additional | |
312 | macros are provided simply for the purpose of defining functions with | |
313 | variable argument lists. | |
314 | ||
315 | As with @file{stdarg.h}, the type @code{va_list} is used to hold a data | |
316 | structure representing a variable argument list. | |
317 | ||
318 | @menu | |
319 | * va_alist:: | |
320 | * va_start-trad:: | |
321 | * va_arg-trad:: | |
322 | * va_end-trad:: | |
323 | @end menu | |
324 | ||
325 | @page | |
326 | @node va_alist | |
327 | @subsection Declare variable arguments | |
328 | @findex va_alist | |
329 | @findex va_dcl | |
330 | @strong{Synopsis} | |
331 | @example | |
332 | #include <varargs.h> | |
333 | @var{function}(va_alist) | |
334 | va_dcl | |
335 | @end example | |
336 | ||
337 | @strong{Description}@* | |
338 | To use the @file{varargs.h} version of variable argument lists, you must | |
339 | declare your function with a call to the macro @code{va_alist} as its | |
340 | argument list, and use @code{va_dcl} as the declaration. @emph{Do not | |
341 | use a semicolon after @code{va_dcl}.} | |
342 | ||
343 | @strong{Returns}@* | |
344 | These macros cannot be used in a context where a return is syntactically | |
345 | possible. | |
346 | ||
347 | @strong{Portability}@* | |
348 | @var{va_alist} and @var{va_dcl} were the most widespread method of | |
349 | declaring variable argument lists prior to ANSI C. | |
350 | ||
351 | @page | |
352 | @node va_start-trad | |
353 | @subsection Initialize variable argument list | |
354 | @findex va_start | |
355 | @strong{Synopsis} | |
356 | @example | |
357 | #include <varargs.h> | |
358 | va_list @var{ap}; | |
359 | va_start(@var{ap}); | |
360 | @end example | |
361 | ||
362 | @strong{Description}@* | |
363 | With the @file{varargs.h} macros, use @code{va_start} to initialize a | |
364 | data structure @var{ap} to permit manipulating a variable argument list. | |
365 | @var{ap} must have the type @var{va_alist}. | |
366 | ||
367 | @strong{Returns}@* | |
368 | @code{va_start} does not return a result. | |
369 | ||
370 | @strong{Portability}@* | |
371 | @code{va_start} is also defined as a macro in ANSI C, but the | |
372 | definitions are incompatible; the ANSI version has another parameter | |
373 | besides @var{ap}. | |
374 | ||
375 | @page | |
376 | @node va_arg-trad | |
377 | @subsection Extract a value from argument list | |
378 | @findex va_arg | |
379 | @strong{Synopsis} | |
380 | @example | |
381 | #include <varargs.h> | |
382 | @var{type} va_arg(va_list @var{ap}, @var{type}); | |
383 | @end example | |
384 | ||
385 | @strong{Description}@* | |
386 | @code{va_arg} returns the next unprocessed value from a variable | |
387 | argument list @var{ap} (which you must previously create with | |
388 | @var{va_start}). Specify the type for the value as the second parameter | |
389 | to the macro, @var{type}. | |
390 | ||
391 | @strong{Returns}@* | |
392 | @code{va_arg} returns the next argument, an object of type @var{type}. | |
393 | ||
394 | @strong{Portability}@* | |
395 | The @code{va_arg} defined in @file{varargs.h} has the same syntax and | |
396 | usage as the ANSI C version from @file{stdarg.h}. | |
397 | ||
398 | @page | |
399 | @node va_end-trad | |
400 | @subsection Abandon a variable argument list | |
401 | @findex va_end | |
402 | @strong{Synopsis} | |
403 | @example | |
404 | #include <varargs.h> | |
405 | va_end(va_list @var{ap}); | |
406 | @end example | |
407 | ||
408 | @strong{Description}@* | |
409 | Use @code{va_end} to declare that your program will not use the variable | |
410 | argument list @var{ap} any further. | |
411 | ||
412 | @strong{Returns}@* | |
413 | @code{va_end} does not return a result. | |
414 | ||
415 | @strong{Portability}@* | |
416 | The @code{va_end} defined in @file{varargs.h} has the same syntax and | |
417 | usage as the ANSI C version from @file{stdarg.h}. | |
418 | ||
419 | @node Library Index | |
420 | @unnumbered Index | |
421 | @printindex cp | |
422 | ||
423 | @tex | |
424 | % I think something like @colophon should be in texinfo. In the | |
425 | % meantime: | |
426 | \long\def\colophon{\hbox to0pt{}\vfill | |
427 | \centerline{The body of this manual is set in} | |
428 | \centerline{\fontname\tenrm,} | |
429 | \centerline{with headings in {\bf\fontname\tenbf}} | |
430 | \centerline{and examples in {\tt\fontname\tentt}.} | |
431 | \centerline{{\it\fontname\tenit\/} and} | |
432 | \centerline{{\sl\fontname\tensl\/}} | |
433 | \centerline{are used for emphasis.}\vfill} | |
434 | \page\colophon | |
435 | % Blame: pesch@cygnus.com, 28mar91. | |
436 | @end tex | |
437 | ||
438 | @contents | |
439 | @bye | |
440 | ||
441 |