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