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