OpenCores
URL https://opencores.org/ocsvn/openrisc_me/openrisc_me/trunk

Subversion Repositories openrisc_me

[/] [openrisc/] [trunk/] [gnu-src/] [newlib-1.18.0/] [newlib/] [libc/] [libc.texinfo] - Blame information for rev 207

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 207 jeremybenn
\input texinfo.tex
2
@setfilename libc.info
3
@syncodeindex fn cp
4
 
5
@ifinfo
6
@format
7
START-INFO-DIR-ENTRY
8
* libc::                        The ANSI C library.
9
END-INFO-DIR-ENTRY
10
@end format
11
@end ifinfo
12
 
13
@ifinfo
14
This file documents the ANSI C library.
15
 
16
Copyright (C) 1992, 1993, 1994-2009 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} 1.18.0
73
@subtitle December 2008
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 stdio64.texi
143
@include iconvset.texi
144
 
145
@menu
146
* Introduction::
147
* Stdlib::
148
* Ctype::
149
* Stdio::
150
@ifset STDIO64
151
* Stdio64::
152
@end ifset
153
 
154
* Strings::
155
* Wchar strings::
156
@ifset SIGNALS
157
* Signals::
158
@end ifset
159
 
160
* Timefns::
161
* Locale::
162
* Reentrancy::
163
 
164
* Misc::
165
* Posix::
166
* Syscalls::
167
* Arglists::
168
@ifset ICONV
169
* Iconv::
170
@end ifset
171
 
172
* Library Index::
173
@end menu
174
@end ifnottex
175
 
176
@node Introduction
177
@chapter Introduction
178
 
179
This reference manual describes the functions provided by the Red Hat
180
``newlib'' version of the standard ANSI C library.  This document is not
181
intended as an overview or a tutorial for the C library.  Each library
182
function is listed with a synopsis of its use, a brief description,
183
return values (including error handling), and portability issues.
184
 
185
Some of the library functions depend on support from the underlying
186
operating system and may not be available on every platform.  For
187
embedded systems in particular, many of these underlying operating
188
system services may not be available or may not be fully functional.
189
The specific operating system subroutines required for a particular
190
library function are listed in the ``Portability'' section of the
191
function description.  @xref{Syscalls}, for a description of the
192
relevant operating system calls.
193
 
194
@include targetdep.tex
195
 
196
@node Arglists
197
@chapter Variable Argument Lists
198
 
199
The @code{printf} family of functions is defined to accept a variable
200
number of arguments, rather than a fixed argument list.  You can define
201
your own functions with a variable argument list, by using macro
202
definitions from either @file{stdarg.h} (for compatibility with ANSI C)
203
or from @file{varargs.h} (for compatibility with a popular convention
204
prior to ANSI C).
205
 
206
@menu
207
* Stdarg::
208
* Varargs::
209
@end menu
210
 
211
@node Stdarg
212
@section ANSI-standard macros, @file{stdarg.h}
213
 
214
In ANSI C, a function has a variable number of arguments when its
215
parameter list ends in an ellipsis (@code{...}).  The parameter list
216
must also include at least one explicitly named argument; that argument
217
is used to initialize the variable list data structure.
218
 
219
ANSI C defines three macros (@code{va_start}, @code{va_arg}, and
220
@code{va_end}) to operate on variable argument lists.  @file{stdarg.h}
221
also defines a special type to represent variable argument lists: this
222
type is called @code{va_list}.
223
 
224
@menu
225
* va_start::
226
* va_arg::
227
* va_end::
228
@end menu
229
 
230
@page
231
@node va_start
232
@subsection Initialize variable argument list
233
@findex va_start
234
@strong{Synopsis}
235
@example
236
#include <stdarg.h>
237
void va_start(va_list @var{ap}, @var{rightmost});
238
@end example
239
 
240
@strong{Description}@*
241
Use @code{va_start} to initialize the variable argument list @var{ap},
242
so that @code{va_arg} can extract values from it.  @var{rightmost} is
243
the name of the last explicit argument in the parameter list (the
244
argument immediately preceding the ellipsis @samp{...} that flags
245
variable arguments in an ANSI C function header).  You can only use
246
@code{va_start} in a function declared using this ellipsis notation
247
(not, for example, in one of its subfunctions).
248
 
249
@strong{Returns}@*
250
@code{va_start} does not return a result.
251
 
252
@strong{Portability}@*
253
ANSI C requires @code{va_start}.
254
 
255
@page
256
@node va_arg
257
@subsection Extract a value from argument list
258
@findex va_arg
259
@strong{Synopsis}
260
@example
261
#include <stdarg.h>
262
@var{type} va_arg(va_list @var{ap}, @var{type});
263
@end example
264
 
265
@strong{Description}@*
266
@code{va_arg} returns the next unprocessed value from a variable
267
argument list @var{ap} (which you must previously create with
268
@var{va_start}).  Specify the type for the value as the second parameter
269
to the macro, @var{type}.
270
 
271
You may pass a @code{va_list} object @var{ap} to a subfunction, and use
272
@code{va_arg} from the subfunction rather than from the function
273
actually declared with an ellipsis in the header; however, in that case
274
you may @emph{only} use @code{va_arg} from the subfunction.  ANSI C does
275
not permit extracting successive values from a single variable-argument
276
list from different levels of the calling stack.
277
 
278
There is no mechanism for testing whether there is actually a next
279
argument available; you might instead pass an argument count (or some
280
other data that implies an argument count) as one of the fixed arguments
281
in your function call.
282
 
283
@strong{Returns}@*
284
@code{va_arg} returns the next argument, an object of type @var{type}.
285
 
286
@strong{Portability}@*
287
ANSI C requires @code{va_arg}.
288
 
289
@page
290
@node va_end
291
@subsection Abandon a variable argument list
292
@findex va_end
293
@strong{Synopsis}
294
@example
295
#include <stdarg.h>
296
void va_end(va_list @var{ap});
297
@end example
298
 
299
@strong{Description}@*
300
Use @code{va_end} to declare that your program will not use the variable
301
argument list @var{ap} any further.
302
 
303
@strong{Returns}@*
304
@code{va_end} does not return a result.
305
 
306
@strong{Portability}@*
307
ANSI C requires @code{va_end}.
308
 
309
@node Varargs
310
@section Traditional macros, @file{varargs.h}
311
 
312
If your C compiler predates ANSI C, you may still be able to use
313
variable argument lists using the macros from the @file{varargs.h}
314
header file.  These macros resemble their ANSI counterparts, but have
315
important differences in usage.   In particular, since traditional C has
316
no declaration mechanism for variable argument lists, two additional
317
macros are provided simply for the purpose of defining functions with
318
variable argument lists.
319
 
320
As with @file{stdarg.h}, the type @code{va_list} is used to hold a data
321
structure representing a variable argument list.
322
 
323
@menu
324
* va_alist::
325
* va_start-trad::
326
* va_arg-trad::
327
* va_end-trad::
328
@end menu
329
 
330
@page
331
@node va_alist
332
@subsection Declare variable arguments
333
@findex va_alist
334
@findex va_dcl
335
@strong{Synopsis}
336
@example
337
#include <varargs.h>
338
@var{function}(va_alist)
339
va_dcl
340
@end example
341
 
342
@strong{Description}@*
343
To use the @file{varargs.h} version of variable argument lists, you must
344
declare your function with a call to the macro @code{va_alist} as its
345
argument list, and use @code{va_dcl} as the declaration.  @emph{Do not
346
use a semicolon after @code{va_dcl}.}
347
 
348
@strong{Returns}@*
349
These macros cannot be used in a context where a return is syntactically
350
possible.
351
 
352
@strong{Portability}@*
353
@var{va_alist} and @var{va_dcl} were the most widespread method of
354
declaring variable argument lists prior to ANSI C.
355
 
356
@page
357
@node va_start-trad
358
@subsection Initialize variable argument list
359
@findex va_start
360
@strong{Synopsis}
361
@example
362
#include <varargs.h>
363
va_list @var{ap};
364
va_start(@var{ap});
365
@end example
366
 
367
@strong{Description}@*
368
With the @file{varargs.h} macros, use @code{va_start} to initialize a
369
data structure @var{ap} to permit manipulating a variable argument list.
370
@var{ap} must have the type @var{va_alist}.
371
 
372
@strong{Returns}@*
373
@code{va_start} does not return a result.
374
 
375
@strong{Portability}@*
376
@code{va_start} is also defined as a macro in ANSI C, but the
377
definitions are incompatible; the ANSI version has another parameter
378
besides @var{ap}.
379
 
380
@page
381
@node va_arg-trad
382
@subsection Extract a value from argument list
383
@findex va_arg
384
@strong{Synopsis}
385
@example
386
#include <varargs.h>
387
@var{type} va_arg(va_list @var{ap}, @var{type});
388
@end example
389
 
390
@strong{Description}@*
391
@code{va_arg} returns the next unprocessed value from a variable
392
argument list @var{ap} (which you must previously create with
393
@var{va_start}).  Specify the type for the value as the second parameter
394
to the macro, @var{type}.
395
 
396
@strong{Returns}@*
397
@code{va_arg} returns the next argument, an object of type @var{type}.
398
 
399
@strong{Portability}@*
400
The @code{va_arg} defined in @file{varargs.h} has the same syntax and
401
usage as the ANSI C version from @file{stdarg.h}.
402
 
403
@page
404
@node va_end-trad
405
@subsection Abandon a variable argument list
406
@findex va_end
407
@strong{Synopsis}
408
@example
409
#include <varargs.h>
410
va_end(va_list @var{ap});
411
@end example
412
 
413
@strong{Description}@*
414
Use @code{va_end} to declare that your program will not use the variable
415
argument list @var{ap} any further.
416
 
417
@strong{Returns}@*
418
@code{va_end} does not return a result.
419
 
420
@strong{Portability}@*
421
The @code{va_end} defined in @file{varargs.h} has the same syntax and
422
usage as the ANSI C version from @file{stdarg.h}.
423
 
424
@node Library Index
425
@unnumbered Index
426
@printindex cp
427
 
428
@tex
429
% I think something like @colophon should be in texinfo.  In the
430
% meantime:
431
\long\def\colophon{\hbox to0pt{}\vfill
432
\centerline{The body of this manual is set in}
433
\centerline{\fontname\tenrm,}
434
\centerline{with headings in {\bf\fontname\tenbf}}
435
\centerline{and examples in {\tt\fontname\tentt}.}
436
\centerline{{\it\fontname\tenit\/} and}
437
\centerline{{\sl\fontname\tensl\/}}
438
\centerline{are used for emphasis.}\vfill}
439
\page\colophon
440
% Blame: pesch@cygnus.com, 28mar91.
441
@end tex
442
 
443
@contents
444
@bye
445
 
446
 

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.