diff options
Diffstat (limited to 'newlib/libc/libc.texinfo')
| -rw-r--r-- | newlib/libc/libc.texinfo | 445 |
1 files changed, 0 insertions, 445 deletions
diff --git a/newlib/libc/libc.texinfo b/newlib/libc/libc.texinfo deleted file mode 100644 index f4f9624bc..000000000 --- a/newlib/libc/libc.texinfo +++ /dev/null @@ -1,445 +0,0 @@ -\input texinfo.tex -@setfilename libc.info -@syncodeindex fn cp - -@ifinfo -@format -START-INFO-DIR-ENTRY -* libc:: The ANSI C library. -END-INFO-DIR-ENTRY -@end format -@end ifinfo - -@ifinfo -This file documents the ANSI C library. - -Copyright (C) 1992, 1993, 1994-2004 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} 1.16.0 -@subtitle December 2007 -@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 extra.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:: -* Syscalls:: -* Arglists:: -@ifset ICONV -* Iconv:: -@end ifset - -* Library 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 Library Index -@unnumbered 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 - - |