newlib-cygwin/newlib/libc/libc.texi

437 lines
13 KiB
Plaintext
Raw Normal View History

2000-02-18 03:39:52 +08:00
\input texinfo.tex
@setfilename libc.info
@ifinfo
@format
@dircategory Newlib
@direntry
* libc: (libc). The ANSI C library.
@end direntry
2000-02-18 03:39:52 +08:00
@end format
@end ifinfo
@ifinfo
This file documents the ANSI C library.
Copyright (C) 1992, 1993, 1994-2014 Red Hat, Inc.
2000-02-18 03:39:52 +08:00
@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.
2003-10-20 Bob Wilson <bob.wilson@acm.org> * libc/locale/locale.c: Use double quotes in code. * libc/locale/locale.tex: Likewise. * libc/libc.texinfo: Hyphenate "floating-point". * libc/machine/necv70/necv70.tex: Likewise. * libc/stdio/sprintf.c: Likewise. * libc/stdio/sscanf.c: Likewise. * libc/stdlib/atof.c: Likewise. * libc/stdlib/ldtoa.c: Fix comment typo. * libc/stdlib/div.c: Use @ifnottex instead of @ifinfo. * libc/stdlib/ldiv.c: Likewise. * libm/common/s_expm1.c: Likewise. * libm/common/s_ilogb.c: Hyphenate "floating-point". Use "nonzero". * libm/common/s_infinity: Hyphenate "double- and single-precision". * libm/common/s_nan.c: Likewise. Also correct the FUNCTION summary. * libm/common/s_nextafter.c: Fix typo. Hyphenate "double-precision" and "floating-point". * libm/common/s_scalbn.c: Correct the FUNCTION summary. * libm/math/e_pow.c: Fix comment typo. * libm/math/math.tex: Hyphenate "single-precision" and "floating-point". * libm/math/s_asinh.c: Use @ifnottex instead of @ifinfo. * libm/math/s_atan.c: Likewise. * libm/math/s_frexp.c: Likewise. Also use "nonzero". * libm/math/s_isnan.c: Hyphenate "single-precision" and "floating-point". Use "nonzero". * libm/math/s_ldexp.c: Use @ifnottex instead of @ifinfo. * libm/math/w_acos.c: Likewise. * libm/math/w_acosh.c: Likewise. * libm/math/w_asin.c: Likewise. * libm/math/w_atan2.c: Likewise. * libm/math/w_atanh.c: Likewise. * libm/math/w_cosh.c: Likewise. * libm/math/w_exp.c: Likewise. * libm/math/w_exp2.c: Likewise. Add missing @end and missing @tex version of 2^x in the description. * libm/math/w_fmod.c: Use @ifnottex instead of @ifinfo. * libm/math/w_gamma.c: Likewise. * libm/math/w_hypot.c: Likewise. * libm/math/w_j0.c: Likewise. * libm/math/w_sinh.c: Likewise. * libm/math/w_pow.c: Replace "exp1.0nt" with "exponent". * libm/mathfp/mathfp.tex: Hyphenate "single-precision" and "floating-point". * libm/mathfp/e_acosh.c: Use @ifnottex instead of @ifinfo. * libm/mathfp/e_atanh.c: Likewise. * libm/mathfp/e_hypot.c: Likewise. * libm/mathfp/er_lgamma.c: Likewise. * libm/mathfp/s_acos.c: Likewise. * libm/mathfp/s_asine.c: Likewise. * libm/mathfp/s_asinh.c: Likewise. * libm/mathfp/s_atan.c: Likewise. * libm/mathfp/s_atan2.c: Likewise. * libm/mathfp/s_atangent.c: Likewise. * libm/mathfp/s_cosh.c: Likewise. * libm/mathfp/s_exp.c: Likewise. * libm/mathfp/s_fmod.c: Likewise. * libm/mathfp/s_frexp.c: Likewise. Also use "nonzero". * libm/mathfp/s_isnan.c: Hyphenate "single-precision" and "floating-point". Use "nonzero". * libm/math/s_pow.c: Replace "exp1.0nt" with "exponent". * libm/mathfp/s_ldexp.c: Use @ifnottex instead of @ifinfo. * libm/mathfp/s_sineh.c: Likewise. * libm/mathfp/w_jn.c: Likewise.
2003-10-21 02:46:38 +08:00
libc uses floating-point conversion software developed at AT&T, which
2000-02-18 03:39:52 +08:00
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
2000-02-18 03:39:52 +08:00
@titlepage
@title The Red Hat newlib C Library
2000-02-18 03:39:52 +08:00
@subtitle Full Configuration
@sp 1
@subtitle @code{libc} 4.4.0
@subtitle December 2023
@author Steve Chamberlain
@author Roland Pesch
@author Red Hat Support
@author Jeff Johnston
2000-02-18 03:39:52 +08:00
@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.
2000-02-18 03:39:52 +08:00
}
\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.
2003-10-20 Bob Wilson <bob.wilson@acm.org> * libc/locale/locale.c: Use double quotes in code. * libc/locale/locale.tex: Likewise. * libc/libc.texinfo: Hyphenate "floating-point". * libc/machine/necv70/necv70.tex: Likewise. * libc/stdio/sprintf.c: Likewise. * libc/stdio/sscanf.c: Likewise. * libc/stdlib/atof.c: Likewise. * libc/stdlib/ldtoa.c: Fix comment typo. * libc/stdlib/div.c: Use @ifnottex instead of @ifinfo. * libc/stdlib/ldiv.c: Likewise. * libm/common/s_expm1.c: Likewise. * libm/common/s_ilogb.c: Hyphenate "floating-point". Use "nonzero". * libm/common/s_infinity: Hyphenate "double- and single-precision". * libm/common/s_nan.c: Likewise. Also correct the FUNCTION summary. * libm/common/s_nextafter.c: Fix typo. Hyphenate "double-precision" and "floating-point". * libm/common/s_scalbn.c: Correct the FUNCTION summary. * libm/math/e_pow.c: Fix comment typo. * libm/math/math.tex: Hyphenate "single-precision" and "floating-point". * libm/math/s_asinh.c: Use @ifnottex instead of @ifinfo. * libm/math/s_atan.c: Likewise. * libm/math/s_frexp.c: Likewise. Also use "nonzero". * libm/math/s_isnan.c: Hyphenate "single-precision" and "floating-point". Use "nonzero". * libm/math/s_ldexp.c: Use @ifnottex instead of @ifinfo. * libm/math/w_acos.c: Likewise. * libm/math/w_acosh.c: Likewise. * libm/math/w_asin.c: Likewise. * libm/math/w_atan2.c: Likewise. * libm/math/w_atanh.c: Likewise. * libm/math/w_cosh.c: Likewise. * libm/math/w_exp.c: Likewise. * libm/math/w_exp2.c: Likewise. Add missing @end and missing @tex version of 2^x in the description. * libm/math/w_fmod.c: Use @ifnottex instead of @ifinfo. * libm/math/w_gamma.c: Likewise. * libm/math/w_hypot.c: Likewise. * libm/math/w_j0.c: Likewise. * libm/math/w_sinh.c: Likewise. * libm/math/w_pow.c: Replace "exp1.0nt" with "exponent". * libm/mathfp/mathfp.tex: Hyphenate "single-precision" and "floating-point". * libm/mathfp/e_acosh.c: Use @ifnottex instead of @ifinfo. * libm/mathfp/e_atanh.c: Likewise. * libm/mathfp/e_hypot.c: Likewise. * libm/mathfp/er_lgamma.c: Likewise. * libm/mathfp/s_acos.c: Likewise. * libm/mathfp/s_asine.c: Likewise. * libm/mathfp/s_asinh.c: Likewise. * libm/mathfp/s_atan.c: Likewise. * libm/mathfp/s_atan2.c: Likewise. * libm/mathfp/s_atangent.c: Likewise. * libm/mathfp/s_cosh.c: Likewise. * libm/mathfp/s_exp.c: Likewise. * libm/mathfp/s_fmod.c: Likewise. * libm/mathfp/s_frexp.c: Likewise. Also use "nonzero". * libm/mathfp/s_isnan.c: Hyphenate "single-precision" and "floating-point". Use "nonzero". * libm/math/s_pow.c: Replace "exp1.0nt" with "exponent". * libm/mathfp/s_ldexp.c: Use @ifnottex instead of @ifinfo. * libm/mathfp/s_sineh.c: Likewise. * libm/mathfp/w_jn.c: Likewise.
2003-10-21 02:46:38 +08:00
@file{libc} uses floating-point conversion software developed at AT&T,
2000-02-18 03:39:52 +08:00
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
2000-02-18 03:39:52 +08:00
@node Top
@top The Red Hat newlib C Library
2000-02-18 03:39:52 +08:00
@menu
* Introduction::
2000-02-18 03:39:52 +08:00
* Stdlib::
* Ctype::
* Stdio::
2002-07-17 Jeff Johnston <jjohnstn@redhat.com> * configure.host(stdio64_dir): New setting that is used to enable building of new stdio64 directory. * libc/Makefile.am[HAVE_STDIO64_DIR]: Add support for large files. (stmp-stdio64,stdio64.texi): New targets to optionally add in stdio64 info to info files. * libc/Makefile.in: Regenerated. * libc/configure: Ditto. * libc/configure.in: Add configuration variables that are set when stdio64 is selected as subdir in configure.host. * libc/libc.texinfo: Add optional menu item for Stdio64, based on whether STDIO64 flag is set or not. * libc/sys.tex: Add optional stdio64 syscalls based on whether STDIO64 flag is set or not. * libc/include/reent.h[__LARGE64_FILES]: Add new stdio64 _r sycall routines. * libc/include/stdio.h[__LARGE64_FILES]: Add new stdio64 prototypes. (FILE): Typedef'd to __FILE instead of struct __sFILE directly. (__SL64): New file flag indicating file is opened via fopen64. * libc/include/sys/_types.h(_off64_t): Added. * libc/include/sys/config.h: For x86-linux, define __LARGE64_FILES. * libc/include/sys/reent.h(struct __sFILE64): New file structure for 64-bit offset large file support. (__FILE): New intermediate type either set to struct __sFILE64 or struct __sFILE, depending on whether __LARGE64_FILES is set or not. * libc/reent/Makefile.am[HAVE_STDIO64_DIR]: Add new files. * libc/reent/Makefile.in: Regenerated. * libc/reent/fstat64r.c: New file. * libc/reent/lseek64r.c: Ditto. * libc/reent/open64r.c: Ditto. * libc/reent/reent.tex: Optionally add stdio64 reentrant syscalls based on whether STDIO64 flag is set. * libc/stdio/stdio.tex: Add blank line. * libc/stdio64/Makefile.am: New file. * libc/stdio64/Makefile.in: Ditto. * libc/stdio64/fgetpos64.c: Ditto. * libc/stdio64/fopen64.: Ditto. * libc/stdio64/freopen64.c: Ditto. * libc/stdio64/fseeko64.c: Ditto. * libc/stdio64/fsetpos64.c: Ditto. * libc/stdio64/ftello64.c: Ditto. * libc/stdio64/local64.h: Ditto. * libc/stdio64/stdio64.c: Ditto. * libc/stdio64/stdio64.tex: Ditto. * libc/stdio64/tmpfile64.c: Ditto. * libc/sys/linux/io64.c: Add weak aliases for lseek64, fstat64, and open64.
2002-07-18 07:25:44 +08:00
* Stdio64::
2000-02-18 03:39:52 +08:00
* Strings::
* Wchar strings::
2000-02-18 03:39:52 +08:00
* Signals::
* Timefns::
* Locale::
* Reentrancy::
2000-02-18 03:39:52 +08:00
* Misc::
* Posix::
* Syscalls::
2000-02-18 03:39:52 +08:00
* Arglists::
* Encoding conversions::
* Overflow Protection::
2004-01-23 Artem B. Bityuckiy <abitytsky@softminecorp.com> * acinclude.m4 (--enable-newlib-iconv): New configuration option. (--enable-newlib-builtin-converters): Ditto. * configure.in: Add code to set _ICONV_ENABLED flag. Set _MB_LEN_MAX to 1 if not mb enabled. * configure: Regenerated. * aclocal.m4: Ditto. * Makefile.in: Ditto. * newlib.hin: Add _ICONV_ENABLED flag. * libc/Makefile.am: Add support for iconv. * libc/configure.in: Ditto. * libc/Makefile.in: Regenerated. * libc/aclocal.m4: Ditto. * libc/configure: Ditto. * libc/libc.texinfo: Add iconv documentation. * libc/iconv/AUTHORS, libc/iconv/COPYING, libc/iconv/Makefile.am, libc/iconv/Makefile.in, libc/iconv/README.ORIGINAL, libc/iconv/README.TODO, libc/iconv/charset.aliases, libc/iconv/iconv.tex, libc/iconv/ccs/Makefile.am, libc/iconv/ccs/Makefile.in, libc/iconv/ccs/README.CCS.SOURCES, libc/iconv/ccs/big5.c, libc/iconv/ccs/cns11643_plane1.c, libc/iconv/ccs/cns11643_plane14.c, libc/iconv/ccs/cns11643_plane2.c, libc/iconv/ccs/cp775.c, libc/iconv/ccs/cp850.c, libc/iconv/ccs/cp852.c, libc/iconv/ccs/cp855.c, libc/iconv/ccs/cp866.c, libc/iconv/ccs/gb_2312_80.c, libc/iconv/ccs/iconv_mktbl, libc/iconv/ccs/iso_8859_1.c, libc/iconv/ccs/iso_8859_15.c, libc/iconv/ccs/iso_8859_2.c, libc/iconv/ccs/iso_8859_4.c, libc/iconv/ccs/iso_8859_5.c, libc/iconv/ccs/jis_x0201.c, libc/iconv/ccs/jis_x0208_1983.c, libc/iconv/ccs/jis_x0212_1990.c, libc/iconv/ccs/koi8_r.c, libc/iconv/ccs/koi8_u.c, libc/iconv/ccs/ksx1001.c, libc/iconv/ccs/shift_jis.c, libc/iconv/ccs/us_ascii.c, libc/iconv/ccs/binary/Makefile.am, libc/iconv/ccs/binary/Makefile.in, libc/iconv/ccs/binary/big5.cct, libc/iconv/ccs/binary/cns11643_plane1.cct, libc/iconv/ccs/binary/cns11643_plane14.cct, libc/iconv/ccs/binary/cns11643_plane2.cct, libc/iconv/ccs/binary/cp775.cct, libc/iconv/ccs/binary/cp850.cct, libc/iconv/ccs/binary/cp852.cct, libc/iconv/ccs/binary/cp855.cct, libc/iconv/ccs/binary/cp866.cct, libc/iconv/ccs/binary/gb_2312_80.cct, libc/iconv/ccs/binary/iso_8859_1.cct, libc/iconv/ccs/binary/iso_8859_15.cct, libc/iconv/ccs/binary/iso_8859_2.cct, libc/iconv/ccs/binary/iso_8859_4.cct, libc/iconv/ccs/binary/iso_8859_5.cct, libc/iconv/ccs/binary/jis_x0201.cct, libc/iconv/ccs/binary/jis_x0208_1983.cct, libc/iconv/ccs/binary/jis_x0212_1990.cct, libc/iconv/ccs/binary/koi8_r.cct, libc/iconv/ccs/binary/koi8_u.cct, libc/iconv/ccs/binary/ksx1001.cct, libc/iconv/ccs/binary/shift_jis.cct, libc/iconv/ccs/binary/us_ascii.cct, libc/iconv/ces/Makefile.am, libc/iconv/ces/Makefile.in, libc/iconv/ces/euc-jp.c, libc/iconv/ces/euc-kr.c, libc/iconv/ces/euc-tw.c, libc/iconv/ces/gb2312.c, libc/iconv/ces/iso-10646-ucs-2.c, libc/iconv/ces/iso-10646-ucs-4.c, libc/iconv/ces/ucs-2-internal.c, libc/iconv/ces/ucs-4-internal.c, libc/iconv/ces/utf-16.c, libc/iconv/ces/utf-8.c, libc/iconv/lib/Makefile.am, libc/iconv/lib/Makefile.in, libc/iconv/lib/aliases.c, libc/iconv/lib/bialiasesi.c, libc/iconv/lib/biccs.c, libc/iconv/lib/bices.c, libc/iconv/lib/ccs.c, libc/iconv/lib/ces.c, libc/iconv/lib/ces_euc.c, libc/iconv/lib/ces_iso2022.c, libc/iconv/lib/ces_table.c, libc/iconv/lib/converter.c, libc/iconv/lib/deps.h, libc/iconv/lib/endian.h, libc/iconv/lib/iconv.c, libc/iconv/lib/loaddata.c, libc/iconv/lib/local.h, libc/include/iconv.h: New files. * libc/sys/linux/include/iconv.h: Ditto. * libc/include/sys/_types.h (_iconv_t): Added. * doc/aclocal.m4: Regenerated. * doc/configure: Ditto. * doc/Makefile.in: Ditto. * iconvdata/Makefile.in: Ditto. * iconvdata/aclocal.m4: Ditto. * iconvdata/configure: Ditto. * libc/*aclocal.m4: Ditto. * libc/*Makefile.in: Ditto. * libc/*configure: Ditto. * libm/*aclocal.m4: Ditto. * libm/*Makefile.in: Ditto. * libm/*configure: Ditto.
2004-01-24 05:37:46 +08:00
* Document Index::
* Function Index::
2000-02-18 03:39:52 +08:00
@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.
2000-02-18 03:39:52 +08:00
@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
* Function va_start::
* Function va_arg::
* Function va_end::
2000-02-18 03:39:52 +08:00
@end menu
@page
@node Function va_start
2000-02-18 03:39:52 +08:00
@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 Function va_arg
2000-02-18 03:39:52 +08:00
@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 Function va_end
2000-02-18 03:39:52 +08:00
@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
* Function va_alist::
* Function va_start-trad::
* Function va_arg-trad::
* Function va_end-trad::
2000-02-18 03:39:52 +08:00
@end menu
@page
@node Function va_alist
2000-02-18 03:39:52 +08:00
@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 Function va_start-trad
2000-02-18 03:39:52 +08:00
@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 Function va_arg-trad
2000-02-18 03:39:52 +08:00
@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 Function va_end-trad
2000-02-18 03:39:52 +08:00
@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
2000-02-18 03:39:52 +08:00
@printindex cp
@node Function Index
@unnumbered Function Index
@printindex fn
2000-02-18 03:39:52 +08:00
@tex
% I think something like @@colophon should be in texinfo. In the
2000-02-18 03:39:52 +08:00
% 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.
2000-02-18 03:39:52 +08:00
@end tex
@contents
@bye