   This file documents the ANSI C library.

   Copyright (C) 1992, 1993, 1994-2009 Red Hat, Inc.

   `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.

   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.

The Red Hat newlib C Library
****************************

1 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.  See Syscalls, for a description of the
relevant operating system calls.

2 Standard Utility Functions (`stdlib.h')
*****************************************

This chapter groups utility functions useful in a variety of programs.
The corresponding declarations are in the header file `stdlib.h'.

2.1 `_Exit'--end program execution with no cleanup processing
=============================================================

*Synopsis*
     #include <stdlib.h>
     void _Exit(int CODE);
   *Description*
Use `_Exit' to return control from a program to the host operating
environment.  Use the argument CODE to pass an exit status to the
operating environment: two particular values, `EXIT_SUCCESS' and
`EXIT_FAILURE', are defined in ``stdlib.h'' to indicate success or
failure in a portable fashion.

   `_Exit' differs from `exit' in that it does not run any
application-defined cleanup functions registered with `atexit' and it
does not clean up files and streams.  It is identical to `_exit'.

*Returns*
`_Exit' does not return to its caller.

*Portability*
`_Exit' is defined by the C99 standard.

   Supporting OS subroutines required: `_exit'.

2.2 `a64l', `l64a'--convert between radix-64 ASCII string and long
==================================================================

*Synopsis*
     #include <stdlib.h>
     long a64l(const char *INPUT);
     char *l64a(long INPUT);
   *Description*
Conversion is performed between long and radix-64 characters.  The
`l64a' routine transforms up to 32 bits of input value starting from
least significant bits to the most significant bits.  The input value
is split up into a maximum of 5 groups of 6 bits and possibly one group
of 2 bits (bits 31 and 30).

   Each group of 6 bits forms a value from 0-63 which is translated into
a character as follows:

   * 0 = '.'

   * 1 = '/'

   * 2-11 = '0' to '9'

   * 12-37 = 'A' to 'Z'

   * 38-63 = 'a' to 'z'

   When the remaining bits are zero or all bits have been translated, a
null terminator is appended to the string.  An input value of 0 results
in the empty string.

   The `a64l' function performs the reverse translation.  Each
character is used to generate a 6-bit value for up to 30 bits and then
a 2-bit value to complete a 32-bit result.  The null terminator means
that the remaining digits are 0.  An empty input string or NULL string
results in 0L.  An invalid string results in undefined behavior.  If
the size of a long is greater than 32 bits, the result is sign-extended.

*Returns*
`l64a' returns a null-terminated string of 0 to 6 characters.  `a64l'
returns the 32-bit translated value from the input character string.

*Portability*
`l64a' and `a64l' are non-ANSI and are defined by the Single Unix
Specification.

   Supporting OS subroutines required: None.

2.3 `abort'--abnormal termination of a program
==============================================

*Synopsis*
     #include <stdlib.h>
     void abort(void);
   *Description*
Use `abort' to signal that your program has detected a condition it
cannot deal with.  Normally, `abort' ends your program's execution.

   Before terminating your program, `abort' raises the exception
`SIGABRT' (using ``raise(SIGABRT)'').  If you have used `signal' to
register an exception handler for this condition, that handler has the
opportunity to retain control, thereby avoiding program termination.

   In this implementation, `abort' does not perform any stream- or
file-related cleanup (the host environment may do so; if not, you can
arrange for your program to do its own cleanup with a `SIGABRT'
exception handler).

*Returns*
`abort' does not return to its caller.

*Portability*
ANSI C requires `abort'.

   Supporting OS subroutines required: `_exit' and optionally, `write'.

2.4 `abs'--integer absolute value (magnitude)
=============================================

*Synopsis*
     #include <stdlib.h>
     int abs(int I);
   *Description*
`abs' returns the absolute value of I (also called the magnitude of I).
That is, if I is negative, the result is the opposite of I, but if I is
nonnegative the result is I.

   The similar function `labs' uses and returns `long' rather than
`int' values.

*Returns*
The result is a nonnegative integer.

*Portability*
`abs' is ANSI.

   No supporting OS subroutines are required.

2.5 `assert'--macro for debugging diagnostics
=============================================

*Synopsis*
     #include <assert.h>
     void assert(int EXPRESSION);
   *Description*
Use this macro to embed debuggging diagnostic statements in your
programs.  The argument EXPRESSION should be an expression which
evaluates to true (nonzero) when your program is working as you
intended.

   When EXPRESSION evaluates to false (zero), `assert' calls `abort',
after first printing a message showing what failed and where:

      Assertion failed: EXPRESSION, file FILENAME, line LINENO, function: FUNC

   If the name of the current function is not known (for example, when
using a C89 compiler that does not understand __func__), the function
location is omitted.

   The macro is defined to permit you to turn off all uses of `assert'
at compile time by defining `NDEBUG' as a preprocessor variable.   If
you do this, the `assert' macro expands to

      (void(0))

*Returns*
`assert' does not return a value.

*Portability*
The `assert' macro is required by ANSI, as is the behavior when
`NDEBUG' is defined.

   Supporting OS subroutines required (only if enabled): `close',
`fstat', `getpid', `isatty', `kill', `lseek', `read', `sbrk', `write'.

2.6 `atexit'--request execution of functions at program exit
============================================================

*Synopsis*
     #include <stdlib.h>
     int atexit (void (*FUNCTION)(void));
   *Description*
You can use `atexit' to enroll functions in a list of functions that
will be called when your program terminates normally.  The argument is
a pointer to a user-defined function (which must not require arguments
and must not return a result).

   The functions are kept in a LIFO stack; that is, the last function
enrolled by `atexit' will be the first to execute when your program
exits.

   There is no built-in limit to the number of functions you can enroll
in this list; however, after every group of 32 functions is enrolled,
`atexit' will call `malloc' to get space for the next part of the list.
 The initial list of 32 functions is statically allocated, so you can
always count on at least that many slots available.

*Returns*
`atexit' returns `0' if it succeeds in enrolling your function, `-1' if
it fails (possible only if no space was available for `malloc' to
extend the list of functions).

*Portability*
`atexit' is required by the ANSI standard, which also specifies that
implementations must support enrolling at least 32 functions.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.

2.7 `atof', `atoff'--string to double or float
==============================================

*Synopsis*
     #include <stdlib.h>
     double atof(const char *S);
     float atoff(const char *S);
   *Description*
`atof' converts the initial portion of a string to a `double'.  `atoff'
converts the initial portion of a string to a `float'.

   The functions parse the character string S, locating a substring
which can be converted to a floating-point value. The substring must
match the format:
      [+|-]DIGITS[.][DIGITS][(e|E)[+|-]DIGITS]
   The substring converted is the longest initial fragment of S that
has the expected format, beginning with the first non-whitespace
character.  The substring is empty if `str' is empty, consists entirely
of whitespace, or if the first non-whitespace character is something
other than `+', `-', `.', or a digit.

   `atof(S)' is implemented as `strtod(S, NULL)'.  `atoff(S)' is
implemented as `strtof(S, NULL)'.

*Returns*
`atof' returns the converted substring value, if any, as a `double'; or
`0.0',  if no conversion could be performed.  If the correct value is
out of the range of representable values, plus or minus `HUGE_VAL' is
returned, and `ERANGE' is stored in `errno'.  If the correct value
would cause underflow, `0.0' is returned and `ERANGE' is stored in
`errno'.

   `atoff' obeys the same rules as `atof', except that it returns a
`float'.

*Portability*
`atof' is ANSI C. `atof', `atoi', and `atol' are subsumed by `strod'
and `strol', but are used extensively in existing code. These functions
are less reliable, but may be faster if the argument is verified to be
in a valid range.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.

2.8 `atoi', `atol'--string to integer
=====================================

*Synopsis*
     #include <stdlib.h>
     int atoi(const char *S);
     long atol(const char *S);
     int _atoi_r(struct _reent *PTR, const char *S);
     long _atol_r(struct _reent *PTR, const char *S);
   *Description*
`atoi' converts the initial portion of a string to an `int'.  `atol'
converts the initial portion of a string to a `long'.

   `atoi(s)' is implemented as `(int)strtol(s, NULL, 10).' `atol(s)' is
implemented as `strtol(s, NULL, 10).'

   `_atoi_r' and `_atol_r' are reentrant versions of `atoi' and `atol'
respectively, passing the reentrancy struct pointer.

*Returns*
The functions return the converted value, if any. If no conversion was
made, `0' is returned.

*Portability*
`atoi', `atol' are ANSI.

   No supporting OS subroutines are required.

2.9 `atoll'--convert a string to a long long integer
====================================================

*Synopsis*
     #include <stdlib.h>
     long long atoll(const char *STR);
     long long _atoll_r(struct _reent *PTR, const char *STR);
   *Description*
The function `atoll' converts the initial portion of the string pointed
to by `*STR' to a type `long long'.  A call to atoll(str) in this
implementation is equivalent to strtoll(str, (char **)NULL, 10)
including behavior on error.

   The alternate function `_atoll_r' is a reentrant version.  The extra
argument REENT is a pointer to a reentrancy structure.

*Returns*
The converted value.

*Portability*
`atoll' is ISO 9899 (C99) and POSIX 1003.1-2001 compatable.

   No supporting OS subroutines are required.

2.10 `bsearch'--binary search
=============================

*Synopsis*
     #include <stdlib.h>
     void *bsearch(const void *KEY, const void *BASE,
         size_t NMEMB, size_t SIZE,
         int (*COMPAR)(const void *, const void *));
   *Description*
`bsearch' searches an array beginning at BASE for any element that
matches KEY, using binary search.  NMEMB is the element count of the
array; SIZE is the size of each element.

   The array must be sorted in ascending order with respect to the
comparison function COMPAR (which you supply as the last argument of
`bsearch').

   You must define the comparison function `(*COMPAR)' to have two
arguments; its result must be negative if the first argument is less
than the second, zero if the two arguments match, and positive if the
first argument is greater than the second (where "less than" and
"greater than" refer to whatever arbitrary ordering is appropriate).

*Returns*
Returns a pointer to an element of ARRAY that matches KEY.  If more
than one matching element is available, the result may point to any of
them.

*Portability*
`bsearch' is ANSI.

   No supporting OS subroutines are required.

2.11 `calloc'--allocate space for arrays
========================================

*Synopsis*
     #include <stdlib.h>
     void *calloc(size_t N, size_t S);
     void *_calloc_r(void *REENT, size_t N, size_t S);
   *Description*
Use `calloc' to request a block of memory sufficient to hold an array
of N elements, each of which has size S.

   The memory allocated by `calloc' comes out of the same memory pool
used by `malloc', but the memory block is initialized to all zero
bytes.  (To avoid the overhead of initializing the space, use `malloc'
instead.)

   The alternate function `_calloc_r' is reentrant.  The extra argument
REENT is a pointer to a reentrancy structure.

*Returns*
If successful, a pointer to the newly allocated space.

   If unsuccessful, `NULL'.

*Portability*
`calloc' is ANSI.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.

2.12 `div'--divide two integers
===============================

*Synopsis*
     #include <stdlib.h>
     div_t div(int N, int D);
   *Description*
Divide N/D, returning quotient and remainder as two integers in a
structure `div_t'.

*Returns*
The result is represented with the structure

      typedef struct
      {
       int quot;
       int rem;
      } div_t;

   where the `quot' field represents the quotient, and `rem' the
remainder.  For nonzero D, if ``R = div(N,D);'' then N equals ``R.rem +
D*R.quot''.

   To divide `long' rather than `int' values, use the similar function
`ldiv'.

*Portability*
`div' is ANSI.

   No supporting OS subroutines are required.

2.13 `ecvt', `ecvtf', `fcvt', `fcvtf'--double or float to string
================================================================

*Synopsis*
     #include <stdlib.h>

     char *ecvt(double VAL, int CHARS, int *DECPT, int *SGN);
     char *ecvtf(float VAL, int CHARS, int *DECPT, int *SGN);

     char *fcvt(double VAL, int DECIMALS,
         int *DECPT, int *SGN);
     char *fcvtf(float VAL, int DECIMALS,
         int *DECPT, int *SGN);
   *Description*
`ecvt' and `fcvt' produce (null-terminated) strings of digits
representating the `double' number VAL.  `ecvtf' and `fcvtf' produce
the corresponding character representations of `float' numbers.

   (The `stdlib' functions `ecvtbuf' and `fcvtbuf' are reentrant
versions of `ecvt' and `fcvt'.)

   The only difference between `ecvt' and `fcvt' is the interpretation
of the second argument (CHARS or DECIMALS).  For `ecvt', the second
argument CHARS specifies the total number of characters to write (which
is also the number of significant digits in the formatted string, since
these two functions write only digits).  For `fcvt', the second
argument DECIMALS specifies the number of characters to write after the
decimal point; all digits for the integer part of VAL are always
included.

   Since `ecvt' and `fcvt' write only digits in the output string, they
record the location of the decimal point in `*DECPT', and the sign of
the number in `*SGN'.  After formatting a number, `*DECPT' contains the
number of digits to the left of the decimal point.  `*SGN' contains `0'
if the number is positive, and `1' if it is negative.

*Returns*
All four functions return a pointer to the new string containing a
character representation of VAL.

*Portability*
None of these functions are ANSI C.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.

2.14 `gvcvt', `gcvtf'--format double or float as string
=======================================================

*Synopsis*
     #include <stdlib.h>

     char *gcvt(double VAL, int PRECISION, char *BUF);
     char *gcvtf(float VAL, int PRECISION, char *BUF);
   *Description*
`gcvt' writes a fully formatted number as a null-terminated string in
the buffer `*BUF'.  `gdvtf' produces corresponding character
representations of `float' numbers.

   `gcvt' uses the same rules as the `printf' format
``%.PRECISIONg''--only negative values are signed (with ``-''), and
either exponential or ordinary decimal-fraction format is chosen
depending on the number of significant digits (specified by PRECISION).

*Returns*
The result is a pointer to the formatted representation of VAL (the
same as the argument BUF).

*Portability*
Neither function is ANSI C.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.

2.15 `ecvtbuf', `fcvtbuf'--double or float to string
====================================================

*Synopsis*
     #include <stdio.h>

     char *ecvtbuf(double VAL, int CHARS, int *DECPT,
         int *SGN, char *BUF);

     char *fcvtbuf(double VAL, int DECIMALS, int *DECPT,
         int *SGN, char *BUF);
   *Description*
`ecvtbuf' and `fcvtbuf' produce (null-terminated) strings of digits
representating the `double' number VAL.

   The only difference between `ecvtbuf' and `fcvtbuf' is the
interpretation of the second argument (CHARS or DECIMALS). For
`ecvtbuf', the second argument CHARS specifies the total number of
characters to write (which is also the number of significant digits in
the formatted string, since these two functions write only digits). For
`fcvtbuf', the second argument DECIMALS specifies the number of
characters to write after the decimal point; all digits for the integer
part of VAL are always included.

   Since `ecvtbuf' and `fcvtbuf' write only digits in the output
string, they record the location of the decimal point in `*DECPT', and
the sign of the number in `*SGN'.  After formatting a number, `*DECPT'
contains the number of digits to the left of the decimal point.  `*SGN'
contains `0' if the number is positive, and `1' if it is negative.  For
both functions, you supply a pointer BUF to an area of memory to hold
the converted string.

*Returns*
Both functions return a pointer to BUF, the string containing a
character representation of VAL.

*Portability*
Neither function is ANSI C.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.

2.16 `__env_lock', `__env_unlock'--lock environ variable
========================================================

*Synopsis*
     #include <envlock.h>
     void __env_lock (struct _reent *REENT);
     void __env_unlock (struct _reent *REENT);
   *Description*
The `setenv' family of routines call these functions when they need to
modify the environ variable.  The version of these routines supplied in
the library use the lock API defined in sys/lock.h.  If multiple
threads of execution can call `setenv', or if `setenv' can be called
reentrantly, then you need to define your own versions of these
functions in order to safely lock the memory pool during a call.  If
you do not, the memory pool may become corrupted.

   A call to `setenv' may call `__env_lock' recursively; that is, the
sequence of calls may go `__env_lock', `__env_lock', `__env_unlock',
`__env_unlock'.  Any implementation of these routines must be careful
to avoid causing a thread to wait for a lock that it already holds.

2.17 `exit'--end program execution
==================================

*Synopsis*
     #include <stdlib.h>
     void exit(int CODE);
   *Description*
Use `exit' to return control from a program to the host operating
environment.  Use the argument CODE to pass an exit status to the
operating environment: two particular values, `EXIT_SUCCESS' and
`EXIT_FAILURE', are defined in ``stdlib.h'' to indicate success or
failure in a portable fashion.

   `exit' does two kinds of cleanup before ending execution of your
program.  First, it calls all application-defined cleanup functions you
have enrolled with `atexit'.  Second, files and streams are cleaned up:
any pending output is delivered to the host system, each open file or
stream is closed, and files created by `tmpfile' are deleted.

*Returns*
`exit' does not return to its caller.

*Portability*
ANSI C requires `exit', and specifies that `EXIT_SUCCESS' and
`EXIT_FAILURE' must be defined.

   Supporting OS subroutines required: `_exit'.

2.18 `getenv'--look up environment variable
===========================================

*Synopsis*
     #include <stdlib.h>
     char *getenv(const char *NAME);
   *Description*
`getenv' searches the list of environment variable names and values
(using the global pointer "`char **environ'") for a variable whose name
matches the string at NAME.  If a variable name matches, `getenv'
returns a pointer to the associated value.

*Returns*
A pointer to the (string) value of the environment variable, or `NULL'
if there is no such environment variable.

*Portability*
`getenv' is ANSI, but the rules for properly forming names of
environment variables vary from one system to another.

   `getenv' requires a global pointer `environ'.

2.19 `labs'--long integer absolute value
========================================

*Synopsis*
     #include <stdlib.h>
     long labs(long I);
   *Description*
`labs' returns the absolute value of I (also called the magnitude of
I).  That is, if I is negative, the result is the opposite of I, but if
I is nonnegative the result is I.

   The similar function `abs' uses and returns `int' rather than `long'
values.

*Returns*
The result is a nonnegative long integer.

*Portability*
`labs' is ANSI.

   No supporting OS subroutine calls are required.

2.20 `ldiv'--divide two long integers
=====================================

*Synopsis*
     #include <stdlib.h>
     ldiv_t ldiv(long N, long D);
   *Description*
Divide N/D, returning quotient and remainder as two long integers in a
structure `ldiv_t'.

*Returns*
The result is represented with the structure

      typedef struct
      {
       long quot;
       long rem;
      } ldiv_t;

   where the `quot' field represents the quotient, and `rem' the
remainder.  For nonzero D, if ``R = ldiv(N,D);'' then N equals ``R.rem
+ D*R.quot''.

   To divide `int' rather than `long' values, use the similar function
`div'.

*Portability*
`ldiv' is ANSI.

   No supporting OS subroutines are required.

2.21 `llabs'--compute the absolute value of an long long integer.
=================================================================

*Synopsis*
     #include <stdlib.h>
     long long llabs(long long j);
   *Description*
The `llabs' function computes the absolute value of the long long
integer argument J (also called the magnitude of J).

   The similar function `labs' uses and returns `long' rather than
`long long' values.

*Returns*
A nonnegative long long integer.

*Portability*
`llabs' is ISO 9899 (C99) compatable.

   No supporting OS subroutines are required.

2.22 `lldiv'--divide two long long integers
===========================================

*Synopsis*
     #include <stdlib.h>
     lldiv_t lldiv(long long N, long long D);
   *Description*
Divide N/D, returning quotient and remainder as two long long integers
in a structure `lldiv_t'.

*Returns*
The result is represented with the structure

      typedef struct
      {
       long long quot;
       long long rem;
      } lldiv_t;

   where the `quot' field represents the quotient, and `rem' the
remainder.  For nonzero D, if ``R = ldiv(N,D);'' then N equals ``R.rem
+ D*R.quot''.

   To divide `long' rather than `long long' values, use the similar
function `ldiv'.

*Portability*
`lldiv' is ISO 9899 (C99) compatable.

   No supporting OS subroutines are required.

2.23 `malloc', `realloc', `free'--manage memory
===============================================

*Synopsis*
     #include <stdlib.h>
     void *malloc(size_t NBYTES);
     void *realloc(void *APTR, size_t NBYTES);
     void *reallocf(void *APTR, size_t NBYTES);
     void free(void *APTR);

     void *memalign(size_t ALIGN, size_t NBYTES);

     size_t malloc_usable_size(void *APTR);

     void *_malloc_r(void *REENT, size_t NBYTES);
     void *_realloc_r(void *REENT,
         void *APTR, size_t NBYTES);
     void *_reallocf_r(void *REENT,
         void *APTR, size_t NBYTES);
     void _free_r(void *REENT, void *APTR);

     void *_memalign_r(void *REENT,
         size_t ALIGN, size_t NBYTES);

     size_t _malloc_usable_size_r(void *REENT, void *APTR);
   *Description*
These functions manage a pool of system memory.

   Use `malloc' to request allocation of an object with at least NBYTES
bytes of storage available.  If the space is available, `malloc'
returns a pointer to a newly allocated block as its result.

   If you already have a block of storage allocated by `malloc', but
you no longer need all the space allocated to it, you can make it
smaller by calling `realloc' with both the object pointer and the new
desired size as arguments.  `realloc' guarantees that the contents of
the smaller object match the beginning of the original object.

   Similarly, if you need more space for an object, use `realloc' to
request the larger size; again, `realloc' guarantees that the beginning
of the new, larger object matches the contents of the original object.

   When you no longer need an object originally allocated by `malloc'
or `realloc' (or the related function `calloc'), return it to the
memory storage pool by calling `free' with the address of the object as
the argument.  You can also use `realloc' for this purpose by calling
it with `0' as the NBYTES argument.

   The `reallocf' function behaves just like `realloc' except if the
function is required to allocate new storage and this fails.  In this
case `reallocf' will free the original object passed in whereas
`realloc' will not.

   The `memalign' function returns a block of size NBYTES aligned to a
ALIGN boundary.  The ALIGN argument must be a power of two.

   The `malloc_usable_size' function takes a pointer to a block
allocated by `malloc'.  It returns the amount of space that is
available in the block.  This may or may not be more than the size
requested from `malloc', due to alignment or minimum size constraints.

   The alternate functions `_malloc_r', `_realloc_r', `_reallocf_r',
`_free_r', `_memalign_r', and `_malloc_usable_size_r' are reentrant
versions.  The extra argument REENT is a pointer to a reentrancy
structure.

   If you have multiple threads of execution which may call any of these
routines, or if any of these routines may be called reentrantly, then
you must provide implementations of the `__malloc_lock' and
`__malloc_unlock' functions for your system.  See the documentation for
those functions.

   These functions operate by calling the function `_sbrk_r' or `sbrk',
which allocates space.  You may need to provide one of these functions
for your system.  `_sbrk_r' is called with a positive value to allocate
more space, and with a negative value to release previously allocated
space if it is no longer required.  See Stubs.

*Returns*
`malloc' returns a pointer to the newly allocated space, if successful;
otherwise it returns `NULL'.  If your application needs to generate
empty objects, you may use `malloc(0)' for this purpose.

   `realloc' returns a pointer to the new block of memory, or `NULL' if
a new block could not be allocated.  `NULL' is also the result when you
use ``realloc(APTR,0)'' (which has the same effect as ``free(APTR)'').
You should always check the result of `realloc'; successful
reallocation is not guaranteed even when you request a smaller object.

   `free' does not return a result.

   `memalign' returns a pointer to the newly allocated space.

   `malloc_usable_size' returns the usable size.

*Portability*
`malloc', `realloc', and `free' are specified by the ANSI C standard,
but other conforming implementations of `malloc' may behave differently
when NBYTES is zero.

   `memalign' is part of SVR4.

   `malloc_usable_size' is not portable.

   Supporting OS subroutines required: `sbrk'.

2.24 `mallinfo', `malloc_stats', `mallopt'--malloc support
==========================================================

*Synopsis*
     #include <malloc.h>
     struct mallinfo mallinfo(void);
     void malloc_stats(void);
     int mallopt(int PARAMETER, VALUE);

     struct mallinfo _mallinfo_r(void *REENT);
     void _malloc_stats_r(void *REENT);
     int _mallopt_r(void *REENT, int PARAMETER, VALUE);
   *Description*
`mallinfo' returns a structure describing the current state of memory
allocation.  The structure is defined in malloc.h.  The following
fields are defined: `arena' is the total amount of space in the heap;
`ordblks' is the number of chunks which are not in use; `uordblks' is
the total amount of space allocated by `malloc'; `fordblks' is the
total amount of space not in use; `keepcost' is the size of the top
most memory block.

   `malloc_stats' print some statistics about memory allocation on
standard error.

   `mallopt' takes a parameter and a value.  The parameters are defined
in malloc.h, and may be one of the following: `M_TRIM_THRESHOLD' sets
the maximum amount of unused space in the top most block before
releasing it back to the system in `free' (the space is released by
calling `_sbrk_r' with a negative argument); `M_TOP_PAD' is the amount
of padding to allocate whenever `_sbrk_r' is called to allocate more
space.

   The alternate functions `_mallinfo_r', `_malloc_stats_r', and
`_mallopt_r' are reentrant versions.  The extra argument REENT is a
pointer to a reentrancy structure.

*Returns*
`mallinfo' returns a mallinfo structure.  The structure is defined in
malloc.h.

   `malloc_stats' does not return a result.

   `mallopt' returns zero if the parameter could not be set, or
non-zero if it could be set.

*Portability*
`mallinfo' and `mallopt' are provided by SVR4, but `mallopt' takes
different parameters on different systems.  `malloc_stats' is not
portable.

2.25 `__malloc_lock', `__malloc_unlock'--lock malloc pool
=========================================================

*Synopsis*
     #include <malloc.h>
     void __malloc_lock (struct _reent *REENT);
     void __malloc_unlock (struct _reent *REENT);
   *Description*
The `malloc' family of routines call these functions when they need to
lock the memory pool.  The version of these routines supplied in the
library use the lock API defined in sys/lock.h.  If multiple threads of
execution can call `malloc', or if `malloc' can be called reentrantly,
then you need to define your own versions of these functions in order
to safely lock the memory pool during a call.  If you do not, the
memory pool may become corrupted.

   A call to `malloc' may call `__malloc_lock' recursively; that is,
the sequence of calls may go `__malloc_lock', `__malloc_lock',
`__malloc_unlock', `__malloc_unlock'.  Any implementation of these
routines must be careful to avoid causing a thread to wait for a lock
that it already holds.

2.26 `mblen'--minimal multibyte length function
===============================================

*Synopsis*
     #include <stdlib.h>
     int mblen(const char *S, size_t N);
   *Description*
When _MB_CAPABLE is not defined, this is a minimal ANSI-conforming
implementation of `mblen'.  In this case, the only "multi-byte
character sequences" recognized are single bytes, and thus `1' is
returned unless S is the null pointer or has a length of 0 or is the
empty string.

   When _MB_CAPABLE is defined, this routine calls `_mbtowc_r' to
perform the conversion, passing a state variable to allow state
dependent decoding.  The result is based on the locale setting which may
be restricted to a defined set of locales.

*Returns*
This implementation of `mblen' returns `0' if S is `NULL' or the empty
string; it returns `1' if not _MB_CAPABLE or the character is a
single-byte character; it returns `-1' if the multi-byte character is
invalid; otherwise it returns the number of bytes in the multibyte
character.

*Portability*
`mblen' is required in the ANSI C standard.  However, the precise
effects vary with the locale.

   `mblen' requires no supporting OS subroutines.

2.27 `mbsrtowcs', `mbsnrtowcs'--convert a character string to a wide-character string
=====================================================================================

*Synopsis*
     #include <wchar.h>
     size_t mbsrtowcs(wchar_t *DST, const char **SRC, size_t LEN,
         mbstate_t *PS);

     #include <wchar.h>
     size_t _mbsrtowcs_r(struct _reent *PTR, wchar_t *DST,
         const char **SRC, size_t LEN,
         mbstate_t *PS);

     #include <wchar.h>
     size_t mbsnrtowcs(wchar_t *DST, const char **SRC,
         size_t NMS, size_t LEN, mbstate_t *PS);

     #include <wchar.h>
     size_t _mbsnrtowcs_r(struct _reent *PTR, wchar_t *DST,
         const char **SRC, size_t NMS,
         size_t LEN, mbstate_t *PS);
   *Description*
The `mbsrtowcs' function converts a sequence of multibyte characters
pointed to indirectly by SRC into a sequence of corresponding wide
characters and stores at most LEN of them in the wchar_t array pointed
to by DST, until it encounters a terminating null character ('\0').

   If DST is NULL, no characters are stored.

   If DST is not NULL, the pointer pointed to by SRC is updated to point
to the character after the one that conversion stopped at.  If
conversion stops because a null character is encountered, *SRC is set
to NULL.

   The mbstate_t argument, PS, is used to keep track of the shift
state.  If it is NULL, `mbsrtowcs' uses an internal, static mbstate_t
object, which is initialized to the initial conversion state at program
startup.

   The `mbsnrtowcs' function behaves identically to `mbsrtowcs', except
that conversion stops after reading at most NMS bytes from the buffer
pointed to by SRC.

*Returns*
The `mbsrtowcs' and `mbsnrtowcs' functions return the number of wide
characters stored in the array pointed to by DST if successful,
otherwise it returns (size_t)-1.

*Portability*
`mbsrtowcs' is defined by the C99 standard.  `mbsnrtowcs' is defined by
the POSIX.1-2008 standard.

2.28 `mbstowcs'--minimal multibyte string to wide char converter
================================================================

*Synopsis*
     #include <stdlib.h>
     int mbstowcs(wchar_t *PWC, const char *S, size_t N);
   *Description*
When _MB_CAPABLE is not defined, this is a minimal ANSI-conforming
implementation of `mbstowcs'.  In this case, the only "multi-byte
character sequences" recognized are single bytes, and they are
"converted" to wide-char versions simply by byte extension.

   When _MB_CAPABLE is defined, this routine calls `_mbstowcs_r' to
perform the conversion, passing a state variable to allow state
dependent decoding.  The result is based on the locale setting which may
be restricted to a defined set of locales.

*Returns*
This implementation of `mbstowcs' returns `0' if S is `NULL' or is the
empty string; it returns `-1' if _MB_CAPABLE and one of the multi-byte
characters is invalid or incomplete; otherwise it returns the minimum
of: `n' or the number of multi-byte characters in `s' plus 1 (to
compensate for the nul character).  If the return value is -1, the
state of the `pwc' string is indeterminate.  If the input has a length
of 0, the output string will be modified to contain a wchar_t nul
terminator.

*Portability*
`mbstowcs' is required in the ANSI C standard.  However, the precise
effects vary with the locale.

   `mbstowcs' requires no supporting OS subroutines.

2.29 `mbtowc'--minimal multibyte to wide char converter
=======================================================

*Synopsis*
     #include <stdlib.h>
     int mbtowc(wchar_t *PWC, const char *S, size_t N);
   *Description*
When _MB_CAPABLE is not defined, this is a minimal ANSI-conforming
implementation of `mbtowc'.  In this case, only "multi-byte character
sequences" recognized are single bytes, and they are "converted" to
themselves.  Each call to `mbtowc' copies one character from `*S' to
`*PWC', unless S is a null pointer.  The argument n is ignored.

   When _MB_CAPABLE is defined, this routine calls `_mbtowc_r' to
perform the conversion, passing a state variable to allow state
dependent decoding.  The result is based on the locale setting which may
be restricted to a defined set of locales.

*Returns*
This implementation of `mbtowc' returns `0' if S is `NULL' or is the
empty string; it returns `1' if not _MB_CAPABLE or the character is a
single-byte character; it returns `-1' if n is `0' or the multi-byte
character is invalid; otherwise it returns the number of bytes in the
multibyte character.  If the return value is -1, no changes are made to
the `pwc' output string.  If the input is the empty string, a wchar_t
nul is placed in the output string and 0 is returned.  If the input has
a length of 0, no changes are made to the `pwc' output string.

*Portability*
`mbtowc' is required in the ANSI C standard.  However, the precise
effects vary with the locale.

   `mbtowc' requires no supporting OS subroutines.

2.30 `on_exit'--request execution of function with argument at program exit
===========================================================================

*Synopsis*
     #include <stdlib.h>
     int on_exit (void (*FUNCTION)(int, void *), void *ARG);
   *Description*
You can use `on_exit' to enroll functions in a list of functions that
will be called when your program terminates normally.  The argument is
a pointer to a user-defined function which takes two arguments.  The
first is the status code passed to exit and the second argument is of
type pointer to void.  The function must not return a result.  The value
of ARG is registered and passed as the argument to FUNCTION.

   The functions are kept in a LIFO stack; that is, the last function
enrolled by `atexit' or `on_exit' will be the first to execute when
your program exits.  You can intermix functions using `atexit' and
`on_exit'.

   There is no built-in limit to the number of functions you can enroll
in this list; however, after every group of 32 functions is enrolled,
`atexit'/`on_exit' will call `malloc' to get space for the next part of
the list.   The initial list of 32 functions is statically allocated, so
you can always count on at least that many slots available.

*Returns*
`on_exit' returns `0' if it succeeds in enrolling your function, `-1'
if it fails (possible only if no space was available for `malloc' to
extend the list of functions).

*Portability*
`on_exit' is a non-standard glibc extension

   Supporting OS subroutines required: None

2.31 `qsort'--sort an array
===========================

*Synopsis*
     #include <stdlib.h>
     void qsort(void *BASE, size_t NMEMB, size_t SIZE,
         int (*COMPAR)(const void *, const void *) );
   *Description*
`qsort' sorts an array (beginning at BASE) of NMEMB objects.  SIZE
describes the size of each element of the array.

   You must supply a pointer to a comparison function, using the
argument shown as COMPAR.  (This permits sorting objects of unknown
properties.)  Define the comparison function to accept two arguments,
each a pointer to an element of the array starting at BASE.  The result
of `(*COMPAR)' must be negative if the first argument is less than the
second, zero if the two arguments match, and positive if the first
argument is greater than the second (where "less than" and "greater
than" refer to whatever arbitrary ordering is appropriate).

   The array is sorted in place; that is, when `qsort' returns, the
array elements beginning at BASE have been reordered.

*Returns*
`qsort' does not return a result.

*Portability*
`qsort' is required by ANSI (without specifying the sorting algorithm).

2.32 `rand', `srand'--pseudo-random numbers
===========================================

*Synopsis*
     #include <stdlib.h>
     int rand(void);
     void srand(unsigned int SEED);
     int rand_r(unsigned int *SEED);
   *Description*
`rand' returns a different integer each time it is called; each integer
is chosen by an algorithm designed to be unpredictable, so that you can
use `rand' when you require a random number.  The algorithm depends on
a static variable called the "random seed"; starting with a given value
of the random seed always produces the same sequence of numbers in
successive calls to `rand'.

   You can set the random seed using `srand'; it does nothing beyond
storing its argument in the static variable used by `rand'.  You can
exploit this to make the pseudo-random sequence less predictable, if
you wish, by using some other unpredictable value (often the least
significant parts of a time-varying value) as the random seed before
beginning a sequence of calls to `rand'; or, if you wish to ensure (for
example, while debugging) that successive runs of your program use the
same "random" numbers, you can use `srand' to set the same random seed
at the outset.

*Returns*
`rand' returns the next pseudo-random integer in sequence; it is a
number between `0' and `RAND_MAX' (inclusive).

   `srand' does not return a result.

*Portability*
`rand' is required by ANSI, but the algorithm for pseudo-random number
generation is not specified; therefore, even if you use the same random
seed, you cannot expect the same sequence of results on two different
systems.

   `rand' requires no supporting OS subroutines.

2.33 `rand48', `drand48', `erand48', `lrand48', `nrand48', `mrand48', `jrand48', `srand48', `seed48', `lcong48'--pseudo-random number generators and initialization routines
============================================================================================================================================================================

*Synopsis*
     #include <stdlib.h>
     double drand48(void);
     double erand48(unsigned short XSEED[3]);
     long lrand48(void);
     long nrand48(unsigned short XSEED[3]);
     long mrand48(void);
     long jrand48(unsigned short XSEED[3]);
     void srand48(long SEED);
     unsigned short *seed48(unsigned short XSEED[3]);
     void lcong48(unsigned short P[7]);
   *Description*
The `rand48' family of functions generates pseudo-random numbers using
a linear congruential algorithm working on integers 48 bits in size.
The particular formula employed is r(n+1) = (a * r(n) + c) mod m where
the default values are for the multiplicand a = 0xfdeece66d =
25214903917 and the addend c = 0xb = 11. The modulo is always fixed at
m = 2 ** 48.  r(n) is called the seed of the random number generator.

   For all the six generator routines described next, the first
computational step is to perform a single iteration of the algorithm.

   `drand48' and `erand48' return values of type double. The full 48
bits of r(n+1) are loaded into the mantissa of the returned value, with
the exponent set such that the values produced lie in the interval
[0.0, 1.0].

   `lrand48' and `nrand48' return values of type long in the range [0,
2**31-1]. The high-order (31) bits of r(n+1) are loaded into the lower
bits of the returned value, with the topmost (sign) bit set to zero.

   `mrand48' and `jrand48' return values of type long in the range
[-2**31, 2**31-1]. The high-order (32) bits of r(n+1) are loaded into
the returned value.

   `drand48', `lrand48', and `mrand48' use an internal buffer to store
r(n). For these functions the initial value of r(0) = 0x1234abcd330e =
20017429951246.

   On the other hand, `erand48', `nrand48', and `jrand48' use a
user-supplied buffer to store the seed r(n), which consists of an array
of 3 shorts, where the zeroth member holds the least significant bits.

   All functions share the same multiplicand and addend.

   `srand48' is used to initialize the internal buffer r(n) of
`drand48', `lrand48', and `mrand48' such that the 32 bits of the seed
value are copied into the upper 32 bits of r(n), with the lower 16 bits
of r(n) arbitrarily being set to 0x330e.  Additionally, the constant
multiplicand and addend of the algorithm are reset to the default
values given above.

   `seed48' also initializes the internal buffer r(n) of `drand48',
`lrand48', and `mrand48', but here all 48 bits of the seed can be
specified in an array of 3 shorts, where the zeroth member specifies
the lowest bits. Again, the constant multiplicand and addend of the
algorithm are reset to the default values given above.  `seed48'
returns a pointer to an array of 3 shorts which contains the old seed.
This array is statically allocated, thus its contents are lost after
each new call to `seed48'.

   Finally, `lcong48' allows full control over the multiplicand and
addend used in `drand48', `erand48', `lrand48', `nrand48', `mrand48',
and `jrand48', and the seed used in `drand48', `lrand48', and `mrand48'.
An array of 7 shorts is passed as parameter; the first three shorts are
used to initialize the seed; the second three are used to initialize the
multiplicand; and the last short is used to initialize the addend.  It
is thus not possible to use values greater than 0xffff as the addend.

   Note that all three methods of seeding the random number generator
always also set the multiplicand and addend for any of the six
generator calls.

   For a more powerful random number generator, see `random'.

*Portability*
SUS requires these functions.

   No supporting OS subroutines are required.

2.34 `strtod', `strtof'--string to double or float
==================================================

*Synopsis*
     #include <stdlib.h>
     double strtod(const char *STR, char **TAIL);
     float strtof(const char *STR, char **TAIL);

     double _strtod_r(void *REENT,
         const char *STR, char **TAIL);
   *Description*
The function `strtod' parses the character string STR, producing a
substring which can be converted to a double value.  The substring
converted is the longest initial subsequence of STR, beginning with the
first non-whitespace character, that has one of these formats:
     [+|-]DIGITS[.[DIGITS]][(e|E)[+|-]DIGITS]
     [+|-].DIGITS[(e|E)[+|-]DIGITS]
     [+|-](i|I)(n|N)(f|F)[(i|I)(n|N)(i|I)(t|T)(y|Y)]
     [+|-](n|N)(a|A)(n|N)[<(>[HEXDIGITS]<)>]
     [+|-]0(x|X)HEXDIGITS[.[HEXDIGITS]][(p|P)[+|-]DIGITS]
     [+|-]0(x|X).HEXDIGITS[(p|P)[+|-]DIGITS]
   The substring contains no characters if STR is empty, consists
entirely of whitespace, or if the first non-whitespace character is
something other than `+', `-', `.', or a digit, and cannot be parsed as
infinity or NaN. If the platform does not support NaN, then NaN is
treated as an empty substring.  If the substring is empty, no
conversion is done, and the value of STR is stored in `*TAIL'.
Otherwise, the substring is converted, and a pointer to the final string
(which will contain at least the terminating null character of STR) is
stored in `*TAIL'.  If you want no assignment to `*TAIL', pass a null
pointer as TAIL.  `strtof' is identical to `strtod' except for its
return type.

   This implementation returns the nearest machine number to the input
decimal string.  Ties are broken by using the IEEE round-even rule.
However, `strtof' is currently subject to double rounding errors.

   The alternate function `_strtod_r' is a reentrant version.  The
extra argument REENT is a pointer to a reentrancy structure.

*Returns*
`strtod' returns the converted substring value, if any.  If no
conversion could be performed, 0 is returned.  If the correct value is
out of the range of representable values, plus or minus `HUGE_VAL' is
returned, and `ERANGE' is stored in errno. If the correct value would
cause underflow, 0 is returned and `ERANGE' is stored in errno.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.

2.35 `strtol'--string to long
=============================

*Synopsis*
     #include <stdlib.h>
     long strtol(const char *S, char **PTR,int BASE);

     long _strtol_r(void *REENT,
         const char *S, char **PTR,int BASE);
   *Description*
The function `strtol' converts the string `*S' to a `long'. First, it
breaks down the string into three parts: leading whitespace, which is
ignored; a subject string consisting of characters resembling an
integer in the radix specified by BASE; and a trailing portion
consisting of zero or more unparseable characters, and always including
the terminating null character. Then, it attempts to convert the
subject string into a `long' and returns the result.

   If the value of BASE is 0, the subject string is expected to look
like a normal C integer constant: an optional sign, a possible ``0x''
indicating a hexadecimal base, and a number. If BASE is between 2 and
36, the expected form of the subject is a sequence of letters and
digits representing an integer in the radix specified by BASE, with an
optional plus or minus sign. The letters `a'-`z' (or, equivalently,
`A'-`Z') are used to signify values from 10 to 35; only letters whose
ascribed values are less than BASE are permitted. If BASE is 16, a
leading `0x' is permitted.

   The subject sequence is the longest initial sequence of the input
string that has the expected form, starting with the first
non-whitespace character.  If the string is empty or consists entirely
of whitespace, or if the first non-whitespace character is not a
permissible letter or digit, the subject string is empty.

   If the subject string is acceptable, and the value of BASE is zero,
`strtol' attempts to determine the radix from the input string. A
string with a leading `0x' is treated as a hexadecimal value; a string
with a leading 0 and no `x' is treated as octal; all other strings are
treated as decimal. If BASE is between 2 and 36, it is used as the
conversion radix, as described above. If the subject string begins with
a minus sign, the value is negated. Finally, a pointer to the first
character past the converted subject string is stored in PTR, if PTR is
not `NULL'.

   If the subject string is empty (or not in acceptable form), no
conversion is performed and the value of S is stored in PTR (if PTR is
not `NULL').

   The alternate function `_strtol_r' is a reentrant version.  The
extra argument REENT is a pointer to a reentrancy structure.

*Returns*
`strtol' returns the converted value, if any. If no conversion was
made, 0 is returned.

   `strtol' returns `LONG_MAX' or `LONG_MIN' if the magnitude of the
converted value is too large, and sets `errno' to `ERANGE'.

*Portability*
`strtol' is ANSI.

   No supporting OS subroutines are required.

2.36 `strtoll'--string to long long
===================================

*Synopsis*
     #include <stdlib.h>
     long long strtoll(const char *S, char **PTR,int BASE);

     long long _strtoll_r(void *REENT,
         const char *S, char **PTR,int BASE);
   *Description*
The function `strtoll' converts the string `*S' to a `long long'.
First, it breaks down the string into three parts: leading whitespace,
which is ignored; a subject string consisting of characters resembling
an integer in the radix specified by BASE; and a trailing portion
consisting of zero or more unparseable characters, and always including
the terminating null character. Then, it attempts to convert the
subject string into a `long long' and returns the result.

   If the value of BASE is 0, the subject string is expected to look
like a normal C integer constant: an optional sign, a possible ``0x''
indicating a hexadecimal base, and a number. If BASE is between 2 and
36, the expected form of the subject is a sequence of letters and
digits representing an integer in the radix specified by BASE, with an
optional plus or minus sign. The letters `a'-`z' (or, equivalently,
`A'-`Z') are used to signify values from 10 to 35; only letters whose
ascribed values are less than BASE are permitted. If BASE is 16, a
leading `0x' is permitted.

   The subject sequence is the longest initial sequence of the input
string that has the expected form, starting with the first
non-whitespace character.  If the string is empty or consists entirely
of whitespace, or if the first non-whitespace character is not a
permissible letter or digit, the subject string is empty.

   If the subject string is acceptable, and the value of BASE is zero,
`strtoll' attempts to determine the radix from the input string. A
string with a leading `0x' is treated as a hexadecimal value; a string
with a leading 0 and no `x' is treated as octal; all other strings are
treated as decimal. If BASE is between 2 and 36, it is used as the
conversion radix, as described above. If the subject string begins with
a minus sign, the value is negated. Finally, a pointer to the first
character past the converted subject string is stored in PTR, if PTR is
not `NULL'.

   If the subject string is empty (or not in acceptable form), no
conversion is performed and the value of S is stored in PTR (if PTR is
not `NULL').

   The alternate function `_strtoll_r' is a reentrant version.  The
extra argument REENT is a pointer to a reentrancy structure.

*Returns*
`strtoll' returns the converted value, if any. If no conversion was
made, 0 is returned.

   `strtoll' returns `LONG_LONG_MAX' or `LONG_LONG_MIN' if the
magnitude of the converted value is too large, and sets `errno' to
`ERANGE'.

*Portability*
`strtoll' is ANSI.

   No supporting OS subroutines are required.

2.37 `strtoul'--string to unsigned long
=======================================

*Synopsis*
     #include <stdlib.h>
     unsigned long strtoul(const char *S, char **PTR,
         int BASE);

     unsigned long _strtoul_r(void *REENT, const char *S,
         char **PTR, int BASE);
   *Description*
The function `strtoul' converts the string `*S' to an `unsigned long'.
First, it breaks down the string into three parts: leading whitespace,
which is ignored; a subject string consisting of the digits meaningful
in the radix specified by BASE (for example, `0' through `7' if the
value of BASE is 8); and a trailing portion consisting of one or more
unparseable characters, which always includes the terminating null
character. Then, it attempts to convert the subject string into an
unsigned long integer, and returns the result.

   If the value of BASE is zero, the subject string is expected to look
like a normal C integer constant (save that no optional sign is
permitted): a possible `0x' indicating hexadecimal radix, and a number.
If BASE is between 2 and 36, the expected form of the subject is a
sequence of digits (which may include letters, depending on the base)
representing an integer in the radix specified by BASE.  The letters
`a'-`z' (or `A'-`Z') are used as digits valued from 10 to 35. If BASE
is 16, a leading `0x' is permitted.

   The subject sequence is the longest initial sequence of the input
string that has the expected form, starting with the first
non-whitespace character.  If the string is empty or consists entirely
of whitespace, or if the first non-whitespace character is not a
permissible digit, the subject string is empty.

   If the subject string is acceptable, and the value of BASE is zero,
`strtoul' attempts to determine the radix from the input string. A
string with a leading `0x' is treated as a hexadecimal value; a string
with a leading `0' and no `x' is treated as octal; all other strings are
treated as decimal. If BASE is between 2 and 36, it is used as the
conversion radix, as described above. Finally, a pointer to the first
character past the converted subject string is stored in PTR, if PTR is
not `NULL'.

   If the subject string is empty (that is, if `*'S does not start with
a substring in acceptable form), no conversion is performed and the
value of S is stored in PTR (if PTR is not `NULL').

   The alternate function `_strtoul_r' is a reentrant version.  The
extra argument REENT is a pointer to a reentrancy structure.

*Returns*
`strtoul' returns the converted value, if any. If no conversion was
made, `0' is returned.

   `strtoul' returns `ULONG_MAX' if the magnitude of the converted
value is too large, and sets `errno' to `ERANGE'.

*Portability*
`strtoul' is ANSI.

   `strtoul' requires no supporting OS subroutines.

2.38 `strtoull'--string to unsigned long long
=============================================

*Synopsis*
     #include <stdlib.h>
     unsigned long long strtoull(const char *S, char **PTR,
         int BASE);

     unsigned long long _strtoull_r(void *REENT, const char *S,
         char **PTR, int BASE);
   *Description*
The function `strtoull' converts the string `*S' to an `unsigned long
long'. First, it breaks down the string into three parts: leading
whitespace, which is ignored; a subject string consisting of the digits
meaningful in the radix specified by BASE (for example, `0' through `7'
if the value of BASE is 8); and a trailing portion consisting of one or
more unparseable characters, which always includes the terminating null
character. Then, it attempts to convert the subject string into an
unsigned long long integer, and returns the result.

   If the value of BASE is zero, the subject string is expected to look
like a normal C integer constant (save that no optional sign is
permitted): a possible `0x' indicating hexadecimal radix, and a number.
If BASE is between 2 and 36, the expected form of the subject is a
sequence of digits (which may include letters, depending on the base)
representing an integer in the radix specified by BASE.  The letters
`a'-`z' (or `A'-`Z') are used as digits valued from 10 to 35. If BASE
is 16, a leading `0x' is permitted.

   The subject sequence is the longest initial sequence of the input
string that has the expected form, starting with the first
non-whitespace character.  If the string is empty or consists entirely
of whitespace, or if the first non-whitespace character is not a
permissible digit, the subject string is empty.

   If the subject string is acceptable, and the value of BASE is zero,
`strtoull' attempts to determine the radix from the input string. A
string with a leading `0x' is treated as a hexadecimal value; a string
with a leading `0' and no `x' is treated as octal; all other strings are
treated as decimal. If BASE is between 2 and 36, it is used as the
conversion radix, as described above. Finally, a pointer to the first
character past the converted subject string is stored in PTR, if PTR is
not `NULL'.

   If the subject string is empty (that is, if `*'S does not start with
a substring in acceptable form), no conversion is performed and the
value of S is stored in PTR (if PTR is not `NULL').

   The alternate function `_strtoull_r' is a reentrant version.  The
extra argument REENT is a pointer to a reentrancy structure.

*Returns*
`strtoull' returns the converted value, if any. If no conversion was
made, `0' is returned.

   `strtoull' returns `ULONG_LONG_MAX' if the magnitude of the converted
value is too large, and sets `errno' to `ERANGE'.

*Portability*
`strtoull' is ANSI.

   `strtoull' requires no supporting OS subroutines.

2.39 `wcsrtombs', `wcsnrtombs'--convert a wide-character string to a character string
=====================================================================================

*Synopsis*
     #include <wchar.h>
     size_t wcsrtombs(char *DST, const wchar_t **SRC, size_t LEN,
         mbstate_t *PS);

     #include <wchar.h>
     size_t _wcsrtombs_r(struct _reent *PTR, char *DST,
         const wchar_t **SRC, size_t LEN,
         mbstate_t *PS);

     #include <wchar.h>
     size_t wcsnrtombs(char *DST, const wchar_t **SRC,
         size_t NWC, size_t LEN, mbstate_t *PS);

     #include <wchar.h>
     size_t _wcsnrtombs_r(struct _reent *PTR, char *DST,
         const wchar_t **SRC, size_t NWC,
         size_t LEN, mbstate_t *PS);
   *Description*
The `wcsrtombs' function converts a string of wide characters indirectly
pointed to by SRC to a corresponding multibyte character string stored
in the array pointed to by DST>.  No more than LEN bytes are written to
DST>.

   If DST> is NULL, no characters are stored.

   If DST> is not NULL, the pointer pointed to by SRC is updated to
point to the character after the one that conversion stopped at.  If
conversion stops because a null character is encountered, *SRC is set
to NULL.

   The mbstate_t argument, PS, is used to keep track of the shift
state.  If it is NULL, `wcsrtombs' uses an internal, static mbstate_t
object, which is initialized to the initial conversion state at program
startup.

   The `wcsnrtombs' function behaves identically to `wcsrtombs', except
that conversion stops after reading at most NWC characters from the
buffer pointed to by SRC.

*Returns*
The `wcsrtombs' and `wcsnrtombs' functions return the number of bytes
stored in the array pointed to by DST (not including any terminating
null), if successful, otherwise it returns (size_t)-1.

*Portability*
`wcsrtombs' is defined by C99 standard.  `wcsnrtombs' is defined by the
POSIX.1-2008 standard.

2.40 `wcstod', `wcstof'--wide char string to double or float
============================================================

*Synopsis*
     #include <stdlib.h>
     double wcstod(const wchar_t *STR, wchar_t **TAIL);
     float wcstof(const wchar_t *STR, wchar_t **TAIL);

     double _wcstod_r(void *REENT,
         const wchar_t *STR, wchar_t **TAIL);
     float _wcstof_r(void *REENT,
         const wchar_t *STR, wchar_t **TAIL);
   *Description*
The function `wcstod' parses the wide character string STR, producing a
substring which can be converted to a double value.  The substring
converted is the longest initial subsequence of STR, beginning with the
first non-whitespace character, that has one of these formats:
     [+|-]DIGITS[.[DIGITS]][(e|E)[+|-]DIGITS]
     [+|-].DIGITS[(e|E)[+|-]DIGITS]
     [+|-](i|I)(n|N)(f|F)[(i|I)(n|N)(i|I)(t|T)(y|Y)]
     [+|-](n|N)(a|A)(n|N)[<(>[HEXDIGITS]<)>]
     [+|-]0(x|X)HEXDIGITS[.[HEXDIGITS]][(p|P)[+|-]DIGITS]
     [+|-]0(x|X).HEXDIGITS[(p|P)[+|-]DIGITS]
   The substring contains no characters if STR is empty, consists
entirely of whitespace, or if the first non-whitespace character is
something other than `+', `-', `.', or a digit, and cannot be parsed as
infinity or NaN. If the platform does not support NaN, then NaN is
treated as an empty substring.  If the substring is empty, no
conversion is done, and the value of STR is stored in `*TAIL'.
Otherwise, the substring is converted, and a pointer to the final string
(which will contain at least the terminating null character of STR) is
stored in `*TAIL'.  If you want no assignment to `*TAIL', pass a null
pointer as TAIL.  `wcstof' is identical to `wcstod' except for its
return type.

   This implementation returns the nearest machine number to the input
decimal string.  Ties are broken by using the IEEE round-even rule.
However, `wcstof' is currently subject to double rounding errors.

   The alternate functions `_wcstod_r' and `_wcstof_r' are reentrant
versions of `wcstod' and `wcstof', respectively.  The extra argument
REENT is a pointer to a reentrancy structure.

*Returns*
Return the converted substring value, if any.  If no conversion could
be performed, 0 is returned.  If the correct value is out of the range
of representable values, plus or minus `HUGE_VAL' is returned, and
`ERANGE' is stored in errno. If the correct value would cause
underflow, 0 is returned and `ERANGE' is stored in errno.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.

2.41 `wcstol'--wide string to long
==================================

*Synopsis*
     #include <wchar.h>
     long wcstol(const wchar_t *S, wchar_t **PTR,int BASE);

     long _wcstol_r(void *REENT,
         const wchar_t *S, wchar_t **PTR,int BASE);
   *Description*
The function `wcstol' converts the wide string `*S' to a `long'. First,
it breaks down the string into three parts: leading whitespace, which
is ignored; a subject string consisting of characters resembling an
integer in the radix specified by BASE; and a trailing portion
consisting of zero or more unparseable characters, and always including
the terminating null character. Then, it attempts to convert the
subject string into a `long' and returns the result.

   If the value of BASE is 0, the subject string is expected to look
like a normal C integer constant: an optional sign, a possible ``0x''
indicating a hexadecimal base, and a number. If BASE is between 2 and
36, the expected form of the subject is a sequence of letters and
digits representing an integer in the radix specified by BASE, with an
optional plus or minus sign. The letters `a'-`z' (or, equivalently,
`A'-`Z') are used to signify values from 10 to 35; only letters whose
ascribed values are less than BASE are permitted. If BASE is 16, a
leading `0x' is permitted.

   The subject sequence is the longest initial sequence of the input
string that has the expected form, starting with the first
non-whitespace character.  If the string is empty or consists entirely
of whitespace, or if the first non-whitespace character is not a
permissible letter or digit, the subject string is empty.

   If the subject string is acceptable, and the value of BASE is zero,
`wcstol' attempts to determine the radix from the input string. A
string with a leading `0x' is treated as a hexadecimal value; a string
with a leading 0 and no `x' is treated as octal; all other strings are
treated as decimal. If BASE is between 2 and 36, it is used as the
conversion radix, as described above. If the subject string begins with
a minus sign, the value is negated. Finally, a pointer to the first
character past the converted subject string is stored in PTR, if PTR is
not `NULL'.

   If the subject string is empty (or not in acceptable form), no
conversion is performed and the value of S is stored in PTR (if PTR is
not `NULL').

   The alternate function `_wcstol_r' is a reentrant version.  The
extra argument REENT is a pointer to a reentrancy structure.

*Returns*
`wcstol' returns the converted value, if any. If no conversion was
made, 0 is returned.

   `wcstol' returns `LONG_MAX' or `LONG_MIN' if the magnitude of the
converted value is too large, and sets `errno' to `ERANGE'.

*Portability*
`wcstol' is ANSI.

   No supporting OS subroutines are required.

2.42 `wcstoll'--wide string to long long
========================================

*Synopsis*
     #include <wchar.h>
     long long wcstoll(const wchar_t *S, wchar_t **PTR,int BASE);

     long long _wcstoll_r(void *REENT,
         const wchar_t *S, wchar_t **PTR,int BASE);
   *Description*
The function `wcstoll' converts the wide string `*S' to a `long long'.
First, it breaks down the string into three parts: leading whitespace,
which is ignored; a subject string consisting of characters resembling
an integer in the radix specified by BASE; and a trailing portion
consisting of zero or more unparseable characters, and always including
the terminating null character. Then, it attempts to convert the
subject string into a `long long' and returns the result.

   If the value of BASE is 0, the subject string is expected to look
like a normal C integer constant: an optional sign, a possible ``0x''
indicating a hexadecimal base, and a number. If BASE is between 2 and
36, the expected form of the subject is a sequence of letters and
digits representing an integer in the radix specified by BASE, with an
optional plus or minus sign. The letters `a'-`z' (or, equivalently,
`A'-`Z') are used to signify values from 10 to 35; only letters whose
ascribed values are less than BASE are permitted. If BASE is 16, a
leading `0x' is permitted.

   The subject sequence is the longest initial sequence of the input
string that has the expected form, starting with the first
non-whitespace character.  If the string is empty or consists entirely
of whitespace, or if the first non-whitespace character is not a
permissible letter or digit, the subject string is empty.

   If the subject string is acceptable, and the value of BASE is zero,
`wcstoll' attempts to determine the radix from the input string. A
string with a leading `0x' is treated as a hexadecimal value; a string
with a leading 0 and no `x' is treated as octal; all other strings are
treated as decimal. If BASE is between 2 and 36, it is used as the
conversion radix, as described above. If the subject string begins with
a minus sign, the value is negated. Finally, a pointer to the first
character past the converted subject string is stored in PTR, if PTR is
not `NULL'.

   If the subject string is empty (or not in acceptable form), no
conversion is performed and the value of S is stored in PTR (if PTR is
not `NULL').

   The alternate function `_wcstoll_r' is a reentrant version.  The
extra argument REENT is a pointer to a reentrancy structure.

*Returns*
`wcstoll' returns the converted value, if any. If no conversion was
made, 0 is returned.

   `wcstoll' returns `LONG_LONG_MAX' or `LONG_LONG_MIN' if the
magnitude of the converted value is too large, and sets `errno' to
`ERANGE'.

*Portability*
`wcstoll' is ANSI.

   No supporting OS subroutines are required.

2.43 `wcstoul'--wide string to unsigned long
============================================

*Synopsis*
     #include <wchar.h>
     unsigned long wcstoul(const wchar_t *S, wchar_t **PTR,
         int BASE);

     unsigned long _wcstoul_r(void *REENT, const wchar_t *S,
         wchar_t **PTR, int BASE);
   *Description*
The function `wcstoul' converts the wide string `*S' to an `unsigned
long'. First, it breaks down the string into three parts: leading
whitespace, which is ignored; a subject string consisting of the digits
meaningful in the radix specified by BASE (for example, `0' through `7'
if the value of BASE is 8); and a trailing portion consisting of one or
more unparseable characters, which always includes the terminating null
character. Then, it attempts to convert the subject string into an
unsigned long integer, and returns the result.

   If the value of BASE is zero, the subject string is expected to look
like a normal C integer constant (save that no optional sign is
permitted): a possible `0x' indicating hexadecimal radix, and a number.
If BASE is between 2 and 36, the expected form of the subject is a
sequence of digits (which may include letters, depending on the base)
representing an integer in the radix specified by BASE.  The letters
`a'-`z' (or `A'-`Z') are used as digits valued from 10 to 35. If BASE
is 16, a leading `0x' is permitted.

   The subject sequence is the longest initial sequence of the input
string that has the expected form, starting with the first
non-whitespace character.  If the string is empty or consists entirely
of whitespace, or if the first non-whitespace character is not a
permissible digit, the subject string is empty.

   If the subject string is acceptable, and the value of BASE is zero,
`wcstoul' attempts to determine the radix from the input string. A
string with a leading `0x' is treated as a hexadecimal value; a string
with a leading `0' and no `x' is treated as octal; all other strings are
treated as decimal. If BASE is between 2 and 36, it is used as the
conversion radix, as described above. Finally, a pointer to the first
character past the converted subject string is stored in PTR, if PTR is
not `NULL'.

   If the subject string is empty (that is, if `*'S does not start with
a substring in acceptable form), no conversion is performed and the
value of S is stored in PTR (if PTR is not `NULL').

   The alternate function `_wcstoul_r' is a reentrant version.  The
extra argument REENT is a pointer to a reentrancy structure.

*Returns*
`wcstoul' returns the converted value, if any. If no conversion was
made, `0' is returned.

   `wcstoul' returns `ULONG_MAX' if the magnitude of the converted
value is too large, and sets `errno' to `ERANGE'.

*Portability*
`wcstoul' is ANSI.

   `wcstoul' requires no supporting OS subroutines.

2.44 `wcstoull'--wide string to unsigned long long
==================================================

*Synopsis*
     #include <wchar.h>
     unsigned long long wcstoull(const wchar_t *S, wchar_t **PTR,
         int BASE);

     unsigned long long _wcstoull_r(void *REENT, const wchar_t *S,
         wchar_t **PTR, int BASE);
   *Description*
The function `wcstoull' converts the wide string `*S' to an `unsigned
long long'. First, it breaks down the string into three parts: leading
whitespace, which is ignored; a subject string consisting of the digits
meaningful in the radix specified by BASE (for example, `0' through `7'
if the value of BASE is 8); and a trailing portion consisting of one or
more unparseable characters, which always includes the terminating null
character. Then, it attempts to convert the subject string into an
unsigned long long integer, and returns the result.

   If the value of BASE is zero, the subject string is expected to look
like a normal C integer constant:  an optional sign (`+' or `-'), a
possible `0x' indicating hexadecimal radix or a possible <0> indicating
octal radix, and a number.  If BASE is between 2 and 36, the expected
form of the subject is a sequence of digits (which may include letters,
depending on the base) representing an integer in the radix specified
by BASE.  The letters `a'-`z' (or `A'-`Z') are used as digits valued
from 10 to 35. If BASE is 16, a leading `0x' is permitted.

   The subject sequence is the longest initial sequence of the input
string that has the expected form, starting with the first
non-whitespace character.  If the string is empty or consists entirely
of whitespace, or if the first non-whitespace character is not a
permissible digit, the subject string is empty.

   If the subject string is acceptable, and the value of BASE is zero,
`wcstoull' attempts to determine the radix from the input string. A
string with a leading `0x' is treated as a hexadecimal value; a string
with a leading `0' and no `x' is treated as octal; all other strings are
treated as decimal. If BASE is between 2 and 36, it is used as the
conversion radix, as described above. Finally, a pointer to the first
character past the converted subject string is stored in PTR, if PTR is
not `NULL'.

   If the subject string is empty (that is, if `*'S does not start with
a substring in acceptable form), no conversion is performed and the
value of S is stored in PTR (if PTR is not `NULL').

   The alternate function `_wcstoull_r' is a reentrant version.  The
extra argument REENT is a pointer to a reentrancy structure.

*Returns*
`wcstoull' returns `0' and sets `errno' to `EINVAL' if the value of
BASE is not supported.

   `wcstoull' returns the converted value, if any. If no conversion was
made, `0' is returned.

   `wcstoull' returns `ULLONG_MAX' if the magnitude of the converted
value is too large, and sets `errno' to `ERANGE'.

*Portability*
`wcstoull' is ANSI.

   `wcstoull' requires no supporting OS subroutines.

2.45 `system'--execute command string
=====================================

*Synopsis*
     #include <stdlib.h>
     int system(char *S);

     int _system_r(void *REENT, char *S);
   *Description*
Use `system' to pass a command string `*S' to `/bin/sh' on your system,
and wait for it to finish executing.

   Use "`system(NULL)'" to test whether your system has `/bin/sh'
available.

   The alternate function `_system_r' is a reentrant version.  The
extra argument REENT is a pointer to a reentrancy structure.

*Returns*
`system(NULL)' returns a non-zero value if `/bin/sh' is available, and
`0' if it is not.

   With a command argument, the result of `system' is the exit status
returned by `/bin/sh'.

*Portability*
ANSI C requires `system', but leaves the nature and effects of a
command processor undefined.  ANSI C does, however, specify that
`system(NULL)' return zero or nonzero to report on the existence of a
command processor.

   POSIX.2 requires `system', and requires that it invoke a `sh'.
Where `sh' is found is left unspecified.

   Supporting OS subroutines required: `_exit', `_execve', `_fork_r',
`_wait_r'.

2.46 `wcstombs'--minimal wide char string to multibyte string converter
=======================================================================

*Synopsis*
     #include <stdlib.h>
     size_t wcstombs(char *S, const wchar_t *PWC, size_t N);
   *Description*
When _MB_CAPABLE is not defined, this is a minimal ANSI-conforming
implementation of `wcstombs'.  In this case, all wide-characters are
expected to represent single bytes and so are converted simply by
casting to char.

   When _MB_CAPABLE is defined, this routine calls `_wcstombs_r' to
perform the conversion, passing a state variable to allow state
dependent decoding.  The result is based on the locale setting which may
be restricted to a defined set of locales.

*Returns*
This implementation of `wcstombs' returns `0' if S is `NULL' or is the
empty string; it returns `-1' if _MB_CAPABLE and one of the wide-char
characters does not represent a valid multi-byte character; otherwise
it returns the minimum of: `n' or the number of bytes that are
transferred to `s', not including the nul terminator.

   If the return value is -1, the state of the `pwc' string is
indeterminate.  If the input has a length of 0, the output string will
be modified to contain a wchar_t nul terminator if `n' > 0.

*Portability*
`wcstombs' is required in the ANSI C standard.  However, the precise
effects vary with the locale.

   `wcstombs' requires no supporting OS subroutines.

2.47 `wctomb'--minimal wide char to multibyte converter
=======================================================

*Synopsis*
     #include <stdlib.h>
     int wctomb(char *S, wchar_t WCHAR);
   *Description*
When _MB_CAPABLE is not defined, this is a minimal ANSI-conforming
implementation of `wctomb'.  The only "wide characters" recognized are
single bytes, and they are "converted" to themselves.

   When _MB_CAPABLE is defined, this routine calls `_wctomb_r' to
perform the conversion, passing a state variable to allow state
dependent decoding.  The result is based on the locale setting which may
be restricted to a defined set of locales.

   Each call to `wctomb' modifies `*S' unless S is a null pointer or
_MB_CAPABLE is defined and WCHAR is invalid.

*Returns*
This implementation of `wctomb' returns `0' if S is `NULL'; it returns
`-1' if _MB_CAPABLE is enabled and the wchar is not a valid multi-byte
character, it returns `1' if _MB_CAPABLE is not defined or the wchar is
in reality a single byte character, otherwise it returns the number of
bytes in the multi-byte character.

*Portability*
`wctomb' is required in the ANSI C standard.  However, the precise
effects vary with the locale.

   `wctomb' requires no supporting OS subroutines.

3 Character Type Macros and Functions (`ctype.h')
*************************************************

This chapter groups macros (which are also available as subroutines) to
classify characters into several categories (alphabetic, numeric,
control characters, whitespace, and so on), or to perform simple
character mappings.

   The header file `ctype.h' defines the macros.

3.1 `isalnum'--alphanumeric character predicate
===============================================

*Synopsis*
     #include <ctype.h>
     int isalnum(int C);
   *Description*
`isalnum' is a macro which classifies ASCII integer values by table
lookup.  It is a predicate returning non-zero for alphabetic or numeric
ASCII characters, and `0' for other arguments.  It is defined for all
integer values.

   You can use a compiled subroutine instead of the macro definition by
undefining the macro using ``#undef isalnum''.

*Returns*
`isalnum' returns non-zero if C is a letter (`a'-`z' or `A'-`Z') or a
digit (`0'-`9').

*Portability*
`isalnum' is ANSI C.

   No OS subroutines are required.

3.2 `isalpha'--alphabetic character predicate
=============================================

*Synopsis*
     #include <ctype.h>
     int isalpha(int C);
   *Description*
`isalpha' is a macro which classifies ASCII integer values by table
lookup.  It is a predicate returning non-zero when C represents an
alphabetic ASCII character, and 0 otherwise.  It is defined only when
`isascii'(C) is true or C is EOF.

   You can use a compiled subroutine instead of the macro definition by
undefining the macro using ``#undef isalpha''.

*Returns*
`isalpha' returns non-zero if C is a letter (`A'-`Z' or `a'-`z').

*Portability*
`isalpha' is ANSI C.

   No supporting OS subroutines are required.

3.3 `isascii'--ASCII character predicate
========================================

*Synopsis*
     #include <ctype.h>
     int isascii(int C);
   *Description*
`isascii' is a macro which returns non-zero when C is an ASCII
character, and 0 otherwise.  It is defined for all integer values.

   You can use a compiled subroutine instead of the macro definition by
undefining the macro using ``#undef isascii''.

*Returns*
`isascii' returns non-zero if the low order byte of C is in the range 0
to 127 (`0x00'-`0x7F').

*Portability*
`isascii' is ANSI C.

   No supporting OS subroutines are required.

3.4 `iscntrl'--control character predicate
==========================================

*Synopsis*
     #include <ctype.h>
     int iscntrl(int C);
   *Description*
`iscntrl' is a macro which classifies ASCII integer values by table
lookup.  It is a predicate returning non-zero for control characters,
and 0 for other characters.  It is defined only when `isascii'(C) is
true or C is EOF.

   You can use a compiled subroutine instead of the macro definition by
undefining the macro using ``#undef iscntrl''.

*Returns*
`iscntrl' returns non-zero if C is a delete character or ordinary
control character (`0x7F' or `0x00'-`0x1F').

*Portability*
`iscntrl' is ANSI C.

   No supporting OS subroutines are required.

3.5 `isdigit'--decimal digit predicate
======================================

*Synopsis*
     #include <ctype.h>
     int isdigit(int C);
   *Description*
`isdigit' is a macro which classifies ASCII integer values by table
lookup.  It is a predicate returning non-zero for decimal digits, and 0
for other characters.  It is defined only when `isascii'(C) is true or
C is EOF.

   You can use a compiled subroutine instead of the macro definition by
undefining the macro using ``#undef isdigit''.

*Returns*
`isdigit' returns non-zero if C is a decimal digit (`0'-`9').

*Portability*
`isdigit' is ANSI C.

   No supporting OS subroutines are required.

3.6 `islower'--lowercase character predicate
============================================

*Synopsis*
     #include <ctype.h>
     int islower(int C);
   *Description*
`islower' is a macro which classifies ASCII integer values by table
lookup.  It is a predicate returning non-zero for minuscules (lowercase
alphabetic characters), and 0 for other characters.  It is defined only
when `isascii'(C) is true or C is EOF.

   You can use a compiled subroutine instead of the macro definition by
undefining the macro using ``#undef islower''.

*Returns*
`islower' returns non-zero if C is a lowercase letter (`a'-`z').

*Portability*
`islower' is ANSI C.

   No supporting OS subroutines are required.

3.7 `isprint', `isgraph'--printable character predicates
========================================================

*Synopsis*
     #include <ctype.h>
     int isprint(int C);
     int isgraph(int C);
   *Description*
`isprint' is a macro which classifies ASCII integer values by table
lookup.  It is a predicate returning non-zero for printable characters,
and 0 for other character arguments.  It is defined only when
`isascii'(C) is true or C is EOF.

   You can use a compiled subroutine instead of the macro definition by
undefining either macro using ``#undef isprint'' or ``#undef isgraph''.

*Returns*
`isprint' returns non-zero if C is a printing character,
(`0x20'-`0x7E').  `isgraph' behaves identically to `isprint', except
that the space character (`0x20') is excluded.

*Portability*
`isprint' and `isgraph' are ANSI C.

   No supporting OS subroutines are required.

3.8 `ispunct'--punctuation character predicate
==============================================

*Synopsis*
     #include <ctype.h>
     int ispunct(int C);
   *Description*
`ispunct' is a macro which classifies ASCII integer values by table
lookup.  It is a predicate returning non-zero for printable punctuation
characters, and 0 for other characters.  It is defined only when
`isascii'(C) is true or C is EOF.

   You can use a compiled subroutine instead of the macro definition by
undefining the macro using ``#undef ispunct''.

*Returns*
`ispunct' returns non-zero if C is a printable punctuation character
(`isgraph(C) && !isalnum(C)').

*Portability*
`ispunct' is ANSI C.

   No supporting OS subroutines are required.

3.9 `isspace'--whitespace character predicate
=============================================

*Synopsis*
     #include <ctype.h>
     int isspace(int C);
   *Description*
`isspace' is a macro which classifies ASCII integer values by table
lookup.  It is a predicate returning non-zero for whitespace
characters, and 0 for other characters.  It is defined only when
`isascii'(C) is true or C is EOF.

   You can use a compiled subroutine instead of the macro definition by
undefining the macro using ``#undef isspace''.

*Returns*
`isspace' returns non-zero if C is a space, tab, carriage return, new
line, vertical tab, or formfeed (`0x09'-`0x0D', `0x20').

*Portability*
`isspace' is ANSI C.

   No supporting OS subroutines are required.

3.10 `isupper'--uppercase character predicate
=============================================

*Synopsis*
     #include <ctype.h>
     int isupper(int C);
   *Description*
`isupper' is a macro which classifies ASCII integer values by table
lookup.  It is a predicate returning non-zero for uppercase letters
(`A'-`Z'), and 0 for other characters.  It is defined only when
`isascii'(C) is true or C is EOF.

   You can use a compiled subroutine instead of the macro definition by
undefining the macro using ``#undef isupper''.

*Returns*
`isupper' returns non-zero if C is a uppercase letter (A-Z).

*Portability*
`isupper' is ANSI C.

   No supporting OS subroutines are required.

3.11 `isxdigit'--hexadecimal digit predicate
============================================

*Synopsis*
     #include <ctype.h>
     int isxdigit(int C);
   *Description*
`isxdigit' is a macro which classifies ASCII integer values by table
lookup.  It is a predicate returning non-zero for hexadecimal digits,
and `0' for other characters.  It is defined only when `isascii'(C) is
true or C is EOF.

   You can use a compiled subroutine instead of the macro definition by
undefining the macro using ``#undef isxdigit''.

*Returns*
`isxdigit' returns non-zero if C is a hexadecimal digit (`0'-`9',
`a'-`f', or `A'-`F').

*Portability*
`isxdigit' is ANSI C.

   No supporting OS subroutines are required.

3.12 `toascii'--force integers to ASCII range
=============================================

*Synopsis*
     #include <ctype.h>
     int toascii(int C);
   *Description*
`toascii' is a macro which coerces integers to the ASCII range (0-127)
by zeroing any higher-order bits.

   You can use a compiled subroutine instead of the macro definition by
undefining this macro using ``#undef toascii''.

*Returns*
`toascii' returns integers between 0 and 127.

*Portability*
`toascii' is not ANSI C.

   No supporting OS subroutines are required.

3.13 `tolower'--translate characters to lowercase
=================================================

*Synopsis*
     #include <ctype.h>
     int tolower(int C);
     int _tolower(int C);
   *Description*
`tolower' is a macro which converts uppercase characters to lowercase,
leaving all other characters unchanged.  It is only defined when C is
an integer in the range `EOF' to `255'.

   You can use a compiled subroutine instead of the macro definition by
undefining this macro using ``#undef tolower''.

   `_tolower' performs the same conversion as `tolower', but should
only be used when C is known to be an uppercase character (`A'-`Z').

*Returns*
`tolower' returns the lowercase equivalent of C when it is a character
between `A' and `Z', and C otherwise.

   `_tolower' returns the lowercase equivalent of C when it is a
character between `A' and `Z'.  If C is not one of these characters,
the behaviour of `_tolower' is undefined.

*Portability*
`tolower' is ANSI C.  `_tolower' is not recommended for portable
programs.

   No supporting OS subroutines are required.

3.14 `toupper'--translate characters to uppercase
=================================================

*Synopsis*
     #include <ctype.h>
     int toupper(int C);
     int _toupper(int C);
   *Description*
`toupper' is a macro which converts lowercase characters to uppercase,
leaving all other characters unchanged.  It is only defined when C is
an integer in the range `EOF' to `255'.

   You can use a compiled subroutine instead of the macro definition by
undefining this macro using ``#undef toupper''.

   `_toupper' performs the same conversion as `toupper', but should
only be used when C is known to be a lowercase character (`a'-`z').

*Returns*
`toupper' returns the uppercase equivalent of C when it is a character
between `a' and `z', and C otherwise.

   `_toupper' returns the uppercase equivalent of C when it is a
character between `a' and `z'.  If C is not one of these characters,
the behaviour of `_toupper' is undefined.

*Portability*
`toupper' is ANSI C.  `_toupper' is not recommended for portable
programs.

   No supporting OS subroutines are required.

3.15 `iswalnum'--alphanumeric wide character test
=================================================

*Synopsis*
     #include <wctype.h>
     int iswalnum(wint_t C);
   *Description*
`iswalnum' is a function which classifies wide-character values that
are alphanumeric.

*Returns*
`iswalnum' returns non-zero if C is a alphanumeric wide character.

*Portability*
`iswalnum' is C99.

   No supporting OS subroutines are required.

3.16 `iswalpha'--alphabetic wide character test
===============================================

*Synopsis*
     #include <wctype.h>
     int iswalpha(wint_t C);
   *Description*
`iswalpha' is a function which classifies wide-character values that
are alphabetic.

*Returns*
`iswalpha' returns non-zero if C is an alphabetic wide character.

*Portability*
`iswalpha' is C99.

   No supporting OS subroutines are required.

3.17 `iswcntrl'--control wide character test
============================================

*Synopsis*
     #include <wctype.h>
     int iswcntrl(wint_t C);
   *Description*
`iswcntrl' is a function which classifies wide-character values that
are categorized as control characters.

*Returns*
`iswcntrl' returns non-zero if C is a control wide character.

*Portability*
`iswcntrl' is C99.

   No supporting OS subroutines are required.

3.18 `iswblank'--blank wide character test
==========================================

*Synopsis*
     #include <wctype.h>
     int iswblank(wint_t C);
   *Description*
`iswblank' is a function which classifies wide-character values that
are categorized as blank.

*Returns*
`iswblank' returns non-zero if C is a blank wide character.

*Portability*
`iswblank' is C99.

   No supporting OS subroutines are required.

3.19 `iswdigit'--decimal digit wide character test
==================================================

*Synopsis*
     #include <wctype.h>
     int iswdigit(wint_t C);
   *Description*
`iswdigit' is a function which classifies wide-character values that
are decimal digits.

*Returns*
`iswdigit' returns non-zero if C is a decimal digit wide character.

*Portability*
`iswdigit' is C99.

   No supporting OS subroutines are required.

3.20 `iswgraph'--graphic wide character test
============================================

*Synopsis*
     #include <wctype.h>
     int iswgraph(wint_t C);
   *Description*
`iswgraph' is a function which classifies wide-character values that
are graphic.

*Returns*
`iswgraph' returns non-zero if C is a graphic wide character.

*Portability*
`iswgraph' is C99.

   No supporting OS subroutines are required.

3.21 `iswlower'--lowercase wide character test
==============================================

*Synopsis*
     #include <wctype.h>
     int iswlower(wint_t C);
   *Description*
`iswlower' is a function which classifies wide-character values that
have uppercase translations.

*Returns*
`iswlower' returns non-zero if C is a lowercase wide character.

*Portability*
`iswlower' is C99.

   No supporting OS subroutines are required.

3.22 `iswprint'--printable wide character test
==============================================

*Synopsis*
     #include <wctype.h>
     int iswprint(wint_t C);
   *Description*
`iswprint' is a function which classifies wide-character values that
are printable.

*Returns*
`iswprint' returns non-zero if C is a printable wide character.

*Portability*
`iswprint' is C99.

   No supporting OS subroutines are required.

3.23 `iswpunct'--punctuation wide character test
================================================

*Synopsis*
     #include <wctype.h>
     int iswpunct(wint_t C);
   *Description*
`iswpunct' is a function which classifies wide-character values that
are punctuation.

*Returns*
`iswpunct' returns non-zero if C is a punctuation wide character.

*Portability*
`iswpunct' is C99.

   No supporting OS subroutines are required.

3.24 `iswspace'--whitespace wide character test
===============================================

*Synopsis*
     #include <wctype.h>
     int iswspace(wint_t C);
   *Description*
`iswspace' is a function which classifies wide-character values that
are categorized as whitespace.

*Returns*
`iswspace' returns non-zero if C is a whitespace wide character.

*Portability*
`iswspace' is C99.

   No supporting OS subroutines are required.

3.25 `iswupper'--uppercase wide character test
==============================================

*Synopsis*
     #include <wctype.h>
     int iswupper(wint_t C);
   *Description*
`iswupper' is a function which classifies wide-character values that
have uppercase translations.

*Returns*
`iswupper' returns non-zero if C is a uppercase wide character.

*Portability*
`iswupper' is C99.

   No supporting OS subroutines are required.

3.26 `iswxdigit'--hexadecimal digit wide character test
=======================================================

*Synopsis*
     #include <wctype.h>
     int iswxdigit(wint_t C);
   *Description*
`iswxdigit' is a function which classifies wide character values that
are hexadecimal digits.

*Returns*
`iswxdigit' returns non-zero if C is a hexadecimal digit wide character.

*Portability*
`iswxdigit' is C99.

   No supporting OS subroutines are required.

3.27 `iswctype'--extensible wide-character test
===============================================

*Synopsis*
     #include <wctype.h>
     int iswctype(wint_t C, wctype_t DESC);
   *Description*
`iswctype' is a function which classifies wide-character values using
the wide-character test specified by DESC.

*Returns*
`iswctype' returns non-zero if and only if C matches the test specified
by DESC.  If DESC is unknown, zero is returned.

*Portability*
`iswctype' is C99.

   No supporting OS subroutines are required.

3.28 `wctype'--get wide-character classification type
=====================================================

*Synopsis*
     #include <wctype.h>
     wctype_t wctype(const char *C);
   *Description*
`wctype' is a function which takes a string C and gives back the
appropriate wctype_t type value associated with the string, if one
exists.  The following values are guaranteed to be recognized: "alnum",
"alpha", "blank", "cntrl", "digit", "graph", "lower", "print", "punct",
"space", "upper", and "xdigit".

*Returns*
`wctype' returns 0 and sets `errno' to `EINVAL' if the given name is
invalid.  Otherwise, it returns a valid non-zero wctype_t value.

*Portability*
`wctype' is C99.

   No supporting OS subroutines are required.

3.29 `towlower'--translate wide characters to lowercase
=======================================================

*Synopsis*
     #include <wctype.h>
     wint_t towlower(wint_t C);
   *Description*
`towlower' is a function which converts uppercase wide characters to
lowercase, leaving all other characters unchanged.

*Returns*
`towlower' returns the lowercase equivalent of C when it is a uppercase
wide character; otherwise, it returns the input character.

*Portability*
`towlower' is C99.

   No supporting OS subroutines are required.

3.30 `towupper'--translate wide characters to uppercase
=======================================================

*Synopsis*
     #include <wctype.h>
     wint_t towupper(wint_t C);
   *Description*
`towupper' is a function which converts lowercase wide characters to
uppercase, leaving all other characters unchanged.

*Returns*
`towupper' returns the uppercase equivalent of C when it is a lowercase
wide character, otherwise, it returns the input character.

*Portability*
`towupper' is C99.

   No supporting OS subroutines are required.

3.31 `towctrans'--extensible wide-character translation
=======================================================

*Synopsis*
     #include <wctype.h>
     wint_t towctrans(wint_t C, wctrans_t W);
   *Description*
`towctrans' is a function which converts wide characters based on a
specified translation type W.  If the translation type is invalid or
cannot be applied to the current character, no change to the character
is made.

*Returns*
`towctrans' returns the translated equivalent of C when it is a valid
for the given translation, otherwise, it returns the input character.
When the translation type is invalid, `errno' is set `EINVAL'.

*Portability*
`towctrans' is C99.

   No supporting OS subroutines are required.

3.32 `wctrans'--get wide-character translation type
===================================================

*Synopsis*
     #include <wctype.h>
     wctrans_t wctrans(const char *C);
   *Description*
`wctrans' is a function which takes a string C and gives back the
appropriate wctrans_t type value associated with the string, if one
exists.  The following values are guaranteed to be recognized:
"tolower" and "toupper".

*Returns*
`wctrans' returns 0 and sets `errno' to `EINVAL' if the given name is
invalid.  Otherwise, it returns a valid non-zero wctrans_t value.

*Portability*
`wctrans' is C99.

   No supporting OS subroutines are required.

4 Input and Output (`stdio.h')
******************************

This chapter comprises functions to manage files or other input/output
streams. Among these functions are subroutines to generate or scan
strings according to specifications from a format string.

   The underlying facilities for input and output depend on the host
system, but these functions provide a uniform interface.

   The corresponding declarations are in `stdio.h'.

   The reentrant versions of these functions use macros

     _stdin_r(REENT)
     _stdout_r(REENT)
     _stderr_r(REENT)

instead of the globals `stdin', `stdout', and `stderr'.  The argument
<[reent]> is a pointer to a reentrancy structure.

4.1 `clearerr'--clear file or stream error indicator
====================================================

*Synopsis*
     #include <stdio.h>
     void clearerr(FILE *FP);
   *Description*
The `stdio' functions maintain an error indicator with each file
pointer FP, to record whether any read or write errors have occurred on
the associated file or stream.  Similarly, it maintains an end-of-file
indicator to record whether there is no more data in the file.

   Use `clearerr' to reset both of these indicators.

   See `ferror' and `feof' to query the two indicators.

*Returns*
`clearerr' does not return a result.

*Portability*
ANSI C requires `clearerr'.

   No supporting OS subroutines are required.

4.2 `diprintf', `vdiprintf'--print to a file descriptor (integer only)
======================================================================

*Synopsis*
     #include <stdio.h>
     #include <stdarg.h>
     int diprintf(int FD, const char *FORMAT, ...);
     int vdiprintf(int FD, const char *FORMAT, va_list AP);
     int _diprintf_r(struct _reent *PTR, int FD,
         const char *FORMAT, ...);
     int _vdiprintf_r(struct _reent *PTR, int FD,
         const char *FORMAT, va_list AP);
   *Description*
`diprintf' and `vdiprintf' are similar to `dprintf' and `vdprintf',
except that only integer format specifiers are processed.

   The functions `_diprintf_r' and `_vdiprintf_r' are simply reentrant
versions of the functions above.

*Returns*
Similar to `dprintf' and `vdprintf'.

*Portability*
This set of functions is an integer-only extension, and is not portable.

   Supporting OS subroutines required: `sbrk', `write'.

4.3 `dprintf', `vdprintf'--print to a file descriptor
=====================================================

*Synopsis*
     #include <stdio.h>
     #include <stdarg.h>
     int dprintf(int FD, const char *FORMAT, ...);
     int vdprintf(int FD, const char *FORMAT, va_list AP);
     int _dprintf_r(struct _reent *PTR, int FD,
         const char *FORMAT, ...);
     int _vdprintf_r(struct _reent *PTR, int FD,
         const char *FORMAT, va_list AP);
   *Description*
`dprintf' and `vdprintf' allow printing a format, similarly to
`printf', but write to a file descriptor instead of to a `FILE' stream.

   The functions `_dprintf_r' and `_vdprintf_r' are simply reentrant
versions of the functions above.

*Returns*
The return value and errors are exactly as for `write', except that
`errno' may also be set to `ENOMEM' if the heap is exhausted.

*Portability*
This function is originally a GNU extension in glibc and is not
portable.

   Supporting OS subroutines required: `sbrk', `write'.

4.4 `fclose'--close a file
==========================

*Synopsis*
     #include <stdio.h>
     int fclose(FILE *FP);
     int _fclose_r(struct _reent *REENT, FILE *FP);
   *Description*
If the file or stream identified by FP is open, `fclose' closes it,
after first ensuring that any pending data is written (by calling
`fflush(FP)').

   The alternate function `_fclose_r' is a reentrant version.  The
extra argument REENT is a pointer to a reentrancy structure.

*Returns*
`fclose' returns `0' if successful (including when FP is `NULL' or not
an open file); otherwise, it returns `EOF'.

*Portability*
`fclose' is required by ANSI C.

   Required OS subroutines: `close', `fstat', `isatty', `lseek',
`read', `sbrk', `write'.

4.5 `fcloseall'--close all files
================================

*Synopsis*
     #include <stdio.h>
     int fcloseall(void);
     int _fcloseall_r (struct _reent *PTR);
   *Description*
`fcloseall' closes all files in the current reentrancy struct's domain.
The function `_fcloseall_r' is the same function, except the reentrancy
struct is passed in as the PTR argument.

   This function is not recommended as it closes all streams, including
the std streams.

*Returns*
`fclose' returns `0' if all closes are successful.  Otherwise, EOF is
returned.

*Portability*
`fcloseall' is a glibc extension.

   Required OS subroutines: `close', `fstat', `isatty', `lseek',
`read', `sbrk', `write'.

4.6 `fdopen'--turn open file into a stream
==========================================

*Synopsis*
     #include <stdio.h>
     FILE *fdopen(int FD, const char *MODE);
     FILE *_fdopen_r(struct _reent *REENT,
         int FD, const char *MODE);
   *Description*
`fdopen' produces a file descriptor of type `FILE *', from a descriptor
for an already-open file (returned, for example, by the system
subroutine `open' rather than by `fopen').  The MODE argument has the
same meanings as in `fopen'.

*Returns*
File pointer or `NULL', as for `fopen'.

*Portability*
`fdopen' is ANSI.

4.7 `feof'--test for end of file
================================

*Synopsis*
     #include <stdio.h>
     int feof(FILE *FP);
   *Description*
`feof' tests whether or not the end of the file identified by FP has
been reached.

*Returns*
`feof' returns `0' if the end of file has not yet been reached; if at
end of file, the result is nonzero.

*Portability*
`feof' is required by ANSI C.

   No supporting OS subroutines are required.

4.8 `ferror'--test whether read/write error has occurred
========================================================

*Synopsis*
     #include <stdio.h>
     int ferror(FILE *FP);
   *Description*
The `stdio' functions maintain an error indicator with each file
pointer FP, to record whether any read or write errors have occurred on
the associated file or stream.  Use `ferror' to query this indicator.

   See `clearerr' to reset the error indicator.

*Returns*
`ferror' returns `0' if no errors have occurred; it returns a nonzero
value otherwise.

*Portability*
ANSI C requires `ferror'.

   No supporting OS subroutines are required.

4.9 `fflush'--flush buffered file output
========================================

*Synopsis*
     #include <stdio.h>
     int fflush(FILE *FP);

     int _fflush_r(struct _reent *REENT, FILE *FP);
   *Description*
The `stdio' output functions can buffer output before delivering it to
the host system, in order to minimize the overhead of system calls.

   Use `fflush' to deliver any such pending output (for the file or
stream identified by FP) to the host system.

   If FP is `NULL', `fflush' delivers pending output from all open
files.

   Additionally, if FP is a seekable input stream visiting a file
descriptor, set the position of the file descriptor to match next
unread byte, useful for obeying POSIX semantics when ending a process
without consuming all input from the stream.

   The alternate function `_fflush_r' is a reentrant version, where the
extra argument REENT is a pointer to a reentrancy structure, and FP
must not be NULL.

*Returns*
`fflush' returns `0' unless it encounters a write error; in that
situation, it returns `EOF'.

*Portability*
ANSI C requires `fflush'.  The behavior on input streams is only
specified by POSIX, and not all implementations follow POSIX rules.

   No supporting OS subroutines are required.

4.10 `fgetc'--get a character from a file or stream
===================================================

*Synopsis*
     #include <stdio.h>
     int fgetc(FILE *FP);

     #include <stdio.h>
     int _fgetc_r(struct _reent *PTR, FILE *FP);
   *Description*
Use `fgetc' to get the next single character from the file or stream
identified by FP.  As a side effect, `fgetc' advances the file's
current position indicator.

   For a macro version of this function, see `getc'.

   The function `_fgetc_r' is simply a reentrant version of `fgetc'
that is passed the additional reentrant structure pointer argument: PTR.

*Returns*
The next character (read as an `unsigned char', and cast to `int'),
unless there is no more data, or the host system reports a read error;
in either of these situations, `fgetc' returns `EOF'.

   You can distinguish the two situations that cause an `EOF' result by
using the `ferror' and `feof' functions.

*Portability*
ANSI C requires `fgetc'.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.

4.11 `fgetpos'--record position in a stream or file
===================================================

*Synopsis*
     #include <stdio.h>
     int fgetpos(FILE *FP, fpos_t *POS);
     int _fgetpos_r(struct _reent *PTR, FILE *FP, fpos_t *POS);
   *Description*
Objects of type `FILE' can have a "position" that records how much of
the file your program has already read.  Many of the `stdio' functions
depend on this position, and many change it as a side effect.

   You can use `fgetpos' to report on the current position for a file
identified by FP; `fgetpos' will write a value representing that
position at `*POS'.  Later, you can use this value with `fsetpos' to
return the file to this position.

   In the current implementation, `fgetpos' simply uses a character
count to represent the file position; this is the same number that
would be returned by `ftell'.

*Returns*
`fgetpos' returns `0' when successful.  If `fgetpos' fails, the result
is `1'.  Failure occurs on streams that do not support positioning; the
global `errno' indicates this condition with the value `ESPIPE'.

*Portability*
`fgetpos' is required by the ANSI C standard, but the meaning of the
value it records is not specified beyond requiring that it be
acceptable as an argument to `fsetpos'.  In particular, other
conforming C implementations may return a different result from `ftell'
than what `fgetpos' writes at `*POS'.

   No supporting OS subroutines are required.

4.12 `fgets'--get character string from a file or stream
========================================================

*Synopsis*
     #include <stdio.h>
     char *fgets(char *BUF, int N, FILE *FP);

     #include <stdio.h>
     char *_fgets_r(struct _reent *PTR, char *BUF, int N, FILE *FP);
   *Description*
Reads at most N-1 characters from FP until a newline is found. The
characters including to the newline are stored in BUF. The buffer is
terminated with a 0.

   The `_fgets_r' function is simply the reentrant version of `fgets'
and is passed an additional reentrancy structure pointer: PTR.

*Returns*
`fgets' returns the buffer passed to it, with the data filled in. If
end of file occurs with some data already accumulated, the data is
returned with no other indication. If no data are read, NULL is
returned instead.

*Portability*
`fgets' should replace all uses of `gets'. Note however that `fgets'
returns all of the data, while `gets' removes the trailing newline
(with no indication that it has done so.)

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.

4.13 `fgetwc', `getwc'--get a wide character from a file or stream
==================================================================

*Synopsis*
     #include <stdio.h>
     #include <wchar.h>
     wint_t fgetwc(FILE *FP);

     #include <stdio.h>
     #include <wchar.h>
     wint_t _fgetwc_r(struct _reent *PTR, FILE *FP);

     #include <stdio.h>
     #include <wchar.h>
     wint_t getwc(FILE *FP);

     #include <stdio.h>
     #include <wchar.h>
     wint_t _getwc_r(struct _reent *PTR, FILE *FP);
   *Description*
Use `fgetwc' to get the next wide character from the file or stream
identified by FP.  As a side effect, `fgetwc' advances the file's
current position indicator.

   The  `getwc'  function  or macro functions identically to `fgetwc'.
It may be implemented as a macro, and may evaluate its argument more
than once. There is no reason ever to use it.

   `_fgetwc_r' and `_getwc_r' are simply reentrant versions of `fgetwc'
and `getwc' that are passed the additional reentrant structure pointer
argument: PTR.

*Returns*
The next wide character cast to `wint_t'), unless there is no more data,
or the host system reports a read error; in either of these situations,
`fgetwc' and `getwc' return `WEOF'.

   You can distinguish the two situations that cause an `EOF' result by
using the `ferror' and `feof' functions.

*Portability*
C99, POSIX.1-2001

4.14 `fgetws'--get wide character string from a file or stream
==============================================================

*Synopsis*
     #include <wchar.h>
     wchar_t *fgetws(wchar_t *WS, int N, FILE *FP);

     #include <wchar.h>
     wchar_t *_fgetws_r(struct _reent *PTR, wchar_t *WS, int N, FILE *FP);
   *Description*
Reads at most N-1 wide characters from FP until a newline is found. The
wide characters including to the newline are stored in WS. The buffer
is terminated with a 0.

   The `_fgetws_r' function is simply the reentrant version of `fgetws'
and is passed an additional reentrancy structure pointer: PTR.

*Returns*
`fgetws' returns the buffer passed to it, with the data filled in. If
end of file occurs with some data already accumulated, the data is
returned with no other indication. If no data are read, NULL is
returned instead.

*Portability*
C99, POSIX.1-2001

4.15 `fileno'--return file descriptor associated with stream
============================================================

*Synopsis*
     #include <stdio.h>
     int fileno(FILE *FP);
   *Description*
You can use `fileno' to return the file descriptor identified by FP.

*Returns*
`fileno' returns a non-negative integer when successful.  If FP is not
an open stream, `fileno' returns -1.

*Portability*
`fileno' is not part of ANSI C.  POSIX requires `fileno'.

   Supporting OS subroutines required: none.

4.16 `fmemopen'--open a stream around a fixed-length string
===========================================================

*Synopsis*
     #include <stdio.h>
     FILE *fmemopen(void *restrict BUF, size_t SIZE,
         const char *restrict MODE);
   *Description*
`fmemopen' creates a seekable `FILE' stream that wraps a fixed-length
buffer of SIZE bytes starting at BUF.  The stream is opened with MODE
treated as in `fopen', where append mode starts writing at the first
NUL byte.  If BUF is NULL, then SIZE bytes are automatically provided
as if by `malloc', with the initial size of 0, and MODE must contain
`+' so that data can be read after it is written.

   The stream maintains a current position, which moves according to
bytes read or written, and which can be one past the end of the array.
The stream also maintains a current file size, which is never greater
than SIZE.  If MODE starts with `r', the position starts at `0', and
file size starts at SIZE if BUF was provided.  If MODE starts with `w',
the position and file size start at `0', and if BUF was provided, the
first byte is set to NUL.  If MODE starts with `a', the position and
file size start at the location of the first NUL byte, or else SIZE if
BUF was provided.

   When reading, NUL bytes have no significance, and reads cannot exceed
the current file size.  When writing, the file size can increase up to
SIZE as needed, and NUL bytes may be embedded in the stream (see
`open_memstream' for an alternative that automatically enlarges the
buffer).  When the stream is flushed or closed after a write that
changed the file size, a NUL byte is written at the current position if
there is still room; if the stream is not also open for reading, a NUL
byte is additionally written at the last byte of BUF when the stream
has exceeded SIZE, so that a write-only BUF is always NUL-terminated
when the stream is flushed or closed (and the initial SIZE should take
this into account).  It is not possible to seek outside the bounds of
SIZE.  A NUL byte written during a flush is restored to its previous
value when seeking elsewhere in the string.

*Returns*
The return value is an open FILE pointer on success.  On error, `NULL'
is returned, and `errno' will be set to EINVAL if SIZE is zero or MODE
is invalid, ENOMEM if BUF was NULL and memory could not be allocated,
or EMFILE if too many streams are already open.

*Portability*
This function is being added to POSIX 200x, but is not in POSIX 2001.

   Supporting OS subroutines required: `sbrk'.

4.17 `fopen'--open a file
=========================

*Synopsis*
     #include <stdio.h>
     FILE *fopen(const char *FILE, const char *MODE);

     FILE *_fopen_r(struct _reent *REENT,
         const char *FILE, const char *MODE);
   *Description*
`fopen' initializes the data structures needed to read or write a file.
Specify the file's name as the string at FILE, and the kind of access
you need to the file with the string at MODE.

   The alternate function `_fopen_r' is a reentrant version.  The extra
argument REENT is a pointer to a reentrancy structure.

   Three fundamental kinds of access are available: read, write, and
append.  `*MODE' must begin with one of the three characters ``r'',
``w'', or ``a'', to select one of these:

`r'
     Open the file for reading; the operation will fail if the file does
     not exist, or if the host system does not permit you to read it.

`w'
     Open the file for writing _from the beginning_ of the file:
     effectively, this always creates a new file.  If the file whose
     name you specified already existed, its old contents are discarded.

`a'
     Open the file for appending data, that is writing from the end of
     file.  When you open a file this way, all data always goes to the
     current end of file; you cannot change this using `fseek'.

   Some host systems distinguish between "binary" and "text" files.
Such systems may perform data transformations on data written to, or
read from, files opened as "text".  If your system is one of these,
then you can append a ``b'' to any of the three modes above, to specify
that you are opening the file as a binary file (the default is to open
the file as a text file).

   ``rb'', then, means "read binary"; ``wb'', "write binary"; and
``ab'', "append binary".

   To make C programs more portable, the ``b'' is accepted on all
systems, whether or not it makes a difference.

   Finally, you might need to both read and write from the same file.
You can also append a ``+'' to any of the three modes, to permit this.
(If you want to append both ``b'' and ``+'', you can do it in either
order: for example, `"rb+"' means the same thing as `"r+b"' when used
as a mode string.)

   Use `"r+"' (or `"rb+"') to permit reading and writing anywhere in an
existing file, without discarding any data; `"w+"' (or `"wb+"') to
create a new file (or begin by discarding all data from an old one)
that permits reading and writing anywhere in it; and `"a+"' (or
`"ab+"') to permit reading anywhere in an existing file, but writing
only at the end.

*Returns*
`fopen' returns a file pointer which you can use for other file
operations, unless the file you requested could not be opened; in that
situation, the result is `NULL'.  If the reason for failure was an
invalid string at MODE, `errno' is set to `EINVAL'.

*Portability*
`fopen' is required by ANSI C.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `open', `read', `sbrk', `write'.

4.18 `fopencookie'--open a stream with custom callbacks
=======================================================

*Synopsis*
     #include <stdio.h>
     FILE *fopencookie(const void *COOKIE, const char *MODE,
         cookie_io_functions_t FUNCTIONS);
   *Description*
`fopencookie' creates a `FILE' stream where I/O is performed using
custom callbacks.  The callbacks are registered via the structure:

   typedef ssize_t (*cookie_read_function_t)(void *_cookie, char *_buf,
size_t _n); typedef ssize_t (*cookie_write_function_t)(void *_cookie,
const char *_buf, size_t _n); typedef int
(*cookie_seek_function_t)(void *_cookie, off_t *_off, int _whence);
typedef int (*cookie_close_function_t)(void *_cookie);

     	typedef struct
     	{
     		cookie_read_function_t	*read;
     		cookie_write_function_t *write;
     		cookie_seek_function_t	*seek;
     		cookie_close_function_t *close;
     	} cookie_io_functions_t;

   The stream is opened with MODE treated as in `fopen'.  The callbacks
FUNCTIONS.READ and FUNCTIONS.WRITE may only be NULL when MODE does not
require them.

   FUNCTIONS.READ should return -1 on failure, or else the number of
bytes read (0 on EOF).  It is similar to `read', except that COOKIE
will be passed as the first argument.

   FUNCTIONS.WRITE should return -1 on failure, or else the number of
bytes written.  It is similar to `write', except that COOKIE will be
passed as the first argument.

   FUNCTIONS.SEEK should return -1 on failure, and 0 on success, with
_OFF set to the current file position.  It is a cross between `lseek'
and `fseek', with the _WHENCE argument interpreted in the same manner.
A NULL FUNCTIONS.SEEK makes the stream behave similarly to a pipe in
relation to stdio functions that require positioning.

   FUNCTIONS.CLOSE should return -1 on failure, or 0 on success.  It is
similar to `close', except that COOKIE will be passed as the first
argument.  A NULL FUNCTIONS.CLOSE merely flushes all data then lets
`fclose' succeed.  A failed close will still invalidate the stream.

   Read and write I/O functions are allowed to change the underlying
buffer on fully buffered or line buffered streams by calling `setvbuf'.
They are also not required to completely fill or empty the buffer.
They are not, however, allowed to change streams from unbuffered to
buffered or to change the state of the line buffering flag.  They must
also be prepared to have read or write calls occur on buffers other
than the one most recently specified.

*Returns*
The return value is an open FILE pointer on success.  On error, `NULL'
is returned, and `errno' will be set to EINVAL if a function pointer is
missing or MODE is invalid, ENOMEM if the stream cannot be created, or
EMFILE if too many streams are already open.

*Portability*
This function is a newlib extension, copying the prototype from Linux.
It is not portable.  See also the `funopen' interface from BSD.

   Supporting OS subroutines required: `sbrk'.

4.19 `fpurge'--discard pending file I/O
=======================================

*Synopsis*
     #include <stdio.h>
     int fpurge(FILE *FP);

     int _fpurge_r(struct _reent *REENT, FILE *FP);
   *Description*
Use `fpurge' to clear all buffers of the given stream.  For output
streams, this discards data not yet written to disk.  For input streams,
this discards any data from `ungetc' and any data retrieved from disk
but not yet read via `getc'.  This is more severe than `fflush', and
generally is only needed when manually altering the underlying file
descriptor of a stream.

   The alternate function `_fpurge_r' is a reentrant version, where the
extra argument REENT is a pointer to a reentrancy structure, and FP
must not be NULL.

*Returns*
`fpurge' returns `0' unless FP is not valid, in which case it returns
`EOF' and sets `errno'.

*Portability*
These functions are not portable to any standard.

   No supporting OS subroutines are required.

4.20 `fputc'--write a character on a stream or file
===================================================

*Synopsis*
     #include <stdio.h>
     int fputc(int CH, FILE *FP);

     #include <stdio.h>
     int _fputc_r(struct _rent *PTR, int CH, FILE *FP);
   *Description*
`fputc' converts the argument CH from an `int' to an `unsigned char',
then writes it to the file or stream identified by FP.

   If the file was opened with append mode (or if the stream cannot
support positioning), then the new character goes at the end of the
file or stream.  Otherwise, the new character is written at the current
value of the position indicator, and the position indicator oadvances
by one.

   For a macro version of this function, see `putc'.

   The `_fputc_r' function is simply a reentrant version of `fputc'
that takes an additional reentrant structure argument: PTR.

*Returns*
If successful, `fputc' returns its argument CH.  If an error
intervenes, the result is `EOF'.  You can use ``ferror(FP)'' to query
for errors.

*Portability*
`fputc' is required by ANSI C.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.

4.21 `fputs'--write a character string in a file or stream
==========================================================

*Synopsis*
     #include <stdio.h>
     int fputs(const char *S, FILE *FP);

     #include <stdio.h>
     int _fputs_r(struct _reent *PTR, const char *S, FILE *FP);
   *Description*
`fputs' writes the string at S (but without the trailing null) to the
file or stream identified by FP.

   `_fputs_r' is simply the reentrant version of `fputs' that takes an
additional reentrant struct pointer argument: PTR.

*Returns*
If successful, the result is `0'; otherwise, the result is `EOF'.

*Portability*
ANSI C requires `fputs', but does not specify that the result on
success must be `0'; any non-negative value is permitted.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.

4.22 `fputwc', `putwc'--write a wide character on a stream or file
==================================================================

*Synopsis*
     #include <stdio.h>
     #include <wchar.h>
     wint_t fputwc(wchar_t WC, FILE *FP);

     #include <stdio.h>
     #include <wchar.h>
     wint_t _fputwc_r(struct _reent *PTR, wchar_t WC, FILE *FP);

     #include <stdio.h>
     #include <wchar.h>
     wint_t putwc(wchar_t WC, FILE *FP);

     #include <stdio.h>
     #include <wchar.h>
     wint_t _putwc_r(struct _reent *PTR, wchar_t WC, FILE *FP);
   *Description*
`fputwc' writes the wide character argument WC to the file or stream
identified by FP.

   If the file was opened with append mode (or if the stream cannot
support positioning), then the new wide character goes at the end of the
file or stream.  Otherwise, the new wide character is written at the
current value of the position indicator, and the position indicator
oadvances by one.

   The `putwc' function or macro functions identically to `fputwc'.  It
may be implemented as a macro, and may evaluate its argument more than
once. There is no reason ever to use it.

   The `_fputwc_r' and `_putwc_r' functions are simply reentrant
versions of `fputwc' and `putwc' that take an additional reentrant
structure argument: PTR.

*Returns*
If successful, `fputwc' and `putwc' return their argument WC.  If an
error intervenes, the result is `EOF'.  You can use ``ferror(FP)'' to
query for errors.

*Portability*
C99, POSIX.1-2001

4.23 `fputws'--write a wide character string in a file or stream
================================================================

*Synopsis*
     #include <wchar.h>
     int fputws(const wchar_t *WS, FILE *FP);

     #include <wchar.h>
     int _fputws_r(struct _reent *PTR, const wchar_t *WS, FILE *FP);
   *Description*
`fputws' writes the wide character string at WS (but without the
trailing null) to the file or stream identified by FP.

   `_fputws_r' is simply the reentrant version of `fputws' that takes
an additional reentrant struct pointer argument: PTR.

*Returns*
If successful, the result is a non-negative integer; otherwise, the
result is `-1' to indicate an error.

*Portability*
C99, POSIX.1-2001

4.24 `fread'--read array elements from a file
=============================================

*Synopsis*
     #include <stdio.h>
     size_t fread(void *BUF, size_t SIZE, size_t COUNT,
         FILE *FP);

     #include <stdio.h>
     size_t _fread_r(struct _reent *PTR, void *BUF,
         size_t SIZE, size_t COUNT, FILE *FP);
   *Description*
`fread' attempts to copy, from the file or stream identified by FP,
COUNT elements (each of size SIZE) into memory, starting at BUF.
`fread' may copy fewer elements than COUNT if an error, or end of file,
intervenes.

   `fread' also advances the file position indicator (if any) for FP by
the number of _characters_ actually read.

   `_fread_r' is simply the reentrant version of `fread' that takes an
additional reentrant structure pointer argument: PTR.

*Returns*
The result of `fread' is the number of elements it succeeded in reading.

*Portability*
ANSI C requires `fread'.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.

4.25 `freopen'--open a file using an existing file descriptor
=============================================================

*Synopsis*
     #include <stdio.h>
     FILE *freopen(const char *FILE, const char *MODE,
         FILE *FP);
     FILE *_freopen_r(struct _reent *PTR, const char *FILE,
         const char *MODE, FILE *FP);
   *Description*
Use this variant of `fopen' if you wish to specify a particular file
descriptor FP (notably `stdin', `stdout', or `stderr') for the file.

   If FP was associated with another file or stream, `freopen' closes
that other file or stream (but ignores any errors while closing it).

   FILE and MODE are used just as in `fopen'.

   If FILE is `NULL', the underlying stream is modified rather than
closed.  The file cannot be given a more permissive access mode (for
example, a MODE of "w" will fail on a read-only file descriptor), but
can change status such as append or binary mode.  If modification is
not possible, failure occurs.

*Returns*
If successful, the result is the same as the argument FP.  If the file
cannot be opened as specified, the result is `NULL'.

*Portability*
ANSI C requires `freopen'.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `open', `read', `sbrk', `write'.

4.26 `fseek', `fseeko'--set file position
=========================================

*Synopsis*
     #include <stdio.h>
     int fseek(FILE *FP, long OFFSET, int WHENCE)
     int fseeko(FILE *FP, off_t OFFSET, int WHENCE)
     int _fseek_r(struct _reent *PTR, FILE *FP,
         long OFFSET, int WHENCE)
     int _fseeko_r(struct _reent *PTR, FILE *FP,
         off_t OFFSET, int WHENCE)
   *Description*
Objects of type `FILE' can have a "position" that records how much of
the file your program has already read.  Many of the `stdio' functions
depend on this position, and many change it as a side effect.

   You can use `fseek'/`fseeko' to set the position for the file
identified by FP.  The value of OFFSET determines the new position, in
one of three ways selected by the value of WHENCE (defined as macros in
``stdio.h''):

   `SEEK_SET'--OFFSET is the absolute file position (an offset from the
beginning of the file) desired.  OFFSET must be positive.

   `SEEK_CUR'--OFFSET is relative to the current file position.  OFFSET
can meaningfully be either positive or negative.

   `SEEK_END'--OFFSET is relative to the current end of file.  OFFSET
can meaningfully be either positive (to increase the size of the file)
or negative.

   See `ftell'/`ftello' to determine the current file position.

*Returns*
`fseek'/`fseeko' return `0' when successful.  On failure, the result is
`EOF'.  The reason for failure is indicated in `errno': either `ESPIPE'
(the stream identified by FP doesn't support repositioning) or `EINVAL'
(invalid file position).

*Portability*
ANSI C requires `fseek'.

   `fseeko' is defined by the Single Unix specification.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.

4.27 `fsetpos'--restore position of a stream or file
====================================================

*Synopsis*
     #include <stdio.h>
     int fsetpos(FILE *FP, const fpos_t *POS);
     int _fsetpos_r(struct _reent *PTR, FILE *FP,
         const fpos_t *POS);
   *Description*
Objects of type `FILE' can have a "position" that records how much of
the file your program has already read.  Many of the `stdio' functions
depend on this position, and many change it as a side effect.

   You can use `fsetpos' to return the file identified by FP to a
previous position `*POS' (after first recording it with `fgetpos').

   See `fseek' for a similar facility.

*Returns*
`fgetpos' returns `0' when successful.  If `fgetpos' fails, the result
is `1'.  The reason for failure is indicated in `errno': either
`ESPIPE' (the stream identified by FP doesn't support repositioning) or
`EINVAL' (invalid file position).

*Portability*
ANSI C requires `fsetpos', but does not specify the nature of `*POS'
beyond identifying it as written by `fgetpos'.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.

4.28 `ftell', `ftello'--return position in a stream or file
===========================================================

*Synopsis*
     #include <stdio.h>
     long ftell(FILE *FP);
     off_t ftello(FILE *FP);
     long _ftell_r(struct _reent *PTR, FILE *FP);
     off_t _ftello_r(struct _reent *PTR, FILE *FP);
   *Description*
Objects of type `FILE' can have a "position" that records how much of
the file your program has already read.  Many of the `stdio' functions
depend on this position, and many change it as a side effect.

   The result of `ftell'/`ftello' is the current position for a file
identified by FP.  If you record this result, you can later use it with
`fseek'/`fseeko' to return the file to this position.  The difference
between `ftell' and `ftello' is that `ftell' returns `long' and
`ftello' returns `off_t'.

   In the current implementation, `ftell'/`ftello' simply uses a
character count to represent the file position; this is the same number
that would be recorded by `fgetpos'.

*Returns*
`ftell'/`ftello' return the file position, if possible.  If they cannot
do this, they return `-1L'.  Failure occurs on streams that do not
support positioning; the global `errno' indicates this condition with
the value `ESPIPE'.

*Portability*
`ftell' is required by the ANSI C standard, but the meaning of its
result (when successful) is not specified beyond requiring that it be
acceptable as an argument to `fseek'.  In particular, other conforming
C implementations may return a different result from `ftell' than what
`fgetpos' records.

   `ftello' is defined by the Single Unix specification.

   No supporting OS subroutines are required.

4.29 `funopen', `fropen', `fwopen'--open a stream with custom callbacks
=======================================================================

*Synopsis*
     #include <stdio.h>
     FILE *funopen(const void *COOKIE,
         int (*READFN) (void *cookie, char *buf, int n),
         int (*WRITEFN) (void *cookie, const char *buf, int n),
         fpos_t (*SEEKFN) (void *cookie, fpos_t off, int whence),
         int (*CLOSEFN) (void *cookie));
     FILE *fropen(const void *COOKIE,
         int (*READFN) (void *cookie, char *buf, int n));
     FILE *fwopen(const void *COOKIE,
         int (*WRITEFN) (void *cookie, const char *buf, int n));
   *Description*
`funopen' creates a `FILE' stream where I/O is performed using custom
callbacks.  At least one of READFN and WRITEFN must be provided, which
determines whether the stream behaves with mode <"r">, <"w">, or <"r+">.

   READFN should return -1 on failure, or else the number of bytes read
(0 on EOF).  It is similar to `read', except that <int> rather than
<size_t> bounds a transaction size, and COOKIE will be passed as the
first argument.  A NULL READFN makes attempts to read the stream fail.

   WRITEFN should return -1 on failure, or else the number of bytes
written.  It is similar to `write', except that <int> rather than
<size_t> bounds a transaction size, and COOKIE will be passed as the
first argument.  A NULL WRITEFN makes attempts to write the stream fail.

   SEEKFN should return (fpos_t)-1 on failure, or else the current file
position.  It is similar to `lseek', except that COOKIE will be passed
as the first argument.  A NULL SEEKFN makes the stream behave similarly
to a pipe in relation to stdio functions that require positioning.
This implementation assumes fpos_t and off_t are the same type.

   CLOSEFN should return -1 on failure, or 0 on success.  It is similar
to `close', except that COOKIE will be passed as the first argument.  A
NULL CLOSEFN merely flushes all data then lets `fclose' succeed.  A
failed close will still invalidate the stream.

   Read and write I/O functions are allowed to change the underlying
buffer on fully buffered or line buffered streams by calling `setvbuf'.
They are also not required to completely fill or empty the buffer.
They are not, however, allowed to change streams from unbuffered to
buffered or to change the state of the line buffering flag.  They must
also be prepared to have read or write calls occur on buffers other
than the one most recently specified.

   The functions `fropen' and `fwopen' are convenience macros around
`funopen' that only use the specified callback.

*Returns*
The return value is an open FILE pointer on success.  On error, `NULL'
is returned, and `errno' will be set to EINVAL if a function pointer is
missing, ENOMEM if the stream cannot be created, or EMFILE if too many
streams are already open.

*Portability*
This function is a newlib extension, copying the prototype from BSD.
It is not portable.  See also the `fopencookie' interface from Linux.

   Supporting OS subroutines required: `sbrk'.

4.30 `fwide'--set and determine the orientation of a FILE stream
================================================================

*Synopsis*
     #include <wchar.h>
     int fwide(FILE *FP, int MODE)

     int _fwide_r(struct _reent *PTR, FILE *FP, int MODE)
   *Description*
When MODE is zero, the `fwide' function determines the current
orientation of FP. It returns a value > 0 if FP is wide-character
oriented, i.e. if wide character I/O is permitted but char I/O is
disallowed. It returns a value < 0 if FP is byte oriented, i.e. if char
I/O is permitted but wide character I/O is disallowed. It returns zero
if FP has no orientation yet; in this case the next I/O operation might
change the orientation (to byte oriented if it is a char I/O operation,
or to wide-character oriented if it is a wide character I/O operation).

   Once a stream has an orientation, it cannot be changed and persists
until the stream is closed, unless the stream is re-opened with freopen,
which removes the orientation of the stream.

   When MODE is non-zero, the `fwide' function first attempts to set
FP's orientation (to wide-character oriented if MODE > 0, or to byte
oriented if MODE < 0). It then returns a value denoting the current
orientation, as above.

*Returns*
The `fwide' function returns FP's orientation, after possibly changing
it. A return value > 0 means wide-character oriented. A return value <
0 means byte oriented. A return value of zero means undecided.

*Portability*
C99, POSIX.1-2001.

4.31 `fwrite'--write array elements
===================================

*Synopsis*
     #include <stdio.h>
     size_t fwrite(const void *BUF, size_t SIZE,
         size_t COUNT, FILE *FP);

     #include <stdio.h>
     size_t _fwrite_r(struct _reent *PTR, const void *BUF, size_t SIZE,
         size_t COUNT, FILE *FP);
   *Description*
`fwrite' attempts to copy, starting from the memory location BUF, COUNT
elements (each of size SIZE) into the file or stream identified by FP.
`fwrite' may copy fewer elements than COUNT if an error intervenes.

   `fwrite' also advances the file position indicator (if any) for FP
by the number of _characters_ actually written.

   `_fwrite_r' is simply the reentrant version of `fwrite' that takes
an additional reentrant structure argument: PTR.

*Returns*
If `fwrite' succeeds in writing all the elements you specify, the
result is the same as the argument COUNT.  In any event, the result is
the number of complete elements that `fwrite' copied to the file.

*Portability*
ANSI C requires `fwrite'.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.

4.32 `getc'--read a character (macro)
=====================================

*Synopsis*
     #include <stdio.h>
     int getc(FILE *FP);

     #include <stdio.h>
     int _getc_r(struct _reent *PTR, FILE *FP);
   *Description*
`getc' is a macro, defined in `stdio.h'.  You can use `getc' to get the
next single character from the file or stream identified by FP.  As a
side effect, `getc' advances the file's current position indicator.

   For a subroutine version of this macro, see `fgetc'.

   The `_getc_r' function is simply the reentrant version of `getc'
which passes an additional reentrancy structure pointer argument: PTR.

*Returns*
The next character (read as an `unsigned char', and cast to `int'),
unless there is no more data, or the host system reports a read error;
in either of these situations, `getc' returns `EOF'.

   You can distinguish the two situations that cause an `EOF' result by
using the `ferror' and `feof' functions.

*Portability*
ANSI C requires `getc'; it suggests, but does not require, that `getc'
be implemented as a macro.  The standard explicitly permits macro
implementations of `getc' to use the argument more than once;
therefore, in a portable program, you should not use an expression with
side effects as the `getc' argument.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.

4.33 `getc_unlocked'--non-thread-safe version of getc (macro)
=============================================================

*Synopsis*
     #include <stdio.h>
     int getc_unlocked(FILE *FP);

     #include <stdio.h>
     int _getc_unlocked_r(FILE *FP);
   *Description*
`getc_unlocked' is a non-thread-safe version of `getc' declared in
`stdio.h'.  `getc_unlocked' may only safely be used within a scope
protected by flockfile() (or ftrylockfile()) and funlockfile().  These
functions may safely be used in a multi-threaded program if and only if
they are called while the invoking thread owns the ( FILE *) object, as
is the case after a successful call to the flockfile() or
ftrylockfile() functions.  If threads are disabled, then
`getc_unlocked' is equivalent to `getc'.

   The `_getc_unlocked_r' function is simply the reentrant version of
`get_unlocked' which passes an additional reentrancy structure pointer
argument: PTR.

*Returns*
See `getc'.

*Portability*
POSIX 1003.1 requires `getc_unlocked'.  `getc_unlocked' may be
implemented as a macro, so arguments should not have side-effects.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.

4.34 `getchar'--read a character (macro)
========================================

*Synopsis*
     #include <stdio.h>
     int getchar(void);

     int _getchar_r(struct _reent *REENT);
   *Description*
`getchar' is a macro, defined in `stdio.h'.  You can use `getchar' to
get the next single character from the standard input stream.  As a
side effect, `getchar' advances the standard input's current position
indicator.

   The alternate function `_getchar_r' is a reentrant version.  The
extra argument REENT is a pointer to a reentrancy structure.

*Returns*
The next character (read as an `unsigned char', and cast to `int'),
unless there is no more data, or the host system reports a read error;
in either of these situations, `getchar' returns `EOF'.

   You can distinguish the two situations that cause an `EOF' result by
using ``ferror(stdin)'' and ``feof(stdin)''.

*Portability*
ANSI C requires `getchar'; it suggests, but does not require, that
`getchar' be implemented as a macro.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.

4.35 `getchar_unlocked'--non-thread-safe version of getchar (macro)
===================================================================

*Synopsis*
     #include <stdio.h>
     int getchar_unlocked();

     #include <stdio.h>
     int _getchar_unlocked_r(struct _reent *PTR);
   *Description*
`getchar_unlocked' is a non-thread-safe version of `getchar' declared
in `stdio.h'.  `getchar_unlocked' may only safely be used within a
scope protected by flockfile() (or ftrylockfile()) and funlockfile().
These functions may safely be used in a multi-threaded program if and
only if they are called while the invoking thread owns the ( FILE *)
object, as is the case after a successful call to the flockfile() or
ftrylockfile() functions.  If threads are disabled, then
`getchar_unlocked' is equivalent to `getchar'.

   The `_getchar_unlocked_r' function is simply the reentrant version of
`getchar_unlocked' which passes an addtional reentrancy structure
pointer argument: PTR.

*Returns*
See `getchar'.

*Portability*
POSIX 1003.1 requires `getchar_unlocked'.  `getchar_unlocked' may be
implemented as a macro.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.

4.36 `getdelim'--read a line up to a specified line delimiter
=============================================================

*Synopsis*
     #include <stdio.h>
     int getdelim(char **BUFPTR, size_t *N,
         int DELIM, FILE *FP);
   *Description*
`getdelim' reads a file FP up to and possibly including a specified
delimiter DELIM.  The line is read into a buffer pointed to by BUFPTR
and designated with size *N.  If the buffer is not large enough, it
will be dynamically grown by `getdelim'.  As the buffer is grown, the
pointer to the size N will be updated.

*Returns*
`getdelim' returns `-1' if no characters were successfully read;
otherwise, it returns the number of bytes successfully read.  At end of
file, the result is nonzero.

*Portability*
`getdelim' is a glibc extension.

   No supporting OS subroutines are directly required.

4.37 `getline'--read a line from a file
=======================================

*Synopsis*
     #include <stdio.h>
     ssize_t getline(char **BUFPTR, size_t *N, FILE *FP);
   *Description*
`getline' reads a file FP up to and possibly including the newline
character.  The line is read into a buffer pointed to by BUFPTR and
designated with size *N.  If the buffer is not large enough, it will be
dynamically grown by `getdelim'.  As the buffer is grown, the pointer
to the size N will be updated.

   `getline' is equivalent to getdelim(bufptr, n, '\n', fp);

*Returns*
`getline' returns `-1' if no characters were successfully read,
otherwise, it returns the number of bytes successfully read.  at end of
file, the result is nonzero.

*Portability*
`getline' is a glibc extension.

   No supporting OS subroutines are directly required.

4.38 `gets'--get character string (obsolete, use `fgets' instead)
=================================================================

*Synopsis*
     #include <stdio.h>

     char *gets(char *BUF);

     char *_gets_r(struct _reent *REENT, char *BUF);
   *Description*
Reads characters from standard input until a newline is found.  The
characters up to the newline are stored in BUF. The newline is
discarded, and the buffer is terminated with a 0.

   This is a _dangerous_ function, as it has no way of checking the
amount of space available in BUF. One of the attacks used by the
Internet Worm of 1988 used this to overrun a buffer allocated on the
stack of the finger daemon and overwrite the return address, causing
the daemon to execute code downloaded into it over the connection.

   The alternate function `_gets_r' is a reentrant version.  The extra
argument REENT is a pointer to a reentrancy structure.

*Returns*
`gets' returns the buffer passed to it, with the data filled in. If end
of file occurs with some data already accumulated, the data is returned
with no other indication. If end of file occurs with no data in the
buffer, NULL is returned.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.

4.39 `getw'--read a word (int)
==============================

*Synopsis*
     #include <stdio.h>
     int getw(FILE *FP);
   *Description*
`getw' is a function, defined in `stdio.h'.  You can use `getw' to get
the next word from the file or stream identified by FP.  As a side
effect, `getw' advances the file's current position indicator.

*Returns*
The next word (read as an `int'), unless there is no more data or the
host system reports a read error; in either of these situations, `getw'
returns `EOF'.  Since `EOF' is a valid `int', you must use `ferror' or
`feof' to distinguish these situations.

*Portability*
`getw' is a remnant of K&R C; it is not part of any ISO C Standard.
`fread' should be used instead.  In fact, this implementation of `getw'
is based upon `fread'.

   Supporting OS subroutines required: `fread'.

4.40 `getwchar'--read a wide character from standard input
==========================================================

*Synopsis*
     #include <wchar.h>
     wint_t getwchar(void);

     wint_t _getwchar_r(struct _reent *REENT);
   *Description*
`getwchar' function or macro is the wide character equivalent of the
`getchar' function.  You can use `getwchar' to get the next wide
character from the standard input stream.  As a side effect, `getwchar'
advances the standard input's current position indicator.

   The alternate function `_getwchar_r' is a reentrant version.  The
extra argument REENT is a pointer to a reentrancy structure.

*Returns*
The next wide character cast to `wint_t', unless there is no more data,
or the host system reports a read error; in either of these situations,
`getwchar' returns `WEOF'.

   You can distinguish the two situations that cause an `WEOF' result by
using ``ferror(stdin)'' and ``feof(stdin)''.

*Portability*
C99

4.41 `mktemp', `mkstemp', `mkstemps'--generate unused file name
===============================================================

*Synopsis*
     #include <stdlib.h>
     char *mktemp(char *PATH);
     char *mkdtemp(char *PATH);
     int mkstemp(char *PATH);
     int mkstemps(char *PATH, int SUFFIXLEN);

     char *_mktemp_r(struct _reent *REENT, char *PATH);
     char *_mkdtemp_r(struct _reent *REENT, char *PATH);
     int *_mkstemp_r(struct _reent *REENT, char *PATH);
     int *_mkstemps_r(struct _reent *REENT, char *PATH, int LEN);
   *Description*
`mktemp', `mkstemp', and `mkstemps' attempt to generate a file name
that is not yet in use for any existing file.  `mkstemp' and `mkstemps'
create the file and open it for reading and writing; `mktemp' simply
generates the file name (making `mktemp' a security risk).  `mkdtemp'
attempts to create a directory instead of a file, with a permissions
mask of 0700.

   You supply a simple pattern for the generated file name, as the
string at PATH.  The pattern should be a valid filename (including path
information if you wish) ending with at least six ``X'' characters.
The generated filename will match the leading part of the name you
supply, with the trailing ``X'' characters replaced by some combination
of digits and letters.  With `mkstemps', the ``X'' characters end
SUFFIXLEN bytes before the end of the string.

   The alternate functions `_mktemp_r', `_mkdtemp_r', `_mkstemp_r', and
`_mkstemps_r' are reentrant versions.  The extra argument REENT is a
pointer to a reentrancy structure.

*Returns*
`mktemp' returns the pointer PATH to the modified string representing
an unused filename, unless it could not generate one, or the pattern
you provided is not suitable for a filename; in that case, it returns
`NULL'.

   `mkdtemp' returns the pointer PATH to the modified string if the
directory was created, otherwise it returns `NULL'.

   `mkstemp' and `mkstemps' return a file descriptor to the newly
created file, unless it could not generate an unused filename, or the
pattern you provided is not suitable for a filename; in that case, it
returns `-1'.

*Portability*
ANSI C does not require either `mktemp' or `mkstemp'; the System V
Interface Definition requires `mktemp' as of Issue 2.  POSIX 2001
requires `mkstemp', and POSIX 2008 requires `mkdtemp', but `mkstemps'
is not standardized.

   Supporting OS subroutines required: `getpid', `mkdir', `open',
`stat'.

4.42 `open_memstream', `open_wmemstream'--open a write stream around an arbitrary-length string
===============================================================================================

*Synopsis*
     #include <stdio.h>
     FILE *open_memstream(char **restrict BUF,
         size_t *restrict SIZE);

     #include <wchar.h>
     FILE *open_wmemstream(wchar_t **restrict BUF,
         size_t *restrict SIZE);
   *Description*
`open_memstream' creates a seekable, byte-oriented `FILE' stream that
wraps an arbitrary-length buffer, created as if by `malloc'.  The
current contents of *BUF are ignored; this implementation uses *SIZE as
a hint of the maximum size expected, but does not fail if the hint was
wrong.  The parameters BUF and SIZE are later stored through following
any call to `fflush' or `fclose', set to the current address and usable
size of the allocated string; although after fflush, the pointer is
only valid until another stream operation that results in a write.
Behavior is undefined if the user alters either *BUF or *SIZE prior to
`fclose'.

   `open_wmemstream' is like `open_memstream' just with the associated
stream being wide-oriented.  The size set in SIZE in subsequent
operations is the number of wide characters.

   The stream is write-only, since the user can directly read *BUF
after a flush; see `fmemopen' for a way to wrap a string with a
readable stream.  The user is responsible for calling `free' on the
final *BUF after `fclose'.

   Any time the stream is flushed, a NUL byte is written at the current
position (but is not counted in the buffer length), so that the string
is always NUL-terminated after at most *SIZE bytes (or wide characters
in case of `open_wmemstream').  However, data previously written beyond
the current stream offset is not lost, and the NUL value written during
a flush is restored to its previous value when seeking elsewhere in the
string.

*Returns*
The return value is an open FILE pointer on success.  On error, `NULL'
is returned, and `errno' will be set to EINVAL if BUF or SIZE is NULL,
ENOMEM if memory could not be allocated, or EMFILE if too many streams
are already open.

*Portability*
POSIX.1-2008

   Supporting OS subroutines required: `sbrk'.

4.43 `perror'--print an error message on standard error
=======================================================

*Synopsis*
     #include <stdio.h>
     void perror(char *PREFIX);

     void _perror_r(struct _reent *REENT, char *PREFIX);
   *Description*
Use `perror' to print (on standard error) an error message
corresponding to the current value of the global variable `errno'.
Unless you use `NULL' as the value of the argument PREFIX, the error
message will begin with the string at PREFIX, followed by a colon and a
space (`: '). The remainder of the error message is one of the strings
described for `strerror'.

   The alternate function `_perror_r' is a reentrant version.  The
extra argument REENT is a pointer to a reentrancy structure.

*Returns*
`perror' returns no result.

*Portability*
ANSI C requires `perror', but the strings issued vary from one
implementation to another.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.

4.44 `putc'--write a character (macro)
======================================

*Synopsis*
     #include <stdio.h>
     int putc(int CH, FILE *FP);

     #include <stdio.h>
     int _putc_r(struct _reent *PTR, int CH, FILE *FP);
   *Description*
`putc' is a macro, defined in `stdio.h'.  `putc' writes the argument CH
to the file or stream identified by FP, after converting it from an
`int' to an `unsigned char'.

   If the file was opened with append mode (or if the stream cannot
support positioning), then the new character goes at the end of the
file or stream.  Otherwise, the new character is written at the current
value of the position indicator, and the position indicator advances by
one.

   For a subroutine version of this macro, see `fputc'.

   The `_putc_r' function is simply the reentrant version of `putc'
that takes an additional reentrant structure argument: PTR.

*Returns*
If successful, `putc' returns its argument CH.  If an error intervenes,
the result is `EOF'.  You can use ``ferror(FP)'' to query for errors.

*Portability*
ANSI C requires `putc'; it suggests, but does not require, that `putc'
be implemented as a macro.  The standard explicitly permits macro
implementations of `putc' to use the FP argument more than once;
therefore, in a portable program, you should not use an expression with
side effects as this argument.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.

4.45 `putc_unlocked'--non-thread-safe version of putc (macro)
=============================================================

*Synopsis*
     #include <stdio.h>
     int putc_unlocked(int CH, FILE *FP);

     #include <stdio.h>
     int _putc_unlocked_r(struct _reent *PTR, int CH, FILE *FP);
   *Description*
`putc_unlocked' is a non-thread-safe version of `putc' declared in
`stdio.h'.  `putc_unlocked' may only safely be used within a scope
protected by flockfile() (or ftrylockfile()) and funlockfile().  These
functions may safely be used in a multi-threaded program if and only if
they are called while the invoking thread owns the ( FILE *) object, as
is the case after a successful call to the flockfile() or
ftrylockfile() functions.  If threads are disabled, then
`putc_unlocked' is equivalent to `putc'.

   The function `_putc_unlocked_r' is simply the reentrant version of
`putc_unlocked' that takes an additional reentrant structure pointer
argument: PTR.

*Returns*
See `putc'.

*Portability*
POSIX 1003.1 requires `putc_unlocked'.  `putc_unlocked' may be
implemented as a macro, so arguments should not have side-effects.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.

4.46 `putchar'--write a character (macro)
=========================================

*Synopsis*
     #include <stdio.h>
     int putchar(int CH);

     int _putchar_r(struct _reent *REENT, int CH);
   *Description*
`putchar' is a macro, defined in `stdio.h'.  `putchar' writes its
argument to the standard output stream, after converting it from an
`int' to an `unsigned char'.

   The alternate function `_putchar_r' is a reentrant version.  The
extra argument REENT is a pointer to a reentrancy structure.

*Returns*
If successful, `putchar' returns its argument CH.  If an error
intervenes, the result is `EOF'.  You can use ``ferror(stdin)'' to
query for errors.

*Portability*
ANSI C requires `putchar'; it suggests, but does not require, that
`putchar' be implemented as a macro.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.

4.47 `putchar_unlocked'--non-thread-safe version of putchar (macro)
===================================================================

*Synopsis*
     #include <stdio.h>
     int putchar_unlocked(int CH);
   *Description*
`putchar_unlocked' is a non-thread-safe version of `putchar' declared
in `stdio.h'.  `putchar_unlocked' may only safely be used within a
scope protected by flockfile() (or ftrylockfile()) and funlockfile().
These functions may safely be used in a multi-threaded program if and
only if they are called while the invoking thread owns the ( FILE *)
object, as is the case after a successful call to the flockfile() or
ftrylockfile() functions.  If threads are disabled, then
`putchar_unlocked' is equivalent to `putchar'.

*Returns*
See `putchar'.

*Portability*
POSIX 1003.1 requires `putchar_unlocked'.  `putchar_unlocked' may be
implemented as a macro.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.

4.48 `puts'--write a character string
=====================================

*Synopsis*
     #include <stdio.h>
     int puts(const char *S);

     int _puts_r(struct _reent *REENT, const char *S);
   *Description*
`puts' writes the string at S (followed by a newline, instead of the
trailing null) to the standard output stream.

   The alternate function `_puts_r' is a reentrant version.  The extra
argument REENT is a pointer to a reentrancy structure.

*Returns*
If successful, the result is a nonnegative integer; otherwise, the
result is `EOF'.

*Portability*
ANSI C requires `puts', but does not specify that the result on success
must be `0'; any non-negative value is permitted.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.

4.49 `putw'--write a word (int)
===============================

*Synopsis*
     #include <stdio.h>
     int putw(int W, FILE *FP);
   *Description*
`putw' is a function, defined in `stdio.h'.  You can use `putw' to
write a word to the file or stream identified by FP.  As a side effect,
`putw' advances the file's current position indicator.

*Returns*
Zero on success, `EOF' on failure.

*Portability*
`putw' is a remnant of K&R C; it is not part of any ISO C Standard.
`fwrite' should be used instead.  In fact, this implementation of
`putw' is based upon `fwrite'.

   Supporting OS subroutines required: `fwrite'.

4.50 `putwchar'--write a wide character to standard output
==========================================================

*Synopsis*
     #include <wchar.h>
     wint_t putwchar(wchar_t WC);

     wint_t _putwchar_r(struct _reent *REENT, wchar_t WC);
   *Description*
The `putwchar' function or macro is the wide-character equivalent of
the `putchar' function. It writes the wide character wc to stdout.

   The alternate function `_putwchar_r' is a reentrant version.  The
extra argument REENT is a pointer to a reentrancy structure.

*Returns*
If successful, `putwchar' returns its argument WC.  If an error
intervenes, the result is `EOF'.  You can use ``ferror(stdin)'' to
query for errors.

*Portability*
C99

4.51 `remove'--delete a file's name
===================================

*Synopsis*
     #include <stdio.h>
     int remove(char *FILENAME);

     int _remove_r(struct _reent *REENT, char *FILENAME);
   *Description*
Use `remove' to dissolve the association between a particular filename
(the string at FILENAME) and the file it represents.  After calling
`remove' with a particular filename, you will no longer be able to open
the file by that name.

   In this implementation, you may use `remove' on an open file without
error; existing file descriptors for the file will continue to access
the file's data until the program using them closes the file.

   The alternate function `_remove_r' is a reentrant version.  The
extra argument REENT is a pointer to a reentrancy structure.

*Returns*
`remove' returns `0' if it succeeds, `-1' if it fails.

*Portability*
ANSI C requires `remove', but only specifies that the result on failure
be nonzero.  The behavior of `remove' when you call it on an open file
may vary among implementations.

   Supporting OS subroutine required: `unlink'.

4.52 `rename'--rename a file
============================

*Synopsis*
     #include <stdio.h>
     int rename(const char *OLD, const char *NEW);
   *Description*
Use `rename' to establish a new name (the string at NEW) for a file now
known by the string at OLD.  After a successful `rename', the file is
no longer accessible by the string at OLD.

   If `rename' fails, the file named `*OLD' is unaffected.  The
conditions for failure depend on the host operating system.

*Returns*
The result is either `0' (when successful) or `-1' (when the file could
not be renamed).

*Portability*
ANSI C requires `rename', but only specifies that the result on failure
be nonzero.  The effects of using the name of an existing file as
`*NEW' may vary from one implementation to another.

   Supporting OS subroutines required: `link', `unlink', or `rename'.

4.53 `rewind'--reinitialize a file or stream
============================================

*Synopsis*
     #include <stdio.h>
     void rewind(FILE *FP);
     void _rewind_r(struct _reent *PTR, FILE *FP);
   *Description*
`rewind' returns the file position indicator (if any) for the file or
stream identified by FP to the beginning of the file.  It also clears
any error indicator and flushes any pending output.

*Returns*
`rewind' does not return a result.

*Portability*
ANSI C requires `rewind'.

   No supporting OS subroutines are required.

4.54 `setbuf'--specify full buffering for a file or stream
==========================================================

*Synopsis*
     #include <stdio.h>
     void setbuf(FILE *FP, char *BUF);
   *Description*
`setbuf' specifies that output to the file or stream identified by FP
should be fully buffered.  All output for this file will go to a buffer
(of size `BUFSIZ', specified in ``stdio.h'').  Output will be passed on
to the host system only when the buffer is full, or when an input
operation intervenes.

   You may, if you wish, supply your own buffer by passing a pointer to
it as the argument BUF.  It must have size `BUFSIZ'.  You can also use
`NULL' as the value of BUF, to signal that the `setbuf' function is to
allocate the buffer.

*Warnings*
You may only use `setbuf' before performing any file operation other
than opening the file.

   If you supply a non-null BUF, you must ensure that the associated
storage continues to be available until you close the stream identified
by FP.

*Returns*
`setbuf' does not return a result.

*Portability*
Both ANSI C and the System V Interface Definition (Issue 2) require
`setbuf'.  However, they differ on the meaning of a `NULL' buffer
pointer: the SVID issue 2 specification says that a `NULL' buffer
pointer requests unbuffered output.  For maximum portability, avoid
`NULL' buffer pointers.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.

4.55 `setbuffer'--specify full buffering for a file or stream with size
=======================================================================

*Synopsis*
     #include <stdio.h>
     void setbuffer(FILE *FP, char *BUF, int SIZE);
   *Description*
`setbuffer' specifies that output to the file or stream identified by
FP should be fully buffered.  All output for this file will go to a
buffer (of size SIZE).  Output will be passed on to the host system
only when the buffer is full, or when an input operation intervenes.

   You may, if you wish, supply your own buffer by passing a pointer to
it as the argument BUF.  It must have size SIZE.  You can also use
`NULL' as the value of BUF, to signal that the `setbuffer' function is
to allocate the buffer.

*Warnings*
You may only use `setbuffer' before performing any file operation other
than opening the file.

   If you supply a non-null BUF, you must ensure that the associated
storage continues to be available until you close the stream identified
by FP.

*Returns*
`setbuffer' does not return a result.

*Portability*
This function comes from BSD not ANSI or POSIX.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.

4.56 `setlinebuf'--specify line buffering for a file or stream
==============================================================

*Synopsis*
     #include <stdio.h>
     void setlinebuf(FILE *FP);
   *Description*
`setlinebuf' specifies that output to the file or stream identified by
FP should be line buffered.  This causes the file or stream to pass on
output to the host system at every newline, as well as when the buffer
is full, or when an input operation intervenes.

*Warnings*
You may only use `setlinebuf' before performing any file operation
other than opening the file.

*Returns*
`setlinebuf' returns as per setvbuf.

*Portability*
This function comes from BSD not ANSI or POSIX.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.

4.57 `setvbuf'--specify file or stream buffering
================================================

*Synopsis*
     #include <stdio.h>
     int setvbuf(FILE *FP, char *BUF,
         int MODE, size_t SIZE);
   *Description*
Use `setvbuf' to specify what kind of buffering you want for the file
or stream identified by FP, by using one of the following values (from
`stdio.h') as the MODE argument:

`_IONBF'
     Do not use a buffer: send output directly to the host system for
     the file or stream identified by FP.

`_IOFBF'
     Use full output buffering: output will be passed on to the host
     system only when the buffer is full, or when an input operation
     intervenes.

`_IOLBF'
     Use line buffering: pass on output to the host system at every
     newline, as well as when the buffer is full, or when an input
     operation intervenes.

   Use the SIZE argument to specify how large a buffer you wish.  You
can supply the buffer itself, if you wish, by passing a pointer to a
suitable area of memory as BUF.  Otherwise, you may pass `NULL' as the
BUF argument, and `setvbuf' will allocate the buffer.

*Warnings*
You may only use `setvbuf' before performing any file operation other
than opening the file.

   If you supply a non-null BUF, you must ensure that the associated
storage continues to be available until you close the stream identified
by FP.

*Returns*
A `0' result indicates success, `EOF' failure (invalid MODE or SIZE can
cause failure).

*Portability*
Both ANSI C and the System V Interface Definition (Issue 2) require
`setvbuf'. However, they differ on the meaning of a `NULL' buffer
pointer: the SVID issue 2 specification says that a `NULL' buffer
pointer requests unbuffered output.  For maximum portability, avoid
`NULL' buffer pointers.

   Both specifications describe the result on failure only as a nonzero
value.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.

4.58 `siprintf', `fiprintf', `iprintf', `sniprintf', `asiprintf', `asniprintf'--format output (integer only)
============================================================================================================

*Synopsis*
     #include <stdio.h>

     int iprintf(const char *FORMAT, ...);
     int fiprintf(FILE *FD, const char *FORMAT , ...);
     int siprintf(char *STR, const char *FORMAT, ...);
     int sniprintf(char *STR, size_t SIZE, const char *FORMAT,
         ...);
     int asiprintf(char **STRP, const char *FORMAT, ...);
     char *asniprintf(char *STR, size_t *SIZE,
         const char *FORMAT, ...);

     int _iprintf_r(struct _reent *PTR, const char *FORMAT, ...);
     int _fiprintf_r(struct _reent *PTR, FILE *FD,
         const char *FORMAT, ...);
     int _siprintf_r(struct _reent *PTR, char *STR,
         const char *FORMAT, ...);
     int _sniprintf_r(struct _reent *PTR, char *STR, size_t SIZE,
         const char *FORMAT, ...);
     int _asiprintf_r(struct _reent *PTR, char **STRP,
         const char *FORMAT, ...);
     char *_asniprintf_r(struct _reent *PTR, char *STR,
         size_t *SIZE, const char *FORMAT, ...);
   *Description*
`iprintf', `fiprintf', `siprintf', `sniprintf', `asiprintf', and
`asniprintf' are the same as `printf', `fprintf', `sprintf',
`snprintf', `asprintf', and `asnprintf', respectively, except that they
restrict usage to non-floating-point format specifiers.

   `_iprintf_r', `_fiprintf_r', `_asiprintf_r', `_siprintf_r',
`_sniprintf_r', `_asniprintf_r' are simply reentrant versions of the
functions above.

*Returns*
Similar to `printf', `fprintf', `sprintf', `snprintf', `asprintf', and
`asnprintf'.

*Portability*
`iprintf', `fiprintf', `siprintf', `sniprintf', `asiprintf', and
`asniprintf' are newlib extensions.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.

4.59 `siscanf', `fiscanf', `iscanf'--scan and format non-floating input
=======================================================================

*Synopsis*
     #include <stdio.h>

     int iscanf(const char *FORMAT, ...);
     int fiscanf(FILE *FD, const char *FORMAT, ...);
     int siscanf(const char *STR, const char *FORMAT, ...);

     int _iscanf_r(struct _reent *PTR, const char *FORMAT, ...);
     int _fiscanf_r(struct _reent *PTR, FILE *FD,
         const char *FORMAT, ...);
     int _siscanf_r(struct _reent *PTR, const char *STR,
         const char *FORMAT, ...);
   *Description*
`iscanf', `fiscanf', and `siscanf' are the same as `scanf', `fscanf',
and `sscanf' respectively, only that they restrict the available
formats to non-floating-point format specifiers.

   The routines `_iscanf_r', `_fiscanf_r', and `_siscanf_r' are
reentrant versions of `iscanf', `fiscanf', and `siscanf' that take an
additional first argument pointing to a reentrancy structure.

*Returns*
`iscanf' returns the number of input fields successfully scanned,
converted and stored; the return value does not include scanned fields
which were not stored.

   If `iscanf' attempts to read at end-of-file, the return value is
`EOF'.

   If no fields were stored, the return value is `0'.

*Portability*
`iscanf', `fiscanf', and `siscanf' are newlib extensions.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.

4.60 `sprintf', `fprintf', `printf', `snprintf', `asprintf', `asnprintf'--format output
=======================================================================================

*Synopsis*
     #include <stdio.h>

     int printf(const char *FORMAT, ...);
     int fprintf(FILE *FD, const char *FORMAT, ...);
     int sprintf(char *STR, const char *FORMAT, ...);
     int snprintf(char *STR, size_t SIZE, const char *FORMAT,
         ...);
     int asprintf(char **STRP, const char *FORMAT, ...);
     char *asnprintf(char *STR, size_t *SIZE, const char *FORMAT,
         ...);

     int _printf_r(struct _reent *PTR, const char *FORMAT, ...);
     int _fprintf_r(struct _reent *PTR, FILE *FD,
         const char *FORMAT, ...);
     int _sprintf_r(struct _reent *PTR, char *STR,
         const char *FORMAT, ...);
     int _snprintf_r(struct _reent *PTR, char *STR, size_t SIZE,
         const char *FORMAT, ...);
     int _asprintf_r(struct _reent *PTR, char **STRP,
         const char *FORMAT, ...);
     char *_asnprintf_r(struct _reent *PTR, char *STR,
         size_t *SIZE, const char *FORMAT, ...);
   *Description*
`printf' accepts a series of arguments, applies to each a format
specifier from `*FORMAT', and writes the formatted data to `stdout',
without a terminating NUL character.  The behavior of `printf' is
undefined if there are not enough arguments for the format.  `printf'
returns when it reaches the end of the format string.  If there are
more arguments than the format requires, excess arguments are ignored.

   `fprintf' is like `printf', except that output is directed to the
stream FD rather than `stdout'.

   `sprintf' is like `printf', except that output is directed to the
buffer STR, and a terminating NUL is output.  Behavior is undefined if
more output is generated than the buffer can hold.

   `snprintf' is like `sprintf', except that output is limited to at
most SIZE bytes, including the terminating `NUL'.  As a special case,
if SIZE is 0, STR can be NULL, and `snprintf' merely calculates how
many bytes would be printed.

   `asprintf' is like `sprintf', except that the output is stored in a
dynamically allocated buffer, PSTR, which should be freed later with
`free'.

   `asnprintf' is like `sprintf', except that the return type is either
the original STR if it was large enough, or a dynamically allocated
string if the output exceeds *SIZE; the length of the result is
returned in *SIZE.  When dynamic allocation occurs, the contents of the
original STR may have been modified.

   For `sprintf', `snprintf', and `asnprintf', the behavior is
undefined if the output `*STR' overlaps with one of the arguments.
Behavior is also undefined if the argument for `%n' within `*FORMAT'
overlaps another argument.

   FORMAT is a pointer to a character string containing two types of
objects: ordinary characters (other than `%'), which are copied
unchanged to the output, and conversion specifications, each of which
is introduced by `%'. (To include `%' in the output, use `%%' in the
format string.)  A conversion specification has the following form:

            %[POS][FLAGS][WIDTH][.PREC][SIZE]TYPE

   The fields of the conversion specification have the following
meanings:

   * POS

     Conversions normally consume arguments in the order that they are
     presented.  However, it is possible to consume arguments out of
     order, and reuse an argument for more than one conversion
     specification (although the behavior is undefined if the same
     argument is requested with different types), by specifying POS,
     which is a decimal integer followed by '$'.  The integer must be
     between 1 and <NL_ARGMAX> from limits.h, and if argument `%n$' is
     requested, all earlier arguments must be requested somewhere
     within FORMAT.  If positional parameters are used, then all
     conversion specifications except for `%%' must specify a position.
     This positional parameters method is a POSIX extension to the C
     standard definition for the functions.

   * FLAGS

     FLAGS is an optional sequence of characters which control output
     justification, numeric signs, decimal points, trailing zeros, and
     octal and hex prefixes.  The flag characters are minus (`-'), plus
     (`+'), space ( ), zero (`0'), sharp (`#'), and quote (`'').  They
     can appear in any combination, although not all flags can be used
     for all conversion specification types.

    `''
          A POSIX extension to the C standard.  However, this
          implementation presently treats it as a no-op, which is the
          default behavior for the C locale, anyway.  (If it did what
          it is supposed to, when TYPE were `i', `d', `u', `f', `F',
          `g', or `G', the integer portion of the conversion would be
          formatted with thousands' grouping wide characters.)

    `-'
          The result of the conversion is left justified, and the right
          is padded with blanks.  If you do not use this flag, the
          result is right justified, and padded on the left.

    `+'
          The result of a signed conversion (as determined by TYPE of
          `d', `i', `a', `A', `e', `E', `f', `F', `g', or `G') will
          always begin with a plus or minus sign.  (If you do not use
          this flag, positive values do not begin with a plus sign.)

    `" " (space)'
          If the first character of a signed conversion specification
          is not a sign, or if a signed conversion results in no
          characters, the result will begin with a space.  If the space
          ( ) flag and the plus (`+') flag both appear, the space flag
          is ignored.

    `0'
          If the TYPE character is `d', `i', `o', `u', `x', `X', `a',
          `A', `e', `E', `f', `F', `g', or `G':  leading zeros are used
          to pad the field width (following any indication of sign or
          base); no spaces are used for padding.  If the zero (`0') and
          minus (`-') flags both appear, the zero (`0') flag will be
          ignored.  For `d', `i', `o', `u', `x', and `X' conversions,
          if a precision PREC is specified, the zero (`0') flag is
          ignored.

          Note that `0' is interpreted as a flag, not as the beginning
          of a field width.

    `#'
          The result is to be converted to an alternative form,
          according to the TYPE character:

         `o'
               Increases precision to force the first digit of the
               result to be a zero.

         `x'
               A non-zero result will have a `0x' prefix.

         `X'
               A non-zero result will have a `0X' prefix.

         `a, A, e, E, f, or F'
               The result will always contain a decimal point even if
               no digits follow the point.  (Normally, a decimal point
               appears only if a digit follows it.)  Trailing zeros are
               removed.

         `g or G'
               The result will always contain a decimal point even if
               no digits follow the point.  Trailing zeros are not
               removed.

         `all others'
               Undefined.

   * WIDTH

     WIDTH is an optional minimum field width.  You can either specify
     it directly as a decimal integer, or indirectly by using instead
     an asterisk (`*'), in which case an `int' argument is used as the
     field width.  If positional arguments are used, then the width
     must also be specified positionally as `*m$', with m as a decimal
     integer.  Negative field widths are treated as specifying the
     minus (`-') flag for left justfication, along with a positive
     field width.  The resulting format may be wider than the specified
     width.

   * PREC

     PREC is an optional field; if present, it is introduced with ``.''
     (a period). You can specify the precision either directly as a
     decimal integer or indirectly by using an asterisk (`*'), in which
     case an `int' argument is used as the precision.  If positional
     arguments are used, then the precision must also be specified
     positionally as `*m$', with m as a decimal integer.  Supplying a
     negative precision is equivalent to omitting the precision.  If
     only a period is specified the precision is zero. The effect
     depends on the conversion TYPE.

    `d, i, o, u, x, or X'
          Minimum number of digits to appear.  If no precision is
          given, defaults to 1.

    `a or A'
          Number of digits to appear after the decimal point.  If no
          precision is given, the precision defaults to the minimum
          needed for an exact representation.

    `e, E, f or F'
          Number of digits to appear after the decimal point.  If no
          precision is given, the precision defaults to 6.

    `g or G'
          Maximum number of significant digits.  A precision of 0 is
          treated the same as a precision of 1.  If no precision is
          given, the precision defaults to 6.

    `s or S'
          Maximum number of characters to print from the string.  If no
          precision is given, the entire string is printed.

    `all others'
          undefined.

   * SIZE

     SIZE is an optional modifier that changes the data type that the
     corresponding argument has.  Behavior is unspecified if a size is
     given that does not match the TYPE.

    `hh'
          With `d', `i', `o', `u', `x', or `X', specifies that the
          argument should be converted to a `signed char' or `unsigned
          char' before printing.

          With `n', specifies that the argument is a pointer to a
          `signed char'.

    `h'
          With `d', `i', `o', `u', `x', or `X', specifies that the
          argument should be converted to a `short' or `unsigned short'
          before printing.

          With `n', specifies that the argument is a pointer to a
          `short'.

    `l'
          With `d', `i', `o', `u', `x', or `X', specifies that the
          argument is a `long' or `unsigned long'.

          With `c', specifies that the argument has type `wint_t'.

          With `s', specifies that the argument is a pointer to
          `wchar_t'.

          With `n', specifies that the argument is a pointer to a
          `long'.

          With `a', `A', `e', `E', `f', `F', `g', or `G', has no effect
          (because of vararg promotion rules, there is no need to
          distinguish between `float' and `double').

    `ll'
          With `d', `i', `o', `u', `x', or `X', specifies that the
          argument is a `long long' or `unsigned long long'.

          With `n', specifies that the argument is a pointer to a `long
          long'.

    `j'
          With `d', `i', `o', `u', `x', or `X', specifies that the
          argument is an `intmax_t' or `uintmax_t'.

          With `n', specifies that the argument is a pointer to an
          `intmax_t'.

    `z'
          With `d', `i', `o', `u', `x', or `X', specifies that the
          argument is a `size_t'.

          With `n', specifies that the argument is a pointer to a
          `size_t'.

    `t'
          With `d', `i', `o', `u', `x', or `X', specifies that the
          argument is a `ptrdiff_t'.

          With `n', specifies that the argument is a pointer to a
          `ptrdiff_t'.

    `L'
          With `a', `A', `e', `E', `f', `F', `g', or `G', specifies
          that the argument is a `long double'.

   * TYPE

     TYPE specifies what kind of conversion `printf' performs.  Here is
     a table of these:

    `%'
          Prints the percent character (`%').

    `c'
          Prints ARG as single character.  If the `l' size specifier is
          in effect, a multibyte character is printed.

    `C'
          Short for `%lc'.  A POSIX extension to the C standard.

    `s'
          Prints the elements of a pointer to `char' until the
          precision or a null character is reached.  If the `l' size
          specifier is in effect, the pointer is to an array of
          `wchar_t', and the string is converted to multibyte
          characters before printing.

    `S'
          Short for `%ls'.  A POSIX extension to the C standard.

    `d or i'
          Prints a signed decimal integer; takes an `int'.  Leading
          zeros are inserted as necessary to reach the precision.  A
          value of 0 with a precision of 0 produces an empty string.

    `D'
          Newlib extension, short for `%ld'.

    `o'
          Prints an unsigned octal integer; takes an `unsigned'.
          Leading zeros are inserted as necessary to reach the
          precision.  A value of 0 with a precision of 0 produces an
          empty string.

    `O'
          Newlib extension, short for `%lo'.

    `u'
          Prints an unsigned decimal integer; takes an `unsigned'.
          Leading zeros are inserted as necessary to reach the
          precision.  A value of 0 with a precision of 0 produces an
          empty string.

    `U'
          Newlib extension, short for `%lu'.

    `x'
          Prints an unsigned hexadecimal integer (using `abcdef' as
          digits beyond `9'); takes an `unsigned'.  Leading zeros are
          inserted as necessary to reach the precision.  A value of 0
          with a precision of 0 produces an empty string.

    `X'
          Like `x', but uses `ABCDEF' as digits beyond `9'.

    `f'
          Prints a signed value of the form `[-]9999.9999', with the
          precision determining how many digits follow the decimal
          point; takes a `double' (remember that `float' promotes to
          `double' as a vararg).  The low order digit is rounded to
          even.  If the precision results in at most DECIMAL_DIG
          digits, the result is rounded correctly; if more than
          DECIMAL_DIG digits are printed, the result is only guaranteed
          to round back to the original value.

          If the value is infinite, the result is `inf', and no zero
          padding is performed.  If the value is not a number, the
          result is `nan', and no zero padding is performed.

    `F'
          Like `f', but uses `INF' and `NAN' for non-finite numbers.

    `e'
          Prints a signed value of the form `[-]9.9999e[+|-]999'; takes
          a `double'.  The digit before the decimal point is non-zero
          if the value is non-zero.  The precision determines how many
          digits appear between `.' and `e', and the exponent always
          contains at least two digits.  The value zero has an exponent
          of zero.  If the value is not finite, it is printed like `f'.

    `E'
          Like `e', but using `E' to introduce the exponent, and like
          `F' for non-finite values.

    `g'
          Prints a signed value in either `f' or `e' form, based on the
          given value and precision--an exponent less than -4 or
          greater than the precision selects the `e' form.  Trailing
          zeros and the decimal point are printed only if necessary;
          takes a `double'.

    `G'
          Like `g', except use `F' or `E' form.

    `a'
          Prints a signed value of the form `[-]0x1.ffffp[+|-]9'; takes
          a `double'.  The letters `abcdef' are used for digits beyond
          `9'.  The precision determines how many digits appear after
          the decimal point.  The exponent contains at least one digit,
          and is a decimal value representing the power of 2; a value
          of 0 has an exponent of 0.  Non-finite values are printed
          like `f'.

    `A'
          Like `a', except uses `X', `P', and `ABCDEF' instead of lower
          case.

    `n'
          Takes a pointer to `int', and stores a count of the number of
          bytes written so far.  No output is created.

    `p'
          Takes a pointer to `void', and prints it in an
          implementation-defined format.  This implementation is
          similar to `%#tx'), except that `0x' appears even for the
          NULL pointer.

   `_printf_r', `_fprintf_r', `_asprintf_r', `_sprintf_r',
`_snprintf_r', `_asnprintf_r' are simply reentrant versions of the
functions above.

*Returns*
On success, `sprintf' and `asprintf' return the number of bytes in the
output string, except the concluding `NUL' is not counted.  `snprintf'
returns the number of bytes that would be in the output string, except
the concluding `NUL' is not counted.  `printf' and `fprintf' return the
number of characters transmitted.  `asnprintf' returns the original STR
if there was enough room, otherwise it returns an allocated string.

   If an error occurs, the result of `printf', `fprintf', `snprintf',
and `asprintf' is a negative value, and the result of `asnprintf' is
NULL.  No error returns occur for `sprintf'.  For `printf' and
`fprintf', `errno' may be set according to `fputc'.  For `asprintf' and
`asnprintf', `errno' may be set to ENOMEM if allocation fails, and for
`snprintf', `errno' may be set to EOVERFLOW if SIZE or the output
length exceeds INT_MAX.

*Bugs*
The ""' (quote) flag does not work when locale's thousands_sep is not
empty.

*Portability*
ANSI C requires `printf', `fprintf', `sprintf', and `snprintf'.
`asprintf' and `asnprintf' are newlib extensions.

   The ANSI C standard specifies that implementations must support at
least formatted output of up to 509 characters.  This implementation
has no inherent limit.

   Depending on how newlib was configured, not all format specifiers are
supported.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.

4.61 `sscanf', `fscanf', `scanf'--scan and format input
=======================================================

*Synopsis*
     #include <stdio.h>

     int scanf(const char *FORMAT, ...);
     int fscanf(FILE *FD, const char *FORMAT, ...);
     int sscanf(const char *STR, const char *FORMAT, ...);

     int _scanf_r(struct _reent *PTR, const char *FORMAT, ...);
     int _fscanf_r(struct _reent *PTR, FILE *FD,
         const char *FORMAT, ...);
     int _sscanf_r(struct _reent *PTR, const char *STR,
         const char *FORMAT, ...);
   *Description*
`scanf' scans a series of input fields from standard input, one
character at a time.  Each field is interpreted according to a format
specifier passed to `scanf' in the format string at `*FORMAT'.  `scanf'
stores the interpreted input from each field at the address passed to
it as the corresponding argument following FORMAT.  You must supply the
same number of format specifiers and address arguments as there are
input fields.

   There must be sufficient address arguments for the given format
specifiers; if not the results are unpredictable and likely
disasterous.  Excess address arguments are merely ignored.

   `scanf' often produces unexpected results if the input diverges from
an expected pattern. Since the combination of `gets' or `fgets'
followed by `sscanf' is safe and easy, that is the preferred way to be
certain that a program is synchronized with input at the end of a line.

   `fscanf' and `sscanf' are identical to `scanf', other than the
source of input: `fscanf' reads from a file, and `sscanf' from a string.

   The routines `_scanf_r', `_fscanf_r', and `_sscanf_r' are reentrant
versions of `scanf', `fscanf', and `sscanf' that take an additional
first argument pointing to a reentrancy structure.

   The string at `*FORMAT' is a character sequence composed of zero or
more directives. Directives are composed of one or more whitespace
characters, non-whitespace characters, and format specifications.

   Whitespace characters are blank (` '), tab (`\t'), or newline (`\n').
When `scanf' encounters a whitespace character in the format string it
will read (but not store) all consecutive whitespace characters up to
the next non-whitespace character in the input.

   Non-whitespace characters are all other ASCII characters except the
percent sign (`%').  When `scanf' encounters a non-whitespace character
in the format string it will read, but not store a matching
non-whitespace character.

   Format specifications tell `scanf' to read and convert characters
from the input field into specific types of values, and store then in
the locations specified by the address arguments.

   Trailing whitespace is left unread unless explicitly matched in the
format string.

   The format specifiers must begin with a percent sign (`%') and have
the following form:

            %[*][WIDTH][SIZE]TYPE

   Each format specification begins with the percent character (`%').
The other fields are:
`*'
     an optional marker; if present, it suppresses interpretation and
     assignment of this input field.

`WIDTH'
     an optional maximum field width: a decimal integer, which controls
     the maximum number of characters that will be read before
     converting the current input field.  If the input field has fewer
     than WIDTH characters, `scanf' reads all the characters in the
     field, and then proceeds with the next field and its format
     specification.

     If a whitespace or a non-convertable character occurs before WIDTH
     character are read, the characters up to that character are read,
     converted, and stored.  Then `scanf' proceeds to the next format
     specification.

`size'
     `h', `j', `l', `L', `t', and `z' are optional size characters
     which override the default way that `scanf' interprets the data
     type of the corresponding argument.

          Modifier   Type(s)
             hh      d, i, o, u, x, n  convert input to char,
                                       store in char object

             h       d, i, o, u, x, n  convert input to short,
                                       store in short object

             h       D, I, O, U, X     no effect
                     e, f, c, s, p

             j       d, i, o, u, x, n  convert input to intmax_t,
                                       store in intmax_t object

             j       all others        no effect

             l       d, i, o, u, x, n  convert input to long,
                                       store in long object

             l       e, f, g           convert input to double
                                       store in a double object

             l       D, I, O, U, X     no effect
                     c, s, p

             ll      d, i, o, u, x, n  convert to long long,
                                       store in long long

             L       d, i, o, u, x, n  convert to long long,
                                       store in long long

             L       e, f, g, E, G     convert to long double,
                                       store in long double

             L       all others        no effect

             t       d, i, o, u, x, n  convert input to ptrdiff_t,
                                       store in ptrdiff_t object

             t       all others        no effect

             z       d, i, o, u, x, n  convert input to size_t,
                                       store in size_t object

             z       all others        no effect

`TYPE'
     A character to specify what kind of conversion `scanf' performs.
     Here is a table of the conversion characters:

    `%'
          No conversion is done; the percent character (`%') is stored.

    `c'
          Scans one character.  Corresponding ARG: `(char *arg)'.

    `s'
          Reads a character string into the array supplied.
          Corresponding ARG: `(char arg[])'.

    `[PATTERN]'
          Reads a non-empty character string into memory starting at
          ARG.  This area must be large enough to accept the sequence
          and a terminating null character which will be added
          automatically.  (PATTERN is discussed in the paragraph
          following this table). Corresponding ARG: `(char *arg)'.

    `d'
          Reads a decimal integer into the corresponding ARG: `(int
          *arg)'.

    `D'
          Reads a decimal integer into the corresponding ARG: `(long
          *arg)'.

    `o'
          Reads an octal integer into the corresponding ARG: `(int
          *arg)'.

    `O'
          Reads an octal integer into the corresponding ARG: `(long
          *arg)'.

    `u'
          Reads an unsigned decimal integer into the corresponding ARG:
          `(unsigned int *arg)'.

    `U'
          Reads an unsigned decimal integer into the corresponding ARG:
          `(unsigned long *arg)'.

    `x,X'
          Read a hexadecimal integer into the corresponding ARG: `(int
          *arg)'.

    `e, f, g'
          Read a floating-point number into the corresponding ARG:
          `(float *arg)'.

    `E, F, G'
          Read a floating-point number into the corresponding ARG:
          `(double *arg)'.

    `i'
          Reads a decimal, octal or hexadecimal integer into the
          corresponding ARG: `(int *arg)'.

    `I'
          Reads a decimal, octal or hexadecimal integer into the
          corresponding ARG: `(long *arg)'.

    `n'
          Stores the number of characters read in the corresponding
          ARG: `(int *arg)'.

    `p'
          Stores a scanned pointer.  ANSI C leaves the details to each
          implementation; this implementation treats `%p' exactly the
          same as `%U'.  Corresponding ARG: `(void **arg)'.

     A PATTERN of characters surrounded by square brackets can be used
     instead of the `s' type character.  PATTERN is a set of characters
     which define a search set of possible characters making up the
     `scanf' input field.  If the first character in the brackets is a
     caret (`^'), the search set is inverted to include all ASCII
     characters except those between the brackets.  There is also a
     range facility which you can use as a shortcut. `%[0-9] ' matches
     all decimal digits.  The hyphen must not be the first or last
     character in the set.  The character prior to the hyphen must be
     lexically less than the character after it.

     Here are some PATTERN examples:
    `%[abcd]'
          matches strings containing only `a', `b', `c', and `d'.

    `%[^abcd]'
          matches strings containing any characters except `a', `b',
          `c', or `d'

    `%[A-DW-Z]'
          matches strings containing `A', `B', `C', `D', `W', `X', `Y',
          `Z'

    `%[z-a]'
          matches the characters  `z', `-', and `a'

     Floating point numbers (for field types `e', `f', `g', `E', `F',
     `G') must correspond to the following general form:

          		[+/-] ddddd[.]ddd [E|e[+|-]ddd]

     where objects inclosed in square brackets are optional, and `ddd'
     represents decimal, octal, or hexadecimal digits.

*Returns*
`scanf' returns the number of input fields successfully scanned,
converted and stored; the return value does not include scanned fields
which were not stored.

   If `scanf' attempts to read at end-of-file, the return value is
`EOF'.

   If no fields were stored, the return value is `0'.

   `scanf' might stop scanning a particular field before reaching the
normal field end character, or may terminate entirely.

   `scanf' stops scanning and storing the current field and moves to
the next input field (if any) in any of the following situations:

   * The assignment suppressing character (`*') appears after the `%'
     in the format specification; the current input field is scanned
     but not stored.

   * WIDTH characters have been read (WIDTH is a width specification, a
     positive decimal integer).

   * The next character read cannot be converted under the the current
     format (for example, if a `Z' is read when the format is decimal).

   * The next character in the input field does not appear in the
     search set (or does appear in the inverted search set).

   When `scanf' stops scanning the current input field for one of these
reasons, the next character is considered unread and used as the first
character of the following input field, or the first character in a
subsequent read operation on the input.

   `scanf' will terminate under the following circumstances:

   * The next character in the input field conflicts with a
     corresponding non-whitespace character in the format string.

   * The next character in the input field is `EOF'.

   * The format string has been exhausted.

   When the format string contains a character sequence that is not
part of a format specification, the same character sequence must appear
in the input; `scanf' will scan but not store the matched characters.
If a conflict occurs, the first conflicting character remains in the
input as if it had never been read.

*Portability*
`scanf' is ANSI C.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.

4.62 `swprintf', `fwprintf', `wprintf'--wide character format output
====================================================================

*Synopsis*
     #include <wchar.h>

     int wprintf(const wchar_t *FORMAT, ...);
     int fwprintf(FILE *FD, const wchar_t *FORMAT, ...);
     int swprintf(wchar_t *STR, size_t SIZE,
         const wchar_t *FORMAT, ...);

     int _wprintf_r(struct _reent *PTR, const wchar_t *FORMAT, ...);
     int _fwprintf_r(struct _reent *PTR, FILE *FD,
         const wchar_t *FORMAT, ...);
     int _swprintf_r(struct _reent *PTR, wchar_t *STR,
         size_t SIZE, const wchar_t *FORMAT, ...);
   *Description*
`wprintf' accepts a series of arguments, applies to each a format
specifier from `*FORMAT', and writes the formatted data to `stdout',
without a terminating NUL wide character.  The behavior of `wprintf' is
undefined if there are not enough arguments for the format or if any
argument is not the right type for the corresponding conversion
specifier.  `wprintf' returns when it reaches the end of the format
string.  If there are more arguments than the format requires, excess
arguments are ignored.

   `fwprintf' is like `wprintf', except that output is directed to the
stream FD rather than `stdout'.

   `swprintf' is like `wprintf', except that output is directed to the
buffer STR with a terminating wide `NUL', and the resulting string
length is limited to at most SIZE wide characters, including the
terminating `NUL'.  It is considered an error if the output (including
the terminating wide-`NULL') does not fit into SIZE wide characters.
(This error behavior is not the same as for `snprintf', which
`swprintf' is otherwise completely analogous to.  While `snprintf'
allows the needed size to be known simply by giving SIZE=0, `swprintf'
does not, giving an error instead.)

   For `swprintf' the behavior is undefined if the output `*STR'
overlaps with one of the arguments.  Behavior is also undefined if the
argument for `%n' within `*FORMAT' overlaps another argument.

   FORMAT is a pointer to a wide character string containing two types
of objects: ordinary characters (other than `%'), which are copied
unchanged to the output, and conversion specifications, each of which
is introduced by `%'. (To include `%' in the output, use `%%' in the
format string.)  A conversion specification has the following form:

            %[POS][FLAGS][WIDTH][.PREC][SIZE]TYPE

   The fields of the conversion specification have the following
meanings:

   * POS

     Conversions normally consume arguments in the order that they are
     presented.  However, it is possible to consume arguments out of
     order, and reuse an argument for more than one conversion
     specification (although the behavior is undefined if the same
     argument is requested with different types), by specifying POS,
     which is a decimal integer followed by '$'.  The integer must be
     between 1 and <NL_ARGMAX> from limits.h, and if argument `%n$' is
     requested, all earlier arguments must be requested somewhere
     within FORMAT.  If positional parameters are used, then all
     conversion specifications except for `%%' must specify a position.
     This positional parameters method is a POSIX extension to the C
     standard definition for the functions.

   * FLAGS

     FLAGS is an optional sequence of characters which control output
     justification, numeric signs, decimal points, trailing zeros, and
     octal and hex prefixes.  The flag characters are minus (`-'), plus
     (`+'), space ( ), zero (`0'), sharp (`#'), and quote (`'').  They
     can appear in any combination, although not all flags can be used
     for all conversion specification types.

    `''
          A POSIX extension to the C standard.  However, this
          implementation presently treats it as a no-op, which is the
          default behavior for the C locale, anyway.  (If it did what
          it is supposed to, when TYPE were `i', `d', `u', `f', `F',
          `g', or `G', the integer portion of the conversion would be
          formatted with thousands' grouping wide characters.)

    `-'
          The result of the conversion is left justified, and the right
          is padded with blanks.  If you do not use this flag, the
          result is right justified, and padded on the left.

    `+'
          The result of a signed conversion (as determined by TYPE of
          `d', `i', `a', `A', `e', `E', `f', `F', `g', or `G') will
          always begin with a plus or minus sign.  (If you do not use
          this flag, positive values do not begin with a plus sign.)

    `" " (space)'
          If the first character of a signed conversion specification
          is not a sign, or if a signed conversion results in no
          characters, the result will begin with a space.  If the space
          ( ) flag and the plus (`+') flag both appear, the space flag
          is ignored.

    `0'
          If the TYPE character is `d', `i', `o', `u', `x', `X', `a',
          `A', `e', `E', `f', `F', `g', or `G':  leading zeros are used
          to pad the field width (following any indication of sign or
          base); no spaces are used for padding.  If the zero (`0') and
          minus (`-') flags both appear, the zero (`0') flag will be
          ignored.  For `d', `i', `o', `u', `x', and `X' conversions,
          if a precision PREC is specified, the zero (`0') flag is
          ignored.

          Note that `0' is interpreted as a flag, not as the beginning
          of a field width.

    `#'
          The result is to be converted to an alternative form,
          according to the TYPE character:

         `o'
               Increases precision to force the first digit of the
               result to be a zero.

         `x'
               A non-zero result will have a `0x' prefix.

         `X'
               A non-zero result will have a `0X' prefix.

         `a, A, e, E, f, or F'
               The result will always contain a decimal point even if
               no digits follow the point.  (Normally, a decimal point
               appears only if a digit follows it.)  Trailing zeros are
               removed.

         `g or G'
               The result will always contain a decimal point even if
               no digits follow the point.  Trailing zeros are not
               removed.

         `all others'
               Undefined.

   * WIDTH

     WIDTH is an optional minimum field width.  You can either specify
     it directly as a decimal integer, or indirectly by using instead
     an asterisk (`*'), in which case an `int' argument is used as the
     field width.  If positional arguments are used, then the width
     must also be specified positionally as `*m$', with m as a decimal
     integer.  Negative field widths are treated as specifying the
     minus (`-') flag for left justfication, along with a positive
     field width.  The resulting format may be wider than the specified
     width.

   * PREC

     PREC is an optional field; if present, it is introduced with ``.''
     (a period). You can specify the precision either directly as a
     decimal integer or indirectly by using an asterisk (`*'), in which
     case an `int' argument is used as the precision.  If positional
     arguments are used, then the precision must also be specified
     positionally as `*m$', with m as a decimal integer.  Supplying a
     negative precision is equivalent to omitting the precision.  If
     only a period is specified the precision is zero. The effect
     depends on the conversion TYPE.

    `d, i, o, u, x, or X'
          Minimum number of digits to appear.  If no precision is
          given, defaults to 1.

    `a or A'
          Number of digits to appear after the decimal point.  If no
          precision is given, the precision defaults to the minimum
          needed for an exact representation.

    `e, E, f or F'
          Number of digits to appear after the decimal point.  If no
          precision is given, the precision defaults to 6.

    `g or G'
          Maximum number of significant digits.  A precision of 0 is
          treated the same as a precision of 1.  If no precision is
          given, the precision defaults to 6.

    `s or S'
          Maximum number of characters to print from the string.  If no
          precision is given, the entire string is printed.

    `all others'
          undefined.

   * SIZE

     SIZE is an optional modifier that changes the data type that the
     corresponding argument has.  Behavior is unspecified if a size is
     given that does not match the TYPE.

    `hh'
          With `d', `i', `o', `u', `x', or `X', specifies that the
          argument should be converted to a `signed char' or `unsigned
          char' before printing.

          With `n', specifies that the argument is a pointer to a
          `signed char'.

    `h'
          With `d', `i', `o', `u', `x', or `X', specifies that the
          argument should be converted to a `short' or `unsigned short'
          before printing.

          With `n', specifies that the argument is a pointer to a
          `short'.

    `l'
          With `d', `i', `o', `u', `x', or `X', specifies that the
          argument is a `long' or `unsigned long'.

          With `c', specifies that the argument has type `wint_t'.

          With `s', specifies that the argument is a pointer to
          `wchar_t'.

          With `n', specifies that the argument is a pointer to a
          `long'.

          With `a', `A', `e', `E', `f', `F', `g', or `G', has no effect
          (because of vararg promotion rules, there is no need to
          distinguish between `float' and `double').

    `ll'
          With `d', `i', `o', `u', `x', or `X', specifies that the
          argument is a `long long' or `unsigned long long'.

          With `n', specifies that the argument is a pointer to a `long
          long'.

    `j'
          With `d', `i', `o', `u', `x', or `X', specifies that the
          argument is an `intmax_t' or `uintmax_t'.

          With `n', specifies that the argument is a pointer to an
          `intmax_t'.

    `z'
          With `d', `i', `o', `u', `x', or `X', specifies that the
          argument is a `size_t'.

          With `n', specifies that the argument is a pointer to a
          `size_t'.

    `t'
          With `d', `i', `o', `u', `x', or `X', specifies that the
          argument is a `ptrdiff_t'.

          With `n', specifies that the argument is a pointer to a
          `ptrdiff_t'.

    `L'
          With `a', `A', `e', `E', `f', `F', `g', or `G', specifies
          that the argument is a `long double'.

   * TYPE

     TYPE specifies what kind of conversion `wprintf' performs.  Here
     is a table of these:

    `%'
          Prints the percent character (`%').

    `c'
          If no `l' qualifier is present, the int argument shall be
          converted to a wide character as if by calling the btowc()
          function and the resulting wide character shall be written.
          Otherwise, the wint_t argument shall be converted to wchar_t,
          and written.

    `C'
          Short for `%lc'.  A POSIX extension to the C standard.

    `s'
          If no `l' qualifier is present, the application shall ensure
          that the argument is a pointer to a character array
          containing a character sequence beginning in the initial
          shift state.  Characters from the array shall be converted as
          if by repeated calls to the mbrtowc() function, with the
          conversion state described by an mbstate_t object initialized
          to zero before the first character is converted, and written
          up to (but not including) the terminating null wide
          character. If the precision is specified, no more than that
          many wide characters shall be written.  If the precision is
          not specified, or is greater than the size of the array, the
          application shall ensure that the array contains a null wide
          character.

          If an `l' qualifier is present, the application shall ensure
          that the argument is a pointer to an array of type wchar_t.
          Wide characters from the array shall be written up to (but
          not including) a terminating null wide character. If no
          precision is specified, or is greater than the size of the
          array, the application shall ensure that the array contains a
          null wide character. If a precision is specified, no more
          than that many wide characters shall be written.

    `S'
          Short for `%ls'.  A POSIX extension to the C standard.

    `d or i'
          Prints a signed decimal integer; takes an `int'.  Leading
          zeros are inserted as necessary to reach the precision.  A
          value of 0 with a precision of 0 produces an empty string.

    `o'
          Prints an unsigned octal integer; takes an `unsigned'.
          Leading zeros are inserted as necessary to reach the
          precision.  A value of 0 with a precision of 0 produces an
          empty string.

    `u'
          Prints an unsigned decimal integer; takes an `unsigned'.
          Leading zeros are inserted as necessary to reach the
          precision.  A value of 0 with a precision of 0 produces an
          empty string.

    `x'
          Prints an unsigned hexadecimal integer (using `abcdef' as
          digits beyond `9'); takes an `unsigned'.  Leading zeros are
          inserted as necessary to reach the precision.  A value of 0
          with a precision of 0 produces an empty string.

    `X'
          Like `x', but uses `ABCDEF' as digits beyond `9'.

    `f'
          Prints a signed value of the form `[-]9999.9999', with the
          precision determining how many digits follow the decimal
          point; takes a `double' (remember that `float' promotes to
          `double' as a vararg).  The low order digit is rounded to
          even.  If the precision results in at most DECIMAL_DIG
          digits, the result is rounded correctly; if more than
          DECIMAL_DIG digits are printed, the result is only guaranteed
          to round back to the original value.

          If the value is infinite, the result is `inf', and no zero
          padding is performed.  If the value is not a number, the
          result is `nan', and no zero padding is performed.

    `F'
          Like `f', but uses `INF' and `NAN' for non-finite numbers.

    `e'
          Prints a signed value of the form `[-]9.9999e[+|-]999'; takes
          a `double'.  The digit before the decimal point is non-zero
          if the value is non-zero.  The precision determines how many
          digits appear between `.' and `e', and the exponent always
          contains at least two digits.  The value zero has an exponent
          of zero.  If the value is not finite, it is printed like `f'.

    `E'
          Like `e', but using `E' to introduce the exponent, and like
          `F' for non-finite values.

    `g'
          Prints a signed value in either `f' or `e' form, based on the
          given value and precision--an exponent less than -4 or
          greater than the precision selects the `e' form.  Trailing
          zeros and the decimal point are printed only if necessary;
          takes a `double'.

    `G'
          Like `g', except use `F' or `E' form.

    `a'
          Prints a signed value of the form `[-]0x1.ffffp[+|-]9'; takes
          a `double'.  The letters `abcdef' are used for digits beyond
          `9'.  The precision determines how many digits appear after
          the decimal point.  The exponent contains at least one digit,
          and is a decimal value representing the power of 2; a value
          of 0 has an exponent of 0.  Non-finite values are printed
          like `f'.

    `A'
          Like `a', except uses `X', `P', and `ABCDEF' instead of lower
          case.

    `n'
          Takes a pointer to `int', and stores a count of the number of
          bytes written so far.  No output is created.

    `p'
          Takes a pointer to `void', and prints it in an
          implementation-defined format.  This implementation is
          similar to `%#tx'), except that `0x' appears even for the
          NULL pointer.

   `_wprintf_r', `_fwprintf_r', `_swprintf_r', are simply reentrant
versions of the functions above.

*Returns*
On success, `swprintf' return the number of wide characters in the
output string, except the concluding `NUL' is not counted.  `wprintf'
and `fwprintf' return the number of characters transmitted.

   If an error occurs, the result of `wprintf', `fwprintf', and
`swprintf' is a negative value.  For `wprintf' and `fwprintf', `errno'
may be set according to `fputwc'.  For `swprintf', `errno' may be set
to EOVERFLOW if SIZE is greater than INT_MAX / sizeof (wchar_t), or
when the output does not fit into SIZE wide characters (including the
terminating wide `NULL').

*Bugs*
The ""' (quote) flag does not work when locale's thousands_sep is not
empty.

*Portability*
POSIX-1.2008 with extensions; C99 (compliant except for POSIX
extensions).

   Depending on how newlib was configured, not all format specifiers are
supported.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.

4.63 `swscanf', `fwscanf', `wscanf'--scan and format wide character input
=========================================================================

*Synopsis*
     #include <stdio.h>

     int wscanf(const wchar_t *FORMAT, ...);
     int fwscanf(FILE *FD, const wchar_t *FORMAT, ...);
     int swscanf(const wchar_t *STR, const wchar_t *FORMAT, ...);

     int _wscanf_r(struct _reent *PTR, const wchar_t *FORMAT, ...);
     int _fwscanf_r(struct _reent *PTR, FILE *FD,
         const wchar_t *FORMAT, ...);
     int _swscanf_r(struct _reent *PTR, const wchar_t *STR,
         const wchar_t *FORMAT, ...);
   *Description*
`wscanf' scans a series of input fields from standard input, one wide
character at a time.  Each field is interpreted according to a format
specifier passed to `wscanf' in the format string at `*FORMAT'.
`wscanf' stores the interpreted input from each field at the address
passed to it as the corresponding argument following FORMAT.  You must
supply the same number of format specifiers and address arguments as
there are input fields.

   There must be sufficient address arguments for the given format
specifiers; if not the results are unpredictable and likely
disasterous.  Excess address arguments are merely ignored.

   `wscanf' often produces unexpected results if the input diverges from
an expected pattern. Since the combination of `gets' or `fgets'
followed by `swscanf' is safe and easy, that is the preferred way to be
certain that a program is synchronized with input at the end of a line.

   `fwscanf' and `swscanf' are identical to `wscanf', other than the
source of input: `fwscanf' reads from a file, and `swscanf' from a
string.

   The routines `_wscanf_r', `_fwscanf_r', and `_swscanf_r' are
reentrant versions of `wscanf', `fwscanf', and `swscanf' that take an
additional first argument pointing to a reentrancy structure.

   The string at `*FORMAT' is a wide character sequence composed of
zero or more directives. Directives are composed of one or more
whitespace characters, non-whitespace characters, and format
specifications.

   Whitespace characters are blank (` '), tab (`\t'), or newline (`\n').
When `wscanf' encounters a whitespace character in the format string it
will read (but not store) all consecutive whitespace characters up to
the next non-whitespace character in the input.

   Non-whitespace characters are all other ASCII characters except the
percent sign (`%').  When `wscanf' encounters a non-whitespace
character in the format string it will read, but not store a matching
non-whitespace character.

   Format specifications tell `wscanf' to read and convert characters
from the input field into specific types of values, and store then in
the locations specified by the address arguments.

   Trailing whitespace is left unread unless explicitly matched in the
format string.

   The format specifiers must begin with a percent sign (`%') and have
the following form:

            %[*][WIDTH][SIZE]TYPE

   Each format specification begins with the percent character (`%').
The other fields are:
`*'
     an optional marker; if present, it suppresses interpretation and
     assignment of this input field.

`WIDTH'
     an optional maximum field width: a decimal integer, which controls
     the maximum number of characters that will be read before
     converting the current input field.  If the input field has fewer
     than WIDTH characters, `wscanf' reads all the characters in the
     field, and then proceeds with the next field and its format
     specification.

     If a whitespace or a non-convertable wide character occurs before
     WIDTH character are read, the characters up to that character are
     read, converted, and stored.  Then `wscanf' proceeds to the next
     format specification.

`size'
     `h', `j', `l', `L', `t', and `z' are optional size characters
     which override the default way that `wscanf' interprets the data
     type of the corresponding argument.

          Modifier   Type(s)
             hh      d, i, o, u, x, n  convert input to char,
                                       store in char object

             h       d, i, o, u, x, n  convert input to short,
                                       store in short object

             h       e, f, c, s, p     no effect

             j       d, i, o, u, x, n  convert input to intmax_t,
                                       store in intmax_t object

             j       all others        no effect

             l       d, i, o, u, x, n  convert input to long,
                                       store in long object

             l       e, f, g           convert input to double
                                       store in a double object

             l       c, s, [           the input is stored in a wchar_t object

             l       p                 no effect

             ll      d, i, o, u, x, n  convert to long long,
                                       store in long long

             L       d, i, o, u, x, n  convert to long long,
                                       store in long long

             L       e, f, g, E, G     convert to long double,
                                       store in long double

             L       all others        no effect

             t       d, i, o, u, x, n  convert input to ptrdiff_t,
                                       store in ptrdiff_t object

             t       all others        no effect

             z       d, i, o, u, x, n  convert input to size_t,
                                       store in size_t object

             z       all others        no effect

`TYPE'
     A character to specify what kind of conversion `wscanf' performs.
     Here is a table of the conversion characters:

    `%'
          No conversion is done; the percent character (`%') is stored.

    `c'
          Scans one wide character.  Corresponding ARG: `(char *arg)'.
          Otherwise, if an `l' specifier is present, the corresponding
          ARG is a `(wchar_t *arg)'.

    `s'
          Reads a character string into the array supplied.
          Corresponding ARG: `(char arg[])'.  If an `l' specifier is
          present, the corresponding ARG is a `(wchar_t *arg)'.

    `[PATTERN]'
          Reads a non-empty character string into memory starting at
          ARG.  This area must be large enough to accept the sequence
          and a terminating null character which will be added
          automatically.  (PATTERN is discussed in the paragraph
          following this table).  Corresponding ARG: `(char *arg)'.  If
          an `l' specifier is present, the corresponding ARG is a
          `(wchar_t *arg)'.

    `d'
          Reads a decimal integer into the corresponding ARG: `(int
          *arg)'.

    `o'
          Reads an octal integer into the corresponding ARG: `(int
          *arg)'.

    `u'
          Reads an unsigned decimal integer into the corresponding ARG:
          `(unsigned int *arg)'.

    `x,X'
          Read a hexadecimal integer into the corresponding ARG: `(int
          *arg)'.

    `e, f, g'
          Read a floating-point number into the corresponding ARG:
          `(float *arg)'.

    `E, F, G'
          Read a floating-point number into the corresponding ARG:
          `(double *arg)'.

    `i'
          Reads a decimal, octal or hexadecimal integer into the
          corresponding ARG: `(int *arg)'.

    `n'
          Stores the number of characters read in the corresponding
          ARG: `(int *arg)'.

    `p'
          Stores a scanned pointer.  ANSI C leaves the details to each
          implementation; this implementation treats `%p' exactly the
          same as `%U'.  Corresponding ARG: `(void **arg)'.

     A PATTERN of characters surrounded by square brackets can be used
     instead of the `s' type character.  PATTERN is a set of characters
     which define a search set of possible characters making up the
     `wscanf' input field.  If the first character in the brackets is a
     caret (`^'), the search set is inverted to include all ASCII
     characters except those between the brackets.  There is no range
     facility as is defined in the corresponding non-wide character
     scanf functions.  Ranges are not part of the POSIX standard.

     Here are some PATTERN examples:
    `%[abcd]'
          matches wide character strings containing only `a', `b', `c',
          and `d'.

    `%[^abcd]'
          matches wide character strings containing any characters
          except `a', `b', `c', or `d'.

    `%[A-DW-Z]'
          Note: No wide character ranges, so this expression matches
          wide character strings containing `A', `-', `D', `W', `Z'.

     Floating point numbers (for field types `e', `f', `g', `E', `F',
     `G') must correspond to the following general form:

          		[+/-] ddddd[.]ddd [E|e[+|-]ddd]

     where objects inclosed in square brackets are optional, and `ddd'
     represents decimal, octal, or hexadecimal digits.

*Returns*
`wscanf' returns the number of input fields successfully scanned,
converted and stored; the return value does not include scanned fields
which were not stored.

   If `wscanf' attempts to read at end-of-file, the return value is
`EOF'.

   If no fields were stored, the return value is `0'.

   `wscanf' might stop scanning a particular field before reaching the
normal field end character, or may terminate entirely.

   `wscanf' stops scanning and storing the current field and moves to
the next input field (if any) in any of the following situations:

   * The assignment suppressing character (`*') appears after the `%'
     in the format specification; the current input field is scanned
     but not stored.

   * WIDTH characters have been read (WIDTH is a width specification, a
     positive decimal integer).

   * The next wide character read cannot be converted under the the
     current format (for example, if a `Z' is read when the format is
     decimal).

   * The next wide character in the input field does not appear in the
     search set (or does appear in the inverted search set).

   When `wscanf' stops scanning the current input field for one of
these reasons, the next character is considered unread and used as the
first character of the following input field, or the first character in
a subsequent read operation on the input.

   `wscanf' will terminate under the following circumstances:

   * The next wide character in the input field conflicts with a
     corresponding non-whitespace character in the format string.

   * The next wide character in the input field is `WEOF'.

   * The format string has been exhausted.

   When the format string contains a wide character sequence that is
not part of a format specification, the same wide character sequence
must appear in the input; `wscanf' will scan but not store the matched
characters.  If a conflict occurs, the first conflicting wide character
remains in the input as if it had never been read.

*Portability*
`wscanf' is C99, POSIX-1.2008.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.

4.64 `tmpfile'--create a temporary file
=======================================

*Synopsis*
     #include <stdio.h>
     FILE *tmpfile(void);

     FILE *_tmpfile_r(struct _reent *REENT);
   *Description*
Create a temporary file (a file which will be deleted automatically),
using a name generated by `tmpnam'.  The temporary file is opened with
the mode `"wb+"', permitting you to read and write anywhere in it as a
binary file (without any data transformations the host system may
perform for text files).

   The alternate function `_tmpfile_r' is a reentrant version.  The
argument REENT is a pointer to a reentrancy structure.

*Returns*
`tmpfile' normally returns a pointer to the temporary file.  If no
temporary file could be created, the result is NULL, and `errno'
records the reason for failure.

*Portability*
Both ANSI C and the System V Interface Definition (Issue 2) require
`tmpfile'.

   Supporting OS subroutines required: `close', `fstat', `getpid',
`isatty', `lseek', `open', `read', `sbrk', `write'.

   `tmpfile' also requires the global pointer `environ'.

4.65 `tmpnam', `tempnam'--name for a temporary file
===================================================

*Synopsis*
     #include <stdio.h>
     char *tmpnam(char *S);
     char *tempnam(char *DIR, char *PFX);
     char *_tmpnam_r(struct _reent *REENT, char *S);
     char *_tempnam_r(struct _reent *REENT, char *DIR, char *PFX);
   *Description*
Use either of these functions to generate a name for a temporary file.
The generated name is guaranteed to avoid collision with other files
(for up to `TMP_MAX' calls of either function).

   `tmpnam' generates file names with the value of `P_tmpdir' (defined
in ``stdio.h'') as the leading directory component of the path.

   You can use the `tmpnam' argument S to specify a suitable area of
memory for the generated filename; otherwise, you can call
`tmpnam(NULL)' to use an internal static buffer.

   `tempnam' allows you more control over the generated filename: you
can use the argument DIR to specify the path to a directory for
temporary files, and you can use the argument PFX to specify a prefix
for the base filename.

   If DIR is `NULL', `tempnam' will attempt to use the value of
environment variable `TMPDIR' instead; if there is no such value,
`tempnam' uses the value of `P_tmpdir' (defined in ``stdio.h'').

   If you don't need any particular prefix to the basename of temporary
files, you can pass `NULL' as the PFX argument to `tempnam'.

   `_tmpnam_r' and `_tempnam_r' are reentrant versions of `tmpnam' and
`tempnam' respectively.  The extra argument REENT is a pointer to a
reentrancy structure.

*Warnings*
The generated filenames are suitable for temporary files, but do not in
themselves make files temporary.  Files with these names must still be
explicitly removed when you no longer want them.

   If you supply your own data area S for `tmpnam', you must ensure
that it has room for at least `L_tmpnam' elements of type `char'.

*Returns*
Both `tmpnam' and `tempnam' return a pointer to the newly generated
filename.

*Portability*
ANSI C requires `tmpnam', but does not specify the use of `P_tmpdir'.
The System V Interface Definition (Issue 2) requires both `tmpnam' and
`tempnam'.

   Supporting OS subroutines required: `close',  `fstat', `getpid',
`isatty', `lseek', `open', `read', `sbrk', `write'.

   The global pointer `environ' is also required.

4.66 `ungetc'--push data back into a stream
===========================================

*Synopsis*
     #include <stdio.h>
     int ungetc(int C, FILE *STREAM);

     int _ungetc_r(struct _reent *REENT, int C, FILE *STREAM);
   *Description*
`ungetc' is used to return bytes back to STREAM to be read again.  If C
is EOF, the stream is unchanged.  Otherwise, the unsigned char C is put
back on the stream, and subsequent reads will see the bytes pushed back
in reverse order.  Pushed byes are lost if the stream is repositioned,
such as by `fseek', `fsetpos', or `rewind'.

   The underlying file is not changed, but it is possible to push back
something different than what was originally read.  Ungetting a
character will clear the end-of-stream marker, and decrement the file
position indicator.  Pushing back beyond the beginning of a file gives
unspecified behavior.

   The alternate function `_ungetc_r' is a reentrant version.  The
extra argument REENT is a pointer to a reentrancy structure.

*Returns*
The character pushed back, or `EOF' on error.

*Portability*
ANSI C requires `ungetc', but only requires a pushback buffer of one
byte; although this implementation can handle multiple bytes, not all
can.  Pushing back a signed char is a common application bug.

   Supporting OS subroutines required: `sbrk'.

4.67 `ungetwc'--push wide character data back into a stream
===========================================================

*Synopsis*
     #include <stdio.h>
     #include <wchar.h>
     wint_t ungetwc(wint_t WC, FILE *STREAM);

     wint_t _ungetwc_r(struct _reent *REENT, wint_t WC, FILE *STREAM);
   *Description*
`ungetwc' is used to return wide characters back to STREAM to be read
again.  If WC is WEOF, the stream is unchanged.  Otherwise, the wide
character WC is put back on the stream, and subsequent reads will see
the wide chars pushed back in reverse order.  Pushed wide chars are
lost if the stream is repositioned, such as by `fseek', `fsetpos', or
`rewind'.

   The underlying file is not changed, but it is possible to push back
something different than what was originally read.  Ungetting a
character will clear the end-of-stream marker, and decrement the file
position indicator.  Pushing back beyond the beginning of a file gives
unspecified behavior.

   The alternate function `_ungetwc_r' is a reentrant version.  The
extra argument REENT is a pointer to a reentrancy structure.

*Returns*
The wide character pushed back, or `WEOF' on error.

*Portability*
C99

4.68 `vfprintf', `vprintf', `vsprintf', `vsnprintf', `vasprintf', `vasnprintf'--format argument list
====================================================================================================

*Synopsis*
     #include <stdio.h>
     #include <stdarg.h>
     int vprintf(const char *FMT, va_list LIST);
     int vfprintf(FILE *FP, const char *FMT, va_list LIST);
     int vsprintf(char *STR, const char *FMT, va_list LIST);
     int vsnprintf(char *STR, size_t SIZE, const char *FMT,
         va_list LIST);
     int vasprintf(char **STRP, const char *FMT, va_list LIST);
     char *vasnprintf(char *STR, size_t *SIZE, const char *FMT,
         va_list LIST);

     int _vprintf_r(struct _reent *REENT, const char *FMT,
         va_list LIST);
     int _vfprintf_r(struct _reent *REENT, FILE *FP,
         const char *FMT, va_list LIST);
     int _vsprintf_r(struct _reent *REENT, char *STR,
         const char *FMT, va_list LIST);
     int _vasprintf_r(struct _reent *REENT, char **STR,
         const char *FMT, va_list LIST);
     int _vsnprintf_r(struct _reent *REENT, char *STR,
         size_t SIZE, const char *FMT, va_list LIST);
     char *_vasnprintf_r(struct _reent *REENT, char *STR,
         size_t *SIZE, const char *FMT, va_list LIST);
   *Description*
`vprintf', `vfprintf', `vasprintf', `vsprintf', `vsnprintf', and
`vasnprintf' are (respectively) variants of `printf', `fprintf',
`asprintf', `sprintf', `snprintf', and `asnprintf'.  They differ only
in allowing their caller to pass the variable argument list as a
`va_list' object (initialized by `va_start') rather than directly
accepting a variable number of arguments.  The caller is responsible
for calling `va_end'.

   `_vprintf_r', `_vfprintf_r', `_vasprintf_r', `_vsprintf_r',
`_vsnprintf_r', and `_vasnprintf_r' are reentrant versions of the above.

*Returns*
The return values are consistent with the corresponding functions.

*Portability*
ANSI C requires `vprintf', `vfprintf', `vsprintf', and `vsnprintf'.
The remaining functions are newlib extensions.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.

4.69 `vfscanf', `vscanf', `vsscanf'--format argument list
=========================================================

*Synopsis*
     #include <stdio.h>
     #include <stdarg.h>
     int vscanf(const char *FMT, va_list LIST);
     int vfscanf(FILE *FP, const char *FMT, va_list LIST);
     int vsscanf(const char *STR, const char *FMT, va_list LIST);

     int _vscanf_r(struct _reent *REENT, const char *FMT,
         va_list LIST);
     int _vfscanf_r(struct _reent *REENT, FILE *FP, const char *FMT,
         va_list LIST);
     int _vsscanf_r(struct _reent *REENT, const char *STR,
         const char *FMT, va_list LIST);
   *Description*
`vscanf', `vfscanf', and `vsscanf' are (respectively) variants of
`scanf', `fscanf', and `sscanf'.  They differ only in allowing their
caller to pass the variable argument list as a `va_list' object
(initialized by `va_start') rather than directly accepting a variable
number of arguments.

*Returns*
The return values are consistent with the corresponding functions:
`vscanf' returns the number of input fields successfully scanned,
converted, and stored; the return value does not include scanned fields
which were not stored.

   If `vscanf' attempts to read at end-of-file, the return value is
`EOF'.

   If no fields were stored, the return value is `0'.

   The routines `_vscanf_r', `_vfscanf_f', and `_vsscanf_r' are
reentrant versions which take an additional first parameter which
points to the reentrancy structure.

*Portability*
These are GNU extensions.

   Supporting OS subroutines required:

4.70 `vfwprintf', `vwprintf', `vswprintf'--wide character format argument list
==============================================================================

*Synopsis*
     #include <stdio.h>
     #include <stdarg.h>
     #include <wchar.h>
     int vwprintf(const wchar_t *FMT, va_list LIST);
     int vfwprintf(FILE *FP, const wchar_t *FMT, va_list LIST);
     int vswprintf(wchar_t *STR, size_t SIZE, const wchar_t *FMT,
         va_list LIST);

     int _vwprintf_r(struct _reent *REENT, const wchar_t *FMT,
         va_list LIST);
     int _vfwprintf_r(struct _reent *REENT, FILE *FP,
         const wchar_t *FMT, va_list LIST);
     int _vswprintf_r(struct _reent *REENT, wchar_t *STR,
         size_t SIZE, const wchar_t *FMT, va_list LIST);
   *Description*
`vwprintf', `vfwprintf' and `vswprintf' are (respectively) variants of
`wprintf', `fwprintf' and `swprintf'.  They differ only in allowing
their caller to pass the variable argument list as a `va_list' object
(initialized by `va_start') rather than directly accepting a variable
number of arguments.  The caller is responsible for calling `va_end'.

   `_vwprintf_r', `_vfwprintf_r' and `_vswprintf_r' are reentrant
versions of the above.

*Returns*
The return values are consistent with the corresponding functions.

*Portability*
POSIX-1.2008 with extensions; C99 (compliant except for POSIX
extensions).

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.

*See Also*
`wprintf', `fwprintf' and `swprintf'.

4.71 `vfwscanf', `vwscanf', `vswscanf'--scan and format argument list from wide character input
===============================================================================================

*Synopsis*
     #include <stdio.h>
     #include <stdarg.h>
     int vwscanf(const wchar_t *FMT, va_list LIST);
     int vfwscanf(FILE *FP, const wchar_t *FMT, va_list LIST);
     int vswscanf(const wchar_t *STR, const wchar_t *FMT, va_list LIST);

     int _vwscanf(struct _reent *REENT, const wchar_t *FMT,
         va_list LIST);
     int _vfwscanf(struct _reent *REENT, FILE *FP, const wchar_t *FMT,
         va_list LIST);
     int _vswscanf(struct _reent *REENT, const wchar_t *STR,
         const wchar_t *FMT, va_list LIST);
   *Description*
`vwscanf', `vfwscanf', and `vswscanf' are (respectively) variants of
`wscanf', `fwscanf', and `swscanf'.  They differ only in allowing their
caller to pass the variable argument list as a `va_list' object
(initialized by `va_start') rather than directly accepting a variable
number of arguments.

*Returns*
The return values are consistent with the corresponding functions:
`vwscanf' returns the number of input fields successfully scanned,
converted, and stored; the return value does not include scanned fields
which were not stored.

   If `vwscanf' attempts to read at end-of-file, the return value is
`EOF'.

   If no fields were stored, the return value is `0'.

   The routines `_vwscanf', `_vfwscanf', and `_vswscanf' are reentrant
versions which take an additional first parameter which points to the
reentrancy structure.

*Portability*
C99, POSIX-1.2008

4.72 `viprintf', `vfiprintf', `vsiprintf', `vsniprintf', `vasiprintf', `vasniprintf'--format argument list (integer only)
=========================================================================================================================

*Synopsis*
     #include <stdio.h>
     #include <stdarg.h>
     int viprintf(const char *FMT, va_list LIST);
     int vfiprintf(FILE *FP, const char *FMT, va_list LIST);
     int vsiprintf(char *STR, const char *FMT, va_list LIST);
     int vsniprintf(char *STR, size_t SIZE, const char *FMT,
         va_list LIST);
     int vasiprintf(char **STRP, const char *FMT, va_list LIST);
     char *vasniprintf(char *STR, size_t *SIZE, const char *FMT,
         va_list LIST);

     int _viprintf_r(struct _reent *REENT, const char *FMT,
         va_list LIST);
     int _vfiprintf_r(struct _reent *REENT, FILE *FP,
         const char *FMT, va_list LIST);
     int _vsiprintf_r(struct _reent *REENT, char *STR,
         const char *FMT, va_list LIST);
     int _vsniprintf_r(struct _reent *REENT, char *STR,
         size_t SIZE, const char *FMT, va_list LIST);
     int _vasiprintf_r(struct _reent *REENT, char **STR,
         const char *FMT, va_list LIST);
     char *_vasniprintf_r(struct _reent *REENT, char *STR,
         size_t *SIZE, const char *FMT, va_list LIST);
   *Description*
`viprintf', `vfiprintf', `vasiprintf', `vsiprintf', `vsniprintf', and
`vasniprintf' are (respectively) variants of `iprintf', `fiprintf',
`asiprintf', `siprintf', `sniprintf', and `asniprintf'.  They differ
only in allowing their caller to pass the variable argument list as a
`va_list' object (initialized by `va_start') rather than directly
accepting a variable number of arguments.  The caller is responsible
for calling `va_end'.

   `_viprintf_r', `_vfiprintf_r', `_vasiprintf_r', `_vsiprintf_r',
`_vsniprintf_r', and `_vasniprintf_r' are reentrant versions of the
above.

*Returns*
The return values are consistent with the corresponding functions:

*Portability*
All of these functions are newlib extensions.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.

4.73 `viscanf', `vfiscanf', `vsiscanf'--format argument list
============================================================

*Synopsis*
     #include <stdio.h>
     #include <stdarg.h>
     int viscanf(const char *FMT, va_list LIST);
     int vfiscanf(FILE *FP, const char *FMT, va_list LIST);
     int vsiscanf(const char *STR, const char *FMT, va_list LIST);

     int _viscanf_r(struct _reent *REENT, const char *FMT,
         va_list LIST);
     int _vfiscanf_r(struct _reent *REENT, FILE *FP, const char *FMT,
         va_list LIST);
     int _vsiscanf_r(struct _reent *REENT, const char *STR,
         const char *FMT, va_list LIST);
   *Description*
`viscanf', `vfiscanf', and `vsiscanf' are (respectively) variants of
`iscanf', `fiscanf', and `siscanf'.  They differ only in allowing their
caller to pass the variable argument list as a `va_list' object
(initialized by `va_start') rather than directly accepting a variable
number of arguments.

*Returns*
The return values are consistent with the corresponding functions:
`viscanf' returns the number of input fields successfully scanned,
converted, and stored; the return value does not include scanned fields
which were not stored.

   If `viscanf' attempts to read at end-of-file, the return value is
`EOF'.

   If no fields were stored, the return value is `0'.

   The routines `_viscanf_r', `_vfiscanf_f', and `_vsiscanf_r' are
reentrant versions which take an additional first parameter which
points to the reentrancy structure.

*Portability*
These are newlib extensions.

   Supporting OS subroutines required:

5 Large File Input and Output (`stdio.h')
*****************************************

This chapter comprises additional functions to manage large files which
are potentially larger than 2GB.

   The underlying facilities for input and output depend on the host
system, but these functions provide a uniform interface.

   The corresponding declarations are in `stdio.h'.

5.1 `fopen64'--open a large file
================================

*Synopsis*
     #include <stdio.h>
     FILE *fopen64(const char *FILE, const char *MODE);
     FILE *_fopen64_r(void *REENT,
         const char *FILE, const char *MODE);
   *Description*
`fopen64' is identical to `fopen' except it opens a large file that is
potentially >2GB in size.  See `fopen' for further details.

*Returns*
`fopen64' return a file pointer which you can use for other file
operations, unless the file you requested could not be opened; in that
situation, the result is `NULL'.  If the reason for failure was an
invalid string at MODE, `errno' is set to `EINVAL'.

*Portability*
`fopen64' is a glibc extension.

   Supporting OS subroutines required: `close', `fstat64', `isatty',
`lseek64', `open64', `read', `sbrk', `write'.

5.2 `freopen64'--open a large file using an existing file descriptor
====================================================================

*Synopsis*
     #include <stdio.h>
     FILE *freopen64(const char *FILE, const char *MODE,
         FILE *FP);
     FILE *_freopen64_r(struct _reent *PTR, const char *FILE,
         const char *MODE, FILE *FP);
   *Description*
Use this variant of `fopen64' if you wish to specify a particular file
descriptor FP (notably `stdin', `stdout', or `stderr') for the file.

   If FP was associated with another file or stream, `freopen64' closes
that other file or stream (but ignores any errors while closing it).

   FILE and MODE are used just as in `fopen'.

   If FILE is `NULL', the underlying stream is modified rather than
closed.  The file cannot be given a more permissive access mode (for
example, a MODE of "w" will fail on a read-only file descriptor), but
can change status such as append or binary mode.  If modification is
not possible, failure occurs.

*Returns*
If successful, the result is the same as the argument FP.  If the file
cannot be opened as specified, the result is `NULL'.

*Portability*
`freopen' is a glibc extension.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek64', `open64', `read', `sbrk', `write'.

5.3 `ftello64'--return position in a stream or file
===================================================

*Synopsis*
     #include <stdio.h>
     _off64_t ftello64(FILE *FP);
     _off64_t _ftello64_r(struct _reent *PTR, FILE *FP);
   *Description*
Objects of type `FILE' can have a "position" that records how much of
the file your program has already read.  Many of the `stdio' functions
depend on this position, and many change it as a side effect.

   The result of `ftello64' is the current position for a large file
identified by FP.  If you record this result, you can later use it with
`fseeko64' to return the file to this position.  The difference between
`ftello' and `ftello64' is that `ftello' returns `off_t' and `ftello64'
is designed to work for large files (>2GB) and returns `_off64_t'.

   In the current implementation, `ftello64' simply uses a character
count to represent the file position; this is the same number that
would be recorded by `fgetpos64'.

   The function exists only if the __LARGE64_FILES flag is defined.  An
error occurs if the FP was not opened via `fopen64'.

*Returns*
`ftello64' returns the file position, if possible.  If it cannot do
this, it returns `-1'.  Failure occurs on streams that do not support
positioning or not opened via `fopen64'; the global `errno' indicates
this condition with the value `ESPIPE'.

*Portability*
`ftello64' is a glibc extension.

   No supporting OS subroutines are required.

5.4 `fseeko64'--set file position for large file
================================================

*Synopsis*
     #include <stdio.h>
     int fseeko64(FILE *FP, _off64_t OFFSET, int WHENCE)
     int _fseeko64_r (struct _reent *PTR, FILE *FP,
         _off64_t OFFSET, int WHENCE)
   *Description*
Objects of type `FILE' can have a "position" that records how much of
the file your program has already read.  Many of the `stdio' functions
depend on this position, and many change it as a side effect.

   You can use `fseeko64' to set the position for the file identified by
FP that was opened via `fopen64'.  The value of OFFSET determines the
new position, in one of three ways selected by the value of WHENCE
(defined as macros in ``stdio.h''):

   `SEEK_SET'--OFFSET is the absolute file position (an offset from the
beginning of the file) desired.  OFFSET must be positive.

   `SEEK_CUR'--OFFSET is relative to the current file position.  OFFSET
can meaningfully be either positive or negative.

   `SEEK_END'--OFFSET is relative to the current end of file.  OFFSET
can meaningfully be either positive (to increase the size of the file)
or negative.

   See `ftello64' to determine the current file position.

*Returns*
`fseeko64' returns `0' when successful.  On failure, the result is
`EOF'.  The reason for failure is indicated in `errno': either `ESPIPE'
(the stream identified by FP doesn't support repositioning or wasn't
opened via `fopen64') or `EINVAL' (invalid file position).

*Portability*
`fseeko64' is a glibc extension.

   Supporting OS subroutines required: `close', `fstat64', `isatty',
`lseek64', `read', `sbrk', `write'.

5.5 `fgetpos64'--record position in a large stream or file
==========================================================

*Synopsis*
     #include <stdio.h>
     int fgetpos64(FILE *FP, _fpos64_t *POS);
     int _fgetpos64_r(struct _reent *PTR, FILE *FP,
         _fpos64_t *POS);
   *Description*
Objects of type `FILE' can have a "position" that records how much of
the file your program has already read.  Many of the `stdio' functions
depend on this position, and many change it as a side effect.

   You can use `fgetpos64' to report on the current position for a file
identified by FP that was opened by `fopen64'; `fgetpos' will write a
value representing that position at `*POS'.  Later, you can use this
value with `fsetpos64' to return the file to this position.

   In the current implementation, `fgetpos64' simply uses a character
count to represent the file position; this is the same number that
would be returned by `ftello64'.

*Returns*
`fgetpos64' returns `0' when successful.  If `fgetpos64' fails, the
result is `1'.  Failure occurs on streams that do not support
positioning or streams not opened via `fopen64'; the global `errno'
indicates these conditions with the value `ESPIPE'.

*Portability*
`fgetpos64' is a glibc extension.

   No supporting OS subroutines are required.

5.6 `fsetpos64'--restore position of a large stream or file
===========================================================

*Synopsis*
     #include <stdio.h>
     int fsetpos64(FILE *FP, const _fpos64_t *POS);
     int _fsetpos64_r(struct _reent *PTR, FILE *FP,
         const _fpos64_t *POS);
   *Description*
Objects of type `FILE' can have a "position" that records how much of
the file your program has already read.  Many of the `stdio' functions
depend on this position, and many change it as a side effect.

   You can use `fsetpos64' to return the large file identified by FP to
a previous position `*POS' (after first recording it with `fgetpos64').

   See `fseeko64' for a similar facility.

*Returns*
`fgetpos64' returns `0' when successful.  If `fgetpos64' fails, the
result is `1'.  The reason for failure is indicated in `errno': either
`ESPIPE' (the stream identified by FP doesn't support 64-bit
repositioning) or `EINVAL' (invalid file position).

*Portability*
`fsetpos64' is a glibc extension.

   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek64', `read', `sbrk', `write'.

5.7 `tmpfile64'--create a large temporary file
==============================================

*Synopsis*
     #include <stdio.h>
     FILE *tmpfile64(void);

     FILE *_tmpfile64_r(void *REENT);
   *Description*
Create a large temporary file (a file which will be deleted
automatically), using a name generated by `tmpnam'.  The temporary file
is opened with the mode `"wb+"', permitting you to read and write
anywhere in it as a binary file (without any data transformations the
host system may perform for text files).  The file may be larger than
2GB.

   The alternate function `_tmpfile64_r' is a reentrant version.  The
argument REENT is a pointer to a reentrancy structure.

   Both `tmpfile64' and `_tmpfile64_r' are only defined if
__LARGE64_FILES is defined.

*Returns*
`tmpfile64' normally returns a pointer to the temporary file.  If no
temporary file could be created, the result is NULL, and `errno'
records the reason for failure.

*Portability*
`tmpfile64' is a glibc extension.

   Supporting OS subroutines required: `close', `fstat', `getpid',
`isatty', `lseek64', `open64', `read', `sbrk', `write'.

   `tmpfile64' also requires the global pointer `environ'.

6 Strings and Memory (`string.h')
*********************************

This chapter describes string-handling functions and functions for
managing areas of memory.  The corresponding declarations are in
`string.h'.

6.1 `bcmp'--compare two memory areas
====================================

*Synopsis*
     #include <string.h>
     int bcmp(const void *S1, const void *S2, size_t N);
   *Description*
This function compares not more than N bytes of the object pointed to
by S1 with the object pointed to by S2.

   This function is identical to `memcmp'.

*Returns*
The function returns an integer greater than, equal to or less than
zero 	according to whether the object pointed to by S1 is greater
than, equal to or less than the object pointed to by S2.

*Portability*
`bcmp' requires no supporting OS subroutines.

6.2 `bcopy'--copy memory regions
================================

*Synopsis*
     #include <string.h>
     void bcopy(const void *IN, void *OUT, size_t N);
   *Description*
This function copies N bytes from the memory region pointed to by IN to
the memory region pointed to by OUT.

   This function is implemented in term of `memmove'.

*Portability*
`bcopy' requires no supporting OS subroutines.

6.3 `bzero'--initialize memory to zero
======================================

*Synopsis*
     #include <string.h>
     void bzero(void *B, size_t LENGTH);
   *Description*
`bzero' initializes LENGTH bytes of memory, starting at address B, to
zero.

*Returns*
`bzero' does not return a result.

*Portability*
`bzero' is in the Berkeley Software Distribution.  Neither ANSI C nor
the System V Interface Definition (Issue 2) require `bzero'.

   `bzero' requires no supporting OS subroutines.

6.4 `index'--search for character in string
===========================================

*Synopsis*
     #include <string.h>
     char * index(const char *STRING, int C);
   *Description*
This function finds the first occurence of C (converted to a char) in
the string pointed to by STRING (including the terminating null
character).

   This function is identical to `strchr'.

*Returns*
Returns a pointer to the located character, or a null pointer if C does
not occur in STRING.

*Portability*
`index' requires no supporting OS subroutines.

6.5 `memccpy'--copy memory regions with end-token check
=======================================================

*Synopsis*
     #include <string.h>
     void* memccpy(void *OUT, const void *IN,
         int ENDCHAR, size_t N);
   *Description*
This function copies up to N bytes from the memory region pointed to by
IN to the memory region pointed to by OUT.  If a byte matching the
ENDCHAR is encountered, the byte is copied and copying stops.

   If the regions overlap, the behavior is undefined.

*Returns*
`memccpy' returns a pointer to the first byte following the ENDCHAR in
the OUT region.  If no byte matching ENDCHAR was copied, then `NULL' is
returned.

*Portability*
`memccpy' is a GNU extension.

   `memccpy' requires no supporting OS subroutines.

6.6 `memchr'--find character in memory
======================================

*Synopsis*
     #include <string.h>
     void *memchr(const void *SRC, int C, size_t LENGTH);
   *Description*
This function searches memory starting at `*SRC' for the character C.
The search only ends with the first occurrence of C, or after LENGTH
characters; in particular, `NUL' does not terminate the search.

*Returns*
If the character C is found within LENGTH characters of `*SRC', a
pointer to the character is returned. If C is not found, then `NULL' is
returned.

*Portability*
`memchr' is ANSI C.

   `memchr' requires no supporting OS subroutines.

6.7 `memcmp'--compare two memory areas
======================================

*Synopsis*
     #include <string.h>
     int memcmp(const void *S1, const void *S2, size_t N);
   *Description*
This function compares not more than N characters of the object pointed
to by S1 with the object pointed to by S2.

*Returns*
The function returns an integer greater than, equal to or less than
zero 	according to whether the object pointed to by S1 is greater
than, equal to or less than the object pointed to by S2.

*Portability*
`memcmp' is ANSI C.

   `memcmp' requires no supporting OS subroutines.

6.8 `memcpy'--copy memory regions
=================================

*Synopsis*
     #include <string.h>
     void* memcpy(void *OUT, const void *IN, size_t N);
   *Description*
This function copies N bytes from the memory region pointed to by IN to
the memory region pointed to by OUT.

   If the regions overlap, the behavior is undefined.

*Returns*
`memcpy' returns a pointer to the first byte of the OUT region.

*Portability*
`memcpy' is ANSI C.

   `memcpy' requires no supporting OS subroutines.

6.9 `memmem'--find memory segment
=================================

*Synopsis*
     #include <string.h>
     char *memmem(const void *S1, size_t L1, const void *S2,
         size_t L2);
   *Description*
Locates the first occurrence in the memory region pointed to by S1 with
length L1 of the sequence of bytes pointed to by S2 of length L2.  If
you already know the lengths of your haystack and needle, `memmem' can
be much faster than `strstr'.

*Returns*
Returns a pointer to the located segment, or a null pointer if S2 is
not found. If L2 is 0, S1 is returned.

*Portability*
`memmem' is a newlib extension.

   `memmem' requires no supporting OS subroutines.

6.10 `memmove'--move possibly overlapping memory
================================================

*Synopsis*
     #include <string.h>
     void *memmove(void *DST, const void *SRC, size_t LENGTH);
   *Description*
This function moves LENGTH characters from the block of memory starting
at `*SRC' to the memory starting at `*DST'. `memmove' reproduces the
characters correctly at `*DST' even if the two areas overlap.

*Returns*
The function returns DST as passed.

*Portability*
`memmove' is ANSI C.

   `memmove' requires no supporting OS subroutines.

6.11 `mempcpy'--copy memory regions and return end pointer
==========================================================

*Synopsis*
     #include <string.h>
     void* mempcpy(void *OUT, const void *IN, size_t N);
   *Description*
This function copies N bytes from the memory region pointed to by IN to
the memory region pointed to by OUT.

   If the regions overlap, the behavior is undefined.

*Returns*
`mempcpy' returns a pointer to the byte following the last byte copied
to the OUT region.

*Portability*
`mempcpy' is a GNU extension.

   `mempcpy' requires no supporting OS subroutines.

6.12 `memset'--set an area of memory
====================================

*Synopsis*
     #include <string.h>
     void *memset(void *DST, int C, size_t LENGTH);
   *Description*
This function converts the argument C into an unsigned char and fills
the first LENGTH characters of the array pointed to by DST to the value.

*Returns*
`memset' returns the value of DST.

*Portability*
`memset' is ANSI C.

   `memset' requires no supporting OS subroutines.

6.13 `rindex'--reverse search for character in string
=====================================================

*Synopsis*
     #include <string.h>
     char * rindex(const char *STRING, int C);
   *Description*
This function finds the last occurence of C (converted to a char) in
the string pointed to by STRING (including the terminating null
character).

   This function is identical to `strrchr'.

*Returns*
Returns a pointer to the located character, or a null pointer if C does
not occur in STRING.

*Portability*
`rindex' requires no supporting OS subroutines.

6.14 `stpcpy'--copy string returning a pointer to its end
=========================================================

*Synopsis*
     #include <string.h>
     char *stpcpy(char *DST, const char *SRC);
   *Description*
`stpcpy' copies the string pointed to by SRC (including the terminating
null character) to the array pointed to by DST.

*Returns*
This function returns a pointer to the end of the destination string,
thus pointing to the trailing '\0'.

*Portability*
`stpcpy' is a GNU extension, candidate for inclusion into POSIX/SUSv4.

   `stpcpy' requires no supporting OS subroutines.

6.15 `stpncpy'--counted copy string returning a pointer to its end
==================================================================

*Synopsis*
     #include <string.h>
     char *stpncpy(char *DST, const char *SRC, size_t LENGTH);
   *Description*
`stpncpy' copies not more than LENGTH characters from the the string
pointed to by SRC (including the terminating null character) to the
array pointed to by DST.  If the string pointed to by SRC is shorter
than LENGTH characters, null characters are appended to the destination
array until a total of LENGTH characters have been written.

*Returns*
This function returns a pointer to the end of the destination string,
thus pointing to the trailing '\0', or, if the destination string is
not null-terminated, pointing to dst + n.

*Portability*
`stpncpy' is a GNU extension, candidate for inclusion into POSIX/SUSv4.

   `stpncpy' requires no supporting OS subroutines.

6.16 `strcasecmp'--case-insensitive character string compare
============================================================

*Synopsis*
     #include <string.h>
     int strcasecmp(const char *A, const char *B);
   *Description*
`strcasecmp' compares the string at A to the string at B in a
case-insensitive manner.

*Returns*
If `*A' sorts lexicographically after `*B' (after both are converted to
lowercase), `strcasecmp' returns a number greater than zero.  If the
two strings match, `strcasecmp' returns zero.  If `*A' sorts
lexicographically before `*B', `strcasecmp' returns a number less than
zero.

*Portability*
`strcasecmp' is in the Berkeley Software Distribution.

   `strcasecmp' requires no supporting OS subroutines. It uses
tolower() from elsewhere in this library.

6.17 `strcasestr'--case-insensitive character string search
===========================================================

*Synopsis*
     #include <string.h>
     char *strcasestr(const char *S, const char *FIND);
   *Description*
`strcasestr' searchs the string S for the first occurrence of the
sequence FIND.  `strcasestr' is identical to `strstr' except the search
is case-insensitive.

*Returns*
A pointer to the first case-insensitive occurrence of the sequence FIND
or `NULL' if no match was found.

*Portability*
`strcasestr' is in the Berkeley Software Distribution.

   `strcasestr' requires no supporting OS subroutines. It uses
tolower() from elsewhere in this library.

6.18 `strcat'--concatenate strings
==================================

*Synopsis*
     #include <string.h>
     char *strcat(char *DST, const char *SRC);
   *Description*
`strcat' appends a copy of the string pointed to by SRC (including the
terminating null character) to the end of the string pointed to by DST.
The initial character of SRC overwrites the null character at the end
of DST.

*Returns*
This function returns the initial value of DST

*Portability*
`strcat' is ANSI C.

   `strcat' requires no supporting OS subroutines.

6.19 `strchr'--search for character in string
=============================================

*Synopsis*
     #include <string.h>
     char * strchr(const char *STRING, int C);
   *Description*
This function finds the first occurence of C (converted to a char) in
the string pointed to by STRING (including the terminating null
character).

*Returns*
Returns a pointer to the located character, or a null pointer if C does
not occur in STRING.

*Portability*
`strchr' is ANSI C.

   `strchr' requires no supporting OS subroutines.

6.20 `strcmp'--character string compare
=======================================

*Synopsis*
     #include <string.h>
     int strcmp(const char *A, const char *B);
   *Description*
`strcmp' compares the string at A to the string at B.

*Returns*
If `*A' sorts lexicographically after `*B', `strcmp' returns a number
greater than zero.  If the two strings match, `strcmp' returns zero.
If `*A' sorts lexicographically before `*B', `strcmp' returns a number
less than zero.

*Portability*
`strcmp' is ANSI C.

   `strcmp' requires no supporting OS subroutines.

6.21 `strcoll'--locale-specific character string compare
========================================================

*Synopsis*
     #include <string.h>
     int strcoll(const char *STRA, const char * STRB);
   *Description*
`strcoll' compares the string pointed to by STRA to the string pointed
to by STRB, using an interpretation appropriate to the current
`LC_COLLATE' state.

*Returns*
If the first string is greater than the second string, `strcoll'
returns a number greater than zero.  If the two strings are equivalent,
`strcoll' returns zero.  If the first string is less than the second
string, `strcoll' returns a number less than zero.

*Portability*
`strcoll' is ANSI C.

   `strcoll' requires no supporting OS subroutines.

6.22 `strcpy'--copy string
==========================

*Synopsis*
     #include <string.h>
     char *strcpy(char *DST, const char *SRC);
   *Description*
`strcpy' copies the string pointed to by SRC (including the terminating
null character) to the array pointed to by DST.

*Returns*
This function returns the initial value of DST.

*Portability*
`strcpy' is ANSI C.

   `strcpy' requires no supporting OS subroutines.

6.23 `strcspn'--count characters not in string
==============================================

*Synopsis*
     size_t strcspn(const char *S1, const char *S2);
   *Description*
This function computes the length of the initial part of the string
pointed to by S1 which consists entirely of characters NOT from the
string pointed to by S2 (excluding the terminating null character).

*Returns*
`strcspn' returns the length of the substring found.

*Portability*
`strcspn' is ANSI C.

   `strcspn' requires no supporting OS subroutines.

6.24 `strerror'--convert error number to string
===============================================

*Synopsis*
     #include <string.h>
     char *strerror(int ERRNUM);
   *Description*
`strerror' converts the error number ERRNUM into a string.  The value
of ERRNUM is usually a copy of `errno'.  If `errnum' is not a known
error number, the result points to an empty string.

   This implementation of `strerror' prints out the following strings
for each of the values defined in ``errno.h'':

`E2BIG'
     Arg list too long

`EACCES'
     Permission denied

`EADDRINUSE'
     Address already in use

`EADV'
     Advertise error

`EAFNOSUPPORT'
     Address family not supported by protocol family

`EAGAIN'
     No more processes

`EALREADY'
     Socket already connected

`EBADF'
     Bad file number

`EBADMSG'
     Bad message

`EBUSY'
     Device or resource busy

`ECHILD'
     No children

`ECOMM'
     Communication error

`ECONNABORTED'
     Software caused connection abort

`ECONNREFUSED'
     Connection refused

`EDEADLK'
     Deadlock

`EDESTADDRREQ'
     Destination address required

`EEXIST'
     File exists

`EDOM'
     Math argument

`EFAULT'
     Bad address

`EFBIG'
     File too large

`EHOSTDOWN'
     Host is down

`EHOSTUNREACH'
     Host is unreachable

`EIDRM'
     Identifier removed

`EINPROGRESS'
     Connection already in progress

`EINTR'
     Interrupted system call

`EINVAL'
     Invalid argument

`EIO'
     I/O error

`EISCONN'
     Socket is already connected

`EISDIR'
     Is a directory

`ELIBACC'
     Cannot access a needed shared library

`ELIBBAD'
     Accessing a corrupted shared library

`ELIBEXEC'
     Cannot exec a shared library directly

`ELIBMAX'
     Attempting to link in more shared libraries than system limit

`ELIBSCN'
     `.lib' section in a.out corrupted

`EMFILE'
     Too many open files

`EMLINK'
     Too many links

`EMSGSIZE'
     Message too long

`EMULTIHOP'
     Multihop attempted

`ENAMETOOLONG'
     File or path name too long

`ENETDOWN'
     Network interface not configured

`ENETUNREACH'
     Network is unreachable

`ENFILE'
     Too many open files in system

`ENODEV'
     No such device

`ENOENT'
     No such file or directory

`ENOEXEC'
     Exec format error

`ENOLCK'
     No lock

`ENOLINK'
     Virtual circuit is gone

`ENOMEM'
     Not enough space

`ENOMSG'
     No message of desired type

`ENONET'
     Machine is not on the network

`ENOPKG'
     No package

`ENOPROTOOPT'
     Protocol not available

`ENOSPC'
     No space left on device

`ENOSR'
     No stream resources

`ENOSTR'
     Not a stream

`ENOSYS'
     Function not implemented

`ENOTBLK'
     Block device required

`ENOTCONN'
     Socket is not connected

`ENOTDIR'
     Not a directory

`ENOTEMPTY'
     Directory not empty

`ENOTSOCK'
     Socket operation on non-socket

`ENOTSUP'
     Not supported

`ENOTTY'
     Not a character device

`ENXIO'
     No such device or address

`EPERM'
     Not owner

`EPIPE'
     Broken pipe

`EPROTO'
     Protocol error

`EPROTOTYPE'
     Protocol wrong type for socket

`EPROTONOSUPPORT'
     Unknown protocol

`ERANGE'
     Result too large

`EREMOTE'
     Resource is remote

`EROFS'
     Read-only file system

`ESHUTDOWN'
     Can't send after socket shutdown

`ESOCKTNOSUPPORT'
     Socket type not supported

`ESPIPE'
     Illegal seek

`ESRCH'
     No such process

`ESRMNT'
     Srmount error

`ETIME'
     Stream ioctl timeout

`ETIMEDOUT'
     Connection timed out

`ETXTBSY'
     Text file busy

`EXDEV'
     Cross-device link

`ECANCELED'
     Operation canceled

`ENOTRECOVERABLE'
     State not recoverable

`EOWNERDEAD'
     Previous owner died

`ESTRPIPE'
     Strings pipe error

*Returns*
This function returns a pointer to a string.  Your application must not
modify that string.

*Portability*
ANSI C requires `strerror', but does not specify the strings used for
each error number.

   Although this implementation of `strerror' is reentrant, ANSI C
declares that subsequent calls to `strerror' may overwrite the result
string; therefore portable code cannot depend on the reentrancy of this
subroutine.

   This implementation of `strerror' provides for user-defined
extensibility.  `errno.h' defines __ELASTERROR, which can be used as a
base for user-defined error values.  If the user supplies a routine
named `_user_strerror', and ERRNUM passed to `strerror' does not match
any of the supported values, `_user_strerror' is called with ERRNUM as
its argument.

   `_user_strerror' takes one argument of type INT, and returns a
character pointer.  If ERRNUM is unknown to `_user_strerror',
`_user_strerror' returns NULL.  The default `_user_strerror' returns
NULL for all input values.

   `strerror' requires no supporting OS subroutines.

6.25 `strerror_r'--convert error number to string and copy to buffer
====================================================================

*Synopsis*
     #include <string.h>
     char *strerror_r(int ERRNUM, char *BUFFER, size_t N);
   *Description*
`strerror_r' converts the error number ERRNUM into a string and copies
the result into the supplied BUFFER for a length up to N, including the
NUL terminator. The value of ERRNUM is usually a copy of `errno'.  If
`errnum' is not a known error number, the result is the empty string.

   See `strerror' for how strings are mapped to `errnum'.

*Returns*
This function returns a pointer to a string.  Your application must not
modify that string.

*Portability*
`strerror_r' is a GNU extension.

   `strerror_r' requires no supporting OS subroutines.

6.26 `strlen'--character string length
======================================

*Synopsis*
     #include <string.h>
     size_t strlen(const char *STR);
   *Description*
The `strlen' function works out the length of the string starting at
`*STR' by counting chararacters until it reaches a `NULL' character.

*Returns*
`strlen' returns the character count.

*Portability*
`strlen' is ANSI C.

   `strlen' requires no supporting OS subroutines.

6.27 `strlwr'--force string to lowercase
========================================

*Synopsis*
     #include <string.h>
     char *strlwr(char *A);
   *Description*
`strlwr' converts each character in the string at A to lowercase.

*Returns*
`strlwr' returns its argument, A.

*Portability*
`strlwr' is not widely portable.

   `strlwr' requires no supporting OS subroutines.

6.28 `strncasecmp'--case-insensitive character string compare
=============================================================

*Synopsis*
     #include <string.h>
     int strncasecmp(const char *A, const char * B, size_t LENGTH);
   *Description*
`strncasecmp' compares up to LENGTH characters from the string at A to
the string at B in a case-insensitive manner.

*Returns*
If `*A' sorts lexicographically after `*B' (after both are converted to
lowercase), `strncasecmp' returns a number greater than zero.  If the
two strings are equivalent, `strncasecmp' returns zero.  If `*A' sorts
lexicographically before `*B', `strncasecmp' returns a number less than
zero.

*Portability*
`strncasecmp' is in the Berkeley Software Distribution.

   `strncasecmp' requires no supporting OS subroutines. It uses
tolower() from elsewhere in this library.

6.29 `strncat'--concatenate strings
===================================

*Synopsis*
     #include <string.h>
     char *strncat(char *DST, const char *SRC, size_t LENGTH);
   *Description*
`strncat' appends not more than LENGTH characters from the string
pointed to by SRC (including the	terminating null character) to
the end of the string pointed to by DST.  The initial character of SRC
overwrites the null character at the end of DST.  A terminating null
character is always appended to the result

*Warnings*
Note that a null is always appended, so that if the copy is limited by
the LENGTH argument, the number of characters appended to DST is `n +
1'.

*Returns*
This function returns the initial value of DST

*Portability*
`strncat' is ANSI C.

   `strncat' requires no supporting OS subroutines.

6.30 `strncmp'--character string compare
========================================

*Synopsis*
     #include <string.h>
     int strncmp(const char *A, const char * B, size_t LENGTH);
   *Description*
`strncmp' compares up to LENGTH characters from the string at A to the
string at B.

*Returns*
If `*A' sorts lexicographically after `*B', `strncmp' returns a number
greater than zero.  If the two strings are equivalent, `strncmp'
returns zero.  If `*A' sorts lexicographically before `*B', `strncmp'
returns a number less than zero.

*Portability*
`strncmp' is ANSI C.

   `strncmp' requires no supporting OS subroutines.

6.31 `strncpy'--counted copy string
===================================

*Synopsis*
     #include <string.h>
     char *strncpy(char *DST, const char *SRC, size_t LENGTH);
   *Description*
`strncpy' copies not more than LENGTH characters from the the string
pointed to by SRC (including the terminating null character) to the
array pointed to by DST.  If the string pointed to by SRC is shorter
than LENGTH characters, null characters are appended to the destination
array until a total of LENGTH characters have been written.

*Returns*
This function returns the initial value of DST.

*Portability*
`strncpy' is ANSI C.

   `strncpy' requires no supporting OS subroutines.

6.32 `strnlen'--character string length
=======================================

*Synopsis*
     #include <string.h>
     size_t strnlen(const char *STR, size_t N);
   *Description*
The `strnlen' function works out the length of the string starting at
`*STR' by counting chararacters until it reaches a NUL character or the
maximum: N number of characters have been inspected.

*Returns*
`strnlen' returns the character count or N.

*Portability*
`strnlen' is a GNU extension.

   `strnlen' requires no supporting OS subroutines.

6.33 `strpbrk'--find characters in string
=========================================

*Synopsis*
     #include <string.h>
     char *strpbrk(const char *S1, const char *S2);
   *Description*
This function locates the first occurence in the string pointed to by
S1 of any character in string pointed to by S2 (excluding the
terminating null character).

*Returns*
`strpbrk' returns a pointer to the character found in S1, or a null
pointer if no character from S2 occurs in S1.

*Portability*
`strpbrk' requires no supporting OS subroutines.

6.34 `strrchr'--reverse search for character in string
======================================================

*Synopsis*
     #include <string.h>
     char * strrchr(const char *STRING, int C);
   *Description*
This function finds the last occurence of C (converted to a char) in
the string pointed to by STRING (including the terminating null
character).

*Returns*
Returns a pointer to the located character, or a null pointer if C does
not occur in STRING.

*Portability*
`strrchr' is ANSI C.

   `strrchr' requires no supporting OS subroutines.

6.35 `strspn'--find initial match
=================================

*Synopsis*
     #include <string.h>
     size_t strspn(const char *S1, const char *S2);
   *Description*
This function computes the length of the initial segment of the string
pointed to by S1 which consists entirely of characters from the string
pointed to by S2 (excluding the terminating null character).

*Returns*
`strspn' returns the length of the segment found.

*Portability*
`strspn' is ANSI C.

   `strspn' requires no supporting OS subroutines.

6.36 `strstr'--find string segment
==================================

*Synopsis*
     #include <string.h>
     char *strstr(const char *S1, const char *S2);
   *Description*
Locates the first occurrence in the string pointed to by S1 of the
sequence of characters in the string pointed to by S2 (excluding the
terminating null character).

*Returns*
Returns a pointer to the located string segment, or a null pointer if
the string S2 is not found. If S2 points to a string with zero length,
S1 is returned.

*Portability*
`strstr' is ANSI C.

   `strstr' requires no supporting OS subroutines.

6.37 `strtok', `strtok_r', `strsep'--get next token from a string
=================================================================

*Synopsis*
     #include <string.h>
     char *strtok(char *SOURCE, const char *DELIMITERS)
     char *strtok_r(char *SOURCE, const char *DELIMITERS,
         char **LASTS)
     char *strsep(char **SOURCE_PTR, const char *DELIMITERS)
   *Description*
The `strtok' function is used to isolate sequential tokens in a
null-terminated string, `*SOURCE'. These tokens are delimited in the
string by at least one of the characters in `*DELIMITERS'.  The first
time that `strtok' is called, `*SOURCE' should be specified; subsequent
calls, wishing to obtain further tokens from the same string, should
pass a null pointer instead.  The separator string, `*DELIMITERS', must
be supplied each time and may change between calls.

   The `strtok' function returns a pointer to the beginning of each
subsequent token in the string, after replacing the separator character
itself with a null character.  When no more tokens remain, a null
pointer is returned.

   The `strtok_r' function has the same behavior as `strtok', except a
pointer to placeholder `*LASTS' must be supplied by the caller.

   The `strsep' function is similar in behavior to `strtok', except a
pointer to the string pointer must be supplied `SOURCE_PTR' and the
function does not skip leading delimiters.  When the string starts with
a delimiter, the delimiter is changed to the null character and the
empty string is returned.  Like `strtok_r' and `strtok', the
`*SOURCE_PTR' is updated to the next character following the last
delimiter found or NULL if the end of string is reached with no more
delimiters.

*Returns*
`strtok', `strtok_r', and `strsep' all return a pointer to the next
token, or `NULL' if no more tokens can be found.  For `strsep', a token
may be the empty string.

*Portability*
`strtok' is ANSI C.  `strtok_r' is POSIX.  `strsep' is a BSD extension.

   `strtok', `strtok_r', and `strsep' require no supporting OS
subroutines.

6.38 `strupr'--force string to uppercase
========================================

*Synopsis*
     #include <string.h>
     char *strupr(char *A);
   *Description*
`strupr' converts each character in the string at A to uppercase.

*Returns*
`strupr' returns its argument, A.

*Portability*
`strupr' is not widely portable.

   `strupr' requires no supporting OS subroutines.

6.39 `strxfrm'--transform string
================================

*Synopsis*
     #include <string.h>
     size_t strxfrm(char *S1, const char *S2, size_t N);
   *Description*
This function transforms the string pointed to by S2 and places the
resulting string into the array pointed to by S1. The transformation is
such that if the `strcmp' function is applied to the two transformed
strings, it returns a value greater than, equal to, or less than zero,
correspoinding to the result of a `strcoll' function applied to the
same two original strings.

   No more than N characters are placed into the resulting array
pointed to by S1, including the terminating null character. If N is
zero, S1 may be a null pointer. If copying takes place between objects
that overlap, the behavior is undefined.

   With a C locale, this function just copies.

*Returns*
The `strxfrm' function returns the length of the transformed string
(not including the terminating null character). If the value returned
is N or more, the contents of the array pointed to by S1 are
indeterminate.

*Portability*
`strxfrm' is ANSI C.

   `strxfrm' requires no supporting OS subroutines.

6.40 `swab'--swap adjacent bytes
================================

*Synopsis*
     #include <unistd.h>
     void swab(const void *IN, void *OUT, ssize_t N);
   *Description*
This function copies N bytes from the memory region pointed to by IN to
the memory region pointed to by OUT, exchanging adjacent even and odd
bytes.

*Portability*
`swab' requires no supporting OS subroutines.

6.41 `wcscasecmp'--case-insensitive wide character string compare
=================================================================

*Synopsis*
     #include <wchar.h>
     int wcscasecmp(const wchar_t *A, const wchar_t *B);
   *Description*
`wcscasecmp' compares the wide character string at A to the wide
character string at B in a case-insensitive manner.

*Returns*
If `*A' sorts lexicographically after `*B' (after both are converted to
uppercase), `wcscasecmp' returns a number greater than zero.  If the
two strings match, `wcscasecmp' returns zero.  If `*A' sorts
lexicographically before `*B', `wcscasecmp' returns a number less than
zero.

*Portability*
POSIX-1.2008

   `wcscasecmp' requires no supporting OS subroutines. It uses
tolower() from elsewhere in this library.

6.42 `wcsdup'--wide character string duplicate
==============================================

*Synopsis*
     #include <wchar.h>
     wchar_t *wcsdup(const wchar_t *STR);

     #include <wchar.h>
     wchar_t *_wcsdup_r(struct _reent *PTR, const wchar_t *STR);
   *Description*
`wcsdup' allocates a new wide character string using `malloc', and
copies the content of the argument STR into the newly allocated string,
thus making a copy of STR.

*Returns*
`wcsdup' returns a pointer to the copy of STR if enough memory for the
copy was available.  Otherwise it returns NULL and errno is set to
ENOMEM.

*Portability*
POSIX-1.2008

6.43 `wcsncasecmp'--case-insensitive wide character string compare
==================================================================

*Synopsis*
     #include <wchar.h>
     int wcsncasecmp(const wchar_t *A, const wchar_t * B, size_t LENGTH);
   *Description*
`wcsncasecmp' compares up to LENGTH wide characters from the string at
A to the string at B in a case-insensitive manner.

*Returns*
If `*A' sorts lexicographically after `*B' (after both are converted to
uppercase), `wcsncasecmp' returns a number greater than zero.  If the
two strings are equivalent, `wcsncasecmp' returns zero.  If `*A' sorts
lexicographically before `*B', `wcsncasecmp' returns a number less than
zero.

*Portability*
POSIX-1.2008

   `wcsncasecmp' requires no supporting OS subroutines. It uses
tolower() from elsewhere in this library.

7 Wide Character Strings (`wchar.h')
************************************

This chapter describes wide-character string-handling functions and
managing areas of memory containing wide characters.  The corresponding
declarations are in `wchar.h'.

7.1 `wmemchr'--find a wide character in memory
==============================================

*Synopsis*
     #include <wchar.h>
     wchar_t	*wmemchr(const wchar_t *S, wchar_t C, size_t N);
   *Description*
The `wmemchr' function locates the first occurrence of C in the initial
N wide characters of the object pointed to be S. This function is not
affected by locale and all wchar_t values are treated identically.  The
null wide character and wchar_t values not corresponding to valid
characters are not treated specially.

   If N is zero, S must be a valid pointer and the function behaves as
if no valid occurrence of C is found.

*Returns*
The `wmemchr' function returns a pointer to the located wide character,
or a null pointer if the wide character does not occur in the object.

*Portability*
`wmemchr' is ISO/IEC 9899/AMD1:1995 (ISO C).

   No supporting OS subroutines are required.

7.2 `wmemcmp'--compare wide characters in memory
================================================

*Synopsis*
     #include <wchar.h>
     int wmemcmp(const wchar_t *S1, const wchar_t *S2, size_t N);
   *Description*
The `wmemcmp' function compares the first N wide characters of the
object pointed to by S1 to the first N wide characters of the object
pointed to by S2. This function is not affected by locale and all
wchar_t values are treated identically. The null wide character and
wchar_t values not corresponding to valid characters are not treated
specially.

   If N is zero, S1 and S2 must be a valid pointers and the function
behaves as if the two objects compare equal.

*Returns*
The `wmemcmp' function returns an integer greater than, equal to, or
less than zero, accordingly as the object pointed to by S1 is greater
than, equal to, or less than the object pointed to by S2.

*Portability*
`wmemcmp' is ISO/IEC 9899/AMD1:1995 (ISO C).

   No supporting OS subroutines are required.

7.3 `wmemcpy'--copy wide characters in memory
=============================================

*Synopsis*
     #include <wchar.h>
     wchar_t *wmemcpy(wchar_t *D, const wchar_t *S, size_t N);
   *Description*
The `wmemcpy' function copies N wide characters from the object pointed
to by S to the object pointed to be D. This function is not affected by
locale and all wchar_t values are treated identically.  The null wide
character and wchar_t values not corresponding to valid characters are
not treated specially.

   If N is zero, D and S must be a valid pointers, and the function
copies zero wide characters.

*Returns*
The `wmemcpy' function returns the value of D.

*Portability*
`wmemcpy' is ISO/IEC 9899/AMD1:1995 (ISO C).

   No supporting OS subroutines are required.

7.4 `wmemmove'--copy wide characters in memory with overlapping areas
=====================================================================

*Synopsis*
     #include <wchar.h>
     wchar_t *wmemmove(wchar_t *D, const wchar_t *S, size_t N);
   *Description*
The `wmemmove' function copies N wide characters from the object
pointed to by S to the object pointed to by D. Copying takes place as
if the N wide characters from the object pointed to by S are first
copied into a temporary array of N wide characters that does not
overlap the objects pointed to by D or S, and then the N wide
characters from the temporary array are copied into the object pointed
to by D.

   This function is not affected by locale and all wchar_t values are
treated identically. The null wide character and wchar_t values not
corresponding to valid characters are not treated specially.

   If N is zero, D and S must be a valid pointers, and the function
copies zero wide characters.

*Returns*
The `wmemmove' function returns the value of D.

*Portability*
`wmemmove' is ISO/IEC 9899/AMD1:1995 (ISO C).

   No supporting OS subroutines are required.

7.5 `wmemset'--set wide characters in memory
============================================

*Synopsis*
     #include <wchar.h>
     wchar_t *wmemset(wchar_t *S, wchar_t C, size_t N);
   *Description*
The `wmemset' function copies the value of C into each of the first N
wide characters of the object pointed to by S.  This function is not
affected by locale and all wchar_t values are treated identically.  The
null wide character and wchar_t values not corresponding to valid
characters are not treated specially.

   If N is zero, S must be a valid pointer and the function copies zero
wide characters.

*Returns*
The `wmemset' function returns the value of S.

*Portability*
`wmemset' is ISO/IEC 9899/AMD1:1995 (ISO C).

   No supporting OS subroutines are required.

7.6 `wcscat'--concatenate two wide-character strings
====================================================

*Synopsis*
     #include <wchar.h>
     wchar_t *wcscat(wchar_t *S1, const wchar_t *S2);
   *Description*
The `wcscat' function appends a copy of the wide-character string
pointed to by S2 (including the terminating null wide-character code)
to the end of the wide-character string pointed to by S1.  The initial
wide-character code of S2 overwrites the null wide-character code at
the end of S1. If copying takes place between objects that overlap, the
behaviour is undefined.

*Returns*
The `wcscat' function returns S1; no return value is reserved to
indicate an error.

*Portability*
`wcscat' is ISO/IEC 9899/AMD1:1995 (ISO C).

   No supporting OS subroutines are required.

7.7 `wcschr'--wide-character string scanning operation
======================================================

*Synopsis*
     #include <wchar.h>
     wchar_t *wcschr(const wchar_t *S, wchar_t C);
   *Description*
The `wcschr' function locates the first occurrence of C in the
wide-character string pointed to by S. The value of C must be a
character representable as a type wchar_t and must be a wide-character
code corresponding to a valid character in the current locale.  The
terminating null wide-character string.

*Returns*
Upon completion, `wcschr' returns a pointer to the wide-character code,
or a null pointer if the wide-character code is not found.

*Portability*
`wcschr' is ISO/IEC 9899/AMD1:1995 (ISO C).

   No supporting OS subroutines are required.

7.8 `wcscmp'--compare two wide-character strings
================================================

*Synopsis*
     #include <wchar.h>
     int wcscmp(const wchar_t *S1, *S2);
   *Description*
The `wcscmp' function compares the wide-character string pointed to by
S1 to the wide-character string pointed to by S2.

   The sign of a non-zero return value is determined by the sign of the
difference between the values of the first pair of wide-character codes
that differ in the objects being compared.

*Returns*
Upon completion, `wcscmp' returns an integer greater than, equal to or
less than 0, if the wide-character string pointed to by S1 is greater
than, equal to or less than the wide-character string pointed to by S2
respectively.

*Portability*
`wcscmp' is ISO/IEC 9899/AMD1:1995 (ISO C).

   No supporting OS subroutines are required.

7.9 `wcscoll'--locale-specific wide-character string compare
============================================================

*Synopsis*
     #include <wchar.h>
     int wcscoll(const wchar_t *STRA, const wchar_t * STRB);
   *Description*
`wcscoll' compares the wide-character string pointed to by STRA to the
wide-character string pointed to by STRB, using an interpretation
appropriate to the current `LC_COLLATE' state.

   The current implementation of `wcscoll' simply uses `wcscmp' and
does not support any language-specific sorting.

*Returns*
If the first string is greater than the second string, `wcscoll'
returns a number greater than zero.  If the two strings are equivalent,
`wcscoll' returns zero.  If the first string is less than the second
string, `wcscoll' returns a number less than zero.

*Portability*
`wcscoll' is ISO/IEC 9899/AMD1:1995 (ISO C).

7.10 `wcscpy'--copy a wide-character string
===========================================

*Synopsis*
     #include <wchar.h>
     wchar_t *wcscpy(wchar_t *S1, const wchar_t *,S2);
   *Description*
The `wcscpy' function copies the wide-character string pointed to by S2
(including the terminating null wide-character code) into the array
pointed to by S1. If copying takes place between objects that overlap,
the behaviour is undefined.

*Returns*
The `wcscpy' function returns S1; no return value is reserved to
indicate an error.

*Portability*
`wcscpy' is ISO/IEC 9899/AMD1:1995 (ISO C).

   No supporting OS subroutines are required.

7.11 `wcpcpy'--copy a wide-character string returning a pointer to its end
==========================================================================

*Synopsis*
     #include <wchar.h>
     wchar_t *wcpcpy(wchar_t *S1, const wchar_t *,S2);
   *Description*
The `wcpcpy' function copies the wide-character string pointed to by S2
(including the terminating null wide-character code) into the array
pointed to by S1. If copying takes place between objects that overlap,
the behaviour is undefined.

*Returns*
This function returns a pointer to the end of the destination string,
thus pointing to the trailing '\0'.

*Portability*
`wcpcpy' is a GNU extension.

   No supporting OS subroutines are required.

7.12 `wcscspn'--get length of a complementary wide substring
============================================================

*Synopsis*
     #include <wchar.h>
     size_t wcscspn(const wchar_t *S, wchar_t *SET);
   *Description*
The `wcscspn' function computes the length of the maximum initial
segment of the wide-character string pointed to by S which consists
entirely of wide-character codes not from the wide-character string
pointed to by SET.

*Returns*
The `wcscspn' function returns the length of the initial substring of
S1; no return value is reserved to indicate an error.

*Portability*
`wcscspn' is ISO/IEC 9899/AMD1:1995 (ISO C).

   No supporting OS subroutines are required.

7.13 `wcsftime'-convert date and time to a formatted wide-character string
==========================================================================

*Synopsis*
     #include <time.h>
     #include <wchar.h>
     size_t wcsftime(wchar_t *S, size_t MAXSIZE,
         const wchar_t *FORMAT, const struct tm *TIMP);
   *Description*
`wcsftime' is equivalent to `strftime', except that:
   * The argument s points to the initial element of an array of wide
     characters into which the generated output is to be placed.

   * The argument maxsize indicates the limiting number of wide
     characters.

   * The argument format is a wide-character string and the conversion
     specifiers are replaced by corresponding sequences of wide
     characters.

   * The return value indicates the number of wide characters.

   (The difference in all of the above being wide characters versus
regular characters.)  See `strftime' for the details of the format
specifiers.

*Returns*
When the formatted time takes up no more than MAXSIZE wide characters,
the result is the length of the formatted wide string.  Otherwise, if
the formatting operation was abandoned due to lack of room, the result
is `0', and the wide-character string starting at S corresponds to just
those parts of `*FORMAT' that could be completely filled in within the
MAXSIZE limit.

*Portability*
C99 and POSIX require `wcsftime', but do not specify the contents of
`*S' when the formatted string would require more than MAXSIZE
characters.  Unrecognized specifiers and fields of `timp' that are out
of range cause undefined results.  Since some formats expand to 0
bytes, it is wise to set `*S' to a nonzero value beforehand to
distinguish between failure and an empty string.  This implementation
does not support `s' being NULL, nor overlapping `s' and `format'.

   `wcsftime' requires no supporting OS subroutines.

*See Also*
`strftime'

7.14 `wcslcat'--concatenate wide-character strings to specified length
======================================================================

*Synopsis*
     #include <wchar.h>
     size_t wcslcat(wchar_t *DST, const wchar_t *SRC, size_t SIZ);
   *Description*
The `wcslcat' function appends wide characters from SRC to end of the
DST wide-character string so that the resultant wide-character string
is not more than SIZ wide characters including the terminating null
wide-character code.  A terminating null wide character is always added
unless SIZ is 0.  Thus, the maximum number of wide characters that can
be appended from SRC is SIZ - 1. If copying takes place between objects
that overlap, the behaviour is undefined.

*Returns*
Wide-character string length of initial DST plus the wide-character
string length of SRC (does not include terminating null
wide-characters).  If the return value is greater than or equal to SIZ,
then truncation occurred and not all wide characters from SRC were
appended.

*Portability*
No supporting OS subroutines are required.

7.15 `wcslcpy'--copy a wide-character string to specified length
================================================================

*Synopsis*
     #include <wchar.h>
     size_t wcslcpy(wchar_t *DST, const wchar_t *SRC, size_t SIZ);
   *Description*
`wcslcpy' copies wide characters from SRC to DST such that up to SIZ -
1 characters are copied.  A terminating null is appended to the result,
unless SIZ is zero.

*Returns*
`wcslcpy' returns the number of wide characters in SRC, not including
the terminating null wide character.  If the return value is greater
than or equal to SIZ, then not all wide characters were copied from SRC
and truncation occurred.

*Portability*
No supporting OS subroutines are required.

7.16 `wcslen'--get wide-character string length
===============================================

*Synopsis*
     #include <wchar.h>
     size_t wcslen(const wchar_t *S);
   *Description*
The `wcslen' function computes the number of wide-character codes in
the wide-character string to which S points, not including the
terminating null wide-character code.

*Returns*
The `wcslen' function returns the length of S; no return value is
reserved to indicate an error.

*Portability*
`wcslen' is ISO/IEC 9899/AMD1:1995 (ISO C).

   No supporting OS subroutines are required.

7.17 `wcsncat'--concatenate part of two wide-character strings
==============================================================

*Synopsis*
     #include <wchar.h>
     wchar_t *wcsncat(wchar_t *S1, const wchar_t *S2, size_t N);
   *Description*
The `wcsncat' function appends not more than N wide-character codes (a
null wide-character code and wide-character codes that follow it are
not appended) from the array pointed to by S2 to the end of the
wide-character string pointed to by S1. The initial wide-character code
of S2 overwrites the null wide-character code at the end of S1.  A
terminating null wide-character code is always appended to the result.
If copying takes place between objects that overlap, the behaviour is
undefined.

*Returns*
The `wcsncat' function returns S1; no return value is reserved to
indicate an error.

*Portability*
`wcsncat' is ISO/IEC 9899/AMD1:1995 (ISO C).

   No supporting OS subroutines are required.

7.18 `wcsncmp'--compare part of two wide-character strings
==========================================================

*Synopsis*
     #include <wchar.h>
     int wcsncmp(const wchar_t *S1, const wchar_t *S2, size_t N);
   *Description*
The `wcsncmp' function compares not more than N wide-character codes
(wide-character codes that follow a null wide-character code are not
compared) from the array pointed to by S1 to the array pointed to by S2.

   The sign of a non-zero return value is determined by the sign of the
difference between the values of the first pair of wide-character codes
that differ in the objects being compared.

*Returns*
Upon successful completion, `wcsncmp' returns an integer greater than,
equal to or less than 0, if the possibly null-terminated array pointed
to by S1 is greater than, equal to or less than the possibly
null-terminated array pointed to by S2 respectively.

*Portability*
`wcsncmp' is ISO/IEC 9899/AMD1:1995 (ISO C).

   No supporting OS subroutines are required.

7.19 `wcsncpy'--copy part of a wide-character string
====================================================

*Synopsis*
     #include <wchar.h>
     wchar_t *wcsncpy(wchar_t *S1, const wchar_t *S2, size_t N);
   *Description*
The `wcsncpy' function copies not more than N wide-character codes
(wide-character codes that follow a null wide-character code are not
copied) from the array pointed to by S2 to the array pointed to by S1.
If copying takes place between objects that overlap, the behaviour is
undefined.  Note that if S1 contains more than N wide characters before
its terminating null, the result is not null-terminated.

   If the array pointed to by S2 is a wide-character string that is
shorter than N wide-character codes, null wide-character codes are
appended to the copy in the array pointed to by S1, until N
wide-character codes in all are written.

*Returns*
The `wcsncpy' function returns S1; no return value is reserved to
indicate an error.

*Portability*
ISO/IEC 9899; POSIX.1.

   No supporting OS subroutines are required.

7.20 `wcpncpy'--copy part of a wide-character string returning a pointer to its end
===================================================================================

*Synopsis*
     #include <wchar.h>
     wchar_t *wcpncpy(wchar_t *S1, const wchar_t *S2, size_t N);
   *Description*
The `wcpncpy' function copies not more than n wide-character codes
(wide-character codes that follow a null wide-character code are not
copied) from the array pointed to by S2 to the array pointed to by S1.
If copying takes place between objects that overlap, the behaviour is
undefined.

   If the array pointed to by S2 is a wide-character string that is
shorter than N wide-character codes, null wide-character codes are
appended to the copy in the array pointed to by S1, until N
wide-character codes in all are written.

*Returns*
The `wcpncpy' function returns S1; no return value is reserved to
indicate an error.

*Portability*
`wcpncpy' is ISO/IEC 9899/AMD1:1995 (ISO C).

   No supporting OS subroutines are required.

7.21 `wcsnlen'--get fixed-size wide-character string length
===========================================================

*Synopsis*
     #include <wchar.h>
     size_t wcsnlen(const wchar_t *S, size_t MAXLEN);
   *Description*
The `wcsnlen' function computes the number of wide-character codes in
the wide-character string pointed to by S not including the terminating
L'\0' wide character but at most MAXLEN wide characters.

*Returns*
`wcsnlen' returns the length of S if it is less then MAXLEN, or MAXLEN
if there is no L'\0' wide character in first MAXLEN characters.

*Portability*
`wcsnlen' is a GNU extension.

   `wcsnlen' requires no supporting OS subroutines.

7.22 `wcspbrk'---scan wide-character string for a wide-character code
=====================================================================

*Synopsis*
     #include <wchar.h>
     wchar_t *wcspbrk(const wchar_t *S, const wchar_t *SET);
   *Description*
The `wcspbrk' function locates the first occurrence in the
wide-character string pointed to by S of any wide-character code from
the wide-character string pointed to by SET.

*Returns*
Upon successful completion, `wcspbrk' returns a pointer to the
wide-character code or a null pointer if no wide-character code from
SET occurs in S.

*Portability*
`wcspbrk' is ISO/IEC 9899/AMD1:1995 (ISO C).

   No supporting OS subroutines are required.

7.23 `wcsrchr'--wide-character string scanning operation
========================================================

*Synopsis*
     #include <wchar.h>
     wchar_t *wcsrchr(const wchar_t *S, wchar_t C);
   *Description*
The `wcsrchr' function locates the last occurrence of C in the
wide-character string pointed to by S. The value of C must be a
character representable as a type wchar_t and must be a wide-character
code corresponding to a valid character in the current locale.  The
terminating null wide-character code is considered to be part of the
wide-character string.

*Returns*
Upon successful completion, `wcsrchr' returns a pointer to the
wide-character code or a null pointer if C does not occur in the
wide-character string.

*Portability*
`wcsrchr' is ISO/IEC 9899/AMD1:1995 (ISO C).

   No supporting OS subroutines are required.

7.24 `wcsspn'--get length of a wide substring
=============================================

*Synopsis*
     #include <wchar.h>
     size_t wcsspn(const wchar_t *S, const wchar_t *SET);
   *Description*
The `wcsspn' function computes the length of the maximum initial
segment of the wide-character string pointed to by S which consists
entirely of wide-character codes from the wide-character string pointed
to by SET.

*Returns*
The wcsspn() function returns the length S1; no return value is
reserved to indicate an error.

*Portability*
`wcsspn' is ISO/IEC 9899/AMD1:1995 (ISO C).

   No supporting OS subroutines are required.

7.25 `wcsstr'--find a wide-character substring
==============================================

*Synopsis*
     #include <wchar.h>
     wchar_t *wcsstr(const wchar_t *BIG, const wchar_t *LITTLE);
   *Description*
The `wcsstr' function locates the first occurrence in the
wide-character string pointed to by BIG of the sequence of wide
characters (excluding the terminating null wide character) in the
wide-character string pointed to by LITTLE.

*Returns*
On successful completion, `wcsstr' returns a pointer to the located
wide-character string, or a null pointer if the wide-character string
is not found.

   If LITTLE points to a wide-character string with zero length, the
function returns BIG.

*Portability*
`wcsstr' is ISO/IEC 9899/AMD1:1995 (ISO C).

7.26 `wcstok'--get next token from a string
===========================================

*Synopsis*
     #include <wchar.h>
     wchar_t *wcstok(wchar_t *SOURCE, const wchar_t *DELIMITERS,
         wchar_t **LASTS)
   *Description*
The `wcstok' function is the wide-character equivalent of the
`strtok_r' function (which in turn is the same as the `strtok' function
with an added argument to make it thread-safe).

   The `wcstok' function is used to isolate (one at a time) sequential
tokens in a null-terminated wide-character string, `*SOURCE'.  A token
is defined as a substring not containing any wide-characters from
`*DELIMITERS'.

   The first time that `wcstok' is called, `*SOURCE' should be
specified with the wide-character string to be searched, and
`*LASTS'-but not `lasts', which must be non-NULL-may be random;
subsequent calls, wishing to obtain further tokens from the same
string, should pass a null pointer for `*SOURCE' instead but must
supply `*LASTS' unchanged from the last call.  The separator
wide-character string, `*DELIMITERS', must be supplied each time and
may change between calls.  A pointer to placeholder `*LASTS' must be
supplied by the caller, and is set each time as needed to save the state
by `wcstok'.	Every call to `wcstok' with `*SOURCE' == `NULL' must
pass the value of `*LASTS' as last set by `wcstok'.

   The `wcstok' function returns a pointer to the beginning of each
subsequent token in the string, after replacing the separator
wide-character itself with a null wide-character.  When no more tokens
remain, a null pointer is returned.

*Returns*
`wcstok' returns a pointer to the first wide character of a token, or
`NULL' if there is no token.

*Portability*
`wcstok' is C99 and POSIX.1-2001.

   `wcstok' requires no supporting OS subroutines.

7.27 `wcswidth'--number of column positions of a wide-character string
======================================================================

*Synopsis*
     #include <wchar.h>
     int wcswidth(const wchar_t *PWCS, size_t N);
   *Description*
The `wcswidth' function shall determine the number of column positions
required for N wide-character codes (or fewer than N wide-character
codes if a null wide-character code is encountered before N
wide-character codes are exhausted) in the string pointed to by PWCS.

*Returns*
The `wcswidth' function either shall return 0 (if PWCS points to a null
wide-character code), or return the number of column positions to be
occupied by the wide-character string pointed to by PWCS, or return -1
(if any of the first N wide-character codes in the wide-character
string pointed to by PWCS is not a printable wide-character code).

*Portability*
`wcswidth' has been introduced in the Single UNIX Specification Volume
2.  `wcswidth' has been marked as an extension in the Single UNIX
Specification Volume 3.

7.28 `wcsxfrm'--locale-specific wide-character string transformation
====================================================================

*Synopsis*
     #include <wchar.h>
     int wcsxfrm(wchar_t *STRA, const wchar_t * STRB, size_t N);
   *Description*
`wcsxfrm' transforms the wide-character string pointed to by STRB to
the wide-character string pointed to by STRA, Comparing two transformed
wide strings with `wcscmp' should return the same result as comparing
the original strings with `wcscoll'.  No more than N wide characters
are transformed, including the trailing null character.

   If N is 0, STRA may be a NULL pointer.

   The current implementation of `wcsxfrm' simply uses `wcslcpy' and
does not support any language-specific transformations.

*Returns*
`wcsxfrm' returns the length of the transformed wide character string.
if the return value is greater or equal to N, the content of STRA is
undefined.

*Portability*
`wcsxfrm' is ISO/IEC 9899/AMD1:1995 (ISO C).

7.29 `wcwidth'--number of column positions of a wide-character code
===================================================================

*Synopsis*
     #include <wchar.h>
     int wcwidth(const wchar_t WC);
   *Description*
The `wcwidth' function shall determine the number of column positions
required for the wide character WC. The application shall ensure that
the value of WC is a character representable as a wchar_t, and is a
wide-character code corresponding to a valid character in the current
locale.

*Returns*
The `wcwidth' function shall either return 0 (if WC is a null
wide-character code), or return the number of column positions to be
occupied by the wide-character code WC, or return -1 (if WC does not
correspond to a printable wide-character code).

*Portability*
`wcwidth' has been introduced in the Single UNIX Specification Volume 2.
`wcwidth' has been marked as an extension in the Single UNIX
Specification Volume 3.

8 Signal Handling (`signal.h')
******************************

A "signal" is an event that interrupts the normal flow of control in
your program.  Your operating environment normally defines the full set
of signals available (see `sys/signal.h'), as well as the default means
of dealing with them--typically, either printing an error message and
aborting your program, or ignoring the signal.

   All systems support at least the following signals:
`SIGABRT'
     Abnormal termination of a program; raised by the <<abort>>
     function.

`SIGFPE'
     A domain error in arithmetic, such as overflow, or division by
     zero.

`SIGILL'
     Attempt to execute as a function data that is not executable.

`SIGINT'
     Interrupt; an interactive attention signal.

`SIGSEGV'
     An attempt to access a memory location that is not available.

`SIGTERM'
     A request that your program end execution.

   Two functions are available for dealing with asynchronous
signals--one to allow your program to send signals to itself (this is
called "raising" a signal), and one to specify subroutines (called
"handlers" to handle particular signals that you anticipate may
occur--whether raised by your own program or the operating environment.

   To support these functions, `signal.h' defines three macros:

`SIG_DFL'
     Used with the `signal' function in place of a pointer to a handler
     subroutine, to select the operating environment's default handling
     of a signal.

`SIG_IGN'
     Used with the `signal' function in place of a pointer to a
     handler, to ignore a particular signal.

`SIG_ERR'
     Returned by the `signal' function in place of a pointer to a
     handler, to indicate that your request to set up a handler could
     not be honored for some reason.

   `signal.h' also defines an integral type, `sig_atomic_t'.  This type
is not used in any function declarations; it exists only to allow your
signal handlers to declare a static storage location where they may
store a signal value.  (Static storage is not otherwise reliable from
signal handlers.)

8.1 `raise'--send a signal
==========================

*Synopsis*
     #include <signal.h>
     int raise(int SIG);

     int _raise_r(void *REENT, int SIG);
   *Description*
Send the signal SIG (one of the macros from ``sys/signal.h'').  This
interrupts your program's normal flow of execution, and allows a signal
handler (if you've defined one, using `signal') to take control.

   The alternate function `_raise_r' is a reentrant version.  The extra
argument REENT is a pointer to a reentrancy structure.

*Returns*
The result is `0' if SIG was successfully raised, `1' otherwise.
However, the return value (since it depends on the normal flow of
execution) may not be visible, unless the signal handler for SIG
terminates with a `return' or unless `SIG_IGN' is in effect for this
signal.

*Portability*
ANSI C requires `raise', but allows the full set of signal numbers to
vary from one implementation to another.

   Required OS subroutines: `getpid', `kill'.

8.2 `signal'--specify handler subroutine for a signal
=====================================================

*Synopsis*
     #include <signal.h>
     void (*signal(int SIG, void(*FUNC)(int))) (int);

     void (*_signal_r(void *REENT, int SIG, void(*FUNC)(int))) (int);
   *Description*
`signal' provides a simple signal-handling implementation for embedded
targets.

   `signal' allows you to request changed treatment for a particular
signal SIG.  You can use one of the predefined macros `SIG_DFL' (select
system default handling) or `SIG_IGN' (ignore this signal) as the value
of FUNC; otherwise, FUNC is a function pointer that identifies a
subroutine in your program as the handler for this signal.

   Some of the execution environment for signal handlers is
unpredictable; notably, the only library function required to work
correctly from within a signal handler is `signal' itself, and only
when used to redefine the handler for the current signal value.

   Static storage is likewise unreliable for signal handlers, with one
exception: if you declare a static storage location as ``volatile
sig_atomic_t'', then you may use that location in a signal handler to
store signal values.

   If your signal handler terminates using `return' (or implicit
return), your program's execution continues at the point where it was
when the signal was raised (whether by your program itself, or by an
external event).  Signal handlers can also use functions such as `exit'
and `abort' to avoid returning.

   The alternate function `_signal_r' is the reentrant version.  The
extra argument REENT is a pointer to a reentrancy structure.

*Returns*
If your request for a signal handler cannot be honored, the result is
`SIG_ERR'; a specific error number is also recorded in `errno'.

   Otherwise, the result is the previous handler (a function pointer or
one of the predefined macros).

*Portability*
ANSI C requires `signal'.

   No supporting OS subroutines are required to link with `signal', but
it will not have any useful effects, except for software generated
signals, without an operating system that can actually raise exceptions.

9 Time Functions (`time.h')
***************************

This chapter groups functions used either for reporting on time
(elapsed, current, or compute time) or to perform calculations based on
time.

   The header file `time.h' defines three types.  `clock_t' and
`time_t' are both used for representations of time particularly
suitable for arithmetic.  (In this implementation, quantities of type
`clock_t' have the highest resolution possible on your machine, and
quantities of type `time_t' resolve to seconds.)  `size_t' is also
defined if necessary for quantities representing sizes.

   `time.h' also defines the structure `tm' for the traditional
representation of Gregorian calendar time as a series of numbers, with
the following fields:

`tm_sec'
     Seconds, between 0 and 60 inclusive (60 allows for leap seconds).

`tm_min'
     Minutes, between 0 and 59 inclusive.

`tm_hour'
     Hours, between 0 and 23 inclusive.

`tm_mday'
     Day of the month, between 1 and 31 inclusive.

`tm_mon'
     Month, between 0 (January) and 11 (December).

`tm_year'
     Year (since 1900), can be negative for earlier years.

`tm_wday'
     Day of week, between 0 (Sunday) and 6 (Saturday).

`tm_yday'
     Number of days elapsed since last January 1, between 0 and 365
     inclusive.

`tm_isdst'
     Daylight Savings Time flag: positive means DST in effect, zero
     means DST not in effect, negative means no information about DST
     is available.  Although for mktime(), negative means that it
     should decide if DST is in effect or not.

9.1 `asctime'--format time as string
====================================

*Synopsis*
     #include <time.h>
     char *asctime(const struct tm *CLOCK);
     char *_asctime_r(const struct tm *CLOCK, char *BUF);
   *Description*
Format the time value at CLOCK into a string of the form
      Wed Jun 15 11:38:07 1988\n\0
   The string is generated in a static buffer; each call to `asctime'
overwrites the string generated by previous calls.

*Returns*
A pointer to the string containing a formatted timestamp.

*Portability*
ANSI C requires `asctime'.

   `asctime' requires no supporting OS subroutines.

9.2 `clock'--cumulative processor time
======================================

*Synopsis*
     #include <time.h>
     clock_t clock(void);
   *Description*
Calculates the best available approximation of the cumulative amount of
time used by your program since it started.  To convert the result into
seconds, divide by the macro `CLOCKS_PER_SEC'.

*Returns*
The amount of processor time used so far by your program, in units
defined by the machine-dependent macro `CLOCKS_PER_SEC'.  If no
measurement is available, the result is (clock_t)`-1'.

*Portability*
ANSI C requires `clock' and `CLOCKS_PER_SEC'.

   Supporting OS subroutine required: `times'.

9.3 `ctime'--convert time to local and format as string
=======================================================

*Synopsis*
     #include <time.h>
     char *ctime(const time_t *CLOCK);
     char *ctime_r(const time_t *CLOCK, char *BUF);
   *Description*
Convert the time value at CLOCK to local time (like `localtime') and
format it into a string of the form
      Wed Jun 15 11:38:07 1988\n\0
   (like `asctime').

*Returns*
A pointer to the string containing a formatted timestamp.

*Portability*
ANSI C requires `ctime'.

   `ctime' requires no supporting OS subroutines.

9.4 `difftime'--subtract two times
==================================

*Synopsis*
     #include <time.h>
     double difftime(time_t TIM1, time_t TIM2);
   *Description*
Subtracts the two times in the arguments: ``TIM1 - TIM2''.

*Returns*
The difference (in seconds) between TIM2 and TIM1, as a `double'.

*Portability*
ANSI C requires `difftime', and defines its result to be in seconds in
all implementations.

   `difftime' requires no supporting OS subroutines.

9.5 `gmtime'--convert time to UTC traditional form
==================================================

*Synopsis*
     #include <time.h>
     struct tm *gmtime(const time_t *CLOCK);
     struct tm *gmtime_r(const time_t *CLOCK, struct tm *RES);
   *Description*
`gmtime' takes the time at CLOCK representing the number of elapsed
seconds since 00:00:00 on January 1, 1970, Universal Coordinated Time
(UTC, also known in some countries as GMT, Greenwich Mean time) and
converts it to a `struct tm' representation.

   `gmtime' constructs the traditional time representation in static
storage; each call to `gmtime' or `localtime' will overwrite the
information generated by previous calls to either function.

*Returns*
A pointer to the traditional time representation (`struct tm').

*Portability*
ANSI C requires `gmtime'.

   `gmtime' requires no supporting OS subroutines.

9.6 `localtime'--convert time to local representation
=====================================================

*Synopsis*
     #include <time.h>
     struct tm *localtime(time_t *CLOCK);
     struct tm *localtime_r(time_t *CLOCK, struct tm *RES);
   *Description*
`localtime' converts the time at CLOCK into local time, then converts
its representation from the arithmetic representation to the
traditional representation defined by `struct tm'.

   `localtime' constructs the traditional time representation in static
storage; each call to `gmtime' or `localtime' will overwrite the
information generated by previous calls to either function.

   `mktime' is the inverse of `localtime'.

*Returns*
A pointer to the traditional time representation (`struct tm').

*Portability*
ANSI C requires `localtime'.

   `localtime' requires no supporting OS subroutines.

9.7 `mktime'--convert time to arithmetic representation
=======================================================

*Synopsis*
     #include <time.h>
     time_t mktime(struct tm *TIMP);
   *Description*
`mktime' assumes the time at TIMP is a local time, and converts its
representation from the traditional representation defined by `struct
tm' into a representation suitable for arithmetic.

   `localtime' is the inverse of `mktime'.

*Returns*
If the contents of the structure at TIMP do not form a valid calendar
time representation, the result is `-1'.  Otherwise, the result is the
time, converted to a `time_t' value.

*Portability*
ANSI C requires `mktime'.

   `mktime' requires no supporting OS subroutines.

9.8 `strftime'--convert date and time to a formatted string
===========================================================

*Synopsis*
     #include <time.h>
     size_t strftime(char *S, size_t MAXSIZE,
         const char *FORMAT, const struct tm *TIMP);
   *Description*
`strftime' converts a `struct tm' representation of the time (at TIMP)
into a null-terminated string, starting at S and occupying no more than
MAXSIZE characters.

   You control the format of the output using the string at FORMAT.
`*FORMAT' can contain two kinds of specifications: text to be copied
literally into the formatted string, and time conversion
specifications.  Time conversion specifications are two- and
three-character sequences beginning with ``%'' (use ``%%'' to include a
percent sign in the output).  Each defined conversion specification
selects only the specified field(s) of calendar time data from `*TIMP',
and converts it to a string in one of the following ways:

`%a'
     The abbreviated weekday name according to the current locale.
     [tm_wday]

`%A'
     The full weekday name according to the current locale.  In the
     default "C" locale, one of ``Sunday'', ``Monday'', ``Tuesday'',
     ``Wednesday'', ``Thursday'', ``Friday'', ``Saturday''. [tm_wday]

`%b'
     The abbreviated month name according to the current locale.
     [tm_mon]

`%B'
     The full month name according to the current locale.  In the
     default "C" locale, one of ``January'', ``February'', ``March'',
     ``April'', ``May'', ``June'', ``July'', ``August'', ``September'',
     ``October'', ``November'', ``December''. [tm_mon]

`%c'
     The preferred date and time representation for the current locale.
     [tm_sec, tm_min, tm_hour, tm_mday, tm_mon, tm_year, tm_wday]

`%C'
     The century, that is, the year divided by 100 then truncated.  For
     4-digit years, the result is zero-padded and exactly two
     characters; but for other years, there may a negative sign or more
     digits.  In this way, ``%C%y'' is equivalent to ``%Y''. [tm_year]

`%d'
     The day of the month, formatted with two digits (from ``01'' to
     ``31''). [tm_mday]

`%D'
     A string representing the date, in the form ``"%m/%d/%y"''.
     [tm_mday, tm_mon, tm_year]

`%e'
     The day of the month, formatted with leading space if single digit
     (from ``1'' to ``31''). [tm_mday]

`%E`x''
     In some locales, the E modifier selects alternative
     representations of certain modifiers `x'.  In newlib, it is
     ignored, and treated as %`x'.

`%F'
     A string representing the ISO 8601:2000 date format, in the form
     ``"%Y-%m-%d"''. [tm_mday, tm_mon, tm_year]

`%g'
     The last two digits of the week-based year, see specifier %G (from
     ``00'' to ``99''). [tm_year, tm_wday, tm_yday]

`%G'
     The week-based year. In the ISO 8601:2000 calendar, week 1 of the
     year includes January 4th, and begin on Mondays. Therefore, if
     January 1st, 2nd, or 3rd falls on a Sunday, that day and earlier
     belong to the last week of the previous year; and if December
     29th, 30th, or 31st falls on Monday, that day and later belong to
     week 1 of the next year.  For consistency with %Y, it always has
     at least four characters.  Example: "%G" for Saturday 2nd January
     1999 gives "1998", and for Tuesday 30th December 1997 gives
     "1998". [tm_year, tm_wday, tm_yday]

`%h'
     Synonym for "%b". [tm_mon]

`%H'
     The hour (on a 24-hour clock), formatted with two digits (from
     ``00'' to ``23''). [tm_hour]

`%I'
     The hour (on a 12-hour clock), formatted with two digits (from
     ``01'' to ``12''). [tm_hour]

`%j'
     The count of days in the year, formatted with three digits (from
     ``001'' to ``366''). [tm_yday]

`%k'
     The hour (on a 24-hour clock), formatted with leading space if
     single digit (from ``0'' to ``23''). Non-POSIX extension (c.p.
     %I). [tm_hour]

`%l'
     The hour (on a 12-hour clock), formatted with leading space if
     single digit (from ``1'' to ``12''). Non-POSIX extension (c.p.
     %H). [tm_hour]

`%m'
     The month number, formatted with two digits (from ``01'' to
     ``12'').  [tm_mon]

`%M'
     The minute, formatted with two digits (from ``00'' to ``59'').
     [tm_min]

`%n'
     A newline character (``\n'').

`%O`x''
     In some locales, the O modifier selects alternative digit
     characters for certain modifiers `x'.  In newlib, it is ignored,
     and treated as %`x'.

`%p'
     Either ``AM'' or ``PM'' as appropriate, or the corresponding
     strings for the current locale. [tm_hour]

`%P'
     Same as '`%p'', but in lowercase.  This is a GNU extension.
     [tm_hour]

`%r'
     Replaced by the time in a.m. and p.m. notation.  In the "C" locale
     this is equivalent to "%I:%M:%S %p".  In locales which don't
     define a.m./p.m.  notations, the result is an empty string.
     [tm_sec, tm_min, tm_hour]

`%R'
     The 24-hour time, to the minute.  Equivalent to "%H:%M". [tm_min,
     tm_hour]

`%S'
     The second, formatted with two digits (from ``00'' to ``60'').  The
     value 60 accounts for the occasional leap second. [tm_sec]

`%t'
     A tab character (``\t'').

`%T'
     The 24-hour time, to the second.  Equivalent to "%H:%M:%S".
     [tm_sec, tm_min, tm_hour]

`%u'
     The weekday as a number, 1-based from Monday (from ``1'' to
     ``7''). [tm_wday]

`%U'
     The week number, where weeks start on Sunday, week 1 contains the
     first Sunday in a year, and earlier days are in week 0.  Formatted
     with two digits (from ``00'' to ``53'').  See also `%W'. [tm_wday,
     tm_yday]

`%V'
     The week number, where weeks start on Monday, week 1 contains
     January 4th, and earlier days are in the previous year.  Formatted
     with two digits (from ``01'' to ``53'').  See also `%G'. [tm_year,
     tm_wday, tm_yday]

`%w'
     The weekday as a number, 0-based from Sunday (from ``0'' to ``6'').
     [tm_wday]

`%W'
     The week number, where weeks start on Monday, week 1 contains the
     first Monday in a year, and earlier days are in week 0.  Formatted
     with two digits (from ``00'' to ``53''). [tm_wday, tm_yday]

`%x'
     Replaced by the preferred date representation in the current
     locale.  In the "C" locale this is equivalent to "%m/%d/%y".
     [tm_mon, tm_mday, tm_year]

`%X'
     Replaced by the preferred time representation in the current
     locale.  In the "C" locale this is equivalent to "%H:%M:%S".
     [tm_sec, tm_min, tm_hour]

`%y'
     The last two digits of the year (from ``00'' to ``99''). [tm_year]
     (Implementation interpretation:  always positive, even for
     negative years.)

`%Y'
     The full year, equivalent to `%C%y'.  It will always have at least
     four characters, but may have more.  The year is accurate even
     when tm_year added to the offset of 1900 overflows an int.
     [tm_year]

`%z'
     The offset from UTC.  The format consists of a sign (negative is
     west of Greewich), two characters for hour, then two characters
     for minutes (-hhmm or +hhmm).  If tm_isdst is negative, the offset
     is unknown and no output is generated; if it is zero, the offset
     is the standard offset for the current time zone; and if it is
     positive, the offset is the daylight savings offset for the
     current timezone. The offset is determined from the TZ environment
     variable, as if by calling tzset(). [tm_isdst]

`%Z'
     The time zone name.  If tm_isdst is negative, no output is
     generated.  Otherwise, the time zone name is based on the TZ
     environment variable, as if by calling tzset(). [tm_isdst]

`%%'
     A single character, ``%''.

*Returns*
When the formatted time takes up no more than MAXSIZE characters, the
result is the length of the formatted string.  Otherwise, if the
formatting operation was abandoned due to lack of room, the result is
`0', and the string starting at S corresponds to just those parts of
`*FORMAT' that could be completely filled in within the MAXSIZE limit.

*Portability*
ANSI C requires `strftime', but does not specify the contents of `*S'
when the formatted string would require more than MAXSIZE characters.
Unrecognized specifiers and fields of `timp' that are out of range
cause undefined results.  Since some formats expand to 0 bytes, it is
wise to set `*S' to a nonzero value beforehand to distinguish between
failure and an empty string.  This implementation does not support `s'
being NULL, nor overlapping `s' and `format'.

   `strftime' requires no supporting OS subroutines.

*Bugs*
`strftime' ignores the LC_TIME category of the current locale,
hard-coding the "C" locale settings.

9.9 `time'--get current calendar time (as single number)
========================================================

*Synopsis*
     #include <time.h>
     time_t time(time_t *T);
   *Description*
`time' looks up the best available representation of the current time
and returns it, encoded as a `time_t'.  It stores the same value at T
unless the argument is `NULL'.

*Returns*
A `-1' result means the current time is not available; otherwise the
result represents the current time.

*Portability*
ANSI C requires `time'.

   Supporting OS subroutine required: Some implementations require
`gettimeofday'.

9.10 `__tz_lock', `__tz_unlock'--lock time zone global variables
================================================================

*Synopsis*
     #include "local.h"
     void __tz_lock (void);
     void __tz_unlock (void);
   *Description*
The `tzset' facility functions call these functions when they need to
ensure the values of global variables.  The version of these routines
supplied in the library use the lock API defined in sys/lock.h.  If
multiple threads of execution can call the time functions and give up
scheduling in the middle, then you you need to define your own versions
of these functions in order to safely lock the time zone variables
during a call.  If you do not, the results of `localtime', `mktime',
`ctime', and `strftime' are undefined.

   The lock `__tz_lock' may not be called recursively; that is, a call
`__tz_lock' will always lock all subsequent `__tz_lock' calls until the
corresponding `__tz_unlock' call on the same thread is made.

9.11 `tzset'--set timezone characteristics from TZ environment variable
=======================================================================

*Synopsis*
     #include <time.h>
     void tzset(void);
     void _tzset_r (struct _reent *);
   *Description*
`tzset' examines the TZ environment variable and sets up the three
external variables: `_timezone', `_daylight', and `tzname'.  The value
of `_timezone' shall be the offset from the current time zone to GMT.
The value of `_daylight' shall be 0 if there is no daylight savings
time for the current time zone, otherwise it will be non-zero.  The
`tzname' array has two entries: the first is the name of the standard
time zone, the second is the name of the daylight-savings time zone.

   The TZ environment variable is expected to be in the following POSIX
format:

   stdoffset1[dst[offset2][,start[/time1],end[/time2]]]

   where: std is the name of the standard time-zone (minimum 3 chars)
offset1 is the value to add to local time to arrive at Universal time
it has the form:  hh[:mm[:ss]] dst is the name of the alternate
(daylight-savings) time-zone (min 3 chars) offset2 is the value to add
to local time to arrive at Universal time it has the same format as the
std offset start is the day that the alternate time-zone starts time1
is the optional time that the alternate time-zone starts (this is in
local time and defaults to 02:00:00 if not specified) end is the day
that the alternate time-zone ends time2 is the time that the alternate
time-zone ends (it is in local time and defaults to 02:00:00 if not
specified)

   Note that there is no white-space padding between fields.  Also note
that if TZ is null, the default is Universal GMT which has no
daylight-savings time.  If TZ is empty, the default EST5EDT is used.

   The function `_tzset_r' is identical to `tzset' only it is reentrant
and is used for applications that use multiple threads.

*Returns*
There is no return value.

*Portability*
`tzset' is part of the POSIX standard.

   Supporting OS subroutine required: None

10 Locale (`locale.h')
**********************

A "locale" is the name for a collection of parameters (affecting
collating sequences and formatting conventions) that may be different
depending on location or culture.  The `"C"' locale is the only one
defined in the ANSI C standard.

   This is a minimal implementation, supporting only the required `"C"'
value for locale; strings representing other locales are not honored.
(`""' is also accepted; it represents the default locale for an
implementation, here equivalent to `"C"'.

   `locale.h' defines the structure `lconv' to collect the information
on a locale, with the following fields:

`char *decimal_point'
     The decimal point character used to format "ordinary" numbers (all
     numbers except those referring to amounts of money).  `"."' in the
     C locale.

`char *thousands_sep'
     The character (if any) used to separate groups of digits, when
     formatting ordinary numbers.  `""' in the C locale.

`char *grouping'
     Specifications for how many digits to group (if any grouping is
     done at all) when formatting ordinary numbers.  The _numeric
     value_ of each character in the string represents the number of
     digits for the next group, and a value of `0' (that is, the
     string's trailing `NULL') means to continue grouping digits using
     the last value specified.  Use `CHAR_MAX' to indicate that no
     further grouping is desired.  `""' in the C locale.

`char *int_curr_symbol'
     The international currency symbol (first three characters), if
     any, and the character used to separate it from numbers.  `""' in
     the C locale.

`char *currency_symbol'
     The local currency symbol, if any.  `""' in the C locale.

`char *mon_decimal_point'
     The symbol used to delimit fractions in amounts of money.  `""' in
     the C locale.

`char *mon_thousands_sep'
     Similar to `thousands_sep', but used for amounts of money.  `""'
     in the C locale.

`char *mon_grouping'
     Similar to `grouping', but used for amounts of money.  `""' in the
     C locale.

`char *positive_sign'
     A string to flag positive amounts of money when formatting.  `""'
     in the C locale.

`char *negative_sign'
     A string to flag negative amounts of money when formatting.  `""'
     in the C locale.

`char int_frac_digits'
     The number of digits to display when formatting amounts of money to
     international conventions.  `CHAR_MAX' (the largest number
     representable as a `char') in the C locale.

`char frac_digits'
     The number of digits to display when formatting amounts of money to
     local conventions.  `CHAR_MAX' in the C locale.

`char p_cs_precedes'
     `1' indicates the local currency symbol is used before a _positive
     or zero_ formatted amount of money; `0' indicates the currency
     symbol is placed after the formatted number.  `CHAR_MAX' in the C
     locale.

`char p_sep_by_space'
     `1' indicates the local currency symbol must be separated from
     _positive or zero_ numbers by a space; `0' indicates that it is
     immediately adjacent to numbers.  `CHAR_MAX' in the C locale.

`char n_cs_precedes'
     `1' indicates the local currency symbol is used before a
     _negative_ formatted amount of money; `0' indicates the currency
     symbol is placed after the formatted number.  `CHAR_MAX' in the C
     locale.

`char n_sep_by_space'
     `1' indicates the local currency symbol must be separated from
     _negative_ numbers by a space; `0' indicates that it is
     immediately adjacent to numbers.  `CHAR_MAX' in the C locale.

`char p_sign_posn'
     Controls the position of the _positive_ sign for numbers
     representing money.  `0' means parentheses surround the number;
     `1' means the sign is placed before both the number and the
     currency symbol; `2' means the sign is placed after both the number
     and the currency symbol; `3' means the sign is placed just before
     the currency symbol; and `4' means the sign is placed just after
     the currency symbol.  `CHAR_MAX' in the C locale.

`char n_sign_posn'
     Controls the position of the _negative_ sign for numbers
     representing money, using the same rules as `p_sign_posn'.
     `CHAR_MAX' in the C locale.

10.1 `setlocale', `localeconv'--select or query locale
======================================================

*Synopsis*
     #include <locale.h>
     char *setlocale(int CATEGORY, const char *LOCALE);
     lconv *localeconv(void);

     char *_setlocale_r(void *REENT,
         int CATEGORY, const char *LOCALE);
     lconv *_localeconv_r(void *REENT);
   *Description*
`setlocale' is the facility defined by ANSI C to condition the
execution environment for international collating and formatting
information; `localeconv' reports on the settings of the current locale.

   This is a minimal implementation, supporting only the required
`"POSIX"' and `"C"' values for LOCALE; strings representing other
locales are not honored unless _MB_CAPABLE is defined.

   If _MB_CAPABLE is defined, POSIX locale strings are allowed,
following the form

   language[_TERRITORY][.charset][@modifier]

   `"language"' is a two character string per ISO 639, or, if not
available for a given language, a three character string per ISO 639-3.
`"TERRITORY"' is a country code per ISO 3166.  For `"charset"' and
`"modifier"' see below.

   Additionally to the POSIX specifier, the following extension is
supported for backward compatibility with older implementations using
newlib: `"C-charset"'.  Instead of `"C-"', you can also specify `"C."'.
Both variations allow to specify language neutral locales while using
other charsets than ASCII, for instance `"C.UTF-8"', which keeps all
settings as in the C locale, but uses the UTF-8 charset.

   The following charsets are recognized: `"UTF-8"', `"JIS"',
`"EUCJP"', `"SJIS"', `"KOI8-R"', `"KOI8-U"', `"GEORGIAN-PS"',
`"PT154"', `"TIS-620"', `"ISO-8859-x"' with 1 <= x <= 16, or `"CPxxx"'
with xxx in [437, 720, 737, 775, 850, 852, 855, 857, 858, 862, 866,
874, 932, 1125, 1250, 1251, 1252, 1253, 1254, 1255, 1256, 1257, 1258].

   Charsets are case insensitive.  For instance, `"EUCJP"' and `"eucJP"'
are equivalent.  Charset names with dashes can also be written without
dashes, as in `"UTF8"', `"iso88591"' or `"koi8r"'.  `"EUCJP"' and
`"EUCKR"' are also recognized with dash, `"EUC-JP"' and `"EUC-KR"'.

   Full support for all of the above charsets requires that newlib has
been build with multibyte support and support for all ISO and Windows
Codepage.  Otherwise all singlebyte charsets are simply mapped to
ASCII.  Right now, only newlib for Cygwin is built with full charset
support by default.  Under Cygwin, this implementation additionally
supports the charsets `"GBK"', `"GB2312"', `"eucCN"', `"eucKR"', and
`"Big5"'.  Cygwin does not support `"JIS"'.

   Cygwin additionally supports locales from the file
/usr/share/locale/locale.alias.

   (`""' is also accepted; if given, the settings are read from the
corresponding LC_* environment variables and $LANG according to POSIX
rules.

   This implementation also supports a single modifier, `"cjknarrow"'.
Any other modifier is ignored.  `"cjknarrow"', in conjunction with one
of the language specifiers `"ja"', `"ko"', and `"zh"' specifies how the
functions `wcwidth' and `wcswidth' handle characters from the "CJK
Ambiguous Width" character class described in
http://www.unicode.org/unicode/reports/tr11/.  Usually these characters
have a width of 1, unless you specify one of the aforementioned
languages, in which case these characters have a width of 2.  By
specifying the `"cjknarrow"' modifier, these characters will have a
width of one in the languages `"ja"', `"ko"', and `"zh"' as well.

   If you use `NULL' as the LOCALE argument, `setlocale' returns a
pointer to the string representing the current locale.  The acceptable
values for CATEGORY are defined in ``locale.h'' as macros beginning
with `"LC_"'.

   `localeconv' returns a pointer to a structure (also defined in
``locale.h'') describing the locale-specific conventions currently in
effect.

   `_localeconv_r' and `_setlocale_r' are reentrant versions of
`localeconv' and `setlocale' respectively.  The extra argument REENT is
a pointer to a reentrancy structure.

*Returns*
A successful call to `setlocale' returns a pointer to a string
associated with the specified category for the new locale.  The string
returned by `setlocale' is such that a subsequent call using that
string will restore that category (or all categories in case of LC_ALL),
to that state.  The application shall not modify the string returned
which may be overwritten by a subsequent call to `setlocale'.  On
error, `setlocale' returns `NULL'.

   `localeconv' returns a pointer to a structure of type `lconv', which
describes the formatting and collating conventions in effect (in this
implementation, always those of the C locale).

*Portability*
ANSI C requires `setlocale', but the only locale required across all
implementations is the C locale.

11 Reentrancy
*************

Reentrancy is a characteristic of library functions which allows
multiple processes to use the same address space with assurance that
the values stored in those spaces will remain constant between calls.
The Red Hat newlib implementation of the library functions ensures that
whenever possible, these library functions are reentrant.  However,
there are some functions that can not be trivially made reentrant.
Hooks have been provided to allow you to use these functions in a fully
reentrant fashion.

   These hooks use the structure `_reent' defined in `reent.h'.  A
variable defined as `struct _reent' is called a "reentrancy structure".
All functions which must manipulate global information are available in
two versions.  The first version has the usual name, and uses a single
global instance of the reentrancy structure.  The second has a
different name, normally formed by prepending `_' and appending `_r',
and takes a pointer to the particular reentrancy structure to use.

   For example, the function `fopen' takes two arguments, FILE and
MODE, and uses the global reentrancy structure.  The function
`_fopen_r' takes the arguments, STRUCT_REENT, which is a pointer to an
instance of the reentrancy structure, FILE and MODE.

   There are two versions of `struct _reent', a normal one and one for
small memory systems, controlled by the `_REENT_SMALL' definition from
the (automatically included) `<sys/config.h>'.

   Each function which uses the global reentrancy structure uses the
global variable `_impure_ptr', which points to a reentrancy structure.

   This means that you have two ways to achieve reentrancy.  Both
require that each thread of execution control initialize a unique global
variable of type `struct _reent':

  1. Use the reentrant versions of the library functions, after
     initializing a global reentrancy structure for each process.  Use
     the pointer to this structure as the extra argument for all
     library functions.

  2. Ensure that each thread of execution control has a pointer to its
     own unique reentrancy structure in the global variable
     `_impure_ptr', and call the standard library subroutines.

   The following functions are provided in both reentrant and
non-reentrant versions.

_Equivalent for errno variable:_
     _errno_r

_Locale functions:_
     _localeconv_r  _setlocale_r

_Equivalents for stdio variables:_
     _stdin_r        _stdout_r       _stderr_r

_Stdio functions:_
     _fdopen_r       _perror_r       _tempnam_r
     _fopen_r        _putchar_r      _tmpnam_r
     _getchar_r      _puts_r         _tmpfile_r
     _gets_r         _remove_r       _vfprintf_r
     _iprintf_r      _rename_r       _vsnprintf_r
     _mkstemp_r      _snprintf_r     _vsprintf_r
     _mktemp_t       _sprintf_r

_Signal functions:_
     _init_signal_r  _signal_r
     _kill_r         __sigtramp_r
     _raise_r

_Stdlib functions:_
     _calloc_r       _mblen_r        _setenv_r
     _dtoa_r         _mbstowcs_r     _srand_r
     _free_r         _mbtowc_r       _strtod_r
     _getenv_r       _memalign_r     _strtol_r
     _mallinfo_r     _mstats_r       _strtoul_r
     _malloc_r       _putenv_r       _system_r
     _malloc_r       _rand_r         _wcstombs_r
     _malloc_stats_r _realloc_r      _wctomb_r

_String functions:_
     _strdup_r       _strtok_r

_System functions:_
     _close_r        _link_r         _unlink_r
     _execve_r       _lseek_r        _wait_r
     _fcntl_r        _open_r         _write_r
     _fork_r         _read_r
     _fstat_r        _sbrk_r
     _gettimeofday_r _stat_r
     _getpid_r       _times_r

_Additional 64-bit I/O System functions:_
     _fstat64_r	_lseek64_r	_open64_r

_Time function:_
     _asctime_r

12 Miscellaneous Macros and Functions
*************************************

This chapter describes miscellaneous routines not covered elsewhere.

12.1 `ffs'--find first bit set in a word
========================================

*Synopsis*
     int ffs(int WORD);
   *Description*
`ffs' returns the first bit set in a word.

*Returns*
`ffs' returns 0 if C is 0, 1 if C is odd, 2 if C is a multiple of 2,
etc.

*Portability*
`ffs' is not ANSI C.

   No supporting OS subroutines are required.

12.2 `unctrl'--get printable representation of a character
==========================================================

*Synopsis*
     #include <unctrl.h>
     char *unctrl(int C);
     int unctrllen(int C);
   *Description*
`unctrl' is a macro which returns the printable representation of C as
a string.  `unctrllen' is a macro which returns the length of the
printable representation of C.

*Returns*
`unctrl' returns a string of the printable representation of C.

   `unctrllen' returns the length of the string which is the printable
representation of C.

*Portability*
`unctrl' and `unctrllen' are not ANSI C.

   No supporting OS subroutines are required.

13 Posix Functions
******************

This chapter groups several utility functions specified by POSIX, but
not by C.  Each function documents which header to use.

13.1 `popen', `pclose'--tie a stream to a command string
========================================================

*Synopsis*
     #include <stdio.h>
     FILE *popen(const char *S, const char *MODE);

     int pclose(FILE *F);
   *Description*
Use `popen' to create a stream to a child process executing a command
string `*S' as processed by `/bin/sh' on your system.  The argument
MODE must start with either ``r'', where the stream reads from the
child's `stdout', or ``w'', where the stream writes to the child's
`stdin'.  As an extension, MODE may also contain ``e'' to set the
close-on-exec bit of the parent's file descriptor.  The stream created
by `popen' must be closed by `pclose' to avoid resource leaks.

   Streams created by prior calls to `popen' are not visible in
subsequent `popen' children, regardless of the close-on-exec bit.

   Use "`system(NULL)'" to test whether your system has `/bin/sh'
available.

*Returns*
`popen' returns a file stream opened with the specified MODE, or `NULL'
if a child process could not be created.  `pclose' returns -1 if the
stream was not created by `popen' or if the application used `wait' or
similar to steal the status; otherwise it returns the exit status of
the child which can be interpreted in the same manner as a status
obtained by `waitpid'.

*Portability*
POSIX.2 requires `popen' and `pclose', but only specifies a mode of
just `r' or `w'.  Where `sh' is found is left unspecified.

   Supporting OS subroutines required: `_exit', `_execve', `_fork_r',
`_wait_r', `pipe', `fcntl', `sbrk'.

14 System Calls
***************

The C subroutine library depends on a handful of subroutine calls for
operating system services.  If you use the C library on a system that
complies with the POSIX.1 standard (also known as IEEE 1003.1), most of
these subroutines are supplied with your operating system.

   If some of these subroutines are not provided with your system--in
the extreme case, if you are developing software for a "bare board"
system, without an OS--you will at least need to provide do-nothing
stubs (or subroutines with minimal functionality) to allow your
programs to link with the subroutines in `libc.a'.

14.1 Definitions for OS interface
=================================

This is the complete set of system definitions (primarily subroutines)
required; the examples shown implement the minimal functionality
required to allow `libc' to link, and fail gracefully where OS services
are not available.

   Graceful failure is permitted by returning an error code.  A minor
complication arises here: the C library must be compatible with
development environments that supply fully functional versions of these
subroutines.  Such environments usually return error codes in a global
`errno'.  However, the Red Hat newlib C library provides a _macro_
definition for `errno' in the header file `errno.h', as part of its
support for reentrant routines (see Reentrancy).

   The bridge between these two interpretations of `errno' is
straightforward: the C library routines with OS interface calls capture
the `errno' values returned globally, and record them in the
appropriate field of the reentrancy structure (so that you can query
them using the `errno' macro from `errno.h').

   This mechanism becomes visible when you write stub routines for OS
interfaces.   You must include `errno.h', then disable the macro, like
this:

     #include <errno.h>
     #undef errno
     extern int errno;

The examples in this chapter include this treatment of `errno'.

`_exit'
     Exit a program without cleaning up files.  If your system doesn't
     provide this, it is best to avoid linking with subroutines that
     require it (`exit', `system').

`close'
     Close a file.  Minimal implementation:

          int close(int file) {
            return -1;
          }

`environ'
     A pointer to a list of environment variables and their values.
     For a minimal environment, this empty list is adequate:

          char *__env[1] = { 0 };
          char **environ = __env;

`execve'
     Transfer control to a new process.  Minimal implementation (for a
     system without processes):

          #include <errno.h>
          #undef errno
          extern int errno;
          int execve(char *name, char **argv, char **env) {
            errno = ENOMEM;
            return -1;
          }

`fork'
     Create a new process.  Minimal implementation (for a system
     without processes):

          #include <errno.h>
          #undef errno
          extern int errno;
          int fork(void) {
            errno = EAGAIN;
            return -1;
          }

`fstat'
     Status of an open file.  For consistency with other minimal
     implementations in these examples, all files are regarded as
     character special devices.  The `sys/stat.h' header file required
     is distributed in the `include' subdirectory for this C library.

          #include <sys/stat.h>
          int fstat(int file, struct stat *st) {
            st->st_mode = S_IFCHR;
            return 0;
          }

`getpid'
     Process-ID; this is sometimes used to generate strings unlikely to
     conflict with other processes.  Minimal implementation, for a
     system without processes:

          int getpid(void) {
            return 1;
          }

`isatty'
     Query whether output stream is a terminal.   For consistency with
     the other minimal implementations, which only support output to
     `stdout', this minimal implementation is suggested:

          int isatty(int file) {
            return 1;
          }

`kill'
     Send a signal.  Minimal implementation:

          #include <errno.h>
          #undef errno
          extern int errno;
          int kill(int pid, int sig) {
            errno = EINVAL;
            return -1;
          }

`link'
     Establish a new name for an existing file.  Minimal implementation:

          #include <errno.h>
          #undef errno
          extern int errno;
          int link(char *old, char *new) {
            errno = EMLINK;
            return -1;
          }

`lseek'
     Set position in a file.  Minimal implementation:

          int lseek(int file, int ptr, int dir) {
            return 0;
          }

`open'
     Open a file.  Minimal implementation:

          int open(const char *name, int flags, int mode) {
            return -1;
          }

`read'
     Read from a file.  Minimal implementation:

          int read(int file, char *ptr, int len) {
            return 0;
          }

`sbrk'
     Increase program data space.  As `malloc' and related functions
     depend on this, it is useful to have a working implementation.  The
     following suffices for a standalone system; it exploits the symbol
     `_end' automatically defined by the GNU linker.

          caddr_t sbrk(int incr) {
            extern char _end;		/* Defined by the linker */
            static char *heap_end;
            char *prev_heap_end;

            if (heap_end == 0) {
              heap_end = &_end;
            }
            prev_heap_end = heap_end;
            if (heap_end + incr > stack_ptr) {
              write (1, "Heap and stack collision\n", 25);
              abort ();
            }

            heap_end += incr;
            return (caddr_t) prev_heap_end;
          }

`stat'
     Status of a file (by name).  Minimal implementation:

          int stat(char *file, struct stat *st) {
            st->st_mode = S_IFCHR;
            return 0;
          }

`times'
     Timing information for current process.  Minimal implementation:

          int times(struct tms *buf) {
            return -1;
          }

`unlink'
     Remove a file's directory entry.  Minimal implementation:

          #include <errno.h>
          #undef errno
          extern int errno;
          int unlink(char *name) {
            errno = ENOENT;
            return -1;
          }

`wait'
     Wait for a child process.  Minimal implementation:
          #include <errno.h>
          #undef errno
          extern int errno;
          int wait(int *status) {
            errno = ECHILD;
            return -1;
          }

`write'
     Write to a file.  `libc' subroutines will use this system routine
     for output to all files, _including_ `stdout'--so if you need to
     generate any output, for example to a serial port for debugging,
     you should make your minimal `write' capable of doing this.  The
     following minimal implementation is an incomplete example; it
     relies on a `outbyte' subroutine (not shown; typically, you must
     write this in assembler from examples provided by your hardware
     manufacturer) to actually perform the output.

          int write(int file, char *ptr, int len) {
            int todo;

            for (todo = 0; todo < len; todo++) {
              outbyte (*ptr++);
            }
            return len;
          }

14.2 Reentrant covers for OS subroutines
========================================

Since the system subroutines are used by other library routines that
require reentrancy, `libc.a' provides cover routines (for example, the
reentrant version of `fork' is `_fork_r').  These cover routines are
consistent with the other reentrant subroutines in this library, and
achieve reentrancy by using a reserved global data block (see
Reentrancy).

`_open_r'
     A reentrant version of `open'.  It takes a pointer to the global
     data block, which holds `errno'.

          int _open_r(void *REENT,
              const char *FILE, int FLAGS, int MODE);

`_open64_r'
     A reentrant version of `open64'.  It takes a pointer to the global
     data block, which holds `errno'.

          int _open64_r(void *REENT,
              const char *FILE, int FLAGS, int MODE);

`_close_r'
     A reentrant version of `close'.  It takes a pointer to the global
     data block, which holds `errno'.

          int _close_r(void *REENT, int FD);

`_lseek_r'
     A reentrant version of `lseek'.  It takes a pointer to the global
     data block, which holds `errno'.

          off_t _lseek_r(void *REENT,
              int FD, off_t POS, int WHENCE);

`_lseek64_r'
     A reentrant version of `lseek64'.  It takes a pointer to the global
     data block, which holds `errno'.

          off_t _lseek64_r(void *REENT,
              int FD, off_t POS, int WHENCE);

`_read_r'
     A reentrant version of `read'.  It takes a pointer to the global
     data block, which holds `errno'.

          long _read_r(void *REENT,
              int FD, void *BUF, size_t CNT);

`_write_r'
     A reentrant version of `write'.  It takes a pointer to the global
     data block, which holds `errno'.

          long _write_r(void *REENT,
              int FD, const void *BUF, size_t CNT);

`_fork_r'
     A reentrant version of `fork'.  It takes a pointer to the global
     data block, which holds `errno'.

          int _fork_r(void *REENT);

`_wait_r'
     A reentrant version of `wait'.  It takes a pointer to the global
     data block, which holds `errno'.

          int _wait_r(void *REENT, int *STATUS);

`_stat_r'
     A reentrant version of `stat'.  It takes a pointer to the global
     data block, which holds `errno'.

          int _stat_r(void *REENT,
              const char *FILE, struct stat *PSTAT);

`_fstat_r'
     A reentrant version of `fstat'.  It takes a pointer to the global
     data block, which holds `errno'.

          int _fstat_r(void *REENT,
              int FD, struct stat *PSTAT);

`_fstat64_r'
     A reentrant version of `fstat64'.  It takes a pointer to the global
     data block, which holds `errno'.

          int _fstat64_r(void *REENT,
              int FD, struct stat *PSTAT);

`_link_r'
     A reentrant version of `link'.  It takes a pointer to the global
     data block, which holds `errno'.

          int _link_r(void *REENT,
              const char *OLD, const char *NEW);

`_unlink_r'
     A reentrant version of `unlink'.  It takes a pointer to the global
     data block, which holds `errno'.

          int _unlink_r(void *REENT, const char *FILE);

`_sbrk_r'
     A reentrant version of `sbrk'.  It takes a pointer to the global
     data block, which holds `errno'.

          char *_sbrk_r(void *REENT, size_t INCR);

15 Variable Argument Lists
**************************

The `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 `stdarg.h' (for compatibility with ANSI C) or from
`varargs.h' (for compatibility with a popular convention prior to ANSI
C).

15.1 ANSI-standard macros, `stdarg.h'
=====================================

In ANSI C, a function has a variable number of arguments when its
parameter list ends in an ellipsis (`...').  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 (`va_start', `va_arg', and `va_end') to
operate on variable argument lists.  `stdarg.h' also defines a special
type to represent variable argument lists: this type is called
`va_list'.

15.1.1 Initialize variable argument list
----------------------------------------

*Synopsis*
     #include <stdarg.h>
     void va_start(va_list AP, RIGHTMOST);

   *Description*
Use `va_start' to initialize the variable argument list AP, so that
`va_arg' can extract values from it.  RIGHTMOST is the name of the last
explicit argument in the parameter list (the argument immediately
preceding the ellipsis `...' that flags variable arguments in an ANSI C
function header).  You can only use `va_start' in a function declared
using this ellipsis notation (not, for example, in one of its
subfunctions).

   *Returns*
`va_start' does not return a result.

   *Portability*
ANSI C requires `va_start'.

15.1.2 Extract a value from argument list
-----------------------------------------

*Synopsis*
     #include <stdarg.h>
     TYPE va_arg(va_list AP, TYPE);

   *Description*
`va_arg' returns the next unprocessed value from a variable argument
list AP (which you must previously create with VA_START).  Specify the
type for the value as the second parameter to the macro, TYPE.

   You may pass a `va_list' object AP to a subfunction, and use
`va_arg' from the subfunction rather than from the function actually
declared with an ellipsis in the header; however, in that case you may
_only_ use `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.

   *Returns*
`va_arg' returns the next argument, an object of type TYPE.

   *Portability*
ANSI C requires `va_arg'.

15.1.3 Abandon a variable argument list
---------------------------------------

*Synopsis*
     #include <stdarg.h>
     void va_end(va_list AP);

   *Description*
Use `va_end' to declare that your program will not use the variable
argument list AP any further.

   *Returns*
`va_end' does not return a result.

   *Portability*
ANSI C requires `va_end'.

15.2 Traditional macros, `varargs.h'
====================================

If your C compiler predates ANSI C, you may still be able to use
variable argument lists using the macros from the `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 `stdarg.h', the type `va_list' is used to hold a data
structure representing a variable argument list.

15.2.1 Declare variable arguments
---------------------------------

*Synopsis*
     #include <varargs.h>
     FUNCTION(va_alist)
     va_dcl

   *Description*
To use the `varargs.h' version of variable argument lists, you must
declare your function with a call to the macro `va_alist' as its
argument list, and use `va_dcl' as the declaration.  _Do not use a
semicolon after `va_dcl'._

   *Returns*
These macros cannot be used in a context where a return is syntactically
possible.

   *Portability*
VA_ALIST and VA_DCL were the most widespread method of declaring
variable argument lists prior to ANSI C.

15.2.2 Initialize variable argument list
----------------------------------------

*Synopsis*
     #include <varargs.h>
     va_list AP;
     va_start(AP);

   *Description*
With the `varargs.h' macros, use `va_start' to initialize a data
structure AP to permit manipulating a variable argument list.  AP must
have the type VA_ALIST.

   *Returns*
`va_start' does not return a result.

   *Portability*
`va_start' is also defined as a macro in ANSI C, but the definitions
are incompatible; the ANSI version has another parameter besides AP.

15.2.3 Extract a value from argument list
-----------------------------------------

*Synopsis*
     #include <varargs.h>
     TYPE va_arg(va_list AP, TYPE);

   *Description*
`va_arg' returns the next unprocessed value from a variable argument
list AP (which you must previously create with VA_START).  Specify the
type for the value as the second parameter to the macro, TYPE.

   *Returns*
`va_arg' returns the next argument, an object of type TYPE.

   *Portability*
The `va_arg' defined in `varargs.h' has the same syntax and usage as
the ANSI C version from `stdarg.h'.

15.2.4 Abandon a variable argument list
---------------------------------------

*Synopsis*
     #include <varargs.h>
     va_end(va_list AP);

   *Description*
Use `va_end' to declare that your program will not use the variable
argument list AP any further.

   *Returns*
`va_end' does not return a result.

   *Portability*
The `va_end' defined in `varargs.h' has the same syntax and usage as
the ANSI C version from `stdarg.h'.