This is Info file libc.info, produced by Makeinfo version 1.67 from the
input file /dumbo/build/lsi/i386-cygwin32/src/newlib/libc/libc.texinfo.

START-INFO-DIR-ENTRY
* libc::                        The ANSI C library.
END-INFO-DIR-ENTRY

   This file documents the ANSI C library.

   Copyright (C) 1992, 1993 Cygnus Support

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


File: libc.info,  Node: Top,  Next: Stdlib,  Up: (dir)

The Cygnus C Support Library
****************************

* Menu:

* Stdlib::
* Ctype::
* Stdio::
* Strings::

* Signals::

* Timefns::
* Locale::
* Syscalls::
* Misc::
* Arglists::
* Reentrancy::
* Library Index::


File: libc.info,  Node: Stdlib,  Next: Ctype,  Prev: Top,  Up: Top

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

* Menu:

* abort::       Abnormal termination of a program
* abs::         Integer absolute value (magnitude)
* assert::      Macro for Debugging Diagnostics
* atexit::      Request execution of functions at program exit
* atof::        String to double or float
* atoi::        String to integer
* bsearch::     Binary search
* calloc::      Allocate space for arrays
* div::         Divide two integers
* ecvtbuf::     Double or float to string of digits
* ecvt::        Double or float to string of digits (malloc result)
* gvcvt::       Format double or float as string
* exit::        End program execution
* getenv::      Look up environment variable
* labs::        Long integer absolute value (magnitude)
* ldiv::        Divide two long integers
* malloc::      Allocate and manage memory (malloc, realloc, free)
* mbtowc::      Minimal multibyte to wide character converter
* qsort::       Sort an array
* rand::        Pseudo-random numbers
* strtod::      String to double or float
* strtol::      String to long
* strtoul::     String to unsigned long
* system::      Execute command string
* wctomb::      Minimal wide character to multibyte converter


File: libc.info,  Node: abort,  Next: abs,  Up: Stdlib

`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: `getpid', `kill'.


File: libc.info,  Node: abs,  Next: assert,  Prev: abort,  Up: Stdlib

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


File: libc.info,  Node: assert,  Next: atexit,  Prev: abs,  Up: Stdlib

`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

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


File: libc.info,  Node: atexit,  Next: atof,  Prev: assert,  Up: Stdlib

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


File: libc.info,  Node: atof,  Next: atoi,  Prev: atexit,  Up: Stdlib

`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 `strtodf(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'.


File: libc.info,  Node: atoi,  Next: bsearch,  Prev: atof,  Up: Stdlib

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

*Synopsis*
     #include <stdlib.h>
     int atoi(const char *S);
     long atol(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).'

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

*Portability*
`atoi' is ANSI.

   No supporting OS subroutines are required.


File: libc.info,  Node: bsearch,  Next: calloc,  Prev: atoi,  Up: Stdlib

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


File: libc.info,  Node: calloc,  Next: div,  Prev: bsearch,  Up: Stdlib

`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 functios `_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'.


File: libc.info,  Node: div,  Next: ecvtbuf,  Prev: calloc,  Up: Stdlib

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


File: libc.info,  Node: ecvt,  Next: gvcvt,  Prev: ecvtbuf,  Up: Stdlib

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


File: libc.info,  Node: gvcvt,  Next: exit,  Prev: ecvt,  Up: Stdlib

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


File: libc.info,  Node: ecvtbuf,  Next: ecvt,  Prev: div,  Up: Stdlib

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


File: libc.info,  Node: exit,  Next: getenv,  Prev: gvcvt,  Up: Stdlib

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


File: libc.info,  Node: getenv,  Next: labs,  Prev: exit,  Up: Stdlib

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


File: libc.info,  Node: labs,  Next: ldiv,  Prev: getenv,  Up: Stdlib

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


File: libc.info,  Node: ldiv,  Next: malloc,  Prev: labs,  Up: Stdlib

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


File: libc.info,  Node: malloc,  Next: mbtowc,  Prev: ldiv,  Up: Stdlib

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

*Synopsis*
     #include <stdlib.h>
     void *malloc(size_t NBYTES);
     void *realloc(void *APTR, size_t NBYTES);
     void free(void *APTR);
     
     void *_malloc_r(void *REENT, size_t NBYTES);
     void *_realloc_r(void *REENT,
         void *APTR, size_t NBYTES);
     void _free_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 alternate functions `_malloc_r', `_realloc_r', and `_free_r' are
reentrant versions.  The extra argument REENT is a pointer to a
reentrancy structure.

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

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

   Supporting OS subroutines required: `sbrk', `write' (if WARN_VLIMIT).


File: libc.info,  Node: mbtowc,  Next: qsort,  Prev: malloc,  Up: Stdlib

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

*Synopsis*
     #include <stdlib.h>
     int mbtowc(wchar_t *PWC, const char *S, size_t N);
   *Description*
This is a minimal ANSI-conforming implementation of `mbtowc'.  The 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.

   In this implementation, the argument N is ignored.

*Returns*
This implementation of `mbtowc' returns `0' if S is `NULL'; it returns
`1' otherwise (reporting the length of the character "sequence" used).

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

   `mbtowc' requires no supporting OS subroutines.


File: libc.info,  Node: qsort,  Next: rand,  Prev: mbtowc,  Up: Stdlib

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


File: libc.info,  Node: rand,  Next: strtod,  Prev: qsort,  Up: Stdlib

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


File: libc.info,  Node: strtod,  Next: strtol,  Prev: rand,  Up: Stdlib

`strtod', `strtodf'--string to double or float
==============================================

*Synopsis*
     #include <stdlib.h>
     double strtod(const char *STR, char **TAIL);
     float strtodf(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 the format:
     [+|-]DIGITS[.][DIGITS][(e|E)[+|-]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. 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.  `strtodf' 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.

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


File: libc.info,  Node: strtol,  Next: strtoul,  Prev: strtod,  Up: Stdlib

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


File: libc.info,  Node: strtoul,  Next: system,  Prev: strtol,  Up: Stdlib

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


File: libc.info,  Node: system,  Next: wctomb,  Prev: strtoul,  Up: Stdlib

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


File: libc.info,  Node: wctomb,  Prev: system,  Up: Stdlib

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

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

   Each call to `wctomb' copies the character WCHAR to `*S', unless S
is a null pointer.

*Returns*
This implementation of `wctomb' returns `0' if S is `NULL'; it returns
`1' otherwise (reporting the length of the character "sequence"
generated).

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

   `wctomb' requires no supporting OS subroutines.


File: libc.info,  Node: Ctype,  Next: Stdio,  Prev: Stdlib,  Up: Top

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.

* Menu:

* isalnum::   Alphanumeric character predicate
* isalpha::   Alphabetic character predicate
* isascii::   ASCII character predicate
* iscntrl::   Control character predicate
* isdigit::   Decimal digit predicate
* islower::   Lower-case character predicate
* isprint::   Printable character predicates (isprint, isgraph)
* ispunct::   Punctuation character predicate
* isspace::   Whitespace character predicate
* isupper::   Uppercase character predicate
* isxdigit::  Hexadecimal digit predicate
* toascii::   Force integers to ASCII range
* tolower::   Translate characters to lower case
* toupper::   Translate characters to upper case


File: libc.info,  Node: isalnum,  Next: isalpha,  Up: Ctype

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


File: libc.info,  Node: isalpha,  Next: isascii,  Prev: isalnum,  Up: Ctype

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


File: libc.info,  Node: isascii,  Next: iscntrl,  Prev: isalpha,  Up: Ctype

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


File: libc.info,  Node: iscntrl,  Next: isdigit,  Prev: isascii,  Up: Ctype

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


File: libc.info,  Node: isdigit,  Next: islower,  Prev: iscntrl,  Up: Ctype

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


File: libc.info,  Node: islower,  Next: isprint,  Prev: isdigit,  Up: Ctype

`islower'--lower-case 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
(lower-case 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 lower case letter (`a'-`z').

*Portability*
`islower' is ANSI C.

   No supporting OS subroutines are required.


File: libc.info,  Node: isprint,  Next: ispunct,  Prev: islower,  Up: Ctype

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


File: libc.info,  Node: ispunct,  Next: isspace,  Prev: isprint,  Up: Ctype

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


File: libc.info,  Node: isspace,  Next: isupper,  Prev: ispunct,  Up: Ctype

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


File: libc.info,  Node: isupper,  Next: isxdigit,  Prev: isspace,  Up: Ctype

`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 upper-case 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 upper case letter (A-Z).

*Portability*
`isupper' is ANSI C.

   No supporting OS subroutines are required.


File: libc.info,  Node: isxdigit,  Next: toascii,  Prev: isupper,  Up: Ctype

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


File: libc.info,  Node: toascii,  Next: tolower,  Prev: isxdigit,  Up: Ctype

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


File: libc.info,  Node: tolower,  Next: toupper,  Prev: toascii,  Up: Ctype

`tolower'--translate characters to lower case
=============================================

*Synopsis*
     #include <ctype.h>
     int tolower(int C);
     int _tolower(int C);
   *Description*
`tolower' is a macro which converts upper-case characters to lower
case, 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 lower-case equivalent of C when it is a character
between `A' and `Z', and C otherwise.

   `_tolower' returns the lower-case 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.


File: libc.info,  Node: toupper,  Prev: tolower,  Up: Ctype

`toupper'--translate characters to upper case
=============================================

*Synopsis*
     #include <ctype.h>
     int toupper(int C);
     int _toupper(int C);
   *Description*
`toupper' is a macro which converts lower-case characters to upper
case, 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 upper-case equivalent of C when it is a character
between `a' and `z', and C otherwise.

   `_toupper' returns the upper-case 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.


File: libc.info,  Node: Stdio,  Next: Strings,  Prev: Ctype,  Up: Top

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.

* Menu:

* clearerr::    Clear file or stream error indicator
* fclose::      Close a file
* feof::        Test for end of file
* ferror::      Test whether read/write error has occurred
* fflush::      Flush buffered file output
* fgetc::       Get a character from a file or stream
* fgetpos::     Record position in a stream or file
* fgets::       Get character string from a file or stream
* fiprintf::    Write formatted output to file (integer only)
* fopen::       Open a file
* fdopen::	Turn an open file into a stream
* fputc::       Write a character on a stream or file
* fputs::       Write a character string in a file or stream
* fread::       Read array elements from a file
* freopen::     Open a file using an existing file descriptor
* fseek::       Set file position
* fsetpos::     Restore position of a stream or file
* ftell::       Return position in a stream or file
* fwrite::      Write array elements from memory to a file or stream
* getc::        Get a character from a file or stream (macro)
* getchar::     Get a character from standard input (macro)
* gets::        Get character string from standard input (obsolete)
* iprintf::     Write formatted output (integer only)
* mktemp::      Generate unused file name
* perror::      Print an error message on standard error
* putc::        Write a character on a stream or file (macro)
* putchar::     Write a character on standard output (macro)
* puts::        Write a character string on standard output
* remove::      Delete a file's name
* rename::      Rename a file
* rewind::      Reinitialize a file or stream
* setbuf::      Specify full buffering for a file or stream
* setvbuf::     Specify buffering for a file or stream
* siprintf::    Write formatted output (integer only)
* printf::      Write formatted output
* scanf::       Scan and format input
* tmpfile::     Create a temporary file
* tmpnam::      Generate name for a temporary file
* vprintf::     Format variable argument list


File: libc.info,  Node: clearerr,  Next: fclose,  Up: Stdio

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


File: libc.info,  Node: fclose,  Next: feof,  Prev: clearerr,  Up: Stdio

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

*Synopsis*
     #include <stdio.h>
     int fclose(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)').

*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'.


File: libc.info,  Node: feof,  Next: ferror,  Prev: fclose,  Up: Stdio

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


File: libc.info,  Node: ferror,  Next: fflush,  Prev: feof,  Up: Stdio

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


File: libc.info,  Node: fflush,  Next: fgetc,  Prev: ferror,  Up: Stdio

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

*Synopsis*
     #include <stdio.h>
     int fflush(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.

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

*Portability*
ANSI C requires `fflush'.

   No supporting OS subroutines are required.


File: libc.info,  Node: fgetc,  Next: fgetpos,  Prev: fflush,  Up: Stdio

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

*Synopsis*
     #include <stdio.h>
     int fgetc(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'.

*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'.


File: libc.info,  Node: fgetpos,  Next: fgets,  Prev: fgetc,  Up: Stdio

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

*Synopsis*
     #include <stdio.h>
     int fgetpos(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.


File: libc.info,  Node: fgets,  Next: fiprintf,  Prev: fgetpos,  Up: Stdio

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

*Synopsis*
     #include <stdio.h>
     char *fgets(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.

*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'.


File: libc.info,  Node: fiprintf,  Next: fopen,  Prev: fgets,  Up: Stdio

`fiprintf'--format output to file (integer only)
================================================

*Synopsis*
     #include <stdio.h>
     
     int fiprintf(FILE *FD, const char *FORMAT, ...);
   *Description*
`fiprintf' is a restricted version of `fprintf': it has the same
arguments and behavior, save that it cannot perform any floating-point
formatting--the `f', `g', `G', `e', and `F' type specifiers are not
recognized.

*Returns*
`fiprintf' returns the number of bytes in the output string, save that
the concluding `NULL' is not counted.  `fiprintf' returns when the end
of the format string is encountered.  If an error occurs, `fiprintf'
returns `EOF'.

*Portability*
`fiprintf' is not required by ANSI C.

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


File: libc.info,  Node: fopen,  Next: fdopen,  Prev: fiprintf,  Up: Stdio

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

*Synopsis*
     #include <stdio.h>
     FILE *fopen(const char *FILE, const char *MODE);
     
     FILE *_fopen_r(void *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'.


File: libc.info,  Node: fdopen,  Next: fputc,  Prev: fopen,  Up: Stdio

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

*Synopsis*
     #include <stdio.h>
     FILE *fdopen(int FD, const char *MODE);
     FILE *_fdopen_r(void *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.


File: libc.info,  Node: fputc,  Next: fputs,  Prev: fdopen,  Up: Stdio

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

*Synopsis*
     #include <stdio.h>
     int fputc(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'.

*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'.


File: libc.info,  Node: fputs,  Next: fread,  Prev: fputc,  Up: Stdio

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

*Synopsis*
     #include <stdio.h>
     int fputs(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.

*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'.


File: libc.info,  Node: fread,  Next: freopen,  Prev: fputs,  Up: Stdio

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

*Synopsis*
     #include <stdio.h>
     size_t fread(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.

*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'.


File: libc.info,  Node: freopen,  Next: fseek,  Prev: fread,  Up: Stdio

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

*Synopsis*
     #include <stdio.h>
     FILE *freopen(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'.

*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'.


File: libc.info,  Node: fseek,  Next: fsetpos,  Prev: freopen,  Up: Stdio

`fseek'--set file position
==========================

*Synopsis*
     #include <stdio.h>
     int fseek(FILE *FP, long 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' 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' to determine the current file position.

*Returns*
`fseek' returns `0' when successful.  If `fseek' fails, 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'.

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


File: libc.info,  Node: fsetpos,  Next: ftell,  Prev: fseek,  Up: Stdio

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

*Synopsis*
     #include <stdio.h>
     int fsetpos(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'.


File: libc.info,  Node: ftell,  Next: fwrite,  Prev: fsetpos,  Up: Stdio

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

*Synopsis*
     #include <stdio.h>
     long ftell(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' is the current position for a file identified
by FP.  If you record this result, you can later use it with `fseek' to
return the file to this position.

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

*Returns*
`ftell' returns the file position, if possible.  If it cannot do this,
it returns `-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.

   No supporting OS subroutines are required.


File: libc.info,  Node: fwrite,  Next: getc,  Prev: ftell,  Up: Stdio

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

*Synopsis*
     #include <stdio.h>
     size_t fwrite(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.

*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'.


File: libc.info,  Node: getc,  Next: getchar,  Prev: fwrite,  Up: Stdio

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

*Synopsis*
     #include <stdio.h>
     int getc(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'.

*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'.


File: libc.info,  Node: getchar,  Next: gets,  Prev: getc,  Up: Stdio

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

*Synopsis*
     #include <stdio.h>
     int getchar(void);
     
     int _getchar_r(void *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'.


File: libc.info,  Node: gets,  Next: iprintf,  Prev: getchar,  Up: Stdio

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

*Synopsis*
     #include <stdio.h>
     
     char *gets(char *BUF);
     
     char *_gets_r(void *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'.


File: libc.info,  Node: iprintf,  Next: mktemp,  Prev: gets,  Up: Stdio

`iprintf'--write formatted output (integer only)
================================================

*Synopsis*
     #include <stdio.h>
     
     int iprintf(const char *FORMAT, ...);
   *Description*
`iprintf' is a restricted version of `printf': it has the same
arguments and behavior, save that it cannot perform any floating-point
formatting: the `f', `g', `G', `e', and `F' type specifiers are not
recognized.

*Returns*
`iprintf' returns the number of bytes in the output string, save that
the concluding `NULL' is not counted.  `iprintf' returns when the end
of the format string is encountered.  If an error occurs, `iprintf'
returns `EOF'.

*Portability*
`iprintf' is not required by ANSI C.

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


File: libc.info,  Node: mktemp,  Next: perror,  Prev: iprintf,  Up: Stdio

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

*Synopsis*
     #include <stdio.h>
     char *mktemp(char *PATH);
     int mkstemp(char *PATH);
     
     char *_mktemp_r(void *REENT, char *PATH);
     int *_mkstemp_r(void *REENT, char *PATH);
   *Description*
`mktemp' and `mkstemp' attempt to generate a file name that is not yet
in use for any existing file.  `mkstemp' creates the file and opens it
for reading and writing; `mktemp' simply generates the file name.

   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 some number of ``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.

   The alternate functions `_mktemp_r' and `_mkstemp_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'.

   `mkstemp' returns 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.

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


File: libc.info,  Node: perror,  Next: putc,  Prev: mktemp,  Up: Stdio

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

*Synopsis*
     #include <stdio.h>
     void perror(char *PREFIX);
     
     void _perror_r(void *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'.


File: libc.info,  Node: putc,  Next: putchar,  Prev: perror,  Up: Stdio

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

*Synopsis*
     #include <stdio.h>
     int putc(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'.

*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'.


File: libc.info,  Node: putchar,  Next: puts,  Prev: putc,  Up: Stdio

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

*Synopsis*
     #include <stdio.h>
     int putchar(int CH);
     
     int _putchar_r(void *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'.


File: libc.info,  Node: puts,  Next: remove,  Prev: putchar,  Up: Stdio

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

*Synopsis*
     #include <stdio.h>
     int puts(const char *S);
     
     int _puts_r(void *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'.

File: libc.info,  Node: remove,  Next: rename,  Prev: puts,  Up: Stdio

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

*Synopsis*
     #include <stdio.h>
     int remove(char *FILENAME);
     
     int _remove_r(void *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'.


File: libc.info,  Node: rename,  Next: rewind,  Prev: remove,  Up: Stdio

`rename'--rename a file
=======================

*Synopsis*
     #include <stdio.h>
     int rename(const char *OLD, const char *NEW);
     
     int _rename_r(void *REENT,
         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.

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

*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'.


File: libc.info,  Node: rewind,  Next: setbuf,  Prev: rename,  Up: Stdio

`rewind'--reinitialize a file or stream
=======================================

*Synopsis*
     #include <stdio.h>
     void rewind(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.


File: libc.info,  Node: setbuf,  Next: setvbuf,  Prev: rewind,  Up: Stdio

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


File: libc.info,  Node: setvbuf,  Next: siprintf,  Prev: setbuf,  Up: Stdio

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


File: libc.info,  Node: siprintf,  Next: printf,  Prev: setvbuf,  Up: Stdio

`siprintf'--write formatted output (integer only)
=================================================

*Synopsis*
     #include <stdio.h>
     
     int siprintf(char *STR, const char *FORMAT [, ARG, ...]);
   *Description*
`siprintf' is a restricted version of `sprintf': it has the same
arguments and behavior, save that it cannot perform any floating-point
formatting: the `f', `g', `G', `e', and `F' type specifiers are not
recognized.

*Returns*
`siprintf' returns the number of bytes in the output string, save that
the concluding `NULL' is not counted.  `siprintf' returns when the end
of the format string is encountered.

*Portability*
`siprintf' is not required by ANSI C.

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


File: libc.info,  Node: printf,  Next: scanf,  Prev: siprintf,  Up: Stdio

`printf', `fprintf', `sprintf'--format output
=============================================

*Synopsis*
     #include <stdio.h>
     
     int printf(const char *FORMAT [, ARG, ...]);
     int fprintf(FILE *FD, const char *FORMAT [, ARG, ...]);
     int sprintf(char *STR, const char *FORMAT [, ARG, ...]);
   *Description*
`printf' accepts a series of arguments, applies to each a format
specifier from `*FORMAT', and writes the formatted data to `stdout',
terminated with a null 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' and `sprintf' are identical to `printf', other than the
destination of the formatted output: `fprintf' sends the output to a
specified file FD, while `sprintf' stores the output in the specified
char array STR.  For `sprintf', the behavior is also undefined if the
output `*STR' overlaps with one of the arguments.  FORMAT is a pointer
to a charater 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:

            %[FLAGS][WIDTH][.PREC][SIZE][TYPE]

   The fields of the conversion specification have the following
meanings:

   * FLAGS

     an optional sequence of characters which control output
     justification, numeric signs, decimal points, trailing zeroes, and
     octal and hex prefixes.  The flag characters are minus (`-'), plus
     (`+'), space ( ), zero (`0'), and sharp (`#').  They can appear in
     any combination.

    `-'
          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)
          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', `e',
          `E', `f', `g', or `G': leading zeroes, 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 next character:

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

         `e, E 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 zeroes
               are removed.

         `g or G'
               same as `e' or `E', but trailing zeroes 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.  Negative field widths are not supported; if you
     attempt to specify a negative field width, it is interpreted as a
     minus (`-') flag followed by a positive field width.

   * PREC

     an optional field; if present, it is introduced with ``.'' (a
     period). This field gives the maximum number of characters to
     print in a conversion; the minimum number of digits of an integer
     to print, for conversions with TYPE `d', `i', `o', `u', `x', and
     `X'; the maximum number of significant digits, for the `g' and `G'
     conversions; or the number of digits to print after the decimal
     point, for `e', `E', and `f' conversions.  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.  Supplying a negative precision is equivalent to
     omitting the precision.  If only a period is specified the
     precision is zero.  If a precision appears with any other
     conversion TYPE than those listed here, the behavior is undefined.

   * SIZE

     `h', `l', and `L' are optional size characters which override the
     default way that `printf' interprets the data type of the
     corresponding argument.  `h' forces the following `d', `i', `o',
     `u', `x' or `X' conversion TYPE to apply to a `short' or `unsigned
     short'. `h' also forces a following `n' TYPE to apply to a pointer
     to a `short'. Similarily, an `l' forces the following `d', `i',
     `o', `u', `x' or `X' conversion TYPE to apply to a `long' or
     `unsigned long'.  `l' also forces a following `n' TYPE to apply to
     a pointer to a `long'. If an `h' or an `l' appears with another
     conversion specifier, the behavior is undefined.  `L' forces a
     following `e', `E', `f', `g' or `G' conversion TYPE to apply to a
     `long double' argument.  If `L' appears with any other conversion
     TYPE, the behavior is undefined.

   * 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

    `s'
          prints characters until precision is reached or a null
          terminator is encountered; takes a string pointer

    `d'
          prints a signed decimal integer; takes an `int' (same as `i')

    `i'
          prints a signed decimal integer; takes an `int' (same as `d')

    `o'
          prints a signed octal integer; takes an `int'

    `u'
          prints an unsigned decimal integer; takes an `int'

    `x'
          prints an unsigned hexadecimal integer (using `abcdef' as
          digits beyond `9'); takes an `int'

    `X'
          prints an unsigned hexadecimal integer (using `ABCDEF' as
          digits beyond `9'); takes an `int'

    `f'
          prints a signed value of the form `[-]9999.9999'; takes a
          floating point number

    `e'
          prints a signed	value of the form
          `[-]9.9999e[+|-]999'; takes a floating point number

    `E'
          prints the same way as `e', but using `E' to introduce the
          exponent; takes a floating point number

    `g'
          prints a signed value in either `f' or `e' form, based on
          given value and precision--trailing zeros and the decimal
          point are printed only if necessary; takes a floating point
          number

    `G'
          prints the same way as `g', but using `E' for the exponent if
          an exponent is needed; takes a floating point number

    `n'
          stores (in the same object) a count of the characters written;
          takes a pointer to `int'

    `p'
          prints a pointer in an implementation-defined format.  This
          implementation treats the pointer as an `unsigned long' (same
          as `Lu').

*Returns*
`sprintf' returns the number of bytes in the output string, save that
the concluding `NULL' is not counted.  `printf' and `fprintf' return
the number of characters transmitted.  If an error occurs, `printf' and
`fprintf' return `EOF'. No error returns occur for `sprintf'.

*Portability*
The  ANSI C standard specifies that implementations must support at
least formatted output of up to 509 characters.

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


File: libc.info,  Node: scanf,  Next: tmpfile,  Prev: printf,  Up: Stdio

`scanf', `fscanf', `sscanf'--scan and format input
==================================================

*Synopsis*
     #include <stdio.h>
     
     int scanf(const char *FORMAT [, ARG, ...]);
     int fscanf(FILE *FD, const char *FORMAT [, ARG, ...]);
     int sscanf(const char *STR, const char *FORMAT
         [, ARG, ...]);
   *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 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', `l', and `L' are optional size characters which override the
     default way that `scanf' interprets the data type of the
     corresponding argument.

          Modifier   Type(s)
             h       d, i, o, u, x     convert input to short,
                                       store in short object
          
             h       D, I, O, U, X     no effect
                     e, f, c, s, n, p
          
             l       d, i, o, u, x     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, n, p
          
             L       d, i, o, u, x     convert to long double,
                                       store in long double
          
             L      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'.


File: libc.info,  Node: tmpfile,  Next: tmpnam,  Prev: scanf,  Up: Stdio

`tmpfile'--create a temporary file
==================================

*Synopsis*
     #include <stdio.h>
     FILE *tmpfile(void);
     
     FILE *_tmpfile_r(void *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'.


File: libc.info,  Node: tmpnam,  Next: vprintf,  Prev: tmpfile,  Up: Stdio

`tmpnam', `tempnam'--name for a temporary file
==============================================

*Synopsis*
     #include <stdio.h>
     char *tmpnam(char *S);
     char *tempnam(char *DIR, char *PFX);
     char *_tmpnam_r(void *REENT, char *S);
     char *_tempnam_r(void *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.


File: libc.info,  Node: vprintf,  Prev: tmpnam,  Up: Stdio

`vprintf', `vfprintf', `vsprintf'--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 _vprintf_r(void *REENT, const char *FMT,
         va_list LIST);
     int _vfprintf_r(void *REENT, FILE *FP, const char *FMT,
         va_list LIST);
     int _vsprintf_r(void *REENT, char *STR, const char *FMT,
         va_list LIST);
   *Description*
`vprintf', `vfprintf', and `vsprintf' are (respectively) variants of
`printf', `fprintf', and `sprintf'.  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:
`vsprintf' returns the number of bytes in the output string, save that
the concluding `NULL' is not counted.  `vprintf' and `vfprintf' return
the number of characters transmitted.  If an error occurs, `vprintf'
and `vfprintf' return `EOF'. No error returns occur for `vsprintf'.

*Portability*
ANSI C requires all three functions.

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


File: libc.info,  Node: Strings,  Next: Signals,  Prev: Stdio,  Up: Top

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

* Menu:

* bcmp::        Compare two memory areas
* bcopy::       Copy memory regions
* bzero::       Initialize memory to zero
* index::       Search for character in string
* memchr::      Find character in memory
* memcmp::      Compare two memory areas
* memcpy::      Copy memory regions
* memmove::     Move possibly overlapping memory
* memset::      Set an area of memory
* rindex::      Reverse search for character in string
* strcat::      Concatenate strings
* strchr::      Search for character in string
* strcmp::      Character string compare
* strcoll::     Locale specific character string compare
* strcpy::      Copy string
* strcspn::     Count chars not in string
* strerror::    Convert error number to string
* strlen::      Character string length
* strncat::     Concatenate strings
* strncmp::     Character string compare
* strncpy::     Counted copy string
* strpbrk::     Find chars in string
* strrchr::     Reverse search for character in string
* strspn::      Find initial match
* strstr::      Find string segment
* strtok::      Get next token from a string
* strxfrm::     Transform string


File: libc.info,  Node: bcmp,  Next: bcopy,  Up: Strings

`bcmp'--compare two memory areas
================================

   *Synopsis*
     #include <string.h>
     int bcmp(const char *S1, const char *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.

   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.


File: libc.info,  Node: bcopy,  Next: bzero,  Prev: bcmp,  Up: Strings

`bcopy'--copy memory regions
============================

*Synopsis*
     #include <string.h>
     void bcopy(const char *IN, char  *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.


File: libc.info,  Node: bzero,  Next: index,  Prev: bcopy,  Up: Strings

`bzero'--initialize memory to zero
==================================

*Synopsis*
     #include <string.h>
     void bzero(char *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.


File: libc.info,  Node: index,  Next: memchr,  Prev: bzero,  Up: Strings

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


File: libc.info,  Node: memchr,  Next: memcmp,  Prev: index,  Up: Strings

`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, `NULL' 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.


File: libc.info,  Node: memcmp,  Next: memcpy,  Prev: memchr,  Up: Strings

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


File: libc.info,  Node: memcpy,  Next: memmove,  Prev: memcmp,  Up: Strings

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


File: libc.info,  Node: memmove,  Next: memset,  Prev: memcpy,  Up: Strings

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


File: libc.info,  Node: memset,  Next: rindex,  Prev: memmove,  Up: Strings

`memset'--set an area of memory
===============================

*Synopsis*
     #include <string.h>
     void *memset(const 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 M.

*Portability*
`memset' is ANSI C.

   `memset' requires no supporting OS subroutines.


File: libc.info,  Node: rindex,  Next: strcat,  Prev: memset,  Up: Strings

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


File: libc.info,  Node: strcat,  Next: strchr,  Prev: rindex,  Up: Strings

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


File: libc.info,  Node: strchr,  Next: strcmp,  Prev: strcat,  Up: Strings

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


File: libc.info,  Node: strcmp,  Next: strcoll,  Prev: strchr,  Up: Strings

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


File: libc.info,  Node: strcoll,  Next: strcpy,  Prev: strcmp,  Up: Strings

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


File: libc.info,  Node: strcpy,  Next: strcspn,  Prev: strcoll,  Up: Strings

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


File: libc.info,  Node: strcspn,  Next: strerror,  Prev: strcpy,  Up: Strings

`strcspn'--count chars 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.


File: libc.info,  Node: strerror,  Next: strlen,  Prev: strcspn,  Up: Strings

`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

`EADV'
     Advertise error

`EAGAIN'
     No more processes

`EBADF'
     Bad file number

`EBADMSG'
     Bad message

`EBUSY'
     Device or resource busy

`ECHILD'
     No children

`ECOMM'
     Communication error

`EDEADLK'
     Deadlock

`EEXIST'
     File exists

`EDOM'
     Math argument

`EFAULT'
     Bad address

`EFBIG'
     File too large

`EIDRM'
     Identifier removed

`EINTR'
     Interrupted system call

`EINVAL'
     Invalid argument

`EIO'
     I/O error

`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

`EMULTIHOP'
     Multihop attempted

`ENAMETOOLONG'
     File or path name too long

`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

`ENOSPC'
     No space left on device

`ENOSR'
     No stream resources

`ENOSTR'
     Not a stream

`ENOSYS'
     Function not implemented

`ENOTBLK'
     Block device required

`ENOTDIR'
     Not a directory

`ENOTEMPTY'
     Directory not empty

`ENOTTY'
     Not a character device

`ENXIO'
     No such device or address

`EPERM'
     Not owner

`EPIPE'
     Broken pipe

`EPROTO'
     Protocol error

`ERANGE'
     Result too large

`EREMOTE'
     Resource is remote

`EROFS'
     Read-only file system

`ESPIPE'
     Illegal seek

`ESRCH'
     No such process

`ESRMNT'
     Srmount error

`ETIME'
     Stream ioctl timeout

`ETXTBSY'
     Text file busy

`EXDEV'
     Cross-device link

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


File: libc.info,  Node: strlen,  Next: strncat,  Prev: strerror,  Up: Strings

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


File: libc.info,  Node: strncat,  Next: strncmp,  Prev: strlen,  Up: Strings

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


File: libc.info,  Node: strncmp,  Next: strncpy,  Prev: strncat,  Up: Strings

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


File: libc.info,  Node: strncpy,  Next: strpbrk,  Prev: strncmp,  Up: Strings

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


File: libc.info,  Node: strpbrk,  Next: strrchr,  Prev: strncpy,  Up: Strings

`strpbrk'--find chars 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.


File: libc.info,  Node: strrchr,  Next: strspn,  Prev: strpbrk,  Up: Strings

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


File: libc.info,  Node: strspn,  Next: strstr,  Prev: strrchr,  Up: Strings

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


File: libc.info,  Node: strstr,  Next: strtok,  Prev: strspn,  Up: Strings

`strstr'--find string segment
=============================

*Synopsis*
     #include <string.h>
     char *strstr(const char *S1, const char *S2);
   *Description*
Locates the first occurence 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,
the S1 is returned.

*Portability*
`strstr' is ANSI C.

   `strstr' requires no supporting OS subroutines.


File: libc.info,  Node: strtok,  Next: strxfrm,  Prev: strstr,  Up: Strings

`strtok'--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)
   *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 NUL 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.

*Returns*
`strtok' returns a pointer to the next token, or `NULL' if no more
tokens can be found.

*Portability*
`strtok' is ANSI C.

   `strtok' requires no supporting OS subroutines.


File: libc.info,  Node: strxfrm,  Prev: strtok,  Up: Strings

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


File: libc.info,  Node: Signals,  Next: Timefns,  Prev: Strings,  Up: Top

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

* Menu:

* raise::   Send a signal
* signal::  Specify handler subroutine for a signal


File: libc.info,  Node: raise,  Next: signal,  Up: Signals

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


File: libc.info,  Node: signal,  Prev: raise,  Up: Signals

`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);
     
     int raise (int SIG);
     
     int _raise_r (void *REENT, int SIG);
   *Description*
`signal, raise' provide a simple signal/raise 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.

   `raise' sends the signal sig to the executing program.  It returns
zero if successful, non-zero if unsuccessful.

   The alternate functions `_signal_r, _raise_r' are the reentrant
versions.  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 `raise', `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.


File: libc.info,  Node: Timefns,  Next: Locale,  Prev: Signals,  Up: Top

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.

`tm_min'
     Minutes.

`tm_hour'
     Hours.

`tm_mday'
     Day.

`tm_mon'
     Month.

`tm_year'
     Year (since 1900).

`tm_wday'
     Day of week: the number of days since Sunday.

`tm_yday'
     Number of days elapsed since last January 1.

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

* Menu:

* asctime::     Format time as string
* clock::       Cumulative processor time
* ctime::       Convert time to local and format as string
* difftime::    Subtract two times
* gmtime::      Convert time to UTC (GMT) traditional representation
* localtime::   Convert time to local representation
* mktime::      Convert time to arithmetic representation
* strftime::    Flexible calendar time formatter
* time::        Get current calendar time (as single number)


File: libc.info,  Node: asctime,  Next: clock,  Up: Timefns

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


File: libc.info,  Node: clock,  Next: ctime,  Prev: asctime,  Up: Timefns

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

*Portability*
ANSI C requires `clock' and `CLOCKS_PER_SEC'.

   Supporting OS subroutine required: `times'.


File: libc.info,  Node: ctime,  Next: difftime,  Prev: clock,  Up: Timefns

`ctime'--convert time to local and format as string
===================================================

*Synopsis*
     #include <time.h>
     char *ctime(time_t CLOCK);
     char *ctime_r(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.


File: libc.info,  Node: difftime,  Next: gmtime,  Prev: ctime,  Up: Timefns

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


File: libc.info,  Node: gmtime,  Next: localtime,  Prev: difftime,  Up: Timefns

`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' assumes the time at CLOCK represents a local time.  `gmtime'
converts it to UTC (Universal Coordinated Time, also known in some
countries as GMT, Greenwich Mean time), then converts the
representation from the arithmetic representation to the traditional
representation defined by `struct tm'.

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


File: libc.info,  Node: localtime,  Next: mktime,  Prev: gmtime,  Up: Timefns

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


File: libc.info,  Node: mktime,  Next: strftime,  Prev: localtime,  Up: Timefns

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


File: libc.info,  Node: strftime,  Next: time,  Prev: mktime,  Up: Timefns

`strftime'--flexible calendar time formatter
============================================

*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 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-character
sequences beginning with ``%'' (use ``%%'' to include a percent sign in
the output).  Each defined conversion specification selects a field of
calendar time data from `*TIMP', and converts it to a string in one of
the following ways:

`%a'
     An abbreviation for the day of the week.

`%A'
     The full name for the day of the week.

`%b'
     An abbreviation for the month name.

`%B'
     The full name of the month.

`%c'
     A string representing the complete date and time, in the form
           Mon Apr 01 13:13:13 1992

`%d'
     The day of the month, formatted with two digits.

`%H'
     The hour (on a 24-hour clock), formatted with two digits.

`%I'
     The hour (on a 12-hour clock), formatted with two digits.

`%j'
     The count of days in the year, formatted with three digits (from
     ``001'' to ``366'').

`%m'
     The month number, formatted with two digits.

`%M'
     The minute, formatted with two digits.

`%p'
     Either ``AM'' or ``PM'' as appropriate.

`%S'
     The second, formatted with two digits.

`%U'
     The week number, formatted with two digits (from ``00'' to ``53'';
     week number 1 is taken as beginning with the first Sunday in a
     year).  See also `%W'.

`%w'
     A single digit representing the day of the week: Sunday is day `0'.

`%W'
     Another version of the week number: like ``%U'', but counting week
     1 as beginning with the first Monday in a year.

`o %x'
     A string representing the complete date, in a format like
           Mon Apr 01 1992

`%X'
     A string representing the full time of day (hours, minutes, and
     seconds), in a format like
           13:13:13

`%y'
     The last two digits of the year.

`%Y'
     The full year, formatted with four digits to include the century.

`%Z'
     Defined by ANSI C as eliciting the time zone if available; it is
     not available in this implementation (which accepts ``%Z'' but
     generates no output for it).

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

   `strftime' requires no supporting OS subroutines.


File: libc.info,  Node: time,  Prev: strftime,  Up: Timefns

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


File: libc.info,  Node: Locale,  Next: Syscalls,  Prev: Timefns,  Up: Top

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.

* Menu:

* setlocale::  Select or query locale


File: libc.info,  Node: setlocale,  Up: Locale

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

   If you use `NULL' as the LOCALE argument, `setlocale' returns a
pointer to the string representing the current locale (always ```C'''
in this implementation).  The acceptable values for CATEGORY are
defined in ``locale.h'' as macros beginning with `"LC_"', but this
implementation does not check the values you pass in the CATEGORY
argument.

   `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*
`setlocale' returns either a pointer to a string naming the locale
currently in effect (always ```C''' for this implementation), or, if
the locale request cannot be honored, `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.

   No supporting OS subroutines are required.


File: libc.info,  Node: Reentrancy,  Next: Library Index,  Prev: Arglists,  Up: Top

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.
Cygnus's 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.

   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       _mkstemp_r       _remove_r
     _fopen_r        _mktemp_r        _rename_r
     _getchar_r      _perror_r        _tempnam_r
     _gets_r         _putchar_r       _tmpnam_r
     _iprintf_r 	_puts_r		 _tmpfile_r
*Signal functions:*
     _raise_r        _signal_r
*Stdlib functions:*
     _dtoa_r         _realloc_r      _strtoul_r
     _free_r         _srand_r        _system_r
     _malloc_r       _strtod_r
     _rand_r         _strtol_r
*String functions:*
     _strtok_r
*System functions:*
     _close_r        _lseek_r        _stat_r
     _fork_r         _open_r         _unlink_r
     _fstat_r        _read_r         _wait_r
     _link_r         _sbrk_r         _write_r
*Time function:*
     _asctime_r


File: libc.info,  Node: Misc,  Next: Arglists,  Prev: Syscalls,  Up: Top

Miscellaneous Macros and Functions
**********************************

   This chapter describes miscellaneous routines not covered elsewhere.

* Menu:

* unctrl::   Return printable representation of a character


File: libc.info,  Node: unctrl,  Up: Misc

`unctrl'--translate characters to upper case
============================================

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


File: libc.info,  Node: Syscalls,  Next: Misc,  Prev: Locale,  Up: Top

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

* Menu:

* Stubs::		Definitions for OS interface
* Reentrant Syscalls::	Reentrant covers for OS subroutines


File: libc.info,  Node: Stubs,  Next: Reentrant Syscalls,  Up: Syscalls

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 Cygnus C library provides a *macro* definition
for `errno' in the header file `errno.h', as part of its support for
reentrant routines (*note Reentrancy: 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() {
            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() {
            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;
          }

`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;
            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 a character 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 `writechar' 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++) {
                  writechar(*ptr++);
              }
              return len;
          }


File: libc.info,  Node: Reentrant Syscalls,  Prev: Stubs,  Up: Syscalls

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 (*note
Reentrancy: 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);

`_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);

`_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);

`_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);


File: libc.info,  Node: Arglists,  Next: Reentrancy,  Prev: Misc,  Up: Top

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

* Menu:

* Stdarg::
* Varargs::


File: libc.info,  Node: Stdarg,  Next: Varargs,  Up: Arglists

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

* Menu:

* va_start::
* va_arg::
* va_end::


File: libc.info,  Node: va_start,  Next: va_arg,  Up: Stdarg

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


File: libc.info,  Node: va_arg,  Next: va_end,  Prev: va_start,  Up: Stdarg

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


File: libc.info,  Node: va_end,  Prev: va_arg,  Up: Stdarg

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


File: libc.info,  Node: Varargs,  Prev: Stdarg,  Up: Arglists

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.

* Menu:

* va_alist::
* va_start-trad::
* va_arg-trad::
* va_end-trad::


File: libc.info,  Node: va_alist,  Next: va_start-trad,  Up: Varargs

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.


File: libc.info,  Node: va_start-trad,  Next: va_arg-trad,  Prev: va_alist,  Up: Varargs

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.


File: libc.info,  Node: va_arg-trad,  Next: va_end-trad,  Prev: va_start-trad,  Up: Varargs

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


File: libc.info,  Node: va_end-trad,  Prev: va_arg-trad,  Up: Varargs

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


File: libc.info,  Node: Library Index,  Prev: Reentrancy,  Up: Top

Index
*****

* Menu:

* _asctime_r:                            asctime.
* _calloc_r:                             calloc.
* _close_r:                              Reentrant Syscalls.
* _exit:                                 Stubs.
* _fdopen_r:                             fdopen.
* _fopen_r:                              fopen.
* _fork_r:                               Reentrant Syscalls.
* _free_r:                               malloc.
* _fstat_r:                              Reentrant Syscalls.
* _getchar_r:                            getchar.
* _gets_r:                               gets.
* _impure_ptr:                           Reentrancy.
* _link_r:                               Reentrant Syscalls.
* _localeconv_r:                         setlocale.
* _lseek_r:                              Reentrant Syscalls.
* _malloc_r:                             malloc.
* _mkstemp_r:                            mktemp.
* _mktemp_r:                             mktemp.
* _open_r:                               Reentrant Syscalls.
* _perror_r:                             perror.
* _putchar_r:                            putchar.
* _puts_r:                               puts.
* _raise_r <1>:                          signal.
* _raise_r:                              raise.
* _read_r:                               Reentrant Syscalls.
* _realloc_r:                            malloc.
* _reent:                                Reentrancy.
* _rename_r:                             rename.
* _sbrk_r:                               Reentrant Syscalls.
* _setlocale_r:                          setlocale.
* _signal_r:                             signal.
* _stat_r:                               Reentrant Syscalls.
* _strtod_r:                             strtod.
* _strtol_r:                             strtol.
* _strtoul_r:                            strtoul.
* _system_r:                             system.
* _tempnam_r:                            tmpnam.
* _tmpfile_r:                            tmpfile.
* _tmpnam_r:                             tmpnam.
* _tolower:                              tolower.
* _toupper:                              toupper.
* _unlink_r:                             Reentrant Syscalls.
* _wait_r:                               Reentrant Syscalls.
* _write_r:                              Reentrant Syscalls.
* abort:                                 abort.
* abs:                                   abs.
* asctime:                               asctime.
* assert:                                assert.
* atexit:                                atexit.
* atof:                                  atof.
* atoff:                                 atof.
* atoi:                                  atoi.
* atol:                                  atoi.
* bcmp:                                  bcmp.
* bsearch:                               bsearch.
* bzero:                                 bzero.
* calloc:                                calloc.
* clearerr:                              clearerr.
* clock:                                 clock.
* close:                                 Stubs.
* ctime:                                 ctime.
* difftime:                              difftime.
* div:                                   div.
* ecvt:                                  ecvt.
* ecvtbuf:                               ecvtbuf.
* environ <1>:                           Stubs.
* environ:                               getenv.
* errno global vs macro:                 Stubs.
* execve:                                Stubs.
* exit:                                  exit.
* extra argument, reentrant fns:         Reentrancy.
* fclose:                                fclose.
* fcvt:                                  ecvt.
* fcvtbuf:                               ecvtbuf.
* fdopen:                                fdopen.
* feof:                                  feof.
* ferror:                                ferror.
* fflush:                                fflush.
* fgetc:                                 fgetc.
* fgetpos:                               fgetpos.
* fgets:                                 fgets.
* fiprintf:                              fiprintf.
* fopen:                                 fopen.
* fork:                                  Stubs.
* fprintf:                               printf.
* fputc:                                 fputc.
* fputs:                                 fputs.
* fread:                                 fread.
* free:                                  malloc.
* freopen:                               freopen.
* fscanf:                                scanf.
* fseek:                                 fseek.
* fsetpos:                               fsetpos.
* fstat:                                 Stubs.
* ftell:                                 ftell.
* fwrite:                                fwrite.
* gcvt:                                  gvcvt.
* gcvtf:                                 gvcvt.
* getc:                                  getc.
* getchar:                               getchar.
* getenv:                                getenv.
* getpid:                                Stubs.
* gets:                                  gets.
* global reentrancy structure:           Reentrancy.
* gmtime:                                gmtime.
* index:                                 index.
* iprintf:                               iprintf.
* isalnum:                               isalnum.
* isalpha:                               isalpha.
* isascii:                               isascii.
* isatty:                                Stubs.
* iscntrl:                               iscntrl.
* isdigit:                               isdigit.
* isgraph:                               isprint.
* islower:                               islower.
* isprint:                               isprint.
* ispunct:                               ispunct.
* isspace:                               isspace.
* isupper:                               isupper.
* isxdigit:                              isxdigit.
* kill:                                  Stubs.
* labs:                                  labs.
* ldiv:                                  ldiv.
* link:                                  Stubs.
* linking the C library:                 Syscalls.
* list of reentrant functions:           Reentrancy.
* localeconv:                            setlocale.
* localtime:                             localtime.
* lseek:                                 Stubs.
* malloc:                                malloc.
* mbtowc:                                mbtowc.
* memchr:                                memchr.
* memcmp:                                memcmp.
* memmove:                               memmove.
* memset:                                memset.
* mkstemp:                               mktemp.
* mktemp:                                mktemp.
* mktime:                                mktime.
* OS interface subroutines:              Stubs.
* perror:                                perror.
* printf:                                printf.
* putc:                                  putc.
* putchar:                               putchar.
* puts:                                  puts.
* qsort:                                 qsort.
* raise <1>:                             raise.
* raise:                                 signal.
* rand:                                  rand.
* rand_r:                                rand.
* read:                                  Stubs.
* realloc:                               malloc.
* reent.h:                               Reentrancy.
* reentrancy:                            Reentrancy.
* reentrancy structure:                  Reentrancy.
* reentrant function list:               Reentrancy.
* remove:                                remove.
* rename:                                rename.
* rewind:                                rewind.
* rindex:                                rindex.
* sbrk:                                  Stubs.
* scanf:                                 scanf.
* setbuf:                                setbuf.
* setlocale:                             setlocale.
* setvbuf:                               setvbuf.
* signal:                                signal.
* siprintf:                              siprintf.
* sprintf:                               printf.
* srand:                                 rand.
* sscanf:                                scanf.
* stat:                                  Stubs.
* strcat:                                strcat.
* strchr:                                strchr.
* strcmp:                                strcmp.
* strcoll:                               strcoll.
* strcpy:                                strcpy.
* strcspn:                               strcspn.
* strerror:                              strerror.
* strftime:                              strftime.
* strlen:                                strlen.
* strncat:                               strncat.
* strncmp:                               strncmp.
* strncpy:                               strncpy.
* strpbrk:                               strpbrk.
* strrchr:                               strrchr.
* strspn:                                strspn.
* strstr:                                strstr.
* strtod:                                strtod.
* strtodf:                               strtod.
* strtok:                                strtok.
* strtok_r:                              strtok.
* strtol:                                strtol.
* strtoul:                               strtoul.
* strxfrm:                               strxfrm.
* stubs:                                 Stubs.
* subroutines for OS interface:          Stubs.
* system:                                system.
* tempnam:                               tmpnam.
* time:                                  time.
* times:                                 Stubs.
* tmpfile:                               tmpfile.
* tmpnam:                                tmpnam.
* toascii:                               toascii.
* tolower:                               tolower.
* toupper:                               toupper.
* unctrl:                                unctrl.
* unctrllen:                             unctrl.
* unlink:                                Stubs.
* va_alist:                              va_alist.
* va_arg <1>:                            va_arg-trad.
* va_arg:                                va_arg.
* va_dcl:                                va_alist.
* va_end <1>:                            va_end-trad.
* va_end:                                va_end.
* va_start <1>:                          va_start.
* va_start:                              va_start-trad.
* vfprintf:                              vprintf.
* vprintf:                               vprintf.
* vsprintf:                              vprintf.
* wait:                                  Stubs.
* wctomb:                                wctomb.
* write:                                 Stubs.



Tag Table:
Node: Top1990
Node: Stdlib2265
Node: abort3724
Node: abs4729
Node: assert5342
Node: atexit6475
Node: atof7912
Node: atoi9727
Node: bsearch10402
Node: calloc11630
Node: div12607
Node: ecvt13347
Node: gvcvt15268
Node: ecvtbuf16290
Node: exit18008
Node: getenv19070
Node: labs19868
Node: ldiv20484
Node: malloc21248
Node: mbtowc23861
Node: qsort24792
Node: rand25989
Node: strtod27695
Node: strtol29696
Node: strtoul32538
Node: system35411
Node: wctomb36618
Node: Ctype37449
Node: isalnum38542
Node: isalpha39291
Node: isascii40052
Node: iscntrl40724
Node: isdigit41510
Node: islower42235
Node: isprint43009
Node: ispunct43961
Node: isspace44758
Node: isupper45569
Node: isxdigit46321
Node: toascii47093
Node: tolower47704
Node: toupper48858
Node: Stdio49995
Node: clearerr52732
Node: fclose53500
Node: feof54116
Node: ferror54619
Node: fflush55322
Node: fgetc56073
Node: fgetpos56999
Node: fgets58455
Node: fiprintf59418
Node: fopen60314
Node: fdopen63352
Node: fputc63991
Node: fputs65015
Node: fread65711
Node: freopen66556
Node: fseek67486
Node: fsetpos68994
Node: ftell70129
Node: fwrite71512
Node: getc72471
Node: getchar73700
Node: gets74857
Node: iprintf76191
Node: mktemp77069
Node: perror78819
Node: putc79874
Node: putchar81191
Node: puts82139
Node: remove82991
Node: rename84142
Node: rewind85268
Node: setbuf85832
Node: setvbuf87356
Node: siprintf89388
Node: printf90251
Node: scanf98909
Node: tmpfile108942
Node: tmpnam110084
Node: vprintf112471
Node: Strings113952
Node: bcmp115365
Node: bcopy116027
Node: bzero116495
Node: index117054
Node: memchr117667
Node: memcmp118379
Node: memcpy119045
Node: memmove119621
Node: memset120245
Node: rindex120775
Node: strcat121410
Node: strchr122016
Node: strcmp122615
Node: strcoll123244
Node: strcpy124048
Node: strcspn124540
Node: strerror125135
Node: strlen128832
Node: strncat129347
Node: strncmp130223
Node: strncpy130918
Node: strpbrk131665
Node: strrchr132267
Node: strspn132888
Node: strstr133483
Node: strtok134151
Node: strxfrm135520
Node: Signals136735
Node: raise138974
Node: signal140003
Node: Timefns142435
Node: asctime144170
Node: clock144833
Node: ctime145547
Node: difftime146180
Node: gmtime146719
Node: localtime147723
Node: mktime148657
Node: strftime149449
Node: time152726
Node: Locale153387
Node: setlocale157787
Node: Reentrancy159878
Node: Misc162973
Node: unctrl163263
Node: Syscalls163948
Node: Stubs164752
Node: Reentrant Syscalls171272
Node: Arglists174076
Node: Stdarg174592
Node: va_start175248
Node: va_arg176004
Node: va_end177187
Node: Varargs177595
Node: va_alist178351
Node: va_start-trad179021
Node: va_arg-trad179644
Node: va_end-trad180305
Node: Library Index180799

End Tag Table
