[444] | 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 | |
---|